ESP32

ESP32
ESP-IDF Programming Guide
Release v5.0-dev-401-g451ce8a
Espressif Systems
Nov 19, 2021
Table of contents
Table of contents i
1 Get Started 3
1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 What You Need . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3 Development Board Overviews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3.1 ESP32-DevKitC V4 Getting Started Guide . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3.2 ESP-WROVER-KIT V4.1 Getting Started Guide . . . . . . . . . . . . . . . . . . . . . 11
1.3.3 ESP32-PICO-KIT V4 / V4.1 Getting Started Guide . . . . . . . . . . . . . . . . . . . . 34
1.3.4 ESP32-Ethernet-Kit V1.2 Getting Started Guide . . . . . . . . . . . . . . . . . . . . . . 44
1.3.5 ESP32-DevKitS(-R) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
1.3.6 ESP32-PICO-KIT-1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
1.3.7 ESP32-PICO-DevKitM-2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
1.3.8 ESP32-DevKitM-1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
1.4 Installation Step by Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
1.4.1 Setting up Development Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
1.4.2 Creating Your First Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
1.5 Step 1. Install prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
1.5.1 Standard Setup of Toolchain for Windows . . . . . . . . . . . . . . . . . . . . . . . . . 94
1.5.2 Standard Setup of Toolchain for Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
1.5.3 Standard Setup of Toolchain for Mac OS . . . . . . . . . . . . . . . . . . . . . . . . . . 100
1.6 Step 2. Get ESP-IDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
1.6.1 Linux and macOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
1.6.2 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
1.7 Step 3. Set up the tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
1.7.1 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
1.7.2 Linux and macOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
1.7.3 Alternative File Downloads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
1.7.4 Customizing the tools installation path . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
1.8 Step 4. Set up the environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
1.8.1 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
1.8.2 Linux and macOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
1.9 Step 5. Start a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
1.9.1 Linux and macOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
1.9.2 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
1.10 Step 6. Connect Your Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
1.11 Step 7. Configure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
1.11.1 Linux and macOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
1.11.2 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
1.12 Step 8. Build the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
1.13 Step 9. Flash onto the Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
1.13.1 Encountered Issues While Flashing? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
1.13.2 Normal Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
1.14 Step 10. Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
1.15 Updating ESP-IDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
1.16 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
i
1.16.1 Establish Serial Connection with ESP32 . . . . . . . . . . . . . . . . . . . . . . . . . . 109
1.16.2 Build and Flash with Eclipse IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
1.16.3 Getting Started with VS Code IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
1.16.4 IDF Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
1.16.5 Customized Setup of Toolchain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
2 API Reference 127

2.1 Bluetooth API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
2.1.1 Controller && VHCI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
2.1.2 BT COMMON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
2.1.3 BT LE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
2.1.4 CLASSIC BT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
2.1.5 NimBLE-based host APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
2.1.6 ESP-BLE-MESH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
2.2 Networking APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
2.2.1 Wi-Fi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
2.2.2 Ethernet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603
2.2.3 Thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630
2.2.4 IP Network Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635
2.2.5 Application Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
2.3 Peripherals API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
2.3.1 Analog to Digital Converter (ADC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
2.3.2 Digital To Analog Converter (DAC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
2.3.3 General Purpose Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674
2.3.4 GPIO & RTC GPIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685
2.3.5 Inter-Integrated Circuit (I2C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703
2.3.6 Inter-IC Sound (I2S) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719
2.3.7 LCD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732
2.3.8 LED Control (LEDC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
2.3.9 Motor Control Pulse Width Modulator (MCPWM) . . . . . . . . . . . . . . . . . . . . . 755
2.3.10 Pulse Counter (PCNT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
2.3.11 Remote Control (RMT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788
2.3.12 SD Pull-up Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806
2.3.13 SDMMC Host Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810
2.3.14 SD SPI Host Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814
2.3.15 SDIO Card Slave Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 818
2.3.16 Sigma-delta Modulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827
2.3.17 SPI Master Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 830
2.3.18 SPI Slave Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852
2.3.19 ESP32-WROOM-32SE (Secure Element) . . . . . . . . . . . . . . . . . . . . . . . . . 859
2.3.20 Touch Sensor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 859
2.3.21 Two-Wire Automotive Interface (TWAI) . . . . . . . . . . . . . . . . . . . . . . . . . . 873
2.3.22 Universal Asynchronous Receiver/Transmitter (UART) . . . . . . . . . . . . . . . . . . 888
2.4 Application Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 911
2.4.1 ASIO port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 911
2.4.2 ESP-MQTT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912
2.4.3 ESP-TLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923
2.4.4 OpenSSL-APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 933
2.4.5 ESP HTTP Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961
2.4.6 HTTP Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975
2.4.7 HTTPS server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997
2.4.8 ICMP Echo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999
2.4.9 ESP Local Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004
2.4.10 mDNS Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012
2.4.11 ESP-Modbus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1025
2.4.12 ESP WebSocket Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1047
2.4.13 ESP Serial Slave Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1054
2.4.14 ESP x509 Certificate Bundle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1069
ii
2.4.15 IP Network Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1071
2.5 Provisioning API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1071
2.5.1 Protocol Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1071
2.5.2 Unified Provisioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1081
2.5.3 Wi-Fi Provisioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1085
2.6 Storage API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1102
2.6.1 FAT Filesystem Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1102
2.6.2 Manufacturing Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1107
2.6.3 Non-volatile storage library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1113
2.6.4 NVS Partition Generator Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1132
2.6.5 SD/SDIO/MMC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1139
2.6.6 SPI Flash API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1148
2.6.7 SPIFFS Filesystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1173
2.6.8 Virtual filesystem component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1176
2.6.9 Wear Levelling API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1189
2.7 System API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1193
2.7.1 App Image Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1193
2.7.2 Application Level Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1198
2.7.3 Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1203
2.7.4 eFuse Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1211
2.7.5 Error Codes and Helper Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1226
2.7.6 ESP HTTPS OTA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1228
2.7.7 POSIX Threads Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1232
2.7.8 Event Loop Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1236
2.7.9 FreeRTOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1252
2.7.10 FreeRTOS Additions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1355
2.7.11 Heap Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1371
2.7.12 Heap Memory Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1382
2.7.13 High Resolution Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1393
2.7.14 The himem allocation API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1399
2.7.15 Inter-Processor Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1401
2.7.16 Call function with external stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1405
2.7.17 Interrupt allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1407
2.7.18 Logging library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1412
2.7.19 Miscellaneous System APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1418
2.7.20 Over The Air Updates (OTA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1423
2.7.21 Performance Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1434
2.7.22 Power Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1436
2.7.23 Random Number Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1442
2.7.24 Sleep Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1443
2.7.25 Watchdogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1453
2.7.26 System Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1456
2.7.27 Internal and Unstable APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1460
2.8 API Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1461
2.8.1 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1461
2.8.2 Configuration structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1461
2.8.3 Private APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1462
2.8.4 Components in example projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1462
2.8.5 API Stability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1462
2.9 Project Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1463
2.9.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1463
2.9.2 Project Configuration Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1464
2.9.3 Using sdkconfig.defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1464
2.9.4 Kconfig Formatting Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1464
2.9.5 Backward Compatibility of Kconfig Options . . . . . . . . . . . . . . . . . . . . . . . . 1464
2.9.6 Configuration Options Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1465
2.10 Error Codes Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1716
iii
3 ESP32 Hardware Reference 1723
3.1 Chip Series Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1723
3.1.1 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1725
4 API Guides 1727

4.1 Application Level Tracing library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1727
4.1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1727
4.1.2 Modes of Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1727
4.1.3 Configuration Options and Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . 1728
4.1.4 How to use this library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1729
4.2 Application Startup Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1737
4.2.1 First stage bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1737
4.2.2 Second stage bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1738
4.2.3 Application startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1738
4.3 BluFi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1740
4.3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1740
4.3.2 The BluFi Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1740
4.3.3 The Flow Chart of BluFi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1741
4.3.4 The Frame Formats Defined in BluFi . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1741
4.3.5 The Security Implementation of ESP32 . . . . . . . . . . . . . . . . . . . . . . . . . . . 1747
4.3.6 GATT Related Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1748
4.4 Bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1748
4.4.1 Bootloader compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1749
4.4.2 Log Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1749
4.4.3 Factory reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1750
4.4.4 Boot from Test Firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1750
4.4.5 Rollback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1751
4.4.6 Watchdog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1751
4.4.7 Bootloader Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1751
4.4.8 Fast boot from Deep Sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1751
4.4.9 Custom bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1751
4.5 Build System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1752
4.5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1752
4.5.2 Using the Build System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1753
4.5.3 Example Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1756
4.5.4 Project CMakeLists File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1757
4.5.5 Component CMakeLists Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1758
4.5.6 Component Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1761
4.5.7 Preprocessor Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1761
4.5.8 Component Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1761
4.5.9 Overriding Parts of the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1765
4.5.10 Configuration-Only Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1765
4.5.11 Debugging CMake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1766
4.5.12 Example Component CMakeLists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1766
4.5.13 Custom sdkconfig defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1770
4.5.14 Flash arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1770
4.5.15 Building the Bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1771
4.5.16 Selecting the Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1771
4.5.17 Writing Pure CMake Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1772
4.5.18 Using Third-Party CMake Projects with Components . . . . . . . . . . . . . . . . . . . 1772
4.5.19 Using Prebuilt Libraries with Components . . . . . . . . . . . . . . . . . . . . . . . . . 1773
4.5.20 Using ESP-IDF in Custom CMake Projects . . . . . . . . . . . . . . . . . . . . . . . . . 1773
4.5.21 ESP-IDF CMake Build System API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1774
4.5.22 File Globbing & Incremental Builds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1778
4.5.23 Build System Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1778
4.5.24 Build System Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1779
4.5.25 Migrating from ESP-IDF GNU Make System . . . . . . . . . . . . . . . . . . . . . . . 1780
4.6 Deep Sleep Wake Stubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1782
iv
4.6.1 Rules for Wake Stubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1782
4.6.2 Implementing A Stub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1782
4.6.3 Loading Code Into RTC Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1782
4.6.4 Loading Data Into RTC Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1783
4.7 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1783
4.7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1783
4.7.2 Error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1784
4.7.3 Converting error codes to error messages . . . . . . . . . . . . . . . . . . . . . . . . . . 1784
4.7.4 ESP_ERROR_CHECK macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1784
4.7.5 ESP_ERROR_CHECK_WITHOUT_ABORT macro . . . . . . . . . . . . . . . . . . . . . 1785
4.7.6 ESP_RETURN_ON_ERROR macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1785
4.7.7 ESP_GOTO_ON_ERROR macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1785
4.7.8 ESP_RETURN_ON_FALSE macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1785
4.7.9 ESP_GOTO_ON_FALSE macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1785
4.7.10 CHECK MACROS Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1785
4.7.11 Error handling patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1786
4.7.12 C++ Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1787
4.8 ESP-BLE-MESH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1787
4.8.1 Getting Started with ESP-BLE-MESH . . . . . . . . . . . . . . . . . . . . . . . . . . . 1787
4.8.2 ESP-BLE-MESH Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1793
4.8.3 ESP-BLE-MESH Demo Videos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1795
4.8.4 ESP-BLE-MESH FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1795
4.9 ESP-WIFI-MESH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1824
4.9.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1824
4.9.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1824
4.9.3 ESP-WIFI-MESH Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1825
4.9.4 Building a Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1831
4.9.5 Managing a Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1836
4.9.6 Data Transmission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1839
4.9.7 Channel Switching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1841
4.9.8 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1844
4.9.9 Further Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1845
4.10 Core Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1845
4.10.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1845
4.10.2 Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1845
4.10.3 Save core dump to flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1846
4.10.4 Print core dump to UART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1846
4.10.5 ROM Functions in Backtraces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1847
4.10.6 Dumping variables on demand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1847
4.10.7 Running espcoredump.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1847
4.11 Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1848
4.11.1 Wi-Fi, Ethernet, and IP Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1848
4.11.2 Mesh Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1850
4.11.3 Bluetooth Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1850
4.12 Support for External RAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1850
4.12.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1850
4.12.2 Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1850
4.12.3 Configuring External RAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1851
4.12.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1852
4.12.5 Failure to initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1853
4.12.6 Chip revisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1853
4.13 Fatal Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1853
4.13.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1853
4.13.2 Panic Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1854
4.13.3 Register Dump and Backtrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1854
4.13.4 GDB Stub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1856
4.13.5 Guru Meditation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1857
v
4.13.6 Other Fatal Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1859
4.14 Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1861
4.14.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1861
4.14.2 Relevant eFuses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1862
4.14.3 Flash Encryption Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1862
4.14.4 Flash Encryption Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1863
4.14.5 Possible Failures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1869
4.14.6 ESP32 Flash Encryption Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1870
4.14.7 Reading and Writing Data in Encrypted Flash . . . . . . . . . . . . . . . . . . . . . . . 1870
4.14.8 Updating Encrypted Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1871
4.14.9 Disabling Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1872
4.14.10 Key Points About Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1872
4.14.11 Limitations of Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1873
4.14.12 Flash Encryption and Secure Boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1873
4.14.13 Advanced Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1873
4.14.14 Technical Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1875
4.15 ESP-IDF FreeRTOS SMP Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1876
4.15.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1876
4.15.2 Tasks and Task Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1877
4.15.3 Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1877
4.15.4 Critical Sections & Disabling Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . 1879
4.15.5 Floating Point Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1880
4.15.6 Task Deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1880
4.15.7 Thread Local Storage Pointers & Deletion Callbacks . . . . . . . . . . . . . . . . . . . . 1880
4.15.8 Configuring ESP-IDF FreeRTOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1881
4.16 Hardware Abstraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1881
4.16.1 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1882
4.16.2 LL (Low Level) Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1882
4.16.3 HAL (Hardware Abstraction Layer) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1883
4.17 High-Level Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1884
4.17.1 Interrupt Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1884
4.17.2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1885
4.18 JTAG Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1885
4.18.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1886
4.18.2 How it Works? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1886
4.18.3 Selecting JTAG Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1887
4.18.4 Setup of OpenOCD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1887
4.18.5 Configuring ESP32 Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1888
4.18.6 Launching Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1893
4.18.7 Debugging Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1893
4.18.8 Building OpenOCD from Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1893
4.18.9 Tips and Quirks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1897
4.19 Linker Script Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1928
4.19.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1928
4.19.2 Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1928
4.19.3 Linker Script Generation Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1931
4.20 Memory Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1938
4.20.1 DRAM (Data RAM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1938
4.20.2 IRAM (Instruction RAM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1938
4.20.3 IROM (code executed from Flash) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1939
4.20.4 RTC fast memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1939
4.20.5 DROM (data stored in Flash) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1940
4.20.6 RTC slow memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1940
4.20.7 DMA Capable Requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1940
4.20.8 DMA Buffer in the stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1941
4.21 lwIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1941
4.21.1 Supported APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1941
vi
4.21.2 BSD Sockets API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1941
4.21.3 Netconn API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1945
4.21.4 lwIP FreeRTOS Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1945
4.21.5 IPv6 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1946
4.21.6 esp-lwip custom modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1946
4.21.7 Performance Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1947
4.22 OpenThread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1949
4.22.1 Mode of the OpenThread stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1949
4.22.2 How To Write an OpenThread Application . . . . . . . . . . . . . . . . . . . . . . . . . 1950
4.22.3 The OpenThread border router . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1950
4.23 Partition Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1951
4.23.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1951
4.23.2 Built-in Partition Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1951
4.23.3 Creating Custom Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1951
4.23.4 Generating Binary Partition Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1954
4.23.5 Partition Size Checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1954
4.23.6 Flashing the partition table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1954
4.23.7 Partition Tool (parttool.py) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1955
4.24 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1956
4.24.1 How to Optimize Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1956
4.24.2 Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1956
4.25 RF calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1973
4.25.1 Partial calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1973
4.25.2 Full calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1973
4.25.3 No calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1974
4.25.4 PHY initialization data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1974
4.26 Secure Boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1974
4.26.1 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1975
4.26.2 Secure Boot Process Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1975
4.26.3 Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1975
4.26.4 Bootloader Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1976
4.26.5 How To Enable Secure Boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1976
4.26.6 Re-Flashable Software Bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1977
4.26.7 Generating Secure Boot Signing Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1977
4.26.8 Remote Signing of Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1978
4.26.9 Secure Boot Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1978
4.26.11 Secure Boot & Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1980
4.26.12 Signed App Verification Without Hardware Secure Boot . . . . . . . . . . . . . . . . . . 1980
4.27 Secure Boot V2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1980
4.27.1 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1981
4.27.2 Advantages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1981
4.27.3 Secure Boot V2 Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1981
4.27.4 Signature Block Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1982
4.27.5 Verifying a Signature Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1982
4.27.6 Verifying an Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1982
4.27.7 Bootloader Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1983
4.27.8 eFuse usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1983
4.27.9 How To Enable Secure Boot V2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1983
4.27.10 Restrictions after Secure Boot is enabled . . . . . . . . . . . . . . . . . . . . . . . . . . 1984
4.27.11 Generating Secure Boot Signing Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1984
4.27.12 Remote Signing of Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1984
4.27.13 Secure Boot Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1985
4.27.15 Secure Boot & Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1985
4.27.16 Signed App Verification Without Hardware Secure Boot . . . . . . . . . . . . . . . . . . 1985
vii
4.28 Thread Local Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1986
4.28.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1986
4.28.2 FreeRTOS Native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1986
4.28.3 Pthread API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1987
4.28.4 C11 Standard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1987
4.29 Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1987
4.29.1 Downloadable Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1987
4.29.2 IDF Docker Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1995
4.29.3 IDF Windows Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1997
4.29.4 IDF Component Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1998
4.29.5 IDF Clang Tidy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1999
4.30 ULP Coprocessor programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2000
4.30.1 ESP32 ULP coprocessor instruction set . . . . . . . . . . . . . . . . . . . . . . . . . . . 2000
4.30.2 Programming ULP coprocessor using C macros (legacy) . . . . . . . . . . . . . . . . . . 2013
4.30.3 Installing the Toolchain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2018
4.30.4 Compiling the ULP Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2018
4.30.5 Accessing the ULP Program Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 2019
4.30.6 Starting the ULP Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2019
4.30.7 ESP32 ULP program flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2021
4.31 Unit Testing in ESP32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2021
4.31.1 Normal Test Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2022
4.31.2 Multi-device Test Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2022
4.31.3 Multi-stage Test Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2023
4.31.4 Tests For Different Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2024
4.31.5 Building Unit Test App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2024
4.31.6 Running Unit Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2025
4.31.7 Timing Code with Cache Compensated Timer . . . . . . . . . . . . . . . . . . . . . . . 2026
4.31.8 Mocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2027
4.32 Unit Testing on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2028
4.32.1 Embedded Software Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2029
4.32.2 IDF Unit Tests on Linux Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2029
4.33 Wi-Fi Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2030
4.33.1 ESP32 Wi-Fi Feature List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2030
4.33.2 How To Write a Wi-Fi Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2030
4.33.3 ESP32 Wi-Fi API Error Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2031
4.33.4 ESP32 Wi-Fi API Parameter Initialization . . . . . . . . . . . . . . . . . . . . . . . . . 2031
4.33.5 ESP32 Wi-Fi Programming Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2031
4.33.6 ESP32 Wi-Fi Event Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2032
4.33.7 ESP32 Wi-Fi Station General Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . 2035
4.33.8 ESP32 Wi-Fi AP General Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2037
4.33.9 ESP32 Wi-Fi Scan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2039
4.33.10 ESP32 Wi-Fi Station Connecting Scenario . . . . . . . . . . . . . . . . . . . . . . . . . 2045
4.33.11 ESP32 Wi-Fi Station Connecting When Multiple APs Are Found . . . . . . . . . . . . . 2049
4.33.12 Wi-Fi Reconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2049
4.33.13 Wi-Fi Beacon Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2049
4.33.14 ESP32 Wi-Fi Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2049
4.33.15 Wi-Fi Easy Connect™ (DPP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2054
4.33.16 Wireless Network Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2055
4.33.17 Radio Resource Measurement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2055
4.33.18 ESP32 Wi-Fi Power-saving Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2055
4.33.19 ESP32 Wi-Fi Throughput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2056
4.33.20 Wi-Fi 80211 Packet Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2056
4.33.21 Wi-Fi Sniffer Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2058
4.33.22 Wi-Fi Multiple Antennas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2059
4.33.23 Wi-Fi Channel State Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2060
4.33.24 Wi-Fi Channel State Information Configure . . . . . . . . . . . . . . . . . . . . . . . . . 2061
4.33.25 Wi-Fi HT20/40 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2062
4.33.26 Wi-Fi QoS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2062
viii
4.33.27 Wi-Fi AMSDU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2063
4.33.28 Wi-Fi Fragment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2063
4.33.29 WPS Enrollee . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2063
4.33.30 Wi-Fi Buffer Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2063
4.33.31 How to improve Wi-Fi performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2064
4.33.32 Wi-Fi Menuconfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2067
4.33.33 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2070
4.34 Wi-Fi Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2074
4.34.1 ESP32 Wi-Fi Security Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2076
4.34.2 Protected Management Frames (PMF) . . . . . . . . . . . . . . . . . . . . . . . . . . . 2076
4.34.3 WPA3-Personal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2077
5 ESP-IDF 5.0 Migration Guides 2079

5.1 Migrate Windows Environment to ESP-IDF 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . 2079
5.2 Migrate Peripherals to ESP-IDF 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2079
5.2.1 Peripheral Clock Gating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2079
5.3 Migrate Build System to ESP-IDF 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2079
5.4 Migrate System to ESP-IDF 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2079
5.4.1 Inter-Processor Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2079
5.5 Migrate Ethernet Drivers to ESP-IDF 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2079
5.5.1 esp_eth_ioctl() API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2080
6 Libraries and Frameworks 2081

6.1 Cloud Frameworks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2081
6.1.1 ESP RainMaker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2081
6.1.2 AWS IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2081
6.1.3 Azure IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2081
6.1.4 Google IoT Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2081
6.1.5 Aliyun IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2081
6.1.6 Joylink IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2081
6.1.7 Tencent IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2082
6.1.8 Tencentyun IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2082
6.1.9 Baidu IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2082
6.2 Espressif s Frameworks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2082
6.2.1 Espressif Audio Development Framework . . . . . . . . . . . . . . . . . . . . . . . . . 2082
6.2.2 ESP-CSI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2082
6.2.3 Espressif DSP Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2082
6.2.4 ESP-WIFI-MESH Development Framework . . . . . . . . . . . . . . . . . . . . . . . . 2083
6.2.5 ESP-WHO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2083
6.2.6 ESP RainMaker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2083
6.2.7 ESP-IoT-Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2083
7 Contributions Guide 2085

7.1 How to Contribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2085
7.2 Before Contributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2085
7.3 Pull Request Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2085
7.4 Legal Part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2086
7.5 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2086
7.5.1 Espressif IoT Development Framework Style Guide . . . . . . . . . . . . . . . . . . . . 2086
7.5.2 Install pre-commit Hook for ESP-IDF Project . . . . . . . . . . . . . . . . . . . . . . . 2093
7.5.3 Documenting Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2094
7.5.4 Creating Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2099
7.5.5 API Documentation Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2100
7.5.6 Contributor Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2102
7.5.7 Copyright Header Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2104
8 ESP-IDF Versions 2107

8.1 Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2107
8.2 Which Version Should I Start With? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2107
ix
8.3 Versioning Scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2107
8.4 Support Periods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2108
8.5 Checking the Current Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2109
8.6 Git Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2110
8.7 Updating ESP-IDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2110
8.7.1 Updating to Stable Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2111
8.7.2 Updating to a Pre-Release Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2111
8.7.3 Updating to Master Branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2111
8.7.4 Updating to a Release Branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2112
9 Resources 2113
9.1 PlatformIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2113
9.1.1 What is PlatformIO? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2113
9.1.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2113
9.1.3 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2114
9.1.4 Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2114
9.1.5 Project Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2114
9.1.6 Next Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2114
9.2 Useful Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2114
10 Copyrights and Licenses 2115

10.1 Software Copyrights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2115
10.1.1 Firmware Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2115
10.1.2 Build Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2116
10.1.3 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2116
10.2 ROM Source Code Copyrights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2116
10.3 Xtensa libhal MIT License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2117
10.4 TinyBasic Plus MIT License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2117
10.5 TJpgDec License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2117
11 About 2119
12 Switch Between Languages 2121
Index 2123
Index 2123
x
Table of contents
This is the documentation for Espressif IoT Development Framework (esp-idf). ESP-IDF is the official development
framework for the ESP32, ESP32-S and ESP32-C Series SoCs.
This document describes using ESP-IDF with the ESP32 SoC.
Get Started API Reference H/W Reference
API Guides Contribute Resources
Espressif Systems 1 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Table of contents

Chapter 1
Get Started
This document is intended to help you set up the software development environment for the hardware based on the
ESP32 chip by Espressif. After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development
Framework) for menu configuration, then for building and flashing firmware onto an ESP32 board.
Note: This is documentation for the master branch (latest version) of ESP-IDF. This version is under continual
development. Stable version documentation is available, as well as other ESP-IDF Versions.
1.1 Introduction
ESP32 is a system on a chip that integrates the following features:
• Wi-Fi (2.4 GHz band)
• Bluetooth
• Dual high performance Xtensa® 32-bit LX6 CPU cores
• Ultra Low Power co-processor
• Multiple peripherals
Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform, which helps meet the continuous
demands for efficient power usage, compact design, security, high performance, and reliability.
Espressif provides basic hardware and software resources to help application developers realize their ideas using the
ESP32 series hardware. The software development framework by Espressif is intended for development of Internet-
of-Things (IoT) applications with Wi-Fi, Bluetooth, power management and several other system features.
1.2 What You Need

Hardware:
• An ESP32 board
• USB cable - USB A / micro USB B
• Computer running Windows, Linux, or macOS
Software:
You have a choice to either download and install the following software manually
• Toolchain to compile code for ESP32
• Build tools - CMake and Ninja to build a full Application for ESP32
• ESP-IDF that essentially contains API (software libraries and source code) for ESP32 and scripts to operate
the Toolchain
3
Chapter 1. Get Started
or get through the onboarding process using the following official plugins for integrated development environments
(IDE) described in separate documents
• Eclipse Plugin (installation link)
• VS Code Extension (setup)
Fig. 1: Development of applications for ESP32
1.3 Development Board Overviews

If you have one of ESP32 development boards listed below, you can click on the link to learn more about its hardware.
1.3.1 ESP32-DevKitC V4 Getting Started Guide
This guide shows how to start using the ESP32-DevKitC V4 development board.
What You Need
• ESP32-DevKitC V4 board
• USB A / micro USB B cable
You can skip the introduction sections and go directly to Section Start Application Development.

Overview
ESP32-DevKitC V4 is a small-sized ESP32-based development board produced by Espressif. Most of the I/O pins
are broken out to the pin headers on both sides for easy interfacing. Developers can either connect peripherals with
jumper wires or mount ESP32-DevKitC V4 on a breadboard.
To cover a wide range of user requirements, the following versions of ESP32-DevKitC V4 are available:
• different ESP32 modules
– ESP32-WROOM-DA
– ESP32-WROOM-32E
– ESP32-WROOM-32UE
– ESP32-WROOM-32D
– ESP32-WROOM-32U
– ESP32-SOLO-1
– ESP32-WROVER-E
– ESP32-WROVER-IE
• male or female pin headers.
For details please refer to ESP Product Selector.
Functional Description
The following figure and the table below describe the key components, interfaces and controls of the ESP32-DevKitC
V4 board.
Fig. 2: ESP32-DevKitC V4 with ESP32-WROOM-32 module soldered

Key Component Description

ESP32-WROOM-32 A module with ESP32 at its core. For more information, see ESP32-WROOM-32
Datasheet.
EN Reset button.
Boot Download button. Holding down Boot and then pressing EN initiates Firmware
Download mode for downloading firmware through the serial port.
USB-to-UART Bridge Single USB-UART bridge chip provides transfer rates of up to 3 Mbps.
Micro USB Port USB interface. Power supply for the board as well as the communication interface
between a computer and the ESP32-WROOM-32 module.
5V Power On LED Turns on when the USB or an external 5V power supply is connected to the board.
For details see the schematics in Related Documents.
I/O Most of the pins on the ESP module are broken out to the pin headers on the board.
You can program ESP32 to enable multiple functions such as PWM, ADC, DAC,
I2C, I2S, SPI, etc.
Note: The pins D0, D1, D2, D3, CMD and CLK are used internally for communication between ESP32 and SPI
flash memory. They are grouped on both sides near the USB connector. Avoid using these pins, as it may disrupt
access to the SPI flash memory / SPI RAM.
Note: The pins GPIO16 and GPIO17 are available for use only on the boards with the modules ESP32-WROOM
and ESP32-SOLO-1. The boards with ESP32-WROVER modules have the pins reserved for internal use.
Power Supply Options
There are three mutually exclusive ways to provide power to the board:
• Micro USB port, default power supply
• 5V / GND header pins
• 3V3 / GND header pins
Warning: The power supply must be provided using one and only one of the options above, otherwise the
board and/or the power supply source can be damaged.
Header Block
The two tables below provide the Name and Function of I/O header pins on both sides of the board, as shown in
ESP32-DevKitC V4 with ESP32-WROOM-32 module soldered. The numbering and names are the same as in the
ESP32-DevKitC V4 schematics (PDF).

J1
No. Name Type Function
1 3V3 P 3.3 V power supply
2 EN I CHIP_PU, Reset
3 IO36 I GPIO36, ADC1_CH0, S_VP
4 IO39 I GPIO39, ADC1_CH3, S_VN
5 IO34 I GPIO34, ADC1_CH6, VDET_1
6 IO35 I GPIO35, ADC1_CH7, VDET_2
7 IO32 I/O GPIO32, ADC1_CH4, TOUCH_CH9, XTAL_32K_P
8 IO33 I/O GPIO33, ADC1_CH5, TOUCH_CH8, XTAL_32K_N
9 IO25 I/O GPIO25, ADC1_CH8, DAC_1
10 IO26 I/O GPIO26, ADC2_CH9, DAC_2
11 IO27 I/O GPIO27, ADC2_CH7, TOUCH_CH7
12 IO14 I/O GPIO14, ADC2_CH6, TOUCH_CH6, MTMS
13 IO12 I/O GPIO12, ADC2_CH5, TOUCH_CH5, MTDI
14 GND G Ground
15 IO13 I/O GPIO13, ADC2_CH4, TOUCH_CH4, MTCK
16 IO9 I/O GPIO9, D2
18 IO11 I/O GPIO11, CMD
19 5V0 P 5 V power supply
J3
1 GND G Ground
2 IO23 I/O GPIO23
3 IO22 I/O GPIO22
4 IO1 I/O GPIO1, U0TXD
5 IO3 I/O GPIO3, U0RXD
6 IO21 I/O GPIO21
7 GND G Ground
8 IO19 I/O GPIO19
9 IO18 I/O GPIO18
10 IO5 I/O GPIO5
11 IO17 I/O GPIO17
12 IO16 I/O GPIO16
14 IO0 I/O GPIO0, ADC2_CH1, TOUCH_CH1, Boot
17 IO15 I/O GPIO15, ADC2_CH3, TOUCH_CH3, MTDO
19 IO6 I/O GPIO6, SCK
P: Power supply; I: Input; O: Output.
Pin Layout
Note on C15
The component C15 may cause the following issues on earlier ESP32-DevKitC V4 boards:
• The board may boot into Download mode
• If you output clock on GPIO0, C15 may impact the signal
In case these issues occur, please remove the component. The figure below shows C15 highlighted in yellow.

Fig. 3: ESP32-DevKitC Pin Layout (click to enlarge)
Fig. 4: Location of C15 (yellow) on ESP32-DevKitC V4 board

Start Application Development
Before powering up your ESP32-DevKitC V4, please make sure that the board is in good condition with no obvious
signs of damage.
After that, proceed to Get Started, where Section Installation Step by Step will quickly help you set up the development
environment and then flash an example project onto your board.
Board Dimensions
Fig. 5: Dimensions of ESP32-DevKitC board with ESP32-WROOM-32 module soldered - back
Related Documents
• ESP32-DevKitC V4 schematics (PDF)

• ESP32 Datasheet (PDF)
• ESP32-WROOM-DA Datasheet (PDF)
• ESP32-WROOM-32 Datasheet (PDF)
• ESP32-WROOM-32D and ESP32-WROOM-32U Datasheet (PDF)
• ESP32-WROVER Datasheet (PDF)
• ESP32-WROVER-B Datasheet (PDF)
• ESP Product Selector
For further design documentation for the board, please contact us at [email protected].
ESP32-DevKitC V2 Getting Started Guide This guide shows how to start using the ESP32-DevKitC V2 devel-
opment board.
What You Need

• ESP32-DevKitC V2 board
• USB A / micro USB B cable

Overview ESP32-DevKitC V2 is a small-sized ESP32-based development board produced by Espressif. Most of

the I/O pins are broken out to the pin headers on both sides for easy interfacing. Developers can either connect
peripherals with jumper wires or mount ESP32-DevKitC V4 on a breadboard.
Functional Description The following figure and the table below describe the key components, interfaces and
controls of the ESP32-DevKitC V2 board.
Fig. 6: ESP32-DevKitC V2 board layout
Key Com- Description

ponent
ESP32- Standard module with ESP32 at its core. For more information, see ESP32-WROOM-32 Datasheet
WROOM-
32
EN Reset button.
Boot Download button. Holding down Boot and then pressing EN initiates Firmware Download mode
for downloading firmware through the serial port.
Micro USB interface. Power supply for the board as well as the communication interface between a com-
USB Port puter and ESP32-WROOM-32.
I/O Most of the pins on the ESP module are broken out to the pin headers on the board. You can
program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc.
Power Supply Options There are three mutually exclusive ways to provide power to the board:

Start Application Development Before powering up your ESP32-DevKitC V2, please make sure that the board
is in good condition with no obvious signs of damage.
Related Documents
• ESP32-DevKitC schematics (PDF)
1.3.2 ESP-WROVER-KIT V4.1 Getting Started Guide
This guide shows how to get started with the ESP-WROVER-KIT V4.1 development board and also provides infor-
mation about its functionality and configuration options.
What You Need
• ESP-WROVER-KIT V4.1 board

• USB 2.0 cable A to Micro-B
Overview
ESP-WROVER-KIT is an ESP32-based development board produced by Espressif.

ESP-WROVER-KIT features the following integrated components:
• ESP32-WROVER-E module
• LCD screen
• MicroSD card slot
Its another distinguishing feature is the embedded FTDI FT2232HL chip - an advanced multi-interface USB bridge.
This chip enables to use JTAG for direct debugging of ESP32 through the USB interface without a separate JTAG
debugger. ESP-WROVER-KIT makes development convenient, easy, and cost-effective.
Most of the ESP32 I/O pins are broken out to the board s pin headers for easy access.
Note: ESP32 s GPIO16 and GPIO17 are used as chip select and clock signals for PSRAM. By default, the two
GPIOs are not broken out to the board s pin headers in order to ensure reliable performance.
Functionality Overview
The block diagram below shows the main components of ESP-WROVER-KIT and their interconnections.
The following two figures and the table below describe the key components, interfaces, and controls of the ESP-
WROVER-KIT board.
The table below provides description in the following manner:
• Starting from the first picture s top right corner and going clockwise

Fig. 7: ESP-WROVER-KIT block diagram
Fig. 8: ESP-WROVER-KIT board layout - front

Fig. 9: ESP-WROVER-KIT board layout - back
• Then moving on to the second picture


FT2232 The FT2232 chip serves as a multi-protocol USB-to-serial bridge which can be pro-
grammed and controlled via USB to provide communication with ESP32. FT2232
also features USB-to-JTAG interface which is available on channel A of the chip,
while USB-to-serial is on channel B. The FT2232 chip enhances user-friendliness
in terms of application development and debugging. See ESP-WROVER-KIT V4.1
schematic.
32.768 kHz External precision 32.768 kHz crystal oscillator serves as a clock with low-power
consumption while the chip is in Deep-sleep mode.
0R Zero-ohm resistor intended as a placeholder for a current shunt, can be desoldered
or replaced with a current shunt to facilitate the measurement of ESP32 s current
consumption in different modes.
ESP32-WROVER-E This ESP32 module features 64-Mbit PSRAM for flexible extended storage and data
module processing capabilities.
Diagnostic LEDs Four red LEDs connected to the GPIO pins of FT2232. Intended for future use.
UART Serial port. The serial TX/RX signals of FT2232 and ESP32 are broken out to the
inward and outward sides of JP2 respectively. By default, these pairs of pins are
connected with jumpers. To use ESP32 s serial interface, remove the jumpers and
connect another external serial device to the respective pins.
SPI By default, ESP32 uses its SPI interface to access flash and PSRAM memory inside
the module. Use these pins to connect ESP32 to another SPI device. In this case, an
extra chip select (CS) signal is needed. Please note that the voltage of this interface
is 3.3 V.
CTS/RTS Serial port flow control signals: the pins are not connected to the circuitry by default.
To enable them, short the respective pins of JP14 with jumpers.
JTAG JTAG interface. JTAG signals of FT2232 and ESP32 are broken out to the inward
and outward sides of JP2 respectively. By default, these pairs of pins are discon-
nected. To enable JTAG, short the respective pins with jumpers as shown in Section
Setup Options.
USB Port USB interface. Power supply for the board as well as the communication interface
between a computer and the board.
EN Button Reset button.
BOOT Button Download button. Holding down Boot and then pressing EN initiates Firmware
Power Switch Power On/Off Switch. Toggling toward the Boot button powers the board on, tog-
gling away from Boot powers the board off.
Power Selector Power supply selector interface. The board can be powered either via USB or via the
5V Input interface. Select the power source with a jumper. For more details, see
Section Setup Options, jumper header JP7.
5V Input 5V power supply interface for a standard coaxial power connector, 5.5 x 2.1 mm,
center positive. This interface can be more convenient when the board is operating
autonomously (not connected to a computer).
5V Power On LED This red LED turns on when power is supplied to the board, either from USB or 5V
Input.
LDO NCP1117(1A). 5V-to-3.3V LDO. NCP1117 can provide a maximum current of 1A.
The LDO on the board has a fixed output voltage. Although, the user can install an
LDO with adjustable output voltage. For details, please refer to ESP-WROVER-KIT
V4.1 schematic.
Camera Connector Camera interface, a standard OV7670 camera module.
RGB LED Red, green and blue (RGB) light emitting diodes (LEDs), can be controlled by pulse
width modulation (PWM).
I/O Connector All the pins on the ESP32 module are broken out to pin headers. You can program
ESP32 to enable multiple functions, such as PWM, ADC, DAC, I2C, I2S, SPI, etc.
MicroSD Card Slot Useful for developing applications that access MicroSD card for data storage and
retrieval.
LCD Support for mounting and interfacing a 3.2 SPI (standard 4-wire Serial Peripheral
Interface) LCD, as shown on figure ESP-WROVER-KIT board layout - back.

Setup Options
There are three jumper blocks available to set up the board functionality. The most frequently required options are
listed in the table below.

Header Jumper Setting Description of Functionality
JP7 Power ESP-WROVER-KIT via an external power

supply
JP7 Power ESP-WROVER-KIT via USB
JP2 Enable JTAG functionality

Allocation of ESP32 Pins
Some pins / terminals of ESP32 are allocated for use with the onboard or external hardware. If that hardware is not
used, e.g., nothing is plugged into the Camera (JP4) header, then these GPIOs can be used for other purposes.
Some of the pins, such as GPIO0 or GPIO2, have multiple functions and some of them are shared among onboard
and external peripheral devices. Certain combinations of peripherals cannot work together. For example, it is not
possible to do JTAG debugging of an application that is using SD card, because several pins are shared by JTAG and
the SD card slot.
In other cases, peripherals can coexist under certain conditions. This is applicable to, for example, LCD screen and
SD card that share only a single pin GPIO21. This pin is used to provide D/C (Data / Control) signal for the LCD as
well as the Card Detect signal read from the SD card slot. If the card detect functionality is not essential, then it may
be disabled by removing R167, so both LCD and SD may operate together.
For more details on which pins are shared among which peripherals, please refer to the table in the next section.
Main I/O Connector / JP1 The JP1 connector consists of 14x2 male pins whose functions are shown in the middle
two I/O columns of the table below. The two Shared With columns on both sides describe where else on the
board a certain GPIO is used.
Shared With I/O I/O Shared With

n/a 3.3V GND n/a
NC/XTAL IO32 IO33 NC/XTAL
JTAG, MicroSD IO12 IO13 JTAG, MicroSD
JTAG, MicroSD IO14 IO27 Camera
Camera IO26 IO25 Camera, LCD
Camera IO35 IO34 Camera
JTAG EN IO23 Camera, LCD
Camera, LCD IO22 IO21 Camera, LCD, MicroSD
Camera, LCD IO19 IO18 Camera, LCD
Camera, LCD IO5 IO17 PSRAM
PSRAM IO16 IO4 LED, Camera, MicroSD
Camera, LED, Boot IO0 IO2 LED, MicroSD
JTAG, MicroSD IO15 5V
Legend:
• NC/XTAL - 32.768 kHz Oscillator
• JTAG - JTAG / JP2
• Boot - Boot button / SW2
• Camera - Camera / JP4
• LED - RGB LED
• MicroSD - MicroSD Card / J4
• LCD - LCD / U5
• PSRAM - ESP32-WROVER-E s PSRAM
32.768 kHz Oscillator

. ESP32 Pin
1 GPIO32
2 GPIO33
Note: Since GPIO32 and GPIO33 are connected to the oscillator by default, they are not connected to the JP1 I/O
connector to maintain signal integrity. This allocation may be changed from the oscillator to JP1 by desoldering the
zero-ohm resistors from positions R11 / R23 and re-soldering them to positions R12 / R24.

SPI Flash / JP2

. ESP32 Pin
1 CLK / GPIO6
2 SD0 / GPIO7
3 SD1 / GPIO8
4 SD2 / GPIO9
5 SD3 / GPIO10
6 CMD / GPIO11
Important: The module s flash bus is connected to the jumper block JP2 through zero-ohm resistors R140 ~
R145. If the flash memory needs to operate at the frequency of 80 MHz, for reasons such as improving the integrity
of bus signals, you can desolder these resistors to disconnect the module s flash bus from the pin header JP2.
JTAG / JP2
. ESP32 Pin JTAG Signal
1 EN TRST_N
2 MTMS / GPIO14 TMS
3 MTDO / GPIO15 TDO
4 MTDI / GPIO12 TDI
5 MTCK / GPIO13 TCK
Camera / JP4
. ESP32 Pin Camera Signal
1 n/a 3.3V
2 n/a Ground
3 GPIO27 SIO_C / SCCB Clock
4 GPIO26 SIO_D / SCCB Data
5 GPIO25 VSYNC / Vertical Sync
6 GPIO23 HREF / Horizontal Reference
7 GPIO22 PCLK / Pixel Clock
8 GPIO21 XCLK / System Clock
9 GPIO35 D7 / Pixel Data Bit 7
17 GPIO0 RESET / Camera Reset
18 n/a PWDN / Camera Power Down
• Signals D0 .. D7 denote camera data bus
RGB LED
. ESP32 Pin RGB LED
1 GPIO0 Red
2 GPIO2 Green
3 GPIO4 Blue

MicroSD Card
. ESP32 Pin MicroSD Signal
1 MTDI / GPIO12 DATA2
2 MTCK / GPIO13 CD / DATA3
3 MTDO / GPIO15 CMD
4 MTMS / GPIO14 CLK
5 GPIO2 DATA0
6 GPIO4 DATA1
7 GPIO21 Card Detect
LCD / U5
. ESP32 Pin LCD Signal
1 GPIO18 RESET
2 GPIO19 SCL
3 GPIO21 D/C
4 GPIO22 CS
5 GPIO23 SDA
6 GPIO25 SDO
7 GPIO5 Backlight
Before powering up your ESP-WROVER-KIT, please make sure that the board is in good condition with no obvious
signs of damage.
Initial Setup Please set only the following jumpers shown in the pictures below:
• Select USB as the power source using the jumper block JP7.
• Enable UART communication using the jumper block JP2.
Power up from USB port Enable UART communication
Do not install any other jumpers.

Turn the Power Switch to ON, the 5V Power On LED should light up.
Now to Development Please proceed to Get Started, where Section Installation Step by Step will quickly help you
set up the development environment and then flash an example project onto your board.

Related Documents
• ESP-WROVER-KIT V4.1 schematic (PDF)

• ESP-WROVER-KIT V4.1 layout (DXF) may be opened online with Autodesk Viewer
• ESP32-WROVER-E Datasheet (PDF)
• JTAG Debugging
• ESP32 Hardware Reference
ESP-WROVER-KIT V3 Getting Started Guide This guide shows how to get started with the ESP-WROVER-
KIT V3 development board and also provides information about its functionality and configuration options. For the
description of other ESP-WROVER-KIT versions, please check ESP32 Hardware Reference.
What You Need

• ESP-WROVER-KIT V3 board
Overview ESP-WROVER-KIT is an ESP32-based development board produced by Espressif. This board features
an integrated LCD screen and MicroSD card slot.
ESP-WROVER-KIT comes with the following ESP32 modules:
• ESP32-WROOM-32
• ESP32-WROVER series
Note: The version with the ESP32-WROVER module uses ESP32 s GPIO16 and GPIO17 as chip
select and clock signals for PSRAM. By default, the two GPIOs are not broken out to the board s pin
headers in order to ensure reliable performance.
Functionality Overview The block diagram below shows the main components of ESP-WROVER-KIT and their
interconnections.
Functional Description The following two figures and the table below describe the key components, interfaces,
and controls of the ESP-WROVER-KIT board.

Key Description
Com-
po-
nent
32.768 External precision 32.768 kHz crystal oscillator serves as a clock with low-power consumption while the
kHz chip is in Deep-sleep mode.
0R Zero-ohm resistor intended as a placeholder for a current shunt, can be desoldered or replaced with a
current shunt to facilitate the measurement of ESP32 s current consumption in different modes.
ESP32 Either ESP32-WROOM-32 or ESP32-WROVER with an integrated ESP32. The ESP32-WROVER
Mod- module features all the functions of ESP32-WROOM-32 and integrates an external 32-MBit PSRAM for
ule flexible extended storage and data processing capabilities.
FT2232The FT2232 chip serves as a multi-protocol USB-to-serial bridge which can be programmed and con-
trolled via USB to provide communication with ESP32. FT2232 also features USB-to-JTAG interface
which is available on channel A of the chip, while USB-to-serial is on channel B. The FT2232 chip en-
hances user-friendliness in terms of application development and debugging. See ESP-WROVER-KIT
V3 schematic.
UART Serial port. The serial TX/RX signals of FT2232 and ESP32 are broken out to the inward and outward
sides of JP11 respectively. By default, these pairs of pins are connected with jumpers. To use ESP32 s
serial interface, remove the jumpers and connect another external serial device to the respective pins.
SPI By default, ESP32 uses its SPI interface to access flash and PSRAM memory inside the module. Use
these pins to connect ESP32 to another SPI device. In this case, an extra chip select (CS) signal is needed.
Please note that the interface voltage for the version with ESP32-WROVER is 1.8V, while that for the
version with ESP32-WROOM-32 is 3.3V.
CTS/RTS Serial port flow control signals: the pins are not connected to the circuitry by default. To enable them,
short the respective pins of JP14 with jumpers.
JTAG JTAG interface. JTAG signals of FT2232 and ESP32 are broken out to the inward and outward sides of
JP8 respectively. By default, these pairs of pins are disconnected. To enable JTAG, short the respective
pins with jumpers as shown in Section Setup Options.
EN Reset button.
Boot Download button. Holding down Boot and then pressing EN initiates Firmware Download mode for
downloading firmware through the serial port.
USB USB interface. Power supply for the board as well as the communication interface between a computer
and the board.
Power Power On/Off Switch. Toggling toward USB powers the board on, toggling away from USB powers the
Key board off.
Power Power supply selector interface. The board can be powered either via USB or via the 5V Input interface.
Se- Select the power source with a jumper. For more details, see Section Setup Options, jumper header JP7.
Espressif
lect Systems 21 Release v5.0-dev-401-g451ce8a
5V Submit Document Feedback
The 5V power supply interface can be more convenient when the board is operating autonomously (not
In- connected to a computer).
put


Setup Options There are five jumper blocks available to set up the board functionality. The most frequently
required options are listed in the table below.

JP7 Power ESP-WROVER-KIT via an external power

supply
JP8 Enable JTAG functionality

Allocation of ESP32 Pins Some pins / terminals of ESP32 are allocated for use with the onboard or external
hardware. If that hardware is not used, e.g., nothing is plugged into the Camera (JP4) header, then these GPIOs can
be used for other purposes.
Some of the pins, such as GPIO0 or GPIO2, have multiple functions and some of them are shared among onboard
and external peripheral devices. Certain combinations of peripherals cannot work together. For example, it is not
possible to do JTAG debugging of an application that is using SD card, because several pins are shared by JTAG and
the SD card slot.
In other cases, peripherals can coexist under certain conditions. This is applicable to, for example, LCD screen and
SD card that share only a single pin GPIO21. This pin is used to provide D/C (Data / Control) signal for the LCD as
well as the CD (Card Detect) signal read from the SD card slot. If the card detect functionality is not essential, then
it may be disabled by removing R167, so both LCD and SD may operate together.
For more details on which pins are shared among which peripherals, please refer to the table in the next section.
Main I/O Connector / JP1 The JP1 connector consists of 14x2 male pins whose functions are shown in the middle
two I/O columns of the table below. The two Shared With columns on both sides describe where else on the
board a certain GPIO is used.
Shared With I/O I/O Shared With

n/a 3.3V GND n/a
NC/XTAL IO32 IO33 NC/XTAL
JTAG, MicroSD IO12 IO13 JTAG, MicroSD
JTAG, MicroSD IO14 IO27 Camera
Camera IO26 IO25 Camera, LCD
JTAG EN IO23 Camera, LCD
Camera, LCD IO22 IO21 Camera, LCD, MicroSD
Camera, LCD IO19 IO18 Camera, LCD
Camera, LCD IO5 IO17 PSRAM
PSRAM IO16 IO4 LED, Camera, MicroSD
Camera, LED, Boot IO0 IO2 LED, MicroSD
JTAG, MicroSD IO15 5V
Legend:
• NC/XTAL - 32.768 kHz Oscillator
• JTAG - JTAG / JP8
• Boot - Boot button / SW2
• Camera - Camera / JP4
• LED - RGB LED
• MicroSD - MicroSD Card / J4
• LCD - LCD / U5
• PSRAM - only in case ESP32-WROVER is installed
32.768 kHz Oscillator

. ESP32 Pin
1 GPIO32
2 GPIO33
Note: Since GPIO32 and GPIO33 are connected to the oscillator by default, they are not connected to the JP1 I/O
connector to maintain signal integrity. This allocation may be changed from the oscillator to JP1 by desoldering the
zero-ohm resistors from positions R11 / R23 and re-soldering them to positions R12 / R24.

SPI Flash / JP13

. ESP32 Pin
1 CLK / GPIO6
2 SD0 / GPIO7
3 SD1 / GPIO8
4 SD2 / GPIO9
5 SD3 / GPIO10
6 CMD / GPIO11
Important: The module s flash bus is connected to the jumper block JP13 through zero-ohm resistors R140 ~
R145. If the flash memory needs to operate at the frequency of 80 MHz, for reasons such as improving the integrity
of bus signals, you can desolder these resistors to disconnect the module s flash bus from the pin header JP13.
JTAG / JP8
. ESP32 Pin JTAG Signal
1 EN TRST_N
2 MTMS / GPIO14 TMS
3 MTDO / GPIO15 TDO
4 MTDI / GPIO12 TDI
5 MTCK / GPIO13 TCK
Camera / JP4
. ESP32 Pin Camera Signal
1 n/a 3.3V
2 n/a Ground
3 GPIO27 SIO_C / SCCB Clock
4 GPIO26 SIO_D / SCCB Data
5 GPIO25 VSYNC / Vertical Sync
6 GPIO23 HREF / Horizontal Reference
7 GPIO22 PCLK / Pixel Clock
8 GPIO21 XCLK / System Clock
17 GPIO0 RESET / Camera Reset
18 n/a PWDN / Camera Power Down
• Signals D0 .. D7 denote camera data bus
RGB LED
. ESP32 Pin RGB LED
1 GPIO0 Red
2 GPIO2 Green
3 GPIO4 Blue

MicroSD Card
. ESP32 Pin MicroSD Signal
1 MTDI / GPIO12 DATA2
2 MTCK / GPIO13 CD / DATA3
3 MTDO / GPIO15 CMD
4 MTMS / GPIO14 CLK
5 GPIO2 DATA0
6 GPIO4 DATA1
7 GPIO21 CD
LCD / U5
. ESP32 Pin LCD Signal
1 GPIO18 RESET
2 GPIO19 SCL
3 GPIO21 D/C
4 GPIO22 CS
5 GPIO23 SDA
6 GPIO25 SDO
7 GPIO5 Backlight
Start Application Development Before powering up your ESP-WROVER-KIT, please make sure that the board


Related Documents
• ESP-WROVER-KIT V3 schematic (PDF)
• JTAG Debugging
ESP-WROVER-KIT V2 Getting Started Guide This guide shows how to get started with the ESP-WROVER-
KIT V2 development board and also provides information about its functionality and configuration options. For the
description of other ESP-WROVER-KIT versions, please check ESP32 Hardware Reference.
What You Need

• ESP-WROVER-KIT V2 board
Overview ESP-WROVER-KIT is an ESP32-based development board produced by Espressif. This board features
an integrated LCD screen and MicroSD card slot.
ESP-WROVER-KIT comes with the following ESP32 modules:
• ESP32-WROOM-32
• ESP32-WROVER series
Note: The version with the ESP32-WROVER module uses ESP32 s GPIO16 and GPIO17 as chip
select and clock signals for PSRAM. By default, the two GPIOs are not broken out to the board s pin
headers in order to ensure reliable performance.
Functionality Overview The block diagram below shows the main components of ESP-WROVER-KIT and their
interconnections.
Functional Description The following two figures and the table below describe the key components, interfaces,
and controls of the ESP-WROVER-KIT board.



Key Description
Com-
po-
nent
32.768 External precision 32.768 kHz crystal oscillator serves as a clock with low-power consumption while the
kHz chip is in Deep-sleep mode.
ESP32 Either ESP32-WROOM-32 or ESP32-WROVER with an integrated ESP32. The ESP32-WROVER
Mod- module features all the functions of ESP32-WROOM-32 and integrates an external 32-MBit PSRAM
ule for flexible extended storage and data processing capabilities.
CTS/RTSSerial port flow control signals: the pins are not connected to the circuitry by default. To enable them,
short the respective pins of JP14 with jumpers.
UART Serial port. The serial TX/RX signals of FT2232 and ESP32 are broken out to the inward and outward
sides of JP11 respectively. By default, these pairs of pins are connected with jumpers. To use ESP32 s
serial interface, remove the jumpers and connect another external serial device to the respective pins.
SPI By default, ESP32 uses its SPI interface to access flash and PSRAM memory inside the module. Use
these pins to connect ESP32 to another SPI device. In this case, an extra chip select (CS) signal is
needed. Please note that the interface voltage for the version with ESP32-WROVER is 1.8V, while that
for the version with ESP32-WROOM-32 is 3.3V.
JTAG JTAG interface. JTAG signals of FT2232 and ESP32 are broken out to the inward and outward sides of
JP8 respectively. By default, these pairs of pins are disconnected. To enable JTAG, short the respective
pins with jumpers as shown in Section Setup Options.
FT2232 The FT2232 chip serves as a multi-protocol USB-to-serial bridge which can be programmed and con-
trolled via USB to provide communication with ESP32. FT2232 features USB-to-UART and USB-to-
JTAG functionalities.
EN Reset button.
Boot Download button. Holding down Boot and then pressing EN initiates Firmware Download mode for
downloading firmware through the serial port.
and the board.
Power Power supply selector interface. The board can be powered either via USB or via the 5V Input interface.
Se- Select the power source with a jumper. For more details, see Section Setup Options, jumper header JP7.
lect
Power Power On/Off Switch. Toggling toward USB powers the board on, toggling away from USB powers the
Key board off.
5V The 5V power supply interface can be more convenient when the board is operating autonomously (not
put
LDO NCP1117(1A). 5V-to-3.3V LDO. NCP1117 can provide a maximum current of 1A. The LDO on the
board has a fixed output voltage. Although, the user can install an LDO with adjustable output voltage.
For details, please refer to ESP-WROVER-KIT V2 schematic.
Cam- Camera interface, a standard OV7670 camera module.
era
RGB Red, green and blue (RGB) light emitting diodes (LEDs), can be controlled by pulse width modulation
(PWM).
I/O All the pins on the ESP32 module are broken out to pin headers. You can program ESP32 to enable
multiple functions, such as PWM, ADC, DAC, I2C, I2S, SPI, etc.
Mi- MicroSD card slot for data storage: when ESP32 enters the download mode, GPIO2 cannot be held high.
croSD However, a pull-up resistor is required on GPIO2 to enable the MicroSD Card. By default, GPIO2 and
Card the pull-up resistor R153 are disconnected. To enable the SD Card, use jumpers on JP1 as shown in
Section Setup Options.
LCD Support for mounting and interfacing a 3.2 SPI (standard 4-wire Serial Peripheral Interface) LCD, as
shown on figure ESP-WROVER-KIT board layout - back.
Setup Options There are five jumper blocks available to set up the board functionality. The most frequently
required options are listed in the table below.

JP1 Enable pull up for the MicroSD Card
JP1 Assert GPIO2 low during each download (by jumping it to

GPIO0)
JP7 Power ESP-WROVER-KIT via an external power supply
Espressif
JP8 Systems Enable33JTAG functionality Release v5.0-dev-401-g451ce8a
Start Application Development Before powering up your ESP-WROVER-KIT, please make sure that the board

Related Documents
• ESP-WROVER-KIT V2 schematic (PDF)
• JTAG Debugging
1.3.3 ESP32-PICO-KIT V4 / V4.1 Getting Started Guide
This guide shows how to get started with the ESP32-PICO-KIT V4 / V4.1 mini development board. For the descrip-
tion of other ESP32-PICO-KIT versions, please check ESP32 Hardware Reference.
This particular description covers ESP32-PICO-KIT V4 and V4.1. The difference is the upgraded USB-UART
bridge from CP2102 in V4 with up to 1 Mbps transfer rates to CP2102N in V4.1 with up to 3 Mbps transfer rates.
What You Need
• ESP32-PICO-KIT mini development board

• USB 2.0 A to Micro B cable

Overview
ESP32-PICO-KIT is an ESP32-based mini development board produced by Espressif.

The core of this board is ESP32-PICO-D4 - a System-in-Package (SiP) module with complete Wi-Fi and Bluetooth
functionalities. Compared to other ESP32 modules, ESP32-PICO-D4 integrates the following peripheral components
in one single package, which otherwise would need to be installed separately:
• 40 MHz crystal oscillator
• 4 MB flash
• Filter capacitors
• RF matching links
This setup reduces the costs of additional external components as well as the cost of assembly and testing and also
increases the overall usability of the product.
The development board features a USB-UART Bridge circuit which allows developers to connect the board to a
computer s USB port for flashing and debugging.
All the IO signals and system power on ESP32-PICO-D4 are led out to two rows of 20 x 0.1 header pads on both sides
of the development board for easy access. For compatibility with Dupont wires, 2 x 17 header pads are populated
with two rows of male pin headers. The remaining 2 x 3 header pads beside the antenna are not populated. These
pads may be populated later by the user if required.
Note:
1. The 2 x 3 pads not populated with pin headers are connected to the flash memory embedded in the ESP32-
PICO-D4 SiP module. For more details see module s datasheet in Related Documents.
2. ESP32-PICO-KIT comes with male headers by default.
The block diagram below shows the main components of ESP32-PICO-KIT and their interconnections.
Fig. 16: ESP32-PICO-KIT block diagram

The following figure and the table below describe the key components, interfaces, and controls of the ESP32-PICO-
KIT board.
Fig. 17: ESP32-PICO-KIT board layout
Below is the description of the items identified in the figure starting from the top left corner and going clockwise.

Key Description
Com-
po-
nent
ESP32- Standard ESP32-PICO-D4 module soldered to the ESP32-PICO-KIT board. The complete ESP32 sys-
PICO- tem on a chip (ESP32 SoC) has been integrated into the SiP module, requiring only an external antenna
D4 with LC matching network, decoupling capacitors, and a pull-up resistor for EN signals to function
properly.
LDO 5V-to-3.3V Low dropout voltage regulator (LDO).
USB- Single-chip USB-UART bridge: CP2102 in V4 provides up to 1 Mbps transfer rates and CP2102N in
UART V4.1 offers up to 3 Mbps transfers rates.
bridge
Micro USB interface. Power supply for the board as well as the communication interface between a computer
USB and the board.
Port
5V This red LED turns on when power is supplied to the board. For details, see the schematics in Related
Power Documents.
On
LED
I/O All the pins on ESP32-PICO-D4 are broken out to pin headers. You can program ESP32 to enable
multiple functions, such as PWM, ADC, DAC, I2C, I2S, SPI, etc. For details, please see Section Pin
Descriptions.
BOOT Download button. Holding down Boot and then pressing EN initiates Firmware Download mode for
But- downloading firmware through the serial port.
ton
EN Reset button.
But-
ton
Power Supply Options
There are three mutually exclusive ways to provide power to the board:
Pin Descriptions
The two tables below provide the Name and Function of I/O header pins on both sides of the board, see ESP32-
PICO-KIT board layout. The pin numbering and header names are the same as in the schematic given in Related
Documents.

Header J2

1 FLASH_SD1 (FSD1) I/O
GPIO8, SD_DATA1,
SPID, HS1_DATA1 (See
1) , U2CTS

GPIO7, SD_DATA0,
SPIQ, HS1_DATA0 (See
1) , U2RTS
3 FLASH_CLK (FCLK) I/O

GPIO6, SD_CLK,
SPICLK, HS1_CLK (See
1) , U1CTS
4 IO21 I/O
GPIO21, VSPIHD,
EMAC_TX_EN
5 IO22 I/O
GPIO22, VSPIWP,
U0RTS, EMAC_TXD1
6 IO19 I/O
GPIO19, VSPIQ,
U0CTS, EMAC_TXD0
7 IO23 I/O
GPIO23, VSPID,
HS1_STROBE
8 IO18 I/O
GPIO18, VSPICLK,
HS1_DATA7
9 IO5 I/O
GPIO5, VSPICS0,
HS1_DATA6,
EMAC_RX_CLK
10 IO10 I/O
GPIO10, SD_DATA3,
SPIWP, HS1_DATA3,
U1TXD
11 IO9 I/O
GPIO9, SD_DATA2,
SPIHD, HS1_DATA2,
U1RXD
12 RXD0 I/O
Submit Document Feedback GPIO3, U0RXD (See 3) ,
CLK_OUT2

Header J3

1 FLASH_CS (FCS) I/O
GPIO16, HS1_DATA4
(See 1) , U2RXD,
EMAC_CLK_OUT

GPIO17, HS1_DATA5
(See 1) , U2TXD,
EMAC_CLK_OUT_180

GPIO11, SD_CMD,
SPICS0, HS1_CMD (See
1) , U1RTS
4 SENSOR_VP (FSVP) I
GPIO36, ADC1_CH0,
RTC_GPIO0
5 SENSOR_VN (FSVN) I
GPIO39, ADC1_CH3,
RTC_GPIO3
6 IO25 I/O
GPIO25, DAC_1,
ADC2_CH8,
RTC_GPIO6,
EMAC_RXD0
7 IO26 I/O
GPIO26, DAC_2,
ADC2_CH9,
RTC_GPIO7,
EMAC_RXD1
8 IO32 I/O
32K_XP (See 2a) ,
ADC1_CH4, TOUCH9,
RTC_GPIO9
9 IO33 I/O
32K_XN (See 2b) ,
ADC1_CH5, TOUCH8,
RTC_GPIO8
10 IO27 I/O
GPIO27, ADC2_CH7,
TOUCH7,
RTC_GPIO17
EMAC_RX_DV
11
Espressif Systems IO14 40 I/O Release v5.0-dev-401-g451ce8a
ADC2_CH6, TOUCH6,
RTC_GPIO16, MTMS,
HSPICLK,
The following notes give more information about the items in the tables above.
1. This pin is connected to the flash pin of ESP32-PICO-D4.
2. 32.768 kHz crystal oscillator: a) input b) output
3. This pin is connected to the pin of the USB bridge chip on the board.
4. The operating voltage of ESP32-PICO-KIT s embedded SPI flash is 3.3V. Therefore, the strapping pin MTDI
should hold bit zero during the module power-on reset. If connected, please make sure that this pin is not held
up on reset.
Before powering up your ESP32-PICO-KIT, please make sure that the board is in good condition with no obvious
signs of damage.
Board Dimensions
The dimensions are 52 x 20.3 x 10 mm (2.1 x 0.8 x 0.4 ).
Fig. 18: ESP32-PICO-KIT dimensions - back
For the board physical construction details, please refer to its Reference Design listed below.
Related Documents
• ESP32-PICO-KIT V4 schematic (PDF)

• ESP32-PICO-KIT V4.1 schematic (PDF)
• ESP32-PICO-KIT Reference Design containing OrCAD schematic, PCB layout, gerbers and BOM
• ESP32-PICO-D4 Datasheet (PDF)
ESP32-PICO-KIT V3 Getting Started Guide This guide shows how to get started with the ESP32-PICO-KIT
V3 mini development board. For the description of other ESP32-PICO-KIT versions, please check ESP32 Hardware
Reference.

Fig. 19: ESP32-PICO-KIT dimensions - side
What You Need

• ESP32-PICO-KIT V3 mini development board
• USB 2.0 A to Micro B cable
Overview ESP32-PICO-KIT V3 is an ESP32-based mini development board produced by Espressif. The core of
this board is ESP32-PICO-D4 - a System-in-Package (SiP) module.
The development board features a USB-UART Bridge circuit, which allows developers to connect the board to a
All the IO signals and system power on ESP32-PICO-D4 are led out to two rows of 20 x 0.1 header pads on both
sides of the development board for easy access.
Functional Description The following figure and the table below describe the key components, interfaces, and
controls of the ESP32-PICO-KIT V3 board.

Fig. 20: ESP32-PICO-KIT V3 board layout

Key Description
Com-
po-
nent
ESP32- Standard ESP32-PICO-D4 module soldered to the ESP32-PICO-KIT V3 board. The complete ESP32
PICO- system on a chip (ESP32 SoC) has been integrated into the SiP module, requiring only an external an-
D4 tenna with LC matching network, decoupling capacitors, and a pull-up resistor for EN signals to function
properly.
USB- Single-chip USB-UART bridge provides up to 1 Mbps transfers rates.
UART
bridge
USB and the board.
Port
Power This red LED turns on when power is supplied to the board.
On
LED
I/O All the pins on ESP32-PICO-D4 are broken out to pin headers. You can program ESP32 to enable
multiple functions, such as PWM, ADC, DAC, I2C, I2S, SPI, etc.
ton
EN Reset button.
But-
ton
Start Application Development Before powering up your ESP32-PICO-KIT V3, please make sure that the board
Related Documents
• ESP32-PICO-KIT V3 schematic (PDF)
• ESP32-PICO-D4 Datasheet (PDF)
1.3.4 ESP32-Ethernet-Kit V1.2 Getting Started Guide
This guide shows how to get started with the ESP32-Ethernet-Kit development board and also provides information
about its functionality and configuration options.
The ESP32-Ethernet-Kit is an Ethernet-to-Wi-Fi development board that enables Ethernet devices to be intercon-
nected over Wi-Fi. At the same time, to provide more flexible power supply options, the ESP32-Ethernet-Kit also
supports power over Ethernet (PoE).
What You Need
• ESP32-Ethernet-Kit V1.2 board

• USB 2.0 A to Micro B Cable

Fig. 21: ESP32-Ethernet-Kit V1.2 Overview (click to enlarge)

Overview
ESP32-Ethernet-Kit is an ESP32-based development board produced by Espressif.

It consists of two development boards, the Ethernet board A and the PoE board B. The Ethernet board (A) con-
tains Bluetooth/Wi-Fi dual-mode ESP32-WROVER-E module and IP101GRI, a Single Port 10/100 Fast Ethernet
Transceiver (PHY). The PoE board (B) provides power over Ethernet functionality. The A board can work indepen-
dently, without the board B installed.
Fig. 22: ESP32-Ethernet-Kit V1.2 (click to enlarge)
For the application loading and monitoring, the Ethernet board (A) also features FTDI FT2232H chip - an advanced
multi-interface USB bridge. This chip enables to use JTAG for direct debugging of ESP32 through the USB interface
without a separate JTAG debugger.
The block diagram below shows the main components of ESP32-Ethernet-Kit and their interconnections.
The following figures and tables describe the key components, interfaces, and controls of the ESP32-Ethernet-Kit.

Fig. 23: ESP32-Ethernet-Kit block diagram (click to enlarge)
Fig. 24: ESP32-Ethernet-Kit - Ethernet board (A) layout (click to enlarge)

Ethernet Board (A) The table below provides description starting from the picture s top right corner and going
clockwise.

Key Description
Com-
po-
nent
ESP32- This ESP32 module features 64-Mbit PSRAM for flexible extended storage and data processing capabil-
WROVER- ities.
E
GPIO Five unpopulated through-hole solder pads to provide access to selected GPIOs of ESP32. For details,
Header see GPIO Header 2.
2
Func- A 4-bit DIP switch used to configure the functionality of selected GPIOs of ESP32. For details see
tion Function Switch.
Switch
Tx/Rx Two LEDs to show the status of UART transmission.
LEDs
FT2232H The FT2232H chip serves as a multi-protocol USB-to-serial bridge which can be programmed and con-
trolled via USB to provide communication with ESP32. FT2232H also features USB-to-JTAG interface
which is available on channel A of the chip, while USB-to-serial is on channel B. The FT2232H chip
enhances user-friendliness in terms of application development and debugging. See ESP32-Ethernet-Kit
V1.2 Ethernet board (A) schematic.
Port and the board.
Power Power On/Off Switch. Toggling the switch to 5V0 position powers the board on, toggling to GND position
Switch powers the board off.
put
5V This red LED turns on when power is supplied to the board, either from USB or 5V Input.
Power
On
LED
DC/DC Provided DC 5 V to 3.3 V conversion, output current up to 2 A.
Con-
verter
Board A pair male and female header pins for mounting the PoE board (B).
B
Con-
nec-
tors
IP101GRI The physical layer (PHY) connection to the Ethernet cable is implemented using the IP101GRI chip. The
(PHY) connection between PHY and ESP32 is done through the reduced media-independent interface (RMII),
a variant of the media-independent interface (MII) standard. The PHY supports the IEEE 802.3/802.3u
standard of 10/100 Mbps.
RJ45 Ethernet network data transmission port.
Port
Mag- The Magnetics are part of the Ethernet specification to protect against faults and transients, including
net- rejection of common mode signals between the transceiver IC and the cable. The magnetics also provide
ics galvanic isolation between the transceiver and the Ethernet device.
Mod-
ule
Link/Activity
Two LEDs (green and red) that respectively indicate the Link and Activity statuses of the PHY.
LEDs
BOOT Download button. Holding down BOOT and then pressing EN initiates Firmware Download mode for
ton
EN Reset button.
But-
ton
GPIO This header provides six unpopulated through-hole solder pads connected to spare GPIOs of ESP32. For
Espressif Systemssee GPIO Header 1.
Header details, 49 Release v5.0-dev-401-g451ce8a
1 Submit Document Feedback
Note: Automatic firmware download is supported. If following steps and using software described in Section Start
Application Development, users don t need to do any operation with BOOT button or EN button.
PoE Board (B) This board coverts power delivered over the Ethernet cable (PoE) to provide a power supply for the
Ethernet board (A). The main components of the PoE board (B) are shown on the block diagram under Functionality
Overview.
The PoE board (B) has the following features:
• Support for IEEE 802.3at
• Power output: 5 V, 1.4 A
To take advantage of the PoE functionality the RJ45 Port of the Ethernet board (A) should be connected with an
Ethernet cable to a switch that supports PoE. When the Ethernet board (A) detects 5 V power output from the PoE
board (B), the USB power will be automatically cut off.
Fig. 25: ESP32-Ethernet-Kit - PoE board (B) layout (click to enlarge)
Table 1: Table PoE board (B)

Board A Connector Four female (left) and four male (right) header pins for connecting the PoE board (B) to
Ethernet board (A). The pins on the left accept power coming from a PoE switch. The
pins on the right deliver 5 V power supply to the Ethernet board (A).
External Power Ter- Optional power supply (26.6 ~ 54 V) to the PoE board (B).
minals
Setup Options
This section describes options to configure the ESP32-Ethernet-Kit hardware.
Function Switch When in On position, this DIP switch is routing listed GPIOs to FT2232H to provide JTAG
functionality. When in Off position, the GPIOs may be used for other purposes.
DIP SW GPIO Pin

1 GPIO13
2 GPIO12
3 GPIO15
4 GPIO14
RMII Clock Selection The ethernet MAC and PHY under RMII working mode need a common 50 MHz refer-
ence clock (i.e. RMII clock) that can be provided either externally, or generated from internal ESP32 APLL (not
recommended).

Note: For additional information on the RMII clock selection, please refer to ESP32-Ethernet-Kit V1.2 Ethernet
board (A) schematic, sheet 2, location D2.
RMII Clock Sourced Externally by PHY By default, the ESP32-Ethernet-Kit is configured to provide RMII
clock for the IP101GRI PHY s 50M_CLKO output. The clock signal is generated by the frequency multiplication
of 25 MHz crystal connected to the PHY. For details, please see the figure below.
Fig. 26: RMII Clock from IP101GRI PHY
Please note that the PHY is reset on power up by pulling the RESET_N signal down with a resistor. ESP32 should
assert RESET_N high with GPIO5 to enable PHY. Only this can ensure the power-up of system. Otherwise ESP32
may enter download mode (when the clock signal of REF_CLK_50M is at a high logic level during the GPIO0
power-up sampling phase).
RMII Clock Sourced Internally from ESP32 s APLL Another option is to source the RMII Clock from internal
ESP32 APLL, see figure below. The clock signal coming from GPIO0 is first inverted, to account for transmission
line delay, and then supplied to the PHY.
To implement this option, users need to remove or add some RC components on the board. For details please refer
to ESP32-Ethernet-Kit V1.2 Ethernet board (A) schematic, sheet 2, location D2. Please note that if the APLL is
already used for other purposes (e.g. I2S peripheral), then you have no choice but use an external RMII clock.

Fig. 27: RMII Clock from ESP Internal APLL

GPIO Allocation
This section describes allocation of ESP32 GPIOs to specific interfaces or functions of the ESP32-Ethernet-Kit.
IP101GRI (PHY) Interface The allocation of the ESP32 (MAC) pins to IP101GRI (PHY) is shown in the table
below. Implementation of ESP32-Ethernet-Kit defaults to Reduced Media-Independent Interface (RMII).
No. ESP32 Pin (MAC) IP101GRI (PHY)

RMII Interface
1 GPIO21 TX_EN
2 GPIO19 TXD[0]
3 GPIO22 TXD[1]
4 GPIO25 RXD[0]
5 GPIO26 RXD[1]
6 GPIO27 CRS_DV
7 GPIO0 REF_CLK
Serial Management Interface
8 GPIO23 MDC
9 GPIO18 MDIO
PHY Reset
10 GPIO5 Reset_N
Note: The allocation of all pins under the ESP32 s RMII Interface is fixed and cannot be changed either through IO
MUX or GPIO Matrix. REF_CLK can only be selected from GPIO0, GPIO16 or GPIO17 and it can not be changed
through GPIO Matrix.
GPIO Header 1 This header exposes some GPIOs that are not used elsewhere on the ESP32-Ethernet-Kit.
No. ESP32 Pin

1 GPIO32
2 GPIO33
3 GPIO34
4 GPIO35
5 GPIO36
6 GPIO39
GPIO Header 2 This header contains GPIOs that may be used for other purposes depending on scenarios described
in column Comments .
No. ESP32 Pin Comments

1 GPIO17 See note 1
2 GPIO16 See note 1
3 GPIO4
4 GPIO2
5 GPIO13 See note 2
6 GPIO12 See note 2
7 GPIO15 See note 2
8 GPIO14 See note 2
9 GND Ground
10 3V3 3.3 V power supply

Note:
1. The ESP32 pins GPIO16 and GPIO17 are not broken out to the ESP32-WROVER-E module and therefore
not available for use. If you need to use these pins, please solder a module without PSRAM memory inside,
e.g. the ESP32-WROOM-32D or ESP32-SOLO-1.
2. Functionality depends on the settings of the Function Switch.
GPIO Allocation Summary
ESP32-WROVER-E IP101GRI UART JTAG GPIO Comments

S_VP IO36
S_VN IO39
IO34 IO34
IO35 IO35
IO32 IO32
IO33 IO33
IO25 RXD[0]
IO26 RXD[1]
IO27 CRS_DV
IO14 TMS IO14
IO12 TDI IO12
IO13 TCK IO13
IO15 TDO IO15
IO2 IO2
IO0 REF_CLK See note 1
IO4 IO4
IO16 IO16 (NC) See note 2
IO5 Reset_N See note 1
IO18 MDIO
IO19 TXD[0]
IO21 TX_EN
RXD0 RXD
TXD0 TXD
IO22 TXD[1]
IO23 MDC
Note:
1. To prevent the power-on state of the GPIO0 from being affected by the clock output on the PHY side, the
RESET_N signal to PHY defaults to low, turning the clock output off. After power-on you can control RE-
SET_N with GPIO5 to turn the clock output on. See also RMII Clock Sourced Externally by PHY. For PHYs
that cannot turn off the clock output through RESET_N, it is recommended to use a crystal module that can be
disabled/enabled externally. Similarly like when using RESET_N, the oscillator module should be disabled by
default and turned on by ESP32 after power-up. For a reference design please see ESP32-Ethernet-Kit V1.2
Ethernet board (A) schematic.
2. The ESP32 pins GPIO16 and GPIO17 are not broken out to the ESP32-WROVER-E module and therefore

Before powering up your ESP32-Ethernet-Kit, please make sure that the board is in good condition with no obvious
signs of damage.
Initial Setup
1. Set the Function Switch on the Ethernet board (A) to its default position by turning all the switches to ON.
2. To simplify flashing and testing of the application, do not input extra signals to the board headers.
3. The PoE board (B) can now be plugged in, but do not connect external power to it.
4. Connect the Ethernet board (A) to the PC with a USB cable.
5. Turn the Power Switch from GND to 5V0 position, the 5V Power On LED should light up.
Now to Development Proceed to Get Started, where Section Installation Step by Step will quickly help you set up
the development environment and then flash an example project onto your board.
Move on to the next section only if you have successfully completed all the above steps.
Configure and Load the Ethernet Example After setting up the development environment and testing the board,
you can configure and flash the ethernet/basic example. This example has been created for testing Ethernet function-
ality. It supports different PHY, including IP101GRI installed on ESP32-Ethernet-Kit V1.2 (click to enlarge).
Summary of Changes from ESP32-Ethernet-Kit V1.1
• Correct the placement of GPIO pin number marking on the board s silkscreen besides the DIP switch.
• Values of C1, C2, C42, and C43 are updated to 20 pF. For more information, please check ESP32-Ethernet-Kit
• Replace ESP32-WROVER-B with ESP32-WROVER-E.
Other Versions of ESP32-Ethernet-Kit
• ESP32-Ethernet-Kit V1.0 Getting Started Guide

Related Documents
• ESP32-Ethernet-Kit V1.2 Ethernet Board (A) Schematic (PDF)

• ESP32-Ethernet-Kit PoE Board (B) Schematic (PDF)
• ESP32-Ethernet-Kit V1.2 Ethernet Board (A) PCB Layout (PDF)
• ESP32-Ethernet-Kit PoE Board (B) PCB Layout (PDF)
• ESP32-WROVER-E Datasheet (PDF)
• JTAG Debugging
For other design documentation for the board, please contact us at [email protected].
ESP32-Ethernet-Kit V1.0 Getting Started Guide This guide shows how to get started with the ESP32-Ethernet-
Kit development board and also provides information about its functionality and configuration options.

What You Need

Overview ESP32-Ethernet-Kit is an ESP32-based development board produced by Espressif.

It consists of two development boards, the Ethernet board A and the PoE board B, The Ethernet board (A) con-
tains Bluetooth / Wi-Fi dual-mode ESP32-WROVER-B module and IP101GRI, a Single Port 10/100 Fast Ethernet
Fig. 28: ESP32-Ethernet-Kit V1.0
For the application loading and monitoring the Ethernet board (A) also features FTDI FT2232H chip - an advanced
Functionality Overview The block diagram below shows the main components of ESP32-Ethernet-Kit and their
interconnections.
Functional Description The following two figures and tables describe the key components, interfaces, and controls
of the ESP32-Ethernet-Kit.


clockwise.

Key Description
Com-
po-
nent
WROVER- ities.
B
2
Flow A jumper header with access to the board signals. For details, see Flow Control.
Con-
trol
Func- A DIP switch used to configure the functionality of selected GPIOs of ESP32. For details, see Function
tion Switch.
Switch
LEDs
GPIO Provides access to some GPIOs of ESP32 that can be used depending on the position of the Function
Header Switch.
3
Port and the board.
Power Power On/Off Switch. Toggling toward the Boot button powers the board on, toggling away from Boot
put
Power
On
LED
DC/DC Provided DC 5 V to 3.3 V conversion, output current up to 2A.
Con-
verter
Board A pair male header pins for mounting the PoE board (B).
B
Con-
nec-
tors
a variant of the media-independent interface (MII) standard. The PHY supports the IEEE 802.3 / 802.3u
standard of 10/100Mbps.
Port
Mod-
ule
Link/Activity
LEDs
BOOT Download button. Holding down BOOT and then pressing CH_PU initiates Firmware Download mode
Espressif
But- for Systems
downloading firmware through the serial port.59 Release v5.0-dev-401-g451ce8a
ton Submit Document Feedback
CH_PUReset button.
But-
Overview.

Board A Connector Four female header pins for mounting this board onto Ethernet board (A).
External Power Terminals Optional power supply to the PoE board (B).
Setup Options This section describes options to configure the ESP32-Ethernet-Kit hardware.
Function Switch The functions for specific GPIO pins can be selected with the Function Switch.
DIP SW GPIO Pin Pin Functionality if DIP SW is ON

1 GPIO14 Connected to FT2232H to provide JTAG functionality
6 GPIO2 Connected to on-board 25 MHz oscillator
7 GPIO5 Connected to RESET_N input of IP101GRI
8 n/a
You can make a certain GPIO pin available for other purposes by putting its DIP SW to the Off position.
Flow Control This is a 2 x 2 jumper pin header intended for the UART flow control.
. Signal Comment
1 MTDO GPIO13, see also Function Switch
2 MTCK GPIO15, see also Function Switch
3 RTS RTS signal of FT2232H
4 CTS CTS signal of FT2232H
GPIO Allocation This section describes allocation of ESP32 GPIOs to specific interfaces or functions of the
ESP32-Ethernet-Kit.

. ESP32 Pin (MAC) IP101GRI (PHY)

RMII Interface
1 GPIO21 TX_EN
2 GPIO19 TXD[0]
3 GPIO22 TXD[1]
4 GPIO25 RXD[0]
5 GPIO26 RXD[1]
6 GPIO27 CRS_DV
7 GPIO0 REF_CLK
8 GPIO23 MDC
9 GPIO18 MDIO
PHY Reset
10 GPIO5 Reset_N
Note: Except for REF_CLK, the allocation of all pins under the RMII Interface is fixed and cannot be changed either
through IOMUX or GPIO Matrix.
. ESP32 Pin
1 GPIO32
2 GPIO33
3 GPIO34
4 GPIO35
5 GPIO36
6 GPIO39
GPIO Header 2 This header contains the GPIOs with specific MII functionality (except GPIO2), as opposed to
Reduced Media-Independent Interface (RMII) functionality implemented on ESP32-Ethernet-Kit board by default,
see IP101GRI (PHY) Interface. Depending on the situation, if MMI is used, specific Ethernet applications might
require this functionality.
. ESP32 Pin MII Function Comments

1 GPIO17 EMAC_CLK_180 See note 1
2 GPIO16 EMAC_CLK_OUT See note 1
3 GPIO4 EMAC_TX_ER
4 GPIO2 n/a See note 2
5 GPIO5 EMAC_RX_CLK See note 2
Note:
1. The ESP32 pins GPIO16 and GPIO17 are not broken out to the ESP32-WROVER-B module and therefore
not available for use. If you need to use these pins, please solder a module without SPIRAM memory inside,

GPIO Header 3 The functionality of GPIOs connected to this header depends on the settings of the Function
Switch.
. ESP32 Pin
1 GPIO15
2 GPIO13
3 GPIO12
4 GPIO14
5 GND
6 3V3
ESP32-WROVER-B IP101GRI UART JTAG GPIO Comments

S_VP IO36
S_VN IO39
IO34 IO34
IO35 IO35
IO32 IO32
IO33 IO33
IO25 RXD[0]
IO26 RXD[1]
IO27 CRS_DV
IO14 TMS IO14
IO12 TDI IO12
IO13 RTS TCK IO13
IO15 CTS TDO IO15
IO2 IO2 See notes 1 and 3 below
IO0 REF_CLK See notes 2 and 3 below
IO4 nTRST IO4
IO16 IO16 (NC) See note 4 below
IO17 IO17 (NC) See note 4 below
IO5 Reset_N IO5
IO18 MDIO
IO19 TXD[0]
IO21 TX_EN
RXD0 RXD
TXD0 TXD
IO22 TXD[1]
IO23 MDC
Note:
1. GPIO2 is used to enable external oscillator of the PHY.
2. GPIO0 is a source of 50 MHz reference clock for the PHY. The clock signal is first inverted, to account for
transmission line delay, and then supplied to the PHY.
3. To prevent affecting the power-on state of GPIO0 by the clock output on the PHY side, the PHY external
oscillator is enabled using GPIO2 after ESP32 is powered up.
not available for use. If you need to use these pins, please solder a module without SPIRAM memory inside,
Start Application Development Before powering up your ESP32-Ethernet-Kit, please make sure that the board

Initial Setup
2. To simplify flashing and testing the application, do not install any jumpers and do not connect any signals to
the board headers.
ality. It supports different PHY, including IP101GRI installed on ESP32-Ethernet-Kit V1.0 board.
Related Documents
• ESP32-Ethernet-Kit V1.0 Ethernet board (A) schematic (PDF)
• ESP32-Ethernet-Kit V1.0 PoE board (B) schematic (PDF)
• JTAG Debugging
ESP32-Ethernet-Kit V1.1 Getting Started Guide This guide shows how to get started with the ESP32-Ethernet-
Kit development board and also provides information about its functionality and configuration options.
What You Need

Overview ESP32-Ethernet-Kit is an ESP32-based development board produced by Espressif.

It consists of two development boards, the Ethernet board A and the PoE board B. The Ethernet board (A) con-
tains Bluetooth / Wi-Fi dual-mode ESP32-WROVER-B module and IP101GRI, a Single Port 10/100 Fast Ethernet
For the application loading and monitoring, the Ethernet board (A) also features FTDI FT2232H chip - an advanced
Functionality Overview The block diagram below shows the main components of ESP32-Ethernet-Kit and their
interconnections.

Fig. 32: ESP32-Ethernet-Kit V1.1

Functional Description The following figures and tables describe the key components, interfaces, and controls of
the ESP32-Ethernet-Kit.
clockwise.

Key Description
Com-
po-
nent
WROVER- ities.
B
2
Func- A 4-bit DIP switch used to configure the functionality of selected GPIOs of ESP32. Please note that
tion placement of GPIO pin number marking on the board s silkscreen besides the DIP switch is incorrect.
Switch For details and correct pin allocation see Function Switch.
LEDs
Port and the board.
Power Power On/Off Switch. Toggling the switch to 5V0 position powers the board on, toggling to GND position
put
Power
On
LED
DC/DC Provided DC 5 V to 3.3 V conversion, output current up to 2A.
Con-
verter
Board A pair male and female header pins for mounting the PoE board (B).
B
Con-
nec-
tors
a variant of the media-independent interface (MII) standard. The PHY supports the IEEE 802.3 / 802.3u
standard of 10/100Mbps.
Port
Mod-
ule
Link/Activity
LEDs
BOOT Download button. Holding down BOOT and then pressing EN initiates Firmware Download mode for
ton
EN Reset button.
But-
ton
GPIO This header provides six unpopulated through-hole solder pads connected to spare GPIOs of ESP32. For
Espressif Systemssee GPIO Header 1.
Header details, 66 Release v5.0-dev-401-g451ce8a
1 Submit Document Feedback
Overview.
Table 2: Table PoE board (B)

Board A Connector Four female (left) and four male (right) header pins for connecting the PoE board (B) to
Ethernet board (A). The pins on the left accept power coming from a PoE switch. The
pins on the right deliver 5 V power supply to the Ethernet board (A).
External Power Ter- Optional power supply (26.6 ~ 54 V) to the PoE board (B).
minals
Setup Options This section describes options to configure the ESP32-Ethernet-Kit hardware.
Function Switch When in On position, this DIP switch is routing listed GPIOs to FT2232H to provide JTAG
functionality. When in Off position, the GPIOs may be used for other purposes.
DIP SW GPIO Pin

1 GPIO13
2 GPIO12
3 GPIO15
4 GPIO14
Note: Placement of GPIO pin number marking on the board s silkscreen besides the DIP switch is incorrect.
Please use instead the pin order as in the table above.
RMII Clock Selection The ethernet MAC and PHY under RMII working mode need a common 50 MHz reference
clock (i.e. RMII clock) that can be provided either externally, or generated from internal ESP32 APLL.
Note: For additional information on the RMII clock selection, please refer to ESP32-Ethernet-Kit V1.1 Ethernet
board (A) schematic, sheet 2, location D2.

RMII Clock Sourced Externally by PHY By default, the ESP32-Ethernet-Kit is configured to provide RMII
clock for the IP101GRI PHY s 50M_CLKO output. The clock signal is generated by the frequency multiplication
of 25 MHz crystal connected to the PHY. For details, please see the figure below.
Fig. 36: RMII Clock from IP101GRI PHY
Please note that the PHY is reset on power up by pulling the RESET_N signal down with a resistor. ESP32 should
assert RESET_N high with GPIO5 to enable PHY. Only this can ensure the power-up of system. Otherwise ESP32
may enter download mode (when the clock signal of REF_CLK_50M is at a high logic level during the GPIO0
power-up sampling phase).
RMII Clock Sourced Internally from ESP32 s APLL Another option is to source the RMII Clock from internal
ESP32 APLL, see figure below. The clock signal coming from GPIO0 is first inverted, to account for transmission
line delay, and then supplied to the PHY.
To implement this option, users need to remove or add some RC components on the board. For details please refer
to ESP32-Ethernet-Kit V1.1 Ethernet board (A) schematic, sheet 2, location D2. Please note that if the APLL is
already used for other purposes (e.g. I2S peripheral), then you have no choice but use an external RMII clock.
GPIO Allocation This section describes allocation of ESP32 GPIOs to specific interfaces or functions of the
ESP32-Ethernet-Kit.

Fig. 37: RMII Clock from ESP Internal APLL

. ESP32 Pin (MAC) IP101GRI (PHY)

RMII Interface
1 GPIO21 TX_EN
2 GPIO19 TXD[0]
3 GPIO22 TXD[1]
4 GPIO25 RXD[0]
5 GPIO26 RXD[1]
6 GPIO27 CRS_DV
7 GPIO0 REF_CLK
8 GPIO23 MDC
9 GPIO18 MDIO
PHY Reset
10 GPIO5 Reset_N
Note: Except for REF_CLK, the allocation of all pins under the ESP32 s RMII Interface is fixed and cannot be
changed either through IOMUX or GPIO Matrix.
. ESP32 Pin
1 GPIO32
2 GPIO33
3 GPIO34
4 GPIO35
5 GPIO36
6 GPIO39
GPIO Header 2 This header contains GPIOs that may be used for other purposes depending on scenarios described
in column Comments .
. ESP32 Pin Comments

1 GPIO17 See note 1
2 GPIO16 See note 1
3 GPIO4
4 GPIO2
5 GPIO13 See note 2
6 GPIO12 See note 2
7 GPIO15 See note 2
8 GPIO14 See note 2
9 GND Ground
10 3V3 3.3 V power supply
Note:

ESP32-WROVER-B IP101GRI UART JTAG GPIO Comments

S_VP IO36
S_VN IO39
IO34 IO34
IO35 IO35
IO32 IO32
IO33 IO33
IO25 RXD[0]
IO26 RXD[1]
IO27 CRS_DV
IO14 TMS IO14
IO12 TDI IO12
IO13 RTS TCK IO13
IO15 CTS TDO IO15
IO2 IO2
IO0 REF_CLK See note 1
IO4 IO4
IO5 Reset_N See note 1
IO18 MDIO
IO19 TXD[0]
IO21 TX_EN
RXD0 RXD
TXD0 TXD
IO22 TXD[1]
IO23 MDC
Note:
1. To prevent the power-on state of the GPIO0 from being affected by the clock output on the PHY side, the
RESET_N signal to PHY defaults to low, turning the clock output off. After power-on you can control RE-
SET_N with GPIO5 to turn the clock output on. See also RMII Clock Sourced Externally by PHY. For PHYs
that cannot turn off the clock output through RESET_N, it is recommended to use a crystal module that can be
disabled / enabled externally. Similarly like when using RESET_N, the oscillator module should be disabled
by default and turned on by ESP32 after power-up. For a reference design please see ESP32-Ethernet-Kit
Start Application Development Before powering up your ESP32-Ethernet-Kit, please make sure that the board
Initial Setup
2. To simplify flashing and testing of the application, do not input extra signals to the board headers.

ality. It supports different PHY, including IP101GRI installed on ESP32-Ethernet-Kit V1.1.
Summary of Changes from ESP32-Ethernet-Kit V1.0

• The original inverted clock provided to the PHY by ESP32 using GPIO0 has been replaced by a clock generated
on PHY side. The PHY s clock is connected to the ESP32 with same GPIO0. The GPIO2 which was originally
used to control the active crystal oscillator on the PHY side, can now be used for other purposes.
• On power up, the ESP32 boot strapping pin GPIO0 may be affected by clock generated on the PHY side. To
resolve this issue the PHY s Reset-N signal is pulled low using resistor R17 and effectively turning off the
PHY s clock output. The Reset-N signal can be then pulled high by ESP32 using GPIO5.
• Removed FT2232H chip s external SPI Flash U6.
• Removed flow control jumper header J4.
• Removed nTRST JTAG signal. The corresponding GPIO4 can now be used for other purposes.
• Pull-up resistor R68 on the GPIO15 line is moved to the MTDO side of JTAG.
• To make the A and B board connections more foolproof (reduce chances of plugging in the B board in reverse
orientation), the original two 4-pin male rows on board A were changed to one 4-pin female row and one 4-pin
male row. Corresponding male and female 4-pins rows were installed on board B.
Other Versions of ESP32-Ethernet-Kit

Related Documents
• ESP32-Ethernet-Kit V1.1 Ethernet board (A) schematic (PDF)
• ESP32-Ethernet-Kit V1.0 PoE board (B) schematic (PDF)
• JTAG Debugging
1.3.5 ESP32-DevKitS(-R)
This user guide provides information on ESP32-DevKitS(-R), an ESP32-based flashing board produced by Espressif.
ESP32-DevKitS(-R) is a combination of two board names: ESP32-DevKitS and ESP32-DevKitS-R. S stands for
springs, and R stands for WROVER.

ESP32-DevKitS ESP32-DevKitS-R
The document consists of the following major sections:

• Getting Started: Provides an overview of ESP32-DevKitS(-R) and hardware/software setup instructions to get
started.
• Hardware Reference: Provides more detailed information about ESP32-DevKitS(-R) s hardware.
• Related Documents: Gives links to related documentation.
Getting Started
This section describes how to get started with ESP32-DevKitS(-R). It begins with a few introductory sections about
ESP32-DevKitS(-R), then Section How to Flash a Board provides instructions on how to mount a module onto
ESP32-DevKitS(-R), get it ready, and flash firmware onto it.
Overview ESP32-DevKitS(-R) is Espressif s flashing board designed specifically for ESP32. It can be used to
flash an ESP32 module without soldering the module to the power supply and signal lines. With a module mounted,
ESP32-DevKitS(-R) can also be used as a mini development board like ESP32-DevKitC.
ESP32-DevKitS and ESP32-DevKitS-R boards vary only in layout of spring pins to fit the following ESP32 modules.
• ESP32-DevKitS:
– ESP32-WROOM-32
– ESP32-WROOM-32D
– ESP32-WROOM-32U
– ESP32-SOLO-1
– ESP32-WROOM-32E
– ESP32-WROOM-32UE
• ESP32-DevKitS-R:
– ESP32-WROVER (PCB & IPEX)
– ESP32-WROVER-B (PCB & IPEX)
– ESP32-WROVER-E
– ESP32-WROVER-IE
For information about above modules, please refer to ESP32 Series Modules.
Description of Components

Fig. 38: ESP32-DevKitS - front
Fig. 39: ESP32-DevKitS-R - front


Spring Pins Click the module in. The pins will fit into the module s castellated holes.
2.54 mm Female Headers These female headers are connected to pins of the module mounted on this
board. For description of female headers, please refer to Header Blocks.
USB-to-UART Bridge Single-chip USB to UART bridge provides transfer rates of up to 3 Mbps.
LDO 5V-to-3.3V low-dropout voltage regulator (LDO).
Micro-USB Connector/Micro USB interface. Power supply for the board as well as the communication in-
USB Port terface between a computer and the board.
EN Button Reset button.
Boot Button Download button. Holding down Boot and then pressing EN initiates
Firmware Download mode for downloading firmware through the serial port.
Power On LED Turns on when the USB or power supply is connected to the board.
How to Flash a Board Before powering up your ESP32-DevKitS(-R), please make sure that it is in good condition
with no obvious signs of damage.
Required Hardware
• An ESP32 module of your choice
• USB 2.0 cable (Standard-A to Micro-B)
Hardware Setup Please mount a module of your choice onto your ESP32-DevKitS(-R) according to the following
steps:
• Gently put your module on the ESP32-DevKitS(-R) board. Make sure that castellated holes on your module
are aligned with spring pins on the board.
• Press your module down into the board until it clicks.
• Check whether all spring pins are inserted into castellated holes. If there are some misaligned spring pins,
place them into castellated holes with tweezers.
Software Setup
Preferred Method The ESP-IDF development framework provides a preferred way of flashing binaries onto
ESP32-DevKitS(-R). Please proceed to Get Started, where Section Installation Step by Step will quickly help you
set up the development environment and then flash an application example onto your ESP32-DevKitS(-R).
Alternative Method As an alternative, Windows users can flash binaries using the Flash Download Tool. Just
download it, unzip it, and follow the instructions inside the doc folder.
Note:
1. To flash binary files, ESP32 should be set to Firmware Download mode. This can be done either
by the flash tool automatically, or by holding down the Boot button and tapping the EN button.
2. After flashing binary files, the Flash Download Tool restarts your ESP32 module and boots the
flashed application by default.
Board Dimensions
Contents and Packaging

Fig. 40: ESP32-DevKitS board dimensions - back
Fig. 41: ESP32-DevKitS-R board dimensions - back

Retail orders If you order a few samples, each ESP32-DevKitS(-R) comes in an individual package in either
antistatic bag or any packaging depending on a retailer.
For retail orders, please go to https://www.espressif.com/en/company/contact/buy-a-sample.
Wholesale Orders If you order in bulk, the boards come in large cardboard boxes.
For wholesale orders, please go to https://www.espressif.com/en/contact-us/sales-questions.
Hardware Reference
Block Diagram A block diagram below shows the components of ESP32-DevKitS(-R) and their interconnections.
Fig. 42: ESP32-DevKitS(-R) (click to enlarge)
• 5V and GND header pins
• 3V3 and GND header pins
It is advised to use the first option: micro USB port.
. Label Signal
L1 3V3 VDD 3V3
L2 EN CHIP_PU
L3 VP SENSOR_VP
L4 VN SENSOR_VN
L5 34 GPIO34
L6 35 GPIO35
L7 32 GPIO32
L8 33 GPIO33
L9 25 GPIO25
Continued on next page

Table 3 – continued from previous page

. Label Signal
L10 26 GPIO26
L11 27 GPIO27
L12 14 GPIO14
L13 12 GPIO12
L14 GND GND
L15 13 GPIO13
L16 D2 SD_DATA2
L17 D3 SD_DATA3
L18 CMD SD_CMD
L19 5V External 5V
R1 GND GND
R2 23 GPIO23
R3 22 GPIO22
R4 TX U0TXD
R5 RX U0RXD
R6 21 GPIO21
R7 GND GND
R8 19 GPIO19
R9 18 GPIO18
R10 5 GPIO5
R11 17 GPIO17
R12 16 GPIO16
R13 4 GPIO4
R14 0 GPIO0
R15 2 GPIO2
R16 15 GPIO15
R17 D1 SD_DATA1
R18 D0 SD_DATA0
R19 CLK SD_CLK
Header Blocks For the image of header blocks, please refer to Description of Components.
Related Documents
• ESP32-DevKitS(-R) Schematics (PDF)

• ESP32-WROOM-32D & ESP32-WROOM-32U Datasheet (PDF)
• ESP32-SOLO-1 Datasheet (PDF)
1.3.6 ESP32-PICO-KIT-1
Overview
ESP32-PICO-KIT-1 is an ESP32-based development board produced by Espressif.

The core of this board is ESP32-PICO-V3 - a System-in-Package (SiP) module with complete Wi-Fi and Bluetooth
functionalities. Compared to other ESP32 modules, ESP32-PICO-V3 integrates the following peripheral components
in one single package, which otherwise would need to be installed separately:
• 40 MHz crystal oscillator

• 4 MB flash
• Filter capacitors
• RF matching network
This setup reduces the costs of additional external components as well as the cost of assembly and testing and also
increases the overall usability of the product.
The development board features a USB-to-UART Bridge circuit which allows developers to connect the board to a
All the IO signals and system power on ESP32-PICO-V3 are led out to two rows of 18 x 0.1 header pads on both
sides of the development board for easy access. For compatibility with Dupont wires, all header pads are populated
with two rows of male pin headers.
Note: ESP32-PICO-KIT-1 comes with male headers by default.
ESP32-PICO-KIT-1 provides the users with hardware for development of applications based on the ESP32, making
it easier for users to explore ESP32 functionalities.
This guide covers:
• Getting Started: Provides an overview of the ESP32-PICO-KIT-1 and software setup instructions to get started.
• Contents and Packaging: Provides information about packaging and contents for retail and wholesale orders.
• Hardware Reference: Provides more detailed information about the ESP32-PICO-KIT-1 s hardware.
• Hardware Revision Details: Covers revision history, known issues, and links to user guides for previous versions
of the ESP32-PICO-KIT-1.
Getting Started
This section describes how to get started with the ESP32-PICO-KIT-1. It begins with a few introductory sections
about the ESP32-PICO-KIT-1, then Section Start Application Development provides instructions on how to flash
firmware onto the ESP32-PICO-KIT-1.
Description of Components The following figure and the table below describe the key components, interfaces,
and controls of the ESP32-PICO-KIT-1 board.

Fig. 43: ESP32-PICO-KIT-1 Overview (click to enlarge)

Fig. 44: ESP32-PICO-KIT-1 board layout - front (click to enlarge)
Key Description
Com-
po-
nent
ESP32- Standard ESP32-PICO-V3 module soldered to the ESP32-PICO-KIT-1 board. The complete ESP32
PICO- system on a chip (ESP32 SoC) has been integrated into the SiP module, requiring only an external
V3 antenna with LC matching network, decoupling capacitors, and a pull-up resistor for EN signals to
function properly.
USB- CP2102N, single-chip USB-to-UART bridge that offers up to 3 Mbps transfers rates.
to-
UART
bridge
USB and the board.
Port
5V This red LED turns on when power is supplied to the board. For details, see the schematic in Related
Power Documents.
On
LED
I/O All the pins on ESP32-PICO-V3 are broken out to pin headers. You can program ESP32 to enable
Con- multiple functions, such as PWM, ADC, DAC, I2C, I2S, SPI, etc. For details, please see Section Pin
nector Descriptions.
Button downloading firmware through the serial port.
EN Reset button.
Button
Start Application Development Before powering up your ESP32-PICO-KIT-1, please make sure that the board
Required Hardware
• 1 x ESP32-PICO-KIT-1
• 1 x USB 2.0 A to Micro B cable

• 1 x Computer running Windows, Linux, or macOS
Software Setup Please proceed to Get Started, where Section Installation Step by Step will quickly help you set up
the development environment.
Retail Orders If you order one or several samples of the board, each ESP32-PICO-KIT-1 development board
comes in an individual package.
Hardware Reference
Block Diagram The block diagram below shows the main components of ESP32-PICO-KIT-1 and their intercon-
nections.
Fig. 45: ESP32-PICO-KIT-1 Block Diagram (click to enlarge)
• 5V/GND header pins
• 3V3/GND header pins
Pin Descriptions The two tables below provide the Name and Function of I/O header pins on both sides of the
board, see Description of Components. The pin numbering and header names are the same as in the schematic given
in Related Documents.

Header J2

1 IO20 I/O GPIO20
2 IO21 I/O GPIO21, VSPIHD, EMAC_TX_EN
3 IO22 I/O GPIO22, VSPIWP, U0RTS, EMAC_TXD1
4 IO19 I/O GPIO19, VSPIQ, U0CTS, EMAC_TXD0
5 IO8 I/O GPIO8, SD_DATA1, HS1_DATA1, U2CTS
6 IO7 I/O GPIO7, SD_DATA0, HS1_DATA0, U2RTS
7 IO5 I/O GPIO5, VSPICS0, HS1_DATA6, EMAC_RX_CLK
8 IO10 I/O GPIO10, SD_DATA3, SPIWP, HS1_DATA3, U1TXD
9 IO9 I/O GPIO9, SD_DATA2, SPIHD, HS1_DATA2, U1RXD
10 RXD0 I/O GPIO3, U0RXD (See 1), CLK_OUT2
11 TXD0 I/O GPIO1, U0TXD (See 1), CLK_OUT3, EMAC_RXD2
12 IO35 I ADC1_CH7, RTC_GPIO5
14 IO38 I GPIO38, ADC1_CH2, RTC_GPIO2
16 EN I CHIP_PU
17 GND P Ground
18 VDD33 P 3.3 V power supply
(3V3)
Header J3

1 GND P Ground
2 SENSOR_VP
I GPIO36, ADC1_CH0, RTC_GPIO0
(FSVP)
3 SENSOR_VN
(FSVN)
4 IO25 I/O GPIO25, DAC_1, ADC2_CH8, RTC_GPIO6, EMAC_RXD0
6 IO32 I/O 32K_XP (See 2a), ADC1_CH4, TOUCH9, RTC_GPIO9
7 IO33 I/O 32K_XN (See 2b), ADC1_CH5, TOUCH8, RTC_GPIO8
8 IO27 I/O GPIO27, ADC2_CH7, TOUCH7, RTC_GPIO17, EMAC_RX_DV
9 IO14 I/O ADC2_CH6, TOUCH6, RTC_GPIO16, MTMS, HSPICLK, HS2_CLK,
SD_CLK, EMAC_TXD2
10 IO12 I/O ADC2_CH5, TOUCH5, RTC_GPIO15, MTDI (See 3), HSPIQ,
HS2_DATA2, SD_DATA2, EMAC_TXD3
11 IO13 I/O ADC2_CH4, TOUCH4, RTC_GPIO14, MTCK, HSPID, HS2_DATA3,
SD_DATA3, EMAC_RX_ER
12 IO15 I/O ADC2_CH3, TOUCH3, RTC_GPIO13, MTDO, HSPICS0, HS2_CMD,
SD_CMD, EMAC_RXD3
13 IO2 I/O ADC2_CH2, TOUCH2, RTC_GPIO12, HSPIWP, HS2_DATA0,
SD_DATA0
14 IO4 I/O ADC2_CH0, TOUCH0, RTC_GPIO10, HSPIHD, HS2_DATA1,
SD_DATA1, EMAC_TX_ER
15 IO0 I/O ADC2_CH1, TOUCH1, RTC_GPIO11, CLK_OUT1, EMAC_TX_CLK
16 VDD33 P 3.3V power supply
(3V3)
17 GND P Ground
18 EXT_5V P 5V power supply
(5V)

3. The operating voltage of ESP32-PICO-KIT-1 s embedded SPI flash is 3.3 V. Therefore, the strapping pin
MTDI should be pulled down during the module power-on reset. If connected, please make sure that this pin
is not held up on reset.
Fig. 46: ESP32-PICO-KIT-1 Pin Layout(click to enlarge)
Pin Layout
Hardware Revision Details
No previous versions available.
Related Documents
• ESP32-PICO-V3 Datasheet (PDF)

• ESP32-PICO-KIT-1 Schematic (PDF)
• ESP32-PICO-KIT-1 PCB Layout (PDF)
1.3.7 ESP32-PICO-DevKitM-2
Overview
ESP32-PICO-DevKitM-2 is an ESP32-based development board produced by Espressif.

The core of this board is ESP32-PICO-MINI-02(02U) module with complete Wi-Fi and Bluetooth functionalities.
The development board features a USB-to-UART Bridge circuit which allows developers to connect the board to a
All the IO signals and system power on ESP32-PICO-MINI-02(02U) are led out to two rows of 18 x 0.1 header
pads on both sides of the development board for easy access. For compatibility with Dupont wires, all header pads
are populated with two rows of male pin headers.

Note: ESP32-PICO-DevKitM-2 comes with male headers by default.
ESP32-PICO-DevKitM-2 provides the users with hardware for development of applications based on the ESP32,
making it easier for users to explore ESP32 functionalities.
Fig. 47: ESP32-PICO-DevKitM-2 Overview (click to enlarge)
This guide covers:

• Getting Started: Provides an overview of the ESP32-PICO-DevKitM-2 and software setup instructions to get
started.
• Contents and Packaging: Provides information about packaging and contents for retail and wholesale orders.
• Hardware Reference: Provides more detailed information about the ESP32-PICO-DevKitM-2 s hardware.
• Hardware Revision Details: Covers revision history, known issues, and links to user guides for previous versions
(if any) of the ESP32-PICO-DevKitM-2.
Getting Started
This section describes how to get started with the ESP32-PICO-DevKitM-2. It begins with a few introductory sections
about the ESP32-PICO-DevKitM-2, then Section Start Application Development provides instructions on how to flash
firmware onto the ESP32-PICO-DevKitM-2.
Description of Components The following figure and the table below describe the key components, interfaces,
and controls of the ESP32-PICO-DevKitM-2 board. We take the board with a ESP32-PICO-MINI-02 module as an
example in the following sections.

Fig. 48: ESP32-PICO-DevKitM-2 board layout - front (click to enlarge)
Key Description
Compo-
nent
ESP32- Standard ESP32-PICO-MINI-02 module soldered to the ESP32-PICO-DevKitM-2 board. The com-
PICO- plete ESP32 system on a chip (ESP32 SoC) has been integrated into the module. Users can also select
MINI-02 the board with ESP32-PICO-MINI-02U soldered.
USB-to- CP2102N, single-chip USB-UART bridge that offers up to 3 Mbps transfers rates.
UART
bridge
Micro-B USB interface. Power supply for the board as well as the communication interface between a computer
USB and the board.
Port
5V This red LED turns on when power is supplied to the board. For details, see the schematic in Related
Power Documents.
On LED
I/O Con- All the pins on ESP32-PICO-MINI-02 are broken out to pin headers. You can program ESP32 to
nector enable multiple functions, such as PWM, ADC, DAC, I2C, I2S, SPI, etc. For details, please see
Section Pin Descriptions.
Button downloading firmware through the serial port.
EN But- Reset button.
ton
Start Application Development Before powering up your ESP32-PICO-DevKitM-2, please make sure that the
board is in good condition with no obvious signs of damage.
Required Hardware
• 1 x ESP32-PICO-DevKitM-2
• 1 x USB 2.0 A to Micro B cable
• 1 x Computer running Windows, Linux, or macOS

the development environment.
Retail Orders If you order one or several samples of the board, each ESP32-PICO-DevKitM-2 development board
comes in an individual package.
Hardware Reference
Block Diagram The block diagram below shows the main components of ESP32-PICO-DevKitM-2 and their
interconnections.
Fig. 49: ESP32-PICO-DevKitM-2 Block Diagram (click to enlarge)
• 5V/GND header pins
• 3V3/GND header pins
Pin Descriptions The two tables below provide the Name and Function of I/O header pins on both sides of the
board, see Description of Components. The pin numbering and header names are the same as in the schematic given
in Related Documents.

Header J2

1 IO20 I/O GPIO20
5 IO8 I/O GPIO8, SD_DATA1, HS1_DATA1, U2CTS
6 IO7 I/O GPIO7, SD_DATA0, HS1_DATA0, U2RTS
7 IO5 I/O GPIO5, VSPICS0, HS1_DATA6, EMAC_RX_CLK
8 NC - NC
9 NC - NC
10 RXD0 I/O GPIO3, U0RXD (See 1), CLK_OUT2
11 TXD0 I/O GPIO1, U0TXD (See 1), CLK_OUT3, EMAC_RXD2
16 EN I CHIP_PU
17 GND P Ground
18 VDD33 P 3.3 V power supply
(3V3)
Header J3

1 GND P Ground
2 SENSOR_VP
(FSVP)
3 SENSOR_VN
(FSVN)
6 IO32 I/O 32K_XP (See 2a), ADC1_CH4, TOUCH9, RTC_GPIO9
7 IO33 I/O 32K_XN (See 2b), ADC1_CH5, TOUCH8, RTC_GPIO8
9 IO14 I/O ADC2_CH6, TOUCH6, RTC_GPIO16, MTMS, HSPICLK, HS2_CLK,
SD_CLK, EMAC_TXD2
10 IO12 I/O ADC2_CH5, TOUCH5, RTC_GPIO15, MTDI (See 3), HSPIQ,
11 IO13 I/O ADC2_CH4, TOUCH4, RTC_GPIO14, MTCK, HSPID, HS2_DATA3,
SD_DATA3, EMAC_RX_ER
12 IO15 I/O ADC2_CH3, TOUCH3, RTC_GPIO13, MTDO, HSPICS0, HS2_CMD,
SD_CMD, EMAC_RXD3
13 IO2 I/O ADC2_CH2, TOUCH2, RTC_GPIO12, HSPIWP, HS2_DATA0,
SD_DATA0
14 IO4 I/O ADC2_CH0, TOUCH0, RTC_GPIO10, HSPIHD, HS2_DATA1,
SD_DATA1, EMAC_TX_ER
15 IO0 I/O ADC2_CH1, TOUCH1, RTC_GPIO11, CLK_OUT1, EMAC_TX_CLK
16 VDD33 P 3.3V power supply
(3V3)
17 GND P Ground
18 EXT_5V P 5V power supply
(5V)

3. The operating voltage of ESP32-PICO-DevKitM-2 s embedded SPI flash is 3.3 V. Therefore, the strapping
pin MTDI should be pulled down during the module power-on reset. If connected, please make sure that this
pin is not held up on reset.
Fig. 50: ESP32-PICO-DevKitM-2 Pin Layout (click to enlarge)
Pin Layout
Related Documents
• ESP32-PICO-MINI-02 & ESP32-PICO-MINI-1U Datasheet (PDF)

• ESP32-PICO-DevKitM-2 Schematic (PDF)
• ESP32-PICO-DevKitM-2 PCB Layout (PDF)
1.3.8 ESP32-DevKitM-1
This user guide will help you get started with ESP32-DevKitM-1 and will also provide more in-depth information.
ESP32-DevKitM-1 is an ESP32-MINI-1(1U)-based development board produced by Espressif. Most of the I/O pins
are broken out to the pin headers on both sides for easy interfacing. Users can either connect peripherals with jumper
wires or mount ESP32-DevKitM-1 on a breadboard.

ESP32-DevKitM-1 - front ESP32-DevKitM-1 - isometric
The document consists of the following major sections:

• Getting started: Provides an overview of the ESP32-DevKitM-1 and hardware/software setup instructions to
get started.
• Hardware reference: Provides more detailed information about the ESP32-DevKitM-1 s hardware.
• Related Documents: Gives links to related documentaiton.
Getting Started
This section describes how to get started with ESP32-DevKitM-1. It begins with a few introductory sections about
the ESP32-DevKitM-1, then Section Start Application Development provides instructions on how to do the initial
hardware setup and then how to flash firmware onto the ESP32-DevKitM-1.
Overview This is a small and convenient development board that features:

• ESP32-MINI-1, or ESP32-MINI-1U module
• USB-to-serial programming interface that also provides power supply for the board
• pin headers
• pushbuttons for reset and activation of Firmware Download mode
• a few other components
Retail orders If you order a few samples, each ESP32-DevKitM-1 comes in an individual package in either anti-
static bag or any packaging depending on your retailer.
Description of Components The following figure and the table below describe the key components, interfaces and
controls of the ESP32-DevKitM-1 board. We take the board with a ESP32-MINI-1 module as an example in the
following sections.

Fig. 51: ESP32-DevKitM-1 - front

On-board module ESP32-MINI-1 module or ESP32-MINI-1U module. ESP32-MINI-1 comes with an
on-board PCB antenna. ESP32-MINI-1U comes with an external antenna connector.
The two modules both have a 4 MB flash in chip package. For details, please see
ESP32-MINI-1 & ESP32-MINI-1U Datasheet.
5 V to 3.3 V LDO Power regulator converts 5 V to 3.3 V.
Boot Button Download button. Holding down Boot and then pressing Reset initiates Firmware
Reset Button Reset Button
Micro-USB Port USB interface. Power supply for the board as well as the communication interface
between a computer and the ESP32 chip.
USB-to-UART Bridge Single USB-UART bridge chip provides transfer rates up to 3 Mbps.
3.3 V Power On LED Turns on when the USB is connected to the board. For details, please see the
schematics in Related Documents.
I/O Connector All available GPIO pins (except for the SPI bus for flash) are broken out to the pin
headers on the board. Users can program ESP32 chip to enable multiple functions.
Start Application Development Before powering up your ESP32-DevKitM-1, please make sure that it is in good
condition with no obvious signs of damage.
Required Hardware
• ESP32-DevKitM-1
• USB 2.0 cable (Standard-A to Micro-B)
the development environment and then flash an application example onto your ESP32-DevKitM-1.

Attention: ESP32-DevKitM-1 is a board with a single core module, please enable single core mode (CON-
FIG_FREERTOS_UNICORE) in menuconfig before flashing your applications.
Hardware Reference
Block Diagram A block diagram below shows the components of ESP32-DevKitM-1 and their interconnections.
Fig. 52: ESP32-DevKitM-1
Power Source Select There are three mutually exclusive ways to provide power to the board:
• 5V and GND header pins
• 3V3 and GND header pins
Warning:
• The power supply must be provided using one and only one of the options above, otherwise the board
and/or the power supply source can be damaged.
• Power supply by micro USB port is recommended.
Pin Descriptions The table below provides the Name and Function of pins on both sides of the board. For pe-
ripheral pin configurations, please refer to ESP32 Datasheet.

1 GND P Ground
2 3V3 P 3.3 V power supply
3 I36 I GPIO36, ADC1_CH0, RTC_GPIO0


7 RST I Reset; High: enable; Low: powers off
10 IO32 I/O GPIO32, XTAL_32K_P (32.768 kHz crystal oscillator input),
ADC1_CH4, TOUCH9, RTC_GPIO9
11 IO33 I/O GPIO33, XTAL_32K_N (32.768 kHz crystal oscillator output),
ADC1_CH5, TOUCH8, RTC_GPIO8
15 IO14 I/O GPIO14, ADC2_CH6, TOUCH6, RTC_GPIO16, MTMS, HSPICLK,
HS2_CLK, SD_CLK, EMAC_TXD2
16 5V P 5 V power supply
17 IO12 I/O GPIO12, ADC2_CH5, TOUCH5, RTC_GPIO15, MTDI, HSPIQ,
18 IO13 I/O GPIO13, ADC2_CH4, TOUCH4, RTC_GPIO14, MTCK, HSPID,
HS2_DATA3, SD_DATA3, EMAC_RX_ER
19 IO15 I/O GPIO15, ADC2_CH3, TOUCH3, RTC_GPIO13, MTDO, HSPICS0,
HS2_CMD, SD_CMD, EMAC_RXD3
20 IO2 I/O GPIO2, ADC2_CH2, TOUCH2, RTC_GPIO12, HSPIWP,
HS2_DATA0, SD_DATA0
21 IO0 I/O GPIO0, ADC2_CH1, TOUCH1, RTC_GPIO11, CLK_OUT1,
EMAC_TX_CLK
22 IO4 I/O GPIO4, ADC2_CH0, TOUCH0, RTC_GPIO10, HSPIHD,
HS2_DATA1, SD_DATA1, EMAC_TX_ER
23 IO9 I/O GPIO9, HS1_DATA2, U1RXD, SD_DATA2
24 IO10 I/O GPIO10, HS1_DATA3, U1TXD, SD_DATA3
25 IO5 I/O GPIO5, HS1_DATA6, VSPICS0, EMAC_RX_CLK
26 IO18 I/O GPIO18, HS1_DATA7, VSPICLK
27 IO23 I/O GPIO23, HS1_STROBE, VSPID
31 TXD0 I/O GPIO1, U0TXD, CLK_OUT3, EMAC_RXD2
32 RXD0 I/O GPIO3, U0RXD, CLK_OUT2
Related Documents
• ESP32-MINI-1 & ESP32-MINI-1U Datasheet (PDF)

• ESP32-DevKitM-1 Schematics (PDF)
• ESP32-DevKitM-1 PCB layout (PDF)
• ESP32-DevKitM-1 layout (DXF) - You can view it with Autodesk Viewer online

1.4 Installation Step by Step

This is a detailed roadmap to walk you through the installation process.
1.4.1 Setting up Development Environment
• Step 1. Install prerequisites for Windows, Linux, or macOS

• Step 2. Get ESP-IDF
• Step 3. Set up the tools
• Step 4. Set up the environment variables
1.4.2 Creating Your First Project
• Step 5. Start a Project

• Step 6. Connect Your Device
• Step 7. Configure
• Step 8. Build the Project
• Step 9. Flash onto the Device
• Step 10. Monitor
1.5 Step 1. Install prerequisites

Some tools need to be installed on the computer before proceeding to the next steps. Follow the links below for the
instructions for your OS:
1.5.1 Standard Setup of Toolchain for Windows
Introduction
ESP-IDF requires some prerequisite tools to be installed so you can build firmware for supported chips. The prereq-
uisite tools include Python, Git, cross-compilers, CMake and Ninja build tools.
For this Getting Started we re going to use the Command Prompt, but after ESP-IDF is installed you can use Eclipse
or another graphical IDE with CMake support instead.
Note: Limitations: - The installation path of ESP-IDF and ESP-IDF Tools must not be longer than 90 characters.
Too long installation paths might result in a failed build. - The installation path of Python or ESP-IDF must not contain
white spaces or parentheses. - The installation path of Python or ESP-IDF should not contain special characters (non-
ASCII) unless the operating system is configured with Unicode UTF-8 support.
System Administrator can enable the support via Control Panel - Change date, time, or number formats - Adminis-
trative tab - Change system locale - check the option Beta: Use Unicode UTF-8 for worldwide language support
- Ok and reboot the computer.
ESP-IDF Tools Installer
The easiest way to install ESP-IDF s prerequisites is to download one of ESP-IDF Tools Installers from this URL:
https://dl.espressif.com/dl/esp-idf/?idf=4.4

What is the usecase for Online and Offline Installer Online Installer is very small and allows the installation of all
available releases of ESP-IDF. The installer will download only necessary dependencies including Git For Windows
during the installation process. The installer stores downloaded files in the cache directory %userprofile%\.
espressif
Offline Installer does not require any network connection. The installer contains all required dependencies including
Git For Windows .
Components of the installation The installer deploys the following components:

• Embedded Python
• Cross-compilers
• OpenOCD
• CMake and Ninja build tools
• ESP-IDF
The installer also allows reusing the existing directory with ESP-IDF. The recommended directory is %userpro-
file%\Desktop\esp-idf where %userprofile% is your home directory.
Launching ESP-IDF Environment At the end of the installation process you can check out option Run ESP-
IDF PowerShell Environment or Run ESP-IDF Command Prompt (cmd.exe). The installer will
launch ESP-IDF environment in selected prompt.
Run ESP-IDF PowerShell Environment:
Fig. 53: Completing the ESP-IDF Tools Setup Wizard with Run ESP-IDF PowerShell Environment
Run ESP-IDF Command Prompt (cmd.exe):

Fig. 54: ESP-IDF PowerShell
Fig. 55: Completing the ESP-IDF Tools Setup Wizard with Run ESP-IDF Command Prompt (cmd.exe)

Fig. 56: ESP-IDF Command Prompt

Using the Command Prompt
For the remaining Getting Started steps, we re going to use the Windows Command Prompt.
ESP-IDF Tools Installer also creates a shortcut in the Start menu to launch the ESP-IDF Command Prompt. This
shortcut launches the Command Prompt (cmd.exe) and runs export.bat script to set up the environment variables
(PATH, IDF_PATH and others). Inside this command prompt, all the installed tools are available.
Note that this shortcut is specific to the ESP-IDF directory selected in the ESP-IDF Tools Installer. If you have
multiple ESP-IDF directories on the computer (for example, to work with different versions of ESP-IDF), you have
two options to use them:
1. Create a copy of the shortcut created by the ESP-IDF Tools Installer, and change the working directory of the
new shortcut to the ESP-IDF directory you wish to use.
2. Alternatively, run cmd.exe, then change to the ESP-IDF directory you wish to use, and run export.bat.
Note that unlike the previous option, this way requires Python and Git to be present in PATH. If you get errors
related to Python or Git not being found, use the first option.
Next Steps
If the ESP-IDF Tools Installer has finished successfully, then the development environment setup is complete. Pro-
ceed directly to Step 5. Start a Project.
Related Documents
For advanced users who want to customize the install process:
Updating ESP-IDF tools on Windows
Install ESP-IDF tools using a script From the Windows Command Prompt, change to the directory where ESP-
IDF is installed. Then run:
install.bat
For Powershell, change to the directory where ESP-IDF is installed. Then run:
install.ps1
This will download and install the tools necessary to use ESP-IDF. If the specific version of the tool is already
installed, no action will be taken. The tools are downloaded and installed into a directory specified during ESP-IDF
Tools Installer process. By default, this is C:\Users\username\.espressif.
Add ESP-IDF tools to PATH using an export script ESP-IDF tools installer creates a Start menu shortcut for
ESP-IDF Command Prompt . This shortcut opens a Command Prompt window where all the tools are already
available.
In some cases, you may want to work with ESP-IDF in a Command Prompt window which wasn t started using that
shortcut. If this is the case, follow the instructions below to add ESP-IDF tools to PATH.
In the command prompt where you need to use ESP-IDF, change to the directory where ESP-IDF is installed, then
execute export.bat:
cd %userprofile%\esp\esp-idf
export.bat
Alternatively in the Powershell where you need to use ESP-IDF, change to the directory where ESP-IDF is installed,
then execute export.ps1:

cd ~/esp/esp-idf
export.ps1
When this is done, the tools will be available in this command prompt.
1.5.2 Standard Setup of Toolchain for Linux
Install Prerequisites
To compile with ESP-IDF you need to get the following packages. The command to run depends on which distribution
of Linux you are using:
• Ubuntu and Debian:
sudo apt-get install git wget flex bison gperf python3 python3-pip python3-
,→setuptools cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.
,→0-0
• CentOS 7 & 8:
sudo yum -y update && sudo yum install git wget flex bison gperf python3␣
,→python3-pip python3-setuptools cmake ninja-build ccache dfu-util libusbx
CentOS 7 is still supported but CentOS version 8 is recommended for a better user experience.
• Arch:
sudo pacman -S --needed gcc git make flex bison gperf python-pip cmake ninja␣
,→ccache dfu-util libusb
Note:
• CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating,
enabling of a backports repository, or installing of a cmake3 package rather than cmake .
• If you do not see your Linux distribution in the above list then please check its documentation to find out which
command to use for package installation.
Additional Tips
Permission issues /dev/ttyUSB0 With some Linux distributions you may get the Failed to open port
/dev/ttyUSB0 error message when flashing the ESP32. This can be solved by adding the current user to the dialout
group.
Python compatibility
ESP-IDF supports Python 3.6 or newer. It is recommended to upgrade your operating system to a recent version
satisfying this requirement. Other options include the installation of Python from sources or the use of a Python
version management system such as pyenv.
Next Steps
To carry on with development environment setup, proceed to Step 2. Get ESP-IDF.

1.5.3 Standard Setup of Toolchain for Mac OS
ESP-IDF will use the version of Python installed by default on macOS.

• install pip:
sudo easy_install pip
• install CMake & Ninja build:

– If you have HomeBrew, you can run:
brew install cmake ninja dfu-util
– If you have MacPorts, you can run:
sudo port install cmake ninja dfu-util
– Otherwise, consult the CMake and Ninja home pages for macOS installation downloads.
• It is strongly recommended to also install ccache for faster builds. If you have HomeBrew, this can be done
via brew install ccache or sudo port install ccache on MacPorts.
Note: If an error like this is shown during any step:
xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools),␣

,→missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun
Then you will need to install the XCode command line tools to continue. You can install these by running xcode-
select --install.
Installing Python 3 Basing on macOS Catalina 10.15 release notes, use of Python 2.7 is not recommended and
Python 2.7 will not be included by default in future versions of macOS. Check what Python you currently have:
python --version
If the output is like Python 2.7.17, your default interpreter is Python 2.7. If so, also check if Python 3 isn t
already installed on your computer:
python3 --version
If above command returns an error, it means Python 3 is not installed.

Below is an overview of steps to install Python 3.
• Installing with HomeBrew can be done as follows:
brew install python3
• If you have MacPorts, you can run:
sudo port install python38
Next Steps
To carry on with development environment setup, proceed to Step 2. Get ESP-IDF.

Windows Linux Mac OS
Note: This guide uses the directory ~/esp on Linux and macOS or %userprofile%\esp on Windows as
an installation folder for ESP-IDF. You can use any directory, but you will need to adjust paths for the commands
respectively. Keep in mind that ESP-IDF does not support spaces in paths.
1.6 Step 2. Get ESP-IDF

To build applications for the ESP32, you need the software libraries provided by Espressif in ESP-IDF repository.
To get ESP-IDF, navigate to your installation directory and clone the repository with git clone, following in-
structions below specific to your operating system.
1.6.1 Linux and macOS
Open Terminal, and run the following commands:
mkdir -p ~/esp
cd ~/esp
git clone --recursive https://github.com/espressif/esp-idf.git
ESP-IDF will be downloaded into ~/esp/esp-idf.

Consult ESP-IDF Versions for information about which ESP-IDF version to use in a given situation.
1.6.2 Windows
In addition to installing the tools, ESP-IDF Tools Installer for Windows introduced in Step 1 can also download a copy
of ESP-IDF.
If you wish to download ESP-IDF without the help of ESP-IDF Tools Installer, refer to these instructions.
1.7 Step 3. Set up the tools

Aside from the ESP-IDF, you also need to install the tools used by ESP-IDF, such as the compiler, debugger, Python
packages, etc.

1.7.1 Windows
ESP-IDF Tools Installer for Windows introduced in Step 1 installs all the required tools.
If you want to install the tools without the help of ESP-IDF Tools Installer, open the Command Prompt and follow
these steps:
cd %userprofile%\esp\esp-idf
install.bat esp32
or with Windows PowerShell
cd ~/esp/esp-idf
./install.ps1 esp32
cd ~/esp/esp-idf
./install.sh esp32
or with Fish shell
cd ~/esp/esp-idf
./install.fish esp32
Note: To install tools for multiple targets you can specify those targets at once. For example: ./install.sh
esp32,esp32c3,esp32s3. To install tools for all supported targets, run the script without specifying targets
./install.sh or use ./install.sh all.
1.7.3 Alternative File Downloads
The tools installer downloads a number of files attached to GitHub Releases. If accessing GitHub is slow then it is
possible to set an environment variable to prefer Espressif s download server for GitHub asset downloads.
Note: This setting only controls individual tools downloaded from GitHub releases, it doesn t change the URLs
used to access any Git repositories.
Windows
To prefer the Espressif download server when running the ESP-IDF Tools Installer, mark the Use Espressif down-
load mirror instead of GitHub in the screen Select Components section Optimization.
Linux and macOS
To prefer the Espressif download server when installing tools, use the following sequence of commands when running
install.sh:
cd ~/esp/esp-idf
export IDF_GITHUB_ASSETS="dl.espressif.com/github_assets"
./install.sh

1.7.4 Customizing the tools installation path
The scripts introduced in this step install compilation tools required by ESP-IDF inside the user home directory:
$HOME/.espressif on Linux and macOS, %USERPROFILE%\.espressif on Windows. If you wish to
install the tools into a different directory, set the environment variable IDF_TOOLS_PATH before running the
installation scripts. Make sure that your user account has sufficient permissions to read and write this path.
If changing the IDF_TOOLS_PATH, make sure it is set to the same value every time the Install script (install.
bat, install.ps1 or install.sh) and an Export script (export.bat, export.ps1 or export.sh)
are executed.
1.8 Step 4. Set up the environment variables

The installed tools are not yet added to the PATH environment variable. To make the tools usable from the command
line, some environment variables must be set. ESP-IDF provides another script which does that.
1.8.1 Windows
ESP-IDF Tools Installer for Windows creates an ESP-IDF Command Prompt shortcut in the Start Menu. This
shortcut opens the Command Prompt and sets up all the required environment variables. You can open this shortcut
and proceed to the next step.
Alternatively, if you want to use ESP-IDF in an existing Command Prompt window, you can run:
%userprofile%\esp\esp-idf\export.bat
or with Windows PowerShell
.$HOME/esp/esp-idf/export.ps1
In the terminal where you are going to use ESP-IDF, run:
. $HOME/esp/esp-idf/export.sh
or for fish (supported only since fish version 3.0.0):
. $HOME/esp/esp-idf/export.fish
Note the space between the leading dot and the path!
If you plan to use esp-idf frequently, you can create an alias for executing export.sh:
1. Copy and paste the following command to your shell s profile (.profile, .bashrc, .zprofile, etc.)
alias get_idf='. $HOME/esp/esp-idf/export.sh'
2. Refresh the configuration by restarting the terminal session or by running source [path to profile],
for example, source ~/.bashrc.
Now you can run get_idf to set up or refresh the esp-idf environment in any terminal session.
Technically, you can add export.sh to your shell s profile directly; however, it is not recommended. Doing so
activates IDF virtual environment in every terminal session (including those where IDF is not needed), defeating the
purpose of the virtual environment and likely affecting other software.

1.9 Step 5. Start a Project

Now you are ready to prepare your application for ESP32. You can start with get-started/hello_world project from
examples directory in IDF.
Copy the project get-started/hello_world to ~/esp directory:
cd ~/esp
cp -r $IDF_PATH/examples/get-started/hello_world .
1.9.2 Windows
cd %userprofile%\esp
xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world
There is a range of example projects in the examples directory in ESP-IDF. You can copy any project in the same
way as presented above and run it. It is also possible to build examples in-place, without copying them first.
Important: The ESP-IDF build system does not support spaces in the paths to either ESP-IDF or to projects.
1.10 Step 6. Connect Your Device

Now connect your ESP32 board to the computer and check under what serial port the board is visible.
Serial ports have the following patterns in their names:
• Windows: names like COM1
• Linux: starting with /dev/tty
• macOS: starting with /dev/cu.
If you are not sure how to check the serial port name, please refer to Establish Serial Connection with ESP32 for full
details.
Note: Keep the port name handy as you will need it in the next steps.
1.11 Step 7. Configure

Navigate to your hello_world directory from Step 5. Start a Project, set ESP32 chip as the target and run the
project configuration utility menuconfig.
cd ~/esp/hello_world
idf.py set-target esp32
idf.py menuconfig

1.11.2 Windows
cd %userprofile%\esp\hello_world
idf.py set-target esp32
idf.py menuconfig
Setting the target with idf.py set-target esp32 should be done once, after opening a new project. If the
project contains some existing builds and configuration, they will be cleared and initialized. The target may be saved
in environment variable to skip this step at all. See Selecting the Target for additional information.
If the previous steps have been done correctly, the following menu appears:
Fig. 57: Project configuration - Home window
You are using this menu to set up project specific variables, e.g. Wi-Fi network name and password, the processor
speed, etc. Setting up the project with menuconfig may be skipped for hello_word . This example will run with
default configuration.
Attention: If you use ESP32-DevKitC board with the ESP32-SOLO-1 module, or ESP32-DevKitM-1 board
with the ESP32-MIN1-1(1U) module, enable single core mode (CONFIG_FREERTOS_UNICORE) in menuconfig
before flashing examples.
Note: The colors of the menu could be different in your terminal. You can change the appearance with the option
--style. Please run idf.py menuconfig --help for further information.
1.12 Step 8. Build the Project

Build the project by running:
idf.py build
This command will compile the application and all ESP-IDF components, then it will generate the bootloader, par-
tition table, and application binaries.

$ idf.py build
Running cmake in directory /path/to/hello_world/build
Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
Warn about uninitialized values.
-- Found Git: /usr/bin/git (found version "2.17.0")
-- Building empty aws_iot component due to configuration
-- Component names: ...
-- Component paths: ...
... (more lines of build system output)
[527/527] Generating hello_world.bin

esptool.py v2.3.1
Project build complete. To flash, run this command:

../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash -
,→-flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello_world.
,→bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/

,→partition-table.bin
or run 'idf.py -p PORT flash'
If there are no errors, the build will finish by generating the firmware binary .bin files.
1.13 Step 9. Flash onto the Device

Flash the binaries that you just built (bootloader.bin, partition-table.bin and hello_world.bin) onto your ESP32 board
by running:
idf.py -p PORT [-b BAUD] flash
Replace PORT with your ESP32 board s serial port name from Step 6. Connect Your Device.
You can also change the flasher baud rate by replacing BAUD with the baud rate you need. The default baud rate is
460800.
For more information on idf.py arguments, see idf.py.
Note: The option flash automatically builds and flashes the project, so running idf.py build is not necessary.
1.13.1 Encountered Issues While Flashing?
If you run the given command and see errors such as Failed to connect , there might be several reasons for this.
One of the reasons might be issues encountered by esptool.py, the utility that is called by the build system to
reset the chip, interact with the ROM bootloader, and flash firmware. One simple solution to try is manual reset
described below, and if it does not help you can find more details about possible issues in Troubleshooting.
esptool.py resets ESP32 automatically by asserting DTR and RTS control lines of the USB to serial converter
chip, i.e., FTDI or CP210x (for more information, see Establish Serial Connection with ESP32). The DTR and RTS
control lines are in turn connected to GPIO0 and CHIP_PU (EN) pins of ESP32, thus changes in the voltage levels
of DTR and RTS will boot ESP32 into Firmware Download mode. As an example, check the schematic for the
ESP32 DevKitC development board.
In general, you should have no problems with the official esp-idf development boards. However, esptool.py is
not able to reset your hardware automatically in the following cases:
• Your hardware does not have the DTR and RTS lines connected to GPIO0 and CHIP_PU
• The DTR and RTS lines are configured differently
• There are no such serial control lines at all

Depending on the kind of hardware you have, it may also be possible to manually put your ESP32 board into Firmware
Download mode (reset).
• For development boards produced by Espressif, this information can be found in the respective getting started
guides or user guides. For example, to manually reset an esp-idf development board, hold down the Boot
button (GPIO0) and press the EN button (CHIP_PU).
• For other types of hardware, try pulling GPIO0 down.
1.13.2 Normal Operation
When flashing, you will see the output log similar to the following:
...
esptool.py --chip esp32 -p /dev/ttyUSB0 -b 460800 --before=default_reset --
,→after=hard_reset write_flash --flash_mode dio --flash_freq 40m --flash_size 2MB␣
,→0x8000 partition_table/partition-table.bin 0x1000 bootloader/bootloader.bin␣
,→0x10000 hello_world.bin
esptool.py v3.0-dev
Serial port /dev/ttyUSB0
Connecting........_
Chip is ESP32D0WDQ6 (revision 0)
Features: WiFi, BT, Dual Core, Coding Scheme None
Crystal is 40MHz
MAC: 24:0a:c4:05:b9:14
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
Changed.
Configuring flash size...
Compressed 3072 bytes to 103...
Writing at 0x00008000... (100 %)
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.0 seconds (effective 5962.8␣
,→kbit/s)...
Hash of data verified.

Writing at 0x00001000... (100 %)
Wrote 26096 bytes (15408 compressed) at 0x00001000 in 0.4 seconds (effective 546.7␣
,→kbit/s)...

Writing at 0x00010000... (20 %)
Writing at 0x00014000... (40 %)
Writing at 0x00018000... (60 %)
Writing at 0x0001c000... (80 %)
Writing at 0x00020000... (100 %)
Wrote 147104 bytes (77364 compressed) at 0x00010000 in 1.9 seconds (effective 615.
,→5 kbit/s)...
Leaving...
Hard resetting via RTS pin...
Done
If there are no issues by the end of the flash process, the board will reboot and start up the hello_world application.
If you d like to use the Eclipse or VS Code IDE instead of running idf.py, check out the Eclipse guide, VS Code
guide.

1.14 Step 10. Monitor

To check if hello_world is indeed running, type idf.py -p PORT monitor (Do not forget to replace PORT
with your serial port name).
This command launches the IDF Monitor application:
$ idf.py -p /dev/ttyUSB0 monitor

Running idf_monitor in directory [...]/esp/hello_world/build
Executing "python [...]/esp-idf/tools/idf_monitor.py -b 115200 [...]/esp/hello_
,→world/build/hello_world.elf"...
--- idf_monitor on /dev/ttyUSB0 115200 ---

--- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
ets Jun 8 2016 00:22:57
rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)

ets Jun 8 2016 00:22:57
...
After startup and diagnostic logs scroll up, you should see Hello world! printed out by the application.
...
Hello world!
Restarting in 10 seconds...
This is esp32 chip with 2 CPU core(s), WiFi/BT/BLE, silicon revision 1, 2MB␣
,→external flash
Minimum free heap size: 298968 bytes

To exit IDF monitor use the shortcut Ctrl+].

If IDF monitor fails shortly after the upload, or, if instead of the messages above, you see random garbage similar to
what is given below, your board is likely using a 26 MHz crystal. Most development board designs use 40 MHz, so
ESP-IDF uses this frequency as a default value.
If you have such a problem, do the following:

1. Exit the monitor.
2. Go back to menuconfig.
3. Go to Component config > ESP32-specific > Main XTAL frequency, then change CON-
FIG_ESP32_XTAL_FREQ_SEL to 26 MHz.
4. After that, build and flash the application again.
Note: You can combine building, flashing and monitoring into one step by running:
idf.py -p PORT flash monitor
See also:
• IDF Monitor for handy shortcuts and more details on using IDF monitor.
• idf.py for a full reference of idf.py commands and options.
That s all that you need to get started with ESP32!
Now you are ready to try some other examples, or go straight to developing your own applications.

Important: Some of examples do not support ESP32 because required hardware is not included in ESP32 so it
cannot be supported.
If building an example, please check the README file for the Supported Targets table. If this is present
including ESP32 target, or the table does not exist at all, the example will work on ESP32.
1.15 Updating ESP-IDF

You should update ESP-IDF from time to time, as newer versions fix bugs and provide new features. The simplest way
to do the update is to delete the existing esp-idf folder and clone it again, as if performing the initial installation
described in Step 2. Get ESP-IDF.
Another solution is to update only what has changed. The update procedure depends on the version of ESP-IDF you
are using.
After updating ESP-IDF, execute the Install script again, in case the new ESP-IDF version requires different versions
of tools. See instructions at Step 3. Set up the tools.
Once the new tools are installed, update the environment using the Export script. See instructions at Step 4. Set up
the environment variables.
1.16 Related Documents
1.16.1 Establish Serial Connection with ESP32
This section provides guidance how to establish serial connection between ESP32 and PC.
Connect ESP32 to PC
Connect the ESP32 board to the PC using the USB cable. If device driver does not install automatically, identify
USB to serial converter chip on your ESP32 board (or external converter dongle), search for drivers in internet and
install them.
Below is the list of USB to serial converter chips installed on most of the ESP32 boards produced by Espressif together
with links to the drivers:
• CP210x: CP210x USB to UART Bridge VCP Drivers
• FTDI: FTDI Virtual COM Port Drivers
Please check the board user guide for specific USB to serial converter chip used. The drivers above are primarily for
reference. Under normal circumstances, the drivers should be bundled with an operating system and automatically
installed upon connecting the board to the PC.
Check port on Windows
Check the list of identified COM ports in the Windows Device Manager. Disconnect ESP32 and connect it back, to
verify which port disappears from the list and then shows back again.
Figures below show serial port for ESP32 DevKitC and ESP32 WROVER KIT

Fig. 58: USB to UART bridge of ESP32-DevKitC in Windows Device Manager

Fig. 59: Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager

Check port on Linux and macOS
To check the device name for the serial port of your ESP32 board (or external converter dongle), run this command
two times, first with the board / dongle unplugged, then with plugged in. The port which appears the second time is
the one you need:
Linux
ls /dev/tty*
macOS
ls /dev/cu.*
Note: macOS users: if you don t see the serial port then check you have the USB/serial drivers installed as shown
in the Getting Started guide for your particular development board. For macOS High Sierra (10.13), you may also
have to explicitly allow the drivers to load. Open System Preferences -> Security & Privacy -> General and check
if there is a message shown here about System Software from developer where the developer name is Silicon
Labs or FTDI.
Adding user to dialout on Linux
The currently logged user should have read and write access the serial port over USB. On most Linux distributions,
this is done by adding the user to dialout group with the following command:
sudo usermod -a -G dialout $USER
on Arch Linux this is done by adding the user to uucp group with the following command:
sudo usermod -a -G uucp $USER
Make sure you re-login to enable read and write permissions for the serial port.
Verify serial connection
Now verify that the serial connection is operational. You can do this using a serial terminal program by checking if
you get any output on the terminal after reseting ESP32.
Windows and Linux In this example we will use PuTTY SSH Client that is available for both Windows and Linux.
You can use other serial program and set communication parameters like below.
Run terminal, set identified serial port, baud rate = 115200, data bits = 8, stop bits = 1, and parity = N. Below are
example screen shots of setting the port and such transmission parameters (in short described as 115200-8-1-N) on
Windows and Linux. Remember to select exactly the same serial port you have identified in steps above.
Then open serial port in terminal and check, if you see any log printed out by ESP32. The log contents will depend
on application loaded to ESP32, see Example Output.
Note: Close the serial terminal after verification that communication is working. If you keep the terminal session
open, the serial port will be inaccessible for uploading firmware later.

Fig. 60: Setting Serial Communication in PuTTY on Windows

Fig. 61: Setting Serial Communication in PuTTY on Linux

macOS To spare you the trouble of installing a serial terminal program, macOS offers the screen command.
• As discussed in Check port on Linux and macOS, run:
ls /dev/cu.*
• You should see similar output:
/dev/cu.Bluetooth-Incoming-Port /dev/cu.SLAB_USBtoUART /dev/cu.SLAB_

,→USBtoUART7
• The output will vary depending on the type and the number of boards connected to your PC. Then pick the
device name of your board and run:
screen /dev/cu.device_name 115200
Replace device_name with the name found running ls /dev/cu.*.

• What you are looking for is some log displayed by the screen. The log contents will depend on application
loaded to ESP32, see Example Output. To exit the screen session type Ctrl-A + \ .
Note: Do not forget to exit the screen session after verifying that the communication is working. If you fail to do
it and just close the terminal window, the serial port will be inaccessible for uploading firmware later.
Example Output An example log by ESP32 is shown below. Reset the board if you do not see anything.
ets Jun 8 2016 00:22:57
rst:0x5 (DEEPSLEEP_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)

ets Jun 8 2016 00:22:57
rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)

configsip: 0, SPIWP:0x00
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
mode:DIO, clock div:2
load:0x3fff0008,len:8
load:0x40078000,len:7828
load:0x40080000,len:252
entry 0x40080034
I (44) boot: ESP-IDF v2.0-rc1-401-gf9fba35 2nd stage bootloader
I (45) boot: compile time 18:48:10
...
If you can see readable log output, it means serial connection is working and you are ready to proceed with installation
and finally upload of application to ESP32.
Note: For some serial port wiring configurations, the serial RTS & DTR pins need to be disabled in the terminal
program before the ESP32 will boot and produce serial output. This depends on the hardware itself, most development
boards (including all Espressif boards) do not have this issue. The issue is present if RTS & DTR are wired directly
to the EN & GPIO0 pins. See the esptool documentation for more details.
If you got here from Step 6. Connect Your Device when installing s/w for ESP32 development, then you can continue
with Step 7. Configure.
1.16.2 Build and Flash with Eclipse IDE
ESP-IDF V4.0 has a new CMake-based build system as the default build system.

There is a new ESP-IDF Eclipse Plugin that works with the CMake-based build system. Please refer to Espressif
IDF Eclipse Plugins IDF for further instructions.
Note: In Espressif IDF Eclipse Plugins, though screenshots are captured from macOS, installation instructions are
applicable for Windows, Linux and macOS.
1.16.3 Getting Started with VS Code IDE
We have official support for VS Code and we aim to provide complete end to end support for all actions related to
ESP-IDF namely build, flash, monitor, debug, tracing, core-dump, System Trace Viewer, etc.
Quick Install Guide
Recommended way to install ESP-IDF Visual Studio Code Extension is by downloading it from VS Code Marketplace
or following Quick Installation Guide.
Review the tutorials <https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs/tutorial/toc.md> for
ESP-IDF Visual Studio Code Extension to learn how to use all features.
Supported Features
• Setup, will help you to quickly install ESP-IDF and its relevant toolchain with just few clicks.
• Build, with one click build and multi target build, you can easily build and deploy your applications.
• Flash, with both UART and JTAG flash out of the box.
• Monitoring comes with built-in terminal where you can trigger IDF Monitor Commands from within VS Code
as you are used to in traditional terminals.
• Debugging <https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs/tutorial/debugging.md>,
with out of box hardware debugging and also support for postmortem debugging like core-dump, you can
analyze the bugs with convenience.
• GUI Menu Config, provides with simplified UI for configuring your chip.
• App & Heap Tracing, provides support for collecting traces from your application and simplified UI for
analyzing them.
• System View Tracing Viewer, aims to read and display the .svdat files into trace UI, we also support multiple
core tracing views.
• IDF Size Analysis Overview presents an UI for binary size analysis.
• Rainmaker Cloud, we have inbuilt Rainmaker Cloud support where you can edit/read state of your connected
IoT devices easily.
• Code Coverage, we have inbuilt code coverage support which shall highlight in color which line have been
covered. We also render the existing HTML report directly inside the IDE.
Bugs & Feature Requests
If you face an issue with certain feature of VS Code or VS Code in general we recommend to ask your question in
the forum, or open a github issue for our dev teams to review.
We also welcome new feature request, most of the features we have today is result of people asking it to implement,
or improve certain aspect of the extension, raise your feature request on github.
1.16.4 IDF Monitor
The IDF monitor tool is mainly a serial terminal program which relays serial data to and from the target device s
serial port. It also provides some IDF-specific features.
This tool can be launched from an IDF project by running idf.py monitor.

Keyboard Shortcuts
For easy interaction with IDF Monitor, use the keyboard shortcuts given in the table.
Keyboard Action Description

Shortcut
Ctrl+] Exit the program
Ctrl+T Menu escape key Press and follow it by one of the keys given below.
Send the menu character it-
• Ctrl+T
self to remote
Send the exit character it-
• Ctrl+]
self to remote
Reset target into bootloader Resets the target, into bootloader via the RTS line (if connected),
• Ctrl+P
to pause app via RTS line so that the board runs nothing. Useful when you need to wait for
another device to startup.
Reset target board via RTS Resets the target board and re-starts the application via the RTS
• Ctrl+R
line (if connected).
Build and flash the project Pauses idf_monitor to run the project flash target, then re-
• Ctrl+F
sumes idf_monitor. Any changed source files are recompiled
and then re-flashed. Target encrypted-flash is run if
idf_monitor was started with argument -E.
Build and flash the app only Pauses idf_monitor to run the app-flash target, then resumes
• Ctrl+A
idf_monitor. Similar to the flash target, but only the main app
(or A)
is built and re-flashed. Target encrypted-app-flash is
run if idf_monitor was started with argument -E.
Stop/resume log output Discards all incoming serial data while activated. Allows to
• Ctrl+Y
printing on screen quickly pause and examine log output without quitting the mon-
itor.
Stop/resume log output Creates a file in the project directory and the output is written to
• Ctrl+L
saved to file that file until this is disabled with the same keyboard shortcut (or
IDF Monitor exits).
Stop/resume printing IDF Monitor can print a timestamp in the beginning of each line.
• Ctrl+I
timestamps The timestamp format can be changed by the --timestamp-
(or I)
format command line argument.
Display all keyboard short-
• Ctrl+H
cuts
(or H)
Exit the program

• Ctrl+X
(or X)
Ctrl+C Interrupt running applica- Pauses IDF monitor and run GDB project debugger
tion to debug the application at runtime. This requires
:ref:CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME option
to be enabled.
Any keys pressed, other than Ctrl-] and Ctrl-T, will be sent through the serial port.
IDF-specific features
Automatic Address Decoding Whenever ESP-IDF outputs a hexadecimal code address of the form
0x4_______, IDF Monitor uses addr2line to look up the location in the source code and find the function name.
If an ESP-IDF app crashes and panics, a register dump and backtrace is produced, such as the following:

Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was␣

,→unhandled.
Register dump:
PC : 0x400f360d PS : 0x00060330 A0 : 0x800dbf56 A1 :␣
,→0x3ffb7e00
A2 : 0x3ffb136c A3 : 0x00000005 A4 : 0x00000000 A5 :␣

,→0x00000000
A6 : 0x00000000 A7 : 0x00000080 A8 : 0x00000000 A9 :␣

,→0x3ffb7dd0
A10 : 0x00000003 A11 : 0x00060f23 A12 : 0x00060f20 A13 :␣

,→0x3ffba6d0
A14 : 0x00000047 A15 : 0x0000000f SAR : 0x00000019 EXCCAUSE:␣

,→0x0000001d
EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT :␣

,→0x00000000
Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40␣

,→0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90
IDF Monitor adds more details to the dump:
Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was␣

,→unhandled.
Register dump:
PC : 0x400f360d PS : 0x00060330 A0 : 0x800dbf56 A1 :␣
,→0x3ffb7e00
0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/

,→hello_world/main/./hello_world_main.c:57
(inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_

,→world/main/./hello_world_main.c:52
A2 : 0x3ffb136c A3 : 0x00000005 A4 : 0x00000000 A5 :␣

,→0x00000000
A6 : 0x00000000 A7 : 0x00000080 A8 : 0x00000000 A9 :␣

,→0x3ffb7dd0
A10 : 0x00000003 A11 : 0x00060f23 A12 : 0x00060f20 A13 :␣

,→0x3ffba6d0
A14 : 0x00000047 A15 : 0x0000000f SAR : 0x00000019 EXCCAUSE:␣

,→0x0000001d

,→0x00000000
Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40␣

,→0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90
0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/

,→hello_world/main/./hello_world_main.c:57
(inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_

0x400dbf56: still_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_

0x400dbf5e: dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/

,→main/./hello_world_main.c:42
0x400dbf82: app_main at /home/gus/esp/32/idf/examples/get-started/hello_world/main/

,→./hello_world_main.c:33
0x400d071d: main_task at /home/gus/esp/32/idf/components/esp32/./cpu_start.c:254
To decode each address, IDF Monitor runs the following command in the background:
xtensa-esp32-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS
Note: Set environment variable ESP_MONITOR_DECODE to 0 or call idf_monitor.py with specific command line

option: idf_monitor.py --disable-address-decoding to disable address decoding.
Launching GDB with GDBStub By default, if esp-idf crashes, the panic handler prints relevant registers and the
stack dump (similar to the ones above) over the serial port. Then it resets the board.
Furthermore, the application can be configured to run GDBStub in the background and handle the Ctrl+C event from
the monitor.
Optionally, the panic handler can be configured to run GDBStub, the tool which can communicate with GDB project
debugger. GDBStub allows to read memory, examine call stack frames and variables, etc. It is not as versatile as
JTAG debugging, but this method does not require any special hardware.
To enable GDBStub on panic, open the project configuration menu (idf.py menuconfig) and set CON-
FIG_ESP_SYSTEM_PANIC to GDBStub on panic or set CONFIG_ESP_SYSTEM_PANIC to GDBStub on
runtime.
In this case, if the panic handler or Ctrl+C command is triggered, as soon as IDF Monitor sees that GDBStub has
loaded, it automatically pauses serial monitoring and runs GDB with necessary arguments. After GDB exits, the
board is reset via the RTS serial line. If this line is not connected, please reset the board manually by pressing its
Reset button.
In the background, IDF Monitor runs the following command:
xtensa-esp32-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex␣
,→interrupt build/PROJECT.elf :idf_target:`Hello NAME chip`
Output Filtering IDF monitor can be invoked as idf.py monitor --print-filter="xyz", where
--print-filter is the parameter for output filtering. The default value is an empty string, which means that
everything is printed.
Restrictions on what to print can be specified as a series of <tag>:<log_level> items where <tag> is the tag
string and <log_level> is a character from the set {N, E, W, I, D, V, *} referring to a level for logging.
For example, PRINT_FILTER="tag1:W" matches and prints only the outputs written with
ESP_LOGW("tag1", ...) or at lower verbosity level, i.e. ESP_LOGE("tag1", ...). Not speci-
fying a <log_level> or using * defaults to Verbose level.
Note: Use primary logging to disable at compilation the outputs you do not need through the logging library. Output
filtering with IDF monitor is a secondary solution which can be useful for adjusting the filtering options without
recompiling the application.
Your app tags must not contain spaces, asterisks *, or colons : to be compatible with the output filtering feature.
If the last line of the output in your app is not followed by a carriage return, the output filtering might get confused, i.e.,
the monitor starts to print the line and later finds out that the line should not have been written. This is a known issue
and can be avoided by always adding a carriage return (especially when no output follows immediately afterwards).
Examples Of Filtering Rules:

• * can be used to match any tags. However, the string PRINT_FILTER="*:I tag1:E" with regards to
tag1 prints errors only, because the rule for tag1 has a higher priority over the rule for *.
• The default (empty) rule is equivalent to *:V because matching every tag at the Verbose level or lower means
matching everything.
• "*:N" suppresses not only the outputs from logging functions, but also the prints made by printf, etc. To
avoid this, use *:E or a higher verbosity level.
• Rules "tag1:V", "tag1:v", "tag1:", "tag1:*", and "tag1" are equivalent.
• Rule "tag1:W tag1:E" is equivalent to "tag1:E" because any consequent occurrence of the same tag
name overwrites the previous one.

• Rule "tag1:I tag2:W" only prints tag1 at the Info verbosity level or lower and tag2 at the Warning
verbosity level or lower.
• Rule "tag1:I tag2:W tag3:N" is essentially equivalent to the previous one because tag3:N specifies
that tag3 should not be printed.
• tag3:N in the rule "tag1:I tag2:W tag3:N *:V" is more meaningful because without tag3:N the
tag3 messages could have been printed; the errors for tag1 and tag2 will be printed at the specified (or
lower) verbosity level and everything else will be printed by default.
A More Complex Filtering Example The following log snippet was acquired without any filtering options:
load:0x40078000,len:13564
entry 0x40078d4c
E (31) esp_image: image at 0x30000 has invalid magic byte
W (31) esp_image: image at 0x30000 has invalid SPI mode 255
E (39) boot: Factory app partition is not bootable
I (568) cpu_start: Pro cpu up.
I (569) heap_init: Initializing. RAM available for dynamic allocation:
I (603) cpu_start: Pro cpu start user code
D (309) light_driver: [light_init, 74]:status: 1, mode: 2
D (318) vfs: esp_vfs_register_fd_range is successful for range <54; 64) and VFS ID␣
,→1
I (328) wifi: wifi driver task: 3ffdbf84, prio:23, stack:4096, core=0
The captured output for the filtering options PRINT_FILTER="wifi esp_image:E light_driver:I"
is given below:
I (328) wifi: wifi driver task: 3ffdbf84, prio:23, stack:4096, core=0
The options ``PRINT_FILTER="light_driver:D esp_image:N boot:N cpu_start:N

vfs:N wifi:N *:V" show the following output:
load:0x40078000,len:13564
entry 0x40078d4c
D (309) light_driver: [light_init, 74]:status: 1, mode: 2
Known Issues with IDF Monitor
Issues Observed on Windows

• Arrow keys, as well as some other keys, do not work in GDB due to Windows Console limitations.
• Occasionally, when idf.py exits, it might stall for up to 30 seconds before IDF Monitor resumes.
• When gdb is run, it might stall for a short time before it begins communicating with the GDBStub.
1.16.5 Customized Setup of Toolchain
Instead of downloading binary toolchain from Espressif website (see Step 3. Set up the tools) you may build the
toolchain yourself.
If you can t think of a reason why you need to build it yourself, then probably it s better to stick with the binary
version. However, here are some of the reasons why you might want to compile it from source:
• if you want to customize toolchain build configuration
• if you want to use a different GCC version (such as 4.8.5)
• if you want to hack gcc or newlib or libstdc++
• if you are curious and/or have time to spare
• if you don t trust binaries downloaded from the Internet
In any case, here are the instructions to compile the toolchain yourself.

Setup Windows Toolchain from Scratch
This is a step-by-step alternative to running the ESP-IDF Tools Installer for the CMake-based build system. Installing
all of the tools by hand allows more control over the process, and also provides the information for advanced users to
customize the install.
To quickly setup the toolchain and other tools in standard way, using the ESP-IDF Tools installer, proceed to section
Standard Setup of Toolchain for Windows.
Get ESP-IDF
Note: Previous versions of ESP-IDF used the MSYS2 bash terminal command line. The current cmake-based
build system can run in the regular Windows Command Prompt which is used here.
If you use PowerShell, please note that some command syntax will be different to what is shown below.
Open Command Prompt and run the following commands:
mkdir %userprofile%\esp
cd %userprofile%\esp
git clone --recursive https://github.com/espressif/esp-idf.git
ESP-IDF will be downloaded into %userprofile%\esp\esp-idf.

Note: This command will clone the master branch, which has the latest development ( bleeding edge ) version
of ESP-IDF. It is fully functional and updated on weekly basis with the most recent features and bugfixes.
Note: GitHub s Download zip file feature does not work with ESP-IDF, a git clone is required. As a
fallback, Stable version can be installed without Git.
Note: Do not miss the --recursive option. If you have already cloned ESP-IDF without this option, run another
command to get all the submodules:
cd esp-idf
git submodule update --init
Tools
CMake Download the latest stable release of CMake for Windows and run the installer.
When the installer asks for Install Options, choose either Add CMake to the system PATH for all users or Add
CMake to the system PATH for the current user .
Ninja build
Note: Ninja currently only provides binaries for 64-bit Windows.
Download the Ninja latest stable Windows release from the (download page).
The Ninja for Windows download is a .zip file containing a single ninja.exe file which needs to be unzipped to a
directory which is then added to your Path (or you can choose a directory which is already on your Path).

Python Download the latest Python for Windows installer, and run it.
The Customise step of the Python installer gives a list of options. The last option is Add python.exe to Path
. Change this option to select Will be installed .
Once Python is installed, open a Windows Command Prompt from the Start menu and run the following command:
pip install --user pyserial
Toolchain Setup Download the precompiled Windows toolchain:

https://dl.espressif.com/dl/xtensa-esp32-elf-gcc8_4_0-esp-2021r2-win32.zip
Unzip the zip file to C:\Program Files (or some other location). The zip file contains a single directory
xtensa-esp32-elf.
Next, the bin subdirectory of this directory must be added to your Path. For example, the directory to add may be
C:\Program Files\xtensa-esp32-elf\bin.
Adding Directory to Path To add any new directory to your Windows Path environment variable:
Open the System control panel and navigate to the Environment Variables dialog. (On Windows 10, this is found
under Advanced System Settings).
Double-click the Path variable (either User or System Path, depending if you want other users to have this directory
on their path.) Go to the end of the value, and append ;<new value>.
Next Steps To carry on with development environment setup, proceed to Step 3. Set up the tools.
Setup Linux Toolchain from Scratch
The following instructions are alternative to downloading binary toolchain from Espressif website. To quickly setup
the binary toolchain, instead of compiling it yourself, backup and proceed to section Standard Setup of Toolchain for
Linux.
Note: The reason you might need to build your own toolchain is to solve the Y2K38 problem (time_t expand to 64
bits instead of 32 bits).
Install Prerequisites To compile with ESP-IDF you need to get the following packages:
• CentOS 7:
sudo yum -y update && sudo yum install git wget ncurses-devel flex bison gperf␣
,→python3 python3-pip cmake ninja-build ccache dfu-util libusbx
CentOS 7 is still supported but CentOS version 8 is recommended for a better user experience.
• Ubuntu and Debian:
sudo apt-get install git wget libncurses-dev flex bison gperf python3 python3-
,→pip python3-setuptools python3-serial python3-cryptography python3-future␣
,→python3-pyparsing python3-pyelftools cmake ninja-build ccache libffi-dev␣
,→libssl-dev dfu-util libusb-1.0-0
• Arch:
sudo pacman -Sy --needed gcc git make ncurses flex bison gperf python-pyserial␣
,→python-cryptography python-future python-pyparsing python-pyelftools cmake␣
,→ninja ccache dfu-util libusb

Note: CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating,
enabling of a backports repository, or installing of a cmake3 package rather than cmake .
Compile the Toolchain from Source

• Install dependencies:
– CentOS 7:
sudo yum install gawk gperf grep gettext ncurses-devel python3 python3-
,→devel automake bison flex texinfo help2man libtool make
– Ubuntu pre-16.04:
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-
,→dev automake bison flex texinfo help2man libtool make
– Ubuntu 16.04 or newer:

sudo apt-get install gawk gperf grep gettext python python-dev automake␣
,→bison flex texinfo help2man libtool libtool-bin make
– Debian 9:
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-
,→dev automake bison flex texinfo help2man libtool libtool-bin make
– Arch:
sudo pacman -Sy --needed python-pip
Create the working directory and go into it:

mkdir -p ~/esp
cd ~/esp
Download crosstool-NG and build it:

git clone https://github.com/espressif/crosstool-NG.git
cd crosstool-NG
git checkout esp-2021r2
./bootstrap && ./configure --enable-local && make
Note: To create a toolchain with support for 64-bit time_t, you need to remove the --enable-newlib-long-
time_t option from the crosstool-NG/samples/xtensa-esp32-elf/crosstool.config file in
33 and 43 lines.
Build the toolchain:

./ct-ng xtensa-esp32-elf
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
Toolchain will be built in ~/esp/crosstool-NG/builds/xtensa-esp32-elf.
Add Toolchain to PATH The custom toolchain needs to be copied to a binary directory and added to the PATH.
Choose a directory, for example ~/esp/xtensa-esp32-elf/, and copy the build output to this directory.
To use it, you will need to update your PATH environment variable in ~/.profile file. To make xtensa-
esp32-elf available for all terminal sessions, add the following line to your ~/.profile file:

export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"
Note: If you have /bin/bash set as login shell, and both .bash_profile and .profile exist, then update
.bash_profile instead. In CentOS, alias should set in .bashrc.
Log off and log in back to make the .profile changes effective. Run the following command to verify if PATH
is correctly set:
printenv PATH
You are looking for similar result containing toolchain s path at the beginning of displayed string:
$ printenv PATH
/home/user-name/esp/xtensa-esp32-elf/bin:/home/user-name/bin:/home/user-name/.
,→local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/
,→games:/usr/local/games:/snap/bin
Instead of /home/user-name there should be a home path specific to your installation.
Next Steps To carry on with development environment setup, proceed to Step 2. Get ESP-IDF.
Setup Toolchain for Mac OS from Scratch
Package Manager To set up the toolchain from scratch, rather than downloading a pre-compiled toolchain, you
will need to install either the MacPorts or Homebrew package manager.
MacPorts needs a full XCode installation, while Homebrew only needs XCode command line tools.
See Customized Setup of Toolchain section for some of the reasons why installing the toolchain from scratch may be
necessary.
• install pip:
sudo easy_install pip
• install pyserial:
pip install --user pyserial
• install CMake & Ninja build:

– If you have Homebrew, you can run:
brew install cmake ninja dfu-util
– If you have MacPorts, you can run:

sudo port install cmake ninja dfu-util
Compile the Toolchain from Source Install dependencies:

• with MacPorts:
sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf␣
,→automake make
• with Homebrew:

brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool␣
,→autoconf automake make
Create a case-sensitive filesystem image:
hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive␣

,→HFS+"
Mount it:
hdiutil mount ~/esp/crosstool.dmg
Create a symlink to your work directory:
mkdir -p ~/esp
ln -s /Volumes/ctng ~/esp/ctng-volume
Go into the newly created directory:
cd ~/esp/ctng-volume
Download crosstool-NG and build it:
git clone https://github.com/espressif/crosstool-NG.git

cd crosstool-NG
git checkout esp-2021r2
./bootstrap && ./configure --enable-local && make
Build the toolchain:
./ct-ng xtensa-esp32-elf
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
Toolchain will be built in ~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf. To

use it, you need to add ~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf/bin to
PATH environment variable.
Next Steps To carry on with development environment setup, proceed to Step 2. Get ESP-IDF.


Chapter 2
API Reference
2.1 Bluetooth API
2.1.1 Controller && VHCI
Overview
Instructions
Application Example
Check bluetooth/hci folder in ESP-IDF examples, which contains the following application:
• This is a BLE advertising demo with virtual HCI interface. Send Re-
set/ADV_PARAM/ADV_DATA/ADV_ENABLE HCI command for BLE advertising - blue-
tooth/hci/controller_vhci_ble_adv.
API Reference
Header File
• components/bt/include/esp32/include/esp_bt.h
Functions
esp_err_t esp_ble_tx_power_set(esp_ble_power_type_t power_type, esp_power_level_t power_level)
Set BLE TX power Connection Tx power should only be set after connection created.
Return ESP_OK - success, other - failed
Parameters
• power_type: : The type of which tx power, could set Advertising/Connection/Default and etc
• power_level: Power level(index) corresponding to absolute value(dbm)
esp_power_level_t esp_ble_tx_power_get(esp_ble_power_type_t power_type)
Get BLE TX power Connection Tx power should only be get after connection created.
Return >= 0 - Power level, < 0 - Invalid
Parameters
• power_type: : The type of which tx power, could set Advertising/Connection/Default and etc
esp_err_t esp_bredr_tx_power_set(esp_power_level_t min_power_level, esp_power_level_t
max_power_level)
Set BR/EDR TX power BR/EDR power control will use the power in range of minimum value and maximum
value. The power level will effect the global BR/EDR TX power, such inquire, page, connection and so on.
127
Chapter 2. API Reference
Please call the function after esp_bt_controller_enable and before any function which cause RF do TX. So you
can call the function before doing discovery, profile init and so on. For example, if you want BR/EDR use the
new TX power to do inquire, you should call this function before inquire. Another word, If call this function
when BR/EDR is in inquire(ING), please do inquire again after call this function. Default minimum power
level is ESP_PWR_LVL_N0, and maximum power level is ESP_PWR_LVL_P3.
Parameters
• min_power_level: The minimum power level
• max_power_level: The maximum power level
esp_err_t esp_bredr_tx_power_get(esp_power_level_t *min_power_level, esp_power_level_t
*max_power_level)
Get BR/EDR TX power If the argument is not NULL, then store the corresponding value.
Parameters
• min_power_level: The minimum power level
• max_power_level: The maximum power level
esp_err_t esp_bredr_sco_datapath_set(esp_sco_data_path_t data_path)
Set default SCO data path Should be called after controller is enabled, and before (e)SCO link is established.
Parameters
• data_path: SCO data path
esp_err_t esp_bt_controller_init(esp_bt_controller_config_t *cfg)
Initialize BT controller to allocate task and other resource. This function should be called only once, before
any other BT functions are called.
Parameters
• cfg: Initial configuration of BT controller. Different from previous version, there s a mode and
some connection configuration in cfg to configure controller work mode and allocate the resource
which is needed.
esp_err_t esp_bt_controller_deinit(void)
De-initialize BT controller to free resource and delete task.
This function should be called only once, after any other BT functions are called.
esp_err_t esp_bt_controller_enable(esp_bt_mode_t mode)
Enable BT controller. Due to a known issue, you cannot call esp_bt_controller_enable() a second time to
change the controller mode dynamically. To change controller mode, call esp_bt_controller_disable() and
then call esp_bt_controller_enable() with the new mode.
Parameters
• mode: : the mode(BLE/BT/BTDM) to enable. For compatible of API, retain this argument. This
mode must be equal as the mode in cfg of esp_bt_controller_init().
esp_err_t esp_bt_controller_disable(void)
Disable BT controller.
esp_bt_controller_status_t esp_bt_controller_get_status(void)
Get BT controller is initialised/de-initialised/enabled/disabled.
Return status value
bool esp_vhci_host_check_send_available(void)
esp_vhci_host_check_send_available used for check actively if the host can send packet to controller or not.

Return true for ready to send, false means cannot send packet
void esp_vhci_host_send_packet(uint8_t *data, uint16_t len)
esp_vhci_host_send_packet host send packet to controller
Should not call this function from within a critical section or when the scheduler is suspended.
Parameters
• data: the packet point
• len: the packet length
esp_err_t esp_vhci_host_register_callback(const esp_vhci_host_callback_t *callback)
esp_vhci_host_register_callback register the vhci reference callback struct defined by vhci_host_callback
structure.
Return ESP_OK - success, ESP_FAIL - failed
Parameters
• callback: esp_vhci_host_callback type variable
esp_err_t esp_bt_controller_mem_release(esp_bt_mode_t mode)
esp_bt_controller_mem_release release the controller memory as per the mode
This function releases the BSS, data and other sections of the controller to heap. The total size is about 70k
bytes.
esp_bt_controller_mem_release(mode) should be called only before esp_bt_controller_init() or after
esp_bt_controller_deinit().
Note that once BT controller memory is released, the process cannot be reversed. It means you cannot use the
bluetooth mode which you have released by this function.
If your firmware will later upgrade the Bluetooth controller mode (BLE -> BT Classic or disabled -> enabled)
then do not call this function.
If the app calls esp_bt_controller_enable(ESP_BT_MODE_BLE) to use BLE only then it is safe to call
esp_bt_controller_mem_release(ESP_BT_MODE_CLASSIC_BT) at initialization time to free unused BT
Classic memory.
If the mode is ESP_BT_MODE_BTDM, then it may be useful to call API
esp_bt_mem_release(ESP_BT_MODE_BTDM) instead, which internally calls
esp_bt_controller_mem_release(ESP_BT_MODE_BTDM) and additionally releases the BSS and data
consumed by the BT/BLE host stack to heap. For more details about usage please refer to the documentation
of esp_bt_mem_release() function
Parameters
• mode: : the mode want to release memory
esp_err_t esp_bt_mem_release(esp_bt_mode_t mode)
esp_bt_mem_release release controller memory and BSS and data section of the BT/BLE host stack as per the
mode
This function first releases controller memory by internally calling esp_bt_controller_mem_release(). Addi-
tionally, if the mode is set to ESP_BT_MODE_BTDM, it also releases the BSS and data consumed by the
BT/BLE host stack to heap
Note that once BT memory is released, the process cannot be reversed. It means you cannot use the bluetooth
mode which you have released by this function.
If your firmware will later upgrade the Bluetooth controller mode (BLE -> BT Classic or disabled -> enabled)
then do not call this function.
If you never intend to use bluetooth in a current boot-up cycle, you can call
esp_bt_mem_release(ESP_BT_MODE_BTDM) before esp_bt_controller_init or after
esp_bt_controller_deinit.

For example, if a user only uses bluetooth for setting the WiFi configuration, and does not use bluetooth in the
rest of the product operation . In such cases, after receiving the WiFi configuration, you can disable/deinit
bluetooth and release its memory. Below is the sequence of APIs to be called for such scenarios:
esp_bluedroid_disable();
esp_bluedroid_deinit();
esp_bt_controller_disable();
esp_bt_controller_deinit();
esp_bt_mem_release(ESP_BT_MODE_BTDM);
Note In case of NimBLE host, to release BSS and data memory to heap, the mode needs to be set to
ESP_BT_MODE_BTDM as controller is dual mode.
Parameters
• mode: : the mode whose memory is to be released
esp_err_t esp_bt_sleep_enable(void)
enable bluetooth to enter modem sleep
Note that this function shall not be invoked before esp_bt_controller_enable()
There are currently two options for bluetooth modem sleep, one is ORIG mode, and another is EVED Mode.
EVED Mode is intended for BLE only.
For ORIG mode: Bluetooth modem sleep is enabled in controller start up by default if CON-
FIG_CTRL_BTDM_MODEM_SLEEP is set and ORIG mode is selected. In ORIG modem sleep mode,
bluetooth controller will switch off some components and pause to work every now and then, if there is no
event to process; and wakeup according to the scheduled interval and resume the work. It can also wakeup
earlier upon external request using function esp_bt_controller_wakeup_request .
Return
• ESP_OK : success
• other : failed
esp_err_t esp_bt_sleep_disable(void)
disable bluetooth modem sleep
Note that this function shall not be invoked before esp_bt_controller_enable()
If esp_bt_sleep_disable() is called, bluetooth controller will not be allowed to enter modem sleep;
If ORIG modem sleep mode is in use, if this function is called, bluetooth controller may not immediately wake
up if it is dormant then. In this case, esp_bt_controller_wakeup_request() can be used to shorten the time for
wakeup.
Return
• other : failed
esp_err_t esp_ble_scan_dupilcate_list_flush(void)
Manually clear scan duplicate list.
Note that scan duplicate list will be automatically cleared when the maximum amount of device in the filter is
reached the amount of device in the filter can be configured in menuconfig.
Note This function name is incorrectly spelled, it will be fixed in release 5.x version.
Return
• other : failed
void esp_wifi_bt_power_domain_on(void)
bt Wi-Fi power domain power on
void esp_wifi_bt_power_domain_off(void)
bt Wi-Fi power domain power off

Structures
struct esp_bt_controller_config_t
Controller config options, depend on config mask. Config mask indicate which functions enabled, this means
some options or parameters of some functions enabled by config mask.
Public Members
uint16_t controller_task_stack_size
Bluetooth controller task stack size
uint8_t controller_task_prio
Bluetooth controller task priority
uint8_t hci_uart_no
If use UART1/2 as HCI IO interface, indicate UART number
uint32_t hci_uart_baudrate
If use UART1/2 as HCI IO interface, indicate UART baudrate
uint8_t scan_duplicate_mode
scan duplicate mode
uint8_t scan_duplicate_type
scan duplicate type
uint16_t normal_adv_size
Normal adv size for scan duplicate
uint16_t mesh_adv_size
Mesh adv size for scan duplicate
uint16_t send_adv_reserved_size
Controller minimum memory value
uint32_t controller_debug_flag
Controller debug log flag
uint8_t mode
Controller mode: BR/EDR, BLE or Dual Mode
uint8_t ble_max_conn
BLE maximum connection numbers
uint8_t bt_max_acl_conn
BR/EDR maximum ACL connection numbers
uint8_t bt_sco_datapath
SCO data path, i.e. HCI or PCM module
bool auto_latency
BLE auto latency, used to enhance classic BT performance
bool bt_legacy_auth_vs_evt
BR/EDR Legacy auth complete event required to protect from BIAS attack
uint8_t bt_max_sync_conn
BR/EDR maximum ACL connection numbers. Effective in menuconfig
uint8_t ble_sca
BLE low power crystal accuracy index
uint8_t pcm_role
PCM role (master & slave)
uint8_t pcm_polar
PCM polar trig (falling clk edge & rising clk edge)

bool hli
Using high level interrupt or not
uint32_t magic
Magic number
struct esp_vhci_host_callback
esp_vhci_host_callback used for vhci call host function to notify what host need to do
Public Members
void (*notify_host_send_available)(void)
callback used to notify that the host can send packet to controller
int (*notify_host_recv)(uint8_t *data, uint16_t len)
callback used to notify that the controller has a packet to send to the host
Macros
ESP_BT_CONTROLLER_CONFIG_MAGIC_VAL
BT_CONTROLLER_INIT_CONFIG_DEFAULT()
Type Definitions
typedef struct esp_vhci_host_callback esp_vhci_host_callback_t
esp_vhci_host_callback used for vhci call host function to notify what host need to do
Enumerations
enum esp_bt_mode_t
Bluetooth mode for controller enable/disable.
Values:
ESP_BT_MODE_IDLE = 0x00
Bluetooth is not running
ESP_BT_MODE_BLE = 0x01
Run BLE mode
ESP_BT_MODE_CLASSIC_BT = 0x02
Run Classic BT mode
ESP_BT_MODE_BTDM = 0x03
Run dual mode
enum [anonymous]
BLE sleep clock accuracy(SCA), values for ble_sca field in esp_bt_controller_config_t, currently only
ESP_BLE_SCA_500PPM and ESP_BLE_SCA_250PPM are supported.
Values:
ESP_BLE_SCA_500PPM = 0
BLE SCA at 500ppm
ESP_BLE_SCA_250PPM
BLE SCA at 250ppm
ESP_BLE_SCA_150PPM
BLE SCA at 150ppm
ESP_BLE_SCA_100PPM
BLE SCA at 100ppm
ESP_BLE_SCA_75PPM
BLE SCA at 75ppm

ESP_BLE_SCA_50PPM
BLE SCA at 50ppm
ESP_BLE_SCA_30PPM
BLE SCA at 30ppm
ESP_BLE_SCA_20PPM
BLE SCA at 20ppm
enum esp_bt_controller_status_t
Bluetooth controller enable/disable/initialised/de-initialised status.
Values:
ESP_BT_CONTROLLER_STATUS_IDLE = 0
ESP_BT_CONTROLLER_STATUS_INITED
ESP_BT_CONTROLLER_STATUS_ENABLED
ESP_BT_CONTROLLER_STATUS_NUM
enum esp_ble_power_type_t
BLE tx power type ESP_BLE_PWR_TYPE_CONN_HDL0-8: for each connection, and only be
set after connection completed. when disconnect, the correspond TX power is not effected.
ESP_BLE_PWR_TYPE_ADV : for advertising/scan response. ESP_BLE_PWR_TYPE_SCAN : for scan.
ESP_BLE_PWR_TYPE_DEFAULT : if each connection s TX power is not set, it will use this default value.
if neither in scan mode nor in adv mode, it will use this default value. If none of power type is set, system will
use ESP_PWR_LVL_P3 as default for ADV/SCAN/CONN0-9.
Values:
ESP_BLE_PWR_TYPE_CONN_HDL0 = 0
For connection handle 0
ESP_BLE_PWR_TYPE_ADV = 9
For advertising
ESP_BLE_PWR_TYPE_SCAN = 10
For scan
ESP_BLE_PWR_TYPE_DEFAULT = 11
For default, if not set other, it will use default value
ESP_BLE_PWR_TYPE_NUM = 12
TYPE numbers

enum esp_power_level_t
Bluetooth TX power level(index), it s just a index corresponding to power(dbm).
Values:
ESP_PWR_LVL_N12 = 0
Corresponding to -12dbm
ESP_PWR_LVL_N9 = 1
ESP_PWR_LVL_N6 = 2
ESP_PWR_LVL_N3 = 3
ESP_PWR_LVL_N0 = 4
Corresponding to 0dbm
ESP_PWR_LVL_P3 = 5
Corresponding to +3dbm
ESP_PWR_LVL_P6 = 6
ESP_PWR_LVL_P9 = 7
ESP_PWR_LVL_N14 = ESP_PWR_LVL_N12
Backward compatibility! Setting to -14dbm will actually result to -12dbm
Backward compatibility! Setting to -2dbm will actually result to 0dbm
ESP_PWR_LVL_P1 = ESP_PWR_LVL_P3
Backward compatibility! Setting to +1dbm will actually result to +3dbm
enum esp_sco_data_path_t
Bluetooth audio data transport path.
Values:
ESP_SCO_DATA_PATH_HCI = 0
data over HCI transport
ESP_SCO_DATA_PATH_PCM = 1
data over PCM interface
2.1.2 BT COMMON
BT GENERIC DEFINES

Overview Instructions
Application Example Instructions
API Reference
Header File
• components/bt/host/bluedroid/api/include/api/esp_bt_defs.h
Structures
struct esp_bt_uuid_t
UUID type.
Public Members
uint16_t len
UUID length, 16bit, 32bit or 128bit
uint16_t uuid16
16bit UUID
uint32_t uuid32
32bit UUID
uint8_t uuid128[ESP_UUID_LEN_128]
128bit UUID
union esp_bt_uuid_t::[anonymous] uuid
UUID
Macros
ESP_BLUEDROID_STATUS_CHECK(status)
ESP_BT_OCTET16_LEN
ESP_BT_OCTET8_LEN
ESP_DEFAULT_GATT_IF
Default GATT interface id.
ESP_BLE_CONN_INT_MIN
relate to BTM_BLE_CONN_INT_MIN in stack/btm_ble_api.h
ESP_BLE_CONN_INT_MAX
relate to BTM_BLE_CONN_INT_MAX in stack/btm_ble_api.h
ESP_BLE_CONN_LATENCY_MAX
relate to ESP_BLE_CONN_LATENCY_MAX in stack/btm_ble_api.h
ESP_BLE_CONN_SUP_TOUT_MIN
relate to BTM_BLE_CONN_SUP_TOUT_MIN in stack/btm_ble_api.h
ESP_BLE_CONN_SUP_TOUT_MAX
relate to ESP_BLE_CONN_SUP_TOUT_MAX in stack/btm_ble_api.h
ESP_BLE_CONN_PARAM_UNDEF
ESP_BLE_SCAN_PARAM_UNDEF
ESP_BLE_IS_VALID_PARAM(x, min, max)
Check the param is valid or not.

ESP_UUID_LEN_16
ESP_UUID_LEN_32
ESP_UUID_LEN_128
ESP_BD_ADDR_LEN
Bluetooth address length.
ESP_BLE_ENC_KEY_MASK
Used to exchange the encryption key in the init key & response key.
ESP_BLE_ID_KEY_MASK
Used to exchange the IRK key in the init key & response key.
ESP_BLE_CSR_KEY_MASK
Used to exchange the CSRK key in the init key & response key.
ESP_BLE_LINK_KEY_MASK
Used to exchange the link key(this key just used in the BLE & BR/EDR coexist mode) in the init key &
response key.
ESP_APP_ID_MIN
Minimum of the application id.
ESP_APP_ID_MAX
Maximum of the application id.
ESP_BD_ADDR_STR
ESP_BD_ADDR_HEX(addr)
Type Definitions
typedef uint8_t esp_bt_octet16_t[ESP_BT_OCTET16_LEN]
typedef uint8_t esp_bt_octet8_t[ESP_BT_OCTET8_LEN]
typedef uint8_t esp_link_key[ESP_BT_OCTET16_LEN]
typedef uint8_t esp_bd_addr_t[ESP_BD_ADDR_LEN]
Bluetooth device address.
typedef uint8_t esp_ble_key_mask_t
Enumerations
enum esp_bt_status_t
Status Return Value.
Values:
ESP_BT_STATUS_SUCCESS = 0
ESP_BT_STATUS_FAIL
ESP_BT_STATUS_NOT_READY
ESP_BT_STATUS_NOMEM
ESP_BT_STATUS_BUSY
ESP_BT_STATUS_DONE = 5
ESP_BT_STATUS_UNSUPPORTED
ESP_BT_STATUS_PARM_INVALID
ESP_BT_STATUS_UNHANDLED
ESP_BT_STATUS_AUTH_FAILURE
ESP_BT_STATUS_RMT_DEV_DOWN = 10

ESP_BT_STATUS_AUTH_REJECTED
ESP_BT_STATUS_INVALID_STATIC_RAND_ADDR
ESP_BT_STATUS_PENDING
ESP_BT_STATUS_UNACCEPT_CONN_INTERVAL
ESP_BT_STATUS_PARAM_OUT_OF_RANGE
ESP_BT_STATUS_TIMEOUT
ESP_BT_STATUS_PEER_LE_DATA_LEN_UNSUPPORTED
ESP_BT_STATUS_CONTROL_LE_DATA_LEN_UNSUPPORTED
ESP_BT_STATUS_ERR_ILLEGAL_PARAMETER_FMT
ESP_BT_STATUS_MEMORY_FULL = 20
ESP_BT_STATUS_EIR_TOO_LARGE
enum esp_bt_dev_type_t
Bluetooth device type.
Values:
ESP_BT_DEVICE_TYPE_BREDR = 0x01
ESP_BT_DEVICE_TYPE_BLE = 0x02
ESP_BT_DEVICE_TYPE_DUMO = 0x03
enum esp_ble_addr_type_t
BLE device address type.
Values:
BLE_ADDR_TYPE_PUBLIC = 0x00
BLE_ADDR_TYPE_RANDOM = 0x01
BLE_ADDR_TYPE_RPA_PUBLIC = 0x02
BLE_ADDR_TYPE_RPA_RANDOM = 0x03
enum esp_ble_wl_addr_type_t
white list address type
Values:
BLE_WL_ADDR_TYPE_PUBLIC = 0x00
BLE_WL_ADDR_TYPE_RANDOM = 0x01
BT MAIN API
API Reference
Header File
• components/bt/host/bluedroid/api/include/api/esp_bt_main.h

Functions
esp_bluedroid_status_t esp_bluedroid_get_status(void)
Get bluetooth stack status.
Return Bluetooth stack status
esp_err_t esp_bluedroid_enable(void)
Enable bluetooth, must after esp_bluedroid_init().
Return
• ESP_OK : Succeed
• Other : Failed
esp_err_t esp_bluedroid_disable(void)
Disable bluetooth, must prior to esp_bluedroid_deinit().
Return
• Other : Failed
esp_err_t esp_bluedroid_init(void)
Init and alloc the resource for bluetooth, must be prior to every bluetooth stuff.
Return
• Other : Failed
esp_err_t esp_bluedroid_deinit(void)
Deinit and free the resource for bluetooth, must be after every bluetooth stuff.
Return
• Other : Failed
Enumerations
enum esp_bluedroid_status_t
Bluetooth stack status type, to indicate whether the bluetooth stack is ready.
Values:
ESP_BLUEDROID_STATUS_UNINITIALIZED = 0
Bluetooth not initialized
ESP_BLUEDROID_STATUS_INITIALIZED
Bluetooth initialized but not enabled
ESP_BLUEDROID_STATUS_ENABLED
Bluetooth initialized and enabled
BT DEVICE APIs
Overview Bluetooth device reference APIs.

Instructions
API Reference
Header File
• components/bt/host/bluedroid/api/include/api/esp_bt_device.h

Functions
const uint8_t *esp_bt_dev_get_address(void)
Get bluetooth device address. Must use after esp_bluedroid_enable .
Return bluetooth device address (six bytes), or NULL if bluetooth stack is not enabled
esp_err_t esp_bt_dev_set_device_name(const char *name)
Set bluetooth device name. This function should be called after esp_bluedroid_enable() completes successfully.
A BR/EDR/LE device type shall have a single Bluetooth device name which shall be identical irrespective of
the physical channel used to perform the name discovery procedure.
Return
• ESP_ERR_INVALID_ARG : if name is NULL pointer or empty, or string length out of limit
• ESP_ERR_INVALID_STATE : if bluetooth stack is not yet enabled
• ESP_FAIL : others
Parameters
• [in] name: : device name to be set
2.1.3 BT LE
GAP API
Application Example Check bluetooth/bluedroid/ble folder in ESP-IDF examples, which contains the following
demos and their tutorials:
• This is a SMP security client demo and its tutorial. This demo initiates its security parameters and acts as a
GATT client, which can send a security request to the peer device and then complete the encryption procedure.
– bluetooth/bluedroid/ble/gatt_security_client
– GATT Security Client Example Walkthrough
• This is a SMP security server demo and its tutorial. This demo initiates its security parameters and acts as a
GATT server, which can send a pair request to the peer device and then complete the encryption procedure.
– bluetooth/bluedroid/ble/gatt_security_server
– GATT Security Server Example Walkthrough
API Reference
Header File
• components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h
Functions
esp_err_t esp_ble_gap_register_callback(esp_gap_ble_cb_t callback)
This function is called to occur gap event, such as scan result.
Return
• other : failed
Parameters
• [in] callback: callback function
esp_err_t esp_ble_gap_config_adv_data(esp_ble_adv_data_t *adv_data)
This function is called to override the BTA default ADV parameters.
Return
• other : failed

Parameters
• [in] adv_data: Pointer to User defined ADV data structure. This memory space can not be
freed until callback of config_adv_data is received.
esp_err_t esp_ble_gap_set_scan_params(esp_ble_scan_params_t *scan_params)
This function is called to set scan parameters.
Return
• other : failed
Parameters
• [in] scan_params: Pointer to User defined scan_params data structure. This memory space
can not be freed until callback of set_scan_params
esp_err_t esp_ble_gap_start_scanning(uint32_t duration)
This procedure keep the device scanning the peer device which advertising on the air.
Return
• other : failed
Parameters
• [in] duration: Keeping the scanning time, the unit is second.
esp_err_t esp_ble_gap_stop_scanning(void)
This function call to stop the device scanning the peer device which advertising on the air.
Return
– other : failed
esp_err_t esp_ble_gap_start_advertising(esp_ble_adv_params_t *adv_params)
This function is called to start advertising.
Return
• other : failed
Parameters
• [in] adv_params: pointer to User defined adv_params data structure.
esp_err_t esp_ble_gap_stop_advertising(void)
This function is called to stop advertising.
Return
• other : failed
esp_err_t esp_ble_gap_update_conn_params(esp_ble_conn_update_params_t *params)
Update connection parameters, can only be used when connection is up.
Return
• other : failed
Parameters
• [in] params: - connection update parameters
esp_err_t esp_ble_gap_set_pkt_data_len(esp_bd_addr_t remote_device, uint16_t
tx_data_length)
This function is to set maximum LE data packet size.
Return
• other : failed
esp_err_t esp_ble_gap_set_rand_addr(esp_bd_addr_t rand_addr)
This function sets the static Random Address and Non-Resolvable Private Address for the application.

Return
• other : failed
Parameters
• [in] rand_addr: the random address which should be setting
esp_err_t esp_ble_gap_clear_rand_addr(void)
This function clears the random address for the application.
Return
• other : failed
esp_err_t esp_ble_gap_config_local_privacy(bool privacy_enable)
Enable/disable privacy on the local device.
Return
• other : failed
Parameters
• [in] privacy_enable: - enable/disable privacy on remote device.
esp_err_t esp_ble_gap_config_local_icon(uint16_t icon)
set local gap appearance icon
Return
• other : failed
Parameters
• [in] icon: - External appearance value, these values are defined by the Bluetooth
SIG, please refer to https://www.bluetooth.com/specifications/gatt/viewer?attributeXmlFile=org.
bluetooth.characteristic.gap.appearance.xml
esp_err_t esp_ble_gap_update_whitelist(bool add_remove, esp_bd_addr_t remote_bda,
esp_ble_wl_addr_type_t wl_addr_type)
Add or remove device from white list.
Return
• other : failed
Parameters
• [in] add_remove: the value is true if added the ble device to the white list, and false remove
to the white list.
• [in] remote_bda: the remote device address add/remove from the white list.
• [in] wl_addr_type: whitelist address type
esp_err_t esp_ble_gap_clear_whitelist(void)
Clear all white list.
Return
• other : failed
esp_err_t esp_ble_gap_get_whitelist_size(uint16_t *length)
Get the whitelist size in the controller.
Return
• other : failed
Parameters
• [out] length: the white list length.

esp_err_t esp_ble_gap_set_prefer_conn_params(esp_bd_addr_t bd_addr, uint16_t

min_conn_int, uint16_t max_conn_int,
uint16_t slave_latency, uint16_t supervi-
sion_tout)
This function is called to set the preferred connection parameters when default connection parameter is not
desired before connecting. This API can only be used in the master role.
Return
• other : failed
Parameters
• [in] bd_addr: BD address of the peripheral
• [in] min_conn_int: minimum preferred connection interval
• [in] max_conn_int: maximum preferred connection interval
• [in] slave_latency: preferred slave latency
• [in] supervision_tout: preferred supervision timeout
esp_err_t esp_ble_gap_set_device_name(const char *name)
Set device name to the local device.
Return
• other : failed
Parameters
• [in] name: - device name.
esp_err_t esp_ble_gap_get_local_used_addr(esp_bd_addr_t local_used_addr, uint8_t
*addr_type)
This function is called to get local used address and adress type. uint8_t *esp_bt_dev_get_address(void) get
the public address.
Return - ESP_OK : success
• other : failed
Parameters
• [in] local_used_addr: - current local used ble address (six bytes)
• [in] addr_type: - ble address type
uint8_t *esp_ble_resolve_adv_data(uint8_t *adv_data, uint8_t type, uint8_t *length)
This function is called to get ADV data for a specific type.
Return pointer of ADV data
Parameters
• [in] adv_data: - pointer of ADV data which to be resolved
• [in] type: - finding ADV data type
• [out] length: - return the length of ADV data not including type
esp_err_t esp_ble_gap_config_adv_data_raw(uint8_t *raw_data, uint32_t raw_data_len)
This function is called to set raw advertising data. User need to fill ADV data by self.
Return
• other : failed
Parameters
• [in] raw_data: : raw advertising data
• [in] raw_data_len: : raw advertising data length , less than 31 bytes
esp_err_t esp_ble_gap_config_scan_rsp_data_raw(uint8_t *raw_data, uint32_t
raw_data_len)
This function is called to set raw scan response data. User need to fill scan response data by self.
Return
• other : failed
Parameters

• [in] raw_data: : raw scan response data

• [in] raw_data_len: : raw scan response data length , less than 31 bytes
esp_err_t esp_ble_gap_read_rssi(esp_bd_addr_t remote_addr)
This function is called to read the RSSI of remote device. The address of link policy results are returned in the
gap callback function with ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT event.
Return
• other : failed
Parameters
• [in] remote_addr: : The remote connection device address.
esp_err_t esp_ble_gap_add_duplicate_scan_exceptional_device(esp_ble_duplicate_exceptional_info_type_t
type,
esp_duplicate_info_t
device_info)
This function is called to add a device info into the duplicate scan exceptional list.
Return
• other : failed
Parameters
• [in] type: device info type, it is defined in esp_ble_duplicate_exceptional_info_type_t when
type is MESH_BEACON_TYPE, MESH_PROV_SRV_ADV or MESH_PROXY_SRV_ADV ,
device_info is invalid.
• [in] device_info: the device information.
esp_err_t esp_ble_gap_remove_duplicate_scan_exceptional_device(esp_ble_duplicate_exceptional_info_type_t
type,
esp_duplicate_info_t
device_info)
This function is called to remove a device info from the duplicate scan exceptional list.
Return
• other : failed
Parameters
• [in] type: device info type, it is defined in esp_ble_duplicate_exceptional_info_type_t when
type is MESH_BEACON_TYPE, MESH_PROV_SRV_ADV or MESH_PROXY_SRV_ADV ,
device_info is invalid.
• [in] device_info: the device information.
esp_err_t esp_ble_gap_clean_duplicate_scan_exceptional_list(esp_duplicate_scan_exceptional_list_type_t
list_type)
This function is called to clean the duplicate scan exceptional list. This API will delete all device information
in the duplicate scan exceptional list.
Return
• other : failed
Parameters
• [in] list_type: duplicate scan exceptional list type, the value can be one or more of
esp_duplicate_scan_exceptional_list_type_t.
esp_err_t esp_ble_gap_set_security_param(esp_ble_sm_param_t param_type, void *value,
uint8_t len)
Set a GAP security parameter value. Overrides the default value.
Secure connection is highly recommended to avoid some major vulnerabilities like Impersonation in the Pin
Pairing Protocol (CVE-2020-26555) and Authentication of the LE Legacy Pairing Protocol .
To accept only secure connection mode, it is necessary do as following:

1. Set bit ESP_LE_AUTH_REQ_SC_ONLY (param_type is ESP_BLE_SM_AUTHEN_REQ_MODE),

bit ESP_LE_AUTH_BOND and bit ESP_LE_AUTH_REQ_MITM is optional as required.
2. Set to ESP_BLE_ONLY_ACCEPT_SPECIFIED_AUTH_ENABLE (param_type is
ESP_BLE_SM_ONLY_ACCEPT_SPECIFIED_SEC_AUTH).
• other : failed
Parameters
• [in] param_type: : the type of the param which to be set
• [in] value: : the param value
• [in] len: : the length of the param value
esp_err_t esp_ble_gap_security_rsp(esp_bd_addr_t bd_addr, bool accept)
Grant security request access.
• other : failed
Parameters
• [in] bd_addr: : BD address of the peer
• [in] accept: : accept the security request or not
esp_err_t esp_ble_set_encryption(esp_bd_addr_t bd_addr, esp_ble_sec_act_t sec_act)
Set a gap parameter value. Use this function to change the default GAP parameter values.
• other : failed
Parameters
• [in] bd_addr: : the address of the peer device need to encryption
• [in] sec_act: : This is the security action to indicate what kind of BLE security level is required
for the BLE link if the BLE is supported
esp_err_t esp_ble_passkey_reply(esp_bd_addr_t bd_addr, bool accept, uint32_t passkey)
Reply the key value to the peer device in the legacy connection stage.
• other : failed
Parameters
• [in] accept: : passkey entry successful or declined.
• [in] passkey: : passkey value, must be a 6 digit number, can be lead by 0.
esp_err_t esp_ble_confirm_reply(esp_bd_addr_t bd_addr, bool accept)
Reply the confirm value to the peer device in the secure connection stage.
• other : failed
Parameters
• [in] bd_addr: : BD address of the peer device
• [in] accept: : numbers to compare are the same or different.
esp_err_t esp_ble_remove_bond_device(esp_bd_addr_t bd_addr)
Removes a device from the security database list of peer device. It manages unpairing event while connected.
• other : failed
Parameters
int esp_ble_get_bond_device_num(void)
Get the device number from the security database list of peer device. It will return the device bonded number
immediately.
Return - >= 0 : bonded devices number.
• ESP_FAIL : failed

esp_err_t esp_ble_get_bond_device_list(int *dev_num, esp_ble_bond_dev_t *dev_list)

Get the device from the security database list of peer device. It will return the device bonded information
immediately.
• other : failed
Parameters
• [inout] dev_num: Indicate the dev_list array(buffer) size as input. If dev_num is
large enough, it means the actual number as output. Suggest that dev_num value equal to
esp_ble_get_bond_device_num().
• [out] dev_list: an array(buffer) of esp_ble_bond_dev_t type. Use for storing the
bonded devices address. The dev_list should be allocated by who call this API.
esp_err_t esp_ble_oob_req_reply(esp_bd_addr_t bd_addr, uint8_t *TK, uint8_t len)
This function is called to provide the OOB data for SMP in response to ESP_GAP_BLE_OOB_REQ_EVT.
• other : failed
Parameters
• [in] bd_addr: BD address of the peer device.
• [in] TK: TK value, the TK value shall be a 128-bit random number
• [in] len: length of tk, should always be 128-bit
esp_err_t esp_ble_gap_disconnect(esp_bd_addr_t remote_device)
This function is to disconnect the physical connection of the peer device gattc may have multiple virtual GATT
server connections when multiple app_id registered. esp_ble_gattc_close (esp_gatt_if_t gattc_if, uint16_t
conn_id) only close one virtual GATT server connection. if there exist other virtual GATT server connec-
tions, it does not disconnect the physical connection. esp_ble_gap_disconnect(esp_bd_addr_t remote_device)
disconnect the physical connection directly.
• other : failed
Parameters
• [in] remote_device: : BD address of the peer device
esp_err_t esp_ble_get_current_conn_params(esp_bd_addr_t bd_addr, esp_gap_conn_params_t
*conn_params)
This function is called to read the connection parameters information of the device.
• other : failed
Parameters
• [out] conn_params: the connection parameters information
esp_err_t esp_gap_ble_set_channels(esp_gap_ble_channels channels)
BLE set channels.
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• other : failed
Parameters
• [in] channels: : The n th such field (in the range 0 to 36) contains the value for the link layer
channel index n. 0 means channel n is bad. 1 means channel n is unknown. The most significant bits
are reserved and shall be set to 0. At least one channel shall be marked as unknown.
esp_err_t esp_gap_ble_set_authorization(esp_bd_addr_t bd_addr, bool authorize)
This function is called to authorized a link after Authentication(MITM protection)
• other : failed
Parameters
• [out] authorize: Authorized the link or not.

esp_err_t esp_ble_gap_read_phy(esp_bd_addr_t bd_addr)

This function is used to read the current transmitter PHY and receiver PHY on the connection identified by
remote address.
• other : failed
Parameters
esp_err_t esp_ble_gap_set_prefered_default_phy(esp_ble_gap_phy_mask_t tx_phy_mask,
esp_ble_gap_phy_mask_t rx_phy_mask)
This function is used to allows the Host to specify its preferred values for the transmitter PHY and receiver
PHY to be used for all subsequent connections over the LE transport.
• other : failed
Parameters
• [in] tx_phy_mask: : indicates the transmitter PHYs that the Host prefers the Controller to
use
• [in] rx_phy_mask: : indicates the receiver PHYs that the Host prefers the Controller to use
esp_err_t esp_ble_gap_set_prefered_phy(esp_bd_addr_t bd_addr, esp_ble_gap_all_phys_t
all_phys_mask, esp_ble_gap_phy_mask_t
tx_phy_mask, esp_ble_gap_phy_mask_t rx_phy_mask,
esp_ble_gap_prefer_phy_options_t phy_options)
This function is used to set the PHY preferences for the connection identified by the remote address. The
Controller might not be able to make the change (e.g. because the peer does not support the requested PHY)
or may decide that the current PHY is preferable.
• other : failed
Parameters
• [in] bd_addr: : remote address
• [in] all_phys_mask: : a bit field that allows the Host to specify
• [in] tx_phy_mask: : a bit field that indicates the transmitter PHYs that the Host prefers the
Controller to use
• [in] rx_phy_mask: : a bit field that indicates the receiver PHYs that the Host prefers the
Controller to use
• [in] phy_options: : a bit field that allows the Host to specify options for PHYs
esp_err_t esp_ble_gap_ext_adv_set_rand_addr(uint8_t instance, esp_bd_addr_t rand_addr)
This function is used by the Host to set the random device address specified by the Random_Address parameter.
• other : failed
Parameters
• [in] instance: : Used to identify an advertising set
• [in] rand_addr: : Random Device Address
esp_err_t esp_ble_gap_ext_adv_set_params(uint8_t instance, const
esp_ble_gap_ext_adv_params_t *params)
This function is used by the Host to set the advertising parameters.
• other : failed
Parameters
• [in] instance: : identifies the advertising set whose parameters are being configured.
• [in] params: : advertising parameters
esp_err_t esp_ble_gap_config_ext_adv_data_raw(uint8_t instance, uint16_t length, const
uint8_t *data)
This function is used to set the data used in advertising PDUs that have a data field.

• other : failed
Parameters
• [in] instance: : identifies the advertising set whose data are being configured
• [in] length: : data length
• [in] data: : data information
esp_err_t esp_ble_gap_config_ext_scan_rsp_data_raw(uint8_t instance, uint16_t length,
const uint8_t *scan_rsp_data)
This function is used to provide scan response data used in scanning response PDUs.
• other : failed
Parameters
• [in] instance: : identifies the advertising set whose response data are being configured.
• [in] length: : responsedata length
• [in] scan_rsp_data: : response data information
esp_err_t esp_ble_gap_ext_adv_start(uint8_t num_adv, const esp_ble_gap_ext_adv_t
*ext_adv)
This function is used to request the Controller to enable one or more advertising sets using the advertising sets
identified by the instance parameter.
• other : failed
Parameters
• [in] num_adv: : Number of advertising sets to enable or disable
• [in] ext_adv: : adv parameters
esp_err_t esp_ble_gap_ext_adv_stop(uint8_t num_adv, const uint8_t *ext_adv_inst)
This function is used to request the Controller to disable one or more advertising sets using the advertising sets
identified by the instance parameter.
• other : failed
Parameters
• [in] num_adv: : Number of advertising sets to enable or disable
• [in] ext_adv_inst: : ext adv instance
esp_err_t esp_ble_gap_ext_adv_set_remove(uint8_t instance)
This function is used to remove an advertising set from the Controller.
• other : failed
Parameters
esp_err_t esp_ble_gap_ext_adv_set_clear(void)
This function is used to remove all existing advertising sets from the Controller.
• other : failed
esp_err_t esp_ble_gap_periodic_adv_set_params(uint8_t instance, const
esp_ble_gap_periodic_adv_params_t
*params)
This function is used by the Host to set the parameters for periodic advertising.
• other : failed
Parameters
• [in] instance: : identifies the advertising set whose periodic advertising parameters are being
configured.
• [in] params: : periodic adv parameters

esp_err_t esp_ble_gap_config_periodic_adv_data_raw(uint8_t instance, uint16_t length,

const uint8_t *data)
This function is used to set the data used in periodic advertising PDUs.
• other : failed
Parameters
• [in] instance: : identifies the advertising set whose periodic advertising parameters are being
configured.
• [in] length: : the length of periodic data
• [in] data: : periodic data information
esp_err_t esp_ble_gap_periodic_adv_start(uint8_t instance)
This function is used to request the Controller to enable the periodic advertising for the advertising set specified.
• other : failed
Parameters
esp_err_t esp_ble_gap_periodic_adv_stop(uint8_t instance)
This function is used to request the Controller to disable the periodic advertising for the advertising set specified.
• other : failed
Parameters
esp_err_t esp_ble_gap_set_ext_scan_params(const esp_ble_ext_scan_params_t *params)
This function is used to set the extended scan parameters to be used on the advertising channels.
• other : failed
Parameters
• [in] params: : scan parameters
esp_err_t esp_ble_gap_start_ext_scan(uint32_t duration, uint16_t period)
This function is used to enable scanning.
• other : failed
Parameters
• [in] duration: : Scan duration
• [in] period: : Time interval from when the Controller started its last Scan Duration until it
begins the subsequent Scan Duration.
esp_err_t esp_ble_gap_stop_ext_scan(void)
This function is used to disable scanning.
• other : failed
esp_err_t esp_ble_gap_periodic_adv_create_sync(const esp_ble_gap_periodic_adv_sync_params_t
*params)
This function is used to synchronize with periodic advertising from an advertiser and begin receiving periodic
advertising packets.
• other : failed
Parameters
• [in] params: : sync parameters
esp_err_t esp_ble_gap_periodic_adv_sync_cancel(void)
This function is used to cancel the LE_Periodic_Advertising_Create_Sync command while it is pending.

• other : failed
esp_err_t esp_ble_gap_periodic_adv_sync_terminate(uint16_t sync_handle)
This function is used to stop reception of the periodic advertising identified by the Sync Handle parameter.
• other : failed
Parameters
• [in] sync_handle: : identify the periodic advertiser
esp_err_t esp_ble_gap_periodic_adv_add_dev_to_list(esp_ble_addr_type_t addr_type,
esp_bd_addr_t addr, uint8_t sid)
This function is used to add a single device to the Periodic Advertiser list stored in the Controller.
• other : failed
Parameters
• [in] addr_type: : address type
• [in] addr: : Device Address
• [in] sid: : Advertising SID subfield in the ADI field used to identify the Periodic Advertising
esp_err_t esp_ble_gap_periodic_adv_remove_dev_from_list(esp_ble_addr_type_t
addr_type, esp_bd_addr_t
addr, uint8_t sid)
This function is used to remove one device from the list of Periodic Advertisers stored in the Controller.
Removals from the Periodic Advertisers List take effect immediately.
• other : failed
Parameters
• [in] addr_type: : address type
• [in] addr: : Device Address
• [in] sid: : Advertising SID subfield in the ADI field used to identify the Periodic Advertising
esp_err_t esp_ble_gap_periodic_adv_clear_dev(void)
This function is used to remove all devices from the list of Periodic Advertisers in the Controller.
• other : failed
esp_err_t esp_ble_gap_prefer_ext_connect_params_set(esp_bd_addr_t addr,
esp_ble_gap_phy_mask_t
phy_mask, const
esp_ble_gap_conn_params_t
*phy_1m_conn_params, const
*phy_2m_conn_params, const
*phy_coded_conn_params)
This function is used to set aux connection parameters.
• other : failed
Parameters
• [in] addr: : device address
• [in] phy_mask: : indicates the PHY(s) on which the advertising packets should be received on
the primary advertising channel and the PHYs for which connection parameters have been specified.
• [in] phy_1m_conn_params: : Scan connectable advertisements on the LE 1M PHY. Con-
nection parameters for the LE 1M PHY are provided.
• [in] phy_2m_conn_params: : Connection parameters for the LE 2M PHY are provided.
• [in] phy_coded_conn_params: : Scan connectable advertisements on the LE Coded PHY.
Connection parameters for the LE Coded PHY are provided.

Unions
union esp_ble_key_value_t
#include <esp_gap_ble_api.h> union type of the security key value
Public Members
esp_ble_penc_keys_t penc_key
received peer encryption key
esp_ble_pcsrk_keys_t pcsrk_key
received peer device SRK
esp_ble_pid_keys_t pid_key
peer device ID key
esp_ble_lenc_keys_t lenc_key
local encryption reproduction keys LTK = = d1(ER,DIV,0)
esp_ble_lcsrk_keys lcsrk_key
local device CSRK = d1(ER,DIV,1)
union esp_ble_sec_t
#include <esp_gap_ble_api.h> union associated with ble security
Public Members
esp_ble_sec_key_notif_t key_notif
passkey notification
esp_ble_sec_req_t ble_req
BLE SMP related request
esp_ble_key_t ble_key
BLE SMP keys used when pairing
esp_ble_local_id_keys_t ble_id_keys
BLE IR event
esp_ble_auth_cmpl_t auth_cmpl
Authentication complete indication.
union esp_ble_gap_cb_param_t
#include <esp_gap_ble_api.h> Gap callback parameters union.
Public Members
struct esp_ble_gap_cb_param_t::ble_adv_data_cmpl_evt_param adv_data_cmpl

Event parameter of ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_scan_rsp_data_cmpl_evt_param scan_rsp_data_cmpl
Event parameter of ESP_GAP_BLE_SCAN_RSP_DATA_SET_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_scan_param_cmpl_evt_param scan_param_cmpl
Event parameter of ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_scan_result_evt_param scan_rst
Event parameter of ESP_GAP_BLE_SCAN_RESULT_EVT
struct esp_ble_gap_cb_param_t::ble_adv_data_raw_cmpl_evt_param adv_data_raw_cmpl
Event parameter of ESP_GAP_BLE_ADV_DATA_RAW_SET_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_scan_rsp_data_raw_cmpl_evt_param scan_rsp_data_raw_cmpl
Event parameter of ESP_GAP_BLE_SCAN_RSP_DATA_RAW_SET_COMPLETE_EVT

struct esp_ble_gap_cb_param_t::ble_adv_start_cmpl_evt_param adv_start_cmpl

Event parameter of ESP_GAP_BLE_ADV_START_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_scan_start_cmpl_evt_param scan_start_cmpl
Event parameter of ESP_GAP_BLE_SCAN_START_COMPLETE_EVT
esp_ble_sec_t ble_security
ble gap security union type
struct esp_ble_gap_cb_param_t::ble_scan_stop_cmpl_evt_param scan_stop_cmpl
Event parameter of ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_adv_stop_cmpl_evt_param adv_stop_cmpl
Event parameter of ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_set_rand_cmpl_evt_param set_rand_addr_cmpl
Event parameter of ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT
struct esp_ble_gap_cb_param_t::ble_update_conn_params_evt_param update_conn_params
Event parameter of ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT
struct esp_ble_gap_cb_param_t::ble_pkt_data_length_cmpl_evt_param pkt_data_lenth_cmpl
Event parameter of ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_local_privacy_cmpl_evt_param local_privacy_cmpl
Event parameter of ESP_GAP_BLE_SET_LOCAL_PRIVACY_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_remove_bond_dev_cmpl_evt_param remove_bond_dev_cmpl
Event parameter of ESP_GAP_BLE_REMOVE_BOND_DEV_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_clear_bond_dev_cmpl_evt_param clear_bond_dev_cmpl
Event parameter of ESP_GAP_BLE_CLEAR_BOND_DEV_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_get_bond_dev_cmpl_evt_param get_bond_dev_cmpl
Event parameter of ESP_GAP_BLE_GET_BOND_DEV_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_read_rssi_cmpl_evt_param read_rssi_cmpl
Event parameter of ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_update_whitelist_cmpl_evt_param update_whitelist_cmpl
Event parameter of ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_update_duplicate_exceptional_list_cmpl_evt_param update_duplicate_excepti
Event parameter of ESP_GAP_BLE_UPDATE_DUPLICATE_EXCEPTIONAL_LIST_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_set_channels_evt_param ble_set_channels
Event parameter of ESP_GAP_BLE_SET_CHANNELS_EVT
struct esp_ble_gap_cb_param_t::ble_read_phy_cmpl_evt_param read_phy
Event parameter of ESP_GAP_BLE_READ_PHY_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_set_perf_def_phy_cmpl_evt_param set_perf_def_phy
Event parameter of ESP_GAP_BLE_SET_PREFERED_DEFAULT_PHY_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_set_perf_phy_cmpl_evt_param set_perf_phy
Event parameter of ESP_GAP_BLE_SET_PREFERED_PHY_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_adv_set_rand_addr_cmpl_evt_param ext_adv_set_rand_addr
Event parameter of ESP_GAP_BLE_EXT_ADV_SET_RAND_ADDR_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_adv_set_params_cmpl_evt_param ext_adv_set_params
Event parameter of ESP_GAP_BLE_EXT_ADV_SET_PARAMS_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_adv_data_set_cmpl_evt_param ext_adv_data_set
Event parameter of ESP_GAP_BLE_EXT_ADV_DATA_SET_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_adv_scan_rsp_set_cmpl_evt_param scan_rsp_set
Event parameter of ESP_GAP_BLE_EXT_SCAN_RSP_DATA_SET_COMPLETE_EVT

struct esp_ble_gap_cb_param_t::ble_ext_adv_start_cmpl_evt_param ext_adv_start

Event parameter of ESP_GAP_BLE_EXT_ADV_START_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_adv_stop_cmpl_evt_param ext_adv_stop
Event parameter of ESP_GAP_BLE_EXT_ADV_STOP_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_adv_set_remove_cmpl_evt_param ext_adv_remove
Event parameter of ESP_GAP_BLE_EXT_ADV_SET_REMOVE_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_adv_set_clear_cmpl_evt_param ext_adv_clear
Event parameter of ESP_GAP_BLE_EXT_ADV_SET_CLEAR_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_periodic_adv_set_params_cmpl_param peroid_adv_set_params
Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SET_PARAMS_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_periodic_adv_data_set_cmpl_param period_adv_data_set
Event parameter of ESP_GAP_BLE_PERIODIC_ADV_DATA_SET_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_periodic_adv_start_cmpl_param period_adv_start
Event parameter of ESP_GAP_BLE_PERIODIC_ADV_START_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_periodic_adv_stop_cmpl_param period_adv_stop
Event parameter of ESP_GAP_BLE_PERIODIC_ADV_STOP_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_period_adv_create_sync_cmpl_param period_adv_create_sync
Event parameter of ESP_GAP_BLE_PERIODIC_ADV_CREATE_SYNC_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_period_adv_sync_cancel_cmpl_param period_adv_sync_cancel
Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SYNC_CANCEL_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_period_adv_sync_terminate_cmpl_param period_adv_sync_term
Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SYNC_TERMINATE_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_period_adv_add_dev_cmpl_param period_adv_add_dev
Event parameter of ESP_GAP_BLE_PERIODIC_ADV_ADD_DEV_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_period_adv_remove_dev_cmpl_param period_adv_remove_dev
Event parameter of ESP_GAP_BLE_PERIODIC_ADV_REMOVE_DEV_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_period_adv_clear_dev_cmpl_param period_adv_clear_dev
Event parameter of ESP_GAP_BLE_PERIODIC_ADV_CLEAR_DEV_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_set_ext_scan_params_cmpl_param set_ext_scan_params
Event parameter of ESP_GAP_BLE_SET_EXT_SCAN_PARAMS_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_scan_start_cmpl_param ext_scan_start
Event parameter of ESP_GAP_BLE_EXT_SCAN_START_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_scan_stop_cmpl_param ext_scan_stop
Event parameter of ESP_GAP_BLE_EXT_SCAN_STOP_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_conn_params_set_cmpl_param ext_conn_params_set
Event parameter of ESP_GAP_BLE_PREFER_EXT_CONN_PARAMS_SET_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_adv_terminate_param adv_terminate
Event parameter of ESP_GAP_BLE_ADV_TERMINATED_EVT
struct esp_ble_gap_cb_param_t::ble_scan_req_received_param scan_req_received
Event parameter of ESP_GAP_BLE_SCAN_REQ_RECEIVED_EVT
struct esp_ble_gap_cb_param_t::ble_channel_sel_alg_param channel_sel_alg
Event parameter of ESP_GAP_BLE_CHANNEL_SELETE_ALGORITHM_EVT
struct esp_ble_gap_cb_param_t::ble_periodic_adv_sync_lost_param periodic_adv_sync_lost
Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SYNC_LOST_EVT
struct esp_ble_gap_cb_param_t::ble_periodic_adv_sync_estab_param periodic_adv_sync_estab
Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SYNC_ESTAB_EVT

struct esp_ble_gap_cb_param_t::ble_phy_update_cmpl_param phy_update

Event parameter of ESP_GAP_BLE_PHY_UPDATE_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_adv_report_param ext_adv_report
Event parameter of ESP_GAP_BLE_EXT_ADV_REPORT_EVT
struct esp_ble_gap_cb_param_t::ble_periodic_adv_report_param period_adv_report
Event parameter of ESP_GAP_BLE_PERIODIC_ADV_REPORT_EVT
struct ble_adv_data_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT.
Public Members
esp_bt_status_t status
Indicate the set advertising data operation success status
struct ble_adv_data_raw_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_ADV_DATA_RAW_SET_COMPLETE_EVT.
Public Members
Indicate the set raw advertising data operation success status
struct ble_adv_start_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_ADV_START_COMPLETE_EVT.
Public Members
Indicate advertising start operation success status
struct ble_adv_stop_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT.
Public Members
Indicate adv stop operation success status
struct ble_adv_terminate_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_ADV_TERMINATED_EVT.
Public Members
uint8_t status
Indicate adv terminate status
uint8_t adv_instance
extend advertising handle
uint16_t conn_idx
connection index
uint8_t completed_event
the number of completed extend advertising events

struct ble_channel_sel_alg_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_CHANNEL_SELETE_ALGORITHM_EVT.
Public Members
uint16_t conn_handle
connection handle
uint8_t channel_sel_alg
channel selection algorithm
struct ble_clear_bond_dev_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_CLEAR_BOND_DEV_COMPLETE_EVT.
Public Members
Indicate the clear bond device operation success status
struct ble_ext_adv_data_set_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_ADV_DATA_SET_COMPLETE_EVT.
Public Members
Indicate extend advertising data set status
struct ble_ext_adv_report_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_ADV_REPORT_EVT.
Public Members
esp_ble_gap_ext_adv_reprot_t params
extend advertising report parameters
struct ble_ext_adv_scan_rsp_set_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_SCAN_RSP_DATA_SET_COMPLETE_EVT.
Public Members
Indicate extend advertising sacn response data set status
struct ble_ext_adv_set_clear_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_ADV_SET_CLEAR_COMPLETE_EVT.
Public Members
Indicate advertising stop operation success status
struct ble_ext_adv_set_params_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_ADV_SET_PARAMS_COMPLETE_EVT.

Public Members
Indicate extend advertising parameters set status
struct ble_ext_adv_set_rand_addr_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_ADV_SET_RAND_ADDR_COMPLETE_EVT.
Public Members
Indicate extend advertising random address set status
struct ble_ext_adv_set_remove_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_ADV_SET_REMOVE_COMPLETE_EVT.
Public Members
struct ble_ext_adv_start_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_ADV_START_COMPLETE_EVT.
Public Members
Indicate advertising start operation success status
struct ble_ext_adv_stop_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_ADV_STOP_COMPLETE_EVT.
Public Members
struct ble_ext_conn_params_set_cmpl_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_PREFER_EXT_CONN_PARAMS_SET_COMPLETE_EVT.
Public Members
Indicate extend connection parameters set status
struct ble_ext_scan_start_cmpl_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_SCAN_START_COMPLETE_EVT.
Public Members
Indicate extend advertising start status
struct ble_ext_scan_stop_cmpl_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_SCAN_STOP_COMPLETE_EVT.

Public Members
Indicate extend advertising stop status
struct ble_get_bond_dev_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_GET_BOND_DEV_COMPLETE_EVT.
Public Members
Indicate the get bond device operation success status
uint8_t dev_num
Indicate the get number device in the bond list
esp_ble_bond_dev_t *bond_dev
the pointer to the bond device Structure
struct ble_local_privacy_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_SET_LOCAL_PRIVACY_COMPLETE_EVT.
Public Members
Indicate the set local privacy operation success status
struct ble_period_adv_add_dev_cmpl_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_ADD_DEV_COMPLETE_EVT.
Public Members
Indicate periodic advertising device list add status
struct ble_period_adv_clear_dev_cmpl_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_CLEAR_DEV_COMPLETE_EVT.
Public Members
Indicate periodic advertising device list clean status
struct ble_period_adv_create_sync_cmpl_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_CREATE_SYNC_COMPLETE_EVT.
Public Members
Indicate periodic advertising create sync status
struct ble_period_adv_remove_dev_cmpl_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_REMOVE_DEV_COMPLETE_EVT.

Public Members
Indicate periodic advertising device list remove status
struct ble_period_adv_sync_cancel_cmpl_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_SYNC_CANCEL_COMPLETE_EVT.
Public Members
Indicate periodic advertising sync cancle status
struct ble_period_adv_sync_terminate_cmpl_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_SYNC_TERMINATE_COMPLETE_EVT.
Public Members
Indicate periodic advertising sync terminate status
struct ble_periodic_adv_data_set_cmpl_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_DATA_SET_COMPLETE_EVT.
Public Members
Indicate periodic advertising data set status
struct ble_periodic_adv_report_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_REPORT_EVT.
Public Members
esp_ble_gap_periodic_adv_report_t params
periodic advertising report parameters
struct ble_periodic_adv_set_params_cmpl_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_SET_PARAMS_COMPLETE_EVT.
Public Members
Indicate periodic advertisingparameters set status
struct ble_periodic_adv_start_cmpl_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_START_COMPLETE_EVT.
Public Members
Indicate periodic advertising start status
struct ble_periodic_adv_stop_cmpl_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_STOP_COMPLETE_EVT.

Public Members
Indicate periodic advertising stop status
struct ble_periodic_adv_sync_estab_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_SYNC_ESTAB_EVT.
Public Members
uint8_t status
periodic advertising sync status
uint16_t sync_handle
periodic advertising sync handle
uint8_t sid
periodic advertising sid
esp_ble_addr_type_t adv_addr_type
periodic advertising address type
esp_bd_addr_t adv_addr
periodic advertising address
esp_ble_gap_phy_t adv_phy
periodic advertising phy type
uint16_t period_adv_interval
periodic advertising interval
uint8_t adv_clk_accuracy
periodic advertising clock accuracy
struct ble_periodic_adv_sync_lost_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_SYNC_LOST_EVT.
Public Members
sync handle
struct ble_phy_update_cmpl_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_PHY_UPDATE_COMPLETE_EVT.
Public Members
phy update status
esp_bd_addr_t bda
address
esp_ble_gap_phy_t tx_phy
tx phy type
esp_ble_gap_phy_t rx_phy
rx phy type
struct ble_pkt_data_length_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVT.

Public Members
Indicate the set pkt data length operation success status
esp_ble_pkt_data_length_params_t params
pkt data length value
struct ble_read_phy_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_READ_PHY_COMPLETE_EVT.
Public Members
read phy complete status
esp_bd_addr_t bda
read phy address
esp_ble_gap_phy_t tx_phy
tx phy type
esp_ble_gap_phy_t rx_phy
rx phy type
struct ble_read_rssi_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT.
Public Members
Indicate the read adv tx power operation success status
int8_t rssi
The ble remote device rssi value, the range is from -127 to 20, the unit is dbm, if the RSSI cannot
be read, the RSSI metric shall be set to 127.
esp_bd_addr_t remote_addr
The remote device address
struct ble_remove_bond_dev_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_REMOVE_BOND_DEV_COMPLETE_EVT.
Public Members
Indicate the remove bond device operation success status
esp_bd_addr_t bd_addr
The device address which has been remove from the bond list
struct ble_scan_param_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT.
Public Members
Indicate the set scan param operation success status

struct ble_scan_req_received_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_SCAN_REQ_RECEIVED_EVT.
Public Members
uint8_t adv_instance
extend advertising handle
esp_ble_addr_type_t scan_addr_type
scanner address type
esp_bd_addr_t scan_addr
scanner address
struct ble_scan_result_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_SCAN_RESULT_EVT.
Public Members
esp_gap_search_evt_t search_evt
Search event type
esp_bd_addr_t bda
Bluetooth device address which has been searched
esp_bt_dev_type_t dev_type
Device type
esp_ble_addr_type_t ble_addr_type
Ble device address type
esp_ble_evt_type_t ble_evt_type
Ble scan result event type
int rssi
Searched device s RSSI
uint8_t ble_adv[ESP_BLE_ADV_DATA_LEN_MAX + ESP_BLE_SCAN_RSP_DATA_LEN_MAX]
Received EIR
int flag
Advertising data flag bit
int num_resps
Scan result number
uint8_t adv_data_len
Adv data length
uint8_t scan_rsp_len
Scan response length
uint32_t num_dis
The number of discard packets
struct ble_scan_rsp_data_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_SCAN_RSP_DATA_SET_COMPLETE_EVT.
Public Members
Indicate the set scan response data operation success status

struct ble_scan_rsp_data_raw_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_SCAN_RSP_DATA_RAW_SET_COMPLETE_EVT.
Public Members
Indicate the set raw advertising data operation success status
struct ble_scan_start_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_SCAN_START_COMPLETE_EVT.
Public Members
Indicate scan start operation success status
struct ble_scan_stop_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT.
Public Members
Indicate scan stop operation success status
struct ble_set_channels_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_SET_CHANNELS_EVT.
Public Members
esp_bt_status_t stat
BLE set channel status
struct ble_set_ext_scan_params_cmpl_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_SET_EXT_SCAN_PARAMS_COMPLETE_EVT.
Public Members
Indicate extend advertising parameters set status
struct ble_set_perf_def_phy_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_SET_PREFERED_DEFAULT_PHY_COMPLETE_EVT.
Public Members
Indicate perf default phy set status
struct ble_set_perf_phy_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_SET_PREFERED_PHY_COMPLETE_EVT.

Public Members
Indicate perf phy set status
struct ble_set_rand_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT.
Public Members
Indicate set static rand address operation success status
struct ble_update_conn_params_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT.
Public Members
Indicate update connection parameters success status
esp_bd_addr_t bda
Bluetooth device address
uint16_t min_int
Min connection interval
uint16_t max_int
Max connection interval
uint16_t latency
Slave latency for the connection in number of connection events. Range: 0x0000 to 0x01F3
uint16_t conn_int
Current connection interval
uint16_t timeout
Supervision timeout for the LE Link. Range: 0x000A to 0x0C80. Mandatory Range: 0x000A to
0x0C80 Time = N * 10 msec
struct ble_update_duplicate_exceptional_list_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_UPDATE_DUPLICATE_EXCEPTIONAL_LIST_COMPLETE_EVT.
Public Members
Indicate update duplicate scan exceptional list operation success status
uint8_t subcode
Define in esp_bt_duplicate_exceptional_subcode_type_t
uint16_t length
The length of device_info
esp_duplicate_info_t device_info
device information, when subcode is ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_CLEAN,
the value is invalid
struct ble_update_whitelist_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT.

Public Members
Indicate the add or remove whitelist operation success status
esp_ble_wl_opration_t wl_opration
The value is ESP_BLE_WHITELIST_ADD if add address to whitelist operation success,
ESP_BLE_WHITELIST_REMOVE if remove address from the whitelist operation success
Structures
struct esp_ble_adv_params_t
Advertising parameters.
Public Members
uint16_t adv_int_min
Minimum advertising interval for undirected and low duty cycle directed advertising. Range: 0x0020 to
0x4000 Default: N = 0x0800 (1.28 second) Time = N * 0.625 msec Time Range: 20 ms to 10.24 sec
uint16_t adv_int_max
Maximum advertising interval for undirected and low duty cycle directed advertising. Range: 0x0020 to
0x4000 Default: N = 0x0800 (1.28 second) Time = N * 0.625 msec Time Range: 20 ms to 10.24 sec
Advertising max interval
esp_ble_adv_type_t adv_type
Advertising type
esp_ble_addr_type_t own_addr_type
Owner bluetooth device address type
esp_bd_addr_t peer_addr
Peer device bluetooth device address
esp_ble_addr_type_t peer_addr_type
Peer device bluetooth device address type, only support public address type and random address type
esp_ble_adv_channel_t channel_map
Advertising channel map
esp_ble_adv_filter_t adv_filter_policy
Advertising filter policy
struct esp_ble_adv_data_t
Advertising data content, according to Supplement to the Bluetooth Core Specification .
Public Members
bool set_scan_rsp
Set this advertising data as scan response or not
bool include_name
Advertising data include device name or not
bool include_txpower
Advertising data include TX power
int min_interval
Advertising data show slave preferred connection min interval. The connection interval in the following
manner: connIntervalmin = Conn_Interval_Min * 1.25 ms Conn_Interval_Min range: 0x0006 to 0x0C80
Value of 0xFFFF indicates no specific minimum. Values not defined above are reserved for future use.

int max_interval
Advertising data show slave preferred connection max interval. The connection interval in the follow-
ing manner: connIntervalmax = Conn_Interval_Max * 1.25 ms Conn_Interval_Max range: 0x0006 to
0x0C80 Conn_Interval_Max shall be equal to or greater than the Conn_Interval_Min. Value of 0xFFFF
indicates no specific maximum. Values not defined above are reserved for future use.
int appearance
External appearance of device
uint16_t manufacturer_len
Manufacturer data length
uint8_t *p_manufacturer_data
Manufacturer data point
uint16_t service_data_len
Service data length
uint8_t *p_service_data
Service data point
uint16_t service_uuid_len
Service uuid length
uint8_t *p_service_uuid
Service uuid array point
uint8_t flag
Advertising flag of discovery mode, see BLE_ADV_DATA_FLAG detail
struct esp_ble_scan_params_t
Ble scan parameters.
Public Members
esp_ble_scan_type_t scan_type
Scan type
Owner address type
esp_ble_scan_filter_t scan_filter_policy
Scan filter policy
uint16_t scan_interval
Scan interval. This is defined as the time interval from when the Controller started its last LE scan until
it begins the subsequent LE scan. Range: 0x0004 to 0x4000 Default: 0x0010 (10 ms) Time = N * 0.625
msec Time Range: 2.5 msec to 10.24 seconds
uint16_t scan_window
Scan window. The duration of the LE scan. LE_Scan_Window shall be less than or equal to
LE_Scan_Interval Range: 0x0004 to 0x4000 Default: 0x0010 (10 ms) Time = N * 0.625 msec Time
Range: 2.5 msec to 10240 msec
esp_ble_scan_duplicate_t scan_duplicate
The Scan_Duplicates parameter controls whether the Link Layer should filter out duplicate advertising
reports (BLE_SCAN_DUPLICATE_ENABLE) to the Host, or if the Link Layer should generate ad-
vertising reports for each packet received
struct esp_gap_conn_params_t
connection parameters information

Public Members
uint16_t interval
connection interval
uint16_t latency
uint16_t timeout
Supervision timeout for the LE Link. Range: 0x000A to 0x0C80. Mandatory Range: 0x000A to 0x0C80
Time = N * 10 msec Time Range: 100 msec to 32 seconds
struct esp_ble_conn_update_params_t
Connection update parameters.
Public Members
esp_bd_addr_t bda
Bluetooth device address
uint16_t min_int
Min connection interval
uint16_t max_int
Max connection interval
uint16_t latency
uint16_t timeout
struct esp_ble_pkt_data_length_params_t
BLE pkt date length keys.
Public Members
uint16_t rx_len
pkt rx data length value
uint16_t tx_len
pkt tx data length value
struct esp_ble_penc_keys_t
BLE encryption keys.
Public Members
esp_bt_octet16_t ltk
The long term key
esp_bt_octet8_t rand
The random number
uint16_t ediv
The ediv value
uint8_t sec_level
The security level of the security link
uint8_t key_size
The key size(7~16) of the security link

struct esp_ble_pcsrk_keys_t
BLE CSRK keys.
Public Members
uint32_t counter
The counter
esp_bt_octet16_t csrk
The csrk key
uint8_t sec_level
The security level
struct esp_ble_pid_keys_t
BLE pid keys.
Public Members
esp_bt_octet16_t irk
The irk value
esp_ble_addr_type_t addr_type
The address type
esp_bd_addr_t static_addr
The static address
struct esp_ble_lenc_keys_t
BLE Encryption reproduction keys.
Public Members
esp_bt_octet16_t ltk
The long term key
uint16_t div
The div value
uint8_t key_size
The key size of the security link
uint8_t sec_level
struct esp_ble_lcsrk_keys
BLE SRK keys.
Public Members
uint32_t counter
The counter value
uint16_t div
The div value
uint8_t sec_level
esp_bt_octet16_t csrk
The csrk key value

struct esp_ble_sec_key_notif_t
Structure associated with ESP_KEY_NOTIF_EVT.
Public Members
peer address
uint32_t passkey
the numeric value for comparison. If just_works, do not show this number to UI
struct esp_ble_sec_req_t
Structure of the security request.
Public Members
peer address
struct esp_ble_bond_key_info_t
struct type of the bond key information value
Public Members
esp_ble_key_mask_t key_mask
the key mask to indicate witch key is present
esp_ble_penc_keys_t penc_key
received peer encryption key
esp_ble_pcsrk_keys_t pcsrk_key
received peer device SRK
esp_ble_pid_keys_t pid_key
peer device ID key
struct esp_ble_bond_dev_t
struct type of the bond device value
Public Members
peer address
esp_ble_bond_key_info_t bond_key
the bond key information
struct esp_ble_key_t
union type of the security key value
Public Members
peer address
esp_ble_key_type_t key_type
key type of the security link
esp_ble_key_value_t p_key_value
the pointer to the key value

struct esp_ble_local_id_keys_t
structure type of the ble local id keys value
Public Members
esp_bt_octet16_t ir
the 16 bits of the ir value
esp_bt_octet16_t irk
the 16 bits of the ir key value
esp_bt_octet16_t dhk
the 16 bits of the dh key value
struct esp_ble_auth_cmpl_t
Structure associated with ESP_AUTH_CMPL_EVT.
Public Members
BD address peer device.
bool key_present
Valid link key value in key element
esp_link_key key
Link key associated with peer device.
uint8_t key_type
The type of Link Key
bool success
TRUE of authentication succeeded, FALSE if failed.
uint8_t fail_reason
The HCI reason/error code for when success=FALSE
Peer device address type
esp_bt_dev_type_t dev_type
Device type
esp_ble_auth_req_t auth_mode
authentication mode
struct esp_ble_gap_ext_adv_params_t
ext adv parameters
Public Members
esp_ble_ext_adv_type_mask_t type
ext adv type
uint32_t interval_min
ext adv minimum interval
uint32_t interval_max
ext adv maximum interval
esp_ble_adv_channel_t channel_map
ext adv channel map

ext adv own addresss type
esp_ble_addr_type_t peer_addr_type
ext adv peer address type
esp_bd_addr_t peer_addr
ext adv peer address
esp_ble_adv_filter_t filter_policy
ext adv filter policy
int8_t tx_power
ext adv tx power
esp_ble_gap_pri_phy_t primary_phy
ext adv primary phy
uint8_t max_skip
ext adv maximum skip
esp_ble_gap_phy_t secondary_phy
ext adv secondary phy
uint8_t sid
ext adv sid
bool scan_req_notif
ext adv sacn request event notify
struct esp_ble_ext_scan_cfg_t
ext scan config
Public Members
esp_ble_scan_type_t scan_type
ext scan type
ext scan interval
ext scan window
struct esp_ble_ext_scan_params_t
ext scan parameters
Public Members
ext scan own addresss type
esp_ble_scan_filter_t filter_policy
ext scan filter policy
esp_ble_scan_duplicate_t scan_duplicate
ext scan duplicate scan
esp_ble_ext_scan_cfg_mask_t cfg_mask
ext scan config mask
esp_ble_ext_scan_cfg_t uncoded_cfg
ext scan uncoded config parameters
esp_ble_ext_scan_cfg_t coded_cfg
ext scan coded config parameters

struct esp_ble_gap_conn_params_t
create extend connection parameters
Public Members
init scan interval
init scan window
minimum interval
maximum interval
uint16_t latency
ext scan type
uint16_t supervision_timeout
connection supervision timeout
uint16_t min_ce_len
minimum ce length
uint16_t max_ce_len
maximum ce length
struct esp_ble_gap_ext_adv_t
extend adv enable parameters
Public Members
uint8_t instance
advertising handle
int duration
advertising duration
int max_events
maximum number of extended advertising events
struct esp_ble_gap_periodic_adv_params_t
periodic adv parameters
Public Members
periodic advertising minimum interval
periodic advertising maximum interval
uint8_t properties
periodic advertising properties
struct esp_ble_gap_periodic_adv_sync_params_t
periodic adv sync parameters

Public Members
esp_ble_gap_sync_t filter_policy
periodic advertising sync filter policy
uint8_t sid
esp_bd_addr_t addr
uint16_t skip
the maximum number of periodic advertising events that can be skipped
uint16_t sync_timeout
synchronization timeout
struct esp_ble_gap_ext_adv_reprot_t
extend adv report parameters
Public Members
esp_ble_gap_adv_type_t event_type
extend advertising type
uint8_t addr_type
extend advertising address type
esp_bd_addr_t addr
extend advertising address
esp_ble_gap_pri_phy_t primary_phy
extend advertising primary phy
esp_ble_gap_phy_t secondly_phy
extend advertising secondary phy
uint8_t sid
extend advertising sid
uint8_t tx_power
extend advertising tx power
int8_t rssi
extend advertising rssi
uint16_t per_adv_interval
uint8_t dir_addr_type
direct address type
esp_bd_addr_t dir_addr
direct address
esp_ble_gap_ext_adv_data_status_t data_status
data type
uint8_t adv_data_len
extend advertising data length
uint8_t adv_data[251]
extend advertising data

struct esp_ble_gap_periodic_adv_report_t
periodic adv report parameters
Public Members
periodic advertising train handle
uint8_t tx_power
periodic advertising tx power
int8_t rssi
periodic advertising rssi
esp_ble_gap_ext_adv_data_status_t data_status
periodic advertising data type
uint8_t data_length
periodic advertising data length
uint8_t data[251]
periodic advertising data
struct esp_ble_gap_periodic_adv_sync_estab_t
perodic adv sync establish parameters
Public Members
uint8_t status
periodic advertising sync status
periodic advertising train handle
uint8_t sid
esp_bd_addr_t adv_addr
esp_ble_gap_phy_t adv_phy
periodic advertising adv phy type
uint16_t period_adv_interval
uint8_t adv_clk_accuracy
periodic advertising clock accuracy
Macros
ESP_BLE_ADV_FLAG_LIMIT_DISC
BLE_ADV_DATA_FLAG data flag bit definition used for advertising data flag
ESP_BLE_ADV_FLAG_GEN_DISC
ESP_BLE_ADV_FLAG_BREDR_NOT_SPT
ESP_BLE_ADV_FLAG_DMT_CONTROLLER_SPT
ESP_BLE_ADV_FLAG_DMT_HOST_SPT
ESP_BLE_ADV_FLAG_NON_LIMIT_DISC

ESP_LE_KEY_NONE
ESP_LE_KEY_PENC
ESP_LE_KEY_PID
ESP_LE_KEY_PCSRK
ESP_LE_KEY_PLK
ESP_LE_KEY_LLK
ESP_LE_KEY_LENC
ESP_LE_KEY_LID
ESP_LE_KEY_LCSRK
ESP_LE_AUTH_NO_BOND
ESP_LE_AUTH_BOND
ESP_LE_AUTH_REQ_MITM
ESP_LE_AUTH_REQ_BOND_MITM
0101
ESP_LE_AUTH_REQ_SC_ONLY
ESP_LE_AUTH_REQ_SC_BOND
ESP_LE_AUTH_REQ_SC_MITM
ESP_LE_AUTH_REQ_SC_MITM_BOND
ESP_BLE_ONLY_ACCEPT_SPECIFIED_AUTH_DISABLE
ESP_BLE_ONLY_ACCEPT_SPECIFIED_AUTH_ENABLE
ESP_BLE_OOB_DISABLE
ESP_BLE_OOB_ENABLE
ESP_IO_CAP_OUT
ESP_IO_CAP_IO
ESP_IO_CAP_IN
ESP_IO_CAP_NONE
ESP_IO_CAP_KBDISP
ESP_BLE_APPEARANCE_UNKNOWN
ESP_BLE_APPEARANCE_GENERIC_PHONE
ESP_BLE_APPEARANCE_GENERIC_COMPUTER
ESP_BLE_APPEARANCE_GENERIC_WATCH
ESP_BLE_APPEARANCE_SPORTS_WATCH
ESP_BLE_APPEARANCE_GENERIC_CLOCK
ESP_BLE_APPEARANCE_GENERIC_DISPLAY
ESP_BLE_APPEARANCE_GENERIC_REMOTE
ESP_BLE_APPEARANCE_GENERIC_EYEGLASSES
ESP_BLE_APPEARANCE_GENERIC_TAG
ESP_BLE_APPEARANCE_GENERIC_KEYRING
ESP_BLE_APPEARANCE_GENERIC_MEDIA_PLAYER

ESP_BLE_APPEARANCE_GENERIC_BARCODE_SCANNER
ESP_BLE_APPEARANCE_GENERIC_THERMOMETER
ESP_BLE_APPEARANCE_THERMOMETER_EAR
ESP_BLE_APPEARANCE_GENERIC_HEART_RATE
ESP_BLE_APPEARANCE_HEART_RATE_BELT
ESP_BLE_APPEARANCE_GENERIC_BLOOD_PRESSURE
ESP_BLE_APPEARANCE_BLOOD_PRESSURE_ARM
ESP_BLE_APPEARANCE_BLOOD_PRESSURE_WRIST
ESP_BLE_APPEARANCE_GENERIC_HID
ESP_BLE_APPEARANCE_HID_KEYBOARD
ESP_BLE_APPEARANCE_HID_MOUSE
ESP_BLE_APPEARANCE_HID_JOYSTICK
ESP_BLE_APPEARANCE_HID_GAMEPAD
ESP_BLE_APPEARANCE_HID_DIGITIZER_TABLET
ESP_BLE_APPEARANCE_HID_CARD_READER
ESP_BLE_APPEARANCE_HID_DIGITAL_PEN
ESP_BLE_APPEARANCE_HID_BARCODE_SCANNER
ESP_BLE_APPEARANCE_GENERIC_GLUCOSE
ESP_BLE_APPEARANCE_GENERIC_WALKING
ESP_BLE_APPEARANCE_WALKING_IN_SHOE
ESP_BLE_APPEARANCE_WALKING_ON_SHOE
ESP_BLE_APPEARANCE_WALKING_ON_HIP
ESP_BLE_APPEARANCE_GENERIC_CYCLING
ESP_BLE_APPEARANCE_CYCLING_COMPUTER
ESP_BLE_APPEARANCE_CYCLING_SPEED
ESP_BLE_APPEARANCE_CYCLING_CADENCE
ESP_BLE_APPEARANCE_CYCLING_POWER
ESP_BLE_APPEARANCE_CYCLING_SPEED_CADENCE
ESP_BLE_APPEARANCE_GENERIC_PULSE_OXIMETER
ESP_BLE_APPEARANCE_PULSE_OXIMETER_FINGERTIP
ESP_BLE_APPEARANCE_PULSE_OXIMETER_WRIST
ESP_BLE_APPEARANCE_GENERIC_WEIGHT
ESP_BLE_APPEARANCE_GENERIC_PERSONAL_MOBILITY_DEVICE
ESP_BLE_APPEARANCE_POWERED_WHEELCHAIR
ESP_BLE_APPEARANCE_MOBILITY_SCOOTER
ESP_BLE_APPEARANCE_GENERIC_CONTINUOUS_GLUCOSE_MONITOR
ESP_BLE_APPEARANCE_GENERIC_INSULIN_PUMP
ESP_BLE_APPEARANCE_INSULIN_PUMP_DURABLE_PUMP
ESP_BLE_APPEARANCE_INSULIN_PUMP_PATCH_PUMP

ESP_BLE_APPEARANCE_INSULIN_PEN
ESP_BLE_APPEARANCE_GENERIC_MEDICATION_DELIVERY
ESP_BLE_APPEARANCE_GENERIC_OUTDOOR_SPORTS
ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION
ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_AND_NAV
ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_POD
ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_POD_AND_NAV
ESP_GAP_BLE_CHANNELS_LEN
ESP_GAP_BLE_ADD_WHITELIST_COMPLETE_EVT
This is the old name, just for backwards compatibility.
ESP_BLE_ADV_DATA_LEN_MAX
Advertising data maximum length.
ESP_BLE_SCAN_RSP_DATA_LEN_MAX
Scan response data maximum length.
BLE_BIT(n)
ESP_BLE_GAP_SET_EXT_ADV_PROP_NONCONN_NONSCANNABLE_UNDIRECTED
ESP_BLE_GAP_SET_EXT_ADV_PROP_CONNECTABLE
ESP_BLE_GAP_SET_EXT_ADV_PROP_SCANNABLE
ESP_BLE_GAP_SET_EXT_ADV_PROP_DIRECTED
ESP_BLE_GAP_SET_EXT_ADV_PROP_HD_DIRECTED
ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY
ESP_BLE_GAP_SET_EXT_ADV_PROP_ANON_ADV
ESP_BLE_GAP_SET_EXT_ADV_PROP_INCLUDE_TX_PWR
ESP_BLE_GAP_SET_EXT_ADV_PROP_MASK
ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_IND
ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_LD_DIR
ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_HD_DIR
ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_SCAN
ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_NONCONN
ESP_BLE_GAP_PHY_1M
ESP_BLE_GAP_PHY_2M
ESP_BLE_GAP_PHY_CODED
ESP_BLE_GAP_NO_PREFER_TRANSMIT_PHY
ESP_BLE_GAP_NO_PREFER_RECEIVE_PHY
ESP_BLE_GAP_PRI_PHY_1M
ESP_BLE_GAP_PRI_PHY_CODED
ESP_BLE_GAP_PHY_1M_PREF_MASK
ESP_BLE_GAP_PHY_2M_PREF_MASK
ESP_BLE_GAP_PHY_CODED_PREF_MASK
ESP_BLE_GAP_PHY_OPTIONS_NO_PREF

ESP_BLE_GAP_PHY_OPTIONS_PREF_S2_CODING
ESP_BLE_GAP_PHY_OPTIONS_PREF_S8_CODING
ESP_BLE_GAP_EXT_SCAN_CFG_UNCODE_MASK
ESP_BLE_GAP_EXT_SCAN_CFG_CODE_MASK
ESP_BLE_GAP_EXT_ADV_DATA_COMPLETE
ESP_BLE_GAP_EXT_ADV_DATA_INCOMPLETE
ESP_BLE_GAP_EXT_ADV_DATA_TRUNCATED
ESP_BLE_GAP_SYNC_POLICY_BY_ADV_INFO
ESP_BLE_GAP_SYNC_POLICY_BY_PERIODIC_LIST
ESP_BLE_ADV_REPORT_EXT_ADV_IND
ESP_BLE_ADV_REPORT_EXT_SCAN_IND
ESP_BLE_ADV_REPORT_EXT_DIRECT_ADV
ESP_BLE_ADV_REPORT_EXT_SCAN_RSP
ESP_BLE_LEGACY_ADV_TYPE_IND
ESP_BLE_LEGACY_ADV_TYPE_DIRECT_IND
ESP_BLE_LEGACY_ADV_TYPE_SCAN_IND
ESP_BLE_LEGACY_ADV_TYPE_NONCON_IND
ESP_BLE_LEGACY_ADV_TYPE_SCAN_RSP_TO_ADV_IND
ESP_BLE_LEGACY_ADV_TYPE_SCAN_RSP_TO_ADV_SCAN_IND
Type Definitions
typedef uint8_t esp_ble_key_type_t
typedef uint8_t esp_ble_auth_req_t
combination of the above bit pattern
typedef uint8_t esp_ble_io_cap_t
combination of the io capability
typedef uint8_t esp_gap_ble_channels[ESP_GAP_BLE_CHANNELS_LEN]
typedef uint8_t esp_duplicate_info_t[ESP_BD_ADDR_LEN]
typedef uint16_t esp_ble_ext_adv_type_mask_t
typedef uint8_t esp_ble_gap_phy_t
typedef uint8_t esp_ble_gap_all_phys_t
typedef uint8_t esp_ble_gap_pri_phy_t
typedef uint8_t esp_ble_gap_phy_mask_t
typedef uint16_t esp_ble_gap_prefer_phy_options_t
typedef uint8_t esp_ble_ext_scan_cfg_mask_t
typedef uint8_t esp_ble_gap_ext_adv_data_status_t
typedef uint8_t esp_ble_gap_sync_t
typedef uint8_t esp_ble_gap_adv_type_t
typedef void (*esp_gap_ble_cb_t)(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_param_t
*param)
GAP callback function type.

Parameters
• event: : Event type
• param: : Point to callback parameter, currently is union type
Enumerations
enum esp_gap_ble_cb_event_t
GAP BLE callback event type.
Values:
ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT = 0
When advertising data set complete, the event comes
ESP_GAP_BLE_SCAN_RSP_DATA_SET_COMPLETE_EVT
When scan response data set complete, the event comes
ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT
When scan parameters set complete, the event comes
ESP_GAP_BLE_SCAN_RESULT_EVT
When one scan result ready, the event comes each time
ESP_GAP_BLE_ADV_DATA_RAW_SET_COMPLETE_EVT
When raw advertising data set complete, the event comes
ESP_GAP_BLE_SCAN_RSP_DATA_RAW_SET_COMPLETE_EVT
When raw advertising data set complete, the event comes
ESP_GAP_BLE_ADV_START_COMPLETE_EVT
When start advertising complete, the event comes
ESP_GAP_BLE_SCAN_START_COMPLETE_EVT
When start scan complete, the event comes
ESP_GAP_BLE_AUTH_CMPL_EVT = 8
ESP_GAP_BLE_KEY_EVT
ESP_GAP_BLE_SEC_REQ_EVT
ESP_GAP_BLE_PASSKEY_NOTIF_EVT
ESP_GAP_BLE_PASSKEY_REQ_EVT
ESP_GAP_BLE_OOB_REQ_EVT
ESP_GAP_BLE_LOCAL_IR_EVT
ESP_GAP_BLE_LOCAL_ER_EVT
ESP_GAP_BLE_NC_REQ_EVT
ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT
When stop adv complete, the event comes
ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT
When stop scan complete, the event comes
ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT = 19
When set the static rand address complete, the event comes
ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT
When update connection parameters complete, the event comes
ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVT
When set pkt length complete, the event comes
ESP_GAP_BLE_SET_LOCAL_PRIVACY_COMPLETE_EVT
When Enable/disable privacy on the local device complete, the event comes

ESP_GAP_BLE_REMOVE_BOND_DEV_COMPLETE_EVT
When remove the bond device complete, the event comes
ESP_GAP_BLE_CLEAR_BOND_DEV_COMPLETE_EVT
When clear the bond device clear complete, the event comes
ESP_GAP_BLE_GET_BOND_DEV_COMPLETE_EVT
When get the bond device list complete, the event comes
ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT
When read the rssi complete, the event comes
ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT
When add or remove whitelist complete, the event comes
ESP_GAP_BLE_UPDATE_DUPLICATE_EXCEPTIONAL_LIST_COMPLETE_EVT
When update duplicate exceptional list complete, the event comes
ESP_GAP_BLE_SET_CHANNELS_EVT = 29
When setting BLE channels complete, the event comes
ESP_GAP_BLE_READ_PHY_COMPLETE_EVT
ESP_GAP_BLE_SET_PREFERED_DEFAULT_PHY_COMPLETE_EVT
ESP_GAP_BLE_SET_PREFERED_PHY_COMPLETE_EVT
ESP_GAP_BLE_EXT_ADV_SET_RAND_ADDR_COMPLETE_EVT
ESP_GAP_BLE_EXT_ADV_SET_PARAMS_COMPLETE_EVT
ESP_GAP_BLE_EXT_ADV_DATA_SET_COMPLETE_EVT
ESP_GAP_BLE_EXT_SCAN_RSP_DATA_SET_COMPLETE_EVT
ESP_GAP_BLE_EXT_ADV_START_COMPLETE_EVT
ESP_GAP_BLE_EXT_ADV_STOP_COMPLETE_EVT
ESP_GAP_BLE_EXT_ADV_SET_REMOVE_COMPLETE_EVT
ESP_GAP_BLE_EXT_ADV_SET_CLEAR_COMPLETE_EVT
ESP_GAP_BLE_PERIODIC_ADV_SET_PARAMS_COMPLETE_EVT
ESP_GAP_BLE_PERIODIC_ADV_DATA_SET_COMPLETE_EVT
ESP_GAP_BLE_PERIODIC_ADV_START_COMPLETE_EVT
ESP_GAP_BLE_PERIODIC_ADV_STOP_COMPLETE_EVT
ESP_GAP_BLE_PERIODIC_ADV_CREATE_SYNC_COMPLETE_EVT
ESP_GAP_BLE_PERIODIC_ADV_SYNC_CANCEL_COMPLETE_EVT
ESP_GAP_BLE_PERIODIC_ADV_SYNC_TERMINATE_COMPLETE_EVT
ESP_GAP_BLE_PERIODIC_ADV_ADD_DEV_COMPLETE_EVT
ESP_GAP_BLE_PERIODIC_ADV_REMOVE_DEV_COMPLETE_EVT
ESP_GAP_BLE_PERIODIC_ADV_CLEAR_DEV_COMPLETE_EVT
ESP_GAP_BLE_SET_EXT_SCAN_PARAMS_COMPLETE_EVT
ESP_GAP_BLE_EXT_SCAN_START_COMPLETE_EVT
ESP_GAP_BLE_EXT_SCAN_STOP_COMPLETE_EVT
ESP_GAP_BLE_PREFER_EXT_CONN_PARAMS_SET_COMPLETE_EVT
ESP_GAP_BLE_PHY_UPDATE_COMPLETE_EVT
ESP_GAP_BLE_EXT_ADV_REPORT_EVT

ESP_GAP_BLE_SCAN_TIMEOUT_EVT
ESP_GAP_BLE_ADV_TERMINATED_EVT
ESP_GAP_BLE_SCAN_REQ_RECEIVED_EVT
ESP_GAP_BLE_CHANNEL_SELETE_ALGORITHM_EVT
ESP_GAP_BLE_PERIODIC_ADV_REPORT_EVT
ESP_GAP_BLE_PERIODIC_ADV_SYNC_LOST_EVT
ESP_GAP_BLE_PERIODIC_ADV_SYNC_ESTAB_EVT
ESP_GAP_BLE_EVT_MAX
enum esp_ble_adv_data_type
The type of advertising data(not adv_type)
Values:
ESP_BLE_AD_TYPE_FLAG = 0x01
ESP_BLE_AD_TYPE_16SRV_PART = 0x02
ESP_BLE_AD_TYPE_16SRV_CMPL = 0x03
ESP_BLE_AD_TYPE_NAME_SHORT = 0x08
ESP_BLE_AD_TYPE_NAME_CMPL = 0x09
ESP_BLE_AD_TYPE_TX_PWR = 0x0A
ESP_BLE_AD_TYPE_DEV_CLASS = 0x0D
ESP_BLE_AD_TYPE_SM_TK = 0x10
ESP_BLE_AD_TYPE_SM_OOB_FLAG = 0x11
ESP_BLE_AD_TYPE_INT_RANGE = 0x12
ESP_BLE_AD_TYPE_SOL_SRV_UUID = 0x14
ESP_BLE_AD_TYPE_128SOL_SRV_UUID = 0x15
ESP_BLE_AD_TYPE_SERVICE_DATA = 0x16
ESP_BLE_AD_TYPE_PUBLIC_TARGET = 0x17
ESP_BLE_AD_TYPE_RANDOM_TARGET = 0x18
ESP_BLE_AD_TYPE_APPEARANCE = 0x19
ESP_BLE_AD_TYPE_ADV_INT = 0x1A
ESP_BLE_AD_TYPE_LE_DEV_ADDR = 0x1b
ESP_BLE_AD_TYPE_LE_ROLE = 0x1c
ESP_BLE_AD_TYPE_SPAIR_C256 = 0x1d
ESP_BLE_AD_TYPE_SPAIR_R256 = 0x1e
ESP_BLE_AD_TYPE_32SOL_SRV_UUID = 0x1f
ESP_BLE_AD_TYPE_32SERVICE_DATA = 0x20
ESP_BLE_AD_TYPE_128SERVICE_DATA = 0x21
ESP_BLE_AD_TYPE_LE_SECURE_CONFIRM = 0x22

ESP_BLE_AD_TYPE_LE_SECURE_RANDOM = 0x23
ESP_BLE_AD_TYPE_URI = 0x24
ESP_BLE_AD_TYPE_INDOOR_POSITION = 0x25
ESP_BLE_AD_TYPE_TRANS_DISC_DATA = 0x26
ESP_BLE_AD_TYPE_LE_SUPPORT_FEATURE = 0x27
ESP_BLE_AD_TYPE_CHAN_MAP_UPDATE = 0x28
ESP_BLE_AD_MANUFACTURER_SPECIFIC_TYPE = 0xFF
enum esp_ble_adv_type_t
Advertising mode.
Values:
ADV_TYPE_IND = 0x00
ADV_TYPE_DIRECT_IND_HIGH = 0x01
ADV_TYPE_SCAN_IND = 0x02
ADV_TYPE_NONCONN_IND = 0x03
ADV_TYPE_DIRECT_IND_LOW = 0x04
enum esp_ble_adv_channel_t
Advertising channel mask.
Values:
ADV_CHNL_37 = 0x01
ADV_CHNL_38 = 0x02
ADV_CHNL_39 = 0x04
ADV_CHNL_ALL = 0x07
enum esp_ble_adv_filter_t
Values:
ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY = 0x00
Allow both scan and connection requests from anyone.
ADV_FILTER_ALLOW_SCAN_WLST_CON_ANY
Allow both scan req from White List devices only and connection req from anyone.
ADV_FILTER_ALLOW_SCAN_ANY_CON_WLST
Allow both scan req from anyone and connection req from White List devices only.
ADV_FILTER_ALLOW_SCAN_WLST_CON_WLST
Allow scan and connection requests from White List devices only.
enum esp_ble_sec_act_t
Values:
ESP_BLE_SEC_ENCRYPT = 1
ESP_BLE_SEC_ENCRYPT_NO_MITM
ESP_BLE_SEC_ENCRYPT_MITM
enum esp_ble_sm_param_t
Values:
ESP_BLE_SM_PASSKEY = 0
ESP_BLE_SM_AUTHEN_REQ_MODE
ESP_BLE_SM_IOCAP_MODE

ESP_BLE_SM_SET_INIT_KEY
ESP_BLE_SM_SET_RSP_KEY
ESP_BLE_SM_MAX_KEY_SIZE
ESP_BLE_SM_MIN_KEY_SIZE
ESP_BLE_SM_SET_STATIC_PASSKEY
ESP_BLE_SM_CLEAR_STATIC_PASSKEY
ESP_BLE_SM_ONLY_ACCEPT_SPECIFIED_SEC_AUTH
ESP_BLE_SM_OOB_SUPPORT
ESP_BLE_APP_ENC_KEY_SIZE
ESP_BLE_SM_MAX_PARAM
enum esp_ble_scan_type_t
Ble scan type.
Values:
BLE_SCAN_TYPE_PASSIVE = 0x0
Passive scan
BLE_SCAN_TYPE_ACTIVE = 0x1
Active scan
enum esp_ble_scan_filter_t
Ble scan filter type.
Values:
BLE_SCAN_FILTER_ALLOW_ALL = 0x0
Accept all :
1. advertisement packets except directed advertising packets not addressed to this device (default).
BLE_SCAN_FILTER_ALLOW_ONLY_WLST = 0x1
Accept only :
1. advertisement packets from devices where the advertiser s address is in the White list.
2. Directed advertising packets which are not addressed for this device shall be ignored.
BLE_SCAN_FILTER_ALLOW_UND_RPA_DIR = 0x2
Accept all :
1. undirected advertisement packets, and
2. directed advertising packets where the initiator address is a resolvable private address, and
3. directed advertising packets addressed to this device.
BLE_SCAN_FILTER_ALLOW_WLIST_RPA_DIR = 0x3
Accept all :
1. advertisement packets from devices where the advertiser s address is in the White list, and
2. directed advertising packets where the initiator address is a resolvable private address, and
3. directed advertising packets addressed to this device.
enum esp_ble_scan_duplicate_t
Ble scan duplicate type.
Values:
BLE_SCAN_DUPLICATE_DISABLE = 0x0
the Link Layer should generate advertising reports to the host for each packet received
BLE_SCAN_DUPLICATE_ENABLE = 0x1
the Link Layer should filter out duplicate advertising reports to the Host

BLE_SCAN_DUPLICATE_MAX = 0x2
0x02 0xFF, Reserved for future use
enum esp_gap_search_evt_t
Sub Event of ESP_GAP_BLE_SCAN_RESULT_EVT.
Values:
ESP_GAP_SEARCH_INQ_RES_EVT = 0
Inquiry result for a peer device.
ESP_GAP_SEARCH_INQ_CMPL_EVT = 1
Inquiry complete.
ESP_GAP_SEARCH_DISC_RES_EVT = 2
Discovery result for a peer device.
ESP_GAP_SEARCH_DISC_BLE_RES_EVT = 3
Discovery result for BLE GATT based service on a peer device.
ESP_GAP_SEARCH_DISC_CMPL_EVT = 4
Discovery complete.
ESP_GAP_SEARCH_DI_DISC_CMPL_EVT = 5
Discovery complete.
ESP_GAP_SEARCH_SEARCH_CANCEL_CMPL_EVT = 6
Search cancelled
ESP_GAP_SEARCH_INQ_DISCARD_NUM_EVT = 7
The number of pkt discarded by flow control
enum esp_ble_evt_type_t
Ble scan result event type, to indicate the result is scan response or advertising data or other.
Values:
ESP_BLE_EVT_CONN_ADV = 0x00
Connectable undirected advertising (ADV_IND)
ESP_BLE_EVT_CONN_DIR_ADV = 0x01
Connectable directed advertising (ADV_DIRECT_IND)
ESP_BLE_EVT_DISC_ADV = 0x02
Scannable undirected advertising (ADV_SCAN_IND)
ESP_BLE_EVT_NON_CONN_ADV = 0x03
Non connectable undirected advertising (ADV_NONCONN_IND)
ESP_BLE_EVT_SCAN_RSP = 0x04
Scan Response (SCAN_RSP)
enum esp_ble_wl_opration_t
Values:
ESP_BLE_WHITELIST_REMOVE = 0X00
remove mac from whitelist
ESP_BLE_WHITELIST_ADD = 0X01
add address to whitelist
enum esp_bt_duplicate_exceptional_subcode_type_t
Values:
ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_ADD = 0
Add device info into duplicate scan exceptional list
ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_REMOVE
Remove device info from duplicate scan exceptional list

ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_CLEAN
Clean duplicate scan exceptional list
enum esp_ble_duplicate_exceptional_info_type_t
Values:
ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_ADV_ADDR = 0
BLE advertising address , device info will be added into ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_ADDR_LIST
ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_LINK_ID
BLE mesh link ID, it is for BLE mesh, device info will be added into
ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_LINK_ID_LIST
ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_BEACON_TYPE
BLE mesh beacon AD type, the format is | Len | 0x2B | Beacon Type | Beacon Data |
ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_PROV_SRV_ADV
BLE mesh provisioning service uuid, the format is | 0x02 | 0x01 | flags | 0x03 | 0x03 | 0x1827 | . |`
ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_PROXY_SRV_ADV
BLE mesh adv with proxy service uuid, the format is | 0x02 | 0x01 | flags | 0x03 | 0x03 | 0x1828 | . |`
enum esp_duplicate_scan_exceptional_list_type_t
Values:
ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_ADDR_LIST = BLE_BIT(0)
duplicate scan exceptional addr list
ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_LINK_ID_LIST = BLE_BIT(1)
duplicate scan exceptional mesh link ID list
ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_BEACON_TYPE_LIST = BLE_BIT(2)
duplicate scan exceptional mesh beacon type list
ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_PROV_SRV_ADV_LIST = BLE_BIT(3)
duplicate scan exceptional mesh adv with provisioning service uuid
ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_PROXY_SRV_ADV_LIST = BLE_BIT(4)
duplicate scan exceptional mesh adv with provisioning service uuid
ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_ALL_LIST = 0xFFFF
duplicate scan exceptional all list
GATT DEFINES
API Reference
Header File
• components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h
Unions
union esp_gatt_rsp_t
#include <esp_gatt_defs.h> GATT remote read request response type.

Public Members
esp_gatt_value_t attr_value
Gatt attribute structure
uint16_t handle
Gatt attribute handle
Structures
struct esp_gatt_id_t
Gatt id, include uuid and instance id.
Public Members
esp_bt_uuid_t uuid
UUID
uint8_t inst_id
Instance id
struct esp_gatt_srvc_id_t
Gatt service id, include id (uuid and instance id) and primary flag.
Public Members
esp_gatt_id_t id
Gatt id, include uuid and instance
bool is_primary
This service is primary or not
struct esp_attr_desc_t
Attribute description (used to create database)
Public Members
uint16_t uuid_length
UUID length
uint8_t *uuid_p
UUID value
uint16_t perm
Attribute permission
uint16_t max_length
Maximum length of the element
uint16_t length
Current length of the element
uint8_t *value
Element value array
struct esp_attr_control_t
attribute auto response flag

Public Members
uint8_t auto_rsp
if auto_rsp set to ESP_GATT_RSP_BY_APP, means the response of Write/Read operation will by
replied by application. if auto_rsp set to ESP_GATT_AUTO_RSP, means the response of Write/Read
operation will be replied by GATT stack automatically.
struct esp_gatts_attr_db_t
attribute type added to the gatt server database
Public Members
esp_attr_control_t attr_control
The attribute control type
esp_attr_desc_t att_desc
The attribute type
struct esp_attr_value_t
set the attribute value type
Public Members
uint16_t attr_max_len
attribute max value length
uint16_t attr_len
attribute current value length
uint8_t *attr_value
the pointer to attribute value
struct esp_gatts_incl_svc_desc_t
Gatt include service entry element.
Public Members
uint16_t start_hdl
Gatt start handle value of included service
uint16_t end_hdl
Gatt end handle value of included service
uint16_t uuid
Gatt attribute value UUID of included service
struct esp_gatts_incl128_svc_desc_t
Gatt include 128 bit service entry element.
Public Members
uint16_t start_hdl
Gatt start handle value of included 128 bit service
uint16_t end_hdl
Gatt end handle value of included 128 bit service
struct esp_gatt_value_t
Gatt attribute value.

Public Members
uint8_t value[ESP_GATT_MAX_ATTR_LEN]
Gatt attribute value
uint16_t handle
Gatt attribute handle
uint16_t offset
Gatt attribute value offset
uint16_t len
Gatt attribute value length
uint8_t auth_req
Gatt authentication request
struct esp_gatt_conn_params_t
Connection parameters information.
Public Members
uint16_t interval
connection interval
uint16_t latency
uint16_t timeout
struct esp_gattc_multi_t
read multiple attribute
Public Members
uint8_t num_attr
The number of the attribute
uint16_t handles[ESP_GATT_MAX_READ_MULTI_HANDLES]
The handles list
struct esp_gattc_db_elem_t
data base attribute element
Public Members
esp_gatt_db_attr_type_t type
The attribute type
uint16_t attribute_handle
The attribute handle, it s valid for all of the type
uint16_t start_handle
The service start handle, it s valid only when the type = ESP_GATT_DB_PRIMARY_SERVICE or
ESP_GATT_DB_SECONDARY_SERVICE
uint16_t end_handle
The service end handle, it s valid only when the type = ESP_GATT_DB_PRIMARY_SERVICE or

esp_gatt_char_prop_t properties
The characteristic properties, it s valid only when the type = ESP_GATT_DB_CHARACTERISTIC
esp_bt_uuid_t uuid
The attribute uuid, it s valid for all of the type
struct esp_gattc_service_elem_t
service element
Public Members
bool is_primary
The service flag, true if the service is primary service, else is secondary service
The start handle of the service
uint16_t end_handle
The end handle of the service
esp_bt_uuid_t uuid
The uuid of the service
struct esp_gattc_char_elem_t
characteristic element
Public Members
uint16_t char_handle
The characteristic handle
esp_gatt_char_prop_t properties
The characteristic properties
esp_bt_uuid_t uuid
The characteristic uuid
struct esp_gattc_descr_elem_t
descriptor element
Public Members
uint16_t handle
The characteristic descriptor handle
esp_bt_uuid_t uuid
The characteristic descriptor uuid
struct esp_gattc_incl_svc_elem_t
include service element
Public Members
uint16_t handle
The include service current attribute handle
uint16_t incl_srvc_s_handle
The start handle of the service which has been included
uint16_t incl_srvc_e_handle
The end handle of the service which has been included

esp_bt_uuid_t uuid
The include service uuid
Macros
ESP_GATT_UUID_IMMEDIATE_ALERT_SVC
All ESP_GATT_UUID_xxx is attribute types
ESP_GATT_UUID_LINK_LOSS_SVC
ESP_GATT_UUID_TX_POWER_SVC
ESP_GATT_UUID_CURRENT_TIME_SVC
ESP_GATT_UUID_REF_TIME_UPDATE_SVC
ESP_GATT_UUID_NEXT_DST_CHANGE_SVC
ESP_GATT_UUID_GLUCOSE_SVC
ESP_GATT_UUID_HEALTH_THERMOM_SVC
ESP_GATT_UUID_DEVICE_INFO_SVC
ESP_GATT_UUID_HEART_RATE_SVC
ESP_GATT_UUID_PHONE_ALERT_STATUS_SVC
ESP_GATT_UUID_BATTERY_SERVICE_SVC
ESP_GATT_UUID_BLOOD_PRESSURE_SVC
ESP_GATT_UUID_ALERT_NTF_SVC
ESP_GATT_UUID_HID_SVC
ESP_GATT_UUID_SCAN_PARAMETERS_SVC
ESP_GATT_UUID_RUNNING_SPEED_CADENCE_SVC
ESP_GATT_UUID_Automation_IO_SVC
ESP_GATT_UUID_CYCLING_SPEED_CADENCE_SVC
ESP_GATT_UUID_CYCLING_POWER_SVC
ESP_GATT_UUID_LOCATION_AND_NAVIGATION_SVC
ESP_GATT_UUID_ENVIRONMENTAL_SENSING_SVC
ESP_GATT_UUID_BODY_COMPOSITION
ESP_GATT_UUID_USER_DATA_SVC
ESP_GATT_UUID_WEIGHT_SCALE_SVC
ESP_GATT_UUID_BOND_MANAGEMENT_SVC
ESP_GATT_UUID_CONT_GLUCOSE_MONITOR_SVC
ESP_GATT_UUID_PRI_SERVICE
ESP_GATT_UUID_SEC_SERVICE
ESP_GATT_UUID_INCLUDE_SERVICE
ESP_GATT_UUID_CHAR_DECLARE
ESP_GATT_UUID_CHAR_EXT_PROP
ESP_GATT_UUID_CHAR_DESCRIPTION
ESP_GATT_UUID_CHAR_CLIENT_CONFIG
ESP_GATT_UUID_CHAR_SRVR_CONFIG

ESP_GATT_UUID_CHAR_PRESENT_FORMAT
ESP_GATT_UUID_CHAR_AGG_FORMAT
ESP_GATT_UUID_CHAR_VALID_RANGE
ESP_GATT_UUID_EXT_RPT_REF_DESCR
ESP_GATT_UUID_RPT_REF_DESCR
ESP_GATT_UUID_NUM_DIGITALS_DESCR
ESP_GATT_UUID_VALUE_TRIGGER_DESCR
ESP_GATT_UUID_ENV_SENSING_CONFIG_DESCR
ESP_GATT_UUID_ENV_SENSING_MEASUREMENT_DESCR
ESP_GATT_UUID_ENV_SENSING_TRIGGER_DESCR
ESP_GATT_UUID_TIME_TRIGGER_DESCR
ESP_GATT_UUID_GAP_DEVICE_NAME
ESP_GATT_UUID_GAP_ICON
ESP_GATT_UUID_GAP_PREF_CONN_PARAM
ESP_GATT_UUID_GAP_CENTRAL_ADDR_RESOL
ESP_GATT_UUID_GATT_SRV_CHGD
ESP_GATT_UUID_ALERT_LEVEL
ESP_GATT_UUID_TX_POWER_LEVEL
ESP_GATT_UUID_CURRENT_TIME
ESP_GATT_UUID_LOCAL_TIME_INFO
ESP_GATT_UUID_REF_TIME_INFO
ESP_GATT_UUID_NW_STATUS
ESP_GATT_UUID_NW_TRIGGER
ESP_GATT_UUID_ALERT_STATUS
ESP_GATT_UUID_RINGER_CP
ESP_GATT_UUID_RINGER_SETTING
ESP_GATT_UUID_GM_MEASUREMENT
ESP_GATT_UUID_GM_CONTEXT
ESP_GATT_UUID_GM_CONTROL_POINT
ESP_GATT_UUID_GM_FEATURE
ESP_GATT_UUID_SYSTEM_ID
ESP_GATT_UUID_MODEL_NUMBER_STR
ESP_GATT_UUID_SERIAL_NUMBER_STR
ESP_GATT_UUID_FW_VERSION_STR
ESP_GATT_UUID_HW_VERSION_STR
ESP_GATT_UUID_SW_VERSION_STR
ESP_GATT_UUID_MANU_NAME
ESP_GATT_UUID_IEEE_DATA
ESP_GATT_UUID_PNP_ID

ESP_GATT_UUID_HID_INFORMATION
ESP_GATT_UUID_HID_REPORT_MAP
ESP_GATT_UUID_HID_CONTROL_POINT
ESP_GATT_UUID_HID_REPORT
ESP_GATT_UUID_HID_PROTO_MODE
ESP_GATT_UUID_HID_BT_KB_INPUT
ESP_GATT_UUID_HID_BT_KB_OUTPUT
ESP_GATT_UUID_HID_BT_MOUSE_INPUT
ESP_GATT_HEART_RATE_MEAS
Heart Rate Measurement.
ESP_GATT_BODY_SENSOR_LOCATION
Body Sensor Location.
ESP_GATT_HEART_RATE_CNTL_POINT
Heart Rate Control Point.
ESP_GATT_UUID_BATTERY_LEVEL
ESP_GATT_UUID_SC_CONTROL_POINT
ESP_GATT_UUID_SENSOR_LOCATION
ESP_GATT_UUID_RSC_MEASUREMENT
ESP_GATT_UUID_RSC_FEATURE
ESP_GATT_UUID_CSC_MEASUREMENT
ESP_GATT_UUID_CSC_FEATURE
ESP_GATT_UUID_SCAN_INT_WINDOW
ESP_GATT_UUID_SCAN_REFRESH
ESP_GATT_ILLEGAL_UUID
GATT INVALID UUID.
ESP_GATT_ILLEGAL_HANDLE
GATT INVALID HANDLE.
ESP_GATT_ATTR_HANDLE_MAX
GATT attribute max handle.
ESP_GATT_MAX_READ_MULTI_HANDLES
ESP_GATT_PERM_READ
Attribute permissions.
ESP_GATT_PERM_READ_ENCRYPTED
ESP_GATT_PERM_READ_ENC_MITM
ESP_GATT_PERM_WRITE
ESP_GATT_PERM_WRITE_ENCRYPTED
ESP_GATT_PERM_WRITE_ENC_MITM
ESP_GATT_PERM_WRITE_SIGNED
ESP_GATT_PERM_WRITE_SIGNED_MITM
ESP_GATT_PERM_READ_AUTHORIZATION
ESP_GATT_PERM_WRITE_AUTHORIZATION

ESP_GATT_CHAR_PROP_BIT_BROADCAST
ESP_GATT_CHAR_PROP_BIT_READ
ESP_GATT_CHAR_PROP_BIT_WRITE_NR
ESP_GATT_CHAR_PROP_BIT_WRITE
ESP_GATT_CHAR_PROP_BIT_NOTIFY
ESP_GATT_CHAR_PROP_BIT_INDICATE
ESP_GATT_CHAR_PROP_BIT_AUTH
ESP_GATT_CHAR_PROP_BIT_EXT_PROP
ESP_GATT_MAX_ATTR_LEN
GATT maximum attribute length.
ESP_GATT_RSP_BY_APP
ESP_GATT_AUTO_RSP
ESP_GATT_IF_NONE
If callback report gattc_if/gatts_if as this macro, means this event is not correspond to any app
Type Definitions
typedef uint16_t esp_gatt_perm_t
typedef uint8_t esp_gatt_char_prop_t
typedef uint8_t esp_gatt_if_t
Gatt interface type, different application on GATT client use different gatt_if
Enumerations
enum esp_gatt_prep_write_type
Attribute write data type from the client.
Values:
ESP_GATT_PREP_WRITE_CANCEL = 0x00
Prepare write cancel
ESP_GATT_PREP_WRITE_EXEC = 0x01
Prepare write execute
enum esp_gatt_status_t
GATT success code and error codes.
Values:
ESP_GATT_OK = 0x0
ESP_GATT_INVALID_HANDLE = 0x01
ESP_GATT_READ_NOT_PERMIT = 0x02
ESP_GATT_WRITE_NOT_PERMIT = 0x03
ESP_GATT_INVALID_PDU = 0x04
ESP_GATT_INSUF_AUTHENTICATION = 0x05
ESP_GATT_REQ_NOT_SUPPORTED = 0x06
ESP_GATT_INVALID_OFFSET = 0x07
ESP_GATT_INSUF_AUTHORIZATION = 0x08
ESP_GATT_PREPARE_Q_FULL = 0x09
ESP_GATT_NOT_FOUND = 0x0a

ESP_GATT_NOT_LONG = 0x0b
ESP_GATT_INSUF_KEY_SIZE = 0x0c
ESP_GATT_INVALID_ATTR_LEN = 0x0d
ESP_GATT_ERR_UNLIKELY = 0x0e
ESP_GATT_INSUF_ENCRYPTION = 0x0f
ESP_GATT_UNSUPPORT_GRP_TYPE = 0x10
ESP_GATT_INSUF_RESOURCE = 0x11
ESP_GATT_NO_RESOURCES = 0x80
ESP_GATT_INTERNAL_ERROR = 0x81
ESP_GATT_WRONG_STATE = 0x82
ESP_GATT_DB_FULL = 0x83
ESP_GATT_BUSY = 0x84
ESP_GATT_ERROR = 0x85
ESP_GATT_CMD_STARTED = 0x86
ESP_GATT_ILLEGAL_PARAMETER = 0x87
ESP_GATT_PENDING = 0x88
ESP_GATT_AUTH_FAIL = 0x89
ESP_GATT_MORE = 0x8a
ESP_GATT_INVALID_CFG = 0x8b
ESP_GATT_SERVICE_STARTED = 0x8c
ESP_GATT_ENCRYPED_MITM = ESP_GATT_OK
ESP_GATT_ENCRYPED_NO_MITM = 0x8d
ESP_GATT_NOT_ENCRYPTED = 0x8e
ESP_GATT_CONGESTED = 0x8f
ESP_GATT_DUP_REG = 0x90
ESP_GATT_ALREADY_OPEN = 0x91
ESP_GATT_CANCEL = 0x92
ESP_GATT_STACK_RSP = 0xe0
ESP_GATT_APP_RSP = 0xe1
ESP_GATT_UNKNOWN_ERROR = 0xef
ESP_GATT_CCC_CFG_ERR = 0xfd
ESP_GATT_PRC_IN_PROGRESS = 0xfe
ESP_GATT_OUT_OF_RANGE = 0xff
enum esp_gatt_conn_reason_t
Gatt Connection reason enum.
Values:
ESP_GATT_CONN_UNKNOWN = 0
Gatt connection unknown
ESP_GATT_CONN_L2C_FAILURE = 1
General L2cap failure

ESP_GATT_CONN_TIMEOUT = 0x08
Connection timeout
ESP_GATT_CONN_TERMINATE_PEER_USER = 0x13
Connection terminate by peer user
ESP_GATT_CONN_TERMINATE_LOCAL_HOST = 0x16
Connection terminated by local host
ESP_GATT_CONN_FAIL_ESTABLISH = 0x3e
Connection fail to establish
ESP_GATT_CONN_LMP_TIMEOUT = 0x22
Connection fail for LMP response tout
ESP_GATT_CONN_CONN_CANCEL = 0x0100
L2CAP connection cancelled
ESP_GATT_CONN_NONE = 0x0101
No connection to cancel
enum esp_gatt_auth_req_t
Gatt authentication request type.
Values:
ESP_GATT_AUTH_REQ_NONE = 0
ESP_GATT_AUTH_REQ_NO_MITM = 1
ESP_GATT_AUTH_REQ_MITM = 2
ESP_GATT_AUTH_REQ_SIGNED_NO_MITM = 3
ESP_GATT_AUTH_REQ_SIGNED_MITM = 4
enum esp_service_source_t
Values:
ESP_GATT_SERVICE_FROM_REMOTE_DEVICE = 0
ESP_GATT_SERVICE_FROM_NVS_FLASH = 1
ESP_GATT_SERVICE_FROM_UNKNOWN = 2
enum esp_gatt_write_type_t
Gatt write type.
Values:
ESP_GATT_WRITE_TYPE_NO_RSP = 1
Gatt write attribute need no response
ESP_GATT_WRITE_TYPE_RSP
Gatt write attribute need remote response
enum esp_gatt_db_attr_type_t
the type of attribute element
Values:
ESP_GATT_DB_PRIMARY_SERVICE
Gattc primary service attribute type in the cache
Gattc secondary service attribute type in the cache
ESP_GATT_DB_CHARACTERISTIC
Gattc characteristic attribute type in the cache
ESP_GATT_DB_DESCRIPTOR
Gattc characteristic descriptor attribute type in the cache

ESP_GATT_DB_INCLUDED_SERVICE
Gattc include service attribute type in the cache
ESP_GATT_DB_ALL
Gattc all the attribute (primary service & secondary service & include service & char & descriptor) type
in the cache
GATT SERVER API
• This is a GATT sever demo and its tutorial. This demo creates a GATT service with an attribute table, which
releases the user from adding attributes one by one. This is the recommended method of adding attributes.
– bluetooth/bluedroid/ble/gatt_server_service_table
– GATT Server Service Table Example Walkthrough
• This is a GATT server demo and its tutorial. This demo creates a GATT service by adding attributes one by
one as defined by Bluedroid. The recommended method of adding attributes is presented in example above.
– bluetooth/bluedroid/ble/gatt_server
– GATT Server Example Walkthrough
• This is a BLE SPP-Like demo. This demo, which acts as a GATT server, can receive data from UART and
then send the data to the peer device automatically.
– bluetooth/bluedroid/ble/ble_spp_server
API Reference
Header File
• components/bt/host/bluedroid/api/include/api/esp_gatts_api.h
Functions
esp_err_t esp_ble_gatts_register_callback(esp_gatts_cb_t callback)
This function is called to register application callbacks with BTA GATTS module.
Return
• other : failed
esp_err_t esp_ble_gatts_app_register(uint16_t app_id)
This function is called to register application identifier.
Return
• other : failed
esp_err_t esp_ble_gatts_app_unregister(esp_gatt_if_t gatts_if)
unregister with GATT Server.
Return
• other : failed
Parameters
• [in] gatts_if: GATT server access interface
esp_err_t esp_ble_gatts_create_service(esp_gatt_if_t gatts_if, esp_gatt_srvc_id_t *service_id,
uint16_t num_handle)
Create a service. When service creation is done, a callback event ESP_GATTS_CREATE_EVT is called to

report status and service ID to the profile. The service ID obtained in the callback function needs to be used
when adding included service and characteristics/descriptors into the service.
Return
• other : failed
Parameters
• [in] service_id: service ID.
• [in] num_handle: number of handle requested for this service.
esp_err_t esp_ble_gatts_create_attr_tab(const esp_gatts_attr_db_t *gatts_attr_db,
esp_gatt_if_t gatts_if, uint8_t max_nb_attr, uint8_t
srvc_inst_id)
Create a service attribute tab.
Return
• other : failed
Parameters
• [in] gatts_attr_db: the pointer to the service attr tab
• [in] max_nb_attr: the number of attribute to be added to the service database.
• [in] srvc_inst_id: the instance id of the service
esp_err_t esp_ble_gatts_add_included_service(uint16_t service_handle, uint16_t in-
cluded_service_handle)
This function is called to add an included service. This function have to be called between
esp_ble_gatts_create_service and esp_ble_gatts_add_char . After included service is included, a callback
event ESP_GATTS_ADD_INCL_SRVC_EVT is reported the included service ID.
Return
• other : failed
Parameters
• [in] service_handle: service handle to which this included service is to be added.
• [in] included_service_handle: the service ID to be included.
esp_err_t esp_ble_gatts_add_char(uint16_t service_handle, esp_bt_uuid_t *char_uuid,
esp_gatt_perm_t perm, esp_gatt_char_prop_t property,
esp_attr_value_t *char_val, esp_attr_control_t *control)
This function is called to add a characteristic into a service.
Return
• other : failed
Parameters
• [in] service_handle: service handle to which this included service is to be added.
• [in] char_uuid: : Characteristic UUID.
• [in] perm: : Characteristic value declaration attribute permission.
• [in] property: : Characteristic Properties
• [in] char_val: : Characteristic value
• [in] control: : attribute response control byte
esp_err_t esp_ble_gatts_add_char_descr(uint16_t service_handle, esp_bt_uuid_t *descr_uuid,
esp_gatt_perm_t perm, esp_attr_value_t
*char_descr_val, esp_attr_control_t *control)
This function is called to add characteristic descriptor. When it s done, a callback event
ESP_GATTS_ADD_DESCR_EVT is called to report the status and an ID number for this descriptor.
Return
• other : failed

Parameters
• [in] service_handle: service handle to which this characteristic descriptor is to be added.
• [in] perm: descriptor access permission.
• [in] descr_uuid: descriptor UUID.
• [in] char_descr_val: : Characteristic descriptor value
• [in] control: : attribute response control byte
esp_err_t esp_ble_gatts_delete_service(uint16_t service_handle)
This function is called to delete a service. When this is done, a callback event ESP_GATTS_DELETE_EVT
is report with the status.
Return
• other : failed
Parameters
• [in] service_handle: service_handle to be deleted.
esp_err_t esp_ble_gatts_start_service(uint16_t service_handle)
This function is called to start a service.
Return
• other : failed
Parameters
• [in] service_handle: the service handle to be started.
esp_err_t esp_ble_gatts_stop_service(uint16_t service_handle)
This function is called to stop a service.
Return
• other : failed
Parameters
• [in] service_handle: - service to be topped.
esp_err_t esp_ble_gatts_send_indicate(esp_gatt_if_t gatts_if, uint16_t conn_id, uint16_t
attr_handle, uint16_t value_len, uint8_t *value, bool
need_confirm)
Send indicate or notify to GATT client. Set param need_confirm as false will send notification, otherwise
indication.
Return
• other : failed
Parameters
• [in] conn_id: - connection id to indicate.
• [in] attr_handle: - attribute handle to indicate.
• [in] value_len: - indicate value length.
• [in] value: value to indicate.
• [in] need_confirm: - Whether a confirmation is required. false sends a GATT notification,
true sends a GATT indication.
esp_err_t esp_ble_gatts_send_response(esp_gatt_if_t gatts_if, uint16_t conn_id, uint32_t
trans_id, esp_gatt_status_t status, esp_gatt_rsp_t *rsp)
This function is called to send a response to a request.
Return
• other : failed
Parameters
• [in] conn_id: - connection identifier.

• [in] trans_id: - transfer id

• [in] status: - response status
• [in] rsp: - response data.
esp_err_t esp_ble_gatts_set_attr_value(uint16_t attr_handle, uint16_t length, const uint8_t
*value)
This function is called to set the attribute value by the application.
Return
• other : failed
Parameters
• [in] attr_handle: the attribute handle which to be set
• [in] length: the value length
• [in] value: the pointer to the attribute value
esp_gatt_status_t esp_ble_gatts_get_attr_value(uint16_t attr_handle, uint16_t *length, const
uint8_t **value)
Retrieve attribute value.
Return
• ESP_GATT_OK : success
• other : failed
Parameters
• [in] attr_handle: Attribute handle.
• [out] length: pointer to the attribute value length
• [out] value: Pointer to attribute value payload, the value cannot be modified by user
esp_err_t esp_ble_gatts_open(esp_gatt_if_t gatts_if, esp_bd_addr_t remote_bda, bool is_direct)
Open a direct open connection or add a background auto connection.
Return
• other : failed
Parameters
• [in] remote_bda: remote device bluetooth device address.
• [in] is_direct: direct connection or background auto connection
esp_err_t esp_ble_gatts_close(esp_gatt_if_t gatts_if, uint16_t conn_id)
Close a connection a remote device.
Return
• other : failed
Parameters
• [in] conn_id: connection ID to be closed.
esp_err_t esp_ble_gatts_send_service_change_indication(esp_gatt_if_t gatts_if,
esp_bd_addr_t remote_bda)
Send service change indication.
Return
• other : failed
Parameters
• [in] remote_bda: remote device bluetooth device address. If remote_bda is NULL then it
will send service change indication to all the connected devices and if not then to a specific device
Unions

union esp_ble_gatts_cb_param_t
#include <esp_gatts_api.h> Gatt server callback parameters union.
Public Members
struct esp_ble_gatts_cb_param_t::gatts_reg_evt_param reg

Gatt server callback param of ESP_GATTS_REG_EVT
struct esp_ble_gatts_cb_param_t::gatts_read_evt_param read
Gatt server callback param of ESP_GATTS_READ_EVT
struct esp_ble_gatts_cb_param_t::gatts_write_evt_param write
Gatt server callback param of ESP_GATTS_WRITE_EVT
struct esp_ble_gatts_cb_param_t::gatts_exec_write_evt_param exec_write
Gatt server callback param of ESP_GATTS_EXEC_WRITE_EVT
struct esp_ble_gatts_cb_param_t::gatts_mtu_evt_param mtu
Gatt server callback param of ESP_GATTS_MTU_EVT
struct esp_ble_gatts_cb_param_t::gatts_conf_evt_param conf
Gatt server callback param of ESP_GATTS_CONF_EVT (confirm)
struct esp_ble_gatts_cb_param_t::gatts_create_evt_param create
Gatt server callback param of ESP_GATTS_CREATE_EVT
struct esp_ble_gatts_cb_param_t::gatts_add_incl_srvc_evt_param add_incl_srvc
Gatt server callback param of ESP_GATTS_ADD_INCL_SRVC_EVT
struct esp_ble_gatts_cb_param_t::gatts_add_char_evt_param add_char
Gatt server callback param of ESP_GATTS_ADD_CHAR_EVT
struct esp_ble_gatts_cb_param_t::gatts_add_char_descr_evt_param add_char_descr
Gatt server callback param of ESP_GATTS_ADD_CHAR_DESCR_EVT
struct esp_ble_gatts_cb_param_t::gatts_delete_evt_param del
Gatt server callback param of ESP_GATTS_DELETE_EVT
struct esp_ble_gatts_cb_param_t::gatts_start_evt_param start
Gatt server callback param of ESP_GATTS_START_EVT
struct esp_ble_gatts_cb_param_t::gatts_stop_evt_param stop
Gatt server callback param of ESP_GATTS_STOP_EVT
struct esp_ble_gatts_cb_param_t::gatts_connect_evt_param connect
Gatt server callback param of ESP_GATTS_CONNECT_EVT
struct esp_ble_gatts_cb_param_t::gatts_disconnect_evt_param disconnect
Gatt server callback param of ESP_GATTS_DISCONNECT_EVT
struct esp_ble_gatts_cb_param_t::gatts_open_evt_param open
Gatt server callback param of ESP_GATTS_OPEN_EVT
struct esp_ble_gatts_cb_param_t::gatts_cancel_open_evt_param cancel_open
Gatt server callback param of ESP_GATTS_CANCEL_OPEN_EVT
struct esp_ble_gatts_cb_param_t::gatts_close_evt_param close
Gatt server callback param of ESP_GATTS_CLOSE_EVT
struct esp_ble_gatts_cb_param_t::gatts_congest_evt_param congest
Gatt server callback param of ESP_GATTS_CONGEST_EVT
struct esp_ble_gatts_cb_param_t::gatts_rsp_evt_param rsp
Gatt server callback param of ESP_GATTS_RESPONSE_EVT
struct esp_ble_gatts_cb_param_t::gatts_add_attr_tab_evt_param add_attr_tab
Gatt server callback param of ESP_GATTS_CREAT_ATTR_TAB_EVT

struct esp_ble_gatts_cb_param_t::gatts_set_attr_val_evt_param set_attr_val

Gatt server callback param of ESP_GATTS_SET_ATTR_VAL_EVT
struct esp_ble_gatts_cb_param_t::gatts_send_service_change_evt_param service_change
Gatt server callback param of ESP_GATTS_SEND_SERVICE_CHANGE_EVT
struct gatts_add_attr_tab_evt_param
#include <esp_gatts_api.h> ESP_GATTS_CREAT_ATTR_TAB_EVT.
Public Members
esp_gatt_status_t status
Operation status
esp_bt_uuid_t svc_uuid
Service uuid type
uint8_t svc_inst_id
Service id
uint16_t num_handle
The number of the attribute handle to be added to the gatts database
uint16_t *handles
The number to the handles
struct gatts_add_char_descr_evt_param
#include <esp_gatts_api.h> ESP_GATTS_ADD_CHAR_DESCR_EVT.
Public Members
Operation status
uint16_t attr_handle
Descriptor attribute handle
uint16_t service_handle
Service attribute handle
esp_bt_uuid_t descr_uuid
Characteristic descriptor uuid
struct gatts_add_char_evt_param
#include <esp_gatts_api.h> ESP_GATTS_ADD_CHAR_EVT.
Public Members
Operation status
Characteristic attribute handle
esp_bt_uuid_t char_uuid
Characteristic uuid
struct gatts_add_incl_srvc_evt_param
#include <esp_gatts_api.h> ESP_GATTS_ADD_INCL_SRVC_EVT.

Public Members
Operation status
Included service attribute handle
struct gatts_cancel_open_evt_param
#include <esp_gatts_api.h> ESP_GATTS_CANCEL_OPEN_EVT.
Public Members
Operation status
struct gatts_close_evt_param
#include <esp_gatts_api.h> ESP_GATTS_CLOSE_EVT.
Public Members
Operation status
uint16_t conn_id
Connection id
struct gatts_conf_evt_param
#include <esp_gatts_api.h> ESP_GATTS_CONF_EVT.
Public Members
Operation status
uint16_t conn_id
Connection id
uint16_t handle
attribute handle
uint16_t len
The indication or notification value length, len is valid when send notification or indication failed
uint8_t *value
The indication or notification value , value is valid when send notification or indication failed
struct gatts_congest_evt_param
#include <esp_gatts_api.h> ESP_GATTS_LISTEN_EVT.
ESP_GATTS_CONGEST_EVT
Public Members
uint16_t conn_id
Connection id

bool congested
Congested or not
struct gatts_connect_evt_param
#include <esp_gatts_api.h> ESP_GATTS_CONNECT_EVT.
Public Members
uint16_t conn_id
Connection id
uint8_t link_role
Link role : master role = 0 ; slave role = 1
esp_bd_addr_t remote_bda
Remote bluetooth device address
esp_gatt_conn_params_t conn_params
current Connection parameters
struct gatts_create_evt_param
#include <esp_gatts_api.h> ESP_GATTS_UNREG_EVT.
ESP_GATTS_CREATE_EVT
Public Members
Operation status
esp_gatt_srvc_id_t service_id
Service id, include service uuid and other information
struct gatts_delete_evt_param
#include <esp_gatts_api.h> ESP_GATTS_DELETE_EVT.
Public Members
Operation status
struct gatts_disconnect_evt_param
#include <esp_gatts_api.h> ESP_GATTS_DISCONNECT_EVT.
Public Members
uint16_t conn_id
Connection id
esp_gatt_conn_reason_t reason
Indicate the reason of disconnection

struct gatts_exec_write_evt_param
#include <esp_gatts_api.h> ESP_GATTS_EXEC_WRITE_EVT.
Public Members
uint16_t conn_id
Connection id
uint32_t trans_id
Transfer id
esp_bd_addr_t bda
The bluetooth device address which been written
uint8_t exec_write_flag
Execute write flag
struct gatts_mtu_evt_param
#include <esp_gatts_api.h> ESP_GATTS_MTU_EVT.
Public Members
uint16_t conn_id
Connection id
uint16_t mtu
MTU size
struct gatts_open_evt_param
#include <esp_gatts_api.h> ESP_GATTS_OPEN_EVT.
Public Members
Operation status
struct gatts_read_evt_param
#include <esp_gatts_api.h> ESP_GATTS_READ_EVT.
Public Members
uint16_t conn_id
Connection id
uint32_t trans_id
Transfer id
esp_bd_addr_t bda
The bluetooth device address which been read
uint16_t handle
The attribute handle
uint16_t offset
Offset of the value, if the value is too long
bool is_long
The value is too long or not
bool need_rsp
The read operation need to do response

struct gatts_reg_evt_param
#include <esp_gatts_api.h> ESP_GATTS_REG_EVT.
Public Members
Operation status
uint16_t app_id
Application id which input in register API
struct gatts_rsp_evt_param
#include <esp_gatts_api.h> ESP_GATTS_RESPONSE_EVT.
Public Members
Operation status
uint16_t handle
Attribute handle which send response
struct gatts_send_service_change_evt_param
#include <esp_gatts_api.h> ESP_GATTS_SEND_SERVICE_CHANGE_EVT.
Public Members
Operation status
struct gatts_set_attr_val_evt_param
#include <esp_gatts_api.h> ESP_GATTS_SET_ATTR_VAL_EVT.
Public Members
uint16_t srvc_handle
The service handle
Operation status
struct gatts_start_evt_param
#include <esp_gatts_api.h> ESP_GATTS_START_EVT.
Public Members
Operation status
struct gatts_stop_evt_param
#include <esp_gatts_api.h> ESP_GATTS_STOP_EVT.

Public Members
Operation status
struct gatts_write_evt_param
#include <esp_gatts_api.h> ESP_GATTS_WRITE_EVT.
Public Members
uint16_t conn_id
Connection id
uint32_t trans_id
Transfer id
esp_bd_addr_t bda
The bluetooth device address which been written
uint16_t handle
uint16_t offset
Offset of the value, if the value is too long
bool need_rsp
The write operation need to do response
bool is_prep
This write operation is prepare write
uint16_t len
The write attribute value length
uint8_t *value
The write attribute value
Macros
ESP_GATT_PREP_WRITE_CANCEL
Prepare write flag to indicate cancel prepare write
ESP_GATT_PREP_WRITE_EXEC
Prepare write flag to indicate execute prepare write
Type Definitions
typedef void (*esp_gatts_cb_t)(esp_gatts_cb_event_t event, esp_gatt_if_t gatts_if,
esp_ble_gatts_cb_param_t *param)
GATT Server callback function type.
Parameters
• gatts_if: : GATT server access interface, normally different gatts_if correspond to different
profile
Enumerations

enum esp_gatts_cb_event_t
GATT Server callback function events.
Values:
ESP_GATTS_REG_EVT = 0
When register application id, the event comes
ESP_GATTS_READ_EVT = 1
When gatt client request read operation, the event comes
ESP_GATTS_WRITE_EVT = 2
When gatt client request write operation, the event comes
ESP_GATTS_EXEC_WRITE_EVT = 3
When gatt client request execute write, the event comes
ESP_GATTS_MTU_EVT = 4
When set mtu complete, the event comes
ESP_GATTS_CONF_EVT = 5
When receive confirm, the event comes
ESP_GATTS_UNREG_EVT = 6
When unregister application id, the event comes
ESP_GATTS_CREATE_EVT = 7
When create service complete, the event comes
ESP_GATTS_ADD_INCL_SRVC_EVT = 8
When add included service complete, the event comes
ESP_GATTS_ADD_CHAR_EVT = 9
When add characteristic complete, the event comes
ESP_GATTS_ADD_CHAR_DESCR_EVT = 10
When add descriptor complete, the event comes
ESP_GATTS_DELETE_EVT = 11
When delete service complete, the event comes
ESP_GATTS_START_EVT = 12
When start service complete, the event comes
ESP_GATTS_STOP_EVT = 13
When stop service complete, the event comes
ESP_GATTS_CONNECT_EVT = 14
When gatt client connect, the event comes
ESP_GATTS_DISCONNECT_EVT = 15
When gatt client disconnect, the event comes
ESP_GATTS_OPEN_EVT = 16
When connect to peer, the event comes
ESP_GATTS_CANCEL_OPEN_EVT = 17
When disconnect from peer, the event comes
ESP_GATTS_CLOSE_EVT = 18
When gatt server close, the event comes
ESP_GATTS_LISTEN_EVT = 19
When gatt listen to be connected the event comes
ESP_GATTS_CONGEST_EVT = 20
When congest happen, the event comes
ESP_GATTS_RESPONSE_EVT = 21
When gatt send response complete, the event comes

ESP_GATTS_CREAT_ATTR_TAB_EVT = 22
When gatt create table complete, the event comes
ESP_GATTS_SET_ATTR_VAL_EVT = 23
When gatt set attr value complete, the event comes
ESP_GATTS_SEND_SERVICE_CHANGE_EVT = 24
When gatt send service change indication complete, the event comes
GATT CLIENT API
• This is a GATT client demo and its tutorial. This demo can scan for devices, connect to the GATT server and
discover its services.
– bluetooth/bluedroid/ble/gatt_client
– GATT Client Example Walkthrough
• This is a multiple connection demo and its tutorial. This demo can connect to multiple GATT server devices
and discover their services.
– bluetooth/bluedroid/ble/gattc_multi_connect
– GATT Client Multi-connection Example Walkthrough
• This is a BLE SPP-Like demo. This demo, which acts as a GATT client, can receive data from UART and
then send the data to the peer device automatically.
– bluetooth/bluedroid/ble/ble_spp_client
API Reference
Header File
• components/bt/host/bluedroid/api/include/api/esp_gattc_api.h
Functions
esp_err_t esp_ble_gattc_register_callback(esp_gattc_cb_t callback)
This function is called to register application callbacks with GATTC module.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] callback: : pointer to the application callback function.
esp_err_t esp_ble_gattc_app_register(uint16_t app_id)
This function is called to register application callbacks with GATTC module.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] app_id: : Application Identify (UUID), for different application
esp_err_t esp_ble_gattc_app_unregister(esp_gatt_if_t gattc_if)
This function is called to unregister an application from GATTC module.
Return
• ESP_OK: success
• other: failed

Parameters
• [in] gattc_if: Gatt client access interface.
esp_err_t esp_ble_gattc_open(esp_gatt_if_t gattc_if, esp_bd_addr_t remote_bda,
esp_ble_addr_type_t remote_addr_type, bool is_direct)
Open a direct connection or add a background auto connection.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] remote_bda: remote device bluetooth device address.
• [in] remote_addr_type: remote device bluetooth device the address type.
• [in] is_direct: direct connection or background auto connection(by now, background auto
connection is not supported).
esp_err_t esp_ble_gattc_aux_open(esp_gatt_if_t gattc_if, esp_bd_addr_t remote_bda,
esp_ble_addr_type_t remote_addr_type, bool is_direct)
esp_err_t esp_ble_gattc_close(esp_gatt_if_t gattc_if, uint16_t conn_id)
Close the virtual connection to the GATT server. gattc may have multiple virtual GATT server connections
when multiple app_id registered, this API only close one virtual GATT server connection. if there exist other
virtual GATT server connections, it does not disconnect the physical connection. if you want to disconnect the
physical connection directly, you can use esp_ble_gap_disconnect(esp_bd_addr_t remote_device).
Return
• ESP_OK: success
• other: failed
Parameters
• [in] conn_id: connection ID to be closed.
esp_err_t esp_ble_gattc_send_mtu_req(esp_gatt_if_t gattc_if, uint16_t conn_id)
Configure the MTU size in the GATT channel. This can be done only once per connection. Before using, use
esp_ble_gatt_set_local_mtu() to configure the local MTU size.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] conn_id: connection ID.
esp_err_t esp_ble_gattc_search_service(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_bt_uuid_t
*filter_uuid)
This function is called to get service from local cache. This function report service search result by a callback
event, and followed by a service search complete event.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] conn_id: connection ID.
• [in] filter_uuid: a UUID of the service application is interested in. If Null, discover for all
services.
esp_gatt_status_t esp_ble_gattc_get_service(esp_gatt_if_t gattc_if, uint16_t conn_id,
esp_bt_uuid_t *svc_uuid, esp_gattc_service_elem_t
*result, uint16_t *count, uint16_t offset)
Find all the service with the given service uuid in the gattc cache, if the svc_uuid is NULL, find all the service.
Note: It just get service from local cache, won t get from remote devices. If want to get it from remote device,
need to used the esp_ble_gattc_cache_refresh, then call esp_ble_gattc_get_service again.

Return
• ESP_OK: success
• other: failed
Parameters
• [in] conn_id: connection ID which identify the server.
• [in] svc_uuid: the pointer to the service uuid.
• [out] result: The pointer to the service which has been found in the gattc cache.
• [inout] count: input the number of service want to find, it will output the number of service
has been found in the gattc cache with the given service uuid.
• [in] offset: Offset of the service position to get.
esp_gatt_status_t esp_ble_gattc_get_all_char(esp_gatt_if_t gattc_if, uint16_t conn_id,
uint16_t start_handle, uint16_t end_handle,
esp_gattc_char_elem_t *result, uint16_t *count,
uint16_t offset)
Find all the characteristic with the given service in the gattc cache Note: It just get characteristic from local
cache, won t get from remote devices.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] start_handle: the attribute start handle.
• [in] end_handle: the attribute end handle
• [out] result: The pointer to the characteristic in the service.
• [inout] count: input the number of characteristic want to find, it will output the number of
characteristic has been found in the gattc cache with the given service.
• [in] offset: Offset of the characteristic position to get.
esp_gatt_status_t esp_ble_gattc_get_all_descr(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t
char_handle, esp_gattc_descr_elem_t *result,
uint16_t *count, uint16_t offset)
Find all the descriptor with the given characteristic in the gattc cache Note: It just get descriptor from local
Return
• ESP_OK: success
• other: failed
Parameters
• [in] char_handle: the given characteristic handle
• [out] result: The pointer to the descriptor in the characteristic.
• [inout] count: input the number of descriptor want to find, it will output the number of
descriptor has been found in the gattc cache with the given characteristic.
• [in] offset: Offset of the descriptor position to get.
esp_gatt_status_t esp_ble_gattc_get_char_by_uuid(esp_gatt_if_t gattc_if, uint16_t conn_id,
uint16_t start_handle, uint16_t
end_handle, esp_bt_uuid_t char_uuid,
esp_gattc_char_elem_t *result, uint16_t
*count)
Find the characteristic with the given characteristic uuid in the gattc cache Note: It just get characteristic from
local cache, won t get from remote devices.
Return
• ESP_OK: success
• other: failed
Parameters


• [in] start_handle: the attribute start handle
• [in] char_uuid: the characteristic uuid
• [out] result: The pointer to the characteristic in the service.
• [inout] count: input the number of characteristic want to find, it will output the number of
characteristic has been found in the gattc cache with the given service.
esp_gatt_status_t esp_ble_gattc_get_descr_by_uuid(esp_gatt_if_t gattc_if, uint16_t
conn_id, uint16_t start_handle,
uint16_t end_handle, esp_bt_uuid_t
char_uuid, esp_bt_uuid_t descr_uuid,
esp_gattc_descr_elem_t *result, uint16_t
*count)
Find the descriptor with the given characteristic uuid in the gattc cache Note: It just get descriptor from local
Return
• ESP_OK: success
• other: failed
Parameters
• [in] char_uuid: the characteristic uuid.
• [in] descr_uuid: the descriptor uuid.
• [out] result: The pointer to the descriptor in the given characteristic.
esp_gatt_status_t esp_ble_gattc_get_descr_by_char_handle(esp_gatt_if_t gattc_if, uint16_t
conn_id, uint16_t char_handle,
esp_bt_uuid_t descr_uuid,
esp_gattc_descr_elem_t *result,
uint16_t *count)
Find the descriptor with the given characteristic handle in the gattc cache Note: It just get descriptor from local
Return
• ESP_OK: success
• other: failed
Parameters
• [in] char_handle: the characteristic handle.
• [in] descr_uuid: the descriptor uuid.
• [out] result: The pointer to the descriptor in the given characteristic.
esp_gatt_status_t esp_ble_gattc_get_include_service(esp_gatt_if_t gattc_if, uint16_t conn_id,
uint16_t start_handle, uint16_t
end_handle, esp_bt_uuid_t *incl_uuid,
esp_gattc_incl_svc_elem_t *result,
uint16_t *count)
Find the include service with the given service handle in the gattc cache Note: It just get include service from
local cache, won t get from remote devices.
Return
• ESP_OK: success

• other: failed
Parameters
• [in] incl_uuid: the include service uuid
• [out] result: The pointer to the include service in the given service.
• [inout] count: input the number of include service want to find, it will output the number of
include service has been found in the gattc cache with the given service.
esp_gatt_status_t esp_ble_gattc_get_attr_count(esp_gatt_if_t gattc_if, uint16_t conn_id,
esp_gatt_db_attr_type_t type, uint16_t
start_handle, uint16_t end_handle, uint16_t
char_handle, uint16_t *count)
Find the attribute count with the given service or characteristic in the gattc cache.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] type: the attribute type.
• [in] start_handle: the attribute start handle, if the type is ESP_GATT_DB_DESCRIPTOR,
this parameter should be ignore
• [in] end_handle: the attribute end handle, if the type is ESP_GATT_DB_DESCRIPTOR,
this parameter should be ignore
• [in] char_handle: the characteristic handle, this parameter valid when the type is
ESP_GATT_DB_DESCRIPTOR. If the type isn t ESP_GATT_DB_DESCRIPTOR, this param-
eter should be ignore.
• [out] count: output the number of attribute has been found in the gattc cache with the given
attribute type.
esp_gatt_status_t esp_ble_gattc_get_db(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t
start_handle, uint16_t end_handle, esp_gattc_db_elem_t
*db, uint16_t *count)
This function is called to get the GATT database. Note: It just get attribute data base from local cache, won
t get from remote devices.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] db: output parameter which will contain the GATT database copy. Caller is responsible for
freeing it.
• [in] count: number of elements in database.
esp_err_t esp_ble_gattc_read_char(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t handle,
esp_gatt_auth_req_t auth_req)
This function is called to read a service s characteristics of the given characteristic handle.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] conn_id: : connection ID.

• [in] handle: : characteritic handle to read.

• [in] auth_req: : authenticate request type
esp_err_t esp_ble_gattc_read_by_type(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t
start_handle, uint16_t end_handle, esp_bt_uuid_t *uuid,
This function is called to read a service s characteristics of the given characteristic UUID.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] start_handle: : the attribute start handle.
• [in] end_handle: : the attribute end handle
• [in] uuid: : The UUID of attribute which will be read.
esp_err_t esp_ble_gattc_read_multiple(esp_gatt_if_t gattc_if, uint16_t conn_id,
esp_gattc_multi_t *read_multi, esp_gatt_auth_req_t
auth_req)
This function is called to read multiple characteristic or characteristic descriptors.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] read_multi: : pointer to the read multiple parameter.
esp_err_t esp_ble_gattc_read_char_descr(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t han-
dle, esp_gatt_auth_req_t auth_req)
This function is called to read a characteristics descriptor.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] handle: : descriptor handle to read.
esp_err_t esp_ble_gattc_write_char(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t handle,
uint16_t value_len, uint8_t *value, esp_gatt_write_type_t
write_type, esp_gatt_auth_req_t auth_req)
This function is called to write characteristic value.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] handle: : characteristic handle to write.
• [in] value_len: length of the value to be written.
• [in] value: : the value to be written.
• [in] write_type: : the type of attribute write operation.
• [in] auth_req: : authentication request.

esp_err_t esp_ble_gattc_write_char_descr(esp_gatt_if_t gattc_if, uint16_t conn_id,

uint16_t handle, uint16_t value_len, uint8_t
*value, esp_gatt_write_type_t write_type,
This function is called to write characteristic descriptor value.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] conn_id: : connection ID
• [in] handle: : descriptor hadle to write.
• [in] write_type: : the type of attribute write operation.
esp_err_t esp_ble_gattc_prepare_write(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t han-
dle, uint16_t offset, uint16_t value_len, uint8_t *value,
This function is called to prepare write a characteristic value.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] handle: : characteristic handle to prepare write.
• [in] offset: : offset of the write value.
esp_err_t esp_ble_gattc_prepare_write_char_descr(esp_gatt_if_t gattc_if, uint16_t conn_id,
uint16_t handle, uint16_t offset,
uint16_t value_len, uint8_t *value,
This function is called to prepare write a characteristic descriptor value.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] handle: : characteristic descriptor handle to prepare write.
• [in] offset: : offset of the write value.
esp_err_t esp_ble_gattc_execute_write(esp_gatt_if_t gattc_if, uint16_t conn_id, bool is_execute)
This function is called to execute write a prepare write sequence.
Return
• ESP_OK: success
• other: failed
Parameters

• [in] is_execute: : execute or cancel.

esp_err_t esp_ble_gattc_register_for_notify(esp_gatt_if_t gattc_if, esp_bd_addr_t
server_bda, uint16_t handle)
This function is called to register for notification of a service.
Return
• ESP_OK: registration succeeds
• other: failed
Parameters
• [in] server_bda: : target GATT server.
• [in] handle: : GATT characteristic handle.
esp_err_t esp_ble_gattc_unregister_for_notify(esp_gatt_if_t gattc_if, esp_bd_addr_t
server_bda, uint16_t handle)
This function is called to de-register for notification of a service.
Return
• ESP_OK: unregister succeeds
• other: failed
Parameters
• [in] server_bda: : target GATT server.
• [in] handle: : GATT characteristic handle.
esp_err_t esp_ble_gattc_cache_refresh(esp_bd_addr_t remote_bda)
Refresh the server cache store in the gattc stack of the remote device. If the device is connected, this API will
restart the discovery of service information of the remote device.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] remote_bda: remote device BD address.
esp_err_t esp_ble_gattc_cache_assoc(esp_gatt_if_t gattc_if, esp_bd_addr_t src_addr,
esp_bd_addr_t assoc_addr, bool is_assoc)
Add or delete the associated address with the source address. Note: The role of this API is mainly when the
client side has stored a server-side database, when it needs to connect another device, but the device s attribute
database is the same as the server database stored on the client-side, calling this API can use the database that
the device has stored used as the peer server database to reduce the attribute database search and discovery
process and speed up the connection time. The associated address mains that device want to used the database
has stored in the local cache. The source address mains that device want to share the database to the associated
address device.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] src_addr: the source address which provide the attribute table.
• [in] assoc_addr: the associated device address which went to share the attribute table with
the source address.
• [in] is_assoc: true add the associated device address, false remove the associated device
address.
esp_err_t esp_ble_gattc_cache_get_addr_list(esp_gatt_if_t gattc_if)
Get the address list which has store the attribute table in the gattc cache. There will callback
ESP_GATTC_GET_ADDR_LIST_EVT event when get address list complete.
Return
• ESP_OK: success
• other: failed

Parameters
esp_err_t esp_ble_gattc_cache_clean(esp_bd_addr_t remote_bda)
Clean the service cache of this device in the gattc stack,.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] remote_bda: remote device BD address.
Unions
union esp_ble_gattc_cb_param_t
#include <esp_gattc_api.h> Gatt client callback parameters union.
Public Members
struct esp_ble_gattc_cb_param_t::gattc_reg_evt_param reg

Gatt client callback param of ESP_GATTC_REG_EVT
struct esp_ble_gattc_cb_param_t::gattc_open_evt_param open
Gatt client callback param of ESP_GATTC_OPEN_EVT
struct esp_ble_gattc_cb_param_t::gattc_close_evt_param close
Gatt client callback param of ESP_GATTC_CLOSE_EVT
struct esp_ble_gattc_cb_param_t::gattc_cfg_mtu_evt_param cfg_mtu
Gatt client callback param of ESP_GATTC_CFG_MTU_EVT
struct esp_ble_gattc_cb_param_t::gattc_search_cmpl_evt_param search_cmpl
Gatt client callback param of ESP_GATTC_SEARCH_CMPL_EVT
struct esp_ble_gattc_cb_param_t::gattc_search_res_evt_param search_res
Gatt client callback param of ESP_GATTC_SEARCH_RES_EVT
struct esp_ble_gattc_cb_param_t::gattc_read_char_evt_param read
Gatt client callback param of ESP_GATTC_READ_CHAR_EVT
struct esp_ble_gattc_cb_param_t::gattc_write_evt_param write
Gatt client callback param of ESP_GATTC_WRITE_DESCR_EVT
struct esp_ble_gattc_cb_param_t::gattc_exec_cmpl_evt_param exec_cmpl
Gatt client callback param of ESP_GATTC_EXEC_EVT
struct esp_ble_gattc_cb_param_t::gattc_notify_evt_param notify
Gatt client callback param of ESP_GATTC_NOTIFY_EVT
struct esp_ble_gattc_cb_param_t::gattc_srvc_chg_evt_param srvc_chg
Gatt client callback param of ESP_GATTC_SRVC_CHG_EVT
struct esp_ble_gattc_cb_param_t::gattc_congest_evt_param congest
Gatt client callback param of ESP_GATTC_CONGEST_EVT
struct esp_ble_gattc_cb_param_t::gattc_reg_for_notify_evt_param reg_for_notify
Gatt client callback param of ESP_GATTC_REG_FOR_NOTIFY_EVT
struct esp_ble_gattc_cb_param_t::gattc_unreg_for_notify_evt_param unreg_for_notify
Gatt client callback param of ESP_GATTC_UNREG_FOR_NOTIFY_EVT
struct esp_ble_gattc_cb_param_t::gattc_connect_evt_param connect
Gatt client callback param of ESP_GATTC_CONNECT_EVT
struct esp_ble_gattc_cb_param_t::gattc_disconnect_evt_param disconnect
Gatt client callback param of ESP_GATTC_DISCONNECT_EVT

struct esp_ble_gattc_cb_param_t::gattc_set_assoc_addr_cmp_evt_param set_assoc_cmp

Gatt client callback param of ESP_GATTC_SET_ASSOC_EVT
struct esp_ble_gattc_cb_param_t::gattc_get_addr_list_evt_param get_addr_list
Gatt client callback param of ESP_GATTC_GET_ADDR_LIST_EVT
struct esp_ble_gattc_cb_param_t::gattc_queue_full_evt_param queue_full
Gatt client callback param of ESP_GATTC_QUEUE_FULL_EVT
struct esp_ble_gattc_cb_param_t::gattc_dis_srvc_cmpl_evt_param dis_srvc_cmpl
Gatt client callback param of ESP_GATTC_DIS_SRVC_CMPL_EVT
struct gattc_cfg_mtu_evt_param
#include <esp_gattc_api.h> ESP_GATTC_CFG_MTU_EVT.
Public Members
Operation status
uint16_t conn_id
Connection id
uint16_t mtu
MTU size
struct gattc_close_evt_param
#include <esp_gattc_api.h> ESP_GATTC_CLOSE_EVT.
Public Members
Operation status
uint16_t conn_id
Connection id
The reason of gatt connection close
struct gattc_congest_evt_param
#include <esp_gattc_api.h> ESP_GATTC_CONGEST_EVT.
Public Members
uint16_t conn_id
Connection id
bool congested
Congested or not
struct gattc_connect_evt_param
#include <esp_gattc_api.h> ESP_GATTC_CONNECT_EVT.

Public Members
uint16_t conn_id
Connection id
uint8_t link_role
Link role : master role = 0 ; slave role = 1
esp_gatt_conn_params_t conn_params
current connection parameters
struct gattc_dis_srvc_cmpl_evt_param
#include <esp_gattc_api.h> ESP_GATTC_DIS_SRVC_CMPL_EVT.
Public Members
Operation status
uint16_t conn_id
Connection id
struct gattc_disconnect_evt_param
#include <esp_gattc_api.h> ESP_GATTC_DISCONNECT_EVT.
Public Members
disconnection reason
uint16_t conn_id
Connection id
struct gattc_exec_cmpl_evt_param
#include <esp_gattc_api.h> ESP_GATTC_EXEC_EVT.
Public Members
Operation status
uint16_t conn_id
Connection id
struct gattc_get_addr_list_evt_param
#include <esp_gattc_api.h> ESP_GATTC_GET_ADDR_LIST_EVT.
Public Members
Operation status
uint8_t num_addr
The number of address in the gattc cache address list

esp_bd_addr_t *addr_list
The pointer to the address list which has been get from the gattc cache
struct gattc_notify_evt_param
#include <esp_gattc_api.h> ESP_GATTC_NOTIFY_EVT.
Public Members
uint16_t conn_id
Connection id
uint16_t handle
The Characteristic or descriptor handle
uint16_t value_len
Notify attribute value
uint8_t *value
Notify attribute value
bool is_notify
True means notify, false means indicate
struct gattc_open_evt_param
#include <esp_gattc_api.h> ESP_GATTC_OPEN_EVT.
Public Members
Operation status
uint16_t conn_id
Connection id
uint16_t mtu
MTU size
struct gattc_queue_full_evt_param
#include <esp_gattc_api.h> ESP_GATTC_QUEUE_FULL_EVT.
Public Members
Operation status
uint16_t conn_id
Connection id
bool is_full
The gattc command queue is full or not
struct gattc_read_char_evt_param
#include <esp_gattc_api.h> ESP_GATTC_READ_CHAR_EVT, ESP_GATTC_READ_DESCR_EVT.

Public Members
Operation status
uint16_t conn_id
Connection id
uint16_t handle
Characteristic handle
uint8_t *value
Characteristic value
uint16_t value_len
Characteristic value length
struct gattc_reg_evt_param
#include <esp_gattc_api.h> ESP_GATTC_REG_EVT.
Public Members
Operation status
uint16_t app_id
Application id which input in register API
struct gattc_reg_for_notify_evt_param
#include <esp_gattc_api.h> ESP_GATTC_REG_FOR_NOTIFY_EVT.
Public Members
Operation status
uint16_t handle
The characteristic or descriptor handle
struct gattc_search_cmpl_evt_param
#include <esp_gattc_api.h> ESP_GATTC_SEARCH_CMPL_EVT.
Public Members
Operation status
uint16_t conn_id
Connection id
esp_service_source_t searched_service_source
The source of the service information
struct gattc_search_res_evt_param
#include <esp_gattc_api.h> ESP_GATTC_SEARCH_RES_EVT.

Public Members
uint16_t conn_id
Connection id
Service start handle
uint16_t end_handle
Service end handle
esp_gatt_id_t srvc_id
Service id, include service uuid and other information
bool is_primary
True if this is the primary service
struct gattc_set_assoc_addr_cmp_evt_param
#include <esp_gattc_api.h> ESP_GATTC_SET_ASSOC_EVT.
Public Members
Operation status
struct gattc_srvc_chg_evt_param
#include <esp_gattc_api.h> ESP_GATTC_SRVC_CHG_EVT.
Public Members
struct gattc_unreg_for_notify_evt_param
#include <esp_gattc_api.h> ESP_GATTC_UNREG_FOR_NOTIFY_EVT.
Public Members
Operation status
uint16_t handle
The characteristic or descriptor handle
struct gattc_write_evt_param
#include <esp_gattc_api.h> ESP_GATTC_WRITE_CHAR_EVT, ESP_GATTC_PREP_WRITE_EVT,
ESP_GATTC_WRITE_DESCR_EVT.
Public Members
Operation status
uint16_t conn_id
Connection id
uint16_t handle
The Characteristic or descriptor handle

uint16_t offset
The prepare write offset, this value is valid only when prepare write
Type Definitions
typedef void (*esp_gattc_cb_t)(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_if,
esp_ble_gattc_cb_param_t *param)
GATT Client callback function type.
Parameters
• gattc_if: : GATT client access interface, normally different gattc_if correspond to different
profile
Enumerations
enum esp_gattc_cb_event_t
GATT Client callback function events.
Values:
ESP_GATTC_REG_EVT = 0
When GATT client is registered, the event comes
ESP_GATTC_UNREG_EVT = 1
When GATT client is unregistered, the event comes
ESP_GATTC_OPEN_EVT = 2
When GATT virtual connection is set up, the event comes
ESP_GATTC_READ_CHAR_EVT = 3
When GATT characteristic is read, the event comes
ESP_GATTC_WRITE_CHAR_EVT = 4
When GATT characteristic write operation completes, the event comes
ESP_GATTC_CLOSE_EVT = 5
When GATT virtual connection is closed, the event comes
ESP_GATTC_SEARCH_CMPL_EVT = 6
When GATT service discovery is completed, the event comes
ESP_GATTC_SEARCH_RES_EVT = 7
When GATT service discovery result is got, the event comes
ESP_GATTC_READ_DESCR_EVT = 8
When GATT characteristic descriptor read completes, the event comes
ESP_GATTC_WRITE_DESCR_EVT = 9
When GATT characteristic descriptor write completes, the event comes
ESP_GATTC_NOTIFY_EVT = 10
When GATT notification or indication arrives, the event comes
ESP_GATTC_PREP_WRITE_EVT = 11
When GATT prepare-write operation completes, the event comes
ESP_GATTC_EXEC_EVT = 12
When write execution completes, the event comes
ESP_GATTC_ACL_EVT = 13
When ACL connection is up, the event comes
ESP_GATTC_CANCEL_OPEN_EVT = 14
When GATT client ongoing connection is cancelled, the event comes

ESP_GATTC_SRVC_CHG_EVT = 15
When service changed occurs, the event comes
ESP_GATTC_ENC_CMPL_CB_EVT = 17
When encryption procedure completes, the event comes
ESP_GATTC_CFG_MTU_EVT = 18
When configuration of MTU completes, the event comes
ESP_GATTC_ADV_DATA_EVT = 19
When advertising of data, the event comes
ESP_GATTC_MULT_ADV_ENB_EVT = 20
When multi-advertising is enabled, the event comes
ESP_GATTC_MULT_ADV_UPD_EVT = 21
When multi-advertising parameters are updated, the event comes
ESP_GATTC_MULT_ADV_DATA_EVT = 22
When multi-advertising data arrives, the event comes
ESP_GATTC_MULT_ADV_DIS_EVT = 23
When multi-advertising is disabled, the event comes
ESP_GATTC_CONGEST_EVT = 24
When GATT connection congestion comes, the event comes
ESP_GATTC_BTH_SCAN_ENB_EVT = 25
When batch scan is enabled, the event comes
ESP_GATTC_BTH_SCAN_CFG_EVT = 26
When batch scan storage is configured, the event comes
ESP_GATTC_BTH_SCAN_RD_EVT = 27
When Batch scan read event is reported, the event comes
ESP_GATTC_BTH_SCAN_THR_EVT = 28
When Batch scan threshold is set, the event comes
ESP_GATTC_BTH_SCAN_PARAM_EVT = 29
When Batch scan parameters are set, the event comes
ESP_GATTC_BTH_SCAN_DIS_EVT = 30
When Batch scan is disabled, the event comes
ESP_GATTC_SCAN_FLT_CFG_EVT = 31
When Scan filter configuration completes, the event comes
ESP_GATTC_SCAN_FLT_PARAM_EVT = 32
When Scan filter parameters are set, the event comes
ESP_GATTC_SCAN_FLT_STATUS_EVT = 33
When Scan filter status is reported, the event comes
ESP_GATTC_ADV_VSC_EVT = 34
When advertising vendor spec content event is reported, the event comes
ESP_GATTC_REG_FOR_NOTIFY_EVT = 38
When register for notification of a service completes, the event comes
ESP_GATTC_UNREG_FOR_NOTIFY_EVT = 39
When unregister for notification of a service completes, the event comes
ESP_GATTC_CONNECT_EVT = 40
When the ble physical connection is set up, the event comes
ESP_GATTC_DISCONNECT_EVT = 41
When the ble physical connection disconnected, the event comes

ESP_GATTC_READ_MULTIPLE_EVT = 42
When the ble characteristic or descriptor multiple complete, the event comes
ESP_GATTC_QUEUE_FULL_EVT = 43
When the gattc command queue full, the event comes
ESP_GATTC_SET_ASSOC_EVT = 44
When the ble gattc set the associated address complete, the event comes
ESP_GATTC_GET_ADDR_LIST_EVT = 45
When the ble get gattc address list in cache finish, the event comes
ESP_GATTC_DIS_SRVC_CMPL_EVT = 46
When the ble discover service complete, the event comes
BLUFI API
Overview BLUFI is a profile based GATT to config ESP32 WIFI to connect/disconnect AP or setup a softap and
etc. Use should concern these things:
1. The event sent from profile. Then you need to do something as the event indicate.
2. Security reference. You can write your own Security functions such as symmetrical encryption/decryption and
checksum functions. Even you can define the Key Exchange/Negotiation procedure.
Application Example Check bluetooth folder in ESP-IDF examples, which contains the following application:
• This is the BLUFI demo. This demo can set ESP32 s wifi to softap/station/softap&station mode and config
wifi connections - bluetooth/blufi
API Reference
Header File
• components/bt/common/api/include/api/esp_blufi_api.h
Functions
esp_err_t esp_blufi_register_callbacks(esp_blufi_callbacks_t *callbacks)
This function is called to receive blufi callback event.
Parameters
• [in] callbacks: callback functions
esp_err_t esp_blufi_profile_init(void)
This function is called to initialize blufi_profile.
esp_err_t esp_blufi_profile_deinit(void)
This function is called to de-initialize blufi_profile.
esp_err_t esp_blufi_send_wifi_conn_report(wifi_mode_t opmode, esp_blufi_sta_conn_state_t
sta_conn_state, uint8_t softap_conn_num,
esp_blufi_extra_info_t *extra_info)
This function is called to send wifi connection report.
Parameters
• opmode: : wifi opmode
• sta_conn_state: : station is already in connection or not

• softap_conn_num: : softap connection number

• extra_info: : extra information, such as sta_ssid, softap_ssid and etc.
esp_err_t esp_blufi_send_wifi_list(uint16_t apCount, esp_blufi_ap_record_t *list)
This function is called to send wifi list.
Parameters
• apCount: : wifi list count
• list: : wifi list
uint16_t esp_blufi_get_version(void)
Get BLUFI profile version.
Return Most 8bit significant is Great version, Least 8bit is Sub version
esp_err_t esp_blufi_send_error_info(esp_blufi_error_state_t state)
This function is called to send blufi error information.
Parameters
• state: : error state
esp_err_t esp_blufi_send_custom_data(uint8_t *data, uint32_t data_len)
This function is called to custom data.
Parameters
• data: : custom data value
• data_len: : the length of custom data
Unions
union esp_blufi_cb_param_t
#include <esp_blufi_api.h> BLUFI callback parameters union.
Public Members
struct esp_blufi_cb_param_t::blufi_init_finish_evt_param init_finish

Blufi callback param of ESP_BLUFI_EVENT_INIT_FINISH
struct esp_blufi_cb_param_t::blufi_deinit_finish_evt_param deinit_finish
Blufi callback param of ESP_BLUFI_EVENT_DEINIT_FINISH
struct esp_blufi_cb_param_t::blufi_set_wifi_mode_evt_param wifi_mode
Blufi callback param of ESP_BLUFI_EVENT_INIT_FINISH
struct esp_blufi_cb_param_t::blufi_connect_evt_param connect
Blufi callback param of ESP_BLUFI_EVENT_CONNECT
struct esp_blufi_cb_param_t::blufi_disconnect_evt_param disconnect
Blufi callback param of ESP_BLUFI_EVENT_DISCONNECT
struct esp_blufi_cb_param_t::blufi_recv_sta_bssid_evt_param sta_bssid
Blufi callback param of ESP_BLUFI_EVENT_RECV_STA_BSSID
struct esp_blufi_cb_param_t::blufi_recv_sta_ssid_evt_param sta_ssid
Blufi callback param of ESP_BLUFI_EVENT_RECV_STA_SSID
struct esp_blufi_cb_param_t::blufi_recv_sta_passwd_evt_param sta_passwd
Blufi callback param of ESP_BLUFI_EVENT_RECV_STA_PASSWD
struct esp_blufi_cb_param_t::blufi_recv_softap_ssid_evt_param softap_ssid
Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_SSID

struct esp_blufi_cb_param_t::blufi_recv_softap_passwd_evt_param softap_passwd

Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD
struct esp_blufi_cb_param_t::blufi_recv_softap_max_conn_num_evt_param softap_max_conn_num
Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUM
struct esp_blufi_cb_param_t::blufi_recv_softap_auth_mode_evt_param softap_auth_mode
Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE
struct esp_blufi_cb_param_t::blufi_recv_softap_channel_evt_param softap_channel
Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL
struct esp_blufi_cb_param_t::blufi_recv_username_evt_param username
Blufi callback param of ESP_BLUFI_EVENT_RECV_USERNAME
struct esp_blufi_cb_param_t::blufi_recv_ca_evt_param ca
Blufi callback param of ESP_BLUFI_EVENT_RECV_CA_CERT
struct esp_blufi_cb_param_t::blufi_recv_client_cert_evt_param client_cert
Blufi callback param of ESP_BLUFI_EVENT_RECV_CLIENT_CERT
struct esp_blufi_cb_param_t::blufi_recv_server_cert_evt_param server_cert
Blufi callback param of ESP_BLUFI_EVENT_RECV_SERVER_CERT
struct esp_blufi_cb_param_t::blufi_recv_client_pkey_evt_param client_pkey
Blufi callback param of ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY
struct esp_blufi_cb_param_t::blufi_recv_server_pkey_evt_param server_pkey
Blufi callback param of ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY
struct esp_blufi_cb_param_t::blufi_get_error_evt_param report_error
Blufi callback param of ESP_BLUFI_EVENT_REPORT_ERROR
struct esp_blufi_cb_param_t::blufi_recv_custom_data_evt_param custom_data
Blufi callback param of ESP_BLUFI_EVENT_RECV_CUSTOM_DATA
struct blufi_connect_evt_param
#include <esp_blufi_api.h> ESP_BLUFI_EVENT_CONNECT.
Public Members
Blufi Remote bluetooth device address
uint8_t server_if
server interface
uint16_t conn_id
Connection id
struct blufi_deinit_finish_evt_param
#include <esp_blufi_api.h> ESP_BLUFI_EVENT_DEINIT_FINISH.
Public Members
esp_blufi_deinit_state_t state
De-initial status
struct blufi_disconnect_evt_param
#include <esp_blufi_api.h> ESP_BLUFI_EVENT_DISCONNECT.

Public Members
Blufi Remote bluetooth device address
struct blufi_get_error_evt_param
#include <esp_blufi_api.h> ESP_BLUFI_EVENT_REPORT_ERROR.
Public Members
esp_blufi_error_state_t state
Blufi error state
struct blufi_init_finish_evt_param
#include <esp_blufi_api.h> ESP_BLUFI_EVENT_INIT_FINISH.
Public Members
esp_blufi_init_state_t state
Initial status
struct blufi_recv_ca_evt_param
#include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_CA_CERT.
Public Members
uint8_t *cert
CA certificate point
int cert_len
CA certificate length
struct blufi_recv_client_cert_evt_param
#include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_CLIENT_CERT
Public Members
uint8_t *cert
Client certificate point
int cert_len
Client certificate length
struct blufi_recv_client_pkey_evt_param
#include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY
Public Members
uint8_t *pkey
Client Private Key point, if Client certificate not contain Key
int pkey_len
Client Private key length
struct blufi_recv_custom_data_evt_param
#include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_CUSTOM_DATA.

Public Members
uint8_t *data
Custom data
uint32_t data_len
Custom data Length
struct blufi_recv_server_cert_evt_param
#include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_SERVER_CERT
Public Members
uint8_t *cert
Client certificate point
int cert_len
Client certificate length
struct blufi_recv_server_pkey_evt_param
#include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY
Public Members
uint8_t *pkey
Client Private Key point, if Client certificate not contain Key
int pkey_len
Client Private key length
struct blufi_recv_softap_auth_mode_evt_param
#include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE.
Public Members
wifi_auth_mode_t auth_mode
Authentication mode
struct blufi_recv_softap_channel_evt_param
#include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL.
Public Members
uint8_t channel
Authentication mode
struct blufi_recv_softap_max_conn_num_evt_param
#include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUM.
Public Members
int max_conn_num
SSID
struct blufi_recv_softap_passwd_evt_param
#include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD.

Public Members
uint8_t *passwd
Password
int passwd_len
Password Length
struct blufi_recv_softap_ssid_evt_param
#include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_SOFTAP_SSID.
Public Members
uint8_t *ssid
SSID
int ssid_len
SSID length
struct blufi_recv_sta_bssid_evt_param
#include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_STA_BSSID.
Public Members
uint8_t bssid[6]
BSSID
struct blufi_recv_sta_passwd_evt_param
#include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_STA_PASSWD.
Public Members
uint8_t *passwd
Password
int passwd_len
Password Length
struct blufi_recv_sta_ssid_evt_param
#include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_STA_SSID.
Public Members
uint8_t *ssid
SSID
int ssid_len
SSID length
struct blufi_recv_username_evt_param
#include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_USERNAME.
Public Members
uint8_t *name
Username point

int name_len
Username length
struct blufi_set_wifi_mode_evt_param
#include <esp_blufi_api.h> ESP_BLUFI_EVENT_SET_WIFI_MODE.
Public Members
wifi_mode_t op_mode
Wifi operation mode
Structures
struct esp_blufi_extra_info_t
BLUFI extra information structure.
Public Members
uint8_t sta_bssid[6]
BSSID of station interface
bool sta_bssid_set
is BSSID of station interface set
uint8_t *sta_ssid
SSID of station interface
int sta_ssid_len
length of SSID of station interface
uint8_t *sta_passwd
password of station interface
int sta_passwd_len
length of password of station interface
uint8_t *softap_ssid
SSID of softap interface
int softap_ssid_len
length of SSID of softap interface
uint8_t *softap_passwd
password of station interface
int softap_passwd_len
length of password of station interface
uint8_t softap_authmode
authentication mode of softap interface
bool softap_authmode_set
is authentication mode of softap interface set
uint8_t softap_max_conn_num
max connection number of softap interface
bool softap_max_conn_num_set
is max connection number of softap interface set
uint8_t softap_channel
channel of softap interface
bool softap_channel_set
is channel of softap interface set

struct esp_blufi_ap_record_t
Description of an WiFi AP.
Public Members
uint8_t ssid[33]
SSID of AP
int8_t rssi
signal strength of AP
struct esp_blufi_callbacks_t
BLUFI callback functions type.
Public Members
esp_blufi_event_cb_t event_cb
BLUFI event callback
esp_blufi_negotiate_data_handler_t negotiate_data_handler
BLUFI negotiate data function for negotiate share key
esp_blufi_encrypt_func_t encrypt_func
BLUFI encrypt data function with share key generated by negotiate_data_handler
esp_blufi_decrypt_func_t decrypt_func
BLUFI decrypt data function with share key generated by negotiate_data_handler
esp_blufi_checksum_func_t checksum_func
BLUFI check sum function (FCS)
Macros
ESP_BD_ADDR_LEN
Bluetooth address length.
Type Definitions
typedef uint8_t esp_bd_addr_t[ESP_BD_ADDR_LEN]
Bluetooth device address.
typedef void (*esp_blufi_event_cb_t)(esp_blufi_cb_event_t event, esp_blufi_cb_param_t
*param)
BLUFI event callback function type.
Parameters
typedef void (*esp_blufi_negotiate_data_handler_t)(uint8_t *data, int len, uint8_t
**output_data, int *output_len,
bool *need_free)
BLUFI negotiate data handler.
Parameters
• data: : data from phone
• len: : length of data from phone
• output_data: : data want to send to phone
• output_len: : length of data want to send to phone
• need_free: : output reporting if memory needs to be freed or not *
typedef int (*esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len)
BLUFI encrypt the data after negotiate a share key.

Return Nonnegative number is encrypted length, if error, return negative number;

Parameters
• iv8: : initial vector(8bit), normally, blufi core will input packet sequence number
• crypt_data: : plain text and encrypted data, the encrypt function must support autochthonous
encrypt
• crypt_len: : length of plain text
typedef int (*esp_blufi_decrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len)
BLUFI decrypt the data after negotiate a share key.
Return Nonnegative number is decrypted length, if error, return negative number;
Parameters
• crypt_data: : encrypted data and plain text, the encrypt function must support autochthonous
decrypt
• crypt_len: : length of encrypted text
typedef uint16_t (*esp_blufi_checksum_func_t)(uint8_t iv8, uint8_t *data, int len)
BLUFI checksum.
Parameters
• data: : data need to checksum
• len: : length of data
Enumerations
enum esp_blufi_cb_event_t
Values:
ESP_BLUFI_EVENT_INIT_FINISH = 0
ESP_BLUFI_EVENT_DEINIT_FINISH
ESP_BLUFI_EVENT_SET_WIFI_OPMODE
ESP_BLUFI_EVENT_BLE_CONNECT
ESP_BLUFI_EVENT_BLE_DISCONNECT
ESP_BLUFI_EVENT_REQ_CONNECT_TO_AP
ESP_BLUFI_EVENT_REQ_DISCONNECT_FROM_AP
ESP_BLUFI_EVENT_GET_WIFI_STATUS
ESP_BLUFI_EVENT_DEAUTHENTICATE_STA
ESP_BLUFI_EVENT_RECV_STA_BSSID
ESP_BLUFI_EVENT_RECV_STA_SSID
ESP_BLUFI_EVENT_RECV_STA_PASSWD
ESP_BLUFI_EVENT_RECV_SOFTAP_SSID
ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD
ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUM
ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE
ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL
ESP_BLUFI_EVENT_RECV_USERNAME
ESP_BLUFI_EVENT_RECV_CA_CERT
ESP_BLUFI_EVENT_RECV_CLIENT_CERT
ESP_BLUFI_EVENT_RECV_SERVER_CERT

ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY
ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY
ESP_BLUFI_EVENT_RECV_SLAVE_DISCONNECT_BLE
ESP_BLUFI_EVENT_GET_WIFI_LIST
ESP_BLUFI_EVENT_REPORT_ERROR
ESP_BLUFI_EVENT_RECV_CUSTOM_DATA
enum esp_blufi_sta_conn_state_t
BLUFI config status.
Values:
ESP_BLUFI_STA_CONN_SUCCESS = 0x00
ESP_BLUFI_STA_CONN_FAIL = 0x01
enum esp_blufi_init_state_t
BLUFI init status.
Values:
ESP_BLUFI_INIT_OK = 0
ESP_BLUFI_INIT_FAILED
enum esp_blufi_deinit_state_t
BLUFI deinit status.
Values:
ESP_BLUFI_DEINIT_OK = 0
ESP_BLUFI_DEINIT_FAILED
enum esp_blufi_error_state_t
Values:
ESP_BLUFI_SEQUENCE_ERROR = 0
ESP_BLUFI_CHECKSUM_ERROR
ESP_BLUFI_DECRYPT_ERROR
ESP_BLUFI_ENCRYPT_ERROR
ESP_BLUFI_INIT_SECURITY_ERROR
ESP_BLUFI_DH_MALLOC_ERROR
ESP_BLUFI_DH_PARAM_ERROR
ESP_BLUFI_READ_PARAM_ERROR
ESP_BLUFI_MAKE_PUBLIC_ERROR
ESP_BLUFI_DATA_FORMAT_ERROR
2.1.4 CLASSIC BT
CLASSIC BLUETOOTH GAP API

API Reference
Header File
• components/bt/host/bluedroid/api/include/api/esp_gap_bt_api.h
Functions
static uint32_t esp_bt_gap_get_cod_srvc(uint32_t cod)
get major service field of COD
Return major service bits
Parameters
• [in] cod: Class of Device
static uint32_t esp_bt_gap_get_cod_major_dev(uint32_t cod)
get major device field of COD
Return major device bits
Parameters
static uint32_t esp_bt_gap_get_cod_minor_dev(uint32_t cod)
get minor service field of COD
Return minor service bits
Parameters
static uint32_t esp_bt_gap_get_cod_format_type(uint32_t cod)
get format type of COD
Return format type
Parameters
static bool esp_bt_gap_is_valid_cod(uint32_t cod)
decide the integrity of COD
Return
• true if cod is valid
• false otherise
Parameters
esp_err_t esp_bt_gap_register_callback(esp_bt_gap_cb_t callback)
register callback function. This function should be called after esp_bluedroid_enable() completes successfully
Return
• ESP_FAIL: others
esp_err_t esp_bt_gap_set_scan_mode(esp_bt_connection_mode_t c_mode,
esp_bt_discovery_mode_t d_mode)
Set discoverability and connectability mode for legacy bluetooth. This function should be called after
esp_bluedroid_enable() completes successfully.
Return
• ESP_ERR_INVALID_ARG: if argument invalid
Parameters
• [in] c_mode: : one of the enums of esp_bt_connection_mode_t
• [in] d_mode: : one of the enums of esp_bt_discovery_mode_t

esp_err_t esp_bt_gap_start_discovery(esp_bt_inq_mode_t mode, uint8_t inq_len, uint8_t

num_rsps)
This function starts Inquiry and Name Discovery. This function should be called after esp_bluedroid_enable()
completes successfully. When Inquiry is halted and cached results do not contain device name, then Name
Discovery will connect to the peer target to get the device name. esp_bt_gap_cb_t will be called with
ESP_BT_GAP_DISC_STATE_CHANGED_EVT when Inquriry is started or Name Discovery is completed.
esp_bt_gap_cb_t will be called with ESP_BT_GAP_DISC_RES_EVT each time the two types of discovery
results are got.
Return
• ESP_ERR_INVALID_ARG: if invalid parameters are provided
Parameters
• [in] mode: - Inquiry mode
• [in] inq_len: - Inquiry duration in 1.28 sec units, ranging from 0x01 to 0x30. This parameter
only specifies the total duration of the Inquiry process,
– when this time expires, Inquiry will be halted.
• [in] num_rsps: - Number of responses that can be received before the Inquiry is halted, value
0 indicates an unlimited number of responses.
esp_err_t esp_bt_gap_cancel_discovery(void)
Cancel Inquiry and Name Discovery. This function should be called after esp_bluedroid_enable() completes
successfully. esp_bt_gap_cb_t will be called with ESP_BT_GAP_DISC_STATE_CHANGED_EVT if In-
quiry or Name Discovery is cancelled by calling this function.
Return
esp_err_t esp_bt_gap_get_remote_services(esp_bd_addr_t remote_bda)
Start SDP to get remote services. This function should be called after esp_bluedroid_enable() completes suc-
cessfully. esp_bt_gap_cb_t will be called with ESP_BT_GAP_RMT_SRVCS_EVT after service discovery
ends.
Return
esp_err_t esp_bt_gap_get_remote_service_record(esp_bd_addr_t remote_bda, esp_bt_uuid_t
*uuid)
Start SDP to look up the service matching uuid on the remote device. This function should be called after
esp_bt_gap_cb_t will be called with ESP_BT_GAP_RMT_SRVC_REC_EVT after service discovery ends
Return
uint8_t *esp_bt_gap_resolve_eir_data(uint8_t *eir, esp_bt_eir_type_t type, uint8_t *length)
This function is called to get EIR data for a specific type.
Return pointer of starting position of eir data excluding eir data type, NULL if not found
Parameters
• [in] eir: - pointer of raw eir data to be resolved
• [in] type: - specific EIR data type
• [out] length: - return the length of EIR data excluding fields of length and data type

esp_err_t esp_bt_gap_config_eir_data(esp_bt_eir_data_t *eir_data)

This function is called to config EIR data.
esp_bt_gap_cb_t will be called with ESP_BT_GAP_CONFIG_EIR_DATA_EVT after config EIR ends.
Return
• ESP_ERR_INVALID_ARG: if param is invalid
Parameters
• [in] eir_data: - pointer of EIR data content
esp_err_t esp_bt_gap_set_cod(esp_bt_cod_t cod, esp_bt_cod_mode_t mode)
This function is called to set class of device. The structure esp_bt_gap_cb_t will be called with
ESP_BT_GAP_SET_COD_EVT after set COD ends. Some profile have special restrictions on class of device,
changes may cause these profile do not work.
Return
• ESP_ERR_INVALID_ARG: if param is invalid
Parameters
• [in] cod: - class of device
• [in] mode: - setting mode
esp_err_t esp_bt_gap_get_cod(esp_bt_cod_t *cod)
This function is called to get class of device.
Return
Parameters
• [out] cod: - class of device
esp_err_t esp_bt_gap_read_rssi_delta(esp_bd_addr_t remote_addr)
This function is called to read RSSI delta by address after connected. The RSSI value returned by
ESP_BT_GAP_READ_RSSI_DELTA_EVT.
Return
Parameters
• [in] remote_addr: - remote device address, corresponding to a certain connection handle
esp_err_t esp_bt_gap_remove_bond_device(esp_bd_addr_t bd_addr)
Removes a device from the security database list of peer device.
Parameters
int esp_bt_gap_get_bond_device_num(void)
Get the device number from the security database list of peer device. It will return the device bonded number
immediately.
Return - >= 0 : bonded devices number
esp_err_t esp_bt_gap_get_bond_device_list(int *dev_num, esp_bd_addr_t *dev_list)
Get the device from the security database list of peer device. It will return the device bonded information
immediately.

Return
Parameters
• [inout] dev_num: Indicate the dev_list array(buffer) size as input. If dev_num is
large enough, it means the actual number as output. Suggest that dev_num value equal to
esp_ble_get_bond_device_num().
• [out] dev_list: an array(buffer) of esp_bd_addr_t type. Use for storing the bonded
devices address. The dev_list should be allocated by who call this API.
esp_err_t esp_bt_gap_set_pin(esp_bt_pin_type_t pin_type, uint8_t pin_code_len, esp_bt_pin_code_t
pin_code)
Set pin type and default pin code for legacy pairing.
• other : failed
Parameters
• [in] pin_type: Use variable or fixed pin. If pin_type is ESP_BT_PIN_TYPE_VARIABLE,
pin_code and pin_code_len will be ignored, and ESP_BT_GAP_PIN_REQ_EVT will come when
control requests for pin code. Else, will use fixed pin code and not callback to users.
• [in] pin_code_len: Length of pin_code
• [in] pin_code: Pin_code
esp_err_t esp_bt_gap_pin_reply(esp_bd_addr_t bd_addr, bool accept, uint8_t pin_code_len,
esp_bt_pin_code_t pin_code)
Reply the pin_code to the peer device for legacy pairing when ESP_BT_GAP_PIN_REQ_EVT is coming.
• other : failed
Parameters
• [in] bd_addr: BD address of the peer
• [in] accept: Pin_code reply successful or declined.
• [in] pin_code_len: Length of pin_code
• [in] pin_code: Pin_code
esp_err_t esp_bt_gap_set_security_param(esp_bt_sp_param_t param_type, void *value, uint8_t
len)
Set a GAP security parameter value. Overrides the default value.
• other : failed
Parameters
• [in] param_type: : the type of the param which is to be set
• [in] value: : the param value
• [in] len: : the length of the param value
esp_err_t esp_bt_gap_ssp_passkey_reply(esp_bd_addr_t bd_addr, bool accept, uint32_t
passkey)
Reply the key value to the peer device in the legacy connection stage.
• other : failed
Parameters
• [in] accept: : passkey entry successful or declined.
• [in] passkey: : passkey value, must be a 6 digit number, can be lead by 0.
esp_err_t esp_bt_gap_ssp_confirm_reply(esp_bd_addr_t bd_addr, bool accept)

Reply the confirm value to the peer device in the legacy connection stage.
• other : failed
Parameters
• [in] accept: : numbers to compare are the same or different
esp_err_t esp_bt_gap_set_afh_channels(esp_bt_gap_afh_channels channels)
Set the AFH channels.
• other : failed
Parameters
• [in] channels: : The n th such field (in the range 0 to 78) contains the value for channel n :
0 means channel n is bad. 1 means channel n is unknown. The most significant bit is reserved and
shall be set to 0. At least 20 channels shall be marked as unknown.
esp_err_t esp_bt_gap_read_remote_name(esp_bd_addr_t remote_bda)
Read the remote device name.
• other : failed
Parameters
• [in] remote_bda: The remote device s address
esp_err_t esp_bt_gap_set_qos(esp_bd_addr_t remote_bda, uint32_t t_poll)
Config Quality of service.
• other : failed
Parameters
• [in] remote_bda: The remote device s address
• [in] t_poll: Poll interval, the maximum time between transmissions which from the master to
a particular slave on the ACL logical transport. unit is 0.625ms
Unions
union esp_bt_gap_cb_param_t
#include <esp_gap_bt_api.h> A2DP state callback parameters.
Public Members
struct esp_bt_gap_cb_param_t::disc_res_param disc_res

discovery result parameter struct
struct esp_bt_gap_cb_param_t::disc_state_changed_param disc_st_chg
discovery state changed parameter struct
struct esp_bt_gap_cb_param_t::rmt_srvcs_param rmt_srvcs
services of remote device parameter struct
struct esp_bt_gap_cb_param_t::rmt_srvc_rec_param rmt_srvc_rec
specific service record from remote device parameter struct
struct esp_bt_gap_cb_param_t::read_rssi_delta_param read_rssi_delta
read rssi parameter struct
struct esp_bt_gap_cb_param_t::config_eir_data_param config_eir_data
config EIR data

struct esp_bt_gap_cb_param_t::auth_cmpl_param auth_cmpl

authentication complete parameter struct
struct esp_bt_gap_cb_param_t::pin_req_param pin_req
pin request parameter struct
struct esp_bt_gap_cb_param_t::cfm_req_param cfm_req
confirm request parameter struct
struct esp_bt_gap_cb_param_t::key_notif_param key_notif
passkey notif parameter struct
struct esp_bt_gap_cb_param_t::key_req_param key_req
passkey request parameter struct
struct esp_bt_gap_cb_param_t::set_afh_channels_param set_afh_channels
set AFH channel parameter struct
struct esp_bt_gap_cb_param_t::read_rmt_name_param read_rmt_name
read Remote Name parameter struct
struct esp_bt_gap_cb_param_t::mode_chg_param mode_chg
mode change event parameter struct
struct esp_bt_gap_cb_param_t::bt_remove_bond_dev_cmpl_evt_param remove_bond_dev_cmpl
Event parameter of ESP_BT_GAP_REMOVE_BOND_DEV_COMPLETE_EVT
struct esp_bt_gap_cb_param_t::qos_cmpl_param qos_cmpl
QoS complete parameter struct
struct auth_cmpl_param
#include <esp_gap_bt_api.h> ESP_BT_GAP_AUTH_CMPL_EVT.
Public Members
esp_bd_addr_t bda
remote bluetooth device address
authentication complete status
uint8_t device_name[ESP_BT_GAP_MAX_BDNAME_LEN + 1]
device name
struct bt_remove_bond_dev_cmpl_evt_param
#include <esp_gap_bt_api.h> ESP_BT_GAP_REMOVE_BOND_DEV_COMPLETE_EVT.
Public Members
esp_bd_addr_t bda
Indicate the remove bond device operation success status
struct cfm_req_param
#include <esp_gap_bt_api.h> ESP_BT_GAP_CFM_REQ_EVT.
Public Members
esp_bd_addr_t bda

uint32_t num_val
the numeric value for comparison.
struct config_eir_data_param
#include <esp_gap_bt_api.h> ESP_BT_GAP_CONFIG_EIR_DATA_EVT *.
Public Members
config EIR status: ESP_BT_STATUS_SUCCESS: config success
ESP_BT_STATUS_EIR_TOO_LARGE: the EIR data is more than 240B. The EIR may not
contain the whole data. others: failed
uint8_t eir_type_num
the number of EIR types in EIR type
esp_bt_eir_type_t eir_type[ESP_BT_EIR_TYPE_MAX_NUM]
EIR types in EIR type
struct disc_res_param
#include <esp_gap_bt_api.h> ESP_BT_GAP_DISC_RES_EVT.
Public Members
esp_bd_addr_t bda
int num_prop
number of properties got
esp_bt_gap_dev_prop_t *prop
properties discovered from the new device
struct disc_state_changed_param
#include <esp_gap_bt_api.h> ESP_BT_GAP_DISC_STATE_CHANGED_EVT.
Public Members
esp_bt_gap_discovery_state_t state
discovery state
struct key_notif_param
#include <esp_gap_bt_api.h> ESP_BT_GAP_KEY_NOTIF_EVT.
Public Members
esp_bd_addr_t bda
uint32_t passkey
the numeric value for passkey entry.
struct key_req_param
#include <esp_gap_bt_api.h> ESP_BT_GAP_KEY_REQ_EVT.

Public Members
esp_bd_addr_t bda
struct mode_chg_param
#include <esp_gap_bt_api.h> ESP_BT_GAP_MODE_CHG_EVT.
Public Members
esp_bd_addr_t bda
esp_bt_pm_mode_t mode
PM mode
struct pin_req_param
#include <esp_gap_bt_api.h> ESP_BT_GAP_PIN_REQ_EVT.
Public Members
esp_bd_addr_t bda
bool min_16_digit
TRUE if the pin returned must be at least 16 digits
struct qos_cmpl_param
#include <esp_gap_bt_api.h> ESP_BT_GAP_QOS_CMPL_EVT.
Public Members
QoS status
esp_bd_addr_t bda
uint32_t t_poll
poll interval, the maximum time between transmissions which from the master to a particular slave
on the ACL logical transport. unit is 0.625ms.
struct read_rmt_name_param
#include <esp_gap_bt_api.h> ESP_BT_GAP_READ_REMOTE_NAME_EVT.
Public Members
read Remote Name status
uint8_t rmt_name[ESP_BT_GAP_MAX_BDNAME_LEN + 1]
Remote device name
struct read_rssi_delta_param
#include <esp_gap_bt_api.h> ESP_BT_GAP_READ_RSSI_DELTA_EVT *.

Public Members
esp_bd_addr_t bda
read rssi status
int8_t rssi_delta
rssi delta value range -128 ~127, The value zero indicates that the RSSI is inside the Golden Receive
Power Range, the Golden Receive Power Range is from ESP_BT_GAP_RSSI_LOW_THRLD to
ESP_BT_GAP_RSSI_HIGH_THRLD
struct rmt_srvc_rec_param
#include <esp_gap_bt_api.h> ESP_BT_GAP_RMT_SRVC_REC_EVT.
Public Members
esp_bd_addr_t bda
service search status
struct rmt_srvcs_param
#include <esp_gap_bt_api.h> ESP_BT_GAP_RMT_SRVCS_EVT.
Public Members
esp_bd_addr_t bda
service search status
int num_uuids
number of UUID in uuid_list
esp_bt_uuid_t *uuid_list
list of service UUIDs of remote device
struct set_afh_channels_param
#include <esp_gap_bt_api.h> ESP_BT_GAP_SET_AFH_CHANNELS_EVT.
Public Members
set AFH channel status
Structures
struct esp_bt_cod_t
Class of device.
Public Members
uint32_t reserved_2 : 2
undefined

uint32_t minor : 6
minor class
uint32_t major : 5
major class
uint32_t service : 11
service class
uint32_t reserved_8 : 8
undefined
struct esp_bt_gap_dev_prop_t
Bluetooth Device Property Descriptor.
Public Members
esp_bt_gap_dev_prop_type_t type
Device property type
int len
Device property value length
void *val
Device property value
struct esp_bt_eir_data_t
EIR data content, according to Supplement to the Bluetooth Core Specification .
Public Members
bool fec_required
FEC is required or not, true by default
bool include_txpower
EIR data include TX power, false by default
bool include_uuid
EIR data include UUID, false by default
uint8_t flag
EIR flags, see ESP_BT_EIR_FLAG for details, EIR will not include flag if it is 0, 0 by default
uint16_t manufacturer_len
Manufacturer data length, 0 by default
uint8_t *p_manufacturer_data
Manufacturer data point
uint16_t url_len
URL length, 0 by default
uint8_t *p_url
URL point
Macros
ESP_BT_GAP_RSSI_HIGH_THRLD
RSSI threshold.
High RSSI threshold
ESP_BT_GAP_RSSI_LOW_THRLD
Low RSSI threshold
ESP_BT_GAP_AFH_CHANNELS_LEN

ESP_BT_GAP_MAX_BDNAME_LEN
Maximum bytes of Bluetooth device name.
ESP_BT_GAP_EIR_DATA_LEN
Maximum size of EIR Significant part.
ESP_BT_EIR_TYPE_FLAGS
Extended Inquiry Response data type.
Flag with information such as BR/EDR and LE support
ESP_BT_EIR_TYPE_INCMPL_16BITS_UUID
Incomplete list of 16-bit service UUIDs
ESP_BT_EIR_TYPE_CMPL_16BITS_UUID
Complete list of 16-bit service UUIDs
ESP_BT_EIR_TYPE_SHORT_LOCAL_NAME
Shortened Local Name
ESP_BT_EIR_TYPE_CMPL_LOCAL_NAME
Complete Local Name
ESP_BT_EIR_TYPE_TX_POWER_LEVEL
Tx power level, value is 1 octet ranging from -127 to 127, unit is dBm
ESP_BT_EIR_TYPE_URL
Uniform resource identifier
ESP_BT_EIR_TYPE_MANU_SPECIFIC
Manufacturer specific data
ESP_BT_EIR_TYPE_MAX_NUM
MAX number of EIR type
ESP_BT_EIR_FLAG_LIMIT_DISC
ESP_BT_EIR_FLAG_GEN_DISC
ESP_BT_EIR_FLAG_BREDR_NOT_SPT
ESP_BT_EIR_FLAG_DMT_CONTROLLER_SPT
ESP_BT_EIR_FLAG_DMT_HOST_SPT
ESP_BT_EIR_MAX_LEN
ESP_BT_PIN_CODE_LEN
Max pin code length
ESP_BT_IO_CAP_OUT
ESP_BT_IO_CAP_IO
ESP_BT_IO_CAP_IN
ESP_BT_IO_CAP_NONE
ESP_BT_PM_MD_ACTIVE
Active mode

ESP_BT_PM_MD_HOLD
Hold mode
ESP_BT_PM_MD_SNIFF
Sniff mode
ESP_BT_PM_MD_PARK
Park state
ESP_BT_COD_SRVC_BIT_MASK
Bits of major service class field.
Major service bit mask
ESP_BT_COD_SRVC_BIT_OFFSET
Major service bit offset
ESP_BT_COD_MAJOR_DEV_BIT_MASK
Bits of major device class field.
Major device bit mask
ESP_BT_COD_MAJOR_DEV_BIT_OFFSET
Major device bit offset
ESP_BT_COD_MINOR_DEV_BIT_MASK
Bits of minor device class field.
Minor device bit mask
ESP_BT_COD_MINOR_DEV_BIT_OFFSET
Minor device bit offset
ESP_BT_COD_FORMAT_TYPE_BIT_MASK
Bits of format type.
Format type bit mask
ESP_BT_COD_FORMAT_TYPE_BIT_OFFSET
Format type bit offset
ESP_BT_COD_FORMAT_TYPE_1
Class of device format type 1.
ESP_BT_GAP_MIN_INQ_LEN
Minimum and Maximum inquiry length Minimum inquiry duration, unit is 1.28s
ESP_BT_GAP_MAX_INQ_LEN
Maximum inquiry duration, unit is 1.28s
Type Definitions
typedef uint8_t esp_bt_gap_afh_channels[ESP_BT_GAP_AFH_CHANNELS_LEN]
typedef uint8_t esp_bt_eir_type_t
typedef uint8_t esp_bt_pin_code_t[ESP_BT_PIN_CODE_LEN]
Pin Code (upto 128 bits) MSB is 0
typedef uint8_t esp_bt_io_cap_t
Combination of the IO Capability
typedef uint8_t esp_bt_pm_mode_t
typedef void (*esp_bt_gap_cb_t)(esp_bt_gap_cb_event_t event, esp_bt_gap_cb_param_t *param)
bluetooth GAP callback function type
Parameters
• param: : Pointer to callback parameter

Enumerations
enum esp_bt_cod_mode_t
class of device settings
Values:
ESP_BT_SET_COD_MAJOR_MINOR = 0x01
overwrite major, minor class
ESP_BT_SET_COD_SERVICE_CLASS = 0x02
set the bits in the input, the current bit will remain
ESP_BT_CLR_COD_SERVICE_CLASS = 0x04
clear the bits in the input, others will remain
ESP_BT_SET_COD_ALL = 0x08
overwrite major, minor, set the bits in service class
ESP_BT_INIT_COD = 0x0a
overwrite major, minor, and service class
enum esp_bt_connection_mode_t
Discoverability and Connectability mode.
Values:
ESP_BT_NON_CONNECTABLE
Non-connectable
ESP_BT_CONNECTABLE
Connectable
enum esp_bt_discovery_mode_t
Values:
ESP_BT_NON_DISCOVERABLE
Non-discoverable
ESP_BT_LIMITED_DISCOVERABLE
Limited Discoverable
ESP_BT_GENERAL_DISCOVERABLE
General Discoverable
enum esp_bt_gap_dev_prop_type_t
Bluetooth Device Property type.
Values:
ESP_BT_GAP_DEV_PROP_BDNAME = 1
Bluetooth device name, value type is int8_t []
ESP_BT_GAP_DEV_PROP_COD
Class of Device, value type is uint32_t
ESP_BT_GAP_DEV_PROP_RSSI
Received Signal strength Indication, value type is int8_t, ranging from -128 to 127
ESP_BT_GAP_DEV_PROP_EIR
Extended Inquiry Response, value type is uint8_t []
enum esp_bt_cod_srvc_t
Major service class field of Class of Device, mutiple bits can be set.
Values:
ESP_BT_COD_SRVC_NONE = 0
None indicates an invalid value
ESP_BT_COD_SRVC_LMTD_DISCOVER = 0x1
Limited Discoverable Mode

ESP_BT_COD_SRVC_POSITIONING = 0x8
Positioning (Location identification)
ESP_BT_COD_SRVC_NETWORKING = 0x10
Networking, e.g. LAN, Ad hoc
ESP_BT_COD_SRVC_RENDERING = 0x20
Rendering, e.g. Printing, Speakers
ESP_BT_COD_SRVC_CAPTURING = 0x40
Capturing, e.g. Scanner, Microphone
ESP_BT_COD_SRVC_OBJ_TRANSFER = 0x80
Object Transfer, e.g. v-Inbox, v-Folder
ESP_BT_COD_SRVC_AUDIO = 0x100
Audio, e.g. Speaker, Microphone, Headset service
ESP_BT_COD_SRVC_TELEPHONY = 0x200
Telephony, e.g. Cordless telephony, Modem, Headset service
ESP_BT_COD_SRVC_INFORMATION = 0x400
Information, e.g., WEB-server, WAP-server
enum esp_bt_pin_type_t
Values:
ESP_BT_PIN_TYPE_VARIABLE = 0
Refer to BTM_PIN_TYPE_VARIABLE
ESP_BT_PIN_TYPE_FIXED = 1
Refer to BTM_PIN_TYPE_FIXED
enum esp_bt_sp_param_t
Values:
ESP_BT_SP_IOCAP_MODE = 0
Set IO mode
enum esp_bt_cod_major_dev_t
Major device class field of Class of Device.
Values:
ESP_BT_COD_MAJOR_DEV_MISC = 0
Miscellaneous
ESP_BT_COD_MAJOR_DEV_COMPUTER = 1
Computer
ESP_BT_COD_MAJOR_DEV_PHONE = 2
Phone(cellular, cordless, pay phone, modem
ESP_BT_COD_MAJOR_DEV_LAN_NAP = 3
LAN, Network Access Point
ESP_BT_COD_MAJOR_DEV_AV = 4
Audio/Video(headset, speaker, stereo, video display, VCR
ESP_BT_COD_MAJOR_DEV_PERIPHERAL = 5
Peripheral(mouse, joystick, keyboard)
ESP_BT_COD_MAJOR_DEV_IMAGING = 6
Imaging(printer, scanner, camera, display
ESP_BT_COD_MAJOR_DEV_WEARABLE = 7
Wearable
ESP_BT_COD_MAJOR_DEV_TOY = 8
Toy

ESP_BT_COD_MAJOR_DEV_HEALTH = 9
Health
ESP_BT_COD_MAJOR_DEV_UNCATEGORIZED = 31
Uncategorized: device not specified
enum esp_bt_gap_discovery_state_t
Bluetooth Device Discovery state
Values:
ESP_BT_GAP_DISCOVERY_STOPPED
Device discovery stopped
ESP_BT_GAP_DISCOVERY_STARTED
Device discovery started
enum esp_bt_gap_cb_event_t
BT GAP callback events.
Values:
ESP_BT_GAP_DISC_RES_EVT = 0
Device discovery result event
ESP_BT_GAP_DISC_STATE_CHANGED_EVT
Discovery state changed event
ESP_BT_GAP_RMT_SRVCS_EVT
Get remote services event
ESP_BT_GAP_RMT_SRVC_REC_EVT
Get remote service record event
ESP_BT_GAP_AUTH_CMPL_EVT
Authentication complete event
ESP_BT_GAP_PIN_REQ_EVT
Legacy Pairing Pin code request
ESP_BT_GAP_CFM_REQ_EVT
Security Simple Pairing User Confirmation request.
ESP_BT_GAP_KEY_NOTIF_EVT
Security Simple Pairing Passkey Notification
ESP_BT_GAP_KEY_REQ_EVT
Security Simple Pairing Passkey request
ESP_BT_GAP_READ_RSSI_DELTA_EVT
Read rssi event
ESP_BT_GAP_CONFIG_EIR_DATA_EVT
Config EIR data event
ESP_BT_GAP_SET_AFH_CHANNELS_EVT
Set AFH channels event
ESP_BT_GAP_READ_REMOTE_NAME_EVT
Read Remote Name event
ESP_BT_GAP_MODE_CHG_EVT
ESP_BT_GAP_REMOVE_BOND_DEV_COMPLETE_EVT
remove bond device complete event
ESP_BT_GAP_QOS_CMPL_EVT
QOS complete event
ESP_BT_GAP_EVT_MAX

enum esp_bt_inq_mode_t
Inquiry Mode
Values:
ESP_BT_INQ_MODE_GENERAL_INQUIRY
General inquiry mode
ESP_BT_INQ_MODE_LIMITED_INQUIRY
Limited inquiry mode
Bluetooth A2DP API
Application Example Check bluetooth/bluedroid/classic_bt folder in ESP-IDF examples, which contains the fol-
lowing application:
• This is a A2DP sink client demo. This demo can be discovered and connected by A2DP source device and
receive the audio stream from remote device - bluetooth/bluedroid/classic_bt/a2dp_sink
API Reference
Header File
• components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h
Functions
esp_err_t esp_a2d_register_callback(esp_a2d_cb_t callback)
Register application callback function to A2DP module. This function should be called only after
esp_bluedroid_enable() completes successfully, used by both A2DP source and sink.
Return
• ESP_OK: success
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: if callback is a NULL function pointer
Parameters
• [in] callback: A2DP event callback function
esp_err_t esp_a2d_sink_register_data_callback(esp_a2d_sink_data_cb_t callback)
Register A2DP sink data output function; For now the output is PCM data stream decoded from SBC format.
This function should be called only after esp_bluedroid_enable() completes successfully, used only by A2DP
sink. The callback is invoked in the context of A2DP sink task whose stack size is configurable through
menuconfig.
Return
• ESP_OK: success
Parameters
• [in] callback: A2DP sink data callback function
esp_err_t esp_a2d_sink_init(void)
Initialize the bluetooth A2DP sink module. This function should be called after esp_bluedroid_enable() com-
pletes successfully, and ESP_A2D_PROF_STATE_EVT with ESP_A2D_INIT_SUCCESS will reported to
the APP layer. Note: A2DP can work independently. If you want to use AVRC together, you should initiate
AVRC first. This function should be called after esp_bluedroid_enable() completes successfully.
Return
• ESP_OK: if the initialization request is sent successfully


esp_err_t esp_a2d_sink_deinit(void)
De-initialize for A2DP sink module. This function should be called only after esp_bluedroid_enable() com-
pletes successfully, and ESP_A2D_PROF_STATE_EVT with ESP_A2D_DEINIT_SUCCESS will reported
to APP layer.
Return
• ESP_OK: if the deinitialization request is sent successfully
esp_err_t esp_a2d_sink_connect(esp_bd_addr_t remote_bda)
Connect to remote bluetooth A2DP source device. This API must be called after esp_a2d_sink_init() and
before esp_a2d_sink_deinit().
Return
• ESP_OK: connect request is sent to lower layer successfully
Parameters
• [in] remote_bda: remote bluetooth device address
esp_err_t esp_a2d_sink_disconnect(esp_bd_addr_t remote_bda)
Disconnect from the remote A2DP source device. This API must be called after esp_a2d_sink_init() and
before esp_a2d_sink_deinit().
Return
• ESP_OK: disconnect request is sent to lower layer successfully
Parameters
esp_err_t esp_a2d_media_ctrl(esp_a2d_media_ctrl_t ctrl)
Media control commands. This API can be used for both A2DP sink and source and must be called after
esp_a2d_sink_init() and before esp_a2d_sink_deinit().
Return
• ESP_OK: control command is sent to lower layer successfully
Parameters
• [in] ctrl: control commands for A2DP data channel
esp_err_t esp_a2d_source_init(void)
Initialize the bluetooth A2DP source module. A2DP can work independently. If you want to use AVRC
together, you should initiate AVRC first. This function should be called after esp_bluedroid_enable() completes
successfully, and ESP_A2D_PROF_STATE_EVT with ESP_A2D_INIT_SUCCESS will reported to the APP
layer. Note: A2DP can work independently. If you want to use AVRC together, you should initiate AVRC
first.
Return
• ESP_OK: if the initialization request is sent to lower layer successfully
esp_err_t esp_a2d_source_deinit(void)
De-initialize for A2DP source module. This function should be called only after esp_bluedroid_enable() com-
pletes successfully, and ESP_A2D_PROF_STATE_EVT with ESP_A2D_DEINIT_SUCCESS will reported
to APP layer.
Return

• ESP_OK: success
esp_err_t esp_a2d_source_register_data_callback(esp_a2d_source_data_cb_t callback)
Register A2DP source data input function. For now, the input shoule be PCM data stream. This function should
be called only after esp_bluedroid_enable() completes successfully. The callback is invoked in the context of
A2DP source task whose stack size is configurable through menuconfig.
Return
• ESP_OK: success
Parameters
• [in] callback: A2DP source data callback function
esp_err_t esp_a2d_source_connect(esp_bd_addr_t remote_bda)
Connect to remote A2DP sink device. This API must be called after esp_a2d_source_init() and before
esp_a2d_source_deinit().
Return
• ESP_OK: connect request is sent to lower layer successfully
Parameters
esp_err_t esp_a2d_source_disconnect(esp_bd_addr_t remote_bda)
Disconnect from the remote A2DP sink device. This API must be called after esp_a2d_source_init() and
before esp_a2d_source_deinit().
Return
• ESP_OK: disconnect request is sent to lower layer
Parameters
Unions
union esp_a2d_cb_param_t
#include <esp_a2dp_api.h> A2DP state callback parameters.
Public Members
struct esp_a2d_cb_param_t::a2d_conn_stat_param conn_stat

A2DP connection status
struct esp_a2d_cb_param_t::a2d_audio_stat_param audio_stat
audio stream playing state
struct esp_a2d_cb_param_t::a2d_audio_cfg_param audio_cfg
media codec configuration information
struct esp_a2d_cb_param_t::media_ctrl_stat_param media_ctrl_stat
status in acknowledgement to media control commands
struct esp_a2d_cb_param_t::a2d_prof_stat_param a2d_prof_stat
status to indicate a2d prof init or deinit
struct a2d_audio_cfg_param
#include <esp_a2dp_api.h> ESP_A2D_AUDIO_CFG_EVT.

Public Members
esp_a2d_mcc_t mcc
A2DP media codec capability information
struct a2d_audio_stat_param
#include <esp_a2dp_api.h> ESP_A2D_AUDIO_STATE_EVT.
Public Members
esp_a2d_audio_state_t state
one of the values from esp_a2d_audio_state_t
struct a2d_conn_stat_param
#include <esp_a2dp_api.h> ESP_A2D_CONNECTION_STATE_EVT.
Public Members
esp_a2d_connection_state_t state
one of values from esp_a2d_connection_state_t
esp_a2d_disc_rsn_t disc_rsn
reason of disconnection for DISCONNECTED
struct a2d_prof_stat_param
#include <esp_a2dp_api.h> ESP_A2D_PROF_STATE_EVT.
Public Members
esp_a2d_init_state_t init_state
a2dp profile state param
struct media_ctrl_stat_param
#include <esp_a2dp_api.h> ESP_A2D_MEDIA_CTRL_ACK_EVT.
Public Members
esp_a2d_media_ctrl_t cmd
media control commands to acknowledge
esp_a2d_media_ctrl_ack_t status
acknowledgement to media control commands
Structures
struct esp_a2d_mcc_t
A2DP media codec capabilities union

Public Members
esp_a2d_mct_t type
A2DP media codec type
uint8_t sbc[ESP_A2D_CIE_LEN_SBC]
SBC codec capabilities
uint8_t m12[ESP_A2D_CIE_LEN_M12]
MPEG-1,2 audio codec capabilities
uint8_t m24[ESP_A2D_CIE_LEN_M24]
MPEG-2, 4 AAC audio codec capabilities
uint8_t atrac[ESP_A2D_CIE_LEN_ATRAC]
ATRAC family codec capabilities
union esp_a2d_mcc_t::[anonymous] cie
A2DP codec information element
Macros
ESP_A2D_MCT_SBC
Media codec types supported by A2DP.
SBC
ESP_A2D_MCT_M12
MPEG-1, 2 Audio
ESP_A2D_MCT_M24
MPEG-2, 4 AAC
ESP_A2D_MCT_ATRAC
ATRAC family
ESP_A2D_MCT_NON_A2DP
ESP_A2D_CIE_LEN_SBC
ESP_A2D_CIE_LEN_M12
ESP_A2D_CIE_LEN_M24
ESP_A2D_CIE_LEN_ATRAC
Type Definitions
typedef uint8_t esp_a2d_mct_t
typedef void (*esp_a2d_cb_t)(esp_a2d_cb_event_t event, esp_a2d_cb_param_t *param)
A2DP profile callback function type.
Parameters
typedef void (*esp_a2d_sink_data_cb_t)(const uint8_t *buf, uint32_t len)
A2DP sink data callback function.
Parameters
• [in] buf: : pointer to the data received from A2DP source device and is PCM format decoded
from SBC decoder; buf references to a static memory block and can be overwritten by upcoming
data
• [in] len: : size(in bytes) in buf
typedef int32_t (*esp_a2d_source_data_cb_t)(uint8_t *buf, int32_t len)
A2DP source data read callback function.
Return size of bytes read successfully, if the argument len is -1, this value is ignored.

Parameters
• [in] buf: : buffer to be filled with PCM data stream from higher layer
• [in] len: : size(in bytes) of data block to be copied to buf. -1 is an indication to user that data
buffer shall be flushed
Enumerations
enum esp_a2d_connection_state_t
Bluetooth A2DP connection states.
Values:
ESP_A2D_CONNECTION_STATE_DISCONNECTED = 0
connection released
ESP_A2D_CONNECTION_STATE_CONNECTING
connecting remote device
ESP_A2D_CONNECTION_STATE_CONNECTED
connection established
ESP_A2D_CONNECTION_STATE_DISCONNECTING
disconnecting remote device
enum esp_a2d_disc_rsn_t
Bluetooth A2DP disconnection reason.
Values:
ESP_A2D_DISC_RSN_NORMAL = 0
Finished disconnection that is initiated by local or remote device
ESP_A2D_DISC_RSN_ABNORMAL
Abnormal disconnection caused by signal loss
enum esp_a2d_audio_state_t
Bluetooth A2DP datapath states.
Values:
ESP_A2D_AUDIO_STATE_REMOTE_SUSPEND = 0
audio stream datapath suspended by remote device
ESP_A2D_AUDIO_STATE_STOPPED
audio stream datapath stopped
ESP_A2D_AUDIO_STATE_STARTED
audio stream datapath started
enum esp_a2d_media_ctrl_ack_t
A2DP media control command acknowledgement code.
Values:
ESP_A2D_MEDIA_CTRL_ACK_SUCCESS = 0
media control command is acknowledged with success
ESP_A2D_MEDIA_CTRL_ACK_FAILURE
media control command is acknowledged with failure
ESP_A2D_MEDIA_CTRL_ACK_BUSY
media control command is rejected, as previous command is not yet acknowledged
enum esp_a2d_media_ctrl_t
A2DP media control commands.
Values:
ESP_A2D_MEDIA_CTRL_NONE = 0
Not for application use, use inside stack only.

ESP_A2D_MEDIA_CTRL_CHECK_SRC_RDY
check whether AVDTP is connected, only used in A2DP source
ESP_A2D_MEDIA_CTRL_START
command to set up media transmission channel
ESP_A2D_MEDIA_CTRL_STOP
command to stop media transmission
ESP_A2D_MEDIA_CTRL_SUSPEND
command to suspend media transmission
enum esp_a2d_init_state_t
Bluetooth A2DP Initiation states.
Values:
ESP_A2D_DEINIT_SUCCESS = 0
A2DP profile deinit successful event
ESP_A2D_INIT_SUCCESS
A2DP profile deinit successful event
enum esp_a2d_cb_event_t
A2DP callback events.
Values:
ESP_A2D_CONNECTION_STATE_EVT = 0
connection state changed event
ESP_A2D_AUDIO_STATE_EVT
audio stream transmission state changed event
ESP_A2D_AUDIO_CFG_EVT
audio codec is configured, only used for A2DP SINK
ESP_A2D_MEDIA_CTRL_ACK_EVT
acknowledge event in response to media control commands
ESP_A2D_PROF_STATE_EVT
indicate a2dp init&deinit complete
BT AVRCP APIs
Overview Bluetooth AVRCP reference APIs.

Instructions
API Reference
Header File
• components/bt/host/bluedroid/api/include/api/esp_avrc_api.h
Functions
esp_err_t esp_avrc_ct_register_callback(esp_avrc_ct_cb_t callback)
Register application callbacks to AVRCP module. This function should be called after esp_bluedroid_enable()
completes successfully.
Return

• ESP_OK: success
Parameters
• [in] callback: AVRCP controller callback function
esp_err_t esp_avrc_ct_init(void)
Initialize the bluetooth AVRCP controller module, This function should be called after esp_bluedroid_enable()
completes successfully. Note: AVRC cannot work independently, AVRC should be used along with A2DP
and AVRC should be initialized before A2DP.
Return
• ESP_OK: success
esp_err_t esp_avrc_ct_deinit(void)
De-initialize AVRCP controller module. This function should be called after after esp_bluedroid_enable()
and AVRC should be deinitialized before A2DP.
Return
• ESP_OK: success
esp_err_t esp_avrc_ct_send_set_player_value_cmd(uint8_t tl, uint8_t attr_id, uint8_t
value_id)
Send player application settings command to AVRCP target. This function should be called after
ESP_AVRC_CT_CONNECTION_STATE_EVT is received and AVRCP connection is established.
Return
• ESP_OK: success
Parameters
• [in] tl: : transaction label, 0 to 15, consecutive commands should use different values
• [in] attr_id: : player application setting attribute IDs from one of esp_avrc_ps_attr_ids_t
• [in] value_id: : attribute value defined for the specific player application setting attribute
esp_err_t esp_avrc_ct_send_get_rn_capabilities_cmd(uint8_t tl)
Send GetCapabilities PDU to AVRCP target to retrieve remote device s supported notification event_ids.
This function should be called after ESP_AVRC_CT_CONNECTION_STATE_EVT is received and AVRCP
connection is established.
Return
• ESP_OK: success
Parameters
esp_err_t esp_avrc_ct_send_register_notification_cmd(uint8_t tl, uint8_t event_id,
uint32_t event_parameter)
Send register notification command to AVRCP target. This function should be called after
Return
• ESP_OK: success
• ESP_ERR_NOT_SUPPORTED: if the event_id is not supported in current implementation
Parameters
• [in] tl: : transaction label, 0 to 15, consecutive commands should use different values.

• [in] event_id: : id of events, e.g. ESP_AVRC_RN_PLAY_STATUS_CHANGE,

ESP_AVRC_RN_TRACK_CHANGE, etc.
• [in] event_parameter: : playback interval for
ESP_AVRC_RN_PLAY_POS_CHANGED; For other events , value of this parameter is
ignored.
esp_err_t esp_avrc_ct_send_set_absolute_volume_cmd(uint8_t tl, uint8_t volume)
Send set absolute volume command to AVRCP target. This function should be called after
Return
• ESP_OK: success
• ESP_ERR_NOT_SUPPORTED: if the event_id is not supported in current implementation
Parameters
• [in] volume: : volume, 0 to 0x7f, means 0% to 100%
esp_err_t esp_avrc_ct_send_metadata_cmd(uint8_t tl, uint8_t attr_mask)
Send metadata command to AVRCP target. This function should be called after
Return
• ESP_OK: success
Parameters
• [in] attr_mask: : mask of attributes, e.g. ESP_AVRC_MD_ATTR_ID_TITLE |
ESP_AVRC_MD_ATTR_ID_ARTIST.
esp_err_t esp_avrc_ct_send_passthrough_cmd(uint8_t tl, uint8_t key_code, uint8_t key_state)
Send passthrough command to AVRCP target. This function should be called after
Return
• ESP_OK: success
Parameters
• [in] key_code: : passthrough command code, e.g. ESP_AVRC_PT_CMD_PLAY,
ESP_AVRC_PT_CMD_STOP, etc.
• [in] key_state: : passthrough command key state,
ESP_AVRC_PT_CMD_STATE_PRESSED or ESP_AVRC_PT_CMD_STATE_RELEASED
esp_err_t esp_avrc_tg_register_callback(esp_avrc_tg_cb_t callback)
Register application callbacks to AVRCP target module. This function should be called after
Return
• ESP_OK: success
Parameters
• [in] callback: AVRCP target callback function
esp_err_t esp_avrc_tg_init(void)
Initialize the bluetooth AVRCP target module, This function should be called after esp_bluedroid_enable()
and AVRC should be initialized before A2DP.

Return
• ESP_OK: success
esp_err_t esp_avrc_tg_deinit(void)
De-initialize AVRCP target module. This function should be called after after esp_bluedroid_enable() com-
pletes successfully. Note: AVRC cannot work independently, AVRC should be used along with A2DP and
AVRC should be deinitialized before A2DP.
Return
• ESP_OK: success
esp_err_t esp_avrc_tg_get_psth_cmd_filter(esp_avrc_psth_filter_t filter,
esp_avrc_psth_bit_mask_t *cmd_set)
Get the current filter of remote passthrough commands on AVRC target. Filter is given by filter type
and bit mask for the passthrough commands. This function should be called after esp_avrc_tg_init().
For filter type ESP_AVRC_PSTH_FILTER_ALLOWED_CMD, the retrieved command set is constant
and it covers all of the passthrough commands that can possibly be supported. For filter type
ESP_AVRC_PSTH_FILTER_SUPPORT_COMMANDS, the retrieved command set covers the passthrough
commands selected to be supported according to current configuration. The configuration can be changed
using esp_avrc_tg_set_psth_cmd_filter().
Return
• ESP_OK: success
• ESP_ERR_INVALID_STATE: if bluetooth stack is not enabled or AVRC TG is not initialized
• ESP_ERR_INVALID_ARG: if filter type is invalid or cmd_set is NULL
• ESP_FAIL: otherwise
esp_err_t esp_avrc_tg_set_psth_cmd_filter(esp_avrc_psth_filter_t filter, const
esp_avrc_psth_bit_mask_t *cmd_set)
Set the filter of remote passthrough commands on AVRC target. Filter is given by filter type and bit mask for
the passthrough commands. This function should be called after esp_avrc_tg_init().
If filter type is ESP_AVRC_PSTH_FILTER_SUPPORT_CMD, the passthrough commands which are
set 1 as given in cmd_set will generate ESP_AVRC_CT_PASSTHROUGH_RSP_EVT callback event
and are auto-accepted in the protocol stack, other commands are replied with response type NOT
IMPLEMENTED (8). The set of supported commands should be a subset of allowed command
set. The allowed command set can be retrieved using esp_avrc_tg_get_psth_cmd_filter() with filter type
ESP_AVRC_PSTH_FILTER_ALLOWED_CMD .
Filter type ESP_AVRC_PSTH_FILTER_ALLOWED_CMD does not apply to this function.
Return
• ESP_OK: success
• ESP_ERR_INVALID_STATE: if bluetooth stack is not enabled
• ESP_ERR_INVALID_ARG: if filter type is invalid or cmd_set is NULL
• ESP_ERR_NOT_SUPPORTED:: if filter type is ESP_AVRC_PSTH_FILTER_ALLOWED_CMD,
or cmd_set includes unallowed commands
bool esp_avrc_psth_bit_mask_operation(esp_avrc_bit_mask_op_t op,
esp_avrc_psth_bit_mask_t *psth, esp_avrc_pt_cmd_t
cmd)
Operate on the type esp_avrc_psth_bit_mask_t with regard to a specific PASSTHROUGH command.
Return For operation ESP_AVRC_BIT_MASK_OP_SET or ESP_AVRC_BIT_MASK_OP_CLEAR,
return true for a successful operation, otherwise return false. For operation
ESP_AVRC_BIT_MASK_OP_TEST, return true if the corresponding bit is set, otherwise false.
Parameters
• [in] op: operation requested on the bit mask field
• [in] psth: pointer to passthrough command bit mask structure
• [in] cmd: passthrough command code

esp_err_t esp_avrc_tg_get_rn_evt_cap(esp_avrc_rn_evt_cap_t cap, esp_avrc_rn_evt_cap_mask_t

*evt_set)
Get the requested event notification capabilies on local AVRC target. The capability is returned in a bit mask
representation in evt_set. This function should be called after esp_avrc_tg_init().
For capability type ESP_AVRC_RN_CAP_ALLOWED_EVT, the retrieved event set is constant and it
covers all of the notifcation events that can possibly be supported with current implementation.
For capability type ESP_AVRC_RN_CAP_SUPPORTED_EVT, the event set covers the notification
events selected to be supported under current configuration, The configuration can be changed using
esp_avrc_tg_set_rn_evt_cap().
Return
• ESP_OK: success
• ESP_ERR_INVALID_ARG: if cap is invalid or evt_set is NULL
• ESP_FAIL: otherwise
esp_err_t esp_avrc_tg_set_rn_evt_cap(const esp_avrc_rn_evt_cap_mask_t *evt_set)
Set the event notification capabilities on local AVRCP target. The capability is given in a bit mask representation
in evt_set and must be a subset of allowed event IDs with current implementation. This function should be
called after esp_avrc_tg_init().
Return
• ESP_OK: success
• ESP_ERR_INVALID_STATE: if bluetooth stack is not enabled
• ESP_ERR_INVALID_ARG: if evt_set is NULL
bool esp_avrc_rn_evt_bit_mask_operation(esp_avrc_bit_mask_op_t op,
esp_avrc_rn_evt_cap_mask_t *events,
esp_avrc_rn_event_ids_t event_id)
Operate on the type esp_avrc_rn_evt_cap_mask_t with regard to a specific event.
For operation ESP_AVRC_BIT_MASK_OP_TEST, return true if the corresponding bit is set, otherwise false.
Return For operation ESP_AVRC_BIT_MASK_OP_SET or ESP_AVRC_BIT_MASK_OP_CLEAR, re-
turn true for a successful operation, otherwise return false.
Parameters
• [in] op: operation requested on the bit mask field
• [in] events: pointer to event notification capability bit mask structure
• [in] event_id: notification event code
esp_err_t esp_avrc_tg_send_rn_rsp(esp_avrc_rn_event_ids_t event_id, esp_avrc_rn_rsp_t rsp,
esp_avrc_rn_param_t *param)
Send RegisterNotification Response to remote AVRCP controller. Local event notification capability can be
set using esp_avrc_tg_set_rn_evt_cap(), in a bit mask representation in evt_set. This function should be called
after esp_avrc_tg_init().
Return
• ESP_OK: success
• ESP_ERR_INVALID_ARG: if evt_set is NULL
Parameters
• [in] event_id: notification event ID that remote AVRCP CT registers
• [in] rsp: notification response code
• [in] param: parameters included in the specific notification
Unions
union esp_avrc_rn_param_t
#include <esp_avrc_api.h> AVRCP notification parameters.

Public Members
uint8_t volume
response data for ESP_AVRC_RN_VOLUME_CHANGE, ranges 0..127
esp_avrc_playback_stat_t playback
response data for ESP_AVRC_RN_PLAY_STATUS_CHANGE
uint8_t elm_id[8]
response data for ESP_AVRC_RN_TRACK_CHANGE
uint32_t play_pos
response data for ESP_AVRC_RN_PLAY_POS_CHANGED, in millisecond
esp_avrc_batt_stat_t batt
response data for ESP_AVRC_RN_BATTERY_STATUS_CHANGE
union esp_avrc_ct_cb_param_t
#include <esp_avrc_api.h> AVRC controller callback parameters.
Public Members
struct esp_avrc_ct_cb_param_t::avrc_ct_conn_stat_param conn_stat

AVRC connection status
struct esp_avrc_ct_cb_param_t::avrc_ct_psth_rsp_param psth_rsp
passthrough command response
struct esp_avrc_ct_cb_param_t::avrc_ct_meta_rsp_param meta_rsp
metadata attributes response
struct esp_avrc_ct_cb_param_t::avrc_ct_change_notify_param change_ntf
notifications
struct esp_avrc_ct_cb_param_t::avrc_ct_rmt_feats_param rmt_feats
AVRC features discovered from remote SDP server
struct esp_avrc_ct_cb_param_t::avrc_ct_get_rn_caps_rsp_param get_rn_caps_rsp
get supported event capabilities response from AVRCP target
struct esp_avrc_ct_cb_param_t::avrc_ct_set_volume_rsp_param set_volume_rsp
set absolute volume response event
struct avrc_ct_change_notify_param
#include <esp_avrc_api.h> ESP_AVRC_CT_CHANGE_NOTIFY_EVT.
Public Members
uint8_t event_id
id of AVRC event notification
esp_avrc_rn_param_t event_parameter
event notification parameter
struct avrc_ct_conn_stat_param
#include <esp_avrc_api.h> ESP_AVRC_CT_CONNECTION_STATE_EVT.
Public Members
bool connected
whether AVRC connection is set up

struct avrc_ct_get_rn_caps_rsp_param
#include <esp_avrc_api.h> ESP_AVRC_CT_GET_RN_CAPABILITIES_RSP_EVT.
Public Members
uint8_t cap_count
number of items provided in event or company_id according to cap_id used
esp_avrc_rn_evt_cap_mask_t evt_set
supported event_ids represented in bit-mask
struct avrc_ct_meta_rsp_param
#include <esp_avrc_api.h> ESP_AVRC_CT_METADATA_RSP_EVT.
Public Members
uint8_t attr_id
id of metadata attribute
uint8_t *attr_text
attribute itself
int attr_length
attribute character length
struct avrc_ct_psth_rsp_param
#include <esp_avrc_api.h> ESP_AVRC_CT_PASSTHROUGH_RSP_EVT.
Public Members
uint8_t tl
transaction label, 0 to 15
uint8_t key_code
passthrough command code
uint8_t key_state
0 for PRESSED, 1 for RELEASED
struct avrc_ct_rmt_feats_param
#include <esp_avrc_api.h> ESP_AVRC_CT_REMOTE_FEATURES_EVT.
Public Members
uint32_t feat_mask
AVRC feature mask of remote device
uint16_t tg_feat_flag
feature flag of remote device as TG
struct avrc_ct_set_volume_rsp_param
#include <esp_avrc_api.h> ESP_AVRC_CT_SET_ABSOLUTE_VOLUME_RSP_EVT.

Public Members
uint8_t volume
the volume which has actually been set, range is 0 to 0x7f, means 0% to 100%
union esp_avrc_tg_cb_param_t
#include <esp_avrc_api.h> AVRC target callback parameters.
Public Members
struct esp_avrc_tg_cb_param_t::avrc_tg_conn_stat_param conn_stat

AVRC connection status
struct esp_avrc_tg_cb_param_t::avrc_tg_rmt_feats_param rmt_feats
AVRC features discovered through SDP
struct esp_avrc_tg_cb_param_t::avrc_tg_psth_cmd_param psth_cmd
passthrough command
struct esp_avrc_tg_cb_param_t::avrc_tg_set_abs_vol_param set_abs_vol
set absolute volume command targeted on audio sink
struct esp_avrc_tg_cb_param_t::avrc_tg_reg_ntf_param reg_ntf
register notification
struct esp_avrc_tg_cb_param_t::avrc_tg_set_app_value_param set_app_value
set player application value
struct avrc_tg_conn_stat_param
#include <esp_avrc_api.h> ESP_AVRC_TG_CONNECTION_STATE_EVT.
Public Members
bool connected
whether AVRC connection is set up
struct avrc_tg_psth_cmd_param
#include <esp_avrc_api.h> ESP_AVRC_TG_PASSTHROUGH_CMD_EVT.
Public Members
uint8_t key_code
passthrough command code
uint8_t key_state
0 for PRESSED, 1 for RELEASED
struct avrc_tg_reg_ntf_param
#include <esp_avrc_api.h> ESP_AVRC_TG_REGISTER_NOTIFICATION_EVT.
Public Members
uint8_t event_id
event id of AVRC RegisterNotification
uint32_t event_parameter
event notification parameter

struct avrc_tg_rmt_feats_param
#include <esp_avrc_api.h> ESP_AVRC_TG_REMOTE_FEATURES_EVT.
Public Members
uint32_t feat_mask
AVRC feature mask of remote device
uint16_t ct_feat_flag
feature flag of remote device as CT
struct avrc_tg_set_abs_vol_param
#include <esp_avrc_api.h> ESP_AVRC_TG_SET_ABSOLUTE_VOLUME_CMD_EVT.
Public Members
uint8_t volume
volume ranges from 0 to 127
struct avrc_tg_set_app_value_param
#include <esp_avrc_api.h> ESP_AVRC_TG_SET_PLAYER_APP_VALUE_EVT.
Public Members
uint8_t num_val
attribute num
esp_avrc_set_app_value_param_t *p_vals
point to the id and value of player application attribute
Structures
struct esp_avrc_psth_bit_mask_t
AVRC passthrough command bit mask.
Public Members
uint16_t bits[8]
bit mask representation of PASSTHROUGH commands
struct esp_avrc_rn_evt_cap_mask_t
AVRC target notification event capability bit mask.
Public Members
uint16_t bits
bit mask representation of PASSTHROUGH commands
struct esp_avrc_set_app_value_param_t
AVRCP set app value parameters.

Public Members
uint8_t attr_id
player application attribute id
uint8_t attr_val
player application attribute value
Macros
ESP_AVRC_TRANS_LABEL_MAX
max transaction label
Type Definitions
typedef void (*esp_avrc_ct_cb_t)(esp_avrc_ct_cb_event_t event, esp_avrc_ct_cb_param_t
*param)
AVRCP controller callback function type.
Parameters
• param: : Pointer to callback parameter union
typedef void (*esp_avrc_tg_cb_t)(esp_avrc_tg_cb_event_t event, esp_avrc_tg_cb_param_t
*param)
AVRCP target callback function type.
Parameters
• param: : Pointer to callback parameter union
Enumerations
enum esp_avrc_features_t
AVRC feature bit mask.
Values:
ESP_AVRC_FEAT_RCTG = 0x0001
remote control target
ESP_AVRC_FEAT_RCCT = 0x0002
remote control controller
ESP_AVRC_FEAT_VENDOR = 0x0008
remote control vendor dependent commands
ESP_AVRC_FEAT_BROWSE = 0x0010
use browsing channel
ESP_AVRC_FEAT_META_DATA = 0x0040
remote control metadata transfer command/response
ESP_AVRC_FEAT_ADV_CTRL = 0x0200
remote control advanced control commmand/response
enum esp_avrc_feature_flag_t
AVRC supported features flag retrieved in SDP record.
Values:
ESP_AVRC_FEAT_FLAG_CAT1 = 0x0001
category 1
category 2

category 3
category 4
ESP_AVRC_FEAT_FLAG_BROWSING = 0x0040
browsing
ESP_AVRC_FEAT_FLAG_COVER_ART_GET_IMAGE_PROP = 0x0080
Cover Art GetImageProperties
ESP_AVRC_FEAT_FLAG_COVER_ART_GET_IMAGE = 0x0100
Cover Art GetImage
ESP_AVRC_FEAT_FLAG_COVER_ART_GET_LINKED_THUMBNAIL = 0x0200
Cover Art GetLinkedThumbnail
enum esp_avrc_pt_cmd_t
AVRC passthrough command code.
Values:
ESP_AVRC_PT_CMD_SELECT = 0x00
select
ESP_AVRC_PT_CMD_UP = 0x01
up
ESP_AVRC_PT_CMD_DOWN = 0x02
down
ESP_AVRC_PT_CMD_LEFT = 0x03
left
ESP_AVRC_PT_CMD_RIGHT = 0x04
right
ESP_AVRC_PT_CMD_RIGHT_UP = 0x05
right-up
ESP_AVRC_PT_CMD_RIGHT_DOWN = 0x06
right-down
ESP_AVRC_PT_CMD_LEFT_UP = 0x07
left-up
ESP_AVRC_PT_CMD_LEFT_DOWN = 0x08
left-down
ESP_AVRC_PT_CMD_ROOT_MENU = 0x09
root menu
ESP_AVRC_PT_CMD_SETUP_MENU = 0x0A
setup menu
ESP_AVRC_PT_CMD_CONT_MENU = 0x0B
contents menu
ESP_AVRC_PT_CMD_FAV_MENU = 0x0C
favorite menu
ESP_AVRC_PT_CMD_EXIT = 0x0D
exit
ESP_AVRC_PT_CMD_0 = 0x20
0
1

2
3
4
5
6
7
8
9
ESP_AVRC_PT_CMD_DOT = 0x2A
dot
ESP_AVRC_PT_CMD_ENTER = 0x2B
enter
ESP_AVRC_PT_CMD_CLEAR = 0x2C
clear
ESP_AVRC_PT_CMD_CHAN_UP = 0x30
channel up
ESP_AVRC_PT_CMD_CHAN_DOWN = 0x31
channel down
ESP_AVRC_PT_CMD_PREV_CHAN = 0x32
previous channel
ESP_AVRC_PT_CMD_SOUND_SEL = 0x33
sound select
ESP_AVRC_PT_CMD_INPUT_SEL = 0x34
input select
ESP_AVRC_PT_CMD_DISP_INFO = 0x35
display information
ESP_AVRC_PT_CMD_HELP = 0x36
help
ESP_AVRC_PT_CMD_PAGE_UP = 0x37
page up
ESP_AVRC_PT_CMD_PAGE_DOWN = 0x38
page down
ESP_AVRC_PT_CMD_POWER = 0x40
power
ESP_AVRC_PT_CMD_VOL_UP = 0x41
volume up
ESP_AVRC_PT_CMD_VOL_DOWN = 0x42
volume down

ESP_AVRC_PT_CMD_MUTE = 0x43
mute
ESP_AVRC_PT_CMD_PLAY = 0x44
play
ESP_AVRC_PT_CMD_STOP = 0x45
stop
ESP_AVRC_PT_CMD_PAUSE = 0x46
pause
ESP_AVRC_PT_CMD_RECORD = 0x47
record
ESP_AVRC_PT_CMD_REWIND = 0x48
rewind
ESP_AVRC_PT_CMD_FAST_FORWARD = 0x49
fast forward
ESP_AVRC_PT_CMD_EJECT = 0x4A
eject
ESP_AVRC_PT_CMD_FORWARD = 0x4B
forward
ESP_AVRC_PT_CMD_BACKWARD = 0x4C
backward
ESP_AVRC_PT_CMD_ANGLE = 0x50
angle
ESP_AVRC_PT_CMD_SUBPICT = 0x51
subpicture
ESP_AVRC_PT_CMD_F1 = 0x71
F1
F2
F3
F4
F5
ESP_AVRC_PT_CMD_VENDOR = 0x7E
vendor unique
enum esp_avrc_psth_filter_t
AVRC passthrough command filter.
Values:
ESP_AVRC_PSTH_FILTER_ALLOWED_CMD = 0
all of the PASSTHROUGH commands that can possibly be used, immuateble
ESP_AVRC_PSTH_FILTER_SUPPORTED_CMD = 1
PASSTHROUGH commands selectively supported according to the current configuration
ESP_AVRC_PSTH_FILTER_SUPPORT_MAX
enum esp_avrc_bit_mask_op_t
Values:

ESP_AVRC_BIT_MASK_OP_TEST = 0
operation code to test a specific bit
ESP_AVRC_BIT_MASK_OP_SET = 1
operation code to set a specific bit
ESP_AVRC_BIT_MASK_OP_CLEAR = 2
operation code to clear a specific bit
enum esp_avrc_pt_cmd_state_t
AVRC passthrough command state.
Values:
ESP_AVRC_PT_CMD_STATE_PRESSED = 0
key pressed
ESP_AVRC_PT_CMD_STATE_RELEASED = 1
key released
enum esp_avrc_ct_cb_event_t
AVRC Controller callback events.
Values:
ESP_AVRC_CT_CONNECTION_STATE_EVT = 0
ESP_AVRC_CT_PASSTHROUGH_RSP_EVT = 1
passthrough response event
ESP_AVRC_CT_METADATA_RSP_EVT = 2
metadata response event
ESP_AVRC_CT_PLAY_STATUS_RSP_EVT = 3
play status response event
ESP_AVRC_CT_CHANGE_NOTIFY_EVT = 4
notification event
ESP_AVRC_CT_REMOTE_FEATURES_EVT = 5
feature of remote device indication event
ESP_AVRC_CT_GET_RN_CAPABILITIES_RSP_EVT = 6
supported notification events capability of peer device
ESP_AVRC_CT_SET_ABSOLUTE_VOLUME_RSP_EVT = 7
set absolute volume response event
enum esp_avrc_tg_cb_event_t
AVRC Target callback events.
Values:
ESP_AVRC_TG_CONNECTION_STATE_EVT = 0
ESP_AVRC_TG_REMOTE_FEATURES_EVT = 1
feature of remote device indication event
ESP_AVRC_TG_PASSTHROUGH_CMD_EVT = 2
passthrough command event
ESP_AVRC_TG_SET_ABSOLUTE_VOLUME_CMD_EVT = 3
set absolute volume command from remote device
ESP_AVRC_TG_REGISTER_NOTIFICATION_EVT = 4
register notification event

ESP_AVRC_TG_SET_PLAYER_APP_VALUE_EVT = 5
set applicaton attribute value, attribute refer to esp_avrc_ps_attr_ids_t
enum esp_avrc_md_attr_mask_t
AVRC metadata attribute mask.
Values:
ESP_AVRC_MD_ATTR_TITLE = 0x1
title of the playing track
ESP_AVRC_MD_ATTR_ARTIST = 0x2
track artist
ESP_AVRC_MD_ATTR_ALBUM = 0x4
album name
ESP_AVRC_MD_ATTR_TRACK_NUM = 0x8
track position on the album
ESP_AVRC_MD_ATTR_NUM_TRACKS = 0x10
number of tracks on the album
ESP_AVRC_MD_ATTR_GENRE = 0x20
track genre
ESP_AVRC_MD_ATTR_PLAYING_TIME = 0x40
total album playing time in miliseconds
enum esp_avrc_rn_event_ids_t
AVRC event notification ids.
Values:
ESP_AVRC_RN_PLAY_STATUS_CHANGE = 0x01
track status change, eg. from playing to paused
ESP_AVRC_RN_TRACK_CHANGE = 0x02
new track is loaded
ESP_AVRC_RN_TRACK_REACHED_END = 0x03
current track reached end
ESP_AVRC_RN_TRACK_REACHED_START = 0x04
current track reached start position
ESP_AVRC_RN_PLAY_POS_CHANGED = 0x05
track playing position changed
ESP_AVRC_RN_BATTERY_STATUS_CHANGE = 0x06
battery status changed
ESP_AVRC_RN_SYSTEM_STATUS_CHANGE = 0x07
system status changed
ESP_AVRC_RN_APP_SETTING_CHANGE = 0x08
application settings changed
ESP_AVRC_RN_NOW_PLAYING_CHANGE = 0x09
now playing content changed
ESP_AVRC_RN_AVAILABLE_PLAYERS_CHANGE = 0x0a
available players changed
ESP_AVRC_RN_ADDRESSED_PLAYER_CHANGE = 0x0b
the addressed player changed
ESP_AVRC_RN_UIDS_CHANGE = 0x0c
UIDs changed

ESP_AVRC_RN_VOLUME_CHANGE = 0x0d
volume changed locally on TG
ESP_AVRC_RN_MAX_EVT
enum esp_avrc_rn_evt_cap_t
AVRC target notification event notification capability.
Values:
ESP_AVRC_RN_CAP_ALLOWED_EVT = 0
all of the notification events that can possibly be supported, immutable
ESP_AVRC_RN_CAP_SUPPORTED_EVT = 1
notification events selectively supported according to the current configuration
ESP_AVRC_RN_CAP_MAX
enum esp_avrc_rn_rsp_t
AVRC notification response type.
Values:
ESP_AVRC_RN_RSP_INTERIM = 13
initial response to RegisterNotification, should be sent T_mtp(1000ms) from receiving the command
ESP_AVRC_RN_RSP_CHANGED = 15
final response to RegisterNotification command
enum esp_avrc_ps_attr_ids_t
AVRC player setting ids.
Values:
ESP_AVRC_PS_EQUALIZER = 0x01
equalizer, on or off
ESP_AVRC_PS_REPEAT_MODE = 0x02
repeat mode
ESP_AVRC_PS_SHUFFLE_MODE = 0x03
shuffle mode
ESP_AVRC_PS_SCAN_MODE = 0x04
scan mode on or off
ESP_AVRC_PS_MAX_ATTR
enum esp_avrc_ps_eq_value_ids_t
AVRC equalizer modes.
Values:
ESP_AVRC_PS_EQUALIZER_OFF = 0x1
equalizer OFF
ESP_AVRC_PS_EQUALIZER_ON = 0x2
equalizer ON
enum esp_avrc_ps_rpt_value_ids_t
AVRC repeat modes.
Values:
ESP_AVRC_PS_REPEAT_OFF = 0x1
repeat mode off
ESP_AVRC_PS_REPEAT_SINGLE = 0x2
single track repeat

ESP_AVRC_PS_REPEAT_GROUP = 0x3
group repeat
enum esp_avrc_ps_shf_value_ids_t
AVRC shuffle modes.
Values:
ESP_AVRC_PS_SHUFFLE_OFF = 0x1
ESP_AVRC_PS_SHUFFLE_ALL = 0x2
ESP_AVRC_PS_SHUFFLE_GROUP = 0x3
enum esp_avrc_ps_scn_value_ids_t
AVRC scan modes.
Values:
ESP_AVRC_PS_SCAN_OFF = 0x1
scan off
ESP_AVRC_PS_SCAN_ALL = 0x2
all tracks scan
ESP_AVRC_PS_SCAN_GROUP = 0x3
group scan
enum esp_avrc_rsp_t
AVCTP response codes.
Values:
ESP_AVRC_RSP_NOT_IMPL = 8
not implemented
ESP_AVRC_RSP_ACCEPT = 9
accept
ESP_AVRC_RSP_REJECT = 10
reject
ESP_AVRC_RSP_IN_TRANS = 11
in transition
ESP_AVRC_RSP_IMPL_STBL = 12
implemented/stable
ESP_AVRC_RSP_CHANGED = 13
changed
ESP_AVRC_RSP_INTERIM = 15
interim
enum esp_avrc_batt_stat_t
AVRCP battery status.
Values:
ESP_AVRC_BATT_NORMAL = 0
normal state
ESP_AVRC_BATT_WARNING = 1
unable to operate soon
ESP_AVRC_BATT_CRITICAL = 2
cannot operate any more
ESP_AVRC_BATT_EXTERNAL = 3
plugged to external power supply

ESP_AVRC_BATT_FULL_CHARGE = 4
when completely charged from external power supply
enum esp_avrc_playback_stat_t
AVRCP current status of playback.
Values:
ESP_AVRC_PLAYBACK_STOPPED = 0
stopped
ESP_AVRC_PLAYBACK_PLAYING = 1
playing
ESP_AVRC_PLAYBACK_PAUSED = 2
paused
ESP_AVRC_PLAYBACK_FWD_SEEK = 3
forward seek
ESP_AVRC_PLAYBACK_REV_SEEK = 4
reverse seek
ESP_AVRC_PLAYBACK_ERROR = 0xFF
error
SPP API
Application Example Check bluetooth/bluedroid/classic_bt folder in ESP-IDF examples, which contains the fol-
lowing application:
• This is a SPP demo. This demo can discover the service, connect, send and recive SPP data blue-
tooth/bluedroid/classic_bt/bt_spp_acceptor, bluetooth/bluedroid/classic_bt/bt_spp_initiator
API Reference
Header File
• components/bt/host/bluedroid/api/include/api/esp_spp_api.h
Functions
esp_err_t esp_spp_register_callback(esp_spp_cb_t callback)
This function is called to init callbacks with SPP module.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] callback: pointer to the init callback function.
esp_err_t esp_spp_init(esp_spp_mode_t mode)
This function is called to init SPP module. When the operation is completed, the callback function will be called
with ESP_SPP_INIT_EVT. This function should be called after esp_bluedroid_enable() completes success-
fully.
Return
• ESP_OK: success
• other: failed
Parameters

• [in] mode: Choose the mode of SPP, ESP_SPP_MODE_CB or ESP_SPP_MODE_VFS.

esp_err_t esp_spp_deinit(void)
This function is called to uninit SPP module. The operation will close all active SPP connection first, then the
callback function will be called with ESP_SPP_CLOSE_EVT, and the number of ESP_SPP_CLOSE_EVT
is equal to the number of connection. When the operation is completed, the callback function will be called
with ESP_SPP_UNINIT_EVT. This function should be called after esp_spp_init() completes successfully.
Return
• ESP_OK: success
• other: failed
esp_err_t esp_spp_start_discovery(esp_bd_addr_t bd_addr)
This function is called to performs service discovery for the services provided by the given peer device. When
the operation is completed, the callback function will be called with ESP_SPP_DISCOVERY_COMP_EVT.
This funciton must be called after esp_spp_init() successful and before esp_spp_deinit().
Return
• ESP_OK: success
• other: failed
Parameters
• [in] bd_addr: Remote device bluetooth device address.
esp_err_t esp_spp_connect(esp_spp_sec_t sec_mask, esp_spp_role_t role, uint8_t remote_scn,
esp_bd_addr_t peer_bd_addr)
This function makes an SPP connection to a remote BD Address. When the connection is initiated or failed to
initiate, the callback is called with ESP_SPP_CL_INIT_EVT. When the connection is established or failed,
the callback is called with ESP_SPP_OPEN_EVT. This funciton must be called after esp_spp_init() successful
and before esp_spp_deinit().
Return
• ESP_OK: success
• other: failed
Parameters
• [in] sec_mask: Security Setting Mask. Suggest to use ESP_SPP_SEC_NONE,
ESP_SPP_SEC_AUTHORIZE or ESP_SPP_SEC_AUTHENTICATE only.
• [in] role: Master or slave.
• [in] remote_scn: Remote device bluetooth device SCN.
• [in] peer_bd_addr: Remote device bluetooth device address.
esp_err_t esp_spp_disconnect(uint32_t handle)
This function closes an SPP connection. When the operation is completed, the callback function will be
called with ESP_SPP_CLOSE_EVT. This funciton must be called after esp_spp_init() successful and before
esp_spp_deinit().
Return
• ESP_OK: success
• other: failed
Parameters
• [in] handle: The connection handle.
esp_err_t esp_spp_start_srv(esp_spp_sec_t sec_mask, esp_spp_role_t role, uint8_t local_scn, const
char *name)
This function create a SPP server and starts listening for an SPP connection request from a remote Bluetooth
device. When the server is started successfully, the callback is called with ESP_SPP_START_EVT. When
the connection is established, the callback is called with ESP_SPP_SRV_OPEN_EVT. This funciton must be
called after esp_spp_init() successful and before esp_spp_deinit().
Return
• ESP_OK: success
• other: failed
Parameters

• [in] sec_mask: Security Setting Mask. Suggest to use ESP_SPP_SEC_NONE,

ESP_SPP_SEC_AUTHORIZE or ESP_SPP_SEC_AUTHENTICATE only.
• [in] role: Master or slave.
• [in] local_scn: The specific channel you want to get. If channel is 0, means get any channel.
• [in] name: Server s name.
esp_err_t esp_spp_stop_srv(void)
This function stops all SPP servers. The operation will close all active SPP connection first, then the call-
back function will be called with ESP_SPP_CLOSE_EVT, and the number of ESP_SPP_CLOSE_EVT
is equal to the number of connection. When the operation is completed, the callback is called with
ESP_SPP_SRV_STOP_EVT. This funciton must be called after esp_spp_init() successful and before
esp_spp_deinit().
Return
• ESP_OK: success
• other: failed
esp_err_t esp_spp_stop_srv_scn(uint8_t scn)
This function stops a specific SPP server. The operation will close all active SPP connection first on the
specific SPP server, then the callback function will be called with ESP_SPP_CLOSE_EVT, and the number of
ESP_SPP_CLOSE_EVT is equal to the number of connection. When the operation is completed, the callback
is called with ESP_SPP_SRV_STOP_EVT. This funciton must be called after esp_spp_init() successful and
before esp_spp_deinit().
Return
• ESP_OK: success
• other: failed
Parameters
• [in] scn: Server channel number.
esp_err_t esp_spp_write(uint32_t handle, int len, uint8_t *p_data)
This function is used to write data, only for ESP_SPP_MODE_CB. When this function need to
be called repeatedly, it is strongly recommended to call this function again after the previous event
ESP_SPP_WRITE_EVT is received and the parameter cong is equal to false. If the previous event
ESP_SPP_WRITE_EVT with parameter cong is equal to true, the function can only be called again when
the event ESP_SPP_CONG_EVT with parameter cong equal to false is received. This funciton must be
called after an connection between initiator and acceptor has been established.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] handle: The connection handle.
• [in] len: The length of the data written.
• [in] p_data: The data written.
esp_err_t esp_spp_vfs_register(void)
This function is used to register VFS. For now, SPP only supports write, read and close.
Return
• ESP_OK: success
• other: failed
Unions
union esp_spp_cb_param_t
#include <esp_spp_api.h> SPP callback parameters union.
Public Members
struct esp_spp_cb_param_t::spp_init_evt_param init

SPP callback param of SPP_INIT_EVT

struct esp_spp_cb_param_t::spp_uninit_evt_param uninit

SPP callback param of SPP_UNINIT_EVT
struct esp_spp_cb_param_t::spp_discovery_comp_evt_param disc_comp
SPP callback param of SPP_DISCOVERY_COMP_EVT
struct esp_spp_cb_param_t::spp_open_evt_param open
SPP callback param of ESP_SPP_OPEN_EVT
struct esp_spp_cb_param_t::spp_srv_open_evt_param srv_open
SPP callback param of ESP_SPP_SRV_OPEN_EVT
struct esp_spp_cb_param_t::spp_close_evt_param close
SPP callback param of ESP_SPP_CLOSE_EVT
struct esp_spp_cb_param_t::spp_start_evt_param start
SPP callback param of ESP_SPP_START_EVT
struct esp_spp_cb_param_t::spp_srv_stop_evt_param srv_stop
SPP callback param of ESP_SPP_SRV_STOP_EVT
struct esp_spp_cb_param_t::spp_cl_init_evt_param cl_init
SPP callback param of ESP_SPP_CL_INIT_EVT
struct esp_spp_cb_param_t::spp_write_evt_param write
SPP callback param of ESP_SPP_WRITE_EVT
struct esp_spp_cb_param_t::spp_data_ind_evt_param data_ind
SPP callback param of ESP_SPP_DATA_IND_EVT
struct esp_spp_cb_param_t::spp_cong_evt_param cong
SPP callback param of ESP_SPP_CONG_EVT
struct spp_cl_init_evt_param
#include <esp_spp_api.h> ESP_SPP_CL_INIT_EVT.
Public Members
esp_spp_status_t status
status
uint32_t handle
The connection handle
uint8_t sec_id
security ID used by this server
bool use_co
TRUE to use co_rfc_data
struct spp_close_evt_param
#include <esp_spp_api.h> ESP_SPP_CLOSE_EVT.
Public Members
status
uint32_t port_status
PORT status
uint32_t handle

bool async
FALSE, if local initiates disconnect
struct spp_cong_evt_param
#include <esp_spp_api.h> ESP_SPP_CONG_EVT.
Public Members
status
uint32_t handle
bool cong
TRUE, congested. FALSE, uncongested
struct spp_data_ind_evt_param
#include <esp_spp_api.h> ESP_SPP_DATA_IND_EVT.
Public Members
status
uint32_t handle
uint16_t len
The length of data
uint8_t *data
The data received
struct spp_discovery_comp_evt_param
#include <esp_spp_api.h> SPP_DISCOVERY_COMP_EVT.
Public Members
status
uint8_t scn_num
The num of scn_num
uint8_t scn[ESP_SPP_MAX_SCN]
channel #
const char *service_name[ESP_SPP_MAX_SCN]
service_name
struct spp_init_evt_param
#include <esp_spp_api.h> SPP_INIT_EVT.
Public Members
status
struct spp_open_evt_param
#include <esp_spp_api.h> ESP_SPP_OPEN_EVT.

Public Members
status
uint32_t handle
int fd
The file descriptor only for ESP_SPP_MODE_VFS
esp_bd_addr_t rem_bda
The peer address
struct spp_srv_open_evt_param
#include <esp_spp_api.h> ESP_SPP_SRV_OPEN_EVT.
Public Members
status
uint32_t handle
uint32_t new_listen_handle
The new listen handle
int fd
The file descriptor only for ESP_SPP_MODE_VFS
esp_bd_addr_t rem_bda
The peer address
struct spp_srv_stop_evt_param
#include <esp_spp_api.h> ESP_SPP_SRV_STOP_EVT.
Public Members
status
uint8_t scn
Server channel number
struct spp_start_evt_param
#include <esp_spp_api.h> ESP_SPP_START_EVT.
Public Members
status
uint32_t handle
uint8_t sec_id
security ID used by this server
uint8_t scn
Server channel number

bool use_co
TRUE to use co_rfc_data
struct spp_uninit_evt_param
#include <esp_spp_api.h> SPP_UNINIT_EVT.
Public Members
status
struct spp_write_evt_param
#include <esp_spp_api.h> ESP_SPP_WRITE_EVT.
Public Members
status
uint32_t handle
int len
The length of the data written.
bool cong
congestion status
Macros
ESP_SPP_SEC_NONE
No security. relate to BTA_SEC_NONE in bta/bta_api.h
ESP_SPP_SEC_AUTHORIZE
Authorization required (only needed for out going connection ) relate to BTA_SEC_AUTHORIZE in
bta/bta_api.h
ESP_SPP_SEC_AUTHENTICATE
Authentication required. relate to BTA_SEC_AUTHENTICATE in bta/bta_api.h
ESP_SPP_SEC_ENCRYPT
Encryption required. relate to BTA_SEC_ENCRYPT in bta/bta_api.h
ESP_SPP_SEC_MODE4_LEVEL4
Mode 4 level 4 service, i.e. incoming/outgoing MITM and P-256 encryption relate to
BTA_SEC_MODE4_LEVEL4 in bta/bta_api.h
ESP_SPP_SEC_MITM
Man-In-The_Middle protection relate to BTA_SEC_MITM in bta/bta_api.h
ESP_SPP_SEC_IN_16_DIGITS
Min 16 digit for pin code relate to BTA_SEC_IN_16_DIGITS in bta/bta_api.h
ESP_SPP_MAX_MTU
SPP max MTU
ESP_SPP_MAX_SCN
SPP max SCN

Type Definitions
typedef uint16_t esp_spp_sec_t
typedef void (esp_spp_cb_t)(esp_spp_cb_event_t event, esp_spp_cb_param_t *param)
SPP callback function type. When handle ESP_SPP_DATA_IND_EVT, it is strongly recommended to cache
incoming data, and process them in other lower priority application task rather than in this callback directly.
Parameters
• event: Event type
• param: Point to callback parameter, currently is union type
Enumerations
enum esp_spp_status_t
Values:
ESP_SPP_SUCCESS = 0
Successful operation.
ESP_SPP_FAILURE
Generic failure.
ESP_SPP_BUSY
Temporarily can not handle this request.
ESP_SPP_NO_DATA
No data
ESP_SPP_NO_RESOURCE
No more resource
ESP_SPP_NEED_INIT
SPP module shall init first
ESP_SPP_NEED_DEINIT
SPP module shall deinit first
ESP_SPP_NO_CONNECTION
Connection may have been closed
ESP_SPP_NO_SERVER
No SPP server
enum esp_spp_role_t
Values:
ESP_SPP_ROLE_MASTER = 0
Role: master
ESP_SPP_ROLE_SLAVE = 1
Role: slave
enum esp_spp_mode_t
Values:
ESP_SPP_MODE_CB = 0
When data is coming, a callback will come with data
ESP_SPP_MODE_VFS = 1
Use VFS to write/read data
enum esp_spp_cb_event_t
SPP callback function events.
Values:
ESP_SPP_INIT_EVT = 0
When SPP is inited, the event comes

ESP_SPP_UNINIT_EVT = 1
When SPP is uninited, the event comes
ESP_SPP_DISCOVERY_COMP_EVT = 8
When SDP discovery complete, the event comes
ESP_SPP_OPEN_EVT = 26
When SPP Client connection open, the event comes
ESP_SPP_CLOSE_EVT = 27
When SPP connection closed, the event comes
ESP_SPP_START_EVT = 28
When SPP server started, the event comes
ESP_SPP_CL_INIT_EVT = 29
When SPP client initiated a connection, the event comes
ESP_SPP_DATA_IND_EVT = 30
When SPP connection received data, the event comes, only for ESP_SPP_MODE_CB
ESP_SPP_CONG_EVT = 31
When SPP connection congestion status changed, the event comes, only for ESP_SPP_MODE_CB
ESP_SPP_WRITE_EVT = 33
When SPP write operation completes, the event comes, only for ESP_SPP_MODE_CB
ESP_SPP_SRV_OPEN_EVT = 34
When SPP Server connection open, the event comes
ESP_SPP_SRV_STOP_EVT = 35
When SPP server stopped, the event comes
HFP DEFINES
API Reference
Header File
• components/bt/host/bluedroid/api/include/api/esp_hf_defs.h
Macros
ESP_BT_HF_NUMBER_LEN
ESP_BT_HF_OPERATOR_NAME_LEN
BTC_HSAG_SERVICE_NAME
BTC_HFAG_SERVICE_NAME
BTC_HF_SERVICES
BTC_HF_SERVICE_NAMES
BTC_HF_SECURITY
BTC_HF_CALL_END_TIMEOUT
BTC_HF_INVALID_IDX

Type Definitions
typedef void (*esp_hf_connection_state_callback)(esp_hf_connection_state_t state,
esp_bd_addr_t *bd_addr)
Callback for connection state change. state will have one of the values from BtHfConnectionState
typedef void (*esp_hf_audio_state_callback)(esp_hf_audio_state_t state, esp_bd_addr_t
*bd_addr)
Callback for audio connection state change. state will have one of the values from BtHfAudioState
typedef void (*esp_hf_vr_cmd_callback)(esp_hf_vr_state_t state, esp_bd_addr_t *bd_addr)
Callback for VR connection state change. state will have one of the values from BtHfVRState
typedef void (*esp_hf_answer_call_cmd_callback)(esp_bd_addr_t *bd_addr)
Callback for answer incoming call (ATA)
typedef void (*esp_hf_hangup_call_cmd_callback)(esp_bd_addr_t *bd_addr)
Callback for disconnect call (AT+CHUP)
typedef void (*esp_hf_volume_cmd_callback)(esp_hf_volume_control_target_t type, int vol-
ume, esp_bd_addr_t *bd_addr)
Callback for disconnect call (AT+CHUP) type will denote Speaker/Mic gain (BtHfVolumeControl).
typedef void (*esp_hf_dial_call_cmd_callback)(char *number, esp_bd_addr_t *bd_addr)
Callback for dialing an outgoing call If number is NULL, redial
typedef void (*esp_hf_dtmf_cmd_callback)(char tone, esp_bd_addr_t *bd_addr)
Callback for sending DTMF tones tone contains the dtmf character to be sent
typedef void (*esp_hf_nrec_cmd_callback)(esp_hf_nrec_t nrec, esp_bd_addr_t *bd_addr)
Callback for enabling/disabling noise reduction/echo cancellation value will be 1 to enable, 0 to disable
typedef void (*esp_hf_wbs_callback)(esp_hf_wbs_config_t wbs, esp_bd_addr_t *bd_addr)
Callback for AT+BCS and event from BAC WBS enable, WBS disable
typedef void (*esp_hf_chld_cmd_callback)(esp_hf_chld_type_t chld, esp_bd_addr_t
*bd_addr)
Callback for call hold handling (AT+CHLD) value will contain the call hold command (0, 1, 2, 3)
typedef void (*esp_hf_cnum_cmd_callback)(esp_bd_addr_t *bd_addr)
Callback for CNUM (subscriber number)
typedef void (*esp_hf_cind_cmd_callback)(esp_bd_addr_t *bd_addr)
Callback for indicators (CIND)
typedef void (*esp_hf_cops_cmd_callback)(esp_bd_addr_t *bd_addr)
Callback for operator selection (COPS)
typedef void (*esp_hf_clcc_cmd_callback)(esp_bd_addr_t *bd_addr)
Callback for call list (AT+CLCC)
typedef void (*esp_hf_unknown_at_cmd_callback)(char *at_string, esp_bd_addr_t
*bd_addr)
Callback for unknown AT command recd from AG at_string will contain the unparsed AT string
typedef void (*esp_hf_key_pressed_cmd_callback)(esp_bd_addr_t *bd_addr)
Callback for keypressed (HSP) event.
Enumerations
enum esp_hf_in_band_ring_state_t
in-band ring tone state
Values:
ESP_HF_IN_BAND_RINGTONE_NOT_PROVIDED = 0
ESP_HF_IN_BAND_RINGTONE_PROVIDED

enum esp_hf_vr_state_t
voice recognition state
Values:
ESP_HF_VR_STATE_DISABLED = 0
voice recognition disabled
ESP_HF_VR_STATE_ENABLED
voice recognition enabled
enum esp_hf_volume_control_target_t
Bluetooth HFP audio volume control target.
Values:
ESP_HF_VOLUME_CONTROL_TARGET_SPK = 0
speaker
ESP_HF_VOLUME_CONTROL_TARGET_MIC
microphone
enum esp_hf_audio_state_t
Bluetooth HFP audio connection status.
Values:
ESP_HF_AUDIO_STATE_DISCONNECTED = 0
audio connection released
ESP_HF_AUDIO_STATE_CONNECTING
audio connection has been initiated
ESP_HF_AUDIO_STATE_CONNECTED
audio connection is established
ESP_HF_AUDIO_STATE_CONNECTED_MSBC
mSBC audio connection is established
enum esp_hf_volume_type_t
Values:
ESP_HF_VOLUME_TYPE_SPK = 0
ESP_HF_VOLUME_TYPE_MIC
enum esp_hf_network_state_t
+CIND network service availability status
Values:
ESP_HF_NETWORK_STATE_NOT_AVAILABLE = 0
ESP_HF_NETWORK_STATE_AVAILABLE
enum esp_hf_service_type_t
+CIEV Service type
Values:
ESP_HF_SERVICE_TYPE_HOME = 0
ESP_HF_SERVICE_TYPE_ROAMING
enum esp_hf_call_status_t
+CIND call status indicator values
Values:
ESP_HF_CALL_STATUS_NO_CALLS = 0
no call in progress

ESP_HF_CALL_STATUS_CALL_IN_PROGRESS = 1
call is present(active or held)
enum esp_hf_call_setup_status_t
+CIND call setup status indicator values
Values:
ESP_HF_CALL_SETUP_STATUS_IDLE = 0
no call setup in progress
ESP_HF_CALL_SETUP_STATUS_INCOMING = 1
incoming call setup in progress
ESP_HF_CALL_SETUP_STATUS_OUTGOING_DIALING = 2
outgoing call setup in dialing state
ESP_HF_CALL_SETUP_STATUS_OUTGOING_ALERTING = 3
outgoing call setup in alerting state
enum esp_hf_roaming_status_t
+CIND roaming status indicator values
Values:
ESP_HF_ROAMING_STATUS_INACTIVE = 0
roaming is not active
ESP_HF_ROAMING_STATUS_ACTIVE
a roaming is active
enum esp_hf_call_held_status_t
+CIND call held indicator values
Values:
ESP_HF_CALL_HELD_STATUS_NONE = 0
no calls held
ESP_HF_CALL_HELD_STATUS_HELD_AND_ACTIVE = 1
both active and held call
ESP_HF_CALL_HELD_STATUS_HELD = 2
call on hold, no active call
enum esp_hf_current_call_status_t
+CLCC status of the call
Values:
ESP_HF_CURRENT_CALL_STATUS_ACTIVE = 0
active
ESP_HF_CURRENT_CALL_STATUS_HELD = 1
held
ESP_HF_CURRENT_CALL_STATUS_DIALING = 2
dialing (outgoing calls only)
ESP_HF_CURRENT_CALL_STATUS_ALERTING = 3
alerting (outgoing calls only)
ESP_HF_CURRENT_CALL_STATUS_INCOMING = 4
incoming (incoming calls only)
ESP_HF_CURRENT_CALL_STATUS_WAITING = 5
waiting (incoming calls only)
ESP_HF_CURRENT_CALL_STATUS_HELD_BY_RESP_HOLD = 6
call held by response and hold

enum esp_hf_current_call_direction_t
+CLCC direction of the call
Values:
ESP_HF_CURRENT_CALL_DIRECTION_OUTGOING = 0
outgoing
ESP_HF_CURRENT_CALL_DIRECTION_INCOMING = 1
incoming
enum esp_hf_current_call_mpty_type_t
+CLCC multi-party call flag
Values:
ESP_HF_CURRENT_CALL_MPTY_TYPE_SINGLE = 0
not a member of a multi-party call
ESP_HF_CURRENT_CALL_MPTY_TYPE_MULTI = 1
member of a multi-party call
enum esp_hf_current_call_mode_t
+CLCC call mode
Values:
ESP_HF_CURRENT_CALL_MODE_VOICE = 0
ESP_HF_CURRENT_CALL_MODE_DATA = 1
ESP_HF_CURRENT_CALL_MODE_FAX = 2
enum esp_hf_call_addr_type_t
+CLCC address type
Values:
ESP_HF_CALL_ADDR_TYPE_UNKNOWN = 0x81
unkown address type
ESP_HF_CALL_ADDR_TYPE_INTERNATIONAL = 0x91
international address
enum esp_hf_subscriber_service_type_t
+CNUM service type of the phone number
Values:
ESP_HF_SUBSCRIBER_SERVICE_TYPE_UNKNOWN = 0
unknown
ESP_HF_SUBSCRIBER_SERVICE_TYPE_VOICE
voice service
ESP_HF_SUBSCRIBER_SERVICE_TYPE_FAX
fax service
enum esp_hf_btrh_status_t
+BTRH response and hold result code
Values:
ESP_HF_BTRH_STATUS_HELD = 0
incoming call is put on held in AG
ESP_HF_BTRH_STATUS_ACCEPTED
held incoming call is accepted in AG
ESP_HF_BTRH_STATUS_REJECTED
held incoming call is rejected in AG

enum esp_hf_btrh_cmd_t
AT+BTRH response and hold action code.
Values:
ESP_HF_BTRH_CMD_HOLD = 0
put the incoming call on hold
ESP_HF_BTRH_CMD_ACCEPT = 1
accept a held incoming call
ESP_HF_BTRH_CMD_REJECT = 2
reject a held incoming call
enum esp_hf_nrec_t
Values:
ESP_HF_NREC_STOP = 0
ESP_HF_NREC_START
enum esp_hf_call_waiting_status_t
+CCWA resposne status
Values:
ESP_HF_CALL_WAITING_INACTIVE
ESP_HF_CALL_WAITING_ACTIVE
enum esp_hf_wbs_config_t
Values:
ESP_HF_WBS_NONE
ESP_HF_WBS_NO
ESP_HF_WBS_YES
enum esp_hf_connection_state_t
Bluetooth HFP RFCOMM connection and service level connection status.
Values:
ESP_HF_CONNECTION_STATE_DISCONNECTED = 0
RFCOMM data link channel released
ESP_HF_CONNECTION_STATE_CONNECTING
connecting remote device on the RFCOMM data link
ESP_HF_CONNECTION_STATE_CONNECTED
RFCOMM connection established
ESP_HF_CONNECTION_STATE_SLC_CONNECTED
service level connection established
ESP_HF_CONNECTION_STATE_DISCONNECTING
disconnecting with remote device on the RFCOMM data link
enum esp_hf_chld_type_t
AT+CHLD command values.
Values:
ESP_HF_CHLD_TYPE_REL = 0
<0>, Terminate all held or set UDUB( busy ) to a waiting call
ESP_HF_CHLD_TYPE_REL_ACC
<1>, Terminate all active calls and accepts a waiting/held call
ESP_HF_CHLD_TYPE_HOLD_ACC
<2>, Hold all active calls and accepts a waiting/held call

ESP_HF_CHLD_TYPE_MERGE
<3>, Add all held calls to a conference
ESP_HF_CHLD_TYPE_MERGE_DETACH
<4>, connect the two calls and disconnects the subscriber from both calls
ESP_HF_CHLD_TYPE_REL_X
<1x>, releases specified calls only
ESP_HF_CHLD_TYPE_PRIV_X
<2x>, request private consultation mode with specified call
enum esp_hf_at_response_code_t
Values:
ESP_HF_AT_RESPONSE_CODE_OK = 0
acknowledges execution of a command line
ESP_HF_AT_RESPONSE_CODE_ERR
command not accepted
ESP_HF_AT_RESPONSE_CODE_NO_CARRIER
connection terminated
ESP_HF_AT_RESPONSE_CODE_BUSY
busy signal detected
ESP_HF_AT_RESPONSE_CODE_NO_ANSWER
connection completion timeout
ESP_HF_AT_RESPONSE_CODE_DELAYED
delayed
ESP_HF_AT_RESPONSE_CODE_BLACKLISTED
blacklisted
ESP_HF_AT_RESPONSE_CODE_CME
CME error
enum esp_hf_at_response_t
Values:
ESP_HF_AT_RESPONSE_ERROR = 0
ESP_HF_AT_RESPONSE_OK
enum esp_hf_cme_err_t
Extended Audio Gateway Error Result Code Response.
Values:
ESP_HF_CME_AG_FAILURE = 0
ag failure
ESP_HF_CME_NO_CONNECTION_TO_PHONE = 1
no connection to phone
ESP_HF_CME_OPERATION_NOT_ALLOWED = 3
operation not allowed
ESP_HF_CME_OPERATION_NOT_SUPPORTED = 4
operation not supported
ESP_HF_CME_PH_SIM_PIN_REQUIRED = 5
PH-SIM PIN Required
ESP_HF_CME_SIM_NOT_INSERTED = 10
SIM not inserted

ESP_HF_CME_SIM_PIN_REQUIRED = 11
SIM PIN required
ESP_HF_CME_SIM_PUK_REQUIRED = 12
SIM PUK required
ESP_HF_CME_SIM_FAILURE = 13
SIM failure
ESP_HF_CME_SIM_BUSY = 14
SIM busy
ESP_HF_CME_INCORRECT_PASSWORD = 16
incorrect password
ESP_HF_CME_SIM_PIN2_REQUIRED = 17
SIM PIN2 required
ESP_HF_CME_SIM_PUK2_REQUIRED = 18
SIM PUK2 required
ESP_HF_CME_MEMEORY_FULL = 20
memory full
ESP_HF_CME_INVALID_INDEX = 21
invalid index
ESP_HF_CME_MEMEORY_FAILURE = 23
memory failure
ESP_HF_CME_TEXT_STRING_TOO_LONG = 24
test string too long
ESP_HF_CME_INVALID_CHARACTERS_IN_TEXT_STRING = 25
invalid characters in text string
ESP_HF_CME_DIAL_STRING_TOO_LONG = 26
dial string too long
ESP_HF_CME_INVALID_CHARACTERS_IN_DIAL_STRING = 27
invalid characters in dial string
ESP_HF_CME_NO_NETWORK_SERVICE = 30
no network service
ESP_HF_CME_NETWORK_TIMEOUT = 31
network timeout
ESP_HF_CME_NETWORK_NOT_ALLOWED = 32
network not allowed emergency calls only
HFP CLIENT API
API Reference
Header File
• components/bt/host/bluedroid/api/include/api/esp_hf_client_api.h

Functions
esp_err_t esp_hf_client_register_callback(esp_hf_client_cb_t callback)
Register application callback function to HFP client module. This function should be called only after
Return
• ESP_OK: success
Parameters
• [in] callback: HFP client event callback function
esp_err_t esp_hf_client_init(void)
Initialize the bluetooth HFP client module. This function should be called after esp_bluedroid_enable() com-
pletes successfully.
Return
esp_err_t esp_hf_client_deinit(void)
De-initialize for HFP client module. This function should be called only after esp_bluedroid_enable() com-
pletes successfully.
Return
• ESP_OK: success
esp_err_t esp_hf_client_connect(esp_bd_addr_t remote_bda)
Establish a Service Level Connection to remote bluetooth HFP audio gateway(AG) device. This function must
be called after esp_hf_client_init() and before esp_hf_client_deinit().
Return
• ESP_OK: connect request is sent to lower layer
Parameters
esp_err_t esp_hf_client_disconnect(esp_bd_addr_t remote_bda)
Disconnect from the remote HFP audio gateway. This function must be called after esp_hf_client_init() and
before esp_hf_client_deinit().
Return
Parameters
esp_err_t esp_hf_client_connect_audio(esp_bd_addr_t remote_bda)
Create audio connection with remote HFP AG. As a precondition to use this API, Service Level Connection
shall exist with AG.
Return
Parameters
esp_err_t esp_hf_client_disconnect_audio(esp_bd_addr_t remote_bda)
Release the established audio connection with remote HFP AG. As a precondition to use this API, Service

Level Connection shall exist with AG.

Return
Parameters
esp_err_t esp_hf_client_start_voice_recognition(void)
Enable voice recognition in the AG. As a precondition to use this API, Service Level Connection shall exist
with AG.
Return
esp_err_t esp_hf_client_stop_voice_recognition(void)
Disable voice recognition in the AG. As a precondition to use this API, Service Level Connection shall exist
with AG.
Return
esp_err_t esp_hf_client_volume_update(esp_hf_volume_control_target_t type, int volume)
Volume synchronization with AG. As a precondition to use this API, Service Level Connection shall exist with
AG.
Return
Parameters
• [in] type: volume control target, speaker or microphone
• [in] volume: gain of the speaker of microphone, ranges 0 to 15
esp_err_t esp_hf_client_dial(const char *number)
Place a call with a specified number, if number is NULL, last called number is called. As a precondition to
use this API, Service Level Connection shall exist with AG.
Return
Parameters
• [in] number: number string of the call. If NULL, the last number is called(aka re-dial)
esp_err_t esp_hf_client_dial_memory(int location)
Place a call with number specified by location(speed dial). As a precondition to use this API, Service Level
Connection shall exist with AG.
Return
Parameters
• [in] location: location of the number in the memory
esp_err_t esp_hf_client_send_chld_cmd(esp_hf_chld_type_t chld, int idx)
Send call hold and multiparty commands, or enhanced call control commands(Use AT+CHLD). As a precon-
dition to use this API, Service Level Connection shall exist with AG.

Return
Parameters
• [in] chld: AT+CHLD call hold and multiparty handling AT command.
• [in] idx: used in Enhanced Call Control Mechanisms, used if chld is
ESP_HF_CHLD_TYPE_REL_X or ESP_HF_CHLD_TYPE_PRIV_X
esp_err_t esp_hf_client_send_btrh_cmd(esp_hf_btrh_cmd_t btrh)
Send response and hold action command(Send AT+BTRH command) As a precondition to use this API, Ser-
vice Level Connection shall exist with AG.
Return
Parameters
• [in] btrh: response and hold action to send
esp_err_t esp_hf_client_answer_call(void)
Answer an incoming call(send ATA command). As a precondition to use this API, Service Level Connection
shall exist with AG.
Return
esp_err_t esp_hf_client_reject_call(void)
Reject an incoming call(send AT+CHUP command). As a precondition to use this API, Service Level Con-
nection shall exist with AG.
Return
esp_err_t esp_hf_client_query_current_calls(void)
Query list of current calls in AG(send AT+CLCC command). As a precondition to use this API, Service Level
Connection shall exist with AG.
Return
esp_err_t esp_hf_client_query_current_operator_name(void)
Query the name of currently selected network operator in AG(use AT+COPS commands). As a precondition
to use this API, Service Level Connection shall exist with AG.
Return
esp_err_t esp_hf_client_retrieve_subscriber_info(void)
Get subscriber information number from AG(send AT+CNUM command) As a precondition to use this API,
Service Level Connection shall exist with AG.
Return

esp_err_t esp_hf_client_send_dtmf(char code)

Transmit DTMF codes during an ongoing call(use AT+VTS commands) As a precondition to use this API,
Service Level Connection shall exist with AG.
Return
Parameters
• [in] code: dtmf code, single ascii character in the set 0-9, #, *, A-D
esp_err_t esp_hf_client_request_last_voice_tag_number(void)
Request a phone number from AG corresponding to last voice tag recorded (send AT+BINP command). As a
precondition to use this API, Service Level Connection shall exist with AG.
Return
esp_err_t esp_hf_client_send_nrec(void)
Disable echo cancellation and noise reduction in the AG (use AT+NREC=0 command). As a precondition to
use this API, Service Level Connection shall exist with AG.
Return
• ESP_OK: NREC=0 request is sent to lower layer
esp_err_t esp_hf_client_register_data_callback(esp_hf_client_incoming_data_cb_t recv,
esp_hf_client_outgoing_data_cb_t send)
Register HFP client data output function; the callback is only used in the case that Voice Over HCI is enabled.
Return
• ESP_OK: success
Parameters
• [in] recv: HFP client incoming data callback function
• [in] send: HFP client outgoing data callback function
void esp_hf_client_outgoing_data_ready(void)
Trigger the lower-layer to fetch and send audio data. This function is only only used in the case that Voice
Over HCI is enabled. After this function is called, lower layer will invoke esp_hf_client_outgoing_data_cb_t
to fetch data.
As a precondition to use this API, Service Level Connection shall exist with AG.
void esp_hf_client_pcm_resample_init(uint32_t src_sps, uint32_t bits, uint32_t channels)
Initialize the down sampling converter. This is a utility function that can only be used in the case that Voice
Over HCI is enabled.
Parameters
• [in] src_sps: original samples per second(source audio data, i.e. 48000, 32000, 16000, 44100,
22050, 11025)
• [in] bits: number of bits per pcm sample (16)
• [in] channels: number of channels (i.e. mono(1), stereo(2) )
void esp_hf_client_pcm_resample_deinit(void)
Deinitialize the down sampling converter.
int32_t esp_hf_client_pcm_resample(void *src, uint32_t in_bytes, void *dst)
Down sampling utility to convert high sampling rate into 8K/16bits 1-channel mode PCM samples. This can
only be used in the case that Voice Over HCI is enabled.

Return number of samples converted

Parameters
• [in] src: pointer to the buffer where the original sampling PCM are stored
• [in] in_bytes: length of the input PCM sample buffer in byte
• [in] dst: pointer to the buffer which is to be used to store the converted PCM samples
Unions
union esp_hf_client_cb_param_t
#include <esp_hf_client_api.h> HFP client callback parameters.
Public Members
struct esp_hf_client_cb_param_t::hf_client_conn_stat_param conn_stat

HF callback param of ESP_HF_CLIENT_CONNECTION_STATE_EVT
struct esp_hf_client_cb_param_t::hf_client_audio_stat_param audio_stat
HF callback param of ESP_HF_CLIENT_AUDIO_STATE_EVT
struct esp_hf_client_cb_param_t::hf_client_bvra_param bvra
HF callback param of ESP_HF_CLIENT_BVRA_EVT
struct esp_hf_client_cb_param_t::hf_client_service_availability_param service_availability
HF callback param of ESP_HF_CLIENT_CIND_SERVICE_AVAILABILITY_EVT
struct esp_hf_client_cb_param_t::hf_client_network_roaming_param roaming
HF callback param of ESP_HF_CLIENT_CIND_ROAMING_STATUS_EVT
struct esp_hf_client_cb_param_t::hf_client_signal_strength_ind_param signal_strength
HF callback param of ESP_HF_CLIENT_CIND_SIGNAL_STRENGTH_EVT
struct esp_hf_client_cb_param_t::hf_client_battery_level_ind_param battery_level
HF callback param of ESP_HF_CLIENT_CIND_BATTERY_LEVEL_EVT
struct esp_hf_client_cb_param_t::hf_client_current_operator_param cops
HF callback param of ESP_HF_CLIENT_COPS_CURRENT_OPERATOR_EVT
struct esp_hf_client_cb_param_t::hf_client_call_ind_param call
HF callback param of ESP_HF_CLIENT_CIND_CALL_EVT
struct esp_hf_client_cb_param_t::hf_client_call_setup_ind_param call_setup
struct esp_hf_client_cb_param_t::hf_client_call_held_ind_param call_held
HF callback param of ESP_HF_CLIENT_CIND_CALL_HELD_EVT
struct esp_hf_client_cb_param_t::hf_client_btrh_param btrh
HF callback param of ESP_HF_CLIENT_BRTH_EVT
struct esp_hf_client_cb_param_t::hf_client_clip_param clip
HF callback param of ESP_HF_CLIENT_CLIP_EVT
struct esp_hf_client_cb_param_t::hf_client_ccwa_param ccwa
struct esp_hf_client_cb_param_t::hf_client_clcc_param clcc
HF callback param of ESP_HF_CLIENT_CLCC_EVT
struct esp_hf_client_cb_param_t::hf_client_volume_control_param volume_control
HF callback param of ESP_HF_CLIENT_VOLUME_CONTROL_EVT
struct esp_hf_client_cb_param_t::hf_client_at_response_param at_response
HF callback param of ESP_HF_CLIENT_AT_RESPONSE_EVT
struct esp_hf_client_cb_param_t::hf_client_cnum_param cnum
HF callback param of ESP_HF_CLIENT_CNUM_EVT

struct esp_hf_client_cb_param_t::hf_client_bsirparam bsir

HF callback param of ESP_HF_CLIENT_BSIR_EVT
struct esp_hf_client_cb_param_t::hf_client_binp_param binp
HF callback param of ESP_HF_CLIENT_BINP_EVT
struct hf_client_at_response_param
#include <esp_hf_client_api.h> ESP_HF_CLIENT_AT_RESPONSE_EVT.
Public Members
esp_hf_at_response_code_t code
AT response code
esp_hf_cme_err_t cme
Extended Audio Gateway Error Result Code
struct hf_client_audio_stat_param
#include <esp_hf_client_api.h> ESP_HF_CLIENT_AUDIO_STATE_EVT.
Public Members
esp_hf_client_audio_state_t state
audio connection state
struct hf_client_battery_level_ind_param
#include <esp_hf_client_api.h> ESP_HF_CLIENT_CIND_BATTERY_LEVEL_EVT.
Public Members
int value
battery charge value, ranges from 0 to 5
struct hf_client_binp_param
#include <esp_hf_client_api.h> ESP_HF_CLIENT_BINP_EVT.
Public Members
const char *number

phone number corresponding to the last voice tag in the HF
struct hf_client_bsirparam
#include <esp_hf_client_api.h> ESP_HF_CLIENT_BSIR_EVT.
Public Members
esp_hf_client_in_band_ring_state_t state
setting state of in-band ring tone
struct hf_client_btrh_param
#include <esp_hf_client_api.h> ESP_HF_CLIENT_BTRH_EVT.

Public Members
esp_hf_btrh_status_t status
call hold and response status result code
struct hf_client_bvra_param
#include <esp_hf_client_api.h> ESP_HF_CLIENT_BVRA_EVT.
Public Members
esp_hf_vr_state_t value
voice recognition state
struct hf_client_call_held_ind_param
#include <esp_hf_client_api.h> ESP_HF_CLIENT_CIND_CALL_HELD_EVT.
Public Members
esp_hf_call_held_status_t status
bluetooth proprietary call hold status indicator
struct hf_client_call_ind_param
#include <esp_hf_client_api.h> ESP_HF_CLIENT_CIND_CALL_EVT.
Public Members
esp_hf_call_status_t status
call status indicator
struct hf_client_call_setup_ind_param
#include <esp_hf_client_api.h> ESP_HF_CLIENT_CIND_CALL_SETUP_EVT.
Public Members
esp_hf_call_setup_status_t status
call setup status indicator
struct hf_client_ccwa_param
#include <esp_hf_client_api.h> ESP_HF_CLIENT_CCWA_EVT.
Public Members
const char *number

phone number string of waiting call
struct hf_client_clcc_param
#include <esp_hf_client_api.h> ESP_HF_CLIENT_CLCC_EVT.
Public Members
int idx
numbering(starting with 1) of the call
esp_hf_current_call_direction_t dir
direction of the call

esp_hf_current_call_status_t status
status of the call
esp_hf_current_call_mpty_type_t mpty
multi-party flag
char *number
phone number(optional)
struct hf_client_clip_param
#include <esp_hf_client_api.h> ESP_HF_CLIENT_CLIP_EVT.
Public Members
const char *number

phone number string of call
struct hf_client_cnum_param
#include <esp_hf_client_api.h> ESP_HF_CLIENT_CNUM_EVT.
Public Members
const char *number

phone number string
esp_hf_subscriber_service_type_t type
service type that the phone number relates to
struct hf_client_conn_stat_param
#include <esp_hf_client_api.h> ESP_HF_CLIENT_CONNECTION_STATE_EVT.
Public Members
esp_hf_client_connection_state_t state
HF connection state
uint32_t peer_feat
AG supported features
uint32_t chld_feat
AG supported features on call hold and multiparty services
struct hf_client_current_operator_param
#include <esp_hf_client_api.h> ESP_HF_CLIENT_COPS_CURRENT_OPERATOR_EVT.
Public Members
const char *name

name of the network operator
struct hf_client_network_roaming_param
#include <esp_hf_client_api.h> ESP_HF_CLIENT_CIND_ROAMING_STATUS_EVT.

Public Members
esp_hf_roaming_status_t status
roaming status
struct hf_client_service_availability_param
#include <esp_hf_client_api.h> ESP_HF_CLIENT_CIND_SERVICE_AVAILABILITY_EVT.
Public Members
esp_hf_network_state_t status
service availability status
struct hf_client_signal_strength_ind_param
#include <esp_hf_client_api.h> ESP_HF_CLIENT_CIND_SIGNAL_STRENGTH_EVT.
Public Members
int value
signal strength value, ranges from 0 to 5
struct hf_client_volume_control_param
#include <esp_hf_client_api.h> ESP_HF_CLIENT_VOLUME_CONTROL_EVT.
Public Members
esp_hf_volume_control_target_t type
volume control target, speaker or microphone
int volume
gain, ranges from 0 to 15
Macros
ESP_BT_HF_CLIENT_NUMBER_LEN
ESP_BT_HF_CLIENT_OPERATOR_NAME_LEN
ESP_HF_CLIENT_PEER_FEAT_3WAY
ESP_HF_CLIENT_PEER_FEAT_ECNR
ESP_HF_CLIENT_PEER_FEAT_VREC
ESP_HF_CLIENT_PEER_FEAT_INBAND
ESP_HF_CLIENT_PEER_FEAT_VTAG
ESP_HF_CLIENT_PEER_FEAT_REJECT
ESP_HF_CLIENT_PEER_FEAT_ECS
ESP_HF_CLIENT_PEER_FEAT_ECC
ESP_HF_CLIENT_PEER_FEAT_EXTERR
ESP_HF_CLIENT_PEER_FEAT_CODEC
ESP_HF_CLIENT_CHLD_FEAT_REL
ESP_HF_CLIENT_CHLD_FEAT_REL_ACC
ESP_HF_CLIENT_CHLD_FEAT_REL_X
ESP_HF_CLIENT_CHLD_FEAT_HOLD_ACC

ESP_HF_CLIENT_CHLD_FEAT_PRIV_X
ESP_HF_CLIENT_CHLD_FEAT_MERGE
ESP_HF_CLIENT_CHLD_FEAT_MERGE_DETACH
Type Definitions
typedef void (*esp_hf_client_incoming_data_cb_t)(const uint8_t *buf, uint32_t len)
HFP client incoming data callback function, the callback is useful in case of Voice Over HCI.
Parameters
• [in] buf: : pointer to incoming data(payload of HCI synchronous data packet), the buffer is
allocated inside bluetooth protocol stack and will be released after invoke of the callback is finished.
typedef uint32_t (*esp_hf_client_outgoing_data_cb_t)(uint8_t *buf, uint32_t len)
HFP client outgoing data callback function, the callback is useful in case of Voice Over HCI. Once audio
connection is set up and the application layer has prepared data to send, the lower layer will call this function
to read data and then send. This callback is supposed to be implemented as non-blocking, and if data is not
enough, return value 0 is supposed.
Return length of data successfully read
Parameters
typedef void (*esp_hf_client_cb_t)(esp_hf_client_cb_event_t event, esp_hf_client_cb_param_t
*param)
HFP client callback function type.
Parameters
Enumerations
enum esp_hf_client_connection_state_t
Bluetooth HFP RFCOMM connection and service level connection status.
Values:
ESP_HF_CLIENT_CONNECTION_STATE_DISCONNECTED = 0
RFCOMM data link channel released
ESP_HF_CLIENT_CONNECTION_STATE_CONNECTING
connecting remote device on the RFCOMM data link
ESP_HF_CLIENT_CONNECTION_STATE_CONNECTED
RFCOMM connection established
ESP_HF_CLIENT_CONNECTION_STATE_SLC_CONNECTED
service level connection established
ESP_HF_CLIENT_CONNECTION_STATE_DISCONNECTING
disconnecting with remote device on the RFCOMM dat link
enum esp_hf_client_audio_state_t
Bluetooth HFP audio connection status.
Values:
ESP_HF_CLIENT_AUDIO_STATE_DISCONNECTED = 0
audio connection released
ESP_HF_CLIENT_AUDIO_STATE_CONNECTING
audio connection has been initiated

ESP_HF_CLIENT_AUDIO_STATE_CONNECTED
audio connection is established
ESP_HF_CLIENT_AUDIO_STATE_CONNECTED_MSBC
mSBC audio connection is established
enum esp_hf_client_in_band_ring_state_t
in-band ring tone state
Values:
ESP_HF_CLIENT_IN_BAND_RINGTONE_NOT_PROVIDED = 0
ESP_HF_CLIENT_IN_BAND_RINGTONE_PROVIDED
enum esp_hf_client_cb_event_t
HF CLIENT callback events.
Values:
ESP_HF_CLIENT_CONNECTION_STATE_EVT = 0
ESP_HF_CLIENT_AUDIO_STATE_EVT
audio connection state change event
ESP_HF_CLIENT_BVRA_EVT
voice recognition state change event
ESP_HF_CLIENT_CIND_CALL_EVT
call indication
ESP_HF_CLIENT_CIND_CALL_SETUP_EVT
call setup indication
ESP_HF_CLIENT_CIND_CALL_HELD_EVT
call held indication
ESP_HF_CLIENT_CIND_SERVICE_AVAILABILITY_EVT
network service availability indication
ESP_HF_CLIENT_CIND_SIGNAL_STRENGTH_EVT
signal strength indication
ESP_HF_CLIENT_CIND_ROAMING_STATUS_EVT
roaming status indication
ESP_HF_CLIENT_CIND_BATTERY_LEVEL_EVT
battery level indication
ESP_HF_CLIENT_COPS_CURRENT_OPERATOR_EVT
current operator information
ESP_HF_CLIENT_BTRH_EVT
call response and hold event
ESP_HF_CLIENT_CLIP_EVT
Calling Line Identification notification
ESP_HF_CLIENT_CCWA_EVT
call waiting notification
ESP_HF_CLIENT_CLCC_EVT
list of current calls notification
ESP_HF_CLIENT_VOLUME_CONTROL_EVT
audio volume control command from AG, provided by +VGM or +VGS message
ESP_HF_CLIENT_AT_RESPONSE_EVT
AT command response event

ESP_HF_CLIENT_CNUM_EVT
subscriber information response from AG
ESP_HF_CLIENT_BSIR_EVT
setting of in-band ring tone
ESP_HF_CLIENT_BINP_EVT
requested number of last voice tag from AG
ESP_HF_CLIENT_RING_IND_EVT
ring indication event
HFP AG API
API Reference
Header File
• components/bt/host/bluedroid/api/include/api/esp_hf_ag_api.h
Functions
esp_err_t esp_bt_hf_register_callback(esp_hf_cb_t callback)
Register application callback function to HFP AG module. This function should be called only after
Return
• ESP_OK: success
Parameters
• [in] callback: HFP AG event callback function
esp_err_t esp_bt_hf_init(esp_bd_addr_t remote_addr)
Initialize the bluetooth HF AG module. This function should be called after esp_bluedroid_enable() completes
successfully.
Return
Parameters
• [in] remote_addr: remote bluetooth device address
esp_err_t esp_bt_hf_deinit(esp_bd_addr_t remote_addr)
De-initialize for HF AG module. This function should be called only after esp_bluedroid_enable() completes
successfully.
Return
• ESP_OK: success
Parameters
esp_err_t esp_bt_hf_connect(esp_bd_addr_t remote_bda)
To establish a Service Level Connection to remote bluetooth HFP client device. This function must be called
after esp_bt_hf_init() and before esp_bt_hf_deinit().
Return
• ESP_OK: connect request is sent to lower layer

Parameters
• [in] remote_bda: remote bluetooth HFP client device address
esp_err_t esp_bt_hf_disconnect(esp_bd_addr_t remote_bda)
Disconnect from the remote HFP client. This function must be called after esp_bt_hf_init() and before
esp_bt_hf_deinit().
Return
Parameters
esp_err_t esp_bt_hf_connect_audio(esp_bd_addr_t remote_bda)
Create audio connection with remote HFP client. As a precondition to use this API, Service Level Connection
shall exist with HFP client.
Return
Parameters
esp_err_t esp_bt_hf_disconnect_audio(esp_bd_addr_t remote_bda)
Release the established audio connection with remote HFP client. As a precondition to use this API, Service
Level Connection shall exist with HFP client.
Return
Parameters
esp_err_t esp_bt_hf_vra(esp_bd_addr_t remote_bda, esp_hf_vr_state_t value)
Response of Volume Recognition Command(AT+VRA) from HFP client. As a precondition to use this API,
Service Level Connection shall exist with HFP client.
Return
Parameters
• [in] remote_bda: the device address of voice recognization initiator
• [in] value: 0 - voice recognition disabled, 1- voice recognition enabled
esp_err_t esp_bt_hf_volume_control(esp_bd_addr_t remote_bda, esp_hf_volume_control_target_t
type, int volume)
Volume synchronization with HFP client. As a precondition to use this API, Service Level Connection shall
exist with HFP client.
Return
Parameters
• [in] type: volume control target, speaker or microphone
• [in] volume: gain of the speaker of microphone, ranges 0 to 15
esp_err_t esp_hf_unat_response(esp_bd_addr_t remote_addr, char *unat)
Handle Unknown AT command from HFP Client. As a precondition to use this API, Service Level Connection


Return
Parameters
• [in] unat: User AT command response to HF Client. It will response ERROR by default if
unat is NULL.
esp_err_t esp_bt_hf_cmee_response(esp_bd_addr_t remote_bda, esp_hf_at_response_code_t re-
sponse_code, esp_hf_cme_err_t error_code)
Unsolicited send extend AT error code to HFP Client. As a precondition to use this API, Service Level Con-
nection shall exist with HFP client.
Return
Parameters
• [in] response_code: AT command response code
• [in] error_code: CME error code
esp_err_t esp_bt_hf_indchange_notification(esp_bd_addr_t remote_addr,
esp_hf_call_status_t call_state,
esp_hf_call_setup_status_t call_setup_state,
esp_hf_network_state_t ntk_state, int signal)
Usolicited send device status notificationto HFP Client. As a precondition to use this API, Service Level
Connection shall exist with HFP client.
Return
Parameters
• [in] call_state: call state
• [in] call_setup_state: call setup state
• [in] ntk_state: network service state
• [in] signal: signal strength from 0 to 5
esp_err_t esp_bt_hf_cind_response(esp_bd_addr_t remote_addr, esp_hf_call_status_t
call_state, esp_hf_call_setup_status_t call_setup_state,
esp_hf_network_state_t ntk_state, int signal,
esp_hf_roaming_status_t roam, int batt_lev,
esp_hf_call_held_status_t call_held_status)
Response to device individual indicatiors to HFP Client. As a precondition to use this API, Service Level
Return
Parameters
• [in] ntk_state: network service state
• [in] signal: signal strength from 0 to 5
• [in] roam: roam state

• [in] batt_lev: batery level from 0 to 5

• [in] call_held_status: call held status
esp_err_t esp_bt_hf_cops_response(esp_bd_addr_t remote_addr, char *name)
Reponse for AT+COPS command from HF Client. As a precondition to use this API, Service Level Connection
Return
Parameters
• [in] name: current operator name
esp_err_t esp_bt_hf_clcc_response(esp_bd_addr_t remote_addr, int in-
dex, esp_hf_current_call_direction_t
dir, esp_hf_current_call_status_t cur-
rent_call_state, esp_hf_current_call_mode_t mode,
esp_hf_current_call_mpty_type_t mpty, char *number,
esp_hf_call_addr_type_t type)
Response to AT+CLCC command from HFP Client. As a precondition to use this API, Service Level Con-
Return
Parameters
• [in] index: the index of current call
• [in] dir: call direction (incoming/outgoing)
• [in] current_call_state: current call state
• [in] mode: current call mode (voice/data/fax)
• [in] mpty: single or multi type
• [in] number: current call number
• [in] type: international type or unknow
esp_err_t esp_bt_hf_cnum_response(esp_bd_addr_t remote_addr, char *number,
esp_hf_subscriber_service_type_t type)
Response for AT+CNUM command from HF Client. As a precondition to use this API, Service Level Con-
Return
Parameters
• [in] number: registration number
• [in] type: service type (unknown/voice/fax)
esp_err_t esp_bt_hf_bsir(esp_bd_addr_t remote_addr, esp_hf_in_band_ring_state_t state)
Inform HF Client that AG Provided in-band ring tone or not. As a precondition to use this API, Service Level
Return
Parameters

• [in] state: in-band ring tone state

esp_err_t esp_bt_hf_answer_call(esp_bd_addr_t remote_addr, int num_active, int num_held,
esp_hf_call_status_t call_state, esp_hf_call_setup_status_t
call_setup_state, char *number, esp_hf_call_addr_type_t
call_addr_type)
Answer Incoming Call from AG. As a precondition to use this API, Service Level Connection shall exist with
HFP client.
Return
Parameters
• [in] num_active: the number of active call
• [in] num_held: the number of held call
• [in] number: number of the incoming call
• [in] call_addr_type: call address type
esp_err_t esp_bt_hf_reject_call(esp_bd_addr_t remote_addr, int num_active, int num_held,
call_addr_type)
Reject Incoming Call from AG. As a precondition to use this API, Service Level Connection shall exist with
HFP client.
Return
Parameters
• [in] number: number of the incoming call
esp_err_t esp_bt_hf_out_call(esp_bd_addr_t remote_addr, int num_active, int num_held,
call_addr_type)
Initiate a call from AG. As a precondition to use this API, Service Level Connection shall exist with HFP client.
Return
Parameters
• [in] number: number of the outgoing call

esp_err_t esp_bt_hf_end_call(esp_bd_addr_t remote_addr, int num_active, int num_held,

call_addr_type)
End an ongoing call. As a precondition to use this API, Service Level Connection shall exist with HFP client.
Return
Parameters
• [in] number: number of the call
esp_err_t esp_bt_hf_register_data_callback(esp_hf_incoming_data_cb_t recv,
esp_hf_outgoing_data_cb_t send)
Register AG data output function. The callback is only used in the case that Voice Over HCI is enabled.
Return
• ESP_OK: success
Parameters
• [in] recv: HFP client incoming data callback function
• [in] send: HFP client outgoing data callback function
void esp_hf_outgoing_data_ready(void)
Trigger the lower-layer to fetch and send audio data.
This function is only used in the case that Voice Over HCI is enabled. As a precondition to use this API,
Service Level Connection shall exist with HFP client. After this function is called, lower layer will invoke
esp_hf_client_outgoing_data_cb_t to fetch data
Unions
union esp_hf_cb_param_t
#include <esp_hf_ag_api.h> HFP AG callback parameters.
Public Members
struct esp_hf_cb_param_t::hf_conn_stat_param conn_stat

AG callback param of ESP_HF_CONNECTION_STATE_EVT
struct esp_hf_cb_param_t::hf_audio_stat_param audio_stat
AG callback param of ESP_HF_AUDIO_STATE_EVT
struct esp_hf_cb_param_t::hf_vra_rep_param vra_rep
AG callback param of ESP_HF_BVRA_RESPONSE_EVT
struct esp_hf_cb_param_t::hf_volume_control_param volume_control
AG callback param of ESP_HF_VOLUME_CONTROL_EVT
struct esp_hf_cb_param_t::hf_unat_rep_param unat_rep
AG callback param of ESP_HF_UNAT_RESPONSE_EVT
struct esp_hf_cb_param_t::hf_cind_param cind
AG callback param of ESP_HF_CIND_RESPONSE_EVT

struct esp_hf_cb_param_t::hf_out_call_param out_call

AG callback param of ESP_HF_DIAL_EVT
struct esp_hf_cb_param_t::hf_vts_rep_param vts_rep
AG callback param of ESP_HF_VTS_RESPONSE_EVT
struct esp_hf_cb_param_t::hf_nrec_param nrec
AG callback param of ESP_HF_NREC_RESPONSE_EVT
struct esp_hf_cb_param_t::hf_wbs_rep_param wbs_rep
AG callback param of ESP_HF_WBS_RESPONSE_EVT
struct esp_hf_cb_param_t::hf_bcs_rep_param bcs_rep
AG callback param of ESP_HF_BCS_RESPONSE_EVT
struct hf_audio_stat_param
#include <esp_hf_ag_api.h> ESP_HF_AUDIO_STATE_EVT.
Public Members
esp_hf_audio_state_t state
Audio connection state
struct hf_bcs_rep_param
#include <esp_hf_ag_api.h> ESP_HF_BCS_RESPONSE_EVT.
Public Members
esp_hf_wbs_config_t mode
codec mode CVSD or mSBC
struct hf_cind_param
#include <esp_hf_ag_api.h> ESP_HF_CIND_RESPONSE_EVT.
Public Members
esp_hf_call_status_t call_status
call status indicator
esp_hf_call_setup_status_t call_setup_status
call setup status indicator
esp_hf_network_state_t svc
int signal_strength
esp_hf_roaming_status_t roam
int battery_level
battery charge value, ranges from 0 to 5
esp_hf_call_held_status_t call_held_status
struct hf_conn_stat_param
#include <esp_hf_ag_api.h> ESP_HS_CONNECTION_STATE_EVT.

Public Members
esp_hf_connection_state_t state
Connection state
uint32_t peer_feat
HF supported features
uint32_t chld_feat
AG supported features on call hold and multiparty services
struct hf_nrec_param
#include <esp_hf_ag_api.h> ESP_HF_NREC_RESPOSNE_EVT.
Public Members
esp_hf_nrec_t state
NREC enabled or disabled
struct hf_out_call_param
#include <esp_hf_ag_api.h> ESP_HF_DIAL_EVT.
Public Members
char *num_or_loc
location in phone memory
struct hf_unat_rep_param
#include <esp_hf_ag_api.h> ESP_HF_UNAT_RESPOSNE_EVT.
Public Members
char *unat
Unknown AT command string
struct hf_volume_control_param
#include <esp_hf_ag_api.h> ESP_HF_VOLUME_CONTROL_EVT.
Public Members
esp_hf_volume_type_t type
Volume control target, speaker or microphone
int volume
Gain, ranges from 0 to 15
struct hf_vra_rep_param
#include <esp_hf_ag_api.h> ESP_HF_BVRA_RESPONSE_EVT.

Public Members
esp_hf_vr_state_t value
Voice recognition state
struct hf_vts_rep_param
#include <esp_hf_ag_api.h> ESP_HF_VTS_RESPOSNE_EVT.
Public Members
char *code
MTF code from HF Client
struct hf_wbs_rep_param
#include <esp_hf_ag_api.h> ESP_HF_WBS_RESPONSE_EVT.
Public Members
esp_hf_wbs_config_t codec
codec mode CVSD or mSBC
Macros
ESP_HF_PEER_FEAT_3WAY
ESP_HF_PEER_FEAT_ECNR
ESP_HF_PEER_FEAT_VREC
ESP_HF_PEER_FEAT_INBAND
ESP_HF_PEER_FEAT_VTAG
ESP_HF_PEER_FEAT_REJECT
ESP_HF_PEER_FEAT_ECS
ESP_HF_PEER_FEAT_ECC
ESP_HF_PEER_FEAT_EXTERR
ESP_HF_PEER_FEAT_CODEC
ESP_HF_CHLD_FEAT_REL
ESP_HF_CHLD_FEAT_REL_ACC
ESP_HF_CHLD_FEAT_REL_X
ESP_HF_CHLD_FEAT_HOLD_ACC
ESP_HF_CHLD_FEAT_PRIV_X
ESP_HF_CHLD_FEAT_MERGE
ESP_HF_CHLD_FEAT_MERGE_DETACH
Type Definitions
typedef void (*esp_hf_incoming_data_cb_t)(const uint8_t *buf, uint32_t len)
AG incoming data callback function, the callback is useful in case of Voice Over HCI.
Parameters

typedef uint32_t (*esp_hf_outgoing_data_cb_t)(uint8_t *buf, uint32_t len)
AG outgoing data callback function, the callback is useful in case of Voice Over HCI. Once audio connection
is set up and the application layer has prepared data to send, the lower layer will call this function to read data
and then send. This callback is supposed to be implemented as non-blocking, and if data is not enough, return
value 0 is supposed.
Return length of data successfully read
Parameters
typedef void (*esp_hf_cb_t)(esp_hf_cb_event_t event, esp_hf_cb_param_t *param)
HF AG callback function type.
Parameters
Enumerations
enum esp_hf_cb_event_t
HF callback events.
Values:
ESP_HF_CONNECTION_STATE_EVT = 0
Connection state changed event
ESP_HF_AUDIO_STATE_EVT
Audio connection state change event
ESP_HF_BVRA_RESPONSE_EVT
Voice recognition state change event
ESP_HF_VOLUME_CONTROL_EVT
Audio volume control command from HF Client, provided by +VGM or +VGS message
ESP_HF_UNAT_RESPONSE_EVT
Unknown AT cmd Response
ESP_HF_IND_UPDATE_EVT
Indicator Update Event
ESP_HF_CIND_RESPONSE_EVT
Call And Device Indicator Response
ESP_HF_COPS_RESPONSE_EVT
Current operator information
ESP_HF_CLCC_RESPONSE_EVT
List of current calls notification
ESP_HF_CNUM_RESPONSE_EVT
Subscriber information response from HF Client
ESP_HF_VTS_RESPONSE_EVT
Enable or not DTMF
ESP_HF_NREC_RESPONSE_EVT
Enable or not NREC
ESP_HF_ATA_RESPONSE_EVT
Answer an Incoming Call

ESP_HF_CHUP_RESPONSE_EVT
Reject an Incoming Call
ESP_HF_DIAL_EVT
Origin an outgoing call with specific number or the dial the last number
ESP_HF_WBS_RESPONSE_EVT
Codec Status
ESP_HF_BCS_RESPONSE_EVT
Final Codec Choice
2.1.5 NimBLE-based host APIs
Overview
Apache MyNewt NimBLE is a highly configurable and BT SIG qualifiable BLE stack providing both host and con-
troller functionalities. ESP-IDF supports NimBLE host stack which is specifically ported for ESP32 platform and
FreeRTOS. The underlying controller is still the same (as in case of Bluedroid) providing VHCI interface. Refer
to NimBLE user guide for a complete list of features and additional information on NimBLE stack. Most features
of NimBLE including BLE Mesh are supported by ESP-IDF. The porting layer is kept cleaner by maintaining all
the existing APIs of NimBLE along with a single ESP-NimBLE API for initialization, making it simpler for the
application developers.
Architecture
Currently, NimBLE host and controller support different transports such as UART and RAM between them. How-
ever, RAM transport cannot be used as is in case of ESP as ESP controller supports VHCI interface and buffering
schemes used by NimBLE host is incompatible with that used by ESP controller. Therefore, a new transport between
NimBLE host and ESP controller has been added. This is depicted in the figure below. This layer is responsible for
maintaining pool of transport buffers and formatting buffers exchanges between host and controller as per the re-
quirements.
Fig. 1: ESP NimBLE Stack
Threading Model
The NimBLE host can run inside the application thread or can have its own independent thread. This flexibil-
ity is inherently provided by NimBLE design. By default, a thread is spawned by the porting function nim-
ble_port_freertos_init. This behavior can be changed by overriding the same function. For BLE Mesh,
additional thread (advertising thread) is used which keeps on feeding advertisement events to the main thread.
Programming Sequence
To begin with, make sure that the NimBLE stack is enabled from menuconfig choose NimBLE for the Bluetooth host.
Typical programming sequence with NimBLE stack consists of the following steps:

• Initialize NVS flash using nvs_flash_init() API. This is because ESP controller uses NVS during
initialization.
• Call esp_nimble_hci_and_controller_init() to initialize ESP controller as well as trans-
port layer. This will also link the host and controller modules together. Alternatively, if ESP controller
is already initialized, then esp_nimble_hci_init() can be called for the remaining initialization.
• Initialize the host stack using nimble_port_init.
• Initialize the required NimBLE host configuration parameters and callbacks
• Perform application specific tasks/initialization
• Run the thread for host stack using nimble_port_freertos_init
This documentation does not cover NimBLE APIs. Refer to NimBLE tutorial for more details on the programming
sequence/NimBLE APIs for different scenarios.
API Reference
Header File
• components/bt/host/nimble/esp-hci/include/esp_nimble_hci.h
Functions
esp_err_t esp_nimble_hci_init(void)
Initialize VHCI transport layer between NimBLE Host and ESP Bluetooth controller.
This function initializes the transport buffers to be exchanged between NimBLE host and ESP controller. It
also registers required host callbacks with the controller.
Return
• ESP_OK if the initialization is successful
• Appropriate error code from esp_err_t in case of an error
esp_err_t esp_nimble_hci_and_controller_init(void)
Initialize ESP Bluetooth controller(link layer) and VHCI transport layer between NimBLE Host and ESP
Bluetooth controller.
This function initializes ESP controller in BLE only mode and the transport buffers to be exchanged between
NimBLE host and ESP controller. It also registers required host callbacks with the controller.
Below is the sequence of APIs to be called to init/enable NimBLE host and ESP controller:
void ble_host_task(void *param)

{
nimble_port_run(); //This function will return only when nimble_port_
,→stop() is executed.
nimble_port_freertos_deinit();
}
int ret = esp_nimble_hci_and_controller_init();

if (ret != ESP_OK) {
ESP_LOGE(TAG, "esp_nimble_hci_and_controller_init() failed with error: %d
,→", ret);
return;
}
nimble_port_init();
//Initialize the NimBLE Host configuration
nimble_port_freertos_init(ble_host_task);
nimble_port_freertos_init() is an optional call that creates a new task in which the NimBLE host will run.
The task function should have a call to nimble_port_run(). If a separate task is not required, calling nim-
ble_port_run() will run the NimBLE host in the current task.

Return
• ESP_OK if the initialization is successful
• Appropriate error code from esp_err_t in case of an error
esp_err_t esp_nimble_hci_deinit(void)
Deinitialize VHCI transport layer between NimBLE Host and ESP Bluetooth controller.
Note This function should be called after the NimBLE host is deinitialized.
Return
• ESP_OK if the deinitialization is successful
• Appropriate error codes from esp_err_t in case of an error
esp_err_t esp_nimble_hci_and_controller_deinit(void)
Deinitialize VHCI transport layer between NimBLE Host and ESP Bluetooth controller and disable and deini-
tialize the controller.
Below is the sequence of APIs to be called to disable/deinit NimBLE host and ESP controller:
Note This function should not be executed in the context of Bluetooth host task.
Note This function should be called after the NimBLE host is deinitialized.
int ret = nimble_port_stop();

if (ret == 0) {
nimble_port_deinit();
ret = esp_nimble_hci_and_controller_deinit();
if (ret != ESP_OK) {
ESP_LOGE(TAG, "esp_nimble_hci_and_controller_deinit() failed with␣
,→error: %d", ret);
}
}
If nimble_port_freertos_init() is used during initialization, then nimble_port_freertos_deinit() should be called

in the host task after nimble_port_run().
Return
• ESP_OK if the deinitialization is successful
• Appropriate error codes from esp_err_t in case of an error
Macros
BLE_HCI_UART_H4_NONE
BLE_HCI_UART_H4_CMD
BLE_HCI_UART_H4_ACL
BLE_HCI_UART_H4_SCO
BLE_HCI_UART_H4_EVT
2.1.6 ESP-BLE-MESH
With various features of ESP-BLE-MESH, users can create a managed flooding mesh network for several scenarios,
such as lighting, sensor and etc.
For an ESP32 to join and work on a ESP-BLE-MESH network, it must be provisioned firstly. By provisioning, the
ESP32, as an unprovisioned device, will join the ESP-BLE-MESH network and become a ESP-BLE-MESH node,
communicating with other nodes within or beyond the radio range.
Apart from ESP-BLE-MESH nodes, inside ESP-BLE-MESH network, there is also ESP32 that works as ESP-BLE-
MESH Provisioner, which could provision unprovisioned devices into ESP-BLE-MESH nodes and configure the
nodes with various features.

For information how to start using ESP32 and ESP-BLE-MESH, please see the Section Getting Started with ESP-
BLE-MESH. If you are interested in information on ESP-BLE-MESH architecture, including some details of software
implementation, please see Section ESP-BLE-MESH Architecture.
Application Examples and Demos
Please refer to Sections ESP-BLE-MESH Examples and ESP-BLE-MESH Demo Videos.
API Reference
ESP-BLE-MESH APIs are divided into the following parts:

• ESP-BLE-MESH Definitions
• ESP-BLE-MESH Core API Reference
• ESP-BLE-MESH Models API Reference
ESP-BLE-MESH Definitions
This section contains only one header file, which lists the following items of ESP-BLE-MESH.
• ID of all the models and related message opcodes
• Structs of model, element and Composition Data
• Structs of used by ESP-BLE-MESH Node/Provisioner for provisioning
• Structs used to transmit/receive messages
• Event types and related event parameters
Header File
• components/bt/esp_ble_mesh/api/esp_ble_mesh_defs.h
Unions
union esp_ble_mesh_prov_cb_param_t
#include <esp_ble_mesh_defs.h> BLE Mesh Node/Provisioner callback parameters union.
Public Members
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_prov_register_comp_param prov_register_comp

Event parameter of ESP_BLE_MESH_PROV_REGISTER_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_set_unprov_dev_name_comp_param node_set_unprov_dev_name
Event parameter of ESP_BLE_MESH_NODE_SET_UNPROV_DEV_NAME_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_prov_enable_comp_param node_prov_enable_comp
Event parameter of ESP_BLE_MESH_NODE_PROV_ENABLE_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_prov_disable_comp_param node_prov_disable_comp
Event parameter of ESP_BLE_MESH_NODE_PROV_DISABLE_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_link_open_evt_param node_prov_link_open
Event parameter of ESP_BLE_MESH_NODE_PROV_LINK_OPEN_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_link_close_evt_param node_prov_link_close
Event parameter of ESP_BLE_MESH_NODE_PROV_LINK_CLOSE_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_output_num_evt_param node_prov_output_num
Event parameter of ESP_BLE_MESH_NODE_PROV_OUTPUT_NUMBER_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_output_str_evt_param node_prov_output_str
Event parameter of ESP_BLE_MESH_NODE_PROV_OUTPUT_STRING_EVT

struct esp_ble_mesh_prov_cb_param_t::ble_mesh_input_evt_param node_prov_input

Event parameter of ESP_BLE_MESH_NODE_PROV_INPUT_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provision_complete_evt_param node_prov_complete
Event parameter of ESP_BLE_MESH_NODE_PROV_COMPLETE_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provision_reset_param node_prov_reset
Event parameter of ESP_BLE_MESH_NODE_PROV_RESET_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_set_oob_pub_key_comp_param node_prov_set_oob_pub_key_co
Event parameter of ESP_BLE_MESH_NODE_PROV_SET_OOB_PUB_KEY_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_input_number_comp_param node_prov_input_num_comp
Event parameter of ESP_BLE_MESH_NODE_PROV_INPUT_NUM_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_input_string_comp_param node_prov_input_str_comp
Event parameter of ESP_BLE_MESH_NODE_PROV_INPUT_STR_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_identity_enable_comp_param node_proxy_identity_enabl
Event parameter of ESP_BLE_MESH_NODE_PROXY_IDENTITY_ENABLE_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_gatt_enable_comp_param node_proxy_gatt_enable_comp
Event parameter of ESP_BLE_MESH_NODE_PROXY_GATT_ENABLE_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_gatt_disable_comp_param node_proxy_gatt_disable_com
Event parameter of ESP_BLE_MESH_NODE_PROXY_GATT_DISABLE_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_node_add_local_net_key_comp_param node_add_net_key_comp
Event parameter of ESP_BLE_MESH_NODE_ADD_LOCAL_NET_KEY_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_node_add_local_app_key_comp_param node_add_app_key_comp
Event parameter of ESP_BLE_MESH_NODE_ADD_LOCAL_APP_KEY_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_node_bind_local_mod_app_comp_param node_bind_app_key_to_
Event parameter of ESP_BLE_MESH_NODE_BIND_APP_KEY_TO_MODEL_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_recv_unprov_adv_pkt_param provisioner_recv_unpr
Event parameter of ESP_BLE_MESH_PROVISIONER_RECV_UNPROV_ADV_PKT_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_enable_comp_param provisioner_prov_enable
Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_ENABLE_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_disable_comp_param provisioner_prov_disabl
Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_DISABLE_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_link_open_evt_param provisioner_prov_link_open
Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_LINK_OPEN_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_read_oob_pub_key_evt_param provisioner_prov
Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_READ_OOB_PUB_KEY_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_input_evt_param provisioner_prov_input
Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_INPUT_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_output_evt_param provisioner_prov_output
Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_OUTPUT_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_link_close_evt_param provisioner_prov_link_clos
Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_LINK_CLOSE_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_comp_param provisioner_prov_complete
Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_COMPLETE_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_add_unprov_dev_comp_param provisioner_add_unpr
Event parameter of ESP_BLE_MESH_PROVISIONER_ADD_UNPROV_DEV_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_dev_with_addr_comp_param provisioner_prov_
Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_DEV_WITH_ADDR_COMP_EVT

struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_delete_dev_comp_param provisioner_delete_dev_c

Event parameter of ESP_BLE_MESH_PROVISIONER_DELETE_DEV_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_set_dev_uuid_match_comp_param provisioner_set_de
Event parameter of ESP_BLE_MESH_PROVISIONER_SET_DEV_UUID_MATCH_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_set_prov_data_info_comp_param provisioner_set_pr
Event parameter of ESP_BLE_MESH_PROVISIONER_SET_PROV_DATA_INFO_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_set_static_oob_val_comp_param provisioner_set_sta
Event parameter of ESP_BLE_MESH_PROVISIONER_SET_STATIC_OOB_VALUE_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_set_primary_elem_addr_comp_param provisioner_set
Event parameter of ESP_BLE_MESH_PROVISIONER_SET_PRIMARY_ELEM_ADDR_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_read_oob_pub_key_comp_param provisioner_pro
Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_READ_OOB_PUB_KEY_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_input_num_comp_param provisioner_prov_inp
Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_INPUT_NUMBER_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_input_str_comp_param provisioner_prov_inpu
Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_INPUT_STRING_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_set_node_name_comp_param provisioner_set_node_
Event parameter of ESP_BLE_MESH_PROVISIONER_SET_NODE_NAME_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_add_local_app_key_comp_param provisioner_add_ap
Event parameter of ESP_BLE_MESH_PROVISIONER_ADD_LOCAL_APP_KEY_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_update_local_app_key_comp_param provisioner_upda
Event parameter of ESP_BLE_MESH_PROVISIONER_UPDATE_LOCAL_APP_KEY_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_bind_local_mod_app_comp_param provisioner_bind_
Event parameter of ESP_BLE_MESH_PROVISIONER_BIND_APP_KEY_TO_MODEL_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_add_local_net_key_comp_param provisioner_add_net
Event parameter of ESP_BLE_MESH_PROVISIONER_ADD_LOCAL_NET_KEY_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_update_local_net_key_comp_param provisioner_updat
Event parameter of ESP_BLE_MESH_PROVISIONER_UPDATE_LOCAL_NET_KEY_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_store_node_comp_data_comp_param provisioner_stor
Event parameter of ESP_BLE_MESH_PROVISIONER_STORE_NODE_COMP_DATA_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_delete_node_with_uuid_comp_param provisioner_dele
Event parameter of ESP_BLE_MESH_PROVISIONER_DELETE_NODE_WITH_UUID_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_delete_node_with_addr_comp_param provisioner_dele
Event parameter of ESP_BLE_MESH_PROVISIONER_DELETE_NODE_WITH_ADDR_COMP_EVT
int err_code
Indicate the result of enabling/disabling to receive heartbeat messages by the Provisioner
Indicate the result of setting the heartbeat filter type by the Provisioner
Indicate the result of setting the heartbeat filter address by the Provisioner
Indicate the result of directly erasing settings by the Provisioner
Indicate the result of opening settings with index by the Provisioner
Indicate the result of opening settings with user id by the Provisioner
Indicate the result of closing settings with index by the Provisioner
Indicate the result of closing settings with user id by the Provisioner
Indicate the result of deleting settings with index by the Provisioner
Indicate the result of deleting settings with user id by the Provisioner

bool enable
Indicate enabling or disabling receiving heartbeat messages
struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_enable_heartbeat_recv_comp
ESP_BLE_MESH_PROVISIONER_ENABLE_HEARTBEAT_RECV_COMP_EVT.
Event parameters of ESP_BLE_MESH_PROVISIONER_ENABLE_HEARTBEAT_RECV_COMP_EVT
uint8_t type
Type of the filter used for receiving heartbeat messages
struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_set_heartbeat_filter_type_comp
ESP_BLE_MESH_PROVISIONER_SET_HEARTBEAT_FILTER_TYPE_COMP_EVT.
Event parameters of ESP_BLE_MESH_PROVISIONER_SET_HEARTBEAT_FILTER_TYPE_COMP_EVT
uint8_t op
Operation (add, remove, clean)
uint16_t hb_src
Heartbeat source address
uint16_t hb_dst
Heartbeat destination address
struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_set_heartbeat_filter_info_comp
ESP_BLE_MESH_PROVISIONER_SET_HEARTBEAT_FILTER_INFO_COMP_EVT.
Event parameters of ESP_BLE_MESH_PROVISIONER_SET_HEARTBEAT_FILTER_INFO_COMP_EVT
uint8_t init_ttl
Heartbeat InitTTL
uint8_t rx_ttl
Heartbeat RxTTL
uint8_t hops
Heartbeat hops (InitTTL - RxTTL + 1)
uint16_t feature
Bit field of currently active features of the node
int8_t rssi
RSSI of the heartbeat message
struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_recv_heartbeat
ESP_BLE_MESH_PROVISIONER_RECV_HEARTBEAT_MESSAGE_EVT.
Event parameters of ESP_BLE_MESH_PROVISIONER_RECV_HEARTBEAT_MESSAGE_EVT
struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_direct_erase_settings_comp
ESP_BLE_MESH_PROVISIONER_DRIECT_ERASE_SETTINGS_COMP_EVT.
Event parameters of ESP_BLE_MESH_PROVISIONER_DRIECT_ERASE_SETTINGS_COMP_EVT
uint8_t index
Index of Provisioner settings
struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_open_settings_with_index_comp
ESP_BLE_MESH_PROVISIONER_OPEN_SETTINGS_WITH_INDEX_COMP_EVT.
Event parameter of ESP_BLE_MESH_PROVISIONER_OPEN_SETTINGS_WITH_INDEX_COMP_EVT
char uid[ESP_BLE_MESH_SETTINGS_UID_SIZE + 1]
Provisioner settings user id
struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_open_settings_with_uid_comp
ESP_BLE_MESH_PROVISIONER_OPEN_SETTINGS_WITH_UID_COMP_EVT.
Event parameters of ESP_BLE_MESH_PROVISIONER_OPEN_SETTINGS_WITH_UID_COMP_EVT

struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_close_settings_with_index_comp

ESP_BLE_MESH_PROVISIONER_CLOSE_SETTINGS_WITH_INDEX_COMP_EVT.
Event parameter of ESP_BLE_MESH_PROVISIONER_CLOSE_SETTINGS_WITH_INDEX_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_close_settings_with_uid_comp
ESP_BLE_MESH_PROVISIONER_CLOSE_SETTINGS_WITH_UID_COMP_EVT.
Event parameters of ESP_BLE_MESH_PROVISIONER_CLOSE_SETTINGS_WITH_UID_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_delete_settings_with_index_comp
ESP_BLE_MESH_PROVISIONER_DELETE_SETTINGS_WITH_INDEX_COMP_EVT.
Event parameter of ESP_BLE_MESH_PROVISIONER_DELETE_SETTINGS_WITH_INDEX_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_delete_settings_with_uid_comp
ESP_BLE_MESH_PROVISIONER_DELETE_SETTINGS_WITH_UID_COMP_EVT.
Event parameters of ESP_BLE_MESH_PROVISIONER_DELETE_SETTINGS_WITH_UID_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_set_fast_prov_info_comp_param set_fast_prov_info_comp
Event parameter of ESP_BLE_MESH_SET_FAST_PROV_INFO_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_set_fast_prov_action_comp_param set_fast_prov_action_comp
Event parameter of ESP_BLE_MESH_SET_FAST_PROV_ACTION_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_heartbeat_msg_recv_param heartbeat_msg_recv
Event parameter of ESP_BLE_MESH_HEARTBEAT_MESSAGE_RECV_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_enable_comp_param lpn_enable_comp
Event parameter of ESP_BLE_MESH_LPN_ENABLE_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_disable_comp_param lpn_disable_comp
Event parameter of ESP_BLE_MESH_LPN_DISABLE_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_poll_comp_param lpn_poll_comp
Event parameter of ESP_BLE_MESH_LPN_POLL_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_friendship_establish_param lpn_friendship_establish
Event parameter of ESP_BLE_MESH_LPN_FRIENDSHIP_ESTABLISH_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_friendship_terminate_param lpn_friendship_terminate
Event parameter of ESP_BLE_MESH_LPN_FRIENDSHIP_TERMINATE_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_friend_friendship_establish_param frnd_friendship_establish
Event parameter of ESP_BLE_MESH_FRIEND_FRIENDSHIP_ESTABLISH_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_friend_friendship_terminate_param frnd_friendship_terminate
Event parameter of ESP_BLE_MESH_FRIEND_FRIENDSHIP_TERMINATE_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_recv_adv_pkt_param proxy_client_recv_adv_pkt
Event parameter of ESP_BLE_MESH_PROXY_CLIENT_RECV_ADV_PKT_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_connected_param proxy_client_connected
Event parameter of ESP_BLE_MESH_PROXY_CLIENT_CONNECTED_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_disconnected_param proxy_client_disconnected
Event parameter of ESP_BLE_MESH_PROXY_CLIENT_DISCONNECTED_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_recv_filter_status_param proxy_client_recv_filte
Event parameter of ESP_BLE_MESH_PROXY_CLIENT_RECV_FILTER_STATUS_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_connect_comp_param proxy_client_connect_comp
Event parameter of ESP_BLE_MESH_PROXY_CLIENT_CONNECT_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_disconnect_comp_param proxy_client_disconnect
Event parameter of ESP_BLE_MESH_PROXY_CLIENT_DISCONNECT_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_set_filter_type_comp_param proxy_client_set_filt
Event parameter of ESP_BLE_MESH_PROXY_CLIENT_SET_FILTER_TYPE_COMP_EVT

struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_add_filter_addr_comp_param proxy_client_add_fil

Event parameter of ESP_BLE_MESH_PROXY_CLIENT_ADD_FILTER_ADDR_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_remove_filter_addr_comp_param proxy_client_remov
Event parameter of ESP_BLE_MESH_PROXY_CLIENT_REMOVE_FILTER_ADDR_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_model_sub_group_addr_comp_param model_sub_group_addr_co
Event parameters of ESP_BLE_MESH_MODEL_SUBSCRIBE_GROUP_ADDR_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_model_unsub_group_addr_comp_param model_unsub_group_addr
Event parameters of ESP_BLE_MESH_MODEL_UNSUBSCRIBE_GROUP_ADDR_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_deinit_mesh_comp_param deinit_mesh_comp
Event parameter of ESP_BLE_MESH_DEINIT_MESH_COMP_EVT
struct ble_mesh_deinit_mesh_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_DEINIT_MESH_COMP_EVT.
Public Members
int err_code
Indicate the result of BLE Mesh deinitialization
struct ble_mesh_friend_friendship_establish_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_FRIEND_FRIENDSHIP_ESTABLISH_EVT.
Public Members
uint16_t lpn_addr
Low Power Node unicast address
struct ble_mesh_friend_friendship_terminate_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_FRIEND_FRIENDSHIP_TERMINATE_EVT.
Public Types
enum [anonymous]
This enum value is the reason of friendship termination on the friend node side
Values:
ESP_BLE_MESH_FRND_FRIENDSHIP_TERMINATE_ESTABLISH_FAIL
Friend Offer has been sent, but Friend Offer is not received within 1 second, friendship fails to
be established
ESP_BLE_MESH_FRND_FRIENDSHIP_TERMINATE_POLL_TIMEOUT
Friendship is established, PollTimeout timer expires and no Friend Poll/Sub Add/Sub Remove
is received
ESP_BLE_MESH_FRND_FRIENDSHIP_TERMINATE_RECV_FRND_REQ
Receive Friend Request from existing Low Power Node
ESP_BLE_MESH_FRND_FRIENDSHIP_TERMINATE_RECV_FRND_CLEAR
Receive Friend Clear from other friend node
ESP_BLE_MESH_FRND_FRIENDSHIP_TERMINATE_DISABLE
Friend feature disabled or corresponding NetKey is deleted

Public Members
uint16_t lpn_addr
Low Power Node unicast address
esp_ble_mesh_prov_cb_param_t::ble_mesh_friend_friendship_terminate_param::[anonymous] reason
This enum value is the reason of friendship termination on the friend node side Friendship terminated
reason
struct ble_mesh_heartbeat_msg_recv_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_HEARTBEAT_MESSAGE_RECV_EVT.
Public Members
uint8_t hops
Heartbeat hops (InitTTL - RxTTL + 1)
uint16_t feature
Bit field of currently active features of the node
struct ble_mesh_input_evt_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_INPUT_EVT.
Public Members
esp_ble_mesh_input_action_t action
Action of Input OOB Authentication
uint8_t size
Size of Input OOB Authentication
struct ble_mesh_input_number_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_INPUT_NUM_COMP_EVT.
Public Members
int err_code
Indicate the result of inputting number
struct ble_mesh_input_string_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_INPUT_STR_COMP_EVT.
Public Members
int err_code
Indicate the result of inputting string
struct ble_mesh_link_close_evt_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_LINK_CLOSE_EVT.
Public Members
esp_ble_mesh_prov_bearer_t bearer
Type of the bearer used when device link is closed
struct ble_mesh_link_open_evt_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_LINK_OPEN_EVT.

Public Members
Type of the bearer used when device link is open
struct ble_mesh_lpn_disable_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_LPN_DISABLE_COMP_EVT.
Public Members
int err_code
Indicate the result of disabling LPN functionality
struct ble_mesh_lpn_enable_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_LPN_ENABLE_COMP_EVT.
Public Members
int err_code
Indicate the result of enabling LPN functionality
struct ble_mesh_lpn_friendship_establish_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_LPN_FRIENDSHIP_ESTABLISH_EVT.
Public Members
uint16_t friend_addr
Friend Node unicast address
struct ble_mesh_lpn_friendship_terminate_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_LPN_FRIENDSHIP_TERMINATE_EVT.
Public Members
uint16_t friend_addr
Friend Node unicast address
struct ble_mesh_lpn_poll_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_LPN_POLL_COMP_EVT.
Public Members
int err_code
Indicate the result of sending Friend Poll
struct ble_mesh_model_sub_group_addr_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_MODEL_SUBSCRIBE_GROUP_ADDR_COMP_EVT.
Public Members
int err_code
Indicate the result of local model subscribing group address
uint16_t element_addr
Element address

uint16_t company_id
Company ID
uint16_t model_id
Model ID
uint16_t group_addr
Group Address
struct ble_mesh_model_unsub_group_addr_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_MODEL_UNSUBSCRIBE_GROUP_ADDR_COMP_EVT.
Public Members
int err_code
Indicate the result of local model unsubscribing group address
Element address
uint16_t company_id
Company ID
uint16_t model_id
Model ID
uint16_t group_addr
Group Address
struct ble_mesh_node_add_local_app_key_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_ADD_LOCAL_APP_KEY_COMP_EVT.
Public Members
int err_code
Indicate the result of adding local AppKey by the node
uint16_t net_idx
NetKey Index
uint16_t app_idx
AppKey Index
struct ble_mesh_node_add_local_net_key_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_ADD_LOCAL_NET_KEY_COMP_EVT.
Public Members
int err_code
Indicate the result of adding local NetKey by the node
uint16_t net_idx
NetKey Index
struct ble_mesh_node_bind_local_mod_app_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_BIND_APP_KEY_TO_MODEL_COMP_EVT.

Public Members
int err_code
Indicate the result of binding AppKey with model by the node
Element address
uint16_t app_idx
AppKey Index
uint16_t company_id
Company ID
uint16_t model_id
Model ID
struct ble_mesh_output_num_evt_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_OUTPUT_NUMBER_EVT.
Public Members
esp_ble_mesh_output_action_t action
Action of Output OOB Authentication
uint32_t number
Number of Output OOB Authentication
struct ble_mesh_output_str_evt_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_OUTPUT_STRING_EVT.
Public Members
char string[8]
String of Output OOB Authentication
struct ble_mesh_prov_disable_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_DISABLE_COMP_EVT.
Public Members
int err_code
Indicate the result of disabling BLE Mesh device
struct ble_mesh_prov_enable_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_ENABLE_COMP_EVT.
Public Members
int err_code
Indicate the result of enabling BLE Mesh device
struct ble_mesh_prov_register_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROV_REGISTER_COMP_EVT.

Public Members
int err_code
Indicate the result of BLE Mesh initialization
struct ble_mesh_provision_complete_evt_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_COMPLETE_EVT.
Public Members
uint16_t net_idx
NetKey Index
uint8_t net_key[16]
NetKey
uint16_t addr
Primary address
uint8_t flags
Flags
uint32_t iv_index
IV Index
struct ble_mesh_provision_reset_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_RESET_EVT.
struct ble_mesh_provisioner_add_local_app_key_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_ADD_LOCAL_APP_KEY_COMP_EVT.
Public Members
int err_code
Indicate the result of adding local AppKey by the Provisioner
uint16_t net_idx
NetKey Index
uint16_t app_idx
AppKey Index
struct ble_mesh_provisioner_add_local_net_key_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_ADD_LOCAL_NET_KEY_COMP_EVT.
Public Members
int err_code
Indicate the result of adding local NetKey by the Provisioner
uint16_t net_idx
NetKey Index
struct ble_mesh_provisioner_add_unprov_dev_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_ADD_UNPROV_DEV_COMP_EVT.

Public Members
int err_code
Indicate the result of adding device into queue by the Provisioner
struct ble_mesh_provisioner_bind_local_mod_app_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_BIND_APP_KEY_TO_MODEL_COMP_EVT.
Public Members
int err_code
Indicate the result of binding AppKey with model by the Provisioner
Element address
uint16_t app_idx
AppKey Index
uint16_t company_id
Company ID
uint16_t model_id
Model ID
struct ble_mesh_provisioner_delete_dev_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_DELETE_DEV_COMP_EVT.
Public Members
int err_code
Indicate the result of deleting device by the Provisioner
struct ble_mesh_provisioner_delete_node_with_addr_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_DELETE_NODE_WITH_ADDR_COMP_EVT.
Public Members
int err_code
Indicate the result of deleting node with unicast address by the Provisioner
uint16_t unicast_addr
Node unicast address
struct ble_mesh_provisioner_delete_node_with_uuid_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_DELETE_NODE_WITH_UUID_COMP_EVT.
Public Members
int err_code
Indicate the result of deleting node with uuid by the Provisioner
uint8_t uuid[16]
Node device uuid
struct ble_mesh_provisioner_link_close_evt_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_PROV_LINK_CLOSE_EVT.

Public Members
Type of the bearer used when Provisioner link is closed
uint8_t reason
Reason of the closed provisioning link
struct ble_mesh_provisioner_link_open_evt_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_PROV_LINK_OPEN_EVT.
Public Members
Type of the bearer used when Provisioner link is opened
struct ble_mesh_provisioner_prov_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_PROV_COMPLETE_EVT.
Public Members
uint16_t node_idx
Index of the provisioned device
esp_ble_mesh_octet16_t device_uuid
Device UUID of the provisioned device
Primary address of the provisioned device
uint8_t element_num
Element count of the provisioned device
uint16_t netkey_idx
NetKey Index of the provisioned device
struct ble_mesh_provisioner_prov_dev_with_addr_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_PROV_DEV_WITH_ADDR_COMP_EVT.
Public Members
int err_code
Indicate the result of Provisioner starting to provision a device
struct ble_mesh_provisioner_prov_disable_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_PROV_DISABLE_COMP_EVT.
Public Members
int err_code
Indicate the result of disabling BLE Mesh Provisioner
struct ble_mesh_provisioner_prov_enable_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_PROV_ENABLE_COMP_EVT.

Public Members
int err_code
Indicate the result of enabling BLE Mesh Provisioner
struct ble_mesh_provisioner_prov_input_evt_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_PROV_INPUT_EVT.
Public Members
esp_ble_mesh_oob_method_t method
Method of device Output OOB Authentication
esp_ble_mesh_output_action_t action
Action of device Output OOB Authentication
uint8_t size
Size of device Output OOB Authentication
uint8_t link_idx
Index of the provisioning link
struct ble_mesh_provisioner_prov_input_num_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_PROV_INPUT_NUMBER_COMP_EVT.
Public Members
int err_code
Indicate the result of inputting number by the Provisioner
struct ble_mesh_provisioner_prov_input_str_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_PROV_INPUT_STRING_COMP_EVT.
Public Members
int err_code
Indicate the result of inputting string by the Provisioner
struct ble_mesh_provisioner_prov_output_evt_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_PROV_OUTPUT_EVT.
Public Members
esp_ble_mesh_oob_method_t method
Method of device Input OOB Authentication
esp_ble_mesh_input_action_t action
Action of device Input OOB Authentication
uint8_t size
Size of device Input OOB Authentication
uint8_t link_idx
char string[8]
String output by the Provisioner
uint32_t number
Number output by the Provisioner

union esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_output_evt_param::[anonymous] [anonymous]
struct ble_mesh_provisioner_prov_read_oob_pub_key_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_PROV_READ_OOB_PUB_KEY_COMP_EVT.
Public Members
int err_code
Indicate the result of setting OOB Public Key by the Provisioner
struct ble_mesh_provisioner_prov_read_oob_pub_key_evt_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_PROV_READ_OOB_PUB_KEY_EVT.
Public Members
uint8_t link_idx
struct ble_mesh_provisioner_recv_unprov_adv_pkt_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_RECV_UNPROV_ADV_PKT_EVT.
Public Members
uint8_t dev_uuid[16]
Device UUID of the unprovisioned device
esp_ble_mesh_bd_addr_t addr
Device address of the unprovisioned device
esp_ble_mesh_addr_type_t addr_type
Device address type
uint16_t oob_info
OOB Info of the unprovisioned device
uint8_t adv_type
Avertising type of the unprovisioned device
Bearer of the unprovisioned device
int8_t rssi
RSSI of the received advertising packet
struct ble_mesh_provisioner_set_dev_uuid_match_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_SET_DEV_UUID_MATCH_COMP_EVT.
Public Members
int err_code
Indicate the result of setting Device UUID match value by the Provisioner
struct ble_mesh_provisioner_set_node_name_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_SET_NODE_NAME_COMP_EVT.

Public Members
int err_code
Indicate the result of setting provisioned device name by the Provisioner
uint16_t node_index
Index of the provisioned device
struct ble_mesh_provisioner_set_primary_elem_addr_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_SET_PRIMARY_ELEM_ADDR_COMP_EVT.
Public Members
int err_code
Indicate the result of setting unicast address of primary element by the Provisioner
struct ble_mesh_provisioner_set_prov_data_info_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_SET_PROV_DATA_INFO_COMP_EVT.
Public Members
int err_code
Indicate the result of setting provisioning info by the Provisioner
struct ble_mesh_provisioner_set_static_oob_val_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_SET_STATIC_OOB_VALUE_COMP_EVT.
Public Members
int err_code
Indicate the result of setting static oob value by the Provisioner
struct ble_mesh_provisioner_store_node_comp_data_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_STORE_NODE_COMP_DATA_COMP_EVT.
Public Members
int err_code
Indicate the result of storing node composition data by the Provisioner
uint16_t addr
Node element address
struct ble_mesh_provisioner_update_local_app_key_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_UPDATE_LOCAL_APP_KEY_COMP_EVT.
Public Members
int err_code
Indicate the result of updating local AppKey by the Provisioner
uint16_t net_idx
NetKey Index
uint16_t app_idx
AppKey Index

struct ble_mesh_provisioner_update_local_net_key_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_UPDATE_LOCAL_NET_KEY_COMP_EVT.
Public Members
int err_code
Indicate the result of updating local NetKey by the Provisioner
uint16_t net_idx
NetKey Index
struct ble_mesh_proxy_client_add_filter_addr_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROXY_CLIENT_ADD_FILTER_ADDR_COMP_EVT.
Public Members
int err_code
Indicate the result of Proxy Client add filter address
uint8_t conn_handle
Proxy connection handle
uint16_t net_idx
Corresponding NetKey Index
struct ble_mesh_proxy_client_connect_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROXY_CLIENT_CONNECT_COMP_EVT.
Public Members
int err_code
Indicate the result of Proxy Client connect
Device address of the Proxy Server
Device address type
uint16_t net_idx
struct ble_mesh_proxy_client_connected_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROXY_CLIENT_CONNECTED_EVT.
Public Members
Device address type
uint8_t conn_handle
uint16_t net_idx
struct ble_mesh_proxy_client_disconnect_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROXY_CLIENT_DISCONNECT_COMP_EVT.

Public Members
int err_code
Indicate the result of Proxy Client disconnect
uint8_t conn_handle
struct ble_mesh_proxy_client_disconnected_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROXY_CLIENT_DISCONNECTED_EVT.
Public Members
Device address type
uint8_t conn_handle
uint16_t net_idx
uint8_t reason
Proxy disconnect reason
struct ble_mesh_proxy_client_recv_adv_pkt_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROXY_CLIENT_RECV_ADV_PKT_EVT.
Public Members
Device address
Device address type
uint16_t net_idx
Network ID related NetKey Index
uint8_t net_id[8]
Network ID contained in the advertising packet
int8_t rssi
RSSI of the received advertising packet
struct ble_mesh_proxy_client_recv_filter_status_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROXY_CLIENT_RECV_FILTER_STATUS_EVT.
Public Members
uint8_t conn_handle
uint16_t server_addr
Proxy Server primary element address
uint16_t net_idx

uint8_t filter_type
Proxy Server filter type(whitelist or blacklist)
uint16_t list_size
Number of addresses in the Proxy Server filter list
struct ble_mesh_proxy_client_remove_filter_addr_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROXY_CLIENT_REMOVE_FILTER_ADDR_COMP_EVT.
Public Members
int err_code
Indicate the result of Proxy Client remove filter address
uint8_t conn_handle
uint16_t net_idx
struct ble_mesh_proxy_client_set_filter_type_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROXY_CLIENT_SET_FILTER_TYPE_COMP_EVT.
Public Members
int err_code
Indicate the result of Proxy Client set filter type
uint8_t conn_handle
uint16_t net_idx
struct ble_mesh_proxy_gatt_disable_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROXY_GATT_DISABLE_COMP_EVT.
Public Members
int err_code
Indicate the result of disabling Mesh Proxy Service
struct ble_mesh_proxy_gatt_enable_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROXY_GATT_ENABLE_COMP_EVT.
Public Members
int err_code
Indicate the result of enabling Mesh Proxy Service
struct ble_mesh_proxy_identity_enable_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROXY_IDENTITY_ENABLE_COMP_EVT.
Public Members
int err_code
Indicate the result of enabling Mesh Proxy advertising

struct ble_mesh_set_fast_prov_action_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_SET_FAST_PROV_ACTION_COMP_EVT.
Public Members
uint8_t status_action
Indicate the result of setting action of fast provisioning
struct ble_mesh_set_fast_prov_info_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_SET_FAST_PROV_INFO_COMP_EVT.
Public Members
uint8_t status_unicast
Indicate the result of setting unicast address range of fast provisioning
uint8_t status_net_idx
Indicate the result of setting NetKey Index of fast provisioning
uint8_t status_match
Indicate the result of setting matching Device UUID of fast provisioning
struct ble_mesh_set_oob_pub_key_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_SET_OOB_PUB_KEY_COMP_EVT.
Public Members
int err_code
Indicate the result of setting OOB Public Key
struct ble_mesh_set_unprov_dev_name_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_SET_UNPROV_DEV_NAME_COMP_EVT.
Public Members
int err_code
Indicate the result of setting BLE Mesh device name
union esp_ble_mesh_server_state_value_t
#include <esp_ble_mesh_defs.h> Server model state value union.
Public Members
uint8_t onoff
The value of the Generic OnOff state
The value of the Light LC Light OnOff state
struct esp_ble_mesh_server_state_value_t::[anonymous] gen_onoff
The Generic OnOff state
int16_t level
The value of the Generic Level state
struct esp_ble_mesh_server_state_value_t::[anonymous] gen_level
The Generic Level state
uint8_t onpowerup
The value of the Generic OnPowerUp state

struct esp_ble_mesh_server_state_value_t::[anonymous] gen_onpowerup

The Generic OnPowerUp state
uint16_t power
The value of the Generic Power Actual state
struct esp_ble_mesh_server_state_value_t::[anonymous] gen_power_actual
The Generic Power Actual state
uint16_t lightness
The value of the Light Lightness Actual state
The value of the Light Lightness Linear state
The value of the Light CTL Lightness state
The value of the Light HSL Lightness state
The value of the Light xyL Lightness state
struct esp_ble_mesh_server_state_value_t::[anonymous] light_lightness_actual
The Light Lightness Actual state
struct esp_ble_mesh_server_state_value_t::[anonymous] light_lightness_linear
The Light Lightness Linear state
struct esp_ble_mesh_server_state_value_t::[anonymous] light_ctl_lightness
The Light CTL Lightness state
uint16_t temperature
The value of the Light CTL Temperature state
int16_t delta_uv
The value of the Light CTL Delta UV state
struct esp_ble_mesh_server_state_value_t::[anonymous] light_ctl_temp_delta_uv
The Light CTL Temperature & Delta UV states
uint16_t hue
The value of the Light HSL Hue state
uint16_t saturation
The value of the Light HSL Saturation state
struct esp_ble_mesh_server_state_value_t::[anonymous] light_hsl
The Light HSL composite state
struct esp_ble_mesh_server_state_value_t::[anonymous] light_hsl_lightness
The Light HSL Lightness state
struct esp_ble_mesh_server_state_value_t::[anonymous] light_hsl_hue
The Light HSL Hue state
struct esp_ble_mesh_server_state_value_t::[anonymous] light_hsl_saturation
The Light HSL Saturation state
struct esp_ble_mesh_server_state_value_t::[anonymous] light_xyl_lightness
The Light xyL Lightness state
struct esp_ble_mesh_server_state_value_t::[anonymous] light_lc_light_onoff
The Light LC Light OnOff state
union esp_ble_mesh_model_cb_param_t
#include <esp_ble_mesh_defs.h> BLE Mesh model callback parameters union.

Public Members
struct esp_ble_mesh_model_cb_param_t::ble_mesh_model_operation_evt_param model_operation

Event parameter of ESP_BLE_MESH_MODEL_OPERATION_EVT
struct esp_ble_mesh_model_cb_param_t::ble_mesh_model_send_comp_param model_send_comp
Event parameter of ESP_BLE_MESH_MODEL_SEND_COMP_EVT
struct esp_ble_mesh_model_cb_param_t::ble_mesh_model_publish_comp_param model_publish_comp
Event parameter of ESP_BLE_MESH_MODEL_PUBLISH_COMP_EVT
struct esp_ble_mesh_model_cb_param_t::ble_mesh_mod_recv_publish_msg_param client_recv_publish_msg
Event parameter of ESP_BLE_MESH_CLIENT_MODEL_RECV_PUBLISH_MSG_EVT
struct esp_ble_mesh_model_cb_param_t::ble_mesh_client_model_send_timeout_param client_send_timeout
Event parameter of ESP_BLE_MESH_CLIENT_MODEL_SEND_TIMEOUT_EVT
struct esp_ble_mesh_model_cb_param_t::ble_mesh_model_publish_update_evt_param model_publish_update
Event parameter of ESP_BLE_MESH_MODEL_PUBLISH_UPDATE_EVT
struct esp_ble_mesh_model_cb_param_t::ble_mesh_server_model_update_state_comp_param server_model_update_
Event parameter of ESP_BLE_MESH_SERVER_MODEL_UPDATE_STATE_COMP_EVT
struct ble_mesh_client_model_send_timeout_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_CLIENT_MODEL_SEND_TIMEOUT_EVT.
Public Members
uint32_t opcode
Opcode of the previously sent message
esp_ble_mesh_model_t *model
Pointer to the model which sends the previous message
esp_ble_mesh_msg_ctx_t *ctx
Pointer to the context of the previous message
struct ble_mesh_mod_recv_publish_msg_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_CLIENT_MODEL_RECV_PUBLISH_MSG_EVT.
Public Members
uint32_t opcode
Opcode of the unsolicited received message
Pointer to the model which receives the message
Pointer to the context of the message
uint16_t length
Length of the received message
uint8_t *msg
Value of the received message
struct ble_mesh_model_operation_evt_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_MODEL_OPERATION_EVT.

Public Members
uint32_t opcode
Opcode of the received message
Pointer to the model which receives the message
Pointer to the context of the received message
uint16_t length
Length of the received message
uint8_t *msg
Value of the received message
struct ble_mesh_model_publish_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_MODEL_PUBLISH_COMP_EVT.
Public Members
int err_code
Indicate the result of publishing a message
Pointer to the model which publishes the message
struct ble_mesh_model_publish_update_evt_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_MODEL_PUBLISH_UPDATE_EVT.
Public Members
Pointer to the model which is going to update its publish message
struct ble_mesh_model_send_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_MODEL_SEND_COMP_EVT.
Public Members
int err_code
Indicate the result of sending a message
uint32_t opcode
Opcode of the message
Pointer to the model which sends the message
Context of the message
struct ble_mesh_server_model_update_state_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_SERVER_MODEL_UPDATE_STATE_COMP_EVT.

Public Members
int err_code
Indicate the result of updating server model state
Pointer to the server model which state value is updated
esp_ble_mesh_server_state_type_t type
Type of the updated server state
Structures
struct esp_ble_mesh_deinit_param_t
BLE Mesh deinit parameters
Public Members
bool erase_flash
Indicate if erasing flash when deinit mesh stack
struct esp_ble_mesh_elem_t
Abstraction that describes a BLE Mesh Element. This structure is associated with struct bt_mesh_elem in
mesh_access.h
Public Members
Element Address, assigned during provisioning.
const uint16_t location
Location Descriptor (GATT Bluetooth Namespace Descriptors)
const uint8_t sig_model_count
SIG Model count
const uint8_t vnd_model_count
Vendor Model count
esp_ble_mesh_model_t *sig_models
SIG Models
esp_ble_mesh_model_t *vnd_models
Vendor Models
struct esp_ble_mesh_model_pub_t
Abstraction that describes a model publication context. This structure is associated with struct
bt_mesh_model_pub in mesh_access.h
Public Members
Pointer to the model to which the context belongs. Initialized by the stack.
uint16_t publish_addr
Publish Address.
uint16_t app_idx : 12
Publish AppKey Index.
uint16_t cred : 1
Friendship Credentials Flag.

uint16_t send_rel : 1
Force reliable sending (segment acks)
uint8_t ttl
Publish Time to Live.
uint8_t retransmit
Retransmit Count & Interval Steps.
uint8_t period
Publish Period.
uint8_t period_div : 4
Divisor for the Period.
uint8_t fast_period : 1
Use FastPeriodDivisor
uint8_t count : 3
Retransmissions left.
uint32_t period_start
Start of the current period.
struct net_buf_simple *msg
Publication buffer, containing the publication message.
This will get correctly created when the publication context has been defined using the
ESP_BLE_MESH_MODEL_PUB_DEFINE macro.
ESP_BLE_MESH_MODEL_PUB_DEFINE(name, size);
esp_ble_mesh_cb_t update
Callback used to update publish message. Initialized by the stack.
struct k_delayed_work timer
Publish Period Timer. Initialized by the stack.
uint8_t dev_role
Role of the device that is going to publish messages
struct esp_ble_mesh_model_op_t
Abstraction that describes a model operation context. This structure is associated with struct
bt_mesh_model_op in mesh_access.h
Public Members
const uint32_t opcode

Message opcode
const size_t min_len
Message minimum length
esp_ble_mesh_cb_t param_cb
Callback used to handle message. Initialized by the stack.
struct esp_ble_mesh_model_cbs_t
Abstraction that describes a model callback structure. This structure is associated with struct
bt_mesh_model_cb in mesh_access.h.
Public Members
esp_ble_mesh_cb_t init_cb
Callback used during model initialization. Initialized by the stack.

struct esp_ble_mesh_model
Abstraction that describes a Mesh Model instance. This structure is associated with struct bt_mesh_model in
mesh_access.h
Public Members
const uint16_t model_id

16-bit model identifier
uint16_t company_id
16-bit company identifier
uint16_t model_id
16-bit model identifier
struct esp_ble_mesh_model::[anonymous]::[anonymous] vnd
Structure encapsulating a model ID with a company ID
union esp_ble_mesh_model::[anonymous] [anonymous]
Model ID
uint8_t element_idx
Internal information, mainly for persistent storage Belongs to Nth element
uint8_t model_idx
Is the Nth model in the element
uint16_t flags
Information about what has changed
esp_ble_mesh_elem_t *element
The Element to which this Model belongs
esp_ble_mesh_model_pub_t *const pub
Model Publication
uint16_t keys[CONFIG_BLE_MESH_MODEL_KEY_COUNT]
AppKey List
uint16_t groups[CONFIG_BLE_MESH_MODEL_GROUP_COUNT]
Subscription List (group or virtual addresses)
esp_ble_mesh_model_op_t *op
Model operation context
esp_ble_mesh_model_cbs_t *cb
Model callback structure
void *user_data
Model-specific user data
struct esp_ble_mesh_msg_ctx_t
Message sending context. This structure is associated with struct bt_mesh_msg_ctx in mesh_access.h
Public Members
uint16_t net_idx
NetKey Index of the subnet through which to send the message.
uint16_t app_idx
AppKey Index for message encryption.
uint16_t addr
Remote address.

uint16_t recv_dst
Destination address of a received message. Not used for sending.
int8_t recv_rssi
RSSI of received packet. Not used for sending.
uint8_t recv_ttl : 7
Received TTL value. Not used for sending.
uint8_t send_rel : 1
Force sending reliably by using segment acknowledgement
uint8_t send_ttl
TTL, or ESP_BLE_MESH_TTL_DEFAULT for default TTL.
uint32_t recv_op
Opcode of a received message. Not used for sending message.
Model corresponding to the message, no need to be initialized before sending message
bool srv_send
Indicate if the message is sent by a node server model, no need to be initialized before sending message
struct esp_ble_mesh_prov_t
Provisioning properties & capabilities. This structure is associated with struct bt_mesh_prov in mesh_access.h
struct esp_ble_mesh_comp_t
Node Composition data context. This structure is associated with struct bt_mesh_comp in mesh_access.h
Public Members
uint16_t cid
16-bit SIG-assigned company identifier
uint16_t pid
16-bit vendor-assigned product identifier
uint16_t vid
16-bit vendor-assigned product version identifier
size_t element_count
Element count
esp_ble_mesh_elem_t *elements
A sequence of elements
struct esp_ble_mesh_unprov_dev_add_t
Information of the device which is going to be added for provisioning.
Public Members
Device address
Device address type
uint8_t uuid[16]
Device UUID
uint16_t oob_info
Device OOB Info ADD_DEV_START_PROV_NOW_FLAG shall not be set if the bearer has both
PB-ADV and PB-GATT enabled

Provisioning Bearer
struct esp_ble_mesh_device_delete_t
Information of the device which is going to be deleted.
Public Members
Device address
Device address type
uint8_t uuid[16]
Device UUID
uint8_t flag
BIT0: device address; BIT1: device UUID
struct esp_ble_mesh_prov_data_info_t
Information of the provisioner which is going to be updated.
Public Members
uint16_t net_idx
NetKey Index
uint8_t flags
Flags
uint32_t iv_index
IV Index
uint8_t flag
BIT0: net_idx; BIT1: flags; BIT2: iv_index
struct esp_ble_mesh_node_t
Information of the provisioned node
Public Members
Node device address
Node device address type
uint8_t dev_uuid[16]
Device UUID
uint16_t oob_info
Node OOB information
Node unicast address
uint8_t element_num
Node element number
uint16_t net_idx
Node NetKey Index

uint8_t flags
Node key refresh flag and iv update flag
uint32_t iv_index
Node IV Index
uint8_t dev_key[16]
Node device key
char name[ESP_BLE_MESH_NODE_NAME_MAX_LEN + 1]
Node name
uint16_t comp_length
Length of Composition Data
uint8_t *comp_data
Value of Composition Data
struct esp_ble_mesh_fast_prov_info_t
Context of fast provisioning which need to be set.
Public Members
uint16_t unicast_min
Minimum unicast address used for fast provisioning
uint16_t unicast_max
Maximum unicast address used for fast provisioning
uint16_t net_idx
Netkey index used for fast provisioning
uint8_t flags
Flags used for fast provisioning
uint32_t iv_index
IV Index used for fast provisioning
uint8_t offset
Offset of the UUID to be compared
uint8_t match_len
Length of the UUID to be compared
uint8_t match_val[16]
Value of UUID to be compared
struct esp_ble_mesh_heartbeat_filter_info_t
Context of Provisioner heartbeat filter information to be set
Public Members
uint16_t hb_src
Heartbeat source address (unicast address)
uint16_t hb_dst
Heartbeat destination address (unicast address or group address)
struct esp_ble_mesh_client_op_pair_t
BLE Mesh client models related definitions.
Client model Get/Set message opcode and corresponding Status message opcode

Public Members
uint32_t cli_op
The client message opcode
uint32_t status_op
The server status opcode corresponding to the client message opcode
struct esp_ble_mesh_client_t
Client Model user data context.
Public Members
Pointer to the client model. Initialized by the stack.
int op_pair_size
Size of the op_pair
const esp_ble_mesh_client_op_pair_t *op_pair
Table containing get/set message opcode and corresponding status message opcode
uint32_t publish_status
Callback used to handle the received unsolicited message. Initialized by the stack.
void *internal_data
Pointer to the internal data of client model
uint8_t msg_role
Role of the device (Node/Provisioner) that is going to send messages
struct esp_ble_mesh_client_common_param_t
Common parameters of the messages sent by Client Model.
Public Members
esp_ble_mesh_opcode_t opcode
Message opcode
Pointer to the client model structure
esp_ble_mesh_msg_ctx_t ctx
The context used to send message
int32_t msg_timeout
Timeout value (ms) to get response to the sent message Note: if using default timeout value in menuconfig,
make sure to set this value to 0
uint8_t msg_role
Role of the device - Node/Provisioner
struct esp_ble_mesh_state_transition_t
Parameters of the server model state transition
Public Functions
BLE_MESH_ATOMIC_DEFINE(flag, ESP_BLE_MESH_SERVER_FLAG_MAX)
Flag used to indicate if the transition timer has been started internally.
If the model which contains esp_ble_mesh_state_transition_t sets set_auto_rsp to
ESP_BLE_MESH_SERVER_RSP_BY_APP, the handler of the timer shall be initialized by the
users.

And users can use this flag to indicate whether the timer is started or not.
Public Members
bool just_started
Indicate if the state transition has just started
uint8_t trans_time
State transition time
uint8_t remain_time
Remaining time of state transition
uint8_t delay
Delay before starting state transition
uint32_t quo_tt
Duration of each divided transition step
uint32_t counter
Number of steps which the transition duration is divided
uint32_t total_duration
State transition total duration
int64_t start_timestamp
Time when the state transition is started
Timer used for state transition
struct esp_ble_mesh_last_msg_info_t
Parameters of the server model received last same set message.
Public Members
uint8_t tid
Transaction number of the last message
uint16_t src
Source address of the last message
uint16_t dst
Destination address of the last message
int64_t timestamp
Time when the last message is received
struct esp_ble_mesh_server_rsp_ctrl_t
Parameters of the Server Model response control
Public Members
uint8_t get_auto_rsp : 1
BLE Mesh Server Response Option.
1. If get_auto_rsp is set to ESP_BLE_MESH_SERVER_RSP_BY_APP, then the response of Client
Get messages need to be replied by the application;
2. If get_auto_rsp is set to ESP_BLE_MESH_SERVER_AUTO_RSP, then the response of Client Get
messages will be replied by the server models;
3. If set_auto_rsp is set to ESP_BLE_MESH_SERVER_RSP_BY_APP, then the response of Client
Set messages need to be replied by the application;

4. If set_auto_rsp is set to ESP_BLE_MESH_SERVER_AUTO_RSP, then the response of Client Set

messages will be replied by the server models;
5. If status_auto_rsp is set to ESP_BLE_MESH_SERVER_RSP_BY_APP, then the response of
Server Status messages need to be replied by the application;
6. If status_auto_rsp is set to ESP_BLE_MESH_SERVER_AUTO_RSP, then the response of Server
Status messages will be replied by the server models;Response control for Client Get messages
uint8_t set_auto_rsp : 1
Response control for Client Set messages
uint8_t status_auto_rsp : 1
Response control for Server Status messages
Macros
ESP_BLE_MESH_SDU_MAX_LEN
< The maximum length of a BLE Mesh message, including Opcode, Payload and TransMIC Length of a short
Mesh MIC.
ESP_BLE_MESH_MIC_SHORT
Length of a long Mesh MIC.
ESP_BLE_MESH_MIC_LONG
The maximum length of a BLE Mesh provisioned node name
ESP_BLE_MESH_NODE_NAME_MAX_LEN
The maximum length of a BLE Mesh unprovisioned device name
ESP_BLE_MESH_DEVICE_NAME_MAX_LEN
The maximum length of settings user id
ESP_BLE_MESH_SETTINGS_UID_SIZE
Invalid settings index
ESP_BLE_MESH_INVALID_SETTINGS_IDX
Define the BLE Mesh octet 16 bytes size
ESP_BLE_MESH_OCTET16_LEN
ESP_BLE_MESH_OCTET8_LEN
ESP_BLE_MESH_CID_NVAL
Special TTL value to request using configured default TTL
ESP_BLE_MESH_TTL_DEFAULT
Maximum allowed TTL value
ESP_BLE_MESH_TTL_MAX
ESP_BLE_MESH_ADDR_UNASSIGNED
ESP_BLE_MESH_ADDR_ALL_NODES
ESP_BLE_MESH_ADDR_PROXIES
ESP_BLE_MESH_ADDR_FRIENDS
ESP_BLE_MESH_ADDR_RELAYS
ESP_BLE_MESH_KEY_UNUSED
ESP_BLE_MESH_KEY_DEV
ESP_BLE_MESH_KEY_PRIMARY
ESP_BLE_MESH_KEY_ANY
Primary Network Key index
ESP_BLE_MESH_NET_PRIMARY
Relay state value

ESP_BLE_MESH_RELAY_DISABLED
ESP_BLE_MESH_RELAY_ENABLED
ESP_BLE_MESH_RELAY_NOT_SUPPORTED
Beacon state value
ESP_BLE_MESH_BEACON_DISABLED
ESP_BLE_MESH_BEACON_ENABLED
GATT Proxy state value
ESP_BLE_MESH_GATT_PROXY_DISABLED
ESP_BLE_MESH_GATT_PROXY_ENABLED
ESP_BLE_MESH_GATT_PROXY_NOT_SUPPORTED
Friend state value
ESP_BLE_MESH_FRIEND_DISABLED
ESP_BLE_MESH_FRIEND_ENABLED
ESP_BLE_MESH_FRIEND_NOT_SUPPORTED
Node identity state value
ESP_BLE_MESH_NODE_IDENTITY_STOPPED
ESP_BLE_MESH_NODE_IDENTITY_RUNNING
ESP_BLE_MESH_NODE_IDENTITY_NOT_SUPPORTED
Supported features
ESP_BLE_MESH_FEATURE_RELAY
ESP_BLE_MESH_FEATURE_PROXY
ESP_BLE_MESH_FEATURE_FRIEND
ESP_BLE_MESH_FEATURE_LOW_POWER
ESP_BLE_MESH_FEATURE_ALL_SUPPORTED
ESP_BLE_MESH_ADDR_IS_UNICAST(addr)
ESP_BLE_MESH_ADDR_IS_GROUP(addr)
ESP_BLE_MESH_ADDR_IS_VIRTUAL(addr)
ESP_BLE_MESH_ADDR_IS_RFU(addr)
ESP_BLE_MESH_INVALID_NODE_INDEX
ESP_BLE_MESH_TRANSMIT(count, int_ms)
Encode transmission count & interval steps.
Note For example, ESP_BLE_MESH_TRANSMIT(2, 20) means that the message will be sent about
90ms(count is 3, step is 1, interval is 30 ms which includes 10ms of advertising interval random de-
lay).
Return BLE Mesh transmit value that can be used e.g. for the default values of the Configuration Model data.
Parameters
• count: Number of retransmissions (first transmission is excluded).
• int_ms: Interval steps in milliseconds. Must be greater than 0 and a multiple of 10.
ESP_BLE_MESH_GET_TRANSMIT_COUNT(transmit)
Decode transmit count from a transmit value.
Return Transmission count (actual transmissions equal to N + 1).
Parameters
• transmit: Encoded transmit count & interval value.

ESP_BLE_MESH_GET_TRANSMIT_INTERVAL(transmit)
Decode transmit interval from a transmit value.
Return Transmission interval in milliseconds.
Parameters
• transmit: Encoded transmit count & interval value.
ESP_BLE_MESH_PUBLISH_TRANSMIT(count, int_ms)
Encode Publish Retransmit count & interval steps.
Return BLE Mesh transmit value that can be used e.g. for the default values of the Configuration Model data.
Parameters
• count: Number of retransmissions (first transmission is excluded).
• int_ms: Interval steps in milliseconds. Must be greater than 0 and a multiple of 50.
ESP_BLE_MESH_GET_PUBLISH_TRANSMIT_COUNT(transmit)
Decode Publish Retransmit count from a given value.
Return Retransmission count (actual transmissions equal to N + 1).
Parameters
• transmit: Encoded Publish Retransmit count & interval value.
ESP_BLE_MESH_GET_PUBLISH_TRANSMIT_INTERVAL(transmit)
Decode Publish Retransmit interval from a given value.
Callbacks which are not needed to be initialized by users (set with 0 and will be initialized internally)
Return Transmission interval in milliseconds.
Parameters
• transmit: Encoded Publish Retransmit count & interval value.
ESP_BLE_MESH_PROV_STATIC_OOB_MAX_LEN
Maximum length of string used by Output OOB authentication
ESP_BLE_MESH_PROV_OUTPUT_OOB_MAX_LEN
Maximum length of string used by Output OOB authentication
ESP_BLE_MESH_PROV_INPUT_OOB_MAX_LEN
Macros used to define message opcode
ESP_BLE_MESH_MODEL_OP_1(b0)
ESP_BLE_MESH_MODEL_OP_2(b0, b1)
ESP_BLE_MESH_MODEL_OP_3(b0, cid)
This macro is associated with BLE_MESH_MODEL_CB in mesh_access.h
ESP_BLE_MESH_SIG_MODEL(_id, _op, _pub, _user_data)
This macro is associated with BLE_MESH_MODEL_VND_CB in mesh_access.h
ESP_BLE_MESH_VENDOR_MODEL(_company, _id, _op, _pub, _user_data)
ESP_BLE_MESH_ELEMENT(_loc, _mods, _vnd_mods)
Helper to define a BLE Mesh element within an array.
In case the element has no SIG or Vendor models, the helper macro ESP_BLE_MESH_MODEL_NONE can
be given instead.
Note This macro is associated with BLE_MESH_ELEM in mesh_access.h
Parameters
• _loc: Location Descriptor.
• _mods: Array of SIG models.
• _vnd_mods: Array of vendor models.
ESP_BLE_MESH_PROV(uuid, sta_val, sta_val_len, out_size, out_act, in_size, in_act)
BT_OCTET32_LEN
BD_ADDR_LEN

ESP_BLE_MESH_ADDR_TYPE_PUBLIC
ESP_BLE_MESH_ADDR_TYPE_RANDOM
ESP_BLE_MESH_ADDR_TYPE_RPA_PUBLIC
ESP_BLE_MESH_ADDR_TYPE_RPA_RANDOM
ESP_BLE_MESH_MODEL_PUB_DEFINE(_name, _msg_len, _role)
Define a model publication context.
Parameters
• _name: Variable name given to the context.
• _msg_len: Length of the publication message.
• _role: Role of the device which contains the model.
ESP_BLE_MESH_MODEL_OP(_opcode, _min_len)
Define a model operation context.
Parameters
• _opcode: Message opcode.
• _min_len: Message minimum length.
ESP_BLE_MESH_MODEL_OP_END
Define the terminator for the model operation table. Each model operation struct array must use this terminator
as the end tag of the operation unit.
ESP_BLE_MESH_MODEL_NONE
Helper to define an empty model array. This structure is associated with BLE_MESH_MODEL_NONE in
mesh_access.h
ADD_DEV_RM_AFTER_PROV_FLAG
Device will be removed from queue after provisioned successfully
ADD_DEV_START_PROV_NOW_FLAG
Start provisioning device immediately
ADD_DEV_FLUSHABLE_DEV_FLAG
Device can be remove when queue is full and new device is going to added
DEL_DEV_ADDR_FLAG
DEL_DEV_UUID_FLAG
PROV_DATA_NET_IDX_FLAG
PROV_DATA_FLAGS_FLAG
PROV_DATA_IV_INDEX_FLAG
ESP_BLE_MESH_HEARTBEAT_FILTER_ACCEPTLIST
ESP_BLE_MESH_HEARTBEAT_FILTER_REJECTLIST
Provisioner heartbeat filter operation
ESP_BLE_MESH_HEARTBEAT_FILTER_ADD
ESP_BLE_MESH_HEARTBEAT_FILTER_REMOVE
ESP_BLE_MESH_MODEL_ID_CONFIG_SRV
BLE Mesh models related Model ID and Opcode definitions.
< Foundation Models
ESP_BLE_MESH_MODEL_ID_CONFIG_CLI
ESP_BLE_MESH_MODEL_ID_HEALTH_SRV
ESP_BLE_MESH_MODEL_ID_HEALTH_CLI
Models from the Mesh Model Specification
ESP_BLE_MESH_MODEL_ID_GEN_ONOFF_SRV

ESP_BLE_MESH_MODEL_ID_GEN_ONOFF_CLI
ESP_BLE_MESH_MODEL_ID_GEN_LEVEL_SRV
ESP_BLE_MESH_MODEL_ID_GEN_LEVEL_CLI
ESP_BLE_MESH_MODEL_ID_GEN_DEF_TRANS_TIME_SRV
ESP_BLE_MESH_MODEL_ID_GEN_DEF_TRANS_TIME_CLI
ESP_BLE_MESH_MODEL_ID_GEN_POWER_ONOFF_SRV
ESP_BLE_MESH_MODEL_ID_GEN_POWER_ONOFF_SETUP_SRV
ESP_BLE_MESH_MODEL_ID_GEN_POWER_ONOFF_CLI
ESP_BLE_MESH_MODEL_ID_GEN_POWER_LEVEL_SRV
ESP_BLE_MESH_MODEL_ID_GEN_POWER_LEVEL_SETUP_SRV
ESP_BLE_MESH_MODEL_ID_GEN_POWER_LEVEL_CLI
ESP_BLE_MESH_MODEL_ID_GEN_BATTERY_SRV
ESP_BLE_MESH_MODEL_ID_GEN_BATTERY_CLI
ESP_BLE_MESH_MODEL_ID_GEN_LOCATION_SRV
ESP_BLE_MESH_MODEL_ID_GEN_LOCATION_SETUP_SRV
ESP_BLE_MESH_MODEL_ID_GEN_LOCATION_CLI
ESP_BLE_MESH_MODEL_ID_GEN_ADMIN_PROP_SRV
ESP_BLE_MESH_MODEL_ID_GEN_MANUFACTURER_PROP_SRV
ESP_BLE_MESH_MODEL_ID_GEN_USER_PROP_SRV
ESP_BLE_MESH_MODEL_ID_GEN_CLIENT_PROP_SRV
ESP_BLE_MESH_MODEL_ID_GEN_PROP_CLI
ESP_BLE_MESH_MODEL_ID_SENSOR_SRV
ESP_BLE_MESH_MODEL_ID_SENSOR_SETUP_SRV
ESP_BLE_MESH_MODEL_ID_SENSOR_CLI
ESP_BLE_MESH_MODEL_ID_TIME_SRV
ESP_BLE_MESH_MODEL_ID_TIME_SETUP_SRV
ESP_BLE_MESH_MODEL_ID_TIME_CLI
ESP_BLE_MESH_MODEL_ID_SCENE_SRV
ESP_BLE_MESH_MODEL_ID_SCENE_SETUP_SRV
ESP_BLE_MESH_MODEL_ID_SCENE_CLI
ESP_BLE_MESH_MODEL_ID_SCHEDULER_SRV
ESP_BLE_MESH_MODEL_ID_SCHEDULER_SETUP_SRV
ESP_BLE_MESH_MODEL_ID_SCHEDULER_CLI
ESP_BLE_MESH_MODEL_ID_LIGHT_LIGHTNESS_SRV
ESP_BLE_MESH_MODEL_ID_LIGHT_LIGHTNESS_SETUP_SRV
ESP_BLE_MESH_MODEL_ID_LIGHT_LIGHTNESS_CLI
ESP_BLE_MESH_MODEL_ID_LIGHT_CTL_SRV
ESP_BLE_MESH_MODEL_ID_LIGHT_CTL_SETUP_SRV
ESP_BLE_MESH_MODEL_ID_LIGHT_CTL_CLI

ESP_BLE_MESH_MODEL_ID_LIGHT_CTL_TEMP_SRV
ESP_BLE_MESH_MODEL_ID_LIGHT_HSL_SRV
ESP_BLE_MESH_MODEL_ID_LIGHT_HSL_SETUP_SRV
ESP_BLE_MESH_MODEL_ID_LIGHT_HSL_CLI
ESP_BLE_MESH_MODEL_ID_LIGHT_HSL_HUE_SRV
ESP_BLE_MESH_MODEL_ID_LIGHT_HSL_SAT_SRV
ESP_BLE_MESH_MODEL_ID_LIGHT_XYL_SRV
ESP_BLE_MESH_MODEL_ID_LIGHT_XYL_SETUP_SRV
ESP_BLE_MESH_MODEL_ID_LIGHT_XYL_CLI
ESP_BLE_MESH_MODEL_ID_LIGHT_LC_SRV
ESP_BLE_MESH_MODEL_ID_LIGHT_LC_SETUP_SRV
ESP_BLE_MESH_MODEL_ID_LIGHT_LC_CLI
ESP_BLE_MESH_MODEL_OP_BEACON_GET
Config Beacon Get
ESP_BLE_MESH_MODEL_OP_COMPOSITION_DATA_GET
Config Composition Data Get
ESP_BLE_MESH_MODEL_OP_DEFAULT_TTL_GET
Config Default TTL Get
ESP_BLE_MESH_MODEL_OP_GATT_PROXY_GET
Config GATT Proxy Get
ESP_BLE_MESH_MODEL_OP_RELAY_GET
Config Relay Get
ESP_BLE_MESH_MODEL_OP_MODEL_PUB_GET
Config Model Publication Get
ESP_BLE_MESH_MODEL_OP_FRIEND_GET
Config Friend Get
ESP_BLE_MESH_MODEL_OP_HEARTBEAT_PUB_GET
Config Heartbeat Publication Get
ESP_BLE_MESH_MODEL_OP_HEARTBEAT_SUB_GET
Config Heartbeat Subscription Get
ESP_BLE_MESH_MODEL_OP_NET_KEY_GET
Config NetKey Get
ESP_BLE_MESH_MODEL_OP_APP_KEY_GET
Config AppKey Get
ESP_BLE_MESH_MODEL_OP_NODE_IDENTITY_GET
Config Node Identity Get
ESP_BLE_MESH_MODEL_OP_SIG_MODEL_SUB_GET
Config SIG Model Subscription Get
ESP_BLE_MESH_MODEL_OP_VENDOR_MODEL_SUB_GET
Config Vendor Model Subscription Get
ESP_BLE_MESH_MODEL_OP_SIG_MODEL_APP_GET
Config SIG Model App Get
ESP_BLE_MESH_MODEL_OP_VENDOR_MODEL_APP_GET
Config Vendor Model App Get

ESP_BLE_MESH_MODEL_OP_KEY_REFRESH_PHASE_GET
Config Key Refresh Phase Get
ESP_BLE_MESH_MODEL_OP_LPN_POLLTIMEOUT_GET
Config Low Power Node PollTimeout Get
ESP_BLE_MESH_MODEL_OP_NETWORK_TRANSMIT_GET
Config Network Transmit Get
ESP_BLE_MESH_MODEL_OP_BEACON_SET
Config Beacon Set
ESP_BLE_MESH_MODEL_OP_DEFAULT_TTL_SET
Config Default TTL Set
ESP_BLE_MESH_MODEL_OP_GATT_PROXY_SET
Config GATT Proxy Set
ESP_BLE_MESH_MODEL_OP_RELAY_SET
Config Relay Set
ESP_BLE_MESH_MODEL_OP_MODEL_PUB_SET
Config Model Publication Set
ESP_BLE_MESH_MODEL_OP_MODEL_SUB_ADD
Config Model Subscription Add
ESP_BLE_MESH_MODEL_OP_MODEL_SUB_VIRTUAL_ADDR_ADD
Config Model Subscription Virtual Address Add
ESP_BLE_MESH_MODEL_OP_MODEL_SUB_DELETE
Config Model Subscription Delete
ESP_BLE_MESH_MODEL_OP_MODEL_SUB_VIRTUAL_ADDR_DELETE
Config Model Subscription Virtual Address Delete
ESP_BLE_MESH_MODEL_OP_MODEL_SUB_OVERWRITE
Config Model Subscription Overwrite
ESP_BLE_MESH_MODEL_OP_MODEL_SUB_VIRTUAL_ADDR_OVERWRITE
Config Model Subscription Virtual Address Overwrite
ESP_BLE_MESH_MODEL_OP_NET_KEY_ADD
Config NetKey Add
ESP_BLE_MESH_MODEL_OP_APP_KEY_ADD
Config AppKey Add
ESP_BLE_MESH_MODEL_OP_MODEL_APP_BIND
Config Model App Bind
ESP_BLE_MESH_MODEL_OP_NODE_RESET
Config Node Reset
ESP_BLE_MESH_MODEL_OP_FRIEND_SET
Config Friend Set
ESP_BLE_MESH_MODEL_OP_HEARTBEAT_PUB_SET
Config Heartbeat Publication Set
ESP_BLE_MESH_MODEL_OP_HEARTBEAT_SUB_SET
Config Heartbeat Subscription Set
ESP_BLE_MESH_MODEL_OP_NET_KEY_UPDATE
Config NetKey Update
ESP_BLE_MESH_MODEL_OP_NET_KEY_DELETE
Config NetKey Delete

ESP_BLE_MESH_MODEL_OP_APP_KEY_UPDATE
Config AppKey Update
ESP_BLE_MESH_MODEL_OP_APP_KEY_DELETE
Config AppKey Delete
ESP_BLE_MESH_MODEL_OP_NODE_IDENTITY_SET
Config Node Identity Set
ESP_BLE_MESH_MODEL_OP_KEY_REFRESH_PHASE_SET
Config Key Refresh Phase Set
ESP_BLE_MESH_MODEL_OP_MODEL_PUB_VIRTUAL_ADDR_SET
Config Model Publication Virtual Address Set
ESP_BLE_MESH_MODEL_OP_MODEL_SUB_DELETE_ALL
Config Model Subscription Delete All
ESP_BLE_MESH_MODEL_OP_MODEL_APP_UNBIND
Config Model App Unbind
ESP_BLE_MESH_MODEL_OP_NETWORK_TRANSMIT_SET
Config Network Transmit Set
ESP_BLE_MESH_MODEL_OP_BEACON_STATUS
ESP_BLE_MESH_MODEL_OP_COMPOSITION_DATA_STATUS
ESP_BLE_MESH_MODEL_OP_DEFAULT_TTL_STATUS
ESP_BLE_MESH_MODEL_OP_GATT_PROXY_STATUS
ESP_BLE_MESH_MODEL_OP_RELAY_STATUS
ESP_BLE_MESH_MODEL_OP_MODEL_PUB_STATUS
ESP_BLE_MESH_MODEL_OP_MODEL_SUB_STATUS
ESP_BLE_MESH_MODEL_OP_SIG_MODEL_SUB_LIST
ESP_BLE_MESH_MODEL_OP_VENDOR_MODEL_SUB_LIST
ESP_BLE_MESH_MODEL_OP_NET_KEY_STATUS
ESP_BLE_MESH_MODEL_OP_NET_KEY_LIST
ESP_BLE_MESH_MODEL_OP_APP_KEY_STATUS
ESP_BLE_MESH_MODEL_OP_APP_KEY_LIST
ESP_BLE_MESH_MODEL_OP_NODE_IDENTITY_STATUS
ESP_BLE_MESH_MODEL_OP_MODEL_APP_STATUS
ESP_BLE_MESH_MODEL_OP_SIG_MODEL_APP_LIST
ESP_BLE_MESH_MODEL_OP_VENDOR_MODEL_APP_LIST
ESP_BLE_MESH_MODEL_OP_NODE_RESET_STATUS
ESP_BLE_MESH_MODEL_OP_FRIEND_STATUS
ESP_BLE_MESH_MODEL_OP_KEY_REFRESH_PHASE_STATUS
ESP_BLE_MESH_MODEL_OP_HEARTBEAT_PUB_STATUS
ESP_BLE_MESH_MODEL_OP_HEARTBEAT_SUB_STATUS
ESP_BLE_MESH_MODEL_OP_LPN_POLLTIMEOUT_STATUS
ESP_BLE_MESH_MODEL_OP_NETWORK_TRANSMIT_STATUS
ESP_BLE_MESH_CFG_STATUS_SUCCESS
ESP_BLE_MESH_CFG_STATUS_INVALID_ADDRESS

ESP_BLE_MESH_CFG_STATUS_INVALID_MODEL
ESP_BLE_MESH_CFG_STATUS_INVALID_APPKEY
ESP_BLE_MESH_CFG_STATUS_INVALID_NETKEY
ESP_BLE_MESH_CFG_STATUS_INSUFFICIENT_RESOURCES
ESP_BLE_MESH_CFG_STATUS_KEY_INDEX_ALREADY_STORED
ESP_BLE_MESH_CFG_STATUS_INVALID_PUBLISH_PARAMETERS
ESP_BLE_MESH_CFG_STATUS_NOT_A_SUBSCRIBE_MODEL
ESP_BLE_MESH_CFG_STATUS_STORAGE_FAILURE
ESP_BLE_MESH_CFG_STATUS_FEATURE_NOT_SUPPORTED
ESP_BLE_MESH_CFG_STATUS_CANNOT_UPDATE
ESP_BLE_MESH_CFG_STATUS_CANNOT_REMOVE
ESP_BLE_MESH_CFG_STATUS_CANNOT_BIND
ESP_BLE_MESH_CFG_STATUS_TEMP_UNABLE_TO_CHANGE_STATE
ESP_BLE_MESH_CFG_STATUS_CANNOT_SET
ESP_BLE_MESH_CFG_STATUS_UNSPECIFIED_ERROR
ESP_BLE_MESH_CFG_STATUS_INVALID_BINDING
ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_GET
Health Fault Get
ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_GET
Health Period Get
ESP_BLE_MESH_MODEL_OP_ATTENTION_GET
Health Attention Get
ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_CLEAR
Health Fault Clear
ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_CLEAR_UNACK
Health Fault Clear Unacknowledged
ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_TEST
Health Fault Test
ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_TEST_UNACK
Health Fault Test Unacknowledged
ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_SET
Health Period Set
ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_SET_UNACK
Health Period Set Unacknowledged
ESP_BLE_MESH_MODEL_OP_ATTENTION_SET
Health Attention Set
ESP_BLE_MESH_MODEL_OP_ATTENTION_SET_UNACK
Health Attention Set Unacknowledged
ESP_BLE_MESH_MODEL_OP_HEALTH_CURRENT_STATUS
ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_STATUS
ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_STATUS
ESP_BLE_MESH_MODEL_OP_ATTENTION_STATUS
ESP_BLE_MESH_MODEL_OP_GEN_ONOFF_GET

ESP_BLE_MESH_MODEL_OP_GEN_ONOFF_SET
ESP_BLE_MESH_MODEL_OP_GEN_ONOFF_SET_UNACK
ESP_BLE_MESH_MODEL_OP_GEN_ONOFF_STATUS
Generic Level Message Opcode
ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_GET
ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_SET
ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_SET_UNACK
ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_STATUS
ESP_BLE_MESH_MODEL_OP_GEN_DELTA_SET
ESP_BLE_MESH_MODEL_OP_GEN_DELTA_SET_UNACK
ESP_BLE_MESH_MODEL_OP_GEN_MOVE_SET
ESP_BLE_MESH_MODEL_OP_GEN_MOVE_SET_UNACK
Generic Default Transition Time Message Opcode
ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIME_GET
ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIME_SET
ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIME_SET_UNACK
ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIME_STATUS
Generic Power OnOff Message Opcode
ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_GET
ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_STATUS
Generic Power OnOff Setup Message Opcode
ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_SET
ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_SET_UNACK
Generic Power Level Message Opcode
ESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_GET
ESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_SET
ESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_SET_UNACK
ESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_STATUS
ESP_BLE_MESH_MODEL_OP_GEN_POWER_LAST_GET
ESP_BLE_MESH_MODEL_OP_GEN_POWER_LAST_STATUS
ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULT_GET
ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULT_STATUS
ESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_GET
ESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_STATUS
Generic Power Level Setup Message Opcode
ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULT_SET
ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULT_SET_UNACK
ESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_SET
ESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_SET_UNACK
Generic Battery Message Opcode
ESP_BLE_MESH_MODEL_OP_GEN_BATTERY_GET

ESP_BLE_MESH_MODEL_OP_GEN_BATTERY_STATUS
Generic Location Message Opcode
ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_GET
ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_STATUS
ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_GET
ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_STATUS
Generic Location Setup Message Opcode
ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_SET
ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_SET_UNACK
ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_SET
ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_SET_UNACK
Generic Manufacturer Property Message Opcode
ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTIES_GET
ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTIES_STATUS
ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_GET
ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_SET
ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_SET_UNACK
ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_STATUS
Generic Admin Property Message Opcode
ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTIES_GET
ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTIES_STATUS
ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_GET
ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_SET
ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_SET_UNACK
ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_STATUS
Generic User Property Message Opcode
ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTIES_GET
ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTIES_STATUS
ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTY_GET
ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTY_SET
ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTY_SET_UNACK
ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTY_STATUS
Generic Client Property Message Opcode
ESP_BLE_MESH_MODEL_OP_GEN_CLIENT_PROPERTIES_GET
ESP_BLE_MESH_MODEL_OP_GEN_CLIENT_PROPERTIES_STATUS
ESP_BLE_MESH_MODEL_OP_SENSOR_DESCRIPTOR_GET
ESP_BLE_MESH_MODEL_OP_SENSOR_DESCRIPTOR_STATUS
ESP_BLE_MESH_MODEL_OP_SENSOR_GET
ESP_BLE_MESH_MODEL_OP_SENSOR_STATUS
ESP_BLE_MESH_MODEL_OP_SENSOR_COLUMN_GET
ESP_BLE_MESH_MODEL_OP_SENSOR_COLUMN_STATUS

ESP_BLE_MESH_MODEL_OP_SENSOR_SERIES_GET
ESP_BLE_MESH_MODEL_OP_SENSOR_SERIES_STATUS
Sensor Setup Message Opcode
ESP_BLE_MESH_MODEL_OP_SENSOR_CADENCE_GET
ESP_BLE_MESH_MODEL_OP_SENSOR_CADENCE_SET
ESP_BLE_MESH_MODEL_OP_SENSOR_CADENCE_SET_UNACK
ESP_BLE_MESH_MODEL_OP_SENSOR_CADENCE_STATUS
ESP_BLE_MESH_MODEL_OP_SENSOR_SETTINGS_GET
ESP_BLE_MESH_MODEL_OP_SENSOR_SETTINGS_STATUS
ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_GET
ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_SET
ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_SET_UNACK
ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_STATUS
ESP_BLE_MESH_MODEL_OP_TIME_GET
ESP_BLE_MESH_MODEL_OP_TIME_SET
ESP_BLE_MESH_MODEL_OP_TIME_STATUS
ESP_BLE_MESH_MODEL_OP_TIME_ROLE_GET
ESP_BLE_MESH_MODEL_OP_TIME_ROLE_SET
ESP_BLE_MESH_MODEL_OP_TIME_ROLE_STATUS
ESP_BLE_MESH_MODEL_OP_TIME_ZONE_GET
ESP_BLE_MESH_MODEL_OP_TIME_ZONE_SET
ESP_BLE_MESH_MODEL_OP_TIME_ZONE_STATUS
ESP_BLE_MESH_MODEL_OP_TAI_UTC_DELTA_GET
ESP_BLE_MESH_MODEL_OP_TAI_UTC_DELTA_SET
ESP_BLE_MESH_MODEL_OP_TAI_UTC_DELTA_STATUS
Scene Message Opcode
ESP_BLE_MESH_MODEL_OP_SCENE_GET
ESP_BLE_MESH_MODEL_OP_SCENE_RECALL
ESP_BLE_MESH_MODEL_OP_SCENE_RECALL_UNACK
ESP_BLE_MESH_MODEL_OP_SCENE_STATUS
ESP_BLE_MESH_MODEL_OP_SCENE_REGISTER_GET
ESP_BLE_MESH_MODEL_OP_SCENE_REGISTER_STATUS
Scene Setup Message Opcode
ESP_BLE_MESH_MODEL_OP_SCENE_STORE
ESP_BLE_MESH_MODEL_OP_SCENE_STORE_UNACK
ESP_BLE_MESH_MODEL_OP_SCENE_DELETE
ESP_BLE_MESH_MODEL_OP_SCENE_DELETE_UNACK
Scheduler Message Opcode
ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_GET
ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_STATUS

ESP_BLE_MESH_MODEL_OP_SCHEDULER_GET
ESP_BLE_MESH_MODEL_OP_SCHEDULER_STATUS
Scheduler Setup Message Opcode
ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_SET
ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_SET_UNACK
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_SET
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_SET_UNACK
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_STATUS
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LINEAR_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LINEAR_SET
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LINEAR_SET_UNACK
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LINEAR_STATUS
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LAST_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LAST_STATUS
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEFAULT_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEFAULT_STATUS
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_RANGE_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_RANGE_STATUS
Light Lightness Setup Message Opcode
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEFAULT_SET
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEFAULT_SET_UNACK
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_RANGE_SET
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_RANGE_SET_UNACK
Light CTL Message Opcode
ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_SET
ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_SET_UNACK
ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_STATUS
ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_RANGE_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_RANGE_STATUS
ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_SET
ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_SET_UNACK
ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_STATUS
ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULT_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULT_STATUS
Light CTL Setup Message Opcode
ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULT_SET
ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULT_SET_UNACK

ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_RANGE_SET
ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_RANGE_SET_UNACK
Light HSL Message Opcode
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_SET
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_SET_UNACK
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_STATUS
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SATURATION_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SATURATION_SET
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SATURATION_SET_UNACK
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SATURATION_STATUS
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SET
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SET_UNACK
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_STATUS
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_TARGET_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_TARGET_STATUS
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULT_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULT_STATUS
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_STATUS
Light HSL Setup Message Opcode
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULT_SET
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULT_SET_UNACK
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_SET
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_SET_UNACK
Light xyL Message Opcode
ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_SET
ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_SET_UNACK
ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_STATUS
ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_TARGET_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_TARGET_STATUS
ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULT_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULT_STATUS
ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_STATUS
Light xyL Setup Message Opcode
ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULT_SET
ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULT_SET_UNACK

ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_SET
ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_SET_UNACK
Light Control Message Opcode
ESP_BLE_MESH_MODEL_OP_LIGHT_LC_MODE_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_LC_MODE_SET
ESP_BLE_MESH_MODEL_OP_LIGHT_LC_MODE_SET_UNACK
ESP_BLE_MESH_MODEL_OP_LIGHT_LC_MODE_STATUS
ESP_BLE_MESH_MODEL_OP_LIGHT_LC_OM_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_LC_OM_SET
ESP_BLE_MESH_MODEL_OP_LIGHT_LC_OM_SET_UNACK
ESP_BLE_MESH_MODEL_OP_LIGHT_LC_OM_STATUS
ESP_BLE_MESH_MODEL_OP_LIGHT_LC_LIGHT_ONOFF_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_LC_LIGHT_ONOFF_SET
ESP_BLE_MESH_MODEL_OP_LIGHT_LC_LIGHT_ONOFF_SET_UNACK
ESP_BLE_MESH_MODEL_OP_LIGHT_LC_LIGHT_ONOFF_STATUS
ESP_BLE_MESH_MODEL_OP_LIGHT_LC_PROPERTY_GET
ESP_BLE_MESH_MODEL_OP_LIGHT_LC_PROPERTY_SET
ESP_BLE_MESH_MODEL_OP_LIGHT_LC_PROPERTY_SET_UNACK
ESP_BLE_MESH_MODEL_OP_LIGHT_LC_PROPERTY_STATUS
ESP_BLE_MESH_MODEL_STATUS_SUCCESS
ESP_BLE_MESH_MODEL_STATUS_CANNOT_SET_RANGE_MIN
ESP_BLE_MESH_MODEL_STATUS_CANNOT_SET_RANGE_MAX
ESP_BLE_MESH_SERVER_RSP_BY_APP
Response need to be sent in the application
ESP_BLE_MESH_SERVER_AUTO_RSP
Response will be sent internally
Type Definitions
typedef uint8_t esp_ble_mesh_octet16_t[ESP_BLE_MESH_OCTET16_LEN]
Define the BLE Mesh octet 8 bytes size
typedef uint8_t esp_ble_mesh_octet8_t[ESP_BLE_MESH_OCTET8_LEN]
Invalid Company ID
typedef uint32_t esp_ble_mesh_cb_t
typedef uint8_t UINT8
typedef UINT8 BT_OCTET32[BT_OCTET32_LEN]
typedef uint8_t BD_ADDR[BD_ADDR_LEN]
typedef uint8_t esp_ble_mesh_bd_addr_t[BD_ADDR_LEN]
typedef uint8_t esp_ble_mesh_addr_type_t
BLE device address type.

typedef struct esp_ble_mesh_model esp_ble_mesh_model_t

typedef uint8_t esp_ble_mesh_dev_add_flag_t
typedef uint32_t esp_ble_mesh_opcode_config_client_get_t
esp_ble_mesh_opcode_config_client_get_t belongs to esp_ble_mesh_opcode_t, this typedef is only used to
locate the opcodes used by esp_ble_mesh_config_client_get_state. The following opcodes will only be used in
the esp_ble_mesh_config_client_get_state function.
typedef uint32_t esp_ble_mesh_opcode_config_client_set_t
esp_ble_mesh_opcode_config_client_set_t belongs to esp_ble_mesh_opcode_t, this typedef is only used to
locate the opcodes used by esp_ble_mesh_config_client_set_state. The following opcodes will only be used in
the esp_ble_mesh_config_client_set_state function.
typedef uint32_t esp_ble_mesh_opcode_config_status_t
esp_ble_mesh_opcode_config_status_t belongs to esp_ble_mesh_opcode_t, this typedef is only used to locate
the opcodes used by the Config Model messages The following opcodes are used by the BLE Mesh Config
Server Model internally to respond to the Config Client Model s request messages.
typedef uint8_t esp_ble_mesh_cfg_status_t
This typedef is only used to indicate the status code contained in some of the Configuration Server Model status
message.
typedef uint32_t esp_ble_mesh_opcode_health_client_get_t
esp_ble_mesh_opcode_health_client_get_t belongs to esp_ble_mesh_opcode_t, this typedef is only used to
locate the opcodes used by esp_ble_mesh_health_client_get_state. The following opcodes will only be used in
the esp_ble_mesh_health_client_get_state function.
typedef uint32_t esp_ble_mesh_opcode_health_client_set_t
esp_ble_mesh_opcode_health_client_set_t belongs to esp_ble_mesh_opcode_t, this typedef is only used to
locate the opcodes used by esp_ble_mesh_health_client_set_state. The following opcodes will only be used in
the esp_ble_mesh_health_client_set_state function.
typedef uint32_t esp_ble_mesh_health_model_status_t
esp_ble_mesh_health_model_status_t belongs to esp_ble_mesh_opcode_t, this typedef is only used to locate
the opcodes used by the Health Model messages. The following opcodes are used by the BLE Mesh Health
Server Model internally to respond to the Health Client Model s request messages.
typedef uint32_t esp_ble_mesh_generic_message_opcode_t
esp_ble_mesh_generic_message_opcode_t belongs to esp_ble_mesh_opcode_t, this typedef is
only used to locate the opcodes used by functions esp_ble_mesh_generic_client_get_state &
esp_ble_mesh_generic_client_set_state.Generic OnOff Message Opcode
typedef uint32_t esp_ble_mesh_sensor_message_opcode_t
esp_ble_mesh_sensor_message_opcode_t belongs to esp_ble_mesh_opcode_t, this typedef is
only used to locate the opcodes used by functions esp_ble_mesh_sensor_client_get_state &
esp_ble_mesh_sensor_client_set_state.Sensor Message Opcode
typedef uint32_t esp_ble_mesh_time_scene_message_opcode_t
esp_ble_mesh_time_scene_message_opcode_t belongs to esp_ble_mesh_opcode_t, this typedef is
only used to locate the opcodes used by functions esp_ble_mesh_time_scene_client_get_state &
esp_ble_mesh_time_scene_client_set_state.Time Message Opcode
typedef uint32_t esp_ble_mesh_light_message_opcode_t
esp_ble_mesh_light_message_opcode_t belongs to esp_ble_mesh_opcode_t, this typedef is
only used to locate the opcodes used by functions esp_ble_mesh_light_client_get_state &
esp_ble_mesh_light_client_set_state.Light Lightness Message Opcode
typedef uint32_t esp_ble_mesh_opcode_t
End of defines of esp_ble_mesh_opcode_t
typedef uint8_t esp_ble_mesh_model_status_t
This typedef is only used to indicate the status code contained in some of the server models (e.g. Generic
Server Model) status message.

Enumerations
enum esp_ble_mesh_cb_type_t
Values:
ESP_BLE_MESH_TYPE_PROV_CB
ESP_BLE_MESH_TYPE_OUTPUT_NUM_CB
ESP_BLE_MESH_TYPE_OUTPUT_STR_CB
ESP_BLE_MESH_TYPE_INTPUT_CB
ESP_BLE_MESH_TYPE_LINK_OPEN_CB
ESP_BLE_MESH_TYPE_LINK_CLOSE_CB
ESP_BLE_MESH_TYPE_COMPLETE_CB
ESP_BLE_MESH_TYPE_RESET_CB
enum esp_ble_mesh_oob_method_t
Values:
ESP_BLE_MESH_NO_OOB
ESP_BLE_MESH_STATIC_OOB
ESP_BLE_MESH_OUTPUT_OOB
ESP_BLE_MESH_INPUT_OOB
enum esp_ble_mesh_output_action_t
Values:
ESP_BLE_MESH_NO_OUTPUT = 0
ESP_BLE_MESH_BLINK = BIT(0)
ESP_BLE_MESH_BEEP = BIT(1)
ESP_BLE_MESH_VIBRATE = BIT(2)
ESP_BLE_MESH_DISPLAY_NUMBER = BIT(3)
ESP_BLE_MESH_DISPLAY_STRING = BIT(4)
enum esp_ble_mesh_input_action_t
Values:
ESP_BLE_MESH_NO_INPUT = 0
ESP_BLE_MESH_PUSH = BIT(0)
ESP_BLE_MESH_TWIST = BIT(1)
ESP_BLE_MESH_ENTER_NUMBER = BIT(2)
ESP_BLE_MESH_ENTER_STRING = BIT(3)
enum esp_ble_mesh_prov_bearer_t
Values:
ESP_BLE_MESH_PROV_ADV = BIT(0)
ESP_BLE_MESH_PROV_GATT = BIT(1)
enum esp_ble_mesh_prov_oob_info_t
Values:
ESP_BLE_MESH_PROV_OOB_OTHER = BIT(0)
ESP_BLE_MESH_PROV_OOB_URI = BIT(1)
ESP_BLE_MESH_PROV_OOB_2D_CODE = BIT(2)
ESP_BLE_MESH_PROV_OOB_BAR_CODE = BIT(3)

ESP_BLE_MESH_PROV_OOB_NFC = BIT(4)
ESP_BLE_MESH_PROV_OOB_NUMBER = BIT(5)
ESP_BLE_MESH_PROV_OOB_STRING = BIT(6)
ESP_BLE_MESH_PROV_OOB_ON_BOX = BIT(11)
ESP_BLE_MESH_PROV_OOB_IN_BOX = BIT(12)
ESP_BLE_MESH_PROV_OOB_ON_PAPER = BIT(13)
ESP_BLE_MESH_PROV_OOB_IN_MANUAL = BIT(14)
ESP_BLE_MESH_PROV_OOB_ON_DEV = BIT(15)
enum esp_ble_mesh_dev_role_t
Values:
ROLE_NODE = 0
ROLE_PROVISIONER
ROLE_FAST_PROV
enum esp_ble_mesh_fast_prov_action_t
Values:
FAST_PROV_ACT_NONE
FAST_PROV_ACT_ENTER
FAST_PROV_ACT_SUSPEND
FAST_PROV_ACT_EXIT
FAST_PROV_ACT_MAX
enum esp_ble_mesh_proxy_filter_type_t
Values:
PROXY_FILTER_WHITELIST
PROXY_FILTER_BLACKLIST
enum esp_ble_mesh_prov_cb_event_t
Values:
ESP_BLE_MESH_PROV_REGISTER_COMP_EVT
Initialize BLE Mesh provisioning capabilities and internal data information completion event
ESP_BLE_MESH_NODE_SET_UNPROV_DEV_NAME_COMP_EVT
Set the unprovisioned device name completion event
ESP_BLE_MESH_NODE_PROV_ENABLE_COMP_EVT
Enable node provisioning functionality completion event
ESP_BLE_MESH_NODE_PROV_DISABLE_COMP_EVT
Disable node provisioning functionality completion event
ESP_BLE_MESH_NODE_PROV_LINK_OPEN_EVT
Establish a BLE Mesh link event
ESP_BLE_MESH_NODE_PROV_LINK_CLOSE_EVT
Close a BLE Mesh link event
ESP_BLE_MESH_NODE_PROV_OOB_PUB_KEY_EVT
Generate Node input OOB public key event
ESP_BLE_MESH_NODE_PROV_OUTPUT_NUMBER_EVT
Generate Node Output Number event

ESP_BLE_MESH_NODE_PROV_OUTPUT_STRING_EVT
Generate Node Output String event
ESP_BLE_MESH_NODE_PROV_INPUT_EVT
Event requiring the user to input a number or string
ESP_BLE_MESH_NODE_PROV_COMPLETE_EVT
Provisioning done event
ESP_BLE_MESH_NODE_PROV_RESET_EVT
Provisioning reset event
ESP_BLE_MESH_NODE_PROV_SET_OOB_PUB_KEY_COMP_EVT
Node set oob public key completion event
ESP_BLE_MESH_NODE_PROV_INPUT_NUMBER_COMP_EVT
Node input number completion event
ESP_BLE_MESH_NODE_PROV_INPUT_STRING_COMP_EVT
Node input string completion event
ESP_BLE_MESH_NODE_PROXY_IDENTITY_ENABLE_COMP_EVT
Enable BLE Mesh Proxy Identity advertising completion event
ESP_BLE_MESH_NODE_PROXY_GATT_ENABLE_COMP_EVT
Enable BLE Mesh GATT Proxy Service completion event
ESP_BLE_MESH_NODE_PROXY_GATT_DISABLE_COMP_EVT
Disable BLE Mesh GATT Proxy Service completion event
ESP_BLE_MESH_NODE_ADD_LOCAL_NET_KEY_COMP_EVT
Node add NetKey locally completion event
ESP_BLE_MESH_NODE_ADD_LOCAL_APP_KEY_COMP_EVT
Node add AppKey locally completion event
ESP_BLE_MESH_NODE_BIND_APP_KEY_TO_MODEL_COMP_EVT
Node bind AppKey to model locally completion event
ESP_BLE_MESH_PROVISIONER_PROV_ENABLE_COMP_EVT
Provisioner enable provisioning functionality completion event
ESP_BLE_MESH_PROVISIONER_PROV_DISABLE_COMP_EVT
Provisioner disable provisioning functionality completion event
ESP_BLE_MESH_PROVISIONER_RECV_UNPROV_ADV_PKT_EVT
Provisioner receives unprovisioned device beacon event
ESP_BLE_MESH_PROVISIONER_PROV_READ_OOB_PUB_KEY_EVT
Provisioner read unprovisioned device OOB public key event
ESP_BLE_MESH_PROVISIONER_PROV_INPUT_EVT
Provisioner input value for provisioning procedure event
ESP_BLE_MESH_PROVISIONER_PROV_OUTPUT_EVT
Provisioner output value for provisioning procedure event
ESP_BLE_MESH_PROVISIONER_PROV_LINK_OPEN_EVT
Provisioner establish a BLE Mesh link event
ESP_BLE_MESH_PROVISIONER_PROV_LINK_CLOSE_EVT
Provisioner close a BLE Mesh link event
ESP_BLE_MESH_PROVISIONER_PROV_COMPLETE_EVT
Provisioner provisioning done event
ESP_BLE_MESH_PROVISIONER_ADD_UNPROV_DEV_COMP_EVT
Provisioner add a device to the list which contains devices that are waiting/going to be provisioned com-
pletion event

ESP_BLE_MESH_PROVISIONER_PROV_DEV_WITH_ADDR_COMP_EVT
Provisioner start to provision an unprovisioned device completion event
ESP_BLE_MESH_PROVISIONER_DELETE_DEV_COMP_EVT
Provisioner delete a device from the list, close provisioning link with the device completion event
ESP_BLE_MESH_PROVISIONER_SET_DEV_UUID_MATCH_COMP_EVT
Provisioner set the value to be compared with part of the unprovisioned device UUID completion event
ESP_BLE_MESH_PROVISIONER_SET_PROV_DATA_INFO_COMP_EVT
Provisioner set net_idx/flags/iv_index used for provisioning completion event
ESP_BLE_MESH_PROVISIONER_SET_STATIC_OOB_VALUE_COMP_EVT
Provisioner set static oob value used for provisioning completion event
ESP_BLE_MESH_PROVISIONER_SET_PRIMARY_ELEM_ADDR_COMP_EVT
Provisioner set unicast address of primary element completion event
ESP_BLE_MESH_PROVISIONER_PROV_READ_OOB_PUB_KEY_COMP_EVT
Provisioner read unprovisioned device OOB public key completion event
ESP_BLE_MESH_PROVISIONER_PROV_INPUT_NUMBER_COMP_EVT
Provisioner input number completion event
ESP_BLE_MESH_PROVISIONER_PROV_INPUT_STRING_COMP_EVT
Provisioner input string completion event
ESP_BLE_MESH_PROVISIONER_SET_NODE_NAME_COMP_EVT
Provisioner set node name completion event
ESP_BLE_MESH_PROVISIONER_ADD_LOCAL_APP_KEY_COMP_EVT
Provisioner add local app key completion event
ESP_BLE_MESH_PROVISIONER_UPDATE_LOCAL_APP_KEY_COMP_EVT
Provisioner update local app key completion event
ESP_BLE_MESH_PROVISIONER_BIND_APP_KEY_TO_MODEL_COMP_EVT
Provisioner bind local model with local app key completion event
ESP_BLE_MESH_PROVISIONER_ADD_LOCAL_NET_KEY_COMP_EVT
Provisioner add local network key completion event
ESP_BLE_MESH_PROVISIONER_UPDATE_LOCAL_NET_KEY_COMP_EVT
Provisioner update local network key completion event
ESP_BLE_MESH_PROVISIONER_STORE_NODE_COMP_DATA_COMP_EVT
Provisioner store node composition data completion event
ESP_BLE_MESH_PROVISIONER_DELETE_NODE_WITH_UUID_COMP_EVT
Provisioner delete node with uuid completion event
ESP_BLE_MESH_PROVISIONER_DELETE_NODE_WITH_ADDR_COMP_EVT
Provisioner delete node with unicast address completion event
ESP_BLE_MESH_PROVISIONER_ENABLE_HEARTBEAT_RECV_COMP_EVT
Provisioner start to receive heartbeat message completion event
ESP_BLE_MESH_PROVISIONER_SET_HEARTBEAT_FILTER_TYPE_COMP_EVT
Provisioner set the heartbeat filter type completion event
ESP_BLE_MESH_PROVISIONER_SET_HEARTBEAT_FILTER_INFO_COMP_EVT
Provisioner set the heartbeat filter information completion event
ESP_BLE_MESH_PROVISIONER_RECV_HEARTBEAT_MESSAGE_EVT
Provisioner receive heartbeat message event
ESP_BLE_MESH_PROVISIONER_DRIECT_ERASE_SETTINGS_COMP_EVT
Provisioner directly erase settings completion event

ESP_BLE_MESH_PROVISIONER_OPEN_SETTINGS_WITH_INDEX_COMP_EVT
Provisioner open settings with index completion event
ESP_BLE_MESH_PROVISIONER_OPEN_SETTINGS_WITH_UID_COMP_EVT
Provisioner open settings with user id completion event
ESP_BLE_MESH_PROVISIONER_CLOSE_SETTINGS_WITH_INDEX_COMP_EVT
Provisioner close settings with index completion event
ESP_BLE_MESH_PROVISIONER_CLOSE_SETTINGS_WITH_UID_COMP_EVT
Provisioner close settings with user id completion event
ESP_BLE_MESH_PROVISIONER_DELETE_SETTINGS_WITH_INDEX_COMP_EVT
Provisioner delete settings with index completion event
ESP_BLE_MESH_PROVISIONER_DELETE_SETTINGS_WITH_UID_COMP_EVT
Provisioner delete settings with user id completion event
ESP_BLE_MESH_SET_FAST_PROV_INFO_COMP_EVT
Set fast provisioning information (e.g. unicast address range, net_idx, etc.) completion event
ESP_BLE_MESH_SET_FAST_PROV_ACTION_COMP_EVT
Set fast provisioning action completion event
ESP_BLE_MESH_HEARTBEAT_MESSAGE_RECV_EVT
Receive Heartbeat message event
ESP_BLE_MESH_LPN_ENABLE_COMP_EVT
Enable Low Power Node completion event
ESP_BLE_MESH_LPN_DISABLE_COMP_EVT
Disable Low Power Node completion event
ESP_BLE_MESH_LPN_POLL_COMP_EVT
Low Power Node send Friend Poll completion event
ESP_BLE_MESH_LPN_FRIENDSHIP_ESTABLISH_EVT
Low Power Node establishes friendship event
ESP_BLE_MESH_LPN_FRIENDSHIP_TERMINATE_EVT
Low Power Node terminates friendship event
ESP_BLE_MESH_FRIEND_FRIENDSHIP_ESTABLISH_EVT
Friend Node establishes friendship event
ESP_BLE_MESH_FRIEND_FRIENDSHIP_TERMINATE_EVT
Friend Node terminates friendship event
ESP_BLE_MESH_PROXY_CLIENT_RECV_ADV_PKT_EVT
Proxy Client receives Network ID advertising packet event
ESP_BLE_MESH_PROXY_CLIENT_CONNECTED_EVT
Proxy Client establishes connection successfully event
ESP_BLE_MESH_PROXY_CLIENT_DISCONNECTED_EVT
Proxy Client terminates connection successfully event
ESP_BLE_MESH_PROXY_CLIENT_RECV_FILTER_STATUS_EVT
Proxy Client receives Proxy Filter Status event
ESP_BLE_MESH_PROXY_CLIENT_CONNECT_COMP_EVT
Proxy Client connect completion event
ESP_BLE_MESH_PROXY_CLIENT_DISCONNECT_COMP_EVT
Proxy Client disconnect completion event
ESP_BLE_MESH_PROXY_CLIENT_SET_FILTER_TYPE_COMP_EVT
Proxy Client set filter type completion event

ESP_BLE_MESH_PROXY_CLIENT_ADD_FILTER_ADDR_COMP_EVT
Proxy Client add filter address completion event
ESP_BLE_MESH_PROXY_CLIENT_REMOVE_FILTER_ADDR_COMP_EVT
Proxy Client remove filter address completion event
ESP_BLE_MESH_MODEL_SUBSCRIBE_GROUP_ADDR_COMP_EVT
Local model subscribes group address completion event
ESP_BLE_MESH_MODEL_UNSUBSCRIBE_GROUP_ADDR_COMP_EVT
Local model unsubscribes group address completion event
ESP_BLE_MESH_DEINIT_MESH_COMP_EVT
De-initialize BLE Mesh stack completion event
ESP_BLE_MESH_PROV_EVT_MAX
enum [anonymous]
BLE Mesh server models related definitions.
This enum value is the flag of transition timer operation
Values:
ESP_BLE_MESH_SERVER_TRANS_TIMER_START
ESP_BLE_MESH_SERVER_FLAG_MAX
enum esp_ble_mesh_server_state_type_t
This enum value is the type of server model states
Values:
ESP_BLE_MESH_GENERIC_ONOFF_STATE
ESP_BLE_MESH_GENERIC_LEVEL_STATE
ESP_BLE_MESH_GENERIC_ONPOWERUP_STATE
ESP_BLE_MESH_GENERIC_POWER_ACTUAL_STATE
ESP_BLE_MESH_LIGHT_LIGHTNESS_ACTUAL_STATE
ESP_BLE_MESH_LIGHT_LIGHTNESS_LINEAR_STATE
ESP_BLE_MESH_LIGHT_CTL_LIGHTNESS_STATE
ESP_BLE_MESH_LIGHT_CTL_TEMP_DELTA_UV_STATE
ESP_BLE_MESH_LIGHT_HSL_STATE
ESP_BLE_MESH_LIGHT_HSL_LIGHTNESS_STATE
ESP_BLE_MESH_LIGHT_HSL_HUE_STATE
ESP_BLE_MESH_LIGHT_HSL_SATURATION_STATE
ESP_BLE_MESH_LIGHT_XYL_LIGHTNESS_STATE
ESP_BLE_MESH_LIGHT_LC_LIGHT_ONOFF_STATE
ESP_BLE_MESH_SERVER_MODEL_STATE_MAX
enum esp_ble_mesh_model_cb_event_t
Values:
ESP_BLE_MESH_MODEL_OPERATION_EVT
User-defined models receive messages from peer devices (e.g. get, set, status, etc) event
ESP_BLE_MESH_MODEL_SEND_COMP_EVT
User-defined models send messages completion event
ESP_BLE_MESH_MODEL_PUBLISH_COMP_EVT
User-defined models publish messages completion event

ESP_BLE_MESH_CLIENT_MODEL_RECV_PUBLISH_MSG_EVT
User-defined client models receive publish messages event
ESP_BLE_MESH_CLIENT_MODEL_SEND_TIMEOUT_EVT
Timeout event for the user-defined client models that failed to receive response from peer server models
ESP_BLE_MESH_MODEL_PUBLISH_UPDATE_EVT
When a model is configured to publish messages periodically, this event will occur during every publish
period
ESP_BLE_MESH_SERVER_MODEL_UPDATE_STATE_COMP_EVT
Server models update state value completion event
ESP_BLE_MESH_MODEL_EVT_MAX
ESP-BLE-MESH Core API Reference
This section contains ESP-BLE-MESH Core related APIs, which can be used to initialize ESP-BLE-MESH stack,
provision, send/publish messages, etc.
This API reference covers six components:
• ESP-BLE-MESH Stack Initialization
• Reading of Local Data Information
• Low Power Operation (Updating)
• Send/Publish Messages, add Local AppKey, etc.
• ESP-BLE-MESH Node/Provisioner Provisioning
• ESP-BLE-MESH GATT Proxy Server
ESP-BLE-MESH Stack Initialization
Header File
• components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_common_api.h
Functions
esp_err_t esp_ble_mesh_init(esp_ble_mesh_prov_t *prov, esp_ble_mesh_comp_t *comp)
Initialize BLE Mesh module. This API initializes provisioning capabilities and composition data information.
Note After calling this API, the device needs to call esp_ble_mesh_prov_enable() to enable provisioning func-
tionality again.
Return ESP_OK on success or error code otherwise.
Parameters
• [in] prov: Pointer to the device provisioning capabilities. This pointer must remain valid during
the lifetime of the BLE Mesh device.
• [in] comp: Pointer to the device composition data information. This pointer must remain valid
during the lifetime of the BLE Mesh device.
esp_err_t esp_ble_mesh_deinit(esp_ble_mesh_deinit_param_t *param)
De-initialize BLE Mesh module.
Note This function shall be invoked after esp_ble_mesh_client_model_deinit().
Parameters
• [in] param: Pointer to the structure of BLE Mesh deinit parameters.
Reading of Local Data Information

Header File
• components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_local_data_operation_api.h
Functions
int32_t esp_ble_mesh_get_model_publish_period(esp_ble_mesh_model_t *model)
Get the model publish period, the unit is ms.
Return Publish period value on success, 0 or (negative) error code from errno.h on failure.
Parameters
• [in] model: Model instance pointer.
uint16_t esp_ble_mesh_get_primary_element_address(void)
Get the address of the primary element.
Return Address of the primary element on success, or ESP_BLE_MESH_ADDR_UNASSIGNED on failure
which means the device has not been provisioned.
uint16_t *esp_ble_mesh_is_model_subscribed_to_group(esp_ble_mesh_model_t *model,
uint16_t group_addr)
Check if the model has subscribed to the given group address. Note: E.g., once a status message is received
and the destination address is a group address, the model uses this API to check if it is successfully subscribed
to the given group address.
Return Pointer to the group address within the Subscription List of the model on success, or NULL on failure
which means the model has not subscribed to the given group address. Note: With the pointer to the group
address returned, you can reset the group address to 0x0000 in order to unsubscribe the model from the
group.
Parameters
• [in] model: Pointer to the model.
• [in] group_addr: Group address.
esp_ble_mesh_elem_t *esp_ble_mesh_find_element(uint16_t element_addr)
Find the BLE Mesh element pointer via the element address.
Return Pointer to the element on success, or NULL on failure.
Parameters
• [in] element_addr: Element address.
uint8_t esp_ble_mesh_get_element_count(void)
Get the number of elements that have been registered.
Return Number of elements.
esp_ble_mesh_model_t *esp_ble_mesh_find_vendor_model(const esp_ble_mesh_elem_t
*element, uint16_t company_id,
uint16_t model_id)
Find the Vendor specific model with the given element, the company ID and the Vendor Model ID.
Return Pointer to the Vendor Model on success, or NULL on failure which means the Vendor Model is not
found.
Parameters
• [in] element: Element to which the model belongs.
• [in] company_id: A 16-bit company identifier assigned by the Bluetooth SIG.
• [in] model_id: A 16-bit vendor-assigned model identifier.
esp_ble_mesh_model_t *esp_ble_mesh_find_sig_model(const esp_ble_mesh_elem_t *element,
uint16_t model_id)
Find the SIG model with the given element and Model id.
Return Pointer to the SIG Model on success, or NULL on failure which means the SIG Model is not found.
Parameters
• [in] element: Element to which the model belongs.
• [in] model_id: SIG model identifier.

const esp_ble_mesh_comp_t *esp_ble_mesh_get_composition_data(void)

Get the Composition data which has been registered.
Return Pointer to the Composition data on success, or NULL on failure which means the Composition data
is not initialized.
esp_err_t esp_ble_mesh_model_subscribe_group_addr(uint16_t element_addr, uint16_t com-
pany_id, uint16_t model_id, uint16_t
group_addr)
A local model of node or Provisioner subscribes a group address.
Note This function shall not be invoked before node is provisioned or Provisioner is enabled.
Parameters
• [in] element_addr: Unicast address of the element to which the model belongs.
• [in] company_id: A 16-bit company identifier.
• [in] model_id: A 16-bit model identifier.
• [in] group_addr: The group address to be subscribed.
esp_err_t esp_ble_mesh_model_unsubscribe_group_addr(uint16_t element_addr, uint16_t
company_id, uint16_t model_id,
uint16_t group_addr)
A local model of node or Provisioner unsubscribes a group address.
Note This function shall not be invoked before node is provisioned or Provisioner is enabled.
Parameters
• [in] element_addr: Unicast address of the element to which the model belongs.
• [in] company_id: A 16-bit company identifier.
• [in] model_id: A 16-bit model identifier.
• [in] group_addr: The subscribed group address.
const uint8_t *esp_ble_mesh_node_get_local_net_key(uint16_t net_idx)
This function is called by Node to get the local NetKey.
Return NetKey on success, or NULL on failure.
Parameters
• [in] net_idx: NetKey index.
const uint8_t *esp_ble_mesh_node_get_local_app_key(uint16_t app_idx)
This function is called by Node to get the local AppKey.
Return AppKey on success, or NULL on failure.
Parameters
• [in] app_idx: AppKey index.
esp_err_t esp_ble_mesh_node_add_local_net_key(const uint8_t net_key[16], uint16_t
net_idx)
This function is called by Node to add a local NetKey.
Note This function can only be called after the device is provisioned.
Parameters
• [in] net_key: NetKey to be added.
• [in] net_idx: NetKey Index.
esp_err_t esp_ble_mesh_node_add_local_app_key(const uint8_t app_key[16], uint16_t
net_idx, uint16_t app_idx)
This function is called by Node to add a local AppKey.
Note The net_idx must be an existing one. This function can only be called after the device is provisioned.
Parameters
• [in] app_key: AppKey to be added.
• [in] net_idx: NetKey Index.

• [in] app_idx: AppKey Index.

esp_err_t esp_ble_mesh_node_bind_app_key_to_local_model(uint16_t element_addr,
uint16_t company_id,
uint16_t model_id, uint16_t
app_idx)
This function is called by Node to bind AppKey to model locally.
Note If going to bind app_key with local vendor model, the company_id shall be set to 0xFFFF. This function
can only be called after the device is provisioned.
Parameters
• [in] element_addr: Node local element address
• [in] company_id: Node local company id
• [in] model_id: Node local model id
• [in] app_idx: Node local appkey index
Low Power Operation (Updating)
Header File
• components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_low_power_api.h
Functions
esp_err_t esp_ble_mesh_lpn_enable(void)
Enable BLE Mesh device LPN functionality.
Note This API enables LPN functionality. Once called, the proper Friend Request will be sent.
esp_err_t esp_ble_mesh_lpn_disable(bool force)
Disable BLE Mesh device LPN functionality.
Parameters
• [in] force: when disabling LPN functionality, use this flag to indicate whether directly clear
corresponding information or just send friend clear to disable it if friendship has already been estab-
lished.
esp_err_t esp_ble_mesh_lpn_poll(void)
LPN tries to poll messages from the Friend Node.
Note The Friend Poll message is sent by a Low Power node to ask the Friend node to send a message that it
has stored for the Low Power node. Users can call this API to send Friend Poll message manually. If this
API is not invoked, the bottom layer of the Low Power node will send Friend Poll before the PollTimeout
timer expires. If the corresponding Friend Update is received and MD is set to 0, which means there are
no messages for the Low Power node, then the Low Power node will stop scanning.
Send/Publish Messages, add Local AppKey, etc.
Header File
• components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_networking_api.h
Functions

esp_err_t esp_ble_mesh_register_custom_model_callback(esp_ble_mesh_model_cb_t call-

back)
Register BLE Mesh callback for user-defined models operations. This callback can report the following events
generated for the user-defined models:
• Call back the messages received by user-defined client and server models to the application layer;
• If users call esp_ble_mesh_server/client_model_send, this callback notifies the application layer of the
send_complete event;
• If user-defined client model sends a message that requires response, and the response message is received
after the timer expires, the response message will be reported to the application layer as published by a
peer device;
• If the user-defined client model fails to receive the response message during a specified period of time, a
timeout event will be reported to the application layer.
Note The client models (i.e. Config Client model, Health Client model, Generic Client models, Sensor Client
model, Scene Client model and Lighting Client models) that have been realized internally have their
specific register functions. For example, esp_ble_mesh_register_config_client_callback is the register
function for Config Client Model.
Parameters
• [in] callback: Pointer to the callback function.
esp_err_t esp_ble_mesh_model_msg_opcode_init(uint8_t *data, uint32_t opcode)
Add the message opcode to the beginning of the model message before sending or publishing the model mes-
sage.
Note This API is only used to set the opcode of the message.
Parameters
• [in] data: Pointer to the message data.
• [in] opcode: The message opcode.
esp_err_t esp_ble_mesh_client_model_init(esp_ble_mesh_model_t *model)
Initialize the user-defined client model. All user-defined client models shall call this function to initialize the
client model internal data. Node: Before calling this API, the op_pair_size and op_pair variabled within the
user_data(defined using esp_ble_mesh_client_t_) of the client model need to be initialized.
Parameters
• [in] model: BLE Mesh Client model to which the message belongs.
esp_err_t esp_ble_mesh_client_model_deinit(esp_ble_mesh_model_t *model)
De-initialize the user-defined client model.
Note This function shall be invoked before esp_ble_mesh_deinit() is called.
Parameters
• [in] model: Pointer of the Client model.
esp_err_t esp_ble_mesh_server_model_send_msg(esp_ble_mesh_model_t *model,
esp_ble_mesh_msg_ctx_t *ctx, uint32_t
opcode, uint16_t length, uint8_t *data)
Send server model messages(such as server model status messages).
Parameters
• [in] model: BLE Mesh Server Model to which the message belongs.
• [in] ctx: Message context, includes keys, TTL, etc.
• [in] opcode: Message opcode.
• [in] length: Message length (exclude the message opcode).
• [in] data: Parameters of Access Payload (exclude the message opcode) to be sent.

esp_err_t esp_ble_mesh_client_model_send_msg(esp_ble_mesh_model_t *model,

esp_ble_mesh_msg_ctx_t *ctx, uint32_t
opcode, uint16_t length, uint8_t *data,
int32_t msg_timeout, bool need_rsp,
esp_ble_mesh_dev_role_t device_role)
Send client model message (such as model get, set, etc).
Parameters
• [in] model: BLE Mesh Client Model to which the message belongs.
• [in] ctx: Message context, includes keys, TTL, etc.
• [in] data: Parameters of the Access Payload (exclude the message opcode) to be sent.
• [in] msg_timeout: Time to get response to the message (in milliseconds).
• [in] need_rsp: TRUE if the opcode requires the peer device to reply, FALSE otherwise.
• [in] device_role: Role of the device (Node/Provisioner) that sends the message.
esp_err_t esp_ble_mesh_model_publish(esp_ble_mesh_model_t *model, uint32_t opcode, uint16_t
length, uint8_t *data, esp_ble_mesh_dev_role_t de-
vice_role)
Send a model publication message.
Note Before calling this function, the user needs to ensure that the model publica-
tion message (esp_ble_mesh_model_pub_t::msg) contains a valid message to be sent.
And if users want to update the publishing message, this API should be called in
ESP_BLE_MESH_MODEL_PUBLISH_UPDATE_EVT with the message updated.
Parameters
• [in] model: Mesh (client) Model publishing the message.
• [in] data: Parameters of the Access Payload (exclude the message opcode) to be sent.
• [in] device_role: Role of the device (node/provisioner) publishing the message of the type
esp_ble_mesh_dev_role_t.
esp_err_t esp_ble_mesh_server_model_update_state(esp_ble_mesh_model_t *model,
esp_ble_mesh_server_state_type_t type,
esp_ble_mesh_server_state_value_t
*value)
Update a server model state value. If the model publication state is set properly (e.g. publish address is set to
a valid address), it will publish corresponding status message.
Note Currently this API is used to update bound state value, not for all server model states.
Parameters
• [in] model: Server model which is going to update the state.
• [in] type: Server model state type.
• [in] value: Server model state value.
esp_err_t esp_ble_mesh_node_local_reset(void)
Reset the provisioning procedure of the local BLE Mesh node.
Note All provisioning information in this node will be deleted and the node needs to be reprovisioned. The API
function esp_ble_mesh_node_prov_enable() needs to be called to start a new provisioning procedure.
esp_err_t esp_ble_mesh_provisioner_set_node_name(uint16_t index, const char *name)
This function is called to set the node (provisioned device) name.
Note index is obtained from the parameters of ESP_BLE_MESH_PROVISIONER_PROV_COMPLETE_EVT.
Parameters

• [in] index: Index of the node in the node queue.

• [in] name: Name (end by \0 ) to be set for the node.
const char *esp_ble_mesh_provisioner_get_node_name(uint16_t index)
This function is called to get the node (provisioned device) name.
Note index is obtained from the parameters of ESP_BLE_MESH_PROVISIONER_PROV_COMPLETE_EVT.
Return Node name on success, or NULL on failure.
Parameters
• [in] index: Index of the node in the node queue.
uint16_t esp_ble_mesh_provisioner_get_node_index(const char *name)
This function is called to get the node (provisioned device) index.
Return Node index on success, or an invalid value (0xFFFF) on failure.
Parameters
• [in] name: Name of the node (end by \0 ).
esp_err_t esp_ble_mesh_provisioner_store_node_comp_data(uint16_t unicast_addr,
uint8_t *data, uint16_t
length)
This function is called to store the Composition Data of the node.
Parameters
• [in] unicast_addr: Element address of the node
• [in] data: Pointer of Composition Data
• [in] length: Length of Composition Data
esp_ble_mesh_node_t *esp_ble_mesh_provisioner_get_node_with_uuid(const uint8_t
uuid[16])
This function is called to get the provisioned node information with the node device uuid.
Return Pointer of the node info struct or NULL on failure.
Parameters
• [in] uuid: Device UUID of the node
esp_ble_mesh_node_t *esp_ble_mesh_provisioner_get_node_with_addr(uint16_t uni-
cast_addr)
This function is called to get the provisioned node information with the node unicast address.
Parameters
• [in] unicast_addr: Unicast address of the node
esp_ble_mesh_node_t *esp_ble_mesh_provisioner_get_node_with_name(const char
*name)
This function is called to get the provisioned node information with the node name.
Parameters
• [in] name: Name of the node (end by \0 ).
uint16_t esp_ble_mesh_provisioner_get_prov_node_count(void)
This function is called by Provisioner to get provisioned node count.
Return Number of the provisioned nodes.
const esp_ble_mesh_node_t **esp_ble_mesh_provisioner_get_node_table_entry(void)
This function is called by Provisioner to get the entry of the node table.
Note After invoking the function to get the entry of nodes, users can use the for loop com-
bined with the macro CONFIG_BLE_MESH_MAX_PROV_NODES to get each node s in-
formation. Before trying to read the node s information, users need to check if the
node exists, i.e. if the *(esp_ble_mesh_node_t **node) is NULL. For example: ``` const
esp_ble_mesh_node_t **entry = esp_ble_mesh_provisioner_get_node_table_entry(); for (int i = 0; i <

CONFIG_BLE_MESH_MAX_PROV_NODES; i++) { const esp_ble_mesh_node_t *node = entry[i];

if (node) { } } ```
Return Pointer to the start of the node table.
esp_err_t esp_ble_mesh_provisioner_delete_node_with_uuid(const uint8_t uuid[16])
This function is called to delete the provisioned node information with the node device uuid.
Parameters
• [in] uuid: Device UUID of the node
esp_err_t esp_ble_mesh_provisioner_delete_node_with_addr(uint16_t unicast_addr)
This function is called to delete the provisioned node information with the node unicast address.
Parameters
• [in] unicast_addr: Unicast address of the node
esp_err_t esp_ble_mesh_provisioner_add_local_app_key(const uint8_t app_key[16],
uint16_t net_idx, uint16_t
app_idx)
This function is called to add a local AppKey for Provisioner.
Note app_key: If set to NULL, app_key will be generated internally. net_idx: Should be an existing one.
app_idx: If it is going to be generated internally, it should be set to 0xFFFF, and the new app_idx will
be reported via an event.
Parameters
• [in] app_key: The app key to be set for the local BLE Mesh stack.
• [in] net_idx: The network key index.
• [in] app_idx: The app key index.
esp_err_t esp_ble_mesh_provisioner_update_local_app_key(const uint8_t app_key[16],
uint16_t net_idx, uint16_t
app_idx)
This function is used to update a local AppKey for Provisioner.
Parameters
• [in] app_key: Value of the AppKey.
• [in] net_idx: Corresponding NetKey Index.
• [in] app_idx: The AppKey Index
const uint8_t *esp_ble_mesh_provisioner_get_local_app_key(uint16_t net_idx, uint16_t
app_idx)
This function is called by Provisioner to get the local app key value.
Return App key on success, or NULL on failure.
Parameters
• [in] net_idx: Network key index.
• [in] app_idx: Application key index.
esp_err_t esp_ble_mesh_provisioner_bind_app_key_to_local_model(uint16_t el-
ement_addr,
uint16_t app_idx,
uint16_t
model_id,
uint16_t com-
pany_id)
This function is called by Provisioner to bind own model with proper app key.
Note company_id: If going to bind app_key with local vendor model, company_id should be set to 0xFFFF.
Parameters
• [in] element_addr: Provisioner local element address

• [in] app_idx: Provisioner local appkey index

• [in] model_id: Provisioner local model id
• [in] company_id: Provisioner local company id
esp_err_t esp_ble_mesh_provisioner_add_local_net_key(const uint8_t net_key[16],
uint16_t net_idx)
This function is called by Provisioner to add local network key.
Note net_key: If set to NULL, net_key will be generated internally. net_idx: If it is going to be generated
internally, it should be set to 0xFFFF, and the new net_idx will be reported via an event.
Parameters
• [in] net_key: The network key to be added to the Provisioner local BLE Mesh stack.
• [in] net_idx: The network key index.
esp_err_t esp_ble_mesh_provisioner_update_local_net_key(const uint8_t net_key[16],
uint16_t net_idx)
This function is called by Provisioner to update a local network key.
Parameters
• [in] net_key: Value of the NetKey.
• [in] net_idx: The NetKey Index.
const uint8_t *esp_ble_mesh_provisioner_get_local_net_key(uint16_t net_idx)
This function is called by Provisioner to get the local network key value.
Return Network key on success, or NULL on failure.
Parameters
esp_err_t esp_ble_mesh_provisioner_recv_heartbeat(bool enable)
This function is called by Provisioner to enable or disable receiving heartbeat messages.
Note If enabling receiving heartbeat message successfully, the filter will be an empty rejectlist by default,
which means all heartbeat messages received by the Provisioner will be reported to the application layer.
Parameters
• [in] enable: Enable or disable receiving heartbeat messages.
esp_err_t esp_ble_mesh_provisioner_set_heartbeat_filter_type(uint8_t type)
This function is called by Provisioner to set the heartbeat filter type.
Note 1. If the filter type is not the same with the current value, then all the filter entries will be cleaned.
1. If the previous type is rejectlist, and changed to acceptlist, then the filter will be an empty acceptlist,
which means no heartbeat messages will be reported. Users need to add SRC or DST into the filter
entry, then heartbeat messages from the SRC or to the DST will be reported.
Parameters
• [in] type: Heartbeat filter type (acceptlist or rejectlist).
esp_err_t esp_ble_mesh_provisioner_set_heartbeat_filter_info(uint8_t op,
esp_ble_mesh_heartbeat_filter_info_t
*info)
This function is called by Provisioner to add or remove a heartbeat filter entry.
1. If the operation is REMOVE , the hb_src can be set to the SRC (can only be a unicast address)
of heartbeat messages, and the hb_dst can be set to the DST (unicast address or group address), at
least one of them needs to be set.
• The filter entry with the same SRC or DST will be removed.
Note 1. If the operation is ADD , the hb_src can be set to the SRC (can only be a unicast address) of
heartbeat messages, and the hb_dst can be set to the DST (unicast address or group address), at least
one of them needs to be set.

• If only one of them is set, the filter entry will only use the configured SRC or DST to filter heartbeat
messages.
• If both of them are set, the SRC and DST will both be used to decide if a heartbeat message will be
handled.
• If SRC or DST already exists in some filter entry, then the corresponding entry will be cleaned firstly,
then a new entry will be allocated to store the information.
Parameters
• [in] op: Add or REMOVE
• [in] info: Heartbeat filter entry information, including: hb_src - Heartbeat source address;
hb_dst - Heartbeat destination address;
esp_err_t esp_ble_mesh_provisioner_direct_erase_settings(void)
This function is called by Provisioner to directly erase the mesh information from nvs namespace.
Note This function can be invoked when the mesh stack is not initialized or has been de-initialized.
esp_err_t esp_ble_mesh_provisioner_open_settings_with_index(uint8_t index)
This function is called by Provisioner to open a nvs namespace for storing mesh information.
Note Before open another nvs namespace, the previously opened nvs namespace must be closed firstly.
Parameters
• [in] index: Settings index.
esp_err_t esp_ble_mesh_provisioner_open_settings_with_uid(const char *uid)
This function is called by Provisioner to open a nvs namespace for storing mesh information.
Note Before open another nvs namespace, the previously opened nvs namespace must be closed firstly.
Parameters
• [in] uid: Settings user id.
esp_err_t esp_ble_mesh_provisioner_close_settings_with_index(uint8_t index, bool
erase)
This function is called by Provisioner to close a nvs namespace which is opened previously for storing mesh
information.
Note 1. Before closing the nvs namespace, it must be open.
1. When the function is invoked, the Provisioner functionality will be disabled firstly, and: a) If the
erase flag is set to false, the mesh information will be cleaned (e.g. removing NetKey, AppKey,
nodes, etc) from the mesh stack. b) If the erase flag is set to true, the mesh information stored
in the nvs namespace will also be erased besides been cleaned from the mesh stack.
2. If Provisioner tries to work properly again, we can invoke the open function to open a new nvs
namespace or a previously added one, and restore the mesh information from it if not erased.
3. The working process shall be as following: a) Open settings A b) Start to provision and control nodes
c) Close settings A d) Open settings B e) Start to provision and control other nodes f) Close settings
B g)
Parameters
• [in] erase: Indicate if erasing mesh information.
esp_err_t esp_ble_mesh_provisioner_close_settings_with_uid(const char *uid, bool
erase)
This function is called by Provisioner to close a nvs namespace which is opened previously for storing mesh
information.
Note 1. Before closing the nvs namespace, it must be open.
1. When the function is invoked, the Provisioner functionality will be disabled firstly, and: a) If the
erase flag is set to false, the mesh information will be cleaned (e.g. removing NetKey, AppKey,

nodes, etc) from the mesh stack. b) If the erase flag is set to true, the mesh information stored
in the nvs namespace will also be erased besides been cleaned from the mesh stack.
2. If Provisioner tries to work properly again, we can invoke the open function to open a new nvs
namespace or a previously added one, and restore the mesh information from it if not erased.
3. The working process shall be as following: a) Open settings A b) Start to provision and control nodes
c) Close settings A d) Open settings B e) Start to provision and control other nodes f) Close settings
B g)
Parameters
• [in] erase: Indicate if erasing mesh information.
esp_err_t esp_ble_mesh_provisioner_delete_settings_with_index(uint8_t index)
This function is called by Provisioner to erase the mesh information and settings user id from a nvs namespace.
Note When this function is called, the nvs namespace must not be open. This function is used to erase the
mesh information and settings user id which are not used currently.
Parameters
esp_err_t esp_ble_mesh_provisioner_delete_settings_with_uid(const char *uid)
This function is called by Provisioner to erase the mesh information and settings user id from a nvs namespace.
Note When this function is called, the nvs namespace must not be open. This function is used to erase the
mesh information and settings user id which are not used currently.
Parameters
const char *esp_ble_mesh_provisioner_get_settings_uid(uint8_t index)
This function is called by Provisioner to get settings user id.
Return Setting user id on success or NULL on failure.
Parameters
uint8_t esp_ble_mesh_provisioner_get_settings_index(const char *uid)
This function is called by Provisioner to get settings index.
Return Settings index.
Parameters
uint8_t esp_ble_mesh_provisioner_get_free_settings_count(void)
This function is called by Provisioner to get the number of free settings user id.
Return Number of free settings user id.
const uint8_t *esp_ble_mesh_get_fast_prov_app_key(uint16_t net_idx, uint16_t app_idx)
This function is called to get fast provisioning application key.
Return Application key on success, or NULL on failure.
Parameters
• [in] app_idx: Application key index.
Type Definitions
typedef void (*esp_ble_mesh_model_cb_t)(esp_ble_mesh_model_cb_event_t event,
esp_ble_mesh_model_cb_param_t *param)
: event, event code of user-defined model events; param, parameters of user-defined model events
ESP-BLE-MESH Node/Provisioner Provisioning

Header File
• components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_provisioning_api.h
Functions
esp_err_t esp_ble_mesh_register_prov_callback(esp_ble_mesh_prov_cb_t callback)
Register BLE Mesh provisioning callback.
Parameters
bool esp_ble_mesh_node_is_provisioned(void)
Check if a device has been provisioned.
Return TRUE if the device is provisioned, FALSE if the device is unprovisioned.
esp_err_t esp_ble_mesh_node_prov_enable(esp_ble_mesh_prov_bearer_t bearers)
Enable specific provisioning bearers to get the device ready for provisioning.
Note PB-ADV: send unprovisioned device beacon. PB-GATT: send connectable advertising packets.
Parameters
• bearers: Bit-wise OR of provisioning bearers.
esp_err_t esp_ble_mesh_node_prov_disable(esp_ble_mesh_prov_bearer_t bearers)
Disable specific provisioning bearers to make a device inaccessible for provisioning.
Parameters
• bearers: Bit-wise OR of provisioning bearers.
esp_err_t esp_ble_mesh_node_set_oob_pub_key(uint8_t pub_key_x[32], uint8_t pub_key_y[32],
uint8_t private_key[32])
Unprovisioned device set own oob public key & private key pair.
Note In order to avoid suffering brute-forcing attack (CVE-2020-26559). The Bluetooth SIG recommends
that potentially vulnerable mesh provisioners use an out-of-band mechanism to exchange the public keys.
So as an unprovisioned device, it should use this function to input the Public Key exchanged through the
out-of-band mechanism.
Parameters
• [in] pub_key_x: Unprovisioned device s Public Key X
• [in] pub_key_y: Unprovisioned device s Public Key Y
• [in] private_key: Unprovisioned device s Private Key
esp_err_t esp_ble_mesh_node_input_number(uint32_t number)
Provide provisioning input OOB number.
Note This is intended to be called if the user has received ESP_BLE_MESH_NODE_PROV_INPUT_EVT
with ESP_BLE_MESH_ENTER_NUMBER as the action.
Parameters
• [in] number: Number input by device.
esp_err_t esp_ble_mesh_node_input_string(const char *string)
Provide provisioning input OOB string.
Note This is intended to be called if the user has received ESP_BLE_MESH_NODE_PROV_INPUT_EVT
with ESP_BLE_MESH_ENTER_STRING as the action.
Parameters
• [in] string: String input by device.

esp_err_t esp_ble_mesh_set_unprovisioned_device_name(const char *name)

Using this function, an unprovisioned device can set its own device name, which will be broadcasted in its
advertising data.
Note This API applicable to PB-GATT mode only by setting the name to the scan response data, it doesn t
apply to PB-ADV mode.
Parameters
• [in] name: Unprovisioned device name
esp_err_t esp_ble_mesh_provisioner_read_oob_pub_key(uint8_t link_idx, uint8_t
pub_key_x[32], uint8_t
pub_key_y[32])
Provisioner inputs unprovisioned device s oob public key.
Note In order to avoid suffering brute-forcing attack (CVE-2020-26559). The Bluetooth SIG recommends
that potentially vulnerable mesh provisioners use an out-of-band mechanism to exchange the public keys.
Parameters
• [in] link_idx: The provisioning link index
• [in] pub_key_x: Unprovisioned device s Public Key X
• [in] pub_key_y: Unprovisioned device s Public Key Y
esp_err_t esp_ble_mesh_provisioner_input_string(const char *string, uint8_t link_idx)
Provide provisioning input OOB string.
This is intended to be called after the esp_ble_mesh_prov_t prov_input_num callback has been called with
ESP_BLE_MESH_ENTER_STRING as the action.
Parameters
• [in] string: String input by Provisioner.
• [in] link_idx: The provisioning link index.
esp_err_t esp_ble_mesh_provisioner_input_number(uint32_t number, uint8_t link_idx)
Provide provisioning input OOB number.
This is intended to be called after the esp_ble_mesh_prov_t prov_input_num callback has been called with
ESP_BLE_MESH_ENTER_NUMBER as the action.
Parameters
• [in] number: Number input by Provisioner.
• [in] link_idx: The provisioning link index.
esp_err_t esp_ble_mesh_provisioner_prov_enable(esp_ble_mesh_prov_bearer_t bearers)
Enable one or more provisioning bearers.
Note PB-ADV: Enable BLE scan. PB-GATT: Initialize corresponding BLE Mesh Proxy info.
Parameters
• [in] bearers: Bit-wise OR of provisioning bearers.
esp_err_t esp_ble_mesh_provisioner_prov_disable(esp_ble_mesh_prov_bearer_t bearers)
Disable one or more provisioning bearers.
Note PB-ADV: Disable BLE scan. PB-GATT: Break any existing BLE Mesh Provisioning connections.
Parameters
• [in] bearers: Bit-wise OR of provisioning bearers.
esp_err_t esp_ble_mesh_provisioner_add_unprov_dev(esp_ble_mesh_unprov_dev_add_t
*add_dev,
esp_ble_mesh_dev_add_flag_t flags)
Add unprovisioned device info to the unprov_dev queue.


Note : 1. Currently address type only supports public address and static random address.
1. If device UUID and/or device address as well as address type already exist in the device queue, but
the bearer is different from the existing one, add operation will also be successful and it will update
the provision bearer supported by the device.
2. For example, if the Provisioner wants to add an unprovisioned device info before receiving its un-
provisioned device beacon or Mesh Provisioning advertising packets, the Provisioner can use this
API to add the device info with each one or both of device UUID and device address added. When
the Provisioner gets the device s advertising packets, it will start provisioning the device internally.
• In this situation, the Provisioner can set bearers with each one or both of
ESP_BLE_MESH_PROV_ADV and ESP_BLE_MESH_PROV_GATT enabled, and
cannot set flags with ADD_DEV_START_PROV_NOW_FLAG enabled.
3. Another example is when the Provisioner receives the unprovisioned device s beacon or Mesh
Provisioning advertising packets, the advertising packets will be reported on to the application layer
using the callback registered by the function esp_ble_mesh_register_prov_callback. And in the call-
back, the Provisioner can call this API to start provisioning the device.
• If the Provisioner uses PB-ADV to provision, either one or both of device UUID and device
address can be added, bearers shall be set with ESP_BLE_MESH_PROV_ADV enabled and
the flags shall be set with ADD_DEV_START_PROV_NOW_FLAG enabled.
• If the Provisioner uses PB-GATT to provision, both the device UUID and device address need
to be added, bearers shall be set with ESP_BLE_MESH_PROV_GATT enabled, and the flags
shall be set with ADD_DEV_START_PROV_NOW_FLAG enabled.
• If the Provisioner just wants to store the unprovisioned device info when receiving its
advertising packets and start to provision it the next time (e.g. after receiving its ad-
vertising packets again), then it can add the device info with either one or both of de-
vice UUID and device address included. Bearers can be set with either one or both of
ESP_BLE_MESH_PROV_ADV and ESP_BLE_MESH_PROV_GATT enabled (recommend
to enable the bearer which will receive its advertising packets, because if the other bearer is
enabled, the Provisioner is not aware if the device supports the bearer), and flags cannot be set
with ADD_DEV_START_PROV_NOW_FLAG enabled.
• Note: ESP_BLE_MESH_PROV_ADV, ESP_BLE_MESH_PROV_GATT and
ADD_DEV_START_PROV_NOW_FLAG can not be enabled at the same time.
Parameters
• [in] add_dev: Pointer to a struct containing the device information
• [in] flags: Flags indicate several operations on the device information
– Remove device information from queue after device has been provisioned (BIT0)
– Start provisioning immediately after device is added to queue (BIT1)
– Device can be removed if device queue is full (BIT2)
esp_err_t esp_ble_mesh_provisioner_prov_device_with_addr(const uint8_t uuid[16],
esp_ble_mesh_bd_addr_t
addr,
esp_ble_mesh_addr_type_t
addr_type,
esp_ble_mesh_prov_bearer_t
bearer, uint16_t oob_info,
uint16_t unicast_addr)
Provision an unprovisioned device and assign a fixed unicast address for it in advance.
Return Zero on success or (negative) error code otherwise.
Note : 1. Currently address type only supports public address and static random address.
1. Bearer must be equal to ESP_BLE_MESH_PROV_ADV or ESP_BLE_MESH_PROV_GATT,
since Provisioner will start to provision a device immediately once this function is in-
voked. And the input bearer must be identical with the one within the parameters of the
ESP_BLE_MESH_PROVISIONER_RECV_UNPROV_ADV_PKT_EVT event.
2. If this function is used by a Provisioner to provision devices, the application should take care of the
assigned unicast address and avoid overlap of the unicast addresses of different nodes.
3. Recommend to use only one of the functions esp_ble_mesh_provisioner_add_unprov_dev and
esp_ble_mesh_provisioner_prov_device_with_addr by a Provisioner.

Parameters
• [in] uuid: Device UUID of the unprovisioned device
• [in] addr: Device address of the unprovisioned device
• [in] addr_type: Device address type of the unprovisioned device
• [in] bearer: Provisioning bearer going to be used by Provisioner
• [in] oob_info: OOB info of the unprovisioned device
• [in] unicast_addr: Unicast address going to be allocated for the unprovisioned device
esp_err_t esp_ble_mesh_provisioner_delete_dev(esp_ble_mesh_device_delete_t *del_dev)
Delete device from queue, and reset current provisioning link with the device.
Note If the device is in the queue, remove it from the queue; if the device is being provisioned, terminate the
provisioning procedure. Either one of the device address or device UUID can be used as input.
Parameters
• [in] del_dev: Pointer to a struct containing the device information.
esp_err_t esp_ble_mesh_provisioner_set_dev_uuid_match(const uint8_t *match_val,
uint8_t match_len, uint8_t
offset, bool prov_after_match)
This function is called by Provisioner to set the part of the device UUID to be compared before starting to
provision.
Parameters
• [in] match_val: Value to be compared with the part of the device UUID.
• [in] match_len: Length of the compared match value.
• [in] offset: Offset of the device UUID to be compared (based on zero).
• [in] prov_after_match: Flag used to indicate whether provisioner should start to provision
the device immediately if the part of the UUID matches.
esp_err_t esp_ble_mesh_provisioner_set_prov_data_info(esp_ble_mesh_prov_data_info_t
*prov_data_info)
This function is called by Provisioner to set provisioning data information before starting to provision.
Parameters
• [in] prov_data_info: Pointer to a struct containing net_idx or flags or iv_index.
esp_err_t esp_ble_mesh_provisioner_set_static_oob_value(const uint8_t *value,
uint8_t length)
This function is called by Provisioner to set static oob value used for provisioning.
AuthValues selected using a cryptographically secure random or pseudorandom number generator and having
the maximum permitted entropy (128-bits) will be most difficult to brute-force. AuthValues with reduced
entropy or generated in a predictable manner will not grant the same level of protection against this vulnerability.
Selecting a new AuthValue with each provisioning attempt can also make it more difficult to launch a brute-
force attack by requiring the attacker to restart the search with each provisioning attempt (CVE-2020-26556).
Note The Bluetooth SIG recommends that mesh implementations enforce a randomly selected AuthValue
using all of the available bits, where permitted by the implementation. A large entropy helps ensure that
a brute-force of the AuthValue, even a static AuthValue, cannot normally be completed in a reasonable
time (CVE-2020-26557).
Parameters
• [in] value: Pointer to the static oob value.
• [in] length: Length of the static oob value.
esp_err_t esp_ble_mesh_provisioner_set_primary_elem_addr(uint16_t addr)
This function is called by Provisioner to set own Primary element address.
Note This API must be invoked when BLE Mesh initialization is completed successfully, and can be invoked
before Provisioner functionality is enabled. Once this API is invoked successfully, the prov_unicast_addr
value in the struct esp_ble_mesh_prov_t will be ignored, and Provisioner will use this address as its own

primary element address. And if the unicast address going to assigned for the next unprovisioned de-
vice is smaller than the input address + element number of Provisioner, then the address for the next
unprovisioned device will be recalculated internally.
Parameters
• [in] addr: Unicast address of the Primary element of Provisioner.
esp_err_t esp_ble_mesh_set_fast_prov_info(esp_ble_mesh_fast_prov_info_t *fast_prov_info)
This function is called to set provisioning data information before starting fast provisioning.
Parameters
• [in] fast_prov_info: Pointer to a struct containing unicast address range, net_idx, etc.
esp_err_t esp_ble_mesh_set_fast_prov_action(esp_ble_mesh_fast_prov_action_t action)
This function is called to start/suspend/exit fast provisioning.
Parameters
• [in] action: fast provisioning action (i.e. enter, suspend, exit).
Type Definitions
typedef void (*esp_ble_mesh_prov_cb_t)(esp_ble_mesh_prov_cb_event_t event,
esp_ble_mesh_prov_cb_param_t *param)
: event, event code of provisioning events; param, parameters of provisioning events
typedef void (*esp_ble_mesh_prov_adv_cb_t)(const esp_ble_mesh_bd_addr_t addr,
const esp_ble_mesh_addr_type_t addr_type,
const uint8_t adv_type, const
uint8_t *dev_uuid, uint16_t oob_info,
esp_ble_mesh_prov_bearer_t bearer)
Callback for Provisioner that received advertising packets from unprovisioned devices which are not in the
unprovisioned device queue.
Report on the unprovisioned device beacon and mesh provisioning service adv data to application.
Parameters
• [in] addr: Pointer to the unprovisioned device address.
• [in] addr_type: Unprovisioned device address type.
• [in] adv_type: Adv packet type(ADV_IND or ADV_NONCONN_IND).
• [in] dev_uuid: Unprovisioned device UUID pointer.
• [in] oob_info: OOB information of the unprovisioned device.
• [in] bearer: Adv packet received from PB-GATT or PB-ADV bearer.
ESP-BLE-MESH GATT Proxy Server
Header File
• components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_proxy_api.h
Functions
esp_err_t esp_ble_mesh_proxy_identity_enable(void)
Enable advertising with Node Identity.
Note This API requires that GATT Proxy support be enabled. Once called, each subnet starts advertising
using Node Identity for the next 60 seconds, and after 60s Network ID will be advertised. Under normal
conditions, the BLE Mesh Proxy Node Identity and Network ID advertising will be enabled automatically
by BLE Mesh stack after the device is provisioned.
esp_err_t esp_ble_mesh_proxy_gatt_enable(void)
Enable BLE Mesh GATT Proxy Service.


esp_err_t esp_ble_mesh_proxy_gatt_disable(void)
Disconnect the BLE Mesh GATT Proxy connection if there is any, and disable the BLE Mesh GATT Proxy
Service.
esp_err_t esp_ble_mesh_proxy_client_connect(esp_ble_mesh_bd_addr_t addr,
esp_ble_mesh_addr_type_t addr_type, uint16_t
net_idx)
Proxy Client creates a connection with the Proxy Server.
Parameters
• [in] addr: Device address of the Proxy Server.
• [in] addr_type: Device address type(public or static random).
• [in] net_idx: NetKey Index related with Network ID in the Mesh Proxy advertising packet.
esp_err_t esp_ble_mesh_proxy_client_disconnect(uint8_t conn_handle)
Proxy Client terminates a connection with the Proxy Server.
Parameters
• [in] conn_handle: Proxy connection handle.
esp_err_t esp_ble_mesh_proxy_client_set_filter_type(uint8_t conn_handle,
uint16_t net_idx,
esp_ble_mesh_proxy_filter_type_t
filter_type)
Proxy Client sets the filter type of the Proxy Server.
Parameters
• [in] filter_type: whitelist or blacklist.
esp_err_t esp_ble_mesh_proxy_client_add_filter_addr(uint8_t conn_handle, uint16_t
net_idx, uint16_t *addr, uint16_t
addr_num)
Proxy Client adds address to the Proxy Server filter list.
Parameters
• [in] addr: Pointer to the filter address.
• [in] addr_num: Number of the filter address.
esp_err_t esp_ble_mesh_proxy_client_remove_filter_addr(uint8_t conn_handle, uint16_t
net_idx, uint16_t *addr,
uint16_t addr_num)
Proxy Client removes address from the Proxy Server filter list.
Parameters
• [in] addr: Pointer to the filter address.
• [in] addr_num: Number of the filter address.

ESP-BLE-MESH Models API Reference
This section contains ESP-BLE-MESH Model related APIs, event types, event parameters, etc.
There are six categories of models:
• Configuration Client/Server Models
• Health Client/Server Models
• Generic Client/Server Models
• Sensor Client/Server Models
• Time and Scenes Client/Server Models
• Lighting Client/Server Models
Note: Definitions related to Server Models are being updated, and will be released soon.
Configuration Client/Server Models
Header File
• components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_config_model_api.h
Functions
esp_err_t esp_ble_mesh_register_config_client_callback(esp_ble_mesh_cfg_client_cb_t
callback)
Register BLE Mesh Config Client Model callback.
Parameters
esp_err_t esp_ble_mesh_register_config_server_callback(esp_ble_mesh_cfg_server_cb_t
callback)
Register BLE Mesh Config Server Model callback.
Parameters
esp_err_t esp_ble_mesh_config_client_get_state(esp_ble_mesh_client_common_param_t
*params, esp_ble_mesh_cfg_client_get_state_t
*get_state)
Get the value of Config Server Model states using the Config Client Model get messages.
Note If you want to find the opcodes and corresponding meanings accepted by this API, please refer to
esp_ble_mesh_opcode_config_client_get_t in esp_ble_mesh_defs.h
Parameters
• [in] params: Pointer to BLE Mesh common client parameters.
• [in] get_state: Pointer to a union, each kind of opcode corresponds to one structure inside.
Shall not be set to NULL.
esp_err_t esp_ble_mesh_config_client_set_state(esp_ble_mesh_client_common_param_t
*params, esp_ble_mesh_cfg_client_set_state_t
*set_state)
Set the value of the Configuration Server Model states using the Config Client Model set messages.
esp_ble_mesh_opcode_config_client_set_t in esp_ble_mesh_defs.h
Parameters

• [in] set_state: Pointer to a union, each kind of opcode corresponds to one structure inside.
Unions
union esp_ble_mesh_cfg_client_get_state_t
#include <esp_ble_mesh_config_model_api.h> For ESP_BLE_MESH_MODEL_OP_BEACON_GET
ESP_BLE_MESH_MODEL_OP_COMPOSITION_DATA_GET ESP_BLE_MESH_MODEL_OP_DEFAULT_TTL_GET
ESP_BLE_MESH_MODEL_OP_GATT_PROXY_GET ESP_BLE_MESH_MODEL_OP_RELAY_GET
ESP_BLE_MESH_MODEL_OP_MODEL_PUB_GET ESP_BLE_MESH_MODEL_OP_FRIEND_GET
ESP_BLE_MESH_MODEL_OP_HEARTBEAT_PUB_GET ESP_BLE_MESH_MODEL_OP_HEARTBEAT_SUB_GET
the get_state parameter in the esp_ble_mesh_config_client_get_state function should not be set to NULL.
Public Members
esp_ble_mesh_cfg_model_pub_get_t model_pub_get
For ESP_BLE_MESH_MODEL_OP_MODEL_PUB_GET.
esp_ble_mesh_cfg_composition_data_get_t comp_data_get
For ESP_BLE_MESH_MODEL_OP_COMPOSITION_DATA_GET.
esp_ble_mesh_cfg_sig_model_sub_get_t sig_model_sub_get
For ESP_BLE_MESH_MODEL_OP_SIG_MODEL_SUB_GET
esp_ble_mesh_cfg_vnd_model_sub_get_t vnd_model_sub_get
For ESP_BLE_MESH_MODEL_OP_VENDOR_MODEL_SUB_GET
esp_ble_mesh_cfg_app_key_get_t app_key_get
For ESP_BLE_MESH_MODEL_OP_APP_KEY_GET.
esp_ble_mesh_cfg_node_identity_get_t node_identity_get
For ESP_BLE_MESH_MODEL_OP_NODE_IDENTITY_GET.
esp_ble_mesh_cfg_sig_model_app_get_t sig_model_app_get
For ESP_BLE_MESH_MODEL_OP_SIG_MODEL_APP_GET
esp_ble_mesh_cfg_vnd_model_app_get_t vnd_model_app_get
For ESP_BLE_MESH_MODEL_OP_VENDOR_MODEL_APP_GET
esp_ble_mesh_cfg_kr_phase_get_t kr_phase_get
For ESP_BLE_MESH_MODEL_OP_KEY_REFRESH_PHASE_GET
esp_ble_mesh_cfg_lpn_polltimeout_get_t lpn_pollto_get
For ESP_BLE_MESH_MODEL_OP_LPN_POLLTIMEOUT_GET
union esp_ble_mesh_cfg_client_set_state_t
#include <esp_ble_mesh_config_model_api.h> For ESP_BLE_MESH_MODEL_OP_BEACON_SET
ESP_BLE_MESH_MODEL_OP_DEFAULT_TTL_SET ESP_BLE_MESH_MODEL_OP_GATT_PROXY_SET
ESP_BLE_MESH_MODEL_OP_RELAY_SET ESP_BLE_MESH_MODEL_OP_MODEL_PUB_SET
ESP_BLE_MESH_MODEL_OP_MODEL_SUB_ADD ESP_BLE_MESH_MODEL_OP_MODEL_SUB_VIRTUAL_ADDR
ESP_BLE_MESH_MODEL_OP_MODEL_SUB_DELETE ESP_BLE_MESH_MODEL_OP_MODEL_SUB_VIRTUAL_AD
ESP_BLE_MESH_MODEL_OP_MODEL_SUB_OVERWRITE ESP_BLE_MESH_MODEL_OP_MODEL_SUB_VIRTUAL
ESP_BLE_MESH_MODEL_OP_NET_KEY_ADD ESP_BLE_MESH_MODEL_OP_APP_KEY_ADD
ESP_BLE_MESH_MODEL_OP_MODEL_APP_BIND ESP_BLE_MESH_MODEL_OP_NODE_RESET
ESP_BLE_MESH_MODEL_OP_FRIEND_SET ESP_BLE_MESH_MODEL_OP_HEARTBEAT_PUB_SET
ESP_BLE_MESH_MODEL_OP_HEARTBEAT_SUB_SET the set_state parameter in the
esp_ble_mesh_config_client_set_state function should not be set to NULL.
Public Members
esp_ble_mesh_cfg_beacon_set_t beacon_set
For ESP_BLE_MESH_MODEL_OP_BEACON_SET

esp_ble_mesh_cfg_default_ttl_set_t default_ttl_set
For ESP_BLE_MESH_MODEL_OP_DEFAULT_TTL_SET
esp_ble_mesh_cfg_friend_set_t friend_set
For ESP_BLE_MESH_MODEL_OP_FRIEND_SET
esp_ble_mesh_cfg_gatt_proxy_set_t gatt_proxy_set
For ESP_BLE_MESH_MODEL_OP_GATT_PROXY_SET
esp_ble_mesh_cfg_relay_set_t relay_set
For ESP_BLE_MESH_MODEL_OP_RELAY_SET
esp_ble_mesh_cfg_net_key_add_t net_key_add
For ESP_BLE_MESH_MODEL_OP_NET_KEY_ADD
esp_ble_mesh_cfg_app_key_add_t app_key_add
For ESP_BLE_MESH_MODEL_OP_APP_KEY_ADD
esp_ble_mesh_cfg_model_app_bind_t model_app_bind
For ESP_BLE_MESH_MODEL_OP_MODEL_APP_BIND
esp_ble_mesh_cfg_model_pub_set_t model_pub_set
For ESP_BLE_MESH_MODEL_OP_MODEL_PUB_SET
esp_ble_mesh_cfg_model_sub_add_t model_sub_add
For ESP_BLE_MESH_MODEL_OP_MODEL_SUB_ADD
esp_ble_mesh_cfg_model_sub_delete_t model_sub_delete
For ESP_BLE_MESH_MODEL_OP_MODEL_SUB_DELETE
esp_ble_mesh_cfg_model_sub_overwrite_t model_sub_overwrite
For ESP_BLE_MESH_MODEL_OP_MODEL_SUB_OVERWRITE
esp_ble_mesh_cfg_model_sub_va_add_t model_sub_va_add
For ESP_BLE_MESH_MODEL_OP_MODEL_SUB_VIRTUAL_ADDR_ADD
esp_ble_mesh_cfg_model_sub_va_delete_t model_sub_va_delete
For ESP_BLE_MESH_MODEL_OP_MODEL_SUB_VIRTUAL_ADDR_DELETE
esp_ble_mesh_cfg_model_sub_va_overwrite_t model_sub_va_overwrite
For ESP_BLE_MESH_MODEL_OP_MODEL_SUB_VIRTUAL_ADDR_OVERWRITE
esp_ble_mesh_cfg_heartbeat_pub_set_t heartbeat_pub_set
For ESP_BLE_MESH_MODEL_OP_HEARTBEAT_PUB_SET
esp_ble_mesh_cfg_heartbeat_sub_set_t heartbeat_sub_set
For ESP_BLE_MESH_MODEL_OP_HEARTBEAT_SUB_SET
esp_ble_mesh_cfg_model_pub_va_set_t model_pub_va_set
For ESP_BLE_MESH_MODEL_OP_MODEL_PUB_VIRTUAL_ADDR_SET
esp_ble_mesh_cfg_model_sub_delete_all_t model_sub_delete_all
For ESP_BLE_MESH_MODEL_OP_MODEL_SUB_DELETE_ALL
esp_ble_mesh_cfg_net_key_update_t net_key_update
For ESP_BLE_MESH_MODEL_OP_NET_KEY_UPDATE
esp_ble_mesh_cfg_net_key_delete_t net_key_delete
For ESP_BLE_MESH_MODEL_OP_NET_KEY_DELETE
esp_ble_mesh_cfg_app_key_update_t app_key_update
For ESP_BLE_MESH_MODEL_OP_APP_KEY_UPDATE
esp_ble_mesh_cfg_app_key_delete_t app_key_delete
For ESP_BLE_MESH_MODEL_OP_APP_KEY_DELETE
esp_ble_mesh_cfg_node_identity_set_t node_identity_set
For ESP_BLE_MESH_MODEL_OP_NODE_IDENTITY_SET

esp_ble_mesh_cfg_model_app_unbind_t model_app_unbind
For ESP_BLE_MESH_MODEL_OP_MODEL_APP_UNBIND
esp_ble_mesh_cfg_kr_phase_set_t kr_phase_set
For ESP_BLE_MESH_MODEL_OP_KEY_REFRESH_PHASE_SET
esp_ble_mesh_cfg_net_transmit_set_t net_transmit_set
For ESP_BLE_MESH_MODEL_OP_NETWORK_TRANSMIT_SET
union esp_ble_mesh_cfg_client_common_cb_param_t
#include <esp_ble_mesh_config_model_api.h> Configuration Client Model received message union.
Public Members
esp_ble_mesh_cfg_beacon_status_cb_t beacon_status
The beacon status value
esp_ble_mesh_cfg_comp_data_status_cb_t comp_data_status
The composition data status value
esp_ble_mesh_cfg_default_ttl_status_cb_t default_ttl_status
The default_ttl status value
esp_ble_mesh_cfg_gatt_proxy_status_cb_t gatt_proxy_status
The gatt_proxy status value
esp_ble_mesh_cfg_relay_status_cb_t relay_status
The relay status value
esp_ble_mesh_cfg_model_pub_status_cb_t model_pub_status
The model publication status value
esp_ble_mesh_cfg_model_sub_status_cb_t model_sub_status
The model subscription status value
esp_ble_mesh_cfg_net_key_status_cb_t netkey_status
The netkey status value
esp_ble_mesh_cfg_app_key_status_cb_t appkey_status
The appkey status value
esp_ble_mesh_cfg_mod_app_status_cb_t model_app_status
The model app status value
esp_ble_mesh_cfg_friend_status_cb_t friend_status
The friend status value
esp_ble_mesh_cfg_hb_pub_status_cb_t heartbeat_pub_status
The heartbeat publication status value
esp_ble_mesh_cfg_hb_sub_status_cb_t heartbeat_sub_status
The heartbeat subscription status value
esp_ble_mesh_cfg_net_trans_status_cb_t net_transmit_status
The network transmit status value
esp_ble_mesh_cfg_model_sub_list_cb_t model_sub_list
The model subscription list value
esp_ble_mesh_cfg_net_key_list_cb_t netkey_list
The network key index list value
esp_ble_mesh_cfg_app_key_list_cb_t appkey_list
The application key index list value
esp_ble_mesh_cfg_node_id_status_cb_t node_identity_status
The node identity status value

esp_ble_mesh_cfg_model_app_list_cb_t model_app_list
The model application key index list value
esp_ble_mesh_cfg_kr_phase_status_cb_t kr_phase_status
The key refresh phase status value
esp_ble_mesh_cfg_lpn_pollto_status_cb_t lpn_timeout_status
The low power node poll timeout status value
union esp_ble_mesh_cfg_server_state_change_t
#include <esp_ble_mesh_config_model_api.h> Configuration Server model state change value union.
Public Members
esp_ble_mesh_state_change_cfg_mod_pub_set_t mod_pub_set
The recv_op in ctx can be used to decide which state is changed.Config Model Publication Set
esp_ble_mesh_state_change_cfg_model_sub_add_t mod_sub_add
Config Model Subscription Add
esp_ble_mesh_state_change_cfg_model_sub_delete_t mod_sub_delete
Config Model Subscription Delete
esp_ble_mesh_state_change_cfg_netkey_add_t netkey_add
Config NetKey Add
esp_ble_mesh_state_change_cfg_netkey_update_t netkey_update
Config NetKey Update
esp_ble_mesh_state_change_cfg_netkey_delete_t netkey_delete
Config NetKey Delete
esp_ble_mesh_state_change_cfg_appkey_add_t appkey_add
Config AppKey Add
esp_ble_mesh_state_change_cfg_appkey_update_t appkey_update
Config AppKey Update
esp_ble_mesh_state_change_cfg_appkey_delete_t appkey_delete
Config AppKey Delete
esp_ble_mesh_state_change_cfg_model_app_bind_t mod_app_bind
Config Model App Bind
esp_ble_mesh_state_change_cfg_model_app_unbind_t mod_app_unbind
Config Model App Unbind
esp_ble_mesh_state_change_cfg_kr_phase_set_t kr_phase_set
Config Key Refresh Phase Set
union esp_ble_mesh_cfg_server_cb_value_t
#include <esp_ble_mesh_config_model_api.h> Configuration Server model callback value union.
Public Members
esp_ble_mesh_cfg_server_state_change_t state_change
ESP_BLE_MESH_CFG_SERVER_STATE_CHANGE_EVT
Structures
struct esp_ble_mesh_cfg_srv
Configuration Server Model context

Public Members
Pointer to Configuration Server Model
uint8_t net_transmit
Network Transmit state
uint8_t relay
Relay Mode state
uint8_t relay_retransmit
Relay Retransmit state
uint8_t beacon
Secure Network Beacon state
uint8_t gatt_proxy
GATT Proxy state
uint8_t friend_state
Friend state
uint8_t default_ttl
Default TTL
Heartbeat Publication timer
uint16_t dst
Destination address for Heartbeat messages
uint16_t count
Number of Heartbeat messages to be sent
Number of Heartbeat messages received
uint8_t period
Period for sending Heartbeat messages
uint8_t ttl
TTL to be used when sending Heartbeat messages
uint16_t feature
Bit field indicating features that trigger Heartbeat messages when changed
uint16_t net_idx
NetKey Index used by Heartbeat Publication
struct esp_ble_mesh_cfg_srv::[anonymous] heartbeat_pub
Heartbeat Publication
int64_t expiry
Timestamp when Heartbeat subscription period is expired
uint16_t src
Source address for Heartbeat messages
uint8_t min_hops
Minimum hops when receiving Heartbeat messages
uint8_t max_hops
Maximum hops when receiving Heartbeat messages
esp_ble_mesh_cb_t heartbeat_recv_cb
Optional heartbeat subscription tracking function
struct esp_ble_mesh_cfg_srv::[anonymous] heartbeat_sub
Heartbeat Subscription

struct esp_ble_mesh_cfg_composition_data_get_t
Parameters of Config Composition Data Get.
Public Members
uint8_t page
Page number of the Composition Data.
struct esp_ble_mesh_cfg_model_pub_get_t
Parameters of Config Model Publication Get.
Public Members
The element address
uint16_t model_id
The model id
uint16_t company_id
The company id, if not a vendor model, shall set to 0xFFFF
struct esp_ble_mesh_cfg_sig_model_sub_get_t
Parameters of Config SIG Model Subscription Get.
Public Members
The element address
uint16_t model_id
The model id
struct esp_ble_mesh_cfg_vnd_model_sub_get_t
Parameters of Config Vendor Model Subscription Get.
Public Members
The element address
uint16_t model_id
The model id
uint16_t company_id
struct esp_ble_mesh_cfg_app_key_get_t
Parameters of Config AppKey Get.
Public Members
uint16_t net_idx
The network key index
struct esp_ble_mesh_cfg_node_identity_get_t
Parameters of Config Node Identity Get.

Public Members
uint16_t net_idx
struct esp_ble_mesh_cfg_sig_model_app_get_t
Parameters of Config SIG Model App Get.
Public Members
The element address
uint16_t model_id
The model id
struct esp_ble_mesh_cfg_vnd_model_app_get_t
Parameters of Config Vendor Model App Get.
Public Members
The element address
uint16_t model_id
The model id
uint16_t company_id
struct esp_ble_mesh_cfg_kr_phase_get_t
Parameters of Config Key Refresh Phase Get.
Public Members
uint16_t net_idx
struct esp_ble_mesh_cfg_lpn_polltimeout_get_t
Parameters of Config Low Power Node PollTimeout Get.
Public Members
uint16_t lpn_addr
The unicast address of the Low Power node
struct esp_ble_mesh_cfg_beacon_set_t
Parameters of Config Beacon Set.
Public Members
uint8_t beacon
New Secure Network Beacon state
struct esp_ble_mesh_cfg_default_ttl_set_t
Parameters of Config Default TTL Set.

Public Members
uint8_t ttl
The default TTL state value
struct esp_ble_mesh_cfg_friend_set_t
Parameters of Config Friend Set.
Public Members
The friend state value
struct esp_ble_mesh_cfg_gatt_proxy_set_t
Parameters of Config GATT Proxy Set.
Public Members
uint8_t gatt_proxy
The GATT Proxy state value
struct esp_ble_mesh_cfg_relay_set_t
Parameters of Config Relay Set.
Public Members
uint8_t relay
The relay value
uint8_t relay_retransmit
The relay retransmit value
struct esp_ble_mesh_cfg_net_key_add_t
Parameters of Config NetKey Add.
Public Members
uint16_t net_idx
uint8_t net_key[16]
The network key value
struct esp_ble_mesh_cfg_app_key_add_t
Parameters of Config AppKey Add.
Public Members
uint16_t net_idx
uint16_t app_idx
The app key index
uint8_t app_key[16]
The app key value
struct esp_ble_mesh_cfg_model_app_bind_t
Parameters of Config Model App Bind.

Public Members
The element address
uint16_t model_app_idx
Index of the app key to bind with the model
uint16_t model_id
The model id
uint16_t company_id
struct esp_ble_mesh_cfg_model_pub_set_t
Parameters of Config Model Publication Set.
Public Members
The element address
Value of the publish address
uint16_t publish_app_idx
Index of the application key
bool cred_flag
Value of the Friendship Credential Flag
uint8_t publish_ttl
Default TTL value for the publishing messages
uint8_t publish_period
Period for periodic status publishing
uint8_t publish_retransmit
Number of retransmissions and number of 50-millisecond steps between retransmissions
uint16_t model_id
The model id
uint16_t company_id
struct esp_ble_mesh_cfg_model_sub_add_t
Parameters of Config Model Subscription Add.
Public Members
The element address
uint16_t sub_addr
The address to be added to the Subscription List
uint16_t model_id
The model id
uint16_t company_id
struct esp_ble_mesh_cfg_model_sub_delete_t
Parameters of Config Model Subscription Delete.

Public Members
The element address
uint16_t sub_addr
The address to be removed from the Subscription List
uint16_t model_id
The model id
uint16_t company_id
struct esp_ble_mesh_cfg_model_sub_overwrite_t
Parameters of Config Model Subscription Overwrite.
Public Members
The element address
uint16_t sub_addr
The address to be added to the Subscription List
uint16_t model_id
The model id
uint16_t company_id
struct esp_ble_mesh_cfg_model_sub_va_add_t
Parameters of Config Model Subscription Virtual Address Add.
Public Members
The element address
uint8_t label_uuid[16]
The Label UUID of the virtual address to be added to the Subscription List
uint16_t model_id
The model id
uint16_t company_id
struct esp_ble_mesh_cfg_model_sub_va_delete_t
Parameters of Config Model Subscription Virtual Address Delete.
Public Members
The element address
The Label UUID of the virtual address to be removed from the Subscription List
uint16_t model_id
The model id

uint16_t company_id
struct esp_ble_mesh_cfg_model_sub_va_overwrite_t
Parameters of Config Model Subscription Virtual Address Overwrite.
Public Members
The element address
The Label UUID of the virtual address to be added to the Subscription List
uint16_t model_id
The model id
uint16_t company_id
struct esp_ble_mesh_cfg_model_pub_va_set_t
Parameters of Config Model Publication Virtual Address Set.
Public Members
The element address
Value of the Label UUID publish address
uint16_t publish_app_idx
bool cred_flag
uint8_t publish_ttl
Default TTL value for the publishing messages
uint8_t publish_period
uint8_t publish_retransmit
uint16_t model_id
The model id
uint16_t company_id
struct esp_ble_mesh_cfg_model_sub_delete_all_t
Parameters of Config Model Subscription Delete All.
Public Members
The element address
uint16_t model_id
The model id

uint16_t company_id
struct esp_ble_mesh_cfg_net_key_update_t
Parameters of Config NetKey Update.
Public Members
uint16_t net_idx
uint8_t net_key[16]
The network key value
struct esp_ble_mesh_cfg_net_key_delete_t
Parameters of Config NetKey Delete.
Public Members
uint16_t net_idx
struct esp_ble_mesh_cfg_app_key_update_t
Parameters of Config AppKey Update.
Public Members
uint16_t net_idx
uint16_t app_idx
The app key index
uint8_t app_key[16]
The app key value
struct esp_ble_mesh_cfg_app_key_delete_t
Parameters of Config AppKey Delete.
Public Members
uint16_t net_idx
uint16_t app_idx
The app key index
struct esp_ble_mesh_cfg_node_identity_set_t
Parameters of Config Node Identity Set.
Public Members
uint16_t net_idx
uint8_t identity
New Node Identity state
struct esp_ble_mesh_cfg_model_app_unbind_t
Parameters of Config Model App Unbind.

Public Members
The element address
uint16_t model_app_idx
Index of the app key to bind with the model
uint16_t model_id
The model id
uint16_t company_id
struct esp_ble_mesh_cfg_kr_phase_set_t
Parameters of Config Key Refresh Phase Set.
Public Members
uint16_t net_idx
uint8_t transition
New Key Refresh Phase Transition
struct esp_ble_mesh_cfg_net_transmit_set_t
Parameters of Config Network Transmit Set.
Public Members
uint8_t net_transmit
Network Transmit State
struct esp_ble_mesh_cfg_heartbeat_pub_set_t
Parameters of Config Model Heartbeat Publication Set.
Public Members
uint16_t dst
uint8_t count
Number of Heartbeat messages to be sent
uint8_t period
uint8_t ttl
uint16_t feature
Bit field indicating features that trigger Heartbeat messages when changed
uint16_t net_idx
NetKey Index
struct esp_ble_mesh_cfg_heartbeat_sub_set_t
Parameters of Config Model Heartbeat Subscription Set.

Public Members
uint16_t src
uint16_t dst
uint8_t period
Period for receiving Heartbeat messages
struct esp_ble_mesh_cfg_beacon_status_cb_t
Parameter of Config Beacon Status
Public Members
uint8_t beacon
Secure Network Beacon state value
struct esp_ble_mesh_cfg_comp_data_status_cb_t
Parameters of Config Composition Data Status
Public Members
uint8_t page
Page number of the Composition Data
struct net_buf_simple *composition_data
Pointer to Composition Data for the identified page
struct esp_ble_mesh_cfg_default_ttl_status_cb_t
Parameter of Config Default TTL Status
Public Members
uint8_t default_ttl
Default TTL state value
struct esp_ble_mesh_cfg_gatt_proxy_status_cb_t
Parameter of Config GATT Proxy Status
Public Members
uint8_t gatt_proxy
GATT Proxy state value
struct esp_ble_mesh_cfg_relay_status_cb_t
Parameters of Config Relay Status
Public Members
uint8_t relay
Relay state value
uint8_t retransmit
Relay retransmit value(number of retransmissions and number of 10-millisecond steps between retrans-
missions)

struct esp_ble_mesh_cfg_model_pub_status_cb_t
Parameters of Config Model Publication Status
Public Members
uint8_t status
Status Code for the request message
Address of the element
Value of the publish address
uint16_t app_idx
bool cred_flag
uint8_t ttl
Default TTL value for the outgoing messages
uint8_t period
uint8_t transmit
uint16_t company_id
Company ID
uint16_t model_id
Model ID
struct esp_ble_mesh_cfg_model_sub_status_cb_t
Parameters of Config Model Subscription Status
Public Members
uint8_t status
uint16_t sub_addr
Value of the address
uint16_t company_id
Company ID
uint16_t model_id
Model ID
struct esp_ble_mesh_cfg_net_key_status_cb_t
Parameters of Config NetKey Status
Public Members
uint8_t status

uint16_t net_idx
Index of the NetKey
struct esp_ble_mesh_cfg_app_key_status_cb_t
Parameters of Config AppKey Status
Public Members
uint8_t status
uint16_t net_idx
Index of the NetKey
uint16_t app_idx
struct esp_ble_mesh_cfg_mod_app_status_cb_t
Parameters of Config Model App Status
Public Members
uint8_t status
uint16_t app_idx
uint16_t company_id
Company ID
uint16_t model_id
Model ID
struct esp_ble_mesh_cfg_friend_status_cb_t
Parameter of Config Friend Status
Public Members
Friend state value
struct esp_ble_mesh_cfg_hb_pub_status_cb_t
Parameters of Config Heartbeat Publication Status
Public Members
uint8_t status
uint16_t dst
uint8_t count
Number of Heartbeat messages remaining to be sent
uint8_t period

uint8_t ttl
uint16_t features
Features that trigger Heartbeat messages when changed
uint16_t net_idx
Index of the NetKey
struct esp_ble_mesh_cfg_hb_sub_status_cb_t
Parameters of Config Heartbeat Subscription Status
Public Members
uint8_t status
uint16_t src
uint16_t dst
uint8_t period
Remaining Period for processing Heartbeat messages
uint8_t count
Number of Heartbeat messages received
uint8_t min_hops
Minimum hops when receiving Heartbeat messages
uint8_t max_hops
struct esp_ble_mesh_cfg_net_trans_status_cb_t
Parameters of Config Network Transmit Status
Public Members
uint8_t net_trans_count : 3
Number of transmissions for each Network PDU originating from the node
uint8_t net_trans_step : 5
struct esp_ble_mesh_cfg_model_sub_list_cb_t
Parameters of Config SIG/Vendor Subscription List
Public Members
uint8_t status
uint16_t company_id
Company ID
uint16_t model_id
Model ID

struct net_buf_simple *sub_addr

A block of all addresses from the Subscription List
struct esp_ble_mesh_cfg_net_key_list_cb_t
Parameter of Config NetKey List
Public Members
struct net_buf_simple *net_idx

A list of NetKey Indexes known to the node
struct esp_ble_mesh_cfg_app_key_list_cb_t
Parameters of Config AppKey List
Public Members
uint8_t status
uint16_t net_idx
NetKey Index of the NetKey that the AppKeys are bound to
struct net_buf_simple *app_idx
A list of AppKey indexes that are bound to the NetKey identified by NetKeyIndex
struct esp_ble_mesh_cfg_node_id_status_cb_t
Parameters of Config Node Identity Status
Public Members
uint8_t status
uint16_t net_idx
Index of the NetKey
uint8_t identity
Node Identity state
struct esp_ble_mesh_cfg_model_app_list_cb_t
Parameters of Config SIG/Vendor Model App List
Public Members
uint8_t status
uint16_t company_id
Company ID
uint16_t model_id
Model ID
struct net_buf_simple *app_idx
All AppKey indexes bound to the Model
struct esp_ble_mesh_cfg_kr_phase_status_cb_t
Parameters of Config Key Refresh Phase Status

Public Members
uint8_t status
uint16_t net_idx
Index of the NetKey
uint8_t phase
Key Refresh Phase state
struct esp_ble_mesh_cfg_lpn_pollto_status_cb_t
Parameters of Config Low Power Node PollTimeout Status
Public Members
uint16_t lpn_addr
The unicast address of the Low Power node
int32_t poll_timeout
The current value of the PollTimeout timer of the Low Power node
struct esp_ble_mesh_cfg_client_cb_param_t
Configuration Client Model callback parameters
Public Members
int error_code
Appropriate error code
esp_ble_mesh_client_common_param_t *params
The client common parameters
esp_ble_mesh_cfg_client_common_cb_param_t status_cb
The config status message callback values
struct esp_ble_mesh_state_change_cfg_mod_pub_set_t
Configuration Server model related context.
Public Members
Element Address
uint16_t pub_addr
Publish Address
uint16_t app_idx
AppKey Index
bool cred_flag
Friendship Credential Flag
uint8_t pub_ttl
Publish TTL
uint8_t pub_period
Publish Period
uint8_t pub_retransmit
Publish Retransmit

uint16_t company_id
Company ID
uint16_t model_id
Model ID
struct esp_ble_mesh_state_change_cfg_model_sub_add_t
Parameters of Config Model Subscription Add
Public Members
Element Address
uint16_t sub_addr
Subscription Address
uint16_t company_id
Company ID
uint16_t model_id
Model ID
struct esp_ble_mesh_state_change_cfg_model_sub_delete_t
Parameters of Config Model Subscription Delete
Public Members
Element Address
uint16_t sub_addr
Subscription Address
uint16_t company_id
Company ID
uint16_t model_id
Model ID
struct esp_ble_mesh_state_change_cfg_netkey_add_t
Parameters of Config NetKey Add
Public Members
uint16_t net_idx
NetKey Index
uint8_t net_key[16]
NetKey
struct esp_ble_mesh_state_change_cfg_netkey_update_t
Parameters of Config NetKey Update
Public Members
uint16_t net_idx
NetKey Index
uint8_t net_key[16]
NetKey

struct esp_ble_mesh_state_change_cfg_netkey_delete_t
Parameter of Config NetKey Delete
Public Members
uint16_t net_idx
NetKey Index
struct esp_ble_mesh_state_change_cfg_appkey_add_t
Parameters of Config AppKey Add
Public Members
uint16_t net_idx
NetKey Index
uint16_t app_idx
AppKey Index
uint8_t app_key[16]
AppKey
struct esp_ble_mesh_state_change_cfg_appkey_update_t
Parameters of Config AppKey Update
Public Members
uint16_t net_idx
NetKey Index
uint16_t app_idx
AppKey Index
uint8_t app_key[16]
AppKey
struct esp_ble_mesh_state_change_cfg_appkey_delete_t
Parameters of Config AppKey Delete
Public Members
uint16_t net_idx
NetKey Index
uint16_t app_idx
AppKey Index
struct esp_ble_mesh_state_change_cfg_model_app_bind_t
Parameters of Config Model App Bind
Public Members
Element Address
uint16_t app_idx
AppKey Index
uint16_t company_id
Company ID

uint16_t model_id
Model ID
struct esp_ble_mesh_state_change_cfg_model_app_unbind_t
Parameters of Config Model App Unbind
Public Members
Element Address
uint16_t app_idx
AppKey Index
uint16_t company_id
Company ID
uint16_t model_id
Model ID
struct esp_ble_mesh_state_change_cfg_kr_phase_set_t
Parameters of Config Key Refresh Phase Set
Public Members
uint16_t net_idx
NetKey Index
uint8_t kr_phase
New Key Refresh Phase Transition
struct esp_ble_mesh_cfg_server_cb_param_t
Configuration Server model callback parameters
Public Members
Pointer to the server model structure
Context of the received message
esp_ble_mesh_cfg_server_cb_value_t value
Value of the received configuration messages
Macros
ESP_BLE_MESH_MODEL_CFG_SRV(srv_data)
Define a new Config Server Model.
Note The Config Server Model can only be included by a Primary Element.
Return New Config Server Model instance.
Parameters
• srv_data: Pointer to a unique Config Server Model user_data.
ESP_BLE_MESH_MODEL_CFG_CLI(cli_data)
Define a new Config Client Model.
Note The Config Client Model can only be included by a Primary Element.
Return New Config Client Model instance.
Parameters
• cli_data: Pointer to a unique struct esp_ble_mesh_client_t.

Type Definitions
typedef struct esp_ble_mesh_cfg_srv esp_ble_mesh_cfg_srv_t
Configuration Server Model context
typedef void (*esp_ble_mesh_cfg_client_cb_t)(esp_ble_mesh_cfg_client_cb_event_t event,
esp_ble_mesh_cfg_client_cb_param_t
*param)
Bluetooth Mesh Config Client and Server Model functions.
Configuration Client Model callback function type
Parameters
• param: Pointer to callback parameter
typedef void (*esp_ble_mesh_cfg_server_cb_t)(esp_ble_mesh_cfg_server_cb_event_t event,
esp_ble_mesh_cfg_server_cb_param_t
*param)
Configuration Server Model callback function type.
Parameters
Enumerations
enum esp_ble_mesh_cfg_client_cb_event_t
This enum value is the event of Configuration Client Model
Values:
ESP_BLE_MESH_CFG_CLIENT_GET_STATE_EVT
ESP_BLE_MESH_CFG_CLIENT_SET_STATE_EVT
ESP_BLE_MESH_CFG_CLIENT_PUBLISH_EVT
ESP_BLE_MESH_CFG_CLIENT_TIMEOUT_EVT
ESP_BLE_MESH_CFG_CLIENT_EVT_MAX
enum esp_ble_mesh_cfg_server_cb_event_t
This enum value is the event of Configuration Server model
Values:
ESP_BLE_MESH_CFG_SERVER_STATE_CHANGE_EVT
ESP_BLE_MESH_CFG_SERVER_EVT_MAX
Health Client/Server Models
Header File
• components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_health_model_api.h
Functions
esp_err_t esp_ble_mesh_register_health_client_callback(esp_ble_mesh_health_client_cb_t
callback)
Register BLE Mesh Health Model callback, the callback will report Health Client & Server Model events.
Parameters
esp_err_t esp_ble_mesh_register_health_server_callback(esp_ble_mesh_health_server_cb_t
callback)
Register BLE Mesh Health Server Model callback.


Parameters
esp_err_t esp_ble_mesh_health_client_get_state(esp_ble_mesh_client_common_param_t
*params, esp_ble_mesh_health_client_get_state_t
*get_state)
This function is called to get the Health Server states using the Health Client Model get messages.
esp_ble_mesh_opcode_health_client_get_t in esp_ble_mesh_defs.h
Parameters
• [in] get_state: Pointer to a union, each kind of opcode corresponds to one structure inside.
esp_err_t esp_ble_mesh_health_client_set_state(esp_ble_mesh_client_common_param_t
*params, esp_ble_mesh_health_client_set_state_t
*set_state)
This function is called to set the Health Server states using the Health Client Model set messages.
esp_ble_mesh_opcode_health_client_set_t in esp_ble_mesh_defs.h
Parameters
• [in] set_state: Pointer to a union, each kind of opcode corresponds to one structure inside.
esp_err_t esp_ble_mesh_health_server_fault_update(esp_ble_mesh_elem_t *element)
This function is called by the Health Server Model to update the context of its Health Current status.
Parameters
• [in] element: The element to which the Health Server Model belongs.
Unions
union esp_ble_mesh_health_client_get_state_t
#include <esp_ble_mesh_health_model_api.h> For ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_GET
ESP_BLE_MESH_MODEL_OP_ATTENTION_GET ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_GET
the get_state parameter in the esp_ble_mesh_health_client_get_state function should not be set to NULL.
Public Members
esp_ble_mesh_health_fault_get_t fault_get
For ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_GET.
union esp_ble_mesh_health_client_set_state_t
#include <esp_ble_mesh_health_model_api.h> For ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_CLEAR
ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_CLEAR_UNACK ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT
ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_TEST_UNACK ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_
ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_SET_UNACK ESP_BLE_MESH_MODEL_OP_ATTENTION_SET
ESP_BLE_MESH_MODEL_OP_ATTENTION_SET_UNACK the set_state parameter in the
esp_ble_mesh_health_client_set_state function should not be set to NULL.
Public Members
esp_ble_mesh_health_attention_set_t attention_set
For ESP_BLE_MESH_MODEL_OP_ATTENTION_SET or ESP_BLE_MESH_MODEL_OP_ATTENTION_SET_UNA

esp_ble_mesh_health_period_set_t period_set
For ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_SET or
ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_SET_UNACK.
esp_ble_mesh_health_fault_test_t fault_test
For ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_TEST or
ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_TEST_UNACK.
esp_ble_mesh_health_fault_clear_t fault_clear
For ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_CLEAR or
ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_CLEAR_UNACK.
union esp_ble_mesh_health_client_common_cb_param_t
#include <esp_ble_mesh_health_model_api.h> Health Client Model received message union.
Public Members
esp_ble_mesh_health_current_status_cb_t current_status
The health current status value
esp_ble_mesh_health_fault_status_cb_t fault_status
The health fault status value
esp_ble_mesh_health_period_status_cb_t period_status
The health period status value
esp_ble_mesh_health_attention_status_cb_t attention_status
The health attention status value
union esp_ble_mesh_health_server_cb_param_t
#include <esp_ble_mesh_health_model_api.h> Health Server Model callback parameters union.
Public Members
esp_ble_mesh_health_fault_update_comp_cb_t fault_update_comp
ESP_BLE_MESH_HEALTH_SERVER_FAULT_UPDATE_COMP_EVT
esp_ble_mesh_health_fault_clear_cb_t fault_clear
ESP_BLE_MESH_HEALTH_SERVER_FAULT_CLEAR_EVT
esp_ble_mesh_health_fault_test_cb_t fault_test
ESP_BLE_MESH_HEALTH_SERVER_FAULT_TEST_EVT
esp_ble_mesh_health_attention_on_cb_t attention_on
ESP_BLE_MESH_HEALTH_SERVER_ATTENTION_ON_EVT
esp_ble_mesh_health_attention_off_cb_t attention_off
ESP_BLE_MESH_HEALTH_SERVER_ATTENTION_OFF_EVT
Structures
struct esp_ble_mesh_health_srv_cb_t
ESP BLE Mesh Health Server callback
Public Members
esp_ble_mesh_cb_t fault_clear
Clear health registered faults. Initialized by the stack.
esp_ble_mesh_cb_t fault_test
Run a specific health test. Initialized by the stack.

esp_ble_mesh_cb_t attention_on
Health attention on callback. Initialized by the stack.
esp_ble_mesh_cb_t attention_off
Health attention off callback. Initialized by the stack.
struct esp_ble_mesh_health_test_t
ESP BLE Mesh Health Server test Context
Public Members
uint8_t id_count
Number of Health self-test ID
const uint8_t *test_ids
Array of Health self-test IDs
uint16_t company_id
Company ID used to identify the Health Fault state
uint8_t prev_test_id
Current test ID of the health fault test
uint8_t current_faults[ESP_BLE_MESH_HEALTH_FAULT_ARRAY_SIZE]
Array of current faults
uint8_t registered_faults[ESP_BLE_MESH_HEALTH_FAULT_ARRAY_SIZE]
Array of registered faults
struct esp_ble_mesh_health_srv_t
ESP BLE Mesh Health Server Model Context
Public Members
Pointer to Health Server Model
esp_ble_mesh_health_srv_cb_t health_cb
Health callback struct
struct k_delayed_work attention_timer
Attention Timer state
bool attention_timer_start
Attention Timer start flag
esp_ble_mesh_health_test_t health_test
Health Server fault test
struct esp_ble_mesh_health_fault_get_t
Parameter of Health Fault Get
Public Members
uint16_t company_id
Bluetooth assigned 16-bit Company ID
struct esp_ble_mesh_health_attention_set_t
Parameter of Health Attention Set

Public Members
uint8_t attention
Value of the Attention Timer state
struct esp_ble_mesh_health_period_set_t
Parameter of Health Period Set
Public Members
uint8_t fast_period_divisor
Divider for the Publish Period
struct esp_ble_mesh_health_fault_test_t
Parameter of Health Fault Test
Public Members
uint16_t company_id
uint8_t test_id
ID of a specific test to be performed
struct esp_ble_mesh_health_fault_clear_t
Parameter of Health Fault Clear
Public Members
uint16_t company_id
struct esp_ble_mesh_health_current_status_cb_t
Parameters of Health Current Status
Public Members
uint8_t test_id
ID of a most recently performed test
uint16_t company_id
struct net_buf_simple *fault_array
FaultArray field contains a sequence of 1-octet fault values
struct esp_ble_mesh_health_fault_status_cb_t
Parameters of Health Fault Status
Public Members
uint8_t test_id
ID of a most recently performed test
uint16_t company_id
struct net_buf_simple *fault_array
FaultArray field contains a sequence of 1-octet fault values

struct esp_ble_mesh_health_period_status_cb_t
Parameter of Health Period Status
Public Members
uint8_t fast_period_divisor
Divider for the Publish Period
struct esp_ble_mesh_health_attention_status_cb_t
Parameter of Health Attention Status
Public Members
uint8_t attention
Value of the Attention Timer state
struct esp_ble_mesh_health_client_cb_param_t
Health Client Model callback parameters
Public Members
int error_code
The client common parameters.
esp_ble_mesh_health_client_common_cb_param_t status_cb
The health message status callback values
struct esp_ble_mesh_health_fault_update_comp_cb_t
Parameter of publishing Health Current Status completion event
Public Members
int error_code
The result of publishing Health Current Status
esp_ble_mesh_elem_t *element
Pointer to the element which contains the Health Server Model
struct esp_ble_mesh_health_fault_clear_cb_t
Parameters of Health Fault Clear event
Public Members
Pointer to the Health Server Model
uint16_t company_id
struct esp_ble_mesh_health_fault_test_cb_t
Parameters of Health Fault Test event

Public Members
uint8_t test_id
ID of a specific test to be performed
uint16_t company_id
struct esp_ble_mesh_health_attention_on_cb_t
Parameter of Health Attention On event
Public Members
uint8_t time
Duration of attention timer on (in seconds)
struct esp_ble_mesh_health_attention_off_cb_t
Parameter of Health Attention Off event
Public Members
Macros
ESP_BLE_MESH_MODEL_HEALTH_SRV(srv, pub)
Define a new Health Server Model.
Note The Health Server Model can only be included by a Primary Element.
Return New Health Server Model instance.
Parameters
• srv: Pointer to the unique struct esp_ble_mesh_health_srv_t.
• pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
ESP_BLE_MESH_MODEL_HEALTH_CLI(cli_data)
Define a new Health Client Model.
Note This API needs to be called for each element on which the application needs to have a Health Client
Model.
Return New Health Client Model instance.
Parameters
• cli_data: Pointer to the unique struct esp_ble_mesh_client_t.
ESP_BLE_MESH_HEALTH_PUB_DEFINE(_name, _max, _role)
A helper to define a health publication context
Parameters
• _name: Name given to the publication context variable.
• _max: Maximum number of faults the element can have.
• _role: Role of the device which contains the model.
ESP_BLE_MESH_HEALTH_STANDARD_TEST
SIG identifier of Health Fault Test. 0x01 ~ 0xFF: Vendor Specific Test.

ESP_BLE_MESH_NO_FAULT
Fault values of Health Fault Test. 0x33 ~ 0x7F: Reserved for Future Use. 0x80 ~ 0xFF: Vendor Specific
Warning/Error.
ESP_BLE_MESH_BATTERY_LOW_WARNING
ESP_BLE_MESH_BATTERY_LOW_ERROR
ESP_BLE_MESH_SUPPLY_VOLTAGE_TOO_LOW_WARNING
ESP_BLE_MESH_SUPPLY_VOLTAGE_TOO_LOW_ERROR
ESP_BLE_MESH_SUPPLY_VOLTAGE_TOO_HIGH_WARNING
ESP_BLE_MESH_SUPPLY_VOLTAGE_TOO_HIGH_ERROR
ESP_BLE_MESH_POWER_SUPPLY_INTERRUPTED_WARNING
ESP_BLE_MESH_POWER_SUPPLY_INTERRUPTED_ERROR
ESP_BLE_MESH_NO_LOAD_WARNING
ESP_BLE_MESH_NO_LOAD_ERROR
ESP_BLE_MESH_OVERLOAD_WARNING
ESP_BLE_MESH_OVERLOAD_ERROR
ESP_BLE_MESH_OVERHEAT_WARNING
ESP_BLE_MESH_OVERHEAT_ERROR
ESP_BLE_MESH_CONDENSATION_WARNING
ESP_BLE_MESH_CONDENSATION_ERROR
ESP_BLE_MESH_VIBRATION_WARNING
ESP_BLE_MESH_VIBRATION_ERROR
ESP_BLE_MESH_CONFIGURATION_WARNING
ESP_BLE_MESH_CONFIGURATION_ERROR
ESP_BLE_MESH_ELEMENT_NOT_CALIBRATED_WARNING
ESP_BLE_MESH_ELEMENT_NOT_CALIBRATED_ERROR
ESP_BLE_MESH_MEMORY_WARNING
ESP_BLE_MESH_MEMORY_ERROR
ESP_BLE_MESH_SELF_TEST_WARNING
ESP_BLE_MESH_SELF_TEST_ERROR
ESP_BLE_MESH_INPUT_TOO_LOW_WARNING
ESP_BLE_MESH_INPUT_TOO_LOW_ERROR
ESP_BLE_MESH_INPUT_TOO_HIGH_WARNING
ESP_BLE_MESH_INPUT_TOO_HIGH_ERROR
ESP_BLE_MESH_INPUT_NO_CHANGE_WARNING
ESP_BLE_MESH_INPUT_NO_CHANGE_ERROR
ESP_BLE_MESH_ACTUATOR_BLOCKED_WARNING
ESP_BLE_MESH_ACTUATOR_BLOCKED_ERROR
ESP_BLE_MESH_HOUSING_OPENED_WARNING
ESP_BLE_MESH_HOUSING_OPENED_ERROR
ESP_BLE_MESH_TAMPER_WARNING

ESP_BLE_MESH_TAMPER_ERROR
ESP_BLE_MESH_DEVICE_MOVED_WARNING
ESP_BLE_MESH_DEVICE_MOVED_ERROR
ESP_BLE_MESH_DEVICE_DROPPED_WARNING
ESP_BLE_MESH_DEVICE_DROPPED_ERROR
ESP_BLE_MESH_OVERFLOW_WARNING
ESP_BLE_MESH_OVERFLOW_ERROR
ESP_BLE_MESH_EMPTY_WARNING
ESP_BLE_MESH_EMPTY_ERROR
ESP_BLE_MESH_INTERNAL_BUS_WARNING
ESP_BLE_MESH_INTERNAL_BUS_ERROR
ESP_BLE_MESH_MECHANISM_JAMMED_WARNING
ESP_BLE_MESH_MECHANISM_JAMMED_ERROR
ESP_BLE_MESH_HEALTH_FAULT_ARRAY_SIZE
Type Definitions
typedef void (*esp_ble_mesh_health_client_cb_t)(esp_ble_mesh_health_client_cb_event_t
event, esp_ble_mesh_health_client_cb_param_t
*param)
Bluetooth Mesh Health Client and Server Model function.
Health Client Model callback function type
Parameters
typedef void (*esp_ble_mesh_health_server_cb_t)(esp_ble_mesh_health_server_cb_event_t
event, esp_ble_mesh_health_server_cb_param_t
*param)
Health Server Model callback function type.
Parameters
Enumerations
enum esp_ble_mesh_health_client_cb_event_t
This enum value is the event of Health Client Model
Values:
ESP_BLE_MESH_HEALTH_CLIENT_GET_STATE_EVT
ESP_BLE_MESH_HEALTH_CLIENT_SET_STATE_EVT
ESP_BLE_MESH_HEALTH_CLIENT_PUBLISH_EVT
ESP_BLE_MESH_HEALTH_CLIENT_TIMEOUT_EVT
ESP_BLE_MESH_HEALTH_CLIENT_EVT_MAX
enum esp_ble_mesh_health_server_cb_event_t
This enum value is the event of Health Server Model
Values:
ESP_BLE_MESH_HEALTH_SERVER_FAULT_UPDATE_COMP_EVT

ESP_BLE_MESH_HEALTH_SERVER_FAULT_CLEAR_EVT
ESP_BLE_MESH_HEALTH_SERVER_FAULT_TEST_EVT
ESP_BLE_MESH_HEALTH_SERVER_ATTENTION_ON_EVT
ESP_BLE_MESH_HEALTH_SERVER_ATTENTION_OFF_EVT
ESP_BLE_MESH_HEALTH_SERVER_EVT_MAX
Generic Client/Server Models
Header File
• components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_generic_model_api.h
Functions
esp_err_t esp_ble_mesh_register_generic_client_callback(esp_ble_mesh_generic_client_cb_t
callback)
Register BLE Mesh Generic Client Model callback.
Parameters
esp_err_t esp_ble_mesh_generic_client_get_state(esp_ble_mesh_client_common_param_t
*params,
esp_ble_mesh_generic_client_get_state_t
*get_state)
Get the value of Generic Server Model states using the Generic Client Model get messages.
esp_ble_mesh_generic_message_opcode_t in esp_ble_mesh_defs.h
Parameters
• [in] get_state: Pointer to generic get message value. Shall not be set to NULL.
esp_err_t esp_ble_mesh_generic_client_set_state(esp_ble_mesh_client_common_param_t
*params,
esp_ble_mesh_generic_client_set_state_t
*set_state)
Set the value of Generic Server Model states using the Generic Client Model set messages.
esp_ble_mesh_generic_message_opcode_t in esp_ble_mesh_defs.h
Parameters
• [in] set_state: Pointer to generic set message value. Shall not be set to NULL.
esp_err_t esp_ble_mesh_register_generic_server_callback(esp_ble_mesh_generic_server_cb_t
callback)
Register BLE Mesh Generic Server Model callback.
Parameters
Unions
union esp_ble_mesh_generic_client_get_state_t
#include <esp_ble_mesh_generic_model_api.h> Generic Client Model get message union.

Public Members
esp_ble_mesh_gen_user_property_get_t user_property_get
For ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTY_GET
esp_ble_mesh_gen_admin_property_get_t admin_property_get
For ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_GET
esp_ble_mesh_gen_manufacturer_property_get_t manufacturer_property_get
For ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_SET
esp_ble_mesh_gen_client_properties_get_t client_properties_get
For ESP_BLE_MESH_MODEL_OP_GEN_CLIENT_PROPERTIES_GET
union esp_ble_mesh_generic_client_set_state_t
#include <esp_ble_mesh_generic_model_api.h> Generic Client Model set message union.
Public Members
esp_ble_mesh_gen_onoff_set_t onoff_set
For ESP_BLE_MESH_MODEL_OP_GEN_ONOFF_SET & ESP_BLE_MESH_MODEL_OP_GEN_ONOFF_SET_UN
esp_ble_mesh_gen_level_set_t level_set
For ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_SET & ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_SET_UNA
esp_ble_mesh_gen_delta_set_t delta_set
For ESP_BLE_MESH_MODEL_OP_GEN_DELTA_SET & ESP_BLE_MESH_MODEL_OP_GEN_DELTA_SET_UN
esp_ble_mesh_gen_move_set_t move_set
For ESP_BLE_MESH_MODEL_OP_GEN_MOVE_SET & ESP_BLE_MESH_MODEL_OP_GEN_MOVE_SET_UNA
esp_ble_mesh_gen_def_trans_time_set_t def_trans_time_set
For ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIME_SET &
ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIME_SET_UNACK
esp_ble_mesh_gen_onpowerup_set_t power_set
For ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_SET &
ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_SET_UNACK
esp_ble_mesh_gen_power_level_set_t power_level_set
For ESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_SET &
ESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_SET_UNACK
esp_ble_mesh_gen_power_default_set_t power_default_set
For ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULT_SET &
ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULT_SET_UNACK
esp_ble_mesh_gen_power_range_set_t power_range_set
For ESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_SET &
ESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_SET_UNACK
esp_ble_mesh_gen_loc_global_set_t loc_global_set
For ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_SET &
ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_SET_UNACK
esp_ble_mesh_gen_loc_local_set_t loc_local_set
For ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_SET &
ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_SET_UNACK
esp_ble_mesh_gen_user_property_set_t user_property_set
For ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTY_SET &
ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTY_SET_UNACK
esp_ble_mesh_gen_admin_property_set_t admin_property_set
For ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_SET &
ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_SET_UNACK

esp_ble_mesh_gen_manufacturer_property_set_t manufacturer_property_set
For ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_SET &
ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_SET_UNACK
union esp_ble_mesh_gen_client_status_cb_t
#include <esp_ble_mesh_generic_model_api.h> Generic Client Model received message union.
Public Members
esp_ble_mesh_gen_onoff_status_cb_t onoff_status
For ESP_BLE_MESH_MODEL_OP_GEN_ONOFF_STATUS
esp_ble_mesh_gen_level_status_cb_t level_status
For ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_STATUS
esp_ble_mesh_gen_def_trans_time_status_cb_t def_trans_time_status
For ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIME_STATUS
esp_ble_mesh_gen_onpowerup_status_cb_t onpowerup_status
For ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_STATUS
esp_ble_mesh_gen_power_level_status_cb_t power_level_status
For ESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_STATUS
esp_ble_mesh_gen_power_last_status_cb_t power_last_status
For ESP_BLE_MESH_MODEL_OP_GEN_POWER_LAST_STATUS
esp_ble_mesh_gen_power_default_status_cb_t power_default_status
For ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULT_STATUS
esp_ble_mesh_gen_power_range_status_cb_t power_range_status
For ESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_STATUS
esp_ble_mesh_gen_battery_status_cb_t battery_status
For ESP_BLE_MESH_MODEL_OP_GEN_BATTERY_STATUS
esp_ble_mesh_gen_loc_global_status_cb_t location_global_status
For ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_STATUS
esp_ble_mesh_gen_loc_local_status_cb_t location_local_status
ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_STATUS
esp_ble_mesh_gen_user_properties_status_cb_t user_properties_status
ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTIES_STATUS
esp_ble_mesh_gen_user_property_status_cb_t user_property_status
ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTY_STATUS
esp_ble_mesh_gen_admin_properties_status_cb_t admin_properties_status
ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTIES_STATUS
esp_ble_mesh_gen_admin_property_status_cb_t admin_property_status
ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_STATUS
esp_ble_mesh_gen_manufacturer_properties_status_cb_t manufacturer_properties_status
ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTIES_STATUS
esp_ble_mesh_gen_manufacturer_property_status_cb_t manufacturer_property_status
ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_STATUS
esp_ble_mesh_gen_client_properties_status_cb_t client_properties_status
ESP_BLE_MESH_MODEL_OP_GEN_CLIENT_PROPERTIES_STATUS
union esp_ble_mesh_generic_server_state_change_t
#include <esp_ble_mesh_generic_model_api.h> Generic Server Model state change value union.

Public Members
esp_ble_mesh_state_change_gen_onoff_set_t onoff_set
The recv_op in ctx can be used to decide which state is changed.Generic OnOff Set
esp_ble_mesh_state_change_gen_level_set_t level_set
Generic Level Set
esp_ble_mesh_state_change_gen_delta_set_t delta_set
Generic Delta Set
esp_ble_mesh_state_change_gen_move_set_t move_set
Generic Move Set
esp_ble_mesh_state_change_gen_def_trans_time_set_t def_trans_time_set
Generic Default Transition Time Set
esp_ble_mesh_state_change_gen_onpowerup_set_t onpowerup_set
Generic OnPowerUp Set
esp_ble_mesh_state_change_gen_power_level_set_t power_level_set
Generic Power Level Set
esp_ble_mesh_state_change_gen_power_default_set_t power_default_set
Generic Power Default Set
esp_ble_mesh_state_change_gen_power_range_set_t power_range_set
Generic Power Range Set
esp_ble_mesh_state_change_gen_loc_global_set_t loc_global_set
Generic Location Global Set
esp_ble_mesh_state_change_gen_loc_local_set_t loc_local_set
Generic Location Local Set
esp_ble_mesh_state_change_gen_user_property_set_t user_property_set
Generic User Property Set
esp_ble_mesh_state_change_gen_admin_property_set_t admin_property_set
Generic Admin Property Set
esp_ble_mesh_state_change_gen_manu_property_set_t manu_property_set
Generic Manufacturer Property Set
union esp_ble_mesh_generic_server_recv_get_msg_t
#include <esp_ble_mesh_generic_model_api.h> Generic Server Model received get message union.
Public Members
esp_ble_mesh_server_recv_gen_user_property_get_t user_property
Generic User Property Get
esp_ble_mesh_server_recv_gen_admin_property_get_t admin_property
Generic Admin Property Get
esp_ble_mesh_server_recv_gen_manufacturer_property_get_t manu_property
Generic Manufacturer Property Get
esp_ble_mesh_server_recv_gen_client_properties_get_t client_properties
Generic Client Properties Get
union esp_ble_mesh_generic_server_recv_set_msg_t
#include <esp_ble_mesh_generic_model_api.h> Generic Server Model received set message union.

Public Members
esp_ble_mesh_server_recv_gen_onoff_set_t onoff
Generic OnOff Set/Generic OnOff Set Unack
esp_ble_mesh_server_recv_gen_level_set_t level
Generic Level Set/Generic Level Set Unack
esp_ble_mesh_server_recv_gen_delta_set_t delta
Generic Delta Set/Generic Delta Set Unack
esp_ble_mesh_server_recv_gen_move_set_t move
Generic Move Set/Generic Move Set Unack
esp_ble_mesh_server_recv_gen_def_trans_time_set_t def_trans_time
Generic Default Transition Time Set/Generic Default Transition Time Set Unack
esp_ble_mesh_server_recv_gen_onpowerup_set_t onpowerup
Generic OnPowerUp Set/Generic OnPowerUp Set Unack
esp_ble_mesh_server_recv_gen_power_level_set_t power_level
Generic Power Level Set/Generic Power Level Set Unack
esp_ble_mesh_server_recv_gen_power_default_set_t power_default
Generic Power Default Set/Generic Power Default Set Unack
esp_ble_mesh_server_recv_gen_power_range_set_t power_range
Generic Power Range Set/Generic Power Range Set Unack
esp_ble_mesh_server_recv_gen_loc_global_set_t location_global
Generic Location Global Set/Generic Location Global Set Unack
esp_ble_mesh_server_recv_gen_loc_local_set_t location_local
Generic Location Local Set/Generic Location Local Set Unack
esp_ble_mesh_server_recv_gen_user_property_set_t user_property
Generic User Property Set/Generic User Property Set Unack
esp_ble_mesh_server_recv_gen_admin_property_set_t admin_property
Generic Admin Property Set/Generic Admin Property Set Unack
esp_ble_mesh_server_recv_gen_manufacturer_property_set_t manu_property
Generic Manufacturer Property Set/Generic Manufacturer Property Set Unack
union esp_ble_mesh_generic_server_cb_value_t
#include <esp_ble_mesh_generic_model_api.h> Generic Server Model callback value union.
Public Members
esp_ble_mesh_generic_server_state_change_t state_change
ESP_BLE_MESH_GENERIC_SERVER_STATE_CHANGE_EVT
esp_ble_mesh_generic_server_recv_get_msg_t get
ESP_BLE_MESH_GENERIC_SERVER_RECV_GET_MSG_EVT
esp_ble_mesh_generic_server_recv_set_msg_t set
ESP_BLE_MESH_GENERIC_SERVER_RECV_SET_MSG_EVT
Structures
struct esp_ble_mesh_gen_onoff_set_t
Bluetooth Mesh Generic Client Model Get and Set parameters structure.
Parameters of Generic OnOff Set.

Public Members
bool op_en
Indicate if optional parameters are included
uint8_t onoff
Target value of Generic OnOff state
uint8_t tid
Transaction ID
uint8_t trans_time
Time to complete state transition (optional)
uint8_t delay
Indicate message execution delay (C.1)
struct esp_ble_mesh_gen_level_set_t
Parameters of Generic Level Set.
Public Members
bool op_en
int16_t level
Target value of Generic Level state
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_gen_delta_set_t
Parameters of Generic Delta Set.
Public Members
bool op_en
int32_t level
Delta change of Generic Level state
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_gen_move_set_t
Parameters of Generic Move Set.
Public Members
bool op_en

int16_t delta_level
Delta Level step to calculate Move speed for Generic Level state
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_gen_def_trans_time_set_t
Parameter of Generic Default Transition Time Set.
Public Members
uint8_t trans_time
The value of the Generic Default Transition Time state
struct esp_ble_mesh_gen_onpowerup_set_t
Parameter of Generic OnPowerUp Set.
Public Members
uint8_t onpowerup
struct esp_ble_mesh_gen_power_level_set_t
Parameters of Generic Power Level Set.
Public Members
bool op_en
uint16_t power
Target value of Generic Power Actual state
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_gen_power_default_set_t
Parameter of Generic Power Default Set.
Public Members
uint16_t power
The value of the Generic Power Default state
struct esp_ble_mesh_gen_power_range_set_t
Parameters of Generic Power Range Set.

Public Members
uint16_t range_min
Value of Range Min field of Generic Power Range state
uint16_t range_max
Value of Range Max field of Generic Power Range state
struct esp_ble_mesh_gen_loc_global_set_t
Parameters of Generic Location Global Set.
Public Members
int32_t global_latitude
Global Coordinates (Latitude)
int32_t global_longitude
Global Coordinates (Longitude)
int16_t global_altitude
Global Altitude
struct esp_ble_mesh_gen_loc_local_set_t
Parameters of Generic Location Local Set.
Public Members
int16_t local_north
Local Coordinates (North)
int16_t local_east
Local Coordinates (East)
int16_t local_altitude
Local Altitude
uint8_t floor_number
Floor Number
uint16_t uncertainty
Uncertainty
struct esp_ble_mesh_gen_user_property_get_t
Parameter of Generic User Property Get.
Public Members
uint16_t property_id
Property ID identifying a Generic User Property
struct esp_ble_mesh_gen_user_property_set_t
Parameters of Generic User Property Set.
Public Members
struct net_buf_simple *property_value
Raw value for the User Property

struct esp_ble_mesh_gen_admin_property_get_t
Parameter of Generic Admin Property Get.
Public Members
Property ID identifying a Generic Admin Property
struct esp_ble_mesh_gen_admin_property_set_t
Parameters of Generic Admin Property Set.
Public Members
uint8_t user_access
Enumeration indicating user access
Raw value for the Admin Property
struct esp_ble_mesh_gen_manufacturer_property_get_t
Parameter of Generic Manufacturer Property Get.
Public Members
Property ID identifying a Generic Manufacturer Property
struct esp_ble_mesh_gen_manufacturer_property_set_t
Parameters of Generic Manufacturer Property Set.
Public Members
uint8_t user_access
struct esp_ble_mesh_gen_client_properties_get_t
Parameter of Generic Client Properties Get.
Public Members
A starting Client Property ID present within an element
struct esp_ble_mesh_gen_onoff_status_cb_t
Bluetooth Mesh Generic Client Model Get and Set callback parameters structure.
Parameters of Generic OnOff Status.

Public Members
bool op_en
uint8_t present_onoff
Current value of Generic OnOff state
uint8_t target_onoff
Target value of Generic OnOff state (optional)
uint8_t remain_time
Time to complete state transition (C.1)
struct esp_ble_mesh_gen_level_status_cb_t
Parameters of Generic Level Status.
Public Members
bool op_en
int16_t present_level
Current value of Generic Level state
int16_t target_level
Target value of the Generic Level state (optional)
uint8_t remain_time
struct esp_ble_mesh_gen_def_trans_time_status_cb_t
Parameter of Generic Default Transition Time Status.
Public Members
uint8_t trans_time
struct esp_ble_mesh_gen_onpowerup_status_cb_t
Parameter of Generic OnPowerUp Status.
Public Members
uint8_t onpowerup
struct esp_ble_mesh_gen_power_level_status_cb_t
Parameters of Generic Power Level Status.
Public Members
bool op_en
uint16_t present_power
Current value of Generic Power Actual state
uint16_t target_power
Target value of Generic Power Actual state (optional)

uint8_t remain_time
struct esp_ble_mesh_gen_power_last_status_cb_t
Parameter of Generic Power Last Status.
Public Members
uint16_t power
The value of the Generic Power Last state
struct esp_ble_mesh_gen_power_default_status_cb_t
Parameter of Generic Power Default Status.
Public Members
uint16_t power
The value of the Generic Default Last state
struct esp_ble_mesh_gen_power_range_status_cb_t
Parameters of Generic Power Range Status.
Public Members
uint8_t status_code
uint16_t range_min
uint16_t range_max
struct esp_ble_mesh_gen_battery_status_cb_t
Parameters of Generic Battery Status.
Public Members
uint32_t battery_level : 8
Value of Generic Battery Level state
uint32_t time_to_discharge : 24
Value of Generic Battery Time to Discharge state
uint32_t time_to_charge : 24
Value of Generic Battery Time to Charge state
uint32_t flags : 8
Value of Generic Battery Flags state
struct esp_ble_mesh_gen_loc_global_status_cb_t
Parameters of Generic Location Global Status.
Public Members

Global Altitude
struct esp_ble_mesh_gen_loc_local_status_cb_t
Parameters of Generic Location Local Status.
Public Members
int16_t local_north
int16_t local_east
Local Altitude
Floor Number
Uncertainty
struct esp_ble_mesh_gen_user_properties_status_cb_t
Parameter of Generic User Properties Status.
Public Members
struct net_buf_simple *property_ids

Buffer contains a sequence of N User Property IDs
struct esp_ble_mesh_gen_user_property_status_cb_t
Parameters of Generic User Property Status.
Public Members
bool op_en
uint8_t user_access
Enumeration indicating user access (optional)
Raw value for the User Property (C.1)
struct esp_ble_mesh_gen_admin_properties_status_cb_t
Parameter of Generic Admin Properties Status.
Public Members

Buffer contains a sequence of N Admin Property IDs
struct esp_ble_mesh_gen_admin_property_status_cb_t
Parameters of Generic Admin Property Status.

Public Members
bool op_en
uint8_t user_access
Raw value for the Admin Property (C.1)
struct esp_ble_mesh_gen_manufacturer_properties_status_cb_t
Parameter of Generic Manufacturer Properties Status.
Public Members

Buffer contains a sequence of N Manufacturer Property IDs
struct esp_ble_mesh_gen_manufacturer_property_status_cb_t
Parameters of Generic Manufacturer Property Status.
Public Members
bool op_en
uint8_t user_access
Raw value for the Manufacturer Property (C.1)
struct esp_ble_mesh_gen_client_properties_status_cb_t
Parameter of Generic Client Properties Status.
Public Members

Buffer contains a sequence of N Client Property IDs
struct esp_ble_mesh_generic_client_cb_param_t
Generic Client Model callback parameters
Public Members
int error_code
esp_ble_mesh_gen_client_status_cb_t status_cb
The generic status message callback values

struct esp_ble_mesh_gen_onoff_state_t
Parameters of Generic OnOff state
Public Members
uint8_t onoff
The present value of the Generic OnOff state
uint8_t target_onoff
The target value of the Generic OnOff state
struct esp_ble_mesh_gen_onoff_srv_t
User data of Generic OnOff Server Model
Public Members
Pointer to the Generic OnOff Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
esp_ble_mesh_gen_onoff_state_t state
Parameters of the Generic OnOff state
esp_ble_mesh_last_msg_info_t last
Parameters of the last received set message
esp_ble_mesh_state_transition_t transition
Parameters of state transition
struct esp_ble_mesh_gen_level_state_t
Parameters of Generic Level state
Public Members
int16_t level
The present value of the Generic Level state
int16_t target_level
The target value of the Generic Level state
int16_t last_level
When a new transaction starts, level should be set to last_last, and use level + incoming delta to
calculate the target level. In another word, last_level is used to record level of the last transaction,
and last_delta is used to record the previously received delta_level value.The last value of the Generic
Level state
int32_t last_delta
The last delta change of the Generic Level state
bool move_start
Indicate if the transition of the Generic Level state has been started
bool positive
Indicate if the transition is positive or negative
struct esp_ble_mesh_gen_level_srv_t
User data of Generic Level Server Model

Public Members
Pointer to the Generic Level Server Model. Initialized internally.
esp_ble_mesh_gen_level_state_t state
Parameters of the Generic Level state
int32_t tt_delta_level
Delta change value of level state transition
struct esp_ble_mesh_gen_def_trans_time_state_t
Parameter of Generic Default Transition Time state
Public Members
uint8_t trans_time
struct esp_ble_mesh_gen_def_trans_time_srv_t
User data of Generic Default Transition Time Server Model
Public Members
Pointer to the Generic Default Transition Time Server Model. Initialized internally.
esp_ble_mesh_gen_def_trans_time_state_t state
Parameters of the Generic Default Transition Time state
struct esp_ble_mesh_gen_onpowerup_state_t
Parameter of Generic OnPowerUp state
Public Members
uint8_t onpowerup
struct esp_ble_mesh_gen_power_onoff_srv_t
User data of Generic Power OnOff Server Model
Public Members
Pointer to the Generic Power OnOff Server Model. Initialized internally.

esp_ble_mesh_gen_onpowerup_state_t *state
Parameters of the Generic OnPowerUp state
struct esp_ble_mesh_gen_power_onoff_setup_srv_t
User data of Generic Power OnOff Setup Server Model
Public Members
Pointer to the Generic Power OnOff Setup Server Model. Initialized internally.
esp_ble_mesh_gen_onpowerup_state_t *state
Parameters of the Generic OnPowerUp state
struct esp_ble_mesh_gen_power_level_state_t
Parameters of Generic Power Level state
Public Members
uint16_t power_actual
The present value of the Generic Power Actual state
uint16_t target_power_actual
The target value of the Generic Power Actual state
uint16_t power_last
The value of the Generic Power Last state
uint16_t power_default
uint8_t status_code
The status code of setting Generic Power Range state
uint16_t power_range_min
The minimum value of the Generic Power Range state
uint16_t power_range_max
The maximum value of the Generic Power Range state
struct esp_ble_mesh_gen_power_level_srv_t
User data of Generic Power Level Server Model
Public Members
Pointer to the Generic Power Level Server Model. Initialized internally.
esp_ble_mesh_gen_power_level_state_t *state
Parameters of the Generic Power Level state

int32_t tt_delta_level
Delta change value of level state transition
struct esp_ble_mesh_gen_power_level_setup_srv_t
User data of Generic Power Level Setup Server Model
Public Members
Pointer to the Generic Power Level Setup Server Model. Initialized internally.
esp_ble_mesh_gen_power_level_state_t *state
Parameters of the Generic Power Level state
struct esp_ble_mesh_gen_battery_state_t
Parameters of Generic Battery state
Public Members
uint32_t battery_level : 8
The value of the Generic Battery Level state
uint32_t time_to_discharge : 24
The value of the Generic Battery Time to Discharge state
uint32_t time_to_charge : 24
The value of the Generic Battery Time to Charge state
uint32_t battery_flags : 8
The value of the Generic Battery Flags state
struct esp_ble_mesh_gen_battery_srv_t
User data of Generic Battery Server Model
Public Members
Pointer to the Generic Battery Server Model. Initialized internally.
esp_ble_mesh_gen_battery_state_t state
Parameters of the Generic Battery state
struct esp_ble_mesh_gen_location_state_t
Parameters of Generic Location state
Public Members
The value of the Global Latitude field
The value of the Global Longitude field
The value of the Global Altitude field

int16_t local_north
The value of the Local North field
int16_t local_east
The value of the Local East field
The value of the Local Altitude field
The value of the Floor Number field
The value of the Uncertainty field
struct esp_ble_mesh_gen_location_srv_t
User data of Generic Location Server Model
Public Members
Pointer to the Generic Location Server Model. Initialized internally.
esp_ble_mesh_gen_location_state_t *state
Parameters of the Generic Location state
struct esp_ble_mesh_gen_location_setup_srv_t
User data of Generic Location Setup Server Model
Public Members
Pointer to the Generic Location Setup Server Model. Initialized internally.
esp_ble_mesh_gen_location_state_t *state
Parameters of the Generic Location state
struct esp_ble_mesh_generic_property_t
Parameters of Generic Property states
Public Members
uint16_t id
The value of User/Admin/Manufacturer Property ID
uint8_t user_access
The value of User Access field
uint8_t admin_access
The value of Admin Access field
uint8_t manu_access
The value of Manufacturer Access field
struct net_buf_simple *val
The value of User/Admin/Manufacturer Property

struct esp_ble_mesh_gen_user_prop_srv_t
User data of Generic User Property Server Model
Public Members
Pointer to the Generic User Property Server Model. Initialized internally.
uint8_t property_count
Generic User Property count
esp_ble_mesh_generic_property_t *properties
Parameters of the Generic User Property state
struct esp_ble_mesh_gen_admin_prop_srv_t
User data of Generic Admin Property Server Model
Public Members
Pointer to the Generic Admin Property Server Model. Initialized internally.
Generic Admin Property count
Parameters of the Generic Admin Property state
struct esp_ble_mesh_gen_manu_prop_srv_t
User data of Generic Manufacturer Property Server Model
Public Members
Pointer to the Generic Manufacturer Property Server Model. Initialized internally.
Generic Manufacturer Property count
Parameters of the Generic Manufacturer Property state
struct esp_ble_mesh_gen_client_prop_srv_t
User data of Generic Client Property Server Model
Public Members
Pointer to the Generic Client Property Server Model. Initialized internally.

uint8_t id_count
Generic Client Property ID count
uint16_t *property_ids
Parameters of the Generic Client Property state
struct esp_ble_mesh_state_change_gen_onoff_set_t
Parameter of Generic OnOff Set state change event
Public Members
uint8_t onoff
The value of Generic OnOff state
struct esp_ble_mesh_state_change_gen_level_set_t
Parameter of Generic Level Set state change event
Public Members
int16_t level
The value of Generic Level state
struct esp_ble_mesh_state_change_gen_delta_set_t
Parameter of Generic Delta Set state change event
Public Members
int16_t level
struct esp_ble_mesh_state_change_gen_move_set_t
Parameter of Generic Move Set state change event
Public Members
int16_t level
struct esp_ble_mesh_state_change_gen_def_trans_time_set_t
Parameter of Generic Default Transition Time Set state change event
Public Members
uint8_t trans_time
The value of Generic Default Transition Time state
struct esp_ble_mesh_state_change_gen_onpowerup_set_t
Parameter of Generic OnPowerUp Set state change event
Public Members
uint8_t onpowerup
The value of Generic OnPowerUp state
struct esp_ble_mesh_state_change_gen_power_level_set_t
Parameter of Generic Power Level Set state change event

Public Members
uint16_t power
The value of Generic Power Actual state
struct esp_ble_mesh_state_change_gen_power_default_set_t
Parameter of Generic Power Default Set state change event
Public Members
uint16_t power
The value of Generic Power Default state
struct esp_ble_mesh_state_change_gen_power_range_set_t
Parameters of Generic Power Range Set state change event
Public Members
uint16_t range_min
The minimum value of Generic Power Range state
uint16_t range_max
The maximum value of Generic Power Range state
struct esp_ble_mesh_state_change_gen_loc_global_set_t
Parameters of Generic Location Global Set state change event
Public Members
int32_t latitude
The Global Latitude value of Generic Location state
int32_t longitude
The Global Longitude value of Generic Location state
int16_t altitude
The Global Altitude value of Generic Location state
struct esp_ble_mesh_state_change_gen_loc_local_set_t
Parameters of Generic Location Local Set state change event
Public Members
int16_t north
The Local North value of Generic Location state
int16_t east
The Local East value of Generic Location state
int16_t altitude
The Local Altitude value of Generic Location state
The Floor Number value of Generic Location state
The Uncertainty value of Generic Location state
struct esp_ble_mesh_state_change_gen_user_property_set_t
Parameters of Generic User Property Set state change event

Public Members
uint16_t id
The property id of Generic User Property state
struct net_buf_simple *value
The property value of Generic User Property state
struct esp_ble_mesh_state_change_gen_admin_property_set_t
Parameters of Generic Admin Property Set state change event
Public Members
uint16_t id
The property id of Generic Admin Property state
uint8_t access
The property access of Generic Admin Property state
struct net_buf_simple *value
The property value of Generic Admin Property state
struct esp_ble_mesh_state_change_gen_manu_property_set_t
Parameters of Generic Manufacturer Property Set state change event
Public Members
uint16_t id
The property id of Generic Manufacturer Property state
uint8_t access
The property value of Generic Manufacturer Property state
struct esp_ble_mesh_server_recv_gen_user_property_get_t
Context of the received Generic User Property Get message
Public Members
struct esp_ble_mesh_server_recv_gen_admin_property_get_t
Context of the received Generic Admin Property Get message
Public Members
struct esp_ble_mesh_server_recv_gen_manufacturer_property_get_t
Context of the received Generic Manufacturer Property message
Public Members
struct esp_ble_mesh_server_recv_gen_client_properties_get_t
Context of the received Generic Client Properties Get message

Public Members
A starting Client Property ID present within an element
struct esp_ble_mesh_server_recv_gen_onoff_set_t
Context of the received Generic OnOff Set message
Public Members
bool op_en
uint8_t onoff
Target value of Generic OnOff state
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_server_recv_gen_level_set_t
Context of the received Generic Level Set message
Public Members
bool op_en
int16_t level
Target value of Generic Level state
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_server_recv_gen_delta_set_t
Context of the received Generic Delta Set message
Public Members
bool op_en
int32_t delta_level
Delta change of Generic Level state
uint8_t tid
Transaction ID
uint8_t trans_time

uint8_t delay
struct esp_ble_mesh_server_recv_gen_move_set_t
Context of the received Generic Move Set message
Public Members
bool op_en
int16_t delta_level
Delta Level step to calculate Move speed for Generic Level state
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_server_recv_gen_def_trans_time_set_t
Context of the received Generic Default Transition Time Set message
Public Members
uint8_t trans_time
struct esp_ble_mesh_server_recv_gen_onpowerup_set_t
Context of the received Generic OnPowerUp Set message
Public Members
uint8_t onpowerup
struct esp_ble_mesh_server_recv_gen_power_level_set_t
Context of the received Generic Power Level Set message
Public Members
bool op_en
uint16_t power
Target value of Generic Power Actual state
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_server_recv_gen_power_default_set_t
Context of the received Generic Power Default Set message

Public Members
uint16_t power
struct esp_ble_mesh_server_recv_gen_power_range_set_t
Context of the received Generic Power Range Set message
Public Members
uint16_t range_min
uint16_t range_max
struct esp_ble_mesh_server_recv_gen_loc_global_set_t
Context of the received Generic Location Global Set message
Public Members
Global Altitude
struct esp_ble_mesh_server_recv_gen_loc_local_set_t
Context of the received Generic Location Local Set message
Public Members
int16_t local_north
int16_t local_east
Local Altitude
Floor Number
Uncertainty
struct esp_ble_mesh_server_recv_gen_user_property_set_t
Context of the received Generic User Property Set message
Public Members
Raw value for the User Property

struct esp_ble_mesh_server_recv_gen_admin_property_set_t
Context of the received Generic Admin Property Set message
Public Members
uint8_t user_access
Raw value for the Admin Property
struct esp_ble_mesh_server_recv_gen_manufacturer_property_set_t
Context of the received Generic Manufacturer Property Set message
Public Members
uint8_t user_access
struct esp_ble_mesh_generic_server_cb_param_t
Generic Server Model callback parameters
Public Members
Pointer to Generic Server Models
Context of the received messages
esp_ble_mesh_generic_server_cb_value_t value
Value of the received Generic Messages
Macros
ESP_BLE_MESH_MODEL_GEN_ONOFF_CLI(cli_pub, cli_data)
Define a new Generic OnOff Client Model.
Note This API needs to be called for each element on which the application needs to have a Generic OnOff
Client Model.
Return New Generic OnOff Client Model instance.
Parameters
• cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
ESP_BLE_MESH_MODEL_GEN_LEVEL_CLI(cli_pub, cli_data)
Define a new Generic Level Client Model.
Note This API needs to be called for each element on which the application needs to have a Generic Level
Client Model.
Return New Generic Level Client Model instance.
Parameters

ESP_BLE_MESH_MODEL_GEN_DEF_TRANS_TIME_CLI(cli_pub, cli_data)
Define a new Generic Default Transition Time Client Model.
Note This API needs to be called for each element on which the application needs to have a Generic Default
Transition Time Client Model.
Return New Generic Default Transition Time Client Model instance.
Parameters
ESP_BLE_MESH_MODEL_GEN_POWER_ONOFF_CLI(cli_pub, cli_data)
Define a new Generic Power OnOff Client Model.
Note This API needs to be called for each element on which the application needs to have a Generic Power
OnOff Client Model.
Return New Generic Power OnOff Client Model instance.
Parameters
ESP_BLE_MESH_MODEL_GEN_POWER_LEVEL_CLI(cli_pub, cli_data)
Define a new Generic Power Level Client Model.
Note This API needs to be called for each element on which the application needs to have a Generic Power
Level Client Model.
Return New Generic Power Level Client Model instance.
Parameters
ESP_BLE_MESH_MODEL_GEN_BATTERY_CLI(cli_pub, cli_data)
Define a new Generic Battery Client Model.
Note This API needs to be called for each element on which the application needs to have a Generic Battery
Client Model.
Return New Generic Battery Client Model instance.
Parameters
ESP_BLE_MESH_MODEL_GEN_LOCATION_CLI(cli_pub, cli_data)
Define a new Generic Location Client Model.
Note This API needs to be called for each element on which the application needs to have a Generic Location
Client Model.
Return New Generic Location Client Model instance.
Parameters
ESP_BLE_MESH_MODEL_GEN_PROPERTY_CLI(cli_pub, cli_data)
Define a new Generic Property Client Model.
Note This API needs to be called for each element on which the application needs to have a Generic Property
Client Model.
Return New Generic Location Client Model instance.
Parameters
ESP_BLE_MESH_MODEL_GEN_ONOFF_SRV(srv_pub, srv_data)
Generic Server Models related context.
Define a new Generic OnOff Server Model.

Note 1. The Generic OnOff Server Model is a root model.

1. This model shall support model publication and model subscription.
Return New Generic OnOff Server Model instance.
Parameters
• srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• srv_data: Pointer to the unique struct esp_ble_mesh_gen_onoff_srv_t.
ESP_BLE_MESH_MODEL_GEN_LEVEL_SRV(srv_pub, srv_data)
Define a new Generic Level Server Model.
Note 1. The Generic Level Server Model is a root model.
Return New Generic Level Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_gen_level_srv_t.
ESP_BLE_MESH_MODEL_GEN_DEF_TRANS_TIME_SRV(srv_pub, srv_data)
Define a new Generic Default Transition Time Server Model.
Note 1. The Generic Default Transition Time Server Model is a root model.
Return New Generic Default Transition Time Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_gen_def_trans_time_srv_t.
ESP_BLE_MESH_MODEL_GEN_POWER_ONOFF_SRV(srv_pub, srv_data)
Define a new Generic Power OnOff Server Model.
Note 1. The Generic Power OnOff Server model extends the Generic OnOff Server model. When this model
is present on an element, the corresponding Generic Power OnOff Setup Server model shall also be
present.
1. This model may be used to represent a variety of devices that do not fit any of the model descriptions
that have been defined but support the generic properties of On/Off.
Return New Generic Power OnOff Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_gen_power_onoff_srv_t.
ESP_BLE_MESH_MODEL_GEN_POWER_ONOFF_SETUP_SRV(srv_pub, srv_data)
Define a new Generic Power OnOff Setup Server Model.
Note 1. The Generic Power OnOff Setup Server model extends the Generic Power OnOff Server model and
the Generic Default Transition Time Server model.
1. This model shall support model subscription.
Return New Generic Power OnOff Setup Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_gen_power_onoff_setup_srv_t.
ESP_BLE_MESH_MODEL_GEN_POWER_LEVEL_SRV(srv_pub, srv_data)
Define a new Generic Power Level Server Model.
Note 1. The Generic Power Level Server model extends the Generic Power OnOff Server model and the
Generic Level Server model. When this model is present on an Element, the corresponding Generic
Power Level Setup Server model shall also be present.
Return New Generic Power Level Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_gen_power_level_srv_t.

ESP_BLE_MESH_MODEL_GEN_POWER_LEVEL_SETUP_SRV(srv_pub, srv_data)
Define a new Generic Power Level Setup Server Model.
Note 1. The Generic Power Level Setup Server model extends the Generic Power Level Server model and the
Generic Power OnOff Setup Server model.
Return New Generic Power Level Setup Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_gen_power_level_setup_srv_t.
ESP_BLE_MESH_MODEL_GEN_BATTERY_SRV(srv_pub, srv_data)
Define a new Generic Battery Server Model.
Note 1. The Generic Battery Server Model is a root model.
2. The model may be used to represent an element that is powered by a battery.
Return New Generic Battery Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_gen_battery_srv_t.
ESP_BLE_MESH_MODEL_GEN_LOCATION_SRV(srv_pub, srv_data)
Define a new Generic Location Server Model.
Note 1. The Generic Location Server model is a root model. When this model is present on an Element, the
corresponding Generic Location Setup Server model shall also be present.
2. The model may be used to represent an element that knows its location (global or local).
Return New Generic Location Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_gen_location_srv_t.
ESP_BLE_MESH_MODEL_GEN_LOCATION_SETUP_SRV(srv_pub, srv_data)
Define a new Generic Location Setup Server Model.
Note 1. The Generic Location Setup Server model extends the Generic Location Server model.
Return New Generic Location Setup Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_gen_location_setup_srv_t.
ESP_BLE_MESH_MODEL_GEN_USER_PROP_SRV(srv_pub, srv_data)
Define a new Generic User Property Server Model.
Note 1. The Generic User Property Server model is a root model.
Return New Generic User Property Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_gen_user_prop_srv_t.
ESP_BLE_MESH_MODEL_GEN_ADMIN_PROP_SRV(srv_pub, srv_data)
Define a new Generic Admin Property Server Model.
Note 1. The Generic Admin Property Server model extends the Generic User Property Server model.
Return New Generic Admin Property Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_gen_admin_prop_srv_t.

ESP_BLE_MESH_MODEL_GEN_MANUFACTURER_PROP_SRV(srv_pub, srv_data)
Define a new Generic Manufacturer Property Server Model.
Note 1. The Generic Manufacturer Property Server model extends the Generic User Property Server model.
Return New Generic Manufacturer Property Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_gen_manu_prop_srv_t.
ESP_BLE_MESH_MODEL_GEN_CLIENT_PROP_SRV(srv_pub, srv_data)
Define a new Generic User Property Server Model.
Note 1. The Generic Client Property Server model is a root model.
Return New Generic Client Property Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_gen_client_prop_srv_t.
Type Definitions
typedef void (*esp_ble_mesh_generic_client_cb_t)(esp_ble_mesh_generic_client_cb_event_t
event,
esp_ble_mesh_generic_client_cb_param_t
*param)
Bluetooth Mesh Generic Client Model function.
Generic Client Model callback function type
Parameters
typedef void (*esp_ble_mesh_generic_server_cb_t)(esp_ble_mesh_generic_server_cb_event_t
event,
esp_ble_mesh_generic_server_cb_param_t
*param)
Bluetooth Mesh Generic Server Model function.
Generic Server Model callback function type
Parameters
Enumerations
enum esp_ble_mesh_generic_client_cb_event_t
This enum value is the event of Generic Client Model
Values:
ESP_BLE_MESH_GENERIC_CLIENT_GET_STATE_EVT
ESP_BLE_MESH_GENERIC_CLIENT_SET_STATE_EVT
ESP_BLE_MESH_GENERIC_CLIENT_PUBLISH_EVT
ESP_BLE_MESH_GENERIC_CLIENT_TIMEOUT_EVT
ESP_BLE_MESH_GENERIC_CLIENT_EVT_MAX
enum esp_ble_mesh_gen_user_prop_access_t
This enum value is the access value of Generic User Property
Values:
ESP_BLE_MESH_GEN_USER_ACCESS_PROHIBIT

ESP_BLE_MESH_GEN_USER_ACCESS_READ
ESP_BLE_MESH_GEN_USER_ACCESS_WRITE
ESP_BLE_MESH_GEN_USER_ACCESS_READ_WRITE
enum esp_ble_mesh_gen_admin_prop_access_t
This enum value is the access value of Generic Admin Property
Values:
ESP_BLE_MESH_GEN_ADMIN_NOT_USER_PROP
ESP_BLE_MESH_GEN_ADMIN_ACCESS_READ
ESP_BLE_MESH_GEN_ADMIN_ACCESS_WRITE
ESP_BLE_MESH_GEN_ADMIN_ACCESS_READ_WRITE
enum esp_ble_mesh_gen_manu_prop_access_t
This enum value is the access value of Generic Manufacturer Property
Values:
ESP_BLE_MESH_GEN_MANU_NOT_USER_PROP
ESP_BLE_MESH_GEN_MANU_ACCESS_READ
enum esp_ble_mesh_generic_server_cb_event_t
This enum value is the event of Generic Server Model
Values:
ESP_BLE_MESH_GENERIC_SERVER_STATE_CHANGE_EVT
1. When get_auto_rsp is set to ESP_BLE_MESH_SERVER_AUTO_RSP, no event will be callback
to the application layer when Generic Get messages are received.
2. When set_auto_rsp is set to ESP_BLE_MESH_SERVER_AUTO_RSP, this event will be callback
to the application layer when Generic Set/Set Unack messages are received.
ESP_BLE_MESH_GENERIC_SERVER_RECV_GET_MSG_EVT
When get_auto_rsp is set to ESP_BLE_MESH_SERVER_RSP_BY_APP, this event will be callback to
the application layer when Generic Get messages are received.
ESP_BLE_MESH_GENERIC_SERVER_RECV_SET_MSG_EVT
When set_auto_rsp is set to ESP_BLE_MESH_SERVER_RSP_BY_APP, this event will be callback to
the application layer when Generic Set/Set Unack messages are received.
ESP_BLE_MESH_GENERIC_SERVER_EVT_MAX
Sensor Client/Server Models
Header File
• components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_sensor_model_api.h
Functions
esp_err_t esp_ble_mesh_register_sensor_client_callback(esp_ble_mesh_sensor_client_cb_t
callback)
Register BLE Mesh Sensor Client Model callback.
Parameters

esp_err_t esp_ble_mesh_sensor_client_get_state(esp_ble_mesh_client_common_param_t
*params, esp_ble_mesh_sensor_client_get_state_t
*get_state)
Get the value of Sensor Server Model states using the Sensor Client Model get messages.
Note If you want to know the opcodes and corresponding meanings accepted by this API, please refer to
esp_ble_mesh_sensor_message_opcode_t in esp_ble_mesh_defs.h
Parameters
• [in] get_state: Pointer to sensor get message value. Shall not be set to NULL.
esp_err_t esp_ble_mesh_sensor_client_set_state(esp_ble_mesh_client_common_param_t
*params, esp_ble_mesh_sensor_client_set_state_t
*set_state)
Set the value of Sensor Server Model states using the Sensor Client Model set messages.
esp_ble_mesh_sensor_message_opcode_t in esp_ble_mesh_defs.h
Parameters
• [in] set_state: Pointer to sensor set message value. Shall not be set to NULL.
esp_err_t esp_ble_mesh_register_sensor_server_callback(esp_ble_mesh_sensor_server_cb_t
callback)
Register BLE Mesh Sensor Server Model callback.
Parameters
Unions
union esp_ble_mesh_sensor_client_get_state_t
#include <esp_ble_mesh_sensor_model_api.h> Sensor Client Model get message union.
Public Members
esp_ble_mesh_sensor_descriptor_get_t descriptor_get
For ESP_BLE_MESH_MODEL_OP_SENSOR_DESCRIPTOR_GET
esp_ble_mesh_sensor_cadence_get_t cadence_get
For ESP_BLE_MESH_MODEL_OP_SENSOR_CADENCE_GET
esp_ble_mesh_sensor_settings_get_t settings_get
For ESP_BLE_MESH_MODEL_OP_SENSOR_SETTINGS_GET
esp_ble_mesh_sensor_setting_get_t setting_get
For ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_GET
esp_ble_mesh_sensor_get_t sensor_get
For ESP_BLE_MESH_MODEL_OP_SENSOR_GET
esp_ble_mesh_sensor_column_get_t column_get
For ESP_BLE_MESH_MODEL_OP_SENSOR_COLUMN_GET
esp_ble_mesh_sensor_series_get_t series_get
For ESP_BLE_MESH_MODEL_OP_SENSOR_SERIES_GET
union esp_ble_mesh_sensor_client_set_state_t
#include <esp_ble_mesh_sensor_model_api.h> Sensor Client Model set message union.

Public Members
esp_ble_mesh_sensor_cadence_set_t cadence_set
For ESP_BLE_MESH_MODEL_OP_SENSOR_CADENCE_SET &
ESP_BLE_MESH_MODEL_OP_SENSOR_CADENCE_SET_UNACK
esp_ble_mesh_sensor_setting_set_t setting_set
For ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_SET &
ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_SET_UNACK
union esp_ble_mesh_sensor_client_status_cb_t
#include <esp_ble_mesh_sensor_model_api.h> Sensor Client Model received message union.
Public Members
esp_ble_mesh_sensor_descriptor_status_cb_t descriptor_status
For ESP_BLE_MESH_MODEL_OP_SENSOR_DESCRIPTOR_STATUS
esp_ble_mesh_sensor_cadence_status_cb_t cadence_status
For ESP_BLE_MESH_MODEL_OP_SENSOR_CADENCE_STATUS
esp_ble_mesh_sensor_settings_status_cb_t settings_status
For ESP_BLE_MESH_MODEL_OP_SENSOR_SETTINGS_STATUS
esp_ble_mesh_sensor_setting_status_cb_t setting_status
For ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_STATUS
esp_ble_mesh_sensor_status_cb_t sensor_status
For ESP_BLE_MESH_MODEL_OP_SENSOR_STATUS
esp_ble_mesh_sensor_column_status_cb_t column_status
For ESP_BLE_MESH_MODEL_OP_SENSOR_COLUMN_STATUS
esp_ble_mesh_sensor_series_status_cb_t series_status
For ESP_BLE_MESH_MODEL_OP_SENSOR_SERIES_STATUS
union esp_ble_mesh_sensor_server_state_change_t
#include <esp_ble_mesh_sensor_model_api.h> Sensor Server Model state change value union.
Public Members
esp_ble_mesh_state_change_sensor_cadence_set_t sensor_cadence_set
The recv_op in ctx can be used to decide which state is changed.Sensor Cadence Set
esp_ble_mesh_state_change_sensor_setting_set_t sensor_setting_set
Sensor Setting Set
union esp_ble_mesh_sensor_server_recv_get_msg_t
#include <esp_ble_mesh_sensor_model_api.h> Sensor Server Model received get message union.
Public Members
esp_ble_mesh_server_recv_sensor_descriptor_get_t sensor_descriptor
Sensor Descriptor Get
esp_ble_mesh_server_recv_sensor_cadence_get_t sensor_cadence
Sensor Cadence Get
esp_ble_mesh_server_recv_sensor_settings_get_t sensor_settings
Sensor Settings Get
esp_ble_mesh_server_recv_sensor_setting_get_t sensor_setting
Sensor Setting Get

esp_ble_mesh_server_recv_sensor_get_t sensor_data
Sensor Get
esp_ble_mesh_server_recv_sensor_column_get_t sensor_column
Sensor Column Get
esp_ble_mesh_server_recv_sensor_series_get_t sensor_series
Sensor Series Get
union esp_ble_mesh_sensor_server_recv_set_msg_t
#include <esp_ble_mesh_sensor_model_api.h> Sensor Server Model received set message union.
Public Members
esp_ble_mesh_server_recv_sensor_cadence_set_t sensor_cadence
Sensor Cadence Set
esp_ble_mesh_server_recv_sensor_setting_set_t sensor_setting
Sensor Setting Set
union esp_ble_mesh_sensor_server_cb_value_t
#include <esp_ble_mesh_sensor_model_api.h> Sensor Server Model callback value union.
Public Members
esp_ble_mesh_sensor_server_state_change_t state_change
ESP_BLE_MESH_SENSOR_SERVER_STATE_CHANGE_EVT
esp_ble_mesh_sensor_server_recv_get_msg_t get
ESP_BLE_MESH_SENSOR_SERVER_RECV_GET_MSG_EVT
esp_ble_mesh_sensor_server_recv_set_msg_t set
ESP_BLE_MESH_SENSOR_SERVER_RECV_SET_MSG_EVT
Structures
struct esp_ble_mesh_sensor_descriptor_get_t
Bluetooth Mesh Sensor Client Model Get and Set parameters structure.
Parameters of Sensor Descriptor Get
Public Members
bool op_en
Property ID of a sensor (optional)
struct esp_ble_mesh_sensor_cadence_get_t
Parameter of Sensor Cadence Get
Public Members
Property ID of a sensor
struct esp_ble_mesh_sensor_cadence_set_t
Parameters of Sensor Cadence Set

Public Members
Property ID for the sensor
uint8_t fast_cadence_period_divisor : 7
Divisor for the publish period
uint8_t status_trigger_type : 1
The unit and format of the Status Trigger Delta fields
struct net_buf_simple *status_trigger_delta_down
Delta down value that triggers a status message
struct net_buf_simple *status_trigger_delta_up
Delta up value that triggers a status message
uint8_t status_min_interval
Minimum interval between two consecutive Status messages
struct net_buf_simple *fast_cadence_low
Low value for the fast cadence range
struct net_buf_simple *fast_cadence_high
Fast value for the fast cadence range
struct esp_ble_mesh_sensor_settings_get_t
Parameter of Sensor Settings Get
Public Members
uint16_t sensor_property_id
struct esp_ble_mesh_sensor_setting_get_t
Parameters of Sensor Setting Get
Public Members
uint16_t sensor_setting_property_id
Setting ID identifying a setting within a sensor
struct esp_ble_mesh_sensor_setting_set_t
Parameters of Sensor Setting Set
Public Members
Property ID identifying a sensor
struct net_buf_simple *sensor_setting_raw
Raw value for the setting
struct esp_ble_mesh_sensor_get_t
Parameters of Sensor Get

Public Members
bool op_en
Property ID for the sensor (optional)
struct esp_ble_mesh_sensor_column_get_t
Parameters of Sensor Column Get
Public Members
Property identifying a sensor
struct net_buf_simple *raw_value_x
Raw value identifying a column
struct esp_ble_mesh_sensor_series_get_t
Parameters of Sensor Series Get
Public Members
bool op_en
struct net_buf_simple *raw_value_x1
Raw value identifying a starting column (optional)
struct net_buf_simple *raw_value_x2
Raw value identifying an ending column (C.1)
struct esp_ble_mesh_sensor_descriptor_status_cb_t
Bluetooth Mesh Sensor Client Model Get and Set callback parameters structure.
Parameter of Sensor Descriptor Status
Public Members
struct net_buf_simple *descriptor

Sequence of 8-octet sensor descriptors (optional)
struct esp_ble_mesh_sensor_cadence_status_cb_t
Parameters of Sensor Cadence Status
Public Members
Property for the sensor
struct net_buf_simple *sensor_cadence_value
Value of sensor cadence state
struct esp_ble_mesh_sensor_settings_status_cb_t
Parameters of Sensor Settings Status

Public Members
struct net_buf_simple *sensor_setting_property_ids
A sequence of N sensor setting property IDs (optional)
struct esp_ble_mesh_sensor_setting_status_cb_t
Parameters of Sensor Setting Status
Public Members
bool op_en
Indicate id optional parameters are included
uint8_t sensor_setting_access
Read/Write access rights for the setting (optional)
struct net_buf_simple *sensor_setting_raw
struct esp_ble_mesh_sensor_status_cb_t
Parameter of Sensor Status
Public Members
struct net_buf_simple *marshalled_sensor_data

Value of sensor data state (optional)
struct esp_ble_mesh_sensor_column_status_cb_t
Parameters of Sensor Column Status
Public Members
Property identifying a sensor and the Y axis
struct net_buf_simple *sensor_column_value
Left values of sensor column status
struct esp_ble_mesh_sensor_series_status_cb_t
Parameters of Sensor Series Status
Public Members
Property identifying a sensor and the Y axis
struct net_buf_simple *sensor_series_value
Left values of sensor series status
struct esp_ble_mesh_sensor_client_cb_param_t
Sensor Client Model callback parameters

Public Members
int error_code
0: success, otherwise failure. For the error code values please refer to errno.h file. A negative sign is
added to the standard error codes in errno.h.
esp_ble_mesh_sensor_client_status_cb_t status_cb
The sensor status message callback values
struct esp_ble_mesh_sensor_descriptor_t
Parameters of Sensor Descriptor state
Public Members
uint32_t positive_tolerance : 12
The value of Sensor Positive Tolerance field
uint32_t negative_tolerance : 12
The value of Sensor Negative Tolerance field
uint32_t sampling_function : 8
The value of Sensor Sampling Function field
uint8_t measure_period
The value of Sensor Measurement Period field
uint8_t update_interval
The value of Sensor Update Interval field
struct esp_ble_mesh_sensor_setting_t
Parameters of Sensor Setting state
Public Members
The value of Sensor Setting Property ID field
uint8_t access
The value of Sensor Setting Access field
struct net_buf_simple *raw
The value of Sensor Setting Raw field
struct esp_ble_mesh_sensor_cadence_t
Parameters of Sensor Cadence state
Public Members
uint8_t period_divisor : 7
The value of Fast Cadence Period Divisor field
uint8_t trigger_type : 1
The value of Status Trigger Type field
struct net_buf_simple *trigger_delta_down
Note: The parameter size in trigger_delta_down, trigger_delta_up, fast_cadence_low &
fast_cadence_high indicates the exact length of these four parameters, and they are associated with the
Sensor Property ID. Users need to initialize the size precisely.The value of Status Trigger Delta Down
field

struct net_buf_simple *trigger_delta_up

The value of Status Trigger Delta Up field
uint8_t min_interval
The value of Status Min Interval field
The value of Fast Cadence Low field
The value of Fast Cadence High field
struct esp_ble_mesh_sensor_data_t
Parameters of Sensor Data state
Public Members
uint8_t format : 1
Format A: The Length field is a 1-based uint4 value (valid range 0x0 0xF, representing range of 1 16).
Format B: The Length field is a 1-based uint7 value (valid range 0x0 0x7F, representing range of 1
127). The value 0x7F represents a length of zero.The value of the Sensor Data format
uint8_t length : 7
The value of the Sensor Data length
struct net_buf_simple *raw_value
The value of Sensor Data raw value
struct esp_ble_mesh_sensor_series_column_t
Parameters of Sensor Series Column state
Public Members

The value of Sensor Raw Value X field
struct net_buf_simple *column_width
The value of Sensor Column Width field
struct net_buf_simple *raw_value_y
The value of Sensor Raw Value Y field
struct esp_ble_mesh_sensor_state_t
Parameters of Sensor states
Public Members
The value of Sensor Property ID field
esp_ble_mesh_sensor_descriptor_t descriptor
Parameters of the Sensor Descriptor state
const uint8_t setting_count
Multiple Sensor Setting states may be present for each sensor. The Sensor Setting Property ID values
shall be unique for each Sensor Property ID that identifies a sensor within an element.
esp_ble_mesh_sensor_setting_t *settings
Parameters of the Sensor Setting state

esp_ble_mesh_sensor_cadence_t *cadence
The Sensor Cadence state may be not supported by sensors based on device properties referencing non-
scalar characteristics such as histograms or composite characteristics .Parameters of the Sensor
Cadence state
esp_ble_mesh_sensor_data_t sensor_data
Parameters of the Sensor Data state
esp_ble_mesh_sensor_series_column_t series_column
Parameters of the Sensor Series Column state
struct esp_ble_mesh_sensor_srv_t
User data of Sensor Server Model
Public Members
Pointer to the Sensor Server Model. Initialized internally.
const uint8_t state_count
Sensor state count
esp_ble_mesh_sensor_state_t *states
Parameters of the Sensor states
struct esp_ble_mesh_sensor_setup_srv_t
User data of Sensor Setup Server Model
Public Members
Pointer to the Sensor Setup Server Model. Initialized internally.
const uint8_t state_count
Sensor state count
esp_ble_mesh_sensor_state_t *states
Parameters of the Sensor states
struct esp_ble_mesh_state_change_sensor_cadence_set_t
Parameters of Sensor Cadence Set state change event
Public Members
The value of Sensor Property ID state
uint8_t period_divisor : 7
The value of Fast Cadence Period Divisor state
uint8_t trigger_type : 1
The value of Status Trigger Type state
struct net_buf_simple *trigger_delta_down
The value of Status Trigger Delta Down state

struct net_buf_simple *trigger_delta_up

The value of Status Trigger Delta Up state
uint8_t min_interval
The value of Status Min Interval state
The value of Fast Cadence Low state
The value of Fast Cadence High state
struct esp_ble_mesh_state_change_sensor_setting_set_t
Parameters of Sensor Setting Set state change event
Public Members
The value of Sensor Property ID state
uint16_t setting_property_id
The value of Sensor Setting Property ID state
struct net_buf_simple *setting_value
The value of Sensor Property Value state
struct esp_ble_mesh_server_recv_sensor_descriptor_get_t
Context of the received Sensor Descriptor Get message
Public Members
bool op_en
Property ID of a sensor (optional)
struct esp_ble_mesh_server_recv_sensor_cadence_get_t
Context of the received Sensor Cadence Get message
Public Members
struct esp_ble_mesh_server_recv_sensor_settings_get_t
Context of the received Sensor Settings Get message
Public Members
struct esp_ble_mesh_server_recv_sensor_setting_get_t
Context of the received Sensor Setting Get message

Public Members
struct esp_ble_mesh_server_recv_sensor_get_t
Context of the received Sensor Get message
Public Members
bool op_en
Property ID for the sensor (optional)
struct esp_ble_mesh_server_recv_sensor_column_get_t
Context of the received Sensor Column Get message
Public Members
Raw value identifying a column
struct esp_ble_mesh_server_recv_sensor_series_get_t
Context of the received Sensor Series Get message
Public Members
bool op_en
struct net_buf_simple *raw_value
Raw value containing X1 and X2 (optional)
struct esp_ble_mesh_server_recv_sensor_cadence_set_t
Context of the received Sensor Cadence Set message
Public Members
Property ID for the sensor
struct net_buf_simple *cadence
Value of Sensor Cadence state
struct esp_ble_mesh_server_recv_sensor_setting_set_t
Context of the received Sensor Setting Set message

Public Members
struct net_buf_simple *setting_raw
struct esp_ble_mesh_sensor_server_cb_param_t
Sensor Server Model callback parameters
Public Members
Pointer to Sensor Server Models
esp_ble_mesh_sensor_server_cb_value_t value
Value of the received Sensor Messages
Macros
ESP_BLE_MESH_MODEL_SENSOR_CLI(cli_pub, cli_data)
Define a new Sensor Client Model.
Note This API needs to be called for each element on which the application needs to have a Sensor Client
Model.
Return New Sensor Client Model instance.
Parameters
ESP_BLE_MESH_MODEL_SENSOR_SRV(srv_pub, srv_data)
Sensor Server Models related context.
Define a new Sensor Server Model.
Note 1. The Sensor Server model is a root model. When this model is present on an element, the corresponding
Sensor Setup Server model shall also be present.
Return New Sensor Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_sensor_srv_t.
ESP_BLE_MESH_MODEL_SENSOR_SETUP_SRV(srv_pub, srv_data)
Define a new Sensor Setup Server Model.
Note 1. The Sensor Setup Server model extends the Sensor Server model.
Return New Sensor Setup Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_sensor_setup_srv_t.
ESP_BLE_MESH_INVALID_SENSOR_PROPERTY_ID
Invalid Sensor Property ID
ESP_BLE_MESH_SENSOR_PROPERTY_ID_LEN
Length of Sensor Property ID

ESP_BLE_MESH_SENSOR_DESCRIPTOR_LEN
Length of Sensor Descriptor state
ESP_BLE_MESH_SENSOR_UNSPECIFIED_POS_TOLERANCE
Unspecified Sensor Positive Tolerance
ESP_BLE_MESH_SENSOR_UNSPECIFIED_NEG_TOLERANCE
Unspecified Sensor Negative Tolerance
ESP_BLE_MESH_SENSOR_NOT_APPL_MEASURE_PERIOD
Not applicable Sensor Measurement Period
ESP_BLE_MESH_SENSOR_NOT_APPL_UPDATE_INTERVAL
Not applicable Sensor Update Interval
ESP_BLE_MESH_INVALID_SENSOR_SETTING_PROPERTY_ID
Invalid Sensor Setting Property ID
ESP_BLE_MESH_SENSOR_SETTING_PROPERTY_ID_LEN
Length of Sensor Setting Property ID
ESP_BLE_MESH_SENSOR_SETTING_ACCESS_LEN
Length of Sensor Setting Access
ESP_BLE_MESH_SENSOR_SETTING_ACCESS_READ
Sensor Setting Access - Read
ESP_BLE_MESH_SENSOR_SETTING_ACCESS_READ_WRITE
Sensor Setting Access - Read & Write
ESP_BLE_MESH_SENSOR_DIVISOR_TRIGGER_TYPE_LEN
Length of Sensor Divisor Trigger Type
ESP_BLE_MESH_SENSOR_STATUS_MIN_INTERVAL_LEN
Length of Sensor Status Min Interval
ESP_BLE_MESH_SENSOR_PERIOD_DIVISOR_MAX_VALUE
Maximum value of Sensor Period Divisor
ESP_BLE_MESH_SENSOR_STATUS_MIN_INTERVAL_MAX
Maximum value of Sensor Status Min Interval
ESP_BLE_MESH_SENSOR_STATUS_TRIGGER_TYPE_CHAR
Sensor Status Trigger Type - Format Type of the characteristic that the Sensor Property ID state references
ESP_BLE_MESH_SENSOR_STATUS_TRIGGER_TYPE_UINT16
Sensor Status Trigger Type - Format Type uint16
ESP_BLE_MESH_SENSOR_DATA_FORMAT_A
Sensor Data Format A
ESP_BLE_MESH_SENSOR_DATA_FORMAT_B
Sensor Data Format B
ESP_BLE_MESH_SENSOR_DATA_FORMAT_A_MPID_LEN
MPID length of Sensor Data Format A
ESP_BLE_MESH_SENSOR_DATA_FORMAT_B_MPID_LEN
MPID length of Sensor Data Format B
ESP_BLE_MESH_SENSOR_DATA_ZERO_LEN
Zero length of Sensor Data.
Note: The Length field is a 1-based uint7 value (valid range 0x0 0x7F, representing range of 1 127). The
value 0x7F represents a length of zero.
ESP_BLE_MESH_GET_SENSOR_DATA_FORMAT(_data)
Get format of the sensor data.

Note Multiple sensor data may be concatenated. Make sure the _data pointer is updated before getting the
format of the corresponding sensor data.
Return Format of the sensor data.
Parameters
• _data: Pointer to the start of the sensor data.
ESP_BLE_MESH_GET_SENSOR_DATA_LENGTH(_data, _fmt)
Get length of the sensor data.
Note Multiple sensor data may be concatenated. Make sure the _data pointer is updated before getting the
length of the corresponding sensor data.
Return Length (zero-based) of the sensor data.
Parameters
• _fmt: Format of the sensor data.
ESP_BLE_MESH_GET_SENSOR_DATA_PROPERTY_ID(_data, _fmt)
Get Sensor Property ID of the sensor data.
Note Multiple sensor data may be concatenated. Make sure the _data pointer is updated before getting Sensor
Property ID of the corresponding sensor data.
Return Sensor Property ID of the sensor data.
Parameters
• _fmt: Format of the sensor data.
ESP_BLE_MESH_SENSOR_DATA_FORMAT_A_MPID(_len, _id)
Generate a MPID value for sensor data with Format A.
Note 1. The Format field is 0b0 and indicates that Format A is used.
1. The Length field is a 1-based uint4 value (valid range 0x0 0xF, representing range of 1 16).
2. The Property ID is an 11-bit bit field representing 11 LSb of a Property ID.
3. This format may be used for Property Values that are not longer than 16 octets and for Property IDs
less than 0x0800.
Return 2-octet MPID value for sensor data with Format A.
Parameters
• _len: Length of Sensor Raw value.
• _id: Sensor Property ID.
ESP_BLE_MESH_SENSOR_DATA_FORMAT_B_MPID(_len, _id)
Generate a MPID value for sensor data with Format B.
Note 1. The Format field is 0b1 and indicates Format B is used.
1. The Length field is a 1-based uint7 value (valid range 0x0 0x7F, representing range of 1 127). The
value 0x7F represents a length of zero.
2. The Property ID is a 16-bit bit field representing a Property ID.
3. This format may be used for Property Values not longer than 128 octets and for any Property IDs.
Property values longer than 128 octets are not supported by the Sensor Status message.
4. Exclude the generated 1-octet value, the 2-octet Sensor Property ID
Return 3-octet MPID value for sensor data with Format B.
Parameters
• _len: Length of Sensor Raw value.
• _id: Sensor Property ID.
Type Definitions
typedef void (*esp_ble_mesh_sensor_client_cb_t)(esp_ble_mesh_sensor_client_cb_event_t
event, esp_ble_mesh_sensor_client_cb_param_t
*param)
Bluetooth Mesh Sensor Client Model function.
Sensor Client Model callback function type
Parameters


typedef void (*esp_ble_mesh_sensor_server_cb_t)(esp_ble_mesh_sensor_server_cb_event_t
event, esp_ble_mesh_sensor_server_cb_param_t
*param)
Bluetooth Mesh Sensor Server Model function.
Sensor Server Model callback function type
Parameters
Enumerations
enum esp_ble_mesh_sensor_client_cb_event_t
This enum value is the event of Sensor Client Model
Values:
ESP_BLE_MESH_SENSOR_CLIENT_GET_STATE_EVT
ESP_BLE_MESH_SENSOR_CLIENT_SET_STATE_EVT
ESP_BLE_MESH_SENSOR_CLIENT_PUBLISH_EVT
ESP_BLE_MESH_SENSOR_CLIENT_TIMEOUT_EVT
ESP_BLE_MESH_SENSOR_CLIENT_EVT_MAX
enum esp_ble_mesh_sensor_sample_func
This enum value is value of Sensor Sampling Function
Values:
ESP_BLE_MESH_SAMPLE_FUNC_UNSPECIFIED
ESP_BLE_MESH_SAMPLE_FUNC_INSTANTANEOUS
ESP_BLE_MESH_SAMPLE_FUNC_ARITHMETIC_MEAN
ESP_BLE_MESH_SAMPLE_FUNC_RMS
ESP_BLE_MESH_SAMPLE_FUNC_MAXIMUM
ESP_BLE_MESH_SAMPLE_FUNC_MINIMUM
ESP_BLE_MESH_SAMPLE_FUNC_ACCUMULATED
ESP_BLE_MESH_SAMPLE_FUNC_COUNT
enum esp_ble_mesh_sensor_server_cb_event_t
This enum value is the event of Sensor Server Model
Values:
ESP_BLE_MESH_SENSOR_SERVER_STATE_CHANGE_EVT
to the application layer when Sensor Get messages are received.
to the application layer when Sensor Set/Set Unack messages are received.
ESP_BLE_MESH_SENSOR_SERVER_RECV_GET_MSG_EVT
the application layer when Sensor Get messages are received.
ESP_BLE_MESH_SENSOR_SERVER_RECV_SET_MSG_EVT
the application layer when Sensor Set/Set Unack messages are received.
ESP_BLE_MESH_SENSOR_SERVER_EVT_MAX

Time and Scenes Client/Server Models
Header File
• components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_time_scene_model_api.h
Functions
esp_err_t esp_ble_mesh_register_time_scene_client_callback(esp_ble_mesh_time_scene_client_cb_t
callback)
Register BLE Mesh Time Scene Client Model callback.
Parameters
esp_err_t esp_ble_mesh_time_scene_client_get_state(esp_ble_mesh_client_common_param_t
*params,
esp_ble_mesh_time_scene_client_get_state_t
*get_state)
Get the value of Time Scene Server Model states using the Time Scene Client Model get messages.
esp_ble_mesh_time_scene_message_opcode_t in esp_ble_mesh_defs.h
Parameters
• [in] get_state: Pointer to time scene get message value. Shall not be set to NULL.
esp_err_t esp_ble_mesh_time_scene_client_set_state(esp_ble_mesh_client_common_param_t
*params,
esp_ble_mesh_time_scene_client_set_state_t
*set_state)
Set the value of Time Scene Server Model states using the Time Scene Client Model set messages.
esp_ble_mesh_time_scene_message_opcode_t in esp_ble_mesh_defs.h
Parameters
• [in] set_state: Pointer to time scene set message value. Shall not be set to NULL.
esp_err_t esp_ble_mesh_register_time_scene_server_callback(esp_ble_mesh_time_scene_server_cb_t
callback)
Register BLE Mesh Time and Scenes Server Model callback.
Parameters
Unions
union esp_ble_mesh_time_scene_client_get_state_t
#include <esp_ble_mesh_time_scene_model_api.h> Time Scene Client Model get message union.
Public Members
esp_ble_mesh_scheduler_act_get_t scheduler_act_get
For ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_GET
union esp_ble_mesh_time_scene_client_set_state_t
#include <esp_ble_mesh_time_scene_model_api.h> Time Scene Client Model set message union.

Public Members
esp_ble_mesh_time_set_t time_set
For ESP_BLE_MESH_MODEL_OP_TIME_SET
esp_ble_mesh_time_zone_set_t time_zone_set
For ESP_BLE_MESH_MODEL_OP_TIME_ZONE_SET
esp_ble_mesh_tai_utc_delta_set_t tai_utc_delta_set
For ESP_BLE_MESH_MODEL_OP_TAI_UTC_DELTA_SET
esp_ble_mesh_time_role_set_t time_role_set
For ESP_BLE_MESH_MODEL_OP_TIME_ROLE_SET
esp_ble_mesh_scene_store_t scene_store
For ESP_BLE_MESH_MODEL_OP_SCENE_STORE & ESP_BLE_MESH_MODEL_OP_SCENE_STORE_UNACK
esp_ble_mesh_scene_recall_t scene_recall
For ESP_BLE_MESH_MODEL_OP_SCENE_RECALL & ESP_BLE_MESH_MODEL_OP_SCENE_RECALL_UNAC
esp_ble_mesh_scene_delete_t scene_delete
For ESP_BLE_MESH_MODEL_OP_SCENE_DELETE & ESP_BLE_MESH_MODEL_OP_SCENE_DELETE_UNAC
esp_ble_mesh_scheduler_act_set_t scheduler_act_set
For ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_SET &
ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_SET_UNACK
union esp_ble_mesh_time_scene_client_status_cb_t
#include <esp_ble_mesh_time_scene_model_api.h> Time Scene Client Model received message union.
Public Members
esp_ble_mesh_time_status_cb_t time_status
For ESP_BLE_MESH_MODEL_OP_TIME_STATUS
esp_ble_mesh_time_zone_status_cb_t time_zone_status
For ESP_BLE_MESH_MODEL_OP_TIME_ZONE_STATUS
esp_ble_mesh_tai_utc_delta_status_cb_t tai_utc_delta_status
For ESP_BLE_MESH_MODEL_OP_TAI_UTC_DELTA_STATUS
esp_ble_mesh_time_role_status_cb_t time_role_status
For ESP_BLE_MESH_MODEL_OP_TIME_ROLE_STATUS
esp_ble_mesh_scene_status_cb_t scene_status
For ESP_BLE_MESH_MODEL_OP_SCENE_STATUS
esp_ble_mesh_scene_register_status_cb_t scene_register_status
For ESP_BLE_MESH_MODEL_OP_SCENE_REGISTER_STATUS
esp_ble_mesh_scheduler_status_cb_t scheduler_status
For ESP_BLE_MESH_MODEL_OP_SCHEDULER_STATUS
esp_ble_mesh_scheduler_act_status_cb_t scheduler_act_status
For ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_STATUS
union esp_ble_mesh_time_scene_server_state_change_t
#include <esp_ble_mesh_time_scene_model_api.h> Time Scene Server Model state change value union.
Public Members
esp_ble_mesh_state_change_time_set_t time_set
The recv_op in ctx can be used to decide which state is changed.Time Set

esp_ble_mesh_state_change_time_status_t time_status
Time Status
esp_ble_mesh_state_change_time_zone_set_t time_zone_set
Time Zone Set
esp_ble_mesh_state_change_tai_utc_delta_set_t tai_utc_delta_set
TAI UTC Delta Set
esp_ble_mesh_state_change_time_role_set_t time_role_set
Time Role Set
esp_ble_mesh_state_change_scene_store_t scene_store
Scene Store
esp_ble_mesh_state_change_scene_recall_t scene_recall
Scene Recall
esp_ble_mesh_state_change_scene_delete_t scene_delete
Scene Delete
esp_ble_mesh_state_change_scheduler_act_set_t scheduler_act_set
Scheduler Action Set
union esp_ble_mesh_time_scene_server_recv_get_msg_t
#include <esp_ble_mesh_time_scene_model_api.h> Time Scene Server Model received get message union.
Public Members
esp_ble_mesh_server_recv_scheduler_act_get_t scheduler_act
Scheduler Action Get
union esp_ble_mesh_time_scene_server_recv_set_msg_t
#include <esp_ble_mesh_time_scene_model_api.h> Time Scene Server Model received set message union.
Public Members
esp_ble_mesh_server_recv_time_set_t time
Time Set
esp_ble_mesh_server_recv_time_zone_set_t time_zone
Time Zone Set
esp_ble_mesh_server_recv_tai_utc_delta_set_t tai_utc_delta
TAI-UTC Delta Set
esp_ble_mesh_server_recv_time_role_set_t time_role
Time Role Set
esp_ble_mesh_server_recv_scene_store_t scene_store
Scene Store/Scene Store Unack
esp_ble_mesh_server_recv_scene_recall_t scene_recall
Scene Recall/Scene Recall Unack
esp_ble_mesh_server_recv_scene_delete_t scene_delete
Scene Delete/Scene Delete Unack
esp_ble_mesh_server_recv_scheduler_act_set_t scheduler_act
Scheduler Action Set/Scheduler Action Set Unack
union esp_ble_mesh_time_scene_server_recv_status_msg_t
#include <esp_ble_mesh_time_scene_model_api.h> Time Scene Server Model received status message union.

Public Members
esp_ble_mesh_server_recv_time_status_t time_status
Time Status
union esp_ble_mesh_time_scene_server_cb_value_t
#include <esp_ble_mesh_time_scene_model_api.h> Time Scene Server Model callback value union.
Public Members
esp_ble_mesh_time_scene_server_state_change_t state_change
ESP_BLE_MESH_TIME_SCENE_SERVER_STATE_CHANGE_EVT
esp_ble_mesh_time_scene_server_recv_get_msg_t get
ESP_BLE_MESH_TIME_SCENE_SERVER_RECV_GET_MSG_EVT
esp_ble_mesh_time_scene_server_recv_set_msg_t set
ESP_BLE_MESH_TIME_SCENE_SERVER_RECV_SET_MSG_EVT
esp_ble_mesh_time_scene_server_recv_status_msg_t status
ESP_BLE_MESH_TIME_SCENE_SERVER_RECV_STATUS_MSG_EVT
Structures
struct esp_ble_mesh_time_set_t
Bluetooth Mesh Time Scene Client Model Get and Set parameters structure.
Parameters of Time Set
Public Members
uint8_t tai_seconds[5]
The current TAI time in seconds
uint8_t sub_second
The sub-second time in units of 1/256 second
uint8_t uncertainty
The estimated uncertainty in 10-millisecond steps
uint16_t time_authority : 1
0 = No Time Authority, 1 = Time Authority
uint16_t tai_utc_delta : 15
Current difference between TAI and UTC in seconds
uint8_t time_zone_offset
The local time zone offset in 15-minute increments
struct esp_ble_mesh_time_zone_set_t
Parameters of Time Zone Set
Public Members
uint8_t time_zone_offset_new
Upcoming local time zone offset
uint8_t tai_zone_change[5]
TAI Seconds time of the upcoming Time Zone Offset change
struct esp_ble_mesh_tai_utc_delta_set_t
Parameters of TAI-UTC Delta Set

Public Members
uint16_t tai_utc_delta_new : 15
Upcoming difference between TAI and UTC in seconds
uint16_t padding : 1
Always 0b0. Other values are Prohibited.
uint8_t tai_delta_change[5]
TAI Seconds time of the upcoming TAI-UTC Delta change
struct esp_ble_mesh_time_role_set_t
Parameter of Time Role Set
Public Members
uint8_t time_role
The Time Role for the element
struct esp_ble_mesh_scene_store_t
Parameter of Scene Store
Public Members
uint16_t scene_number
The number of scenes to be stored
struct esp_ble_mesh_scene_recall_t
Parameters of Scene Recall
Public Members
bool op_en
The number of scenes to be recalled
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_scene_delete_t
Parameter of Scene Delete
Public Members
The number of scenes to be deleted
struct esp_ble_mesh_scheduler_act_get_t
Parameter of Scheduler Action Get

Public Members
uint8_t index
Index of the Schedule Register entry to get
struct esp_ble_mesh_scheduler_act_set_t
Parameters of Scheduler Action Set
Public Members
uint64_t index : 4
Index of the Schedule Register entry to set
uint64_t year : 7
Scheduled year for the action
uint64_t month : 12
Scheduled month for the action
uint64_t day : 5
Scheduled day of the month for the action
uint64_t hour : 5
Scheduled hour for the action
uint64_t minute : 6
Scheduled minute for the action
uint64_t second : 6
Scheduled second for the action
uint64_t day_of_week : 7
Schedule days of the week for the action
uint64_t action : 4
Action to be performed at the scheduled time
uint64_t trans_time : 8
Transition time for this action
struct esp_ble_mesh_time_status_cb_t
Bluetooth Mesh Time Scene Client Model Get and Set callback parameters structure.
Parameters of Time Status
Public Members
uint8_t sub_second
uint8_t uncertainty

struct esp_ble_mesh_time_zone_status_cb_t
Parameters of Time Zone Status
Public Members
uint8_t time_zone_offset_curr
Current local time zone offset
struct esp_ble_mesh_tai_utc_delta_status_cb_t
Parameters of TAI-UTC Delta Status
Public Members
uint16_t tai_utc_delta_curr : 15
uint16_t padding_1 : 1
uint16_t padding_2 : 1
struct esp_ble_mesh_time_role_status_cb_t
Parameter of Time Role Status
Public Members
uint8_t time_role
struct esp_ble_mesh_scene_status_cb_t
Parameters of Scene Status
Public Members
bool op_en
uint8_t status_code
Status code of the last operation
uint16_t current_scene
Scene Number of the current scene
uint16_t target_scene
Scene Number of the target scene (optional)

uint8_t remain_time
struct esp_ble_mesh_scene_register_status_cb_t
Parameters of Scene Register Status
Public Members
uint8_t status_code
Status code for the previous operation
Scene Number of the current scene
struct net_buf_simple *scenes
A list of scenes stored within an element
struct esp_ble_mesh_scheduler_status_cb_t
Parameter of Scheduler Status
Public Members
uint16_t schedules
Bit field indicating defined Actions in the Schedule Register
struct esp_ble_mesh_scheduler_act_status_cb_t
Parameters of Scheduler Action Status
Public Members
uint64_t index : 4
Enumerates (selects) a Schedule Register entry
uint64_t year : 7
uint64_t month : 12
uint64_t day : 5
uint64_t hour : 5
uint64_t minute : 6
uint64_t second : 6
uint64_t action : 4

struct esp_ble_mesh_time_scene_client_cb_param_t
Time Scene Client Model callback parameters
Public Members
int error_code
esp_ble_mesh_time_scene_client_status_cb_t status_cb
The scene status message callback values
struct esp_ble_mesh_time_state_t
Parameters of Time state
Public Members
The value of the TAI Seconds state
uint8_t subsecond
The value of the Subsecond field
uint8_t uncertainty
The value of the Uncertainty field
The value of the Time Zone Offset Current field
The value of the Time Zone Offset New state
The value of the TAI of Zone Chaneg field
The value of the Time Authority bit
The value of the TAI-UTC Delta Current state
The value of the TAI-UTC Delta New state
The value of the TAI of Delta Change field
struct esp_ble_mesh_time_state_t::[anonymous] time
Parameters of the Time state
uint8_t time_role
The value of the Time Role state
struct esp_ble_mesh_time_srv_t
User data of Time Server Model
Public Members
Pointer to the Time Server Model. Initialized internally.

esp_ble_mesh_time_state_t *state
struct esp_ble_mesh_time_setup_srv_t
User data of Time Setup Server Model
Public Members
Pointer to the Time Setup Server Model. Initialized internally.
esp_ble_mesh_time_state_t *state
struct esp_ble_mesh_scene_register_t
1. Scene Store is an operation of storing values of a present state of an element.
2. The structure and meaning of the stored state is determined by a model. States to be stored are specified
by each model.
3. The Scene Store operation shall persistently store all values of all states marked as Stored with Scene for
all models present on all elements of a node.
4. If a model is extending another model, the extending model shall determine the Stored with Scene be-
havior of that model.Parameters of Scene Register state
Public Members
The value of the Scene Number
uint8_t scene_type
The value of the Scene Type
struct net_buf_simple *scene_value
Scene value may use a union to represent later, the union contains structures of all the model states which
can be stored in a scene.The value of the Scene Value
struct esp_ble_mesh_scenes_state_t
Parameters of Scenes state.
Scenes serve as memory banks for storage of states (e.g., a power level or a light level/color). Values of states
of an element can be stored as a scene and can be recalled later from the scene memory.
A scene is represented by a Scene Number, which is a 16-bit non-zero, mesh-wide value. (There can be a
maximum of 65535 scenes in a mesh network.) The meaning of a scene, as well as the state storage container
associated with it, are determined by a model.
The Scenes state change may start numerous parallel model transitions. In that case, each individual model
handles the transition internally.
The scene transition is defined as a group of individual model transitions started by a Scene Recall operation.
The scene transition is in progress when at least one transition from the group of individual model transitions
is in progress.

Public Members
const uint16_t scene_count

The Scenes state s scene count
esp_ble_mesh_scene_register_t *scenes
Parameters of the Scenes state
The Current Scene state is a 16-bit value that contains either the Scene Number of the currently active
scene or a value of 0x0000 when no scene is active.
When a Scene Store operation or a Scene Recall operation completes with success, the Current Scene
state value shall be to the Scene Number used during that operation.
When the Current Scene Number is deleted from a Scene Register state as a result of Scene Delete
operation, the Current Scene state shall be set to 0x0000.
When any of the element s state that is marked as Stored with Scene has changed not as a result of
a Scene Recall operation, the value of the Current Scene state shall be set to 0x0000.
When a scene transition is in progress, the value of the Current Scene state shall be set to 0x0000.The
value of the Current Scene state
uint16_t target_scene
The Target Scene state is a 16-bit value that contains the target Scene Number when a scene transition is
in progress.
When the scene transition is in progress and the target Scene Number is deleted from a Scene Register
state as a result of Scene Delete operation, the Target Scene state shall be set to 0x0000.
When the scene transition is in progress and a new Scene Number is stored in the Scene Register as a
result of Scene Store operation, the Target Scene state shall be set to the new Scene Number.
When the scene transition is not in progress, the value of the Target Scene state shall be set to 0x0000.The
value of the Target Scene state
uint8_t status_code
The status code of the last scene operation
bool in_progress
Indicate if the scene transition is in progress
struct esp_ble_mesh_scene_srv_t
User data of Scene Server Model
Public Members
Pointer to the Scene Server Model. Initialized internally.
esp_ble_mesh_scenes_state_t *state
struct esp_ble_mesh_scene_setup_srv_t
User data of Scene Setup Server Model

Public Members
Pointer to the Scene Setup Server Model. Initialized internally.
esp_ble_mesh_scenes_state_t *state
struct esp_ble_mesh_schedule_register_t
Parameters of Scheduler Register state
Public Members
bool in_use
Indicate if the registered schedule is in use
uint64_t year : 7
The value of Scheduled year for the action
uint64_t month : 12
The value of Scheduled month for the action
uint64_t day : 5
The value of Scheduled day of the month for the action
uint64_t hour : 5
The value of Scheduled hour for the action
uint64_t minute : 6
The value of Scheduled minute for the action
uint64_t second : 6
The value of Scheduled second for the action
The value of Schedule days of the week for the action
uint64_t action : 4
The value of Action to be performed at the scheduled time
The value of Transition time for this action
The value of Scene Number to be used for some actions
struct esp_ble_mesh_scheduler_state_t
Parameters of Scheduler state
Public Members
const uint8_t schedule_count

Scheduler count
esp_ble_mesh_schedule_register_t *schedules
Up to 16 scheduled entries
struct esp_ble_mesh_scheduler_srv_t
User data of Scheduler Server Model

Public Members
Pointer to the Scheduler Server Model. Initialized internally.
esp_ble_mesh_scheduler_state_t *state
Parameters of the Scheduler state
struct esp_ble_mesh_scheduler_setup_srv_t
User data of Scheduler Setup Server Model
Public Members
Pointer to the Scheduler Setup Server Model. Initialized internally.
esp_ble_mesh_scheduler_state_t *state
Parameters of the Scheduler state
struct esp_ble_mesh_state_change_time_set_t
Parameters of Time Set state change event
Public Members
uint8_t subsecond
uint8_t uncertainty
struct esp_ble_mesh_state_change_time_status_t
Parameters of Time Status state change event
Public Members
uint8_t subsecond
uint8_t uncertainty

struct esp_ble_mesh_state_change_time_zone_set_t
Parameters of Time Zone Set state change event
Public Members
struct esp_ble_mesh_state_change_tai_utc_delta_set_t
Parameters of TAI UTC Delta Set state change event
Public Members
struct esp_ble_mesh_state_change_time_role_set_t
Parameter of Time Role Set state change event
Public Members
uint8_t time_role
struct esp_ble_mesh_state_change_scene_store_t
Parameter of Scene Store state change event
Public Members
struct esp_ble_mesh_state_change_scene_recall_t
Parameter of Scene Recall state change event
Public Members
struct esp_ble_mesh_state_change_scene_delete_t
Parameter of Scene Delete state change event

Public Members
struct esp_ble_mesh_state_change_scheduler_act_set_t
Parameter of Scheduler Action Set state change event
Public Members
uint64_t index : 4
uint64_t year : 7
uint64_t month : 12
uint64_t day : 5
uint64_t hour : 5
uint64_t minute : 6
uint64_t second : 6
uint64_t action : 4
Scene number to be used for some actions
struct esp_ble_mesh_server_recv_scheduler_act_get_t
Context of the received Scheduler Action Get message
Public Members
uint8_t index
Index of the Schedule Register entry to get
struct esp_ble_mesh_server_recv_time_set_t
Context of the received Time Set message
Public Members
uint8_t subsecond

uint8_t uncertainty
struct esp_ble_mesh_server_recv_time_zone_set_t
Context of the received Time Zone Set message
Public Members
struct esp_ble_mesh_server_recv_tai_utc_delta_set_t
Context of the received TAI UTC Delta Set message
Public Members
uint16_t padding : 1
struct esp_ble_mesh_server_recv_time_role_set_t
Context of the received Time Role Set message
Public Members
uint8_t time_role
struct esp_ble_mesh_server_recv_scene_store_t
Context of the received Scene Store message
Public Members
struct esp_ble_mesh_server_recv_scene_recall_t
Context of the received Scene Recall message

Public Members
bool op_en
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_server_recv_scene_delete_t
Context of the received Scene Delete message
Public Members
struct esp_ble_mesh_server_recv_scheduler_act_set_t
Context of the received Scheduler Action Set message
Public Members
uint64_t index : 4
uint64_t year : 7
uint64_t month : 12
uint64_t day : 5
uint64_t hour : 5
uint64_t minute : 6
uint64_t second : 6
uint64_t action : 4
Scene number to be used for some actions
struct esp_ble_mesh_server_recv_time_status_t
Context of the received Time Status message

Public Members
uint8_t subsecond
uint8_t uncertainty
struct esp_ble_mesh_time_scene_server_cb_param_t
Time Scene Server Model callback parameters
Public Members
Pointer to Time and Scenes Server Models
esp_ble_mesh_time_scene_server_cb_value_t value
Value of the received Time and Scenes Messages
Macros
ESP_BLE_MESH_MODEL_TIME_CLI(cli_pub, cli_data)
Define a new Time Client Model.
Note This API needs to be called for each element on which the application needs to have a Time Client
Model.
Return New Time Client Model instance.
Parameters
ESP_BLE_MESH_MODEL_SCENE_CLI(cli_pub, cli_data)
Define a new Scene Client Model.
Note This API needs to be called for each element on which the application needs to have a Scene Client
Model.
Return New Scene Client Model instance.
Parameters
ESP_BLE_MESH_MODEL_SCHEDULER_CLI(cli_pub, cli_data)
Define a new Scheduler Client Model.
Note This API needs to be called for each element on which the application needs to have a Scheduler Client
Model.
Return New Scheduler Client Model instance.
Parameters

ESP_BLE_MESH_MODEL_TIME_SRV(srv_pub, srv_data)
Time Scene Server Models related context.
Define a new Time Server Model.
Note 1. The Time Server model is a root model. When this model is present on an Element, the corresponding
Time Setup Server model shall also be present.
Return New Time Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_time_srv_t.
ESP_BLE_MESH_MODEL_TIME_SETUP_SRV(srv_data)
Define a new Time Setup Server Model.
Note 1. The Time Setup Server model extends the Time Server model. Time is sensitive information that is
propagated across a mesh network.
1. Only an authorized Time Client should be allowed to change the Time and Time Role states. A
dedicated application key Bluetooth SIG Proprietary should be used on the Time Setup Server to
restrict access to the server to only authorized Time Clients.
2. This model does not support subscribing nor publishing.
Return New Time Setup Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_time_setup_srv_t.
ESP_BLE_MESH_MODEL_SCENE_SRV(srv_pub, srv_data)
Define a new Scene Server Model.
Note 1. The Scene Server model is a root model. When this model is present on an Element, the corresponding
Scene Setup Server model shall also be present.
2. The model may be present only on the Primary element of a node.
Return New Scene Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_scene_srv_t.
ESP_BLE_MESH_MODEL_SCENE_SETUP_SRV(srv_pub, srv_data)
Define a new Scene Setup Server Model.
Note 1. The Scene Setup Server model extends the Scene Server model and the Generic Default Transition
Time Server model.
Return New Scene Setup Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_scene_setup_srv_t.
ESP_BLE_MESH_MODEL_SCHEDULER_SRV(srv_pub, srv_data)
Define a new Scheduler Server Model.
Note 1. The Scheduler Server model extends the Scene Server model. When this model is present on an
Element, the corresponding Scheduler Setup Server model shall also be present.
3. The model requires the Time Server model shall be present on the element.
Return New Scheduler Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_scheduler_srv_t.

ESP_BLE_MESH_MODEL_SCHEDULER_SETUP_SRV(srv_pub, srv_data)
Define a new Scheduler Setup Server Model.
Note 1. The Scheduler Setup Server model extends the Scheduler Server and the Scene Setup Server models.
Return New Scheduler Setup Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_scheduler_setup_srv_t.
ESP_BLE_MESH_UNKNOWN_TAI_SECONDS
Unknown TAI Seconds
ESP_BLE_MESH_UNKNOWN_TAI_ZONE_CHANGE
Unknown TAI of Zone Change
ESP_BLE_MESH_UNKNOWN_TAI_DELTA_CHANGE
Unknown TAI of Delta Change
ESP_BLE_MESH_TAI_UTC_DELTA_MAX_VALUE
Maximum TAI-UTC Delta value
ESP_BLE_MESH_TAI_SECONDS_LEN
Length of TAI Seconds
ESP_BLE_MESH_TAI_OF_ZONE_CHANGE_LEN
Length of TAI of Zone Change
ESP_BLE_MESH_TAI_OF_DELTA_CHANGE_LEN
Length of TAI of Delta Change
ESP_BLE_MESH_INVALID_SCENE_NUMBER
Invalid Scene Number
ESP_BLE_MESH_SCENE_NUMBER_LEN
Length of the Scene Number
ESP_BLE_MESH_SCHEDULE_YEAR_ANY_YEAR
Any year of the Scheduled year
ESP_BLE_MESH_SCHEDULE_DAY_ANY_DAY
Any day of the Scheduled day
ESP_BLE_MESH_SCHEDULE_HOUR_ANY_HOUR
Any hour of the Scheduled hour
ESP_BLE_MESH_SCHEDULE_HOUR_ONCE_A_DAY
Any hour of the Scheduled Day
ESP_BLE_MESH_SCHEDULE_SEC_ANY_OF_HOUR
Any minute of the Scheduled hour
ESP_BLE_MESH_SCHEDULE_SEC_EVERY_15_MIN
Every 15 minutes of the Scheduled hour
ESP_BLE_MESH_SCHEDULE_SEC_EVERY_20_MIN
Every 20 minutes of the Scheduled hour
ESP_BLE_MESH_SCHEDULE_SEC_ONCE_AN_HOUR
Once of the Scheduled hour
ESP_BLE_MESH_SCHEDULE_SEC_ANY_OF_MIN
Any second of the Scheduled minute
ESP_BLE_MESH_SCHEDULE_SEC_EVERY_15_SEC
Every 15 seconds of the Scheduled minute

ESP_BLE_MESH_SCHEDULE_SEC_EVERY_20_SEC
Every 20 seconds of the Scheduled minute
ESP_BLE_MESH_SCHEDULE_SEC_ONCE_AN_MIN
Once of the Scheduled minute
ESP_BLE_MESH_SCHEDULE_ACT_TURN_OFF
Scheduled Action - Turn Off
ESP_BLE_MESH_SCHEDULE_ACT_TURN_ON
Scheduled Action - Turn On
ESP_BLE_MESH_SCHEDULE_ACT_SCENE_RECALL
Scheduled Action - Scene Recall
ESP_BLE_MESH_SCHEDULE_ACT_NO_ACTION
Scheduled Action - No Action
ESP_BLE_MESH_SCHEDULE_SCENE_NO_SCENE
Scheduled Scene - No Scene
ESP_BLE_MESH_SCHEDULE_ENTRY_MAX_INDEX
Maximum number of Scheduled entries
ESP_BLE_MESH_TIME_NONE
Time Role - None
ESP_BLE_MESH_TIME_AUTHORITY
Time Role - Mesh Time Authority
ESP_BLE_MESH_TIME_RELAY
Time Role - Mesh Time Relay
ESP_BLE_MESH_TIME_CLINET
Time Role - Mesh Time Client
ESP_BLE_MESH_SCENE_SUCCESS
Scene operation - Success
ESP_BLE_MESH_SCENE_REG_FULL
Scene operation - Scene Register Full
ESP_BLE_MESH_SCENE_NOT_FOUND
Scene operation - Scene Not Found
Type Definitions
typedef void (*esp_ble_mesh_time_scene_client_cb_t)(esp_ble_mesh_time_scene_client_cb_event_t
event,
esp_ble_mesh_time_scene_client_cb_param_t
*param)
Bluetooth Mesh Time Scene Client Model function.
Time Scene Client Model callback function type
Parameters
typedef void (*esp_ble_mesh_time_scene_server_cb_t)(esp_ble_mesh_time_scene_server_cb_event_t
event,
esp_ble_mesh_time_scene_server_cb_param_t
*param)
Bluetooth Mesh Time and Scenes Server Model function.
Time Scene Server Model callback function type
Parameters

Enumerations
enum esp_ble_mesh_time_scene_client_cb_event_t
This enum value is the event of Time Scene Client Model
Values:
ESP_BLE_MESH_TIME_SCENE_CLIENT_GET_STATE_EVT
ESP_BLE_MESH_TIME_SCENE_CLIENT_SET_STATE_EVT
ESP_BLE_MESH_TIME_SCENE_CLIENT_PUBLISH_EVT
ESP_BLE_MESH_TIME_SCENE_CLIENT_TIMEOUT_EVT
ESP_BLE_MESH_TIME_SCENE_CLIENT_EVT_MAX
enum esp_ble_mesh_time_scene_server_cb_event_t
This enum value is the event of Time Scene Server Model
Values:
ESP_BLE_MESH_TIME_SCENE_SERVER_STATE_CHANGE_EVT
to the application layer when Time Scene Get messages are received.
to the application layer when Time Scene Set/Set Unack messages are received.
ESP_BLE_MESH_TIME_SCENE_SERVER_RECV_GET_MSG_EVT
the application layer when Time Scene Get messages are received.
ESP_BLE_MESH_TIME_SCENE_SERVER_RECV_SET_MSG_EVT
the application layer when Time Scene Set/Set Unack messages are received.
ESP_BLE_MESH_TIME_SCENE_SERVER_RECV_STATUS_MSG_EVT
When status_auto_rsp is set to ESP_BLE_MESH_SERVER_RSP_BY_APP, this event will be callback
to the application layer when TIme Status message is received.
ESP_BLE_MESH_TIME_SCENE_SERVER_EVT_MAX
Lighting Client/Server Models
Header File
• components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_lighting_model_api.h
Functions
esp_err_t esp_ble_mesh_register_light_client_callback(esp_ble_mesh_light_client_cb_t
callback)
Register BLE Mesh Light Client Model callback.
Parameters
• [in] callback: pointer to the callback function.
esp_err_t esp_ble_mesh_light_client_get_state(esp_ble_mesh_client_common_param_t
*params, esp_ble_mesh_light_client_get_state_t
*get_state)
Get the value of Light Server Model states using the Light Client Model get messages.
esp_ble_mesh_light_message_opcode_t in esp_ble_mesh_defs.h


Parameters
• [in] get_state: Pointer of light get message value. Shall not be set to NULL.
esp_err_t esp_ble_mesh_light_client_set_state(esp_ble_mesh_client_common_param_t
*params, esp_ble_mesh_light_client_set_state_t
*set_state)
Set the value of Light Server Model states using the Light Client Model set messages.
esp_ble_mesh_light_message_opcode_t in esp_ble_mesh_defs.h
Parameters
• [in] set_state: Pointer of light set message value. Shall not be set to NULL.
esp_err_t esp_ble_mesh_register_lighting_server_callback(esp_ble_mesh_lighting_server_cb_t
callback)
Register BLE Mesh Lighting Server Model callback.
Parameters
Unions
union esp_ble_mesh_light_client_get_state_t
#include <esp_ble_mesh_lighting_model_api.h> Lighting Client Model get message union.
Public Members
esp_ble_mesh_light_lc_property_get_t lc_property_get
For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_PROPERTY_GET
union esp_ble_mesh_light_client_set_state_t
#include <esp_ble_mesh_lighting_model_api.h> Lighting Client Model set message union.
Public Members
esp_ble_mesh_light_lightness_set_t lightness_set
For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_SET &
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_SET_UNACK
esp_ble_mesh_light_lightness_linear_set_t lightness_linear_set
For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LINEAR_SET &
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LINEAR_SET_UNACK
esp_ble_mesh_light_lightness_default_set_t lightness_default_set
For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEFAULT_SET &
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEFAULT_SET_UNACK
esp_ble_mesh_light_lightness_range_set_t lightness_range_set
For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_RANGE_SET &
ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_RANGE_SET_UNACK
esp_ble_mesh_light_ctl_set_t ctl_set
For ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_SET_UNA
esp_ble_mesh_light_ctl_temperature_set_t ctl_temperature_set
For ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_SET &
ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_SET_UNACK

esp_ble_mesh_light_ctl_temperature_range_set_t ctl_temperature_range_set
For ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_RANGE_SET &
ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_RANGE_SET_UNACK
esp_ble_mesh_light_ctl_default_set_t ctl_default_set
For ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULT_SET &
ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULT_SET_UNACK
esp_ble_mesh_light_hsl_set_t hsl_set
For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SET_UNAC
esp_ble_mesh_light_hsl_hue_set_t hsl_hue_set
For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE
esp_ble_mesh_light_hsl_saturation_set_t hsl_saturation_set
For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SATURATION_SET &
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SATURATION_SET_UNACK
esp_ble_mesh_light_hsl_default_set_t hsl_default_set
For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULT_SET &
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULT_SET_UNACK
esp_ble_mesh_light_hsl_range_set_t hsl_range_set
For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_SET &
ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_SET_UNACK
esp_ble_mesh_light_xyl_set_t xyl_set
For ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_SET_UNA
esp_ble_mesh_light_xyl_default_set_t xyl_default_set
For ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULT_SET &
ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULT_SET_UNACK
esp_ble_mesh_light_xyl_range_set_t xyl_range_set
For ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_SET &
ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_SET_UNACK
esp_ble_mesh_light_lc_mode_set_t lc_mode_set
For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_MODE_SET &
ESP_BLE_MESH_MODEL_OP_LIGHT_LC_MODE_SET_UNACK
esp_ble_mesh_light_lc_om_set_t lc_om_set
For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_OM_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_LC_OM_SET
esp_ble_mesh_light_lc_light_onoff_set_t lc_light_onoff_set
For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_LIGHT_ONOFF_SET &
ESP_BLE_MESH_MODEL_OP_LIGHT_LC_LIGHT_ONOFF_SET_UNACK
esp_ble_mesh_light_lc_property_set_t lc_property_set
For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_PROPERTY_SET &
ESP_BLE_MESH_MODEL_OP_LIGHT_LC_PROPERTY_SET_UNACK
union esp_ble_mesh_light_client_status_cb_t
#include <esp_ble_mesh_lighting_model_api.h> Lighting Client Model received message union.
Public Members
esp_ble_mesh_light_lightness_status_cb_t lightness_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_STATUS
esp_ble_mesh_light_lightness_linear_status_cb_t lightness_linear_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LINEAR_STATUS
esp_ble_mesh_light_lightness_last_status_cb_t lightness_last_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LAST_STATUS

esp_ble_mesh_light_lightness_default_status_cb_t lightness_default_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEFAULT_STATUS
esp_ble_mesh_light_lightness_range_status_cb_t lightness_range_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_RANGE_STATUS
esp_ble_mesh_light_ctl_status_cb_t ctl_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_STATUS
esp_ble_mesh_light_ctl_temperature_status_cb_t ctl_temperature_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_STATUS
esp_ble_mesh_light_ctl_temperature_range_status_cb_t ctl_temperature_range_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_RANGE_STATUS
esp_ble_mesh_light_ctl_default_status_cb_t ctl_default_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULT_STATUS
esp_ble_mesh_light_hsl_status_cb_t hsl_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_STATUS
esp_ble_mesh_light_hsl_target_status_cb_t hsl_target_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_TARGET_STATUS
esp_ble_mesh_light_hsl_hue_status_cb_t hsl_hue_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_STATUS
esp_ble_mesh_light_hsl_saturation_status_cb_t hsl_saturation_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SATURATION_STATUS
esp_ble_mesh_light_hsl_default_status_cb_t hsl_default_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULT_STATUS
esp_ble_mesh_light_hsl_range_status_cb_t hsl_range_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_STATUS
esp_ble_mesh_light_xyl_status_cb_t xyl_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_STATUS
esp_ble_mesh_light_xyl_target_status_cb_t xyl_target_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_TARGET_STATUS
esp_ble_mesh_light_xyl_default_status_cb_t xyl_default_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULT_STATUS
esp_ble_mesh_light_xyl_range_status_cb_t xyl_range_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_STATUS
esp_ble_mesh_light_lc_mode_status_cb_t lc_mode_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_MODE_STATUS
esp_ble_mesh_light_lc_om_status_cb_t lc_om_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_OM_STATUS
esp_ble_mesh_light_lc_light_onoff_status_cb_t lc_light_onoff_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_LIGHT_ONOFF_STATUS
esp_ble_mesh_light_lc_property_status_cb_t lc_property_status
For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_PROPERTY_STATUS
union esp_ble_mesh_lighting_server_state_change_t
#include <esp_ble_mesh_lighting_model_api.h> Lighting Server Model state change value union.
Public Members
esp_ble_mesh_state_change_light_lightness_set_t lightness_set
The recv_op in ctx can be used to decide which state is changed.Light Lightness Set

esp_ble_mesh_state_change_light_lightness_linear_set_t lightness_linear_set
Light Lightness Linear Set
esp_ble_mesh_state_change_light_lightness_default_set_t lightness_default_set
Light Lightness Default Set
esp_ble_mesh_state_change_light_lightness_range_set_t lightness_range_set
Light Lightness Range Set
esp_ble_mesh_state_change_light_ctl_set_t ctl_set
Light CTL Set
esp_ble_mesh_state_change_light_ctl_temperature_set_t ctl_temp_set
Light CTL Temperature Set
esp_ble_mesh_state_change_light_ctl_temperature_range_set_t ctl_temp_range_set
Light CTL Temperature Range Set
esp_ble_mesh_state_change_light_ctl_default_set_t ctl_default_set
Light CTL Default Set
esp_ble_mesh_state_change_light_hsl_set_t hsl_set
Light HSL Set
esp_ble_mesh_state_change_light_hsl_hue_set_t hsl_hue_set
Light HSL Hue Set
esp_ble_mesh_state_change_light_hsl_saturation_set_t hsl_saturation_set
Light HSL Saturation Set
esp_ble_mesh_state_change_light_hsl_default_set_t hsl_default_set
Light HSL Default Set
esp_ble_mesh_state_change_light_hsl_range_set_t hsl_range_set
Light HSL Range Set
esp_ble_mesh_state_change_light_xyl_set_t xyl_set
Light xyL Set
esp_ble_mesh_state_change_light_xyl_default_set_t xyl_default_set
Light xyL Default Set
esp_ble_mesh_state_change_light_xyl_range_set_t xyl_range_set
Light xyL Range Set
esp_ble_mesh_state_change_light_lc_mode_set_t lc_mode_set
Light LC Mode Set
esp_ble_mesh_state_change_light_lc_om_set_t lc_om_set
Light LC Occupancy Mode Set
esp_ble_mesh_state_change_light_lc_light_onoff_set_t lc_light_onoff_set
Light LC Light OnOff Set
esp_ble_mesh_state_change_light_lc_property_set_t lc_property_set
Light LC Property Set
esp_ble_mesh_state_change_sensor_status_t sensor_status
Sensor Status
union esp_ble_mesh_lighting_server_recv_get_msg_t
#include <esp_ble_mesh_lighting_model_api.h> Lighting Server Model received get message union.
Public Members
esp_ble_mesh_server_recv_light_lc_property_get_t lc_property
Light LC Property Get

union esp_ble_mesh_lighting_server_recv_set_msg_t
#include <esp_ble_mesh_lighting_model_api.h> Lighting Server Model received set message union.
Public Members
esp_ble_mesh_server_recv_light_lightness_set_t lightness
Light Lightness Set/Light Lightness Set Unack
esp_ble_mesh_server_recv_light_lightness_linear_set_t lightness_linear
Light Lightness Linear Set/Light Lightness Linear Set Unack
esp_ble_mesh_server_recv_light_lightness_default_set_t lightness_default
Light Lightness Default Set/Light Lightness Default Set Unack
esp_ble_mesh_server_recv_light_lightness_range_set_t lightness_range
Light Lightness Range Set/Light Lightness Range Set Unack
esp_ble_mesh_server_recv_light_ctl_set_t ctl
Light CTL Set/Light CTL Set Unack
esp_ble_mesh_server_recv_light_ctl_temperature_set_t ctl_temp
Light CTL Temperature Set/Light CTL Temperature Set Unack
esp_ble_mesh_server_recv_light_ctl_temperature_range_set_t ctl_temp_range
Light CTL Temperature Range Set/Light CTL Temperature Range Set Unack
esp_ble_mesh_server_recv_light_ctl_default_set_t ctl_default
Light CTL Default Set/Light CTL Default Set Unack
esp_ble_mesh_server_recv_light_hsl_set_t hsl
Light HSL Set/Light HSL Set Unack
esp_ble_mesh_server_recv_light_hsl_hue_set_t hsl_hue
Light HSL Hue Set/Light HSL Hue Set Unack
esp_ble_mesh_server_recv_light_hsl_saturation_set_t hsl_saturation
Light HSL Saturation Set/Light HSL Saturation Set Unack
esp_ble_mesh_server_recv_light_hsl_default_set_t hsl_default
Light HSL Default Set/Light HSL Default Set Unack
esp_ble_mesh_server_recv_light_hsl_range_set_t hsl_range
Light HSL Range Set/Light HSL Range Set Unack
esp_ble_mesh_server_recv_light_xyl_set_t xyl
Light xyL Set/Light xyL Set Unack
esp_ble_mesh_server_recv_light_xyl_default_set_t xyl_default
Light xyL Default Set/Light xyL Default Set Unack
esp_ble_mesh_server_recv_light_xyl_range_set_t xyl_range
Light xyL Range Set/Light xyL Range Set Unack
esp_ble_mesh_server_recv_light_lc_mode_set_t lc_mode
Light LC Mode Set/Light LC Mode Set Unack
esp_ble_mesh_server_recv_light_lc_om_set_t lc_om
Light LC OM Set/Light LC OM Set Unack
esp_ble_mesh_server_recv_light_lc_light_onoff_set_t lc_light_onoff
Light LC Light OnOff Set/Light LC Light OnOff Set Unack
esp_ble_mesh_server_recv_light_lc_property_set_t lc_property
Light LC Property Set/Light LC Property Set Unack
union esp_ble_mesh_lighting_server_recv_status_msg_t
#include <esp_ble_mesh_lighting_model_api.h> Lighting Server Model received status message union.

Public Members
esp_ble_mesh_server_recv_sensor_status_t sensor_status
Sensor Status
union esp_ble_mesh_lighting_server_cb_value_t
#include <esp_ble_mesh_lighting_model_api.h> Lighting Server Model callback value union.
Public Members
esp_ble_mesh_lighting_server_state_change_t state_change
ESP_BLE_MESH_LIGHTING_SERVER_STATE_CHANGE_EVT
esp_ble_mesh_lighting_server_recv_get_msg_t get
ESP_BLE_MESH_LIGHTING_SERVER_RECV_GET_MSG_EVT
esp_ble_mesh_lighting_server_recv_set_msg_t set
ESP_BLE_MESH_LIGHTING_SERVER_RECV_SET_MSG_EVT
esp_ble_mesh_lighting_server_recv_status_msg_t status
ESP_BLE_MESH_LIGHTING_SERVER_RECV_STATUS_MSG_EVT
Structures
struct esp_ble_mesh_light_lightness_set_t
Bluetooth Mesh Light Lightness Client Model Get and Set parameters structure.
Parameters of Light Lightness Set
Public Members
bool op_en
uint16_t lightness
Target value of light lightness actual state
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_light_lightness_linear_set_t
Parameters of Light Lightness Linear Set
Public Members
bool op_en
uint16_t lightness
Target value of light lightness linear state
uint8_t tid
Transaction ID
uint8_t trans_time

uint8_t delay
struct esp_ble_mesh_light_lightness_default_set_t
Parameter of Light Lightness Default Set
Public Members
uint16_t lightness
The value of the Light Lightness Default state
struct esp_ble_mesh_light_lightness_range_set_t
Parameters of Light Lightness Range Set
Public Members
uint16_t range_min
Value of range min field of light lightness range state
uint16_t range_max
Value of range max field of light lightness range state
struct esp_ble_mesh_light_ctl_set_t
Parameters of Light CTL Set
Public Members
bool op_en
uint16_t ctl_lightness
Target value of light ctl lightness state
uint16_t ctl_temperatrue
Target value of light ctl temperature state
int16_t ctl_delta_uv
Target value of light ctl delta UV state
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_light_ctl_temperature_set_t
Parameters of Light CTL Temperature Set
Public Members
bool op_en
uint16_t ctl_temperatrue
int16_t ctl_delta_uv

uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_light_ctl_temperature_range_set_t
Parameters of Light CTL Temperature Range Set
Public Members
uint16_t range_min
Value of temperature range min field of light ctl temperature range state
uint16_t range_max
Value of temperature range max field of light ctl temperature range state
struct esp_ble_mesh_light_ctl_default_set_t
Parameters of Light CTL Default Set
Public Members
uint16_t lightness
Value of light lightness default state
Value of light temperature default state
int16_t delta_uv
Value of light delta UV default state
struct esp_ble_mesh_light_hsl_set_t
Parameters of Light HSL Set
Public Members
bool op_en
uint16_t hsl_lightness
Target value of light hsl lightness state
uint16_t hsl_hue
Target value of light hsl hue state
uint16_t hsl_saturation
Target value of light hsl saturation state
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_light_hsl_hue_set_t
Parameters of Light HSL Hue Set

Public Members
bool op_en
uint16_t hue
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_light_hsl_saturation_set_t
Parameters of Light HSL Saturation Set
Public Members
bool op_en
uint16_t saturation
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_light_hsl_default_set_t
Parameters of Light HSL Default Set
Public Members
uint16_t lightness
uint16_t hue
Value of light hue default state
uint16_t saturation
Value of light saturation default state
struct esp_ble_mesh_light_hsl_range_set_t
Parameters of Light HSL Range Set
Public Members
uint16_t hue_range_min
Value of hue range min field of light hsl hue range state
uint16_t hue_range_max
Value of hue range max field of light hsl hue range state

uint16_t saturation_range_min
Value of saturation range min field of light hsl saturation range state
uint16_t saturation_range_max
Value of saturation range max field of light hsl saturation range state
struct esp_ble_mesh_light_xyl_set_t
Parameters of Light xyL Set
Public Members
bool op_en
Indicate whether optional parameters included
uint16_t xyl_lightness
The target value of the Light xyL Lightness state
uint16_t xyl_x
The target value of the Light xyL x state
uint16_t xyl_y
The target value of the Light xyL y state
uint8_t tid
Transaction Identifier
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_light_xyl_default_set_t
Parameters of Light xyL Default Set
Public Members
uint16_t lightness
uint16_t xyl_x
The value of the Light xyL x Default state
uint16_t xyl_y
The value of the Light xyL y Default state
struct esp_ble_mesh_light_xyl_range_set_t
Parameters of Light xyL Range Set
Public Members
uint16_t xyl_x_range_min
The value of the xyL x Range Min field of the Light xyL x Range state
uint16_t xyl_x_range_max
The value of the xyL x Range Max field of the Light xyL x Range state
uint16_t xyl_y_range_min
The value of the xyL y Range Min field of the Light xyL y Range state
uint16_t xyl_y_range_max
The value of the xyL y Range Max field of the Light xyL y Range state

struct esp_ble_mesh_light_lc_mode_set_t
Parameter of Light LC Mode Set
Public Members
uint8_t mode
The target value of the Light LC Mode state
struct esp_ble_mesh_light_lc_om_set_t
Parameter of Light LC OM Set
Public Members
uint8_t mode
The target value of the Light LC Occupancy Mode state
struct esp_ble_mesh_light_lc_light_onoff_set_t
Parameters of Light LC Light OnOff Set
Public Members
bool op_en
uint8_t light_onoff
The target value of the Light LC Light OnOff state
uint8_t tid
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_light_lc_property_get_t
Parameter of Light LC Property Get
Public Members
Property ID identifying a Light LC Property
struct esp_ble_mesh_light_lc_property_set_t
Parameters of Light LC Property Set
Public Members
Raw value for the Light LC Property
struct esp_ble_mesh_light_lightness_status_cb_t
Bluetooth Mesh Light Lightness Client Model Get and Set callback parameters structure.
Parameters of Light Lightness Status

Public Members
bool op_en
uint16_t present_lightness
Current value of light lightness actual state
uint16_t target_lightness
Target value of light lightness actual state (optional)
uint8_t remain_time
struct esp_ble_mesh_light_lightness_linear_status_cb_t
Parameters of Light Lightness Linear Status
Public Members
bool op_en
uint16_t present_lightness
Current value of light lightness linear state
Target value of light lightness linear state (optional)
uint8_t remain_time
struct esp_ble_mesh_light_lightness_last_status_cb_t
Parameter of Light Lightness Last Status
Public Members
uint16_t lightness
The value of the Light Lightness Last state
struct esp_ble_mesh_light_lightness_default_status_cb_t
Parameter of Light Lightness Default Status
Public Members
uint16_t lightness
The value of the Light Lightness default State
struct esp_ble_mesh_light_lightness_range_status_cb_t
Parameters of Light Lightness Range Status
Public Members
uint8_t status_code
uint16_t range_min
uint16_t range_max

struct esp_ble_mesh_light_ctl_status_cb_t
Parameters of Light CTL Status
Public Members
bool op_en
uint16_t present_ctl_lightness
Current value of light ctl lightness state
uint16_t present_ctl_temperature
Current value of light ctl temperature state
uint16_t target_ctl_lightness
Target value of light ctl lightness state (optional)
uint16_t target_ctl_temperature
Target value of light ctl temperature state (C.1)
uint8_t remain_time
struct esp_ble_mesh_light_ctl_temperature_status_cb_t
Parameters of Light CTL Temperature Status
Public Members
bool op_en
uint16_t present_ctl_temperature
Current value of light ctl temperature state
uint16_t present_ctl_delta_uv
Current value of light ctl delta UV state
uint16_t target_ctl_temperature
Target value of light ctl temperature state (optional)
uint16_t target_ctl_delta_uv
Target value of light ctl delta UV state (C.1)
uint8_t remain_time
struct esp_ble_mesh_light_ctl_temperature_range_status_cb_t
Parameters of Light CTL Temperature Range Status
Public Members
uint8_t status_code
Status code for the request message
uint16_t range_min
uint16_t range_max
struct esp_ble_mesh_light_ctl_default_status_cb_t
Parameters of Light CTL Default Status

Public Members
uint16_t lightness
int16_t delta_uv
struct esp_ble_mesh_light_hsl_status_cb_t
Parameters of Light HSL Status
Public Members
bool op_en
uint16_t hsl_lightness
Current value of light hsl lightness state
uint16_t hsl_hue
Current value of light hsl hue state
uint16_t hsl_saturation
Current value of light hsl saturation state
uint8_t remain_time
struct esp_ble_mesh_light_hsl_target_status_cb_t
Parameters of Light HSL Target Status
Public Members
bool op_en
uint16_t hsl_lightness_target
uint16_t hsl_hue_target
uint16_t hsl_saturation_target
uint8_t remain_time
struct esp_ble_mesh_light_hsl_hue_status_cb_t
Parameters of Light HSL Hue Status
Public Members
bool op_en
uint16_t present_hue
Current value of light hsl hue state

uint16_t target_hue
Target value of light hsl hue state (optional)
uint8_t remain_time
struct esp_ble_mesh_light_hsl_saturation_status_cb_t
Parameters of Light HSL Saturation Status
Public Members
bool op_en
uint16_t present_saturation
Current value of light hsl saturation state
uint16_t target_saturation
Target value of light hsl saturation state (optional)
uint8_t remain_time
struct esp_ble_mesh_light_hsl_default_status_cb_t
Parameters of Light HSL Default Status
Public Members
uint16_t lightness
uint16_t hue
uint16_t saturation
struct esp_ble_mesh_light_hsl_range_status_cb_t
Parameters of Light HSL Range Status
Public Members
uint8_t status_code
Status code for the request message
struct esp_ble_mesh_light_xyl_status_cb_t
Parameters of Light xyL Status

Public Members
bool op_en
uint16_t xyl_lightness
The present value of the Light xyL Lightness state
uint16_t xyl_x
The present value of the Light xyL x state
uint16_t xyl_y
The present value of the Light xyL y state
uint8_t remain_time
struct esp_ble_mesh_light_xyl_target_status_cb_t
Parameters of Light xyL Target Status
Public Members
bool op_en
uint16_t target_xyl_lightness
uint16_t target_xyl_x
uint16_t target_xyl_y
uint8_t remain_time
struct esp_ble_mesh_light_xyl_default_status_cb_t
Parameters of Light xyL Default Status
Public Members
uint16_t lightness
uint16_t xyl_x
uint16_t xyl_y
struct esp_ble_mesh_light_xyl_range_status_cb_t
Parameters of Light xyL Range Status
Public Members
uint8_t status_code
Status Code for the requesting message
uint16_t xyl_x_range_min

uint16_t xyl_x_range_max
uint16_t xyl_y_range_min
uint16_t xyl_y_range_max
struct esp_ble_mesh_light_lc_mode_status_cb_t
Parameter of Light LC Mode Status
Public Members
uint8_t mode
The present value of the Light LC Mode state
struct esp_ble_mesh_light_lc_om_status_cb_t
Parameter of Light LC OM Status
Public Members
uint8_t mode
The present value of the Light LC Occupancy Mode state
struct esp_ble_mesh_light_lc_light_onoff_status_cb_t
Parameters of Light LC Light OnOff Status
Public Members
bool op_en
uint8_t present_light_onoff
The present value of the Light LC Light OnOff state
uint8_t target_light_onoff
The target value of the Light LC Light OnOff state (Optional)
uint8_t remain_time
struct esp_ble_mesh_light_lc_property_status_cb_t
Parameters of Light LC Property Status
Public Members
struct esp_ble_mesh_light_client_cb_param_t
Lighting Client Model callback parameters

Public Members
int error_code
esp_ble_mesh_light_client_status_cb_t status_cb
The light status message callback values
struct esp_ble_mesh_light_lightness_state_t
Parameters of Light Lightness state
Public Members
uint16_t lightness_linear
The present value of Light Lightness Linear state
uint16_t target_lightness_linear
The target value of Light Lightness Linear state
uint16_t lightness_actual
The present value of Light Lightness Actual state
uint16_t target_lightness_actual
The target value of Light Lightness Actual state
uint16_t lightness_last
The value of Light Lightness Last state
uint16_t lightness_default
The value of Light Lightness Default state
uint8_t status_code
The status code of setting Light Lightness Range state
uint16_t lightness_range_min
The minimum value of Light Lightness Range state
uint16_t lightness_range_max
The maximum value of Light Lightness Range state
struct esp_ble_mesh_light_lightness_srv_t
User data of Light Lightness Server Model
Public Members
Pointer to the Lighting Lightness Server Model. Initialized internally.
esp_ble_mesh_light_lightness_state_t *state
Parameters of the Light Lightness state
esp_ble_mesh_state_transition_t actual_transition
esp_ble_mesh_state_transition_t linear_transition

int32_t tt_delta_lightness_actual
Delta change value of lightness actual state transition
int32_t tt_delta_lightness_linear
Delta change value of lightness linear state transition
struct esp_ble_mesh_light_lightness_setup_srv_t
User data of Light Lightness Setup Server Model
Public Members
Pointer to the Lighting Lightness Setup Server Model. Initialized internally.
esp_ble_mesh_light_lightness_state_t *state
Parameters of the Light Lightness state
struct esp_ble_mesh_light_ctl_state_t
Parameters of Light CTL state
Public Members
uint16_t lightness
The present value of Light CTL Lightness state
The target value of Light CTL Lightness state
The present value of Light CTL Temperature state
uint16_t target_temperature
The target value of Light CTL Temperature state
int16_t delta_uv
The present value of Light CTL Delta UV state
int16_t target_delta_uv
The target value of Light CTL Delta UV state
uint8_t status_code
The statue code of setting Light CTL Temperature Range state
uint16_t temperature_range_min
The minimum value of Light CTL Temperature Range state
uint16_t temperature_range_max
The maximum value of Light CTL Temperature Range state
uint16_t temperature_default
The value of Light CTL Temperature Default state
int16_t delta_uv_default
The value of Light CTL Delta UV Default state
struct esp_ble_mesh_light_ctl_srv_t
User data of Light CTL Server Model

Public Members
Pointer to the Lighting CTL Server Model. Initialized internally.
esp_ble_mesh_light_ctl_state_t *state
Parameters of the Light CTL state
int32_t tt_delta_lightness
Delta change value of lightness state transition
int32_t tt_delta_temperature
Delta change value of temperature state transition
int32_t tt_delta_delta_uv
Delta change value of delta uv state transition
struct esp_ble_mesh_light_ctl_setup_srv_t
User data of Light CTL Setup Server Model
Public Members
Pointer to the Lighting CTL Setup Server Model. Initialized internally.
struct esp_ble_mesh_light_ctl_temp_srv_t
User data of Light CTL Temperature Server Model
Public Members
Pointer to the Lighting CTL Temperature Server Model. Initialized internally.
int32_t tt_delta_temperature
Delta change value of temperature state transition
int32_t tt_delta_delta_uv
Delta change value of delta uv state transition

struct esp_ble_mesh_light_hsl_state_t
Parameters of Light HSL state
Public Members
uint16_t lightness
The present value of Light HSL Lightness state
The target value of Light HSL Lightness state
uint16_t hue
The present value of Light HSL Hue state
uint16_t target_hue
The target value of Light HSL Hue state
uint16_t saturation
The present value of Light HSL Saturation state
uint16_t target_saturation
The target value of Light HSL Saturation state
uint16_t hue_default
The value of Light HSL Hue Default state
uint16_t saturation_default
The value of Light HSL Saturation Default state
uint8_t status_code
The status code of setting Light HSL Hue & Saturation Range state
The minimum value of Light HSL Hue Range state
The maximum value of Light HSL Hue Range state
The minimum value of Light HSL Saturation state
The maximum value of Light HSL Saturation state
struct esp_ble_mesh_light_hsl_srv_t
User data of Light HSL Server Model
Public Members
Pointer to the Lighting HSL Server Model. Initialized internally.
esp_ble_mesh_light_hsl_state_t *state
Parameters of the Light HSL state

int32_t tt_delta_hue
Delta change value of hue state transition
int32_t tt_delta_saturation
Delta change value of saturation state transition
struct esp_ble_mesh_light_hsl_setup_srv_t
User data of Light HSL Setup Server Model
Public Members
Pointer to the Lighting HSL Setup Server Model. Initialized internally.
struct esp_ble_mesh_light_hsl_hue_srv_t
User data of Light HSL Hue Server Model
Public Members
Pointer to the Lighting HSL Hue Server Model. Initialized internally.
int32_t tt_delta_hue
Delta change value of hue state transition
struct esp_ble_mesh_light_hsl_sat_srv_t
User data of Light HSL Saturation Server Model
Public Members
Pointer to the Lighting HSL Saturation Server Model. Initialized internally.

int32_t tt_delta_saturation
Delta change value of saturation state transition
struct esp_ble_mesh_light_xyl_state_t
Parameters of Light xyL state
Public Members
uint16_t lightness
The present value of Light xyL Lightness state
The target value of Light xyL Lightness state
uint16_t x
The present value of Light xyL x state
uint16_t target_x
The target value of Light xyL x state
uint16_t y
The present value of Light xyL y state
uint16_t target_y
The target value of Light xyL y state
uint16_t x_default
The value of Light xyL x Default state
uint16_t y_default
The value of Light xyL y Default state
uint8_t status_code
The status code of setting Light xyL x & y Range state
uint16_t x_range_min
The minimum value of Light xyL x Range state
uint16_t x_range_max
The maximum value of Light xyL x Range state
uint16_t y_range_min
The minimum value of Light xyL y Range state
uint16_t y_range_max
The maximum value of Light xyL y Range state
struct esp_ble_mesh_light_xyl_srv_t
User data of Light xyL Server Model
Public Members
Pointer to the Lighting xyL Server Model. Initialized internally.
esp_ble_mesh_light_xyl_state_t *state
Parameters of the Light xyL state

int32_t tt_delta_x
Delta change value of x state transition
int32_t tt_delta_y
Delta change value of y state transition
struct esp_ble_mesh_light_xyl_setup_srv_t
User data of Light xyL Setup Server Model
Public Members
Pointer to the Lighting xyL Setup Server Model. Initialized internally.
esp_ble_mesh_light_xyl_state_t *state
Parameters of the Light xyL state
struct esp_ble_mesh_light_lc_state_t
Parameters of Light LC states
Public Members
uint32_t mode : 1
0b0 The controller is turned off.
• The binding with the Light Lightness state is disabled. 0b1 The controller is turned on.
• The binding with the Light Lightness state is enabled.The value of Light LC Mode state
uint32_t occupancy_mode : 1
The value of Light LC Occupancy Mode state
uint32_t light_onoff : 1
The present value of Light LC Light OnOff state
uint32_t target_light_onoff : 1
The target value of Light LC Light OnOff state
uint32_t occupancy : 1
The value of Light LC Occupancy state
uint32_t ambient_luxlevel : 24
The value of Light LC Ambient LuxLevel state
uint16_t linear_output
1. Light LC Linear Output = max((Lightness Out)^2/65535, Regulator Output)
2. If the Light LC Mode state is set to 0b1, the binding is enabled and upon a change of the Light LC
Linear Output state, the following operation shall be performed: Light Lightness Linear = Light LC
Linear Output
3. If the Light LC Mode state is set to 0b0, the binding is disabled (i.e., upon a change of the Light
LC Linear Output state, no operation on the Light Lightness Linear state is performed).The value
of Light LC Linear Output state

struct esp_ble_mesh_light_lc_property_state_t
Parameters of Light Property states. The Light LC Property states are read / write states that determine the
configuration of a Light Lightness Controller. Each state is represented by a device property and is controlled
by Light LC Property messages.
Public Members
uint32_t time_occupancy_delay
A timing state that determines the delay for changing the Light LC Occupancy state upon receiving a
Sensor Status message from an occupancy sensor.The value of Light LC Time Occupancy Delay state
uint32_t time_fade_on
A timing state that determines the time the controlled lights fade to the level determined by the Light LC
Lightness On state.The value of Light LC Time Fade On state
uint32_t time_run_on
A timing state that determines the time the controlled lights stay at the level determined by the Light LC
Lightness On state.The value of Light LC Time Run On state
uint32_t time_fade
A timing state that determines the time the controlled lights fade from the level determined by the Light
LC Lightness On state to the level determined by the Light Lightness Prolong state.The value of Light
LC Time Fade state
uint32_t time_prolong
A timing state that determines the time the controlled lights stay at the level determined by the Light LC
Lightness Prolong state.The value of Light LC Time Prolong state
uint32_t time_fade_standby_auto
LC Lightness Prolong state to the level determined by the Light LC Lightness Standby state when the
transition is automatic.The value of Light LC Time Fade Standby Auto state
uint32_t time_fade_standby_manual
LC Lightness Prolong state to the level determined by the Light LC Lightness Standby state when the
transition is triggered by a change in the Light LC Light OnOff state.The value of Light LC Time Fade
Standby Manual state
uint16_t lightness_on
A lightness state that determines the perceptive light lightness at the Occupancy and Run internal con-
troller states.The value of Light LC Lightness On state
uint16_t lightness_prolong
A lightness state that determines the light lightness at the Prolong internal controller state.The value of
Light LC Lightness Prolong state
uint16_t lightness_standby
A lightness state that determines the light lightness at the Standby internal controller state.The value of
Light LC Lightness Standby state
uint16_t ambient_luxlevel_on
A uint16 state representing the Ambient LuxLevel level that determines if the controller transitions from
the Light Control Standby state.The value of Light LC Ambient LuxLevel On state
uint16_t ambient_luxlevel_prolong
A uint16 state representing the required Ambient LuxLevel level in the Prolong state.The value of Light
LC Ambient LuxLevel Prolong state
uint16_t ambient_luxlevel_standby
A uint16 state representing the required Ambient LuxLevel level in the Standby state.The value of Light
LC Ambient LuxLevel Standby state

float regulator_kiu
A float32 state representing the integral coefficient that determines the integral part of the equation defin-
ing the output of the Light LC PI Feedback Regulator, when Light LC Ambient LuxLevel is less than
LuxLevel Out. Valid range: 0.0 ~ 1000.0. The default value is 250.0.The value of Light LC Regulator
Kiu state
float regulator_kid
A float32 state representing the integral coefficient that determines the integral part of the equation defin-
ing the output of the Light LC PI Feedback Regulator, when Light LC Ambient LuxLevel is greater than
or equal to the value of the LuxLevel Out state. Valid range: 0.0 ~ 1000.0. The default value is 25.0.The
value of Light LC Regulator Kid state
float regulator_kpu
A float32 state representing the proportional coefficient that determines the proportional part of the equa-
tion defining the output of the Light LC PI Feedback Regulator, when Light LC Ambient LuxLevel is
less than the value of the LuxLevel Out state. Valid range: 0.0 ~ 1000.0. The default value is 80.0.The
value of Light LC Regulator Kpu state
float regulator_kpd
A float32 state representing the proportional coefficient that determines the proportional part of the equa-
tion defining the output of the Light LC PI Feedback Regulator, when Light LC Ambient LuxLevel is
greater than or equal to the value of the LuxLevel Out state. Valid range: 0.0 ~ 1000.0. The default value
is 80.0.The value of Light LC Regulator Kpd state
int8_t regulator_accuracy
A int8 state representing the percentage accuracy of the Light LC PI Feedback Regulator. Valid range:
0.0 ~ 100.0. The default value is 2.0.The value of Light LC Regulator Accuracy state
uint32_t set_occupancy_to_1_delay
If the message Raw field contains a Raw Value for the Time Since Motion Sensed device property,
which represents a value less than or equal to the value of the Light LC Occupancy Delay state, it shall
delay setting the Light LC Occupancy state to 0b1 by the difference between the value of the Light LC
Occupancy Delay state and the received Time Since Motion value. The value of the difference between
value of the Light LC Occupancy Delay state and the received Time Since Motion value
struct esp_ble_mesh_light_lc_state_machine_t
Parameters of Light LC state machine
Public Members
uint8_t fade_on
The value of transition time of Light LC Time Fade On
uint8_t fade
The value of transition time of Light LC Time Fade
uint8_t fade_standby_auto
The value of transition time of Light LC Time Fade Standby Auto
uint8_t fade_standby_manual
The value of transition time of Light LC Time Fade Standby Manual
struct esp_ble_mesh_light_lc_state_machine_t::[anonymous] trans_time
The Fade On, Fade, Fade Standby Auto, and Fade Standby Manual states are transition states that define
the transition of the Lightness Out and LuxLevel Out states. This transition can be started as a result of
the Light LC State Machine change or as a result of receiving the Light LC Light OnOff Set or Light LC
Light Set Unacknowledged message.The value of transition time
esp_ble_mesh_lc_state_t state
The value of Light LC state machine state
Timer of Light LC state machine

struct esp_ble_mesh_light_control_t
Parameters of Light Lightness controller
Public Members
esp_ble_mesh_light_lc_state_t state
Parameters of Light LC state
esp_ble_mesh_light_lc_property_state_t prop_state
Parameters of Light LC Property state
esp_ble_mesh_light_lc_state_machine_t state_machine
Parameters of Light LC state machine
struct esp_ble_mesh_light_lc_srv_t
User data of Light LC Server Model
Public Members
Pointer to the Lighting LC Server Model. Initialized internally.
esp_ble_mesh_light_control_t *lc
Parameters of the Light controller
struct esp_ble_mesh_light_lc_setup_srv_t
User data of Light LC Setup Server Model
Public Members
Pointer to the Lighting LC Setup Server Model. Initialized internally.
esp_ble_mesh_light_control_t *lc
Parameters of the Light controller
struct esp_ble_mesh_state_change_light_lightness_set_t
Parameter of Light Lightness Actual state change event
Public Members
uint16_t lightness
The value of Light Lightness Actual state
struct esp_ble_mesh_state_change_light_lightness_linear_set_t
Parameter of Light Lightness Linear state change event

Public Members
uint16_t lightness
The value of Light Lightness Linear state
struct esp_ble_mesh_state_change_light_lightness_default_set_t
Parameter of Light Lightness Default state change event
Public Members
uint16_t lightness
struct esp_ble_mesh_state_change_light_lightness_range_set_t
Parameters of Light Lightness Range state change event
Public Members
uint16_t range_min
The minimum value of Light Lightness Range state
uint16_t range_max
The maximum value of Light Lightness Range state
struct esp_ble_mesh_state_change_light_ctl_set_t
Parameters of Light CTL state change event
Public Members
uint16_t lightness
The value of Light CTL Lightness state
The value of Light CTL Temperature state
int16_t delta_uv
The value of Light CTL Delta UV state
struct esp_ble_mesh_state_change_light_ctl_temperature_set_t
Parameters of Light CTL Temperature state change event
Public Members
The value of Light CTL Temperature state
int16_t delta_uv
The value of Light CTL Delta UV state
struct esp_ble_mesh_state_change_light_ctl_temperature_range_set_t
Parameters of Light CTL Temperature Range state change event
Public Members
uint16_t range_min
The minimum value of Light CTL Temperature Range state
uint16_t range_max
The maximum value of Light CTL Temperature Range state

struct esp_ble_mesh_state_change_light_ctl_default_set_t
Parameters of Light CTL Default state change event
Public Members
uint16_t lightness
The value of Light CTL Temperature Default state
int16_t delta_uv
The value of Light CTL Delta UV Default state
struct esp_ble_mesh_state_change_light_hsl_set_t
Parameters of Light HSL state change event
Public Members
uint16_t lightness
The value of Light HSL Lightness state
uint16_t hue
The value of Light HSL Hue state
uint16_t saturation
The value of Light HSL Saturation state
struct esp_ble_mesh_state_change_light_hsl_hue_set_t
Parameter of Light HSL Hue state change event
Public Members
uint16_t hue
The value of Light HSL Hue state
struct esp_ble_mesh_state_change_light_hsl_saturation_set_t
Parameter of Light HSL Saturation state change event
Public Members
uint16_t saturation
The value of Light HSL Saturation state
struct esp_ble_mesh_state_change_light_hsl_default_set_t
Parameters of Light HSL Default state change event
Public Members
uint16_t lightness
The value of Light HSL Lightness Default state
uint16_t hue
The value of Light HSL Hue Default state
uint16_t saturation
The value of Light HSL Saturation Default state
struct esp_ble_mesh_state_change_light_hsl_range_set_t
Parameters of Light HSL Range state change event

Public Members
The minimum hue value of Light HSL Range state
The maximum hue value of Light HSL Range state
The minimum saturation value of Light HSL Range state
The maximum saturation value of Light HSL Range state
struct esp_ble_mesh_state_change_light_xyl_set_t
Parameters of Light xyL state change event
Public Members
uint16_t lightness
The value of Light xyL Lightness state
uint16_t x
The value of Light xyL x state
uint16_t y
The value of Light xyL y state
struct esp_ble_mesh_state_change_light_xyl_default_set_t
Parameters of Light xyL Default state change event
Public Members
uint16_t lightness
uint16_t x
The value of Light xyL x Default state
uint16_t y
The value of Light xyL y Default state
struct esp_ble_mesh_state_change_light_xyl_range_set_t
Parameters of Light xyL Range state change event
Public Members
The minimum value of Light xyL x Range state
The maximum value of Light xyL x Range state
The minimum value of Light xyL y Range state
The maximum value of Light xyL y Range state
struct esp_ble_mesh_state_change_light_lc_mode_set_t
Parameter of Light LC Mode state change event

Public Members
uint8_t mode
The value of Light LC Mode state
struct esp_ble_mesh_state_change_light_lc_om_set_t
Parameter of Light LC Occupancy Mode state change event
Public Members
uint8_t mode
The value of Light LC Occupancy Mode state
struct esp_ble_mesh_state_change_light_lc_light_onoff_set_t
Parameter of Light LC Light OnOff state change event
Public Members
uint8_t onoff
The value of Light LC Light OnOff state
struct esp_ble_mesh_state_change_light_lc_property_set_t
Parameters of Light LC Property state change event
Public Members
The property id of Light LC Property state
The property value of Light LC Property state
struct esp_ble_mesh_state_change_sensor_status_t
Parameters of Sensor Status state change event
Public Members
The value of Sensor Property ID
uint8_t occupancy
The value of Light LC Occupancy state
uint32_t set_occupancy_to_1_delay
The value of Light LC Set Occupancy to 1 Delay state
uint32_t ambient_luxlevel
The value of Light LC Ambient Luxlevel state
union esp_ble_mesh_state_change_sensor_status_t::[anonymous] state
Parameters of Sensor Status related state
struct esp_ble_mesh_server_recv_light_lc_property_get_t
Context of the received Light LC Property Get message

Public Members
struct esp_ble_mesh_server_recv_light_lightness_set_t
Context of the received Light Lightness Set message
Public Members
bool op_en
uint16_t lightness
Target value of light lightness actual state
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_server_recv_light_lightness_linear_set_t
Context of the received Light Lightness Linear Set message
Public Members
bool op_en
uint16_t lightness
Target value of light lightness linear state
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_server_recv_light_lightness_default_set_t
Context of the received Light Lightness Default Set message
Public Members
uint16_t lightness
struct esp_ble_mesh_server_recv_light_lightness_range_set_t
Context of the received Light Lightness Range Set message
Public Members
uint16_t range_min

uint16_t range_max
struct esp_ble_mesh_server_recv_light_ctl_set_t
Context of the received Light CTL Set message
Public Members
bool op_en
uint16_t lightness
Target value of light ctl lightness state
int16_t delta_uv
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_server_recv_light_ctl_temperature_set_t
Context of the received Light CTL Temperature Set message
Public Members
bool op_en
int16_t delta_uv
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_server_recv_light_ctl_temperature_range_set_t
Context of the received Light CTL Temperature Range Set message
Public Members
uint16_t range_min
uint16_t range_max

struct esp_ble_mesh_server_recv_light_ctl_default_set_t
Context of the received Light CTL Default Set message
Public Members
uint16_t lightness
int16_t delta_uv
struct esp_ble_mesh_server_recv_light_hsl_set_t
Context of the received Light HSL Set message
Public Members
bool op_en
uint16_t lightness
uint16_t hue
uint16_t saturation
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_server_recv_light_hsl_hue_set_t
Context of the received Light HSL Hue Set message
Public Members
bool op_en
uint16_t hue
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_server_recv_light_hsl_saturation_set_t
Context of the received Light HSL Saturation Set message

Public Members
bool op_en
uint16_t saturation
uint8_t tid
Transaction ID
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_server_recv_light_hsl_default_set_t
Context of the received Light HSL Default Set message
Public Members
uint16_t lightness
uint16_t hue
uint16_t saturation
struct esp_ble_mesh_server_recv_light_hsl_range_set_t
Context of the received Light HSL Range Set message
Public Members
struct esp_ble_mesh_server_recv_light_xyl_set_t
Context of the received Light xyL Set message
Public Members
bool op_en
uint16_t lightness
uint16_t x

uint16_t y
uint8_t tid
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_server_recv_light_xyl_default_set_t
Context of the received Light xyL Default Set message
Public Members
uint16_t lightness
uint16_t x
uint16_t y
struct esp_ble_mesh_server_recv_light_xyl_range_set_t
Context of the received Light xyl Range Set message
Public Members
struct esp_ble_mesh_server_recv_light_lc_mode_set_t
Context of the received Light LC Mode Set message
Public Members
uint8_t mode
The target value of the Light LC Mode state
struct esp_ble_mesh_server_recv_light_lc_om_set_t
Context of the received Light OM Set message
Public Members
uint8_t mode
The target value of the Light LC Occupancy Mode state
struct esp_ble_mesh_server_recv_light_lc_light_onoff_set_t
Context of the received Light LC Light OnOff Set message

Public Members
bool op_en
uint8_t light_onoff
The target value of the Light LC Light OnOff state
uint8_t tid
uint8_t trans_time
uint8_t delay
struct esp_ble_mesh_server_recv_light_lc_property_set_t
Context of the received Light LC Property Set message
Public Members
struct esp_ble_mesh_server_recv_sensor_status_t
Context of the received Sensor Status message
Public Members
struct net_buf_simple *data

Value of sensor data state (optional)
struct esp_ble_mesh_lighting_server_cb_param_t
Lighting Server Model callback parameters
Public Members
Pointer to Lighting Server Models
esp_ble_mesh_lighting_server_cb_value_t value
Value of the received Lighting Messages
Macros
ESP_BLE_MESH_MODEL_LIGHT_LIGHTNESS_CLI(cli_pub, cli_data)
Define a new Light Lightness Client Model.
Note This API needs to be called for each element on which the application needs to have a Light Lightness
Client Model.
Return New Light Lightness Client Model instance.
Parameters

ESP_BLE_MESH_MODEL_LIGHT_CTL_CLI(cli_pub, cli_data)
Define a new Light CTL Client Model.
Note This API needs to be called for each element on which the application needs to have a Light CTL Client
Model.
Return New Light CTL Client Model instance.
Parameters
ESP_BLE_MESH_MODEL_LIGHT_HSL_CLI(cli_pub, cli_data)
Define a new Light HSL Client Model.
Note This API needs to be called for each element on which the application needs to have a Light HSL Client
Model.
Return New Light HSL Client Model instance.
Parameters
ESP_BLE_MESH_MODEL_LIGHT_XYL_CLI(cli_pub, cli_data)
Define a new Light xyL Client Model.
Note This API needs to be called for each element on which the application needs to have a Light xyL Client
Model.
Return New Light xyL Client Model instance.
Parameters
ESP_BLE_MESH_MODEL_LIGHT_LC_CLI(cli_pub, cli_data)
Define a new Light LC Client Model.
Note This API needs to be called for each element on which the application needs to have a Light LC Client
Model.
Return New Light LC Client Model instance.
Parameters
ESP_BLE_MESH_MODEL_LIGHT_LIGHTNESS_SRV(srv_pub, srv_data)
Lighting Server Models related context.
Define a new Light Lightness Server Model.
Note 1. The Light Lightness Server model extends the Generic Power OnOff Server model and the Generic
Level Server model. When this model is present on an Element, the corresponding Light Lightness Setup
Server model shall also be present.
Return New Light Lightness Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_light_lightness_srv_t.
ESP_BLE_MESH_MODEL_LIGHT_LIGHTNESS_SETUP_SRV(srv_pub, srv_data)
Define a new Light Lightness Setup Server Model.
Note 1. The Light Lightness Setup Server model extends the Light Lightness Server model and the Generic
Power OnOff Setup Server model.
Return New Light Lightness Setup Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_light_lightness_setup_srv_t.

ESP_BLE_MESH_MODEL_LIGHT_CTL_SRV(srv_pub, srv_data)
Define a new Light CTL Server Model.
Note 1. The Light CTL Server model extends the Light Lightness Server model. When this model is present
on an Element, the corresponding Light CTL Temperature Server model and the corresponding Light
CTL Setup Server model shall also be present.
2. The model requires two elements: the main element and the Temperature element. The Temperature
element contains the corresponding Light CTL Temperature Server model and an instance of a
Generic Level state bound to the Light CTL Temperature state on the Temperature element. The
Light CTL Temperature state on the Temperature element is bound to the Light CTL state on the
main element.
Return New Light CTL Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_light_ctl_srv_t.
ESP_BLE_MESH_MODEL_LIGHT_CTL_SETUP_SRV(srv_pub, srv_data)
Define a new Light CTL Setup Server Model.
Note 1. The Light CTL Setup Server model extends the Light CTL Server and the Light Lightness Setup
Server.
Return New Light CTL Setup Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_light_ctl_setup_srv_t.
ESP_BLE_MESH_MODEL_LIGHT_CTL_TEMP_SRV(srv_pub, srv_data)
Define a new Light CTL Temperature Server Model.
Note 1. The Light CTL Temperature Server model extends the Generic Level Server model.
Return New Light CTL Temperature Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_light_ctl_temp_srv_t.
ESP_BLE_MESH_MODEL_LIGHT_HSL_SRV(srv_pub, srv_data)
Define a new Light HSL Server Model.
Note 1. The Light HSL Server model extends the Light Lightness Server model. When this model is present on
an Element, the corresponding Light HSL Hue Server model and the corresponding Light HSL Saturation
Server model and the corresponding Light HSL Setup Server model shall also be present.
2. The model requires three elements: the main element and the Hue element and the Saturation ele-
ment. The Hue element contains the corresponding Light HSL Hue Server model and an instance
of a Generic Level state bound to the Light HSL Hue state on the Hue element. The Saturation el-
ement contains the corresponding Light HSL Saturation Server model and an instance of a Generic
Level state bound to the Light HSL Saturation state on the Saturation element. The Light HSL Hue
state on the Hue element is bound to the Light HSL state on the main element and the Light HSL
Saturation state on the Saturation element is bound to the Light HSL state on the main element.
Return New Light HSL Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_light_hsl_srv_t.
ESP_BLE_MESH_MODEL_LIGHT_HSL_SETUP_SRV(srv_pub, srv_data)
Define a new Light HSL Setup Server Model.
Note 1. The Light HSL Setup Server model extends the Light HSL Server and the Light Lightness Setup
Server.

Return New Light HSL Setup Server Model instance.

Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_light_hsl_setup_srv_t.
ESP_BLE_MESH_MODEL_LIGHT_HSL_HUE_SRV(srv_pub, srv_data)
Define a new Light HSL Hue Server Model.
Note 1. The Light HSL Hue Server model extends the Generic Level Server model. This model is associated
with the Light HSL Server model.
Return New Light HSL Hue Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_light_hsl_hue_srv_t.
ESP_BLE_MESH_MODEL_LIGHT_HSL_SAT_SRV(srv_pub, srv_data)
Define a new Light HSL Saturation Server Model.
Note 1. The Light HSL Saturation Server model extends the Generic Level Server model. This model is
associated with the Light HSL Server model.
Return New Light HSL Saturation Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_light_hsl_sat_srv_t.
ESP_BLE_MESH_MODEL_LIGHT_XYL_SRV(srv_pub, srv_data)
Define a new Light xyL Server Model.
Note 1. The Light xyL Server model extends the Light Lightness Server model. When this model is present
on an Element, the corresponding Light xyL Setup Server model shall also be present.
Return New Light xyL Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_light_xyl_srv_t.
ESP_BLE_MESH_MODEL_LIGHT_XYL_SETUP_SRV(srv_pub, srv_data)
Define a new Light xyL Setup Server Model.
Note 1. The Light xyL Setup Server model extends the Light xyL Server and the Light Lightness Setup Server.
Return New Light xyL Setup Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_light_xyl_setup_srv_t.
ESP_BLE_MESH_MODEL_LIGHT_LC_SRV(srv_pub, srv_data)
Define a new Light LC Server Model.
Note 1. The Light LC (Lightness Control) Server model extends the Light Lightness Server model and the
Generic OnOff Server model. When this model is present on an Element, the corresponding Light LC
Setup Server model shall also be present.
2. This model may be used to represent an element that is a client to a Sensor Server model and controls
the Light Lightness Actual state via defined state bindings.
Return New Light LC Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_light_lc_srv_t.
ESP_BLE_MESH_MODEL_LIGHT_LC_SETUP_SRV(srv_pub, srv_data)
Define a new Light LC Setup Server Model.

Note 1. The Light LC (Lightness Control) Setup model extends the Light LC Server model.
2. This model may be used to configure setup parameters for the Light LC Server model.
Return New Light LC Setup Server Model instance.
Parameters
• srv_data: Pointer to the unique struct esp_ble_mesh_light_lc_setup_srv_t.
Type Definitions
typedef void (*esp_ble_mesh_light_client_cb_t)(esp_ble_mesh_light_client_cb_event_t
event, esp_ble_mesh_light_client_cb_param_t
*param)
Bluetooth Mesh Light Client Model function.
Lighting Client Model callback function type
Parameters
typedef void (*esp_ble_mesh_lighting_server_cb_t)(esp_ble_mesh_lighting_server_cb_event_t
event,
esp_ble_mesh_lighting_server_cb_param_t
*param)
Bluetooth Mesh Lighting Server Model function.
Lighting Server Model callback function type
Parameters
Enumerations
enum esp_ble_mesh_light_client_cb_event_t
This enum value is the event of Lighting Client Model
Values:
ESP_BLE_MESH_LIGHT_CLIENT_GET_STATE_EVT
ESP_BLE_MESH_LIGHT_CLIENT_SET_STATE_EVT
ESP_BLE_MESH_LIGHT_CLIENT_PUBLISH_EVT
ESP_BLE_MESH_LIGHT_CLIENT_TIMEOUT_EVT
ESP_BLE_MESH_LIGHT_CLIENT_EVT_MAX
enum esp_ble_mesh_lc_state_t
This enum value is the Light LC State Machine states
Values:
ESP_BLE_MESH_LC_OFF
ESP_BLE_MESH_LC_STANDBY
ESP_BLE_MESH_LC_FADE_ON
ESP_BLE_MESH_LC_RUN
ESP_BLE_MESH_LC_FADE
ESP_BLE_MESH_LC_PROLONG
ESP_BLE_MESH_LC_FADE_STANDBY_AUTO
ESP_BLE_MESH_LC_FADE_STANDBY_MANUAL

enum esp_ble_mesh_lighting_server_cb_event_t
This enum value is the event of Lighting Server Model
Values:
ESP_BLE_MESH_LIGHTING_SERVER_STATE_CHANGE_EVT
to the application layer when Lighting Get messages are received.
to the application layer when Lighting Set/Set Unack messages are received.
ESP_BLE_MESH_LIGHTING_SERVER_RECV_GET_MSG_EVT
the application layer when Lighting Get messages are received.
ESP_BLE_MESH_LIGHTING_SERVER_RECV_SET_MSG_EVT
the application layer when Lighting Set/Set Unack messages are received.
ESP_BLE_MESH_LIGHTING_SERVER_RECV_STATUS_MSG_EVT
When status_auto_rsp is set to ESP_BLE_MESH_SERVER_RSP_BY_APP, this event will be callback
to the application layer when Sensor Status message is received.
ESP_BLE_MESH_LIGHTING_SERVER_EVT_MAX
ESP-IDF currently supports two host stacks. The Bluedroid based stack (default) supports classic Bluetooth as well
as BLE. On the other hand, Apache NimBLE based stack is BLE only. For users to make a choice:
• For usecases involving classic Bluetooth as well as BLE, Bluedroid should be used.
• For BLE-only usecases, using NimBLE is recommended. It is less demanding in terms of code footprint and
runtime memory, making it suitable for such scenarios.
For the overview of the ESP32 Bluetooth stack architecture, follow the links below:
• ESP32 Bluetooth Architecture (PDF) [English]
• ESP32 Bluetooth Architecture (PDF) [ ]
Code examples for this API section are provided in the bluetooth/bluedroid directory of ESP-IDF examples.
The following examples contain detailed walkthroughs:
• GATT Client Example Walkthrough
• GATT Server Service Table Example Walkthrough
• GATT Server Example Walkthrough
• GATT Security Client Example Walkthrough
• GATT Security Server Example Walkthrough
• GATT Client Multi-connection Example Walkthrough
2.2 Networking APIs
2.2.1 Wi-Fi
Wi-Fi
Introduction The Wi-Fi libraries provide support for configuring and monitoring the ESP32 Wi-Fi networking
functionality. This includes configuration for:
• Station mode (aka STA mode or Wi-Fi client mode). ESP32 connects to an access point.
• AP mode (aka Soft-AP mode or Access Point mode). Stations connect to the ESP32.
• Combined AP-STA mode (ESP32 is concurrently an access point and a station connected to another access
point).
• Various security modes for the above (WPA, WPA2, WEP, etc.)
• Scanning for access points (active & passive scanning).

• Promiscuous mode for monitoring of IEEE802.11 Wi-Fi packets.
Application Examples The wifi directory of ESP-IDF examples contains the following applications:
Code examples for Wi-Fi are provided in the wifi directory of ESP-IDF examples.
In addition, there is a simple esp-idf-template application to demonstrate a minimal IDF project structure.
API Reference
Header File
• components/esp_wifi/include/esp_wifi.h
Functions
esp_err_t esp_wifi_init(const wifi_init_config_t *config)
Init WiFi Alloc resource for WiFi driver, such as WiFi control structure, RX/TX buffer, WiFi NVS structure
etc, this WiFi also start WiFi task.
Attention 1. This API must be called before all other WiFi API can be called
Attention 2. Always use WIFI_INIT_CONFIG_DEFAULT macro to init the config to default values, this
can guarantee all the fields got correct value when more fields are added into wifi_init_config_t in fu-
ture release. If you want to set your owner initial values, overwrite the default values which are set by
WIFI_INIT_CONFIG_DEFAULT, please be notified that the field magic of wifi_init_config_t should
always be WIFI_INIT_CONFIG_MAGIC!
Return
• ESP_OK: succeed
• ESP_ERR_NO_MEM: out of memory
• others: refer to error code esp_err.h
Parameters
• config: pointer to WiFi init configuration structure; can point to a temporary variable.
esp_err_t esp_wifi_deinit(void)
Deinit WiFi Free all resource allocated in esp_wifi_init and stop WiFi task.
Attention 1. This API should be called if you want to remove WiFi driver from the system
Return
• ESP_OK: succeed
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
esp_err_t esp_wifi_set_mode(wifi_mode_t mode)
Set the WiFi operating mode.
Set the WiFi operating mode as station, soft-AP or station+soft-AP, The default mode is station mode.
Return
• ESP_OK: succeed
• ESP_ERR_INVALID_ARG: invalid argument
• others: refer to error code in esp_err.h
Parameters
• mode: WiFi operating mode
esp_err_t esp_wifi_get_mode(wifi_mode_t *mode)
Get current operating mode of WiFi.
Return
• ESP_OK: succeed
Parameters

• [out] mode: store current WiFi mode

esp_err_t esp_wifi_start(void)
Start WiFi according to current configuration If mode is WIFI_MODE_STA, it create station control block
and start station If mode is WIFI_MODE_AP, it create soft-AP control block and start soft-AP If mode is
WIFI_MODE_APSTA, it create soft-AP and station control block and start soft-AP and station.
Return
• ESP_OK: succeed
• ESP_ERR_WIFI_CONN: WiFi internal error, station or soft-AP control block wrong
• ESP_FAIL: other WiFi internal errors
esp_err_t esp_wifi_stop(void)
Stop WiFi If mode is WIFI_MODE_STA, it stop station and free station control block If mode is
WIFI_MODE_AP, it stop soft-AP and free soft-AP control block If mode is WIFI_MODE_APSTA, it stop
station/soft-AP and free station/soft-AP control block.
Return
• ESP_OK: succeed
esp_err_t esp_wifi_restore(void)
Restore WiFi stack persistent settings to default values.
This function will reset settings made using the following APIs:
• esp_wifi_set_bandwidth,
• esp_wifi_set_protocol,
• esp_wifi_set_config related
• esp_wifi_set_mode
Return
• ESP_OK: succeed
esp_err_t esp_wifi_connect(void)
Connect the ESP32 WiFi station to the AP.
Attention 1. This API only impact WIFI_MODE_STA or WIFI_MODE_APSTA mode
Attention 2. If the ESP32 is connected to an AP, call esp_wifi_disconnect to disconnect.
Attention 3. The scanning triggered by esp_wifi_start_scan() will not be effective until connection between
ESP32 and the AP is established. If ESP32 is scanning and connecting at the same time, ESP32 will abort
scanning and return a warning message and error number ESP_ERR_WIFI_STATE. If you want to do re-
connection after ESP32 received disconnect event, remember to add the maximum retry time, otherwise
the called scan will not work. This is especially true when the AP doesn t exist, and you still try reconnec-
tion after ESP32 received disconnect event with the reason code WIFI_REASON_NO_AP_FOUND.
Return
• ESP_OK: succeed
• ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start
• ESP_ERR_WIFI_CONN: WiFi internal error, station or soft-AP control block wrong
• ESP_ERR_WIFI_SSID: SSID of AP which station connects is invalid
esp_err_t esp_wifi_disconnect(void)
Disconnect the ESP32 WiFi station from the AP.
Return
• ESP_OK: succeed
• ESP_ERR_WIFI_NOT_INIT: WiFi was not initialized by esp_wifi_init
• ESP_ERR_WIFI_NOT_STARTED: WiFi was not started by esp_wifi_start
• ESP_FAIL: other WiFi internal errors

esp_err_t esp_wifi_clear_fast_connect(void)
Currently this API is just an stub API.
Return
• ESP_OK: succeed
• others: fail
esp_err_t esp_wifi_deauth_sta(uint16_t aid)
deauthenticate all stations or associated id equals to aid
Return
• ESP_OK: succeed
• ESP_ERR_WIFI_MODE: WiFi mode is wrong
Parameters
• aid: when aid is 0, deauthenticate all stations, otherwise deauthenticate station whose associated id
is aid
esp_err_t esp_wifi_scan_start(const wifi_scan_config_t *config, bool block)
Scan all available APs.
Attention If this API is called, the found APs are stored in WiFi driver dynamic allocated memory and the
will be freed in esp_wifi_scan_get_ap_records, so generally, call esp_wifi_scan_get_ap_records to cause
the memory to be freed once the scan is done
Attention The values of maximum active scan time and passive scan time per channel are limited to 1500
milliseconds. Values above 1500ms may cause station to disconnect from AP and are not recommended.
Return
• ESP_OK: succeed
• ESP_ERR_WIFI_TIMEOUT: blocking scan is timeout
• ESP_ERR_WIFI_STATE: wifi still connecting when invoke esp_wifi_scan_start
• others: refer to error code in esp_err.h
Parameters
• config: configuration of scanning
• block: if block is true, this API will block the caller until the scan is done, otherwise it will return
immediately
esp_err_t esp_wifi_scan_stop(void)
Stop the scan in process.
Return
• ESP_OK: succeed
esp_err_t esp_wifi_scan_get_ap_num(uint16_t *number)
Get number of APs found in last scan.
Attention This API can only be called when the scan is completed, otherwise it may get wrong value.
Return
• ESP_OK: succeed
Parameters
• [out] number: store number of APIs found in last scan
esp_err_t esp_wifi_scan_get_ap_records(uint16_t *number, wifi_ap_record_t *ap_records)
Get AP list found in last scan.
Return

• ESP_OK: succeed
Parameters
• [inout] number: As input param, it stores max AP number ap_records can hold. As output
param, it receives the actual AP number this API returns.
• ap_records: wifi_ap_record_t array to hold the found APs
esp_err_t esp_wifi_sta_get_ap_info(wifi_ap_record_t *ap_info)
Get information of AP which the ESP32 station is associated with.
Attention When the obtained country information is empty, it means that the AP does not carry country
information
Return
• ESP_OK: succeed
• ESP_ERR_WIFI_CONN: The station interface don t initialized
• ESP_ERR_WIFI_NOT_CONNECT: The station is in disconnect status
Parameters
• ap_info: the wifi_ap_record_t to hold AP information sta can get the connected ap s phy mode
info through the struct member phy_11b phy_11g phy_11n phy_lr in the wifi_ap_record_t struct.
For example, phy_11b = 1 imply that ap support 802.11b mode
esp_err_t esp_wifi_set_ps(wifi_ps_type_t type)
Set current WiFi power save type.
Attention Default power save type is WIFI_PS_MIN_MODEM.
Return ESP_OK: succeed
Parameters
• type: power save type
esp_err_t esp_wifi_get_ps(wifi_ps_type_t *type)
Get current WiFi power save type.
Attention Default power save type is WIFI_PS_MIN_MODEM.
Return ESP_OK: succeed
Parameters
• [out] type: store current power save type
esp_err_t esp_wifi_set_protocol(wifi_interface_t ifx, uint8_t protocol_bitmap)
Set protocol type of specified interface The default protocol is (WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTO
Attention Currently we only support 802.11b or 802.11bg or 802.11bgn mode
Return
• ESP_OK: succeed
• ESP_ERR_WIFI_IF: invalid interface
• others: refer to error codes in esp_err.h
Parameters
• ifx: interfaces
• protocol_bitmap: WiFi protocol bitmap
esp_err_t esp_wifi_get_protocol(wifi_interface_t ifx, uint8_t *protocol_bitmap)
Get the current protocol bitmap of the specified interface.
Return
• ESP_OK: succeed
Parameters

• ifx: interface
• [out] protocol_bitmap: store current WiFi protocol bitmap of interface ifx
esp_err_t esp_wifi_set_bandwidth(wifi_interface_t ifx, wifi_bandwidth_t bw)
Set the bandwidth of ESP32 specified interface.
Attention 1. API return false if try to configure an interface that is not enabled
Attention 2. WIFI_BW_HT40 is supported only when the interface support 11N
Return
• ESP_OK: succeed
Parameters
• ifx: interface to be configured
• bw: bandwidth
esp_err_t esp_wifi_get_bandwidth(wifi_interface_t ifx, wifi_bandwidth_t *bw)
Get the bandwidth of ESP32 specified interface.
Attention 1. API return false if try to get a interface that is not enable
Return
• ESP_OK: succeed
Parameters
• ifx: interface to be configured
• [out] bw: store bandwidth of interface ifx
esp_err_t esp_wifi_set_channel(uint8_t primary, wifi_second_chan_t second)
Set primary/secondary channel of ESP32.
Attention 1. This API should be called after esp_wifi_start()
Attention 2. When ESP32 is in STA mode, this API should not be called when STA is scanning or connecting
to an external AP
Attention 3. When ESP32 is in softAP mode, this API should not be called when softAP has connected to
external STAs
Attention 4. When ESP32 is in STA+softAP mode, this API should not be called when in the scenarios
described above
Return
• ESP_OK: succeed
Parameters
• primary: for HT20, primary is the channel number, for HT40, primary is the primary channel
• second: for HT20, second is ignored, for HT40, second is the second channel
esp_err_t esp_wifi_get_channel(uint8_t *primary, wifi_second_chan_t *second)
Get the primary/secondary channel of ESP32.
Attention 1. API return false if try to get a interface that is not enable
Return
• ESP_OK: succeed
Parameters
• primary: store current primary channel
• [out] second: store current second channel

esp_err_t esp_wifi_set_country(const wifi_country_t *country)

configure country info
Attention 1. It is discouraged to call this API since this doesn t validate the per-country rules, it s up to
the user to fill in all fields according to local regulations. Please use esp_wifi_set_country_code instead.
Attention 2. The default country is CHINA {.cc= CN , .schan=1, .nchan=13, pol-
icy=WIFI_COUNTRY_POLICY_AUTO}
Attention 3. When the country policy is WIFI_COUNTRY_POLICY_AUTO, the country info of the AP to
which the station is connected is used. E.g. if the configured country info is {.cc= USA , .schan=1,
.nchan=11} and the country info of the AP to which the station is connected is {.cc= JP , .schan=1,
.nchan=14} then the country info that will be used is {.cc= JP , .schan=1, .nchan=14}. If the station
disconnected from the AP the country info is set back to the country info of the station automatically,
{.cc= US , .schan=1, .nchan=11} in the example.
Attention 4. When the country policy is WIFI_COUNTRY_POLICY_MANUAL, then the configured coun-
try info is used always.
Attention 5. When the country info is changed because of configuration or because the station connects to a
different external AP, the country IE in probe response/beacon of the soft-AP is also changed.
Attention 6. The country configuration is stored into flash.
Attention 7. When this API is called, the PHY init data will switch to the PHY init data type corresponding
to the country info.
Return
• ESP_OK: succeed
Parameters
• country: the configured country info
esp_err_t esp_wifi_get_country(wifi_country_t *country)
get the current country info
Return
• ESP_OK: succeed
Parameters
• country: country info
esp_err_t esp_wifi_set_mac(wifi_interface_t ifx, const uint8_t mac[6])
Set MAC address of the ESP32 WiFi station or the soft-AP interface.
Attention 1. This API can only be called when the interface is disabled
Attention 2. ESP32 soft-AP and station have different MAC addresses, do not set them to be the same.
Attention 3. The bit 0 of the first byte of ESP32 MAC address can not be 1. For example, the MAC address
can set to be 1a:XX:XX:XX:XX:XX , but can not be 15:XX:XX:XX:XX:XX .
Return
• ESP_OK: succeed
• ESP_ERR_WIFI_MAC: invalid mac address
Parameters
• ifx: interface
• mac: the MAC address
esp_err_t esp_wifi_get_mac(wifi_interface_t ifx, uint8_t mac[6])
Get mac of specified interface.
Return
• ESP_OK: succeed


Parameters
• ifx: interface
• [out] mac: store mac of the interface ifx
esp_err_t esp_wifi_set_promiscuous_rx_cb(wifi_promiscuous_cb_t cb)
Register the RX callback function in the promiscuous mode.
Each time a packet is received, the registered callback function will be called.
Return
• ESP_OK: succeed
Parameters
• cb: callback
esp_err_t esp_wifi_set_promiscuous(bool en)
Enable the promiscuous mode.
Return
• ESP_OK: succeed
Parameters
• en: false - disable, true - enable
esp_err_t esp_wifi_get_promiscuous(bool *en)
Get the promiscuous mode.
Return
• ESP_OK: succeed
Parameters
• [out] en: store the current status of promiscuous mode
esp_err_t esp_wifi_set_promiscuous_filter(const wifi_promiscuous_filter_t *filter)
Enable the promiscuous mode packet type filter.
Note The default filter is to filter all packets except WIFI_PKT_MISC
Return
• ESP_OK: succeed
Parameters
• filter: the packet type filtered in promiscuous mode.
esp_err_t esp_wifi_get_promiscuous_filter(wifi_promiscuous_filter_t *filter)
Get the promiscuous filter.
Return
• ESP_OK: succeed
Parameters
• [out] filter: store the current status of promiscuous filter
esp_err_t esp_wifi_set_promiscuous_ctrl_filter(const wifi_promiscuous_filter_t *filter)
Enable subtype filter of the control packet in promiscuous mode.
Note The default filter is to filter none control packet.
Return
• ESP_OK: succeed
Parameters
• filter: the subtype of the control packet filtered in promiscuous mode.

esp_err_t esp_wifi_get_promiscuous_ctrl_filter(wifi_promiscuous_filter_t *filter)

Get the subtype filter of the control packet in promiscuous mode.
Return
• ESP_OK: succeed
• ESP_ERR_WIFI_ARG: invalid argument
Parameters
• [out] filter: store the current status of subtype filter of the control packet in promiscuous
mode
esp_err_t esp_wifi_set_config(wifi_interface_t interface, wifi_config_t *conf)
Set the configuration of the ESP32 STA or AP.
Attention 1. This API can be called only when specified interface is enabled, otherwise, API fail
Attention 2. For station configuration, bssid_set needs to be 0; and it needs to be 1 only when users need to
check the MAC address of the AP.
Attention 3. ESP32 is limited to only one channel, so when in the soft-AP+station mode, the soft-AP will
adjust its channel automatically to be the same as the channel of the ESP32 station.
Return
• ESP_OK: succeed
• ESP_ERR_WIFI_MODE: invalid mode
• ESP_ERR_WIFI_PASSWORD: invalid password
• ESP_ERR_WIFI_NVS: WiFi internal NVS error
• others: refer to the erro code in esp_err.h
Parameters
• interface: interface
• conf: station or soft-AP configuration
esp_err_t esp_wifi_get_config(wifi_interface_t interface, wifi_config_t *conf)
Get configuration of specified interface.
Return
• ESP_OK: succeed
Parameters
• interface: interface
• [out] conf: station or soft-AP configuration
esp_err_t esp_wifi_ap_get_sta_list(wifi_sta_list_t *sta)
Get STAs associated with soft-AP.
Attention SSC only API
Return
• ESP_OK: succeed
• ESP_ERR_WIFI_CONN: WiFi internal error, the station/soft-AP control block is invalid
Parameters
• [out] sta: station list ap can get the connected sta s phy mode info through the struct member
phy_11b phy_11g phy_11n phy_lr in the wifi_sta_info_t struct. For example, phy_11b = 1 imply
that sta support 802.11b mode
esp_err_t esp_wifi_ap_get_sta_aid(const uint8_t mac[6], uint16_t *aid)
Get AID of STA connected with soft-AP.
Return

• ESP_OK: succeed
• ESP_ERR_NOT_FOUND: Requested resource not found
• ESP_ERR_WIFI_CONN: WiFi internal error, the station/soft-AP control block is invalid
Parameters
• mac: STA s mac address
• [out] aid: Store the AID corresponding to STA mac
esp_err_t esp_wifi_set_storage(wifi_storage_t storage)
Set the WiFi API configuration storage type.
Attention 1. The default value is WIFI_STORAGE_FLASH
Return
• ESP_OK: succeed
Parameters
• storage: : storage type
esp_err_t esp_wifi_set_vendor_ie(bool enable, wifi_vendor_ie_type_t type, wifi_vendor_ie_id_t
idx, const void *vnd_ie)
Set 802.11 Vendor-Specific Information Element.
Return
• ESP_OK: succeed
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init()
• ESP_ERR_INVALID_ARG: Invalid argument, including if first byte of vnd_ie is not
WIFI_VENDOR_IE_ELEMENT_ID (0xDD) or second byte is an invalid length.
• ESP_ERR_NO_MEM: Out of memory
Parameters
• enable: If true, specified IE is enabled. If false, specified IE is removed.
• type: Information Element type. Determines the frame type to associate with the IE.
• idx: Index to set or clear. Each IE type can be associated with up to two elements (indices 0 & 1).
• vnd_ie: Pointer to vendor specific element data. First 6 bytes should be a header with fields
matching vendor_ie_data_t. If enable is false, this argument is ignored and can be NULL. Data
does not need to remain valid after the function returns.
esp_err_t esp_wifi_set_vendor_ie_cb(esp_vendor_ie_cb_t cb, void *ctx)
Register Vendor-Specific Information Element monitoring callback.
Return
• ESP_OK: succeed
Parameters
• cb: Callback function
• ctx: Context argument, passed to callback function.
esp_err_t esp_wifi_set_max_tx_power(int8_t power)
Set maximum transmitting power after WiFi start.
Attention 1. Maximum power before wifi startup is limited by PHY init data bin.
Attention 2. The value set by this API will be mapped to the max_tx_power of the structure wifi_country_t
variable.
Attention 3. Mapping Table {Power, max_tx_power} = {{8, 2}, {20, 5}, {28, 7}, {34, 8}, {44, 11}, {52,
13}, {56, 14}, {60, 15}, {66, 16}, {72, 18}, {80, 20}}.
Attention 4. Param power unit is 0.25dBm, range is [8, 84] corresponding to 2dBm - 20dBm.
Attention 5. Relationship between set value and actual value. As follows: {set value range, actual value} =
{{[8, 19],8}, {[20, 27],20}, {[28, 33],28}, {[34, 43],34}, {[44, 51],44}, {[52, 55],52}, {[56, 59],56},
{[60, 65],60}, {[66, 71],66}, {[72, 79],72}, {[80, 84],80}}.
Return

• ESP_OK: succeed
• ESP_ERR_WIFI_NOT_START: WiFi is not started by esp_wifi_start
• ESP_ERR_WIFI_ARG: invalid argument, e.g. parameter is out of range
Parameters
• power: Maximum WiFi transmitting power.
esp_err_t esp_wifi_get_max_tx_power(int8_t *power)
Get maximum transmiting power after WiFi start.
Return
• ESP_OK: succeed
• ESP_ERR_WIFI_NOT_START: WiFi is not started by esp_wifi_start
Parameters
• power: Maximum WiFi transmitting power, unit is 0.25dBm.
esp_err_t esp_wifi_set_event_mask(uint32_t mask)
Set mask to enable or disable some WiFi events.
Attention 1. Mask can be created by logical OR of various WIFI_EVENT_MASK_ constants. Events which
have corresponding bit set in the mask will not be delivered to the system event handler.
Attention 2. Default WiFi event mask is WIFI_EVENT_MASK_AP_PROBEREQRECVED.
Attention 3. There may be lots of stations sending probe request data around. Don t unmask this event
unless you need to receive probe request data.
Return
• ESP_OK: succeed
Parameters
• mask: WiFi event mask.
esp_err_t esp_wifi_get_event_mask(uint32_t *mask)
Get mask of WiFi events.
Return
• ESP_OK: succeed
Parameters
• mask: WiFi event mask.
esp_err_t esp_wifi_80211_tx(wifi_interface_t ifx, const void *buffer, int len, bool en_sys_seq)
Send raw ieee80211 data.
Attention Currently only support for sending beacon/probe request/probe response/action and non-QoS data
frame
Return
• ESP_OK: success
• ESP_ERR_WIFI_IF: Invalid interface
• ESP_ERR_INVALID_ARG: Invalid parameter
• ESP_ERR_WIFI_NO_MEM: out of memory
Parameters
• ifx: interface if the Wi-Fi mode is Station, the ifx should be WIFI_IF_STA. If the Wi-Fi mode
is SoftAP, the ifx should be WIFI_IF_AP. If the Wi-Fi mode is Station+SoftAP, the ifx should be
WIFI_IF_STA or WIFI_IF_AP. If the ifx is wrong, the API returns ESP_ERR_WIFI_IF.
• buffer: raw ieee80211 buffer
• len: the length of raw buffer, the len must be <= 1500 Bytes and >= 24 Bytes
• en_sys_seq: indicate whether use the internal sequence number. If en_sys_seq is false, the
sequence in raw buffer is unchanged, otherwise it will be overwritten by WiFi driver with the system
sequence number. Generally, if esp_wifi_80211_tx is called before the Wi-Fi connection has been
set up, both en_sys_seq==true and en_sys_seq==false are fine. However, if the API is called after

the Wi-Fi connection has been set up, en_sys_seq must be true, otherwise ESP_ERR_WIFI_ARG
is returned.
esp_err_t esp_wifi_set_csi_rx_cb(wifi_csi_cb_t cb, void *ctx)
Register the RX callback function of CSI data.
Each time a CSI data is received, the callback function will be called.
Return
• ESP_OK: succeed
Parameters
• cb: callback
• ctx: context argument, passed to callback function
esp_err_t esp_wifi_set_csi_config(const wifi_csi_config_t *config)
Set CSI data configuration.
return
• ESP_OK: succeed
• ESP_ERR_WIFI_NOT_START: WiFi is not started by esp_wifi_start or promiscuous mode is not en-
abled
Parameters
• config: configuration
esp_err_t esp_wifi_set_csi(bool en)
Enable or disable CSI.
return
• ESP_OK: succeed
• ESP_ERR_WIFI_NOT_START: WiFi is not started by esp_wifi_start or promiscuous mode is not en-
abled
Parameters
• en: true - enable, false - disable
esp_err_t esp_wifi_set_ant_gpio(const wifi_ant_gpio_config_t *config)
Set antenna GPIO configuration.
Return
• ESP_OK: succeed
• ESP_ERR_WIFI_ARG: Invalid argument, e.g. parameter is NULL, invalid GPIO number etc
Parameters
• config: Antenna GPIO configuration.
esp_err_t esp_wifi_get_ant_gpio(wifi_ant_gpio_config_t *config)
Get current antenna GPIO configuration.
Return
• ESP_OK: succeed
• ESP_ERR_WIFI_ARG: invalid argument, e.g. parameter is NULL
Parameters
• config: Antenna GPIO configuration.
esp_err_t esp_wifi_set_ant(const wifi_ant_config_t *config)
Set antenna configuration.
Return

• ESP_OK: succeed
• ESP_ERR_WIFI_ARG: Invalid argument, e.g. parameter is NULL, invalid antenna mode or invalid
GPIO number
Parameters
• config: Antenna configuration.
esp_err_t esp_wifi_get_ant(wifi_ant_config_t *config)
Get current antenna configuration.
Return
• ESP_OK: succeed
• ESP_ERR_WIFI_ARG: invalid argument, e.g. parameter is NULL
Parameters
• config: Antenna configuration.
int64_t esp_wifi_get_tsf_time(wifi_interface_t interface)
Get the TSF time In Station mode or SoftAP+Station mode if station is not connected or station doesn t
receive at least one beacon after connected, will return 0.
Attention Enabling power save may cause the return value inaccurate, except WiFi modem sleep
Return 0 or the TSF time
Parameters
• interface: The interface whose tsf_time is to be retrieved.
esp_err_t esp_wifi_set_inactive_time(wifi_interface_t ifx, uint16_t sec)
Set the inactive time of the ESP32 STA or AP.
Attention 1. For Station, If the station does not receive a beacon frame from the connected SoftAP during
the inactive time, disconnect from SoftAP. Default 6s.
Attention 2. For SoftAP, If the softAP doesn t receive any data from the connected STA during inactive
time, the softAP will force deauth the STA. Default is 300s.
Attention 3. The inactive time configuration is not stored into flash
Return
• ESP_OK: succeed
• ESP_ERR_WIFI_ARG: invalid argument, For Station, if sec is less than 3. For SoftAP, if sec is
less than 10.
Parameters
• ifx: interface to be configured.
• sec: Inactive time. Unit seconds.
esp_err_t esp_wifi_get_inactive_time(wifi_interface_t ifx, uint16_t *sec)
Get inactive time of specified interface.
Return
• ESP_OK: succeed
Parameters
• ifx: Interface to be configured.
• sec: Inactive time. Unit seconds.
esp_err_t esp_wifi_statis_dump(uint32_t modules)
Dump WiFi statistics.
Return
• ESP_OK: succeed
• others: failed
Parameters
• modules: statistic modules to be dumped

esp_err_t esp_wifi_set_rssi_threshold(int32_t rssi)

Set RSSI threshold below which APP will get an event.
Attention This API needs to be called every time after WIFI_EVENT_STA_BSS_RSSI_LOW event is re-
ceived.
Return
• ESP_OK: succeed
Parameters
• rssi: threshold value in dbm between -100 to 0
esp_err_t esp_wifi_ftm_initiate_session(wifi_ftm_initiator_cfg_t *cfg)
Start an FTM Initiator session by sending FTM request If successful, event WIFI_EVENT_FTM_REPORT
is generated with the result of the FTM procedure.
Attention Use this API only in Station mode
Return
• ESP_OK: succeed
• others: failed
Parameters
• cfg: FTM Initiator session configuration
esp_err_t esp_wifi_ftm_end_session(void)
End the ongoing FTM Initiator session.
Attention This API works only on FTM Initiator
Return
• ESP_OK: succeed
• others: failed
esp_err_t esp_wifi_ftm_resp_set_offset(int16_t offset_cm)
Set offset in cm for FTM Responder. An equivalent offset is calculated in picoseconds and added in TOD of
FTM Measurement frame (T1).
Attention Use this API only in AP mode before performing FTM as responder
Return
• ESP_OK: succeed
• others: failed
Parameters
• offset_cm: T1 Offset to be added in centimeters
esp_err_t esp_wifi_config_11b_rate(wifi_interface_t ifx, bool disable)
Enable or disable 11b rate of specified interface.
Attention 1. This API should be called after esp_wifi_init() and before esp_wifi_start().
Attention 2. Only when really need to disable 11b rate call this API otherwise don t call this.
Return
• ESP_OK: succeed
• others: failed
Parameters
• disable: true means disable 11b rate while false means enable 11b rate.
esp_err_t esp_wifi_config_espnow_rate(wifi_interface_t ifx, wifi_phy_rate_t rate)
Config ESPNOW rate of specified interface.
Return
• ESP_OK: succeed
• others: failed
Parameters
• rate: Phy rate to be configured.

esp_err_t esp_wifi_set_connectionless_wake_interval(uint16_t interval)

Set interval for station to wake up periodically at disconnected.
Attention 1. Only when ESP_WIFI_STA_DISCONNECTED_PM_ENABLE is enabled, this configuration
could work
Attention 2. This configuration only work for station mode and disconnected status
Attention 3. This configuration would influence nothing until some module configure wake_window
Attention 4. A sensible interval which is not too small is recommended (e.g. 100ms)
Parameters
• interval: how much micriosecond would the chip wake up, from 1 to 65535.
esp_err_t esp_wifi_set_country_code(const char *country, bool ieee80211d_enabled)
configure country
Attention 1. When ieee80211d_enabled, the country info of the AP to which the station is connected is used.
E.g. if the configured country is US and the country info of the AP to which the station is connected is
JP then the country info that will be used is JP. If the station disconnected from the AP the country info
is set back to the country info of the station automatically, US in the example.
Attention 2. When ieee80211d_enabled is disabled, then the configured country info is used always.
Attention 3. When the country info is changed because of configuration or because the station connects to a
different external AP, the country IE in probe response/beacon of the soft-AP is also changed.
Attention 4. The country configuration is stored into flash.
Attention 5. When this API is called, the PHY init data will switch to the PHY init data type corresponding
to the country info.
Attention 6. Supported country codes are 01 (world safe mode) AT , AU , BE , BG , BR
, CA , CH , CN , CY , CZ , DE , DK , EE , ES , FI , FR , GB
, GR , HK , HR , HU , IE , IN , IS , IT , JP , KR , LI , LT ,
LU , LV , MT , MX , NL , NO , NZ , PL , PT , RO , SE , SI ,
SK , TW , US
Attention 7. When country code 01 (world safe mode) is set, SoftAP mode won t contain country IE.
Attention 8. The default country is CN and ieee80211d_enabled is TRUE.
Return
• ESP_OK: succeed
Parameters
• country: the configured country ISO code
• ieee80211d_enabled: 802.11d is enabled or not
esp_err_t esp_wifi_get_country_code(char *country)
get the current country code
Return
• ESP_OK: succeed
Parameters
• country: country code
esp_err_t esp_wifi_config_80211_tx_rate(wifi_interface_t ifx, wifi_phy_rate_t rate)
Config 80211 tx rate of specified interface.
Return
• ESP_OK: succeed
• others: failed
Parameters
• rate: Phy rate to be configured.
Structures

struct wifi_init_config_t
WiFi stack configuration parameters passed to esp_wifi_init call.
Public Members
system_event_handler_t event_handler
WiFi event handler
wifi_osi_funcs_t *osi_funcs
WiFi OS functions
wpa_crypto_funcs_t wpa_crypto_funcs
WiFi station crypto functions when connect
int static_rx_buf_num
WiFi static RX buffer number
int dynamic_rx_buf_num
WiFi dynamic RX buffer number
int tx_buf_type
WiFi TX buffer type
int static_tx_buf_num
WiFi static TX buffer number
int dynamic_tx_buf_num
WiFi dynamic TX buffer number
int cache_tx_buf_num
WiFi TX cache buffer number
int csi_enable
WiFi channel state information enable flag
int ampdu_rx_enable
WiFi AMPDU RX feature enable flag
int ampdu_tx_enable
WiFi AMPDU TX feature enable flag
int amsdu_tx_enable
WiFi AMSDU TX feature enable flag
int nvs_enable
WiFi NVS flash enable flag
int nano_enable
Nano option for printf/scan family enable flag
int rx_ba_win
WiFi Block Ack RX window size
int wifi_task_core_id
WiFi Task Core ID
int beacon_max_len
WiFi softAP maximum length of the beacon
int mgmt_sbuf_num
WiFi management short buffer number, the minimum value is 6, the maximum value is 32
uint64_t feature_caps
Enables additional WiFi features and capabilities
bool sta_disconnected_pm
WiFi Power Management for station at disconnected status

int magic
WiFi init magic number, it should be the last field
Macros
ESP_ERR_WIFI_NOT_INIT
WiFi driver was not installed by esp_wifi_init
ESP_ERR_WIFI_NOT_STARTED
WiFi driver was not started by esp_wifi_start
ESP_ERR_WIFI_NOT_STOPPED
WiFi driver was not stopped by esp_wifi_stop
ESP_ERR_WIFI_IF
WiFi interface error
ESP_ERR_WIFI_MODE
WiFi mode error
ESP_ERR_WIFI_STATE
WiFi internal state error
ESP_ERR_WIFI_CONN
WiFi internal control block of station or soft-AP error
ESP_ERR_WIFI_NVS
WiFi internal NVS module error
ESP_ERR_WIFI_MAC
MAC address is invalid
ESP_ERR_WIFI_SSID
SSID is invalid
ESP_ERR_WIFI_PASSWORD
Password is invalid
ESP_ERR_WIFI_TIMEOUT
Timeout error
ESP_ERR_WIFI_WAKE_FAIL
WiFi is in sleep state(RF closed) and wakeup fail
ESP_ERR_WIFI_WOULD_BLOCK
The caller would block
ESP_ERR_WIFI_NOT_CONNECT
Station still in disconnect status
ESP_ERR_WIFI_POST
Failed to post the event to WiFi task
ESP_ERR_WIFI_INIT_STATE
Invalid WiFi state when init/deinit is called
ESP_ERR_WIFI_STOP_STATE
Returned when WiFi is stopping
ESP_ERR_WIFI_NOT_ASSOC
The WiFi connection is not associated
ESP_ERR_WIFI_TX_DISALLOW
The WiFi TX is disallowed
WIFI_STATIC_TX_BUFFER_NUM
WIFI_CACHE_TX_BUFFER_NUM
WIFI_DYNAMIC_TX_BUFFER_NUM

WIFI_CSI_ENABLED
WIFI_AMPDU_RX_ENABLED
WIFI_AMPDU_TX_ENABLED
WIFI_AMSDU_TX_ENABLED
WIFI_NVS_ENABLED
WIFI_NANO_FORMAT_ENABLED
WIFI_INIT_CONFIG_MAGIC
WIFI_DEFAULT_RX_BA_WIN
WIFI_TASK_CORE_ID
WIFI_SOFTAP_BEACON_MAX_LEN
WIFI_MGMT_SBUF_NUM
WIFI_STA_DISCONNECTED_PM_ENABLED
CONFIG_FEATURE_WPA3_SAE_BIT
CONFIG_FEATURE_CACHE_TX_BUF_BIT
CONFIG_FEATURE_FTM_INITIATOR_BIT
CONFIG_FEATURE_FTM_RESPONDER_BIT
WIFI_INIT_CONFIG_DEFAULT()
Type Definitions
typedef void (*wifi_promiscuous_cb_t)(void *buf, wifi_promiscuous_pkt_type_t type)
The RX callback function in the promiscuous mode. Each time a packet is received, the callback function will
be called.
Parameters
• buf: Data received. Type of data in buffer (wifi_promiscuous_pkt_t or wifi_pkt_rx_ctrl_t) indicated
by type parameter.
• type: promiscuous packet type.
typedef void (*esp_vendor_ie_cb_t)(void *ctx, wifi_vendor_ie_type_t type, const uint8_t sa[6],
const vendor_ie_data_t *vnd_ie, int rssi)
Function signature for received Vendor-Specific Information Element callback.
Parameters
• ctx: Context argument, as passed to esp_wifi_set_vendor_ie_cb() when registering callback.
• type: Information element type, based on frame type received.
• sa: Source 802.11 address.
• vnd_ie: Pointer to the vendor specific element data received.
• rssi: Received signal strength indication.
typedef void (*wifi_csi_cb_t)(void *ctx, wifi_csi_info_t *data)
The RX callback function of Channel State Information(CSI) data.
Each time a CSI data is received, the callback function will be called.
Parameters
• ctx: context argument, passed to esp_wifi_set_csi_rx_cb() when registering callback function.
• data: CSI data received. The memory that it points to will be deallocated after callback function
returns.
Header File
• components/esp_wifi/include/esp_wifi_types.h

Unions
union wifi_config_t
#include <esp_wifi_types.h> Configuration data for ESP32 AP or STA.
The usage of this union (for ap or sta configuration) is determined by the accompanying interface argument
passed to esp_wifi_set_config() or esp_wifi_get_config()
Public Members
wifi_ap_config_t ap
configuration of AP
wifi_sta_config_t sta
configuration of STA
Structures
struct wifi_country_t
Structure describing WiFi country-based regional restrictions.
Public Members
char cc[3]
country code string
uint8_t schan
start channel
uint8_t nchan
total channel number
int8_t max_tx_power
This field is used for getting WiFi maximum transmitting power, call esp_wifi_set_max_tx_power to set
the maximum transmitting power.
wifi_country_policy_t policy
country policy
struct wifi_active_scan_time_t
Range of active scan times per channel.
Public Members
uint32_t min
minimum active scan time per channel, units: millisecond
uint32_t max
maximum active scan time per channel, units: millisecond, values above 1500ms may cause station to
disconnect from AP and are not recommended.
struct wifi_scan_time_t
Aggregate of active & passive scan time per channel.
Public Members
wifi_active_scan_time_t active
active scan time per channel, units: millisecond.
uint32_t passive
passive scan time per channel, units: millisecond, values above 1500ms may cause station to disconnect
from AP and are not recommended.

struct wifi_scan_config_t
Parameters for an SSID scan.
Public Members
uint8_t *ssid
SSID of AP
uint8_t *bssid
MAC address of AP
uint8_t channel
channel, scan the specific channel
bool show_hidden
enable to scan AP whose SSID is hidden
wifi_scan_type_t scan_type
scan type, active or passive
wifi_scan_time_t scan_time
scan time per channel
struct wifi_ap_record_t
Description of a WiFi AP.
Public Members
uint8_t bssid[6]
MAC address of AP
uint8_t ssid[33]
SSID of AP
uint8_t primary
channel of AP
wifi_second_chan_t second
secondary channel of AP
int8_t rssi
signal strength of AP
wifi_auth_mode_t authmode
authmode of AP
wifi_cipher_type_t pairwise_cipher
pairwise cipher of AP
wifi_cipher_type_t group_cipher
group cipher of AP
wifi_ant_t ant
antenna used to receive beacon from AP
uint32_t phy_11b : 1
bit: 0 flag to identify if 11b mode is enabled or not
uint32_t phy_11g : 1
bit: 1 flag to identify if 11g mode is enabled or not
uint32_t phy_11n : 1
bit: 2 flag to identify if 11n mode is enabled or not
uint32_t phy_lr : 1
bit: 3 flag to identify if low rate is enabled or not

uint32_t wps : 1
bit: 4 flag to identify if WPS is supported or not
uint32_t ftm_responder : 1
bit: 5 flag to identify if FTM is supported in responder mode
uint32_t ftm_initiator : 1
bit: 6 flag to identify if FTM is supported in initiator mode
uint32_t reserved : 25
bit: 7..31 reserved
wifi_country_t country
country information of AP
struct wifi_scan_threshold_t
Structure describing parameters for a WiFi fast scan.
Public Members
int8_t rssi
The minimum rssi to accept in the fast scan mode
The weakest authmode to accept in the fast scan mode
struct wifi_pmf_config_t
Configuration structure for Protected Management Frame
Public Members
bool capable
Advertizes support for Protected Management Frame. Device will prefer to connect in PMF mode if
other device also advertizes PMF capability.
bool required
Advertizes that Protected Management Frame is required. Device will not associate to non-PMF capable
devices.
struct wifi_ap_config_t
Soft-AP configuration settings for the ESP32.
Public Members
uint8_t ssid[32]
SSID of ESP32 soft-AP. If ssid_len field is 0, this must be a Null terminated string. Otherwise, length
is set according to ssid_len.
uint8_t password[64]
Password of ESP32 soft-AP.
uint8_t ssid_len
Optional length of SSID field.
uint8_t channel
Channel of ESP32 soft-AP
Auth mode of ESP32 soft-AP. Do not support AUTH_WEP in soft-AP mode
uint8_t ssid_hidden
Broadcast SSID or not, default 0, broadcast the SSID

uint8_t max_connection
Max number of stations allowed to connect in, default 4, max 10
uint16_t beacon_interval
Beacon interval which should be multiples of 100. Unit: TU(time unit, 1 TU = 1024 us). Range: 100 ~
60000. Default value: 100
wifi_cipher_type_t pairwise_cipher
pairwise cipher of SoftAP, group cipher will be derived using this. cipher values are
valid starting from WIFI_CIPHER_TYPE_TKIP, enum values before that will be consid-
ered as invalid and default cipher suites(TKIP+CCMP) will be used. Valid cipher suites
in softAP mode are WIFI_CIPHER_TYPE_TKIP, WIFI_CIPHER_TYPE_CCMP and
WIFI_CIPHER_TYPE_TKIP_CCMP.
bool ftm_responder
Enable FTM Responder mode
struct wifi_sta_config_t
STA configuration settings for the ESP32.
Public Members
uint8_t ssid[32]
SSID of target AP.
Password of target AP.
wifi_scan_method_t scan_method
do all channel scan or fast scan
bool bssid_set
whether set MAC address of target AP or not. Generally, station_config.bssid_set needs to be 0; and it
needs to be 1 only when users need to check the MAC address of the AP.
uint8_t bssid[6]
MAC address of target AP
uint8_t channel
channel of target AP. Set to 1~13 to scan starting from the specified channel before connecting to AP. If
the channel of AP is unknown, set it to 0.
uint16_t listen_interval
Listen interval for ESP32 station to receive beacon when WIFI_PS_MAX_MODEM is set. Units: AP
beacon intervals. Defaults to 3 if set to 0.
wifi_sort_method_t sort_method
sort the connect AP in the list by rssi or security mode
wifi_scan_threshold_t threshold
When sort_method is set, only APs which have an auth mode that is more secure than the selected auth
mode and a signal stronger than the minimum RSSI will be used.
wifi_pmf_config_t pmf_cfg
Configuration for Protected Management Frame. Will be advertized in RSN Capabilities in RSN IE.
uint32_t rm_enabled : 1
Whether Radio Measurements are enabled for the connection
uint32_t btm_enabled : 1
Whether BSS Transition Management is enabled for the connection
uint32_t mbo_enabled : 1
Whether MBO is enabled for the connection

Reserved for future feature set
struct wifi_sta_info_t
Description of STA associated with AP.
Public Members
uint8_t mac[6]
mac address
int8_t rssi
current average rssi of sta connected
uint32_t phy_11b : 1
bit: 0 flag to identify if 11b mode is enabled or not
uint32_t phy_11g : 1
bit: 1 flag to identify if 11g mode is enabled or not
uint32_t phy_11n : 1
bit: 2 flag to identify if 11n mode is enabled or not
uint32_t phy_lr : 1
bit: 3 flag to identify if low rate is enabled or not
uint32_t is_mesh_child : 1
bit: 4 flag to identify mesh child
bit: 5..31 reserved
struct wifi_sta_list_t
List of stations associated with the ESP32 Soft-AP.
Public Members
wifi_sta_info_t sta[ESP_WIFI_MAX_CONN_NUM]
station list
int num
number of stations in the list (other entries are invalid)
struct vendor_ie_data_t
Vendor Information Element header.
The first bytes of the Information Element will match this header. Payload follows.
Public Members
uint8_t element_id
Should be set to WIFI_VENDOR_IE_ELEMENT_ID (0xDD)
uint8_t length
Length of all bytes in the element data following this field. Minimum 4.
uint8_t vendor_oui[3]
Vendor identifier (OUI).
uint8_t vendor_oui_type
Vendor-specific OUI type.
uint8_t payload[0]
Payload. Length is equal to value in length field, minus 4.

struct wifi_pkt_rx_ctrl_t
Received packet radio metadata header, this is the common header at the beginning of all promiscuous mode
RX callback buffers.
Public Members
signed rssi : 8
Received Signal Strength Indicator(RSSI) of packet. unit: dBm
unsigned rate : 5
PHY rate encoding of the packet. Only valid for non HT(11bg) packet
unsigned __pad0__ : 1
reserved
unsigned sig_mode : 2
0: non HT(11bg) packet; 1: HT(11n) packet; 3: VHT(11ac) packet
reserved
unsigned mcs : 7
Modulation Coding Scheme. If is HT(11n) packet, shows the modulation, range from 0 to 76(MSC0 ~
MCS76)
unsigned cwb : 1
Channel Bandwidth of the packet. 0: 20MHz; 1: 40MHz
reserved
unsigned smoothing : 1
reserved
unsigned not_sounding : 1
reserved
reserved
unsigned aggregation : 1
Aggregation. 0: MPDU packet; 1: AMPDU packet
unsigned stbc : 2
Space Time Block Code(STBC). 0: non STBC packet; 1: STBC packet
unsigned fec_coding : 1
Flag is set for 11n packets which are LDPC
unsigned sgi : 1
Short Guide Interval(SGI). 0: Long GI; 1: Short GI
signed noise_floor : 8
noise floor of Radio Frequency Module(RF). unit: 0.25dBm
unsigned ampdu_cnt : 8
ampdu cnt
unsigned channel : 4
primary channel on which this packet is received
unsigned secondary_channel : 4
secondary channel on which this packet is received. 0: none; 1: above; 2: below
reserved

unsigned timestamp : 32
timestamp. The local time when this packet is received. It is precise only if modem sleep or light sleep
is not enabled. unit: microsecond
reserved
reserved
unsigned ant : 1
antenna number from which this packet is received. 0: WiFi antenna 0; 1: WiFi antenna 1
unsigned sig_len : 12
length of packet including Frame Check Sequence(FCS)
reserved
unsigned rx_state : 8
state of the packet. 0: no error; others: error numbers which are not public
struct wifi_promiscuous_pkt_t
Payload passed to buf parameter of promiscuous mode RX callback.
Public Members
wifi_pkt_rx_ctrl_t rx_ctrl
metadata header
uint8_t payload[0]
Data or management payload. Length of payload is described by rx_ctrl.sig_len. Type of content deter-
mined by packet type argument of callback.
struct wifi_promiscuous_filter_t
Mask for filtering different packet types in promiscuous mode.
Public Members
uint32_t filter_mask
OR of one or more filter values WIFI_PROMIS_FILTER_*
struct wifi_csi_config_t
Channel state information(CSI) configuration type.
Public Members
bool lltf_en
enable to receive legacy long training field(lltf) data. Default enabled
bool htltf_en
enable to receive HT long training field(htltf) data. Default enabled
bool stbc_htltf2_en
enable to receive space time block code HT long training field(stbc-htltf2) data. Default enabled
bool ltf_merge_en
enable to generate htlft data by averaging lltf and ht_ltf data when receiving HT packet. Otherwise, use
ht_ltf data directly. Default enabled
bool channel_filter_en
enable to turn on channel filter to smooth adjacent sub-carrier. Disable it to keep independence of adjacent
sub-carrier. Default enabled

bool manu_scale
manually scale the CSI data by left shifting or automatically scale the CSI data. If set true, please set the
shift bits. false: automatically. true: manually. Default false
uint8_t shift
manually left shift bits of the scale of the CSI data. The range of the left shift bits is 0~15
struct wifi_csi_info_t
CSI data type.
Public Members
wifi_pkt_rx_ctrl_t rx_ctrl
received packet radio metadata header of the CSI data
uint8_t mac[6]
source MAC address of the CSI data
bool first_word_invalid
first four bytes of the CSI data is invalid or not
int8_t *buf
buffer of CSI data
uint16_t len
length of CSI data
struct wifi_ant_gpio_t
WiFi GPIO configuration for antenna selection.
Public Members
uint8_t gpio_select : 1
Whether this GPIO is connected to external antenna switch
uint8_t gpio_num : 7
The GPIO number that connects to external antenna switch
struct wifi_ant_gpio_config_t
WiFi GPIOs configuration for antenna selection.
Public Members
wifi_ant_gpio_t gpio_cfg[4]
The configurations of GPIOs that connect to external antenna switch
struct wifi_ant_config_t
WiFi antenna configuration.
Public Members
wifi_ant_mode_t rx_ant_mode
WiFi antenna mode for receiving
wifi_ant_t rx_ant_default
Default antenna mode for receiving, it s ignored if rx_ant_mode is not WIFI_ANT_MODE_AUTO
wifi_ant_mode_t tx_ant_mode
WiFi antenna mode for transmission, it can be set to WIFI_ANT_MODE_AUTO only if rx_ant_mode
is set to WIFI_ANT_MODE_AUTO

uint8_t enabled_ant0 : 4
Index (in antenna GPIO configuration) of enabled WIFI_ANT_MODE_ANT0
uint8_t enabled_ant1 : 4
Index (in antenna GPIO configuration) of enabled WIFI_ANT_MODE_ANT1
struct wifi_action_tx_req_t
Action Frame Tx Request.
Public Members
wifi_interface_t ifx
WiFi interface to send request to
uint8_t dest_mac[6]
Destination MAC address
bool no_ack
Indicates no ack required
wifi_action_rx_cb_t rx_cb
Rx Callback to receive any response
uint32_t data_len
Length of the appended Data
uint8_t data[0]
Appended Data payload
struct wifi_ftm_initiator_cfg_t
FTM Initiator configuration.
Public Members
uint8_t resp_mac[6]
MAC address of the FTM Responder
uint8_t channel
Primary channel of the FTM Responder
uint8_t frm_count
No. of FTM frames requested in terms of 4 or 8 bursts (allowed values - 0(No pref), 16, 24, 32, 64)
uint16_t burst_period
Requested time period between consecutive FTM bursts in 100 s of milliseconds (0 - No pref)
struct wifi_event_sta_scan_done_t
Argument structure for WIFI_EVENT_SCAN_DONE event
Public Members
uint32_t status
status of scanning APs: 0 success, 1 - failure
uint8_t number
number of scan results
uint8_t scan_id
scan sequence number, used for block scan
struct wifi_event_sta_connected_t
Argument structure for WIFI_EVENT_STA_CONNECTED event

Public Members
uint8_t ssid[32]
SSID of connected AP
uint8_t ssid_len
SSID length of connected AP
uint8_t bssid[6]
BSSID of connected AP
uint8_t channel
channel of connected AP
authentication mode used by AP
struct wifi_event_sta_disconnected_t
Argument structure for WIFI_EVENT_STA_DISCONNECTED event
Public Members
uint8_t ssid[32]
SSID of disconnected AP
uint8_t ssid_len
SSID length of disconnected AP
uint8_t bssid[6]
BSSID of disconnected AP
uint8_t reason
reason of disconnection
struct wifi_event_sta_authmode_change_t
Argument structure for WIFI_EVENT_STA_AUTHMODE_CHANGE event
Public Members
wifi_auth_mode_t old_mode
the old auth mode of AP
wifi_auth_mode_t new_mode
the new auth mode of AP
struct wifi_event_sta_wps_er_pin_t
Argument structure for WIFI_EVENT_STA_WPS_ER_PIN event
Public Members
uint8_t pin_code[8]
PIN code of station in enrollee mode
struct wifi_event_sta_wps_er_success_t
Argument structure for WIFI_EVENT_STA_WPS_ER_SUCCESS event
Public Members
uint8_t ap_cred_cnt
Number of AP credentials received

uint8_t ssid[MAX_SSID_LEN]
SSID of AP
uint8_t passphrase[MAX_PASSPHRASE_LEN]
Passphrase for the AP
struct wifi_event_sta_wps_er_success_t::[anonymous] ap_cred[MAX_WPS_AP_CRED]
All AP credentials received from WPS handshake
struct wifi_event_ap_staconnected_t
Argument structure for WIFI_EVENT_AP_STACONNECTED event
Public Members
uint8_t mac[6]
MAC address of the station connected to ESP32 soft-AP
uint8_t aid
the aid that ESP32 soft-AP gives to the station connected to
bool is_mesh_child
flag to identify mesh child
struct wifi_event_ap_stadisconnected_t
Argument structure for WIFI_EVENT_AP_STADISCONNECTED event
Public Members
uint8_t mac[6]
MAC address of the station disconnects to ESP32 soft-AP
uint8_t aid
the aid that ESP32 soft-AP gave to the station disconnects to
bool is_mesh_child
flag to identify mesh child
struct wifi_event_ap_probe_req_rx_t
Argument structure for WIFI_EVENT_AP_PROBEREQRECVED event
Public Members
int rssi
Received probe request signal strength
uint8_t mac[6]
MAC address of the station which send probe request
struct wifi_event_bss_rssi_low_t
Argument structure for WIFI_EVENT_STA_BSS_RSSI_LOW event
Public Members
int32_t rssi
RSSI value of bss
struct wifi_ftm_report_entry_t
Argument structure for

Public Members
uint8_t dlog_token
Dialog Token of the FTM frame
int8_t rssi
RSSI of the FTM frame received
uint32_t rtt
Round Trip Time in pSec with a peer
uint64_t t1
Time of departure of FTM frame from FTM Responder in pSec
uint64_t t2
Time of arrival of FTM frame at FTM Initiator in pSec
uint64_t t3
Time of departure of ACK from FTM Initiator in pSec
uint64_t t4
Time of arrival of ACK at FTM Responder in pSec
struct wifi_event_ftm_report_t
Argument structure for WIFI_EVENT_FTM_REPORT event
Public Members
uint8_t peer_mac[6]
MAC address of the FTM Peer
wifi_ftm_status_t status
Status of the FTM operation
uint32_t rtt_raw
Raw average Round-Trip-Time with peer in Nano-Seconds
uint32_t rtt_est
Estimated Round-Trip-Time with peer in Nano-Seconds
uint32_t dist_est
Estimated one-way distance in Centi-Meters
wifi_ftm_report_entry_t *ftm_report_data
Pointer to FTM Report with multiple entries, should be freed after use
uint8_t ftm_report_num_entries
Number of entries in the FTM Report data
struct wifi_event_action_tx_status_t
Argument structure for WIFI_EVENT_ACTION_TX_STATUS event
Public Members
wifi_interface_t ifx
WiFi interface to send request to
uint32_t context
Context to identify the request
uint8_t da[6]
Destination MAC address
uint8_t status
Status of the operation

struct wifi_event_roc_done_t
Argument structure for WIFI_EVENT_ROC_DONE event
Public Members
uint32_t context
Context to identify the request
Macros
WIFI_OFFCHAN_TX_REQ
WIFI_OFFCHAN_TX_CANCEL
WIFI_ROC_REQ
WIFI_ROC_CANCEL
WIFI_PROTOCOL_11B
WIFI_PROTOCOL_11G
WIFI_PROTOCOL_11N
WIFI_PROTOCOL_LR
ESP_WIFI_MAX_CONN_NUM
max number of stations which can connect to ESP32 soft-AP
WIFI_VENDOR_IE_ELEMENT_ID
WIFI_PROMIS_FILTER_MASK_ALL
filter all packets
WIFI_PROMIS_FILTER_MASK_MGMT
filter the packets with type of WIFI_PKT_MGMT
WIFI_PROMIS_FILTER_MASK_CTRL
filter the packets with type of WIFI_PKT_CTRL
WIFI_PROMIS_FILTER_MASK_DATA
filter the packets with type of WIFI_PKT_DATA
WIFI_PROMIS_FILTER_MASK_MISC
filter the packets with type of WIFI_PKT_MISC
WIFI_PROMIS_FILTER_MASK_DATA_MPDU
filter the MPDU which is a kind of WIFI_PKT_DATA
WIFI_PROMIS_FILTER_MASK_DATA_AMPDU
filter the AMPDU which is a kind of WIFI_PKT_DATA
WIFI_PROMIS_FILTER_MASK_FCSFAIL
filter the FCS failed packets, do not open it in general
WIFI_PROMIS_CTRL_FILTER_MASK_ALL
filter all control packets
WIFI_PROMIS_CTRL_FILTER_MASK_WRAPPER
filter the control packets with subtype of Control Wrapper
WIFI_PROMIS_CTRL_FILTER_MASK_BAR
filter the control packets with subtype of Block Ack Request
WIFI_PROMIS_CTRL_FILTER_MASK_BA
filter the control packets with subtype of Block Ack
WIFI_PROMIS_CTRL_FILTER_MASK_PSPOLL
filter the control packets with subtype of PS-Poll

WIFI_PROMIS_CTRL_FILTER_MASK_RTS
filter the control packets with subtype of RTS
WIFI_PROMIS_CTRL_FILTER_MASK_CTS
filter the control packets with subtype of CTS
WIFI_PROMIS_CTRL_FILTER_MASK_ACK
filter the control packets with subtype of ACK
WIFI_PROMIS_CTRL_FILTER_MASK_CFEND
filter the control packets with subtype of CF-END
WIFI_PROMIS_CTRL_FILTER_MASK_CFENDACK
filter the control packets with subtype of CF-END+CF-ACK
WIFI_EVENT_MASK_ALL
mask all WiFi events
WIFI_EVENT_MASK_NONE
mask none of the WiFi events
WIFI_EVENT_MASK_AP_PROBEREQRECVED
mask SYSTEM_EVENT_AP_PROBEREQRECVED event
MAX_SSID_LEN
MAX_PASSPHRASE_LEN
MAX_WPS_AP_CRED
WIFI_STATIS_BUFFER
WIFI_STATIS_RXTX
WIFI_STATIS_HW
WIFI_STATIS_DIAG
WIFI_STATIS_PS
WIFI_STATIS_ALL
Type Definitions
typedef int (*wifi_action_rx_cb_t)(uint8_t *hdr, uint8_t *payload, size_t len, uint8_t channel)
The Rx callback function of Action Tx operations.
Parameters
• hdr: pointer to the IEEE 802.11 Header structure
• payload: pointer to the Payload following 802.11 Header
• len: length of the Payload
• channel: channel number the frame is received on
Enumerations
enum wifi_mode_t
Values:
WIFI_MODE_NULL = 0
null mode
WIFI_MODE_STA
WiFi station mode
WIFI_MODE_AP
WiFi soft-AP mode
WIFI_MODE_APSTA
WiFi station + soft-AP mode

WIFI_MODE_MAX
enum wifi_interface_t
Values:
WIFI_IF_STA = ESP_IF_WIFI_STA
WIFI_IF_AP = ESP_IF_WIFI_AP
enum wifi_country_policy_t
Values:
WIFI_COUNTRY_POLICY_AUTO
Country policy is auto, use the country info of AP to which the station is connected
WIFI_COUNTRY_POLICY_MANUAL
Country policy is manual, always use the configured country info
enum wifi_auth_mode_t
Values:
WIFI_AUTH_OPEN = 0
authenticate mode : open
WIFI_AUTH_WEP
authenticate mode : WEP
WIFI_AUTH_WPA_PSK
authenticate mode : WPA_PSK
WIFI_AUTH_WPA2_PSK
authenticate mode : WPA2_PSK
WIFI_AUTH_WPA_WPA2_PSK
authenticate mode : WPA_WPA2_PSK
WIFI_AUTH_WPA2_ENTERPRISE
authenticate mode : WPA2_ENTERPRISE
WIFI_AUTH_WPA3_PSK
authenticate mode : WPA3_PSK
WIFI_AUTH_WPA2_WPA3_PSK
authenticate mode : WPA2_WPA3_PSK
WIFI_AUTH_WAPI_PSK
authenticate mode : WAPI_PSK
WIFI_AUTH_MAX
enum wifi_err_reason_t
Values:
WIFI_REASON_UNSPECIFIED = 1
WIFI_REASON_AUTH_EXPIRE = 2
WIFI_REASON_AUTH_LEAVE = 3
WIFI_REASON_ASSOC_EXPIRE = 4
WIFI_REASON_ASSOC_TOOMANY = 5
WIFI_REASON_NOT_AUTHED = 6
WIFI_REASON_NOT_ASSOCED = 7
WIFI_REASON_ASSOC_LEAVE = 8
WIFI_REASON_ASSOC_NOT_AUTHED = 9
WIFI_REASON_DISASSOC_PWRCAP_BAD = 10

WIFI_REASON_DISASSOC_SUPCHAN_BAD = 11
WIFI_REASON_BSS_TRANSITION_DISASSOC = 12
WIFI_REASON_IE_INVALID = 13
WIFI_REASON_MIC_FAILURE = 14
WIFI_REASON_4WAY_HANDSHAKE_TIMEOUT = 15
WIFI_REASON_GROUP_KEY_UPDATE_TIMEOUT = 16
WIFI_REASON_IE_IN_4WAY_DIFFERS = 17
WIFI_REASON_GROUP_CIPHER_INVALID = 18
WIFI_REASON_PAIRWISE_CIPHER_INVALID = 19
WIFI_REASON_AKMP_INVALID = 20
WIFI_REASON_UNSUPP_RSN_IE_VERSION = 21
WIFI_REASON_INVALID_RSN_IE_CAP = 22
WIFI_REASON_802_1X_AUTH_FAILED = 23
WIFI_REASON_CIPHER_SUITE_REJECTED = 24
WIFI_REASON_INVALID_PMKID = 53
WIFI_REASON_BEACON_TIMEOUT = 200
WIFI_REASON_NO_AP_FOUND = 201
WIFI_REASON_AUTH_FAIL = 202
WIFI_REASON_ASSOC_FAIL = 203
WIFI_REASON_HANDSHAKE_TIMEOUT = 204
WIFI_REASON_CONNECTION_FAIL = 205
WIFI_REASON_AP_TSF_RESET = 206
WIFI_REASON_ROAMING = 207
enum wifi_second_chan_t
Values:
WIFI_SECOND_CHAN_NONE = 0
the channel width is HT20
WIFI_SECOND_CHAN_ABOVE
the channel width is HT40 and the secondary channel is above the primary channel
WIFI_SECOND_CHAN_BELOW
the channel width is HT40 and the secondary channel is below the primary channel
enum wifi_scan_type_t
Values:
WIFI_SCAN_TYPE_ACTIVE = 0
active scan
WIFI_SCAN_TYPE_PASSIVE
passive scan
enum wifi_cipher_type_t
Values:
WIFI_CIPHER_TYPE_NONE = 0
the cipher type is none

WIFI_CIPHER_TYPE_WEP40
the cipher type is WEP40
WIFI_CIPHER_TYPE_WEP104
the cipher type is WEP104
WIFI_CIPHER_TYPE_TKIP
the cipher type is TKIP
WIFI_CIPHER_TYPE_CCMP
the cipher type is CCMP
WIFI_CIPHER_TYPE_TKIP_CCMP
the cipher type is TKIP and CCMP
WIFI_CIPHER_TYPE_AES_CMAC128
the cipher type is AES-CMAC-128
WIFI_CIPHER_TYPE_SMS4
the cipher type is SMS4
WIFI_CIPHER_TYPE_GCMP
the cipher type is GCMP
WIFI_CIPHER_TYPE_GCMP256
the cipher type is GCMP-256
WIFI_CIPHER_TYPE_AES_GMAC128
the cipher type is AES-GMAC-128
WIFI_CIPHER_TYPE_AES_GMAC256
the cipher type is AES-GMAC-256
WIFI_CIPHER_TYPE_UNKNOWN
the cipher type is unknown
enum wifi_ant_t
WiFi antenna.
Values:
WIFI_ANT_ANT0
WiFi antenna 0
WIFI_ANT_ANT1
WiFi antenna 1
WIFI_ANT_MAX
Invalid WiFi antenna
enum wifi_scan_method_t
Values:
WIFI_FAST_SCAN = 0
Do fast scan, scan will end after find SSID match AP
WIFI_ALL_CHANNEL_SCAN
All channel scan, scan will end after scan all the channel
enum wifi_sort_method_t
Values:
WIFI_CONNECT_AP_BY_SIGNAL = 0
Sort match AP in scan list by RSSI
WIFI_CONNECT_AP_BY_SECURITY
Sort match AP in scan list by security mode
enum wifi_ps_type_t
Values:

WIFI_PS_NONE
No power save
WIFI_PS_MIN_MODEM
Minimum modem power saving. In this mode, station wakes up to receive beacon every DTIM period
WIFI_PS_MAX_MODEM
Maximum modem power saving. In this mode, interval to receive beacons is determined by the lis-
ten_interval parameter in wifi_sta_config_t
enum wifi_bandwidth_t
Values:
WIFI_BW_HT20 = 1
WIFI_BW_HT40
enum wifi_storage_t
Values:
WIFI_STORAGE_FLASH
all configuration will store in both memory and flash
WIFI_STORAGE_RAM
all configuration will only store in the memory
enum wifi_vendor_ie_type_t
Vendor Information Element type.
Determines the frame type that the IE will be associated with.
Values:
WIFI_VND_IE_TYPE_BEACON
WIFI_VND_IE_TYPE_PROBE_REQ
WIFI_VND_IE_TYPE_PROBE_RESP
WIFI_VND_IE_TYPE_ASSOC_REQ
WIFI_VND_IE_TYPE_ASSOC_RESP
enum wifi_vendor_ie_id_t
Vendor Information Element index.
Each IE type can have up to two associated vendor ID elements.
Values:
WIFI_VND_IE_ID_0
WIFI_VND_IE_ID_1
enum wifi_promiscuous_pkt_type_t
Promiscuous frame type.
Passed to promiscuous mode RX callback to indicate the type of parameter in the buffer.
Values:
WIFI_PKT_MGMT
Management frame, indicates buf argument is wifi_promiscuous_pkt_t
WIFI_PKT_CTRL
Control frame, indicates buf argument is wifi_promiscuous_pkt_t
WIFI_PKT_DATA
Data frame, indiciates buf argument is wifi_promiscuous_pkt_t
WIFI_PKT_MISC
Other type, such as MIMO etc. buf argument is wifi_promiscuous_pkt_t but the payload is zero length.

enum wifi_ant_mode_t
WiFi antenna mode.
Values:
WIFI_ANT_MODE_ANT0
Enable WiFi antenna 0 only
WIFI_ANT_MODE_ANT1
Enable WiFi antenna 1 only
WIFI_ANT_MODE_AUTO
Enable WiFi antenna 0 and 1, automatically select an antenna
WIFI_ANT_MODE_MAX
Invalid WiFi enabled antenna
enum wifi_phy_rate_t
WiFi PHY rate encodings.
Values:
WIFI_PHY_RATE_1M_L = 0x00
1 Mbps with long preamble
5.5 Mbps with long preamble
WIFI_PHY_RATE_2M_S = 0x05
2 Mbps with short preamble
5.5 Mbps with short preamble
11 Mbps with short preamble
WIFI_PHY_RATE_48M = 0x08
48 Mbps
WIFI_PHY_RATE_24M = 0x09
24 Mbps
WIFI_PHY_RATE_12M = 0x0A
12 Mbps
WIFI_PHY_RATE_6M = 0x0B
6 Mbps
WIFI_PHY_RATE_54M = 0x0C
54 Mbps
WIFI_PHY_RATE_36M = 0x0D
36 Mbps
WIFI_PHY_RATE_18M = 0x0E
18 Mbps
WIFI_PHY_RATE_9M = 0x0F
9 Mbps
WIFI_PHY_RATE_MCS0_LGI = 0x10
MCS0 with long GI, 6.5 Mbps for 20MHz, 13.5 Mbps for 40MHz

MCS1 with long GI, 13 Mbps for 20MHz, 27 Mbps for 40MHz
WIFI_PHY_RATE_MCS0_SGI = 0x18
MCS0 with short GI, 7.2 Mbps for 20MHz, 15 Mbps for 40MHz
WIFI_PHY_RATE_MCS1_SGI = 0x19
WIFI_PHY_RATE_MCS2_SGI = 0x1A
WIFI_PHY_RATE_MCS3_SGI = 0x1B
WIFI_PHY_RATE_MCS4_SGI = 0x1C
WIFI_PHY_RATE_MCS5_SGI = 0x1D
WIFI_PHY_RATE_MCS6_SGI = 0x1E
MCS6 with short GI, 65 Mbps for 20MHz, 135 Mbps for 40MHz
WIFI_PHY_RATE_MCS7_SGI = 0x1F
WIFI_PHY_RATE_LORA_250K = 0x29
250 Kbps
WIFI_PHY_RATE_LORA_500K = 0x2A
500 Kbps
WIFI_PHY_RATE_MAX
enum wifi_event_t
WiFi event declarations
Values:
WIFI_EVENT_WIFI_READY = 0
ESP32 WiFi ready
WIFI_EVENT_SCAN_DONE
ESP32 finish scanning AP
WIFI_EVENT_STA_START
ESP32 station start
WIFI_EVENT_STA_STOP
ESP32 station stop

WIFI_EVENT_STA_CONNECTED
ESP32 station connected to AP
WIFI_EVENT_STA_DISCONNECTED
ESP32 station disconnected from AP
WIFI_EVENT_STA_AUTHMODE_CHANGE
the auth mode of AP connected by ESP32 station changed
WIFI_EVENT_STA_WPS_ER_SUCCESS
ESP32 station wps succeeds in enrollee mode
WIFI_EVENT_STA_WPS_ER_FAILED
ESP32 station wps fails in enrollee mode
WIFI_EVENT_STA_WPS_ER_TIMEOUT
ESP32 station wps timeout in enrollee mode
WIFI_EVENT_STA_WPS_ER_PIN
ESP32 station wps pin code in enrollee mode
WIFI_EVENT_STA_WPS_ER_PBC_OVERLAP
ESP32 station wps overlap in enrollee mode
WIFI_EVENT_AP_START
ESP32 soft-AP start
WIFI_EVENT_AP_STOP
ESP32 soft-AP stop
WIFI_EVENT_AP_STACONNECTED
a station connected to ESP32 soft-AP
WIFI_EVENT_AP_STADISCONNECTED
a station disconnected from ESP32 soft-AP
WIFI_EVENT_AP_PROBEREQRECVED
Receive probe request packet in soft-AP interface
WIFI_EVENT_FTM_REPORT
Receive report of FTM procedure
WIFI_EVENT_STA_BSS_RSSI_LOW
AP s RSSI crossed configured threshold
WIFI_EVENT_ACTION_TX_STATUS
Status indication of Action Tx operation
WIFI_EVENT_ROC_DONE
Remain-on-Channel operation complete
WIFI_EVENT_STA_BEACON_TIMEOUT
ESP32 station beacon timeout
WIFI_EVENT_MAX
Invalid WiFi event ID
enum wifi_event_sta_wps_fail_reason_t
Argument structure for WIFI_EVENT_STA_WPS_ER_FAILED event
Values:
WPS_FAIL_REASON_NORMAL = 0
ESP32 WPS normal fail reason
WPS_FAIL_REASON_RECV_M2D
ESP32 WPS receive M2D frame
WPS_FAIL_REASON_MAX

enum wifi_ftm_status_t
FTM operation status types.
Values:
FTM_STATUS_SUCCESS = 0
FTM exchange is successful
FTM_STATUS_UNSUPPORTED
Peer does not support FTM
FTM_STATUS_CONF_REJECTED
Peer rejected FTM configuration in FTM Request
FTM_STATUS_NO_RESPONSE
Peer did not respond to FTM Requests
FTM_STATUS_FAIL
Unknown error during FTM exchange
SmartConfig
The SmartConfigTM is a provisioning technology developed by TI to connect a new Wi-Fi device to a Wi-Fi network.
It uses a mobile app to broadcast the network credentials from a smartphone, or a tablet, to an un-provisioned Wi-Fi
device.
The advantage of this technology is that the device does not need to directly know SSID or password of an Access
Point (AP). This information is provided using the smartphone. This is particularly important to headless device and
systems, due to their lack of a user interface.
If you are looking for other options to provision your ESP32 devices, check Provisioning API.
Application Example Connect ESP32 to target AP using SmartConfig: wifi/smart_config.
API Reference
Header File
• components/esp_wifi/include/esp_smartconfig.h
Functions
const char *esp_smartconfig_get_version(void)
Get the version of SmartConfig.
Return
• SmartConfig version const char.
esp_err_t esp_smartconfig_start(const smartconfig_start_config_t *config)
Start SmartConfig, config ESP device to connect AP. You need to broadcast information by phone APP. Device
sniffer special packets from the air that containing SSID and password of target AP.
Attention 1. This API can be called in station or softAP-station mode.
Attention 2. Can not call esp_smartconfig_start twice before it finish, please call esp_smartconfig_stop first.
Return
• ESP_OK: succeed
• others: fail
Parameters
• config: pointer to smartconfig start configure structure
esp_err_t esp_smartconfig_stop(void)
Stop SmartConfig, free the buffer taken by esp_smartconfig_start.

Attention Whether connect to AP succeed or not, this API should be called to free memory taken by smart-
config_start.
Return
• ESP_OK: succeed
• others: fail
esp_err_t esp_esptouch_set_timeout(uint8_t time_s)
Set timeout of SmartConfig process.
Attention Timing starts from SC_STATUS_FIND_CHANNEL status. SmartConfig will restart if timeout.
Return
• ESP_OK: succeed
• others: fail
Parameters
• time_s: range 15s~255s, offset:45s.
esp_err_t esp_smartconfig_set_type(smartconfig_type_t type)
Set protocol type of SmartConfig.
Attention If users need to set the SmartConfig type, please set it before calling esp_smartconfig_start.
Return
• ESP_OK: succeed
• others: fail
Parameters
• type: Choose from the smartconfig_type_t.
esp_err_t esp_smartconfig_fast_mode(bool enable)
Set mode of SmartConfig. default normal mode.
Attention 1. Please call it before API esp_smartconfig_start.
Attention 2. Fast mode have corresponding APP(phone).
Attention 3. Two mode is compatible.
Return
• ESP_OK: succeed
• others: fail
Parameters
• enable: false-disable(default); true-enable;
esp_err_t esp_smartconfig_get_rvd_data(uint8_t *rvd_data, uint8_t len)
Get reserved data of ESPTouch v2.
Return
• ESP_OK: succeed
• others: fail
Parameters
• rvd_data: reserved data
• len: length of reserved data
Structures
struct smartconfig_event_got_ssid_pswd_t
Argument structure for SC_EVENT_GOT_SSID_PSWD event
Public Members
uint8_t ssid[32]
SSID of the AP. Null terminated string.
Password of the AP. Null terminated string.
bool bssid_set
whether set MAC address of target AP or not.

uint8_t bssid[6]
MAC address of target AP.
smartconfig_type_t type
Type of smartconfig(ESPTouch or AirKiss).
uint8_t token
Token from cellphone which is used to send ACK to cellphone.
uint8_t cellphone_ip[4]
IP address of cellphone.
struct smartconfig_start_config_t
Configure structure for esp_smartconfig_start
Public Members
bool enable_log
Enable smartconfig logs.
bool esp_touch_v2_enable_crypt
Enable ESPTouch v2 crypt.
char *esp_touch_v2_key
ESPTouch v2 crypt key, len should be 16.
Macros
SMARTCONFIG_START_CONFIG_DEFAULT()
Enumerations
enum smartconfig_type_t
Values:
SC_TYPE_ESPTOUCH = 0
protocol: ESPTouch
SC_TYPE_AIRKISS
protocol: AirKiss
SC_TYPE_ESPTOUCH_AIRKISS
protocol: ESPTouch and AirKiss
SC_TYPE_ESPTOUCH_V2
protocol: ESPTouch v2
enum smartconfig_event_t
Smartconfig event declarations
Values:
SC_EVENT_SCAN_DONE
ESP32 station smartconfig has finished to scan for APs
SC_EVENT_FOUND_CHANNEL
ESP32 station smartconfig has found the channel of the target AP
SC_EVENT_GOT_SSID_PSWD
ESP32 station smartconfig got the SSID and password
SC_EVENT_SEND_ACK_DONE
ESP32 station smartconfig has sent ACK to cellphone

ESP-NOW
Overview ESP-NOW is a kind of connectionless Wi-Fi communication protocol that is defined by Espressif. In
ESP-NOW, application data is encapsulated in a vendor-specific action frame and then transmitted from one Wi-Fi
device to another without connection. CTR with CBC-MAC Protocol(CCMP) is used to protect the action frame for
security. ESP-NOW is widely used in smart light, remote controlling, sensor, etc.
Frame Format ESP-NOW uses a vendor-specific action frame to transmit ESP-NOW data. The default ESP-
NOW bit rate is 1 Mbps. The format of the vendor-specific action frame is as follows:
-----------------------------------------------------------------------------------
,→-------------------------
| MAC Header | Category Code | Organization Identifier | Random Values | Vendor␣

,→Specific Content | FCS |
-----------------------------------------------------------------------------------
,→-------------------------
24 bytes 1 byte 3 bytes 4 bytes 7~

,→255 bytes 4 bytes
• Category Code: The Category Code field is set to the value(127) indicating the vendor-specific category.
• Organization Identifier: The Organization Identifier contains a unique identifier (0x18fe34), which is the first
three bytes of MAC address applied by Espressif.
• Random Value: The Random Value filed is used to prevents relay attacks.
• Vendor Specific Content: The Vendor Specific Content contains vendor-specific fields as follows:
-------------------------------------------------------------------------------
| Element ID | Length | Organization Identifier | Type | Version | Body |
-------------------------------------------------------------------------------
1 byte 1 byte 3 bytes 1 byte 1 byte 0~250 bytes
• Element ID: The Element ID field is set to the value (221), indicating the vendor-specific element.
• Length: The length is the total length of Organization Identifier, Type, Version and Body.
• Organization Identifier: The Organization Identifier contains a unique identifier(0x18fe34), which is the first
three bytes of MAC address applied by Espressif.
• Type: The Type field is set to the value (4) indicating ESP-NOW.
• Version: The Version field is set to the version of ESP-NOW.
• Body: The Body contains the ESP-NOW data.
As ESP-NOW is connectionless, the MAC header is a little different from that of standard frames. The FromDS and
ToDS bits of FrameControl field are both 0. The first address field is set to the destination address. The second address
field is set to the source address. The third address field is set to broadcast address (0xff:0xff:0xff:0xff:0xff:0xff).
Security
ESP-NOW uses the CCMP method, which is described in IEEE Std. 802.11-2012, to protect the vendor-specific action frame
• PMK is used to encrypt LMK with the AES-128 algorithm. Call esp_now_set_pmk() to set PMK.
If PMK is not set, a default PMK will be used.
• LMK of the paired device is used to encrypt the vendor-specific action frame with the CCMP method.
The maximum number of different LMKs is six. If the LMK of the paired device is not set, the vendor-
specific action frame will not be encrypted.
Encrypting multicast vendor-specific action frame is not supported.
Initialization and De-initialization Call esp_now_init() to initialize ESP-NOW and

esp_now_deinit() to de-initialize ESP-NOW. ESP-NOW data must be transmitted after Wi-Fi is started,
so it is recommended to start Wi-Fi before initializing ESP-NOW and stop Wi-Fi after de-initializing ESP-NOW.
When esp_now_deinit() is called, all of the information of paired devices will be deleted.

Add Paired Device Call esp_now_add_peer() to add the device to the paired device list before you send
data to this device. The maximum number of paired devices is twenty. If security is enabled, the LMK must be set.
You can send ESP-NOW data via both the Station and the SoftAP interface. Make sure that the interface is enabled
before sending ESP-NOW data. A device with a broadcast MAC address must be added before sending broadcast
data. The range of the channel of paired devices is from 0 to 14. If the channel is set to 0, data will be sent on the
current channel. Otherwise, the channel must be set as the channel that the local device is on.
Send ESP-NOW Data Call esp_now_send() to send ESP-NOW data and

esp_now_register_send_cb to register sending callback function. It will return ESP_NOW_SEND_SUCCESS
in sending callback function if the data is received successfully on the MAC layer. Otherwise, it will return
ESP_NOW_SEND_FAIL. Several reasons can lead to ESP-NOW fails to send data. For example, the destination
device doesn t exist; the channels of the devices are not the same; the action frame is lost when transmitting on
the air, etc. It is not guaranteed that application layer can receive the data. If necessary, send back ack data when
receiving ESP-NOW data. If receiving ack data timeouts, retransmit the ESP-NOW data. A sequence number can
also be assigned to ESP-NOW data to drop the duplicate data.
If there is a lot of ESP-NOW data to send, call esp_now_send() to send less than or equal to 250 bytes of
data once a time. Note that too short interval between sending two ESP-NOW data may lead to disorder of sending
callback function. So, it is recommended that sending the next ESP-NOW data after the sending callback function
of the previous sending has returned. The sending callback function runs from a high-priority Wi-Fi task. So, do not
do lengthy operations in the callback function. Instead, post the necessary data to a queue and handle it from a lower
priority task.
Receiving ESP-NOW Data Call esp_now_register_recv_cb to register receiving callback function. Call
the receiving callback function when receiving ESP-NOW. The receiving callback function also runs from the Wi-Fi
task. So, do not do lengthy operations in the callback function. Instead, post the necessary data to a queue and handle
it from a lower priority task.
API Reference
Header File
• components/esp_wifi/include/esp_now.h
Functions
esp_err_t esp_now_init(void)
Initialize ESPNOW function.
Return
• ESP_OK : succeed
• ESP_ERR_ESPNOW_INTERNAL : Internal error
esp_err_t esp_now_deinit(void)
De-initialize ESPNOW function.
Return
esp_err_t esp_now_get_version(uint32_t *version)
Get the version of ESPNOW.
Return
• ESP_ERR_ESPNOW_ARG : invalid argument
Parameters
• version: ESPNOW version
esp_err_t esp_now_register_recv_cb(esp_now_recv_cb_t cb)
Register callback function of receiving ESPNOW data.

Return
• ESP_ERR_ESPNOW_NOT_INIT : ESPNOW is not initialized
• ESP_ERR_ESPNOW_INTERNAL : internal error
Parameters
• cb: callback function of receiving ESPNOW data
esp_err_t esp_now_unregister_recv_cb(void)
Unregister callback function of receiving ESPNOW data.
Return
esp_err_t esp_now_register_send_cb(esp_now_send_cb_t cb)
Register callback function of sending ESPNOW data.
Return
Parameters
• cb: callback function of sending ESPNOW data
esp_err_t esp_now_unregister_send_cb(void)
Unregister callback function of sending ESPNOW data.
Return
esp_err_t esp_now_send(const uint8_t *peer_addr, const uint8_t *data, size_t len)
Send ESPNOW data.
Attention 1. If peer_addr is not NULL, send data to the peer whose MAC address matches peer_addr
Attention 2. If peer_addr is NULL, send data to all of the peers that are added to the peer list
Attention 3. The maximum length of data must be less than ESP_NOW_MAX_DATA_LEN
Attention 4. The buffer pointed to by data argument does not need to be valid after esp_now_send returns
Return
• ESP_ERR_ESPNOW_NO_MEM : out of memory
• ESP_ERR_ESPNOW_NOT_FOUND : peer is not found
• ESP_ERR_ESPNOW_IF : current WiFi interface doesn t match that of peer
Parameters
• peer_addr: peer MAC address
• data: data to send
• len: length of data
esp_err_t esp_now_add_peer(const esp_now_peer_info_t *peer)
Add a peer to peer list.
Return
• ESP_ERR_ESPNOW_FULL : peer list is full
• ESP_ERR_ESPNOW_NO_MEM : out of memory
• ESP_ERR_ESPNOW_EXIST : peer has existed
Parameters
• peer: peer information

esp_err_t esp_now_del_peer(const uint8_t *peer_addr)

Delete a peer from peer list.
Return
Parameters
esp_err_t esp_now_mod_peer(const esp_now_peer_info_t *peer)
Modify a peer.
Return
• ESP_ERR_ESPNOW_FULL : peer list is full
Parameters
esp_err_t esp_now_get_peer(const uint8_t *peer_addr, esp_now_peer_info_t *peer)
Get a peer whose MAC address matches peer_addr from peer list.
Return
Parameters
esp_err_t esp_now_fetch_peer(bool from_head, esp_now_peer_info_t *peer)
Fetch a peer from peer list. Only return the peer which address is unicast, for the multicast/broadcast address,
the function will ignore and try to find the next in the peer list.
Return
Parameters
• from_head: fetch from head of list or not
bool esp_now_is_peer_exist(const uint8_t *peer_addr)
Peer exists or not.
Return
• true : peer exists
• false : peer not exists
Parameters
esp_err_t esp_now_get_peer_num(esp_now_peer_num_t *num)
Get the number of peers.
Return
Parameters

• num: number of peers

esp_err_t esp_now_set_pmk(const uint8_t *pmk)
Set the primary master key.
Attention 1. primary master key is used to encrypt local master key
Return
Parameters
• pmk: primary master key
esp_err_t esp_now_set_wake_window(uint16_t window)
Set esp_now wake window for sta_disconnected power management.
Attention 1. Only when ESP_WIFI_STA_DISCONNECTED_PM_ENABLE is enabled, this configuration
could work
Attention 2. This configuration only work for station mode and disconnected status
Attention 3. If more than one module has configured its wake_window, chip would choose the largest one to
stay waked
Attention 4. If the gap between interval and window is smaller than 5ms, the chip would keep waked all the
time
Attention 5. If never configured wake_window, the chip would keep waked at disconnected once it uses
esp_now
Return
Parameters
• window: how much microsecond would the chip keep waked each interval, vary from 0 to 65535
Structures
struct esp_now_peer_info
ESPNOW peer information parameters.
Public Members
uint8_t peer_addr[ESP_NOW_ETH_ALEN]
ESPNOW peer MAC address that is also the MAC address of station or softap
uint8_t lmk[ESP_NOW_KEY_LEN]
ESPNOW peer local master key that is used to encrypt data
uint8_t channel
Wi-Fi channel that peer uses to send/receive ESPNOW data. If the value is 0, use the current channel
which station or softap is on. Otherwise, it must be set as the channel that station or softap is on.
wifi_interface_t ifidx
Wi-Fi interface that peer uses to send/receive ESPNOW data
bool encrypt
ESPNOW data that this peer sends/receives is encrypted or not
void *priv
ESPNOW peer private data
struct esp_now_peer_num
Number of ESPNOW peers which exist currently.

Public Members
int total_num
Total number of ESPNOW peers, maximum value is ESP_NOW_MAX_TOTAL_PEER_NUM
int encrypt_num
Number of encrypted ESPNOW peers, maximum value is ESP_NOW_MAX_ENCRYPT_PEER_NUM
Macros
ESP_ERR_ESPNOW_BASE
ESPNOW error number base.
ESP_ERR_ESPNOW_NOT_INIT
ESPNOW is not initialized.
ESP_ERR_ESPNOW_ARG
Invalid argument
ESP_ERR_ESPNOW_NO_MEM
Out of memory
ESP_ERR_ESPNOW_FULL
ESPNOW peer list is full
ESP_ERR_ESPNOW_NOT_FOUND
ESPNOW peer is not found
ESP_ERR_ESPNOW_INTERNAL
Internal error
ESP_ERR_ESPNOW_EXIST
ESPNOW peer has existed
ESP_ERR_ESPNOW_IF
Interface error
ESP_NOW_ETH_ALEN
Length of ESPNOW peer MAC address
ESP_NOW_KEY_LEN
Length of ESPNOW peer local master key
ESP_NOW_MAX_TOTAL_PEER_NUM
Maximum number of ESPNOW total peers
ESP_NOW_MAX_ENCRYPT_PEER_NUM
Maximum number of ESPNOW encrypted peers
ESP_NOW_MAX_DATA_LEN
Maximum length of ESPNOW data which is sent very time
Type Definitions
typedef struct esp_now_peer_info esp_now_peer_info_t
ESPNOW peer information parameters.
typedef struct esp_now_peer_num esp_now_peer_num_t
Number of ESPNOW peers which exist currently.
typedef void (*esp_now_recv_cb_t)(const uint8_t *mac_addr, const uint8_t *data, int
data_len)
Callback function of receiving ESPNOW data.
Parameters
• mac_addr: peer MAC address
• data: received data
• data_len: length of received data

typedef void (*esp_now_send_cb_t)(const uint8_t *mac_addr, esp_now_send_status_t status)

Callback function of sending ESPNOW data.
Parameters
• mac_addr: peer MAC address
• status: status of sending ESPNOW data (succeed or fail)
Enumerations
enum esp_now_send_status_t
Status of sending ESPNOW data .
Values:
ESP_NOW_SEND_SUCCESS = 0
Send ESPNOW data successfully
ESP_NOW_SEND_FAIL
Send ESPNOW data fail
ESP-WIFI-MESH Programming Guide
This is a programming guide for ESP-WIFI-MESH, including the API reference and coding examples. This guide is
split into the following parts:
1. ESP-WIFI-MESH Programming Model
2. Writing an ESP-WIFI-MESH Application
3. Self Organized Networking
4. Application Examples
5. API Reference
For documentation regarding the ESP-WIFI-MESH protocol, please see the ESP-WIFI-MESH API Guide. For more
information about ESP-WIFI-MESH Development Framework, please see ESP-WIFI-MESH Development Frame-
work.
ESP-WIFI-MESH Programming Model
Software Stack The ESP-WIFI-MESH software stack is built atop the Wi-Fi Driver/FreeRTOS and may use the
LwIP Stack in some instances (i.e. the root node). The following diagram illustrates the ESP-WIFI-MESH software
stack.
Fig. 2: ESP-WIFI-MESH Software Stack

System Events An application interfaces with ESP-WIFI-MESH via ESP-WIFI-MESH Events. Since ESP-
WIFI-MESH is built atop the Wi-Fi stack, it is also possible for the application to interface with the Wi-Fi driver
via the Wi-Fi Event Task. The following diagram illustrates the interfaces for the various System Events in an
ESP-WIFI-MESH application.
Fig. 3: ESP-WIFI-MESH System Events Delivery
The mesh_event_id_t defines all possible ESP-WIFI-MESH events and can indicate events such as the con-
nection/disconnection of parent/child. Before ESP-WIFI-MESH events can be used, the application must register
a Mesh Events handler via esp_event_handler_register() to the default event task. The Mesh Events
handler that is registered contain handlers for each ESP-WIFI-MESH event relevant to the application.
Typical use cases of mesh events include using events such as MESH_EVENT_PARENT_CONNECTED and
MESH_EVENT_CHILD_CONNECTED to indicate when a node can begin transmitting data upstream and down-
stream respectively. Likewise, IP_EVENT_STA_GOT_IP and IP_EVENT_STA_LOST_IP can be used to indi-
cate when the root node can and cannot transmit data to the external IP network.
Warning: When using ESP-WIFI-MESH under self-organized mode, users must ensure that no calls to Wi-
Fi API are made. This is due to the fact that the self-organizing mode will internally make Wi-Fi API calls
to connect/disconnect/scan etc. Any Wi-Fi calls from the application (including calls from callbacks and
handlers of Wi-Fi events) may interfere with ESP-WIFI-MESH s self-organizing behavior. Therefore,
user s should not call Wi-Fi APIs after esp_mesh_start() is called, and before esp_mesh_stop() is
called.
LwIP & ESP-WIFI-MESH The application can access the ESP-WIFI-MESH stack directly without having to
go through the LwIP stack. The LwIP stack is only required by the root node to transmit/receive data to/from an
external IP network. However, since every node can potentially become the root node (due to automatic root node
selection), each node must still initialize the LwIP stack.
Each node is required to initialize LwIP by calling tcpip_adapter_init(). In order to prevent non-root
node access to LwIP, the application should stop the following services after LwIP initialization:
• DHCP server service on the softAP interface.
• DHCP client service on the station interface.
The following code snippet demonstrates how to initialize LwIP for ESP-WIFI-MESH applications.
/* tcpip initialization */
tcpip_adapter_init();
/*
* for mesh
* stop DHCP server on softAP interface by default
* stop DHCP client on station interface by default
*/
ESP_ERROR_CHECK(tcpip_adapter_dhcps_stop(TCPIP_ADAPTER_IF_AP));
ESP_ERROR_CHECK(tcpip_adapter_dhcpc_stop(TCPIP_ADAPTER_IF_STA));

Note: ESP-WIFI-MESH requires a root node to be connected with a router. Therefore, in the event that a node
becomes the root, the corresponding handler must start the DHCP client service and immediately obtain an
IP address. Doing so will allow other nodes to begin transmitting/receiving packets to/from the external IP network.
However, this step is unnecessary if static IP settings are used.
Writing an ESP-WIFI-MESH Application The prerequisites for starting ESP-WIFI-MESH is to initialize LwIP
and Wi-Fi, The following code snippet demonstrates the necessary prerequisite steps before ESP-WIFI-MESH itself
can be initialized.
tcpip_adapter_init();
/*
* for mesh
* stop DHCP server on softAP interface by default
* stop DHCP client on station interface by default
*/
ESP_ERROR_CHECK(tcpip_adapter_dhcps_stop(TCPIP_ADAPTER_IF_AP));
ESP_ERROR_CHECK(tcpip_adapter_dhcpc_stop(TCPIP_ADAPTER_IF_STA));
/* event initialization */
ESP_ERROR_CHECK(esp_event_loop_create_default());
/* Wi-Fi initialization */
wifi_init_config_t config = WIFI_INIT_CONFIG_DEFAULT();
ESP_ERROR_CHECK(esp_wifi_init(&config));
/* register IP events handler */
ESP_ERROR_CHECK(esp_event_handler_register(IP_EVENT, IP_EVENT_STA_GOT_IP, &ip_
,→event_handler, NULL));
ESP_ERROR_CHECK(esp_wifi_set_storage(WIFI_STORAGE_FLASH));
ESP_ERROR_CHECK(esp_wifi_start());
After initializing LwIP and Wi-Fi, the process of getting an ESP-WIFI-MESH network up and running can be
summarized into the following three steps:
1. Initialize Mesh
2. Configuring an ESP-WIFI-MESH Network
3. Start Mesh
Initialize Mesh The following code snippet demonstrates how to initialize ESP-WIFI-MESH
/* mesh initialization */
ESP_ERROR_CHECK(esp_mesh_init());
/* register mesh events handler */
ESP_ERROR_CHECK(esp_event_handler_register(MESH_EVENT, ESP_EVENT_ANY_ID, &mesh_
,→event_handler, NULL));
Configuring an ESP-WIFI-MESH Network ESP-WIFI-MESH is configured via

esp_mesh_set_config() which receives its arguments using the mesh_cfg_t structure. The struc-
ture contains the following parameters used to configure ESP-WIFI-MESH:
Parameter Description
Channel Range from 1 to 14
Mesh ID ID of ESP-WIFI-MESH Network, see mesh_addr_t
Router Router Configuration, see mesh_router_t
Mesh AP Mesh AP Configuration, see mesh_ap_cfg_t
Crypto Functions Crypto Functions for Mesh IE, see mesh_crypto_funcs_t

The following code snippet demonstrates how to configure ESP-WIFI-MESH.

/* Enable the Mesh IE encryption by default */
mesh_cfg_t cfg = MESH_INIT_CONFIG_DEFAULT();
/* mesh ID */
memcpy((uint8_t *) &cfg.mesh_id, MESH_ID, 6);
/* channel (must match the router's channel) */
cfg.channel = CONFIG_MESH_CHANNEL;
/* router */
cfg.router.ssid_len = strlen(CONFIG_MESH_ROUTER_SSID);
memcpy((uint8_t *) &cfg.router.ssid, CONFIG_MESH_ROUTER_SSID, cfg.router.ssid_len);
memcpy((uint8_t *) &cfg.router.password, CONFIG_MESH_ROUTER_PASSWD,
strlen(CONFIG_MESH_ROUTER_PASSWD));
/* mesh softAP */
cfg.mesh_ap.max_connection = CONFIG_MESH_AP_CONNECTIONS;
memcpy((uint8_t *) &cfg.mesh_ap.password, CONFIG_MESH_AP_PASSWD,
strlen(CONFIG_MESH_AP_PASSWD));
ESP_ERROR_CHECK(esp_mesh_set_config(&cfg));
Start Mesh The following code snippet demonstrates how to start ESP-WIFI-MESH.
/* mesh start */
ESP_ERROR_CHECK(esp_mesh_start());
After starting ESP-WIFI-MESH, the application should check for ESP-WIFI-MESH events to determine when it
has connected to the network. After connecting, the application can start transmitting and receiving packets over the
ESP-WIFI-MESH network using esp_mesh_send() and esp_mesh_recv().
Self Organized Networking Self organized networking is a feature of ESP-WIFI-MESH where nodes can au-
tonomously scan/select/connect/reconnect to other nodes and routers. This feature allows an ESP-WIFI-MESH net-
work to operate with high degree of autonomy by making the network robust to dynamic network topologies and
conditions. With self organized networking enabled, nodes in an ESP-WIFI-MESH network are able to carry out the
following actions without autonomously:
• Selection or election of the root node (see Automatic Root Node Selection in Building a Network)
• Selection of a preferred parent node (see Parent Node Selection in Building a Network)
• Automatic reconnection upon detecting a disconnection (see Intermediate Parent Node Failure in Managing
a Network)
When self organized networking is enabled, the ESP-WIFI-MESH stack will internally make calls to Wi-Fi APIs.
Therefore, the application layer should not make any calls to Wi-Fi APIs whilst self organized networking is
enabled as doing so would risk interfering with ESP-WIFI-MESH.
Toggling Self Organized Networking Self organized networking can be enabled or disabled by the application
at runtime by calling the esp_mesh_set_self_organized() function. The function has the two following
parameters:
• bool enable specifies whether to enable or disable self organized networking.
• bool select_parent specifies whether a new parent node should be selected when enabling self orga-
nized networking. Selecting a new parent has different effects depending the node type and the node s current
state. This parameter is unused when disabling self organized networking.
Disabling Self Organized Networking The following code snippet demonstrates how to disable self organized
networking.
//Disable self organized networking
esp_mesh_set_self_organized(false, false);
ESP-WIFI-MESH will attempt to maintain the node s current Wi-Fi state when disabling self organized networking.

• If the node was previously connected to other nodes, it will remain connected.
• If the node was previously disconnected and was scanning for a parent node or router, it will stop scanning.
• If the node was previously attempting to reconnect to a parent node or router, it will stop reconnecting.
Enabling Self Organized Networking ESP-WIFI-MESH will attempt to maintain the node s current Wi-Fi state
when enabling self organized networking. However, depending on the node type and whether a new parent is selected,
the Wi-Fi state of the node can change. The following table shows effects of enabling self organized networking.
Select Parent Is Root Node Effects

N N
• Nodes already connected to a
parent node will remain con-
nected.
• Nodes previously scan-
ning for a parent nodes
will stop scanning. Call
esp_mesh_connect()
to restart.
Y
• A root node already con-
nected to router will stay con-
nected.
• A root node disconnected
from router will need to call
esp_mesh_connect()
to reconnect.
Y N
• Nodes without a parent node
will automatically select a
preferred parent and connect.
• Nodes already connected to
a parent node will discon-
nect, reselect a preferred par-
ent node, and connect.
Y
• For a root node to connect to
a parent node, it must give up
it s role as root. Therefore,
a root node will disconnect
from the router and all child
nodes, select a preferred par-
ent node, and connect.
The following code snipping demonstrates how to enable self organized networking.
//Enable self organized networking and select a new parent

esp_mesh_set_self_organized(true, true);
...
//Enable self organized networking and manually reconnect

esp_mesh_set_self_organized(true, false);
esp_mesh_connect();

Calling Wi-Fi API There can be instances in which an application may want to directly call Wi-Fi API whilst
using ESP-WIFI-MESH. For example, an application may want to manually scan for neighboring APs. However,
self organized networking must be disabled before the application calls any Wi-Fi APIs. This will prevent the
ESP-WIFI-MESH stack from attempting to call any Wi-Fi APIs and potentially interfering with the application s
calls.
Therefore, application calls to Wi-Fi APIs should be placed in between calls of
esp_mesh_set_self_organized() which disable and enable self organized networking. The follow-
ing code snippet demonstrates how an application can safely call esp_wifi_scan_start() whilst using
ESP-WIFI-MESH.
//Disable self organized networking

esp_mesh_set_self_organized(0, 0);
//Stop any scans already in progress

esp_wifi_scan_stop();
//Manually start scan. Will automatically stop when run to completion
esp_wifi_scan_start();
//Process scan results
...
//Re-enable self organized networking if still connected

...
//Re-enable self organized networking if non-root and disconnected

...
//Re-enable self organized networking if root and disconnected

esp_mesh_set_self_organized(1, 0); //Don't select new parent
esp_mesh_connect(); //Manually reconnect to router
Application Examples ESP-IDF contains these ESP-WIFI-MESH example projects:

The Internal Communication Example demonstrates how to set up a ESP-WIFI-MESH network and have the root
node send a data packet to every node within the network.
The Manual Networking Example demonstrates how to use ESP-WIFI-MESH without the self-organizing features.
This example shows how to program a node to manually scan for a list of potential parent nodes and select a parent
node based on custom criteria.
API Reference
Header File
• components/esp_wifi/include/esp_mesh.h
Functions
esp_err_t esp_mesh_init(void)
Mesh initialization.
• Check whether Wi-Fi is started.
• Initialize mesh global variables with default values.
Attention This API shall be called after Wi-Fi is started.

Return
• ESP_OK
• ESP_FAIL
esp_err_t esp_mesh_deinit(void)
Mesh de-initialization.
• Release resources and stop the mesh
Return
• ESP_OK
• ESP_FAIL
esp_err_t esp_mesh_start(void)
Start mesh.
• Initialize mesh IE.
• Start mesh network management service.
• Create TX and RX queues according to the configuration.
• Register mesh packets receive callback.
Attention This API shall be called after mesh initialization and configuration.
Return
• ESP_OK
• ESP_FAIL
• ESP_ERR_MESH_NOT_INIT
• ESP_ERR_MESH_NOT_CONFIG
• ESP_ERR_MESH_NO_MEMORY
esp_err_t esp_mesh_stop(void)
Stop mesh.
• Deinitialize mesh IE.
• Disconnect with current parent.
• Disassociate all currently associated children.
• Stop mesh network management service.
• Unregister mesh packets receive callback.
• Delete TX and RX queues.
• Release resources.
• Restore Wi-Fi softAP to default settings if Wi-Fi dual mode is enabled.
• Set Wi-Fi Power Save type to WIFI_PS_NONE.
Return
• ESP_OK
• ESP_FAIL
esp_err_t esp_mesh_send(const mesh_addr_t *to, const mesh_data_t *data, int flag, const
mesh_opt_t opt[], int opt_count)
Send a packet over the mesh network.
• Send a packet to any device in the mesh network.
• Send a packet to external IP network.
Attention This API is not reentrant.
Return
• ESP_OK
• ESP_FAIL
• ESP_ERR_MESH_ARGUMENT
• ESP_ERR_MESH_NOT_START
• ESP_ERR_MESH_DISCONNECTED
• ESP_ERR_MESH_OPT_UNKNOWN
• ESP_ERR_MESH_EXCEED_MTU
• ESP_ERR_MESH_NO_MEMORY
• ESP_ERR_MESH_TIMEOUT
• ESP_ERR_MESH_QUEUE_FULL

• ESP_ERR_MESH_NO_ROUTE_FOUND
• ESP_ERR_MESH_DISCARD
Parameters
• [in] to: the address of the final destination of the packet
– If the packet is to the root, set this parameter to NULL.
– If the packet is to an external IP network, set this parameter to the IPv4:PORT combination.
This packet will be delivered to the root firstly, then the root will forward this packet to the final
IP server address.
• [in] data: pointer to a sending mesh packet
– Field size should not exceed MESH_MPS. Note that the size of one mesh packet should not
exceed MESH_MTU.
– Field proto should be set to data protocol in use (default is MESH_PROTO_BIN for binary).
– Field tos should be set to transmission tos (type of service) in use (default is MESH_TOS_P2P
for point-to-point reliable).
• [in] flag: bitmap for data sent
– Speed up the route search
* If the packet is to the root and to parameter is NULL, set this parameter to 0.
* If the packet is to an internal device, MESH_DATA_P2P should be set.
* If the packet is to the root ( to parameter isn t NULL) or to external IP network,
MESH_DATA_TODS should be set.
* If the packet is from the root to an internal device, MESH_DATA_FROMDS should be set.
– Specify whether this API is block or non-block, block by default
* If needs non-blocking, MESH_DATA_NONBLOCK should be set. Otherwise, may use
esp_mesh_send_block_time() to specify a blocking time.
– In the situation of the root change, MESH_DATA_DROP identifies this packet can be dropped
by the new root for upstream data to external IP network, we try our best to avoid data loss caused
by the root change, but there is a risk that the new root is running out of memory because most of
memory is occupied by the pending data which isn t read out in time by esp_mesh_recv_toDS().
Generally, we suggest esp_mesh_recv_toDS() is called after a connection with IP network
is created. Thus data outgoing to external IP network via socket is just from reading
esp_mesh_recv_toDS() which avoids unnecessary memory copy.
• [in] opt: options
– In case of sending a packet to a certain group, MESH_OPT_SEND_GROUP is a good choice.
In this option, the value field should be set to the target receiver addresses in this group.
– Root sends a packet to an internal device, this packet is from external IP network in case the
receiver device responds this packet, MESH_OPT_RECV_DS_ADDR is required to attach the
target DS address.
• [in] opt_count: option count
– Currently, this API only takes one option, so opt_count is only supported to be 1.
esp_err_t esp_mesh_send_block_time(uint32_t time_ms)
Set blocking time of esp_mesh_send()
Attention This API shall be called before mesh is started.
Return
• ESP_OK
Parameters
• [in] time_ms: blocking time of esp_mesh_send(), unit:ms
esp_err_t esp_mesh_recv(mesh_addr_t *from, mesh_data_t *data, int timeout_ms, int *flag, mesh_opt_t
opt[], int opt_count)
Receive a packet targeted to self over the mesh network.
flag could be MESH_DATA_FROMDS or MESH_DATA_TODS.
Attention Mesh RX queue should be checked regularly to avoid running out of memory.
• Use esp_mesh_get_rx_pending() to check the number of packets available in the queue waiting to
be received by applications.
Return
• ESP_OK

Parameters
• [out] from: the address of the original source of the packet
• [out] data: pointer to the received mesh packet
– Field proto is the data protocol in use. Should follow it to parse the received data.
– Field tos is the transmission tos (type of service) in use.
• [in] timeout_ms: wait time if a packet isn t immediately available (0:no wait, port-
MAX_DELAY:wait forever)
• [out] flag: bitmap for data received
– MESH_DATA_FROMDS represents data from external IP network
– MESH_DATA_TODS represents data directed upward within the mesh network
Parameters
• [out] opt: options desired to receive
– MESH_OPT_RECV_DS_ADDR attaches the DS address
• [in] opt_count: option count desired to receive
– Currently, this API only takes one option, so opt_count is only supported to be 1.
esp_err_t esp_mesh_recv_toDS(mesh_addr_t *from, mesh_addr_t *to, mesh_data_t *data, int time-
out_ms, int *flag, mesh_opt_t opt[], int opt_count)
Receive a packet targeted to external IP network.
• Root uses this API to receive packets destined to external IP network
• Root forwards the received packets to the final destination via socket.
• If no socket connection is ready to send out the received packets and this esp_mesh_recv_toDS() hasn
t been called by applications, packets from the whole mesh network will be pending in toDS queue.
Use esp_mesh_get_rx_pending() to check the number of packets available in the queue waiting to be received
by applications in case of running out of memory in the root.
Using esp_mesh_set_xon_qsize() users may configure the RX queue size, default:32. If this size is too large,
and esp_mesh_recv_toDS() isn t called in time, there is a risk that a great deal of memory is occupied by the
pending packets. If this size is too small, it will impact the efficiency on upstream. How to decide this value
depends on the specific application scenarios.
flag could be MESH_DATA_TODS.
Attention This API is only called by the root.
Return
• ESP_OK
• ESP_ERR_MESH_RECV_RELEASE
Parameters
• [out] from: the address of the original source of the packet
• [out] to: the address contains remote IP address and port (IPv4:PORT)
• [out] data: pointer to the received packet
– Contain the protocol and applications should follow it to parse the data.
• [in] timeout_ms: wait time if a packet isn t immediately available (0:no wait, port-
MAX_DELAY:wait forever)
• [out] flag: bitmap for data received
– MESH_DATA_TODS represents the received data target to external IP network. Root shall
forward this data to external IP network via the association with router.
Parameters
• [out] opt: options desired to receive
• [in] opt_count: option count desired to receive
esp_err_t esp_mesh_set_config(const mesh_cfg_t *config)
Set mesh stack configuration.

• Use MESH_INIT_CONFIG_DEFAULT() to initialize the default values, mesh IE is encrypted by de-

fault.
• Mesh network is established on a fixed channel (1-14).
• Mesh event callback is mandatory.
• Mesh ID is an identifier of an MBSS. Nodes with the same mesh ID can communicate with each other.
• Regarding to the router configuration, if the router is hidden, BSSID field is mandatory.
If BSSID field isn t set and there exists more than one router with same SSID, there is a risk that more roots
than one connected with different BSSID will appear. It means more than one mesh network is established
with the same mesh ID.
Root conflict function could eliminate redundant roots connected with the same BSSID, but couldn t handle
roots connected with different BSSID. Because users might have such requirements of setting up routers with
same SSID for the future replacement. But in that case, if the above situations happen, please make sure
applications implement forward functions on the root to guarantee devices in different mesh networks can
communicate with each other. max_connection of mesh softAP is limited by the max number of Wi-Fi softAP
supported (max:10).
Attention This API shall be called before mesh is started after mesh is initialized.
Return
• ESP_OK
• ESP_ERR_MESH_NOT_ALLOWED
Parameters
• [in] config: pointer to mesh stack configuration
esp_err_t esp_mesh_get_config(mesh_cfg_t *config)
Get mesh stack configuration.
Return
• ESP_OK
Parameters
• [out] config: pointer to mesh stack configuration
esp_err_t esp_mesh_set_router(const mesh_router_t *router)
Get router configuration.
Attention This API is used to dynamically modify the router configuration after mesh is configured.
Return
• ESP_OK
Parameters
• [in] router: pointer to router configuration
esp_err_t esp_mesh_get_router(mesh_router_t *router)
Get router configuration.
Return
• ESP_OK
Parameters
• [out] router: pointer to router configuration
esp_err_t esp_mesh_set_id(const mesh_addr_t *id)
Set mesh network ID.
Attention This API is used to dynamically modify the mesh network ID.
Return
• ESP_OK
• ESP_ERR_MESH_ARGUMENT: invalid argument
Parameters
• [in] id: pointer to mesh network ID

esp_err_t esp_mesh_get_id(mesh_addr_t *id)

Get mesh network ID.
Return
• ESP_OK
Parameters
• [out] id: pointer to mesh network ID
esp_err_t esp_mesh_set_type(mesh_type_t type)
Designate device type over the mesh network.
• MESH_IDLE: designates a device as a self-organized node for a mesh network
• MESH_ROOT: designates the root node for a mesh network
• MESH_LEAF: designates a device as a standalone Wi-Fi station that connects to a parent
• MESH_STA: designates a device as a standalone Wi-Fi station that connects to a router
Return
• ESP_OK
Parameters
• [in] type: device type
mesh_type_t esp_mesh_get_type(void)
Get device type over mesh network.
Attention This API shall be called after having received the event
MESH_EVENT_PARENT_CONNECTED.
Return mesh type
esp_err_t esp_mesh_set_max_layer(int max_layer)
Set network max layer value.
• for tree topology, the max is 25.
• for chain topology, the max is 1000.
• Network max layer limits the max hop count.
Return
• ESP_OK
Parameters
• [in] max_layer: max layer value
int esp_mesh_get_max_layer(void)
Get max layer value.
Return max layer value
esp_err_t esp_mesh_set_ap_password(const uint8_t *pwd, int len)
Set mesh softAP password.
Return
• ESP_OK
Parameters
• [in] pwd: pointer to the password
• [in] len: password length
esp_err_t esp_mesh_set_ap_authmode(wifi_auth_mode_t authmode)
Set mesh softAP authentication mode.

Return
• ESP_OK
Parameters
• [in] authmode: authentication mode
wifi_auth_mode_t esp_mesh_get_ap_authmode(void)
Get mesh softAP authentication mode.
Return authentication mode
esp_err_t esp_mesh_set_ap_connections(int connections)
Set mesh max connection value.
• Set mesh softAP max connection = mesh max connection + non-mesh max connection
Return
• ESP_OK
Parameters
• [in] connections: the number of max connections
int esp_mesh_get_ap_connections(void)
Get mesh max connection configuration.
Return the number of mesh max connections
int esp_mesh_get_non_mesh_connections(void)
Get non-mesh max connection configuration.
Return the number of non-mesh max connections
int esp_mesh_get_layer(void)
Get current layer value over the mesh network.
Return layer value
esp_err_t esp_mesh_get_parent_bssid(mesh_addr_t *bssid)
Get the parent BSSID.
Return
• ESP_OK
• ESP_FAIL
Parameters
• [out] bssid: pointer to parent BSSID
bool esp_mesh_is_root(void)
Return whether the device is the root node of the network.
Return true/false
esp_err_t esp_mesh_set_self_organized(bool enable, bool select_parent)
Enable/disable self-organized networking.
• Self-organized networking has three main functions: select the root node; find a preferred parent; initiate
reconnection if a disconnection is detected.
• Self-organized networking is enabled by default.
• If self-organized is disabled, users should set a parent for the device via esp_mesh_set_parent().
Attention This API is used to dynamically modify whether to enable the self organizing.
Return

• ESP_OK
• ESP_FAIL
Parameters
• [in] enable: enable or disable self-organized networking
• [in] select_parent: Only valid when self-organized networking is enabled.
– if select_parent is set to true, the root will give up its mesh root status and search for a new
parent like other non-root devices.
bool esp_mesh_get_self_organized(void)
Return whether enable self-organized networking or not.
Return true/false
esp_err_t esp_mesh_waive_root(const mesh_vote_t *vote, int reason)
Cause the root device to give up (waive) its mesh root status.
• A device is elected root primarily based on RSSI from the external router.
• If external router conditions change, users can call this API to perform a root switch.
• In this API, users could specify a desired root address to replace itself or specify an attempts value to
ask current root to initiate a new round of voting. During the voting, a better root candidate would be
expected to find to replace the current one.
• If no desired root candidate, the vote will try a specified number of attempts (at least 15). If no better
root candidate is found, keep the current one. If a better candidate is found, the new better one will send
a root switch request to the current root, current root will respond with a root switch acknowledgment.
• After that, the new candidate will connect to the router to be a new root, the previous root will disconnect
with the router and choose another parent instead.
Root switch is completed with minimal disruption to the whole mesh network.
Return
• ESP_OK
• ESP_ERR_MESH_QUEUE_FULL
• ESP_FAIL
Parameters
• [in] vote: vote configuration
– If this parameter is set NULL, the vote will perform the default 15 times.
– Field percentage threshold is 0.9 by default.
– Field is_rc_specified shall be false.
– Field attempts shall be at least 15 times.
• [in] reason: only accept MESH_VOTE_REASON_ROOT_INITIATED for now
esp_err_t esp_mesh_set_vote_percentage(float percentage)
Set vote percentage threshold for approval of being a root (default:0.9)
• During the networking, only obtaining vote percentage reaches this threshold, the device could be a root.
Return
• ESP_OK
• ESP_FAIL
Parameters
• [in] percentage: vote percentage threshold
float esp_mesh_get_vote_percentage(void)
Get vote percentage threshold for approval of being a root.
Return percentage threshold
esp_err_t esp_mesh_set_ap_assoc_expire(int seconds)
Set mesh softAP associate expired time (default:10 seconds)
• If mesh softAP hasn t received any data from an associated child within this time, mesh softAP will
take this child inactive and disassociate it.

• If mesh softAP is encrypted, this value should be set a greater value, such as 30 seconds.
Return
• ESP_OK
• ESP_FAIL
Parameters
• [in] seconds: the expired time
int esp_mesh_get_ap_assoc_expire(void)
Get mesh softAP associate expired time.
Return seconds
int esp_mesh_get_total_node_num(void)
Get total number of devices in current network (including the root)
Attention The returned value might be incorrect when the network is changing.
Return total number of devices (including the root)
int esp_mesh_get_routing_table_size(void)
Get the number of devices in this device s sub-network (including self)
Return the number of devices over this device s sub-network (including self)
esp_err_t esp_mesh_get_routing_table(mesh_addr_t *mac, int len, int *size)
Get routing table of this device s sub-network (including itself)
Return
• ESP_OK
Parameters
• [out] mac: pointer to routing table
• [in] len: routing table size(in bytes)
• [out] size: pointer to the number of devices in routing table (including itself)
esp_err_t esp_mesh_post_toDS_state(bool reachable)
Post the toDS state to the mesh stack.
Attention This API is only for the root.
Return
• ESP_OK
• ESP_FAIL
Parameters
• [in] reachable: this state represents whether the root is able to access external IP network
esp_err_t esp_mesh_get_tx_pending(mesh_tx_pending_t *pending)
Return the number of packets pending in the queue waiting to be sent by the mesh stack.
Return
• ESP_OK
• ESP_FAIL
Parameters
• [out] pending: pointer to the TX pending
esp_err_t esp_mesh_get_rx_pending(mesh_rx_pending_t *pending)
Return the number of packets available in the queue waiting to be received by applications.
Return
• ESP_OK
• ESP_FAIL
Parameters
• [out] pending: pointer to the RX pending
int esp_mesh_available_txupQ_num(const mesh_addr_t *addr, uint32_t *xseqno_in)
Return the number of packets could be accepted from the specified address.
Return the number of upQ for a certain address

Parameters
• [in] addr: self address or an associate children address
• [out] xseqno_in: sequence number of the last received packet from the specified address
esp_err_t esp_mesh_set_xon_qsize(int qsize)
Set the number of queue.
Return
• ESP_OK
• ESP_FAIL
Parameters
• [in] qsize: default:32 (min:16)
int esp_mesh_get_xon_qsize(void)
Get queue size.
Return the number of queue
esp_err_t esp_mesh_allow_root_conflicts(bool allowed)
Set whether allow more than one root existing in one network.
Return
• ESP_OK
• ESP_WIFI_ERR_NOT_INIT
• ESP_WIFI_ERR_NOT_START
Parameters
• [in] allowed: allow or not
bool esp_mesh_is_root_conflicts_allowed(void)
Check whether allow more than one root to exist in one network.
Return true/false
esp_err_t esp_mesh_set_group_id(const mesh_addr_t *addr, int num)
Set group ID addresses.
Return
• ESP_OK
• ESP_MESH_ERR_ARGUMENT
Parameters
• [in] addr: pointer to new group ID addresses
• [in] num: the number of group ID addresses
esp_err_t esp_mesh_delete_group_id(const mesh_addr_t *addr, int num)
Delete group ID addresses.
Return
• ESP_OK
Parameters
• [in] addr: pointer to deleted group ID address
int esp_mesh_get_group_num(void)
Get the number of group ID addresses.
Return the number of group ID addresses
esp_err_t esp_mesh_get_group_list(mesh_addr_t *addr, int num)
Get group ID addresses.
Return
• ESP_OK
Parameters

• [out] addr: pointer to group ID addresses

bool esp_mesh_is_my_group(const mesh_addr_t *addr)
Check whether the specified group address is my group.
Return true/false
esp_err_t esp_mesh_set_capacity_num(int num)
Set mesh network capacity (max:1000, default:300)
Return
• ESP_OK
Parameters
• [in] num: mesh network capacity
int esp_mesh_get_capacity_num(void)
Get mesh network capacity.
Return mesh network capacity
esp_err_t esp_mesh_set_ie_crypto_funcs(const mesh_crypto_funcs_t *crypto_funcs)
Set mesh IE crypto functions.
Attention This API can be called at any time after mesh is initialized.
Return
• ESP_OK
Parameters
• [in] crypto_funcs: crypto functions for mesh IE
– If crypto_funcs is set to NULL, mesh IE is no longer encrypted.
esp_err_t esp_mesh_set_ie_crypto_key(const char *key, int len)
Set mesh IE crypto key.
Attention This API can be called at any time after mesh is initialized.
Return
• ESP_OK
Parameters
• [in] key: ASCII crypto key
• [in] len: length in bytes, range:8~64
esp_err_t esp_mesh_get_ie_crypto_key(char *key, int len)
Get mesh IE crypto key.
Return
• ESP_OK
Parameters
• [out] key: ASCII crypto key
• [in] len: length in bytes, range:8~64
esp_err_t esp_mesh_set_root_healing_delay(int delay_ms)
Set delay time before starting root healing.
Return
• ESP_OK
Parameters
• [in] delay_ms: delay time in milliseconds
int esp_mesh_get_root_healing_delay(void)
Get delay time before network starts root healing.

Return delay time in milliseconds

esp_err_t esp_mesh_fix_root(bool enable)
Enable network Fixed Root Setting.
• Enabling fixed root disables automatic election of the root node via voting.
• All devices in the network shall use the same Fixed Root Setting (enabled or disabled).
• If Fixed Root is enabled, users should make sure a root node is designated for the network.
Return
• ESP_OK
Parameters
• [in] enable: enable or not
bool esp_mesh_is_root_fixed(void)
Check whether network Fixed Root Setting is enabled.
• Enable/disable network Fixed Root Setting by API esp_mesh_fix_root().
• Network Fixed Root Setting also changes with the flag value in parent networking IE.
Return true/false
esp_err_t esp_mesh_set_parent(const wifi_config_t *parent, const mesh_addr_t
*parent_mesh_id, mesh_type_t my_type, int my_layer)
Set a specified parent for the device.
Attention This API can be called at any time after mesh is configured.
Return
• ESP_OK
• ESP_ERR_ARGUMENT
• ESP_ERR_MESH_NOT_CONFIG
Parameters
• [in] parent: parent configuration, the SSID and the channel of the parent are mandatory.
– If the BSSID is set, make sure that the SSID and BSSID represent the same parent, otherwise
the device will never find this specified parent.
• [in] parent_mesh_id: parent mesh ID,
– If this value is not set, the original mesh ID is used.
• [in] my_type: mesh type
– MESH_STA is not supported.
– If the parent set for the device is the same as the router in the network configuration, then
my_type shall set MESH_ROOT and my_layer shall set MESH_ROOT_LAYER.
• [in] my_layer: mesh layer
– my_layer of the device may change after joining the network.
– If my_type is set MESH_NODE, my_layer shall be greater than MESH_ROOT_LAYER.
– If my_type is set MESH_LEAF, the device becomes a standalone Wi-Fi station and no longer
has the ability to extend the network.
esp_err_t esp_mesh_scan_get_ap_ie_len(int *len)
Get mesh networking IE length of one AP.
Return
• ESP_OK
• ESP_ERR_WIFI_NOT_INIT
• ESP_ERR_WIFI_ARG
• ESP_ERR_WIFI_FAIL
Parameters
• [out] len: mesh networking IE length
esp_err_t esp_mesh_scan_get_ap_record(wifi_ap_record_t *ap_record, void *buffer)
Get AP record.
Attention Different from esp_wifi_scan_get_ap_records(), this API only gets one of APs scanned each time.
See manual_networking example.
Return

• ESP_OK
• ESP_ERR_WIFI_FAIL
Parameters
• [out] ap_record: pointer to one AP record
• [out] buffer: pointer to the mesh networking IE of this AP
esp_err_t esp_mesh_flush_upstream_packets(void)
Flush upstream packets pending in to_parent queue and to_parent_p2p queue.
Return
• ESP_OK
esp_err_t esp_mesh_get_subnet_nodes_num(const mesh_addr_t *child_mac, int *nodes_num)
Get the number of nodes in the subnet of a specific child.
Return
• ESP_OK
Parameters
• [in] child_mac: an associated child address of this device
• [out] nodes_num: pointer to the number of nodes in the subnet of a specific child
esp_err_t esp_mesh_get_subnet_nodes_list(const mesh_addr_t *child_mac, mesh_addr_t
*nodes, int nodes_num)
Get nodes in the subnet of a specific child.
Return
• ESP_OK
Parameters
• [in] child_mac: an associated child address of this device
• [out] nodes: pointer to nodes in the subnet of a specific child
• [in] nodes_num: the number of nodes in the subnet of a specific child
esp_err_t esp_mesh_disconnect(void)
Disconnect from current parent.
Return
• ESP_OK
esp_err_t esp_mesh_connect(void)
Connect to current parent.
Return
• ESP_OK
esp_err_t esp_mesh_flush_scan_result(void)
Flush scan result.
Return
• ESP_OK
esp_err_t esp_mesh_switch_channel(const uint8_t *new_bssid, int csa_newchan, int csa_count)
Cause the root device to add Channel Switch Announcement Element (CSA IE) to beacon.
• Set the new channel
• Set how many beacons with CSA IE will be sent before changing a new channel
• Enable the channel switch function
Return
• ESP_OK

Parameters
• [in] new_bssid: the new router BSSID if the router changes
• [in] csa_newchan: the new channel number to which the whole network is moving
• [in] csa_count: channel switch period(beacon count), unit is based on beacon interval of its
softAP, the default value is 15.
esp_err_t esp_mesh_get_router_bssid(uint8_t *router_bssid)
Get the router BSSID.
Return
• ESP_OK
Parameters
• [out] router_bssid: pointer to the router BSSID
int64_t esp_mesh_get_tsf_time(void)
Get the TSF time.
Return the TSF time
esp_err_t esp_mesh_set_topology(esp_mesh_topology_t topo)
Set mesh topology. The default value is MESH_TOPO_TREE.
• MESH_TOPO_CHAIN supports up to 1000 layers
Return
• ESP_OK
Parameters
• [in] topo: MESH_TOPO_TREE or MESH_TOPO_CHAIN
esp_mesh_topology_t esp_mesh_get_topology(void)
Get mesh topology.
Return MESH_TOPO_TREE or MESH_TOPO_CHAIN
esp_err_t esp_mesh_enable_ps(void)
Enable mesh Power Save function.
Return
• ESP_OK
esp_err_t esp_mesh_disable_ps(void)
Disable mesh Power Save function.
Return
• ESP_OK
bool esp_mesh_is_ps_enabled(void)
Check whether the mesh Power Save function is enabled.
Return true/false
bool esp_mesh_is_device_active(void)
Check whether the device is in active state.
• If the device is not in active state, it will neither transmit nor receive frames.

Return true/false
esp_err_t esp_mesh_set_active_duty_cycle(int dev_duty, int dev_duty_type)
Set the device duty cycle and type.
• The range of dev_duty values is 1 to 100. The default value is 10.
• dev_duty = 100, the PS will be stopped.
• dev_duty is better to not less than 5.
• dev_duty_type could be MESH_PS_DEVICE_DUTY_REQUEST or
MESH_PS_DEVICE_DUTY_DEMAND.
• If dev_duty_type is set to MESH_PS_DEVICE_DUTY_REQUEST, the device will use a nwk_duty
provided by the network.
• If dev_duty_type is set to MESH_PS_DEVICE_DUTY_DEMAND, the device will use the specified
dev_duty.
Attention This API can be called at any time after mesh is started.
Return
• ESP_OK
• ESP_FAIL
Parameters
• [in] dev_duty: device duty cycle
• [in] dev_duty_type: device PS duty cycle type, not accept
MESH_PS_NETWORK_DUTY_MASTER
esp_err_t esp_mesh_get_active_duty_cycle(int *dev_duty, int *dev_duty_type)
Get device duty cycle and type.
Return
• ESP_OK
Parameters
• [out] dev_duty: device duty cycle
• [out] dev_duty_type: device PS duty cycle type
esp_err_t esp_mesh_set_network_duty_cycle(int nwk_duty, int duration_mins, int applied_rule)
Set the network duty cycle, duration and rule.
• The range of nwk_duty values is 1 to 100. The default value is 10.
• nwk_duty is the network duty cycle the entire network or the up-link path will use. A device that suc-
cessfully sets the nwk_duty is known as a NWK-DUTY-MASTER.
• duration_mins specifies how long the specified nwk_duty will be used. Once duration_mins expires, the
root will take over as the NWK-DUTY-MASTER. If an existing NWK-DUTY-MASTER leaves the
network, the root will take over as the NWK-DUTY-MASTER again.
• duration_mins = (-1) represents nwk_duty will be used until a new NWK-DUTY-MASTER with a dif-
ferent nwk_duty appears.
• Only the root can set duration_mins to (-1).
• If applied_rule is set to MESH_PS_NETWORK_DUTY_APPLIED_ENTIRE, the nwk_duty will be
used by the entire network.
• If applied_rule is set to MESH_PS_NETWORK_DUTY_APPLIED_UPLINK, the nwk_duty will only
be used by the up-link path nodes.
• The root does not accept MESH_PS_NETWORK_DUTY_APPLIED_UPLINK.
• A nwk_duty with duration_mins(-1) set by the root is the default network duty cycle used by the entire
network.
Attention This API can be called at any time after mesh is started.
• In self-organized network, if this API is called before mesh is started in all devices, (1)nwk_duty
shall be set to the same value for all devices; (2)duration_mins shall be set to (-1); (3)applied_rule
shall be set to MESH_PS_NETWORK_DUTY_APPLIED_ENTIRE; after the voted root appears,
the root will become the NWK-DUTY-MASTER and broadcast the nwk_duty and its identity of
NWK-DUTY-MASTER.
• If the root is specified (FIXED-ROOT), call this API in the root to provide a default nwk_duty for
the entire network.

• After joins the network, any device can call this API to change the nwk_duty, duration_mins or
applied_rule.
Return
• ESP_OK
• ESP_FAIL
Parameters
• [in] nwk_duty: network duty cycle
• [in] duration_mins: duration (unit: minutes)
• [in] applied_rule: only support MESH_PS_NETWORK_DUTY_APPLIED_ENTIRE
esp_err_t esp_mesh_get_network_duty_cycle(int *nwk_duty, int *duration_mins, int
*dev_duty_type, int *applied_rule)
Get the network duty cycle, duration, type and rule.
Return
• ESP_OK
Parameters
• [out] nwk_duty: current network duty cycle
• [out] duration_mins: the duration of current nwk_duty
• [out] dev_duty_type: if it includes MESH_PS_DEVICE_DUTY_MASTER, this device is
the current NWK-DUTY-MASTER.
• [out] applied_rule: MESH_PS_NETWORK_DUTY_APPLIED_ENTIRE
int esp_mesh_get_running_active_duty_cycle(void)
Get the running active duty cycle.
• The running active duty cycle of the root is 100.
• If duty type is set to MESH_PS_DEVICE_DUTY_REQUEST, the running active duty cycle is nwk_duty
provided by the network.
• If duty type is set to MESH_PS_DEVICE_DUTY_DEMAND, the running active duty cycle is dev_duty
specified by the users.
• In a mesh network, devices are typically working with a certain duty-cycle (transmitting, receiving and
sleep) to reduce the power consumption. The running active duty cycle decides the amount of awake
time within a beacon interval. At each start of beacon interval, all devices wake up, broadcast beacons,
and transmit packets if they do have pending packets for their parents or for their children. Note that
Low-duty-cycle means devices may not be active in most of the time, the latency of data transmission
might be greater.
Return the running active duty cycle
esp_err_t esp_mesh_ps_duty_signaling(int fwd_times)
Duty signaling.
Return
• ESP_OK
Parameters
• [in] fwd_times: the times of forwarding duty signaling packets
Unions
union mesh_addr_t
#include <esp_mesh.h> Mesh address.
Public Members
uint8_t addr[6]
mac address
mip_t mip
mip address
union mesh_event_info_t
#include <esp_mesh.h> Mesh event information.

Public Members
mesh_event_channel_switch_t channel_switch
channel switch
mesh_event_child_connected_t child_connected
child connected
mesh_event_child_disconnected_t child_disconnected
child disconnected
mesh_event_routing_table_change_t routing_table
routing table change
mesh_event_connected_t connected
parent connected
mesh_event_disconnected_t disconnected
parent disconnected
mesh_event_no_parent_found_t no_parent
no parent found
mesh_event_layer_change_t layer_change
layer change
mesh_event_toDS_state_t toDS_state
toDS state, devices shall check this state firstly before trying to send packets to external IP network. This
state indicates right now whether the root is capable of sending packets out. If not, devices had better to
wait until this state changes to be MESH_TODS_REACHABLE.
mesh_event_vote_started_t vote_started
vote started
mesh_event_root_address_t root_addr
root address
mesh_event_root_switch_req_t switch_req
root switch request
mesh_event_root_conflict_t root_conflict
other powerful root
mesh_event_root_fixed_t root_fixed
fixed root
mesh_event_scan_done_t scan_done
scan done
mesh_event_network_state_t network_state
network state, such as whether current mesh network has a root.
mesh_event_find_network_t find_network
network found that can join
mesh_event_router_switch_t router_switch
new router information
mesh_event_ps_duty_t ps_duty
PS duty information
union mesh_rc_config_t
#include <esp_mesh.h> Vote address configuration.

Public Members
int attempts
max vote attempts before a new root is elected automatically by mesh network. (min:15, 15 by default)
mesh_addr_t rc_addr
a new root address specified by users for API esp_mesh_waive_root()
Structures
struct mip_t
IP address and port.
Public Members
ip4_addr_t ip4
IP address
uint16_t port
port
struct mesh_event_channel_switch_t
Channel switch information.
Public Members
uint8_t channel
new channel
struct mesh_event_connected_t
Parent connected information.
Public Members
wifi_event_sta_connected_t connected
parent information, same as Wi-Fi event SYSTEM_EVENT_STA_CONNECTED does
uint16_t self_layer
layer
uint8_t duty
parent duty
struct mesh_event_no_parent_found_t
No parent found information.
Public Members
int scan_times
scan times being through
struct mesh_event_layer_change_t
Layer change information.
Public Members
uint16_t new_layer
new layer

struct mesh_event_vote_started_t
vote started information
Public Members
int reason
vote reason, vote could be initiated by children or by the root itself
int attempts
max vote attempts before stopped
mesh_addr_t rc_addr
root address specified by users via API esp_mesh_waive_root()
struct mesh_event_find_network_t
find a mesh network that this device can join
Public Members
uint8_t channel
channel number of the new found network
uint8_t router_bssid[6]
router BSSID
struct mesh_event_root_switch_req_t
Root switch request information.
Public Members
int reason
root switch reason, generally root switch is initialized by users via API esp_mesh_waive_root()
mesh_addr_t rc_addr
the address of root switch requester
struct mesh_event_root_conflict_t
Other powerful root address.
Public Members
int8_t rssi
rssi with router
uint16_t capacity
the number of devices in current network
uint8_t addr[6]
other powerful root address
struct mesh_event_routing_table_change_t
Routing table change.
Public Members
uint16_t rt_size_new
the new value
uint16_t rt_size_change
the changed value

struct mesh_event_root_fixed_t
Root fixed.
Public Members
bool is_fixed
status
struct mesh_event_scan_done_t
Scan done event information.
Public Members
uint8_t number
the number of APs scanned
struct mesh_event_network_state_t
Network state information.
Public Members
bool is_rootless
whether current mesh network has a root
struct mesh_event_ps_duty_t
PS duty information.
Public Members
uint8_t duty
parent or child duty
mesh_event_child_connected_t child_connected
child info
struct mesh_opt_t
Mesh option.
Public Members
uint8_t type
option type
uint16_t len
option length
uint8_t *val
option value
struct mesh_data_t
Mesh data for esp_mesh_send() and esp_mesh_recv()
Public Members
uint8_t *data
data

uint16_t size
data size
mesh_proto_t proto
data protocol
mesh_tos_t tos
data type of service
struct mesh_router_t
Router configuration.
Public Members
uint8_t ssid[32]
SSID
uint8_t ssid_len
length of SSID
uint8_t bssid[6]
BSSID, if this value is specified, users should also specify allow_router_switch .
password
bool allow_router_switch
if the BSSID is specified and this value is also set, when the router of this specified BSSID fails to be
found after fail (mesh_attempts_t) times, the whole network is allowed to switch to another router
with the same SSID. The new router might also be on a different channel. The default value is false.
There is a risk that if the password is different between the new switched router and the previous one, the
mesh network could be established but the root will never connect to the new switched router.
struct mesh_ap_cfg_t
Mesh softAP configuration.
Public Members
mesh softAP password
uint8_t max_connection
max number of stations allowed to connect in, default 6, max 10 = max_connection + non-
mesh_max_connectionmax mesh connections
uint8_t nonmesh_max_connection
max non-mesh connections
struct mesh_cfg_t
Mesh initialization configuration.
Public Members
uint8_t channel
channel, the mesh network on
bool allow_channel_switch
if this value is set, when fail (mesh_attempts_t) times is reached, device will change to a full channel
scan for a network that could join. The default value is false.
mesh_addr_t mesh_id
mesh network identification

mesh_router_t router
router configuration
mesh_ap_cfg_t mesh_ap
mesh softAP configuration
const mesh_crypto_funcs_t *crypto_funcs
crypto functions
struct mesh_vote_t
Vote.
Public Members
float percentage
vote percentage threshold for approval of being a root
bool is_rc_specified
if true, rc_addr shall be specified (Unimplemented). if false, attempts value shall be specified to make
network start root election.
mesh_rc_config_t config
vote address configuration
struct mesh_tx_pending_t
The number of packets pending in the queue waiting to be sent by the mesh stack.
Public Members
int to_parent
to parent queue
int to_parent_p2p
to parent (P2P) queue
int to_child
to child queue
int to_child_p2p
to child (P2P) queue
int mgmt
management queue
int broadcast
broadcast and multicast queue
struct mesh_rx_pending_t
The number of packets available in the queue waiting to be received by applications.
Public Members
int toDS
to external DS
int toSelf
to self

Macros
MESH_ROOT_LAYER
root layer value
MESH_MTU
max transmit unit(in bytes)
MESH_MPS
max payload size(in bytes)
ESP_ERR_MESH_WIFI_NOT_START
Mesh error code definition.
Wi-Fi isn t started
ESP_ERR_MESH_NOT_INIT
mesh isn t initialized
ESP_ERR_MESH_NOT_CONFIG
mesh isn t configured
ESP_ERR_MESH_NOT_START
mesh isn t started
ESP_ERR_MESH_NOT_SUPPORT
not supported yet
ESP_ERR_MESH_NOT_ALLOWED
operation is not allowed
ESP_ERR_MESH_NO_MEMORY
out of memory
ESP_ERR_MESH_ARGUMENT
illegal argument
ESP_ERR_MESH_EXCEED_MTU
packet size exceeds MTU
ESP_ERR_MESH_TIMEOUT
timeout
ESP_ERR_MESH_DISCONNECTED
disconnected with parent on station interface
ESP_ERR_MESH_QUEUE_FAIL
queue fail
ESP_ERR_MESH_QUEUE_FULL
queue full
ESP_ERR_MESH_NO_PARENT_FOUND
no parent found to join the mesh network
ESP_ERR_MESH_NO_ROUTE_FOUND
no route found to forward the packet
ESP_ERR_MESH_OPTION_NULL
no option found
ESP_ERR_MESH_OPTION_UNKNOWN
unknown option
ESP_ERR_MESH_XON_NO_WINDOW
no window for software flow control on upstream
ESP_ERR_MESH_INTERFACE
low-level Wi-Fi interface error

ESP_ERR_MESH_DISCARD_DUPLICATE
discard the packet due to the duplicate sequence number
ESP_ERR_MESH_DISCARD
discard the packet
ESP_ERR_MESH_VOTING
vote in progress
ESP_ERR_MESH_XMIT
XMIT
ESP_ERR_MESH_QUEUE_READ
error in reading queue
ESP_ERR_MESH_PS
mesh PS is not specified as enable or disable
ESP_ERR_MESH_RECV_RELEASE
release esp_mesh_recv_toDS
MESH_DATA_ENC
Flags bitmap for esp_mesh_send() and esp_mesh_recv()
data encrypted (Unimplemented)
MESH_DATA_P2P
point-to-point delivery over the mesh network
MESH_DATA_FROMDS
receive from external IP network
MESH_DATA_TODS
identify this packet is target to external IP network
MESH_DATA_NONBLOCK
esp_mesh_send() non-block
MESH_DATA_DROP
in the situation of the root having been changed, identify this packet can be dropped by new root
MESH_DATA_GROUP
identify this packet is target to a group address
MESH_OPT_SEND_GROUP
Option definitions for esp_mesh_send() and esp_mesh_recv()
data transmission by group; used with esp_mesh_send() and shall have payload
MESH_OPT_RECV_DS_ADDR
return a remote IP address; used with esp_mesh_send() and esp_mesh_recv()
MESH_ASSOC_FLAG_VOTE_IN_PROGRESS
Flag of mesh networking IE.
vote in progress
MESH_ASSOC_FLAG_NETWORK_FREE
no root in current network
MESH_ASSOC_FLAG_ROOTS_FOUND
root conflict is found
MESH_ASSOC_FLAG_ROOT_FIXED
fixed root
MESH_PS_DEVICE_DUTY_REQUEST
Mesh PS (Power Save) duty cycle type.

requests to join a network PS without specifying a device duty cycle. After the device joins the network, a
network duty cycle will be provided by the network
MESH_PS_DEVICE_DUTY_DEMAND
requests to join a network PS and specifies a demanded device duty cycle
MESH_PS_NETWORK_DUTY_MASTER
indicates the device is the NWK-DUTY-MASTER (network duty cycle master)
MESH_PS_NETWORK_DUTY_APPLIED_ENTIRE
Mesh PS (Power Save) duty cycle applied rule.
MESH_PS_NETWORK_DUTY_APPLIED_UPLINK
MESH_INIT_CONFIG_DEFAULT()
Type Definitions
typedef mesh_addr_t mesh_event_root_address_t
Root address.
typedef wifi_event_sta_disconnected_t mesh_event_disconnected_t
Parent disconnected information.
typedef wifi_event_ap_staconnected_t mesh_event_child_connected_t
Child connected information.
typedef wifi_event_ap_stadisconnected_t mesh_event_child_disconnected_t
Child disconnected information.
typedef wifi_event_sta_connected_t mesh_event_router_switch_t
New router information.
Enumerations
enum mesh_event_id_t
Enumerated list of mesh event id.
Values:
MESH_EVENT_STARTED
mesh is started
MESH_EVENT_STOPPED
mesh is stopped
MESH_EVENT_CHANNEL_SWITCH
channel switch
MESH_EVENT_CHILD_CONNECTED
a child is connected on softAP interface
MESH_EVENT_CHILD_DISCONNECTED
a child is disconnected on softAP interface
MESH_EVENT_ROUTING_TABLE_ADD
routing table is changed by adding newly joined children
MESH_EVENT_ROUTING_TABLE_REMOVE
routing table is changed by removing leave children
MESH_EVENT_PARENT_CONNECTED
parent is connected on station interface
MESH_EVENT_PARENT_DISCONNECTED
parent is disconnected on station interface
MESH_EVENT_NO_PARENT_FOUND
no parent found

MESH_EVENT_LAYER_CHANGE
layer changes over the mesh network
MESH_EVENT_TODS_STATE
state represents whether the root is able to access external IP network
MESH_EVENT_VOTE_STARTED
the process of voting a new root is started either by children or by the root
MESH_EVENT_VOTE_STOPPED
the process of voting a new root is stopped
MESH_EVENT_ROOT_ADDRESS
the root address is obtained. It is posted by mesh stack automatically.
MESH_EVENT_ROOT_SWITCH_REQ
root switch request sent from a new voted root candidate
MESH_EVENT_ROOT_SWITCH_ACK
root switch acknowledgment responds the above request sent from current root
MESH_EVENT_ROOT_ASKED_YIELD
the root is asked yield by a more powerful existing root. If self organized is disabled and this device is
specified to be a root by users, users should set a new parent for this device. if self organized is enabled,
this device will find a new parent by itself, users could ignore this event.
MESH_EVENT_ROOT_FIXED
when devices join a network, if the setting of Fixed Root for one device is different from that of its parent,
the device will update the setting the same as its parent s. Fixed Root Setting of each device is variable
as that setting changes of the root.
MESH_EVENT_SCAN_DONE
if self-organized networking is disabled, user can call esp_wifi_scan_start() to trigger this event, and add
the corresponding scan done handler in this event.
MESH_EVENT_NETWORK_STATE
network state, such as whether current mesh network has a root.
MESH_EVENT_STOP_RECONNECTION
the root stops reconnecting to the router and non-root devices stop reconnecting to their parents.
MESH_EVENT_FIND_NETWORK
when the channel field in mesh configuration is set to zero, mesh stack will perform a full channel scan
to find a mesh network that can join, and return the channel value after finding it.
MESH_EVENT_ROUTER_SWITCH
if users specify BSSID of the router in mesh configuration, when the root connects to another router with
the same SSID, this event will be posted and the new router information is attached.
MESH_EVENT_PS_PARENT_DUTY
parent duty
MESH_EVENT_PS_CHILD_DUTY
child duty
MESH_EVENT_PS_DEVICE_DUTY
device duty
MESH_EVENT_MAX
enum mesh_type_t
Device type.
Values:
MESH_IDLE
hasn t joined the mesh network yet

MESH_ROOT
the only sink of the mesh network. Has the ability to access external IP network
MESH_NODE
intermediate device. Has the ability to forward packets over the mesh network
MESH_LEAF
has no forwarding ability
MESH_STA
connect to router with a standlone Wi-Fi station mode, no network expansion capability
enum mesh_proto_t
Protocol of transmitted application data.
Values:
MESH_PROTO_BIN
binary
MESH_PROTO_HTTP
HTTP protocol
MESH_PROTO_JSON
JSON format
MESH_PROTO_MQTT
MQTT protocol
MESH_PROTO_AP
IP network mesh communication of node s AP interface
MESH_PROTO_STA
IP network mesh communication of node s STA interface
enum mesh_tos_t
For reliable transmission, mesh stack provides three type of services.
Values:
MESH_TOS_P2P
provide P2P (point-to-point) retransmission on mesh stack by default
MESH_TOS_E2E
provide E2E (end-to-end) retransmission on mesh stack (Unimplemented)
MESH_TOS_DEF
no retransmission on mesh stack
enum mesh_vote_reason_t
Vote reason.
Values:
MESH_VOTE_REASON_ROOT_INITIATED = 1
vote is initiated by the root
MESH_VOTE_REASON_CHILD_INITIATED
vote is initiated by children
enum mesh_disconnect_reason_t
Mesh disconnect reason code.
Values:
MESH_REASON_CYCLIC = 100
cyclic is detected
MESH_REASON_PARENT_IDLE
parent is idle

MESH_REASON_LEAF
the connected device is changed to a leaf
MESH_REASON_DIFF_ID
in different mesh ID
MESH_REASON_ROOTS
root conflict is detected
MESH_REASON_PARENT_STOPPED
parent has stopped the mesh
MESH_REASON_SCAN_FAIL
scan fail
MESH_REASON_IE_UNKNOWN
unknown IE
MESH_REASON_WAIVE_ROOT
waive root
MESH_REASON_PARENT_WORSE
parent with very poor RSSI
MESH_REASON_EMPTY_PASSWORD
use an empty password to connect to an encrypted parent
MESH_REASON_PARENT_UNENCRYPTED
connect to an unencrypted parent/router
enum esp_mesh_topology_t
Mesh topology.
Values:
MESH_TOPO_TREE
tree topology
MESH_TOPO_CHAIN
chain topology
enum mesh_event_toDS_state_t
The reachability of the root to a DS (distribute system)
Values:
MESH_TODS_UNREACHABLE
the root isn t able to access external IP network
MESH_TODS_REACHABLE
the root is able to access external IP network
Wi-Fi Easy ConnectTM (DPP)
Wi-Fi Easy ConnectTM , also known as Device Provisioning Protocol (DPP) or Easy Connect, is a provisioning pro-
tocol certified by Wi-Fi Alliance. It is a secure and standardized provisioning protocol for configuration of Wi-Fi
Devices. With Easy Connect adding a new device to a network is as simple as scanning a QR Code. This reduces
complexity and enhances user experience while onboarding devices without UI like Smart Home and IoT products.
Unlike old protocols like WiFi Protected Setup (WPS), Wi-Fi Easy Connect incorporates strong encryption through
public key cryptography to ensure networks remain secure as new devices are added. Easy Connect brings many
benefits in the User Experience:
• Simple and intuitive to use; no lengthy instructions to follow for new device setup
• No need to remember and enter passwords into the device being provisioned
• Works with electronic or printed QR codes, or human-readable strings
• Supports both WPA2 and WPA3 networks

Please refer to Wi-Fi Alliance s official page on Easy Connect for more information.
ESP32 supports Enrollee mode of Easy Connect with QR Code as the provisioning method. A display is required to
display this QR Code. Users can scan this QR Code using their capable device and provision the ESP32 to their Wi-Fi
network. The provisioning device needs to be connected to the AP which need not support Wi-Fi Easy Connect™.
Easy Connect is still an evolving protocol. Of known platforms that support the QR Code method are some Android
smartphones with Android 10 or higher. To use Easy Connect no additional App needs to be installed on the supported
smartphone.
Application Example Example on how to provision ESP32 using a supported smartphone:

wifi/wifi_easy_connect/dpp-enrollee.
API Reference
Header File
• components/wpa_supplicant/esp_supplicant/include/esp_dpp.h
Functions
esp_err_t esp_supp_dpp_init(esp_supp_dpp_event_cb_t evt_cb)
Initialize DPP Supplicant.
Starts DPP Supplicant and initializes related Data Structures.
return
• ESP_OK: Success
• ESP_FAIL: Failure
Parameters
• evt_cb: Callback function to receive DPP related events
void esp_supp_dpp_deinit(void)
De-initalize DPP Supplicant.
Frees memory from DPP Supplicant Data Structures.
esp_err_t esp_supp_dpp_bootstrap_gen(const char *chan_list, esp_supp_dpp_bootstrap_t type,
const char *key, const char *info)
Generates Bootstrap Information as an Enrollee.
Generates Out Of Band Bootstrap information as an Enrollee which can be used by a DPP Configurator to
provision the Enrollee.
Return
• ESP_OK: Success
• ESP_FAIL: Failure
Parameters
• chan_list: List of channels device will be available on for listening
• type: Bootstrap method type, only QR Code method is supported for now.
• key: (Optional) Private Key used to generate a Bootstrapping Public Key
• info: (Optional) Ancilliary Device Information like Serial Number
esp_err_t esp_supp_dpp_start_listen(void)
Start listening on Channels provided during esp_supp_dpp_bootstrap_gen.
Listens on every Channel from Channel List for a pre-defined wait time.
Return
• ESP_OK: Success
• ESP_FAIL: Generic Failure
• ESP_ERR_INVALID_STATE: ROC attempted before WiFi is started
• ESP_ERR_NO_MEM: Memory allocation failed while posting ROC request

void esp_supp_dpp_stop_listen(void)
Stop listening on Channels.
Stops listening on Channels and cancels ongoing listen operation.
Macros
ESP_ERR_DPP_FAILURE
Generic failure during DPP Operation
ESP_ERR_DPP_TX_FAILURE
DPP Frame Tx failed OR not Acked
ESP_ERR_DPP_INVALID_ATTR
Encountered invalid DPP Attribute
Type Definitions
typedef enum dpp_bootstrap_type esp_supp_dpp_bootstrap_t
Types of Bootstrap Methods for DPP.
typedef void (*esp_supp_dpp_event_cb_t)(esp_supp_dpp_event_t evt, void *data)
Callback function for receiving DPP Events from Supplicant.
Callback function will be called with DPP related information.
Parameters
• evt: DPP event ID
• data: Event data payload
Enumerations
enum dpp_bootstrap_type
Types of Bootstrap Methods for DPP.
Values:
DPP_BOOTSTRAP_QR_CODE
QR Code Method
DPP_BOOTSTRAP_PKEX
Proof of Knowledge Method
DPP_BOOTSTRAP_NFC_URI
NFC URI record Method
enum esp_supp_dpp_event_t
Types of Callback Events received from DPP Supplicant.
Values:
ESP_SUPP_DPP_URI_READY
URI is ready through Bootstrapping
ESP_SUPP_DPP_CFG_RECVD
Config received via DPP Authentication
ESP_SUPP_DPP_FAIL
DPP Authentication failure
Code examples for the Wi-Fi API are provided in the wifi directory of ESP-IDF examples.
Code examples for ESP-WIFI-MESH are provided in the mesh directory of ESP-IDF examples.
2.2.2 Ethernet
Ethernet

Overview ESP-IDF provides a set of consistent and flexible APIs to support both internal Ethernet MAC (EMAC)
controller and external SPI-Ethernet modules.
This programming guide is split into the following sections:
1. Basic Ethernet Concepts
2. Configure MAC and PHY
3. Connect Driver to TCP/IP Stack
4. Misc control of Ethernet driver
Basic Ethernet Concepts Ethernet is an asynchronous Carrier Sense Multiple Access with Collision Detect
(CSMA/CD) protocol/interface. It is generally not well suited for low power applications. However, with ubiq-
uitous deployment, internet connectivity, high data rates and limitless rage expandability, Ethernet can accommodate
nearly all wired communications.
Normal IEEE 802.3 compliant Ethernet frames are between 64 and 1518 bytes in length. They are made up of
five or six different fields: a destination MAC address (DA), a source MAC address (SA), a type/length field, data
payload, an optional padding field and a Cyclic Redundancy Check (CRC). Additionally, when transmitted on the
Ethernet medium, a 7-byte preamble field and Start-of-Frame (SOF) delimiter byte are appended to the beginning
of the Ethernet packet.
Thus the traffic on the twist-pair cabling will appear as shown blow:
Fig. 4: Ethernet Data Frame Format
Preamble and Start-of-Frame Delimiter The preamble contains seven bytes of 55H, it allows the receiver to lock
onto the stream of data before the actual frame arrives. The Start-of-Frame Delimiter (SFD) is a binary sequence
10101011 (as seen on the physical medium). It is sometimes considered to be part of the preamble.
When transmitting and receiving data, the preamble and SFD bytes will automatically be generated or stripped from
the packets.

Destination Address The destination address field contains a 6-byte length MAC address of the device that the
packet is directed to. If the Least Significant bit in the first byte of the MAC address is set, the address is a multi-cast
destination. For example, 01-00-00-00-F0-00 and 33-45-67-89-AB-CD are multi-cast addresses, while 00-00-00-
00-F0-00 and 32-45-67-89-AB-CD are not. Packets with multi-cast destination addresses are designed to arrive and
be important to a selected group of Ethernet nodes. If the destination address field is the reserved multi-cast address,
i.e. FF-FF-FF-FF-FF-FF, the packet is a broadcast packet and it will be directed to everyone sharing the network.
If the Least Significant bit in the first byte of the MAC address is clear, the address is a uni-cast address and will be
designed for usage by only the addressed node.
Normally the EMAC controller incorporates receive filters which can be used to discard or accept packets with multi-
cast, broadcast and/or uni-cast destination addresses. When transmitting packets, the host controller is responsible
for writing the desired destination address into the transmit buffer.
Source Address The source address field contains a 6-byte length MAC address of the node which created the
Ethernet packet. Users of Ethernet must generate a unique MAC address for each controller used. MAC addresses
consist of two portions. The first three bytes are known as the Organizationally Unique Identifier (OUI). OUIs are
distributed by the IEEE. The last three bytes are address bytes at the discretion of the company that purchased the
OUI. More information about MAC Address used in ESP-IDF, please see MAC Address Allocation.
When transmitting packets, the assigned source MAC address must be written into the transmit buffer by the host
controller.
Type / Length The type/length field is a 2-byte field, if the value in this field is <= 1500 (decimal), it is considered
a length field and it specifies the amount of non-padding data which follows in the data field. If the value is >= 1536,
it represents the protocol the following packet data belongs to. The following are the most common type values:
• IPv4 = 0800H
• IPv6 = 86DDH
• ARP = 0806H
Users implementing proprietary networks may choose to treat this field as a length field, while applications imple-
menting protocols such as the Internet Protocol (IP) or Address Resolution Protocol (ARP), should program this field
with the appropriate type defined by the protocol s specification when transmitting packets.
Payload The payload field is a variable length field, anywhere from 0 to 1500 bytes. Larger data packets will
violate Ethernet standards and will be dropped by most Ethernet nodes. This field contains the client data, such as an
IP datagram.
Padding and FCS The padding field is a variable length field added to meet IEEE 802.3 specification requirements
when small data payloads are used. The DA, SA, type, payload and padding of an Ethernet packet must be no smaller
than 60 bytes. Adding the required 4-byte FCS field, packets must be no smaller than 64 bytes. If the data field is
less than 46 bytes long, a padding field is required.
The FCS field is a 4-byte field which contains an industry standard 32-bit CRC calculated with the data from the
DA, SA, type, payload and padding fields. Given the complexity of calculating a CRC, the hardware normally will
automatically generate a valid CRC and transmit it. Otherwise, the host controller must generate the CRC and place
it in the transmit buffer.
Normally, the host controller does not need to concern itself with padding and the CRC which the hardware EMAC
will also be able to automatically generate when transmitting and verify when receiving. However, the padding and
CRC fields will be written into the receive buffer when packets arrive, so they may be evaluated by the host controller
if needed.
Note: Besides the basic data frame described above, there re two other common frame types in 10/100 Mbps
Ethernet: control frames and VLAN tagged frames. They re not supported in ESP-IDF.

Configure MAC and PHY Ethernet driver is composed of two parts: MAC and PHY.
The communication between MAC and PHY can have diverse choices: MII (Media Independent Interface), RMII
(Reduced Media Independent Interface) and etc.
One of the obvious difference between MII and RMII is the signal consumption. For MII, it usually costs up to 18
signals. Instead, RMII interface can reduce the consumption to 9.
In RMII mode, both the receiver and transmitter signals are referenced to the REF_CLK. REF_CLK must be stable
during any access to PHY and MAC. Generally there re three ways to generate the REF_CLK depending on the
PHY device in your design:
• Some PHY chip can derive the REF_CLK from its external connected 25MHz crystal oscillator (as seen
the option a in the picture). In this case, you should select CONFIG_ETH_RMII_CLK_INPUT in CON-
FIG_ETH_RMII_CLK_MODE.
• Some PHY chip uses an external connected 50MHz crystal oscillator or other clock source, which can also be
used as the REF_CLK for MAC side (as seen the option b in the picture). In this case, you still need to select
CONFIG_ETH_RMII_CLK_INPUT in CONFIG_ETH_RMII_CLK_MODE.
• Some EMAC controller can generate the REF_CLK using its internal high precision PLL (as seen the
option c in the picture). In this case, you should select CONFIG_ETH_RMII_CLK_OUTPUT in CON-
FIG_ETH_RMII_CLK_MODE.
Note: REF_CLK is configured via Project Configuration as described above by default. However, it can be
overwritten from user application code by appropriately setting interface and clock_config members of
eth_mac_config_t structure. See emac_rmii_clock_mode_t and emac_rmii_clock_gpio_t for
more details.
Warning: If the RMII clock mode is selected to CONFIG_ETH_RMII_CLK_OUTPUT, then GPIO0 can be
used to output the REF_CLK signal. See CONFIG_ETH_RMII_CLK_OUTPUT_GPIO0 for more information.
What s more, if you re not using PSRAM in your design, GPIO16 and GPIO17 are also available to output
the reference clock. See CONFIG_ETH_RMII_CLK_OUT_GPIO for more information.
If the RMII clock mode is selected to CONFIG_ETH_RMII_CLK_INPUT, then GPIO0 is the only choice to
input the REF_CLK signal. Please note that, GPIO0 is also an important strapping GPIO on ESP32. If GPIO0
samples a low level during power up, ESP32 will go into download mode. The system will get halted until a
manually reset. The workaround of this issue is disabling the REF_CLK in hardware by default, so that the
strapping pin won t be interfered by other signals in boot stage. Then re-enable the REF_CLK in Ethernet driver
installation stage. The ways to disable the REF_CLK signal can be:
• Disable or power down the crystal oscillator (as the case b in the picture).
• Force the PHY device in reset status (as the case a in the picture). This could fail for some PHY device
(i.e. it still outputs signal to GPIO0 even in reset state).
No matter which RMII clock mode you select, you really need to take care of the signal integrity of REF_CLK
in your hardware design! Keep the trace as short as possible. Keep it away from RF devices. Keep it away from
inductor elements.
Note: ESP-IDF only supports the RMII interface (i.e. always select CONFIG_ETH_PHY_INTERFACE_RMII in
Kconfig option CONFIG_ETH_PHY_INTERFACE).
Signals used in data plane are fixed to specific GPIOs via MUX, they can t be modified to other GPIOs. Signals
used in control plane can be routed to any free GPIOs via Matrix. Please refer to ESP32-Ethernet-Kit for hardware
design example.
We need to setup necessary parameters for MAC and PHY respectively based on your Ethernet board design and
then combine the two together, completing the driver installation.
Configuration for MAC is described in eth_mac_config_t, including:

Fig. 5: Ethernet RMII Interface

• sw_reset_timeout_ms: software reset timeout value, in milliseconds, typically MAC reset should be
finished within 100ms.
• rx_task_stack_size and rx_task_prio: the MAC driver creates a dedicated task to process in-
coming packets, these two parameters are used to set the stack size and priority of the task.
• flags: specifying extra features that the MAC driver should have, it could be useful in some special sit-
uations. The value of this field can be OR d with macros prefixed with ETH_MAC_FLAG_. For ex-
ample, if the MAC driver should work when cache is disabled, then you should configure this field with
ETH_MAC_FLAG_WORK_WITH_CACHE_DISABLE.
• smi_mdc_gpio_num and smi_mdio_gpio_num: the GPIO number used to connect the SMI signals.
• interface: configuration of MAC Data interface to PHY (MII/RMII).
• clock_config: configuration of EMAC Interface clock (REF_CLK mode and GPIO number in case of
RMII).
Configuration for PHY is described in eth_phy_config_t, including:
• phy_addr: multiple PHY device can share the same SMI bus, so each PHY needs a unique address. Usually
this address is configured during hardware design by pulling up/down some PHY strapping pins. You can set
the value from 0 to 15 based on your Ethernet board. Especially, if the SMI bus is shared by only one PHY
device, setting this value to -1 can enable the driver to detect the PHY address automatically.
• reset_timeout_ms: reset timeout value, in milliseconds, typically PHY reset should be finished within
100ms.
• autonego_timeout_ms: auto-negotiation timeout value, in milliseconds. Ethernet driver will start nego-
tiation with the peer Ethernet node automatically, to determine to duplex and speed mode. This value usually
depends on the ability of the PHY device on your board.
• reset_gpio_num: if your board also connect the PHY reset pin to one of the GPIO, then set it here.
Otherwise, set this field to -1.
ESP-IDF provides a default configuration for MAC and PHY in macro ETH_MAC_DEFAULT_CONFIG and
ETH_PHY_DEFAULT_CONFIG.
Create MAC and PHY Instance Ethernet driver is implemented in an Object-Oriented style. Any operation on
MAC and PHY should be based on the instance of them two.
Internal EMAC + External PHY

eth_mac_config_t mac_config = ETH_MAC_DEFAULT_CONFIG(); // apply default MAC␣
,→configuration
mac_config.smi_mdc_gpio_num = CONFIG_EXAMPLE_ETH_MDC_GPIO; // alter the GPIO␣

,→used for MDC signal
mac_config.smi_mdio_gpio_num = CONFIG_EXAMPLE_ETH_MDIO_GPIO; // alter the GPIO␣

,→used for MDIO signal
esp_eth_mac_t *mac = esp_eth_mac_new_esp32(&mac_config); // create MAC instance
eth_phy_config_t phy_config = ETH_PHY_DEFAULT_CONFIG(); // apply default PHY␣

,→configuration
phy_config.phy_addr = CONFIG_EXAMPLE_ETH_PHY_ADDR; // alter the PHY␣

,→address according to your board design
phy_config.reset_gpio_num = CONFIG_EXAMPLE_ETH_PHY_RST_GPIO; // alter the GPIO␣

,→used for PHY reset
esp_eth_phy_t *phy = esp_eth_phy_new_ip101(&phy_config); // create PHY instance

// ESP-IDF officially supports several different Ethernet PHY chip driver
// esp_eth_phy_t *phy = esp_eth_phy_new_rtl8201(&phy_config);
// esp_eth_phy_t *phy = esp_eth_phy_new_lan8720(&phy_config);
// esp_eth_phy_t *phy = esp_eth_phy_new_dp83848(&phy_config);
Optional Runtime MAC Clock Configuration EMAC REF_CLK can be optionally configured from user appli-
cation code.


,→configuration
// ...
mac_config.interface = EMAC_DATA_INTERFACE_RMII; // alter EMAC Data Interface

mac_config.clock_config.rmii.clock_mode = EMAC_CLK_OUT; // select EMAC REF_CLK mode
mac_config.clock_config.rmii.clock_gpio = EMAC_CLK_OUT_GPIO; // select GPIO number␣
,→used to input/output EMAC REF_CLK
esp_eth_mac_t *mac = esp_eth_mac_new_esp32(&mac_config); // create MAC instance
SPI-Ethernet Module
,→configuration
eth_phy_config_t phy_config = ETH_PHY_DEFAULT_CONFIG(); // apply default PHY␣

,→configuration
phy_config.phy_addr = CONFIG_EXAMPLE_ETH_PHY_ADDR; // alter the PHY␣

,→address according to your board design
phy_config.reset_gpio_num = CONFIG_EXAMPLE_ETH_PHY_RST_GPIO; // alter the GPIO␣

,→used for PHY reset
// Install GPIO interrupt service (as the SPI-Ethernet module is interrupt driven)
gpio_install_isr_service(0);
// SPI bus configuration
spi_device_handle_t spi_handle = NULL;
spi_bus_config_t buscfg = {
.miso_io_num = CONFIG_EXAMPLE_ETH_SPI_MISO_GPIO,
.mosi_io_num = CONFIG_EXAMPLE_ETH_SPI_MOSI_GPIO,
.sclk_io_num = CONFIG_EXAMPLE_ETH_SPI_SCLK_GPIO,
.quadwp_io_num = -1,
.quadhd_io_num = -1,
};
ESP_ERROR_CHECK(spi_bus_initialize(CONFIG_EXAMPLE_ETH_SPI_HOST, &buscfg, 1));
// Allocate SPI device from the bus
spi_device_interface_config_t devcfg = {
.command_bits = 1,
.address_bits = 7,
.mode = 0,
.clock_speed_hz = CONFIG_EXAMPLE_ETH_SPI_CLOCK_MHZ * 1000 * 1000,
.spics_io_num = CONFIG_EXAMPLE_ETH_SPI_CS_GPIO,
.queue_size = 20
};
ESP_ERROR_CHECK(spi_bus_add_device(CONFIG_EXAMPLE_ETH_SPI_HOST, &devcfg, &spi_
,→handle));
/* dm9051 ethernet driver is based on spi driver */

eth_dm9051_config_t dm9051_config = ETH_DM9051_DEFAULT_CONFIG(spi_handle);
dm9051_config.int_gpio_num = CONFIG_EXAMPLE_ETH_SPI_INT_GPIO;
esp_eth_mac_t *mac = esp_eth_mac_new_dm9051(&dm9051_config, &mac_config);
esp_eth_phy_t *phy = esp_eth_phy_new_dm9051(&phy_config);
Note:
• When creating MAC and PHY instance for SPI-Ethernet modules (e.g. DM9051), the constructor function
must have the same suffix (e.g. esp_eth_mac_new_dm9051 and esp_eth_phy_new_dm9051). This is because
we don t have other choices but the integrated PHY.
• We have to create an SPI device handle firstly and then pass it to the MAC constructor function. More instruc-
tions on creating SPI device handle, please refer to SPI Master.
• The SPI device configuration (i.e. spi_device_interface_config_t) can be different for other Ethernet modules.
Please check out your module s spec and the examples in esp-idf.

Install Driver To install the Ethernet driver, we need to combine the instance of MAC and PHY and set some
additional high-level configurations (i.e. not specific to either MAC or PHY) in esp_eth_config_t:
• mac: instance that created from MAC generator (e.g. esp_eth_mac_new_esp32()).
• phy: instance that created from PHY generator (e.g. esp_eth_phy_new_ip101()).
• check_link_period_ms: Ethernet driver starts an OS timer to check the link status periodically, this
field is used to set the interval, in milliseconds.
• stack_input: In most of Ethernet IoT applications, any Ethernet frame that received by driver
should be passed to upper layer (e.g. TCP/IP stack). This field is set to a function which is re-
sponsible to deal with the incoming frames. You can even update this field at runtime via function
esp_eth_update_input_path() after driver installation.
• on_lowlevel_init_done and on_lowlevel_deinit_done: These two fields are used to specify
the hooks which get invoked when low level hardware has been initialized or de-initialized.
ESP-IDF provides a default configuration for driver installation in macro ETH_DEFAULT_CONFIG.
esp_eth_config_t config = ETH_DEFAULT_CONFIG(mac, phy); // apply default driver␣

,→configuration
esp_eth_handle_t eth_handle = NULL; // after driver installed, we will get the␣

,→handle of the driver
esp_eth_driver_install(&config, &eth_handle); // install driver
Ethernet driver also includes event-driven model, which will send useful and important event to user space. We need to
initialize the event loop before installing the Ethernet driver. For more information about event-driven programming,
please refer to ESP Event.
/** Event handler for Ethernet events */

static void eth_event_handler(void *arg, esp_event_base_t event_base,
int32_t event_id, void *event_data)
{
uint8_t mac_addr[6] = {0};
/* we can get the ethernet driver handle from event data */
esp_eth_handle_t eth_handle = *(esp_eth_handle_t *)event_data;
switch (event_id) {
case ETHERNET_EVENT_CONNECTED:
esp_eth_ioctl(eth_handle, ETH_CMD_G_MAC_ADDR, mac_addr);
ESP_LOGI(TAG, "Ethernet Link Up");
ESP_LOGI(TAG, "Ethernet HW Addr %02x:%02x:%02x:%02x:%02x:%02x",
mac_addr[0], mac_addr[1], mac_addr[2], mac_addr[3], mac_
,→addr[4], mac_addr[5]);
break;
case ETHERNET_EVENT_DISCONNECTED:
ESP_LOGI(TAG, "Ethernet Link Down");
break;
case ETHERNET_EVENT_START:
ESP_LOGI(TAG, "Ethernet Started");
break;
case ETHERNET_EVENT_STOP:
ESP_LOGI(TAG, "Ethernet Stopped");
break;
default:
break;
}
}
esp_event_loop_create_default(); // create a default event loop that running in␣

,→background
esp_event_handler_register(ETH_EVENT, ESP_EVENT_ANY_ID, &eth_event_handler, NULL);␣

,→// register Ethernet event handler (to deal with user specific stuffs when event␣
,→like link up/down happened)

Start Ethernet Driver After driver installation, we can start Ethernet immediately.
esp_eth_start(eth_handle); // start Ethernet driver state machine
Connect Driver to TCP/IP Stack Up until now, we have installed the Ethernet driver. From the view of OSI
(Open System Interconnection), we re still on level 2 (i.e. Data Link Layer). We can detect link up and down event,
we can gain MAC address in user space, but we can t obtain IP address, let alone send HTTP request. The TCP/IP
stack used in ESP-IDF is called LwIP, for more information about it, please refer to LwIP.
To connect Ethernet driver to TCP/IP stack, these three steps need to follow:
1. Create network interface for Ethernet driver
2. Attach the network interface to Ethernet driver
3. Register IP event handlers
More information about network interface, please refer to Network Interface.
/** Event handler for IP_EVENT_ETH_GOT_IP */

static void got_ip_event_handler(void *arg, esp_event_base_t event_base,
{
ip_event_got_ip_t *event = (ip_event_got_ip_t *) event_data;
const esp_netif_ip_info_t *ip_info = &event->ip_info;
ESP_LOGI(TAG, "Ethernet Got IP Address");

ESP_LOGI(TAG, "~~~~~~~~~~~");
ESP_LOGI(TAG, "ETHIP:" IPSTR, IP2STR(&ip_info->ip));
ESP_LOGI(TAG, "ETHMASK:" IPSTR, IP2STR(&ip_info->netmask));
ESP_LOGI(TAG, "ETHGW:" IPSTR, IP2STR(&ip_info->gw));
ESP_LOGI(TAG, "~~~~~~~~~~~");
}
esp_netif_init()); // Initialize TCP/IP network interface (should be called only␣

,→once in application)
esp_netif_config_t cfg = ESP_NETIF_DEFAULT_ETH(); // apply default network␣

,→interface configuration for Ethernet
esp_netif_t *eth_netif = esp_netif_new(&cfg); // create network interface for␣

,→Ethernet driver
esp_netif_attach(eth_netif, esp_eth_new_netif_glue(eth_handle)); // attach␣

,→Ethernet driver to TCP/IP stack
esp_event_handler_register(IP_EVENT, IP_EVENT_ETH_GOT_IP, &got_ip_event_handler,␣

,→NULL); // register user defined IP event handlers
esp_eth_start(eth_handle); // start Ethernet driver state machine
Warning: It is recommended to fully initialize the Ethernet driver and network interface prior registering user
s Ethernet/IP event handlers, i.e. register the event handlers as the last thing prior starting the Ethernet driver.
Such approach ensures that Ethernet/IP events get executed first by the Ethernet driver or network interface and
so the system is in expected state when executing user s handlers.
Misc control of Ethernet driver The following functions should only be invoked after the Ethernet driver has been
installed.
• Stop Ethernet driver: esp_eth_stop()
• Update Ethernet data input path: esp_eth_update_input_path()
• Misc get/set of Ethernet driver attributes: esp_eth_ioctl()

/* get MAC address */

uint8_t mac_addr[6];
memset(mac_addr, 0, sizeof(mac_addr));
esp_eth_ioctl(eth_handle, ETH_CMD_G_MAC_ADDR, mac_addr);
ESP_LOGI(TAG, "Ethernet MAC Address: %02x:%02x:%02x:%02x:%02x:%02x",
mac_addr[0], mac_addr[1], mac_addr[2], mac_addr[3], mac_addr[4], mac_
,→addr[5]);
/* get PHY address */

int phy_addr = -1;
esp_eth_ioctl(eth_handle, ETH_CMD_G_PHY_ADDR, &phy_addr);
ESP_LOGI(TAG, "Ethernet PHY Address: %d", phy_addr);
Flow control Ethernet on MCU usually has a limitation in the number of frames it can handle during network
congestion, because of the limitation in RAM size. A sending station might be transmitting data faster than the
peer end can accept it. Ethernet flow control mechanism allows the receiving node to signal the sender requesting
suspension of transmissions until the receiver catches up. The magic behind that is the pause frame, which was defined
in IEEE 802.3x.
Pause frame is a special Ethernet frame used to carry the pause command, whose EtherType field is 0x8808, with
the Control opcode set to 0x0001. Only stations configured for full-duplex operation may send pause frames. When
a station wishes to pause the other end of a link, it sends a pause frame to the 48-bit reserved multicast address
of 01-80-C2-00-00-01. The pause frame also includes the period of pause time being requested, in the form of a
two-byte integer, ranging from 0 to 65535.
After Ethernet driver installation, the flow control feature is disabled by default. You can enable it by:
bool flow_ctrl_enable = true;

esp_eth_ioctl(eth_handle, ETH_CMD_S_FLOW_CTRL, &flow_ctrl_enable);
One thing should be kept in mind, is that the pause frame ability will be advertised to peer end by PHY during auto
negotiation. Ethernet driver sends pause frame only when both sides of the link support it.
Application Example
• Ethernet basic example: ethernet/basic.
• Ethernet iperf example: ethernet/iperf.
• Ethernet to Wi-Fi AP router : ethernet/eth2ap.
• Most of protocol examples should also work for Ethernet: protocols.
API Reference
Header File
• components/esp_eth/include/esp_eth.h
Functions
esp_err_t esp_eth_driver_install(const esp_eth_config_t *config, esp_eth_handle_t *out_hdl)
Install Ethernet driver.
Return
• ESP_OK: install esp_eth driver successfully
• ESP_ERR_INVALID_ARG: install esp_eth driver failed because of some invalid argument
• ESP_ERR_NO_MEM: install esp_eth driver failed because there s no memory for driver
• ESP_FAIL: install esp_eth driver failed because some other error occurred
Parameters
• [in] config: configuration of the Ethernet driver
• [out] out_hdl: handle of Ethernet driver

esp_err_t esp_eth_driver_uninstall(esp_eth_handle_t hdl)

Uninstall Ethernet driver.
Note It s not recommended to uninstall Ethernet driver unless it won t get used any more in application code.
To uninstall Ethernet driver, you have to make sure, all references to the driver are released. Ethernet
driver can only be uninstalled successfully when reference counter equals to one.
Return
• ESP_OK: uninstall esp_eth driver successfully
• ESP_ERR_INVALID_ARG: uninstall esp_eth driver failed because of some invalid argument
• ESP_ERR_INVALID_STATE: uninstall esp_eth driver failed because it has more than one refer-
ence
• ESP_FAIL: uninstall esp_eth driver failed because some other error occurred
Parameters
• [in] hdl: handle of Ethernet driver
esp_err_t esp_eth_start(esp_eth_handle_t hdl)
Start Ethernet driver ONLY in standalone mode (i.e. without TCP/IP stack)
Note This API will start driver state machine and internal software timer (for checking link status).
Return
• ESP_OK: start esp_eth driver successfully
• ESP_ERR_INVALID_ARG: start esp_eth driver failed because of some invalid argument
• ESP_ERR_INVALID_STATE: start esp_eth driver failed because driver has started already
• ESP_FAIL: start esp_eth driver failed because some other error occurred
Parameters
esp_err_t esp_eth_stop(esp_eth_handle_t hdl)
Stop Ethernet driver.
Note This function does the oppsite operation of esp_eth_start.
Return
• ESP_OK: stop esp_eth driver successfully
• ESP_ERR_INVALID_ARG: stop esp_eth driver failed because of some invalid argument
• ESP_ERR_INVALID_STATE: stop esp_eth driver failed because driver has not started yet
• ESP_FAIL: stop esp_eth driver failed because some other error occurred
Parameters
esp_err_t esp_eth_update_input_path(esp_eth_handle_t hdl, esp_err_t
(*stack_input))esp_eth_handle_t hdl, uint8_t *buffer,
uint32_t length, void *priv
, void *privUpdate Ethernet data input path (i.e. specify where to pass the input buffer)
Note After install driver, Ethernet still don t know where to deliver the input buffer. In fact, this API registers
a callback function which get invoked when Ethernet received new packets.
Return
• ESP_OK: update input path successfully
• ESP_ERR_INVALID_ARG: update input path failed because of some invalid argument
• ESP_FAIL: update input path failed because some other error occurred
Parameters
• [in] stack_input: function pointer, which does the actual process on incoming packets
• [in] priv: private resource, which gets passed to stack_input callback without any modi-
fication
esp_err_t esp_eth_transmit(esp_eth_handle_t hdl, void *buf, size_t length)
General Transmit.
Return
• ESP_OK: transmit frame buffer successfully
• ESP_ERR_INVALID_ARG: transmit frame buffer failed because of some invalid argument
• ESP_FAIL: transmit frame buffer failed because some other error occurred

Parameters
• [in] buf: buffer of the packet to transfer
• [in] length: length of the buffer to transfer
esp_err_t esp_eth_receive(esp_eth_handle_t hdl, uint8_t *buf, uint32_t *length)
General Receive is deprecated and shall not be accessed from app code, as polling is not supported by Ethernet.
Note Before this function got invoked, the value of length should set by user, equals the size of buffer.
After the function returned, the value of length means the real length of received data.
Note This API was exposed by accident, users should not use this API in their applications. Ethernet driver
is interrupt driven, and doesn t support polling mode. Instead, users should register input callback with
esp_eth_update_input_path.
Return
• ESP_OK: receive frame buffer successfully
• ESP_ERR_INVALID_ARG: receive frame buffer failed because of some invalid argument
• ESP_ERR_INVALID_SIZE: input buffer size is not enough to hold the incoming data. in this case,
value of returned length indicates the real size of incoming data.
• ESP_FAIL: receive frame buffer failed because some other error occurred
Parameters
• [out] buf: buffer to preserve the received packet
• [out] length: length of the received packet
esp_err_t esp_eth_ioctl(esp_eth_handle_t hdl, esp_eth_io_cmd_t cmd, void *data)
Misc IO function of Etherent driver.
The following IO control commands are supported:
• ETH_CMD_S_MAC_ADDR sets Ethernet interface MAC address. data argument is pointer to MAC
address buffer with expected size of 6 bytes.
• ETH_CMD_G_MAC_ADDR gets Ethernet interface MAC address. data argument is pointer to a buffer
to which MAC address is to be copied. The buffer size must be at least 6 bytes.
• ETH_CMD_S_PHY_ADDR sets PHY address in range of <0-31>. data argument is pointer to memory
of uint32_t datatype from where the configuration option is read.
• ETH_CMD_G_PHY_ADDR gets PHY address. data argument is pointer to memory of uint32_t
datatype to which the PHY address is to be stored.
• ETH_CMD_S_AUTONEGO enables or disables Ethernet link speed and duplex mode autonegotiation.
data argument is pointer to memory of bool datatype from which the configuration option is read.
Preconditions: Ethernet driver needs to be stopped.
• ETH_CMD_G_AUTONEGO gets current configuration of the Ethernet link speed and duplex mode au-
tonegotiation. data argument is pointer to memory of bool datatype to which the current configuration
is to be stored.
• ETH_CMD_S_SPEED sets the Ethernet link speed. data argument is pointer to memory of eth_speed_t
datatype from which the configuration option is read. Preconditions: Ethernet driver needs to be stopped
and auto-negotiation disabled.
• ETH_CMD_G_SPEED gets current Ethernet link speed. data argument is pointer to memory of
eth_speed_t datatype to which the speed is to be stored.
• ETH_CMD_S_PROMISCUOUS sets/resets Ethernet interface promiscuous mode. data argument is
pointer to memory of bool datatype from which the configuration option is read.
• ETH_CMD_S_FLOW_CTRL sets/resets Ethernet interface flow control. data argument is pointer to
memory of bool datatype from which the configuration option is read.
• ETH_CMD_S_DUPLEX_MODE sets the Ethernet duplex mode. data argument is pointer to memory of
eth_duplex_t datatype from which the configuration option is read. Preconditions: Ethernet driver needs
to be stopped and auto-negotiation disabled.
• ETH_CMD_G_DUPLEX_MODE gets current Ethernet link duplex mode. data argument is pointer to
memory of eth_duplex_t datatype to which the duplex mode is to be stored.
• ETH_CMD_S_PHY_LOOPBACK sets/resets PHY to/from loopback mode. data argument is pointer
to memory of bool datatype from which the configuration option is read.
Return

• ESP_OK: process io command successfully

• ESP_ERR_INVALID_ARG: process io command failed because of some invalid argument
• ESP_FAIL: process io command failed because some other error occurred
• ESP_ERR_NOT_SUPPORTED: requested feature is not supported
Parameters
• [in] cmd: IO control command
• [inout] data: address of data for set command or address where to store the data when used
with get command
esp_err_t esp_eth_increase_reference(esp_eth_handle_t hdl)
Increase Ethernet driver reference.
Note Ethernet driver handle can be obtained by os timer, netif, etc. It s dangerous when thread A is us-
ing Ethernet but thread B uninstall the driver. Using reference counter can prevent such risk, but care
should be taken, when you obtain Ethernet driver, this API must be invoked so that the driver won t be
uninstalled during your using time.
Return
• ESP_OK: increase reference successfully
• ESP_ERR_INVALID_ARG: increase reference failed because of some invalid argument
Parameters
esp_err_t esp_eth_decrease_reference(esp_eth_handle_t hdl)
Decrease Ethernet driver reference.
Return
• ESP_OK: increase reference successfully
• ESP_ERR_INVALID_ARG: increase reference failed because of some invalid argument
Parameters
Structures
struct esp_eth_config_t
Configuration of Ethernet driver.
Public Members
esp_eth_mac_t *mac
Ethernet MAC object.
esp_eth_phy_t *phy
Ethernet PHY object.
uint32_t check_link_period_ms
Period time of checking Ethernet link status.
bool auto_nego_en
Configuration status of PHY autonegotiation feature.
esp_err_t (*stack_input)(esp_eth_handle_t eth_handle, uint8_t *buffer, uint32_t length, void
*priv)
Input frame buffer to user s stack.
Return
• ESP_OK: input frame buffer to upper stack successfully
• ESP_FAIL: error occurred when inputting buffer to upper stack
Parameters
• [in] eth_handle: handle of Ethernet driver
• [in] buffer: frame buffer that will get input to upper stack
• [in] length: length of the frame buffer

esp_err_t (*on_lowlevel_init_done)(esp_eth_handle_t eth_handle)

Callback function invoked when lowlevel initialization is finished.
Return
• ESP_OK: process extra lowlevel initialization successfully
• ESP_FAIL: error occurred when processing extra lowlevel initialization
Parameters
esp_err_t (*on_lowlevel_deinit_done)(esp_eth_handle_t eth_handle)
Callback function invoked when lowlevel deinitialization is finished.
Return
• ESP_OK: process extra lowlevel deinitialization successfully
• ESP_FAIL: error occurred when processing extra lowlevel deinitialization
Parameters
esp_err_t (*read_phy_reg)(esp_eth_handle_t eth_handle, uint32_t phy_addr, uint32_t phy_reg,
uint32_t *reg_value)
Read PHY register.
Note Usually the PHY register read/write function is provided by MAC (SMI interface), but if the PHY
device is managed by other interface (e.g. I2C), then user needs to implement the corresponding
read/write. Setting this to NULL means your PHY device is managed by MAC s SMI interface.
Return
• ESP_OK: read PHY register successfully
• ESP_ERR_INVALID_ARG: read PHY register failed because of invalid argument
• ESP_ERR_TIMEOUT: read PHY register failed because of timeout
• ESP_FAIL: read PHY register failed because some other error occurred
Parameters
• [in] phy_addr: PHY chip address (0~31)
• [in] phy_reg: PHY register index code
• [out] reg_value: PHY register value
esp_err_t (*write_phy_reg)(esp_eth_handle_t eth_handle, uint32_t phy_addr, uint32_t phy_reg,
uint32_t reg_value)
Write PHY register.
Note Usually the PHY register read/write function is provided by MAC (SMI interface), but if the PHY
device is managed by other interface (e.g. I2C), then user needs to implement the corresponding
read/write. Setting this to NULL means your PHY device is managed by MAC s SMI interface.
Return
• ESP_OK: write PHY register successfully
• ESP_ERR_TIMEOUT: write PHY register failed because of timeout
• ESP_FAIL: write PHY register failed because some other error occurred
Parameters
• [in] reg_value: PHY register value
Macros
ETH_DEFAULT_CONFIG(emac, ephy)
Default configuration for Ethernet driver.
Type Definitions
typedef void *esp_eth_handle_t
Handle of Ethernet driver.

Header File
• components/esp_eth/include/esp_eth_com.h
Functions
esp_err_t esp_eth_detect_phy_addr(esp_eth_mediator_t *eth, int *detected_addr)
Detect PHY address.
Return
• ESP_OK: detect phy address successfully
• ESP_ERR_INVALID_ARG: invalid parameter
• ESP_ERR_NOT_FOUND: can t detect any PHY device
• ESP_FAIL: detect phy address failed because some error occurred
Parameters
• [in] eth: mediator of Ethernet driver
• [out] detected_addr: a valid address after detection
Structures
struct esp_eth_mediator_s
Ethernet mediator.
Public Members
esp_err_t (*phy_reg_read)(esp_eth_mediator_t *eth, uint32_t phy_addr, uint32_t phy_reg,

uint32_t *reg_value)
Read PHY register.
Return
• ESP_FAIL: read PHY register failed because some error occurred
Parameters
• [in] phy_addr: PHY Chip address (0~31)
esp_err_t (*phy_reg_write)(esp_eth_mediator_t *eth, uint32_t phy_addr, uint32_t phy_reg,
uint32_t reg_value)
Write PHY register.
Return
• ESP_FAIL: write PHY register failed because some error occurred
Parameters
• [in] phy_addr: PHY Chip address (0~31)
esp_err_t (*stack_input)(esp_eth_mediator_t *eth, uint8_t *buffer, uint32_t length)
Deliver packet to upper stack.
Return
• ESP_OK: deliver packet to upper stack successfully
• ESP_FAIL: deliver packet failed because some error occurred
Parameters
• [in] buffer: packet buffer
• [in] length: length of the packet

esp_err_t (*on_state_changed)(esp_eth_mediator_t *eth, esp_eth_state_t state, void *args)

Callback on Ethernet state changed.
Return
• ESP_OK: process the new state successfully
• ESP_FAIL: process the new state failed because some error occurred
Parameters
• [in] state: new state
• [in] args: optional argument for the new state
Macros
ETH_MAX_PAYLOAD_LEN
Maximum Ethernet payload size.
ETH_MIN_PAYLOAD_LEN
Minimum Ethernet payload size.
ETH_HEADER_LEN
Ethernet frame header size: Dest addr(6 Bytes) + Src addr(6 Bytes) + length/type(2 Bytes)
ETH_VLAN_TAG_LEN
Optional 802.1q VLAN Tag length.
ETH_JUMBO_FRAME_PAYLOAD_LEN
Jumbo frame payload size.
ETH_MAX_PACKET_SIZE
Maximum frame size (1522 Bytes)
ETH_MIN_PACKET_SIZE
Minimum frame size (64 Bytes)
Type Definitions
typedef struct esp_eth_mediator_s esp_eth_mediator_t
Ethernet mediator.
Enumerations
enum esp_eth_state_t
Ethernet driver state.
Values:
ETH_STATE_LLINIT
Lowlevel init done
ETH_STATE_DEINIT
Deinit done
ETH_STATE_LINK
Link status changed
ETH_STATE_SPEED
Speed updated
ETH_STATE_DUPLEX
Duplex updated
ETH_STATE_PAUSE
Pause ability updated
enum esp_eth_io_cmd_t
Command list for ioctl API.
Values:

ETH_CMD_G_MAC_ADDR
Get MAC address
ETH_CMD_S_MAC_ADDR
Set MAC address
ETH_CMD_G_PHY_ADDR
Get PHY address
ETH_CMD_S_PHY_ADDR
Set PHY address
ETH_CMD_G_AUTONEGO
Get PHY Auto Negotiation
ETH_CMD_S_AUTONEGO
Set PHY Auto Negotiation
ETH_CMD_G_SPEED
Get Speed
ETH_CMD_S_SPEED
Set Speed
ETH_CMD_S_PROMISCUOUS
Set promiscuous mode
ETH_CMD_S_FLOW_CTRL
Set flow control
ETH_CMD_G_DUPLEX_MODE
Get Duplex mode
ETH_CMD_S_DUPLEX_MODE
Set Duplex mode
ETH_CMD_S_PHY_LOOPBACK
Set PHY loopback
enum eth_event_t
Ethernet event declarations.
Values:
ETHERNET_EVENT_START
Ethernet driver start
ETHERNET_EVENT_STOP
Ethernet driver stop
ETHERNET_EVENT_CONNECTED
Ethernet got a valid link
ETHERNET_EVENT_DISCONNECTED
Ethernet lost a valid link
Header File
• components/esp_eth/include/esp_eth_mac.h
Functions
esp_eth_mac_t *esp_eth_mac_new_esp32(const eth_mac_config_t *config)
Create ESP32 Ethernet MAC instance.
Return
• instance: create MAC instance successfully
• NULL: create MAC instance failed because some error occurred

Parameters
• config: Ethernet MAC configuration
Unions
union eth_mac_clock_config_t
#include <esp_eth_mac.h> Ethernet MAC Clock Configuration.
Public Members
struct eth_mac_clock_config_t::[anonymous] mii

EMAC MII Clock Configuration
emac_rmii_clock_mode_t clock_mode
RMII Clock Mode Configuration
emac_rmii_clock_gpio_t clock_gpio
RMII Clock GPIO Configuration
struct eth_mac_clock_config_t::[anonymous] rmii
EMAC RMII Clock Configuration
Structures
struct esp_eth_mac_s
Ethernet MAC.
Public Members
esp_err_t (*set_mediator)(esp_eth_mac_t *mac, esp_eth_mediator_t *eth)

Set mediator for Ethernet MAC.
Return
• ESP_OK: set mediator for Ethernet MAC successfully
• ESP_ERR_INVALID_ARG: set mediator for Ethernet MAC failed because of invalid argu-
ment
Parameters
• [in] mac: Ethernet MAC instance
• [in] eth: Ethernet mediator
esp_err_t (*init)(esp_eth_mac_t *mac)
Initialize Ethernet MAC.
Return
• ESP_OK: initialize Ethernet MAC successfully
• ESP_ERR_TIMEOUT: initialize Ethernet MAC failed because of timeout
• ESP_FAIL: initialize Ethernet MAC failed because some other error occurred
Parameters
esp_err_t (*deinit)(esp_eth_mac_t *mac)
Deinitialize Ethernet MAC.
Return
• ESP_OK: deinitialize Ethernet MAC successfully
• ESP_FAIL: deinitialize Ethernet MAC failed because some error occurred
Parameters
esp_err_t (*start)(esp_eth_mac_t *mac)
Start Ethernet MAC.

Return
• ESP_OK: start Ethernet MAC successfully
• ESP_FAIL: start Ethernet MAC failed because some other error occurred
Parameters
esp_err_t (*stop)(esp_eth_mac_t *mac)
Stop Ethernet MAC.
Return
• ESP_OK: stop Ethernet MAC successfully
• ESP_FAIL: stop Ethernet MAC failed because some error occurred
Parameters
esp_err_t (*transmit)(esp_eth_mac_t *mac, uint8_t *buf, uint32_t length)
Transmit packet from Ethernet MAC.
Return
• ESP_OK: transmit packet successfully
• ESP_ERR_INVALID_ARG: transmit packet failed because of invalid argument
• ESP_ERR_INVALID_STATE: transmit packet failed because of wrong state of MAC
• ESP_FAIL: transmit packet failed because some other error occurred
Parameters
• [in] buf: packet buffer to transmit
• [in] length: length of packet
esp_err_t (*receive)(esp_eth_mac_t *mac, uint8_t *buf, uint32_t *length)
Receive packet from Ethernet MAC.
Note Memory of buf is allocated in the Layer2, make sure it get free after process.
Note Before this function got invoked, the value of length should set by user, equals the size of buffer.
After the function returned, the value of length means the real length of received data.
Return
• ESP_OK: receive packet successfully
• ESP_ERR_INVALID_ARG: receive packet failed because of invalid argument
• ESP_ERR_INVALID_SIZE: input buffer size is not enough to hold the incoming data. in this
case, value of returned length indicates the real size of incoming data.
• ESP_FAIL: receive packet failed because some other error occurred
Parameters
• [out] buf: packet buffer which will preserve the received frame
• [out] length: length of the received packet
esp_err_t (*read_phy_reg)(esp_eth_mac_t *mac, uint32_t phy_addr, uint32_t phy_reg, uint32_t
*reg_value)
Read PHY register.
Return
• ESP_ERR_INVALID_STATE: read PHY register failed because of wrong state of MAC
• ESP_ERR_TIMEOUT: read PHY register failed because of timeout
• ESP_FAIL: read PHY register failed because some other error occurred
Parameters
esp_err_t (*write_phy_reg)(esp_eth_mac_t *mac, uint32_t phy_addr, uint32_t phy_reg, uint32_t
reg_value)

Write PHY register.

Return
• ESP_ERR_INVALID_STATE: write PHY register failed because of wrong state of MAC
• ESP_ERR_TIMEOUT: write PHY register failed because of timeout
• ESP_FAIL: write PHY register failed because some other error occurred
Parameters
esp_err_t (*set_addr)(esp_eth_mac_t *mac, uint8_t *addr)
Set MAC address.
Return
• ESP_OK: set MAC address successfully
• ESP_ERR_INVALID_ARG: set MAC address failed because of invalid argument
• ESP_FAIL: set MAC address failed because some other error occurred
Parameters
• [in] addr: MAC address
esp_err_t (*get_addr)(esp_eth_mac_t *mac, uint8_t *addr)
Get MAC address.
Return
• ESP_OK: get MAC address successfully
• ESP_ERR_INVALID_ARG: get MAC address failed because of invalid argument
• ESP_FAIL: get MAC address failed because some other error occurred
Parameters
• [out] addr: MAC address
esp_err_t (*set_speed)(esp_eth_mac_t *mac, eth_speed_t speed)
Set speed of MAC.
Return
• ESP_OK: set MAC speed successfully
• ESP_ERR_INVALID_ARG: set MAC speed failed because of invalid argument
• ESP_FAIL: set MAC speed failed because some other error occurred
Parameters
• [in] ma:c: Ethernet MAC instance
• [in] speed: MAC speed
esp_err_t (*set_duplex)(esp_eth_mac_t *mac, eth_duplex_t duplex)
Set duplex mode of MAC.
Return
• ESP_OK: set MAC duplex mode successfully
• ESP_ERR_INVALID_ARG: set MAC duplex failed because of invalid argument
• ESP_FAIL: set MAC duplex failed because some other error occurred
Parameters
• [in] duplex: MAC duplex
esp_err_t (*set_link)(esp_eth_mac_t *mac, eth_link_t link)
Set link status of MAC.
Return
• ESP_OK: set link status successfully
• ESP_ERR_INVALID_ARG: set link status failed because of invalid argument
• ESP_FAIL: set link status failed because some other error occurred

Parameters
• [in] link: Link status
esp_err_t (*set_promiscuous)(esp_eth_mac_t *mac, bool enable)
Set promiscuous of MAC.
Return
• ESP_OK: set promiscuous mode successfully
• ESP_FAIL: set promiscuous mode failed because some error occurred
Parameters
• [in] enable: set true to enable promiscuous mode; set false to disable promiscuous mode
esp_err_t (*enable_flow_ctrl)(esp_eth_mac_t *mac, bool enable)
Enable flow control on MAC layer or not.
Return
• ESP_OK: set flow control successfully
• ESP_FAIL: set flow control failed because some error occurred
Parameters
• [in] enable: set true to enable flow control; set false to disable flow control
esp_err_t (*set_peer_pause_ability)(esp_eth_mac_t *mac, uint32_t ability)
Set the PAUSE ability of peer node.
Return
• ESP_OK: set peer pause ability successfully
• ESP_FAIL: set peer pause ability failed because some error occurred
Parameters
• [in] ability: zero indicates that pause function is supported by link partner; non-zero
indicates that pause function is not supported by link partner
esp_err_t (*del)(esp_eth_mac_t *mac)
Free memory of Ethernet MAC.
Return
• ESP_OK: free Ethernet MAC instance successfully
• ESP_FAIL: free Ethernet MAC instance failed because some error occurred
Parameters
struct eth_mac_config_t
Configuration of Ethernet MAC object.
Public Members
uint32_t sw_reset_timeout_ms
Software reset timeout value (Unit: ms)
uint32_t rx_task_stack_size
Stack size of the receive task
uint32_t rx_task_prio
Priority of the receive task
int smi_mdc_gpio_num
SMI MDC GPIO number, set to -1 could bypass the SMI GPIO configuration
int smi_mdio_gpio_num
SMI MDIO GPIO number, set to -1 could bypass the SMI GPIO configuration

uint32_t flags
Flags that specify extra capability for mac driver
eth_data_interface_t interface
EMAC Data interface to PHY (MII/RMII)
eth_mac_clock_config_t clock_config
EMAC Interface clock configuration
Macros
ETH_MAC_FLAG_WORK_WITH_CACHE_DISABLE
MAC driver can work when cache is disabled
ETH_MAC_FLAG_PIN_TO_CORE
Pin MAC task to the CPU core where driver installation happened
ETH_MAC_DEFAULT_CONFIG()
Default configuration for Ethernet MAC object.
Type Definitions
typedef struct esp_eth_mac_s esp_eth_mac_t
Ethernet MAC.
Enumerations
enum emac_rmii_clock_mode_t
RMII Clock Mode Options.
Values:
EMAC_CLK_DEFAULT
Default values configured using Kconfig are going to be used when Default selected.
EMAC_CLK_EXT_IN
Input RMII Clock from external. EMAC Clock GPIO number needs to be configured when this option
is selected.
Note MAC will get RMII clock from outside. Note that ESP32 only supports GPIO0 to input the RMII
clock.
EMAC_CLK_OUT
Output RMII Clock from internal APLL Clock. EMAC Clock GPIO number needs to be configured
when this option is selected.
enum emac_rmii_clock_gpio_t
RMII Clock GPIO number Options.
Values:
EMAC_CLK_IN_GPIO = 0
MAC will get RMII clock from outside at this GPIO.
Note ESP32 only supports GPIO0 to input the RMII clock.
EMAC_APPL_CLK_OUT_GPIO = 0
Output RMII Clock from internal APLL Clock available at GPIO0.
Note GPIO0 can be set to output a pre-divided PLL clock (test only!). Enabling this option will configure
GPIO0 to output a 50MHz clock. In fact this clock doesn t have directly relationship with EMAC
peripheral. Sometimes this clock won t work well with your PHY chip. You might need to add
some extra devices after GPIO0 (e.g. inverter). Note that outputting RMII clock on GPIO0 is an
experimental practice. If you want the Ethernet to work with WiFi, don t select GPIO0 output
mode for stability.
EMAC_CLK_OUT_GPIO = 16
Output RMII Clock from internal APLL Clock available at GPIO16.

EMAC_CLK_OUT_180_GPIO = 17
Inverted Output RMII Clock from internal APLL Clock available at GPIO17.
Header File
• components/esp_eth/include/esp_eth_phy.h
Functions
esp_eth_phy_t *esp_eth_phy_new_ip101(const eth_phy_config_t *config)
Create a PHY instance of IP101.
Return
• instance: create PHY instance successfully
• NULL: create PHY instance failed because some error occurred
Parameters
• [in] config: configuration of PHY
esp_eth_phy_t *esp_eth_phy_new_rtl8201(const eth_phy_config_t *config)
Create a PHY instance of RTL8201.
Return
Parameters
esp_eth_phy_t *esp_eth_phy_new_lan87xx(const eth_phy_config_t *config)
Create a PHY instance of LAN87xx.
Return
Parameters
static esp_eth_phy_t *esp_eth_phy_new_lan8720(const eth_phy_config_t *config)
Create a PHY instance of LAN8720.
Note For ESP-IDF backwards compatibility reasons. In all other cases, use esp_eth_phy_new_lan87xx in-
stead.
Return
Parameters
esp_eth_phy_t *esp_eth_phy_new_dp83848(const eth_phy_config_t *config)
Create a PHY instance of DP83848.
Return
Parameters
esp_eth_phy_t *esp_eth_phy_new_ksz8041(const eth_phy_config_t *config)
Create a PHY instance of KSZ8041.
Return
Parameters

esp_eth_phy_t *esp_eth_phy_new_ksz8081(const eth_phy_config_t *config)

Return
Parameters
static esp_eth_phy_t *esp_eth_phy_new_ksz8091(const eth_phy_config_t *config)
Return
Parameters
Structures
struct esp_eth_phy_s
Ethernet PHY.
Public Members
esp_err_t (*set_mediator)(esp_eth_phy_t *phy, esp_eth_mediator_t *mediator)

Set mediator for PHY.
Return
• ESP_OK: set mediator for Ethernet PHY instance successfully
• ESP_ERR_INVALID_ARG: set mediator for Ethernet PHY instance failed because of some
invalid arguments
Parameters
• [in] phy: Ethernet PHY instance
• [in] mediator: mediator of Ethernet driver
esp_err_t (*reset)(esp_eth_phy_t *phy)
Software Reset Ethernet PHY.
Return
• ESP_OK: reset Ethernet PHY successfully
• ESP_FAIL: reset Ethernet PHY failed because some error occurred
Parameters
esp_err_t (*reset_hw)(esp_eth_phy_t *phy)
Hardware Reset Ethernet PHY.
Note Hardware reset is mostly done by pull down and up PHY s nRST pin
Return
• ESP_OK: reset Ethernet PHY successfully
• ESP_FAIL: reset Ethernet PHY failed because some error occurred
Parameters
esp_err_t (*init)(esp_eth_phy_t *phy)
Initialize Ethernet PHY.
Return
• ESP_OK: initialize Ethernet PHY successfully
• ESP_FAIL: initialize Ethernet PHY failed because some error occurred
Parameters

esp_err_t (*deinit)(esp_eth_phy_t *phy)

Deinitialize Ethernet PHY.
Return
• ESP_OK: deinitialize Ethernet PHY successfully
• ESP_FAIL: deinitialize Ethernet PHY failed because some error occurred
Parameters
esp_err_t (*autonego_ctrl)(esp_eth_phy_t *phy, eth_phy_autoneg_cmd_t cmd, bool *au-
tonego_en_stat)
Configure auto negotiation.
Return
• ESP_OK: restart auto negotiation successfully
• ESP_FAIL: restart auto negotiation failed because some error occurred
• ESP_ERR_INVALID_ARG: invalid command
Parameters
• [in] cmd: Configuration command, it is possible to Enable (restart), Disable or get current
status of PHY auto negotiation
• [out] autonego_en_stat: Address where to store current status of auto negotiation
configuration
esp_err_t (*get_link)(esp_eth_phy_t *phy)
Get Ethernet PHY link status.
Return
• ESP_OK: get Ethernet PHY link status successfully
• ESP_FAIL: get Ethernet PHY link status failed because some error occurred
Parameters
esp_err_t (*pwrctl)(esp_eth_phy_t *phy, bool enable)
Power control of Ethernet PHY.
Return
• ESP_OK: control Ethernet PHY power successfully
• ESP_FAIL: control Ethernet PHY power failed because some error occurred
Parameters
• [in] enable: set true to power on Ethernet PHY; ser false to power off Ethernet PHY
esp_err_t (*set_addr)(esp_eth_phy_t *phy, uint32_t addr)
Set PHY chip address.
Return
• ESP_OK: set Ethernet PHY address successfully
• ESP_FAIL: set Ethernet PHY address failed because some error occurred
Parameters
• [in] addr: PHY chip address
esp_err_t (*get_addr)(esp_eth_phy_t *phy, uint32_t *addr)
Get PHY chip address.
Return
• ESP_OK: get Ethernet PHY address successfully
• ESP_ERR_INVALID_ARG: get Ethernet PHY address failed because of invalid argument
Parameters
• [out] addr: PHY chip address

esp_err_t (*advertise_pause_ability)(esp_eth_phy_t *phy, uint32_t ability)

Advertise pause function supported by MAC layer.
Return
• ESP_OK: Advertise pause ability successfully
• ESP_ERR_INVALID_ARG: Advertise pause ability failed because of invalid argument
Parameters
• [out] addr: Pause ability
esp_err_t (*loopback)(esp_eth_phy_t *phy, bool enable)
Sets the PHY to loopback mode.
Return
• ESP_OK: PHY instance loopback mode has been configured successfully
• ESP_FAIL: PHY instance loopback configuration failed because some error occurred
Parameters
• [in] enable: enables or disables PHY loopback
esp_err_t (*set_speed)(esp_eth_phy_t *phy, eth_speed_t speed)
Sets PHY speed mode.
Note Autonegotiation feature needs to be disabled prior to calling this function for the new setting to be
applied
Return
• ESP_OK: PHY instance speed mode has been configured successfully
• ESP_FAIL: PHY instance speed mode configuration failed because some error occurred
Parameters
• [in] speed: Speed mode to be set
esp_err_t (*set_duplex)(esp_eth_phy_t *phy, eth_duplex_t duplex)
Sets PHY duplex mode.
Note Autonegotiation feature needs to be disabled prior to calling this function for the new setting to be
applied
Return
• ESP_OK: PHY instance duplex mode has been configured successfully
• ESP_FAIL: PHY instance duplex mode configuration failed because some error occurred
Parameters
• [in] duplex: Duplex mode to be set
esp_err_t (*del)(esp_eth_phy_t *phy)
Free memory of Ethernet PHY instance.
Return
• ESP_OK: free PHY instance successfully
• ESP_FAIL: free PHY instance failed because some error occurred
Parameters
struct eth_phy_config_t
Ethernet PHY configuration.
Public Members
int32_t phy_addr
PHY address, set -1 to enable PHY address detection at initialization stage
uint32_t reset_timeout_ms
Reset timeout value (Unit: ms)

uint32_t autonego_timeout_ms
Auto-negotiation timeout value (Unit: ms)
int reset_gpio_num
Reset GPIO number, -1 means no hardware reset
Macros
ESP_ETH_PHY_ADDR_AUTO
ETH_PHY_DEFAULT_CONFIG()
Default configuration for Ethernet PHY object.
Type Definitions
typedef struct esp_eth_phy_s esp_eth_phy_t
Ethernet PHY.
Enumerations
enum eth_phy_autoneg_cmd_t
Auto-negotiation controll commands.
Values:
ESP_ETH_PHY_AUTONEGO_RESTART
ESP_ETH_PHY_AUTONEGO_EN
ESP_ETH_PHY_AUTONEGO_DIS
ESP_ETH_PHY_AUTONEGO_G_STAT
Header File
• components/esp_eth/include/esp_eth_netif_glue.h
Functions
esp_eth_netif_glue_handle_t esp_eth_new_netif_glue(esp_eth_handle_t eth_hdl)
Create a netif glue for Ethernet driver.
Note netif glue is used to attach io driver to TCP/IP netif
Return glue object, which inherits esp_netif_driver_base_t
Parameters
• eth_hdl: Ethernet driver handle
esp_err_t esp_eth_del_netif_glue(esp_eth_netif_glue_handle_t eth_netif_glue)
Delete netif glue of Ethernet driver.
Return -ESP_OK: delete netif glue successfully
Parameters
• eth_netif_glue: netif glue
esp_err_t esp_eth_set_default_handlers(void *esp_netif)
Register default IP layer handlers for Ethernet.
Note : Ethernet handle might not yet properly initialized when setting up these default handlers
Warning : This function is deprecated and is kept here only for compatibility reasons. Registration of default
IP layer handlers for Ethernet is now handled automatically. Do not call this function if you want to use
multiple Ethernet instances at a time.
Return
• ESP_ERR_INVALID_ARG: invalid parameter (esp_netif is NULL)
• ESP_OK: set default IP layer handlers successfully
• others: other failure occurred during register esp_event handler
Parameters

• [in] esp_netif: esp network interface handle created for Ethernet driver
esp_err_t esp_eth_clear_default_handlers(void *esp_netif)
Unregister default IP layer handlers for Ethernet.
Warning : This function is deprecated and is kept here only for compatibility reasons. Unregistration
of default IP layer handlers for Ethernet is now handled automatically if not registered by calling
esp_eth_set_default_handlers.
Return
• ESP_ERR_INVALID_ARG: invalid parameter (esp_netif is NULL)
• ESP_OK: clear default IP layer handlers successfully
• others: other failure occurred during unregister esp_event handler
Parameters
• [in] esp_netif: esp network interface handle created for Ethernet driver
Type Definitions
typedef struct esp_eth_netif_glue_t *esp_eth_netif_glue_handle_t
Handle of netif glue - an intermediate layer between netif and Ethernet driver.
Code examples for the Ethernet API are provided in the ethernet directory of ESP-IDF examples.
2.2.3 Thread
Thread
Introduction Thread is a IP-based mesh networking protocol. It s based on the 802.15.4 physical and MAC
layer.
Application Examples The openthread directory of ESP-IDF examples contains the following applications:
• The OpenThread interactive shell openthread/ot_cli.
• The Thread border router openthread/ot_br.
• The Thread radio co-processor openthread/ot_rcp.
API Reference For manipulating the Thread network, the OpenThread api shall be used. The OpenThread api
docs can be found at the OpenThread official website.
ESP-IDF provides extra apis for launching and managing the OpenThread stack, binding to network interfaces and
border routing features.
Header File
• components/openthread/include/esp_openthread.h
Functions
esp_err_t esp_openthread_init(const esp_openthread_platform_config_t *init_config)
Initializes the full OpenThread stack.
Note The OpenThread instance will also be initialized in this function.
Return
• ESP_OK on success
• ESP_ERR_NO_MEM if allocation has failed
• ESP_ERR_INVALID_ARG if radio or host connection mode not supported
• ESP_ERR_INVALID_STATE if already initialized
Parameters
• [in] init_config: The initialization configuration.
esp_err_t esp_openthread_launch_mainloop(void)
Launches the OpenThread main loop.

Note Thie function will not return unless error happens when running the OpenThread stack.
Return
• ESP_FAIL on other failures
esp_err_t esp_openthread_deinit(void)
This function performs OpenThread stack and platform driver deinitialization.
Return
• ESP_ERR_INVALID_STATE if not initialized
otInstance *esp_openthread_get_instance(void)
This function acquires the underlying OpenThread instance.
Note This function can be called on other tasks without lock.
Return The OpenThread instance pointer
Header File
• components/openthread/include/esp_openthread_types.h
Structures
struct esp_openthread_mainloop_context_t
This structure represents a context for a select() based mainloop.
Public Members
fd_set read_fds
The read file descriptors
fd_set write_fds
The write file descriptors
fd_set error_fds
The error file descriptors
int max_fd
The max file descriptor
struct timeval timeout
The timeout
struct esp_openthread_uart_config_t
The uart port config for OpenThread.
Public Members
uart_port_t port
UART port number
uart_config_t uart_config
UART configuration, see uart_config_t docs
int rx_pin
UART RX pin
int tx_pin
UART TX pin
struct esp_openthread_radio_config_t
The OpenThread radio configuration.

Public Members
esp_openthread_radio_mode_t radio_mode
The radio mode
esp_openthread_uart_config_t radio_uart_config
The uart configuration to RCP
struct esp_openthread_host_connection_config_t
The OpenThread host connection configuration.
Public Members
esp_openthread_host_connection_mode_t host_connection_mode
The host connection mode
esp_openthread_uart_config_t host_uart_config
The uart configuration to host
struct esp_openthread_port_config_t
The OpenThread port specific configuration.
Public Members
const char *storage_partition_name

The partition for storing OpenThread dataset
uint8_t netif_queue_size
The packet queue size for the network interface
uint8_t task_queue_size
The task queue size
struct esp_openthread_platform_config_t
The OpenThread platform configuration.
Public Members
esp_openthread_radio_config_t radio_config
The radio configuration
esp_openthread_host_connection_config_t host_config
The host connection configuration
esp_openthread_port_config_t port_config
The port configuration
Enumerations
enum esp_openthread_event_t
OpenThread event declarations.
Values:
OPENTHREAD_EVENT_START
OpenThread stack start
OPENTHREAD_EVENT_STOP
OpenThread stack stop
OPENTHREAD_EVENT_IF_UP
OpenThread network interface up

OPENTHREAD_EVENT_IF_DOWN
OpenThread network interface down
OPENTHREAD_EVENT_GOT_IP6
OpenThread stack added IPv6 address
OPENTHREAD_EVENT_LOST_IP6
OpenThread stack removed IPv6 address
OPENTHREAD_EVENT_MULTICAST_GROUP_JOIN
OpenThread stack joined IPv6 multicast group
OPENTHREAD_EVENT_MULTICAST_GROUP_LEAVE
OpenThread stack left IPv6 multicast group
OPENTHREAD_EVENT_TREL_ADD_IP6
OpenThread stack added TREL IPv6 address
OPENTHREAD_EVENT_TREL_REMOVE_IP6
OpenThread stack removed TREL IPv6 address
OPENTHREAD_EVENT_TREL_MULTICAST_GROUP_JOIN
OpenThread stack joined TREL IPv6 multicast group
enum esp_openthread_radio_mode_t
The radio mode of OpenThread.
Values:
RADIO_MODE_NATIVE = 0x0
Use the native 15.4 radio
RADIO_MODE_UART_RCP = 0x1
UART connection to a 15.4 capable radio co-processor (RCP)
RADIO_MODE_SPI_RCP = 0x2
SPI connection to a 15.4 capable radio co-processor (RCP)
enum esp_openthread_host_connection_mode_t
How OpenThread connects to the host.
Values:
HOST_CONNECTION_MODE_NONE = 0x0
Disable host connection
HOST_CONNECTION_MODE_CLI_UART = 0x1
CLI UART connection to the host
HOST_CONNECTION_MODE_RCP_UART = 0x2
RCP UART connection to the host
Header File
• components/openthread/include/esp_openthread_lock.h
Functions
esp_err_t esp_openthread_lock_init(void)
This function initializes the OpenThread API lock.
Return
void esp_openthread_lock_deinit(void)
This function deinitializes the OpenThread API lock.

bool esp_openthread_lock_acquire(TickType_t block_ticks)

This functions acquires the OpenThread API lock.
Note Every OT APIs that takes an otInstance argument MUST be protected with this API lock except that
the call site is in OT callbacks.
Return
• True on lock acquired
• False on failing to acquire the lock with the timeout.
Parameters
• [in] block_ticks: The maxinum number of RTOS ticks to wait for the lock.
void esp_openthread_lock_release(void)
This function releases the OpenThread API lock.
Header File
• components/openthread/include/esp_openthread_netif_glue.h
Functions
void *esp_openthread_netif_glue_init(const esp_openthread_platform_config_t *config)
This function initializes the OpenThread network interface glue.
Return
• glue pointer on success
• NULL on failure
Parameters
• [in] config: The platform configuration.
void esp_openthread_netif_glue_deinit(void)
This function deinitializes the OpenThread network interface glue.
esp_netif_t *esp_openthread_get_netif(void)
This function acquires the OpenThread netif.
Return The OpenThread netif or NULL if not initialzied.
Header File
• components/openthread/include/esp_openthread_border_router.h
Functions
void esp_openthread_set_backbone_netif(esp_netif_t *backbone_netif)
Sets the backbone interface used for border routing.
Note This function must be called before esp_openthread_init
Parameters
• [in] backbone_netif: The backbone network interface (WiFi or ethernet)
esp_err_t esp_openthread_border_router_init(void)
Initializes the border router features of OpenThread.
Note Calling this function will make the device behave as an OpenThread border router. Kconfig option
CONFIG_OPENTHREAD_BORDER_ROUTER is required.
Return
• ESP_ERR_NOT_SUPPORTED if feature not supported
• ESP_FIAL on other failures
esp_err_t esp_openthread_border_router_deinit(void)
Deinitializes the border router features of OpenThread.
Return

• ESP_ERR_INVALID_STATE if not initialized
• ESP_FIAL on other failures
esp_netif_t *esp_openthread_get_backbone_netif(void)
Gets the backbone interface of OpenThread border router.
Return The backbone interface or NULL if border router not initialized.
Thread is an IPv6-based mesh networking technology for IoT. Code examples for the Thread API are provided in
the openthread directory of ESP-IDF examples.
2.2.4 IP Network Layer
ESP-NETIF
The purpose of ESP-NETIF library is twofold:

• It provides an abstraction layer for the application on top of the TCP/IP stack. This will allow applications to
choose between IP stacks in the future.
• The APIs it provides are thread safe, even if the underlying TCP/IP stack APIs are not.
ESP-IDF currently implements ESP-NETIF for the lwIP TCP/IP stack only. However, the adapter itself is TCP/IP
implementation agnostic and different implementations are possible.
Some ESP-NETIF API functions are intended to be called by application code, for example to get/set interface IP
addresses, configure DHCP. Other functions are intended for internal ESP-IDF use by the network driver layer.
In many cases, applications do not need to call ESP-NETIF APIs directly as they are called from the default network
event handlers.
ESP-NETIF component is a successor of the tcpip_adapter, former network interface abstraction, which has become
deprecated since IDF v4.1. Please refer to the TCP/IP Adapter Migration Guide section in case existing applications
to be ported to use the esp-netif API instead.
ESP-NETIF architecture
| (A) USER CODE |
| |
.............| init settings events |
. +----------------------------------------+
. . | *
. . | *
--------+ +===========================+ * +-----------------------+
| | new/config get/set | * | |
| | |...*.....| init |
| |---------------------------| * | |
init | | |**** | |
start |********| event handler |*********| DHCP |
stop | | | | |
| |---------------------------| | |
| | | | NETIF |
+-----| | | +-----------------+ |
| glue|----<---| esp_netif_transmit |--<------| netif_output | |
| | | | | | |
| |---->---| esp_netif_receive |-->------| netif_input | |
| | | | + ----------------+ |
| |....<...| esp_netif_free_rx_buffer |...<.....| packet buffer |
+-----| | | | |
| | | | (D) |
(B) | | (C) | +-----------------------+
--------+ +===========================+
(continues on next page)

(continued from previous page)

communication NETWORK STACK
DRIVER ESP-NETIF
Data and event flow in the diagram

• ........ Initialization line from user code to ESP-NETIF and communication driver
• --<--->-- Data packets going from communication media to TCP/IP stack and back
• ******** Events aggregated in ESP-NETIF propagates to driver, user code and network stack
• | User settings and runtime configuration
ESP-NETIF interaction
A) User code, boiler plate Overall application interaction with a specific IO driver for communication media and
configured TCP/IP network stack is abstracted using ESP-NETIF APIs and outlined as below:
A) Initialization code
1) Initializes IO driver
2) Creates a new instance of ESP-NETIF and configure with
• ESP-NETIF specific options (flags, behaviour, name)
• Network stack options (netif init and input functions, not publicly available)
• IO driver specific options (transmit, free rx buffer functions, IO driver handle)
3) Attaches the IO driver handle to the ESP-NETIF instance created in the above steps
4) Configures event handlers
• use default handlers for common interfaces defined in IO drivers; or define a specific handlers for
customised behaviour/new interfaces
• register handlers for app related events (such as IP lost/acquired)
B) Interaction with network interfaces using ESP-NETIF API
• Getting and setting TCP/IP related parameters (DHCP, IP, etc)
• Receiving IP events (connect/disconnect)
• Controlling application lifecycle (set interface up/down)
B) Communication driver, IO driver, media driver Communication driver plays these two important roles in
relation with ESP-NETIF:
1) Event handlers: Define behaviour patterns of interaction with ESP-NETIF (for example: ethernet link-up ->
turn netif on)
2) Glue IO layer: Adapts the input/output functions to use ESP-NETIF transmit, receive and free receive buffer
• Installs driver_transmit to appropriate ESP-NETIF object, so that outgoing packets from network stack are
passed to the IO driver
• Calls esp_netif_receive() to pass incoming data to network stack
C) ESP-NETIF, former tcpip_adapter ESP-NETIF is an intermediary between an IO driver and a network stack,
connecting packet data path between these two. As that it provides a set of interfaces for attaching a driver to ESP-
NETIF object (runtime) and configuring a network stack (compile time). In addition to that a set of API is provided
to control network interface lifecycle and its TCP/IP properties. As an overview, the ESP-NETIF public interface
could be divided into these 6 groups:
1) Initialization APIs (to create and configure ESP-NETIF instance)
2) Input/Output API (for passing data between IO driver and network stack)
3) Event or Action API
• Used for network interface lifecycle management

• ESP-NETIF provides building blocks for designing event handlers

4) Setters and Getters for basic network interface properties
5) Network stack abstraction: enabling user interaction with TCP/IP stack
• Set interface up or down
• DHCP server and client API
• DNS API
6) Driver conversion utilities
D) Network stack Network stack has no public interaction with application code with regard to public interfaces
and shall be fully abstracted by ESP-NETIF API.
ESP-NETIF programmer s manual Please refer to the example section for basic initialization of default inter-
faces:
• WiFi Station: wifi/getting_started/station/main/station_example_main.c
• WiFi Access Point: wifi/getting_started/softAP/main/softap_example_main.c
• Ethernet: ethernet/basic/main/ethernet_example_main.c
For more specific cases please consult this guide: ESP-NETIF Custom I/O Driver.
WiFi default initialization The initialization code as well as registering event handlers for default interfaces, such
as softAP and station, are provided in two separate APIs to facilitate simple startup code for most applications:
• esp_netif_create_default_wifi_ap()
• esp_netif_create_default_wifi_sta()
Please note that these functions return the esp_netif handle, i.e. a pointer to a network interface object allocated
and configured with default settings, which as a consequence, means that:
• The created object has to be destroyed if a network de-initialization is provided by an application using
esp_netif_destroy_default_wifi().
• These default interfaces must not be created multiple times, unless the created handle is deleted using
esp_netif_destroy().
• When using Wifi in AP+STA mode, both these interfaces has to be created.
API Reference
Header File
• components/esp_netif/include/esp_netif.h
Functions
esp_err_t esp_netif_init(void)
Initialize the underlying TCP/IP stack.
Return
• ESP_FAIL if initializing failed
Note This function should be called exactly once from application code, when the application starts up.
esp_err_t esp_netif_deinit(void)
Deinitialize the esp-netif component (and the underlying TCP/IP stack)
Note: Deinitialization is not supported yet
Return
• ESP_ERR_INVALID_STATE if esp_netif not initialized
• ESP_ERR_NOT_SUPPORTED otherwise

esp_netif_t *esp_netif_new(const esp_netif_config_t *esp_netif_config)

Creates an instance of new esp-netif object based on provided config.
Return
• pointer to esp-netif object on success
• NULL otherwise
Parameters
• [in] esp_netif_config: pointer esp-netif configuration
void esp_netif_destroy(esp_netif_t *esp_netif)
Destroys the esp_netif object.
Parameters
• [in] esp_netif: pointer to the object to be deleted
esp_err_t esp_netif_set_driver_config(esp_netif_t *esp_netif, const
esp_netif_driver_ifconfig_t *driver_config)
Configures driver related options of esp_netif object.
Return
• ESP_ERR_ESP_NETIF_INVALID_PARAMS if invalid parameters provided
Parameters
• [inout] esp_netif: pointer to the object to be configured
• [in] driver_config: pointer esp-netif io driver related configuration
esp_err_t esp_netif_attach(esp_netif_t *esp_netif, esp_netif_iodriver_handle driver_handle)
Attaches esp_netif instance to the io driver handle.
Calling this function enables connecting specific esp_netif object with already initialized io driver to update
esp_netif object with driver specific configuration (i.e. calls post_attach callback, which typically sets io driver
callbacks to esp_netif instance and starts the driver)
Return
• ESP_ERR_ESP_NETIF_DRIVER_ATTACH_FAILED if driver s pot_attach callback failed
Parameters
• [inout] esp_netif: pointer to esp_netif object to be attached
• [in] driver_handle: pointer to the driver handle
esp_err_t esp_netif_receive(esp_netif_t *esp_netif, void *buffer, size_t len, void *eb)
Passes the raw packets from communication media to the appropriate TCP/IP stack.
This function is called from the configured (peripheral) driver layer. The data are then forwarded as frames to
the TCP/IP stack.
Return
• ESP_OK
Parameters
• [in] esp_netif: Handle to esp-netif instance
• [in] buffer: Received data
• [in] len: Length of the data frame
• [in] eb: Pointer to internal buffer (used in Wi-Fi driver)
void esp_netif_action_start(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data)
Default building block for network interface action upon IO driver start event Creates network interface, if
AUTOUP enabled turns the interface on, if DHCPS enabled starts dhcp server.
Note This API can be directly used as event handler
Parameters
• base:
• event_id:
• data:

void esp_netif_action_stop(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data)

Default building block for network interface action upon IO driver stop event.
Parameters
• base:
• event_id:
• data:
void esp_netif_action_connected(void *esp_netif, esp_event_base_t base, int32_t event_id, void
*data)
Default building block for network interface action upon IO driver connected event.
Parameters
• base:
• event_id:
• data:
void esp_netif_action_disconnected(void *esp_netif, esp_event_base_t base, int32_t event_id,
void *data)
Default building block for network interface action upon IO driver disconnected event.
Parameters
• base:
• event_id:
• data:
void esp_netif_action_got_ip(void *esp_netif, esp_event_base_t base, int32_t event_id, void
*data)
Default building block for network interface action upon network got IP event.
Parameters
• base:
• event_id:
• data:
void esp_netif_action_join_ip6_multicast_group(void *esp_netif, esp_event_base_t base,
int32_t event_id, void *data)
Default building block for network interface action upon IPv6 multicast group join.
Parameters
• base:
• event_id:
• data:
void esp_netif_action_leave_ip6_multicast_group(void *esp_netif, esp_event_base_t
base, int32_t event_id, void *data)
Default building block for network interface action upon IPv6 multicast group leave.
Parameters
• base:
• event_id:
• data:

void esp_netif_action_add_ip6_address(void *esp_netif, esp_event_base_t base, int32_t

event_id, void *data)
Default building block for network interface action upon IPv6 address added by the underlying stack.
Parameters
• base:
• event_id:
• data:
void esp_netif_action_remove_ip6_address(void *esp_netif, esp_event_base_t base, int32_t
event_id, void *data)
Default building block for network interface action upon IPv6 address removed by the underlying stack.
Parameters
• base:
• event_id:
• data:
esp_err_t esp_netif_set_mac(esp_netif_t *esp_netif, uint8_t mac[])
Set the mac address for the interface instance.
Return
• ESP_OK - success
• ESP_ERR_ESP_NETIF_IF_NOT_READY - interface status error
• ESP_ERR_NOT_SUPPORTED - mac not supported on this interface
Parameters
• [in] mac: Desired mac address for the related network interface
esp_err_t esp_netif_get_mac(esp_netif_t *esp_netif, uint8_t mac[])
Get the mac address for the interface instance.
Return
• ESP_ERR_NOT_SUPPORTED - mac not supported on this interface
Parameters
• [out] mac: Resultant mac address for the related network interface
esp_err_t esp_netif_set_hostname(esp_netif_t *esp_netif, const char *hostname)
Set the hostname of an interface.
The configured hostname overrides the default configuration value CONFIG_LWIP_LOCAL_HOSTNAME.
Please note that when the hostname is altered after interface started/connected the changes would only be
reflected once the interface restarts/reconnects
Return
• ESP_ERR_ESP_NETIF_INVALID_PARAMS - parameter error
Parameters
• [in] hostname: New hostname for the interface. Maximum length 32 bytes.
esp_err_t esp_netif_get_hostname(esp_netif_t *esp_netif, const char **hostname)
Get interface hostname.
Return

• ESP_ERR_ESP_NETIF_INVALID_PARAMS - parameter error

Parameters
• [out] hostname: Returns a pointer to the hostname. May be NULL if no hostname is set. If
set non-NULL, pointer remains valid (and string may change if the hostname changes).
bool esp_netif_is_netif_up(esp_netif_t *esp_netif)
Test if supplied interface is up or down.
Return
• true - Interface is up
• false - Interface is down
Parameters
esp_err_t esp_netif_get_ip_info(esp_netif_t *esp_netif, esp_netif_ip_info_t *ip_info)
Get interface s IP address information.
If the interface is up, IP information is read directly from the TCP/IP stack. If the interface is down, IP
information is read from a copy kept in the ESP-NETIF instance
Return
• ESP_OK
• ESP_ERR_ESP_NETIF_INVALID_PARAMS
Parameters
• [out] ip_info: If successful, IP information will be returned in this argument.
esp_err_t esp_netif_get_old_ip_info(esp_netif_t *esp_netif, esp_netif_ip_info_t *ip_info)
Get interface s old IP information.
Returns an old IP address previously stored for the interface when the valid IP changed.
If the IP lost timer has expired (meaning the interface was down for longer than the configured interval) then
the old IP information will be zero.
Return
• ESP_OK
Parameters
• [out] ip_info: If successful, IP information will be returned in this argument.
esp_err_t esp_netif_set_ip_info(esp_netif_t *esp_netif, const esp_netif_ip_info_t *ip_info)
Set interface s IP address information.
This function is mainly used to set a static IP on an interface.
If the interface is up, the new IP information is set directly in the TCP/IP stack.
The copy of IP information kept in the ESP-NETIF instance is also updated (this copy is returned if the IP is
queried while the interface is still down.)
Note DHCP client/server must be stopped (if enabled for this interface) before setting new IP information.
Note Calling this interface for may generate a SYSTEM_EVENT_STA_GOT_IP or SYS-
TEM_EVENT_ETH_GOT_IP event.
Return
• ESP_OK
• ESP_ERR_ESP_NETIF_DHCP_NOT_STOPPED If DHCP server or client is still running
Parameters
• [in] ip_info: IP information to set on the specified interface

esp_err_t esp_netif_set_old_ip_info(esp_netif_t *esp_netif, const esp_netif_ip_info_t

*ip_info)
Set interface old IP information.
This function is called from the DHCP client (if enabled), before a new IP is set. It is also called from the default
handlers for the SYSTEM_EVENT_STA_CONNECTED and SYSTEM_EVENT_ETH_CONNECTED
events.
Calling this function stores the previously configured IP, which can be used to determine if the IP changes in
the future.
If the interface is disconnected or down for too long, the IP lost timer will expire (after the configured
interval) and set the old IP information to zero.
Return
• ESP_OK
Parameters
• [in] ip_info: Store the old IP information for the specified interface
int esp_netif_get_netif_impl_index(esp_netif_t *esp_netif)
Get net interface index from network stack implementation.
Note This index could be used in setsockopt() to bind socket with multicast interface
Return implementation specific index of interface represented with supplied esp_netif
Parameters
esp_err_t esp_netif_get_netif_impl_name(esp_netif_t *esp_netif, char *name)
Get net interface name from network stack implementation.
Note This name could be used in setsockopt() to bind socket with appropriate interface
Return
• ESP_OK
Parameters
• [out] name: Interface name as specified in underlying TCP/IP stack. Note that the actual name
will be copied to the specified buffer, which must be allocated to hold maximum interface name size
(6 characters for lwIP)
esp_err_t esp_netif_dhcps_option(esp_netif_t *esp_netif, esp_netif_dhcp_option_mode_t opt_op,
esp_netif_dhcp_option_id_t opt_id, void *opt_val, uint32_t
opt_len)
Set or Get DHCP server option.
Return
• ESP_OK
• ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED
• ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED
Parameters
• [in] opt_op: ESP_NETIF_OP_SET to set an option, ESP_NETIF_OP_GET to get an option.
• [in] opt_id: Option index to get or set, must be one of the supported enum values.
• [inout] opt_val: Pointer to the option parameter.
• [in] opt_len: Length of the option parameter.
esp_err_t esp_netif_dhcpc_option(esp_netif_t *esp_netif, esp_netif_dhcp_option_mode_t opt_op,
esp_netif_dhcp_option_id_t opt_id, void *opt_val, uint32_t
opt_len)
Set or Get DHCP client option.
Return

• ESP_OK
Parameters
• [in] opt_op: ESP_NETIF_OP_SET to set an option, ESP_NETIF_OP_GET to get an option.
• [in] opt_id: Option index to get or set, must be one of the supported enum values.
• [inout] opt_val: Pointer to the option parameter.
• [in] opt_len: Length of the option parameter.
esp_err_t esp_netif_dhcpc_start(esp_netif_t *esp_netif)
Start DHCP client (only if enabled in interface object)
Note The default event handlers for the SYSTEM_EVENT_STA_CONNECTED and SYS-
TEM_EVENT_ETH_CONNECTED events call this function.
Return
• ESP_OK
• ESP_ERR_ESP_NETIF_DHCPC_START_FAILED
Parameters
esp_err_t esp_netif_dhcpc_stop(esp_netif_t *esp_netif)
Stop DHCP client (only if enabled in interface object)
Note Calling action_netif_stop() will also stop the DHCP Client if it is running.
Return
• ESP_OK
• ESP_ERR_ESP_NETIF_IF_NOT_READY
Parameters
esp_err_t esp_netif_dhcpc_get_status(esp_netif_t *esp_netif, esp_netif_dhcp_status_t *status)
Get DHCP client status.
Return
• ESP_OK
Parameters
• [out] status: If successful, the status of DHCP client will be returned in this argument.
esp_err_t esp_netif_dhcps_get_status(esp_netif_t *esp_netif, esp_netif_dhcp_status_t *status)
Get DHCP Server status.
Return
• ESP_OK
Parameters
• [out] status: If successful, the status of the DHCP server will be returned in this argument.
esp_err_t esp_netif_dhcps_start(esp_netif_t *esp_netif)
Start DHCP server (only if enabled in interface object)
Return
• ESP_OK
Parameters

esp_err_t esp_netif_dhcps_stop(esp_netif_t *esp_netif)

Stop DHCP server (only if enabled in interface object)
Return
• ESP_OK
• ESP_ERR_ESP_NETIF_IF_NOT_READY
Parameters
esp_err_t esp_netif_set_dns_info(esp_netif_t *esp_netif, esp_netif_dns_type_t type,
esp_netif_dns_info_t *dns)
Set DNS Server information.
This function behaves differently if DHCP server or client is enabled
If DHCP client is enabled, main and backup DNS servers will be updated automatically from the DHCP lease
if the relevant DHCP options are set. Fallback DNS Server is never updated from the DHCP lease and is
designed to be set via this API. If DHCP client is disabled, all DNS server types can be set via this API only.
If DHCP server is enabled, the Main DNS Server setting is used by the DHCP server to provide a DNS Server
option to DHCP clients (Wi-Fi stations).
• The default Main DNS server is typically the IP of the Wi-Fi AP interface itself.
• This function can override it by setting server type ESP_NETIF_DNS_MAIN.
• Other DNS Server types are not supported for the Wi-Fi AP interface.
Return
• ESP_ERR_ESP_NETIF_INVALID_PARAMS invalid params
Parameters
• [in] type: Type of DNS Server to set: ESP_NETIF_DNS_MAIN,
ESP_NETIF_DNS_BACKUP, ESP_NETIF_DNS_FALLBACK
• [in] dns: DNS Server address to set
esp_err_t esp_netif_get_dns_info(esp_netif_t *esp_netif, esp_netif_dns_type_t type,
esp_netif_dns_info_t *dns)
Get DNS Server information.
Return the currently configured DNS Server address for the specified interface and Server type.
This may be result of a previous call to esp_netif_set_dns_info(). If the interface s DHCP client is enabled,
the Main or Backup DNS Server may be set by the current DHCP lease.
Return
• ESP_ERR_ESP_NETIF_INVALID_PARAMS invalid params
Parameters
• [in] type: Type of DNS Server to get: ESP_NETIF_DNS_MAIN,
ESP_NETIF_DNS_BACKUP, ESP_NETIF_DNS_FALLBACK
• [out] dns: DNS Server result is written here on success
esp_err_t esp_netif_create_ip6_linklocal(esp_netif_t *esp_netif)
Create interface link-local IPv6 address.
Cause the TCP/IP stack to create a link-local IPv6 address for the specified interface.
This function also registers a callback for the specified interface, so that if the link-local address becomes
verified as the preferred address then a SYSTEM_EVENT_GOT_IP6 event will be sent.
Return
• ESP_OK

Parameters
esp_err_t esp_netif_get_ip6_linklocal(esp_netif_t *esp_netif, esp_ip6_addr_t *if_ip6)
Get interface link-local IPv6 address.
If the specified interface is up and a preferred link-local IPv6 address has been created for the interface, return
a copy of it.
Return
• ESP_OK
• ESP_FAIL If interface is down, does not have a link-local IPv6 address, or the link-local IPv6
address is not a preferred address.
Parameters
• [out] if_ip6: IPv6 information will be returned in this argument if successful.
esp_err_t esp_netif_get_ip6_global(esp_netif_t *esp_netif, esp_ip6_addr_t *if_ip6)
Get interface global IPv6 address.
If the specified interface is up and a preferred global IPv6 address has been created for the interface, return a
copy of it.
Return
• ESP_OK
• ESP_FAIL If interface is down, does not have a global IPv6 address, or the global IPv6 address is
not a preferred address.
Parameters
• [out] if_ip6: IPv6 information will be returned in this argument if successful.
int esp_netif_get_all_ip6(esp_netif_t *esp_netif, esp_ip6_addr_t if_ip6[])
Get all IPv6 addresses of the specified interface.
Return number of returned IPv6 addresses
Parameters
• [out] if_ip6: Array of IPv6 addresses will be copied to the argument
void esp_netif_set_ip4_addr(esp_ip4_addr_t *addr, uint8_t a, uint8_t b, uint8_t c, uint8_t d)
Sets IPv4 address to the specified octets.
Parameters
• [out] addr: IP address to be set
• a: the first octet (127 for IP 127.0.0.1)
• b:
• c:
• d:
char *esp_ip4addr_ntoa(const esp_ip4_addr_t *addr, char *buf, int buflen)
Converts numeric IP address into decimal dotted ASCII representation.
Return either pointer to buf which now holds the ASCII representation of addr or NULL if buf was too small
Parameters
• addr: ip address in network order to convert
• buf: target buffer where the string is stored
• buflen: length of buf
uint32_t esp_ip4addr_aton(const char *addr)
Ascii internet address interpretation routine The value returned is in network order.
Return ip address in network order
Parameters
• addr: IP address in ascii representation (e.g. 127.0.0.1 )

esp_err_t esp_netif_str_to_ip4(const char *src, esp_ip4_addr_t *dst)

Converts Ascii internet IPv4 address into esp_ip4_addr_t.
Return
• ESP_FAIL if conversion failed
• ESP_ERR_INVALID_ARG if invalid parameter is passed into
Parameters
• [in] src: IPv4 address in ascii representation (e.g. 127.0.0.1 )
• [out] dst: Address of the target esp_ip4_addr_t structure to receive converted address
esp_err_t esp_netif_str_to_ip6(const char *src, esp_ip6_addr_t *dst)
Converts Ascii internet IPv6 address into esp_ip4_addr_t Zeros in the IP address can be stripped or completely
ommited: 2001:db8:85a3:0:0:0:2:1 or 2001:db8::2:1 )
Return
• ESP_FAIL if conversion failed
• ESP_ERR_INVALID_ARG if invalid parameter is passed into
Parameters
• [in] src: IPv6 address in ascii representation (e.g.
2001:0db8:85a3:0000:0000:0000:0002:0001 )
• [out] dst: Address of the target esp_ip6_addr_t structure to receive converted address
esp_netif_iodriver_handle esp_netif_get_io_driver(esp_netif_t *esp_netif)
Gets media driver handle for this esp-netif instance.
Return opaque pointer of related IO driver
Parameters
esp_netif_t *esp_netif_get_handle_from_ifkey(const char *if_key)
Searches over a list of created objects to find an instance with supplied if key.
Return Handle to esp-netif instance
Parameters
• if_key: Textual description of network interface
esp_netif_flags_t esp_netif_get_flags(esp_netif_t *esp_netif)
Returns configured flags for this interface.
Return Configuration flags
Parameters
const char *esp_netif_get_ifkey(esp_netif_t *esp_netif)
Returns configured interface key for this esp-netif instance.
Return Textual description of related interface
Parameters
const char *esp_netif_get_desc(esp_netif_t *esp_netif)
Returns configured interface type for this esp-netif instance.
Return Enumerated type of this interface, such as station, AP, ethernet
Parameters
int esp_netif_get_route_prio(esp_netif_t *esp_netif)
Returns configured routing priority number.
Return Integer representing the instance s route-prio, or -1 if invalid paramters
Parameters

int32_t esp_netif_get_event_id(esp_netif_t *esp_netif, esp_netif_ip_event_type_t event_type)

Returns configured event for this esp-netif instance and supplied event type.
Return specific event id which is configured to be raised if the interface lost or acquired IP address -1 if
supplied event_type is not known
Parameters
• event_type: (either get or lost IP)
esp_netif_t *esp_netif_next(esp_netif_t *esp_netif)
Iterates over list of interfaces. Returns first netif if NULL given as parameter.
Return First netif from the list if supplied parameter is NULL, next one otherwise
Parameters
size_t esp_netif_get_nr_of_ifs(void)
Returns number of registered esp_netif objects.
Return Number of esp_netifs
void esp_netif_netstack_buf_ref(void *netstack_buf)
increase the reference counter of net stack buffer
Parameters
• [in] netstack_buf: the net stack buffer
void esp_netif_netstack_buf_free(void *netstack_buf)
free the netstack buffer
Parameters
• [in] netstack_buf: the net stack buffer
Macros
_ESP_NETIF_SUPPRESS_LEGACY_WARNING_
WiFi default API reference
Header File
• components/esp_wifi/include/esp_wifi_default.h
Functions
esp_err_t esp_netif_attach_wifi_station(esp_netif_t *esp_netif)
Attaches wifi station interface to supplied netif.
Return
• ESP_FAIL if attach failed
Parameters
• esp_netif: instance to attach the wifi station to
esp_err_t esp_netif_attach_wifi_ap(esp_netif_t *esp_netif)
Attaches wifi soft AP interface to supplied netif.
Return
• ESP_FAIL if attach failed
Parameters
• esp_netif: instance to attach the wifi AP to
esp_err_t esp_wifi_set_default_wifi_sta_handlers(void)
Sets default wifi event handlers for STA interface.

Return
• ESP_OK on success, error returned from esp_event_handler_register if failed
esp_err_t esp_wifi_set_default_wifi_ap_handlers(void)
Sets default wifi event handlers for AP interface.
Return
esp_err_t esp_wifi_clear_default_wifi_driver_and_handlers(void *esp_netif)
Clears default wifi event handlers for supplied network interface.
Return
Parameters
• esp_netif: instance of corresponding if object
esp_netif_t *esp_netif_create_default_wifi_ap(void)
Creates default WIFI AP. In case of any init error this API aborts.
Note The API creates esp_netif object with default WiFi access point config, attaches the netif to wifi and
registers default wifi handlers.
Return pointer to esp-netif instance
esp_netif_t *esp_netif_create_default_wifi_sta(void)
Creates default WIFI STA. In case of any init error this API aborts.
Note The API creates esp_netif object with default WiFi station config, attaches the netif to wifi and registers
default wifi handlers.
void esp_netif_destroy_default_wifi(void *esp_netif)
Destroys default WIFI netif created with esp_netif_create_default_wifi_ () API.
Note This API unregisters wifi handlers and detaches the created object from the wifi. (this function is a
no-operation if esp_netif is NULL)
Parameters
• [in] esp_netif: object to detach from WiFi and destroy
esp_netif_t *esp_netif_create_wifi(wifi_interface_t wifi_if, esp_netif_inherent_config_t
*esp_netif_config)
Creates esp_netif WiFi object based on the custom configuration.
Attention This API DOES NOT register default handlers!
Parameters
• [in] wifi_if: type of wifi interface
• [in] esp_netif_config: inherent esp-netif configuration pointer
esp_err_t esp_netif_create_default_wifi_mesh_netifs(esp_netif_t **p_netif_sta,
esp_netif_t **p_netif_ap)
Creates default STA and AP network interfaces for esp-mesh.
Both netifs are almost identical to the default station and softAP, but with DHCP client and server disabled.
Please note that the DHCP client is typically enabled only if the device is promoted to a root node.
Returns created interfaces which could be ignored setting parameters to NULL if an application code does not
need to save the interface instances for further processing.
Return ESP_OK on success
Parameters
• [out] p_netif_sta: pointer where the resultant STA interface is saved (if non NULL)
• [out] p_netif_ap: pointer where the resultant AP interface is saved (if non NULL)

TCP/IP Adapter Migration Guide
TCP/IP Adapter is a network interface abstraction component used in IDF prior to v4.1. This page outlines migration
from tcpip_adapter API to its successor ESP-NETIF.
Updating network connection code
Network stack initialization Simply replace tcpip_adapter_init() with esp_netif_init(). Please

note that the ESP-NETIF initialization API returns standard error code and the esp_netif_deinit() for un-
initialization is available.
Also replace #include "tcpip_adapter.h" with #include "esp_netif.h".
Network interface creation TCP/IP Adapter defined these three interfaces statically:
• WiFi Station
• WiFi Access Point
• Ethernet
Network interface instance shall be explicitly constructed for the ESP-NETIF to enable its con-
nection to the TCP/IP stack. For example initialization code for WiFi has to explicitly call
esp_netif_create_default_wifi_sta(); or esp_netif_create_default_wifi_ap();
after the TCP/IP stack and the event loop have been initialized. Please consult an example initialization code for
these three interfaces:
• WiFi Station: wifi/getting_started/station/main/station_example_main.c
• WiFi Access Point: wifi/getting_started/softAP/main/softap_example_main.c
• Ethernet: ethernet/basic/main/ethernet_example_main.c
Replacing other tcpip_adapter API All the tcpip_adapter functions have their esp-netif counter-part. Please
refer to the esp_netif.h grouped into these sections:
• Setters/Getters
• DHCP
• DNS
• IP address
Default event handlers Event handlers are moved from tcpip_adapter to appropriate driver code. There is no
change from application code perspective, all events shall be handled in the same way. Please note that within IP
related event handlers, application code usually receives IP addresses in a form of esp-netif specific struct (not the
LwIP structs, but binary compatible). This is the preferred way of printing the address:
ESP_LOGI(TAG, "got ip:" IPSTR "\n", IP2STR(&event->ip_info.ip));
Instead of
ESP_LOGI(TAG, "got ip:%s\n", ip4addr_ntoa(&event->ip_info.ip));
Since ip4addr_ntoa() is a LwIP API, the esp-netif provides esp_ip4addr_ntoa() as a replacement, but
the above method is generally preferred.
IP addresses It is preferred to use esp-netif defined IP structures. Please note that the LwIP structs will still work
when default compatibility enabled. * esp-netif IP address definitions

Next steps Additional step in porting an application to fully benefit from the ESP-NETIF is to disable the
tcpip_adapter compatibility layer in the component configuration: ESP NETIF Adapter -> Enable back-
ward compatible tcpip_adapter interface and check if the project compiles. TCP/IP adapter brings
many include dependencies and this step might help in decoupling the application from using specific TCP/IP stack
API directly.
ESP-NETIF Custom I/O Driver
This section outlines implementing a new I/O driver with esp-netif connection capabilities. By convention the I/O
driver has to register itself as an esp-netif driver and thus holds a dependency on esp-netif component and is responsible
for providing data path functions, post-attach callback and in most cases also default event handlers to define network
interface actions based on driver s lifecycle transitions.
Packet input/output As shown in the diagram, the following three API functions for the packet data path must be
defined for connecting with esp-netif:
• esp_netif_transmit()
• esp_netif_free_rx_buffer()
• esp_netif_receive()
The first two functions for transmitting and freeing the rx buffer are provided as callbacks, i.e. they get called from
esp-netif (and its underlying TCP/IP stack) and I/O driver provides their implementation.
The receiving function on the other hand gets called from the I/O driver, so that the driver s code simply calls
esp_netif_receive() on a new data received event.
Post attach callback A final part of the network interface initialization consists of attaching the esp-netif instance
to the I/O driver, by means of calling the following API:
esp_err_t esp_netif_attach(esp_netif_t *esp_netif, esp_netif_iodriver_handle␣

,→driver_handle);
It is assumed that the esp_netif_iodriver_handle is a pointer to driver s object, a struct derived from
struct esp_netif_driver_base_s, so that the first member of I/O driver structure must be this base
structure with pointers to
• post-attach function callback
• related esp-netif instance
As a consequence the I/O driver has to create an instance of the struct per below:
typedef struct my_netif_driver_s {

esp_netif_driver_base_t base; /*!< base structure reserved as␣
,→esp-netif driver */
driver_impl *h; /*!< handle of driver␣

,→implementation */
} my_netif_driver_t;
with actual values of my_netif_driver_t::base.post_attach and the actual drivers handle

my_netif_driver_t::h. So when the esp_netif_attach() gets called from the initialization code,
the post-attach callback from I/O driver s code gets executed to mutually register callbacks between esp-netif and
I/O driver instances. Typically the driver is started as well in the post-attach callback. An example of a simple
post-attach callback is outlined below:
static esp_err_t my_post_attach_start(esp_netif_t * esp_netif, void * args)

{
my_netif_driver_t *driver = args;
const esp_netif_driver_ifconfig_t driver_ifconfig = {
.driver_free_rx_buffer = my_free_rx_buf,


.transmit = my_transmit,
.handle = driver->driver_impl
};
driver->base.netif = esp_netif;
ESP_ERROR_CHECK(esp_netif_set_driver_config(esp_netif, &driver_ifconfig));
my_driver_start(driver->driver_impl);
return ESP_OK;
}
Default handlers I/O drivers also typically provide default definitions of lifecycle behaviour of related network
interfaces based on state transitions of I/O drivers. For example driver start -> network start, etc. An example of
such a default handler is provided below:
esp_err_t my_driver_netif_set_default_handlers(my_netif_driver_t *driver, esp_

,→netif_t * esp_netif)
{
driver_set_event_handler(driver->driver_impl, esp_netif_action_start, MY_DRV_
,→EVENT_START, esp_netif);
driver_set_event_handler(driver->driver_impl, esp_netif_action_stop, MY_DRV_

,→EVENT_STOP, esp_netif);
return ESP_OK;
}
Network stack connection The packet data path functions for transmitting and freeing the rx buffer (defined in
the I/O driver) are called from the esp-netif, specifically from its TCP/IP stack connecting layer. The following API
reference outlines these network stack interaction with the esp-netif.
Header File
• components/esp_netif/include/esp_netif_net_stack.h
Functions
esp_netif_t *esp_netif_get_handle_from_netif_impl(void *dev)
Returns esp-netif handle.
Return handle to related esp-netif instance
Parameters
• [in] dev: opaque ptr to network interface of specific TCP/IP stack
void *esp_netif_get_netif_impl(esp_netif_t *esp_netif)
Returns network stack specific implementation handle (if supported)
Note that it is not supported to acquire PPP netif impl pointer and this function will return NULL for esp_netif
instances configured to PPP mode
Return handle to related network stack netif handle
Parameters
esp_err_t esp_netif_transmit(esp_netif_t *esp_netif, void *data, size_t len)
Outputs packets from the TCP/IP stack to the media to be transmitted.
This function gets called from network stack to output packets to IO driver.
Return ESP_OK on success, an error passed from the I/O driver otherwise
Parameters
• [in] data: Data to be transmitted

esp_err_t esp_netif_transmit_wrap(esp_netif_t *esp_netif, void *data, size_t len, void

*netstack_buf)
Outputs packets from the TCP/IP stack to the media to be transmitted.
This function gets called from network stack to output packets to IO driver.
Return ESP_OK on success, an error passed from the I/O driver otherwise
Parameters
• [in] data: Data to be transmitted
• [in] netstack_buf: net stack buffer
void esp_netif_free_rx_buffer(void *esp_netif, void *buffer)
Free the rx buffer allocated by the media driver.
This function gets called from network stack when the rx buffer to be freed in IO driver context, i.e. to
deallocate a buffer owned by io driver (when data packets were passed to higher levels to avoid copying)
Parameters
• [in] buffer: Rx buffer pointer
Code examples for TCP/IP socket APIs are provided in the protocols/sockets directory of ESP-IDF examples.
The TCP/IP Adapter (legacy network interface library) has been deprecated, please consult the TCP/IP Adapter
Migration Guide to update existing IDF applications.
2.2.5 Application Layer
Documentation for Application layer network protocols (above the IP Network layer) are provided in Application
Protocols.
2.3 Peripherals API
2.3.1 Analog to Digital Converter (ADC)
ADC Channels
The ESP32 integrates 2 SAR (Successive Approximation Register) ADCs, supporting a total of 18 measurement
channels (analog enabled pins).
These channels are supported:
ADC1:
• 8 channels: GPIO32 - GPIO39
ADC2:
• 10 channels: GPIO0, GPIO2, GPIO4, GPIO12 - GPIO15, GOIO25 - GPIO27
ADC Attenuation
Vref is the reference voltage used internally by ESP32 ADCs for measuring the input voltage. The ESP32 ADCs
can measure analog voltages from 0 V to Vref. Among different chips, the Vref varies, the median is 1.1 V. In order
to convert voltages larger than Vref, input voltages can be attenuated before being input to the ADCs. There are 4
available attenuation options, the higher the attenuation is, the higher the measurable input voltage could be.

Attenuation Measurable input voltage range

ADC_ATTEN_DB_0 100 mV ~ 950 mV
ADC_ATTEN_DB_2_5 100 mV ~ 1250 mV
ADC Conversion
An ADC conversion is to convert the input analog voltage to a digital value. The ADC conversion results provided
by the ADC driver APIs are raw data. Resolution of ESP32 ADC raw results under Single Read mode is 12-bit.
• adc1_get_raw()
• adc2_get_raw()
To calculate the voltage based on the ADC raw results, this formula can be used:
Vout = Dout * Vmax / Dmax (1)
where:
Vout Digital output result, standing for the voltage.

Dout ADC raw digital reading result.
Vmax Maximum measurable input analog voltage, see ADC Attenuation.
Dmax Maximum of the output ADC raw digital reading result, which is 4095 under Single Read mode, 4095
under Continuous Read mode.
For boards with eFuse ADC calibration bits, esp_adc_cal_raw_to_voltage() can be used to get the cal-
ibrated conversion results. These results stand for the actual voltage (in mV). No need to transform these data via
the formula (1). If ADC calibration APIs are used on boards without eFuse ADC calibration bits, warnings will be
generated. See ADC Calibration.
ADC Limitations
Note:
• Some of the ADC2 pins are used as strapping pins (GPIO 0, 2, 15) thus cannot be used freely. Such is the
case in the following official Development Kits:
• ESP32 DevKitC: GPIO 0 cannot be used due to external auto program circuits.
• ESP-WROVER-KIT: GPIO 0, 2, 4 and 15 cannot be used due to external connections for different purposes.
• Since the ADC2 module is also used by the Wi-Fi, only one of them could get the preemption when using
together, which means the adc2_get_raw() may get blocked until Wi-Fi stops, and vice versa.
Driver Usage
Both of the ADC units support single read mode, which is suitable for low-frequency sampling operations.
Note: ADC readings from a pin not connected to any signal are random.
ADC Single Read mode The ADC should be configured before reading is taken.
• For ADC1, configure desired precision and attenuation by calling functions adc1_config_width() and
adc1_config_channel_atten().

• For ADC2, configure the attenuation by adc2_config_channel_atten(). The reading width of

ADC2 is configured every time you take the reading.
Attenuation configuration is done per channel, see adc1_channel_t and adc2_channel_t, set as a parameter
of above functions.
Then it is possible to read ADC conversion result with adc1_get_raw() and adc2_get_raw(). Reading
width of ADC2 should be set as a parameter of adc2_get_raw() instead of in the configuration functions.
Single Read mode ADC example can be found in peripherals/adc/single_read directory of ESP-IDF examples.
It is also possible to read the internal hall effect sensor via ADC1 by calling dedicated function
hall_sensor_read(). Note that even the hall sensor is internal to ESP32, reading from it uses channels 0
and 3 of ADC1 (GPIO 36 and 39). Do not connect anything else to these pins and do not change their configuration.
Otherwise it may affect the measurement of low value signal from the sensor.
This API provides convenient way to configure ADC1 for reading from ULP. To do so, call function
adc1_ulp_enable() and then set precision and attenuation as discussed above.
There is another specific function adc_vref_to_gpio() used to route internal reference voltage to a GPIO pin.
It comes handy to calibrate ADC reading and this is discussed in section ADC Calibration.
Note: See ADC Limitations for the limitation of using ADC single read mode.
Minimizing Noise
The ESP32 ADC can be sensitive to noise leading to large discrepancies in ADC readings. Depending on the usage
scenario, users may connect a bypass capacitor (e.g. a 100 nF ceramic capacitor) to the ADC input pad in use, to
minimize noise. Besides, multisampling may also be used to further mitigate the effects of noise.
Fig. 6: Graph illustrating noise mitigation using capacitor and multisampling of 64 samples.

ADC Calibration
The esp_adc_cal/include/esp_adc_cal.h API provides functions to correct for differences in measured voltages caused
by variation of ADC reference voltages (Vref) between chips. Per design the ADC reference voltage is 1100 mV,
however the true reference voltage can range from 1000 mV to 1200 mV amongst different ESP32s.
Fig. 7: Graph illustrating effect of differing reference voltages on the ADC voltage curve.
Correcting ADC readings using this API involves characterizing one of the ADCs at a given attenuation to obtain
a characteristics curve (ADC-Voltage curve) that takes into account the difference in ADC reference voltage. The
characteristics curve is in the form of y = coeff_a * x + coeff_b and is used to convert ADC readings to
voltages in mV. Calculation of the characteristics curve is based on calibration values which can be stored in eFuse
or provided by the user.
Calibration Values Calibration values are used to generate characteristic curves that account for the variation of
ADC reference voltage of a particular ESP32 chip. There are currently 3 source(s) of calibration values on ESP32.
The availability of these calibration values will depend on the type and production date of the ESP32 chip/module.
• Two Point values represent each of the ADCs readings at 150 mV and 850 mV. To obtain more accurate
calibration results these values should be measured by user and burned into eFuse BLOCK3.
• eFuse Vref represents the true ADC reference voltage. This value is measured and burned into eFuse BLOCK0
during factory calibration.
• Default Vref is an estimate of the ADC reference voltage provided by the user as a parameter during charac-
terization. If Two Point or eFuse Vref values are unavailable, Default Vref will be used.
Individual measurement and burning of the eFuse Vref has been applied to ESP32-D0WD and
ESP32-D0WDQ6 chips produced on/after the 1st week of 2018. Such chips may be recognized
by date codes on/later than 012018 (see Line 4 on figure below).
If you would like to purchase chips or modules with calibration, double check with distributor or
Espressif ([email protected]) directly.
If you are unable to check the date code (i.e. the chip may be enclosed inside a canned module,
etc.), you can still verify if eFuse Vref is present by running the espefuse.py tool with adc_info
parameter
$IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/
,→ttyUSB0 adc_info

Fig. 8: ESP32 Chip Surface Marking
Replace /dev/ttyUSB0 with ESP32 board s port name.

A chip that has specific eFuse Vref value programmed (in this case 1093 mV) will be reported as
follows:
ADC VRef calibration: 1093 mV
In another example below the eFuse Vref is not programmed:
ADC VRef calibration: None (1100 mV nominal)
For a chip with two point calibration the message will look similar to:
ADC VRef calibration: 1149 mV

ADC readings stored in efuse BLK3:
ADC1 Low reading (150 mV): 306
ADC1 High reading (850 mV): 3153
ADC2 Low reading (150 mV): 389
ADC2 High reading (850 mV): 3206
Application Extensions
For a full example see esp-idf: peripherals/adc/single_read

Characterizing an ADC at a particular attenuation:
#include "driver/adc.h"
#include "esp_adc_cal.h"
...
//Characterize ADC at particular atten

esp_adc_cal_characteristics_t *adc_chars = calloc(1, sizeof(esp_adc_cal_
,→characteristics_t));
esp_adc_cal_value_t val_type = esp_adc_cal_characterize(unit, atten, ADC_WIDTH_

,→BIT_12, DEFAULT_VREF, adc_chars);
//Check type of calibration value used to characterize ADC

if (val_type == ESP_ADC_CAL_VAL_EFUSE_VREF) {
printf("eFuse Vref");


} else if (val_type == ESP_ADC_CAL_VAL_EFUSE_TP) {
printf("Two Point");
} else {
printf("Default");
}
Reading an ADC then converting the reading to a voltage:
#include "esp_adc_cal.h"
...
uint32_t reading = adc1_get_raw(ADC1_CHANNEL_5);
uint32_t voltage = esp_adc_cal_raw_to_voltage(reading, adc_chars);
Routing ADC reference voltage to GPIO, so it can be manually measured (for Default Vref):
...
esp_err_t status = adc_vref_to_gpio(ADC_UNIT_1, GPIO_NUM_25);

if (status == ESP_OK) {
printf("v_ref routed to GPIO\n");
} else {
printf("failed to route v_ref\n");
}
GPIO Lookup Macros
There are macros available to specify the GPIO number of a ADC channel, or vice versa. e.g.
1. ADC1_CHANNEL_0_GPIO_NUM is the GPIO number of ADC1 channel 0.
2. ADC1_GPIOn_CHANNEL is the ADC1 channel number of GPIO n.
API Reference
This reference covers three components:

• ADC driver
• ADC Calibration
• GPIO Lookup Macros
ADC driver
Header File
• components/driver/esp32/include/driver/adc.h
Functions
esp_err_t adc_set_i2s_data_source(adc_i2s_source_t src)
Set I2S data source.
Return
• ESP_OK success
Parameters
• src: I2S DMA data source, I2S DMA can get data from digital signals or from ADC.

esp_err_t adc_i2s_mode_init(adc_unit_t adc_unit, adc_channel_t channel)

Initialize I2S ADC mode.
Return
• ESP_OK success
• ESP_ERR_INVALID_ARG Parameter error
Parameters
• adc_unit: ADC unit index
• channel: ADC channel index
int hall_sensor_read(void)
Read Hall Sensor.
Note When the power switch of SARADC1, SARADC2, HALL sensor and AMP sensor is turned on,
the input of GPIO36 and GPIO39 will be pulled down for about 80ns. When enabling power for
any of these peripherals, ignore input from GPIO36 and GPIO39. Please refer to section 3.11 of
ECO_and_Workarounds_for_Bugs_in_ESP32 for the description of this issue.
Note The Hall Sensor uses channels 0 and 3 of ADC1. Do not configure these channels for use as ADC
channels.
Note The ADC1 module must be enabled by calling adc1_config_width() before calling hall_sensor_read().
ADC1 should be configured for 12 bit readings, as the hall sensor readings are low values and do not
cover the full range of the ADC.
Return The hall sensor reading.
Header File
• components/hal/include/hal/adc_types.h
Structures
struct adc_digi_pattern_table_t
ADC digital controller (DMA mode) conversion rules setting.
Public Members
uint8_t atten : 2
ADC sampling voltage attenuation configuration. Modification of attenuation affects the range of mea-
surements. 0: measurement range 0 - 800mV, 1: measurement range 0 - 1100mV, 2: measurement range
0 - 1350mV, 3: measurement range 0 - 2600mV.
uint8_t bit_width : 2
ADC resolution.
• 0: 9 bit;
• 1: 10 bit;
• 2: 11 bit;
• 3: 12 bit.
int8_t channel : 4
ADC channel index.
uint8_t val
Raw data value
struct adc_digi_output_data_t
ADC digital controller (DMA mode) output data format. Used to analyze the acquired ADC (DMA) data.
Note ESP32-S2: Member channel can be used to judge the validity of the ADC data, because the role of
the arbiter may get invalid ADC data.

Public Members
uint16_t data : 12
ADC real output data info. Resolution: 12 bit.
ADC real output data info. Resolution: 11 bit.
uint16_t channel : 4
ADC channel index info. For ESP32-S2: If (channel < ADC_CHANNEL_MAX), The data is valid. If
(channel > ADC_CHANNEL_MAX), The data is invalid.
struct adc_digi_output_data_t::[anonymous]::[anonymous] type1
When the configured output format is 12bit. ADC_DIGI_FORMAT_12BIT
uint16_t unit : 1
ADC unit index info. 0: ADC1; 1: ADC2.
struct adc_digi_output_data_t::[anonymous]::[anonymous] type2
When the configured output format is 11bit. ADC_DIGI_FORMAT_11BIT
uint16_t val
Raw data value
struct adc_digi_config_t
CONFIG_IDF_TARGET_ESP32.
ADC digital controller (DMA mode) configuration parameters.
Example setting: When using ADC1 channel0 to measure voltage, the sampling rate is required to be 1 kHz:
+---------------------+--------+--------+--------+
| sample rate | 1 kHz | 1 kHz | 1 kHz |
+---------------------+--------+--------+--------+
| conv_mode | single | both | alter |
| adc1_pattern_len | 1 | 1 | 1 |
| dig_clk.use_apll | 0 | 0 | 0 |
| dig_clk.div_num | 99 | 99 | 99 |
| dig_clk.div_b | 0 | 0 | 0 |
| dig_clk.div_a | 0 | 0 | 0 |
| interval | 400 | 400 | 200 |
+---------------------+--------+--------+--------+
| `trigger_meas_freq` | 1 kHz | 1 kHz | 2 kHz |
+---------------------+--------+--------+--------+
Explanation of the relationship between conv_limit_num, dma_eof_num and the number of DMA out-
puts:
+---------------------+--------+--------+--------+
| conv_mode | single | both | alter |
+---------------------+--------+--------+--------+
| trigger meas times | 1 | 1 | 1 |
+---------------------+--------+--------+--------+
| conv_limit_num | +1 | +1 | +1 |
| dma_eof_num | +1 | +2 | +1 |
| dma output (byte) | +2 | +4 | +2 |
+---------------------+--------+--------+--------+
Public Members
bool conv_limit_en
Enable the function of limiting ADC conversion times. If the number of ADC conversion trigger count
is equal to the limit_num, the conversion is stopped.

uint32_t conv_limit_num
Set the upper limit of the number of ADC conversion triggers. Range: 1 ~ 255.
uint32_t adc1_pattern_len
Pattern table length for digital controller. Range: 0 ~ 16 (0: Don t change the pattern table setting).
The pattern table that defines the conversion rules for each SAR ADC. Each table has 16 items, in which
channel selection, resolution and attenuation are stored. When the conversion is started, the controller
reads conversion rules from the pattern table one by one. For each controller the scan sequence has at
most 16 different rules before repeating itself.
uint32_t adc2_pattern_len
Refer to adc1_pattern_len
adc_digi_pattern_table_t *adc1_pattern
Pointer to pattern table for digital controller. The table size defined by adc1_pattern_len.
adc_digi_pattern_table_t *adc2_pattern
Refer to adc1_pattern
adc_digi_convert_mode_t conv_mode
ADC conversion mode for digital controller. See adc_digi_convert_mode_t.
adc_digi_output_format_t format
ADC output data format for digital controller. See adc_digi_output_format_t.
Enumerations
enum adc_unit_t
ADC unit enumeration.
Note For ADC digital controller (DMA mode), ESP32 doesn t support ADC_UNIT_2, ADC_UNIT_BOTH,
ADC_UNIT_ALTER.
Values:
ADC_UNIT_1 = 1
SAR ADC 1.
ADC_UNIT_2 = 2
SAR ADC 2.
ADC_UNIT_BOTH = 3
SAR ADC 1 and 2.
ADC_UNIT_ALTER = 7
SAR ADC 1 and 2 alternative mode.
ADC_UNIT_MAX
enum adc_channel_t
ADC channels handle. See adc1_channel_t, adc2_channel_t.
Note For ESP32 ADC1, don t use ADC_CHANNEL_8, ADC_CHANNEL_9. See adc1_channel_t.
Values:
ADC_CHANNEL_0 = 0
ADC channel
ADC_CHANNEL_1
ADC channel
ADC_CHANNEL_2
ADC channel
ADC_CHANNEL_3
ADC channel

ADC_CHANNEL_4
ADC channel
ADC_CHANNEL_5
ADC channel
ADC_CHANNEL_6
ADC channel
ADC_CHANNEL_7
ADC channel
ADC_CHANNEL_8
ADC channel
ADC_CHANNEL_9
ADC channel
ADC_CHANNEL_MAX
enum adc_atten_t
ADC attenuation parameter. Different parameters determine the range of the ADC. See
adc1_config_channel_atten.
Values:
ADC_ATTEN_DB_0 = 0
No input attenumation, ADC can measure up to approx. 800 mV.
ADC_ATTEN_DB_2_5 = 1
The input voltage of ADC will be attenuated extending the range of measurement by about 2.5 dB (1.33
x)
ADC_ATTEN_DB_6 = 2
The input voltage of ADC will be attenuated extending the range of measurement by about 6 dB (2 x)
ADC_ATTEN_DB_11 = 3
The input voltage of ADC will be attenuated extending the range of measurement by about 11 dB (3.55
x)
ADC_ATTEN_MAX
enum adc_i2s_source_t
ESP32 ADC DMA source selection.
Values:
ADC_I2S_DATA_SRC_IO_SIG = 0
I2S data from GPIO matrix signal
ADC_I2S_DATA_SRC_ADC = 1
I2S data from ADC
ADC_I2S_DATA_SRC_MAX
enum adc_bits_width_t
ADC resolution setting option.
Values:
ADC_WIDTH_BIT_9 = 0
ADC capture width is 9Bit.
ADC_WIDTH_BIT_10 = 1

ADC_WIDTH_MAX
enum adc_digi_convert_mode_t
ADC digital controller (DMA mode) work mode.
Note The conversion mode affects the sampling frequency: SINGLE_UNIT_1: When the measurement is
triggered, only ADC1 is sampled once. SINGLE_UNIT_2: When the measurement is triggered, only
ADC2 is sampled once. BOTH_UNIT : When the measurement is triggered, ADC1 and ADC2 are
sampled at the same time. ALTER_UNIT : When the measurement is triggered, ADC1 or ADC2 samples
alternately.
Values:
ADC_CONV_SINGLE_UNIT_1 = 1
SAR ADC 1.
ADC_CONV_SINGLE_UNIT_2 = 2
SAR ADC 2.
ADC_CONV_BOTH_UNIT = 3
SAR ADC 1 and 2.
ADC_CONV_ALTER_UNIT = 7
SAR ADC 1 and 2 alternative mode.
ADC_CONV_UNIT_MAX
enum adc_digi_output_format_t
ADC digital controller (DMA mode) output data format option.
Values:
ADC_DIGI_FORMAT_12BIT
ADC to DMA data format, [15:12]-channel, [11: 0]-12 bits ADC data
(adc_digi_output_data_t). Note: For single convert mode.
ADC_DIGI_FORMAT_11BIT
ADC to DMA data format, [15]-adc unit, [14:11]-channel, [10: 0]-11 bits ADC data
(adc_digi_output_data_t). Note: For multi or alter convert mode.
ADC_DIGI_FORMAT_MAX
Header File
• components/driver/include/driver/adc_common.h
Functions
void adc_power_on(void)
Enable ADC power.
void adc_power_off(void)
Power off SAR ADC.
void adc_power_acquire(void)
Increment the usage counter for ADC module. ADC will stay powered on while the counter is greater than 0.
Call adc_power_release when done using the ADC.
void adc_power_release(void)
Decrement the usage counter for ADC module. ADC will stay powered on while the counter is greater than 0.
Call this function when done using the ADC.
esp_err_t adc_gpio_init(adc_unit_t adc_unit, adc_channel_t channel)
Initialize ADC pad.

Return
• ESP_OK success
Parameters
• channel: ADC channel index
esp_err_t adc1_pad_get_io_num(adc1_channel_t channel, gpio_num_t *gpio_num)
Get the GPIO number of a specific ADC1 channel.
Return
• ESP_OK if success
• ESP_ERR_INVALID_ARG if channel not valid
Parameters
• channel: Channel to get the GPIO number
• gpio_num: output buffer to hold the GPIO number
esp_err_t adc1_config_channel_atten(adc1_channel_t channel, adc_atten_t atten)
Set the attenuation of a particular channel on ADC1, and configure its associated GPIO pin mux.
The default ADC voltage is for attenuation 0 dB and listed in the table below. By setting higher attenuation it
is possible to read higher voltages.
Due to ADC characteristics, most accurate results are obtained within the suggested range shown in the
following table.
+----------+-------------+-----------------+
| | attenuation | suggested range |
| SoC | (dB) | (mV) |
+==========+=============+=================+
| | 0 | 100 ~ 950 |
| +-------------+-----------------+
| | 2.5 | 100 ~ 1250 |
| ESP32 +-------------+-----------------+
| | 6 | 150 ~ 1750 |
| +-------------+-----------------+
| | 11 | 150 ~ 2450 |
+----------+-------------+-----------------+
| | 0 | 0 ~ 750 |
| +-------------+-----------------+
| | 2.5 | 0 ~ 1050 |
| ESP32-S2 +-------------+-----------------+
| | 6 | 0 ~ 1300 |
| +-------------+-----------------+
| | 11 | 0 ~ 2500 |
+----------+-------------+-----------------+
For maximum accuracy, use the ADC calibration APIs and measure voltages within these recommended
ranges.
Note For any given channel, this function must be called before the first time adc1_get_raw() is called
for that channel.
Note This function can be called multiple times to configure multiple ADC channels simultaneously. You may
call adc1_get_raw() only after configuring a channel.
Return
• ESP_OK success
Parameters
• channel: ADC1 channel to configure
• atten: Attenuation level
esp_err_t adc1_config_width(adc_bits_width_t width_bit)
Configure ADC1 capture width, meanwhile enable output invert for ADC1. The configuration is for all channels

of ADC1.
Return
• ESP_OK success
Parameters
• width_bit: Bit capture width for ADC1
int adc1_get_raw(adc1_channel_t channel)
Take an ADC1 reading from a single channel.
Note ESP32: When the power switch of SARADC1, SARADC2, HALL sensor and AMP sensor is turned
on, the input of GPIO36 and GPIO39 will be pulled down for about 80ns. When enabling power
for any of these peripherals, ignore input from GPIO36 and GPIO39. Please refer to section 3.11 of
ECO_and_Workarounds_for_Bugs_in_ESP32 for the description of this issue. As a workaround, call
adc_power_acquire() in the app. This will result in higher power consumption (by ~1mA), but will re-
move the glitches on GPIO36 and GPIO39.
Note Call adc1_config_width() before the first time this function is called.
Note For any given channel, adc1_config_channel_atten(channel) must be called before the first time this
function is called. Configuring a new channel does not prevent a previously configured channel from
being read.
Return
• -1: Parameter error
• Other: ADC1 channel reading.
Parameters
• channel: ADC1 channel to read
esp_err_t adc_set_data_inv(adc_unit_t adc_unit, bool inv_en)
Set ADC data invert.
Return
• ESP_OK success
Parameters
• inv_en: whether enable data invert
esp_err_t adc_set_clk_div(uint8_t clk_div)
Set ADC source clock.
Return
• ESP_OK success
Parameters
• clk_div: ADC clock divider, ADC clock is divided from APB clock
esp_err_t adc_set_data_width(adc_unit_t adc_unit, adc_bits_width_t width_bit)
Configure ADC capture width.
Return
• ESP_OK success
Parameters
• width_bit: Bit capture width for ADC unit.
void adc1_ulp_enable(void)
Configure ADC1 to be usable by the ULP.
This function reconfigures ADC1 to be controlled by the ULP. Effect of this function can be reverted using
adc1_get_raw() function.
Note that adc1_config_channel_atten, adc1_config_width() functions need to be called to configure
ADC1 channels, before ADC1 is used by the ULP.

esp_err_t adc2_pad_get_io_num(adc2_channel_t channel, gpio_num_t *gpio_num)

Get the GPIO number of a specific ADC2 channel.
Return
• ESP_ERR_INVALID_ARG if channel not valid
Parameters
• channel: Channel to get the GPIO number
• gpio_num: output buffer to hold the GPIO number
esp_err_t adc2_config_channel_atten(adc2_channel_t channel, adc_atten_t atten)
Configure the ADC2 channel, including setting attenuation.
The default ADC voltage is for attenuation 0 dB and listed in the table below. By setting higher attenuation it
is possible to read higher voltages.
Due to ADC characteristics, most accurate results are obtained within the suggested range shown in the
following table.
+----------+-------------+-----------------+
| | attenuation | suggested range |
| SoC | (dB) | (mV) |
+==========+=============+=================+
| | 0 | 100 ~ 950 |
| +-------------+-----------------+
| | 2.5 | 100 ~ 1250 |
| ESP32 +-------------+-----------------+
| | 6 | 150 ~ 1750 |
| +-------------+-----------------+
| | 11 | 150 ~ 2450 |
+----------+-------------+-----------------+
| | 0 | 0 ~ 750 |
| +-------------+-----------------+
| | 2.5 | 0 ~ 1050 |
| ESP32-S2 +-------------+-----------------+
| | 6 | 0 ~ 1300 |
| +-------------+-----------------+
| | 11 | 0 ~ 2500 |
+----------+-------------+-----------------+
For maximum accuracy, use the ADC calibration APIs and measure voltages within these recommended
ranges.
Note This function also configures the input GPIO pin mux to connect it to the ADC2 channel. It must be
called before calling adc2_get_raw() for this channel.
Note For any given channel, this function must be called before the first time adc2_get_raw() is called
for that channel.
Return
• ESP_OK success
Parameters
• channel: ADC2 channel to configure
• atten: Attenuation level
esp_err_t adc2_get_raw(adc2_channel_t channel, adc_bits_width_t width_bit, int *raw_out)
Take an ADC2 reading on a single channel.
Note ESP32: When the power switch of SARADC1, SARADC2, HALL sensor and AMP sensor is turned
on, the input of GPIO36 and GPIO39 will be pulled down for about 80ns. When enabling power
for any of these peripherals, ignore input from GPIO36 and GPIO39. Please refer to section 3.11 of

Note ESP32: For a given channel, adc2_config_channel_atten() must be called before the first
time this function is called. If Wi-Fi is started via esp_wifi_start(), this function will always fail
with ESP_ERR_TIMEOUT.
Note ESP32-S2: ADC2 support hardware arbiter. The arbiter is to improve the use efficiency of ADC2. After
the control right is robbed by the high priority, the low priority controller will read the invalid ADC2 data.
Default priority: Wi-Fi > RTC > Digital;
Return
• ESP_ERR_TIMEOUT ADC2 is being used by other controller and the request timed out.
• ESP_ERR_INVALID_STATE The controller status is invalid. Please try again.
Parameters
• channel: ADC2 channel to read
• width_bit: Bit capture width for ADC2
• raw_out: the variable to hold the output data.
esp_err_t adc_vref_to_gpio(adc_unit_t adc_unit, gpio_num_t gpio)
Output ADC1 or ADC2 s reference voltage to adc2_channe_t s IO.
This function routes the internal reference voltage of ADCn to one of ADC2 s channels. This reference
voltage can then be manually measured for calibration purposes.
Note ESP32 only supports output of ADC2 s internal reference voltage.
Return
• ESP_OK: v_ref successfully routed to selected GPIO
• ESP_ERR_INVALID_ARG: Unsupported GPIO
Parameters
• [in] adc_unit: ADC unit index
• [in] gpio: GPIO number (Only ADC2 s channels IO are supported)
esp_err_t adc2_vref_to_gpio(gpio_num_t gpio)
Output ADC2 reference voltage to adc2_channe_t s IO.
This function routes the internal reference voltage of ADCn to one of ADC2 s channels. This reference
voltage can then be manually measured for calibration purposes.
Return
• ESP_OK: v_ref successfully routed to selected GPIO
• ESP_ERR_INVALID_ARG: Unsupported GPIO
Parameters
• [in] gpio: GPIO number (ADC2 s channels are supported)
esp_err_t adc_digi_init(void)
ADC digital controller initialization.
Return
• ESP_OK Success
esp_err_t adc_digi_deinit(void)
ADC digital controller deinitialization.
Return
• ESP_OK Success
esp_err_t adc_digi_controller_config(const adc_digi_config_t *config)
Setting the digital controller.
Return
• ESP_ERR_INVALID_STATE Driver state is invalid.
• ESP_ERR_INVALID_ARG If the combination of arguments is invalid.
• ESP_OK On success
Parameters
• config: Pointer to digital controller paramter. Refer to adc_digi_config_t.

Macros
ADC_ATTEN_0db
ADC rtc controller attenuation option.
Note This definitions are only for being back-compatible
ADC_ATTEN_2_5db
ADC_ATTEN_6db
ADC_ATTEN_11db
ADC_WIDTH_BIT_DEFAULT
The default (max) bit width of the ADC of current version. You can also get the maximum bitwidth by
SOC_ADC_MAX_BITWIDTH defined in soc_caps.h.
ADC_WIDTH_9Bit
ADC_WIDTH_10Bit
ADC_WIDTH_11Bit
ADC_WIDTH_12Bit
Enumerations
enum adc1_channel_t
Values:
ADC1_CHANNEL_0 = 0
ADC1 channel 0 is GPIO36
ADC1_CHANNEL_1
ADC1_CHANNEL_2
ADC1_CHANNEL_3
ADC1_CHANNEL_4
ADC1_CHANNEL_5
ADC1_CHANNEL_6
ADC1_CHANNEL_7
ADC1_CHANNEL_MAX
enum adc2_channel_t
Values:
ADC2_CHANNEL_0 = 0
ADC2 channel 0 is GPIO4 (ESP32), GPIO11 (ESP32-S2)
ADC2_CHANNEL_1
ADC2_CHANNEL_2
ADC2_CHANNEL_3

ADC2_CHANNEL_4
ADC2_CHANNEL_5
ADC2_CHANNEL_6
ADC2_CHANNEL_7
ADC2_CHANNEL_8
ADC2_CHANNEL_9
ADC2_CHANNEL_MAX
enum adc_i2s_encode_t
ADC digital controller encode option.
Values:
ADC_ENCODE_12BIT
ADC to DMA data format, , [15:12]-channel [11:0]-12 bits ADC data
ADC_ENCODE_11BIT
ADC to DMA data format, [15]-unit, [14:11]-channel [10:0]-11 bits ADC data
ADC_ENCODE_MAX
ADC Calibration
Header File
• components/esp_adc_cal/include/esp_adc_cal.h
Functions
esp_err_t esp_adc_cal_check_efuse(esp_adc_cal_value_t value_type)
Checks if ADC calibration values are burned into eFuse.
This function checks if ADC reference voltage or Two Point values have been burned to the eFuse of the
current ESP32
Note in ESP32S2, only ESP_ADC_CAL_VAL_EFUSE_TP is supported. Some old ESP32S2s do not sup-
port this, either. In which case you have to calibrate it manually, possibly by performing your own
two-point calibration on the chip.
Return
• ESP_OK: The calibration mode is supported in eFuse
• ESP_ERR_NOT_SUPPORTED: Error, eFuse values are not burned
• ESP_ERR_INVALID_ARG: Error, invalid argument (ESP_ADC_CAL_VAL_DEFAULT_VREF)
Parameters
• value_type: Type of calibration value (ESP_ADC_CAL_VAL_EFUSE_VREF or
ESP_ADC_CAL_VAL_EFUSE_TP)
esp_adc_cal_value_t esp_adc_cal_characterize(adc_unit_t adc_num, adc_atten_t atten,
adc_bits_width_t bit_width, uint32_t de-
fault_vref, esp_adc_cal_characteristics_t *chars)
Characterize an ADC at a particular attenuation.
This function will characterize the ADC at a particular attenuation and generate the ADC-Voltage curve in the
form of [y = coeff_a * x + coeff_b]. Characterization can be based on Two Point values, eFuse Vref, or default
Vref and the calibration values will be prioritized in that order.

Note For ESP32, Two Point values and eFuse Vref calibration can be enabled/disabled using menuconfig.
For ESP32s2, only Two Point values calibration and only ADC_WIDTH_BIT_13 is supported. The
parameter default_vref is unused.
Return
• ESP_ADC_CAL_VAL_EFUSE_VREF: eFuse Vref used for characterization
• ESP_ADC_CAL_VAL_EFUSE_TP: Two Point value used for characterization (only in Linear
Mode)
• ESP_ADC_CAL_VAL_DEFAULT_VREF: Default Vref used for characterization
Parameters
• [in] adc_num: ADC to characterize (ADC_UNIT_1 or ADC_UNIT_2)
• [in] atten: Attenuation to characterize
• [in] bit_width: Bit width configuration of ADC
• [in] default_vref: Default ADC reference voltage in mV (Only in ESP32, used if eFuse
values is not available)
• [out] chars: Pointer to empty structure used to store ADC characteristics
uint32_t esp_adc_cal_raw_to_voltage(uint32_t adc_reading, const
esp_adc_cal_characteristics_t *chars)
Convert an ADC reading to voltage in mV.
This function converts an ADC reading to a voltage in mV based on the ADC s characteristics.
Note Characteristics structure must be initialized before this function is called (call
esp_adc_cal_characterize())
Return Voltage in mV
Parameters
• [in] adc_reading: ADC reading
• [in] chars: Pointer to initialized structure containing ADC characteristics
esp_err_t esp_adc_cal_get_voltage(adc_channel_t channel, const esp_adc_cal_characteristics_t
*chars, uint32_t *voltage)
Reads an ADC and converts the reading to a voltage in mV.
This function reads an ADC then converts the raw reading to a voltage in mV based on the characteristics
provided. The ADC that is read is also determined by the characteristics.
Note The Characteristics structure must be initialized before this function is called (call
esp_adc_cal_characterize())
Return
• ESP_OK: ADC read and converted to mV
• ESP_ERR_INVALID_ARG: Error due to invalid arguments
• ESP_ERR_INVALID_STATE: Reading result is invalid. Try to read again.
Parameters
• [in] channel: ADC Channel to read
• [in] chars: Pointer to initialized ADC characteristics structure
• [out] voltage: Pointer to store converted voltage
Structures
struct esp_adc_cal_characteristics_t
Structure storing characteristics of an ADC.
Note Call esp_adc_cal_characterize() to initialize the structure
Public Members
adc_unit_t adc_num
ADC number
adc_atten_t atten
ADC attenuation

adc_bits_width_t bit_width
ADC bit width
uint32_t coeff_a
Gradient of ADC-Voltage curve
uint32_t coeff_b
Offset of ADC-Voltage curve
uint32_t vref
Vref used by lookup table
const uint32_t *low_curve
Pointer to low Vref curve of lookup table (NULL if unused)
const uint32_t *high_curve
Pointer to high Vref curve of lookup table (NULL if unused)
uint8_t version
ADC Calibration
Enumerations
enum esp_adc_cal_value_t
Type of calibration value used in characterization.
Values:
ESP_ADC_CAL_VAL_EFUSE_VREF = 0
Characterization based on reference voltage stored in eFuse
ESP_ADC_CAL_VAL_EFUSE_TP = 1
Characterization based on Two Point values stored in eFuse
ESP_ADC_CAL_VAL_DEFAULT_VREF = 2
Characterization based on default reference voltage
ESP_ADC_CAL_VAL_EFUSE_TP_FIT = 3
Characterization based on Two Point values and fitting curve coefficients stored in eFuse
ESP_ADC_CAL_VAL_MAX
ESP_ADC_CAL_VAL_NOT_SUPPORTED = ESP_ADC_CAL_VAL_MAX
GPIO Lookup Macros
Header File
• components/soc/esp32/include/soc/adc_channel.h
Macros
ADC1_GPIO36_CHANNEL
ADC1_CHANNEL_0_GPIO_NUM
ADC1_GPIO37_CHANNEL
ADC1_GPIO38_CHANNEL
ADC1_GPIO39_CHANNEL
ADC1_GPIO32_CHANNEL

ADC1_GPIO33_CHANNEL
ADC1_GPIO34_CHANNEL
ADC1_GPIO35_CHANNEL
ADC2_GPIO4_CHANNEL
ADC2_GPIO0_CHANNEL
ADC2_GPIO2_CHANNEL
ADC2_GPIO15_CHANNEL
ADC2_GPIO13_CHANNEL
ADC2_GPIO12_CHANNEL
ADC2_GPIO14_CHANNEL
ADC2_GPIO27_CHANNEL
ADC2_GPIO25_CHANNEL
ADC2_GPIO26_CHANNEL
2.3.2 Digital To Analog Converter (DAC)
Overview
ESP32 has two 8-bit DAC (digital to analog converter) channels, connected to GPIO25 (Channel 1) and GPIO26
(Channel 2).
The DAC driver allows these channels to be set to arbitrary voltages.
The DAC channels can also be driven with DMA-style written sample data by the digital controller, via the I2S driver
when using the built-in DAC mode .
For other analog output options, see the Sigma-delta Modulation module and the LED Control module. Both these
modules produce high frequency PWM output, which can be hardware low-pass filtered in order to generate a lower
frequency analog output.

Application Example
Setting DAC channel 1 (GPIO25) voltage to approx 0.78 of VDD_A voltage (VDD * 200 / 255). For VDD_A 3.3V,
this is 2.59V:
#include <driver/dac.h>
...
dac_output_enable(DAC_CHANNEL_1);
dac_output_voltage(DAC_CHANNEL_1, 200);
API Reference
Header File
• components/driver/esp32/include/driver/dac.h
Functions
esp_err_t dac_i2s_enable(void)
Enable DAC output data from I2S.
Return
• ESP_OK success
esp_err_t dac_i2s_disable(void)
Disable DAC output data from I2S.
Return
• ESP_OK success
Header File
• components/driver/include/driver/dac_common.h
Functions
esp_err_t dac_pad_get_io_num(dac_channel_t channel, gpio_num_t *gpio_num)
Get the GPIO number of a specific DAC channel.
Return
Parameters
• channel: Channel to get the gpio number
• gpio_num: output buffer to hold the gpio number
esp_err_t dac_output_voltage(dac_channel_t channel, uint8_t dac_value)
Set DAC output voltage. DAC output is 8-bit. Maximum (255) corresponds to VDD3P3_RTC.
Note Need to configure DAC pad before calling this function. DAC channel 1 is attached to GPIO25, DAC
channel 2 is attached to GPIO26
Return
• ESP_OK success
Parameters
• channel: DAC channel
• dac_value: DAC output value
esp_err_t dac_output_enable(dac_channel_t channel)
DAC pad output enable.
Note DAC channel 1 is attached to GPIO25, DAC channel 2 is attached to GPIO26 I2S left channel will be
mapped to DAC channel 2 I2S right channel will be mapped to DAC channel 1

Parameters
esp_err_t dac_output_disable(dac_channel_t channel)
DAC pad output disable.
Note DAC channel 1 is attached to GPIO25, DAC channel 2 is attached to GPIO26
Return
• ESP_OK success
Parameters
esp_err_t dac_cw_generator_enable(void)
Enable cosine wave generator output.
Return
• ESP_OK success
esp_err_t dac_cw_generator_disable(void)
Disable cosine wave generator output.
Return
• ESP_OK success
esp_err_t dac_cw_generator_config(dac_cw_config_t *cw)
Config the cosine wave generator function in DAC module.
Return
• ESP_OK success
• ESP_ERR_INVALID_ARG The parameter is NULL.
Parameters
• cw: Configuration.
GPIO Lookup Macros Some useful macros can be used to specified the GPIO number of a DAC channel, or vice
versa. e.g.
1. DAC_CHANNEL_1_GPIO_NUM is the GPIO number of channel 1 (GPIO25);
2. DAC_GPIO26_CHANNEL is the channel number of GPIO 26 (channel 2).
Header File
• components/soc/esp32/include/soc/dac_channel.h
Macros
DAC_GPIO25_CHANNEL
DAC_CHANNEL_1_GPIO_NUM
DAC_GPIO26_CHANNEL
DAC_CHANNEL_2_GPIO_NUM
Header File
• components/hal/include/hal/dac_types.h
Structures
struct dac_cw_config_t
Config the cosine wave generator function in DAC module.

Public Members
dac_channel_t en_ch
Enable the cosine wave generator of DAC channel.
dac_cw_scale_t scale
Set the amplitude of the cosine wave generator output.
dac_cw_phase_t phase
Set the phase of the cosine wave generator output.
uint32_t freq
Set frequency of cosine wave generator output. Range: 130(130Hz) ~ 55000(100KHz).
int8_t offset
Set the voltage value of the DC component of the cosine wave generator output. Note: Unreasonable
settings can cause waveform to be oversaturated. Range: -128 ~ 127.
Enumerations
enum dac_channel_t
Values:
DAC_CHANNEL_1 = 0
DAC channel 1 is GPIO25(ESP32) / GPIO17(ESP32S2)
DAC_CHANNEL_2 = 1
DAC channel 2 is GPIO26(ESP32) / GPIO18(ESP32S2)
DAC_CHANNEL_MAX
enum dac_cw_scale_t
The multiple of the amplitude of the cosine wave generator. The max amplitude is VDD3P3_RTC.
Values:
DAC_CW_SCALE_1 = 0x0
1/1. Default.
1/2.
1/4.
1/8.
enum dac_cw_phase_t
Set the phase of the cosine wave generator output.
Values:
DAC_CW_PHASE_0 = 0x2
Phase shift +0°
DAC_CW_PHASE_180 = 0x3
Phase shift +180°
2.3.3 General Purpose Timer
Introduction
The ESP32 chip contains two hardware timer groups. Each group has two general-purpose hardware timer(s). They
are all 64-bit generic timers based on 16-bit pre-scalers and 64-bit up / down counters which are capable of being
auto-reloaded.

Functional Overview
The following sections of this document cover the typical steps to configure and operate a timer:
• Timer Initialization - covers which parameters should be set up to get the timer working, and also what specific
functionality is provided depending on the timer configuration.
• Timer Control - describes how to read a timer s value, pause or start a timer, and change how it operates.
• Alarms - shows how to set and use alarms.
• Interrupts- explains how to use interrupt callbacks.
Timer Initialization The two ESP32 timer groups, with two timer(s) in each, provide the total of four individual
timers for use. An ESP32 timer group should be identified using timer_group_t. An individual timer in a group
should be identified with timer_idx_t.
First of all, the timer should be initialized by calling the function timer_init() and passing a structure
timer_config_t to it to define how the timer should operate. In particular, the following timer parameters
can be set:
• Divider: Sets how quickly the timer s counter is ticking . The setting divider is used as a divisor of the
clock source that by default is APB_CLK running at 80 MHz. For more information of APB_CLK frequency,
please check ESP32 Technical Reference Manual > Reset and Clock [PDF] chapter for more details.
• Mode: Sets if the counter should be incrementing or decrementing. It can be defined using counter_dir
by selecting one of the values from timer_count_dir_t.
• Counter Enable: If the counter is enabled, it will start incrementing / decrementing immediately after calling
timer_init(). You can change the behavior with counter_en by selecting one of the values from
timer_start_t.
• Alarm Enable: Can be set using alarm_en.
• Auto Reload: Sets if the counter should auto_reload the initial counter value on the timer s alarm or
continue incrementing or decrementing.
To get the current values of the timer s settings, use the function timer_get_config().
Timer Control Once the timer is enabled, its counter starts running. To enable the timer, call the function
timer_init() with counter_en set to true, or call timer_start(). You can specify the timer s
initial counter value by calling timer_set_counter_value(). To check the timer s current value, call
timer_get_counter_value() or timer_get_counter_time_sec().
To pause the timer at any time, call timer_pause(). To resume it, call timer_start().
To reconfigure the timer, you can call timer_init(). This function is described in Section Timer Initialization.
You can also reconfigure the timer by using dedicated functions to change individual settings:
Set- Dedicated Description

ting Function
Di- timer_set_divider()
Change the rate of ticking. To avoid unpredictable results, the timer should be paused
vider when changing the divider. If the timer is running, timer_set_divider() pauses
it, change the setting, and start the timer again.
Mode timer_set_counter_mode()
Set if the counter should be incrementing or decrementing
Auto timer_set_auto_reload()
Set if the initial counter value should be reloaded on the timer s alarm
Reload
Alarms To set an alarm, call the function timer_set_alarm_value() and then enable the alarm us-
ing timer_set_alarm(). The alarm can also be enabled during the timer initialization stage, when
timer_init() is called.
After the alarm is enabled, and the timer reaches the alarm value, the following two actions can occur depending on
the configuration:
• An interrupt will be triggered if previously configured. See Section Interrupts on how to configure interrupts.

• When auto_reload is enabled, the timer s counter will automatically be reloaded to start
counting again from a previously configured value. This value should be set in advance with
timer_set_counter_value().
Note:
• If an alarm value is set and the timer has already reached this value, the alarm is triggered immediately.
• Once triggered, the alarm is disabled automatically and needs to be re-enabled to trigger again.
To check the specified alarm value, call timer_get_alarm_value().
Interrupts Registration of an interrupt callback for a specific timer can be done by calling
timer_isr_callback_add() and passing in the group ID, timer ID, callback handler and user data.
The callback handler will be invoked in ISR context, so user shouldn t put any blocking API in the callback
function. The benefit of using interrupt callback instead of precessing interrupt from scratch is, you don t have
to deal with interrupt status check and clean stuffs, they are all addressed before the callback got run in driver s
default interrupt handler.
For more information on how to use interrupts, please see the application example below.
Application Example
The 64-bit hardware timer example: peripherals/timer_group.
API Reference
Header File
• components/driver/include/driver/timer.h
Functions
esp_err_t timer_get_counter_value(timer_group_t group_num, timer_idx_t timer_num, uint64_t
*timer_val)
Read the counter value of hardware timer.
Return
• ESP_OK Success
Parameters
• group_num: Timer group, 0 for TIMERG0 or 1 for TIMERG1
• timer_num: Timer index, 0 for hw_timer[0] & 1 for hw_timer[1]
• timer_val: Pointer to accept timer counter value.
esp_err_t timer_get_counter_time_sec(timer_group_t group_num, timer_idx_t timer_num, double
*time)
Read the counter value of hardware timer, in unit of a given scale.
Return
• ESP_OK Success
Parameters
• time: Pointer, type of double*, to accept timer counter value, in seconds.
esp_err_t timer_set_counter_value(timer_group_t group_num, timer_idx_t timer_num, uint64_t
load_val)
Set counter value to hardware timer.

Return
• ESP_OK Success
Parameters
• load_val: Counter value to write to the hardware timer.
esp_err_t timer_start(timer_group_t group_num, timer_idx_t timer_num)
Start the counter of hardware timer.
Return
• ESP_OK Success
Parameters
• group_num: Timer group number, 0 for TIMERG0 or 1 for TIMERG1
esp_err_t timer_pause(timer_group_t group_num, timer_idx_t timer_num)
Pause the counter of hardware timer.
Return
• ESP_OK Success
Parameters
esp_err_t timer_set_counter_mode(timer_group_t group_num, timer_idx_t timer_num,
timer_count_dir_t counter_dir)
Set counting mode for hardware timer.
Return
• ESP_OK Success
Parameters
• counter_dir: Counting direction of timer, count-up or count-down
esp_err_t timer_set_auto_reload(timer_group_t group_num, timer_idx_t timer_num,
timer_autoreload_t reload)
Enable or disable counter reload function when alarm event occurs.
Return
• ESP_OK Success
Parameters
• reload: Counter reload mode.
esp_err_t timer_set_divider(timer_group_t group_num, timer_idx_t timer_num, uint32_t divider)
Set hardware divider of the source clock to the timer group. By default, the source clock is APB clock running
at 80 MHz. For more information, please check Chapter Reset and Clock in Chip Technical Reference Manual.
Return
• ESP_OK Success
Parameters
• divider: Timer clock divider value. The divider s range is from from 2 to 65536.

esp_err_t timer_set_alarm_value(timer_group_t group_num, timer_idx_t timer_num, uint64_t

alarm_value)
Set timer alarm value.
Return
• ESP_OK Success
Parameters
• alarm_value: A 64-bit value to set the alarm value.
esp_err_t timer_get_alarm_value(timer_group_t group_num, timer_idx_t timer_num, uint64_t
*alarm_value)
Get timer alarm value.
Return
• ESP_OK Success
Parameters
• alarm_value: Pointer of A 64-bit value to accept the alarm value.
esp_err_t timer_set_alarm(timer_group_t group_num, timer_idx_t timer_num, timer_alarm_t
alarm_en)
Enable or disable generation of timer alarm events.
Return
• ESP_OK Success
Parameters
• alarm_en: To enable or disable timer alarm function.
esp_err_t timer_isr_callback_add(timer_group_t group_num, timer_idx_t timer_num, timer_isr_t
isr_handler, void *arg, int intr_alloc_flags)
Add ISR handle callback for the corresponding timer.
The callback should return a bool value to determine whether need to do YIELD at the end of the ISR.
Note This ISR handler will be called from an ISR. This ISR handler do not need to handle interrupt status,
and should be kept short. If you want to realize some specific applications or write the whole ISR, you
can call timer_isr_register( ) to register ISR.
Parameters
• group_num: Timer group number
• timer_num: Timer index of timer group
• isr_handler: Interrupt handler function, it is a callback function.
• arg: Parameter for handler function
• intr_alloc_flags: Flags used to allocate the interrupt. One or multiple (ORred)
ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.
If the intr_alloc_flags value ESP_INTR_FLAG_IRAM is set, the handler function must be declared with
IRAM_ATTR attribute and can only call functions in IRAM or ROM. It cannot call other timer APIs.
Return
• ESP_OK Success
esp_err_t timer_isr_callback_remove(timer_group_t group_num, timer_idx_t timer_num)
Remove ISR handle callback for the corresponding timer.
Return
• ESP_OK Success


Parameters
esp_err_t timer_isr_register(timer_group_t group_num, timer_idx_t timer_num, void (*fn))void *
, void *arg, int intr_alloc_flags, timer_isr_handle_t *handleRegister Timer interrupt handler, the handler is an
ISR. The handler will be attached to the same CPU core that this function is running on.
If the intr_alloc_flags value ESP_INTR_FLAG_IRAM is set, the handler function must be declared with
IRAM_ATTR attribute and can only call functions in IRAM or ROM. It cannot call other timer APIs. Use
direct register access to configure timers from inside the ISR in this case.
Note If use this function to reigster ISR, you need to write the whole ISR. In the interrupt handler, you need to
call timer_spinlock_take(..) before your handling, and call timer_spinlock_give( ) after your handling.
Parameters
• fn: Interrupt handler function.
• handle: Pointer to return handle. If non-NULL, a handle for the interrupt will be returned here.
Return
• ESP_OK Success
esp_err_t timer_init(timer_group_t group_num, timer_idx_t timer_num, const timer_config_t *config)
Initializes and configure the timer.
Return
• ESP_OK Success
Parameters
• config: Pointer to timer initialization parameters.
esp_err_t timer_deinit(timer_group_t group_num, timer_idx_t timer_num)
Deinitializes the timer.
Return
• ESP_OK Success
Parameters
esp_err_t timer_get_config(timer_group_t group_num, timer_idx_t timer_num, timer_config_t
*config)
Get timer configure value.
Return
• ESP_OK Success
Parameters
• config: Pointer of struct to accept timer parameters.
esp_err_t timer_group_intr_enable(timer_group_t group_num, timer_intr_t intr_mask)
Enable timer group interrupt, by enable mask.

Return
• ESP_OK Success
Parameters
• intr_mask: Timer interrupt enable mask.
– TIMER_INTR_T0: t0 interrupt
– TIMER_INTR_WDT: watchdog interrupt
esp_err_t timer_group_intr_disable(timer_group_t group_num, timer_intr_t intr_mask)
Disable timer group interrupt, by disable mask.
Return
• ESP_OK Success
Parameters
• intr_mask: Timer interrupt disable mask.
– TIMER_INTR_WDT: watchdog interrupt
esp_err_t timer_enable_intr(timer_group_t group_num, timer_idx_t timer_num)
Enable timer interrupt.
Return
• ESP_OK Success
Parameters
• timer_num: Timer index.
esp_err_t timer_disable_intr(timer_group_t group_num, timer_idx_t timer_num)
Disable timer interrupt.
Return
• ESP_OK Success
Parameters
void timer_group_intr_clr_in_isr(timer_group_t group_num, timer_idx_t timer_num)
Clear timer interrupt status, just used in ISR.
Parameters
void timer_group_clr_intr_status_in_isr(timer_group_t group_num, timer_idx_t
timer_num)
Clear timer interrupt status, just used in ISR.
Parameters
void timer_group_enable_alarm_in_isr(timer_group_t group_num, timer_idx_t timer_num)
Enable alarm interrupt, just used in ISR.
Parameters

uint64_t timer_group_get_counter_value_in_isr(timer_group_t group_num, timer_idx_t

timer_num)
Get the current counter value, just used in ISR.
Return
• Counter value
Parameters
void timer_group_set_alarm_value_in_isr(timer_group_t group_num, timer_idx_t timer_num,
uint64_t alarm_val)
Set the alarm threshold for the timer, just used in ISR.
Parameters
• alarm_val: Alarm threshold.
void timer_group_set_counter_enable_in_isr(timer_group_t group_num, timer_idx_t
timer_num, timer_start_t counter_en)
Enable/disable a counter, just used in ISR.
Parameters
• counter_en: Enable/disable.
timer_intr_t timer_group_intr_get_in_isr(timer_group_t group_num)
Get the masked interrupt status, just used in ISR.
Return
• Interrupt status
Parameters
uint32_t timer_group_get_intr_status_in_isr(timer_group_t group_num)
Get interrupt status, just used in ISR.
Return
• Interrupt status
Parameters
void timer_group_clr_intr_sta_in_isr(timer_group_t group_num, timer_intr_t intr_mask)
Clear the masked interrupt status, just used in ISR.
Parameters
• intr_mask: Masked interrupt.
bool timer_group_get_auto_reload_in_isr(timer_group_t group_num, timer_idx_t
timer_num)
Get auto reload enable status, just used in ISR.
Return
• True Auto reload enabled
• False Auto reload disabled
Parameters
• timer_num: Timer index
esp_err_t timer_spinlock_take(timer_group_t group_num)
Take timer spinlock to enter critical protect.
Note Deprecated, the recommended way is to use ISR callbacks instead, see timer_group_example_main
Return

• ESP_OK Success
Parameters
esp_err_t timer_spinlock_give(timer_group_t group_num)
Give timer spinlock to exit critical protect.
Note Deprecated, the recommended way is to use ISR callbacks instead, see timer_group_example_main
Return
• ESP_OK Success
Parameters
Structures
struct timer_config_t
Data structure with timer s configuration settings.
Public Members
timer_alarm_t alarm_en
Timer alarm enable
timer_start_t counter_en
Counter enable
timer_intr_mode_t intr_type
Interrupt mode
timer_count_dir_t counter_dir
Counter direction
timer_autoreload_t auto_reload
Timer auto-reload
timer_src_clk_t clk_src
Selects source clock.
uint32_t divider
Counter clock divider
Macros
TIMER_BASE_CLK
Frequency of the clock on the input of the timer groups.
Note This macro is not correct for Timer Groups with multiple clock sources (e.g. APB, XTAL) So please
don t use it in your application, we keep it here only for backward compatible
Type Definitions
typedef bool (*timer_isr_t)(void *)
Interrupt handle callback function. User need to retrun a bool value in callback.
Return
• True Do task yield at the end of ISR
• False Not do task yield at the end of ISR
Note If you called FreeRTOS functions in callback, you need to return true or false based on the retrun value
of argument pxHigherPriorityTaskWoken. For example, xQueueSendFromISR is called in
callback, if the return value pxHigherPriorityTaskWoken of any FreeRTOS calls is pdTRUE,
return true; otherwise return false.

typedef intr_handle_t timer_isr_handle_t

Interrupt handle, used in order to free the isr after use. Aliases to an int handle for now.
Enumerations
enum timer_group_t
Selects a Timer-Group out of 2 available groups.
Values:
TIMER_GROUP_0 = 0
Hw timer group 0
TIMER_GROUP_1 = 1
Hw timer group 1
TIMER_GROUP_MAX
Maximum number of Hw timer groups
enum timer_idx_t
Select a hardware timer from timer groups.
Values:
TIMER_0 = 0
Select timer0 of GROUPx
TIMER_1 = 1
Select timer1 of GROUPx
TIMER_MAX
enum timer_intr_t
Interrupt types of the timer.
Values:
TIMER_INTR_T0 = 1 << 0
interrupt of timer 0
TIMER_INTR_T1 = 1 << 1
interrupt of timer 1
TIMER_INTR_WDT = 1 << 2
interrupt of watchdog
TIMER_INTR_NONE = 0
enum timer_count_dir_t
Decides the direction of counter.
Values:
TIMER_COUNT_DOWN = GPTIMER_COUNT_DOWN
Descending Count from cnt.high|cnt.low
TIMER_COUNT_UP = GPTIMER_COUNT_UP
Ascending Count from Zero
TIMER_COUNT_MAX
Maximum number of timer count directions
enum timer_start_t
Decides whether timer is on or paused.
Values:
TIMER_PAUSE
Pause timer counter

TIMER_START
Start timer counter
enum timer_alarm_t
Decides whether to enable alarm mode.
Values:
TIMER_ALARM_DIS = 0
Disable timer alarm
TIMER_ALARM_EN = 1
Enable timer alarm
TIMER_ALARM_MAX
enum timer_intr_mode_t
Select interrupt type if running in alarm mode.
Values:
TIMER_INTR_LEVEL = 0
Interrupt mode: level mode
TIMER_INTR_MAX
enum timer_autoreload_t
Select if Alarm needs to be loaded by software or automatically reload by hardware.
Values:
TIMER_AUTORELOAD_DIS = 0
Disable auto-reload: hardware will not load counter value after an alarm event
TIMER_AUTORELOAD_EN = 1
Enable auto-reload: hardware will load counter value after an alarm event
TIMER_AUTORELOAD_MAX
enum timer_src_clk_t
Select timer source clock.
Values:
TIMER_SRC_CLK_APB = GPTIMER_CLK_SRC_APB
Select APB as the source clock
Header File
• components/hal/include/hal/timer_types.h
Enumerations
enum gptimer_clock_source_t
GPTimer clock source.
Note The clock source listed here is not supported on all targets
Note User should select the clock source based on real requirements:
╔══════════════════════╦══════════════════════════════
║ GPTimer clock source ║ Features ║ Power Management ║
╠══════════════════════╬══════════════════════════════
║ GPTIMER_CLK_SRC_APB ║ High resolution ║ ESP_PM_APB_FREQ_MAX lock ║
╠══════════════════════╬══════════════════════════════
║ GPTIMER_CLK_SRC_XTAL ║ Medium resolution, high accuracy ║ No PM lock ║
╚══════════════════════╩══════════════════════════════
Values:

GPTIMER_CLK_SRC_APB
Select APB as the source clock
GPTIMER_CLK_SRC_XTAL
Select XTAL as the source clock
enum gptimer_count_direction_t
GPTimer count direction.
Values:
GPTIMER_COUNT_DOWN
Decrease count value
GPTIMER_COUNT_UP
Increase count value
enum gptimer_alarm_action_t
GPTimer actions on alarm event.
Values:
GPTIMER_ALARM_ACTION_CONTINUE
Counter will pass through the alarm point and continue counting
GPTIMER_ALARM_ACTION_STOP
Counter will stop on alarm event
GPTIMER_ALARM_ACTION_RELOAD
Counter will do reload on alarm event
2.3.4 GPIO & RTC GPIO
Overview
The ESP32 chip features 34 physical GPIO pads. Some GPIO pads cannot be used or do not have the corresponding
pin on the chip package. For more details, see ESP32 Technical Reference Manual > IO MUX and GPIO Matrix
(GPIO, IO_MUX) [PDF].
Each pad can be used as a general purpose I/O or can be connected to an internal peripheral signal. The table below
provides more information on pin usage, and please note the comments in the table for GPIOs with restrictions.
GPIO Analog Function RTC GPIO Comments

GPIO0 ADC2_CH1 RTC_GPIO11 Strapping pin
GPIO1 TXD
GPIO2 ADC2_CH2 RTC_GPIO12 Strapping pin
GPIO3 RXD
GPIO4 ADC2_CH0 RTC_GPIO10
GPIO5 Strapping pin
GPIO6 SPI0/1
GPIO7 SPI0/1
GPIO8 SPI0/1
GPIO9 SPI0/1
GPIO10 SPI0/1
GPIO11 SPI0/1
GPIO12 ADC2_CH5 RTC_GPIO15 Strapping pin; JTAG
GPIO13 ADC2_CH4 RTC_GPIO14 JTAG
GPIO14 ADC2_CH6 RTC_GPIO16 JTAG
GPIO15 ADC2_CH3 RTC_GPIO13 Strapping pin; JTAG
GPIO16 SPI0/1
GPIO17 SPI0/1


GPIO Analog Function RTC GPIO Comments
GPIO18
GPIO19
GPIO20 This pin is only available on ESP32-
PICO-V3 chip package
GPIO21
GPIO22
GPIO23
GPIO34 ADC1_CH6 RTC_GPIO4 GPI
Note:
• Strapping pin: GPIO0, GPIO2, GPIO5, GPIO12 (MTDI), and GPIO15 (MTDO) are strapping pins. For more
infomation, please refer to ESP32 datasheet.
• SPI0/1: GPIO6-11 and GPIO16-17 are usually connected to the SPI flash and PSRAM integrated on the
module and therefore should not be used for other purposes.
• JTAG: GPIO12-15 are usually used for inline debug.
• GPI: GPIO34-39 can only be set as input mode and do not have software-enabled pullup or pulldown functions.
• TXD & RXD are usually used for flashing and debugging.
• ADC2: ADC2 pins cannot be used when Wi-Fi is used. So, if you re using Wi-Fi and you re having trouble
getting the value from an ADC2 GPIO, you may consider using an ADC1 GPIO instead, that should solve your
problem. For more details, please refer to ADC limitations.
There is also separate RTC GPIO support, which functions when GPIOs are routed to the RTC low-power
and analog subsystem. These pin functions can be used when:
• In deep sleep
• The Ultra Low Power co-processor is running
• Analog functions such as ADC/DAC/etc are in use.
Application Example
GPIO output and input interrupt example: peripherals/gpio/generic_gpio.
API Reference - Normal GPIO
Header File
• components/driver/include/driver/gpio.h
Functions
esp_err_t gpio_config(const gpio_config_t *pGPIOConfig)
GPIO common configuration.
Configure GPIO s Mode,pull-up,PullDown,IntrType

Return
• ESP_OK success
Parameters
• pGPIOConfig: Pointer to GPIO configure struct
esp_err_t gpio_reset_pin(gpio_num_t gpio_num)
Reset an gpio to default state (select gpio function, enable pullup and disable input and output).
Note This function also configures the IOMUX for this pin to the GPIO function, and disconnects any other
peripheral output configured via GPIO Matrix.
Return Always return ESP_OK.
Parameters
• gpio_num: GPIO number.
esp_err_t gpio_set_intr_type(gpio_num_t gpio_num, gpio_int_type_t intr_type)
GPIO set interrupt trigger type.
Return
• ESP_OK Success
Parameters
• gpio_num: GPIO number. If you want to set the trigger type of e.g. of GPIO16, gpio_num should
be GPIO_NUM_16 (16);
• intr_type: Interrupt type, select from gpio_int_type_t
esp_err_t gpio_intr_enable(gpio_num_t gpio_num)
Enable GPIO module interrupt signal.
Note Please do not use the interrupt of GPIO36 and GPIO39 when using ADC or Wi-Fi with sleep
mode enabled. Please refer to the comments of adc1_get_raw. Please refer to section 3.11 of
Return
• ESP_OK Success
Parameters
• gpio_num: GPIO number. If you want to enable an interrupt on e.g. GPIO16, gpio_num should
esp_err_t gpio_intr_disable(gpio_num_t gpio_num)
Disable GPIO module interrupt signal.
Return
• ESP_OK success
Parameters
• gpio_num: GPIO number. If you want to disable the interrupt of e.g. GPIO16, gpio_num should
esp_err_t gpio_set_level(gpio_num_t gpio_num, uint32_t level)
GPIO set output level.
Return
• ESP_OK Success
• ESP_ERR_INVALID_ARG GPIO number error
Parameters
• gpio_num: GPIO number. If you want to set the output level of e.g. GPIO16, gpio_num should
• level: Output level. 0: low ; 1: high
int gpio_get_level(gpio_num_t gpio_num)
GPIO get input level.

Warning If the pad is not configured for input (or input and output) the returned value is always 0.
Return
• 0 the GPIO input level is 0
• 1 the GPIO input level is 1
Parameters
• gpio_num: GPIO number. If you want to get the logic level of e.g. pin GPIO16, gpio_num should
esp_err_t gpio_set_direction(gpio_num_t gpio_num, gpio_mode_t mode)
GPIO set direction.
Configure GPIO direction,such as output_only,input_only,output_and_input
Return
• ESP_OK Success
• ESP_ERR_INVALID_ARG GPIO error
Parameters
• gpio_num: Configure GPIO pins number, it should be GPIO number. If you want to set direction
of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);
• mode: GPIO direction
esp_err_t gpio_set_pull_mode(gpio_num_t gpio_num, gpio_pull_mode_t pull)
Configure GPIO pull-up/pull-down resistors.
Only pins that support both input & output have integrated pull-up and pull-down resistors. Input-only GPIOs
34-39 do not.
Return
• ESP_OK Success
• ESP_ERR_INVALID_ARG : Parameter error
Parameters
• gpio_num: GPIO number. If you want to set pull up or down mode for e.g. GPIO16, gpio_num
should be GPIO_NUM_16 (16);
• pull: GPIO pull up/down mode.
esp_err_t gpio_wakeup_enable(gpio_num_t gpio_num, gpio_int_type_t intr_type)
Enable GPIO wake-up function.
Return
• ESP_OK Success
Parameters
• gpio_num: GPIO number.
• intr_type: GPIO wake-up type. Only GPIO_INTR_LOW_LEVEL or
GPIO_INTR_HIGH_LEVEL can be used.
esp_err_t gpio_wakeup_disable(gpio_num_t gpio_num)
Disable GPIO wake-up function.
Return
• ESP_OK Success
Parameters
• gpio_num: GPIO number
esp_err_t gpio_isr_register(void (*fn))void *
, void *arg, int intr_alloc_flags, gpio_isr_handle_t *handleRegister GPIO interrupt handler, the handler is an
This ISR function is called whenever any GPIO interrupt occurs. See the alternative gpio_install_isr_service()
and gpio_isr_handler_add() API in order to have the driver support per-GPIO ISRs.
To disable or remove the ISR, pass the returned handle to the interrupt allocation functions.
Parameters


Return
• ESP_OK Success ;
• ESP_ERR_NOT_FOUND No free interrupt found with the specified flags
esp_err_t gpio_pullup_en(gpio_num_t gpio_num)
Enable pull-up on GPIO.
Return
• ESP_OK Success
Parameters
esp_err_t gpio_pullup_dis(gpio_num_t gpio_num)
Disable pull-up on GPIO.
Return
• ESP_OK Success
Parameters
esp_err_t gpio_pulldown_en(gpio_num_t gpio_num)
Enable pull-down on GPIO.
Return
• ESP_OK Success
Parameters
esp_err_t gpio_pulldown_dis(gpio_num_t gpio_num)
Disable pull-down on GPIO.
Return
• ESP_OK Success
Parameters
esp_err_t gpio_install_isr_service(int intr_alloc_flags)
Install the driver s GPIO ISR handler service, which allows per-pin GPIO interrupt handlers.
This function is incompatible with gpio_isr_register() - if that function is used, a single global ISR is registered
for all GPIO interrupts. If this function is used, the ISR service provides a global GPIO ISR and individual pin
handlers are registered via the gpio_isr_handler_add() function.
Return
• ESP_OK Success
• ESP_ERR_NO_MEM No memory to install this service
• ESP_ERR_INVALID_STATE ISR service already installed.
• ESP_ERR_NOT_FOUND No free interrupt found with the specified flags
Parameters

void gpio_uninstall_isr_service(void)
Uninstall the driver s GPIO ISR service, freeing related resources.
esp_err_t gpio_isr_handler_add(gpio_num_t gpio_num, gpio_isr_t isr_handler, void *args)
Add ISR handler for the corresponding GPIO pin.
Call this function after using gpio_install_isr_service() to install the driver s GPIO ISR handler service.
The pin ISR handlers no longer need to be declared with IRAM_ATTR, unless you pass the
ESP_INTR_FLAG_IRAM flag when allocating the ISR in gpio_install_isr_service().
This ISR handler will be called from an ISR. So there is a stack size limit (configurable as ISR stack size
in menuconfig). This limit is smaller compared to a global GPIO interrupt handler due to the additional level
of indirection.
Return
• ESP_OK Success
• ESP_ERR_INVALID_STATE Wrong state, the ISR service has not been initialized.
Parameters
• isr_handler: ISR handler function for the corresponding GPIO number.
• args: parameter for ISR handler.
esp_err_t gpio_isr_handler_remove(gpio_num_t gpio_num)
Remove ISR handler for the corresponding GPIO pin.
Return
• ESP_OK Success
• ESP_ERR_INVALID_STATE Wrong state, the ISR service has not been initialized.
Parameters
esp_err_t gpio_set_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t strength)
Set GPIO pad drive capability.
Return
• ESP_OK Success
Parameters
• gpio_num: GPIO number, only support output GPIOs
• strength: Drive capability of the pad
esp_err_t gpio_get_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t *strength)
Get GPIO pad drive capability.
Return
• ESP_OK Success
Parameters
• strength: Pointer to accept drive capability of the pad
esp_err_t gpio_hold_en(gpio_num_t gpio_num)
Enable gpio pad hold function.
The gpio pad hold function works in both input and output modes, but must be output-capable gpios. If pad
hold enabled: in output mode: the output level of the pad will be force locked and can not be changed. in input
mode: the input value read will not change, regardless the changes of input signal.
The state of digital gpio cannot be held during Deep-sleep, and it will resume the hold function when
the chip wakes up from Deep-sleep. If the digital gpio also needs to be held during Deep-sleep,
gpio_deep_sleep_hold_en should also be called.
Power down or call gpio_hold_dis will disable this function.

Return
• ESP_OK Success
• ESP_ERR_NOT_SUPPORTED Not support pad hold function
Parameters
• gpio_num: GPIO number, only support output-capable GPIOs
esp_err_t gpio_hold_dis(gpio_num_t gpio_num)
Disable gpio pad hold function.
When the chip is woken up from Deep-sleep, the gpio will be set to the default mode, so, the gpio will output
the default level if this function is called. If you don t want the level changes, the gpio should be configured
to a known state before this function is called. e.g. If you hold gpio18 high during Deep-sleep, after the chip
is woken up and gpio_hold_dis is called, gpio18 will output low level(because gpio18 is input mode by
default). If you don t want this behavior, you should configure gpio18 as output mode and set it to hight level
before calling gpio_hold_dis.
Return
• ESP_OK Success
• ESP_ERR_NOT_SUPPORTED Not support pad hold function
Parameters
• gpio_num: GPIO number, only support output-capable GPIOs
void gpio_deep_sleep_hold_en(void)
Enable all digital gpio pad hold function during Deep-sleep.
When the chip is in Deep-sleep mode, all digital gpio will hold the state before sleep, and when the chip is
woken up, the status of digital gpio will not be held. Note that the pad hold feature only works when the chip
is in Deep-sleep mode, when not in sleep mode, the digital gpio state can be changed even you have called this
function.
Power down or call gpio_hold_dis will disable this function, otherwise, the digital gpio hold feature works as
long as the chip enter Deep-sleep.
void gpio_deep_sleep_hold_dis(void)
Disable all digital gpio pad hold function during Deep-sleep.
void gpio_iomux_in(uint32_t gpio_num, uint32_t signal_idx)
Set pad input to a peripheral signal through the IOMUX.
Parameters
• gpio_num: GPIO number of the pad.
• signal_idx: Peripheral signal id to input. One of the *_IN_IDX signals in soc/
gpio_sig_map.h.
void gpio_iomux_out(uint8_t gpio_num, int func, bool oen_inv)
Set peripheral output to an GPIO pad through the IOMUX.
Parameters
• gpio_num: gpio_num GPIO number of the pad.
• func: The function number of the peripheral pin to output pin. One of the FUNC_X_* of specified
pin (X) in soc/io_mux_reg.h.
• oen_inv: True if the output enable needs to be inverted, otherwise False.
esp_err_t gpio_sleep_sel_en(gpio_num_t gpio_num)
Enable SLP_SEL to change GPIO status automantically in lightsleep.
Return
• ESP_OK Success
Parameters
esp_err_t gpio_sleep_sel_dis(gpio_num_t gpio_num)
Disable SLP_SEL to change GPIO status automantically in lightsleep.
Return
• ESP_OK Success

Parameters
esp_err_t gpio_sleep_set_direction(gpio_num_t gpio_num, gpio_mode_t mode)
GPIO set direction at sleep.
Configure GPIO direction,such as output_only,input_only,output_and_input
Return
• ESP_OK Success
Parameters
• gpio_num: Configure GPIO pins number, it should be GPIO number. If you want to set direction
of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);
esp_err_t gpio_sleep_set_pull_mode(gpio_num_t gpio_num, gpio_pull_mode_t pull)
Configure GPIO pull-up/pull-down resistors at sleep.
Only pins that support both input & output have integrated pull-up and pull-down resistors. Input-only GPIOs
34-39 do not.
Return
• ESP_OK Success
• ESP_ERR_INVALID_ARG : Parameter error
Parameters
• gpio_num: GPIO number. If you want to set pull up or down mode for e.g. GPIO16, gpio_num
should be GPIO_NUM_16 (16);
• pull: GPIO pull up/down mode.
Macros
GPIO_PIN_COUNT
GPIO_IS_VALID_GPIO(gpio_num)
Check whether it is a valid GPIO number.
GPIO_IS_VALID_OUTPUT_GPIO(gpio_num)
Check whether it can be a valid GPIO number of output mode.
Type Definitions
typedef intr_handle_t gpio_isr_handle_t
Header File
• components/hal/include/hal/gpio_types.h
Structures
struct gpio_config_t
Configuration parameters of GPIO pad for gpio_config function.
Public Members
uint64_t pin_bit_mask
GPIO pin: set with bit mask, each bit maps to a GPIO
gpio_mode_t mode
GPIO mode: set input/output mode
gpio_pullup_t pull_up_en
GPIO pull-up

gpio_pulldown_t pull_down_en
GPIO pull-down
gpio_int_type_t intr_type
GPIO interrupt type
Macros
GPIO_SEL_0
Pin 0 selected
GPIO_SEL_1
Pin 1 selected
GPIO_SEL_2
Pin 2 selected
GPIO_SEL_3
Pin 3 selected
GPIO_SEL_4
Pin 4 selected
GPIO_SEL_5
Pin 5 selected
GPIO_SEL_6
Pin 6 selected
GPIO_SEL_7
Pin 7 selected
GPIO_SEL_8
Pin 8 selected
GPIO_SEL_9
Pin 9 selected
GPIO_SEL_10
Pin 10 selected
GPIO_SEL_11
Pin 11 selected
GPIO_SEL_12
Pin 12 selected
GPIO_SEL_13
Pin 13 selected
GPIO_SEL_14
Pin 14 selected
GPIO_SEL_15
Pin 15 selected
GPIO_SEL_16
Pin 16 selected
GPIO_SEL_17
Pin 17 selected
GPIO_SEL_18
Pin 18 selected
GPIO_SEL_19
Pin 19 selected

GPIO_SEL_20
Pin 20 selected
GPIO_SEL_21
Pin 21 selected
GPIO_SEL_22
Pin 22 selected
GPIO_SEL_23
Pin 23 selected
GPIO_SEL_25
Pin 25 selected
GPIO_SEL_26
Pin 26 selected
GPIO_SEL_27
Pin 27 selected
GPIO_SEL_28
Pin 28 selected
GPIO_SEL_29
Pin 29 selected
GPIO_SEL_30
Pin 30 selected
GPIO_SEL_31
Pin 31 selected
GPIO_SEL_32
Pin 32 selected
GPIO_SEL_33
Pin 33 selected
GPIO_SEL_34
Pin 34 selected
GPIO_SEL_35
Pin 35 selected
GPIO_SEL_36
Pin 36 selected
GPIO_SEL_37
Pin 37 selected
GPIO_SEL_38
Pin 38 selected
GPIO_SEL_39
Pin 39 selected
GPIO_PIN_REG_0
GPIO_PIN_REG_1
GPIO_PIN_REG_2
GPIO_PIN_REG_3
GPIO_PIN_REG_4
GPIO_PIN_REG_5
GPIO_PIN_REG_6

GPIO_PIN_REG_7
GPIO_PIN_REG_8
GPIO_PIN_REG_9
GPIO_PIN_REG_10
GPIO_PIN_REG_11
GPIO_PIN_REG_12
GPIO_PIN_REG_13
GPIO_PIN_REG_14
GPIO_PIN_REG_15
GPIO_PIN_REG_16
GPIO_PIN_REG_17
GPIO_PIN_REG_18
GPIO_PIN_REG_19
GPIO_PIN_REG_20
GPIO_PIN_REG_21
GPIO_PIN_REG_22
GPIO_PIN_REG_23
GPIO_PIN_REG_24
GPIO_PIN_REG_25
GPIO_PIN_REG_26
GPIO_PIN_REG_27
GPIO_PIN_REG_28
GPIO_PIN_REG_29
GPIO_PIN_REG_30
GPIO_PIN_REG_31
GPIO_PIN_REG_32
GPIO_PIN_REG_33
GPIO_PIN_REG_34
GPIO_PIN_REG_35
GPIO_PIN_REG_36
GPIO_PIN_REG_37
GPIO_PIN_REG_38
GPIO_PIN_REG_39
GPIO_PIN_REG_40
GPIO_PIN_REG_41
GPIO_PIN_REG_42
GPIO_PIN_REG_43
GPIO_PIN_REG_44
GPIO_PIN_REG_45

GPIO_PIN_REG_46
GPIO_PIN_REG_47
GPIO_PIN_REG_48
Type Definitions
typedef void (*gpio_isr_t)(void *)
Enumerations
enum gpio_port_t
Values:
GPIO_PORT_0 = 0
GPIO_PORT_MAX
enum gpio_num_t
Values:
GPIO_NUM_NC = -1
Use to signal not connected to S/W
GPIO_NUM_0 = 0
GPIO0, input and output
GPIO_NUM_1 = 1
GPIO_NUM_2 = 2
GPIO_NUM_3 = 3
GPIO_NUM_4 = 4
GPIO_NUM_5 = 5
GPIO_NUM_6 = 6
GPIO_NUM_7 = 7
GPIO_NUM_8 = 8
GPIO_NUM_9 = 9
GPIO_NUM_10 = 10
GPIO_NUM_11 = 11
GPIO_NUM_12 = 12
GPIO_NUM_13 = 13
GPIO_NUM_14 = 14

GPIO_NUM_15 = 15
GPIO_NUM_16 = 16
GPIO_NUM_17 = 17
GPIO_NUM_18 = 18
GPIO_NUM_19 = 19
GPIO_NUM_20 = 20
GPIO_NUM_21 = 21
GPIO_NUM_22 = 22
GPIO_NUM_23 = 23
GPIO_NUM_25 = 25
GPIO_NUM_26 = 26
GPIO_NUM_27 = 27
GPIO_NUM_28 = 28
GPIO_NUM_29 = 29
GPIO_NUM_30 = 30
GPIO_NUM_31 = 31
GPIO_NUM_32 = 32
GPIO_NUM_33 = 33
GPIO_NUM_34 = 34
GPIO34, input mode only
GPIO_NUM_35 = 35
GPIO_NUM_36 = 36
GPIO_NUM_37 = 37
GPIO_NUM_38 = 38

GPIO_NUM_39 = 39
GPIO_NUM_MAX
enum gpio_int_type_t
Values:
GPIO_INTR_DISABLE = 0
Disable GPIO interrupt
GPIO_INTR_POSEDGE = 1
GPIO interrupt type : rising edge
GPIO_INTR_NEGEDGE = 2
GPIO interrupt type : falling edge
GPIO_INTR_ANYEDGE = 3
GPIO interrupt type : both rising and falling edge
GPIO_INTR_LOW_LEVEL = 4
GPIO interrupt type : input low level trigger
GPIO_INTR_HIGH_LEVEL = 5
GPIO interrupt type : input high level trigger
GPIO_INTR_MAX
enum gpio_mode_t
Values:
GPIO_MODE_DISABLE = GPIO_MODE_DEF_DISABLE
GPIO mode : disable input and output
GPIO_MODE_INPUT = GPIO_MODE_DEF_INPUT
GPIO mode : input only
GPIO_MODE_OUTPUT = GPIO_MODE_DEF_OUTPUT
GPIO mode : output only mode
GPIO_MODE_OUTPUT_OD = ((GPIO_MODE_DEF_OUTPUT) | (GPIO_MODE_DEF_OD))
GPIO mode : output only with open-drain mode
GPIO_MODE_INPUT_OUTPUT_OD = ((GPIO_MODE_DEF_INPUT) | (GPIO_MODE_DEF_OUTPUT) | (GPIO_MODE_D
GPIO mode : output and input with open-drain mode
GPIO_MODE_INPUT_OUTPUT = ((GPIO_MODE_DEF_INPUT) | (GPIO_MODE_DEF_OUTPUT))
GPIO mode : output and input mode
enum gpio_pullup_t
Values:
GPIO_PULLUP_DISABLE = 0x0
Disable GPIO pull-up resistor
GPIO_PULLUP_ENABLE = 0x1
Enable GPIO pull-up resistor
enum gpio_pulldown_t
Values:
GPIO_PULLDOWN_DISABLE = 0x0
Disable GPIO pull-down resistor
GPIO_PULLDOWN_ENABLE = 0x1
Enable GPIO pull-down resistor
enum gpio_pull_mode_t
Values:

GPIO_PULLUP_ONLY
Pad pull up
GPIO_PULLDOWN_ONLY
Pad pull down
GPIO_PULLUP_PULLDOWN
Pad pull up + pull down
GPIO_FLOATING
Pad floating
enum gpio_drive_cap_t
Values:
GPIO_DRIVE_CAP_0 = 0
Pad drive capability: weak
Pad drive capability: stronger
Pad drive capability: medium
GPIO_DRIVE_CAP_DEFAULT = 2
Pad drive capability: medium
Pad drive capability: strongest
GPIO_DRIVE_CAP_MAX
API Reference - RTC GPIO
Header File
• components/driver/include/driver/rtc_io.h
Functions
static bool rtc_gpio_is_valid_gpio(gpio_num_t gpio_num)
Determine if the specified GPIO is a valid RTC GPIO.
Return true if GPIO is valid for RTC GPIO use. false otherwise.
Parameters
static int rtc_io_number_get(gpio_num_t gpio_num)
Get RTC IO index number by gpio number.
Return >=0: Index of rtcio. -1 : The gpio is not rtcio.
Parameters
esp_err_t rtc_gpio_init(gpio_num_t gpio_num)
Init a GPIO as RTC GPIO.
This function must be called when initializing a pad for an analog function.
Return
• ESP_OK success
• ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters
• gpio_num: GPIO number (e.g. GPIO_NUM_12)
esp_err_t rtc_gpio_deinit(gpio_num_t gpio_num)
Init a GPIO as digital GPIO.

Return
• ESP_OK success
Parameters
uint32_t rtc_gpio_get_level(gpio_num_t gpio_num)
Get the RTC IO input level.
Return
• 1 High level
• 0 Low level
Parameters
esp_err_t rtc_gpio_set_level(gpio_num_t gpio_num, uint32_t level)
Set the RTC IO output level.
Return
• ESP_OK Success
Parameters
• level: output level
esp_err_t rtc_gpio_set_direction(gpio_num_t gpio_num, rtc_gpio_mode_t mode)
RTC GPIO set direction.
Configure RTC GPIO direction, such as output only, input only, output and input.
Return
• ESP_OK Success
Parameters
esp_err_t rtc_gpio_set_direction_in_sleep(gpio_num_t gpio_num, rtc_gpio_mode_t mode)
RTC GPIO set direction in deep sleep mode or disable sleep status (default). In some application scenarios,
IO needs to have another states during deep sleep.
NOTE: ESP32 support INPUT_ONLY mode. ESP32S2 support INPUT_ONLY, OUTPUT_ONLY, IN-
PUT_OUTPUT mode.
Return
• ESP_OK Success
Parameters
esp_err_t rtc_gpio_pullup_en(gpio_num_t gpio_num)
RTC GPIO pullup enable.
This function only works for RTC IOs. In general, call gpio_pullup_en, which will work both for normal
GPIOs and RTC IOs.
Return
• ESP_OK Success
Parameters

esp_err_t rtc_gpio_pulldown_en(gpio_num_t gpio_num)

RTC GPIO pulldown enable.
This function only works for RTC IOs. In general, call gpio_pulldown_en, which will work both for normal
GPIOs and RTC IOs.
Return
• ESP_OK Success
Parameters
esp_err_t rtc_gpio_pullup_dis(gpio_num_t gpio_num)
RTC GPIO pullup disable.
This function only works for RTC IOs. In general, call gpio_pullup_dis, which will work both for normal
GPIOs and RTC IOs.
Return
• ESP_OK Success
Parameters
esp_err_t rtc_gpio_pulldown_dis(gpio_num_t gpio_num)
RTC GPIO pulldown disable.
This function only works for RTC IOs. In general, call gpio_pulldown_dis, which will work both for normal
GPIOs and RTC IOs.
Return
• ESP_OK Success
Parameters
esp_err_t rtc_gpio_set_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t strength)
Set RTC GPIO pad drive capability.
Return
• ESP_OK Success
Parameters
• strength: Drive capability of the pad
esp_err_t rtc_gpio_get_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t *strength)
Get RTC GPIO pad drive capability.
Return
• ESP_OK Success
Parameters
• strength: Pointer to accept drive capability of the pad
esp_err_t rtc_gpio_hold_en(gpio_num_t gpio_num)
Enable hold function on an RTC IO pad.
Enabling HOLD function will cause the pad to latch current values of input enable, output enable, output value,
function, drive strength values. This function is useful when going into light or deep sleep mode to prevent the
pin configuration from changing.
Return
• ESP_OK Success

Parameters
esp_err_t rtc_gpio_hold_dis(gpio_num_t gpio_num)
Disable hold function on an RTC IO pad.
Disabling hold function will allow the pad receive the values of input enable, output enable, output value,
function, drive strength from RTC_IO peripheral.
Return
• ESP_OK Success
Parameters
esp_err_t rtc_gpio_isolate(gpio_num_t gpio_num)
Helper function to disconnect internal circuits from an RTC IO This function disables input, output, pullup,
pulldown, and enables hold feature for an RTC IO. Use this function if an RTC IO needs to be disconnected
from internal circuits in deep sleep, to minimize leakage current.
In particular, for ESP32-WROVER module, call rtc_gpio_isolate(GPIO_NUM_12) before entering deep
sleep, to reduce deep sleep current.
Return
• ESP_ERR_INVALID_ARG if GPIO is not an RTC IO
Parameters
• gpio_num: GPIO number (e.g. GPIO_NUM_12).
esp_err_t rtc_gpio_force_hold_all(void)
Enable force hold signal for all RTC IOs.
Each RTC pad has a force hold input signal from the RTC controller. If this signal is set, pad latches current
values of input enable, function, output enable, and other signals which come from the RTC mux. Force hold
signal is enabled before going into deep sleep for pins which are used for EXT1 wakeup.
esp_err_t rtc_gpio_force_hold_dis_all(void)
Disable force hold signal for all RTC IOs.
esp_err_t rtc_gpio_wakeup_enable(gpio_num_t gpio_num, gpio_int_type_t intr_type)
Enable wakeup from sleep mode using specific GPIO.
Return
• ESP_ERR_INVALID_ARG if gpio_num is not an RTC IO, or intr_type is not one of
GPIO_INTR_HIGH_LEVEL, GPIO_INTR_LOW_LEVEL.
Parameters
• intr_type: Wakeup on high level (GPIO_INTR_HIGH_LEVEL) or low level
(GPIO_INTR_LOW_LEVEL)
esp_err_t rtc_gpio_wakeup_disable(gpio_num_t gpio_num)
Disable wakeup from sleep mode using specific GPIO.
Return
• ESP_ERR_INVALID_ARG if gpio_num is not an RTC IO
Parameters
Macros
RTC_GPIO_IS_VALID_GPIO(gpio_num)

Header File
• components/hal/include/hal/rtc_io_types.h
Enumerations
enum rtc_gpio_mode_t
RTCIO output/input mode type.
Values:
RTC_GPIO_MODE_INPUT_ONLY
Pad input
RTC_GPIO_MODE_OUTPUT_ONLY
Pad output
RTC_GPIO_MODE_INPUT_OUTPUT
Pad input + output
RTC_GPIO_MODE_DISABLED
Pad (output + input) disable
RTC_GPIO_MODE_OUTPUT_OD
Pad open-drain output
RTC_GPIO_MODE_INPUT_OUTPUT_OD
Pad input + open-drain output
2.3.5 Inter-Integrated Circuit (I2C)
Overview
I2C is a serial, synchronous, half-duplex communication protocol that allows co-existence of multiple masters and
slaves on the same bus. The I2C bus consists of two lines: serial data line (SDA) and serial clock (SCL). Both lines
require pull-up resistors.
With such advantages as simplicity and low manufacturing cost, I2C is mostly used for communication of low-speed
peripheral devices over short distances (within one foot).
ESP32 has two I2C controllers (also referred to as ports) which are responsible for handling communications on the
I2C bus. Each I2C controller can operate as master or slave. As an example, one controller can act as a master and
the other as a slave at the same time.
Driver Features
I2C driver governs communications of devices over the I2C bus. The driver supports the following features:
• Reading and writing bytes in Master mode
• Slave mode
• Reading and writing to registers which are in turn read/written by the master
Driver Usage
The following sections describe typical steps of configuring and operating the I2C driver:
1. Configuration - set the initialization parameters (master or slave mode, GPIO pins for SDA and SCL, clock
speed, etc.)
2. Install Driver- activate the driver on one of the two I2C controllers as a master or slave
3. Depending on whether you configure the driver for a master or slave, choose the appropriate item
a) Communication as Master - handle communications (master)
b) Communication as Slave - respond to messages from the master (slave)

4. Interrupt Handling - configure and service I2C interrupts

5. Customized Configuration - adjust default I2C communication parameters (timings, bit order, etc.)
6. Error Handling - how to recognize and handle driver configuration and communication errors
7. Delete Driver- release resources used by the I2C driver when communication ends
Configuration To establish I2C communication, start by configuring the driver. This is done by setting the param-
eters of the structure i2c_config_t:
• Set I2C mode of operation - slave or master from i2c_mode_t
• Configure communication pins
– Assign GPIO pins for SDA and SCL signals
– Set whether to enable ESP32 s internal pull-ups
• (Master only) Set I2C clock speed
• (Slave only) Configure the following
– Whether to enable 10 bit address mode
– Define slave address
After that, initialize the configuration for a given I2C port. For this, call the function i2c_param_config() and
pass to it the port number and the structure i2c_config_t.
Configuration example (master):
int i2c_master_port = 0;
i2c_config_t conf = {
.mode = I2C_MODE_MASTER,
.sda_io_num = I2C_MASTER_SDA_IO, // select GPIO specific to your␣
,→project
.sda_pullup_en = GPIO_PULLUP_ENABLE,
.scl_io_num = I2C_MASTER_SCL_IO, // select GPIO specific to your␣
,→project
.scl_pullup_en = GPIO_PULLUP_ENABLE,
.master.clk_speed = I2C_MASTER_FREQ_HZ, // select frequency specific to your␣
,→project
// .clk_flags = 0, /*!< Optional, you can use I2C_SCLK_SRC_FLAG_*␣

,→flags to choose i2c source clock here. */
};
Configuration example (slave):
int i2c_slave_port = I2C_SLAVE_NUM;

i2c_config_t conf_slave = {
.sda_io_num = I2C_SLAVE_SDA_IO, // select GPIO specific to your␣
,→project
.sda_pullup_en = GPIO_PULLUP_ENABLE,
.scl_io_num = I2C_SLAVE_SCL_IO, // select GPIO specific to your␣
,→project
.scl_pullup_en = GPIO_PULLUP_ENABLE,
.mode = I2C_MODE_SLAVE,
.slave.addr_10bit_en = 0,
.slave.slave_addr = ESP_SLAVE_ADDR, // address of your project
};
At this stage, i2c_param_config() also sets a few other I2C configuration parameters to default values that are
defined by the I2C specification. For more details on the values and how to modify them, see Customized Configura-
tion.
Source Clock Configuration Clock sources allocator is added for supporting different clock sources. The clock
allocator will choose one clock source that meets all the requirements of frequency and capability (as requested in
i2c_config_t::clk_flags).

When i2c_config_t::clk_flags is 0, the clock allocator will select only according to the desired frequency.
If no special capabilities are needed, such as APB, you can configure the clock allocator to select the source clock only
according to the desired frequency. For this, set i2c_config_t::clk_flags to 0. For clock characteristics,
see the table below.
Note: A clock is not a valid option, if it doesn t meet the requested capabilities, i.e. any bit of requested capabilities
(clk_flags) is 0 in the clock s capabilities.
Table 2: Characteristics of ESP32 clock sources

Clock Clock MAX freq for SCL Clock capabilities
name fre-
quency
APB 80 4 MHz /
clock MHz
Explanations for i2c_config_t::clk_flags are as follows:

1. I2C_SCLK_SRC_FLAG_AWARE_DFS: Clock s baud rate will not change while APB clock is changing.
2. I2C_SCLK_SRC_FLAG_LIGHT_SLEEP: It supports Light-sleep mode, which APB clock cannot do.
3. Some flags may not be supported on ESP32, reading technical reference manual before using it.
Note: The clock frequency of SCL in master mode should not be lager than max frequency for SCL mentioned in
the table above.
Install Driver After the I2C driver is configured, install it by calling the function i2c_driver_install()
with the following parameters:
• Port number, one of the two port numbers from i2c_port_t
• Master or slave, selected from i2c_mode_t
• (Slave only) Size of buffers to allocate for sending and receiving data. As I2C is a master-centric bus, data
can only go from the slave to the master at the master s request. Therefore, the slave will usually have a send
buffer where the slave application writes data. The data remains in the send buffer to be read by the master at
the master s own discretion.
• Flags for allocating the interrupt (see ESP_INTR_FLAG_* values in
esp_hw_support/include/esp_intr_alloc.h)
Communication as Master After installing the I2C driver, ESP32 is ready to communicate with other I2C devices.
ESP32 s I2C controller operating as master is responsible for establishing communication with I2C slave devices
and sending commands to trigger a slave to action, for example, to take a measurement and send the readings back
to the master.
For better process organization, the driver provides a container, called a command link , that should be populated
with a sequence of commands and then passed to the I2C controller for execution.
Master Write The example below shows how to build a command link for an I2C master to send n bytes to a slave.
The following describes how a command link for a master write is set up and what comes inside:
1. Create a command link with i2c_cmd_link_create().
Then, populate it with the series of data to be sent to the slave:
a) Start bit - i2c_master_start()
b) Slave address - i2c_master_write_byte(). The single byte address is provided as an argument
of this function call.
c) Data - One or more bytes as an argument of i2c_master_write()

Fig. 9: I2C command link - master write example
d) Stop bit - i2c_master_stop()

Both functions i2c_master_write_byte() and i2c_master_write() have an addi-
tional argument specifying whether the master should ensure that it has received the ACK bit.
2. Trigger the execution of the command link by I2C controller by calling i2c_master_cmd_begin().
Once the execution is triggered, the command link cannot be modified.
3. After the commands are transmitted, release the resources used by the command link by calling
i2c_cmd_link_delete().
Master Read The example below shows how to build a command link for an I2C master to read n bytes from a
slave.
Fig. 10: I2C command link - master read example
Compared to writing data, the command link is populated in Step 4 not with i2c_master_write... func-
tions but with i2c_master_read_byte() and / or i2c_master_read(). Also, the last read in Step 5 is
configured so that the master does not provide the ACK bit.
Indicating Write or Read After sending a slave address (see Step 3 on both diagrams above), the master either
writes or reads from the slave.

The information on what the master will actually do is hidden in the least significant bit of the slave s address.
For this reason, the command link sent by the master to write data to the slave contains the address
(ESP_SLAVE_ADDR << 1) | I2C_MASTER_WRITE and looks as follows:
i2c_master_write_byte(cmd, (ESP_SLAVE_ADDR << 1) | I2C_MASTER_WRITE, ACK_EN);
Likewise, the command link to read from the slave looks as follows:
i2c_master_write_byte(cmd, (ESP_SLAVE_ADDR << 1) | I2C_MASTER_READ, ACK_EN);
Communication as Slave After installing the I2C driver, ESP32 is ready to communicate with other I2C devices.
The API provides the following functions for slaves
• i2c_slave_read_buffer()
Whenever the master writes data to the slave, the slave will automatically store it in the receive
buffer. This allows the slave application to call the function i2c_slave_read_buffer() at
its own discretion. This function also has a parameter to specify block time if no data is in the
receive buffer. This will allow the slave application to wait with a specified timeout for data to
arrive to the buffer.
• i2c_slave_write_buffer()
The send buffer is used to store all the data that the slave wants to send to the mas-
ter in FIFO order. The data stays there until the master requests for it. The function
i2c_slave_write_buffer() has a parameter to specify block time if the send buffer is
full. This will allow the slave application to wait with a specified timeout for the adequate amount
of space to become available in the send buffer.
A code example showing how to use these functions can be found in peripherals/i2c.
Interrupt Handling During driver installation, an interrupt handler is installed by default. However, you can
register your own interrupt handler instead of the default one by calling the function i2c_isr_register().
When implementing your own interrupt handler, refer to ESP32 Technical Reference Manual > I2C Controller (I2C)
> Interrupts [PDF] for the description of interrupts triggered by the I2C controller.
To delete an interrupt handler, call i2c_isr_free().
Customized Configuration As mentioned at the end of Section Configuration, when the function
i2c_param_config() initializes the driver configuration for an I2C port, it also sets several I2C communication
parameters to default values defined in the I2C specification. Some other related parameters are pre-configured in
registers of the I2C controller.
All these parameters can be changed to user-defined values by calling dedicated functions given in the table be-
low. Please note that the timing values are defined in APB clock cycles. The frequency of APB is specified in
I2C_APB_CLK_FREQ.
Table 3: Other Configurable I2C Communication Parameters

Parameters to Change Function
High time and low time for SCL pulses i2c_set_period()
SCL and SDA signal timing used during generation of start signals i2c_set_start_timing()
SCL and SDA signal timing used during generation of stop signals i2c_set_stop_timing()
Timing relationship between SCL and SDA signals when slave samples, i2c_set_data_timing()
as well as when master toggles
I2C timeout i2c_set_timeout()
Choice between transmitting / receiving the LSB or MSB first, choose i2c_set_data_mode()
one of the modes defined in i2c_trans_mode_t
Each of the above functions has a _get_ counterpart to check the currently set value. For example, to check the I2C
timeout value, call i2c_get_timeout().

To check the default parameter values which are set during the driver configuration process, please refer to the file
driver/i2c.c and look for defines with the suffix _DEFAULT.
You can also select different pins for SDA and SCL signals and alter the configuration of pull-ups with the function
i2c_set_pin(). If you want to modify already entered values, use the function i2c_param_config().
Note: ESP32 s internal pull-ups are in the range of tens of kOhm, which is, in most cases, insufficient for use as
I2C pull-ups. Users are advised to use external pull-ups with values described in the I2C specification.
Error Handling The majority of I2C driver functions either return ESP_OK on successful completion or a specific
error code on failure. It is a good practice to always check the returned values and implement error handling. The
driver also prints out log messages that contain error details, e.g., when checking the validity of entered configuration.
For details please refer to the file driver/i2c.c and look for defines with the suffix _ERR_STR.
Use dedicated interrupts to capture communication failures. For instance, if a slave stretches the clock for too long
while preparing the data to send back to master, the interrupt I2C_TIME_OUT_INT will be triggered. For detailed
information, see Interrupt Handling.
In case of a communication failure, you can reset the internal hardware buffers by calling the functions
i2c_reset_tx_fifo() and i2c_reset_rx_fifo() for the send and receive buffers respectively.
Delete Driver When the I2C communication is established with the function i2c_driver_install() and
is not required for some substantial amount of time, the driver may be deinitialized to release allocated resources by
calling i2c_driver_delete().
Before calling i2c_driver_delete() to remove i2c driver, please make sure that all threads have stopped using
the driver in any way, because this function does not guarantee thread safety.
Application Example
I2C master and slave example: peripherals/i2c.
API Reference
Header File
• components/driver/include/driver/i2c.h
Functions
esp_err_t i2c_driver_install(i2c_port_t i2c_num, i2c_mode_t mode, size_t slv_rx_buf_len, size_t
slv_tx_buf_len, int intr_alloc_flags)
Install an I2C driver.
Note In master mode, if the cache is likely to be disabled(such as write flash) and the slave is time-sensitive,
ESP_INTR_FLAG_IRAM is suggested to be used. In this case, please use the memory allocated from
internal RAM in i2c read and write function, because we can not access the psram(if psram is enabled)
in interrupt handle function when cache is disabled.
Return
• ESP_OK Success
• ESP_FAIL Driver installation error
Parameters
• i2c_num: I2C port number
• mode: I2C mode (either master or slave)
• slv_rx_buf_len: Receiving buffer size. Only slave mode will use this value, it is ignored in
master mode.

• slv_tx_buf_len: Sending buffer size. Only slave mode will use this value, it is ignored in
master mode.
esp_err_t i2c_driver_delete(i2c_port_t i2c_num)
Delete I2C driver.
Note This function does not guarantee thread safety. Please make sure that no thread will continuously hold
semaphores before calling the delete function.
Return
• ESP_OK Success
Parameters
• i2c_num: I2C port to delete
esp_err_t i2c_param_config(i2c_port_t i2c_num, const i2c_config_t *i2c_conf)
Configure an I2C bus with the given configuration.
Return
• ESP_OK Success
Parameters
• i2c_num: I2C port to configure
• i2c_conf: Pointer to the I2C configuration
esp_err_t i2c_reset_tx_fifo(i2c_port_t i2c_num)
reset I2C tx hardware fifo
Return
• ESP_OK Success
Parameters
esp_err_t i2c_reset_rx_fifo(i2c_port_t i2c_num)
reset I2C rx fifo
Return
• ESP_OK Success
Parameters
esp_err_t i2c_isr_register(i2c_port_t i2c_num, void (*fn))void *
, void *arg, int intr_alloc_flags, intr_handle_t *handleRegister an I2C ISR handler.
Return
• ESP_OK Success
Parameters
• i2c_num: I2C port number to attach handler to
• fn: ISR handler function
• arg: Parameter for the ISR handler
• handle: Handle return from esp_intr_alloc.
esp_err_t i2c_isr_free(intr_handle_t handle)
Delete and free I2C ISR handle.
Return
• ESP_OK Success
Parameters

• handle: Handle of isr to delete.

esp_err_t i2c_set_pin(i2c_port_t i2c_num, int sda_io_num, int scl_io_num, bool sda_pullup_en, bool
scl_pullup_en, i2c_mode_t mode)
Configure GPIO pins for I2C SCK and SDA signals.
Return
• ESP_OK Success
Parameters
• sda_io_num: GPIO number for I2C SDA signal
• scl_io_num: GPIO number for I2C SCL signal
• sda_pullup_en: Enable the internal pullup for SDA pin
• scl_pullup_en: Enable the internal pullup for SCL pin
• mode: I2C mode
esp_err_t i2c_master_write_to_device(i2c_port_t i2c_num, uint8_t device_address, const
uint8_t *write_buffer, size_t write_size, TickType_t
ticks_to_wait)
Perform a write to a device connected to a particular I2C port. This function is a wrapper to
i2c_master_start(), i2c_master_write(), i2c_master_read(), etc It shall only be
called in I2C master mode.
Return
• ESP_OK Success
• ESP_FAIL Sending command error, slave hasn t ACK the transfer.
• ESP_ERR_INVALID_STATE I2C driver not installed or not in master mode.
• ESP_ERR_TIMEOUT Operation timeout because the bus is busy.
Parameters
• i2c_num: I2C port number to perform the transfer on
• device_address: I2C device s 7-bit address
• write_buffer: Bytes to send on the bus
• write_size: Size, in bytes, of the write buffer
• ticks_to_wait: Maximum ticks to wait before issuing a timeout.
esp_err_t i2c_master_read_from_device(i2c_port_t i2c_num, uint8_t device_address,
uint8_t *read_buffer, size_t read_size, TickType_t
ticks_to_wait)
Perform a read to a device connected to a particular I2C port. This function is a wrapper to
i2c_master_start(), i2c_master_write(), i2c_master_read(), etc It shall only be
called in I2C master mode.
Return
• ESP_OK Success
Parameters
• read_buffer: Buffer to store the bytes received on the bus
• read_size: Size, in bytes, of the read buffer
esp_err_t i2c_master_write_read_device(i2c_port_t i2c_num, uint8_t device_address,
const uint8_t *write_buffer, size_t write_size,
uint8_t *read_buffer, size_t read_size, TickType_t
ticks_to_wait)
Perform a write followed by a read to a device on the I2C bus. A repeated start signal is used between the

write and read, thus, the bus is not released until the two transactions are finished. This function is a
wrapper to i2c_master_start(), i2c_master_write(), i2c_master_read(), etc It shall
only be called in I2C master mode.
Return
• ESP_OK Success
Parameters
• write_buffer: Bytes to send on the bus
• write_size: Size, in bytes, of the write buffer
• read_buffer: Buffer to store the bytes received on the bus
• read_size: Size, in bytes, of the read buffer
i2c_cmd_handle_t i2c_cmd_link_create_static(uint8_t *buffer, uint32_t size)
Create and initialize an I2C commands list with a given buffer. All the allocations for data or signals (START,
STOP, ACK, ) will be performed within this buffer. This buffer must be valid during the whole transaction.
After finishing the I2C transactions, it is required to call i2c_cmd_link_delete_static().
Note It is highly advised to not allocate this buffer on the stack. The size of the data used
underneath may increase in the future, resulting in a possible stack overflow as the macro
I2C_LINK_RECOMMENDED_SIZE would also return a bigger value. A better option is to use a buffer
allocated statically or dynamically (with malloc).
Return Handle to the I2C command link or NULL if the buffer provided is too small, please use
I2C_LINK_RECOMMENDED_SIZE macro to get the recommended size for the buffer.
Parameters
• buffer: Buffer to use for commands allocations
• size: Size in bytes of the buffer
i2c_cmd_handle_t i2c_cmd_link_create(void)
Create and initialize an I2C commands list with a given buffer. After finishing the I2C transactions, it is
required to call i2c_cmd_link_delete() to release and return the resources. The required bytes will
be dynamically allocated.
Return Handle to the I2C command link
void i2c_cmd_link_delete_static(i2c_cmd_handle_t cmd_handle)
Free the I2C commands list allocated statically with i2c_cmd_link_create_static.
Parameters
• cmd_handle: I2C commands list allocated statically. This handle should be created thanks to
i2c_cmd_link_create_static() function
void i2c_cmd_link_delete(i2c_cmd_handle_t cmd_handle)
Free the I2C commands list.
Parameters
• cmd_handle: I2C commands list. This handle should be created thanks to
i2c_cmd_link_create() function
esp_err_t i2c_master_start(i2c_cmd_handle_t cmd_handle)
Queue a START signal to the given commands list. This function shall only be called in I2C master mode.
Call i2c_master_cmd_begin() to send all the queued commands.
Return
• ESP_OK Success
• ESP_ERR_NO_MEM The static buffer used to create cmd_handler is too small
• ESP_FAIL No more memory left on the heap

Parameters
• cmd_handle: I2C commands list
esp_err_t i2c_master_write_byte(i2c_cmd_handle_t cmd_handle, uint8_t data, bool ack_en)
Queue a write byte command to the commands list. A single byte will be sent on the I2C port. This function
shall only be called in I2C master mode. Call i2c_master_cmd_begin() to send all queued commands.
Return
• ESP_OK Success
Parameters
• data: Byte to send on the port
• ack_en: Enable ACK signal
esp_err_t i2c_master_write(i2c_cmd_handle_t cmd_handle, const uint8_t *data, size_t data_len,
bool ack_en)
Queue a write (multiple) bytes command to the commands list. This function shall only be called in I2C
master mode. Call i2c_master_cmd_begin() to send all queued commands.
Return
• ESP_OK Success
Parameters
• data: Bytes to send. This buffer shall remain valid until the transaction is finished. If the PSRAM
is enabled and intr_flag is set to ESP_INTR_FLAG_IRAM, data should be allocated from
internal RAM.
• data_len: Length, in bytes, of the data buffer
• ack_en: Enable ACK signal
esp_err_t i2c_master_read_byte(i2c_cmd_handle_t cmd_handle, uint8_t *data, i2c_ack_type_t ack)
Queue a read byte command to the commands list. A single byte will be read on the I2C bus. This function
shall only be called in I2C master mode. Call i2c_master_cmd_begin() to send all queued commands.
Return
• ESP_OK Success
Parameters
• data: Pointer where the received byte will the stored. This buffer shall remain valid until the
transaction is finished.
• ack: ACK signal
esp_err_t i2c_master_read(i2c_cmd_handle_t cmd_handle, uint8_t *data, size_t data_len,
i2c_ack_type_t ack)
Queue a read (multiple) bytes command to the commands list. Multiple bytes will be read on the I2C
bus. This function shall only be called in I2C master mode. Call i2c_master_cmd_begin() to send all
queued commands.
Return
• ESP_OK Success
Parameters


• data: Pointer where the received bytes will the stored. This buffer shall remain valid until the
transaction is finished.
• data_len: Size, in bytes, of the data buffer
• ack: ACK signal
esp_err_t i2c_master_stop(i2c_cmd_handle_t cmd_handle)
Queue a STOP signal to the given commands list. This function shall only be called in I2C master mode.
Call i2c_master_cmd_begin() to send all the queued commands.
Return
• ESP_OK Success
Parameters
esp_err_t i2c_master_cmd_begin(i2c_port_t i2c_num, i2c_cmd_handle_t cmd_handle, TickType_t
ticks_to_wait)
Send all the queued commands on the I2C bus, in master mode. The task will be blocked until all the commands
have been sent out. The I2C APIs are not thread-safe, if you want to use one I2C port in different tasks, you
need to take care of the multi-thread issue. This function shall only be called in I2C master mode.
Return
• ESP_OK Success
Parameters
int i2c_slave_write_buffer(i2c_port_t i2c_num, const uint8_t *data, int size, TickType_t
ticks_to_wait)
Write bytes to internal ringbuffer of the I2C slave data. When the TX fifo empty, the ISR will fill the hardware
FIFO with the internal ringbuffer s data.
Note This function shall only be called in I2C slave mode.
Return
• ESP_FAIL (-1) Parameter error
• Other (>=0) The number of data bytes pushed to the I2C slave buffer.
Parameters
• data: Bytes to write into internal buffer
• size: Size, in bytes, of data buffer
• ticks_to_wait: Maximum ticks to wait.
int i2c_slave_read_buffer(i2c_port_t i2c_num, uint8_t *data, size_t max_size, TickType_t
ticks_to_wait)
Read bytes from I2C internal buffer. When the I2C bus receives data, the ISR will copy them from the hardware
RX FIFO to the internal ringbuffer. Calling this function will then copy bytes from the internal ringbuffer to
the data user buffer.
Note This function shall only be called in I2C slave mode.
Return
• ESP_FAIL(-1) Parameter error
• Others(>=0) The number of data bytes read from I2C slave buffer.
Parameters
• data: Buffer to fill with ringbuffer s bytes

• max_size: Maximum bytes to read

• ticks_to_wait: Maximum waiting ticks
esp_err_t i2c_set_period(i2c_port_t i2c_num, int high_period, int low_period)
Set I2C master clock period.
Return
• ESP_OK Success
Parameters
• high_period: Clock cycle number during SCL is high level, high_period is a 14 bit value
• low_period: Clock cycle number during SCL is low level, low_period is a 14 bit value
esp_err_t i2c_get_period(i2c_port_t i2c_num, int *high_period, int *low_period)
Get I2C master clock period.
Return
• ESP_OK Success
Parameters
• high_period: pointer to get clock cycle number during SCL is high level, will get a 14 bit value
• low_period: pointer to get clock cycle number during SCL is low level, will get a 14 bit value
esp_err_t i2c_filter_enable(i2c_port_t i2c_num, uint8_t cyc_num)
Enable hardware filter on I2C bus Sometimes the I2C bus is disturbed by high frequency noise(about 20ns),
or the rising edge of the SCL clock is very slow, these may cause the master state machine to break. Enable
hardware filter can filter out high frequency interference and make the master more stable.
Note Enable filter will slow down the SCL clock.
Return
• ESP_OK Success
Parameters
• i2c_num: I2C port number to filter
• cyc_num: the APB cycles need to be filtered (0<= cyc_num <=7). When the period of a pulse is
less than cyc_num * APB_cycle, the I2C controller will ignore this pulse.
esp_err_t i2c_filter_disable(i2c_port_t i2c_num)
Disable filter on I2C bus.
Return
• ESP_OK Success
Parameters
esp_err_t i2c_set_start_timing(i2c_port_t i2c_num, int setup_time, int hold_time)
set I2C master start signal timing
Return
• ESP_OK Success
Parameters
• setup_time: clock number between the falling-edge of SDA and rising-edge of SCL for start
mark, it s a 10-bit value.
• hold_time: clock num between the falling-edge of SDA and falling-edge of SCL for start mark,
it s a 10-bit value.
esp_err_t i2c_get_start_timing(i2c_port_t i2c_num, int *setup_time, int *hold_time)
get I2C master start signal timing

Return
• ESP_OK Success
Parameters
• setup_time: pointer to get setup time
• hold_time: pointer to get hold time
esp_err_t i2c_set_stop_timing(i2c_port_t i2c_num, int setup_time, int hold_time)
set I2C master stop signal timing
Return
• ESP_OK Success
Parameters
• setup_time: clock num between the rising-edge of SCL and the rising-edge of SDA, it s a
10-bit value.
• hold_time: clock number after the STOP bit s rising-edge, it s a 14-bit value.
esp_err_t i2c_get_stop_timing(i2c_port_t i2c_num, int *setup_time, int *hold_time)
get I2C master stop signal timing
Return
• ESP_OK Success
Parameters
• setup_time: pointer to get setup time.
• hold_time: pointer to get hold time.
esp_err_t i2c_set_data_timing(i2c_port_t i2c_num, int sample_time, int hold_time)
set I2C data signal timing
Return
• ESP_OK Success
Parameters
• sample_time: clock number I2C used to sample data on SDA after the rising-edge of SCL, it
s a 10-bit value
• hold_time: clock number I2C used to hold the data after the falling-edge of SCL, it s a 10-bit
value
esp_err_t i2c_get_data_timing(i2c_port_t i2c_num, int *sample_time, int *hold_time)
get I2C data signal timing
Return
• ESP_OK Success
Parameters
• sample_time: pointer to get sample time
• hold_time: pointer to get hold time
esp_err_t i2c_set_timeout(i2c_port_t i2c_num, int timeout)
set I2C timeout value
Return
• ESP_OK Success
Parameters

• timeout: timeout value for I2C bus (unit: APB 80Mhz clock cycle)
esp_err_t i2c_get_timeout(i2c_port_t i2c_num, int *timeout)
get I2C timeout value
Return
• ESP_OK Success
Parameters
• timeout: pointer to get timeout value
esp_err_t i2c_set_data_mode(i2c_port_t i2c_num, i2c_trans_mode_t tx_trans_mode,
i2c_trans_mode_t rx_trans_mode)
set I2C data transfer mode
Return
• ESP_OK Success
Parameters
• tx_trans_mode: I2C sending data mode
• rx_trans_mode: I2C receving data mode
esp_err_t i2c_get_data_mode(i2c_port_t i2c_num, i2c_trans_mode_t *tx_trans_mode,
i2c_trans_mode_t *rx_trans_mode)
get I2C data transfer mode
Return
• ESP_OK Success
Parameters
• tx_trans_mode: pointer to get I2C sending data mode
• rx_trans_mode: pointer to get I2C receiving data mode
Structures
struct i2c_config_t
I2C initialization parameters.
Public Members
i2c_mode_t mode
I2C mode
int sda_io_num
GPIO number for I2C sda signal
int scl_io_num
GPIO number for I2C scl signal
bool sda_pullup_en
Internal GPIO pull mode for I2C sda signal
bool scl_pullup_en
Internal GPIO pull mode for I2C scl signal
uint32_t clk_speed
I2C clock frequency for master mode, (no higher than 1MHz for now)
struct i2c_config_t::[anonymous]::[anonymous] master
I2C master config

uint8_t addr_10bit_en
I2C 10bit address mode enable for slave mode
uint16_t slave_addr
I2C address for slave mode
uint32_t maximum_speed
I2C expected clock speed from SCL.
struct i2c_config_t::[anonymous]::[anonymous] slave
I2C slave config
uint32_t clk_flags
Bitwise of I2C_SCLK_SRC_FLAG_**FOR_DFS** for clk source choice
Macros
I2C_APB_CLK_FREQ
I2C source clock is APB clock, 80MHz
I2C_NUM_MAX
I2C port max
I2C_NUM_0
I2C port 0
I2C_NUM_1
I2C port 1
I2C_SCLK_SRC_FLAG_FOR_NOMAL
Any one clock source that is available for the specified frequency may be choosen
I2C_SCLK_SRC_FLAG_AWARE_DFS
For REF tick clock, it won t change with APB.
I2C_SCLK_SRC_FLAG_LIGHT_SLEEP
For light sleep mode.
I2C_INTERNAL_STRUCT_SIZE
Minimum size, in bytes, of the internal private structure used to describe I2C commands link.
I2C_LINK_RECOMMENDED_SIZE(TRANSACTIONS)
The following macro is used to determine the recommended size of the buffer to pass to
i2c_cmd_link_create_static() function. It requires one parameter, TRANSACTIONS, de-
scribing the number of transactions intended to be performed on the I2C port. For example, if one wants
to perform a read on an I2C device register, TRANSACTIONS must be at least 2, because the commands
required are the following:
• write device register
• read register content
Signals such as (repeated) start , stop , nack , ack shall not be counted.
Type Definitions
typedef void *i2c_cmd_handle_t
I2C command handle
Header File
• components/hal/include/hal/i2c_types.h
Macros
I2C_CLK_FREQ_MAX
Use the highest speed that is available for the clock source picked by clk_flags.

Type Definitions
typedef int i2c_port_t
I2C port number, can be I2C_NUM_0 ~ (I2C_NUM_MAX-1).
Enumerations
enum i2c_mode_t
Values:
I2C_MODE_SLAVE = 0
I2C slave mode
I2C_MODE_MASTER
I2C master mode
I2C_MODE_MAX
enum i2c_rw_t
Values:
I2C_MASTER_WRITE = 0
I2C write data
I2C_MASTER_READ
I2C read data
enum i2c_trans_mode_t
Values:
I2C_DATA_MODE_MSB_FIRST = 0
I2C data msb first
I2C_DATA_MODE_LSB_FIRST = 1
I2C data lsb first
I2C_DATA_MODE_MAX
enum i2c_addr_mode_t
Values:
I2C_ADDR_BIT_7 = 0
I2C 7bit address for slave mode
I2C_ADDR_BIT_10
I2C 10bit address for slave mode
I2C_ADDR_BIT_MAX
enum i2c_ack_type_t
Values:
I2C_MASTER_ACK = 0x0
I2C ack for each byte read
I2C_MASTER_NACK = 0x1
I2C nack for each byte read
I2C_MASTER_LAST_NACK = 0x2
I2C nack for the last byte
I2C_MASTER_ACK_MAX
enum i2c_sclk_t
I2C clock source, sorting from smallest to largest, place them in order. This can be expanded in the future use.
Values:
I2C_SCLK_DEFAULT = 0
I2C source clock not selected

I2C_SCLK_APB
I2C source clock from APB, 80M
I2C_SCLK_MAX
enum i2c_opmode_t
Values:
I2C_CMD_RESTART = 0
I2C restart command
I2C_CMD_WRITE
I2C write command
I2C_CMD_READ
I2C read command
I2C_CMD_STOP
I2C stop command
I2C_CMD_END
I2C end command
2.3.6 Inter-IC Sound (I2S)
Overview
I2S (Inter-IC Sound) is a serial, synchronous communication protocol that is usually used for transmitting audio data
between two digital audio devices.
ESP32 contains two I2S peripheral(s). These peripherals can be configured to input and output sample data via the
I2S driver.
An I2S bus consists of the following lines:
• Master clock line (operational)
• Bit clock line
• Channel select line
• Serial data line
Each I2S controller has the following features that can be configured using the I2S driver:
• Operation as system master or slave
• Capable of acting as transmitter or receiver
• DMA controller that allows for streaming sample data without requiring the CPU to copy each data sample
Each controller can operate in half-duplex communication mode. Thus, the two controllers can be combined to
establish full-duplex communication.
I2S0 output can be routed directly to the digital-to-analog converter s (DAC) output channels (GPIO 25 & GPIO
26) to produce direct analog output without involving any external I2S codecs. I2S0 can also be used for transmitting
PDM (Pulse-density modulation) signals.
The I2S peripherals also support LCD mode for communicating data over a parallel bus, as used by some LCD
displays and camera modules. LCD mode has the following operational modes:
• LCD master transmitting mode
• Camera slave receiving mode
• ADC/DAC mode
For more information, see ESP32 Technical Reference Manual > I2S Controller (I2S) > LCD Mode [PDF].
Note: For high accuracy clock applications, use the APLL_CLK clock source, which has the frequency range of 16
~ 128 MHz. You can enable the APLL_CLK clock source by setting i2s_config_t::use_apll to TRUE.

If i2s_config_t::use_apll = TRUE and i2s_config_t::fixed_mclk > 0, then the master clock

output frequency for I2S will be equal to the value of i2s_config_t::fixed_mclk, which means that the
mclk frequency is provided by the user, instead of being calculated by the driver.
The clock rate of the word select line, which is called audio left-right clock rate (LRCK) here, is al-
ways the divisor of the master clock output frequency and for which the following is always true: 0 <
MCLK/LRCK/channels/bits_per_sample < 64.
Functional Overview
Installing the Driver Install the I2S driver by calling the function :cpp:funcì2s_driver_install` and passing the
following arguments:
• Port number
• The structure i2s_config_t with defined communication parameters
• Event queue size and handle
Once :cpp:funcì2s_driver_install` returns ESP_OK, it means I2S has started.
Configuration example:
static const int i2s_num = 0; // i2s port number
i2s_config_t i2s_config = {
.mode = I2S_MODE_MASTER | I2S_MODE_TX,
.sample_rate = 44100,
.bits_per_sample = I2S_BITS_PER_SAMPLE_16BIT,
.channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT,
.communication_format = I2S_COMM_FORMAT_STAND_I2S
.tx_desc_auto_clear = false,
.dma_buf_count = 8,
.dma_buf_len = 64,
.use_apll = false,
.intr_alloc_flags = ESP_INTR_FLAG_LEVEL1 // Interrupt level 1, default 0
};
i2s_driver_install(I2S_NUM, &i2s_config, 0, NULL);
Setting Communication Pins Once the driver is installed, configure physical GPIO pins to which signals will be
routed. For this, call the function :cpp:funcì2s_set_pin` and pass the following arguments to it:
• Port number
• The structure i2s_pin_config_t defining the GPIO pin numbers to which the driver should route the
MCK, BCK, WS, DATA out, and DATA in signals. If you want to keep a currently allocated pin number for
a specific signal, or if this signal is unused, then pass the macro I2S_PIN_NO_CHANGE. See the example
below.
Note: MCK only takes effect in I2S_MODE_MASTER mode.
static const i2s_pin_config_t pin_config = {

.mck_io_num = 0,
.bck_io_num = 4,
.ws_io_num = 5,
.data_out_num = 18,
.data_in_num = I2S_PIN_NO_CHANGE
};
i2s_set_pin(i2s_num, &pin_config);

Running I2S Communication To perform a transmission:

• Prepare the data for sending
• Call the function i2s_write() and pass the data buffer address and data length to it
The function will write the data to the DMA Tx buffer, and then the data will be transmitted automatically.
i2s_write(I2S_NUM, samples_data, ((bits+8)/16)*SAMPLE_PER_CYCLE*4, &i2s_bytes_

,→write, 100);
To retrieve received data, use the function i2s_read(). It will retrieve the data from the DMA Rx buffer, once
the data is received by the I2S controller.
i2s_read(I2S_NUM, data_recv, ((bits+8)/16)*SAMPLE_PER_CYCLE*4, &i2s_bytes_read,␣

,→100);
You can temporarily stop the I2S driver by calling the function i2s_stop(), which will disable the I2S Tx/Rx
units until the function i2s_start() is called. If the function :cpp:funcì2s_driver_install` is used, the driver will
start up automatically eliminating the need to call i2s_start().
Deleting the Driver If the established communication is no longer required, the driver can be removed to free
allocated resources by calling i2s_driver_uninstall().
Application Example
A code example for the I2S driver can be found in the directory peripherals/i2s.
In addition, there are two short configuration examples for the I2S driver.
In addition, there is a short configuration examples for the I2S driver.
I2S configuration Example for general usage.
#include "driver/i2s.h"
i2s_config_t i2s_config = {
.mode = I2S_MODE_MASTER | I2S_MODE_TX,
.bits_per_sample = I2S_BITS_PER_SAMPLE_16BIT,
.communication_format = I2S_COMM_FORMAT_STAND_I2S
.tx_desc_auto_clear = false,
.dma_buf_count = 8,
.dma_buf_len = 64,
.use_apll = false,
.intr_alloc_flags = ESP_INTR_FLAG_LEVEL1 // Interrupt level 1, default 0
};
static const i2s_pin_config_t pin_config = {

.bck_io_num = 4,
.ws_io_num = 5,
.data_out_num = 18,
.data_in_num = I2S_PIN_NO_CHANGE
};
i2s_driver_install(i2s_num, &i2s_config, 0, NULL); //install and start i2s driver

i2s_set_pin(i2s_num, &pin_config);


...
/* You can reset parameters by calling 'i2s_set_clk'
*
* The low 16 bits are the valid data bits in one chan and the high 16 bits are
* the total bits in one chan. If high 16 bits is smaller than low 16 bits, it will
* be set to a same value as low 16 bits.
*/
uint32_t bits_cfg = (I2S_BITS_PER_CHAN_32BIT << 16) | I2S_BITS_PER_SAMPLE_16BIT;
i2s_set_clk(i2s_num, 22050, bits_cfg, I2S_CHANNEL_STEREO);
...
i2s_driver_uninstall(i2s_num); //stop & destroy i2s driver
Configuring I2S to use internal DAC for analog output

#include "driver/i2s.h"
#include "freertos/queue.h"
static const i2s_config_t i2s_config = {

.mode = I2S_MODE_MASTER | I2S_MODE_TX | I2S_MODE_DAC_BUILT_IN,
.bits_per_sample = 16, /* the DAC module will only take the 8bits from MSB */
.intr_alloc_flags = 0, // default interrupt priority
.dma_buf_count = 8,
.dma_buf_len = 64,
.use_apll = false
};
...
i2s_driver_install(i2s_num, &i2s_config, 0, NULL); //install and start i2s␣

,→ driver
i2s_set_pin(i2s_num, NULL); //for internal DAC, this will enable both of the␣
,→ internal channels
//You can call i2s_set_dac_mode to set built-in DAC output mode.

//i2s_set_dac_mode(I2S_DAC_CHANNEL_BOTH_EN);
i2s_set_sample_rates(i2s_num, 22050); //set sample rates
i2s_driver_uninstall(i2s_num); //stop & destroy i2s driver
API Reference
Header File
• components/driver/include/driver/i2s.h
Functions
esp_err_t i2s_set_pin(i2s_port_t i2s_num, const i2s_pin_config_t *pin)
Set I2S pin number.
Inside the pin configuration structure, set I2S_PIN_NO_CHANGE for any pin where the current configuration
should not be changed.

Note The I2S peripheral output signals can be connected to multiple GPIO pads. However, the I2S peripheral
input signal can only be connected to one GPIO pad.
Parameters
• i2s_num: I2S port number
• pin: I2S Pin structure, or NULL to set 2-channel 8-bit internal DAC pin configuration (GPIO25
& GPIO26)
Note if *pin is set as NULL, this function will initialize both of the built-in DAC channels by default. if
you don t want this to happen and you want to initialize only one of the DAC channels, you can call
i2s_set_dac_mode instead.
Return
• ESP_OK Success
• ESP_FAIL IO error
esp_err_t i2s_set_pdm_rx_down_sample(i2s_port_t i2s_num, i2s_pdm_dsr_t downsample)
Set PDM mode down-sample rate In PDM RX mode, there would be 2 rounds of downsample process in
hardware. In the first downsample process, the sampling number can be 16 or 8. In the second downsample
process, the sampling number is fixed as 8. So the clock frequency in PDM RX mode would be (fpcm * 64)
or (fpcm * 128) accordingly.
Note After calling this function, it would call i2s_set_clk inside to update the clock frequency. Please call this
function after I2S driver has been initialized.
Return
• ESP_OK Success
• ESP_ERR_NO_MEM Out of memory
Parameters
• downsample: i2s RX down sample rate for PDM mode.
esp_err_t i2s_set_pdm_tx_up_sample(i2s_port_t i2s_num, const i2s_pdm_tx_upsample_cfg_t
*upsample_cfg)
Set TX PDM mode up-sample rate.
Note If you have set PDM mode while calling i2s_driver_install , default PDM TX upsample parame-
ters have already been set, no need to call this function again if you don t have to change the default
configuration
Return
• ESP_OK Success
Parameters
• upsample_cfg: Set I2S PDM up-sample rate configuration
esp_err_t i2s_driver_install(i2s_port_t i2s_num, const i2s_config_t *i2s_config, int queue_size,
void *i2s_queue)
Install and start I2S driver.
This function must be called before any I2S driver read/write operations.
Parameters
• i2s_config: I2S configurations - see i2s_config_t struct
• queue_size: I2S event queue size/depth.
• i2s_queue: I2S event queue handle, if set NULL, driver will not use an event queue.
Return
• ESP_OK Success
• ESP_ERR_INVALID_STATE Current I2S port is in use

esp_err_t i2s_driver_uninstall(i2s_port_t i2s_num)

Uninstall I2S driver.
Return
• ESP_OK Success
• ESP_ERR_INVALID_STATE I2S port has been uninstalled by others (e.g. LCD i80)
Parameters
esp_err_t i2s_write(i2s_port_t i2s_num, const void *src, size_t size, size_t *bytes_written, TickType_t
ticks_to_wait)
Write data to I2S DMA transmit buffer.
Return
• ESP_OK Success
Parameters
• src: Source address to write from
• size: Size of data in bytes
• [out] bytes_written: Number of bytes written, if timeout, the result will be less than the
size passed in.
• ticks_to_wait: TX buffer wait timeout in RTOS ticks. If this many ticks pass without space
becoming available in the DMA transmit buffer, then the function will return (note that if the data
is written to the DMA buffer in pieces, the overall operation may still take longer than this timeout.)
Pass portMAX_DELAY for no timeout.
esp_err_t i2s_write_expand(i2s_port_t i2s_num, const void *src, size_t size, size_t src_bits, size_t
aim_bits, size_t *bytes_written, TickType_t ticks_to_wait)
Write data to I2S DMA transmit buffer while expanding the number of bits per sample. For example, expanding
16-bit PCM to 32-bit PCM.
Format of the data in source buffer is determined by the I2S configuration (see i2s_config_t).
Parameters
• src: Source address to write from
• src_bits: Source audio bit
• aim_bits: Bit wanted, no more than 32, and must be greater than src_bits
• [out] bytes_written: Number of bytes written, if timeout, the result will be less than the
size passed in.
• ticks_to_wait: TX buffer wait timeout in RTOS ticks. If this many ticks pass without space
becoming available in the DMA transmit buffer, then the function will return (note that if the data
is written to the DMA buffer in pieces, the overall operation may still take longer than this timeout.)
Pass portMAX_DELAY for no timeout.
Return
• ESP_OK Success
esp_err_t i2s_read(i2s_port_t i2s_num, void *dest, size_t size, size_t *bytes_read, TickType_t
ticks_to_wait)
Read data from I2S DMA receive buffer.
Note If the built-in ADC mode is enabled, we should call i2s_adc_enable and i2s_adc_disable around the
whole reading process, to prevent the data getting corrupted.
Return
• ESP_OK Success
Parameters

• dest: Destination address to read into

• [out] bytes_read: Number of bytes read, if timeout, bytes read will be less than the size
passed in.
• ticks_to_wait: RX buffer wait timeout in RTOS ticks. If this many ticks pass without bytes
becoming available in the DMA receive buffer, then the function will return (note that if data is read
from the DMA buffer in pieces, the overall operation may still take longer than this timeout.) Pass
portMAX_DELAY for no timeout.
esp_err_t i2s_set_sample_rates(i2s_port_t i2s_num, uint32_t rate)
Set sample rate used for I2S RX and TX.
The bit clock rate is determined by the sample rate and i2s_config_t configuration parameters (number of
channels, bits_per_sample).
bit_clock = rate * (number of channels) * bits_per_sample
Return
• ESP_OK Success
Parameters
• rate: I2S sample rate (ex: 8000, 44100 )
esp_err_t i2s_stop(i2s_port_t i2s_num)
Stop I2S driver.
There is no need to call i2s_stop() before calling i2s_driver_uninstall().
Disables I2S TX/RX, until i2s_start() is called.
Return
• ESP_OK Success
Parameters
esp_err_t i2s_start(i2s_port_t i2s_num)
Start I2S driver.
It is not necessary to call this function after i2s_driver_install() (it is started automatically), however it is
necessary to call it after i2s_stop().
Return
• ESP_OK Success
Parameters
esp_err_t i2s_zero_dma_buffer(i2s_port_t i2s_num)
Zero the contents of the TX DMA buffer.
Pushes zero-byte samples into the TX DMA buffer, until it is full.
Return
• ESP_OK Success
Parameters
esp_err_t i2s_set_clk(i2s_port_t i2s_num, uint32_t rate, uint32_t bits_cfg, i2s_channel_t ch)
Set clock & bit width used for I2S RX and TX.
Similar to i2s_set_sample_rates(), but also sets bit width.
1. stop i2s;

2. calculate mclk, bck, bck_factor

3. malloc dma buffer;
4. start i2s
Return
• ESP_OK Success
Parameters
• rate: I2S sample rate (ex: 8000, 44100 )
• bits_cfg: I2S bits configuration the low 16 bits is for data bits per sample in one channel (see
i2s_bits_per_sample_t ) the high 16 bits is for total bits in one channel (see i2s_bits_per_chan_t
) high 16bits =0 means same as the bits per sample.
• ch: I2S channel, (I2S_CHANNEL_MONO, I2S_CHANNEL_STEREO or specific channel in
TDM mode)
float i2s_get_clk(i2s_port_t i2s_num)
get clock set on particular port number.
Return
• actual clock set by i2s driver
Parameters
esp_err_t i2s_set_adc_mode(adc_unit_t adc_unit, adc1_channel_t adc_channel)
Set built-in ADC mode for I2S DMA, this function will initialize ADC pad, and set ADC parameters.
Note In this mode, the ADC maximum sampling rate is 150KHz. Set the sampling rate through
i2s_config_t.
Return
• ESP_OK Success
Parameters
• adc_unit: SAR ADC unit index
• adc_channel: ADC channel index
esp_err_t i2s_adc_enable(i2s_port_t i2s_num)
Start to use I2S built-in ADC mode.
Note This function would acquire the lock of ADC to prevent the data getting corrupted during the I2S pe-
ripheral is being used to do fully continuous ADC sampling.
Return
• ESP_OK Success
• ESP_ERR_INVALID_STATE Driver state error
Parameters
• i2s_num: i2s port index
esp_err_t i2s_adc_disable(i2s_port_t i2s_num)
Stop to use I2S built-in ADC mode.
Note This function would release the lock of ADC so that other tasks can use ADC.
Return
• ESP_OK Success
• ESP_ERR_INVALID_STATE Driver state error
Parameters
• i2s_num: i2s port index
esp_err_t i2s_set_dac_mode(i2s_dac_mode_t dac_mode)
Set I2S dac mode, I2S built-in DAC is disabled by default.

Note Built-in DAC functions are only supported on I2S0 for current ESP32 chip. If either of the built-in DAC
channel are enabled, the other one can not be used as RTC DAC function at the same time.
Return
• ESP_OK Success
Parameters
• dac_mode: DAC mode configurations - see i2s_dac_mode_t
Structures
struct i2s_pdm_tx_upsample_cfg_t
I2S PDM up-sample rate configuration.
Note TX PDM can only be set to the following two upsampling rate configurations: 1: fp = 960, fs = sam-
ple_rate / 100, in this case, Fpdm = 128*48000 2: fp = 960, fs = 480, in this case, Fpdm = 128*Fpcm
= 128*sample_rate If the pdm receiver do not care the pdm serial clock, it s recommended set Fpdm
= 128*48000. Otherwise, the second configuration should be applied.
Public Members
int sample_rate
I2S PDM sample rate
int fp
I2S PDM TX upsampling paramater. Normally it should be set to 960
int fs
I2S PDM TX upsampling paramater. When it is set to 480, the pdm clock frequency Fpdm = 128 *
sample_rate, when it is set to sample_rate / 100 Fpdm will be fixed to 128*48000
struct i2s_pin_config_t
I2S pin number for i2s_set_pin.
Public Members
int mck_io_num
MCK in out pin. Note that ESP32 supports setting MCK on GPIO0/GPIO1/GPIO3 only
int bck_io_num
BCK in out pin
int ws_io_num
WS in out pin
int data_out_num
DATA out pin
int data_in_num
DATA in pin
struct i2s_driver_config_t
I2S driver configuration parameters.
Public Members
i2s_mode_t mode
I2S work mode
uint32_t sample_rate
I2S sample rate

i2s_bits_per_sample_t bits_per_sample
I2S sample bits in one channel
i2s_channel_fmt_t channel_format
I2S channel format.
i2s_comm_format_t communication_format
I2S communication format
int intr_alloc_flags
Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See
esp_intr_alloc.h for more info
int dma_buf_count
I2S DMA Buffer Count
int dma_buf_len
I2S DMA Buffer Length
bool use_apll
I2S using APLL as main I2S clock, enable it to get accurate clock
bool tx_desc_auto_clear
I2S auto clear tx descriptor if there is underflow condition (helps in avoiding noise in case of data un-
availability)
int fixed_mclk
I2S using fixed MCLK output. If use_apll = true and fixed_mclk > 0, then the clock output for i2s is
fixed and equal to the fixed_mclk value. If fixed_mclk set, mclk_multiple won t take effect
i2s_mclk_multiple_t mclk_multiple
The multiple of I2S master clock(MCLK) to sample rate
i2s_bits_per_chan_t bits_per_chan
I2S total bits in one channel only take effect when larger than bits_per_sample , default 0 means
equal to bits_per_sample
struct i2s_event_t
Event structure used in I2S event queue.
Public Members
i2s_event_type_t type
I2S event type
size_t size
I2S data size for I2S_DATA event
Macros
I2S_PIN_NO_CHANGE
Use in i2s_pin_config_t for pins which should not be changed
I2S_PDM_DEFAULT_UPSAMPLE_CONFIG(rate)
Default I2S PDM Up-Sampling Rate configuration.
Type Definitions
typedef i2s_driver_config_t i2s_config_t
typedef intr_handle_t i2s_isr_handle_t

Enumerations
enum i2s_port_t
I2S port number, the max port number is (I2S_NUM_MAX -1).
Values:
I2S_NUM_0 = 0
I2S port 0
I2S_NUM_1 = 1
I2S port 1
I2S_NUM_MAX
I2S port max
enum i2s_event_type_t
I2S event queue types.
Values:
I2S_EVENT_DMA_ERROR
I2S_EVENT_TX_DONE
I2S DMA finish sent 1 buffer
I2S_EVENT_RX_DONE
I2S DMA finish received 1 buffer
I2S_EVENT_TX_Q_OVF
I2S DMA sent queue overflow
I2S_EVENT_RX_Q_OVF
I2S DMA receive queue overflow
I2S_EVENT_MAX
I2S event max index
Header File
• components/hal/include/hal/i2s_types.h
Enumerations
enum i2s_bits_per_sample_t
I2S bit width per sample.
Values:
I2S_BITS_PER_SAMPLE_8BIT = 8
data bit-width: 8
data bit-width: 16
data bit-width: 24
data bit-width: 32
enum i2s_bits_per_chan_t
I2S bit width per chan.
Values:
I2S_BITS_PER_CHAN_DEFAULT = (0)
channel bit-width equals to data bit-width
I2S_BITS_PER_CHAN_8BIT = (8)
channel bit-width: 8

enum i2s_channel_t
I2S channel.
Values:
I2S_CHANNEL_MONO = (0x01 << 31) | 0x03
I2S channel (mono), two channel enabled. In this mode, you only need to send one channel data but the
fifo will copy same data for another channel automatically, then both channels will transmit same data.
The highest bit is for differentiating I2S_CHANNEL_STEREO since they both use two channels
I2S_CHANNEL_STEREO = 0x03
I2S channel (stereo), two channel enabled. In this mode, two channels will transmit different data.
enum i2s_comm_format_t
I2S communication standard format.
Values:
I2S_COMM_FORMAT_STAND_I2S = 0X01
I2S communication I2S Philips standard, data launch at second BCK
I2S_COMM_FORMAT_STAND_MSB = 0X02
I2S communication MSB alignment standard, data launch at first BCK
I2S_COMM_FORMAT_STAND_PCM_SHORT = 0x04
PCM Short standard, also known as DSP mode. The period of synchronization signal (WS) is 1 bck
cycle.
I2S_COMM_FORMAT_STAND_PCM_LONG = 0x0C
PCM Long standard. The period of synchronization signal (WS) is channel_bit*bck cycles.
I2S_COMM_FORMAT_STAND_MAX
standard max
I2S_COMM_FORMAT_I2S = 0x01
I2S communication format I2S, correspond to I2S_COMM_FORMAT_STAND_I2S
I2S_COMM_FORMAT_I2S_MSB = 0x01
I2S format MSB, (I2S_COMM_FORMAT_I2S |I2S_COMM_FORMAT_I2S_MSB) correspond to
I2S_COMM_FORMAT_STAND_I2S
I2S_COMM_FORMAT_I2S_LSB = 0x02
I2S format LSB, (I2S_COMM_FORMAT_I2S |I2S_COMM_FORMAT_I2S_LSB) correspond to
I2S_COMM_FORMAT_STAND_MSB
I2S_COMM_FORMAT_PCM = 0x04
I2S communication format PCM, correspond to I2S_COMM_FORMAT_STAND_PCM_SHORT
I2S_COMM_FORMAT_PCM_SHORT = 0x04
PCM Short, (I2S_COMM_FORMAT_PCM | I2S_COMM_FORMAT_PCM_SHORT) correspond to
I2S_COMM_FORMAT_STAND_PCM_SHORT
I2S_COMM_FORMAT_PCM_LONG = 0x08
PCM Long, (I2S_COMM_FORMAT_PCM | I2S_COMM_FORMAT_PCM_LONG) correspond to
I2S_COMM_FORMAT_STAND_PCM_LONG
enum i2s_channel_fmt_t
I2S channel format type.
Values:

I2S_CHANNEL_FMT_RIGHT_LEFT
Separated left and right channel
I2S_CHANNEL_FMT_ALL_RIGHT
Load right channel data in both two channels
I2S_CHANNEL_FMT_ALL_LEFT
Load left channel data in both two channels
I2S_CHANNEL_FMT_ONLY_RIGHT
Only load data in right channel (mono mode)
I2S_CHANNEL_FMT_ONLY_LEFT
Only load data in left channel (mono mode)
enum i2s_mode_t
I2S Mode.
Values:
I2S_MODE_MASTER = (0x1 << 0)
Master mode
I2S_MODE_SLAVE = (0x1 << 1)
Slave mode
I2S_MODE_TX = (0x1 << 2)
TX mode
I2S_MODE_RX = (0x1 << 3)
RX mode
I2S_MODE_DAC_BUILT_IN = (0x1 << 4)
Output I2S data to built-in DAC, no matter the data format is 16bit or 32 bit, the DAC module will only
take the 8bits from MSB
I2S_MODE_ADC_BUILT_IN = (0x1 << 5)
Input I2S data from built-in ADC, each data can be 12-bit width at most
I2S_MODE_PDM = (0x1 << 6)
I2S PDM mode
enum i2s_clock_src_t
I2S source clock.
Values:
I2S_CLK_D2CLK = 0
Clock from PLL_D2_CLK(160M)
I2S_CLK_APLL
Clock from APLL
enum i2s_mclk_multiple_t
The multiple of mclk to sample rate.
Values:
I2S_MCLK_MULTIPLE_DEFAULT = 0
Default value. mclk = sample_rate * 256
I2S_MCLK_MULTIPLE_128 = 128
mclk = sample_rate * 128

enum i2s_dac_mode_t
I2S DAC mode for i2s_set_dac_mode.
Note Built-in DAC functions are only supported on I2S0 for current ESP32 chip.
Values:
I2S_DAC_CHANNEL_DISABLE = 0
Disable I2S built-in DAC signals
I2S_DAC_CHANNEL_RIGHT_EN = 1
Enable I2S built-in DAC right channel, maps to DAC channel 1 on GPIO25
I2S_DAC_CHANNEL_LEFT_EN = 2
Enable I2S built-in DAC left channel, maps to DAC channel 2 on GPIO26
I2S_DAC_CHANNEL_BOTH_EN = 0x3
Enable both of the I2S built-in DAC channels.
I2S_DAC_CHANNEL_MAX = 0x4
I2S built-in DAC mode max index
enum i2s_pdm_dsr_t
I2S PDM RX downsample mode.
Values:
I2S_PDM_DSR_8S = 0
downsampling number is 8 for PDM RX mode
I2S_PDM_DSR_16S
downsampling number is 16 for PDM RX mode
I2S_PDM_DSR_MAX
enum i2s_pdm_sig_scale_t
Values:
I2S_PDM_SIG_SCALING_DIV_2 = 0
I2S TX PDM sigmadelta signal scaling: /2
I2S_PDM_SIG_SCALING_MUL_1 = 1
I2S TX PDM sigmadelta signal scaling: x1
2.3.7 LCD
Introduction
ESP chips can generate various kinds of timings that needed by common LCDs on the market, like SPI LCD, I80
LCD (a.k.a Intel 8080 parallel LCD), RGB LCD, I2C LCD, etc. The esp_lcd component is officially to support
those LCDs with a group of universal APIs across chips.
Functional Overview
In esp_lcd, an LCD panel is represented by esp_lcd_panel_handle_t, which plays the role of an abstract
frame buffer, regardless of the frame memory is allocated inside ESP chip or in external LCD controller. Based on
the location of the frame buffer, the LCD panel allocation functions are mainly grouped into the following categories:

• RGB LCD panel - is simply based on a group of specific synchronous signals indicating where to start and
stop a frame.
• Controller based LCD panel involves multiple steps to get a panel handle, like bus allocation, IO
device registration and controller driver install.
After we get the LCD handle, the remaining LCD operations are the same for different LCD interfaces and vendors.
Application Example
LCD examples are located under: peripherals/lcd:

• Jpeg decoding and LCD display - peripherals/lcd/tjpgd
• LVGL porting and animation UI - peripherals/lcd/lvgl
API Reference
Header File
• components/hal/include/hal/lcd_types.h
Enumerations
enum lcd_clock_source_t
LCD clock source.
Note User should select the clock source based on the real requirement:
Values:
LCD_CLK_SRC_PLL160M
Select PLL160M as the source clock
LCD_CLK_SRC_APLL
Select APLL as the source clock
LCD_CLK_SRC_XTAL
Select XTAL as the source clock
Header File
• components/esp_lcd/include/esp_lcd_types.h
Type Definitions
typedef struct esp_lcd_panel_io_t *esp_lcd_panel_io_handle_t
Type of LCD panel IO handle
typedef struct esp_lcd_panel_t *esp_lcd_panel_handle_t
Type of LCD panel handle
Enumerations
enum esp_lcd_color_space_t
LCD color space type definition.
Values:
ESP_LCD_COLOR_SPACE_RGB
Color space: RGB
ESP_LCD_COLOR_SPACE_BGR
Color space: BGR

ESP_LCD_COLOR_SPACE_MONOCHROME
Color space: monochrome
Header File
• components/esp_lcd/include/esp_lcd_panel_io.h
Functions
esp_err_t esp_lcd_panel_io_tx_param(esp_lcd_panel_io_handle_t io, int lcd_cmd, const void
*param, size_t param_size)
Transmit LCD command and corresponding parameters.
Note Commands sent by this function are short, so they are sent using polling transactions. The func-
tion does not return before the command tranfer is completed. If any queued transactions sent by
esp_lcd_panel_io_tx_color() are still pending when this function is called, this function will
wait until they are finished and the queue is empty before sending the command(s).
Return
• ESP_ERR_INVALID_ARG if parameter is invalid
Parameters
• [in] io: LCD panel IO handle, which is created by other factory API like
esp_lcd_new_panel_io_spi()
• [in] lcd_cmd: The specific LCD command
• [in] param: Buffer that holds the command specific parameters, set to NULL if no parameter
is needed for the command
• [in] param_size: Size of param in memory, in bytes, set to zero if no parameter is needed
for the command
esp_err_t esp_lcd_panel_io_tx_color(esp_lcd_panel_io_handle_t io, int lcd_cmd, const void
*color, size_t color_size)
Transmit LCD RGB data.
Note This function will package the command and RGB data into a transaction, and push into a queue.
The real transmission is performed in the background (DMA+interrupt). The caller should take care
of the lifecycle of the color buffer. Recycling of color buffer should be done in the callback
on_color_trans_done().
Return
Parameters
• [in] io: LCD panel IO handle, which is created by factory API like
• [in] lcd_cmd: The specific LCD command
• [in] color: Buffer that holds the RGB color data
• [in] color_size: Size of color in memory, in bytes
esp_err_t esp_lcd_panel_io_del(esp_lcd_panel_io_handle_t io)
Destory LCD panel IO handle (deinitialize panel and free all corresponding resource)
Return
Parameters
• [in] io: LCD panel IO handle, which is created by factory API like
esp_err_t esp_lcd_new_panel_io_spi(esp_lcd_spi_bus_handle_t bus, const
esp_lcd_panel_io_spi_config_t *io_config,
esp_lcd_panel_io_handle_t *ret_io)
Create LCD panel IO handle, for SPI interface.
Return


• ESP_ERR_NO_MEM if out of memory
Parameters
• [in] bus: SPI bus handle
• [in] io_config: IO configuration, for SPI interface
• [out] ret_io: Returned IO handle
esp_err_t esp_lcd_new_panel_io_i2c(esp_lcd_i2c_bus_handle_t bus, const
esp_lcd_panel_io_i2c_config_t *io_config,
Create LCD panel IO handle, for I2C interface.
Return
Parameters
• [in] bus: I2C bus handle
• [in] io_config: IO configuration, for I2C interface
• [out] ret_io: Returned IO handle
esp_err_t esp_lcd_new_i80_bus(const esp_lcd_i80_bus_config_t *bus_config,
esp_lcd_i80_bus_handle_t *ret_bus)
Create Intel 8080 bus handle.
Return
• ESP_ERR_NOT_FOUND if no free bus is available
Parameters
• [in] bus_config: Bus configuration
• [out] ret_bus: Returned bus handle
esp_err_t esp_lcd_del_i80_bus(esp_lcd_i80_bus_handle_t bus)
Destory Intel 8080 bus handle.
Return
• ESP_ERR_INVALID_STATE if there still be some device attached to the bus
Parameters
• [in] bus: Intel 8080 bus handle, created by esp_lcd_new_i80_bus()
esp_err_t esp_lcd_new_panel_io_i80(esp_lcd_i80_bus_handle_t bus, const
esp_lcd_panel_io_i80_config_t *io_config,
Create LCD panel IO, for Intel 8080 interface.
Return
• ESP_ERR_NOT_SUPPORTED if some configuration can t be satisfied, e.g. pixel clock out of
the range
Parameters
• [in] bus: Intel 8080 bus handle, created by esp_lcd_new_i80_bus()
• [in] io_config: IO configuration, for i80 interface
• [out] ret_io: Returned panel IO handle
Structures

struct esp_lcd_panel_io_event_data_t
Type of LCD panel IO event data.
struct esp_lcd_panel_io_spi_config_t
Panel IO configuration structure, for SPI interface.
Public Members
int cs_gpio_num
GPIO used for CS line
int dc_gpio_num
GPIO used to select the D/C line, set this to -1 if the D/C line not controlled by manually pulling high/low
GPIO
int spi_mode
Traditional SPI mode (0~3)
unsigned int pclk_hz
Frequency of pixel clock
size_t trans_queue_depth
Size of internal transaction queue
esp_lcd_panel_io_color_trans_done_cb_t on_color_trans_done
Callback invoked when color data transfer has finished
void *user_ctx
User private data, passed directly to on_color_trans_done s user_ctx
int lcd_cmd_bits
Bit-width of LCD command
int lcd_param_bits
Bit-width of LCD parameter
unsigned int dc_as_cmd_phase : 1
D/C line value is encoded into SPI transaction command phase
unsigned int dc_low_on_data : 1
If this flag is enabled, DC line = 0 means transfer data, DC line = 1 means transfer command; vice versa
unsigned int octal_mode : 1
transmit with octal mode (8 data lines), this mode is used to simulate Intel 8080 timing
struct esp_lcd_panel_io_i2c_config_t
Public Members
uint32_t dev_addr
I2C device address
Callback invoked when color data transfer has finished
void *user_ctx
size_t control_phase_bytes
I2C LCD panel will encode control information (e.g. D/C seclection) into control phase, in several bytes
unsigned int dc_bit_offset
Offset of the D/C selection bit in control phase
int lcd_cmd_bits

int lcd_param_bits
unsigned int dc_low_on_data : 1
If this flag is enabled, DC line = 0 means transfer data, DC line = 1 means transfer command; vice versa
struct esp_lcd_i80_bus_config_t
LCD Intel 8080 bus configuration structure.
Public Members
int dc_gpio_num
GPIO used for D/C line
int wr_gpio_num
GPIO used for WR line
lcd_clock_source_t clk_src
Clock source for the I80 LCD peripheral
int data_gpio_nums[(24)]
GPIOs used for data lines
size_t bus_width
Number of data lines, 8 or 16
size_t max_transfer_bytes
Maximum transfer size, this determines the length of internal DMA link
struct esp_lcd_panel_io_i80_config_t
Panel IO configuration structure, for intel 8080 interface.
Public Members
int cs_gpio_num
GPIO used for CS line, set to -1 will declaim exclusively use of I80 bus
unsigned int pclk_hz
Frequency of pixel clock
size_t trans_queue_depth
Transaction queue size, larger queue, higher throughput
Callback invoked when color data was tranferred done
void *user_ctx
int lcd_cmd_bits
int lcd_param_bits
unsigned int dc_idle_level : 1
Level of DC line in IDLE phase
unsigned int dc_cmd_level : 1
Level of DC line in CMD phase
unsigned int dc_dummy_level : 1
Level of DC line in DUMMY phase
unsigned int dc_data_level : 1
Level of DC line in DATA phase

struct esp_lcd_panel_io_i80_config_t::[anonymous] dc_levels

Each i80 device might have its own D/C control logic
unsigned int cs_active_high : 1
If set, a high level of CS line will select the device, otherwise, CS line is low level active
unsigned int reverse_color_bits : 1
Reverse the data bits, D[N:0] -> D[0:N]
unsigned int swap_color_bytes : 1
Swap adjacent two color bytes
unsigned int pclk_active_neg : 1
The display will write data lines when there s a falling edge on WR signal (a.k.a the PCLK)
unsigned int pclk_idle_low : 1
The WR signal (a.k.a the PCLK) stays at low level in IDLE phase
Type Definitions
typedef void *esp_lcd_spi_bus_handle_t
Type of LCD SPI bus handle
typedef void *esp_lcd_i2c_bus_handle_t
Type of LCD I2C bus handle
typedef struct esp_lcd_i80_bus_t *esp_lcd_i80_bus_handle_t
Type of LCD intel 8080 bus handle
typedef bool (*esp_lcd_panel_io_color_trans_done_cb_t)(esp_lcd_panel_io_handle_t
panel_io,
esp_lcd_panel_io_event_data_t
*edata, void *user_ctx)
Declare the prototype of the function that will be invoked when panel IO finishes transferring color data.
Return Whether a high priority task has been waken up by this function
Parameters
• [in] panel_io: LCD panel IO handle, which is created by factory API like
• [in] edata: Panel IO event data, fed by driver
• [in] user_ctx: User data, passed from esp_lcd_panel_io_xxx_config_t
Header File
• components/esp_lcd/include/esp_lcd_panel_ops.h
Functions
esp_err_t esp_lcd_panel_reset(esp_lcd_panel_handle_t panel)
Reset LCD panel.
Note Panel reset must be called before attempting to initialize the panel using esp_lcd_panel_init().
Return
Parameters
• [in] panel: LCD panel handle, which is created by other factory API like
esp_lcd_new_panel_st7789()
esp_err_t esp_lcd_panel_init(esp_lcd_panel_handle_t panel)
Initialize LCD panel.
Note Before calling this function, make sure the LCD panel has finished the reset stage by
esp_lcd_panel_reset().
Return
Parameters

esp_err_t esp_lcd_panel_del(esp_lcd_panel_handle_t panel)
Deinitialize the LCD panel.
Return
Parameters
esp_err_t esp_lcd_panel_draw_bitmap(esp_lcd_panel_handle_t panel, int x_start, int y_start, int
x_end, int y_end, const void *color_data)
Draw bitmap on LCD panel.
Return
Parameters
• [in] x_start: Start index on x-axis (x_start included)
• [in] y_start: Start index on y-axis (y_start included)
• [in] x_end: End index on x-axis (x_end not included)
• [in] y_end: End index on y-axis (y_end not included)
• [in] color_data: RGB color data that will be dumped to the specific window range
esp_err_t esp_lcd_panel_mirror(esp_lcd_panel_handle_t panel, bool mirror_x, bool mirror_y)
Mirror the LCD panel on specific axis.
Note Combined with esp_lcd_panel_swap_xy(), one can realize screen rotation
Return
• ESP_ERR_NOT_SUPPORTED if this function is not supported by the panel
Parameters
• [in] mirror_x: Whether the panel will be mirrored about the x axis
• [in] mirror_y: Whether the panel will be mirrored about the y axis
esp_err_t esp_lcd_panel_swap_xy(esp_lcd_panel_handle_t panel, bool swap_axes)
Swap/Exchange x and y axis.
Note Combined with esp_lcd_panel_mirror(), one can realize screen rotation
Return
Parameters
• [in] swap_axes: Whether to swap the x and y axis
esp_err_t esp_lcd_panel_set_gap(esp_lcd_panel_handle_t panel, int x_gap, int y_gap)
Set extra gap in x and y axis.
The gap is the space (in pixels) between the left/top sides of the LCD panel and the first row/column respectively
of the actual contents displayed.
Note Setting a gap is useful when positioning or centering a frame that is smaller than the LCD.
Return
Parameters

• [in] x_gap: Extra gap on x axis, in pixels

• [in] y_gap: Extra gap on y axis, in pixels
esp_err_t esp_lcd_panel_invert_color(esp_lcd_panel_handle_t panel, bool invert_color_data)
Invert the color (bit-wise invert the color data line)
Return
Parameters
• [in] invert_color_data: Whether to invert the color data
esp_err_t esp_lcd_panel_disp_off(esp_lcd_panel_handle_t panel, bool off)
Turn off the display.
Return
Parameters
• [in] off: Whether to turn off the screen
Header File
• components/esp_lcd/include/esp_lcd_panel_rgb.h
Header File
• components/esp_lcd/include/esp_lcd_panel_vendor.h
Functions
esp_err_t esp_lcd_new_panel_st7789(const esp_lcd_panel_io_handle_t io, const
esp_lcd_panel_dev_config_t *panel_dev_config,
esp_lcd_panel_handle_t *ret_panel)
Create LCD panel for model ST7789.
Return
Parameters
• [in] io: LCD panel IO handle
• [in] panel_dev_config: general panel device configuration
• [out] ret_panel: Returned LCD panel handle
esp_err_t esp_lcd_new_panel_nt35510(const esp_lcd_panel_io_handle_t io, const
Create LCD panel for model NT35510.
Return
Parameters

esp_err_t esp_lcd_new_panel_ssd1306(const esp_lcd_panel_io_handle_t io, const

Create LCD panel for model SSD1306.
Return
Parameters
Structures
struct esp_lcd_panel_dev_config_t
Configuration structure for panel device.
Public Members
int reset_gpio_num
GPIO used to reset the LCD panel, set to -1 if it s not used
esp_lcd_color_space_t color_space
Set the color space used by the LCD panel
unsigned int bits_per_pixel
Color depth, in bpp
unsigned int reset_active_high : 1
Setting this if the panel reset is high level active
2.3.8 LED Control (LEDC)
Introduction
The LED control (LEDC) peripheral is primarily designed to control the intensity of LEDs, although it can also be
used to generate PWM signals for other purposes. It has 16 channels which can generate independent waveforms that
can be used, for example, to drive RGB LED devices.
LEDC channels are divided into two groups of 8 channels each. One group of LEDC channels operates in high
speed mode. This mode is implemented in hardware and offers automatic and glitch-free changing of the PWM duty
cycle. The other group of channels operate in low speed mode, the PWM duty cycle must be changed by the driver
in software. Each group of channels is also able to use different clock sources.
The PWM controller can automatically increase or decrease the duty cycle gradually, allowing for fades without any
processor interference.
Setting up a channel of the LEDC in either high or low speed mode is done in three steps:
1. Timer Configuration by specifying the PWM signal s frequency and duty cycle resolution.
2. Channel Configuration by associating it with the timer and GPIO to output the PWM signal.
3. Change PWM Signal that drives the output in order to change LED s intensity. This can be done under the
full control of software or with hardware fading functions.
As an optional step, it is also possible to set up an interrupt on fade end.

Fig. 11: Key Settings of LED PWM Controller s API
Timer Configuration Setting the timer is done by calling the function ledc_timer_config() and passing
the data structure ledc_timer_config_t that contains the following configuration settings:
• Speed mode ledc_mode_t
• Timer number ledc_timer_t
• PWM signal frequency
• Resolution of PWM duty
The frequency and the duty resolution are interdependent. The higher the PWM frequency, the lower the duty
resolution which is available, and vice versa. This relationship might be important if you are planning to use this API
for purposes other than changing the intensity of LEDs. For more details, see Section Supported Range of Frequency
and Duty Resolutions.
Channel Configuration When the timer is set up, configure the desired channel (one out of ledc_channel_t).
This is done by calling the function ledc_channel_config().
Similar to the timer configuration, the channel setup function should be passed a structure
ledc_channel_config_t that contains the channel s configuration parameters.
At this point, the channel should start operating and generating the PWM signal on the selected GPIO, as configured
in ledc_channel_config_t, with the frequency specified in the timer settings and the given duty cycle. The
channel operation (signal generation) can be suspended at any time by calling the function ledc_stop().
Change PWM Signal Once the channel starts operating and generating the PWM signal with the constant duty
cycle and frequency, there are a couple of ways to change this signal. When driving LEDs, primarily the duty cycle
is changed to vary the light intensity.
The following two sections describe how to change the duty cycle using software and hardware fading. If required,
the signal s frequency can also be changed; it is covered in Section Change PWM Frequency.
Change PWM Duty Cycle Using Software To set the duty cycle, use the dedicated function
ledc_set_duty(). After that, call ledc_update_duty() to activate the changes. To check the
currently set value, use the corresponding _get_ function ledc_get_duty().
Another way to set the duty cycle, as well as some other channel parameters, is by calling
ledc_channel_config() covered in Section Channel Configuration.

The range of the duty cycle values passed to functions depends on selected duty_resolution and should be
from 0 to (2 ** duty_resolution) - 1. For example, if the selected duty resolution is 10, then the duty
cycle values can range from 0 to 1023. This provides the resolution of ~0.1%.
Change PWM Duty Cycle using Hardware The LEDC hardware provides the means to gradually transition from
one duty cycle value to another. To use this functionality, enable fading with ledc_fade_func_install()
and then configure it by calling one of the available fading functions:
• ledc_set_fade_with_time()
• ledc_set_fade_with_step()
• ledc_set_fade()
Finally start fading with ledc_fade_start().
If not required anymore, fading and an associated interrupt can be disabled with
ledc_fade_func_uninstall().
Change PWM Frequency The LEDC API provides several ways to change the PWM frequency on the fly :
• Set the frequency by calling ledc_set_freq(). There is a corresponding function ledc_get_freq()
to check the current frequency.
• Change the frequency and the duty resolution by calling ledc_bind_channel_timer() to bind some
other timer to the channel.
• Change the channel s timer by calling ledc_channel_config().
More Control Over PWM There are several lower level timer-specific functions that can be used to change PWM
settings:
• ledc_timer_set()
• ledc_timer_rst()
• ledc_timer_pause()
• ledc_timer_resume()
The first two functions are called behind the scenes by ledc_channel_config() to provide a startup of a
timer after it is configured.
Use Interrupts When configuring an LEDC channel, one of the parameters selected within
ledc_channel_config_t is ledc_intr_type_t which triggers an interrupt on fade completion.
For registration of a handler to address this interrupt, call ledc_isr_register().
LEDC High and Low Speed Mode
High speed mode enables a glitch-free changeover of timer settings. This means that if the timer settings are modified,
the changes will be applied automatically on the next overflow interrupt of the timer. In contrast, when updating the
low-speed timer, the change of settings should be explicitly triggered by software. The LEDC driver handles it in the
background, e.g., when ledc_timer_config() or ledc_timer_set() is called.
For additional details regarding speed modes, see ESP32 Technical Reference Manual > LED PWM Controller (LEDC)
[PDF]. Please note that the support for SLOW_CLOCK mentioned in this manual is not yet supported in the LEDC
driver.
Supported Range of Frequency and Duty Resolutions
The LED PWM Controller is designed primarily to drive LEDs. It provides a large flexibility of PWM duty cycle
settings. For instance, the PWM frequency of 5 kHz can have the maximum duty resolution of 13 bits. This means
that the duty can be set anywhere from 0 to 100% with a resolution of ~0.012% (2 ** 13 = 8192 discrete levels of the
LED intensity). Note, however, that these parameters depend on the clock signal clocking the LED PWM Controller

timer which in turn clocks the channel (see timer configuration and the ESP32 Technical Reference Manual > LED
PWM Controller (LEDC) [PDF]).
The LEDC can be used for generating signals at much higher frequencies that are sufficient enough to clock other
devices, e.g., a digital camera module. In this case, the maximum available frequency is 40 MHz with duty resolution
of 1 bit. This means that the duty cycle is fixed at 50% and cannot be adjusted.
The LEDC API is designed to report an error when trying to set a frequency and a duty resolution that exceed the
range of LEDC s hardware. For example, an attempt to set the frequency to 20 MHz and the duty resolution to 3
bits will result in the following error reported on a serial monitor:
E (196) ledc: requested frequency and duty resolution cannot be achieved, try␣
,→reducing freq_hz or duty_resolution. div_param=128
In such a situation, either the duty resolution or the frequency must be reduced. For example, setting the duty
resolution to 2 will resolve this issue and will make it possible to set the duty cycle at 25% steps, i.e., at 25%, 50%
or 75%.
The LEDC driver will also capture and report attempts to configure frequency / duty resolution combinations that are
below the supported minimum, e.g.:
E (196) ledc: requested frequency and duty resolution cannot be achieved, try␣
,→increasing freq_hz or duty_resolution. div_param=128000000
The duty resolution is normally set using ledc_timer_bit_t. This enumeration covers the range from 10 to 15
bits. If a smaller duty resolution is required (from 10 down to 1), enter the equivalent numeric values directly.
Application Example
The LEDC change duty cycle and fading control example: peripherals/ledc/ledc_fade.
The LEDC basic example: peripherals/ledc/ledc_basic.
API Reference
Header File
• components/driver/include/driver/ledc.h
Functions
esp_err_t ledc_channel_config(const ledc_channel_config_t *ledc_conf)
LEDC channel configuration Configure LEDC channel with the given channel/output
gpio_num/interrupt/source timer/frequency(Hz)/LEDC duty resolution.
Return
• ESP_OK Success
Parameters
• ledc_conf: Pointer of LEDC channel configure struct
esp_err_t ledc_timer_config(const ledc_timer_config_t *timer_conf)
LEDC timer configuration Configure LEDC timer with the given source timer/frequency(Hz)/duty_resolution.
Return
• ESP_OK Success
• ESP_FAIL Can not find a proper pre-divider number base on the given frequency and the current
duty_resolution.
Parameters
• timer_conf: Pointer of LEDC timer configure struct

esp_err_t ledc_update_duty(ledc_mode_t speed_mode, ledc_channel_t channel)

LEDC update channel parameters.
Note Call this function to activate the LEDC updated parameters. After ledc_set_duty, we need to call this
function to update the settings.
Note ledc_set_duty, ledc_set_duty_with_hpoint and ledc_update_duty are not thread-safe, do not call these
functions to control one LEDC channel in different tasks at the same time. A thread-safe version of API
is ledc_set_duty_and_update
Return
• ESP_OK Success
Parameters
• speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets
support high speed mode.
• channel: LEDC channel (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t
esp_err_t ledc_set_pin(int gpio_num, ledc_mode_t speed_mode, ledc_channel_t ledc_channel)
Set LEDC output gpio.
Return
• ESP_OK Success
Parameters
• gpio_num: The LEDC output gpio
• ledc_channel: LEDC channel (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t
esp_err_t ledc_stop(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t idle_level)
LEDC stop. Disable LEDC output, and set idle level.
Return
• ESP_OK Success
Parameters
• idle_level: Set output idle level after LEDC stops.
esp_err_t ledc_set_freq(ledc_mode_t speed_mode, ledc_timer_t timer_num, uint32_t freq_hz)
LEDC set channel frequency (Hz)
Return
• ESP_OK Success
• ESP_FAIL Can not find a proper pre-divider number base on the given frequency and the current
duty_resolution.
Parameters
• timer_num: LEDC timer index (0-3), select from ledc_timer_t
• freq_hz: Set the LEDC frequency
uint32_t ledc_get_freq(ledc_mode_t speed_mode, ledc_timer_t timer_num)
LEDC get channel frequency (Hz)
Return
• 0 error
• Others Current LEDC frequency
Parameters

• timer_num: LEDC timer index (0-3), select from ledc_timer_t

esp_err_t ledc_set_duty_with_hpoint(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t
duty, uint32_t hpoint)
LEDC set duty and hpoint value Only after calling ledc_update_duty will the duty update.
is ledc_set_duty_and_update
Note If a fade operation is running in progress on that channel, the driver would not allow it to be stopped.
Other duty operations will have to wait until the fade operation has finished.
Return
• ESP_OK Success
Parameters
• duty: Set the LEDC duty, the range of duty setting is [0, (2**duty_resolution) - 1]
• hpoint: Set the LEDC hpoint value(max: 0xfffff)
int ledc_get_hpoint(ledc_mode_t speed_mode, ledc_channel_t channel)
LEDC get hpoint value, the counter value when the output is set high level.
Return
• LEDC_ERR_VAL if parameter error
• Others Current hpoint value of LEDC channel
Parameters
esp_err_t ledc_set_duty(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t duty)
LEDC set duty This function do not change the hpoint value of this channel. if needed, please call
ledc_set_duty_with_hpoint. only after calling ledc_update_duty will the duty update.
is ledc_set_duty_and_update.
Return
• ESP_OK Success
Parameters
uint32_t ledc_get_duty(ledc_mode_t speed_mode, ledc_channel_t channel)
LEDC get duty.
Return
• LEDC_ERR_DUTY if parameter error
• Others Current LEDC duty
Parameters

esp_err_t ledc_set_fade(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t duty,

ledc_duty_direction_t fade_direction, uint32_t step_num, uint32_t
duty_cycle_num, uint32_t duty_scale)
LEDC set gradient Set LEDC gradient, After the function calls the ledc_update_duty function, the function
can take effect.
Return
• ESP_OK Success
Parameters
• duty: Set the start of the gradient duty, the range of duty setting is [0, (2**duty_resolution) - 1]
• fade_direction: Set the direction of the gradient
• step_num: Set the number of the gradient
• duty_cycle_num: Set how many LEDC tick each time the gradient lasts
• duty_scale: Set gradient change amplitude
esp_err_t ledc_isr_register(void (*fn))void *
, void *arg, int intr_alloc_flags, ledc_isr_handle_t *handleRegister LEDC interrupt handler, the handler is an
Return
• ESP_OK Success
• ESP_ERR_INVALID_ARG Function pointer error.
Parameters
• arg: User-supplied argument passed to the handler function.
esp_err_t ledc_timer_set(ledc_mode_t speed_mode, ledc_timer_t timer_sel, uint32_t clock_divider,
uint32_t duty_resolution, ledc_clk_src_t clk_src)
Configure LEDC settings.
Return
• (-1) Parameter error
• Other Current LEDC duty
Parameters
• timer_sel: Timer index (0-3), there are 4 timers in LEDC module
• clock_divider: Timer clock divide value, the timer clock is divided from the selected clock
source
• duty_resolution: Resolution of duty setting in number of bits. The range of duty values is
[0, (2**duty_resolution)]
• clk_src: Select LEDC source clock.
esp_err_t ledc_timer_rst(ledc_mode_t speed_mode, ledc_timer_t timer_sel)
Reset LEDC timer.
Return
• ESP_OK Success
Parameters
• timer_sel: LEDC timer index (0-3), select from ledc_timer_t

esp_err_t ledc_timer_pause(ledc_mode_t speed_mode, ledc_timer_t timer_sel)

Pause LEDC timer counter.
Return
• ESP_OK Success
Parameters
esp_err_t ledc_timer_resume(ledc_mode_t speed_mode, ledc_timer_t timer_sel)
Resume LEDC timer.
Return
• ESP_OK Success
Parameters
esp_err_t ledc_bind_channel_timer(ledc_mode_t speed_mode, ledc_channel_t channel,
ledc_timer_t timer_sel)
Bind LEDC channel with the selected timer.
Return
• ESP_OK Success
Parameters
• channel: LEDC channel index (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t
esp_err_t ledc_set_fade_with_step(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t
target_duty, uint32_t scale, uint32_t cycle_num)
Set LEDC fade function.
Note Call ledc_fade_func_install() once before calling this function. Call ledc_fade_start() after this to start
fading.
Note ledc_set_fade_with_step, ledc_set_fade_with_time and ledc_fade_start are not thread-safe, do not call
these functions to control one LEDC channel in different tasks at the same time. A thread-safe version
of API is ledc_set_fade_step_and_start
Return
• ESP_OK Success
• ESP_ERR_INVALID_STATE Fade function not installed.
• ESP_FAIL Fade function init error
Parameters
support high speed mode. ,
• target_duty: Target duty of fading [0, (2**duty_resolution) - 1]
• scale: Controls the increase or decrease step scale.
• cycle_num: increase or decrease the duty every cycle_num cycles
esp_err_t ledc_set_fade_with_time(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t
target_duty, int max_fade_time_ms)
Set LEDC fade function, with a limited time.

Note Call ledc_fade_func_install() once before calling this function. Call ledc_fade_start() after this to start
fading.
Note ledc_set_fade_with_step, ledc_set_fade_with_time and ledc_fade_start are not thread-safe, do not call
these functions to control one LEDC channel in different tasks at the same time. A thread-safe version
of API is ledc_set_fade_step_and_start
Return
• ESP_OK Success
Parameters
support high speed mode. ,
• max_fade_time_ms: The maximum time of the fading ( ms ).
esp_err_t ledc_fade_func_install(int intr_alloc_flags)
Install LEDC fade function. This function will occupy interrupt of LEDC module.
Return
• ESP_OK Success
• ESP_ERR_INVALID_STATE Fade function already installed.
Parameters
void ledc_fade_func_uninstall(void)
Uninstall LEDC fade function.
esp_err_t ledc_fade_start(ledc_mode_t speed_mode, ledc_channel_t channel, ledc_fade_mode_t
fade_mode)
Start LEDC fading.
Note Call ledc_fade_func_install() once before calling this function. Call this API right after
ledc_set_fade_with_time or ledc_set_fade_with_step before to start fading.
Return
• ESP_OK Success
• ESP_ERR_INVALID_ARG Parameter error.
Parameters
• channel: LEDC channel number
• fade_mode: Whether to block until fading done.
esp_err_t ledc_set_duty_and_update(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t
duty, uint32_t hpoint)
A thread-safe API to set duty for LEDC channel and return when duty updated.
Parameters
• hpoint: Set the LEDC hpoint value(max: 0xfffff)

esp_err_t ledc_set_fade_time_and_start(ledc_mode_t speed_mode, ledc_channel_t channel,

uint32_t target_duty, uint32_t max_fade_time_ms,
ledc_fade_mode_t fade_mode)
A thread-safe API to set and start LEDC fade function, with a limited time.
Note Call ledc_fade_func_install() once, before calling this function.
Return
• ESP_OK Success
Parameters
• max_fade_time_ms: The maximum time of the fading ( ms ).
• fade_mode: choose blocking or non-blocking mode
esp_err_t ledc_set_fade_step_and_start(ledc_mode_t speed_mode, ledc_channel_t channel,
uint32_t target_duty, uint32_t scale, uint32_t cy-
cle_num, ledc_fade_mode_t fade_mode)
A thread-safe API to set and start LEDC fade function.
Note Call ledc_fade_func_install() once before calling this function.
Return
• ESP_OK Success
Parameters
• scale: Controls the increase or decrease step scale.
• cycle_num: increase or decrease the duty every cycle_num cycles
• fade_mode: choose blocking or non-blocking mode
esp_err_t ledc_cb_register(ledc_mode_t speed_mode, ledc_channel_t channel, ledc_cbs_t *cbs, void
*user_arg)
LEDC callback registration function.
Note The callback is called from an ISR, it must never attempt to block, and any FreeRTOS API called must
be ISR capable.
Return
• ESP_OK Success
Parameters
• cbs: Group of LEDC callback functions
• user_arg: user registered data for the callback function

Structures
struct ledc_channel_config_t
Configuration parameters of LEDC channel for ledc_channel_config function.
Public Members
int gpio_num
the LEDC output gpio_num, if you want to use gpio16, gpio_num = 16
ledc_mode_t speed_mode
LEDC speed speed_mode, high-speed mode or low-speed mode
ledc_channel_t channel
LEDC channel (0 - 7)
ledc_intr_type_t intr_type
configure interrupt, Fade interrupt enable or Fade interrupt disable
ledc_timer_t timer_sel
Select the timer source of channel (0 - 3)
uint32_t duty
LEDC channel duty, the range of duty setting is [0, (2**duty_resolution)]
int hpoint
LEDC channel hpoint value, the max value is 0xfffff
unsigned int output_invert : 1
Enable (1) or disable (0) gpio output invert
struct ledc_channel_config_t::[anonymous] flags
LEDC flags
struct ledc_timer_config_t
Configuration parameters of LEDC Timer timer for ledc_timer_config function.
Public Members
ledc_mode_t speed_mode
LEDC speed speed_mode, high-speed mode or low-speed mode
ledc_timer_bit_t duty_resolution
LEDC channel duty resolution
ledc_timer_bit_t bit_num
Deprecated in ESP-IDF 3.0. This is an alias to duty_resolution for backward compatibility with
ESP-IDF 2.1
ledc_timer_t timer_num
The timer source of channel (0 - 3)
uint32_t freq_hz
LEDC timer frequency (Hz)
ledc_clk_cfg_t clk_cfg
Configure LEDC source clock. For low speed channels and high speed channels, you can specify the
source clock using LEDC_USE_REF_TICK, LEDC_USE_APB_CLK or LEDC_AUTO_CLK. For low
speed channels, you can also specify the source clock using LEDC_USE_RTC8M_CLK, in this case, all
low speed channel s source clock must be RTC8M_CLK
struct ledc_cb_param_t
LEDC callback parameter.

Public Members
ledc_cb_event_t event
Event name
uint32_t speed_mode
Speed mode of the LEDC channel group
uint32_t channel
LEDC channel (0 - LEDC_CHANNEL_MAX-1)
uint32_t duty
LEDC current duty of the channel, the range of duty is [0, (2**duty_resolution) - 1]
struct ledc_cbs_t
Group of supported LEDC callbacks.
Note The callbacks are all running under ISR environment
Public Members
ledc_cb_t fade_cb
LEDC fade_end callback function
Macros
LEDC_APB_CLK_HZ
LEDC_REF_CLK_HZ
LEDC_ERR_DUTY
LEDC_ERR_VAL
Type Definitions
typedef intr_handle_t ledc_isr_handle_t
typedef bool (*ledc_cb_t)(const ledc_cb_param_t *param, void *user_arg)
Type of LEDC event callback.
Parameters
• param: LEDC callback parameter
• user_arg: User registered data
Enumerations
enum ledc_cb_event_t
LEDC callback event type.
Values:
LEDC_FADE_END_EVT
LEDC fade end event
Header File
• components/hal/include/hal/ledc_types.h
Enumerations
enum ledc_mode_t
Values:
LEDC_HIGH_SPEED_MODE = 0
LEDC high speed speed_mode

LEDC_LOW_SPEED_MODE
LEDC low speed speed_mode
LEDC_SPEED_MODE_MAX
LEDC speed limit
enum ledc_intr_type_t
Values:
LEDC_INTR_DISABLE = 0
Disable LEDC interrupt
LEDC_INTR_FADE_END
Enable LEDC interrupt
LEDC_INTR_MAX
enum ledc_duty_direction_t
Values:
LEDC_DUTY_DIR_DECREASE = 0
LEDC duty decrease direction
LEDC_DUTY_DIR_INCREASE = 1
LEDC duty increase direction
LEDC_DUTY_DIR_MAX
enum ledc_slow_clk_sel_t
Values:
LEDC_SLOW_CLK_RTC8M = 0
LEDC low speed timer clock source is 8MHz RTC clock
LEDC_SLOW_CLK_APB
LEDC low speed timer clock source is 80MHz APB clock
enum ledc_clk_cfg_t
In theory, the following enumeration shall be placed in LEDC driver s header. However, as the next enu-
meration, ledc_clk_src_t, makes the use of some of these values and to avoid mutual inclusion of the
headers, we must define it here.
Values:
LEDC_AUTO_CLK = 0
The driver will automatically select the source clock(REF_TICK or APB) based on the giving resolution
and duty parameter when init the timer
LEDC_USE_APB_CLK
LEDC timer select APB clock as source clock
LEDC_USE_RTC8M_CLK
LEDC timer select RTC8M_CLK as source clock. Only for low speed channels and this parameter must
be the same for all low speed channels
LEDC_USE_REF_TICK
LEDC timer select REF_TICK clock as source clock
enum ledc_clk_src_t
Values:
LEDC_REF_TICK = LEDC_USE_REF_TICK
LEDC timer clock divided from reference tick (1Mhz)
LEDC_APB_CLK = LEDC_USE_APB_CLK
LEDC timer clock divided from APB clock (80Mhz)
LEDC_SCLK = LEDC_USE_APB_CLK
Selecting this value for LEDC_TICK_SEL_TIMER let the hardware take its source clock from
LEDC_APB_CLK_SEL

enum ledc_timer_t
Values:
LEDC_TIMER_0 = 0
LEDC timer 0
LEDC_TIMER_1
LEDC timer 1
LEDC_TIMER_2
LEDC timer 2
LEDC_TIMER_3
LEDC timer 3
LEDC_TIMER_MAX
enum ledc_channel_t
Values:
LEDC_CHANNEL_0 = 0
LEDC channel 0
LEDC_CHANNEL_1
LEDC channel 1
LEDC_CHANNEL_2
LEDC channel 2
LEDC_CHANNEL_3
LEDC channel 3
LEDC_CHANNEL_4
LEDC channel 4
LEDC_CHANNEL_5
LEDC channel 5
LEDC_CHANNEL_6
LEDC channel 6
LEDC_CHANNEL_7
LEDC channel 7
LEDC_CHANNEL_MAX
enum ledc_timer_bit_t
Values:
LEDC_TIMER_1_BIT = 1
LEDC PWM duty resolution of 1 bits
LEDC_TIMER_2_BIT
LEDC_TIMER_3_BIT
LEDC_TIMER_4_BIT
LEDC_TIMER_5_BIT
LEDC_TIMER_6_BIT
LEDC_TIMER_7_BIT

LEDC_TIMER_8_BIT
LEDC_TIMER_9_BIT
LEDC_TIMER_10_BIT
LEDC_TIMER_11_BIT
LEDC_TIMER_12_BIT
LEDC_TIMER_13_BIT
LEDC_TIMER_14_BIT
LEDC_TIMER_15_BIT
LEDC_TIMER_16_BIT
LEDC_TIMER_17_BIT
LEDC_TIMER_18_BIT
LEDC_TIMER_19_BIT
LEDC_TIMER_20_BIT
LEDC_TIMER_BIT_MAX
enum ledc_fade_mode_t
Values:
LEDC_FADE_NO_WAIT = 0
LEDC fade function will return immediately
LEDC_FADE_WAIT_DONE
LEDC fade function will block until fading to the target duty
LEDC_FADE_MAX
2.3.9 Motor Control Pulse Width Modulator (MCPWM)
ESP32 has two MCPWM units which can be used to control different types of motors. Each unit has three pairs of
PWM outputs.
Further in documentation the outputs of a single unit are labeled PWMxA / PWMxB.
More detailed block diagram of the MCPWM unit is shown below. Each A/B pair may be clocked by any one of
the three timers Timer 0, 1 and 2. The same timer may be used to clock more than one pair of PWM outputs. Each
unit is also able to collect inputs such as SYNC SIGNALS, detect FAULT SIGNALS like motor overcurrent or
overvoltage, as well as obtain feedback with CAPTURE SIGNALS on e.g. a rotor position.
Description of this API starts with configuration of MCPWM s Timer and Generator submodules to provide
the basic motor control functionality. Then it discusses more advanced submodules and functionalities of a Fault
Handler, signal Capture and Carrier.

Fig. 12: MCPWM Overview
Fig. 13: MCPWM Block Diagram

Contents
• Configure a basic functionality of the outputs

• Operate the outputs to drive a motor
• Adjust how the motor is driven
• Synchronize sync timers to work together
• Capture external signals to provide additional control over the outputs
• Use Fault Handler to detect and manage faults
• Add a higher frequency Carrier, if output signals are passed through an isolation transformer
• Extra configuration of Resolution.
Configure
The scope of configuration depends on the motor type, in particular how many outputs and inputs are required, and
what will be the sequence of signals to drive the motor.
In this case we will describe a simple configuration to control a brushed DC motor that is using only some of the
available MCPWM s resources. An example circuit is shown below. It includes a H-Bridge to switch polarization
of a voltage applied to the motor (M) and to provide sufficient current to drive it.
Fig. 14: Example of Brushed DC Motor Control with MCPWM
Configuration covers the following steps:

1. Selection of a MCPWM unit that will be used to drive the motor. There are two units available on-board of
ESP32 and enumerated in mcpwm_unit_t.
2. Initialization of two GPIOs as output signals within selected unit by calling mcpwm_gpio_init(). The
two output signals are typically used to command the motor to rotate right or left. All available signal
options are listed in mcpwm_io_signals_t. To set more than a single pin at a time, use function
mcpwm_set_pin() together with mcpwm_pin_config_t.
3. Selection of a timer. There are three timers available within the unit. The timers are listed in
mcpwm_timer_t.
4. Setting of the timer frequency and initial duty within mcpwm_config_t structure.
5. Setting timer resolution if necessary, by calling mcpwm_group_set_resolution() and
mcpwm_timer_set_resolution()
6. Calling of mcpwm_init() with the above parameters to make the configuration effective.

Operate
To operate a motor connected to the MCPWM unit, e.g. turn it left or right, or vary the speed, we should apply some
control signals to the unit s outputs. The outputs are organized into three pairs. Within a pair they are labeled A
and B and each driven by a submodule called an Generator . To provide a PWM signal, the Operator itself,
which contains two Generator, should be clocked by one of three available Timers. To make the API simpler, each
Timer is automatically associated by the API to drive an Operator of the same index, e.g. Timer 0 is associated with
Operator 0.
There are the following basic ways to control the outputs:
• We can drive particular signal steady high or steady low with function mcpwm_set_signal_high() or
mcpwm_set_signal_low(). This will make the motor to turn with a maximum speed or stop. Depending
on selected output A or B the motor will rotate either right or left.
• Another option is to drive the outputs with the PWM signal by calling mcpwm_start() or
mcpwm_stop(). The motor speed will be proportional to the PWM duty.
• To vary PWM s duty call mcpwm_set_duty() and provide the duty value in %. Optionally, you
may call mcpwm_set_duty_in_us(), if you prefer to set the duty in microseconds. Checking of cur-
rently set value is possible by calling mcpwm_get_duty(). Phase of the PWM signal may be altered
by calling mcpwm_set_duty_type(). The duty is set individually for each A and B output using
mcpwm_generator_t in specific function calls. The duty value refers either to high or low output signal
duration. This is configured when calling mcpwm_init(), as discussed in section Configure, and selecting
one of options from mcpwm_duty_type_t.
Note: Call function mcpwm_set_duty_type() every time after mcpwm_set_signal_high() or

mcpwm_set_signal_low() to resume with previously set duty cycle.
Adjust
There are couple of ways to adjust a signal on the outputs and changing how the motor operates.
• Set specific PWM frequency by calling mcpwm_set_frequency(). This may be required to adjust to
electrical or mechanical characteristics of particular motor and driver. To check what frequency is set, use
function mcpwm_get_frequency().
• Introduce a dead time between outputs A and B when they are changing the state to reverse direction of the
motor rotation. This is to make up for on/off switching delay of the motor driver FETs. The dead time options
are defined in mcpwm_deadtime_type_t and enabled by calling mcpwm_deadtime_enable(). To
disable this functionality call mcpwm_deadtime_disable().
• Synchronize outputs of operator submodules, e.g. to get raising edge of PWM0A/B and PWM1A/B to start ex-
actly at the same time, or shift them between each other by a given phase. Synchronization is triggered by SYNC
SIGNALS shown on the block diagram of the MCPWM above, and defined in mcpwm_sync_signal_t.
To attach the signal to a GPIO call mcpwm_gpio_init(). You can then enable synchronization with func-
tion mcpwm_sync_configure(). As input parameters provide MCPWM unit, timer to synchronize, the
synchronization signal and a phase to delay the timer.
Note: Synchronization signals are referred to using two different enumerations. First one
mcpwm_io_signals_t is used together with function mcpwm_gpio_init() when selecting a GPIO
as the signal input source. The second one mcpwm_sync_signal_t is used when enabling or disabling
synchronization with mcpwm_sync_configure() or mcpwm_sync_disable().
• Vary the pattern of the A/B output signals by getting MCPWM counters to count up, down and up/down
(automatically changing the count direction). Respective configuration is done when calling mcpwm_init(),
as discussed in section Configure, and selecting one of counter types from mcpwm_counter_type_t. For
explanation of how A/B PWM output signals are generated, see ESP32 Technical Reference Manual > Motor
Control PWM (MCPWM) [PDF].

Synchronize
Each PWM timer has a synchronization input and a synchronization output. The synchronization input can be selected
from other timers synchronization outputs or GPIO signals via the GPIO matrix. Timer s synchronization signal
can be generated from either the input sync signal or when the count value reaches peak/zero. Thus, the PWM timers
can be chained together with their phase-locked. During synchronization, the PWM timer clock prescaler will reset
its counter in order to synchronize the PWM timer clock.
The functionality is enabled in following steps:
1. Make sure the PWM timer and operator are already configured so that sync will inherit its config (count mode,
freq and duty).
2. Enabling sync input of the timer by invoking mcpwm_sync_configure(), selecting desired signal input
from mcpwm_sync_signal_t, and setting the desired phase range from 0 to 999 which is mapped to
0%~99.9%. 0 means zero phase is applied and output is fired at the same time. And selecting desired counting
direction.
3. Enabling one of sync event source from another timer or from external GPIO input.
To sync with another timer:
Enabling sync output of another timer by invoking mcpwm_set_timer_sync_output() and selecting desired
event to generate sync output from mcpwm_timer_sync_trigger_t.
To sync with GPIO positive edge input (negative edge requires mcpwm_sync_invert_gpio_synchro()):
Configuring GPIOs to act as the sync signal inputs by calling functions mcpwm_gpio_init() or
mcpwm_set_pin(), which were described in section Configure.
It s normal condition that chained sync signal may have tens or even hundreds of nanoseconds of delay between
each timer output due to hardware limitation. To sync two timers accurately it is required to have the third timer
occupied to produce sync event that can be consumed parallel by other two timer, so that those two timer will have
no delay between each other but have the same delay between the timer which provides events. Another solution is
introducing an external GPIO event source so that all three timers can be synced together with no delay.
If not required anymore, the capture functionality may be disabled with mcpwm_sync_disable().
Capture
One of requirements of BLDC (Brushless DC, see figure below) motor control is sensing of the rotor position. To
facilitate this task each MCPWM unit provides three sensing inputs together with dedicated hardware. The hardware
is able to detect the input signal s edge and measure time between signals. As result the control software is simpler
and the CPU power may be used for other tasks.
The capture functionality may be used for other types of motors or tasks. The functionality is enabled in two steps:
1. Configuration of GPIOs to act as the capture signal inputs by calling functions mcpwm_gpio_init() or
mcpwm_set_pin(), that were described in section Configure.
2. Enabling of the functionality itself by invoking mcpwm_capture_enable_channel(), selecting desired
signal input from mcpwm_capture_channel_id_t, setting the signal edge, signal count prescaler and
user callback within mcpwm_capture_config_t
Within the second step above a 32-bit capture timer is enabled. The timer runs continuously driven by the APB
clock. The clock frequency is typically 80 MHz. On each capture event the capture timer s value is stored in time-
stamp register that may be then checked by calling mcpwm_capture_signal_get_value(). The edge of
the last signal may be checked with mcpwm_capture_signal_get_edge(). Those data are also provided
inside callback function as event data cap_event_data_t
If not required anymore, the capture functionality may be disabled with
mcpwm_capture_disable_channel().
Capture prescale is different from other modules as it is applied to the input signal, not the timer source. Prescaler
has maintained its own level state with the initial value set to low and is detecting the positive edge of the input
signal to change its internal state. That means if two pairs of positive and negative edges are passed to input, the
prescaler s internal state will change twice. ISR will report on this internal state change, not the input signal.

Fig. 15: Example of Brushless DC Motor Control with MCPWM
For example, setting prescale to 2 will generate ISR callback on each positive edge of input if both edge is se-
lected via mcpwm_capture_config_t. Or each 2 positive edges of input if only one edge is selected though
mcpwm_capture_config_t.
Fault Handler
Each unit of the MCPWM is able to sense external signals with information about failure of the motor, the motor
driver or any other device connected to the MCPWM. There are three fault inputs per unit that may be routed to user
selectable GPIOs. The MCPWM may be configured to perform one of four predefined actions on A/B outputs when
a fault signal is received:
• lock current state of the output
• set the output low
• set the output high
• toggle the output
The user should determine possible failure modes of the motor and what action should be performed on detection of
particular fault, e.g. drive all outputs low for a brushed motor, or lock current state for a stepper motor, etc. As result
of this action the motor should be put into a safe state to reduce likelihood of a damage caused by the fault.
The fault handler functionality is enabled in two steps:
1. Configuration of GPIOs to act as fault signal inputs. This is done in analogous way as described for
capture signals in section above. It includes setting the signal level to trigger the fault as defined in
mcpwm_fault_input_level_t.
2. Initialization of the fault handler by calling either mcpwm_fault_set_oneshot_mode() or
mcpwm_fault_set_cyc_mode(). These functions set the mode that MCPWM should operate once
fault signal becomes inactive. There are two modes possible:
• State of MCPWM unit will be locked until reset - mcpwm_fault_set_oneshot_mode().
• The MCPWM will resume operation once fault signal becoming inactive -
mcpwm_fault_set_cyc_mode().

The function call parameters include selection of one of three fault inputs defined
in mcpwm_fault_signal_t and specific action on outputs A and B defined in
mcpwm_action_on_pwmxa_t and mcpwm_action_on_pwmxb_t.
Particular fault signal may be disabled at the runtime by calling mcpwm_fault_deinit().
Carrier
The MCPWM has a carrier submodule used if galvanic isolation from the motor driver is required by passing the A/B
output signals through transformers. Any of A and B output signals may be at 100% duty and not changing whenever
motor is required to run steady at the full load. Coupling of non alternating signals with a transformer is problematic,
so the signals are modulated by the carrier submodule to create an AC waveform, to make the coupling possible.
To use the carrier submodule, it should be first initialized by calling mcpwm_carrier_init(). The carrier
parameters are defined in mcpwm_carrier_config_t structure invoked within the function call. Then the
carrier functionality may be enabled by calling mcpwm_carrier_enable().
The carrier parameters may be then altered at a runtime by calling dedicated functions to change in-
dividual fields of the mcpwm_carrier_config_t structure, like mcpwm_carrier_set_period(),
mcpwm_carrier_set_duty_cycle(), mcpwm_carrier_output_invert(), etc.
This includes enabling and setting duration of the first pulse of the career with
mcpwm_carrier_oneshot_mode_enable(). For more details, see ESP32 Technical Reference Man-
ual > Motor Control PWM (MCPWM) > PWM Carrier Submodule [PDF].
To disable carrier functionality call mcpwm_carrier_disable().
Interrupts
Registering of the MCPWM interrupt handler is possible by calling mcpwm_isr_register(). Note if

mcpwm_capture_enable_channel() is used then a default ISR routine will be installed hence please do
not call this function to register any more.
Resolution
The default resolution for MCPWM group and MCPWM timer are configured to 10MHz and 1MHz
in mcpwm_init(), which might be not enough for some applications. The driver also provides two
APIs that can be used to override the default resolution: mcpwm_group_set_resolution() and
mcpwm_timer_set_resolution().
Note that, these two APIs won t update the frequency and duty automatically, to achieve that, one has to call
mcpwm_set_frequency() and mcpwm_set_duty() accordingly.
To get PWM pulse that is below 15Hz, please set the resolution to a lower value. For high frequency PWM with
limited step range, please set them with higher value.
Application Example
MCPWM example are located under: peripherals/mcpwm:

• Control of BLDC (brushless DC) motor with hall sensor feedback - peripher-
als/mcpwm/mcpwm_bldc_hall_control
• Brushed DC motor control - peripherals/mcpwm/mcpwm_brushed_dc_control
• Servo motor control - peripherals/mcpwm/mcpwm_servo_control
• HC-SR04 sensor with capture - peripherals/mcpwm/mcpwm_capture_hc_sr04

API Reference
Header File
• components/hal/include/hal/mcpwm_types.h
Enumerations
enum mcpwm_timer_direction_t
Values:
MCPWM_TIMER_DIRECTION_UP
Counting direction: Increase
MCPWM_TIMER_DIRECTION_DOWN
Counting direction: Decrease
enum mcpwm_timer_event_t
Values:
MCPWM_TIMER_EVENT_ZERO
MCPWM timer counts to zero
MCPWM_TIMER_EVENT_PEAK
MCPWM timer counts to peak
enum mcpwm_timer_count_mode_t
Values:
MCPWM_TIMER_COUNT_MODE_PAUSE
MCPWM timer paused
MCPWM_TIMER_COUNT_MODE_UP
MCPWM timer counting up
MCPWM_TIMER_COUNT_MODE_DOWN
MCPWM timer counting down
MCPWM_TIMER_COUNT_MODE_UP_DOWN
MCPWM timer counting up and down
enum mcpwm_timer_execute_cmd_t
Values:
MCPWM_TIMER_STOP_AT_ZERO
MCPWM timer stops when couting to zero
MCPWM_TIMER_STOP_AT_PEAK
MCPWM timer stops when counting to peak
MCPWM_TIMER_START_NO_STOP
MCPWM timer starts couting
MCPWM_TIMER_START_STOP_AT_ZERO
MCPWM timer starts counting and stops when couting to zero
MCPWM_TIMER_START_STOP_AT_PEAK
MCPWM timer starts counting and stops when counting to peak
enum mcpwm_generator_action_t
Values:
MCPWM_GEN_ACTION_KEEP
Generator action: Keep the same level
MCPWM_GEN_ACTION_LOW
Generator action: Force to low level

MCPWM_GEN_ACTION_HIGH
Generator action: Force to high level
MCPWM_GEN_ACTION_TOGGLE
Generator action: Toggle level
enum mcpwm_trip_type_t
Values:
MCPWM_TRIP_TYPE_CBC
CBC trip type, shut down the operator cycle by cycle
MCPWM_TRIP_TYPE_OST
OST trip type, shut down the operator in one shot
Header File
• components/driver/include/driver/mcpwm.h
Functions
esp_err_t mcpwm_gpio_init(mcpwm_unit_t mcpwm_num, mcpwm_io_signals_t io_signal, int
gpio_num)
This function initializes each gpio signal for MCPWM.
Note This function initializes one gpio at a time.
Return
• ESP_OK Success
Parameters
• mcpwm_num: set MCPWM unit(0-1)
• io_signal: set MCPWM signals, each MCPWM unit has 6 output(MCPWMXA, MCPWMXB)
and 9 input(SYNC_X, FAULT_X, CAP_X) X is timer_num(0-2)
• gpio_num: set this to configure gpio for MCPWM, if you want to use gpio16, gpio_num = 16
esp_err_t mcpwm_set_pin(mcpwm_unit_t mcpwm_num, const mcpwm_pin_config_t *mcpwm_pin)
Initialize MCPWM gpio structure.
Note This function initialize a group of MCPWM GPIOs at a time.
Return
• ESP_OK Success
Parameters
• mcpwm_pin: MCPWM pin structure
esp_err_t mcpwm_init(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num, const mcpwm_config_t
*mcpwm_conf)
Initialize MCPWM parameters.
Note The default resolution configured for MCPWM group and timer are 160M / 16 = 10M and 10M
/ 10 = 1M The default resolution can be changed by calling mcpwm_group_set_resolution() and
mcpwm_timer_set_resolution(), before calling this function.
Return
• ESP_OK Success
Parameters
• timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers.
• mcpwm_conf: configure structure mcpwm_config_t
esp_err_t mcpwm_group_set_resolution(mcpwm_unit_t mcpwm_num, unsigned long int resolution)
Set resolution of the MCPWM group.

Note This will override default resolution of group(=10,000,000). This WILL NOT automatically update
frequency and duty. Call mcpwm_set_frequency() and mcpwm_set_duty() manually to set them back.
Return
• ESP_OK Success
Parameters
• resolution: set expected frequency resolution
esp_err_t mcpwm_timer_set_resolution(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num,
unsigned long int resolution)
Set resolution of each timer.
Note This WILL override default resolution of timer(=1,000,000). This WILL NOT automatically update
frequency and duty. Call mcpwm_set_frequency() and mcpwm_set_duty() manually to set them back.
Return
• ESP_OK Success
Parameters
• timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers
• resolution: set expected frequency resolution
esp_err_t mcpwm_set_frequency(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num, uint32_t
frequency)
Set frequency(in Hz) of MCPWM timer.
Return
• ESP_OK Success
Parameters
• frequency: set the frequency in Hz of each timer
esp_err_t mcpwm_set_duty(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num,
mcpwm_generator_t gen, float duty)
Set duty cycle of each operator(MCPWMXA/MCPWMXB)
Return
• ESP_OK Success
Parameters
• gen: set the generator(MCPWMXA/MCPWMXB), X is operator number selected
• duty: set duty cycle in %(i.e for 62.3% duty cycle, duty = 62.3) of each operator
esp_err_t mcpwm_set_duty_in_us(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num,
mcpwm_generator_t gen, uint32_t duty_in_us)
Set duty cycle of each operator(MCPWMXA/MCPWMXB) in us.
Return
• ESP_OK Success
Parameters
• gen: set the generator(MCPWMXA/MCPWMXB), x is operator number selected
• duty_in_us: set duty value in microseconds of each operator
esp_err_t mcpwm_set_duty_type(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num,
mcpwm_generator_t gen, mcpwm_duty_type_t duty_type)

Set duty either active high or active low(out of phase/inverted)

Note Call this function every time after mcpwm_set_signal_high or mcpwm_set_signal_low to resume with
previously set duty cycle
Return
• ESP_OK Success
Parameters
• duty_type: set active low or active high duty type
uint32_t mcpwm_get_frequency(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num)
Get frequency of timer.
Return
• frequency of timer
Parameters
float mcpwm_get_duty(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num, mcpwm_operator_t
gen)
Get duty cycle of each operator.
Return
• duty cycle in % of each operator(56.7 means duty is 56.7%)
Parameters
uint32_t mcpwm_get_duty_in_us(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num,
mcpwm_operator_t gen)
Get duty cycle of each operator in us.
Return
• duty cycle in us of each operator
Parameters
esp_err_t mcpwm_set_signal_high(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num,
mcpwm_generator_t gen)
Use this function to set MCPWM signal high.
Return
• ESP_OK Success
Parameters
• gen: set the operator(MCPWMXA/MCPWMXB), x is timer number selected
esp_err_t mcpwm_set_signal_low(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num,
mcpwm_generator_t gen)
Use this function to set MCPWM signal low.
Return
• ESP_OK Success
Parameters


• gen: set the operator(MCPWMXA/MCPWMXB), x is timer number selected
esp_err_t mcpwm_start(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num)
Start MCPWM signal on timer x .
Return
• ESP_OK Success
Parameters
esp_err_t mcpwm_stop(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num)
Start MCPWM signal on timer x .
Return
• ESP_OK Success
Parameters
esp_err_t mcpwm_carrier_init(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num, const
mcpwm_carrier_config_t *carrier_conf)
Initialize carrier configuration.
Return
• ESP_OK Success
Parameters
• carrier_conf: configure structure mcpwm_carrier_config_t
esp_err_t mcpwm_carrier_enable(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num)
Enable MCPWM carrier submodule, for respective timer.
Return
• ESP_OK Success
Parameters
esp_err_t mcpwm_carrier_disable(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num)
Disable MCPWM carrier submodule, for respective timer.
Return
• ESP_OK Success
Parameters
esp_err_t mcpwm_carrier_set_period(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num,
uint8_t carrier_period)
Set period of carrier.
Return
• ESP_OK Success
Parameters


• carrier_period: set the carrier period of each timer, carrier period = (carrier_period +
1)*800ns (carrier_period <= 15)
esp_err_t mcpwm_carrier_set_duty_cycle(mcpwm_unit_t mcpwm_num, mcpwm_timer_t
timer_num, uint8_t carrier_duty)
Set duty_cycle of carrier.
Return
• ESP_OK Success
Parameters
• carrier_duty: set duty_cycle of carrier , carrier duty cycle = carrier_duty*12.5% (chop_duty
<= 7)
esp_err_t mcpwm_carrier_oneshot_mode_enable(mcpwm_unit_t mcpwm_num, mcpwm_timer_t
timer_num, uint8_t pulse_width)
Enable and set width of first pulse in carrier oneshot mode.
Return
• ESP_OK Success
Parameters
• pulse_width: set pulse width of first pulse in oneshot mode, width = (carrier pe-
riod)*(pulse_width +1) (pulse_width <= 15)
esp_err_t mcpwm_carrier_oneshot_mode_disable(mcpwm_unit_t mcpwm_num, mcpwm_timer_t
timer_num)
Disable oneshot mode, width of first pulse = carrier period.
Return
• ESP_OK Success
Parameters
esp_err_t mcpwm_carrier_output_invert(mcpwm_unit_t mcpwm_num, mcpwm_timer_t
timer_num, mcpwm_carrier_out_ivt_t carrier_ivt_mode)
Enable or disable carrier output inversion.
Return
• ESP_OK Success
Parameters
• carrier_ivt_mode: enable or disable carrier output inversion
esp_err_t mcpwm_deadtime_enable(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num,
mcpwm_deadtime_type_t dt_mode, uint32_t red, uint32_t fed)
Enable and initialize deadtime for each MCPWM timer.
Return
• ESP_OK Success
Parameters

• dt_mode: set deadtime mode

• red: set rising edge delay = red*100ns
• fed: set rising edge delay = fed*100ns
esp_err_t mcpwm_deadtime_disable(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num)
Disable deadtime on MCPWM timer.
Return
• ESP_OK Success
Parameters
esp_err_t mcpwm_fault_init(mcpwm_unit_t mcpwm_num, mcpwm_fault_input_level_t intput_level,
mcpwm_fault_signal_t fault_sig)
Initialize fault submodule, currently low level triggering is not supported.
Return
• ESP_OK Success
Parameters
• intput_level: set fault signal level, which will cause fault to occur
• fault_sig: set the fault pin, which needs to be enabled
esp_err_t mcpwm_fault_set_oneshot_mode(mcpwm_unit_t mcpwm_num, mcpwm_timer_t
timer_num, mcpwm_fault_signal_t fault_sig,
mcpwm_output_action_t action_on_pwmxa,
mcpwm_output_action_t action_on_pwmxb)
Set oneshot mode on fault detection, once fault occur in oneshot mode reset is required to resume MCPWM
signals.
Note currently low level triggering is not supported
Return
• ESP_OK Success
Parameters
• fault_sig: set the fault pin, which needs to be enabled for oneshot mode
• action_on_pwmxa: action to be taken on MCPWMXA when fault occurs, either no change or
high or low or toggle
• action_on_pwmxb: action to be taken on MCPWMXB when fault occurs, either no change or
esp_err_t mcpwm_fault_set_cyc_mode(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num,
mcpwm_fault_signal_t fault_sig, mcpwm_output_action_t
action_on_pwmxa, mcpwm_output_action_t ac-
tion_on_pwmxb)
Set cycle-by-cycle mode on fault detection, once fault occur in cyc mode MCPWM signal resumes as soon as
fault signal becomes inactive.
Note currently low level triggering is not supported
Return
• ESP_OK Success
Parameters
• fault_sig: set the fault pin, which needs to be enabled for cyc mode
• action_on_pwmxa: action to be taken on MCPWMXA when fault occurs, either no change or

• action_on_pwmxb: action to be taken on MCPWMXB when fault occurs, either no change or

esp_err_t mcpwm_fault_deinit(mcpwm_unit_t mcpwm_num, mcpwm_fault_signal_t fault_sig)
Disable fault signal.
Return
• ESP_OK Success
Parameters
• fault_sig: fault pin, which needs to be disabled
esp_err_t mcpwm_capture_enable(mcpwm_unit_t mcpwm_num, mcpwm_capture_signal_t cap_sig,
mcpwm_capture_on_edge_t cap_edge, uint32_t num_of_pulse)
Initialize capture submodule.
Note Enabling capture feature would also enable the capture interrupt event, users have to register an interrupt
handler by mcpwm_isr_register, and in there, query the capture data.
Note The capture timer uses APB_CLK (typically 80MHz) as the count source.
Return
• ESP_OK Success
Parameters
• cap_edge: set capture edge, BIT(0) - negative edge, BIT(1) - positive edge
• cap_sig: capture pin, which needs to be enabled
• num_of_pulse: Input capture signal prescaling, ranges from 0 to 255, representing prescaling
from 1 to 256.
esp_err_t mcpwm_capture_disable(mcpwm_unit_t mcpwm_num, mcpwm_capture_signal_t cap_sig)
Disable capture signal.
Return
• ESP_OK Success
Parameters
• cap_sig: capture pin, which needs to be disabled
esp_err_t mcpwm_capture_enable_channel(mcpwm_unit_t mcpwm_num,
mcpwm_capture_channel_id_t cap_channel, const
mcpwm_capture_config_t *cap_conf)
Enable capture channel.
Return
• ESP_OK Success
Parameters
• cap_channel: capture channel, which needs to be enabled
• cap_conf: capture channel configuration
esp_err_t mcpwm_capture_disable_channel(mcpwm_unit_t mcpwm_num,
mcpwm_capture_channel_id_t cap_channel)
Disable capture channel.
Return
• ESP_OK Success
Parameters
• cap_channel: capture channel, which needs to be disabled

uint32_t mcpwm_capture_signal_get_value(mcpwm_unit_t mcpwm_num,

mcpwm_capture_signal_t cap_sig)
Get capture value.
Return Captured value
Parameters
• cap_sig: capture channel on which value is to be measured
uint32_t mcpwm_capture_signal_get_edge(mcpwm_unit_t mcpwm_num,
mcpwm_capture_signal_t cap_sig)
Get edge of capture signal.
Return Capture signal edge: 1 - positive edge, 2 - negtive edge
Parameters
• cap_sig: capture channel of whose edge is to be determined
esp_err_t mcpwm_sync_enable(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num,
mcpwm_sync_signal_t sync_sig, uint32_t phase_val)
Initialize sync submodule and sets the signal that will cause the timer be loaded with pre-defined value.
Note Count direction is undefined within this API
Return
• ESP_OK Success
Parameters
• sync_sig: set the synchronization input signal
• phase_val: phase value in 1/1000 (for 86.7%, phase_val = 867) which timer moves to on sync
signal
esp_err_t mcpwm_sync_configure(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num, const
mcpwm_sync_config_t *sync_conf)
Initialize sync submodule and sets the signal that will cause the timer be loaded with pre-defined value.
Return
• ESP_OK Success
Parameters
• sync_conf: sync configuration on this timer
esp_err_t mcpwm_sync_disable(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num)
Disable sync submodule on given timer.
Return
• ESP_OK Success
Parameters
esp_err_t mcpwm_set_timer_sync_output(mcpwm_unit_t mcpwm_num, mcpwm_timer_t
timer_num, mcpwm_timer_sync_trigger_t trigger)
Set sync output on given timer Configures what event triggers MCPWM timer to output a sync signal.
Return
• ESP_OK Success
Parameters

• trigger: set the trigger that will cause the timer to generate a software sync signal. Specifically,
MCPWM_SWSYNC_SOURCE_DISABLED will disable the timer from generating sync signal.
esp_err_t mcpwm_timer_trigger_soft_sync(mcpwm_unit_t mcpwm_num, mcpwm_timer_t
timer_num)
Trigger a software sync event and sends it to a specific timer.
Note This software sync event will have the same effect as hw one, except that:
• On esp32s3 the soft sync event can be routed to its output if MCPWM_SWSYNC_SOURCE_SYNCIN
is selected via mcpwm_set_timer_sync_output()
• On esp32 there is no such behavior and soft sync event will only take effect on this timer and can not
be propagated to others.
Return
• ESP_OK Success
Parameters
esp_err_t mcpwm_sync_invert_gpio_synchro(mcpwm_unit_t mcpwm_num, mcpwm_sync_signal_t
sync_sig, bool invert)
Set external GPIO sync input inverter.
Return
• ESP_OK Success
Parameters
• sync_sig: set sync signal of MCPWM, only supports GPIO sync signal
• invert: whether GPIO sync source input is inverted (to get negative edge trigger)
esp_err_t mcpwm_isr_register(mcpwm_unit_t mcpwm_num, void (*fn))void *
, void *arg, int intr_alloc_flags, intr_handle_t *handleRegister MCPWM interrupt handler, the handler is an
ISR. the handler will be attached to the same CPU core that this function is running on.
Return
• ESP_OK Success
Parameters
• fn: interrupt handler function.
• arg: user-supplied argument passed to the handler function.
• intr_alloc_flags: flags used to allocate the interrupt. One or multiple (ORred)
ESP_INTR_FLAG_* values. see esp_intr_alloc.h for more info.
• handle: pointer to return handle. If non-NULL, a handle for the interrupt will be returned here.
Structures
struct mcpwm_pin_config_t
pin number for MCPWM
Public Members
int mcpwm0a_out_num
MCPWM0A out pin
int mcpwm0b_out_num
MCPWM0A out pin
int mcpwm1a_out_num
MCPWM0A out pin

int mcpwm1b_out_num
MCPWM0A out pin
int mcpwm2a_out_num
MCPWM0A out pin
int mcpwm2b_out_num
MCPWM0A out pin
int mcpwm_sync0_in_num
SYNC0 in pin
SYNC1 in pin
SYNC2 in pin
int mcpwm_fault0_in_num
FAULT0 in pin
FAULT1 in pin
FAULT2 in pin
int mcpwm_cap0_in_num
CAP0 in pin
CAP1 in pin
CAP2 in pin
struct cap_event_data_t
event data that will be passed into ISR callback
Public Members
mcpwm_capture_on_edge_t cap_edge
Which signal edge is detected
uint32_t cap_value
Corresponding timestamp when event occurs. Clock rate = APB(usually 80M)
struct mcpwm_config_t
MCPWM config structure.
Public Members
uint32_t frequency
Set frequency of MCPWM in Hz
float cmpr_a
Set % duty cycle for operator a(MCPWMXA), i.e for 62.3% duty cycle, duty_a = 62.3
float cmpr_b
Set % duty cycle for operator b(MCPWMXB), i.e for 48% duty cycle, duty_b = 48.0
mcpwm_duty_type_t duty_mode
Set type of duty cycle
mcpwm_counter_type_t counter_mode
Set type of MCPWM counter

struct mcpwm_carrier_config_t
MCPWM carrier configuration structure.
Public Members
uint8_t carrier_period
Set carrier period = (carrier_period + 1)*800ns, carrier_period should be < 16
uint8_t carrier_duty
Set carrier duty cycle, carrier_duty should be less than 8 (increment every 12.5%)
uint8_t pulse_width_in_os
Set pulse width of first pulse in one shot mode = (carrier period)*(pulse_width_in_os + 1), should be less
then 16
mcpwm_carrier_os_t carrier_os_mode
Enable or disable carrier oneshot mode
mcpwm_carrier_out_ivt_t carrier_ivt_mode
Invert output of carrier
struct mcpwm_capture_config_t
MCPWM config capture structure.
Public Members
mcpwm_capture_on_edge_t cap_edge
Set capture edge
uint32_t cap_prescale
Prescale of capture signal, ranging from 1 to 256
cap_isr_cb_t capture_cb
User defined capture event callback, running under interrupt context
void *user_data
User defined ISR callback function args
struct mcpwm_sync_config_t
MCPWM config sync structure.
Public Members
mcpwm_sync_signal_t sync_sig
Set sync input signal that will cause timer to sync
uint32_t timer_val
Counter value to be set after sync, in 0 ~ 999, unit: 1 / 1000 * peak
mcpwm_timer_direction_t count_direction
Counting direction to be set after sync
Macros
MCPWM_OPR_A
MCPWM_OPR_B
MCPWM_OPR_MAX
MCPWM_SELCT_SYNC0
MCPWM_SELCT_SYNC1
MCPWM_SELCT_SYNC2

MCPWM_NO_CHANGE_IN_MCPWMXA
MCPWM_FORCE_MCPWMXA_LOW
MCPWM_FORCE_MCPWMXA_HIGH
MCPWM_TOG_MCPWMXA
MCPWM_NO_CHANGE_IN_MCPWMXB
MCPWM_FORCE_MCPWMXB_LOW
MCPWM_FORCE_MCPWMXB_HIGH
MCPWM_TOG_MCPWMXB
Type Definitions
typedef mcpwm_generator_t mcpwm_operator_t
typedef mcpwm_output_action_t mcpwm_action_on_pwmxa_t
typedef mcpwm_output_action_t mcpwm_action_on_pwmxb_t
typedef mcpwm_capture_signal_t mcpwm_capture_channel_id_t
MCPWM capture channel ID alias.
typedef bool (*cap_isr_cb_t)(mcpwm_unit_t mcpwm, mcpwm_capture_channel_id_t cap_channel,
const cap_event_data_t *edata, void *user_data)
Type of capture event callback.
Note Since this an ISR callback so do not do anything that may block and call APIs that is designed to be used
within ISR(usually has _ISR postfix)
Return Whether a task switch is needed after the callback function returns, this is usually due to the callback
wakes up some high priority task.
Parameters
• mcpwm: MCPWM unit(0-1)
• cap_channel: capture channel ID
• edata: Capture event data, contains capture edge and capture value, fed by the driver
• user_data: User registered data, passed from mcpwm_capture_config_t
Enumerations
enum mcpwm_io_signals_t
IO signals for the MCPWM.
• 6 MCPWM output pins that generate PWM signals
• 3 MCPWM fault input pins to detect faults like overcurrent, overvoltage, etc.
• 3 MCPWM sync input pins to synchronize MCPWM outputs signals
• 3 MCPWM capture input pins to gather feedback from controlled motors, using e.g. hall sensors
Values:
MCPWM0A = 0
PWM0A output pin
MCPWM0B
PWM0B output pin
MCPWM1A
PWM1A output pin
MCPWM1B
PWM1B output pin
MCPWM2A
PWM2A output pin

MCPWM2B
PWM2B output pin
MCPWM_SYNC_0
SYNC0 input pin
MCPWM_SYNC_1
SYNC1 input pin
MCPWM_SYNC_2
SYNC2 input pin
MCPWM_FAULT_0
FAULT0 input pin
MCPWM_FAULT_1
FAULT1 input pin
MCPWM_FAULT_2
FAULT2 input pin
MCPWM_CAP_0 = 84
CAP0 input pin
MCPWM_CAP_1
CAP1 input pin
MCPWM_CAP_2
CAP2 input pin
enum mcpwm_unit_t
Select MCPWM unit.
Values:
MCPWM_UNIT_0
MCPWM unit0 selected
MCPWM_UNIT_1
MCPWM unit1 selected
MCPWM_UNIT_MAX
Max number of MCPWM units
enum mcpwm_timer_t
Select MCPWM timer.
Values:
MCPWM_TIMER_0
Select MCPWM timer0
MCPWM_TIMER_1
Select MCPWM timer1
MCPWM_TIMER_2
Select MCPWM timer2
MCPWM_TIMER_MAX
Max number of timers in a unit
enum mcpwm_generator_t
Select MCPWM operator.
Values:
MCPWM_GEN_A
Select MCPWMXA, where X is operator number
MCPWM_GEN_B
Select MCPWMXB, where X is operator number

MCPWM_GEN_MAX
Num of generators to each operator of MCPWM
enum mcpwm_carrier_os_t
MCPWM carrier oneshot mode, in this mode the width of the first pulse of carrier can be programmed.
Values:
MCPWM_ONESHOT_MODE_DIS
Enable oneshot mode
MCPWM_ONESHOT_MODE_EN
Disable oneshot mode
enum mcpwm_carrier_out_ivt_t
MCPWM carrier output inversion, high frequency carrier signal active with MCPWM signal is high.
Values:
MCPWM_CARRIER_OUT_IVT_DIS
Enable carrier output inversion
MCPWM_CARRIER_OUT_IVT_EN
Disable carrier output inversion
enum mcpwm_fault_signal_t
MCPWM select fault signal input.
Values:
MCPWM_SELECT_F0
Select F0 as input
MCPWM_SELECT_F1
Select F1 as input
MCPWM_SELECT_F2
Select F2 as input
enum mcpwm_sync_signal_t
MCPWM select sync signal input.
Values:
MCPWM_SELECT_NO_INPUT
No sync input selected
MCPWM_SELECT_TIMER0_SYNC
Select software sync signal from timer0 as input
MCPWM_SELECT_GPIO_SYNC0
Select GPIO SYNC0 as input
enum mcpwm_timer_sync_trigger_t
MCPWM timer sync event trigger.
Values:

MCPWM_SWSYNC_SOURCE_SYNCIN
the input sync signal will be routed to its sync output path
MCPWM_SWSYNC_SOURCE_TEZ
sync signal generated when timer counts to zero
MCPWM_SWSYNC_SOURCE_TEP
sync signal generated when timer counts to peak
MCPWM_SWSYNC_SOURCE_DISABLED
timer does not generate sync signals
enum mcpwm_fault_input_level_t
MCPWM select triggering level of fault signal.
Values:
MCPWM_LOW_LEVEL_TGR
Fault condition occurs when fault input signal goes from high to low
MCPWM_HIGH_LEVEL_TGR
Fault condition occurs when fault input signal goes low to high
enum mcpwm_capture_on_edge_t
MCPWM select capture starts from which edge.
Values:
MCPWM_NEG_EDGE = BIT(0)
Capture the negative edge
MCPWM_POS_EDGE = BIT(1)
Capture the positive edge
MCPWM_BOTH_EDGE = BIT(1) | BIT(0)
Capture both edges
enum mcpwm_intr_t
Interrupt masks for MCPWM capture.
Values:
MCPWM_LL_INTR_CAP0 = BIT(27)
Capture 0 happened.
Capture 1 happened.
Capture 2 happened.
enum mcpwm_counter_type_t
Select type of MCPWM counter.
Values:
MCPWM_FREEZE_COUNTER
Counter freeze
MCPWM_UP_COUNTER
For asymmetric MCPWM
MCPWM_DOWN_COUNTER
For asymmetric MCPWM
MCPWM_UP_DOWN_COUNTER
For symmetric MCPWM, frequency is half of MCPWM frequency set
MCPWM_COUNTER_MAX
Maximum counter mode

enum mcpwm_duty_type_t
Select type of MCPWM duty cycle mode.
Values:
MCPWM_DUTY_MODE_0 = 0
Active high duty, i.e. duty cycle proportional to high time for asymmetric MCPWM
MCPWM_DUTY_MODE_1
Active low duty, i.e. duty cycle proportional to low time for asymmetric MCPWM, out of phase(inverted)
MCPWM
MCPWM_HAL_GENERATOR_MODE_FORCE_LOW
MCPWM_HAL_GENERATOR_MODE_FORCE_HIGH
MCPWM_DUTY_MODE_MAX
Num of duty cycle modes
enum mcpwm_deadtime_type_t
MCPWM deadtime types, used to generate deadtime, RED refers to rising edge delay and FED refers to falling
edge delay.
Values:
MCPWM_DEADTIME_BYPASS = 0
Bypass the deadtime
MCPWM_BYPASS_RED
MCPWMXA Out = MCPWMXA In with no delay, MCPWMXB Out = MCPWMXA In with falling
edge delay
MCPWM_BYPASS_FED
MCPWMXA Out = MCPWMXA In with rising edge delay, MCPWMXB Out = MCPWMXB In with
no delay
MCPWM_ACTIVE_HIGH_MODE
MCPWMXA Out = MCPWMXA In with rising edge delay, MCPWMXB Out = MCPWMXA In with
falling edge delay
MCPWM_ACTIVE_LOW_MODE
MCPWMXA Out = MCPWMXA In with compliment of rising edge delay, MCPWMXB Out = MCP-
WMXA In with compliment of falling edge delay
MCPWM_ACTIVE_HIGH_COMPLIMENT_MODE
MCPWMXA Out = MCPWMXA In with rising edge delay, MCPWMXB = MCPWMXA In with com-
pliment of falling edge delay
MCPWM_ACTIVE_LOW_COMPLIMENT_MODE
MCPWMXA Out = MCPWMXA In with compliment of rising edge delay, MCPWMXB Out = MCP-
WMXA In with falling edge delay
MCPWM_ACTIVE_RED_FED_FROM_PWMXA
MCPWMXA Out = MCPWMXB Out = MCPWMXA In with rising edge delay as well as falling edge
delay
MCPWM_ACTIVE_RED_FED_FROM_PWMXB
MCPWMXA Out = MCPWMXB Out = MCPWMXB In with rising edge delay as well as falling edge
delay
MCPWM_DEADTIME_TYPE_MAX
Maximum number of supported dead time modes
enum mcpwm_output_action_t
MCPWM select action to be taken on the output when event happens.
Values:

MCPWM_ACTION_NO_CHANGE = 0
No change in the output
MCPWM_ACTION_FORCE_LOW
Make output low
MCPWM_ACTION_FORCE_HIGH
Make output high
MCPWM_ACTION_TOGGLE
Make output toggle
enum mcpwm_capture_signal_t
MCPWM select capture signal input.
Values:
MCPWM_SELECT_CAP0
Select CAP0 as input
MCPWM_SELECT_CAP1
MCPWM_SELECT_CAP2
2.3.10 Pulse Counter (PCNT)
Introduction
The PCNT (Pulse Counter) module is designed to count the number of rising and/or falling edges of an input signal.
Each pulse counter unit has a 16-bit signed counter register and two channels that can be configured to either increment
or decrement the counter. Each channel has a signal input that accepts signal edges to be detected, as well as a control
input that can be used to enable or disable the signal input. The inputs have optional filters that can be used to discard
unwanted glitches in the signal.
Description of functionality of this API has been broken down into four sections:
• Configuration - describes counter s configuration parameters and how to setup the counter.
• Operating the Counter - provides information on control functions to pause, measure and clear the counter.
• Filtering Pulses - describes options to filtering pulses and the counter control signals.
• Using Interrupts - presents how to trigger interrupts on specific states of the counter.
Configuration
The PCNT module has 8 independent counting units numbered from 0 to 7. In the API they are referred
to using pcnt_unit_t. Each unit has two independent channels numbered as 0 and 1 and specified with
pcnt_channel_t.
The configuration is provided separately per unit s channel using pcnt_config_t and covers:
• The unit and the channel number this configuration refers to.
• GPIO numbers of the pulse input and the pulse gate input.
• Two pairs of parameters: pcnt_ctrl_mode_t and pcnt_count_mode_t to define how the counter
reacts depending on the the status of control signal and how counting is done positive / negative edge of the
pulses.
• Two limit values (minimum / maximum) that are used to establish watchpoints and trigger interrupts when the
pulse count is meeting particular limit.

Setting up of particular channel is then done by calling a function pcnt_unit_config() with above
pcnt_config_t as the input parameter.
To disable the pulse or the control input pin in configuration, provide PCNT_PIN_NOT_USED instead of the GPIO
number.
Operating the Counter
After doing setup with pcnt_unit_config(), the counter immediately starts to operate. The accumulated pulse
count can be checked by calling pcnt_get_counter_value().
There are couple of functions that allow to control the counter s operation: pcnt_counter_pause(),
pcnt_counter_resume() and pcnt_counter_clear()
It is also possible to dynamically change the previously set up counter modes with pcnt_unit_config() by
calling pcnt_set_mode().
If desired, the pulse input pin and the control input pin may be changed on the fly using pcnt_set_pin().
To disable particular input provide as a function parameter PCNT_PIN_NOT_USED instead of the GPIO number.
Note: For the counter not to miss any pulses, the pulse duration should be longer than one APB_CLK cycle (12.5
ns). The pulses are sampled on the edges of the APB_CLK clock and may be missed, if fall between the edges. This
applies to counter operation with or without a filer.
Filtering Pulses
The PCNT unit features filters on each of the pulse and control inputs, adding the option to ignore short glitches in
the signals.
The length of ignored pulses is provided in APB_CLK clock cycles by calling pcnt_set_filter_value().
The current filter setting may be checked with pcnt_get_filter_value(). The APB_CLK clock is running
at 80 MHz.
The filter is put into operation / suspended by calling pcnt_filter_enable() /
pcnt_filter_disable().
Using Interrupts
There are five counter state watch events, defined in pcnt_evt_type_t, that are able to trigger an interrupt. The
event happens on the pulse counter reaching specific values:
• Minimum or maximum count values: counter_l_lim or counter_h_lim provided in
pcnt_config_t as discussed in Configuration
• Threshold 0 or Threshold 1 values set using function pcnt_set_event_value().
• Pulse count = 0
To register, enable or disable an interrupt to service the above events, call pcnt_isr_register(),
pcnt_intr_enable(). and pcnt_intr_disable(). To enable or disable events on reaching threshold
values, you will also need to call functions pcnt_event_enable() and pcnt_event_disable().
In order to check what are the threshold values currently set, use function pcnt_get_event_value().
Application Example
• Pulse counter with control signal and event interrupt example: peripherals/pcnt/pulse_count_event.
• Parse the signal generated from rotary encoder: peripherals/pcnt/rotary_encoder.

API Reference
Header File
• components/driver/include/driver/pcnt.h
Functions
esp_err_t pcnt_unit_config(const pcnt_config_t *pcnt_config)
Configure Pulse Counter unit.
Note This function will disable three events: PCNT_EVT_L_LIM, PCNT_EVT_H_LIM,
PCNT_EVT_ZERO.
Return
• ESP_OK Success
• ESP_ERR_INVALID_STATE pcnt driver already initialized
Parameters
• pcnt_config: Pointer of Pulse Counter unit configure parameter
esp_err_t pcnt_get_counter_value(pcnt_unit_t pcnt_unit, int16_t *count)
Get pulse counter value.
Return
• ESP_OK Success
• ESP_ERR_INVALID_STATE pcnt driver has not been initialized
Parameters
• pcnt_unit: Pulse Counter unit number
• count: Pointer to accept counter value
esp_err_t pcnt_counter_pause(pcnt_unit_t pcnt_unit)
Pause PCNT counter of PCNT unit.
Return
• ESP_OK Success
Parameters
• pcnt_unit: PCNT unit number
esp_err_t pcnt_counter_resume(pcnt_unit_t pcnt_unit)
Resume counting for PCNT counter.
Return
• ESP_OK Success
Parameters
• pcnt_unit: PCNT unit number, select from pcnt_unit_t
esp_err_t pcnt_counter_clear(pcnt_unit_t pcnt_unit)
Clear and reset PCNT counter value to zero.
Return
• ESP_OK Success
Parameters
• pcnt_unit: PCNT unit number, select from pcnt_unit_t
esp_err_t pcnt_intr_enable(pcnt_unit_t pcnt_unit)
Enable PCNT interrupt for PCNT unit.

Note Each Pulse counter unit has five watch point events that share the same interrupt. Configure events with
pcnt_event_enable() and pcnt_event_disable()
Return
• ESP_OK Success
Parameters
esp_err_t pcnt_intr_disable(pcnt_unit_t pcnt_unit)
Disable PCNT interrupt for PCNT unit.
Return
• ESP_OK Success
Parameters
esp_err_t pcnt_event_enable(pcnt_unit_t unit, pcnt_evt_type_t evt_type)
Enable PCNT event of PCNT unit.
Return
• ESP_OK Success
Parameters
• unit: PCNT unit number
• evt_type: Watch point event type. All enabled events share the same interrupt (one interrupt per
pulse counter unit).
esp_err_t pcnt_event_disable(pcnt_unit_t unit, pcnt_evt_type_t evt_type)
Disable PCNT event of PCNT unit.
Return
• ESP_OK Success
Parameters
esp_err_t pcnt_set_event_value(pcnt_unit_t unit, pcnt_evt_type_t evt_type, int16_t value)
Set PCNT event value of PCNT unit.
Return
• ESP_OK Success
Parameters
• value: Counter value for PCNT event
esp_err_t pcnt_get_event_value(pcnt_unit_t unit, pcnt_evt_type_t evt_type, int16_t *value)
Get PCNT event value of PCNT unit.
Return
• ESP_OK Success

Parameters
• value: Pointer to accept counter value for PCNT event
esp_err_t pcnt_get_event_status(pcnt_unit_t unit, uint32_t *status)
Get PCNT event status of PCNT unit.
Return
• ESP_OK Success
Parameters
• status: Pointer to accept event status word
esp_err_t pcnt_isr_unregister(pcnt_isr_handle_t handle)
Unregister PCNT interrupt handler (registered by pcnt_isr_register), the handler is an ISR. The handler will
be attached to the same CPU core that this function is running on. If the interrupt service is registered by
pcnt_isr_service_install, please call pcnt_isr_service_uninstall instead.
Return
• ESP_OK Success
• ESP_ERR_NOT_FOUND Can not find the interrupt that matches the flags.
Parameters
• handle: handle to unregister the ISR service.
esp_err_t pcnt_isr_register(void (*fn))void *
, void *arg, int intr_alloc_flags, pcnt_isr_handle_t *handleRegister PCNT interrupt handler, the handler is an
ISR. The handler will be attached to the same CPU core that this function is running on. Please do not use
pcnt_isr_service_install if this function was called.
Return
• ESP_OK Success
• ESP_ERR_NOT_FOUND Can not find the interrupt that matches the flags.
Parameters
Calling pcnt_isr_unregister to unregister this ISR service if needed, but only if the handle is not
NULL.
esp_err_t pcnt_set_pin(pcnt_unit_t unit, pcnt_channel_t channel, int pulse_io, int ctrl_io)
Configure PCNT pulse signal input pin and control input pin.
Note Set the signal input to PCNT_PIN_NOT_USED if unused.
Return
• ESP_OK Success
Parameters
• channel: PCNT channel number
• pulse_io: Pulse signal input GPIO
• ctrl_io: Control signal input GPIO
esp_err_t pcnt_filter_enable(pcnt_unit_t unit)
Enable PCNT input filter.

Return
• ESP_OK Success
Parameters
esp_err_t pcnt_filter_disable(pcnt_unit_t unit)
Disable PCNT input filter.
Return
• ESP_OK Success
Parameters
esp_err_t pcnt_set_filter_value(pcnt_unit_t unit, uint16_t filter_val)
Set PCNT filter value.
Note filter_val is a 10-bit value, so the maximum filter_val should be limited to 1023.
Return
• ESP_OK Success
Parameters
• filter_val: PCNT signal filter value, counter in APB_CLK cycles. Any pulses lasting shorter
than this will be ignored when the filter is enabled.
esp_err_t pcnt_get_filter_value(pcnt_unit_t unit, uint16_t *filter_val)
Get PCNT filter value.
Return
• ESP_OK Success
Parameters
• filter_val: Pointer to accept PCNT filter value.
esp_err_t pcnt_set_mode(pcnt_unit_t unit, pcnt_channel_t channel, pcnt_count_mode_t
pos_mode, pcnt_count_mode_t neg_mode, pcnt_ctrl_mode_t hctrl_mode,
pcnt_ctrl_mode_t lctrl_mode)
Set PCNT counter mode.
Return
• ESP_OK Success
Parameters
• channel: PCNT channel number
• pos_mode: Counter mode when detecting positive edge
• neg_mode: Counter mode when detecting negative edge
• hctrl_mode: Counter mode when control signal is high level
• lctrl_mode: Counter mode when control signal is low level
esp_err_t pcnt_isr_handler_add(pcnt_unit_t unit, void (*isr_handler))void *
, void *argsAdd ISR handler for specified unit.
Call this function after using pcnt_isr_service_install() to install the PCNT driver s ISR handler service.

The ISR handlers do not need to be declared with IRAM_ATTR, unless you pass the
ESP_INTR_FLAG_IRAM flag when allocating the ISR in pcnt_isr_service_install().
This ISR handler will be called from an ISR. So there is a stack size limit (configurable as ISR stack size
in menuconfig). This limit is smaller compared to a global PCNT interrupt handler due to the additional level
of indirection.
Return
• ESP_OK Success
Parameters
• isr_handler: Interrupt handler function.
• args: Parameter for handler function
esp_err_t pcnt_isr_service_install(int intr_alloc_flags)
Install PCNT ISR service.
Note We can manage different interrupt service for each unit. This function will use the default ISR handle
service, Calling pcnt_isr_service_uninstall to uninstall the default service if needed. Please do not use
pcnt_isr_register if this function was called.
Return
• ESP_OK Success
• ESP_ERR_NO_MEM No memory to install this service
• ESP_ERR_INVALID_STATE ISR service already installed
Parameters
void pcnt_isr_service_uninstall(void)
Uninstall PCNT ISR service, freeing related resources.
esp_err_t pcnt_isr_handler_remove(pcnt_unit_t unit)
Delete ISR handler for specified unit.
Return
• ESP_OK Success
Parameters
Structures
struct pcnt_config_t
Pulse Counter configuration for a single channel.
Public Members
int pulse_gpio_num
Pulse input GPIO number, if you want to use GPIO16, enter pulse_gpio_num = 16, a negative value will
be ignored
int ctrl_gpio_num
Control signal input GPIO number, a negative value will be ignored
pcnt_ctrl_mode_t lctrl_mode
PCNT low control mode
pcnt_ctrl_mode_t hctrl_mode
PCNT high control mode

pcnt_count_mode_t pos_mode
PCNT positive edge count mode
pcnt_count_mode_t neg_mode
PCNT negative edge count mode
int16_t counter_h_lim
Maximum counter value
int16_t counter_l_lim
Minimum counter value
pcnt_unit_t unit
PCNT unit number
pcnt_channel_t channel
the PCNT channel
Macros
PCNT_PIN_NOT_USED
When selected for a pin, this pin will not be used
PCNT_MODE_KEEP
Control mode: won t change counter mode
PCNT_MODE_REVERSE
Control mode: invert counter mode(increase -> decrease, decrease -> increase)
PCNT_MODE_DISABLE
Control mode: Inhibit counter(counter value will not change in this condition)
PCNT_MODE_MAX
PCNT_COUNT_DIS
Counter mode: Inhibit counter(counter value will not change in this condition)
PCNT_COUNT_INC
Counter mode: Increase counter value
PCNT_COUNT_DEC
Counter mode: Decrease counter value
PCNT_COUNT_MAX
Type Definitions
typedef intr_handle_t pcnt_isr_handle_t
typedef pcnt_channel_level_action_t pcnt_ctrl_mode_t
Selection of available modes that determine the counter s action depending on the state of the control signal
s input GPIO.
Note Configuration covers two actions, one for high, and one for low level on the control input
typedef pcnt_channel_edge_action_t pcnt_count_mode_t
Selection of available modes that determine the counter s action on the edge of the pulse signal s input GPIO.
Note Configuration covers two actions, one for positive, and one for negative edge on the pulse input
Enumerations
enum pcnt_port_t
PCNT port number, the max port number is (PCNT_PORT_MAX - 1).
Values:
PCNT_PORT_0
PCNT port 0

PCNT_PORT_MAX
PCNT port max
enum pcnt_unit_t
Selection of all available PCNT units.
Values:
PCNT_UNIT_0
PCNT unit 0
PCNT_UNIT_1
PCNT unit 1
PCNT_UNIT_2
PCNT unit 2
PCNT_UNIT_3
PCNT unit 3
PCNT_UNIT_4
PCNT unit 4
PCNT_UNIT_5
PCNT unit 5
PCNT_UNIT_6
PCNT unit 6
PCNT_UNIT_7
PCNT unit 7
PCNT_UNIT_MAX
enum pcnt_channel_t
Selection of channels available for a single PCNT unit.
Values:
PCNT_CHANNEL_0
PCNT channel 0
PCNT_CHANNEL_1
PCNT channel 1
PCNT_CHANNEL_MAX
enum pcnt_evt_type_t
Selection of counter s events the may trigger an interrupt.
Values:
PCNT_EVT_THRES_1 = 1 << 2
PCNT watch point event: threshold1 value event
PCNT_EVT_THRES_0 = 1 << 3
PCNT watch point event: threshold0 value event
PCNT_EVT_L_LIM = 1 << 4
PCNT watch point event: Minimum counter value
PCNT_EVT_H_LIM = 1 << 5
PCNT watch point event: Maximum counter value
PCNT_EVT_ZERO = 1 << 6
PCNT watch point event: counter value zero event
PCNT_EVT_MAX

Header File
• components/hal/include/hal/pcnt_types.h
Enumerations
enum pcnt_channel_level_action_t
PCNT channel action on control level.
Values:
PCNT_CHANNEL_LEVEL_ACTION_KEEP
Keep current count mode
PCNT_CHANNEL_LEVEL_ACTION_INVERSE
Invert current count mode (increase -> decrease, decrease -> increase)
PCNT_CHANNEL_LEVEL_ACTION_HOLD
Hold current count value
enum pcnt_channel_edge_action_t
PCNT channel action on signal edge.
Values:
PCNT_CHANNEL_EDGE_ACTION_HOLD
Hold current count value
PCNT_CHANNEL_EDGE_ACTION_INCREASE
Increase count value
PCNT_CHANNEL_EDGE_ACTION_DECREASE
Decrease count value
enum pcnt_unit_count_sign_t
PCNT unit counter value s sign.
Values:
PCNT_UNIT_COUNT_SIGN_ZERO_POS
positive value to zero
PCNT_UNIT_COUNT_SIGN_ZERO_NEG
negative value to zero
PCNT_UNIT_COUNT_SIGN_NEG
counter value negative
PCNT_UNIT_COUNT_SIGN_POS
counter value positive
2.3.11 Remote Control (RMT)
The RMT (Remote Control) module driver can be used to send and receive infrared remote control signals. Due to
flexibility of RMT module, the driver can also be used to generate or receive many other types of signals.
The signal, which consists of a series of pulses, is generated by RMT s transmitter based on a list of values. The
values define the pulse duration and a binary level, see below. The transmitter can also provide a carrier and modulate
it with provided pulses.
The reverse operation is performed by the receiver, where a series of pulses is decoded into a list of values containing
the pulse duration and binary level. A filter may be applied to remove high frequency noise from the input signal.
There couple of typical steps to setup and operate the RMT and they are discussed in the following sections:
1. Configure Driver
2. Transmit Data or Receive Data
3. Change Operation Parameters

Fig. 16: RMT Transmitter Overview
Fig. 17: RMT Receiver Overview

4. Use Interrupts
The RMT has eight channels numbered from zero to seven. Each channel is able to independently transmit or receive
data. They are referred to using indexes defined in structure rmt_channel_t.
Configure Driver
There are several parameters that define how particular channel operates. Most of these parameters are configured
by setting specific members of rmt_config_t structure. Some of the parameters are common to both transmit
or receive mode, and some are mode specific. They are all discussed below.
Common Parameters
• The channel to be configured, select one from the rmt_channel_t enumerator.
• The RMT operation mode - whether this channel is used to transmit or receive data, selected by setting a
rmt_mode members to one of the values from rmt_mode_t.
• What is the pin number to transmit or receive RMT signals, selected by setting gpio_num.
• How many memory blocks will be used by the channel, set with mem_block_num.
• Extra miscellaneous parameters for the channel can be set in the flags.
– When RMT_CHANNEL_FLAGS_AWARE_DFS is set, RMT channel will take REF_TICK or
XTAL as source clock. The benefit is, RMT channel can continue work even when APB clock is chang-
ing. See power_management for more information.
– When RMT_CHANNEL_FLAGS_INVERT_SIG is set, the driver will invert the RMT signal sending
to or receiving from the channel. It just works like an external inverter connected to the GPIO of certain
RMT channel.
• A clock divider, that will determine the range of pulse length generated by the RMT transmitter or discrim-
inated by the receiver. Selected by setting clk_div to a value within [1 .. 255] range. The RMT source clock
is typically APB CLK, 80Mhz by default. But when RMT_CHANNEL_FLAGS_AWARE_DFS is set in
flags, RMT source clock is changed to REF_TICK or XTAL.
Note: The period of a square wave after the clock divider is called a tick . The length of the pulses generated
by the RMT transmitter or discriminated by the receiver is configured in number of ticks .
There are also couple of specific parameters that should be set up depending if selected channel is configured in
Transmit Mode or Receive Mode:
Transmit Mode When configuring channel in transmit mode, set tx_config and the following members of
rmt_tx_config_t:
• Transmit the currently configured data items in a loop - loop_en
• Enable the RMT carrier signal - carrier_en
• Frequency of the carrier in Hz - carrier_freq_hz
• Duty cycle of the carrier signal in percent (%) - carrier_duty_percent
• Level of the RMT output, when the carrier is applied - carrier_level
• Enable the RMT output if idle - idle_output_en
• Set the signal level on the RMT output if idle - idle_level
Receive Mode In receive mode, set rx_config and the following members of rmt_rx_config_t:
• Enable a filter on the input of the RMT receiver - filter_en
• A threshold of the filter, set in the number of ticks - filter_ticks_thresh. Pulses shorter than this setting will
be filtered out. Note, that the range of entered tick values is [0..255].
• A pulse length threshold that will turn the RMT receiver idle, set in number of ticks - idle_threshold. The
receiver will ignore pulses longer than this setting.

Finalize Configuration Once the rmt_config_t structure is populated with parameters, it should be then
invoked with rmt_config() to make the configuration effective.
The last configuration step is installation of the driver in memory by calling rmt_driver_install(). If
rx_buf_size parameter of this function is > 0, then a ring buffer for incoming data will be allocated. A de-
fault ISR handler will be installed, see a note in Use Interrupts.
Now, depending on how the channel is configured, we are ready to either Transmit Data or Receive Data. This is
described in next two sections.
Transmit Data
Before being able to transmit some RMT pulses, we need to define the pulse pattern. The minimum pattern recognized
by the RMT controller, later called an item , is provided in a structure rmt_item32_t. Each item consists of
two pairs of two values. The first value in a pair describes the signal duration in ticks and is 15 bits long, the second
provides the signal level (high or low) and is contained in a single bit. A block of couple of items and the structure
of an item is presented below.
Fig. 18: Structure of RMT items (L - signal level)
For a simple example how to define a block of items see peripherals/rmt/morse_code.

The items are provided to the RMT controller by calling function rmt_write_items(). This function also
automatically triggers start of transmission. It may be called to wait for transmission completion or exit just after
transmission start. In such case you can wait for the transmission end by calling rmt_wait_tx_done(). This
function does not limit the number of data items to transmit. It is using an interrupt to successively copy the new data
chunks to RMT s internal memory as previously provided data are sent out.
Another way to provide data for transmission is by calling rmt_fill_tx_items(). In this case transmission
is not started automatically. To control the transmission process use rmt_tx_start() and rmt_tx_stop().
The number of items to sent is restricted by the size of memory blocks allocated in the RMT controller s internal
memory, see rmt_set_mem_block_num().
Receive Data
Warning: RMT RX channel can t receive packet whose items are larger than its memory block size. If you
set the memory block number to 1, then this RX channel can t receive packet with more than 64 items. This is
a hardware limitation.

Before starting the receiver we need some storage for incoming items. The RMT controller has 512 x 32-bits of
internal RAM shared between all eight channels.
In typical scenarios it is not enough as an ultimate storage for all incoming (and outgoing) items. Therefore this
API supports retrieval of incoming items on the fly to save them in a ring buffer of a size defined by the user. The
size is provided when calling rmt_driver_install() discussed above. To get a handle to this buffer call
rmt_get_ringbuf_handle().
With the above steps complete we can start the receiver by calling rmt_rx_start() and then move to checking
what s inside the buffer. To do so, you can use common FreeRTOS functions that interact with the ring buffer.
Please see an example how to do it in peripherals/rmt/ir_protocols.
To stop the receiver, call rmt_rx_stop().
Change Operation Parameters
Previously described function rmt_config() provides a convenient way to set several configuration parameters
in one shot. This is usually done on application start. Then, when the application is running, the API provides an
alternate way to update individual parameters by calling dedicated functions. Each function refers to the specific
RMT channel provided as the first input parameter. Most of the functions have _get_ counterpart to read back the
currently configured value.
Parameters Common to Transmit and Receive Mode

• Selection of a GPIO pin number on the input or output of the RMT - rmt_set_gpio()
• Number of memory blocks allocated for the incoming or outgoing data - rmt_set_mem_pd()
• Setting of the clock divider - rmt_set_clk_div()
• Selection of the clock source, note that currently one clock source is supported, the APB clock which is 80Mhz
- rmt_set_source_clk()
Transmit Mode Parameters

• Enable or disable the loop back mode for the transmitter - rmt_set_tx_loop_mode()
• Binary level on the output to apply the carrier - rmt_set_tx_carrier(), selected from
rmt_carrier_level_t
• Determines the binary level on the output when transmitter is idle - rmt_set_idle_level(), selected
from rmt_idle_level_t
Receive Mode Parameters

• The filter setting - rmt_set_rx_filter()
• The receiver threshold setting - rmt_set_rx_idle_thresh()
• Whether the transmitter or receiver is entitled to access RMT s memory - rmt_set_memory_owner(),
selection is from rmt_mem_owner_t.
Use Interrupts
Registering of an interrupt handler for the RMT controller is done be calling rmt_isr_register().
Note: When calling rmt_driver_install() to use the system RMT driver, a default ISR is being installed.
In such a case you cannot register a generic ISR handler with rmt_isr_register().
The RMT controller triggers interrupts on four specific events describes below. To enable interrupts on these events,
the following functions are provided:
• The RMT receiver has finished receiving a signal - rmt_set_rx_intr_en()
• The RMT transmitter has finished transmitting the signal - rmt_set_tx_intr_en()

• The number of events the transmitter has sent matches a threshold value rmt_set_tx_thr_intr_en()
• Ownership to the RMT memory block has been violated - rmt_set_err_intr_en()
Setting or clearing an interrupt enable mask for specific channels and events may be also done by calling
rmt_set_intr_enable_mask() or rmt_clr_intr_enable_mask().
When servicing an interrupt within an ISR, the interrupt need to explicitly cleared. To do so, set spe-
cific bits described as RMT.int_clr.val.chN_event_name and defined as a volatile struct in
soc/esp32/include/soc/rmt_struct.h, where N is the RMT channel number [0, n] and the event_name is one of
four events described above.
If you do not need an ISR anymore, you can deregister it by calling a function rmt_isr_deregister().
Warning: It s not recommended for users to register an interrupt handler in their applications. RMT driver is
highly dependent on interrupt, especially when doing transaction in a ping-pong way, so the driver itself has regis-
tered a default handler called rmt_driver_isr_default. Instead, if what you want is to get a notification
when transaction is done, go ahead with rmt_register_tx_end_callback().
Uninstall Driver
If the RMT driver has been installed with rmt_driver_install() for some specific period of time and then
not required, the driver may be removed to free allocated resources by calling rmt_driver_uninstall().
Application Examples
• Using RMT to send morse code: peripherals/rmt/morse_code.

• Using RMT to drive RGB LED strip: peripherals/rmt/led_strip.
• NEC remote control TX and RX example: peripherals/rmt/ir_protocols.
• Musical buzzer example: peripherals/rmt/musical_buzzer.
API Reference
Header File
• components/driver/include/driver/rmt.h
Functions
esp_err_t rmt_set_clk_div(rmt_channel_t channel, uint8_t div_cnt)
Set RMT clock divider, channel clock is divided from source clock.
Return
• ESP_OK Success
Parameters
• channel: RMT channel
• div_cnt: RMT counter clock divider
esp_err_t rmt_get_clk_div(rmt_channel_t channel, uint8_t *div_cnt)
Get RMT clock divider, channel clock is divided from source clock.
Return
• ESP_OK Success
Parameters
• div_cnt: pointer to accept RMT counter divider

esp_err_t rmt_set_rx_idle_thresh(rmt_channel_t channel, uint16_t thresh)

Set RMT RX idle threshold value.
In receive mode, when no edge is detected on the input signal for longer than idle_thres channel clock cycles,
the receive process is finished.
Return
• ESP_OK Success
Parameters
• thresh: RMT RX idle threshold
esp_err_t rmt_get_rx_idle_thresh(rmt_channel_t channel, uint16_t *thresh)
Get RMT idle threshold value.
In receive mode, when no edge is detected on the input signal for longer than idle_thres channel clock cycles,
the receive process is finished.
Return
• ESP_OK Success
Parameters
• thresh: pointer to accept RMT RX idle threshold value
esp_err_t rmt_set_mem_block_num(rmt_channel_t channel, uint8_t rmt_mem_num)
Set RMT memory block number for RMT channel.
This function is used to configure the amount of memory blocks allocated to channel n The 8 channels share
a 512x32-bit RAM block which can be read and written by the processor cores over the APB bus, as well as
read by the transmitters and written by the receivers.
The RAM address range for channel n is start_addr_CHn to end_addr_CHn, which are defined by: Memory
block start address is RMT_CHANNEL_MEM(n) (in soc/rmt_reg.h), that is, start_addr_chn = RMT base
address + 0x800 + 64 ∗ 4 ∗ n, and end_addr_chn = RMT base address + 0x800 + 64 ∗ 4 ∗ n + 64 ∗ 4 ∗
RMT_MEM_SIZE_CHn mod 512 ∗ 4
Note If memory block number of one channel is set to a value greater than 1, this channel will occupy the
memory block of the next channel. Channel 0 can use at most 8 blocks of memory, accordingly channel
7 can only use one memory block.
Return
• ESP_OK Success
Parameters
• rmt_mem_num: RMT RX memory block number, one block has 64 * 32 bits.
esp_err_t rmt_get_mem_block_num(rmt_channel_t channel, uint8_t *rmt_mem_num)
Get RMT memory block number.
Return
• ESP_OK Success
Parameters
• rmt_mem_num: Pointer to accept RMT RX memory block number
esp_err_t rmt_set_tx_carrier(rmt_channel_t channel, bool carrier_en, uint16_t high_level, uint16_t
low_level, rmt_carrier_level_t carrier_level)
Configure RMT carrier for TX signal.
Set different values for carrier_high and carrier_low to set different frequency of carrier. The unit of car-
rier_high/low is the source clock tick, not the divided channel counter clock.

Return
• ESP_OK Success
Parameters
• carrier_en: Whether to enable output carrier.
• high_level: High level duration of carrier
• low_level: Low level duration of carrier.
• carrier_level: Configure the way carrier wave is modulated for channel.
– 1 b1:transmit on low output level
– 1 b0:transmit on high output level
esp_err_t rmt_set_mem_pd(rmt_channel_t channel, bool pd_en)
Set RMT memory in low power mode.
Reduce power consumed by memory. 1:memory is in low power state.
Return
• ESP_OK Success
Parameters
• pd_en: RMT memory low power enable.
esp_err_t rmt_get_mem_pd(rmt_channel_t channel, bool *pd_en)
Get RMT memory low power mode.
Return
• ESP_OK Success
Parameters
• pd_en: Pointer to accept RMT memory low power mode.
esp_err_t rmt_tx_start(rmt_channel_t channel, bool tx_idx_rst)
Set RMT start sending data from memory.
Return
• ESP_OK Success
Parameters
• tx_idx_rst: Set true to reset memory index for TX. Otherwise, transmitter will continue sending
from the last index in memory.
esp_err_t rmt_tx_stop(rmt_channel_t channel)
Set RMT stop sending.
Return
• ESP_OK Success
Parameters
esp_err_t rmt_rx_start(rmt_channel_t channel, bool rx_idx_rst)
Set RMT start receiving data.
Return
• ESP_OK Success
Parameters
• rx_idx_rst: Set true to reset memory index for receiver. Otherwise, receiver will continue
receiving data to the last index in memory.

esp_err_t rmt_rx_stop(rmt_channel_t channel)

Set RMT stop receiving data.
Return
• ESP_OK Success
Parameters
esp_err_t rmt_tx_memory_reset(rmt_channel_t channel)
Reset RMT TX memory.
Return
• ESP_OK Success
Parameters
esp_err_t rmt_rx_memory_reset(rmt_channel_t channel)
Reset RMT RX memory.
Return
• ESP_OK Success
Parameters
esp_err_t rmt_set_memory_owner(rmt_channel_t channel, rmt_mem_owner_t owner)
Set RMT memory owner.
Note Setting memroy is only valid for RX channel.
Return
• ESP_OK Success
Parameters
• owner: To set when the transmitter or receiver can process the memory of channel.
esp_err_t rmt_get_memory_owner(rmt_channel_t channel, rmt_mem_owner_t *owner)
Get RMT memory owner.
Return
• ESP_OK Success
Parameters
• owner: Pointer to get memory owner.
esp_err_t rmt_set_tx_loop_mode(rmt_channel_t channel, bool loop_en)
Set RMT tx loop mode.
Return
• ESP_OK Success
Parameters
• loop_en: Enable RMT transmitter loop sending mode. If set true, transmitter will continue send-
ing from the first data to the last data in channel over and over again in a loop.
esp_err_t rmt_get_tx_loop_mode(rmt_channel_t channel, bool *loop_en)
Get RMT tx loop mode.
Return
• ESP_OK Success

Parameters
• loop_en: Pointer to accept RMT transmitter loop sending mode.
esp_err_t rmt_set_rx_filter(rmt_channel_t channel, bool rx_filter_en, uint8_t thresh)
Set RMT RX filter.
In receive mode, channel will ignore input pulse when the pulse width is smaller than threshold. Counted in
source clock, not divided counter clock.
Return
• ESP_OK Success
Parameters
• rx_filter_en: To enable RMT receiver filter.
• thresh: Threshold of pulse width for receiver.
esp_err_t rmt_set_source_clk(rmt_channel_t channel, rmt_source_clk_t base_clk)
Set RMT source clock.
RMT module has two clock sources:
1. APB clock which is 80Mhz
2. REF tick clock, which would be 1Mhz (not supported in this version).
Return
• ESP_OK Success
Parameters
• base_clk: To choose source clock for RMT module.
esp_err_t rmt_get_source_clk(rmt_channel_t channel, rmt_source_clk_t *src_clk)
Get RMT source clock.
RMT module has two clock sources:
1. APB clock which is 80Mhz
2. REF tick clock, which would be 1Mhz (not supported in this version).
Return
• ESP_OK Success
Parameters
• src_clk: Pointer to accept source clock for RMT module.
esp_err_t rmt_set_idle_level(rmt_channel_t channel, bool idle_out_en, rmt_idle_level_t level)
Set RMT idle output level for transmitter.
Return
• ESP_OK Success
Parameters
• idle_out_en: To enable idle level output.
• level: To set the output signal s level for channel in idle state.
esp_err_t rmt_get_idle_level(rmt_channel_t channel, bool *idle_out_en, rmt_idle_level_t *level)
Get RMT idle output level for transmitter.
Return
• ESP_OK Success
Parameters


• idle_out_en: Pointer to accept value of enable idle.
• level: Pointer to accept value of output signal s level in idle state for specified channel.
esp_err_t rmt_get_status(rmt_channel_t channel, uint32_t *status)
Get RMT status.
Return
• ESP_OK Success
Parameters
• status: Pointer to accept channel status. Please refer to RMT_CHnSTATUS_REG(n=0~7) in
rmt_reg.h for more details of each field.
esp_err_t rmt_set_rx_intr_en(rmt_channel_t channel, bool en)
Set RMT RX interrupt enable.
Return
• ESP_OK Success
Parameters
• en: enable or disable RX interrupt.
esp_err_t rmt_set_err_intr_en(rmt_channel_t channel, bool en)
Set RMT RX error interrupt enable.
Return
• ESP_OK Success
Parameters
• en: enable or disable RX err interrupt.
esp_err_t rmt_set_tx_intr_en(rmt_channel_t channel, bool en)
Set RMT TX interrupt enable.
Return
• ESP_OK Success
Parameters
• en: enable or disable TX interrupt.
esp_err_t rmt_set_tx_thr_intr_en(rmt_channel_t channel, bool en, uint16_t evt_thresh)
Set RMT TX threshold event interrupt enable.
An interrupt will be triggered when the number of transmitted items reaches the threshold value
Return
• ESP_OK Success
Parameters
• en: enable or disable TX event interrupt.
• evt_thresh: RMT event interrupt threshold value
esp_err_t rmt_set_gpio(rmt_channel_t channel, rmt_mode_t mode, gpio_num_t gpio_num, bool in-
vert_signal)
Configure the GPIO used by RMT channel.
Return
• ESP_ERR_INVALID_ARG Configure RMT GPIO failed because of wrong parameter
• ESP_OK Configure RMT GPIO successfully

Parameters
• mode: RMT mode, either RMT_MODE_TX or RMT_MODE_RX
• gpio_num: GPIO number, which is connected with certain RMT signal
• invert_signal: Invert RMT signal physically by GPIO matrix
esp_err_t rmt_config(const rmt_config_t *rmt_param)
Configure RMT parameters.
Return
• ESP_OK Success
Parameters
• rmt_param: RMT parameter struct
esp_err_t rmt_isr_register(void (*fn))void *
, void *arg, int intr_alloc_flags, rmt_isr_handle_t *handleRegister RMT interrupt handler, the handler is an
ISR.
The handler will be attached to the same CPU core that this function is running on.
Note If you already called rmt_driver_install to use system RMT driver, please do not register ISR handler
again.
Return
• ESP_OK Success
• ESP_FAIL System driver installed, can not register ISR handler for RMT
Parameters
• arg: Parameter for the handler function
• handle: If non-zero, a handle to later clean up the ISR gets stored here.
esp_err_t rmt_isr_deregister(rmt_isr_handle_t handle)
Deregister previously registered RMT interrupt handler.
Return
• ESP_OK Success
• ESP_ERR_INVALID_ARG Handle invalid
Parameters
• handle: Handle obtained from rmt_isr_register
esp_err_t rmt_fill_tx_items(rmt_channel_t channel, const rmt_item32_t *item, uint16_t
item_num, uint16_t mem_offset)
Fill memory data of channel with given RMT items.
Return
• ESP_OK Success
Parameters
• item: Pointer of items.
• item_num: RMT sending items number.
• mem_offset: Index offset of memory.
esp_err_t rmt_driver_install(rmt_channel_t channel, size_t rx_buf_size, int intr_alloc_flags)
Initialize RMT driver.
Return
• ESP_ERR_INVALID_STATE Driver is already installed, call rmt_driver_uninstall first.
• ESP_ERR_NO_MEM Memory allocation failure
• ESP_OK Success

Parameters
• rx_buf_size: Size of RMT RX ringbuffer. Can be 0 if the RX ringbuffer is not used.
• intr_alloc_flags: Flags for the RMT driver interrupt handler. Pass 0 for default flags. See
esp_intr_alloc.h for details. If ESP_INTR_FLAG_IRAM is used, please do not use the memory
allocated from psram when calling rmt_write_items.
esp_err_t rmt_driver_uninstall(rmt_channel_t channel)
Uninstall RMT driver.
Return
• ESP_OK Success
Parameters
esp_err_t rmt_get_channel_status(rmt_channel_status_result_t *channel_status)
Get the current status of eight channels.
Note Do not call this function if it is possible that rmt_driver_uninstall will be called at the same
time.
Return
• ESP_ERR_INVALID_ARG Parameter is NULL
• ESP_OK Success
Parameters
• [out] channel_status: store the current status of each channel
esp_err_t rmt_get_counter_clock(rmt_channel_t channel, uint32_t *clock_hz)
Get speed of channel s internal counter clock.
Return
• ESP_ERR_INVALID_ARG Parameter is NULL
• ESP_OK Success
Parameters
• [out] clock_hz: counter clock speed, in hz
esp_err_t rmt_write_items(rmt_channel_t channel, const rmt_item32_t *rmt_item, int item_num,
bool wait_tx_done)
RMT send waveform from rmt_item array.
This API allows user to send waveform with any length.
Note This function will not copy data, instead, it will point to the original items, and send the waveform items.
If wait_tx_done is set to true, this function will block and will not return until all items have been sent
out. If wait_tx_done is set to false, this function will return immediately, and the driver interrupt will
continue sending the items. We must make sure the item data will not be damaged when the driver is still
sending items in driver interrupt.
Return
• ESP_OK Success
Parameters
• rmt_item: head point of RMT items array. If ESP_INTR_FLAG_IRAM is used, please do not
use the memory allocated from psram when calling rmt_write_items.
• item_num: RMT data item number.
• wait_tx_done:
– If set 1, it will block the task and wait for sending done.
– If set 0, it will not wait and return immediately.
esp_err_t rmt_wait_tx_done(rmt_channel_t channel, TickType_t wait_time)
Wait RMT TX finished.
Return

• ESP_OK RMT Tx done successfully

• ESP_ERR_TIMEOUT Exceeded the wait_time given
• ESP_FAIL Driver not installed
Parameters
• wait_time: Maximum time in ticks to wait for transmission to be complete. If set 0, return
immediately with ESP_ERR_TIMEOUT if TX is busy (polling).
esp_err_t rmt_get_ringbuf_handle(rmt_channel_t channel, RingbufHandle_t *buf_handle)
Get ringbuffer from RMT.
Users can get the RMT RX ringbuffer handle, and process the RX data.
Return
• ESP_OK Success
Parameters
• buf_handle: Pointer to buffer handle to accept RX ringbuffer handle.
esp_err_t rmt_translator_init(rmt_channel_t channel, sample_to_rmt_t fn)
Init rmt translator and register user callback. The callback will convert the raw data that needs to be sent to
rmt format. If a channel is initialized more than once, tha user callback will be replaced by the later.
Return
• ESP_FAIL Init fail.
• ESP_OK Init success.
Parameters
• channel: RMT channel .
• fn: Point to the data conversion function.
esp_err_t rmt_translator_set_context(rmt_channel_t channel, void *context)
Set user context for the translator of specific channel.
Return
• ESP_FAIL Set context fail
• ESP_OK Set context success
Parameters
• channel: RMT channel number
• context: User context
esp_err_t rmt_translator_get_context(const size_t *item_num, void **context)
Get the user context set by rmt_translator_set_context .
Note This API must be invoked in the RMT translator callback function, and the first argument must be the
actual parameter item_num you got in that callback function.
Return
• ESP_FAIL Get context fail
• ESP_OK Get context success
Parameters
• item_num: Address of the memory which contains the number of translated items (It s from
driver s internal memroy)
• context: Returned User context
esp_err_t rmt_write_sample(rmt_channel_t channel, const uint8_t *src, size_t src_size, bool
wait_tx_done)
Translate uint8_t type of data into rmt format and send it out. Requires rmt_translator_init to init the translator
first.
Return
• ESP_FAIL Send fail
• ESP_OK Send success
Parameters

• channel: RMT channel .

• src: Pointer to the raw data.
• src_size: The size of the raw data.
• wait_tx_done: Set true to wait all data send done.
rmt_tx_end_callback_t rmt_register_tx_end_callback(rmt_tx_end_fn_t function, void *arg)
Registers a callback that will be called when transmission ends.
Called by rmt_driver_isr_default in interrupt context.
Note Requires rmt_driver_install to install the default ISR handler.
Return the previous callback settings (members will be set to NULL if there was none)
Parameters
• function: Function to be called from the default interrupt handler or NULL.
• arg: Argument which will be provided to the callback when it is called.
esp_err_t rmt_memory_rw_rst(rmt_channel_t channel)
Reset RMT TX/RX memory index.
Return
• ESP_OK Success
Parameters
void rmt_set_intr_enable_mask(uint32_t mask)
Set mask value to RMT interrupt enable register.
Parameters
• mask: Bit mask to set to the register
void rmt_clr_intr_enable_mask(uint32_t mask)
Clear mask value to RMT interrupt enable register.
Parameters
• mask: Bit mask to clear the register
esp_err_t rmt_set_pin(rmt_channel_t channel, rmt_mode_t mode, gpio_num_t gpio_num)
Set RMT pin.
Return
• ESP_OK Success
Parameters
• mode: TX or RX mode for RMT
• gpio_num: GPIO number to transmit or receive the signal.
Structures
struct rmt_tx_config_t
Data struct of RMT TX configure parameters.
Public Members
uint32_t carrier_freq_hz
RMT carrier frequency
rmt_carrier_level_t carrier_level
Level of the RMT output, when the carrier is applied
rmt_idle_level_t idle_level
RMT idle level

uint8_t carrier_duty_percent
RMT carrier duty (%)
bool carrier_en
RMT carrier enable
bool loop_en
Enable sending RMT items in a loop
bool idle_output_en
RMT idle level output enable
struct rmt_rx_config_t
Data struct of RMT RX configure parameters.
Public Members
uint16_t idle_threshold
RMT RX idle threshold
uint8_t filter_ticks_thresh
RMT filter tick number
bool filter_en
RMT receiver filter enable
struct rmt_config_t
Data struct of RMT configure parameters.
Public Members
rmt_mode_t rmt_mode
RMT mode: transmitter or receiver
rmt_channel_t channel
RMT channel
gpio_num_t gpio_num
RMT GPIO number
uint8_t clk_div
RMT channel counter divider
uint8_t mem_block_num
RMT memory block number
uint32_t flags
RMT channel extra configurations, OR d with RMT_CHANNEL_FLAGS_[*]
rmt_tx_config_t tx_config
RMT TX parameter
rmt_rx_config_t rx_config
RMT RX parameter
struct rmt_tx_end_callback_t
Structure encapsulating a RMT TX end callback.
Public Members
rmt_tx_end_fn_t function
Function which is called on RMT TX end

void *arg
Optional argument passed to function
Macros
RMT_CHANNEL_FLAGS_AWARE_DFS
Channel can work during APB clock scaling
RMT_CHANNEL_FLAGS_INVERT_SIG
Invert RMT signal
RMT_MEM_ITEM_NUM
Define memory space of each RMT channel (in words = 4 bytes)
RMT_DEFAULT_CONFIG_TX(gpio, channel_id)
Default configuration for Tx channel.
RMT_DEFAULT_CONFIG_RX(gpio, channel_id)
Default configuration for RX channel.
Type Definitions
typedef intr_handle_t rmt_isr_handle_t
RMT interrupt handle.
typedef void (*rmt_tx_end_fn_t)(rmt_channel_t channel, void *arg)
Type of RMT Tx End callback function.
typedef void (*sample_to_rmt_t)(const void *src, rmt_item32_t *dest, size_t src_size, size_t
wanted_num, size_t *translated_size, size_t *item_num)
User callback function to convert uint8_t type data to rmt format(rmt_item32_t).
This function may be called from an ISR, so, the code should be short and efficient.
Note In fact, item_num should be a multiple of translated_size, e.g. : When we convert each byte of uint8_t
type data to rmt format data, the relation between item_num and translated_size should be item_num
= translated_size*8.
Parameters
• src: Pointer to the buffer storing the raw data that needs to be converted to rmt format.
• [out] dest: Pointer to the buffer storing the rmt format data.
• src_size: The raw data size.
• wanted_num: The number of rmt format data that wanted to get.
• [out] translated_size: The size of the raw data that has been converted to rmt format, it
should return 0 if no data is converted in user callback.
• [out] item_num: The number of the rmt format data that actually converted to, it can be less
than wanted_num if there is not enough raw data, but cannot exceed wanted_num. it should return
0 if no data was converted.
Header File
• components/hal/include/hal/rmt_types.h
Structures
struct rmt_channel_status_result_t
Data struct of RMT channel status.
Public Members
rmt_channel_status_t status[RMT_CHANNEL_MAX]
Store the current status of each channel

Enumerations
enum rmt_channel_t
RMT channel ID.
Values:
RMT_CHANNEL_0
RMT channel number 0
RMT_CHANNEL_1
RMT_CHANNEL_2
RMT_CHANNEL_3
RMT_CHANNEL_4
RMT_CHANNEL_5
RMT_CHANNEL_6
RMT_CHANNEL_7
RMT_CHANNEL_MAX
Number of RMT channels
enum rmt_mem_owner_t
RMT Internal Memory Owner.
Values:
RMT_MEM_OWNER_TX
RMT RX mode, RMT transmitter owns the memory block
RMT_MEM_OWNER_RX
RMT RX mode, RMT receiver owns the memory block
RMT_MEM_OWNER_MAX
enum rmt_source_clk_t
Clock Source of RMT Channel.
Values:
RMT_BASECLK_REF = 0
RMT source clock is REF_TICK, 1MHz by default
RMT_BASECLK_APB = 1
RMT source clock is APB CLK, 80Mhz by default
RMT_BASECLK_MAX
enum rmt_data_mode_t
RMT Data Mode.
Note We highly recommended to use MEM mode not FIFO mode since there will be some gotcha in FIFO
mode.
Values:
RMT_DATA_MODE_FIFO
RMT_DATA_MODE_MEM
RMT_DATA_MODE_MAX

enum rmt_mode_t
RMT Channel Working Mode (TX or RX)
Values:
RMT_MODE_TX
RMT TX mode
RMT_MODE_RX
RMT RX mode
RMT_MODE_MAX
enum rmt_idle_level_t
RMT Idle Level.
Values:
RMT_IDLE_LEVEL_LOW
RMT TX idle level: low Level
RMT_IDLE_LEVEL_HIGH
RMT TX idle level: high Level
RMT_IDLE_LEVEL_MAX
enum rmt_carrier_level_t
RMT Carrier Level.
Values:
RMT_CARRIER_LEVEL_LOW
RMT carrier wave is modulated for low Level output
RMT_CARRIER_LEVEL_HIGH
RMT carrier wave is modulated for high Level output
RMT_CARRIER_LEVEL_MAX
enum rmt_channel_status_t
RMT Channel Status.
Values:
RMT_CHANNEL_UNINIT
RMT channel uninitialized
RMT_CHANNEL_IDLE
RMT channel status idle
RMT_CHANNEL_BUSY
RMT channel status busy
2.3.12 SD Pull-up Requirements
Espressif hardware products are designed for multiple use cases which may require different pull states on pins. For
this reason, the pull state of particular pins on certain products will need to be adjusted to provide the pull-ups required
in the SD bus.
SD pull-up requirements apply to cases where ESP32 uses the SPI controller to communicate with SD cards. When
an SD card is operating in SPI mode or 1-bit SD mode, the CMD and DATA (DAT0 - DAT3) lines of the SD bus
must be pulled up by 10 kOhm resistors. Slaves should also have pull-ups on all above-mentioned lines (regardless
of whether these lines are connected to the host) in order to prevent SD cards from entering a wrong state.
By default, the MTDI bootstrapping pin is incompatible with the DAT2 line pull-up if the flash voltage is 3.3 V. For
more information, see MTDI Strapping Pin below.
This document has the following structure:

• Overview of compatibility between the default pull states on pins of Espressif s products and the states required
by the SD bus
• Solutions - ideas on how to resolve compatibility issues
• Related information - other relevant information
Overview of Compatibility
This section provides an overview of compatibility issues that might occur when using SDIO (secure digital input
output). Since the SD bus needs to be connected to pull-ups, these issues should be resolved regardless of whether
they are related to master (host) or slave (device). Each issue has links to its respective solution. A solution for a host
and device may differ.
Systems on a Chip (SoCs)

• ESP32 (except for D2WD versions, see ESP32 datasheet):
– No Pull-ups
– Conflicts Between Bootstrap and SDIO on DAT2 for models with 3.3 V flash chip
• ESP32-D2WD:
– No Pull-ups
– No Pull-up on GPIO12
Systems in Packages (SIP)

• ESP32-PICO-D4:
– No Pull-ups
– Conflicts Between Bootstrap and SDIO on DAT2
Modules
• ESP32-WROOM-32 Series, including ESP32-WROOM-32, ESP32-WROOM-32D, ESP32-WROOM-32U,
and ESP32-SOLO-1
– No Pull-ups
• ESP32-WROVER Series, including ESP32-WROVER and ESP32-WROVER-I
– No Pull-ups
• ESP32-WROVER-B Series, including ESP32-WROVER-B and ESP32-WROVER-IB
– No Pull-ups
Development Boards
• ESP32-PICO-KIT, including PICO-KIT v4.1, v4.0, and v3
– No Pull-ups
– Download Mode Not Working (minor issue)
• ESP32-DevKitC, including ESP32-DevKitC v4 and v2
– No Pull-ups
– Download Mode Not Working (minor issue)
• ESP-WROVER-KIT
– Required pull-ups are provided
– Pull-up Conflicts on GPIO13 (v4.1, v3, v2, and v1)
– Conflicts Between Bootstrap and SDIO on DAT2 (v4.1, v2, and v1)
– Download Mode Not Working (minor issue) (v2, v1)
You can determine the version of your ESP23-WROVER-KIT by checking which module is
mounted on it:

– ESP32-WROVER-B on v4.1
– ESP32-WROVER on v3
– ESP32-WROOM-32 on v1 and v2
• ESP32-LyraTD-MSC
• ESP32-LyraT
– Pull-up Conflicts on GPIO13
Non-Espressif Hosts Please make sure that your SDIO host provides necessary pull-ups for all SD bus signals.
Solutions
No Pull-ups If you use a development board without pull-ups, you can do the following:
• If your host and slave device are on seperate boards, replace one of them with a board that has pull-ups. For
the list of Espressif s development boards with pull-ups, go to Development Boards.
• Attach external pull-ups by connecting each pin which requires a pull-up to VDD via a 10 kOhm resistor.
Pull-up Conflicts on GPIO13 If DAT3 of your device is not properly pulled up, you have the following options:
• Use 1-bit SD mode and tie the device s DAT3 to VDD
• Use SPI mode
• Perform one of the following actions on the GPIO13 pin:
– Remove the pull-down resistors
– Attach a pull-up resistor of less than 5 kOhm (2 kOhm suggested)
– Pull it up or drive it high either by using the host or with 3.3 V on VDD in 1-bit SD mode
Conflicts Between Bootstrap and SDIO on DAT2 There is a conflict between the boot strapping requirements
of the ESP32 and the SDIO protocol. For details, see MTDI Strapping Pin.
To resolve the conflict, you have the following options:
1. (Recommended) Burn the flash voltage selection eFuses. This will permanently configure the internal regulator
s output voltage to 3.3 V, and GPIO12 will not be used as a bootstrapping pin. After that, connect a pull-up
resistor to GPIO12.
Warning: Burning eFuses is irreversible! The issue list above might be out of date, so please make sure
that the module you are burning has a 3.3 V flash chip by checking the information on http://www.espressif.
com/. If you burn the 3.3 V eFuses on a module with a 1.8 V flash chip, the module will stop functioning.
If you are sure that you need to irreversibly burn eFuses, go to your ESP-IDF directory and run the following
command:
components/esptool_py/esptool/espefuse.py set_flash_voltage 3.3V
This command will burn the XPD_SDIO_TIEH, XPD_SDIO_FORCE, and XPD_SDIO_REG eFuses. After all
the three eFuses are burned to value 1, the internal VDD_SDIO flash voltage regulator will be permanently set
to 3.3 V. You will see the following log if the burning succeeds:
espefuse.py v2.6
Connecting....
Enable internal flash voltage regulator (VDD_SDIO) to 3.3 V.

The following eFuses are burned: XPD_SDIO_FORCE, XPD_SDIO_REG, XPD_SDIO_TIEH.
This is an irreversible operation.
Type 'BURN' (all capitals) to continue.


BURN
VDD_SDIO setting complete.
To check the status of the eFuses, run:
``components/esptool_py/esptool/espefuse.py summary``
If running from an automated flashing script, espefuse.py has an option --do-not-confirm.

For more details, see ESP32 Technical Reference Manual [PDF].
2. If using 1-bit SD mode or SPI mode, disconnect the DAT2 pin and make sure it is pulled high. For this, do
one the following:
• Leave the host s DAT2 floating and directly connect the slave s DAT2 to VDD.
• For a slave device, build a firmware with the option SDIO_SLAVE_FLAG_DAT2_DISABLED and re-
flash your device. This option will help avoid slave detecting on the DAT2 line. Note that 4-bit SD mode
will no longer be supported by the standard Card Common Control Register (CCCR); however, the host
will not be aware of that. The use of 4-bit SD mode will have to be disabled on the host s side.
No Pull-up on GPIO12 Your module is compatible with the SDIO protocol. Just connect GPIO12 to VDD via a
10 kOhm resistor.
Download Mode Not Working (minor issue) When the GPIO2 pin is pulled high in accordance with the SD
pull-up requirements, you cannot enter Download mode because GPIO2 is a bootstrapping pin which in this case
must be pulled low.
There are the following solutions:
• For boards that require shorting the GPIO0 and GPIO2 pins with a jumper, put the jumper in place, and the
auto-reset circuit will pull GPIO2 low along with GPIO0 before entering Download mode.
• For boards with components attached to their GPIO2 pin (such as pull-down resistors and/or LEDs), check the
schematic of your development board for anything connected to GPIO2.
– LEDs would not affect operation in most cases.
– Pull-down resistors can interfere with DAT0 signals and must be removed.
If the above solutions do not work for you, please determine if it is the host or slave device that has pull-ups affecting
their GPIO2, then locate these pull-ups and remove them.
Related Information
MTDI Strapping Pin MTDI (GPIO12) is used as a bootstrapping pin to select the output voltage of an internal
regulator (VDD_SDIO) which powers the flash chip. This pin has an internal pull-down, so, if left unconnected, it
will read low at startup, which will lead to selecting the default 3.3 V operation.
All ESP32-WROVER modules, excluding ESP32-WROVER-B, use 1.8 V flash and have internal pull-ups on
GPIO12. Other modules that use 3.3 V flash have no pull-ups on the GPIO12 pin, and this pin is slightly pulled
down internally.
When adding a pull-up to this pin for SD card operation, consider the following:
• For boards that do not use the internal regulator (VDD_SDIO) to power flash, GPIO12 can be pulled high.
• For boards using 1.8 V flash chips, GPIO12 needs to be pulled high at reset. This is fully compatible with the
SD card operation.
• On boards using the internal regulator and a 3.3 V flash chip, GPIO12 must be pulled low at reset. This is
incompatible with the SD card operation. For reference information on compatibility of Espressif s boards
with the SD card operation, see Overview of Compatibility.
Internal Pull-ups and Strapping Requirements Using external resistors is always preferable. However, Espres-
sif s products have internal weak pull-up and pull-down resistors which can be enabled and used instead of external
ones. Please keep in mind that this solution cannot guarantee reliable SDIO communication.

With that said, the information about these internal pull-ups and strapping requirements can still be useful. Espressif
hardware products have different weak internal pull-ups / pull-downs connected to CMD and DATA pins. The table
below shows the default pull-up and pull-down states of the CMD and DATA pins.
The following abbreviations are used in the table:
• WPU: Weak pull-up inside the SoC
• WPD: Weak pull-down inside the SoC
• PU: Pull-up inside Espressif modules but outside the SoC
Table 4: Default pull-up and pull-down states of the CMD and DATA pins
GPIO number Pin Name Startup State Strapping Requirement
15 CMD WPU
2 DAT0 WPD Low for Download mode
4 DAT1 WPD
12 DAT2 PU for 1.8 V flash; WPD High for 1.8 V flash; Low
for 3.3 V flash for 3.3 V flash
13 DAT3 WPU
2.3.13 SDMMC Host Driver
Overview
ESP32 s SDMMC host peripheral has two slots:

• Slot 0 (SDMMC_HOST_SLOT_0) is an 8-bit slot. It uses HS1_* signals in the PIN MUX.
• Slot 1 (SDMMC_HOST_SLOT_1) is a 4-bit slot. It uses HS2_* signals in the PIN MUX.
Pin mappings of these slots are given in the table below.
Signal Slot 0 Slot 1

CMD GPIO11 GPIO15
CLK GPIO6 GPIO14
D0 GPIO7 GPIO2
D1 GPIO8 GPIO4
D2 GPIO9 GPIO12
D3 GPIO10 GPIO13
D4 GPIO16
D5 GPIO17
D6 GPIO5
D7 GPIO18
CD any input via GPIO matrix
WP any input via GPIO matrix
The Card Detect and Write Protect signals can be routed to arbitrary pins using the GPIO matrix. To reserve the
pins, set the gpio_cd and gpio_wp members of the sdmmc_slot_config_t structure before calling sd-
mmc_host_init_slot(). Please note that it is not advised to specify a Card Detect pin when working with
SDIO cards, because the card detect signal in ESP32 can also trigger SDIO slave interrupt.
Warning: Pins used by Slot 0 (HS1_*) are also used to connect the SPI flash chip in ESP32-WROOM and
ESP32-WROVER modules. These pins cannot be shared between an SD card and SPI flash. If you need to use
Slot 0, connect SPI flash to different pins and set eFuses accordingly.

Supported Speed Modes
SDMMC Host driver supports the following speed modes:

• Default Speed (20 MHz), 1/4-line (with SD cards), and 1/4/8-line (with 3.3 V eMMC)
• High Speed (40 MHz), 1/4-line (with SD cards), and 1/4/8-line (with 3.3 V eMMC)
• High Speed DDR (40 MHz), 4-line (with 3.3 V eMMC)
Speed modes not supported at present:
• High Speed DDR mode, 8-line eMMC
• UHS-I 1.8 V modes, 4-line SD cards
Using the SDMMC Host Driver
Of all the functions listed below, only the following ones will be used directly by most applications:
• sdmmc_host_init()
• sdmmc_host_init_slot()
• sdmmc_host_deinit()
Other functions, such as the ones given below, will be called by the SD/MMC protocol layer via function pointers in
the sdmmc_host_t structure:
• sdmmc_host_set_bus_width()
• sdmmc_host_set_card_clk()
• sdmmc_host_do_transaction()
Configuring Bus Width and Frequency
With the default initializers for sdmmc_host_t and sdmmc_slot_config_t (SDMMC_HOST_DEFAULT and
SDMMC_SLOT_CONFIG_DEFAULT), SDMMC Host driver will attempt to use the widest bus supported by the card
(4 lines for SD, 8 lines for eMMC) and the frequency of 20 MHz.
In the designs where communication at 40 MHz frequency can be achieved, it is possible to increase the bus frequency
by changing the max_freq_khz field of sdmmc_host_t:
sdmmc_host_t host = SDMMC_HOST_DEFAULT();

host.max_freq_khz = SDMMC_FREQ_HIGHSPEED;
To configure the bus width, set the width field of sdmmc_slot_config_t. For example, to set 1-line mode:
sdmmc_slot_config_t slot = SDMMC_SLOT_CONFIG_DEFAULT();

slot.width = 1;
See also
See SD/SDIO/MMC Driver for the higher level driver which implements the protocol layer.
See SD SPI Host Driver for a similar driver which uses the SPI controller and is limited to SD protocol s SPI mode.
See SD Pull-up Requirements for pullup support and compatibilities of modules and development kits.
API Reference
Header File
• components/driver/include/driver/sdmmc_host.h

Functions
esp_err_t sdmmc_host_init(void)
Initialize SDMMC host peripheral.
Note This function is not thread safe
Return
• ESP_ERR_INVALID_STATE if sdmmc_host_init was already called
• ESP_ERR_NO_MEM if memory can not be allocated
esp_err_t sdmmc_host_init_slot(int slot, const sdmmc_slot_config_t *slot_config)
Initialize given slot of SDMMC peripheral.
On the ESP32, SDMMC peripheral has two slots:
• Slot 0: 8-bit wide, maps to HS1_* signals in PIN MUX
• Slot 1: 4-bit wide, maps to HS2_* signals in PIN MUX
Card detect and write protect signals can be routed to arbitrary GPIOs using GPIO matrix.
Return
• ESP_ERR_INVALID_STATE if host has not been initialized using sdmmc_host_init
Parameters
• slot: slot number (SDMMC_HOST_SLOT_0 or SDMMC_HOST_SLOT_1)
• slot_config: additional configuration for the slot
esp_err_t sdmmc_host_set_bus_width(int slot, size_t width)
Select bus width to be used for data transfer.
SD/MMC card must be initialized prior to this command, and a command to set bus width has to be sent to
the card (e.g. SD_APP_SET_BUS_WIDTH)
Return
• ESP_ERR_INVALID_ARG if slot number or width is not valid
Parameters
• width: bus width (1, 4, or 8 for slot 0; 1 or 4 for slot 1)
size_t sdmmc_host_get_slot_width(int slot)
Get bus width configured in sdmmc_host_init_slot to be used for data transfer.
Return configured bus width of the specified slot.
Parameters
esp_err_t sdmmc_host_set_card_clk(int slot, uint32_t freq_khz)
Set card clock frequency.
Currently only integer fractions of 40MHz clock can be used. For High Speed cards, 40MHz can be used. For
Default Speed cards, 20MHz can be used.
Return
• other error codes may be returned in the future
Parameters
• freq_khz: card clock frequency, in kHz
esp_err_t sdmmc_host_set_bus_ddr_mode(int slot, bool ddr_enabled)
Enable or disable DDR mode of SD interface.
Return

• ESP_ERR_NOT_SUPPORTED if DDR mode is not supported on this slot
Parameters
• ddr_enabled: enable or disable DDR mode
esp_err_t sdmmc_host_do_transaction(int slot, sdmmc_command_t *cmdinfo)
Send command to the card and get response.
This function returns when command is sent and response is received, or data is transferred, or timeout occurs.
Note This function is not thread safe w.r.t. init/deinit functions, and bus width/clock speed configuration
functions. Multiple tasks can call sdmmc_host_do_transaction as long as other sdmmc_host_* functions
are not called.
Attention Data buffer passed in cmdinfo->data must be in DMA capable memory
Return
• ESP_ERR_TIMEOUT if response or data transfer has timed out
• ESP_ERR_INVALID_CRC if response or data transfer CRC check has failed
• ESP_ERR_INVALID_RESPONSE if the card has sent an invalid response
• ESP_ERR_INVALID_SIZE if the size of data transfer is not valid in SD protocol
• ESP_ERR_INVALID_ARG if the data buffer is not in DMA capable memory
Parameters
• cmdinfo: pointer to structure describing command and data to transfer
esp_err_t sdmmc_host_io_int_enable(int slot)
Enable IO interrupts.
This function configures the host to accept SDIO interrupts.
Return returns ESP_OK, other errors possible in the future
Parameters
esp_err_t sdmmc_host_io_int_wait(int slot, TickType_t timeout_ticks)
Block until an SDIO interrupt is received, or timeout occurs.
Return
• ESP_OK on success (interrupt received)
• ESP_ERR_TIMEOUT if the interrupt did not occur within timeout_ticks
Parameters
• timeout_ticks: number of RTOS ticks to wait for the interrupt
esp_err_t sdmmc_host_deinit(void)
Disable SDMMC host and release allocated resources.
Return
• ESP_ERR_INVALID_STATE if sdmmc_host_init function has not been called
esp_err_t sdmmc_host_pullup_en(int slot, int width)
Enable the pull-ups of sd pins.
This function is deprecated. Please set SDMMC_SLOT_FLAG_INTERNAL_PULLUP flag in sd-
mmc_slot_config_t::flags instead.
Note You should always place actual pullups on the lines instead of using this function. Internal pullup re-
sistance are high and not sufficient, may cause instability in products. This is for debug or examples
only.
Return
• ESP_OK: if success
• ESP_ERR_INVALID_ARG: if configured width larger than maximum the slot can support

Parameters
• slot: Slot to use, normally set it to 1.
• width: Bit width of your configuration, 1 or 4.
Structures
struct sdmmc_slot_config_t
Extra configuration for SDMMC peripheral slot
Public Members
gpio_num_t gpio_cd
GPIO number of card detect signal.
gpio_num_t cd
GPIO number of card detect signal; shorter name.
gpio_num_t gpio_wp
GPIO number of write protect signal.
gpio_num_t wp
GPIO number of write protect signal; shorter name.
uint8_t width
Bus width used by the slot (might be less than the max width supported)
uint32_t flags
Features used by this slot.
Macros
SDMMC_HOST_SLOT_0
SDMMC slot 0.
SDMMC_HOST_SLOT_1
SDMMC slot 1.
SDMMC_HOST_DEFAULT()
Default sdmmc_host_t structure initializer for SDMMC peripheral.
Uses SDMMC peripheral, with 4-bit mode enabled, and max frequency set to 20MHz
SDMMC_SLOT_FLAG_INTERNAL_PULLUP
Enable internal pullups on enabled pins. The internal pullups are insufficient however, please make sure external
pullups are connected on the bus. This is for debug / example purpose only.
SDMMC_SLOT_NO_CD
indicates that card detect line is not used
SDMMC_SLOT_NO_WP
indicates that write protect line is not used
SDMMC_SLOT_WIDTH_DEFAULT
use the maximum possible width for the slot
SDMMC_SLOT_CONFIG_DEFAULT()
Macro defining default configuration of SDMMC host slot
2.3.14 SD SPI Host Driver
Overview
The SD SPI host driver allows communicating with one or more SD cards by the SPI Master driver which makes use
of the SPI host. Each card is accessed through an SD SPI device represented by an sdspi_dev_handle_t spi_handle re-

turned when attaching the device to an SPI bus by calling sdspi_host_init_device. The bus should be already initialized
before (by spi_bus_initialize).
This driver s naming pattern was adopted from the SDMMC Host driver due to their similarity. Likewise, the APIs
of both drivers are also very similar.
SD SPI driver (access the SD card in SPI mode) offers lower throughput but makes pin selection more flexible. With
the help of the GPIO matrix, an SPI peripheral s signals can be routed to any ESP32 pin. Otherwise, if SDMMC
host driver is used (See SDMMC Host) to access the card in SD 1-bit/4-bit mode, higher throughput can be reached
but it requires routing the signals through their dedicated IO_MUX pins only.
With the help of SPI Master driver based on, the SPI bus can be shared among SD cards and other SPI devices. The
SPI Master driver will handle exclusive access from different tasks.
The SD SPI driver uses software-controlled CS signal.
How to Use
Firstly, use the macro SDSPI_DEVICE_CONFIG_DEFAULT to initialize a structure sdmmc_slot_config_t,

which is used to initialize an SD SPI device. This macro will also fill in the default pin mappings, which is same as
the pin mappings of SDMMC host driver. Modify the host and pins of the structure to desired value. Then call
sdspi_host_init_device to initialize the SD SPI device and attach to its bus.
Then use SDSPI_HOST_DEFAULT macro to initialize a sdmmc_host_t structure, which is used to store the state
and configurations of upper layer (SD/SDIO/MMC driver). Modify the slot parameter of the structure to the SD SPI
device spi_handle just returned from sdspi_host_init_device. Call sdmmc_card_init with the sdmmc_host_t to
probe and initialize the SD card.
Now you can use SD/SDIO/MMC driver functions to access your card!
Other Details
Only the following driver s API functions are normally used by most applications:
• sdspi_host_init()
• sdspi_host_init_device()
• sdspi_host_remove_device()
• sdspi_host_deinit()
Other functions are mostly used by the protocol level SD/SDIO/MMC driver via function pointers in the sd-
mmc_host_t structure. For more details, see the SD/SDIO/MMC Driver.
Note: SD over SPI does not support speeds above SDMMC_FREQ_DEFAULT due to the limitations of the SPI
driver.
API Reference
Header File
• components/driver/include/driver/sdspi_host.h
Functions
esp_err_t sdspi_host_init(void)
Initialize SD SPI driver.
Return
• other error codes may be returned in future versions

esp_err_t sdspi_host_init_device(const sdspi_device_config_t *dev_config, sdspi_dev_handle_t

*out_handle)
Attach and initialize an SD SPI device on the specific SPI bus.
Note Initialize the SPI bus by spi_bus_initialize() before calling this function.
Note The SDIO over sdspi needs an extra interrupt line. Call gpio_install_isr_service() before
this function.
Return
• ESP_ERR_INVALID_ARG if sdspi_host_init_device has invalid arguments
• other errors from the underlying spi_master and gpio drivers
Parameters
• dev_config: pointer to device configuration structure
• out_handle: Output of the handle to the sdspi device.
esp_err_t sdspi_host_remove_device(sdspi_dev_handle_t handle)
Remove an SD SPI device.
Return Always ESP_OK
Parameters
• handle: Handle of the SD SPI device
esp_err_t sdspi_host_do_transaction(sdspi_dev_handle_t handle, sdmmc_command_t *cmdinfo)
Send command to the card and get response.
This function returns when command is sent and response is received, or data is transferred, or timeout occurs.
Note This function is not thread safe w.r.t. init/deinit functions, and bus width/clock speed configuration
functions. Multiple tasks can call sdspi_host_do_transaction as long as other sdspi_host_* functions are
not called.
Return
• ESP_ERR_TIMEOUT if response or data transfer has timed out
• ESP_ERR_INVALID_CRC if response or data transfer CRC check has failed
• ESP_ERR_INVALID_RESPONSE if the card has sent an invalid response
Parameters
• handle: Handle of the sdspi device
• cmdinfo: pointer to structure describing command and data to transfer
esp_err_t sdspi_host_set_card_clk(sdspi_dev_handle_t host, uint32_t freq_khz)
Set card clock frequency.
Currently only integer fractions of 40MHz clock can be used. For High Speed cards, 40MHz can be used. For
Default Speed cards, 20MHz can be used.
Return
• other error codes may be returned in the future
Parameters
• host: Handle of the sdspi device
• freq_khz: card clock frequency, in kHz
esp_err_t sdspi_host_deinit(void)
Release resources allocated using sdspi_host_init.
Return
• ESP_ERR_INVALID_STATE if sdspi_host_init function has not been called

esp_err_t sdspi_host_io_int_enable(sdspi_dev_handle_t handle)

Enable SDIO interrupt.
Return
Parameters
esp_err_t sdspi_host_io_int_wait(sdspi_dev_handle_t handle, TickType_t timeout_ticks)
Wait for SDIO interrupt until timeout.
Return
Parameters
• timeout_ticks: Ticks to wait before timeout.
esp_err_t sdspi_host_init_slot(int slot, const sdspi_slot_config_t *slot_config)
Initialize SD SPI driver for the specific SPI controller.
Note The SDIO over sdspi needs an extra interrupt line. Call gpio_install_isr_service() before
this function.
Parameters
• slot: SPI controller to use (SPI2_HOST or SPI3_HOST)
• slot_config: pointer to slot configuration structure
Return
• ESP_ERR_INVALID_ARG if sdspi_init_slot has invalid arguments
• other errors from the underlying spi_master and gpio drivers
Structures
struct sdspi_device_config_t
Extra configuration for SD SPI device.
Public Members
spi_host_device_t host_id
SPI host to use, SPIx_HOST (see spi_types.h).
gpio_num_t gpio_cs
GPIO number of CS signal.
gpio_num_t gpio_cd
gpio_num_t gpio_wp
gpio_num_t gpio_int
GPIO number of interrupt line (input) for SDIO card.
struct sdspi_slot_config_t
Extra configuration for SPI host.
Public Members
gpio_num_t gpio_cs
GPIO number of CS signal.

gpio_num_t gpio_cd
gpio_num_t gpio_wp
gpio_num_t gpio_int
GPIO number of interrupt line (input) for SDIO card.
gpio_num_t gpio_miso
GPIO number of MISO signal.
gpio_num_t gpio_mosi
GPIO number of MOSI signal.
gpio_num_t gpio_sck
GPIO number of SCK signal.
int dma_channel
DMA channel to be used by SPI driver (1 or 2).
Macros
SDSPI_DEFAULT_HOST
SDSPI_HOST_DEFAULT()
Default sdmmc_host_t structure initializer for SD over SPI driver.
Uses SPI mode and max frequency set to 20MHz
slot should be set to an sdspi device initialized by sdspi_host_init_device().
SDSPI_SLOT_NO_CD
indicates that card detect line is not used
SDSPI_SLOT_NO_WP
indicates that write protect line is not used
SDSPI_SLOT_NO_INT
indicates that interrupt line is not used
SDSPI_DEVICE_CONFIG_DEFAULT()
Macro defining default configuration of SD SPI device.
SDSPI_SLOT_CONFIG_DEFAULT()
Macro defining default configuration of SPI host
Type Definitions
typedef int sdspi_dev_handle_t
Handle representing an SD SPI device.
2.3.15 SDIO Card Slave Driver
Overview
The ESP32 SDIO Card peripherals (Host, Slave) shares two sets of pins as below table. The first set is
usually occupied by SPI0 bus which is responsible for the SPI flash holding the code to run. This means
SDIO slave driver can only runs on the second set of pins while SDIO host is not using it.
The SDIO slave can run under 3 modes: SPI, 1-bit SD and 4-bit SD modes, which is detected automat-
ically by the hardware. According to the SDIO specification, CMD and DAT0-3 lines should be pulled
up no matter in 1-bit, 4-bit or SPI mode.

Connections
Pin Name Corresponding pins in SPI mode Slot1 Slot2
GPIO Number
CLK SCLK 6 14
CMD MOSI 11 15
DAT0 MISO 7 2
DAT1 Interrupt 8 4
DAT2 N.C. (pullup) 9 12
DAT3 #CS 10 13
• 1-bit SD mode: Connect CLK, CMD, DAT0, DAT1 pins and the ground.
• 4-bit SD mode: Connect all pins and the ground.
• SPI mode: Connect SCLK, MOSI, MISO, Interrupt, #CS pins and the ground.
Note: Please check if CMD and DATA lines D0-D3 of the card are properly pulled up by 10 KOhm resistors. This
should be ensured even in 1-bit mode or SPI mode. Most official modules don t offer these pullups internally. If
you are using official development boards, check Overview of Compatibility to see whether your development boards
have such pullups.
Note: Most official modules have conflicts on strapping pins with the SDIO slave function. If you are using a ESP32
module with 3.3 V flash inside, you have to burn the EFUSE when you are developing on the module for the first
time. See Overview of Compatibility to see how to make your modules compatible with the SDIO.
Here is a list for modules/kits with 3.3 V flash:
• Modules: ESP32-PICO-D4, ESP32-WROOM-32 series (including ESP32-SOLO-1), ESP32-WROVER-B
and ESP32-WROVER-IB
• Kits: ESP32-PICO-KIT, ESP32-DevKitC (till v4), ESP32-WROVER-KIT (v4.1 (also known as ESP32-
WROVER-KIT-VB), v2, v1 (also known as DevKitJ v1))
You can tell the version of your ESP23-WROVER-KIT version from the module on it: v4.1 are with ESP32-
WROVER-B modules, v3 are with ESP32-WROVER modules, while v2 and v1 are with ESP32-WROOM-32
modules.
Refer to SD Pull-up Requirements for more technical details of the pullups.

The host initialize the slave into SD mode by first sending CMD0 with DAT3 pin high, or in SPI mode by sending
CMD0 with CS pin (the same pin as DAT3) low.
After the initialization, the host can enable the 4-bit SD mode by writing CCCR register 0x07 by CMD52. All the
bus detection process are handled by the slave peripheral.
The host has to communicate with the slave by an ESP-slave-specific protocol. The slave driver offers 3 services over
Function 1 access by CMD52 and CMD53: (1) a sending FIFO and a receiving FIFO, (2) 52 8-bit R/W registers
shared by host and slave, (3) 16 interrupt sources (8 from host to slave, and 8 from slave to host).
Terminology The SDIO slave driver uses the following terms:

• Transfer: a transfer is always started by a command token from the host, and may contain a reply and several
data blocks. ESP32 slave software is based on transfers.
• Sending: slave to host transfers.
• Receiving: host to slave transfers.
Note: Register names in ESP32 Technical Reference Manual > SDIO Slave Controller [PDF] are oriented from the
point of view of the host, i.e. rx registers refer to sending, while tx registers refer to receiving. We re not
using tx or rx in the driver to avoid ambiguities.

• FIFO: specific address in Function 1 that can be access by CMD53 to read/write large amount of data. The
address is related to the length requested to read from/write to the slave in a single transfer: requested length =
0x1F800-address.
• Ownership: When the driver takes ownership of a buffer, it means the driver can randomly read/write the
buffer (usually via DMA). The application should not read/write the buffer until the ownership is returned to
the application. If the application reads from a buffer owned by a receiving driver, the data read can be random;
if the application writes to a buffer owned by a sending driver, the data sent may be corrupted.
• Requested length: The length requested in one transfer determined by the FIFO address.
• Transfer length: The length requested in one transfer determined by the CMD53 byte/block count field.
Note: Requested length is different from the transfer length. ESP32 slave DMA base on the requested length rather
than the transfer length. The transfer length should be no shorter than the requested length, and the rest part will be
filled with 0 (sending) or discard (receiving).
• Receiving buffer size: The buffer size is pre-defined between the host and the slave before communication
starts. Slave application has to set the buffer size during initialization by the recv_buffer_size member
of sdio_slave_config_t.
• Interrupts: the esp32 slave support interrupts in two directions: from host to slave (called slave interrupts below)
and from slave to host (called host interrupts below). See more in Interrupts.
• Registers: specific address in Function 1 access by CMD52 or CMD53.
Communication with ESP SDIO Slave The host should initialize the ESP32 SDIO slave according to the standard
SDIO initialization process (Sector 3.1.2 of SDIO Simplified Specification), which is described briefly in ESP SDIO
Slave Initialization.
Furthermore, there s an ESP32-specific upper-level communication protocol upon the CMD52/CMD53 to Func
1. Please refer to ESP SDIO Slave Protocol. There is also a component ESP Serial Slave Link for ESP32 master to
communicate with ESP32 SDIO slave, see example peripherals/sdio when programming your host.
Interrupts There are interrupts from host to slave, and from slave to host to help communicating conveniently.
Slave Interrupts The host can interrupt the slave by writing any one bit in the register 0x08D. Once any bit
of the register is set, an interrupt is raised and the SDIO slave driver calls the callback function defined in the
slave_intr_cb member in the sdio_slave_config_t structure.
Note: The callback function is called in the ISR, do not use any delay, loop or spinlock in the callback.
There s another set of functions can be used. You can call sdio_slave_wait_int to wait for an interrupt
within a certain time, or call sdio_slave_clear_int to clear interrupts from host. The callback function can
work with the wait functions perfectly.
Host Interrupts The slave can interrupt the host by an interrupt line (at certain time) which is level sensitive. When
the host see the interrupt line pulled down, it may read the slave interrupt status register, to see the interrupt source.
Host can clear interrupt bits, or choose to disable a interrupt source. The interrupt line will hold active until all the
sources are cleared or disabled.
There are several dedicated interrupt sources as well as general purpose sources. see sdio_slave_hostint_t
for more information.
Shared Registers There are 52 8-bit R/W shared registers to share information between host and slave. The slave
can write or read the registers at any time by sdio_slave_read_reg and sdio_slave_write_reg. The
host can access (R/W) the register by CMD52 or CMD53.

Receiving FIFO When the host is going to send the slave some packets, it has to check whether the slave is ready
to receive by reading the buffer number of slave.
To allow the host sending data to the slave, the application has to load buffers to the slave driver by the following
steps:
1. Register the buffer by calling sdio_slave_recv_register_buf, and get the handle of the registered
buffer. The driver will allocate memory for the linked-list descriptor needed to link the buffer onto the hard-
ware. The size of these buffers should equal to the Receiving buffer size.
2. Load buffers onto the driver by passing the buffer handle to sdio_slave_recv_load_buf.
3. Get the received data by calling sdio_slave_recv or sdio_slave_recv_packet. If non-blocking
call is needed, set wait=0.
The difference between two APIs is that, sdio_slave_recv_packet gives more information about
packet, which can consist of several buffers. When ESP_ERR_NOT_FINISHED is returned by this API,
you should call this API iteratively until the return value is ESP_OK. All the continuous buffers returned with
ESP_ERR_NOT_FINISHED, together with the last buffer returned with ESP_OK, belong to one packet from
the host. Call sdio_slave_recv_get_buf to get the address of the received data, and the actual length
received in each buffer. The packet length is the sum of received length of all the buffers in the packet.
If the host never send data longer than the Receiving buffer size, or you don t care about the packet boundary
(e.g. the data is only a byte stream), you can call the simpler version sdio_slave_recv instead.
4. Pass the handle of processed buffer back to the driver by sdio_recv_load_buf again.
Note: To avoid overhead from copying data, the driver itself doesn t have any buffer inside, the application is
responsible to offer new buffers in time. The DMA will automatically store received data to the buffer.
Sending FIFO Each time the slave has data to send, it raises an interrupt and the host will request for the packet
length. There are two sending modes:
• Stream Mode: when a buffer is loaded to the driver, the buffer length will be counted into the packet length
requested by host in the incoming communications. Regardless previous packets are sent or not. This means
the host can get data of several buffers in one transfer.
• Packet Mode: the packet length is updated packet by packet, and only when previous packet is sent. This
means that the host can only get data of one buffer in one transfer.
Note: To avoid overhead from copying data, the driver itself doesn t have any buffer inside. Namely, the DMA
takes data directly from the buffer provided by the application. The application should not touch the buffer until the
sending is finished.
The sending mode can be set in the sending_mode member of sdio_slave_config_t, and the buffer num-
bers can be set in the send_queue_size. All the buffers are restricted to be no larger than 4092 bytes. Though
in the stream mode several buffers can be sent in one transfer, each buffer is still counted as one in the queue.
The application can call sdio_slave_transmit to send packets. In this case the function returns when the
transfer is successfully done, so the queue is not fully used. When higher effeciency is required, the application can
use the following functions instead:
1. Pass buffer information (address, length, as well as an arg indicating the buffer) to
sdio_slave_send_queue. If non-blocking call is needed, set wait=0. If the wait is not
portMAX_DELAY (wait until success), application has to check the result to know whether the data is put in
to the queue or discard.
2. Call sdio_slave_send_get_finished to get and deal with a finished transfer. A buffer should be keep
unmodified until returned from sdio_slave_send_get_finished. This means the buffer is actually
sent to the host, rather than just staying in the queue.
There are several ways to use the arg in the queue parameter:
1. Directly point arg to a dynamic-allocated buffer, and use the arg to free it when transfer finished.

2. Wrap transfer informations in a transfer structure, and point arg to the structure. You can use the structure
to do more things like:
typedef struct {
uint8_t* buffer;
size_t size;
int id;
}sdio_transfer_t;
//and send as:

sdio_transfer_t trans = {
.buffer = ADDRESS_TO_SEND,
.size = 8,
.id = 3, //the 3rd transfer so far
};
sdio_slave_send_queue(trans.buffer, trans.size, &trans, portMAX_DELAY);
//... maybe more transfers are sent here
//and deal with finished transfer as:

sdio_transfer_t* arg = NULL;
sdio_slave_send_get_finished((void**)&arg, portMAX_DELAY);
ESP_LOGI("tag", "(%d) successfully send %d bytes of %p", arg->id, arg->size,␣
,→arg->buffer);
some_post_callback(arg); //do more things
3. Working with the receiving part of this driver, point arg to the receive buffer handle of this buffer. So that
we can directly use the buffer to receive data when it s sent:
uint8_t buffer[256]={1,2,3,4,5,6,7,8};
sdio_slave_buf_handle_t handle = sdio_slave_recv_register_buf(buffer);
sdio_slave_send_queue(buffer, 8, handle, portMAX_DELAY);
//... maybe more transfers are sent here
//and load finished buffer to receive as

sdio_slave_buf_handle_t handle = NULL;
sdio_slave_send_get_finished((void**)&handle, portMAX_DELAY);
sdio_slave_recv_load_buf(handle);
More about this, see peripherals/sdio.
Application Example
Slave/master communication: peripherals/sdio.
API Reference
Header File
• components/hal/include/hal/sdio_slave_types.h
Enumerations
enum sdio_slave_hostint_t
Mask of interrupts sending to the host.
Values:
SDIO_SLAVE_HOSTINT_BIT0 = BIT(0)
General purpose interrupt bit 0.

SDIO_SLAVE_HOSTINT_SEND_NEW_PACKET = BIT(23)
New packet available.
enum sdio_slave_timing_t
Timing of SDIO slave.
Values:
SDIO_SLAVE_TIMING_PSEND_PSAMPLE = 0
Send at posedge, and sample at posedge. Default value for HS mode. Normally there s no problem
using this to work in DS mode.
SDIO_SLAVE_TIMING_NSEND_PSAMPLE
Send at negedge, and sample at posedge. Default value for DS mode and below.
SDIO_SLAVE_TIMING_PSEND_NSAMPLE
Send at posedge, and sample at negedge.
SDIO_SLAVE_TIMING_NSEND_NSAMPLE
Send at negedge, and sample at negedge.
enum sdio_slave_sending_mode_t
Configuration of SDIO slave mode.
Values:
SDIO_SLAVE_SEND_STREAM = 0
Stream mode, all packets to send will be combined as one if possible.
SDIO_SLAVE_SEND_PACKET = 1
Packet mode, one packets will be sent one after another (only increase packet_len if last packet sent).
Header File
• components/driver/include/driver/sdio_slave.h
Functions
esp_err_t sdio_slave_initialize(sdio_slave_config_t *config)
Initialize the sdio slave driver
Return
• ESP_ERR_NOT_FOUND if no free interrupt found.
• ESP_ERR_INVALID_STATE if already initialized.
• ESP_ERR_NO_MEM if fail due to memory allocation failed.
Parameters
• config: Configuration of the sdio slave driver.
void sdio_slave_deinit(void)
De-initialize the sdio slave driver to release the resources.
esp_err_t sdio_slave_start(void)
Start hardware for sending and receiving, as well as set the IOREADY1 to 1.
Note The driver will continue sending from previous data and PKT_LEN counting, keep data received as well
as start receiving from current TOKEN1 counting. See sdio_slave_reset.

Return
• ESP_ERR_INVALID_STATE if already started.
• ESP_OK otherwise.
void sdio_slave_stop(void)
Stop hardware from sending and receiving, also set IOREADY1 to 0.
Note this will not clear the data already in the driver, and also not reset the PKT_LEN and TOKEN1 counting.
Call sdio_slave_reset to do that.
esp_err_t sdio_slave_reset(void)
Clear the data still in the driver, as well as reset the PKT_LEN and TOKEN1 counting.
Return always return ESP_OK.
sdio_slave_buf_handle_t sdio_slave_recv_register_buf(uint8_t *start)
Register buffer used for receiving. All buffers should be registered before used, and then can be used (again)
in the driver by the handle returned.
Note The driver will use and only use the amount of space specified in the recv_buffer_size member
set in the sdio_slave_config_t. All buffers should be larger than that. The buffer is used by the
DMA, so it should be DMA capable and 32-bit aligned.
Return The buffer handle if success, otherwise NULL.
Parameters
• start: The start address of the buffer.
esp_err_t sdio_slave_recv_unregister_buf(sdio_slave_buf_handle_t handle)
Unregister buffer from driver, and free the space used by the descriptor pointing to the buffer.
Return ESP_OK if success, ESP_ERR_INVALID_ARG if the handle is NULL or the buffer is being used.
Parameters
• handle: Handle to the buffer to release.
esp_err_t sdio_slave_recv_load_buf(sdio_slave_buf_handle_t handle)
Load buffer to the queue waiting to receive data. The driver takes ownership of the buffer until the buffer is
returned by sdio_slave_send_get_finished after the transaction is finished.
Return
• ESP_ERR_INVALID_ARG if invalid handle or the buffer is already in the queue. Only after the
buffer is returened by sdio_slave_recv can you load it again.
Parameters
• handle: Handle to the buffer ready to receive data.
esp_err_t sdio_slave_recv_packet(sdio_slave_buf_handle_t *handle_ret, TickType_t wait)
Get buffer of received data if exist with packet information. The driver returns the ownership of the buffer to
the app.
When you see return value is ESP_ERR_NOT_FINISHED, you should call this API iteratively until the return
value is ESP_OK. All the continuous buffers returned with ESP_ERR_NOT_FINISHED, together with the
last buffer returned with ESP_OK, belong to one packet from the host.
You can call simpler sdio_slave_recv instead, if the host never send data longer than the Receiving
buffer size, or you don t care about the packet boundary (e.g. the data is only a byte stream).
Note Call sdio_slave_load_buf with the handle to re-load the buffer onto the link list, and receive
with the same buffer again. The address and length of the buffer got here is the same as got from
sdio_slave_get_buffer.
Return
• ESP_ERR_INVALID_ARG if handle_ret is NULL
• ESP_ERR_TIMEOUT if timeout before receiving new data
• ESP_ERR_NOT_FINISHED if returned buffer is not the end of a packet from the host, should call
this API again until the end of a packet
Parameters

• handle_ret: Handle of the buffer holding received data. Use this handle in
sdio_slave_recv_load_buf() to receive in the same buffer again.
• wait: Time to wait before data received.
esp_err_t sdio_slave_recv(sdio_slave_buf_handle_t *handle_ret, uint8_t **out_addr, size_t *out_len,
TickType_t wait)
Get received data if exist. The driver returns the ownership of the buffer to the app.
Note Call sdio_slave_load_buf with the handle to re-load the buffer onto the link list, and receive
with the same buffer again. The address and length of the buffer got here is the same as got from
sdio_slave_get_buffer.
Return
• ESP_ERR_INVALID_ARG if handle_ret is NULL
• ESP_ERR_TIMEOUT if timeout before receiving new data
Parameters
• handle_ret: Handle to the buffer holding received data. Use this handle in
sdio_slave_recv_load_buf to receive in the same buffer again.
• [out] out_addr: Output of the start address, set to NULL if not needed.
• [out] out_len: Actual length of the data in the buffer, set to NULL if not needed.
• wait: Time to wait before data received.
uint8_t *sdio_slave_recv_get_buf(sdio_slave_buf_handle_t handle, size_t *len_o)
Retrieve the buffer corresponding to a handle.
Return buffer address if success, otherwise NULL.
Parameters
• handle: Handle to get the buffer.
• len_o: Output of buffer length
esp_err_t sdio_slave_send_queue(uint8_t *addr, size_t len, void *arg, TickType_t wait)
Put a new sending transfer into the send queue. The driver takes ownership of the buffer until the buffer is
returned by sdio_slave_send_get_finished after the transaction is finished.
Return
• ESP_ERR_INVALID_ARG if the length is not greater than 0.
• ESP_ERR_TIMEOUT if the queue is still full until timeout.
• ESP_OK if success.
Parameters
• addr: Address for data to be sent. The buffer should be DMA capable and 32-bit aligned.
• len: Length of the data, should not be longer than 4092 bytes (may support longer in the future).
• arg: Argument to returned in sdio_slave_send_get_finished. The argument can be
used to indicate which transaction is done, or as a parameter for a callback. Set to NULL if not
needed.
• wait: Time to wait if the buffer is full.
esp_err_t sdio_slave_send_get_finished(void **out_arg, TickType_t wait)
Return the ownership of a finished transaction.
Return ESP_ERR_TIMEOUT if no transaction finished, or ESP_OK if succeed.
Parameters
• out_arg: Argument of the finished transaction. Set to NULL if unused.
• wait: Time to wait if there s no finished sending transaction.
esp_err_t sdio_slave_transmit(uint8_t *addr, size_t len)
Start a new sending transfer, and wait for it (blocked) to be finished.
Return
• ESP_ERR_INVALID_ARG if the length of descriptor is not greater than 0.
• ESP_ERR_TIMEOUT if the queue is full or host do not start a transfer before timeout.
• ESP_OK if success.
Parameters
• addr: Start address of the buffer to send

• len: Length of buffer to send.

uint8_t sdio_slave_read_reg(int pos)
Read the spi slave register shared with host.
Note register 28 to 31 are reserved for interrupt vector.
Return value of the register.
Parameters
• pos: register address, 0-27 or 32-63.
esp_err_t sdio_slave_write_reg(int pos, uint8_t reg)
Write the spi slave register shared with host.
Note register 29 and 31 are used for interrupt vector.
Return ESP_ERR_INVALID_ARG if address wrong, otherwise ESP_OK.
Parameters
• pos: register address, 0-11, 14-15, 18-19, 24-27 and 32-63, other address are reserved.
• reg: the value to write.
sdio_slave_hostint_t sdio_slave_get_host_intena(void)
Get the interrupt enable for host.
Return the interrupt mask.
void sdio_slave_set_host_intena(sdio_slave_hostint_t mask)
Set the interrupt enable for host.
Parameters
• mask: Enable mask for host interrupt.
esp_err_t sdio_slave_send_host_int(uint8_t pos)
Interrupt the host by general purpose interrupt.
Return
• ESP_ERR_INVALID_ARG if interrupt num error
• ESP_OK otherwise
Parameters
• pos: Interrupt num, 0-7.
void sdio_slave_clear_host_int(sdio_slave_hostint_t mask)
Clear general purpose interrupt to host.
Parameters
• mask: Interrupt bits to clear, by bit mask.
esp_err_t sdio_slave_wait_int(int pos, TickType_t wait)
Wait for general purpose interrupt from host.
Note this clears the interrupt at the same time.
Return ESP_OK if success, ESP_ERR_TIMEOUT if timeout.
Parameters
• pos: Interrupt source number to wait for. is set.
• wait: Time to wait before interrupt triggered.
Structures
struct sdio_slave_config_t
Configuration of SDIO slave.
Public Members
sdio_slave_timing_t timing
timing of sdio_slave. see sdio_slave_timing_t.

sdio_slave_sending_mode_t sending_mode
mode of sdio_slave. SDIO_SLAVE_MODE_STREAM if the data needs to be sent as much as possible;
SDIO_SLAVE_MODE_PACKET if the data should be sent in packets.
int send_queue_size
max buffers that can be queued before sending.
size_t recv_buffer_size
If buffer_size is too small, it costs more CPU time to handle larger number of buffers. If buffer_size is
too large, the space larger than the transaction length is left blank but still counts a buffer, and the buffers
are easily run out. Should be set according to length of data really transferred. All data that do not fully
fill a buffer is still counted as one buffer. E.g. 10 bytes data costs 2 buffers if the size is 8 bytes per
buffer. Buffer size of the slave pre-defined between host and slave before communication. All receive
buffer given to the driver should be larger than this.
sdio_event_cb_t event_cb
when the host interrupts slave, this callback will be called with interrupt number (0-7).
uint32_t flags
Features to be enabled for the slave, combinations of SDIO_SLAVE_FLAG_*.
Macros
SDIO_SLAVE_RECV_MAX_BUFFER
SDIO_SLAVE_FLAG_DAT2_DISABLED
It is required by the SD specification that all 4 data lines should be used and pulled up even in 1-bit mode or
SPI mode. However, as a feature, the user can specify this flag to make use of DAT2 pin in 1-bit mode. Note
that the host cannot read CCCR registers to know we don t support 4-bit mode anymore, please do this at
your own risk.
SDIO_SLAVE_FLAG_HOST_INTR_DISABLED
The DAT1 line is used as the interrupt line in SDIO protocol. However, as a feature, the user can specify this
flag to make use of DAT1 pin of the slave in 1-bit mode. Note that the host has to do polling to the interrupt
registers to know whether there are interrupts from the slave. And it cannot read CCCR registers to know we
don t support 4-bit mode anymore, please do this at your own risk.
SDIO_SLAVE_FLAG_INTERNAL_PULLUP
Enable internal pullups for enabled pins. It is required by the SD specification that all the 4 data lines should
be pulled up even in 1-bit mode or SPI mode. Note that the internal pull-ups are not sufficient for stable
communication, please do connect external pull-ups on the bus. This is only for example and debug use.
Type Definitions
typedef void (*sdio_event_cb_t)(uint8_t event)
typedef void *sdio_slave_buf_handle_t
Handle of a receive buffer, register a handle by calling sdio_slave_recv_register_buf. Use the
handle to load the buffer to the driver, or call sdio_slave_recv_unregister_buf if it is no longer
used.
2.3.16 Sigma-delta Modulation
Introduction
ESP32 has a second-order sigma-delta modulation module. This driver configures the channels of the sigma-delta
module.
There are 8 independent sigma-delta modulation channels identified with sigmadelta_channel_t. Each chan-
nel is capable to output the binary, hardware generated signal with the sigma-delta modulation.

Selected channel should be set up by providing configuration parameters in sigmadelta_config_t and then
applying this configuration with sigmadelta_config().
Another option is to call individual functions, that will configure all required parameters one by one:
• Prescaler of the sigma-delta generator - sigmadelta_set_prescale()
• Duty of the output signal - sigmadelta_set_duty()
• GPIO pin to output modulated signal - sigmadelta_set_pin()
The range of the duty input parameter of sigmadelta_set_duty() is from -128 to 127 (eight bit
signed integer). If zero value is set, then the output signal s duty will be about 50%, see description of sig-
madelta_set_duty().
Convert to analog signal (Optional)
Typically, if the sigma-delta signal is connected to an LED, you don t have to add any filter between them (because
our eyes are a low pass filter naturally). However, if you want to check the real voltage or watch the analog waveform,
you need to design an analog low pass filter. Also, it is recommended to use an active filter instead of a passive filter
to gain better isolation and not lose too much voltage.
For example, you can take the following Sallen-Key topology Low Pass Filter as a reference.
Fig. 19: Sallen-Key Low Pass Filter
Application Example
Sigma-delta Modulation example: peripherals/sigmadelta.
API Reference
Header File
• components/driver/include/driver/sigmadelta.h

Functions
esp_err_t sigmadelta_config(const sigmadelta_config_t *config)
Configure Sigma-delta channel.
Return
• ESP_OK Success
• ESP_ERR_INVALID_STATE sigmadelta driver already initialized
Parameters
• config: Pointer of Sigma-delta channel configuration struct
esp_err_t sigmadelta_set_duty(sigmadelta_channel_t channel, int8_t duty)
Set Sigma-delta channel duty.
This function is used to set Sigma-delta channel duty, If you add a capacitor between the output pin and ground,
the average output voltage will be Vdc = VDDIO / 256 * duty + VDDIO/2, where VDDIO is the power supply
voltage.
Return
• ESP_OK Success
• ESP_ERR_INVALID_STATE sigmadelta driver has not been initialized
Parameters
• channel: Sigma-delta channel number
• duty: Sigma-delta duty of one channel, the value ranges from -128 to 127, recommended range is
-90 ~ 90. The waveform is more like a random one in this range.
esp_err_t sigmadelta_set_prescale(sigmadelta_channel_t channel, uint8_t prescale)
Set Sigma-delta channel s clock pre-scale value. The source clock is APP_CLK, 80MHz. The clock frequency
of the sigma-delta channel is APP_CLK / pre_scale.
Return
• ESP_OK Success
Parameters
• prescale: The divider of source clock, ranges from 0 to 255
esp_err_t sigmadelta_set_pin(sigmadelta_channel_t channel, gpio_num_t gpio_num)
Set Sigma-delta signal output pin.
Return
• ESP_OK Success
Parameters
• gpio_num: GPIO number of output pin.
Header File
• components/hal/include/hal/sigmadelta_types.h
Structures
struct sigmadelta_config_t
Sigma-delta configure struct.

Public Members
sigmadelta_channel_t channel
Sigma-delta channel number
int8_t sigmadelta_duty
Sigma-delta duty, duty ranges from -128 to 127.
uint8_t sigmadelta_prescale
Sigma-delta prescale, prescale ranges from 0 to 255.
uint8_t sigmadelta_gpio
Sigma-delta output io number, refer to gpio.h for more details.
Enumerations
enum sigmadelta_port_t
SIGMADELTA port number, the max port number is (SIGMADELTA_NUM_MAX -1).
Values:
SIGMADELTA_PORT_0
SIGMADELTA port 0
SIGMADELTA_PORT_MAX
SIGMADELTA port max
enum sigmadelta_channel_t
Sigma-delta channel list.
Values:
SIGMADELTA_CHANNEL_0
Sigma-delta channel 0
SIGMADELTA_CHANNEL_MAX
Sigma-delta channel max
2.3.17 SPI Master Driver
SPI Master driver is a program that controls ESP32 s SPI peripherals while they function as masters.

Overview of ESP32 s SPI peripherals
ESP32 integrates 4 SPI peripherals.

• SPI0 and SPI1 are used internally to access the ESP32 s attached flash memory. Both controllers share the
same SPI bus signals, and there is an arbiter to determine which can access the bus.
There are quite a few limitations when using SPI Master driver on the SPI1 bus, see Notes on Using the SPI
Master driver on SPI1 Bus.
• SPI2 and SPI3 are general purpose SPI controllers, sometimes referred to as HSPI and VSPI, respectively.
They are open to users. SPI2 and SPI3 have independent bus signals with the same respective names. Each
bus has three CS lines to drive up to same number of SPI slaves.
Terminology
The terms used in relation to the SPI master driver are given in the table below.
Term Definition
Host The SPI controller peripheral inside ESP32 that initiates SPI transmissions over the bus, and acts as an SPI
Master.
De- SPI slave device. An SPI bus may be connected to one or more Devices. Each Device shares the MOSI,
vice MISO and SCLK signals but is only active on the bus when the Host asserts the Device s individual CS
line.
Bus A signal bus, common to all Devices connected to one Host. In general, a bus includes the following lines:
MISO, MOSI, SCLK, one or more CS lines, and, optionally, QUADWP and QUADHD. So Devices are
connected to the same lines, with the exception that each Device has its own CS line. Several Devices can
also share one CS line if connected in the daisy-chain manner.
MOSIMaster Out, Slave In, a.k.a. D. Data transmission from a Host to Device. Also data0 signal in Octal/OPI
mode.
MISOMaster In, Slave Out, a.k.a. Q. Data transmission from a Device to Host. Also data1 signal in Octal/OPI
mode.
SCLKSerial Clock. Oscillating signal generated by a Host that keeps the transmission of data bits in sync.
CS Chip Select. Allows a Host to select individual Device(s) connected to the bus in order to send or receive
data.
QUADWP Write Protect signal. Used for 4-bit (qio/qout) transactions. Also for data2 signal in Octal/OPI mode.
QUADHD Hold signal. Used for 4-bit (qio/qout) transactions. Also for data3 signal in Octal/OPI mode.
DATA4Data4 signal in Octal/OPI mode.
As- The action of activating a line.
ser-
tion
De- The action of returning the line back to inactive (back to idle) status.
assertion
Trans-One instance of a Host asserting a CS line, transferring data to and from a Device, and de-asserting the CS
ac- line. Transactions are atomic, which means they can never be interrupted by another transaction.
tion
LaunchEdge of the clock at which the source register launches the signal onto the line.
edge
Latch Edge of the clock at which the destination register latches in the signal.
edge
Driver Features
The SPI master driver governs communications of Hosts with Devices. The driver supports the following features:

• Multi-threaded environments
• Transparent handling of DMA transfers while reading and writing data
• Automatic time-division multiplexing of data coming from different Devices on the same signal bus, see SPI
Bus Lock.
Warning: The SPI master driver has the concept of multiple Devices connected to a single bus (sharing a single
ESP32 SPI peripheral). As long as each Device is accessed by only one task, the driver is thread safe. However,
if multiple tasks try to access the same SPI Device, the driver is not thread-safe. In this case, it is recommended
to either:
• Refactor your application so that each SPI peripheral is only accessed by a single task at a time.
• Add a mutex lock around the shared Device using xSemaphoreCreateMutex.
SPI Features
SPI Master
SPI Bus Lock To realize the multiplexing of different devices from different drivers (SPI Master, SPI Flash, etc.),
an SPI bus lock is applied on each SPI bus. Drivers can attach their devices onto the bus with the arbitration of the
lock.
Each bus lock are initialized with a BG (background) service registered, all devices request to do transactions on the
bus should wait until the BG to be successfully disabled.
• For SPI1 bus, the BG is the cache, the bus lock will help to disable the cache before device operations starts,
and enable it again after device releasing the lock. No devices on SPI1 is allowed using ISR (it s meaningless
for the task to yield to other tasks when the cache is disabled).
There are quite a few limitations when using SPI Master driver on the SPI1 bus, see Notes on Using the SPI
Master driver on SPI1 Bus.
• For other buses, the driver may register its ISR as the BG. The bus lock will block a device task when it requests
for exclusive use of the bus, try to disable the ISR, and unblock the device task allowed to exclusively use the
bus when the ISR is successfully disabled. When the task releases the lock, the lock will also try to resume the
ISR if there are pending transactions to be done in the ISR.
SPI Transactions
An SPI bus transaction consists of five phases which can be found in the table below. Any of these phases can be
skipped.
Phase Description
Com- In this phase, a command (0-16 bit) is written to the bus by the Host.
mand
Ad- In this phase, an address (0-64 bit) is transmitted over the bus by the Host.
dress
Write Host sends data to a Device. This data follows the optional command and address phases and is indis-
tinguishable from them at the electrical level.
Dummy This phase is configurable and is used to meet the timing requirements.
Read Device sends data to its Host.
The attributes of a transaction are determined by the bus configuration structure spi_bus_config_t, de-
vice configuration structure spi_device_interface_config_t, and transaction configuration structure
spi_transaction_t.
An SPI Host can send full-duplex transactions, during which the read and write phases occur simultaneously. The
total transaction length is determined by the sum of the following members:

• spi_device_interface_config_t::command_bits
• spi_device_interface_config_t::address_bits
• spi_transaction_t::length
While the member spi_transaction_t::rxlength only determines the length of data received into the
buffer.
In half-duplex transactions, the read and write phases are not simultaneous (one direction at a time). The lengths of the
write and read phases are determined by length and rxlength members of the struct spi_transaction_t
respectively.
The command and address phases are optional, as not every SPI device requires a command and/or address. This is
reflected in the Device s configuration: if command_bits and/or address_bits are set to zero, no command
or address phase will occur.
The read and write phases can also be optional, as not every transaction requires both writing and reading data. If
rx_buffer is NULL and SPI_TRANS_USE_RXDATA is not set, the read phase is skipped. If tx_buffer is
NULL and SPI_TRANS_USE_TXDATA is not set, the write phase is skipped.
The driver supports two types of transactions: the interrupt transactions and polling transactions. The programmer
can choose to use a different transaction type per Device. If your Device requires both transaction types, see Notes
on Sending Mixed Transactions to the Same Device.
Interrupt Transactions Interrupt transactions will block the transaction routine until the transaction completes,
thus allowing the CPU to run other tasks.
An application task can queue multiple transactions, and the driver will automatically handle them one-by-one in the
interrupt service routine (ISR). It allows the task to switch to other procedures until all the transactions complete.
Polling Transactions Polling transactions do not use interrupts. The routine keeps polling the SPI Host s status
bit until the transaction is finished.
All the tasks that use interrupt transactions can be blocked by the queue. At this point, they will need to wait for the
ISR to run twice before the transaction is finished. Polling transactions save time otherwise spent on queue handling
and context switching, which results in smaller transaction duration. The disadvantage is that the CPU is busy while
these transactions are in progress.
The spi_device_polling_end() routine needs an overhead of at least 1 us to unblock other tasks when
the transaction is finished. It is strongly recommended to wrap a series of polling transactions using the functions
spi_device_acquire_bus() and spi_device_release_bus() to avoid the overhead. For more in-
formation, see Bus Acquiring.
Transaction Line Mode Supported line modes for ESP32 are listed as follows, to make use of these modes, set
the member flags in the struct spi_transaction_t as shown in the Transaction Flag column. If you want to
check if corresponding IO pins are set or not, set the member flags in the spi_bus_config_t as shown in the
Bus IO setting Flag column.

Mode Command Address Data Transaction Flag Bus IO setting

name Line Width Line Width Line Flag
Width
Nor- 1 1 1 0 0
mal
SPI
Dual 1 1 2 SPI_TRANS_MODE_DIO SPICOM-
Output MON_BUSFLAG_DUAL
Dual 1 2 2 SPI_TRANS_MODE_DIO |
I/O SPI_TRANS_MULTILINE_ADDR
Quad 1 1 4 SPI_TRANS_MODE_QIO SPICOMMON_BUSFLAG_QUAD
Output
Quad 1 4 4 SPI_TRANS_MODE_QIO |
I/O SPI_TRANS_MULTILINE_ADDR
Command and Address Phases During the command and address phases, the members cmd and addr in the
struct spi_transaction_t are sent to the bus, nothing is read at this time. The default lengths of the command
and address phases are set in spi_device_interface_config_t by calling spi_bus_add_device().
If the flags SPI_TRANS_VARIABLE_CMD and SPI_TRANS_VARIABLE_ADDR in the member
spi_transaction_t::flags are not set, the driver automatically sets the length of these phases to
default values during Device initialization.
If the lengths of the command and address phases need to be variable, declare the
struct spi_transaction_ext_t, set the flags SPI_TRANS_VARIABLE_CMD and/or
SPI_TRANS_VARIABLE_ADDR in the member spi_transaction_ext_t::base and configure the
rest of base as usual. Then the length of each phase will be equal to command_bits and address_bits set in
the struct spi_transaction_ext_t.
If the command and address phase need to be as the same number of lines as data phase, you need to
set SPI_TRANS_MULTILINE_CMD and/or SPI_TRANS_MULTILINE_ADDR to the flags member in the struct
spi_transaction_t. Also see Transaction Line Mode.
Write and Read Phases Normally, the data that needs to be transferred to or from a Device will be read from
or written to a chunk of memory indicated by the members rx_buffer and tx_buffer of the structure
spi_transaction_t. If DMA is enabled for transfers, the buffers are required to be:
1. Allocated in DMA-capable internal memory. If external PSRAM is enabled, this means using pvPortMal-
locCaps(size, MALLOC_CAP_DMA).
2. 32-bit aligned (staring from a 32-bit boundary and having a length of multiples of 4 bytes).
If these requirements are not satisfied, the transaction efficiency will be affected due to the allocation and copying of
temporary buffers.
If using more than one data lines to transmit, please set SPI_DEVICE_HALFDUPLEX flag for the member flags in the
struct spi_device_interface_config_t. And the member flags in the struct spi_transaction_t
should be set as described in Transaction Line Mode.
Note: Half-duplex transactions with both read and write phases are not supported when using DMA. For details and
workarounds, see Known Issues.
Bus Acquiring Sometimes you might want to send SPI transactions exclusively and continuously so that it
takes as little time as possible. For this, you can use bus acquiring, which helps to suspend transactions (both
polling or interrupt) to other devices until the bus is released. To acquire and release a bus, use the functions
spi_device_acquire_bus() and spi_device_release_bus().

Driver Usage
• Initialize an SPI bus by calling the function spi_bus_initialize(). Make sure to set the correct I/O
pins in the struct spi_bus_config_t. Set the signals that are not needed to -1.
• Register a Device connected to the bus with the driver by calling the function spi_bus_add_device().
Make sure to configure any timing requirements the device might need with the parameter dev_config.
You should now have obtained the Device s handle which will be used when sending a transaction to it.
• To interact with the Device, fill one or more spi_transaction_t structs with any transaction parameters
required. Then send the structs either using a polling transaction or an interrupt transaction:
– Interrupt Either queue all transactions by calling the function spi_device_queue_trans() and,
at a later time, query the result using the function spi_device_get_trans_result(), or
handle all requests synchronously by feeding them into spi_device_transmit().
– Polling Call the function spi_device_polling_transmit() to send polling transactions.
Alternatively, if you want to insert something in between, send the transactions by using
spi_device_polling_start() and spi_device_polling_end().
• (Optional) To perform back-to-back transactions with a Device, call the function
spi_device_acquire_bus() before sending transactions and spi_device_release_bus()
after the transactions have been sent.
• (Optional) To unload the driver for a certain Device, call spi_bus_remove_device() with the Device
handle as an argument.
• (Optional) To remove the driver for a bus, make sure no more drivers are attached and call
spi_bus_free().
The example code for the SPI master driver can be found in the peripherals/spi_master directory of ESP-IDF exam-
ples.
Transactions with Data Not Exceeding 32 Bits When the transaction data size is equal to or less than 32 bits, it
will be sub-optimal to allocate a buffer for the data. The data can be directly stored in the transaction struct instead. For
transmitted data, it can be achieved by using the tx_data member and setting the SPI_TRANS_USE_TXDATA
flag on the transmission. For received data, use rx_data and set SPI_TRANS_USE_RXDATA. In both cases, do
not touch the tx_buffer or rx_buffer members, because they use the same memory locations as tx_data
and rx_data.
Transactions with Integers Other Than uint8_t An SPI Host reads and writes data into memory byte by byte.
By default, data is sent with the most significant bit (MSB) first, as LSB first used in rare cases. If a value less than 8
bits needs to be sent, the bits should be written into memory in the MSB first manner.
For example, if 0b00010 needs to be sent, it should be written into a uint8_t variable, and the length for reading
should be set to 5 bits. The Device will still receive 8 bits with 3 additional random bits, so the reading must be
performed correctly.
On top of that, ESP32 is a little-endian chip, which means that the least significant byte of uint16_t and
uint32_t variables is stored at the smallest address. Hence, if uint16_t is stored in memory, bits [7:0] are
sent first, followed by bits [15:8].
For cases when the data to be transmitted has the size differing from uint8_t arrays, the following macros can be
used to transform data to the format that can be sent by the SPI driver directly:
• SPI_SWAP_DATA_TX for data to be transmitted
• SPI_SWAP_DATA_RX for data received
Notes on Sending Mixed Transactions to the Same Device To reduce coding complexity, send only one type of
transactions (interrupt or polling) to one Device. However, you still can send both interrupt and polling transactions
alternately. The notes below explain how to do this.
The polling transactions should be initiated only after all the polling and interrupt transactions are finished.
Since an unfinished polling transaction blocks other transactions, please do not forget to call the function
spi_device_polling_end() after spi_device_polling_start() to allow other transactions or to

allow other Devices to use the bus. Remember that if there is no need to switch to other tasks during your polling
transaction, you can initiate a transaction with spi_device_polling_transmit() so that it will be ended
automatically.
In-flight polling transactions are disturbed by the ISR operation to accommodate interrupt
transactions. Always make sure that all the interrupt transactions sent to the ISR are fin-
ished before you call spi_device_polling_start(). To do that, you can keep calling
spi_device_get_trans_result() until all the transactions are returned.
To have better control of the calling sequence of functions, send mixed transactions to the same Device only within
a single task.
Notes on Using the SPI Master driver on SPI1 Bus

Note: Though the SPI Bus Lock feature makes it possible to use SPI Master driver on the SPI1 bus, it s still tricky
and needs a lot of special treatment. It s a feature for advanced developers.
To use SPI Master driver on SPI1 bus, you have to take care of two problems:
1. The code and data, required at the meanwhile the driver is operating SPI1 bus, should be in the internal memory.
SPI1 bus is shared among devices and the cache for data (code) in the Flash as well as the PSRAM. The cache
should be disabled during the other drivers are operating the SPI1 bus. Hence the data (code) in the flash as
well as the PSRAM cannot be fetched at the meanwhile the driver acquires the SPI1 bus by:
• Explicit bus acquiring between spi_device_acquire_bus() and
spi_device_release_bus().
• Implicit bus acquiring between spi_device_polling_start() and
spi_device_polling_end() (or inside spi_device_polling_transmit()).
During the time above, all other tasks and most ISRs will be disabled (see IRAM-Safe Interrupt Handlers).
Application code and data used by current task should be placed in internal memory (DRAM or IRAM), or
already in the ROM. Access to external memory (flash code, const data in the flash, and static/heap data in the
PSRAM) will cause a Cache disabled but cached memory region accessed exception. For differences between
IRAM, DRAM, and flash cache, please refer to the application memory layout documentation.
To place functions into the IRAM, you can either:
1. Add IRAM_ATTR (include esp_attr.h ) to the function like:
IRAM_ATTR void foo(void) { }
Please note that when a function is inlined, it will follow its caller s segment, and the attribute will not
take effect. You may need to use NOLINE_ATTR to avoid this.
2. Use the noflash placement in the linker.lf. See more in Linker Script Generation. Please note that, some
code may be transformed into lookup table in the const data by the compiler, so noflash_text is not safe.
Please do take care that the optimization level may affect the compiler behavior of inline, or transforming some
code into lookup table in the const data, etc.
To place data into the DRAM, you can either:
1. Add DRAM_ATTR (include esp_attr.h ) to the data definition like:
DRAM_ATTR int g_foo = 3;
2. Use the noflash placement in the linker.lf. See more in Linker Script Generation.
Please also see the example peripherals/spi_master/hd_eeprom.
GPIO Matrix and IO_MUX Most of ESP32 s peripheral signals have direct connection to their dedicated
IO_MUX pins. However, the signals can also be routed to any other available pins using the less direct GPIO matrix.
If at least one signal is routed through the GPIO matrix, then all signals will be routed through it.
The GPIO matrix introduces flexibility of routing but also brings the following disadvantages:
• Increases the input delay of the MISO signal, which makes MISO setup time violations more likely. If SPI
needs to operate at high speeds, use dedicated IO_MUX pins.
• Allows signals with clock frequencies only up to 40 MHz, as opposed to 80 MHz if IO_MUX pins are used.
Note: For more details about the influence of the MISO input delay on the maximum clock frequency, see Timing

Considerations.
The IO_MUX pins for SPI buses are given below.
Pin Name SPI2 SPI3

GPIO Number
CS0* 15 5
SCLK 14 18
MISO 12 19
MOSI 13 23
QUADWP 2 22
QUADHD 4 21
• Only the first Device attached to the bus can use the CS0 pin.
Transfer Speed Considerations
There are three factors limiting the transfer speed:

• Transaction interval
• SPI clock frequency
• Cache miss of SPI functions, including callbacks
The main parameter that determines the transfer speed for large transactions is clock frequency. For multiple small
transactions, the transfer speed is mostly determined by the length of transaction intervals.
Transaction Duration Transaction duration includes setting up SPI peripheral registers, copying data to FIFOs or
setting up DMA links, and the time for SPI transaction.
Interrupt transactions allow appending extra overhead to accommodate the cost of FreeRTOS queues and the time
needed for switching between tasks and the ISR.
For interrupt transactions, the CPU can switch to other tasks when a transaction is in progress. This saves the CPU
time but increases the transaction duration. See Interrupt Transactions. For polling transactions, it does not block
the task but allows to do polling when the transaction is in progress. For more information, see Polling Transactions.
If DMA is enabled, setting up the linked list requires about 2 us per transaction. When a master is transferring data,
it automatically reads the data from the linked list. If DMA is not enabled, the CPU has to write and read each byte
from the FIFO by itself. Usually, this is faster than 2 us, but the transaction length is limited to 64 bytes for both
write and read.
Typical transaction duration for one byte of data are given below.
• Interrupt Transaction via DMA: 28 µs.
• Interrupt Transaction via CPU: 25 µs.
• Polling Transaction via DMA: 10 µs.
• Polling Transaction via CPU: 8 µs.
SPI Clock Frequency Transferring each byte takes eight times the clock period 8/fspi.
If the clock frequency is too high, the use of some functions might be limited. See Timing Considerations.
Cache Miss The default config puts only the ISR into the IRAM. Other SPI related functions, including the driver
itself and the callback, might suffer from cache misses and will need to wait until the code is read from flash. Select
CONFIG_SPI_MASTER_IN_IRAM to put the whole SPI driver into IRAM and put the entire callback(s) and its callee
functions into IRAM to prevent cache misses.

For an interrupt transaction, the overall cost is 20+8n/Fspi[MHz] [us] for n bytes transferred in one transaction.
Hence, the transferring speed is: n/(20+8n/Fspi). An example of transferring speed at 8 MHz clock speed is given
in the following table.
Frequency Transaction Interval Transaction Length Total Time Total Speed

(MHz) (us) (bytes) (us) (KBps)
8 25 1 26 38.5
8 25 8 33 242.4
8 25 16 41 490.2
8 25 64 89 719.1
8 25 128 153 836.6
When a transaction length is short, the cost of transaction interval is high. If possible, try to squash several short
transactions into one transaction to achieve a higher transfer speed.
Please note that the ISR is disabled during flash operation by default. To keep sending transactions during
flash operations, enable CONFIG_SPI_MASTER_ISR_IN_IRAM and set ESP_INTR_FLAG_IRAM in the member
spi_bus_config_t::intr_flags. In this case, all the transactions queued before starting flash operations
will be handled by the ISR in parallel. Also note that the callback of each Device and their callee functions should
be in IRAM, or your callback will crash due to cache miss. For more details, see IRAM-Safe Interrupt Handlers.
Timing Considerations
As shown in the figure below, there is a delay on the MISO line after the SCLK launch edge and before the signal is
latched by the internal register. As a result, the MISO pin setup time is the limiting factor for the SPI clock speed.
When the delay is too long, the setup slack is < 0, which means the setup timing requirement is violated and the
reading might be incorrect.
The maximum allowed frequency is dependent on:

• input_delay_ns - maximum data valid time on the MISO bus after a clock cycle on SCLK starts
• If the IO_MUX pin or the GPIO Matrix is used
When the GPIO matrix is used, the maximum allowed frequency is reduced to about 33~77% in comparison to the
existing input delay. To retain a higher frequency, you have to use the IO_MUX pins or the dummy bit workaround.
You can obtain the maximum reading frequency of the master by using the function spi_get_freq_limit().

Dummy bit workaround: Dummy clocks, during which the Host does not read data, can be inserted before the read
phase begins. The Device still sees the dummy clocks and sends out data, but the Host does not read until the read
phase comes. This compensates for the lack of the MISO setup time required by the Host and allows the Host to do
reading at a higher frequency.
In the ideal case, if the Device is so fast that the input delay is shorter than an APB clock cycle - 12.5 ns - the
maximum frequency at which the Host can read (or read and write) in different conditions is as follows:
Frequency Limit (MHz) Dummy Bits Used By Driver Comments

GPIO matrix IO_MUX pins
26.6 80 No
40 Yes Half-duplex, no DMA allowed
If the Host only writes data, the dummy bit workaround and the frequency check can be disabled by setting the bit
SPI_DEVICE_NO_DUMMY in the member spi_device_interface_config_t::flags. When disabled,
the output frequency can be 80MHz, even if the GPIO matrix is used.
spi_device_interface_config_t::flags
The SPI master driver still works even if the input_delay_ns in the structure
spi_device_interface_config_t is set to 0. However, setting an accurate value helps to:
• Calculate the frequency limit for full-duplex transactions
• Compensate the timing correctly with dummy bits for half-duplex transactions
You can approximate the maximum data valid time after the launch edge of SPI clocks by checking the statistics in
the AC characteristics chapter of your Device s specification or measure the time using an oscilloscope or logic
analyzer.
Please note that the actual PCB layout design and excessive loads may increase the input delay. It means that non-
optimal wiring and/or a load capacitor on the bus will most likely lead to input delay values exceeding the values
given in the Device specification or measured while the bus is floating.
Some typical delay values are shown in the following table. (These data are retrieved when the slave device is on a
different physical chip)
Device Input delay (ns)

Ideal Device 0
ESP32 slave using IO_MUX* 50
ESP32 slave using GPIO_MUX* 75
The MISO path delay (valid time) consists of a slave s input delay plus master s GPIO matrix delay. This delay
determines the frequency limit above which full-duplex transfers will not work as well as the dummy bits used in the
half-duplex transactions. The frequency limit is:
Freq limit [MHz] = 80 / (floor(MISO delay[ns]/12.5) + 1)
The figure below shows the relationship between frequency limit and input delay. Two extra APB clock cycle periods
should be added to the MISO delay if the master uses the GPIO matrix.

Corresponding frequency limits for different Devices with different input delay times are shown in the table below.
Master Input delay (ns) MISO path delay (ns) Freq. limit (MHz)
IO_MUX (0ns) 0 0 80
50 50 16
75 75 11.43
GPIO (25ns) 0 25 26.67
50 75 11.43
75 100 8.89
Known Issues
1. Half-duplex transactions are not compatible with DMA when both writing and reading phases are used.
If such transactions are required, you have to use one of the alternative solutions:
1. Use full-duplex transactions instead.
2. Disable DMA by setting the bus initialization function s last parameter to 0 as follows:
ret=spi_bus_initialize(VSPI_HOST, &buscfg, 0);
This can prohibit you from transmitting and receiving data longer than 64 bytes. 3. Try using the
command and address fields to replace the write phase.
2. Full-duplex transactions are not compatible with the dummy bit workaround, hence the frequency is limited.
See dummy bit speed-up workaround.
3. dummy_bits in spi_device_interface_config_t and spi_transaction_ext_t are not
available when SPI read and write phases are both enabled (regardless of full duplex or half duplex mode).
4. cs_ena_pretrans is not compatible with the command and address phases of full-duplex transactions.

Application Example
The code example for using the SPI master half duplex mode to read/write a AT93C46D EEPROM (8-bit mode)
can be found in the peripherals/spi_master/hd_eeprom directory of ESP-IDF examples.
API Reference - SPI Common
Header File
• components/hal/include/hal/spi_types.h
Structures
struct spi_line_mode_t
Line mode of SPI transaction phases: CMD, ADDR, DOUT/DIN.
Public Members
uint8_t cmd_lines
The line width of command phase, e.g. 2-line-cmd-phase.
uint8_t addr_lines
The line width of address phase, e.g. 1-line-addr-phase.
uint8_t data_lines
The line width of data phase, e.g. 4-line-data-phase.
Enumerations
enum spi_host_device_t
Enum with the three SPI peripherals that are software-accessible in it.
Values:
SPI1_HOST = 0
SPI1.
SPI2_HOST = 1
SPI2.
SPI3_HOST = 2
SPI3.
SPI_HOST_MAX
invalid host value
enum spi_event_t
SPI Events.
Values:
SPI_EV_BUF_TX = BIT(0)
The buffer has sent data to master.
SPI_EV_BUF_RX = BIT(1)
The buffer has received data from master.
SPI_EV_SEND_DMA_READY = BIT(2)
Slave has loaded its TX data buffer to the hardware (DMA).
SPI_EV_SEND = BIT(3)
Master has received certain number of the data, the number is determined by Master.
SPI_EV_RECV_DMA_READY = BIT(4)
Slave has loaded its RX data buffer to the hardware (DMA).

SPI_EV_RECV = BIT(5)
Slave has received certain number of data from master, the number is determined by Master.
SPI_EV_CMD9 = BIT(6)
Received CMD9 from master.
SPI_EV_CMDA = BIT(7)
Received CMDA from master.
SPI_EV_TRANS = BIT(8)
A transaction has done.
Header File
• components/driver/include/driver/spi_common.h
Functions
esp_err_t spi_bus_initialize(spi_host_device_t host_id, const spi_bus_config_t *bus_config,
spi_dma_chan_t dma_chan)
Initialize a SPI bus.
Warning SPI0/1 is not supported
Warning If a DMA channel is selected, any transmit and receive buffer used should be allocated in DMA-
capable memory.
Warning The ISR of SPI is always executed on the core which calls this function. Never starve the ISR on
this core or the SPI transactions will not be handled.
Return
• ESP_ERR_INVALID_ARG if configuration is invalid
• ESP_ERR_INVALID_STATE if host already is in use
• ESP_ERR_NOT_FOUND if there is no available DMA channel
Parameters
• host_id: SPI peripheral that controls this bus
• bus_config: Pointer to a spi_bus_config_t struct specifying how the host should be initialized
• dma_chan: - Selecting a DMA channel for an SPI bus allows transactions on the bus with size only
limited by the amount of internal memory.
– Selecting SPI_DMA_DISABLED limits the size of transactions.
– Set to SPI_DMA_DISABLED if only the SPI flash uses this bus.
– Set to SPI_DMA_CH_AUTO to let the driver to allocate the DMA channel.
esp_err_t spi_bus_free(spi_host_device_t host_id)
Free a SPI bus.
Warning In order for this to succeed, all devices have to be removed first.
Return
• ESP_ERR_INVALID_STATE if not all devices on the bus are freed
Parameters
• host_id: SPI peripheral to free
Structures
struct spi_bus_config_t
This is a configuration structure for a SPI bus.
You can use this structure to specify the GPIO pins of the bus. Normally, the driver will use the GPIO matrix
to route the signals. An exception is made when all signals either can be routed through the IO_MUX or are
-1. In that case, the IO_MUX is used, allowing for >40MHz speeds.

Note Be advised that the slave driver does not use the quadwp/quadhd lines and fields in spi_bus_config_t
refering to these lines will be ignored and can thus safely be left uninitialized.
Public Members
int mosi_io_num
GPIO pin for Master Out Slave In (=spi_d) signal, or -1 if not used.
int data0_io_num
GPIO pin for spi data0 signal in quad/octal mode, or -1 if not used.
int miso_io_num
GPIO pin for Master In Slave Out (=spi_q) signal, or -1 if not used.
int data1_io_num
int sclk_io_num
GPIO pin for SPI Clock signal, or -1 if not used.
int quadwp_io_num
GPIO pin for WP (Write Protect) signal, or -1 if not used.
int data2_io_num
int quadhd_io_num
GPIO pin for HD (Hold) signal, or -1 if not used.
int data3_io_num
int data4_io_num
GPIO pin for spi data4 signal in octal mode, or -1 if not used.
int data5_io_num
int data6_io_num
int data7_io_num
int max_transfer_sz
Maximum transfer size, in bytes. Defaults to 4092 if 0 when DMA enabled, or to
SOC_SPI_MAXIMUM_BUFFER_SIZE if DMA is disabled.
uint32_t flags
Abilities of bus to be checked by the driver. Or-ed value of SPICOMMON_BUSFLAG_* flags.
int intr_flags
Interrupt flag for the bus to set the priority, and IRAM attribute, see esp_intr_alloc.h. Note that
the EDGE, INTRDISABLED attribute are ignored by the driver. Note that if ESP_INTR_FLAG_IRAM
is set, ALL the callbacks of the driver, and their callee functions, should be put in the IRAM.
Macros
SPI_MAX_DMA_LEN
SPI_SWAP_DATA_TX(DATA, LEN)
Transform unsigned integer of length <= 32 bits to the format which can be sent by the SPI driver directly.
E.g. to send 9 bits of data, you can:
uint16_t data = SPI_SWAP_DATA_TX(0x145, 9);

Then points tx_buffer to &data.

Parameters
• DATA: Data to be sent, can be uint8_t, uint16_t or uint32_t.
• LEN: Length of data to be sent, since the SPI peripheral sends from the MSB, this helps to shift the
data to the MSB.
SPI_SWAP_DATA_RX(DATA, LEN)
Transform received data of length <= 32 bits to the format of an unsigned integer.
E.g. to transform the data of 15 bits placed in a 4-byte array to integer:
uint16_t data = SPI_SWAP_DATA_RX(*(uint32_t*)t->rx_data, 15);
Parameters
• DATA: Data to be rearranged, can be uint8_t, uint16_t or uint32_t.
• LEN: Length of data received, since the SPI peripheral writes from the MSB, this helps to shift the
data to the LSB.
SPICOMMON_BUSFLAG_SLAVE
Initialize I/O in slave mode.
SPICOMMON_BUSFLAG_MASTER
Initialize I/O in master mode.
SPICOMMON_BUSFLAG_IOMUX_PINS
Check using iomux pins. Or indicates the pins are configured through the IO mux rather than GPIO matrix.
SPICOMMON_BUSFLAG_GPIO_PINS
Force the signals to be routed through GPIO matrix. Or indicates the pins are routed through the GPIO matrix.
SPICOMMON_BUSFLAG_SCLK
Check existing of SCLK pin. Or indicates CLK line initialized.
SPICOMMON_BUSFLAG_MISO
Check existing of MISO pin. Or indicates MISO line initialized.
SPICOMMON_BUSFLAG_MOSI
Check existing of MOSI pin. Or indicates MOSI line initialized.
SPICOMMON_BUSFLAG_DUAL
Check MOSI and MISO pins can output. Or indicates bus able to work under DIO mode.
SPICOMMON_BUSFLAG_WPHD
Check existing of WP and HD pins. Or indicates WP & HD pins initialized.
SPICOMMON_BUSFLAG_QUAD
Check existing of MOSI/MISO/WP/HD pins as output. Or indicates bus able to work under QIO mode.
SPICOMMON_BUSFLAG_IO4_IO7
Check existing of IO4~IO7 pins. Or indicates IO4~IO7 pins initialized.
SPICOMMON_BUSFLAG_OCTAL
Check existing of MOSI/MISO/WP/HD/SPIIO4/SPIIO5/SPIIO6/SPIIO7 pins as output. Or indicates bus
able to work under octal mode.
SPICOMMON_BUSFLAG_NATIVE_PINS
Type Definitions
typedef spi_common_dma_t spi_dma_chan_t
Enumerations
enum spi_common_dma_t
SPI DMA channels.
Values:

SPI_DMA_DISABLED = 0
Do not enable DMA for SPI.
SPI_DMA_CH1 = 1
Enable DMA, select DMA Channel 1.
SPI_DMA_CH2 = 2
Enable DMA, select DMA Channel 2.
SPI_DMA_CH_AUTO = 3
Enable DMA, channel is automatically selected by driver.
API Reference - SPI Master
Header File
• components/driver/include/driver/spi_master.h
Functions
esp_err_t spi_bus_add_device(spi_host_device_t host_id, const spi_device_interface_config_t
*dev_config, spi_device_handle_t *handle)
Allocate a device on a SPI bus.
This initializes the internal structures for a device, plus allocates a CS pin on the indicated SPI master peripheral
and routes it to the indicated GPIO. All SPI master devices have three CS pins and can thus control up to three
devices.
Note While in general, speeds up to 80MHz on the dedicated SPI pins and 40MHz on GPIO-matrix-routed
pins are supported, full-duplex transfers routed over the GPIO matrix only support speeds up to 26MHz.
Return
• ESP_ERR_NOT_FOUND if host doesn t have any free CS slots
Parameters
• host_id: SPI peripheral to allocate device on
• dev_config: SPI interface protocol config for the device
• handle: Pointer to variable to hold the device handle
esp_err_t spi_bus_remove_device(spi_device_handle_t handle)
Remove a device from the SPI bus.
Return
• ESP_ERR_INVALID_STATE if device already is freed
Parameters
• handle: Device handle to free
esp_err_t spi_device_queue_trans(spi_device_handle_t handle, spi_transaction_t *trans_desc, Tick-
Type_t ticks_to_wait)
Queue a SPI transaction for interrupt transaction execution. Get the result by
spi_device_get_trans_result.
Note Normally a device cannot start (queue) polling and interrupt transactions simultaneously.
Return
• ESP_ERR_INVALID_ARG if parameter is invalid. This can happen if
SPI_DEVICE_CS_KEEP_LOW flag is specified while the bus was not acquired
(spi_device_acquire_bus() should be called first)
• ESP_ERR_TIMEOUT if there was no room in the queue before ticks_to_wait expired
• ESP_ERR_NO_MEM if allocating DMA-capable temporary buffer failed
• ESP_ERR_INVALID_STATE if previous transactions are not finished

Parameters
• handle: Device handle obtained using spi_host_add_dev
• trans_desc: Description of transaction to execute
• ticks_to_wait: Ticks to wait until there s room in the queue; use portMAX_DELAY to never
time out.
esp_err_t spi_device_get_trans_result(spi_device_handle_t handle, spi_transaction_t
**trans_desc, TickType_t ticks_to_wait)
Get the result of a SPI transaction queued earlier by spi_device_queue_trans.
This routine will wait until a transaction to the given device succesfully completed. It will then return the
description of the completed transaction so software can inspect the result and e.g. free the memory or re-use
the buffers.
Return
• ESP_ERR_TIMEOUT if there was no completed transaction before ticks_to_wait expired
Parameters
• trans_desc: Pointer to variable able to contain a pointer to the description of the transac-
tion that is executed. The descriptor should not be modified until the descriptor is returned by
spi_device_get_trans_result.
• ticks_to_wait: Ticks to wait until there s a returned item; use portMAX_DELAY to never
time out.
esp_err_t spi_device_transmit(spi_device_handle_t handle, spi_transaction_t *trans_desc)
Send a SPI transaction, wait for it to complete, and return the result.
This function is the equivalent of calling spi_device_queue_trans() followed by spi_device_get_trans_result().
Do not use this when there is still a transaction separately queued (started) from spi_device_queue_trans() or
polling_start/transmit that hasn t been finalized.
Note This function is not thread safe when multiple tasks access the same SPI device. Normally a device
cannot start (queue) polling and interrupt transactions simutanuously.
Return
Parameters
esp_err_t spi_device_polling_start(spi_device_handle_t handle, spi_transaction_t *trans_desc,
TickType_t ticks_to_wait)
Immediately start a polling transaction.
Note Normally a device cannot start (queue) polling and interrupt transactions simutanuously. Moreover, a
device cannot start a new polling transaction if another polling transaction is not finished.
Return
• ESP_ERR_INVALID_ARG if parameter is invalid. This can happen if
SPI_DEVICE_CS_KEEP_LOW flag is specified while the bus was not acquired
(spi_device_acquire_bus() should be called first)
• ESP_ERR_TIMEOUT if the device cannot get control of the bus before ticks_to_wait expired
• ESP_ERR_NO_MEM if allocating DMA-capable temporary buffer failed
• ESP_ERR_INVALID_STATE if previous transactions are not finished
Parameters
• ticks_to_wait: Ticks to wait until there s room in the queue; currently only port-
MAX_DELAY is supported.

esp_err_t spi_device_polling_end(spi_device_handle_t handle, TickType_t ticks_to_wait)

Poll until the polling transaction ends.
This routine will not return until the transaction to the given device has succesfully completed. The task is not
blocked, but actively busy-spins for the transaction to be completed.
Return
• ESP_ERR_TIMEOUT if the transaction cannot finish before ticks_to_wait expired
Parameters
time out.
esp_err_t spi_device_polling_transmit(spi_device_handle_t handle, spi_transaction_t
*trans_desc)
Send a polling transaction, wait for it to complete, and return the result.
This function is the equivalent of calling spi_device_polling_start() followed by spi_device_polling_end(). Do
not use this when there is still a transaction that hasn t been finalized.
Note This function is not thread safe when multiple tasks access the same SPI device. Normally a device
cannot start (queue) polling and interrupt transactions simutanuously.
Return
Parameters
esp_err_t spi_device_acquire_bus(spi_device_handle_t device, TickType_t wait)
Occupy the SPI bus for a device to do continuous transactions.
Transactions to all other devices will be put off until spi_device_release_bus is called.
Note The function will wait until all the existing transactions have been sent.
Return
• ESP_ERR_INVALID_ARG : wait is not set to portMAX_DELAY.
• ESP_OK : Success.
Parameters
• device: The device to occupy the bus.
• wait: Time to wait before the the bus is occupied by the device. Currently MUST set to port-
MAX_DELAY.
void spi_device_release_bus(spi_device_handle_t dev)
Release the SPI bus occupied by the device. All other devices can start sending transactions.
Parameters
• dev: The device to release the bus.
int spi_cal_clock(int fapb, int hz, int duty_cycle, uint32_t *reg_o)
Calculate the working frequency that is most close to desired frequency, and also the register value.
Parameters
• fapb: The frequency of apb clock, should be APB_CLK_FREQ.
• hz: Desired working frequency
• duty_cycle: Duty cycle of the spi clock
• reg_o: Output of value to be set in clock register, or NULL if not needed.
Return Actual working frequency that most fit.
int spi_get_actual_clock(int fapb, int hz, int duty_cycle)
Calculate the working frequency that is most close to desired frequency.
Return Actual working frequency that most fit.

Parameters
• fapb: The frequency of apb clock, should be APB_CLK_FREQ.
• hz: Desired working frequency
• duty_cycle: Duty cycle of the spi clock
void spi_get_timing(bool gpio_is_used, int input_delay_ns, int eff_clk, int *dummy_o, int
*cycles_remain_o)
Calculate the timing settings of specified frequency and settings.
Note If **dummy_o* is not zero, it means dummy bits should be applied in half duplex mode, and full duplex
mode may not work.
Parameters
• gpio_is_used: True if using GPIO matrix, or False if iomux pins are used.
• input_delay_ns: Input delay from SCLK launch edge to MISO data valid.
• eff_clk: Effective clock frequency (in Hz) from spi_cal_clock.
• dummy_o: Address of dummy bits used output. Set to NULL if not needed.
• cycles_remain_o: Address of cycles remaining (after dummy bits are used) output.
– -1 If too many cycles remaining, suggest to compensate half a clock.
– 0 If no remaining cycles or dummy bits are not used.
– positive value: cycles suggest to compensate.
int spi_get_freq_limit(bool gpio_is_used, int input_delay_ns)
Get the frequency limit of current configurations. SPI master working at this limit is OK, while above the limit,
full duplex mode and DMA will not work, and dummy bits will be aplied in the half duplex mode.
Return Frequency limit of current configurations.
Parameters
• gpio_is_used: True if using GPIO matrix, or False if native pins are used.
• input_delay_ns: Input delay from SCLK launch edge to MISO data valid.
Structures
struct spi_device_interface_config_t
This is a configuration for a SPI slave device that is connected to one of the SPI buses.
Public Members
uint8_t command_bits
Default amount of bits in command phase (0-16), used when SPI_TRANS_VARIABLE_CMD is not
used, otherwise ignored.
uint8_t address_bits
Default amount of bits in address phase (0-64), used when SPI_TRANS_VARIABLE_ADDR is not
used, otherwise ignored.
uint8_t dummy_bits
Amount of dummy bits to insert between address and data phase.
uint8_t mode
SPI mode, representing a pair of (CPOL, CPHA) configuration:
• 0: (0, 0)
• 1: (0, 1)
• 2: (1, 0)
• 3: (1, 1)
uint16_t duty_cycle_pos
Duty cycle of positive clock, in 1/256th increments (128 = 50%/50% duty). Setting this to 0 (=not setting
it) is equivalent to setting this to 128.
uint16_t cs_ena_pretrans
Amount of SPI bit-cycles the cs should be activated before the transmission (0-16). This only works on
half-duplex transactions.

uint8_t cs_ena_posttrans
Amount of SPI bit-cycles the cs should stay active after the transmission (0-16)
int clock_speed_hz
Clock speed, divisors of 80MHz, in Hz. See SPI_MASTER_FREQ_*.
int input_delay_ns
Maximum data valid time of slave. The time required between SCLK and MISO valid, including the
possible clock delay from slave to master. The driver uses this value to give an extra delay before the
MISO is ready on the line. Leave at 0 unless you know you need a delay. For better timing performance
at high frequency (over 8MHz), it s suggest to have the right value.
int spics_io_num
CS GPIO pin for this device, or -1 if not used.
uint32_t flags
Bitwise OR of SPI_DEVICE_* flags.
int queue_size
Transaction queue size. This sets how many transactions can be in the air (queued using
spi_device_queue_trans but not yet finished using spi_device_get_trans_result) at the same time.
transaction_cb_t pre_cb
Callback to be called before a transmission is started.
This callback is called within interrupt context should be in IRAM for best performance, see Trans-
ferring Speed section in the SPI Master documentation for full details. If not, the callback may crash
during flash operation when the driver is initialized with ESP_INTR_FLAG_IRAM.
transaction_cb_t post_cb
Callback to be called after a transmission has completed.
struct spi_transaction_t
This structure describes one SPI transaction. The descriptor should not be modified until the transaction fin-
ishes.
Public Members
uint32_t flags
Bitwise OR of SPI_TRANS_* flags.
uint16_t cmd
Command data, of which the length is set in the command_bits of spi_device_interface_config_t.
NOTE: this field, used to be command in ESP-IDF 2.1 and before, is re-written to be used in
a new way in ESP-IDF 3.0.
Example: write 0x0123 and command_bits=12 to send command 0x12, 0x3_ (in previous version, you
may have to write 0x3_12).
uint64_t addr
Address data, of which the length is set in the address_bits of spi_device_interface_config_t.
NOTE: this field, used to be address in ESP-IDF 2.1 and before, is re-written to be used in a
new way in ESP-IDF3.0.
Example: write 0x123400 and address_bits=24 to send address of 0x12, 0x34, 0x00 (in previous version,
you may have to write 0x12340000).
size_t length
Total data length, in bits.

size_t rxlength
Total data length received, should be not greater than length in full-duplex mode (0 defaults this to the
value of length).
void *user
User-defined variable. Can be used to store eg transaction ID.
const void *tx_buffer
Pointer to transmit buffer, or NULL for no MOSI phase.
uint8_t tx_data[4]
If SPI_TRANS_USE_TXDATA is set, data set here is sent directly from this variable.
void *rx_buffer
Pointer to receive buffer, or NULL for no MISO phase. Written by 4 bytes-unit if DMA is used.
uint8_t rx_data[4]
If SPI_TRANS_USE_RXDATA is set, data is received directly to this variable.
struct spi_transaction_ext_t
This struct is for SPI transactions which may change their address and command length. Please do set the flags
in base to SPI_TRANS_VARIABLE_CMD_ADR to use the bit length here.
Public Members
struct spi_transaction_t base

Transaction data, so that pointer to spi_transaction_t can be converted into spi_transaction_ext_t.
uint8_t command_bits
The command length in this transaction, in bits.
uint8_t address_bits
The address length in this transaction, in bits.
uint8_t dummy_bits
The dummy length in this transaction, in bits.
Macros
SPI_MASTER_FREQ_8M
SPI master clock is divided by 80MHz apb clock. Below defines are example frequencies, and are accurate. Be
free to specify a random frequency, it will be rounded to closest frequency (to macros below if above 8MHz).
8MHz
SPI_MASTER_FREQ_9M
8.89MHz
SPI_MASTER_FREQ_10M
10MHz
SPI_MASTER_FREQ_11M
11.43MHz
SPI_MASTER_FREQ_13M
13.33MHz
SPI_MASTER_FREQ_16M
16MHz
SPI_MASTER_FREQ_20M
20MHz
SPI_MASTER_FREQ_26M
26.67MHz
SPI_MASTER_FREQ_40M
40MHz

SPI_MASTER_FREQ_80M
80MHz
SPI_DEVICE_TXBIT_LSBFIRST
Transmit command/address/data LSB first instead of the default MSB first.
SPI_DEVICE_RXBIT_LSBFIRST
Receive data LSB first instead of the default MSB first.
SPI_DEVICE_BIT_LSBFIRST
Transmit and receive LSB first.
SPI_DEVICE_3WIRE
Use MOSI (=spid) for both sending and receiving data.
SPI_DEVICE_POSITIVE_CS
Make CS positive during a transaction instead of negative.
SPI_DEVICE_HALFDUPLEX
Transmit data before receiving it, instead of simultaneously.
SPI_DEVICE_CLK_AS_CS
Output clock on CS line if CS is active.
SPI_DEVICE_NO_DUMMY
There are timing issue when reading at high frequency (the frequency is related to whether iomux pins are used,
valid time after slave sees the clock).
• In half-duplex mode, the driver automatically inserts dummy bits before reading phase to fix the timing
issue. Set this flag to disable this feature.
• In full-duplex mode, however, the hardware cannot use dummy bits, so there is no way to prevent data
being read from getting corrupted. Set this flag to confirm that you re going to work with output only,
or read without dummy bits at your own risk.
SPI_DEVICE_DDRCLK
SPI_TRANS_MODE_DIO
Transmit/receive data in 2-bit mode.
SPI_TRANS_MODE_QIO
SPI_TRANS_USE_RXDATA
Receive into rx_data member of spi_transaction_t instead into memory at rx_buffer.
SPI_TRANS_USE_TXDATA
Transmit tx_data member of spi_transaction_t instead of data at tx_buffer. Do not set tx_buffer when using
this.
SPI_TRANS_MODE_DIOQIO_ADDR
Also transmit address in mode selected by SPI_MODE_DIO/SPI_MODE_QIO.
SPI_TRANS_VARIABLE_CMD
Use the command_bits in spi_transaction_ext_t rather than default value in
spi_device_interface_config_t.
SPI_TRANS_VARIABLE_ADDR
Use the address_bits in spi_transaction_ext_t rather than default value in
SPI_TRANS_VARIABLE_DUMMY
Use the dummy_bits in spi_transaction_ext_t rather than default value in
SPI_TRANS_CS_KEEP_ACTIVE
Keep CS active after data transfer.

SPI_TRANS_MULTILINE_CMD
The data lines used at command phase is the same as data phase (otherwise, only one data line is used at
command phase)
SPI_TRANS_MODE_OCT
SPI_TRANS_MULTILINE_ADDR
The data lines used at address phase is the same as data phase (otherwise, only one data line is used at address
phase)
Type Definitions
typedef struct spi_transaction_t spi_transaction_t
typedef void (*transaction_cb_t)(spi_transaction_t *trans)
typedef struct spi_device_t *spi_device_handle_t
Handle for a device on a SPI bus.
2.3.18 SPI Slave Driver
SPI Slave driver is a program that controls ESP32 s SPI peripherals while they function as slaves.
Overview of ESP32 s SPI peripherals
ESP32 integrates two general purpose SPI controllers which can be used as slave nodes driven by an off-chip SPI
master
• SPI2, sometimes referred to as HSPI
• SPI3, sometimes referred to as VSPI
SPI2 and SPI3 have independent signal buses with the same respective names.
Terminology
The terms used in relation to the SPI slave driver are given in the table below.

Term Definition
Host The SPI controller peripheral external to ESP32 that
initiates SPI transmissions over the bus, and acts as an
SPI Master.
Device SPI slave device (general purpose SPI controller). Each
Device shares the MOSI, MISO and SCLK signals but
is only active on the bus when the Host asserts the De-
vice s individual CS line.
Bus A signal bus, common to all Devices connected to one
Host. In general, a bus includes the following lines:
MISO, MOSI, SCLK, one or more CS lines, and, op-
tionally, QUADWP and QUADHD. So Devices are
connected to the same lines, with the exception that
each Device has its own CS line. Several Devices can
also share one CS line if connected in the daisy-chain
manner.
Master In, Slave Out, a.k.a. Q. Data transmission from
• MISO
a Device to Host.
Master Out, Slave in, a.k.a. D. Data transmission from
• MOSI
a Host to Device.
Serial Clock. Oscillating signal generated by a Host that
• SCLK
keeps the transmission of data bits in sync.
Chip Select. Allows a Host to select individual De-
• CS
vice(s) connected to the bus in order to send or receive
data.
Write Protect signal. Only used for 4-bit (qio/qout)
• QUADWP
transactions.
Hold signal. Only used for 4-bit (qio/qout) transactions.
• QUADHD
The action of activating a line. The opposite action of

• Assertion
returning the line back to inactive (back to idle) is called
de-assertion.
Transaction One instance of a Host asserting a CS line, transferring
data to and from a Device, and de-asserting the CS line.
Transactions are atomic, which means they can never be
interrupted by another transaction.
Launch edge Edge of the clock at which the source register launches
the signal onto the line.
Latch edge Edge of the clock at which the destination register
latches in the signal.
Driver Features
The SPI slave driver allows using the SPI peripherals as full-duplex Devices. The driver can send/receive transactions
up to 64 bytes in length, or utilize DMA to send/receive longer transactions. However, there are some known issues
related to DMA.
SPI Transactions
A full-duplex SPI transaction begins when the Host asserts the CS line and starts sending out clock pulses on the
SCLK line. Every clock pulse, a data bit is shifted from the Host to the Device on the MOSI line and back on the
MISO line at the same time. At the end of the transaction, the Host de-asserts the CS line.

The attributes of a transaction are determined by the configuration structure for an SPI host act-
ing as a slave device spi_slave_interface_config_t, and transaction configuration structure
spi_slave_transaction_t.
As not every transaction requires both writing and reading data, you have a choice to config-
ure the spi_transaction_t structure for TX only, RX only, or TX and RX transactions. If
spi_slave_transaction_t::rx_buffer is set to NULL, the read phase will be skipped. If
spi_slave_transaction_t::tx_buffer is set to NULL, the write phase will be skipped.
Note: A Host should not start a transaction before its Device is ready for receiving data. It is recommended to use
another GPIO pin for a handshake signal to sync the Devices. For more details, see Transaction Interval.
Driver Usage
• Initialize an SPI peripheral as a Device by calling the function cpp:func:spi_slave_initialize. Make sure to set
the correct I/O pins in the struct bus_config. Set the unused signals to -1.
If transactions will be longer than 32 bytes, allow a DMA channel 1 or 2 by setting the parameter dma_chan to 1
or 2 respectively. Otherwise, set dma_chan to 0.
• Before initiating transactions, fill one or more spi_slave_transaction_t structs with the transaction
parameters required. Either queue all transactions by calling the function spi_slave_queue_trans()
and, at a later time, query the result by using the function spi_slave_get_trans_result(), or handle
all requests individually by feeding them into spi_slave_transmit(). The latter two functions will be
blocked until the Host has initiated and finished a transaction, causing the queued data to be sent and received.
• (Optional) To unload the SPI slave driver, call spi_slave_free().
Transaction Data and Master/Slave Length Mismatches
Normally, the data that needs to be transferred to or from a Device is read or written to a chunk of memory indicated
by the rx_buffer and tx_buffer members of the spi_transaction_t structure. The SPI driver can be
configured to use DMA for transfers, in which case these buffers must be allocated in DMA-capable memory using
pvPortMallocCaps(size, MALLOC_CAP_DMA).
The amount of data that the driver can read or write to the buffers is limited by the member
spi_transaction_t::length. However, this member does not define the actual length of an SPI
transaction. A transaction s length is determined by a Host which drives the clock and CS lines.
The actual length of the transmission can be read only after a transaction is finished from the member
spi_slave_transaction_t::trans_len.
If the length of the transmission is greater than the buffer length, only the initial number of bits specified in the
length member will be sent and received. In this case, trans_len is set to length instead of the actual
transaction length. To meet the actual transaction length requirements, set length to a value greater than the
maximum trans_len expected. If the transmission length is shorter than the buffer length, only the data equal to
the length of the buffer will be transmitted.
GPIO Matrix and IO_MUX
Most of ESP32 s peripheral signals have direct connection to their dedicated IO_MUX pins. However, the signals
can also be routed to any other available pins using the less direct GPIO matrix.
If at least one signal is routed through the GPIO matrix, then all signals will be routed through it. The GPIO matrix
samples all signals at 80 MHz and transmits them between the GPIO and the peripheral.
If the driver is configured so that all SPI signals are either routed to their dedicated IO_MUX pins or are not connected
at all, the GPIO matrix will be bypassed.

The GPIO matrix introduces flexibility of routing but also increases the input delay of the MISO signal, which makes
MISO setup time violations more likely. If SPI needs to operate at high speeds, use dedicated IO_MUX pins.
Note: For more details about the influence of the MISO input delay on the maximum clock frequency, see Timing
Considerations.
The IO_MUX pins for SPI buses are given below.
Pin Name SPI2 SPI3

GPIO Number
CS0* 15 5
SCLK 14 18
MISO 12 19
MOSI 13 23
QUADWP 2 22
QUADHD 4 21
• Only the first Device attached to the bus can use the CS0 pin.
Speed and Timing Considerations
Transaction Interval The ESP32 SPI slave peripherals are designed as general purpose Devices controlled by a
CPU. As opposed to dedicated slaves, CPU-based SPI Devices have a limited number of pre-defined registers. All
transactions must be handled by the CPU, which means that the transfers and responses are not real-time, and there
might be noticeable latency.
As a solution, a Device s response rate can be doubled by using the functions spi_slave_queue_trans()
and then spi_slave_get_trans_result() instead of using spi_slave_transmit().
You can also configure a GPIO pin through which the Device will signal to the Host when it is ready for a new
transaction. A code example of this can be found in peripherals/spi_slave.
SCLK Frequency Requirements The SPI slaves are designed to operate at up to 10 MHz. The data cannot be
recognized or received correctly if the clock is too fast or does not have a 50% duty cycle.
On top of that, there are additional requirements for the data to meet the timing constraints:
• Read (MOSI): The Device can read data correctly only if the data is already set at the launch edge. Although
it is usually the case for most masters.
• Write (MISO): The output delay of the MISO signal needs to be shorter than half of a clock cycle period so
that the MISO line is stable before the next latch edge. Given that the clock is balanced, the output delay
and frequency limitations in different cases are given below.
Output delay of MISO (ns) Freq. limit (MHz)

IO_MUX 43.75 <11.4
GPIO matrix 68.75 <7.2
Note: 1. If the frequency is equal to the limitation, it can lead to random errors. 2. The clock uncertainty
between Host and Device (12.5ns) is included. 3. The output delay is measured under ideal circumstances
(no load). If the MISO pin is heavily loaded, the output delay will be longer, and the maximum allowed
frequency will be lower.
Exception: The frequency is allowed to be higher if the master has more tolerance for the MISO setup
time, e.g., latch data at the next edge, or configurable latching time.

Restrictions and Known Issues
1. If DMA is enabled, the rx buffer should be word-aligned (starting from a 32-bit boundary and having a length
of multiples of 4 bytes). Otherwise, DMA may write incorrectly or not in a boundary aligned manner. The
driver reports an error if this condition is not satisfied.
Also, a Host should write lengths that are multiples of 4 bytes. The data with inappropriate lengths will be
discarded.
2. Furthermore, DMA requires SPI modes 1 and 3. For SPI modes 0 and 2, the MISO signal has to be launched
half a clock cycle earlier to meet the timing. The new timing is as follows:
If DMA is enabled, a Device s launch edge is half of an SPI clock cycle ahead of the normal time, shifting to the
Master s actual latch edge. In this case, if the GPIO matrix is bypassed, the hold time for data sampling is 68.75 ns
and no longer a half of an SPI clock cycle. If the GPIO matrix is used, the hold time will increase to 93.75 ns. The
Host should sample the data immediately at the latch edge or communicate in SPI modes 1 or 3. If your Host cannot
meet these timing requirements, initialize your Device without DMA.
Application Example
The code example for Device/Host communication can be found in the peripherals/spi_slave directory of ESP-IDF
examples.
API Reference
Header File
• components/driver/include/driver/spi_slave.h
Functions
esp_err_t spi_slave_initialize(spi_host_device_t host, const spi_bus_config_t *bus_config,
const spi_slave_interface_config_t *slave_config,
spi_dma_chan_t dma_chan)
Initialize a SPI bus as a slave interface.
Warning SPI0/1 is not supported
Warning If a DMA channel is selected, any transmit and receive buffer used should be allocated in DMA-
capable memory.
Warning The ISR of SPI is always executed on the core which calls this function. Never starve the ISR on
this core or the SPI transactions will not be handled.
Return
• ESP_ERR_INVALID_ARG if configuration is invalid
• ESP_ERR_INVALID_STATE if host already is in use
• ESP_ERR_NOT_FOUND if there is no available DMA channel
Parameters
• host: SPI peripheral to use as a SPI slave interface
• bus_config: Pointer to a spi_bus_config_t struct specifying how the host should be initialized
• slave_config: Pointer to a spi_slave_interface_config_t struct specifying the details for the slave
interface

• dma_chan: - Selecting a DMA channel for an SPI bus allows transactions on the bus with size only
limited by the amount of internal memory.
– Selecting SPI_DMA_DISABLED limits the size of transactions.
– Set to SPI_DMA_DISABLED if only the SPI flash uses this bus.
– Set to SPI_DMA_CH_AUTO to let the driver to allocate the DMA channel.
esp_err_t spi_slave_free(spi_host_device_t host)
Free a SPI bus claimed as a SPI slave interface.
Return
• ESP_ERR_INVALID_STATE if not all devices on the bus are freed
Parameters
• host: SPI peripheral to free
esp_err_t spi_slave_queue_trans(spi_host_device_t host, const spi_slave_transaction_t
*trans_desc, TickType_t ticks_to_wait)
Queue a SPI transaction for execution.
Queues a SPI transaction to be executed by this slave device. (The transaction queue size was specified when the
slave device was initialised via spi_slave_initialize.) This function may block if the queue is full (depending on
the ticks_to_wait parameter). No SPI operation is directly initiated by this function, the next queued transaction
will happen when the master initiates a SPI transaction by pulling down CS and sending out clock signals.
This function hands over ownership of the buffers in trans_desc to the SPI slave driver; the application
is not to access this memory until spi_slave_queue_trans is called to hand ownership back to the
application.
Return
Parameters
• host: SPI peripheral that is acting as a slave
• trans_desc: Description of transaction to execute. Not const because we may want to write
status back into the transaction description.
• ticks_to_wait: Ticks to wait until there s room in the queue; use portMAX_DELAY to never
time out.
esp_err_t spi_slave_get_trans_result(spi_host_device_t host, spi_slave_transaction_t
**trans_desc, TickType_t ticks_to_wait)
Get the result of a SPI transaction queued earlier.
This routine will wait until a transaction to the given device (queued earlier with spi_slave_queue_trans) has
succesfully completed. It will then return the description of the completed transaction so software can inspect
the result and e.g. free the memory or re-use the buffers.
It is mandatory to eventually use this function for any transaction queued by spi_slave_queue_trans.
Return
Parameters
• host: SPI peripheral to that is acting as a slave
• [out] trans_desc: Pointer to variable able to contain a pointer to the description of the
transaction that is executed
time out.
esp_err_t spi_slave_transmit(spi_host_device_t host, spi_slave_transaction_t *trans_desc, Tick-
Do a SPI transaction.
Essentially does the same as spi_slave_queue_trans followed by spi_slave_get_trans_result. Do not use this
when there is still a transaction queued that hasn t been finalized using spi_slave_get_trans_result.

Return
Parameters
• host: SPI peripheral to that is acting as a slave
• trans_desc: Pointer to variable able to contain a pointer to the description of the transaction that
is executed. Not const because we may want to write status back into the transaction description.
time out.
Structures
struct spi_slave_interface_config_t
This is a configuration for a SPI host acting as a slave device.
Public Members
int spics_io_num
CS GPIO pin for this device.
uint32_t flags
Bitwise OR of SPI_SLAVE_* flags.
int queue_size
Transaction queue size. This sets how many transactions can be in the air (queued using
spi_slave_queue_trans but not yet finished using spi_slave_get_trans_result) at the same time.
uint8_t mode
SPI mode, representing a pair of (CPOL, CPHA) configuration:
• 0: (0, 0)
• 1: (0, 1)
• 2: (1, 0)
• 3: (1, 1)
slave_transaction_cb_t post_setup_cb
Callback called after the SPI registers are loaded with new data.
slave_transaction_cb_t post_trans_cb
Callback called after a transaction is done.
struct spi_slave_transaction_t
This structure describes one SPI transaction
Public Members
size_t length
Total data length, in bits.
size_t trans_len
Transaction data length, in bits.
const void *tx_buffer
Pointer to transmit buffer, or NULL for no MOSI phase.

void *rx_buffer
Pointer to receive buffer, or NULL for no MISO phase. When the DMA is anabled, must start at WORD
boundary (rx_buffer%4==0), and has length of a multiple of 4 bytes.
void *user
User-defined variable. Can be used to store eg transaction ID.
Macros
SPI_SLAVE_TXBIT_LSBFIRST
Transmit command/address/data LSB first instead of the default MSB first.
SPI_SLAVE_RXBIT_LSBFIRST
Receive data LSB first instead of the default MSB first.
SPI_SLAVE_BIT_LSBFIRST
Transmit and receive LSB first.
Type Definitions
typedef struct spi_slave_transaction_t spi_slave_transaction_t
typedef void (*slave_transaction_cb_t)(spi_slave_transaction_t *trans)
2.3.19 ESP32-WROOM-32SE (Secure Element)
Overview
The ESP32-WROOM-32SE has integrated Microchip s ATECC608A cryptoauth chip in the module. ATECC608A
is secure element which would generate and store ECC private key in the hardware.The ECC private key can be used
to enhance security to connect to IoT cloud services with use of X.509 based mutual authentication. The application
example demonstrates ECDSA sign and verify functions using ECC private key stored in ATECC608A
Application Example
Secure Element ECDSA Sign/Verify example: peripherals/secure_element/atecc608_ecdsa.
How to configure and provision ESP32-WROOM-32SE for TLS
To configure and provision ATECC608A chip on ESP32-WROOM-32SE please visit esp_cryptoauth_utility
How to use ATECC608A of ESP32-WROOM-32SE for TLS
ATECC608A can be used for TLS connections using ESP-TLS. To configure ESP-TLS for using secure element
please refer ATECC608A with ESP-TLS in ESP-TLS documentation.
2.3.20 Touch Sensor
Introduction
A touch sensor system is built on a substrate which carries electrodes and relevant connections under a protective flat
surface. When a user touches the surface, the capacitance variation is used to evaluate if the touch was valid.
Touch sensor on ESP32 can support up to 10 capacitive touch pads / GPIOs.
The sensing pads can be arranged in different combinations (e.g., matrix, slider), so that a larger area or more points
can be detected. The touch pad sensing process is under the control of a hardware-implemented finite-state machine
(FSM) which is initiated by software or a dedicated hardware timer.

For design, operation, and control registers of a touch sensor, see ESP32 Technical Reference Manual > On-Chip
Sensors and Analog Signal Processing [PDF].
In-depth design details of touch sensors and firmware development guidelines for ESP32 are available in Touch Sensor
Application Note.
For more information about testing touch sensors in various configurations, please check the Guide for ESP32-Sense-
Kit.
Description of API is broken down into groups of functions to provide a quick overview of the following features:
• Initialization of touch pad driver
• Configuration of touch pad GPIO pins
• Taking measurements
• Adjusting parameters of measurements
• Filtering measurements
• Touch detection methods
• Setting up interrupts to report touch detection
• Waking up from Sleep mode on interrupt
For detailed description of a particular function, please go to Section API Reference. Practical implementation of this
API is covered in Section Application Examples.
Initialization Before using a touch pad, you need to initialize the touch pad driver by calling the function
touch_pad_init(). This function sets several .._DEFAULT driver parameters listed in API Reference under
Macros. It also removes the information about which pads have been touched before, if any, and disables interrupts.
If the driver is not required anymore, deinitialize it by calling touch_pad_deinit().
Configuration Enabling the touch sensor functionality for a particular GPIO is done with
touch_pad_config().
Use the function touch_pad_set_fsm_mode() to select if touch pad measurement (operated by FSM)
should be started automatically by a hardware timer, or by software. If software mode is selected, use
touch_pad_sw_start() to start the FSM.
Touch State Measurements The following two functions come in handy to read raw or filtered measurements
from the sensor:
• touch_pad_read_raw_data()
• touch_pad_read_filtered()
They can also be used, for example, to evaluate a particular touch pad design by checking the range of sensor readings
when a pad is touched or released. This information can be then used to establish a touch threshold.
Note: Before using touch_pad_read_filtered(), you need to initialize and configure the filter by calling
specific filter functions described in Section Filtering of Measurements.
For the demonstration of how to read the touch pad data, check the application example peripher-
als/touch_sensor/touch_sensor_v1/touch_pad_read.
Optimization of Measurements A touch sensor has several configurable parameters to match the characteristics
of a particular touch pad design. For instance, to sense smaller capacity changes, it is possible to narrow down the
reference voltage range within which the touch pads are charged / discharged. The high and low reference voltages
are set using the function touch_pad_set_voltage().

Besides the ability to discern smaller capacity changes, a positive side effect is reduction of power consumption for
low power applications. A likely negative effect is an increase in measurement noise. If the dynamic range of obtained
readings is still satisfactory, then further reduction of power consumption might be done by reducing the measurement
time with touch_pad_set_meas_time().
The following list summarizes available measurement parameters and corresponding set functions:
• Touch pad charge / discharge parameters:
– voltage range: touch_pad_set_voltage()
– speed (slope): touch_pad_set_cnt_mode()
• Measurement time: touch_pad_set_meas_time()
Relationship between the voltage range (high / low reference voltages), speed (slope), and measurement time is shown
in the figure below.
Fig. 20: Touch pad - relationship between measurement parameters
The last chart Output represents the touch sensor reading, i.e., the count of pulses collected within the measurement
time.
All functions are provided in pairs to set a specific parameter and to get the current parameter s value, e.g.,
touch_pad_set_voltage() and touch_pad_get_voltage().
Filtering of Measurements If measurements are noisy, you can filter them with provided API functions. Before
using the filter, please start it by calling touch_pad_filter_start().
The filter type is IIR (infinite impulse response), and it has a configurable period that can be set with the function
touch_pad_set_filter_period().
You can stop the filter with touch_pad_filter_stop(). If not required anymore, the filter can be deleted by
invoking touch_pad_filter_delete().
Touch Detection Touch detection is implemented in ESP32 s hardware based on the user-configured threshold
and raw measurements executed by FSM. Use the functions touch_pad_get_status() to check which pads
have been touched and touch_pad_clear_status() to clear the touch status information.
Hardware touch detection can also be wired to interrupts. This is described in the next section.
If measurements are noisy and capacity changes are small, hardware touch detection might be unreliable. To resolve
this issue, instead of using hardware detection / provided interrupts, implement measurement filtering and perform

touch detection in your own application. For sample implementation of both methods of touch detection, see pe-
ripherals/touch_sensor/touch_sensor_v1/touch_pad_interrupt.
Touch Triggered Interrupts Before enabling an interrupt on a touch detection, you should establish a touch de-
tection threshold. Use the functions described in Touch State Measurements to read and display sensor measurements
when a pad is touched and released. Apply a filter if measurements are noisy and relative capacity changes are small.
Depending on your application and environment conditions, test the influence of temperature and power supply volt-
age changes on measured values.
Once a detection threshold is established, it can be set during initialization with touch_pad_config() or at the
runtime with touch_pad_set_thresh().
In the next step, configure how interrupts are triggered. They can be triggered below or above the threshold, which is
set with the function touch_pad_set_trigger_mode().
Finally, configure and manage interrupt calls using the following functions:
• touch_pad_isr_register() / touch_pad_isr_deregister()
• touch_pad_intr_enable() / touch_pad_intr_disable()
When interrupts are operational, you can obtain the information from which particular pad an interrupt came by
invoking touch_pad_get_status() and clear the pad status with touch_pad_clear_status().
Note: Interrupts on touch detection operate on raw / unfiltered measurements checked against user established
threshold and are implemented in hardware. Enabling the software filtering API (see Filtering of Measurements) does
not affect this process.
Wakeup from Sleep Mode If touch pad interrupts are used to wake up the chip from a sleep mode, you can select
a certain configuration of pads (SET1 or both SET1 and SET2) that should be touched to trigger the interrupt and
cause the subsequent wakeup. To do so, use the function touch_pad_set_trigger_source().
Configuration of required bit patterns of pads may be managed for each SET with:
• touch_pad_set_group_mask() / touch_pad_get_group_mask()
• touch_pad_clear_group_mask()
• Touch sensor read example: peripherals/touch_sensor/touch_sensor_v1/touch_pad_read.

• Touch sensor interrupt example: peripherals/touch_sensor/touch_sensor_v1/touch_pad_interrupt.
API Reference
Header File
• components/driver/esp32/include/driver/touch_sensor.h
Functions
esp_err_t touch_pad_config(touch_pad_t touch_num, uint16_t threshold)
Configure touch pad interrupt threshold.
Note If FSM mode is set to TOUCH_FSM_MODE_TIMER, this function will be blocked for one measure-
ment cycle and wait for data to be valid.
Return
• ESP_OK Success
• ESP_ERR_INVALID_ARG if argument wrong
• ESP_FAIL if touch pad not initialized

Parameters
• touch_num: touch pad index
• threshold: interrupt threshold,
esp_err_t touch_pad_read(touch_pad_t touch_num, uint16_t *touch_value)
get touch sensor counter value. Each touch sensor has a counter to count the number of charge/discharge
cycles. When the pad is not touched , we can get a number of the counter. When the pad is touched ,
the value in counter will get smaller because of the larger equivalent capacitance.
Note This API requests hardware measurement once. If IIR filter mode is enabled, please use
touch_pad_read_raw_data interface instead.
Return
• ESP_OK Success
• ESP_ERR_INVALID_ARG Touch pad parameter error
• ESP_ERR_INVALID_STATE This touch pad hardware connection is error, the value of
touch_value is 0.
• ESP_FAIL Touch pad not initialized
Parameters
• touch_value: pointer to accept touch sensor value
esp_err_t touch_pad_read_filtered(touch_pad_t touch_num, uint16_t *touch_value)
get filtered touch sensor counter value by IIR filter.
Note touch_pad_filter_start has to be called before calling touch_pad_read_filtered. This function can be
called from ISR
Return
• ESP_OK Success
touch_value is 0.
Parameters
esp_err_t touch_pad_read_raw_data(touch_pad_t touch_num, uint16_t *touch_value)
get raw data (touch sensor counter value) from IIR filter process. Need not request hardware measurements.
Note touch_pad_filter_start has to be called before calling touch_pad_read_raw_data. This function can be
called from ISR
Return
• ESP_OK Success
touch_value is 0.
Parameters
esp_err_t touch_pad_set_filter_read_cb(filter_cb_t read_cb)
Register the callback function that is called after each IIR filter calculation.
Note The read_cb callback is called in timer task in each filtering cycle.
Return
• ESP_OK Success
• ESP_ERR_INVALID_ARG set error
Parameters
• read_cb: Pointer to filtered callback function. If the argument passed in is NULL, the callback
will stop.
esp_err_t touch_pad_isr_register(intr_handler_t fn, void *arg)

Register touch-pad ISR. The handler will be attached to the same CPU core that this function is running on.
Return
• ESP_OK Success ;
• ESP_ERR_NO_MEM No memory
Parameters
• fn: Pointer to ISR handler
• arg: Parameter for ISR
esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_cycle)
Set touch sensor measurement and sleep time. Excessive total time will slow down the touch response. Too
small measurement time will not be sampled enough, resulting in inaccurate measurements.
Note The greater the duty cycle of the measurement time, the more system power is consumed.
Return
Parameters
• sleep_cycle: The touch sensor will sleep after each measurement. sleep_cycle decide the in-
terval between each measurement. t_sleep = sleep_cycle / (RTC_SLOW_CLK frequency). The ap-
proximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz
function.
• meas_cycle: The duration of the touch sensor measurement. t_meas = meas_cycle / 8M, the
maximum measure time is 0xffff / 8M = 8.19 ms
esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_cycle)
Get touch sensor measurement and sleep time.
Return
Parameters
• sleep_cycle: Pointer to accept sleep cycle number
• meas_cycle: Pointer to accept measurement cycle count.
esp_err_t touch_pad_sw_start(void)
Trigger a touch sensor measurement, only support in SW mode of FSM.
Return
esp_err_t touch_pad_set_thresh(touch_pad_t touch_num, uint16_t threshold)
Set touch sensor interrupt threshold.
Return
• ESP_ERR_INVALID_ARG if argument is wrong
Parameters
• threshold: threshold of touchpad count, refer to touch_pad_set_trigger_mode to see how to set
trigger mode.
esp_err_t touch_pad_get_thresh(touch_pad_t touch_num, uint16_t *threshold)
Get touch sensor interrupt threshold.
Return
Parameters
• threshold: pointer to accept threshold
esp_err_t touch_pad_set_trigger_mode(touch_trigger_mode_t mode)
Set touch sensor interrupt trigger mode. Interrupt can be triggered either when counter result is less than
threshold or when counter result is more than threshold.

Return
Parameters
• mode: touch sensor interrupt trigger mode
esp_err_t touch_pad_get_trigger_mode(touch_trigger_mode_t *mode)
Get touch sensor interrupt trigger mode.
Return
Parameters
• mode: pointer to accept touch sensor interrupt trigger mode
esp_err_t touch_pad_set_trigger_source(touch_trigger_src_t src)
Set touch sensor interrupt trigger source. There are two sets of touch signals. Set1 and set2 can be mapped to
several touch signals. Either set will be triggered if at least one of its touch signal is touched . The interrupt
can be configured to be generated if set1 is triggered, or only if both sets are triggered.
Return
Parameters
• src: touch sensor interrupt trigger source
esp_err_t touch_pad_get_trigger_source(touch_trigger_src_t *src)
Get touch sensor interrupt trigger source.
Return
Parameters
• src: pointer to accept touch sensor interrupt trigger source
esp_err_t touch_pad_set_group_mask(uint16_t set1_mask, uint16_t set2_mask, uint16_t en_mask)
Set touch sensor group mask. Touch pad module has two sets of signals, Touched signal is triggered only
if at least one of touch pad in this group is touched . This function will set the register bits according to
the given bitmask.
Return
Parameters
• set1_mask: bitmask of touch sensor signal group1, it s a 10-bit value
• set2_mask: bitmask of touch sensor signal group2, it s a 10-bit value
• en_mask: bitmask of touch sensor work enable, it s a 10-bit value
esp_err_t touch_pad_get_group_mask(uint16_t *set1_mask, uint16_t *set2_mask, uint16_t
*en_mask)
Get touch sensor group mask.
Return
Parameters
• set1_mask: pointer to accept bitmask of touch sensor signal group1, it s a 10-bit value
• set2_mask: pointer to accept bitmask of touch sensor signal group2, it s a 10-bit value
• en_mask: pointer to accept bitmask of touch sensor work enable, it s a 10-bit value
esp_err_t touch_pad_clear_group_mask(uint16_t set1_mask, uint16_t set2_mask, uint16_t
en_mask)
Clear touch sensor group mask. Touch pad module has two sets of signals, Interrupt is triggered only if at least
one of touch pad in this group is touched . This function will clear the register bits according to the given
bitmask.
Return


Parameters
• set1_mask: bitmask touch sensor signal group1, it s a 10-bit value
• set2_mask: bitmask touch sensor signal group2, it s a 10-bit value
• en_mask: bitmask of touch sensor work enable, it s a 10-bit value
esp_err_t touch_pad_intr_enable(void)
To enable touch pad interrupt.
Return
esp_err_t touch_pad_intr_disable(void)
To disable touch pad interrupt.
Return
esp_err_t touch_pad_intr_clear(void)
To clear touch pad interrupt.
Return
esp_err_t touch_pad_set_filter_period(uint32_t new_period_ms)
set touch pad filter calibration period, in ms. Need to call touch_pad_filter_start before all touch filter APIs
Return
• ESP_OK Success
• ESP_ERR_INVALID_STATE driver state error
• ESP_ERR_INVALID_ARG parameter error
Parameters
• new_period_ms: filter period, in ms
esp_err_t touch_pad_get_filter_period(uint32_t *p_period_ms)
get touch pad filter calibration period, in ms Need to call touch_pad_filter_start before all touch filter APIs
Return
• ESP_OK Success
Parameters
• p_period_ms: pointer to accept period
esp_err_t touch_pad_filter_start(uint32_t filter_period_ms)
start touch pad filter function This API will start a filter to process the noise in order to prevent false triggering
when detecting slight change of capacitance. Need to call touch_pad_filter_start before all touch filter APIs
Note This filter uses FreeRTOS timer, which is dispatched from a task with priority 1 by default on CPU 0. So
if some application task with higher priority takes a lot of CPU0 time, then the quality of data obtained
from this filter will be affected. You can adjust FreeRTOS timer task priority in menuconfig.
Return
• ESP_OK Success
• ESP_ERR_NO_MEM No memory for driver
Parameters
• filter_period_ms: filter calibration period, in ms
esp_err_t touch_pad_filter_stop(void)
stop touch pad filter function Need to call touch_pad_filter_start before all touch filter APIs
Return
• ESP_OK Success

esp_err_t touch_pad_filter_delete(void)
delete touch pad filter driver and release the memory Need to call touch_pad_filter_start before all touch filter
APIs
Return
• ESP_OK Success
Type Definitions
typedef void (*filter_cb_t)(uint16_t *raw_value, uint16_t *filtered_value)
Callback function that is called after each IIR filter calculation.
Note This callback is called in timer task in each filtering cycle.
Note This callback should not be blocked.
Parameters
• raw_value: The latest raw data(touch sensor counter value) that points to all chan-
nels(raw_value[0..TOUCH_PAD_MAX-1]).
• filtered_value: The latest IIR filtered data(calculated from raw data) that points to all chan-
nels(filtered_value[0..TOUCH_PAD_MAX-1]).
Header File
• components/driver/include/driver/touch_sensor_common.h
Functions
esp_err_t touch_pad_init(void)
Initialize touch module.
Note If default parameter don t match the usage scenario, it can be changed after this function.
Return
• ESP_OK Success
• ESP_ERR_NO_MEM Touch pad init error
• ESP_ERR_NOT_SUPPORTED Touch pad is providing current to external XTAL
esp_err_t touch_pad_deinit(void)
Un-install touch pad driver.
Note After this function is called, other touch functions are prohibited from being called.
Return
• ESP_OK Success
• ESP_FAIL Touch pad driver not initialized
esp_err_t touch_pad_io_init(touch_pad_t touch_num)
Initialize touch pad GPIO.
Return
Parameters
esp_err_t touch_pad_set_voltage(touch_high_volt_t refh, touch_low_volt_t refl, touch_volt_atten_t
atten)
Set touch sensor high voltage threshold of chanrge. The touch sensor measures the channel capacitance value
by charging and discharging the channel. So the high threshold should be less than the supply voltage.
Return
Parameters
• refh: the value of DREFH
• refl: the value of DREFL

• atten: the attenuation on DREFH

esp_err_t touch_pad_get_voltage(touch_high_volt_t *refh, touch_low_volt_t *refl,
touch_volt_atten_t *atten)
Get touch sensor reference voltage,.
Return
Parameters
• refh: pointer to accept DREFH value
• refl: pointer to accept DREFL value
• atten: pointer to accept the attenuation on DREFH
esp_err_t touch_pad_set_cnt_mode(touch_pad_t touch_num, touch_cnt_slope_t slope,
touch_tie_opt_t opt)
Set touch sensor charge/discharge speed for each pad. If the slope is 0, the counter would always be zero.
If the slope is 1, the charging and discharging would be slow, accordingly. If the slope is set 7, which is the
maximum value, the charging and discharging would be fast.
Note The higher the charge and discharge current, the greater the immunity of the touch channel, but it will
increase the system power consumption.
Return
Parameters
• slope: touch pad charge/discharge speed
• opt: the initial voltage
esp_err_t touch_pad_get_cnt_mode(touch_pad_t touch_num, touch_cnt_slope_t *slope,
touch_tie_opt_t *opt)
Get touch sensor charge/discharge speed for each pad.
Return
Parameters
• slope: pointer to accept touch pad charge/discharge slope
• opt: pointer to accept the initial voltage
esp_err_t touch_pad_isr_deregister(void (*fn))void *
, void *argDeregister the handler previously registered using touch_pad_isr_handler_register.
Return
• ESP_ERR_INVALID_STATE if a handler matching both fn and arg isn t registered
Parameters
• fn: handler function to call (as passed to touch_pad_isr_handler_register)
• arg: argument of the handler (as passed to touch_pad_isr_handler_register)
esp_err_t touch_pad_get_wakeup_status(touch_pad_t *pad_num)
Get the touch pad which caused wakeup from deep sleep.
Return
• ESP_OK Success
• ESP_ERR_INVALID_ARG parameter is NULL
Parameters
• pad_num: pointer to touch pad which caused wakeup
esp_err_t touch_pad_set_fsm_mode(touch_fsm_mode_t mode)
Set touch sensor FSM mode, the test action can be triggered by the timer, as well as by the software.
Return


Parameters
• mode: FSM mode
esp_err_t touch_pad_get_fsm_mode(touch_fsm_mode_t *mode)
Get touch sensor FSM mode.
Return
Parameters
• mode: pointer to accept FSM mode
esp_err_t touch_pad_clear_status(void)
To clear the touch sensor channel active status.
Note The FSM automatically updates the touch sensor status. It is generally not necessary to call this API to
clear the status.
Return
uint32_t touch_pad_get_status(void)
Get the touch sensor channel active status mask. The bit position represents the channel number. The 0/1
status of the bit represents the trigger status.
Return
• The touch sensor status. e.g. Touch1 trigger status is status_mask & (BIT1).
bool touch_pad_meas_is_done(void)
Check touch sensor measurement status.
Return
• True measurement is under way
• False measurement done
GPIO Lookup Macros Some useful macros can be used to specified the GPIO number of a touch pad channel,
or vice versa. e.g.
1. TOUCH_PAD_NUM5_GPIO_NUM is the GPIO number of channel 5 (12);
2. TOUCH_PAD_GPIO4_CHANNEL is the channel number of GPIO 4 (channel 0).
Header File
• components/soc/esp32/include/soc/touch_sensor_channel.h
Macros
TOUCH_PAD_GPIO4_CHANNEL
TOUCH_PAD_NUM0_GPIO_NUM

Header File
• components/hal/include/hal/touch_sensor_types.h
Macros
TOUCH_PAD_BIT_MASK_ALL
TOUCH_PAD_SLOPE_DEFAULT
TOUCH_PAD_TIE_OPT_DEFAULT
TOUCH_PAD_BIT_MASK_MAX
TOUCH_PAD_HIGH_VOLTAGE_THRESHOLD
TOUCH_PAD_LOW_VOLTAGE_THRESHOLD
TOUCH_PAD_ATTEN_VOLTAGE_THRESHOLD
TOUCH_PAD_IDLE_CH_CONNECT_DEFAULT
TOUCH_PAD_THRESHOLD_MAX
If set touch threshold max value, The touch sensor can t be in touched status
TOUCH_PAD_SLEEP_CYCLE_DEFAULT
The timer frequency is RTC_SLOW_CLK (can be 150k or 32k depending on the options), max value is 0xffff
TOUCH_PAD_MEASURE_CYCLE_DEFAULT
The timer frequency is 8Mhz, the max value is 0x7fff
TOUCH_FSM_MODE_DEFAULT
The touch FSM my be started by the software or timer
TOUCH_TRIGGER_MODE_DEFAULT
Interrupts can be triggered if sensor value gets below or above threshold
TOUCH_TRIGGER_SOURCE_DEFAULT
The wakeup trigger source can be SET1 or both SET1 and SET2
Enumerations
enum touch_pad_t
Touch pad channel
Values:
TOUCH_PAD_NUM0 = 0
Touch pad channel 0 is GPIO4(ESP32)
TOUCH_PAD_NUM1
Touch pad channel 1 is GPIO0(ESP32) / GPIO1(ESP32-S2)

TOUCH_PAD_NUM2
TOUCH_PAD_NUM3
TOUCH_PAD_NUM4
TOUCH_PAD_NUM5
TOUCH_PAD_NUM6
TOUCH_PAD_NUM7
TOUCH_PAD_NUM8
TOUCH_PAD_NUM9
TOUCH_PAD_MAX
enum touch_high_volt_t
Touch sensor high reference voltage
Values:
TOUCH_HVOLT_KEEP = -1
Touch sensor high reference voltage, no change
TOUCH_HVOLT_2V4 = 0
Touch sensor high reference voltage, 2.4V
TOUCH_HVOLT_2V5
TOUCH_HVOLT_2V6
TOUCH_HVOLT_2V7
TOUCH_HVOLT_MAX
enum touch_low_volt_t
Touch sensor low reference voltage
Values:
TOUCH_LVOLT_KEEP = -1
Touch sensor low reference voltage, no change
TOUCH_LVOLT_0V5 = 0
Touch sensor low reference voltage, 0.5V
TOUCH_LVOLT_0V6
TOUCH_LVOLT_0V7
TOUCH_LVOLT_0V8
TOUCH_LVOLT_MAX

enum touch_volt_atten_t
Touch sensor high reference voltage attenuation
Values:
TOUCH_HVOLT_ATTEN_KEEP = -1
Touch sensor high reference voltage attenuation, no change
TOUCH_HVOLT_ATTEN_1V5 = 0
Touch sensor high reference voltage attenuation, 1.5V attenuation
TOUCH_HVOLT_ATTEN_1V
TOUCH_HVOLT_ATTEN_0V5
TOUCH_HVOLT_ATTEN_0V
Touch sensor high reference voltage attenuation, 0V attenuation
TOUCH_HVOLT_ATTEN_MAX
enum touch_cnt_slope_t
Touch sensor charge/discharge speed
Values:
TOUCH_PAD_SLOPE_0 = 0
Touch sensor charge / discharge speed, always zero
Touch sensor charge / discharge speed, slowest
Touch sensor charge / discharge speed
Touch sensor charge / discharge speed, fast
TOUCH_PAD_SLOPE_MAX
enum touch_tie_opt_t
Touch sensor initial charge level
Values:
TOUCH_PAD_TIE_OPT_LOW = 0
Initial level of charging voltage, low level
TOUCH_PAD_TIE_OPT_HIGH = 1
Initial level of charging voltage, high level
TOUCH_PAD_TIE_OPT_MAX
enum touch_fsm_mode_t
Touch sensor FSM mode
Values:

TOUCH_FSM_MODE_TIMER = 0
To start touch FSM by timer
TOUCH_FSM_MODE_SW
To start touch FSM by software trigger
TOUCH_FSM_MODE_MAX
enum touch_trigger_mode_t
Values:
TOUCH_TRIGGER_BELOW = 0
Touch interrupt will happen if counter value is less than threshold.
TOUCH_TRIGGER_ABOVE = 1
Touch interrupt will happen if counter value is larger than threshold.
TOUCH_TRIGGER_MAX
enum touch_trigger_src_t
Values:
TOUCH_TRIGGER_SOURCE_BOTH = 0
wakeup interrupt is generated if both SET1 and SET2 are touched
TOUCH_TRIGGER_SOURCE_SET1 = 1
wakeup interrupt is generated if SET1 is touched
TOUCH_TRIGGER_SOURCE_MAX
2.3.21 Two-Wire Automotive Interface (TWAI)
Overview
The Two-Wire Automotive Interface (TWAI) is a real-time serial communication protocol suited for automotive and
industrial applications. It is compatible with ISO11898-1 Classical frames, thus can support Standard Frame Format
(11-bit ID) and Extended Frame Format (29-bit ID). The ESP32 s peripherals contains a TWAI controller that can
be configured to communicate on a TWAI bus via an external transceiver.
Warning: The TWAI controller is not compatible with ISO11898-1 FD Format frames, and will interpret such
frames as errors.
This programming guide is split into the following sections:

1. TWAI Protocol Summary
2. Signals Lines and Transceiver
3. Driver Configuration
4. Driver Operation
5. Examples
TWAI Protocol Summary
The TWAI is a multi-master, multi-cast, asynchronous, serial communication protocol. TWAI also supports error
detection and signalling, and inbuilt message prioritization.
Multi-master: Any node on the bus can initiate the transfer of a message.
Multi-cast: When a node transmits a message, all nodes on the bus will receive the message (i.e., broadcast) thus
ensuring data consistency across all nodes. However, some nodes can selectively choose which messages to accept
via the use of acceptance filtering (multi-cast).

Asynchronous: The bus does not contain a clock signal. All nodes on the bus operate at the same bit rate and
synchronize using the edges of the bits transmitted on the bus.
Error Detection and Signalling: Every node will constantly monitor the bus. When any node detects an error, it
will signal the detection by transmitting an error frame. Other nodes will receive the error frame and transmit their
own error frames in response. This will result in an error detection being propagated to all nodes on the bus.
Message Priorities: Messages contain an ID field. If two or more nodes attempt to transmit simultaneously, the
node transmitting the message with the lower ID value will win arbitration of the bus. All other nodes will become
receivers ensuring that there is at most one transmitter at any time.
TWAI Messages TWAI Messages are split into Data Frames and Remote Frames. Data Frames are used to deliver
a data payload to other nodes, whereas a Remote Frame is used to request a Data Frame from other nodes (other nodes
can optionally respond with a Data Frame). Data and Remote Frames have two frame formats known as Extended
Frame and Standard Frame which contain a 29-bit ID and an 11-bit ID respectively. A TWAI message consists of
the following fields:
• 29-bit or 11-bit ID: Determines the priority of the message (lower value has higher priority).
• Data Length Code (DLC) between 0 to 8: Indicates the size (in bytes) of the data payload for a Data Frame,
or the amount of data to request for a Remote Frame.
• Up to 8 bytes of data for a Data Frame (should match DLC).
Error States and Counters The TWAI protocol implements a feature known as fault confinement where a
persistently erroneous node will eventually eliminate itself form the bus. This is implemented by requiring every
node to maintain two internal error counters known as the Transmit Error Counter (TEC) and the Receive Error
Counter (REC). The two error counters are incremented and decremented according to a set of rules (where the
counters increase on an error, and decrease on a successful message transmission/reception). The values of the
counters are used to determine a node s error state, namely Error Active, Error Passive, and Bus-Off.
Error Active: A node is Error Active when both TEC and REC are less than 128 and indicates that the node is
operating normally. Error Active nodes are allowed to participate in bus communications, and will actively signal the
detection of any errors by automatically transmitting an Active Error Flag over the bus.
Error Passive: A node is Error Passive when either the TEC or REC becomes greater than or equal to 128.
Error Passive nodes are still able to take part in bus communications, but will instead transmit a Passive Error Flag
upon detection of an error.
Bus-Off: A node becomes Bus-Off when the TEC becomes greater than or equal to 256. A Bus-Off node is
unable influence the bus in any manner (essentially disconnected from the bus) thus eliminating itself from the bus.
A node will remain in the Bus-Off state until it undergoes bus-off recovery.
Signals Lines and Transceiver
The TWAI controller does not contain a integrated transceiver. Therefore, to connect the TWAI controller to a TWAI
bus, an external transceiver is required. The type of external transceiver used should depend on the application
s physical layer specification (e.g. using SN65HVD23x transceivers for ISO 11898-2 compatibility).
The TWAI controller s interface consists of 4 signal lines known as TX, RX, BUS-OFF, and CLKOUT. These
four signal lines can be routed through the GPIO Matrix to the ESP32 s GPIO pads.
TX and RX: The TX and RX signal lines are required to interface with an external transceiver. Both signal lines
represent/interpret a dominant bit as a low logic level (0V), and a recessive bit as a high logic level (3.3V).
BUS-OFF: The BUS-OFF signal line is optional and is set to a low logic level (0V) whenever the TWAI controller
reaches a bus-off state. The BUS-OFF signal line is set to a high logic level (3.3V) otherwise.
CLKOUT: The CLKOUT signal line is optional and outputs a prescaled version of the controller s source clock
(APB Clock).

Fig. 21: Signal lines of the TWAI controller
Note: An external transceiver must internally loopback the TX to RX such that a change in logic level to the TX
signal line can be observed on the RX line. Failing to do so will cause the TWAI controller to interpret differences
in logic levels between the two signal lines as a loss in arbitration or a bit error.
Driver Configuration
This section covers how to configure the TWAI driver.
Operating Modes The TWAI driver supports the following modes of operations:
Normal Mode: The normal operating mode allows the TWAI controller to take part in bus activities such as trans-
mitting and receiving messages/error frames. Acknowledgement from another node is required when transmitting a
message.
No Ack Mode: The No Acknowledgement mode is similar to normal mode, however acknowledgements are not
required for a message transmission to be considered successful. This mode is useful when self testing the TWAI
controller (loopback of transmissions).
Listen Only Mode: This mode will prevent the TWAI controller from influencing the bus. Therefore, transmission of
messages/acknowledgement/error frames will be disabled. However the TWAI controller will still be able to receive
messages but will not acknowledge the message. This mode is suited for bus monitor applications.
Alerts The TWAI driver contains an alert feature that is used to notify the application layer of certain TWAI con-
troller or TWAI bus events. Alerts are selectively enabled when the TWAI driver is installed, but can be reconfigured
during runtime by calling twai_reconfigure_alerts(). The application can then wait for any enabled alerts
to occur by calling twai_read_alerts(). The TWAI driver supports the following alerts:

Table 5: TWAI Driver Alerts

Alert Flag Description
TWAI_ALERT_TX_IDLE No more messages queued for transmission
TWAI_ALERT_TX_SUCCESS The previous transmission was successful
TWAI_ALERT_RX_DATA A frame has been received and added to the RX queue
TWAI_ALERT_BELOW_ERR_WARN Both error counters have dropped below error warning limit
TWAI_ALERT_ERR_ACTIVE TWAI controller has become error active
TWAI_ALERT_RECOVERY_IN_PROGRESSTWAI controller is undergoing bus recovery
TWAI_ALERT_BUS_RECOVERED TWAI controller has successfully completed bus recovery
TWAI_ALERT_ARB_LOST The previous transmission lost arbitration
TWAI_ALERT_ABOVE_ERR_WARN One of the error counters have exceeded the error warning limit
TWAI_ALERT_BUS_ERROR A (Bit, Stuff, CRC, Form, ACK) error has occurred on the bus
TWAI_ALERT_TX_FAILED The previous transmission has failed
TWAI_ALERT_RX_QUEUE_FULL The RX queue is full causing a received frame to be lost
TWAI_ALERT_ERR_PASS TWAI controller has become error passive
TWAI_ALERT_BUS_OFF Bus-off condition occurred. TWAI controller can no longer influ-
ence bus
Note: The TWAI controller s error warning limit is used to preemptively warn the application of bus errors
before the error passive state is reached. By default, the TWAI driver sets the error warning limit to 96. The
TWAI_ALERT_ABOVE_ERR_WARN is raised when the TEC or REC becomes larger then or equal to the error
warning limit. The TWAI_ALERT_BELOW_ERR_WARN is raised when both TEC and REC return back to values
below 96.
Note: When enabling alerts, the TWAI_ALERT_AND_LOG flag can be used to cause the TWAI driver to
log any raised alerts to UART. However, alert logging is disabled and TWAI_ALERT_AND_LOG if the CON-
FIG_TWAI_ISR_IN_IRAM option is enabled (see Placing ISR into IRAM).
Note: The TWAI_ALERT_ALL and TWAI_ALERT_NONE macros can also be used to enable/disable all alerts
during configuration/reconfiguration.
Bit Timing The operating bit rate of the TWAI driver is configured using the twai_timing_config_t struc-
ture. The period of each bit is made up of multiple time quanta, and the period of a time quantum is determined
by a prescaled version of the TWAI controller s source clock. A single bit contains the following segments in the
following order:
1. The Synchronization Segment consists of a single time quantum
2. Timing Segment 1 consists of 1 to 16 time quanta before sample point
3. Timing Segment 2 consists of 1 to 8 time quanta after sample point
The Baudrate Prescaler is used to determine the period of each time quantum by dividing the TWAI controller s
source clock (80 MHz APB clock). On the ESP32, the brp can be any even number from 2 to 128.
If the ESP32 is a revision 2 or later chip, the brp will also support any multiple of 4 from 132 to 256, and can be
enabled by setting the CONFIG_ESP32_REV_MIN to revision 2 or higher.
The sample point of a bit is located on the intersection of Timing Segment 1 and 2. Enabling Triple Sampling will
cause 3 time quanta to be sampled per bit instead of 1 (extra samples are located at the tail end of Timing Segment
1).
The Synchronization Jump Width is used to determine the maximum number of time quanta a single bit time can
be lengthened/shortened for synchronization purposes. sjw can range from 1 to 4.

Fig. 22: Bit timing configuration for 500kbit/s given BRP = 8
Note: Multiple combinations of brp, tseg_1, tseg_2, and sjw can achieve the same bit rate. Users should
tune these values to the physical characteristics of their bus by taking into account factors such as propagation delay,
node information processing time, and phase errors.
Bit timing macro initializers are also available for commonly used bit rates. The following macro initializers are
provided by the TWAI driver.
• TWAI_TIMING_CONFIG_1MBITS()
• TWAI_TIMING_CONFIG_800KBITS()
Revision 2 or later of the ESP32 also supports the following bit rates:
• TWAI_TIMING_CONFIG_12_5KBITS()
Acceptance Filter The TWAI controller contains a hardware acceptance filter which can be used to filter messages
of a particular ID. A node that filters out a message will not receive the message, but will still acknowledge it.
Acceptance filters can make a node more efficient by filtering out messages sent over the bus that are irrelevant to the
node. The acceptance filter is configured using two 32-bit values within twai_filter_config_t known as the
acceptance code and the acceptance mask.
The acceptance code specifies the bit sequence which a message s ID, RTR, and data bytes must match in order
for the message to be received by the TWAI controller. The acceptance mask is a bit sequence specifying which
bits of the acceptance code can be ignored. This allows for a messages of different IDs to be accepted by a single
acceptance code.
The acceptance filter can be used under Single or Dual Filter Mode. Single Filter Mode will use the acceptance
code and mask to define a single filter. This allows for the first two data bytes of a standard frame to be filtered, or
the entirety of an extended frame s 29-bit ID. The following diagram illustrates how the 32-bit acceptance code and
mask will be interpreted under Single Filter Mode (Note: The yellow and blue fields represent standard and extended
frame formats respectively).
Fig. 23: Bit layout of single filter mode (Right side MSBit)

Dual Filter Mode will use the acceptance code and mask to define two separate filters allowing for increased flexi-
bility of ID s to accept, but does not allow for all 29-bits of an extended ID to be filtered. The following diagram
illustrates how the 32-bit acceptance code and mask will be interpreted under Dual Filter Mode (Note: The yellow
and blue fields represent standard and extended frame formats respectively).
Fig. 24: Bit layout of dual filter mode (Right side MSBit)
Disabling TX Queue The TX queue can be disabled during configuration by setting the tx_queue_len member
of twai_general_config_t to 0. This will allow applications that do not require message transmission to save
a small amount of memory when using the TWAI driver.
Placing ISR into IRAM The TWAI driver s ISR (Interrupt Service Routine) can be placed into IRAM so that
the ISR can still run whilst the cache is disabled. Placing the ISR into IRAM may be necessary to maintain the TWAI
driver s functionality during lengthy cache disabling operations (such as SPI Flash writes, OTA updates etc). Whilst
the cache is disabled, the ISR will continue to:
• Read received messages from the RX buffer and place them into the driver s RX queue.
• Load messages pending transmission from the driver s TX queue and write them into the TX buffer.
To place the TWAI driver s ISR, users must do the following:
• Enable the CONFIG_TWAI_ISR_IN_IRAM option using idf.py menuconfig.
• When calling twai_driver_install(), the intr_flags member of twai_general_config_t
should set the ESP_INTR_FLAG_IRAM set.
Note: When the CONFIG_TWAI_ISR_IN_IRAM option is enabled, the TWAI driver will no longer log any alerts
(i.e., the TWAI_ALERT_AND_LOG flag will not have any effect).
Driver Operation
The TWAI driver is designed with distinct states and strict rules regarding the functions or conditions that trigger a
state transition. The following diagram illustrates the various states and their transitions.
Fig. 25: State transition diagram of the TWAI driver (see table below)

Label Transition Action/Condition

A Uninstalled -> Stopped twai_driver_install()
B Stopped -> Uninstalled twai_driver_uninstall()
C Stopped -> Running twai_start()
D Running -> Stopped twai_stop()
E Running -> Bus-Off Transmit Error Counter >= 256
F Bus-Off -> Uninstalled twai_driver_uninstall()
G Bus-Off -> Recovering twai_initiate_recovery()
H Recovering -> Stopped 128 occurrences of 11 consecutive reces-
sive bits.
Driver States Uninstalled: In the uninstalled state, no memory is allocated for the driver and the TWAI controller
is powered OFF.
Stopped: In this state, the TWAI controller is powered ON and the TWAI driver has been installed. However the
TWAI controller will be unable to take part in any bus activities such as transmitting, receiving, or acknowledging
messages.
Running: In the running state, the TWAI controller is able to take part in bus activities. Therefore messages can
be transmitted/received/acknowledged. Furthermore the TWAI controller will be able to transmit error frames upon
detection of errors on the bus.
Bus-Off: The bus-off state is automatically entered when the TWAI controller s Transmit Error Counter becomes
greater than or equal to 256. The bus-off state indicates the occurrence of severe errors on the bus or in the TWAI
controller. Whilst in the bus-off state, the TWAI controller will be unable to take part in any bus activities. To exit
the bus-off state, the TWAI controller must undergo the bus recovery process.
Recovering: The recovering state is entered when the TWAI controller undergoes bus recovery. The TWAI con-
troller/TWAI driver will remain in the recovering state until the 128 occurrences of 11 consecutive recessive bits is
observed on the bus.
Message Fields and Flags The TWAI driver distinguishes different types of messages by using the various bit field
members of the twai_message_t structure. These bit field members determine whether a message is in standard
or extended format, a remote frame, and the type of transmission to use when transmitting such a message.
These bit field members can also be toggled using the the flags member of twai_message_t and the following
message flags:
Message Flag Description

TWAI_MSG_FLAG_EXTD Message is in Extended Frame Format (29bit ID)
TWAI_MSG_FLAG_RTR Message is a Remote Frame (Remote Transmission Request)
TWAI_MSG_FLAG_SS Transmit message using Single Shot Transmission (Message will not be retrans-
mitted upon error or loss of arbitration). Unused for received message.
TWAI_MSG_FLAG_SELF Transmit message using Self Reception Request (Transmitted message will also
received by the same node). Unused for received message.
TWAI_MSG_FLAG_DLC_NON_COMP
Message s Data length code is larger than 8. This will break compliance with
TWAI
TWAI_MSG_FLAG_NONE Clears all bit fields. Equivalent to a Standard Frame Format (11bit ID) Data
Frame.
Examples
Configuration & Installation The following code snippet demonstrates how to configure, install,
and start the TWAI driver via the use of the various configuration structures, macro initializers, the
twai_driver_install() function, and the twai_start() function.

#include "driver/gpio.h"
#include "driver/twai.h"
void app_main()
{
//Initialize configuration structures using macro initializers
twai_general_config_t g_config = TWAI_GENERAL_CONFIG_DEFAULT(GPIO_NUM_21, GPIO_
,→NUM_22, TWAI_MODE_NORMAL);
twai_timing_config_t t_config = TWAI_TIMING_CONFIG_500KBITS();

twai_filter_config_t f_config = TWAI_FILTER_CONFIG_ACCEPT_ALL();
//Install TWAI driver

if (twai_driver_install(&g_config, &t_config, &f_config) == ESP_OK) {
printf("Driver installed\n");
} else {
printf("Failed to install driver\n");
return;
}
//Start TWAI driver

if (twai_start() == ESP_OK) {
printf("Driver started\n");
} else {
printf("Failed to start driver\n");
return;
}
...
The usage of macro initializers is not mandatory and each of the configuration structures can be manually.
Message Transmission The following code snippet demonstrates how to transmit a message via the usage of the
twai_message_t type and twai_transmit() function.
...
//Configure message to transmit

twai_message_t message;
message.identifier = 0xAAAA;
message.extd = 1;
message.data_length_code = 4;
for (int i = 0; i < 4; i++) {
message.data[i] = 0;
}
//Queue message for transmission

if (twai_transmit(&message, pdMS_TO_TICKS(1000)) == ESP_OK) {
printf("Message queued for transmission\n");
} else {
printf("Failed to queue message for transmission\n");
}
Message Reception The following code snippet demonstrates how to receive a message via the usage of the
twai_message_t type and twai_receive() function.

...
//Wait for message to be received

twai_message_t message;
if (twai_receive(&message, pdMS_TO_TICKS(10000)) == ESP_OK) {
printf("Message received\n");
} else {
printf("Failed to receive message\n");
return;
}
//Process received message

if (message.extd) {
printf("Message is in Extended Format\n");
} else {
printf("Message is in Standard Format\n");
}
printf("ID is %d\n", message.identifier);
if (!(message.rtr)) {
for (int i = 0; i < message.data_length_code; i++) {
printf("Data byte %d = %d\n", i, message.data[i]);
}
}
Reconfiguring and Reading Alerts The following code snippet demonstrates how to reconfigure and read TWAI
driver alerts via the use of the twai_reconfigure_alerts() and twai_read_alerts() functions.
...
//Reconfigure alerts to detect Error Passive and Bus-Off error states

uint32_t alerts_to_enable = TWAI_ALERT_ERR_PASS | TWAI_ALERT_BUS_OFF;
if (twai_reconfigure_alerts(alerts_to_enable, NULL) == ESP_OK) {
printf("Alerts reconfigured\n");
} else {
printf("Failed to reconfigure alerts");
}
//Block indefinitely until an alert occurs

uint32_t alerts_triggered;
twai_read_alerts(&alerts_triggered, portMAX_DELAY);
Stop and Uninstall The following code demonstrates how to stop and uninstall the TWAI driver via the use of the
twai_stop() and twai_driver_uninstall() functions.
...
//Stop the TWAI driver

if (twai_stop() == ESP_OK) {
printf("Driver stopped\n");
} else {
printf("Failed to stop driver\n");
return;
}

//Uninstall the TWAI driver

if (twai_driver_uninstall() == ESP_OK) {
printf("Driver uninstalled\n");
} else {
printf("Failed to uninstall driver\n");
return;
}
Multiple ID Filter Configuration The acceptance mask in twai_filter_config_t can be configured such
that two or more IDs will be accepted for a single filter. For a particular filter to accept multiple IDs, the conflicting
bit positions amongst the IDs must be set in the acceptance mask. The acceptance code can be set to any one of the
IDs.
The following example shows how the calculate the acceptance mask given multiple IDs:
ID1 = 11'b101 1010 0000

ID2 = 11'b101 1010 0001
ID3 = 11'b101 1010 0100
ID4 = 11'b101 1010 1000
//Acceptance Mask
MASK = 11'b000 0000 1101
Application Examples Network Example: The TWAI Network example demonstrates communication between
two ESP32s using the TWAI driver API. One TWAI node acts as a network master that initiates and ceases the transfer
of a data from another node acting as a network slave. The example can be found via peripherals/twai/twai_network.
Alert and Recovery Example: This example demonstrates how to use the TWAI driver s alert and bus-off re-
covery API. The example purposely introduces errors on the bus to put the TWAI controller into the Bus-Off state.
An alert is used to detect the Bus-Off state and trigger the bus recovery process. The example can be found via
peripherals/twai/twai_alert_and_recovery.
Self Test Example: This example uses the No Acknowledge Mode and Self Reception Request to cause the TWAI
controller to send and simultaneously receive a series of messages. This example can be used to verify if the connec-
tions between the TWAI controller and the external transceiver are working correctly. The example can be found via
peripherals/twai/twai_self_test.
API Reference
Header File
• components/hal/include/hal/twai_types.h
Structures
struct twai_message_t
Structure to store a TWAI message.
Note The flags member is deprecated
Public Members
uint32_t extd : 1
Extended Frame Format (29bit ID)
uint32_t rtr : 1
Message is a Remote Frame

uint32_t ss : 1
Transmit as a Single Shot Transmission. Unused for received.
uint32_t self : 1
Transmit as a Self Reception Request. Unused for received.
uint32_t dlc_non_comp : 1
Message s Data length code is larger than 8. This will break compliance with ISO 11898-1
Reserved bits
uint32_t flags
Deprecated: Alternate way to set bits using message flags
uint32_t identifier
11 or 29 bit identifier
uint8_t data_length_code
Data length code
uint8_t data[TWAI_FRAME_MAX_DLC]
Data bytes (not relevant in RTR frame)
struct twai_timing_config_t
Structure for bit timing configuration of the TWAI driver.
Note Macro initializers are available for this structure
Public Members
uint32_t brp
Baudrate prescaler (i.e., APB clock divider). Any even number from 2 to 128 for ESP32, 2 to 32768 for
ESP32S2. For ESP32 Rev 2 or later, multiples of 4 from 132 to 256 are also supported
uint8_t tseg_1
Timing segment 1 (Number of time quanta, between 1 to 16)
uint8_t tseg_2
Timing segment 2 (Number of time quanta, 1 to 8)
uint8_t sjw
Synchronization Jump Width (Max time quanta jump for synchronize from 1 to 4)
bool triple_sampling
Enables triple sampling when the TWAI controller samples a bit
struct twai_filter_config_t
Structure for acceptance filter configuration of the TWAI driver (see documentation)
Public Members
uint32_t acceptance_code
32-bit acceptance code
uint32_t acceptance_mask
32-bit acceptance mask
bool single_filter
Use Single Filter Mode (see documentation)

Macros
TWAI_EXTD_ID_MASK
TWAI Constants.
Bit mask for 29 bit Extended Frame Format ID
TWAI_STD_ID_MASK
Bit mask for 11 bit Standard Frame Format ID
TWAI_FRAME_MAX_DLC
Max data bytes allowed in TWAI
TWAI_FRAME_EXTD_ID_LEN_BYTES
EFF ID requires 4 bytes (29bit)
TWAI_FRAME_STD_ID_LEN_BYTES
SFF ID requires 2 bytes (11bit)
TWAI_ERR_PASS_THRESH
Error counter threshold for error passive
Enumerations
enum twai_mode_t
TWAI Controller operating modes.
Values:
TWAI_MODE_NORMAL
Normal operating mode where TWAI controller can send/receive/acknowledge messages
TWAI_MODE_NO_ACK
Transmission does not require acknowledgment. Use this mode for self testing
TWAI_MODE_LISTEN_ONLY
The TWAI controller will not influence the bus (No transmissions or acknowledgments) but can receive
messages
Header File
• components/driver/include/driver/twai.h
Functions
esp_err_t twai_driver_install(const twai_general_config_t *g_config, const
twai_timing_config_t *t_config, const twai_filter_config_t
*f_config)
Install TWAI driver.
This function installs the TWAI driver using three configuration structures. The required memory is allocated
and the TWAI driver is placed in the stopped state after running this function.
Note Macro initializers are available for the configuration structures (see documentation)
Note To reinstall the TWAI driver, call twai_driver_uninstall() first
Return
• ESP_OK: Successfully installed TWAI driver
• ESP_ERR_INVALID_ARG: Arguments are invalid
• ESP_ERR_NO_MEM: Insufficient memory
• ESP_ERR_INVALID_STATE: Driver is already installed
Parameters
• [in] g_config: General configuration structure
• [in] t_config: Timing configuration structure
• [in] f_config: Filter configuration structure

esp_err_t twai_driver_uninstall(void)
Uninstall the TWAI driver.
This function uninstalls the TWAI driver, freeing the memory utilized by the driver. This function can only be
called when the driver is in the stopped state or the bus-off state.
Warning The application must ensure that no tasks are blocked on TX/RX queues or alerts when this function
is called.
Return
• ESP_OK: Successfully uninstalled TWAI driver
• ESP_ERR_INVALID_STATE: Driver is not in stopped/bus-off state, or is not installed
esp_err_t twai_start(void)
Start the TWAI driver.
This function starts the TWAI driver, putting the TWAI driver into the running state. This allows the TWAI
driver to participate in TWAI bus activities such as transmitting/receiving messages. The TX and RX queue
are reset in this function, clearing any messages that are unread or pending transmission. This function can
only be called when the TWAI driver is in the stopped state.
Return
• ESP_OK: TWAI driver is now running
• ESP_ERR_INVALID_STATE: Driver is not in stopped state, or is not installed
esp_err_t twai_stop(void)
Stop the TWAI driver.
This function stops the TWAI driver, preventing any further message from being transmitted or received until
twai_start() is called. Any messages in the TX queue are cleared. Any messages in the RX queue should be
read by the application after this function is called. This function can only be called when the TWAI driver is
in the running state.
Warning A message currently being transmitted/received on the TWAI bus will be ceased immediately. This
may lead to other TWAI nodes interpreting the unfinished message as an error.
Return
• ESP_OK: TWAI driver is now Stopped
• ESP_ERR_INVALID_STATE: Driver is not in running state, or is not installed
esp_err_t twai_transmit(const twai_message_t *message, TickType_t ticks_to_wait)
Transmit a TWAI message.
This function queues a TWAI message for transmission. Transmission will start immediately if no other mes-
sages are queued for transmission. If the TX queue is full, this function will block until more space becomes
available or until it times out. If the TX queue is disabled (TX queue length = 0 in configuration), this function
will return immediately if another message is undergoing transmission. This function can only be called when
the TWAI driver is in the running state and cannot be called under Listen Only Mode.
Note This function does not guarantee that the transmission is successful. The TX_SUCCESS/TX_FAILED
alert can be enabled to alert the application upon the success/failure of a transmission.
Note The TX_IDLE alert can be used to alert the application when no other messages are awaiting transmis-
sion.
Return
• ESP_OK: Transmission successfully queued/initiated
• ESP_ERR_TIMEOUT: Timed out waiting for space on TX queue
• ESP_FAIL: TX queue is disabled and another message is currently transmitting
• ESP_ERR_INVALID_STATE: TWAI driver is not in running state, or is not installed
• ESP_ERR_NOT_SUPPORTED: Listen Only Mode does not support transmissions
Parameters
• [in] message: Message to transmit
• [in] ticks_to_wait: Number of FreeRTOS ticks to block on the TX queue
esp_err_t twai_receive(twai_message_t *message, TickType_t ticks_to_wait)
Receive a TWAI message.

This function receives a message from the RX queue. The flags field of the message structure will indicate the
type of message received. This function will block if there are no messages in the RX queue
Warning The flags field of the received message should be checked to determine if the received message
contains any data bytes.
Return
• ESP_OK: Message successfully received from RX queue
• ESP_ERR_TIMEOUT: Timed out waiting for message
• ESP_ERR_INVALID_STATE: TWAI driver is not installed
Parameters
• [out] message: Received message
• [in] ticks_to_wait: Number of FreeRTOS ticks to block on RX queue
esp_err_t twai_read_alerts(uint32_t *alerts, TickType_t ticks_to_wait)
Read TWAI driver alerts.
This function will read the alerts raised by the TWAI driver. If no alert has been issued when this function is
called, this function will block until an alert occurs or until it timeouts.
Note Multiple alerts can be raised simultaneously. The application should check for all alerts that have been
enabled.
Return
• ESP_OK: Alerts read
• ESP_ERR_TIMEOUT: Timed out waiting for alerts
Parameters
• [out] alerts: Bit field of raised alerts (see documentation for alert flags)
• [in] ticks_to_wait: Number of FreeRTOS ticks to block for alert
esp_err_t twai_reconfigure_alerts(uint32_t alerts_enabled, uint32_t *current_alerts)
Reconfigure which alerts are enabled.
This function reconfigures which alerts are enabled. If there are alerts which have not been read whilst recon-
figuring, this function can read those alerts.
Return
• ESP_OK: Alerts reconfigured
Parameters
• [in] alerts_enabled: Bit field of alerts to enable (see documentation for alert flags)
• [out] current_alerts: Bit field of currently raised alerts. Set to NULL if unused
esp_err_t twai_initiate_recovery(void)
Start the bus recovery process.
This function initiates the bus recovery process when the TWAI driver is in the bus-off state. Once initiated,
the TWAI driver will enter the recovering state and wait for 128 occurrences of the bus-free signal on the
TWAI bus before returning to the stopped state. This function will reset the TX queue, clearing any messages
pending transmission.
Note The BUS_RECOVERED alert can be enabled to alert the application when the bus recovery process
completes.
Return
• ESP_OK: Bus recovery started
• ESP_ERR_INVALID_STATE: TWAI driver is not in the bus-off state, or is not installed
esp_err_t twai_get_status_info(twai_status_info_t *status_info)
Get current status information of the TWAI driver.
Return
• ESP_OK: Status information retrieved


Parameters
• [out] status_info: Status information
esp_err_t twai_clear_transmit_queue(void)
Clear the transmit queue.
This function will clear the transmit queue of all messages.
Note The transmit queue is automatically cleared when twai_stop() or twai_initiate_recovery() is called.
Return
• ESP_OK: Transmit queue cleared
• ESP_ERR_INVALID_STATE: TWAI driver is not installed or TX queue is disabled
esp_err_t twai_clear_receive_queue(void)
Clear the receive queue.
This function will clear the receive queue of all messages.
Note The receive queue is automatically cleared when twai_start() is called.
Return
• ESP_OK: Transmit queue cleared
Structures
struct twai_general_config_t
Structure for general configuration of the TWAI driver.
Public Members
twai_mode_t mode
Mode of TWAI controller
gpio_num_t tx_io
Transmit GPIO number
gpio_num_t rx_io
Receive GPIO number
gpio_num_t clkout_io
CLKOUT GPIO number (optional, set to -1 if unused)
gpio_num_t bus_off_io
Bus off indicator GPIO number (optional, set to -1 if unused)
uint32_t tx_queue_len
Number of messages TX queue can hold (set to 0 to disable TX Queue)
uint32_t rx_queue_len
Number of messages RX queue can hold
uint32_t alerts_enabled
Bit field of alerts to enable (see documentation)
uint32_t clkout_divider
CLKOUT divider. Can be 1 or any even number from 2 to 14 (optional, set to 0 if unused)
int intr_flags
Interrupt flags to set the priority of the driver s ISR. Note that to use the ESP_INTR_FLAG_IRAM,
the CONFIG_TWAI_ISR_IN_IRAM option should be enabled first.
struct twai_status_info_t
Structure to store status information of TWAI driver.

Public Members
twai_state_t state
Current state of TWAI controller (Stopped/Running/Bus-Off/Recovery)
uint32_t msgs_to_tx
Number of messages queued for transmission or awaiting transmission completion
uint32_t msgs_to_rx
Number of messages in RX queue waiting to be read
uint32_t tx_error_counter
Current value of Transmit Error Counter
uint32_t rx_error_counter
Current value of Receive Error Counter
uint32_t tx_failed_count
Number of messages that failed transmissions
uint32_t rx_missed_count
Number of messages that were lost due to a full RX queue (or errata workaround if enabled)
uint32_t rx_overrun_count
Number of messages that were lost due to a RX FIFO overrun
uint32_t arb_lost_count
Number of instances arbitration was lost
uint32_t bus_error_count
Number of instances a bus error has occurred
Macros
TWAI_IO_UNUSED
Marks GPIO as unused in TWAI configuration
Enumerations
enum twai_state_t
TWAI driver states.
Values:
TWAI_STATE_STOPPED
Stopped state. The TWAI controller will not participate in any TWAI bus activities
TWAI_STATE_RUNNING
Running state. The TWAI controller can transmit and receive messages
TWAI_STATE_BUS_OFF
Bus-off state. The TWAI controller cannot participate in bus activities until it has recovered
TWAI_STATE_RECOVERING
Recovering state. The TWAI controller is undergoing bus recovery
2.3.22 Universal Asynchronous Receiver/Transmitter (UART)
Overview
A Universal Asynchronous Receiver/Transmitter (UART) is a hardware feature that handles communication (i.e.,
timing requirements and data framing) using widely-adopted asynchronous serial communication interfaces, such as
RS232, RS422, RS485. A UART provides a widely adopted and cheap method to realize full-duplex or half-duplex
data exchange among different devices.

The ESP32 chip has three UART controllers (UART0, UART1, and UART2), each featuring an identical set of
registers to simplify programming and for more flexibility.
Each UART controller is independently configurable with parameters such as baud rate, data bit length, bit ordering,
number of stop bits, parity bit etc. All the controllers are compatible with UART-enabled devices from various
manufacturers and can also support Infrared Data Association protocols (IrDA).
Functional Overview
The following overview describes how to establish communication between an ESP32 and other UART devices using
the functions and data types of the UART driver. The overview reflects a typical programming workflow and is broken
down into the sections provided below:
1. Setting Communication Parameters - Setting baud rate, data bits, stop bits, etc.
2. Setting Communication Pins - Assigning pins for connection to a device.
3. Driver Installation - Allocating ESP32 s resources for the UART driver.
4. Running UART Communication - Sending / receiving data
5. Using Interrupts - Triggering interrupts on specific communication events
6. Deleting a Driver - Freeing allocated resources if a UART communication is no longer required
Steps 1 to 3 comprise the configuration stage. Step 4 is where the UART starts operating. Steps 5 and 6 are optional.
The UART driver s functions identify each of the UART controllers using uart_port_t. This identification is
needed for all the following function calls.
Setting Communication Parameters UART communication parameters can be configured all in a single step or
individually in multiple steps.
Single Step Call the function uart_param_config() and pass to it a uart_config_t structure. The
uart_config_t structure should contain all the required parameters. See the example below.
const uart_port_t uart_num = UART_NUM_2;

uart_config_t uart_config = {
.baud_rate = 115200,
.data_bits = UART_DATA_8_BITS,
.parity = UART_PARITY_DISABLE,
.stop_bits = UART_STOP_BITS_1,
.flow_ctrl = UART_HW_FLOWCTRL_CTS_RTS,
.rx_flow_ctrl_thresh = 122,
};
// Configure UART parameters
ESP_ERROR_CHECK(uart_param_config(uart_num, &uart_config));
Multiple Steps Configure specific parameters individually by calling a dedicated function from the table given
below. These functions are also useful if re-configuring a single parameter.
Table 6: Functions for Configuring specific parameters individually

Parameter to Configure Function
Baud rate uart_set_baudrate()
Number of transmitted bits uart_set_word_length() selected out of uart_word_length_t
Parity control uart_set_parity() selected out of uart_parity_t
Number of stop bits uart_set_stop_bits() selected out of uart_stop_bits_t
Hardware flow control mode uart_set_hw_flow_ctrl() selected out of
uart_hw_flowcontrol_t
Communication mode uart_set_mode() selected out of uart_mode_t

Each of the above functions has a _get_ counterpart to check the currently set value. For example, to check the
current baud rate value, call uart_get_baudrate().
Setting Communication Pins After setting communication parameters, configure the physical GPIO pins to which
the other UART device will be connected. For this, call the function uart_set_pin() and specify the GPIO pin
numbers to which the driver should route the Tx, Rx, RTS, and CTS signals. If you want to keep a currently allocated
pin number for a specific signal, pass the macro UART_PIN_NO_CHANGE.
The same macro should be specified for pins that will not be used.
// Set UART pins(TX: IO4, RX: IO5, RTS: IO18, CTS: IO19)
ESP_ERROR_CHECK(uart_set_pin(UART_NUM_2, 4, 5, 18, 19));
Driver Installation Once the communication pins are set, install the driver by calling
uart_driver_install() and specify the following parameters:
• Size of Tx ring buffer
• Size of Rx ring buffer
• Event queue handle and size
• Flags to allocate an interrupt
The function will allocate the required internal resources for the UART driver.
// Setup UART buffered IO with event queue

const int uart_buffer_size = (1024 * 2);
QueueHandle_t uart_queue;
// Install UART driver using an event queue here
ESP_ERROR_CHECK(uart_driver_install(UART_NUM_2, uart_buffer_size, \
uart_buffer_size, 10, &uart_queue, 0));
Once this step is complete, you can connect the external UART device and check the communication.
Running UART Communication Serial communication is controlled by each UART controller s finite state
machine (FSM).
The process of sending data involves the following steps:
1. Write data into Tx FIFO buffer
2. FSM serializes the data
3. FSM sends the data out
The process of receiving data is similar, but the steps are reversed:
1. FSM processes an incoming serial stream and parallelizes it
2. FSM writes the data into Rx FIFO buffer
3. Read the data from Rx FIFO buffer
Therefore, an application will be limited to writing and reading data from a respective buffer using
uart_write_bytes() and uart_read_bytes() respectively, and the FSM will do the rest.
Transmitting After preparing the data for transmission, call the function uart_write_bytes() and pass the
data buffer s address and data length to it. The function will copy the data to the Tx ring buffer (either immediately
or after enough space is available), and then exit. When there is free space in the Tx FIFO buffer, an interrupt service
routine (ISR) moves the data from the Tx ring buffer to the Tx FIFO buffer in the background. The code below
demonstrates the use of this function.
// Write data to UART.

char* test_str = "This is a test string.\n";
uart_write_bytes(uart_num, (const char*)test_str, strlen(test_str));

The function uart_write_bytes_with_break() is similar to uart_write_bytes() but adds a serial

break signal at the end of the transmission. A serial break signal means holding the Tx line low for a period longer
than one data frame.
// Write data to UART, end with a break signal.

uart_write_bytes_with_break(uart_num, "test break\n",strlen("test break\n"), 100);
Another function for writing data to the Tx FIFO buffer is uart_tx_chars(). Unlike
uart_write_bytes(), this function will not block until space is available. Instead, it will write all data
which can immediately fit into the hardware Tx FIFO, and then return the number of bytes that were written.
There is a companion function uart_wait_tx_done() that monitors the status of the Tx FIFO buffer and
returns once it is empty.
// Wait for packet to be sent

ESP_ERROR_CHECK(uart_wait_tx_done(uart_num, 100)); // wait timeout is 100 RTOS␣
,→ticks (TickType_t)
Receiving Once the data is received by the UART and saved in the Rx FIFO buffer, it needs to be retrieved using
the function uart_read_bytes(). Before reading data, you can check the number of bytes available in the
Rx FIFO buffer by calling uart_get_buffered_data_len(). An example of using these functions is given
below.
// Read data from UART.

uint8_t data[128];
int length = 0;
ESP_ERROR_CHECK(uart_get_buffered_data_len(uart_num, (size_t*)&length));
length = uart_read_bytes(uart_num, data, length, 100);
If the data in the Rx FIFO buffer is no longer needed, you can clear the buffer by calling uart_flush().
Software Flow Control If the hardware flow control is disabled, you can manually set the RTS and DTR signal
levels by using the functions uart_set_rts() and uart_set_dtr() respectively.
Communication Mode Selection The UART controller supports a number of communication modes. A mode
can be selected using the function uart_set_mode(). Once a specific mode is selected, the UART driver will
handle the behavior of a connected UART device accordingly. As an example, it can control the RS485 driver chip
using the RTS line to allow half-duplex RS485 communication.
// Setup UART in rs485 half duplex mode

ESP_ERROR_CHECK(uart_set_mode(uart_num, UART_MODE_RS485_HALF_DUPLEX));
Using Interrupts There are many interrupts that can be generated following specific UART states or detected
errors. The full list of available interrupts is provided in ESP32 Technical Reference Manual > UART Controller
(UART) > UART Interrupts and UHCI Interrupts [PDF]. You can enable or disable specific interrupts by calling
uart_enable_intr_mask() or uart_disable_intr_mask() respectively. The mask of all interrupts
is available as UART_INTR_MASK.
By default, the uart_driver_install() function installs the driver s internal interrupt handler to man-
age the Tx and Rx ring buffers and provides high-level API functions like events (see below). It is also possi-
ble to register a lower level interrupt handler instead using uart_isr_register(), and to free it again using
uart_isr_free(). Some UART driver functions which use the Tx and Rx ring buffers, events, etc. will not
automatically work in this case - it is necessary to handle the interrupts directly in the ISR. Inside the custom handler
implementation, clear the interrupt status bits using uart_clear_intr_status().

The API provides a convenient way to handle specific interrupts discussed in this document by wrapping them into
dedicated functions:
• Event detection: There are several events defined in uart_event_type_t that may be reported to a
user application using the FreeRTOS queue functionality. You can enable this functionality when calling
uart_driver_install() described in Driver Installation. An example of using Event detection can be
found in peripherals/uart/uart_events.
• FIFO space threshold or transmission timeout reached: The Tx and Rx FIFO buffers can trigger an inter-
rupt when they are filled with a specific number of characters, or on a timeout of sending or receiving data. To
use these interrupts, do the following:
– Configure respective threshold values of the buffer length and timeout by entering them in the structure
uart_intr_config_t and calling uart_intr_config()
– Enable the interrupts using the functions uart_enable_tx_intr() and
uart_enable_rx_intr()
– Disable these interrupts using the corresponding functions uart_disable_tx_intr() or
uart_disable_rx_intr()
• Pattern detection: An interrupt triggered on detecting a pattern of the same character being received/sent re-
peatedly for a number of times. This functionality is demonstrated in the example peripherals/uart/uart_events.
It can be used, e.g., to detect a command string followed by a specific number of identical characters (the pat-
tern ) added at the end of the command string. The following functions are available:
– Configure and enable this interrupt using uart_enable_pattern_det_intr()
– Disable the interrupt using uart_disable_pattern_det_intr()
Macros The API also defines several macros. For example, UART_FIFO_LEN defines the length of hardware
FIFO buffers; UART_BITRATE_MAX gives the maximum baud rate supported by the UART controllers, etc.
Deleting a Driver If the communication established with uart_driver_install() is no longer required,

the driver can be removed to free allocated resources by calling uart_driver_delete().
Overview of RS485 specific communication options
Note: The following section will use [UART_REGISTER_NAME].[UART_FIELD_BIT] to refer to UART

register fields/bits. For more information on a specific option bit, see ESP32 Technical Reference Manual > UART
Controller (UART) > Register Summary [PDF]. Use the register name to navigate to the register description and then
find the field/bit.
• UART_RS485_CONF_REG.UART_RS485_EN: setting this bit enables RS485 communication mode sup-

port.
• UART_RS485_CONF_REG.UART_RS485TX_RX_EN: if this bit is set, the transmitter s output signal
loops back to the receiver s input signal.
• UART_RS485_CONF_REG.UART_RS485RXBY_TX_EN: if this bit is set, the transmitter will still be send-
ing data if the receiver is busy (remove collisions automatically by hardware).
The ESP32 s RS485 UART hardware can detect signal collisions during transmission of a datagram and generate
the interrupt UART_RS485_CLASH_INT if this interrupt is enabled. The term collision means that a transmitted
datagram is not equal to the one received on the other end. Data collisions are usually associated with the presence
of other active devices on the bus or might occur due to bus errors.
The collision detection feature allows handling collisions when their interrupts are activated and triggered. The in-
terrupts UART_RS485_FRM_ERR_INT and UART_RS485_PARITY_ERR_INT can be used with the collision
detection feature to control frame errors and parity bit errors accordingly in RS485 mode. This functionality is
supported in the UART driver and can be used by selecting the UART_MODE_RS485_APP_CTRL mode (see the
function uart_set_mode()).
The collision detection feature can work with circuit A and circuit C (see Section Interface Connection Options). In
the case of using circuit A or B, the RTS pin connected to the DE pin of the bus driver should be controlled by the

user application. Use the function uart_get_collision_flag() to check if the collision detection flag has
been raised.
The ESP32 UART controllers themselves do not support half-duplex communication as they cannot provide automatic
control of the RTS pin connected to the ~RE/DE input of RS485 bus driver. However, half-duplex communication
can be achieved via software control of the RTS pin by the UART driver. This can be enabled by selecting the
UART_MODE_RS485_HALF_DUPLEX mode when calling uart_set_mode().
Once the host starts writing data to the Tx FIFO buffer, the UART driver automatically asserts the RTS pin (logic 1);
once the last bit of the data has been transmitted, the driver de-asserts the RTS pin (logic 0). To use this mode, the
software would have to disable the hardware flow control function. This mode works with all the used circuits shown
below.
Interface Connection Options This section provides example schematics to demonstrate the basic aspects of
ESP32 s RS485 interface connection.
Note:
• The schematics below do not necessarily contain all required elements.
• The analog devices ADM483 & ADM2483 are examples of common RS485 transceivers and can be replaced
with other similar transceivers.
Circuit A: Collision Detection Circuit

VCC ---------------+
|
+-------x-------+
RXD <------| R |
| B|----------<> B
TXD ------>| D ADM483 |
ESP | | RS485 bus side
RTS ------>| DE |
| A|----------<> A
+----| /RE |
| +-------x-------+
| |
GND GND
This circuit is preferable because it allows for collision detection and is quite simple at the same time. The receiver
in the line driver is constantly enabled, which allows the UART to monitor the RS485 bus. Echo suppression is per-
formed by the UART peripheral when the bit UART_RS485_CONF_REG.UART_RS485TX_RX_EN is enabled.
Circuit B: Manual Switching Transmitter/Receiver Without Collision Detection

VCC ---------------+
|
+-------x-------+
RXD <------| R |
| B|-----------<> B
TXD ------>| D ADM483 |
ESP | | RS485 bus side
RTS --+--->| DE |
| | A|-----------<> A
+----| /RE |
+-------x-------+
|
GND

This circuit does not allow for collision detection. It suppresses the null bytes that the hardware receives when
the bit UART_RS485_CONF_REG.UART_RS485TX_RX_EN is set. The bit UART_RS485_CONF_REG.
UART_RS485RXBY_TX_EN is not applicable in this case.
Circuit C: Auto Switching Transmitter/Receiver

VCC1 <-------------------+-----------+ +-------------------+----> VCC2
10K ____ | | | |
+---|____|--+ +---x-----------x---+ 10K ____ |
| | | +---|____|--+
RX <----------+-------------------| RXD | |
10K ____ | A|---+---------------<> A (+)
+-------|____|------| PV ADM2483 | | ____ 120
| ____ | | +---|____|---+ RS485␣
,→bus side
VCC1 <--+--|____|--+------->| DE | |
10K | | B|---+------------+--<> B (-)
---+ +-->| /RE | | ____
10K | | | | +---|____|---+
____ | /-C +---| TXD | 10K |
TX >---|____|--+_B_|/ NPN | | | |
|\ | +---x-----------x---+ |
| \-E | | | |
| | | | |
GND1 GND1 GND1 GND2 GND2
This galvanically isolated circuit does not require RTS pin control by a software application or driver because
it controls the transceiver direction automatically. However, it requires suppressing null bytes during transmis-
sion by setting UART_RS485_CONF_REG.UART_RS485RXBY_TX_EN to 1 and UART_RS485_CONF_REG.
UART_RS485TX_RX_EN to 0. This setup can work in any RS485 UART mode or even in UART_MODE_UART.
The table below describes the code examples available in the directory peripherals/uart/.
Code Example Description

peripherals/uart/uart_echo Configuring UART settings, installing the UART driver, and read-
ing/writing over the UART1 interface.
peripherals/uart/uart_events Reporting various communication events, using pattern detection inter-
rupts.
peripherals/uart/uart_async_rxtxtasks Transmitting and receiving data in two separate FreeRTOS tasks over the
same UART.
peripherals/uart/uart_select Using synchronous I/O multiplexing for UART file descriptors.
peripherals/uart/uart_echo_rs485 Setting up UART driver to communicate over RS485 interface in half-
duplex mode. This example is similar to peripherals/uart/uart_echo but
allows communication through an RS485 interface chip connected to
ESP32 pins.
peripherals/uart/nmea0183_parser Obtaining GPS information by parsing NMEA0183 statements received
from GPS via the UART peripheral.
API Reference
Header File
• components/driver/include/driver/uart.h

Functions
esp_err_t uart_driver_install(uart_port_t uart_num, int rx_buffer_size, int tx_buffer_size, int
queue_size, QueueHandle_t *uart_queue, int intr_alloc_flags)
Install UART driver and set the UART to the default configuration.
UART ISR handler will be attached to the same CPU core that this function is running on.
Note Rx_buffer_size should be greater than UART_FIFO_LEN. Tx_buffer_size should be either zero or
greater than UART_FIFO_LEN.
Return
• ESP_OK Success
• ESP_FAIL Parameter error
Parameters
• uart_num: UART port number, the max port number is (UART_NUM_MAX -1).
• rx_buffer_size: UART RX ring buffer size.
• tx_buffer_size: UART TX ring buffer size. If set to zero, driver will not use TX buffer, TX
function will block task until all data have been sent out.
• queue_size: UART event queue size/depth.
• uart_queue: UART event queue handle (out param). On success, a new queue handle is written
here to provide access to UART events. If set to NULL, driver will not use an event queue.
• intr_alloc_flags: Flags used to allocate the interrupt. One or multiple
(ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info. Do not set
ESP_INTR_FLAG_IRAM here (the driver s ISR handler is not located in IRAM)
esp_err_t uart_driver_delete(uart_port_t uart_num)
Uninstall UART driver.
Return
• ESP_OK Success
Parameters
bool uart_is_driver_installed(uart_port_t uart_num)
Checks whether the driver is installed or not.
Return
• true driver is installed
• false driver is not installed
Parameters
esp_err_t uart_set_word_length(uart_port_t uart_num, uart_word_length_t data_bit)
Set UART data bits.
Return
• ESP_OK Success
Parameters
• data_bit: UART data bits
esp_err_t uart_get_word_length(uart_port_t uart_num, uart_word_length_t *data_bit)
Get the UART data bit configuration.
Return
• ESP_OK Success, result will be put in (*data_bit)
Parameters
• data_bit: Pointer to accept value of UART data bits.
esp_err_t uart_set_stop_bits(uart_port_t uart_num, uart_stop_bits_t stop_bits)
Set UART stop bits.

Return
• ESP_OK Success
• ESP_FAIL Fail
Parameters
• stop_bits: UART stop bits
esp_err_t uart_get_stop_bits(uart_port_t uart_num, uart_stop_bits_t *stop_bits)
Get the UART stop bit configuration.
Return
• ESP_OK Success, result will be put in (*stop_bit)
Parameters
• stop_bits: Pointer to accept value of UART stop bits.
esp_err_t uart_set_parity(uart_port_t uart_num, uart_parity_t parity_mode)
Set UART parity mode.
Return
• ESP_OK Success
Parameters
• parity_mode: the enum of uart parity configuration
esp_err_t uart_get_parity(uart_port_t uart_num, uart_parity_t *parity_mode)
Get the UART parity mode configuration.
Return
• ESP_OK Success, result will be put in (*parity_mode)
Parameters
• parity_mode: Pointer to accept value of UART parity mode.
esp_err_t uart_set_baudrate(uart_port_t uart_num, uint32_t baudrate)
Set UART baud rate.
Return
• ESP_OK Success
Parameters
• baudrate: UART baud rate.
esp_err_t uart_get_baudrate(uart_port_t uart_num, uint32_t *baudrate)
Get the UART baud rate configuration.
Return
• ESP_OK Success, result will be put in (*baudrate)
Parameters
• baudrate: Pointer to accept value of UART baud rate
esp_err_t uart_set_line_inverse(uart_port_t uart_num, uint32_t inverse_mask)
Set UART line inverse mode.
Return
• ESP_OK Success
Parameters

• inverse_mask: Choose the wires that need to be inverted. Using the ORred mask of
uart_signal_inv_t
esp_err_t uart_set_hw_flow_ctrl(uart_port_t uart_num, uart_hw_flowcontrol_t flow_ctrl, uint8_t
rx_thresh)
Set hardware flow control.
Return
• ESP_OK Success
Parameters
• flow_ctrl: Hardware flow control mode
• rx_thresh: Threshold of Hardware RX flow control (0 ~ UART_FIFO_LEN). Only when
UART_HW_FLOWCTRL_RTS is set, will the rx_thresh value be set.
esp_err_t uart_set_sw_flow_ctrl(uart_port_t uart_num, bool enable, uint8_t rx_thresh_xon, uint8_t
rx_thresh_xoff)
Set software flow control.
Return
• ESP_OK Success
Parameters
• uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
• enable: switch on or off
• rx_thresh_xon: low water mark
• rx_thresh_xoff: high water mark
esp_err_t uart_get_hw_flow_ctrl(uart_port_t uart_num, uart_hw_flowcontrol_t *flow_ctrl)
Get the UART hardware flow control configuration.
Return
• ESP_OK Success, result will be put in (*flow_ctrl)
Parameters
• flow_ctrl: Option for different flow control mode.
esp_err_t uart_clear_intr_status(uart_port_t uart_num, uint32_t clr_mask)
Clear UART interrupt status.
Return
• ESP_OK Success
Parameters
• clr_mask: Bit mask of the interrupt status to be cleared.
esp_err_t uart_enable_intr_mask(uart_port_t uart_num, uint32_t enable_mask)
Set UART interrupt enable.
Return
• ESP_OK Success
Parameters
• enable_mask: Bit mask of the enable bits.
esp_err_t uart_disable_intr_mask(uart_port_t uart_num, uint32_t disable_mask)
Clear UART interrupt enable bits.
Return

• ESP_OK Success
Parameters
• disable_mask: Bit mask of the disable bits.
esp_err_t uart_enable_rx_intr(uart_port_t uart_num)
Enable UART RX interrupt (RX_FULL & RX_TIMEOUT INTERRUPT)
Return
• ESP_OK Success
Parameters
esp_err_t uart_disable_rx_intr(uart_port_t uart_num)
Disable UART RX interrupt (RX_FULL & RX_TIMEOUT INTERRUPT)
Return
• ESP_OK Success
Parameters
esp_err_t uart_disable_tx_intr(uart_port_t uart_num)
Disable UART TX interrupt (TX_FULL & TX_TIMEOUT INTERRUPT)
Return
• ESP_OK Success
Parameters
• uart_num: UART port number
esp_err_t uart_enable_tx_intr(uart_port_t uart_num, int enable, int thresh)
Enable UART TX interrupt (TX_FULL & TX_TIMEOUT INTERRUPT)
Return
• ESP_OK Success
Parameters
• enable: 1: enable; 0: disable
• thresh: Threshold of TX interrupt, 0 ~ UART_FIFO_LEN
esp_err_t uart_isr_register(uart_port_t uart_num, void (*fn))void *
, void *arg, int intr_alloc_flags, uart_isr_handle_t *handleRegister UART interrupt handler (ISR).
Note UART ISR handler will be attached to the same CPU core that this function is running on.
Return
• ESP_OK Success
Parameters
• arg: parameter for handler function
esp_err_t uart_isr_free(uart_port_t uart_num)
Free UART interrupt handler registered by uart_isr_register. Must be called on the same core as
uart_isr_register was called.
Return

• ESP_OK Success
Parameters
esp_err_t uart_set_pin(uart_port_t uart_num, int tx_io_num, int rx_io_num, int rts_io_num, int
cts_io_num)
Assign signals of a UART peripheral to GPIO pins.
Note If the GPIO number configured for a UART signal matches one of the IOMUX signals for that GPIO,
the signal will be connected directly via the IOMUX. Otherwise the GPIO and signal will be connected
via the GPIO Matrix. For example, if on an ESP32 the call uart_set_pin(0, 1, 3, -1, -1)
is performed, as GPIO1 is UART0 s default TX pin and GPIO3 is UART0 s default RX pin, both
will be connected to respectively U0TXD and U0RXD through the IOMUX, totally bypassing the GPIO
matrix. The check is performed on a per-pin basis. Thus, it is possible to have RX pin binded to a GPIO
through the GPIO matrix, whereas TX is binded to its GPIO through the IOMUX.
Note Internal signal can be output to multiple GPIO pads. Only one GPIO pad can connect with input signal.
Return
• ESP_OK Success
Parameters
• tx_io_num: UART TX pin GPIO number.
• rx_io_num: UART RX pin GPIO number.
• rts_io_num: UART RTS pin GPIO number.
• cts_io_num: UART CTS pin GPIO number.
esp_err_t uart_set_rts(uart_port_t uart_num, int level)
Manually set the UART RTS pin level.
Note UART must be configured with hardware flow control disabled.
Return
• ESP_OK Success
Parameters
• level: 1: RTS output low (active); 0: RTS output high (block)
esp_err_t uart_set_dtr(uart_port_t uart_num, int level)
Manually set the UART DTR pin level.
Return
• ESP_OK Success
Parameters
• level: 1: DTR output low; 0: DTR output high
esp_err_t uart_set_tx_idle_num(uart_port_t uart_num, uint16_t idle_num)
Set UART idle interval after tx FIFO is empty.
Return
• ESP_OK Success
Parameters
• idle_num: idle interval after tx FIFO is empty(unit: the time it takes to send one bit under current
baudrate)
esp_err_t uart_param_config(uart_port_t uart_num, const uart_config_t *uart_config)
Set UART configuration parameters.
Return

• ESP_OK Success
Parameters
• uart_config: UART parameter settings
esp_err_t uart_intr_config(uart_port_t uart_num, const uart_intr_config_t *intr_conf)
Configure UART interrupts.
Return
• ESP_OK Success
Parameters
• intr_conf: UART interrupt settings
esp_err_t uart_wait_tx_done(uart_port_t uart_num, TickType_t ticks_to_wait)
Wait until UART TX FIFO is empty.
Return
• ESP_OK Success
• ESP_ERR_TIMEOUT Timeout
Parameters
• ticks_to_wait: Timeout, count in RTOS ticks
int uart_tx_chars(uart_port_t uart_num, const char *buffer, uint32_t len)
Send data to the UART port from a given buffer and length.
This function will not wait for enough space in TX FIFO. It will just fill the available TX FIFO and return
when the FIFO is full.
Note This function should only be used when UART TX buffer is not enabled.
Return
• OTHERS (>=0) The number of bytes pushed to the TX FIFO
Parameters
• buffer: data buffer address
• len: data length to send
int uart_write_bytes(uart_port_t uart_num, const void *src, size_t size)
Send data to the UART port from a given buffer and length,.
If the UART driver s parameter tx_buffer_size is set to zero: This function will not return until all the
data have been sent out, or at least pushed into TX FIFO.
Otherwise, if the tx_buffer_size > 0, this function will return after copying all the data to tx ring buffer,
UART ISR will then move data from the ring buffer to TX FIFO gradually.
Return
Parameters
• src: data buffer address
• size: data length to send
int uart_write_bytes_with_break(uart_port_t uart_num, const void *src, size_t size, int
brk_len)
Send data to the UART port from a given buffer and length,.
If the UART driver s parameter tx_buffer_size is set to zero: This function will not return until all the
data and the break signal have been sent out. After all data is sent out, send a break signal.

Otherwise, if the tx_buffer_size > 0, this function will return after copying all the data to tx ring buffer,
UART ISR will then move data from the ring buffer to TX FIFO gradually. After all data sent out, send a
break signal.
Return
Parameters
• src: data buffer address
• size: data length to send
• brk_len: break signal duration(unit: the time it takes to send one bit at current baudrate)
int uart_read_bytes(uart_port_t uart_num, void *buf, uint32_t length, TickType_t ticks_to_wait)
UART read bytes from UART buffer.
Return
• (-1) Error
• OTHERS (>=0) The number of bytes read from UART FIFO
Parameters
• buf: pointer to the buffer.
• length: data length
• ticks_to_wait: sTimeout, count in RTOS ticks
esp_err_t uart_flush(uart_port_t uart_num)
Alias of uart_flush_input. UART ring buffer flush. This will discard all data in the UART RX buffer.
Note Instead of waiting the data sent out, this function will clear UART rx buffer. In order to send all the data
in tx FIFO, we can use uart_wait_tx_done function.
Return
• ESP_OK Success
Parameters
esp_err_t uart_flush_input(uart_port_t uart_num)
Clear input buffer, discard all the data is in the ring-buffer.
Note In order to send all the data in tx FIFO, we can use uart_wait_tx_done function.
Return
• ESP_OK Success
Parameters
esp_err_t uart_get_buffered_data_len(uart_port_t uart_num, size_t *size)
UART get RX ring buffer cached data length.
Return
• ESP_OK Success
Parameters
• size: Pointer of size_t to accept cached data length
esp_err_t uart_disable_pattern_det_intr(uart_port_t uart_num)
UART disable pattern detect function. Designed for applications like AT commands . When the hardware
detects a series of one same character, the interrupt will be triggered.
Return
• ESP_OK Success
Parameters

esp_err_t uart_enable_pattern_det_intr(uart_port_t uart_num, char pattern_chr, uint8_t
chr_num, int chr_tout, int post_idle, int pre_idle)
UART enable pattern detect function. Designed for applications like AT commands . When the hardware
detect a series of one same character, the interrupt will be triggered.
Note This function only works for esp32. And this function is deprecated, please use
uart_enable_pattern_det_baud_intr instead.
Return
• ESP_OK Success
Parameters
• uart_num: UART port number.
• pattern_chr: character of the pattern.
• chr_num: number of the character, 8bit value.
• chr_tout: timeout of the interval between each pattern characters, 24bit value, unit is APB
(80Mhz) clock cycle. When the duration is less than this value, it will not take this data as at_cmd
char.
• post_idle: idle time after the last pattern character, 24bit value, unit is APB (80Mhz) clock
cycle. When the duration is less than this value, it will not take the previous data as the last at_cmd
char
• pre_idle: idle time before the first pattern character, 24bit value, unit is APB (80Mhz) clock
cycle. When the duration is less than this value, it will not take this data as the first at_cmd char.
esp_err_t uart_enable_pattern_det_baud_intr(uart_port_t uart_num, char pattern_chr,
uint8_t chr_num, int chr_tout, int post_idle, int
pre_idle)
UART enable pattern detect function. Designed for applications like AT commands . When the hardware
detect a series of one same character, the interrupt will be triggered.
Return
• ESP_OK Success
Parameters
• uart_num: UART port number.
• pattern_chr: character of the pattern.
• chr_num: number of the character, 8bit value.
• chr_tout: timeout of the interval between each pattern characters, 16bit value, unit is the baud-
rate cycle you configured. When the duration is more than this value, it will not take this data as
at_cmd char.
• post_idle: idle time after the last pattern character, 16bit value, unit is the baud-rate cycle you
configured. When the duration is less than this value, it will not take the previous data as the last
at_cmd char
• pre_idle: idle time before the first pattern character, 16bit value, unit is the baud-rate cycle you
configured. When the duration is less than this value, it will not take this data as the first at_cmd
char.
int uart_pattern_pop_pos(uart_port_t uart_num)
Return the nearest detected pattern position in buffer. The positions of the detected pattern are saved in a
queue, this function will dequeue the first pattern position and move the pointer to next pattern position.
The following APIs will modify the pattern position info: uart_flush_input, uart_read_bytes,
uart_driver_delete, uart_pop_pattern_pos It is the application s responsibility to ensure atomic access
to the pattern queue and the rx data buffer when using pattern detect feature.
Note If the RX buffer is full and flow control is not enabled, the detected pattern may not be found in the rx
buffer due to overflow.
Return
• (-1) No pattern found for current index or parameter error
• others the pattern position in rx buffer.

Parameters
int uart_pattern_get_pos(uart_port_t uart_num)
Return the nearest detected pattern position in buffer. The positions of the detected pattern are saved in a
queue, This function do nothing to the queue.
The following APIs will modify the pattern position info: uart_flush_input, uart_read_bytes,
uart_driver_delete, uart_pop_pattern_pos It is the application s responsibility to ensure atomic access
to the pattern queue and the rx data buffer when using pattern detect feature.
Note If the RX buffer is full and flow control is not enabled, the detected pattern may not be found in the rx
buffer due to overflow.
Return
• (-1) No pattern found for current index or parameter error
• others the pattern position in rx buffer.
Parameters
esp_err_t uart_pattern_queue_reset(uart_port_t uart_num, int queue_length)
Allocate a new memory with the given length to save record the detected pattern position in rx buffer.
Return
• ESP_ERR_NO_MEM No enough memory
• ESP_ERR_INVALID_STATE Driver not installed
• ESP_OK Success
Parameters
• queue_length: Max queue length for the detected pattern. If the queue length is not large
enough, some pattern positions might be lost. Set this value to the maximum number of patterns
that could be saved in data buffer at the same time.
esp_err_t uart_set_mode(uart_port_t uart_num, uart_mode_t mode)
UART set communication mode.
Note This function must be executed after uart_driver_install(), when the driver object is initialized.
Return
• ESP_OK Success
Parameters
• uart_num: Uart number to configure, the max port number is (UART_NUM_MAX -1).
• mode: UART UART mode to set
esp_err_t uart_set_rx_full_threshold(uart_port_t uart_num, int threshold)
Set uart threshold value for RX fifo full.
Note If application is using higher baudrate and it is observed that bytes in hardware RX fifo are overwritten
then this threshold can be reduced
Return
• ESP_OK Success
• ESP_ERR_INVALID_STATE Driver is not installed
Parameters
• threshold: Threshold value above which RX fifo full interrupt is generated
esp_err_t uart_set_tx_empty_threshold(uart_port_t uart_num, int threshold)
Set uart threshold values for TX fifo empty.
Return
• ESP_OK Success


Parameters
• threshold: Threshold value below which TX fifo empty interrupt is generated
esp_err_t uart_set_rx_timeout(uart_port_t uart_num, const uint8_t tout_thresh)
UART set threshold timeout for TOUT feature.
Return
• ESP_OK Success
Parameters
• uart_num: Uart number to configure, the max port number is (UART_NUM_MAX -1).
• tout_thresh: This parameter defines timeout threshold in uart symbol periods. The maximum
value of threshold is 126. tout_thresh = 1, defines TOUT interrupt timeout equal to transmission time
of one symbol (~11 bit) on current baudrate. If the time is expired the UART_RXFIFO_TOUT_INT
interrupt is triggered. If tout_thresh == 0, the TOUT feature is disabled.
esp_err_t uart_get_collision_flag(uart_port_t uart_num, bool *collision_flag)
Returns collision detection flag for RS485 mode Function returns the collision detection flag into variable
pointed by collision_flag. *collision_flag = true, if collision detected else it is equal to false. This function
should be executed when actual transmission is completed (after uart_write_bytes()).
Return
• ESP_OK Success
Parameters
• uart_num: Uart number to configure the max port number is (UART_NUM_MAX -1).
• collision_flag: Pointer to variable of type bool to return collision flag.
esp_err_t uart_set_wakeup_threshold(uart_port_t uart_num, int wakeup_threshold)
Set the number of RX pin signal edges for light sleep wakeup.
UART can be used to wake up the system from light sleep. This feature works by counting the number of
positive edges on RX pin and comparing the count to the threshold. When the count exceeds the threshold,
system is woken up from light sleep. This function allows setting the threshold value.
Stop bit and parity bits (if enabled) also contribute to the number of edges. For example, letter a with
ASCII code 97 is encoded as 0100001101 on the wire (with 8n1 configuration), start and stop bits included.
This sequence has 3 positive edges (transitions from 0 to 1). Therefore, to wake up the system when a is
sent, set wakeup_threshold=3.
The character that triggers wakeup is not received by UART (i.e. it can not be obtained from UART FIFO).
Depending on the baud rate, a few characters after that will also not be received. Note that when the chip enters
and exits light sleep mode, APB frequency will be changing. To make sure that UART has correct baud rate
all the time, select REF_TICK as UART clock source, by setting use_ref_tick field in uart_config_t to true.
Note in ESP32, the wakeup signal can only be input via IO_MUX (i.e. GPIO3 should be configured as
function_1 to wake up UART0, GPIO9 should be configured as function_5 to wake up UART1), UART2
does not support light sleep wakeup feature.
Return
• ESP_ERR_INVALID_ARG if uart_num is incorrect or wakeup_threshold is outside of [3, 0x3ff]
range.
Parameters
• uart_num: UART number, the max port number is (UART_NUM_MAX -1).
• wakeup_threshold: number of RX edges for light sleep wakeup, value is 3 .. 0x3ff.
esp_err_t uart_get_wakeup_threshold(uart_port_t uart_num, int *out_wakeup_threshold)
Get the number of RX pin signal edges for light sleep wakeup.
See description of uart_set_wakeup_threshold for the explanation of UART wakeup feature.

Return
• ESP_ERR_INVALID_ARG if out_wakeup_threshold is NULL
Parameters
• uart_num: UART number, the max port number is (UART_NUM_MAX -1).
• [out] out_wakeup_threshold: output, set to the current value of wakeup threshold for the
given UART.
esp_err_t uart_wait_tx_idle_polling(uart_port_t uart_num)
Wait until UART tx memory empty and the last char send ok (polling mode).
• Return
– ESP_OK on success
– ESP_ERR_INVALID_ARG Parameter error
– ESP_FAIL Driver not installed
Parameters
• uart_num: UART number
esp_err_t uart_set_loop_back(uart_port_t uart_num, bool loop_back_en)
Configure TX signal loop back to RX module, just for the test usage.
• Return
– ESP_OK on success
– ESP_ERR_INVALID_ARG Parameter error
– ESP_FAIL Driver not installed
Parameters
• loop_back_en: Set ture to enable the loop back function, else set it false.
void uart_set_always_rx_timeout(uart_port_t uart_num, bool always_rx_timeout_en)
Configure behavior of UART RX timeout interrupt.
When always_rx_timeout is true, timeout interrupt is triggered even if FIFO is full. This function can cause
extra timeout interrupts triggered only to send the timeout event. Call this function only if you want to ensure
timeout interrupt will always happen after a byte stream.
Parameters
• always_rx_timeout_en: Set to false enable the default behavior of timeout interrupt, set it to
true to always trigger timeout interrupt.
Structures
struct uart_intr_config_t
UART interrupt configuration parameters for uart_intr_config function.
Public Members
uint32_t intr_enable_mask
UART interrupt enable mask, choose from UART_XXXX_INT_ENA_M under
UART_INT_ENA_REG(i), connect with bit-or operator
uint8_t rx_timeout_thresh
UART timeout interrupt threshold (unit: time of sending one byte)
uint8_t txfifo_empty_intr_thresh
UART TX empty interrupt threshold.
uint8_t rxfifo_full_thresh
UART RX full interrupt threshold.
struct uart_event_t
Event structure used in UART event queue.

Public Members
uart_event_type_t type
UART event type
size_t size
UART data size for UART_DATA event
bool timeout_flag
UART data read timeout flag for UART_DATA event (no new data received during configured RX
TOUT) If the event is caused by FIFO-full interrupt, then there will be no event with the timeout flag
before the next byte coming.
Macros
UART_NUM_0
UART port 0
UART_NUM_1
UART port 1
UART_NUM_2
UART port 2
UART_NUM_MAX
UART port max
UART_PIN_NO_CHANGE
UART_FIFO_LEN
Length of the UART HW FIFO.
UART_BITRATE_MAX
Maximum configurable bitrate.
Type Definitions
typedef intr_handle_t uart_isr_handle_t
Enumerations
enum uart_event_type_t
UART event types used in the ring buffer.
Values:
UART_DATA
UART data event
UART_BREAK
UART break event
UART_BUFFER_FULL
UART RX buffer full event
UART_FIFO_OVF
UART FIFO overflow event
UART_FRAME_ERR
UART RX frame error event
UART_PARITY_ERR
UART RX parity event
UART_DATA_BREAK
UART TX data and break event

UART_PATTERN_DET
UART pattern detected
UART_EVENT_MAX
UART event max index
Header File
• components/hal/include/hal/uart_types.h
Structures
struct uart_at_cmd_t
UART AT cmd char configuration parameters Note that this function may different on different chip. Please
refer to the TRM at confirguration.
Public Members
uint8_t cmd_char
UART AT cmd char
uint8_t char_num
AT cmd char repeat number
uint32_t gap_tout
gap time(in baud-rate) between AT cmd char
uint32_t pre_idle
the idle time(in baud-rate) between the non AT char and first AT char
uint32_t post_idle
the idle time(in baud-rate) between the last AT char and the none AT char
struct uart_sw_flowctrl_t
UART software flow control configuration parameters.
Public Members
uint8_t xon_char
Xon flow control char
uint8_t xoff_char
Xoff flow control char
uint8_t xon_thrd
If the software flow control is enabled and the data amount in rxfifo is less than xon_thrd, an xon_char
will be sent
uint8_t xoff_thrd
If the software flow control is enabled and the data amount in rxfifo is more than xoff_thrd, an xoff_char
will be sent
struct uart_config_t
UART configuration parameters for uart_param_config function.
Public Members
int baud_rate
UART baud rate
uart_word_length_t data_bits
UART byte size

uart_parity_t parity
UART parity mode
uart_stop_bits_t stop_bits
UART stop bits
uart_hw_flowcontrol_t flow_ctrl
UART HW flow control mode (cts/rts)
uint8_t rx_flow_ctrl_thresh
UART HW RTS threshold
uart_sclk_t source_clk
UART source clock selection
bool use_ref_tick
Deprecated method to select ref tick clock source, set source_clk field instead
Type Definitions
typedef int uart_port_t
UART port number, can be UART_NUM_0 ~ (UART_NUM_MAX -1).
Enumerations
enum uart_mode_t
UART mode selection.
Values:
UART_MODE_UART = 0x00
mode: regular UART mode
UART_MODE_RS485_HALF_DUPLEX = 0x01
mode: half duplex RS485 UART mode control by RTS pin
UART_MODE_IRDA = 0x02
mode: IRDA UART mode
UART_MODE_RS485_COLLISION_DETECT = 0x03
mode: RS485 collision detection UART mode (used for test purposes)
UART_MODE_RS485_APP_CTRL = 0x04
mode: application control RS485 UART mode (used for test purposes)
enum uart_word_length_t
UART word length constants.
Values:
UART_DATA_5_BITS = 0x0
word length: 5bits
word length: 6bits
word length: 7bits
word length: 8bits
UART_DATA_BITS_MAX = 0x4
enum uart_stop_bits_t
UART stop bits number.
Values:

UART_STOP_BITS_1 = 0x1
stop bit: 1bit
UART_STOP_BITS_1_5 = 0x2
stop bit: 1.5bits
UART_STOP_BITS_2 = 0x3
stop bit: 2bits
UART_STOP_BITS_MAX = 0x4
enum uart_parity_t
UART parity constants.
Values:
UART_PARITY_DISABLE = 0x0
Disable UART parity
UART_PARITY_EVEN = 0x2
Enable UART even parity
UART_PARITY_ODD = 0x3
Enable UART odd parity
enum uart_hw_flowcontrol_t
UART hardware flow control modes.
Values:
UART_HW_FLOWCTRL_DISABLE = 0x0
disable hardware flow control
UART_HW_FLOWCTRL_RTS = 0x1
enable RX hardware flow control (rts)
UART_HW_FLOWCTRL_CTS = 0x2
enable TX hardware flow control (cts)
UART_HW_FLOWCTRL_CTS_RTS = 0x3
enable hardware flow control
UART_HW_FLOWCTRL_MAX = 0x4
enum uart_signal_inv_t
UART signal bit map.
Values:
UART_SIGNAL_INV_DISABLE = 0
Disable UART signal inverse
UART_SIGNAL_IRDA_TX_INV = (0x1 << 0)
inverse the UART irda_tx signal
UART_SIGNAL_IRDA_RX_INV = (0x1 << 1)
inverse the UART irda_rx signal
UART_SIGNAL_RXD_INV = (0x1 << 2)
inverse the UART rxd signal
UART_SIGNAL_CTS_INV = (0x1 << 3)
inverse the UART cts signal
UART_SIGNAL_DSR_INV = (0x1 << 4)
inverse the UART dsr signal
UART_SIGNAL_TXD_INV = (0x1 << 5)
inverse the UART txd signal

UART_SIGNAL_RTS_INV = (0x1 << 6)

inverse the UART rts signal
UART_SIGNAL_DTR_INV = (0x1 << 7)
inverse the UART dtr signal
enum uart_sclk_t
UART source clock.
Values:
UART_SCLK_APB = 0x0
UART source clock from APB
UART_SCLK_REF_TICK = 0x3
UART source clock from REF_TICK
GPIO Lookup Macros The UART peripherals have dedicated IO_MUX pins to which they are connected directly.
However, signals can also be routed to other pins using the less direct GPIO matrix. To use direct routes, you need
to know which pin is a dedicated IO_MUX pin for a UART channel. GPIO Lookup Macros simplify the process of
finding and assigning IO_MUX pins. You choose a macro based on either the IO_MUX pin number, or a required
UART channel name, and the macro will return the matching counterpart for you. See some examples below.
Note: These macros are useful if you need very high UART baud rates (over 40 MHz), which means you will have
to use IO_MUX pins only. In other cases, these macros can be ignored, and you can use the GPIO Matrix as it allows
you to configure any GPIO pin for any UART function.
1. UART_NUM_2_TXD_DIRECT_GPIO_NUM returns the IO_MUX pin number of UART channel 2 TXD pin
(pin 17)
2. UART_GPIO19_DIRECT_CHANNEL returns the UART number of GPIO 19 when connected to the UART
peripheral via IO_MUX (this is UART_NUM_0)
3. UART_CTS_GPIO19_DIRECT_CHANNEL returns the UART number of GPIO 19 when used as the UART
CTS pin via IO_MUX (this is UART_NUM_0). Similar to the above macro but specifies the pin function which
is also part of the IO_MUX assignment.
Header File
• components/soc/esp32/include/soc/uart_channel.h
Macros
UART_GPIO1_DIRECT_CHANNEL
UART_NUM_0_TXD_DIRECT_GPIO_NUM
UART_NUM_0_RXD_DIRECT_GPIO_NUM
UART_NUM_0_CTS_DIRECT_GPIO_NUM
UART_NUM_0_RTS_DIRECT_GPIO_NUM
UART_TXD_GPIO1_DIRECT_CHANNEL
UART_RXD_GPIO3_DIRECT_CHANNEL
UART_CTS_GPIO19_DIRECT_CHANNEL
UART_RTS_GPIO22_DIRECT_CHANNEL

Code examples for this API section are provided in the peripherals directory of ESP-IDF examples.
2.4 Application Protocols
2.4.1 ASIO port
Overview
Asio is a cross-platform C++ library, see https://think-async.com. It provides a consistent asynchronous model using
a modern C++ approach.
ASIO documentation Please refer to the original asio documentation at https://think-async.com/Asio/

Documentation. Asio also comes with a number of examples which could be find under Documentation/Examples
on that web site.

Supported features ESP platform port currently supports only network asynchronous socket operations; does not
support serial port. SSL/TLS support is disabled by default and could be enabled in component configuration menu
by choosing TLS library from
• mbedTLS with OpenSSL translation layer (default option)
• wolfSSL
SSL support is very basic at this stage and it does include following features:
• Verification callbacks
• DH property files
• Certificates/private keys file APIs
Internal asio settings for ESP include
• EXCEPTIONS are enabled in ASIO if enabled in menuconfig
• TYPEID is enabled in ASIO if enabled in menuconfig
Application Example
ESP examples are based on standard asio protocols/asio:

• protocols/asio/udp_echo_server
• protocols/asio/tcp_echo_server
• protocols/asio/asio_chat
• protocols/asio/ssl_client_server
Please refer to the specific example README.md for details
2.4.2 ESP-MQTT
Overview
ESP-MQTT is an implementation of MQTT protocol client (MQTT is a lightweight publish/subscribe messaging

protocol).
Features
• Supports MQTT over TCP, SSL with mbedtls, MQTT over Websocket, MQTT over Websocket Secure.
• Easy to setup with URI
• Multiple instances (Multiple clients in one application)
• Support subscribing, publishing, authentication, last will messages, keep alive pings and all 3 QoS levels (it
should be a fully functional client).
Application Example
• protocols/mqtt/tcp: MQTT over tcp, default port 1883

• protocols/mqtt/ssl: MQTT over tcp, default port 8883
• protocols/mqtt/ssl_psk: MQTT over tcp using pre-shared keys for authentication, default port 8883
• protocols/mqtt/ws: MQTT over Websocket, default port 80
• protocols/mqtt/wss: MQTT over Websocket Secure, default port 443
Configuration
URI
• Curently support mqtt, mqtts, ws, wss schemes
• MQTT over TCP samples:

– mqtt://mqtt.eclipseprojects.io: MQTT over TCP, default port 1883:

– mqtt://mqtt.eclipseprojects.io:1884 MQTT over TCP, port 1884:
– mqtt://username:[email protected]:1884 MQTT over TCP,
port 1884, with username and password
• MQTT over SSL samples:
– mqtts://mqtt.eclipseprojects.io: MQTT over SSL, port 8883
– mqtts://mqtt.eclipseprojects.io:8884: MQTT over SSL, port 8884
• MQTT over Websocket samples:
– ws://mqtt.eclipseprojects.io:80/mqtt
• MQTT over Websocket Secure samples:
– wss://mqtt.eclipseprojects.io:443/mqtt
• Minimal configurations:
const esp_mqtt_client_config_t mqtt_cfg = {

.uri = "mqtt://mqtt.eclipseprojects.io",
// .user_context = (void *)your_context
};
esp_mqtt_client_handle_t client = esp_mqtt_client_init(&mqtt_cfg);
esp_mqtt_client_register_event(client, ESP_EVENT_ANY_ID, mqtt_event_handler,␣
,→client);
esp_mqtt_client_start(client);
• Note: By default mqtt client uses event loop library to post related mqtt events (connected, subscribed, pub-
lished, etc.)
SSL
• Get certificate from server, example: mqtt.eclipseprojects.io openssl s_client -
showcerts -connect mqtt.eclipseprojects.io:8883 </dev/null 2>/dev/
null|openssl x509 -outform PEM >mqtt_eclipse_org.pem
• Check the sample application: examples/mqtt_ssl
• Configuration:
const esp_mqtt_client_config_t mqtt_cfg = {

.uri = "mqtts://mqtt.eclipseprojects.io:8883",
.event_handle = mqtt_event_handler,
.cert_pem = (const char *)mqtt_eclipse_org_pem_start,
};
If the certificate is not null-terminated then cert_len should also be set. Other SSL related configuration param-
eters are:
• use_global_ca_store: use the global certificate store to verify server certificate, see esp-tls.h for
more information
• client_cert_pem: pointer to certificate data in PEM or DER format for SSL mutual authentication,
default is NULL, not required if mutual authentication is not needed.
• client_cert_len: length of the buffer pointed to by client_cert_pem. May be 0 for null-terminated pem.
• client_key_pem: pointer to private key data in PEM or DER format for SSL mutual authentication,
default is NULL, not required if mutual authentication is not needed.
• client_key_len: length of the buffer pointed to by client_key_pem. May be 0 for null-terminated pem.
• psk_hint_key: pointer to PSK struct defined in esp_tls.h to enable PSK authentication (as alternative to
certificate verification). If not NULL and server/client certificates are NULL, PSK is enabled
• alpn_protos: NULL-terminated list of protocols to be used for ALPN.
Last Will and Testament MQTT allows for a last will and testament (LWT) message to notify other clients when a
client ungracefully disconnects. This is configured by the following fields in the esp_mqtt_client_config_t-
struct.
• lwt_topic: pointer to the LWT message topic
• lwt_msg: pointer to the LWT message

• lwt_msg_len: length of the LWT message, required if lwt_msg is not null-terminated

• lwt_qos: quality of service for the LWT message
• lwt_retain: specifies the retain flag of the LWT message
Other Configuration Parameters

• disable_clean_session: determines the clean session flag for the connect message, defaults to a clean
session
• keepalive: determines how many seconds the client will wait for a ping response before disconnecting,
default is 120 seconds.
• disable_auto_reconnect: enable to stop the client from reconnecting to server after errors or discon-
nects
• user_context: custom context that will be passed to the event handler
• task_prio: MQTT task priority, defaults to 5
• task_stack: MQTT task stack size, defaults to 6144 bytes, setting this will override setting from menu-
config
• buffer_size: size of MQTT send/receive buffer, default is 1024 bytes
• username: pointer to the username used for connecting to the broker
• password: pointer to the password used for connecting to the broker
• client_id: pointer to the client id, defaults to ESP32_%CHIPID% where %CHIPID% are the last 3 bytes
of MAC address in hex format
• host: MQTT broker domain (ipv4 as string), setting the uri will override this
• port: MQTT broker port, specifying the port in the uri will override this
• transport: sets the transport protocol, setting the uri will override this
• refresh_connection_after_ms: refresh connection after this value (in milliseconds)
• event_handle: handle for MQTT events as a callback in legacy mode
• event_loop_handle: handle for MQTT event loop library
For more options on esp_mqtt_client_config_t, please refer to API reference below
Change settings in Project Configuration Menu The settings for MQTT can be found using idf.py menu-
config, under Component config -> ESP-MQTT Configuration
The following settings are available:
• CONFIG_MQTT_PROTOCOL_311: Enables 3.1.1 version of MQTT protocol
• CONFIG_MQTT_TRANSPORT_SSL, CONFIG_MQTT_TRANSPORT_WEBSOCKET: Enables specific MQTT
transport layer, such as SSL, WEBSOCKET, WEBSOCKET_SECURE
• CONFIG_MQTT_CUSTOM_OUTBOX: Disables default implementation of mqtt_outbox, so a specific imple-
mentaion can be supplied
Events
The following events may be posted by the MQTT client:

• MQTT_EVENT_BEFORE_CONNECT: The client is initialized and about to start connecting to the broker.
• MQTT_EVENT_CONNECTED: The client has successfully established a connection to the broker. The client
is now ready to send and receive data.
• MQTT_EVENT_DISCONNECTED: The client has aborted the connection due to being unable to read or write
data, e.g. because the server is unavailable.
• MQTT_EVENT_SUBSCRIBED: The broker has acknowledged the client s subscribe request. The event data
will contain the message ID of the subscribe message.
• MQTT_EVENT_UNSUBSCRIBED: The broker has acknowledged the client s unsubscribe request. The event
data will contain the message ID of the unsubscribe message.
• MQTT_EVENT_PUBLISHED: The broker has acknowledged the client s publish message. This will only
be posted for Quality of Service level 1 and 2, as level 0 does not use acknowledgements. The event data will
contain the message ID of the publish message.

• MQTT_EVENT_DATA: The client has received a publish message. The event data contains: message ID, name
of the topic it was published to, received data and its length. For data that exceeds the internal buffer multiple
MQTT_EVENT_DATA will be posted and current_data_offset and total_data_len from event data updated to
keep track of the fragmented message.
• MQTT_EVENT_ERROR: The client has encountered an error. esp_mqtt_error_type_t from error_handle in the
event data can be used to further determine the type of the error. The type of error will determine which parts
of the error_handle struct is filled.
API Reference
Header File
• components/mqtt/esp-mqtt/include/mqtt_client.h
Functions
esp_mqtt_client_handle_t esp_mqtt_client_init(const esp_mqtt_client_config_t *config)
Creates mqtt client handle based on the configuration.
Return mqtt_client_handle if successfully created, NULL on error
Parameters
• config: mqtt configuration structure
esp_err_t esp_mqtt_client_set_uri(esp_mqtt_client_handle_t client, const char *uri)
Sets mqtt connection URI. This API is usually used to overrides the URI configured in esp_mqtt_client_init.
Return ESP_FAIL if URI parse error, ESP_OK on success
Parameters
• client: mqtt client handle
• uri:
esp_err_t esp_mqtt_client_start(esp_mqtt_client_handle_t client)
Starts mqtt client with already created client handle.
Return ESP_OK on success ESP_ERR_INVALID_ARG on wrong initialization ESP_FAIL on other error
Parameters
esp_err_t esp_mqtt_client_reconnect(esp_mqtt_client_handle_t client)
This api is typically used to force reconnection upon a specific event.
Return ESP_OK on success ESP_ERR_INVALID_ARG on wrong initialization ESP_FAIL if client is in
invalid state
Parameters
esp_err_t esp_mqtt_client_disconnect(esp_mqtt_client_handle_t client)
This api is typically used to force disconnection from the broker.
Return ESP_OK on success ESP_ERR_INVALID_ARG on wrong initialization
Parameters
esp_err_t esp_mqtt_client_stop(esp_mqtt_client_handle_t client)
Stops mqtt client tasks.
• Notes:
• Cannot be called from the mqtt event handler
Return ESP_OK on success ESP_ERR_INVALID_ARG on wrong initialization ESP_FAIL if client is in
invalid state
Parameters

int esp_mqtt_client_subscribe(esp_mqtt_client_handle_t client, const char *topic, int qos)

Subscribe the client to defined topic with defined qos.
Notes:
• Client must be connected to send subscribe message
• This API is could be executed from a user task or from a mqtt event callback i.e. internal mqtt task (API
is protected by internal mutex, so it might block if a longer data receive operation is in progress.
Return message_id of the subscribe message on success -1 on failure
Parameters
• topic:
• qos:
int esp_mqtt_client_unsubscribe(esp_mqtt_client_handle_t client, const char *topic)
Unsubscribe the client from defined topic.
Notes:
• Client must be connected to send unsubscribe message
• It is thread safe, please refer to esp_mqtt_client_subscribe for details
Return message_id of the subscribe message on success -1 on failure
Parameters
• topic:
int esp_mqtt_client_publish(esp_mqtt_client_handle_t client, const char *topic, const char
*data, int len, int qos, int retain)
Client to send a publish message to the broker.
Notes:
• This API might block for several seconds, either due to network timeout (10s) or if publishing payloads
longer than internal buffer (due to message fragmentation)
• Client doesn t have to be connected for this API to work, enqueueing the messages with qos>1 (returning
-1 for all the qos=0 messages if disconnected). If MQTT_SKIP_PUBLISH_IF_DISCONNECTED is
enabled, this API will not attempt to publish when the client is not connected and will always return -1.
• It is thread safe, please refer to esp_mqtt_client_subscribe for details
Return message_id of the publish message (for QoS 0 message_id will always be zero) on success. -1 on
failure.
Parameters
• topic: topic string
• data: payload string (set to NULL, sending empty payload message)
• len: data length, if set to 0, length is calculated from payload string
• qos: qos of publish message
• retain: retain flag
int esp_mqtt_client_enqueue(esp_mqtt_client_handle_t client, const char *topic, const char
*data, int len, int qos, int retain, bool store)
Enqueue a message to the outbox, to be sent later. Typically used for messages with qos>0, but could be also
used for qos=0 messages if store=true.
This API generates and stores the publish message into the internal outbox and the actual sending to the net-
work is performed in the mqtt-task context (in contrast to the esp_mqtt_client_publish() which sends the pub-
lish message immediately in the user task s context). Thus, it could be used as a non blocking version of
esp_mqtt_client_publish().
Return message_id if queued successfully, -1 otherwise
Parameters
• topic: topic string

• data: payload string (set to NULL, sending empty payload message)

• len: data length, if set to 0, length is calculated from payload string
• qos: qos of publish message
• retain: retain flag
• store: if true, all messages are enqueued; otherwise only qos1 and qos 2 are enqueued
esp_err_t esp_mqtt_client_destroy(esp_mqtt_client_handle_t client)
Destroys the client handle.
Notes:
• Cannot be called from the mqtt event handler
Return ESP_OK ESP_ERR_INVALID_ARG on wrong initialization
Parameters
esp_err_t esp_mqtt_set_config(esp_mqtt_client_handle_t client, const esp_mqtt_client_config_t
*config)
Set configuration structure, typically used when updating the config (i.e. on before_connect event.
Return ESP_ERR_NO_MEM if failed to allocate ESP_ERR_INVALID_ARG if conflicts on transport con-
figuration. ESP_OK on success
Parameters
• config: mqtt configuration structure
esp_err_t esp_mqtt_client_register_event(esp_mqtt_client_handle_t client,
esp_mqtt_event_id_t event, esp_event_handler_t
event_handler, void *event_handler_arg)
Registers mqtt event.
Return ESP_ERR_NO_MEM if failed to allocate ESP_ERR_INVALID_ARG on wrong initialization
ESP_OK on success
Parameters
• event: event type
• event_handler: handler callback
• event_handler_arg: handlers context
int esp_mqtt_client_get_outbox_size(esp_mqtt_client_handle_t client)
Get outbox size.
Return outbox size 0 on wrong initialization
Parameters
Structures
struct esp_mqtt_error_codes
MQTT error code structure to be passed as a contextual information into ERROR event.
Important: This structure extends esp_tls_last_error error structure and is backward compatible with
it (so might be down-casted and treated as esp_tls_last_error error, but recommended to update
applications if used this way previously)
Use this structure directly checking error_type first and then appropriate error code depending on the source
of the error:
| error_type | related member variables | note | | MQTT_ERROR_TYPE_TCP_TRANSPORT |
esp_tls_last_esp_err, esp_tls_stack_err, esp_tls_cert_verify_flags, sock_errno | Error reported from
tcp_transport/esp-tls | | MQTT_ERROR_TYPE_CONNECTION_REFUSED | connect_return_code | Inter-
nal error reported from MQTT broker on connection |

Public Members
esp_err_t esp_tls_last_esp_err
last esp_err code reported from esp-tls component
int esp_tls_stack_err
tls specific error code reported from underlying tls stack
int esp_tls_cert_verify_flags
tls flags reported from underlying tls stack during certificate verification
esp_mqtt_error_type_t error_type
error type referring to the source of the error
esp_mqtt_connect_return_code_t connect_return_code
connection refused error code reported from MQTT broker on connection
int esp_transport_sock_errno
errno from the underlying socket
struct esp_mqtt_event_t
MQTT event configuration structure
Public Members
esp_mqtt_event_id_t event_id
MQTT event type
esp_mqtt_client_handle_t client
MQTT client handle for this event
void *user_context
User context passed from MQTT client config
char *data
Data associated with this event
int data_len
Length of the data for this event
int total_data_len
Total length of the data (longer data are supplied with multiple events)
int current_data_offset
Actual offset for the data associated with this event
char *topic
Topic associated with this event
int topic_len
Length of the topic for this event associated with this event
int msg_id
MQTT messaged id of message
int session_present
MQTT session_present flag for connection event
esp_mqtt_error_codes_t *error_handle
esp-mqtt error handle including esp-tls errors as well as internal mqtt errors
bool retain
Retained flag of the message associated with this event
struct esp_mqtt_client_config_t
MQTT client configuration structure

Public Members
mqtt_event_callback_t event_handle
handle for MQTT events as a callback in legacy mode
esp_event_loop_handle_t event_loop_handle
handle for MQTT event loop library
const char *host
MQTT server domain (ipv4 as string)
const char *uri
Complete MQTT broker URI
uint32_t port
MQTT server port
const char *client_id
default client id is ESP32_CHIPID% where CHIPID% are last 3 bytes of MAC address in hex format
const char *username
MQTT username
const char *password
MQTT password
const char *lwt_topic
LWT (Last Will and Testament) message topic (NULL by default)
const char *lwt_msg
LWT message (NULL by default)
int lwt_qos
LWT message qos
int lwt_retain
LWT retained message flag
int lwt_msg_len
LWT message length
int disable_clean_session
mqtt clean session, default clean_session is true
int keepalive
mqtt keepalive, default is 120 seconds
bool disable_auto_reconnect
this mqtt client will reconnect to server (when errors/disconnect). Set disable_auto_reconnect=true to
disable
void *user_context
pass user context to this option, then can receive that context in event->user_context
int task_prio
MQTT task priority, default is 5, can be changed in make menuconfig
int task_stack
MQTT task stack size, default is 6144 bytes, can be changed in make menuconfig
int buffer_size
size of MQTT send/receive buffer, default is 1024 (only receive buffer size if out_buffer_size
defined)
const char *cert_pem
Pointer to certificate data in PEM or DER format for server verify (with SSL), default is NULL, not re-
quired to verify the server. PEM-format must have a terminating NULL-character. DER-format requires
the length to be passed in cert_len.

size_t cert_len
Length of the buffer pointed to by cert_pem. May be 0 for null-terminated pem
const char *client_cert_pem
Pointer to certificate data in PEM or DER format for SSL mutual authentication, default is NULL, not
required if mutual authentication is not needed. If it is not NULL, also client_key_pem has to be
provided. PEM-format must have a terminating NULL-character. DER-format requires the length to be
passed in client_cert_len.
size_t client_cert_len
Length of the buffer pointed to by client_cert_pem. May be 0 for null-terminated pem
const char *client_key_pem
Pointer to private key data in PEM or DER format for SSL mutual authentication, default is NULL, not
required if mutual authentication is not needed. If it is not NULL, also client_cert_pem has to be
passed in client_key_len
size_t client_key_len
Length of the buffer pointed to by client_key_pem. May be 0 for null-terminated pem
esp_mqtt_transport_t transport
overrides URI transport
int refresh_connection_after_ms
Refresh connection after this value (in milliseconds)
const struct psk_key_hint *psk_hint_key
Pointer to PSK struct defined in esp_tls.h to enable PSK authentication (as alternative to certificate veri-
fication). If not NULL and server/client certificates are NULL, PSK is enabled
bool use_global_ca_store
Use a global ca_store for all the connections in which this bool is set.
esp_err_t (*crt_bundle_attach)(void *conf)
Pointer to ESP x509 Certificate Bundle attach function for the usage of certification bundles in mqtts
int reconnect_timeout_ms
Reconnect to the broker after this value in miliseconds if auto reconnect is not disabled (defaults to 10s)
const char **alpn_protos
NULL-terminated list of supported application protocols to be used for ALPN
const char *clientkey_password
Client key decryption password string
int clientkey_password_len
String length of the password pointed to by clientkey_password
esp_mqtt_protocol_ver_t protocol_ver
MQTT protocol version used for connection, defaults to value from menuconfig
int out_buffer_size
size of MQTT output buffer. If not defined, both output and input buffers have the same size defined as
buffer_size
bool skip_cert_common_name_check
Skip any validation of server certificate CN field, this reduces the security of TLS and makes the mqtt
client susceptible to MITM attacks
bool use_secure_element
enable secure element for enabling SSL connection
void *ds_data
carrier of handle for digital signature parameters
int network_timeout_ms
Abort network operation if it is not completed after this value, in milliseconds (defaults to 10s)

bool disable_keepalive
Set disable_keepalive=true to turn off keep-alive mechanism, false by default (keepalive is active by
default). Note: setting the config value keepalive to 0 doesn t disable keepalive feature, but uses a
default keepalive period
const char *path
Path in the URI
int message_retransmit_timeout
timeout for retansmit of failded packet
Macros
MQTT_ERROR_TYPE_ESP_TLS
MQTT_ERROR_TYPE_TCP_TRANSPORT error type hold all sorts of transport layer errors, including ESP-
TLS error, but in the past only the errors from MQTT_ERROR_TYPE_ESP_TLS layer were reported, so the
ESP-TLS error type is re-defined here for backward compatibility
Type Definitions
typedef struct esp_mqtt_client *esp_mqtt_client_handle_t
typedef struct esp_mqtt_error_codes esp_mqtt_error_codes_t
MQTT error code structure to be passed as a contextual information into ERROR event.
Important: This structure extends esp_tls_last_error error structure and is backward compatible with
it (so might be down-casted and treated as esp_tls_last_error error, but recommended to update
applications if used this way previously)
Use this structure directly checking error_type first and then appropriate error code depending on the source
of the error:
| error_type | related member variables | note | | MQTT_ERROR_TYPE_TCP_TRANSPORT |
esp_tls_last_esp_err, esp_tls_stack_err, esp_tls_cert_verify_flags, sock_errno | Error reported from
tcp_transport/esp-tls | | MQTT_ERROR_TYPE_CONNECTION_REFUSED | connect_return_code | Inter-
nal error reported from MQTT broker on connection |
typedef esp_mqtt_event_t *esp_mqtt_event_handle_t
typedef esp_err_t (*mqtt_event_callback_t)(esp_mqtt_event_handle_t event)
Enumerations
enum esp_mqtt_event_id_t
MQTT event types.
User event handler receives context data in esp_mqtt_event_t structure with
• user_context - user data from esp_mqtt_client_config_t
• client - mqtt client handle
• various other data depending on event type
Values:
MQTT_EVENT_ANY = -1
MQTT_EVENT_ERROR = 0
on error event, additional context: connection return code, error handle from esp_tls (if supported)
MQTT_EVENT_CONNECTED
connected event, additional context: session_present flag
MQTT_EVENT_DISCONNECTED
disconnected event
MQTT_EVENT_SUBSCRIBED
subscribed event, additional context: msg_id

MQTT_EVENT_UNSUBSCRIBED
unsubscribed event
MQTT_EVENT_PUBLISHED
published event, additional context: msg_id
MQTT_EVENT_DATA
data event, additional context:
• msg_id message id
• topic pointer to the received topic
• topic_len length of the topic
• data pointer to the received data
• data_len length of the data for this event
• current_data_offset offset of the current data for this event
• total_data_len total length of the data received
• retain retain flag of the message Note: Multiple MQTT_EVENT_DATA could be fired for one
message, if it is longer than internal buffer. In that case only first event contains topic pointer and
length, other contain data only with current data length and current data offset updating.
MQTT_EVENT_BEFORE_CONNECT
The event occurs before connecting
MQTT_EVENT_DELETED
Notification on delete of one message from the internal outbox, if the message couldn t have been sent
and acknowledged before expiring defined in OUTBOX_EXPIRED_TIMEOUT_MS. (events are not
posted upon deletion of successfully acknowledged messages)
• This event id is posted only if MQTT_REPORT_DELETED_MESSAGES==1
• Additional context: msg_id (id of the deleted message).
enum esp_mqtt_connect_return_code_t
MQTT connection error codes propagated via ERROR event
Values:
MQTT_CONNECTION_ACCEPTED = 0
Connection accepted
MQTT_CONNECTION_REFUSE_PROTOCOL
MQTT connection refused reason: Wrong protocol
MQTT_CONNECTION_REFUSE_ID_REJECTED
MQTT connection refused reason: ID rejected
MQTT_CONNECTION_REFUSE_SERVER_UNAVAILABLE
MQTT connection refused reason: Server unavailable
MQTT_CONNECTION_REFUSE_BAD_USERNAME
MQTT connection refused reason: Wrong user
MQTT_CONNECTION_REFUSE_NOT_AUTHORIZED
MQTT connection refused reason: Wrong username or password
enum esp_mqtt_error_type_t
MQTT connection error codes propagated via ERROR event
Values:
MQTT_ERROR_TYPE_NONE = 0
MQTT_ERROR_TYPE_TCP_TRANSPORT
MQTT_ERROR_TYPE_CONNECTION_REFUSED
enum esp_mqtt_transport_t
Values:
MQTT_TRANSPORT_UNKNOWN = 0x0

MQTT_TRANSPORT_OVER_TCP
MQTT over TCP, using scheme: mqtt
MQTT_TRANSPORT_OVER_SSL
MQTT over SSL, using scheme: mqtts
MQTT_TRANSPORT_OVER_WS
MQTT over Websocket, using scheme:: ws
MQTT_TRANSPORT_OVER_WSS
MQTT over Websocket Secure, using scheme: wss
enum esp_mqtt_protocol_ver_t
MQTT protocol version used for connection
Values:
MQTT_PROTOCOL_UNDEFINED = 0
MQTT_PROTOCOL_V_3_1
MQTT_PROTOCOL_V_3_1_1
2.4.3 ESP-TLS
Overview
The ESP-TLS component provides a simplified API interface for accessing the commonly used TLS functionality.
It supports common scenarios like CA certification validation, SNI, ALPN negotiation, non-blocking connection
among others. All the configuration can be specified in the esp_tls_cfg_t data structure. Once done, TLS
communication can be conducted using the following APIs:
• esp_tls_conn_new(): for opening a new TLS connection.
• esp_tls_conn_read(): for reading from the connection.
• esp_tls_conn_write(): for writing into the connection.
• esp_tls_conn_delete(): for freeing up the connection.
Any application layer protocol like HTTP1, HTTP2 etc can be executed on top of this layer.
Application Example
Simple HTTPS example that uses ESP-TLS to establish a secure socket connection: protocols/https_request.
Tree structure for ESP-TLS component
├── esp_tls.c
├── esp_tls.h
├── esp_tls_mbedtls.c
├── esp_tls_wolfssl.c
└── private_include
├── esp_tls_mbedtls.h
└── esp_tls_wolfssl.h
The ESP-TLS component has a file esp-tls/esp_tls.h which contain the public API headers for the component. Inter-
nally ESP-TLS component uses one of the two SSL/TLS Libraries between mbedtls and wolfssl for its operation. API
specific to mbedtls are present in esp-tls/private_include/esp_tls_mbedtls.h and API specific to wolfssl are present in
esp-tls/private_include/esp_tls_wolfssl.h.

TLS Server verification
The ESP-TLS provides multiple options for TLS server verification on the client side. The ESP-TLS client can verify
the server by validating the peer s server certificate or with the help of pre-shared keys. The user should select only
one of the following options in the esp_tls_cfg_t structure for TLS server verification. If no option is selected
then client will return a fatal error by default at the time of the TLS connection setup.
• cacert_buf and cacert_bytes: The CA certificate can be provided in a buffer to the esp_tls_cfg_t struc-
ture. The ESP-TLS will use the CA certificate present in the buffer to verify the server. The following variables
in esp_tls_cfg_t structure must be set.
– cacert_buf - pointer to the buffer which contains the CA cert.
– cacert_bytes - size of the CA certificate in bytes.
• use_global_ca_store: The global_ca_store can be initialized and set at once. Then it can be used
to verify the server for all the ESP-TLS connections which have set use_global_ca_store = true
in their respective esp_tls_cfg_t structure. See API Reference section below on information regarding
different API used for initializing and setting up the global_ca_store.
• crt_bundle_attach: The ESP x509 Certificate Bundle API provides an easy way to include a bundle of custom
x509 root certificates for TLS server verification. More details can be found at ESP x509 Certificate Bundle
• psk_hint_key: To use pre-shared keys for server verification, CONFIG_ESP_TLS_PSK_VERIFICATION
should be enabled in the ESP-TLS menuconfig. Then the pointer to PSK hint and key should be provided
to the esp_tls_cfg_t structure. The ESP-TLS will use the PSK for server verification only when no other
option regarding the server verification is selected.
• skip server verification: This is an insecure option provided in the ESP-TLS for test-
ing purpose. The option can be set by enabling CONFIG_ESP_TLS_INSECURE and CON-
FIG_ESP_TLS_SKIP_SERVER_CERT_VERIFY in the ESP-TLS menuconfig. When this option is enabled the
ESP-TLS will skip server verification by default when no other options for server verification are selected in
the esp_tls_cfg_t structure. WARNING:Enabling this option comes with a potential risk of establishing a
TLS connection with a server which has a fake identity, provided that the server certificate is not provided either
through API or other mechanism like ca_store etc.
Underlying SSL/TLS Library Options
The ESP-TLS component has an option to use mbedtls or wolfssl as their underlying SSL/TLS library. By default
only mbedtls is available and is used, wolfssl SSL/TLS library is available publicly at https://github.com/espressif/
esp-wolfssl. The repository provides wolfssl component in binary format, it also provides few examples which are
useful for understanding the API. Please refer the repository README.md for information on licensing and other
options. Please see below option for using wolfssl in your project.
Note: As the library options are internal to ESP-TLS, switching the libries will not change ESP-TLS specific code for
a project.
How to use wolfssl with ESP-IDF
There are two ways to use wolfssl in your project

1) Directly add wolfssl as a component in your project with following three commands.:
(First change directory (cd) to your project directory)

mkdir components
cd components
git clone https://github.com/espressif/esp-wolfssl.git
2) Add wolfssl as an extra component in your project.

• Download wolfssl with:
git clone https://github.com/espressif/esp-wolfssl.git

• Include esp-wolfssl in ESP-IDF with setting EXTRA_COMPONENT_DIRS in CMakeLists.txt of your project

as done in wolfssl/examples. For reference see Optional Project variables in build-system.
After above steps, you will have option to choose wolfssl as underlying SSL/TLS library in configuration menu of
your project as follows:
idf.py menuconfig -> ESP-TLS -> choose SSL/TLS Library -> mbedtls/wolfssl
Comparison between mbedtls and wolfssl
The following table shows a typical comparison between wolfssl and mbedtls when protocols/https_request exam-
ple (which has server authentication) was run with both SSL/TLS libraries and with all respective configurations
set to default. (mbedtls IN_CONTENT length and OUT_CONTENT length were set to 16384 bytes and 4096 bytes
respectively)
Property Wolfssl Mbedtls

Total Heap Consumed ~19 Kb ~37 Kb
Task Stack Used ~2.2 Kb ~3.6 Kb
Bin size ~858 Kb ~736 Kb
Note: These values are subject to change with change in configuration options and version of respective libraries.
ATECC608A (Secure Element) with ESP-TLS
ESP-TLS provides support for using ATECC608A cryptoauth chip with ESP32-WROOM-32SE. Use of
ATECC608A is supported only when ESP-TLS is used with mbedTLS as its underlying SSL/TLS stack. ESP-TLS
uses mbedtls as its underlying TLS/SSL stack by default unless changed manually.
Note: ATECC608A chip on ESP32-WROOM-32SE must be already configured and provisioned, for details refer
esp_cryptoauth_utility
To enable the secure element support, and use it in you project for TLS connection, you will have to follow below
steps
1) Add esp-cryptoauthlib in your project, for details please refer esp-cryptoauthlib with ESP_IDF
2) Enable following menuconfig option:
menuconfig->Component config->ESP-TLS->Use Secure Element (ATECC608A) with ESP-

,→TLS
3) Select type of ATECC608A chip with following option:
menuconfig->Component config->esp-cryptoauthlib->Choose Type of ATECC608A chip
to know more about different types of ATECC608A chips and how to obtain type of ATECC608A connected to
your ESP module please visit ATECC608A chip type
4) Enable use of ATECC608A in ESP-TLS by providing following config option in esp_tls_cfg_t
esp_tls_cfg_t cfg = {
/* other configurations options */
.use_secure_element = true,
};

API Reference
Header File
• components/esp-tls/esp_tls.h
Functions
esp_tls_t *esp_tls_init(void)
Create TLS connection.
This function allocates and initializes esp-tls structure handle.
Return tls Pointer to esp-tls as esp-tls handle if successfully initialized, NULL if allocation error
esp_tls_t *esp_tls_conn_new(const char *hostname, int hostlen, int port, const esp_tls_cfg_t *cfg)
Create a new blocking TLS/SSL connection.
This function establishes a TLS/SSL connection with the specified host in blocking manner.
Note: This API is present for backward compatibility reasons. Alternative function with the same functionality
is esp_tls_conn_new_sync (and its asynchronous version esp_tls_conn_new_async)
Return pointer to esp_tls_t, or NULL if connection couldn t be opened.
Parameters
• [in] hostname: Hostname of the host.
• [in] hostlen: Length of hostname.
• [in] port: Port number of the host.
• [in] cfg: TLS configuration as esp_tls_cfg_t. If you wish to open non-TLS connection, keep this
NULL. For TLS connection, a pass pointer to esp_tls_cfg_t. At a minimum, this structure should
be zero-initialized.
int esp_tls_conn_new_sync(const char *hostname, int hostlen, int port, const esp_tls_cfg_t *cfg,
esp_tls_t *tls)
Create a new blocking TLS/SSL connection.
This function establishes a TLS/SSL connection with the specified host in blocking manner.
Return
• -1 If connection establishment fails.
• 1 If connection establishment is successful.
• 0 If connection state is in progress.
Parameters
• [in] cfg: TLS configuration as esp_tls_cfg_t. If you wish to open non-TLS connection, keep this
NULL. For TLS connection, a pass pointer to esp_tls_cfg_t. At a minimum, this structure should
be zero-initialized.
• [in] tls: Pointer to esp-tls as esp-tls handle.
esp_tls_t *esp_tls_conn_http_new(const char *url, const esp_tls_cfg_t *cfg)
Create a new blocking TLS/SSL connection with a given HTTP url.
The behaviour is same as esp_tls_conn_new() API. However this API accepts host s url.
Return pointer to esp_tls_t, or NULL if connection couldn t be opened.
Parameters
• [in] url: url of host.
• [in] cfg: TLS configuration as esp_tls_cfg_t. If you wish to open non-TLS connection, keep
this NULL. For TLS connection, a pass pointer to esp_tls_cfg_t . At a minimum, this structure
should be zero-initialized.
int esp_tls_conn_new_async(const char *hostname, int hostlen, int port, const esp_tls_cfg_t *cfg,
esp_tls_t *tls)
Create a new non-blocking TLS/SSL connection.

This function initiates a non-blocking TLS/SSL connection with the specified host, but due to its non-blocking
nature, it doesn t wait for the connection to get established.
Return
• 0 If connection establishment is in progress.
Parameters
• [in] cfg: TLS configuration as esp_tls_cfg_t. non_block member of this structure should be
set to be true.
• [in] tls: pointer to esp-tls as esp-tls handle.
int esp_tls_conn_http_new_async(const char *url, const esp_tls_cfg_t *cfg, esp_tls_t *tls)
Create a new non-blocking TLS/SSL connection with a given HTTP url.
The behaviour is same as esp_tls_conn_new() API. However this API accepts host s url.
Return
• 0 If connection establishment is in progress.
Parameters
• [in] url: url of host.
• [in] cfg: TLS configuration as esp_tls_cfg_t.
static ssize_t esp_tls_conn_write(esp_tls_t *tls, const void *data, size_t datalen)
Write from buffer data into specified tls connection.
Return
• >=0 if write operation was successful, the return value is the number of bytes actually written to the
TLS/SSL connection.
• <0 if write operation was not successful, because either an error occured or an action must be taken
by the calling process.
• ESP_TLS_ERR_SSL_WANT_READ/ ESP_TLS_ERR_SSL_WANT_WRITE. if the handshake
is incomplete and waiting for data to be available for reading. In this case this functions needs to be
called again when the underlying transport is ready for operation.
Parameters
• [in] data: Buffer from which data will be written.
• [in] datalen: Length of data buffer.
static ssize_t esp_tls_conn_read(esp_tls_t *tls, void *data, size_t datalen)
Read from specified tls connection into the buffer data .
Return
• >0 if read operation was successful, the return value is the number of bytes actually read from the
TLS/SSL connection.
• 0 if read operation was not successful. The underlying connection was closed.
• <0 if read operation was not successful, because either an error occured or an action must be taken
by the calling process.
Parameters
• [in] data: Buffer to hold read data.
• [in] datalen: Length of data buffer.
void esp_tls_conn_delete(esp_tls_t *tls)
Compatible version of esp_tls_conn_destroy() to close the TLS/SSL connection.
Note This API will be removed in IDFv5.0

Parameters
int esp_tls_conn_destroy(esp_tls_t *tls)
Close the TLS/SSL connection and free any allocated resources.
This function should be called to close each tls connection opened with esp_tls_conn_new() or
esp_tls_conn_http_new() APIs.
Return - 0 on success
• -1 if socket error or an invalid argument
Parameters
ssize_t esp_tls_get_bytes_avail(esp_tls_t *tls)
Return the number of application data bytes remaining to be read from the current record.
This API is a wrapper over mbedtls s mbedtls_ssl_get_bytes_avail() API.
Return
• -1 in case of invalid arg
• bytes available in the application data record read buffer
Parameters
esp_err_t esp_tls_get_conn_sockfd(esp_tls_t *tls, int *sockfd)
Returns the connection socket file descriptor from esp_tls session.
Return - ESP_OK on success and value of sockfd will be updated with socket file descriptor for connection
• ESP_ERR_INVALID_ARG if (tls == NULL || sockfd == NULL)
Parameters
• [in] tls: handle to esp_tls context
• [out] sockfd: int pointer to sockfd value.
esp_err_t esp_tls_init_global_ca_store(void)
Create a global CA store, initially empty.
This function should be called if the application wants to use the same CA store for multiple connections. This
function initialises the global CA store which can be then set by calling esp_tls_set_global_ca_store(). To be
effective, this function must be called before any call to esp_tls_set_global_ca_store().
Return
• ESP_OK if creating global CA store was successful.
• ESP_ERR_NO_MEM if an error occured when allocating the mbedTLS resources.
esp_err_t esp_tls_set_global_ca_store(const unsigned char *cacert_pem_buf, const un-
signed int cacert_pem_bytes)
Set the global CA store with the buffer provided in pem format.
This function should be called if the application wants to set the global CA store for multiple connections
i.e. to add the certificates in the provided buffer to the certificate chain. This function implicitly calls
esp_tls_init_global_ca_store() if it has not already been called. The application must call this function be-
fore calling esp_tls_conn_new().
Return
• ESP_OK if adding certificates was successful.
• Other if an error occured or an action must be taken by the calling process.
Parameters
• [in] cacert_pem_buf: Buffer which has certificates in pem format. This buffer is used for
creating a global CA store, which can be used by other tls connections.
• [in] cacert_pem_bytes: Length of the buffer.
void esp_tls_free_global_ca_store(void)
Free the global CA store currently being used.

The memory being used by the global CA store to store all the parsed certificates is freed up. The application
can call this API if it no longer needs the global CA store.
esp_err_t esp_tls_get_and_clear_last_error(esp_tls_error_handle_t h, int *esp_tls_code, int
*esp_tls_flags)
Returns last error in esp_tls with detailed mbedtls related error codes. The error information is cleared internally
upon return.
Return
• ESP_ERR_INVALID_STATE if invalid parameters
• ESP_OK (0) if no error occurred
• specific error code (based on ESP_ERR_ESP_TLS_BASE) otherwise
Parameters
• [in] h: esp-tls error handle.
• [out] esp_tls_code: last error code returned from mbedtls api (set to zero if none) This
pointer could be NULL if caller does not care about esp_tls_code
• [out] esp_tls_flags: last certification verification flags (set to zero if none) This pointer
could be NULL if caller does not care about esp_tls_code
esp_err_t esp_tls_get_and_clear_error_type(esp_tls_error_handle_t h, esp_tls_error_type_t
err_type, int *error_code)
Returns the last error captured in esp_tls of a specific type The error information is cleared internally upon
return.
Return
• ESP_ERR_INVALID_STATE if invalid parameters
• ESP_OK if a valid error returned and was cleared
Parameters
• [in] h: esp-tls error handle.
• [in] err_type: specific error type
• [out] error_code: last error code returned from mbedtls api (set to zero if none) This pointer
could be NULL if caller does not care about esp_tls_code
mbedtls_x509_crt *esp_tls_get_global_ca_store(void)
Get the pointer to the global CA store currently being used.
The application must first call esp_tls_set_global_ca_store(). Then the same CA store could be used by the
application for APIs other than esp_tls.
Note Modifying the pointer might cause a failure in verifying the certificates.
Return
• Pointer to the global CA store currently being used if successful.
• NULL if there is no global CA store set.
esp_err_t esp_tls_plain_tcp_connect(const char *host, int hostlen, int port, const esp_tls_cfg_t
*cfg, esp_tls_error_handle_t error_handle, int *sockfd)
Creates a plain TCP connection, returning a valid socket fd on success or an error handle.
Return ESP_OK on success ESP_ERR_INVALID_ARG if invalid output parameters ESP-TLS based error
codes on failure
Parameters
• [in] host: Hostname of the host.
• [in] cfg: ESP-TLS configuration as esp_tls_cfg_t.
• [out] error_handle: ESP-TLS error handle holding potential errors occurred during con-
nection
• [out] sockfd: Socket descriptor if successfully connected on TCP layer
Structures
struct psk_key_hint
ESP-TLS preshared key and hint structure.

Public Members
const uint8_t *key

key in PSK authentication mode in binary format
const size_t key_size
length of the key
const char *hint
hint in PSK authentication mode in string format
struct tls_keep_alive_cfg
esp-tls client session ticket ctx
Keep alive parameters structure
Public Members
bool keep_alive_enable
Enable keep-alive timeout
int keep_alive_idle
Keep-alive idle time (second)
int keep_alive_interval
Keep-alive interval time (second)
int keep_alive_count
Keep-alive packet retry send count
struct esp_tls_cfg
ESP-TLS configuration parameters.
Note Note about format of certificates:
• This structure includes certificates of a Certificate Authority, of client or server as well as private
keys, which may be of PEM or DER format. In case of PEM format, the buffer must be NULL
terminated (with NULL character included in certificate size).
• Certificate Authority s certificate may be a chain of certificates in case of PEM format, but could
be only one certificate in case of DER format
• Variables names of certificates and private key buffers and sizes are defined as unions providing
backward compatibility for legacy *_pem_buf and *_pem_bytes names which suggested only PEM
format was supported. It is encouraged to use generic names such as cacert_buf and cacert_bytes.
Public Members
const char **alpn_protos

Application protocols required for HTTP2. If HTTP2/ALPN support is required, a list of protocols that
should be negotiated. The format is length followed by protocol name. For the most common cases the
following is ok: const char **alpn_protos = { h2 , NULL };
• where h2 is the protocol name
const unsigned char *cacert_buf
Certificate Authority s certificate in a buffer. Format may be PEM or DER, depending on mbedtls-
support This buffer should be NULL terminated in case of PEM
const unsigned char *cacert_pem_buf
CA certificate buffer legacy name
unsigned int cacert_bytes
Size of Certificate Authority certificate pointed to by cacert_buf (including NULL-terminator in case of
PEM format)

unsigned int cacert_pem_bytes

Size of Certificate Authority certificate legacy name
const unsigned char *clientcert_buf
Client certificate in a buffer Format may be PEM or DER, depending on mbedtls-support This buffer
should be NULL terminated in case of PEM
const unsigned char *clientcert_pem_buf
Client certificate legacy name
unsigned int clientcert_bytes
Size of client certificate pointed to by clientcert_pem_buf (including NULL-terminator in case of PEM
format)
unsigned int clientcert_pem_bytes
Size of client certificate legacy name
const unsigned char *clientkey_buf
Client key in a buffer Format may be PEM or DER, depending on mbedtls-support This buffer should be
NULL terminated in case of PEM
const unsigned char *clientkey_pem_buf
Client key legacy name
unsigned int clientkey_bytes
Size of client key pointed to by clientkey_pem_buf (including NULL-terminator in case of PEM format)
unsigned int clientkey_pem_bytes
Size of client key legacy name
const unsigned char *clientkey_password
unsigned int clientkey_password_len
String length of the password pointed to by clientkey_password
bool non_block
Configure non-blocking mode. If set to true the underneath socket will be configured in non blocking
mode after tls session is established
bool use_secure_element
Enable this option to use secure element or atecc608a chip ( Integrated with ESP32-WROOM-32SE )
int timeout_ms
Network timeout in milliseconds
const char *common_name
If non-NULL, server certificate CN must match this name. If NULL, server certificate CN must match
hostname.
bool skip_common_name
Skip any validation of server certificate CN field
tls_keep_alive_cfg_t *keep_alive_cfg
Enable TCP keep-alive timeout for SSL connection
const psk_hint_key_t *psk_hint_key
Pointer to PSK hint and key. if not NULL (and certificates are NULL) then PSK authentication is enabled
with configured setup. Important note: the pointer must be valid for connection
Function pointer to esp_crt_bundle_attach. Enables the use of certification bundle for server verification,
must be enabled in menuconfig

void *ds_data
Pointer for digital signature peripheral context
bool is_plain_tcp
Use non-TLS connection: When set to true, the esp-tls uses plain TCP transport rather then
TLS/SSL connection. Note, that it is possible to connect using a plain tcp transport directly with
esp_tls_plain_tcp_connect() API
struct ifreq *if_name
The name of interface for data to go through. Use the default interface without setting
struct esp_tls
ESP-TLS Connection Handle.
Public Members
mbedtls_ssl_context ssl
TLS/SSL context
mbedtls_entropy_context entropy
mbedTLS entropy context structure
mbedtls_ctr_drbg_context ctr_drbg
mbedTLS ctr drbg context structure. CTR_DRBG is deterministic random bit generation based on AES-
256
mbedtls_ssl_config conf
TLS/SSL configuration to be shared between mbedtls_ssl_context structures
mbedtls_net_context server_fd
mbedTLS wrapper type for sockets
mbedtls_x509_crt cacert
Container for the X.509 CA certificate
mbedtls_x509_crt *cacert_ptr
Pointer to the cacert being used.
mbedtls_x509_crt clientcert
Container for the X.509 client certificate
mbedtls_pk_context clientkey
Container for the private key of the client certificate
int sockfd
Underlying socket file descriptor.
ssize_t (*read)(struct esp_tls *tls, char *data, size_t datalen)
Callback function for reading data from TLS/SSL connection.
ssize_t (*write)(struct esp_tls *tls, const char *data, size_t datalen)
Callback function for writing data to TLS/SSL connection.
esp_tls_conn_state_t conn_state
ESP-TLS Connection state
fd_set rset
read file descriptors
fd_set wset
write file descriptors
bool is_tls
indicates connection type (TLS or NON-TLS)
esp_tls_role_t role
esp-tls role

• ESP_TLS_CLIENT
• ESP_TLS_SERVER
esp_tls_error_handle_t error_handle
handle to error descriptor
Type Definitions
typedef enum esp_tls_conn_state esp_tls_conn_state_t
ESP-TLS Connection State.
typedef enum esp_tls_role esp_tls_role_t
typedef struct psk_key_hint psk_hint_key_t
ESP-TLS preshared key and hint structure.
typedef struct tls_keep_alive_cfg tls_keep_alive_cfg_t
esp-tls client session ticket ctx
Keep alive parameters structure
typedef struct esp_tls_cfg esp_tls_cfg_t
ESP-TLS configuration parameters.
Note Note about format of certificates:
• This structure includes certificates of a Certificate Authority, of client or server as well as private
keys, which may be of PEM or DER format. In case of PEM format, the buffer must be NULL
terminated (with NULL character included in certificate size).
• Certificate Authority s certificate may be a chain of certificates in case of PEM format, but could
be only one certificate in case of DER format
• Variables names of certificates and private key buffers and sizes are defined as unions providing
backward compatibility for legacy *_pem_buf and *_pem_bytes names which suggested only PEM
format was supported. It is encouraged to use generic names such as cacert_buf and cacert_bytes.
typedef struct esp_tls esp_tls_t
ESP-TLS Connection Handle.
Enumerations
enum esp_tls_conn_state
ESP-TLS Connection State.
Values:
ESP_TLS_INIT = 0
ESP_TLS_CONNECTING
ESP_TLS_HANDSHAKE
ESP_TLS_FAIL
ESP_TLS_DONE
enum esp_tls_role
Values:
ESP_TLS_CLIENT = 0
ESP_TLS_SERVER
2.4.4 OpenSSL-APIs
Note: The OpenSSL-API will be discontinued in ESP-IDF from v5.0. Please use ESP-TLS <esp_tls> instead.

The code of this API (located in openssl directory), does not contain OpenSSL itself but is intended as a wrapper
for applications using the OpenSSL API. It uses mbedTLS to do the actual work, so anyone compiling openssl code
needs the mbedtls library and header file.
OpenSSL APIs not mentioned in this article are not open to public for the time, also do not have the corresponding
function. If user calls it directly, it will always return an error or may show cannot link at compiling time.
Chapter Introduction
• Chapter 1. SSL Context Method Create

• Chapter 2. SSL Context Function
• Chapter 3. SSL Function
• Chapter 4. SSL X509 Certification and Private Key Function
Chapter 1. SSL Context Method Create
1.1 const SSL_METHOD* SSLv3_client_method (void)

Arguments:
none
Return:
SSLV3.0 version SSL context client method point
Description:
create the target SSL context method
Example:
void example(void)
{
const SSL_METHOD *method = SSLv3_client_method();
...
}
1.2 const SSL_METHOD* TLSv1_client_method (void)

Arguments:
none
Return:
TLSV1.0 version SSL context client method point
Description:
Example:
void example(void)
{
const SSL_METHOD *method = TLSv1_client_method();
...
}

1.3 const SSL_METHOD* TLSv1_1_client_method (void)

Arguments:
none
Return:
Description:
Example:
void example(void)
{
const SSL_METHOD *method = TLSv1_1_client_method();
...
}
1.4 const SSL_METHOD* TLSv1_2_client_method (void)

Arguments:
none
Return:
Description:
Example:
void example(void)
{
...
}
1.5 const SSL_METHOD* TLS_client_method (void)

Arguments:
none
Return:
Description:
create the default SSL context method, it's always to be TLSV1.2
Example:

void example(void)
{
...
}
1.6 const SSL_METHOD* SSLv3_server_method (void)

Arguments:
none
Return:
SSLV3.0 version SSL context server method point
Description:
Example:
void example(void)
{
const SSL_METHOD *method = SSLv3_server_method();
...
}
1.7 const SSL_METHOD* TLSv1_server_method (void)

Arguments:
none
Return:
TLSV1.0 version SSL context server method point
Description:
Example:
void example(void)
{
const SSL_METHOD *method = TLSv1_server_method();
...
}
1.8 const SSL_METHOD* TLSv1_1_server_method (void)

Arguments:
none
Return:

Description:
Example:
void example(void)
{
const SSL_METHOD *method = TLSv1_1_server_method();
...
}
1.9 const SSL_METHOD* TLSv1_2_server_method (void)

Arguments:
none
Return:
Description:
Example:
void example(void)
{
...
}
1.10 const SSL_METHOD* TLS_server_method (void)

Arguments:
none
Return:
Description:
create the default SSL context method, it's always to be TLSV1.2
Example:
void example(void)
{
...
}
Chapter 2. SSL Context Function
2.1 SSL_CTX* SSL_CTX_new (const SSL_METHOD * method)

Arguments:
method - the SSL context method point
Return:
context point
Description:
create a SSL context
Example:
void example(void)
{
SSL_CTX *ctx = SSL_CTX_new(SSLv3_server_method());
...
}
2.2 void SSL_CTX_free (SSL_CTX * ctx)

Arguments:
ctx - the SSL context point
Return:
none
Description:
free a SSL context
Example:
void example(void)
{
SSL_CTX *ctx;
... ...
SSL_CTX_free(ctx);
}
2.3 int SSL_CTX_set_ssl_version (SSL_CTX * ctx, const SSL_METHOD * meth)

Arguments:
ctx - SSL context point

meth - SSL method point
Return:
1 : OK
0 : failed
Description:
set the SSL context version
Example:

void example(void)
{
SSL_CTX *ctx;
const SSL_METHOD *meth;
... ...
SSL_CTX_set_ssl_version(ctx, meth);
}
2.4 const SSL_METHOD* SSL_CTX_get_ssl_method (SSL_CTX * ctx)

Arguments:
Return:
SSL context method
Description:
get the SSL context method
Example:
void example(void)
{
const SSL_METHOD *method;
SSL_CTX *ctx;
... ...
method = SSL_CTX_get_ssl_method(ctx);
}
Chapter 3. SSL Function
3.1 SSL* SSL_new (SSL_CTX * ctx)

Arguments:
Return:
SSL method
Description:
create a SSL
Example:
void example(void)
{
SSL *ssl;
SSL_CTX *ctx;
... ...


ssl = SSL_new(ctx);
}
3.2 void SSL_free (SSL * ssl)

Arguments:
ssl - SSL point
Return:
none
Description:
free SSL
Example:
void example(void)
{
SSL *ssl;
... ...
SSL_free(ssl);
}
3.3 int SSL_do_handshake (SSL * ssl)

Arguments:
ssl - SSL point
Return:
1 : OK
0 : failed, connect is close by remote
-1 : a error catch
Description:
perform the SSL handshake
Example:
void example(void)
{
SSL *ssl;
int ret;
... ...
ret = SSL_do_handshake(ssl);
}
3.4 int SSL_connect (SSL * ssl)

Arguments:
ssl - SSL point
Return:

1 : OK
-1 : a error catch
Description:
connect to the remote SSL server
Example:
void example(void)
{
SSL *ssl;
int ret;
... ...
ret = SSL_connect(ssl);
}
3.5 int SSL_accept (SSL * ssl)

Arguments:
ssl - SSL point
Return:
1 : OK
-1 : a error catch
Description:
accept the remote connection
Example:
void example(void)
{
SSL *ssl;
int ret;
... ...
ret = SSL_accept(ssl);
}
3.6 int SSL_shutdown (SSL * ssl)

Arguments:
ssl - SSL point
Return:
1 : OK
-1 : a error catch
Description:

shutdown the connection
Example:
void example(void)
{
SSL *ssl;
int ret;
... ...
ret = SSL_shutdown(ssl);
}
3.7 int SSL_clear (SSL * ssl)

Arguments:
ssl - SSL point
Return:
1 : OK
0 : failed
Description:
shutdown the connection
Example:
void example(void)
{
SSL *ssl;
int ret;
... ...
ret = SSL_clear(ssl);
}
3.8 int SSL_read (SSL * ssl, void * buffer, int len)

Arguments:
ssl - point
buffer - data buffer point
len - data length
Return:
> 0 : OK, and return received data bytes

= 0 : no data received or connection is closed
< 0 : an error catch
Description:
read data from remote
Example:

void example(void)
{
SSL *ssl;
char *buf;
int len;
int ret;
... ...
ret = SSL_read(ssl, buf, len);

}
3.9 int SSL_write (SSL * ssl, const void * buffer, int len)
Arguments:
ssl - SSL point

buffer - data buffer point
len - data length
Return:
> 0 : OK, and return received data bytes

= 0 : no data sent or connection is closed
< 0 : an error catch
Description:
send the data to remote
Example:
void example(void)
{
SSL *ssl;
char *buf;
int len;
int ret;
... ...
ret = SSL_write(ssl, buf, len);

}
3.10 SSL_CTX *SSL_get_SSL_CTX (const SSL * ssl)

Arguments:
ssl - SSL point
Return:
SSL context
Description:
get SSL context of the SSL
Example:
void example(void)
{


SSL *ssl;
SSL_CTX *ctx;
... ...
ctx = SSL_get_SSL_CTX(ssl);
}
3.11 int SSL_get_shutdown (const SSL * ssl)

Arguments:
ssl - SSL point
Return:
shutdown mode
Description:
get SSL shutdown mode
Example:
void example(void)
{
SSL *ssl;
int mode;
... ...
mode = SSL_get_SSL_CTX(ssl);
}
3.12 void SSL_set_shutdown (SSL * ssl, int mode)

Arguments:
ssl - SSL point
Return:
shutdown mode
Description:
set SSL shutdown mode
Example:
void example(void)
{
SSL *ssl;
int mode = 0;
... ...
SSL_set_shutdown(ssl, mode);
}
3.13 const SSL_METHOD* SSL_get_ssl_method (SSL * ssl)

Arguments:

ssl - SSL point
Return:
SSL method
Description:
set SSL shutdown mode
Example:
void example(void)
{
SSL *ssl;
... ...
method = SSL_get_ssl_method(ssl);
}
3.14 int SSL_set_ssl_method (SSL * ssl, const SSL_METHOD * method)

Arguments:
ssl - SSL point

meth - SSL method point
Return:
1 : OK
0 : failed
Description:
set the SSL method
Example:
void example(void)
{
int ret;
SSL *ssl;
... ...
ret = SSL_set_ssl_method(ssl, method);

}
3.15 int SSL_pending (const SSL * ssl)

Arguments:
ssl - SSL point
Return:
data bytes
Description:

get received data bytes
Example:
void example(void)
{
int ret;
SSL *ssl;
... ...
ret = SSL_pending(ssl);
}
3.16 int SSL_has_pending (const SSL * ssl)

Arguments:
ssl - SSL point
Return:
1 : Yes
0 : No
Description:
check if data is received
Example:
void example(void)
{
int ret;
SSL *ssl;
... ...
ret = SSL_has_pending(ssl);
}
3.17 int SSL_get_fd (const SSL * ssl)

Arguments:
ssl - SSL point
Return:
>= 0 : socket id
< 0 : a error catch
Description:
get the socket of the SSL
Example:
void example(void)
{
int ret;
SSL *ssl;

... ...
ret = SSL_get_fd(ssl);
}
3.18 int SSL_get_rfd (const SSL * ssl)

Arguments:
ssl - SSL point
Return:
>= 0 : socket id
< 0 : a error catch
Description:
get the read only socket of the SSL
Example:
void example(void)
{
int ret;
SSL *ssl;
... ...
ret = SSL_get_rfd(ssl);
}
3.19 int SSL_get_wfd (const SSL * ssl)

Arguments:
ssl - SSL point
Return:
>= 0 : socket id
< 0 : a error catch
Description:
get the write only socket of the SSL
Example:
void example(void)
{
int ret;
SSL *ssl;
... ...
ret = SSL_get_wfd(ssl);
}
3.20 int SSL_set_fd (SSL * ssl, int fd)

Arguments:

ssl - SSL point

fd - socket id
Return:
1 : OK
0 : failed
Description:
set socket to SSL
Example:
void example(void)
{
int ret;
SSL *ssl;
int socket;
... ...
ret = SSL_set_fd(ssl, socket);

}
3.21 int SSL_set_rfd (SSL * ssl, int fd)

Arguments:
ssl - SSL point

fd - socket id
Return:
1 : OK
0 : failed
Description:
set read only socket to SSL
Example:
void example(void)
{
int ret;
SSL *ssl;
int socket;
... ...
ret = SSL_set_rfd(ssl, socket);

}
3.22 int SSL_set_wfd (SSL * ssl, int fd)

Arguments:
ssl - SSL point

fd - socket id
Return:

1 : OK
0 : failed
Description:
set write only socket to SSL
Example:
void example(void)
{
int ret;
SSL *ssl;
int socket;
... ...
ret = SSL_set_wfd(ssl, socket);

}
3.23 int SSL_version (const SSL * ssl)

Arguments:
ssl - SSL point
Return:
SSL version
Description:
get SSL version
Example:
void example(void)
{
int version;
SSL *ssl;
... ...
version = SSL_version(ssl);
}
3.24 const char* SSL_get_version (const SSL * ssl)

Arguments:
ssl - SSL point
Return:
SSL version string
Description:
get the SSL current version string
Example:

void example(void)
{
char *version;
SSL *ssl;
... ...
version = SSL_get_version(ssl);
}
3.25 OSSL_HANDSHAKE_STATE SSL_get_state (const SSL * ssl)

Arguments:
ssl - SSL point
Return:
SSL state
Description:
get the SSL state
Example:
void example(void)
{
OSSL_HANDSHAKE_STATE state;
SSL *ssl;
... ...
state = SSL_get_state(ssl);
}
3.26 const char* SSL_alert_desc_string (int value)

Arguments:
value - SSL description
Return:
alert value string
Description:
get alert description string
Example:
void example(void)
{
int val;
char *str;
... ...
str = SSL_alert_desc_string(val);
}
3.27 const char* SSL_alert_desc_string_long (int value)

Arguments:
value - SSL description
Return:
alert value long string
Description:
get alert description long string
Example:
void example(void)
{
int val;
char *str;
... ...
str = SSL_alert_desc_string_long(val);
}
3.28 const char* SSL_alert_type_string (int value)

Arguments:
value - SSL type description
Return:
alert type string
Description:
get alert type string
Example:
void example(void)
{
int val;
char *str;
... ...
str = SSL_alert_type_string(val);
}
3.29 const char* SSL_alert_type_string_long (int value)

Arguments:
value - SSL type description
Return:
alert type long string
Description:

get alert type long string
Example:
void example(void)
{
int val;
char *str;
... ...
str = SSL_alert_type_string_long(val);
}
3.30 const char* SSL_rstate_string (SSL * ssl)

Arguments:
ssl - SSL point
Return:
state string
Description:
get the state string where SSL is reading
Example:
void example(void)
{
SSL *ssl;
char *str;
... ...
str = SSL_rstate_string(ssl);
}
3.31 const char* SSL_rstate_string_long (SSL * ssl)

Arguments:
ssl - SSL point
Return:
state long string
Description:
get the state long string where SSL is reading
Example:
void example(void)
{
SSL *ssl;
char *str;
... ...

str = SSL_rstate_string_long(ssl);
}
3.32 const char* SSL_state_string (const SSL * ssl)

Arguments:
ssl - SSL point
Return:
state string
Description:
get the state string
Example:
void example(void)
{
SSL *ssl;
const char *str;
... ...
str = SSL_state_string(ssl);
}
3.33 char* SSL_state_string_long (const SSL * ssl)

Arguments:
ssl - SSL point
Return:
state long string
Description:
get the state long string
Example:
void example(void)
{
SSL *ssl;
char *str;
... ...
str = SSL_state_string(ssl);
}
3.34 int SSL_get_error (const SSL * ssl, int ret_code)

Arguments:
ssl - SSL point

ret_code - SSL return code

Return:
SSL error number
Description:
get SSL error code
Example:
void example(void)
{
SSL *ssl;
int ret;
int err;
... ...
err = SSL_get_error(ssl, ret);

}
3.35 int SSL_want (const SSL * ssl)

Arguments:
ssl - SSL point
Return:
specifical statement
Description:
get the SSL specifical statement
Example:
void example(void)
{
SSL *ssl;
int state;
... ...
state = SSL_want(ssl);
}
3.36 int SSL_want_nothing (const SSL * ssl)

Arguments:
ssl - SSL point
Return:
0 : false
1 : true
Description:
check if SSL want nothing
Example:

void example(void)
{
SSL *ssl;
int ret;
... ...
ret = SSL_want(ssl);
}
3.37 int SSL_want_read (const SSL * ssl)

Arguments:
ssl - SSL point
Return:
0 : false
1 : true
Description:
check if SSL want to read
Example:
void example(void)
{
SSL *ssl;
int ret;
... ...
ret = SSL_want_read(ssl);
}
3.38 int SSL_want_write (const SSL * ssl)

Arguments:
ssl - SSL point
Return:
0 : false
1 : true
Description:
check if SSL want to write
Example:
void example(void)
{
SSL *ssl;
int ret;
... ...
ret = SSL_want_write(ssl);
}

Chapter 4. SSL X509 Certification and Private Key Function
4.1 X509 * d2i_X509 (X509 ** cert, const unsigned char * buffer, long len)
Arguments:
cert - a point pointed to X509 certification
buffer - a point pointed to the certification context memory point
length - certification bytes
Return:
X509 certification object point
Description:
load a character certification context into system context. If '*cert' is␣
,→pointed to the
certification, then load certification into it. Or create a new X509␣

,→certification object
Example:
void example(void)
{
X509 *new;
X509 *cert;
unsigned char *buffer;
long len;
... ...
new = d2i_X509(&cert, buffer, len);

}
4.2 int SSL_add_client_CA (SSL * ssl, X509 * x)

Arguments:
ssl - SSL point
x - CA certification point
Return:
1 : OK
0 : failed
Description:
add CA client certification into the SSL
Example:
void example(void)
{
int ret;
SSL *ssl;
X509 *new;
... ...
ret = SSL_add_client_CA(ssl, new);

}
4.3 int SSL_CTX_add_client_CA (SSL_CTX * ctx, X509 * x)

Arguments:
x - CA certification point
Return:
1 : OK
0 : failed
Description:
add CA client certification into the SSL context
Example:
void example(void)
{
int ret;
SSL_CTX *ctx;
X509 *new;
... ...
ret = SSL_add_clSSL_CTX_add_client_CAient_CA(ctx, new);

}
4.4 X509* SSL_get_certificate (const SSL * ssl)

Arguments:
ssl - SSL point
Return:
SSL certification point
Description:
get the SSL certification point
Example:
void example(void)
{
SSL *ssl;
X509 *cert;
... ...
cert = SSL_get_certificate(ssl);
}
4.5 long SSL_get_verify_result (const SSL * ssl)

Arguments:
ssl - SSL point
Return:
the result of verifying
Description:

get the verifying result of the SSL certification
Example:
void example(void)
{
SSL *ssl;
long ret;
... ...
ret = SSL_get_verify_result(ssl);
}
4.6 int SSL_CTX_use_certificate (SSL_CTX * ctx, X509 * x)

Arguments:
ctx - the SSL context point

pkey - certification object point
Return:
1 : OK
0 : failed
Description:
load the certification into the SSL_CTX or SSL object
Example:
void example(void)
{
int ret;
SSL_CTX *ctx
X509 *new;
... ...
ret = SSL_CTX_use_certificate(ctx, new);

}
4.7 int SSL_CTX_use_certificate_ASN1 (SSL_CTX * ctx, int len, const unsigned char * d)
Arguments:

len - certification length
d - data point
Return:
1 : OK
0 : failed
Description:
load the ASN1 certification into SSL context
Example:

void example(void)
{
int ret;
SSL_CTX *ctx;
const unsigned char *buf;
int len;
... ...
ret = SSL_CTX_use_certificate_ASN1(ctx, len, buf);

}
4.8 int SSL_CTX_use_PrivateKey (SSL_CTX * ctx, EVP_PKEY * pkey)

Arguments:

pkey - private key object point
Return:
1 : OK
0 : failed
Description:
load the private key into the context object
Example:
void example(void)
{
int ret;
SSL_CTX *ctx;
EVP_PKEY *pkey;
... ...
ret = SSL_CTX_use_PrivateKey(ctx, pkey);

}
4.9 int SSL_CTX_use_PrivateKey_ASN1 (int pk, SSL_CTX * ctx, const unsigned char * d, long len)
Arguments:

d - data point
len - private key length
Return:
1 : OK
0 : failed
Description:
load the ASN1 private key into SSL context
Example:
void example(void)
{


int ret;
int pk;
SSL_CTX *ctx;
long len;
... ...
ret = SSL_CTX_use_PrivateKey_ASN1(pk, ctx, buf, len);

}
4.10 int SSL_CTX_use_RSAPrivateKey_ASN1 (SSL_CTX * ctx, const unsigned char * d, long len)
Arguments:

d - data point
len - private key length
Return:
1 : OK
0 : failed
Description:
load the RSA ASN1 private key into SSL context
Example:
void example(void)
{
int ret;
SSL_CTX *ctx;
long len;
... ...
ret = SSL_CTX_use_RSAPrivateKey_ASN1(ctx, buf, len);

}
4.11 int SSL_use_certificate_ASN1 (SSL * ssl, int len, const unsigned char * d)
Arguments:
ssl - SSL point

len - data bytes
d - data point
Return:
1 : OK
0 : failed
Description:
load certification into the SSL
Example:

void example(void)
{
int ret;
SSL *ssl;
long len;
... ...
ret = SSL_use_certificate_ASN1(ssl, len, buf);

}
4.12 X509* SSL_get_peer_certificate (const SSL * ssl)

Arguments:
ssl - SSL point
Return:
peer certification
Description:
get peer certification
Example:
void example(void)
{
SSL *ssl;
X509 *peer;
... ...
peer = SSL_get_peer_certificate(ssl);
}
2.4.5 ESP HTTP Client
Overview
esp_http_client provides an API for making HTTP/S requests from ESP-IDF programs. The steps to use this
API for an HTTP request are:
• esp_http_client_init(): To use the HTTP client, the first thing we must do is create an
esp_http_client by pass into this function with the esp_http_client_config_t configurations.
Which configuration values we do not define, the library will use default.
• esp_http_client_perform(): The esp_http_client argument created from the init function is
needed. This function performs all operations of the esp_http_client, from opening the connection, sending
data, downloading data and closing the connection if necessary. All related events will be invoked in the
event_handle (defined by esp_http_client_config_t). This function performs its job and blocks the
current task until it s done
• esp_http_client_cleanup(): After completing our esp_http_client s task, this is the last function
to be called. It will close the connection (if any) and free up all the memory allocated to the HTTP client

Application Example
esp_err_t _http_event_handle(esp_http_client_event_t *evt)

{
switch(evt->event_id) {
case HTTP_EVENT_ERROR:
ESP_LOGI(TAG, "HTTP_EVENT_ERROR");
break;
case HTTP_EVENT_ON_CONNECTED:
ESP_LOGI(TAG, "HTTP_EVENT_ON_CONNECTED");
break;
case HTTP_EVENT_HEADER_SENT:
ESP_LOGI(TAG, "HTTP_EVENT_HEADER_SENT");
break;
case HTTP_EVENT_ON_HEADER:
ESP_LOGI(TAG, "HTTP_EVENT_ON_HEADER");
printf("%.*s", evt->data_len, (char*)evt->data);
break;
case HTTP_EVENT_ON_DATA:
ESP_LOGI(TAG, "HTTP_EVENT_ON_DATA, len=%d", evt->data_len);
if (!esp_http_client_is_chunked_response(evt->client)) {
printf("%.*s", evt->data_len, (char*)evt->data);
}
break;
case HTTP_EVENT_ON_FINISH:
ESP_LOGI(TAG, "HTTP_EVENT_ON_FINISH");
break;
case HTTP_EVENT_DISCONNECTED:
ESP_LOGI(TAG, "HTTP_EVENT_DISCONNECTED");
break;
}
return ESP_OK;
}
esp_http_client_config_t config = {
.url = "http://httpbin.org/redirect/2",
.event_handler = _http_event_handle,
};
esp_http_client_handle_t client = esp_http_client_init(&config);
esp_err_t err = esp_http_client_perform(client);
if (err == ESP_OK) {
ESP_LOGI(TAG, "Status = %d, content_length = %d",
esp_http_client_get_status_code(client),
esp_http_client_get_content_length(client));
}
esp_http_client_cleanup(client);
Persistent Connections
Persistent connections means that the HTTP client can re-use the same connection for several transfers. If the server
does not request to close the connection with the Connection: close header, the new transfer with sample ip
address, port, and protocol.
To allow the HTTP client to take full advantage of persistent connections, you should do as many of your file transfers
as possible using the same handle.
Persistent Connections example

esp_err_t err;
.url = "http://httpbin.org/get",
};
// first request
err = esp_http_client_perform(client);
// second request
esp_http_client_set_url(client, "http://httpbin.org/anything")
esp_http_client_set_method(client, HTTP_METHOD_DELETE);
esp_http_client_set_header(client, "HeaderKey", "HeaderValue");
err = esp_http_client_perform(client);
HTTPS
The HTTP client supports SSL connections using mbedtls, with the url configuration starting with https scheme
(or transport_type = HTTP_TRANSPORT_OVER_SSL). HTTPS support can be configured via CON-
FIG_ESP_HTTP_CLIENT_ENABLE_HTTPS (enabled by default).
Note: By providing information using HTTPS, the library will use the SSL transport type to connect to the server.
If you want to verify server, then need to provide additional certificate in PEM format, and provide to cert_pem
in esp_http_client_config_t
HTTPS example
static void https()
{
.url = "https://www.howsmyssl.com",
.cert_pem = howsmyssl_com_root_cert_pem_start,
};
esp_err_t err = esp_http_client_perform(client);
ESP_LOGI(TAG, "Status = %d, content_length = %d",
esp_http_client_get_status_code(client),
esp_http_client_get_content_length(client));
}
}
HTTP Stream
Some applications need to open the connection and control the reading of the data in an active manner. the HTTP
client supports some functions to make this easier, of course, once you use these functions you should not use
the esp_http_client_perform() function with that handle, and esp_http_client_init() alway
to called first to get the handle. Perform that functions in the order below:
• esp_http_client_init(): to create and handle
• esp_http_client_set_* or esp_http_client_delete_*: to modify the http connection infor-
mation (optional)
• esp_http_client_open(): Open the http connection with write_len parameter, write_len=0
if we only need read

• esp_http_client_write(): Upload data, max length equal to write_len of

esp_http_client_open() function. We may not need to call it if write_len=0
• esp_http_client_fetch_headers(): After sending the headers and write data (if any) to the server,
this function will read the HTTP Server response headers. Calling this function will return the content-
length from the Server, and we can call esp_http_client_get_status_code() for the HTTP
status of the connection.
• esp_http_client_read(): Now, we can read the HTTP stream by this function.
• esp_http_client_close(): We should the connection after finish
• esp_http_client_cleanup(): And release the resources
Perform HTTP request as Stream reader Check the example function

http_perform_as_stream_reader at protocols/esp_http_client.
HTTP Authentication
The HTTP client supports both Basic and Digest Authentication. By providing usernames and passwords in url or in
the username, password of config entry. And with auth_type = HTTP_AUTH_TYPE_BASIC, the HTTP
client takes only 1 perform to pass the authentication process. If auth_type = HTTP_AUTH_TYPE_NONE,
but there are username and password in the configuration, the HTTP client takes 2 performs. The first time it
connects to the server and receives the UNAUTHORIZED header. Based on this information, it will know which
authentication method to choose, and perform it on the second.
Config authentication example with URI

.url = "http://user:[email protected]/basic-auth/user/passwd",
.auth_type = HTTP_AUTH_TYPE_BASIC,
};
Config authentication example with username, password entry

.url = "http://httpbin.org/basic-auth/user/passwd",
.username = "user",
.password = "passwd",
.auth_type = HTTP_AUTH_TYPE_BASIC,
};
HTTP Client example: protocols/esp_http_client.
API Reference
Header File
• components/esp_http_client/include/esp_http_client.h
Functions
esp_http_client_handle_t esp_http_client_init(const esp_http_client_config_t *config)
Start a HTTP session This function must be the first function to call, and it returns a esp_http_client_handle_t
that you must use as input to other functions in the interface. This call MUST have a corresponding call to
esp_http_client_cleanup when the operation is complete.
Return
• esp_http_client_handle_t
• NULL if any errors
Parameters
• [in] config: The configurations, see http_client_config_t

esp_err_t esp_http_client_perform(esp_http_client_handle_t client)

Invoke this function after esp_http_client_init and all the options calls are made, and will perform
the transfer as described in the options. It must be called with the same esp_http_client_handle_t as input as
the esp_http_client_init call returned. esp_http_client_perform performs the entire request in either blocking
or non-blocking manner. By default, the API performs request in a blocking manner and returns when done,
or if it failed, and in non-blocking manner, it returns if EAGAIN/EWOULDBLOCK or EINPROGRESS is
encountered, or if it failed. And in case of non-blocking request, the user may call this API multiple times
unless request & response is complete or there is a failure. To enable non-blocking esp_http_client_perform(),
is_async member of esp_http_client_config_t must be set while making a call to esp_http_client_init() API.
You can do any amount of calls to esp_http_client_perform while using the same esp_http_client_handle_t.
The underlying connection may be kept open if the server allows it. If you intend to transfer more than one
file, you are even encouraged to do so. esp_http_client will then attempt to re-use the same connection for
the following transfers, thus making the operations faster, less CPU intense and using less network resources.
Just note that you will have to use esp_http_client_set_** between the invokes to set options for the
following esp_http_client_perform.
Note You must never call this function simultaneously from two places using the same client handle.
Let the function return first before invoking it another time. If you want parallel transfers, you
must use several esp_http_client_handle_t. This function include esp_http_client_open
-> esp_http_client_write -> esp_http_client_fetch_headers ->
esp_http_client_read (and option) esp_http_client_close.
Return
• ESP_OK on successful
• ESP_FAIL on error
Parameters
• client: The esp_http_client handle
esp_err_t esp_http_client_set_url(esp_http_client_handle_t client, const char *url)
Set URL for client, when performing this behavior, the options in the URL will replace the old ones.
Return
• ESP_OK
• ESP_FAIL
Parameters
• [in] client: The esp_http_client handle
• [in] url: The url
esp_err_t esp_http_client_set_post_field(esp_http_client_handle_t client, const char *data,
int len)
Set post data, this function must be called before esp_http_client_perform. Note: The data param-
eter passed to this function is a pointer and this function will not copy the data.
Return
• ESP_OK
• ESP_FAIL
Parameters
• [in] data: post data pointer
• [in] len: post length
int esp_http_client_get_post_field(esp_http_client_handle_t client, char **data)
Get current post field information.
Return Size of post data
Parameters
• [in] client: The client
• [out] data: Point to post data pointer
esp_err_t esp_http_client_set_header(esp_http_client_handle_t client, const char *key, const
char *value)
Set http request header, this function must be called after esp_http_client_init and before any perform function.
Return

• ESP_OK
• ESP_FAIL
Parameters
• [in] key: The header key
• [in] value: The header value
esp_err_t esp_http_client_get_header(esp_http_client_handle_t client, const char *key, char
**value)
Get http request header. The value parameter will be set to NULL if there is no header which is same as the
key specified, otherwise the address of header value will be assigned to value parameter. This function must
be called after esp_http_client_init.
Return
• ESP_OK
• ESP_FAIL
Parameters
• [in] key: The header key
• [out] value: The header value
esp_err_t esp_http_client_get_username(esp_http_client_handle_t client, char **value)
Get http request username. The address of username buffer will be assigned to value parameter. This function
must be called after esp_http_client_init.
Return
• ESP_OK
• ESP_ERR_INVALID_ARG
Parameters
• [out] value: The username value
esp_err_t esp_http_client_set_username(esp_http_client_handle_t client, const char
*username)
Set http request username. The value of username parameter will be assigned to username buffer. If the
username parameter is NULL then username buffer will be freed.
Return
• ESP_OK
Parameters
• [in] username: The username value
esp_err_t esp_http_client_get_password(esp_http_client_handle_t client, char **value)
Get http request password. The address of password buffer will be assigned to value parameter. This function
must be called after esp_http_client_init.
Return
• ESP_OK
Parameters
• [out] value: The password value
esp_err_t esp_http_client_set_password(esp_http_client_handle_t client, const char
*password)
Set http request password. The value of password parameter will be assigned to password buffer. If the
password parameter is NULL then password buffer will be freed.
Return
• ESP_OK
Parameters


• [in] password: The password value
esp_err_t esp_http_client_set_authtype(esp_http_client_handle_t client,
esp_http_client_auth_type_t auth_type)
Set http request auth_type.
Return
• ESP_OK
Parameters
• [in] auth_type: The esp_http_client auth type
esp_err_t esp_http_client_set_method(esp_http_client_handle_t client, esp_http_client_method_t
method)
Set http request method.
Return
• ESP_OK
Parameters
• [in] method: The method
esp_err_t esp_http_client_set_timeout_ms(esp_http_client_handle_t client, int timeout_ms)
Set http request timeout.
Return
• ESP_OK
Parameters
• [in] timeout_ms: The timeout value
esp_err_t esp_http_client_delete_header(esp_http_client_handle_t client, const char *key)
Delete http request header.
Return
• ESP_OK
• ESP_FAIL
Parameters
• [in] key: The key
esp_err_t esp_http_client_open(esp_http_client_handle_t client, int write_len)
This function will be open the connection, write all header strings and return.
Return
• ESP_OK
• ESP_FAIL
Parameters
• [in] write_len: HTTP Content length need to write to the server
int esp_http_client_write(esp_http_client_handle_t client, const char *buffer, int len)
This function will write data to the HTTP connection previously opened by esp_http_client_open()
Return
• (-1) if any errors
• Length of data written
Parameters
• buffer: The buffer

• [in] len: This value must not be larger than the write_len parameter provided to
esp_http_client_open()
int64_t esp_http_client_fetch_headers(esp_http_client_handle_t client)
This function need to call after esp_http_client_open, it will read from http stream, process all receive headers.
Return
• (0) if stream doesn t contain content-length header, or chunked encoding (checked by
esp_http_client_is_chunked response)
• (-1: ESP_FAIL) if any errors
• Download data length defined by content-length header
Parameters
bool esp_http_client_is_chunked_response(esp_http_client_handle_t client)
Check response data is chunked.
Return true or false
Parameters
int esp_http_client_read(esp_http_client_handle_t client, char *buffer, int len)
Read data from http stream.
Return
• Length of data was read
Parameters
• [in] len: The length
int esp_http_client_get_status_code(esp_http_client_handle_t client)
Get http response status code, the valid value if this function invoke after esp_http_client_perform
Return Status code
Parameters
int64_t esp_http_client_get_content_length(esp_http_client_handle_t client)
Get http response content length (from header Content-Length) the valid value if this function invoke after
esp_http_client_perform
Return
• (-1) Chunked transfer
• Content-Length value as bytes
Parameters
esp_err_t esp_http_client_close(esp_http_client_handle_t client)
Close http connection, still kept all http request resources.
Return
• ESP_OK
• ESP_FAIL
Parameters
esp_err_t esp_http_client_cleanup(esp_http_client_handle_t client)
This function must be the last function to call for an session. It is the opposite of the esp_http_client_init
function and must be called with the same handle as input that a esp_http_client_init call returned. This might
close all connections this handle has used and possibly has kept open until now. Don t call this function if
you intend to transfer more files, re-using handles is a key to good performance with esp_http_client.
Return

• ESP_OK
• ESP_FAIL
Parameters
esp_http_client_transport_t esp_http_client_get_transport_type(esp_http_client_handle_t
client)
Get transport type.
Return
• HTTP_TRANSPORT_UNKNOWN
• HTTP_TRANSPORT_OVER_TCP
• HTTP_TRANSPORT_OVER_SSL
Parameters
esp_err_t esp_http_client_set_redirection(esp_http_client_handle_t client)
Set redirection URL. When received the 30x code from the server, the client stores the redirect URL provided
by the server. This function will set the current URL to redirect to enable client to execute the redirection
request.
Return
• ESP_OK
• ESP_FAIL
Parameters
void esp_http_client_add_auth(esp_http_client_handle_t client)
On receiving HTTP Status code 401, this API can be invoked to add authorization information.
Note There is a possibility of receiving body message with redirection status codes, thus make sure to flush
off body data after calling this API.
Parameters
bool esp_http_client_is_complete_data_received(esp_http_client_handle_t client)
Checks if entire data in the response has been read without any error.
Return
• true
• false
Parameters
int esp_http_client_read_response(esp_http_client_handle_t client, char *buffer, int len)
Helper API to read larger data chunks This is a helper API which internally calls esp_http_client_read
multiple times till the end of data is reached or till the buffer gets full.
Return
• Length of data was read
Parameters
• [in] len: The buffer length
esp_err_t esp_http_client_flush_response(esp_http_client_handle_t client, int *len)
Process all remaining response data This uses an internal buffer to repeatedly receive, parse, and discard re-
sponse data until complete data is processed. As no additional user-supplied buffer is required, this may be
preferrable to esp_http_client_read_response in situations where the content of the response may
be ignored.
Return
• ESP_OK If successful, len will have discarded length
• ESP_FAIL If failed to read response

• ESP_ERR_INVALID_ARG If the client is NULL

Parameters
• len: Length of data discarded
esp_err_t esp_http_client_get_url(esp_http_client_handle_t client, char *url, const int len)
Get URL from client.
Return
• ESP_OK
• ESP_FAIL
Parameters
• [inout] url: The buffer to store URL
• [in] len: The buffer length
esp_err_t esp_http_client_get_chunk_length(esp_http_client_handle_t client, int *len)
Get Chunk-Length from client.
Return
• ESP_OK If successful, len will have length of current chunk
• ESP_FAIL If the server is not a chunked server
• ESP_ERR_INVALID_ARG If the client or len are NULL
Parameters
• [out] len: Variable to store length
Structures
struct esp_http_client_event
HTTP Client events data.
Public Members
esp_http_client_event_id_t event_id
event_id, to know the cause of the event
esp_http_client_handle_t client
esp_http_client_handle_t context
void *data
data of the event
int data_len
data length of data
void *user_data
user_data context, from esp_http_client_config_t user_data
char *header_key
For HTTP_EVENT_ON_HEADER event_id, it s store current http header key
char *header_value
For HTTP_EVENT_ON_HEADER event_id, it s store current http header value
struct esp_http_client_config_t
HTTP configuration.
Public Members
const char *url

HTTP URL, the information on the URL is most important, it overrides the other fields below, if any

const char *host

Domain or IP as string
int port
Port to connect, default depend on esp_http_client_transport_t (80 or 443)
Using for Http authentication
Using for Http authentication
esp_http_client_auth_type_t auth_type
Http authentication type, see esp_http_client_auth_type_t
const char *path
HTTP Path, if not set, default is /
const char *query
HTTP query
SSL server certification, PEM format as string, if the client requires to verify server
size_t cert_len
const char *client_cert_pem
SSL client certification, PEM format as string, if the server requires to verify client
Length of the buffer pointed to by client_cert_pem. May be 0 for null-terminated pem
const char *client_key_pem
SSL client key, PEM format as string, if the server requires to verify client
const char *client_key_password
size_t client_key_password_len
String length of the password pointed to by client_key_password
const char *user_agent
The User Agent string to send with HTTP requests
esp_http_client_method_t method
HTTP Method
int timeout_ms
Network timeout in milliseconds
bool disable_auto_redirect
Disable HTTP automatic redirects
int max_redirection_count
Max number of redirections on receiving HTTP redirect status code, using default value if zero
int max_authorization_retries
Max connection retries on receiving HTTP unauthorized status code, using default value if zero. Disables
authorization retry if -1
http_event_handle_cb event_handler
HTTP Event Handle
esp_http_client_transport_t transport_type
HTTP transport type, see esp_http_client_transport_t

int buffer_size
HTTP receive buffer size
int buffer_size_tx
HTTP transmit buffer size
void *user_data
HTTP user_data context
bool is_async
Set asynchronous mode, only supported with HTTPS for now
Function pointer to esp_crt_bundle_attach. Enables the use of certification bundle for server verification,
must be enabled in menuconfig
int keep_alive_idle
Keep-alive idle time. Default is 5 (second)
Keep-alive interval time. Default is 5 (second)
Keep-alive packet retry send count. Default is 3 counts
Macros
DEFAULT_HTTP_BUF_SIZE
ESP_ERR_HTTP_BASE
Starting number of HTTP error codes
ESP_ERR_HTTP_MAX_REDIRECT
The error exceeds the number of HTTP redirects
ESP_ERR_HTTP_CONNECT
Error open the HTTP connection
ESP_ERR_HTTP_WRITE_DATA
Error write HTTP data
ESP_ERR_HTTP_FETCH_HEADER
Error read HTTP header from server
ESP_ERR_HTTP_INVALID_TRANSPORT
There are no transport support for the input scheme
ESP_ERR_HTTP_CONNECTING
HTTP connection hasn t been established yet
ESP_ERR_HTTP_EAGAIN
Mapping of errno EAGAIN to esp_err_t
ESP_ERR_HTTP_CONNECTION_CLOSED
Read FIN from peer and the connection closed

Type Definitions
typedef struct esp_http_client *esp_http_client_handle_t
typedef struct esp_http_client_event *esp_http_client_event_handle_t
typedef struct esp_http_client_event esp_http_client_event_t
HTTP Client events data.
typedef esp_err_t (*http_event_handle_cb)(esp_http_client_event_t *evt)
Enumerations
enum esp_http_client_event_id_t
HTTP Client events id.
Values:
HTTP_EVENT_ERROR = 0
This event occurs when there are any errors during execution
HTTP_EVENT_ON_CONNECTED
Once the HTTP has been connected to the server, no data exchange has been performed
HTTP_EVENT_HEADERS_SENT
After sending all the headers to the server
HTTP_EVENT_HEADER_SENT = HTTP_EVENT_HEADERS_SENT
This header has been kept for backward compatability and will be deprecated in future versions esp-idf
HTTP_EVENT_ON_HEADER
Occurs when receiving each header sent from the server
HTTP_EVENT_ON_DATA
Occurs when receiving data from the server, possibly multiple portions of the packet
HTTP_EVENT_ON_FINISH
Occurs when finish a HTTP session
HTTP_EVENT_DISCONNECTED
The connection has been disconnected
enum esp_http_client_transport_t
HTTP Client transport.
Values:
HTTP_TRANSPORT_UNKNOWN = 0x0
Unknown
HTTP_TRANSPORT_OVER_TCP
Transport over tcp
HTTP_TRANSPORT_OVER_SSL
Transport over ssl
enum esp_http_client_method_t
HTTP method.
Values:
HTTP_METHOD_GET = 0
HTTP GET Method
HTTP_METHOD_POST
HTTP POST Method
HTTP_METHOD_PUT
HTTP PUT Method
HTTP_METHOD_PATCH
HTTP PATCH Method

HTTP_METHOD_DELETE
HTTP DELETE Method
HTTP_METHOD_HEAD
HTTP HEAD Method
HTTP_METHOD_NOTIFY
HTTP NOTIFY Method
HTTP_METHOD_SUBSCRIBE
HTTP SUBSCRIBE Method
HTTP_METHOD_UNSUBSCRIBE
HTTP UNSUBSCRIBE Method
HTTP_METHOD_OPTIONS
HTTP OPTIONS Method
HTTP_METHOD_COPY
HTTP COPY Method
HTTP_METHOD_MOVE
HTTP MOVE Method
HTTP_METHOD_LOCK
HTTP LOCK Method
HTTP_METHOD_UNLOCK
HTTP UNLOCK Method
HTTP_METHOD_PROPFIND
HTTP PROPFIND Method
HTTP_METHOD_PROPPATCH
HTTP PROPPATCH Method
HTTP_METHOD_MKCOL
HTTP MKCOL Method
HTTP_METHOD_MAX
enum esp_http_client_auth_type_t
HTTP Authentication type.
Values:
HTTP_AUTH_TYPE_NONE = 0
No authention
HTTP_AUTH_TYPE_BASIC
HTTP Basic authentication
HTTP_AUTH_TYPE_DIGEST
HTTP Disgest authentication
enum HttpStatus_Code
Enum for the HTTP status codes.
Values:
HttpStatus_Ok = 200
HttpStatus_MultipleChoices = 300
HttpStatus_MovedPermanently = 301
HttpStatus_Found = 302
HttpStatus_TemporaryRedirect = 307
HttpStatus_BadRequest = 400

HttpStatus_Unauthorized = 401
HttpStatus_Forbidden = 403
HttpStatus_NotFound = 404
HttpStatus_InternalError = 500
2.4.6 HTTP Server
Overview
The HTTP Server component provides an ability for running a lightweight web server on ESP32. Following are
detailed steps to use the API exposed by HTTP Server:
• httpd_start(): Creates an instance of HTTP server, allocate memory/resources for it depending upon
the specified configuration and outputs a handle to the server instance. The server has both, a listening socket
(TCP) for HTTP traffic, and a control socket (UDP) for control signals, which are selected in a round robin
fashion in the server task loop. The task priority and stack size are configurable during server instance creation
by passing httpd_config_t structure to httpd_start(). TCP traffic is parsed as HTTP requests and, depending
on the requested URI, user registered handlers are invoked which are supposed to send back HTTP response
packets.
• httpd_stop(): This stops the server with the provided handle and frees up any associated mem-
ory/resources. This is a blocking function that first signals a halt to the server task and then waits for the
task to terminate. While stopping, the task will close all open connections, remove registered URI handlers
and reset all session context data to empty.
• httpd_register_uri_handler(): A URI handler is registered by passing object of type
httpd_uri_t structure which has members including uri name, method type (eg. HTTPD_GET/
HTTPD_POST/HTTPD_PUT etc.), function pointer of type esp_err_t *handler (httpd_req_t
*req) and user_ctx pointer to user context data.
Application Example
/* Our URI handler function to be called during GET /uri request */

esp_err_t get_handler(httpd_req_t *req)
{
/* Send a simple response */
const char resp[] = "URI GET Response";
httpd_resp_send(req, resp, HTTPD_RESP_USE_STRLEN);
return ESP_OK;
}
/* Our URI handler function to be called during POST /uri request */

esp_err_t post_handler(httpd_req_t *req)
{
/* Destination buffer for content of HTTP POST request.
* httpd_req_recv() accepts char* only, but content could
* as well be any binary data (needs type casting).
* In case of string data, null termination will be absent, and
* content length would give length of string */
char content[100];
/* Truncate if content length larger than the buffer */

size_t recv_size = MIN(req->content_len, sizeof(content));
int ret = httpd_req_recv(req, content, recv_size);

if (ret <= 0) { /* 0 return value indicates connection closed */
/* Check if timeout occurred */
if (ret == HTTPD_SOCK_ERR_TIMEOUT) {


/* In case of timeout one can choose to retry calling
* httpd_req_recv(), but to keep it simple, here we
* respond with an HTTP 408 (Request Timeout) error */
httpd_resp_send_408(req);
}
/* In case of error, returning ESP_FAIL will
* ensure that the underlying socket is closed */
return ESP_FAIL;
}
/* Send a simple response */

const char resp[] = "URI POST Response";
httpd_resp_send(req, resp, HTTPD_RESP_USE_STRLEN);
return ESP_OK;
}
/* URI handler structure for GET /uri */

httpd_uri_t uri_get = {
.uri = "/uri",
.method = HTTP_GET,
.handler = get_handler,
.user_ctx = NULL
};
/* URI handler structure for POST /uri */

httpd_uri_t uri_post = {
.uri = "/uri",
.method = HTTP_POST,
.handler = post_handler,
.user_ctx = NULL
};
/* Function for starting the webserver */

httpd_handle_t start_webserver(void)
{
/* Generate default configuration */
httpd_config_t config = HTTPD_DEFAULT_CONFIG();
/* Empty handle to esp_http_server */

httpd_handle_t server = NULL;
/* Start the httpd server */

if (httpd_start(&server, &config) == ESP_OK) {
/* Register URI handlers */
httpd_register_uri_handler(server, &uri_get);
httpd_register_uri_handler(server, &uri_post);
}
/* If server failed to start, handle will be NULL */
return server;
}
/* Function for stopping the webserver */

void stop_webserver(httpd_handle_t server)
{
if (server) {
/* Stop the httpd server */
httpd_stop(server);
}
}

Simple HTTP server example Check HTTP server example under protocols/http_server/simple where handling
of arbitrary content lengths, reading request headers and URL query parameters, and setting response headers is
demonstrated.
Persistent Connections
HTTP server features persistent connections, allowing for the re-use of the same connection (session) for several
transfers, all the while maintaining context specific data for the session. Context data may be allocated dynamically by
the handler in which case a custom function may need to be specified for freeing this data when the connection/session
is closed.
Persistent Connections Example

/* Custom function to free context */
void free_ctx_func(void *ctx)
{
/* Could be something other than free */
free(ctx);
}
esp_err_t adder_post_handler(httpd_req_t *req)

{
/* Create session's context if not already available */
if (! req->sess_ctx) {
req->sess_ctx = malloc(sizeof(ANY_DATA_TYPE)); /*!< Pointer to context␣
,→data */
req->free_ctx = free_ctx_func; /*!< Function to free␣

,→context data */
/* Access context data */

ANY_DATA_TYPE *ctx_data = (ANY_DATA_TYPE *)req->sess_ctx;
/* Respond */
...............
...............
...............
return ESP_OK;
}
Check the example under protocols/http_server/persistent_sockets.
Websocket server
HTTP server provides a simple websocket support if the feature is enabled in menuconfig, please see CON-
FIG_HTTPD_WS_SUPPORT. Please check the example under protocols/http_server/ws_echo_server
API Reference
Header File
• components/esp_http_server/include/esp_http_server.h
Functions
esp_err_t httpd_register_uri_handler(httpd_handle_t handle, const httpd_uri_t *uri_handler)
Registers a URI handler.
Example usage:

esp_err_t my_uri_handler(httpd_req_t* req)

{
// Recv , Process and Send
....
....
....
// Fail condition
if (....) {
// Return fail to close session //
return ESP_FAIL;
}
// On success
return ESP_OK;
}
// URI handler structure

httpd_uri_t my_uri {
.uri = "/my_uri/path/xyz",
.method = HTTPD_GET,
.handler = my_uri_handler,
.user_ctx = NULL
};
// Register handler
if (httpd_register_uri_handler(server_handle, &my_uri) != ESP_OK) {
// If failed to register handler
....
}
Note URI handlers can be registered in real time as long as the server handle is valid.
Return
•ESP_OK : On successfully registering the handler
•ESP_ERR_INVALID_ARG : Null arguments
•ESP_ERR_HTTPD_HANDLERS_FULL : If no slots left for new handler
•ESP_ERR_HTTPD_HANDLER_EXISTS : If handler with same URI and method is already reg-
istered
Parameters
• [in] handle: handle to HTTPD server instance
• [in] uri_handler: pointer to handler that needs to be registered
esp_err_t httpd_unregister_uri_handler(httpd_handle_t handle, const char *uri,
httpd_method_t method)
Unregister a URI handler.
Return
• ESP_OK : On successfully deregistering the handler
• ESP_ERR_INVALID_ARG : Null arguments
• ESP_ERR_NOT_FOUND : Handler with specified URI and method not found
Parameters
• [in] uri: URI string
• [in] method: HTTP method
esp_err_t httpd_unregister_uri(httpd_handle_t handle, const char *uri)
Unregister all URI handlers with the specified uri string.
Return
• ESP_OK : On successfully deregistering all such handlers
• ESP_ERR_NOT_FOUND : No handler registered with specified uri string

Parameters
• [in] uri: uri string specifying all handlers that need to be deregisterd
esp_err_t httpd_sess_set_recv_override(httpd_handle_t hd, int sockfd, httpd_recv_func_t
recv_func)
Override web server s receive function (by session FD)
This function overrides the web server s receive function. This same function is used to read HTTP request
packets.
Note This API is supposed to be called either from the context of
• an http session APIs where sockfd is a valid parameter
• a URI handler where sockfd is obtained using httpd_req_to_sockfd()
Return
• ESP_OK : On successfully registering override
Parameters
• [in] hd: HTTPD instance handle
• [in] sockfd: Session socket FD
• [in] recv_func: The receive function to be set for this session
esp_err_t httpd_sess_set_send_override(httpd_handle_t hd, int sockfd, httpd_send_func_t
send_func)
Override web server s send function (by session FD)
This function overrides the web server s send function. This same function is used to send out any response
to any HTTP request.
Return
Parameters
• [in] send_func: The send function to be set for this session
esp_err_t httpd_sess_set_pending_override(httpd_handle_t hd, int sockfd,
httpd_pending_func_t pending_func)
Override web server s pending function (by session FD)
This function overrides the web server s pending function. This function is used to test for pending bytes in
a socket.
Return
Parameters
• [in] pending_func: The receive function to be set for this session
int httpd_req_to_sockfd(httpd_req_t *r)
Get the Socket Descriptor from the HTTP request.
This API will return the socket descriptor of the session for which URI handler was executed on reception of
HTTP request. This is useful when user wants to call functions that require session socket fd, from within a
URI handler, ie. : httpd_sess_get_ctx(), httpd_sess_trigger_close(), httpd_sess_update_lru_counter().

Note This API is supposed to be called only from the context of a URI handler where httpd_req_t* request
pointer is valid.
Return
• Socket descriptor : The socket descriptor for this request
• -1 : Invalid/NULL request pointer
Parameters
• [in] r: The request whose socket descriptor should be found
int httpd_req_recv(httpd_req_t *r, char *buf, size_t buf_len)
API to read content data from the HTTP request.
This API will read HTTP content data from the HTTP request into provided buffer. Use content_len provided
in httpd_req_t structure to know the length of data to be fetched. If content_len is too large for the buffer then
user may have to make multiple calls to this function, each time fetching buf_len number of bytes, while
the pointer to content data is incremented internally by the same number.
Note
• This API is supposed to be called only from the context of a URI handler where httpd_req_t* request
pointer is valid.
• If an error is returned, the URI handler must further return an error. This will ensure that the
erroneous socket is closed and cleaned up by the web server.
• Presently Chunked Encoding is not supported
Return
• Bytes : Number of bytes read into the buffer successfully
• 0 : Buffer length parameter is zero / connection closed by peer
• HTTPD_SOCK_ERR_INVALID : Invalid arguments
• HTTPD_SOCK_ERR_TIMEOUT : Timeout/interrupted while calling socket recv()
• HTTPD_SOCK_ERR_FAIL : Unrecoverable error while calling socket recv()
Parameters
• [in] r: The request being responded to
• [in] buf: Pointer to a buffer that the data will be read into
• [in] buf_len: Length of the buffer
size_t httpd_req_get_hdr_value_len(httpd_req_t *r, const char *field)
Search for a field in request headers and return the string length of it s value.
Note
pointer is valid.
• Once httpd_resp_send() API is called all request headers are purged, so request headers need be
copied into separate buffers if they are required later.
Return
• Length : If field is found in the request URL
• Zero : Field not found / Invalid request / Null arguments
Parameters
• [in] field: The header field to be searched in the request
esp_err_t httpd_req_get_hdr_value_str(httpd_req_t *r, const char *field, char *val, size_t
val_size)
Get the value string of a field from the request headers.
Note
pointer is valid.
• Once httpd_resp_send() API is called all request headers are purged, so request headers need be
copied into separate buffers if they are required later.
• If output size is greater than input, then the value is truncated, accompanied by truncation error as
return value.
• Use httpd_req_get_hdr_value_len() to know the right buffer length
Return
• ESP_OK : Field found in the request header and value string copied

• ESP_ERR_NOT_FOUND : Key not found

• ESP_ERR_HTTPD_INVALID_REQ : Invalid HTTP request pointer
• ESP_ERR_HTTPD_RESULT_TRUNC : Value string truncated
Parameters
• [in] field: The field to be searched in the header
• [out] val: Pointer to the buffer into which the value will be copied if the field is found
• [in] val_size: Size of the user buffer val
size_t httpd_req_get_url_query_len(httpd_req_t *r)
Get Query string length from the request URL.
Note This API is supposed to be called only from the context of a URI handler where httpd_req_t* request
pointer is valid
Return
• Length : Query is found in the request URL
• Zero : Query not found / Null arguments / Invalid request
Parameters
esp_err_t httpd_req_get_url_query_str(httpd_req_t *r, char *buf, size_t buf_len)
Get Query string from the request URL.
Note
• Presently, the user can fetch the full URL query string, but decoding will have to be performed by
the user. Request headers can be read using httpd_req_get_hdr_value_str() to know the Content-
Type (eg. Content-Type: application/x-www-form-urlencoded) and then the appropriate decoding
algorithm needs to be applied.
pointer is valid
• If output size is greater than input, then the value is truncated, accompanied by truncation error as
return value
• Prior to calling this function, one can use httpd_req_get_url_query_len() to know the query string
length beforehand and hence allocate the buffer of right size (usually query string length + 1 for null
termination) for storing the query string
Return
• ESP_OK : Query is found in the request URL and copied to buffer
• ESP_ERR_NOT_FOUND : Query not found
• ESP_ERR_HTTPD_INVALID_REQ : Invalid HTTP request pointer
• ESP_ERR_HTTPD_RESULT_TRUNC : Query string truncated
Parameters
• [out] buf: Pointer to the buffer into which the query string will be copied (if found)
• [in] buf_len: Length of output buffer
esp_err_t httpd_query_key_value(const char *qry, const char *key, char *val, size_t val_size)
Helper function to get a URL query tag from a query string of the type param1=val1&param2=val2.
Note
• The components of URL query string (keys and values) are not URLdecoded. The user must check
for Content-Type field in the request headers and then depending upon the specified encoding
(URLencoded or otherwise) apply the appropriate decoding algorithm.
• If actual value size is greater than val_size, then the value is truncated, accompanied by truncation
error as return value.
Return
• ESP_OK : Key is found in the URL query string and copied to buffer

Parameters
• [in] qry: Pointer to query string
• [in] key: The key to be searched in the query string
• [out] val: Pointer to the buffer into which the value will be copied if the key is found
• [in] val_size: Size of the user buffer val
esp_err_t httpd_req_get_cookie_val(httpd_req_t *req, const char *cookie_name, char *val,
size_t *val_size)
Get the value string of a cookie value from the Cookie request headers by cookie name.
Return
• ESP_OK : Key is found in the cookie string and copied to buffer
• ESP_ERR_NO_MEM : Memory allocation failure
Parameters
• [in] req: Pointer to the HTTP request
• [in] cookie_name: The cookie name to be searched in the request
• [out] val: Pointer to the buffer into which the value of cookie will be copied if the cookie is
found
• [inout] val_size: Pointer to size of the user buffer val . This vari-
able will contain cookie length if ESP_OK is returned and required buffer length incase
ESP_ERR_HTTPD_RESULT_TRUNC is returned.
bool httpd_uri_match_wildcard(const char *uri_template, const char *uri_to_match, size_t
match_upto)
Test if a URI matches the given wildcard template.
Template may end with ? to make the previous character optional (typically a slash), * for a wildcard
match, and ?* to make the previous character optional, and if present, allow anything to follow.
Example:
• * matches everything
• /foo/? matches /foo and /foo/
• /foo/* (sans the backslash) matches /foo/ and /foo/bar, but not /foo or /fo
• /foo/?* or /foo/*? (sans the backslash) matches /foo/, /foo/bar, and also /foo, but not /foox or /fo
The special characters ? and * anywhere else in the template will be taken literally.
Return true if a match was found
Parameters
• [in] uri_template: URI template (pattern)
• [in] uri_to_match: URI to be matched
• [in] match_upto: how many characters of the URI buffer to test (there may be trailing query
string etc.)
esp_err_t httpd_resp_send(httpd_req_t *r, const char *buf, ssize_t buf_len)
API to send a complete HTTP response.
This API will send the data as an HTTP response to the request. This assumes that you have the entire response
ready in a single buffer. If you wish to send response in incremental chunks use httpd_resp_send_chunk()
instead.
If no status code and content-type were set, by default this will send 200 OK status code and content type
as text/html. You may call the following functions before this API to configure the response headers :
httpd_resp_set_status() - for setting the HTTP status string, httpd_resp_set_type() - for setting the Content
Type, httpd_resp_set_hdr() - for appending any additional field value entries in the response header
Note
pointer is valid.
• Once this API is called, the request has been responded to.

• No additional data can then be sent for the request.

• Once this API is called, all request headers are purged, so request headers need be copied into
separate buffers if they are required later.
Return
• ESP_OK : On successfully sending the response packet
• ESP_ERR_INVALID_ARG : Null request pointer
• ESP_ERR_HTTPD_RESP_HDR : Essential headers are too large for internal buffer
• ESP_ERR_HTTPD_RESP_SEND : Error in raw send
• ESP_ERR_HTTPD_INVALID_REQ : Invalid request
Parameters
• [in] buf: Buffer from where the content is to be fetched
• [in] buf_len: Length of the buffer, HTTPD_RESP_USE_STRLEN to use strlen()
esp_err_t httpd_resp_send_chunk(httpd_req_t *r, const char *buf, ssize_t buf_len)
API to send one HTTP chunk.
This API will send the data as an HTTP response to the request. This API will use chunked-encoding and
send the response in the form of chunks. If you have the entire response contained in a single buffer, please
use httpd_resp_send() instead.
If no status code and content-type were set, by default this will send 200 OK status code and content
type as text/html. You may call the following functions before this API to configure the response headers
httpd_resp_set_status() - for setting the HTTP status string, httpd_resp_set_type() - for setting the Content
Type, httpd_resp_set_hdr() - for appending any additional field value entries in the response header
Note
pointer is valid.
• When you are finished sending all your chunks, you must call this function with buf_len as 0.
Return
• ESP_OK : On successfully sending the response packet chunk
• ESP_ERR_HTTPD_INVALID_REQ : Invalid request pointer
Parameters
• [in] buf: Pointer to a buffer that stores the data
• [in] buf_len: Length of the buffer, HTTPD_RESP_USE_STRLEN to use strlen()
static esp_err_t httpd_resp_sendstr(httpd_req_t *r, const char *str)
API to send a complete string as HTTP response.
This API simply calls http_resp_send with buffer length set to string length assuming the buffer contains a null
terminated string
Return
Parameters
• [in] str: String to be sent as response body
static esp_err_t httpd_resp_sendstr_chunk(httpd_req_t *r, const char *str)
API to send a string as an HTTP response chunk.

This API simply calls http_resp_send_chunk with buffer length set to string length assuming the buffer contains
a null terminated string
Return
Parameters
• [in] str: String to be sent as response body (NULL to finish response packet)
esp_err_t httpd_resp_set_status(httpd_req_t *r, const char *status)
API to set the HTTP status code.
This API sets the status of the HTTP response to the value specified. By default, the 200 OK response is
sent as the response.
Note
pointer is valid.
• This API only sets the status to this value. The status isn t sent out until any of the send APIs is
executed.
• Make sure that the lifetime of the status string is valid till send function is called.
Return
• ESP_OK : On success
Parameters
• [in] status: The HTTP status code of this response
esp_err_t httpd_resp_set_type(httpd_req_t *r, const char *type)
API to set the HTTP content type.
This API sets the Content Type field of the response. The default content type is text/html .
Note
pointer is valid.
• This API only sets the content type to this value. The type isn t sent out until any of the send APIs
is executed.
• Make sure that the lifetime of the type string is valid till send function is called.
Return
Parameters
• [in] type: The Content Type of the response
esp_err_t httpd_resp_set_hdr(httpd_req_t *r, const char *field, const char *value)
API to append any additional headers.
This API sets any additional header fields that need to be sent in the response.
Note
pointer is valid.
• The header isn t sent out until any of the send APIs is executed.
• The maximum allowed number of additional headers is limited to value of max_resp_headers in
config structure.

• Make sure that the lifetime of the field value strings are valid till send function is called.
Return
• ESP_OK : On successfully appending new header
• ESP_ERR_HTTPD_RESP_HDR : Total additional headers exceed max allowed
Parameters
• [in] field: The field name of the HTTP header
• [in] value: The value of this HTTP header
esp_err_t httpd_resp_send_err(httpd_req_t *req, httpd_err_code_t error, const char *msg)
For sending out error code in response to HTTP request.
Note
pointer is valid.
• If you wish to send additional data in the body of the response, please use the lower-level functions
directly.
Return
Parameters
• [in] req: Pointer to the HTTP request for which the response needs to be sent
• [in] error: Error type to send
• [in] msg: Error message string (pass NULL for default message)
static esp_err_t httpd_resp_send_404(httpd_req_t *r)
Helper function for HTTP 404.
Send HTTP 404 message. If you wish to send additional data in the body of the response, please use the
lower-level functions directly.
Note
pointer is valid.
Return
Parameters
Note
pointer is valid.
Return


Parameters
Note
pointer is valid.
Return
Parameters
int httpd_send(httpd_req_t *r, const char *buf, size_t buf_len)
Raw HTTP send.
Call this API if you wish to construct your custom response packet. When using this, all essential header, eg.
HTTP version, Status Code, Content Type and Length, Encoding, etc. will have to be constructed manually,
and HTTP delimeters (CRLF) will need to be placed correctly for separating sub-sections of the HTTP response
packet.
If the send override function is set, this API will end up calling that function eventually to send data out.
Note
pointer is valid.
• Unless the response has the correct HTTP structure (which the user must now ensure) it is not
guaranteed that it will be recognized by the client. For most cases, you wouldn t have to call this
API, but you would rather use either of : httpd_resp_send(), httpd_resp_send_chunk()
Return
• Bytes : Number of bytes that were sent successfully
• HTTPD_SOCK_ERR_TIMEOUT : Timeout/interrupted while calling socket send()
• HTTPD_SOCK_ERR_FAIL : Unrecoverable error while calling socket send()
Parameters
• [in] buf: Buffer from where the fully constructed packet is to be read
• [in] buf_len: Length of the buffer
int httpd_socket_send(httpd_handle_t hd, int sockfd, const char *buf, size_t buf_len, int flags)
A low level API to send data on a given socket
This internally calls the default send function, or the function registered by httpd_sess_set_send_override().
Note This API is not recommended to be used in any request handler. Use this only for advanced use cases,
wherein some asynchronous data is to be sent over a socket.
Return
• Bytes : The number of bytes sent successfully


Parameters
• [in] hd: server instance
• [in] sockfd: session socket file descriptor
• [in] buf: buffer with bytes to send
• [in] buf_len: data size
• [in] flags: flags for the send() function
int httpd_socket_recv(httpd_handle_t hd, int sockfd, char *buf, size_t buf_len, int flags)
A low level API to receive data from a given socket
This internally calls the default recv function, or the function registered by httpd_sess_set_recv_override().
Note This API is not recommended to be used in any request handler. Use this only for advanced use cases,
wherein some asynchronous communication is required.
Return
• Bytes : The number of bytes received successfully
Parameters
esp_err_t httpd_register_err_handler(httpd_handle_t handle, httpd_err_code_t error,
httpd_err_handler_func_t handler_fn)
Function for registering HTTP error handlers.
This function maps a handler function to any supported error code given by httpd_err_code_t. See
prototype httpd_err_handler_func_t above for details.
Return
• ESP_OK : handler registered successfully
• ESP_ERR_INVALID_ARG : invalid error code or server handle
Parameters
• [in] handle: HTTP server handle
• [in] error: Error type
• [in] handler_fn: User implemented handler function (Pass NULL to unset any previously set
handler)
esp_err_t httpd_start(httpd_handle_t *handle, const httpd_config_t *config)
Starts the web server.
Create an instance of HTTP server and allocate memory/resources for it depending upon the specified config-
uration.
Example usage:
//Function for starting the webserver
httpd_handle_t start_webserver(void)
{
// Generate default configuration
// Empty handle to http_server

httpd_handle_t server = NULL;
// Start the httpd server

if (httpd_start(&server, &config) == ESP_OK) {


// Register URI handlers
httpd_register_uri_handler(server, &uri_get);
httpd_register_uri_handler(server, &uri_post);
}
// If server failed to start, handle will be NULL
return server;
}
Return
• ESP_OK : Instance created successfully
• ESP_ERR_INVALID_ARG : Null argument(s)
• ESP_ERR_HTTPD_ALLOC_MEM : Failed to allocate memory for instance
• ESP_ERR_HTTPD_TASK : Failed to launch server task
Parameters
• [in] config: Configuration for new instance of the server
• [out] handle: Handle to newly created instance of the server. NULL on error
esp_err_t httpd_stop(httpd_handle_t handle)
Stops the web server.
Deallocates memory/resources used by an HTTP server instance and deletes it. Once deleted the handle can
no longer be used for accessing the instance.
Example usage:
// Function for stopping the webserver

void stop_webserver(httpd_handle_t server)
{
// Ensure handle is non NULL
if (server != NULL) {
// Stop the httpd server
httpd_stop(server);
}
}
Return
• ESP_OK : Server stopped successfully
• ESP_ERR_INVALID_ARG : Handle argument is Null
Parameters
• [in] handle: Handle to server returned by httpd_start
esp_err_t httpd_queue_work(httpd_handle_t handle, httpd_work_fn_t work, void *arg)
Queue execution of a function in HTTPD s context.
This API queues a work function for asynchronous execution
Note Some protocols require that the web server generate some asynchronous data and send it to the persis-
tently opened connection. This facility is for use by such protocols.
Return
• ESP_OK : On successfully queueing the work
• ESP_FAIL : Failure in ctrl socket
Parameters
• [in] work: Pointer to the function to be executed in the HTTPD s context
• [in] arg: Pointer to the arguments that should be passed to this function
void *httpd_sess_get_ctx(httpd_handle_t handle, int sockfd)
Get session context from socket descriptor.
Typically if a session context is created, it is available to URI handlers through the httpd_req_t structure.
But, there are cases where the web server s send/receive functions may require the context (for example,

for accessing keying information etc). Since the send/receive function only have the socket descriptor at their
disposal, this API provides them with a way to retrieve the session context.
Return
• void* : Pointer to the context associated with this session
• NULL : Empty context / Invalid handle / Invalid socket fd
Parameters
• [in] sockfd: The socket descriptor for which the context should be extracted.
void httpd_sess_set_ctx(httpd_handle_t handle, int sockfd, void *ctx, httpd_free_ctx_fn_t free_fn)
Set session context by socket descriptor.
Parameters
• [in] ctx: Context object to assign to the session
• [in] free_fn: Function that should be called to free the context
void *httpd_sess_get_transport_ctx(httpd_handle_t handle, int sockfd)
Get session transport context by socket descriptor.
This context is used by the send/receive functions, for example to manage SSL context.
See httpd_sess_get_ctx()
Return
• void* : Pointer to the transport context associated with this session
• NULL : Empty context / Invalid handle / Invalid socket fd
Parameters
void httpd_sess_set_transport_ctx(httpd_handle_t handle, int sockfd, void *ctx,
httpd_free_ctx_fn_t free_fn)
Set session transport context by socket descriptor.
See httpd_sess_set_ctx()
Parameters
• [in] ctx: Transport context object to assign to the session
• [in] free_fn: Function that should be called to free the transport context
void *httpd_get_global_user_ctx(httpd_handle_t handle)
Get HTTPD global user context (it was set in the server config struct)
Return global user context
Parameters
void *httpd_get_global_transport_ctx(httpd_handle_t handle)
Get HTTPD global transport context (it was set in the server config struct)
Return global transport context
Parameters
esp_err_t httpd_sess_trigger_close(httpd_handle_t handle, int sockfd)
Trigger an httpd session close externally.
Note Calling this API is only required in special circumstances wherein some application requires to close an
httpd client session asynchronously.
Return
• ESP_OK : On successfully initiating closure
• ESP_FAIL : Failure to queue work

• ESP_ERR_NOT_FOUND : Socket fd not found

Parameters
• [in] sockfd: The socket descriptor of the session to be closed
esp_err_t httpd_sess_update_lru_counter(httpd_handle_t handle, int sockfd)
Update LRU counter for a given socket.
LRU Counters are internally associated with each session to monitor how recently a session exchanged traffic.
When LRU purge is enabled, if a client is requesting for connection but maximum number of sockets/sessions
is reached, then the session having the earliest LRU counter is closed automatically.
Updating the LRU counter manually prevents the socket from being purged due to the Least Recently Used
(LRU) logic, even though it might not have received traffic for some time. This is useful when all open sock-
ets/session are frequently exchanging traffic but the user specifically wants one of the sessions to be kept open,
irrespective of when it last exchanged a packet.
Note Calling this API is only necessary if the LRU Purge Enable option is enabled.
Return
• ESP_OK : Socket found and LRU counter updated
• ESP_ERR_NOT_FOUND : Socket not found
Parameters
• [in] sockfd: The socket descriptor of the session for which LRU counter is to be updated
esp_err_t httpd_get_client_list(httpd_handle_t handle, size_t *fds, int *client_fds)
Returns list of current socket descriptors of active sessions.
Note Size of provided array has to be equal or greater then maximum number of opened sockets, configured
upon initialization with max_open_sockets field in httpd_config_t structure.
Return
• ESP_OK : Successfully retrieved session list
• ESP_ERR_INVALID_ARG : Wrong arguments or list is longer than provided array
Parameters
• [inout] fds: In: Size of provided client_fds array Out: Number of valid client fds returned in
client_fds,
• [out] client_fds: Array of client fds
Structures
struct httpd_config
HTTP Server Configuration Structure.
Note Use HTTPD_DEFAULT_CONFIG() to initialize the configuration to a default value and then modify
only those fields that are specifically determined by the use case.
Public Members
unsigned task_priority
Priority of FreeRTOS task which runs the server
size_t stack_size
The maximum stack size allowed for the server task
BaseType_t core_id
The core the HTTP server task will run on
uint16_t server_port
TCP Port number for receiving and transmitting HTTP traffic

uint16_t ctrl_port
UDP Port number for asynchronously exchanging control signals between various components of the
server
uint16_t max_open_sockets
Max number of sockets/clients connected at any time
uint16_t max_uri_handlers
Maximum allowed uri handlers
uint16_t max_resp_headers
Maximum allowed additional headers in HTTP response
uint16_t backlog_conn
Number of backlog connections
bool lru_purge_enable
Purge Least Recently Used connection
uint16_t recv_wait_timeout
Timeout for recv function (in seconds)
uint16_t send_wait_timeout
Timeout for send function (in seconds)
void *global_user_ctx
Global user context.
This field can be used to store arbitrary user data within the server context. The value can be retrieved
using the server handle, available e.g. in the httpd_req_t struct.
When shutting down, the server frees up the user context by calling free() on the global_user_ctx field.
If you wish to use a custom function for freeing the global user context, please specify that here.
httpd_free_ctx_fn_t global_user_ctx_free_fn
Free function for global user context
void *global_transport_ctx
Global transport context.
Similar to global_user_ctx, but used for session encoding or encryption (e.g. to hold the SSL context). It
will be freed using free(), unless global_transport_ctx_free_fn is specified.
httpd_free_ctx_fn_t global_transport_ctx_free_fn
Free function for global transport context
httpd_open_func_t open_fn
Custom session opening callback.
Called on a new session socket just after accept(), but before reading any data.
This is an opportunity to set up e.g. SSL encryption using global_transport_ctx and the send/recv/pending
session overrides.
If a context needs to be maintained between these functions, store it in the session using
httpd_sess_set_transport_ctx() and retrieve it later with httpd_sess_get_transport_ctx()
Returning a value other than ESP_OK will immediately close the new socket.
httpd_close_func_t close_fn
Custom session closing callback.
Called when a session is deleted, before freeing user and transport contexts and before closing the socket.
This is a place for custom de-init code common to all sockets.
Set the user or transport context to NULL if it was freed here, so the server does not try to free it again.
This function is run for all terminated sessions, including sessions where the socket was closed by the
network stack - that is, the file descriptor may not be valid anymore.

httpd_uri_match_func_t uri_match_fn
URI matcher function.
Called when searching for a matching URI: 1) whose request handler is to be executed right after an HTTP
request is successfully parsed 2) in order to prevent duplication while registering a new URI handler using
httpd_register_uri_handler()
Available options are: 1) NULL : Internally do basic matching using strncmp() 2)
httpd_uri_match_wildcard() : URI wildcard matcher
Users can implement their own matching functions (See description of the
httpd_uri_match_func_t function prototype)
struct httpd_req
HTTP Request Data Structure.
Public Members
httpd_handle_t handle
Handle to server instance
int method
The type of HTTP request, -1 if unsupported method
const char uri[HTTPD_MAX_URI_LEN + 1]
The URI of this request (1 byte extra for null termination)
size_t content_len
Length of the request body
void *aux
Internally used members
void *user_ctx
User context pointer passed during URI registration.
void *sess_ctx
Session Context Pointer
A session context. Contexts are maintained across sessions for a given open TCP connection. One
session could have multiple request responses. The web server will ensure that the context persists across
all these request and responses.
By default, this is NULL. URI Handlers can set this to any meaningful value.
If the underlying socket gets closed, and this pointer is non-NULL, the web server will free up the context
by calling free(), unless free_ctx function is set.
httpd_free_ctx_fn_t free_ctx
Pointer to free context hook
Function to free session context
If the web server s socket closes, it frees up the session context by calling free() on the sess_ctx member.
If you wish to use a custom function for freeing the session context, please specify that here.
bool ignore_sess_ctx_changes
Flag indicating if Session Context changes should be ignored
By default, if you change the sess_ctx in some URI handler, the http server will internally free the
earlier context (if non NULL), after the URI handler returns. If you want to manage the alloca-
tion/reallocation/freeing of sess_ctx yourself, set this flag to true, so that the server will not perform
any checks on it. The context will be cleared by the server (by calling free_ctx or free()) only if the
socket gets closed.
struct httpd_uri
Structure for URI handler.

Public Members
const char *uri

The URI to handle
httpd_method_t method
Method supported by the URI
esp_err_t (*handler)(httpd_req_t *r)
Handler to call for supported request method. This must return ESP_OK, or else the underlying socket
will be closed.
void *user_ctx
Pointer to user context data which will be available to handler
Macros
HTTPD_MAX_REQ_HDR_LEN
HTTPD_MAX_URI_LEN
HTTPD_SOCK_ERR_FAIL
HTTPD_SOCK_ERR_INVALID
HTTPD_SOCK_ERR_TIMEOUT
HTTPD_200
HTTP Response 200
HTTPD_204
HTTP Response 204
HTTPD_207
HTTP Response 207
HTTPD_400
HTTP Response 400
HTTPD_404
HTTP Response 404
HTTPD_408
HTTP Response 408
HTTPD_500
HTTP Response 500
HTTPD_TYPE_JSON
HTTP Content type JSON
HTTPD_TYPE_TEXT
HTTP Content type text/HTML
HTTPD_TYPE_OCTET
HTTP Content type octext-stream
HTTPD_DEFAULT_CONFIG()
ESP_ERR_HTTPD_BASE
Starting number of HTTPD error codes
ESP_ERR_HTTPD_HANDLERS_FULL
All slots for registering URI handlers have been consumed
ESP_ERR_HTTPD_HANDLER_EXISTS
URI handler with same method and target URI already registered
ESP_ERR_HTTPD_INVALID_REQ
Invalid request pointer

ESP_ERR_HTTPD_RESULT_TRUNC
Result string truncated
ESP_ERR_HTTPD_RESP_HDR
Response header field larger than supported
ESP_ERR_HTTPD_RESP_SEND
Error occured while sending response packet
ESP_ERR_HTTPD_ALLOC_MEM
Failed to dynamically allocate memory for resource
ESP_ERR_HTTPD_TASK
Failed to launch server task/thread
HTTPD_RESP_USE_STRLEN
Type Definitions
typedef struct httpd_req httpd_req_t
HTTP Request Data Structure.
typedef struct httpd_uri httpd_uri_t
Structure for URI handler.
typedef int (*httpd_send_func_t)(httpd_handle_t hd, int sockfd, const char *buf, size_t buf_len,
int flags)
Prototype for HTTPDs low-level send function.
Note User specified send function must handle errors internally, depending upon the set value of errno,
and return specific HTTPD_SOCK_ERR_ codes, which will eventually be conveyed as return value
of httpd_send() function
Return
• Bytes : The number of bytes sent successfully
Parameters
typedef int (*httpd_recv_func_t)(httpd_handle_t hd, int sockfd, char *buf, size_t buf_len, int
flags)
Prototype for HTTPDs low-level recv function.
Note User specified recv function must handle errors internally, depending upon the set value of errno,
and return specific HTTPD_SOCK_ERR_ codes, which will eventually be conveyed as return value
of httpd_req_recv() function
Return
• Bytes : The number of bytes received successfully
Parameters

typedef int (*httpd_pending_func_t)(httpd_handle_t hd, int sockfd)

Prototype for HTTPDs low-level get pending bytes function.
Note User specified pending function must handle errors internally, depending upon the set value of errno,
and return specific HTTPD_SOCK_ERR_ codes, which will be handled accordingly in the server task.
Return
• Bytes : The number of bytes waiting to be received
• HTTPD_SOCK_ERR_TIMEOUT : Timeout/interrupted while calling socket pending()
• HTTPD_SOCK_ERR_FAIL : Unrecoverable error while calling socket pending()
Parameters
typedef esp_err_t (*httpd_err_handler_func_t)(httpd_req_t *req, httpd_err_code_t error)
Function prototype for HTTP error handling.
This function is executed upon HTTP errors generated during internal processing of an HTTP request. This is
used to override the default behavior on error, which is to send HTTP error response and close the underlying
socket.
Note
• If implemented, the server will not automatically send out HTTP error response codes, therefore,
httpd_resp_send_err() must be invoked inside this function if user wishes to generate HTTP error
responses.
• When invoked, the validity of uri, method, content_len and user_ctx fields of the
httpd_req_t parameter is not guaranteed as the HTTP request may be partially received/parsed.
• The function must return ESP_OK if underlying socket needs to be kept open. Any other
value will ensure that the socket is closed. The return value is ignored when error is of type
HTTPD_500_INTERNAL_SERVER_ERROR and the socket closed anyway.
Return
• ESP_OK : error handled successful
• ESP_FAIL : failure indicates that the underlying socket needs to be closed
Parameters
• [in] req: HTTP request for which the error needs to be handled
• [in] error: Error type
typedef void *httpd_handle_t
HTTP Server Instance Handle.
Every instance of the server will have a unique handle.
typedef enum http_method httpd_method_t
HTTP Method Type wrapper over enum http_method available in http_parser library.
typedef void (*httpd_free_ctx_fn_t)(void *ctx)
Prototype for freeing context data (if any)
Parameters
• [in] ctx: object to free
typedef esp_err_t (*httpd_open_func_t)(httpd_handle_t hd, int sockfd)
Function prototype for opening a session.
Called immediately after the socket was opened to set up the send/recv functions and other parameters of the
socket.
Return
• Any value other than ESP_OK will signal the server to close the socket immediately
Parameters

typedef void (*httpd_close_func_t)(httpd_handle_t hd, int sockfd)

Function prototype for closing a session.
Note It s possible that the socket descriptor is invalid at this point, the function is called for all terminated
sessions. Ensure proper handling of return codes.
Parameters
typedef bool (*httpd_uri_match_func_t)(const char *reference_uri, const char
*uri_to_match, size_t match_upto)
Function prototype for URI matching.
Return true on match
Parameters
• [in] reference_uri: URI/template with respect to which the other URI is matched
• [in] uri_to_match: URI/template being matched to the reference URI/template
• [in] match_upto: For specifying the actual length of uri_to_match up to which the match-
ing algorithm is to be applied (The maximum value is strlen(uri_to_match), independent
of the length of reference_uri)
typedef struct httpd_config httpd_config_t
HTTP Server Configuration Structure.
Note Use HTTPD_DEFAULT_CONFIG() to initialize the configuration to a default value and then modify
only those fields that are specifically determined by the use case.
typedef void (*httpd_work_fn_t)(void *arg)
Prototype of the HTTPD work function Please refer to httpd_queue_work() for more details.
Parameters
• [in] arg: The arguments for this work function
Enumerations
enum httpd_err_code_t
Error codes sent as HTTP response in case of errors encountered during processing of an HTTP request.
Values:
HTTPD_500_INTERNAL_SERVER_ERROR = 0
HTTPD_501_METHOD_NOT_IMPLEMENTED
HTTPD_505_VERSION_NOT_SUPPORTED
HTTPD_400_BAD_REQUEST
HTTPD_401_UNAUTHORIZED
HTTPD_403_FORBIDDEN
HTTPD_404_NOT_FOUND
HTTPD_405_METHOD_NOT_ALLOWED
HTTPD_408_REQ_TIMEOUT
HTTPD_411_LENGTH_REQUIRED
HTTPD_414_URI_TOO_LONG
HTTPD_431_REQ_HDR_FIELDS_TOO_LARGE
HTTPD_ERR_CODE_MAX

2.4.7 HTTPS server
Overview
This component is built on top of esp_http_server. The HTTPS server takes advantage of hooks and function overrides
in the regular HTTP server to provide encryption using OpenSSL.
All documentation for esp_http_server applies also to a server you create this way.
Used APIs
The following API of esp_http_server should not be used with esp_https_server, as they are used internally to handle
secure sessions and to maintain internal state:
• send , receive and pending function overrides - secure socket handling
– httpd_sess_set_send_override()
– httpd_sess_set_recv_override()
– httpd_sess_set_pending_override()
• transport context - both global and session
– httpd_sess_get_transport_ctx() - returns SSL used for the session
– httpd_sess_set_transport_ctx()
– httpd_get_global_transport_ctx() - returns the shared SSL context
– httpd_config_t.global_transport_ctx
– httpd_config_t.global_transport_ctx_free_fn
– httpd_config_t.open_fn - used to set up secure sockets
Everything else can be used without limitations.
Usage
Please see the example protocols/https_server to learn how to set up a secure server.
Basically all you need is to generate a certificate, embed it in the firmware, and provide its pointers and lengths to the
start function via the init struct.
The server can be started with or without SSL by changing a flag in the init struct - httpd_ssl_config.
transport_mode. This could be used e.g. for testing or in trusted environments where you prefer speed over
security.
Performance
The initial session setup can take about two seconds, or more with slower clock speeds or more verbose logging.
Subsequent requests through the open secure socket are much faster (down to under 100 ms).
API Reference
Header File
• components/esp_https_server/include/esp_https_server.h
Functions
esp_err_t httpd_ssl_start(httpd_handle_t *handle, httpd_ssl_config_t *config)
Create a SSL capable HTTP server (secure mode may be disabled in config)
Return success
Parameters
• [inout] config: - server config, must not be const. Does not have to stay valid after calling
this function.

• [out] handle: - storage for the server handle, must be a valid pointer
void httpd_ssl_stop(httpd_handle_t handle)
Stop the server. Blocks until the server is shut down.
Parameters
• [in] handle:
Structures
struct esp_https_server_user_cb_arg
Callback data struct, contains the ESP-TLS connection handle.
struct httpd_ssl_config
HTTPS server config struct
Please use HTTPD_SSL_CONFIG_DEFAULT() to initialize it.
Public Members
httpd_config_t httpd
Underlying HTTPD server config
Parameters like task stack size and priority can be adjusted here.
const uint8_t *cacert_pem
CA certificate (here it is treated as server cert) Todo: Fix this change in release/v5.0 as it would be
a breaking change i.e. Rename the nomenclature of variables holding different certs in https_server
component as well as example 1)The cacert variable should hold the CA which is used to authenticate
clients (should inherit current role of client_verify_cert_pem var) 2)There should be another variable
servercert which whould hold servers own certificate (should inherit current role of cacert var)
size_t cacert_len
CA certificate byte length
const uint8_t *client_verify_cert_pem
Client verify authority certificate (CA used to sign clients, or client cert itself
size_t client_verify_cert_len
Client verify authority cert len
const uint8_t *prvtkey_pem
Private key
size_t prvtkey_len
Private key byte length
httpd_ssl_transport_mode_t transport_mode
Transport Mode (default secure)
uint16_t port_secure
Port used when transport mode is secure (default 443)
uint16_t port_insecure
Port used when transport mode is insecure (default 80)
bool session_tickets
Enable tls session tickets
esp_https_server_user_cb *user_cb
User callback for esp_https_server
Macros

HTTPD_SSL_CONFIG_DEFAULT()
Default config struct init
(http_server default config had to be copied for customization)
Notes:
• port is set when starting the server, according to transport_mode
• one socket uses ~ 40kB RAM with SSL, we reduce the default socket count to 4
• SSL sockets are usually long-lived, closing LRU prevents pool exhaustion DOS
• Stack size may need adjustments depending on the user application
Type Definitions
typedef struct esp_https_server_user_cb_arg esp_https_server_user_cb_arg_t
Callback data struct, contains the ESP-TLS connection handle.
typedef void esp_https_server_user_cb(esp_https_server_user_cb_arg_t *user_cb)
Callback function prototype Can be used to get connection or client information (SSL context) E.g. Client
certificate, Socket FD, Connection state, etc.
Parameters
• user_cb: Callback data struct
typedef struct httpd_ssl_config httpd_ssl_config_t
Enumerations
enum httpd_ssl_transport_mode_t
Values:
HTTPD_SSL_TRANSPORT_SECURE
HTTPD_SSL_TRANSPORT_INSECURE
2.4.8 ICMP Echo
Overview
ICMP (Internet Control Message Protocol) is used for diagnostic or control purposes or generated in response to
errors in IP operations. The common network util ping is implemented based on the ICMP packets with the type
field value of 0, also called Echo Reply.
During a ping session, the source host firstly sends out an ICMP echo request packet and wait for an ICMP echo reply
with specific times. In this way, it also measures the round-trip time for the messages. After receiving a valid ICMP
echo reply, the source host will generate statistics about the IP link layer (e.g. packet loss, elapsed time, etc).
It is common that IoT device needs to check whether a remote server is alive or not. The device should show the
warnings to users when it got offline. It can be achieved by creating a ping session and sending/parsing ICMP echo
packets periodically.
To make this internal procedure much easier for users, ESP-IDF provides some out-of-box APIs.
Create a new ping session To create a ping session, you need to fill in the esp_ping_config_t configuration
structure firstly, specifying target IP address, interval times, and etc. Optionally, you can also register some callback
functions with the esp_ping_callbacks_t` structure.
Example method to create a new ping session and register callbacks:
static void test_on_ping_success(esp_ping_handle_t hdl, void *args)

{
// optionally, get callback arguments
// const char* str = (const char*) args;


// printf("%s\r\n", str); // "foo"
uint8_t ttl;
uint16_t seqno;
uint32_t elapsed_time, recv_len;
ip_addr_t target_addr;
esp_ping_get_profile(hdl, ESP_PING_PROF_SEQNO, &seqno, sizeof(seqno));
esp_ping_get_profile(hdl, ESP_PING_PROF_TTL, &ttl, sizeof(ttl));
esp_ping_get_profile(hdl, ESP_PING_PROF_IPADDR, &target_addr, sizeof(target_
,→addr));
esp_ping_get_profile(hdl, ESP_PING_PROF_SIZE, &recv_len, sizeof(recv_len));

esp_ping_get_profile(hdl, ESP_PING_PROF_TIMEGAP, &elapsed_time, sizeof(elapsed_
,→time));
printf("%d bytes from %s icmp_seq=%d ttl=%d time=%d ms\n",

recv_len, inet_ntoa(target_addr.u_addr.ip4), seqno, ttl, elapsed_time);
}
static void test_on_ping_timeout(esp_ping_handle_t hdl, void *args)

{
uint16_t seqno;
esp_ping_get_profile(hdl, ESP_PING_PROF_SEQNO, &seqno, sizeof(seqno));
esp_ping_get_profile(hdl, ESP_PING_PROF_IPADDR, &target_addr, sizeof(target_
,→addr));
printf("From %s icmp_seq=%d timeout\n", inet_ntoa(target_addr.u_addr.ip4),␣

,→seqno);
static void test_on_ping_end(esp_ping_handle_t hdl, void *args)

{
uint32_t transmitted;
uint32_t received;
uint32_t total_time_ms;
esp_ping_get_profile(hdl, ESP_PING_PROF_REQUEST, &transmitted,␣

,→ sizeof(transmitted));
esp_ping_get_profile(hdl, ESP_PING_PROF_REPLY, &received, sizeof(received));
esp_ping_get_profile(hdl, ESP_PING_PROF_DURATION, &total_time_ms, sizeof(total_
,→time_ms));
printf("%d packets transmitted, %d received, time %dms\n", transmitted,␣

,→received, total_time_ms);
void initialize_ping()
{
/* convert URL to IP address */
struct addrinfo hint;
struct addrinfo *res = NULL;
memset(&hint, 0, sizeof(hint));
memset(&target_addr, 0, sizeof(target_addr));
getaddrinfo("www.espressif.com", NULL, &hint, &res);
struct in_addr addr4 = ((struct sockaddr_in *) (res->ai_addr))->sin_addr;
inet_addr_to_ip4addr(ip_2_ip4(&target_addr), &addr4);
freeaddrinfo(res);
esp_ping_config_t ping_config = ESP_PING_DEFAULT_CONFIG();

ping_config.target_addr = target_addr; // target IP address
ping_config.count = ESP_PING_COUNT_INFINITE; // ping in infinite mode, esp_
,→ping_stop can stop it
/* set callback functions */



esp_ping_callbacks_t cbs;
cbs.on_ping_success = test_on_ping_success;
cbs.on_ping_timeout = test_on_ping_timeout;
cbs.on_ping_end = test_on_ping_end;
cbs.cb_args = "foo"; // arguments that will feed to all callback functions,␣
,→can be NULL
cbs.cb_args = eth_event_group;
esp_ping_handle_t ping;
esp_ping_new_session(&ping_config, &cbs, &ping);
}
Start and Stop ping session You can start and stop ping session with the handle returned by
esp_ping_new_session. Note that, the ping session won t start automatically after creation. If the ping
session is stopped, and restart again, the sequence number in ICMP packets will recount from zero again.
Delete a ping session If a ping session won t be used any more, you can delete it with
esp_ping_delete_session. Please make sure the ping session is in stop state (i.e. you have called
esp_ping_stop before or the ping session has finished all the procedures) when you call this function.
Get runtime statistics As the example code above, you can call esp_ping_get_profile to get different
runtime statistics of ping session in the callback function.
Application Example
ICMP echo example: protocols/icmp_echo
API Reference
Header File
• components/lwip/include/apps/ping/ping_sock.h
Functions
esp_err_t esp_ping_new_session(const esp_ping_config_t *config, const esp_ping_callbacks_t
*cbs, esp_ping_handle_t *hdl_out)
Create a ping session.
Return
• ESP_ERR_INVALID_ARG: invalid parameters (e.g. configuration is null, etc)
• ESP_FAIL: other internal error (e.g. socket error)
• ESP_OK: create ping session successfully, user can take the ping handle to do follow-on jobs
Parameters
• config: ping configuration
• cbs: a bunch of callback functions invoked by internal ping task
• hdl_out: handle of ping session
esp_err_t esp_ping_delete_session(esp_ping_handle_t hdl)
Delete a ping session.
Return
• ESP_ERR_INVALID_ARG: invalid parameters (e.g. ping handle is null, etc)
• ESP_OK: delete ping session successfully
Parameters
• hdl: handle of ping session

esp_err_t esp_ping_start(esp_ping_handle_t hdl)

Start the ping session.
Return
• ESP_OK: start ping session successfully
Parameters
esp_err_t esp_ping_stop(esp_ping_handle_t hdl)
Stop the ping session.
Return
• ESP_OK: stop ping session successfully
Parameters
esp_err_t esp_ping_get_profile(esp_ping_handle_t hdl, esp_ping_profile_t profile, void *data,
uint32_t size)
Get runtime profile of ping session.
Return
• ESP_ERR_INVALID_SIZE: the actual profile data size doesn t match the size parameter
• ESP_OK: get profile successfully
Parameters
• profile: type of profile
• data: profile data
• size: profile data size
Structures
struct esp_ping_callbacks_t
Type of ping callback functions.
Public Members
void *cb_args
arguments for callback functions
void (*on_ping_success)(esp_ping_handle_t hdl, void *args)
Invoked by internal ping thread when received ICMP echo reply packet.
void (*on_ping_timeout)(esp_ping_handle_t hdl, void *args)
Invoked by internal ping thread when receive ICMP echo reply packet timeout.
void (*on_ping_end)(esp_ping_handle_t hdl, void *args)
Invoked by internal ping thread when a ping session is finished.
struct esp_ping_config_t
Type of ping configuration.
Public Members
uint32_t count
A ping session contains count procedures
uint32_t interval_ms
Milliseconds between each ping procedure

uint32_t timeout_ms
Timeout value (in milliseconds) of each ping procedure
uint32_t data_size
Size of the data next to ICMP packet header
uint8_t tos
Type of Service, a field specified in the IP header
ip_addr_t target_addr
Target IP address, either IPv4 or IPv6
uint32_t task_stack_size
Stack size of internal ping task
uint32_t task_prio
Priority of internal ping task
uint32_t interface
Netif index, interface=0 means NETIF_NO_INDEX
Macros
ESP_PING_DEFAULT_CONFIG()
Default ping configuration.
ESP_PING_COUNT_INFINITE
Set ping count to zero will ping target infinitely
Type Definitions
typedef void *esp_ping_handle_t
Type of ping session handle.
Enumerations
enum esp_ping_profile_t
Profile of ping session.
Values:
ESP_PING_PROF_SEQNO
Sequence number of a ping procedure
ESP_PING_PROF_TTL
Time to live of a ping procedure
ESP_PING_PROF_REQUEST
Number of request packets sent out
ESP_PING_PROF_REPLY
Number of reply packets received
ESP_PING_PROF_IPADDR
IP address of replied target
ESP_PING_PROF_SIZE
Size of received packet
ESP_PING_PROF_TIMEGAP
Elapsed time between request and reply packet
ESP_PING_PROF_DURATION
Elapsed time of the whole ping session

2.4.9 ESP Local Control
Overview
ESP Local Control (esp_local_ctrl) component in ESP-IDF provides capability to control an ESP device over Wi-Fi
+ HTTPS or BLE. It provides access to application defined properties that are available for reading / writing via a
set of configurable handlers.
Initialization of the esp_local_ctrl service over BLE transport is performed as follows:
esp_local_ctrl_config_t config = {
.transport = ESP_LOCAL_CTRL_TRANSPORT_BLE,
.transport_config = {
.ble = & (protocomm_ble_config_t) {
.device_name = SERVICE_NAME,
.service_uuid = {
/* LSB <---------------------------------------
* ---------------------------------------> MSB */
0x21, 0xd5, 0x3b, 0x8d, 0xbd, 0x75, 0x68, 0x8a,
0xb4, 0x42, 0xeb, 0x31, 0x4a, 0x1e, 0x98, 0x3d
}
}
},
.proto_sec = {
.version = PROTOCOM_SEC0,
.custom_handle = NULL,
.pop = NULL,
},
.handlers = {
/* User defined handler functions */
.get_prop_values = get_property_values,
.set_prop_values = set_property_values,
.usr_ctx = NULL,
.usr_ctx_free_fn = NULL
},
/* Maximum number of properties that may be set */
.max_properties = 10
};
/* Start esp_local_ctrl service */

ESP_ERROR_CHECK(esp_local_ctrl_start(&config));
Similarly for HTTPS transport:
/* Set the configuration */

httpd_ssl_config_t https_conf = HTTPD_SSL_CONFIG_DEFAULT();
/* Load server certificate */

extern const unsigned char cacert_pem_start[] asm("_binary_cacert_pem_
,→start");
extern const unsigned char cacert_pem_end[] asm("_binary_cacert_pem_end

,→");
https_conf.cacert_pem = cacert_pem_start;
https_conf.cacert_len = cacert_pem_end - cacert_pem_start;
/* Load server private key */

extern const unsigned char prvtkey_pem_start[] asm("_binary_prvtkey_pem_
,→start");
extern const unsigned char prvtkey_pem_end[] asm("_binary_prvtkey_pem_

,→end");
https_conf.prvtkey_pem = prvtkey_pem_start;
https_conf.prvtkey_len = prvtkey_pem_end - prvtkey_pem_start;

esp_local_ctrl_config_t config = {
.transport = ESP_LOCAL_CTRL_TRANSPORT_HTTPD,
.transport_config = {
.httpd = &https_conf
},
.proto_sec = {
.version = PROTOCOM_SEC0,
.custom_handle = NULL,
.pop = NULL,
},
.handlers = {
/* User defined handler functions */
.get_prop_values = get_property_values,
.set_prop_values = set_property_values,
.usr_ctx = NULL,
.usr_ctx_free_fn = NULL
},
/* Maximum number of properties that may be set */
.max_properties = 10
};
/* Start esp_local_ctrl service */

ESP_ERROR_CHECK(esp_local_ctrl_start(&config));
You may set security for transport in ESP local control using following options:
1. PROTOCOM_SEC1: specifies that end to end encryption is used.
2. PROTOCOM_SEC0: specifies that data will be exchanged as a plain text.
3. PROTOCOM_SEC_CUSTOM: you can define your own security requirement. Please note that you will also
have to provide custom_handle of type protocomm_security_t * in this context.
Creating a property
Now that we know how to start the esp_local_ctrl service, let s add a property to it. Each property must have a
unique name (string), a type (e.g. enum), flags (bit fields) and size.
The size is to be kept 0, if we want our property value to be of variable length (e.g. if its a string or bytestream). For
fixed length property value data-types, like int, float, etc., setting the size field to the right value, helps esp_local_ctrl
to perform internal checks on arguments received with write requests.
The interpretation of type and flags fields is totally upto the application, hence they may be used as enumerations, bit-
fields, or even simple integers. One way is to use type values to classify properties, while flags to specify characteristics
of a property.
Here is an example property which is to function as a timestamp. It is assumed that the application defines
TYPE_TIMESTAMP and READONLY, which are used for setting the type and flags fields here.
/* Create a timestamp property */

esp_local_ctrl_prop_t timestamp = {
.name = "timestamp",
.type = TYPE_TIMESTAMP,
.size = sizeof(int32_t),
.flags = READONLY,
.ctx = func_get_time,
.ctx_free_fn = NULL
};
/* Now register the property */

esp_local_ctrl_add_property(&timestamp);

Also notice that there is a ctx field, which is set to point to some custom func_get_time(). This can be used inside the
property get / set handlers to retrieve timestamp.
Here is an example of get_prop_values() handler, which is used for retrieving the timestamp.
static esp_err_t get_property_values(size_t props_count,
const esp_local_ctrl_prop_t *props,
esp_local_ctrl_prop_val_t *prop_
,→values,
void *usr_ctx)
{
for (uint32_t i = 0; i < props_count; i++) {
ESP_LOGI(TAG, "Reading %s", props[i].name);
if (props[i].type == TYPE_TIMESTAMP) {
/* Obtain the timer function from ctx */
int32_t (*func_get_time)(void) = props[i].ctx;
/* Use static variable for saving the value.

* This is essential because the value has to be
* valid even after this function returns.
* Alternative is to use dynamic allocation
* and set the free_fn field */
static int32_t ts = func_get_time();
prop_values[i].data = &ts;
}
}
return ESP_OK;
}
Here is an example of set_prop_values() handler. Notice how we restrict from writing to read-only properties.
static esp_err_t set_property_values(size_t props_count,
const esp_local_ctrl_prop_t *props,
const esp_local_ctrl_prop_val_t␣
,→*prop_values,
void *usr_ctx)
{
for (uint32_t i = 0; i < props_count; i++) {
if (props[i].flags & READONLY) {
ESP_LOGE(TAG, "Cannot write to read-only property %s",␣
,→props[i].name);
return ESP_ERR_INVALID_ARG;
} else {
ESP_LOGI(TAG, "Setting %s", props[i].name);
/* For keeping it simple, lets only log the incoming data */

ESP_LOG_BUFFER_HEX_LEVEL(TAG, prop_values[i].data,
prop_values[i].size, ESP_LOG_INFO);
}
}
return ESP_OK;
}
For complete example see protocols/esp_local_ctrl
Client Side Implementation
The client side implementation will have establish a protocomm session with the device first, over the supported mode
of transport, and then send and receive protobuf messages understood by the esp_local_ctrl service. The service will
translate these messages into requests and then call the appropriate handlers (set / get). Then, the generated response
for each handler is again packed into a protobuf message and transmitted back to the client.
See below the various protobuf messages understood by the esp_local_ctrl service:

1. get_prop_count : This should simply return the total number of properties supported by the service
2. get_prop_values : This accepts an array of indices and should return the information (name, type, flags) and
values of the properties corresponding to those indices
3. set_prop_values : This accepts an array of indices and an array of new values, which are used for setting the
values of the properties corresponding to the indices
Note that indices may or may not be the same for a property, across multiple sessions. Therefore, the client must
only use the names of the properties to uniquely identify them. So, every time a new session is established, the client
should first call get_prop_count and then get_prop_values, hence form an index to name mapping for all properties.
Now when calling set_prop_values for a set of properties, it must first convert the names to indexes, using the created
mapping. As emphasized earlier, the client must refresh the index to name mapping every time a new session is
established with the same device.
The various protocomm endpoints provided by esp_local_ctrl are listed below:
Table 7: Endpoints provided by ESP Local Control

Endpoint URI (HTTPS Server + Description
Name mDNS)
(BLE +
GATT
Server)
esp_local_ctrl/version
https://<mdns- Endpoint used for retrieving version string
hostname>.local/esp_local_ctrl/version
esp_local_ctrl/control
https://<mdns- Endpoint used for sending / receiving control messages
hostname>.local/esp_local_ctrl/control
API Reference
Header File
• components/esp_local_ctrl/include/esp_local_ctrl.h
Functions
const esp_local_ctrl_transport_t *esp_local_ctrl_get_transport_ble(void)
Function for obtaining BLE transport mode.
const esp_local_ctrl_transport_t *esp_local_ctrl_get_transport_httpd(void)
Function for obtaining HTTPD transport mode.
esp_err_t esp_local_ctrl_start(const esp_local_ctrl_config_t *config)
Start local control service.
Return
• ESP_OK : Success
• ESP_FAIL : Failure
Parameters
• [in] config: Pointer to configuration structure
esp_err_t esp_local_ctrl_stop(void)
Stop local control service.
esp_err_t esp_local_ctrl_add_property(const esp_local_ctrl_prop_t *prop)
Add a new property.
This adds a new property and allocates internal resources for it. The total number of properties that could be
added is limited by configuration option max_properties
Return
Parameters

• [in] prop: Property description structure

esp_err_t esp_local_ctrl_remove_property(const char *name)
Remove a property.
This finds a property by name, and releases the internal resources which are associated with it.
Return
• ESP_ERR_NOT_FOUND : Failure
Parameters
• [in] name: Name of the property to remove
const esp_local_ctrl_prop_t *esp_local_ctrl_get_property(const char *name)
Get property description structure by name.
This API may be used to get a property s context structure esp_local_ctrl_prop_t when its name
is known
Return
• Pointer to property
• NULL if not found
Parameters
• [in] name: Name of the property to find
esp_err_t esp_local_ctrl_set_handler(const char *ep_name, protocomm_req_handler_t han-
dler, void *user_ctx)
Register protocomm handler for a custom endpoint.
This API can be called by the application to register a protocomm handler for an endpoint after the local control
service has started.
Note In case of BLE transport the names and uuids of all custom endpoints must be provided beforehand as
a part of the protocomm_ble_config_t structure set in esp_local_ctrl_config_t, and
passed to esp_local_ctrl_start().
Return
Parameters
• [in] ep_name: Name of the endpoint
• [in] handler: Endpoint handler function
• [in] user_ctx: User data
Unions
union esp_local_ctrl_transport_config_t
#include <esp_local_ctrl.h> Transport mode (BLE / HTTPD) configuration.
Public Members
esp_local_ctrl_transport_config_ble_t *ble
This is same as protocomm_ble_config_t. See protocomm_ble.h for available configuration
parameters.
esp_local_ctrl_transport_config_httpd_t *httpd
This is same as httpd_ssl_config_t. See esp_https_server.h for available configuration
parameters.
Structures
struct esp_local_ctrl_prop
Property description data structure, which is to be populated and passed to the
esp_local_ctrl_add_property() function.

Once a property is added, its structure is available for read-only access inside get_prop_values() and
set_prop_values() handlers.
Public Members
char *name
Unique name of property
uint32_t type
Type of property. This may be set to application defined enums
size_t size
Size of the property value, which:
• if zero, the property can have values of variable size
• if non-zero, the property can have values of fixed size only, therefore, checks are performed internally
by esp_local_ctrl when setting the value of such a property
uint32_t flags
Flags set for this property. This could be a bit field. A flag may indicate property behavior, e.g. read-only
/ constant
void *ctx
Pointer to some context data relevant for this property. This will be available for use inside the
get_prop_values and set_prop_values handlers as a part of this property structure. When
set, this is valid throughout the lifetime of a property, till either the property is removed or the
esp_local_ctrl service is stopped.
void (*ctx_free_fn)(void *ctx)
Function used by esp_local_ctrl to internally free the property context when
esp_local_ctrl_remove_property() or esp_local_ctrl_stop() is called.
struct esp_local_ctrl_prop_val
Property value data structure. This gets passed to the get_prop_values() and set_prop_values()
handlers for the purpose of retrieving or setting the present value of a property.
Public Members
void *data
Pointer to memory holding property value
size_t size
Size of property value
void (*free_fn)(void *data)
This may be set by the application in get_prop_values() handler to tell esp_local_ctrl
to call this function on the data pointer above, for freeing its resources after sending the
get_prop_values response.
struct esp_local_ctrl_handlers
Handlers for receiving and responding to local control commands for getting and setting properties.
Public Members
esp_err_t (*get_prop_values)(size_t props_count, const esp_local_ctrl_prop_t props[],

esp_local_ctrl_prop_val_t prop_values[], void *usr_ctx)
Handler function to be implemented for retrieving current values of properties.
Note If any of the properties have fixed sizes, the size field of corresponding element in prop_values
need to be set
Return Returning different error codes will convey the corresponding protocol level errors to the client
:

• ESP_ERR_INVALID_ARG : InvalidArgument
• ESP_ERR_INVALID_STATE : InvalidProto
• All other error codes : InternalError
Parameters
• [in] props_count: Total elements in the props array
• [in] props: Array of properties, the current values for which have been requested by the
client
• [out] prop_values: Array of empty property values, the elements of which need to be
populated with the current values of those properties specified by props argument
• [in] usr_ctx: This provides value of the usr_ctx field of
esp_local_ctrl_handlers_t structure
esp_err_t (*set_prop_values)(size_t props_count, const esp_local_ctrl_prop_t props[], const
esp_local_ctrl_prop_val_t prop_values[], void *usr_ctx)
Handler function to be implemented for changing values of properties.
Note If any of the properties have variable sizes, the size field of the corresponding element in
prop_values must be checked explicitly before making any assumptions on the size.
Return Returning different error codes will convey the corresponding protocol level errors to the client
:
• ESP_ERR_INVALID_ARG : InvalidArgument
• ESP_ERR_INVALID_STATE : InvalidProto
• All other error codes : InternalError
Parameters
• [in] props_count: Total elements in the props array
• [in] props: Array of properties, the values for which the client requests to change
• [in] prop_values: Array of property values, the elements of which need to be used for
updating those properties specified by props argument
• [in] usr_ctx: This provides value of the usr_ctx field of
esp_local_ctrl_handlers_t structure
void *usr_ctx
Context pointer to be passed to above handler functions upon invocation. This is different from the
property level context, as this is valid throughout the lifetime of the esp_local_ctrl service, and
freed only when the service is stopped.
void (*usr_ctx_free_fn)(void *usr_ctx)
Pointer to function which will be internally invoked on usr_ctx for freeing the context resources when
esp_local_ctrl_stop() is called.
struct esp_local_ctrl_proto_sec_cfg
Protocom security configs
Public Members
esp_local_ctrl_proto_sec_t version
This sets protocom security version, sec0/sec1 or custom If custom, user must provide handle via
proto_sec_custom_handle below
void *custom_handle
Custom security handle if security is set custom via proto_sec above This handle must follow pro-
tocomm_security_t signature
void *pop
Proof of possession to be used for local control. Could be NULL.
struct esp_local_ctrl_config
Configuration structure to pass to esp_local_ctrl_start()

Public Members
const esp_local_ctrl_transport_t *transport

Transport layer over which service will be provided
esp_local_ctrl_transport_config_t transport_config
Transport layer over which service will be provided
esp_local_ctrl_proto_sec_cfg_t proto_sec
Security version and POP
esp_local_ctrl_handlers_t handlers
Register handlers for responding to get/set requests on properties
size_t max_properties
This limits the number of properties that are available at a time
Macros
ESP_LOCAL_CTRL_TRANSPORT_BLE
ESP_LOCAL_CTRL_TRANSPORT_HTTPD
Type Definitions
typedef struct esp_local_ctrl_prop esp_local_ctrl_prop_t
Property description data structure, which is to be populated and passed to the
esp_local_ctrl_add_property() function.
Once a property is added, its structure is available for read-only access inside get_prop_values() and
set_prop_values() handlers.
typedef struct esp_local_ctrl_prop_val esp_local_ctrl_prop_val_t
Property value data structure. This gets passed to the get_prop_values() and set_prop_values()
handlers for the purpose of retrieving or setting the present value of a property.
typedef struct esp_local_ctrl_handlers esp_local_ctrl_handlers_t
Handlers for receiving and responding to local control commands for getting and setting properties.
typedef struct esp_local_ctrl_transport esp_local_ctrl_transport_t
Transport mode (BLE / HTTPD) over which the service will be provided.
This is forward declaration of a private structure, implemented internally by esp_local_ctrl.
typedef struct protocomm_ble_config esp_local_ctrl_transport_config_ble_t
Configuration for transport mode BLE.
This is a forward declaration for protocomm_ble_config_t. To use this, application must set CON-
FIG_BT_BLUEDROID_ENABLED and include protocomm_ble.h.
typedef struct httpd_ssl_config esp_local_ctrl_transport_config_httpd_t
Configuration for transport mode HTTPD.
This is a forward declaration for httpd_ssl_config_t. To use this, application must set CON-
FIG_ESP_HTTPS_SERVER_ENABLE and include esp_https_server.h
typedef enum esp_local_ctrl_proto_sec esp_local_ctrl_proto_sec_t
Security types for esp_local_control.
typedef struct esp_local_ctrl_proto_sec_cfg esp_local_ctrl_proto_sec_cfg_t
Protocom security configs
typedef struct esp_local_ctrl_config esp_local_ctrl_config_t
Configuration structure to pass to esp_local_ctrl_start()

Enumerations
enum esp_local_ctrl_proto_sec
Security types for esp_local_control.
Values:
PROTOCOM_SEC0 = 0
PROTOCOM_SEC1
PROTOCOM_SEC_CUSTOM
2.4.10 mDNS Service
Overview
mDNS is a multicast UDP service that is used to provide local network service and host discovery.
mDNS is installed by default on most operating systems or is available as separate package. On Mac OS it is installed
by default and is called Bonjour. Apple releases an installer for Windows that can be found on Apple s support
page. On Linux, mDNS is provided by avahi and is usually installed by default.
mDNS Properties
• hostname: the hostname that the device will respond to. If not set, the hostname will be read from the
interface. Example: my-esp32 will resolve to my-esp32.local
• default_instance: friendly name for your device, like Jhon's ESP32 Thing. If not set, host-
name will be used.
Example method to start mDNS for the STA interface and set hostname and default_instance:
void start_mdns_service()
{
//initialize mDNS service
esp_err_t err = mdns_init();
if (err) {
printf("MDNS Init failed: %d\n", err);
return;
}
//set hostname
mdns_hostname_set("my-esp32");
//set default instance
mdns_instance_name_set("Jhon's ESP32 Thing");
}
mDNS Services mDNS can advertise information about network services that your device offers. Each service is
defined by a few properties.
• instance_name: friendly name for your service, like Jhon's EESP32 Web Server. If not defined,
default_instance will be used.
• service_type: (required) service type, prepended with underscore. Some common types can be found
here.
• proto: (required) protocol that the service runs on, prepended with underscore. Example: _tcp or _udp
• port: (required) network port that the service runs on
• txt: {var, val} array of strings, used to define properties for your service
Example method to add a few services and different properties:

void add_mdns_services()
{
//add our services
mdns_service_add(NULL, "_http", "_tcp", 80, NULL, 0);
mdns_service_add(NULL, "_arduino", "_tcp", 3232, NULL, 0);
mdns_service_add(NULL, "_myservice", "_udp", 1234, NULL, 0);
//NOTE: services must be added before their properties can be set

//use custom instance for the web server
mdns_service_instance_name_set("_http", "_tcp", "Jhon's ESP32 Web Server");
mdns_txt_item_t serviceTxtData[3] = {
{"board","{esp32}"},
{"u","user"},
{"p","password"}
};
//set txt data for service (will free and replace current data)
mdns_service_txt_set("_http", "_tcp", serviceTxtData, 3);
//change service port

mdns_service_port_set("_myservice", "_udp", 4321);
}
mDNS Query mDNS provides methods for browsing for services and resolving host s IP/IPv6 addresses.
Results for services are returned as a linked list of mdns_result_t objects.
Example method to resolve host IPs:
void resolve_mdns_host(const char * host_name)

{
printf("Query A: %s.local", host_name);
struct ip4_addr addr;

addr.addr = 0;
esp_err_t err = mdns_query_a(host_name, 2000, &addr);

if(err){
if(err == ESP_ERR_NOT_FOUND){
printf("Host was not found!");
return;
}
printf("Query Failed");
return;
}
printf(IPSTR, IP2STR(&addr));
}
Example method to resolve local services:
static const char * if_str[] = {"STA", "AP", "ETH", "MAX"};

static const char * ip_protocol_str[] = {"V4", "V6", "MAX"};
void mdns_print_results(mdns_result_t * results){

mdns_result_t * r = results;
mdns_ip_addr_t * a = NULL;
int i = 1, t;
while(r){
printf("%d: Interface: %s, Type: %s\n", i++, if_str[r->tcpip_if], ip_
,→protocol_str[r->ip_protocol]);


if(r->instance_name){
printf(" PTR : %s\n", r->instance_name);
}
if(r->hostname){
printf(" SRV : %s.local:%u\n", r->hostname, r->port);
}
if(r->txt_count){
printf(" TXT : [%u] ", r->txt_count);
for(t=0; t<r->txt_count; t++){
printf("%s=%s; ", r->txt[t].key, r->txt[t].value);
}
printf("\n");
}
a = r->addr;
while(a){
if(a->addr.type == IPADDR_TYPE_V6){
printf(" AAAA: " IPV6STR "\n", IPV62STR(a->addr.u_addr.ip6));
} else {
printf(" A : " IPSTR "\n", IP2STR(&(a->addr.u_addr.ip4)));
}
a = a->next;
}
r = r->next;
}
void find_mdns_service(const char * service_name, const char * proto)

{
ESP_LOGI(TAG, "Query PTR: %s.%s.local", service_name, proto);
mdns_result_t * results = NULL;

esp_err_t err = mdns_query_ptr(service_name, proto, 3000, 20, &results);
if(err){
ESP_LOGE(TAG, "Query Failed");
return;
}
if(!results){
ESP_LOGW(TAG, "No results found!");
return;
}
mdns_print_results(results);
mdns_query_results_free(results);
}
Example of using the methods above:
void my_app_some_method(){
//search for esp32-mdns.local
resolve_mdns_host("esp32-mdns");
//search for HTTP servers

find_mdns_service("_http", "_tcp");
//or file servers
find_mdns_service("_smb", "_tcp"); //windows sharing
find_mdns_service("_afpovertcp", "_tcp"); //apple sharing
find_mdns_service("_nfs", "_tcp"); //NFS server
find_mdns_service("_ftp", "_tcp"); //FTP server
//or networked printer
find_mdns_service("_printer", "_tcp");


find_mdns_service("_ipp", "_tcp");
}
Application Example
mDNS server/scanner example: protocols/mdns.
API Reference
Header File
• components/mdns/include/mdns.h
Functions
esp_err_t mdns_init(void)
Initialize mDNS on given interface.
Return
• ESP_ERR_INVALID_STATE when failed to register event handler
• ESP_ERR_NO_MEM on memory error
• ESP_FAIL when failed to start mdns task
void mdns_free(void)
Stop and free mDNS server.
esp_err_t mdns_hostname_set(const char *hostname)
Set the hostname for mDNS server required if you want to advertise services.
Return
• ESP_OK success
• ESP_ERR_NO_MEM memory error
Parameters
• hostname: Hostname to set
esp_err_t mdns_delegate_hostname_add(const char *hostname, const mdns_ip_addr_t
*address_list)
Adds a hostname and address to be delegated A/AAAA queries will be replied for the hostname and services
can be added to this host.
Return
• ESP_OK success
• ESP_ERR_INVALID_STATE mDNS is not running
Parameters
• hostname: Hostname to add
• address_list: The IP address list of the host
esp_err_t mdns_delegate_hostname_remove(const char *hostname)
Remove a delegated hostname All the services added to this host will also be removed.
Return
• ESP_OK success
Parameters

• hostname: Hostname to remove

bool mdns_hostname_exists(const char *hostname)
Query whether a hostname has been added.
Return
• true The hostname has been added.
• false The hostname has not been added.
Parameters
• hostname: Hostname to query
esp_err_t mdns_instance_name_set(const char *instance_name)
Set the default instance name for mDNS server.
Return
• ESP_OK success
Parameters
• instance_name: Instance name to set
esp_err_t mdns_service_add(const char *instance_name, const char *service_type, const char
*proto, uint16_t port, mdns_txt_item_t txt[], size_t num_items)
Add service to mDNS server.
Note The value length of txt items will be automatically decided by strlen
Return
• ESP_OK success
• ESP_FAIL failed to add service
Parameters
• instance_name: instance name to set. If NULL, global instance name or hostname will be used.
Note that MDNS_MULTIPLE_INSTANCE config option needs to be enabled for adding multiple
instances with the same instance type.
• service_type: service type (_http, _ftp, etc)
• proto: service protocol (_tcp, _udp)
• port: service port
• txt: string array of TXT data (eg. {{ var , val },{ other , 2 }})
• num_items: number of items in TXT data
esp_err_t mdns_service_add_for_host(const char *instance_name, const char *service_type,
const char *proto, const char *hostname, uint16_t port,
mdns_txt_item_t txt[], size_t num_items)
Add service to mDNS server with a delegated hostname.
Return
• ESP_OK success
• ESP_FAIL failed to add service
Parameters
• instance_name: instance name to set. If NULL, global instance name or hostname will be used
Note that MDNS_MULTIPLE_INSTANCE config option needs to be enabled for adding multiple
instances with the same instance type.
• hostname: service hostname. If NULL, local hostname will be used.
• txt: string array of TXT data (eg. {{ var , val },{ other , 2 }})

bool mdns_service_exists(const char *service_type, const char *proto, const char *hostname)
Check whether a service has been added.
Return
• true Correspondding service has been added.
• false Service not found.
Parameters
• hostname: service hostname. If NULL, checks for the local hostname.
bool mdns_service_exists_with_instance(const char *instance, const char *service_type,
const char *proto, const char *hostname)
Check whether a service has been added.
Return
• true Correspondding service has been added.
• false Service not found.
Parameters
• instance: instance name
• hostname: service hostname. If NULL, checks for the local hostname.
esp_err_t mdns_service_remove(const char *service_type, const char *proto)
Remove service from mDNS server.
Return
• ESP_OK success
• ESP_ERR_NOT_FOUND Service not found
Parameters
esp_err_t mdns_service_remove_for_host(const char *service_type, const char *proto,
const char *hostname)
Remove service from mDNS server with hostname.
Return
• ESP_OK success
Parameters
esp_err_t mdns_service_instance_name_set(const char *service_type, const char *proto,
const char *instance_name)
Set instance name for service.
Return
• ESP_OK success
Parameters
• instance_name: instance name to set

esp_err_t mdns_service_instance_name_set_for_host(const char *service_type, const

char *proto, const char *hostname,
const char *instance_name)
Set instance name for service with hostname.
Return
• ESP_OK success
Parameters
• instance_name: instance name to set
esp_err_t mdns_service_port_set(const char *service_type, const char *proto, uint16_t port)
Set service port.
Return
• ESP_OK success
Parameters
esp_err_t mdns_service_port_set_for_host(const char *service_type, const char *proto,
const char *hostname, uint16_t port)
Set service port with hostname.
Return
• ESP_OK success
Parameters
esp_err_t mdns_service_txt_set(const char *service_type, const char *proto, mdns_txt_item_t
txt[], uint8_t num_items)
Replace all TXT items for service.
Return
• ESP_OK success
Parameters
• txt: array of TXT data (eg. {{ var , val },{ other , 2 }})
esp_err_t mdns_service_txt_set_for_host(const char *service_type, const char *proto,
const char *hostname, mdns_txt_item_t txt[],
uint8_t num_items)

Replace all TXT items for service with hostname.

Return
• ESP_OK success
Parameters
• txt: array of TXT data (eg. {{ var , val },{ other , 2 }})
esp_err_t mdns_service_txt_item_set(const char *service_type, const char *proto, const
char *key, const char *value)
Set/Add TXT item for service TXT record.
Note The value length will be automatically decided by strlen
Return
• ESP_OK success
Parameters
• key: the key that you want to add/update
• value: the new value of the key
esp_err_t mdns_service_txt_item_set_with_explicit_value_len(const char
*service_type, const
char *proto, const
char *key, const
char *value, uint8_t
value_len)
Set/Add TXT item for service TXT record.
Return
• ESP_OK success
Parameters
• value_len: the length of the value
esp_err_t mdns_service_txt_item_set_for_host(const char *service_type, const char
*proto, const char *hostname, const char
*key, const char *value)
Set/Add TXT item for service TXT record with hostname.
Note The value length will be automatically decided by strlen
Return
• ESP_OK success

Parameters
esp_err_t mdns_service_txt_item_set_for_host_with_explicit_value_len(const
char
*service_type,
const
char
*proto,
const
char
*hostname,
const
char
*key,
const
char
*value,
uint8_t
value_len)
Set/Add TXT item for service TXT record with hostname and txt value length.
Return
• ESP_OK success
Parameters
• value_len: the length of the value
esp_err_t mdns_service_txt_item_remove(const char *service_type, const char *proto,
const char *key)
Remove TXT item for service TXT record.
Return
• ESP_OK success
Parameters
• key: the key that you want to remove
esp_err_t mdns_service_txt_item_remove_for_host(const char *service_type, const char
*proto, const char *hostname, const
char *key)
Remove TXT item for service TXT record with hostname.
Return
• ESP_OK success


Parameters
• key: the key that you want to remove
esp_err_t mdns_service_subtype_add_for_host(const char *instance_name, const char
*service_type, const char *proto, const char
*hostname, const char *subtype)
Add subtype for service.
Return
• ESP_OK success
Parameters
• instance_name: instance name. If NULL, will find the first service with the same service type
and protocol.
• subtype: The subtype to add.
esp_err_t mdns_service_remove_all(void)
Remove and free all services from mDNS server.
Return
• ESP_OK success
esp_err_t mdns_query_async_delete(mdns_search_once_t *search)
Deletes the finished query. Call this only after the search has ended!
Return
• ESP_OK success
• ESP_ERR_INVALID_STATE search has not finished
• ESP_ERR_INVALID_ARG pointer to search object is NULL
Parameters
• search: pointer to search object
bool mdns_query_async_get_results(mdns_search_once_t *search, uint32_t timeout,
mdns_result_t **results)
Get results from search pointer. Results available as a pointer to the output parameter. Pointer to search object
has to be deleted via mdns_query_async_delete once the query has finished. The results although have
to be freed manually.
Return True if search has finished before or at timeout False if search timeout is over
Parameters
• search: pointer to search object
• timeout: time in milliseconds to wait for answers
• results: pointer to the results of the query
mdns_search_once_t *mdns_query_async_new(const char *name, const char *service_type,
const char *proto, uint16_t type, uint32_t timeout,
size_t max_results, mdns_query_notify_t notifier)
Query mDNS for host or service asynchronousely. Search has to be tested for progress and deleted manually!
Return mdns_search_once_s pointer to new search object if query initiated successfully. NULL otherwise.
Parameters
• name: service instance or host name (NULL for PTR queries)
• service_type: service type (_http, _arduino, _ftp etc.) (NULL for host queries)
• proto: service protocol (_tcp, _udp, etc.) (NULL for host queries)

• type: type of query (MDNS_TYPE_*)

• timeout: time in milliseconds during which mDNS query is active
• max_results: maximum results to be collected
• notifier: Notification function to be called when the result is ready, can be NULL
esp_err_t mdns_query(const char *name, const char *service_type, const char *proto, uint16_t type,
uint32_t timeout, size_t max_results, mdns_result_t **results)
Query mDNS for host or service All following query methods are derived from this one.
Return
• ESP_OK success
• ESP_ERR_INVALID_ARG timeout was not given
Parameters
• name: service instance or host name (NULL for PTR queries)
• service_type: service type (_http, _arduino, _ftp etc.) (NULL for host queries)
• proto: service protocol (_tcp, _udp, etc.) (NULL for host queries)
• type: type of query (MDNS_TYPE_*)
• timeout: time in milliseconds to wait for answers.
• results: pointer to the results of the query results must be freed using mdns_query_results_free
below
void mdns_query_results_free(mdns_result_t *results)
Free query results.
Parameters
• results: linked list of results to be freed
esp_err_t mdns_query_ptr(const char *service_type, const char *proto, uint32_t timeout, size_t
max_results, mdns_result_t **results)
Query mDNS for service.
Return
• ESP_OK success
Parameters
• service_type: service type (_http, _arduino, _ftp etc.)
• proto: service protocol (_tcp, _udp, etc.)
• timeout: time in milliseconds to wait for answer.
• results: pointer to the results of the query
esp_err_t mdns_query_srv(const char *instance_name, const char *service_type, const char
*proto, uint32_t timeout, mdns_result_t **result)
Query mDNS for SRV record.
Return
• ESP_OK success
Parameters
• instance_name: service instance name
• result: pointer to the result of the query

esp_err_t mdns_query_txt(const char *instance_name, const char *service_type, const char

*proto, uint32_t timeout, mdns_result_t **result)
Query mDNS for TXT record.
Return
• ESP_OK success
Parameters
• instance_name: service instance name
• result: pointer to the result of the query
esp_err_t mdns_query_a(const char *host_name, uint32_t timeout, esp_ip4_addr_t *addr)
Query mDNS for A record.
Return
• ESP_OK success
Parameters
• host_name: host name to look for
• addr: pointer to the resulting IP4 address
esp_err_t mdns_query_aaaa(const char *host_name, uint32_t timeout, esp_ip6_addr_t *addr)
Query mDNS for A record.
Please note that hostname must not contain domain name, as mDNS uses .local domain.
Return
• ESP_OK success
Parameters
• host_name: host name to look for
• timeout: time in milliseconds to wait for answer. If 0, max_results needs to be defined
• addr: pointer to the resulting IP6 address
esp_err_t mdns_handle_system_event(void *ctx, system_event_t *event)
System event handler This method controls the service state on all active interfaces and applications are required
to call it from the system event handler for normal operation of mDNS service.
Please note that hostname must not contain domain name, as mDNS uses .local domain.
Parameters
• ctx: The system event context
• event: The system event
Structures
struct mdns_txt_item_t
mDNS basic text item structure Used in mdns_service_add()

Public Members
const char *key

item key name
const char *value
item value string
struct mdns_ip_addr_s
mDNS query linked list IP item
Public Members
esp_ip_addr_t addr
IP address
struct mdns_ip_addr_s *next
next IP, or NULL for the last IP in the list
struct mdns_result_s
mDNS query result structure
Public Members
struct mdns_result_s *next

next result, or NULL for the last result in the list
mdns_if_t tcpip_if
interface index
uint32_t ttl
time to live
mdns_ip_protocol_t ip_protocol
ip_protocol type of the interface (v4/v6)
char *instance_name
instance name
char *service_type
service type
char *proto
srevice protocol
char *hostname
hostname
uint16_t port
service port
mdns_txt_item_t *txt
txt record
uint8_t *txt_value_len
array of txt value len of each record
size_t txt_count
number of txt items
mdns_ip_addr_t *addr
linked list of IP addresses found

Macros
MDNS_TYPE_A
MDNS_TYPE_PTR
MDNS_TYPE_TXT
MDNS_TYPE_AAAA
MDNS_TYPE_SRV
MDNS_TYPE_OPT
MDNS_TYPE_NSEC
MDNS_TYPE_ANY
Type Definitions
typedef struct mdns_search_once_s mdns_search_once_t
Asynchronous query handle.
typedef struct mdns_ip_addr_s mdns_ip_addr_t
mDNS query linked list IP item
typedef enum mdns_if_internal mdns_if_t
typedef struct mdns_result_s mdns_result_t
mDNS query result structure
typedef void (*mdns_query_notify_t)(mdns_search_once_t *search)
Enumerations
enum mdns_ip_protocol_t
mDNS enum to specify the ip_protocol type
Values:
MDNS_IP_PROTOCOL_V4
MDNS_IP_PROTOCOL_V6
MDNS_IP_PROTOCOL_MAX
enum mdns_if_internal
Values:
MDNS_IF_STA = 0
MDNS_IF_AP = 1
MDNS_IF_ETH = 2
MDNS_IF_MAX
2.4.11 ESP-Modbus
Overview
The Modbus serial communication protocol is de facto standard protocol widely used to connect industrial electronic
devices. Modbus allows communication among many devices connected to the same network, for example, a system
that measures temperature and humidity and communicates the results to a computer. The Modbus protocol uses
several types of data: Holding Registers, Input Registers, Coils (single bit output), Discrete Inputs. Versions of the
Modbus protocol exist for serial port and for Ethernet and other protocols that support the Internet protocol suite.
There are many variants of Modbus protocols, some of them are:

• Modbus RTU This is used in serial communication and makes use of a compact, binary representation of
the data for protocol communication. The RTU format follows the commands/data with a cyclic redundancy
check checksum as an error check mechanism to ensure the reliability of data. Modbus RTU is the most
common implementation available for Modbus. A Modbus RTU message must be transmitted continuously
without inter-character hesitations. Modbus messages are framed (separated) by idle (silent) periods. The
RS-485 interface communication is usually used for this type.
• Modbus ASCII This is used in serial communication and makes use of ASCII characters for protocol
communication. The ASCII format uses a longitudinal redundancy check checksum. Modbus ASCII messages
are framed by leading colon ( : ) and trailing newline (CR/LF).
• Modbus TCP/IP or Modbus TCP This is a Modbus variant used for communications over TCP/IP
networks, connecting over port 502. It does not require a checksum calculation, as lower layers already provide
checksum protection.
The following document (and included code snippets) requires some familiarity with the Modbus protocol. Refer to
the Modbus Organization s with protocol specifications for specifics.
Messaging Model And Data Mapping
Modbus is an application protocol that defines rules for messaging structure and data organization that are indepen-
dent of the data transmission medium. Traditional serial Modbus is a register-based protocol that defines message
transactions that occur between master(s) and slave devices (multiple masters are allowed on using Modbus TCP/IP).
The slave devices listen for communication from the master and simply respond as instructed. The master(s) always
controls communication and may communicate directly to one slave, or all connected slaves, but the slaves cannot
communicate directly with each other.
Note: It is assumed that the number of slaves and their register maps are known by the Modbus master before the
start of stack.
The register map of each slave device is usually part of its device manual. A Slave device usually permits configuration
of its short slave address and communication options that are used within the device s network segment.
The Modbus protocol allows devices to map data to four types of registers (Holding, Input, Discrete, Coil). The
figure below illustrates an example mapping of a device s data to the four types of registers.
The following sections give an overview of how to use the ESP_Modbus component found under compo-
nents/freemodbus. The sections cover initialization of a Modbus port, and the setup a master or slave device ac-
cordingly:
• Modbus Port Initialization
• Modbus Slave API Overview
• Modbus Master API Overview
Modbus Port Initialization The ESP_Modbus supports Modbus SERIAL and TCP ports and a port must be
initialized before calling any other Modbus API. The functions below are used to create and then initialize Modbus
controller interface (either master or slave) over a particular transmission medium (either Serial or TCP/IP):
• mbc_slave_init()
• mbc_master_init()
• mbc_slave_init_tcp()
• mbc_master_init_tcp()
The API call uses the first parameter to recognize the type of port being initialized. Supported enumeration
for different ports: MB_PORT_SERIAL_MASTER, MB_PORT_SERIAL_SLAVE accordingly. The parameters
MB_PORT_TCP_MASTER, MB_PORT_TCP_SLAVE are reserved for internal usage.
void* master_handler = NULL; // Pointer to allocate interface structure

// Initialization of Modbus master for serial port
esp_err_t err = mbc_master_init(MB_PORT_SERIAL_MASTER, &master_handler);

Fig. 26: Modbus segment diagram
Fig. 27: Modbus data mapping


if (master_handler == NULL || err != ESP_OK) {
ESP_LOGE(TAG, "mb controller initialization fail.");
}
This example code to initialize slave port:
void* slave_handler = NULL; // Pointer to allocate interface structure

// Initialization of Modbus slave for TCP
esp_err_t err = mbc_slave_init_tcp(&slave_handler);
if (slave_handler == NULL || err != ESP_OK) {
// Error handling is performed here
ESP_LOGE(TAG, "mb controller initialization fail.");
}
Modbus Master API Overview
The following overview describes how to setup Modbus master communication. The overview reflects a typical
programming workflow and is broken down into the sections provided below:
1. Modbus Port Initialization - Initialization of Modbus controller interface for the selected port.
2. Configuring Master Data Access - Configure data descriptors to access slave parameters.
3. Master Communication Options - Allows to setup communication options for selected port.
4. Master Communication - Start stack and sending / receiving data.
5. Modbus Master Teardown - Destroy Modbus controller and its resources.
Configuring Master Data Access The architectural approach of ESP_Modbus includes one level above standard
Modbus IO driver. The additional layer is called Modbus controller and its goal is to add an abstraction such as
CID - characteristic identifier. The CID is linked to a corresponding Modbus registers through the table called Data
Dictionary and represents device physical parameter (such as temperature, humidity, etc.) in specific Modbus slave
device. This approach allows the upper layer (e.g., MESH or MQTT) to be isolated from Modbus specifics thus
simplify Modbus integration with other protocols/networks.
The Data Dictionary is the list in the Modbus master which shall be defined by user to link each CID to its cor-
responding Modbus registers representation using Register Mapping table of the Modbus slave being used. Each
element in this data dictionary is of type mb_parameter_descriptor_t and represents the description of one
physical characteristic:

Table 8: Table 1 Modbus master Data Dictionary description

Field DescriptionDetailed information
cid Characteristic
The identifier of characteristic (must be unique).
ID
param_key
Characteristic
String description of the characteristic.
Name
param_units
Characteristic
Physical Units of the characteristic.
Units
mb_slave_addr
Modbus The short address of the device with correspond parameter UID.
Slave
Address
mb_param_type
Modbus Type of Modbus register area. MB_PARAM_INPUT, MB_PARAM_HOLDING,
Register MB_PARAM_COIL, MB_PARAM_DISCRETE - represents Input , Holding, Coil and
Type Discrete input register area accordingly;
mb_reg_start
Modbus Relative register address of the characteristic in the register area.
Register
Start
mb_size
Modbus Length of characteristic in registers.
Register
Size
param_offset
Instance Offset to instance of the characteristic in bytes. It is used to calculate the absolute address
Offset to the characteristic in the storage structure. It is optional field and can be set to zero if the
parameter is not used in the application.
param_type
Data Specifies type of the characteristic. PARAM_TYPE_U8, PARAM_TYPE_U16,
Type PARAM_TYPE_U32 - Unsigned integer 8/16/32 bit type; PARAM_TYPE_FLOAT -
IEEE754 floating point format; PARAM_TYPE_ASCII - ASCII string or binary data;
param_size
Data The storage size of the characteristic (bytes).
Size
param_opts
Parameter Limits, options of characteristic used during processing of alarm in user application (optional)
Options
accessParameter Can be used in user application to define the behavior of the characteristic dur-
access ing processing of data in user application; PAR_PERMS_READ_WRITE_TRIGGER,
type PAR_PERMS_READ, PAR_PERMS_READ_WRITE_TRIGGER;
Note: The cid and param_key have to be unique. Please use the prefix to the parameter key if you have several
similar parameters in your register map table.
Table 9: Table 2 Example Register mapping table of Modbus slave

CID Register
Length
Range TypeUnitsDescription
0 300004 MAX_UINT U32 Not Serial number of device (4 bytes) read-only
de-
fined
1 300022 MAX_UINT U16 Not Software version (4 bytes) read-only
de-
fined
2 400004 -20..40 FLOAT DegCRoom temperature in DegC. Writing a temperature value to this register for
single point calibration.
// Enumeration of modbus slave addresses accessed by master device

enum {
MB_DEVICE_ADDR1 = 1,
MB_DEVICE_ADDR2,
MB_SLAVE_COUNT


};
// Enumeration of all supported CIDs for device

enum {
CID_SER_NUM1 = 0,
CID_SW_VER1,
CID_TEMP_DATA_1,
CID_SER_NUM2,
CID_SW_VER2,
CID_TEMP_DATA_2
};
// Example Data Dictionary for Modbus parameters in 2 slaves in the segment

mb_parameter_descriptor_t device_parameters[] = {
// CID, Name, Units, Modbus addr, register type, Modbus Reg Start Addr, Modbus␣
,→Reg read length,
// Instance offset (NA), Instance type, Instance length (bytes), Options (NA),␣
,→Permissions
{ CID_SER_NUM1, STR("Serial_number_1"), STR("--"), MB_DEVICE_ADDR1, MB_PARAM_

,→INPUT, 0, 2,
0, PARAM_TYPE_U32, 4, OPTS( 0,0,0 ), PAR_PERMS_READ_WRITE_

,→TRIGGER },
{ CID_SW_VER1, STR("Software_version_1"), STR("--"), MB_DEVICE_ADDR1, MB_PARAM_

,→INPUT, 2, 1,

,→TRIGGER },
{ CID_TEMP_DATA_1, STR("Temperature_1"), STR("C"), MB_DEVICE_ADDR1, MB_PARAM_

,→HOLDING, 0, 2,
0, PARAM_TYPE_FLOAT, 4, OPTS( 16, 30, 1 ), PAR_PERMS_READ_

,→WRITE_TRIGGER },
{ CID_SER_NUM2, STR("Serial_number_2"), STR("--"), MB_DEVICE_ADDR2, MB_PARAM_

,→INPUT, 0, 2,

,→TRIGGER },
{ CID_SW_VER2, STR("Software_version_2"), STR("--"), MB_DEVICE_ADDR2, MB_PARAM_

,→INPUT, 2, 1,

,→TRIGGER },
{ CID_TEMP_DATA_2, STR("Temperature_2"), STR("C"), MB_DEVICE_ADDR2, MB_PARAM_

,→HOLDING, 0, 2,
0, PARAM_TYPE_FLOAT, 4, OPTS( 20, 30, 1 ), PAR_PERMS_READ_

,→WRITE_TRIGGER },
};
// Calculate number of parameters in the table
uint16_t num_device_parameters = (sizeof(device_parameters) / sizeof(device_
,→parameters[0]));
During initialization of the Modbus stack, a pointer to the Data Dictionary (called descriptor) must be provided as
the parameter of the function below.
mbc_master_set_descriptor(): Initialization of master descriptor.
ESP_ERROR_CHECK(mbc_master_set_descriptor(&device_parameters[0], num_device_
,→parameters));
The Data Dictionary can be initialized from SD card, MQTT or other source before start of stack. Once the initial-
ization and setup is done, the Modbus controller allows the reading of complex parameters from any slave included
in descriptor table using its CID.
Master Communication Options Calling the setup function allows for specific communication options to be de-
fined for port.

mbc_master_setup()
The communication structure provided as a parameter is different for serial and TCP communication mode.
Example setup for serial port:
mb_communication_info_t comm_info = {
.port = MB_PORT_NUM, // Serial port number
.mode = MB_MODE_RTU, // Modbus mode of communication (MB_MODE_RTU or MB_
,→MODE_ASCII)
.baudrate = 9600, // Modbus communication baud rate

.parity = MB_PARITY_NONE // parity option for serial port
};
ESP_ERROR_CHECK(mbc_master_setup((void*)&comm_info));
Modbus master TCP port requires additional definition of IP address table where number of addresses should be
equal to number of unique slave addresses in master Modbus Data Dictionary:
The order of IP address string corresponds to short slave address in the Data Dictionary.
#define MB_SLAVE_COUNT 2 // Number of slaves in the segment being accessed (as␣

,→defined in Data Dictionary)
char* slave_ip_address_table[MB_SLAVE_COUNT] = {
"192.168.1.2", // Address corresponds to UID1 and set to predefined value␣
,→by user
"192.168.1.3", // corresponds to UID2 in the segment

NULL // end of table
};
.ip_port = MB_TCP_PORT, // Modbus TCP port number (default␣
,→= 502)
.ip_addr_type = MB_IPV4, // version of IP protocol

.ip_mode = MB_MODE_TCP, // Port communication mode
.ip_addr = (void*)slave_ip_address_table, // assign table of IP addresses
.ip_netif_ptr = esp_netif_ptr // esp_netif_ptr pointer to the␣
,→corresponding network interface
};
ESP_ERROR_CHECK(mbc_master_setup((void*)&comm_info));
Note: Refer to esp_netif component for more information about network interface initialization.
The slave IP addresses in the table can be assigned automatically using mDNS service as described in the example.
Refer to protocols/modbus/tcp/mb_tcp_master for more information.
Note: RS485 communication requires call to UART specific APIs to setup communication mode and pins. Refer
to Running UART Communication section of UART documentation.
Master Communication The starting of the Modbus controller is the final step in enabling communication. This
is performed using function below:
mbc_master_start()
esp_err_t err = mbc_master_start();

if (err != ESP_OK) {


ESP_LOGE(TAG, "mb controller start fail, err=%x.", err);
}
The list of functions below are used by the Modbus master stack from a user s application:
mbc_master_send_request(): This function executes a blocking Modbus request. The master sends a data
request (as defined in parameter request structure mb_param_request_t) and then blocks until a response from
corresponding slave and returns the status of command execution. This function provides a standard way for read/write
access to Modbus devices in the network.
mbc_master_get_cid_info(): The function gets information about each characteristic supported in the data
dictionary and returns the characteristic s description in the form of the mb_parameter_descriptor_t
structure. Each characteristic is accessed using its CID.
mbc_master_get_parameter(): The function reads the data of a characteristic defined in the parameters of
a Modbus slave device. The additional data for request is taken from parameter description table.
Example:
const mb_parameter_descriptor_t* param_descriptor = NULL;

uint8_t temp_data[4] = {0}; // temporary buffer to hold maximum CID size
uint8_t type = 0;
....
// Get the information for characteristic cid from data dictionary

esp_err_t err = mbc_master_get_cid_info(cid, &param_descriptor);
if ((err != ESP_ERR_NOT_FOUND) && (param_descriptor != NULL)) {
err = mbc_master_get_parameter(param_descriptor->cid, (char*)param_descriptor->
,→param_key, (uint8_t*)temp_data, &type);
ESP_LOGI(TAG, "Characteristic #%d %s (%s) value = (0x%08x) read successful.
,→",
param_descriptor->cid,
(char*)param_descriptor->param_key,
(char*)param_descriptor->param_units,
*(uint32_t*)temp_data);
} else {
ESP_LOGE(TAG, "Characteristic #%d (%s) read fail, err = 0x%x (%s).",
param_descriptor->cid,
(char*)param_descriptor->param_key,
(int)err,
(char*)esp_err_to_name(err));
}
} else {
ESP_LOGE(TAG, "Could not get information for characteristic %d.", cid);
}
mbc_master_set_parameter()
The function writes characteristic s value defined as a name and cid parameter in corresponded slave device. The
additional data for parameter request is taken from master parameter description table.
uint8_t type = 0; // Type of parameter

uint8_t temp_data[4] = {0}; // temporary buffer
esp_err_t err = mbc_master_set_parameter(CID_TEMP_DATA_2, "Temperature_2", (uint8_

,→t*)temp_data, &type);
ESP_LOGI(TAG, "Set parameter data successfully.");
} else {
ESP_LOGE(TAG, "Set data fail, err = 0x%x (%s).", (int)err, (char*)esp_err_to_
,→name(err));

Modbus Master Teardown This function stops Modbus communication stack and destroys controller interface
and free all used active objects.
mbc_master_destroy()
ESP_ERROR_CHECK(mbc_master_destroy());
Modbus Slave API Overview
The sections below represent typical programming workflow for the slave API which should be called in following
order:
1. Modbus Port Initialization - Initialization of Modbus controller interface for the selected port.
2. Configuring Slave Data Access - Configure data descriptors to access slave parameters.
3. Slave Communication Options - Allows to setup communication options for selected port.
4. Slave Communication - Start stack and sending / receiving data. Filter events when master accesses the register
areas.
5. Modbus Slave Teardown - Destroy Modbus controller and its resources.
Configuring Slave Data Access The following functions must be called when the Modbus controller slave port is
already initialized. Refer to Modbus Port Initialization.
The slave stack requires the user to define structures (memory storage areas) that store the Modbus parameters ac-
cessed by stack. These structures should be prepared by the user and be assigned to the Modbus controller interface
using mbc_slave_set_descriptor() API call before the start of communication. The slave task can call the
mbc_slave_check_event() function which will block until the Modbus master access the slave. The slave
task can then get information about the data being accessed.
Note: One slave can define several area descriptors per each type of Modbus register area with different start_offset.
Register area is defined by using the mb_register_area_descriptor_t structure.
Table 10: Table 3 Modbus register area descriptor

Field Description
start_offset
Zero based register relative offset for defined register area. Example: register address = 40002 ( 4x
register area - Function 3 - holding register ), start_offset = 2
type Type of the Modbus register area. Refer to mb_param_type_t for more information.
address
A pointer to the memory area which is used to store the register data for this area descriptor.
size The size of the memory area in bytes which is used to store register data.
mbc_slave_set_descriptor()
The function initializes Modbus communication descriptors for each type of Modbus register area (Holding
Registers, Input Registers, Coils (single bit output), Discrete Inputs). Once areas are initialized and the
mbc_slave_start() API is called the Modbus stack can access the data in user data structures by request
from master.
#define MB_REG_INPUT_START_AREA0 (0)
#define MB_REG_HOLDING_START_AREA0 (0)
#define MB_REG_HOLD_CNT (100)
#define MB_REG_INPUT_CNT (100)
mb_register_area_descriptor_t reg_area; // Modbus register area descriptor␣

,→structure
unit16_t holding_reg_area[MB_REG_HOLD_CNT] = {0}; // storage area for holding␣

,→registers
unit16_t input_reg_area[MB_REG_INPUT_CNT] = {0}; // storage area for input␣

,→registers

reg_area.type = MB_PARAM_HOLDING; // Set type of␣

,→register area
reg_area.start_offset = MB_REG_HOLDING_START_AREA0; // Offset of␣

,→register area in Modbus protocol
reg_area.address = (void*)&holding_reg_area[0]; // Set pointer to␣

,→storage instance
reg_area.size = sizeof(holding_reg_area) << 1; // Set the size of␣

,→register storage area in bytes
ESP_ERROR_CHECK(mbc_slave_set_descriptor(reg_area));
reg_area.type = MB_PARAM_INPUT;
reg_area.start_offset = MB_REG_INPUT_START_AREA0;
reg_area.address = (void*)&input_reg_area[0];
reg_area.size = sizeof(input_reg_area) << 1;
ESP_ERROR_CHECK(mbc_slave_set_descriptor(reg_area));
At least one area descriptor per each Modbus register type must be set in order to provide register access to its area.
If the master tries to access an undefined area, the stack will generate a Modbus exception.
Direct access to register area from user application must be protected by critical section:
portENTER_CRITICAL(&param_lock);
holding_reg_area[2] += 10;
portEXIT_CRITICAL(&param_lock);
Slave Communication Options The function initializes the Modbus controller interface and its active context
(tasks, RTOS objects and other resources).
mbc_slave_setup()
The function is used to setup communication parameters of the Modbus stack.
Example initialization of Modbus TCP communication:
esp_netif_init();
...
.ip_port = MB_TCP_PORT, // Modbus TCP port number (default␣
,→= 502)
.ip_addr_type = MB_IPV4, // version of IP protocol

.ip_mode = MB_MODE_TCP, // Port communication mode
.ip_addr = NULL, // This field keeps the client IP␣
,→address to bind, NULL - bind to any client
.ip_netif_ptr = esp_netif_ptr // esp_netif_ptr - pointer to the␣

,→corresponding network interface
};
// Setup communication parameters and start stack

ESP_ERROR_CHECK(mbc_slave_setup((void*)&comm_info));
Example initialization of Modbus serial communication:
#define MB_SLAVE_DEV_SPEED 9600

#define MB_SLAVE_ADDR 1
#define MB_SLAVE_PORT_NUM 2
...
// Setup communication parameters and start stack



.mode = MB_MODE_RTU, // Communication type
.slave_addr = MB_SLAVE_ADDR, // Short address of the slave
.port = MB_SLAVE_PORT_NUM, // UART physical port number
.baudrate = MB_SLAVE_DEV_SPEED, // Baud rate for communication
.parity = MB_PARITY_NONE // Parity option
};
ESP_ERROR_CHECK(mbc_slave_setup((void*)&comm_info));
Slave Communication The function below is used to start Modbus controller interface and allows communication.
mbc_slave_start()
ESP_ERROR_CHECK(mbc_slave_start());
mbc_slave_check_event()
The blocking call to function waits for a event specified (represented as an event mask parameter). Once the master
accesses the parameter and the event mask matches the parameter type, the application task will be unblocked and
function will return the corresponding event mb_event_group_t which describes the type of register access being
done.
mbc_slave_get_param_info()
The function gets information about accessed parameters from the Modbus controller event queue. The KConfig
CONFIG_FMB_CONTROLLER_NOTIFY_QUEUE_SIZE key can be used to configure the notification queue size. The
timeout parameter allows a timeout to be specified when waiting for a notification. The mb_param_info_t
structure contains information about accessed parameter.
Table 11: Table 4 Description of the register info structure:

mb_param_info_t
Field Description
time_stamp
the time stamp of the event when defined parameter is accessed
mb_offset
start Modbus register accessed by master
type type of the Modbus register area being accessed (See the mb_event_group_t for more informa-
tion)
address memory address that corresponds to accessed register in defined area descriptor
size number of registers being accessed by master
Example to get event when holding or input registers accessed in the slave:
#define MB_READ_MASK (MB_EVENT_INPUT_REG_RD | MB_EVENT_HOLDING_REG_RD)
#define MB_WRITE_MASK (MB_EVENT_HOLDING_REG_WR)
#define MB_READ_WRITE_MASK (MB_READ_MASK | MB_WRITE_MASK)
#define MB_PAR_INFO_GET_TOUT (10 / portTICK_RATE_MS)
....
// The function blocks while waiting for register access

mb_event_group_t event = mbc_slave_check_event(MB_READ_WRITE_MASK);
// Get information about data accessed from master

ESP_ERROR_CHECK(mbc_slave_get_param_info(&reg_info, MB_PAR_INFO_GET_TOUT));
const char* rw_str = (event & MB_READ_MASK) ? "READ" : "WRITE";
// Filter events and process them accordingly

if (event & (MB_EVENT_HOLDING_REG_WR | MB_EVENT_HOLDING_REG_RD)) {
ESP_LOGI(TAG, "HOLDING %s (%u us), ADDR:%u, TYPE:%u, INST_ADDR:0x%.4x, SIZE:%u
,→",
rw_str,


(uint32_t)reg_info.time_stamp,
(uint32_t)reg_info.mb_offset,
(uint32_t)reg_info.type,
(uint32_t)reg_info.address,
(uint32_t)reg_info.size);
} else if (event & (MB_EVENT_INPUT_REG_RD)) {
ESP_LOGI(TAG, "INPUT %s (%u us), ADDR:%u, TYPE:%u, INST_ADDR:0x%.4x, SIZE:%u",
rw_str,
(uint32_t)reg_info.time_stamp,
(uint32_t)reg_info.mb_offset,
(uint32_t)reg_info.type,
(uint32_t)reg_info.address,
(uint32_t)reg_info.size);
}
Modbus Slave Teardown This function stops the Modbus communication stack, destroys the controller interface,
and frees all used active objects allocated for the slave.
mbc_slave_destroy()
ESP_ERROR_CHECK(mbc_slave_destroy());
Possible Communication Issues And Solutions
If the examples do not work as expected and slave and master boards are not able to communicate correctly, it is
possible to find the reason for errors. The most important errors are described in master example output and formatted
as below:
E (1692332) MB_CONTROLLER_MASTER: mbc_master_get_parameter(111): SERIAL master get␣

,→parameter failure error=(0x107) (ESP_ERR_TIMEOUT).

Table 12: Table 5 Modbus error codes and troubleshooting

ErrorDescription Possible solution
0x106ESP_ERR_NOT_SUPPORTED Refer to slave register map. Check the master data dictionary for cor-
- Invalid register request - slave rectness.
returned an exception because
the requested register is not
supported.
0x107ESP_ERR_TIMEOUT - Slave Measure and increase the maximum slave response timeout idf.py menu-
response timeout - Modbus config, option CONFIG_FMB_MASTER_TIMEOUT_MS_RESPOND.
slave did not send response dur- Check physical connection or network configuration and make
ing configured slave response sure that the slave response can reach the master side. If the
timeout. application has some high performance tasks with higher prior-
ity than CONFIG_FMB_PORT_TASK_PRIO it is recommended
to place Modbus tasks on the other core using an option CON-
FIG_FMB_PORT_TASK_AFFINITY. Configure the Modbus task s
priority CONFIG_FMB_PORT_TASK_PRIO to ensure that the task gets
sufficient processing time to handle Modbus stack events.
0x108ESP_ERR_INVALID_RESPONSE Check the physical connection then refer to register map of your slave to
- Received unsupported reconfigure the master data dictionary properly.
sponse from slave or frame
check failure. Master can not
execute command handler
because the command is either
not supported or is incorrect.
0x103ESP_ERR_INVALID_STATE Make sure your physical connection is working properly. Increase task
- Critical failure or FSM se- stack size and check Modbus initialization sequence.
quence failure or master FSM
is busy processing previous
request.
Application Example
The examples below use the FreeModbus library port for serial TCP slave and master implementations accordingly.
The selection of stack is performed through KConfig menu option Enable Modbus stack support for appropriate
communication mode and related configuration keys.
• protocols/modbus/serial/mb_slave
• protocols/modbus/serial/mb_master
• protocols/modbus/tcp/mb_tcp_slave
• protocols/modbus/tcp/mb_tcp_master
Please refer to the specific example README.md for details.
Protocol References
• https://modbus.org/specs.php: Modbus Organization with protocol specifications.
API Reference
Header File
• components/freemodbus/common/include/esp_modbus_common.h
Unions

union mb_communication_info_t
#include <esp_modbus_common.h> Device communication structure to setup Modbus controller.
Public Members
mb_mode_type_t mode
Modbus communication mode
uint8_t slave_addr
Modbus slave address field (dummy for master)
uart_port_t port
Modbus communication port (UART) number
uint32_t baudrate
Modbus baudrate
uart_parity_t parity
Modbus UART parity settings
uint16_t dummy_port
Dummy field, unused
struct mb_communication_info_t::[anonymous] [anonymous]
mb_mode_type_t ip_mode
Modbus communication mode
uint16_t ip_port
Modbus port
mb_tcp_addr_type_t ip_addr_type
Modbus address type
void *ip_addr
Modbus address table for connection
void *ip_netif_ptr
Modbus network interface
struct mb_communication_info_t::[anonymous] [anonymous]
Macros
MB_CONTROLLER_STACK_SIZE
MB_CONTROLLER_PRIORITY
MB_DEVICE_ADDRESS
MB_DEVICE_SPEED
MB_UART_PORT
MB_PAR_INFO_TOUT
MB_PARITY_NONE
_XFER_4_RD(dst, src)
_XFER_2_RD(dst, src)
_XFER_4_WR(dst, src)
_XFER_2_WR(dst, src)

Type Definitions
typedef esp_err_t (*iface_init)(void **)
common interface method typesInterface method init
typedef esp_err_t (*iface_destroy)(void)
Interface method destroy
typedef esp_err_t (*iface_setup)(void *)
Interface method setup
typedef esp_err_t (*iface_start)(void)
Interface method start
Enumerations
enum mb_port_type_t
Types of actual Modbus implementation.
Values:
MB_PORT_SERIAL_MASTER = 0x00
Modbus port type serial master.
MB_PORT_SERIAL_SLAVE
Modbus port type serial slave.
MB_PORT_TCP_MASTER
Modbus port type TCP master.
MB_PORT_TCP_SLAVE
Modbus port type TCP slave.
MB_PORT_COUNT
Modbus port count.
MB_PORT_INACTIVE = 0xFF
enum mb_event_group_t
Event group for parameters notification.
Values:
MB_EVENT_NO_EVENTS = 0x00
MB_EVENT_HOLDING_REG_WR = BIT0
Modbus Event Write Holding registers.
MB_EVENT_HOLDING_REG_RD = BIT1
Modbus Event Read Holding registers.
MB_EVENT_INPUT_REG_RD = BIT3
Modbus Event Read Input registers.
MB_EVENT_COILS_WR = BIT4
Modbus Event Write Coils.
MB_EVENT_COILS_RD = BIT5
Modbus Event Read Coils.
MB_EVENT_DISCRETE_RD = BIT6
Modbus Event Read Discrete bits.
MB_EVENT_STACK_STARTED = BIT7
Modbus Event Stack started
enum mb_param_type_t
Type of Modbus parameter.
Values:

MB_PARAM_HOLDING = 0x00
Modbus Holding register.
MB_PARAM_INPUT
Modbus Input register.
MB_PARAM_COIL
Modbus Coils.
MB_PARAM_DISCRETE
Modbus Discrete bits.
MB_PARAM_COUNT
MB_PARAM_UNKNOWN = 0xFF
enum mb_mode_type_t
Modbus serial transmission modes (RTU/ASCII).
Values:
MB_MODE_RTU
RTU transmission mode.
MB_MODE_ASCII
ASCII transmission mode.
MB_MODE_TCP
TCP communication mode.
MB_MODE_UDP
UDP communication mode.
enum mb_tcp_addr_type_t
Modbus TCP type of address.
Values:
MB_IPV4 = 0
TCP IPV4 addressing
MB_IPV6 = 1
TCP IPV6 addressing
Header File
• components/freemodbus/common/include/esp_modbus_master.h
Functions
esp_err_t mbc_master_init_tcp(void **handler)
Initialize Modbus controller and stack for TCP port.
Return
• ESP_OK Success
• ESP_ERR_NO_MEM Parameter error
• ESP_ERR_NOT_SUPPORTED Port type not supported
• ESP_ERR_INVALID_STATE Initialization failure
Parameters
• [out] handler: handler(pointer) to master data structure
esp_err_t mbc_master_init(mb_port_type_t port_type, void **handler)
Initialize Modbus Master controller and stack for Serial port.
Return
• ESP_OK Success


Parameters
• [in] port_type: type of stack
void mbc_master_init_iface(void *handler)
Initialize Modbus Master controller interface handle.
Parameters
• [in] handler: - pointer to master data structure
esp_err_t mbc_master_destroy(void)
Destroy Modbus controller and stack.
Return
• ESP_OK Success
• ESP_ERR_INVALID_STATE Parameter error
esp_err_t mbc_master_start(void)
Start Modbus communication stack.
Return
• ESP_OK Success
• ESP_ERR_INVALID_ARG Modbus stack start error
esp_err_t mbc_master_setup(void *comm_info)
Set Modbus communication parameters for the controller.
Return
• ESP_OK Success
• ESP_ERR_INVALID_ARG Incorrect parameter data
Parameters
• comm_info: Communication parameters structure.
esp_err_t mbc_master_set_descriptor(const mb_parameter_descriptor_t *descriptor, const
uint16_t num_elements)
Assign parameter description table for Modbus controller interface.
Return
• esp_err_t ESP_OK - set descriptor successfully
• esp_err_t ESP_ERR_INVALID_ARG - invalid argument in function call
Parameters
• [in] descriptor: pointer to parameter description table
• num_elements: number of elements in the table
esp_err_t mbc_master_send_request(mb_param_request_t *request, void *data_ptr)
Send data request as defined in parameter request, waits response from slave and returns status of command
execution. This function provides standard way for read/write access to Modbus devices in the network.
Return
• esp_err_t ESP_OK - request was successful
• esp_err_t ESP_ERR_INVALID_ARG - invalid argument of function
• esp_err_t ESP_ERR_INVALID_RESPONSE - an invalid response from slave
• esp_err_t ESP_ERR_TIMEOUT - operation timeout or no response from slave
• esp_err_t ESP_ERR_NOT_SUPPORTED - the request command is not supported by slave
• esp_err_t ESP_FAIL - slave returned an exception or other failure
Parameters
• [in] request: pointer to request structure of type mb_param_request_t
• [in] data_ptr: pointer to data buffer to send or received data (dependent of command field in
request)
esp_err_t mbc_master_get_cid_info(uint16_t cid, const mb_parameter_descriptor_t
**param_info)
Get information about supported characteristic defined as cid. Uses parameter description table to get this

information. The function will check if characteristic defined as a cid parameter is supported and returns its
description in param_info. Returns ESP_ERR_NOT_FOUND if characteristic is not supported.
Return
• esp_err_t ESP_OK - request was successful and buffer contains the supported characteristic name
• esp_err_t ESP_ERR_INVALID_ARG - invalid argument of function
• esp_err_t ESP_ERR_NOT_FOUND - the characteristic (cid) not found
• esp_err_t ESP_FAIL - unknown error during lookup table processing
Parameters
• [in] cid: characteristic id
• param_info: pointer to pointer of characteristic data.
esp_err_t mbc_master_get_parameter(uint16_t cid, char *name, uint8_t *value, uint8_t *type)
Read parameter from modbus slave device whose name is defined by name and has cid. The additional data
for request is taken from parameter description (lookup) table.
Return
• esp_err_t ESP_OK - request was successful and value buffer contains representation of actual pa-
rameter data from slave
• esp_err_t ESP_ERR_INVALID_ARG - invalid argument of function or parameter descriptor
• esp_err_t ESP_ERR_INVALID_RESPONSE - an invalid response from slave
• esp_err_t ESP_ERR_INVALID_STATE - invalid state during data processing or allocation failure
• esp_err_t ESP_ERR_TIMEOUT - operation timed out and no response from slave
• esp_err_t ESP_ERR_NOT_FOUND - the parameter is not found in the parameter description table
Parameters
• [in] cid: id of the characteristic for parameter
• [in] name: pointer into string name (key) of parameter (null terminated)
• [out] value: pointer to data buffer of parameter
• [out] type: parameter type associated with the name returned from parameter description table.
esp_err_t mbc_master_set_parameter(uint16_t cid, char *name, uint8_t *value, uint8_t *type)
Set characteristic s value defined as a name and cid parameter. The additional data for cid parameter request
is taken from master parameter lookup table.
Return
• esp_err_t ESP_OK - request was successful and value was saved in the slave device registers
• esp_err_t ESP_ERR_INVALID_ARG - invalid argument of function or parameter descriptor
• esp_err_t ESP_ERR_INVALID_RESPONSE - an invalid response from slave during processing of
parameter
• esp_err_t ESP_ERR_INVALID_STATE - invalid state during data processing or allocation failure
• esp_err_t ESP_ERR_TIMEOUT - operation timed out and no response from slave
Parameters
• [in] cid: id of the characteristic for parameter
• [in] name: pointer into string name (key) of parameter (null terminated)
• [out] value: pointer to data buffer of parameter (actual representation of json value field in
binary form)
• [out] type: pointer to parameter type associated with the name returned from parameter lookup
table.
Unions
union mb_parameter_opt_t
#include <esp_modbus_master.h> Modbus parameter options for description table.

Public Members
int opt1
Parameter option1
int opt2
Parameter option2
int opt3
Parameter option3
struct mb_parameter_opt_t::[anonymous] [anonymous]
int min
Parameter minimum value
int max
Parameter maximum value
int step
Step of parameter change tracking
struct mb_parameter_opt_t::[anonymous] [anonymous]
Structures
struct mb_parameter_descriptor_t
Characteristics descriptor type is used to describe characteristic and link it with Modbus parameters that reflect
its data.
Public Members
uint16_t cid
Characteristic cid
const char *param_key
The key (name) of the parameter
const char *param_units
The physical units of the parameter
uint8_t mb_slave_addr
Slave address of device in the Modbus segment
mb_param_type_t mb_param_type
Type of modbus parameter
uint16_t mb_reg_start
This is the Modbus register address. This is the 0 based value.
uint16_t mb_size
Size of mb parameter in registers
uint16_t param_offset
Parameter name (OFFSET in the parameter structure)
mb_descr_type_t param_type
Float, U8, U16, U32, ASCII, etc.
mb_descr_size_t param_size
Number of bytes in the parameter.
mb_parameter_opt_t param_opts
Parameter options used to check limits and etc.
mb_param_perms_t access
Access permissions based on mode

struct mb_param_request_t
Modbus register request type structure.
Public Members
uint8_t slave_addr
Modbus slave address
uint8_t command
Modbus command to send
uint16_t reg_start
Modbus start register
uint16_t reg_size
Modbus number of registers
Enumerations
enum mb_descr_type_t
Modbus descriptor table parameter type defines.
Values:
PARAM_TYPE_U8 = 0x00
Unsigned 8
Unsigned 16
Unsigned 32
PARAM_TYPE_FLOAT = 0x03
Float type
PARAM_TYPE_ASCII = 0x04
ASCII type
enum mb_descr_size_t
Modbus descriptor table parameter size in bytes.
Values:
PARAM_SIZE_U8 = 0x01
Unsigned 8
Unsigned 16
Unsigned 32
PARAM_SIZE_FLOAT = 0x04
Float size
PARAM_SIZE_ASCII = 0x08
ASCII size
PARAM_SIZE_ASCII24 = 0x18
ASCII24 size
PARAM_MAX_SIZE
enum mb_param_perms_t
Permissions for the characteristics.
Values:

PAR_PERMS_READ = 1 << BIT0

the characteristic of the device are readable
PAR_PERMS_WRITE = 1 << BIT1
the characteristic of the device are writable
PAR_PERMS_TRIGGER = 1 << BIT2
the characteristic of the device are triggerable
PAR_PERMS_READ_WRITE = PAR_PERMS_READ | PAR_PERMS_WRITE
the characteristic of the device are readable & writable
PAR_PERMS_READ_TRIGGER = PAR_PERMS_READ | PAR_PERMS_TRIGGER
the characteristic of the device are readable & triggerable
PAR_PERMS_WRITE_TRIGGER = PAR_PERMS_WRITE | PAR_PERMS_TRIGGER
the characteristic of the device are writable & triggerable
PAR_PERMS_READ_WRITE_TRIGGER = PAR_PERMS_READ_WRITE | PAR_PERMS_TRIGGER
the characteristic of the device are readable & writable & triggerable
Header File
• components/freemodbus/common/include/esp_modbus_slave.h
Functions
esp_err_t mbc_slave_init_tcp(void **handler)
Initialize Modbus Slave controller and stack for TCP port.
Return
• ESP_OK Success
Parameters
esp_err_t mbc_slave_init(mb_port_type_t port_type, void **handler)
Initialize Modbus Slave controller and stack for Serial port.
Return
• ESP_OK Success
Parameters
• [in] port_type: the type of port
void mbc_slave_init_iface(void *handler)
Initialize Modbus Slave controller interface handle.
Parameters
• [in] handler: - pointer to slave interface data structure
esp_err_t mbc_slave_destroy(void)
Destroy Modbus controller and stack.
Return
• ESP_OK Success
• ESP_ERR_INVALID_STATE Parameter error
esp_err_t mbc_slave_start(void)
Start Modbus communication stack.

Return
• ESP_OK Success
• ESP_ERR_INVALID_ARG Modbus stack start error
esp_err_t mbc_slave_setup(void *comm_info)
Set Modbus communication parameters for the controller.
Return
• ESP_OK Success
• ESP_ERR_INVALID_ARG Incorrect parameter data
Parameters
• comm_info: Communication parameters structure.
mb_event_group_t mbc_slave_check_event(mb_event_group_t group)
Wait for specific event on parameter change.
Return
• mb_event_group_t event bits triggered
Parameters
• group: Group event bit mask to wait for change
esp_err_t mbc_slave_get_param_info(mb_param_info_t *reg_info, uint32_t timeout)
Get parameter information.
Return
• ESP_OK Success
• ESP_ERR_TIMEOUT Can not get data from parameter queue or queue overflow
Parameters
• [out] reg_info: parameter info structure
• timeout: Timeout in milliseconds to read information from parameter queue
esp_err_t mbc_slave_set_descriptor(mb_register_area_descriptor_t descr_data)
Set Modbus area descriptor.
Return
• ESP_OK: The appropriate descriptor is set
• ESP_ERR_INVALID_ARG: The argument is incorrect
Parameters
• descr_data: Modbus registers area descriptor structure
Structures
struct mb_param_info_t
Parameter access event information type.
Public Members
uint32_t time_stamp
Timestamp of Modbus Event (uS)
uint16_t mb_offset
Modbus register offset
mb_event_group_t type
Modbus event type
uint8_t *address
Modbus data storage address
size_t size
Modbus event register size (number of registers)
struct mb_register_area_descriptor_t
Parameter storage area descriptor.

Public Members
uint16_t start_offset
Modbus start address for area descriptor
mb_param_type_t type
Type of storage area descriptor
void *address
Instance address for storage area descriptor
size_t size
Instance size for area descriptor (bytes)
2.4.12 ESP WebSocket Client
Overview
The ESP WebSocket client is an implementation of WebSocket protocol client for ESP32
Features
• Supports WebSocket over TCP, TLS with mbedtls

• Easy to setup with URI
• Multiple instances (Multiple clients in one application)
Configuration
URI
• Supports ws, wss schemes
• WebSocket samples:
– ws://echo.websocket.org: WebSocket over TCP, default port 80
– wss://echo.websocket.org: WebSocket over SSL, default port 443
Minimal configurations:
const esp_websocket_client_config_t ws_cfg = {

.uri = "ws://echo.websocket.org",
};
The WebSocket client supports the use of both path and query in the URI. Sample:

.uri = "ws://echo.websocket.org/connectionhandler?id=104",
};
If there are any options related to the URI in esp_websocket_client_config_t, the option defined by the
URI will be overridden. Sample:

.uri = "ws://echo.websocket.org:123",
.port = 4567,
};
//WebSocket client will connect to websocket.org using port 4567

TLS Configuration:

.uri = "wss://echo.websocket.org",
.cert_pem = (const char *)websocket_org_pem_start,
};
Note: If you want to verify the server, then you need to provide a certificate in PEM format, and provide to
cert_pem in websocket_client_config_t. If no certficate is provided then the TLS connection will to
default not requiring verification.
PEM certificate for this example could be extracted from an openssl s_client command connecting to websocket.org.
In case a host operating system has openssl and sed packages installed, one could execute the following command
to download and save the root or intermediate root certificate to a file (Note for Windows users: Both Linux like
environment or Windows native packages may be used). ` echo "" | openssl s_client -showcerts
-connect websocket.org:443 | sed -n "1,/Root/d; /BEGIN/,/END/p" | openssl
x509 -outform PEM >websocket_org.pem `
This command will extract the second certificate in the chain and save it as a pem-file.
Subprotocol The subprotocol field in the config struct can be used to request a subprotocol

.uri = "ws://websocket.org",
.subprotocol = "soap",
};
Note: The client is indifferent to the subprotocol field in the server response and will accept the connection no matter
what the server replies.
For more options on esp_websocket_client_config_t, please refer to API reference below
Events
• WEBSOCKET_EVENT_CONNECTED: The client has successfully established a connection to the server. The
client is now ready to send and receive data. Contains no event data.
• WEBSOCKET_EVENT_DISCONNECTED: The client has aborted the connection due to the transport layer
failing to read data, e.g. because the server is unavailable. Contains no event data.
• WEBSOCKET_EVENT_DATA: The client has successfully received and parsed a WebSocket frame. The event
data contains a pointer to the payload data, the length of the payload data as well as the opcode of the received
frame. A message may be fragmented into multiple events if the length exceeds the buffer size. This event will
also be posted for non-payload frames, e.g. pong or connection close frames.
• WEBSOCKET_EVENT_ERROR: Not used in the current implementation of the client.
If the client handle is needed in the event handler it can be accessed through the pointer passed to the event handler:
esp_websocket_client_handle_t client = (esp_websocket_client_handle_t)handler_args;
Limitations and Known Issues
• The client is able to request the use of a subprotocol from the server during the handshake, but does not do any
subprotocol related checks on the response from the server.

Application Example
A simple WebSocket example that uses esp_websocket_client to establish a websocket connection and send/receive
data with the websocket.org server can be found here: protocols/websocket.
Sending Text Data The WebSocket client supports sending data as a text data frame, which informs the application
layer that the payload data is text data encoded as UTF-8. Example:
esp_websocket_client_send_text(client, data, len, portMAX_DELAY);
API Reference
Header File
• components/esp_websocket_client/include/esp_websocket_client.h
Functions
esp_websocket_client_handle_t esp_websocket_client_init(const esp_websocket_client_config_t
*config)
Start a Websocket session This function must be the first function to call, and it returns a
esp_websocket_client_handle_t that you must use as input to other functions in the interface. This call MUST
have a corresponding call to esp_websocket_client_destroy when the operation is complete.
Return
• esp_websocket_client_handle_t
• NULL if any errors
Parameters
• [in] config: The configuration
esp_err_t esp_websocket_client_set_uri(esp_websocket_client_handle_t client, const char
*uri)
Set URL for client, when performing this behavior, the options in the URL will replace the old ones Must stop
the WebSocket client before set URI if the client has been connected.
Return esp_err_t
Parameters
• [in] uri: The uri
esp_err_t esp_websocket_client_start(esp_websocket_client_handle_t client)
Open the WebSocket connection.
Return esp_err_t
Parameters
esp_err_t esp_websocket_client_stop(esp_websocket_client_handle_t client)
Stops the WebSocket connection without websocket closing handshake.
This API stops ws client and closes TCP connection directly without sending close frames. It is a good practice
to close the connection in a clean way using esp_websocket_client_close().
Notes:
• Cannot be called from the websocket event handler
Return esp_err_t
Parameters
esp_err_t esp_websocket_client_destroy(esp_websocket_client_handle_t client)
Destroy the WebSocket connection and free all resources. This function must be the last function to call for an

session. It is the opposite of the esp_websocket_client_init function and must be called with the same handle
as input that a esp_websocket_client_init call returned. This might close all connections this handle has used.
Notes:
Return esp_err_t
Parameters
int esp_websocket_client_send(esp_websocket_client_handle_t client, const char *data, int len,
TickType_t timeout)
Generic write data to the WebSocket connection; defaults to binary send.
Return
• Number of data was sent
Parameters
• [in] data: The data
• [in] timeout: Write data timeout in RTOS ticks
int esp_websocket_client_send_bin(esp_websocket_client_handle_t client, const char *data, int
len, TickType_t timeout)
Write binary data to the WebSocket connection (data send with WS OPCODE=02, i.e. binary)
Return
Parameters
int esp_websocket_client_send_text(esp_websocket_client_handle_t client, const char *data,
int len, TickType_t timeout)
Write textual data to the WebSocket connection (data send with WS OPCODE=01, i.e. text)
Return
Parameters
esp_err_t esp_websocket_client_close(esp_websocket_client_handle_t client, TickType_t time-
out)
Close the WebSocket connection in a clean way.
Sequence of clean close initiated by client:
• Client sends CLOSE frame
• Client waits until server echos the CLOSE frame
• Client waits until server closes the connection
• Client is stopped the same way as by the esp_websocket_client_stop()
Notes:
– Cannot be called from the websocket event handler
Return esp_err_t
Parameters


• [in] timeout: Timeout in RTOS ticks for waiting
esp_err_t esp_websocket_client_close_with_code(esp_websocket_client_handle_t client, int
code, const char *data, int len, Tick-
Type_t timeout)
Close the WebSocket connection in a clean way with custom code/data Closing sequence is the same as for
esp_websocket_client_close()
Notes:
Return esp_err_t
Parameters
• [in] code: Close status code as defined in RFC6455 section-7.4
• [in] data: Additional data to closing message
• [in] len: The length of the additional data
• [in] timeout: Timeout in RTOS ticks for waiting
bool esp_websocket_client_is_connected(esp_websocket_client_handle_t client)
Check the WebSocket client connection state.
Return
• true
• false
Parameters
• [in] client: The client handle
esp_err_t esp_websocket_register_events(esp_websocket_client_handle_t client,
esp_websocket_event_id_t event, esp_event_handler_t
event_handler, void *event_handler_arg)
Register the Websocket Events.
Return esp_err_t
Parameters
• client: The client handle
• event: The event id
• event_handler: The callback function
• event_handler_arg: User context
Structures
struct esp_websocket_event_data_t
Websocket event data.
Public Members
const char *data_ptr

Data pointer
int data_len
Data length
uint8_t op_code
Received opcode
esp_websocket_client_handle_t client
esp_websocket_client_handle_t context
void *user_context
user_data context, from esp_websocket_client_config_t user_data

int payload_len
Total payload length, payloads exceeding buffer will be posted through multiple events
int payload_offset
Actual offset for the data associated with this event
struct esp_websocket_client_config_t
Websocket client setup configuration.
Public Members
const char *uri

Websocket URI, the information on the URI can be overrides the other fields below, if any
const char *host
Domain or IP as string
int port
Port to connect, default depend on esp_websocket_transport_t (80 or 443)
Using for Http authentication - Not supported for now
Using for Http authentication - Not supported for now
const char *path
HTTP Path, if not set, default is /
bool disable_auto_reconnect
Disable the automatic reconnect function when disconnected
void *user_context
HTTP user data context
int task_prio
Websocket task priority
int task_stack
Websocket task stack
int buffer_size
Websocket buffer size
Pointer to certificate data in PEM or DER format for server verify (with SSL), default is NULL, not re-
quired to verify the server. PEM-format must have a terminating NULL-character. DER-format requires
the length to be passed in cert_len.
size_t cert_len
const char *client_cert
Pointer to certificate data in PEM or DER format for SSL mutual authentication, default is NULL, not
required if mutual authentication is not needed. If it is not NULL, also client_key has to be provided.
PEM-format must have a terminating NULL-character. DER-format requires the length to be passed in
client_cert_len.
Length of the buffer pointed to by client_cert. May be 0 for null-terminated pem
const char *client_key
Pointer to private key data in PEM or DER format for SSL mutual authentication, default is NULL,
not required if mutual authentication is not needed. If it is not NULL, also client_cert has to be
passed in client_key_len

esp_websocket_transport_t transport
Websocket transport type, see èsp_websocket_transport_t
const char *subprotocol
Websocket subprotocol
const char *user_agent
Websocket user-agent
const char *headers
Websocket additional headers
int pingpong_timeout_sec
Period before connection is aborted due to no PONGs received
bool disable_pingpong_discon
Disable auto-disconnect due to no PONG received within pingpong_timeout_sec
int keep_alive_idle
Keep-alive idle time. Default is 5 (second)
Keep-alive interval time. Default is 5 (second)
Keep-alive packet retry send count. Default is 3 counts
size_t ping_interval_sec
Websocket ping interval, defaults to 10 seconds if not set
Type Definitions
typedef struct esp_websocket_client *esp_websocket_client_handle_t
Enumerations
enum esp_websocket_event_id_t
Websocket Client events id.
Values:
WEBSOCKET_EVENT_ANY = -1
WEBSOCKET_EVENT_ERROR = 0
This event occurs when there are any errors during execution
WEBSOCKET_EVENT_CONNECTED
Once the Websocket has been connected to the server, no data exchange has been performed
WEBSOCKET_EVENT_DISCONNECTED
The connection has been disconnected
WEBSOCKET_EVENT_DATA
When receiving data from the server, possibly multiple portions of the packet

WEBSOCKET_EVENT_CLOSED
The connection has been closed cleanly
WEBSOCKET_EVENT_MAX
enum esp_websocket_transport_t
Websocket Client transport.
Values:
WEBSOCKET_TRANSPORT_UNKNOWN = 0x0
Transport unknown
WEBSOCKET_TRANSPORT_OVER_TCP
Transport over tcp
WEBSOCKET_TRANSPORT_OVER_SSL
Transport over ssl
2.4.13 ESP Serial Slave Link
Overview
Espressif provides several chips that can work as slaves. These slave devices rely on some common buses, and have
their own communication protocols over those buses. The esp_serial_slave_link component is designed for the master
to communicate with ESP slave devices through those protocols over the bus drivers.
After an esp_serial_slave_link device is initialized properly, the application can use it to communicate with the ESP
slave devices conveniently.
Espressif Device protocols
For more details about Espressif device protocols, see the following documents.
Communication with ESP SDIO Slave This document describes the process of initialization of an ESP SDIO
Slave device and then provides details on the ESP SDIO Slave protocol - a non-standard protocol that allows an SDIO
Host to communicate with an ESP SDIO slave.
The ESP SDIO Slave protocol was created to implement the communication between SDIO host and slave, because
the SDIO specification only shows how to access the custom region of a card (by sending CMD52 and CMD53 to
Functions 1-7) without any details regarding the underlying hardware implementation.
SDIO Slave Capabilities of Espressif chips The services provided by the SDIO Slave peripheral of the ESP32
chip are listed in the table below:
Services ESP32
SDIO slave Y
Tohost intr 8
Frhost intr 8
TX DMA Y
RX DMA Y
Shared registers 56*
• * Not including the interrupt registers

ESP SDIO Slave Initialization The host should initialize the ESP32 SDIO slave according to the standard SDIO
initialization process (Section 3.1.2 of SDIO Simplified Specification). In this specification as well as below, the
SDIO slave is called an (SD)IO card. Here is a brief example of an ESP SDIO Slave initialization process:
1. SDIO reset CMD52 (Write 0x6=0x8)
2. SD reset CMD0
3. Check whether IO card (optional) CMD8
4. Send SDIO op cond and wait for card ready CMD5 arg = 0x00000000
CMD5 arg = 0x00ff8000 (according to the response above, poll until ready)
Example: Arg of R4 after first CMD5 (arg=0x00000000) is 0xXXFFFF00.
Keep sending CMD5 with arg=0x00FFFF00 until the R4 shows card ready (arg bit 31=1).
5. Set address CMD3
6. Select card CMD7 (arg address according to CMD3 response)
Example: Arg of R6 after CMD3 is 0x0001xxxx.
Arg of CMD7 should be 0x00010000.
7. Select 4-bit mode (optional) CMD52 (Write 0x07=0x02)
8. Enable func1 CMD52 (Write 0x02=0x02)
9. Enable SDIO interrupt (required if interrupt line (DAT1) is used) CMD52 (Write 0x04=0x03)
10. Set Func0 blocksize (optional, default value is 512 (0x200)) CMD52/53 (Read 0x10~0x11)
CMD52/53 (Write 0x10=0x00)
CMD52/53 (Write 0x11=0x02)
CMD52/53 (Read 0x10~0x11, read to check the final value)
11. Set Func1 blocksize (optional, default value is 512 (0x200)) CMD52/53 (Read 0x110~0x111)
CMD52/53 (Write 0x110=0x00)
CMD52/53 (Write 0x111=0x02)
CMD52/53 (Read 0x110~0x111, read to check the final value)
ESP SDIO Slave Protocol The ESP SDIO Slave protocol is based on the SDIO Specification s I/O Read/Write
commands, i.e., CMD52 and CMD53. The protocol offers the following services:
• Sending FIFO and receiving FIFO
• 52 8-bit R/W registers shared by host and slave (For details, see ESP32 Technical Reference Manual > SDIO
Slave Controller > Register Summary > SDIO SLC Host registers [PDF]
• 16 general purpose interrupt sources, 8 from host to slave and 8 from slave to host
To begin communication, the host needs to enable the I/O Function 1 in the slave and access its registers as described
below.
Check the code example peripherals/sdio.
The ESP Serial Slave Link component implements the logic of this protocol for ESP32 SDIO Host when communi-
cating with an ESP32 SDIO slave.
Slave register table
32-bit
• 0x044 (TOKEN_RDATA): in which bit 27-16 holds the number of the receiving buffer.
• 0x058 (INT_ST): holds the interrupt source bits from slave to host.
• 0x060 (PKT_LEN): holds the accumulated data length (in bytes) already read by host plus the data copied to
the buffer but yet to be read.
• 0x0D4 (INT_CLR): write 1 to clear interrupt bits corresponding to INT_ST.
• 0x0DC (INT_ENA): mask bits for interrupts from slave to host.
8-bit Shared general purpose registers:

• 0x06C-0x077: R/W registers 0-11 shared by slave and host.
• 0x07A-0x07B: R/W registers 14-15 shared by slave and host.
• 0x07E-0x07F: R/W registers 18-19 shared by slave and host.

• 0x088-0x08B: R/W registers 24-27 shared by slave and host.

• 0x09C-0x0BB: R/W registers 32-63 shared by slave and host.
Interrupt Registers: - 0x08D (SLAVE_INT): bits for host to interrupt slave. auto clear.
FIFO (sending and receiving) 0x090 - 0x1F7FF are reserved for FIFOs.
The address of CMD53 is related to the length requested to read from or write to the slave in a single transfer, as
demonstrated by the equation below:
requested length = 0x1F800-address
The slave will respond with data that has a length equal to the length field of CMD53. In cases where the data is longer
than the requested length, the data will be zero filled (when sending) or discarded (when receiving). This includes
both the block and the byte mode of CMD53.
Note: The function number should be set to 1, OP Code should be set to 1 (for CMD53).
In order to achieve higher efficiency when accessing the FIFO by an arbitrary length, the block and byte modes of
CMD53 can be used in combination. For example, given that the block size is set to 512 by default, you can write/get
1031 bytes of data from the FIFO by doing the following:
1. Send CMD53 in block mode, block count=2 (1024 bytes) to address 0x1F3F9=0x1F800-1031.
2. Then send CMD53 in byte mode, byte count=8 (or 7 if your controller supports that) to address
0x1F7F9=0x1F800-7.
Interrupts SDIO interrupts are level sensitive . For host interrupts, the slave sends an interrupt by pulling the
DAT1 line down at a proper time. The host detects when the interrupt line is pulled down and reads the INT_ST
register to determine the source of the interrupt. After that, the host can clear the interrupt bits by writing the
INT_CLR register and process the interrupt. The host can also mask unneeded sources by clearing the bits in the
INT_ENA register corresponding to the sources. If all the sources are cleared (or masked), the DAT1 line goes
inactive.
On ESP32, the corresponding host_int bits are: bit 0 to bit 7.
For slave interrupts, the host sends a transfer to write the SLAVE_INT register. Once a bit is set to 1, the slave
hardware and the driver will detect it and inform the application.
Receiving FIFO To write to the slave s receiving FIFO, the host should complete the following steps:
1. Read the TOKEN1 field (bits 27-16) of the register TOKEN_RDATA (0x044). The buffer number re-
maining is TOKEN1 minus the number of buffers used by host.
2. Make sure the buffer number is sufficient (buffer_size x buffer_num is greater than the data to write,
buffer_size is pre-defined between the host and the slave before the communication starts). Otherwise, keep
returning to Step 1 until the buffer size is sufficient.
3. Write to the FIFO address with CMD53. Note that the requested length should not exceed the length
calculated at Step 2, and the FIFO address is related to requested length.
4. Calculate used buffers. Note that a partially used buffer at the tail is counted as used.
Sending FIFO To read the slave s sending FIFO, the host should complete the following steps:
1. Wait for the interrupt line to become active (optional, low by default).
2. Read (poll) the interrupt bits in the INT_ST register to monitor if new packets exist.
3. If new packets are ready, read the PKT_LEN register. Before reading the packets, determine the length
of data to be read. As the host keeps the length of data already read from the slave, subtract this value from
PKT_LEN, the result will be the maximum length of data available for reading. If no data has been added to
the sending FIFO yet, wait and poll until the slave is ready and update PKT_LEN.
4. Read from the FIFO using CMD53. Note that the requested length should not be greater than calculated at
Step 3, and the FIFO address is related to requested length.

5. Update the read length.
Warning: The driver for ESP32 hasn t been developed yet.
ESP SPI Slave HD (Half Duplex) Mode Protocol
SPI Slave Capabilities of Espressif chips

ESP32 ESP32-S2 ESP32-C3
SPI Slave HD N Y (v2) Y (v2)
Tohost intr N N
Frhost intr 2* 2*
TX DMA Y Y
RX DMA Y Y
Shared registers 72 64
Introduction In the half duplex mode, the master has to use the protocol defined by the slave to communicate with
the slave. Each transaction may consist of the following phases (list by the order they should exist):
• Command: 8-bit, master to slave
This phase determines the rest phases of the transactions. See Supported Commands.
• Address: 8-bit, master to slave, optional
For some commands (WRBUF, RDBUF), this phase specifies the address of shared buffer to write
to/read from. For other commands with this phase, they are meaningless, but still have to exist in
the transaction.
• Dummy: 8-bit, floating, optional
This phase is the turn around time between the master and the slave on the bus, and also provides
enough time for the slave to prepare the data to send to master.
• Data: variable length, the direction is also determined by the command.
This may be a data OUT phase, in which the direction is slave to master, or a data IN phase, in
which the direction is master to slave.
The direction means which side (master or slave) controls the MOSI, MISO, WP and HD pins.
Data IO Modes In some IO modes, more data wires can be use to send the data. As a result, the SPI clock cycles
required for the same amount of data will be less than in 1-bit mode. For example, in QIO mode, address and data
(IN and OUT) should be sent on all 4 data wires (MOSI, MISO, WP, and HD). Here s the modes supported by
ESP32-S2 SPI slave and the wire number used in corresponding modes.
Mode command WN address WN dummy cycles data WN

1-bit 1 1 1 1
DOUT 1 1 4 2
DIO 1 2 4 2
QOUT 1 1 4 4
QIO 1 4 4 4
QPI 4 4 4 4
Normally, which mode is used is determined is determined by the command sent by the master (See Supported
Commands), except from the QPI mode.
QPI Mode The QPI mode is a special state of the SPI Slave. The master can send ENQPI command to put the
slave into the QPI mode state. In the QPI mode, the command is also sent in 4-bit, thus it s not compatible with
the normal modes. The master should only send QPI commands when the slave is in the QPI mode. To exit form the
QPI mode, master can send EXQPI command.

Supported Commands
Note: The command name are in a master-oriented direction. For example, WRBUF means master writes the
buffer of slave.
Name Description Command Address Data

WRBUF Write buffer 0x01 Buf addr master to slave, no
longer than buffer
size
RDBUF Read buffer 0x02 Buf addr slave to master, no
longer than buffer
size
WRDMA Write DMA 0x03 8 bits master to slave, no
longer than length
provided by slave
RDDMA Read DMA 0x04 8 bits slave to master, no
longer than length
provided by slave
SEG_DONE Segments done 0x05 • •
ENQPI Enter QPI mode 0x06 • •
WR_DONE Write segments 0x07 • •

done
CMD8 Interrupt 0x08 • •
CMD9 Interrupt 0x09 • •
CMDA Interrupt 0x0A • •
EXQPI Exit QPI mode 0xDD • •
Moreover, WRBUF, RDBUF, WRDMA, RDDMA commands have their 2-bit and 4-bit version. To do transactions
in 2-bit or 4-bit mode, send the original command ORed by the corresponding command mask below. For example,
command 0xA1 means WRBUF in QIO mode.
Mode Mask
1-bit 0x00
DOUT 0x10
DIO 0x50
QOUT 0x20
QIO 0xA0
QPI 0xA0
Segment Transaction Mode Segment transaction mode is the only mode supported by the SPI Slave HD driver for
now. In this mode, for a transaction the slave load onto the DMA, the master is allowed to read or write in segments.
This way the master doesn t have to prepare large buffer as the size of data provided by the slave. After the master
finish reading/writing a buffer, it has to send corresponding termination command to the slave as a synchronization
signal. The slave driver will update new data (if exist) onto the DMA upon seeing the termination command.
The termination command is WR_DONE (0x07) for the WRDMA, and CMD8 (0x08) for the RDDMA.
Here s an example for the flow the master read data from the slave DMA:

1. The slave loads 4092 bytes of data onto the RDDMA

2. The master do seven RDDMA transactions, each of them are 512 bytes long, and reads the first 3584 bytes
from the slave
3. The master do the last RDDMA transaction of 512 bytes (equal, longer or shorter than the total length loaded by
the slave are all allowed). The first 508 bytes are valid data from the slave, while the last 4 bytes are meaningless
bytes.
4. The master sends CMD8 to the slave
5. The slave loads another 4092 bytes of data onto the RDDMA
6. The master can start new reading transactions after it sends the CMD8
Terminology
• ESSL: Abbreviation for ESP Serial Slave Link, the component described by this document.
• Master: The device running the esp_serial_slave_link component.
• ESSL device: a virtual device on the master associated with an ESP slave device. The device context has the
knowledge of the slave protocol above the bus, relying on some bus drivers to communicate with the slave.
• ESSL device handle: a handle to ESSL device context containing the configuration, status and data required
by the ESSL component. The context stores the driver configurations, communication state, data shared by
master and slave, etc.
The context should be initialized before it is used, and get deinitialized if not used any more. The master
application operates on the ESSL device through this handle.
• ESP slave: the slave device connected to the bus, which ESSL component is designed to communicate with.
• Bus: The bus over which the master and the slave communicate with each other.
• Slave protocol: The special communication protocol specified by Espressif HW/SW over the bus.
• TX buffer num: a counter, which is on the slave and can be read by the master, indicates the accumulated
buffer numbers that the slave has loaded to the hardware to receive data from the master.
• RX data size: a counter, which is on the slave and can be read by the master, indicates the accumulated data
size that the slave has loaded to the hardware to send to the master.
Services provided by ESP slave
There are some common services provided by the Espressif slaves:

1. Tohost Interrupts: The slave can inform the master about certain events by the interrupt line. (optional)
2. Frhost Interrupts: The master can inform the slave about certain events.
3. Tx FIFO (master to slave): the slave can send data in stream to the master. The SDIO slave can also indicate
it has new data to send to master by the interrupt line.
The slave updates the TX buffer num to inform the master how much data it can receive, and the master then
read the TX buffer num, and take off the used buffer number to know how many buffers are remaining.
4. Rx FIFO (slave to master): the slave can receive data from the master in units of receiving buffers.
The slave updates the RX data size to inform the master how much data it has prepared to send, and then
the master read the data size, and take off the data length it has already received to know how many data is
remaining.
5. Shared registers: the master can read some part of the registers on the slave, and also write these registers to
let the slave read.
The services provided by the slave depends on the slave s model. See SDIO Slave Capabilities of Espressif chips and
SPI Slave Capabilities of Espressif chips for more details.
Initialization of ESP Serial Slave Link
ESP SDIO Slave The ESP SDIO slave link (ESSL SDIO) devices relies on the sdmmc component. It includes the
usage of communicating with ESP SDIO Slave device via SDSPI feature. The ESSL device should be initialized as
below:
1. Initialize a sdmmc card (see :doc:` Document of SDMMC driver </api-reference/storage/sdmmc>`) structure.
2. Call sdmmc_card_init() to initialize the card.

3. Initialize the ESSL device with essl_sdio_config_t. The card member should be the sd-
mmc_card_t got in step 2, and the recv_buffer_size member should be filled correctly according to pre-
negotiated value.
4. Call essl_init() to do initialization of the SDIO part.
5. Call essl_wait_for_ready() to wait for the slave to be ready.
ESP SPI Slave

Note: If you are communicating with the ESP SDIO Slave device through SPI interface, you should use the SDIO
interface instead.
Hasn t been supported yet.
APIs
After the initialization process above is performed, you can call the APIs below to make use of the services provided
by the slave:
Tohost Interrupts (optional)

1. Call essl_get_intr_ena() to know which events will trigger the interrupts to the master.
2. Call essl_set_intr_ena() to set the events that will trigger interrupts to the master.
3. Call essl_wait_int() to wait until interrupt from the slave, or timeout.
4. When interrupt is triggered, call essl_get_intr() to know which events are active, and call
essl_clear_intr() to clear them.
Frhost Interrupts
1. Call essl_send_slave_intr() to trigger general purpose interrupt of the slave.
TX FIFO
1. Call essl_get_tx_buffer_num() to know how many buffers the slave has prepared to receive data
from the master. This is optional. The master will poll tx_buffer_num when it try to send packets to the slave,
until the slave has enough buffer or timeout.
2. Call essl_send_paket() to send data to the slave.
RX FIFO
1. Call essl_get_rx_data_size() to know how many data the slave has prepared to send to the master.
This is optional. When the master tries to receive data from the slave, it will update the rx_data_size for once,
if the current rx_data_size is shorter than the buffer size the master prepared to receive. And it may poll the
rx_data_size if the rx_dat_size keeps 0, until timeout.
2. Call essl_get_packet() to receive data from the slave.
Reset counters (Optional) Call essl_reset_cnt() to reset the internal counter if you find the slave has reset
its counter.
Application Example
The example below shows how ESP32 SDIO host and slave communicate with each other. The host use the ESSL
SDIO.
peripherals/sdio.
Please refer to the specific example README.md for details.

API Reference
Header File
• components/esp_serial_slave_link/include/esp_serial_slave_link/essl.h
Functions
esp_err_t essl_init(essl_handle_t handle, uint32_t wait_ms)
Initialize the slave.
Return
• ESP_OK: If success
• ESP_ERR_NOT_SUPPORTED: Current device does not support this function.
• Other value returned from lower layer init.
Parameters
• handle: Handle of an ESSL device.
• wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.
esp_err_t essl_wait_for_ready(essl_handle_t handle, uint32_t wait_ms)
Wait for interrupt of an ESSL slave device.
Return
• ESP_OK: If success
• One of the error codes from SDMMC host controller
Parameters
esp_err_t essl_get_tx_buffer_num(essl_handle_t handle, uint32_t *out_tx_num, uint32_t wait_ms)
Get buffer num for the host to send data to the slave. The buffers are size of buffer_size.
Return
• ESP_OK: Success
• ESP_ERR_NOT_SUPPORTED: This API is not supported in this mode
• One of the error codes from SDMMC/SPI host controller
Parameters
• handle: Handle of a ESSL device.
• out_tx_num: Output of buffer num that host can send data to ESSL slave.
esp_err_t essl_get_rx_data_size(essl_handle_t handle, uint32_t *out_rx_size, uint32_t wait_ms)
Get the size, in bytes, of the data that the ESSL slave is ready to send
Return
• ESP_OK: Success
Parameters
• out_rx_size: Output of data size to read from slave, in bytes
esp_err_t essl_reset_cnt(essl_handle_t handle)
Reset the counters of this component. Usually you don t need to do this unless you know the slave is reset.
Return
• ESP_OK: Success
• ESP_ERR_INVALID_ARG: Invalid argument, handle is not init.
Parameters

esp_err_t essl_send_packet(essl_handle_t handle, const void *start, size_t length, uint32_t wait_ms)
Send a packet to the ESSL Slave. The Slave receives the packet into buffers whose size is buffer_size
(configured during initialization).
Return
• ESP_OK Success
• ESP_ERR_INVALID_ARG: Invalid argument, handle is not init or other argument is not valid.
• ESP_ERR_TIMEOUT: No buffer to use, or error ftrom SDMMC host controller.
• ESP_ERR_NOT_FOUND: Slave is not ready for receiving.
• One of the error codes from SDMMC/SPI host controller.
Parameters
• start: Start address of the packet to send
• length: Length of data to send, if the packet is over-size, the it will be divided into blocks and
hold into different buffers automatically.
esp_err_t essl_get_packet(essl_handle_t handle, void *out_data, size_t size, size_t *out_length,
uint32_t wait_ms)
Get a packet from ESSL slave.
Return
• ESP_OK Success: All the data has been read from the slave.
• ESP_ERR_INVALID_ARG: Invalid argument, The handle is not initialized or the other arguments
are invalid.
• ESP_ERR_NOT_FINISHED: Read was successful, but there is still data remaining.
• ESP_ERR_NOT_FOUND: Slave is not ready to send data.
• One of the error codes from SDMMC/SPI host controller.
Parameters
• [out] out_data: Data output address
• size: The size of the output buffer, if the buffer is smaller than the size of data to receive from
slave, the driver returns ESP_ERR_NOT_FINISHED
• [out] out_length: Output of length the data actually received from slave.
esp_err_t essl_write_reg(essl_handle_t handle, uint8_t addr, uint8_t value, uint8_t *value_o, uint32_t
wait_ms)
Write general purpose R/W registers (8-bit) of ESSL slave.
Note sdio 28-31 are reserved, the lower API helps to skip.
Return
• ESP_OK Success
Parameters
• addr: Address of register to write. For SDIO, valid address: 0-59. For SPI, see essl_spi.h
• value: Value to write to the register.
• value_o: Output of the returned written value.
esp_err_t essl_read_reg(essl_handle_t handle, uint8_t add, uint8_t *value_o, uint32_t wait_ms)
Read general purpose R/W registers (8-bit) of ESSL slave.
Return
• ESP_OK Success
Parameters
• handle: Handle of a essl device.

• add: Address of register to read. For SDIO, Valid address: 0-27, 32-63 (28-31 reserved, return
interrupt bits on read). For SPI, see essl_spi.h
• value_o: Output value read from the register.
esp_err_t essl_wait_int(essl_handle_t handle, uint32_t wait_ms)
wait for an interrupt of the slave
Return
• ESP_OK: If interrupt is triggered.
• ESP_ERR_TIMEOUT: No interrupts before timeout.
Parameters
esp_err_t essl_clear_intr(essl_handle_t handle, uint32_t intr_mask, uint32_t wait_ms)
Clear interrupt bits of ESSL slave. All the bits set in the mask will be cleared, while other bits will stay the
same.
Return
• ESP_OK: Success
Parameters
• intr_mask: Mask of interrupt bits to clear.
esp_err_t essl_get_intr(essl_handle_t handle, uint32_t *intr_raw, uint32_t *intr_st, uint32_t wait_ms)
Get interrupt bits of ESSL slave.
Return
• ESP_OK: Success
• ESP_INVALID_ARG: If both intr_raw and intr_st are NULL.
Parameters
• intr_raw: Output of the raw interrupt bits. Set to NULL if only masked bits are read.
• intr_st: Output of the masked interrupt bits. set to NULL if only raw bits are read.
esp_err_t essl_set_intr_ena(essl_handle_t handle, uint32_t ena_mask, uint32_t wait_ms)
Set interrupt enable bits of ESSL slave. The slave only sends interrupt on the line when there is a bit both the
raw status and the enable are set.
Return
• ESP_OK: Success
Parameters
• ena_mask: Mask of the interrupt bits to enable.
esp_err_t essl_get_intr_ena(essl_handle_t handle, uint32_t *ena_mask_o, uint32_t wait_ms)
Get interrupt enable bits of ESSL slave.
Return
• ESP_OK Success
Parameters


• ena_mask_o: Output of interrupt bit enable mask.
esp_err_t essl_send_slave_intr(essl_handle_t handle, uint32_t intr_mask, uint32_t wait_ms)
Send interrupts to slave. Each bit of the interrupt will be triggered.
Return
• ESP_OK: Success
Parameters
• intr_mask: Mask of interrupt bits to send to slave.
Type Definitions
typedef struct essl_dev_t *essl_handle_t
Handle of an ESSL device.
Header File
• components/esp_serial_slave_link/include/esp_serial_slave_link/essl_sdio.h
Functions
esp_err_t essl_sdio_init_dev(essl_handle_t *out_handle, const essl_sdio_config_t *config)
Initialize the ESSL SDIO device and get its handle.
Return
• ESP_OK: on success
• ESP_ERR_NO_MEM: memory exhausted.
Parameters
• out_handle: Output of the handle.
• config: Configuration for the ESSL SDIO device.
esp_err_t essl_sdio_deinit_dev(essl_handle_t handle)
Deinitialize and free the space used by the ESSL SDIO device.
Return
• ESP_ERR_INVALID_ARG: wrong handle passed
Parameters
• handle: Handle of the ESSL SDIO device to deinit.
Structures
struct essl_sdio_config_t
Configuration for the ESSL SDIO device.
Public Members
sdmmc_card_t *card
The initialized sdmmc card pointer of the slave.
int recv_buffer_size
The pre-negotiated recv buffer size used by both the host and the slave.

Header File
• components/esp_serial_slave_link/include/esp_serial_slave_link/essl_spi.h
Functions
esp_err_t essl_spi_init_dev(essl_handle_t *out_handle, const essl_spi_config_t *init_config)
Initialize the ESSL SPI device function list and get its handle.
Return
• ESP_OK: On success
• ESP_ERR_NO_MEM: Memory exhausted
• ESP_ERR_INVALID_STATE: SPI driver is not initialized
• ESP_ERR_INVALID_ARG: Wrong register ID
Parameters
• [out] out_handle: Output of the handle
• init_config: Configuration for the ESSL SPI device
esp_err_t essl_spi_deinit_dev(essl_handle_t handle)
Deinitialize the ESSL SPI device and free the memory used by the device.
Return
• ESP_OK: On success
• ESP_ERR_INVALID_STATE: ESSL SPI is not in use
Parameters
• handle: Handle of the ESSL SPI device
esp_err_t essl_spi_read_reg(void *arg, uint8_t addr, uint8_t *out_value, uint32_t wait_ms)
Read from the shared registers.
Note The registers for Master/Slave synchronization are reserved. Do not use them. (see rx_sync_reg in
essl_spi_config_t)
Return
• ESP_OK: success
• ESP_ERR_INVALID_STATE: ESSL SPI has not been initialized.
• ESP_ERR_INVALID_ARG: The address argument is not valid. See note 1.
• or other return value from :cpp:func:spi_device_transmit.
Parameters
• arg: Context of the component. (Member arg from essl_handle_t)
• addr: Address of the shared registers. (Valid: 0 ~ SOC_SPI_MAXIMUM_BUFFER_SIZE, reg-
isters for M/S sync are reserved, see note1).
• [out] out_value: Read buffer for the shared registers.
• wait_ms: Time to wait before timeout (reserved for future use, user should set this to 0).
esp_err_t essl_spi_get_packet(void *arg, void *out_data, size_t size, uint32_t wait_ms)
Get a packet from Slave.
Return
•
ESP_OK: On Success
•
ESP_ERR_INVALID_STATE: ESSL SPI has not been initialized.
•
ESP_ERR_INVALID_ARG: The output data address is neither DMA capable nor 4 byte-aligned
•
ESP_ERR_INVALID_SIZE: Master requires size bytes of data but Slave did not load enough
bytes.
Parameters
• [out] out_data: Output data address
• size: The size of the output data.
esp_err_t essl_spi_write_reg(void *arg, uint8_t addr, uint8_t value, uint8_t *out_value, uint32_t
wait_ms)
Write to the shared registers.

Note The registers for Master/Slave synchronization are reserved. Do not use them. (see tx_sync_reg in
essl_spi_config_t)
Note Feature of checking the actual written value (out_value) is not supported.
Return
• ESP_OK: success
• ESP_ERR_INVALID_STATE: ESSL SPI has not been initialized.
• ESP_ERR_INVALID_ARG: The address argument is not valid. See note 1.
• ESP_ERR_NOT_SUPPORTED: Should set out_value to NULL. See note 2.
Parameters
• addr: Address of the shared registers. (Valid: 0 ~ SOC_SPI_MAXIMUM_BUFFER_SIZE, reg-
isters for M/S sync are reserved, see note1)
• value: Buffer for data to send, should be align to 4.
• [out] out_value: Not supported, should be set to NULL.
esp_err_t essl_spi_send_packet(void *arg, const void *data, size_t size, uint32_t wait_ms)
Send a packet to Slave.
Return
•
ESP_OK: On success
•
ESP_ERR_INVALID_STATE: ESSL SPI has not been initialized.
•
ESP_ERR_INVALID_ARG: The data address is not DMA capable
•
ESP_ERR_INVALID_SIZE: Master will send size bytes of data but Slave did not load enough
RX buffer
Parameters
• data: Address of the data to send
• size: Size of the data to send.
void essl_spi_reset_cnt(void *arg)
Reset the counter in Master context.
Note Shall only be called if the slave has reset its counter. Else, Slave and Master would be desynchronized
Parameters
esp_err_t essl_spi_rdbuf(spi_device_handle_t spi, uint8_t *out_data, int addr, int len, uint32_t flags)
Read the shared buffer from the slave in ISR way.
Note The slave s HW doesn t guarantee the data in one SPI transaction is consistent. It sends data in unit of
byte. In other words, if the slave SW attempts to update the shared register when a rdbuf SPI transaction
is in-flight, the data got by the master will be the combination of bytes of different writes of slave SW.
Note out_data should be prepared in words and in the DRAM. The buffer may be written in words by the
DMA. When a byte is written, the remaining bytes in the same word will also be overwritten, even the
len is shorter than a word.
Return
Parameters
• spi: SPI device handle representing the slave
• [out] out_data: Buffer for read data, strongly suggested to be in the DRAM and aligned to 4
• addr: Address of the slave shared buffer
• len: Length to read
• flags: SPI_TRANS_* flags to control the transaction mode of the transaction to send.
esp_err_t essl_spi_rdbuf_polling(spi_device_handle_t spi, uint8_t *out_data, int addr, int len,
uint32_t flags)
Read the shared buffer from the slave in polling way.

Return
Parameters
• [out] out_data: Buffer for read data, strongly suggested to be in the DRAM and aligned to 4
• addr: Address of the slave shared buffer
• len: Length to read
esp_err_t essl_spi_wrbuf(spi_device_handle_t spi, const uint8_t *data, int addr, int len, uint32_t
flags)
Write the shared buffer of the slave in ISR way.
Return
• ESP_OK: success
Parameters
• data: Buffer for data to send, strongly suggested to be in the DRAM
• addr: Address of the slave shared buffer,
• len: Length to write
esp_err_t essl_spi_wrbuf_polling(spi_device_handle_t spi, const uint8_t *data, int addr, int len,
uint32_t flags)
Write the shared buffer of the slave in polling way.
Return
• ESP_OK: success
• or other return value from :cpp:func:spi_device_polling_transmit.
Parameters
• addr: Address of the slave shared buffer,
• len: Length to write
esp_err_t essl_spi_rddma(spi_device_handle_t spi, uint8_t *out_data, int len, int seg_len, uint32_t
flags)
Receive long buffer in segments from the slave through its DMA.
Note This function combines several :cpp:func:essl_spi_rddma_seg and one
:cpp:func:essl_spi_rddma_done at the end. Used when the slave is working in segment
mode.
Return
• ESP_OK: success
Parameters
• [out] out_data: Buffer to hold the received data, strongly suggested to be in the DRAM and
aligned to 4
• len: Total length of data to receive.

• seg_len: Length of each segment, which is not larger than the maximum transaction length al-
lowed for the spi device. Suggested to be multiples of 4. When set < 0, means send all data in one
segment (the rddma_done will still be sent.)
esp_err_t essl_spi_rddma_seg(spi_device_handle_t spi, uint8_t *out_data, int seg_len, uint32_t flags)
Read one data segment from the slave through its DMA.
Note To read long buffer, call :cpp:func:essl_spi_rddma instead.
Return
• ESP_OK: success
Parameters
• [out] out_data: Buffer to hold the received data. strongly suggested to be in the DRAM and
aligned to 4
• seg_len: Length of this segment
esp_err_t essl_spi_rddma_done(spi_device_handle_t spi, uint32_t flags)
Send the rddma_done command to the slave. Upon receiving this command, the slave will stop sending the
current buffer even there are data unsent, and maybe prepare the next buffer to send.
Note This is required only when the slave is working in segment mode.
Return
• ESP_OK: success
Parameters
esp_err_t essl_spi_wrdma(spi_device_handle_t spi, const uint8_t *data, int len, int seg_len, uint32_t
flags)
Send long buffer in segments to the slave through its DMA.
Note This function combines several :cpp:func:essl_spi_wrdma_seg and one
:cpp:func:essl_spi_wrdma_done at the end. Used when the slave is working in segment
mode.
Return
• ESP_OK: success
Parameters
• len: Total length of data to send.
• seg_len: Length of each segment, which is not larger than the maximum transaction length al-
lowed for the spi device. Suggested to be multiples of 4. When set < 0, means send all data in one
segment (the wrdma_done will still be sent.)
esp_err_t essl_spi_wrdma_seg(spi_device_handle_t spi, const uint8_t *data, int seg_len, uint32_t
flags)
Send one data segment to the slave through its DMA.
Note To send long buffer, call :cpp:func:essl_spi_wrdma instead.
Return
• ESP_OK: success
Parameters
• seg_len: Length of this segment

esp_err_t essl_spi_wrdma_done(spi_device_handle_t spi, uint32_t flags)
Send the wrdma_done command to the slave. Upon receiving this command, the slave will stop receiving,
process the received data, and maybe prepare the next buffer to receive.
Note This is required only when the slave is working in segment mode.
Return
• ESP_OK: success
Parameters
Structures
struct essl_spi_config_t
Configuration of ESSL SPI device.
Public Members
spi_device_handle_t *spi
Pointer to SPI device handle.
uint32_t tx_buf_size
The pre-negotiated Master TX buffer size used by both the host and the slave.
uint8_t tx_sync_reg
The pre-negotiated register ID for Master-TX-SLAVE-RX synchronization. 1 word (4 Bytes) will be
reserved for the synchronization.
uint8_t rx_sync_reg
The pre-negotiated register ID for Master-RX-Slave-TX synchronization. 1 word (4 Bytes) will be re-
served for the synchronization.
2.4.14 ESP x509 Certificate Bundle
Overview
The ESP x509 Certificate Bundle API provides an easy way to include a bundle of custom x509 root certificates for
TLS server verification.
Note: The bundle is currently not available when using WolfSSL.
The bundle comes with the complete list of root certificates from Mozilla s NSS root certificate store. Using the
gen_crt_bundle.py python utility the certificates subject name and public key are stored in a file and embedded in
the ESP32 binary.
When generating the bundle you may choose between:
• The full root certificate bundle from Mozilla, containing more than 130 certificates. The current bundle was
updated Tue Oct 5 09:35:35 2021 GMT.
• A pre-selected filter list of the name of the most commonly used root certificates, reducing the amount of
certificates to around 35 while still having around 90 % coverage according to market share statistics.
In addition it is possible to specify a path to a certificate file or a directory containing certificates which then will be
added to the generated bundle.

Note: Trusting all root certificates means the list will have to be updated if any of the certificates are retracted. This
includes removing them from cacrt_all.pem.
Configuration
Most configuration is done through menuconfig. CMake will generate the bundle according to the configuration and
embed it.
• CONFIG_MBEDTLS_CERTIFICATE_BUNDLE: automatically build and attach the bundle.
• CONFIG_MBEDTLS_DEFAULT_CERTIFICATE_BUNDLE: decide which certificates to include from the com-
plete root list.
• CONFIG_MBEDTLS_CUSTOM_CERTIFICATE_BUNDLE_PATH: specify the path of any additional certifi-
cates to embed in the bundle.
To enable the bundle when using ESP-TLS simply pass the function pointer to the bundle attach function:
esp_tls_cfg_t cfg = {
.crt_bundle_attach = esp_crt_bundle_attach,
};
This is done to avoid embedding the certificate bundle unless activated by the user.
If using mbedTLS directly then the bundle may be activated by directly calling the attach function during the setup
process:
mbedtls_ssl_config conf;
mbedtls_ssl_config_init(&conf);
esp_crt_bundle_attach(&conf);
Generating the List of Root Certificates
The list of root certificates comes from Mozilla s NSS root certificate store, which can be found here The list can
be downloaded and created by running the script mk-ca-bundle.pl that is distributed as a part of curl. Another
alternative would be to download the finished list directly from the curl website: CA certificates extracted from
Mozilla
The common certificates bundle were made by selecting the authorities with a market share of more than 1 % from
w3tech s SSL Survey. These authorities were then used to pick the names of the certificates for the filter list,
cmn_crt_authorities.csv, from this list provided by Mozilla.
Updating the Certificate Bundle
The bundle is embedded into the app and can be updated along with the app by an OTA update. If you want to include
a more up-to-date bundle than the bundle currently included in IDF, then the certificate list can be downloaded from
Mozilla as described in Updating the Certificate Bundle.
Application Example
Simple HTTPS example that uses ESP-TLS to establish a secure socket connection using the certificate bundle with
two custom certificates added for verification: protocols/https_x509_bundle.
HTTPS example that uses ESP-TLS and the default bundle: protocols/https_request.
HTTPS example that uses mbedTLS and the default bundle: protocols/https_mbedtls.

API Reference
Header File
• components/mbedtls/esp_crt_bundle/include/esp_crt_bundle.h
Functions
esp_err_t esp_crt_bundle_attach(void *conf)
Attach and enable use of a bundle for certificate verification.
Attach and enable use of a bundle for certificate verification through a verification callback. If no specific bundle
has been set through esp_crt_bundle_set() it will default to the bundle defined in menuconfig and embedded in
the binary.
Return
• ESP_OK if adding certificates was successful.
• Other if an error occured or an action must be taken by the calling process.
Parameters
• [in] conf: The config struct for the SSL connection.
void esp_crt_bundle_detach(mbedtls_ssl_config *conf)
Disable and dealloc the certification bundle.
Removes the certificate verification callback and deallocates used resources
Parameters
• [in] conf: The config struct for the SSL connection.
void esp_crt_bundle_set(const uint8_t *x509_bundle)
Set the default certificate bundle used for verification.
Overrides the default certificate bundle. In most use cases the bundle should be set through menuconfig. The
bundle needs to be sorted by subject name since binary search is used to find certificates.
Parameters
• [in] x509_bundle: A pointer to the certificate bundle.
Code examples for this API section are provided in the protocols directory of ESP-IDF examples.
2.4.15 IP Network Layer
Documentation for IP Network Layer protocols (below the Application Protocol layer) are provided in Networking
APIs.
2.5 Provisioning API
2.5.1 Protocol Communication
Overview
Protocol Communication (protocomm) component manages secure sessions and provides framework for multiple
transports. The application can also use protocomm layer directly to have application specific extensions for the
provisioning (or non-provisioning) use cases.
Following features are available for provisioning :
• Communication security at application level -
– protocomm_security0 (no security)
– protocomm_security1 (curve25519 key exchange + AES-CTR encryption)
• Proof-of-possession (support with protocomm_security1 only)

Protocomm internally uses protobuf (protocol buffers) for secure session establishment. Though users can implement
their own security (even without using protobuf). One can even use protocomm without any security layer.
Protocomm provides framework for various transports - WiFi (SoftAP+HTTPD), BLE, console - in which case the
handler invocation is automatically taken care of on the device side (see Transport Examples below for code snippets).
Note that the client still needs to establish session (only for protocomm_security1) by performing the two way hand-
shake. See Unified Provisioning for more details about the secure handshake logic.
Transport Example (SoftAP + HTTP) with Security 1
For complete example see provisioning/legacy/softap_prov

/* Endpoint handler to be registered with protocomm.
* This simply echoes back the received data. */
esp_err_t echo_req_handler (uint32_t session_id,
const uint8_t *inbuf, ssize_t inlen,
uint8_t **outbuf, ssize_t *outlen,
void *priv_data)
{
/* Session ID may be used for persistence */
printf("Session ID : %d", session_id);
/* Echo back the received data */

*outlen = inlen; /* Output data length updated */
*outbuf = malloc(inlen); /* This will be deallocated outside */
memcpy(*outbuf, inbuf, inlen);
/* Private data that was passed at the time of endpoint creation */

uint32_t *priv = (uint32_t *) priv_data;
if (priv) {
printf("Private data : %d", *priv);
}
return ESP_OK;
}
/* Example function for launching a protocomm instance over HTTP */

protocomm_t *start_pc(const char *pop_string)
{
protocomm_t *pc = protocomm_new();
/* Config for protocomm_httpd_start() */

protocomm_httpd_config_t pc_config = {
.data = {
.config = PROTOCOMM_HTTPD_DEFAULT_CONFIG()
}
};
/* Start protocomm server on top of HTTP */

protocomm_httpd_start(pc, &pc_config);
/* Create Proof of Possession object from pop_string. It must be valid

* throughout the scope of protocomm endpoint. This need not be␣
,→static,
* ie. could be dynamically allocated and freed at the time of␣

,→endpoint
* removal */
const static protocomm_security_pop_t pop_obj = {
.data = (const uint8_t *) strdup(pop_string),
.len = strlen(pop_string)


};
/* Set security for communication at application level. Just like for

* request handlers, setting security creates an endpoint and␣
,→registers
* the handler provided by protocomm_security1. One can similarly use

* protocomm_security0. Only one type of security can be set for a
* protocomm instance at a time. */
protocomm_set_security(pc, "security_endpoint", &protocomm_security1,␣
,→&pop_obj);
/* Private data passed to the endpoint must be valid throughout the␣

,→scope
* of protocomm endpoint. This need not be static, ie. could be␣
,→dynamically
* allocated and freed at the time of endpoint removal */

static uint32_t priv_data = 1234;
/* Add a new endpoint for the protocomm instance, identified by a␣

,→ unique name
* and register a handler function along with private data to be␣
,→passed at the
* time of handler execution. Multiple endpoints can be added as long␣

,→as they
* are identified by unique names */

protocomm_add_endpoint(pc, "echo_req_endpoint",
echo_req_handler, (void *) &priv_data);
return pc;
}
/* Example function for stopping a protocomm instance */

void stop_pc(protocomm_t *pc)
{
/* Remove endpoint identified by it's unique name */
protocomm_remove_endpoint(pc, "echo_req_endpoint");
/* Remove security endpoint identified by it's name */

protocomm_unset_security(pc, "security_endpoint");
/* Stop HTTP server */

protocomm_httpd_stop(pc);
/* Delete (deallocate) the protocomm instance */

protocomm_delete(pc);
}
Transport Example (BLE) with Security 0
For complete example see provisioning/legacy/ble_prov

/* Example function for launching a secure protocomm instance over BLE */
protocomm_t *start_pc()
{
protocomm_t *pc = protocomm_new();
/* Endpoint UUIDs */
protocomm_ble_name_uuid_t nu_lookup_table[] = {
{"security_endpoint", 0xFF51},
{"echo_req_endpoint", 0xFF52}
};

/* Config for protocomm_ble_start() */

protocomm_ble_config_t config = {
.service_uuid = {
/* LSB <---------------------------------------
* ---------------------------------------> MSB */
0xfb, 0x34, 0x9b, 0x5f, 0x80, 0x00, 0x00, 0x80,
0x00, 0x10, 0x00, 0x00, 0xFF, 0xFF, 0x00, 0x00,
},
.nu_lookup_count = sizeof(nu_lookup_table)/sizeof(nu_lookup_
,→table[0]),
.nu_lookup = nu_lookup_table
};
/* Start protocomm layer on top of BLE */

protocomm_ble_start(pc, &config);
/* For protocomm_security0, Proof of Possession is not used, and can␣

,→ be kept NULL */
protocomm_set_security(pc, "security_endpoint", &protocomm_security0,␣
,→NULL);
protocomm_add_endpoint(pc, "echo_req_endpoint", echo_req_handler,␣

,→NULL);
return pc;
}
/* Example function for stopping a protocomm instance */

void stop_pc(protocomm_t *pc)
{
protocomm_remove_endpoint(pc, "echo_req_endpoint");
protocomm_unset_security(pc, "security_endpoint");
/* Stop BLE protocomm service */

protocomm_ble_stop(pc);
protocomm_delete(pc);
}
API Reference
Header File
• components/protocomm/include/common/protocomm.h
Functions
protocomm_t *protocomm_new(void)
Create a new protocomm instance.
This API will return a new dynamically allocated protocomm instance with all elements of the protocomm_t
structure initialized to NULL.
Return
• protocomm_t* : On success
• NULL : No memory for allocating new instance
void protocomm_delete(protocomm_t *pc)
Delete a protocomm instance.
This API will deallocate a protocomm instance that was created using protocomm_new().
Parameters

• [in] pc: Pointer to the protocomm instance to be deleted

esp_err_t protocomm_add_endpoint(protocomm_t *pc, const char *ep_name, proto-
comm_req_handler_t h, void *priv_data)
Add endpoint request handler for a protocomm instance.
This API will bind an endpoint handler function to the specified endpoint name, along with any private data
that needs to be pass to the handler at the time of call.
Note
• An endpoint must be bound to a valid protocomm instance, created using protocomm_new().
• This function internally calls the registered add_endpoint() function of the selected transport
which is a member of the protocomm_t instance structure.
Return
• ESP_FAIL : Error adding endpoint / Endpoint with this name already exists
• ESP_ERR_NO_MEM : Error allocating endpoint resource
• ESP_ERR_INVALID_ARG : Null instance/name/handler arguments
Parameters
• [in] pc: Pointer to the protocomm instance
• [in] ep_name: Endpoint identifier(name) string
• [in] h: Endpoint handler function
• [in] priv_data: Pointer to private data to be passed as a parameter to the handler function on
call. Pass NULL if not needed.
esp_err_t protocomm_remove_endpoint(protocomm_t *pc, const char *ep_name)
Remove endpoint request handler for a protocomm instance.
This API will remove a registered endpoint handler identified by an endpoint name.
Note
• This function internally calls the registered remove_endpoint() function which is a member
of the protocomm_t instance structure.
Return
• ESP_ERR_NOT_FOUND : Endpoint with specified name doesn t exist
• ESP_ERR_INVALID_ARG : Null instance/name arguments
Parameters
esp_err_t protocomm_open_session(protocomm_t *pc, uint32_t session_id)
Allocates internal resources for new transport session.
Note
Return
• ESP_OK : Request handled successfully
• ESP_ERR_NO_MEM : Error allocating internal resource
Parameters
• [in] session_id: Unique ID for a communication session
esp_err_t protocomm_close_session(protocomm_t *pc, uint32_t session_id)
Frees internal resources used by a transport session.
Note
Return
Parameters


esp_err_t protocomm_req_handle(protocomm_t *pc, const char *ep_name, uint32_t session_id,
const uint8_t *inbuf, ssize_t inlen, uint8_t **outbuf, ssize_t
*outlen)
Calls the registered handler of an endpoint session for processing incoming data and generating the response.
Note
• Resulting output buffer must be deallocated by the caller.
Return
• ESP_FAIL : Internal error in execution of registered handler
• ESP_ERR_NO_MEM : Error allocating internal resource
Parameters
• [in] inbuf: Input buffer contains input request data which is to be processed by the registered
handler
• [in] inlen: Length of the input buffer
• [out] outbuf: Pointer to internally allocated output buffer, where the resulting response data
output from the registered handler is to be stored
• [out] outlen: Buffer length of the allocated output buffer
esp_err_t protocomm_set_security(protocomm_t *pc, const char *ep_name, const pro-
tocomm_security_t *sec, const protocomm_security_pop_t
*pop)
Add endpoint security for a protocomm instance.
This API will bind a security session establisher to the specified endpoint name, along with any proof of
possession that may be required for authenticating a session client.
Note
• The choice of security can be any protocomm_security_t instance. Choices proto-
comm_security0 and protocomm_security1 are readily available.
Return
• ESP_ERR_INVALID_STATE : Security endpoint already set
Parameters
• [in] sec: Pointer to endpoint security instance
• [in] pop: Pointer to proof of possession for authenticating a client
esp_err_t protocomm_unset_security(protocomm_t *pc, const char *ep_name)
Remove endpoint security for a protocomm instance.
This API will remove a registered security endpoint identified by an endpoint name.
Return
Parameters


esp_err_t protocomm_set_version(protocomm_t *pc, const char *ep_name, const char *version)
Set endpoint for version verification.
This API can be used for setting an application specific protocol version which can be verified by clients through
the endpoint.
Note
Return
• ESP_ERR_INVALID_STATE : Version endpoint already set
Parameters
• [in] version: Version identifier(name) string
esp_err_t protocomm_unset_version(protocomm_t *pc, const char *ep_name)
Remove version verification endpoint from a protocomm instance.
This API will remove a registered version endpoint identified by an endpoint name.
Return
Parameters
Type Definitions
typedef esp_err_t (*protocomm_req_handler_t)(uint32_t session_id, const uint8_t *inbuf,
ssize_t inlen, uint8_t **outbuf, ssize_t *outlen,
void *priv_data)
Function prototype for protocomm endpoint handler.
typedef struct protocomm protocomm_t
This structure corresponds to a unique instance of protocomm returned when the API protocomm_new()
is called. The remaining Protocomm APIs require this object as the first parameter.
Note Structure of the protocomm object is kept private
Header File
• components/protocomm/include/security/protocomm_security.h
Structures
struct protocomm_security_pop
Proof Of Possession for authenticating a secure session.
Public Members
const uint8_t *data

Pointer to buffer containing the proof of possession data

uint16_t len
Length (in bytes) of the proof of possession data
struct protocomm_security
Protocomm security object structure.
The member functions are used for implementing secure protocomm sessions.
Note This structure should not have any dynamic members to allow re-entrancy
Public Members
int ver
Unique version number of security implementation
esp_err_t (*init)(protocomm_security_handle_t *handle)
Function for initializing/allocating security infrastructure
esp_err_t (*cleanup)(protocomm_security_handle_t handle)
Function for deallocating security infrastructure
esp_err_t (*new_transport_session)(protocomm_security_handle_t handle, uint32_t ses-
sion_id)
Starts new secure transport session with specified ID
esp_err_t (*close_transport_session)(protocomm_security_handle_t handle, uint32_t ses-
sion_id)
Closes a secure transport session with specified ID
esp_err_t (*security_req_handler)(protocomm_security_handle_t handle, const proto-
comm_security_pop_t *pop, uint32_t session_id, const
uint8_t *inbuf, ssize_t inlen, uint8_t **outbuf, ssize_t
*outlen, void *priv_data)
Handler function for authenticating connection request and establishing secure session
esp_err_t (*encrypt)(protocomm_security_handle_t handle, uint32_t session_id, const uint8_t *in-
buf, ssize_t inlen, uint8_t *outbuf, ssize_t *outlen)
Function which implements the encryption algorithm
esp_err_t (*decrypt)(protocomm_security_handle_t handle, uint32_t session_id, const uint8_t *in-
buf, ssize_t inlen, uint8_t *outbuf, ssize_t *outlen)
Function which implements the decryption algorithm
Type Definitions
typedef struct protocomm_security_pop protocomm_security_pop_t
Proof Of Possession for authenticating a secure session.
typedef void *protocomm_security_handle_t
typedef struct protocomm_security protocomm_security_t
Protocomm security object structure.
The member functions are used for implementing secure protocomm sessions.
Note This structure should not have any dynamic members to allow re-entrancy
Header File
• components/protocomm/include/security/protocomm_security0.h
Header File
• components/protocomm/include/security/protocomm_security1.h

Header File
• components/protocomm/include/transports/protocomm_httpd.h
Functions
esp_err_t protocomm_httpd_start(protocomm_t *pc, const protocomm_httpd_config_t *config)
Start HTTPD protocomm transport.
This API internally creates a framework to allow endpoint registration and security configuration for the pro-
tocomm.
Note This is a singleton. ie. Protocomm can have multiple instances, but only one instance can be bound to
an HTTP transport layer.
Return
• ESP_ERR_NOT_SUPPORTED : Transport layer bound to another protocomm instance
• ESP_ERR_INVALID_STATE : Transport layer already bound to this protocomm instance
• ESP_ERR_NO_MEM : Memory allocation for server resource failed
• ESP_ERR_HTTPD_* : HTTP server error on start
Parameters
• [in] pc: Protocomm instance pointer obtained from protocomm_new()
• [in] config: Pointer to config structure for initializing HTTP server
esp_err_t protocomm_httpd_stop(protocomm_t *pc)
Stop HTTPD protocomm transport.
This API cleans up the HTTPD transport protocomm and frees all the handlers registered with the protocomm.
Return
• ESP_ERR_INVALID_ARG : Null / incorrect protocomm instance pointer
Parameters
• [in] pc: Same protocomm instance that was passed to protocomm_httpd_start()
Unions
union protocomm_httpd_config_data_t
#include <protocomm_httpd.h> Protocomm HTTPD Configuration Data
Public Members
void *handle
HTTP Server Handle, if ext_handle_provided is set to true
protocomm_http_server_config_t config
HTTP Server Configuration, if a server is not already active
Structures
struct protocomm_http_server_config_t
Config parameters for protocomm HTTP server.
Public Members
uint16_t port
Port on which the HTTP server will listen
size_t stack_size
Stack size of server task, adjusted depending upon stack usage of endpoint handler

unsigned task_priority
Priority of server task
struct protocomm_httpd_config_t
Config parameters for protocomm HTTP server.
Public Members
bool ext_handle_provided
Flag to indicate of an external HTTP Server Handle has been provided. In such as case, protocomm will
use the same HTTP Server and not start a new one internally.
protocomm_httpd_config_data_t data
Protocomm HTTPD Configuration Data
Macros
PROTOCOMM_HTTPD_DEFAULT_CONFIG()
Header File
• components/protocomm/include/transports/protocomm_ble.h
Functions
esp_err_t protocomm_ble_start(protocomm_t *pc, const protocomm_ble_config_t *config)
Start Bluetooth Low Energy based transport layer for provisioning.
Initialize and start required BLE service for provisioning. This includes the initialization for characteris-
tics/service for BLE.
Return
• ESP_FAIL : Simple BLE start error
• ESP_ERR_NO_MEM : Error allocating memory for internal resources
• ESP_ERR_INVALID_STATE : Error in ble config
Parameters
• [in] pc: Protocomm instance pointer obtained from protocomm_new()
• [in] config: Pointer to config structure for initializing BLE
esp_err_t protocomm_ble_stop(protocomm_t *pc)
Stop Bluetooth Low Energy based transport layer for provisioning.
Stops service/task responsible for BLE based interactions for provisioning
Note You might want to optionally reclaim memory from Bluetooth. Refer to the documentation of
esp_bt_mem_release in that case.
Return
• ESP_FAIL : Simple BLE stop error
• ESP_ERR_INVALID_ARG : Null / incorrect protocomm instance
Parameters
• [in] pc: Same protocomm instance that was passed to protocomm_ble_start()
Structures
struct name_uuid
This structure maps handler required by protocomm layer to UUIDs which are used to uniquely identify BLE
characteristics from a smartphone or a similar client device.

Public Members
const char *name

Name of the handler, which is passed to protocomm layer
uint16_t uuid
UUID to be assigned to the BLE characteristic which is mapped to the handler
struct protocomm_ble_config
Config parameters for protocomm BLE service.
Public Members
char device_name[MAX_BLE_DEVNAME_LEN]
BLE device name being broadcast at the time of provisioning
uint8_t service_uuid[BLE_UUID128_VAL_LENGTH]
128 bit UUID of the provisioning service
uint8_t *manufacturer_data
BLE device manufacturer data pointer in advertisement
ssize_t manufacturer_data_len
BLE device manufacturer data length in advertisement
ssize_t nu_lookup_count
Number of entries in the Name-UUID lookup table
protocomm_ble_name_uuid_t *nu_lookup
Pointer to the Name-UUID lookup table
Macros
MAX_BLE_DEVNAME_LEN
BLE device name cannot be larger than this value 31 bytes (max scan response size) - 1 byte (length) - 1 byte
(type) = 29 bytes
BLE_UUID128_VAL_LENGTH
MAX_BLE_MANUFACTURER_DATA_LEN
Theoretically, the limit for max manufacturer length remains same as BLE device name i.e. 31 bytes (max
scan response size) - 1 byte (length) - 1 byte (type) = 29 bytes However, manufacturer data goes along with
BLE device name in scan response. So, it is important to understand the actual length should be smaller than
(29 - (BLE device name length) - 2).
Type Definitions
typedef struct name_uuid protocomm_ble_name_uuid_t
This structure maps handler required by protocomm layer to UUIDs which are used to uniquely identify BLE
characteristics from a smartphone or a similar client device.
typedef struct protocomm_ble_config protocomm_ble_config_t
Config parameters for protocomm BLE service.
2.5.2 Unified Provisioning
Overview
Unified provisioning support in the ESP-IDF provides an extensible mechanism to the developers to configure the
device with the Wi-Fi credentials and/or other custom configuration using various transports and different security
schemes. Depending on the use-case it provides a complete and ready solution for Wi-Fi network provisioning
along with example iOS and Android applications. Or developers can extend the device-side and phone-app side
implementations to accommodate their requirements for sending additional configuration data. Following are the
important features of this implementation.

1. Extensible Protocol: The protocol is completely flexible and it offers the ability for the developers to send custom
configuration in the provisioning process. The data representation too is left to the application to decide.
2. Transport Flexibility: The protocol can work on Wi-Fi (SoftAP + HTTP server) or on BLE as a transport
protocol. The framework provides an ability to add support for any other transport easily as long as command-
response behaviour can be supported on the transport.
3. Security Scheme Flexibility: It s understood that each use-case may require different security scheme to secure
the data that is exchanged in the provisioning process. Some applications may work with SoftAP that s WPA2
protected or BLE with just-works security. Or the applications may consider the transport to be insecure
and may want application level security. The unified provisioning framework allows application to choose the
security as deemed suitable.
4. Compact Data Representation: The protocol uses Google Protobufs as a data representation for session setup
and Wi-Fi provisioning. They provide a compact data representation and ability to parse the data in multiple
programming languages in native format. Please note that this data representation is not forced on application
specific data and the developers may choose the representation of their choice.
Typical Provisioning Process
Deciding on Transport
Unified provisioning subsystem supports Wi-Fi (SoftAP+HTTP server) and BLE (GATT based) transport schemes.
Following points need to be considered while selecting the best possible transport for provisioning.
1. BLE based transport has an advantage that in the provisioning process, the BLE communication channel stays
intact between the device and the client. That provides reliable provisioning feedback.
2. BLE based provisioning implementation makes the user-experience better from the phone apps as on Android
and iOS both, the phone app can discover and connect to the device without requiring user to go out of the
phone app
3. BLE transport however consumes ~110KB memory at runtime. If the product does not use the BLE or BT
functionality after provisioning is done, almost all the memory can be reclaimed back and can be added into
the heap.
4. SoftAP based transport is highly interoperable; however as the same radio is shared between SoftAP and Station
interface, the transport is not reliable in the phase when the Wi-Fi connection to external AP is attempted. Also,
the client may roam back to different network when the SoftAP changes the channel at the time of Station
connection.
5. SoftAP transport does not require much additional memory for the Wi-Fi use-cases
6. SoftAP based provisioning requires the phone app user to go to System Settings to connect to Wi-Fi network
hosted by the device in case of iOS. The discovery (scanning) as well as connection API is not available for
the iOS applications.
Deciding on Security
Depending on the transport and other constraints the security scheme needs to be selected by the application devel-
opers. Following considerations need to be given from the provisioning security perspective: 1. The configuration
data sent from the client to the device and the response has to be secured. 2. The client should authenticate the device
it is connected to. 3. The device manufacturer may choose proof-of-possession - a unique per device secret to be
entered on the provisioning client as a security measure to make sure that the user can provisions the device in the
possession.
There are two levels of security schemes. The developer may select one or combination depending on requirements.
1. Transport Security: SoftAP provisioning may choose WPA2 protected security with unique per-device
passphrase. Per-device unique passphrase can also act as a proof-of-possession. For BLE, just-works
security can be used as a transport level security after understanding the level of security it provides.
2. Application Security: The unified provisioning subsystem provides application level security (security1) that
provides data protection and authentication (through proof-of-possession) if the application does not use the
transport level security or if the transport level security is not sufficient for the use-case.

Fig. 28: Typical Provisioning Process

Device Discovery
The advertisement and device discovery is left to the application and depending on the protocol chosen, the phone
apps and device firmware application can choose appropriate method to advertise and discovery.
For the SoftAP+HTTP transport, typically the SSID (network name) of the AP hosted by the device can be used for
discovery.
For the BLE transport device name or primary service included in the advertisement or combination of both can be
used for discovery.
Architecture
The below diagram shows architecture of unified provisioning.
Fig. 29: Unified Provisioning Architecture
It relies on the base layer called Protocol Communication (Protocol Communication) which provides a framework
for security schemes and transport mechanisms. Wi-Fi Provisioning layer uses Protocomm to provide simple call-
backs to the application for setting the configuration and getting the Wi-Fi status. The application has control over
implementation of these callbacks. In addition application can directly use protocomm to register custom handlers.
Application creates a protocomm instance which is mapped to a specific transport and specific security scheme. Each
transport in the protocomm has a concept of an end-point which corresponds to logical channel for communication
for specific type of information. For example security handshake happens on a different endpoint than the Wi-Fi
configuration endpoint. Each end-point is identified using a string and depending on the transport internal represen-
tation of the end-point changes. In case of SoftAP+HTTP transport the end-point corresponds to URI whereas in
case of BLE the end-point corresponds to GATT characteristic with specific UUID. Developers can create custom
end-points and implement handler for the data that is received or sent over the same end-point.

Security Schemes
At present unified provisioning supports two security schemes: 1. Security0 - No security (No encryption) 2. Secu-
rity1 - Curve25519 based key exchange, shared key derivation and AES256-CTR mode encryption of the data. It
supports two modes :
a. Authorized - Proof of Possession (PoP) string used to authorize session and derive shared key
b. No Auth (Null PoP) - Shared key derived through key exchange only
Security1 scheme details are shown in the below sequence diagram
Sample Code
Please refer to Protocol Communication and Wi-Fi Provisioning for API guides and code snippets on example usage.
Application implementation can be found as an example under provisioning.
Provisioning Tools
Provisioning applications are available for various platforms, along with source code:
• Android:
– BLE Provisioning app on Play Store.
– SoftAP Provisioning app on Play Store.
– Source code on GitHub: esp-idf-provisioning-android.
• iOS:
– BLE Provisioning app on app store.
– SoftAP Provisioning app on app Store.
– Source code on GitHub: esp-idf-provisioning-ios.
• Linux/MacOS/Windows : tools/esp_prov (a python based command line tool for provisioning)
The phone applications offer simple UI and thus more user centric, while the command line application is useful as
a debugging tool for developers.
2.5.3 Wi-Fi Provisioning
Overview
This component provides APIs that control Wi-Fi provisioning service for receiving and configuring Wi-Fi cre-
dentials over SoftAP or BLE transport via secure Protocol Communication (protocomm) sessions. The set of
wifi_prov_mgr_ APIs help in quickly implementing a provisioning service having necessary features with min-
imal amount of code and sufficient flexibility.
Initialization wifi_prov_mgr_init() is called to configure and initialize the provisioning manager and thus
this must be called prior to invoking any other wifi_prov_mgr_ APIs. Note that the manager relies on other com-
ponents of IDF, namely NVS, TCP/IP, Event Loop and Wi-Fi (and optionally mDNS), hence these must be initialized
beforehand. The manager can be de-initialized at any moment by making a call to wifi_prov_mgr_deinit().
wifi_prov_mgr_config_t config = {
.scheme = wifi_prov_scheme_ble,
.scheme_event_handler = WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BTDM
};
ESP_ERROR_CHECK( wifi_prov_mgr_init(config) );
The configuration structure wifi_prov_mgr_config_t has a few fields to specify the behavior desired of the
manager :

Fig. 30: Security1

• scheme : This is used to specify the provisioning scheme. Each scheme corresponds to one of the
modes of transport supported by protocomm. Hence, we have three options :
– wifi_prov_scheme_ble : BLE transport and GATT Server for handling provisioning
commands
– wifi_prov_scheme_softap : Wi-Fi SoftAP transport and HTTP Server for handling
provisioning commands
– wifi_prov_scheme_console : Serial transport and console for handling provisioning
commands
• scheme_event_handler : An event handler defined along with scheme. Choosing appropriate
scheme specific event handler allows the manager to take care of certain matters automatically.
Presently this is not used for either SoftAP or Console based provisioning, but is very convenient
for BLE. To understand how, we must recall that Bluetooth requires quite some amount of memory
to function and once provisioning is finished, the main application may want to reclaim back this
memory (or part of it, if it needs to use either BLE or classic BT). Also, upon every future re-
boot of a provisioned device, this reclamation of memory needs to be performed again. To reduce
this complication in using wifi_prov_scheme_ble, the scheme specific handlers have been
defined, and depending upon the chosen handler, the BLE / classic BT / BTDM memory will be
freed automatically when the provisioning manager is de-initialized. The available options are:
– WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BTDM - Free both classic BT
and BLE (BTDM) memory. Used when main application doesn t require Bluetooth at all.
– WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BLE - Free only BLE memory.
Used when main application requires classic BT.
– WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BT - Free only classic BT. Used
when main application requires BLE. In this case freeing happens right when the manager is
initialized.
– WIFI_PROV_EVENT_HANDLER_NONE - Don t use any scheme specific handler. Used
when provisioning scheme is not BLE (i.e. SoftAP or Console), or when main application
wants to handle the memory reclaiming on its own, or needs both BLE and classic BT to
function.
• app_event_handler (Deprecated) : It is now recommended to catch WIFI_PROV_EVENT``s
that are emitted to the default event loop handler. See definition
of ``wifi_prov_cb_event_t for the list of events that are generated by the provisioning
service. Here is an excerpt showing some of the provisioning events:
static void event_handler(void* arg, esp_event_base_t event_base,
int event_id, void* event_data)
{
if (event_base == WIFI_PROV_EVENT) {
switch (event_id) {
case WIFI_PROV_START:
ESP_LOGI(TAG, "Provisioning started");
break;
case WIFI_PROV_CRED_RECV: {
wifi_sta_config_t *wifi_sta_cfg = (wifi_sta_config_t␣
,→*)event_data;
ESP_LOGI(TAG, "Received Wi-Fi credentials"

"\n\tSSID : %s\n\tPassword : %s",
(const char *) wifi_sta_cfg->ssid,
(const char *) wifi_sta_cfg->password);
break;
}
case WIFI_PROV_CRED_FAIL: {
wifi_prov_sta_fail_reason_t *reason = (wifi_prov_sta_fail_
,→reason_t *)event_data;
ESP_LOGE(TAG, "Provisioning failed!\n\tReason : %s"

"\n\tPlease reset to factory and retry␣
,→provisioning",
(*reason == WIFI_PROV_STA_AUTH_ERROR) ?
"Wi-Fi station authentication failed" : "Wi-Fi␣
,→access-point not found");


break;
}
case WIFI_PROV_CRED_SUCCESS:
ESP_LOGI(TAG, "Provisioning successful");
break;
case WIFI_PROV_END:
/* De-initialize manager once provisioning is finished */
wifi_prov_mgr_deinit();
break;
default:
break;
}
}
}
The manager can be de-initialized at any moment by making a call to wifi_prov_mgr_deinit().
Check Provisioning State Whether device is provisioned or not can be checked at runtime by calling
wifi_prov_mgr_is_provisioned(). This internally checks if the Wi-Fi credentials are stored in NVS.
Note that presently manager does not have its own NVS namespace for storage of Wi-Fi credentials, instead it relies
on the esp_wifi_ APIs to set and get the credentials stored in NVS from the default location.
If provisioning state needs to be reset, any of the following approaches may be taken :
• the associated part of NVS partition has to be erased manually
• main application must implement some logic to call esp_wifi_ APIs for erasing the credentials
at runtime
• main application must implement some logic to force start the provisioning irrespective of the
provisioning state
bool provisioned = false;

ESP_ERROR_CHECK( wifi_prov_mgr_is_provisioned(&provisioned) );
Start Provisioning Service At the time of starting provisioning we need to specify a service name and the corre-
sponding key. These translate to :
• Wi-Fi SoftAP SSID and passphrase, respectively, when scheme is wifi_prov_scheme_softap
• BLE Device name (service key is ignored) when scheme is wifi_prov_scheme_ble
Also, since internally the manager uses protocomm, we have the option of choosing one of the security features
provided by it :
• Security 1 is secure communication which consists of a prior handshake involving X25519 key exchange along
with authentication using a proof of possession (pop), followed by AES-CTR for encryption/decryption of
subsequent messages
• Security 0 is simply plain text communication. In this case the pop is simply ignored
See Provisioning for details about the security features.
const char *service_name = "my_device";

const char *service_key = "password";
wifi_prov_security_t security = WIFI_PROV_SECURITY_1;

const char *pop = "abcd1234";
ESP_ERROR_CHECK( wifi_prov_mgr_start_provisioning(security, pop, service_

,→name, service_key) );

The provisioning service will automatically finish only if it receives valid Wi-Fi AP credentials followed by success-
fully connection of device to the AP (IP obtained). Regardless of that, the provisioning service can be stopped at any
moment by making a call to wifi_prov_mgr_stop_provisioning().
Note: If the device fails to connect with the provided credentials, it won t accept new credentials anymore, but
the provisioning service will keep on running (only to convey failure to the client), until the device is restarted. Upon
restart the provisioning state will turn out to be true this time (as credentials will be found in NVS), but device will
again fail to connect with those same credentials (unless an AP with the matching credentials somehow does become
available). This situation can be fixed by resetting the credentials in NVS or force starting the provisioning service.
This has been explained above in Check Provisioning State.
Waiting For Completion Typically, the main application will wait for the provisioning to finish, then de-initialize
the manager to free up resources and finally start executing its own logic.
There are two ways for making this possible. The simpler way is to use a blocking call to
wifi_prov_mgr_wait().
// Start provisioning service

ESP_ERROR_CHECK( wifi_prov_mgr_start_provisioning(security, pop, service_
,→name, service_key) );
// Wait for service to complete

wifi_prov_mgr_wait();
// Finally de-initialize the manager

The other way is to use the default event loop handler to catch WIFI_PROV_EVENT``s and call
:cpp:func:`wifi_prov_mgr_deinit()` when event ID is ``WIFI_PROV_END:
static void event_handler(void* arg, esp_event_base_t event_base,

int event_id, void* event_data)
{
if (event_base == WIFI_PROV_EVENT && event_id == WIFI_PROV_END) {
/* De-initialize manager once provisioning is finished */
}
}
User Side Implementation When the service is started, the device to be provisioned is identified by the advertised
service name which, depending upon the selected transport, is either the BLE device name or the SoftAP SSID.
When using SoftAP transport, for allowing service discovery, mDNS must be initialized before starting provisioning.
In this case the hostname set by the main application is used, and the service type is internally set to _esp_wifi_prov.
When using BLE transport, a custom 128 bit UUID should be set using
wifi_prov_scheme_ble_set_service_uuid(). This UUID will be included in the BLE advertisement
and will correspond to the primary GATT service that provides provisioning endpoints as GATT characteristics.
Each GATT characteristic will be formed using the primary service UUID as base, with different auto assigned 12th
and 13th bytes (assume counting starts from 0th byte). Since, an endpoint characteristic UUID is auto assigned, it
shouldn t be used to identify the endpoint. Instead, client side applications should identify the endpoints by reading
the User Characteristic Description (0x2901) descriptor for each characteristic, which contains the endpoint name
of the characteristic. For example, if the service UUID is set to 55cc035e-fb27-4f80-be02-3c60828b7451, each
endpoint characteristic will be assigned a UUID like 55cc____-fb27-4f80-be02-3c60828b7451, with unique values
at the 12th and 13th bytes.
Once connected to the device, the provisioning related protocomm endpoints can be identified as follows :

Table 13: Endpoints provided by Provisioning Service

Endpoint URI (SoftAP + HTTP Server Description
Name + mDNS)
(BLE +
GATT
Server)
prov- http://<mdns- Security endpoint used for session establishment
session hostname>.local/prov-session
prov-scan http://wifi-prov.local/ Endpoint used for starting Wi-Fi scan and receiving scan results
prov-scan
prov- http://<mdns- Endpoint used for configuring Wi-Fi credentials on device
config hostname>.local/prov-config
proto-ver http://<mdns- Endpoint for retrieving version info
hostname>.local/proto-ver
Immediately after connecting, the client application may fetch the version / capabilities information from the proto-ver
endpoint. All communications to this endpoint are un-encrypted, hence necessary information (that may be relevant
for deciding compatibility) can be retrieved before establishing a secure session. The response is in JSON format
and looks like : prov: { ver: v1.1, cap: [no_pop] }, my_app: { ver: 1.345,
cap: [cloud, local_ctrl] },..... Here label prov provides provisioning service version (ver) and
capabilities (cap). For now, only no_pop capability is supported, which indicates that the service doesn t require
proof of possession for authentication. Any application related version / capabilities will be given by other labels (like
my_app in this example). These additional fields are set using wifi_prov_mgr_set_app_info().
User side applications need to implement the signature handshaking required for establishing and authenticating secure
protocomm sessions as per the security scheme configured for use (this is not needed when manager is configured to
use protocomm security 0).
See Unified Provisioning for more details about the secure handshake and encryption used. Applications must use the
.proto files found under protocomm/proto, which define the Protobuf message structures supported by prov-session
endpoint.
Once a session is established, Wi-Fi credentials are configured using the following set of wifi_config commands,
serialized as Protobuf messages (the corresponding .proto files can be found under wifi_provisioning/proto) :
• get_status - For querying the Wi-Fi connection status. The device will respond with a status which will be
one of connecting / connected / disconnected. If status is disconnected, a disconnection reason will also be
included in the status response.
• set_config - For setting the Wi-Fi connection credentials
• apply_config - For applying the credentials saved during set_config and start the Wi-Fi station
After session establishment, client can also request Wi-Fi scan results from the device. The results returned is a list
of AP SSIDs, sorted in descending order of signal strength. This allows client applications to display APs nearby
to the device at the time of provisioning, and users can select one of the SSIDs and provide the password which is
then sent using the wifi_config commands described above. The wifi_scan endpoint supports the following protobuf
commands :
• scan_start - For starting Wi-Fi scan with various options :
– blocking (input) - If true, the command returns only when the scanning is finished
– passive (input) - If true scan is started in passive mode (this may be slower) instead of active mode
– group_channels (input) - This specifies whether to scan all channels in one go (when zero) or perform
scanning of channels in groups, with 120ms delay between scanning of consecutive groups, and the value
of this parameter sets the number of channels in each group. This is useful when transport mode is
SoftAP, where scanning all channels in one go may not give the Wi-Fi driver enough time to send out
beacons, and hence may cause disconnection with any connected stations. When scanning in groups, the
manager will wait for atleast 120ms after completing scan on a group of channels, and thus allow the
driver to send out the beacons. For example, given that the total number of Wi-Fi channels is 14, then
setting group_channels to 4, will create 5 groups, with each group having 3 channels, except the last one
which will have 14 % 3 = 2 channels. So, when scan is started, the first 3 channels will be scanned,
followed by a 120ms delay, and then the next 3 channels, and so on, until all the 14 channels have been

scanned. One may need to adjust this parameter as having only few channels in a group may slow down
the overall scan time, while having too many may again cause disconnection. Usually a value of 4 should
work for most cases. Note that for any other mode of transport, e.g. BLE, this can be safely set to 0, and
hence achieve the fastest overall scanning time.
– period_ms (input) - Scan parameter specifying how long to wait on each channel
• scan_status - Gives the status of scanning process :
– scan_finished (output) - When scan has finished this returns true
– result_count (output) - This gives the total number of results obtained till now. If scan is yet happening
this number will keep on updating
• scan_result - For fetching scan results. This can be called even if scan is still on going
– start_index (input) - Starting index from where to fetch the entries from the results list
– count (input) - Number of entries to fetch from the starting index
– entries (output) - List of entries returned. Each entry consists of ssid, channel and rssi information
Additional Endpoints In case users want to have some additional protocomm endpoints customized to their re-
quirements, this is done in two steps. First is creation of an endpoint with a specific name, and the second step is
the registration of a handler for this endpoint. See protocomm for the function signature of an endpoint handler.
A custom endpoint must be created after initialization and before starting the provisioning service. Whereas, the
protocomm handler is registered for this endpoint only after starting the provisioning service.
wifi_prov_mgr_init(config);
wifi_prov_mgr_endpoint_create("custom-endpoint");
wifi_prov_mgr_start_provisioning(security, pop, service_name, service_
,→key);
wifi_prov_mgr_endpoint_register("custom-endpoint", custom_ep_handler,␣
,→custom_ep_data);
When the provisioning service stops, the endpoint is unregistered automatically.

One can also choose to call wifi_prov_mgr_endpoint_unregister() to manually deactivate an endpoint
at runtime. This can also be used to deactivate the internal endpoints used by the provisioning service.
When / How To Stop Provisioning Service? The default behavior is that once the device successfully connects
using the Wi-Fi credentials set by the apply_config command, the provisioning service will be stopped (and BLE
/ SoftAP turned off) automatically after responding to the next get_status command. If get_status command is not
received by the device, the service will be stopped after a 30s timeout.
On the other hand, if device was not able to connect using the provided Wi-Fi credentials, due to incorrect SSID /
passphrase, the service will keep running, and get_status will keep responding with disconnected status and reason for
disconnection. Any further attempts to provide another set of Wi-Fi credentials, will be rejected. These credentials
will be preserved, unless the provisioning service is force started, or NVS erased.
If this default behavior is not desired, it can be disabled by calling wifi_prov_mgr_disable_auto_stop().
Now the provisioning service will only be stopped after an explicit call to
wifi_prov_mgr_stop_provisioning(), which returns immediately after scheduling a task for stopping
the service. The service stops after a certain delay and WIFI_PROV_END event gets emitted. This delay is specified
by the argument to wifi_prov_mgr_disable_auto_stop().
The customized behavior is useful for applications which want the provisioning service to be stopped some
time after the Wi-Fi connection is successfully established. For example, if the application requires the de-
vice to connect to some cloud service and obtain another set of credentials, and exchange this credentials
over a custom protocomm endpoint, then after successfully doing so stop the provisioning service by calling
wifi_prov_mgr_stop_provisioning() inside the protocomm handler itself. The right amount of de-
lay ensures that the transport resources are freed only after the response from the protocomm handler reaches the
client side application.
For complete example implementation see provisioning/wifi_prov_mgr

Provisioning Tools
Provisioning applications are available for various platforms, along with source code:
• Android:
– BLE Provisioning app on Play Store.
– SoftAP Provisioning app on Play Store.
– Source code on GitHub: esp-idf-provisioning-android.
• iOS:
– BLE Provisioning app on app store.
– SoftAP Provisioning app on app Store.
– Source code on GitHub: esp-idf-provisioning-ios.
• Linux/MacOS/Windows : tools/esp_prov (a python based command line tool for provisioning)
The phone applications offer simple UI and thus more user centric, while the command line application is useful as
a debugging tool for developers.
API Reference
Header File
• components/wifi_provisioning/include/wifi_provisioning/manager.h
Functions
esp_err_t wifi_prov_mgr_init(wifi_prov_mgr_config_t config)
Initialize provisioning manager instance.
Configures the manager and allocates internal resources
Configuration specifies the provisioning scheme (transport) and event handlers
Event WIFI_PROV_INIT is emitted right after initialization is complete
Return
• ESP_FAIL : Fail
Parameters
• [in] config: Configuration structure
void wifi_prov_mgr_deinit(void)
Stop provisioning (if running) and release resource used by the manager.
Event WIFI_PROV_DEINIT is emitted right after de-initialization is finished
If provisioning service is still active when this API is called, it first stops the service, hence emitting
WIFI_PROV_END, and then performs the de-initialization
esp_err_t wifi_prov_mgr_is_provisioned(bool *provisioned)
Checks if device is provisioned.
This checks if Wi-Fi credentials are present on the NVS
The Wi-Fi credentials are assumed to be kept in the same NVS namespace as used by esp_wifi component
If one were to call esp_wifi_set_config() directly instead of going through the provisioning process, this function
will still yield true (i.e. device will be found to be provisioned)
Note Calling wifi_prov_mgr_start_provisioning() automatically resets the provision state, irrespective of what
the state was prior to making the call.
Return
• ESP_OK : Retrieved provision state successfully
• ESP_FAIL : Wi-Fi not initialized
• ESP_ERR_INVALID_ARG : Null argument supplied
• ESP_ERR_INVALID_STATE : Manager not initialized
Parameters

• [out] provisioned: True if provisioned, else false

esp_err_t wifi_prov_mgr_start_provisioning(wifi_prov_security_t security, const char
*pop, const char *service_name, const char
*service_key)
Start provisioning service.
This starts the provisioning service according to the scheme configured at the time of initialization. For scheme
:
• wifi_prov_scheme_ble : This starts protocomm_ble, which internally initializes BLE transport and starts
GATT server for handling provisioning requests
• wifi_prov_scheme_softap : This activates SoftAP mode of Wi-Fi and starts protocomm_httpd, which
internally starts an HTTP server for handling provisioning requests (If mDNS is active it also starts ad-
vertising service with type _esp_wifi_prov._tcp)
Event WIFI_PROV_START is emitted right after provisioning starts without failure
Note This API will start provisioning service even if device is found to be already provisioned, i.e.
wifi_prov_mgr_is_provisioned() yields true
Return
• ESP_OK : Provisioning started successfully
• ESP_FAIL : Failed to start provisioning service
• ESP_ERR_INVALID_STATE : Provisioning manager not initialized or already started
Parameters
• [in] security: Specify which protocomm security scheme to use :
– WIFI_PROV_SECURITY_0 : For no security
– WIFI_PROV_SECURITY_1 : x25519 secure handshake for session establishment followed by
AES-CTR encryption of provisioning messages
• [in] pop: Pointer to proof of possession string (NULL if not needed). This is relevant only for
protocomm security 1, in which case it is used for authenticating secure session
• [in] service_name: Unique name of the service. This translates to:
– Wi-Fi SSID when provisioning mode is softAP
– Device name when provisioning mode is BLE
• [in] service_key: Key required by client to access the service (NULL if not needed). This
translates to:
– Wi-Fi password when provisioning mode is softAP
– ignored when provisioning mode is BLE
void wifi_prov_mgr_stop_provisioning(void)
Stop provisioning service.
If provisioning service is active, this API will initiate a process to stop the service and return. Once the service
actually stops, the event WIFI_PROV_END will be emitted.
If wifi_prov_mgr_deinit() is called without calling this API first, it will automatically stop the provisioning
service and emit the WIFI_PROV_END, followed by WIFI_PROV_DEINIT, before returning.
This API will generally be used along with wifi_prov_mgr_disable_auto_stop() in the scenario when the main
application has registered its own endpoints, and wishes that the provisioning service is stopped only when
some protocomm command from the client side application is received.
Calling this API inside an endpoint handler, with sufficient cleanup_delay, will allow the response / acknowl-
edgment to be sent successfully before the underlying protocomm service is stopped.
Cleaup_delay is set when calling wifi_prov_mgr_disable_auto_stop(). If not specified, it defaults to 1000ms.
For straightforward cases, using this API is usually not necessary as provisioning is stopped automatically once
WIFI_PROV_CRED_SUCCESS is emitted. Stopping is delayed (maximum 30 seconds) thus allowing the
client side application to query for Wi-Fi state, i.e. after receiving the first query and sending Wi-Fi state
connected response the service is stopped immediately.
void wifi_prov_mgr_wait(void)
Wait for provisioning service to finish.

Calling this API will block until provisioning service is stopped i.e. till event WIFI_PROV_END is emitted.
This will not block if provisioning is not started or not initialized.
esp_err_t wifi_prov_mgr_disable_auto_stop(uint32_t cleanup_delay)
Disable auto stopping of provisioning service upon completion.
By default, once provisioning is complete, the provisioning service is automatically stopped, and all endpoints
(along with those registered by main application) are deactivated.
This API is useful in the case when main application wishes to close provisioning service only after it receives
some protocomm command from the client side app. For example, after connecting to Wi-Fi, the device may
want to connect to the cloud, and only once that is successfully, the device is said to be fully configured. But,
then it is upto the main application to explicitly call wifi_prov_mgr_stop_provisioning() later when the device
is fully configured and the provisioning service is no longer required.
Note This must be called before executing wifi_prov_mgr_start_provisioning()
Return
• ESP_ERR_INVALID_STATE : Manager not initialized or provisioning service already started
Parameters
• [in] cleanup_delay: Sets the delay after which the actual cleanup of transport related re-
sources is done after a call to wifi_prov_mgr_stop_provisioning() returns. Minimum allowed value
is 100ms. If not specified, this will default to 1000ms.
esp_err_t wifi_prov_mgr_set_app_info(const char *label, const char *version, const char
**capabilities, size_t total_capabilities)
Set application version and capabilities in the JSON data returned by proto-ver endpoint.
This function can be called multiple times, to specify information about the various application specific services
running on the device, identified by unique labels.
The provisioning service itself registers an entry in the JSON data, by the label prov , containing only
provisioning service version and capabilities. Application services should use a label other than prov so as
not to overwrite this.
Note This must be called before executing wifi_prov_mgr_start_provisioning()
Return
• ESP_ERR_INVALID_STATE : Manager not initialized or provisioning service already started
• ESP_ERR_NO_MEM : Failed to allocate memory for version string
• ESP_ERR_INVALID_ARG : Null argument
Parameters
• [in] label: String indicating the application name.
• [in] version: String indicating the application version. There is no constraint on format.
• [in] capabilities: Array of strings with capabilities. These could be used by the client side
app to know the application registered endpoint capabilities
• [in] total_capabilities: Size of capabilities array
esp_err_t wifi_prov_mgr_endpoint_create(const char *ep_name)
Create an additional endpoint and allocate internal resources for it.
This API is to be called by the application if it wants to create an additional endpoint. All additional endpoints
will be assigned UUIDs starting from 0xFF54 and so on in the order of execution.
protocomm handler for the created endpoint is to be registered later using wifi_prov_mgr_endpoint_register()
after provisioning has started.
Note This API can only be called BEFORE provisioning is started
Note Additional endpoints can be used for configuring client provided parameters other than Wi-Fi credentials,
that are necessary for the main application and hence must be set prior to starting the application
Note After session establishment, the additional endpoints must be targeted first by the client side application
before sending Wi-Fi configuration, because once Wi-Fi configuration finishes the provisioning service
is stopped and hence all endpoints are unregistered
Return

Parameters
• [in] ep_name: unique name of the endpoint
esp_err_t wifi_prov_mgr_endpoint_register(const char *ep_name, proto-
comm_req_handler_t handler, void *user_ctx)
Register a handler for the previously created endpoint.
This API can be called by the application to register a protocomm handler to any endpoint that was created
using wifi_prov_mgr_endpoint_create().
Note This API can only be called AFTER provisioning has started
Note Additional endpoints can be used for configuring client provided parameters other than Wi-Fi credentials,
that are necessary for the main application and hence must be set prior to starting the application
Note After session establishment, the additional endpoints must be targeted first by the client side application
before sending Wi-Fi configuration, because once Wi-Fi configuration finishes the provisioning service
is stopped and hence all endpoints are unregistered
Return
Parameters
• [in] handler: Endpoint handler function
• [in] user_ctx: User data
void wifi_prov_mgr_endpoint_unregister(const char *ep_name)
Unregister the handler for an endpoint.
This API can be called if the application wants to selectively unregister the handler of an endpoint while the
provisioning is still in progress.
All the endpoint handlers are unregistered automatically when the provisioning stops.
Parameters
esp_err_t wifi_prov_mgr_event_handler(void *ctx, system_event_t *event)
Event handler for provisioning manager.
This is called from the main event handler and controls the provisioning manager s internal state machine
depending on incoming Wi-Fi events
Note : This function is DEPRECATED, because events are now handled internally using the event loop library,
esp_event. Calling this will do nothing and simply return ESP_OK.
Return
• ESP_OK : Event handled successfully
Parameters
• [in] ctx: Event context data
• [in] event: Event info
esp_err_t wifi_prov_mgr_get_wifi_state(wifi_prov_sta_state_t *state)
Get state of Wi-Fi Station during provisioning.
Return
• ESP_OK : Successfully retrieved Wi-Fi state
• ESP_FAIL : Provisioning app not running
Parameters
• [out] state: Pointer to wifi_prov_sta_state_t variable to be filled
esp_err_t wifi_prov_mgr_get_wifi_disconnect_reason(wifi_prov_sta_fail_reason_t
*reason)
Get reason code in case of Wi-Fi station disconnection during provisioning.
Return

• ESP_OK : Successfully retrieved Wi-Fi disconnect reason

• ESP_FAIL : Provisioning app not running
Parameters
• [out] reason: Pointer to wifi_prov_sta_fail_reason_t variable to be filled
esp_err_t wifi_prov_mgr_configure_sta(wifi_config_t *wifi_cfg)
Runs Wi-Fi as Station with the supplied configuration.
Configures the Wi-Fi station mode to connect to the AP with SSID and password specified in config structure
and sets Wi-Fi to run as station.
This is automatically called by provisioning service upon receiving new credentials.
If credentials are to be supplied to the manager via a different mode other than through protocomm, then this
API needs to be called.
Event WIFI_PROV_CRED_RECV is emitted after credentials have been applied and Wi-Fi station started
Return
• ESP_OK : Wi-Fi configured and started successfully
• ESP_FAIL : Failed to set configuration
Parameters
• [in] wifi_cfg: Pointer to Wi-Fi configuration structure
esp_err_t wifi_prov_mgr_reset_provisioning(void)
Reset Wi-Fi provisioning config.
Calling this API will restore WiFi stack persistent settings to default values.
Return
• ESP_OK : Reset provisioning config successfully
• ESP_FAIL : Failed to reset provisioning config
esp_err_t wifi_prov_mgr_reset_sm_state_on_failure(void)
Reset internal state machine and clear provisioned credentials.
This API can be used to restart provisioning in case invalid credentials are entered.
Return
• ESP_OK : Reset provisioning state machine successfully
• ESP_FAIL : Failed to reset provisioning state machine
• ESP_ERR_INVALID_STATE : Manager not initialized
Structures
struct wifi_prov_event_handler_t
Event handler that is used by the manager while provisioning service is active.
Public Members
wifi_prov_cb_func_t event_cb
Callback function to be executed on provisioning events
void *user_data
User context data to pass as parameter to callback function
struct wifi_prov_scheme
Structure for specifying the provisioning scheme to be followed by the manager.
Note Ready to use schemes are available:
• wifi_prov_scheme_ble : for provisioning over BLE transport + GATT server
• wifi_prov_scheme_softap : for provisioning over SoftAP transport + HTTP server
• wifi_prov_scheme_console : for provisioning over Serial UART transport + Console (for debugging)

Public Members
esp_err_t (*prov_start)(protocomm_t *pc, void *config)

Function which is to be called by the manager when it is to start the provisioning service associated with
a protocomm instance and a scheme specific configuration
esp_err_t (*prov_stop)(protocomm_t *pc)
Function which is to be called by the manager to stop the provisioning service previously associated with
a protocomm instance
void *(*new_config)(void)
Function which is to be called by the manager to generate a new configuration for the provisioning service,
that is to be passed to prov_start()
void (*delete_config)(void *config)
Function which is to be called by the manager to delete a configuration generated using new_config()
esp_err_t (*set_config_service)(void *config, const char *service_name, const char *ser-
vice_key)
Function which is to be called by the manager to set the service name and key values in the configuration
structure
esp_err_t (*set_config_endpoint)(void *config, const char *endpoint_name, uint16_t uuid)
Function which is to be called by the manager to set a protocomm endpoint with an identifying name and
UUID in the configuration structure
wifi_mode_t wifi_mode
Sets mode of operation of Wi-Fi during provisioning This is set to :
• WIFI_MODE_APSTA for SoftAP transport
• WIFI_MODE_STA for BLE transport
struct wifi_prov_mgr_config_t
Structure for specifying the manager configuration.
Public Members
wifi_prov_scheme_t scheme
Provisioning scheme to use. Following schemes are already available:
• wifi_prov_scheme_softap : for provisioning over SoftAP transport + HTTP server + mDNS (op-
tional)
wifi_prov_event_handler_t scheme_event_handler
Event handler required by the scheme for incorporating scheme specific behavior while provi-
sioning manager is running. Various options may be provided by the scheme for setting this
field. Use WIFI_PROV_EVENT_HANDLER_NONE when not used. When using scheme
wifi_prov_scheme_ble, the following options are available:
• WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BTDM
• WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BLE
• WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BT
wifi_prov_event_handler_t app_event_handler
Event handler that can be set for the purpose of incorporating application specific behavior. Use
WIFI_PROV_EVENT_HANDLER_NONE when not used.
Macros
WIFI_PROV_EVENT_HANDLER_NONE
Event handler can be set to none if not used.

Type Definitions
typedef void (*wifi_prov_cb_func_t)(void *user_data, wifi_prov_cb_event_t event, void
*event_data)
typedef struct wifi_prov_scheme wifi_prov_scheme_t
Structure for specifying the provisioning scheme to be followed by the manager.
Note Ready to use schemes are available:
• wifi_prov_scheme_softap : for provisioning over SoftAP transport + HTTP server
typedef enum wifi_prov_security wifi_prov_security_t
Security modes supported by the Provisioning Manager.
These are same as the security modes provided by protocomm
Enumerations
enum wifi_prov_cb_event_t
Events generated by manager.
These events are generated in order of declaration and, for the stretch of time between initialization and de-
initialization of the manager, each event is signaled only once
Values:
WIFI_PROV_INIT
Emitted when the manager is initialized
WIFI_PROV_START
Indicates that provisioning has started
WIFI_PROV_CRED_RECV
Emitted when Wi-Fi AP credentials are received via protocomm endpoint wifi_config. The event
data in this case is a pointer to the corresponding wifi_sta_config_t structure
WIFI_PROV_CRED_FAIL
Emitted when device fails to connect to the AP of which the credentials were received earlier on event
WIFI_PROV_CRED_RECV. The event data in this case is a pointer to the disconnection reason code
with type wifi_prov_sta_fail_reason_t
WIFI_PROV_CRED_SUCCESS
Emitted when device successfully connects to the AP of which the credentials were received earlier on
event WIFI_PROV_CRED_RECV
WIFI_PROV_END
Signals that provisioning service has stopped
WIFI_PROV_DEINIT
Signals that manager has been de-initialized
enum wifi_prov_security
Security modes supported by the Provisioning Manager.
These are same as the security modes provided by protocomm
Values:
WIFI_PROV_SECURITY_0 = 0
No security (plain-text communication)
WIFI_PROV_SECURITY_1
This secure communication mode consists of X25519 key exchange
• proof of possession (pop) based authentication
• AES-CTR encryption

Header File
• components/wifi_provisioning/include/wifi_provisioning/scheme_ble.h
Functions
void wifi_prov_scheme_ble_event_cb_free_btdm(void *user_data, wifi_prov_cb_event_t
event, void *event_data)
void wifi_prov_scheme_ble_event_cb_free_ble(void *user_data, wifi_prov_cb_event_t event,
void *event_data)
void wifi_prov_scheme_ble_event_cb_free_bt(void *user_data, wifi_prov_cb_event_t event,
void *event_data)
esp_err_t wifi_prov_scheme_ble_set_service_uuid(uint8_t *uuid128)
Set the 128 bit GATT service UUID used for provisioning.
This API is used to override the default 128 bit provisioning service UUID, which is 0000ffff-0000-1000-
8000-00805f9b34fb.
This must be called before starting provisioning, i.e. before making a call to
wifi_prov_mgr_start_provisioning(), otherwise the default UUID will be used.
Note The data being pointed to by the argument must be valid atleast till provisioning is started. Upon start,
the manager will store an internal copy of this UUID, and this data can be freed or invalidated afterwords.
Return
Parameters
• [in] uuid128: A custom 128 bit UUID
esp_err_t wifi_prov_scheme_ble_set_mfg_data(uint8_t *mfg_data, ssize_t mfg_data_len)
Set manufacturer specific data in scan response.
This must be called before starting provisioning, i.e. before making a call to
wifi_prov_mgr_start_provisioning().
Note It is important to understand that length of custom manufacturer data should be within limits. The
manufacturer data goes into scan response along with BLE device name. By default, BLE device name
length is of 11 Bytes, however it can vary as per application use case. So, one has to honour the scan
response data size limits i.e. (mfg_data_len + 2) < 31 - (device_name_length + 2 ). If the mfg_data
length exceeds this limit, the length will be truncated.
Return
Parameters
• [in] mfg_data: Custom manufacturer data
• [in] mfg_data_len: Manufacturer data length
Macros
WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BTDM
WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BLE
WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BT
Header File
• components/wifi_provisioning/include/wifi_provisioning/scheme_softap.h
Functions

void wifi_prov_scheme_softap_set_httpd_handle(void *handle)

Provide HTTPD Server handle externally.
Useful in cases wherein applications need the webserver for some different operations, and do not want the wifi
provisioning component to start/stop a new instance.
Note This API should be called before wifi_prov_mgr_start_provisioning()
Parameters
• [in] handle: Handle to HTTPD server instance
Header File
• components/wifi_provisioning/include/wifi_provisioning/scheme_console.h
Header File
• components/wifi_provisioning/include/wifi_provisioning/wifi_config.h
Functions
esp_err_t wifi_prov_config_data_handler(uint32_t session_id, const uint8_t *inbuf, ssize_t
inlen, uint8_t **outbuf, ssize_t *outlen, void
*priv_data)
Handler for receiving and responding to requests from master.
This is to be registered as the wifi_config endpoint handler (protocomm proto-
comm_req_handler_t) using protocomm_add_endpoint()
Structures
struct wifi_prov_sta_conn_info_t
WiFi STA connected status information.
Public Members
char ip_addr[IP4ADDR_STRLEN_MAX]
IP Address received by station
char bssid[6]
BSSID of the AP to which connection was estalished
char ssid[33]
SSID of the to which connection was estalished
uint8_t channel
Channel of the AP
uint8_t auth_mode
Authorization mode of the AP
struct wifi_prov_config_get_data_t
WiFi status data to be sent in response to get_status request from master.
Public Members
wifi_prov_sta_state_t wifi_state
WiFi state of the station
wifi_prov_sta_fail_reason_t fail_reason
Reason for disconnection (valid only when wifi_state is WIFI_STATION_DISCONNECTED)

wifi_prov_sta_conn_info_t conn_info
Connection information (valid only when wifi_state is WIFI_STATION_CONNECTED)
struct wifi_prov_config_set_data_t
WiFi config data received by slave during set_config request from master.
Public Members
char ssid[33]
SSID of the AP to which the slave is to be connected
char password[64]
Password of the AP
char bssid[6]
BSSID of the AP
uint8_t channel
Channel of the AP
struct wifi_prov_config_handlers
Internal handlers for receiving and responding to protocomm requests from master.
This is to be passed as priv_data for protocomm request handler (refer to
wifi_prov_config_data_handler()) when calling protocomm_add_endpoint().
Public Members
esp_err_t (*get_status_handler)(wifi_prov_config_get_data_t *resp_data, wifi_prov_ctx_t

**ctx)
Handler function called when connection status of the slave (in WiFi station mode) is requested
esp_err_t (*set_config_handler)(const wifi_prov_config_set_data_t *req_data,
wifi_prov_ctx_t **ctx)
Handler function called when WiFi connection configuration (eg. AP SSID, password, etc.) of the slave
(in WiFi station mode) is to be set to user provided values
esp_err_t (*apply_config_handler)(wifi_prov_ctx_t **ctx)
Handler function for applying the configuration that was set in set_config_handler. After apply-
ing the station may get connected to the AP or may fail to connect. The slave must be ready to convey the
updated connection status information when get_status_handler is invoked again by the master.
wifi_prov_ctx_t *ctx
Context pointer to be passed to above handler functions upon invocation
Type Definitions
typedef struct wifi_prov_ctx wifi_prov_ctx_t
Type of context data passed to each get/set/apply handler function set in wifi_prov_config_handlers
structure.
This is passed as an opaque pointer, thereby allowing it be defined later in application code as per requirements.
typedef struct wifi_prov_config_handlers wifi_prov_config_handlers_t
Internal handlers for receiving and responding to protocomm requests from master.
This is to be passed as priv_data for protocomm request handler (refer to
wifi_prov_config_data_handler()) when calling protocomm_add_endpoint().
Enumerations
enum wifi_prov_sta_state_t
WiFi STA status for conveying back to the provisioning master.
Values:

WIFI_PROV_STA_CONNECTING
WIFI_PROV_STA_CONNECTED
WIFI_PROV_STA_DISCONNECTED
enum wifi_prov_sta_fail_reason_t
WiFi STA connection fail reason.
Values:
WIFI_PROV_STA_AUTH_ERROR
WIFI_PROV_STA_AP_NOT_FOUND
Code examples for above API are provided in the provisioning directory of ESP-IDF examples.
Code example for above API is provided in wifi/smart_config
Code example for above API is provided in wifi/wifi_easy_connect/dpp-enrollee
2.6 Storage API
2.6.1 FAT Filesystem Support
ESP-IDF uses the FatFs library to work with FAT filesystems. FatFs resides in the fatfs component. Although the
library can be used directly, many of its features can be accessed via VFS, using the C standard library and POSIX
API functions.
Additionally, FatFs has been modified to support the runtime pluggable disk I/O layer. This allows mapping of FatFs
drives to physical disks at runtime.
Using FatFs with VFS
The header file fatfs/vfs/esp_vfs_fat.h defines the functions for connecting FatFs and VFS.
The function esp_vfs_fat_register() allocates a FATFS structure and registers a given path prefix
in VFS. Subsequent operations on files starting with this prefix are forwarded to FatFs APIs. The function
esp_vfs_fat_unregister_path() deletes the registration with VFS, and frees the FATFS structure.
Most applications use the following workflow when working with esp_vfs_fat_ functions:
1. Call esp_vfs_fat_register() to specify:
• Path prefix where to mount the filesystem (e.g. "/sdcard", "/spiflash")
• FatFs drive number
• A variable which will receive the pointer to the FATFS structure
2. Call ff_diskio_register() to register the disk I/O driver for the drive number used in Step 1.
3. Call the FatFs function f_mount, and optionally f_fdisk, f_mkfs, to mount the filesystem using the
same drive number which was passed to esp_vfs_fat_register(). For more information, see FatFs
documentation.
4. Call the C standard library and POSIX API functions to perform such actions on files as open, read, write,
erase, copy, etc. Use paths starting with the path prefix passed to esp_vfs_register() (for example,
"/sdcard/hello.txt"). The filesystem uses 8.3 filenames format (SFN) by default. If you need to use
long filenames (LFN), enable the CONFIG_FATFS_LONG_FILENAMES option. More details on the FatFs
filenames are available here.
5. Optionally, by enabling the option CONFIG_FATFS_USE_FASTSEEK, use the POSIX lseek function to perform
it faster, the fast seek will not work for files in write mode, so to take advantage of fast seek, you should open
(or close and then reopen) the file in read-only mode.
6. Optionally, call the FatFs library functions directly. In this case, use paths without a VFS prefix (for example,
"/hello.txt").
7. Close all open files.

8. Call the FatFs function f_mount for the same drive number, with NULL FATFS* argument, to unmount
the filesystem.
9. Call the FatFs function ff_diskio_register() with NULL ff_diskio_impl_t* argument and
the same drive number to unregister the disk I/O driver.
10. Call esp_vfs_fat_unregister_path() with the path where the file system is mounted to remove
FatFs from VFS, and free the FATFS structure allocated in Step 1.
The convenience functions esp_vfs_fat_sdmmc_mount, esp_vfs_fat_sdspi_mount and
esp_vfs_fat_sdcard_unmount wrap the steps described above and also handle SD card initialization.
These two functions are described in the next section.
esp_err_t esp_vfs_fat_register(const char *base_path, const char *fat_drive, size_t max_files,
FATFS **out_fs)
Register FATFS with VFS component.
This function registers given FAT drive in VFS, at the specified base path. If only one drive is used, fat_drive
argument can be an empty string. Refer to FATFS library documentation on how to specify FAT drive. This
function also allocates FATFS structure which should be used for f_mount call.
Note This function doesn t mount the drive into FATFS, it just connects POSIX and C standard library IO
function with FATFS. You need to mount desired drive into FATFS separately.
Return
• ESP_ERR_INVALID_STATE if esp_vfs_fat_register was already called
• ESP_ERR_NO_MEM if not enough memory or too many VFSes already registered
Parameters
• base_path: path prefix where FATFS should be registered
• fat_drive: FATFS drive specification; if only one drive is used, can be an empty string
• max_files: maximum number of files which can be open at the same time
• [out] out_fs: pointer to FATFS structure which can be used for FATFS f_mount call is re-
turned via this argument.
esp_err_t esp_vfs_fat_unregister_path(const char *base_path)
Un-register FATFS from VFS.
Note FATFS structure returned by esp_vfs_fat_register is destroyed after this call. Make sure to call f_mount
function to unmount it before calling esp_vfs_fat_unregister_ctx. Difference between this function and
the one above is that this one will release the correct drive, while the one above will release the last
registered one
Return
• ESP_ERR_INVALID_STATE if FATFS is not registered in VFS
Parameters
• base_path: path prefix where FATFS is registered. This is the same used when
esp_vfs_fat_register was called
Using FatFs with VFS and SD cards
The header file fatfs/vfs/esp_vfs_fat.h defines convenience functions esp_vfs_fat_sdmmc_mount(),

esp_vfs_fat_sdspi_mount() and esp_vfs_fat_sdcard_unmount(). These function perform
Steps 1 3 and 7 9 respectively and handle SD card initialization, but provide only limited error handling. Developers
are encouraged to check its source code and incorporate more advanced features into production applications.
The convenience function esp_vfs_fat_sdmmc_unmount() unmounts the filesystem and releases the re-
sources acquired by esp_vfs_fat_sdmmc_mount().
esp_err_t esp_vfs_fat_sdmmc_mount(const char *base_path, const sdmmc_host_t *host_config,
const void *slot_config, const esp_vfs_fat_mount_config_t
*mount_config, sdmmc_card_t **out_card)
Convenience function to get FAT filesystem on SD card registered in VFS.
This is an all-in-one function which does the following:

• initializes SDMMC driver or SPI driver with configuration in host_config

• initializes SD card with configuration in slot_config
• mounts FAT partition on SD card using FATFS library, with configuration in mount_config
• registers FATFS library with VFS, with prefix given by base_prefix variable
This function is intended to make example code more compact. For real world applications, developers should
implement the logic of probing SD card, locating and mounting partition, and registering FATFS in VFS, with
proper error checking and handling of exceptional conditions.
Note Use this API to mount a card through SDSPI is deprecated. Please call
esp_vfs_fat_sdspi_mount() instead for that case.
Return
• ESP_ERR_INVALID_STATE if esp_vfs_fat_sdmmc_mount was already called
• ESP_FAIL if partition can not be mounted
• other error codes from SDMMC or SPI drivers, SDMMC protocol, or FATFS drivers
Parameters
• base_path: path where partition should be registered (e.g. /sdcard )
• host_config: Pointer to structure describing SDMMC host. When using SDMMC peripheral,
this structure can be initialized using SDMMC_HOST_DEFAULT() macro. When using SPI pe-
ripheral, this structure can be initialized using SDSPI_HOST_DEFAULT() macro.
• slot_config: Pointer to structure with slot configuration. For SDMMC peripheral, pass a
pointer to sdmmc_slot_config_t structure initialized using SDMMC_SLOT_CONFIG_DEFAULT.
(Deprecated) For SPI peripheral, pass a pointer to sdspi_slot_config_t structure initialized using SD-
SPI_SLOT_CONFIG_DEFAULT().
• mount_config: pointer to structure with extra parameters for mounting FATFS
• [out] out_card: if not NULL, pointer to the card information structure will be returned via
this argument
esp_err_t esp_vfs_fat_sdspi_mount(const char *base_path, const sdmmc_host_t
*host_config_input, const sdspi_device_config_t *slot_config,
const esp_vfs_fat_mount_config_t *mount_config, sd-
mmc_card_t **out_card)
Convenience function to get FAT filesystem on SD card registered in VFS.
• initializes an SPI Master device based on the SPI Master driver with configuration in slot_config, and
attach it to an initialized SPI bus.
• initializes SD card with configuration in host_config_input
• mounts FAT partition on SD card using FATFS library, with configuration in mount_config
This function is intended to make example code more compact. For real world applications, developers should
implement the logic of probing SD card, locating and mounting partition, and registering FATFS in VFS, with
proper error checking and handling of exceptional conditions.
Note This function try to attach the new SD SPI device to the bus specified in host_config. Make sure the
SPI bus specified in host_config->slot have been initialized by spi_bus_initialize()
before.
Return
• ESP_ERR_INVALID_STATE if esp_vfs_fat_sdmmc_mount was already called
• other error codes from SDMMC or SPI drivers, SDMMC protocol, or FATFS drivers
Parameters
• base_path: path where partition should be registered (e.g. /sdcard )
• host_config_input: Pointer to structure describing SDMMC host. This structure can be
initialized using SDSPI_HOST_DEFAULT() macro.

• slot_config: Pointer to structure with slot configuration. For SPI peripheral, pass a pointer to
sdspi_device_config_t structure initialized using SDSPI_DEVICE_CONFIG_DEFAULT().
• [out] out_card: If not NULL, pointer to the card information structure will be returned via
this argument. It is suggested to hold this handle and use it to unmount the card later if needed.
Otherwise it s not suggested to use more than one card at the same time and unmount one of them
in your application.
struct esp_vfs_fat_mount_config_t
Configuration arguments for esp_vfs_fat_sdmmc_mount and esp_vfs_fat_spiflash_mount functions.
Public Members
bool format_if_mount_failed
If FAT partition can not be mounted, and this parameter is true, create partition table and format the
filesystem.
int max_files
Max number of open files.
size_t allocation_unit_size
If format_if_mount_failed is set, and mount fails, format the card with given allocation unit size. Must
be a power of 2, between sector size and 128 * sector size. For SD cards, sector size is always 512 bytes.
For wear_levelling, sector size is determined by CONFIG_WL_SECTOR_SIZE option.
Using larger allocation unit size will result in higher read/write performance and higher overhead when
storing small files.
Setting this field to 0 will result in allocation unit set to the sector size.
esp_err_t esp_vfs_fat_sdcard_unmount(const char *base_path, sdmmc_card_t *card)
Unmount an SD card from the FAT filesystem and release resources acquired using
esp_vfs_fat_sdmmc_mount() or esp_vfs_fat_sdspi_mount()
Return
• ESP_ERR_INVALID_ARG if the card argument is unregistered
• ESP_ERR_INVALID_STATE if esp_vfs_fat_sdmmc_mount hasn t been called
Using FatFs with VFS in read-only mode
The header file fatfs/vfs/esp_vfs_fat.h also defines the convenience functions

esp_vfs_fat_rawflash_mount() and esp_vfs_fat_rawflash_unmount(). These func-
tions perform Steps 1-3 and 7-9 respectively for read-only FAT partitions. These are particularly helpful for
data partitions written only once during factory provisioning which will not be changed by production application
throughout the lifetime of the hardware.
esp_err_t esp_vfs_fat_rawflash_mount(const char *base_path, const char *partition_label,
const esp_vfs_fat_mount_config_t *mount_config)
Convenience function to initialize read-only FAT filesystem and register it in VFS.
• finds the partition with defined partition_label. Partition label should be configured in the partition table.
• mounts FAT partition using FATFS library
Note Wear levelling is not used when FAT is mounted in read-only mode using this function.
Return
• ESP_ERR_NOT_FOUND if the partition table does not contain FATFS partition with given label

• ESP_ERR_INVALID_STATE if esp_vfs_fat_rawflash_mount was already called for the same par-

tition
• other error codes from SPI flash driver, or FATFS drivers
Parameters
• base_path: path where FATFS partition should be mounted (e.g. /spiflash )
• partition_label: label of the partition which should be used
esp_err_t esp_vfs_fat_rawflash_unmount(const char *base_path, const char
*partition_label)
Unmount FAT filesystem and release resources acquired using esp_vfs_fat_rawflash_mount.
Return
• ESP_ERR_INVALID_STATE if esp_vfs_fat_spiflash_mount hasn t been called
Parameters
• base_path: path where partition should be registered (e.g. /spiflash )
• partition_label: label of partition to be unmounted
FatFS disk IO layer
FatFs has been extended with API functions that register the disk I/O driver at runtime.
They provide implementation of disk I/O functions for SD/MMC cards and can be registered for the given FatFs
drive number using the function ff_diskio_register_sdmmc().
void ff_diskio_register(BYTE pdrv, const ff_diskio_impl_t *discio_impl)
Register or unregister diskio driver for given drive number.
When FATFS library calls one of disk_xxx functions for driver number pdrv, corresponding function in dis-
cio_impl for given pdrv will be called.
Parameters
• pdrv: drive number
• discio_impl: pointer to ff_diskio_impl_t structure with diskio functions or NULL to unregister
and free previously registered drive
struct ff_diskio_impl_t
Structure of pointers to disk IO driver functions.
See FatFs documentation for details about these functions
Public Members
DSTATUS (*init)(unsigned char pdrv)

disk initialization function
DSTATUS (*status)(unsigned char pdrv)
disk status check function
DRESULT (*read)(unsigned char pdrv, unsigned char *buff, uint32_t sector, unsigned count)
sector read function
DRESULT (*write)(unsigned char pdrv, const unsigned char *buff, uint32_t sector, unsigned
count)
sector write function
DRESULT (*ioctl)(unsigned char pdrv, unsigned char cmd, void *buff)
function to get info about disk and do some misc operations

void ff_diskio_register_sdmmc(unsigned char pdrv, sdmmc_card_t *card)

Register SD/MMC diskio driver
Parameters
• card: pointer to sdmmc_card_t structure describing a card; card should be initialized before calling
f_mount.
esp_err_t ff_diskio_register_wl_partition(unsigned char pdrv, wl_handle_t flash_handle)
Register spi flash partition
Parameters
• flash_handle: handle of the wear levelling partition.
esp_err_t ff_diskio_register_raw_partition(unsigned char pdrv, const esp_partition_t
*part_handle)
Register spi flash partition
Parameters
• part_handle: pointer to raw flash partition.
FATFS partition generator
We provide partition generator for FATFS (fatfsgen.py) which is integrated into the build system and could be easily
used in the user project. The tool is used to create filesystem images on a host and populate it with content of the
specified host folder. Current implementation supports short file names, FAT12 and read-only mode (because the
wear levelling is not implemented yet). The WL, long file names, and FAT16 are subjects of future work.
Build system integration with FATFS partition generator It is possible to invoke FATFS generator directly
from the CMake build system by calling fatfs_create_partition_image:
fatfs_create_partition_image(<partition> <base_dir> [FLASH_IN_PROJECT])
fatfs_create_partition_image must be called from project s CMakeLists.txt.

The arguments of the function are as follows:
1. partition - the name of the partition, you can define in partition table (e.g. stor-
age/fatfsgen/partitions_example.csv)
2. base_dir - the directory that will be encoded to FATFS partition and optionally flashed into the device. Beware
that you have to specified suitable size of the partition in the partition table.
3. flag FLASH_IN_PROJECT - optionally, user can opt to have the image automatically flashed together with the
app binaries, partition tables, etc. on idf.py flash -p <PORT> by specifying FLASH_IN_PROJECT.
For example:
fatfs_create_partition_image(my_fatfs_partition my_folder FLASH_IN_PROJECT)
If FLASH_IN_PROJECT is not specified, the image will still be generated, but you will have to flash it manually
using esptool.py or a custom build system target.
For an example, see storage/fatfsgen.
2.6.2 Manufacturing Utility
Introduction
This utility is designed to create instances of factory NVS partition images on a per-device basis for mass manufac-
turing purposes. The NVS partition images are created from CSV files containing user-provided configurations and

values.
Please note that this utility only creates manufacturing binary images which then need to be flashed onto your devices
using:
• esptool.py
• Flash Download tool (available on Windows only).Just download it, unzip, and follow the instructions inside
the doc folder.
• Direct flash programming using custom production tools.
Prerequisites
This utility is dependent on esp-idf s NVS partition utility.

• Operating System requirements:
– Linux / MacOS / Windows (standard distributions)
• The following packages are needed to use this utility:
– Python
Note:
Before using this utility, please make sure that:
• The path to Python is added to the PATH environment variable.
• You have installed the packages from requirement.txt, the file in the root of the esp-idf directory.
Workflow
CSV Configuration File
This file contains the configuration of the device to be flashed.

The data in the configuration file has the following format (the REPEAT tag is optional):
name1,namespace, <-- First entry should be of type "namespace"

key1,type1,encoding1
key2,type2,encoding2,REPEAT
name2,namespace,
Note: The first line in this file should always be the namespace entry.
Each line should have three parameters: key,type,encoding, separated by a comma. If the REPEAT tag is
present, the value corresponding to this key in the master value CSV file will be the same for all devices.
Please refer to README of the NVS Partition Generator utility for detailed description of each parameter.
Below is a sample example of such a configuration file:

app,namespace,
firmware_key,data,hex2bin
serial_no,data,string,REPEAT
device_no,data,i32
Note:
Make sure there are no spaces:
• before and after ,
• at the end of each line in a CSV file
Master Value CSV File
This file contains details of the devices to be flashed. Each line in this file corresponds to a device instance.
The data in the master value CSV file has the following format:
key1,key2,key3,.....
value1,value2,value3,....
Note: The first line in the file should always contain the key names. All the keys from the configuration file should
be present here in the same order. This file can have additional columns (keys). The additional keys will be treated
as metadata and would not be part of the final binary files.
Each line should contain the value of the corresponding keys, separated by a comma. If the key has the REPEAT
tag, its corresponding value must be entered in the second line only. Keep the entry empty for this value in the
following lines.
The description of this parameter is as follows:
value Data value
Data value is the value of data corresponding to the key.
Below is a sample example of a master value CSV file:
id,firmware_key,serial_no,device_no
1,1a2b3c4d5e6faabb,A1,101
2,1a2b3c4d5e6fccdd,,102
3,1a2b3c4d5e6feeff,,103
Note: If the REPEAT tag is present, a new master value CSV file will be created in the same folder as the input
Master CSV File with the values inserted at each line for the key with the REPEAT tag.
This utility creates intermediate CSV files which are used as input for the NVS partition utility to generate the binary
files.
The format of this intermediate CSV file is as follows:
key,type,encoding,value
key,namespace, ,
key1,type1,encoding1,value1
key2,type2,encoding2,value2
An instance of an intermediate CSV file will be created for each device on an individual basis.

Running the utility
Usage:
python mfg_gen.py [-h] {generate,generate-key} ...
Optional Arguments:
+-----+------------+---------------------------------------------------------------
,→-------+
| No. | Parameter | Description ␣

,→ |
+=====+============+======================================================================+
| 1 | -h, --help | show this help message and exit ␣
,→ |
+-----+------------+---------------------------------------------------------------
,→-------+
Commands:
Run mfg_gen.py {command} -h for additional help
+-----+--------------+-------------------------------------------------------------
,→-------+

,→ |
+=====+==============+====================================================================+
| 1 | generate | Generate NVS partition ␣
,→ |
+-----+--------------+-------------------------------------------------------------
,→-------+
| 2 | generate-key | Generate keys for encryption ␣

,→ |
+-----+--------------+-------------------------------------------------------------
,→-------+
To generate factory images for each device (Default): Usage:
python mfg_gen.py generate [-h] [--fileid FILEID] [--version {1,2}] [--keygen]

[--keyfile KEYFILE] [--inputkey INPUTKEY]
[--outdir OUTDIR]
conf values prefix size
Positional Arguments:
+--------------+---------------------------------------------------------------
,→-------+
| Parameter | Description ␣
,→ |
+==============+======================================================================+
| conf | Path to configuration csv file to parse ␣
,→ |
+--------------+---------------------------------------------------------------
,→-------+
| values | Path to values csv file to parse ␣

,→ |
+--------------+---------------------------------------------------------------
,→-------+
| prefix | Unique name for each output filename prefix ␣

,→ |
+-----+--------------+---------------------------------------------------------
,→-------+
| size | Size of NVS partition in bytes ␣

,→ |
| | (must be multiple of 4096) ␣
,→ |


+--------------+---------------------------------------------------------------
,→-------+
Optional Arguments:
+---------------------+--------------------------------------------------------
,→------------+
,→ |
+=====================+====================================================================+
| -h, --help | show this help message and exit ␣
,→ |
+---------------------+--------------------------------------------------------
,→------------+
| --fileid FILEID | Unique file identifier(any key in values file) ␣

,→ |
| | for each filename suffix (Default: numeric value(1,
,→2,3...) |
+---------------------+--------------------------------------------------------
,→------------+
| --version {1,2} | Set multipage blob version. ␣

,→ |
| | Version 1 - Multipage blob support disabled. ␣
,→ |
| | Version 2 - Multipage blob support enabled. ␣
,→ |
| | Default: Version 2 ␣
,→ |
+---------------------+--------------------------------------------------------
,→------------+
| --keygen | Generates key for encrypting NVS partition ␣

,→ |
+---------------------+--------------------------------------------------------
,→------------+
| --inputkey INPUTKEY | File having key for encrypting NVS partition ␣

,→ |
+---------------------+--------------------------------------------------------
,→------------+
| --outdir OUTDIR | Output directory to store files created ␣

,→ |
| | (Default: current directory) ␣
,→ |
+---------------------+--------------------------------------------------------
,→------------+
You can run the utility to generate factory images for each device using the command below. A sample CSV file is
provided with the utility:
python mfg_gen.py generate samples/sample_config.csv samples/sample_values_

,→singlepage_blob.csv Sample 0x3000
The master value CSV file should have the path in the file type relative to the directory from which you are running
the utility.
To generate encrypted factory images for each device:
You can run the utility to encrypt factory images for each device using the command below. A sample CSV file is
provided with the utility:
• Encrypt by allowing the utility to generate encryption keys:

,→singlepage_blob.csv Sample 0x3000 --keygen

Note: Encryption key of the following format <outdir>/keys/keys-<prefix>-<fileid>.bin is cre-

ated.
Note: This newly created file having encryption keys in keys/ directory is compatible with NVS key-partition
structure. Refer to NVS key partition for more details.
• Encrypt by providing the encryption keys as input binary file:

,→singlepage_blob.csv Sample 0x3000 --inputkey keys/sample_keys.bin
To generate only encryption keys: Usage:
python mfg_gen.py generate-key [-h] [--keyfile KEYFILE] [--outdir OUTDIR]
Optional Arguments:
+--------------------+---------------------------------------------------------
,→-------------+
,→ |
+====================+======================================================================+
,→ |
+--------------------+---------------------------------------------------------
,→-------------+
| --keyfile KEYFILE | Path to output encryption keys file ␣

,→ |
+--------------------+---------------------------------------------------------
,→-------------+
| --outdir OUTDIR | Output directory to store files created. ␣

,→ |
,→ |
+--------------------+---------------------------------------------------------
,→-------------+
You can run the utility to generate only encryption keys using the command below:
python mfg_gen.py generate-key
Note: Encryption key of the following format <outdir>/keys/keys-<timestamp>.bin is created.

Timestamp format is: %m-%d_%H-%M.
Note: To provide custom target filename use the keyfile argument.
Generated encryption key binary file can further be used to encrypt factory images created on the per device basis.
The default numeric value: 1,2,3 of the fileid argument corresponds to each line bearing device instance values
in the master value CSV file.
While running the manufacturing utility, the following folders will be created in the specified outdir directory:
• bin/ for storing the generated binary files
• csv/ for storing the generated intermediate CSV files
• keys/ for storing encryption keys (when generating encrypted factory images)

2.6.3 Non-volatile storage library
Introduction
Non-volatile storage (NVS) library is designed to store key-value pairs in flash. This section introduces some concepts
used by NVS.
Underlying storage Currently, NVS uses a portion of main flash memory through the esp_partition API. The
library uses all the partitions with data type and nvs subtype. The application can choose to use the partition
with the label nvs through the nvs_open() API function or any other partition by specifying its name using the
nvs_open_from_partition() API function.
Future versions of this library may have other storage backends to keep data in another flash chip (SPI or I2C), RTC,
FRAM, etc.
Note: if an NVS partition is truncated (for example, when the partition table layout is changed), its contents should
be erased. ESP-IDF build system provides a idf.py erase-flash target to erase all contents of the flash chip.
Note: NVS works best for storing many small values, rather than a few large values of the type string and blob
. If you need to store large blobs or strings, consider using the facilities provided by the FAT filesystem on top of the
wear levelling library.
Keys and values NVS operates on key-value pairs. Keys are ASCII strings; the maximum key length is currently
15 characters. Values can have one of the following types:
• integer types: uint8_t, int8_t, uint16_t, int16_t, uint32_t, int32_t, uint64_t,
int64_t
• zero-terminated string
• variable length binary data (blob)
Note: String values are currently limited to 4000 bytes. This includes the null terminator. Blob values are limited
to 508,000 bytes or 97.6% of the partition size - 4000 bytes, whichever is lower.
Additional types, such as float and double might be added later.

Keys are required to be unique. Assigning a new value to an existing key works as follows:
• If the new value is of the same type as the old one, value is updated.
• If the new value has a different data type, an error is returned.
Data type check is also performed when reading a value. An error is returned if the data type of the read operation
does not match the data type of the value.
Namespaces To mitigate potential conflicts in key names between different components, NVS assigns each key-
value pair to one of namespaces. Namespace names follow the same rules as key names, i.e., the maximum length
is 15 characters. Namespace name is specified in the nvs_open() or nvs_open_from_partition call.
This call returns an opaque handle, which is used in subsequent calls to the nvs_get_*, nvs_set_*, and
nvs_commit() functions. This way, a handle is associated with a namespace, and key names will not collide
with same names in other namespaces. Please note that the namespaces with the same name in different NVS parti-
tions are considered as separate namespaces.

NVS iterators Iterators allow to list key-value pairs stored in NVS, based on specified partition name, namespace,
and data type.
There are the following functions available:
• nvs_entry_find() returns an opaque handle, which is used in subsequent calls to the
nvs_entry_next() and nvs_entry_info() functions.
• nvs_entry_next() returns iterator to the next key-value pair.
• nvs_entry_info() returns information about each key-value pair
If none or no other key-value pair was found for given criteria, nvs_entry_find() and nvs_entry_next()
return NULL. In that case, the iterator does not have to be released. If the iterator is no longer needed, you can
release it by using the function nvs_release_iterator().
Security, tampering, and robustness NVS is not directly compatible with the ESP32 flash encryption system.
However, data can still be stored in encrypted form if NVS encryption is used together with ESP32 flash encryption.
Please refer to NVS Encryption for more details.
If NVS encryption is not used, it is possible for anyone with physical access to the flash chip to alter, erase, or add
key-value pairs. With NVS encryption enabled, it is not possible to alter or add a key-value pair and get recognized
as a valid pair without knowing corresponding NVS encryption keys. However, there is no tamper-resistance against
the erase operation.
The library does try to recover from conditions when flash memory is in an inconsistent state. In particular, one
should be able to power off the device at any point and time and then power it back on. This should not result in loss
of data, except for the new key-value pair if it was being written at the moment of powering off. The library should
also be able to initialize properly with any random data present in flash memory.
NVS Encryption
Data stored in NVS partitions can be encrypted using AES-XTS in the manner similar to the one mentioned in disk
encryption standard IEEE P1619. For the purpose of encryption, each entry is treated as one sector and relative
address of the entry (w.r.t. partition-start) is fed to the encryption algorithm as sector-number. The NVS Encryption
can be enabled by enabling CONFIG_NVS_ENCRYPTION. The keys required for NVS encryption are stored in yet
another partition, which is protected using Flash Encryption. Therefore, enabling Flash Encryption is a prerequisite
for NVS encryption.
The NVS Encryption is enabled by default when Flash Encryption is enabled. This is done because Wi-Fi driver
stores credentials (like SSID and passphrase) in the default NVS partition. It is important to encrypt them as default
choice if platform level encryption is already enabled.
For using NVS encryption, the partition table must contain the NVS key partition. Two partition tables containing the
NVS key partition are provided for NVS encryption under the partition table option (menuconfig->Partition Table).
They can be selected with the project configuration menu (idf.py menuconfig). Please refer to the example
security/flash_encryption for how to configure and use NVS encryption feature.
NVS key partition

An application requiring NVS encryption support needs to be compiled with a key-partition of the type
data and subtype key. This partition should be marked as encrypted and its size should be the minimum
partition size (4KB). Refer to Partition Tables for more details. Two additional partition tables which
contain the NVS key partition are provided under the partition table option (menuconfig->Partition Ta-
ble). They can be directly used for NVS Encryption. The structure of these partitions is depicted below.
+-----------+--------------+-------------+----+
| XTS encryption key (32) |
+---------------------------------------------+
| XTS tweak key (32) |
+---------------------------------------------+


| CRC32 (4) |
+---------------------------------------------+
The XTS encryption keys in the NVS key partition can be generated in one of the following two ways.
1. Generate the keys on the ESP chip:
When NVS encryption is enabled the nvs_flash_init() API function can be used to ini-
tialize the encrypted default NVS partition. The API function internally generates the XTS en-
cryption keys on the ESP chip. The API function finds the first NVS key partition. Then the
API function automatically generates and stores the NVS keys in that partition by making use of
the nvs_flash_generate_keys() API function provided by nvs_flash/include/nvs_flash.h.
New keys are generated and stored only when the respective key partiton is empty. The same key
partition can then be used to read the security configurations for initializing a custom encrypted
NVS partition with help of nvs_flash_secure_init_partition().
The API functions nvs_flash_secure_init() and nvs_flash_secure_init_partition()
do not generate the keys internally. When these API functions are used for initial-
izing encrypted NVS partitions, the keys can be generated after startup using the
nvs_flash_generate_keys() API function provided by nvs_flash.h. The API
function will then write those keys onto the key-partition in encrypted form.
2. Use pre-generated key partition:
This option will be required by the user when keys in the NVS key partition are not generated by the
application. The NVS key partition containing the XTS encryption keys can be generated with the
help of NVS Partition Generator Utility. Then the user can store the pre generated key partition on
the flash with help of the following two commands:
i) Build and flash the partition table
idf.py partition-table partition-table-flash
ii) Store the keys in the NVS key partition (on the flash) with the help of parttool.py (see Partition
Tool section in partition-tables for more details)
parttool.py --port /dev/ttyUSB0 --partition-table-offset "nvs_key␣

,→partition offset" write_partition --partition-name="name of nvs_key␣
,→partition" --input "nvs_key partition"
Since the key partition is marked as encrypted and Flash Encryption is enabled, the bootloader will encrypt this
partition using flash encryption key on the first boot.
It is possible for an application to use different keys for different NVS partitions and thereby have multiple key-
partitions. However, it is a responsibility of the application to provide correct key-partition/keys for the purpose of
encryption/decryption.
Encrypted Read/Write The same NVS API functions nvs_get_* or nvs_set_* can be used for reading of,
and writing to an encrypted nvs partition as well.
Encrypt the default NVS partition: To enable encryption for the default NVS partition no additional steps are
necessary. When CONFIG_NVS_ENCRYPTION is enabled, the nvs_flash_init() API function internally per-
forms some additional steps using the first NVS key partition found to enable encryption for the default NVS partition
(refer to the API documentation for more details). Alternatively, nvs_flash_secure_init() API function
can also be used to enable encryption for the default NVS partition.
Encrypt a custom NVS partition: To enable encryption for a custom NVS par-
tition, nvs_flash_secure_init_partition() API function is used instead of
nvs_flash_init_partition().
When nvs_flash_secure_init() and nvs_flash_secure_init_partition() API functions are
used, the applications are expected to follow the steps below in order to perform NVS read/write operations with
encryption enabled.
1. Find key partition and NVS data partition using esp_partition_find* API functions.

2. Populate the nvs_sec_cfg_t struct using the nvs_flash_read_security_cfg() or

nvs_flash_generate_keys() API functions.
3. Initialise NVS flash partition using the nvs_flash_secure_init() or
nvs_flash_secure_init_partition() API functions.
4. Open a namespace using the nvs_open() or nvs_open_from_partition() API functions.
5. Perform NVS read/write operations using nvs_get_* or nvs_set_*.
6. Deinitialise an NVS partition using nvs_flash_deinit().
NVS Partition Generator Utility
This utility helps generate NVS partition binary files which can be flashed separately on a dedicated partition via a
flashing utility. Key-value pairs to be flashed onto the partition can be provided via a CSV file. For more details,
please refer to NVS Partition Generator Utility.
Application Example
You can find code examples in the storage directory of ESP-IDF examples:
storage/nvs_rw_value
Demonstrates how to read a single integer value from, and write it to NVS.
The value checked in this example holds the number of the ESP32 module restarts. The value s function
as a counter is only possible due to its storing in NVS.
The example also shows how to check if a read / write operation was successful, or if a certain value
has not been initialized in NVS. The diagnostic procedure is provided in plain text to help you track the
program flow and capture any issues on the way.
storage/nvs_rw_blob
Demonstrates how to read a single integer value and a blob (binary large object), and write them to NVS
to preserve this value between ESP32 module restarts.
• value - tracks the number of the ESP32 module soft and hard restarts.
• blob - contains a table with module run times. The table is read from NVS to dynamically allocated
RAM. A new run time is added to the table on each manually triggered soft restart, and then the
added run time is written to NVS. Triggering is done by pulling down GPIO0.
The example also shows how to implement the diagnostic procedure to check if the read / write operation
was successful.
storage/nvs_rw_value_cxx
This example does exactly the same as storage/nvs_rw_value, except that it uses the C++ NVS handle
class.
Internals
Log of key-value pairs NVS stores key-value pairs sequentially, with new key-value pairs being added at the end.
When a value of any given key has to be updated, a new key-value pair is added at the end of the log and the old
key-value pair is marked as erased.
Pages and entries NVS library uses two main entities in its operation: pages and entries. Page is a logical structure
which stores a portion of the overall log. Logical page corresponds to one physical sector of flash memory. Pages
which are in use have a sequence number associated with them. Sequence numbers impose an ordering on pages.
Higher sequence numbers correspond to pages which were created later. Each page can be in one of the following
states:
Empty/uninitialized Flash storage for the page is empty (all bytes are 0xff). Page is not used to store any data at
this point and does not have a sequence number.

Active Flash storage is initialized, page header has been written to flash, page has a valid sequence number. Page
has some empty entries and data can be written there. No more than one page can be in this state at any given
moment.
Full Flash storage is in a consistent state and is filled with key-value pairs. Writing new key-value pairs into this
page is not possible. It is still possible to mark some key-value pairs as erased.
Erasing Non-erased key-value pairs are being moved into another page so that the current page can be erased. This
is a transient state, i.e., page should never stay in this state at the time when any API call returns. In case of a
sudden power off, the move-and-erase process will be completed upon the next power-on.
Corrupted Page header contains invalid data, and further parsing of page data was canceled. Any items previously
written into this page will not be accessible. The corresponding flash sector will not be erased immediately and
will be kept along with sectors in uninitialized state for later use. This may be useful for debugging.
Mapping from flash sectors to logical pages does not have any particular order. The library will inspect sequence
numbers of pages found in each flash sector and organize pages in a list based on these numbers.
+--------+ +--------+ +--------+ +--------+

| Page 1 | | Page 2 | | Page 3 | | Page 4 |
| Full +---> | Full +---> | Active | | Empty | <- states
| #11 | | #12 | | #14 | | | <- sequence numbers
+---+----+ +----+---+ +----+---+ +---+----+
| | | |
| | | |
| | | |
+---v------+ +-----v----+ +------v---+ +------v---+
| Sector 3 | | Sector 0 | | Sector 2 | | Sector 1 | <- physical sectors
+----------+ +----------+ +----------+ +----------+
Structure of a page For now, we assume that flash sector size is 4096 bytes and that ESP32 flash encryption
hardware operates on 32-byte blocks. It is possible to introduce some settings configurable at compile-time (e.g., via
menuconfig) to accommodate flash chips with different sector sizes (although it is not clear if other components in
the system, e.g., SPI flash driver and SPI flash cache can support these other sizes).
Page consists of three parts: header, entry state bitmap, and entries themselves. To be compatible with ESP32 flash
encryption, the entry size is 32 bytes. For integer types, an entry holds one key-value pair. For strings and blobs, an
entry holds part of key-value pair (more on that in the entry structure description).
The following diagram illustrates the page structure. Numbers in parentheses indicate the size of each part in bytes.
+-----------+--------------+-------------+-------------------------+
| State (4) | Seq. no. (4) | version (1) | Unused (19) | CRC32 (4) | Header (32)
+-----------+--------------+-------------+-------------------------+
| Entry state bitmap (32) |
+------------------------------------------------------------------+
| Entry 0 (32) |
+------------------------------------------------------------------+
| Entry 1 (32) |
+------------------------------------------------------------------+
/ /
/ /
+------------------------------------------------------------------+
| Entry 125 (32) |
+------------------------------------------------------------------+
Page header and entry state bitmap are always written to flash unencrypted. Entries are encrypted if flash encryption
feature of ESP32 is used.
Page state values are defined in such a way that changing state is possible by writing 0 into some of the bits. Therefore
it is not necessary to erase the page to change its state unless that is a change to the erased state.
The version field in the header reflects the NVS format version used. For backward compatibility reasons, it is
decremented for every version upgrade starting at 0xff (i.e., 0xff for version-1, 0xfe for version-2 and so on).

CRC32 value in the header is calculated over the part which does not include a state value (bytes 4 to 28). The unused
part is currently filled with 0xff bytes.
The following sections describe the structure of entry state bitmap and entry itself.
Entry and entry state bitmap Each entry can be in one of the following three states represented with two bits in
the entry state bitmap. The final four bits in the bitmap (256 - 2 * 126) are not used.
Empty (2 b11) Nothing is written into the specific entry yet. It is in an uninitialized state (all bytes are 0xff).
Written (2 b10) A key-value pair (or part of key-value pair which spans multiple entries) has been written into
the entry.
Erased (2 b00) A key-value pair in this entry has been discarded. Contents of this entry will not be parsed any-
more.
Structure of entry For values of primitive types (currently integers from 1 to 8 bytes long), entry holds one key-
value pair. For string and blob types, entry holds part of the whole key-value pair. For strings, in case when a
key-value pair spans multiple entries, all entries are stored in the same page. Blobs are allowed to span over multiple
pages by dividing them into smaller chunks. For tracking these chunks, an additional fixed length metadata entry is
stored called blob index . Earlier formats of blobs are still supported (can be read and modified). However, once
the blobs are modified, they are stored using the new format.
+--------+----------+----------+----------------+-----------+---------------+------
,→----+
| NS (1) | Type (1) | Span (1) | ChunkIndex (1) | CRC32 (4) | Key (16) | Data␣
,→(8) |
+--------+----------+----------+----------------+-----------+---------------+------
,→----+
Primitive +------------------------------
,→ --+
+--------> | Data (8) ␣
,→ |
| Types +------------------------------
,→ --+
+-> Fixed length --
| | +---------+--------------+-----
,→----------+-------+
| +--------> | Size(4) | ChunkCount(1)|␣

,→ChunkStart(1) | Rsv(2)|
Data format ---+ Blob Index +---------+--------------+-----

,→----------+-------+
|
| +----------+---------+-----------+
+-> Variable length --> | Size (2) | Rsv (2) | CRC32 (4) |
(Strings, Blob Data) +----------+---------+-----------+
Individual fields in entry structure have the following meanings:

NS Namespace index for this entry. For more information on this value, see the section on namespaces implemen-
tation.
Type One byte indicating the value data type. See the ItemType enumeration in nvs_flash/include/nvs_handle.hpp
for possible values.
Span Number of entries used by this key-value pair. For integer types, this is equal to 1. For strings and blobs, this
depends on value length.
ChunkIndex Used to store the index of a blob-data chunk for blob types. For other types, this should be 0xff.
CRC32 Checksum calculated over all the bytes in this entry, except for the CRC32 field itself.
Key Zero-terminated ASCII string containing a key name. Maximum string length is 15 bytes, excluding a zero
terminator.
Data For integer types, this field contains the value itself. If the value itself is shorter than 8 bytes, it is padded to
the right, with unused bytes filled with 0xff.

For blob index entry, these 8 bytes hold the following information about data-chunks:
• Size (Only for blob index.) Size, in bytes, of complete blob data.
• ChunkCount (Only for blob index.) Total number of blob-data chunks into which the blob was divided
during storage.
• ChunkStart (Only for blob index.) ChunkIndex of the first blob-data chunk of this blob. Subsequent
chunks have chunkIndex incrementally allocated (step of 1).
For string and blob data chunks, these 8 bytes hold additional data about the value, which are described below:
• Size (Only for strings and blobs.) Size, in bytes, of actual data. For strings, this includes zero terminators.
• CRC32 (Only for strings and blobs.) Checksum calculated over all bytes of data.
Variable length values (strings and blobs) are written into subsequent entries, 32 bytes per entry. The Span field of
the first entry indicates how many entries are used.
Namespaces As mentioned above, each key-value pair belongs to one of the namespaces. Namespace identifiers
(strings) are stored as keys of key-value pairs in namespace with index 0. Values corresponding to these keys are
indexes of these namespaces.
+-------------------------------------------+
| NS=0 Type=uint8_t Key="wifi" Value=1 | Entry describing namespace "wifi"
+-------------------------------------------+
| NS=1 Type=uint32_t Key="channel" Value=6 | Key "channel" in namespace "wifi"
+-------------------------------------------+
| NS=0 Type=uint8_t Key="pwm" Value=2 | Entry describing namespace "pwm"
+-------------------------------------------+
| NS=2 Type=uint16_t Key="channel" Value=20 | Key "channel" in namespace "pwm"
+-------------------------------------------+
Item hash list To reduce the number of reads from flash memory, each member of the Page class maintains a list
of pairs: item index; item hash. This list makes searches much quicker. Instead of iterating over all entries, reading
them from flash one at a time, Page::findItem first performs a search for the item hash in the hash list. This gives the
item index within the page if such an item exists. Due to a hash collision, it is possible that a different item will be
found. This is handled by falling back to iteration over items in flash.
Each node in the hash list contains a 24-bit hash and 8-bit item index. Hash is calculated based on item namespace,
key name, and ChunkIndex. CRC32 is used for calculation; the result is truncated to 24 bits. To reduce the overhead
for storing 32-bit entries in a linked list, the list is implemented as a double-linked list of arrays. Each array holds
29 entries, for the total size of 128 bytes, together with linked list pointers and a 32-bit count field. The minimum
amount of extra RAM usage per page is therefore 128 bytes; maximum is 640 bytes.
API Reference
Header File
• components/nvs_flash/include/nvs_flash.h
Functions
esp_err_t nvs_flash_init(void)
Initialize the default NVS partition.
This API initialises the default NVS partition. The default NVS partition is the one that is labeled nvs in
the partition table.
When NVS_ENCRYPTION is enabled in the menuconfig, this API enables the NVS encryption for the
default NVS partition as follows
1. Read security configurations from the first NVS key partition listed in the partition table. (NVS key
partition is any data type partition which has the subtype value set to nvs_keys )
2. If the NVS key partiton obtained in the previous step is empty, generate and store new keys in that NVS
key partiton.

3. Internally call nvs_flash_secure_init() with the security configurations obtained/generated in the pre-
vious steps.
Post initialization NVS read/write APIs remain the same irrespective of NVS encryption.
Return
• ESP_OK if storage was successfully initialized.
• ESP_ERR_NVS_NO_FREE_PAGES if the NVS storage contains no empty pages (which may hap-
pen if NVS partition was truncated)
• ESP_ERR_NOT_FOUND if no partition with label nvs is found in the partition table
• ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures
• one of the error codes from the underlying flash storage driver
• error codes from nvs_flash_read_security_cfg API (when NVS_ENCRYPTION is enabled).
• error codes from nvs_flash_generate_keys API (when NVS_ENCRYPTION is enabled).
• error codes from nvs_flash_secure_init_partition API (when NVS_ENCRYPTION is enabled) .
esp_err_t nvs_flash_init_partition(const char *partition_label)
Initialize NVS flash storage for the specified partition.
Return
• ESP_OK if storage was successfully initialized.
• ESP_ERR_NOT_FOUND if specified partition is not found in the partition table
Parameters
• [in] partition_label: Label of the partition. Must be no longer than 16 characters.
esp_err_t nvs_flash_init_partition_ptr(const esp_partition_t *partition)
Initialize NVS flash storage for the partition specified by partition pointer.
Return
• ESP_OK if storage was successfully initialized
• ESP_ERR_INVALID_ARG in case partition is NULL
Parameters
• [in] partition: pointer to a partition obtained by the ESP partition API.
esp_err_t nvs_flash_deinit(void)
Deinitialize NVS storage for the default NVS partition.
Default NVS partition is the partition with nvs label in the partition table.
Return
• ESP_OK on success (storage was deinitialized)
• ESP_ERR_NVS_NOT_INITIALIZED if the storage was not initialized prior to this call
esp_err_t nvs_flash_deinit_partition(const char *partition_label)
Deinitialize NVS storage for the given NVS partition.
Return
• ESP_ERR_NVS_NOT_INITIALIZED if the storage for given partition was not initialized prior to
this call
Parameters
• [in] partition_label: Label of the partition
esp_err_t nvs_flash_erase(void)
Erase the default NVS partition.
Erases all contents of the default NVS partition (one with label nvs ).

Note If the partition is initialized, this function first de-initializes it. Afterwards, the partition has to be ini-
tialized again to be used.
Return
• ESP_ERR_NOT_FOUND if there is no NVS partition labeled nvs in the partition table
• different error in case de-initialization fails (shouldn t happen)
esp_err_t nvs_flash_erase_partition(const char *part_name)
Erase specified NVS partition.
Erase all content of a specified NVS partition
Return
• ESP_ERR_NOT_FOUND if there is no NVS partition with the specified name in the partition table
• different error in case de-initialization fails (shouldn t happen)
Parameters
• [in] part_name: Name (label) of the partition which should be erased
esp_err_t nvs_flash_erase_partition_ptr(const esp_partition_t *partition)
Erase custom partition.
Erase all content of specified custom partition.
Return
• ESP_ERR_NOT_FOUND if there is no partition with the specified parameters in the partition table
• ESP_ERR_INVALID_ARG in case partition is NULL
Parameters
• [in] partition: pointer to a partition obtained by the ESP partition API.
esp_err_t nvs_flash_secure_init(nvs_sec_cfg_t *cfg)
Initialize the default NVS partition.
This API initialises the default NVS partition. The default NVS partition is the one that is labeled nvs in
the partition table.
Return
• ESP_OK if storage has been initialized successfully.
• ESP_ERR_NOT_FOUND if no partition with label nvs is found in the partition table
Parameters
• [in] cfg: Security configuration (keys) to be used for NVS encryption/decryption. If cfg is
NULL, no encryption is used.
esp_err_t nvs_flash_secure_init_partition(const char *partition_label, nvs_sec_cfg_t *cfg)
Initialize NVS flash storage for the specified partition.
Return
• ESP_OK if storage has been initialized successfully.
• ESP_ERR_NOT_FOUND if specified partition is not found in the partition table
Parameters

• [in] partition_label: Label of the partition. Note that internally, a reference to passed
value is kept and it should be accessible for future operations
• [in] cfg: Security configuration (keys) to be used for NVS encryption/decryption. If cfg is null,
no encryption/decryption is used.
esp_err_t nvs_flash_generate_keys(const esp_partition_t *partition, nvs_sec_cfg_t *cfg)
Generate and store NVS keys in the provided esp partition.
Return -ESP_OK, if cfg was read successfully; -ESP_INVALID_ARG, if partition or cfg; -or error codes
from esp_partition_write/erase APIs.
Parameters
• [in] partition: Pointer to partition structure obtained using esp_partition_find_first or
esp_partition_get. Must be non-NULL.
• [out] cfg: Pointer to nvs security configuration structure. Pointer must be non-NULL. Gener-
ated keys will be populated in this structure.
esp_err_t nvs_flash_read_security_cfg(const esp_partition_t *partition, nvs_sec_cfg_t *cfg)
Read NVS security configuration from a partition.
Note Provided partition is assumed to be marked encrypted .
Return -ESP_OK, if cfg was read successfully; -ESP_INVALID_ARG, if partition or cfg; -
ESP_ERR_NVS_KEYS_NOT_INITIALIZED, if the partition is not yet written with keys. -
ESP_ERR_NVS_CORRUPT_KEY_PART, if the partition containing keys is found to be corrupt -or
error codes from esp_partition_read API.
Parameters
• [in] partition: Pointer to partition structure obtained using esp_partition_find_first or
• [out] cfg: Pointer to nvs security configuration structure. Pointer must be non-NULL.
Structures
struct nvs_sec_cfg_t
Key for encryption and decryption.
Public Members
uint8_t eky[NVS_KEY_SIZE]
XTS encryption and decryption key
uint8_t tky[NVS_KEY_SIZE]
XTS tweak key
Macros
NVS_KEY_SIZE
Header File
• components/nvs_flash/include/nvs.h
Functions
esp_err_t nvs_set_i8(nvs_handle_t handle, const char *key, int8_t value)
set int8_t value for given key
Set value for the key, given its name. Note that the actual storage will not be updated until nvs_commit is
called.
Return
• ESP_OK if value was set successfully
• ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL

• ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only

• ESP_ERR_NVS_INVALID_NAME if key name doesn t satisfy constraints
• ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the underlying storage
to save the value
• ESP_ERR_NVS_REMOVE_FAILED if the value wasn t updated because flash write operation
has failed. The value was written however, and update will be finished after re-initialization of nvs,
provided that flash operation doesn t fail again.
Parameters
• [in] handle: Handle obtained from nvs_open function. Handles that were opened read only
cannot be used.
• [in] key: Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters.
Shouldn t be empty.
• [in] value: The value to set.
esp_err_t nvs_set_u8(nvs_handle_t handle, const char *key, uint8_t value)
set uint8_t value for given key
This function is the same as nvs_set_i8 except for the data type.
esp_err_t nvs_set_str(nvs_handle_t handle, const char *key, const char *value)
set string for given key
Set value for the key, given its name. Note that the actual storage will not be updated until nvs_commit is
called.
Return
•
ESP_OK if value was set successfully
•
ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
•
ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
•
ESP_ERR_NVS_INVALID_NAME if key name doesn t satisfy constraints
•
ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the underlying storage
to save the value
• ESP_ERR_NVS_VALUE_TOO_LONG if the string value is too long
Parameters

cannot be used.
Shouldn t be empty.
• [in] value: The value to set. For strings, the maximum length (including null character) is 4000
bytes, if there is one complete page free for writing. This decreases, however, if the free space is
fragmented.
esp_err_t nvs_get_i8(nvs_handle_t handle, const char *key, int8_t *out_value)
get int8_t value for given key
These functions retrieve value for the key, given its name. If key does not exist, or the requested variable type
doesn t match the type which was used when setting a value, an error is returned.
In case of any error, out_value is not modified.
out_value has to be a pointer to an already allocated variable of the given type.
// Example of using nvs_get_i32:

int32_t max_buffer_size = 4096; // default value
esp_err_t err = nvs_get_i32(my_handle, "max_buffer_size", &max_buffer_size);
assert(err == ESP_OK || err == ESP_ERR_NVS_NOT_FOUND);
// if ESP_ERR_NVS_NOT_FOUND was returned, max_buffer_size will still
// have its default value.
Return
• ESP_OK if the value was retrieved successfully
• ESP_ERR_NVS_NOT_FOUND if the requested key doesn t exist
• ESP_ERR_NVS_INVALID_LENGTH if length is not sufficient to store data
Parameters
• [in] handle: Handle obtained from nvs_open function.
Shouldn t be empty.
• out_value: Pointer to the output value. May be NULL for nvs_get_str and nvs_get_blob, in this
case required length will be returned in length argument.
esp_err_t nvs_get_u8(nvs_handle_t handle, const char *key, uint8_t *out_value)
get uint8_t value for given key
This function is the same as nvs_get_i8 except for the data type.


esp_err_t nvs_get_str(nvs_handle_t handle, const char *key, char *out_value, size_t *length)
get string value for given key
These functions retrieve the data of an entry, given its key. If key does not exist, or the requested variable type
doesn t match the type which was used when setting a value, an error is returned.
In case of any error, out_value is not modified.
All functions expect out_value to be a pointer to an already allocated variable of the given type.
nvs_get_str and nvs_get_blob functions support WinAPI-style length queries. To get the size necessary to
store the value, call nvs_get_str or nvs_get_blob with zero out_value and non-zero pointer to length. Variable
pointed to by length argument will be set to the required length. For nvs_get_str, this length includes the zero
terminator. When calling nvs_get_str and nvs_get_blob with non-zero out_value, length has to be non-zero and
has to point to the length available in out_value. It is suggested that nvs_get/set_str is used for zero-terminated
C strings, and nvs_get/set_blob used for arbitrary data structures.
// Example (without error checking) of using nvs_get_str to get a string into␣

,→dynamic array:
size_t required_size;
nvs_get_str(my_handle, "server_name", NULL, &required_size);
char* server_name = malloc(required_size);
nvs_get_str(my_handle, "server_name", server_name, &required_size);
// Example (without error checking) of using nvs_get_blob to get a binary data

into a static array:
uint8_t mac_addr[6];
size_t size = sizeof(mac_addr);
nvs_get_blob(my_handle, "dst_mac_addr", mac_addr, &size);
Return
• ESP_OK if the value was retrieved successfully
• ESP_ERR_NVS_INVALID_LENGTH if length is not sufficient to store data
Parameters
Shouldn t be empty.
• [out] out_value: Pointer to the output value. May be NULL for nvs_get_str and
nvs_get_blob, in this case required length will be returned in length argument.
• [inout] length: A non-zero pointer to the variable holding the length of out_value. In case
out_value a zero, will be set to the length required to hold the value. In case out_value is not zero,
will be set to the actual length of the value written. For nvs_get_str this includes zero terminator.
esp_err_t nvs_get_blob(nvs_handle_t handle, const char *key, void *out_value, size_t *length)
get blob value for given key
This function behaves the same as nvs_get_str, except for the data type.
esp_err_t nvs_open(const char *name, nvs_open_mode_t open_mode, nvs_handle_t *out_handle)
Open non-volatile storage with a given namespace from the default NVS partition.
Multiple internal ESP-IDF and third party application modules can store their key-value pairs in the NVS
module. In order to reduce possible conflicts on key names, each module can use its own namespace. The
default NVS partition is the one that is labelled nvs in the partition table.
Return
• ESP_OK if storage handle was opened successfully

• ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized

• ESP_ERR_NVS_PART_NOT_FOUND if the partition with label nvs is not found
• ESP_ERR_NVS_NOT_FOUND id namespace doesn t exist yet and mode is NVS_READONLY
• ESP_ERR_NVS_INVALID_NAME if namespace name doesn t satisfy constraints
• other error codes from the underlying storage driver
Parameters
• [in] name: Namespace name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) charac-
ters. Shouldn t be empty.
• [in] open_mode: NVS_READWRITE or NVS_READONLY. If NVS_READONLY, will
open a handle for reading only. All write requests will be rejected for this handle.
• [out] out_handle: If successful (return code is zero), handle will be returned in this argument.
esp_err_t nvs_open_from_partition(const char *part_name, const char *name,
nvs_open_mode_t open_mode, nvs_handle_t *out_handle)
Open non-volatile storage with a given namespace from specified partition.
The behaviour is same as nvs_open() API. However this API can operate on a specified NVS partition
instead of default NVS partition. Note that the specified partition must be registered with NVS using
nvs_flash_init_partition() API.
Return
• ESP_OK if storage handle was opened successfully
• ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized
• ESP_ERR_NVS_PART_NOT_FOUND if the partition with specified name is not found
• ESP_ERR_NVS_NOT_FOUND id namespace doesn t exist yet and mode is NVS_READONLY
• ESP_ERR_NVS_INVALID_NAME if namespace name doesn t satisfy constraints
Parameters
• [in] part_name: Label (name) of the partition of interest for object read/write/erase
• [in] name: Namespace name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) charac-
ters. Shouldn t be empty.
• [in] open_mode: NVS_READWRITE or NVS_READONLY. If NVS_READONLY, will
open a handle for reading only. All write requests will be rejected for this handle.
• [out] out_handle: If successful (return code is zero), handle will be returned in this argument.
esp_err_t nvs_set_blob(nvs_handle_t handle, const char *key, const void *value, size_t length)
set variable length binary value for given key
This family of functions set value for the key, given its name. Note that actual storage will not be updated until
nvs_commit function is called.
Return
•
ESP_OK if value was set successfully
•
ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
•
ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
•
ESP_ERR_NVS_INVALID_NAME if key name doesn t satisfy constraints
•
ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the underlying storage
to save the value
• ESP_ERR_NVS_VALUE_TOO_LONG if the value is too long
Parameters
cannot be used.
Shouldn t be empty.
• [in] value: The value to set.
• [in] length: length of binary value to set, in bytes; Maximum length is 508000 bytes or (97.6%

of the partition size - 4000) bytes whichever is lower.

esp_err_t nvs_erase_key(nvs_handle_t handle, const char *key)
Erase key-value pair with given key name.
Note that actual storage may not be updated until nvs_commit function is called.
Return
• ESP_OK if erase operation was successful
• ESP_ERR_NVS_READ_ONLY if handle was opened as read only
Parameters
• [in] handle: Storage handle obtained with nvs_open. Handles that were opened read only
cannot be used.
Shouldn t be empty.
esp_err_t nvs_erase_all(nvs_handle_t handle)
Erase all key-value pairs in a namespace.
Note that actual storage may not be updated until nvs_commit function is called.
Return
• ESP_OK if erase operation was successful
• ESP_ERR_NVS_READ_ONLY if handle was opened as read only
Parameters
cannot be used.
esp_err_t nvs_commit(nvs_handle_t handle)
Write any pending changes to non-volatile storage.
After setting any values, nvs_commit() must be called to ensure changes are written to non-volatile storage.
Individual implementations may write to storage at other times, but this is not guaranteed.
Return
• ESP_OK if the changes have been written successfully
Parameters
cannot be used.
void nvs_close(nvs_handle_t handle)
Close the storage handle and free any allocated resources.
This function should be called for each handle opened with nvs_open once the handle is not in use any more.
Closing the handle may not automatically write the changes to nonvolatile storage. This has to be done explicitly
using nvs_commit function. Once this function is called on a handle, the handle should no longer be used.
Parameters
• [in] handle: Storage handle to close
esp_err_t nvs_get_stats(const char *part_name, nvs_stats_t *nvs_stats)
Fill structure nvs_stats_t. It provides info about used memory the partition.
This function calculates to runtime the number of used entries, free entries, total entries, and amount namespace
in partition.

// Example of nvs_get_stats() to get the number of used entries and free␣

,→entries:
nvs_stats_t nvs_stats;
nvs_get_stats(NULL, &nvs_stats);
printf("Count: UsedEntries = (%d), FreeEntries = (%d), AllEntries = (%d)\n",
nvs_stats.used_entries, nvs_stats.free_entries, nvs_stats.total_
,→entries);
Return
• ESP_OK if the changes have been written successfully. Return param nvs_stats will be filled.
• ESP_ERR_NVS_PART_NOT_FOUND if the partition with label name is not found. Return
param nvs_stats will be filled 0.
• ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized. Return param
nvs_stats will be filled 0.
• ESP_ERR_INVALID_ARG if nvs_stats equal to NULL.
• ESP_ERR_INVALID_STATE if there is page with the status of INVALID. Return param nvs_stats
will be filled not with correct values because not all pages will be counted. Counting will be inter-
rupted at the first INVALID page.
Parameters
• [in] part_name: Partition name NVS in the partition table. If pass a NULL than will use
NVS_DEFAULT_PART_NAME ( nvs ).
• [out] nvs_stats: Returns filled structure nvs_states_t. It provides info about used memory
the partition.
esp_err_t nvs_get_used_entry_count(nvs_handle_t handle, size_t *used_entries)
Calculate all entries in a namespace.
An entry represents the smallest storage unit in NVS. Strings and blobs may occupy more than one entry.
Note that to find out the total number of entries occupied by the namespace, add one to the returned value
used_entries (if err is equal to ESP_OK). Because the name space entry takes one entry.
// Example of nvs_get_used_entry_count() to get amount of all key-value pairs␣

,→in one namespace:
nvs_handle_t handle;
nvs_open("namespace1", NVS_READWRITE, &handle);
...
size_t used_entries;
size_t total_entries_namespace;
if(nvs_get_used_entry_count(handle, &used_entries) == ESP_OK){
// the total number of entries occupied by the namespace
total_entries_namespace = used_entries + 1;
}
Return
• ESP_OK if the changes have been written successfully. Return param used_entries will be filled
valid value.
• ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized. Return param
used_entries will be filled 0.
• ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL. Return param
used_entries will be filled 0.
• ESP_ERR_INVALID_ARG if used_entries equal to NULL.
• Other error codes from the underlying storage driver. Return param used_entries will be filled 0.
Parameters
• [out] used_entries: Returns amount of used entries from a namespace.
nvs_iterator_t nvs_entry_find(const char *part_name, const char *namespace_name, nvs_type_t
type)
Create an iterator to enumerate NVS entries based on one or more parameters.

// Example of listing all the key-value pairs of any type under specified␣
,→partition and namespace
nvs_iterator_t it = nvs_entry_find(partition, namespace, NVS_TYPE_ANY);

while (it != NULL) {
nvs_entry_info_t info;
nvs_entry_info(it, &info);
it = nvs_entry_next(it);
printf("key '%s', type '%d' \n", info.key, info.type);
};
// Note: no need to release iterator obtained from nvs_entry_find function when
// nvs_entry_find or nvs_entry_next function return NULL, indicating no␣
,→other
// element for specified criteria was found.

}
Return Iterator used to enumerate all the entries found, or NULL if no entry satisfying criteria was found.
Iterator obtained through this function has to be released using nvs_release_iterator when not used any
more.
Parameters
• [in] part_name: Partition name
• [in] namespace_name: Set this value if looking for entries with a specific namespace. Pass
NULL otherwise.
• [in] type: One of nvs_type_t values.
nvs_iterator_t nvs_entry_next(nvs_iterator_t iterator)
Returns next item matching the iterator criteria, NULL if no such item exists.
Note that any copies of the iterator will be invalid after this call.
Return NULL if no entry was found, valid nvs_iterator_t otherwise.
Parameters
• [in] iterator: Iterator obtained from nvs_entry_find function. Must be non-NULL.
void nvs_entry_info(nvs_iterator_t iterator, nvs_entry_info_t *out_info)
Fills nvs_entry_info_t structure with information about entry pointed to by the iterator.
Parameters
• [in] iterator: Iterator obtained from nvs_entry_find or nvs_entry_next function. Must be
non-NULL.
• [out] out_info: Structure to which entry information is copied.
void nvs_release_iterator(nvs_iterator_t iterator)
Release iterator.
Parameters
• [in] iterator: Release iterator obtained from nvs_entry_find function. NULL argument is
allowed.
Structures
struct nvs_entry_info_t
information about entry obtained from nvs_entry_info function
Public Members
char namespace_name[16]
Namespace to which key-value belong
char key[16]
Key of stored key-value pair
nvs_type_t type
Type of stored key-value pair

struct nvs_stats_t
Note Info about storage space NVS.
Public Members
size_t used_entries
Amount of used entries.
size_t free_entries
Amount of free entries.
size_t total_entries
Amount all available entries.
size_t namespace_count
Amount name space.
Macros
ESP_ERR_NVS_BASE
Starting number of error codes
ESP_ERR_NVS_NOT_INITIALIZED
The storage driver is not initialized
ESP_ERR_NVS_NOT_FOUND
Id namespace doesn t exist yet and mode is NVS_READONLY
ESP_ERR_NVS_TYPE_MISMATCH
The type of set or get operation doesn t match the type of value stored in NVS
ESP_ERR_NVS_READ_ONLY
Storage handle was opened as read only
ESP_ERR_NVS_NOT_ENOUGH_SPACE
There is not enough space in the underlying storage to save the value
ESP_ERR_NVS_INVALID_NAME
Namespace name doesn t satisfy constraints
ESP_ERR_NVS_INVALID_HANDLE
Handle has been closed or is NULL
ESP_ERR_NVS_REMOVE_FAILED
The value wasn t updated because flash write operation has failed. The value was written however, and update
will be finished after re-initialization of nvs, provided that flash operation doesn t fail again.
ESP_ERR_NVS_KEY_TOO_LONG
Key name is too long
ESP_ERR_NVS_PAGE_FULL
Internal error; never returned by nvs API functions
ESP_ERR_NVS_INVALID_STATE
NVS is in an inconsistent state due to a previous error. Call nvs_flash_init and nvs_open again, then retry.
ESP_ERR_NVS_INVALID_LENGTH
String or blob length is not sufficient to store data
ESP_ERR_NVS_NO_FREE_PAGES
NVS partition doesn t contain any empty pages. This may happen if NVS partition was truncated. Erase the
whole partition and call nvs_flash_init again.
ESP_ERR_NVS_VALUE_TOO_LONG
String or blob length is longer than supported by the implementation

ESP_ERR_NVS_PART_NOT_FOUND
Partition with specified name is not found in the partition table
ESP_ERR_NVS_NEW_VERSION_FOUND
NVS partition contains data in new format and cannot be recognized by this version of code
ESP_ERR_NVS_XTS_ENCR_FAILED
XTS encryption failed while writing NVS entry
ESP_ERR_NVS_XTS_DECR_FAILED
XTS decryption failed while reading NVS entry
ESP_ERR_NVS_XTS_CFG_FAILED
XTS configuration setting failed
ESP_ERR_NVS_XTS_CFG_NOT_FOUND
XTS configuration not found
ESP_ERR_NVS_ENCR_NOT_SUPPORTED
NVS encryption is not supported in this version
ESP_ERR_NVS_KEYS_NOT_INITIALIZED
NVS key partition is uninitialized
ESP_ERR_NVS_CORRUPT_KEY_PART
NVS key partition is corrupt
ESP_ERR_NVS_WRONG_ENCRYPTION
NVS partition is marked as encrypted with generic flash encryption. This is forbidden since the NVS encryption
works differently.
ESP_ERR_NVS_CONTENT_DIFFERS
Internal error; never returned by nvs API functions. NVS key is different in comparison
NVS_DEFAULT_PART_NAME
Default partition name of the NVS partition in the partition table
NVS_PART_NAME_MAX_SIZE
maximum length of partition name (excluding null terminator)
NVS_KEY_NAME_MAX_SIZE
Maximal length of NVS key name (including null terminator)
Type Definitions
typedef uint32_t nvs_handle_t
Opaque pointer type representing non-volatile storage handle
typedef nvs_handle_t nvs_handle
typedef nvs_open_mode_t nvs_open_mode
typedef struct nvs_opaque_iterator_t *nvs_iterator_t
Opaque pointer type representing iterator to nvs entries
Enumerations
enum nvs_open_mode_t
Mode of opening the non-volatile storage.
Values:
NVS_READONLY
Read only
NVS_READWRITE
Read and write

enum nvs_type_t
Types of variables.
Values:
NVS_TYPE_U8 = 0x01
Type uint8_t
NVS_TYPE_I8 = 0x11
Type int8_t
NVS_TYPE_U16 = 0x02
Type uint16_t
NVS_TYPE_I16 = 0x12
Type int16_t
NVS_TYPE_U32 = 0x04
Type uint32_t
NVS_TYPE_I32 = 0x14
Type int32_t
NVS_TYPE_U64 = 0x08
Type uint64_t
NVS_TYPE_I64 = 0x18
Type int64_t
NVS_TYPE_STR = 0x21
Type string
NVS_TYPE_BLOB = 0x42
Type blob
NVS_TYPE_ANY = 0xff
Must be last
2.6.4 NVS Partition Generator Utility
Introduction
The utility nvs_flash/nvs_partition_generator/nvs_partition_gen.py creates a binary file based on key-value pairs pro-
vided in a CSV file. The binary file is compatible with NVS architecture defined in Non-Volatile Storage. This utility
is ideally suited for generating a binary blob, containing data specific to ODM/OEM, which can be flashed externally
at the time of device manufacturing. This allows manufacturers to generate many instances of the same application
firmware with customized parameters for each device, such as a serial number.
Prerequisites
To use this utility in encryption mode, install the following packages:

• cryptography package
All the required packages are included in requirements.txt in the root of the esp-idf directory.
CSV file format
Each line of a .csv file should contain 4 parameters, separated by a comma. The table below provides the description
for each of these parameters.

No. Pa- Description Notes

ram-
e-
ter
1 Key Key of the data. The data can be accessed later from an appli-
cation using this key.
2 Type Supported values are file, data and namespace.
3 En- Supported values are: u8, i8, u16, i16, u32, i32, u64, As of now, for the file
cod- i64, string, hex2bin, base64 and binary. This type, only hex2bin, base64,
ing specifies how actual data values are encoded in the resulting bi- string, and binary encoding
nary file. The difference between the string and binary is supported.
encoding is that string data is terminated with a NULL
character, whereas binary data is not.
4 Value Data value. Encoding and Value cells for the
namespace field type should be
empty. Encoding and Value of
namespace is fixed and is not
configurable. Any values in these
cells are ignored.
Note: The first line of the CSV file should be the column header and it is not configurable. Comments (if provided)
are allowed only as the first line of the CSV file, the following line then should always be the column header. Comments
should always start with the # symbol.
Below is an example dump of such a CSV file:
key,type,encoding,value <-- column header

namespace_name,namespace,, <-- First entry should be of type "namespace"
key1,data,u8,1
key2,file,string,/path/to/file
Note:
Make sure there are no spaces:
• before and after ,
• at the end of each line in a CSV file
NVS Entry and Namespace association
When a namespace entry is encountered in a CSV file, each following entry will be treated as part of that namespace
until the next namespace entry is found. At this point, all the following entries will be treated as part of the new
namespace.
Note: First entry in a CSV file should always be a namespace entry.
Multipage Blob Support
By default, binary blobs are allowed to span over multiple pages and are written in the format mentioned in Section
Structure of entry. If you intend to use an older format, the utility provides an option to disable this feature.

Encryption Support
The NVS Partition Generator utility also allows you to create an encrypted binary file. The utility uses the AES-XTS
encryption. Please refer to NVS Encryption for more details.
Decryption Support
This utility allows you to decrypt an encrypted NVS binary file. The utility uses an NVS binary file encrypted using
AES-XTS encryption. Please refer to NVS Encryption for more details.
Running the utility
Usage:
python nvs_partition_gen.py [-h] {generate,generate-key,encrypt,decrypt} ...
Optional Arguments:
+-----+------------+---------------------------------------------------------------
,→-------+

,→ |
+=====+============+======================================================================+
| 1 | -h, --help | show this help message and exit ␣
,→ |
+-----+------------+---------------------------------------------------------------
,→-------+
Commands:
Run nvs_partition_gen.py {command} -h for additional help
+-----+--------------+-------------------------------------------------------------
,→-------+

,→ |
+=====+==============+====================================================================+
| 1 | generate | Generate NVS partition ␣
,→ |
+-----+--------------+-------------------------------------------------------------
,→-------+
| 2 | generate-key | Generate keys for encryption ␣

,→ |
+-----+--------------+-------------------------------------------------------------
,→-------+
| 3 | encrypt | Generate NVS encrypted partition ␣

,→ |
+-----+--------------+-------------------------------------------------------------
,→-------+
| 4 | decrypt | Decrypt NVS encrypted partition ␣

,→ |
+-----+--------------+-------------------------------------------------------------
,→-------+
To generate NVS partition (Default):

Usage:
python nvs_partition_gen.py generate [-h] [--version {1,2}] [--outdir␣
,→OUTDIR]
input output size


+--------------+----------------------------------------------------------
,→------------+
,→ |
+==============+======================================================================+
| input | Path to CSV file to parse ␣
,→ |
+--------------+----------------------------------------------------------
,→------------+
| output | Path to output NVS binary file ␣

,→ |
+--------------+----------------------------------------------------------
,→------------+
| size | Size of NVS partition in bytes (must be multiple␣

,→of 4096) |
+--------------+----------------------------------------------------------
,→------------+
Optional Arguments:
+-----------------+-------------------------------------------------------
,→-------------+
,→ |
+=================+====================================================================+
,→ |
+-----------------+-------------------------------------------------------
,→-------------+

,→ |
,→ |
,→ |
,→ |
| | ␣
,→ |
+-----------------+-------------------------------------------------------
,→-------------+

,→ |
,→ |
+-----------------+-------------------------------------------------------
,→-------------+
You can run the utility to generate NVS partition using the command below: A sample CSV file is provided with the
utility:
python nvs_partition_gen.py generate sample_singlepage_blob.csv sample.bin 0x3000
To generate only encryption keys:

Usage:
python nvs_partition_gen.py generate-key [-h] [--keyfile KEYFILE]

[--outdir OUTDIR]

Optional Arguments:
+--------------------+----------------------------------------------------
,→------------------+
,→ |
+====================+======================================================================+
,→ |
+--------------------+----------------------------------------------------
,→------------------+

,→ |
+--------------------+----------------------------------------------------
,→------------------+
| --outdir OUTDIR | Output directory to store files created. ␣

,→ |
,→ |
+--------------------+----------------------------------------------------
,→------------------+
You can run the utility to generate only encryption keys using the command below:
python nvs_partition_gen.py generate-key
To generate encrypted NVS partition:

Usage:
python nvs_partition_gen.py encrypt [-h] [--version {1,2}] [--keygen]
[--keyfile KEYFILE] [--inputkey␣
,→INPUTKEY]
[--outdir OUTDIR]
input output size
+--------------+----------------------------------------------------------
,→------------+
,→ |
+==============+======================================================================+
| input | Path to CSV file to parse ␣
,→ |
+--------------+----------------------------------------------------------
,→------------+
| output | Path to output NVS binary file ␣

,→ |
+--------------+----------------------------------------------------------
,→------------+
| size | Size of NVS partition in bytes (must be multiple␣

,→of 4096) |
+--------------+----------------------------------------------------------
,→------------+
Optional Arguments:
+---------------------+---------------------------------------------------
,→-----------------+
,→ |


+=====================+====================================================================+
,→ |
| | ␣
,→ |
+---------------------+---------------------------------------------------
,→-----------------+

,→ |
,→ |
,→ |
,→ |
+---------------------+---------------------------------------------------
,→-----------------+
| --keygen | Generates key for encrypting NVS partition ␣

,→ |
+---------------------+---------------------------------------------------
,→-----------------+

,→ |
+---------------------+---------------------------------------------------
,→-----------------+
| --inputkey INPUTKEY | File having key for encrypting NVS partition ␣

,→ |
+---------------------+---------------------------------------------------
,→-----------------+

,→ |
,→ |
+---------------------+---------------------------------------------------
,→-----------------+
You can run the utility to encrypt NVS partition using the command below: A sample CSV file is provided with the
utility:
• Encrypt by allowing the utility to generate encryption keys:
python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin␣
,→0x3000 --keygen
Note: Encryption key of the following format <outdir>/keys/keys-<timestamp>.bin is created.
• Encrypt by allowing the utility to generate encryption keys and store it in provided custom filename:
,→0x3000 --keygen --keyfile sample_keys.bin
Note: Encryption key of the following format <outdir>/keys/sample_keys.bin is created.
Note: This newly created file having encryption keys in keys/ directory is compatible with NVS key-partition
structure. Refer to NVS key partition for more details.
• Encrypt by providing the encryption keys as input binary file:


,→0x3000 --inputkey sample_keys.bin
To decrypt encrypted NVS partition:

Usage:
python nvs_partition_gen.py decrypt [-h] [--outdir OUTDIR] input key␣

,→output
+--------------+----------------------------------------------------------
,→------------+
,→ |
+==============+======================================================================+
| input | Path to encrypted NVS partition file to parse ␣
,→ |
+--------------+----------------------------------------------------------
,→------------+
| key | Path to file having keys for decryption ␣

,→ |
+--------------+----------------------------------------------------------
,→------------+
| output | Path to output decrypted binary file ␣

,→ |
+--------------+----------------------------------------------------------
,→------------+
Optional Arguments:
+---------------------+---------------------------------------------------
,→-----------------+
,→ |
+=====================+====================================================================+
,→ |
+---------------------+---------------------------------------------------
,→-----------------+

,→ |
,→ |
+---------------------+---------------------------------------------------
,→-----------------+
You can run the utility to decrypt encrypted NVS partition using the command below:
python nvs_partition_gen.py decrypt sample_encr.bin sample_keys.bin sample_decr.bin
You can also provide the format version number:

• Multipage Blob Support Disabled (Version 1)
• Multipage Blob Support Enabled (Version 2)
Multipage Blob Support Disabled (Version 1): You can run the utility in this format by setting the version
parameter to 1, as shown below. A sample CSV file is provided with the utility:
python nvs_partition_gen.py generate sample_singlepage_blob.csv sample.bin 0x3000 -

,→-version 1

Multipage Blob Support Enabled (Version 2): You can run the utility in this format by setting the version pa-
rameter to 2, as shown below. A sample CSV file is provided with the utility:
python nvs_partition_gen.py generate sample_multipage_blob.csv sample.bin 0x4000 --

,→version 2
Note: Minimum NVS Partition Size needed is 0x3000 bytes.
Note: When flashing the binary onto the device, make sure it is consistent with the application s sdkconfig.
Caveats
• Utility does not check for duplicate keys and will write data pertaining to both keys. You need to make sure
that the keys are distinct.
• Once a new page is created, no data will be written in the space left on the previous page. Fields in the CSV
file need to be ordered in such a way as to optimize memory.
• Utility supports using multiline strings with file type and singleline strings with data type in the CSV file.
• 64-bit datatype is not yet supported.
2.6.5 SD/SDIO/MMC Driver
Overview
The SD/SDIO/MMC driver currently supports SD memory, SDIO cards, and eMMC chips. This is a protocol level
driver built on top of SDMMC and SD SPI host drivers.
SDMMC and SD SPI host drivers (driver/include/driver/sdmmc_host.h and driver/include/driver/sdspi_host.h) pro-
vide API functions for:
• Sending commands to slave devices
• Sending and receiving data
• Handling error conditions within the bus
For functions used to initialize and configure:
• SDMMC host, see SDMMC Host API
• SD SPI host, see SD SPI Host API
The SDMMC protocol layer described in this document handles the specifics of the SD protocol, such as the card
initialization and data transfer commands.
The protocol layer works with the host via the sdmmc_host_t structure. This structure contains pointers to various
functions of the host.
Application Example
An example which combines the SDMMC driver with the FATFS library is provided in the storage/sd_card directory
of ESP-IDF examples. This example initializes the card, then writes and reads data from it using POSIX and C library
APIs. See README.md file in the example directory for more information.
Combo (memory + IO) cards The driver does not support SD combo cards. Combo cards are treated as IO cards.

Thread safety Most applications need to use the protocol layer only in one task. For this reason, the protocol layer
does not implement any kind of locking on the sdmmc_card_t structure, or when accessing SDMMC or SD SPI
host drivers. Such locking is usually implemented on a higher layer, e.g., in the filesystem driver.
Protocol layer API
The protocol layer is given the sdmmc_host_t structure. This structure describes the SD/MMC host driver, lists
its capabilities, and provides pointers to functions of the driver. The protocol layer stores card-specific information in
the sdmmc_card_t structure. When sending commands to the SD/MMC host driver, the protocol layer uses the
sdmmc_command_t structure to describe the command, arguments, expected return values, and data to transfer if
there is any.
Using API with SD memory cards

1. To initialize the host, call the host driver functions, e.g., sdmmc_host_init(), sd-
mmc_host_init_slot().
2. To initialize the card, call sdmmc_card_init() and pass to it the parameters host - the host driver
information, and card - a pointer to the structure sdmmc_card_t which will be filled with information
about the card when the function completes.
3. To read and write sectors of the card, use sdmmc_read_sectors() and sdmmc_write_sectors()
respectively and pass to it the parameter card - a pointer to the card information structure.
4. If the card is not used anymore, call the host driver function - e.g., sdmmc_host_deinit() - to disable
the host peripheral and free the resources allocated by the driver.
Using API with eMMC chips From the protocol layer s perspective, eMMC memory chips behave exactly like
SD memory cards. Even though eMMCs are chips and do not have a card form factor, the terminology for SD cards
can still be applied to eMMC due to the similarity of the protocol (sdmmc_card_t, sdmmc_card_init). Note that
eMMC chips cannot be used over SPI, which makes them incompatible with the SD SPI host driver.
To initialize eMMC memory and perform read/write operations, follow the steps listed for SD cards in the previous
section.
Using API with SDIO cards Initialization and the probing process is the same as with SD memory cards. The
only difference is in data transfer commands in SDIO mode.
During the card initialization and probing, performed with sdmmc_card_init(), the driver only configures the
following registers of the IO card:
1. The IO portion of the card is reset by setting RES bit in the I/O Abort (0x06) register.
2. If 4-line mode is enabled in host and slot configuration, the driver attempts to set the Bus width field in the Bus
Interface Control (0x07) register. If setting the filed is successful, which means that the slave supports 4-line
mode, the host is also switched to 4-line mode.
3. If high-speed mode is enabled in the host configuration, the SHS bit is set in the High Speed (0x13) register.
In particular, the driver does not set any bits in (1) I/O Enable and Int Enable registers, (2) I/O block sizes, etc.
Applications can set them by calling sdmmc_io_write_byte().
For card configuration and data transfer, choose the pair of functions relevant to your case from the table below.
Action Read Function Write Function

Read and write a single byte using IO_RW_DIRECT sdmmc_io_read_byte()
sdmmc_io_write_byte()
(CMD52)
Read and write multiple bytes using IO_RW_EXTENDED sdmmc_io_read_bytes()
sdmmc_io_write_bytes()
(CMD53) in byte mode
Read and write blocks of data using IO_RW_EXTENDED sdmmc_io_read_blocks()
sdmmc_io_write_blocks()
(CMD53) in block mode

SDIO interrupts can be enabled by the application using the function sdmmc_io_enable_int(). When using
SDIO in 1-line mode, the D1 line also needs to be connected to use SDIO interrupts.
If you want the application to wait until the SDIO interrupt occurs, use sdmmc_io_wait_int().
There is a component ESSL (ESP Serial Slave Link) to use if you are communicating with an ESP32 SDIO slave.
See ESP Serial Slave Link and example peripherals/sdio/host.
API Reference
Header File
• components/sdmmc/include/sdmmc_cmd.h
Functions
esp_err_t sdmmc_card_init(const sdmmc_host_t *host, sdmmc_card_t *out_card)
Probe and initialize SD/MMC card using given host
Note Only SD cards (SDSC and SDHC/SDXC) are supported now. Support for MMC/eMMC cards will be
added later.
Return
Parameters
• host: pointer to structure defining host controller
• out_card: pointer to structure which will receive information about the card when the function
completes
void sdmmc_card_print_info(FILE *stream, const sdmmc_card_t *card)
Print information about the card to a stream.
Parameters
• stream: stream obtained using fopen or fdopen
• card: card information structure initialized using sdmmc_card_init
esp_err_t sdmmc_get_status(sdmmc_card_t *card)
Get status of SD/MMC card
Return
Parameters
• card: pointer to card information structure previously initialized using sdmmc_card_init
esp_err_t sdmmc_write_sectors(sdmmc_card_t *card, const void *src, size_t start_sector, size_t sec-
tor_count)
Write given number of sectors to SD/MMC card
Return
Parameters
• src: pointer to data buffer to read data from; data size must be equal to sector_count * card-
>csd.sector_size
• start_sector: sector where to start writing
• sector_count: number of sectors to write
esp_err_t sdmmc_read_sectors(sdmmc_card_t *card, void *dst, size_t start_sector, size_t sec-
tor_count)
Read given number of sectors from the SD/MMC card
Return


Parameters
• dst: pointer to data buffer to write into; buffer size must be at least sector_count * card-
>csd.sector_size
• start_sector: sector where to start reading
• sector_count: number of sectors to read
esp_err_t sdmmc_io_read_byte(sdmmc_card_t *card, uint32_t function, uint32_t reg, uint8_t
*out_byte)
Read one byte from an SDIO card using IO_RW_DIRECT (CMD52)
Return
Parameters
• function: IO function number
• reg: byte address within IO function
• [out] out_byte: output, receives the value read from the card
esp_err_t sdmmc_io_write_byte(sdmmc_card_t *card, uint32_t function, uint32_t reg, uint8_t in_byte,
uint8_t *out_byte)
Write one byte to an SDIO card using IO_RW_DIRECT (CMD52)
Return
Parameters
• reg: byte address within IO function
• in_byte: value to be written
• [out] out_byte: if not NULL, receives new byte value read from the card (read-after-write).
esp_err_t sdmmc_io_read_bytes(sdmmc_card_t *card, uint32_t function, uint32_t addr, void *dst,
size_t size)
Read multiple bytes from an SDIO card using IO_RW_EXTENDED (CMD53)
This function performs read operation using CMD53 in byte mode. For block mode, see sd-
mmc_io_read_blocks.
Return
• ESP_ERR_INVALID_SIZE if size exceeds 512 bytes
Parameters
• addr: byte address within IO function where reading starts
• dst: buffer which receives the data read from card
• size: number of bytes to read
esp_err_t sdmmc_io_write_bytes(sdmmc_card_t *card, uint32_t function, uint32_t addr, const void
*src, size_t size)
Write multiple bytes to an SDIO card using IO_RW_EXTENDED (CMD53)
This function performs write operation using CMD53 in byte mode. For block mode, see sd-
mmc_io_write_blocks.
Return
• ESP_ERR_INVALID_SIZE if size exceeds 512 bytes

Parameters
• addr: byte address within IO function where writing starts
• src: data to be written
• size: number of bytes to write
esp_err_t sdmmc_io_read_blocks(sdmmc_card_t *card, uint32_t function, uint32_t addr, void *dst,
size_t size)
Read blocks of data from an SDIO card using IO_RW_EXTENDED (CMD53)
This function performs read operation using CMD53 in block mode. For byte mode, see sd-
mmc_io_read_bytes.
Return
• ESP_ERR_INVALID_SIZE if size is not divisible by 512 bytes
Parameters
• dst: buffer which receives the data read from card
• size: number of bytes to read, must be divisible by the card block size.
esp_err_t sdmmc_io_write_blocks(sdmmc_card_t *card, uint32_t function, uint32_t addr, const
void *src, size_t size)
Write blocks of data to an SDIO card using IO_RW_EXTENDED (CMD53)
This function performs write operation using CMD53 in block mode. For byte mode, see sd-
mmc_io_write_bytes.
Return
• ESP_ERR_INVALID_SIZE if size is not divisible by 512 bytes
Parameters
• src: data to be written
• size: number of bytes to read, must be divisible by the card block size.
esp_err_t sdmmc_io_enable_int(sdmmc_card_t *card)
Enable SDIO interrupt in the SDMMC host
Return
• ESP_ERR_NOT_SUPPORTED if the host controller does not support IO interrupts
Parameters
esp_err_t sdmmc_io_wait_int(sdmmc_card_t *card, TickType_t timeout_ticks)
Block until an SDIO interrupt is received
Slave uses D1 line to signal interrupt condition to the host. This function can be used to wait for the interrupt.
Return
• ESP_OK if the interrupt is received
• ESP_ERR_NOT_SUPPORTED if the host controller does not support IO interrupts
• ESP_ERR_TIMEOUT if the interrupt does not happen in timeout_ticks
Parameters
• timeout_ticks: time to wait for the interrupt, in RTOS ticks

esp_err_t sdmmc_io_get_cis_data(sdmmc_card_t *card, uint8_t *out_buffer, size_t buffer_size,

size_t *inout_cis_size)
Get the data of CIS region of a SDIO card.
You may provide a buffer not sufficient to store all the CIS data. In this case, this functions store as much data
into your buffer as possible. Also, this function will try to get and return the size required for you.
Return
• ESP_ERR_INVALID_RESPONSE: if the card does not (correctly) support CIS.
• ESP_ERR_INVALID_SIZE: CIS_CODE_END found, but buffer_size is less than required size,
which is stored in the inout_cis_size then.
• ESP_ERR_NOT_FOUND: if the CIS_CODE_END not found. Increase input value of in-
out_cis_size or set it to 0, if you still want to search for the end; output value of inout_cis_size
is invalid in this case.
• and other error code return from sdmmc_io_read_bytes
Parameters
• out_buffer: Output buffer of the CIS data
• buffer_size: Size of the buffer.
• inout_cis_size: Mandatory, pointer to a size, input and output.
– input: Limitation of maximum searching range, should be 0 or larger than buffer_size. The
function searches for CIS_CODE_END until this range. Set to 0 to search infinitely.
– output: The size required to store all the CIS data, if CIS_CODE_END is found.
esp_err_t sdmmc_io_print_cis_info(uint8_t *buffer, size_t buffer_size, FILE *fp)
Parse and print the CIS information of a SDIO card.
Note Not all the CIS codes and all kinds of tuples are supported. If you see some unresolved code, you can
add the parsing of these code in sdmmc_io.c and contribute to the IDF through the Github repository.
using sdmmc_card_init
Return
• ESP_ERR_NOT_SUPPORTED: if the value from the card is not supported to be parsed.
• ESP_ERR_INVALID_SIZE: if the CIS size fields are not correct.
Parameters
• buffer: Buffer to parse
• buffer_size: Size of the buffer.
• fp: File pointer to print to, set to NULL to print to stdout.
Header File
• components/driver/include/driver/sdmmc_types.h
Structures
struct sdmmc_csd_t
Decoded values from SD card Card Specific Data register
Public Members
int csd_ver
CSD structure format
int mmc_ver
MMC version (for CID format)
int capacity
total number of sectors

int sector_size
sector size in bytes
int read_block_len
block length for reads
int card_command_class
Card Command Class for SD
int tr_speed
Max transfer speed
struct sdmmc_cid_t
Decoded values from SD card Card IDentification register
Public Members
int mfg_id
manufacturer identification number
int oem_id
OEM/product identification number
char name[8]
product name (MMC v1 has the longest)
int revision
product revision
int serial
product serial number
int date
manufacturing date
struct sdmmc_scr_t
Decoded values from SD Configuration Register
Public Members
int sd_spec
SD Physical layer specification version, reported by card
int bus_width
bus widths supported by card: BIT(0) 1-bit bus, BIT(2) 4-bit bus
struct sdmmc_ext_csd_t
Decoded values of Extended Card Specific Data
Public Members
uint8_t power_class
Power class used by the card
struct sdmmc_switch_func_rsp_t
SD SWITCH_FUNC response buffer
Public Members
uint32_t data[512 / 8 / sizeof(uint32_t)]

response data

struct sdmmc_command_t
SD/MMC command information
Public Members
uint32_t opcode
SD or MMC command index
uint32_t arg
SD/MMC command argument
sdmmc_response_t response
response buffer
void *data
buffer to send or read into
size_t datalen
length of data buffer
size_t blklen
block length
int flags
see below
esp_err_t error
error returned from transfer
int timeout_ms
response timeout, in milliseconds
struct sdmmc_host_t
SD/MMC Host description
This structure defines properties of SD/MMC host and functions of SD/MMC host which can be used by upper
layers.
Public Members
uint32_t flags
flags defining host properties
int slot
slot number, to be passed to host functions
int max_freq_khz
max frequency supported by the host
float io_voltage
I/O voltage used by the controller (voltage switching is not supported)
esp_err_t (*init)(void)
Host function to initialize the driver
esp_err_t (*set_bus_width)(int slot, size_t width)
host function to set bus width
size_t (*get_bus_width)(int slot)
host function to get bus width
esp_err_t (*set_bus_ddr_mode)(int slot, bool ddr_enable)
host function to set DDR mode
esp_err_t (*set_card_clk)(int slot, uint32_t freq_khz)
host function to set card clock frequency

esp_err_t (*do_transaction)(int slot, sdmmc_command_t *cmdinfo)

host function to do a transaction
esp_err_t (*deinit)(void)
host function to deinitialize the driver
esp_err_t (*deinit_p)(int slot)
host function to deinitialize the driver, called with the slot
esp_err_t (*io_int_enable)(int slot)
Host function to enable SDIO interrupt line
esp_err_t (*io_int_wait)(int slot, TickType_t timeout_ticks)
Host function to wait for SDIO interrupt line to be active
int command_timeout_ms
timeout, in milliseconds, of a single command. Set to 0 to use the default value.
struct sdmmc_card_t
SD/MMC card information structure
Public Members
sdmmc_host_t host
Host with which the card is associated
uint32_t ocr
OCR (Operation Conditions Register) value
sdmmc_cid_t cid
decoded CID (Card IDentification) register value
sdmmc_response_t raw_cid
raw CID of MMC card to be decoded after the CSD is fetched in the data transfer mode
sdmmc_csd_t csd
decoded CSD (Card-Specific Data) register value
sdmmc_scr_t scr
decoded SCR (SD card Configuration Register) value
sdmmc_ext_csd_t ext_csd
decoded EXT_CSD (Extended Card Specific Data) register value
uint16_t rca
RCA (Relative Card Address)
uint16_t max_freq_khz
Maximum frequency, in kHz, supported by the card
uint32_t is_mem : 1
Bit indicates if the card is a memory card
uint32_t is_sdio : 1
Bit indicates if the card is an IO card
uint32_t is_mmc : 1
Bit indicates if the card is MMC
uint32_t num_io_functions : 3
If is_sdio is 1, contains the number of IO functions on the card
uint32_t log_bus_width : 2
log2(bus width supported by card)
uint32_t is_ddr : 1
Card supports DDR mode

Reserved for future expansion
Macros
SDMMC_HOST_FLAG_1BIT
host supports 1-line SD and MMC protocol
host supports 4-line SD and MMC protocol
host supports 8-line MMC protocol
SDMMC_HOST_FLAG_SPI
host supports SPI protocol
SDMMC_HOST_FLAG_DDR
host supports DDR mode for SD/MMC
SDMMC_HOST_FLAG_DEINIT_ARG
host deinit function called with the slot argument
SDMMC_FREQ_DEFAULT
SD/MMC Default speed (limited by clock divider)
SDMMC_FREQ_HIGHSPEED
SD High speed (limited by clock divider)
SDMMC_FREQ_PROBING
SD/MMC probing speed
SDMMC_FREQ_52M
MMC 52MHz speed
SDMMC_FREQ_26M
MMC 26MHz speed
Type Definitions
typedef uint32_t sdmmc_response_t[4]
SD/MMC command response buffer
2.6.6 SPI Flash API
Overview
The spi_flash component contains API functions related to reading, writing, erasing, memory mapping for data in
the external flash. The spi_flash component also has higher-level API functions which work with partitions defined
in the partition table.
Different from the API before IDF v4.0, the functionality of esp_flash_* APIs is not limited to the main SPI flash
chip (the same SPI flash chip from which program runs). With different chip pointers, you can access to external
flash chips connected to not only SPI0/1 but also other SPI buses like SPI2.
Note: Instead of through the cache connected to the SPI0 peripheral, most esp_flash_* APIs go through other SPI
peripherals like SPI1, SPI2, etc.. This makes them able to access to not only the main flash, but also external flash.
However due to limitations of the cache, operations through the cache are limited to the main flash. The address
range limitation for these operations are also on the cache side. The cache is not able to access external flash chips
or address range above its capabilities. These cache operations include: mmap, encrypted read/write, executing code
or access to variables in the flash.

Note: Flash APIs after IDF v4.0 are no longer atomic. A writing operation during another on-going read operation,
on the overlapped flash address, may cause the return data from the read operation to be partly same as before, and
partly updated as new written.
Kconfig option CONFIG_SPI_FLASH_USE_LEGACY_IMPL can be used to switch spi_flash_* functions back

to the implementation before ESP-IDF v4.0. However, the code size may get bigger if you use the new API and the
old API at the same time.
Encrypted reads and writes use the old implementation, even if CONFIG_SPI_FLASH_USE_LEGACY_IMPL is not
enabled. As such, encrypted flash operations are only supported with the main flash chip (and not with other flash
chips, that is on SPI1 with different CS, or on other SPI buses). Reading through cache is only supported on the main
flash, which is determined by the HW.
Support for features of flash chips
Flash features of different vendors are operated in different ways and need special support. The fast/slow read and
Dual mode (DOUT/DIO) of almost all 24-bits address flash chips are supported, because they don t need any
vendor-specific commands.
Quad mode (QIO/QOUT) is supported on following chip types:
1. ISSI
2. GD
3. MXIC
4. FM
5. Winbond
6. XMC
7. BOYA
The 32-bit address range of following chip type is supported:
1. W25Q256
2. GD25Q256
Users can also customize their own flash chip driver, see Overriding Default Chip Drivers for more details.
Warning: Customizing SPI Flash Chip Drivers is considered an expert feature. Users should only do so at
their own risk. (See the notes below)
Overriding Default Chip Drivers During the SPI Flash driver s initialization (i.e., esp_flash_init()),
there is a chip detection step during which the driver will iterate through a Default Chip Driver List and determine
which chip driver can properly support the currently connected flash chip. The Default Chip Drivers are provided by
the IDF, thus are updated in together with each IDF version. However IDF also allows users to customize their own
chip drivers.
Users should note the following when customizing chip drivers:
1. You may need to rely on some non-public IDF functions, which have slight possibility to change between IDF
versions. On the one hand, these changes may be useful bug fixes for your driver, on the other hand, they may
also be breaking changes (i.e., breaks your code).
2. Some IDF bug fixes to other chip drivers will not be automatically applied to your own custom chip drivers.
3. If the protection of flash is not handled properly, there may be some random reliability issues.
4. If you update to a newer IDF version that has support for more chips, you will have to manually add those new
chip drivers into your custom chip driver list. Otherwise the driver will only search for the drivers in custom
list you provided.

Steps For Creating Custom Chip Drivers and Overriding the IDF Default Driver List
1. Enable the CONFIG_SPI_FLASH_OVERRIDE_CHIP_DRIVER_LIST config option. This will prevent compila-
tion and linking of the Default Chip Driver List (default_registered_chips) provided by IDF. Instead, the linker
will search for the structure of the same name (default_registered_chips) that must be provided by the user.
2. Add a new component in your project, e.g. custom_chip_driver.
3. Copy the necessary chip driver files from the spi_flash component in IDF. This may include:
• spi_flash_chip_drivers.c (to provide the default_registered_chips structure)
• Any of the spi_flash_chip_*.c files that matches your own flash model best
• CMakeLists.txt and linker.lf files
Modify the files above properly.
Note:
• When writing your own flash chip driver, you can set your flash chip capabilities through
spi_flash_chip_***(vendor)_get_caps and points the function pointer get_chip_caps for protection to
the spi_flash_chip_***_get_caps function. The steps are as follows.
1. Please check whether your flash chip have the capabilities listed in spi_flash_caps_t by check-
ing the flash datasheet.
2. Write a function named spi_flash_chip_***(vendor)_get_caps. Take the example below as a
reference. (if the flash support suspend and read unique id).
3. Points the the pointer get_chip_caps (in spi_flash_chip_t) to the function mentioned above.
spi_flash_caps_t spi_flash_chip_***(vendor)_get_caps(esp_flash_t *chip)

{
spi_flash_caps_t caps_flags = 0;
// 32-bit-address flash is not supported
flash-suspend is supported
caps_flags |= SPI_FLAHS_CHIP_CAP_SUSPEND;
// flash read unique id.
caps_flags |= SPI_FLASH_CHIP_CAP_UNIQUE_ID;
return caps_flags;
}
const spi_flash_chip_t esp_flash_chip_eon = {

// Other function pointers
.get_chip_caps = spi_flash_chip_eon_get_caps,
};
• You also can see how to implement this in the example storage/custom_flash_driver.
4. Add linking dependency from spi_flash component to the new custom_chip_driver component, by adding the
following lines after the idf_component_register, in the CMakeLists.txt file of the custom_chip_driver compo-
nent:
idf_component_get_property(spi_flash_lib spi_flash COMPONENT_LIB)
set_property(TARGET ${spi_flash_lib} APPEND PROPERTY INTER-
FACE_LINK_LIBRARIES $<LINK_ONLY:${COMPONENT_LIB}>)
5. The linker.lf is used to put every chip driver that you are going to use whilst cache is disabled into internal
RAM. See Linker Script Generation for more details. Make sure this file covers all the source files that you add.
6. Build your project, and you will see the new flash driver is used.
Example See also storage/custom_flash_driver.
Initializing a flash device
To use esp_flash_* APIs, you need to have a chip initialized on a certain SPI bus.
1. Call spi_bus_initialize() to properly initialize an SPI bus. This functions initialize the resources
(I/O, DMA, interrupts) shared among devices attached to this bus.

2. Call spi_bus_add_flash_device() to attach the flash device onto the bus. This allocates memory,
and fill the members for the esp_flash_t structure. The CS I/O is also initialized here.
3. Call esp_flash_init() to actually communicate with the chip. This will also detect the chip type, and
influence the following operations.
Note: Multiple flash chips can be attached to the same bus now. However, using esp_flash_* devices and
spi_device_* devices on the same SPI bus is not supported yet.
SPI flash access API
This is the set of API functions for working with data in flash:
• esp_flash_read() reads data from flash to RAM
• esp_flash_write() writes data from RAM to flash
• esp_flash_erase_region() erases specific region of flash
• esp_flash_erase_chip() erases the whole flash
• esp_flash_get_chip_size() returns flash chip size, in bytes, as configured in menuconfig
Generally, try to avoid using the raw SPI flash functions to the main SPI flash chip in favour of partition-specific
functions.
SPI Flash Size
The SPI flash size is configured by writing a field in the software bootloader image header, flashed at offset 0x1000.
By default, the SPI flash size is detected by esptool.py when this bootloader is written to flash, and the header
is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting CON-
FIG_ESPTOOLPY_FLASHSIZE in project configuration.
If it is necessary to override the configured flash size at runtime, it is possible to set the chip_size member of
the g_rom_flashchip structure. This size is used by esp_flash_* functions (in both software & ROM) to
check the bounds.
Concurrency Constraints for flash on SPI1
Concurrency Constraints for flash on SPI1 The SPI0/1 bus is shared between the instruction & data cache
(for firmware execution) and the SPI1 peripheral (controlled by the drivers including this SPI Flash driver). Hence,
operations to SPI1 will cause significant influence to the whole system. This kind of operations include calling SPI
Flash API or other drivers on SPI1 bus, any operations like read/write/erase or other user defined SPI operations,
regardless to the main flash or other SPI slave devices.
On ESP32, these caches must be disabled while reading/writing/erasing.
When the caches are disabled This means that all CPUs must be running code from IRAM and must only be
reading data from DRAM while flash write operations occur. If you use the API functions documented here, then the
caches will be disabled automatically and transparently. However, note that it will have some performance impact on
other tasks in the system.
There are no such constraints and impacts for flash chips on other SPI buses than SPI0/1.
For differences between IRAM, DRAM, and flash cache, please refer to the application memory layout documenta-
tion.
To avoid reading flash cache accidentally, when one CPU initiates a flash write or erase operation, the other CPU is put
into a blocked state, and all non-IRAM-safe interrupts are disabled on all CPUs until the flash operation completes.
See also OS functions, SPI Bus Lock.

IRAM-Safe Interrupt Handlers If you have an interrupt handler that you want to execute while a flash operation
is in progress (for example, for low latency operations), set the ESP_INTR_FLAG_IRAM flag when the interrupt
handler is registered.
You must ensure that all data and functions accessed by these interrupt handlers, including the ones that handlers call,
are located in IRAM or DRAM. See How to place code in IRAM.
If a function or symbol is not correctly put into IRAM/DRAM, and the interrupt handler reads from the flash cache
during a flash operation, it will cause a crash due to Illegal Instruction exception (for code which should be in IRAM)
or garbage data to be read (for constant data which should be in DRAM).
Note: When working with string in ISRs, it is not advised to use printf and other output functions. For debugging
purposes, use ESP_DRAM_LOGE() and similar macros when logging from ISRs. Make sure that both TAG and
format string are placed into DRAM in that case.
Attention: The SPI0/1 bus is shared between the instruction & data cache (for firmware execution) and the SPI1
peripheral (controlled by the drivers including this SPI flash driver). Hence, calling SPI Flash API on SPI1 bus
(including the main flash) will cause significant influence to the whole system. See Concurrency Constraints for
flash on SPI1 for more details.
Partition table API
ESP-IDF projects use a partition table to maintain information about various regions of SPI flash memory (bootloader,
various application binaries, data, filesystems). More information on partition tables can be found here.
This component provides API functions to enumerate partitions found in the partition table and perform operations
on them. These functions are declared in esp_partition.h:
• esp_partition_find() checks a partition table for entries with specific type, returns an opaque iterator.
• esp_partition_get() returns a structure describing the partition for a given iterator.
• esp_partition_next() shifts the iterator to the next found partition.
• esp_partition_iterator_release() releases iterator returned by esp_partition_find.
• esp_partition_find_first() - a convenience function which returns the structure describing the
first partition found by esp_partition_find.
• esp_partition_read(), esp_partition_write(), esp_partition_erase_range()
are equivalent to spi_flash_read(), spi_flash_write(), spi_flash_erase_range(), but
operate within partition boundaries.
Note: Application code should mostly use these esp_partition_* API functions instead of lower level
esp_flash_* API functions. Partition table API functions do bounds checking and calculate correct offsets in
flash, based on data stored in a partition table.
SPI Flash Encryption
It is possible to encrypt the contents of SPI flash and have it transparently decrypted by hardware.
Refer to the Flash Encryption documentation for more details.
Memory mapping API
ESP32 features memory hardware which allows regions of flash memory to be mapped into instruction and data
address spaces. This mapping works only for read operations. It is not possible to modify contents of flash memory
by writing to a mapped memory region.

Mapping happens in 64 KB pages. Memory mapping hardware can map flash into the data address space and the
instruction address space. See the technical reference manual for more details and limitations about memory mapping
hardware.
Note that some pages are used to map the application itself into memory, so the actual number of available pages
may be less than the capability of the hardware.
Reading data from flash using a memory mapped region is the only way to decrypt contents of flash when flash
encryption is enabled. Decryption is performed at the hardware level.
Memory mapping API are declared in esp_spi_flash.h and esp_partition.h:
• spi_flash_mmap() maps a region of physical flash addresses into instruction space or data space of the
CPU.
• spi_flash_munmap() unmaps previously mapped region.
• esp_partition_mmap() maps part of a partition into the instruction space or data space of the CPU.
Differences between spi_flash_mmap() and esp_partition_mmap() are as follows:
• spi_flash_mmap() must be given a 64 KB aligned physical address.
• esp_partition_mmap() may be given any arbitrary offset within the partition, it will adjust the returned
pointer to mapped memory as necessary.
Note that since memory mapping happens in pages, it may be possible to read data outside of the partition provided
to esp_partition_mmap, regardless of the partition boundary.
Note: mmap is supported by cache, so it can only be used on main flash.
SPI Flash Implementation
The esp_flash_t structure holds chip data as well as three important parts of this API:
1. The host driver, which provides the hardware support to access the chip;
2. The chip driver, which provides compatibility service to different chips;
3. The OS functions, provides support of some OS functions (e.g. lock, delay) in different stages (1st/2st boot, or
the app).
Host driver The host driver relies on an interface (spi_flash_host_driver_t) defined in the
spi_flash_types.h (in the hal/include/hal folder). This interface provides some common functions to
communicate with the chip.
In other files of the SPI HAL, some of these functions are implemented with existing ESP32 memory-spi function-
alities. However due to the speed limitations of ESP32, the HAL layer can t provide high-speed implementations
to some reading commands (So we didn t do it at all). The files (memspi_host_driver.h and .c) implement
the high-speed version of these commands with the common_command function provided in the HAL, and wrap
these functions as spi_flash_host_driver_t for upper layer to use.
You can also implement your own host driver, even with the GPIO. As long as all the functions in the
spi_flash_host_driver_t are implemented, the esp_flash API can access to the flash regardless of the
low-level hardware.
Chip driver The chip driver, defined in spi_flash_chip_driver.h, wraps basic functions provided by the
host driver for the API layer to use.
Some operations need some commands to be sent first, or read some status after. Some chips need different command
or value, or need special communication ways.
There is a type of chip called generic chip which stands for common chips. Other special chip drivers can be
developed on the base of the generic chip.
The chip driver relies on the host driver.

OS functions Currently the OS function layer provides entries of a lock and delay.
The lock (see SPI Bus Lock) is used to resolve the conflicts among the access of devices on the same SPI bus, and the
SPI Flash chip access. E.g.
1. On SPI1 bus, the cache (used to fetch the data (code) in the Flash and PSRAM) should be disabled when the
flash chip on the SPI0/1 is being accessed.
2. On the other buses, the flash driver needs to disable the ISR registered by SPI Master driver, to avoid conflicts.
3. Some devices of SPI Master driver may requires to use the bus monopolized during a period. (especially when
the device doesn t have CS wire, or the wire is controlled by the software like SDSPI driver).
The delay is used by some long operations which requires the master to wait or polling periodically.
The top API wraps these the chip driver and OS functions into an entire component, and also provides some argument
checking.
See also
• Partition Table documentation

• Over The Air Update (OTA) API provides high-level API for updating app firmware stored in flash.
• Non-Volatile Storage (NVS) API provides a structured API for storing small pieces of data in SPI flash.
Implementation details
In order to perform some flash operations, it is necessary to make sure that both CPUs are not running any code from
flash for the duration of the flash operation: - In a single-core setup, the SDK does it by disabling interrupts/scheduler
before performing the flash operation. - In a dual-core setup, this is slightly more complicated as the SDK needs to
make sure that the other CPU is not running any code from flash.
When SPI flash API is called on CPU A (can be PRO or APP), start the spi_flash_op_block_func function
on CPU B using the esp_ipc_call API. This API wakes up a high priority task on CPU B and tells it to execute
a given function, in this case, spi_flash_op_block_func. This function disables cache on CPU B and signals
that the cache is disabled by setting the s_flash_op_can_start flag. Then the task on CPU A disables cache
as well and proceeds to execute flash operation.
While a flash operation is running, interrupts can still run on CPUs A and B. It is assumed that all interrupt code is
placed into RAM. Once the interrupt allocation API is added, a flag should be added to request the interrupt to be
disabled for the duration of a flash operations.
Once the flash operation is complete, the function on CPU A sets another flag, s_flash_op_complete, to let
the task on CPU B know that it can re-enable cache and release the CPU. Then the function on CPU A re-enables
the cache on CPU A as well and returns control to the calling code.
Additionally, all API functions are protected with a mutex (s_flash_op_mutex).
In a single core environment (CONFIG_FREERTOS_UNICORE enabled), you need to disable both caches, so that no
inter-CPU communication can take place.
API Reference - SPI Flash
Header File
• components/spi_flash/include/esp_flash_spi_init.h
Functions
esp_err_t spi_bus_add_flash_device(esp_flash_t **out_chip, const
esp_flash_spi_device_config_t *config)
Add a SPI Flash device onto the SPI bus.
The bus should be already initialized by spi_bus_initialization.

Return
• ESP_ERR_INVALID_ARG: out_chip is NULL, or some field in the config is invalid.
• ESP_ERR_NO_MEM: failed to allocate memory for the chip structures.
• ESP_OK: success.
Parameters
• out_chip: Pointer to hold the initialized chip.
• config: Configuration of the chips to initialize.
esp_err_t spi_bus_remove_flash_device(esp_flash_t *chip)
Remove a SPI Flash device from the SPI bus.
Return
• ESP_ERR_INVALID_ARG: The chip is invalid.
• ESP_OK: success.
Parameters
• chip: The flash device to remove.
Structures
struct esp_flash_spi_device_config_t
Configurations for the SPI Flash to init.
Public Members
spi_host_device_t host_id
Bus to use.
int cs_io_num
GPIO pin to output the CS signal.
esp_flash_io_mode_t io_mode
IO mode to read from the Flash.
esp_flash_speed_t speed
Speed of the Flash clock.
int input_delay_ns
Input delay of the data pins, in ns. Set to 0 if unknown.
int cs_id
CS line ID, ignored when not host_id is not SPI1_HOST, or CON-
FIG_SPI_FLASH_SHARE_SPI1_BUS is enabled. In this case, the CS line used is automatically
assigned by the SPI bus lock.
Header File
• components/spi_flash/include/esp_flash.h
Functions
esp_err_t esp_flash_init(esp_flash_t *chip)
Initialise SPI flash chip interface.
This function must be called before any other API functions are called for this chip.
Note Only the host and read_mode fields of the chip structure must be initialised before this function is
called. Other fields may be auto-detected if left set to zero or NULL.
Note If the chip->drv pointer is NULL, chip chip_drv will be auto-detected based on its manufacturer &
product IDs. See esp_flash_registered_flash_drivers pointer for details of this process.
Return ESP_OK on success, or a flash error code if initialisation fails.
Parameters
• chip: Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.

bool esp_flash_chip_driver_initialized(const esp_flash_t *chip)

Check if appropriate chip driver is set.
Return true if set, otherwise false.
Parameters
esp_err_t esp_flash_read_id(esp_flash_t *chip, uint32_t *out_id)
Read flash ID via the common RDID SPI flash command.
ID is a 24-bit value. Lower 16 bits of id are the chip ID, upper 8 bits are the manufacturer ID.
Parameters
• chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()
• [out] out_id: Pointer to receive ID value.
Return ESP_OK on success, or a flash error code if operation failed.
esp_err_t esp_flash_get_size(esp_flash_t *chip, uint32_t *out_size)
Detect flash size based on flash ID.
Note Most flash chips use a common format for flash ID, where the lower 4 bits specify the size as a power of
2. If the manufacturer doesn t follow this convention, the size may be incorrectly detected.
Parameters
• [out] out_size: Detected size in bytes.
esp_err_t esp_flash_read_unique_chip_id(esp_flash_t *chip, uint64_t *out_id)
Read flash unique ID via the common RDUID SPI flash command.
ID is a 64-bit value.
Parameters
• chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init().
• [out] out_id: Pointer to receive unique ID value.
Return
• ESP_OK on success, or a flash error code if operation failed.
• ESP_ERR_NOT_SUPPORTED if the chip doesn t support read id.
esp_err_t esp_flash_erase_chip(esp_flash_t *chip)
Erase flash chip contents.
Return
• ESP_OK on success,
• ESP_ERR_NOT_SUPPORTED if the chip is not able to perform the operation. This is indicated
by WREN = 1 after the command is sent.
• Other flash error code if operation failed.
Parameters
esp_err_t esp_flash_erase_region(esp_flash_t *chip, uint32_t start, uint32_t len)
Erase a region of the flash chip.
Sector size is specifyed in chip->drv->sector_size field (typically 4096 bytes.) ESP_ERR_INVALID_ARG
will be returned if the start & length are not a multiple of this size.
Parameters
• start: Address to start erasing flash. Must be sector aligned.
• len: Length of region to erase. Must also be sector aligned.
Erase is performed using block (multi-sector) erases where possible (block size is specified in chip->drv-
>block_erase_size field, typically 65536 bytes). Remaining sectors are erased using individual sector erase
commands.

Return
esp_err_t esp_flash_get_chip_write_protect(esp_flash_t *chip, bool *write_protected)
Read if the entire chip is write protected.
Note A correct result for this flag depends on the SPI flash chip model and chip_drv in use (via the chip->drv
field).
Parameters
• [out] write_protected: Pointer to boolean, set to the value of the write protect flag.
esp_err_t esp_flash_set_chip_write_protect(esp_flash_t *chip, bool write_protect)
Set write protection for the SPI flash chip.
Some SPI flash chips may require a power cycle before write protect status can be cleared. Otherwise, write
protection can be removed via a follow-up call to this function.
Note Correct behaviour of this function depends on the SPI flash chip model and chip_drv in use (via the
chip->drv field).
Parameters
• write_protect: Boolean value for the write protect flag
esp_err_t esp_flash_get_protectable_regions(const esp_flash_t *chip, const
esp_flash_region_t **out_regions, uint32_t
*out_num_regions)
Read the list of individually protectable regions of this SPI flash chip.
chip->drv field).
Parameters
• [out] out_regions: Pointer to receive a pointer to the array of protectable regions of the
chip.
• [out] out_num_regions: Pointer to an integer receiving the count of protectable regions in
the array returned in regions .
esp_err_t esp_flash_get_protected_region(esp_flash_t *chip, const esp_flash_region_t
*region, bool *out_protected)
Detect if a region of the SPI flash chip is protected.
Note It is possible for this result to be false and write operations to still fail, if protection is enabled for the
entire chip.
chip->drv field).
Parameters
• region: Pointer to a struct describing a protected region. This must match one of the regions
returned from esp_flash_get_protectable_regions( ).
• [out] out_protected: Pointer to a flag which is set based on the protected status for this
region.
esp_err_t esp_flash_set_protected_region(esp_flash_t *chip, const esp_flash_region_t
*region, bool protect)
Update the protected status for a region of the SPI flash chip.

Note It is possible for the region protection flag to be cleared and write operations to still fail, if protection is
enabled for the entire chip.
chip->drv field).
Parameters
• region: Pointer to a struct describing a protected region. This must match one of the regions
returned from esp_flash_get_protectable_regions( ).
• protect: Write protection flag to set.
esp_err_t esp_flash_read(esp_flash_t *chip, void *buffer, uint32_t address, uint32_t length)
Read data from the SPI flash chip.
There are no alignment constraints on buffer, address or length.
Parameters
• buffer: Pointer to a buffer where the data will be read. To get better performance, this should be
in the DRAM and word aligned.
• address: Address on flash to read from. Must be less than chip->size field.
• length: Length (in bytes) of data to read.
Note If on-chip flash encryption is used, this function returns raw (ie encrypted) data. Use the flash cache to
transparently decrypt data.
Return
• ESP_OK: success
• ESP_ERR_NO_MEM: Buffer is in external PSRAM which cannot be concurrently accessed, and a
temporary internal buffer could not be allocated.
• or a flash error code if operation failed.
esp_err_t esp_flash_write(esp_flash_t *chip, const void *buffer, uint32_t address, uint32_t length)
Write data to the SPI flash chip.
There are no alignment constraints on buffer, address or length.
Parameters
• address: Address on flash to write to. Must be previously erased (SPI NOR flash can only write
bits 1->0).
• buffer: Pointer to a buffer with the data to write. To get better performance, this should be in the
DRAM and word aligned.
• length: Length (in bytes) of data to write.
Return
esp_err_t esp_flash_write_encrypted(esp_flash_t *chip, uint32_t address, const void *buffer,
uint32_t length)
Encrypted and write data to the SPI flash chip using on-chip hardware flash encryption.
Note Both address & length must be 16 byte aligned, as this is the encryption block size
Return
• ESP_ERR_NOT_SUPPORTED: encrypted write not supported for this chip.
• ESP_ERR_INVALID_ARG: Either the address, buffer or length is invalid.
• or other flash error code from spi_flash_write_encrypted().
Parameters
• chip: Pointer to identify flash chip. Must be NULL (the main flash chip). For other chips, en-
crypted write is not supported.

• address: Address on flash to write to. 16 byte aligned. Must be previously erased (SPI NOR flash
can only write bits 1->0).
• buffer: Pointer to a buffer with the data to write.
• length: Length (in bytes) of data to write. 16 byte aligned.
esp_err_t esp_flash_read_encrypted(esp_flash_t *chip, uint32_t address, void *out_buffer,
uint32_t length)
Read and decrypt data from the SPI flash chip using on-chip hardware flash encryption.
Return
• ESP_ERR_NOT_SUPPORTED: encrypted read not supported for this chip.
• or other flash error code from spi_flash_read_encrypted().
Parameters
• chip: Pointer to identify flash chip. Must be NULL (the main flash chip). For other chips, en-
crypted read is not supported.
• address: Address on flash to read from.
• out_buffer: Pointer to a buffer for the data to read to.
• length: Length (in bytes) of data to read.
static bool esp_flash_is_quad_mode(const esp_flash_t *chip)
Returns true if chip is configured for Quad I/O or Quad Fast Read.
Return true if flash works in quad mode, otherwise false
Parameters
Structures
struct esp_flash_region_t
Structure for describing a region of flash.
Public Members
uint32_t offset
Start address of this region.
uint32_t size
Size of the region.
struct esp_flash_os_functions_t
OS-level integration hooks for accessing flash chips inside a running OS.
It s in the public header because some instances should be allocated statically in the startup code. May be
updated according to hardware version and new flash chip feature requirements, shouldn t be treated as public
API.
For advanced developers, you may replace some of them with your implementations at your own risk.
Public Members
esp_err_t (*start)(void *arg)

Called before commencing any flash operation. Does not need to be recursive (ie is called at most once
for each call to end ).
esp_err_t (*end)(void *arg)
Called after completing any flash operation.
esp_err_t (*region_protected)(void *arg, size_t start_addr, size_t size)
Called before any erase/write operations to check whether the region is limited by the OS
esp_err_t (*delay_us)(void *arg, uint32_t us)
Delay for at least us microseconds. Called in between start and end .

void *(*get_temp_buffer)(void *arg, size_t reqest_size, size_t *out_size)

Called for get temp buffer when buffer from application cannot be directly read into/write from.
void (*release_temp_buffer)(void *arg, void *temp_buf)
Called for release temp buffer.
esp_err_t (*check_yield)(void *arg, uint32_t chip_status, uint32_t *out_request)
Yield to other tasks. Called during erase operations.
Return ESP_OK means yield needs to be called (got an event to handle), while ESP_ERR_TIMEOUT
means skip yield.
esp_err_t (*yield)(void *arg, uint32_t *out_status)
Yield to other tasks. Called during erase operations.
int64_t (*get_system_time)(void *arg)
Called for get system time.
struct esp_flash_t
Structure to describe a SPI flash chip connected to the system.
Structure must be initialized before use (passed to esp_flash_init()). It s in the public header because some
instances should be allocated statically in the startup code. May be updated according to hardware version and
new flash chip feature requirements, shouldn t be treated as public API.
For advanced developers, you may replace some of them with your implementations at your own risk.
Public Members
spi_flash_host_inst_t *host
Pointer to hardware-specific host_driver structure. Must be initialized before used.
const spi_flash_chip_t *chip_drv
Pointer to chip-model-specific adapter structure. If NULL, will be detected during initialisation.
const esp_flash_os_functions_t *os_func
Pointer to os-specific hook structure. Call esp_flash_init_os_functions() to setup this field,
after the host is properly initialized.
void *os_func_data
Pointer to argument for os-specific hooks. Left NULL and will be initialized with os_func.
esp_flash_io_mode_t read_mode
Configured SPI flash read mode. Set before esp_flash_init is called.
uint32_t size
Size of SPI flash in bytes. If 0, size will be detected during initialisation.
uint32_t chip_id
Detected chip id.
uint32_t busy : 1
This flag is used to verify chip s status.
uint32_t reserved_flags : 31
reserved.
Macros
SPI_FLASH_YIELD_REQ_YIELD
SPI_FLASH_YIELD_REQ_SUSPEND
SPI_FLASH_YIELD_STA_RESUME

Type Definitions
typedef struct spi_flash_chip_t spi_flash_chip_t
typedef struct esp_flash_t esp_flash_t
Header File
• components/hal/include/hal/spi_flash_types.h
Structures
struct spi_flash_trans_t
Definition of a common transaction. Also holds the return value.
Public Members
uint8_t reserved
Reserved, must be 0.
uint8_t mosi_len
Output data length, in bytes.
uint8_t miso_len
Input data length, in bytes.
uint8_t address_bitlen
Length of address in bits, set to 0 if command does not need an address.
uint32_t address
Address to perform operation on.
const uint8_t *mosi_data
Output data to salve.
uint8_t *miso_data
[out] Input data from slave, little endian
uint32_t flags
Flags for this transaction. Set to 0 for now.
uint16_t command
Command to send.
uint8_t dummy_bitlen
Basic dummy bits to use.
uint32_t io_mode
Flash working mode when SPI_FLASH_IGNORE_BASEIO is specified.
struct spi_flash_sus_cmd_conf
Configuration structure for the flash chip suspend feature.
Public Members
uint32_t sus_mask
SUS/SUS1/SUS2 bit in flash register.
uint32_t cmd_rdsr : 8
Read flash status register(2) command.
uint32_t sus_cmd : 8
Flash suspend command.
uint32_t res_cmd : 8
Flash resume command.

Reserved, set to 0.
struct spi_flash_encryption_t
Structure for flash encryption operations.
Public Members
void (*flash_encryption_enable)(void)
Enable the flash encryption.
void (*flash_encryption_disable)(void)
Disable the flash encryption.
void (*flash_encryption_data_prepare)(uint32_t address, const uint32_t *buffer,
uint32_t size)
Prepare flash encryption before operation.
Note address and buffer must be 8-word aligned.
Parameters
• address: The destination address in flash for the write operation.
• buffer: Data for programming
• size: Size to program.
void (*flash_encryption_done)(void)
flash data encryption operation is done.
void (*flash_encryption_destroy)(void)
Destroy encrypted result
bool (*flash_encryption_check)(uint32_t address, uint32_t length)
Check if is qualified to encrypt the buffer
Parameters
• address: the address of written flash partition.
• length: Buffer size.
struct spi_flash_host_inst_t
SPI Flash Host driver instance
Public Members
const struct spi_flash_host_driver_s *driver

Pointer to the implementation function table.
struct spi_flash_host_driver_s
Host driver configuration and context structure.
Public Members
esp_err_t (*dev_config)(spi_flash_host_inst_t *host)

Configure the device-related register before transactions. This saves some time to re-configure those
registers when we send continuously
esp_err_t (*common_command)(spi_flash_host_inst_t *host, spi_flash_trans_t *t)
Send an user-defined spi transaction to the device.
esp_err_t (*read_id)(spi_flash_host_inst_t *host, uint32_t *id)
Read flash ID.
void (*erase_chip)(spi_flash_host_inst_t *host)
Erase whole flash chip.

void (*erase_sector)(spi_flash_host_inst_t *host, uint32_t start_address)

Erase a specific sector by its start address.
void (*erase_block)(spi_flash_host_inst_t *host, uint32_t start_address)
Erase a specific block by its start address.
esp_err_t (*read_status)(spi_flash_host_inst_t *host, uint8_t *out_sr)
Read the status of the flash chip.
esp_err_t (*set_write_protect)(spi_flash_host_inst_t *host, bool wp)
Disable write protection.
void (*program_page)(spi_flash_host_inst_t *host, const void *buffer, uint32_t address, uint32_t
length)
Program a page of the flash. Check max_write_bytes for the maximum allowed writing length.
bool (*supports_direct_write)(spi_flash_host_inst_t *host, const void *p)
Check whether given buffer can be directly used to write
int (*write_data_slicer)(spi_flash_host_inst_t *host, uint32_t address, uint32_t len, uint32_t
*align_addr, uint32_t page_size)
Slicer for write data. The program_page should be called iteratively with the return value of this
function.
Return Length that can be actually written in one program_page call
Parameters
• address: Beginning flash address to write
• len: Length request to write
• align_addr: Output of the aligned address to write to
• page_size: Physical page size of the flash chip
esp_err_t (*read)(spi_flash_host_inst_t *host, void *buffer, uint32_t address, uint32_t read_len)
Read data from the flash. Check max_read_bytes for the maximum allowed reading length.
bool (*supports_direct_read)(spi_flash_host_inst_t *host, const void *p)
Check whether given buffer can be directly used to read
int (*read_data_slicer)(spi_flash_host_inst_t *host, uint32_t address, uint32_t len, uint32_t
*align_addr, uint32_t page_size)
Slicer for read data. The read should be called iteratively with the return value of this function.
Return Length that can be actually read in one read call
Parameters
• address: Beginning flash address to read
• len: Length request to read
• align_addr: Output of the aligned address to read
• page_size: Physical page size of the flash chip
uint32_t (*host_status)(spi_flash_host_inst_t *host)
Check the host status, 0:busy, 1:idle, 2:suspended.
esp_err_t (*configure_host_io_mode)(spi_flash_host_inst_t *host, uint32_t command,
uint32_t addr_bitlen, int dummy_bitlen_base,
esp_flash_io_mode_t io_mode)
Configure the host to work at different read mode. Responsible to compensate the timing and set IO
mode.
void (*poll_cmd_done)(spi_flash_host_inst_t *host)
Internal use, poll the HW until the last operation is done.
esp_err_t (*flush_cache)(spi_flash_host_inst_t *host, uint32_t addr, uint32_t size)
For some host (SPI1), they are shared with a cache. When the data is modified, the cache needs to be
flushed. Left NULL if not supported.
void (*check_suspend)(spi_flash_host_inst_t *host)
Suspend check erase/program operation, reserved for ESP32-C3 and ESP32-S3 spi flash ROM IMPL.

void (*resume)(spi_flash_host_inst_t *host)

Resume flash from suspend manually
void (*suspend)(spi_flash_host_inst_t *host)
Set flash in suspend status manually
esp_err_t (*sus_setup)(spi_flash_host_inst_t *host, const spi_flash_sus_cmd_conf *sus_conf)
Suspend feature setup for setting cmd and status register mask.
Macros
SPI_FLASH_TRANS_FLAG_CMD16
Send command of 16 bits.
SPI_FLASH_TRANS_FLAG_IGNORE_BASEIO
Not applying the basic io mode configuration for this transaction.
SPI_FLASH_TRANS_FLAG_BYTE_SWAP
Used for DTR mode, to swap the bytes of a pair of rising/falling edge.
ESP_FLASH_SPEED_MIN
Lowest speed supported by the driver, currently 5 MHz.
SPI_FLASH_CONFIG_CONF_BITS
OR the io_mode with this mask, to enable the dummy output feature or replace the first several dummy bits
into address to meet the requirements of conf bits. (Used in DIO/QIO/OIO mode)
SPI_FLASH_OPI_FLAG
A flag for flash work in opi mode, the io mode below are opi, above are SPI/QSPI mode. DO NOT use this
value in any API.
SPI_FLASH_READ_MODE_MIN
Slowest io mode supported by ESP32, currently SlowRd.
Type Definitions
typedef struct spi_flash_host_driver_s spi_flash_host_driver_t
Enumerations
enum esp_flash_speed_t
SPI flash clock speed values, always refer to them by the enum rather than the actual value (more speed may
be appended into the list).
A strategy to select the maximum allowed speed is to enumerate from the ESP_FLSH_SPEED_MAX-1 or
highest frequency supported by your flash, and decrease the speed until the probing success.
Values:
ESP_FLASH_5MHZ = 0
The flash runs under 5MHz.
ESP_FLASH_10MHZ
ESP_FLASH_20MHZ
ESP_FLASH_26MHZ
ESP_FLASH_40MHZ
ESP_FLASH_80MHZ

ESP_FLASH_120MHZ
The flash runs under 120MHz, 120MHZ can only be used by main flash after timing tuning in system.
Do not use this directely in any API.
ESP_FLASH_SPEED_MAX
The maximum frequency supported by the host is ESP_FLASH_SPEED_MAX-1.
enum esp_flash_io_mode_t
Mode used for reading from SPI flash.
Values:
SPI_FLASH_SLOWRD = 0
Data read using single I/O, some limits on speed.
SPI_FLASH_FASTRD
Data read using single I/O, no limit on speed.
SPI_FLASH_DOUT
Data read using dual I/O.
SPI_FLASH_DIO
Both address & data transferred using dual I/O.
SPI_FLASH_QOUT
Data read using quad I/O.
SPI_FLASH_QIO
Both address & data transferred using quad I/O.
SPI_FLASH_OPI_STR = SPI_FLASH_OPI_FLAG
Only support on OPI flash, flash read and write under STR mode.
SPI_FLASH_OPI_DTR
Only support on OPI flash, flash read and write under DTR mode.
SPI_FLASH_READ_MODE_MAX
The fastest io mode supported by the host is ESP_FLASH_READ_MODE_MAX-1.
API Reference - Partition Table
Header File
• components/spi_flash/include/esp_partition.h
Functions
esp_partition_iterator_t esp_partition_find(esp_partition_type_t type, esp_partition_subtype_t sub-
type, const char *label)
Find partition based on one or more parameters.
Return iterator which can be used to enumerate all the partitions found, or NULL if no partitions were found.
Iterator obtained through this function has to be released using esp_partition_iterator_release when not
used any more.
Parameters
• type: Partition type, one of esp_partition_type_t values or an 8-bit unsigned integer. To find all
partitions, no matter the type, use ESP_PARTITION_TYPE_ANY, and set subtype argument to
ESP_PARTITION_SUBTYPE_ANY.
• subtype: Partition subtype, one of esp_partition_subtype_t values or an 8-bit unsigned integer.
To find all partitions of given type, use ESP_PARTITION_SUBTYPE_ANY.
• label: (optional) Partition label. Set this value if looking for partition with a specific name. Pass
NULL otherwise.
const esp_partition_t *esp_partition_find_first(esp_partition_type_t type,
esp_partition_subtype_t subtype, const
char *label)
Find first partition based on one or more parameters.

Return pointer to esp_partition_t structure, or NULL if no partition is found. This pointer is valid for the
lifetime of the application.
Parameters
• type: Partition type, one of esp_partition_type_t values or an 8-bit unsigned integer. To find all
partitions, no matter the type, use ESP_PARTITION_TYPE_ANY, and set subtype argument to
ESP_PARTITION_SUBTYPE_ANY.
• subtype: Partition subtype, one of esp_partition_subtype_t values or an 8-bit unsigned integer To
find all partitions of given type, use ESP_PARTITION_SUBTYPE_ANY.
• label: (optional) Partition label. Set this value if looking for partition with a specific name. Pass
NULL otherwise.
const esp_partition_t *esp_partition_get(esp_partition_iterator_t iterator)
Get esp_partition_t structure for given partition.
Return pointer to esp_partition_t structure. This pointer is valid for the lifetime of the application.
Parameters
• iterator: Iterator obtained using esp_partition_find. Must be non-NULL.
esp_partition_iterator_t esp_partition_next(esp_partition_iterator_t iterator)
Move partition iterator to the next partition found.
Any copies of the iterator will be invalid after this call.
Return NULL if no partition was found, valid esp_partition_iterator_t otherwise.
Parameters
• iterator: Iterator obtained using esp_partition_find. Must be non-NULL.
void esp_partition_iterator_release(esp_partition_iterator_t iterator)
Release partition iterator.
Parameters
• iterator: Iterator obtained using esp_partition_find. The iterator is allowed to be NULL, so it
is not necessary to check its value before calling this function.
const esp_partition_t *esp_partition_verify(const esp_partition_t *partition)
Verify partition data.
Given a pointer to partition data, verify this partition exists in the partition table (all fields match.)
This function is also useful to take partition data which may be in a RAM buffer and convert it to a pointer to
the permanent partition data stored in flash.
Pointers returned from this function can be compared directly to the address of any pointer returned from
esp_partition_get(), as a test for equality.
Return
• If partition not found, returns NULL.
• If found, returns a pointer to the esp_partition_t structure in flash. This pointer is always valid for
the lifetime of the application.
Parameters
• partition: Pointer to partition data to verify. Must be non-NULL. All fields of this structure
must match the partition table entry in flash for this function to return a successful match.
esp_err_t esp_partition_read(const esp_partition_t *partition, size_t src_offset, void *dst, size_t
size)
Read data from the partition.
Partitions marked with an encryption flag will automatically be be read and decrypted via a cache mapping.
Return ESP_OK, if data was read successfully; ESP_ERR_INVALID_ARG, if src_offset exceeds partition
size; ESP_ERR_INVALID_SIZE, if read would go out of bounds of the partition; or one of error codes
from lower-level flash driver.
Parameters
• partition: Pointer to partition structure obtained using esp_partition_find_first or

• dst: Pointer to the buffer where data should be stored. Pointer must be non-NULL and buffer must
be at least size bytes long.
• src_offset: Address of the data to be read, relative to the beginning of the partition.
• size: Size of data to be read, in bytes.
esp_err_t esp_partition_write(const esp_partition_t *partition, size_t dst_offset, const void *src,
size_t size)
Write data to the partition.
Before writing data to flash, corresponding region of flash needs to be erased. This can be done using
esp_partition_erase_range function.
Partitions marked with an encryption flag will automatically be written via the spi_flash_write_encrypted()
function. If writing to an encrypted partition, all write offsets and lengths must be multiples of 16 bytes. See
the spi_flash_write_encrypted() function for more details. Unencrypted partitions do not have this restriction.
Note Prior to writing to flash memory, make sure it has been erased with esp_partition_erase_range call.
Return ESP_OK, if data was written successfully; ESP_ERR_INVALID_ARG, if dst_offset exceeds parti-
tion size; ESP_ERR_INVALID_SIZE, if write would go out of bounds of the partition; or one of error
codes from lower-level flash driver.
Parameters
• dst_offset: Address where the data should be written, relative to the beginning of the partition.
• src: Pointer to the source buffer. Pointer must be non-NULL and buffer must be at least size
bytes long.
• size: Size of data to be written, in bytes.
esp_err_t esp_partition_read_raw(const esp_partition_t *partition, size_t src_offset, void *dst,
size_t size)
Read data from the partition without any transformation/decryption.
Note This function is essentially the same as esp_partition_read() above. It just never decrypts data
but returns it as is.
Return ESP_OK, if data was read successfully; ESP_ERR_INVALID_ARG, if src_offset exceeds partition
size; ESP_ERR_INVALID_SIZE, if read would go out of bounds of the partition; or one of error codes
from lower-level flash driver.
Parameters
• dst: Pointer to the buffer where data should be stored. Pointer must be non-NULL and buffer must
be at least size bytes long.
• src_offset: Address of the data to be read, relative to the beginning of the partition.
esp_err_t esp_partition_write_raw(const esp_partition_t *partition, size_t dst_offset, const
void *src, size_t size)
Write data to the partition without any transformation/encryption.
esp_partition_erase_range function.
Note This function is essentially the same as esp_partition_write() above. It just never encrypts
data but writes it as is.
Note Prior to writing to flash memory, make sure it has been erased with esp_partition_erase_range call.
Return ESP_OK, if data was written successfully; ESP_ERR_INVALID_ARG, if dst_offset exceeds parti-
tion size; ESP_ERR_INVALID_SIZE, if write would go out of bounds of the partition; or one of the
error codes from lower-level flash driver.
Parameters
• dst_offset: Address where the data should be written, relative to the beginning of the partition.

bytes long.
esp_err_t esp_partition_erase_range(const esp_partition_t *partition, size_t offset, size_t size)
Erase part of the partition.
Return ESP_OK, if the range was erased successfully; ESP_ERR_INVALID_ARG, if iterator or dst are
NULL; ESP_ERR_INVALID_SIZE, if erase would go out of bounds of the partition; or one of error
codes from lower-level flash driver.
Parameters
• offset: Offset from the beginning of partition where erase operation should start. Must be aligned
to 4 kilobytes.
• size: Size of the range which should be erased, in bytes. Must be divisible by 4 kilobytes.
esp_err_t esp_partition_mmap(const esp_partition_t *partition, size_t offset, size_t size,
spi_flash_mmap_memory_t memory, const void **out_ptr,
spi_flash_mmap_handle_t *out_handle)
Configure MMU to map partition into data memory.
Unlike spi_flash_mmap function, which requires a 64kB aligned base address, this function doesn t impose
such a requirement. If offset results in a flash address which is not aligned to 64kB boundary, address will be
rounded to the lower 64kB boundary, so that mapped region includes requested range. Pointer returned via
out_ptr argument will be adjusted to point to the requested offset (not necessarily to the beginning of mmap-ed
region).
To release mapped memory, pass handle returned via out_handle argument to spi_flash_munmap function.
Return ESP_OK, if successful
Parameters
• offset: Offset from the beginning of partition where mapping should start.
• size: Size of the area to be mapped.
• memory: Memory space where the region should be mapped
• out_ptr: Output, pointer to the mapped memory region
• out_handle: Output, handle which should be used for spi_flash_munmap call
esp_err_t esp_partition_get_sha256(const esp_partition_t *partition, uint8_t *sha_256)
Get SHA-256 digest for required partition.
For apps with SHA-256 appended to the app image, the result is the appended SHA-256 value for the app
image content. The hash is verified before returning, if app content is invalid then the function returns
ESP_ERR_IMAGE_INVALID. For apps without SHA-256 appended to the image, the result is the SHA-
256 of all bytes in the app image. For other partition types, the result is the SHA-256 of the entire partition.
Return
• ESP_OK: In case of successful operation.
• ESP_ERR_INVALID_ARG: The size was 0 or the sha_256 was NULL.
• ESP_ERR_NO_MEM: Cannot allocate memory for sha256 operation.
• ESP_ERR_IMAGE_INVALID: App partition doesn t contain a valid app image.
• ESP_FAIL: An allocation error occurred.
Parameters
• [in] partition: Pointer to info for partition containing app or data. (fields: address, size and
type, are required to be filled).
• [out] sha_256: Returned SHA-256 digest for a given partition.
bool esp_partition_check_identity(const esp_partition_t *partition_1, const esp_partition_t
*partition_2)
Check for the identity of two partitions by SHA-256 digest.
Return

• True: In case of the two firmware is equal.

• False: Otherwise
Parameters
• [in] partition_1: Pointer to info for partition 1 containing app or data. (fields: address, size
and type, are required to be filled).
• [in] partition_2: Pointer to info for partition 2 containing app or data. (fields: address, size
and type, are required to be filled).
esp_err_t esp_partition_register_external(esp_flash_t *flash_chip, size_t offset, size_t
size, const char *label, esp_partition_type_t
type, esp_partition_subtype_t subtype, const
esp_partition_t **out_partition)
Register a partition on an external flash chip.
This API allows designating certain areas of external flash chips (identified by the esp_flash_t structure) as
partitions. This allows using them with components which access SPI flash through the esp_partition API.
Return
• ESP_ERR_NOT_SUPPORTED if CONFIG_CONFIG_SPI_FLASH_USE_LEGACY_IMPL is
enabled
• ESP_ERR_NO_MEM if memory allocation has failed
• ESP_ERR_INVALID_ARG if the new partition overlaps another partition on the same flash chip
• ESP_ERR_INVALID_SIZE if the partition doesn t fit into the flash chip size
Parameters
• flash_chip: Pointer to the structure identifying the flash chip
• offset: Address in bytes, where the partition starts
• size: Size of the partition in bytes
• label: Partition name
• type: One of the partition types (ESP_PARTITION_TYPE_*), or an integer. Note that applica-
tions can not be booted from external flash chips, so using ESP_PARTITION_TYPE_APP is not
supported.
• subtype: One of the partition subtypes (ESP_PARTITION_SUBTYPE_*), or an integer.
• [out] out_partition: Output, if non-NULL, receives the pointer to the resulting
esp_partition_t structure
esp_err_t esp_partition_deregister_external(const esp_partition_t *partition)
Deregister the partition previously registered using esp_partition_register_external.
Return
•
ESP_OK on success
•
ESP_ERR_NOT_FOUND if the partition pointer is not found
•
ESP_ERR_INVALID_ARG if the partition comes from the partition table
•
ESP_ERR_INVALID_ARG if the partition was not registered using esp_partition_register_external
function.
Parameters
• partition: pointer to the partition structure obtained from esp_partition_register_external,
Structures
struct esp_partition_t
partition information structure
This is not the format in flash, that format is esp_partition_info_t.
However, this is the format used by this API.
Public Members
esp_flash_t *flash_chip
SPI flash chip on which the partition resides

esp_partition_type_t type
partition type (app/data)
esp_partition_subtype_t subtype
partition subtype
uint32_t address
starting address of the partition in flash
uint32_t size
size of the partition, in bytes
char label[17]
partition label, zero-terminated ASCII string
bool encrypted
flag is set to true if partition is encrypted
Macros
ESP_PARTITION_SUBTYPE_OTA(i)
Convenience macro to get esp_partition_subtype_t value for the i-th OTA partition.
Type Definitions
typedef struct esp_partition_iterator_opaque_ *esp_partition_iterator_t
Opaque partition iterator type.
Enumerations
enum esp_partition_type_t
Partition type.
Note Partition types with integer value 0x00-0x3F are reserved for partition types defined by ESP-IDF. Any
other integer value 0x40-0xFE can be used by individual applications, without restriction.
Values:
ESP_PARTITION_TYPE_APP = 0x00
Application partition type.
ESP_PARTITION_TYPE_DATA = 0x01
Data partition type.
ESP_PARTITION_TYPE_ANY = 0xff
Used to search for partitions with any type.
enum esp_partition_subtype_t
Partition subtype.
Application-defined partition types (0x40-0xFE) can set any numeric subtype value.
Note These ESP-IDF-defined partition subtypes apply to partitions of type ESP_PARTITION_TYPE_APP
and ESP_PARTITION_TYPE_DATA.
Values:
ESP_PARTITION_SUBTYPE_APP_FACTORY = 0x00
Factory application partition.
ESP_PARTITION_SUBTYPE_APP_OTA_MIN = 0x10
Base for OTA partition subtypes.
ESP_PARTITION_SUBTYPE_APP_OTA_0 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 0
OTA partition 0.
OTA partition 1.

OTA partition 2.
OTA partition 3.
OTA partition 4.
OTA partition 5.
OTA partition 6.
OTA partition 7.
OTA partition 8.
OTA partition 9.
OTA partition 10.
OTA partition 11.
OTA partition 12.
OTA partition 13.
OTA partition 14.
OTA partition 15.
ESP_PARTITION_SUBTYPE_APP_OTA_MAX = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 16
Max subtype of OTA partition.
ESP_PARTITION_SUBTYPE_APP_TEST = 0x20
Test application partition.
ESP_PARTITION_SUBTYPE_DATA_OTA = 0x00
OTA selection partition.
ESP_PARTITION_SUBTYPE_DATA_PHY = 0x01
PHY init data partition.
ESP_PARTITION_SUBTYPE_DATA_NVS = 0x02
NVS partition.
ESP_PARTITION_SUBTYPE_DATA_COREDUMP = 0x03
COREDUMP partition.
ESP_PARTITION_SUBTYPE_DATA_NVS_KEYS = 0x04
Partition for NVS keys.
ESP_PARTITION_SUBTYPE_DATA_EFUSE_EM = 0x05
Partition for emulate eFuse bits.
ESP_PARTITION_SUBTYPE_DATA_UNDEFINED = 0x06
Undefined (or unspecified) data partition.

ESP_PARTITION_SUBTYPE_DATA_ESPHTTPD = 0x80
ESPHTTPD partition.
ESP_PARTITION_SUBTYPE_DATA_FAT = 0x81
FAT partition.
ESP_PARTITION_SUBTYPE_DATA_SPIFFS = 0x82
SPIFFS partition.
ESP_PARTITION_SUBTYPE_ANY = 0xff
Used to search for partitions with any subtype.
API Reference - Flash Encrypt
Header File
• components/bootloader_support/include/esp_flash_encrypt.h
Functions
static bool esp_flash_encryption_enabled(void)
Is flash encryption currently enabled in hardware?
Flash encryption is enabled if the FLASH_CRYPT_CNT efuse has an odd number of bits set.
Return true if flash encryption is enabled.
esp_err_t esp_flash_encrypt_check_and_update(void)
esp_err_t esp_flash_encrypt_region(uint32_t src_addr, size_t data_length)
Encrypt-in-place a block of flash sectors.
Note This function resets RTC_WDT between operations with sectors.
Return ESP_OK if all operations succeeded, ESP_ERR_FLASH_OP_FAIL if SPI flash fails,
ESP_ERR_FLASH_OP_TIMEOUT if flash times out.
Parameters
• src_addr: Source offset in flash. Should be multiple of 4096 bytes.
• data_length: Length of data to encrypt in bytes. Will be rounded up to next multiple of 4096
bytes.
void esp_flash_write_protect_crypt_cnt(void)
Write protect FLASH_CRYPT_CNT.
Intended to be called as a part of boot process if flash encryption is enabled but secure boot is not used. This
should protect against serial re-flashing of an unauthorised code in absence of secure boot.
Note On ESP32 V3 only, write protecting FLASH_CRYPT_CNT will also prevent disabling UART Down-
load Mode. If both are wanted, call esp_efuse_disable_rom_download_mode() before calling this func-
tion.
esp_flash_enc_mode_t esp_get_flash_encryption_mode(void)
Return the flash encryption mode.
The API is called during boot process but can also be called by application to check the current flash encryption
mode of ESP32
Return
void esp_flash_encryption_init_checks(void)
Check the flash encryption mode during startup.
Verifies the flash encryption config during startup:
Note This function is called automatically during app startup, it doesn t need to be called from the app.
• Correct any insecure flash encryption settings if hardware Secure Boot is enabled.
• Log warnings if the efuse config doesn t match the project config in any way

esp_err_t esp_flash_encryption_enable_secure_features(void)
Set all secure eFuse features related to flash encryption.
Return
• ESP_OK - Successfully
void esp_flash_encryption_set_release_mode(void)
Switches Flash Encryption from Development to Release .
If already in Release mode, the function will do nothing. If flash encryption efuse is not enabled yet then
abort. It burns:
• disable encrypt in dl mode
• set FLASH_CRYPT_CNT efuse to max
Enumerations
enum esp_flash_enc_mode_t
Values:
ESP_FLASH_ENC_MODE_DISABLED
ESP_FLASH_ENC_MODE_DEVELOPMENT
ESP_FLASH_ENC_MODE_RELEASE
2.6.7 SPIFFS Filesystem
Overview
SPIFFS is a file system intended for SPI NOR flash devices on embedded targets. It supports wear levelling, file
system consistency checks, and more.
Notes
• Currently, SPIFFS does not support directories, it produces a flat structure. If SPIFFS is mounted under
/spiffs, then creating a file with the path /spiffs/tmp/myfile.txt will create a file called /tmp/
myfile.txt in SPIFFS, instead of myfile.txt in the directory /spiffs/tmp.
• It is not a real-time stack. One write operation might take much longer than another.
• For now, it does not detect or handle bad blocks.
• SPIFFS is able to reliably utilize only around 75% of assigned partition space.
• When the filesystem is running out of space, the garbage collector is trying to find free space by scanning the
filesystem multiple times, which can take up to several seconds per write function call, depending on required
space. This is caused by the SPIFFS design and the issue has been reported multiple times (e.g. here) and in
the official SPIFFS github repository. The issue can be partially mitigated by the SPIFFS configuration.
• Deleting a file does not always remove the whole file, which leaves unusable sections throughout the filesystem.
Tools
spiffsgen.py spiffsgen.py is a write-only Python SPIFFS implementation used to create filesystem images from the
contents of a host folder. To use spiffsgen.py, open Terminal and run:
python spiffsgen.py <image_size> <base_dir> <output_file>
The required arguments are as follows:

• image_size: size of the partition onto which the created SPIFFS image will be flashed.
• base_dir: directory for which the SPIFFS image needs to be created.
• output_file: SPIFFS image output file.

There are also other arguments that control image generation. Documentation on these arguments can be found in
the tool s help:
python spiffsgen.py --help
These optional arguments correspond to a possible SPIFFS build configuration. To generate the right image, please
make sure that you use the same arguments/configuration as were used to build SPIFFS. As a guide, the help output
indicates the SPIFFS build configuration to which the argument corresponds. In cases when these arguments are not
specified, the default values shown in the help output will be used.
When the image is created, it can be flashed using esptool.py or parttool.py.
Aside from invoking the spiffsgen.py standalone by manually running it from the command line
or a script, it is also possible to invoke spiffsgen.py directly from the build system by calling
spiffs_create_partition_image:
spiffs_create_partition_image(<partition> <base_dir> [FLASH_IN_PROJECT] [DEPENDS␣

,→dep dep dep...])
This is more convenient as the build configuration is automatically passed to the tool, ensuring that the generated image
is valid for that build. An example of this is while the image_size is required for the standalone invocation, only the
partition name is required when using spiffs_create_partition_image the image size is automatically
obtained from the project s partition table.
spiffs_create_partition_image must be called from one of the component CMakeLists.txt files.
Optionally, users can opt to have the image automatically flashed together with the app binaries, partition tables, etc.
on idf.py flash by specifying FLASH_IN_PROJECT. For example:
spiffs_create_partition_image(my_spiffs_partition my_folder FLASH_IN_PROJECT)
If FLASH_IN_PROJECT/SPIFFS_IMAGE_FLASH_IN_PROJECT is not specified, the image will still be gener-

ated, but you will have to flash it manually using esptool.py, parttool.py, or a custom build system target.
There are cases where the contents of the base directory itself is generated at build time. Users can use DE-
PENDS/SPIFFS_IMAGE_DEPENDS to specify targets that should be executed before generating the image:
add_custom_target(dep COMMAND ...)
spiffs_create_partition_image(my_spiffs_partition my_folder DEPENDS dep)
For an example, see storage/spiffsgen.
mkspiffs Another tool for creating SPIFFS partition images is mkspiffs. Similar to spiffsgen.py, it can be
used to create an image from a given folder and then flash that image using esptool.py
For that, you need to obtain the following parameters:
• Block Size: 4096 (standard for SPI Flash)
• Page Size: 256 (standard for SPI Flash)
• Image Size: Size of the partition in bytes (can be obtained from a partition table)
• Partition Offset: Starting address of the partition (can be obtained from a partition table)
To pack a folder into a 1-Megabyte image, run:
mkspiffs -c [src_folder] -b 4096 -p 256 -s 0x100000 spiffs.bin
To flash the image onto ESP32 at offset 0x110000, run:
python esptool.py --chip esp32 --port [port] --baud [baud] write_flash -z 0x110000␣
,→spiffs.bin

Notes on which SPIFFS tool to use The two tools presented above offer very similar functionality. However,
there are reasons to prefer one over the other, depending on the use case.
Use spiffsgen.py in the following cases:
1. If you want to simply generate a SPIFFS image during the build. spiffsgen.py makes it very convenient
by providing functions/commands from the build system itself.
2. If the host has no C/C++ compiler available, because spiffsgen.py does not require compilation.
Use mkspiffs in the following cases:
1. If you need to unpack SPIFFS images in addition to image generation. For now, it is not possible with spiff-
sgen.py.
2. If you have an environment where a Python interpreter is not available, but a host compiler is available. Oth-
erwise, a pre-compiled mkspiffs binary can do the job. However, there is no build system integration for
mkspiffs and the user has to do the corresponding work: compiling mkspiffs during build (if a pre-
compiled binary is not used), creating build rules/targets for the output files, passing proper parameters to the
tool, etc.
See also
Application Example
An example of using SPIFFS is provided in the storage/spiffs directory. This example initializes and mounts a
SPIFFS partition, then writes and reads data from it using POSIX and C library APIs. See the README.md file in
the example directory for more information.
High-level API Reference
Header File
• components/spiffs/include/esp_spiffs.h
Functions
esp_err_t esp_vfs_spiffs_register(const esp_vfs_spiffs_conf_t *conf)
Register and mount SPIFFS to VFS with given path prefix.
Return
• ESP_ERR_NO_MEM if objects could not be allocated
• ESP_ERR_INVALID_STATE if already mounted or partition is encrypted
• ESP_ERR_NOT_FOUND if partition for SPIFFS was not found
• ESP_FAIL if mount or format fails
Parameters
• conf: Pointer to esp_vfs_spiffs_conf_t configuration structure
esp_err_t esp_vfs_spiffs_unregister(const char *partition_label)
Unregister and unmount SPIFFS from VFS
Return
• ESP_OK if successful
• ESP_ERR_INVALID_STATE already unregistered
Parameters
• partition_label: Same label as passed to esp_vfs_spiffs_register.
bool esp_spiffs_mounted(const char *partition_label)
Check if SPIFFS is mounted
Return

• true if mounted
• false if not mounted
Parameters
• partition_label: Optional, label of the partition to check. If not specified, first partition with
subtype=spiffs is used.
esp_err_t esp_spiffs_format(const char *partition_label)
Format the SPIFFS partition
Return
• ESP_OK if successful
• ESP_FAIL on error
Parameters
• partition_label: Same label as passed to esp_vfs_spiffs_register.
esp_err_t esp_spiffs_info(const char *partition_label, size_t *total_bytes, size_t *used_bytes)
Get information for SPIFFS
Return
• ESP_ERR_INVALID_STATE if not mounted
Parameters
• partition_label: Same label as passed to esp_vfs_spiffs_register
• [out] total_bytes: Size of the file system
• [out] used_bytes: Current used bytes in the file system
Structures
struct esp_vfs_spiffs_conf_t
Configuration structure for esp_vfs_spiffs_register.
Public Members
const char *base_path

File path prefix associated with the filesystem.
const char *partition_label
Optional, label of SPIFFS partition to use. If set to NULL, first partition with subtype=spiffs will be
used.
size_t max_files
Maximum files that could be open at the same time.
If true, it will format the file system if it fails to mount.
2.6.8 Virtual filesystem component
Overview
Virtual filesystem (VFS) component provides a unified interface for drivers which can perform operations on file-like
objects. These can be real filesystems (FAT, SPIFFS, etc.) or device drivers which provide a file-like interface.
This component allows C library functions, such as fopen and fprintf, to work with FS drivers. At a high level, each FS
driver is associated with some path prefix. When one of C library functions needs to open a file, the VFS component
searches for the FS driver associated with the file path and forwards the call to that driver. VFS also forwards read,
write, and other calls for the given file to the same FS driver.
For example, one can register a FAT filesystem driver with the /fat prefix and call fopen("/fat/file.txt",
"w"). The VFS component will then call the function open of the FAT driver and pass the argument /file.txt

to it together with appropriate mode flags. All subsequent calls to C library functions for the returned FILE* stream
will also be forwarded to the FAT driver.
FS registration
To register an FS driver, an application needs to define an instance of the esp_vfs_t structure and populate it with
function pointers to FS APIs:
esp_vfs_t myfs = {
.flags = ESP_VFS_FLAG_DEFAULT,
.write = &myfs_write,
.open = &myfs_open,
.fstat = &myfs_fstat,
.close = &myfs_close,
.read = &myfs_read,
};
ESP_ERROR_CHECK(esp_vfs_register("/data", &myfs, NULL));
Depending on the way how the FS driver declares its API functions, either read, write, etc., or read_p,
write_p, etc., should be used.
Case 1: API functions are declared without an extra context pointer (the FS driver is a singleton):
ssize_t myfs_write(int fd, const void * data, size_t size);
// In definition of esp_vfs_t:
.flags = ESP_VFS_FLAG_DEFAULT,
.write = &myfs_write,
// ... other members initialized
// When registering FS, context pointer (third argument) is NULL:

ESP_ERROR_CHECK(esp_vfs_register("/data", &myfs, NULL));
Case 2: API functions are declared with an extra context pointer (the FS driver supports multiple instances):
ssize_t myfs_write(myfs_t* fs, int fd, const void * data, size_t size);
.flags = ESP_VFS_FLAG_CONTEXT_PTR,
.write_p = &myfs_write,
// When registering FS, pass the FS context pointer into the third argument
// (hypothetical myfs_mount function is used for illustrative purposes)
myfs_t* myfs_inst1 = myfs_mount(partition1->offset, partition1->size);
ESP_ERROR_CHECK(esp_vfs_register("/data1", &myfs, myfs_inst1));
// Can register another instance:

myfs_t* myfs_inst2 = myfs_mount(partition2->offset, partition2->size);
ESP_ERROR_CHECK(esp_vfs_register("/data2", &myfs, myfs_inst2));
Synchronous input/output multiplexing Synchronous input/output multiplexing by select() is supported in

the VFS component. The implementation works in the following way.
1. select() is called with file descriptors which could belong to various VFS drivers.
2. The file descriptors are divided into groups each belonging to one VFS driver.
3. The file descriptors belonging to non-socket VFS drivers are handed over to the given VFS drivers by
start_select() described later on this page. This function represents the driver-specific implementa-
tion of select() for the given driver. This should be a non-blocking call which means the function should
immediately return after setting up the environment for checking events related to the given file descriptors.

4. The file descriptors belonging to the socket VFS driver are handed over to the socket driver by
socket_select() described later on this page. This is a blocking call which means that it will return
only if there is an event related to socket file descriptors or a non-socket driver signals socket_select()
to exit.
5. Results are collected from each VFS driver and all drivers are stopped by deinitiazation of the environment for
checking events.
6. The select() call ends and returns the appropriate results.
Non-socket VFS drivers If you want to use select() with a file descriptor belonging to a non-socket VFS
driver then you need to register the driver with functions start_select() and end_select() similarly to
the following example:
.start_select = &uart_start_select,
.end_select = &uart_end_select,
start_select() is called for setting up the environment for detection of read/write/error conditions on file
descriptors belonging to the given VFS driver.
end_select() is called to stop/deinitialize/free the environment which was setup by start_select().
Note: end_select() might be called without a previous start_select() call in some rare circumstances.
end_select() should fail gracefully if this is the case.
Please refer to the reference implementation for the UART peripheral in vfs/vfs_uart.c and most particularly to the
functions esp_vfs_dev_uart_register(), uart_start_select(), and uart_end_select()
Please check the following examples that demonstrate the use of select() with VFS file descriptors:
• peripherals/uart/uart_select
• system/select
Socket VFS drivers A socket VFS driver is using its own internal implementation of select() and non-socket
VFS drivers notify it upon read/write/error conditions.
A socket VFS driver needs to be registered with the following functions defined:
.socket_select = &lwip_select,
.get_socket_select_semaphore = &lwip_get_socket_select_semaphore,
.stop_socket_select = &lwip_stop_socket_select,
.stop_socket_select_isr = &lwip_stop_socket_select_isr,
socket_select() is the internal implementation of select() for the socket driver. It works only with file
descriptors belonging to the socket VFS.
get_socket_select_semaphore() returns the signalization object (semaphore) which will be used in non-
socket drivers to stop the waiting in socket_select().
stop_socket_select() call is used to stop the waiting in socket_select() by passing the object returned
by get_socket_select_semaphore().
stop_socket_select_isr() has the same functionality as stop_socket_select() but it can be used
from ISR.
Please see lwip/port/esp32/vfs_lwip.c for a reference socket driver implementation using LWIP.

Note: If you use select() for socket file descriptors only then you can enable the CON-
FIG_LWIP_USE_ONLY_LWIP_SELECT option to reduce the code size and improve performance.
Note: Don t change the socket driver during an active select() call or you might experience some undefined
behavior.
Paths
Each registered FS has a path prefix associated with it. This prefix can be considered as a mount point of this
partition.
In case when mount points are nested, the mount point with the longest matching path prefix is used when opening
the file. For instance, suppose that the following filesystems are registered in VFS:
• FS 1 on /data
• FS 2 on /data/static
Then:
• FS 1 will be used when opening a file called /data/log.txt
• FS 2 will be used when opening a file called /data/static/index.html
• Even if /index.html" does not exist in FS 2, FS 1 will not be searched for /static/index.html.
As a general rule, mount point names must start with the path separator (/) and must contain at least one character
after path separator. However, an empty mount point name is also supported and might be used in cases when an
application needs to provide a fallback filesystem or to override VFS functionality altogether. Such filesystem will
be used if no prefix matches the path given.
VFS does not handle dots (.) in path names in any special way. VFS does not treat .. as a reference to the parent
directory. In the above example, using a path /data/static/../log.txt will not result in a call to FS 1 to
open /log.txt. Specific FS drivers (such as FATFS) might handle dots in file names differently.
When opening files, the FS driver receives only relative paths to files. For example:
1. The myfs driver is registered with /data as a path prefix.
2. The application calls fopen("/data/config.json", ...).
3. The VFS component calls myfs_open("/config.json", ...).
4. The myfs driver opens the /config.json file.
VFS does not impose any limit on total file path length, but it does limit the FS path prefix to ESP_VFS_PATH_MAX
characters. Individual FS drivers may have their own filename length limitations.
File descriptors
File descriptors are small positive integers from 0 to FD_SETSIZE - 1, where FD_SETSIZE is defined in newlib
s sys/types.h. The largest file descriptors (configured by CONFIG_LWIP_MAX_SOCKETS) are reserved for
sockets. The VFS component contains a lookup-table called s_fd_table for mapping global file descriptors to
VFS driver indexes registered in the s_vfs array.
Standard IO streams (stdin, stdout, stderr)
If the menuconfig option UART for console output is not set to None, then stdin, stdout, and stderr
are configured to read from, and write to, a UART. It is possible to use UART0 or UART1 for standard IO. By default,
UART0 is used with 115200 baud rate; TX pin is GPIO1; RX pin is GPIO3. These parameters can be changed in
menuconfig.

Writing to stdout or stderr will send characters to the UART transmit FIFO. Reading from stdin will retrieve
characters from the UART receive FIFO.
By default, VFS uses simple functions for reading from and writing to UART. Writes busy-wait until all data is put
into UART FIFO, and reads are non-blocking, returning only the data present in the FIFO. Due to this non-blocking
read behavior, higher level C library calls, such as fscanf("%d\n", &var);, might not have desired results.
Applications which use the UART driver can instruct VFS to use the driver s interrupt driven, blocking read and write
functions instead. This can be done using a call to the esp_vfs_dev_uart_use_driver function. It is also
possible to revert to the basic non-blocking functions using a call to esp_vfs_dev_uart_use_nonblocking.
VFS also provides an optional newline conversion feature for input and output. Internally, most applications send
and receive lines terminated by the LF ( n ) character. Different terminal programs may require differ-
ent line termination, such as CR or CRLF. Applications can configure this separately for input and output ei-
ther via menuconfig, or by calls to the functions esp_vfs_dev_uart_port_set_rx_line_endings and
esp_vfs_dev_uart_port_set_tx_line_endings.
Standard streams and FreeRTOS tasks FILE objects for stdin, stdout, and stderr are shared between
all FreeRTOS tasks, but the pointers to these objects are stored in per-task struct _reent.
The following code is transferred to fprintf(__getreent()->_stderr, "42\n"); by the preprocessor:
fprintf(stderr, "42\n");
The __getreent() function returns a per-task pointer to struct _reent in newlib libc. This structure is
allocated on the TCB of each task. When a task is initialized, _stdin, _stdout, and _stderr members of
struct _reent are set to the values of _stdin, _stdout, and _stderr of _GLOBAL_REENT (i.e., the
structure which is used before FreeRTOS is started).
Such a design has the following consequences:
• It is possible to set stdin, stdout, and stderr for any given task without affecting other tasks, e.g., by
doing stdin = fopen("/dev/uart/1", "r").
• Closing default stdin, stdout, or stderr using fclose will close the FILE stream object, which will
affect all other tasks.
• To change the default stdin, stdout, stderr streams for new tasks, modify _GLOBAL_REENT-
>_stdin (_stdout, _stderr) before creating the task.
Event fds
eventfd() call is a powerful tool to notify a select() based loop of custom events. The eventfd() imple-
mentation in ESP-IDF is generally the same as described in man(2) eventfd except for:
• esp_vfs_eventfd_register() has to be called before calling eventfd()
• Options EFD_CLOEXEC, EFD_NONBLOCK and EFD_SEMAPHORE are not supported in flags.
• Option EFD_SUPPORT_ISR has been added in flags. This flag is required to read and the write the eventfd
in an interrupt handler.
Note that creating an eventfd with EFD_SUPPORT_ISR will cause interrupts to be temporarily disabled when
reading, writing the file and during the beginning and the ending of the select() when this file is set.
API Reference
Header File
• components/vfs/include/esp_vfs.h

Functions
ssize_t esp_vfs_write(struct _reent *r, int fd, const void *data, size_t size)
These functions are to be used in newlib syscall table. They will be called by newlib when it needs to use any
of the syscalls.
off_t esp_vfs_lseek(struct _reent *r, int fd, off_t size, int mode)
ssize_t esp_vfs_read(struct _reent *r, int fd, void *dst, size_t size)
int esp_vfs_open(struct _reent *r, const char *path, int flags, int mode)
int esp_vfs_close(struct _reent *r, int fd)
int esp_vfs_fstat(struct _reent *r, int fd, struct stat *st)
int esp_vfs_stat(struct _reent *r, const char *path, struct stat *st)
int esp_vfs_link(struct _reent *r, const char *n1, const char *n2)
int esp_vfs_unlink(struct _reent *r, const char *path)
int esp_vfs_rename(struct _reent *r, const char *src, const char *dst)
int esp_vfs_utime(const char *path, const struct utimbuf *times)
esp_err_t esp_vfs_register(const char *base_path, const esp_vfs_t *vfs, void *ctx)
Register a virtual filesystem for given path prefix.
Return ESP_OK if successful, ESP_ERR_NO_MEM if too many VFSes are registered.
Parameters
• base_path: file path prefix associated with the filesystem. Must be a zero-terminated C string,
may be empty. If not empty, must be up to ESP_VFS_PATH_MAX characters long, and at least 2
characters long. Name must start with a / and must not end with / . For example, /data or
/dev/spi are valid. These VFSes would then be called to handle file paths such as /data/myfile.txt
or /dev/spi/0 . In the special case of an empty base_path, a fallback VFS is registered. Such
VFS will handle paths which are not matched by any other registered VFS.
• vfs: Pointer to esp_vfs_t, a structure which maps syscalls to the filesystem driver functions. VFS
component doesn t assume ownership of this pointer.
• ctx: If vfs->flags has ESP_VFS_FLAG_CONTEXT_PTR set, a pointer which should be passed
to VFS functions. Otherwise, NULL.
esp_err_t esp_vfs_register_fd_range(const esp_vfs_t *vfs, void *ctx, int min_fd, int max_fd)
Special case function for registering a VFS that uses a method other than open() to open new file descriptors
from the interval <min_fd; max_fd).
This is a special-purpose function intended for registering LWIP sockets to VFS.
Return ESP_OK if successful, ESP_ERR_NO_MEM if too many VFSes are registered,
ESP_ERR_INVALID_ARG if the file descriptor boundaries are incorrect.
Parameters
• vfs: Pointer to esp_vfs_t. Meaning is the same as for esp_vfs_register().
• ctx: Pointer to context structure. Meaning is the same as for esp_vfs_register().
• min_fd: The smallest file descriptor this VFS will use.
• max_fd: Upper boundary for file descriptors this VFS will use (the biggest file descriptor plus one).
esp_err_t esp_vfs_register_with_id(const esp_vfs_t *vfs, void *ctx, esp_vfs_id_t *vfs_id)
Special case function for registering a VFS that uses a method other than open() to open new file descriptors. In
comparison with esp_vfs_register_fd_range, this function doesn t pre-registers an interval of file descriptors.
File descriptors can be registered later, by using esp_vfs_register_fd.
Return ESP_OK if successful, ESP_ERR_NO_MEM if too many VFSes are registered,
ESP_ERR_INVALID_ARG if the file descriptor boundaries are incorrect.
Parameters
• vfs: Pointer to esp_vfs_t. Meaning is the same as for esp_vfs_register().
• ctx: Pointer to context structure. Meaning is the same as for esp_vfs_register().
• vfs_id: Here will be written the VFS ID which can be passed to esp_vfs_register_fd for registering
file descriptors.

esp_err_t esp_vfs_unregister(const char *base_path)

Unregister a virtual filesystem for given path prefix
Return ESP_OK if successful, ESP_ERR_INVALID_STATE if VFS for given prefix hasn t been registered
Parameters
• base_path: file prefix previously used in esp_vfs_register call
esp_err_t esp_vfs_unregister_with_id(esp_vfs_id_t vfs_id)
Unregister a virtual filesystem with the given index
Return ESP_OK if successful, ESP_ERR_INVALID_STATE if VFS for the given index hasn t been reg-
istered
Parameters
• vfs_id: The VFS ID returned by esp_vfs_register_with_id
esp_err_t esp_vfs_register_fd(esp_vfs_id_t vfs_id, int *fd)
Special function for registering another file descriptor for a VFS registered by esp_vfs_register_with_id.
Return ESP_OK if the registration is successful, ESP_ERR_NO_MEM if too many file descriptors are reg-
istered, ESP_ERR_INVALID_ARG if the arguments are incorrect.
Parameters
• vfs_id: VFS identificator returned by esp_vfs_register_with_id.
• fd: The registered file descriptor will be written to this address.
esp_err_t esp_vfs_register_fd_with_local_fd(esp_vfs_id_t vfs_id, int local_fd, bool perma-
nent, int *fd)
Special function for registering another file descriptor with given local_fd for a VFS registered by
esp_vfs_register_with_id.
Return ESP_OK if the registration is successful, ESP_ERR_NO_MEM if too many file descriptors are reg-
istered, ESP_ERR_INVALID_ARG if the arguments are incorrect.
Parameters
• local_fd: The fd in the local vfs. Passing -1 will set the local fd as the (*fd) value.
• permanent: Whether the fd should be treated as permannet (not removed after close())
• fd: The registered file descriptor will be written to this address.
esp_err_t esp_vfs_unregister_fd(esp_vfs_id_t vfs_id, int fd)
Special function for unregistering a file descriptor belonging to a VFS registered by esp_vfs_register_with_id.
Return ESP_OK if the registration is successful, ESP_ERR_INVALID_ARG if the arguments are incorrect.
Parameters
• fd: File descriptor which should be unregistered.
int esp_vfs_select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *errorfds, struct timeval
*timeout)
Synchronous I/O multiplexing which implements the functionality of POSIX select() for VFS.
Return The number of descriptors set in the descriptor sets, or -1 when an error (specified by errno) have
occurred.
Parameters
• nfds: Specifies the range of descriptors which should be checked. The first nfds descriptors will
be checked in each set.
• readfds: If not NULL, then points to a descriptor set that on input specifies which descriptors
should be checked for being ready to read, and on output indicates which descriptors are ready to
read.
• writefds: If not NULL, then points to a descriptor set that on input specifies which descriptors
should be checked for being ready to write, and on output indicates which descriptors are ready to
write.
• errorfds: If not NULL, then points to a descriptor set that on input specifies which descrip-
tors should be checked for error conditions, and on output indicates which descriptors have error
conditions.

• timeout: If not NULL, then points to timeval structure which specifies the time period after which
the functions should time-out and return. If it is NULL, then the function will not time-out. Note
that the timeout period is rounded up to the system tick and incremented by one.
void esp_vfs_select_triggered(esp_vfs_select_sem_t sem)
Notification from a VFS driver about a read/write/error condition.
This function is called when the VFS driver detects a read/write/error condition as it was requested by the
previous call to start_select.
Parameters
• sem: semaphore structure which was passed to the driver by the start_select call
void esp_vfs_select_triggered_isr(esp_vfs_select_sem_t sem, BaseType_t *woken)
Notification from a VFS driver about a read/write/error condition (ISR version)
This function is called when the VFS driver detects a read/write/error condition as it was requested by the
previous call to start_select.
Parameters
• sem: semaphore structure which was passed to the driver by the start_select call
• woken: is set to pdTRUE if the function wakes up a task with higher priority
ssize_t esp_vfs_pread(int fd, void *dst, size_t size, off_t offset)
Implements the VFS layer of POSIX pread()
Return A positive return value indicates the number of bytes read. -1 is return on failure and errno is set
accordingly.
Parameters
• fd: File descriptor used for read
• dst: Pointer to the buffer where the output will be written
• size: Number of bytes to be read
• offset: Starting offset of the read
ssize_t esp_vfs_pwrite(int fd, const void *src, size_t size, off_t offset)
Implements the VFS layer of POSIX pwrite()
Return A positive return value indicates the number of bytes written. -1 is return on failure and errno is set
accordingly.
Parameters
• fd: File descriptor used for write
• src: Pointer to the buffer from where the output will be read
• size: Number of bytes to write
• offset: Starting offset of the write
Structures
struct esp_vfs_select_sem_t
VFS semaphore type for select()
Public Members
bool is_sem_local
type of sem is SemaphoreHandle_t when true, defined by socket driver otherwise
void *sem
semaphore instance
struct esp_vfs_t
VFS definition structure.
This structure should be filled with pointers to corresponding FS driver functions.
VFS component will translate all FDs so that the filesystem implementation sees them starting at zero. The
caller sees a global FD which is prefixed with an pre-filesystem-implementation.

Some FS implementations expect some state (e.g. pointer to some structure) to be passed in as a first argument.
For these implementations, populate the members of this structure which have _p suffix, set flags member
to ESP_VFS_FLAG_CONTEXT_PTR and provide the context pointer to esp_vfs_register function. If the
implementation doesn t use this extra argument, populate the members without _p suffix and set flags member
to ESP_VFS_FLAG_DEFAULT.
If the FS driver doesn t provide some of the functions, set corresponding members to NULL.
Public Members
int flags
ESP_VFS_FLAG_CONTEXT_PTR or ESP_VFS_FLAG_DEFAULT
ssize_t (*write_p)(void *p, int fd, const void *data, size_t size)
Write with context pointer
ssize_t (*write)(int fd, const void *data, size_t size)
Write without context pointer
off_t (*lseek_p)(void *p, int fd, off_t size, int mode)
Seek with context pointer
off_t (*lseek)(int fd, off_t size, int mode)
Seek without context pointer
ssize_t (*read_p)(void *ctx, int fd, void *dst, size_t size)
Read with context pointer
ssize_t (*read)(int fd, void *dst, size_t size)
Read without context pointer
ssize_t (*pread_p)(void *ctx, int fd, void *dst, size_t size, off_t offset)
pread with context pointer
ssize_t (*pread)(int fd, void *dst, size_t size, off_t offset)
pread without context pointer
ssize_t (*pwrite_p)(void *ctx, int fd, const void *src, size_t size, off_t offset)
pwrite with context pointer
ssize_t (*pwrite)(int fd, const void *src, size_t size, off_t offset)
pwrite without context pointer
int (*open_p)(void *ctx, const char *path, int flags, int mode)
open with context pointer
int (*open)(const char *path, int flags, int mode)
open without context pointer
int (*close_p)(void *ctx, int fd)
close with context pointer
int (*close)(int fd)
close without context pointer
int (*fstat_p)(void *ctx, int fd, struct stat *st)
fstat with context pointer
int (*fstat)(int fd, struct stat *st)
fstat without context pointer
int (*stat_p)(void *ctx, const char *path, struct stat *st)
stat with context pointer
int (*stat)(const char *path, struct stat *st)
stat without context pointer

int (*link_p)(void *ctx, const char *n1, const char *n2)

link with context pointer
int (*link)(const char *n1, const char *n2)
link without context pointer
int (*unlink_p)(void *ctx, const char *path)
unlink with context pointer
int (*unlink)(const char *path)
unlink without context pointer
int (*rename_p)(void *ctx, const char *src, const char *dst)
rename with context pointer
int (*rename)(const char *src, const char *dst)
rename without context pointer
DIR *(*opendir_p)(void *ctx, const char *name)
opendir with context pointer
DIR *(*opendir)(const char *name)
opendir without context pointer
struct dirent *(*readdir_p)(void *ctx, DIR *pdir)
readdir with context pointer
struct dirent *(*readdir)(DIR *pdir)
readdir without context pointer
int (*readdir_r_p)(void *ctx, DIR *pdir, struct dirent *entry, struct dirent **out_dirent)
readdir_r with context pointer
int (*readdir_r)(DIR *pdir, struct dirent *entry, struct dirent **out_dirent)
readdir_r without context pointer
long (*telldir_p)(void *ctx, DIR *pdir)
telldir with context pointer
long (*telldir)(DIR *pdir)
telldir without context pointer
void (*seekdir_p)(void *ctx, DIR *pdir, long offset)
seekdir with context pointer
void (*seekdir)(DIR *pdir, long offset)
seekdir without context pointer
int (*closedir_p)(void *ctx, DIR *pdir)
closedir with context pointer
int (*closedir)(DIR *pdir)
closedir without context pointer
int (*mkdir_p)(void *ctx, const char *name, mode_t mode)
mkdir with context pointer
int (*mkdir)(const char *name, mode_t mode)
mkdir without context pointer
int (*rmdir_p)(void *ctx, const char *name)
rmdir with context pointer
int (*rmdir)(const char *name)
rmdir without context pointer
int (*fcntl_p)(void *ctx, int fd, int cmd, int arg)
fcntl with context pointer

int (*fcntl)(int fd, int cmd, int arg)

fcntl without context pointer
int (*ioctl_p)(void *ctx, int fd, int cmd, va_list args)
ioctl with context pointer
int (*ioctl)(int fd, int cmd, va_list args)
ioctl without context pointer
int (*fsync_p)(void *ctx, int fd)
fsync with context pointer
int (*fsync)(int fd)
fsync without context pointer
int (*access_p)(void *ctx, const char *path, int amode)
access with context pointer
int (*access)(const char *path, int amode)
access without context pointer
int (*truncate_p)(void *ctx, const char *path, off_t length)
truncate with context pointer
int (*truncate)(const char *path, off_t length)
truncate without context pointer
int (*utime_p)(void *ctx, const char *path, const struct utimbuf *times)
utime with context pointer
int (*utime)(const char *path, const struct utimbuf *times)
utime without context pointer
int (*tcsetattr_p)(void *ctx, int fd, int optional_actions, const struct termios *p)
tcsetattr with context pointer
int (*tcsetattr)(int fd, int optional_actions, const struct termios *p)
tcsetattr without context pointer
int (*tcgetattr_p)(void *ctx, int fd, struct termios *p)
tcgetattr with context pointer
int (*tcgetattr)(int fd, struct termios *p)
tcgetattr without context pointer
int (*tcdrain_p)(void *ctx, int fd)
tcdrain with context pointer
int (*tcdrain)(int fd)
tcdrain without context pointer
int (*tcflush_p)(void *ctx, int fd, int select)
tcflush with context pointer
int (*tcflush)(int fd, int select)
tcflush without context pointer
int (*tcflow_p)(void *ctx, int fd, int action)
tcflow with context pointer
int (*tcflow)(int fd, int action)
tcflow without context pointer
pid_t (*tcgetsid_p)(void *ctx, int fd)
tcgetsid with context pointer
pid_t (*tcgetsid)(int fd)
tcgetsid without context pointer

int (*tcsendbreak_p)(void *ctx, int fd, int duration)

tcsendbreak with context pointer
int (*tcsendbreak)(int fd, int duration)
tcsendbreak without context pointer
esp_err_t (*start_select)(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds,
esp_vfs_select_sem_t sem, void **end_select_args)
start_select is called for setting up synchronous I/O multiplexing of the desired file descriptors in the
given VFS
int (*socket_select)(int nfds, fd_set *readfds, fd_set *writefds, fd_set *errorfds, struct timeval
*timeout)
socket select function for socket FDs with the functionality of POSIX select(); this should be set only for
the socket VFS
void (*stop_socket_select)(void *sem)
called by VFS to interrupt the socket_select call when select is activated from a non-socket VFS driver;
set only for the socket driver
void (*stop_socket_select_isr)(void *sem, BaseType_t *woken)
stop_socket_select which can be called from ISR; set only for the socket driver
void *(*get_socket_select_semaphore)(void)
end_select is called to stop the I/O multiplexing and deinitialize the environment created by start_select
for the given VFS
esp_err_t (*end_select)(void *end_select_args)
get_socket_select_semaphore returns semaphore allocated in the socket driver; set only for the socket
driver
Macros
MAX_FDS
Maximum number of (global) file descriptors.
ESP_VFS_PATH_MAX
Maximum length of path prefix (not including zero terminator)
ESP_VFS_FLAG_DEFAULT
Default value of flags member in esp_vfs_t structure.
ESP_VFS_FLAG_CONTEXT_PTR
Flag which indicates that FS needs extra context pointer in syscalls.
Type Definitions
typedef int esp_vfs_id_t
Header File
• components/vfs/include/esp_vfs_dev.h
Functions
void esp_vfs_dev_uart_register(void)
add /dev/uart virtual filesystem driver
This function is called from startup code to enable serial output
void esp_vfs_dev_uart_set_rx_line_endings(esp_line_endings_t mode)
Set the line endings expected to be received on UART.
This specifies the conversion between line endings received on UART and newlines ( , LF) passed into
stdin:
• ESP_LINE_ENDINGS_CRLF: convert CRLF to LF

• ESP_LINE_ENDINGS_CR: convert CR to LF
• ESP_LINE_ENDINGS_LF: no modification
Note this function is not thread safe w.r.t. reading from UART
Parameters
• mode: line endings expected on UART
void esp_vfs_dev_uart_set_tx_line_endings(esp_line_endings_t mode)
Set the line endings to sent to UART.
This specifies the conversion between newlines ( , LF) on stdout and line endings sent over UART:
• ESP_LINE_ENDINGS_CRLF: convert LF to CRLF
• ESP_LINE_ENDINGS_CR: convert LF to CR
Note this function is not thread safe w.r.t. writing to UART
Parameters
• mode: line endings to send to UART
int esp_vfs_dev_uart_port_set_rx_line_endings(int uart_num, esp_line_endings_t mode)
Set the line endings expected to be received on specified UART.
This specifies the conversion between line endings received on UART and newlines ( , LF) passed into
stdin:
• ESP_LINE_ENDINGS_CRLF: convert CRLF to LF
• ESP_LINE_ENDINGS_CR: convert CR to LF
Note this function is not thread safe w.r.t. reading from UART
Return 0 if successed, or -1 when an error (specified by errno) have occurred.
Parameters
• uart_num: the UART number
int esp_vfs_dev_uart_port_set_tx_line_endings(int uart_num, esp_line_endings_t mode)
Set the line endings to sent to specified UART.
This specifies the conversion between newlines ( , LF) on stdout and line endings sent over UART:
• ESP_LINE_ENDINGS_CRLF: convert LF to CRLF
• ESP_LINE_ENDINGS_CR: convert LF to CR
Note this function is not thread safe w.r.t. writing to UART
Return 0 if successed, or -1 when an error (specified by errno) have occurred.
Parameters
• uart_num: the UART number
void esp_vfs_dev_uart_use_nonblocking(int uart_num)
set VFS to use simple functions for reading and writing UART Read is non-blocking, write is busy waiting
until TX FIFO has enough space. These functions are used by default.
Parameters
• uart_num: UART peripheral number
void esp_vfs_dev_uart_use_driver(int uart_num)
set VFS to use UART driver for reading and writing
Note application must configure UART driver before calling these functions With these functions, read and
write are blocking and interrupt-driven.
Parameters
• uart_num: UART peripheral number

void esp_vfs_usb_serial_jtag_use_driver(void)
set VFS to use USB-SERIAL-JTAG driver for reading and writing
Note application must configure USB-SERIAL-JTAG driver before calling these functions With these func-
tions, read and write are blocking and interrupt-driven.
void esp_vfs_usb_serial_jtag_use_nonblocking(void)
set VFS to use simple functions for reading and writing UART Read is non-blocking, write is busy waiting
until TX FIFO has enough space. These functions are used by default.
Header File
• components/vfs/include/esp_vfs_eventfd.h
Functions
esp_err_t esp_vfs_eventfd_register(const esp_vfs_eventfd_config_t *config)
Registers the event vfs.
Return ESP_OK if successful, ESP_ERR_NO_MEM if too many VFSes are registered.
esp_err_t esp_vfs_eventfd_unregister(void)
Unregisters the event vfs.
Return ESP_OK if successful, ESP_ERR_INVALID_STATE if VFS for given prefix hasn t been registered
int eventfd(unsigned int initval, int flags)
Structures
struct esp_vfs_eventfd_config_t
Eventfd vfs initialization settings.
Public Members
size_t max_fds
The maxinum number of eventfds supported
Macros
EFD_SUPPORT_ISR
ESP_VFS_EVENTD_CONFIG_DEFAULT()
2.6.9 Wear Levelling API
Overview
Most of flash memory and especially SPI flash that is used in ESP32 has a sector-based organization and also has a
limited number of erase/modification cycles per memory sector. The wear levelling component helps to distribute
wear and tear among sectors more evenly without requiring any attention from the user.
The wear levelling component provides API functions related to reading, writing, erasing, and memory mapping of
data in external SPI flash through the partition component. The component also has higher-level API functions which
work with the FAT filesystem defined in FAT filesystem.
The wear levelling component, together with the FAT FS component, uses FAT FS sectors of 4096 bytes, which is
a standard size for flash memory. With this size, the component shows the best performance but needs additional
memory in RAM.
To save internal memory, the component has two additional modes which both use sectors of 512 bytes:
• Performance mode. Erase sector operation data is stored in RAM, the sector is erased, and then data is copied
back to flash memory. However, if a device is powered off for any reason, all 4096 bytes of data is lost.

• Safety mode. The data is first saved to flash memory, and after the sector is erased, the data is saved back. If
a device is powered off, the data can be recovered as soon as the device boots up.
The default settings are as follows: - Sector size is 512 bytes - Performance mode
You can change the settings through the configuration menu.
The wear levelling component does not cache data in RAM. The write and erase functions modify flash directly, and
flash contents are consistent when the function returns.
Wear Levelling access API functions
This is the set of API functions for working with data in flash:
• wl_mount - initializes the wear levelling module and mounts the specified partition
• wl_unmount - unmounts the partition and deinitializes the wear levelling module
• wl_erase_range - erases a range of addresses in flash
• wl_write - writes data to a partition
• wl_read - reads data from a partition
• wl_size - returns the size of available memory in bytes
• wl_sector_size - returns the size of one sector
As a rule, try to avoid using raw wear levelling functions and use filesystem-specific functions instead.
Memory Size
The memory size is calculated in the wear levelling module based on partition parameters. The module uses some
sectors of flash for internal data.
See also
• FAT Filesystem
Application Example
An example which combines the wear levelling driver with the FATFS library is provided in the storage/wear_levelling
directory. This example initializes the wear levelling driver, mounts FATFS partition, as well as writes and reads data
from it using POSIX and C library APIs. See the storage/wear_levelling/README.md file for more information.
High level API Reference
Header Files
• fatfs/vfs/esp_vfs_fat.h
Functions
esp_err_t esp_vfs_fat_spiflash_mount(const char *base_path, const char *partition_label,
const esp_vfs_fat_mount_config_t *mount_config,
wl_handle_t *wl_handle)
Convenience function to initialize FAT filesystem in SPI flash and register it in VFS.
• finds the partition with defined partition_label. Partition label should be configured in the partition table.
• initializes flash wear levelling library on top of the given partition
• mounts FAT partition using FATFS library on top of flash wear levelling library

This function is intended to make example code more compact.

Return
• ESP_ERR_NOT_FOUND if the partition table does not contain FATFS partition with given label
• ESP_ERR_INVALID_STATE if esp_vfs_fat_spiflash_mount was already called
• other error codes from wear levelling library, SPI flash driver, or FATFS drivers
Parameters
• base_path: path where FATFS partition should be mounted (e.g. /spiflash )
• partition_label: label of the partition which should be used
• [out] wl_handle: wear levelling driver handle
struct esp_vfs_fat_mount_config_t
Configuration arguments for esp_vfs_fat_sdmmc_mount and esp_vfs_fat_spiflash_mount functions.
Public Members
If FAT partition can not be mounted, and this parameter is true, create partition table and format the
filesystem.
int max_files
Max number of open files.
size_t allocation_unit_size
If format_if_mount_failed is set, and mount fails, format the card with given allocation unit size. Must
be a power of 2, between sector size and 128 * sector size. For SD cards, sector size is always 512 bytes.
For wear_levelling, sector size is determined by CONFIG_WL_SECTOR_SIZE option.
Using larger allocation unit size will result in higher read/write performance and higher overhead when
storing small files.
Setting this field to 0 will result in allocation unit set to the sector size.
esp_err_t esp_vfs_fat_spiflash_unmount(const char *base_path, wl_handle_t wl_handle)
Unmount FAT filesystem and release resources acquired using esp_vfs_fat_spiflash_mount.
Return
• ESP_ERR_INVALID_STATE if esp_vfs_fat_spiflash_mount hasn t been called
Parameters
• base_path: path where partition should be registered (e.g. /spiflash )
• wl_handle: wear levelling driver handle returned by esp_vfs_fat_spiflash_mount
Mid level API Reference
Header File
• components/wear_levelling/include/wear_levelling.h
Functions
esp_err_t wl_mount(const esp_partition_t *partition, wl_handle_t *out_handle)
Mount WL for defined partition.
Return
• ESP_OK, if the allocation was successfully;
• ESP_ERR_INVALID_ARG, if WL allocation was unsuccessful;
• ESP_ERR_NO_MEM, if there was no memory to allocate WL components;

Parameters
• partition: that will be used for access
• out_handle: handle of the WL instance
esp_err_t wl_unmount(wl_handle_t handle)
Unmount WL for defined partition.
Return
• ESP_OK, if the operation completed successfully;
• or one of error codes from lower-level flash driver.
Parameters
• handle: WL partition handle
esp_err_t wl_erase_range(wl_handle_t handle, size_t start_addr, size_t size)
Erase part of the WL storage.
Return
• ESP_OK, if the range was erased successfully;
• ESP_ERR_INVALID_ARG, if iterator or dst are NULL;
• ESP_ERR_INVALID_SIZE, if erase would go out of bounds of the partition;
Parameters
• handle: WL handle that are related to the partition
• start_addr: Address where erase operation should start. Must be aligned to the result of function
wl_sector_size( ).
• size: Size of the range which should be erased, in bytes. Must be divisible by result of function
wl_sector_size( )..
esp_err_t wl_write(wl_handle_t handle, size_t dest_addr, const void *src, size_t size)
Write data to the WL storage.
wl_erase_range function.
Note Prior to writing to WL storage, make sure it has been erased with wl_erase_range call.
Return
• ESP_OK, if data was written successfully;
• ESP_ERR_INVALID_ARG, if dst_offset exceeds partition size;
• ESP_ERR_INVALID_SIZE, if write would go out of bounds of the partition;
Parameters
• handle: WL handle that are related to the partition
• dest_addr: Address where the data should be written, relative to the beginning of the partition.
bytes long.
esp_err_t wl_read(wl_handle_t handle, size_t src_addr, void *dest, size_t size)
Read data from the WL storage.
Return
• ESP_OK, if data was read successfully;
• ESP_ERR_INVALID_ARG, if src_offset exceeds partition size;
• ESP_ERR_INVALID_SIZE, if read would go out of bounds of the partition;
Parameters
• handle: WL module instance that was initialized before
• dest: Pointer to the buffer where data should be stored. Pointer must be non-NULL and buffer
must be at least size bytes long.
• src_addr: Address of the data to be read, relative to the beginning of the partition.
size_t wl_size(wl_handle_t handle)
Get size of the WL storage.

Return usable size, in bytes

Parameters
• handle: WL module handle that was initialized before
size_t wl_sector_size(wl_handle_t handle)
Get sector size of the WL instance.
Return sector size, in bytes
Parameters
• handle: WL module handle that was initialized before
Macros
WL_INVALID_HANDLE
Type Definitions
typedef int32_t wl_handle_t
wear levelling handle
Code examples for this API section are provided in the storage directory of ESP-IDF examples.
2.7 System API
2.7.1 App Image Format
An application image consists of the following structures:

1. The esp_image_header_t structure describes the mode of SPI flash and the count of memory segments.
2. The esp_image_segment_header_t structure describes each segment, its length, and its location in
ESP32 s memory, followed by the data with a length of data_len. The data offset for each segment in the
image is calculated in the following way:
• offset for 0 Segment = sizeof(esp_image_header_t) + sizeof(esp_image_segment_header_t).
• offset for 1 Segment = offset for 0 Segment + length of 0 Segment +
sizeof(esp_image_segment_header_t).
• offset for 2 Segment = offset for 1 Segment + length of 1 Segment +
sizeof(esp_image_segment_header_t).
•
The count of each segment is defined in the segment_count field that is stored in esp_image_header_t.
The count cannot be more than ESP_IMAGE_MAX_SEGMENTS.
To get the list of your image segments, please run the following command:
esptool.py --chip esp32 image_info build/app.bin
esptool.py v2.3.1
Image version: 1
Entry point: 40080ea4
13 segments
Segment 1: len 0x13ce0 load 0x3f400020 file_offs 0x00000018 SOC_DROM
Segment 2: len 0x00000 load 0x3ff80000 file_offs 0x00013d00 SOC_RTC_DRAM
Segment 3: len 0x00000 load 0x3ff80000 file_offs 0x00013d08 SOC_RTC_DRAM
Segment 4: len 0x028e0 load 0x3ffb0000 file_offs 0x00013d10 DRAM
Segment 5: len 0x00000 load 0x3ffb28e0 file_offs 0x000165f8 DRAM
Segment 6: len 0x00400 load 0x40080000 file_offs 0x00016600 SOC_IRAM
Segment 7: len 0x09600 load 0x40080400 file_offs 0x00016a08 SOC_IRAM
Segment 8: len 0x62e4c load 0x400d0018 file_offs 0x00020010 SOC_IROM
Segment 9: len 0x06cec load 0x40089a00 file_offs 0x00082e64 SOC_IROM
Segment 10: len 0x00000 load 0x400c0000 file_offs 0x00089b58 SOC_RTC_IRAM


Segment 11: len 0x00004 load 0x50000000 file_offs 0x00089b60 SOC_RTC_DATA
Segment 12: len 0x00000 load 0x50000004 file_offs 0x00089b6c SOC_RTC_DATA
Segment 13: len 0x00000 load 0x50000004 file_offs 0x00089b74 SOC_RTC_DATA
Checksum: e8 (valid)Validation Hash:␣
,→407089ca0eae2bbf83b4120979d3354b1c938a49cb7a0c997f240474ef2ec76b (valid)
You can also see the information on segments in the IDF logs while your application is booting:
I (443) esp_image: segment 0: paddr=0x00020020 vaddr=0x3f400020 size=0x13ce0 (␣

,→81120) map
I (489) esp_image: segment 1: paddr=0x00033d08 vaddr=0x3ff80000 size=0x00000 ( 0)␣

,→load
I (530) esp_image: segment 2: paddr=0x00033d10 vaddr=0x3ff80000 size=0x00000 ( 0)␣

,→load
I (571) esp_image: segment 3: paddr=0x00033d18 vaddr=0x3ffb0000 size=0x028e0 (␣

,→10464) load
I (612) esp_image: segment 4: paddr=0x00036600 vaddr=0x3ffb28e0 size=0x00000 ( 0)␣

,→load
I (654) esp_image: segment 5: paddr=0x00036608 vaddr=0x40080000 size=0x00400 (␣

,→1024) load
I (695) esp_image: segment 6: paddr=0x00036a10 vaddr=0x40080400 size=0x09600 (␣

,→38400) load
I (737) esp_image: segment 7: paddr=0x00040018 vaddr=0x400d0018 size=0x62e4c␣

,→(405068) map
I (847) esp_image: segment 8: paddr=0x000a2e6c vaddr=0x40089a00 size=0x06cec (␣

,→27884) load
I (888) esp_image: segment 9: paddr=0x000a9b60 vaddr=0x400c0000 size=0x00000 ( 0)␣

,→load
I (929) esp_image: segment 10: paddr=0x000a9b68 vaddr=0x50000000 size=0x00004 ( 4)␣

,→load
I (971) esp_image: segment 11: paddr=0x000a9b74 vaddr=0x50000004 size=0x00000 ( 0)␣

,→load
I (1012) esp_image: segment 12: paddr=0x000a9b7c vaddr=0x50000004 size=0x00000 (␣

,→0) load
For more details on the type of memory segments and their address ranges, see ESP32 Technical Reference Manual
> System and Memory > Embedded Memory [PDF].
3. The image has a single checksum byte after the last segment. This byte is written on a sixteen byte padded
boundary, so the application image might need padding.
4. If the hash_appended field from esp_image_header_t is set then a SHA256 checksum will be ap-
pended. The value of SHA256 is calculated on the range from first byte and up to this field. The length of this
field is 32 bytes.
5. If the options CONFIG_SECURE_SIGNED_APPS_SCHEME is set to ECDSA then the application image will
have additional 68 bytes for an ECDSA signature, which includes:
• version word (4 bytes),
• signature data (64 bytes).
Application Description
The DROM segment starts with the esp_app_desc_t structure which carries specific fields describing the appli-
cation:
• secure_version - see Anti-rollback.
• version - see App version. *
• project_name is filled from PROJECT_NAME. *
• time and date - compile time and date.
• idf_ver - version of ESP-IDF. *
• app_elf_sha256 - contains sha256 for the elf application file.

* - The maximum length is 32 characters, including null-termination character. For example, if the length of
PROJECT_NAME exceeds 32 characters, the excess characters will be disregarded.
This structure is useful for identification of images uploaded OTA because it has a fixed offset =
sizeof(esp_image_header_t) + sizeof(esp_image_segment_header_t). As soon as a device receives
the first fragment containing this structure, it has all the information to determine whether the update should be
continued or not.
Adding a Custom Structure to an Application
Customer also has the opportunity to have similar structure with a fixed offset relative to the beginning of the image.
The following pattern can be used to add a custom structure to your image:
const __attribute__((section(".rodata_custom_desc"))) esp_custom_app_desc_t custom_

,→app_desc = { ... }
Offset for custom structure is sizeof(esp_image_header_t) + sizeof(esp_image_segment_header_t)

+ sizeof(esp_app_desc_t).
To guarantee that the custom structure is located in the image even if it is not used, you need to add tar-
get_link_libraries(${COMPONENT_TARGET} "-u custom_app_desc") into CMakeLists.
txt.
API Reference
Header File
• components/bootloader_support/include/esp_app_format.h
Structures
struct esp_image_header_t
Main header of binary image.
Public Members
uint8_t magic
Magic word ESP_IMAGE_HEADER_MAGIC
uint8_t segment_count
Count of memory segments
uint8_t spi_mode
flash read mode (esp_image_spi_mode_t as uint8_t)
uint8_t spi_speed : 4
flash frequency (esp_image_spi_freq_t as uint8_t)
uint8_t spi_size : 4
flash chip size (esp_image_flash_size_t as uint8_t)
uint32_t entry_addr
Entry address
uint8_t wp_pin
WP pin when SPI pins set via efuse (read by ROM bootloader, the IDF bootloader uses software to
configure the WP pin and sets this field to 0xEE=disabled)
uint8_t spi_pin_drv[3]
Drive settings for the SPI flash pins (read by ROM bootloader)

esp_chip_id_t chip_id
Chip identification number
uint8_t min_chip_rev
Minimum chip revision supported by image
uint8_t reserved[8]
Reserved bytes in additional header space, currently unused
uint8_t hash_appended
If 1, a SHA256 digest simple hash (of the entire image) is appended after the checksum. Included
in image length. This digest is separate to secure boot and only used for detecting corruption. For secure
boot signed images, the signature is appended after this (and the simple hash is included in the signed
data).
struct esp_image_segment_header_t
Header of binary image segment.
Public Members
uint32_t load_addr
Address of segment
uint32_t data_len
Length of data
struct esp_app_desc_t
Description about application.
Public Members
uint32_t magic_word
Magic word ESP_APP_DESC_MAGIC_WORD
uint32_t secure_version
Secure version
uint32_t reserv1[2]
reserv1
char version[32]
Application version
char project_name[32]
Project name
char time[16]
Compile time
char date[16]
Compile date
char idf_ver[32]
Version IDF
uint8_t app_elf_sha256[32]
sha256 of elf file
uint32_t reserv2[20]
reserv2

Macros
ESP_IMAGE_HEADER_MAGIC
The magic word for the esp_image_header_t structure.
ESP_IMAGE_MAX_SEGMENTS
Max count of segments in the image.
ESP_APP_DESC_MAGIC_WORD
The magic word for the esp_app_desc structure that is in DROM.
Enumerations
enum esp_chip_id_t
ESP chip ID.
Values:
ESP_CHIP_ID_ESP32 = 0x0000
chip ID: ESP32
ESP_CHIP_ID_ESP32S2 = 0x0002
chip ID: ESP32-S2
ESP_CHIP_ID_ESP32C3 = 0x0005
chip ID: ESP32-C3
ESP_CHIP_ID_ESP32S3 = 0x0009
chip ID: ESP32-S3
ESP_CHIP_ID_ESP32H2 = 0x000A
chip ID: ESP32-H2
ESP_CHIP_ID_ESP8684 = 0x000C
chip ID: ESP32-8684
ESP_CHIP_ID_INVALID = 0xFFFF
Invalid chip ID (we defined it to make sure the esp_chip_id_t is 2 bytes size)
enum esp_image_spi_mode_t
SPI flash mode, used in esp_image_header_t.
Values:
ESP_IMAGE_SPI_MODE_QIO
SPI mode QIO
ESP_IMAGE_SPI_MODE_QOUT
SPI mode QOUT
ESP_IMAGE_SPI_MODE_DIO
SPI mode DIO
ESP_IMAGE_SPI_MODE_DOUT
SPI mode DOUT
ESP_IMAGE_SPI_MODE_FAST_READ
SPI mode FAST_READ
ESP_IMAGE_SPI_MODE_SLOW_READ
SPI mode SLOW_READ
enum esp_image_spi_freq_t
SPI flash clock frequency.
Values:
ESP_IMAGE_SPI_SPEED_40M
SPI clock frequency 40 MHz

ESP_IMAGE_SPI_SPEED_80M = 0xF
enum esp_image_flash_size_t
Supported SPI flash sizes.
Values:
ESP_IMAGE_FLASH_SIZE_1MB = 0
SPI flash size 1 MB
ESP_IMAGE_FLASH_SIZE_2MB
ESP_IMAGE_FLASH_SIZE_MAX
SPI flash size MAX
2.7.2 Application Level Tracing
Overview
IDF provides useful feature for program behaviour analysis: application level tracing. It is implemented in the cor-
responding library and can be enabled via menuconfig. This feature allows to transfer arbitrary data between host
and ESP32 via JTAG interface with small overhead on program execution. Developers can use this library to send
application specific state of execution to the host and receive commands or other type of info in the opposite direction
at runtime. The main use cases of this library are:
1. Collecting application specific data, see Application Specific Tracing
2. Lightweight logging to the host, see Logging to Host
3. System behaviour analysis, see System Behavior Analysis with SEGGER SystemView
API Reference
Header File
• components/app_trace/include/esp_app_trace.h
Functions
esp_err_t esp_apptrace_init(void)
Initializes application tracing module.
Note Should be called before any esp_apptrace_xxx call.
Return ESP_OK on success, otherwise see esp_err_t
void esp_apptrace_down_buffer_config(uint8_t *buf, uint32_t size)
Configures down buffer.
Note Needs to be called before initiating any data transfer using esp_apptrace_buffer_get and
esp_apptrace_write. This function does not protect internal data by lock.

Parameters
• buf: Address of buffer to use for down channel (host to target) data.
• size: Size of the buffer.
uint8_t *esp_apptrace_buffer_get(esp_apptrace_dest_t dest, uint32_t size, uint32_t tmo)
Allocates buffer for trace data. After data in buffer are ready to be sent off esp_apptrace_buffer_put must be
called to indicate it.
Return non-NULL on success, otherwise NULL.
Parameters
• dest: Indicates HW interface to send data.
• size: Size of data to write to trace buffer.
• tmo: Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely.
esp_err_t esp_apptrace_buffer_put(esp_apptrace_dest_t dest, uint8_t *ptr, uint32_t tmo)
Indicates that the data in buffer are ready to be sent off. This function is a counterpart of and must be preceeded
by esp_apptrace_buffer_get.
Parameters
• dest: Indicates HW interface to send data. Should be identical to the same parameter in call to
esp_apptrace_buffer_get.
• ptr: Address of trace buffer to release. Should be the value returned by call to
esp_apptrace_buffer_get.
esp_err_t esp_apptrace_write(esp_apptrace_dest_t dest, const void *data, uint32_t size, uint32_t
tmo)
Writes data to trace buffer.
Parameters
• data: Address of data to write to trace buffer.
• size: Size of data to write to trace buffer.
int esp_apptrace_vprintf_to(esp_apptrace_dest_t dest, uint32_t tmo, const char *fmt, va_list ap)
vprintf-like function to sent log messages to host via specified HW interface.
Return Number of bytes written.
Parameters
• fmt: Address of format string.
• ap: List of arguments.
int esp_apptrace_vprintf(const char *fmt, va_list ap)
vprintf-like function to sent log messages to host.
Parameters
• fmt: Address of format string.
• ap: List of arguments.
esp_err_t esp_apptrace_flush(esp_apptrace_dest_t dest, uint32_t tmo)
Flushes remaining data in trace buffer to host.
Parameters
• dest: Indicates HW interface to flush data on.
esp_err_t esp_apptrace_flush_nolock(esp_apptrace_dest_t dest, uint32_t min_sz, uint32_t tmo)
Flushes remaining data in trace buffer to host without locking internal data. This is special version of

esp_apptrace_flush which should be called from panic handler.

Parameters
• dest: Indicates HW interface to flush data on.
• min_sz: Threshold for flushing data. If current filling level is above this value, data will be flushed.
TRAX destinations only.
esp_err_t esp_apptrace_read(esp_apptrace_dest_t dest, void *data, uint32_t *size, uint32_t tmo)
Reads host data from trace buffer.
Parameters
• dest: Indicates HW interface to read the data on.
• data: Address of buffer to put data from trace buffer.
• size: Pointer to store size of read data. Before call to this function pointed memory must hold
requested size of data
uint8_t *esp_apptrace_down_buffer_get(esp_apptrace_dest_t dest, uint32_t *size, uint32_t tmo)
Retrieves incoming data buffer if any. After data in buffer are processed esp_apptrace_down_buffer_put must
be called to indicate it.
Return non-NULL on success, otherwise NULL.
Parameters
• dest: Indicates HW interface to receive data.
• size: Address to store size of available data in down buffer. Must be initialized with requested
value.
esp_err_t esp_apptrace_down_buffer_put(esp_apptrace_dest_t dest, uint8_t *ptr, uint32_t tmo)
Indicates that the data in down buffer are processed. This function is a counterpart of and must be preceeded
by esp_apptrace_down_buffer_get.
Parameters
• dest: Indicates HW interface to receive data. Should be identical to the same parameter in call to
esp_apptrace_down_buffer_get.
• ptr: Address of trace buffer to release. Should be the value returned by call to
esp_apptrace_down_buffer_get.
bool esp_apptrace_host_is_connected(esp_apptrace_dest_t dest)
Checks whether host is connected.
Return true if host is connected, otherwise false
Parameters
• dest: Indicates HW interface to use.
void *esp_apptrace_fopen(esp_apptrace_dest_t dest, const char *path, const char *mode)
Opens file on host. This function has the same semantic as fopen except for the first argument.
Return non zero file handle on success, otherwise 0
Parameters
• path: Path to file.
• mode: Mode string. See fopen for details.
int esp_apptrace_fclose(esp_apptrace_dest_t dest, void *stream)
Closes file on host. This function has the same semantic as fclose except for the first argument.
Return Zero on success, otherwise non-zero. See fclose for details.
Parameters

• stream: File handle returned by esp_apptrace_fopen.

size_t esp_apptrace_fwrite(esp_apptrace_dest_t dest, const void *ptr, size_t size, size_t nmemb,
void *stream)
Writes to file on host. This function has the same semantic as fwrite except for the first argument.
Return Number of written items. See fwrite for details.
Parameters
• ptr: Address of data to write.
• size: Size of an item.
• nmemb: Number of items to write.
size_t esp_apptrace_fread(esp_apptrace_dest_t dest, void *ptr, size_t size, size_t nmemb, void
*stream)
Read file on host. This function has the same semantic as fread except for the first argument.
Return Number of read items. See fread for details.
Parameters
• ptr: Address to store read data.
• size: Size of an item.
• nmemb: Number of items to read.
int esp_apptrace_fseek(esp_apptrace_dest_t dest, void *stream, long offset, int whence)
Set position indicator in file on host. This function has the same semantic as fseek except for the first
argument.
Return Zero on success, otherwise non-zero. See fseek for details.
Parameters
• offset: Offset. See fseek for details.
• whence: Position in file. See fseek for details.
int esp_apptrace_ftell(esp_apptrace_dest_t dest, void *stream)
Get current position indicator for file on host. This function has the same semantic as ftell except for the
first argument.
Return Current position in file. See ftell for details.
Parameters
int esp_apptrace_fstop(esp_apptrace_dest_t dest)
Indicates to the host that all file operations are completed. This function should be called after all file operations
are finished and indicate to the host that it can perform cleanup operations (close open files etc.).
Parameters
void esp_gcov_dump(void)
Triggers gcov info dump. This function waits for the host to connect to target before dumping data.
Enumerations
enum esp_apptrace_dest_t
Application trace data destinations bits.
Values:

ESP_APPTRACE_DEST_JTAG = 1
JTAG destination.
ESP_APPTRACE_DEST_TRAX = ESP_APPTRACE_DEST_JTAG
xxx_TRAX name is obsolete, use more common xxx_JTAG
ESP_APPTRACE_DEST_UART0
UART0 destination.
ESP_APPTRACE_DEST_MAX = ESP_APPTRACE_DEST_UART0
ESP_APPTRACE_DEST_NUM
Header File
• components/app_trace/include/esp_sysview_trace.h
Functions
static esp_err_t esp_sysview_flush(uint32_t tmo)
Flushes remaining data in SystemView trace buffer to host.
Return ESP_OK.
Parameters
• tmo: Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinetly.
int esp_sysview_vprintf(const char *format, va_list args)
vprintf-like function to sent log messages to the host.
Parameters
• format: Address of format string.
• args: List of arguments.
esp_err_t esp_sysview_heap_trace_start(uint32_t tmo)
Starts SystemView heap tracing.
Return ESP_OK on success, ESP_ERR_TIMEOUT if operation has been timed out.
Parameters
• tmo: Timeout (in us) to wait for the host to be connected. Use -1 to wait forever.
esp_err_t esp_sysview_heap_trace_stop(void)
Stops SystemView heap tracing.
Return ESP_OK.
void esp_sysview_heap_trace_alloc(void *addr, uint32_t size, const void *callers)
Sends heap allocation event to the host.
Parameters
• addr: Address of allocated block.
• size: Size of allocated block.
• callers: Pointer to array with callstack addresses. Array size must be CON-
FIG_HEAP_TRACING_STACK_DEPTH.
void esp_sysview_heap_trace_free(void *addr, const void *callers)
Sends heap de-allocation event to the host.
Parameters
• addr: Address of de-allocated block.
• callers: Pointer to array with callstack addresses. Array size must be CON-
FIG_HEAP_TRACING_STACK_DEPTH.

2.7.3 Console
ESP-IDF provides console component, which includes building blocks needed to develop an interactive console
over serial port. This component includes following facilities:
• Line editing, provided by linenoise library. This includes handling of backspace and arrow keys, scrolling
through command history, command auto-completion, and argument hints.
• Splitting of command line into arguments.
• Argument parsing, provided by argtable3 library. This library includes APIs used for parsing GNU style
command line arguments.
• Functions for registration and dispatching of commands.
• Functions to establish a basic REPL (Read-Evaluate-Print-Loop) environment.
Note: These facilities can be used together or independently. For example, it is possible to use line editing and
command registration features, but use getopt or custom code for argument parsing, instead of argtable3. Likewise,
it is possible to use simpler means of command input (such as fgets) together with the rest of the means for
command splitting and argument parsing.
Line editing
Line editing feature lets users compose commands by typing them, erasing symbols using backspace key, navi-
gating within the command using left/right keys, navigating to previously typed commands using up/down keys, and
performing autocompletion using tab key.
Note: This feature relies on ANSI escape sequence support in the terminal application. As such, serial monitors
which display raw UART data can not be used together with the line editing library. If you see [6n or similar escape
sequence when running system/console example instead of a command prompt (e.g. esp> ), it means that the serial
monitor does not support escape sequences. Programs which are known to work are GNU screen, minicom, and
idf_monitor.py (which can be invoked using idf.py monitor from project directory).
Here is an overview of functions provided by linenoise library.
Configuration Linenoise library does not need explicit initialization. However, some configuration defaults may
need to be changed before invoking the main line editing function.
linenoiseClearScreen()
Clear terminal screen using an escape sequence and position the cursor at the top left corner.
linenoiseSetMultiLine()
Switch between single line and multi line editing modes. In single line mode, if the length of the com-
mand exceeds the width of the terminal, the command text is scrolled within the line to show the end of
the text. In this case the beginning of the text is hidden. Single line needs less data to be sent to refresh
screen on each key press, so exhibits less glitching compared to the multi line mode. On the flip side,
editing commands and copying command text from terminal in single line mode is harder. Default is
single line mode.
linenoiseAllowEmpty()
Set whether linenoise library will return a zero-length string (if true) or NULL (if false) for empty
lines. By default, zero-length strings are returned.
linenoiseSetMaxLineLen()
Set maximum length of the line for linenoise library. Default length is 4096. If you need optimize RAM
memory usage, you can do it by this function by setting a value less than default 4 KB.

Main loop linenoise()

In most cases, console applications have some form of read/eval loop. linenoise() is the single
function which handles user s key presses and returns completed line once enter key is pressed. As
such, it handles the read part of the loop.
linenoiseFree()
This function must be called to release the command line buffer obtained from linenoise() function.
Hints and completions linenoiseSetCompletionCallback()

When user presses tab key, linenoise library invokes completion callback. The callback should in-
spect the contents of the command typed so far and provide a list of possible completions using calls to
linenoiseAddCompletion() function. linenoiseSetCompletionCallback() func-
tion should be called to register this completion callback, if completion feature is desired.
console component provides a ready made function to provide completions for registered commands,
esp_console_get_completion() (see below).
linenoiseAddCompletion()
Function to be called by completion callback to inform the library about possible completions of the
currently typed command.
linenoiseSetHintsCallback()
Whenever user input changes, linenoise invokes hints callback. This callback can inspect the command
line typed so far, and provide a string with hints (which can include list of command arguments, for
example). The library then displays the hint text on the same line where editing happens, possibly with
a different color.
linenoiseSetFreeHintsCallback()
If hint string returned by hints callback is dynamically allocated or needs to be otherwise recycled, the
function which performs such cleanup should be registered via linenoiseSetFreeHintsCall-
back().
History linenoiseHistorySetMaxLen()
This function sets the number of most recently typed commands to be kept in memory. Users can
navigate the history using up/down arrows.
linenoiseHistoryAdd()
Linenoise does not automatically add commands to history. Instead, applications need to call this func-
tion to add command strings to the history.
linenoiseHistorySave()
Function saves command history from RAM to a text file, for example on an SD card or on a filesystem
in flash memory.
linenoiseHistoryLoad()
Counterpart to linenoiseHistorySave(), loads history from a file.
linenoiseHistoryFree()
Releases memory used to store command history. Call this function when done working with linenoise
library.

Splitting of command line into arguments
console component provides esp_console_split_argv() function to split command line string into ar-
guments. The function returns the number of arguments found (argc) and fills an array of pointers which can be
passed as argv argument to any function which accepts arguments in argc, argv format.
The command line is split into arguments according to the following rules:
• Arguments are separated by spaces
• If spaces within arguments are required, they can be escaped using \ (backslash) character.
• Other escape sequences which are recognized are \\ (which produces literal backslash) and \", which pro-
duces a double quote.
• Arguments can be quoted using double quotes. Quotes may appear only in the beginning and at the end of the
argument. Quotes within the argument must be escaped as mentioned above. Quotes surrounding the argument
are stripped by esp_console_split_argv function.
Examples:
• abc def 1 20 .3 ⟶ [ abc, def, 1, 20, .3 ]
• abc "123 456" def ⟶ [ abc, 123 456, def ]
• à\ b\\c\" ⟶ [ a b\c" ]
Argument parsing
For argument parsing, console component includes argtable3 library. Please see tutorial for an introduction to
argtable3. Github repository also includes examples.
Command registration and dispatching
console component includes utility functions which handle registration of commands, matching commands typed
by the user to registered ones, and calling these commands with the arguments given on the command line.
Application first initializes command registration module using a call to esp_console_init(), and calls
esp_console_cmd_register() function to register command handlers.
For each command, application provides the following information (in the form of esp_console_cmd_t struc-
ture):
• Command name (string without spaces)
• Help text explaining what the command does
• Optional hint text listing the arguments of the command. If application uses Argtable3 for argument pars-
ing, hint text can be generated automatically by providing a pointer to argtable argument definitions structure
instead.
• The command handler function.
A few other functions are provided by the command registration module:
esp_console_run()
This function takes the command line string, splits it into argc/argv argument list using
esp_console_split_argv(), looks up the command in the list of registered components, and
if it is found, executes its handler.
esp_console_register_help_command()
Adds help command to the list of registered commands. This command prints the list of all the regis-
tered commands, along with their arguments and help texts.
esp_console_get_completion()
Callback function to be used with linenoiseSetCompletionCallback() from linenoise li-
brary. Provides completions to linenoise based on the list of registered commands.
esp_console_get_hint()

Callback function to be used with linenoiseSetHintsCallback() from linenoise library. Pro-

vides argument hints for registered commands to linenoise.
Initialize console REPL environment
To establish a basic REPL environment, console component provides several useful APIs, combining those func-
tions described above.
In a typical application, you only need to call esp_console_new_repl_uart() to initialize the REPL envi-
ronment based on UART device, including driver install, basic console configuration, spawning a thread to do REPL
task and register several useful commands (e.g. help).
After that, you can register your own commands with esp_console_cmd_register(). The REPL environ-
ment keeps in init state until you call esp_console_start_repl().
Application Example
Example application illustrating usage of the console component is available in system/console directory. This
example shows how to initialize UART and VFS functions, set up linenoise library, read and handle commands from
UART, and store command history in Flash. See README.md in the example directory for more details.
Besides that, ESP-IDF contains several useful examples which based on console component and can be treated as
tools when developing applications. For example, peripherals/i2c/i2c_tools, wifi/iperf.
API Reference
Header File
• components/console/esp_console.h
Functions
esp_err_t esp_console_init(const esp_console_config_t *config)
initialize console module
Note Call this once before using other console module features
Return
• ESP_ERR_INVALID_ARG if the configuration is invalid
Parameters
• config: console configuration
esp_err_t esp_console_deinit(void)
de-initialize console module
Note Call this once when done using console module functions
Return
• ESP_ERR_INVALID_STATE if not initialized yet
esp_err_t esp_console_cmd_register(const esp_console_cmd_t *cmd)
Register console command.
Return
• ESP_ERR_INVALID_ARG if command description includes invalid arguments
Parameters
• cmd: pointer to the command description; can point to a temporary value

esp_err_t esp_console_run(const char *cmdline, int *cmd_ret)

Run command line.
Return
• ESP_OK, if command was run
• ESP_ERR_INVALID_ARG, if the command line is empty, or only contained whitespace
• ESP_ERR_NOT_FOUND, if command with given name wasn t registered
• ESP_ERR_INVALID_STATE, if esp_console_init wasn t called
Parameters
• cmdline: command line (command name followed by a number of arguments)
• [out] cmd_ret: return code from the command (set if command was run)
size_t esp_console_split_argv(char *line, char **argv, size_t argv_size)
Split command line into arguments in place.
* - This function finds whitespace-separated arguments in the given input line.

*
* 'abc def 1 20 .3' -> [ 'abc', 'def', '1', '20', '.3' ]
*
* - Argument which include spaces may be surrounded with quotes. In this case
* spaces are preserved and quotes are stripped.
*
* 'abc "123 456" def' -> [ 'abc', '123 456', 'def' ]
*
* - Escape sequences may be used to produce backslash, double quote, and space:
*
* 'a\ b\\c\"' -> [ 'a b\c"' ]
*
Note Pointers to at most argv_size - 1 arguments are returned in argv array. The pointer after the last one (i.e.
argv[argc]) is set to NULL.
Return number of arguments found (argc)
Parameters
• line: pointer to buffer to parse; it is modified in place
• argv: array where the pointers to arguments are written
• argv_size: number of elements in argv_array (max. number of arguments)
void esp_console_get_completion(const char *buf, linenoiseCompletions *lc)
Callback which provides command completion for linenoise library.
When using linenoise for line editing, command completion support can be enabled like this:
linenoiseSetCompletionCallback(&esp_console_get_completion);
Parameters
• buf: the string typed by the user
• lc: linenoiseCompletions to be filled in
const char *esp_console_get_hint(const char *buf, int *color, int *bold)
Callback which provides command hints for linenoise library.
When using linenoise for line editing, hints support can be enabled as follows:
linenoiseSetHintsCallback((linenoiseHintsCallback*) &esp_console_get_hint);
The extra cast is needed because linenoiseHintsCallback is defined as returning a char* instead of const char*.
Return string containing the hint text. This string is persistent and should not be freed (i.e. linenoiseSetFree-
HintsCallback should not be used).
Parameters
• buf: line typed by the user
• [out] color: ANSI color code to be used when displaying the hint
• [out] bold: set to 1 if hint has to be displayed in bold

esp_err_t esp_console_register_help_command(void)
Register a help command.
Default help command prints the list of registered commands along with hints and help strings.
Return
• ESP_ERR_INVALID_STATE, if esp_console_init wasn t called
esp_err_t esp_console_new_repl_uart(const esp_console_dev_uart_config_t *dev_config,
const esp_console_repl_config_t *repl_config,
esp_console_repl_t **ret_repl)
Establish a console REPL environment over UART driver.
Note This is a all-in-one function to establish the environment needed for REPL, includes:
• Install the UART driver on the console UART (8n1, 115200, REF_TICK clock source)
• Configures the stdin/stdout to go through the UART driver
• Initializes linenoise
• Spawn new thread to run REPL in the background
Attention This function is meant to be used in the examples to make the code more compact. Applications
which use console functionality should be based on the underlying linenoise and esp_console functions.
Return
Parameters
• [in] dev_config: UART device configuration
• [in] repl_config: REPL configuration
• [out] ret_repl: return REPL handle after initialization succeed, return NULL otherwise
esp_err_t esp_console_new_repl_usb_cdc(const esp_console_dev_usb_cdc_config_t
*dev_config, const esp_console_repl_config_t
*repl_config, esp_console_repl_t **ret_repl)
Establish a console REPL environment over USB CDC.
Note This is a all-in-one function to establish the environment needed for REPL, includes:
• Initializes linenoise
• Spawn new thread to run REPL in the background
Attention This function is meant to be used in the examples to make the code more compact. Applications
which use console functionality should be based on the underlying linenoise and esp_console functions.
Return
Parameters
• [in] dev_config: USB CDC configuration
• [in] repl_config: REPL configuration
• [out] ret_repl: return REPL handle after initialization succeed, return NULL otherwise
esp_err_t esp_console_start_repl(esp_console_repl_t *repl)
Start REPL environment.
Note Once the REPL got started, it won t be stopped until user call repl->del(repl) to destory the REPL
environment.
Return
• ESP_ERR_INVALID_STATE, if repl has started already
Parameters
• [in] repl: REPL handle returned from esp_console_new_repl_xxx
Structures
struct esp_console_config_t
Parameters for console initialization.

Public Members
size_t max_cmdline_length
length of command line buffer, in bytes
size_t max_cmdline_args
maximum number of command line arguments to parse
int hint_color
ASCII color code of hint text.
int hint_bold
Set to 1 to print hint text in bold.
struct esp_console_repl_config_t
Parameters for console REPL (Read Eval Print Loop)
Public Members
uint32_t max_history_len
maximum length for the history
const char *history_save_path
file path used to save history commands, set to NULL won t save to file system
repl task stack size
uint32_t task_priority
repl task priority
const char *prompt
prompt (NULL represents default: esp> )
size_t max_cmdline_length
maximum length of a command line. If 0, default value will be used
struct esp_console_dev_uart_config_t
Parameters for console device: UART.
Public Members
int channel
UART channel number (count from zero)
int baud_rate
Comunication baud rate.
int tx_gpio_num
GPIO number for TX path, -1 means using default one.
int rx_gpio_num
GPIO number for RX path, -1 means using default one.
struct esp_console_dev_usb_cdc_config_t
Parameters for console device: USB CDC.
Note It s an empty structure for now, reserved for future
struct esp_console_cmd_t
Console command description.

Public Members
const char *command

Command name. Must not be NULL, must not contain spaces. The pointer must be valid until the call
to esp_console_deinit.
const char *help
Help text for the command, shown by help command. If set, the pointer must be valid until the call to
esp_console_deinit. If not set, the command will not be listed in help output.
const char *hint
Hint text, usually lists possible arguments. If set to NULL, and argtable field is non-NULL, hint will
be generated automatically
esp_console_cmd_func_t func
Pointer to a function which implements the command.
void *argtable
Array or structure of pointers to arg_xxx structures, may be NULL. Used to generate hint text if hint
is set to NULL. Array/structure which this field points to must end with an arg_end. Only used for the
duration of esp_console_cmd_register call.
struct esp_console_repl_s
Console REPL base structure.
Public Members
esp_err_t (*del)(esp_console_repl_t *repl)

Delete console REPL environment.
Return
• ESP_FAIL on errors
Parameters
• [in] repl: REPL handle returned from esp_console_new_repl_xxx
Macros
ESP_CONSOLE_CONFIG_DEFAULT()
Default console configuration value.
ESP_CONSOLE_REPL_CONFIG_DEFAULT()
Default console repl configuration value.
ESP_CONSOLE_DEV_UART_CONFIG_DEFAULT()
ESP_CONSOLE_DEV_CDC_CONFIG_DEFAULT()
Type Definitions
typedef struct linenoiseCompletions linenoiseCompletions
typedef int (*esp_console_cmd_func_t)(int argc, char **argv)
Console command main function.
Return console command return code, 0 indicates success
Parameters
• argc: number of arguments
• argv: array with argc entries, each pointing to a zero-terminated string argument
typedef struct esp_console_repl_s esp_console_repl_t
Type defined for console REPL.

2.7.4 eFuse Manager
Introduction
The eFuse Manager library is designed to structure access to eFuse bits and make using these easy. This library
operates eFuse bits by a structure name which is assigned in eFuse table. This sections introduces some concepts
used by eFuse Manager.
Hardware description
The ESP32 has a number of eFuses which can store system and user parameters. Each eFuse is a one-bit field which
can be programmed to 1 after which it cannot be reverted back to 0. Some of system parameters are using these
eFuse bits directly by hardware modules and have special place (for example EFUSE_BLK0).
For more details, see ESP32 Technical Reference Manual > eFuse Controller (eFuse) [PDF]. Some eFuse bits are
available for user applications.
ESP32 has 4 eFuse blocks each of the size of 256 bits (not all bits are available):
• EFUSE_BLK0 is used entirely for system purposes;
• EFUSE_BLK1 is used for flash encrypt key. If not using that Flash Encryption feature, they can be used for
another purpose;
• EFUSE_BLK2 is used for security boot key. If not using that Secure Boot feature, they can be used for another
purpose;
• EFUSE_BLK3 can be partially reserved for the custom MAC address, or used entirely for user application.
Note that some bits are already used in IDF.
Each block is divided into 8 32-bits registers.
eFuse Manager component
The component has API functions for reading and writing fields. Access to the fields is carried out through the
structures that describe the location of the eFuse bits in the blocks. The component provides the ability to form fields
of any length and from any number of individual bits. The description of the fields is made in a CSV file in a table
form. To generate from a tabular form (CSV file) in the C-source uses the tool efuse_table_gen.py. The tool checks
the CSV file for uniqueness of field names and bit intersection, in case of using a custom file from the user s project
directory, the utility will check with the common CSV file.
CSV files:
• common (esp_efuse_table.csv) - contains eFuse fields which are used inside the IDF. C-source generation should
be done manually when changing this file (run command idf.py efuse-common-table). Note that
changes in this file can lead to incorrect operation.
• custom - (optional and can be enabled by CONFIG_EFUSE_CUSTOM_TABLE) contains eFuse fields that are
used by the user in their application. C-source generation should be done manually when changing this file and
running idf.py efuse-custom-table.
Description CSV file
The CSV file contains a description of the eFuse fields. In the simple case, one field has one line of description. Table
header:
# field_name, efuse_block(EFUSE_BLK0..EFUSE_BLK3), bit_start(0..255), bit_
,→count(1..256), comment
Individual params in CSV file the following meanings:

field_name Name of field. The prefix ESP_EFUSE_ will be added to the name, and this field name will be available
in the code. This name will be used to access the fields. The name must be unique for all fields. If the line has
an empty name, then this line is combined with the previous field. This allows you to set an arbitrary order of

bits in the field, and expand the field as well (see MAC_FACTORY field in the common table). The field_name
supports structured format using . to show that the field belongs to another field (see WR_DIS and RD_DIS
in the common table).
efuse_block Block number. It determines where the eFuse bits will be placed for this field. Available
EFUSE_BLK0..EFUSE_BLK3.
bit_start Start bit number (0..255). The bit_start field can be omitted. In this case, it will be set to bit_start +
bit_count from the previous record, if it has the same efuse_block. Otherwise (if efuse_block is different, or
this is the first entry), an error will be generated.
bit_count The number of bits to use in this field (1..-). This parameter can not be omitted. This
field also may be MAX_BLK_LEN in this case, the field length will have the maximum block
length, taking into account the coding scheme (applicable for ESP_EFUSE_SECURE_BOOT_KEY
and ESP_EFUSE_ENCRYPT_FLASH_KEY fields). The value MAX_BLK_LEN depends on CON-
FIG_EFUSE_CODE_SCHEME_SELECTOR, will be replaced with None - 256, 3/4 - 192, REPEAT
- 128.
comment This param is using for comment field, it also move to C-header file. The comment field can be omitted.
If a non-sequential bit order is required to describe a field, then the field description in the following lines should
be continued without specifying a name, this will indicate that it belongs to one field. For example two fields
MAC_FACTORY and MAC_FACTORY_CRC:
# Factory MAC address #

#######################
MAC_FACTORY, EFUSE_BLK0, 72, 8, Factory MAC addr [0]
, EFUSE_BLK0, 64, 8, Factory MAC addr [1]
MAC_FACTORY_CRC, EFUSE_BLK0, 80, 8, CRC8 for factory MAC address
This field will available in code as ESP_EFUSE_MAC_FACTORY and ESP_EFUSE_MAC_FACTORY_CRC.
Structured efuse fields
WR_DIS, EFUSE_BLK0, 0, 32, Write protection

WR_DIS.RD_DIS, EFUSE_BLK0, 0, 1, Write protection for␣
,→RD_DIS
WR_DIS.FIELD_1, EFUSE_BLK0, 1, 1, Write protection for␣

,→FIELD_1

,→FIELD_2 (includes B1 and B2)
WR_DIS.FIELD_2.B1, EFUSE_BLK0, 2, 2, Write protection for␣

,→FIELD_2.B1
WR_DIS.FIELD_2.B2, EFUSE_BLK0, 4, 2, Write protection for␣

,→FIELD_2.B2

,→FIELD_3
WR_DIS.FIELD_3.ALIAS, EFUSE_BLK0, 5, 1, Write protection for␣

,→FIELD_3 (just a alias for WR_DIS.FIELD_3)

,→FIELD_4
The structured eFuse field looks like WR_DIS.RD_DIS where the dot points that this field belongs to the parent
field - WR_DIS and can not be out of the parent s range.
It is possible to use some levels of structured fields as WR_DIS.FIELD_2.B1 and B2. These fields should not be
crossed each other and should be in the range of two fields: WR_DIS and WR_DIS.FIELD_2.
It is possible to create aliases for fields with the same range, see WR_DIS.FIELD_3 and WR_DIS.FIELD_3.
ALIAS.

The IDF names for structured efuse fields should be unique. The efuse_table_gen tool will generate the
final names where the dot will be replaced by _. The names for using in IDF are ESP_EFUSE_WR_DIS,
ESP_EFUSE_WR_DIS_RD_DIS, ESP_EFUSE_WR_DIS_FIELD_2_B1, etc.
efuse_table_gen.py tool
The tool is designed to generate C-source files from CSV file and validate fields. First of all, the check is carried out
on the uniqueness of the names and overlaps of the field bits. If an additional custom file is used, it will be checked
with the existing common file (esp_efuse_table.csv). In case of errors, a message will be displayed and the string that
caused the error. C-source files contain structures of type esp_efuse_desc_t.
To generate a common files, use the following command idf.py efuse-common-table or:
cd $IDF_PATH/components/efuse/
./efuse_table_gen.py esp32/esp_efuse_table.csv
After generation in the folder $IDF_PATH/components/efuse/esp32 create:

• esp_efuse_table.c file.
• In include folder esp_efuse_table.c file.
To generate a custom files, use the following command idf.py efuse-custom-table or:
cd $IDF_PATH/components/efuse/
./efuse_table_gen.py esp32/esp_efuse_table.csv PROJECT_PATH/main/esp_efuse_custom_
,→table.csv
After generation in the folder PROJECT_PATH/main create:

• esp_efuse_custom_table.c file.
• In include folder esp_efuse_custom_table.c file.
To use the generated fields, you need to include two files:
#include "esp_efuse.h"
#include "esp_efuse_table.h" or "esp_efuse_custom_table.h"
Supported coding scheme
eFuse have three coding schemes:

• None (value 0).
• 3/4 (value 1).
• Repeat (value 2).
The coding scheme affects only EFUSE_BLK1, EFUSE_BLK2 and EFUSE_BLK3 blocks. EUSE_BLK0 block
always has a coding scheme None. Coding changes the number of bits that can be written into a block, the block
length is constant 256, some of these bits are used for encoding and not avaliable for the user.
When using a coding scheme, the length of the payload that can be written is limited (for more details 20.3.1.3
System Parameter coding_scheme):
• None 256 bits.
• 3/4 192 bits.
• Repeat 128 bits.
You can find out the coding scheme of your chip:
• run a espefuse.py -p PORT summary command.
• from esptool utility logs (during flashing).
• calling the function in the code esp_efuse_get_coding_scheme() for the EFUSE_BLK3 block.

eFuse tables must always comply with the coding scheme in the chip. There is an CON-
FIG_EFUSE_CODE_SCHEME_SELECTOR option to select the coding type for tables in a Kconfig. When
generating source files, if your tables do not follow the coding scheme, an error message will be displayed. Adjust
the length or offset fields. If your program was compiled with None encoding and 3/4 is used in the chip, then the
ESP_ERR_CODING error may occur when calling the eFuse API (the field is outside the block boundaries). If the
field matches the new block boundaries, then the API will work without errors.
Also, 3/4 coding scheme imposes restrictions on writing bits belonging to one coding unit. The whole block with a
length of 256 bits is divided into 4 coding units, and in each coding unit there are 6 bytes of useful data and 2 service
bytes. These 2 service bytes contain the checksum of the previous 6 data bytes.
It turns out that only one field can be written into one coding unit. Repeated rewriting in one coding unit is prohibited.
But if the record was made in advance or through a esp_efuse_write_block() function, then reading the
fields belonging to one coding unit is possible.
In case 3/4 coding scheme, the writing process is divided into the coding units and we can not use the usual mode
of writing some fields. We can prepare all the data for writing and burn it in one time. You can also use this mode
for None coding scheme but it is not necessary. It is important for 3/4 coding scheme. The batch writing
mode blocks esp_efuse_read_... operations.
After changing the coding scheme, run efuse_common_table and efuse_custom_table commands to
check the tables of the new coding scheme.
To write some fields into one block, or different blocks in one time, you need to use the batch writ-
ing mode. Firstly set this mode through esp_efuse_batch_write_begin() function then write
some fields as usual using the esp_efuse_write_... functions. At the end to burn them, call the
esp_efuse_batch_write_commit() function. It burns prepared data to the eFuse blocks and disables the
batch recording mode.
eFuse API
Access to the fields is via a pointer to the description structure. API functions have some basic operation:
• esp_efuse_read_field_blob() - returns an array of read eFuse bits.
• esp_efuse_read_field_cnt() - returns the number of bits programmed as 1 .
• esp_efuse_write_field_blob() - writes an array.
• esp_efuse_write_field_cnt() - writes a required count of bits as 1 .
• esp_efuse_get_field_size() - returns the number of bits by the field name.
• esp_efuse_read_reg() - returns value of eFuse register.
• esp_efuse_write_reg() - writes value to eFuse register.
• esp_efuse_get_coding_scheme() - returns eFuse coding scheme for blocks.
• esp_efuse_read_block() - reads key to eFuse block starting at the offset and the required size.
• esp_efuse_write_block() - writes key to eFuse block starting at the offset and the required size.
• esp_efuse_batch_write_begin() - set the batch mode of writing fields.
• esp_efuse_batch_write_commit() - writes all prepared data for batch writing mode and reset the
batch writing mode.
• esp_efuse_batch_write_cancel() - reset the batch writing mode and prepared data.
• esp_efuse_get_key_dis_read() - Returns a read protection for the key block.
• esp_efuse_set_key_dis_read() - Sets a read protection for the key block.
• esp_efuse_get_key_dis_write() - Returns a write protection for the key block.
• esp_efuse_set_key_dis_write() - Sets a write protection for the key block.
• esp_efuse_get_key_purpose() - Returns the current purpose set for an eFuse key block.
• esp_efuse_write_key() - Programs a block of key data to an eFuse block
• esp_efuse_write_keys() - Programs keys to unused eFuse blocks
• esp_efuse_find_purpose() - Finds a key block with the particular purpose set.
• esp_efuse_get_keypurpose_dis_write() - Returns a write protection of the key purpose field
for an eFuse key block (for esp32 always true).
• esp_efuse_key_block_unused() - Returns true if the key block is unused, false otherwise.
For frequently used fields, special functions are made, like this esp_efuse_get_chip_ver(),
esp_efuse_get_pkg_ver().

How to add a new field
1. Find a free bits for field. Show esp_efuse_table.csv file or run idf.py show-efuse-table or the next
command:
$ ./efuse_table_gen.py esp32/esp_efuse_table.csv --info

eFuse coding scheme: NONE
# field_name efuse_block bit_start bit_count
1 WR_DIS_FLASH_CRYPT_CNT EFUSE_BLK0 2 1
2 WR_DIS_BLK1 EFUSE_BLK0 7 1
5 RD_DIS_BLK1 EFUSE_BLK0 16 1
8 FLASH_CRYPT_CNT EFUSE_BLK0 20 7
9 MAC_FACTORY EFUSE_BLK0 32 8
15 MAC_FACTORY_CRC EFUSE_BLK0 80 8
16 CHIP_VER_DIS_APP_CPU EFUSE_BLK0 96 1
17 CHIP_VER_DIS_BT EFUSE_BLK0 97 1
18 CHIP_VER_PKG EFUSE_BLK0 105 3
19 CHIP_CPU_FREQ_LOW EFUSE_BLK0 108 1
20 CHIP_CPU_FREQ_RATED EFUSE_BLK0 109 1
21 CHIP_VER_REV1 EFUSE_BLK0 111 1
22 ADC_VREF_AND_SDIO_DREF EFUSE_BLK0 136 6
23 XPD_SDIO_REG EFUSE_BLK0 142 1
24 SDIO_TIEH EFUSE_BLK0 143 1
25 SDIO_FORCE EFUSE_BLK0 144 1
26 ENCRYPT_CONFIG EFUSE_BLK0 188 4
27 CONSOLE_DEBUG_DISABLE EFUSE_BLK0 194 1
28 ABS_DONE_0 EFUSE_BLK0 196 1
29 DISABLE_JTAG EFUSE_BLK0 198 1
30 DISABLE_DL_ENCRYPT EFUSE_BLK0 199 1
31 DISABLE_DL_DECRYPT EFUSE_BLK0 200 1
32 DISABLE_DL_CACHE EFUSE_BLK0 201 1
33 ENCRYPT_FLASH_KEY EFUSE_BLK1 0 256
34 SECURE_BOOT_KEY EFUSE_BLK2 0 256
35 MAC_CUSTOM_CRC EFUSE_BLK3 0 8
36 MAC_CUSTOM EFUSE_BLK3 8 48
37 ADC1_TP_LOW EFUSE_BLK3 96 7
38 ADC1_TP_HIGH EFUSE_BLK3 103 9
39 ADC2_TP_LOW EFUSE_BLK3 112 7
40 ADC2_TP_HIGH EFUSE_BLK3 119 9
41 SECURE_VERSION EFUSE_BLK3 128 32
42 MAC_CUSTOM_VER EFUSE_BLK3 184 8
Used bits in eFuse table:

EFUSE_BLK0
[2 2] [7 9] [16 18] [20 27] [32 87] [96 97] [105 109] [111 111] [136 144] [188␣
,→191] [194 194] [196 196] [198 201]
EFUSE_BLK1
[0 255]
EFUSE_BLK2
[0 255]


EFUSE_BLK3
[0 55] [96 159] [184 191]
Note: Not printed ranges are free for using. (bits in EFUSE_BLK0 are reserved for␣
,→Espressif)
Parsing eFuse CSV input file $IDF_PATH/components/efuse/esp32/esp_efuse_table.csv .

,→..
Verifying eFuse table...
The number of bits not included in square brackets is free (bits in EFUSE_BLK0 are reserved for Espressif). All
fields are checked for overlapping.
2. Fill a line for field: field_name, efuse_block, bit_start, bit_count, comment.
3. Run a show_efuse_table command to check eFuse table. To generate source files run
efuse_common_table or efuse_custom_table command.
Debug eFuse & Unit tests
Virtual eFuses The Kconfig option CONFIG_EFUSE_VIRTUAL will virtualize eFuse values inside the eFuse Man-
ager, so writes are emulated and no eFuse values are permanently changed. This can be useful for debugging app and
unit tests. During startup, the eFuses are copied to RAM. All eFuse operations (read and write) are performed with
RAM instead of the real eFuse registers.
In addition to the CONFIG_EFUSE_VIRTUAL option there is CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH option
that adds a feature to keep eFuses in flash memory. To use this mode the partition_table should have the efuse
partition. partition.csv: "efuse_em, data, efuse, , 0x2000,". During startup, the eFuses are copied
from flash or, in case if flash is empty, from real eFuse to RAM and then update flash. This option allows keeping
eFuses after reboots (possible to test secure_boot and flash_encryption features with this option).
espefuse.py esptool includes a useful tool for reading/writing ESP32 eFuse bits - espefuse.py.
espefuse.py -p PORT summary
Connecting........__
Detecting chip type... ESP32
espefuse.py v3.1-dev
EFUSE_NAME (Block) Description = [Meaningful␣
,→Value] [Readable/Writeable] (Hex Value)
--------------------------------------------------------------------------
,→--------------
Calibration fuses:
BLK3_PART_RESERVE (BLOCK0): BLOCK3 partially served for ADC␣
,→calibration data = True R/W (0b1)
ADC_VREF (BLOCK0): Voltage reference calibration ␣
,→ = 1114 R/W (0b00010)
ADC1_TP_LOW (BLOCK3): ADC1 150mV reading ␣
,→ = 346 R/W (0b0010001)
ADC1_TP_HIGH (BLOCK3): ADC1 850mV reading ␣
,→ = 3285 R/W (0b000000101)
ADC2_TP_LOW (BLOCK3): ADC2 150mV reading ␣
,→ = 449 R/W (0b0000111)
ADC2_TP_HIGH (BLOCK3): ADC2 850mV reading ␣
,→ = 3362 R/W (0b111110101)
Config fuses:
XPD_SDIO_FORCE (BLOCK0): Ignore MTDI pin (GPIO12) for VDD_
,→SDIO on reset = False R/W (0b0)
XPD_SDIO_REG (BLOCK0): If XPD_SDIO_FORCE, enable VDD_
,→SDIO reg on reset = False R/W (0b0) (continues on next page)


XPD_SDIO_TIEH (BLOCK0): If XPD_SDIO_FORCE & XPD_SDIO_REG␣
,→ = 1.8V R/W (0b0)
CLK8M_FREQ (BLOCK0): 8MHz clock freq override ␣
,→ = 53 R/W (0x35)
SPI_PAD_CONFIG_CLK (BLOCK0): Override SD_CLK pad (GPIO6/
,→SPICLK) = 0 R/W (0b00000)
SPI_PAD_CONFIG_Q (BLOCK0): Override SD_DATA_0 pad (GPIO7/
,→SPIQ) = 0 R/W (0b00000)
SPI_PAD_CONFIG_D (BLOCK0): Override SD_DATA_1 pad (GPIO8/
,→SPID) = 0 R/W (0b00000)
SPI_PAD_CONFIG_HD (BLOCK0): Override SD_DATA_2 pad (GPIO9/
,→SPIHD) = 0 R/W (0b00000)
SPI_PAD_CONFIG_CS0 (BLOCK0): Override SD_CMD pad (GPIO11/
,→SPICS0) = 0 R/W (0b00000)
DISABLE_SDIO_HOST (BLOCK0): Disable SDIO host ␣
,→ = False R/W (0b0)
Efuse fuses:
WR_DIS (BLOCK0): Efuse write disable mask ␣
,→ = 0 R/W (0x0000)
RD_DIS (BLOCK0): Efuse read disable mask ␣
,→ = 0 R/W (0x0)
CODING_SCHEME (BLOCK0): Efuse variable block length␣
,→scheme
= 3/4 (BLK1-3 len=192 bits) R/W (0b01)

KEY_STATUS (BLOCK0): Usage of efuse block 3␣
,→(reserved) = False R/W (0b0)
Identity fuses:
MAC (BLOCK0): Factory MAC Address
= 84:0d:8e:18:8e:44 (CRC 0xad OK) R/W
MAC_CRC (BLOCK0): CRC8 for factory MAC address ␣
,→ = 173 R/W (0xad)
CHIP_VER_REV1 (BLOCK0): Silicon Revision 1 ␣
,→ = True R/W (0b1)
CHIP_VER_REV2 (BLOCK0): Silicon Revision 2 ␣
CHIP_VERSION (BLOCK0): Reserved for future chip␣
,→versions = 2 R/W (0b10)
CHIP_PACKAGE (BLOCK0): Chip package identifier ␣
,→ = 0 R/W (0b000)
MAC_VERSION (BLOCK3): Version of the MAC field ␣
,→ = 0 R/W (0x00)
Security fuses:
FLASH_CRYPT_CNT (BLOCK0): Flash encryption mode counter ␣
,→ = 0 R/W (0b0000000)
UART_DOWNLOAD_DIS (BLOCK0): Disable UART download mode␣
,→(ESP32 rev3 only) = False R/W (0b0)
FLASH_CRYPT_CONFIG (BLOCK0): Flash encryption config (key␣
,→tweak bits) = 0 R/W (0x0)
CONSOLE_DEBUG_DISABLE (BLOCK0): Disable ROM BASIC interpreter␣
,→fallback = True R/W (0b1)
ABS_DONE_0 (BLOCK0): Secure boot V1 is enabled for␣
,→bootloader image = False R/W (0b0)
ABS_DONE_1 (BLOCK0): Secure boot V2 is enabled for␣
,→bootloader image = False R/W (0b0)
JTAG_DISABLE (BLOCK0): Disable JTAG ␣
DISABLE_DL_ENCRYPT (BLOCK0): Disable flash encryption in UART␣
,→bootloader = False R/W (0b0)


DISABLE_DL_DECRYPT (BLOCK0): Disable flash decryption in UART␣
DISABLE_DL_CACHE (BLOCK0): Disable flash cache in UART␣
BLOCK1 (BLOCK1): Flash encryption key
= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00␣
,→R/W
BLOCK2 (BLOCK2): Secure boot key

= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00␣
,→R/W
BLOCK3 (BLOCK3): Variable Block 3

= 00 00 00 00 00 00 00 00 00 00 00 00 91 02 87 fa 00 00 00 00 00 00 00 00␣
,→R/W
Flash voltage (VDD_SDIO) determined by GPIO12 on reset (High for 1.8V,␣

,→Low/NC for 3.3V).
To get a dump for all eFuse registers.
espefuse.py -p PORT dump
Connecting........_
Detecting chip type... ESP32
BLOCK0 ( ) [0 ] read_regs: 00000000 8e188e44␣
,→00ad840d 0000e000 00000235 00000000 00000005
BLOCK1 (flash_encryption) [1 ] read_regs: 00000000 00000000␣
,→00000000 00000000 00000000 00000000
BLOCK2 (secure_boot_v1 s) [2 ] read_regs: 00000000 00000000␣

,→00000000 00000000 00000000 00000000
BLOCK3 ( ) [3 ] read_regs: 00000000 00000000␣

,→00000000 fa870291 00000000 00000000
espefuse.py v3.1-dev
Header File
• components/efuse/include/esp_efuse.h
Functions
esp_err_t esp_efuse_read_field_blob(const esp_efuse_desc_t *field[], void *dst, size_t
dst_size_bits)
Reads bits from EFUSE field and writes it into an array.
The number of read bits will be limited to the minimum value from the description of the bits in field
structure or dst_size_bits required size. Use esp_efuse_get_field_size() function to determine the length
of the field.
Note Please note that reading in the batch mode does not show uncommitted changes.
Return
• ESP_OK: The operation was successfully completed.
• ESP_ERR_INVALID_ARG: Error in the passed arguments.
Parameters
• [in] field: A pointer to the structure describing the fields of efuse.
• [out] dst: A pointer to array that will contain the result of reading.
• [in] dst_size_bits: The number of bits required to read. If the requested number of bits
is greater than the field, the number will be limited to the field size.
bool esp_efuse_read_field_bit(const esp_efuse_desc_t *field[])
Read a single bit eFuse field as a boolean value.
Note The value must exist and must be a single bit wide. If there is any possibility of an error in the provided
arguments, call esp_efuse_read_field_blob() and check the returned value instead.

Note If assertions are enabled and the parameter is invalid, execution will abort
Return
• true: The field parameter is valid and the bit is set.
• false: The bit is not set, or the parameter is invalid and assertions are disabled.
Parameters
esp_err_t esp_efuse_read_field_cnt(const esp_efuse_desc_t *field[], size_t *out_cnt)
Reads bits from EFUSE field and returns number of bits programmed as 1 .
If the bits are set not sequentially, they will still be counted.
Return
Parameters
• [out] out_cnt: A pointer that will contain the number of programmed as 1 bits.
esp_err_t esp_efuse_write_field_blob(const esp_efuse_desc_t *field[], const void *src, size_t
src_size_bits)
Writes array to EFUSE field.
The number of write bits will be limited to the minimum value from the description of the bits in field
structure or src_size_bits required size. Use esp_efuse_get_field_size() function to determine the length
of the field. After the function is completed, the writing registers are cleared.
Return
• ESP_ERR_EFUSE_REPEATED_PROG: Error repeated programming of programmed bits is
strictly forbidden.
• ESP_ERR_CODING: Error range of data does not match the coding scheme.
Parameters
• [in] src: A pointer to array that contains the data for writing.
• [in] src_size_bits: The number of bits required to write.
esp_err_t esp_efuse_write_field_cnt(const esp_efuse_desc_t *field[], size_t cnt)
Writes a required count of bits as 1 to EFUSE field.
If there are no free bits in the field to set the required number of bits to 1 ,
ESP_ERR_EFUSE_CNT_IS_FULL error is returned, the field will not be partially recorded. After
the function is completed, the writing registers are cleared.
Return
• ESP_ERR_EFUSE_CNT_IS_FULL: Not all requested cnt bits is set.
Parameters
• [in] cnt: Required number of programmed as 1 bits.
esp_err_t esp_efuse_write_field_bit(const esp_efuse_desc_t *field[])
Write a single bit eFuse field to 1.
For use with eFuse fields that are a single bit. This function will write the bit to value 1 if it is not already set,
or does nothing if the bit is already set.
This is equivalent to calling esp_efuse_write_field_cnt() with the cnt parameter equal to 1, except that it will
return ESP_OK if the field is already set to 1.
Return

• ESP_OK: The operation was successfully completed, or the bit was already set to value 1.
• ESP_ERR_INVALID_ARG: Error in the passed arugments, including if the efuse field is not 1 bit
wide.
Parameters
• [in] field: Pointer to the structure describing the efuse field.
esp_err_t esp_efuse_set_write_protect(esp_efuse_block_t blk)
Sets a write protection for the whole block.
After that, it is impossible to write to this block. The write protection does not apply to block 0.
Return
• ESP_ERR_NOT_SUPPORTED: The block does not support this command.
Parameters
• [in] blk: Block number of eFuse. (EFUSE_BLK1, EFUSE_BLK2 and EFUSE_BLK3)
esp_err_t esp_efuse_set_read_protect(esp_efuse_block_t blk)
Sets a read protection for the whole block.
After that, it is impossible to read from this block. The read protection does not apply to block 0.
Return
• ESP_ERR_NOT_SUPPORTED: The block does not support this command.
Parameters
• [in] blk: Block number of eFuse. (EFUSE_BLK1, EFUSE_BLK2 and EFUSE_BLK3)
int esp_efuse_get_field_size(const esp_efuse_desc_t *field[])
Returns the number of bits used by field.
Return Returns the number of bits used by field.
Parameters
uint32_t esp_efuse_read_reg(esp_efuse_block_t blk, unsigned int num_reg)
Returns value of efuse register.
This is a thread-safe implementation. Example: EFUSE_BLK2_RDATA3_REG where (blk=2, num_reg=3)
Return Value of register
Parameters
• [in] blk: Block number of eFuse.
• [in] num_reg: The register number in the block.
esp_err_t esp_efuse_write_reg(esp_efuse_block_t blk, unsigned int num_reg, uint32_t val)
Write value to efuse register.
Apply a coding scheme if necessary. This is a thread-safe implementation. Example:
EFUSE_BLK3_WDATA0_REG where (blk=3, num_reg=0)
Return
strictly forbidden.
Parameters
• [in] num_reg: The register number in the block.
• [in] val: Value to write.

esp_efuse_coding_scheme_t esp_efuse_get_coding_scheme(esp_efuse_block_t blk)

Return efuse coding scheme for blocks.
Note: The coding scheme is applicable only to 1, 2 and 3 blocks. For 0 block, the coding scheme is always
NONE.
Return Return efuse coding scheme for blocks
Parameters
esp_err_t esp_efuse_read_block(esp_efuse_block_t blk, void *dst_key, size_t offset_in_bits, size_t
size_bits)
Read key to efuse block starting at the offset and the required size.
Return
Parameters
• [in] dst_key: A pointer to array that will contain the result of reading.
• [in] offset_in_bits: Start bit in block.
• [in] size_bits: The number of bits required to read.
esp_err_t esp_efuse_write_block(esp_efuse_block_t blk, const void *src_key, size_t offset_in_bits,
size_t size_bits)
Write key to efuse block starting at the offset and the required size.
Return
• ESP_ERR_EFUSE_REPEATED_PROG: Error repeated programming of programmed bits
Parameters
• [in] src_key: A pointer to array that contains the key for writing.
• [in] offset_in_bits: Start bit in block.
• [in] size_bits: The number of bits required to write.
uint8_t esp_efuse_get_chip_ver(void)
Returns chip version from efuse.
Return chip version
uint32_t esp_efuse_get_pkg_ver(void)
Returns chip package from efuse.
Return chip package
void esp_efuse_reset(void)
Reset efuse write registers.
Efuse write registers are written to zero, to negate any changes that have been staged here.
Note This function is not threadsafe, if calling code updates efuse values from multiple tasks then this is caller
s responsibility to serialise.
void esp_efuse_disable_basic_rom_console(void)
Disable BASIC ROM Console via efuse.
By default, if booting from flash fails the ESP32 will boot a BASIC console in ROM.
Call this function (from bootloader or app) to permanently disable the console on this chip.
esp_err_t esp_efuse_disable_rom_download_mode(void)
Disable ROM Download Mode via eFuse.

Permanently disables the ROM Download Mode feature. Once disabled, if the SoC is booted with strapping
pins set for ROM Download Mode then an error is printed instead.
Note Not all SoCs support this option. An error will be returned if called on an ESP32 with a silicon revision
lower than 3, as these revisions do not support this option.
Note If ROM Download Mode is already disabled, this function does nothing and returns success.
Return
• ESP_OK If the eFuse was successfully burned, or had already been burned.
• ESP_ERR_NOT_SUPPORTED (ESP32 only) This SoC is not capable of disabling UART down-
load mode
• ESP_ERR_INVALID_STATE (ESP32 only) This eFuse is write protected and cannot be written
esp_err_t esp_efuse_set_rom_log_scheme(esp_efuse_rom_log_scheme_t log_scheme)
Set boot ROM log scheme via eFuse.
Note By default, the boot ROM will always print to console. This API can be called to set the log scheme
only once per chip, once the value is changed from the default it can t be changed again.
Return
• ESP_OK If the eFuse was successfully burned, or had already been burned.
• ESP_ERR_NOT_SUPPORTED (ESP32 only) This SoC is not capable of setting ROM log scheme
• ESP_ERR_INVALID_STATE This eFuse is write protected or has been burned already
Parameters
• log_scheme: Supported ROM log scheme
uint32_t esp_efuse_read_secure_version(void)
Return secure_version from efuse field.
Return Secure version from efuse field
bool esp_efuse_check_secure_version(uint32_t secure_version)
Check secure_version from app and secure_version and from efuse field.
Return
• True: If version of app is equal or more then secure_version from efuse.
Parameters
• secure_version: Secure version from app.
esp_err_t esp_efuse_update_secure_version(uint32_t secure_version)
Write efuse field by secure_version value.
Update the secure_version value is available if the coding scheme is None. Note: Do not use this function in
your applications. This function is called as part of the other API.
Return
• ESP_OK: Successful.
• ESP_FAIL: secure version of app cannot be set to efuse field.
• ESP_ERR_NOT_SUPPORTED: Anti rollback is not supported with the 3/4 and Repeat coding
scheme.
Parameters
• [in] secure_version: Secure version from app.
esp_err_t esp_efuse_batch_write_begin(void)
Set the batch mode of writing fields.
This mode allows you to write the fields in the batch mode when need to burn several efuses at one time. To
enable batch mode call begin() then perform as usually the necessary operations read and write and at the end
call commit() to actually burn all written efuses. The batch mode can be used nested. The commit will be done
by the last commit() function. The number of begin() functions should be equal to the number of commit()
functions.
Note: If batch mode is enabled by the first task, at this time the second task cannot write/read efuses. The
second task will wait for the first task to complete the batch operation.

// Example of using the batch writing mode.
// set the batch writing mode

esp_efuse_batch_write_begin();
// use any writing functions as usual

esp_efuse_write_field_blob(ESP_EFUSE_...);
esp_efuse_write_field_cnt(ESP_EFUSE_...);
esp_efuse_set_write_protect(EFUSE_BLKx);
esp_efuse_write_reg(EFUSE_BLKx, ...);
esp_efuse_write_block(EFUSE_BLKx, ...);
esp_efuse_write(ESP_EFUSE_1, 3); // ESP_EFUSE_1 == 1, here we write a new␣
,→value = 3. The changes will be burn by the commit() function.
esp_efuse_read_...(ESP_EFUSE_1); // this function returns ESP_EFUSE_1 == 1␣

,→because uncommitted changes are not readable, it will be available only␣
,→after commit.
...
// esp_efuse_batch_write APIs can be called recursively.

esp_efuse_batch_write_begin();
esp_efuse_set_write_protect(EFUSE_BLKx);
esp_efuse_batch_write_commit(); // the burn will be skipped here, it will be␣
,→done in the last commit().
...
// Write all of these fields to the efuse registers

esp_efuse_batch_write_commit();
esp_efuse_read_...(ESP_EFUSE_1); // this function returns ESP_EFUSE_1 == 3.
Return
esp_err_t esp_efuse_batch_write_cancel(void)
Reset the batch mode of writing fields.
It will reset the batch writing mode and any written changes.
Return
• ESP_ERR_INVALID_STATE: Tha batch mode was not set.
esp_err_t esp_efuse_batch_write_commit(void)
Writes all prepared data for the batch mode.
Must be called to ensure changes are written to the efuse registers. After this the batch writing mode will be
reset.
Return
• ESP_ERR_INVALID_STATE: The deferred writing mode was not set.
bool esp_efuse_block_is_empty(esp_efuse_block_t block)
Checks that the given block is empty.
Return
• True: The block is empty.
• False: The block is not empty or was an error.
bool esp_efuse_get_key_dis_read(esp_efuse_block_t block)
Returns a read protection for the key block.
Return True: The key block is read protected False: The key block is readable.
Parameters
• [in] block: A key block in the range EFUSE_BLK_KEY0..EFUSE_BLK_KEY_MAX

esp_err_t esp_efuse_set_key_dis_read(esp_efuse_block_t block)

Sets a read protection for the key block.
Return
strictly forbidden.
Parameters
bool esp_efuse_get_key_dis_write(esp_efuse_block_t block)
Returns a write protection for the key block.
Return True: The key block is write protected False: The key block is writeable.
Parameters
esp_err_t esp_efuse_set_key_dis_write(esp_efuse_block_t block)
Sets a write protection for the key block.
Return
strictly forbidden.
Parameters
bool esp_efuse_key_block_unused(esp_efuse_block_t block)
Returns true if the key block is unused, false otherwise.
An unused key block is all zero content, not read or write protected, and has purpose 0
(ESP_EFUSE_KEY_PURPOSE_USER)
Return
• True if key block is unused,
• False if key block is used or the specified block index is not a key block.
Parameters
• block: key block to check.
bool esp_efuse_find_purpose(esp_efuse_purpose_t purpose, esp_efuse_block_t *block)
Find a key block with the particular purpose set.
Return
• True: If found,
• False: If not found (value at block pointer is unchanged).
Parameters
• [in] purpose: Purpose to search for.
• [out] block: Pointer in the range EFUSE_BLK_KEY0..EFUSE_BLK_KEY_MAX which will
be set to the key block if found. Can be NULL, if only need to test the key block exists.
bool esp_efuse_get_keypurpose_dis_write(esp_efuse_block_t block)
Returns a write protection of the key purpose field for an efuse key block.
Note For ESP32: no keypurpose, it returns always True.
Return True: The key purpose is write protected. False: The key purpose is writeable.
Parameters
esp_efuse_purpose_t esp_efuse_get_key_purpose(esp_efuse_block_t block)
Returns the current purpose set for an efuse key block.

Return
• Value: If Successful, it returns the value of the purpose related to the given key block.
• ESP_EFUSE_KEY_PURPOSE_MAX: Otherwise.
Parameters
esp_err_t esp_efuse_write_key(esp_efuse_block_t block, esp_efuse_purpose_t purpose, const void
*key, size_t key_size_bytes)
Program a block of key data to an efuse block.
The burn of a key, protection bits, and a purpose happens in batch mode.
Return
•
ESP_OK: Successful.
•
ESP_ERR_INVALID_ARG: Error in the passed arguments.
•
ESP_ERR_INVALID_STATE: Error in efuses state, unused block not found.
•
ESP_ERR_EFUSE_REPEATED_PROG: Error repeated programming of programmed bits is
strictly forbidden.
Parameters
• [in] block: Block to read purpose for. Must be in range EFUSE_BLK_KEY0 to
EFUSE_BLK_KEY_MAX. Key block must be unused (esp_efuse_key_block_unused).
• [in] purpose: Purpose to set for this key. Purpose must be already unset.
• [in] key: Pointer to data to write.
• [in] key_size_bytes: Bytes length of data to write.
esp_err_t esp_efuse_write_keys(const esp_efuse_purpose_t purposes[], uint8_t keys[][32], un-
signed number_of_keys)
Program keys to unused efuse blocks.
The burn of keys, protection bits, and purposes happens in batch mode.
Return
•
ESP_OK: Successful.
•
ESP_ERR_INVALID_ARG: Error in the passed arguments.
•
ESP_ERR_INVALID_STATE: Error in efuses state, unused block not found.
•
ESP_ERR_NOT_ENOUGH_UNUSED_KEY_BLOCKS: Error not enough unused key blocks
available
strictly forbidden.
Parameters
• [in] purposes: Array of purposes (purpose[number_of_keys]).
• [in] keys: Array of keys (uint8_t keys[number_of_keys][32]). Each key is 32 bytes long.
• [in] number_of_keys: The number of keys to write (up to 6 keys).
Structures
struct esp_efuse_desc_t
Type definition for an eFuse field.
Public Members
esp_efuse_block_t efuse_block : 8
Block of eFuse
uint8_t bit_start
Start bit [0..255]
uint16_t bit_count
Length of bit field [1..-]

Macros
ESP_ERR_EFUSE
Base error code for efuse api.
ESP_OK_EFUSE_CNT
OK the required number of bits is set.
ESP_ERR_EFUSE_CNT_IS_FULL
Error field is full.
ESP_ERR_EFUSE_REPEATED_PROG
Error repeated programming of programmed bits is strictly forbidden.
ESP_ERR_CODING
Error while a encoding operation.
ESP_ERR_NOT_ENOUGH_UNUSED_KEY_BLOCKS
Error not enough unused key blocks available
ESP_ERR_DAMAGED_READING
Error. Burn or reset was done during a reading operation leads to damage read data. This error is internal to
the efuse component and not returned by any public API.
Enumerations
enum esp_efuse_rom_log_scheme_t
Type definition for ROM log scheme.
Values:
ESP_EFUSE_ROM_LOG_ALWAYS_ON
Always enable ROM logging
ESP_EFUSE_ROM_LOG_ON_GPIO_LOW
ROM logging is enabled when specific GPIO level is low during start up
ESP_EFUSE_ROM_LOG_ON_GPIO_HIGH
ROM logging is enabled when specific GPIO level is high during start up
ESP_EFUSE_ROM_LOG_ALWAYS_OFF
Disable ROM logging permanently
2.7.5 Error Codes and Helper Functions
This section lists definitions of common ESP-IDF error codes and several helper functions related to error handling.
For general information about error codes in ESP-IDF, see Error Handling.
For the full list of error codes defined in ESP-IDF, see Error Code Reference.
API Reference
Header File
• components/esp_common/include/esp_err.h
Functions
const char *esp_err_to_name(esp_err_t code)
Returns string for esp_err_t error codes.
This function finds the error code in a pre-generated lookup-table and returns its string representation.
The function is generated by the Python script tools/gen_esp_err_to_name.py which should be run each time
an esp_err_t error is modified, created or removed from the IDF project.

Return string error message

Parameters
• code: esp_err_t error code
const char *esp_err_to_name_r(esp_err_t code, char *buf, size_t buflen)
Returns string for esp_err_t and system error codes.
This function finds the error code in a pre-generated lookup-table of esp_err_t errors and returns its string
representation. If the error code is not found then it is attempted to be found among system errors.
The function is generated by the Python script tools/gen_esp_err_to_name.py which should be run each time
an esp_err_t error is modified, created or removed from the IDF project.
Return buf containing the string error message
Parameters
• code: esp_err_t error code
• [out] buf: buffer where the error message should be written
• buflen: Size of buffer buf. At most buflen bytes are written into the buf buffer (including the
terminating null byte).
Macros
ESP_OK
esp_err_t value indicating success (no error)
ESP_FAIL
Generic esp_err_t code indicating failure
ESP_ERR_NO_MEM
Out of memory
ESP_ERR_INVALID_ARG
Invalid argument
ESP_ERR_INVALID_STATE
Invalid state
ESP_ERR_INVALID_SIZE
Invalid size
ESP_ERR_NOT_FOUND
Requested resource not found
ESP_ERR_NOT_SUPPORTED
Operation or feature not supported
ESP_ERR_TIMEOUT
Operation timed out
ESP_ERR_INVALID_RESPONSE
Received response was invalid
ESP_ERR_INVALID_CRC
CRC or checksum was invalid
ESP_ERR_INVALID_VERSION
Version was invalid
ESP_ERR_INVALID_MAC
MAC address was invalid
ESP_ERR_NOT_FINISHED
There are items remained to retrieve
ESP_ERR_WIFI_BASE
Starting number of WiFi error codes
ESP_ERR_MESH_BASE
Starting number of MESH error codes

ESP_ERR_FLASH_BASE
Starting number of flash error codes
ESP_ERR_HW_CRYPTO_BASE
Starting number of HW cryptography module error codes
ESP_ERROR_CHECK(x)
Macro which can be used to check the error code, and terminate the program in case the code is not ESP_OK.
Prints the error code, error location, and the failed statement to serial output.
Disabled if assertions are disabled.
ESP_ERROR_CHECK_WITHOUT_ABORT(x)
Macro which can be used to check the error code. Prints the error code, error location, and the failed statement
to serial output. In comparison with ESP_ERROR_CHECK(), this prints the same error message but isn t
terminating the program.
Type Definitions
typedef int esp_err_t
2.7.6 ESP HTTPS OTA
Overview
esp_https_ota provides simplified APIs to perform firmware upgrades over HTTPS. It s an abstraction layer
over existing OTA APIs.
Application Example
esp_err_t do_firmware_upgrade()
{
.url = CONFIG_FIRMWARE_UPGRADE_URL,
.cert_pem = (char *)server_cert_pem_start,
};
esp_err_t ret = esp_https_ota(&config);
if (ret == ESP_OK) {
esp_restart();
} else {
return ESP_FAIL;
}
return ESP_OK;
}
Partial Image Download over HTTPS
To use partial image download feature, enable partial_http_download configuration in

esp_https_ota_config_t. When this configuration is enabled, firmware image will be downloaded in
multiple HTTP requests of specified size. Maximum content length of each request can be specified by setting
max_http_request_size to required value.
This option is useful while fetching image from a service like AWS S3, where mbedTLS Rx buffer size (CON-
FIG_MBEDTLS_SSL_IN_CONTENT_LEN) can be set to lower value which is not possible without enabling this
configuration.
Default value of mbedTLS Rx buffer size is set to 16K. By using partial_http_download with max_http_request_size
of 4K, size of mbedTLS Rx buffer can be reduced to 4K. With this confiuration, memory saving of around 12K is
expected.

Signature Verification
For additional security, signature of OTA firmware images can be verified. For that, refer Secure OTA Updates Without
Secure boot
API Reference
Header File
• components/esp_https_ota/include/esp_https_ota.h
Functions
esp_err_t esp_https_ota(const esp_http_client_config_t *config)
HTTPS OTA Firmware upgrade.
This function allocates HTTPS OTA Firmware upgrade context, establishes HTTPS connection, reads image
data from HTTP stream and writes it to OTA partition and finishes HTTPS OTA Firmware upgrade operation.
This API supports URL redirection, but if CA cert of URLs differ then it should be appended to cert_pem
member of config.
Note This API handles the entire OTA operation, so if this API is being used then no other APIs from
esp_https_ota component should be called. If more information and control is needed during the
HTTPS OTA process, then one can use esp_https_ota_begin and subsequent APIs. If this API
returns successfully, esp_restart() must be called to boot from the new firmware image.
Return
• ESP_OK: OTA data updated, next reboot will use specified partition.
• ESP_FAIL: For generic failure.
• ESP_ERR_INVALID_ARG: Invalid argument
• ESP_ERR_OTA_VALIDATE_FAILED: Invalid app image
• ESP_ERR_NO_MEM: Cannot allocate memory for OTA operation.
• ESP_ERR_FLASH_OP_TIMEOUT or ESP_ERR_FLASH_OP_FAIL: Flash write failed.
• For other return codes, refer OTA documentation in esp-idf s app_update component.
Parameters
• [in] config: pointer to esp_http_client_config_t structure.
esp_err_t esp_https_ota_begin(esp_https_ota_config_t *ota_config, esp_https_ota_handle_t
*handle)
Start HTTPS OTA Firmware upgrade.
This function initializes ESP HTTPS OTA context and establishes HTTPS connection. This function must
be invoked first. If this function returns successfully, then esp_https_ota_perform should be called
to continue with the OTA process and there should be a call to esp_https_ota_finish on completion
of OTA operation or on failure in subsequent operations. This API supports URL redirection, but if CA cert
of URLs differ then it should be appended to cert_pem member of http_config, which is a part of
ota_config. In case of error, this API explicitly sets handle to NULL.
Note This API is blocking, so setting is_async member of http_config structure will result in an error.
Return
• ESP_OK: HTTPS OTA Firmware upgrade context initialised and HTTPS connection established
• ESP_FAIL: For generic failure.
• ESP_ERR_INVALID_ARG: Invalid argument (missing/incorrect config, certificate, etc.)
• For other return codes, refer documentation in app_update component and esp_http_client compo-
nent in esp-idf.
Parameters
• [in] ota_config: pointer to esp_https_ota_config_t structure
• [out] handle: pointer to an allocated data of type esp_https_ota_handle_t which will
be initialised in this function
esp_err_t esp_https_ota_perform(esp_https_ota_handle_t https_ota_handle)
Read image data from HTTP stream and write it to OTA partition.

This function reads image data from HTTP stream and writes it to OTA partition. This function must be called
only if esp_https_ota_begin() returns successfully. This function must be called in a loop since it returns after
every HTTP read operation thus giving you the flexibility to stop OTA operation midway.
Return
• ESP_ERR_HTTPS_OTA_IN_PROGRESS: OTA update is in progress, call this API again to con-
tinue.
• ESP_OK: OTA update was successful
• ESP_FAIL: OTA update failed
• For other return codes, refer OTA documentation in esp-idf s app_update component.
Parameters
• [in] https_ota_handle: pointer to esp_https_ota_handle_t structure
bool esp_https_ota_is_complete_data_received(esp_https_ota_handle_t https_ota_handle)
Checks if complete data was received or not.
Note This API can be called just before esp_https_ota_finish() to validate if the complete image was indeed
received.
Return
• false
• true
Parameters
esp_err_t esp_https_ota_finish(esp_https_ota_handle_t https_ota_handle)
Clean-up HTTPS OTA Firmware upgrade and close HTTPS connection.
This function closes the HTTP connection and frees the ESP HTTPS OTA context. This function switches the
boot partition to the OTA partition containing the new firmware image.
Note If this API returns successfully, esp_restart() must be called to boot from the new firmware image
esp_https_ota_finish should not be called after calling esp_https_ota_abort
Return
• ESP_OK: Clean-up successful
• ESP_ERR_INVALID_STATE
Parameters
esp_err_t esp_https_ota_abort(esp_https_ota_handle_t https_ota_handle)
Clean-up HTTPS OTA Firmware upgrade and close HTTPS connection.
This function closes the HTTP connection and frees the ESP HTTPS OTA context.
Note esp_https_ota_abort should not be called after calling esp_https_ota_finish
Return
• ESP_OK: Clean-up successful
• ESP_ERR_INVALID_STATE: Invalid ESP HTTPS OTA state
• ESP_FAIL: OTA not started
• ESP_ERR_NOT_FOUND: OTA handle not found
Parameters
esp_err_t esp_https_ota_get_img_desc(esp_https_ota_handle_t https_ota_handle, esp_app_desc_t
*new_app_info)
Reads app description from image header. The app description provides information like the Firmware
version of the image.

Note This API can be called only after esp_https_ota_begin() and before esp_https_ota_perform(). Calling
this API is not mandatory.
Return
• ESP_ERR_INVALID_ARG: Invalid arguments
• ESP_FAIL: Failed to read image descriptor
• ESP_OK: Successfully read image descriptor
Parameters
• [out] new_app_info: pointer to an allocated esp_app_desc_t structure
int esp_https_ota_get_image_len_read(esp_https_ota_handle_t https_ota_handle)
This function returns OTA image data read so far.
Note This API should be called only if esp_https_ota_perform() has been called atleast once or if
esp_https_ota_get_img_desc has been called before.
Return
• -1 On failure
• total bytes read so far
Parameters
int esp_https_ota_get_image_size(esp_https_ota_handle_t https_ota_handle)
This function returns OTA image total size.
Note This API should be called after esp_https_ota_begin() has been already called. This can be used to
create some sort of progress indication (in combination with esp_https_ota_get_image_len_read())
Return
• -1 On failure or chunked encoding
• total bytes of image
Parameters
Structures
struct esp_https_ota_config_t
ESP HTTPS OTA configuration.
Public Members
const esp_http_client_config_t *http_config

ESP HTTP client configuration
http_client_init_cb_t http_client_init_cb
Callback after ESP HTTP client is initialised
bool bulk_flash_erase
Erase entire flash partition during initialization. By default flash partition is erased during write operation
and in chunk of 4K sector size
bool partial_http_download
Enable Firmware image to be downloaded over multiple HTTP requests
int max_http_request_size
Maximum request size for partial HTTP download
Macros
ESP_ERR_HTTPS_OTA_BASE
ESP_ERR_HTTPS_OTA_IN_PROGRESS

Type Definitions
typedef void *esp_https_ota_handle_t
typedef esp_err_t (*http_client_init_cb_t)(esp_http_client_handle_t)
2.7.7 POSIX Threads Support
Overview
ESP-IDF is based on FreeRTOS but offers a range of POSIX-compatible APIs that allow easy porting of third party
code. This includes support for common parts of the POSIX Threads pthreads API.
POSIX Threads are implemented in ESP-IDF as wrappers around equivalent FreeRTOS features. The runtime
memory or performance overhead of using the pthreads API is quite low, but not every feature available in either
pthreads or FreeRTOS is available via the ESP-IDF pthreads support.
Pthreads can be used in ESP-IDF by including standard pthread.h header, which is included in the toolchain libc.
An additional ESP-IDF specific header, esp_pthread.h, provides additional non-POSIX APIs for using some
ESP-IDF features with pthreads.
C++ Standard Library implementations for std::thread, std::mutex, std::condition_variable,
etc. are implemented using pthreads (via GCC libstdc++). Therefore, restrictions mentioned here also apply to the
equivalent C++ standard library functionality.
RTOS Integration
Unlike many operating systems using POSIX Threads, ESP-IDF is a real-time operating system with a real-time
scheduler. This means that a thread will only stop running if a higher priority task is ready to run, the thread blocks
on an OS synchronization structure like a mutex, or the thread calls any of the functions sleep, vTaskDelay(),
or usleep.
Note: If calling a standard libc or C++ sleep function, such as usleep defined in unistd.h, then the task will
only block and yield the CPU if the sleep time is longer than one FreeRTOS tick period. If the time is shorter, the
thread will busy-wait instead of yielding to another RTOS task.
By default all POSIX Threads have the same RTOS priority, but it is possible to change this by calling a custom API.
Standard features
The following standard APIs are implemented in ESP-IDF.

Refer to standard POSIX Threads documentation, or pthread.h, for details about the standard arguments and be-
haviour of each function. Differences or limitations compared to the standard APIs are noted below.
Thread APIs
• pthread_create() - The attr argument is supported for setting stack size and detach state only. Other
attribute fields are ignored. - Unlike FreeRTOS task functions, the start_routine function is allowed to
return. A detached type thread is automatically deleted if the function returns. The default joinable
type thread will be suspended until pthread_join() is called on it.
• pthread_join()
• pthread_detach()
• pthread_exit()
• sched_yield()
• pthread_self() - An assert will fail if this function is called from a FreeRTOS task which is not a pthread.
• pthread_equal()

Thread Attributes
• pthread_attr_init()
• pthread_attr_destroy() - This function doesn t need to free any resources and instead resets the
attr structure to defaults (implementation is same as pthread_attr_init()).
• pthread_attr_getstacksize() / pthread_attr_setstacksize()
• pthread_attr_getdetachstate() / pthread_attr_setdetachstate()
Once
• pthread_once()
Static initializer constant PTHREAD_ONCE_INIT is supported.
Note: This function can be called from tasks created using either pthread or FreeRTOS APIs
Mutexes POSIX Mutexes are implemented as FreeRTOS Mutex Semaphores (normal type for fast or error
check mutexes, and Recursive type for recursive mutexes). This means that they have the same priority inheritance
behaviour as mutexes created with xSemaphoreCreateMutex().
• pthread_mutex_init()
• pthread_mutex_destroy()
• pthread_mutex_lock()
• pthread_mutex_timedlock()
• pthread_mutex_trylock()
• pthread_mutex_unlock()
• pthread_mutexattr_init()
• pthread_mutexattr_destroy()
• pthread_mutexattr_gettype() / pthread_mutexattr_settype()
Static initializer constant PTHREAD_MUTEX_INITIALIZER is supported, but the non-standard static initializer
constants for other mutex types are not supported.
Note: These functions can be called from tasks created using either pthread or FreeRTOS APIs
Condition Variables
• pthread_cond_init() - The attr argument is not implemented and is ignored.
• pthread_cond_destroy()
• pthread_cond_signal()
• pthread_cond_broadcast()
• pthread_cond_wait()
• pthread_cond_timedwait()
Static initializer constant PTHREAD_COND_INITIALIZER is supported.
• The resolution of pthread_cond_timedwait() timeouts is the RTOS tick period (see CON-
FIG_FREERTOS_HZ). Timeouts may be delayed up to one tick period after the requested timeout.
Thread-Specific Data

• pthread_key_create() - The destr_function argument is supported and will be called if a thread

function exits normally, calls pthread_exit(), or if the underlying task is deleted directly using the FreeR-
TOS function vTaskDelete().
• pthread_key_delete()
• pthread_setspecific() / pthread_getspecific()
Note: There are other options for thread local storage in ESP-IDF, including options with higher performance. See
Thread Local Storage.
Not Implemented
The pthread.h header is a standard header and includes additional APIs and features which are not implemented
in ESP-IDF. These include:
• pthread_cancel() returns ENOSYS if called.
• pthread_condattr_init() returns ENOSYS if called.
Other POSIX Threads functions (not listed here) are not implemented and will produce either a compiler or a linker
error if referenced from an ESP-IDF application. If you identify a useful API that you would like to see implemented
in ESP-IDF, please open a feature request on GitHub <https://github.com/espressif/esp-idf/issues> with the details.
ESP-IDF Extensions
The API esp_pthread_set_cfg() defined in the esp_pthreads.h header offers custom extensions to
control how subsequent calls to pthread_create() will behave. Currently the following configuration can be
set:
• Default stack size of new threads, if not specified when calling pthread_create() (overrides CON-
FIG_PTHREAD_TASK_STACK_SIZE_DEFAULT).
• RTOS priority of new threads (overrides CONFIG_PTHREAD_TASK_PRIO_DEFAULT).
• Core affinity / core pinning of new threads (overrides CONFIG_PTHREAD_TASK_CORE_DEFAULT).
• FreeRTOS task name for new threads (overrides CONFIG_PTHREAD_TASK_NAME_DEFAULT)
This configuration is scoped to the calling thread (or FreeRTOS task), meaning that esp_pthread_set_cfg()
can be called independently in different threads or tasks. If the inherit_cfg flag is set in the current configuration
then any new thread created will inherit the creator s configuration (if that thread calls pthread_create()
recursively), otherwise the new thread will have the default configuration.
Examples
• system/pthread demonstrates using the pthreads API to create threads

• cxx/pthread demonstrates using C++ Standard Library functions with threads
API Reference
Header File
• components/pthread/include/esp_pthread.h

Functions
esp_pthread_cfg_t esp_pthread_get_default_config(void)
Creates a default pthread configuration based on the values set via menuconfig.
Return A default configuration structure.
esp_err_t esp_pthread_set_cfg(const esp_pthread_cfg_t *cfg)
Configure parameters for creating pthread.
This API allows you to configure how the subsequent pthread_create() call will behave. This call can be used
to setup configuration parameters like stack size, priority, configuration inheritance etc.
If the inherit flag in the configuration structure is enabled, then the same configuration is also inherited in
the thread subtree.
Note Passing non-NULL attributes to pthread_create() will override the stack_size parameter set using this
API
Return
• ESP_OK if configuration was successfully set
• ESP_ERR_INVALID_ARG if stack_size is less than PTHREAD_STACK_MIN
Parameters
• cfg: The pthread config parameters
esp_err_t esp_pthread_get_cfg(esp_pthread_cfg_t *p)
Get current pthread creation configuration.
This will retrieve the current configuration that will be used for creating threads.
Return
• ESP_OK if the configuration was available
• ESP_ERR_NOT_FOUND if a configuration wasn t previously set
Parameters
• p: Pointer to the pthread config structure that will be updated with the currently configured param-
eters
esp_err_t esp_pthread_init(void)
Initialize pthread library.
Structures
struct esp_pthread_cfg_t
pthread configuration structure that influences pthread creation
Public Members
size_t stack_size
The stack size of the pthread.
size_t prio
The thread s priority.
bool inherit_cfg
Inherit this configuration further.
const char *thread_name
The thread name.
int pin_to_core
The core id to pin the thread to. Has the same value range as xCoreId argument of xTaskCreatePinned-
ToCore.
Macros
PTHREAD_STACK_MIN

2.7.8 Event Loop Library
Overview
The event loop library allows components to declare events to which other components can register handlers code
which will execute when those events occur. This allows loosely coupled components to attach desired behavior to
changes in state of other components without application involvement. For instance, a high level connection handling
library may subscribe to events produced by the wifi subsystem directly and act on those events. This also simplifies
event processing by serializing and deferring code execution to another context.
Using esp_event APIs
There are two objects of concern for users of this library: events and event loops.
Events are occurrences of note. For example, for WiFi, a successful connection to the access point may be an event.
Events are referenced using a two part identifier which are discussed more here. Event loops are the vehicle by which
events get posted by event sources and handled by event handler functions. These two appear prominently in the event
loop library APIs.
Using this library roughly entails the following flow:
1. A user defines a function that should run when an event is posted to a loop. This function is referred to as the
event handler. It should have the same signature as esp_event_handler_t.
2. An event loop is created using esp_event_loop_create(), which outputs a handle to the loop of type
esp_event_loop_handle_t. Event loops created using this API are referred to as user event loops.
There is, however, a special type of event loop called the default event loop which are discussed here.
3. Components register event handlers to the loop using esp_event_handler_register_with(). Han-
dlers can be registered with multiple loops, more on that here.
4. Event sources post an event to the loop using esp_event_post_to().
5. Components wanting to remove their handlers from being called can do so by unregistering from the loop using
esp_event_handler_unregister_with().
6. Event loops which are no longer needed can be deleted using esp_event_loop_delete().
In code, the flow above may look like as follows:
// 1. Define the event handler
void run_on_event(void* handler_arg, esp_event_base_t base, int32_t id, void*␣
,→event_data)
{
// Event handler logic
}
void app_main()
{
// 2. A configuration structure of type esp_event_loop_args_t is needed to␣
,→specify the properties of the loop to be
// created. A handle of type esp_event_loop_handle_t is obtained, which is␣

,→needed by the other APIs to reference the loop
// to perform their operations on.

esp_event_loop_args_t loop_args = {
.queue_size = ...,
.task_name = ...
.task_priority = ...,
.task_stack_size = ...,
.task_core_id = ...
};
esp_event_loop_handle_t loop_handle;
esp_event_loop_create(&loop_args, &loop_handle);


// 3. Register event handler defined in (1). MY_EVENT_BASE and MY_EVENT_ID␣
,→specifies a hypothetical
// event that handler run_on_event should execute on when it gets posted to␣
,→the loop.
esp_event_handler_register_with(loop_handle, MY_EVENT_BASE, MY_EVENT_ID, run_

,→on_event, ...);
...
// 4. Post events to the loop. This queues the event on the event loop. At␣
,→some point in time
// the event loop executes the event handler registered to the posted event,␣
,→in this case run_on_event.
// For simplicity sake this example calls esp_event_post_to from app_main, but␣
,→posting can be done from
// any other tasks (which is the more interesting use case).

esp_event_post_to(loop_handle, MY_EVENT_BASE, MY_EVENT_ID, ...);
...
// 5. Unregistering an unneeded handler

esp_event_handler_unregister_with(loop_handle, MY_EVENT_BASE, MY_EVENT_ID, run_
,→on_event);
...
// 6. Deleting an unneeded event loop

esp_event_loop_delete(loop_handle);
}
Declaring and defining events
As mentioned previously, events consists of two-part identifers: the event base and the event ID. The event base
identifies an independent group of events; the event ID identifies the event within that group. Think of the event base
and event ID as a person s last name and first name, respectively. A last name identifies a family, and the first name
identifies a person within that family.
The event loop library provides macros to declare and define the event base easily.
Event base declaration:
ESP_EVENT_DECLARE_BASE(EVENT_BASE)
Event base definition:
ESP_EVENT_DEFINE_BASE(EVENT_BASE)
Note: In IDF, the base identifiers for system events are uppercase and are postfixed with _EVENT. For example,
the base for wifi events is declared and defined as WIFI_EVENT, the ethernet event base ETHERNET_EVENT, and
so on. The purpose is to have event bases look like constants (although they are global variables considering the
defintions of macros ESP_EVENT_DECLARE_BASE and ESP_EVENT_DEFINE_BASE).
For event ID s, declaring them as enumerations is recommended. Once again, for visibility, these are typically
placed in public header files.
Event ID:

enum {
EVENT_ID_1,
EVENT_ID_2,
EVENT_ID_3,
...
}
Default Event Loop
The default event loop is a special type of loop used for system events (WiFi events, for example). The handle for
this loop is hidden from the user. The creation, deletion, handler registration/unregistration and posting of events is
done through a variant of the APIs for user event loops. The table below enumerates those variants, and the user
event loops equivalent.
User Event Loops Default Event Loops

esp_event_loop_create() esp_event_loop_create_default()
esp_event_loop_delete() esp_event_loop_delete_default()
esp_event_handler_register_with() esp_event_handler_register()
esp_event_handler_unregister_with() esp_event_handler_unregister()
esp_event_post_to() esp_event_post()
If you compare the signatures for both, they are mostly similar except the for the lack of loop handle specification for
the default event loop APIs.
Other than the API difference and the special designation to which system events are posted to, there is no difference
to how default event loops and user event loops behave. It is even possible for users to post their own events to the
default event loop, should the user opt to not create their own loops to save memory.
Notes on Handler Registration
It is possible to register a single handler to multiple events individually, i.e. using multiple calls to
esp_event_handler_register_with(). For those multiple calls, the specific event base and event ID
can be specified with which the handler should execute.
However, in some cases it is desirable for a handler to execute on (1) all events that get posted to a loop or (2) all events
of a particular base identifier. This is possible using the special event base identifier ESP_EVENT_ANY_BASE and
special event ID ESP_EVENT_ANY_ID. These special identifiers may be passed as the event base and event ID
arguments for esp_event_handler_register_with().
Therefore, the valid arguments to esp_event_handler_register_with() are:
1. <event base>, <event ID> - handler executes when the event with base <event base> and event ID <event ID>
gets posted to the loop
2. <event base>, ESP_EVENT_ANY_ID - handler executes when any event with base <event base> gets posted
to the loop
3. ESP_EVENT_ANY_BASE, ESP_EVENT_ANY_ID - handler executes when any event gets posted to the
loop
As an example, suppose the following handler registrations were performed:
esp_event_handler_register_with(loop_handle, MY_EVENT_BASE, MY_EVENT_ID, run_on_

,→event_1, ...);
esp_event_handler_register_with(loop_handle, MY_EVENT_BASE, ESP_EVENT_ANY_ID, run_

,→on_event_2, ...);
esp_event_handler_register_with(loop_handle, ESP_EVENT_ANY_BASE, ESP_EVENT_ANY_ID,␣

,→run_on_event_3, ...);

If the hypothetical event MY_EVENT_BASE, MY_EVENT_ID is posted, all three handlers run_on_event_1,
run_on_event_2, and run_on_event_3 would execute.
If the hypothetical event MY_EVENT_BASE, MY_OTHER_EVENT_ID is posted, only run_on_event_2 and
run_on_event_3 would execute.
If the hypothetical event MY_OTHER_EVENT_BASE, MY_OTHER_EVENT_ID is posted, only
run_on_event_3 would execute.
Handler Registration and Handler Dispatch Order The general rule is that for handlers that match a certain
posted event during dispatch, those which are registered first also gets executed first. The user can then control which
handlers get executed first by registering them before other handlers, provided that all registrations are performed
using a single task. If the user plans to take advantage of this behavior, caution must be exercised if there are multiple
tasks registering handlers. While the first registered, first executed behavior still holds true, the task which gets
executed first will also get their handlers registered first. Handlers registered one after the other by a single task
will still be dispatched in the order relative to each other, but if that task gets pre-empted in between registration by
another task which also registers handlers; then during dispatch those handlers will also get executed in between.
Event loop profiling
A configuration option CONFIG_ESP_EVENT_LOOP_PROFILING can be enabled in order to activate statistics col-

lection for all event loops created. The function esp_event_dump() can be used to output the collected statistics
to a file stream. More details on the information included in the dump can be found in the esp_event_dump()
API Reference.
Application Example
Examples on using the esp_event library can be found in system/esp_event. The examples cover event declaration,
loop creation, handler registration and unregistration and event posting.
Other examples which also adopt esp_event library:
• NMEA Parser , which will decode the statements received from GPS.
API Reference
Header File
• components/esp_event/include/esp_event.h
Functions
esp_err_t esp_event_loop_create(const esp_event_loop_args_t *event_loop_args,
esp_event_loop_handle_t *event_loop)
Create a new event loop.
Return
• ESP_OK: Success
• ESP_ERR_INVALID_ARG: event_loop_args or event_loop was NULL
• ESP_ERR_NO_MEM: Cannot allocate memory for event loops list
• ESP_FAIL: Failed to create task loop
• Others: Fail
Parameters
• [in] event_loop_args: configuration structure for the event loop to create
• [out] event_loop: handle to the created event loop
esp_err_t esp_event_loop_delete(esp_event_loop_handle_t event_loop)
Delete an existing event loop.
Return

• ESP_OK: Success
• Others: Fail
Parameters
• [in] event_loop: event loop to delete, must not be NULL
esp_err_t esp_event_loop_create_default(void)
Create default event loop.
Return
• ESP_OK: Success
• ESP_FAIL: Failed to create task loop
• Others: Fail
esp_err_t esp_event_loop_delete_default(void)
Delete the default event loop.
Return
• ESP_OK: Success
• Others: Fail
esp_err_t esp_event_loop_run(esp_event_loop_handle_t event_loop, TickType_t ticks_to_run)
Dispatch events posted to an event loop.
This function is used to dispatch events posted to a loop with no dedicated task, i.e task name was set to NULL
in event_loop_args argument during loop creation. This function includes an argument to limit the amount
of time it runs, returning control to the caller when that time expires (or some time afterwards). There is no
guarantee that a call to this function will exit at exactly the time of expiry. There is also no guarantee that
events have been dispatched during the call, as the function might have spent all of the alloted time waiting on
the event queue. Once an event has been unqueued, however, it is guaranteed to be dispatched. This guarantee
contributes to not being able to exit exactly at time of expiry as (1) blocking on internal mutexes is necessary
for dispatching the unqueued event, and (2) during dispatch of the unqueued event there is no way to control the
time occupied by handler code execution. The guaranteed time of exit is therefore the alloted time + amount
of time required to dispatch the last unqueued event.
In cases where waiting on the queue times out, ESP_OK is returned and not ESP_ERR_TIMEOUT, since it
is normal behavior.
Note encountering an unknown event that has been posted to the loop will only generate a warning, not an
error.
Return
• ESP_OK: Success
• Others: Fail
Parameters
• [in] event_loop: event loop to dispatch posted events from, must not be NULL
• [in] ticks_to_run: number of ticks to run the loop
esp_err_t esp_event_handler_register(esp_event_base_t event_base, int32_t event_id,
esp_event_handler_t event_handler, void
*event_handler_arg)
Register an event handler to the system event loop (legacy).
This function can be used to register a handler for either: (1) specific events, (2) all events of a certain event
base, or (3) all events known by the system event loop.
Note This function is obsolete and will be deprecated soon, please use esp_event_handler_instance_register()
instead.
• specific events: specify exact event_base and event_id
• all events of a certain base: specify exact event_base and use ESP_EVENT_ANY_ID as the event_id
• all events known by the loop: use ESP_EVENT_ANY_BASE for event_base and
ESP_EVENT_ANY_ID as the event_id
Registering multiple handlers to events is possible. Registering a single handler to multiple events is also
possible. However, registering the same handler to the same event multiple times would cause the previous

registrations to be overwritten.
Note the event loop library does not maintain a copy of event_handler_arg, therefore the user should ensure
that event_handler_arg still points to a valid location by the time the handler gets called
Return
• ESP_OK: Success
• ESP_ERR_NO_MEM: Cannot allocate memory for the handler
• ESP_ERR_INVALID_ARG: Invalid combination of event base and event id
• Others: Fail
Parameters
• [in] event_base: the base id of the event to register the handler for
• [in] event_id: the id of the event to register the handler for
• [in] event_handler: the handler function which gets called when the event is dispatched
• [in] event_handler_arg: data, aside from event data, that is passed to the handler when it
is called
esp_err_t esp_event_handler_register_with(esp_event_loop_handle_t event_loop,
esp_event_base_t event_base, int32_t event_id,
esp_event_handler_t event_handler, void
*event_handler_arg)
Register an event handler to a specific loop (legacy).
This function behaves in the same manner as esp_event_handler_register, except the additional specification
of the event loop to register the handler to.
Note This function is obsolete and will be deprecated soon, please use
esp_event_handler_instance_register_with() instead.
Return
• ESP_OK: Success
• Others: Fail
Parameters
• [in] event_loop: the event loop to register this handler function to, must not be NULL
is called
esp_err_t esp_event_handler_instance_register_with(esp_event_loop_handle_t
event_loop, esp_event_base_t
event_base, int32_t event_id,
esp_event_handler_t event_handler,
void *event_handler_arg,
esp_event_handler_instance_t
*instance)
Register an instance of event handler to a specific loop.
This function can be used to register a handler for either: (1) specific events, (2) all events of a certain event
base, or (3) all events known by the system event loop.
• specific events: specify exact event_base and event_id
• all events of a certain base: specify exact event_base and use ESP_EVENT_ANY_ID as the event_id
• all events known by the loop: use ESP_EVENT_ANY_BASE for event_base and
ESP_EVENT_ANY_ID as the event_id
Besides the error, the function returns an instance object as output parameter to identify each registration. This
is necessary to remove (unregister) the registration before the event loop is deleted.

Registering multiple handlers to events, registering a single handler to multiple events as well as registering the
same handler to the same event multiple times is possible. Each registration yields a distinct instance object
which identifies it over the registration lifetime.
Return
• ESP_OK: Success
• ESP_ERR_INVALID_ARG: Invalid combination of event base and event id or instance is NULL
• Others: Fail
Parameters
• [in] event_loop: the event loop to register this handler function to, must not be NULL
is called
• [out] instance: An event handler instance object related to the registered event handler and
data, can be NULL. This needs to be kept if the specific callback instance should be unregistered
before deleting the whole event loop. Registering the same event handler multiple times is possible
and yields distinct instance objects. The data can be the same for all registrations. If no unregistration
is needed but the handler should be deleted when the event loop is deleted, instance can be NULL.
esp_err_t esp_event_handler_instance_register(esp_event_base_t event_base, int32_t
event_id, esp_event_handler_t
event_handler, void *event_handler_arg,
esp_event_handler_instance_t *instance)
Register an instance of event handler to the default loop.
This function does the same as esp_event_handler_instance_register_with, except that it registers the handler
to the default event loop.
Return
• ESP_OK: Success
• ESP_ERR_INVALID_ARG: Invalid combination of event base and event id or instance is NULL
• Others: Fail
Parameters
is called
• [out] instance: An event handler instance object related to the registered event handler and
data, can be NULL. This needs to be kept if the specific callback instance should be unregistered
before deleting the whole event loop. Registering the same event handler multiple times is possible
and yields distinct instance objects. The data can be the same for all registrations. If no unregistration
is needed but the handler should be deleted when the event loop is deleted, instance can be NULL.
esp_err_t esp_event_handler_unregister(esp_event_base_t event_base, int32_t event_id,
esp_event_handler_t event_handler)
Unregister a handler with the system event loop (legacy).
Unregisters a handler so it will no longer be called during dispatch. Handlers can be unregistered for any com-
bination of event_base and event_id which were previously registered. To unregister a handler, the event_base
and event_id arguments must match exactly the arguments passed to esp_event_handler_register() when that
handler was registered. Passing ESP_EVENT_ANY_BASE and/or ESP_EVENT_ANY_ID will only unreg-
ister handlers that were registered with the same wildcard arguments.

esp_event_handler_instance_unregister() instead.
Note When using ESP_EVENT_ANY_ID, handlers registered to specific event IDs using the same base will
not be unregistered. When using ESP_EVENT_ANY_BASE, events registered to specific bases will
also not be unregistered. This avoids accidental unregistration of handlers registered by other users or
components.
Return ESP_OK success
Return ESP_ERR_INVALID_ARG invalid combination of event base and event id
Return others fail
Parameters
• [in] event_base: the base of the event with which to unregister the handler
• [in] event_id: the id of the event with which to unregister the handler
• [in] event_handler: the handler to unregister
esp_err_t esp_event_handler_unregister_with(esp_event_loop_handle_t event_loop,
esp_event_base_t event_base, int32_t event_id,
esp_event_handler_t event_handler)
Unregister a handler from a specific event loop (legacy).
This function behaves in the same manner as esp_event_handler_unregister, except the additional specification
of the event loop to unregister the handler with.
esp_event_handler_instance_unregister_with() instead.
Return
• ESP_OK: Success
• Others: Fail
Parameters
• [in] event_loop: the event loop with which to unregister this handler function, must not be
NULL
• [in] event_handler: the handler to unregister
esp_err_t esp_event_handler_instance_unregister_with(esp_event_loop_handle_t
event_loop, esp_event_base_t
event_base, int32_t event_id,
esp_event_handler_instance_t
instance)
Unregister a handler instance from a specific event loop.
Unregisters a handler instance so it will no longer be called during dispatch. Handler instances can
be unregistered for any combination of event_base and event_id which were previously registered. To
unregister a handler instance, the event_base and event_id arguments must match exactly the argu-
ments passed to esp_event_handler_instance_register() when that handler instance was registered. Passing
ESP_EVENT_ANY_BASE and/or ESP_EVENT_ANY_ID will only unregister handler instances that were
registered with the same wildcard arguments.
Note When using ESP_EVENT_ANY_ID, handlers registered to specific event IDs using the same base will
not be unregistered. When using ESP_EVENT_ANY_BASE, events registered to specific bases will
also not be unregistered. This avoids accidental unregistration of handlers registered by other users or
components.
Return
• ESP_OK: Success
• Others: Fail
Parameters
• [in] event_loop: the event loop with which to unregister this handler function, must not be
NULL

• [in] instance: the instance object of the registration to be unregistered
esp_err_t esp_event_handler_instance_unregister(esp_event_base_t event_base, int32_t
event_id, esp_event_handler_instance_t
instance)
Unregister a handler from the system event loop.
This function does the same as esp_event_handler_instance_unregister_with, except that it unregisters the
handler instance from the default event loop.
Return
• ESP_OK: Success
• Others: Fail
Parameters
• [in] instance: the instance object of the registration to be unregistered
esp_err_t esp_event_post(esp_event_base_t event_base, int32_t event_id, void *event_data, size_t
event_data_size, TickType_t ticks_to_wait)
Posts an event to the system default event loop. The event loop library keeps a copy of event_data and manages
the copy s lifetime automatically (allocation + deletion); this ensures that the data the handler recieves is
always valid.
Return
• ESP_OK: Success
• ESP_ERR_TIMEOUT: Time to wait for event queue to unblock expired, queue full when posting
from ISR
• Others: Fail
Parameters
• [in] event_base: the event base that identifies the event
• [in] event_id: the event id that identifies the event
• [in] event_data: the data, specific to the event occurence, that gets passed to the handler
• [in] event_data_size: the size of the event data
• [in] ticks_to_wait: number of ticks to block on a full event queue
esp_err_t esp_event_post_to(esp_event_loop_handle_t event_loop, esp_event_base_t event_base,
int32_t event_id, void *event_data, size_t event_data_size, TickType_t
ticks_to_wait)
Posts an event to the specified event loop. The event loop library keeps a copy of event_data and manages the
copy s lifetime automatically (allocation + deletion); this ensures that the data the handler recieves is always
valid.
This function behaves in the same manner as esp_event_post_to, except the additional specification of the event
loop to post the event to.
Return
• ESP_OK: Success
• ESP_ERR_TIMEOUT: Time to wait for event queue to unblock expired, queue full when posting
from ISR
• Others: Fail
Parameters
• [in] event_loop: the event loop to post to, must not be NULL

esp_err_t esp_event_isr_post(esp_event_base_t event_base, int32_t event_id, void *event_data, size_t

event_data_size, BaseType_t *task_unblocked)
Special variant of esp_event_post for posting events from interrupt handlers.
Note this function is only available when CONFIG_ESP_EVENT_POST_FROM_ISR is enabled
Note when this function is called from an interrupt handler placed in IRAM, this function should be placed in
IRAM as well by enabling CONFIG_ESP_EVENT_POST_FROM_IRAM_ISR
Return
• ESP_OK: Success
• ESP_FAIL: Event queue for the default event loop full
• ESP_ERR_INVALID_ARG: Invalid combination of event base and event id, data size of more than
4 bytes
• Others: Fail
Parameters
• [in] event_data_size: the size of the event data; max is 4 bytes
• [out] task_unblocked: an optional parameter (can be NULL) which indicates that an event
task with higher priority than currently running task has been unblocked by the posted event; a
context switch should be requested before the interrupt is existed.
esp_err_t esp_event_isr_post_to(esp_event_loop_handle_t event_loop, esp_event_base_t
event_base, int32_t event_id, void *event_data, size_t
event_data_size, BaseType_t *task_unblocked)
Special variant of esp_event_post_to for posting events from interrupt handlers.
Note this function is only available when CONFIG_ESP_EVENT_POST_FROM_ISR is enabled
Note when this function is called from an interrupt handler placed in IRAM, this function should be placed in
IRAM as well by enabling CONFIG_ESP_EVENT_POST_FROM_IRAM_ISR
Return
• ESP_OK: Success
• ESP_FAIL: Event queue for the loop full
• ESP_ERR_INVALID_ARG: Invalid combination of event base and event id, data size of more than
4 bytes
• Others: Fail
Parameters
• [in] event_loop: the event loop to post to, must not be NULL
• [out] task_unblocked: an optional parameter (can be NULL) which indicates that an event
task with higher priority than currently running task has been unblocked by the posted event; a
context switch should be requested before the interrupt is existed.
esp_err_t esp_event_dump(FILE *file)
Dumps statistics of all event loops.
Dumps event loop info in the format:
event loop
handler
handler
...
event loop
handler
handler
...
where:

event loop
format: address,name rx:total_recieved dr:total_dropped
where:
address - memory address of the event loop
name - name of the event loop, 'none' if no dedicated task
total_recieved - number of successfully posted events
total_dropped - number of events unsuccessfully posted due to queue␣
,→being full
handler
format: address ev:base,id inv:total_invoked run:total_runtime
where:
address - address of the handler function
base,id - the event specified by event base and id this handler␣
,→executes
total_invoked - number of times this handler has been invoked

total_runtime - total amount of time used for invoking this handler
Note this function is a noop when CONFIG_ESP_EVENT_LOOP_PROFILING is disabled

Return
• ESP_OK: Success
• Others: Fail
Parameters
• [in] file: the file stream to output to
Structures
struct esp_event_loop_args_t
Configuration for creating event loops.
Public Members
int32_t queue_size
size of the event loop queue
const char *task_name
name of the event loop task; if NULL, a dedicated task is not created for event loop
UBaseType_t task_priority
priority of the event loop task, ignored if task name is NULL
stack size of the event loop task, ignored if task name is NULL
BaseType_t task_core_id
core to which the event loop task is pinned to, ignored if task name is NULL
Header File
• components/esp_event/include/esp_event_base.h
Macros
ESP_EVENT_DECLARE_BASE(id)
ESP_EVENT_DEFINE_BASE(id)
ESP_EVENT_ANY_BASE
register handler for any event base

ESP_EVENT_ANY_ID
register handler for any event id
Type Definitions
typedef const char *esp_event_base_t
unique pointer to a subsystem that exposes events
typedef void *esp_event_loop_handle_t
a number that identifies an event with respect to a base
typedef void (*esp_event_handler_t)(void *event_handler_arg, esp_event_base_t event_base,
function called when an event is posted to the queue
typedef void *esp_event_handler_instance_t
context identifying an instance of a registered event handler
Related Documents
Legacy event loop
API Reference
Header File
• components/esp_event/include/esp_event_legacy.h
Functions
esp_err_t esp_event_send(system_event_t *event)
Send a event to event task.
Other task/modules, such as the tcpip_adapter, can call this API to send an event to event task
Note This API is part of the legacy event system. New code should use event library API in esp_event.h
Return ESP_OK : succeed
Return others : fail
Parameters
• event: Event to send
esp_err_t esp_event_send_internal(esp_event_base_t event_base, int32_t event_id, void
*event_data, size_t event_data_size, TickType_t
ticks_to_wait)
Send a event to event task.
Other task/modules, such as the tcpip_adapter, can call this API to send an event to event task
Note This API is used by WiFi Driver only.
Return ESP_OK : succeed
Return others : fail
Parameters
esp_err_t esp_event_process_default(system_event_t *event)
Default event handler for system events.
This function performs default handling of system events. When using esp_event_loop APIs, it is called auto-
matically before invoking the user-provided callback function.

Applications which implement a custom event loop must call this function as part of event processing.
Return ESP_OK if an event was handled successfully
Parameters
• event: pointer to event to be handled
void esp_event_set_default_eth_handlers(void)
Install default event handlers for Ethernet interface.
void esp_event_set_default_wifi_handlers(void)
Install default event handlers for Wi-Fi interfaces (station and AP)
esp_err_t esp_event_loop_init(system_event_cb_t cb, void *ctx)
Initialize event loop.
Create the event handler and task
Return
• ESP_OK: succeed
• others: fail
Parameters
• cb: application specified event callback, it can be modified by call esp_event_set_cb
• ctx: reserved for user
system_event_cb_t esp_event_loop_set_cb(system_event_cb_t cb, void *ctx)
Set application specified event callback function.
Attention 1. If cb is NULL, means application don t need to handle If cb is not NULL, it will be call when
an event is received, after the default event callback is completed
Return old callback
Parameters
• cb: application callback function
• ctx: argument to be passed to callback
Unions
union system_event_info_t
#include <esp_event_legacy.h> Union of all possible system_event argument structures
Public Members
system_event_sta_connected_t connected
system_event_sta_disconnected_t disconnected
ESP32 station disconnected to AP
system_event_sta_scan_done_t scan_done
ESP32 station scan (APs) done
system_event_sta_authmode_change_t auth_change
the auth mode of AP ESP32 station connected to changed
system_event_sta_got_ip_t got_ip
ESP32 station got IP, first time got IP or when IP is changed

system_event_sta_wps_er_pin_t sta_er_pin
ESP32 station WPS enrollee mode PIN code received
system_event_sta_wps_fail_reason_t sta_er_fail_reason
ESP32 station WPS enrollee mode failed reason code received
system_event_sta_wps_er_success_t sta_er_success
ESP32 station WPS enrollee success
system_event_ap_staconnected_t sta_connected
system_event_ap_stadisconnected_t sta_disconnected
a station disconnected to ESP32 soft-AP
system_event_ap_probe_req_rx_t ap_probereqrecved
ESP32 soft-AP receive probe request packet
system_event_ftm_report_t ftm_report
Report of FTM procedure
system_event_ap_staipassigned_t ap_staipassigned
ESP32 soft-AP assign an IP to the station
system_event_got_ip6_t got_ip6
ESP32 station or ap or ethernet ipv6 addr state change to preferred
Structures
struct system_event_t
Event, as a tagged enum
Public Members
system_event_id_t event_id
event ID
system_event_info_t event_info
event information
Macros
SYSTEM_EVENT_AP_STA_GOT_IP6
Type Definitions
typedef wifi_event_sta_wps_fail_reason_t system_event_sta_wps_fail_reason_t
Argument structure of SYSTEM_EVENT_STA_WPS_ER_FAILED event
typedef wifi_event_sta_scan_done_t system_event_sta_scan_done_t
Argument structure of SYSTEM_EVENT_SCAN_DONE event
typedef wifi_event_sta_connected_t system_event_sta_connected_t
Argument structure of SYSTEM_EVENT_STA_CONNECTED event
typedef wifi_event_sta_disconnected_t system_event_sta_disconnected_t
Argument structure of SYSTEM_EVENT_STA_DISCONNECTED event
typedef wifi_event_sta_authmode_change_t system_event_sta_authmode_change_t
Argument structure of SYSTEM_EVENT_STA_AUTHMODE_CHANGE event
typedef wifi_event_sta_wps_er_pin_t system_event_sta_wps_er_pin_t
Argument structure of SYSTEM_EVENT_STA_WPS_ER_PIN event
typedef wifi_event_sta_wps_er_success_t system_event_sta_wps_er_success_t
Argument structure of SYSTEM_EVENT_STA_WPS_ER_PIN event

typedef wifi_event_ap_staconnected_t system_event_ap_staconnected_t

Argument structure of event
typedef wifi_event_ap_stadisconnected_t system_event_ap_stadisconnected_t
typedef wifi_event_ap_probe_req_rx_t system_event_ap_probe_req_rx_t
typedef wifi_event_ftm_report_t system_event_ftm_report_t
Argument structure of SYSTEM_EVENT_FTM_REPORT event
typedef ip_event_ap_staipassigned_t system_event_ap_staipassigned_t
typedef ip_event_got_ip_t system_event_sta_got_ip_t
typedef ip_event_got_ip6_t system_event_got_ip6_t
typedef esp_err_t (*system_event_handler_t)(esp_event_base_t event_base, int32_t event_id,
void *event_data, size_t event_data_size, Tick-
Event handler function type
typedef esp_err_t (*system_event_cb_t)(void *ctx, system_event_t *event)
Application specified event callback function.
Return
• ESP_OK: succeed
• others: fail
Parameters
• ctx: reserved for user
• event: event type defined in this file
Enumerations
enum system_event_id_t
System event types enumeration
Values:
SYSTEM_EVENT_WIFI_READY = 0
ESP32 WiFi ready
SYSTEM_EVENT_SCAN_DONE
ESP32 finish scanning AP
SYSTEM_EVENT_STA_START
ESP32 station start
SYSTEM_EVENT_STA_STOP
ESP32 station stop
SYSTEM_EVENT_STA_CONNECTED
SYSTEM_EVENT_STA_DISCONNECTED
ESP32 station disconnected from AP
SYSTEM_EVENT_STA_AUTHMODE_CHANGE
the auth mode of AP connected by ESP32 station changed
SYSTEM_EVENT_STA_GOT_IP
ESP32 station got IP from connected AP

SYSTEM_EVENT_STA_LOST_IP
ESP32 station lost IP and the IP is reset to 0
SYSTEM_EVENT_STA_BSS_RSSI_LOW
ESP32 station connected BSS rssi goes below threshold
SYSTEM_EVENT_STA_WPS_ER_SUCCESS
ESP32 station wps succeeds in enrollee mode
SYSTEM_EVENT_STA_WPS_ER_FAILED
ESP32 station wps fails in enrollee mode
SYSTEM_EVENT_STA_WPS_ER_TIMEOUT
ESP32 station wps timeout in enrollee mode
SYSTEM_EVENT_STA_WPS_ER_PIN
ESP32 station wps pin code in enrollee mode
SYSTEM_EVENT_STA_WPS_ER_PBC_OVERLAP
ESP32 station wps overlap in enrollee mode
SYSTEM_EVENT_AP_START
ESP32 soft-AP start
SYSTEM_EVENT_AP_STOP
ESP32 soft-AP stop
SYSTEM_EVENT_AP_STACONNECTED
SYSTEM_EVENT_AP_STADISCONNECTED
a station disconnected from ESP32 soft-AP
SYSTEM_EVENT_AP_STAIPASSIGNED
ESP32 soft-AP assign an IP to a connected station
SYSTEM_EVENT_AP_PROBEREQRECVED
Receive probe request packet in soft-AP interface
SYSTEM_EVENT_ACTION_TX_STATUS
Receive status of Action frame transmitted
SYSTEM_EVENT_ROC_DONE
Indicates the completion of Remain-on-Channel operation status
SYSTEM_EVENT_STA_BEACON_TIMEOUT
ESP32 station beacon timeout
SYSTEM_EVENT_FTM_REPORT
Receive report of FTM procedure
SYSTEM_EVENT_GOT_IP6
ESP32 station or ap or ethernet interface v6IP addr is preferred
SYSTEM_EVENT_ETH_START
ESP32 ethernet start
SYSTEM_EVENT_ETH_STOP
ESP32 ethernet stop
SYSTEM_EVENT_ETH_CONNECTED
ESP32 ethernet phy link up
SYSTEM_EVENT_ETH_DISCONNECTED
ESP32 ethernet phy link down
SYSTEM_EVENT_ETH_GOT_IP
ESP32 ethernet got IP from connected AP

SYSTEM_EVENT_ETH_LOST_IP
ESP32 ethernet lost IP and the IP is reset to 0
SYSTEM_EVENT_MAX
Number of members in this enum
2.7.9 FreeRTOS
Overview
This section contains documentation of FreeRTOS types, functions, and macros. It is automatically generated from
FreeRTOS header files.
Note: ESP-IDF FreeRTOS is based on the Xtensa port of FreeRTOS v10.2.0,
For more information about FreeRTOS features specific to ESP-IDF, see ESP-IDF FreeRTOS SMP Changes and
ESP-IDF FreeRTOS Additions.
Task API
Header File
• components/freertos/FreeRTOS-Kernel/include/freertos/task.h
Functions
BaseType_t xTaskCreatePinnedToCore(TaskFunction_t pvTaskCode, const char *const pc-
Name, const uint32_t usStackDepth, void *const pvPa-
rameters, UBaseType_t uxPriority, TaskHandle_t *const
pvCreatedTask, const BaseType_t xCoreID)
Create a new task with a specified affinity.
This function is similar to xTaskCreate, but allows setting task affinity in SMP system.
Return pdPASS if the task was successfully created and added to a ready list, otherwise an error code defined
in the file projdefs.h
Parameters
• pvTaskCode: Pointer to the task entry function. Tasks must be implemented to never return (i.e.
continuous loop), or should be terminated using vTaskDelete function.
• pcName: A descriptive name for the task. This is mainly used to facilitate debugging. Max length
defined by configMAX_TASK_NAME_LEN - default is 16.
• usStackDepth: The size of the task stack specified as the number of bytes. Note that this differs
from vanilla FreeRTOS.
• pvParameters: Pointer that will be used as the parameter for the task being created.
• uxPriority: The priority at which the task should run. Systems that include MPU support can
optionally create tasks in a privileged (system) mode by setting bit portPRIVILEGE_BIT of the
priority parameter. For example, to create a privileged task at priority 2 the uxPriority parameter
should be set to ( 2 | portPRIVILEGE_BIT ).
• pvCreatedTask: Used to pass back a handle by which the created task can be referenced.
• xCoreID: If the value is tskNO_AFFINITY, the created task is not pinned to any CPU, and the
scheduler can run it on any core available. Values 0 or 1 indicate the index number of the CPU
which the task should be pinned to. Specifying values larger than (portNUM_PROCESSORS - 1)
will cause the function to fail.
static BaseType_t xTaskCreate(TaskFunction_t pvTaskCode, const char *const pcName, const
uint32_t usStackDepth, void *const pvParameters, UBaseType_t
uxPriority, TaskHandle_t *const pxCreatedTask)
Create a new task and add it to the list of tasks that are ready to run.

Internally, within the FreeRTOS implementation, tasks use two blocks of memory. The first block is used to
hold the task s data structures. The second block is used by the task as its stack. If a task is created using
xTaskCreate() then both blocks of memory are automatically dynamically allocated inside the xTaskCreate()
function. (see https://www.FreeRTOS.org/a00111.html). If a task is created using xTaskCreateStatic() then
the application writer must provide the required memory. xTaskCreateStatic() therefore allows a task to be
created without using any dynamic memory allocation.
See xTaskCreateStatic() for a version that does not use any dynamic memory allocation.
xTaskCreate() can only be used to create a task that has unrestricted access to the entire microcontroller
memory map. Systems that include MPU support can alternatively create an MPU constrained task using
xTaskCreateRestricted().
Example usage:
// Task to be created.
void vTaskCode( void * pvParameters )
{
for( ;; )
{
// Task code goes here.
}
}
// Function that creates a task.

void vOtherFunction( void )
{
static uint8_t ucParameterToPass;
TaskHandle_t xHandle = NULL;
// Create the task, storing the handle. Note that the passed parameter␣
,→ucParameterToPass
// must exist for the lifetime of the task, so in this case is declared␣
,→static. If it was just an
// an automatic stack variable it might no longer exist, or at least have␣
,→been corrupted, by the time
// the new task attempts to access it.

xTaskCreate( vTaskCode, "NAME", STACK_SIZE, &ucParameterToPass, tskIDLE_
,→PRIORITY, &xHandle );
configASSERT( xHandle );
// Use the handle to delete the task.

if( xHandle != NULL )
{
vTaskDelete( xHandle );
}
}
Return pdPASS if the task was successfully created and added to a ready list, otherwise an error code defined
Note If program uses thread local variables (ones specified with __thread keyword) then storage for them
will be allocated on the task s stack.
Parameters
• pcName: A descriptive name for the task. This is mainly used to facilitate debugging. Max length
defined by configMAX_TASK_NAME_LEN - default is 16.
• usStackDepth: The size of the task stack specified as the number of bytes. Note that this differs
• uxPriority: The priority at which the task should run. Systems that include MPU support can
optionally create tasks in a privileged (system) mode by setting bit portPRIVILEGE_BIT of the

priority parameter. For example, to create a privileged task at priority 2 the uxPriority parameter
should be set to ( 2 | portPRIVILEGE_BIT ).
• pvCreatedTask: Used to pass back a handle by which the created task can be referenced.
TaskHandle_t xTaskCreateStaticPinnedToCore(TaskFunction_t pvTaskCode, const char
*const pcName, const uint32_t ulStack-
Depth, void *const pvParameters, UBase-
Type_t uxPriority, StackType_t *const pxS-
tackBuffer, StaticTask_t *const pxTaskBuffer,
const BaseType_t xCoreID)
Create a new task with a specified affinity.
This function is similar to xTaskCreateStatic, but allows specifying task affinity in an SMP system.
Return If neither pxStackBuffer or pxTaskBuffer are NULL, then the task will be created and pdPASS is
returned. If either pxStackBuffer or pxTaskBuffer are NULL then the task will not be created and er-
rCOULD_NOT_ALLOCATE_REQUIRED_MEMORY is returned.
Parameters
• pcName: A descriptive name for the task. This is mainly used to facilitate debugging. The maxi-
mum length of the string is defined by configMAX_TASK_NAME_LEN in FreeRTOSConfig.h.
• ulStackDepth: The size of the task stack specified as the number of bytes. Note that this differs
• uxPriority: The priority at which the task will run.
• pxStackBuffer: Must point to a StackType_t array that has at least ulStackDepth indexes -
the array will then be used as the task s stack, removing the need for the stack to be allocated
dynamically.
• pxTaskBuffer: Must point to a variable of type StaticTask_t, which will then be used to hold
the task s data structures, removing the need for the memory to be allocated dynamically.
• xCoreID: If the value is tskNO_AFFINITY, the created task is not pinned to any CPU, and the
scheduler can run it on any core available. Values 0 or 1 indicate the index number of the CPU
which the task should be pinned to. Specifying values larger than (portNUM_PROCESSORS - 1)
will cause the function to fail.
static TaskHandle_t xTaskCreateStatic(TaskFunction_t pvTaskCode, const char *const pc-
Name, const uint32_t ulStackDepth, void *const
pvParameters, UBaseType_t uxPriority, StackType_t
*const puxStackBuffer, StaticTask_t *const px-
TaskBuffer)
Create a new task and add it to the list of tasks that are ready to run.
xTaskCreate() then both blocks of memory are automatically dynamically allocated inside the xTaskCreate()
function. (see http://www.freertos.org/a00111.html). If a task is created using xTaskCreateStatic() then the
application writer must provide the required memory. xTaskCreateStatic() therefore allows a task to be created
without using any dynamic memory allocation.
Example usage:
// Dimensions the buffer that the task being created will use as its stack.
// NOTE: This is the number of bytes the stack will hold, not the number of
// words as found in vanilla FreeRTOS.
#define STACK_SIZE 200
// Structure that will hold the TCB of the task being created.
StaticTask_t xTaskBuffer;
// Buffer that the task being created will use as its stack. Note this is
// an array of StackType_t variables. The size of StackType_t is dependent on


// the RTOS port.
StackType_t xStack[ STACK_SIZE ];
// Function that implements the task being created.

{
// The parameter value is expected to be 1 as 1 is passed in the
// pvParameters value in the call to xTaskCreateStatic().
configASSERT( ( uint32_t ) pvParameters == 1UL );
for( ;; )
{
}
}
// Function that creates a task.

{
TaskHandle_t xHandle = NULL;
// Create the task without using any dynamic memory allocation.

xHandle = xTaskCreateStatic(
vTaskCode, // Function that implements the task.
"NAME", // Text name for the task.
STACK_SIZE, // Stack size in bytes, not words.
( void * ) 1, // Parameter passed into the task.
tskIDLE_PRIORITY,// Priority at which the task is created.
xStack, // Array to use as the task's stack.
&xTaskBuffer ); // Variable to hold the task's data␣
,→structure.
// puxStackBuffer and pxTaskBuffer were not NULL, so the task will have
// been created, and xHandle will be the task's handle. Use the handle
// to suspend the task.
vTaskSuspend( xHandle );
}
Return If neither pxStackBuffer or pxTaskBuffer are NULL, then the task will be created and pdPASS is
returned. If either pxStackBuffer or pxTaskBuffer are NULL then the task will not be created and er-
rCOULD_NOT_ALLOCATE_REQUIRED_MEMORY is returned.
Note If program uses thread local variables (ones specified with __thread keyword) then storage for them
will be allocated on the task s stack.
Parameters
• pcName: A descriptive name for the task. This is mainly used to facilitate debugging. The maxi-
mum length of the string is defined by configMAX_TASK_NAME_LEN in FreeRTOSConfig.h.
• ulStackDepth: The size of the task stack specified as the number of bytes. Note that this differs
• uxPriority: The priority at which the task will run.
• pxStackBuffer: Must point to a StackType_t array that has at least ulStackDepth indexes -
the array will then be used as the task s stack, removing the need for the stack to be allocated
dynamically.
• pxTaskBuffer: Must point to a variable of type StaticTask_t, which will then be used to hold
the task s data structures, removing the need for the memory to be allocated dynamically.
void vTaskAllocateMPURegions(TaskHandle_t xTask, const MemoryRegion_t *const pxRe-
gions)
Only available when configSUPPORT_DYNAMIC_ALLOCATION is set to 1.

xTaskCreateRestricted() should only be used in systems that include an MPU implementation.

Create a new task and add it to the list of tasks that are ready to run. The function parameters define the
memory regions and associated access permissions allocated to the task.
See xTaskCreateRestrictedStatic() for a version that does not use any dynamic memory allocation.
return pdPASS if the task was successfully created and added to a ready list, otherwise an error code defined
Parameters
• pxTaskDefinition: Pointer to a structure that contains a member for each of the normal
xTaskCreate() parameters (see the xTaskCreate() API documentation) plus an optional stack buffer
and the memory region definitions.
• pxCreatedTask: Used to pass back a handle by which the created task can be referenced.
Example usage:
// Create an TaskParameters_t structure that defines the task to be created.

static const TaskParameters_t xCheckTaskParameters =
{
vATask, // pvTaskCode - the function that implements the task.
"ATask", // pcName - just a text name for the task to assist debugging.
100, // usStackDepth - the stack size DEFINED IN WORDS.
NULL, // pvParameters - passed into the task function as the function␣
,→parameters.
( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the␣

,→portPRIVILEGE_BIT if the task should run in a privileged state.
cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack.
// xRegions - Allocate up to three separate memory regions for access by

// the task, with appropriate access permissions. Different processors have
// different memory alignment requirements - refer to the FreeRTOS␣
,→documentation
// for full information.

{
// Base address Length Parameters
{ cReadWriteArray, 32, portMPU_REGION_READ_WRITE },
{ cReadOnlyArray, 32, portMPU_REGION_READ_ONLY },
{ cPrivilegedOnlyAccessArray, 128, portMPU_REGION_PRIVILEGED_READ_
,→WRITE }
}
};
int main( void )

{
TaskHandle_t xHandle;
// Create a task from the const structure defined above. The task handle
// is requested (the second parameter is not NULL) but in this case just for
// demonstration purposes as its not actually used.
xTaskCreateRestricted( &xRegTest1Parameters, &xHandle );
// Start the scheduler.

vTaskStartScheduler();
// Will only get here if there was insufficient memory to create the idle
// and/or timer task.
for( ;; );
}
Only available when configSUPPORT_STATIC_ALLOCATION is set to 1.

xTaskCreateRestrictedStatic() should only be used in systems that include an MPU implementation.

xTaskCreateRestricted() then the stack is provided by the application writer, and the memory used to hold the
task s data structure is automatically dynamically allocated inside the xTaskCreateRestricted() function. If a
task is created using xTaskCreateRestrictedStatic() then the application writer must provide the memory used
to hold the task s data structures too. xTaskCreateRestrictedStatic() therefore allows a memory protected
task to be created without using any dynamic memory allocation.
return pdPASS if the task was successfully created and added to a ready list, otherwise an error code defined
Parameters
• pxTaskDefinition: Pointer to a structure that contains a member for each of the normal
xTaskCreate() parameters (see the xTaskCreate() API documentation) plus an optional stack buffer
and the memory region definitions. If configSUPPORT_STATIC_ALLOCATION is set to 1 the
structure contains an additional member, which is used to point to a variable of type StaticTask_t -
which is then used to hold the task s data structure.
• pxCreatedTask: Used to pass back a handle by which the created task can be referenced.
Example usage:
// Create an TaskParameters_t structure that defines the task to be created.

// The StaticTask_t variable is only included in the structure when
// configSUPPORT_STATIC_ALLOCATION is set to 1. The PRIVILEGED_DATA macro can
// be used to force the variable into the RTOS kernel's privileged data area.
static PRIVILEGED_DATA StaticTask_t xTaskBuffer;
static const TaskParameters_t xCheckTaskParameters =
{
vATask, // pvTaskCode - the function that implements the task.
"ATask", // pcName - just a text name for the task to assist debugging.
100, // usStackDepth - the stack size DEFINED IN BYTES.
NULL, // pvParameters - passed into the task function as the function␣
,→parameters.
( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the␣

,→portPRIVILEGE_BIT if the task should run in a privileged state.
cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack.
// xRegions - Allocate up to three separate memory regions for access by

// the task, with appropriate access permissions. Different processors have
// different memory alignment requirements - refer to the FreeRTOS␣
,→documentation
// for full information.

{
{ cReadWriteArray, 32, portMPU_REGION_READ_WRITE },
{ cReadOnlyArray, 32, portMPU_REGION_READ_ONLY },
{ cPrivilegedOnlyAccessArray, 128, portMPU_REGION_PRIVILEGED_READ_
,→WRITE }
&xTaskBuffer; // Holds the task's data structure.

};
int main( void )

{
// Create a task from the const structure defined above. The task handle
// is requested (the second parameter is not NULL) but in this case just for
// demonstration purposes as its not actually used.
xTaskCreateRestricted( &xRegTest1Parameters, &xHandle );


// Start the scheduler.
vTaskStartScheduler();
// Will only get here if there was insufficient memory to create the idle
// and/or timer task.
for( ;; );
}
Memory regions are assigned to a restricted task when the task is created by a call to xTaskCreateRestricted().
These regions can be redefined using vTaskAllocateMPURegions().
Example usage:
// Define an array of MemoryRegion_t structures that configures an MPU region

// allowing read/write access for 1024 bytes starting at the beginning of the
// ucOneKByte array. The other two of the maximum 3 definable regions are
// unused so set to zero.
static const MemoryRegion_t xAltRegions[ portNUM_CONFIGURABLE_REGIONS ] =
{
{ ucOneKByte, 1024, portMPU_REGION_READ_WRITE },
{ 0, 0, 0 },
{ 0, 0, 0 }
};
void vATask( void *pvParameters )

{
// This task was created such that it has access to certain regions of
// memory as defined by the MPU configuration. At some point it is
// desired that these MPU regions are replaced with that defined in the
// xAltRegions const struct above. Use a call to vTaskAllocateMPURegions()
// for this purpose. NULL is used as the task handle to indicate that this
// function should modify the MPU regions of the calling task.
vTaskAllocateMPURegions( NULL, xAltRegions );
// Now the task can continue its function, but from this point on can only
// access its stack and the ucOneKByte array (unless any other statically
// defined or shared regions have been declared elsewhere).
}
Parameters
• xTask: The handle of the task being updated.
• pxRegions: A pointer to an MemoryRegion_t structure that contains the new memory region
definitions.
void vTaskDelete(TaskHandle_t xTaskToDelete)
INCLUDE_vTaskDelete must be defined as 1 for this function to be available. See the configuration section
Remove a task from the RTOS real time kernel s management. The task being deleted will be removed from
all ready, blocked, suspended and event lists.
NOTE: The idle task is responsible for freeing the kernel allocated memory from tasks that have been deleted.
It is therefore important that the idle task is not starved of microcontroller processing time if your application
makes any calls to vTaskDelete (). Memory allocated by the task code is not automatically freed, and should
be freed before the task is deleted.
See the demo application file death.c for sample code that utilises vTaskDelete ().
Example usage:


{
// Create the task, storing the handle.

xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle␣
,→);
// Use the handle to delete the task.

vTaskDelete( xHandle );
}
Parameters
• xTaskToDelete: The handle of the task to be deleted. Passing NULL will cause the calling task
to be deleted.
void vTaskDelay(const TickType_t xTicksToDelay)
Delay a task for a given number of ticks. The actual time that the task remains blocked depends on the tick
rate. The constant portTICK_PERIOD_MS can be used to calculate real time from the tick rate - with the
resolution of one tick period.
INCLUDE_vTaskDelay must be defined as 1 for this function to be available. See the configuration section
vTaskDelay() specifies a time at which the task wishes to unblock relative to the time at which vTaskDelay()
is called. For example, specifying a block period of 100 ticks will cause the task to unblock 100 ticks after
vTaskDelay() is called. vTaskDelay() does not therefore provide a good method of controlling the frequency
of a periodic task as the path taken through the code, as well as other task and interrupt activity, will effect
the frequency at which vTaskDelay() gets called and therefore the time at which the task next executes. See
xTaskDelayUntil() for an alternative API function designed to facilitate fixed frequency execution. It does this
by specifying an absolute time (rather than a relative time) at which the calling task should unblock.
Example usage:
void vTaskFunction( void * pvParameters )

{
// Block for 500ms.
const TickType_t xDelay = 500 / portTICK_PERIOD_MS;
for( ;; )
{
// Simply toggle the LED every 500ms, blocking between each toggle.
vToggleLED();
vTaskDelay( xDelay );
}
}
Parameters
• xTicksToDelay: The amount of time, in tick periods, that the calling task should block.
BaseType_t xTaskDelayUntil(TickType_t *const pxPreviousWakeTime, const TickType_t
xTimeIncrement)
INCLUDE_xTaskDelayUntil must be defined as 1 for this function to be available. See the configuration
section for more information.
Delay a task until a specified time. This function can be used by periodic tasks to ensure a constant execution
frequency.
This function differs from vTaskDelay () in one important aspect: vTaskDelay () will cause a task to block for
the specified number of ticks from the time vTaskDelay () is called. It is therefore difficult to use vTaskDelay
() by itself to generate a fixed execution frequency as the time between a task starting to execute and that task
calling vTaskDelay () may not be fixed [the task may take a different path though the code between calls, or
may get interrupted or preempted a different number of times each time it executes].

Whereas vTaskDelay () specifies a wake time relative to the time at which the function is called, xTaskDe-
layUntil () specifies the absolute (exact) time at which it wishes to unblock.
The macro pdMS_TO_TICKS() can be used to calculate the number of ticks from a time specified in millisec-
onds with a resolution of one tick period.
Example usage:
// Perform an action every 10 ticks.

void vTaskFunction( void * pvParameters )
{
TickType_t xLastWakeTime;
const TickType_t xFrequency = 10;
BaseType_t xWasDelayed;
// Initialise the xLastWakeTime variable with the current time.

xLastWakeTime = xTaskGetTickCount ();
for( ;; )
{
// Wait for the next cycle.
xWasDelayed = xTaskDelayUntil( &xLastWakeTime, xFrequency );
// Perform action here. xWasDelayed value can be used to determine

// whether a deadline was missed if the code here took too long.
}
}
Return Value which can be used to check whether the task was actually delayed. Will be pdTRUE if the task
way delayed and pdFALSE otherwise. A task will not be delayed if the next expected wake time is in the
past.
Parameters
• pxPreviousWakeTime: Pointer to a variable that holds the time at which the task was last
unblocked. The variable must be initialised with the current time prior to its first use (see the example
below). Following this the variable is automatically updated within xTaskDelayUntil ().
• xTimeIncrement: The cycle time period. The task will be unblocked at time *pxPreviousWake-
Time + xTimeIncrement. Calling xTaskDelayUntil with the same xTimeIncrement parameter value
will cause the task to execute with a fixed interface period.
BaseType_t xTaskAbortDelay(TaskHandle_t xTask)
INCLUDE_xTaskAbortDelay must be defined as 1 in FreeRTOSConfig.h for this function to be available.
A task will enter the Blocked state when it is waiting for an event. The event it is waiting for can be a tem-
poral event (waiting for a time), such as when vTaskDelay() is called, or an event on an object, such as when
xQueueReceive() or ulTaskNotifyTake() is called. If the handle of a task that is in the Blocked state is used
in a call to xTaskAbortDelay() then the task will leave the Blocked state, and return from whichever function
call placed the task into the Blocked state.
There is no FromISR version of this function as an interrupt would need to know which object a task
was blocked on in order to know which actions to take. For example, if the task was blocked on a queue the
interrupt handler would then need to know if the queue was locked.
Return If the task referenced by xTask was not in the Blocked state then pdFAIL is returned. Otherwise
pdPASS is returned.
Parameters
• xTask: The handle of the task to remove from the Blocked state.
UBaseType_t uxTaskPriorityGet(const TaskHandle_t xTask)
INCLUDE_uxTaskPriorityGet must be defined as 1 for this function to be available. See the configuration
Obtain the priority of any task.
Example usage:

void vAFunction( void )

{
// Create a task, storing the handle.

,→);
// ...
// Use the handle to obtain the priority of the created task.

// It was created with tskIDLE_PRIORITY, but may have changed
// it itself.
if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY )
{
// The task has changed it's priority.
}
// ...
// Is our priority higher than the created task?

if( uxTaskPriorityGet( xHandle ) < uxTaskPriorityGet( NULL ) )
{
// Our priority (obtained using NULL handle) is higher.
}
}
Return The priority of xTask.

Parameters
• xTask: Handle of the task to be queried. Passing a NULL handle results in the priority of the
calling task being returned.
UBaseType_t uxTaskPriorityGetFromISR(const TaskHandle_t xTask)
A version of uxTaskPriorityGet() that can be used from an ISR.
eTaskState eTaskGetState(TaskHandle_t xTask)
INCLUDE_eTaskGetState must be defined as 1 for this function to be available. See the configuration section
Obtain the state of any task. States are encoded by the eTaskState enumerated type.
Return The state of xTask at the time the function was called. Note the state of the task might change between
the function being called, and the functions return value being tested by the calling task.
Parameters
• xTask: Handle of the task to be queried.
void vTaskGetInfo(TaskHandle_t xTask, TaskStatus_t *pxTaskStatus, BaseType_t xGetFreeStackSpace,
eTaskState eState)
configUSE_TRACE_FACILITY must be defined as 1 for this function to be available. See the configuration
Populates a TaskStatus_t structure with information about a task.
Example usage:
{
TaskStatus_t xTaskDetails;
// Obtain the handle of a task from its name.

xHandle = xTaskGetHandle( "Task_Name" );
// Check the handle is not NULL.



configASSERT( xHandle );
// Use the handle to obtain further information about the task.

vTaskGetInfo( xHandle,
&xTaskDetails,
pdTRUE, // Include the high water mark in xTaskDetails.
eInvalid ); // Include the task state in xTaskDetails.
}
Parameters
• xTask: Handle of the task being queried. If xTask is NULL then information will be returned
about the calling task.
• pxTaskStatus: A pointer to the TaskStatus_t structure that will be filled with information about
the task referenced by the handle passed using the xTask parameter.
• xGetFreeStackSpace: The TaskStatus_t structure contains a member to report the stack high
water mark of the task being queried. Calculating the stack high water mark takes a relatively long
time, and can make the system temporarily unresponsive - so the xGetFreeStackSpace parameter is
provided to allow the high water mark checking to be skipped. The high watermark value will only
be written to the TaskStatus_t structure if xGetFreeStackSpace is not set to pdFALSE;
• eState: The TaskStatus_t structure contains a member to report the state of the task being queried.
Obtaining the task state is not as fast as a simple assignment - so the eState parameter is provided to
allow the state information to be omitted from the TaskStatus_t structure. To obtain state information
then set eState to eInvalid - otherwise the value passed in eState will be reported as the task state in
the TaskStatus_t structure.
void vTaskPrioritySet(TaskHandle_t xTask, UBaseType_t uxNewPriority)
INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available. See the configuration
Set the priority of any task.
A context switch will occur before the function returns if the priority being set is higher than the currently
executing task.
Example usage:

{

,→);
// ...
// Use the handle to raise the priority of the created task.

vTaskPrioritySet( xHandle, tskIDLE_PRIORITY + 1 );
// ...
// Use a NULL handle to raise our priority to the same value.

vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 );
}
Parameters
• xTask: Handle to the task for which the priority is being set. Passing a NULL handle results in the
priority of the calling task being set.
• uxNewPriority: The priority to which the task will be set.
void vTaskSuspend(TaskHandle_t xTaskToSuspend)
INCLUDE_vTaskSuspend must be defined as 1 for this function to be available. See the configuration section


Suspend any task. When suspended a task will never get any microcontroller processing time, no matter what
its priority.
Calls to vTaskSuspend are not accumulative - i.e. calling vTaskSuspend () twice on the same task still only
requires one call to vTaskResume () to ready the suspended task.
Example usage:

{

,→);
// ...
// Use the handle to suspend the created task.

// ...
// The created task will not run during this period, unless
// another task calls vTaskResume( xHandle ).
//...
// Suspend ourselves.
vTaskSuspend( NULL );
// We cannot get here unless another task calls vTaskResume

// with our handle as the parameter.
}
Parameters
• xTaskToSuspend: Handle to the task being suspended. Passing a NULL handle will cause the
calling task to be suspended.
void vTaskResume(TaskHandle_t xTaskToResume)
INCLUDE_vTaskSuspend must be defined as 1 for this function to be available. See the configuration section
Resumes a suspended task.
A task that has been suspended by one or more calls to vTaskSuspend () will be made available for running
again by a single call to vTaskResume ().
Example usage:

{

,→);
// ...
// Use the handle to suspend the created task.



// ...
// The created task will not run during this period, unless
// another task calls vTaskResume( xHandle ).
//...
// Resume the suspended task ourselves.

vTaskResume( xHandle );
// The created task will once again get microcontroller processing

// time in accordance with its priority within the system.
}
Parameters
• xTaskToResume: Handle to the task being readied.
BaseType_t xTaskResumeFromISR(TaskHandle_t xTaskToResume)
INCLUDE_xTaskResumeFromISR must be defined as 1 for this function to be available. See the configuration
An implementation of vTaskResume() that can be called from within an ISR.
A task that has been suspended by one or more calls to vTaskSuspend () will be made available for running
again by a single call to xTaskResumeFromISR ().
xTaskResumeFromISR() should not be used to synchronise a task with an interrupt if there is a chance that
the interrupt could arrive prior to the task being suspended - as this can lead to interrupts being missed. Use
of a semaphore as a synchronisation mechanism would avoid this eventuality.
Return pdTRUE if resuming the task should result in a context switch, otherwise pdFALSE. This is used by
the ISR to determine if a context switch may be required following the ISR.
Parameters
• xTaskToResume: Handle to the task being readied.
void vTaskStartScheduler(void)
Starts the real time kernel tick processing. After calling the kernel has control over which tasks are executed
and when.
NOTE: In ESP-IDF the scheduler is started automatically during application startup, vTaskStartScheduler()
should not be called from ESP-IDF applications.
See the demo application file main.c for an example of creating tasks and starting the kernel.
Example usage:

{
// Create at least one task before starting the kernel.
xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
// Start the real time kernel with preemption.

vTaskStartScheduler ();
// Will not get here unless a task calls vTaskEndScheduler ()

}
void vTaskEndScheduler(void)
NOTE: At the time of writing only the x86 real mode port, which runs on a PC in place of DOS, implements
this function.

Stops the real time kernel tick. All created tasks will be automatically deleted and multitasking (either pre-
emptive or cooperative) will stop. Execution then resumes from the point where vTaskStartScheduler () was
called, as if vTaskStartScheduler () had just returned.
See the demo application file main. c in the demo/PC directory for an example that uses vTaskEndScheduler
().
vTaskEndScheduler () requires an exit function to be defined within the portable layer (see vPortEndScheduler
() in port. c for the PC port). This performs hardware specific operations such as stopping the kernel tick.
vTaskEndScheduler () will cause all of the resources allocated by the kernel to be freed - but will not free
resources allocated by application tasks.
Example usage:

{
for( ;; )
{
// At some point we want to end the real time kernel processing

// so call ...
vTaskEndScheduler ();
}
}

{
// Create at least one task before starting the kernel.
xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
// Start the real time kernel with preemption.

vTaskStartScheduler ();
// Will only get here when the vTaskCode () task has called
// vTaskEndScheduler (). When we get here we are back to single task
// execution.
}
void vTaskSuspendAll(void)
Suspends the scheduler without disabling interrupts. Context switches will not occur while the scheduler is
suspended.
After calling vTaskSuspendAll () the calling task will continue to execute without risk of being swapped out
until a call to xTaskResumeAll () has been made.
API functions that have the potential to cause a context switch (for example, vTaskDelayUntil(), xQueueSend(),
etc.) must not be called while the scheduler is suspended.
Example usage:
void vTask1( void * pvParameters )

{
for( ;; )
{
// ...
// At some point the task wants to perform a long operation during

// which it does not want to get swapped out. It cannot use
// taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
// operation may cause interrupts to be missed - including the


// ticks.
// Prevent the real time kernel swapping out the task.

vTaskSuspendAll ();
// Perform the operation here. There is no need to use critical

// sections as we have all the microcontroller processing time.
// During this time interrupts will still operate and the kernel
// tick count will be maintained.
// ...
// The operation is complete. Restart the kernel.

xTaskResumeAll ();
}
}
BaseType_t xTaskResumeAll(void)
Resumes scheduler activity after it was suspended by a call to vTaskSuspendAll().
xTaskResumeAll() only resumes the scheduler. It does not unsuspend tasks that were previously suspended by
a call to vTaskSuspend().
Example usage:
void vTask1( void * pvParameters )

{
for( ;; )
{
// ...
// At some point the task wants to perform a long operation during

// which it does not want to get swapped out. It cannot use
// taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
// operation may cause interrupts to be missed - including the
// ticks.
// Prevent the real time kernel swapping out the task.

vTaskSuspendAll ();
// Perform the operation here. There is no need to use critical

// sections as we have all the microcontroller processing time.
// During this time interrupts will still operate and the real
// time kernel tick count will be maintained.
// ...
// The operation is complete. Restart the kernel. We want to force

// a context switch - but there is no point if resuming the scheduler
// caused a context switch already.
if( !xTaskResumeAll () )
{
taskYIELD ();
}
}
}
Return If resuming the scheduler caused a context switch then pdTRUE is returned, otherwise pdFALSE is
returned.
TickType_t xTaskGetTickCount(void)

Return The count of ticks since vTaskStartScheduler was called.

TickType_t xTaskGetTickCountFromISR(void)
This is a version of xTaskGetTickCount() that is safe to be called from an ISR - provided that TickType_t is
the natural word size of the microcontroller being used or interrupt nesting is either not supported or not being
used.
Return The count of ticks since vTaskStartScheduler was called.
UBaseType_t uxTaskGetNumberOfTasks(void)
Return The number of tasks that the real time kernel is currently managing. This includes all ready, blocked
and suspended tasks. A task that has been deleted but not yet freed by the idle task will also be included
in the count.
char *pcTaskGetName(TaskHandle_t xTaskToQuery)
Return The text (human readable) name of the task referenced by the handle xTaskToQuery. A task can
query its own name by either passing in its own handle, or by setting xTaskToQuery to NULL.
TaskHandle_t xTaskGetHandle(const char *pcNameToQuery)
NOTE: This function takes a relatively long time to complete and should be used sparingly.
Return The handle of the task that has the human readable name pcNameToQuery. NULL is returned if
no matching name is found. INCLUDE_xTaskGetHandle must be set to 1 in FreeRTOSConfig.h for
pcTaskGetHandle() to be available.
UBaseType_t uxTaskGetStackHighWaterMark(TaskHandle_t xTask)
Returns the high water mark of the stack associated with xTask.
INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in FreeRTOSConfig.h for this function to be
available.
Returns the high water mark of the stack associated with xTask. That is, the minimum free stack space there
has been (in bytes not words, unlike vanilla FreeRTOS) since the task started. The smaller the returned number
the closer the task has come to overflowing its stack.
uxTaskGetStackHighWaterMark() and uxTaskGetStackHighWaterMark2() are the same except for their re-
turn type. Using configSTACK_DEPTH_TYPE allows the user to determine the return type. It gets around
the problem of the value overflowing on 8-bit types without breaking backward compatibility for applications
that expect an 8-bit return type.
Return The smallest amount of free stack space there has been (in bytes not words, unlike vanilla FreeRTOS)
since the task referenced by xTask was created.
Parameters
• xTask: Handle of the task associated with the stack to be checked. Set xTask to NULL to check
the stack of the calling task.
configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2(TaskHandle_t xTask)
Returns the start of the stack associated with xTask.
INCLUDE_uxTaskGetStackHighWaterMark2 must be set to 1 in FreeRTOSConfig.h for this function to be
available.
Returns the high water mark of the stack associated with xTask. That is, the minimum free stack space there
has been (in words, so on a 32 bit machine a value of 1 means 4 bytes) since the task started. The smaller the
returned number the closer the task has come to overflowing its stack.
uxTaskGetStackHighWaterMark() and uxTaskGetStackHighWaterMark2() are the same except for their re-
turn type. Using configSTACK_DEPTH_TYPE allows the user to determine the return type. It gets around
the problem of the value overflowing on 8-bit types without breaking backward compatibility for applications
that expect an 8-bit return type.
Return The smallest amount of free stack space there has been (in words, so actual spaces on the stack rather
than bytes) since the task referenced by xTask was created.
Parameters

• xTask: Handle of the task associated with the stack to be checked. Set xTask to NULL to check
the stack of the calling task.
uint8_t *pxTaskGetStackStart(TaskHandle_t xTask)
Returns the start of the stack associated with xTask.
INCLUDE_pxTaskGetStackStart must be set to 1 in FreeRTOSConfig.h for this function to be available.
Returns the lowest stack memory address, regardless of whether the stack grows up or down.
Return A pointer to the start of the stack.
Parameters
• xTask: Handle of the task associated with the stack returned. Set xTask to NULL to return the
stack of the calling task.
void vTaskSetApplicationTaskTag(TaskHandle_t xTask, TaskHookFunction_t pxHookFunction)
Sets pxHookFunction to be the task hook function used by the task xTask.
Parameters
• xTask: Handle of the task to set the hook function for Passing xTask as NULL has the effect of
setting the calling tasks hook function.
• pxHookFunction: Pointer to the hook function.
TaskHookFunction_t xTaskGetApplicationTaskTag(TaskHandle_t xTask)
Returns the pxHookFunction value assigned to the task xTask. Do not call from an interrupt service routine -
call xTaskGetApplicationTaskTagFromISR() instead.
TaskHookFunction_t xTaskGetApplicationTaskTagFromISR(TaskHandle_t xTask)
Returns the pxHookFunction value assigned to the task xTask. Can be called from an interrupt service routine.
void vTaskSetThreadLocalStoragePointer(TaskHandle_t xTaskToSet, BaseType_t xIndex, void
*pvValue)
Set local storage pointer specific to the given task.
Each task contains an array of pointers that is dimensioned by the con-
figNUM_THREAD_LOCAL_STORAGE_POINTERS setting in FreeRTOSConfig.h. The kernel does
not use the pointers itself, so the application writer can use the pointers for any purpose they wish.
Parameters
• xTaskToSet: Task to set thread local storage pointer for
• xIndex: The index of the pointer to set, from 0 to con-
figNUM_THREAD_LOCAL_STORAGE_POINTERS - 1.
• pvValue: Pointer value to set.
void *pvTaskGetThreadLocalStoragePointer(TaskHandle_t xTaskToQuery, BaseType_t xIn-
dex)
Get local storage pointer specific to the given task.
Return Pointer value
Parameters
• xTaskToQuery: Task to get thread local storage pointer for
• xIndex: The index of the pointer to get, from 0 to con-
void vTaskSetThreadLocalStoragePointerAndDelCallback(TaskHandle_t xTaskToSet,
BaseType_t xIndex, void
*pvValue, TlsDeleteCallback-
Function_t pvDelCallback)
Set local storage pointer and deletion callback.

Local storage pointers set for a task can reference dynamically allocated resources. This function is similar to
vTaskSetThreadLocalStoragePointer, but provides a way to release these resources when the task gets deleted.
For each pointer, a callback function can be set. This function will be called when task is deleted, with the
local storage pointer index and value as arguments.
Parameters
• xTaskToSet: Task to set thread local storage pointer for
• xIndex: The index of the pointer to set, from 0 to con-
• pvValue: Pointer value to set.
• pvDelCallback: Function to call to dispose of the local storage pointer when the task is deleted.
void vApplicationGetIdleTaskMemory(StaticTask_t **ppxIdleTaskTCBBuffer, Stack-
Type_t **ppxIdleTaskStackBuffer, uint32_t
*pulIdleTaskStackSize)
This function is used to provide a statically allocated block of memory to FreeRTOS to hold the Idle Task TCB.
This function is required when configSUPPORT_STATIC_ALLOCATION is set. For more information see
this URI: https://www.FreeRTOS.org/a00110.html#configSUPPORT_STATIC_ALLOCATION
Parameters
• ppxIdleTaskTCBBuffer: A handle to a statically allocated TCB buffer
• ppxIdleTaskStackBuffer: A handle to a statically allocated Stack buffer for thie idle task
• pulIdleTaskStackSize: A pointer to the number of elements that will fit in the allocated
stack buffer
BaseType_t xTaskCallApplicationTaskHook(TaskHandle_t xTask, void *pvParameter)
Calls the hook function associated with xTask. Passing xTask as NULL has the effect of calling the Running
tasks (the calling task) hook function.
Parameters
• xTask: Handle of the task to call the hook for.
• pvParameter: Parameter passed to the hook function for the task to interpret as it wants. The
return value is the value returned by the task hook function registered by the user.
TaskHandle_t xTaskGetIdleTaskHandle(void)
xTaskGetIdleTaskHandle() is only available if INCLUDE_xTaskGetIdleTaskHandle is set to 1 in FreeR-
TOSConfig.h.
Simply returns the handle of the idle task. It is not valid to call xTaskGetIdleTaskHandle() before the scheduler
has been started.
UBaseType_t uxTaskGetSystemState(TaskStatus_t *const pxTaskStatusArray, const UBase-
Type_t uxArraySize, uint32_t *const pulTotalRunTime)
configUSE_TRACE_FACILITY must be defined as 1 in FreeRTOSConfig.h for uxTaskGetSystemState() to
be available.
uxTaskGetSystemState() populates an TaskStatus_t structure for each task in the system. TaskStatus_t struc-
tures contain, among other things, members for the task handle, task name, task priority, task state, and total
amount of run time consumed by the task. See the TaskStatus_t structure definition in this file for the full
member list.
NOTE: This function is intended for debugging use only as its use results in the scheduler remaining suspended
for an extended period.
Example usage:
// This example demonstrates how a human readable table of run time stats
// information is generated from raw data provided by uxTaskGetSystemState().
// The human readable table is written to pcWriteBuffer
void vTaskGetRunTimeStats( char *pcWriteBuffer )
{
TaskStatus_t *pxTaskStatusArray;
volatile UBaseType_t uxArraySize, x;
uint32_t ulTotalRunTime, ulStatsAsPercentage;

// Make sure the write buffer does not contain a string.

*pcWriteBuffer = 0x00;
// Take a snapshot of the number of tasks in case it changes while this

// function is executing.
uxArraySize = uxTaskGetNumberOfTasks();
// Allocate a TaskStatus_t structure for each task. An array could be

// allocated statically at compile time.
pxTaskStatusArray = pvPortMalloc( uxArraySize * sizeof( TaskStatus_t ) );
if( pxTaskStatusArray != NULL )

{
// Generate raw status information about each task.
uxArraySize = uxTaskGetSystemState( pxTaskStatusArray, uxArraySize, &
,→ulTotalRunTime );
// For percentage calculations.

ulTotalRunTime /= 100UL;
// Avoid divide by zero errors.

if( ulTotalRunTime > 0 )
{
// For each populated position in the pxTaskStatusArray array,
// format the raw data as human readable ASCII data
for( x = 0; x < uxArraySize; x++ )
{
// What percentage of the total run time has the task used?
// This will always be rounded down to the nearest integer.
// ulTotalRunTimeDiv100 has already been divided by 100.
ulStatsAsPercentage = pxTaskStatusArray[ x ].ulRunTimeCounter␣
,→/ ulTotalRunTime;
if( ulStatsAsPercentage > 0UL )

{
sprintf( pcWriteBuffer, "%s\t\t%lu\t\t%lu%%\r\n",␣
,→pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter,␣
,→ulStatsAsPercentage );
}
else
{
// If the percentage is zero here then the task has
// consumed less than 1% of the total run time.
sprintf( pcWriteBuffer, "%s\t\t%lu\t\t<1%%\r\n",␣
,→pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter );
pcWriteBuffer += strlen( ( char * ) pcWriteBuffer );

}
}
// The array is no longer needed, free the memory it consumes.

vPortFree( pxTaskStatusArray );
}
}
Return The number of TaskStatus_t structures that were populated by uxTaskGetSystemState(). This should
equal the number returned by the uxTaskGetNumberOfTasks() API function, but will be zero if the value
passed in the uxArraySize parameter was too small.
Parameters

• pxTaskStatusArray: A pointer to an array of TaskStatus_t structures. The array must contain

at least one TaskStatus_t structure for each task that is under the control of the RTOS. The number
of tasks under the control of the RTOS can be determined using the uxTaskGetNumberOfTasks()
API function.
• uxArraySize: The size of the array pointed to by the pxTaskStatusArray parameter. The size is
specified as the number of indexes in the array, or the number of TaskStatus_t structures contained
in the array, not by the number of bytes in the array.
• pulTotalRunTime: If configGENERATE_RUN_TIME_STATS is set to 1 in FreeRTOSCon-
fig.h then *pulTotalRunTime is set by uxTaskGetSystemState() to the total run time (as defined by
the run time stats clock, see https://www.FreeRTOS.org/rtos-run-time-stats.html) since the target
booted. pulTotalRunTime can be set to NULL to omit the total run time information.
void vTaskList(char *pcWriteBuffer)
List all the current tasks.
configUSE_TRACE_FACILITY and configUSE_STATS_FORMATTING_FUNCTIONS must both be de-
fined as 1 for this function to be available. See the configuration section of the FreeRTOS.org website for more
information.
NOTE 1: This function will disable interrupts for its duration. It is not intended for normal application runtime
use but as a debug aid.
Lists all the current tasks, along with their current state and stack usage high water mark.
Tasks are reported as blocked ( B ), ready ( R ), deleted ( D ) or suspended ( S ).
PLEASE NOTE:
This function is provided for convenience only, and is used by many of the demo applications. Do not consider
it to be part of the scheduler.
vTaskList() calls uxTaskGetSystemState(), then formats part of the uxTaskGetSystemState() output into a
human readable table that displays task names, states and stack usage.
vTaskList() has a dependency on the sprintf() C library function that might bloat the code size, use a lot of stack,
and provide different results on different platforms. An alternative, tiny, third party, and limited functionality
implementation of sprintf() is provided in many of the FreeRTOS/Demo sub-directories in a file called printf-
stdarg.c (note printf-stdarg.c does not provide a full snprintf() implementation!).
It is recommended that production systems call uxTaskGetSystemState() directly to get access to raw stats data,
rather than indirectly through a call to vTaskList().
Parameters
• pcWriteBuffer: A buffer into which the above mentioned details will be written, in ASCII form.
This buffer is assumed to be large enough to contain the generated report. Approximately 40 bytes
per task should be sufficient.
void vTaskGetRunTimeStats(char *pcWriteBuffer)
Get the state of running tasks as a string
configGENERATE_RUN_TIME_STATS and configUSE_STATS_FORMATTING_FUNCTIONS must
both be defined as 1 for this function to be available. The application must also then provide definitions for port-
CONFIGURE_TIMER_FOR_RUN_TIME_STATS() and portGET_RUN_TIME_COUNTER_VALUE()
to configure a peripheral timer/counter and return the timers current count value respectively. The counter
should be at least 10 times the frequency of the tick count.
NOTE 1: This function will disable interrupts for its duration. It is not intended for normal application runtime
use but as a debug aid.
Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total accumulated execution time being
stored for each task. The resolution of the accumulated time value depends on the frequency of the timer
configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro. Calling vTaskGetRun-
TimeStats() writes the total execution time of each task into a buffer, both as an absolute count value and as a
percentage of the total system execution time.
NOTE 2:

This function is provided for convenience only, and is used by many of the demo applications. Do not consider
it to be part of the scheduler.
vTaskGetRunTimeStats() calls uxTaskGetSystemState(), then formats part of the uxTaskGetSystemState()
output into a human readable table that displays the amount of time each task has spent in the Running state
in both absolute and percentage terms.
vTaskGetRunTimeStats() has a dependency on the sprintf() C library function that might bloat the code size,
use a lot of stack, and provide different results on different platforms. An alternative, tiny, third party, and
limited functionality implementation of sprintf() is provided in many of the FreeRTOS/Demo sub-directories
in a file called printf-stdarg.c (note printf-stdarg.c does not provide a full snprintf() implementation!).
It is recommended that production systems call uxTaskGetSystemState() directly to get access to raw stats data,
rather than indirectly through a call to vTaskGetRunTimeStats().
Parameters
• pcWriteBuffer: A buffer into which the execution times will be written, in ASCII form. This
buffer is assumed to be large enough to contain the generated report. Approximately 40 bytes per
task should be sufficient.
uint32_t ulTaskGetIdleRunTimeCounter(void)
configGENERATE_RUN_TIME_STATS and configUSE_STATS_FORMATTING_FUNCTIONS must
both be defined as 1 for this function to be available. The application must also then provide definitions for port-
CONFIGURE_TIMER_FOR_RUN_TIME_STATS() and portGET_RUN_TIME_COUNTER_VALUE()
to configure a peripheral timer/counter and return the timers current count value respectively. The counter
should be at least 10 times the frequency of the tick count.
Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total accumulated execution time being
stored for each task. The resolution of the accumulated time value depends on the frequency of the timer con-
figured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro. While uxTaskGetSystem-
State() and vTaskGetRunTimeStats() writes the total execution time of each task into a buffer, ulTaskGetI-
dleRunTimeCounter() returns the total execution time of just the idle task.
Return The total run time of the idle task. This is the amount of time the idle task has actually
been executing. The unit of time is dependent on the frequency configured using the portCON-
FIGURE_TIMER_FOR_RUN_TIME_STATS() and portGET_RUN_TIME_COUNTER_VALUE()
macros.
BaseType_t xTaskGenericNotify(TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNo-
tify, uint32_t ulValue, eNotifyAction eAction, uint32_t
*pulPreviousNotificationValue)
See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these functions to be available.
Sends a direct to task notification to a task, with an optional value and action.
Each task has a private array of notification values (or notifications ), each of which is a 32-bit un-
signed integer (uint32_t). The constant configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number
of indexes in the array, and (for backward compatibility) defaults to 1 if left undefined. Prior to FreeRTOS
V10.4.0 there was only one notification value per task.
Events can be sent to a task using an intermediary object. Examples of such objects are queues, semaphores,
mutexes and event groups. Task notifications are a method of sending an event directly to a task without the
need for such an intermediary object.
A notification sent to a task can optionally perform an action, such as update, overwrite or increment one of
the task s notification values. In that way task notifications can be used to send data to a task, or be used as
light weight and fast binary or counting semaphores.
A task can use xTaskNotifyWaitIndexed() to [optionally] block to wait for a notification to be pending, or
ulTaskNotifyTakeIndexed() to [optionally] block to wait for a notification value to have a non-zero value. The
task does not consume any CPU time while it is in the Blocked state.
A notification sent to a task will remain pending until it is cleared by the task calling xTaskNotifyWaitIndexed()
or ulTaskNotifyTakeIndexed() (or their un-indexed equivalents). If the task was already in the Blocked state

to wait for a notification when the notification arrives then the task will automatically be removed from the
Blocked state (unblocked) and the notification cleared.
NOTE Each notification within the array operates independently - a task can only block on one notification
within the array at a time and will not be unblocked by a notification sent to any other array index.
Backward compatibility information: Prior to FreeRTOS V10.4.0 each task had a single notification value
, and all task notification API functions operated on that value. Replacing the single notification value with
an array of notification values necessitated a new set of API functions that could address specific notifications
within the array. xTaskNotify() is the original API function, and remains backward compatible by always
operating on the notification value at index 0 in the array. Calling xTaskNotify() is equivalent to calling xTas-
kNotifyIndexed() with the uxIndexToNotify parameter set to 0.
eSetBits - The target notification value is bitwise ORed with ulValue. xTaskNotifyIndexed() always returns
pdPASS in this case.
Parameters
• xTaskToNotify: The handle of the task being notified. The handle to a task can be returned
from the xTaskCreate() API function used to create the task, and the handle of the currently running
task can be obtained by calling xTaskGetCurrentTaskHandle().
• uxIndexToNotify: The index within the target task s array of notification values
to which the notification is to be sent. uxIndexToNotify must be less than config-
TASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotify() does not have this parameter and al-
ways sends notifications to index 0.
• ulValue: Data that can be sent with the notification. How the data is used depends on the value
of the eAction parameter.
• eAction: Specifies how the notification updates the task s notification value, if at all. Valid values
for eAction are as follows:
eIncrement - The target notification value is incremented. ulValue is not used and xTaskNotifyIndexed() always
returns pdPASS in this case.
eSetValueWithOverwrite - The target notification value is set to the value of ulValue, even if the task being no-
tified had not yet processed the previous notification at the same array index (the task already had a notification
pending at that index). xTaskNotifyIndexed() always returns pdPASS in this case.
eSetValueWithoutOverwrite - If the task being notified did not already have a notification pending at the same
array index then the target notification value is set to ulValue and xTaskNotifyIndexed() will return pdPASS.
If the task being notified already had a notification pending at the same array index then no action is performed
and pdFAIL is returned.
eNoAction - The task receives a notification at the specified array index without the notification value at that
index being updated. ulValue is not used and xTaskNotifyIndexed() always returns pdPASS in this case.
pulPreviousNotificationValue - Can be used to pass out the subject task s notification value before any bits
are modified by the notify function.
Return Dependent on the value of eAction. See the description of the eAction parameter.
BaseType_t xTaskGenericNotifyFromISR(TaskHandle_t xTaskToNotify, UBaseType_t uxIn-
dexToNotify, uint32_t ulValue, eNotifyAction eAction,
uint32_t *pulPreviousNotificationValue, BaseType_t
*pxHigherPriorityTaskWoken)
A version of xTaskNotifyIndexed() that can be used from an interrupt service routine (ISR).


an array of notification values necessitated a new set of API functions that could address specific notifica-
tions within the array. xTaskNotifyFromISR() is the original API function, and remains backward compatible
by always operating on the notification value at index 0 within the array. Calling xTaskNotifyFromISR() is
equivalent to calling xTaskNotifyIndexedFromISR() with the uxIndexToNotify parameter set to 0.
eSetBits - The task s notification value is bitwise ORed with ulValue. xTaskNotify() always returns pdPASS
in this case.
Parameters
TASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyFromISR() does not have this param-
eter and always sends notifications to index 0.
• ulValue: Data that can be sent with the notification. How the data is used depends on the value
of the eAction parameter.
• eAction: Specifies how the notification updates the task s notification value, if at all. Valid values
for eAction are as follows:
eIncrement - The task s notification value is incremented. ulValue is not used and xTaskNotify() always
returns pdPASS in this case.
eSetValueWithOverwrite - The task s notification value is set to the value of ulValue, even if the task being
notified had not yet processed the previous notification (the task already had a notification pending). xTaskNo-
tify() always returns pdPASS in this case.
eSetValueWithoutOverwrite - If the task being notified did not already have a notification pending then the
task s notification value is set to ulValue and xTaskNotify() will return pdPASS. If the task being notified
already had a notification pending then no action is performed and pdFAIL is returned.
eNoAction - The task receives a notification without its notification value being updated. ulValue is not used
and xTaskNotify() always returns pdPASS in this case.
Return Dependent on the value of eAction. See the description of the eAction parameter.
Parameters
• pxHigherPriorityTaskWoken: xTaskNotifyFromISR() will set *pxHigherPriorityTaskWo-
ken to pdTRUE if sending the notification caused the task to which the notification was sent to leave
the Blocked state, and the unblocked task has a priority higher than the currently running task. If
xTaskNotifyFromISR() sets this value to pdTRUE then a context switch should be requested before
the interrupt is exited. How a context switch is requested from an ISR is dependent on the port - see
the documentation page for the port in use.

BaseType_t xTaskGenericNotifyWait(UBaseType_t uxIndexToWaitOn, uint32_t ulBitsTo-

ClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t
*pulNotificationValue, TickType_t xTicksToWait)
Waits for a direct to task notification to be pending at a given index within an array of direct to task notifications.
configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this function to be available.
within the array. xTaskNotifyWait() is the original API function, and remains backward compatible by always
operating on the notification value at index 0 in the array. Calling xTaskNotifyWait() is equivalent to calling
xTaskNotifyWaitIndexed() with the uxIndexToWaitOn parameter set to 0.
Return If a notification was received (including notifications that were already pending when xTaskNotifyWait
was called) then pdPASS is returned. Otherwise pdFAIL is returned.
Parameters
• uxIndexToWaitOn: The index within the calling task s array of notification values on which
the calling task will wait for a notification to be received. uxIndexToWaitOn must be less than con-
figTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyWait() does not have this parameter
and always waits for notifications on index 0.
• ulBitsToClearOnEntry: Bits that are set in ulBitsToClearOnEntry value will be cleared in
the calling task s notification value before the task checks to see if any notifications are pending, and
optionally blocks if no notifications are pending. Setting ulBitsToClearOnEntry to ULONG_MAX
(if limits.h is included) or 0xffffffffUL (if limits.h is not included) will have the effect of resetting the
task s notification value to 0. Setting ulBitsToClearOnEntry to 0 will leave the task s notification
value unchanged.
• ulBitsToClearOnExit: If a notification is pending or received before the calling task ex-
its the xTaskNotifyWait() function then the task s notification value (see the xTaskNotify() API
function) is passed out using the pulNotificationValue parameter. Then any bits that are set in ul-
BitsToClearOnExit will be cleared in the task s notification value (note *pulNotificationValue is
set before any bits are cleared). Setting ulBitsToClearOnExit to ULONG_MAX (if limits.h is in-
cluded) or 0xffffffffUL (if limits.h is not included) will have the effect of resetting the task s
notification value to 0 before the function exits. Setting ulBitsToClearOnExit to 0 will leave the
task s notification value unchanged when the function exits (in which case the value passed out in
pulNotificationValue will match the task s notification value).

• pulNotificationValue: Used to pass the task s notification value out of the function. Note
the value passed out will not be effected by the clearing of any bits caused by ulBitsToClearOnExit
being non-zero.
• xTicksToWait: The maximum amount of time that the task should wait in the Blocked state for
a notification to be received, should a notification not already be pending when xTaskNotifyWait()
was called. The task will not consume any processing time while it is in the Blocked state. This is
specified in kernel ticks, the macro pdMS_TO_TICKS( value_in_ms ) can be used to convert a time
specified in milliseconds to a time specified in ticks.
void vTaskGenericNotifyGiveFromISR(TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNo-
tify, BaseType_t *pxHigherPriorityTaskWoken)
A version of xTaskNotifyGiveIndexed() that can be called from an interrupt service routine (ISR).
See https://www.FreeRTOS.org/RTOS-task-notifications.html for more details.
configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this macro to be available.
vTaskNotifyGiveIndexedFromISR() is intended for use when task notifications are used as light weight and
faster binary or counting semaphore equivalents. Actual FreeRTOS semaphores are given from an ISR using
the xSemaphoreGiveFromISR() API function, the equivalent action that instead uses a task notification is
vTaskNotifyGiveIndexedFromISR().
When task notifications are being used as a binary or counting semaphore equivalent then the task being no-
tified should wait for the notification using the ulTaskNotificationTakeIndexed() API function rather than the
xTaskNotifyWaitIndexed() API function.
within the array. xTaskNotifyFromISR() is the original API function, and remains backward compatible by
always operating on the notification value at index 0 within the array. Calling xTaskNotifyGiveFromISR() is
equivalent to calling xTaskNotifyGiveIndexedFromISR() with the uxIndexToNotify parameter set to 0.
Parameters
TASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyGiveFromISR() does not have this pa-
rameter and always sends notifications to index 0.
• pxHigherPriorityTaskWoken: vTaskNotifyGiveFromISR() will set *pxHigherPriority-
TaskWoken to pdTRUE if sending the notification caused the task to which the notification was
sent to leave the Blocked state, and the unblocked task has a priority higher than the currently run-
ning task. If vTaskNotifyGiveFromISR() sets this value to pdTRUE then a context switch should be
requested before the interrupt is exited. How a context switch is requested from an ISR is dependent
on the port - see the documentation page for the port in use.

uint32_t ulTaskGenericNotifyTake(UBaseType_t uxIndexToWaitOn, BaseType_t xClearCoun-

tOnExit, TickType_t xTicksToWait)
Waits for a direct to task notification on a particular index in the calling task s notification array in a manner
similar to taking a counting semaphore.
configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this function to be available.
ulTaskNotifyTakeIndexed() is intended for use when a task notification is used as a faster and lighter weight bi-
nary or counting semaphore alternative. Actual FreeRTOS semaphores are taken using the xSemaphoreTake()
API function, the equivalent action that instead uses a task notification is ulTaskNotifyTakeIndexed().
When a task is using its notification value as a binary or counting semaphore other tasks should send notifications
to it using the xTaskNotifyGiveIndexed() macro, or xTaskNotifyIndex() function with the eAction parameter
set to eIncrement.
ulTaskNotifyTakeIndexed() can either clear the task s notification value at the array index specified by the
uxIndexToWaitOn parameter to zero on exit, in which case the notification value acts like a binary semaphore,
or decrement the notification value on exit, in which case the notification value acts like a counting semaphore.
A task can use ulTaskNotifyTakeIndexed() to [optionally] block to wait for the task s notification value to be
non-zero. The task does not consume any CPU time while it is in the Blocked state.
Where as xTaskNotifyWaitIndexed() will return when a notification is pending, ulTaskNotifyTakeIndexed()
will return when the task s notification value is not zero.
within the array. ulTaskNotifyTake() is the original API function, and remains backward compatible by always
operating on the notification value at index 0 in the array. Calling ulTaskNotifyTake() is equivalent to calling
ulTaskNotifyTakeIndexed() with the uxIndexToWaitOn parameter set to 0.
Return The task s notification count before it is either cleared to zero or decremented (see the xClearCoun-
tOnExit parameter).
Parameters
• uxIndexToWaitOn: The index within the calling task s array of notification values on which
the calling task will wait for a notification to be non-zero. uxIndexToWaitOn must be less than con-
figTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyTake() does not have this parameter
and always waits for notifications on index 0.
• xClearCountOnExit: if xClearCountOnExit is pdFALSE then the task s notification value
is decremented when the function exits. In this way the notification value acts like a counting
semaphore. If xClearCountOnExit is not pdFALSE then the task s notification value is cleared
to zero when the function exits. In this way the notification value acts like a binary semaphore.
• xTicksToWait: The maximum amount of time that the task should wait in the Blocked state for
the task s notification value to be greater than zero, should the count not already be greater than
zero when ulTaskNotifyTake() was called. The task will not consume any processing time while it

is in the Blocked state. This is specified in kernel ticks, the macro pdMS_TO_TICKS( value_in_ms
) can be used to convert a time specified in milliseconds to a time specified in ticks.
BaseType_t xTaskGenericNotifyStateClear(TaskHandle_t xTask, UBaseType_t uxIndexTo-
Clear)
If a notification is sent to an index within the array of notifications then the notification at that index is said to
be pending until it is read or explicitly cleared by the receiving task. xTaskNotifyStateClearIndexed() is
the function that clears a pending notification without reading the notification value. The notification value at
the same array index is not altered. Set xTask to NULL to clear the notification state of the calling task.
within the array. xTaskNotifyStateClear() is the original API function, and remains backward compatible
by always operating on the notification value at index 0 within the array. Calling xTaskNotifyStateClear() is
equivalent to calling xTaskNotifyStateClearIndexed() with the uxIndexToNotify parameter set to 0.
Return pdTRUE if the task s notification state was set to eNotWaitingNotification, otherwise pdFALSE.
Parameters
• xTask: The handle of the RTOS task that will have a notification state cleared. Set xTask to NULL
to clear a notification state in the calling task. To obtain a task s handle create the task using
xTaskCreate() and make use of the pxCreatedTask parameter, or create the task using xTaskCreat-
eStatic() and store the returned value, or use the task s name in a call to xTaskGetHandle().
• uxIndexToClear: The index within the target task s array of notification values to act upon.
For example, setting uxIndexToClear to 1 will clear the state of the notification at index 1 within
the array. uxIndexToClear must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.
ulTaskNotifyStateClear() does not have this parameter and always acts on the notification at index
0.
uint32_t ulTaskGenericNotifyValueClear(TaskHandle_t xTask, UBaseType_t uxIndexToClear,
uint32_t ulBitsToClear)
ulTaskNotifyValueClearIndexed() clears the bits specified by the ulBitsToClear bit mask in the notification
value at array index uxIndexToClear of the task referenced by xTask.
within the array. ulTaskNotifyValueClear() is the original API function, and remains backward compatible
by always operating on the notification value at index 0 within the array. Calling ulTaskNotifyValueClear() is
equivalent to calling ulTaskNotifyValueClearIndexed() with the uxIndexToClear parameter set to 0.
Return The value of the target task s notification value before the bits specified by ulBitsToClear were
cleared.
Parameters
• xTask: The handle of the RTOS task that will have bits in one of its notification values cleared.
Set xTask to NULL to clear bits in a notification value of the calling task. To obtain a task s handle
create the task using xTaskCreate() and make use of the pxCreatedTask parameter, or create the

task using xTaskCreateStatic() and store the returned value, or use the task s name in a call to
xTaskGetHandle().
• uxIndexToClear: The index within the target task s array of notification values in which to clear
the bits. uxIndexToClear must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.
ulTaskNotifyValueClear() does not have this parameter and always clears bits in the notification
value at index 0.
• ulBitsToClear: Bit mask of the bits to clear in the notification value of xTask. Set a bit to
1 to clear the corresponding bits in the task s notification value. Set ulBitsToClear to 0xffffffff
(UINT_MAX on 32-bit architectures) to clear the notification value to 0. Set ulBitsToClear to 0 to
query the task s notification value without clearing any bits.
void vTaskSetTimeOutState(TimeOut_t *const pxTimeOut)
BaseType_t xTaskCheckForTimeOut(TimeOut_t *const pxTimeOut, TickType_t *const pxTick-
sToWait)
Determines if pxTicksToWait ticks has passed since a time was captured using a call to vTaskSetTimeOut-
State(). The captured time includes the tick count and the number of times the tick count has overflowed.
Example Usage:
// Driver library function used to receive uxWantedBytes from an Rx buffer
// that is filled by a UART interrupt. If there are not enough bytes in the
// Rx buffer then the task enters the Blocked state until it is notified that
// more data has been placed into the buffer. If there is still not enough
// data then the task re-enters the Blocked state, and xTaskCheckForTimeOut()
// is used to re-calculate the Block time to ensure the total amount of time
// spent in the Blocked state does not exceed MAX_TIME_TO_WAIT. This
// continues until either the buffer contains at least uxWantedBytes bytes,
// or the total amount of time spent in the Blocked state reaches
// MAX_TIME_TO_WAIT at which point the task reads however many bytes are
// available up to a maximum of uxWantedBytes.
size_t xUART_Receive( uint8_t *pucBuffer, size_t uxWantedBytes )

{
size_t uxReceived = 0;
TickType_t xTicksToWait = MAX_TIME_TO_WAIT;
TimeOut_t xTimeOut;
// Initialize xTimeOut. This records the time at which this function

// was entered.
vTaskSetTimeOutState( &xTimeOut );
// Loop until the buffer contains the wanted number of bytes, or a

// timeout occurs.
while( UART_bytes_in_rx_buffer( pxUARTInstance ) < uxWantedBytes )
{
// The buffer didn't contain enough data so this task is going to
// enter the Blocked state. Adjusting xTicksToWait to account for
// any time that has been spent in the Blocked state within this
// function so far to ensure the total amount of time spent in the
// Blocked state does not exceed MAX_TIME_TO_WAIT.
if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) != pdFALSE )
{
//Timed out before the wanted number of bytes were available,
// exit the loop.
break;
}
// Wait for a maximum of xTicksToWait ticks to be notified that the

// receive interrupt has placed more data into the buffer.
ulTaskNotifyTake( pdTRUE, xTicksToWait );
}


// Attempt to read uxWantedBytes from the receive buffer into pucBuffer.
// The actual number of bytes read (which might be less than
// uxWantedBytes) is returned.
uxReceived = UART_read_from_receive_buffer( pxUARTInstance,
pucBuffer,
uxWantedBytes );
return uxReceived;
}
Return If timeout has occurred, pdTRUE is returned. Otherwise pdFALSE is returned and pxTicksToWait
is updated to reflect the number of remaining ticks.
See https://www.FreeRTOS.org/xTaskCheckForTimeOut.html
Parameters
• pxTimeOut: The time status as captured previously using vTaskSetTimeOutState. If the timeout
has not yet occurred, it is updated to reflect the current time status.
• pxTicksToWait: The number of ticks to check for timeout i.e. if pxTicksToWait ticks have
passed since pxTimeOut was last updated (either by vTaskSetTimeOutState() or xTaskCheckFor-
TimeOut()), the timeout has occurred. If the timeout has not occurred, pxTicksToWait is updated
to reflect the number of remaining ticks.
BaseType_t xTaskCatchUpTicks(TickType_t xTicksToCatchUp)
Macros
tskKERNEL_VERSION_NUMBER
tskKERNEL_VERSION_MAJOR
tskKERNEL_VERSION_MINOR
tskKERNEL_VERSION_BUILD
tskMPU_REGION_READ_ONLY
tskMPU_REGION_READ_WRITE
tskMPU_REGION_EXECUTE_NEVER
tskMPU_REGION_NORMAL_MEMORY
tskMPU_REGION_DEVICE_MEMORY
tskDEFAULT_INDEX_TO_NOTIFY
tskNO_AFFINITY
tskIDLE_PRIORITY
Defines the priority used by the idle task. This must not be modified.
taskYIELD()
Macro for forcing a context switch.
taskENTER_CRITICAL()
Macro to mark the start of a critical code region. Preemptive context switches cannot occur when in a critical
region.
Note This may alter the stack (depending on the portable implementation) so must be used with care!
taskENTER_CRITICAL_FROM_ISR()
taskENTER_CRITICAL_ISR()
taskEXIT_CRITICAL()
Macro to mark the end of a critical code region. Preemptive context switches cannot occur when in a critical
region.
Note This may alter the stack (depending on the portable implementation) so must be used with care!

taskEXIT_CRITICAL_FROM_ISR(x)
taskEXIT_CRITICAL_ISR()
taskDISABLE_INTERRUPTS()
Macro to disable all maskable interrupts.
taskENABLE_INTERRUPTS()
Macro to enable microcontroller interrupts.
taskSCHEDULER_SUSPENDED
taskSCHEDULER_NOT_STARTED
taskSCHEDULER_RUNNING
vTaskDelayUntil(pxPreviousWakeTime, xTimeIncrement)
xTaskNotify(xTaskToNotify, ulValue, eAction)
xTaskNotifyIndexed(xTaskToNotify, uxIndexToNotify, ulValue, eAction)
xTaskNotifyAndQuery(xTaskToNotify, ulValue, eAction, pulPreviousNotifyValue)
xTaskNotifyAndQueryIndexed() performs the same operation as xTaskNotifyIndexed() with the addition that
it also returns the subject task s prior notification value (the notification value at the time the function is called
rather than when the function returns) in the additional pulPreviousNotifyValue parameter.
xTaskNotifyAndQuery() performs the same operation as xTaskNotify() with the addition that it also returns
the subject task s prior notification value (the notification value as it was at the time the function is called,
rather than when the function returns) in the additional pulPreviousNotifyValue parameter.
xTaskNotifyAndQueryIndexed(xTaskToNotify, uxIndexToNotify, ulValue, eAction, pulPrevious-
NotifyValue)
xTaskNotifyFromISR(xTaskToNotify, ulValue, eAction, pxHigherPriorityTaskWoken)
xTaskNotifyIndexedFromISR(xTaskToNotify, uxIndexToNotify, ulValue, eAction, pxHigherPriori-
tyTaskWoken)
xTaskNotifyAndQueryIndexedFromISR(xTaskToNotify, uxIndexToNotify, ulValue, eAction,
pulPreviousNotificationValue, pxHigherPriorityTaskWo-
ken)
xTaskNotifyAndQueryIndexedFromISR() performs the same operation as xTaskNotifyIndexedFromISR()
with the addition that it also returns the subject task s prior notification value (the notification value at the
time the function is called rather than at the time the function returns) in the additional pulPreviousNotifyValue
parameter.
xTaskNotifyAndQueryFromISR() performs the same operation as xTaskNotifyFromISR() with the addition
that it also returns the subject task s prior notification value (the notification value at the time the function is
called rather than at the time the function returns) in the additional pulPreviousNotifyValue parameter.
xTaskNotifyAndQueryFromISR(xTaskToNotify, ulValue, eAction, pulPreviousNotificationValue,
pxHigherPriorityTaskWoken)
xTaskNotifyWait(ulBitsToClearOnEntry, ulBitsToClearOnExit, pulNotificationValue, xTicksToWait)
xTaskNotifyWaitIndexed(uxIndexToWaitOn, ulBitsToClearOnEntry, ulBitsToClearOnExit, pulNo-
tificationValue, xTicksToWait)
xTaskNotifyGive(xTaskToNotify)
Sends a direct to task notification to a particular index in the target task s notification array in a manner similar
to giving a counting semaphore.
See https://www.FreeRTOS.org/RTOS-task-notifications.html for more details.
configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these macros to be available.

xTaskNotifyGiveIndexed() is a helper macro intended for use when task notifications are used as light weight
and faster binary or counting semaphore equivalents. Actual FreeRTOS semaphores are given using the
xSemaphoreGive() API function, the equivalent action that instead uses a task notification is xTaskNotify-
GiveIndexed().
When task notifications are being used as a binary or counting semaphore equivalent then the task being no-
tified should wait for the notification using the ulTaskNotificationTakeIndexed() API function rather than the
xTaskNotifyWaitIndexed() API function.
within the array. xTaskNotifyGive() is the original API function, and remains backward compatible by always
operating on the notification value at index 0 in the array. Calling xTaskNotifyGive() is equivalent to calling
xTaskNotifyGiveIndexed() with the uxIndexToNotify parameter set to 0.
Return xTaskNotifyGive() is a macro that calls xTaskNotify() with the eAction parameter set to eIncrement
- so pdPASS is always returned.
Parameters
TASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyGive() does not have this parameter
and always sends notifications to index 0.
xTaskNotifyGiveIndexed(xTaskToNotify, uxIndexToNotify)
vTaskNotifyGiveFromISR(xTaskToNotify, pxHigherPriorityTaskWoken)
vTaskNotifyGiveIndexedFromISR(xTaskToNotify, uxIndexToNotify, pxHigherPriorityTaskWo-
ken)
ulTaskNotifyTake(xClearCountOnExit, xTicksToWait)
ulTaskNotifyTakeIndexed(uxIndexToWaitOn, xClearCountOnExit, xTicksToWait)
xTaskNotifyStateClear(xTask)
xTaskNotifyStateClearIndexed(xTask, uxIndexToClear)
ulTaskNotifyValueClear(xTask, ulBitsToClear)
ulTaskNotifyValueClearIndexed(xTask, uxIndexToClear, ulBitsToClear)
Type Definitions
typedef struct tskTaskControlBlock *TaskHandle_t
typedef BaseType_t (*TaskHookFunction_t)(void *)
Defines the prototype to which the application task hook function must conform.

typedef void (*TlsDeleteCallbackFunction_t)(int, void *)

Prototype of local storage pointer deletion callback.
Enumerations
enum eTaskState
Task states returned by eTaskGetState.
Values:
eRunning = 0
eReady
eBlocked
eSuspended
eDeleted
eInvalid
enum eNotifyAction
Values:
eNoAction = 0
eSetBits
eIncrement
eSetValueWithOverwrite
eSetValueWithoutOverwrite
enum eSleepModeStatus
Possible return values for eTaskConfirmSleepModeStatus().
Values:
eAbortSleep = 0
eStandardSleep
eNoTasksWaitingTimeout
Queue API
Header File
• components/freertos/FreeRTOS-Kernel/include/freertos/queue.h
Functions
BaseType_t xQueueGenericSend(QueueHandle_t xQueue, const void *const pvItemToQueue, Tick-
Type_t xTicksToWait, const BaseType_t xCopyPosition)
It is preferred that the macros xQueueSend(), xQueueSendToFront() and xQueueSendToBack() are used in
place of calling this function directly.
Post an item on a queue. The item is queued by copy, not by reference. This function must not be called from
an interrupt service routine. See xQueueSendFromISR () for an alternative which may be used in an ISR.
Example usage:
struct AMessage
{
char ucMessageID;
char ucData[ 20 ];
} xMessage;

uint32_t ulVar = 10UL;

{
QueueHandle_t xQueue1, xQueue2;
struct AMessage *pxMessage;
// Create a queue capable of containing 10 uint32_t values.

xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) );
// Create a queue capable of containing 10 pointers to AMessage structures.

// These should be passed by pointer as they contain a lot of data.
xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
// ...
if( xQueue1 != 0 )
{
// Send an uint32_t. Wait for 10 ticks for space to become
// available if necessary.
if( xQueueGenericSend( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10,␣
,→queueSEND_TO_BACK ) != pdPASS )
{
// Failed to post the message, even after 10 ticks.
}
}
if( xQueue2 != 0 )
{
// Send a pointer to a struct AMessage object. Don't block if the
// queue is already full.
pxMessage = & xMessage;
xQueueGenericSend( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0,␣
,→queueSEND_TO_BACK );
// ... Rest of task code.

}
Return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.

Parameters
• xQueue: The handle to the queue on which the item is to be posted.
• pvItemToQueue: A pointer to the item that is to be placed on the queue. The size of the items
the queue will hold was defined when the queue was created, so this many bytes will be copied from
pvItemToQueue into the queue storage area.
• xTicksToWait: The maximum amount of time the task should block waiting for space to become
available on the queue, should it already be full. The call will return immediately if this is set to 0
and the queue is full. The time is defined in tick periods so the constant portTICK_PERIOD_MS
should be used to convert to real time if this is required.
• xCopyPosition: Can take the value queueSEND_TO_BACK to place the item at the back of
the queue, or queueSEND_TO_FRONT to place the item at the front of the queue (for high priority
messages).
BaseType_t xQueuePeek(QueueHandle_t xQueue, void *const pvBuffer, TickType_t xTicksToWait)
Receive an item from a queue without removing the item from the queue. The item is received by copy so a
buffer of adequate size must be provided. The number of bytes copied into the buffer was defined when the
queue was created.
Successfully received items remain on the queue so will be returned again by the next call, or a call to
xQueueReceive().

This macro must not be used in an interrupt service routine. See xQueuePeekFromISR() for an alternative that
can be called from an interrupt service routine.
Example usage:
struct AMessage
{
char ucMessageID;
char ucData[ 20 ];
} xMessage;
QueueHandle_t xQueue;
// Task to create a queue and post a value.

{

xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );
if( xQueue == 0 )
{
// Failed to create the queue.
}
// ...

xQueueSend( xQueue, ( void * ) &pxMessage, ( TickType_t ) 0 );

}
// Task to peek the data from the queue.

void vADifferentTask( void *pvParameters )
{
struct AMessage *pxRxedMessage;
if( xQueue != 0 )
{
// Peek a message on the created queue. Block for 10 ticks if a
// message is not immediately available.
if( xQueuePeek( xQueue, &( pxRxedMessage ), ( TickType_t ) 10 ) )
{
// pcRxedMessage now points to the struct AMessage variable posted
// by vATask, but the item still remains on the queue.
}
}

}
Return pdTRUE if an item was successfully received from the queue, otherwise pdFALSE.
Parameters
• xQueue: The handle to the queue from which the item is to be received.
• pvBuffer: Pointer to the buffer into which the received item will be copied.
• xTicksToWait: The maximum amount of time the task should block waiting for an item to
receive should the queue be empty at the time of the call. The time is defined in tick periods so
the constant portTICK_PERIOD_MS should be used to convert to real time if this is required.
xQueuePeek() will return immediately if xTicksToWait is 0 and the queue is empty.

BaseType_t xQueuePeekFromISR(QueueHandle_t xQueue, void *const pvBuffer)

A version of xQueuePeek() that can be called from an interrupt service routine (ISR).
Receive an item from a queue without removing the item from the queue. The item is received by copy so a
buffer of adequate size must be provided. The number of bytes copied into the buffer was defined when the
queue was created.
Successfully received items remain on the queue so will be returned again by the next call, or a call to
xQueueReceive().
Parameters
BaseType_t xQueueReceive(QueueHandle_t xQueue, void *const pvBuffer, TickType_t xTicksToWait)
Receive an item from a queue. The item is received by copy so a buffer of adequate size must be provided.
The number of bytes copied into the buffer was defined when the queue was created.
Successfully received items are removed from the queue.
This function must not be used in an interrupt service routine. See xQueueReceiveFromISR for an alternative
that can.
Example usage:
struct AMessage
{
char ucMessageID;
char ucData[ 20 ];
} xMessage;
// Task to create a queue and post a value.

{

xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );
if( xQueue == 0 )
{
}
// ...

xQueueSend( xQueue, ( void * ) &pxMessage, ( TickType_t ) 0 );

}
// Task to receive from the queue.

void vADifferentTask( void *pvParameters )
{
struct AMessage *pxRxedMessage;
if( xQueue != 0 )
{


// Receive a message on the created queue. Block for 10 ticks if a
// message is not immediately available.
if( xQueueReceive( xQueue, &( pxRxedMessage ), ( TickType_t ) 10 ) )
{
// pcRxedMessage now points to the struct AMessage variable posted
// by vATask.
}
}

}
Parameters
• xTicksToWait: The maximum amount of time the task should block waiting for an item to
receive should the queue be empty at the time of the call. xQueueReceive() will return immediately
if xTicksToWait is zero and the queue is empty. The time is defined in tick periods so the constant
portTICK_PERIOD_MS should be used to convert to real time if this is required.
UBaseType_t uxQueueMessagesWaiting(const QueueHandle_t xQueue)
Return the number of messages stored in a queue.
Return The number of messages available in the queue.
Parameters
• xQueue: A handle to the queue being queried.
UBaseType_t uxQueueSpacesAvailable(const QueueHandle_t xQueue)
Return the number of free spaces available in a queue. This is equal to the number of items that can be sent to
the queue before the queue becomes full if no items are removed.
Return The number of spaces available in the queue.
Parameters
• xQueue: A handle to the queue being queried.
void vQueueDelete(QueueHandle_t xQueue)
Delete a queue - freeing all the memory allocated for storing of items placed on the queue.
Parameters
• xQueue: A handle to the queue to be deleted.
BaseType_t xQueueGenericSendFromISR(QueueHandle_t xQueue, const void *const pvItemTo-
Queue, BaseType_t *const pxHigherPriorityTaskWoken,
const BaseType_t xCopyPosition)
It is preferred that the macros xQueueSendFromISR(), xQueueSendToFrontFromISR() and xQueueSendTo-
BackFromISR() be used in place of calling this function directly. xQueueGiveFromISR() is an equivalent for
use by semaphores that don t actually copy any data.
Post an item on a queue. It is safe to use this function from within an interrupt service routine.
Items are queued by copy not reference so it is preferable to only queue small items, especially when called
from an ISR. In most cases it would be preferable to store a pointer to the item being queued.
Example usage for buffered IO (where the ISR can obtain more than one value per call):
void vBufferISR( void )

{
char cIn;
BaseType_t xHigherPriorityTaskWokenByPost;
// We have not woken a task at the start of the ISR.

xHigherPriorityTaskWokenByPost = pdFALSE;

// Loop until the buffer is empty.

do
{
// Obtain a byte from the buffer.
cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );
// Post each byte.

xQueueGenericSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWokenByPost,
,→ queueSEND_TO_BACK );
} while( portINPUT_BYTE( BUFFER_COUNT ) );
// Now the buffer is empty we can switch context if necessary. Note that the
// name of the yield function required is port specific.
if( xHigherPriorityTaskWokenByPost )
{
taskYIELD_YIELD_FROM_ISR();
}
}
Return pdTRUE if the data was successfully sent to the queue, otherwise errQUEUE_FULL.
Parameters
• [out] pxHigherPriorityTaskWoken: xQueueGenericSendFromISR() will set *pxHigh-
erPriorityTaskWoken to pdTRUE if sending to the queue caused a task to unblock, and the un-
blocked task has a priority higher than the currently running task. If xQueueGenericSendFromISR()
sets this value to pdTRUE then a context switch should be requested before the interrupt is exited.
• xCopyPosition: Can take the value queueSEND_TO_BACK to place the item at the back of
the queue, or queueSEND_TO_FRONT to place the item at the front of the queue (for high priority
messages).
BaseType_t xQueueGiveFromISR(QueueHandle_t xQueue, BaseType_t *const pxHigherPriority-
TaskWoken)
BaseType_t xQueueReceiveFromISR(QueueHandle_t xQueue, void *const pvBuffer, BaseType_t
*const pxHigherPriorityTaskWoken)
Receive an item from a queue. It is safe to use this function from within an interrupt service routine.
Example usage:
// Function to create a queue and post some values.

void vAFunction( void *pvParameters )
{
char cValueToPost;
const TickType_t xTicksToWait = ( TickType_t )0xff;
// Create a queue capable of containing 10 characters.

xQueue = xQueueCreate( 10, sizeof( char ) );
if( xQueue == 0 )
{
}
// ...


// Post some characters that will be used within an ISR. If the queue
// is full then this task will block for xTicksToWait ticks.
cValueToPost = 'a';
xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait );
cValueToPost = 'b';
// ... keep posting characters ... this task may block when the queue
// becomes full.
cValueToPost = 'c';
}
// ISR that outputs all the characters received on the queue.

void vISR_Routine( void )
{
BaseType_t xTaskWokenByReceive = pdFALSE;
char cRxedChar;
while( xQueueReceiveFromISR( xQueue, ( void * ) &cRxedChar, &

,→ xTaskWokenByReceive) )
{
// A character was received. Output the character now.
vOutputCharacter( cRxedChar );
// If removing the character from the queue woke the task that was
// posting onto the queue cTaskWokenByReceive will have been set to
// pdTRUE. No matter how many times this loop iterates only one
// task will be woken.
}
if( cTaskWokenByPost != ( char ) pdFALSE;

{
taskYIELD ();
}
}
Parameters
• [out] pxHigherPriorityTaskWoken: A task may be blocked waiting for space to become
available on the queue. If xQueueReceiveFromISR causes such a task to unblock *pxTaskWoken
will get set to pdTRUE, otherwise *pxTaskWoken will remain unchanged.
BaseType_t xQueueIsQueueEmptyFromISR(const QueueHandle_t xQueue)
BaseType_t xQueueIsQueueFullFromISR(const QueueHandle_t xQueue)
UBaseType_t uxQueueMessagesWaitingFromISR(const QueueHandle_t xQueue)
void vQueueAddToRegistry(QueueHandle_t xQueue, const char *pcQueueName)
The registry is provided as a means for kernel aware debuggers to locate queues, semaphores and mutexes. Call
vQueueAddToRegistry() add a queue, semaphore or mutex handle to the registry if you want the handle to be
available to a kernel aware debugger. If you are not using a kernel aware debugger then this function can be
ignored.
configQUEUE_REGISTRY_SIZE defines the maximum number of handles the registry can hold. con-
figQUEUE_REGISTRY_SIZE must be greater than 0 within FreeRTOSConfig.h for the registry to be avail-
able. Its value does not effect the number of queues, semaphores and mutexes that can be created - just the
number that the registry can hold.

Parameters
• xQueue: The handle of the queue being added to the registry. This is the handle returned by a call
to xQueueCreate(). Semaphore and mutex handles can also be passed in here.
• pcQueueName: The name to be associated with the handle. This is the name that the kernel aware
debugger will display. The queue registry only stores a pointer to the string - so the string must be
persistent (global or preferably in ROM/Flash), not on the stack.
void vQueueUnregisterQueue(QueueHandle_t xQueue)
The registry is provided as a means for kernel aware debuggers to locate queues, semaphores and mutexes.
Call vQueueAddToRegistry() add a queue, semaphore or mutex handle to the registry if you want the handle
to be available to a kernel aware debugger, and vQueueUnregisterQueue() to remove the queue, semaphore or
mutex from the register. If you are not using a kernel aware debugger then this function can be ignored.
Parameters
• xQueue: The handle of the queue being removed from the registry.
const char *pcQueueGetName(QueueHandle_t xQueue)
The queue registry is provided as a means for kernel aware debuggers to locate queues, semaphores and mutexes.
Call pcQueueGetName() to look up and return the name of a queue in the queue registry from the queue s
handle.
Return If the queue is in the registry then a pointer to the name of the queue is returned. If the queue is not
in the registry then NULL is returned.
Parameters
• xQueue: The handle of the queue the name of which will be returned.
QueueHandle_t xQueueGenericCreate(const UBaseType_t uxQueueLength, const UBaseType_t
uxItemSize, const uint8_t ucQueueType)
Generic version of the function used to create a queue using dynamic memory allocation. This is called by
other functions and macros that create other RTOS objects that use the queue structure as their base.
QueueHandle_t xQueueGenericCreateStatic(const UBaseType_t uxQueueLength, const
UBaseType_t uxItemSize, uint8_t *pucQueueStorage,
StaticQueue_t *pxStaticQueue, const uint8_t
ucQueueType)
Generic version of the function used to create a queue using dynamic memory allocation. This is called by
other functions and macros that create other RTOS objects that use the queue structure as their base.
QueueSetHandle_t xQueueCreateSet(const UBaseType_t uxEventQueueLength)
Queue sets provide a mechanism to allow a task to block (pend) on a read operation from multiple queues or
semaphores simultaneously.
See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this function.
A queue set must be explicitly created using a call to xQueueCreateSet() before it can be used. Once cre-
ated, standard FreeRTOS queues and semaphores can be added to the set using calls to xQueueAddToSet().
xQueueSelectFromSet() is then used to determine which, if any, of the queues or semaphores contained in the
set is in a state where a queue read or semaphore take operation would be successful.
Note 1: See the documentation on https://www.FreeRTOS.org/RTOS-queue-sets.html for reasons why queue
sets are very rarely needed in practice as there are simpler methods of blocking on multiple objects.
Note 2: Blocking on a queue set that contains a mutex will not cause the mutex holder to inherit the priority
of the blocked task.
Note 3: An additional 4 bytes of RAM is required for each space in a every queue added to a queue set.
Therefore counting semaphores that have a high maximum count value should not be added to a queue set.
Note 4: A receive (in the case of a queue) or take (in the case of a semaphore) operation must not be performed
on a member of a queue set unless a call to xQueueSelectFromSet() has first returned a handle to that set
member.
Return If the queue set is created successfully then a handle to the created queue set is returned. Otherwise
NULL is returned.
Parameters

• uxEventQueueLength: Queue sets store events that occur on the queues and semaphores con-
tained in the set. uxEventQueueLength specifies the maximum number of events that can be queued
at once. To be absolutely certain that events are not lost uxEventQueueLength should be set to the
total sum of the length of the queues added to the set, where binary semaphores and mutexes have
a length of 1, and counting semaphores have a length set by their maximum count value. Examples:
– If a queue set is to hold a queue of length 5, another queue of length 12, and a binary semaphore,
then uxEventQueueLength should be set to (5 + 12 + 1), or 18.
– If a queue set is to hold three binary semaphores then uxEventQueueLength should be set to (1
+ 1 + 1 ), or 3.
– If a queue set is to hold a counting semaphore that has a maximum count of 5, and a counting
semaphore that has a maximum count of 3, then uxEventQueueLength should be set to (5 + 3),
or 8.
BaseType_t xQueueAddToSet(QueueSetMemberHandle_t xQueueOrSemaphore, QueueSetHandle_t
xQueueSet)
Adds a queue or semaphore to a queue set that was previously created by a call to xQueueCreateSet().
member.
Return If the queue or semaphore was successfully added to the queue set then pdPASS is returned. If the
queue could not be successfully added to the queue set because it is already a member of a different queue
set then pdFAIL is returned.
Parameters
• xQueueOrSemaphore: The handle of the queue or semaphore being added to the queue set (cast
to an QueueSetMemberHandle_t type).
• xQueueSet: The handle of the queue set to which the queue or semaphore is being added.
BaseType_t xQueueRemoveFromSet(QueueSetMemberHandle_t xQueueOrSemaphore, Queue-
SetHandle_t xQueueSet)
Removes a queue or semaphore from a queue set. A queue or semaphore can only be removed from a set if
the queue or semaphore is empty.
Return If the queue or semaphore was successfully removed from the queue set then pdPASS is returned. If
the queue was not in the queue set, or the queue (or semaphore) was not empty, then pdFAIL is returned.
Parameters
• xQueueOrSemaphore: The handle of the queue or semaphore being removed from the queue
set (cast to an QueueSetMemberHandle_t type).
• xQueueSet: The handle of the queue set in which the queue or semaphore is included.
QueueSetMemberHandle_t xQueueSelectFromSet(QueueSetHandle_t xQueueSet, const TickType_t
xTicksToWait)
xQueueSelectFromSet() selects from the members of a queue set a queue or semaphore that either contains
data (in the case of a queue) or is available to take (in the case of a semaphore). xQueueSelectFromSet()
effectively allows a task to block (pend) on a read operation on all the queues and semaphores in a queue set
simultaneously.
Note 1: See the documentation on https://www.FreeRTOS.org/RTOS-queue-sets.html for reasons why queue
sets are very rarely needed in practice as there are simpler methods of blocking on multiple objects.
Note 2: Blocking on a queue set that contains a mutex will not cause the mutex holder to inherit the priority
of the blocked task.
member.

Return xQueueSelectFromSet() will return the handle of a queue (cast to a QueueSetMemberHandle_t type)
contained in the queue set that contains data, or the handle of a semaphore (cast to a QueueSetMem-
berHandle_t type) contained in the queue set that is available, or NULL if no such queue or semaphore
exists before before the specified block time expires.
Parameters
• xQueueSet: The queue set on which the task will (potentially) block.
• xTicksToWait: The maximum time, in ticks, that the calling task will remain in the Blocked
state (with other tasks executing) to wait for a member of the queue set to be ready for a successful
queue read or semaphore take operation.
QueueSetMemberHandle_t xQueueSelectFromSetFromISR(QueueSetHandle_t xQueueSet)
A version of xQueueSelectFromSet() that can be used from an ISR.
Macros
xQueueCreate(uxQueueLength, uxItemSize)
Creates a new queue instance, and returns a handle by which the new queue can be referenced.
Internally, within the FreeRTOS implementation, queues use two blocks of memory. The first block is used
to hold the queue s data structures. The second block is used to hold items placed into the queue. If a queue
is created using xQueueCreate() then both blocks of memory are automatically dynamically allocated inside
the xQueueCreate() function. (see https://www.FreeRTOS.org/a00111.html). If a queue is created using
xQueueCreateStatic() then the application writer must provide the memory that will get used by the queue.
xQueueCreateStatic() therefore allows a queue to be created without using any dynamic memory allocation.
https://www.FreeRTOS.org/Embedded-RTOS-Queues.html
Example usage:
struct AMessage
{
char ucMessageID;
char ucData[ 20 ];
};

{

if( xQueue1 == 0 )
{
// Queue was not created and must not be used.
}

if( xQueue2 == 0 )
{
// Queue was not created and must not be used.
}

}
Return If the queue is successfully create then a handle to the newly created queue is returned. If the queue
cannot be created then 0 is returned.
Parameters
• uxQueueLength: The maximum number of items that the queue can contain.
• uxItemSize: The number of bytes each item in the queue will require. Items are queued by copy,
not by reference, so this is the number of bytes that will be copied for each posted item. Each item

on the queue must be the same size.

xQueueCreateStatic(uxQueueLength, uxItemSize, pucQueueStorage, pxQueueBuffer)
Creates a new queue instance, and returns a handle by which the new queue can be referenced.
Internally, within the FreeRTOS implementation, queues use two blocks of memory. The first block is used
to hold the queue s data structures. The second block is used to hold items placed into the queue. If a queue
is created using xQueueCreate() then both blocks of memory are automatically dynamically allocated inside
the xQueueCreate() function. (see https://www.FreeRTOS.org/a00111.html). If a queue is created using
xQueueCreateStatic() then the application writer must provide the memory that will get used by the queue.
xQueueCreateStatic() therefore allows a queue to be created without using any dynamic memory allocation.
https://www.FreeRTOS.org/Embedded-RTOS-Queues.html
Example usage:
struct AMessage
{
char ucMessageID;
char ucData[ 20 ];
};
#define QUEUE_LENGTH 10
#define ITEM_SIZE sizeof( uint32_t )
// xQueueBuffer will hold the queue structure.

StaticQueue_t xQueueBuffer;
// ucQueueStorage will hold the items posted to the queue. Must be at least
// [(queue length) * ( queue item size)] bytes long.
uint8_t ucQueueStorage[ QUEUE_LENGTH * ITEM_SIZE ];

{
QueueHandle_t xQueue1;

xQueue1 = xQueueCreate( QUEUE_LENGTH, // The number of items the queue can␣
,→hold.
ITEM_SIZE // The size of each item in the queue

&( ucQueueStorage[ 0 ] ), // The buffer that will␣
,→hold the items in the queue.
&xQueueBuffer ); // The buffer that will hold the␣

,→queue structure.
// The queue is guaranteed to be created successfully as no dynamic memory

// allocation is used. Therefore xQueue1 is now a handle to a valid queue.

}
Return If the queue is created then a handle to the created queue is returned. If pxQueueBuffer is NULL
then NULL is returned.
Parameters
• uxQueueLength: The maximum number of items that the queue can contain.
• uxItemSize: The number of bytes each item in the queue will require. Items are queued by copy,
not by reference, so this is the number of bytes that will be copied for each posted item. Each item
on the queue must be the same size.
• pucQueueStorage: If uxItemSize is not zero then pucQueueStorageBuffer must point to a
uint8_t array that is at least large enough to hold the maximum number of items that can be in
the queue at any one time - which is ( uxQueueLength * uxItemsSize ) bytes. If uxItemSize is zero
then pucQueueStorageBuffer can be NULL.
• pxQueueBuffer: Must point to a variable of type StaticQueue_t, which will be used to hold the
queue s data structure.

xQueueSendToFront(xQueue, pvItemToQueue, xTicksToWait)

Post an item to the front of a queue. The item is queued by copy, not by reference. This function must not be
called from an interrupt service routine. See xQueueSendFromISR () for an alternative which may be used in
an ISR.
Example usage:
struct AMessage
{
char ucMessageID;
char ucData[ 20 ];
} xMessage;

{


// ...
if( xQueue1 != 0 )
{
if( xQueueSendToFront( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10 ) !=␣
,→pdPASS )
{
}
}
if( xQueue2 != 0 )
{
xQueueSendToFront( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0 );
}

}

Parameters
xQueueSendToBack(xQueue, pvItemToQueue, xTicksToWait)

This is a macro that calls xQueueGenericSend().

Post an item to the back of a queue. The item is queued by copy, not by reference. This function must not be
called from an interrupt service routine. See xQueueSendFromISR () for an alternative which may be used in
an ISR.
Example usage:
struct AMessage
{
char ucMessageID;
char ucData[ 20 ];
} xMessage;

{


// ...
if( xQueue1 != 0 )
{
if( xQueueSendToBack( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10 ) !=␣
,→pdPASS )
{
}
}
if( xQueue2 != 0 )
{
xQueueSendToBack( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0 );
}

}

Parameters

xQueueSend(xQueue, pvItemToQueue, xTicksToWait)

This is a macro that calls xQueueGenericSend(). It is included for backward compatibility with versions of
FreeRTOS.org that did not include the xQueueSendToFront() and xQueueSendToBack() macros. It is equiv-
alent to xQueueSendToBack().
Post an item on a queue. The item is queued by copy, not by reference. This function must not be called from
an interrupt service routine. See xQueueSendFromISR () for an alternative which may be used in an ISR.
Example usage:
struct AMessage
{
char ucMessageID;
char ucData[ 20 ];
} xMessage;

{


// ...
if( xQueue1 != 0 )
{
if( xQueueSend( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10 ) != pdPASS␣
,→)
{
}
}
if( xQueue2 != 0 )
{
xQueueSend( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0 );
}

}

Parameters


xQueueOverwrite(xQueue, pvItemToQueue)
Only for use with queues that have a length of one - so the queue is either empty or full.
Post an item on a queue. If the queue is already full then overwrite the value held in the queue. The item is
queued by copy, not by reference.
This function must not be called from an interrupt service routine. See xQueueOverwriteFromISR () for an
alternative which may be used in an ISR.
Example usage:
void vFunction( void *pvParameters )

{
uint32_t ulVarToSend, ulValReceived;
// Create a queue to hold one uint32_t value. It is strongly

// recommended *not* to use xQueueOverwrite() on queues that can
// contain more than one value, and doing so will trigger an assertion
// if configASSERT() is defined.
xQueue = xQueueCreate( 1, sizeof( uint32_t ) );
// Write the value 10 to the queue using xQueueOverwrite().

ulVarToSend = 10;
xQueueOverwrite( xQueue, &ulVarToSend );
// Peeking the queue should now return 10, but leave the value 10 in
// the queue. A block time of zero is used as it is known that the
// queue holds a value.
ulValReceived = 0;
xQueuePeek( xQueue, &ulValReceived, 0 );
if( ulValReceived != 10 )
{
// Error unless the item was removed by a different task.
}
// The queue is still full. Use xQueueOverwrite() to overwrite the

// value held in the queue with 100.
ulVarToSend = 100;
xQueueOverwrite( xQueue, &ulVarToSend );
// This time read from the queue, leaving the queue empty once more.
// A block time of 0 is used again.
xQueueReceive( xQueue, &ulValReceived, 0 );
// The value read should be the last value written, even though the
// queue was already full when the value was written.
if( ulValReceived != 100 )
{
// Error!
}
// ...
}
Return xQueueOverwrite() is a macro that calls xQueueGenericSend(), and therefore has the same return
values as xQueueSendToFront(). However, pdPASS is the only value that can be returned because
xQueueOverwrite() will write to the queue even when the queue is already full.
Parameters
• xQueue: The handle of the queue to which the data is being sent.

xQueueSendToFrontFromISR(xQueue, pvItemToQueue, pxHigherPriorityTaskWoken)
This is a macro that calls xQueueGenericSendFromISR().
Post an item to the front of a queue. It is safe to use this macro from within an interrupt service routine.

{
char cIn;
BaseType_t xHigherPrioritTaskWoken;

xHigherPriorityTaskWoken = pdFALSE;

do
{
// Post the byte.

xQueueSendToFrontFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );
// Now the buffer is empty we can switch context if necessary.

if( xHigherPriorityTaskWoken )
{
portYIELD_FROM_ISR ();
}
}
Parameters
• [out] pxHigherPriorityTaskWoken: xQueueSendToFrontFromISR() will set *pxHigh-
blocked task has a priority higher than the currently running task. If xQueueSendToFromFromISR()
xQueueSendToBackFromISR(xQueue, pvItemToQueue, pxHigherPriorityTaskWoken)
This is a macro that calls xQueueGenericSendFromISR().
Post an item to the back of a queue. It is safe to use this macro from within an interrupt service routine.

{
char cIn;
BaseType_t xHigherPriorityTaskWoken;



do
{
// Post the byte.

xQueueSendToBackFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );

{
}
}
Parameters
• [out] pxHigherPriorityTaskWoken: xQueueSendToBackFromISR() will set *pxHigh-
blocked task has a priority higher than the currently running task. If xQueueSendToBackFromISR()
xQueueOverwriteFromISR(xQueue, pvItemToQueue, pxHigherPriorityTaskWoken)
A version of xQueueOverwrite() that can be used in an interrupt service routine (ISR).
Only for use with queues that can hold a single item - so the queue is either empty or full.
Post an item on a queue. If the queue is already full then overwrite the value held in the queue. The item is
queued by copy, not by reference.
Example usage:
void vFunction( void *pvParameters )

{
// Create a queue to hold one uint32_t value. It is strongly
// recommended *not* to use xQueueOverwriteFromISR() on queues that can
// contain more than one value, and doing so will trigger an assertion
// if configASSERT() is defined.
xQueue = xQueueCreate( 1, sizeof( uint32_t ) );
}
void vAnInterruptHandler( void )

{
// xHigherPriorityTaskWoken must be set to pdFALSE before it is used.
BaseType_t xHigherPriorityTaskWoken = pdFALSE;
uint32_t ulVarToSend, ulValReceived;
// Write the value 10 to the queue using xQueueOverwriteFromISR().

ulVarToSend = 10;


xQueueOverwriteFromISR( xQueue, &ulVarToSend, &xHigherPriorityTaskWoken );
// The queue is full, but calling xQueueOverwriteFromISR() again will still

// pass because the value held in the queue will be overwritten with the
// new value.
ulVarToSend = 100;
xQueueOverwriteFromISR( xQueue, &ulVarToSend, &xHigherPriorityTaskWoken );
// Reading from the queue will now return 100.
// ...
if( xHigherPrioritytaskWoken == pdTRUE )

{
// Writing to the queue caused a task to unblock and the unblocked task
// has a priority higher than or equal to the priority of the currently
// executing task (the task this interrupt interrupted). Perform a␣
,→context
// switch so this interrupt returns directly to the unblocked task.

portYIELD_FROM_ISR(); // or portEND_SWITCHING_ISR() depending on the port.
}
}
Return xQueueOverwriteFromISR() is a macro that calls xQueueGenericSendFromISR(), and therefore has

the same return values as xQueueSendToFrontFromISR(). However, pdPASS is the only value that can
be returned because xQueueOverwriteFromISR() will write to the queue even when the queue is already
full.
Parameters
• [out] pxHigherPriorityTaskWoken: xQueueOverwriteFromISR() will set *pxHigher-
PriorityTaskWoken to pdTRUE if sending to the queue caused a task to unblock, and the unblocked
task has a priority higher than the currently running task. If xQueueOverwriteFromISR() sets this
value to pdTRUE then a context switch should be requested before the interrupt is exited.
xQueueSendFromISR(xQueue, pvItemToQueue, pxHigherPriorityTaskWoken)
This is a macro that calls xQueueGenericSendFromISR(). It is included for backward compatibility with
versions of FreeRTOS.org that did not include the xQueueSendToBackFromISR() and xQueueSendToFront-
FromISR() macros.
Post an item to the back of a queue. It is safe to use this function from within an interrupt service routine.

{
char cIn;
BaseType_t xHigherPriorityTaskWoken;


do
{


// Post the byte.

xQueueSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );

{
// Actual macro used here is port specific.
}
}
Parameters
• [out] pxHigherPriorityTaskWoken: xQueueSendFromISR() will set *pxHigherPriori-
tyTaskWoken to pdTRUE if sending to the queue caused a task to unblock, and the unblocked task
has a priority higher than the currently running task. If xQueueSendFromISR() sets this value to
pdTRUE then a context switch should be requested before the interrupt is exited.
xQueueReset(xQueue)
Reset a queue back to its original empty state. The return value is now obsolete and is always set to pdPASS.
Type Definitions
typedef struct QueueDefinition *QueueHandle_t
typedef struct QueueDefinition *QueueSetHandle_t
Type by which queue sets are referenced. For example, a call to xQueueCreateSet() returns an xQueueSet
variable that can then be used as a parameter to xQueueSelectFromSet(), xQueueAddToSet(), etc.
typedef struct QueueDefinition *QueueSetMemberHandle_t
Queue sets can contain both queues and semaphores, so the QueueSetMemberHandle_t is defined as a type to
be used where a parameter or return value can be either an QueueHandle_t or an SemaphoreHandle_t.
Semaphore API
Header File
• components/freertos/FreeRTOS-Kernel/include/freertos/semphr.h
Macros
semBINARY_SEMAPHORE_QUEUE_LENGTH
semSEMAPHORE_QUEUE_ITEM_LENGTH
semGIVE_BLOCK_TIME
vSemaphoreCreateBinary(xSemaphore)
xSemaphoreCreateBinary()
Creates a new binary semaphore instance, and returns a handle by which the new semaphore can be referenced.
In many usage scenarios it is faster and more memory efficient to use a direct to task notification in place of a
binary semaphore! https://www.FreeRTOS.org/RTOS-task-notifications.html

Internally, within the FreeRTOS implementation, binary semaphores use a block of memory, in which the
semaphore structure is stored. If a binary semaphore is created using xSemaphoreCreateBinary() then the
required memory is automatically dynamically allocated inside the xSemaphoreCreateBinary() function. (see
https://www.FreeRTOS.org/a00111.html). If a binary semaphore is created using xSemaphoreCreateBina-
ryStatic() then the application writer must provide the memory. xSemaphoreCreateBinaryStatic() therefore
allows a binary semaphore to be created without using any dynamic memory allocation.
The old vSemaphoreCreateBinary() macro is now deprecated in favour of this xSemaphoreCreateBinary()
function. Note that binary semaphores created using the vSemaphoreCreateBinary() macro are created in a
state such that the first call to take the semaphore would pass, whereas binary semaphores created using
xSemaphoreCreateBinary() are created in a state such that the the semaphore must first be given before it
can be taken .
This type of semaphore can be used for pure synchronisation between tasks or between an interrupt and a
task. The semaphore need not be given back once obtained, so one task/interrupt can continuously give the
semaphore while another continuously takes the semaphore. For this reason this type of semaphore does not
use a priority inheritance mechanism. For an alternative that does use priority inheritance see xSemaphoreCre-
ateMutex().
Example usage:
SemaphoreHandle_t xSemaphore = NULL;
void vATask( void * pvParameters )

{
// Semaphore cannot be used before a call to vSemaphoreCreateBinary().
// This is a macro so pass the variable in directly.
xSemaphore = xSemaphoreCreateBinary();
if( xSemaphore != NULL )

{
// The semaphore was created successfully.
// The semaphore can now be used.
}
}
Return Handle to the created semaphore, or NULL if the memory required to hold the semaphore s data
structures could not be allocated.
xSemaphoreCreateBinaryStatic(pxStaticSemaphore)
Creates a new binary semaphore instance, and returns a handle by which the new semaphore can be referenced.
NOTE: In many usage scenarios it is faster and more memory efficient to use a direct to task notification in
place of a binary semaphore! https://www.FreeRTOS.org/RTOS-task-notifications.html
Internally, within the FreeRTOS implementation, binary semaphores use a block of memory, in which the
semaphore structure is stored. If a binary semaphore is created using xSemaphoreCreateBinary() then the
required memory is automatically dynamically allocated inside the xSemaphoreCreateBinary() function. (see
https://www.FreeRTOS.org/a00111.html). If a binary semaphore is created using xSemaphoreCreateBina-
ryStatic() then the application writer must provide the memory. xSemaphoreCreateBinaryStatic() therefore
allows a binary semaphore to be created without using any dynamic memory allocation.
This type of semaphore can be used for pure synchronisation between tasks or between an interrupt and a
task. The semaphore need not be given back once obtained, so one task/interrupt can continuously give the
semaphore while another continuously takes the semaphore. For this reason this type of semaphore does not
use a priority inheritance mechanism. For an alternative that does use priority inheritance see xSemaphoreCre-
ateMutex().
Example usage:

StaticSemaphore_t xSemaphoreBuffer;


{
// Semaphore cannot be used before a call to xSemaphoreCreateBinary() or
// xSemaphoreCreateBinaryStatic().
// The semaphore's data structures will be placed in the xSemaphoreBuffer
// variable, the address of which is passed into the function. The
// function's parameter is not NULL, so the function will not attempt any
// dynamic memory allocation, and therefore the function will not return
// return NULL.
xSemaphore = xSemaphoreCreateBinaryStatic( &xSemaphoreBuffer );
// Rest of task code goes here.

}
Return If the semaphore is created then a handle to the created semaphore is returned. If pxSemaphoreBuffer
is NULL then NULL is returned.
Parameters
• pxStaticSemaphore: Must point to a variable of type StaticSemaphore_t, which will then be
used to hold the semaphore s data structure, removing the need for the memory to be allocated
dynamically.
xSemaphoreTake(xSemaphore, xBlockTime)
Macro to obtain a semaphore. The semaphore must have previously been created with a call to xSemaphoreCre-
ateBinary(), xSemaphoreCreateMutex() or xSemaphoreCreateCounting().
param xSemaphore A handle to the semaphore being taken - obtained when the semaphore was created.
param xBlockTime The time in ticks to wait for the semaphore to become available. The macro
portTICK_PERIOD_MS can be used to convert this to a real time. A block time of zero can be used to
poll the semaphore. A block time of portMAX_DELAY can be used to block indefinitely (provided IN-
CLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h).
Example usage:
// A task that creates a semaphore.

{
// Create the semaphore to guard a shared resource.
vSemaphoreCreateBinary( xSemaphore );
}
// A task that uses the semaphore.

void vAnotherTask( void * pvParameters )
{
// ... Do other things.

{
// See if we can obtain the semaphore. If the semaphore is not available
// wait 10 ticks to see if it becomes free.
if( xSemaphoreTake( xSemaphore, ( TickType_t ) 10 ) == pdTRUE )
{
// We were able to obtain the semaphore and can now access the
// shared resource.
// ...
// We have finished accessing the shared resource. Release the

// semaphore.
xSemaphoreGive( xSemaphore );


}
else
{
// We could not obtain the semaphore and can therefore not access
// the shared resource safely.
}
}
}
Return pdTRUE if the semaphore was obtained. pdFALSE if xBlockTime expired without the semaphore
becoming available.
xSemaphoreTakeRecursive(xMutex, xBlockTime)
Macro to recursively obtain, or take , a mutex type semaphore. The mutex must have previously been
created using a call to xSemaphoreCreateRecursiveMutex();
configUSE_RECURSIVE_MUTEXES must be set to 1 in FreeRTOSConfig.h for this macro to be available.
This macro must not be used on mutexes created using xSemaphoreCreateMutex().
A mutex used recursively can be taken repeatedly by the owner. The mutex doesn t become available
again until the owner has called xSemaphoreGiveRecursive() for each successful take request. For example,
if a task successfully takes the same mutex 5 times then the mutex will not be available to any other task
until it has also given the mutex back exactly five times.
Example usage:
SemaphoreHandle_t xMutex = NULL;
// A task that creates a mutex.

{
// Create the mutex to guard a shared resource.
xMutex = xSemaphoreCreateRecursiveMutex();
}
// A task that uses the mutex.

{
if( xMutex != NULL )

{
// See if we can obtain the mutex. If the mutex is not available
if( xSemaphoreTakeRecursive( xSemaphore, ( TickType_t ) 10 ) == pdTRUE )
{
// We were able to obtain the mutex and can now access the
// shared resource.
// ...
// For some reason due to the nature of the code further calls to
// xSemaphoreTakeRecursive() are made on the same mutex. In real
// code these would not be just sequential calls as this would make
// no sense. Instead the calls are likely to be buried inside
// a more complex call structure.
xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 );
// The mutex has now been 'taken' three times, so will not be
// available to another task until it has also been given back
// three times. Again it is unlikely that real code would have


// these calls sequentially, but instead buried in a more complex
// call structure. This is just for illustrative purposes.
xSemaphoreGiveRecursive( xMutex );
// Now the mutex can be taken by other tasks.

}
else
{
// We could not obtain the mutex and can therefore not access
}
}
}
Return pdTRUE if the semaphore was obtained. pdFALSE if xBlockTime expired without the semaphore
becoming available.
Parameters
• xMutex: A handle to the mutex being obtained. This is the handle returned by xSemaphoreCre-
ateRecursiveMutex();
• xBlockTime: The time in ticks to wait for the semaphore to become available. The macro
portTICK_PERIOD_MS can be used to convert this to a real time. A block time of zero can be used
to poll the semaphore. If the task already owns the semaphore then xSemaphoreTakeRecursive()
will return immediately no matter what the value of xBlockTime.
xSemaphoreGive(xSemaphore)
Macro to release a semaphore. The semaphore must have previously been created with a call to
xSemaphoreCreateBinary(), xSemaphoreCreateMutex() or xSemaphoreCreateCounting(). and obtained us-
ing sSemaphoreTake().
This macro must not be used from an ISR. See xSemaphoreGiveFromISR () for an alternative which can be
used from an ISR.
This macro must also not be used on semaphores created using xSemaphoreCreateRecursiveMutex().
Example usage:

{
// Create the semaphore to guard a shared resource.
vSemaphoreCreateBinary( xSemaphore );

{
if( xSemaphoreGive( xSemaphore ) != pdTRUE )
{
// We would expect this call to fail because we cannot give
// a semaphore without first "taking" it!
}
// Obtain the semaphore - don't block if the semaphore is not

// immediately available.
if( xSemaphoreTake( xSemaphore, ( TickType_t ) 0 ) )
{
// We now have the semaphore and can access the shared resource.
// ...


// We have finished accessing the shared resource so can free the
// semaphore.
if( xSemaphoreGive( xSemaphore ) != pdTRUE )
{
// We would not expect this call to fail because we must have
// obtained the semaphore to get here.
}
}
}
}
Return pdTRUE if the semaphore was released. pdFALSE if an error occurred. Semaphores are imple-
mented using queues. An error can occur if there is no space on the queue to post a message - indicating
that the semaphore was not first obtained correctly.
Parameters
• xSemaphore: A handle to the semaphore being released. This is the handle returned when the
semaphore was created.
xSemaphoreGiveRecursive(xMutex)
Macro to recursively release, or give , a mutex type semaphore. The mutex must have previously been
created using a call to xSemaphoreCreateRecursiveMutex();
configUSE_RECURSIVE_MUTEXES must be set to 1 in FreeRTOSConfig.h for this macro to be available.
This macro must not be used on mutexes created using xSemaphoreCreateMutex().
Example usage:
SemaphoreHandle_t xMutex = NULL;
// A task that creates a mutex.

{
// Create the mutex to guard a shared resource.
xMutex = xSemaphoreCreateRecursiveMutex();
}
// A task that uses the mutex.

{
if( xMutex != NULL )

{
// See if we can obtain the mutex. If the mutex is not available
if( xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 ) == pdTRUE )
{
// We were able to obtain the mutex and can now access the
// shared resource.
// ...
// For some reason due to the nature of the code further calls to
// xSemaphoreTakeRecursive() are made on the same mutex. In real
// code these would not be just sequential calls as this would make
// no sense. Instead the calls are likely to be buried inside
// a more complex call structure.


// The mutex has now been 'taken' three times, so will not be
// available to another task until it has also been given back
// three times. Again it is unlikely that real code would have
// these calls sequentially, it would be more likely that the calls
// to xSemaphoreGiveRecursive() would be called as a call stack
// unwound. This is just for demonstrative purposes.
// Now the mutex can be taken by other tasks.

}
else
{
// We could not obtain the mutex and can therefore not access
}
}
}
Return pdTRUE if the semaphore was given.

Parameters
• xMutex: A handle to the mutex being released, or given . This is the handle returned by
xSemaphoreCreateMutex();
xSemaphoreGiveFromISR(xSemaphore, pxHigherPriorityTaskWoken)
Macro to release a semaphore. The semaphore must have previously been created with a call to
xSemaphoreCreateBinary() or xSemaphoreCreateCounting().
Mutex type semaphores (those created using a call to xSemaphoreCreateMutex()) must not be used with this
macro.
This macro can be used from an ISR.
Example usage:
#define LONG_TIME 0xffff

#define TICKS_TO_WAIT 10
// Repetitive task.
{
for( ;; )
{
// We want this task to run every 10 ticks of a timer. The semaphore
// was created before this task was started.
// Block waiting for the semaphore to become available.

if( xSemaphoreTake( xSemaphore, LONG_TIME ) == pdTRUE )
{
// It is time to execute.
// ...
// We have finished our task. Return to the top of the loop where
// we will block on the semaphore until it is time to execute
// again. Note when using the semaphore for synchronisation with an
// ISR in this manner there is no need to 'give' the semaphore back.


}
}
}
// Timer ISR
void vTimerISR( void * pvParameters )
{
static uint8_t ucLocalTickCount = 0;
static BaseType_t xHigherPriorityTaskWoken;
// A timer tick has occurred.
// ... Do other time functions.
// Is it time for vATask () to run?

ucLocalTickCount++;
if( ucLocalTickCount >= TICKS_TO_WAIT )
{
// Unblock the task by releasing the semaphore.
xSemaphoreGiveFromISR( xSemaphore, &xHigherPriorityTaskWoken );
// Reset the count so we release the semaphore again in 10 ticks time.

ucLocalTickCount = 0;
}
if( xHigherPriorityTaskWoken != pdFALSE )

{
// We can force a context switch here. Context switching from an
// ISR uses port specific syntax. Check the demo task for your port
// to find the syntax required.
}
}
Return pdTRUE if the semaphore was successfully given, otherwise errQUEUE_FULL.

Parameters
• xSemaphore: A handle to the semaphore being released. This is the handle returned when the
• pxHigherPriorityTaskWoken: xSemaphoreGiveFromISR() will set *pxHigherPriority-
TaskWoken to pdTRUE if giving the semaphore caused a task to unblock, and the unblocked task
has a priority higher than the currently running task. If xSemaphoreGiveFromISR() sets this value
to pdTRUE then a context switch should be requested before the interrupt is exited.
xSemaphoreTakeFromISR(xSemaphore, pxHigherPriorityTaskWoken)
Macro to take a semaphore from an ISR. The semaphore must have previously been created with a call to
xSemaphoreCreateBinary() or xSemaphoreCreateCounting().
Mutex type semaphores (those created using a call to xSemaphoreCreateMutex()) must not be used with this
macro.
This macro can be used from an ISR, however taking a semaphore from an ISR is not a common operation. It
is likely to only be useful when taking a counting semaphore when an interrupt is obtaining an object from a
resource pool (when the semaphore count indicates the number of resources available).
Return pdTRUE if the semaphore was successfully taken, otherwise pdFALSE
Parameters
• xSemaphore: A handle to the semaphore being taken. This is the handle returned when the
• [out] pxHigherPriorityTaskWoken: xSemaphoreTakeFromISR() will set *pxHigher-
PriorityTaskWoken to pdTRUE if taking the semaphore caused a task to unblock, and the unblocked
task has a priority higher than the currently running task. If xSemaphoreTakeFromISR() sets this
value to pdTRUE then a context switch should be requested before the interrupt is exited.

xSemaphoreCreateMutex()
Creates a new mutex type semaphore instance, and returns a handle by which the new mutex can be referenced.
Internally, within the FreeRTOS implementation, mutex semaphores use a block of memory, in which
the mutex structure is stored. If a mutex is created using xSemaphoreCreateMutex() then the required
memory is automatically dynamically allocated inside the xSemaphoreCreateMutex() function. (see https:
//www.FreeRTOS.org/a00111.html). If a mutex is created using xSemaphoreCreateMutexStatic() then the
application writer must provided the memory. xSemaphoreCreateMutexStatic() therefore allows a mutex to
be created without using any dynamic memory allocation.
Mutexes created using this function can be accessed using the xSemaphoreTake() and xSemaphoreGive()
macros. The xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros must not be used.
This type of semaphore uses a priority inheritance mechanism so a task taking a semaphore MUST ALWAYS
give the semaphore back once the semaphore it is no longer required.
Mutex type semaphores cannot be used from within interrupt service routines.
See xSemaphoreCreateBinary() for an alternative implementation that can be used for pure synchronisation
(where one task or interrupt always gives the semaphore and another always takes the semaphore) and
from within interrupt service routines.
Example usage:
SemaphoreHandle_t xSemaphore;

{
// Semaphore cannot be used before a call to xSemaphoreCreateMutex().
xSemaphore = xSemaphoreCreateMutex();

{
}
}
Return If the mutex was successfully created then a handle to the created semaphore is returned. If there was
not enough heap to allocate the mutex data structures then NULL is returned.
xSemaphoreCreateMutexStatic(pxMutexBuffer)
Creates a new mutex type semaphore instance, and returns a handle by which the new mutex can be referenced.
Internally, within the FreeRTOS implementation, mutex semaphores use a block of memory, in which
the mutex structure is stored. If a mutex is created using xSemaphoreCreateMutex() then the required
memory is automatically dynamically allocated inside the xSemaphoreCreateMutex() function. (see https:
//www.FreeRTOS.org/a00111.html). If a mutex is created using xSemaphoreCreateMutexStatic() then the
application writer must provided the memory. xSemaphoreCreateMutexStatic() therefore allows a mutex to
be created without using any dynamic memory allocation.
Mutexes created using this function can be accessed using the xSemaphoreTake() and xSemaphoreGive()
macros. The xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros must not be used.
Example usage:

StaticSemaphore_t xMutexBuffer;

{
// A mutex cannot be used before it has been created. xMutexBuffer is
// into xSemaphoreCreateMutexStatic() so no dynamic memory allocation is
// attempted.
xSemaphore = xSemaphoreCreateMutexStatic( &xMutexBuffer );
// As no dynamic memory allocation was performed, xSemaphore cannot be NULL,

// so there is no need to check it.
}
Return If the mutex was successfully created then a handle to the created mutex is returned. If pxMutexBuffer
was NULL then NULL is returned.
Parameters
• pxMutexBuffer: Must point to a variable of type StaticSemaphore_t, which will be used to hold
the mutex s data structure, removing the need for the memory to be allocated dynamically.
xSemaphoreCreateRecursiveMutex()
Creates a new recursive mutex type semaphore instance, and returns a handle by which the new recursive mutex
can be referenced.
Internally, within the FreeRTOS implementation, recursive mutexs use a block of memory, in which the mu-
tex structure is stored. If a recursive mutex is created using xSemaphoreCreateRecursiveMutex() then the
required memory is automatically dynamically allocated inside the xSemaphoreCreateRecursiveMutex() func-
tion. (see http://www.freertos.org/a00111.html). If a recursive mutex is created using xSemaphoreCreateRe-
cursiveMutexStatic() then the application writer must provide the memory that will get used by the mutex.
xSemaphoreCreateRecursiveMutexStatic() therefore allows a recursive mutex to be created without using any
dynamic memory allocation.
Mutexes created using this macro can be accessed using the xSemaphoreTakeRecursive() and xSemaphore-
GiveRecursive() macros. The xSemaphoreTake() and xSemaphoreGive() macros must not be used.
See vSemaphoreCreateBinary() for an alternative implementation that can be used for pure synchronisation
Example usage:

{
// Semaphore cannot be used before a call to xSemaphoreCreateMutex().
xSemaphore = xSemaphoreCreateRecursiveMutex();

{


}
}
Return xSemaphore Handle to the created mutex semaphore. Should be of type SemaphoreHandle_t.
xSemaphoreCreateRecursiveMutexStatic(pxStaticSemaphore)
Creates a new recursive mutex type semaphore instance, and returns a handle by which the new recursive mutex
can be referenced.
Internally, within the FreeRTOS implementation, recursive mutexs use a block of memory, in which the mu-
tex structure is stored. If a recursive mutex is created using xSemaphoreCreateRecursiveMutex() then the
required memory is automatically dynamically allocated inside the xSemaphoreCreateRecursiveMutex() func-
tion. (see https://www.FreeRTOS.org/a00111.html). If a recursive mutex is created using xSemaphoreCre-
ateRecursiveMutexStatic() then the application writer must provide the memory that will get used by the mutex.
xSemaphoreCreateRecursiveMutexStatic() therefore allows a recursive mutex to be created without using any
dynamic memory allocation.
Mutexes created using this macro can be accessed using the xSemaphoreTakeRecursive() and xSemaphore-
GiveRecursive() macros. The xSemaphoreTake() and xSemaphoreGive() macros must not be used.
Example usage:
StaticSemaphore_t xMutexBuffer;

{
// A recursive semaphore cannot be used before it is created. Here a
// recursive mutex is created using xSemaphoreCreateRecursiveMutexStatic().
// The address of xMutexBuffer is passed into the function, and will hold
// the mutexes data structures - so no dynamic memory allocation will be
// attempted.
xSemaphore = xSemaphoreCreateRecursiveMutexStatic( &xMutexBuffer );
// As no dynamic memory allocation was performed, xSemaphore cannot be NULL,

// so there is no need to check it.
}
Return If the recursive mutex was successfully created then a handle to the created recursive mutex is returned.
If pxMutexBuffer was NULL then NULL is returned.
Parameters
• pxStaticSemaphore: Must point to a variable of type StaticSemaphore_t, which will then be
used to hold the recursive mutex s data structure, removing the need for the memory to be allocated
dynamically.
xSemaphoreCreateCounting(uxMaxCount, uxInitialCount)
Creates a new counting semaphore instance, and returns a handle by which the new counting semaphore can
be referenced.

counting semaphore! https://www.FreeRTOS.org/RTOS-task-notifications.html
Internally, within the FreeRTOS implementation, counting semaphores use a block of memory, in which
the counting semaphore structure is stored. If a counting semaphore is created using xSemaphoreCreate-
Counting() then the required memory is automatically dynamically allocated inside the xSemaphoreCreate-
Counting() function. (see https://www.FreeRTOS.org/a00111.html). If a counting semaphore is created us-
ing xSemaphoreCreateCountingStatic() then the application writer can instead optionally provide the memory
that will get used by the counting semaphore. xSemaphoreCreateCountingStatic() therefore allows a counting
semaphore to be created without using any dynamic memory allocation.
Counting semaphores are typically used for two things:
1) Counting events.
In this usage scenario an event handler will give a semaphore each time an event occurs (incrementing
the semaphore count value), and a handler task will take a semaphore each time it processes an event
(decrementing the semaphore count value). The count value is therefore the difference between the number of
events that have occurred and the number that have been processed. In this case it is desirable for the initial
count value to be zero.
2) Resource management.
In this usage scenario the count value indicates the number of resources available. To obtain control of a
resource a task must first obtain a semaphore - decrementing the semaphore count value. When the count value
reaches zero there are no free resources. When a task finishes with the resource it gives the semaphore back
- incrementing the semaphore count value. In this case it is desirable for the initial count value to be equal to
the maximum count value, indicating that all resources are free.
Example usage:

{
// Semaphore cannot be used before a call to xSemaphoreCreateCounting().

// The max value to which the semaphore can count should be 10, and the
// initial value assigned to the count should be 0.
xSemaphore = xSemaphoreCreateCounting( 10, 0 );

{
}
}
Return Handle to the created semaphore. Null if the semaphore could not be created.
Parameters
• uxMaxCount: The maximum count value that can be reached. When the semaphore reaches this
value it can no longer be given .
• uxInitialCount: The count value assigned to the semaphore when it is created.
xSemaphoreCreateCountingStatic(uxMaxCount, uxInitialCount, pxSemaphoreBuffer)
Creates a new counting semaphore instance, and returns a handle by which the new counting semaphore can
be referenced.
counting semaphore! https://www.FreeRTOS.org/RTOS-task-notifications.html
Internally, within the FreeRTOS implementation, counting semaphores use a block of memory, in which the
counting semaphore structure is stored. If a counting semaphore is created using xSemaphoreCreateCount-
ing() then the required memory is automatically dynamically allocated inside the xSemaphoreCreateCount-

ing() function. (see https://www.FreeRTOS.org/a00111.html). If a counting semaphore is created using

xSemaphoreCreateCountingStatic() then the application writer must provide the memory. xSemaphoreCre-
ateCountingStatic() therefore allows a counting semaphore to be created without using any dynamic memory
allocation.
Counting semaphores are typically used for two things:
1) Counting events.
In this usage scenario an event handler will give a semaphore each time an event occurs (incrementing
the semaphore count value), and a handler task will take a semaphore each time it processes an event
(decrementing the semaphore count value). The count value is therefore the difference between the number of
events that have occurred and the number that have been processed. In this case it is desirable for the initial
count value to be zero.
2) Resource management.
In this usage scenario the count value indicates the number of resources available. To obtain control of a
resource a task must first obtain a semaphore - decrementing the semaphore count value. When the count value
reaches zero there are no free resources. When a task finishes with the resource it gives the semaphore back
- incrementing the semaphore count value. In this case it is desirable for the initial count value to be equal to
the maximum count value, indicating that all resources are free.
Example usage:
StaticSemaphore_t xSemaphoreBuffer;

{
// Counting semaphore cannot be used before they have been created. Create
// a counting semaphore using xSemaphoreCreateCountingStatic(). The max
// value to which the semaphore can count is 10, and the initial value
// assigned to the count will be 0. The address of xSemaphoreBuffer is
// passed in and will be used to hold the semaphore structure, so no dynamic
// memory allocation will be used.
xSemaphore = xSemaphoreCreateCounting( 10, 0, &xSemaphoreBuffer );
// No memory allocation was attempted so xSemaphore cannot be NULL, so there

// is no need to check its value.
}
Return If the counting semaphore was successfully created then a handle to the created counting semaphore
is returned. If pxSemaphoreBuffer was NULL then NULL is returned.
Parameters
• uxMaxCount: The maximum count value that can be reached. When the semaphore reaches this
value it can no longer be given .
• uxInitialCount: The count value assigned to the semaphore when it is created.
• pxSemaphoreBuffer: Must point to a variable of type StaticSemaphore_t, which will then be
used to hold the semaphore s data structure, removing the need for the memory to be allocated
dynamically.
vSemaphoreDelete(xSemaphore)
Delete a semaphore. This function must be used with care. For example, do not delete a mutex type semaphore
if the mutex is held by a task.
Parameters
• xSemaphore: A handle to the semaphore to be deleted.
xSemaphoreGetMutexHolder(xSemaphore)
If xMutex is indeed a mutex type semaphore, return the current mutex holder. If xMutex is not a mutex type
semaphore, or the mutex is available (not held by a task), return NULL.

Note: This is a good way of determining if the calling task is the mutex holder, but not a good way of deter-
mining the identity of the mutex holder as the holder may change between the function exiting and the returned
value being tested.
xSemaphoreGetMutexHolderFromISR(xSemaphore)
If xMutex is indeed a mutex type semaphore, return the current mutex holder. If xMutex is not a mutex type
semaphore, or the mutex is available (not held by a task), return NULL.
uxSemaphoreGetCount(xSemaphore)
If the semaphore is a counting semaphore then uxSemaphoreGetCount() returns its current count value. If the
semaphore is a binary semaphore then uxSemaphoreGetCount() returns 1 if the semaphore is available, and 0
if the semaphore is not available.
Type Definitions
typedef QueueHandle_t SemaphoreHandle_t
Timer API
Header File
• components/freertos/FreeRTOS-Kernel/include/freertos/timers.h
Functions
TimerHandle_t xTimerCreate(const char *const pcTimerName, const TickType_t xTimerPeriod-
InTicks, const UBaseType_t uxAutoReload, void *const pvTimerID,
TimerCallbackFunction_t pxCallbackFunction)
TimerHandle_t xTimerCreate( const char * const pcTimerName, TickType_t xTimerPeriodInTicks, UBase-
Type_t uxAutoReload, void * pvTimerID, TimerCallbackFunction_t pxCallbackFunction );
Creates a new software timer instance, and returns a handle by which the created software timer can be refer-
enced.
Internally, within the FreeRTOS implementation, software timers use a block of memory, in which the timer
data structure is stored. If a software timer is created using xTimerCreate() then the required memory is auto-
matically dynamically allocated inside the xTimerCreate() function. (see https://www.FreeRTOS.org/a00111.
html). If a software timer is created using xTimerCreateStatic() then the application writer must provide the
memory that will get used by the software timer. xTimerCreateStatic() therefore allows a software timer to be
Timers are created in the dormant state. The xTimerStart(), xTimerReset(), xTimerStartFromISR(), xTimer-
ResetFromISR(), xTimerChangePeriod() and xTimerChangePeriodFromISR() API functions can all be used
to transition a timer into the active state.
Example usage:
* #define NUM_TIMERS 5
*
* // An array to hold handles to the created timers.
* TimerHandle_t xTimers[ NUM_TIMERS ];
*
* // An array to hold a count of the number of times each timer expires.
* int32_t lExpireCounters[ NUM_TIMERS ] = { 0 };
*
* // Define a callback function that will be used by multiple timer instances.
* // The callback function does nothing but count the number of times the
* // associated timer expires, and stop the timer once the timer has expired
* // 10 times.
* void vTimerCallback( TimerHandle_t pxTimer )
* {
* int32_t lArrayIndex;


* const int32_t xMaxExpiryCountBeforeStopping = 10;
*
* // Optionally do something if the pxTimer parameter is NULL.
* configASSERT( pxTimer );
*
* // Which timer expired?
* lArrayIndex = ( int32_t ) pvTimerGetTimerID( pxTimer );
*
* // Increment the number of times that pxTimer has expired.
* lExpireCounters[ lArrayIndex ] += 1;
*
* // If the timer has expired 10 times then stop it from running.
* if( lExpireCounters[ lArrayIndex ] == xMaxExpiryCountBeforeStopping )
* {
* // Do not use a block time if calling a timer API function from a
* // timer callback function, as doing so could cause a deadlock!
* xTimerStop( pxTimer, 0 );
* }
* }
*
* void main( void )
* {
* int32_t x;
*
* // Create then start some timers. Starting the timers before the␣
,→ scheduler
* // has been started means the timers will start running immediately that
* // the scheduler starts.
* for( x = 0; x < NUM_TIMERS; x++ )
* {
* xTimers[ x ] = xTimerCreate( "Timer", // Just a text name,␣
,→not used by the kernel.
* ( 100 * x ), // The timer period␣

,→in ticks.
* pdTRUE, // The timers will␣

,→auto-reload themselves when they expire.
* ( void * ) x, // Assign each timer␣

,→a unique id equal to its array index.
* vTimerCallback // Each timer calls␣

,→the same callback when it expires.
* );
*
* if( xTimers[ x ] == NULL )
* {
* // The timer was not created.
* }
* else
* {
* // Start the timer. No block time is specified, and even if one␣
,→was
* // it would be ignored because the scheduler has not yet been

* // started.
* if( xTimerStart( xTimers[ x ], 0 ) != pdPASS )
* {
* // The timer could not be set into the Active state.
* }
* }
* }
*
* // ...
* // Create tasks here.


* // ...
*
* // Starting the scheduler will start the timers running as they have␣
already
,→
* // been set into the active state.

* vTaskStartScheduler();
*
* // Should not reach here.
* for( ;; );
* }
*
Return If the timer is successfully created then a handle to the newly created timer is returned. If the timer
cannot be created (because either there is insufficient FreeRTOS heap remaining to allocate the timer
structures, or the timer period was set to 0) then NULL is returned.
Parameters
• pcTimerName: A text name that is assigned to the timer. This is done purely to assist debugging.
The kernel itself only ever references a timer by its handle, and never by its name.
• xTimerPeriodInTicks: The timer period. The time is defined in tick periods so the con-
stant portTICK_PERIOD_MS can be used to convert a time that has been specified in millisec-
onds. For example, if the timer must expire after 100 ticks, then xTimerPeriodInTicks should be
set to 100. Alternatively, if the timer must expire after 500ms, then xPeriod can be set to ( 500 /
portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or equal to 1000. Time
timer period must be greater than 0.
• uxAutoReload: If uxAutoReload is set to pdTRUE then the timer will expire repeatedly with a
frequency set by the xTimerPeriodInTicks parameter. If uxAutoReload is set to pdFALSE then the
timer will be a one-shot timer and enter the dormant state after it expires.
• pvTimerID: An identifier that is assigned to the timer being created. Typically this would be used
in the timer callback function to identify which timer expired when the same callback function is
assigned to more than one timer.
• pxCallbackFunction: The function to call when the timer expires. Callback functions must
have the prototype defined by TimerCallbackFunction_t, which is void vCallbackFunction( Timer-
Handle_t xTimer ); .
TimerHandle_t xTimerCreateStatic(const char *const pcTimerName, const TickType_t
xTimerPeriodInTicks, const UBaseType_t uxAutoReload, void
*const pvTimerID, TimerCallbackFunction_t pxCallbackFunc-
tion, StaticTimer_t *pxTimerBuffer)
TimerHandle_t xTimerCreateStatic(const char * const pcTimerName, TickType_t xTimerPeriodInTicks,
UBaseType_t uxAutoReload, void * pvTimerID, TimerCallbackFunction_t pxCallbackFunction, Static-
Timer_t *pxTimerBuffer );
Creates a new software timer instance, and returns a handle by which the created software timer can be refer-
enced.
Internally, within the FreeRTOS implementation, software timers use a block of memory, in which the timer
data structure is stored. If a software timer is created using xTimerCreate() then the required memory is auto-
matically dynamically allocated inside the xTimerCreate() function. (see https://www.FreeRTOS.org/a00111.
html). If a software timer is created using xTimerCreateStatic() then the application writer must provide the
memory that will get used by the software timer. xTimerCreateStatic() therefore allows a software timer to be
Example usage:
*
* // The buffer used to hold the software timer's data structure.
* static StaticTimer_t xTimerBuffer;


*
* // A variable that will be incremented by the software timer's callback
* // function.
* UBaseType_t uxVariableToIncrement = 0;
*
* // A software timer callback function that increments a variable passed to
* // it when the software timer was created. After the 5th increment the
* // callback function stops the software timer.
* static void prvTimerCallback( TimerHandle_t xExpiredTimer )
* {
* UBaseType_t *puxVariableToIncrement;
* BaseType_t xReturned;
*
* // Obtain the address of the variable to increment from the timer ID.
* puxVariableToIncrement = ( UBaseType_t * ) pvTimerGetTimerID(␣
,→xExpiredTimer );
*
* // Increment the variable to show the timer callback has executed.
* ( *puxVariableToIncrement )++;
*
* // If this callback has executed the required number of times, stop the
* // timer.
* if( *puxVariableToIncrement == 5 )
* {
* // This is called from a timer callback so must not block.
* xTimerStop( xExpiredTimer, staticDONT_BLOCK );
* }
* }
*
*
* void main( void )
* {
* // Create the software time. xTimerCreateStatic() has an extra parameter
* // than the normal xTimerCreate() API function. The parameter is a␣
,→pointer
* // to the StaticTimer_t structure that will hold the software timer

* // structure. If the parameter is passed as NULL then the structure␣
,→will be
* // allocated dynamically, just as if xTimerCreate() had been called.

* xTimer = xTimerCreateStatic( "T1", // Text name for the task.
,→ Helps debugging only. Not used by FreeRTOS.
* xTimerPeriod, // The period of the␣
,→timer in ticks.
* pdTRUE, // This is an auto-reload␣

,→timer.
* ( void * ) &uxVariableToIncrement, // A␣
,→variable incremented by the software timer's callback function
* prvTimerCallback, // The function to␣

,→execute when the timer expires.
* &xTimerBuffer ); // The buffer that will␣

,→hold the software timer structure.
*
* // The scheduler has not started yet so a block time is not used.
* xReturned = xTimerStart( xTimer, 0 );
*
* // ...
* // ...
*
* // Starting the scheduler will start the timers running as they have␣
,→already


*
* for( ;; );
* }
*
Return If the timer is created then a handle to the created timer is returned. If pxTimerBuffer was NULL
then NULL is returned.
Parameters
• pcTimerName: A text name that is assigned to the timer. This is done purely to assist debugging.
The kernel itself only ever references a timer by its handle, and never by its name.
• xTimerPeriodInTicks: The timer period. The time is defined in tick periods so the con-
stant portTICK_PERIOD_MS can be used to convert a time that has been specified in millisec-
onds. For example, if the timer must expire after 100 ticks, then xTimerPeriodInTicks should be
set to 100. Alternatively, if the timer must expire after 500ms, then xPeriod can be set to ( 500
/ portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or equal to 1000. The
timer period must be greater than 0.
frequency set by the xTimerPeriodInTicks parameter. If uxAutoReload is set to pdFALSE then the
timer will be a one-shot timer and enter the dormant state after it expires.
• pvTimerID: An identifier that is assigned to the timer being created. Typically this would be used
in the timer callback function to identify which timer expired when the same callback function is
assigned to more than one timer.
• pxCallbackFunction: The function to call when the timer expires. Callback functions must
have the prototype defined by TimerCallbackFunction_t, which is void vCallbackFunction( Timer-
Handle_t xTimer ); .
• pxTimerBuffer: Must point to a variable of type StaticTimer_t, which will be then be used
to hold the software timer s data structures, removing the need for the memory to be allocated
dynamically.
void *pvTimerGetTimerID(const TimerHandle_t xTimer)
void *pvTimerGetTimerID( TimerHandle_t xTimer );
Returns the ID assigned to the timer.
IDs are assigned to timers using the pvTimerID parameter of the call to xTimerCreated() that was used to
create the timer, and by calling the vTimerSetTimerID() API function.
If the same callback function is assigned to multiple timers then the timer ID can be used as time specific (timer
local) storage.
Example usage:
Return The ID assigned to the timer being queried.
Parameters
• xTimer: The timer being queried.
See the xTimerCreate() API function example usage scenario.
void vTimerSetTimerID(TimerHandle_t xTimer, void *pvNewID)
void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID );
Sets the ID assigned to the timer.
IDs are assigned to timers using the pvTimerID parameter of the call to xTimerCreated() that was used to
create the timer.
If the same callback function is assigned to multiple timers then the timer ID can be used as time specific (timer
local) storage.
Example usage:

Parameters
• xTimer: The timer being updated.
• pvNewID: The ID to assign to the timer.
BaseType_t xTimerIsTimerActive(TimerHandle_t xTimer)
BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer );
Queries a timer to see if it is active or dormant.
A timer will be dormant if: 1) It has been created but not started, or 2) It is an expired one-shot timer that has
not been restarted.
Example usage:
* // This function assumes xTimer has already been created.

* void vAFunction( TimerHandle_t xTimer )
* {
* if( xTimerIsTimerActive( xTimer ) != pdFALSE ) // or more simply and␣
,→equivalently "if( xTimerIsTimerActive( xTimer ) )"
* {
* // xTimer is active, do something.
* }
* else
* {
* // xTimer is not active, do something else.
* }
* }
*
Return pdFALSE will be returned if the timer is dormant. A value other than pdFALSE will be returned if
the timer is active.
Parameters
• xTimer: The timer being queried.
TaskHandle_t xTimerGetTimerDaemonTaskHandle(void)
xTimerGetTimerDaemonTaskHandle() is only available if INCLUDE_xTimerGetTimerDaemonTaskHandle
is set to 1 in FreeRTOSConfig.h.
Simply returns the handle of the timer service/daemon task. It it not valid to call xTimerGetTimerDaemon-
TaskHandle() before the scheduler has been started.
BaseType_t xTimerPendFunctionCallFromISR(PendedFunction_t xFunctionToPend, void
*pvParameter1, uint32_t ulParameter2, Base-
Type_t *pxHigherPriorityTaskWoken)
BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend, void *pvParameter1,
uint32_t ulParameter2, BaseType_t *pxHigherPriorityTaskWoken );
Used from application interrupt service routines to defer the execution of a function to the RTOS daemon task
(the timer service task, hence this function is implemented in timers.c and is prefixed with Timer ).
Ideally an interrupt service routine (ISR) is kept as short as possible, but sometimes an ISR either has a lot of
processing to do, or needs to perform processing that is not deterministic. In these cases xTimerPendFunc-
tionCallFromISR() can be used to defer processing of a function to the RTOS daemon task.
A mechanism is provided that allows the interrupt to return directly to the task that will subsequently execute the
pended callback function. This allows the callback function to execute contiguously in time with the interrupt
- just as if the callback had executed in the interrupt itself.
Example usage:

*
* // The callback function that will execute in the context of the daemon␣
,→ task.
* // Note callback functions must all use this same prototype.
* void vProcessInterface( void *pvParameter1, uint32_t ulParameter2 )
* {
* BaseType_t xInterfaceToService;
*
* // The interface that requires servicing is passed in the second
* // parameter. The first parameter is not used in this case.
* xInterfaceToService = ( BaseType_t ) ulParameter2;
*
* // ...Perform the processing here...
* }
*
* // An ISR that receives data packets from multiple interfaces
* void vAnISR( void )
* {
* BaseType_t xInterfaceToService, xHigherPriorityTaskWoken;
*
* // Query the hardware to determine which interface needs processing.
* xInterfaceToService = prvCheckInterfaces();
*
* // The actual processing is to be deferred to a task. Request the
* // vProcessInterface() callback function is executed, passing in the
* // number of the interface that needs processing. The interface to
* // service is passed in the second parameter. The first parameter is
* // not used in this case.
* xHigherPriorityTaskWoken = pdFALSE;
* xTimerPendFunctionCallFromISR( vProcessInterface, NULL, ( uint32_t )␣
,→xInterfaceToService, &xHigherPriorityTaskWoken );
*
* // If xHigherPriorityTaskWoken is now set to pdTRUE then a context
* // switch should be requested. The macro used is port specific and will
* // be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() - refer to
* // the documentation page for the port being used.
* portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
*
* }
*
Return pdPASS is returned if the message was successfully sent to the timer daemon task, otherwise
pdFALSE is returned.
Parameters
• xFunctionToPend: The function to execute from the timer service/ daemon task. The function
must conform to the PendedFunction_t prototype.
• pvParameter1: The value of the callback function s first parameter. The parameter has a void
* type to allow it to be used to pass any type. For example, unsigned longs can be cast to a void *,
or the void * can be used to point to a structure.
• ulParameter2: The value of the callback function s second parameter.
• pxHigherPriorityTaskWoken: As mentioned above, calling this function will result in a
message being sent to the timer daemon task. If the priority of the timer daemon task (which is
set using configTIMER_TASK_PRIORITY in FreeRTOSConfig.h) is higher than the priority of
the currently running task (the task the interrupt interrupted) then *pxHigherPriorityTaskWoken
will be set to pdTRUE within xTimerPendFunctionCallFromISR(), indicating that a context switch
should be requested before the interrupt exits. For that reason *pxHigherPriorityTaskWoken must
be initialised to pdFALSE. See the example code below.
BaseType_t xTimerPendFunctionCall(PendedFunction_t xFunctionToPend, void *pvParameter1,
uint32_t ulParameter2, TickType_t xTicksToWait)
BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend, void *pvParameter1, uint32_t

ulParameter2, TickType_t xTicksToWait );

Used to defer the execution of a function to the RTOS daemon task (the timer service task, hence this function
is implemented in timers.c and is prefixed with Timer ).
Return pdPASS is returned if the message was successfully sent to the timer daemon task, otherwise
Parameters
• xFunctionToPend: The function to execute from the timer service/ daemon task. The function
must conform to the PendedFunction_t prototype.
• pvParameter1: The value of the callback function s first parameter. The parameter has a void
* type to allow it to be used to pass any type. For example, unsigned longs can be cast to a void *,
or the void * can be used to point to a structure.
• ulParameter2: The value of the callback function s second parameter.
• xTicksToWait: Calling this function will result in a message being sent to the timer daemon task
on a queue. xTicksToWait is the amount of time the calling task should remain in the Blocked state
(so not using any processing time) for space to become available on the timer queue if the queue is
found to be full.
const char *pcTimerGetName(TimerHandle_t xTimer)
const char * const pcTimerGetName( TimerHandle_t xTimer );
Returns the name that was assigned to a timer when the timer was created.
Return The name assigned to the timer specified by the xTimer parameter.
Parameters
• xTimer: The handle of the timer being queried.
void vTimerSetReloadMode(TimerHandle_t xTimer, const UBaseType_t uxAutoReload)
void vTimerSetReloadMode( TimerHandle_t xTimer, const UBaseType_t uxAutoReload );
Updates a timer to be either an auto-reload timer, in which case the timer automatically resets itself each time
it expires, or a one-shot timer, in which case the timer will only expire once unless it is manually restarted.
Parameters
• xTimer: The handle of the timer being updated.
frequency set by the timer s period (see the xTimerPeriodInTicks parameter of the xTimerCreate()
API function). If uxAutoReload is set to pdFALSE then the timer will be a one-shot timer and enter
the dormant state after it expires.
UBaseType_t uxTimerGetReloadMode(TimerHandle_t xTimer)
UBaseType_t uxTimerGetReloadMode( TimerHandle_t xTimer );
Queries a timer to determine if it is an auto-reload timer, in which case the timer automatically resets itself
each time it expires, or a one-shot timer, in which case the timer will only expire once unless it is manually
restarted.
Return If the timer is an auto-reload timer then pdTRUE is returned, otherwise pdFALSE is returned.
Parameters
TickType_t xTimerGetPeriod(TimerHandle_t xTimer)
TickType_t xTimerGetPeriod( TimerHandle_t xTimer );
Returns the period of a timer.
Return The period of the timer in ticks.
Parameters
TickType_t xTimerGetExpiryTime(TimerHandle_t xTimer)
TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer );
Returns the time in ticks at which the timer will expire. If this is less than the current tick count then the expiry
time has overflowed from the current time.

Return If the timer is running then the time in ticks at which the timer will next expire is returned. If the
timer is not running then the return value is undefined.
Parameters
void vApplicationGetTimerTaskMemory(StaticTask_t **ppxTimerTaskTCBBuffer, Stack-
Type_t **ppxTimerTaskStackBuffer, uint32_t
*pulTimerTaskStackSize)
This function is used to provide a statically allocated block of memory to FreeRTOS to hold the Timer Task
TCB. This function is required when configSUPPORT_STATIC_ALLOCATION is set. For more information
see this URI: https://www.FreeRTOS.org/a00110.html#configSUPPORT_STATIC_ALLOCATION
Parameters
• ppxTimerTaskTCBBuffer: A handle to a statically allocated TCB buffer
• ppxTimerTaskStackBuffer: A handle to a statically allocated Stack buffer for thie idle task
• pulTimerTaskStackSize: A pointer to the number of elements that will fit in the allocated
stack buffer
Macros
tmrCOMMAND_EXECUTE_CALLBACK_FROM_ISR
tmrCOMMAND_EXECUTE_CALLBACK
tmrCOMMAND_START_DONT_TRACE
tmrCOMMAND_START
tmrCOMMAND_RESET
tmrCOMMAND_STOP
tmrCOMMAND_CHANGE_PERIOD
tmrCOMMAND_DELETE
tmrFIRST_FROM_ISR_COMMAND
tmrCOMMAND_START_FROM_ISR
tmrCOMMAND_RESET_FROM_ISR
tmrCOMMAND_STOP_FROM_ISR
tmrCOMMAND_CHANGE_PERIOD_FROM_ISR
xTimerStart(xTimer, xTicksToWait)
BaseType_t xTimerStart( TimerHandle_t xTimer, TickType_t xTicksToWait );
Timer functionality is provided by a timer service/daemon task. Many of the public FreeRTOS timer API
functions send commands to the timer service task through a queue called the timer command queue. The
timer command queue is private to the kernel itself and is not directly accessible to application code. The
length of the timer command queue is set by the configTIMER_QUEUE_LENGTH configuration constant.
xTimerStart() starts a timer that was previously created using the xTimerCreate() API function. If the timer
had already been started and was already in the active state, then xTimerStart() has equivalent functionality to
the xTimerReset() API function.
Starting a timer ensures the timer is in the active state. If the timer is not stopped, deleted, or reset in the mean
time, the callback function associated with the timer will get called n ticks after xTimerStart() was called,
where n is the timers defined period.
It is valid to call xTimerStart() before the scheduler has been started, but when this is done the timer will not
actually start until the scheduler is started, and the timers expiry time will be relative to when the scheduler is
started, not relative to when xTimerStart() was called.
The configUSE_TIMERS configuration constant must be set to 1 for xTimerStart() to be available.
Example usage:

Return pdFAIL will be returned if the start command could not be sent to the timer command queue even
after xTicksToWait ticks had passed. pdPASS will be returned if the command was successfully sent
to the timer command queue. When the command is actually processed will depend on the priority of
the timer service/daemon task relative to other tasks in the system, although the timers expiry time is
relative to when xTimerStart() is actually called. The timer service/daemon task priority is set by the
configTIMER_TASK_PRIORITY configuration constant.
Parameters
• xTimer: The handle of the timer being started/restarted.
• xTicksToWait: Specifies the time, in ticks, that the calling task should be held in the Blocked
state to wait for the start command to be successfully sent to the timer command queue, should the
queue already be full when xTimerStart() was called. xTicksToWait is ignored if xTimerStart() is
called before the scheduler is started.
xTimerStop(xTimer, xTicksToWait)
BaseType_t xTimerStop( TimerHandle_t xTimer, TickType_t xTicksToWait );
xTimerStop() stops a timer that was previously started using either of the The xTimerStart(), xTimerReset(),
xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() or xTimerChangePeriodFromISR()
API functions.
Stopping a timer ensures the timer is not in the active state.
The configUSE_TIMERS configuration constant must be set to 1 for xTimerStop() to be available.
Example usage:
Return pdFAIL will be returned if the stop command could not be sent to the timer command queue even
after xTicksToWait ticks had passed. pdPASS will be returned if the command was successfully sent to
the timer command queue. When the command is actually processed will depend on the priority of the
timer service/daemon task relative to other tasks in the system. The timer service/daemon task priority
is set by the configTIMER_TASK_PRIORITY configuration constant.
Parameters
• xTimer: The handle of the timer being stopped.
state to wait for the stop command to be successfully sent to the timer command queue, should the
queue already be full when xTimerStop() was called. xTicksToWait is ignored if xTimerStop() is
xTimerChangePeriod(xTimer, xNewPeriod, xTicksToWait)
BaseType_t xTimerChangePeriod( TimerHandle_t xTimer, TickType_t xNewPeriod, TickType_t xTick-
sToWait );
xTimerChangePeriod() changes the period of a timer that was previously created using the xTimerCreate()
API function.
xTimerChangePeriod() can be called to change the period of an active or dormant state timer.
The configUSE_TIMERS configuration constant must be set to 1 for xTimerChangePeriod() to be available.
Example usage:

* // This function assumes xTimer has already been created. If the timer
* // referenced by xTimer is already active when it is called, then the timer
* // is deleted. If the timer referenced by xTimer is not active when it is
* // called, then the period of the timer is set to 500ms and the timer is
* // started.
* void vAFunction( TimerHandle_t xTimer )
* {
* if( xTimerIsTimerActive( xTimer ) != pdFALSE ) // or more simply and␣
,→equivalently "if( xTimerIsTimerActive( xTimer ) )"
* {
* // xTimer is already active - delete it.
* xTimerDelete( xTimer );
* }
* else
* {
* // xTimer is not active, change its period to 500ms. This will also
* // cause the timer to start. Block for a maximum of 100 ticks if the
* // change period command cannot immediately be sent to the timer
* // command queue.
* if( xTimerChangePeriod( xTimer, 500 / portTICK_PERIOD_MS, 100 ) ==␣
,→pdPASS )
* {
* // The command was successfully sent.
* }
* else
* {
* // The command could not be sent, even after waiting for 100␣
,→ticks
* // to pass. Take appropriate action here.

* }
* }
* }
*
Return pdFAIL will be returned if the change period command could not be sent to the timer command queue
even after xTicksToWait ticks had passed. pdPASS will be returned if the command was successfully
sent to the timer command queue. When the command is actually processed will depend on the priority
of the timer service/daemon task relative to other tasks in the system. The timer service/daemon task
priority is set by the configTIMER_TASK_PRIORITY configuration constant.
Parameters
• xTimer: The handle of the timer that is having its period changed.
• xNewPeriod: The new period for xTimer. Timer periods are specified in tick periods, so the
constant portTICK_PERIOD_MS can be used to convert a time that has been specified in millisec-
onds. For example, if the timer must expire after 100 ticks, then xNewPeriod should be set to
100. Alternatively, if the timer must expire after 500ms, then xNewPeriod can be set to ( 500 /
portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or equal to 1000.
state to wait for the change period command to be successfully sent to the timer command queue,
should the queue already be full when xTimerChangePeriod() was called. xTicksToWait is ignored
if xTimerChangePeriod() is called before the scheduler is started.
xTimerDelete(xTimer, xTicksToWait)
BaseType_t xTimerDelete( TimerHandle_t xTimer, TickType_t xTicksToWait );
xTimerDelete() deletes a timer that was previously created using the xTimerCreate() API function.
The configUSE_TIMERS configuration constant must be set to 1 for xTimerDelete() to be available.

Example usage:
Return pdFAIL will be returned if the delete command could not be sent to the timer command queue even
after xTicksToWait ticks had passed. pdPASS will be returned if the command was successfully sent to
the timer command queue. When the command is actually processed will depend on the priority of the
timer service/daemon task relative to other tasks in the system. The timer service/daemon task priority
is set by the configTIMER_TASK_PRIORITY configuration constant.
Parameters
• xTimer: The handle of the timer being deleted.
state to wait for the delete command to be successfully sent to the timer command queue, should the
queue already be full when xTimerDelete() was called. xTicksToWait is ignored if xTimerDelete()
is called before the scheduler is started.
See the xTimerChangePeriod() API function example usage scenario.
xTimerReset(xTimer, xTicksToWait)
BaseType_t xTimerReset( TimerHandle_t xTimer, TickType_t xTicksToWait );
xTimerReset() re-starts a timer that was previously created using the xTimerCreate() API function. If the
timer had already been started and was already in the active state, then xTimerReset() will cause the timer
to re-evaluate its expiry time so that it is relative to when xTimerReset() was called. If the timer was in the
dormant state then xTimerReset() has equivalent functionality to the xTimerStart() API function.
Resetting a timer ensures the timer is in the active state. If the timer is not stopped, deleted, or reset in the
mean time, the callback function associated with the timer will get called n ticks after xTimerReset() was
called, where n is the timers defined period.
It is valid to call xTimerReset() before the scheduler has been started, but when this is done the timer will not
actually start until the scheduler is started, and the timers expiry time will be relative to when the scheduler is
started, not relative to when xTimerReset() was called.
The configUSE_TIMERS configuration constant must be set to 1 for xTimerReset() to be available.
Example usage:
* // When a key is pressed, an LCD back-light is switched on. If 5 seconds␣

,→pass
* // without a key being pressed, then the LCD back-light is switched off. In
* // this case, the timer is a one-shot timer.
*
* TimerHandle_t xBacklightTimer = NULL;
*
* // The callback function assigned to the one-shot timer. In this case the
* // parameter is not used.
* void vBacklightTimerCallback( TimerHandle_t pxTimer )
* {
* // The timer expired, therefore 5 seconds must have passed since a key
* // was pressed. Switch off the LCD back-light.
* vSetBacklightState( BACKLIGHT_OFF );
* }
*
* // The key press event handler.
* void vKeyPressEventHandler( char cKey )
* {
* // Ensure the LCD back-light is on, then reset the timer that is
* // responsible for turning the back-light off after 5 seconds of
* // key inactivity. Wait 10 ticks for the command to be successfully sent
* // if it cannot be sent immediately.


* vSetBacklightState( BACKLIGHT_ON );
* if( xTimerReset( xBacklightTimer, 100 ) != pdPASS )
* {
* // The reset command was not executed successfully. Take appropriate
* // action here.
* }
*
* // Perform the rest of the key processing here.
* }
*
* void main( void )
* {
* int32_t x;
*
* // Create then start the one-shot timer that is responsible for turning
* // the back-light off if no keys are pressed within a 5 second period.
* xBacklightTimer = xTimerCreate( "BacklightTimer", // Just a␣
,→text name, not used by the kernel.
* ( 5000 / portTICK_PERIOD_MS), // The␣

,→timer period in ticks.
* pdFALSE, // The timer␣

,→is a one-shot timer.
* 0, // The id is␣
,→not used by the callback so can take any value.
* vBacklightTimerCallback // The␣
,→callback function that switches the LCD back-light off.
* );
*
* if( xBacklightTimer == NULL )
* {
* // The timer was not created.
* }
* else
* {
* // Start the timer. No block time is specified, and even if one was
* // it would be ignored because the scheduler has not yet been
* // started.
* if( xTimerStart( xBacklightTimer, 0 ) != pdPASS )
* {
* // The timer could not be set into the Active state.
* }
* }
*
* // ...
* // ...
*
* // Starting the scheduler will start the timer running as it has already
*
* for( ;; );
* }
*
Return pdFAIL will be returned if the reset command could not be sent to the timer command queue even
after xTicksToWait ticks had passed. pdPASS will be returned if the command was successfully sent
to the timer command queue. When the command is actually processed will depend on the priority of
the timer service/daemon task relative to other tasks in the system, although the timers expiry time is
relative to when xTimerStart() is actually called. The timer service/daemon task priority is set by the

configTIMER_TASK_PRIORITY configuration constant.

Parameters
• xTimer: The handle of the timer being reset/started/restarted.
state to wait for the reset command to be successfully sent to the timer command queue, should the
queue already be full when xTimerReset() was called. xTicksToWait is ignored if xTimerReset() is
xTimerStartFromISR(xTimer, pxHigherPriorityTaskWoken)
BaseType_t xTimerStartFromISR( TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken );
A version of xTimerStart() that can be called from an interrupt service routine.
Example usage:
* // This scenario assumes xBacklightTimer has already been created. When a

* // key is pressed, an LCD back-light is switched on. If 5 seconds pass
* // this case, the timer is a one-shot timer, and unlike the example given for
* // the xTimerReset() function, the key press event handler is an interrupt
* // service routine.
*
* {
* }
*
* // The key press interrupt service routine.
* void vKeyPressEventInterruptHandler( void )
* {
* BaseType_t xHigherPriorityTaskWoken = pdFALSE;
*
* // Ensure the LCD back-light is on, then restart the timer that is
* // key inactivity. This is an interrupt service routine so can only
* // call FreeRTOS API functions that end in "FromISR".
*
* // xTimerStartFromISR() or xTimerResetFromISR() could be called here
* // as both cause the timer to re-calculate its expiry time.
* // xHigherPriorityTaskWoken was initialised to pdFALSE when it was
* // declared (in this function).
* if( xTimerStartFromISR( xBacklightTimer, &xHigherPriorityTaskWoken ) !=␣
,→pdPASS )
* {
* // The start command was not executed successfully. Take appropriate
* // action here.
* }
*
*
* // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch
* // should be performed. The syntax required to perform a context switch
* // from inside an ISR varies from port to port, and from compiler to
* // compiler. Inspect the demos for the port you are using to find the
* // actual syntax required.
* if( xHigherPriorityTaskWoken != pdFALSE )
* {
* // Call the interrupt safe yield function here (actual function


* // depends on the FreeRTOS port being used).
* }
* }
*
Return pdFAIL will be returned if the start command could not be sent to the timer command queue. pdPASS
will be returned if the command was successfully sent to the timer command queue. When the command
is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in
the system, although the timers expiry time is relative to when xTimerStartFromISR() is actually called.
The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration
constant.
Parameters
• xTimer: The handle of the timer being started/restarted.
• pxHigherPriorityTaskWoken: The timer service/daemon task spends most of its time in
the Blocked state, waiting for messages to arrive on the timer command queue. Calling xTimer-
StartFromISR() writes a message to the timer command queue, so has the potential to transition
the timer service/daemon task out of the Blocked state. If calling xTimerStartFromISR() causes
the timer service/daemon task to leave the Blocked state, and the timer service/ daemon task has
a priority equal to or greater than the currently executing task (the task that was interrupted), then
*pxHigherPriorityTaskWoken will get set to pdTRUE internally within the xTimerStartFromISR()
function. If xTimerStartFromISR() sets this value to pdTRUE then a context switch should be per-
formed before the interrupt exits.
xTimerStopFromISR(xTimer, pxHigherPriorityTaskWoken)
BaseType_t xTimerStopFromISR( TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken );
A version of xTimerStop() that can be called from an interrupt service routine.
Example usage:
* // This scenario assumes xTimer has already been created and started. When
* // an interrupt occurs, the timer should be simply stopped.
*
* // The interrupt service routine that stops the timer.
* void vAnExampleInterruptServiceRoutine( void )
* {
*
* // The interrupt has occurred - simply stop the timer.
* // xHigherPriorityTaskWoken was set to pdFALSE where it was defined
* // (within this function). As this is an interrupt service routine, only
* // FreeRTOS API functions that end in "FromISR" can be used.
* if( xTimerStopFromISR( xTimer, &xHigherPriorityTaskWoken ) != pdPASS )
* {
* // The stop command was not executed successfully. Take appropriate
* // action here.
* }
*
* {
* }
* }
*

Return pdFAIL will be returned if the stop command could not be sent to the timer command queue. pdPASS
is actually processed will depend on the priority of the timer service/daemon task relative to other tasks
in the system. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY
configuration constant.
Parameters
• xTimer: The handle of the timer being stopped.
StopFromISR() writes a message to the timer command queue, so has the potential to transition
the timer service/daemon task out of the Blocked state. If calling xTimerStopFromISR() causes
*pxHigherPriorityTaskWoken will get set to pdTRUE internally within the xTimerStopFromISR()
function. If xTimerStopFromISR() sets this value to pdTRUE then a context switch should be per-
formed before the interrupt exits.
xTimerChangePeriodFromISR(xTimer, xNewPeriod, pxHigherPriorityTaskWoken)
BaseType_t xTimerChangePeriodFromISR( TimerHandle_t xTimer, TickType_t xNewPeriod, BaseType_t
*pxHigherPriorityTaskWoken );
A version of xTimerChangePeriod() that can be called from an interrupt service routine.
Example usage:
* // This scenario assumes xTimer has already been created and started. When
* // an interrupt occurs, the period of xTimer should be changed to 500ms.
*
* // The interrupt service routine that changes the period of xTimer.
* void vAnExampleInterruptServiceRoutine( void )
* {
*
* // The interrupt has occurred - change the period of xTimer to 500ms.
* // xHigherPriorityTaskWoken was set to pdFALSE where it was defined
* // (within this function). As this is an interrupt service routine, only
* // FreeRTOS API functions that end in "FromISR" can be used.
* if( xTimerChangePeriodFromISR( xTimer, &xHigherPriorityTaskWoken ) !=␣
,→pdPASS )
* {
* // The command to change the timers period was not executed
* // successfully. Take appropriate action here.
* }
*
* {
* }
* }
*
Return pdFAIL will be returned if the command to change the timers period could not be sent to the timer
command queue. pdPASS will be returned if the command was successfully sent to the timer command
queue. When the command is actually processed will depend on the priority of the timer service/daemon
task relative to other tasks in the system. The timer service/daemon task priority is set by the config-
TIMER_TASK_PRIORITY configuration constant.

Parameters
• xTimer: The handle of the timer that is having its period changed.
• xNewPeriod: The new period for xTimer. Timer periods are specified in tick periods, so the
constant portTICK_PERIOD_MS can be used to convert a time that has been specified in millisec-
onds. For example, if the timer must expire after 100 ticks, then xNewPeriod should be set to
100. Alternatively, if the timer must expire after 500ms, then xNewPeriod can be set to ( 500 /
portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or equal to 1000.
ChangePeriodFromISR() writes a message to the timer command queue, so has the potential to
transition the timer service/ daemon task out of the Blocked state. If calling xTimerChangePe-
riodFromISR() causes the timer service/daemon task to leave the Blocked state, and the timer
service/daemon task has a priority equal to or greater than the currently executing task (the task
that was interrupted), then *pxHigherPriorityTaskWoken will get set to pdTRUE internally within
the xTimerChangePeriodFromISR() function. If xTimerChangePeriodFromISR() sets this value to
pdTRUE then a context switch should be performed before the interrupt exits.
xTimerResetFromISR(xTimer, pxHigherPriorityTaskWoken)
BaseType_t xTimerResetFromISR( TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken );
A version of xTimerReset() that can be called from an interrupt service routine.
Example usage:
* // This scenario assumes xBacklightTimer has already been created. When a

* // key is pressed, an LCD back-light is switched on. If 5 seconds pass
* // this case, the timer is a one-shot timer, and unlike the example given for
* // the xTimerReset() function, the key press event handler is an interrupt
* // service routine.
*
* {
* }
*
* // The key press interrupt service routine.
* void vKeyPressEventInterruptHandler( void )
* {
*
* // Ensure the LCD back-light is on, then reset the timer that is
* // key inactivity. This is an interrupt service routine so can only
* // call FreeRTOS API functions that end in "FromISR".
*
* // xTimerStartFromISR() or xTimerResetFromISR() could be called here
* // as both cause the timer to re-calculate its expiry time.
* // xHigherPriorityTaskWoken was initialised to pdFALSE when it was
* // declared (in this function).
* if( xTimerResetFromISR( xBacklightTimer, &xHigherPriorityTaskWoken ) !=␣
,→pdPASS )
* {
* // The reset command was not executed successfully. Take appropriate
* // action here.
* }
*


*
* {
* }
* }
*
Return pdFAIL will be returned if the reset command could not be sent to the timer command queue. pdPASS
is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in
the system, although the timers expiry time is relative to when xTimerResetFromISR() is actually called.
The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration
constant.
Parameters
• xTimer: The handle of the timer that is to be started, reset, or restarted.
ResetFromISR() writes a message to the timer command queue, so has the potential to transition
the timer service/daemon task out of the Blocked state. If calling xTimerResetFromISR() causes
*pxHigherPriorityTaskWoken will get set to pdTRUE internally within the xTimerResetFromISR()
function. If xTimerResetFromISR() sets this value to pdTRUE then a context switch should be
performed before the interrupt exits.
Type Definitions
typedef struct tmrTimerControl *TimerHandle_t
typedef void (*TimerCallbackFunction_t)(TimerHandle_t xTimer)
typedef void (*PendedFunction_t)(void *, uint32_t)
Event Group API
Header File
• components/freertos/FreeRTOS-Kernel/include/freertos/event_groups.h
Functions
EventGroupHandle_t xEventGroupCreate(void)
Create a new event group.
Internally, within the FreeRTOS implementation, event groups use a [small] block of memory, in which
the event group s structure is stored. If an event groups is created using xEventGroupCreate() then the
required memory is automatically dynamically allocated inside the xEventGroupCreate() function. (see
https://www.FreeRTOS.org/a00111.html). If an event group is created using xEventGroupCreateStatic() then
the application writer must instead provide the memory that will get used by the event group. xEventGroupCre-
ateStatic() therefore allows an event group to be created without using any dynamic memory allocation.
Although event groups are not related to ticks, for internal implementation reasons the number of bits avail-
able for use in an event group is dependent on the configUSE_16_BIT_TICKS setting in FreeRTOSConfig.h.

If configUSE_16_BIT_TICKS is 1 then each event group contains 8 usable bits (bit 0 to bit 7). If confi-
gUSE_16_BIT_TICKS is set to 0 then each event group has 24 usable bits (bit 0 to bit 23). The EventBits_t
type is used to store event bits within an event group.
Example usage:
// Declare a variable to hold the created event group.

EventGroupHandle_t xCreatedEventGroup;
// Attempt to create the event group.

xCreatedEventGroup = xEventGroupCreate();
// Was the event group created successfully?

if( xCreatedEventGroup == NULL )
{
// The event group was not created because there was insufficient
// FreeRTOS heap available.
}
else
{
// The event group was created.
}
Return If the event group was created then a handle to the event group is returned. If there was insufficient
FreeRTOS heap available to create the event group then NULL is returned. See https://www.FreeRTOS.
org/a00111.html
EventGroupHandle_t xEventGroupCreateStatic(StaticEventGroup_t *pxEventGroupBuffer)
Create a new event group.
Internally, within the FreeRTOS implementation, event groups use a [small] block of memory, in which
the event group s structure is stored. If an event groups is created using xEventGroupCreate() then the
required memory is automatically dynamically allocated inside the xEventGroupCreate() function. (see
https://www.FreeRTOS.org/a00111.html). If an event group is created using xEventGroupCreateStatic() then
the application writer must instead provide the memory that will get used by the event group. xEventGroupCre-
ateStatic() therefore allows an event group to be created without using any dynamic memory allocation.
Although event groups are not related to ticks, for internal implementation reasons the number of bits avail-
able for use in an event group is dependent on the configUSE_16_BIT_TICKS setting in FreeRTOSConfig.h.
If configUSE_16_BIT_TICKS is 1 then each event group contains 8 usable bits (bit 0 to bit 7). If confi-
gUSE_16_BIT_TICKS is set to 0 then each event group has 24 usable bits (bit 0 to bit 23). The EventBits_t
type is used to store event bits within an event group.
Example usage:
// StaticEventGroup_t is a publicly accessible structure that has the same

// size and alignment requirements as the real event group structure. It is
// provided as a mechanism for applications to know the size of the event
// group (which is dependent on the architecture and configuration file
// settings) without breaking the strict data hiding policy by exposing the
// real event group internals. This StaticEventGroup_t variable is passed
// into the xSemaphoreCreateEventGroupStatic() function and is used to store
// the event group's data structures
StaticEventGroup_t xEventGroupBuffer;
// Create the event group without dynamically allocating any memory.

xEventGroup = xEventGroupCreateStatic( &xEventGroupBuffer );
Return If the event group was created then a handle to the event group is returned. If pxEventGroupBuffer
was NULL then NULL is returned.
Parameters
• pxEventGroupBuffer: pxEventGroupBuffer must point to a variable of type StaticEvent-
Group_t, which will be then be used to hold the event group s data structures, removing the need
for the memory to be allocated dynamically.

EventBits_t xEventGroupWaitBits(EventGroupHandle_t xEventGroup, const EventBits_t uxBit-

sToWaitFor, const BaseType_t xClearOnExit, const Base-
Type_t xWaitForAllBits, TickType_t xTicksToWait)
[Potentially] block to wait for one or more bits to be set within a previously created event group.
This function cannot be called from an interrupt.
Example usage:
#define BIT_0 ( 1 << 0 )

#define BIT_4 ( 1 << 4 )
void aFunction( EventGroupHandle_t xEventGroup )

{
EventBits_t uxBits;
const TickType_t xTicksToWait = 100 / portTICK_PERIOD_MS;
// Wait a maximum of 100ms for either bit 0 or bit 4 to be set within

// the event group. Clear the bits before exiting.
uxBits = xEventGroupWaitBits(
xEventGroup, // The event group being tested.
BIT_0 | BIT_4, // The bits within the event group to wait␣
,→for.
pdTRUE, // BIT_0 and BIT_4 should be cleared before␣

,→returning.
pdFALSE, // Don't wait for both bits, either bit will␣

,→do.
xTicksToWait ); // Wait a maximum of 100ms for either bit to␣

,→be set.
if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )

{
// xEventGroupWaitBits() returned because both bits were set.
}
else if( ( uxBits & BIT_0 ) != 0 )
{
// xEventGroupWaitBits() returned because just BIT_0 was set.
}
{
// xEventGroupWaitBits() returned because just BIT_4 was set.
}
else
{
// xEventGroupWaitBits() returned because xTicksToWait ticks passed
// without either BIT_0 or BIT_4 becoming set.
}
}
Return The value of the event group at the time either the bits being waited for became set, or the block time
expired. Test the return value to know which bits were set. If xEventGroupWaitBits() returned because
its timeout expired then not all the bits being waited for will be set. If xEventGroupWaitBits() returned
because the bits it was waiting for were set then the returned value is the event group value before any
bits were automatically cleared in the case that xClearOnExit parameter was set to pdTRUE.
Parameters
• xEventGroup: The event group in which the bits are being tested. The event group must have
previously been created using a call to xEventGroupCreate().
• uxBitsToWaitFor: A bitwise value that indicates the bit or bits to test inside the event group.
For example, to wait for bit 0 and/or bit 2 set uxBitsToWaitFor to 0x05. To wait for bits 0 and/or
bit 1 and/or bit 2 set uxBitsToWaitFor to 0x07. Etc.
• xClearOnExit: If xClearOnExit is set to pdTRUE then any bits within uxBitsToWaitFor that
are set within the event group will be cleared before xEventGroupWaitBits() returns if the wait
condition was met (if the function returns for a reason other than a timeout). If xClearOnExit is set to

pdFALSE then the bits set in the event group are not altered when the call to xEventGroupWaitBits()
returns.
• xWaitForAllBits: If xWaitForAllBits is set to pdTRUE then xEventGroupWaitBits() will re-
turn when either all the bits in uxBitsToWaitFor are set or the specified block time expires. If
xWaitForAllBits is set to pdFALSE then xEventGroupWaitBits() will return when any one of the
bits set in uxBitsToWaitFor is set or the specified block time expires. The block time is specified by
the xTicksToWait parameter.
• xTicksToWait: The maximum amount of time (specified in ticks ) to wait for one/all (de-
pending on the xWaitForAllBits value) of the bits specified by uxBitsToWaitFor to become set.
EventBits_t xEventGroupClearBits(EventGroupHandle_t xEventGroup, const EventBits_t uxBitsTo-
Clear)
Clear bits within an event group. This function cannot be called from an interrupt.
Example usage:
#define BIT_0 ( 1 << 0 )

#define BIT_4 ( 1 << 4 )

{
EventBits_t uxBits;
// Clear bit 0 and bit 4 in xEventGroup.

uxBits = xEventGroupClearBits(
xEventGroup, // The event group being updated.
BIT_0 | BIT_4 );// The bits being cleared.

{
// Both bit 0 and bit 4 were set before xEventGroupClearBits() was
// called. Both will now be clear (not set).
}
{
// Bit 0 was set before xEventGroupClearBits() was called. It will
// now be clear.
}
{
// Bit 4 was set before xEventGroupClearBits() was called. It will
// now be clear.
}
else
{
// Neither bit 0 nor bit 4 were set in the first place.
}
}
Return The value of the event group before the specified bits were cleared.
Parameters
• xEventGroup: The event group in which the bits are to be cleared.
• uxBitsToClear: A bitwise value that indicates the bit or bits to clear in the event group. For
example, to clear bit 3 only, set uxBitsToClear to 0x08. To clear bit 3 and bit 0 set uxBitsToClear
to 0x09.
EventBits_t xEventGroupSetBits(EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet)
Set bits within an event group. This function cannot be called from an interrupt. xEventGroupSetBits-
FromISR() is a version that can be called from an interrupt.
Setting bits in an event group will automatically unblock tasks that are blocked waiting for the bits.
Example usage:

#define BIT_0 ( 1 << 0 )

#define BIT_4 ( 1 << 4 )

{
EventBits_t uxBits;
// Set bit 0 and bit 4 in xEventGroup.

uxBits = xEventGroupSetBits(
BIT_0 | BIT_4 );// The bits being set.

{
// Both bit 0 and bit 4 remained set when the function returned.
}
{
// Bit 0 remained set when the function returned, but bit 4 was
// cleared. It might be that bit 4 was cleared automatically as a
// task that was waiting for bit 4 was removed from the Blocked
// state.
}
{
// Bit 4 remained set when the function returned, but bit 0 was
// cleared. It might be that bit 0 was cleared automatically as a
// task that was waiting for bit 0 was removed from the Blocked
// state.
}
else
{
// Neither bit 0 nor bit 4 remained set. It might be that a task
// was waiting for both of the bits to be set, and the bits were
// cleared as the task left the Blocked state.
}
}
Return The value of the event group at the time the call to xEventGroupSetBits() returns. There are two
reasons why the returned value might have the bits specified by the uxBitsToSet parameter cleared. First,
if setting a bit results in a task that was waiting for the bit leaving the blocked state then it is possible the
bit will be cleared automatically (see the xClearBitOnExit parameter of xEventGroupWaitBits()). Sec-
ond, any unblocked (or otherwise Ready state) task that has a priority above that of the task that called
xEventGroupSetBits() will execute and may change the event group value before the call to xEvent-
GroupSetBits() returns.
Parameters
• xEventGroup: The event group in which the bits are to be set.
• uxBitsToSet: A bitwise value that indicates the bit or bits to set. For example, to set bit 3 only,
set uxBitsToSet to 0x08. To set bit 3 and bit 0 set uxBitsToSet to 0x09.
EventBits_t xEventGroupSync(EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet,
const EventBits_t uxBitsToWaitFor, TickType_t xTicksToWait)
Atomically set bits within an event group, then wait for a combination of bits to be set within the same event
group. This functionality is typically used to synchronise multiple tasks, where each task has to wait for the
other tasks to reach a synchronisation point before proceeding.
This function cannot be used from an interrupt.
The function will return before its block time expires if the bits specified by the uxBitsToWait parameter are
set, or become set within that time. In this case all the bits specified by uxBitsToWait will be automatically
cleared before the function returns.
Example usage:

// Bits used by the three tasks.

#define TASK_0_BIT ( 1 << 0 )
#define ALL_SYNC_BITS ( TASK_0_BIT | TASK_1_BIT | TASK_2_BIT )
// Use an event group to synchronise three tasks. It is assumed this event

// group has already been created elsewhere.
EventGroupHandle_t xEventBits;
void vTask0( void *pvParameters )

{
EventBits_t uxReturn;
TickType_t xTicksToWait = 100 / portTICK_PERIOD_MS;
for( ;; )
{
// Perform task functionality here.
// Set bit 0 in the event flag to note this task has reached the
// sync point. The other two tasks will set the other two bits defined
// by ALL_SYNC_BITS. All three tasks have reached the synchronisation
// point when all the ALL_SYNC_BITS are set. Wait a maximum of 100ms
// for this to happen.
uxReturn = xEventGroupSync( xEventBits, TASK_0_BIT, ALL_SYNC_BITS,␣
,→xTicksToWait );
if( ( uxReturn & ALL_SYNC_BITS ) == ALL_SYNC_BITS )

{
// All three tasks reached the synchronisation point before the call
// to xEventGroupSync() timed out.
}
}
}

{
for( ;; )
{
// synchronisation point. The other two tasks will set the other two
// bits defined by ALL_SYNC_BITS. All three tasks have reached the
// synchronisation point when all the ALL_SYNC_BITS are set. Wait
// indefinitely for this to happen.
xEventGroupSync( xEventBits, TASK_1_BIT, ALL_SYNC_BITS, portMAX_DELAY );
// xEventGroupSync() was called with an indefinite block time, so

// this task will only reach here if the synchronisation was made by all
// three tasks, so there is no need to test the return value.
}
}

{
for( ;; )
{


// synchronisation point. The other two tasks will set the other two
// bits defined by ALL_SYNC_BITS. All three tasks have reached the
// synchronisation point when all the ALL_SYNC_BITS are set. Wait
// indefinitely for this to happen.
xEventGroupSync( xEventBits, TASK_2_BIT, ALL_SYNC_BITS, portMAX_DELAY );
// xEventGroupSync() was called with an indefinite block time, so

// this task will only reach here if the synchronisation was made by all
// three tasks, so there is no need to test the return value.
}
}
Return The value of the event group at the time either the bits being waited for became set, or the block time
expired. Test the return value to know which bits were set. If xEventGroupSync() returned because its
timeout expired then not all the bits being waited for will be set. If xEventGroupSync() returned because
all the bits it was waiting for were set then the returned value is the event group value before any bits were
automatically cleared.
Parameters
• xEventGroup: The event group in which the bits are being tested. The event group must have
previously been created using a call to xEventGroupCreate().
• uxBitsToSet: The bits to set in the event group before determining if, and possibly waiting for,
all the bits specified by the uxBitsToWait parameter are set.
• uxBitsToWaitFor: A bitwise value that indicates the bit or bits to test inside the event group.
For example, to wait for bit 0 and bit 2 set uxBitsToWaitFor to 0x05. To wait for bits 0 and bit 1
and bit 2 set uxBitsToWaitFor to 0x07. Etc.
• xTicksToWait: The maximum amount of time (specified in ticks ) to wait for all of the bits
specified by uxBitsToWaitFor to become set.
EventBits_t xEventGroupGetBitsFromISR(EventGroupHandle_t xEventGroup)
A version of xEventGroupGetBits() that can be called from an ISR.
Return The event group bits at the time xEventGroupGetBitsFromISR() was called.
Parameters
• xEventGroup: The event group being queried.
void vEventGroupDelete(EventGroupHandle_t xEventGroup)
Delete an event group that was previously created by a call to xEventGroupCreate(). Tasks that are blocked on
the event group will be unblocked and obtain 0 as the event group s value.
Parameters
• xEventGroup: The event group being deleted.
Macros
xEventGroupClearBitsFromISR(xEventGroup, uxBitsToClear)
A version of xEventGroupClearBits() that can be called from an interrupt.
Setting bits in an event group is not a deterministic operation because there are an unknown number of tasks
that may be waiting for the bit or bits being set. FreeRTOS does not allow nondeterministic operations to be
performed while interrupts are disabled, so protects event groups that are accessed from tasks by suspending
the scheduler rather than disabling interrupts. As a result event groups cannot be accessed directly from an
interrupt service routine. Therefore xEventGroupClearBitsFromISR() sends a message to the timer task to
have the clear operation performed in the context of the timer task.
Example usage:
#define BIT_0 ( 1 << 0 )

#define BIT_4 ( 1 << 4 )
// An event group which it is assumed has already been created by a call to

// xEventGroupCreate().


EventGroupHandle_t xEventGroup;
void anInterruptHandler( void )

{
// Clear bit 0 and bit 4 in xEventGroup.
xResult = xEventGroupClearBitsFromISR(
BIT_0 | BIT_4 ); // The bits being set.
if( xResult == pdPASS )

{
// The message was posted successfully.
}
}
Return If the request to execute the function was posted successfully then pdPASS is returned, otherwise
pdFALSE is returned. pdFALSE will be returned if the timer service queue was full.
Parameters
• xEventGroup: The event group in which the bits are to be cleared.
• uxBitsToClear: A bitwise value that indicates the bit or bits to clear. For example, to clear bit
3 only, set uxBitsToClear to 0x08. To clear bit 3 and bit 0 set uxBitsToClear to 0x09.
xEventGroupSetBitsFromISR(xEventGroup, uxBitsToSet, pxHigherPriorityTaskWoken)
A version of xEventGroupSetBits() that can be called from an interrupt.
Setting bits in an event group is not a deterministic operation because there are an unknown number of tasks
that may be waiting for the bit or bits being set. FreeRTOS does not allow nondeterministic operations to be
performed in interrupts or from critical sections. Therefore xEventGroupSetBitsFromISR() sends a message
to the timer task to have the set operation performed in the context of the timer task - where a scheduler lock
is used in place of a critical section.
Example usage:
#define BIT_0 ( 1 << 0 )
#define BIT_4 ( 1 << 4 )
// An event group which it is assumed has already been created by a call to

// xEventGroupCreate().
EventGroupHandle_t xEventGroup;
void anInterruptHandler( void )

{
BaseType_t xHigherPriorityTaskWoken, xResult;
// xHigherPriorityTaskWoken must be initialised to pdFALSE.

// Set bit 0 and bit 4 in xEventGroup.

xResult = xEventGroupSetBitsFromISR(
BIT_0 | BIT_4 // The bits being set.
&xHigherPriorityTaskWoken );
// Was the message posted successfully?

if( xResult == pdPASS )
{
// If xHigherPriorityTaskWoken is now set to pdTRUE then a context
// switch should be requested. The macro used is port specific and
// will be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() -
// refer to the documentation page for the port being used.
portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
}


}
Return If the request to execute the function was posted successfully then pdPASS is returned, otherwise
pdFALSE is returned. pdFALSE will be returned if the timer service queue was full.
Parameters
• xEventGroup: The event group in which the bits are to be set.
• uxBitsToSet: A bitwise value that indicates the bit or bits to set. For example, to set bit 3 only,
set uxBitsToSet to 0x08. To set bit 3 and bit 0 set uxBitsToSet to 0x09.
• pxHigherPriorityTaskWoken: As mentioned above, calling this function will result in a
message being sent to the timer daemon task. If the priority of the timer daemon task is higher than
the priority of the currently running task (the task the interrupt interrupted) then *pxHigherPrior-
ityTaskWoken will be set to pdTRUE by xEventGroupSetBitsFromISR(), indicating that a context
switch should be requested before the interrupt exits. For that reason *pxHigherPriorityTaskWoken
must be initialised to pdFALSE. See the example code below.
xEventGroupGetBits(xEventGroup)
Returns the current value of the bits in an event group. This function cannot be used from an interrupt.
Return The event group bits at the time xEventGroupGetBits() was called.
Parameters
• xEventGroup: The event group being queried.
Type Definitions
typedef struct EventGroupDef_t *EventGroupHandle_t
typedef TickType_t EventBits_t
Stream Buffer API
Header File
• components/freertos/FreeRTOS-Kernel/include/freertos/stream_buffer.h
Functions
size_t xStreamBufferSend(StreamBufferHandle_t xStreamBuffer, const void *pvTxData, size_t
xDataLengthBytes, TickType_t xTicksToWait)
Sends bytes to a stream buffer. The bytes are copied into the stream buffer.
***NOTE***: Uniquely among FreeRTOS objects, the stream buffer implementation (so also the message
buffer implementation, as message buffers are built on top of stream buffers) assumes there is only one task
or interrupt that will write to the buffer (the writer), and only one task or interrupt that will read from the
buffer (the reader). It is safe for the writer and reader to be different tasks or interrupts, but, unlike other
FreeRTOS objects, it is not safe to have multiple different writers or multiple different readers. If there are to
be multiple different writers then the application writer must place each call to a writing API function (such
as xStreamBufferSend()) inside a critical section and set the send block time to 0. Likewise, if there are to be
multiple different readers then the application writer must place each call to a reading API function (such as
xStreamBufferReceive()) inside a critical section and set the receive block time to 0.
Use xStreamBufferSend() to write to a stream buffer from a task. Use xStreamBufferSendFromISR() to write
to a stream buffer from an interrupt service routine (ISR).
Example use:
void vAFunction( StreamBufferHandle_t xStreamBuffer )
{
size_t xBytesSent;
uint8_t ucArrayToSend[] = { 0, 1, 2, 3 };
char *pcStringToSend = "String to send";
const TickType_t x100ms = pdMS_TO_TICKS( 100 );

// Send an array to the stream buffer, blocking for a maximum of 100ms to

// wait for enough space to be available in the stream buffer.
xBytesSent = xStreamBufferSend( xStreamBuffer, ( void * ) ucArrayToSend,␣
,→sizeof( ucArrayToSend ), x100ms );
if( xBytesSent != sizeof( ucArrayToSend ) )

{
// The call to xStreamBufferSend() times out before there was enough
// space in the buffer for the data to be written, but it did
// successfully write xBytesSent bytes.
}
// Send the string to the stream buffer. Return immediately if there is not
// enough space in the buffer.
xBytesSent = xStreamBufferSend( xStreamBuffer, ( void * ) pcStringToSend,␣
,→strlen( pcStringToSend ), 0 );
if( xBytesSent != strlen( pcStringToSend ) )

{
// The entire string could not be added to the stream buffer because
// there was not enough free space in the buffer, but xBytesSent bytes
// were sent. Could try again to send the remaining bytes.
}
}
Return The number of bytes written to the stream buffer. If a task times out before it can write all xDataL-
engthBytes into the buffer it will still write as many bytes as possible.
Parameters
• xStreamBuffer: The handle of the stream buffer to which a stream is being sent.
• pvTxData: A pointer to the buffer that holds the bytes to be copied into the stream buffer.
• xDataLengthBytes: The maximum number of bytes to copy from pvTxData into the stream
buffer.
• xTicksToWait: The maximum amount of time the task should remain in the Blocked state to wait
for enough space to become available in the stream buffer, should the stream buffer contain too little
space to hold the another xDataLengthBytes bytes. The block time is specified in tick periods, so
the absolute time it represents is dependent on the tick frequency. The macro pdMS_TO_TICKS()
can be used to convert a time specified in milliseconds into a time specified in ticks. Setting xTick-
sToWait to portMAX_DELAY will cause the task to wait indefinitely (without timing out), provided
INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. If a task times out before it can write
all xDataLengthBytes into the buffer it will still write as many bytes as possible. A task does not use
any CPU time when it is in the blocked state.
size_t xStreamBufferSendFromISR(StreamBufferHandle_t xStreamBuffer, const void *pvTxData,
size_t xDataLengthBytes, BaseType_t *const pxHigherPriori-
tyTaskWoken)
Interrupt safe version of the API function that sends a stream of bytes to the stream buffer.
Use xStreamBufferSend() to write to a stream buffer from a task. Use xStreamBufferSendFromISR() to write
to a stream buffer from an interrupt service routine (ISR).
Example use:

// A stream buffer that has already been created.

StreamBufferHandle_t xStreamBuffer;
void vAnInterruptServiceRoutine( void )

{
size_t xBytesSent;
BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE.
// Attempt to send the string to the stream buffer.

xBytesSent = xStreamBufferSendFromISR( xStreamBuffer,
( void * ) pcStringToSend,
strlen( pcStringToSend ),

{
// There was not enough free space in the stream buffer for the entire
// string to be written, ut xBytesSent bytes were written.
}
// If xHigherPriorityTaskWoken was set to pdTRUE inside

// xStreamBufferSendFromISR() then a task that has a priority above the
// priority of the currently executing task was unblocked and a context
// switch should be performed to ensure the ISR returns to the unblocked
// task. In most FreeRTOS ports this is done by simply passing
// xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the
// variables value, and perform the context switch if necessary. Check the
// documentation for the port in use for port specific instructions.
taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );
}
Return The number of bytes actually written to the stream buffer, which will be less than xDataLengthBytes
if the stream buffer didn t have enough free space for all the bytes to be written.
Parameters
• xStreamBuffer: The handle of the stream buffer to which a stream is being sent.
• pvTxData: A pointer to the data that is to be copied into the stream buffer.
• xDataLengthBytes: The maximum number of bytes to copy from pvTxData into the stream
buffer.
• pxHigherPriorityTaskWoken: It is possible that a stream buffer will have a task blocked
on it waiting for data. Calling xStreamBufferSendFromISR() can make data available, and so cause
a task that was waiting for data to leave the Blocked state. If calling xStreamBufferSendFromISR()
causes a task to leave the Blocked state, and the unblocked task has a priority higher than the cur-
rently executing task (the task that was interrupted), then, internally, xStreamBufferSendFromISR()
will set *pxHigherPriorityTaskWoken to pdTRUE. If xStreamBufferSendFromISR() sets this value
to pdTRUE, then normally a context switch should be performed before the interrupt is exited. This
will ensure that the interrupt returns directly to the highest priority Ready state task. *pxHigherPri-
orityTaskWoken should be set to pdFALSE before it is passed into the function. See the example
code below for an example.
size_t xStreamBufferReceive(StreamBufferHandle_t xStreamBuffer, void *pvRxData, size_t xBuffer-
LengthBytes, TickType_t xTicksToWait)
Receives bytes from a stream buffer.

Use xStreamBufferReceive() to read from a stream buffer from a task. Use xStreamBufferReceiveFromISR()
to read from a stream buffer from an interrupt service routine (ISR).
Example use:
void vAFunction( StreamBuffer_t xStreamBuffer )
{
uint8_t ucRxData[ 20 ];
size_t xReceivedBytes;
const TickType_t xBlockTime = pdMS_TO_TICKS( 20 );
// Receive up to another sizeof( ucRxData ) bytes from the stream buffer.

// Wait in the Blocked state (so not using any CPU processing time) for a
// maximum of 100ms for the full sizeof( ucRxData ) number of bytes to be
// available.
xReceivedBytes = xStreamBufferReceive( xStreamBuffer,
( void * ) ucRxData,
sizeof( ucRxData ),
xBlockTime );
if( xReceivedBytes > 0 )

{
// A ucRxData contains another xRecievedBytes bytes of data, which can
// be processed here....
}
}
Return The number of bytes actually read from the stream buffer, which will be less than xBufferLengthBytes
if the call to xStreamBufferReceive() timed out before xBufferLengthBytes were available.
Parameters
• xStreamBuffer: The handle of the stream buffer from which bytes are to be received.
• pvRxData: A pointer to the buffer into which the received bytes will be copied.
• xBufferLengthBytes: The length of the buffer pointed to by the pvRxData parameter. This
sets the maximum number of bytes to receive in one call. xStreamBufferReceive will return as many
bytes as possible up to a maximum set by xBufferLengthBytes.
• xTicksToWait: The maximum amount of time the task should remain in the Blocked state to
wait for data to become available if the stream buffer is empty. xStreamBufferReceive() will return
immediately if xTicksToWait is zero. The block time is specified in tick periods, so the absolute
time it represents is dependent on the tick frequency. The macro pdMS_TO_TICKS() can be used
to convert a time specified in milliseconds into a time specified in ticks. Setting xTicksToWait
to portMAX_DELAY will cause the task to wait indefinitely (without timing out), provided IN-
CLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. A task does not use any CPU time when
it is in the Blocked state.
size_t xStreamBufferReceiveFromISR(StreamBufferHandle_t xStreamBuffer, void *pvRxData,
size_t xBufferLengthBytes, BaseType_t *const pxHigher-
PriorityTaskWoken)
An interrupt safe version of the API function that receives bytes from a stream buffer.
Use xStreamBufferReceive() to read bytes from a stream buffer from a task. Use xStreamBufferReceive-
FromISR() to read bytes from a stream buffer from an interrupt service routine (ISR).
Example use:
// A stream buffer that has already been created.
StreamBuffer_t xStreamBuffer;

{


// Receive the next stream from the stream buffer.

xReceivedBytes = xStreamBufferReceiveFromISR( xStreamBuffer,
sizeof( ucRxData ),

{
// ucRxData contains xReceivedBytes read from the stream buffer.
// Process the stream here....
}

// xStreamBufferReceiveFromISR() then a task that has a priority above the
// xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the
taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );
}
Return The number of bytes read from the stream buffer, if any.
Parameters
• xStreamBuffer: The handle of the stream buffer from which a stream is being received.
• pvRxData: A pointer to the buffer into which the received bytes are copied.
sets the maximum number of bytes to receive in one call. xStreamBufferReceive will return as many
bytes as possible up to a maximum set by xBufferLengthBytes.
• pxHigherPriorityTaskWoken: It is possible that a stream buffer will have a task blocked
on it waiting for space to become available. Calling xStreamBufferReceiveFromISR() can make
space available, and so cause a task that is waiting for space to leave the Blocked state. If call-
ing xStreamBufferReceiveFromISR() causes a task to leave the Blocked state, and the unblocked
task has a priority higher than the currently executing task (the task that was interrupted), then,
internally, xStreamBufferReceiveFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE. If
xStreamBufferReceiveFromISR() sets this value to pdTRUE, then normally a context switch should
be performed before the interrupt is exited. That will ensure the interrupt returns directly to the
highest priority Ready state task. *pxHigherPriorityTaskWoken should be set to pdFALSE before
it is passed into the function. See the code example below for an example.
void vStreamBufferDelete(StreamBufferHandle_t xStreamBuffer)
Deletes a stream buffer that was previously created using a call to xStreamBufferCreate() or xStreamBuffer-
CreateStatic(). If the stream buffer was created using dynamic memory (that is, by xStreamBufferCreate()),
then the allocated memory is freed.
A stream buffer handle must not be used after the stream buffer has been deleted.
Parameters
• xStreamBuffer: The handle of the stream buffer to be deleted.
BaseType_t xStreamBufferIsFull(StreamBufferHandle_t xStreamBuffer)
Queries a stream buffer to see if it is full. A stream buffer is full if it does not have any free space, and therefore
cannot accept any more data.
Return If the stream buffer is full then pdTRUE is returned. Otherwise pdFALSE is returned.
Parameters
• xStreamBuffer: The handle of the stream buffer being queried.

BaseType_t xStreamBufferIsEmpty(StreamBufferHandle_t xStreamBuffer)

Queries a stream buffer to see if it is empty. A stream buffer is empty if it does not contain any data.
Return If the stream buffer is empty then pdTRUE is returned. Otherwise pdFALSE is returned.
Parameters
BaseType_t xStreamBufferReset(StreamBufferHandle_t xStreamBuffer)
Resets a stream buffer to its initial, empty, state. Any data that was in the stream buffer is discarded. A stream
buffer can only be reset if there are no tasks blocked waiting to either send to or receive from the stream buffer.
Return If the stream buffer is reset then pdPASS is returned. If there was a task blocked waiting to send to
or read from the stream buffer then the stream buffer is not reset and pdFAIL is returned.
Parameters
• xStreamBuffer: The handle of the stream buffer being reset.
size_t xStreamBufferSpacesAvailable(StreamBufferHandle_t xStreamBuffer)
Queries a stream buffer to see how much free space it contains, which is equal to the amount of data that can
be sent to the stream buffer before it is full.
Return The number of bytes that can be written to the stream buffer before the stream buffer would be full.
Parameters
size_t xStreamBufferBytesAvailable(StreamBufferHandle_t xStreamBuffer)
Queries a stream buffer to see how much data it contains, which is equal to the number of bytes that can be
read from the stream buffer before the stream buffer would be empty.
Return The number of bytes that can be read from the stream buffer before the stream buffer would be empty.
Parameters
BaseType_t xStreamBufferSetTriggerLevel(StreamBufferHandle_t xStreamBuffer, size_t xTrig-
gerLevel)
A stream buffer s trigger level is the number of bytes that must be in the stream buffer before a task that is
blocked on the stream buffer to wait for data is moved out of the blocked state. For example, if a task is blocked
on a read of an empty stream buffer that has a trigger level of 1 then the task will be unblocked when a single
byte is written to the buffer or the task s block time expires. As another example, if a task is blocked on a
read of an empty stream buffer that has a trigger level of 10 then the task will not be unblocked until the stream
buffer contains at least 10 bytes or the task s block time expires. If a reading task s block time expires before
the trigger level is reached then the task will still receive however many bytes are actually available. Setting
a trigger level of 0 will result in a trigger level of 1 being used. It is not valid to specify a trigger level that is
greater than the buffer size.
A trigger level is set when the stream buffer is created, and can be modified using xStreamBufferSetTrigger-
Level().
Return If xTriggerLevel was less than or equal to the stream buffer s length then the trigger level will be
updated and pdTRUE is returned. Otherwise pdFALSE is returned.
Parameters
• xStreamBuffer: The handle of the stream buffer being updated.
• xTriggerLevel: The new trigger level for the stream buffer.
BaseType_t xStreamBufferSendCompletedFromISR(StreamBufferHandle_t xStreamBuffer, Base-
Type_t *pxHigherPriorityTaskWoken)
For advanced users only.
The sbSEND_COMPLETED() macro is called from within the FreeRTOS APIs when data is sent to a message
buffer or stream buffer. If there was a task that was blocked on the message or stream buffer waiting for
data to arrive then the sbSEND_COMPLETED() macro sends a notification to the task to remove it from
the Blocked state. xStreamBufferSendCompletedFromISR() does the same thing. It is provided to enable
application writers to implement their own version of sbSEND_COMPLETED(), and MUST NOT BE USED
AT ANY OTHER TIME.
See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for additional information.

Return If a task was removed from the Blocked state then pdTRUE is returned. Otherwise pdFALSE is
returned.
Parameters
• xStreamBuffer: The handle of the stream buffer to which data was written.
• pxHigherPriorityTaskWoken: *pxHigherPriorityTaskWoken should be initialised to
pdFALSE before it is passed into xStreamBufferSendCompletedFromISR(). If calling xStream-
BufferSendCompletedFromISR() removes a task from the Blocked state, and the task has a priority
above the priority of the currently running task, then *pxHigherPriorityTaskWoken will get set to
pdTRUE indicating that a context switch should be performed before exiting the ISR.
BaseType_t xStreamBufferReceiveCompletedFromISR(StreamBufferHandle_t
xStreamBuffer, BaseType_t
The sbRECEIVE_COMPLETED() macro is called from within the FreeRTOS APIs when data is read out of
a message buffer or stream buffer. If there was a task that was blocked on the message or stream buffer waiting
for data to arrive then the sbRECEIVE_COMPLETED() macro sends a notification to the task to remove it
from the Blocked state. xStreamBufferReceiveCompletedFromISR() does the same thing. It is provided to
enable application writers to implement their own version of sbRECEIVE_COMPLETED(), and MUST NOT
BE USED AT ANY OTHER TIME.
returned.
Parameters
• xStreamBuffer: The handle of the stream buffer from which data was read.
pdFALSE before it is passed into xStreamBufferReceiveCompletedFromISR(). If calling xStream-
BufferReceiveCompletedFromISR() removes a task from the Blocked state, and the task has a pri-
ority above the priority of the currently running task, then *pxHigherPriorityTaskWoken will get set
to pdTRUE indicating that a context switch should be performed before exiting the ISR.
Macros
xStreamBufferCreate(xBufferSizeBytes, xTriggerLevelBytes)
Creates a new stream buffer using dynamically allocated memory. See xStreamBufferCreateStatic() for a ver-
sion that uses statically allocated memory (memory that is allocated at compile time).
configSUPPORT_DYNAMIC_ALLOCATION must be set to 1 or left undefined in FreeRTOSConfig.h for
xStreamBufferCreate() to be available.
Example use:

{
const size_t xStreamBufferSizeBytes = 100, xTriggerLevel = 10;
// Create a stream buffer that can hold 100 bytes. The memory used to hold
// both the stream buffer structure and the data in the stream buffer is
// allocated dynamically.
xStreamBuffer = xStreamBufferCreate( xStreamBufferSizeBytes, xTriggerLevel );
if( xStreamBuffer == NULL )

{
// There was not enough heap memory space available to create the
// stream buffer.
}
else
{


// The stream buffer was created successfully and can now be used.
}
}
Return If NULL is returned, then the stream buffer cannot be created because there is insufficient heap
memory available for FreeRTOS to allocate the stream buffer data structures and storage area. A non-
NULL value being returned indicates that the stream buffer has been created successfully - the returned
value should be stored as the handle to the created stream buffer.
Parameters
• xBufferSizeBytes: The total number of bytes the stream buffer will be able to hold at any one
time.
• xTriggerLevelBytes: The number of bytes that must be in the stream buffer before a task
that is blocked on the stream buffer to wait for data is moved out of the blocked state. For example,
if a task is blocked on a read of an empty stream buffer that has a trigger level of 1 then the task
will be unblocked when a single byte is written to the buffer or the task s block time expires. As
another example, if a task is blocked on a read of an empty stream buffer that has a trigger level of
10 then the task will not be unblocked until the stream buffer contains at least 10 bytes or the task
s block time expires. If a reading task s block time expires before the trigger level is reached then
the task will still receive however many bytes are actually available. Setting a trigger level of 0 will
result in a trigger level of 1 being used. It is not valid to specify a trigger level that is greater than
the buffer size.
xStreamBufferCreateStatic(xBufferSizeBytes, xTriggerLevelBytes, pucStreamBufferStorageArea,
pxStaticStreamBuffer)
Creates a new stream buffer using statically allocated memory. See xStreamBufferCreate() for a version that
uses dynamically allocated memory.
configSUPPORT_STATIC_ALLOCATION must be set to 1 in FreeRTOSConfig.h for xStreamBufferCreat-
eStatic() to be available.
Example use:
// Used to dimension the array used to hold the streams. The available space
// will actually be one less than this, so 999.
#define STORAGE_SIZE_BYTES 1000
// Defines the memory that will actually hold the streams within the stream
// buffer.
static uint8_t ucStorageBuffer[ STORAGE_SIZE_BYTES ];
// The variable used to hold the stream buffer structure.

StaticStreamBuffer_t xStreamBufferStruct;
void MyFunction( void )

{
const size_t xTriggerLevel = 1;
xStreamBuffer = xStreamBufferCreateStatic( sizeof( ucBufferStorage ),

xTriggerLevel,
ucBufferStorage,
&xStreamBufferStruct );
// As neither the pucStreamBufferStorageArea or pxStaticStreamBuffer

// parameters were NULL, xStreamBuffer will not be NULL, and can be used to
// reference the created stream buffer in other stream buffer API calls.
// Other code that uses the stream buffer can go here.

}
Return If the stream buffer is created successfully then a handle to the created stream buffer is returned. If
either pucStreamBufferStorageArea or pxStaticstreamBuffer are NULL then NULL is returned.

Parameters
• xBufferSizeBytes: The size, in bytes, of the buffer pointed to by the pucStreamBufferStor-
ageArea parameter.
• xTriggerLevelBytes: The number of bytes that must be in the stream buffer before a task
that is blocked on the stream buffer to wait for data is moved out of the blocked state. For example,
if a task is blocked on a read of an empty stream buffer that has a trigger level of 1 then the task
will be unblocked when a single byte is written to the buffer or the task s block time expires. As
another example, if a task is blocked on a read of an empty stream buffer that has a trigger level of
10 then the task will not be unblocked until the stream buffer contains at least 10 bytes or the task
s block time expires. If a reading task s block time expires before the trigger level is reached then
the task will still receive however many bytes are actually available. Setting a trigger level of 0 will
result in a trigger level of 1 being used. It is not valid to specify a trigger level that is greater than
the buffer size.
• pucStreamBufferStorageArea: Must point to a uint8_t array that is at least xBufferSize-
Bytes + 1 big. This is the array to which streams are copied when they are written to the stream
buffer.
• pxStaticStreamBuffer: Must point to a variable of type StaticStreamBuffer_t, which will
be used to hold the stream buffer s data structure.
Type Definitions
typedef struct StreamBufferDef_t *StreamBufferHandle_t
Message Buffer API
Header File
• components/freertos/FreeRTOS-Kernel/include/freertos/message_buffer.h
Macros
xMessageBufferCreate(xBufferSizeBytes)
Creates a new message buffer using dynamically allocated memory. See xMessageBufferCreateStatic() for a
version that uses statically allocated memory (memory that is allocated at compile time).
configSUPPORT_DYNAMIC_ALLOCATION must be set to 1 or left undefined in FreeRTOSConfig.h for
xMessageBufferCreate() to be available.
Example use:

{
MessageBufferHandle_t xMessageBuffer;
const size_t xMessageBufferSizeBytes = 100;
// Create a message buffer that can hold 100 bytes. The memory used to hold
// both the message buffer structure and the messages themselves is allocated
// dynamically. Each message added to the buffer consumes an additional 4
// bytes which are used to hold the lengh of the message.
xMessageBuffer = xMessageBufferCreate( xMessageBufferSizeBytes );
if( xMessageBuffer == NULL )

{
// There was not enough heap memory space available to create the
// message buffer.
}
else
{
// The message buffer was created successfully and can now be used.
}

Return If NULL is returned, then the message buffer cannot be created because there is insufficient heap
memory available for FreeRTOS to allocate the message buffer data structures and storage area. A non-
NULL value being returned indicates that the message buffer has been created successfully - the returned
value should be stored as the handle to the created message buffer.
Parameters
• xBufferSizeBytes: The total number of bytes (not messages) the message buffer will be able
to hold at any one time. When a message is written to the message buffer an additional sizeof( size_t
) bytes are also written to store the message s length. sizeof( size_t ) is typically 4 bytes on a 32-bit
architecture, so on most 32-bit architectures a 10 byte message will take up 14 bytes of message
buffer space.
xMessageBufferCreateStatic(xBufferSizeBytes, pucMessageBufferStorageArea, pxStaticMes-
sageBuffer)
Creates a new message buffer using statically allocated memory. See xMessageBufferCreate() for a version
that uses dynamically allocated memory.
Example use:
// Used to dimension the array used to hold the messages. The available space
// will actually be one less than this, so 999.
#define STORAGE_SIZE_BYTES 1000
// Defines the memory that will actually hold the messages within the message
// buffer.
static uint8_t ucStorageBuffer[ STORAGE_SIZE_BYTES ];
// The variable used to hold the message buffer structure.

StaticMessageBuffer_t xMessageBufferStruct;
void MyFunction( void )

{
xMessageBuffer = xMessageBufferCreateStatic( sizeof( ucBufferStorage ),

ucBufferStorage,
&xMessageBufferStruct );
// As neither the pucMessageBufferStorageArea or pxStaticMessageBuffer

// parameters were NULL, xMessageBuffer will not be NULL, and can be used to
// reference the created message buffer in other message buffer API calls.
// Other code that uses the message buffer can go here.

}
Return If the message buffer is created successfully then a handle to the created message buffer is returned.
If either pucMessageBufferStorageArea or pxStaticmessageBuffer are NULL then NULL is returned.
Parameters
• xBufferSizeBytes: The size, in bytes, of the buffer pointed to by the pucMessageBufferStor-
ageArea parameter. When a message is written to the message buffer an additional sizeof( size_t )
bytes are also written to store the message s length. sizeof( size_t ) is typically 4 bytes on a 32-bit
architecture, so on most 32-bit architecture a 10 byte message will take up 14 bytes of message
buffer space. The maximum number of bytes that can be stored in the message buffer is actually
(xBufferSizeBytes - 1).
• pucMessageBufferStorageArea: Must point to a uint8_t array that is at least xBufferSize-
Bytes + 1 big. This is the array to which messages are copied when they are written to the message
buffer.
• pxStaticMessageBuffer: Must point to a variable of type StaticMessageBuffer_t, which will
be used to hold the message buffer s data structure.
xMessageBufferSend(xMessageBuffer, pvTxData, xDataLengthBytes, xTicksToWait)
Sends a discrete message to the message buffer. The message can be any length that fits within the buffer s
free space, and is copied into the buffer.

be multiple different writers then the application writer must place each call to a writing API function (such as
xMessageBufferSend()) inside a critical section and set the send block time to 0. Likewise, if there are to be
xMessageBufferRead()) inside a critical section and set the receive block time to 0.
Use xMessageBufferSend() to write to a message buffer from a task. Use xMessageBufferSendFromISR() to
write to a message buffer from an interrupt service routine (ISR).
Example use:
void vAFunction( MessageBufferHandle_t xMessageBuffer )

{
size_t xBytesSent;
uint8_t ucArrayToSend[] = { 0, 1, 2, 3 };
const TickType_t x100ms = pdMS_TO_TICKS( 100 );
// Send an array to the message buffer, blocking for a maximum of 100ms to

// wait for enough space to be available in the message buffer.
xBytesSent = xMessageBufferSend( xMessageBuffer, ( void * ) ucArrayToSend,␣
,→sizeof( ucArrayToSend ), x100ms );
if( xBytesSent != sizeof( ucArrayToSend ) )

{
// The call to xMessageBufferSend() times out before there was enough
// space in the buffer for the data to be written.
}
// Send the string to the message buffer. Return immediately if there is

// not enough space in the buffer.
xBytesSent = xMessageBufferSend( xMessageBuffer, ( void * ) pcStringToSend,␣
,→strlen( pcStringToSend ), 0 );

{
// The string could not be added to the message buffer because there was
// not enough free space in the buffer.
}
}
Return The number of bytes written to the message buffer. If the call to xMessageBufferSend() times out
before there was enough space to write the message into the message buffer then zero is returned. If the
call did not time out then xDataLengthBytes is returned.
Parameters
• xMessageBuffer: The handle of the message buffer to which a message is being sent.
• pvTxData: A pointer to the message that is to be copied into the message buffer.
• xDataLengthBytes: The length of the message. That is, the number of bytes to copy from
pvTxData into the message buffer. When a message is written to the message buffer an additional
sizeof( size_t ) bytes are also written to store the message s length. sizeof( size_t ) is typically 4
bytes on a 32-bit architecture, so on most 32-bit architecture setting xDataLengthBytes to 20 will
reduce the free space in the message buffer by 24 bytes (20 bytes of message data and 4 bytes to
hold the message length).
• xTicksToWait: The maximum amount of time the calling task should remain in the Blocked
state to wait for enough space to become available in the message buffer, should the message buffer
have insufficient space when xMessageBufferSend() is called. The calling task will never block if
xTicksToWait is zero. The block time is specified in tick periods, so the absolute time it represents
is dependent on the tick frequency. The macro pdMS_TO_TICKS() can be used to convert a time

specified in milliseconds into a time specified in ticks. Setting xTicksToWait to portMAX_DELAY

will cause the task to wait indefinitely (without timing out), provided INCLUDE_vTaskSuspend is
set to 1 in FreeRTOSConfig.h. Tasks do not use any CPU time when they are in the Blocked state.
xMessageBufferSendFromISR(xMessageBuffer, pvTxData, xDataLengthBytes, pxHigherPriority-
TaskWoken)
Interrupt safe version of the API function that sends a discrete message to the message buffer. The message
can be any length that fits within the buffer s free space, and is copied into the buffer.
Use xMessageBufferSend() to write to a message buffer from a task. Use xMessageBufferSendFromISR() to
write to a message buffer from an interrupt service routine (ISR).
Example use:
// A message buffer that has already been created.


{
size_t xBytesSent;
// Attempt to send the string to the message buffer.

xBytesSent = xMessageBufferSendFromISR( xMessageBuffer,
( void * ) pcStringToSend,
strlen( pcStringToSend ),

{
// The string could not be added to the message buffer because there was
// not enough free space in the buffer.
}

// xMessageBufferSendFromISR() then a task that has a priority above the
// xHigherPriorityTaskWoken into portYIELD_FROM_ISR(), which will test the
}
Return The number of bytes actually written to the message buffer. If the message buffer didn t have enough
free space for the message to be stored then 0 is returned, otherwise xDataLengthBytes is returned.
Parameters
• xMessageBuffer: The handle of the message buffer to which a message is being sent.
• pvTxData: A pointer to the message that is to be copied into the message buffer.
• xDataLengthBytes: The length of the message. That is, the number of bytes to copy from
pvTxData into the message buffer. When a message is written to the message buffer an additional

sizeof( size_t ) bytes are also written to store the message s length. sizeof( size_t ) is typically 4
bytes on a 32-bit architecture, so on most 32-bit architecture setting xDataLengthBytes to 20 will
reduce the free space in the message buffer by 24 bytes (20 bytes of message data and 4 bytes to
hold the message length).
• pxHigherPriorityTaskWoken: It is possible that a message buffer will have a task blocked
on it waiting for data. Calling xMessageBufferSendFromISR() can make data available, and so cause
a task that was waiting for data to leave the Blocked state. If calling xMessageBufferSendFromISR()
causes a task to leave the Blocked state, and the unblocked task has a priority higher than the currently
executing task (the task that was interrupted), then, internally, xMessageBufferSendFromISR() will
set *pxHigherPriorityTaskWoken to pdTRUE. If xMessageBufferSendFromISR() sets this value to
pdTRUE, then normally a context switch should be performed before the interrupt is exited. This
will ensure that the interrupt returns directly to the highest priority Ready state task. *pxHigher-
PriorityTaskWoken should be set to pdFALSE before it is passed into the function. See the code
example below for an example.
xMessageBufferReceive(xMessageBuffer, pvRxData, xBufferLengthBytes, xTicksToWait)
Receives a discrete message from a message buffer. Messages can be of variable length and are copied out of
the buffer.
Use xMessageBufferReceive() to read from a message buffer from a task. Use xMessageBufferReceive-
FromISR() to read from a message buffer from an interrupt service routine (ISR).
Example use:
void vAFunction( MessageBuffer_t xMessageBuffer )

{
const TickType_t xBlockTime = pdMS_TO_TICKS( 20 );
// Receive the next message from the message buffer. Wait in the Blocked
// state (so not using any CPU processing time) for a maximum of 100ms for
// a message to become available.
xReceivedBytes = xMessageBufferReceive( xMessageBuffer,
sizeof( ucRxData ),
xBlockTime );

{
// A ucRxData contains a message that is xReceivedBytes long. Process
// the message here....
}
}
Return The length, in bytes, of the message read from the message buffer, if any. If xMessageBufferReceive()
times out before a message became available then zero is returned. If the length of the message is greater
than xBufferLengthBytes then the message will be left in the message buffer and zero is returned.
Parameters
• xMessageBuffer: The handle of the message buffer from which a message is being received.
• pvRxData: A pointer to the buffer into which the received message is to be copied.

sets the maximum length of the message that can be received. If xBufferLengthBytes is too small
to hold the next message then the message will be left in the message buffer and 0 will be returned.
• xTicksToWait: The maximum amount of time the task should remain in the Blocked state to
wait for a message, should the message buffer be empty. xMessageBufferReceive() will return im-
mediately if xTicksToWait is zero and the message buffer is empty. The block time is specified
in tick periods, so the absolute time it represents is dependent on the tick frequency. The macro
pdMS_TO_TICKS() can be used to convert a time specified in milliseconds into a time specified in
ticks. Setting xTicksToWait to portMAX_DELAY will cause the task to wait indefinitely (without
timing out), provided INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. Tasks do not use
any CPU time when they are in the Blocked state.
xMessageBufferReceiveFromISR(xMessageBuffer, pvRxData, xBufferLengthBytes, pxHigherPri-
orityTaskWoken)
An interrupt safe version of the API function that receives a discrete message from a message buffer. Messages
can be of variable length and are copied out of the buffer.
Use xMessageBufferReceive() to read from a message buffer from a task. Use xMessageBufferReceive-
FromISR() to read from a message buffer from an interrupt service routine (ISR).
Example use:
// A message buffer that has already been created.

MessageBuffer_t xMessageBuffer;

{
// Receive the next message from the message buffer.

xReceivedBytes = xMessageBufferReceiveFromISR( xMessageBuffer,
sizeof( ucRxData ),

{
// A ucRxData contains a message that is xReceivedBytes long. Process
// the message here....
}

// xMessageBufferReceiveFromISR() then a task that has a priority above the
// xHigherPriorityTaskWoken into portYIELD_FROM_ISR(), which will test the
}

Return The length, in bytes, of the message read from the message buffer, if any.
Parameters
• xMessageBuffer: The handle of the message buffer from which a message is being received.
• pvRxData: A pointer to the buffer into which the received message is to be copied.
sets the maximum length of the message that can be received. If xBufferLengthBytes is too small
to hold the next message then the message will be left in the message buffer and 0 will be returned.
• pxHigherPriorityTaskWoken: It is possible that a message buffer will have a task blocked
on it waiting for space to become available. Calling xMessageBufferReceiveFromISR() can make
space available, and so cause a task that is waiting for space to leave the Blocked state. If call-
ing xMessageBufferReceiveFromISR() causes a task to leave the Blocked state, and the unblocked
task has a priority higher than the currently executing task (the task that was interrupted), then,
internally, xMessageBufferReceiveFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE.
If xMessageBufferReceiveFromISR() sets this value to pdTRUE, then normally a context switch
should be performed before the interrupt is exited. That will ensure the interrupt returns directly
to the highest priority Ready state task. *pxHigherPriorityTaskWoken should be set to pdFALSE
before it is passed into the function. See the code example below for an example.
vMessageBufferDelete(xMessageBuffer)
Deletes a message buffer that was previously created using a call to xMessageBufferCreate() or xMessage-
BufferCreateStatic(). If the message buffer was created using dynamic memory (that is, by xMessageBuffer-
Create()), then the allocated memory is freed.
A message buffer handle must not be used after the message buffer has been deleted.
Parameters
• xMessageBuffer: The handle of the message buffer to be deleted.
xMessageBufferIsFull(xMessageBuffer)
Tests to see if a message buffer is full. A message buffer is full if it cannot accept any more messages, of any
size, until space is made available by a message being removed from the message buffer.
Return If the message buffer referenced by xMessageBuffer is full then pdTRUE is returned. Otherwise
Parameters
• xMessageBuffer: The handle of the message buffer being queried.
xMessageBufferIsEmpty(xMessageBuffer)
Tests to see if a message buffer is empty (does not contain any messages).
Return If the message buffer referenced by xMessageBuffer is empty then pdTRUE is returned. Otherwise
Parameters
xMessageBufferReset(xMessageBuffer)
Resets a message buffer to its initial empty state, discarding any message it contained.
A message buffer can only be reset if there are no tasks blocked on it.
Return If the message buffer was reset then pdPASS is returned. If the message buffer could not be reset
because either there was a task blocked on the message queue to wait for space to become available, or
to wait for a a message to be available, then pdFAIL is returned.
Parameters
• xMessageBuffer: The handle of the message buffer being reset.
xMessageBufferSpaceAvailable(xMessageBuffer)
Returns the number of bytes of free space in the message buffer.
Return The number of bytes that can be written to the message buffer before the message buffer would be
full. When a message is written to the message buffer an additional sizeof( size_t ) bytes are also written
to store the message s length. sizeof( size_t ) is typically 4 bytes on a 32-bit architecture, so if xMes-
sageBufferSpacesAvailable() returns 10, then the size of the largest message that can be written to the
message buffer is 6 bytes.

Parameters
xMessageBufferSpacesAvailable(xMessageBuffer)
xMessageBufferNextLengthBytes(xMessageBuffer)
Returns the length (in bytes) of the next message in a message buffer. Useful if xMessageBufferReceive()
returned 0 because the size of the buffer passed into xMessageBufferReceive() was too small to hold the next
message.
Return The length (in bytes) of the next message in the message buffer, or 0 if the message buffer is empty.
Parameters
xMessageBufferSendCompletedFromISR(xMessageBuffer, pxHigherPriorityTaskWoken)
The sbSEND_COMPLETED() macro is called from within the FreeRTOS APIs when data is sent to a message
buffer or stream buffer. If there was a task that was blocked on the message or stream buffer waiting for data to
arrive then the sbSEND_COMPLETED() macro sends a notification to the task to remove it from the Blocked
state. xMessageBufferSendCompletedFromISR() does the same thing. It is provided to enable application
writers to implement their own version of sbSEND_COMPLETED(), and MUST NOT BE USED AT ANY
OTHER TIME.
returned.
Parameters
• xMessageBuffer: The handle of the stream buffer to which data was written.
pdFALSE before it is passed into xMessageBufferSendCompletedFromISR(). If calling xMessage-
BufferSendCompletedFromISR() removes a task from the Blocked state, and the task has a priority
above the priority of the currently running task, then *pxHigherPriorityTaskWoken will get set to
pdTRUE indicating that a context switch should be performed before exiting the ISR.
xMessageBufferReceiveCompletedFromISR(xMessageBuffer, pxHigherPriorityTaskWoken)
The sbRECEIVE_COMPLETED() macro is called from within the FreeRTOS APIs when data is read out of
a message buffer or stream buffer. If there was a task that was blocked on the message or stream buffer waiting
for data to arrive then the sbRECEIVE_COMPLETED() macro sends a notification to the task to remove it
from the Blocked state. xMessageBufferReceiveCompletedFromISR() does the same thing. It is provided to
enable application writers to implement their own version of sbRECEIVE_COMPLETED(), and MUST NOT
BE USED AT ANY OTHER TIME.
returned.
Parameters
• xMessageBuffer: The handle of the stream buffer from which data was read.
pdFALSE before it is passed into xMessageBufferReceiveCompletedFromISR(). If calling xMes-
sageBufferReceiveCompletedFromISR() removes a task from the Blocked state, and the task has a
priority above the priority of the currently running task, then *pxHigherPriorityTaskWoken will get
set to pdTRUE indicating that a context switch should be performed before exiting the ISR.
Type Definitions
typedef void *MessageBufferHandle_t
Type by which message buffers are referenced. For example, a call to xMessageBufferCreate() returns an
MessageBufferHandle_t variable that can then be used as a parameter to xMessageBufferSend(), xMessage-
BufferReceive(), etc.

2.7.10 FreeRTOS Additions
Overview
ESP-IDF FreeRTOS is based on the Xtensa port of FreeRTOS v10.2.0 with significant modifications for SMP com-
patibility (see ESP-IDF FreeRTOS SMP Changes). However various features specific to ESP-IDF FreeRTOS have
been added. The features are as follows:
Ring Buffers: Ring buffers were added to provide a form of buffer that could accept entries of arbitrary lengths.
Hooks: ESP-IDF FreeRTOS hooks provides support for registering extra Idle and Tick hooks at run time. Moreover,
the hooks can be asymmetric amongst both CPUs.
Component Specific Properties: Currently added only one component specific property ORIG_INCLUDE_PATH.
Ring Buffers
The ESP-IDF FreeRTOS ring buffer is a strictly FIFO buffer that supports arbitrarily sized items. Ring buffers are a
more memory efficient alternative to FreeRTOS queues in situations where the size of items is variable. The capacity
of a ring buffer is not measured by the number of items it can store, but rather by the amount of memory used for
storing items. The ring buffer provides API to send an item, or to allocate space for an item in the ring buffer to be
filled manually by the user. For efficiency reasons, items are always retrieved from the ring buffer by reference.
As a result, all retrieved items must also be returned to the ring buffer by using vRingbufferReturnItem()
or vRingbufferReturnItemFromISR(), in order for them to be removed from the ring buffer completely.
The ring buffers are split into the three following types:
No-Split buffers will guarantee that an item is stored in contiguous memory and will not attempt to split an item
under any circumstances. Use no-split buffers when items must occupy contiguous memory. Only this buffer type
allows you getting the data item address and writting to the item by yourself.
Allow-Split buffers will allow an item to be split when wrapping around if doing so will allow the item to be stored.
Allow-split buffers are more memory efficient than no-split buffers but can return an item in two parts when retrieving.
Byte buffers do not store data as separate items. All data is stored as a sequence of bytes, and any number of bytes
and be sent or retrieved each time. Use byte buffers when separate items do not need to be maintained (e.g. a byte
stream).
Note: No-split/allow-split buffers will always store items at 32-bit aligned addresses. Therefore when retrieving an
item, the item pointer is guaranteed to be 32-bit aligned. This is useful especially when you need to send some data
to the DMA.
Note: Each item stored in no-split/allow-split buffers will require an additional 8 bytes for a header. Item sizes
will also be rounded up to a 32-bit aligned size (multiple of 4 bytes), however the true item size is recorded within
the header. The sizes of no-split/allow-split buffers will also be rounded up when created.
Usage The following example demonstrates the usage of xRingbufferCreate() and xRing-
bufferSend() to create a ring buffer then send an item to it.
#include "freertos/ringbuf.h"
static char tx_item[] = "test_item";
...
//Create ring buffer

RingbufHandle_t buf_handle;
buf_handle = xRingbufferCreate(1028, RINGBUF_TYPE_NOSPLIT);
if (buf_handle == NULL) {


printf("Failed to create ring buffer\n");
}
//Send an item
UBaseType_t res = xRingbufferSend(buf_handle, tx_item, sizeof(tx_item), pdMS_
,→TO_TICKS(1000));
if (res != pdTRUE) {
printf("Failed to send item\n");
}
The following example demonstrates the usage of xRingbufferSendAcquire() and xRingbufferSend-

Complete() instead of xRingbufferSend() to apply for the memory on the ring buffer (of type RING-
BUF_TYPE_NOSPLIT) and then send an item to it. This way adds one more step, but allows getting the address of
the memory to write to, and writing to the memory yourself.
#include "soc/lldesc.h"
typedef struct {
lldesc_t dma_desc;
uint8_t buf[1];
} dma_item_t;
#define DMA_ITEM_SIZE(N) (sizeof(lldesc_t)+(((N)+3)&(~3)))
...
//Retrieve space for DMA descriptor and corresponding data buffer

//This has to be done with SendAcquire, or the address may be different when␣
,→copy
dma_item_t item;
UBaseType_t res = xRingbufferSendAcquire(buf_handle,
&item, DMA_ITEM_SIZE(buffer_size), pdMS_TO_TICKS(1000));
printf("Failed to acquire memory for item\n");
}
item->dma_desc = (lldesc_t) {
.size = buffer_size,
.length = buffer_size,
.eof = 0,
.owner = 1,
.buf = &item->buf,
};
//Actually send to the ring buffer for consumer to use
res = xRingbufferSendComplete(buf_handle, &item);
printf("Failed to send item\n");
}
The following example demonstrates retrieving and returning an item from a no-split ring buffer using xRing-
bufferReceive() and vRingbufferReturnItem()
...
//Receive an item from no-split ring buffer

size_t item_size;
char *item = (char *)xRingbufferReceive(buf_handle, &item_size, pdMS_TO_
,→TICKS(1000));
//Check received item

if (item != NULL) {


//Print item
for (int i = 0; i < item_size; i++) {
printf("%c", item[i]);
}
printf("\n");
//Return Item
vRingbufferReturnItem(buf_handle, (void *)item);
} else {
//Failed to receive item
printf("Failed to receive item\n");
}
The following example demonstrates retrieving and returning an item from an allow-split ring buffer using xRing-
bufferReceiveSplit() and vRingbufferReturnItem()
...
//Receive an item from allow-split ring buffer

size_t item_size1, item_size2;
char *item1, *item2;
BaseType_t ret = xRingbufferReceiveSplit(buf_handle, (void **)&item1, (void␣
,→**)&item2, &item_size1, &item_size2, pdMS_TO_TICKS(1000));
//Check received item

if (ret == pdTRUE && item1 != NULL) {
for (int i = 0; i < item_size1; i++) {
printf("%c", item1[i]);
}
vRingbufferReturnItem(buf_handle, (void *)item1);
//Check if item was split
if (item2 != NULL) {
for (int i = 0; i < item_size2; i++) {
printf("%c", item2[i]);
}
vRingbufferReturnItem(buf_handle, (void *)item2);
}
printf("\n");
} else {
}
The following example demonstrates retrieving and returning an item from a byte buffer using xRingbuffer-
ReceiveUpTo() and vRingbufferReturnItem()
...
//Receive data from byte buffer

size_t item_size;
char *item = (char *)xRingbufferReceiveUpTo(buf_handle, &item_size, pdMS_TO_
,→TICKS(1000), sizeof(tx_item));
//Check received data

if (item != NULL) {
//Print item
for (int i = 0; i < item_size; i++) {
printf("%c", item[i]);
}
printf("\n");
//Return Item
vRingbufferReturnItem(buf_handle, (void *)item);


} else {
}
For ISR safe versions of the functions used above, call xRingbufferSendFromISR(), xRing-
bufferReceiveFromISR(), xRingbufferReceiveSplitFromISR(), xRingbufferReceive-
UpToFromISR(), and vRingbufferReturnItemFromISR()
Note: Two calls to RingbufferReceive[UpTo][FromISR]() are required if the bytes wraps around the end of the
ring buffer.
Sending to Ring Buffer The following diagrams illustrate the differences between no-split/allow-split buffers and
byte buffers with regards to sending items/data. The diagrams assume that three items of sizes 18, 3, and 27 bytes
are sent respectively to a buffer of 128 bytes.
Fig. 31: Sending items to no-split/allow-split ring buffers
For no-split/allow-split buffers, a header of 8 bytes precedes every data item. Furthermore, the space occupied by
each item is rounded up to the nearest 32-bit aligned size in order to maintain overall 32-bit alignment. However
the true size of the item is recorded inside the header which will be returned when the item is retrieved.
Referring to the diagram above, the 18, 3, and 27 byte items are rounded up to 20, 4, and 28 bytes respectively.
An 8 byte header is then added in front of each item.
Fig. 32: Sending items to byte buffers
Byte buffers treat data as a sequence of bytes and does not incur any overhead (no headers). As a result, all data sent
to a byte buffer is merged into a single item.
Referring to the diagram above, the 18, 3, and 27 byte items are sequentially written to the byte buffer and merged
into a single item of 48 bytes.
Using SendAcquire and SendComplete Items in no-split buffers are acquired (by SendAcquire) in strict FIFO
order and must be sent to the buffer by SendComplete for the data to be accessible by the consumer. Multiple items
can be sent or acquired without calling SendComplete, and the items do not necessarily need to be completed in

the order they were acquired. However the receiving of data items must occur in FIFO order, therefore not calling
SendComplete the earliest acquired item will prevent the subsequent items from being received.
The following diagrams illustrate what will happen when SendAcquire/SendComplete don t happen in the same
order. At the beginning, there is already an data item of 16 bytes sent to the ring buffer. Then SendAcquire is called
to acquire space of 20, 8, 24 bytes on the ring buffer.
Fig. 33: SendAcquire/SendComplete items in no-split ring buffers
After that, we fill (use) the buffers, and send them to the ring buffer by SendComplete in the order of 8, 24, 20. When
8 bytes and 24 bytes data are sent, the consumer still can only get the 16 bytes data item. Due to the usage if 20 bytes
item is not complete, it s not available, nor the following data items.
When the 20 bytes item is finally completed, all the 3 data items can be received now, in the order of 20, 8, 24 bytes,
right after the 16 bytes item existing in the buffer at the beginning.
Allow-split/byte buffers do not allow using SendAcquire/SendComplete since acquired buffers are required to be
complete (not wrapped).
Wrap around The following diagrams illustrate the differences between no-split, allow-split, and byte buffers when
a sent item requires a wrap around. The diagrams assumes a buffer of 128 bytes with 56 bytes of free space that
wraps around and a sent item of 28 bytes.
Fig. 34: Wrap around in no-split buffers
No-split buffers will only store an item in continuous free space and will not split an item under any circum-
stances. When the free space at the tail of the buffer is insufficient to completely store the item and its header, the
free space at the tail will be marked as dummy data. The buffer will then wrap around and store the item in the
free space at the head of the buffer.
Referring to the diagram above, the 16 bytes of free space at the tail of the buffer is insufficient to store the 28 byte
item. Therefore the 16 bytes is marked as dummy data and the item is written to the free space at the head of the
buffer instead.
Allow-split buffers will attempt to split the item into two parts when the free space at the tail of the buffer is
insufficient to store the item data and its header. Both parts of the split item will have their own headers (therefore
incurring an extra 8 bytes of overhead).
Referring to the diagram above, the 16 bytes of free space at the tail of the buffer is insufficient to store the 28 byte
item. Therefore the item is split into two parts (8 and 20 bytes) and written as two parts to the buffer.

Fig. 35: Wrap around in allow-split buffers
Note: Allow-split buffers treats the both parts of the split item as two separate items, therefore call xRingbuf-
ferReceiveSplit() instead of xRingbufferReceive() to receive both parts of a split item in a thread
safe manner.
Fig. 36: Wrap around in byte buffers
Byte buffers will store as much data as possible into the free space at the tail of buffer. The remaining data will
then be stored in the free space at the head of the buffer. No overhead is incurred when wrapping around in byte
buffers.
Referring to the diagram above, the 16 bytes of free space at the tail of the buffer is insufficient to completely store
the 28 bytes of data. Therefore the 16 bytes of free space is filled with data, and the remaining 12 bytes are written
to the free space at the head of the buffer. The buffer now contains data in two separate continuous parts, and each
part continuous will be treated as a separate item by the byte buffer.
Retrieving/Returning The following diagrams illustrates the differences between no-split/allow-split and byte
buffers in retrieving and returning data.
Fig. 37: Retrieving/Returning items in no-split/allow-split ring buffers
Items in no-split/allow-split buffers are retrieved in strict FIFO order and must be returned for the occupied space
to be freed. Multiple items can be retrieved before returning, and the items do not necessarily need to be returned

in the order they were retrieved. However the freeing of space must occur in FIFO order, therefore not returning the
earliest retrieved item will prevent the space of subsequent items from being freed.
Referring to the diagram above, the 16, 20, and 8 byte items are retrieved in FIFO order. However the items are
not returned in they were retrieved (20, 8, 16). As such, the space is not freed until the first item (16 byte) is returned.
Fig. 38: Retrieving/Returning data in byte buffers
Byte buffers do not allow multiple retrievals before returning (every retrieval must be followed by a return
before another retrieval is permitted). When using xRingbufferReceive() or xRingbufferReceive-
FromISR(), all continuous stored data will be retrieved. xRingbufferReceiveUpTo() or xRingbuf-
ferReceiveUpToFromISR() can be used to restrict the maximum number of bytes retrieved. Since every
retrieval must be followed by a return, the space will be freed as soon as the data is returned.
Referring to the diagram above, the 38 bytes of continuous stored data at the tail of the buffer is retrieved, returned,
and freed. The next call to xRingbufferReceive() or xRingbufferReceiveFromISR() then wraps
around and does the same to the 30 bytes of continuous stored data at the head of the buffer.
Ring Buffers with Queue Sets Ring buffers can be added to FreeRTOS queue sets using xRingbufferAd-
dToQueueSetRead() such that every time a ring buffer receives an item or data, the queue set is notified. Once
added to a queue set, every attempt to retrieve an item from a ring buffer should be preceded by a call to xQueue-
SelectFromSet(). To check whether the selected queue set member is the ring buffer, call xRingbuffer-
CanRead().
The following example demonstrates queue set usage with ring buffers.
#include "freertos/queue.h"
...
//Create ring buffer and queue set

RingbufHandle_t buf_handle = xRingbufferCreate(1028, RINGBUF_TYPE_NOSPLIT);
QueueSetHandle_t queue_set = xQueueCreateSet(3);
//Add ring buffer to queue set

if (xRingbufferAddToQueueSetRead(buf_handle, queue_set) != pdTRUE) {
printf("Failed to add to queue set\n");
}
...
//Block on queue set

xQueueSetMemberHandle member = xQueueSelectFromSet(queue_set, pdMS_TO_
,→TICKS(1000));
//Check if member is ring buffer

if (member != NULL && xRingbufferCanRead(buf_handle, member) == pdTRUE) {
//Member is ring buffer, receive item from ring buffer


size_t item_size;
char *item = (char *)xRingbufferReceive(buf_handle, &item_size, 0);
//Handle item
...
} else {
...
}
Ring Buffers with Static Allocation The xRingbufferCreateStatic() can be used to create ring buffers
with specific memory requirements (such as a ring buffer being allocated in external RAM). All blocks of memory
used by a ring buffer must be manually allocated beforehand then passed to the xRingbufferCreateStatic()
to be initialized as a ring buffer. These blocks include the following:
• The ring buffer s data structure of type StaticRingbuffer_t
• The ring buffer s storage area of size xBufferSize. Note that xBufferSize must be 32-bit aligned
for no-split/allow-split buffers.
The manner in which these blocks are allocated will depend on the users requirements (e.g. all blocks being statically
declared, or dynamically allocated with specific capabilities such as external RAM).
Note: When deleting a ring buffer created via xRingbufferCreateStatic(), the function vRing-
bufferDelete() will not free any of the memory blocks. This must be done manually by the user after vRing-
bufferDelete() is called.
The code snippet below demonstrates a ring buffer being allocated entirely in external RAM.
#include "freertos/semphr.h"
#include "esp_heap_caps.h"
#define BUFFER_SIZE 400 //32-bit aligned size

#define BUFFER_TYPE RINGBUF_TYPE_NOSPLIT
...
//Allocate ring buffer data structure and storage area into external RAM
StaticRingbuffer_t *buffer_struct = (StaticRingbuffer_t *)heap_caps_
,→malloc(sizeof(StaticRingbuffer_t), MALLOC_CAP_SPIRAM);
uint8_t *buffer_storage = (uint8_t *)heap_caps_malloc(sizeof(uint8_t)*BUFFER_SIZE,␣

,→MALLOC_CAP_SPIRAM);
//Create a ring buffer with manually allocated memory

RingbufHandle_t handle = xRingbufferCreateStatic(BUFFER_SIZE, BUFFER_TYPE, buffer_
,→storage, buffer_struct);
...
//Delete the ring buffer after used

vRingbufferDelete(handle);
//Manually free all blocks of memory

free(buffer_struct);
free(buffer_storage);

Ring Buffer API Reference
Note: Ideally, ring buffers can be used with multiple tasks in an SMP fashion where the highest priority task
will always be serviced first. However due to the usage of binary semaphores in the ring buffer s underlying
implementation, priority inversion may occur under very specific circumstances.
The ring buffer governs sending by a binary semaphore which is given whenever space is freed on the ring buffer. The
highest priority task waiting to send will repeatedly take the semaphore until sufficient free space becomes available
or until it times out. Ideally this should prevent any lower priority tasks from being serviced as the semaphore should
always be given to the highest priority task.
However in between iterations of acquiring the semaphore, there is a gap in the critical section which may permit
another task (on the other core or with an even higher priority) to free some space on the ring buffer and as a result give
the semaphore. Therefore the semaphore will be given before the highest priority task can re-acquire the semaphore.
This will result in the semaphore being acquired by the second highest priority task waiting to send, hence causing
priority inversion.
This side effect will not affect ring buffer performance drastically given if the number of tasks using the ring buffer
simultaneously is low, and the ring buffer is not operating near maximum capacity.
Header File
• components/esp_ringbuf/include/freertos/ringbuf.h
Functions
RingbufHandle_t xRingbufferCreate(size_t xBufferSize, RingbufferType_t xBufferType)
Create a ring buffer.
Note xBufferSize of no-split/allow-split buffers will be rounded up to the nearest 32-bit aligned size.
Return A handle to the created ring buffer, or NULL in case of error.
Parameters
• [in] xBufferSize: Size of the buffer in bytes. Note that items require space for overhead in
no-split/allow-split buffers
• [in] xBufferType: Type of ring buffer, see documentation.
RingbufHandle_t xRingbufferCreateNoSplit(size_t xItemSize, size_t xItemNum)
Create a ring buffer of type RINGBUF_TYPE_NOSPLIT for a fixed item_size.
This API is similar to xRingbufferCreate(), but it will internally allocate additional space for the headers.
Return A RingbufHandle_t handle to the created ring buffer, or NULL in case of error.
Parameters
• [in] xItemSize: Size of each item to be put into the ring buffer
• [in] xItemNum: Maximum number of items the buffer needs to hold simultaneously
RingbufHandle_t xRingbufferCreateStatic(size_t xBufferSize, RingbufferType_t xBufferType,
uint8_t *pucRingbufferStorage, StaticRingbuffer_t
*pxStaticRingbuffer)
Create a ring buffer but manually provide the required memory.
Note xBufferSize of no-split/allow-split buffers MUST be 32-bit aligned.
Return A handle to the created ring buffer
Parameters
• [in] xBufferSize: Size of the buffer in bytes.
• [in] xBufferType: Type of ring buffer, see documentation
• [in] pucRingbufferStorage: Pointer to the ring buffer s storage area. Storage area must
of the same size as specified by xBufferSize
• [in] pxStaticRingbuffer: Pointed to a struct of type StaticRingbuffer_t which will be
used to hold the ring buffer s data structure

BaseType_t xRingbufferSend(RingbufHandle_t xRingbuffer, const void *pvItem, size_t xItemSize,

TickType_t xTicksToWait)
Insert an item into the ring buffer.
Attempt to insert an item into the ring buffer. This function will block until enough free space is available or
until it times out.
Note For no-split/allow-split ring buffers, the actual size of memory that the item will occupy will be rounded
up to the nearest 32-bit aligned size. This is done to ensure all items are always stored in 32-bit aligned
fashion.
Return
• pdTRUE if succeeded
• pdFALSE on time-out or when the data is larger than the maximum permissible size of the buffer
Parameters
• [in] xRingbuffer: Ring buffer to insert the item into
• [in] pvItem: Pointer to data to insert. NULL is allowed if xItemSize is 0.
• [in] xItemSize: Size of data to insert.
• [in] xTicksToWait: Ticks to wait for room in the ring buffer.
BaseType_t xRingbufferSendFromISR(RingbufHandle_t xRingbuffer, const void *pvItem, size_t
xItemSize, BaseType_t *pxHigherPriorityTaskWoken)
Insert an item into the ring buffer in an ISR.
Attempt to insert an item into the ring buffer from an ISR. This function will return immediately if there is
insufficient free space in the buffer.
Note For no-split/allow-split ring buffers, the actual size of memory that the item will occupy will be rounded
up to the nearest 32-bit aligned size. This is done to ensure all items are always stored in 32-bit aligned
fashion.
Return
• pdFALSE when the ring buffer does not have space.
Parameters
• [in] pvItem: Pointer to data to insert. NULL is allowed if xItemSize is 0.
• [in] xItemSize: Size of data to insert.
• [out] pxHigherPriorityTaskWoken: Value pointed to will be set to pdTRUE if the
function woke up a higher priority task.
BaseType_t xRingbufferSendAcquire(RingbufHandle_t xRingbuffer, void **ppvItem, size_t xItem-
Size, TickType_t xTicksToWait)
Acquire memory from the ring buffer to be written to by an external source and to be sent later.
Attempt to allocate buffer for an item to be sent into the ring buffer. This function will block until enough free
space is available or until it timesout.
The item, as well as the following items SendAcquire or Send after it, will not be able to be read from the
ring buffer until this item is actually sent into the ring buffer.
Note Only applicable for no-split ring buffers now, the actual size of memory that the item will occupy will be
rounded up to the nearest 32-bit aligned size. This is done to ensure all items are always stored in 32-bit
aligned fashion.
Return
• pdFALSE on time-out or when the data is larger than the maximum permissible size of the buffer
Parameters
• [in] xRingbuffer: Ring buffer to allocate the memory
• [out] ppvItem: Double pointer to memory acquired (set to NULL if no memory were retrieved)
• [in] xItemSize: Size of item to acquire.
• [in] xTicksToWait: Ticks to wait for room in the ring buffer.
BaseType_t xRingbufferSendComplete(RingbufHandle_t xRingbuffer, void *pvItem)
Actually send an item into the ring buffer allocated before by xRingbufferSendAcquire.

Note Only applicable for no-split ring buffers. Only call for items allocated by xRingbufferSendAc-
quire.
Return
• pdFALSE if fail for some reason.
Parameters
• [in] pvItem: Pointer to item in allocated memory to insert.
void *xRingbufferReceive(RingbufHandle_t xRingbuffer, size_t *pxItemSize, TickType_t xTick-
sToWait)
Retrieve an item from the ring buffer.
Attempt to retrieve an item from the ring buffer. This function will block until an item is available or until it
times out.
Note A call to vRingbufferReturnItem() is required after this to free the item retrieved.
Return
• Pointer to the retrieved item on success; *pxItemSize filled with the length of the item.
• NULL on timeout, *pxItemSize is untouched in that case.
Parameters
• [in] xRingbuffer: Ring buffer to retrieve the item from
• [out] pxItemSize: Pointer to a variable to which the size of the retrieved item will be written.
• [in] xTicksToWait: Ticks to wait for items in the ring buffer.
void *xRingbufferReceiveFromISR(RingbufHandle_t xRingbuffer, size_t *pxItemSize)
Retrieve an item from the ring buffer in an ISR.
Attempt to retrieve an item from the ring buffer. This function returns immediately if there are no items
available for retrieval
Note A call to vRingbufferReturnItemFromISR() is required after this to free the item retrieved.
Note Byte buffers do not allow multiple retrievals before returning an item
Note Two calls to RingbufferReceiveFromISR() are required if the bytes wrap around the end of the ring
buffer.
Return
• NULL when the ring buffer is empty, *pxItemSize is untouched in that case.
Parameters
BaseType_t xRingbufferReceiveSplit(RingbufHandle_t xRingbuffer, void **ppvHeadItem,
void **ppvTailItem, size_t *pxHeadItemSize, size_t
*pxTailItemSize, TickType_t xTicksToWait)
Retrieve a split item from an allow-split ring buffer.
Attempt to retrieve a split item from an allow-split ring buffer. If the item is not split, only a single item is
retried. If the item is split, both parts will be retrieved. This function will block until an item is available or
until it times out.
Note Call(s) to vRingbufferReturnItem() is required after this to free up the item(s) retrieved.
Note This function should only be called on allow-split buffers
Return
• pdTRUE if an item (split or unsplit) was retrieved
• pdFALSE when no item was retrieved
Parameters
• [out] ppvHeadItem: Double pointer to first part (set to NULL if no items were retrieved)
• [out] ppvTailItem: Double pointer to second part (set to NULL if item is not split)
• [out] pxHeadItemSize: Pointer to size of first part (unmodified if no items were retrieved)
• [out] pxTailItemSize: Pointer to size of second part (unmodified if item is not split)

BaseType_t xRingbufferReceiveSplitFromISR(RingbufHandle_t xRingbuffer, void

**ppvHeadItem, void **ppvTailItem, size_t
*pxHeadItemSize, size_t *pxTailItemSize)
Retrieve a split item from an allow-split ring buffer in an ISR.
Attempt to retrieve a split item from an allow-split ring buffer. If the item is not split, only a single item is
retried. If the item is split, both parts will be retrieved. This function returns immediately if there are no items
available for retrieval
Note Calls to vRingbufferReturnItemFromISR() is required after this to free up the item(s) retrieved.
Note This function should only be called on allow-split buffers
Return
• pdTRUE if an item (split or unsplit) was retrieved
• pdFALSE when no item was retrieved
Parameters
• [out] ppvHeadItem: Double pointer to first part (set to NULL if no items were retrieved)
• [out] ppvTailItem: Double pointer to second part (set to NULL if item is not split)
• [out] pxHeadItemSize: Pointer to size of first part (unmodified if no items were retrieved)
• [out] pxTailItemSize: Pointer to size of second part (unmodified if item is not split)
void *xRingbufferReceiveUpTo(RingbufHandle_t xRingbuffer, size_t *pxItemSize, TickType_t xTick-
sToWait, size_t xMaxSize)
Retrieve bytes from a byte buffer, specifying the maximum amount of bytes to retrieve.
Attempt to retrieve data from a byte buffer whilst specifying a maximum number of bytes to retrieve. This
function will block until there is data available for retrieval or until it times out.
Note A call to vRingbufferReturnItem() is required after this to free up the data retrieved.
Note This function should only be called on byte buffers
Note Two calls to RingbufferReceiveUpTo() are required if the bytes wrap around the end of the ring buffer.
Return
• NULL on timeout, *pxItemSize is untouched in that case.
Parameters
• [in] xMaxSize: Maximum number of bytes to return.
void *xRingbufferReceiveUpToFromISR(RingbufHandle_t xRingbuffer, size_t *pxItemSize, size_t
xMaxSize)
Retrieve bytes from a byte buffer, specifying the maximum amount of bytes to retrieve. Call this from an ISR.
Attempt to retrieve bytes from a byte buffer whilst specifying a maximum number of bytes to retrieve. This
function will return immediately if there is no data available for retrieval.
Note A call to vRingbufferReturnItemFromISR() is required after this to free up the data received.
Note This function should only be called on byte buffers
Return
• NULL when the ring buffer is empty, *pxItemSize is untouched in that case.
Parameters
• [in] xMaxSize: Maximum number of bytes to return.
void vRingbufferReturnItem(RingbufHandle_t xRingbuffer, void *pvItem)
Return a previously-retrieved item to the ring buffer.
Note If a split item is retrieved, both parts should be returned by calling this function twice
Parameters

• [in] xRingbuffer: Ring buffer the item was retrieved from

• [in] pvItem: Item that was received earlier
void vRingbufferReturnItemFromISR(RingbufHandle_t xRingbuffer, void *pvItem, BaseType_t
Return a previously-retrieved item to the ring buffer from an ISR.
Note If a split item is retrieved, both parts should be returned by calling this function twice
Parameters
• [in] xRingbuffer: Ring buffer the item was retrieved from
• [in] pvItem: Item that was received earlier
• [out] pxHigherPriorityTaskWoken: Value pointed to will be set to pdTRUE if the
function woke up a higher priority task.
void vRingbufferDelete(RingbufHandle_t xRingbuffer)
Delete a ring buffer.
Note This function will not deallocate any memory if the ring buffer was created using xRingbufferCreat-
eStatic(). Deallocation must be done manually be the user.
Parameters
• [in] xRingbuffer: Ring buffer to delete
size_t xRingbufferGetMaxItemSize(RingbufHandle_t xRingbuffer)
Get maximum size of an item that can be placed in the ring buffer.
This function returns the maximum size an item can have if it was placed in an empty ring buffer.
Note The max item size for a no-split buffer is limited to ((buffer_size/2)-header_size). This limit is imposed
so that an item of max item size can always be sent to the an empty no-split buffer regardless of the
internal positions of the buffer s read/write/free pointers.
Return Maximum size, in bytes, of an item that can be placed in a ring buffer.
Parameters
• [in] xRingbuffer: Ring buffer to query
size_t xRingbufferGetCurFreeSize(RingbufHandle_t xRingbuffer)
Get current free size available for an item/data in the buffer.
This gives the real time free space available for an item/data in the ring buffer. This represents the maximum
size an item/data can have if it was currently sent to the ring buffer.
Warning This API is not thread safe. So, if multiple threads are accessing the same ring buffer, it is the
application s responsibility to ensure atomic access to this API and the subsequent Send
Note An empty no-split buffer has a max current free size for an item that is limited to ((buffer_size/2)-
header_size). See API reference for xRingbufferGetMaxItemSize().
Return Current free size, in bytes, available for an entry
Parameters
• [in] xRingbuffer: Ring buffer to query
BaseType_t xRingbufferAddToQueueSetRead(RingbufHandle_t xRingbuffer, QueueSetHandle_t
xQueueSet)
Add the ring buffer s read semaphore to a queue set.
The ring buffer s read semaphore indicates that data has been written to the ring buffer. This function adds
the ring buffer s read semaphore to a queue set.
Return
• pdTRUE on success, pdFALSE otherwise
Parameters
• [in] xRingbuffer: Ring buffer to add to the queue set
• [in] xQueueSet: Queue set to add the ring buffer s read semaphore to
BaseType_t xRingbufferCanRead(RingbufHandle_t xRingbuffer, QueueSetMemberHandle_t xMem-
ber)
Check if the selected queue set member is the ring buffer s read semaphore.

This API checks if queue set member returned from xQueueSelectFromSet() is the read semaphore of this
ring buffer. If so, this indicates the ring buffer has items waiting to be retrieved.
Return
• pdTRUE when semaphore belongs to ring buffer
• pdFALSE otherwise.
Parameters
• [in] xRingbuffer: Ring buffer which should be checked
• [in] xMember: Member returned from xQueueSelectFromSet
BaseType_t xRingbufferRemoveFromQueueSetRead(RingbufHandle_t xRingbuffer, Queue-
SetHandle_t xQueueSet)
Remove the ring buffer s read semaphore from a queue set.
This specifically removes a ring buffer s read semaphore from a queue set. The read semaphore is used to
indicate when data has been written to the ring buffer
Return
• pdTRUE on success
• pdFALSE otherwise
Parameters
• [in] xRingbuffer: Ring buffer to remove from the queue set
• [in] xQueueSet: Queue set to remove the ring buffer s read semaphore from
void vRingbufferGetInfo(RingbufHandle_t xRingbuffer, UBaseType_t *uxFree, UBaseType_t
*uxRead, UBaseType_t *uxWrite, UBaseType_t *uxAcquire, UBaseType_t
*uxItemsWaiting)
Get information about ring buffer status.
Get information of the a ring buffer s current status such as free/read/write pointer positions, and number of
items waiting to be retrieved. Arguments can be set to NULL if they are not required.
Parameters
• [in] xRingbuffer: Ring buffer to remove from the queue set
• [out] uxFree: Pointer use to store free pointer position
• [out] uxRead: Pointer use to store read pointer position
• [out] uxWrite: Pointer use to store write pointer position
• [out] uxAcquire: Pointer use to store acquire pointer position
• [out] uxItemsWaiting: Pointer use to store number of items (bytes for byte buffer) waiting
to be retrieved
void xRingbufferPrintInfo(RingbufHandle_t xRingbuffer)
Debugging function to print the internal pointers in the ring buffer.
Parameters
• xRingbuffer: Ring buffer to show
Structures
struct xSTATIC_RINGBUFFER
Struct that is equivalent in size to the ring buffer s data structure.
The contents of this struct are not meant to be used directly. This structure is meant to be used when creating
a statically allocated ring buffer where this struct is of the exact size required to store a ring buffer s control
data structure.
Type Definitions
typedef void *RingbufHandle_t
Type by which ring buffers are referenced. For example, a call to xRingbufferCreate() returns a RingbufHan-
dle_t variable that can then be used as a parameter to xRingbufferSend(), xRingbufferReceive(), etc.
typedef struct xSTATIC_RINGBUFFER StaticRingbuffer_t
Struct that is equivalent in size to the ring buffer s data structure.

The contents of this struct are not meant to be used directly. This structure is meant to be used when creating
a statically allocated ring buffer where this struct is of the exact size required to store a ring buffer s control
data structure.
Enumerations
enum RingbufferType_t
Values:
RINGBUF_TYPE_NOSPLIT = 0
No-split buffers will only store an item in contiguous memory and will never split an item. Each item
requires an 8 byte overhead for a header and will always internally occupy a 32-bit aligned size of space.
RINGBUF_TYPE_ALLOWSPLIT
Allow-split buffers will split an item into two parts if necessary in order to store it. Each item requires
an 8 byte overhead for a header, splitting incurs an extra header. Each item will always internally occupy
a 32-bit aligned size of space.
RINGBUF_TYPE_BYTEBUF
Byte buffers store data as a sequence of bytes and do not maintain separate items, therefore byte buffers
have no overhead. All data is stored as a sequence of byte and any number of bytes can be sent or retrieved
each time.
RINGBUF_TYPE_MAX
Hooks
FreeRTOS consists of Idle Hooks and Tick Hooks which allow for application specific functionality to be added to the
Idle Task and Tick Interrupt. ESP-IDF provides its own Idle and Tick Hook API in addition to the hooks provided
by Vanilla FreeRTOS. ESP-IDF hooks have the added benefit of being run time configurable and asymmetrical.
Vanilla FreeRTOS Hooks Idle and Tick Hooks in vanilla FreeRTOS are implemented by the user defining the
functions vApplicationIdleHook() and vApplicationTickHook() respectively somewhere in the ap-
plication. Vanilla FreeRTOS will run the user defined Idle Hook and Tick Hook on every iteration of the Idle Task
and Tick Interrupt respectively.
Vanilla FreeRTOS hooks are referred to as Legacy Hooks in ESP-IDF FreeRTOS. To enable legacy hooks, CON-
FIG_FREERTOS_LEGACY_HOOKS should be enabled in project configuration menu.
Due to vanilla FreeRTOS being designed for single core, vApplicationIdleHook() and vApplica-
tionTickHook() can only be defined once. However, the ESP32 is dual core in nature, therefore same Idle
Hook and Tick Hook are used for both cores (in other words, the hooks are symmetrical for both cores).
ESP-IDF Idle and Tick Hooks For some use-cases it may be necessary for the Idle Tasks or Tick Interrupts to
execute multiple hooks that are configurable at run time.
Furthermore, due to the the dual core nature of the ESP32, it may be necessary for some applications to have separate
hooks for each core.
Therefore the ESP-IDF provides it s own hooks API in addition to the legacy hooks provided by Vanilla FreeRTOS.
The ESP-IDF tick/idle hooks are registered at run time, and each tick/idle hook must be registered to a specific CPU.
When the idle task runs/tick Interrupt occurs on a particular CPU, the CPU will run each of its registered idle/tick
hooks in turn.
Note: Tick interrupt stays active whilst cache is disabled and hence vApplicationTickHook() (legacy case)
or ESP-IDF tick hooks must be placed in internal RAM. Please refer to the SPI flash API documentation for more
details.

Hooks API Reference
Header File
• components/esp_system/include/esp_freertos_hooks.h
Functions
esp_err_t esp_register_freertos_idle_hook_for_cpu(esp_freertos_idle_cb_t new_idle_cb,
UBaseType_t cpuid)
Register a callback to be called from the specified core s idle hook. The callback should return true if it
should be called by the idle hook once per interrupt (or FreeRTOS tick), and return false if it should be called
repeatedly as fast as possible by the idle hook.
Warning Idle callbacks MUST NOT, UNDER ANY CIRCUMSTANCES, CALL A FUNCTION THAT
MIGHT BLOCK.
Return
• ESP_OK: Callback registered to the specified core s idle hook
• ESP_ERR_NO_MEM: No more space on the specified core s idle hook to register callback
• ESP_ERR_INVALID_ARG: cpuid is invalid
Parameters
• [in] new_idle_cb: Callback to be called
• [in] cpuid: id of the core
esp_err_t esp_register_freertos_idle_hook(esp_freertos_idle_cb_t new_idle_cb)
Register a callback to the idle hook of the core that calls this function. The callback should return true if it
should be called by the idle hook once per interrupt (or FreeRTOS tick), and return false if it should be called
repeatedly as fast as possible by the idle hook.
Warning Idle callbacks MUST NOT, UNDER ANY CIRCUMSTANCES, CALL A FUNCTION THAT
MIGHT BLOCK.
Return
• ESP_OK: Callback registered to the calling core s idle hook
• ESP_ERR_NO_MEM: No more space on the calling core s idle hook to register callback
Parameters
• [in] new_idle_cb: Callback to be called
esp_err_t esp_register_freertos_tick_hook_for_cpu(esp_freertos_tick_cb_t new_tick_cb,
UBaseType_t cpuid)
Register a callback to be called from the specified core s tick hook.
Return
• ESP_OK: Callback registered to specified core s tick hook
• ESP_ERR_NO_MEM: No more space on the specified core s tick hook to register the callback
• ESP_ERR_INVALID_ARG: cpuid is invalid
Parameters
• [in] new_tick_cb: Callback to be called
esp_err_t esp_register_freertos_tick_hook(esp_freertos_tick_cb_t new_tick_cb)
Register a callback to be called from the calling core s tick hook.
Return
• ESP_OK: Callback registered to the calling core s tick hook
• ESP_ERR_NO_MEM: No more space on the calling core s tick hook to register the callback
Parameters
• [in] new_tick_cb: Callback to be called
void esp_deregister_freertos_idle_hook_for_cpu(esp_freertos_idle_cb_t old_idle_cb,
UBaseType_t cpuid)
Unregister an idle callback from the idle hook of the specified core.
Parameters
• [in] old_idle_cb: Callback to be unregistered


void esp_deregister_freertos_idle_hook(esp_freertos_idle_cb_t old_idle_cb)
Unregister an idle callback. If the idle callback is registered to the idle hooks of both cores, the idle hook will
be unregistered from both cores.
Parameters
• [in] old_idle_cb: Callback to be unregistered
void esp_deregister_freertos_tick_hook_for_cpu(esp_freertos_tick_cb_t old_tick_cb,
UBaseType_t cpuid)
Unregister a tick callback from the tick hook of the specified core.
Parameters
• [in] old_tick_cb: Callback to be unregistered
void esp_deregister_freertos_tick_hook(esp_freertos_tick_cb_t old_tick_cb)
Unregister a tick callback. If the tick callback is registered to the tick hooks of both cores, the tick hook will
be unregistered from both cores.
Parameters
• [in] old_tick_cb: Callback to be unregistered
Type Definitions
typedef bool (*esp_freertos_idle_cb_t)(void)
typedef void (*esp_freertos_tick_cb_t)(void)
Component Specific Properties
Besides standard component variables that could be gotten with basic cmake build properties FreeRTOS component
also provides an arguments (only one so far) for simpler integration with other modules:
• ORIG_INCLUDE_PATH - contains an absolute path to freertos root include folder. Thus instead of #include
freertos/FreeRTOS.h you can refer to headers directly: #include FreeRTOS.h .
2.7.11 Heap Memory Allocation
Stack and Heap
ESP-IDF applications use the common computer architecture patterns of stack (dynamic memory allocated by pro-
gram control flow) and heap (dynamic memory allocated by function calls), as well as statically allocated memory
(allocated at compile time).
Because ESP-IDF is a multi-threaded RTOS environment, each RTOS task has its own stack. By default, each of
these stacks is allocated from the heap when the task is created. (See xTaskCreateStatic() for the alternative
where stacks are statically allocated.)
Because ESP32 uses multiple types of RAM, it also contains multiple heaps with different capabilities. A capabilities-
based memory allocator allows apps to make heap allocations for different purposes.
For most purposes, the standard libc malloc() and free() functions can be used for heap allocation without any
special consideration.
However, in order to fully make use of all of the memory types and their characteristics, ESP-IDF also has a
capabilities-based heap memory allocator. If you want to have memory with certain properties (for example, DMA-
Capable Memory or executable-memory), you can create an OR-mask of the required capabilities and pass that to
heap_caps_malloc().

Memory Capabilities
The ESP32 contains multiple types of RAM:

• DRAM (Data RAM) is memory used to hold data. This is the most common kind of memory accessed as
heap.
• IRAM (Instruction RAM) usually holds executable data only. If accessed as generic memory, all accesses must
be 32-bit aligned.
• D/IRAM is RAM which can be used as either Instruction or Data RAM.
For more details on these internal memory types, see Memory Types.
It s also possible to connect external SPI RAM to the ESP32 - external RAM can be integrated into the ESP32 s
memory map using the flash cache, and accessed similarly to DRAM.
DRAM uses capability MALLOC_CAP_8BIT (accessible in single byte reads and writes). When calling mal-
loc(), the ESP-IDF malloc() implementation internally calls heap_caps_malloc(size, MAL-
LOC_CAP_8BIT) in order to allocate DRAM that is byte-addressable. To test the free DRAM heap size at runtime,
call cpp:func:heap_caps_get_free_size(MALLOC_CAP_8BIT).
Because malloc uses the capabilities-based allocation system, memory allocated using heap_caps_malloc()
can be freed by calling the standard free() function.
Available Heap
DRAM At startup, the DRAM heap contains all data memory which is not statically allocated by the app. Reducing
statically allocated buffers will increase the amount of available free heap.
To find the amount of statically allocated memory, use the idf.py size command.
Note: Due to a technical limitation, the maximum statically allocated DRAM usage is 160KB. The remaining
160KB (for a total of 320KB of DRAM) can only be allocated at runtime as heap.
Note: At runtime, the available heap DRAM may be less than calculated at compile time, because at startup some
memory is allocated from the heap before the FreeRTOS scheduler is started (including memory for the stacks of
initial FreeRTOS tasks).
IRAM At startup, the IRAM heap contains all instruction memory which is not used by the app executable code.
The idf.py size command can be used to find the amount of IRAM used by the app.
D/IRAM Some memory in the ESP32 is available as either DRAM or IRAM. If memory is allocated from a
D/IRAM region, the free heap size for both types of memory will decrease.
Heap Sizes At startup, all ESP-IDF apps log a summary of all heap addresses (and sizes) at level Info:

I (259) heap_init: At 3FFAE6E0 len 00001920 (6 KiB): DRAM
I (265) heap_init: At 3FFB2EC8 len 0002D138 (180 KiB): DRAM
I (272) heap_init: At 3FFE0440 len 00003AE0 (14 KiB): D/IRAM
I (278) heap_init: At 3FFE4350 len 0001BCB0 (111 KiB): D/IRAM
I (284) heap_init: At 4008944C len 00016BB4 (90 KiB): IRAM
Finding available heap See Heap Information.

Special Capabilities
DMA-Capable Memory Use the MALLOC_CAP_DMA flag to allocate memory which is suitable for use with
hardware DMA engines (for example SPI and I2S). This capability flag excludes any external PSRAM.
32-Bit Accessible Memory If a certain memory structure is only addressed in 32-bit units, for example an array
of ints or pointers, it can be useful to allocate it with the MALLOC_CAP_32BIT flag. This also allows the allocator
to give out IRAM memory; something which it can t do for a normal malloc() call. This can help to use all the
available memory in the ESP32.
Memory allocated with MALLOC_CAP_32BIT can only be accessed via 32-bit reads and writes, any other type of
access will generate a fatal LoadStoreError exception.
External SPI Memory When external RAM is enabled, external SPI RAM under 4MiB in size can be allocated
using standard malloc calls, or via heap_caps_malloc(MALLOC_CAP_SPIRAM), depending on configura-
tion. See Configuring External RAM for more details.
To use the region above the 4MiB limit, you can use the himem API.
API Reference - Heap Allocation
Header File
• components/heap/include/esp_heap_caps.h
Functions
esp_err_t heap_caps_register_failed_alloc_callback(esp_alloc_failed_hook_t callback)
registers a callback function to be invoked if a memory allocation operation fails
Return ESP_OK if callback was registered.
Parameters
• callback: caller defined callback to be invoked
void *heap_caps_malloc(size_t size, uint32_t caps)
Allocate a chunk of memory which has the given capabilities.
Equivalent semantics to libc malloc(), for capability-aware memory.
In IDF, malloc(p) is equivalent to heap_caps_malloc(p, MALLOC_CAP_8BIT).
Return A pointer to the memory allocated on success, NULL on failure
Parameters
• size: Size, in bytes, of the amount of memory to allocate
• caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory to be returned
void heap_caps_free(void *ptr)
Free memory previously allocated via heap_caps_malloc() or heap_caps_realloc().
Equivalent semantics to libc free(), for capability-aware memory.
In IDF, free(p) is equivalent to heap_caps_free(p).
Parameters
• ptr: Pointer to memory previously returned from heap_caps_malloc() or heap_caps_realloc(). Can
be NULL.
void *heap_caps_realloc(void *ptr, size_t size, uint32_t caps)
Reallocate memory previously allocated via heap_caps_malloc() or heap_caps_realloc().
Equivalent semantics to libc realloc(), for capability-aware memory.
In IDF, realloc(p, s) is equivalent to heap_caps_realloc(p, s, MALLOC_CAP_8BIT).

caps parameter can be different to the capabilities that any original ptr was allocated with. In this way,
realloc can be used to move a buffer if necessary to ensure it meets a new set of capabilities.
Return Pointer to a new buffer of size size with capabilities caps , or NULL if allocation failed.
Parameters
• ptr: Pointer to previously allocated memory, or NULL for a new allocation.
• size: Size of the new buffer requested, or 0 to free the buffer.
• caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory desired for the new
allocation.
void *heap_caps_aligned_alloc(size_t alignment, size_t size, uint32_t caps)
Allocate a aligned chunk of memory which has the given capabilities.
Equivalent semantics to libc aligned_alloc(), for capability-aware memory.
Parameters
• alignment: How the pointer received needs to be aligned must be a power of two
void heap_caps_aligned_free(void *ptr)
Used to deallocate memory previously allocated with heap_caps_aligned_alloc.
Note This function is deprecated, plase consider using heap_caps_free() instead
Parameters
• ptr: Pointer to the memory allocated
void *heap_caps_aligned_calloc(size_t alignment, size_t n, size_t size, uint32_t caps)
Allocate a aligned chunk of memory which has the given capabilities. The initialized value in the memory is
set to zero.
Parameters
• alignment: How the pointer received needs to be aligned must be a power of two
• n: Number of continuing chunks of memory to allocate
• size: Size, in bytes, of a chunk of memory to allocate
void *heap_caps_calloc(size_t n, size_t size, uint32_t caps)
Allocate a chunk of memory which has the given capabilities. The initialized value in the memory is set to
zero.
Equivalent semantics to libc calloc(), for capability-aware memory.
In IDF, calloc(p) is equivalent to heap_caps_calloc(p, MALLOC_CAP_8BIT).
Parameters
size_t heap_caps_get_total_size(uint32_t caps)
Get the total size of all the regions that have the given capabilities.
This function takes all regions capable of having the given capabilities allocated in them and adds up the total
space they have.
Return total size in bytes
Parameters
• caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory
size_t heap_caps_get_free_size(uint32_t caps)
Get the total free size of all the regions that have the given capabilities.

This function takes all regions capable of having the given capabilities allocated in them and adds up the free
space they have.
Note that because of heap fragmentation it is probably not possible to allocate a single block of memory of this
size. Use heap_caps_get_largest_free_block() for this purpose.
Return Amount of free bytes in the regions
Parameters
size_t heap_caps_get_minimum_free_size(uint32_t caps)
Get the total minimum free memory of all regions with the given capabilities.
This adds all the low water marks of the regions capable of delivering the memory with the given capabilities.
Note the result may be less than the global all-time minimum available heap of this kind, as low water marks
are tracked per-region. Individual regions heaps may have reached their low water marks at different points
in time. However this result still gives a worst case indication for all-time minimum free heap.
Return Amount of free bytes in the regions
Parameters
size_t heap_caps_get_largest_free_block(uint32_t caps)
Get the largest free block of memory able to be allocated with the given capabilities.
Returns the largest value of s for which heap_caps_malloc(s, caps) will succeed.
Return Size of largest free block in bytes.
Parameters
void heap_caps_get_info(multi_heap_info_t *info, uint32_t caps)
Get heap info for all regions with the given capabilities.
Calls multi_heap_info() on all heaps which share the given capabilities. The information returned is an aggre-
gate across all matching heaps. The meanings of fields are the same as defined for multi_heap_info_t, except
that minimum_free_bytes has the same caveats described in heap_caps_get_minimum_free_size().
Parameters
• info: Pointer to a structure which will be filled with relevant heap metadata.
void heap_caps_print_heap_info(uint32_t caps)
Print a summary of all memory with the given capabilities.
Calls multi_heap_info on all heaps which share the given capabilities, and prints a two-line summary for each,
then a total summary.
Parameters
bool heap_caps_check_integrity_all(bool print_errors)
Check integrity of all heap memory in the system.
Calls multi_heap_check on all heaps. Optionally print errors if heaps are corrupt.
Calling this function is equivalent to calling heap_caps_check_integrity with the caps argument set to MAL-
LOC_CAP_INVALID.
Return True if all heaps are valid, False if at least one heap is corrupt.
Parameters
• print_errors: Print specific errors if heap corruption is found.
bool heap_caps_check_integrity(uint32_t caps, bool print_errors)
Check integrity of all heaps with the given capabilities.
Calls multi_heap_check on all heaps which share the given capabilities. Optionally print errors if the heaps are
corrupt.

See also heap_caps_check_integrity_all to check all heap memory in the system and
heap_caps_check_integrity_addr to check memory around a single address.
Return True if all heaps are valid, False if at least one heap is corrupt.
Parameters
bool heap_caps_check_integrity_addr(intptr_t addr, bool print_errors)
Check integrity of heap memory around a given address.
This function can be used to check the integrity of a single region of heap memory, which contains the given
address.
This can be useful if debugging heap integrity for corruption at a known address, as it has a lower over-
head than checking all heap regions. Note that if the corrupt address moves around between runs (due to
timing or other factors) then this approach won t work and you should call heap_caps_check_integrity or
heap_caps_check_integrity_all instead.
Note The entire heap region around the address is checked, not only the adjacent heap blocks.
Return True if the heap containing the specified address is valid, False if at least one heap is corrupt or the
address doesn t belong to a heap region.
Parameters
• addr: Address in memory. Check for corruption in region containing this address.
void heap_caps_malloc_extmem_enable(size_t limit)
Enable malloc() in external memory and set limit below which malloc() attempts are placed in internal memory.
When external memory is in use, the allocation strategy is to initially try to satisfy smaller allocation requests
with internal memory and larger requests with external memory. This sets the limit between the two, as well
as generally enabling allocation in external memory.
Parameters
• limit: Limit, in bytes.
void *heap_caps_malloc_prefer(size_t size, size_t num, ...)
Allocate a chunk of memory as preference in decreasing order.
Attention The variable parameters are bitwise OR of MALLOC_CAP_* flags indicating the type of memory.
This API prefers to allocate memory with the first parameter. If failed, allocate memory with the next
parameter. It will try in this order until allocating a chunk of memory successfully or fail to allocate
memories with any of the parameters.
Parameters
• num: Number of variable paramters
void *heap_caps_realloc_prefer(void *ptr, size_t size, size_t num, ...)
Return Pointer to a new buffer of size size , or NULL if allocation failed.
Parameters
• ptr: Pointer to previously allocated memory, or NULL for a new allocation.
• size: Size of the new buffer requested, or 0 to free the buffer.
void *heap_caps_calloc_prefer(size_t n, size_t size, size_t num, ...)
Parameters

void heap_caps_dump(uint32_t caps)

Dump the full structure of all heaps with matching capabilities.
Prints a large amount of output to serial (because of locking limitations, the output bypasses stdout/stderr).
For each (variable sized) block in each matching heap, the following output is printed on a single line:
• Block address (the data buffer returned by malloc is 4 bytes after this if heap debugging is set to Basic,
or 8 bytes otherwise).
• Data size (the data size may be larger than the size requested by malloc, either due to heap fragmentation
or because of heap debugging level).
• Address of next block in the heap.
• If the block is free, the address of the next free block is also printed.
Parameters
void heap_caps_dump_all(void)
Dump the full structure of all heaps.
Covers all registered heaps. Prints a large amount of output to serial.
Output is the same as for heap_caps_dump.
size_t heap_caps_get_allocated_size(void *ptr)
Return the size that a particular pointer was allocated with.
Note The app will crash with an assertion failure if the pointer is not valid.
Return Size of the memory allocated at this block.
Parameters
• ptr: Pointer to currently allocated heap memory. Must be a pointer value previously returned by
heap_caps_malloc,malloc,calloc, etc. and not yet freed.
Macros
MALLOC_CAP_EXEC
Flags to indicate the capabilities of the various memory systems.
Memory must be able to run executable code
MALLOC_CAP_32BIT
Memory must allow for aligned 32-bit data accesses.
MALLOC_CAP_8BIT
Memory must allow for 8/16/ -bit data accesses.
MALLOC_CAP_DMA
Memory must be able to accessed by DMA.
MALLOC_CAP_PID2
Memory must be mapped to PID2 memory space (PIDs are not currently used)
MALLOC_CAP_PID3
MALLOC_CAP_PID4
MALLOC_CAP_PID5
MALLOC_CAP_PID6
MALLOC_CAP_PID7
MALLOC_CAP_SPIRAM
Memory must be in SPI RAM.

MALLOC_CAP_INTERNAL
Memory must be internal; specifically it should not disappear when flash/spiram cache is switched off.
MALLOC_CAP_DEFAULT
Memory can be returned in a non-capability-specific memory allocation (e.g. malloc(), calloc()) call.
MALLOC_CAP_IRAM_8BIT
Memory must be in IRAM and allow unaligned access.
MALLOC_CAP_RETENTION
MALLOC_CAP_RTCRAM
Memory must be in RTC fast memory.
MALLOC_CAP_INVALID
Memory can t be used / list end marker.
Type Definitions
typedef void (*esp_alloc_failed_hook_t)(size_t size, uint32_t caps, const char *func-
tion_name)
callback called when a allocation operation fails, if registered
Parameters
• size: in bytes of failed allocation
• caps: capabillites requested of failed allocation
• function_name: function which generated the failure
Thread Safety Heap functions are thread safe, meaning they can be called from different tasks simultaneously
without any limitations.
It is technically possible to call malloc, free, and related functions from interrupt handler (ISR) context. However
this is not recommended, as heap function calls may delay other interrupts. It is strongly recommended to refactor
applications so that any buffers used by an ISR are pre-allocated outside of the ISR. Support for calling heap functions
from ISRs may be removed in a future update.
Heap Tracing & Debugging
The following features are documented on the Heap Memory Debugging page:
• Heap Information (free space, etc.)
• Heap Corruption Detection
• Heap Tracing (memory leak detection, monitoring, etc.)
API Reference - Initialisation
Header File
• components/heap/include/esp_heap_caps_init.h
Functions
void heap_caps_init(void)
Initialize the capability-aware heap allocator.
This is called once in the IDF startup code. Do not call it at other times.
void heap_caps_enable_nonos_stack_heaps(void)
Enable heap(s) in memory regions where the startup stacks are located.
On startup, the pro/app CPUs have a certain memory region they use as stack, so we cannot do allocations
in the regions these stack frames are. When FreeRTOS is completely started, they do not use that memory
anymore and heap(s) there can be enabled.

esp_err_t heap_caps_add_region(intptr_t start, intptr_t end)

Add a region of memory to the collection of heaps at runtime.
Most memory regions are defined in soc_memory_layout.c for the SoC, and are registered via heap_caps_init().
Some regions can t be used immediately and are later enabled via heap_caps_enable_nonos_stack_heaps().
Call this function to add a region of memory to the heap at some later time.
This function does not consider any of the reserved regions or other data in soc_memory_layout, caller
needs to consider this themselves.
All memory within the region specified by start & end parameters must be otherwise unused.
The capabilities of the newly registered memory will be determined by the start address, as looked up in the
regions specified in soc_memory_layout.c.
Use heap_caps_add_region_with_caps() to register a region with custom capabilities.
Return ESP_OK on success, ESP_ERR_INVALID_ARG if a parameter is invalid,
ESP_ERR_NOT_FOUND if the specified start address doesn t reside in a known region, or
any error returned by heap_caps_add_region_with_caps().
Parameters
• start: Start address of new region.
• end: End address of new region.
esp_err_t heap_caps_add_region_with_caps(const uint32_t caps[], intptr_t start, intptr_t end)
Add a region of memory to the collection of heaps at runtime, with custom capabilities.
Similar to heap_caps_add_region(), only custom memory capabilities are specified by the caller.
Return
• ESP_ERR_INVALID_ARG if a parameter is invalid
• ESP_ERR_NO_MEM if no memory to register new heap.
• ESP_ERR_INVALID_SIZE if the memory region is too small to fit a heap
• ESP_FAIL if region overlaps the start and/or end of an existing region
Parameters
• caps: Ordered array of capability masks for the new region, in order of priority. Must have length
SOC_MEMORY_TYPE_NO_PRIOS. Does not need to remain valid after the call returns.
• start: Start address of new region.
• end: End address of new region.
Implementation Notes
Knowledge about the regions of memory in the chip comes from the soc component, which contains memory
layout information for the chip, and the different capabilities of each region. Each region s capabilities are prioritised,
so that (for example) dedicated DRAM and IRAM regions will be used for allocations ahead of the more versatile
D/IRAM regions.
Each contiguous region of memory contains its own memory heap. The heaps are created using the multi_heap
functionality. multi_heap allows any contiguous region of memory to be used as a heap.
The heap capabilities allocator uses knowledge of the memory regions to initialize each individual heap. Allocation
functions in the heap capabilities API will find the most appropriate heap for the allocation (based on desired ca-
pabilities, available space, and preferences for each region s use) and then calling multi_heap_malloc() or
multi_heap_calloc() for the heap situated in that particular region.
Calling free() involves finding the particular heap corresponding to the freed address, and then calling
multi_heap_free() on that particular multi_heap instance.

API Reference - Multi Heap API
(Note: The multi heap API is used internally by the heap capabilities allocator. Most IDF programs will never need
to call this API directly.)
Header File
• components/heap/include/multi_heap.h
Functions
void *multi_heap_aligned_alloc(multi_heap_handle_t heap, size_t size, size_t alignment)
allocate a chunk of memory with specific alignment
Return pointer to the memory allocated, NULL on failure
Parameters
• heap: Handle to a registered heap.
• size: size in bytes of memory chunk
• alignment: how the memory must be aligned
void *multi_heap_malloc(multi_heap_handle_t heap, size_t size)
malloc() a buffer in a given heap
Semantics are the same as standard malloc(), only the returned buffer will be allocated in the specified heap.
Return Pointer to new memory, or NULL if allocation fails.
Parameters
• size: Size of desired buffer.
void multi_heap_aligned_free(multi_heap_handle_t heap, void *p)
free() a buffer aligned in a given heap.
Note This function is deprecated, consider using multi_heap_free() instead
Parameters
• p: NULL, or a pointer previously returned from multi_heap_aligned_alloc() for the same heap.
void multi_heap_free(multi_heap_handle_t heap, void *p)
free() a buffer in a given heap.
Semantics are the same as standard free(), only the argument p must be NULL or have been allocated in
the specified heap.
Parameters
• p: NULL, or a pointer previously returned from multi_heap_malloc() or multi_heap_realloc() for
the same heap.
void *multi_heap_realloc(multi_heap_handle_t heap, void *p, size_t size)
realloc() a buffer in a given heap.
Semantics are the same as standard realloc(), only the argument p must be NULL or have been allocated
in the specified heap.
Return New buffer of size containing contents of p , or NULL if reallocation failed.
Parameters
• p: NULL, or a pointer previously returned from multi_heap_malloc() or multi_heap_realloc() for
the same heap.
• size: Desired new size for buffer.
size_t multi_heap_get_allocated_size(multi_heap_handle_t heap, void *p)
Return the size that a particular pointer was allocated with.

Return Size of the memory allocated at this block. May be more than the original size argument, due to
padding and minimum block sizes.
Parameters
• p: Pointer, must have been previously returned from multi_heap_malloc() or multi_heap_realloc()
for the same heap.
multi_heap_handle_t multi_heap_register(void *start, size_t size)
Register a new heap for use.
This function initialises a heap at the specified address, and returns a handle for future heap operations.
There is no equivalent function for deregistering a heap - if all blocks in the heap are free, you can immediately
start using the memory for other purposes.
Return Handle of a new heap ready for use, or NULL if the heap region was too small to be initialised.
Parameters
• start: Start address of the memory to use for a new heap.
• size: Size (in bytes) of the new heap.
void multi_heap_set_lock(multi_heap_handle_t heap, void *lock)
Associate a private lock pointer with a heap.
The lock argument is supplied to the MULTI_HEAP_LOCK() and MULTI_HEAP_UNLOCK() macros, de-
fined in multi_heap_platform.h.
The lock in question must be recursive.
When the heap is first registered, the associated lock is NULL.
Parameters
• lock: Optional pointer to a locking structure to associate with this heap.
void multi_heap_dump(multi_heap_handle_t heap)
Dump heap information to stdout.
For debugging purposes, this function dumps information about every block in the heap to stdout.
Parameters
bool multi_heap_check(multi_heap_handle_t heap, bool print_errors)
Check heap integrity.
Walks the heap and checks all heap data structures are valid. If any errors are detected, an error-specific
message can be optionally printed to stderr. Print behaviour can be overriden at compile time by defining
MULTI_CHECK_FAIL_PRINTF in multi_heap_platform.h.
Return true if heap is valid, false otherwise.
Parameters
• print_errors: If true, errors will be printed to stderr.
size_t multi_heap_free_size(multi_heap_handle_t heap)
Return free heap size.
Returns the number of bytes available in the heap.
Equivalent to the total_free_bytes member returned by multi_heap_get_heap_info().
Note that the heap may be fragmented, so the actual maximum size for a single malloc() may be lower. To
know this size, see the largest_free_block member returned by multi_heap_get_heap_info().
Return Number of free bytes.
Parameters

size_t multi_heap_minimum_free_size(multi_heap_handle_t heap)

Return the lifetime minimum free heap size.
Equivalent to the minimum_free_bytes member returned by multi_heap_get_info().
Returns the lifetime low water mark of possible values returned from multi_free_heap_size(), for the
specified heap.
Return Number of free bytes.
Parameters
void multi_heap_get_info(multi_heap_handle_t heap, multi_heap_info_t *info)
Return metadata about a given heap.
Fills a multi_heap_info_t structure with information about the specified heap.
Parameters
• info: Pointer to a structure to fill with heap metadata.
Structures
struct multi_heap_info_t
Structure to access heap metadata via multi_heap_get_info.
Public Members
size_t total_free_bytes
Total free bytes in the heap. Equivalent to multi_free_heap_size().
size_t total_allocated_bytes
Total bytes allocated to data in the heap.
size_t largest_free_block
Size of largest free block in the heap. This is the largest malloc-able size.
size_t minimum_free_bytes
Lifetime minimum free heap size. Equivalent to multi_minimum_free_heap_size().
size_t allocated_blocks
Number of (variable size) blocks allocated in the heap.
size_t free_blocks
Number of (variable size) free blocks in the heap.
size_t total_blocks
Total number of (variable size) blocks in the heap.
Type Definitions
typedef struct multi_heap_info *multi_heap_handle_t
Opaque handle to a registered heap.
2.7.12 Heap Memory Debugging
Overview
ESP-IDF integrates tools for requesting heap information, detecting heap corruption, and tracing memory leaks. These
can help track down memory-related bugs.
For general information about the heap memory allocator, see the Heap Memory Allocation page.

Heap Information
To obtain information about the state of the heap:

• xPortGetFreeHeapSize() is a FreeRTOS function which returns the number of free bytes in the (data
memory) heap. This is equivalent to calling heap_caps_get_free_size(MALLOC_CAP_8BIT).
• heap_caps_get_free_size() can also be used to return the current free memory for different memory
capabilities.
• heap_caps_get_largest_free_block() can be used to return the largest free block in the heap.
This is the largest single allocation which is currently possible. Tracking this value and comparing to total free
heap allows you to detect heap fragmentation.
• xPortGetMinimumEverFreeHeapSize() and the related heap_caps_get_minimum_free_size()
can be used to track the heap low water mark since boot.
• heap_caps_get_info() returns a multi_heap_info_t structure which contains the information
from the above functions, plus some additional heap-specific data (number of allocations, etc.).
• heap_caps_print_heap_info() prints a summary to stdout of the information returned by
heap_caps_get_info().
• heap_caps_dump() and heap_caps_dump_all() will output detailed information about the struc-
ture of each block in the heap. Note that this can be large amount of output.
Heap Corruption Detection
Heap corruption detection allows you to detect various types of heap memory errors:
• Out of bounds writes & buffer overflow.
• Writes to freed memory.
• Reads from freed or uninitialized memory,
Assertions The heap implementation (multi_heap.c, etc.) includes a lot of assertions which will fail if the
heap memory is corrupted. To detect heap corruption most effectively, ensure that assertions are enabled in the project
configuration menu under Compiler options -> CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL.
If a heap integrity assertion fails, a line will be printed like CORRUPT HEAP: multi_heap.c:225 detected
at 0x3ffbb71c. The memory address which is printed is the address of the heap structure which has corrupt
content.
It s also possible to manually check heap integrity by calling heap_caps_check_integrity_all() or
related functions. This function checks all of requested heap memory for integrity, and can be used even if assertions
are disabled. If the integrity check prints an error, it will also contain the address(es) of corrupt heap structures.
Memory Allocation Failed Hook Users can use heap_caps_register_failed_alloc_callback()

to register a callback that will be invoked every time a allocation operation fails.
Additionaly user can enable a generation of a system abort if allocation operation fails by following the
steps below: - In the project configuration menu, navigate to Component config -> Heap Mem-
ory Debugging and select Abort if memory allocation fails option (see CON-
FIG_HEAP_ABORT_WHEN_ALLOCATION_FAILS).
The example below show how to register a allocation failure callback:
#include "esp_heap_caps.h"
void heap_caps_alloc_failed_hook(size_t requested_size, uint32_t caps, const char␣

,→*function_name)
{
printf("%s was called but failed to allocate %d bytes with 0x%X capabilities. \n
,→",function_name, requested_size, caps);


void app_main()
{
...
esp_err_t error = heap_caps_register_failed_alloc_callback(heap_caps_alloc_
,→failed_hook);
...
void *ptr = heap_caps_malloc(allocation_size, MALLOC_CAP_DEFAULT);
...
}
Finding Heap Corruption Memory corruption can be one of the hardest classes of bugs to find and fix, as one
area of memory can be corrupted from a totally different place. Some tips:
• A crash with a CORRUPT HEAP: message will usually include a stack trace, but this stack trace is rarely
useful. The crash is the symptom of memory corruption when the system realises the heap is corrupt, but
usually the corruption happened elsewhere and earlier in time.
• Increasing the Heap memory debugging Configuration level to Light impact or Comprehensive can give
you a more accurate message with the first corrupt memory address.
• Adding regular calls to heap_caps_check_integrity_all() or
heap_caps_check_integrity_addr() in your code will help you pin down the exact time
that the corruption happened. You can move these checks around to close in on the section of code that
corrupted the heap.
• Based on the memory address which is being corrupted, you can use JTAG debugging to set a watchpoint on
this address and have the CPU halt when it is written to.
• If you don t have JTAG, but you do know roughly when the corruption happens, then you can set a watch-
point in software just beforehand via esp_cpu_set_watchpoint(). A fatal exception will occur
when the watchpoint triggers. For example esp_cpu_set_watchpoint(0, (void *)addr, 4,
ESP_WATCHPOINT_STORE. Note that watchpoints are per-CPU and are set on the current running CPU
only, so if you don t know which CPU is corrupting memory then you will need to call this function on both
CPUs.
• For buffer overflows, heap tracing in HEAP_TRACE_ALL mode lets you see which callers are allocating which
addresses from the heap. See Heap Tracing To Find Heap Corruption for more details. If you can find the
function which allocates memory with an address immediately before the address which is corrupted, this will
probably be the function which overflows the buffer.
• Calling heap_caps_dump() or heap_caps_dump_all() can give an indication of what heap blocks
are surrounding the corrupted region and may have overflowed/underflowed/etc.
Configuration Temporarily increasing the heap corruption detection level can give more detailed information about
heap corruption errors.
In the project configuration menu, under Component config there is a menu Heap memory debugging.
The setting CONFIG_HEAP_CORRUPTION_DETECTION can be set to one of three levels:
Basic (no poisoning) This is the default level. No special heap corruption features are enabled, but provided
assertions are enabled (the default configuration) then a heap corruption error will be printed if any of the heap s
internal data structures appear overwritten or corrupted. This usually indicates a buffer overrun or out of bounds
write.
If assertions are enabled, an assertion will also trigger if a double-free occurs (the same memory is freed twice).
Calling heap_caps_check_integrity() in Basic mode will check the integrity of all heap structures, and
print errors if any appear to be corrupted.
Light Impact At this level, heap memory is additionally poisoned with head and tail canary bytes before
and after each block which is allocated. If an application writes outside the bounds of allocated buffers, the canary
bytes will be corrupted and the integrity check will fail.

The head canary word is 0xABBA1234 (3412BAAB in byte order), and the tail canary word is 0xBAAD5678
(7856ADBA in byte order).
Basic heap corruption checks can also detect most out of bounds writes, but this setting is more precise as even a
single byte overrun can be detected. With Basic heap checks, the number of overrun bytes before a failure is detected
will depend on the properties of the heap.
Enabling Light Impact checking increases memory usage, each individual allocation will use 9 to 12 additional
bytes of memory (depending on alignment).
Each time free() is called in Light Impact mode, the head and tail canary bytes of the buffer being freed are
checked against the expected values.
When heap_caps_check_integrity() is called, all allocated blocks of heap memory have their canary bytes
checked against the expected values.
In both cases, the check is that the first 4 bytes of an allocated block (before the buffer returned to the user) should
be the word 0xABBA1234. Then the last 4 bytes of the allocated block (after the buffer returned to the user) should
be the word 0xBAAD5678.
Different values usually indicate buffer underrun or overrun, respectively.
Comprehensive This level incorporates the light impact detection features plus additional checks for
uninitialised-access and use-after-free bugs. In this mode, all freshly allocated memory is filled with the pattern
0xCE, and all freed memory is filled with the pattern 0xFE.
Enabling Comprehensive detection has a substantial runtime performance impact (as all memory needs to be set
to the allocation patterns each time a malloc/free completes, and the memory also needs to be checked each time.)
However it allows easier detection of memory corruption bugs which are much more subtle to find otherwise. It is
recommended to only enable this mode when debugging, not in production.
Crashes in Comprehensive Mode If an application crashes reading/writing an address related to 0xCECECECE

in Comprehensive mode, this indicates it has read uninitialized memory. The application should be changed to either
use calloc() (which zeroes memory), or initialize the memory before using it. The value 0xCECECECE may also be
seen in stack-allocated automatic variables, because in IDF most task stacks are originally allocated from the heap
and in C stack memory is uninitialized by default.
If an application crashes and the exception register dump indicates that some addresses or values were 0xFEFEFEFE,
this indicates it is reading heap memory after it has been freed (a use after free bug .) The application should be
changed to not access heap memory after it has been freed.
If a call to malloc() or realloc() causes a crash because it expected to find the pattern 0xFEFEFEFE in free memory
and a different pattern was found, then this indicates the app has a use-after-free bug where it is writing to memory
which has already been freed.
Manual Heap Checks in Comprehensive Mode Calls to heap_caps_check_integrity() may print er-
rors relating to 0xFEFEFEFE, 0xABBA1234 or 0xBAAD5678. In each case the checker is expecting to find a given
pattern, and will error out if this is not found:
• For free heap blocks, the checker expects to find all bytes set to 0xFE. Any other values indicate a use-after-free
bug where free memory has been incorrectly overwritten.
• For allocated heap blocks, the behaviour is the same as for Light Impact mode. The canary bytes 0xABBA1234
and 0xBAAD5678 are checked at the head and tail of each allocated buffer, and any variation indicates a buffer
overrun/underrun.
Heap Task Tracking
Heap Task Tracking can be used to get per task info for heap memory allocation. Application has to specify the heap
capabilities for which the heap allocation is to be tracked.
Example code is provided in system/heap_task_tracking

Heap Tracing
Heap Tracing allows tracing of code which allocates/frees memory. Two tracing modes are supported:
• Standalone. In this mode trace data are kept on-board, so the size of gathered information is limited by the
buffer assigned for that purposes. Analysis is done by the on-board code. There are a couple of APIs available
for accessing and dumping collected info.
• Host-based. This mode does not have the limitation of the standalone mode, because trace data are sent to the
host over JTAG connection using app_trace library. Later on they can be analysed using special tools.
Heap tracing can perform two functions:
• Leak checking: find memory which is allocated and never freed.
• Heap use analysis: show all functions that are allocating/freeing memory while the trace is running.
How To Diagnose Memory Leaks If you suspect a memory leak, the first step is to figure out which part of the
program is leaking memory. Use the xPortGetFreeHeapSize(), heap_caps_get_free_size(), or
related functions to track memory use over the life of the application. Try to narrow the leak down to a single function
or sequence of functions where free memory always decreases and never recovers.
Standalone Mode Once you ve identified the code which you think is leaking:
• In the project configuration menu, navigate to Component settings -> Heap Memory Debugging
-> Heap tracing and select Standalone option (see CONFIG_HEAP_TRACING_DEST).
• Call the function heap_trace_init_standalone() early in the program, to register a buffer which
can be used to record the memory trace.
• Call the function heap_trace_start() to begin recording all mallocs/frees in the system. Call this
immediately before the piece of code which you suspect is leaking memory.
• Call the function heap_trace_stop() to stop the trace once the suspect piece of code has finished exe-
cuting.
• Call the function heap_trace_dump() to dump the results of the heap trace.
An example:
#include "esp_heap_trace.h"
#define NUM_RECORDS 100

static heap_trace_record_t trace_record[NUM_RECORDS]; // This buffer must be in␣
,→internal RAM
...
void app_main()
{
...
ESP_ERROR_CHECK( heap_trace_init_standalone(trace_record, NUM_RECORDS) );
...
}
void some_function()
{
ESP_ERROR_CHECK( heap_trace_start(HEAP_TRACE_LEAKS) );
do_something_you_suspect_is_leaking();
ESP_ERROR_CHECK( heap_trace_stop() );
heap_trace_dump();
...
}
The output from the heap trace will look something like this:

2 allocations trace (100 entry buffer)

32 bytes (@ 0x3ffaf214) allocated CPU 0 ccount 0x2e9b7384 caller␣
,→0x400d276d:0x400d27c1
0x400d276d: leak_some_memory at /path/to/idf/examples/get-started/blink/main/./

,→blink.c:27
0x400d27c1: blink_task at /path/to/idf/examples/get-started/blink/main/./blink.c:52
8 bytes (@ 0x3ffaf804) allocated CPU 0 ccount 0x2e9b79c0 caller␣

,→0x400d2776:0x400d27c1
0x400d2776: leak_some_memory at /path/to/idf/examples/get-started/blink/main/./

,→blink.c:29
0x400d27c1: blink_task at /path/to/idf/examples/get-started/blink/main/./blink.c:52
40 bytes 'leaked' in trace (2 allocations)

total allocations 2 total frees 0
(Above example output is using IDF Monitor to automatically decode PC addresses to their source files & line number.)
The first line indicates how many allocation entries are in the buffer, compared to its total size.
In HEAP_TRACE_LEAKS mode, for each traced memory allocation which has not already been freed a line is printed
with:
• XX bytes is number of bytes allocated
• @ 0x... is the heap address returned from malloc/calloc.
• CPU x is the CPU (0 or 1) running when the allocation was made.
• ccount 0x... is the CCOUNT (CPU cycle count) register value when the allocation was mode. Is different
for CPU 0 vs CPU 1.
• caller 0x... gives the call stack of the call to malloc()/free(), as a list of PC addresses. These can be
decoded to source files and line numbers, as shown above.
The depth of the call stack recorded for each trace entry can be configured in the project configuration menu, under
Heap Memory Debugging -> Enable heap tracing -> Heap tracing stack depth. Up to 10
stack frames can be recorded for each allocation (the default is 2). Each additional stack frame increases the memory
usage of each heap_trace_record_t record by eight bytes.
Finally, the total number of leaked bytes (bytes allocated but not freed while trace was running) is printed, and
the total number of allocations this represents.
A warning will be printed if the trace buffer was not large enough to hold all the allocations which happened. If you
see this warning, consider either shortening the tracing period or increasing the number of records in the trace buffer.
Host-Based Mode Once you ve identified the code which you think is leaking:
• In the project configuration menu, navigate to Component settings -> Heap Memory Debugging
-> CONFIG_HEAP_TRACING_DEST and select Host-Based.
• In the project configuration menu, navigate to Component settings -> Application Level Trac-
ing -> CONFIG_APPTRACE_DESTINATION and select Trace memory.
• In the project configuration menu, navigate to Component settings -> Application Level Trac-
ing -> FreeRTOS SystemView Tracing and enable CONFIG_APPTRACE_SV_ENABLE.
• Call the function heap_trace_init_tohost() early in the program, to initialize JTAG heap tracing
module.
• Call the function heap_trace_start() to begin recording all mallocs/frees in the system. Call this
immediately before the piece of code which you suspect is leaking memory. In host-based mode argument to
this function is ignored and heap tracing module behaves like HEAP_TRACE_ALL was passed: all allocations
and deallocations are sent to the host.
• Call the function heap_trace_stop() to stop the trace once the suspect piece of code has finished exe-
cuting.
An example:

#include "esp_heap_trace.h"
...
void app_main()
{
...
ESP_ERROR_CHECK( heap_trace_init_tohost() );
...
}
void some_function()
{
ESP_ERROR_CHECK( heap_trace_start(HEAP_TRACE_LEAKS) );
do_something_you_suspect_is_leaking();
ESP_ERROR_CHECK( heap_trace_stop() );
...
}
To gather and analyse heap trace do the following on the host:

1. Build the program and download it to the target as described in Getting Started Guide.
2. Run OpenOCD (see JTAG Debugging).
Note: In order to use this feature you need OpenOCD version v0.10.0-esp32-20181105 or later.
3. You can use GDB to start and/or stop tracing automatically. To do this you need to prepare special gdbinit
file:
target remote :3333
mon reset halt

flushregs
tb heap_trace_start
commands
mon esp sysview start file:///tmp/heap.svdat
c
end
tb heap_trace_stop
commands
mon esp sysview stop
end
Using this file GDB will connect to the target, reset it, and start tracing when program hits breakpoint at
heap_trace_start(). Trace data will be saved to /tmp/heap_log.svdat. Tracing will be stopped when
program hits breakpoint at heap_trace_stop().
4. Run GDB using the following command xtensa-esp32-elf-gdb -x gdbinit </path/to/
program/elf>
5. Quit GDB when program stops at heap_trace_stop(). Trace data are saved in /tmp/heap.svdat
6. Run processing script $IDF_PATH/tools/esp_app_trace/sysviewtrace_proc.py -p -b
</path/to/program/elf> /tmp/heap_log.svdat
The output from the heap trace will look something like this:

Parse trace from '/tmp/heap.svdat'...

Stop parsing trace. (Timeout 0.000000 sec while reading 1 bytes!)
Process events from '['/tmp/heap.svdat']'...
[0.002244575] HEAP: Allocated 1 bytes @ 0x3ffaffd8 from task "alloc" on core 0 by:
/home/user/projects/esp/esp-idf/examples/system/sysview_tracing_heap_log/main/
,→sysview_heap_log.c:47
/home/user/projects/esp/esp-idf/components/freertos/port.c:355 (discriminator 1)
[0.002258425] HEAP: Allocated 2 bytes @ 0x3ffaffe0 from task "alloc" on core 0 by:
[0.002563725] HEAP: Freed bytes @ 0x3ffaffe0 from task "free" on core 0 by:
,→sysview_heap_log.c:31 (discriminator 9)
[0.002782950] HEAP: Freed bytes @ 0x3ffb40b8 from task "main" on core 0 by:
/home/user/projects/esp/esp-idf/components/freertos/tasks.c:4590
[0.002798700] HEAP: Freed bytes @ 0x3ffb50bc from task "main" on core 0 by:
[0.102666150] HEAP: Freed bytes @ 0x3ffaffe8 from task "free" on core 0 by:
[0.202451725] HEAP: Allocated 6 bytes @ 0x3ffafff0 from task "alloc" on core 0 by:
[0.202667075] HEAP: Freed bytes @ 0x3ffafff0 from task "free" on core 0 by:
[0.302451475] HEAP: Allocated 8 bytes @ 0x3ffb40b8 from task "alloc" on core 0 by:


[0.302667500] HEAP: Freed bytes @ 0x3ffb40b8 from task "free" on core 0 by:
Processing completed.
Processed 1019 events
=============== HEAP TRACE REPORT ===============
Processed 14 heap events.
[0.002244575] HEAP: Allocated 1 bytes @ 0x3ffaffd8 from task "alloc" on core 0 by:
Found 10 leaked bytes in 4 blocks.
Heap Tracing To Find Heap Corruption Heap tracing can also be used to help track down heap corruption.
When a region in heap is corrupted, it may be from some other part of the program which allocated memory at a
nearby address.
If you have some idea at what time the corruption occurred, enabling heap tracing in HEAP_TRACE_ALL mode
allows you to record all of the functions which allocated memory, and the addresses of the allocations.
Using heap tracing in this way is very similar to memory leak detection as described above. For memory which is
allocated and not freed, the output is the same. However, records will also be shown for memory which has been
freed.
Performance Impact Enabling heap tracing in menuconfig increases the code size of your program, and has a very
small negative impact on performance of heap allocation/free operations even when heap tracing is not running.
When heap tracing is running, heap allocation/free operations are substantially slower than when heap tracing is
stopped. Increasing the depth of stack frames recorded for each allocation (see above) will also increase this perfor-
mance impact.
False-Positive Memory Leaks Not everything printed by heap_trace_dump() is necessarily a memory leak.
Among things which may show up here, but are not memory leaks:
• Any memory which is allocated after heap_trace_start() but then freed after
heap_trace_stop() will appear in the leak dump.

• Allocations may be made by other tasks in the system. Depending on the timing of these tasks, it s quite
possible this memory is freed after heap_trace_stop() is called.
• The first time a task uses stdio - for example, when it calls printf() - a lock (RTOS mutex semaphore) is
allocated by the libc. This allocation lasts until the task is deleted.
• Certain uses of printf(), such as printing floating point numbers, will allocate some memory from the heap
on demand. These allocations last until the task is deleted.
• The Bluetooth, WiFi, and TCP/IP libraries will allocate heap memory buffers to handle incoming or outgoing
data. These memory buffers are usually short lived, but some may be shown in the heap leak trace if the data
was received/transmitted by the lower levels of the network while the leak trace was running.
• TCP connections will continue to use some memory after they are closed, because of the TIME_WAIT state.
After the TIME_WAIT period has completed, this memory will be freed.
One way to differentiate between real and false positive memory leaks is to call the suspect code multiple
times while tracing is running, and look for patterns (multiple matching allocations) in the heap trace output.
API Reference - Heap Tracing
Header File
• components/heap/include/esp_heap_trace.h
Functions
esp_err_t heap_trace_init_standalone(heap_trace_record_t *record_buffer, size_t num_records)
Initialise heap tracing in standalone mode.
This function must be called before any other heap tracing functions.
To disable heap tracing and allow the buffer to be freed, stop tracing and then call
heap_trace_init_standalone(NULL, 0);
Return
• ESP_ERR_NOT_SUPPORTED Project was compiled without heap tracing enabled in menuconfig.
• ESP_ERR_INVALID_STATE Heap tracing is currently in progress.
• ESP_OK Heap tracing initialised successfully.
Parameters
• record_buffer: Provide a buffer to use for heap trace data. Must remain valid any time heap
tracing is enabled, meaning it must be allocated from internal memory not in PSRAM.
• num_records: Size of the heap trace buffer, as number of record structures.
esp_err_t heap_trace_init_tohost(void)
Initialise heap tracing in host-based mode.
This function must be called before any other heap tracing functions.
Return
• ESP_ERR_INVALID_STATE Heap tracing is currently in progress.
• ESP_OK Heap tracing initialised successfully.
esp_err_t heap_trace_start(heap_trace_mode_t mode)
Start heap tracing. All heap allocations & frees will be traced, until heap_trace_stop() is called.
Note heap_trace_init_standalone() must be called to provide a valid buffer, before this function is called.
Note Calling this function while heap tracing is running will reset the heap trace state and continue tracing.
Return
• ESP_ERR_INVALID_STATE A non-zero-length buffer has not been set via
heap_trace_init_standalone().
• ESP_OK Tracing is started.
Parameters
• mode: Mode for tracing.
– HEAP_TRACE_ALL means all heap allocations and frees are traced.

– HEAP_TRACE_LEAKS means only suspected memory leaks are traced. (When memory is
freed, the record is removed from the trace buffer.)
esp_err_t heap_trace_stop(void)
Stop heap tracing.
Return
• ESP_ERR_INVALID_STATE Heap tracing was not in progress.
• ESP_OK Heap tracing stopped..
esp_err_t heap_trace_resume(void)
Resume heap tracing which was previously stopped.
Unlike heap_trace_start(), this function does not clear the buffer of any pre-existing trace records.
The heap trace mode is the same as when heap_trace_start() was last called (or HEAP_TRACE_ALL if
heap_trace_start() was never called).
Return
• ESP_ERR_INVALID_STATE Heap tracing was already started.
• ESP_OK Heap tracing resumed.
size_t heap_trace_get_count(void)
Return number of records in the heap trace buffer.
It is safe to call this function while heap tracing is running.
esp_err_t heap_trace_get(size_t index, heap_trace_record_t *record)
Return a raw record from the heap trace buffer.
Note It is safe to call this function while heap tracing is running, however in HEAP_TRACE_LEAK mode
record indexing may skip entries unless heap tracing is stopped first.
Return
• ESP_ERR_INVALID_STATE Heap tracing was not initialised.
• ESP_ERR_INVALID_ARG Index is out of bounds for current heap trace record count.
• ESP_OK Record returned successfully.
Parameters
• index: Index (zero-based) of the record to return.
• [out] record: Record where the heap trace record will be copied.
void heap_trace_dump(void)
Dump heap trace record data to stdout.
Note It is safe to call this function while heap tracing is running, however in HEAP_TRACE_LEAK mode
the dump may skip entries unless heap tracing is stopped first.
Structures
struct heap_trace_record_t
Trace record data type. Stores information about an allocated region of memory.
Public Members
uint32_t ccount
CCOUNT of the CPU when the allocation was made. LSB (bit value 1) is the CPU number (0 or 1).
void *address
Address which was allocated.
size_t size
Size of the allocation.

void *alloced_by[CONFIG_HEAP_TRACING_STACK_DEPTH]
Call stack of the caller which allocated the memory.
void *freed_by[CONFIG_HEAP_TRACING_STACK_DEPTH]
Call stack of the caller which freed the memory (all zero if not freed.)
Macros
CONFIG_HEAP_TRACING_STACK_DEPTH
Enumerations
enum heap_trace_mode_t
Values:
HEAP_TRACE_ALL
HEAP_TRACE_LEAKS
2.7.13 High Resolution Timer
Overview
Although FreeRTOS provides software timers, these timers have a few limitations:
• Maximum resolution is equal to RTOS tick period
• Timer callbacks are dispatched from a low-priority task
Hardware timers are free from both of the limitations, but often they are less convenient to use. For example,
application components may need timer events to fire at certain times in the future, but the hardware timer only
contains one compare value used for interrupt generation. This means that some facility needs to be built on top
of the hardware timer to manage the list of pending events can dispatch the callbacks for these events as corresponding
hardware interrupts happen.
An interrupt level of the handler depends on the CONFIG_ESP_TIMER_INTERRUPT_LEVEL option. It allows to set
this: 1, 2 or 3 level (by default 1). Raising the level, the interrupt handler can reduce the timer processing delay.
esp_timer set of APIs provides one-shot and periodic timers, microsecond time resolution, and 64-bit range.
Internally, esp_timer uses a 64-bit hardware timer, where the implemention depends on CON-
FIG_ESP_TIMER_IMPL. Available options are:
• LAC timer
• (legacy) FRC2 timer
Note: The FRC2 is a legacy option for ESP32 until v4.2, a 32-bit hardware timer was used. Starting at v4.2, use the
new LAC timer option instead, it has a simpler implementation, and has smaller run time overhead because software
handling of timer overflow is not needed.
Timer callbacks can dispatched by two methods:

• ESP_TIMER_TASK
• ESP_TIMER_ISR. Available only if CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD is en-
abled (by default disabled).
ESP_TIMER_TASK. Timer callbacks are dispatched from a high-priority esp_timer task. Because all the call-
backs are dispatched from the same task, it is recommended to only do the minimal possible amount of work from
the callback itself, posting an event to a lower priority task using a queue instead.
If other tasks with priority higher than esp_timer are running, callback dispatching will be delayed until
esp_timer task has a chance to run. For example, this will happen if a SPI Flash operation is in progress.

ESP_TIMER_ISR. Timer callbacks are dispatched directly from the timer interrupt handler. This method is useful
for some simple callbacks which aim for lower latency.
Creating and starting a timer, and dispatching the callback takes some time. Therefore there is a lower limit to the
timeout value of one-shot esp_timer. If esp_timer_start_once() is called with a timeout value less than
20us, the callback will be dispatched only after approximately 20us.
Periodic esp_timer also imposes a 50us restriction on the minimal timer period. Periodic software timers with
period of less than 50us are not practical since they would consume most of the CPU time. Consider using dedicated
hardware peripherals or DMA features if you find that a timer with small period is required.
Using esp_timer APIs
Single timer is represented by esp_timer_handle_t type. Timer has a callback function associated with it.
This callback function is called from the esp_timer task each time the timer elapses.
• To create a timer, call esp_timer_create().
• To delete the timer when it is no longer needed, call esp_timer_delete().
The timer can be started in one-shot mode or in periodic mode.
• To start the timer in one-shot mode, call esp_timer_start_once(), passing the time interval after
which the callback should be called. When the callback gets called, the timer is considered to be stopped.
• To start the timer in periodic mode, call esp_timer_start_periodic(), passing the period with which
the callback should be called. The timer keeps running until esp_timer_stop() is called.
Note that the timer must not be running when esp_timer_start_once() or
esp_timer_start_periodic() is called. To restart a running timer, call esp_timer_stop()
first, then call one of the start functions.
Callback functions
Timer callbacks which are processed by ESP_TIMER_ISR method should not call the
context switch call - portYIELD_FROM_ISR(), instead of this you should use the
esp_timer_isr_dispatch_need_yield() function. The context switch will be done after all ISR
dispatch timers have been processed, if required by the system.
esp_timer during the light sleep
During light sleep, the esp_timer counter stops and no callback functions are called. Instead, the time is counted
by the RTC counter. Upon waking up, the system gets the difference between the counters and calls a function that
advances the esp_timer counter. Since the counter has been advanced, the system starts calling callbacks that were
not called during sleep. The number of callbacks depends on the duration of the sleep and the period of the timers.
It can lead to overflow of some queues. This only applies to periodic timers, one-shot timers will be called once.
This behavior can be changed by calling esp_timer_stop() before sleeping. In some cases, this can
be inconvenient, and instead of the stop function, you can use the skip_unhandled_events option during
esp_timer_create(). When the skip_unhandled_events is true, if a periodic timer expires one or more times
during light sleep then only one callback is called on wake.
Using the skip_unhandled_events option with automatic light sleep (see Power Management APIs) helps to reduce the
consumption of the system when it is in light sleep. The duration of light sleep is also determined by esp_timers.
Timers with skip_unhandled_events option will not wake up the system.
Handling callbacks
esp_timer is designed to achieve a high-resolution low latency timer and the ability to handle delayed events. If the
timer is late then the callback will be called as soon as possible, it will not be lost. In the worst case, when the timer has
not been processed for more than one period (for periodic timers), in this case the callbacks will be called one after

the other without waiting for the set period. This can be bad for some applications, and the skip_unhandled_events
option was introduced to eliminate this behavior. If skip_unhandled_events is set then a periodic timer that has expired
multiple times without being able to call the callback will still result in only one callback event once processing is
possible.
Obtaining Current Time
esp_timer also provides a convenience function to obtain the time passed since start-up, with microsecond pre-
cision: esp_timer_get_time(). This function returns the number of microseconds since esp_timer was
initialized, which usually happens shortly before app_main function is called.
Unlike gettimeofday function, values returned by esp_timer_get_time():
• Start from zero after the chip wakes up from deep sleep
• Do not have timezone or DST adjustments applied
Application Example
The following example illustrates usage of esp_timer APIs: system/esp_timer.
API Reference
Header File
• components/esp_timer/include/esp_timer.h
Functions
esp_err_t esp_timer_early_init(void)
Minimal initialization of esp_timer.
This function can be called very early in startup process, after this call only esp_timer_get_time function can
be used.
Note This function is called from startup code. Applications do not need to call this function before using
other esp_timer APIs.
Return
esp_err_t esp_timer_init(void)
Initialize esp_timer library.
Note This function is called from startup code. Applications do not need to call this function before using
other esp_timer APIs. Before calling this function, esp_timer_early_init must be called by the startup
code.
Return
• other errors from interrupt allocator
esp_err_t esp_timer_deinit(void)
De-initialize esp_timer library.
Note Normally this function should not be called from applications
Return
• ESP_ERR_INVALID_STATE if not yet initialized

esp_err_t esp_timer_create(const esp_timer_create_args_t *create_args, esp_timer_handle_t

*out_handle)
Create an esp_timer instance.
Note When done using the timer, delete it with esp_timer_delete function.
Return
• ESP_ERR_INVALID_ARG if some of the create_args are not valid
• ESP_ERR_INVALID_STATE if esp_timer library is not initialized yet
• ESP_ERR_NO_MEM if memory allocation fails
Parameters
• create_args: Pointer to a structure with timer creation arguments. Not saved by the library,
can be allocated on the stack.
• [out] out_handle: Output, pointer to esp_timer_handle_t variable which will hold the created
timer handle.
esp_err_t esp_timer_start_once(esp_timer_handle_t timer, uint64_t timeout_us)
Start one-shot timer.
Timer should not be running when this function is called.
Return
• ESP_ERR_INVALID_ARG if the handle is invalid
• ESP_ERR_INVALID_STATE if the timer is already running
Parameters
• timer: timer handle created using esp_timer_create
• timeout_us: timer timeout, in microseconds relative to the current moment
esp_err_t esp_timer_start_periodic(esp_timer_handle_t timer, uint64_t period)
Start a periodic timer.
Timer should not be running when this function is called. This function will start the timer which will trigger
every period microseconds.
Return
• ESP_ERR_INVALID_STATE if the timer is already running
Parameters
• period: timer period, in microseconds
esp_err_t esp_timer_stop(esp_timer_handle_t timer)
Stop the timer.
This function stops the timer previously started using esp_timer_start_once or esp_timer_start_periodic.
Return
• ESP_ERR_INVALID_STATE if the timer is not running
Parameters
esp_err_t esp_timer_delete(esp_timer_handle_t timer)
Delete an esp_timer instance.
The timer must be stopped before deleting. A one-shot timer which has expired does not need to be stopped.
Return
• ESP_ERR_INVALID_STATE if the timer is running
Parameters
• timer: timer handle allocated using esp_timer_create

int64_t esp_timer_get_time(void)
Get time in microseconds since boot.
Return number of microseconds since underlying timer has been started
int64_t esp_timer_get_next_alarm(void)
Get the timestamp when the next timeout is expected to occur.
Return Timestamp of the nearest timer event, in microseconds. The timebase is the same as for the values
returned by esp_timer_get_time.
int64_t esp_timer_get_next_alarm_for_wake_up(void)
Get the timestamp when the next timeout is expected to occur skipping those which have
skip_unhandled_events flag.
Return Timestamp of the nearest timer event, in microseconds. The timebase is the same as for the values
returned by esp_timer_get_time.
esp_err_t esp_timer_get_period(esp_timer_handle_t timer, uint64_t *period)
Get the period of a timer.
This function fetches the timeout period of a timer.
Note The timeout period is the time interval with which a timer restarts after expiry. For one-shot timers, the
period is 0 as there is no periodicity associated with such timers.
Return
• ESP_ERR_INVALID_ARG if the arguments are invalid
Parameters
• period: memory to store the timer period value in microseconds
esp_err_t esp_timer_get_expiry_time(esp_timer_handle_t timer, uint64_t *expiry)
Get the expiry time of a one-shot timer.
This function fetches the expiry time of a one-shot timer.
Note This API returns a valid expiry time only for a one-shot timer. It returns an error if the timer handle
passed to the function is for a periodic timer.
Return
• ESP_ERR_INVALID_ARG if the arguments are invalid
• ESP_ERR_NOT_SUPPORTED if the timer type is periodic
Parameters
• expiry: memory to store the timeout value in microseconds
esp_err_t esp_timer_dump(FILE *stream)
Dump the list of timers to a stream.
If CONFIG_ESP_TIMER_PROFILING option is enabled, this prints the list of all the existing timers. Oth-
erwise, only the list active timers is printed.
The format is:
name period alarm times_armed times_triggered total_callback_run_time
where:
name timer name (if CONFIG_ESP_TIMER_PROFILING is defined), or timer pointer period period
of timer, in microseconds, or 0 for one-shot timer alarm - time of the next alarm, in microseconds since boot,
or 0 if the timer is not started
The following fields are printed if CONFIG_ESP_TIMER_PROFILING is defined:
times_armed number of times the timer was armed via esp_timer_start_X times_triggered - number of
times the callback was called total_callback_run_time - total time taken by callback to execute, across all calls

Return
• ESP_ERR_NO_MEM if can not allocate temporary buffer for the output
Parameters
• stream: stream (such as stdout) to dump the information to
bool esp_timer_is_active(esp_timer_handle_t timer)
Returns status of a timer, active or not.
This function is used to identify if the timer is still active or not.
Return
• 1 if timer is still active
• 0 if timer is not active.
Parameters
Structures
struct esp_timer_create_args_t
Timer configuration passed to esp_timer_create.
Public Members
esp_timer_cb_t callback
Function to call when timer expires.
void *arg
Argument to pass to the callback.
esp_timer_dispatch_t dispatch_method
Call the callback from task or from ISR.
const char *name
Timer name, used in esp_timer_dump function.
bool skip_unhandled_events
Skip unhandled events for periodic timers.
Type Definitions
typedef struct esp_timer *esp_timer_handle_t
Opaque type representing a single esp_timer.
typedef void (*esp_timer_cb_t)(void *arg)
Timer callback function type.
Parameters
• arg: pointer to opaque user-specific data
Enumerations
enum esp_timer_dispatch_t
Method for dispatching timer callback.
Values:
ESP_TIMER_TASK
Callback is called from timer task.
ESP_TIMER_MAX
Count of the methods for dispatching timer callback.

2.7.14 The himem allocation API
Overview
The ESP32 can access external SPI RAM transparently, so you can use it as normal memory in your program code.
However, because the address space for external memory is limited in size, only the first 4MiB can be used as such.
Access to the remaining memory is still possible, however this needs to go through a bankswitching scheme controlled
by the himem API.
Specifically, what is implemented by the himem API is a bankswitching scheme. Hardware-wise, the 4MiB region
for external SPI RAM is mapped into the CPU address space by a MMU, which maps a configurable 32K bank/page
of external SPI RAM into each of the 32K pages in the 4MiB region accessed by the CPU. For external memories
that are <=4MiB, this MMU is configured to unity mapping, effectively mapping each CPU address 1-to-1 to the
external SPI RAM address.
In order to use the himem API, you have to enable it in the menuconfig using CON-
FIG_SPIRAM_BANKSWITCH_ENABLE, as well as set the amount of banks reserved for this in CON-
FIG_SPIRAM_BANKSWITCH_RESERVE. This decreases the amount of external memory allocated by functions
like malloc(), but it allows you to use the himem api to map any of the remaining memory into the reserved
banks.
The himem API is more-or-less an abstraction of the bankswitching scheme: it allows you to claim one or more banks
of address space (called regions in the API) as well as one or more of banks of memory to map into the ranges.
Example
An example doing a simple memory test of the high memory range is available in esp-idf: system/himem
API Reference
Header File
• components/esp_hw_support/include/soc/esp32/himem.h
Functions
esp_err_t esp_himem_alloc(size_t size, esp_himem_handle_t *handle_out)
Allocate a block in high memory.
Return - ESP_OK if succesful
• ESP_ERR_INVALID_SIZE if size is not a multiple of 32K
Parameters
• size: Size of the to-be-allocated block, in bytes. Note that this needs to be a multiple of the
external RAM mmu block size (32K).
• [out] handle_out: Handle to be returned
esp_err_t esp_himem_alloc_map_range(size_t size, esp_himem_rangehandle_t *handle_out)
Allocate a memory region to map blocks into.
This allocates a contiguous CPU memory region that can be used to map blocks of physical memory into.
Return - ESP_OK if succesful
• ESP_ERR_NO_MEM if out of memory or address space
• ESP_ERR_INVALID_SIZE if size is not a multiple of 32K
Parameters
• size: Size of the range to be allocated. Note this needs to be a multiple of the external RAM mmu
block size (32K).
• [out] handle_out: Handle to be returned

esp_err_t esp_himem_map(esp_himem_handle_t handle, esp_himem_rangehandle_t range, size_t

ram_offset, size_t range_offset, size_t len, int flags, void **out_ptr)
Map a block of high memory into the CPUs address space.
This effectively makes the block available for read/write operations.
Note The region to be mapped needs to have offsets and sizes that are aligned to the SPI RAM MMU block
size (32K)
Return - ESP_OK if the memory could be mapped
• ESP_ERR_INVALID_ARG if offset, range or len aren t MMU-block-aligned (32K)
• ESP_ERR_INVALID_SIZE if the offsets/lengths don t fit in the allocated memory or range
• ESP_ERR_INVALID_STATE if a block in the selected ram offset/length is already mapped, or if
a block in the selected range offset/length already has a mapping.
Parameters
• handle: Handle to the block of memory, as given by esp_himem_alloc
• range: Range handle to map the memory in
• ram_offset: Offset into the block of physical memory of the block to map
• range_offset: Offset into the address range where the block will be mapped
• len: Length of region to map
• flags: One of ESP_HIMEM_MAPFLAG_*
• [out] out_ptr: Pointer to variable to store resulting memory pointer in
esp_err_t esp_himem_free(esp_himem_handle_t handle)
Free a block of physical memory.
This clears out the associated handle making the memory available for re-allocation again. This will only
succeed if none of the memory blocks currently have a mapping.
Return - ESP_OK if the memory is succesfully freed
• ESP_ERR_INVALID_ARG if the handle still is (partially) mapped
Parameters
• handle: Handle to the block of memory, as given by esp_himem_alloc
esp_err_t esp_himem_free_map_range(esp_himem_rangehandle_t handle)
Free a mapping range.
This clears out the associated handle making the range available for re-allocation again. This will only succeed
if none of the range blocks currently are used for a mapping.
Return - ESP_OK if the memory is succesfully freed
• ESP_ERR_INVALID_ARG if the handle still is (partially) mapped to
Parameters
• handle: Handle to the range block, as given by esp_himem_alloc_map_range
esp_err_t esp_himem_unmap(esp_himem_rangehandle_t range, void *ptr, size_t len)
Unmap a region.
Return - ESP_OK if the memory is succesfully unmapped,
• ESP_ERR_INVALID_ARG if ptr or len are invalid.
Parameters
• range: Range handle
• ptr: Pointer returned by esp_himem_map
• len: Length of the block to be unmapped. Must be aligned to the SPI RAM MMU blocksize (32K)
size_t esp_himem_get_phys_size(void)
Get total amount of memory under control of himem API.
Return Amount of memory, in bytes
size_t esp_himem_get_free_size(void)
Get free amount of memory under control of himem API.
Return Amount of free memory, in bytes
size_t esp_himem_reserved_area_size(void)
Get amount of SPI memory address space needed for bankswitching.

Note This is also weakly defined in esp32/spiram.c and returns 0 there, so if no other function in this file is
used, no memory is reserved.
Return Amount of reserved area, in bytes
Macros
ESP_HIMEM_BLKSZ
ESP_HIMEM_MAPFLAG_RO
Indicates that a mapping will only be read from. Note that this is unused for now.
Type Definitions
typedef struct esp_himem_ramdata_t *esp_himem_handle_t
typedef struct esp_himem_rangedata_t *esp_himem_rangehandle_t
2.7.15 Inter-Processor Call
Note: The IPC is an Inter-Processor Call and NOT Inter-Process Communication as found on other operating
systems.
Overview
Due to the dual core nature of the ESP32, there are instances where a certain callback must be run in the context of
a particular CPU such as:
• When allocating an ISR to an interrupt source of a particular CPU (applies to freeing a particular CPU s
interrupt source as well).
• On particular chips (such as the ESP32), accessing memory that is exclusive to a particular CPU (such as RTC
Fast Memory).
• Reading the registers/state of another CPU.
The IPC (Inter-Processor Call) feature allows a particular CPU (the calling CPU) to trigger the execution of a callback
function on another CPU (the target CPU). The IPC feature allows execution of a callback function on the target CPU
in either a task context, or a High Priority Interrupt context (see High-Level Interrupts for more details). Depending on
the context that the callback function is executed in, different restrictions apply to the implementation of the callback
function.
IPC in Task Context
The IPC feature implements callback execution in a task context by creating an IPC task for each CPU during
application startup. When the calling CPU needs to execute a callback on the target CPU, the callback will execute
in the context of the target CPU s IPC task.
When using IPCs in a task context, users need to consider the following:
• IPC callbacks should ideally be simple and short. An IPC callback should avoid attempting to block or
yield.
• The IPC tasks are created at the highest possible priority (i.e., configMAX_PRIORITIES - 1) thus the
callback should also run at that priority as a result. However, CONFIG_ESP_IPC_USES_CALLERS_PRIORITY
is enabled by default which will temporarily lower the priority of the target CPU s IPC task to the calling
CPU before executing the callback.
• Depending on the complexity of the callback, users may need to configure the stack size of the IPC task via
CONFIG_ESP_IPC_TASK_STACK_SIZE.
• The IPC feature is internally protected by a mutex. Therefore, simultaneous IPC calls from two or more calling
CPUs will be handled on a first come first serve basis.

API Usage Task Context IPC callbacks have the following restrictions:
• The callback must be of type void func(void *arg)
• The callback should avoid attempting to block or yield as this will result in the target CPU s IPC task blocking
or yielding.
• The callback must avoid changing any aspect of the IPC task (e.g., by calling vTaskPrioritySet(NULL,
x)).
The IPC feature offers the API listed below to execute a callback in a task context on a target CPU. The API allows
the calling CPU to block until the callback s execution has completed, or return immediately once the callback s
execution has started.
• esp_ipc_call() will trigger an IPC call on the target CPU. This function will block until the target CPU
s IPC task begins execution of the callback.
• esp_ipc_call_blocking() will trigger an IPC on the target CPU. This function will block until the
target CPU s IPC task completes execution of the callback.
IPC in ISR Context
In some cases, we need to quickly obtain the state of another CPU such as in a core dump, GDB stub, various
unit tests, and DPORT workaround. For such scenarios, the IPC feature supports execution of callbacks in a High
Priority Interrupt context. The IPC feature implements the High Priority Interrupt context by reserving a High Priority
Interrupt on each CPU for IPC usage. When a calling CPU needs to execute a callback on the target CPU, the callback
will execute in the context of the High Priority Interrupt of the target CPU.
When using IPCs in High Priority Interrupt context, users need to consider the following:
• Since the callback is executed in a High Priority Interrupt context, the callback must be written entirely in
assembly. See the API Usage below for more details regarding writing assembly callbacks.
• The priority of the reserved High Priority Interrupt is dependent on the CON-
FIG_ESP_SYSTEM_CHECK_INT_LEVEL option
• When the callback executes:
– The calling CPU will disable interrupts of level 3 and lower
– Although the priority of the reserved interrupt depends on CON-
FIG_ESP_SYSTEM_CHECK_INT_LEVEL, during the execution IPC ISR callback, the
target CPU will disable interrupts of level 5 and lower regardless of what CON-
FIG_ESP_SYSTEM_CHECK_INT_LEVEL is set to.
API Usage High Priority Interrupt IPC callbacks have the following restrictions:
• The callback must be of type void func(void *arg) but implemented entirely in assembly
• The callback is invoked via the CALLX0 instruction with register windowing disabled, thus the callback:
– Must not call any register window related instructions (e.g., entry and retw).
– Must not call other C functions as register windowing is disabled
• The callback should be placed in IRAM at a 4-byte aligned address
• (On invocation of/after returning from) the callback, the registers a2, a3, a4 are (saved/restored) automatically thu
– a2 will contain the void *arg of the callback

– a3/a4 are free to use as scratch registers
The IPC feature offers the API listed below to execute a callback in a High Priority Interrupt context.
• esp_ipc_isr_asm_call() will trigger an IPC call on the target CPU. This function will busy-wait until
the target CPU begins execution of the callback.
• esp_ipc_isr_asm_call_blocking() will trigger an IPC call on the target CPU. This function will
busy-wait until the target CPU completes execution of the callback.
The following code-blocks demonstrates a High Priority Interrupt IPC callback written in assembly that simply reads
the target CPU s cycle count.

/* esp_test_ipc_isr_get_cycle_count_other_cpu(void *arg) */
// this function reads CCOUNT of the target CPU and stores it in arg.
// use only a2, a3 and a4 regs here.
.section .iram1, "ax"
.align 4
.global esp_test_ipc_isr_get_cycle_count_other_cpu
.type esp_test_ipc_isr_get_cycle_count_other_cpu, @function
// Args:
// a2 - void* arg
esp_test_ipc_isr_get_cycle_count_other_cpu:
rsr.ccount a3
s32i a3, a2, 0
ret
unit32_t cycle_count;
esp_ipc_isr_asm_call_blocking(esp_test_ipc_isr_get_cycle_count_other_cpu, (void␣
,→*)cycle_count);
Note: The number of scratch registers available for use is sufficient for most simple use cases. But if your callback
requires more scratch registers, void *arg can point to a buffer that is used as a register save area. The callback
can then save and restore more registers. See the system/ipc/ipc_isr.
Note: For more examples of High Priority Interrupt IPC callbacks, see compo-
nents/esp_system/port/arch/xtensa/esp_ipc_isr_routines.S and :components/esp_system/test/test_ipc_isr.S
The High Priority Interrupt IPC API also provides the following convenience functions that can stall/resume the target
CPU. These API utilize the High Priority Interrupt IPC, but supply their own internal callbacks:
• esp_ipc_isr_stall_other_cpu() stalls the target CPU. The calling CPU disables interrupts of level
3 and lower while the target CPU will busy-wait with interrupts of level 5 and lower disabled. The target CPU
will busy-wait until esp_ipc_isr_release_other_cpu() is called.
• esp_ipc_isr_release_other_cpu() resumes the target CPU.
API Reference
Header File
• components/esp_system/include/esp_ipc.h
Functions
esp_err_t esp_ipc_call(uint32_t cpu_id, esp_ipc_func_t func, void *arg)
Execute a callback on a given CPU.
Execute a given callback on a particular CPU. The callback must be of type esp_ipc_func_t and will be
invoked in the context of the target CPU s IPC task.
• This function will block the target CPU s IPC task has begun execution of the callback
• If another IPC call is ongoing, this function will block until the ongoing IPC call completes
• The stack size of the IPC task can be configured via the CONFIG_ESP_IPC_TASK_STACK_SIZE
option
Note In single-core mode, returns ESP_ERR_INVALID_ARG for cpu_id 1.
Return
• ESP_ERR_INVALID_ARG if cpu_id is invalid
• ESP_ERR_INVALID_STATE if the FreeRTOS scheduler is not running
Parameters

• [in] cpu_id: CPU where the given function should be executed (0 or 1)

• [in] func: Pointer to a function of type void func(void* arg) to be executed
• [in] arg: Arbitrary argument of type void* to be passed into the function
esp_err_t esp_ipc_call_blocking(uint32_t cpu_id, esp_ipc_func_t func, void *arg)
Execute a callback on a given CPU until and block until it completes.
This function is identical to esp_ipc_call() except that this function will block until the execution of the callback
completes.
Note In single-core mode, returns ESP_ERR_INVALID_ARG for cpu_id 1.
Return
• ESP_ERR_INVALID_ARG if cpu_id is invalid
• ESP_ERR_INVALID_STATE if the FreeRTOS scheduler is not running
Parameters
• [in] cpu_id: CPU where the given function should be executed (0 or 1)
Type Definitions
typedef void (*esp_ipc_func_t)(void *arg)
IPC Callback.
A callback of this type should be provided as an argument when calling esp_ipc_call() or
esp_ipc_call_blocking().
Header File
• components/esp_system/include/esp_ipc_isr.h
Functions
void esp_ipc_isr_init(void)
Initialize the IPC ISR feature.
This function initializes the IPC ISR feature and must be called before any other esp_ipc_isr () functions.
The IPC ISR feature allows for callbacks (written in assembly) to be run on a particular CPU in the context of
a High Priority Interrupt.
• This function will register a High Priority Interrupt on each CPU. The priority of the interrupts is depen-
dent on the CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL option.
• Callbacks written in assembly can then run in context of the registered High Priority Interrupts
• Callbacks can be executed by calling esp_ipc_isr_asm_call() or esp_ipc_isr_asm_call_blocking()
void esp_ipc_isr_asm_call(esp_ipc_isr_func_t func, void *arg)
Execute an assembly callback on the other CPU.
Execute a given callback on the other CPU in the context of a High Priority Interrupt.
• This function will busy-wait in a critical section until the other CPU has started execution of the callback
• The callback must be written in assembly, is invoked using a CALLX0 instruction, and has a2, a3, a4 as
scratch registers. See docs for more details
Note This function is not available in single-core mode.
Parameters
void esp_ipc_isr_asm_call_blocking(esp_ipc_isr_func_t func, void *arg)
Execute an assembly callback on the other CPU and busy-wait until it completes.
This function is identical to esp_ipc_isr_asm_call() except that this function will busy-wait until the execution
of the callback completes.


Parameters
void esp_ipc_isr_stall_other_cpu(void)
Stall the other CPU.
This function will stall the other CPU. The other CPU is stalled by busy-waiting in the context of a High
Priority Interrupt. The other CPU will not be resumed until esp_ipc_isr_release_other_cpu() is called.
• This function is internally implemented using IPC ISR
• This function is used for DPORT workaround.
• If the stall feature is paused using esp_ipc_isr_stall_pause(), this function will have no effect
void esp_ipc_isr_release_other_cpu(void)
Release the other CPU.
This function will release the other CPU that was previously stalled from calling esp_ipc_isr_stall_other_cpu()
• This function is used for DPORT workaround.
• If the stall feature is paused using esp_ipc_isr_stall_pause(), this function will have no effect
void esp_ipc_isr_stall_pause(void)
Puase the CPU stall feature.
This function will pause the CPU stall feature. Once paused, calls to esp_ipc_isr_stall_other_cpu() and
esp_ipc_isr_release_other_cpu() will have no effect. If a IPC ISR call is already in progress, this function
will busy-wait until the call completes before pausing the CPU stall feature.
void esp_ipc_isr_stall_abort(void)
Abort a CPU stall.
This function will abort any stalling routine of the other CPU due to a pervious call to
esp_ipc_isr_stall_other_cpu(). This function aborts the stall in a non-recoverable manner, thus should
only be called in case of a panic().
• This function is used in panic handling code
void esp_ipc_isr_stall_resume(void)
Resume the CPU stall feature.
This function will resume the CPU stall feature that was previously paused by calling esp_ipc_isr_stall_pause().
Once resumed, calls to esp_ipc_isr_stall_other_cpu() and esp_ipc_isr_release_other_cpu() will have effect
again.
Type Definitions
typedef void (*esp_ipc_isr_func_t)(void *arg)
IPC ISR Callback.
A callback of this type should be provided as an argument when calling esp_ipc_isr_asm_call() or
esp_ipc_isr_asm_call_blocking().
2.7.16 Call function with external stack
Overview
A given function can be executed with a user allocated stack space which is independent of current task stack, this
mechanism can be used to save stack space wasted by tasks which call a common function with intensive stack usage

such as printf. The given function can be called inside the shared stack space which is a callback function deferred
by calling esp_execute_shared_stack_function(), passing that function as parameter
Usage
esp_execute_shared_stack_function() takes four arguments, a mutex object allocated by the caller,

which is used to protect if the same function shares its allocated stack, a pointer to the top of stack used to that
fuction, the size in bytes of stack and, a pointer to a user function where the shared stack space will reside, after
calling the function, the user defined function will be deferred as a callback where functions can be called using the
user allocated space without taking space from current task stack.
The usage may looks like the code below:
void external_stack_function(void)
{
printf("Executing this printf from external stack! \n");
}
//Let's suppose we wanting to call printf using a separated stack space

//allowing app to reduce its stack size.
void app_main()
{
//Allocate a stack buffer, from heap or as a static form:
portSTACK_TYPE *shared_stack = malloc(8192 * sizeof(portSTACK_TYPE));
assert(shared_stack != NULL);
//Allocate a mutex to protect its usage:

SemaphoreHandle_t printf_lock = xSemaphoreCreateMutex();
assert(printf_lock != NULL);
//Call the desired function using the macro helper:

esp_execute_shared_stack_function(printf_lock,
shared_stack,
8192,
external_stack_function);
vSemaphoreDelete(printf_lock);
free(shared_stack);
}
API Reference
Header File
• components/esp_system/include/esp_expression_with_stack.h
Functions
void esp_execute_shared_stack_function(SemaphoreHandle_t lock, void *stack, size_t
stack_size, shared_stack_function function)
Calls user defined shared stack space function.
Note if either lock, stack or stack size is invalid, the expression will be called using the current stack.
Parameters
• lock: Mutex object to protect in case of shared stack
• stack: Pointer to user alocated stack
• stack_size: Size of current stack in bytes
• function: pointer to the shared stack function to be executed

Macros
ESP_EXECUTE_EXPRESSION_WITH_STACK(lock, stack, stack_size, expression)
Type Definitions
typedef void (*shared_stack_function)(void)
2.7.17 Interrupt allocation
Overview
The ESP32 has two cores, with 32 interrupts each. Each interrupt has a certain priority level, most (but not all)
interrupts are connected to the interrupt mux.
Because there are more interrupt sources than interrupts, sometimes it makes sense to share an interrupt in multiple
drivers. The esp_intr_alloc() abstraction exists to hide all these implementation details.
A driver can allocate an interrupt for a certain peripheral by calling esp_intr_alloc() (or
esp_intr_alloc_intrstatus()). It can use the flags passed to this function to set the type of inter-
rupt allocated, specifying a specific level or trigger method. The interrupt allocation code will then find an applicable
interrupt, use the interrupt mux to hook it up to the peripheral, and install the given interrupt handler and ISR to it.
This code has two different types of interrupts it handles differently: Shared interrupts and non-shared interrupts.
The simplest of the two are non-shared interrupts: a separate interrupt is allocated per esp_intr_alloc call and this
interrupt is solely used for the peripheral attached to it, with only one ISR that will get called. Shared interrupts can
have multiple peripherals triggering it, with multiple ISRs being called when one of the peripherals attached signals
an interrupt. Thus, ISRs that are intended for shared interrupts should check the interrupt status of the peripheral
they service in order to see if any action is required.
Non-shared interrupts can be either level- or edge-triggered. Shared interrupts can only be level interrupts (because
of the chance of missed interrupts when edge interrupts are used.) (The logic behind this: DevA and DevB share an
int. DevB signals an int. Int line goes high. ISR handler calls code for DevA -> does nothing. ISR handler calls code
for DevB, but while doing that, DevA signals an int. ISR DevB is done, clears int for DevB, exits interrupt code.
Now an interrupt for DevA is still pending, but because the int line never went low (DevA kept it high even when the
int for DevB was cleared) the interrupt is never serviced.)
Multicore issues
Peripherals that can generate interrupts can be divided in two types:

• External peripherals, within the ESP32 but outside the Xtensa cores themselves. Most ESP32 peripherals are
of this type.
• Internal peripherals, part of the Xtensa CPU cores themselves.
Interrupt handling differs slightly between these two types of peripherals.
Internal peripheral interrupts Each Xtensa CPU core has its own set of six internal peripherals:
• Three timer comparators
• A performance monitor
• Two software interrupts.
Internal interrupt sources are defined in esp_intr_alloc.h as ETS_INTERNAL_*_INTR_SOURCE.
These peripherals can only be configured from the core they are associated with. When generating an interrupt,
the interrupt they generate is hard-wired to their associated core; it s not possible to have e.g. an internal timer
comparator of one core generate an interrupt on another core. That is why these sources can only be managed using
a task running on that specific core. Internal interrupt sources are still allocatable using esp_intr_alloc as normal, but
they cannot be shared and will always have a fixed interrupt level (namely, the one associated in hardware with the
peripheral).

External Peripheral Interrupts The remaining interrupt sources are from external peripherals. These are defined
in soc/soc.h as ETS_*_INTR_SOURCE.
Non-internal interrupt slots in both CPU cores are wired to an interrupt multiplexer, which can be used to route any
external interrupt source to any of these interrupt slots.
• Allocating an external interrupt will always allocate it on the core that does the allocation.
• Freeing an external interrupt must always happen on the same core it was allocated on.
• Disabling and enabling external interrupts from another core is allowed.
• Multiple external interrupt sources can share an interrupt slot by passing ESP_INTR_FLAG_SHARED as a
flag to esp_intr_alloc().
Care should be taken when calling esp_intr_alloc() from a task which is not pinned to a core. During task switching,
these tasks can migrate between cores. Therefore it is impossible to tell which CPU the interrupt is allocated on,
which makes it difficult to free the interrupt handle and may also cause debugging difficulties. It is advised to use
xTaskCreatePinnedToCore() with a specific CoreID argument to create tasks that will allocate interrupts. In the case
of internal interrupt sources, this is required.
IRAM-Safe Interrupt Handlers
The ESP_INTR_FLAG_IRAM flag registers an interrupt handler that always runs from IRAM (and reads all its data
from DRAM), and therefore does not need to be disabled during flash erase and write operations.
This is useful for interrupts which need a guaranteed minimum execution latency, as flash write and erase operations
can be slow (erases can take tens or hundreds of milliseconds to complete).
It can also be useful to keep an interrupt handler in IRAM if it is called very frequently, to avoid flash cache misses.
Refer to the SPI flash API documentation for more details.
Multiple Handlers Sharing A Source
Several handlers can be assigned to a same source, given that all handlers are allocated using the
ESP_INTR_FLAG_SHARED flag. They ll be all allocated to the interrupt, which the source is attached to, and
called sequentially when the source is active. The handlers can be disabled and freed individually. The source is
attached to the interrupt (enabled), if one or more handlers are enabled, otherwise detached. A handler will never be
called when disabled, while its source may still be triggered if any one of its handler enabled.
Sources attached to non-shared interrupt do not support this feature.
Though the framework support this feature, you have to use it very carefully. There usually exist 2 ways to stop a
interrupt from being triggered: disable the source or mask peripheral interrupt status. IDF only handles the enabling
and disabling of the source itself, leaving status and mask bits to be handled by users. Status bits should always
be masked before the handler responsible for it is disabled, or the status should be handled in other enabled
interrupt properly. You may leave some status bits unhandled if you just disable one of all the handlers without
masking the status bits, which causes the interrupt to trigger infinitely resulting in a system crash.
API Reference
Header File
• components/esp_hw_support/include/esp_intr_alloc.h
Functions
esp_err_t esp_intr_mark_shared(int intno, int cpu, bool is_in_iram)
Mark an interrupt as a shared interrupt.
This will mark a certain interrupt on the specified CPU as an interrupt that can be used to hook shared interrupt
handlers to.
Return ESP_ERR_INVALID_ARG if cpu or intno is invalid ESP_OK otherwise

Parameters
• intno: The number of the interrupt (0-31)
• cpu: CPU on which the interrupt should be marked as shared (0 or 1)
• is_in_iram: Shared interrupt is for handlers that reside in IRAM and the int can be left enabled
while the flash cache is disabled.
esp_err_t esp_intr_reserve(int intno, int cpu)
Reserve an interrupt to be used outside of this framework.
This will mark a certain interrupt on the specified CPU as reserved, not to be allocated for any reason.
Return ESP_ERR_INVALID_ARG if cpu or intno is invalid ESP_OK otherwise
Parameters
• intno: The number of the interrupt (0-31)
• cpu: CPU on which the interrupt should be marked as shared (0 or 1)
esp_err_t esp_intr_alloc(int source, int flags, intr_handler_t handler, void *arg, intr_handle_t
*ret_handle)
Allocate an interrupt with the given parameters.
This finds an interrupt that matches the restrictions as given in the flags parameter, maps the given interrupt
source to it and hooks up the given interrupt handler (with optional argument) as well. If needed, it can return
a handle for the interrupt as well.
The interrupt will always be allocated on the core that runs this function.
If ESP_INTR_FLAG_IRAM flag is used, and handler address is not in IRAM or RTC_FAST_MEM, then
ESP_ERR_INVALID_ARG is returned.
Return ESP_ERR_INVALID_ARG if the combination of arguments is invalid. ESP_ERR_NOT_FOUND
No free interrupt found with the specified flags ESP_OK otherwise
Parameters
• source: The interrupt source. One of the ETS_*_INTR_SOURCE interrupt mux sources, as
defined in soc/soc.h, or one of the internal ETS_INTERNAL_*_INTR_SOURCE sources as defined
in this header.
• flags: An ORred mask of the ESP_INTR_FLAG_* defines. These restrict the choice of inter-
rupts that this routine can choose from. If this value is 0, it will default to allocating a non-shared
interrupt of level 1, 2 or 3. If this is ESP_INTR_FLAG_SHARED, it will allocate a shared inter-
rupt of level 1. Setting ESP_INTR_FLAG_INTRDISABLED will return from this function with
the interrupt disabled.
• handler: The interrupt handler. Must be NULL when an interrupt of level >3 is requested,
because these types of interrupts aren t C-callable.
• arg: Optional argument for passed to the interrupt handler
• ret_handle: Pointer to an intr_handle_t to store a handle that can later be used to request details
or free the interrupt. Can be NULL if no handle is required.
esp_err_t esp_intr_alloc_intrstatus(int source, int flags, uint32_t intrstatusreg, uint32_t intrsta-
tusmask, intr_handler_t handler, void *arg, intr_handle_t
*ret_handle)
Allocate an interrupt with the given parameters.
This essentially does the same as esp_intr_alloc, but allows specifying a register and mask combo. For shared
interrupts, the handler is only called if a read from the specified register, ANDed with the mask, returns non-
zero. By passing an interrupt status register address and a fitting mask, this can be used to accelerate interrupt
handling in the case a shared interrupt is triggered; by checking the interrupt statuses first, the code can decide
which ISRs can be skipped
Return ESP_ERR_INVALID_ARG if the combination of arguments is invalid. ESP_ERR_NOT_FOUND
No free interrupt found with the specified flags ESP_OK otherwise
Parameters
• source: The interrupt source. One of the ETS_*_INTR_SOURCE interrupt mux sources, as
defined in soc/soc.h, or one of the internal ETS_INTERNAL_*_INTR_SOURCE sources as defined
in this header.
• flags: An ORred mask of the ESP_INTR_FLAG_* defines. These restrict the choice of inter-
rupts that this routine can choose from. If this value is 0, it will default to allocating a non-shared

interrupt of level 1, 2 or 3. If this is ESP_INTR_FLAG_SHARED, it will allocate a shared inter-

rupt of level 1. Setting ESP_INTR_FLAG_INTRDISABLED will return from this function with
the interrupt disabled.
• intrstatusreg: The address of an interrupt status register
• intrstatusmask: A mask. If a read of address intrstatusreg has any of the bits that are 1 in the
mask set, the ISR will be called. If not, it will be skipped.
• handler: The interrupt handler. Must be NULL when an interrupt of level >3 is requested,
because these types of interrupts aren t C-callable.
• arg: Optional argument for passed to the interrupt handler
• ret_handle: Pointer to an intr_handle_t to store a handle that can later be used to request details
or free the interrupt. Can be NULL if no handle is required.
esp_err_t esp_intr_free(intr_handle_t handle)
Disable and free an interrupt.
Use an interrupt handle to disable the interrupt and release the resources associated with it. If the current core
is not the core that registered this interrupt, this routine will be assigned to the core that allocated this interrupt,
blocking and waiting until the resource is successfully released.
Note When the handler shares its source with other handlers, the interrupt status bits it s responsible for
should be managed properly before freeing it. see esp_intr_disable for more details. Please do
not call this function in esp_ipc_call_blocking.
Return ESP_ERR_INVALID_ARG the handle is NULL ESP_FAIL failed to release this handle ESP_OK
otherwise
Parameters
• handle: The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
int esp_intr_get_cpu(intr_handle_t handle)
Get CPU number an interrupt is tied to.
Return The core number where the interrupt is allocated
Parameters
int esp_intr_get_intno(intr_handle_t handle)
Get the allocated interrupt for a certain handle.
Return The interrupt number
Parameters
esp_err_t esp_intr_disable(intr_handle_t handle)
Disable the interrupt associated with the handle.
Note
1. For local interrupts (ESP_INTERNAL_* sources), this function has to be called on the CPU the
interrupt is allocated on. Other interrupts have no such restriction.
2. When several handlers sharing a same interrupt source, interrupt status bits, which are handled in the
handler to be disabled, should be masked before the disabling, or handled in other enabled interrupts
properly. Miss of interrupt status handling will cause infinite interrupt calls and finally system crash.
Return ESP_ERR_INVALID_ARG if the combination of arguments is invalid. ESP_OK otherwise
Parameters
esp_err_t esp_intr_enable(intr_handle_t handle)
Enable the interrupt associated with the handle.
Note For local interrupts (ESP_INTERNAL_* sources), this function has to be called on the CPU the inter-
rupt is allocated on. Other interrupts have no such restriction.
Parameters

esp_err_t esp_intr_set_in_iram(intr_handle_t handle, bool is_in_iram)

Set the in IRAM status of the handler.
Note Does not work on shared interrupts.
Parameters
• is_in_iram: Whether the handler associated with this handle resides in IRAM. Handlers residing
in IRAM can be called when cache is disabled.
void esp_intr_noniram_disable(void)
Disable interrupts that aren t specifically marked as running from IRAM.
void esp_intr_noniram_enable(void)
Re-enable interrupts disabled by esp_intr_noniram_disable.
void esp_intr_enable_source(int inum)
enable the interrupt source based on its number
Parameters
• inum: interrupt number from 0 to 31
void esp_intr_disable_source(int inum)
disable the interrupt source based on its number
Parameters
• inum: interrupt number from 0 to 31
static int esp_intr_flags_to_level(int flags)
Get the lowest interrupt level from the flags.
Parameters
• flags: The same flags that pass to esp_intr_alloc_intrstatus API
Macros
ESP_INTR_FLAG_LEVEL1
Interrupt allocation flags.
These flags can be used to specify which interrupt qualities the code calling esp_intr_alloc* needs.Accept a
Level 1 interrupt vector (lowest priority)
Accept a Level 2 interrupt vector.
ESP_INTR_FLAG_NMI
Accept a Level 7 interrupt vector (highest priority)
ESP_INTR_FLAG_SHARED
Interrupt can be shared between ISRs.
ESP_INTR_FLAG_EDGE
Edge-triggered interrupt.
ESP_INTR_FLAG_IRAM
ISR can be called if cache is disabled.

ESP_INTR_FLAG_INTRDISABLED
Return with this interrupt disabled.
ESP_INTR_FLAG_LOWMED
Low and medium prio interrupts. These can be handled in C.
ESP_INTR_FLAG_HIGH
High level interrupts. Need to be handled in assembly.
ESP_INTR_FLAG_LEVELMASK
Mask for all level flags.
ETS_INTERNAL_TIMER0_INTR_SOURCE
Platform timer 0 interrupt source.
The esp_intr_alloc* functions can allocate an int for all ETS_*_INTR_SOURCE interrupt sources that are
routed through the interrupt mux. Apart from these sources, each core also has some internal sources that do
not pass through the interrupt mux. To allocate an interrupt for these sources, pass these pseudo-sources to the
functions.
ETS_INTERNAL_SW0_INTR_SOURCE
Software int source 1.
ETS_INTERNAL_SW1_INTR_SOURCE
Software int source 2.
ETS_INTERNAL_PROFILING_INTR_SOURCE
Int source for profiling.
ETS_INTERNAL_INTR_SOURCE_OFF
Provides SystemView with positive IRQ IDs, otherwise scheduler events are not shown properly
ESP_INTR_ENABLE(inum)
Enable interrupt by interrupt number
ESP_INTR_DISABLE(inum)
Disable interrupt by interrupt number
Type Definitions
typedef void (*intr_handler_t)(void *arg)
Function prototype for interrupt handler function
typedef struct intr_handle_data_t intr_handle_data_t
Interrupt handler associated data structure
typedef intr_handle_data_t *intr_handle_t
Handle to an interrupt handler
2.7.18 Logging library
Overview
The logging library provides two ways for setting log verbosity:
• At compile time: in menuconfig, set the verbosity level using the option CONFIG_LOG_DEFAULT_LEVEL.
• Optionally, also in menuconfig, set the maximum verbosity level using the option CON-
FIG_LOG_MAXIMUM_LEVEL. By default this is the same as the default level, but it can be set higher
in order to compile more optional logs into the firmware.

• At runtime: all logs for verbosity levels lower than CONFIG_LOG_DEFAULT_LEVEL are enabled by default.
The function esp_log_level_set() can be used to set a logging level on a per module basis. Modules
are identified by their tags, which are human-readable ASCII zero-terminated strings.
There are the following verbosity levels:
• Error (lowest)
• Warning
• Info
• Debug
• Verbose (highest)
Note: The function esp_log_level_set() cannot set logging levels higher than specified by CON-
FIG_LOG_MAXIMUM_LEVEL. To increase log level for a specific file above this maximum at compile time, use
the macro LOG_LOCAL_LEVEL (see the details below).
How to use this library
In each C file that uses logging functionality, define the TAG variable as shown below:
static const char* TAG = "MyModule";
Then use one of logging macros to produce output, e.g:
ESP_LOGW(TAG, "Baud rate error %.1f%%. Requested: %d baud, actual: %d baud", error␣
,→* 100, baud_req, baud_real);
Several macros are available for different verbosity levels:

• ESP_LOGE - error (lowest)
• ESP_LOGW - warning
• ESP_LOGI - info
• ESP_LOGD - debug
• ESP_LOGV - verbose (highest)
Additionally, there are ESP_EARLY_LOGx versions for each of these macros, e.g. ESP_EARLY_LOGE. These
versions have to be used explicitly in the early startup code only, before heap allocator and syscalls have been ini-
tialized. Normal ESP_LOGx macros can also be used while compiling the bootloader, but they will fall back to the
same implementation as ESP_EARLY_LOGx macros.
There are also ESP_DRAM_LOGx versions for each of these macros, e.g. ESP_DRAM_LOGE. These versions are
used in some places where logging may occur with interrupts disabled or with flash cache inaccessible. Use of this
macros should be as sparing as possible, as logging in these types of code should be avoided for performance reasons.
Note: Inside critical sections interrupts are disabled so it s only possible to use ESP_DRAM_LOGx (preferred)
or ESP_EARLY_LOGx. Even though it s possible to log in these situations, it s better if your program can be
structured not to require it.
To override default verbosity level at file or component scope, define the LOG_LOCAL_LEVEL macro.
At file scope, define it before including esp_log.h, e.g.:
#define LOG_LOCAL_LEVEL ESP_LOG_VERBOSE

#include "esp_log.h"
At component scope, define it in the component makefile:
target_compile_definitions(${COMPONENT_LIB} PUBLIC "-DLOG_LOCAL_LEVEL=ESP_LOG_

,→VERBOSE")

To configure logging output per module at runtime, add calls to the function esp_log_level_set() as follows:
esp_log_level_set("*", ESP_LOG_ERROR); // set all components to ERROR level

esp_log_level_set("wifi", ESP_LOG_WARN); // enable WARN logs from WiFi stack
esp_log_level_set("dhcpc", ESP_LOG_INFO); // enable INFO logs from DHCP client
Note: The DRAM and EARLY log macro variants documented above do not support per module setting of
log verbosity. These macros will always log at the default verbosity level, which can only be changed at runtime
by calling esp_log_level("*", level).
Logging to Host via JTAG By default, the logging library uses the vprintf-like function to write formatted output
to the dedicated UART. By calling a simple API, all log output may be routed to JTAG instead, making logging
several times faster. For details, please refer to Section Logging to Host.
Application Example
The logging library is commonly used by most esp-idf components and examples. For demonstration of log function-
ality, check ESP-IDF s examples directory. The most revelant examples that deal with logging are the following:
• system/ota
• storage/sd_card
• protocols/https_request
API Reference
Header File
• components/log/include/esp_log.h
Functions
void esp_log_level_set(const char *tag, esp_log_level_t level)
Set log level for given tag.
If logging for given component has already been enabled, changes previous setting.
Note that this function can not raise log level above the level set using CONFIG_LOG_MAXIMUM_LEVEL
setting in menuconfig.
To raise log level above the default one for a given file, define LOG_LOCAL_LEVEL to one of the
ESP_LOG_* values, before including esp_log.h in this file.
Parameters
• tag: Tag of the log entries to enable. Must be a non-NULL zero terminated string. Value *
resets log level for all tags to the given value.
• level: Selects log level to enable. Only logs at this and lower verbosity levels will be shown.
esp_log_level_t esp_log_level_get(const char *tag)
Get log level for given tag, can be used to avoid expensive log statements.
Return The current log level for the given tag
Parameters
• tag: Tag of the log to query current level. Must be a non-NULL zero terminated string.
vprintf_like_t esp_log_set_vprintf(vprintf_like_t func)
Set function used to output log entries.
By default, log output goes to UART0. This function can be used to redirect log output to some other destina-
tion, such as file or network. Returns the original log handler, which may be necessary to return output to the
previous destination.

Note Please note that function callback here must be re-entrant as it can be invoked in parallel from multiple
thread context.
Return func old Function used for output.
Parameters
• func: new Function used for output. Must have same signature as vprintf.
uint32_t esp_log_timestamp(void)
Function which returns timestamp to be used in log output.
This function is used in expansion of ESP_LOGx macros. In the 2nd stage bootloader, and at early application
startup stage this function uses CPU cycle counter as time source. Later when FreeRTOS scheduler start
running, it switches to FreeRTOS tick count.
For now, we ignore millisecond counter overflow.
Return timestamp, in milliseconds
char *esp_log_system_timestamp(void)
Function which returns system timestamp to be used in log output.
This function is used in expansion of ESP_LOGx macros to print the system time as HH:MM:SS.sss . The
system time is initialized to 0 on startup, this can be set to the correct time with an SNTP sync, or manually
with standard POSIX time functions.
Currently this will not get used in logging from binary blobs (i.e WiFi & Bluetooth libraries), these will still
print the RTOS tick time.
Return timestamp, in HH:MM:SS.sss
uint32_t esp_log_early_timestamp(void)
Function which returns timestamp to be used in log output.
This function uses HW cycle counter and does not depend on OS, so it can be safely used after application
crash.
Return timestamp, in milliseconds
void esp_log_write(esp_log_level_t level, const char *tag, const char *format, ...)
Write message into the log.
This function is not intended to be used directly. Instead, use one of ESP_LOGE, ESP_LOGW, ESP_LOGI,
ESP_LOGD, ESP_LOGV macros.
This function or these macros should not be used from an interrupt.
void esp_log_writev(esp_log_level_t level, const char *tag, const char *format, va_list args)
Write message into the log, va_list variant.
This function is provided to ease integration toward other logging framework, so that esp_log can be used as a
log sink.
See esp_log_write()
Macros
ESP_LOG_BUFFER_HEX_LEVEL(tag, buffer, buff_len, level)
Log a buffer of hex bytes at specified level, separated into 16 bytes each line.
Parameters
• tag: description tag
• buffer: Pointer to the buffer array
• buff_len: length of buffer in bytes
• level: level of the log
ESP_LOG_BUFFER_CHAR_LEVEL(tag, buffer, buff_len, level)
Log a buffer of characters at specified level, separated into 16 bytes each line. Buffer should contain only
printable characters.
Parameters


ESP_LOG_BUFFER_HEXDUMP(tag, buffer, buff_len, level)
Dump a buffer to the log at specified level.
The dump log shows just like the one below:
W (195) log_example: 0x3ffb4280 45 53 50 33 32 20 69 73 20 67 72 65 61 74␣

,→2c 20 |ESP32 is great, |
W (195) log_example: 0x3ffb4290 77 6f 72 6b 69 6e 67 20 61 6c 6f 6e 67 20␣
,→77 69 |working along wi|
W (205) log_example: 0x3ffb42a0 74 68 20 74 68 65 20 49 44 46 2e 00 ␣
,→ |th the IDF..|
It is highly recommend to use terminals with over 102 text width.

Parameters
ESP_LOG_BUFFER_HEX(tag, buffer, buff_len)
Log a buffer of hex bytes at Info level.
See esp_log_buffer_hex_level
Parameters
ESP_LOG_BUFFER_CHAR(tag, buffer, buff_len)
Log a buffer of characters at Info level. Buffer should contain only printable characters.
See esp_log_buffer_char_level
Parameters
portGET_ARGUMENT_COUNT_INNER(zero, one, count, ...)
macro to output logs in startup code, before heap allocator and syscalls have been initialized. log at
ESP_LOG_ERROR level.
See printf,ESP_LOGE,ESP_DRAM_LOGE
ESP_EARLY_LOGE(tag, format, ...)
In the future, we want to switch to C++20. We also want to become compatible with clang. Hence, we provide
two versions of the following macros which are using variadic arguments. The first one is using the GNU
extension ##__VA_ARGS__. The second one is using the C++20 feature VA_OPT(,). This allows users to
compile their code with standard C++20 enabled instead of the GNU extension. Below C++20, we haven t
found any good alternative to using ##__VA_ARGS__.
ESP_EARLY_LOGW(tag, format, ...)
macro to output logs in startup code at ESP_LOG_WARN level.
See ESP_EARLY_LOGE,ESP_LOGE, printf
ESP_EARLY_LOGI(tag, format, ...)
macro to output logs in startup code at ESP_LOG_INFO level.

ESP_EARLY_LOGD(tag, format, ...)

macro to output logs in startup code at ESP_LOG_DEBUG level.
ESP_EARLY_LOGV(tag, format, ...)
macro to output logs in startup code at ESP_LOG_VERBOSE level.
_ESP_LOG_EARLY_ENABLED(log_level)
ESP_LOG_EARLY_IMPL(tag, format, log_level, log_tag_letter, ...)
ESP_LOGE(tag, format, ...)
ESP_LOGW(tag, format, ...)
ESP_LOGI(tag, format, ...)
ESP_LOGD(tag, format, ...)
ESP_LOGV(tag, format, ...)
ESP_LOG_LEVEL(level, tag, format, ...)
runtime macro to output logs at a specified level.
See printf
Parameters
• tag: tag of the log, which can be used to change the log level by esp_log_level_set at
runtime.
• level: level of the output log.
• format: format of the output log. see printf
• ...: variables to be replaced into the log. see printf
ESP_LOG_LEVEL_LOCAL(level, tag, format, ...)
runtime macro to output logs at a specified level. Also check the level with LOG_LOCAL_LEVEL.
See printf, ESP_LOG_LEVEL
ESP_DRAM_LOGE(tag, format, ...)
Macro to output logs when the cache is disabled. log at ESP_LOG_ERROR level.
Similar to
Usage: ESP_DRAM_LOGE(DRAM_STR("my_tag"), "format", orESP_DRAM_LOGE(TAG,
format , )`, where TAG is a char* that points to a str in the DRAM.
Note Unlike normal logging macros, it s possible to use this macro when interrupts are disabled or inside an
ISR.
See ESP_EARLY_LOGE, the log level cannot be changed per-tag, however esp_log_level_set( * , level)
will set the default level which controls these log lines also.
Note Placing log strings in DRAM reduces available DRAM, so only use when absolutely essential.
See esp_rom_printf,ESP_LOGE
ESP_DRAM_LOGW(tag, format, ...)
macro to output logs when the cache is disabled at ESP_LOG_WARN level.
See ESP_DRAM_LOGW,ESP_LOGW, esp_rom_printf
ESP_DRAM_LOGI(tag, format, ...)
macro to output logs when the cache is disabled at ESP_LOG_INFO level.
See ESP_DRAM_LOGI,ESP_LOGI, esp_rom_printf
ESP_DRAM_LOGD(tag, format, ...)
macro to output logs when the cache is disabled at ESP_LOG_DEBUG level.
See ESP_DRAM_LOGD,ESP_LOGD, esp_rom_printf

ESP_DRAM_LOGV(tag, format, ...)

macro to output logs when the cache is disabled at ESP_LOG_VERBOSE level.
See ESP_DRAM_LOGV,ESP_LOGV, esp_rom_printf
Type Definitions
typedef int (*vprintf_like_t)(const char *, va_list)
Enumerations
enum esp_log_level_t
Log level.
Values:
ESP_LOG_NONE
No log output
ESP_LOG_ERROR
Critical errors, software module can not recover on its own
ESP_LOG_WARN
Error conditions from which recovery measures have been taken
ESP_LOG_INFO
Information messages which describe normal flow of events
ESP_LOG_DEBUG
Extra information which is not necessary for normal use (values, pointers, sizes, etc).
ESP_LOG_VERBOSE
Bigger chunks of debugging information, or frequent messages which can potentially flood the output.
2.7.19 Miscellaneous System APIs
Software reset
To perform software reset of the chip, esp_restart() function is provided. When the function is called, exe-
cution of the program will stop, both CPUs will be reset, application will be loaded by the bootloader and started
again.
Additionally, esp_register_shutdown_handler() function is provided to register a routine which needs
to be called prior to restart (when done by esp_restart()). This is similar to the functionality of atexit
POSIX function.
Reset reason
ESP-IDF application can be started or restarted due to a variety of reasons. To get the last reset reason, call
esp_reset_reason() function. See description of esp_reset_reason_t for the list of possible reset
reasons.
Heap memory
Two heap memory related functions are provided:

• esp_get_free_heap_size() returns the current size of free heap memory
• esp_get_minimum_free_heap_size() returns the minimum size of free heap memory that was
available during program execution.

Note that ESP-IDF supports multiple heaps with different capabilities. Functions mentioned in this section return the
size of heap memory which can be allocated using malloc family of functions. For further information about heap
memory see Heap Memory Allocation.
MAC Address
These APIs allow querying and customizing MAC addresses for different network interfaces that supported (e.g.
Wi-Fi, Bluetooth, Ethernet).
To fetch MAC address for a specific interface (e.g. Wi-Fi, Bluetooth, Ethernet), call the function
esp_read_mac() function.
In ESP-IDF these addresses are calculated from a single Base MAC address. By default, the Espressif base MAC
address is used. This MAC is pre-programmed into ESP32 eFuse from the factory.
Interface MAC address (4 universally administered, de- MAC address (2 universally adminis-
fault) tered)
Wi-Fi base_mac base_mac
Station
Wi-Fi base_mac, +1 to the last octet Local MAC derived from Wi-Fi Station
SoftAP MAC)
Bluetooth base_mac, +2 to the last octet base_mac, +1 to the last octet
Ethernet base_mac, +3 to the last octet Local MAC (derived from Bluetooth MAC)
Note: The default configuration is 4 universally administered MAC addresses, and this is recommended when using
Espressif-provided MAC addresses.
Custom Base MAC The default Base MAC is pre-programmed by Espressif in eFuse BLK0. To set a custom
Base MAC instead, call the function esp_base_mac_addr_set() before initializing any network interfaces
or calling the esp_read_mac() function. The customized MAC address can be stored in any supported storage
device (e.g. Flash, NVS, etc).
The custom base MAC addresses should be allocated such that derived MAC addresses will not overlap. Configure
the option CONFIG_ESP32_UNIVERSAL_MAC_ADDRESSES to set the number of valid universal MAC addresses
that can be derived from the custom base MAC, according to the table above.
Note: It is also possible to call the function esp_netif_set_mac() to set the specific MAC used by a network
interface, after network initialization. It s recommended to use the Base MAC approach documented here instead,
to avoid the possibility of the original MAC address briefly appearing on the network before it is changed.
Custom MAC address in eFuse When reading custom MAC addresses from eFuse, ESP-IDF provides a helper
function esp_efuse_mac_get_custom(). This loads the MAC address from eFuse BLK3. This function
assumes that the custom base MAC address is stored in the following format:
Field # of bits Range of bits Notes

Version 8 191:184 0: invalid, others valid
Reserved 128 183:56
MAC address 48 55:8
MAC address CRC 8 7:0 CRC-8-CCITT, polynomial 0x07
Note: If the 3/4 coding scheme is enabled, all eFuse fields in this block must be burnt at the same time.

Once MAC address has been obtained using esp_efuse_mac_get_custom(), call

esp_base_mac_addr_set() to set this MAC address as base MAC address.
Local vs Universal MAC addresses ESP32 comes pre-programmed with enough valid Espressif universally ad-
ministered MAC addresses for all internal interfaces. The specific calculations to derive an interface s MAC address
from the base MAC address is shown in the table above..
When using a custom MAC address scheme, it s possible that not all interfaces can be assigned a universally ad-
ministered MAC address. In these cases, a locally administered MAC address is assigned. Note that these addresses
are intended for use on a single local network, only.
See this article for the definition of local and universally administered MAC addresses.
Function esp_derive_local_mac() is called internally to derive a local MAC address from a universal MAC
address. The process is as follows:
1. The U/L bit (bit value 0x2) is set in the first octet of the universal MAC address, creating a local MAC address.
2. If this bit is already set in the supplied universal MAC address (meaning: the supplied universal MAC
address was in fact already a local MAC address), then the first octet of the local MAC address is XORed with
0x4.
Chip version
esp_chip_info() function fills esp_chip_info_t structure with information about the chip. This includes
the chip revision, number of CPU cores, and a bit mask of features enabled in the chip.
SDK version
esp_get_idf_version() returns a string describing the IDF version which was used to compile the application.
This is the same value as the one available through IDF_VER variable of the build system. The version string generally
has the format of git describe output.
To get the version at build time, additional version macros are provided. They can be used to enable or disable parts
of the program depending on IDF version.
• ESP_IDF_VERSION_MAJOR, ESP_IDF_VERSION_MINOR, ESP_IDF_VERSION_PATCH are de-
fined to integers representing major, minor, and patch version.
• ESP_IDF_VERSION_VAL and ESP_IDF_VERSION can be used when implementing version checks:
#include "esp_idf_version.h"
#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(4, 0, 0)

// enable functionality present in IDF v4.0
#endif
App version
Application version is stored in esp_app_desc_t structure. It is located in DROM sector and has a fixed
offset from the beginning of the binary file. The structure is located after esp_image_header_t and
esp_image_segment_header_t structures. The field version has string type and max length 32 chars.
To set version in your project manually you need to set PROJECT_VER variable in your project CMake-
Lists.txt/Makefile:
• In application CMakeLists.txt put set(PROJECT_VER "0.1.0.1") before including project.
cmake.
If CONFIG_APP_PROJECT_VER_FROM_CONFIG option is set, the value of CONFIG_APP_PROJECT_VER will
be used. Otherwise if PROJECT_VER variable is not set in the project then it will be retrieved from ei-
ther $(PROJECT_PATH)/version.txt file (if present) else using git command git describe. If

neither is available then PROJECT_VER will be set to 1 . Application can make use of this by calling
esp_ota_get_app_description() or esp_ota_get_partition_description() functions.
API Reference
Header File
• components/esp_system/include/esp_system.h
Functions
esp_err_t esp_register_shutdown_handler(shutdown_handler_t handle)
Register shutdown handler.
This function allows you to register a handler that gets invoked before the application is restarted using
esp_restart function.
Return
• ESP_ERR_INVALID_STATE if the handler has already been registered
• ESP_ERR_NO_MEM if no more shutdown handler slots are available
Parameters
• handle: function to execute on restart
esp_err_t esp_unregister_shutdown_handler(shutdown_handler_t handle)
Unregister shutdown handler.
This function allows you to unregister a handler which was previously registered using
esp_register_shutdown_handler function.
• ESP_ERR_INVALID_STATE if the given handler hasn t been registered before
void esp_restart(void)
Restart PRO and APP CPUs.
This function can be called both from PRO and APP CPUs. After successful restart, CPU reset reason will be
SW_CPU_RESET. Peripherals (except for WiFi, BT, UART0, SPI1, and legacy timers) are not reset. This
function does not return.
esp_reset_reason_t esp_reset_reason(void)
Get reason of last reset.
Return See description of esp_reset_reason_t for explanation of each value.
uint32_t esp_get_free_heap_size(void)
Get the size of available heap.
Note that the returned value may be larger than the maximum contiguous block which can be allocated.
Return Available heap size, in bytes.
uint32_t esp_get_free_internal_heap_size(void)
Get the size of available internal heap.
Note that the returned value may be larger than the maximum contiguous block which can be allocated.
Return Available internal heap size, in bytes.
uint32_t esp_get_minimum_free_heap_size(void)
Get the minimum heap that has ever been available.
Return Minimum free heap ever available
void esp_system_abort(const char *details)
Trigger a software abort.
Parameters

• details: Details that will be displayed during panic handling.
Type Definitions
typedef void (*shutdown_handler_t)(void)
Shutdown handler type
Enumerations
enum esp_reset_reason_t
Reset reasons.
Values:
ESP_RST_UNKNOWN
Reset reason can not be determined.
ESP_RST_POWERON
Reset due to power-on event.
ESP_RST_EXT
Reset by external pin (not applicable for ESP32)
ESP_RST_SW
Software reset via esp_restart.
ESP_RST_PANIC
Software reset due to exception/panic.
ESP_RST_INT_WDT
Reset (software or hardware) due to interrupt watchdog.
ESP_RST_TASK_WDT
Reset due to task watchdog.
ESP_RST_WDT
Reset due to other watchdogs.
ESP_RST_DEEPSLEEP
Reset after exiting deep sleep mode.
ESP_RST_BROWNOUT
Brownout reset (software or hardware)
ESP_RST_SDIO
Reset over SDIO.
Header File
• components/esp_common/include/esp_idf_version.h
Functions
const char *esp_get_idf_version(void)
Return full IDF version string, same as git describe output.
Note If you are printing the ESP-IDF version in a log file or other information, this function provides more
information than using the numerical version macros. For example, numerical version macros don t
differentiate between development, pre-release and release versions, but the output of this function does.
Return constant string from IDF_VER

Macros
ESP_IDF_VERSION_MAJOR
Major version number (X.x.x)
ESP_IDF_VERSION_MINOR
Minor version number (x.X.x)
ESP_IDF_VERSION_PATCH
Patch version number (x.x.X)
ESP_IDF_VERSION_VAL(major, minor, patch)
Macro to convert IDF version number into an integer
To be used in comparisons, such as ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(4, 0, 0)
ESP_IDF_VERSION
Current IDF version, as an integer
To be used in comparisons, such as ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(4, 0, 0)
2.7.20 Over The Air Updates (OTA)
OTA Process Overview
The OTA update mechanism allows a device to update itself based on data received while the normal firmware is
running (for example, over Wi-Fi or Bluetooth.)
OTA requires configuring the Partition Table of the device with at least two OTA app slot partitions (i.e. ota_0
and ota_1) and an OTA Data Partition .
The OTA operation functions write a new app firmware image to whichever OTA app slot that is currently not selected
for booting. Once the image is verified, the OTA Data partition is updated to specify that this image should be used
for the next boot.
OTA Data Partition
An OTA data partition (type data, subtype ota) must be included in the Partition Table of any project which uses
the OTA functions.
For factory boot settings, the OTA data partition should contain no data (all bytes erased to 0xFF). In this case the
esp-idf software bootloader will boot the factory app if it is present in the the partition table. If no factory app is
included in the partition table, the first available OTA slot (usually ota_0) is booted.
After the first OTA update, the OTA data partition is updated to specify which OTA app slot partition should be
booted next.
The OTA data partition is two flash sectors (0x2000 bytes) in size, to prevent problems if there is a power failure
while it is being written. Sectors are independently erased and written with matching data, and if they disagree a
counter field is used to determine which sector was written more recently.
App rollback
The main purpose of the application rollback is to keep the device working after the update. This feature allows
you to roll back to the previous working application in case a new application has critical errors. When the rollback
process is enabled and an OTA update provides a new version of the app, one of three things can happen:
• The application works fine, esp_ota_mark_app_valid_cancel_rollback() marks the running
application with the state ESP_OTA_IMG_VALID. There are no restrictions on booting this application.
• The application has critical errors and further work is not possible, a rollback to the previous application is re-
quired, esp_ota_mark_app_invalid_rollback_and_reboot() marks the running application
with the state ESP_OTA_IMG_INVALID and reset. This application will not be selected by the bootloader
for boot and will boot the previously working application.

• If the CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is set, and a reset occurs without calling

either function then the application is rolled back.
Note: The state is not written to the binary image of the application it is written to the otadata partition. The
partition contains a ota_seq counter which is a pointer to the slot (ota_0, ota_1, ) from which the application
will be selected for boot.
App OTA State States control the process of selecting a boot app:
States Restriction of selecting a boot app in bootloader

ESP_OTA_IMG_VALID
None restriction. Will be selected.
ESP_OTA_IMG_UNDEFINED
None restriction. Will be selected.
ESP_OTA_IMG_INVALID
Will not be selected.
ESP_OTA_IMG_ABORTED
Will not be selected.
ESP_OTA_IMG_NEWIf CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is set it will
be selected only once. In bootloader the state immediately changes to
ESP_OTA_IMG_PENDING_VERIFY.
ESP_OTA_IMG_PENDING_VERIFY
If CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is set it will not be se-
lected and the state will change to ESP_OTA_IMG_ABORTED.
If CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is not enabled (by default), then

the use of the following functions esp_ota_mark_app_valid_cancel_rollback() and
esp_ota_mark_app_invalid_rollback_and_reboot() are optional, and ESP_OTA_IMG_NEW and
ESP_OTA_IMG_PENDING_VERIFY states are not used.
An option in Kconfig CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE allows you to track the first
boot of a new application. In this case, the application must confirm its operability by calling
esp_ota_mark_app_valid_cancel_rollback() function, otherwise the application will be rolled back
upon reboot. It allows you to control the operability of the application during the boot phase. Thus, a new application
has only one attempt to boot successfully.
Rollback Process The description of the rollback process when CON-

FIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is enabled:
• The new application successfully downloaded and esp_ota_set_boot_partition() function makes
this partition bootable and sets the state ESP_OTA_IMG_NEW. This state means that the application is new
and should be monitored for its first boot.
• Reboot esp_restart().
• The bootloader checks for the ESP_OTA_IMG_PENDING_VERIFY state if it is set, then it will be written
to ESP_OTA_IMG_ABORTED.
• The bootloader selects a new application to boot so that the state is not set as ESP_OTA_IMG_INVALID or
ESP_OTA_IMG_ABORTED.
• The bootloader checks the selected application for ESP_OTA_IMG_NEW state if it is set, then it will
be written to ESP_OTA_IMG_PENDING_VERIFY. This state means that the application requires con-
firmation of its operability, if this does not happen and a reboot occurs, this state will be overwritten to
ESP_OTA_IMG_ABORTED (see above) and this application will no longer be able to start, i.e. there will
be a rollback to the previous work application.
• A new application has started and should make a self-test.
• If the self-test has completed successfully, then you must call the function
esp_ota_mark_app_valid_cancel_rollback() because the application is awaiting confir-
mation of operability (ESP_OTA_IMG_PENDING_VERIFY state).
• If the self-test fails then call esp_ota_mark_app_invalid_rollback_and_reboot() function to
roll back to the previous working application, while the invalid application is set ESP_OTA_IMG_INVALID
state.
• If the application has not been confirmed, the state remains ESP_OTA_IMG_PENDING_VERIFY, and the
next boot it will be changed to ESP_OTA_IMG_ABORTED. That will prevent re-boot of this application.
There will be a rollback to the previous working application.

Unexpected Reset If a power loss or an unexpected crash occurs at the time of the first boot of a new application,
it will roll back the application.
Recommendation: Perform the self-test procedure as quickly as possible, to prevent rollback due to power loss.
Only OTA partitions can be rolled back. Factory partition is not rolled back.
Booting invalid/aborted apps Booting an application which was previously set to ESP_OTA_IMG_INVALID or
ESP_OTA_IMG_ABORTED is possible:
• Get the last invalid application partition esp_ota_get_last_invalid_partition().
• Pass the received partition to esp_ota_set_boot_partition(), this will update the otadata.
• Restart esp_restart(). The bootloader will boot the specified application.
To determine if self-tests should be run during startup of an application, call the
esp_ota_get_state_partition() function. If result is ESP_OTA_IMG_PENDING_VERIFY then
self-testing and subsequent confirmation of operability is required.
Where the states are set A brief description of where the states are set:
• ESP_OTA_IMG_VALID state is set by esp_ota_mark_app_valid_cancel_rollback() func-
tion.
• ESP_OTA_IMG_UNDEFINED state is set by esp_ota_set_boot_partition() function if CON-
FIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is not enabled.
• ESP_OTA_IMG_NEW state is set by esp_ota_set_boot_partition() function if CON-
FIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is enabled.
• ESP_OTA_IMG_INVALID state is set by esp_ota_mark_app_invalid_rollback_and_reboot()
function.
• ESP_OTA_IMG_ABORTED state is set if there was no confirmation of the application operability and occurs
reboots (if CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is enabled).
• ESP_OTA_IMG_PENDING_VERIFY state is set in a bootloader if CON-
FIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is enabled and selected app has
ESP_OTA_IMG_NEW state.
Anti-rollback
Anti-rollback prevents rollback to application with security version lower than one programmed in eFuse of chip.
This function works if set CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK option. In the bootloader, when se-
lecting a bootable application, an additional security version check is added which is on the chip and in the application
image. The version in the bootable firmware must be greater than or equal to the version in the chip.
CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK and CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE op-
tions are used together. In this case, rollback is possible only on the security version which is equal or higher than
the version in the chip.
A typical anti-rollback scheme is

• New firmware released with the elimination of vulnerabilities with the previous version of security.
• After the developer makes sure that this firmware is working. He can increase the security version and release
a new firmware.
• Download new application.
• To make it bootable, run the function esp_ota_set_boot_partition(). If the security version of
the new application is smaller than the version in the chip, the new application will be erased. Update to new
firmware is not possible.
• Reboot.
• In the bootloader, an application with a security version greater than or equal to the version in the chip will
be selected. If otadata is in the initial state, and one firmware was loaded via a serial channel, whose secure
version is higher than the chip, then the secure version of efuse will be immediately updated in the bootloader.

• New application booted. Then the application should perform diagnostics of the operation and if it is
completed successfully, you should call esp_ota_mark_app_valid_cancel_rollback() func-
tion to mark the running application with the ESP_OTA_IMG_VALID state and update the secure ver-
sion on chip. Note that if was called esp_ota_mark_app_invalid_rollback_and_reboot()
function a rollback may not happend due to the device may not have any bootable apps then it will return
ESP_ERR_OTA_ROLLBACK_FAILED error and stay in the ESP_OTA_IMG_PENDING_VERIFY state.
• The next update of app is possible if a running app is in the ESP_OTA_IMG_VALID state.
Recommendation:
If you want to avoid the download/erase overhead in case of the app from the server has security version lower
then running app, you have to get new_app_info.secure_version from the first package of an image and
compare it with the secure version of efuse. Use esp_efuse_check_secure_version(new_app_info.
secure_version) function if it is true then continue downloading otherwise abort.
....
bool image_header_was_checked = false;
while (1) {
int data_read = esp_http_client_read(client, ota_write_data, BUFFSIZE);
...
if (data_read > 0) {
if (image_header_was_checked == false) {
esp_app_desc_t new_app_info;
if (data_read > sizeof(esp_image_header_t) + sizeof(esp_image_segment_
,→header_t) + sizeof(esp_app_desc_t)) {
// check current version with downloading

if (esp_efuse_check_secure_version(new_app_info.secure_version) ==␣
,→false) {
ESP_LOGE(TAG, "This a new app can not be downloaded due to a␣

,→secure version is lower than stored in efuse.");
http_cleanup(client);
task_fatal_error();
}
image_header_was_checked = true;
esp_ota_begin(update_partition, OTA_SIZE_UNKNOWN, &update_handle);

}
}
esp_ota_write( update_handle, (const void *)ota_write_data, data_read);
}
}
...
Restrictions:
• The number of bits in the secure_version field is limited to 32 bits. This means that only
32 times you can do an anti-rollback. You can reduce the length of this efuse field using CON-
FIG_BOOTLOADER_APP_SEC_VER_SIZE_EFUSE_FIELD option.
• Anti-rollback works only if the encoding scheme for efuse is set to NONE.
• Factory partition is not supported in anti rollback scheme and hence partition table should not have partition
with SubType set to factory.
• Test partition is not supported in anti rollback scheme and hence partition table should not have partition with
SubType set to test.
security_version:
• In application image it is stored in esp_app_desc structure. The number is set CON-
FIG_BOOTLOADER_APP_SECURE_VERSION.
• In ESP32 it is stored in efuse EFUSE_BLK3_RDATA4_REG. (when a eFuse bit is programmed to 1, it can
never be reverted to 0). The number of bits set in this register is the security_version from app.

Secure OTA Updates Without Secure boot
The verification of signed OTA updates can be performed even without enabling hardware secure
boot. This can be achieved by setting CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT and CON-
FIG_SECURE_SIGNED_ON_UPDATE_NO_SECURE_BOOT
For more information refer to Signed App Verification Without Hardware Secure Boot
OTA Tool (otatool.py)
The component app_update provides a tool otatool.py for performing OTA partition-related operations on a target
device. The following operations can be performed using the tool:
• read contents of otadata partition (read_otadata)
• erase otadata partition, effectively resetting device to factory app (erase_otadata)
• switch OTA partitions (switch_ota_partition)
• erasing OTA partition (erase_ota_partition)
• write to OTA partition (write_ota_partition)
• read contents of OTA partition (read_ota_partition)
The tool can either be imported and used from another Python script or invoked from shell script for users wanting
to perform operation programmatically. This is facilitated by the tool s Python API and command-line interface,
respectively.
Python API Before anything else, make sure that the otatool module is imported.
import sys
import os
idf_path = os.environ["IDF_PATH"] # get value of IDF_PATH from environment

otatool_dir = os.path.join(idf_path, "components", "app_update") # otatool.py␣
,→lives in $IDF_PATH/components/app_update
sys.path.append(otatool_dir) # this enables Python to find otatool module

from otatool import * # import all names inside otatool module
The starting point for using the tool s Python API to do is create a OtatoolTarget object:
# Create a partool.py target device connected on serial port /dev/ttyUSB1

target = OtatoolTarget("/dev/ttyUSB1")
The created object can now be used to perform operations on the target device:
# Erase otadata, reseting the device to factory app

target.erase_otadata()
# Erase contents of OTA app slot 0

target.erase_ota_partition(0)
# Switch boot partition to that of app slot 1

target.switch_ota_partition(1)
# Read OTA partition 'ota_3' and save contents to a file named 'ota_3.bin'
target.read_ota_partition("ota_3", "ota_3.bin")
The OTA partition to operate on is specified using either the app slot number or the partition name.
More information on the Python API is available in the docstrings for the tool.

Command-line Interface The command-line interface of otatool.py has the following structure:
otatool.py [command-args] [subcommand] [subcommand-args]
- command-args - these are arguments that are needed for executing the main␣
,→command (parttool.py), mostly pertaining to the target device
- subcommand - this is the operation to be performed

- subcommand-args - these are arguments that are specific to the chosen operation
# Erase otadata, resetting the device to factory app

otatool.py --port "/dev/ttyUSB1" erase_otadata
# Erase contents of OTA app slot 0

otatool.py --port "/dev/ttyUSB1" erase_ota_partition --slot 0
# Switch boot partition to that of app slot 1

otatool.py --port "/dev/ttyUSB1" switch_ota_partition --slot 1
# Read OTA partition 'ota_3' and save contents to a file named 'ota_3.bin'
otatool.py --port "/dev/ttyUSB1" read_ota_partition --name=ota_3 --output=ota_3.bin
More information can be obtained by specifying help as argument:

# Display possible subcommands and show main command argument descriptions
otatool.py --help
# Show descriptions for specific subcommand arguments

otatool.py [subcommand] --help
See also

• Lower-Level SPI Flash/Partition API
• ESP HTTPS OTA
Application Example
End-to-end example of OTA firmware update workflow: system/ota.
API Reference
Header File
• components/app_update/include/esp_ota_ops.h
Functions
const esp_app_desc_t *esp_ota_get_app_description(void)
Return esp_app_desc structure. This structure includes app version.
Return description for running app.
Return Pointer to esp_app_desc structure.
int esp_ota_get_app_elf_sha256(char *dst, size_t size)
Fill the provided buffer with SHA256 of the ELF file, formatted as hexadecimal, null-terminated. If the buffer
size is not sufficient to fit the entire SHA256 in hex plus a null terminator, the largest possible number of bytes
will be written followed by a null.
Return Number of bytes written to dst (including null terminator)
Parameters

• dst: Destination buffer

• size: Size of the buffer
esp_err_t esp_ota_begin(const esp_partition_t *partition, size_t image_size, esp_ota_handle_t
*out_handle)
Commence an OTA update writing to the specified partition.
The specified partition is erased to the specified image size.
If image size is not yet known, pass OTA_SIZE_UNKNOWN which will cause the entire partition to be erased.
On success, this function allocates memory that remains in use until esp_ota_end() is called with the returned
handle.
Note: If the rollback option is enabled and the running application has
the ESP_OTA_IMG_PENDING_VERIFY state then it will lead to the
ESP_ERR_OTA_ROLLBACK_INVALID_STATE error. Confirm the running app before to run download
a new app, use esp_ota_mark_app_valid_cancel_rollback() function for it (this should be done as early as
possible when you first download a new application).
Return
• ESP_OK: OTA operation commenced successfully.
• ESP_ERR_INVALID_ARG: partition or out_handle arguments were NULL, or partition doesn t
point to an OTA app partition.
• ESP_ERR_OTA_PARTITION_CONFLICT: Partition holds the currently running firmware, can-
not update in place.
• ESP_ERR_NOT_FOUND: Partition argument not found in partition table.
• ESP_ERR_OTA_SELECT_INFO_INVALID: The OTA data partition contains invalid data.
• ESP_ERR_INVALID_SIZE: Partition doesn t fit in configured flash size.
• ESP_ERR_OTA_ROLLBACK_INVALID_STATE: If the running app has not confirmed state.
Before performing an update, the application must be valid.
Parameters
• partition: Pointer to info for partition which will receive the OTA update. Required.
• image_size: Size of new OTA app image. Partition will be erased in order to receive this size
of image. If 0 or OTA_SIZE_UNKNOWN, the entire partition is erased.
• out_handle: On success, returns a handle which should be used for subsequent esp_ota_write()
and esp_ota_end() calls.
esp_err_t esp_ota_write(esp_ota_handle_t handle, const void *data, size_t size)
Write OTA update data to partition.
This function can be called multiple times as data is received during the OTA operation. Data is written
sequentially to the partition.
Return
• ESP_OK: Data was written to flash successfully.
• ESP_ERR_INVALID_ARG: handle is invalid.
• ESP_ERR_OTA_VALIDATE_FAILED: First byte of image contains invalid app image magic byte.
• ESP_ERR_OTA_SELECT_INFO_INVALID: OTA data partition has invalid contents
Parameters
• handle: Handle obtained from esp_ota_begin
• data: Data buffer to write
• size: Size of data buffer in bytes.
esp_err_t esp_ota_write_with_offset(esp_ota_handle_t handle, const void *data, size_t size,
uint32_t offset)
Write OTA update data to partition.
This function can write data in non contiguous manner. If flash encryption is enabled, data should be 16 byte
aligned.

Note While performing OTA, if the packets arrive out of order, esp_ota_write_with_offset() can be used
to write data in non contiguous manner. Use of esp_ota_write_with_offset() in combination with
esp_ota_write() is not recommended.
Return
• ESP_OK: Data was written to flash successfully.
• ESP_ERR_INVALID_ARG: handle is invalid.
• ESP_ERR_OTA_VALIDATE_FAILED: First byte of image contains invalid app image magic byte.
• ESP_ERR_OTA_SELECT_INFO_INVALID: OTA data partition has invalid contents
Parameters
• handle: Handle obtained from esp_ota_begin
• data: Data buffer to write
• size: Size of data buffer in bytes
• offset: Offset in flash partition
esp_err_t esp_ota_end(esp_ota_handle_t handle)
Finish OTA update and validate newly written app image.
Note After calling esp_ota_end(), the handle is no longer valid and any memory associated with it is freed
(regardless of result).
Return
• ESP_OK: Newly written OTA app image is valid.
• ESP_ERR_NOT_FOUND: OTA handle was not found.
• ESP_ERR_INVALID_ARG: Handle was never written to.
• ESP_ERR_OTA_VALIDATE_FAILED: OTA image is invalid (either not a valid app image, or -
if secure boot is enabled - signature failed to verify.)
• ESP_ERR_INVALID_STATE: If flash encryption is enabled, this result indicates an internal error
writing the final encrypted bytes to flash.
Parameters
• handle: Handle obtained from esp_ota_begin().
esp_err_t esp_ota_abort(esp_ota_handle_t handle)
Abort OTA update, free the handle and memory associated with it.
Return
• ESP_OK: Handle and its associated memory is freed successfully.
• ESP_ERR_NOT_FOUND: OTA handle was not found.
Parameters
• handle: obtained from esp_ota_begin().
esp_err_t esp_ota_set_boot_partition(const esp_partition_t *partition)
Configure OTA data for a new boot partition.
Note If this function returns ESP_OK, calling esp_restart() will boot the newly configured app partition.
Return
• ESP_OK: OTA data updated, next reboot will use specified partition.
• ESP_ERR_INVALID_ARG: partition argument was NULL or didn t point to a valid OTA partition
of type app .
• ESP_ERR_OTA_VALIDATE_FAILED: Partition contained invalid app image. Also returned if
secure boot is enabled and signature validation failed.
• ESP_ERR_NOT_FOUND: OTA data partition not found.
• ESP_ERR_FLASH_OP_TIMEOUT or ESP_ERR_FLASH_OP_FAIL: Flash erase or write failed.
Parameters
• partition: Pointer to info for partition containing app image to boot.
const esp_partition_t *esp_ota_get_boot_partition(void)
Get partition info of currently configured boot app.
If esp_ota_set_boot_partition() has been called, the partition which was set by that function will be returned.
If esp_ota_set_boot_partition() has not been called, the result is usually the same as
esp_ota_get_running_partition(). The two results are not equal if the configured boot partition does

not contain a valid app (meaning that the running partition will be an app that the bootloader chose via
fallback).
If the OTA data partition is not present or not valid then the result is the first app partition found in the partition
table. In priority order, this means: the factory app, the first OTA app slot, or the test app partition.
Note that there is no guarantee the returned partition is a valid app. Use
esp_image_verify(ESP_IMAGE_VERIFY, ) to verify if the returned partition contains a bootable
image.
Return Pointer to info for partition structure, or NULL if partition table is invalid or a flash read operation
failed. Any returned pointer is valid for the lifetime of the application.
const esp_partition_t *esp_ota_get_running_partition(void)
Get partition info of currently running app.
This function is different to esp_ota_get_boot_partition() in that it ignores any change of selected boot partition
caused by esp_ota_set_boot_partition(). Only the app whose code is currently running will have its partition
information returned.
The partition returned by this function may also differ from esp_ota_get_boot_partition() if the configured
boot partition is somehow invalid, and the bootloader fell back to a different app partition at boot.
Return Pointer to info for partition structure, or NULL if no partition is found or flash read operation failed.
Returned pointer is valid for the lifetime of the application.
const esp_partition_t *esp_ota_get_next_update_partition(const esp_partition_t
*start_from)
Return the next OTA app partition which should be written with a new firmware.
Call this function to find an OTA app partition which can be passed to esp_ota_begin().
Finds next partition round-robin, starting from the current running partition.
Return Pointer to info for partition which should be updated next. NULL result indicates invalid OTA data
partition, or that no eligible OTA app slot partition was found.
Parameters
• start_from: If set, treat this partition info as describing the current running partition. Can be
NULL, in which case esp_ota_get_running_partition() is used to find the currently running partition.
The result of this function is never the same as this argument.
esp_err_t esp_ota_get_partition_description(const esp_partition_t *partition,
esp_app_desc_t *app_desc)
Returns esp_app_desc structure for app partition. This structure includes app version.
Returns a description for the requested app partition.
Return
• ESP_OK Successful.
• ESP_ERR_NOT_FOUND app_desc structure is not found. Magic word is incorrect.
• ESP_ERR_NOT_SUPPORTED Partition is not application.
• ESP_ERR_INVALID_ARG Arguments is NULL or if partition s offset exceeds partition size.
• ESP_ERR_INVALID_SIZE Read would go out of bounds of the partition.
Parameters
• [in] partition: Pointer to app partition. (only app partition)
• [out] app_desc: Structure of info about app.
uint8_t esp_ota_get_app_partition_count(void)
Returns number of ota partitions provided in partition table.
Return
• Number of OTA partitions
esp_err_t esp_ota_mark_app_valid_cancel_rollback(void)
This function is called to indicate that the running app is working well.

Return
• ESP_OK: if successful.
esp_err_t esp_ota_mark_app_invalid_rollback_and_reboot(void)
This function is called to roll back to the previously workable app with reboot.
If rollback is successful then device will reset else API will return with error code. Checks applications on a
flash drive that can be booted in case of rollback. If the flash does not have at least one app (except the running
app) then rollback is not possible.
Return
• ESP_FAIL: if not successful.
• ESP_ERR_OTA_ROLLBACK_FAILED: The rollback is not possible due to flash does not have
any apps.
const esp_partition_t *esp_ota_get_last_invalid_partition(void)
Returns last partition with invalid state (ESP_OTA_IMG_INVALID or ESP_OTA_IMG_ABORTED).
Return partition.
esp_err_t esp_ota_get_state_partition(const esp_partition_t *partition, esp_ota_img_states_t
*ota_state)
Returns state for given partition.
Return
•
ESP_OK: Successful.
•
ESP_ERR_INVALID_ARG: partition or ota_state arguments were NULL.
•
ESP_ERR_NOT_SUPPORTED: partition is not ota.
•
ESP_ERR_NOT_FOUND: Partition table does not have otadata or state was not found for given
partition.
Parameters
• [in] partition: Pointer to partition.
• [out] ota_state: state of partition (if this partition has a record in otadata).
esp_err_t esp_ota_erase_last_boot_app_partition(void)
Erase previous boot app partition and corresponding otadata select for this partition.
When current app is marked to as valid then you can erase previous app partition.
Return
• ESP_OK: Successful, otherwise ESP_ERR.
bool esp_ota_check_rollback_is_possible(void)
Checks applications on the slots which can be booted in case of rollback.
These applications should be valid (marked in otadata as not UNDEFINED, INVALID or ABORTED and crc
is good) and be able booted, and secure_version of app >= secure_version of efuse (if anti-rollback is enabled).
Return
• True: Returns true if the slots have at least one app (except the running app).
• False: The rollback is not possible.
Macros
OTA_SIZE_UNKNOWN
Used for esp_ota_begin() if new image size is unknown
OTA_WITH_SEQUENTIAL_WRITES
Used for esp_ota_begin() if new image size is unknown and erase can be done in incremental manner (assuming
write operation is in continuous sequence)
ESP_ERR_OTA_BASE
Base error code for ota_ops api
ESP_ERR_OTA_PARTITION_CONFLICT
Error if request was to write or erase the current running partition

ESP_ERR_OTA_SELECT_INFO_INVALID
Error if OTA data partition contains invalid content
ESP_ERR_OTA_VALIDATE_FAILED
Error if OTA app image is invalid
ESP_ERR_OTA_SMALL_SEC_VER
Error if the firmware has a secure version less than the running firmware.
ESP_ERR_OTA_ROLLBACK_FAILED
Error if flash does not have valid firmware in passive partition and hence rollback is not possible
ESP_ERR_OTA_ROLLBACK_INVALID_STATE
Error if current active firmware is still marked in pending validation state
(ESP_OTA_IMG_PENDING_VERIFY), essentially first boot of firmware image post upgrade and
hence firmware upgrade is not possible
Type Definitions
typedef uint32_t esp_ota_handle_t
Opaque handle for an application OTA update.
esp_ota_begin() returns a handle which is then used for subsequent calls to esp_ota_write() and esp_ota_end().
Debugging OTA Failure
Fig. 39: How to Debug When OTA Fails (click to enlarge)

2.7.21 Performance Monitor
The Performance Monitor component provides APIs to use ESP32 internal performance counters to profile functions
and applications.
Application Example
An example which combines performance monitor is provided in examples/system/perfmon directory. This

example initializes the performance monitor structure and execute them with printing the statistics.
High level API Reference
Header Files
• perfmon/include/perfmon.h
API Reference
Header File
• components/perfmon/include/xtensa_perfmon_access.h
Functions
esp_err_t xtensa_perfmon_init(int id, uint16_t select, uint16_t mask, int kernelcnt, int tracelevel)
Init Performance Monitoor.
Initialize performance monitor register with define values
Return
• ESP_ERR_INVALID_ARG if one of the arguments is not correct
Parameters
• [in] id: performance counter number
• [in] select: select value from PMCTRLx register
• [in] mask: mask value from PMCTRLx register
• [in] kernelcnt: kernelcnt value from PMCTRLx register
• [in] tracelevel: tracelevel value from PMCTRLx register
esp_err_t xtensa_perfmon_reset(int id)
Reset PM counter.
Reset PM counter. Writes 0 to the PMx register.
Return
• ESP_ERR_INVALID_ARG if id out of range
Parameters
void xtensa_perfmon_start(void)
Start PM counters.
Start all PM counters synchronously. Write 1 to the PGM register
void xtensa_perfmon_stop(void)
Stop PM counters.
Stop all PM counters synchronously. Write 0 to the PGM register

uint32_t xtensa_perfmon_value(int id)

Read PM counter.
Read value of defined PM counter.
Return
• Performance counter value
Parameters
esp_err_t xtensa_perfmon_overflow(int id)
Read PM overflow state.
Read overflow value of defined PM counter.
Return
• ESP_OK if there is no overflow (overflow = 0)
• ESP_FAIL if overflow occure (overflow = 1)
Parameters
void xtensa_perfmon_dump(void)
Dump PM values.
Dump all PM register to the console.
Header File
• components/perfmon/include/xtensa_perfmon_apis.h
Functions
esp_err_t xtensa_perfmon_exec(const xtensa_perfmon_config_t *config)
Execute PM.
Execute performance counter for dedicated function with defined parameters
Return
• ESP_OK if no errors
• ESP_ERR_INVALID_ARG if one of the required parameters not defined
• ESP_FAIL - counter overflow
Parameters
• [in] config: pointer to the configuration structure
void xtensa_perfmon_view_cb(void *params, uint32_t select, uint32_t mask, uint32_t value)
Dump PM results.
Callback to dump perfmon result to a FILE* stream specified in perfmon_config_t::callback_params. If call-
back_params is set to NULL, will print to stdout
Parameters
• [in] params: used parameters passed from configuration (callback_params). This parameter
expected as FILE* hanle, where data will be stored. If this parameter NULL, then data will be
stored to the stdout.
• [in] select: select value for current counter
• [in] mask: mask value for current counter
• [in] value: counter value for current counter
Structures
struct xtensa_perfmon_config
Performance monitor configuration structure.
Structure to configure performance counter to measure dedicated function

Public Members
int repeat_count
how much times function will be called before the calback will be repeated
float max_deviation
Difference between min and max counter number 0..1, 0 - no difference, 1 - not used
void *call_params
This pointer will be passed to the call_function as a parameter
void (*call_function)(void *params)
pointer to the function that have to be called
void (*callback)(void *params, uint32_t select, uint32_t mask, uint32_t value)
pointer to the function that will be called with result parameters
void *callback_params
parameter that will be passed to the callback
int tracelevel
trace level for all counters. In case of negative value, the filter will be ignored. If it s >=0, then the
perfmon will count only when interrupt level > tracelevel. It s useful to monitor interrupts.
uint32_t counters_size
amount of counter in the list
const uint32_t *select_mask
list of the select/mask parameters
Type Definitions
typedef struct xtensa_perfmon_config xtensa_perfmon_config_t
Performance monitor configuration structure.
Structure to configure performance counter to measure dedicated function
2.7.22 Power Management
Overview
Power management algorithm included in ESP-IDF can adjust the advanced peripheral bus (APB) frequency, CPU
frequency, and put the chip into light sleep mode to run an application at smallest possible power consumption, given
the requirements of application components.
Application components can express their requirements by creating and acquiring power management locks.
For example:
• Driver for a peripheral clocked from APB can request the APB frequency to be set to 80 MHz while the
peripheral is used.
• RTOS can request the CPU to run at the highest configured frequency while there are tasks ready to run.
• A peripheral driver may need interrupts to be enabled, which means it will have to request disabling light sleep.
Since requesting higher APB or CPU frequencies or disabling light sleep causes higher current consumption, please
keep the usage of power management locks by components to a minimum.
Configuration
Power management can be enabled at compile time, using the option CONFIG_PM_ENABLE.
Enabling power management features comes at the cost of increased interrupt latency. Extra latency depends on
a number of factors, such as the CPU frequency, single/dual core mode, whether or not frequency switch needs
to be done. Minimum extra latency is 0.2 us (when the CPU frequency is 240 MHz and frequency scaling is not

enabled). Maximum extra latency is 40 us (when frequency scaling is enabled, and a switch from 40 MHz to 80 MHz
is performed on interrupt entry).
Dynamic frequency scaling (DFS) and automatic light sleep can be enabled in an application by calling
the function esp_pm_configure(). Its argument is a structure defining the frequency scaling settings,
esp_pm_config_esp32_t. In this structure, three fields need to be initialized:
• max_freq_mhz: Maximum CPU frequency in MHz, i.e., the frequency used when the
ESP_PM_CPU_FREQ_MAX lock is acquired. This field will usually be set to the default CPU frequency.
• min_freq_mhz: Minimum CPU frequency in MHz, i.e., the frequency used when only the
ESP_PM_APB_FREQ_MAX lock is acquired. This field can be set to the XTAL frequency value, or the XTAL
frequency divided by an integer. Note that 10 MHz is the lowest frequency at which the default REF_TICK
clock of 1 MHz can be generated.
• light_sleep_enable: Whether the system should automatically enter light sleep when no locks are
acquired (true/false).
Alternatively, if you enable the option CONFIG_PM_DFS_INIT_AUTO in menuconfig, the maximum CPU
frequency will be determined by the CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ setting, and the minimum
CPU frequency will be locked to the XTAL frequency.
Note: Automatic light sleep is based on FreeRTOS Tickless Idle functionality. If automatic light
sleep is requested while the option CONFIG_FREERTOS_USE_TICKLESS_IDLE is not enabled in menuconfig,
esp_pm_configure() will return the error ESP_ERR_NOT_SUPPORTED.
Note: In light sleep, peripherals are clock gated, and interrupts (from GPIOs and internal peripherals) will not be
generated. A wakeup source described in the Sleep Modes documentation can be used to trigger wakeup from the
light sleep state.
For example, the EXT0 and EXT1 wakeup sources can be used to wake up the chip via a GPIO.
Power Management Locks
Applications have the ability to acquire/release locks in order to control the power management algorithm. When an
application acquires a lock, the power management algorithm operation is restricted in a way described below. When
the lock is released, such restrictions are removed.
Power management locks have acquire/release counters. If the lock has been acquired a number of times, it needs to
be released the same number of times to remove associated restrictions.
ESP32 supports three types of locks described in the table below.
Lock Description
ESP_PM_CPU_FREQ_MAX Requests CPU frequency to be at the maximum value set
with esp_pm_configure(). For ESP32, this value can be set to 80
MHz, 160 MHz, or 240 MHz.
ESP_PM_APB_FREQ_MAX Requests the APB frequency to be at the maximum supported value. For
ESP32, this is 80 MHz.
ESP_PM_NO_LIGHT_SLEEP Disables automatic switching to light sleep.
ESP32 Power Management Algorithm
The table below shows how CPU and APB frequencies will be switched if dynamic frequency scaling is
enabled. You can specify the maximum CPU frequency with either esp_pm_configure() or CON-
FIG_ESP32_DEFAULT_CPU_FREQ_MHZ.

Max CPU Frequency Set Lock Acquisition CPU and APB Frequncies
240
Any of CPU: 240 MHz
ESP_PM_CPU_FREQ_MAX APB: 80 MHz
or ESP_PM_APB_FREQ_MAX
acquired
None Min values for both frequencies set

with esp_pm_configure()
160 ESP_PM_CPU_FREQ_MAX
acquired
CPU: 160 MHz
APB: 80 MHz
ESP_PM_APB_FREQ_MAX
acquired,
CPU: 80 MHz
ESP_PM_CPU_FREQ_MAX
not acquired APB: 80 MHz

80
Any of CPU: 80 MHz
ESP_PM_CPU_FREQ_MAX APB: 80 MHz
or ESP_PM_APB_FREQ_MAX
acquired

If none of the locks are acquired, and light sleep is enabled in a call to esp_pm_configure(), the system will
go into light sleep mode. The duration of light sleep will be determined by:
• FreeRTOS tasks blocked with finite timeouts
• Timers registered with High resolution timer APIs
Light sleep duration will be chosen to wake up the chip before the nearest event (task being unblocked, or timer
elapses).
To skip unnecessary wake-up you can consider initializing an esp_timer with the skip_unhandled_events option as
true. Timers with this flag will not wake up the system and it helps to reduce consumption.
Dynamic Frequency Scaling and Peripheral Drivers
When DFS is enabled, the APB frequency can be changed multiple times within a single RTOS tick. The APB
frequency change does not affect the work of some peripherals, while other peripherals may have issues. For example,
Timer Group peripheral timers will keep counting, however, the speed at which they count will change proportionally
to the APB frequency.
The following peripherals work normally even when the APB frequency is changing:
• UART: if REF_TICK is used as a clock source. See use_ref_tick member of uart_config_t.
• LEDC: if REF_TICK is used as a clock source. See ledc_timer_config() function.
• RMT: if REF_TICK or XTAL is used as a clock source. See flags member of rmt_config_t and macro
RMT_CHANNEL_FLAGS_AWARE_DFS.
Currently, the following peripheral drivers are aware of DFS and will use the ESP_PM_APB_FREQ_MAX lock for
the duration of the transaction:

• SPI master
• I2C
• I2S (If the APLL clock is used, then it will use the ESP_PM_NO_LIGHT_SLEEP lock)
• SDMMC
The following drivers will hold the ESP_PM_APB_FREQ_MAX lock while the driver is enabled:
• SPI slave: between calls to spi_slave_initialize() and spi_slave_free().
• Ethernet: between calls to esp_eth_driver_install() and esp_eth_driver_uninstall().
• WiFi: between calls to esp_wifi_start() and esp_wifi_stop(). If modem sleep is enabled, the
lock will be released for the periods of time when radio is disabled.
• TWAI: between calls to twai_driver_install() and twai_driver_uninstall().
• Bluetooth: between calls to esp_bt_controller_enable() and
esp_bt_controller_disable(). If Bluetooth modem sleep is enabled, the
ESP_PM_APB_FREQ_MAX lock will be released for the periods of time when radio is disabled. However the
ESP_PM_NO_LIGHT_SLEEP lock will still be held, unless CONFIG_BTDM_CTRL_LOW_POWER_CLOCK
option is set to External 32kHz crystal .
The following peripheral drivers are not aware of DFS yet. Applications need to acquire/release locks themselves,
when necessary:
• PCNT
• Sigma-delta
• Timer group
• MCPWM
API Reference
Header File
• components/esp_pm/include/esp_pm.h
Functions
esp_err_t esp_pm_configure(const void *config)
Set implementation-specific power management configuration.
Return
• ESP_ERR_INVALID_ARG if the configuration values are not correct
• ESP_ERR_NOT_SUPPORTED if certain combination of values is not supported, or if CON-
FIG_PM_ENABLE is not enabled in sdkconfig
Parameters
• config: pointer to implementation-specific configuration structure (e.g. esp_pm_config_esp32)
esp_err_t esp_pm_get_configuration(void *config)
Get implementation-specific power management configuration.
Return
• ESP_ERR_INVALID_ARG if the pointer is null
Parameters
• config: pointer to implementation-specific configuration structure (e.g. esp_pm_config_esp32)
esp_err_t esp_pm_lock_create(esp_pm_lock_type_t lock_type, int arg, const char *name,
esp_pm_lock_handle_t *out_handle)
Initialize a lock handle for certain power management parameter.
When lock is created, initially it is not taken. Call esp_pm_lock_acquire to take the lock.
This function must not be called from an ISR.
Return

• ESP_ERR_NO_MEM if the lock structure can not be allocated

• ESP_ERR_INVALID_ARG if out_handle is NULL or type argument is not valid
• ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig
Parameters
• lock_type: Power management constraint which the lock should control
• arg: argument, value depends on lock_type, see esp_pm_lock_type_t
• name: arbitrary string identifying the lock (e.g. wifi or spi ). Used by the esp_pm_dump_locks
function to list existing locks. May be set to NULL. If not set to NULL, must point to a string which
is valid for the lifetime of the lock.
• [out] out_handle: handle returned from this function. Use this handle when calling
esp_pm_lock_delete, esp_pm_lock_acquire, esp_pm_lock_release. Must not be NULL.
esp_err_t esp_pm_lock_acquire(esp_pm_lock_handle_t handle)
Take a power management lock.
Once the lock is taken, power management algorithm will not switch to the mode specified in a call to
esp_pm_lock_create, or any of the lower power modes (higher numeric values of mode ).
The lock is recursive, in the sense that if esp_pm_lock_acquire is called a number of times,
esp_pm_lock_release has to be called the same number of times in order to release the lock.
This function may be called from an ISR.
This function is not thread-safe w.r.t. calls to other esp_pm_lock_* functions for the same handle.
Return
Parameters
• handle: handle obtained from esp_pm_lock_create function
esp_err_t esp_pm_lock_release(esp_pm_lock_handle_t handle)
Release the lock taken using esp_pm_lock_acquire.
Call to this functions removes power management restrictions placed when taking the lock.
Locks are recursive, so if esp_pm_lock_acquire is called a number of times, esp_pm_lock_release has to be
called the same number of times in order to actually release the lock.
This function may be called from an ISR.
This function is not thread-safe w.r.t. calls to other esp_pm_lock_* functions for the same handle.
Return
• ESP_ERR_INVALID_STATE if lock is not acquired
Parameters
esp_err_t esp_pm_lock_delete(esp_pm_lock_handle_t handle)
Delete a lock created using esp_pm_lock.
The lock must be released before calling this function.
This function must not be called from an ISR.
Return
• ESP_ERR_INVALID_ARG if the handle argument is NULL
• ESP_ERR_INVALID_STATE if the lock is still acquired
Parameters

esp_err_t esp_pm_dump_locks(FILE *stream)

Dump the list of all locks to stderr
This function dumps debugging information about locks created using esp_pm_lock_create to an output stream.
This function must not be called from an ISR. If esp_pm_lock_acquire/release are called while this function
is running, inconsistent results may be reported.
Return
Parameters
• stream: stream to print information to; use stdout or stderr to print to the console; use fmemo-
pen/open_memstream to print to a string buffer.
Type Definitions
typedef struct esp_pm_lock *esp_pm_lock_handle_t
Opaque handle to the power management lock.
Enumerations
enum esp_pm_lock_type_t
Power management constraints.
Values:
ESP_PM_CPU_FREQ_MAX
Require CPU frequency to be at the maximum value set via esp_pm_configure. Argument is unused and
should be set to 0.
ESP_PM_APB_FREQ_MAX
Require APB frequency to be at the maximum value supported by the chip. Argument is unused and
should be set to 0.
ESP_PM_NO_LIGHT_SLEEP
Prevent the system from going into light sleep. Argument is unused and should be set to 0.
Header File
• components/esp_pm/include/esp32/pm.h
Structures
struct esp_pm_config_esp32_t
Power management config for ESP32.
Pass a pointer to this structure as an argument to esp_pm_configure function.
Public Members
int max_freq_mhz
Maximum CPU frequency, in MHz
int min_freq_mhz
Minimum CPU frequency to use when no locks are taken, in MHz
bool light_sleep_enable
Enter light sleep when no locks are taken

2.7.23 Random Number Generation
ESP32 contains a hardware random number generator, values from it can be obtained using the APIs
esp_random() and esp_fill_random().
The hardware RNG produces true random numbers under any of the following conditions:
• RF subsystem is enabled (i.e. Wi-Fi or Bluetooth are enabled).
• An internal entropy source has been enabled by calling bootloader_random_enable() and not yet
disabled by calling bootloader_random_disable().
• While the ESP-IDF Second stage bootloader is running. This is because the default ESP-IDF boot-
loader implementation calls bootloader_random_enable() when the bootloader starts, and boot-
loader_random_disable() before executing the app.
When any of these conditions are true, samples of physical noise are continuously mixed into the internal hardware
RNG state to provide entropy. Consult the ESP32 Technical Reference Manual > Random Number Generator (RNG)
[PDF] chapter for more details.
If none of the above conditions are true, the output of the RNG should be considered pseudo-random only.
Startup
During startup, ESP-IDF bootloader temporarily enables a non-RF entropy source (internal reference voltage noise)
that provides entropy for any first boot key generation. However, after the app starts executing then normally only
pseudo-random numbers are available until Wi-Fi or Bluetooth are initialized.
To re-enable the entropy source temporarily during app startup, or for an application that does not use Wi-Fi or
Bluetooth, call the function bootloader_random_enable() to re-enable the internal entropy source. The
function bootloader_random_disable() must be called to disable the entropy source again before using
ADC, I2S, Wi-Fi or Bluetooth.
Note: The entropy source enabled during the boot process by the ESP-IDF Second Stage Bootloader will seed the
internal RNG state with some entropy. However, the internal hardware RNG state is not large enough to provide a
continuous stream of true random numbers. This is why a continuous entropy source must be enabled whenever true
random numbers are required.
Note: If an application requires a source of true random numbers but it is not possible to permanently enable a
hardware entropy source, consider using a strong software DRBG implementation such as the mbedTLS CTR-DRBG
or HMAC-DRBG, with an initial seed of entropy from hardware RNG true random numbers.
API Reference
Header File
• components/esp_hw_support/include/esp_random.h
Functions
uint32_t esp_random(void)
Get one random 32-bit word from hardware RNG.
If Wi-Fi or Bluetooth are enabled, this function returns true random numbers. In other situations, if true
random numbers are required then consult the ESP-IDF Programming Guide Random Number Generation
section for necessary prerequisites.
This function automatically busy-waits to ensure enough external entropy has been introduced into the hardware
RNG state, before returning a new random number. This delay is very short (always less than 100 CPU cycles).

Return Random value between 0 and UINT32_MAX

void esp_fill_random(void *buf, size_t len)
Fill a buffer with random bytes from hardware RNG.
Note This function is implemented via calls to esp_random(), so the same constraints apply.
Parameters
• buf: Pointer to buffer to fill with random numbers.
• len: Length of buffer in bytes
Header File
• components/bootloader_support/include/bootloader_random.h
Functions
void bootloader_random_enable(void)
Enable an entropy source for RNG if RF is disabled.
The exact internal entropy source mechanism depends on the chip in use but all SoCs use the SAR ADC
to continuously mix random bits (an internal noise reading) into the HWRNG. Consult the SoC Technical
Reference Manual for more information.
Can also be used from app code early during operation, if true random numbers are required before RF is
initialised. Consult ESP-IDF Programming Guide Random Number Generation section for details.
void bootloader_random_disable(void)
Disable entropy source for RNG.
Disables internal entropy source. Must be called after bootloader_random_enable() and before RF features,
ADC, or I2S (ESP32 only) are initialized.
Consult the ESP-IDF Programming Guide Random Number Generation section for details.
void bootloader_fill_random(void *buffer, size_t length)
Fill buffer with length random bytes.
Note If this function is being called from app code only, and never from the bootloader, then it s better to
call esp_fill_random().
Parameters
• buffer: Pointer to buffer
• length: This many bytes of random data will be copied to buffer
getrandom
A compatible version of the Linux getrandom() function is also provided for ease of porting:
#include <sys/random.h>
ssize_t getrandom(void *buf, size_t buflen, unsigned int flags);
This function is implemented by calling esp_fill_random() internally.

The flags argument is ignored, this function is always non-blocking but the strength of any random numbers is
dependent on the same conditions described above.
Return value is -1 (with errno set to EFAULT) if the buf argument is NULL, and equal to buflen otherwise.
2.7.24 Sleep Modes
Overview
ESP32 is capable of light sleep and deep sleep power saving modes.

In light sleep mode, digital peripherals, most of the RAM, and CPUs are clock-gated, and supply voltage is reduced.
Upon exit from light sleep, peripherals and CPUs resume operation, their internal state is preserved.
In deep sleep mode, CPUs, most of the RAM, and all the digital peripherals which are clocked from APB_CLK are
powered off. The only parts of the chip which can still be powered on are:
• RTC controller
• RTC peripherals
• ULP coprocessor
• RTC fast memory
• RTC slow memory
Wakeup from deep and light sleep modes can be done using several sources. These sources can be
combined, in this case the chip will wake up when any one of the sources is triggered. Wakeup
sources can be enabled using esp_sleep_enable_X_wakeup APIs and can be disabled using
esp_sleep_disable_wakeup_source() API. Next section describes these APIs in detail. Wakeup
sources can be configured at any moment before entering light or deep sleep mode.
Additionally, the application can force specific powerdown modes for the RTC peripherals and RTC memories using
esp_sleep_pd_config() API.
Once wakeup sources are configured, application can enter sleep mode using esp_light_sleep_start() or
esp_deep_sleep_start() APIs. At this point the hardware will be configured according to the requested
wakeup sources, and RTC controller will either power down or power off the CPUs and digital peripherals.
If WiFi connection needs to be maintained, enable WiFi modem sleep, and enable automatic light sleep feature (see
Power Management APIs). This will allow the system to wake up from sleep automatically when required by WiFi
driver, thereby maintaining connection to the AP.
WiFi/BT and sleep modes
In deep sleep and light sleep modes, wireless peripherals are powered down. Before entering deep sleep or light
sleep modes, applications must disable WiFi and BT using appropriate calls (esp_bluedroid_disable(),
esp_bt_controller_disable(), esp_wifi_stop()). WiFi and BT connections will not be maintained
in deep sleep or light sleep, even if these functions are not called.
Wakeup sources
Timer RTC controller has a built in timer which can be used to wake up the chip after a predefined amount of
time. Time is specified at microsecond precision, but the actual resolution depends on the clock source selected for
RTC SLOW_CLK.
For details on RTC clock options, see ESP32 Technical Reference Manual > ULP Coprocessor [PDF].
This wakeup mode doesn t require RTC peripherals or RTC memories to be powered on during sleep.
esp_sleep_enable_timer_wakeup() function can be used to enable deep sleep wakeup using a timer.
Touch pad RTC IO module contains logic to trigger wakeup when a touch sensor interrupt occurs. You need to
configure the touch pad interrupt before the chip starts deep sleep.
Revisions 0 and 1 of the ESP32 only support this wakeup mode when RTC peripherals are not forced to be powered
on (i.e. ESP_PD_DOMAIN_RTC_PERIPH should be set to ESP_PD_OPTION_AUTO).
esp_sleep_enable_touchpad_wakeup() function can be used to enable this wakeup source.
External wakeup (ext0) RTC IO module contains logic to trigger wakeup when one of RTC GPIOs is set to a
predefined logic level. RTC IO is part of RTC peripherals power domain, so RTC peripherals will be kept powered
on during deep sleep if this wakeup source is requested.

Because RTC IO module is enabled in this mode, internal pullup or pulldown resistors can also be used. They
need to be configured by the application using rtc_gpio_pullup_en() and rtc_gpio_pulldown_en()
functions, before calling esp_sleep_start().
In revisions 0 and 1 of the ESP32, this wakeup source is incompatible with ULP and touch wakeup sources.
esp_sleep_enable_ext0_wakeup() function can be used to enable this wakeup source.
Warning: After wake up from sleep, IO pad used for wakeup will be configured as RTC IO. Before using this
pad as digital GPIO, reconfigure it using rtc_gpio_deinit(gpio_num) function.
External wakeup (ext1) RTC controller contains logic to trigger wakeup using multiple RTC GPIOs. One of the
two logic functions can be used to trigger wakeup:
• wake up if any of the selected pins is high (ESP_EXT1_WAKEUP_ANY_HIGH)
• wake up if all the selected pins are low (ESP_EXT1_WAKEUP_ALL_LOW)
This wakeup source is implemented by the RTC controller. As such, RTC peripherals and RTC memories can be
powered down in this mode. However, if RTC peripherals are powered down, internal pullup and pulldown resistors
will be disabled. To use internal pullup or pulldown resistors, request RTC peripherals power domain to be kept on
during sleep, and configure pullup/pulldown resistors using rtc_gpio_ functions, before entering sleep:
esp_sleep_pd_config(ESP_PD_DOMAIN_RTC_PERIPH, ESP_PD_OPTION_ON);
gpio_pullup_dis(gpio_num);
gpio_pulldown_en(gpio_num);
Warning: After wake up from sleep, IO pad(s) used for wakeup will be configured as RTC IO. Before using
these pads as digital GPIOs, reconfigure them using rtc_gpio_deinit(gpio_num) function.
esp_sleep_enable_ext1_wakeup() function can be used to enable this wakeup source.
ULP coprocessor wakeup ULP coprocessor can run while the chip is in sleep mode, and may be used to poll
sensors, monitor ADC or touch sensor values, and wake up the chip when a specific event is detected. ULP copro-
cessor is part of RTC peripherals power domain, and it runs the program stored in RTC slow memory. RTC slow
memory will be powered on during sleep if this wakeup mode is requested. RTC peripherals will be automatically
powered on before ULP coprocessor starts running the program; once the program stops running, RTC peripherals
are automatically powered down again.
Revisions 0 and 1 of the ESP32 only support this wakeup mode when RTC peripherals are not forced to be powered
on (i.e. ESP_PD_DOMAIN_RTC_PERIPH should be set to ESP_PD_OPTION_AUTO).
esp_sleep_enable_ulp_wakeup() function can be used to enable this wakeup source.
GPIO wakeup (light sleep only) In addition to EXT0 and EXT1 wakeup sources described above, one more
method of wakeup from external inputs is available in light sleep mode. With this wakeup source, each pin can be
individually configured to trigger wakeup on high or low level using gpio_wakeup_enable() function. Unlike
EXT0 and EXT1 wakeup sources, which can only be used with RTC IOs, this wakeup source can be used with any
IO (RTC or digital).
esp_sleep_enable_gpio_wakeup() function can be used to enable this wakeup source.
Warning: Before entering light sleep mode, check if any GPIO pin to be driven is part of the VDD_SDIO
power domain. If so, this power domain must be configured to remain ON during sleep.

For example, on ESP32-WROOM-32 board, GPIO16 and GPIO17 are linked to VDD_SDIO power domain. If
they are configured to remain high during light sleep, the power domain should be configured to remain powered
ON. This can be done with esp_sleep_pd_config():
esp_sleep_pd_config(ESP_PD_DOMAIN_VDDSDIO, ESP_PD_OPTION_ON);
UART wakeup (light sleep only) When ESP32 receives UART input from external devices, it is often required to
wake up the chip when input data is available. UART peripheral contains a feature which allows waking up the chip
from light sleep when a certain number of positive edges on RX pin are seen. This number of positive edges can be
set using uart_set_wakeup_threshold() function. Note that the character which triggers wakeup (and any
characters before it) will not be received by the UART after wakeup. This means that the external device typically
needs to send an extra character to the ESP32 to trigger wakeup, before sending the data.
esp_sleep_enable_uart_wakeup() function can be used to enable this wakeup source.
Power-down of RTC peripherals and memories
By default, esp_deep_sleep_start() and esp_light_sleep_start() functions will power down

all RTC power domains which are not needed by the enabled wakeup sources. To override this behaviour,
esp_sleep_pd_config() function is provided.
Note: in revision 0 of the ESP32, RTC fast memory will always be kept enabled in deep sleep, so that the deep sleep
stub can run after reset. This can be overridden, if the application doesn t need clean reset behaviour after deep
sleep.
If some variables in the program are placed into RTC slow memory (for example, using RTC_DATA_ATTR attribute),
RTC slow memory will be kept powered on by default. This can be overridden using esp_sleep_pd_config()
function, if desired.
Entering light sleep
esp_light_sleep_start() function can be used to enter light sleep once wakeup sources are configured. It
is also possible to go into light sleep with no wakeup sources configured, in this case the chip will be in light sleep
mode indefinitely, until external reset is applied.
Entering deep sleep
esp_deep_sleep_start() function can be used to enter deep sleep once wakeup sources are configured. It
is also possible to go into deep sleep with no wakeup sources configured, in this case the chip will be in deep sleep
mode indefinitely, until external reset is applied.
Configuring IOs
Some ESP32 IOs have internal pullups or pulldowns, which are enabled by default. If an external circuit drives this pin
in deep sleep mode, current consumption may increase due to current flowing through these pullups and pulldowns.
To isolate a pin, preventing extra current draw, call rtc_gpio_isolate() function.
For example, on ESP32-WROVER module, GPIO12 is pulled up externally. GPIO12 also has an internal pull-
down in the ESP32 chip. This means that in deep sleep, some current will flow through these external and in-
ternal resistors, increasing deep sleep current above the minimal possible value. Add the following code before
esp_deep_sleep_start() to remove this extra current:
rtc_gpio_isolate(GPIO_NUM_12);

UART output handling
Before entering sleep mode, esp_deep_sleep_start() will flush the contents of UART FIFOs.
When entering light sleep mode using esp_light_sleep_start(), UART FIFOs will not be flushed. Instead,
UART output will be suspended, and remaining characters in the FIFO will be sent out after wakeup from light sleep.
Checking sleep wakeup cause
esp_sleep_get_wakeup_cause() function can be used to check which wakeup source has triggered wakeup
from sleep mode.
For touch pad, it is possible to identify touch pad which has caused wakeup using
esp_sleep_get_touchpad_wakeup_status() functions.
For ext1 wakeup sources, it is possible to identify pin which has caused wakeup using
esp_sleep_get_ext1_wakeup_status() functions.
Disable sleep wakeup source
Previously configured wakeup source can be disabled later using esp_sleep_disable_wakeup_source()

API. This function deactivates trigger for the given wakeup source. Additionally it can disable all triggers if the
argument is ESP_SLEEP_WAKEUP_ALL.
Application Example
Implementation of basic functionality of deep sleep is shown in protocols/sntp example, where ESP module is peri-
odically waken up to retrieve time from NTP server.
More extensive example in system/deep_sleep illustrates usage of various deep sleep wakeup triggers and ULP co-
processor programming.
API Reference
Header File
• components/esp_hw_support/include/esp_sleep.h
Functions
esp_err_t esp_sleep_disable_wakeup_source(esp_sleep_source_t source)
Disable wakeup source.
This function is used to deactivate wake up trigger for source defined as parameter of the function.
See docs/sleep-modes.rst for details.
Note This function does not modify wake up configuration in RTC. It will be performed in esp_sleep_start
function.
Return
• ESP_ERR_INVALID_STATE if trigger was not active
Parameters
• source: - number of source to disable of type esp_sleep_source_t
esp_err_t esp_sleep_enable_ulp_wakeup(void)
Enable wakeup by ULP coprocessor.
Note In revisions 0 and 1 of the ESP32, ULP wakeup source cannot be used when RTC_PERIPH power
domain is forced to be powered on (ESP_PD_OPTION_ON) or when ext0 wakeup source is used.

Return
• ESP_ERR_NOT_SUPPORTED if additional current by touch (CON-
FIG_ESP32_RTC_EXT_CRYST_ADDIT_CURRENT) is enabled.
• ESP_ERR_INVALID_STATE if ULP co-processor is not enabled or if wakeup triggers conflict
esp_err_t esp_sleep_enable_timer_wakeup(uint64_t time_in_us)
Enable wakeup by timer.
Return
• ESP_ERR_INVALID_ARG if value is out of range (TBD)
Parameters
• time_in_us: time before wakeup, in microseconds
esp_err_t esp_sleep_enable_touchpad_wakeup(void)
Enable wakeup by touch sensor.
Note In revisions 0 and 1 of the ESP32, touch wakeup source can not be used when RTC_PERIPH power
domain is forced to be powered on (ESP_PD_OPTION_ON) or when ext0 wakeup source is used.
Note The FSM mode of the touch button should be configured as the timer trigger mode.
Return
• ESP_ERR_NOT_SUPPORTED if additional current by touch (CON-
FIG_ESP32_RTC_EXT_CRYST_ADDIT_CURRENT) is enabled.
• ESP_ERR_INVALID_STATE if wakeup triggers conflict
touch_pad_t esp_sleep_get_touchpad_wakeup_status(void)
Get the touch pad which caused wakeup.
If wakeup was caused by another source, this function will return TOUCH_PAD_MAX;
Return touch pad which caused wakeup
bool esp_sleep_is_valid_wakeup_gpio(gpio_num_t gpio_num)
Returns true if a GPIO number is valid for use as wakeup source.
Note For SoCs with RTC IO capability, this can be any valid RTC IO input pin.
Return True if this GPIO number will be accepted as a sleep wakeup source.
Parameters
• gpio_num: Number of the GPIO to test for wakeup source capability
esp_err_t esp_sleep_enable_ext0_wakeup(gpio_num_t gpio_num, int level)
Enable wakeup using a pin.
This function uses external wakeup feature of RTC_IO peripheral. It will work only if RTC peripherals are
kept on during sleep.
This feature can monitor any pin which is an RTC IO. Once the pin transitions into the state given by level
argument, the chip will be woken up.
Note This function does not modify pin configuration. The pin is configured in esp_sleep_start, immediately
before entering sleep mode.
Note In revisions 0 and 1 of the ESP32, ext0 wakeup source can not be used together with touch or ULP
wakeup sources.
Return
• ESP_ERR_INVALID_ARG if the selected GPIO is not an RTC GPIO, or the mode is invalid
Parameters
• gpio_num: GPIO number used as wakeup source. Only GPIOs which are have RTC functionality
can be used: 0,2,4,12-15,25-27,32-39.
• level: input level which will trigger wakeup (0=low, 1=high)

esp_err_t esp_sleep_enable_ext1_wakeup(uint64_t mask, esp_sleep_ext1_wakeup_mode_t mode)

Enable wakeup using multiple pins.
This function uses external wakeup feature of RTC controller. It will work even if RTC peripherals are shut
down during sleep.
This feature can monitor any number of pins which are in RTC IOs. Once any of the selected pins goes into
the state given by mode argument, the chip will be woken up.
Note This function does not modify pin configuration. The pins are configured in esp_sleep_start, immediately
before entering sleep mode.
Note Internal pullups and pulldowns don t work when RTC peripherals are shut down. In this case, external
resistors need to be added. Alternatively, RTC peripherals (and pullups/pulldowns) may be kept enabled
using esp_sleep_pd_config function.
Return
• ESP_ERR_INVALID_ARG if any of the selected GPIOs is not an RTC GPIO, or mode is invalid
Parameters
• mask: bit mask of GPIO numbers which will cause wakeup. Only GPIOs which have RTC func-
tionality can be used in this bit map: 0,2,4,12-15,25-27,32-39.
• mode: select logic function used to determine wakeup condition:
– ESP_EXT1_WAKEUP_ALL_LOW: wake up when all selected GPIOs are low
– ESP_EXT1_WAKEUP_ANY_HIGH: wake up when any of the selected GPIOs is high
esp_err_t esp_sleep_enable_gpio_wakeup(void)
Enable wakeup from light sleep using GPIOs.
Each GPIO supports wakeup function, which can be triggered on either low level or high level. Unlike EXT0
and EXT1 wakeup sources, this method can be used both for all IOs: RTC IOs and digital IOs. It can only be
used to wakeup from light sleep though.
To enable wakeup, first call gpio_wakeup_enable, specifying gpio number and wakeup level, for each GPIO
which is used for wakeup. Then call this function to enable wakeup feature.
Note In revisions 0 and 1 of the ESP32, GPIO wakeup source can not be used together with touch or ULP
wakeup sources.
Return
esp_err_t esp_sleep_enable_uart_wakeup(int uart_num)
Enable wakeup from light sleep using UART.
Use uart_set_wakeup_threshold function to configure UART wakeup threshold.
Wakeup from light sleep takes some time, so not every character sent to the UART can be received by the
application.
Note ESP32 does not support wakeup from UART2.
Return
• ESP_ERR_INVALID_ARG if wakeup from given UART is not supported
Parameters
• uart_num: UART port to wake up from
esp_err_t esp_sleep_enable_wifi_wakeup(void)
Enable wakeup by WiFi MAC.
Return
esp_err_t esp_sleep_disable_wifi_wakeup(void)
Disable wakeup by WiFi MAC.
Return

uint64_t esp_sleep_get_ext1_wakeup_status(void)
Get the bit mask of GPIOs which caused wakeup (ext1)
If wakeup was caused by another source, this function will return 0.
Return bit mask, if GPIOn caused wakeup, BIT(n) will be set
esp_err_t esp_sleep_pd_config(esp_sleep_pd_domain_t domain, esp_sleep_pd_option_t option)
Set power down mode for an RTC power domain in sleep mode.
If not set set using this API, all power domains default to ESP_PD_OPTION_AUTO.
Return
• ESP_ERR_INVALID_ARG if either of the arguments is out of range
Parameters
• domain: power domain to configure
• option: power down option (ESP_PD_OPTION_OFF, ESP_PD_OPTION_ON, or
ESP_PD_OPTION_AUTO)
void esp_deep_sleep_start(void)
Enter deep sleep with the configured wakeup options.
This function does not return.
esp_err_t esp_light_sleep_start(void)
Enter light sleep with the configured wakeup options.
Return
• ESP_OK on success (returned after wakeup)
• ESP_ERR_INVALID_STATE if WiFi or BT is not stopped
void esp_deep_sleep(uint64_t time_in_us)
Enter deep-sleep mode.
The device will automatically wake up after the deep-sleep time Upon waking up, the device calls deep sleep
wake stub, and then proceeds to load application.
Call to this function is equivalent to a call to esp_deep_sleep_enable_timer_wakeup followed by a call to
esp_deep_sleep_start.
esp_deep_sleep does not shut down WiFi, BT, and higher level protocol connections gracefully. Make sure
relevant WiFi and BT stack functions are called to close any connections and deinitialize the peripherals. These
include:
• esp_bluedroid_disable
• esp_bt_controller_disable
• esp_wifi_stop
This function does not return.
Note The device will wake up immediately if the deep-sleep time is set to 0
Parameters
• time_in_us: deep-sleep time, unit: microsecond
esp_sleep_wakeup_cause_t esp_sleep_get_wakeup_cause(void)
Get the wakeup source which caused wakeup from sleep.
Return cause of wake up from last sleep (deep sleep or light sleep)
void esp_wake_deep_sleep(void)
Default stub to run on wake from deep sleep.
Allows for executing code immediately on wake from sleep, before the software bootloader or ESP-IDF app
has started up.
This function is weak-linked, so you can implement your own version to run code immediately when the chip
wakes from sleep.

See docs/deep-sleep-stub.rst for details.

void esp_set_deep_sleep_wake_stub(esp_deep_sleep_wake_stub_fn_t new_stub)
Install a new stub at runtime to run on wake from deep sleep.
If implementing esp_wake_deep_sleep() then it is not necessary to call this function.
However, it is possible to call this function to substitute a different deep sleep stub. Any function
used as a deep sleep stub must be marked RTC_IRAM_ATTR, and must obey the same rules given for
esp_wake_deep_sleep().
esp_deep_sleep_wake_stub_fn_t esp_get_deep_sleep_wake_stub(void)
Get current wake from deep sleep stub.
Return Return current wake from deep sleep stub, or NULL if no stub is installed.
void esp_default_wake_deep_sleep(void)
The default esp-idf-provided esp_wake_deep_sleep() stub.
See docs/deep-sleep-stub.rst for details.
void esp_deep_sleep_disable_rom_logging(void)
Disable logging from the ROM code after deep sleep.
Using LSB of RTC_STORE4.
void esp_sleep_config_gpio_isolate(void)
Configure to isolate all GPIO pins in sleep state.
void esp_sleep_enable_gpio_switch(bool enable)
Enable or disable GPIO pins status switching between slept status and waked status.
Parameters
• enable: decide whether to switch status or not
Type Definitions
typedef esp_sleep_source_t esp_sleep_wakeup_cause_t
typedef void (*esp_deep_sleep_wake_stub_fn_t)(void)
Function type for stub to run on wake from sleep.
Enumerations
enum esp_sleep_ext1_wakeup_mode_t
Logic function used for EXT1 wakeup mode.
Values:
ESP_EXT1_WAKEUP_ALL_LOW = 0
Wake the chip when all selected GPIOs go low.
ESP_EXT1_WAKEUP_ANY_HIGH = 1
Wake the chip when any of the selected GPIOs go high.
enum esp_sleep_pd_domain_t
Power domains which can be powered down in sleep mode.
Values:
ESP_PD_DOMAIN_RTC_PERIPH
RTC IO, sensors and ULP co-processor.
ESP_PD_DOMAIN_RTC_SLOW_MEM
RTC slow memory.
ESP_PD_DOMAIN_RTC_FAST_MEM
RTC fast memory.
ESP_PD_DOMAIN_XTAL
XTAL oscillator.

ESP_PD_DOMAIN_RTC8M
Internal 8M oscillator.
ESP_PD_DOMAIN_VDDSDIO
VDD_SDIO.
ESP_PD_DOMAIN_MAX
Number of domains.
enum esp_sleep_pd_option_t
Power down options.
Values:
ESP_PD_OPTION_OFF
Power down the power domain in sleep mode.
ESP_PD_OPTION_ON
Keep power domain enabled during sleep mode.
ESP_PD_OPTION_AUTO
Keep power domain enabled in sleep mode, if it is needed by one of the wakeup options. Otherwise
power it down.
enum esp_sleep_source_t
Sleep wakeup cause.
Values:
ESP_SLEEP_WAKEUP_UNDEFINED
In case of deep sleep, reset was not caused by exit from deep sleep.
ESP_SLEEP_WAKEUP_ALL
Not a wakeup cause, used to disable all wakeup sources with esp_sleep_disable_wakeup_source.
ESP_SLEEP_WAKEUP_EXT0
Wakeup caused by external signal using RTC_IO.
ESP_SLEEP_WAKEUP_EXT1
Wakeup caused by external signal using RTC_CNTL.
ESP_SLEEP_WAKEUP_TIMER
Wakeup caused by timer.
ESP_SLEEP_WAKEUP_TOUCHPAD
Wakeup caused by touchpad.
ESP_SLEEP_WAKEUP_ULP
Wakeup caused by ULP program.
ESP_SLEEP_WAKEUP_GPIO
Wakeup caused by GPIO (light sleep only)
ESP_SLEEP_WAKEUP_UART
Wakeup caused by UART (light sleep only)
ESP_SLEEP_WAKEUP_WIFI
Wakeup caused by WIFI (light sleep only)
ESP_SLEEP_WAKEUP_COCPU
Wakeup caused by COCPU int.
ESP_SLEEP_WAKEUP_COCPU_TRAP_TRIG
Wakeup caused by COCPU crash.
ESP_SLEEP_WAKEUP_BT
Wakeup caused by BT (light sleep only)

2.7.25 Watchdogs
Overview
The ESP-IDF has support for multiple types of watchdogs, with the two main ones being: The Interrupt Watchdog
Timer and the Task Watchdog Timer (TWDT). The Interrupt Watchdog Timer and the TWDT can both be enabled
using Project Configuration Menu, however the TWDT can also be enabled during runtime. The Interrupt Watchdog
is responsible for detecting instances where FreeRTOS task switching is blocked for a prolonged period of time. The
TWDT is responsible for detecting instances of tasks running without yielding for a prolonged period.
Interrupt watchdog The interrupt watchdog makes sure the FreeRTOS task switching interrupt isn t blocked for
a long time. This is bad because no other tasks, including potentially important ones like the WiFi task and the idle
task, can t get any CPU runtime. A blocked task switching interrupt can happen because a program runs into an
infinite loop with interrupts disabled or hangs in an interrupt.
The default action of the interrupt watchdog is to invoke the panic handler. causing a register dump and an opportunity
for the programmer to find out, using either OpenOCD or gdbstub, what bit of code is stuck with interrupts disabled.
Depending on the configuration of the panic handler, it can also blindly reset the CPU, which may be preferred in a
production environment.
The interrupt watchdog is built around the hardware watchdog in timer group 1. If this watchdog for some reason
cannot execute the NMI handler that invokes the panic handler (e.g. because IRAM is overwritten by garbage), it
will hard-reset the SOC. If the panic handler executes, it will display the panic reason as Interrupt wdt timeout on
CPU0 or Interrupt wdt timeout on CPU1 (as applicable).
Configuration The interrupt watchdog is enabled by default via the CONFIG_ESP_INT_WDT configuration flag.
The timeout is configured by setting CONFIG_ESP_INT_WDT_TIMEOUT_MS. The default timeout is higher if
PSRAM support is enabled, as a critical section or interrupt routine that accesses a large amount of PSRAM will take
longer to complete in some circumstances. The INT WDT timeout should always be longer than the period between
FreeRTOS ticks (see CONFIG_FREERTOS_HZ).
Tuning If you find the Interrupt watchdog timeout is triggering because an interrupt or critical section is running
longer than the timeout period, consider rewriting the code: critical sections should be made as short as possible, with
non-critical computation happening outside the critical section. Interrupt handlers should also perform the minimum
possible amount of computation, consider pushing data into a queue from the ISR and processing it in a task instead.
Neither critical sections or interrupt handlers should ever block waiting for another event to occur.
If changing the code to reduce the processing time is not possible or desirable, it s possible to increase the CON-
FIG_ESP_INT_WDT_TIMEOUT_MS setting instead.
Task Watchdog Timer The Task Watchdog Timer (TWDT) is responsible for detecting instances of tasks running
for a prolonged period of time without yielding. This is a symptom of CPU starvation and is usually caused by a
higher priority task looping without yielding to a lower-priority task thus starving the lower priority task from CPU
time. This can be an indicator of poorly written code that spinloops on a peripheral, or a task that is stuck in an
infinite loop.
By default the TWDT will watch the Idle Tasks of each CPU, however any task can subscribe to be watched by the
TWDT. Each watched task must reset the TWDT periodically to indicate that they have been allocated CPU time.
If a task does not reset within the TWDT timeout period, a warning will be printed with information about which
tasks failed to reset the TWDT in time and which tasks are currently running.
It is also possible to redefine the function esp_task_wdt_isr_user_handler in the user code, in order to receive the
timeout event and handle it differently.
The TWDT is built around the Hardware Watchdog Timer in Timer Group 0. The TWDT can be initial-
ized by calling esp_task_wdt_init() which will configure the hardware timer. A task can then subscribe
to the TWDT using esp_task_wdt_add() in order to be watched. Each subscribed task must periodi-
cally call esp_task_wdt_reset() to reset the TWDT. Failure by any subscribed tasks to periodically call

esp_task_wdt_reset() indicates that one or more tasks have been starved of CPU time or are stuck in a loop
somewhere.
A watched task can be unsubscribed from the TWDT using esp_task_wdt_delete(). A task that has been
unsubscribed should no longer call esp_task_wdt_reset(). Once all tasks have unsubscribed form the TWDT,
the TWDT can be deinitialized by calling esp_task_wdt_deinit().
The default timeout period for the TWDT is set using config item CONFIG_ESP_TASK_WDT_TIMEOUT_S. This
should be set to at least as long as you expect any single task will need to monopolise the CPU (for example, if you
expect the app will do a long intensive calculation and should not yield to other tasks). It is also possible to change
this timeout at runtime by calling esp_task_wdt_init().
The following config options control TWDT configuration at startup. They are all enabled by default:
• CONFIG_ESP_TASK_WDT - the TWDT is initialized automatically during startup. If this option is disabled,
it is still possible to initialize the Task WDT at runtime by calling esp_task_wdt_init().
• CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0 - CPU0 Idle task is subscribed to the TWDT
during startup. If this option is disabled, it is still possible to subscribe the idle task by calling
esp_task_wdt_add() at any time.
• CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1 - CPU1 Idle task is subscribed to the TWDT during
startup.
JTAG and watchdogs While debugging using OpenOCD, the CPUs will be halted every time a breakpoint is
reached. However if the watchdog timers continue to run when a breakpoint is encountered, they will eventually
trigger a reset making it very difficult to debug code. Therefore OpenOCD will disable the hardware timers of both
the interrupt and task watchdogs at every breakpoint. Moreover, OpenOCD will not reenable them upon leaving
the breakpoint. This means that interrupt watchdog and task watchdog functionality will essentially be disabled. No
warnings or panics from either watchdogs will be generated when the ESP32 is connected to OpenOCD via JTAG.
Interrupt Watchdog API Reference
Header File
• esp_system/include/esp_int_wdt.h
Functions
void esp_int_wdt_init(void)
Initialize the non-CPU-specific parts of interrupt watchdog. This is called in the init code if the interrupt
watchdog is enabled in menuconfig.
Task Watchdog API Reference
A full example using the Task Watchdog is available in esp-idf: system/task_watchdog
Header File
• components/esp_system/include/esp_task_wdt.h
Functions
esp_err_t esp_task_wdt_init(uint32_t timeout, bool panic)
Initialize the Task Watchdog Timer (TWDT)
This function configures and initializes the TWDT. If the TWDT is already initialized when this function is
called, this function will update the TWDT s timeout period and panic configurations instead. After initializing
the TWDT, any task can elect to be watched by the TWDT by subscribing to it using esp_task_wdt_add().
Return

• ESP_OK: Initialization was successful

• ESP_ERR_NO_MEM: Initialization failed due to lack of memory
Note esp_task_wdt_init() must only be called after the scheduler started
Parameters
• [in] timeout: Timeout period of TWDT in seconds
• [in] panic: Flag that controls whether the panic handler will be executed when the TWDT
times out
esp_err_t esp_task_wdt_deinit(void)
Deinitialize the Task Watchdog Timer (TWDT)
This function will deinitialize the TWDT. Calling this function whilst tasks are still subscribed to the TWDT,
or when the TWDT is already deinitialized, will result in an error code being returned.
Return
• ESP_OK: TWDT successfully deinitialized
• ESP_ERR_INVALID_STATE: Error, tasks are still subscribed to the TWDT
• ESP_ERR_NOT_FOUND: Error, TWDT has already been deinitialized
esp_err_t esp_task_wdt_add(TaskHandle_t handle)
Subscribe a task to the Task Watchdog Timer (TWDT)
This function subscribes a task to the TWDT. Each subscribed task must periodically call esp_task_wdt_reset()
to prevent the TWDT from elapsing its timeout period. Failure to do so will result in a TWDT timeout. If the
task being subscribed is one of the Idle Tasks, this function will automatically enable esp_task_wdt_reset() to
called from the Idle Hook of the Idle Task. Calling this function whilst the TWDT is uninitialized or attempting
to subscribe an already subscribed task will result in an error code being returned.
Return
• ESP_OK: Successfully subscribed the task to the TWDT
• ESP_ERR_INVALID_ARG: Error, the task is already subscribed
• ESP_ERR_NO_MEM: Error, could not subscribe the task due to lack of memory
• ESP_ERR_INVALID_STATE: Error, the TWDT has not been initialized yet
Parameters
• [in] handle: Handle of the task. Input NULL to subscribe the current running task to the
TWDT
esp_err_t esp_task_wdt_reset(void)
Reset the Task Watchdog Timer (TWDT) on behalf of the currently running task.
This function will reset the TWDT on behalf of the currently running task. Each subscribed task must pe-
riodically call this function to prevent the TWDT from timing out. If one or more subscribed tasks fail to
reset the TWDT on their own behalf, a TWDT timeout will occur. If the IDLE tasks have been subscribed to
the TWDT, they will automatically call this function from their idle hooks. Calling this function from a task
that has not subscribed to the TWDT, or when the TWDT is uninitialized will result in an error code being
returned.
Return
• ESP_OK: Successfully reset the TWDT on behalf of the currently running task
• ESP_ERR_NOT_FOUND: Error, the current running task has not subscribed to the TWDT
esp_err_t esp_task_wdt_delete(TaskHandle_t handle)
Unsubscribes a task from the Task Watchdog Timer (TWDT)
This function will unsubscribe a task from the TWDT. After being unsubscribed, the task should no longer
call esp_task_wdt_reset(). If the task is an IDLE task, this function will automatically disable the calling of
esp_task_wdt_reset() from the Idle Hook. Calling this function whilst the TWDT is uninitialized or attempting
to unsubscribe an already unsubscribed task from the TWDT will result in an error code being returned.
Return
• ESP_OK: Successfully unsubscribed the task from the TWDT
• ESP_ERR_INVALID_ARG: Error, the task is already unsubscribed
Parameters

• [in] handle: Handle of the task. Input NULL to unsubscribe the current running task.
esp_err_t esp_task_wdt_status(TaskHandle_t handle)
Query whether a task is subscribed to the Task Watchdog Timer (TWDT)
This function will query whether a task is currently subscribed to the TWDT, or whether the TWDT is initial-
ized.
Return :
• ESP_OK: The task is currently subscribed to the TWDT
• ESP_ERR_NOT_FOUND: The task is currently not subscribed to the TWDT
• ESP_ERR_INVALID_STATE: The TWDT is not initialized, therefore no tasks can be subscribed
Parameters
• [in] handle: Handle of the task. Input NULL to query the current running task.
2.7.26 System Time
Overview
System time can be kept using either one time source or two time sources simultaneously. The choice depends on the
application purpose and accuracy requirements for system time.
There are the following two time sources:
• RTC timer: Allows keeping the system time during any resets and sleep modes, only the power-up reset leads
to resetting the RTC timer. The frequency deviation depends on an RTC Clock Source and affects accuracy
only in sleep modes, in which case the time will be measured at 6.6667 us resolution.
• High-resolution timer: Not available during any reset and sleep modes. The reason for using this timer is
to achieve greater accuracy. It uses the APB_CLK clock source (typically 80 MHz), which has a frequency
deviation of less than ±10 ppm. Time will be measured at 1 us resolution.
The settings for the system time source are as follows:
• RTC and high-resolution timer (default)
• RTC
• High-resolution timer
• None
It is recommended to stick to the default setting which provides maximum accuracy. If you want to choose a different
timer, configure CONFIG_ESP32_TIME_SYSCALL in project configuration.
RTC Clock Source
The RTC timer has the following clock sources:

• Internal 150kHz RC oscillator (default): Features lowest deep sleep current consumption and no
dependence on any external components. However, as frequency stability is affected by temperature fluctua-
tions, time may drift in both Deep and Light sleep modes.
• External 32kHz crystal: Requires a 32kHz crystal to be connected to the 32K_XP and 32K_XN pins.
Provides better frequency stability at the expense of slightly higher (by 1 uA) Deep sleep current consumption.
• External 32kHz oscillator at 32K_XN pin: Allows using 32kHz clock generated by an external
circuit. The external clock signal must be connected to the 32K_XN pin. The amplitude should be less than
1.2 V for sine wave signal and less than 1 V for square wave signal. Common mode voltage should be in the
range of 0.1 < Vcm < 0.5xVamp, where Vamp is signal amplitude. Additionally, a 1 nF capacitor must be
placed between the 32K_XP pin and ground. In this case, the 32K_XP pin cannot be used as a GPIO pin.
• Internal 8.5MHz oscillator, divided by 256 (~33kHz): Provides better frequency
stability than the internal 150kHz RC oscillator at the expense of higher (by 5 uA) deep sleep
current consumption. It also does not require external components.
The choice depends on your requirements for system time accuracy and power consumption in sleep modes. To
modify the RTC clock source, set CONFIG_ESP32_RTC_CLK_SRC in project configuration.

More details on wiring requirements for the External 32kHz crystal and External 32kHz os-
cillator at 32K_XN pin sources can be found in Section Crystal Oscillator of ESP32 Hardware Design
Guidelines.
Get Current Time
To get the current time, use the POSIX function gettimeofday(). Additionally, you can use the following
standard C library functions to obtain time and manipulate it:
gettimeofday
time
asctime
clock
ctime
difftime
gmtime
localtime
mktime
strftime
adjtime*
* To stop smooth time adjustment and update the current time immediately, use the POSIX function settime-
ofday().
If you need to obtain time with one second resolution, use the following method:
time_t now;
char strftime_buf[64];
struct tm timeinfo;
time(&now);
// Set timezone to China Standard Time
setenv("TZ", "CST-8", 1);
tzset();
localtime_r(&now, &timeinfo);
strftime(strftime_buf, sizeof(strftime_buf), "%c", &timeinfo);
ESP_LOGI(TAG, "The current date/time in Shanghai is: %s", strftime_buf);
If you need to obtain time with one microsecond resolution, use the code snippet below:
struct timeval tv_now;

gettimeofday(&tv_now, NULL);
int64_t time_us = (int64_t)tv_now.tv_sec * 1000000L + (int64_t)tv_now.tv_usec;
SNTP Time Synchronization
To set the current time, you can use the POSIX functions settimeofday() and adjtime(). They are used
internally in the lwIP SNTP library to set current time when a response from the NTP server is received. These
functions can also be used separately from the lwIP SNTP library.
A function to use inside the lwIP SNTP library depends on a sync mode for system time. Use the function
sntp_set_sync_mode() to set one of the following sync modes:
• SNTP_SYNC_MODE_IMMED (default) updates system time immediately upon receiving a response from the
SNTP server after using settimeofday().
• SNTP_SYNC_MODE_SMOOTH updates time smoothly by gradually reducing time error using the funcion
adjtime(). If the difference between the SNTP response time and system time is more than 35 minutes,
update system time immediately by using settimeofday().

The lwIP SNTP library has API functions for setting a callback function for a certain event. You might need the
following functions:
• sntp_set_time_sync_notification_cb() - use it for setting a callback function that will notify
of the time synchronization process
• sntp_get_sync_status() and sntp_set_sync_status() - use it to get/set time synchronization
status
To start synchronization via SNTP, just call the following three functions.
sntp_setoperatingmode(SNTP_OPMODE_POLL);
sntp_setservername(0, "pool.ntp.org");
sntp_init();
An application with this initialization code will periodically synchronize the time. The time synchronization period is
determined by CONFIG_LWIP_SNTP_UPDATE_DELAY (default value is one hour). To modify the variable, set
CONFIG_LWIP_SNTP_UPDATE_DELAY in project configuration.
A code example that demonstrates the implementation of time synchronization based on the lwIP SNTP library is
provided in protocols/sntp directory.
Timezones
To set local timezone, use the following POSIX functions:

1. Call setenv() to set the TZ environment variable to the correct value depending on the device location. The
format of the time string is the same as described in the GNU libc documentation (although the implementation
is different).
2. Call tzset() to update C library runtime data for the new time zone.
Once these steps are completed, call the standard C library function localtime(), and it will return correct local
time taking into account the time zone offset and daylight saving time.
API Reference
Header File
• components/lwip/include/apps/esp_sntp.h
Functions
void sntp_sync_time(struct timeval *tv)
This function updates the system time.
This is a weak-linked function. It is possible to replace all SNTP update functionality by placing a
sntp_sync_time() function in the app firmware source. If the default implementation is used, calling
sntp_set_sync_mode() allows the time synchronization mode to be changed to instant or smooth. If a callback
function is registered via sntp_set_time_sync_notification_cb(), it will be called following time synchroniza-
tion.
Parameters
• tv: Time received from SNTP server.
void sntp_set_sync_mode(sntp_sync_mode_t sync_mode)
Set the sync mode.
Allowable two mode: SNTP_SYNC_MODE_IMMED and SNTP_SYNC_MODE_SMOOTH.
Parameters
• sync_mode: Sync mode.
sntp_sync_mode_t sntp_get_sync_mode(void)
Get set sync mode.

Return SNTP_SYNC_MODE_IMMED: Update time immediately. SNTP_SYNC_MODE_SMOOTH:

Smooth time updating.
sntp_sync_status_t sntp_get_sync_status(void)
Get status of time sync.
After the update is completed, the status will be returned as SNTP_SYNC_STATUS_COMPLETED. After
that, the status will be reset to SNTP_SYNC_STATUS_RESET. If the update operation is not completed yet,
the status will be SNTP_SYNC_STATUS_RESET. If a smooth mode was chosen and the synchronization is
still continuing (adjtime works), then it will be SNTP_SYNC_STATUS_IN_PROGRESS.
Return SNTP_SYNC_STATUS_RESET: Reset status. SNTP_SYNC_STATUS_COMPLETED: Time is
synchronized. SNTP_SYNC_STATUS_IN_PROGRESS: Smooth time sync in progress.
void sntp_set_sync_status(sntp_sync_status_t sync_status)
Set status of time sync.
Parameters
• sync_status: status of time sync (see sntp_sync_status_t)
void sntp_set_time_sync_notification_cb(sntp_sync_time_cb_t callback)
Set a callback function for time synchronization notification.
Parameters
• callback: a callback function
void sntp_set_sync_interval(uint32_t interval_ms)
Set the sync interval of SNTP operation.
Note: SNTPv4 RFC 4330 enforces a minimum sync interval of 15 seconds. This sync interval will be used in
the next attempt update time throught SNTP. To apply the new sync interval call the sntp_restart() function,
otherwise, it will be applied after the last interval expired.
Parameters
• interval_ms: The sync interval in ms. It cannot be lower than 15 seconds, otherwise 15 seconds
will be set.
uint32_t sntp_get_sync_interval(void)
Get the sync interval of SNTP operation.
Return the sync interval
bool sntp_restart(void)
Restart SNTP.
Return True - Restart False - SNTP was not initialized yet
Type Definitions
typedef void (*sntp_sync_time_cb_t)(struct timeval *tv)
SNTP callback function for notifying about time sync event.
Parameters
• tv: Time received from SNTP server.
Enumerations
enum sntp_sync_mode_t
SNTP time update mode.
Values:
SNTP_SYNC_MODE_IMMED
Update system time immediately when receiving a response from the SNTP server.
SNTP_SYNC_MODE_SMOOTH
Smooth time updating. Time error is gradually reduced using adjtime function. If the difference between
SNTP response time and system time is large (more than 35 minutes) then update immediately.

enum sntp_sync_status_t
SNTP sync status.
Values:
SNTP_SYNC_STATUS_RESET
SNTP_SYNC_STATUS_COMPLETED
SNTP_SYNC_STATUS_IN_PROGRESS
2.7.27 Internal and Unstable APIs
This section is listing some APIs that are internal or likely to be changed or removed in the next releases of ESP-IDF.
API Reference
Header File
• components/esp_rom/include/esp_rom_sys.h
Functions
int esp_rom_printf(const char *fmt, ...)
Print formated string to console device.
Note float and long long data are not supported!
Return int: Total number of characters written on success; A negative number on failure.
Parameters
• fmt: Format string
• ...: Additional arguments, depending on the format string
void esp_rom_delay_us(uint32_t us)
Pauses execution for us microseconds.
Parameters
• us: Number of microseconds to pause
void esp_rom_install_channel_putc(int channel, void (*putc))char c
esp_rom_printf can print message to different channels simultaneously. This function can help install the low
level putc function for esp_rom_printf.
Parameters
• channel: Channel number (startting from 1)
• putc: Function pointer to the putc implementation. Set NULL can disconnect esp_rom_printf
with putc.
void esp_rom_install_uart_printf(void)
Install UART1 as the default console channel, equivalent to esp_rom_install_channel_putc(1,
esp_rom_uart_putc)
soc_reset_reason_t esp_rom_get_reset_reason(int cpu_no)
Get reset reason of CPU.
Return Reset reason code (see in soc/reset_reasons.h)
Parameters
• cpu_no: CPU number
Code examples for this API section are provided in the system directory of ESP-IDF examples.

2.8 API Conventions

This document describes conventions and assumptions common to ESP-IDF Application Programming Interfaces
(APIs).
ESP-IDF provides several kinds of programming interfaces:
• C functions, structures, enums, type definitions and preprocessor macros declared in public header files of ESP-
IDF components. Various pages in the API Reference section of the programming guide contain descriptions
of these functions, structures and types.
• Build system functions, predefined variables and options. These are documented in the build system guide.
• Kconfig options can can be used in code and in the build system (CMakeLists.txt) files.
• Host tools and their command line parameters are also part of ESP-IDF interface.
ESP-IDF consists of components written specifically for ESP-IDF as well as third-party libraries. In some cases, an
ESP-IDF-specific wrapper is added to the third-party library, providing an interface that is either simpler or better
integrated with the rest of ESP-IDF facilities. In other cases, the original API of the third-party library is presented
to the application developers.
Following sections explain some of the aspects of ESP-IDF APIs and their usage.
2.8.1 Error handling
Most ESP-IDF APIs return error codes defined with esp_err_t type. See Error Handling section for more infor-
mation about error handling approaches. Error Code Reference contains the list of error codes returned by ESP-IDF
components.
2.8.2 Configuration structures
Important: Correct initialization of configuration structures is an important part in making the application com-
patible with future versions of ESP-IDF.
Most initialization or configuration functions in ESP-IDF take as an argument a pointer to a configuration structure.
For example:
const esp_timer_create_args_t my_timer_args = {

.callback = &my_timer_callback,
.arg = callback_arg,
.name = "my_timer"
};
esp_timer_handle_t my_timer;
esp_err_t err = esp_timer_create(&my_timer_args, &my_timer);
Initialization functions never store the pointer to the configuration structure, so it is safe to allocate the structure on
the stack.
The application must initialize all fields of the structure. The following is incorrect:
esp_timer_create_args_t my_timer_args;
my_timer_args.callback = &my_timer_callback;
/* Incorrect! Fields .arg and .name are not initialized */
esp_timer_create(&my_timer_args, &my_timer);
Most ESP-IDF examples use C99 designated initializers for structure initialization, since they provide a concise way
of setting a subset of fields, and zero-initializing the remaining fields:

const esp_timer_create_args_t my_timer_args = {

.callback = &my_timer_callback,
/* Correct, fields .arg and .name are zero-initialized */
};
C++ language doesn t support the designated initializers syntax until C++20, however GCC compiler partially
supports it as an extension. When using ESP-IDF APIs in C++ code, you may consider using the following pattern:
esp_timer_create_args_t my_timer_args = {};

/* All the fields are zero-initialized */
my_timer_args.callback = &my_timer_callback;
Default initializers
For some configuration structures, ESP-IDF provides macros for setting default values of fields:

/* HTTPD_DEFAULT_CONFIG expands to a designated initializer.
Now all fields are set to the default values.
Any field can still be modified: */
config.server_port = 8081;
httpd_handle_t server;
esp_err_t err = httpd_start(&server, &config);
It is recommended to use default initializer macros whenever they are provided for a particular configuration structure.
2.8.3 Private APIs
Certain header files in ESP-IDF contain APIs intended to be used only in ESP-IDF source code, and not by the appli-
cations. Such header files often contain private or esp_private in their name or path. Certain components,
such as hal only contain private APIs.
Private APIs may be removed or changed in an incompatible way between minor or patch releases.
2.8.4 Components in example projects
ESP-IDF examples contain a variety of projects demonstrating usage of ESP-IDF APIs. In order to reduce code
duplication in the examples, a few common helpers are defined inside components that are used by multiple examples.
This includes components located in common_components directory, as well as some of the components located in
the examples themselves. These components are not considered to be part of the ESP-IDF API.
It is not recommended to reference these components directly in custom projects (via EXTRA_COMPONENT_DIRS
build system variable), as they may change significantly between ESP-IDF versions. When starting a new project
based on an ESP-IDF example, copy both the project and the common components it depends on out of ESP-IDF,
and treat the common components as part of the project. Note that the common components are written with examples
in mind, and might not include all the error handling required for production applications. Take time to read the code
and understand if it applicable to your use case.
2.8.5 API Stability
ESP-IDF uses Semantic Versioning as explained in the versions page.

Minor and bugfix releases of ESP-IDF guarantee compatibility with previous releases. The sections below explain
different aspects and limitations to compatibility.

Source level compatibility
ESP-IDF guarantees source level compatibility of C functions, structures, enums, type definitions and preprocessor
macros declared in public header files of ESP-IDF components. Source level compatibility implies that the application
can be recompiled with the newer version of ESP-IDF without changes.
The following changes are allowed between minor versions and do not break source level compatibility:
• Deprecating functions (using the deprecated attribute) and header files (using a preprocessor #warning).
Deprecations are listed in ESP-IDF relese notes. It is recommended to update the source code to use the newer
functions or files that replace the deprecated ones, however this is not mandatory. Deprecated functions and
files can be removed in major versions of ESP-IDF.
• Renaming components, moving source and header files between components provided that the build system
ensures that correct files are still found.
• Renaming Kconfig options. Kconfig system renaming mechanism ensures that the original Kconfig option
names can still be used by the application in sdkconfig file, CMake files and source code.
Lack of binary compatibility
ESP-IDF does not guarantee binary compatibility between releases. This means that if a precompiled library is built
with one ESP-IDF version, it is not guaranteed to work the same way with the next minor or bugfix release. The
following are the possible changes that keep source level compatibility but not binary compatibility:
• Changing numerical values for C enum members.
• Adding new structure members or changing the order of members. See Configuration structures for tips that
help ensure compatibility.
• Replacing an extern function with a static inline one with the same signature, or vice versa.
• Replacing a function-like macro with a compatible C function.
Other exceptions from compatibility
While we try to make upgrading to a new ESP-IDF version easy, there are parts of ESP-IDF that may change between
minor versions in an incompatible way. We appreciate issue reports about any unintended breaking changes that don
t fall into the categories below.
• Private APIs.
• Components in example projects.
• Features clearly marked as beta , preview , or experimental .
• Changes made to mitigate security issues or to replace insecure default behaviors with a secure ones.
• Features which were never functional. For example, if it was never possible to use a certain function or an
enumeration value, it may get renamed (as part of fixing it) or removed. This includes software features which
depend on non-functional chip hardware features.
• Unexpected or undefined behavior (for example, due to missing validation of argument ranges) that is not
documented explicitly may be fixed/changed.
• Location of Kconfig options in menuconfig.
• Location and names of example projects.
2.9 Project Configuration
2.9.1 Introduction
ESP-IDF uses kconfiglib which is a Python-based extension to the Kconfig system which provides a compile-time
project configuration mechanism. Kconfig is based around options of several types: integer, string, boolean. Kconfig
files specify dependencies between options, default values of the options, the way the options are grouped together,
etc.
For the complete list of available features please see Kconfig and kconfiglib extentions.

2.9.2 Project Configuration Menu
Application developers can open a terminal-based project configuration menu with the idf.py menuconfig
build target.
After being updated, this configuration is saved inside sdkconfig file in the project root directory. Based on sd-
kconfig, application build targets will generate sdkconfig.h file in the build directory, and will make sdkconfig
options available to the project build system and source files.
2.9.3 Using sdkconfig.defaults
In some cases, such as when sdkconfig file is under revision control, the fact that sdkconfig file gets changed
by the build system may be inconvenient. The build system offers a way to avoid this, in the form of sdkconfig.
defaults file. This file is never touched by the build system, and must be created manually. It can contain all
the options which matter for the given application. The format is the same as that of the sdkconfig file. Once
sdkconfig.defaults is created, sdkconfig can be deleted and added to the ignore list of the revision control
system (e.g. .gitignore file for git). Project build targets will automatically create sdkconfig file, populated
with the settings from sdkconfig.defaults file, and the rest of the settings will be set to their default values.
Note that the build process will not override settings that are already in sdkconfig by ones from sdkconfig.
defaults. For more information, see Custom sdkconfig defaults.
2.9.4 Kconfig Formatting Rules
The following attributes of Kconfig files are standardized:

• Within any menu, option names should have a consistent prefix. The prefix length is currently set to at least 3
characters.
• The indentation style is 4 characters created by spaces. All sub-items belonging to a parent item are indented
by one level deeper. For example, menu is indented by 0 characters, the config inside of the menu by 4
characters, the help of the config by 8 characters and the text of the help by 12 characters.
• No trailing spaces are allowed at the end of the lines.
• The maximum length of options is set to 40 characters.
• The maximum length of lines is set to 120 characters.
• Lines cannot be wrapped by backslash (because there is a bug in earlier versions of conf-idf which causes
that Windows line endings are not recognized after a backslash).
Format checker
tools/check_kconfigs.py is provided for checking the Kconfig formatting rules. The checker checks all
Kconfig and Kconfig.projbuild files in the ESP-IDF directory and generates a new file with suffix .new
with some recommendations how to fix issues (if there are any). Please note that the checker cannot correct all
rules and the responsibility of the developer is to check and make final corrections in order to pass the tests. For
example, indentations will be corrected if there isn t some misleading previous formatting but it cannot come up
with a common prefix for options inside a menu.
2.9.5 Backward Compatibility of Kconfig Options
The standard Kconfig tools ignore unknown options in sdkconfig. So if a developer has custom settings for
options which are renamed in newer ESP-IDF releases then the given setting for the option would be silently ignored.
Therefore, several features have been adopted to avoid this:
1. confgen.py is used by the tool chain to pre-process sdkconfig files before anything else, for example
menuconfig, would read them. As the consequence, the settings for old options will be kept and not ignored.
2. confgen.py recursively finds all sdkconfig.rename files in ESP-IDF directory which contain old and
new Kconfig option names. Old options are replaced by new ones in the sdkconfig file.

3. confgen.py post-processes sdkconfig files and generates all build outputs (sdkconfig.h, sdkcon-
fig.cmake, auto.conf) by adding a list of compatibility statements, i.e. value of the old option is set
the value of the new option (after modification). This is done in order to not break customer codes where old
option might still be used.
4. Deprecated options and their replacements are automatically generated by confgen.py.
2.9.6 Configuration Options Reference
Subsequent sections contain the list of available ESP-IDF options, automatically generated from Kconfig files. Note
that depending on the options selected, some options listed here may not be visible by default in the interface of
menuconfig.
By convention, all option names are upper case with underscores. When Kconfig generates sdkconfig and sdkconfig.h
files, option names are prefixed with CONFIG_. So if an option ENABLE_FOO is defined in a Kconfig file and
selected in menuconfig, then sdkconfig and sdkconfig.h files will have CONFIG_ENABLE_FOO defined. In this
reference, option names are also prefixed with CONFIG_, same as in the source code.
SDK tool configuration
Contains:
• CONFIG_SDK_TOOLPREFIX
• CONFIG_SDK_TOOLCHAIN_SUPPORTS_TIME_WIDE_64_BITS
CONFIG_SDK_TOOLPREFIX
Compiler toolchain path/prefix
Found in: SDK tool configuration
The prefix/path that is used to call the toolchain. The default setting assumes a crosstool-ng gcc setup
that is in your PATH.
Default value:
• xtensa-esp32-elf-
CONFIG_SDK_TOOLCHAIN_SUPPORTS_TIME_WIDE_64_BITS
Toolchain supports time_t wide 64-bits
Found in: SDK tool configuration
Enable this option in case you have a custom toolchain which supports time_t wide 64-bits. This option
checks time_t is 64-bits and disables ROM time functions to use the time functions from the toolchain
instead. This option allows resolving the Y2K38 problem. See Setup Linux Toolchain from Scratch
to build a custom toolchain which supports 64-bits time_t.
Note: ESP-IDF does not currently come with any pre-compiled toolchain that supports 64-bit wide
time_t. This will change in a future major release, but currently 64-bit time_t requires a custom built
toolchain.
Default value:
• No (disabled)
Build type
Contains:
• CONFIG_APP_BUILD_TYPE
• CONFIG_APP_REPRODUCIBLE_BUILD

CONFIG_APP_BUILD_TYPE
Application build type
Found in: Build type
Select the way the application is built.
By default, the application is built as a binary file in a format compatible with the ESP-IDF bootloader.
In addition to this application, 2nd stage bootloader is also built. Application and bootloader binaries
can be written into flash and loaded/executed from there.
Another option, useful for only very small and limited applications, is to only link the .elf file of the
application, such that it can be loaded directly into RAM over JTAG. Note that since IRAM and DRAM
sizes are very limited, it is not possible to build any complex application this way. However for kinds of
testing and debugging, this option may provide faster iterations, since the application does not need to
be written into flash. Note that at the moment, ESP-IDF does not contain all the startup code required
to initialize the CPUs and ROM memory (data/bss). Therefore it is necessary to execute a bit of ROM
code prior to executing the application. A gdbinit file may look as follows (for ESP32):
# Connect to a running instance of OpenOCD target remote :3333 # Reset and halt the target
mon reset halt # Run to a specific point in ROM code, # where most of initialization is
complete. thb *0x40007d54 c # Load the application into RAM load # Run till app_main tb
app_main c
Execute this gdbinit file as follows:
xtensa-esp32-elf-gdb build/app-name.elf -x gdbinit
Example gdbinit files for other targets can be found in tools/test_apps/system/gdb_loadable_elf/
Recommended sdkconfig.defaults for building loadable ELF files is as follows. CON-
FIG_APP_BUILD_TYPE_ELF_RAM is required, other options help reduce application memory
footprint.
CONFIG_APP_BUILD_TYPE_ELF_RAM=y CONFIG_VFS_SUPPORT_TERMIOS=
CONFIG_NEWLIB_NANO_FORMAT=y CONFIG_ESP_SYSTEM_PANIC_PRINT_HALT=y
CONFIG_ESP_DEBUG_STUBS_ENABLE= CONFIG_ESP_ERR_TO_NAME_LOOKUP=
Available options:
• Default (binary application + 2nd stage bootloader)
(APP_BUILD_TYPE_APP_2NDBOOT)
• ELF file, loadable into RAM (EXPERIMENTAL)) (APP_BUILD_TYPE_ELF_RAM)
CONFIG_APP_REPRODUCIBLE_BUILD
Enable reproducible build
Found in: Build type
If enabled, all date, time, and path information would be eliminated. A .gdbinit file would be create
automatically. (or will be append if you have one already)
Default value:
• No (disabled)
Application manager
Contains:
• CONFIG_APP_EXCLUDE_PROJECT_NAME_VAR
• CONFIG_APP_EXCLUDE_PROJECT_VER_VAR
• CONFIG_APP_PROJECT_VER_FROM_CONFIG
• CONFIG_APP_RETRIEVE_LEN_ELF_SHA
• CONFIG_APP_COMPILE_TIME_DATE

CONFIG_APP_COMPILE_TIME_DATE
Use time/date stamp for app
Found in: Application manager
If set, then the app will be built with the current time/date stamp. It is stored in the app description
structure. If not set, time/date stamp will be excluded from app image. This can be useful for getting
the same binary image files made from the same source, but at different times.
Default value:
• Yes (enabled)
CONFIG_APP_EXCLUDE_PROJECT_VER_VAR
Exclude PROJECT_VER from firmware image
The PROJECT_VER variable from the build system will not affect the firmware image. This value will
not be contained in the esp_app_desc structure.
Default value:
• No (disabled)
CONFIG_APP_EXCLUDE_PROJECT_NAME_VAR
Exclude PROJECT_NAME from firmware image
The PROJECT_NAME variable from the build system will not affect the firmware image. This value
will not be contained in the esp_app_desc structure.
Default value:
• No (disabled)
CONFIG_APP_PROJECT_VER_FROM_CONFIG
Get the project version from Kconfig
If this is enabled, then config item APP_PROJECT_VER will be used for the variable PROJECT_VER.
Other ways to set PROJECT_VER will be ignored.
Default value:
• No (disabled)
CONFIG_APP_PROJECT_VER
Project version
Found in: Application manager > CONFIG_APP_PROJECT_VER_FROM_CONFIG
Project version
Default value:
• 1 if CONFIG_APP_PROJECT_VER_FROM_CONFIG

CONFIG_APP_RETRIEVE_LEN_ELF_SHA
The length of APP ELF SHA is stored in RAM(chars)
At startup, the app will read this many hex characters from the embedded APP ELF SHA-256 hash
value and store it in static RAM. This ensures the app ELF SHA-256 value is always available if it needs
to be printed by the panic handler code. Changing this value will change the size of a static buffer, in
bytes.
Range:
• from 8 to 64
Default value:
• 16
Bootloader config
Contains:
• CONFIG_BOOTLOADER_LOG_LEVEL
• CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION
• CONFIG_BOOTLOADER_SPI_WP_PIN
• CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE
• CONFIG_BOOTLOADER_FLASH_XMC_SUPPORT
• CONFIG_BOOTLOADER_APP_TEST
• CONFIG_BOOTLOADER_FACTORY_RESET
• CONFIG_BOOTLOADER_HOLD_TIME_GPIO
• CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC
• CONFIG_BOOTLOADER_SKIP_VALIDATE_ALWAYS
• CONFIG_BOOTLOADER_SKIP_VALIDATE_ON_POWER_ON
• CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP
• CONFIG_BOOTLOADER_SPI_CUSTOM_WP_PIN
• CONFIG_BOOTLOADER_WDT_ENABLE
• CONFIG_BOOTLOADER_VDDSDIO_BOOST
CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION
Bootloader optimization Level
Found in: Bootloader config
This option sets compiler optimization level (gcc -O argument) for the bootloader.
• The default Size setting will add the -0s flag to CFLAGS.
• The Debug setting will add the -Og flag to CFLAGS.
• The Performance setting will add the -O2 flag to CFLAGS.
• The None setting will add the -O0 flag to CFLAGS.
Note that custom optimization levels may be unsupported.
Available options:
• Size (-Os) (BOOTLOADER_COMPILER_OPTIMIZATION_SIZE)
• Debug (-Og) (BOOTLOADER_COMPILER_OPTIMIZATION_DEBUG)
• Optimize for performance (-O2) (BOOTLOADER_COMPILER_OPTIMIZATION_PERF)
• Debug without optimization (-O0) (BOOTLOADER_COMPILER_OPTIMIZATION_NONE)
CONFIG_BOOTLOADER_LOG_LEVEL
Bootloader log verbosity

Specify how much output to see in bootloader logs.

Available options:
• No output (BOOTLOADER_LOG_LEVEL_NONE)
• Error (BOOTLOADER_LOG_LEVEL_ERROR)
• Warning (BOOTLOADER_LOG_LEVEL_WARN)
• Info (BOOTLOADER_LOG_LEVEL_INFO)
• Debug (BOOTLOADER_LOG_LEVEL_DEBUG)
• Verbose (BOOTLOADER_LOG_LEVEL_VERBOSE)
CONFIG_BOOTLOADER_SPI_CUSTOM_WP_PIN
Use custom SPI Flash WP Pin when flash pins set in eFuse (read help)
This setting is only used if the SPI flash pins have been overridden by setting the eFuses
SPI_PAD_CONFIG_xxx, and the SPI flash mode is QIO or QOUT.
When this is the case, the eFuse config only defines 3 of the 4 Quad I/O data pins. The WP pin (aka
ESP32 pin SD_DATA_3 or SPI flash pin IO2 ) is not specified in eFuse. The same pin is also
used for external SPIRAM if it is enabled.
If this config item is set to N (default), the correct WP pin will be automatically used for any Espressif
chip or module with integrated flash. If a custom setting is needed, set this config item to Y and specify
the GPIO number connected to the WP.
Default value:
• No (disabled) if ESPTOOLPY_FLASHMODE_QIO || ESP-
TOOLPY_FLASHMODE_QOUT
CONFIG_BOOTLOADER_SPI_WP_PIN
Custom SPI Flash WP Pin
The option Use custom SPI Flash WP Pin must be set or this value is ignored
If burning a customized set of SPI flash pins in eFuse and using QIO or QOUT mode for flash, set this
value to the GPIO number of the SPI flash WP pin.
Range:
• from 0 to 33 if ESPTOOLPY_FLASHMODE_QIO || ESP-
TOOLPY_FLASHMODE_QOUT
Default value:
• 7 if ESPTOOLPY_FLASHMODE_QIO || ESPTOOLPY_FLASHMODE_QOUT
CONFIG_BOOTLOADER_VDDSDIO_BOOST
VDDSDIO LDO voltage
If this option is enabled, and VDDSDIO LDO is set to 1.8V (using eFuse or MTDI bootstrapping pin),
bootloader will change LDO settings to output 1.9V instead. This helps prevent flash chip from browning
out during flash programming operations.
This option has no effect if VDDSDIO is set to 3.3V, or if the internal VDDSDIO regulator is disabled
via eFuse.
Available options:
• 1.8V (BOOTLOADER_VDDSDIO_BOOST_1_8V)
• 1.9V (BOOTLOADER_VDDSDIO_BOOST_1_9V)

CONFIG_BOOTLOADER_FACTORY_RESET
GPIO triggers factory reset
Allows to reset the device to factory settings: - clear one or more data partitions; - boot from factory
partition. The factory reset will occur if there is a GPIO input held at the configured level while device
starts up. See settings below.
Default value:
• No (disabled)
CONFIG_BOOTLOADER_NUM_PIN_FACTORY_RESET
Number of the GPIO input for factory reset
Found in: Bootloader config > CONFIG_BOOTLOADER_FACTORY_RESET
The selected GPIO will be configured as an input with internal pull-up enabled (note that on some SoCs.
not all pins have an internal pull-up, consult the hardware datasheet for details.) To trigger a factory
reset, this GPIO must be held high or low (as configured) on startup.
Range:
• from 0 to 39 if CONFIG_BOOTLOADER_FACTORY_RESET
Default value:
• 4 if CONFIG_BOOTLOADER_FACTORY_RESET
CONFIG_BOOTLOADER_FACTORY_RESET_PIN_LEVEL
Factory reset GPIO level
Pin level for factory reset, can be triggered on low or high.
Available options:
• Reset on GPIO low (BOOTLOADER_FACTORY_RESET_PIN_LOW)
• Reset on GPIO high (BOOTLOADER_FACTORY_RESET_PIN_HIGH)
CONFIG_BOOTLOADER_OTA_DATA_ERASE
Clear OTA data on factory reset (select factory partition)
The device will boot from factory partition (or OTA slot 0 if no factory partition is present) after a
factory reset.
CONFIG_BOOTLOADER_DATA_FACTORY_RESET
Comma-separated names of partitions to clear on factory reset
Allows customers to select which data partitions will be erased while factory reset.
Specify the names of partitions as a comma-delimited with optional spaces for readability. (Like this:
nvs, phy_init, ) Make sure that the name specified in the partition table and here are the same.
Partitions of type app cannot be specified here.
Default value:
• nvs if CONFIG_BOOTLOADER_FACTORY_RESET

CONFIG_BOOTLOADER_APP_TEST
GPIO triggers boot from test app partition
Allows to run the test app from TEST partition. A boot from test partition will occur if there is
a GPIO input pulled low while device starts up. See settings below.
Default value:
• No (disabled) if CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK
CONFIG_BOOTLOADER_NUM_PIN_APP_TEST
Number of the GPIO input to boot TEST partition
Found in: Bootloader config > CONFIG_BOOTLOADER_APP_TEST
The selected GPIO will be configured as an input with internal pull-up enabled. To trigger a test app,
this GPIO must be pulled low on reset. After the GPIO input is deactivated and the device reboots, the
old application will boot. (factory or OTA[x]). Note that GPIO34-39 do not have an internal pullup and
an external one must be provided.
Range:
• from 0 to 39 if CONFIG_BOOTLOADER_APP_TEST
Default value:
• 18 if CONFIG_BOOTLOADER_APP_TEST
CONFIG_BOOTLOADER_HOLD_TIME_GPIO
Hold time of GPIO for reset/test mode (seconds)
The GPIO must be held low continuously for this period of time after reset before a factory reset or test
partition boot (as applicable) is performed.
Default value:
• 5 if CONFIG_BOOTLOADER_FACTORY_RESET || CONFIG_BOOTLOADER_APP_TEST
CONFIG_BOOTLOADER_WDT_ENABLE
Use RTC watchdog in start code
Tracks the execution time of startup code. If the execution time is exceeded, the RTC_WDT will restart
system. It is also useful to prevent a lock up in start code caused by an unstable power source. NOTE:
Tracks the execution time starts from the bootloader code - re-set timeout, while selecting the source
for slow_clk - and ends calling app_main. Re-set timeout is needed due to WDT uses a SLOW_CLK
clock source. After changing a frequency slow_clk a time of WDT needs to re-set for new frequency.
slow_clk depends on ESP32_RTC_CLK_SRC (INTERNAL_RC or EXTERNAL_CRYSTAL).
Default value:
• Yes (enabled)
CONFIG_BOOTLOADER_WDT_DISABLE_IN_USER_CODE
Allows RTC watchdog disable in user code
Found in: Bootloader config > CONFIG_BOOTLOADER_WDT_ENABLE
If this option is set, the ESP-IDF app must explicitly reset, feed, or disable the rtc_wdt in the app s
own code. If this option is not set (default), then rtc_wdt will be disabled by ESP-IDF before calling the
app_main() function.

Use function rtc_wdt_feed() for resetting counter of rtc_wdt. Use function rtc_wdt_disable() for dis-
abling rtc_wdt.
Default value:
• No (disabled)
CONFIG_BOOTLOADER_WDT_TIME_MS
Timeout for RTC watchdog (ms)
Found in: Bootloader config > CONFIG_BOOTLOADER_WDT_ENABLE
Verify that this parameter is correct and more then the execution time. Pay attention to options such as
reset to factory, trigger test partition and encryption on boot - these options can increase the execution
time. Note: RTC_WDT will reset while encryption operations will be performed.
Range:
• from 0 to 120000
Default value:
• 9000
CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE
Enable app rollback support
After updating the app, the bootloader runs a new app with the
ESP_OTA_IMG_PENDING_VERIFY state set. This state prevents the re-run of this app.
After the first boot of the new app in the user code, the function should be called to confirm the
operability of the app or vice versa about its non-operability. If the app is working, then it is marked
as valid. Otherwise, it is marked as not valid and rolls back to the previous working app. A reboot is
performed, and the app is booted before the software update. Note: If during the first boot a new app
the power goes out or the WDT works, then roll back will happen. Rollback is possible only between
the apps with the same security versions.
Default value:
• No (disabled)
CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK
Enable app anti-rollback support
Found in: Bootloader config > CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE
This option prevents rollback to previous firmware/application image with lower security version.
Default value:
• No (disabled) if CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE
CONFIG_BOOTLOADER_APP_SECURE_VERSION
eFuse secure version of app
Found in: Bootloader config > CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE > CON-
FIG_BOOTLOADER_APP_ANTI_ROLLBACK
The secure version is the sequence number stored in the header of each firmware. The security ver-
sion is set in the bootloader, version is recorded in the eFuse field as the number of set ones. The
allocated number of bits in the efuse field for storing the security version is limited (see BOOT-
LOADER_APP_SEC_VER_SIZE_EFUSE_FIELD option).
Bootloader: When bootloader selects an app to boot, an app is selected that has a security version greater
or equal that recorded in eFuse field. The app is booted with a higher (or equal) secure version.

The security version is worth increasing if in previous versions there is a significant vulnerability and
their use is not acceptable.
Your partition table should has a scheme with ota_0 + ota_1 (without factory).
Default value:
• 0 if CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK
CONFIG_BOOTLOADER_APP_SEC_VER_SIZE_EFUSE_FIELD
Size of the efuse secure version field
The size of the efuse secure version field. Its length is limited to 32 bits for ESP32 and 16 bits for
ESP32-S2. This determines how many times the security version can be increased.
Range:
• from 1 to 32 if CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK
• from 1 to 16 if CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK
Default value:
CONFIG_BOOTLOADER_EFUSE_SECURE_VERSION_EMULATE
Emulate operations with efuse secure version(only test)
This option allows to emulate read/write operations with all eFuses and efuse secure version. It allows
to test anti-rollback implemention without permanent write eFuse bits. There should be an entry in
partition table with following details: emul_efuse, data, efuse, , 0x2000.
This option enables: EFUSE_VIRTUAL and EFUSE_VIRTUAL_KEEP_IN_FLASH.
Default value:
• No (disabled) if CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK
CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP
Skip image validation when exiting deep sleep
This option disables the normal validation of an image coming out of deep sleep (checksums, SHA256,
and signature). This is a trade-off between wakeup performance from deep sleep, and image integrity
checks.
Only enable this if you know what you are doing. It should not be used in conjunction with using
deep_sleep() entry and changing the active OTA partition as this would skip the validation upon first
load of the new OTA partition.
It is possible to enable this option with Secure Boot if allow insecure options is enabled, however it
s strongly recommended to NOT enable it as it may allow a Secure Boot bypass.
Default value:
• No (disabled) if (CONFIG_SECURE_BOOT && CONFIG_SECURE_BOOT_INSECURE) ||
CONFIG_SECURE_BOOT

CONFIG_BOOTLOADER_SKIP_VALIDATE_ON_POWER_ON
Skip image validation from power on reset (READ HELP FIRST)
Some applications need to boot very quickly from power on. By default, the entire app binary is read
from flash and verified which takes up a significant portion of the boot time.
Enabling this option will skip validation of the app when the SoC boots from power on. Note that in this
case it s not possible for the bootloader to detect if an app image is corrupted in the flash, therefore it
s not possible to safely fall back to a different app partition. Flash corruption of this kind is unlikely but
can happen if there is a serious firmware bug or physical damage.
Following other reset types, the bootloader will still validate the app image. This increases the chances
that flash corruption resulting in a crash can be detected following soft reset, and the bootloader will fall
back to a valid app image. To increase the chances of successfully recovering from a flash corruption
event, keep the option BOOTLOADER_WDT_ENABLE enabled and consider also enabling BOOT-
LOADER_WDT_DISABLE_IN_USER_CODE - then manually disable the RTC Watchdog once the
app is running. In addition, enable both the Task and Interrupt watchdog timers with reset options set.
Default value:
• No (disabled)
CONFIG_BOOTLOADER_SKIP_VALIDATE_ALWAYS
Skip image validation always (READ HELP FIRST)
Selecting this option prevents the bootloader from ever validating the app image before booting it. Any
flash corruption of the selected app partition will make the entire SoC unbootable.
Although flash corruption is a very rare case, it is not recommended to select this option. Consider
selecting Skip image validation from power on reset instead. However, if boot time is the only
important factor then it can be enabled.
Default value:
• No (disabled)
CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC
Reserve RTC FAST memory for custom purposes
This option allows the customer to place data in the RTC FAST memory, this area remains valid when
rebooted, except for power loss. This memory is located at a fixed address and is available for both
the bootloader and the application. (The application and bootoloader must be compiled with the same
option). The RTC FAST memory has access only through PRO_CPU.
Default value:
• No (disabled)
CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC_SIZE
Size in bytes for custom purposes
Found in: Bootloader config > CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC
This option reserves in RTC FAST memory the area for custom purposes. If you want to create your
own bootloader and save more information in this area of memory, you can increase it. It must be a
multiple of 4 bytes. This area (rtc_retain_mem_t) is reserved and has access from the bootloader and
an application.

Range:
• from 0 to 0x10 if CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC
Default value:
• 0 if CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC
CONFIG_BOOTLOADER_FLASH_XMC_SUPPORT
Enable the support for flash chips of XMC (READ HELP FIRST)
Perform the startup flow recommended by XMC. Please consult XMC for the details of this flow. XMC
chips will be forbidden to be used, when this option is disabled.
DON T DISABLE THIS UNLESS YOU KNOW WHAT YOU ARE DOING.
Default value:
• Yes (enabled)
Security features
Contains:
• CONFIG_SECURE_BOOT_INSECURE
• CONFIG_SECURE_SIGNED_APPS_SCHEME
• CONFIG_SECURE_SIGNED_ON_BOOT_NO_SECURE_BOOT
• CONFIG_SECURE_FLASH_CHECK_ENC_EN_IN_APP
• CONFIG_SECURE_FLASH_ENC_ENABLED
• CONFIG_SECURE_BOOT
• CONFIG_SECURE_BOOTLOADER_KEY_ENCODING
• Potentially insecure options
• CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT
• CONFIG_SECURE_BOOT_VERIFICATION_KEY
• CONFIG_SECURE_BOOTLOADER_MODE
• CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES
• CONFIG_SECURE_UART_ROM_DL_MODE
• CONFIG_SECURE_SIGNED_ON_UPDATE_NO_SECURE_BOOT
CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT
Require signed app images
Found in: Security features
Require apps to be signed to verify their integrity.
This option uses the same app signature scheme as hardware secure boot, but unlike hardware secure
boot it does not prevent the bootloader from being physically updated. This means that the device can
be secured against remote network access, but not physical access. Compared to using hardware Secure
Boot this option is much simpler to implement.
CONFIG_SECURE_SIGNED_APPS_SCHEME
App Signing Scheme
Select the Secure App signing scheme. Depends on the Chip Revision. There are two options: 1.
ECDSA based secure boot scheme. (Only choice for Secure Boot V1) Supported in ESP32 and ESP32-
ECO3. 2. The RSA based secure boot scheme. (Only choice for Secure Boot V2) Supported in ESP32-
ECO3 (ESP32 Chip Revision 3 onwards), ESP32-S2, ESP32-C3, ESP32-S3.

Available options:
• ECDSA (SECURE_SIGNED_APPS_ECDSA_SCHEME)
Embeds the ECDSA public key in the bootloader and signs the application with an ECDSA
key.
Refer to the documentation before enabling.
• RSA (SECURE_SIGNED_APPS_RSA_SCHEME)
Appends the RSA-3072 based Signature block to the application. Refer to <Secure Boot
Version 2 documentation link> before enabling.
CONFIG_SECURE_SIGNED_ON_BOOT_NO_SECURE_BOOT
Bootloader verifies app signatures
If this option is set, the bootloader will be compiled with code to verify that an app is signed before
booting it.
If hardware secure boot is enabled, this option is always enabled and cannot be disabled. If hardware
secure boot is not enabled, this option doesn t add significant security by itself so most users will want
to leave it disabled.
Default value:
• No (disabled) if CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT && SE-
CURE_SIGNED_APPS_ECDSA_SCHEME
CONFIG_SECURE_SIGNED_ON_UPDATE_NO_SECURE_BOOT
Verify app signature on update
If this option is set, any OTA updated apps will have the signature verified before being considered valid.
When enabled, the signature is automatically checked whenever the esp_ota_ops.h APIs are used for
OTA updates, or esp_image_format.h APIs are used to verify apps.
If hardware secure boot is enabled, this option is always enabled and cannot be disabled. If hardware
secure boot is not enabled, this option still adds significant security against network-based attackers by
preventing spoofing of OTA updates.
Default value:
• Yes (enabled) if CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT
CONFIG_SECURE_BOOT
Enable hardware Secure Boot in bootloader (READ DOCS FIRST)
Build a bootloader which enables Secure Boot on first boot.
Once enabled, Secure Boot will not boot a modified bootloader. The bootloader will only load a partition
table or boot an app if the data has a verified digital signature. There are implications for reflashing
updated apps once secure boot is enabled.
When enabling secure boot, JTAG and ROM BASIC Interpreter are permanently disabled by default.
Default value:
• No (disabled)

CONFIG_SECURE_BOOT_VERSION
Select secure boot version
Found in: Security features > CONFIG_SECURE_BOOT
Select the Secure Boot Version. Depends on the Chip Revision. Secure Boot V2 is the new RSA
based secure boot scheme. Supported in ESP32-ECO3 (ESP32 Chip Revision 3 onwards), ESP32-S2,
ESP32-C3 ECO3. Secure Boot V1 is the AES based secure boot scheme. Supported in ESP32 and
ESP32-ECO3.
Available options:
• Enable Secure Boot version 1 (SECURE_BOOT_V1_ENABLED)
Build a bootloader which enables secure boot version 1 on first boot. Refer to the Secure Boot
section of the ESP-IDF Programmer s Guide for this version before enabling.
• Enable Secure Boot version 2 (SECURE_BOOT_V2_ENABLED)
Build a bootloader which enables Secure Boot version 2 on first boot. Refer to Secure Boot
V2 section of the ESP-IDF Programmer s Guide for this version before enabling.
CONFIG_SECURE_BOOTLOADER_MODE
Secure bootloader mode
Available options:
• One-time flash (SECURE_BOOTLOADER_ONE_TIME_FLASH)
On first boot, the bootloader will generate a key which is not readable externally or by software.
A digest is generated from the bootloader image itself. This digest will be verified on each
subsequent boot.
Enabling this option means that the bootloader cannot be changed after the first time it is
booted.
• Reflashable (SECURE_BOOTLOADER_REFLASHABLE)
Generate a reusable secure bootloader key, derived (via SHA-256) from the secure boot sign-
ing key.
This allows the secure bootloader to be re-flashed by anyone with access to the secure boot
signing key.
This option is less secure than one-time flash, because a leak of the digest key from one device
allows reflashing of any device that uses it.
CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES
Sign binaries during build
Once secure boot or signed app requirement is enabled, app images are required to be signed.
If enabled (default), these binary files are signed as part of the build process. The file named in Secure
boot private signing key will be used to sign the image.
If disabled, unsigned app/partition data will be built. They must be signed manually using espsecure.py.
Version 1 to enable ECDSA Based Secure Boot and Version 2 to enable RSA based Secure Boot. (for
example, on a remote signing server.)
CONFIG_SECURE_BOOT_SIGNING_KEY
Secure boot private signing key
Found in: Security features > CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES
Path to the key file used to sign app images.

Key file is an ECDSA private key (NIST256p curve) in PEM format for Secure Boot V1. Key file is an
RSA private key in PEM format for Secure Boot V2.
Path is evaluated relative to the project directory.
You can generate a new signing key by running the following command: espsecure.py gener-
ate_signing_key secure_boot_signing_key.pem
See the Secure Boot section of the ESP-IDF Programmer s Guide for this version for details.
Default value:
• secure_boot_signing_key.pem if CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES
CONFIG_SECURE_BOOT_VERIFICATION_KEY
Secure boot public signature verification key
Path to a public key file used to verify signed images. Secure Boot V1: This ECDSA public key is
compiled into the bootloader and/or app, to verify app images. Secure Boot V2: This RSA public key
is compiled into the signature block at the end of the bootloader/app.
Key file is in raw binary format, and can be extracted from a PEM formatted private key using the
espsecure.py extract_public_key command.
Refer to the Secure Boot section of the ESP-IDF Programmer s Guide for this version before enabling.
CONFIG_SECURE_BOOTLOADER_KEY_ENCODING
Hardware Key Encoding
In reflashable secure bootloader mode, a hardware key is derived from the signing key (with SHA-256)
and can be written to eFuse with espefuse.py.
Normally this is a 256-bit key, but if 3/4 Coding Scheme is used on the device then the eFuse key is
truncated to 192 bits.
This configuration item doesn t change any firmware code, it only changes the size of key binary which
is generated at build time.
Available options:
• No encoding (256 bit key) (SECURE_BOOTLOADER_KEY_ENCODING_256BIT)
• 3/4 encoding (192 bit key) (SECURE_BOOTLOADER_KEY_ENCODING_192BIT)
CONFIG_SECURE_BOOT_INSECURE
Allow potentially insecure options
You can disable some of the default protections offered by secure boot, in order to enable testing or a
custom combination of security features.
Only enable these options if you are very sure.
Refer to the Secure Boot section of the ESP-IDF Programmer s Guide for this version before enabling.
Default value:
• No (disabled) if CONFIG_SECURE_BOOT

CONFIG_SECURE_FLASH_ENC_ENABLED
Enable flash encryption on boot (READ DOCS FIRST)
If this option is set, flash contents will be encrypted by the bootloader on first boot.
Note: After first boot, the system will be permanently encrypted. Re-flashing an encrypted system is
complicated and not always possible.
Read Flash Encryption before enabling.
Default value:
• No (disabled)
CONFIG_SECURE_FLASH_ENCRYPTION_MODE
Enable usage mode
Found in: Security features > CONFIG_SECURE_FLASH_ENC_ENABLED
By default Development mode is enabled which allows ROM download mode to perform flash encryption
operations (plaintext is sent to the device, and it encrypts it internally and writes ciphertext to flash.) This
mode is not secure, it s possible for an attacker to write their own chosen plaintext to flash.
Release mode should always be selected for production or manufacturing. Once enabled it s no longer
possible for the device in ROM Download Mode to use the flash encryption hardware.
Refer to the Flash Encryption section of the ESP-IDF Programmer s Guide for details.
Available options:
• Development (NOT SECURE) (SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT)
• Release (SECURE_FLASH_ENCRYPTION_MODE_RELEASE)
Potentially insecure options Contains:

• CONFIG_SECURE_BOOT_V2_ALLOW_EFUSE_RD_DIS
• CONFIG_SECURE_BOOT_ALLOW_SHORT_APP_PARTITION
• CONFIG_SECURE_BOOT_ALLOW_JTAG
• CONFIG_SECURE_BOOT_ALLOW_ROM_BASIC
• CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_DEC
• CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_ENC
• CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_CACHE
• CONFIG_SECURE_FLASH_REQUIRE_ALREADY_ENABLED
CONFIG_SECURE_BOOT_ALLOW_ROM_BASIC
Leave ROM BASIC Interpreter available on reset
Found in: Security features > Potentially insecure options
By default, the BASIC ROM Console starts on reset if no valid bootloader is read from the flash.
When either flash encryption or secure boot are enabled, the default is to disable this BASIC fallback
mode permanently via eFuse.
If this option is set, this eFuse is not burned and the BASIC ROM Console may remain accessible. Only
set this option in testing environments.
Default value:
• No (disabled) if CONFIG_SECURE_BOOT_INSECURE || SE-
CURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT

CONFIG_SECURE_BOOT_ALLOW_JTAG
Allow JTAG Debugging
If not set (default), the bootloader will permanently disable JTAG (across entire chip) on first boot when
either secure boot or flash encryption is enabled.
Setting this option leaves JTAG on for debugging, which negates all protections of flash encryption and
some of the protections of secure boot.
Only set this option in testing environments.
Default value:
• No (disabled) if CONFIG_SECURE_BOOT_INSECURE || SE-
CURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT
CONFIG_SECURE_BOOT_ALLOW_SHORT_APP_PARTITION
Allow app partition length not 64KB aligned
If not set (default), app partition size must be a multiple of 64KB. App images are padded to 64KB
length, and the bootloader checks any trailing bytes after the signature (before the next 64KB boundary)
have not been written. This is because flash cache maps entire 64KB pages into the address space. This
prevents an attacker from appending unverified data after the app image in the flash, causing it to be
mapped into the address space.
Setting this option allows the app partition length to be unaligned, and disables padding of the app image
to this length. It is generally not recommended to set this option, unless you have a legacy partitioning
scheme which doesn t support 64KB aligned partition lengths.
CONFIG_SECURE_BOOT_V2_ALLOW_EFUSE_RD_DIS
Allow additional read protecting of efuses
If not set (default, recommended), on first boot the bootloader will burn the WR_DIS_RD_DIS efuse
when Secure Boot is enabled. This prevents any more efuses from being read protected.
If this option is set, it will remain possible to write the EFUSE_RD_DIS efuse field after Secure Boot
is enabled. This may allow an attacker to read-protect the BLK2 efuse (for ESP32) and BLOCK4-
BLOCK10 (i.e. BLOCK_KEY0-BLOCK_KEY5)(for other chips) holding the public key digest, caus-
ing an immediate denial of service and possibly allowing an additional fault injection attack to bypass
the signature protection.
NOTE: Once a BLOCK is read-protected, the application will read all zeros from that block
NOTE: If UART ROM download mode (Permanently disabled (recommended)) or UART ROM
download mode (Permanently switch to Secure mode (recommended)) is set, then it is __NOT__
possible to read/write efuses using espefuse.py utility. However, efuse can be read/written from the
application
CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_ENC
Leave UART bootloader encryption enabled
If not set (default), the bootloader will permanently disable UART bootloader encryption access on first
boot. If set, the UART bootloader will still be able to access hardware encryption.
It is recommended to only set this option in testing environments.

Default value:
• No (disabled) if SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT
CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_DEC
Leave UART bootloader decryption enabled
If not set (default), the bootloader will permanently disable UART bootloader decryption access on first
boot. If set, the UART bootloader will still be able to access hardware decryption.
Only set this option in testing environments. Setting this option allows complete bypass of flash encryp-
tion.
Default value:
CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_CACHE
Leave UART bootloader flash cache enabled
If not set (default), the bootloader will permanently disable UART bootloader flash cache access on first
boot. If set, the UART bootloader will still be able to access the flash cache.
Only set this option in testing environments.
Default value:
CONFIG_SECURE_FLASH_REQUIRE_ALREADY_ENABLED
Require flash encryption to be already enabled
If not set (default), and flash encryption is not yet enabled in eFuses, the 2nd stage bootloader will enable
flash encryption: generate the flash encryption key and program eFuses. If this option is set, and flash
encryption is not yet enabled, the bootloader will error out and reboot. If flash encryption is enabled in
eFuses, this option does not change the bootloader behavior.
Only use this option in testing environments, to avoid accidentally enabling flash encryption on the wrong
device. The device needs to have flash encryption already enabled using espefuse.py.
Default value:
CONFIG_SECURE_FLASH_CHECK_ENC_EN_IN_APP
Check Flash Encryption enabled on app startup
If set (default), in an app during startup code, there is a check of the flash encryption eFuse bit is on (as
the bootloader should already have set it). The app requires this bit is on to continue work otherwise
abort.
If not set, the app does not care if the flash encryption eFuse bit is set or not.
Default value:
• Yes (enabled) if CONFIG_SECURE_FLASH_ENC_ENABLED

CONFIG_SECURE_UART_ROM_DL_MODE
UART ROM download mode
Available options:
• UART ROM download mode (Permanently disabled (recommended)) (SE-
CURE_DISABLE_ROM_DL_MODE)
If set, during startup the app will burn an eFuse bit to permanently disable the UART ROM
Download Mode. This prevents any future use of esptool.py, espefuse.py and similar tools.
Once disabled, if the SoC is booted with strapping pins set for ROM Download Mode then
an error is printed instead.
It is recommended to enable this option in any production application where Flash Encryption
and/or Secure Boot is enabled and access to Download Mode is not required.
It is also possible to permanently disable Download Mode by calling
esp_efuse_disable_rom_download_mode() at runtime.
• UART ROM download mode (Permanently switch to Secure mode (recommended)) (SE-
CURE_ENABLE_SECURE_ROM_DL_MODE)
If set, during startup the app will burn an eFuse bit to permanently switch the UART ROM
Download Mode into a separate Secure Download mode. This option can only work if Down-
load Mode is not already disabled by eFuse.
Secure Download mode limits the use of Download Mode functions to simple flash read,
write and erase operations, plus a command to return a summary of currently enabled security
features.
Secure Download mode is not compatible with the esptool.py flasher stub feature, espefuse.py,
read/writing memory or registers, encrypted download, or any other features that interact with
unsupported Download Mode commands.
Secure Download mode should be enabled in any application where Flash Encryption and/or
Secure Boot is enabled. Disabling this option does not immediately cancel the benefits of the
security features, but it increases the potential attack surface for an attacker to try and
bypass them with a successful physical attack.
It is also possible to enable secure download mode at runtime by calling
esp_efuse_enable_rom_secure_download_mode()
Note: Secure Download mode is not available for ESP32 (includes revisions till ECO3).
• UART ROM download mode (Enabled (not recommended)) (SE-
CURE_INSECURE_ALLOW_DL_MODE)
This is a potentially insecure option. Enabling this option will allow the full UART download
mode to stay enabled. This option SHOULD NOT BE ENABLED for production use cases.
Serial flasher config
Contains:
• CONFIG_ESPTOOLPY_MONITOR_BAUD
• CONFIG_ESPTOOLPY_AFTER
• CONFIG_ESPTOOLPY_BEFORE
• CONFIG_ESPTOOLPY_MONITOR_BAUD_OTHER_VAL
• CONFIG_ESPTOOLPY_FLASHSIZE_DETECT
• CONFIG_ESPTOOLPY_NO_STUB
• CONFIG_ESPTOOLPY_FLASH_SAMPLE_MODE
• CONFIG_ESPTOOLPY_FLASHSIZE
• CONFIG_ESPTOOLPY_FLASHMODE
• CONFIG_ESPTOOLPY_FLASHFREQ
CONFIG_ESPTOOLPY_NO_STUB
Disable download stub
Found in: Serial flasher config

The flasher tool sends a precompiled download stub first by default. That stub allows things like com-
pressed downloads and more. Usually you should not need to disable that feature
Default value:
• No (disabled)
CONFIG_ESPTOOLPY_FLASHMODE
Flash SPI mode
Mode the flash chip is flashed in, as well as the default mode for the binary to run in.
Available options:
• QIO (ESPTOOLPY_FLASHMODE_QIO)
• QOUT (ESPTOOLPY_FLASHMODE_QOUT)
• DIO (ESPTOOLPY_FLASHMODE_DIO)
• DOUT (ESPTOOLPY_FLASHMODE_DOUT)
• OPI (ESPTOOLPY_FLASHMODE_OPI)
CONFIG_ESPTOOLPY_FLASH_SAMPLE_MODE
Flash Sampling Mode
Available options:
• STR Mode (ESPTOOLPY_FLASH_SAMPLE_MODE_STR)
• DTR Mode (ESPTOOLPY_FLASH_SAMPLE_MODE_DTR)
CONFIG_ESPTOOLPY_FLASHFREQ
Flash SPI speed
The SPI flash frequency to be used.
Available options:
• 120 MHz (ESPTOOLPY_FLASHFREQ_120M)
CONFIG_ESPTOOLPY_FLASHSIZE
Flash size
SPI flash size, in megabytes
Available options:
• 1 MB (ESPTOOLPY_FLASHSIZE_1MB)

CONFIG_ESPTOOLPY_FLASHSIZE_DETECT
Detect flash size when flashing bootloader
If this option is set, flashing the project will automatically detect the flash size of the target chip and
update the bootloader image before it is flashed.
Default value:
• Yes (enabled)
CONFIG_ESPTOOLPY_BEFORE
Before flashing
Configure whether esptool.py should reset the ESP32 before flashing.
Automatic resetting depends on the RTS & DTR signals being wired from the serial port to the ESP32.
Most USB development boards do this internally.
Available options:
• Reset to bootloader (ESPTOOLPY_BEFORE_RESET)
• No reset (ESPTOOLPY_BEFORE_NORESET)
CONFIG_ESPTOOLPY_AFTER
After flashing
Configure whether esptool.py should reset the ESP32 after flashing.
Automatic resetting depends on the RTS & DTR signals being wired from the serial port to the ESP32.
Most USB development boards do this internally.
Available options:
• Reset after flashing (ESPTOOLPY_AFTER_RESET)
• Stay in bootloader (ESPTOOLPY_AFTER_NORESET)
CONFIG_ESPTOOLPY_MONITOR_BAUD
idf.py monitor baud rate
Baud rate to use when running idf.py monitor or make monitor to view serial output from a
running chip.
If Same as UART Console baud rate is chosen then the value will follow the UART Console baud
rate config item.
Can override by setting the MONITORBAUD environment variable.
Available options:
• Same as UART console baud rate (ESPTOOLPY_MONITOR_BAUD_CONSOLE)
• 9600 bps (ESPTOOLPY_MONITOR_BAUD_9600B)
• 2 Mbps (ESPTOOLPY_MONITOR_BAUD_2MB)
• Custom baud rate (ESPTOOLPY_MONITOR_BAUD_OTHER)

CONFIG_ESPTOOLPY_MONITOR_BAUD_OTHER_VAL
Custom baud rate value
Default value:
• 115200
Partition Table
Contains:
• CONFIG_PARTITION_TABLE_CUSTOM_FILENAME
• CONFIG_PARTITION_TABLE_MD5
• CONFIG_PARTITION_TABLE_OFFSET
• CONFIG_PARTITION_TABLE_TYPE
CONFIG_PARTITION_TABLE_TYPE
Partition Table
Found in: Partition Table
The partition table to flash to the ESP32. The partition table determines where apps, data and other
resources are expected to be found.
The predefined partition table CSV descriptions can be found in the components/partition_table direc-
tory. These are mostly intended for example and development use, it s expect that for production use
you will copy one of these CSV files and create a custom partition CSV for your application.
Available options:
• Single factory app, no OTA (PARTITION_TABLE_SINGLE_APP)
This is the default partition table, designed to fit into a 2MB or larger flash with a single 1MB
app partition.
The corresponding CSV file in the IDF directory is compo-
nents/partition_table/partitions_singleapp.csv
This partition table is not suitable for an app that needs OTA (over the air update) capability.
• Single factory app (large), no OTA (PARTITION_TABLE_SINGLE_APP_LARGE)
This is a variation of the default partition table, that expands the 1MB app partition size to
1.5MB to fit more code.
nents/partition_table/partitions_singleapp_large.csv
This partition table is not suitable for an app that needs OTA (over the air update) capability.
• Factory app, two OTA definitions (PARTITION_TABLE_TWO_OTA)
This is a basic OTA-enabled partition table with a factory app partition plus two OTA app
partitions. All are 1MB, so this partition table requires 4MB or larger flash size.
nents/partition_table/partitions_two_ota.csv
• Custom partition table CSV (PARTITION_TABLE_CUSTOM)
Specify the path to the partition table CSV to use for your project.
Consult the Partition Table section in the ESP-IDF Programmers Guide for more information.
• Single factory app, no OTA, encrypted NVS (PARTI-
TION_TABLE_SINGLE_APP_ENCRYPTED_NVS)
This is a variation of the default Single factory app, no OTA partition table that supports
encrypted NVS when using flash encryption. See the Flash Encryption section in the ESP-IDF
Programmers Guide for more information.
nents/partition_table/partitions_singleapp_encr_nvs.csv
• Single factory app (large), no OTA, encrypted NVS (PARTI-
TION_TABLE_SINGLE_APP_LARGE_ENC_NVS)

This is a variation of the Single factory app (large), no OTA partition table that supports
nents/partition_table/partitions_singleapp_large_encr_nvs.csv
• Factory app, two OTA definitions, encrypted NVS (PARTI-
TION_TABLE_TWO_OTA_ENCRYPTED_NVS)
This is a variation of the Factory app, two OTA definitions partition table that supports
nents/partition_table/partitions_two_ota_encr_nvs.csv
CONFIG_PARTITION_TABLE_CUSTOM_FILENAME
Custom partition CSV file
Name of the custom partition CSV filename. This path is evaluated relative to the project root directory.
Default value:
• partitions.csv
CONFIG_PARTITION_TABLE_OFFSET
Offset of partition table
The address of partition table (by default 0x8000). Allows you to move the partition table, it gives more
space for the bootloader. Note that the bootloader and app will both need to be compiled with the same
PARTITION_TABLE_OFFSET value.
This number should be a multiple of 0x1000.
Note that partition offsets in the partition table CSV file may need to be changed if this value is set to a
higher value. To have each partition offset adapt to the configured partition table offset, leave all partition
offsets blank in the CSV file.
Default value:
• 0x8000
CONFIG_PARTITION_TABLE_MD5
Generate an MD5 checksum for the partition table
Generate an MD5 checksum for the partition table for protecting the integrity of the table. The gen-
eration should be turned off for legacy bootloaders which cannot recognize the MD5 checksum in the
partition table.
Default value:
• Yes (enabled) if CONFIG_ESP32_COMPATIBLE_PRE_V3_1_BOOTLOADERS
Compiler options
Contains:
• CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL
• CONFIG_COMPILER_OPTIMIZATION_CHECKS_SILENT
• CONFIG_COMPILER_DISABLE_GCC8_WARNINGS

• CONFIG_COMPILER_DUMP_RTL_FILES
• CONFIG_COMPILER_WARN_WRITE_STRINGS
• CONFIG_COMPILER_CXX_EXCEPTIONS
• CONFIG_COMPILER_CXX_RTTI
• CONFIG_COMPILER_OPTIMIZATION
• CONFIG_COMPILER_HIDE_PATHS_MACROS
• CONFIG_COMPILER_STACK_CHECK_MODE
CONFIG_COMPILER_OPTIMIZATION
Optimization Level
Found in: Compiler options
This option sets compiler optimization level (gcc -O argument) for the app.
• The Default setting will add the -0g flag to CFLAGS.
• The Size setting will add the -0s flag to CFLAGS.
• The Performance setting will add the -O2 flag to CFLAGS.
• The None setting will add the -O0 flag to CFLAGS.
The Size setting cause the compiled code to be smaller and faster, but may lead to difficulties of
correlating code addresses to source file lines when debugging.
The Performance setting causes the compiled code to be larger and faster, but will be easier to
correlated code addresses to source file lines.
None with -O0 produces compiled code without optimization.
Note that custom optimization levels may be unsupported.
Compiler optimization for the IDF bootloader is set separately, see the BOOT-
LOADER_COMPILER_OPTIMIZATION setting.
Available options:
• Debug (-Og) (COMPILER_OPTIMIZATION_DEFAULT)
• Optimize for size (-Os) (COMPILER_OPTIMIZATION_SIZE)
• Optimize for performance (-O2) (COMPILER_OPTIMIZATION_PERF)
• Debug without optimization (-O0) (COMPILER_OPTIMIZATION_NONE)
CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL
Assertion level
Assertions can be:
• Enabled. Failure will print verbose assertion details. This is the default.
• Set to silent to save code size (failed assertions will abort() but user needs to use the aborting
address to find the line number with the failed assertion.)
• Disabled entirely (not recommended for most configurations.) -DNDEBUG is added to
CPPFLAGS in this case.
Available options:
• Enabled (COMPILER_OPTIMIZATION_ASSERTIONS_ENABLE)
Enable assertions. Assertion content and line number will be printed on failure.
• Silent (saves code size) (COMPILER_OPTIMIZATION_ASSERTIONS_SILENT)
Enable silent assertions. Failed assertions will abort(), user needs to use the aborting address
to find the line number with the failed assertion.
• Disabled (sets -DNDEBUG) (COMPILER_OPTIMIZATION_ASSERTIONS_DISABLE)
If assertions are disabled, -DNDEBUG is added to CPPFLAGS.

CONFIG_COMPILER_OPTIMIZATION_CHECKS_SILENT
Disable messages in ESP_RETURN_ON_* and ESP_EXIT_ON_* macros
If enabled, the error messages will be discarded in following check macros: -
ESP_RETURN_ON_ERROR - ESP_EXIT_ON_ERROR - ESP_RETURN_ON_FALSE -
ESP_EXIT_ON_FALSE
Default value:
• No (disabled)
CONFIG_COMPILER_HIDE_PATHS_MACROS
Replace ESP-IDF and project paths in binaries
When expanding the __FILE__ and __BASE_FILE__ macros, replace paths inside ESP-IDF with paths
relative to the placeholder string IDF , and convert paths inside the project directory to relative paths.
This allows building the project with assertions or other code that embeds file paths, without the binary
containing the exact path to the IDF or project directories.
This option passes -fmacro-prefix-map options to the GCC command line. To replace additional paths in
your binaries, modify the project CMakeLists.txt file to pass custom -fmacro-prefix-map or -ffile-prefix-
map arguments.
Default value:
• Yes (enabled)
CONFIG_COMPILER_CXX_EXCEPTIONS
Enable C++ exceptions
Enabling this option compiles all IDF C++ files with exception support enabled.
Disabling this option disables C++ exception support in all compiled files, and any libstdc++ code which
throws an exception will abort instead.
Enabling this option currently adds an additional ~500 bytes of heap overhead when an exception is
thrown in user code for the first time.
Default value:
• No (disabled)
Contains:
• CONFIG_COMPILER_CXX_EXCEPTIONS_EMG_POOL_SIZE
CONFIG_COMPILER_CXX_EXCEPTIONS_EMG_POOL_SIZE
Emergency Pool Size
Found in: Compiler options > CONFIG_COMPILER_CXX_EXCEPTIONS
Size (in bytes) of the emergency memory pool for C++ exceptions. This pool will be used to allocate
memory for thrown exceptions when there is not enough memory on the heap.
Default value:
• 0 if CONFIG_COMPILER_CXX_EXCEPTIONS

CONFIG_COMPILER_CXX_RTTI
Enable C++ run-time type info (RTTI)
Enabling this option compiles all C++ files with RTTI support enabled. This increases binary size (typ-
ically by tens of kB) but allows using dynamic_cast conversion and typeid operator.
Default value:
• No (disabled)
CONFIG_COMPILER_STACK_CHECK_MODE
Stack smashing protection mode
Stack smashing protection mode. Emit extra code to check for buffer overflows, such as stack smashing
attacks. This is done by adding a guard variable to functions with vulnerable objects. The guards are
initialized when a function is entered and then checked when the function exits. If a guard check fails,
program is halted. Protection has the following modes:
• In NORMAL mode (GCC flag: -fstack-protector) only functions that call alloca, and functions
with buffers larger than 8 bytes are protected.
• STRONG mode (GCC flag: -fstack-protector-strong) is like NORMAL, but includes additional
functions to be protected those that have local array definitions, or have references to local frame
addresses.
• In OVERALL mode (GCC flag: -fstack-protector-all) all functions are protected.
Modes have the following impact on code performance and coverage:
• performance: NORMAL > STRONG > OVERALL
• coverage: NORMAL < STRONG < OVERALL
The performance impact includes increasing the amount of stack memory required for each task.
Available options:
• None (COMPILER_STACK_CHECK_MODE_NONE)
• Normal (COMPILER_STACK_CHECK_MODE_NORM)
• Strong (COMPILER_STACK_CHECK_MODE_STRONG)
• Overall (COMPILER_STACK_CHECK_MODE_ALL)
CONFIG_COMPILER_WARN_WRITE_STRINGS
Enable -Wwrite-strings warning flag
Adds -Wwrite-strings flag for the C/C++ compilers.
For C, this gives string constants the type const char[] so that copying the address of one into a
non-const char \* pointer produces a warning. This warning helps to find at compile time code that
tries to write into a string constant.
For C++, this warns about the deprecated conversion from string literals to char \*.
Default value:
• No (disabled)
CONFIG_COMPILER_DISABLE_GCC8_WARNINGS
Disable new warnings introduced in GCC 6 - 8

Enable this option if using GCC 6 or newer, and wanting to disable warnings which don t appear with
GCC 5.
Default value:
• No (disabled)
CONFIG_COMPILER_DUMP_RTL_FILES
Dump RTL files during compilation
If enabled, RTL files will be produced during compilation. These files can be used by other tools, for
example to calculate call graphs.
Component config
Contains:
• ADC-Calibration
• Application Level Tracing
• Bluetooth
• CoAP Configuration
• Common ESP-related
• Core dump
• Driver configurations
• eFuse Bit Manager
• CONFIG_BLE_MESH
• ESP HTTP client
• ESP HTTPS OTA
• ESP HTTPS server
• ESP NETIF Adapter
• ESP System Settings
• ESP-ASIO
• ESP-MQTT Configurations
• ESP-TLS
• ESP32-specific
• Ethernet
• Event Loop Library
• FAT Filesystem support
• FreeRTOS
• GDB Stub
• Hardware Abstraction Layer (HAL) and Low Level (LL)
• Hardware Settings
• Heap memory debugging
• High resolution timer (esp_timer)
• HTTP Server
• IPC (Inter-Processor Call)
• jsmn
• LCD and Touch Panel
• libsodium
• Log output
• LWIP
• mbedTLS
• mDNS
• Modbus configuration
• Newlib
• NVS
• OpenSSL

• OpenThread
• PHY
• Power Management
• PThreads
• SPI Flash driver
• SPIFFS Configuration
• Supplicant
• TCP Transport
• Unity unit testing library
• Virtual file system
• Wear Levelling
• Wi-Fi
• Wi-Fi Provisioning Manager
Application Level Tracing Contains:

• CONFIG_APPTRACE_DESTINATION
• FreeRTOS SystemView Tracing
• CONFIG_APPTRACE_GCOV_ENABLE
• CONFIG_APPTRACE_BUF_SIZE
• CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX
• CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH
• CONFIG_APPTRACE_ONPANIC_HOST_FLUSH_TMO
CONFIG_APPTRACE_DESTINATION
Data Destination
Found in: Component config > Application Level Tracing
Select destination for application trace: JTAG or none (to disable).
Available options:
• JTAG (APPTRACE_DEST_JTAG)
• None (APPTRACE_DEST_NONE)
CONFIG_APPTRACE_ONPANIC_HOST_FLUSH_TMO
Timeout for flushing last trace data to host on panic
Timeout for flushing last trace data to host in case of panic. In ms. Use -1 to disable timeout and wait
forever.
CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH
Threshold for flushing last trace data to host on panic
Threshold for flushing last trace data to host on panic in post-mortem mode. This is minimal amount of
data needed to perform flush. In bytes.
CONFIG_APPTRACE_BUF_SIZE
Size of the apptrace buffer
Size of the memory buffer for trace data in bytes.

CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX
Size of the pending data buffer
Size of the buffer for events in bytes. It is useful for buffering events from the time critical code (sched-
uler, ISRs etc). If this parameter is 0 then events will be discarded when main HW buffer is full.
FreeRTOS SystemView Tracing Contains:

• CONFIG_APPTRACE_SV_ENABLE
CONFIG_APPTRACE_SV_ENABLE
SystemView Tracing Enable
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables supporrt for SEGGER SystemView tracing functionality.
CONFIG_APPTRACE_SV_TS_SOURCE
Timer to use as timestamp source
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing > CON-
FIG_APPTRACE_SV_ENABLE
SystemView needs to use a hardware timer as the source of timestamps when tracing. This option selects
the timer for it.
Available options:
• CPU cycle counter (CCOUNT) (APPTRACE_SV_TS_SOURCE_CCOUNT)
• Timer 0, Group 0 (APPTRACE_SV_TS_SOURCE_TIMER_00)
• esp_timer high resolution timer (APPTRACE_SV_TS_SOURCE_ESP_TIMER)
CONFIG_APPTRACE_SV_MAX_TASKS
Maximum supported tasks
Configures maximum supported tasks in sysview debug
CONFIG_APPTRACE_SV_BUF_WAIT_TMO
Trace buffer wait timeout
Configures timeout (in us) to wait for free space in trace buffer. Set to -1 to wait forever and avoid lost
events.

CONFIG_APPTRACE_SV_EVT_OVERFLOW_ENABLE
Trace Buffer Overflow Event
Enables Trace Buffer Overflow event.
CONFIG_APPTRACE_SV_EVT_ISR_ENTER_ENABLE
ISR Enter Event
Enables ISR Enter event.
CONFIG_APPTRACE_SV_EVT_ISR_EXIT_ENABLE
ISR Exit Event
Enables ISR Exit event.
CONFIG_APPTRACE_SV_EVT_ISR_TO_SCHED_ENABLE
ISR Exit to Scheduler Event
Enables ISR to Scheduler event.
CONFIG_APPTRACE_SV_EVT_TASK_START_EXEC_ENABLE
Task Start Execution Event
Enables Task Start Execution event.
CONFIG_APPTRACE_SV_EVT_TASK_STOP_EXEC_ENABLE
Task Stop Execution Event
Enables Task Stop Execution event.
CONFIG_APPTRACE_SV_EVT_TASK_START_READY_ENABLE
Task Start Ready State Event
Enables Task Start Ready State event.

CONFIG_APPTRACE_SV_EVT_TASK_STOP_READY_ENABLE
Task Stop Ready State Event
Enables Task Stop Ready State event.
CONFIG_APPTRACE_SV_EVT_TASK_CREATE_ENABLE
Task Create Event
Enables Task Create event.
CONFIG_APPTRACE_SV_EVT_TASK_TERMINATE_ENABLE
Task Terminate Event
Enables Task Terminate event.
CONFIG_APPTRACE_SV_EVT_IDLE_ENABLE
System Idle Event
Enables System Idle event.
CONFIG_APPTRACE_SV_EVT_TIMER_ENTER_ENABLE
Timer Enter Event
Enables Timer Enter event.
CONFIG_APPTRACE_SV_EVT_TIMER_EXIT_ENABLE
Timer Exit Event
Enables Timer Exit event.
CONFIG_APPTRACE_GCOV_ENABLE
GCOV to Host Enable
Enables support for GCOV data transfer to host.

ESP-ASIO Contains:
• CONFIG_ASIO_SSL_SUPPORT
CONFIG_ASIO_SSL_SUPPORT
Enable SSL/TLS support of ASIO
Found in: Component config > ESP-ASIO
Enable support for basic SSL/TLS features, available for mbedTLS/OpenSSL as well as wolfSSL TLS
library.
Default value:
• No (disabled)
CONFIG_ASIO_SSL_LIBRARY_CHOICE
Choose SSL/TLS library for ESP-TLS (See help for more Info)
Found in: Component config > ESP-ASIO > CONFIG_ASIO_SSL_SUPPORT
The ASIO support multiple backend TLS libraries. Currently the mbedTLS with a thin ESP-OpenSSL
port layer (default choice) and WolfSSL are supported. Different TLS libraries may support different
features and have different resource usage. Consult the ESP-TLS documentation in ESP-IDF Program-
ming guide for more details.
Available options:
• esp-openssl (ASIO_USE_ESP_OPENSSL)
• wolfSSL (License info in wolfSSL directory README) (ASIO_USE_ESP_WOLFSSL)
Bluetooth Contains:
• Bluedroid Options
• CONFIG_BT_ENABLED
• NimBLE Options
CONFIG_BT_ENABLED
Bluetooth
Found in: Component config > Bluetooth
Select this option to enable Bluetooth and show the submenu with Bluetooth configuration choices.
Bluetooth controller Contains:

• CONFIG_BTDM_CTRL_AUTO_LATENCY
• CONFIG_BTDM_BLE_ADV_REPORT_FLOW_CTRL_SUPP
• CONFIG_BTDM_CTRL_FULL_SCAN_SUPPORTED
• CONFIG_BTDM_CTRL_BLE_MAX_CONN
• CONFIG_BTDM_BLE_SCAN_DUPL
• CONFIG_BTDM_BLE_SLEEP_CLOCK_ACCURACY
• CONFIG_BTDM_CTRL_MODE
• CONFIG_BTDM_CTRL_BR_EDR_MAX_ACL_CONN
• CONFIG_BTDM_CTRL_BR_EDR_SCO_DATA_PATH
• CONFIG_BTDM_CTRL_BR_EDR_MAX_SYNC_CONN
• CONFIG_BTDM_CTRL_HCI_MODE_CHOICE
• HCI UART(H4) Options
• CONFIG_BTDM_CTRL_HLI
• CONFIG_BTDM_CTRL_LEGACY_AUTH_VENDOR_EVT
• MODEM SLEEP Options

• CONFIG_BTDM_CTRL_PCM_ROLE_EDGE_CONFIG
• CONFIG_BTDM_CTRL_PINNED_TO_CORE_CHOICE
CONFIG_BTDM_CTRL_MODE
Bluetooth controller mode (BR/EDR/BLE/DUALMODE)
Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller
Specify the bluetooth controller mode (BR/EDR, BLE or dual mode).
Available options:
• BLE Only (BTDM_CTRL_MODE_BLE_ONLY)
• BR/EDR Only (BTDM_CTRL_MODE_BR_EDR_ONLY)
• Bluetooth Dual Mode (BTDM_CTRL_MODE_BTDM)
CONFIG_BTDM_CTRL_BLE_MAX_CONN
BLE Max Connections
BLE maximum connections of bluetooth controller. Each connection uses 1KB static DRAM whenever
the BT controller is enabled.
Range:
• from 1 to 9 if (BTDM_CTRL_MODE_BLE_ONLY || BTDM_CTRL_MODE_BTDM) &&
CONFIG_BT_ENABLED
Default value:
• 3 if (BTDM_CTRL_MODE_BLE_ONLY || BTDM_CTRL_MODE_BTDM) && CON-
FIG_BT_ENABLED
CONFIG_BTDM_CTRL_BR_EDR_MAX_ACL_CONN
BR/EDR ACL Max Connections
BR/EDR ACL maximum connections of bluetooth controller. Each connection uses 1.2 KB DRAM
whenever the BT controller is enabled.
Range:
• from 1 to 7 if (BTDM_CTRL_MODE_BR_EDR_ONLY || BTDM_CTRL_MODE_BTDM)
&& CONFIG_BT_ENABLED
Default value:
• 2 if (BTDM_CTRL_MODE_BR_EDR_ONLY || BTDM_CTRL_MODE_BTDM) &&
CONFIG_BT_ENABLED
CONFIG_BTDM_CTRL_BR_EDR_MAX_SYNC_CONN
BR/EDR Sync(SCO/eSCO) Max Connections
BR/EDR Synchronize maximum connections of bluetooth controller. Each connection uses 2 KB
DRAM whenever the BT controller is enabled.
Range:
• from 0 to 3 if (BTDM_CTRL_MODE_BR_EDR_ONLY || BTDM_CTRL_MODE_BTDM)
Default value:
• 0 if (BTDM_CTRL_MODE_BR_EDR_ONLY || BTDM_CTRL_MODE_BTDM) &&
CONFIG_BT_ENABLED

CONFIG_BTDM_CTRL_BR_EDR_SCO_DATA_PATH
BR/EDR Sync(SCO/eSCO) default data path
SCO data path, i.e. HCI or PCM. SCO data can be sent/received through HCI synchronous packets, or
the data can be routed to on-chip PCM module on ESP32. PCM input/output signals can be matrixed
to GPIOs. The default data path can also be set using API esp_bredr_sco_datapath_set
Available options:
• HCI (BTDM_CTRL_BR_EDR_SCO_DATA_PATH_HCI)
• PCM (BTDM_CTRL_BR_EDR_SCO_DATA_PATH_PCM)
CONFIG_BTDM_CTRL_PCM_ROLE_EDGE_CONFIG
PCM Signal Config (Role and Polar)
Default value:
• Yes (enabled) if BTDM_CTRL_BR_EDR_SCO_DATA_PATH_PCM && CON-
FIG_BT_ENABLED
Contains:
• CONFIG_BTDM_CTRL_PCM_POLAR
• CONFIG_BTDM_CTRL_PCM_ROLE
CONFIG_BTDM_CTRL_PCM_ROLE
PCM Role
Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller > CON-
FIG_BTDM_CTRL_PCM_ROLE_EDGE_CONFIG
PCM role can be configured as PCM master or PCM slave
Available options:
• PCM Master (BTDM_CTRL_PCM_ROLE_MASTER)
• PCM Slave (BTDM_CTRL_PCM_ROLE_SLAVE)
CONFIG_BTDM_CTRL_PCM_POLAR
PCM Polar
FIG_BTDM_CTRL_PCM_ROLE_EDGE_CONFIG
PCM polarity can be configured as Falling Edge or Rising Edge
Available options:
• Falling Edge (BTDM_CTRL_PCM_POLAR_FALLING_EDGE)
• Rising Edge (BTDM_CTRL_PCM_POLAR_RISING_EDGE)
CONFIG_BTDM_CTRL_AUTO_LATENCY
Auto latency
BLE auto latency, used to enhance classic BT performance while classic BT and BLE are enabled at the
same time.
Default value:
• No (disabled) if BTDM_CTRL_MODE_BTDM && CONFIG_BT_ENABLED

CONFIG_BTDM_CTRL_LEGACY_AUTH_VENDOR_EVT
Legacy Authentication Vendor Specific Event Enable
To protect from BIAS attack during Legacy authentication, Legacy authentication Vendor specific event
should be enabled
Default value:
• Yes (enabled) if (BTDM_CTRL_MODE_BR_EDR_ONLY ||
BTDM_CTRL_MODE_BTDM) && CONFIG_BT_ENABLED
CONFIG_BTDM_CTRL_PINNED_TO_CORE_CHOICE
The cpu core which bluetooth controller run
Specify the cpu core to run bluetooth controller. Can not specify no-affinity.
Available options:
• Core 0 (PRO CPU) (BTDM_CTRL_PINNED_TO_CORE_0)
• Core 1 (APP CPU) (BTDM_CTRL_PINNED_TO_CORE_1)
CONFIG_BTDM_CTRL_HCI_MODE_CHOICE
HCI mode
Speicify HCI mode as VHCI or UART(H4)
Available options:
• VHCI (BTDM_CTRL_HCI_MODE_VHCI)
Normal option. Mostly, choose this VHCI when bluetooth host run on ESP32, too.
• UART(H4) (BTDM_CTRL_HCI_MODE_UART_H4)
If use external bluetooth host which run on other hardware and use UART as the HCI interface,
choose this option.
HCI UART(H4) Options Contains:

• CONFIG_BTDM_CTRL_HCI_UART_BAUDRATE
• CONFIG_BTDM_CTRL_HCI_UART_NO
CONFIG_BTDM_CTRL_HCI_UART_NO
UART Number for HCI
Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller > HCI
UART(H4) Options
Uart number for HCI. The available uart is UART1 and UART2.
Range:
• from 1 to 2 if BTDM_CTRL_HCI_MODE_UART_H4 && CONFIG_BT_ENABLED
Default value:
• 1 if BTDM_CTRL_HCI_MODE_UART_H4 && CONFIG_BT_ENABLED

CONFIG_BTDM_CTRL_HCI_UART_BAUDRATE
UART Baudrate for HCI
Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller > HCI
UART(H4) Options
UART Baudrate for HCI. Please use standard baudrate.
Range:
• from 115200 to 921600 if BTDM_CTRL_HCI_MODE_UART_H4 && CON-
FIG_BT_ENABLED
Default value:
• 921600 if BTDM_CTRL_HCI_MODE_UART_H4 && CONFIG_BT_ENABLED
MODEM SLEEP Options Contains:

• CONFIG_BTDM_CTRL_LOW_POWER_CLOCK
• CONFIG_BTDM_CTRL_MODEM_SLEEP
CONFIG_BTDM_CTRL_MODEM_SLEEP
Bluetooth modem sleep
Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller > MODEM
SLEEP Options
Enable/disable bluetooth controller low power mode.
Default value:
• Yes (enabled) if CONFIG_BT_ENABLED
CONFIG_BTDM_CTRL_MODEM_SLEEP_MODE
Bluetooth Modem sleep mode
SLEEP Options > CONFIG_BTDM_CTRL_MODEM_SLEEP
To select which strategy to use for modem sleep
Available options:
• ORIG Mode(sleep with low power clock) (BTDM_CTRL_MODEM_SLEEP_MODE_ORIG)
ORIG mode is a bluetooth sleep mode that can be used for dual mode controller. In this mode,
bluetooth controller sleeps between BR/EDR frames and BLE events. A low power clock is
used to maintain bluetooth reference clock.
• EVED Mode(For internal test only) (BTDM_CTRL_MODEM_SLEEP_MODE_EVED)
EVED mode is for BLE only and is only for internal test. Do not use it for production. this
mode is not compatible with DFS nor light sleep
CONFIG_BTDM_CTRL_LOW_POWER_CLOCK
Bluetooth low power clock
SLEEP Options
Select the low power clock source for bluetooth controller. Bluetooth low power clock is the clock source
to maintain time in sleep mode.
• Main crystal option provides good accuracy and can support Dynamic Frequency Scaling to be
used with Bluetooth modem sleep. Light sleep is not supported.

• External 32kHz crystal option allows user to use a 32.768kHz crystal as Bluetooth low power
clock. This option is allowed as long as External 32kHz crystal is configured as the system RTC
clock source. This option provides good accuracy and supports Bluetooth modem sleep to be used
alongside Dynamic Frequency Scaling or light sleep.
Available options:
• Main crystal (BTDM_CTRL_LPCLK_SEL_MAIN_XTAL)
Main crystal can be used as low power clock for bluetooth modem sleep. If this option is
selected, bluetooth modem sleep can work under Dynamic Frequency Scaling(DFS) enabled,
but cannot work when light sleep is enabled. Main crystal has a good performance in accuracy
as the bluetooth low power clock source.
• External 32kHz crystal (BTDM_CTRL_LPCLK_SEL_EXT_32K_XTAL)
External 32kHz crystal has a nominal frequency of 32.768kHz and provides good frequency
stability. If used as Bluetooth low power clock, External 32kHz can support Bluetooth modem
sleep to be used with both DFS and light sleep.
CONFIG_BTDM_BLE_SLEEP_CLOCK_ACCURACY
BLE Sleep Clock Accuracy
BLE Sleep Clock Accuracy(SCA) for the local device is used to estimate window widening in BLE con-
nection events. With a lower level of clock accuracy(e.g. 500ppm over 250ppm), the slave needs a larger
RX window to synchronize with master in each anchor point, thus resulting in an increase of power con-
sumption but a higher level of robustness in keeping connected. According to the requirements of Blue-
tooth Core specification 4.2, the worst-case accuracy of Classic Bluetooth low power oscialltor(LPO)
is +/-250ppm in STANDBY and in low power modes such as sniff. For BLE the worst-case SCA is
+/-500ppm.
• 151ppm to 250ppm option is the default value for Bluetooth Dual mode
• 251ppm to 500ppm option can be used in BLE only mode when using external 32kHz crystal as
low power clock. This option is provided in case that BLE sleep clock has a lower level of
accuracy, or other error sources contribute to the inaccurate timing during sleep.
Available options:
• 251ppm to 500ppm (BTDM_BLE_DEFAULT_SCA_500PPM)
• 151ppm to 250ppm (BTDM_BLE_DEFAULT_SCA_250PPM)
CONFIG_BTDM_BLE_SCAN_DUPL
BLE Scan Duplicate Options
This select enables parameters setting of BLE scan duplicate.
Default value:
• Yes (enabled) if (BTDM_CTRL_MODE_BTDM || BTDM_CTRL_MODE_BLE_ONLY)
CONFIG_BTDM_SCAN_DUPL_TYPE
Scan Duplicate Type
FIG_BTDM_BLE_SCAN_DUPL
Scan duplicate have three ways. one is Scan Duplicate By Device Address , This way is to use advertiser
address filtering. The adv packet of the same address is only allowed to be reported once. Another way
is Scan Duplicate By Device Address And Advertising Data . This way is to use advertising data and
device address filtering. All different adv packets with the same address are allowed to be reported. The

last way is Scan Duplicate By Advertising Data . This way is to use advertising data filtering. All
same advertising data only allow to be reported once even though they are from different devices.
Available options:
• Scan Duplicate By Device Address (BTDM_SCAN_DUPL_TYPE_DEVICE)
This way is to use advertiser address filtering. The adv packet of the same address is only
allowed to be reported once
• Scan Duplicate By Advertising Data (BTDM_SCAN_DUPL_TYPE_DATA)
This way is to use advertising data filtering. All same advertising data only allow to be reported
once even though they are from different devices.
• Scan Duplicate By Device Address And Advertising Data
(BTDM_SCAN_DUPL_TYPE_DATA_DEVICE)
This way is to use advertising data and device address filtering. All different adv packets with
the same address are allowed to be reported.
CONFIG_BTDM_SCAN_DUPL_CACHE_SIZE
Maximum number of devices in scan duplicate filter
Maximum number of devices which can be recorded in scan duplicate filter. When the maximum amount
of device in the filter is reached, the cache will be refreshed.
Range:
• from 10 to 1000 if CONFIG_BTDM_BLE_SCAN_DUPL && CONFIG_BT_ENABLED
Default value:
• 200 if CONFIG_BTDM_BLE_SCAN_DUPL && CONFIG_BT_ENABLED
CONFIG_BTDM_BLE_MESH_SCAN_DUPL_EN
Special duplicate scan mechanism for BLE Mesh scan
This enables the BLE scan duplicate for special BLE Mesh scan.
Default value:
• No (disabled) if CONFIG_BTDM_BLE_SCAN_DUPL && CONFIG_BT_ENABLED
CONFIG_BTDM_MESH_DUPL_SCAN_CACHE_SIZE
Maximum number of Mesh adv packets in scan duplicate filter
FIG_BTDM_BLE_SCAN_DUPL > CONFIG_BTDM_BLE_MESH_SCAN_DUPL_EN
Maximum number of adv packets which can be recorded in duplicate scan cache for BLE Mesh. When
the maximum amount of device in the filter is reached, the cache will be refreshed.
Range:
• from 10 to 1000 if CONFIG_BTDM_BLE_MESH_SCAN_DUPL_EN && CON-
FIG_BT_ENABLED
Default value:
• 200 if CONFIG_BTDM_BLE_MESH_SCAN_DUPL_EN && CONFIG_BT_ENABLED
CONFIG_BTDM_CTRL_FULL_SCAN_SUPPORTED

BLE full scan feature supported

The full scan function is mainly used to provide BLE scan performance. This is required for scenes with
high scan performance requirements, such as BLE Mesh scenes.
Default value:
• Yes (enabled) if (BTDM_CTRL_MODE_BLE_ONLY || BTDM_CTRL_MODE_BTDM)
CONFIG_BTDM_BLE_ADV_REPORT_FLOW_CTRL_SUPP
BLE adv report flow control supported
The function is mainly used to enable flow control for advertising reports. When it is enabled, advertising
reports will be discarded by the controller if the number of unprocessed advertising reports exceeds the
size of BLE adv report flow control.
Default value:
• Yes (enabled) if (BTDM_CTRL_MODE_BTDM || BTDM_CTRL_MODE_BLE_ONLY)
CONFIG_BTDM_BLE_ADV_REPORT_FLOW_CTRL_NUM
BLE adv report flow control number
FIG_BTDM_BLE_ADV_REPORT_FLOW_CTRL_SUPP
The number of unprocessed advertising report that Bluedroid can save.If you set
BTDM_BLE_ADV_REPORT_FLOW_CTRL_NUM to a small value, this may cause adv packets
lost. If you set BTDM_BLE_ADV_REPORT_FLOW_CTRL_NUM to a large value, Bluedroid
may cache a lot of adv packets and this may cause system memory run out. For example,
if you set it to 50, the maximum memory consumed by host is 35 * 50 bytes. Please set
BTDM_BLE_ADV_REPORT_FLOW_CTRL_NUM according to your system free memory and
handle adv packets as fast as possible, otherwise it will cause adv packets lost.
Range:
• from 50 to 1000 if CONFIG_BTDM_BLE_ADV_REPORT_FLOW_CTRL_SUPP && CON-
FIG_BT_ENABLED
Default value:
• 100 if CONFIG_BTDM_BLE_ADV_REPORT_FLOW_CTRL_SUPP && CON-
FIG_BT_ENABLED
CONFIG_BTDM_BLE_ADV_REPORT_DISCARD_THRSHOLD
BLE adv lost event threshold value
FIG_BTDM_BLE_ADV_REPORT_FLOW_CTRL_SUPP
When adv report flow control is enabled, The ADV lost event will be generated when the number of
ADV packets lost in the controller reaches this threshold. It is better to set a larger value. If you set
BTDM_BLE_ADV_REPORT_DISCARD_THRSHOLD to a small value or printf every adv lost event, it
may cause adv packets lost more.
Range:
• from 1 to 1000 if CONFIG_BTDM_BLE_ADV_REPORT_FLOW_CTRL_SUPP && CON-
FIG_BT_ENABLED
Default value:

• 20 if CONFIG_BTDM_BLE_ADV_REPORT_FLOW_CTRL_SUPP && CON-

FIG_BT_ENABLED
CONFIG_BTDM_CTRL_HLI
High level interrupt
Using Level 4 interrupt for Bluetooth.
Default value:
• Yes (enabled) if CONFIG_BT_ENABLED && CONFIG_BT_ENABLED
CONFIG_BT_HOST
Bluetooth Host
Found in: Component config > Bluetooth > CONFIG_BT_ENABLED
This helps to choose Bluetooth host stack
Available options:
• Bluedroid - Dual-mode (BT_BLUEDROID_ENABLED)
This option is recommended for classic Bluetooth or for dual-mode usecases
• NimBLE - BLE only (BT_NIMBLE_ENABLED)
This option is recommended for BLE only usecases to save on memory
• Controller Only (BT_CONTROLLER_ONLY)
This option is recommended when you want to communicate directly with the controller (with-
out any host) or when you are using any other host stack not supported by Espressif (not
mentioned here).
Bluedroid Options Contains:

• CONFIG_BT_BLE_HOST_QUEUE_CONG_CHECK
• CONFIG_BT_BLUEDROID_MEM_DEBUG
• CONFIG_BT_BTU_TASK_STACK_SIZE
• CONFIG_BT_BTC_TASK_STACK_SIZE
• CONFIG_BT_BLE_ENABLED
• BT DEBUG LOG LEVEL
• CONFIG_BT_ACL_CONNECTIONS
• CONFIG_BT_ALLOCATION_FROM_SPIRAM_FIRST
• CONFIG_BT_CLASSIC_ENABLED
• CONFIG_BT_HID_ENABLED
• CONFIG_BT_STACK_NO_LOG
• CONFIG_BT_MULTI_CONNECTION_ENBALE
• CONFIG_BT_MAX_DEVICE_NAME_LEN
• CONFIG_BT_BLE_ACT_SCAN_REP_ADV_SCAN
• CONFIG_BT_SSP_ENABLED
• CONFIG_BT_BLUEDROID_PINNED_TO_CORE_CHOICE
• CONFIG_BT_BLE_ESTAB_LINK_CONN_TOUT
• CONFIG_BT_BLE_RPA_SUPPORTED
• CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY
• CONFIG_BT_HFP_WBS_ENABLE
CONFIG_BT_BTC_TASK_STACK_SIZE
Bluetooth event (callback to application) task stack size
Found in: Component config > Bluetooth > Bluedroid Options

This select btc task stack size

Default value:
• 3072 if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_BLUEDROID_PINNED_TO_CORE_CHOICE
The cpu core which Bluedroid run
Which the cpu core to run Bluedroid. Can choose core0 and core1. Can not specify no-affinity.
Available options:
• Core 0 (PRO CPU) (BT_BLUEDROID_PINNED_TO_CORE_0)
• Core 1 (APP CPU) (BT_BLUEDROID_PINNED_TO_CORE_1)
CONFIG_BT_BTU_TASK_STACK_SIZE
Bluetooth Bluedroid Host Stack task stack size
This select btu task stack size
Default value:
CONFIG_BT_BLUEDROID_MEM_DEBUG
Bluedroid memory debug
Bluedroid memory debug
Default value:
• No (disabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_CLASSIC_ENABLED
Classic Bluetooth
For now this option needs SMP_ENABLE to be set to yes
Default value:
CONFIG_BT_A2DP_ENABLE
A2DP
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_CLASSIC_ENABLED
Advanced Audio Distrubution Profile
Default value:
• No (disabled) if CONFIG_BT_CLASSIC_ENABLED && BT_BLUEDROID_ENABLED

CONFIG_BT_SPP_ENABLED
SPP
This enables the Serial Port Profile
Default value:
CONFIG_BT_HFP_ENABLE
Hands Free/Handset Profile
Default value:
CONFIG_BT_HFP_ROLE
Hands-free Profile Role configuration
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_CLASSIC_ENABLED >
Available options:
• Hands Free Unit (BT_HFP_CLIENT_ENABLE)
• Audio Gateway (BT_HFP_AG_ENABLE)
CONFIG_BT_HFP_AUDIO_DATA_PATH
audio(SCO) data path
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_CLASSIC_ENABLED >
SCO data path, i.e. HCI or PCM. This option is set using API esp_bredr_sco_datapath_set in
Bluetooth host. Default SCO data path can also be set in Bluetooth Controller.
Available options:
• PCM (BT_HFP_AUDIO_DATA_PATH_PCM)
• HCI (BT_HFP_AUDIO_DATA_PATH_HCI)
CONFIG_BT_HFP_WBS_ENABLE
Wide Band Speech
This enables Wide Band Speech. Should disable it when SCO data path is PCM. Otherwise there will
be no data transmited via GPIOs.
Default value:
• Yes (enabled) if BT_HFP_AUDIO_DATA_PATH_HCI &&
BT_BLUEDROID_ENABLED
CONFIG_BT_HID_ENABLED
Classic BT HID
This enables the BT HID Host

Default value:
CONFIG_BT_HID_ROLE
Profile Role configuration
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_HID_ENABLED
Available options:
• Classic BT HID Host (BT_HID_HOST_ENABLED)
This enables the BT HID Host
• Classic BT HID Device (BT_HID_DEVICE_ENABLED)
This enables the BT HID Device
CONFIG_BT_SSP_ENABLED
Secure Simple Pairing
This enables the Secure Simple Pairing. If disable this option, Bluedroid will only support Legacy Pairing
Default value:
• Yes (enabled) if CONFIG_BT_CLASSIC_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_BLE_ENABLED
Bluetooth Low Energy
This enables Bluetooth Low Energy
Default value:
• Yes (enabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_GATTS_ENABLE
Include GATT server module(GATTS)
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED
This option can be disabled when the app work only on gatt client mode
Default value:
• Yes (enabled) if CONFIG_BT_BLE_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_GATTS_PPCP_CHAR_GAP
Enable Peripheral Preferred Connection Parameters characteristic in GAP service
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED > CON-
FIG_BT_GATTS_ENABLE
This enables Peripheral Preferred Connection Parameters characteristic (UUID: 0x2A04) in GAP
service that has connection parameters like min/max connection interval, slave latency and supervision
timeout multiplier
Default value:
• No (disabled) if CONFIG_BT_GATTS_ENABLE && BT_BLUEDROID_ENABLED

CONFIG_BT_BLE_BLUFI_ENABLE
Include blufi function
FIG_BT_GATTS_ENABLE
This option can be close when the app does not require blufi function.
Default value:
• No (disabled) if CONFIG_BT_GATTS_ENABLE && BT_BLUEDROID_ENABLED
CONFIG_BT_GATT_MAX_SR_PROFILES
Max GATT Server Profiles
FIG_BT_GATTS_ENABLE
Maximum GATT Server Profiles Count
Range:
• from 1 to 32 if CONFIG_BT_GATTS_ENABLE && BT_BLUEDROID_ENABLED &&
Default value:
• 8 if CONFIG_BT_GATTS_ENABLE && BT_BLUEDROID_ENABLED &&
CONFIG_BT_GATTS_SEND_SERVICE_CHANGE_MODE
GATTS Service Change Mode
FIG_BT_GATTS_ENABLE
Service change indication mode for GATT Server.
Available options:
• GATTS manually send service change indication (BT_GATTS_SEND_SERVICE_CHANGE_MANUAL)
Manually send service change indication through API
esp_ble_gatts_send_service_change_indication()
• GATTS automatically send service change indication
(BT_GATTS_SEND_SERVICE_CHANGE_AUTO)
Let Bluedroid handle the service change indication internally
CONFIG_BT_GATTC_ENABLE
Include GATT client module(GATTC)
This option can be close when the app work only on gatt server mode
Default value:
CONFIG_BT_GATTC_CACHE_NVS_FLASH
Save gattc cache data to nvs flash
FIG_BT_GATTC_ENABLE
This select can save gattc cache data to nvs flash

Default value:
• No (disabled) if CONFIG_BT_GATTC_ENABLE && BT_BLUEDROID_ENABLED
CONFIG_BT_GATTC_CONNECT_RETRY_COUNT
The number of attempts to reconnect if the connection establishment failed
FIG_BT_GATTC_ENABLE
The number of attempts to reconnect if the connection establishment failed
Range:
• from 0 to 7 if CONFIG_BT_GATTC_ENABLE && BT_BLUEDROID_ENABLED
Default value:
• 3 if CONFIG_BT_GATTC_ENABLE && BT_BLUEDROID_ENABLED
CONFIG_BT_BLE_SMP_ENABLE
Include BLE security module(SMP)
This option can be close when the app not used the ble security connect.
Default value:
CONFIG_BT_SMP_SLAVE_CON_PARAMS_UPD_ENABLE
Slave enable connection parameters update during pairing
FIG_BT_BLE_SMP_ENABLE
In order to reduce the pairing time, slave actively initiates connection parameters update during pairing.
Default value:
• No (disabled) if CONFIG_BT_BLE_SMP_ENABLE && BT_BLUEDROID_ENABLED
CONFIG_BT_STACK_NO_LOG
Disable BT debug logs (minimize bin size)
This select can save the rodata code size
Default value:
BT DEBUG LOG LEVEL Contains:

• CONFIG_BT_LOG_A2D_TRACE_LEVEL
• CONFIG_BT_LOG_APPL_TRACE_LEVEL
• CONFIG_BT_LOG_AVCT_TRACE_LEVEL
• CONFIG_BT_LOG_AVDT_TRACE_LEVEL
• CONFIG_BT_LOG_AVRC_TRACE_LEVEL
• CONFIG_BT_LOG_BLUFI_TRACE_LEVEL
• CONFIG_BT_LOG_BNEP_TRACE_LEVEL
• CONFIG_BT_LOG_BTC_TRACE_LEVEL
• CONFIG_BT_LOG_BTIF_TRACE_LEVEL
• CONFIG_BT_LOG_BTM_TRACE_LEVEL

• CONFIG_BT_LOG_GAP_TRACE_LEVEL
• CONFIG_BT_LOG_GATT_TRACE_LEVEL
• CONFIG_BT_LOG_HCI_TRACE_LEVEL
• CONFIG_BT_LOG_HID_TRACE_LEVEL
• CONFIG_BT_LOG_L2CAP_TRACE_LEVEL
• CONFIG_BT_LOG_MCA_TRACE_LEVEL
• CONFIG_BT_LOG_OSI_TRACE_LEVEL
• CONFIG_BT_LOG_PAN_TRACE_LEVEL
• CONFIG_BT_LOG_RFCOMM_TRACE_LEVEL
• CONFIG_BT_LOG_SDP_TRACE_LEVEL
• CONFIG_BT_LOG_SMP_TRACE_LEVEL
CONFIG_BT_LOG_HCI_TRACE_LEVEL
HCI layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for HCI layer
Available options:
• NONE (BT_LOG_HCI_TRACE_LEVEL_NONE)
• ERROR (BT_LOG_HCI_TRACE_LEVEL_ERROR)
• WARNING (BT_LOG_HCI_TRACE_LEVEL_WARNING)
• API (BT_LOG_HCI_TRACE_LEVEL_API)
• EVENT (BT_LOG_HCI_TRACE_LEVEL_EVENT)
• DEBUG (BT_LOG_HCI_TRACE_LEVEL_DEBUG)
• VERBOSE (BT_LOG_HCI_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_BTM_TRACE_LEVEL
BTM layer
Define BT trace level for BTM layer
Available options:
• NONE (BT_LOG_BTM_TRACE_LEVEL_NONE)
• ERROR (BT_LOG_BTM_TRACE_LEVEL_ERROR)
• WARNING (BT_LOG_BTM_TRACE_LEVEL_WARNING)
• API (BT_LOG_BTM_TRACE_LEVEL_API)
• EVENT (BT_LOG_BTM_TRACE_LEVEL_EVENT)
• DEBUG (BT_LOG_BTM_TRACE_LEVEL_DEBUG)
• VERBOSE (BT_LOG_BTM_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_L2CAP_TRACE_LEVEL
L2CAP layer
Define BT trace level for L2CAP layer
Available options:
• NONE (BT_LOG_L2CAP_TRACE_LEVEL_NONE)
• ERROR (BT_LOG_L2CAP_TRACE_LEVEL_ERROR)
• WARNING (BT_LOG_L2CAP_TRACE_LEVEL_WARNING)
• API (BT_LOG_L2CAP_TRACE_LEVEL_API)
• EVENT (BT_LOG_L2CAP_TRACE_LEVEL_EVENT)
• DEBUG (BT_LOG_L2CAP_TRACE_LEVEL_DEBUG)
• VERBOSE (BT_LOG_L2CAP_TRACE_LEVEL_VERBOSE)

CONFIG_BT_LOG_RFCOMM_TRACE_LEVEL
RFCOMM layer
Define BT trace level for RFCOMM layer
Available options:
• NONE (BT_LOG_RFCOMM_TRACE_LEVEL_NONE)
• ERROR (BT_LOG_RFCOMM_TRACE_LEVEL_ERROR)
• WARNING (BT_LOG_RFCOMM_TRACE_LEVEL_WARNING)
• API (BT_LOG_RFCOMM_TRACE_LEVEL_API)
• EVENT (BT_LOG_RFCOMM_TRACE_LEVEL_EVENT)
• DEBUG (BT_LOG_RFCOMM_TRACE_LEVEL_DEBUG)
• VERBOSE (BT_LOG_RFCOMM_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_SDP_TRACE_LEVEL
SDP layer
Define BT trace level for SDP layer
Available options:
• NONE (BT_LOG_SDP_TRACE_LEVEL_NONE)
• ERROR (BT_LOG_SDP_TRACE_LEVEL_ERROR)
• WARNING (BT_LOG_SDP_TRACE_LEVEL_WARNING)
• API (BT_LOG_SDP_TRACE_LEVEL_API)
• EVENT (BT_LOG_SDP_TRACE_LEVEL_EVENT)
• DEBUG (BT_LOG_SDP_TRACE_LEVEL_DEBUG)
• VERBOSE (BT_LOG_SDP_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_GAP_TRACE_LEVEL
GAP layer
Define BT trace level for GAP layer
Available options:
• NONE (BT_LOG_GAP_TRACE_LEVEL_NONE)
• ERROR (BT_LOG_GAP_TRACE_LEVEL_ERROR)
• WARNING (BT_LOG_GAP_TRACE_LEVEL_WARNING)
• API (BT_LOG_GAP_TRACE_LEVEL_API)
• EVENT (BT_LOG_GAP_TRACE_LEVEL_EVENT)
• DEBUG (BT_LOG_GAP_TRACE_LEVEL_DEBUG)
• VERBOSE (BT_LOG_GAP_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_BNEP_TRACE_LEVEL
BNEP layer
Define BT trace level for BNEP layer
Available options:
• NONE (BT_LOG_BNEP_TRACE_LEVEL_NONE)
• ERROR (BT_LOG_BNEP_TRACE_LEVEL_ERROR)
• WARNING (BT_LOG_BNEP_TRACE_LEVEL_WARNING)
• API (BT_LOG_BNEP_TRACE_LEVEL_API)

• EVENT (BT_LOG_BNEP_TRACE_LEVEL_EVENT)
• DEBUG (BT_LOG_BNEP_TRACE_LEVEL_DEBUG)
• VERBOSE (BT_LOG_BNEP_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_PAN_TRACE_LEVEL
PAN layer
Define BT trace level for PAN layer
Available options:
• NONE (BT_LOG_PAN_TRACE_LEVEL_NONE)
• ERROR (BT_LOG_PAN_TRACE_LEVEL_ERROR)
• WARNING (BT_LOG_PAN_TRACE_LEVEL_WARNING)
• API (BT_LOG_PAN_TRACE_LEVEL_API)
• EVENT (BT_LOG_PAN_TRACE_LEVEL_EVENT)
• DEBUG (BT_LOG_PAN_TRACE_LEVEL_DEBUG)
• VERBOSE (BT_LOG_PAN_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_A2D_TRACE_LEVEL
A2D layer
Define BT trace level for A2D layer
Available options:
• NONE (BT_LOG_A2D_TRACE_LEVEL_NONE)
• ERROR (BT_LOG_A2D_TRACE_LEVEL_ERROR)
• WARNING (BT_LOG_A2D_TRACE_LEVEL_WARNING)
• API (BT_LOG_A2D_TRACE_LEVEL_API)
• EVENT (BT_LOG_A2D_TRACE_LEVEL_EVENT)
• DEBUG (BT_LOG_A2D_TRACE_LEVEL_DEBUG)
• VERBOSE (BT_LOG_A2D_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_AVDT_TRACE_LEVEL
AVDT layer
Define BT trace level for AVDT layer
Available options:
• NONE (BT_LOG_AVDT_TRACE_LEVEL_NONE)
• ERROR (BT_LOG_AVDT_TRACE_LEVEL_ERROR)
• WARNING (BT_LOG_AVDT_TRACE_LEVEL_WARNING)
• API (BT_LOG_AVDT_TRACE_LEVEL_API)
• EVENT (BT_LOG_AVDT_TRACE_LEVEL_EVENT)
• DEBUG (BT_LOG_AVDT_TRACE_LEVEL_DEBUG)
• VERBOSE (BT_LOG_AVDT_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_AVCT_TRACE_LEVEL
AVCT layer
Define BT trace level for AVCT layer

Available options:
• NONE (BT_LOG_AVCT_TRACE_LEVEL_NONE)
• ERROR (BT_LOG_AVCT_TRACE_LEVEL_ERROR)
• WARNING (BT_LOG_AVCT_TRACE_LEVEL_WARNING)
• API (BT_LOG_AVCT_TRACE_LEVEL_API)
• EVENT (BT_LOG_AVCT_TRACE_LEVEL_EVENT)
• DEBUG (BT_LOG_AVCT_TRACE_LEVEL_DEBUG)
• VERBOSE (BT_LOG_AVCT_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_AVRC_TRACE_LEVEL
AVRC layer
Define BT trace level for AVRC layer
Available options:
• NONE (BT_LOG_AVRC_TRACE_LEVEL_NONE)
• ERROR (BT_LOG_AVRC_TRACE_LEVEL_ERROR)
• WARNING (BT_LOG_AVRC_TRACE_LEVEL_WARNING)
• API (BT_LOG_AVRC_TRACE_LEVEL_API)
• EVENT (BT_LOG_AVRC_TRACE_LEVEL_EVENT)
• DEBUG (BT_LOG_AVRC_TRACE_LEVEL_DEBUG)
• VERBOSE (BT_LOG_AVRC_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_MCA_TRACE_LEVEL
MCA layer
Define BT trace level for MCA layer
Available options:
• NONE (BT_LOG_MCA_TRACE_LEVEL_NONE)
• ERROR (BT_LOG_MCA_TRACE_LEVEL_ERROR)
• WARNING (BT_LOG_MCA_TRACE_LEVEL_WARNING)
• API (BT_LOG_MCA_TRACE_LEVEL_API)
• EVENT (BT_LOG_MCA_TRACE_LEVEL_EVENT)
• DEBUG (BT_LOG_MCA_TRACE_LEVEL_DEBUG)
• VERBOSE (BT_LOG_MCA_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_HID_TRACE_LEVEL
HID layer
Define BT trace level for HID layer
Available options:
• NONE (BT_LOG_HID_TRACE_LEVEL_NONE)
• ERROR (BT_LOG_HID_TRACE_LEVEL_ERROR)
• WARNING (BT_LOG_HID_TRACE_LEVEL_WARNING)
• API (BT_LOG_HID_TRACE_LEVEL_API)
• EVENT (BT_LOG_HID_TRACE_LEVEL_EVENT)
• DEBUG (BT_LOG_HID_TRACE_LEVEL_DEBUG)
• VERBOSE (BT_LOG_HID_TRACE_LEVEL_VERBOSE)

CONFIG_BT_LOG_APPL_TRACE_LEVEL
APPL layer
Define BT trace level for APPL layer
Available options:
• NONE (BT_LOG_APPL_TRACE_LEVEL_NONE)
• ERROR (BT_LOG_APPL_TRACE_LEVEL_ERROR)
• WARNING (BT_LOG_APPL_TRACE_LEVEL_WARNING)
• API (BT_LOG_APPL_TRACE_LEVEL_API)
• EVENT (BT_LOG_APPL_TRACE_LEVEL_EVENT)
• DEBUG (BT_LOG_APPL_TRACE_LEVEL_DEBUG)
• VERBOSE (BT_LOG_APPL_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_GATT_TRACE_LEVEL
GATT layer
Define BT trace level for GATT layer
Available options:
• NONE (BT_LOG_GATT_TRACE_LEVEL_NONE)
• ERROR (BT_LOG_GATT_TRACE_LEVEL_ERROR)
• WARNING (BT_LOG_GATT_TRACE_LEVEL_WARNING)
• API (BT_LOG_GATT_TRACE_LEVEL_API)
• EVENT (BT_LOG_GATT_TRACE_LEVEL_EVENT)
• DEBUG (BT_LOG_GATT_TRACE_LEVEL_DEBUG)
• VERBOSE (BT_LOG_GATT_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_SMP_TRACE_LEVEL
SMP layer
Define BT trace level for SMP layer
Available options:
• NONE (BT_LOG_SMP_TRACE_LEVEL_NONE)
• ERROR (BT_LOG_SMP_TRACE_LEVEL_ERROR)
• WARNING (BT_LOG_SMP_TRACE_LEVEL_WARNING)
• API (BT_LOG_SMP_TRACE_LEVEL_API)
• EVENT (BT_LOG_SMP_TRACE_LEVEL_EVENT)
• DEBUG (BT_LOG_SMP_TRACE_LEVEL_DEBUG)
• VERBOSE (BT_LOG_SMP_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_BTIF_TRACE_LEVEL
BTIF layer
Define BT trace level for BTIF layer
Available options:
• NONE (BT_LOG_BTIF_TRACE_LEVEL_NONE)
• ERROR (BT_LOG_BTIF_TRACE_LEVEL_ERROR)
• WARNING (BT_LOG_BTIF_TRACE_LEVEL_WARNING)
• API (BT_LOG_BTIF_TRACE_LEVEL_API)

• EVENT (BT_LOG_BTIF_TRACE_LEVEL_EVENT)
• DEBUG (BT_LOG_BTIF_TRACE_LEVEL_DEBUG)
• VERBOSE (BT_LOG_BTIF_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_BTC_TRACE_LEVEL
BTC layer
Define BT trace level for BTC layer
Available options:
• NONE (BT_LOG_BTC_TRACE_LEVEL_NONE)
• ERROR (BT_LOG_BTC_TRACE_LEVEL_ERROR)
• WARNING (BT_LOG_BTC_TRACE_LEVEL_WARNING)
• API (BT_LOG_BTC_TRACE_LEVEL_API)
• EVENT (BT_LOG_BTC_TRACE_LEVEL_EVENT)
• DEBUG (BT_LOG_BTC_TRACE_LEVEL_DEBUG)
• VERBOSE (BT_LOG_BTC_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_OSI_TRACE_LEVEL
OSI layer
Define BT trace level for OSI layer
Available options:
• NONE (BT_LOG_OSI_TRACE_LEVEL_NONE)
• ERROR (BT_LOG_OSI_TRACE_LEVEL_ERROR)
• WARNING (BT_LOG_OSI_TRACE_LEVEL_WARNING)
• API (BT_LOG_OSI_TRACE_LEVEL_API)
• EVENT (BT_LOG_OSI_TRACE_LEVEL_EVENT)
• DEBUG (BT_LOG_OSI_TRACE_LEVEL_DEBUG)
• VERBOSE (BT_LOG_OSI_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_BLUFI_TRACE_LEVEL
BLUFI layer
Define BT trace level for BLUFI layer
Available options:
• NONE (BT_LOG_BLUFI_TRACE_LEVEL_NONE)
• ERROR (BT_LOG_BLUFI_TRACE_LEVEL_ERROR)
• WARNING (BT_LOG_BLUFI_TRACE_LEVEL_WARNING)
• API (BT_LOG_BLUFI_TRACE_LEVEL_API)
• EVENT (BT_LOG_BLUFI_TRACE_LEVEL_EVENT)
• DEBUG (BT_LOG_BLUFI_TRACE_LEVEL_DEBUG)
• VERBOSE (BT_LOG_BLUFI_TRACE_LEVEL_VERBOSE)
CONFIG_BT_ACL_CONNECTIONS
BT/BLE MAX ACL CONNECTIONS(1~7)
Maximum BT/BLE connection count

Range:
• from 1 to 7 if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
Default value:
CONFIG_BT_MULTI_CONNECTION_ENBALE
Enable BLE multi-conections
Enable this option if there are multiple connections
Default value:
• Yes (enabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_ALLOCATION_FROM_SPIRAM_FIRST
BT/BLE will first malloc the memory from the PSRAM
This select can save the internal RAM if there have the PSRAM
Default value:
CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY
Use dynamic memory allocation in BT/BLE stack
This select can make the allocation of memory will become more flexible
Default value:
CONFIG_BT_BLE_HOST_QUEUE_CONG_CHECK
BLE queue congestion check
When scanning and scan duplicate is not enabled, if there are a lot of adv packets around or application
layer handling adv packets is slow, it will cause the controller memory to run out. if enabled, adv packets
will be lost when host queue is congested.
Default value:
CONFIG_BT_BLE_ACT_SCAN_REP_ADV_SCAN
Report adv data and scan response individually when BLE active scan
Originally, when doing BLE active scan, Bluedroid will not report adv to application layer until receive
scan response. This option is used to disable the behavior. When enable this option, Bluedroid will
report adv data or scan response to application layer immediately.
# Memory reserved at start of DRAM for Bluetooth stack
Default value:

• No (disabled) if BT_BLUEDROID_ENABLED && (BTDM_CTRL_MODE_BTDM ||

BTDM_CTRL_MODE_BLE_ONLY) && BT_BLUEDROID_ENABLED
CONFIG_BT_BLE_ESTAB_LINK_CONN_TOUT
Timeout of BLE connection establishment
Bluetooth Connection establishment maximum time, if connection time exceeds this value, the connec-
tion establishment fails, ESP_GATTC_OPEN_EVT or ESP_GATTS_OPEN_EVT is triggered.
Range:
Default value:
CONFIG_BT_MAX_DEVICE_NAME_LEN
length of bluetooth device name
Bluetooth Device name length shall be no larger than 248 octets, If the broadcast data cannot contain
the complete device name, then only the shortname will be displayed, the rest parts that can t fit in will
be truncated.
Range:
Default value:
CONFIG_BT_BLE_RPA_SUPPORTED
Update RPA to Controller
This enables controller RPA list function. For ESP32, ESP32 only support network privacy mode. If
this option is enabled, ESP32 will only accept advertising packets from peer devices that contain private
address, HW will not receive the advertising packets contain identity address after IRK changed. If this
option is disabled, address resolution will be performed in the host, so the functions that require controller
to resolve address in the white list cannot be used. This option is disabled by default on ESP32, please
enable or disable this option according to your own needs.
For ESP32C3 and esp32s3, devices support network privacy mode and device privacy mode, users can
switch the two modes according to their own needs. So this option is enabled by default.
Default value:
NimBLE Options Contains:

• CONFIG_BT_NIMBLE_ACL_BUF_COUNT
• CONFIG_BT_NIMBLE_ACL_BUF_SIZE
• CONFIG_BT_NIMBLE_SVC_GAP_DEVICE_NAME
• CONFIG_BT_NIMBLE_HS_STOP_TIMEOUT_MS
• CONFIG_BT_NIMBLE_ROLE_BROADCASTER
• CONFIG_BT_NIMBLE_ROLE_CENTRAL
• CONFIG_BT_NIMBLE_MESH
• CONFIG_BT_NIMBLE_ROLE_OBSERVER
• CONFIG_BT_NIMBLE_ROLE_PERIPHERAL

• CONFIG_BT_NIMBLE_BLUFI_ENABLE
• CONFIG_BT_NIMBLE_ENABLE_CONN_REATTEMPT
• CONFIG_BT_NIMBLE_USE_ESP_TIMER
• CONFIG_BT_NIMBLE_DEBUG
• CONFIG_BT_NIMBLE_HS_FLOW_CTRL
• CONFIG_BT_NIMBLE_SVC_GAP_APPEARANCE
• CONFIG_BT_NIMBLE_HCI_EVT_BUF_SIZE
• CONFIG_BT_NIMBLE_HCI_EVT_HI_BUF_COUNT
• CONFIG_BT_NIMBLE_HCI_EVT_LO_BUF_COUNT
• CONFIG_BT_NIMBLE_GAP_DEVICE_NAME_MAX_LEN
• CONFIG_BT_NIMBLE_MAX_BONDS
• CONFIG_BT_NIMBLE_MAX_CCCDS
• CONFIG_BT_NIMBLE_MAX_CONNECTIONS
• CONFIG_BT_NIMBLE_L2CAP_COC_MAX_NUM
• CONFIG_BT_NIMBLE_MEM_ALLOC_MODE
• CONFIG_BT_NIMBLE_MSYS1_BLOCK_COUNT
• CONFIG_BT_NIMBLE_LOG_LEVEL
• CONFIG_BT_NIMBLE_TASK_STACK_SIZE
• CONFIG_BT_NIMBLE_CRYPTO_STACK_MBEDTLS
• CONFIG_BT_NIMBLE_NVS_PERSIST
• CONFIG_BT_NIMBLE_ATT_PREFERRED_MTU
• CONFIG_BT_NIMBLE_RPA_TIMEOUT
• CONFIG_BT_NIMBLE_SM_LEGACY
• CONFIG_BT_NIMBLE_SM_SC
• CONFIG_BT_NIMBLE_PINNED_TO_CORE_CHOICE
• CONFIG_BT_NIMBLE_SM_SC_DEBUG_KEYS
CONFIG_BT_NIMBLE_MEM_ALLOC_MODE
Memory allocation strategy
Found in: Component config > Bluetooth > NimBLE Options
Allocation strategy for NimBLE host stack, essentially provides ability to allocate all required dynamic
allocations from,
• Internal DRAM memory only
• External SPIRAM memory only
• Either internal or external memory based on default malloc() behavior in ESP-IDF
• Internal IRAM memory wherever applicable else internal DRAM
Available options:
• Internal memory (BT_NIMBLE_MEM_ALLOC_MODE_INTERNAL)
• External SPIRAM (BT_NIMBLE_MEM_ALLOC_MODE_EXTERNAL)
• Default alloc mode (BT_NIMBLE_MEM_ALLOC_MODE_DEFAULT)
• Internal IRAM (BT_NIMBLE_MEM_ALLOC_MODE_IRAM_8BIT)
Allows to use IRAM memory region as 8bit accessible region.
Every unaligned (8bit or 16bit) access will result in an exception and incur penalty of certain
clock cycles per unaligned read/write.
CONFIG_BT_NIMBLE_LOG_LEVEL
NimBLE Host log verbosity
Select NimBLE log level. Please make a note that the selected NimBLE log verbosity can not exceed
the level set in Component config > Log output > Default log verbosity .
Available options:
• No logs (BT_NIMBLE_LOG_LEVEL_NONE)

• Error logs (BT_NIMBLE_LOG_LEVEL_ERROR)

• Warning logs (BT_NIMBLE_LOG_LEVEL_WARNING)
• Info logs (BT_NIMBLE_LOG_LEVEL_INFO)
• Debug logs (BT_NIMBLE_LOG_LEVEL_DEBUG)
CONFIG_BT_NIMBLE_MAX_CONNECTIONS
Maximum number of concurrent connections
Defines maximum number of concurrent BLE connections. For ESP32, user is expected to configure
BTDM_CTRL_BLE_MAX_CONN from controller menu along with this option. Similarly for ESP32-
C3 or ESP32-S3, user is expected to configure BT_CTRL_BLE_MAX_ACT from controller menu.
Range:
• from 1 to 9 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
Default value:
• 3 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MAX_BONDS
Maximum number of bonds to save across reboots
Defines maximum number of bonds to save for peer security and our security
Default value:
CONFIG_BT_NIMBLE_MAX_CCCDS
Maximum number of CCC descriptors to save across reboots
Defines maximum number of CCC descriptors to save
Default value:
CONFIG_BT_NIMBLE_L2CAP_COC_MAX_NUM
Maximum number of connection oriented channels
Defines maximum number of BLE Connection Oriented Channels. When set to (0), BLE COC is not
compiled in
Range:
Default value:
CONFIG_BT_NIMBLE_PINNED_TO_CORE_CHOICE
The CPU core on which NimBLE host will run
The CPU core on which NimBLE host will run. You can choose Core 0 or Core 1. Cannot specify
no-affinity

Available options:
• Core 0 (PRO CPU) (BT_NIMBLE_PINNED_TO_CORE_0)
• Core 1 (APP CPU) (BT_NIMBLE_PINNED_TO_CORE_1)
CONFIG_BT_NIMBLE_TASK_STACK_SIZE
NimBLE Host task stack size
This configures stack size of NimBLE host task
Default value:
• 5120 if CONFIG_BLE_MESH && BT_NIMBLE_ENABLED &&
BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_ROLE_CENTRAL
Enable BLE Central role
Default value:
• Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_ROLE_PERIPHERAL
Enable BLE Peripheral role
Default value:
CONFIG_BT_NIMBLE_ROLE_BROADCASTER
Enable BLE Broadcaster role
Default value:
CONFIG_BT_NIMBLE_ROLE_OBSERVER
Enable BLE Observer role
Default value:
CONFIG_BT_NIMBLE_NVS_PERSIST
Persist the BLE Bonding keys in NVS
Enable this flag to make bonding persistent across device reboots
Default value:

CONFIG_BT_NIMBLE_SM_LEGACY
Security manager legacy pairing
Enable security manager legacy pairing
Default value:
CONFIG_BT_NIMBLE_SM_SC
Security manager secure connections (4.2)
Enable security manager secure connections
Default value:
CONFIG_BT_NIMBLE_DEBUG
Enable extra runtime asserts and host debugging
This enables extra runtime asserts and host debugging
Default value:
• No (disabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_SM_SC_DEBUG_KEYS
Use predefined public-private key pair
If this option is enabled, SM uses predefined DH key pair as described in Core Specification, Vol. 3,
Part H, 2.3.5.6.1. This allows to decrypt air traffic easily and thus should only be used for debugging.
Default value:
• No (disabled) if CONFIG_BT_NIMBLE_SM_SC && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_SVC_GAP_DEVICE_NAME
BLE GAP default device name
The Device Name characteristic shall contain the name of the device as an UTF-8 string. This name
can be changed by using API ble_svc_gap_device_name_set()
Default value:
• nimble if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_GAP_DEVICE_NAME_MAX_LEN
Maximum length of BLE device name in octets
Device Name characteristic value shall be 0 to 248 octets in length
Default value:

CONFIG_BT_NIMBLE_ATT_PREFERRED_MTU
Preferred MTU size in octets
This is the default value of ATT MTU indicated by the device during an ATT MTU exchange. This
value can be changed using API ble_att_set_preferred_mtu()
Default value:
CONFIG_BT_NIMBLE_SVC_GAP_APPEARANCE
External appearance of the device
Standard BLE GAP Appearance value in HEX format e.g. 0x02C0
Default value:
CONFIG_BT_NIMBLE_ACL_BUF_COUNT
ACL Buffer count
The number of ACL data buffers.
Default value:
CONFIG_BT_NIMBLE_ACL_BUF_SIZE
ACL Buffer size
This is the maximum size of the data portion of HCI ACL data packets. It does not include the HCI
data header (of 4 bytes)
Default value:
CONFIG_BT_NIMBLE_HCI_EVT_BUF_SIZE
HCI Event Buffer size
This is the size of each HCI event buffer in bytes. In case of extended advertising, packets can be
fragmented. 257 bytes is the maximum size of a packet.
Default value:
CONFIG_BT_NIMBLE_HCI_EVT_HI_BUF_COUNT
High Priority HCI Event Buffer count

This is the high priority HCI events buffer size. High-priority event buffers are for everything except
advertising reports. If there are no free high-priority event buffers then host will try to allocate a low-
priority buffer instead
Default value:
CONFIG_BT_NIMBLE_HCI_EVT_LO_BUF_COUNT
Low Priority HCI Event Buffer count
This is the low priority HCI events buffer size. Low-priority event buffers are only used for advertising
reports. If there are no free low-priority event buffers, then an incoming advertising report will get
dropped
Default value:
CONFIG_BT_NIMBLE_MSYS1_BLOCK_COUNT
MSYS_1 Block Count
MSYS is a system level mbuf registry. For prepare write & prepare responses MBUFs are allocated
out of msys_1 pool. For NIMBLE_MESH enabled cases, this block count is increased by 8 than user
defined count.
Default value:
CONFIG_BT_NIMBLE_HS_FLOW_CTRL
Enable Host Flow control
Enable Host Flow control
Default value:
CONFIG_BT_NIMBLE_HS_FLOW_CTRL_ITVL
Host Flow control interval
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_HS_FLOW_CTRL
Host flow control interval in msecs
Default value:
• 1000 if CONFIG_BT_NIMBLE_HS_FLOW_CTRL && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_HS_FLOW_CTRL_THRESH
Host Flow control threshold
Host flow control threshold, if the number of free buffers are at or below this threshold, send an imme-
diate number-of-completed-packets event
Default value:

• 2 if CONFIG_BT_NIMBLE_HS_FLOW_CTRL && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_HS_FLOW_CTRL_TX_ON_DISCONNECT
Host Flow control on disconnect
Enable this option to send number-of-completed-packets event to controller after disconnection
Default value:
• Yes (enabled) if CONFIG_BT_NIMBLE_HS_FLOW_CTRL && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_RPA_TIMEOUT
RPA timeout in seconds
Time interval between RPA address change. This is applicable in case of Host based RPA
Range:
Default value:
CONFIG_BT_NIMBLE_MESH
Enable BLE mesh functionality
Enable BLE Mesh functionality
Default value:
Contains:
• CONFIG_BT_NIMBLE_MESH_PROVISIONER
• CONFIG_BT_NIMBLE_MESH_PROV
• CONFIG_BT_NIMBLE_MESH_GATT_PROXY
• CONFIG_BT_NIMBLE_MESH_FRIEND
• CONFIG_BT_NIMBLE_MESH_LOW_POWER
• CONFIG_BT_NIMBLE_MESH_PROXY
• CONFIG_BT_NIMBLE_MESH_RELAY
• CONFIG_BT_NIMBLE_MESH_DEVICE_NAME
• CONFIG_BT_NIMBLE_MESH_NODE_COUNT
CONFIG_BT_NIMBLE_MESH_PROXY
Enable mesh proxy functionality
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH
Enable proxy. This is automatically set whenever NIMBLE_MESH_PB_GATT or NIM-
BLE_MESH_GATT_PROXY is set
Default value:
• No (disabled) if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED

CONFIG_BT_NIMBLE_MESH_PROV
Enable BLE mesh provisioning
Enable mesh provisioning
Default value:
• Yes (enabled) if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_PB_ADV
Enable mesh provisioning over advertising bearer
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH > CON-
FIG_BT_NIMBLE_MESH_PROV
Enable this option to allow the device to be provisioned over the advertising bearer
Default value:
• Yes (enabled) if CONFIG_BT_NIMBLE_MESH_PROV && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_PB_GATT
Enable mesh provisioning over GATT bearer
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH > CON-
FIG_BT_NIMBLE_MESH_PROV
Enable this option to allow the device to be provisioned over the GATT bearer
Default value:
• Yes (enabled) if CONFIG_BT_NIMBLE_MESH_PROV && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_GATT_PROXY
Enable GATT Proxy functionality
This option enables support for the Mesh GATT Proxy Service, i.e. the ability to act as a proxy between
a Mesh GATT Client and a Mesh network
Default value:
• Yes (enabled) if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_RELAY
Enable mesh relay functionality
Support for acting as a Mesh Relay Node
Default value:
CONFIG_BT_NIMBLE_MESH_LOW_POWER
Enable mesh low power mode
Enable this option to be able to act as a Low Power Node
Default value:

CONFIG_BT_NIMBLE_MESH_FRIEND
Enable mesh friend functionality
Enable this option to be able to act as a Friend Node
Default value:
CONFIG_BT_NIMBLE_MESH_DEVICE_NAME
Set mesh device name
This value defines Bluetooth Mesh device/node name
Default value:
• nimble-mesh-node if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_NODE_COUNT
Set mesh node count
Defines mesh node count.
Default value:
• 1 if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_PROVISIONER
Enable BLE mesh provisioner
Enable mesh provisioner.
Default value:
• 0 if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_CRYPTO_STACK_MBEDTLS
Override TinyCrypt with mbedTLS for crypto computations
Enable this option to choose mbedTLS instead of TinyCrypt for crypto computations.
Default value:
CONFIG_BT_NIMBLE_HS_STOP_TIMEOUT_MS
BLE host stop timeout in msec
BLE Host stop procedure timeout in milliseconds.
Default value:

CONFIG_BT_NIMBLE_ENABLE_CONN_REATTEMPT
Enable connection reattempts on connection establishment error
Enable to make the NimBLE host to reattempt GAP connection on connection establishment failure.
Default value:
• No (disabled) if BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MAX_CONN_REATTEMPT
Maximum number connection reattempts
Found in: Component config > Bluetooth > NimBLE Options > CON-
FIG_BT_NIMBLE_ENABLE_CONN_REATTEMPT
Defines maximum number of connection reattempts.
Range:
• from 1 to 7 if BT_NIMBLE_ENABLED && CON-
FIG_BT_NIMBLE_ENABLE_CONN_REATTEMPT && BT_NIMBLE_ENABLED
Default value:
• 3 if BT_NIMBLE_ENABLED && CONFIG_BT_NIMBLE_ENABLE_CONN_REATTEMPT
&& BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_BLUFI_ENABLE
Enable blufi functionality
Set this option to enable blufi functionality.
Default value:
CONFIG_BT_NIMBLE_USE_ESP_TIMER
Enable Esp Timer for Nimble
Set this option to use Esp Timer which has higher priority timer instead of FreeRTOS timer
Default value:
• Yes (enabled) if BT_NIMBLE_ENABLED
CONFIG_BLE_MESH
ESP BLE Mesh Support
Found in: Component config
This option enables ESP BLE Mesh support. The specific features that are available may depend on other
features that have been enabled in the stack, such as Bluetooth Support, Bluedroid Support & GATT
support.
Contains:
• BLE Mesh and BLE coexistence support
• CONFIG_BLE_MESH_GATT_PROXY_CLIENT

• CONFIG_BLE_MESH_GATT_PROXY_SERVER
• BLE Mesh NET BUF DEBUG LOG LEVEL
• CONFIG_BLE_MESH_PROV
• CONFIG_BLE_MESH_PROXY
• BLE Mesh specific test option
• BLE Mesh STACK DEBUG LOG LEVEL
• CONFIG_BLE_MESH_NO_LOG
• CONFIG_BLE_MESH_IVU_DIVIDER
• CONFIG_BLE_MESH_FAST_PROV
• CONFIG_BLE_MESH_FREERTOS_STATIC_ALLOC
• CONFIG_BLE_MESH_CRPL
• CONFIG_BLE_MESH_RX_SDU_MAX
• CONFIG_BLE_MESH_MODEL_KEY_COUNT
• CONFIG_BLE_MESH_APP_KEY_COUNT
• CONFIG_BLE_MESH_MODEL_GROUP_COUNT
• CONFIG_BLE_MESH_LABEL_COUNT
• CONFIG_BLE_MESH_SUBNET_COUNT
• CONFIG_BLE_MESH_TX_SEG_MAX
• CONFIG_BLE_MESH_RX_SEG_MSG_COUNT
• CONFIG_BLE_MESH_TX_SEG_MSG_COUNT
• CONFIG_BLE_MESH_MEM_ALLOC_MODE
• CONFIG_BLE_MESH_MSG_CACHE_SIZE
• CONFIG_BLE_MESH_ADV_BUF_COUNT
• CONFIG_BLE_MESH_PB_GATT
• CONFIG_BLE_MESH_PB_ADV
• CONFIG_BLE_MESH_RELAY
• CONFIG_BLE_MESH_SETTINGS
• CONFIG_BLE_MESH_DEINIT
• CONFIG_BLE_MESH_USE_DUPLICATE_SCAN
• Support for BLE Mesh Client/Server models
• Support for BLE Mesh Foundation models
• CONFIG_BLE_MESH_NODE
• CONFIG_BLE_MESH_PROVISIONER
• CONFIG_BLE_MESH_FRIEND
• CONFIG_BLE_MESH_LOW_POWER
• CONFIG_BLE_MESH_HCI_5_0
• CONFIG_BLE_MESH_IV_UPDATE_TEST
• CONFIG_BLE_MESH_CLIENT_MSG_TIMEOUT
CONFIG_BLE_MESH_HCI_5_0
Support sending 20ms non-connectable adv packets
Found in: Component config > CONFIG_BLE_MESH
It is a temporary solution and needs further modifications.
Default value:
• Yes (enabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_USE_DUPLICATE_SCAN
Support Duplicate Scan in BLE Mesh
Enable this option to allow using specific duplicate scan filter in BLE Mesh, and Scan Duplicate Type
must be set by choosing the option in the Bluetooth Controller section in menuconfig, which is Scan
Duplicate By Device Address and Advertising Data .
Default value:

• Yes (enabled) if BT_BLUEDROID_ENABLED && CONFIG_BLE_MESH
CONFIG_BLE_MESH_MEM_ALLOC_MODE
Allocation strategy for BLE Mesh stack, essentially provides ability to allocate all required dynamic
allocations from,
Recommended mode here is always internal (*), since that is most preferred from security perspective.
But if application requirement does not allow sufficient free internal memory then alternate mode can
be selected.
(*) In case of ESP32-S2/ESP32-S3, hardware allows encryption of external SPIRAM contents provided
hardware flash encryption feature is enabled. In that case, using external SPIRAM allocation strategy is
also safe choice from security perspective.
Available options:
• Internal DRAM (BLE_MESH_MEM_ALLOC_MODE_INTERNAL)
• External SPIRAM (BLE_MESH_MEM_ALLOC_MODE_EXTERNAL)
• Default alloc mode (BLE_MESH_MEM_ALLOC_MODE_DEFAULT)
Enable this option to use the default memory allocation strategy when external SPIRAM is
enabled. See the SPIRAM options for more details.
• Internal IRAM (BLE_MESH_MEM_ALLOC_MODE_IRAM_8BIT)
Allows to use IRAM memory region as 8bit accessible region. Every unaligned (8bit or
16bit) access will result in an exception and incur penalty of certain clock cycles per unaligned
read/write.
CONFIG_BLE_MESH_FREERTOS_STATIC_ALLOC
Enable FreeRTOS static allocation
Enable this option to use FreeRTOS static allocation APIs for BLE Mesh, which provides the ability
to use different dynamic memory (i.e. SPIRAM or IRAM) for FreeRTOS objects. If this option is
disabled, the FreeRTOS static allocation APIs will not be used, and internal DRAM will be allocated
for FreeRTOS objects.
Default value:
• No (disabled) if (CONFIG_ESP32_SPIRAM_SUPPORT || CON-
FIG_ESP32_IRAM_AS_8BIT_ACCESSIBLE_MEMORY) && CONFIG_BLE_MESH
CONFIG_BLE_MESH_FREERTOS_STATIC_ALLOC_MODE
Memory allocation for FreeRTOS objects
Found in: Component config > CONFIG_BLE_MESH > CON-
FIG_BLE_MESH_FREERTOS_STATIC_ALLOC
Choose the memory to be used for FreeRTOS objects.
Available options:
• External SPIRAM (BLE_MESH_FREERTOS_STATIC_ALLOC_EXTERNAL)
If enabled, BLE Mesh allocates dynamic memory from external SPIRAM for FreeRTOS
objects, i.e. mutex, queue, and task stack. External SPIRAM can only be used for task stack

when SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY is enabled. See the SPIRAM

options for more details.
• Internal IRAM (BLE_MESH_FREERTOS_STATIC_ALLOC_IRAM_8BIT)
If enabled, BLE Mesh allocates dynamic memory from internal IRAM for FreeRTOS objects,
i.e. mutex, queue. Note: IRAM region cannot be used as task stack.
CONFIG_BLE_MESH_DEINIT
Support de-initialize BLE Mesh stack
If enabled, users can use the function esp_ble_mesh_deinit() to de-initialize the whole BLE Mesh stack.
Default value:
BLE Mesh and BLE coexistence support Contains:

• CONFIG_BLE_MESH_SUPPORT_BLE_SCAN
• CONFIG_BLE_MESH_SUPPORT_BLE_ADV
CONFIG_BLE_MESH_SUPPORT_BLE_ADV
Support sending normal BLE advertising packets
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh and BLE coexistence support
When selected, users can send normal BLE advertising packets with specific API.
Default value:
• No (disabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_BLE_ADV_BUF_COUNT
Number of advertising buffers for BLE advertising packets
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh and BLE coexistence support > CON-
FIG_BLE_MESH_SUPPORT_BLE_ADV
Number of advertising buffers for BLE packets available.
Range:
• from 1 to 255 if CONFIG_BLE_MESH_SUPPORT_BLE_ADV && CONFIG_BLE_MESH
Default value:
• 3 if CONFIG_BLE_MESH_SUPPORT_BLE_ADV && CONFIG_BLE_MESH
CONFIG_BLE_MESH_SUPPORT_BLE_SCAN
Support scanning normal BLE advertising packets
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh and BLE coexistence support
When selected, users can register a callback and receive normal BLE advertising packets in the appli-
cation layer.
Default value:

CONFIG_BLE_MESH_FAST_PROV
Enable BLE Mesh Fast Provisioning
Enable this option to allow BLE Mesh fast provisioning solution to be used. When there are multiple
unprovisioned devices around, fast provisioning can greatly reduce the time consumption of the whole
provisioning process. When this option is enabled, and after an unprovisioned device is provisioned into
a node successfully, it can be changed to a temporary Provisioner.
Default value:
CONFIG_BLE_MESH_NODE
Support for BLE Mesh Node
Enable the device to be provisioned into a node. This option should be enabled when an unprovisioned
device is going to be provisioned into a node and communicate with other nodes in the BLE Mesh
network.
CONFIG_BLE_MESH_PROVISIONER
Support for BLE Mesh Provisioner
Enable the device to be a Provisioner. The option should be enabled when a device is going to act as a
Provisioner and provision unprovisioned devices into the BLE Mesh network.
CONFIG_BLE_MESH_WAIT_FOR_PROV_MAX_DEV_NUM
Maximum number of unprovisioned devices that can be added to device queue
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_PROVISIONER
This option specifies how many unprovisioned devices can be added to device queue for provisioning.
Users can use this option to define the size of the queue in the bottom layer which is used to store
unprovisioned device information (e.g. Device UUID, address).
Range:
• from 1 to 100 if CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH
Default value:
• 10 if CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_MAX_PROV_NODES
Maximum number of devices that can be provisioned by Provisioner
This option specifies how many devices can be provisioned by a Provisioner. This value indicates the
maximum number of unprovisioned devices which can be provisioned by a Provisioner. For instance,
if the value is 6, it means the Provisioner can provision up to 6 unprovisioned devices. Theoretically a
Provisioner without the limitation of its memory can provision up to 32766 unprovisioned devices, here
we limit the maximum number to 100 just to limit the memory used by a Provisioner. The bigger the
value is, the more memory it will cost by a Provisioner to store the information of nodes.
Range:
Default value:

CONFIG_BLE_MESH_PBA_SAME_TIME
Maximum number of PB-ADV running at the same time by Provisioner
This option specifies how many devices can be provisioned at the same time using PB-ADV. For exam-
ples, if the value is 2, it means a Provisioner can provision two unprovisioned devices with PB-ADV at
the same time.
Range:
• from 1 to 10 if CONFIG_BLE_MESH_PB_ADV && CONFIG_BLE_MESH_PROVISIONER
&& CONFIG_BLE_MESH
Default value:
• 2 if CONFIG_BLE_MESH_PB_ADV && CONFIG_BLE_MESH_PROVISIONER && CON-
FIG_BLE_MESH
CONFIG_BLE_MESH_PBG_SAME_TIME
Maximum number of PB-GATT running at the same time by Provisioner
This option specifies how many devices can be provisioned at the same time using PB-GATT. For ex-
ample, if the value is 2, it means a Provisioner can provision two unprovisioned devices with PB-GATT
at the same time.
Range:
• from 1 to 5 if CONFIG_BLE_MESH_PB_GATT && CONFIG_BLE_MESH_PROVISIONER
&& CONFIG_BLE_MESH
Default value:
• 1 if CONFIG_BLE_MESH_PB_GATT && CONFIG_BLE_MESH_PROVISIONER && CON-
FIG_BLE_MESH
CONFIG_BLE_MESH_PROVISIONER_SUBNET_COUNT
Maximum number of mesh subnets that can be created by Provisioner
This option specifies how many subnets per network a Provisioner can create. Indeed, this value decides
the number of network keys which can be added by a Provisioner.
Range:
Default value:
CONFIG_BLE_MESH_PROVISIONER_APP_KEY_COUNT
Maximum number of application keys that can be owned by Provisioner
This option specifies how many application keys the Provisioner can have. Indeed, this value decides the
number of the application keys which can be added by a Provisioner.
Range:
Default value:

CONFIG_BLE_MESH_PROVISIONER_RECV_HB
Support receiving Heartbeat messages
When this option is enabled, Provisioner can call specific functions to enable or disable receiving Heart-
beat messages and notify them to the application layer.
Default value:
• No (disabled) if CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_PROVISIONER_RECV_HB_FILTER_SIZE
Maximum number of filter entries for receiving Heartbeat messages
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_PROVISIONER > CON-
FIG_BLE_MESH_PROVISIONER_RECV_HB
This option specifies how many heartbeat filter entries Provisioner supports. The heartbeat filter (ac-
ceptlist or rejectlist) entries are used to store a list of SRC and DST which can be used to decide if a
heartbeat message will be processed and notified to the application layer by Provisioner. Note: The filter
is an empty rejectlist by default.
Range:
• from 1 to 1000 if CONFIG_BLE_MESH_PROVISIONER_RECV_HB && CON-
FIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH
Default value:
• 3 if CONFIG_BLE_MESH_PROVISIONER_RECV_HB && CON-
FIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_PROV
BLE Mesh Provisioning support
Enable this option to support BLE Mesh Provisioning functionality. For BLE Mesh, this option should
be always enabled.
Default value:
CONFIG_BLE_MESH_PB_ADV
Provisioning support using the advertising bearer (PB-ADV)
Enable this option to allow the device to be provisioned over the advertising bearer. This option should
be enabled if PB-ADV is going to be used during provisioning procedure.
Default value:
CONFIG_BLE_MESH_UNPROVISIONED_BEACON_INTERVAL
Interval between two consecutive Unprovisioned Device Beacon
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_PB_ADV
This option specifies the interval of sending two consecutive unprovisioned device beacon, users can
use this option to change the frequency of sending unprovisioned device beacon. For example, if the
value is 5, it means the unprovisioned device beacon will send every 5 seconds. When the option of
BLE_MESH_FAST_PROV is selected, the value is better to be 3 seconds, or less.

Range:
• from 1 to 100 if CONFIG_BLE_MESH_NODE && CONFIG_BLE_MESH_PB_ADV &&
CONFIG_BLE_MESH
Default value:
• 5 if CONFIG_BLE_MESH_NODE && CONFIG_BLE_MESH_PB_ADV && CON-
FIG_BLE_MESH
• 3 if CONFIG_BLE_MESH_FAST_PROV && CONFIG_BLE_MESH_NODE && CON-
FIG_BLE_MESH_PB_ADV && CONFIG_BLE_MESH
CONFIG_BLE_MESH_PB_GATT
Provisioning support using GATT (PB-GATT)
Enable this option to allow the device to be provisioned over GATT. This option should be enabled if
PB-GATT is going to be used during provisioning procedure.
# Virtual option enabled whenever any Proxy protocol is needed
CONFIG_BLE_MESH_PROXY
BLE Mesh Proxy protocol support
Enable this option to support BLE Mesh Proxy protocol used by PB-GATT and other proxy pdu trans-
mission.
Default value:
CONFIG_BLE_MESH_GATT_PROXY_SERVER
BLE Mesh GATT Proxy Server
This option enables support for Mesh GATT Proxy Service, i.e. the ability to act as a proxy between a
Mesh GATT Client and a Mesh network. This option should be enabled if a node is going to be a Proxy
Server.
Default value:
• Yes (enabled) if CONFIG_BLE_MESH_NODE && CONFIG_BLE_MESH
CONFIG_BLE_MESH_NODE_ID_TIMEOUT
Node Identity advertising timeout
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_GATT_PROXY_SERVER
This option determines for how long the local node advertises using Node Identity. The given value is
in seconds. The specification limits this to 60 seconds and lists it as the recommended value as well. So
leaving the default value is the safest option. When an unprovisioned device is provisioned successfully
and becomes a node, it will start to advertise using Node Identity during the time set by this option. And
after that, Network ID will be advertised.
Range:
• from 1 to 60 if CONFIG_BLE_MESH_GATT_PROXY_SERVER && CONFIG_BLE_MESH
Default value:
• 60 if CONFIG_BLE_MESH_GATT_PROXY_SERVER && CONFIG_BLE_MESH

CONFIG_BLE_MESH_PROXY_FILTER_SIZE
Maximum number of filter entries per Proxy Client
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_GATT_PROXY_SERVER
This option specifies how many Proxy Filter entries the local node supports. The entries of Proxy filter
(whitelist or blacklist) are used to store a list of addresses which can be used to decide which messages
will be forwarded to the Proxy Client by the Proxy Server.
Range:
• from 1 to 32767 if CONFIG_BLE_MESH_GATT_PROXY_SERVER && CON-
FIG_BLE_MESH
Default value:
• 4 if CONFIG_BLE_MESH_GATT_PROXY_SERVER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_GATT_PROXY_CLIENT
BLE Mesh GATT Proxy Client
This option enables support for Mesh GATT Proxy Client. The Proxy Client can use the GATT bearer
to send mesh messages to a node that supports the advertising bearer.
Default value:
CONFIG_BLE_MESH_SETTINGS
Store BLE Mesh configuration persistently
When selected, the BLE Mesh stack will take care of storing/restoring the BLE Mesh configuration
persistently in flash. If the device is a BLE Mesh node, when this option is enabled, the configuration
of the device will be stored persistently, including unicast address, NetKey, AppKey, etc. And if the
device is a BLE Mesh Provisioner, the information of the device will be stored persistently, including
the information of provisioned nodes, NetKey, AppKey, etc.
Default value:
CONFIG_BLE_MESH_STORE_TIMEOUT
Delay (in seconds) before storing anything persistently
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_SETTINGS
This value defines in seconds how soon any pending changes are actually written into persistent storage
(flash) after a change occurs. The option allows nodes to delay a certain period of time to save proper
information to flash. The default value is 0, which means information will be stored immediately once
there are updates.
Range:
• from 0 to 1000000 if CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH
Default value:
• 0 if CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH
CONFIG_BLE_MESH_SEQ_STORE_RATE

How often the sequence number gets updated in storage

This value defines how often the local sequence number gets updated in persistent storage (i.e. flash).
e.g. a value of 100 means that the sequence number will be stored to flash on every 100th increment.
If the node sends messages very frequently a higher value makes more sense, whereas if the node sends
infrequently a value as low as 0 (update storage for every increment) can make sense. When the stack
gets initialized it will add sequence number to the last stored one, so that it starts off with a value that
s guaranteed to be larger than the last one used before power off.
Range:
Default value:
CONFIG_BLE_MESH_RPL_STORE_TIMEOUT
Minimum frequency that the RPL gets updated in storage
This value defines in seconds how soon the RPL (Replay Protection List) gets written to persistent storage
after a change occurs. If the node receives messages frequently, then a large value is recommended. If
the node receives messages rarely, then the value can be as low as 0 (which means the RPL is written
into the storage immediately). Note that if the node operates in a security-sensitive case, and there is a
risk of sudden power-off, then a value of 0 is strongly recommended. Otherwise, a power loss before
RPL being written into the storage may introduce message replay attacks and system security will be in
a vulnerable state.
Range:
Default value:
CONFIG_BLE_MESH_SETTINGS_BACKWARD_COMPATIBILITY
A specific option for settings backward compatibility
This option is created to solve the issue of failure in recovering node information after mesh stack up-
dates. In the old version mesh stack, there is no key of mesh/role in nvs. In the new version mesh
stack, key of mesh/role is added in nvs, recovering node information needs to check mesh/role
key in nvs and implements selective recovery of mesh node information. Therefore, there may be failure
in recovering node information during node restarting after OTA.
The new version mesh stack adds the option of mesh/role because we have added the support of
storing Provisioner information, while the old version only supports storing node information.
If users are updating their nodes from old version to new version, we recommend enabling this option,
so that system could set the flag in advance before recovering node information and make sure the node
information recovering could work as expected.
Default value:
• No (disabled) if CONFIG_BLE_MESH_NODE && CONFIG_BLE_MESH_SETTINGS &&
CONFIG_BLE_MESH
CONFIG_BLE_MESH_SPECIFIC_PARTITION
Use a specific NVS partition for BLE Mesh

When selected, the mesh stack will use a specified NVS partition instead of default NVS partition. Note
that the specified partition must be registered with NVS using nvs_flash_init_partition() API, and the
partition must exists in the csv file. When Provisioner needs to store a large amount of nodes information
in the flash (e.g. more than 20), this option is recommended to be enabled.
Default value:
• No (disabled) if CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH
CONFIG_BLE_MESH_PARTITION_NAME
Name of the NVS partition for BLE Mesh
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_SETTINGS > CON-
FIG_BLE_MESH_SPECIFIC_PARTITION
This value defines the name of the specified NVS partition used by the mesh stack.
Default value:
• ble_mesh if CONFIG_BLE_MESH_SPECIFIC_PARTITION && CON-
FIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH
CONFIG_BLE_MESH_USE_MULTIPLE_NAMESPACE
Support using multiple NVS namespaces by Provisioner
When selected, Provisioner can use different NVS namespaces to store different instances of mesh in-
formation. For example, if in the first room, Provisioner uses NetKey A, AppKey A and provisions
three devices, these information will be treated as mesh information instance A. When the Provisioner
moves to the second room, it uses NetKey B, AppKey B and provisions two devices, then the informa-
tion will be treated as mesh information instance B. Here instance A and instance B will be stored in
different namespaces. With this option enabled, Provisioner needs to use specific functions to open the
corresponding NVS namespace, restore the mesh information, release the mesh information or erase the
mesh information.
Default value:
• No (disabled) if CONFIG_BLE_MESH_PROVISIONER && CON-
CONFIG_BLE_MESH_MAX_NVS_NAMESPACE
Maximum number of NVS namespaces
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_SETTINGS > CON-
FIG_BLE_MESH_USE_MULTIPLE_NAMESPACE
This option specifies the maximum NVS namespaces supported by Provisioner.
Range:
• from 1 to 255 if CONFIG_BLE_MESH_USE_MULTIPLE_NAMESPACE && CON-
Default value:
• 2 if CONFIG_BLE_MESH_USE_MULTIPLE_NAMESPACE && CON-
CONFIG_BLE_MESH_SUBNET_COUNT
Maximum number of mesh subnets per network

This option specifies how many subnets a Mesh network can have at the same time. Indeed, this value
decides the number of the network keys which can be owned by a node.
Range:
• from 1 to 4096 if CONFIG_BLE_MESH
Default value:
• 3 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_APP_KEY_COUNT
Maximum number of application keys per network
This option specifies how many application keys the device can store per network. Indeed, this value
decides the number of the application keys which can be owned by a node.
Range:
Default value:
CONFIG_BLE_MESH_MODEL_KEY_COUNT
Maximum number of application keys per model
This option specifies the maximum number of application keys to which each model can be bound.
Range:
Default value:
CONFIG_BLE_MESH_MODEL_GROUP_COUNT
Maximum number of group address subscriptions per model
This option specifies the maximum number of addresses to which each model can be subscribed.
Range:
Default value:
CONFIG_BLE_MESH_LABEL_COUNT
Maximum number of Label UUIDs used for Virtual Addresses
This option specifies how many Label UUIDs can be stored. Indeed, this value decides the number of
the Virtual Addresses can be supported by a node.
Range:
Default value:

CONFIG_BLE_MESH_CRPL
Maximum capacity of the replay protection list
This option specifies the maximum capacity of the replay protection list. It is similar to Network message
cache size, but has a different purpose. The replay protection list is used to prevent a node from replay
attack, which will store the source address and sequence number of the received mesh messages. For
Provisioner, the replay protection list size should not be smaller than the maximum number of nodes
whose information can be stored. And the element number of each node should also be taken into
consideration. For example, if Provisioner can provision up to 20 nodes and each node contains two
elements, then the replay protection list size of Provisioner should be at least 40.
Range:
Default value:
CONFIG_BLE_MESH_MSG_CACHE_SIZE
Network message cache size
Number of messages that are cached for the network. This helps prevent unnecessary decryption opera-
tions and unnecessary relays. This option is similar to Replay protection list, but has a different purpose.
A node is not required to cache the entire Network PDU and may cache only part of it for tracking, such
as values for SRC/SEQ or others.
Range:
Default value:
CONFIG_BLE_MESH_ADV_BUF_COUNT
Number of advertising buffers
Number of advertising buffers available. The transport layer reserves ADV_BUF_COUNT - 3 buffers
for outgoing segments. The maximum outgoing SDU size is 12 times this value (out of which 4 or 8
bytes are used for the Transport Layer MIC). For example, 5 segments means the maximum SDU size
is 60 bytes, which leaves 56 bytes for application layer data using a 4-byte MIC, or 52 bytes using an
8-byte MIC.
Range:
Default value:
CONFIG_BLE_MESH_IVU_DIVIDER
Divider for IV Update state refresh timer
When the IV Update state enters Normal operation or IV Update in Progress, we need to keep track of
how many hours has passed in the state, since the specification requires us to remain in the state at least
for 96 hours (Update in Progress has an additional upper limit of 144 hours).
In order to fulfill the above requirement, even if the node might be powered off once in a while, we need
to store persistently how many hours the node has been in the state. This doesn t necessarily need to

happen every hour (thanks to the flexible duration range). The exact cadence will depend a lot on the
ways that the node will be used and what kind of power source it has.
Since there is no single optimal answer, this configuration option allows specifying a divider, i.e. how
many intervals the 96 hour minimum gets split into. After each interval the duration that the node has
been in the current state gets stored to flash. E.g. the default value of 4 means that the state is saved
every 24 hours (96 / 4).
Range:
Default value:
CONFIG_BLE_MESH_TX_SEG_MSG_COUNT
Maximum number of simultaneous outgoing segmented messages
Maximum number of simultaneous outgoing multi-segment and/or reliable messages. The default value
is 1, which means the device can only send one segmented message at a time. And if another segmented
message is going to be sent, it should wait for the completion of the previous one. If users are going to
send multiple segmented messages at the same time, this value should be configured properly.
Range:
• from 1 to if CONFIG_BLE_MESH
Default value:
CONFIG_BLE_MESH_RX_SEG_MSG_COUNT
Maximum number of simultaneous incoming segmented messages
Maximum number of simultaneous incoming multi-segment and/or reliable messages. The default value
is 1, which means the device can only receive one segmented message at a time. And if another seg-
mented message is going to be received, it should wait for the completion of the previous one. If users
are going to receive multiple segmented messages at the same time, this value should be configured
properly.
Range:
Default value:
CONFIG_BLE_MESH_RX_SDU_MAX
Maximum incoming Upper Transport Access PDU length
Maximum incoming Upper Transport Access PDU length. Leave this to the default value, unless you
really need to optimize memory usage.
Range:
Default value:

CONFIG_BLE_MESH_TX_SEG_MAX
Maximum number of segments in outgoing messages
Maximum number of segments supported for outgoing messages. This value should typically be fine-
tuned based on what models the local node supports, i.e. what s the largest message payload that the
node needs to be able to send. This value affects memory and call stack consumption, which is why the
default is lower than the maximum that the specification would allow (32 segments).
The maximum outgoing SDU size is 12 times this number (out of which 4 or 8 bytes is used for the
Transport Layer MIC). For example, 5 segments means the maximum SDU size is 60 bytes, which
leaves 56 bytes for application layer data using a 4-byte MIC and 52 bytes using an 8-byte MIC.
Be sure to specify a sufficient number of advertising buffers when setting this option to a higher value.
There must be at least three more advertising buffers (BLE_MESH_ADV_BUF_COUNT) as there are
outgoing segments.
Range:
Default value:
CONFIG_BLE_MESH_RELAY
Relay support
Support for acting as a Mesh Relay Node. Enabling this option will allow a node to support the Relay fea-
ture, and the Relay feature can still be enabled or disabled by proper configuration messages. Disabling
this option will let a node not support the Relay feature.
Default value:
• Yes (enabled) if CONFIG_BLE_MESH_NODE && CONFIG_BLE_MESH
CONFIG_BLE_MESH_RELAY_ADV_BUF
Use separate advertising buffers for relay packets
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_RELAY
When selected, self-send packets will be put in a high-priority queue and relay packets will be put in a
low-priority queue.
Default value:
• No (disabled) if CONFIG_BLE_MESH_RELAY && CONFIG_BLE_MESH
CONFIG_BLE_MESH_RELAY_ADV_BUF_COUNT
Number of advertising buffers for relay packets
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_RELAY > CON-
FIG_BLE_MESH_RELAY_ADV_BUF
Number of advertising buffers for relay packets available.
Range:
• from 6 to 256 if CONFIG_BLE_MESH_RELAY_ADV_BUF && CON-
FIG_BLE_MESH_RELAY && CONFIG_BLE_MESH
Default value:
• 60 if CONFIG_BLE_MESH_RELAY_ADV_BUF && CONFIG_BLE_MESH_RELAY &&
CONFIG_BLE_MESH

CONFIG_BLE_MESH_LOW_POWER
Support for Low Power features
Enable this option to operate as a Low Power Node. If low power consumption is required by a node,
this option should be enabled. And once the node enters the mesh network, it will try to find a Friend
node and establish a friendship.
CONFIG_BLE_MESH_LPN_ESTABLISHMENT
Perform Friendship establishment using low power
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER
Perform the Friendship establishment using low power with the help of a reduced scan duty cycle. The
downside of this is that the node may miss out on messages intended for it until it has successfully set up
Friendship with a Friend node. When this option is enabled, the node will stop scanning for a period of
time after a Friend Request or Friend Poll is sent, so as to reduce more power consumption.
Default value:
• No (disabled) if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_LPN_AUTO
Automatically start looking for Friend nodes once provisioned
Once provisioned, automatically enable LPN functionality and start looking for Friend nodes. If this
option is disabled LPN mode needs to be manually enabled by calling bt_mesh_lpn_set(true). When an
unprovisioned device is provisioned successfully and becomes a node, enabling this option will trigger
the node starts to send Friend Request at a certain period until it finds a proper Friend node.
Default value:
• No (disabled) if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_LPN_AUTO_TIMEOUT
Time from last received message before going to LPN mode
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER > CON-
FIG_BLE_MESH_LPN_AUTO
Time in seconds from the last received message, that the node waits out before starting to look for Friend
nodes.
Range:
• from 0 to 3600 if CONFIG_BLE_MESH_LPN_AUTO && CON-
FIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
Default value:
• 15 if CONFIG_BLE_MESH_LPN_AUTO && CONFIG_BLE_MESH_LOW_POWER &&
CONFIG_BLE_MESH
CONFIG_BLE_MESH_LPN_RETRY_TIMEOUT
Retry timeout for Friend requests
Time in seconds between Friend Requests, if a previous Friend Request did not yield any acceptable
Friend Offers.
Range:

• from 1 to 3600 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH

Default value:
• 6 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_LPN_RSSI_FACTOR
RSSIFactor, used in Friend Offer Delay calculation
The contribution of the RSSI, measured by the Friend node, used in Friend Offer Delay calculations. 0
= 1, 1 = 1.5, 2 = 2, 3 = 2.5. RSSIFactor, one of the parameters carried by Friend Request sent by Low
Power node, which is used to calculate the Friend Offer Delay.
Range:
Default value:
CONFIG_BLE_MESH_LPN_RECV_WIN_FACTOR
ReceiveWindowFactor, used in Friend Offer Delay calculation
The contribution of the supported Receive Window used in Friend Offer Delay calculations. 0 = 1, 1
= 1.5, 2 = 2, 3 = 2.5. ReceiveWindowFactor, one of the parameters carried by Friend Request sent by
Low Power node, which is used to calculate the Friend Offer Delay.
Range:
Default value:
CONFIG_BLE_MESH_LPN_MIN_QUEUE_SIZE
Minimum size of the acceptable friend queue (MinQueueSizeLog)
The MinQueueSizeLog field is defined as log_2(N), where N is the minimum number of maximum size
Lower Transport PDUs that the Friend node can store in its Friend Queue. As an example, MinQueue-
SizeLog value 1 gives N = 2, and value 7 gives N = 128.
Range:
Default value:
CONFIG_BLE_MESH_LPN_RECV_DELAY
Receive delay requested by the local node
The ReceiveDelay is the time between the Low Power node sending a request and listening for a response.
This delay allows the Friend node time to prepare the response. The value is in units of milliseconds.
Range:
Default value:

CONFIG_BLE_MESH_LPN_POLL_TIMEOUT
The value of the PollTimeout timer
PollTimeout timer is used to measure time between two consecutive requests sent by a Low Power node.
If no requests are received the Friend node before the PollTimeout timer expires, then the friendship
is considered terminated. The value is in units of 100 milliseconds, so e.g. a value of 300 means 30
seconds. The smaller the value, the faster the Low Power node tries to get messages from corresponding
Friend node and vice versa.
Range:
Default value:
CONFIG_BLE_MESH_LPN_INIT_POLL_TIMEOUT
The starting value of the PollTimeout timer
The initial value of the PollTimeout timer when Friendship is to be established for the first time. After
this, the timeout gradually grows toward the actual PollTimeout, doubling in value for each iteration.
The value is in units of 100 milliseconds, so e.g. a value of 300 means 30 seconds.
Range:
• from 10 to if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
Default value:
• if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_LPN_SCAN_LATENCY
Latency for enabling scanning
Latency (in milliseconds) is the time it takes to enable scanning. In practice, it means how much time in
advance of the Receive Window, the request to enable scanning is made.
Range:
Default value:
CONFIG_BLE_MESH_LPN_GROUPS
Number of groups the LPN can subscribe to
Maximum number of groups to which the LPN can subscribe.
Range:
Default value:
CONFIG_BLE_MESH_FRIEND

Support for Friend feature

Enable this option to be able to act as a Friend Node.
CONFIG_BLE_MESH_FRIEND_RECV_WIN
Friend Receive Window
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_FRIEND
Receive Window in milliseconds supported by the Friend node.
Range:
• from 1 to 255 if CONFIG_BLE_MESH_FRIEND && CONFIG_BLE_MESH
Default value:
• 255 if CONFIG_BLE_MESH_FRIEND && CONFIG_BLE_MESH
CONFIG_BLE_MESH_FRIEND_QUEUE_SIZE
Minimum number of buffers supported per Friend Queue
Minimum number of buffers available to be stored for each local Friend Queue. This option decides the
size of each buffer which can be used by a Friend node to store messages for each Low Power node.
Range:
Default value:
CONFIG_BLE_MESH_FRIEND_SUB_LIST_SIZE
Friend Subscription List Size
Size of the Subscription List that can be supported by a Friend node for a Low Power node. And Low
Power node can send Friend Subscription List Add or Friend Subscription List Remove messages to the
Friend node to add or remove subscription addresses.
Range:
Default value:
CONFIG_BLE_MESH_FRIEND_LPN_COUNT
Number of supported LPN nodes
Number of Low Power Nodes with which a Friend can have Friendship simultaneously. A Friend node
can have friendship with multiple Low Power nodes at the same time, while a Low Power node can only
establish friendship with only one Friend node at the same time.
Range:
Default value:

CONFIG_BLE_MESH_FRIEND_SEG_RX
Number of incomplete segment lists per LPN
Number of incomplete segment lists tracked for each Friends LPN. In other words, this determines from
how many elements can segmented messages destined for the Friend queue be received simultaneously.
Range:
Default value:
CONFIG_BLE_MESH_NO_LOG
Disable BLE Mesh debug logs (minimize bin size)
Select this to save the BLE Mesh related rodata code size. Enabling this option will disable the output
of BLE Mesh debug log.
Default value:
• No (disabled) if CONFIG_BLE_MESH && CONFIG_BLE_MESH
BLE Mesh STACK DEBUG LOG LEVEL Contains:

• CONFIG_BLE_MESH_STACK_TRACE_LEVEL
CONFIG_BLE_MESH_STACK_TRACE_LEVEL
BLE_MESH_STACK
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh STACK DEBUG LOG LEVEL
Define BLE Mesh trace level for BLE Mesh stack.
Available options:
• NONE (BLE_MESH_TRACE_LEVEL_NONE)
• ERROR (BLE_MESH_TRACE_LEVEL_ERROR)
• WARNING (BLE_MESH_TRACE_LEVEL_WARNING)
• INFO (BLE_MESH_TRACE_LEVEL_INFO)
• DEBUG (BLE_MESH_TRACE_LEVEL_DEBUG)
• VERBOSE (BLE_MESH_TRACE_LEVEL_VERBOSE)
BLE Mesh NET BUF DEBUG LOG LEVEL Contains:

• CONFIG_BLE_MESH_NET_BUF_TRACE_LEVEL
CONFIG_BLE_MESH_NET_BUF_TRACE_LEVEL
BLE_MESH_NET_BUF
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh NET BUF DEBUG LOG LEVEL
Define BLE Mesh trace level for BLE Mesh net buffer.
Available options:
• NONE (BLE_MESH_NET_BUF_TRACE_LEVEL_NONE)
• ERROR (BLE_MESH_NET_BUF_TRACE_LEVEL_ERROR)
• WARNING (BLE_MESH_NET_BUF_TRACE_LEVEL_WARNING)
• INFO (BLE_MESH_NET_BUF_TRACE_LEVEL_INFO)
• DEBUG (BLE_MESH_NET_BUF_TRACE_LEVEL_DEBUG)

• VERBOSE (BLE_MESH_NET_BUF_TRACE_LEVEL_VERBOSE)
CONFIG_BLE_MESH_CLIENT_MSG_TIMEOUT
Timeout(ms) for client message response
Timeout value used by the node to get response of the acknowledged message which is sent by the client
model. This value indicates the maximum time that a client model waits for the response of the sent
acknowledged messages. If a client model uses 0 as the timeout value when sending acknowledged
messages, then the default value will be used which is four seconds.
Range:
Default value:
Support for BLE Mesh Foundation models Contains:

• CONFIG_BLE_MESH_CFG_CLI
• CONFIG_BLE_MESH_HEALTH_CLI
• CONFIG_BLE_MESH_HEALTH_SRV
CONFIG_BLE_MESH_CFG_CLI
Configuration Client model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Foundation models
Enable support for Configuration Client model.
CONFIG_BLE_MESH_HEALTH_CLI
Health Client model
Enable support for Health Client model.
CONFIG_BLE_MESH_HEALTH_SRV
Health Server model
Enable support for Health Server model.
Default value:
Support for BLE Mesh Client/Server models Contains:

• CONFIG_BLE_MESH_GENERIC_BATTERY_CLI
• CONFIG_BLE_MESH_GENERIC_DEF_TRANS_TIME_CLI
• CONFIG_BLE_MESH_GENERIC_LEVEL_CLI
• CONFIG_BLE_MESH_GENERIC_LOCATION_CLI
• CONFIG_BLE_MESH_GENERIC_ONOFF_CLI
• CONFIG_BLE_MESH_GENERIC_POWER_LEVEL_CLI
• CONFIG_BLE_MESH_GENERIC_POWER_ONOFF_CLI
• CONFIG_BLE_MESH_GENERIC_PROPERTY_CLI
• CONFIG_BLE_MESH_GENERIC_SERVER

• CONFIG_BLE_MESH_LIGHT_CTL_CLI
• CONFIG_BLE_MESH_LIGHT_HSL_CLI
• CONFIG_BLE_MESH_LIGHT_LC_CLI
• CONFIG_BLE_MESH_LIGHT_LIGHTNESS_CLI
• CONFIG_BLE_MESH_LIGHT_XYL_CLI
• CONFIG_BLE_MESH_LIGHTING_SERVER
• CONFIG_BLE_MESH_SCENE_CLI
• CONFIG_BLE_MESH_SCHEDULER_CLI
• CONFIG_BLE_MESH_SENSOR_CLI
• CONFIG_BLE_MESH_SENSOR_SERVER
• CONFIG_BLE_MESH_TIME_SCENE_SERVER
• CONFIG_BLE_MESH_TIME_CLI
CONFIG_BLE_MESH_GENERIC_ONOFF_CLI
Generic OnOff Client model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Generic OnOff Client model.
CONFIG_BLE_MESH_GENERIC_LEVEL_CLI
Generic Level Client model
Enable support for Generic Level Client model.
CONFIG_BLE_MESH_GENERIC_DEF_TRANS_TIME_CLI
Generic Default Transition Time Client model
Enable support for Generic Default Transition Time Client model.
CONFIG_BLE_MESH_GENERIC_POWER_ONOFF_CLI
Generic Power OnOff Client model
Enable support for Generic Power OnOff Client model.
CONFIG_BLE_MESH_GENERIC_POWER_LEVEL_CLI
Generic Power Level Client model
Enable support for Generic Power Level Client model.
CONFIG_BLE_MESH_GENERIC_BATTERY_CLI
Generic Battery Client model
Enable support for Generic Battery Client model.

CONFIG_BLE_MESH_GENERIC_LOCATION_CLI
Generic Location Client model
Enable support for Generic Location Client model.
CONFIG_BLE_MESH_GENERIC_PROPERTY_CLI
Generic Property Client model
Enable support for Generic Property Client model.
CONFIG_BLE_MESH_SENSOR_CLI
Sensor Client model
Enable support for Sensor Client model.
CONFIG_BLE_MESH_TIME_CLI
Time Client model
Enable support for Time Client model.
CONFIG_BLE_MESH_SCENE_CLI
Scene Client model
Enable support for Scene Client model.
CONFIG_BLE_MESH_SCHEDULER_CLI
Scheduler Client model
Enable support for Scheduler Client model.
CONFIG_BLE_MESH_LIGHT_LIGHTNESS_CLI
Light Lightness Client model
Enable support for Light Lightness Client model.
CONFIG_BLE_MESH_LIGHT_CTL_CLI
Light CTL Client model
Enable support for Light CTL Client model.

CONFIG_BLE_MESH_LIGHT_HSL_CLI
Light HSL Client model
Enable support for Light HSL Client model.
CONFIG_BLE_MESH_LIGHT_XYL_CLI
Light XYL Client model
Enable support for Light XYL Client model.
CONFIG_BLE_MESH_LIGHT_LC_CLI
Light LC Client model
Enable support for Light LC Client model.
CONFIG_BLE_MESH_GENERIC_SERVER
Generic server models
Enable support for Generic server models.
Default value:
CONFIG_BLE_MESH_SENSOR_SERVER
Sensor server models
Enable support for Sensor server models.
Default value:
CONFIG_BLE_MESH_TIME_SCENE_SERVER
Time and Scenes server models
Enable support for Time and Scenes server models.
Default value:
CONFIG_BLE_MESH_LIGHTING_SERVER
Lighting server models
Enable support for Lighting server models.
Default value:

CONFIG_BLE_MESH_IV_UPDATE_TEST
Test the IV Update Procedure
This option removes the 96 hour limit of the IV Update Procedure and lets the state to be changed at
any time. If IV Update test mode is going to be used, this option should be enabled.
Default value:
BLE Mesh specific test option Contains:

• CONFIG_BLE_MESH_DEBUG
• CONFIG_BLE_MESH_SHELL
• CONFIG_BLE_MESH_SELF_TEST
CONFIG_BLE_MESH_SELF_TEST
Perform BLE Mesh self-tests
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option
This option adds extra self-tests which are run every time BLE Mesh networking is initialized.
Default value:
CONFIG_BLE_MESH_TEST_AUTO_ENTER_NETWORK
Unprovisioned device enters mesh network automatically
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CON-
FIG_BLE_MESH_SELF_TEST
With this option enabled, an unprovisioned device can automatically enters mesh network using a specific
test function without the provisioning procedure. And on the Provisioner side, a test function needs to
be invoked to add the node information into the mesh stack.
Default value:
• Yes (enabled) if CONFIG_BLE_MESH_SELF_TEST && CONFIG_BLE_MESH
CONFIG_BLE_MESH_TEST_USE_WHITE_LIST
Use white list to filter mesh advertising packets
FIG_BLE_MESH_SELF_TEST
With this option enabled, users can use white list to filter mesh advertising packets while scanning.
Default value:
• No (disabled) if CONFIG_BLE_MESH_SELF_TEST && CONFIG_BLE_MESH
CONFIG_BLE_MESH_SHELL
Enable BLE Mesh shell
Activate shell module that provides BLE Mesh commands to the console.
Default value:

CONFIG_BLE_MESH_DEBUG
Enable BLE Mesh debug logs
Enable debug logs for the BLE Mesh functionality.
Default value:
CONFIG_BLE_MESH_DEBUG_NET
Network layer debug
FIG_BLE_MESH_DEBUG
Enable Network layer debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_TRANS
Transport layer debug
FIG_BLE_MESH_DEBUG
Enable Transport layer debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_BEACON
Beacon debug
FIG_BLE_MESH_DEBUG
Enable Beacon-related debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_CRYPTO
Crypto debug
FIG_BLE_MESH_DEBUG
Enable cryptographic debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_PROV
Provisioning debug
FIG_BLE_MESH_DEBUG
Enable Provisioning debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_ACCESS
Access layer debug
FIG_BLE_MESH_DEBUG
Enable Access layer debug logs for the BLE Mesh functionality.

CONFIG_BLE_MESH_DEBUG_MODEL
Foundation model debug
FIG_BLE_MESH_DEBUG
Enable Foundation Models debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_ADV
Advertising debug
FIG_BLE_MESH_DEBUG
Enable advertising debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_LOW_POWER
Low Power debug
FIG_BLE_MESH_DEBUG
Enable Low Power debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_FRIEND
Friend debug
FIG_BLE_MESH_DEBUG
Enable Friend debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_PROXY
Proxy debug
FIG_BLE_MESH_DEBUG
Enable Proxy protocol debug logs for the BLE Mesh functionality.
CoAP Configuration Contains:

• CONFIG_COAP_MBEDTLS_ENCRYPTION_MODE
• CONFIG_COAP_MBEDTLS_DEBUG
CONFIG_COAP_MBEDTLS_ENCRYPTION_MODE
CoAP Encryption method
Found in: Component config > CoAP Configuration
If the CoAP information is to be encrypted, the encryption environment can be set up in one of two
ways (default being Pre-Shared key mode)
• Encrypt using defined Pre-Shared Keys (PSK if uri includes coaps://)
• Encrypt using defined Public Key Infrastructure (PKI if uri includes coaps://)
Available options:
• Pre-Shared Keys (COAP_MBEDTLS_PSK)
• PKI Certificates (COAP_MBEDTLS_PKI)

CONFIG_COAP_MBEDTLS_DEBUG
Enable CoAP debugging
Found in: Component config > CoAP Configuration
Enable CoAP debugging functions at compile time for the example code.
If this option is enabled, call coap_set_log_level() at runtime in order to enable CoAP debug output via
the ESP log mechanism.
Default value:
• No (disabled)
CONFIG_COAP_MBEDTLS_DEBUG_LEVEL
Set CoAP debugging level
Found in: Component config > CoAP Configuration > CONFIG_COAP_MBEDTLS_DEBUG
Set CoAP debugging level
Available options:
• Emergency (COAP_LOG_EMERG)
• Alert (COAP_LOG_ALERT)
• Critical (COAP_LOG_CRIT)
• Error (COAP_LOG_ERROR)
• Warning (COAP_LOG_WARNING)
• Notice (COAP_LOG_NOTICE)
• Info (COAP_LOG_INFO)
• Debug (COAP_LOG_DEBUG)
• mbedTLS (COAP_LOG_MBEDTLS)
Driver configurations Contains:

• ADC configuration
• GDMA Configuration
• GPIO Configuration
• MCPWM configuration
• RTCIO configuration
• SPI configuration
• TWAI configuration
• UART configuration
ADC configuration Contains:

• CONFIG_ADC_DISABLE_DAC
• CONFIG_ADC_FORCE_XPD_FSM
CONFIG_ADC_FORCE_XPD_FSM
Use the FSM to control ADC power
Found in: Component config > Driver configurations > ADC configuration
ADC power can be controlled by the FSM instead of software. This allows the ADC to be shut off when
it is not working leading to lower power consumption. However using the FSM control ADC power will
increase the noise of ADC.
Default value:
• No (disabled)

CONFIG_ADC_DISABLE_DAC
Disable DAC when ADC2 is used on GPIO 25 and 26
Found in: Component config > Driver configurations > ADC configuration
If this is set, the ADC2 driver will disable the output of the DAC corresponding to the specified channel.
This is the default value.
For testing, disable this option so that we can measure the output of DAC by internal ADC.
Default value:
• Yes (enabled)
MCPWM configuration Contains:

• CONFIG_MCPWM_ISR_IN_IRAM
CONFIG_MCPWM_ISR_IN_IRAM
Place MCPWM ISR function into IRAM
Found in: Component config > Driver configurations > MCPWM configuration
If this option is not selected, the MCPWM interrupt will be deferred when the Cache is in a disabled
state (e.g. Flash write/erase operation).
Note that if this option is selected, all user registered ISR callbacks should never try to use cache as well.
(with IRAM_ATTR)
Default value:
• No (disabled)
SPI configuration Contains:

• CONFIG_SPI_MASTER_ISR_IN_IRAM
• CONFIG_SPI_SLAVE_ISR_IN_IRAM
• CONFIG_SPI_MASTER_IN_IRAM
• CONFIG_SPI_SLAVE_IN_IRAM
CONFIG_SPI_MASTER_IN_IRAM
Place transmitting functions of SPI master into IRAM
Found in: Component config > Driver configurations > SPI configuration
Normally only the ISR of SPI master is placed in the IRAM, so that it can work without the flash when
interrupt is triggered. For other functions, there s some possibility that the flash cache miss when
running inside and out of SPI functions, which may increase the interval of SPI transactions. Enable
this to put queue\_trans, get\_trans\_result and transmit functions into the IRAM to
avoid possible cache miss.
During unit test, this is enabled to measure the ideal case of api.
Default value:
• No (disabled)
CONFIG_SPI_MASTER_ISR_IN_IRAM
Place SPI master ISR function into IRAM
Place the SPI master ISR in to IRAM to avoid possible cache miss.

Also you can forbid the ISR being disabled during flash writing access, by add
ESP_INTR_FLAG_IRAM when initializing the driver.
Default value:
• Yes (enabled)
CONFIG_SPI_SLAVE_IN_IRAM
Place transmitting functions of SPI slave into IRAM
Normally only the ISR of SPI slave is placed in the IRAM, so that it can work without the flash when
interrupt is triggered. For other functions, there s some possibility that the flash cache miss when
running inside and out of SPI functions, which may increase the interval of SPI transactions. Enable
this to put queue\_trans, get\_trans\_result and transmit functions into the IRAM to
avoid possible cache miss.
Default value:
• No (disabled)
CONFIG_SPI_SLAVE_ISR_IN_IRAM
Place SPI slave ISR function into IRAM
Place the SPI slave ISR in to IRAM to avoid possible cache miss.
Also you can forbid the ISR being disabled during flash writing access, by add
ESP_INTR_FLAG_IRAM when initializing the driver.
Default value:
• Yes (enabled)
TWAI configuration Contains:

• CONFIG_TWAI_ERRATA_FIX_RX_FRAME_INVALID
• CONFIG_TWAI_ERRATA_FIX_BUS_OFF_REC
• CONFIG_TWAI_ERRATA_FIX_RX_FIFO_CORRUPT
• CONFIG_TWAI_ERRATA_FIX_TX_INTR_LOST
• CONFIG_TWAI_ISR_IN_IRAM
CONFIG_TWAI_ISR_IN_IRAM
Place TWAI ISR function into IRAM
Found in: Component config > Driver configurations > TWAI configuration
Place the TWAI ISR in to IRAM. This will allow the ISR to avoid cache misses, and also be able to run
whilst the cache is disabled (such as when writing to SPI Flash). Note that if this option is enabled: -
Users should also set the ESP_INTR_FLAG_IRAM in the driver configuration structure when installing
the driver (see docs for specifics). - Alert logging (i.e., setting of the TWAI_ALERT_AND_LOG flag)
will have no effect.
Default value:
• No (disabled)

CONFIG_TWAI_ERRATA_FIX_BUS_OFF_REC
Add SW workaround for REC change during bus-off
When the bus-off condition is reached, the REC should be reset to 0 and frozen (via LOM) by the driver
s ISR. However on the ESP32, there is an edge case where the REC will increase before the driver s
ISR can respond in time (e.g., due to the rapid occurrence of bus errors), thus causing the REC to be
non-zero after bus-off. A non-zero REC can prevent bus-off recovery as the bus-off recovery condition
is that both TEC and REC become 0. Enabling this option will add a workaround in the driver to forcibly
reset REC to zero on reaching bus-off.
Default value:
• No (disabled)
CONFIG_TWAI_ERRATA_FIX_TX_INTR_LOST
Add SW workaround for TX interrupt lost errata
On the ESP32, when a transmit interrupt occurs, and interrupt register is read on the same APB clock
cycle, the transmit interrupt could be lost. Enabling this option will add a workaround that checks the
transmit buffer status bit to recover any lost transmit interrupt.
Default value:
• No (disabled)
CONFIG_TWAI_ERRATA_FIX_RX_FRAME_INVALID
Add SW workaround for invalid RX frame errata
On the ESP32, when receiving a data or remote frame, if a bus error occurs in the data or CRC field,
the data of the next received frame could be invalid. Enabling this option will add a workaround that
will reset the peripheral on detection of this errata condition. Note that if a frame is transmitted on the
bus whilst the reset is ongoing, the message will not be receive by the peripheral sent on the bus during
the reset, the message will be lost.
Default value:
• No (disabled)
CONFIG_TWAI_ERRATA_FIX_RX_FIFO_CORRUPT
Add SW workaround for RX FIFO corruption errata
On the ESP32, when the RX FIFO overruns and the RX message counter maxes out at 64 messages,
the entire RX FIFO is no longer recoverable. Enabling this option will add a workaround that resets the
peripheral on detection of this errata condition. Note that if a frame is being sent on the bus during the
reset bus during the reset, the message will be lost.
Default value:
• No (disabled)
UART configuration Contains:

• CONFIG_UART_ISR_IN_IRAM

CONFIG_UART_ISR_IN_IRAM
Place UART ISR function into IRAM
Found in: Component config > Driver configurations > UART configuration
If this option is not selected, UART interrupt will be disabled for a long time and may cause data lost
when doing spi flash operation.
Default value:
• No (disabled)
RTCIO configuration Contains:

• CONFIG_RTCIO_SUPPORT_RTC_GPIO_DESC
CONFIG_RTCIO_SUPPORT_RTC_GPIO_DESC
Support array rtc_gpio_desc for ESP32
Found in: Component config > Driver configurations > RTCIO configuration
The the array rtc_gpio_desc will don t compile by default. If this option is selected, the array
rtc_gpio_desc can be compile. If user use this array, please enable this configuration.
Default value:
• No (disabled)
GPIO Configuration Contains:

• CONFIG_GPIO_ESP32_SUPPORT_SWITCH_SLP_PULL
CONFIG_GPIO_ESP32_SUPPORT_SWITCH_SLP_PULL
Support light sleep GPIO pullup/pulldown configuration for ESP32
Found in: Component config > Driver configurations > GPIO Configuration
This option is intended to fix the bug that ESP32 is not able to switch to configured pullup/pulldown
mode in sleep. If this option is selected, chip will automatically emulate the behaviour of switching, and
about 450B of source codes would be placed into IRAM.
GDMA Configuration Contains:

• CONFIG_GDMA_ISR_IRAM_SAFE
• CONFIG_GDMA_CTRL_FUNC_IN_IRAM
CONFIG_GDMA_CTRL_FUNC_IN_IRAM
Place GDMA control functions into IRAM
Found in: Component config > Driver configurations > GDMA Configuration
Place GDMA control functions (like start/stop/append/reset) into IRAM, so that these functions can be
IRAM-safe and able to be called in the other IRAM interrupt context. Enabling this option can improve
driver performance as well.
Default value:
• No (disabled)

CONFIG_GDMA_ISR_IRAM_SAFE
GDMA ISR IRAM-Safe
Found in: Component config > Driver configurations > GDMA Configuration
This will ensure the GDMA interrupt handler is IRAM-Safe, allow to avoid flash cache misses, and also
be able to run whilst the cache is disabled. (e.g. SPI Flash write).
Default value:
• No (disabled)
eFuse Bit Manager Contains:

• CONFIG_EFUSE_CODE_SCHEME_SELECTOR
• CONFIG_EFUSE_VIRTUAL
• CONFIG_EFUSE_CUSTOM_TABLE
CONFIG_EFUSE_CUSTOM_TABLE
Use custom eFuse table
Found in: Component config > eFuse Bit Manager
Allows to generate a structure for eFuse from the CSV file.
Default value:
• No (disabled)
CONFIG_EFUSE_CUSTOM_TABLE_FILENAME
Custom eFuse CSV file
Found in: Component config > eFuse Bit Manager > CONFIG_EFUSE_CUSTOM_TABLE
Name of the custom eFuse CSV filename. This path is evaluated relative to the project root directory.
Default value:
• main/esp_efuse_custom_table.csv if CONFIG_EFUSE_CUSTOM_TABLE
CONFIG_EFUSE_VIRTUAL
Simulate eFuse operations in RAM
If n - No virtual mode. All eFuse operations are real and use eFuse registers. If y - The virtual mode
is enabled and all eFuse operations (read and write) are redirected to RAM instead of eFuse registers,
all permanent changes (via eFuse) are disabled. Log output will state changes that would be applied, but
they will not be.
During startup, the eFuses are copied into RAM. This mode is useful for fast tests.
Default value:
• No (disabled)
CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH
Keep eFuses in flash
Found in: Component config > eFuse Bit Manager > CONFIG_EFUSE_VIRTUAL
In addition to the Simulate eFuse operations in RAM option, this option just adds a feature to keep
eFuses after reboots in flash memory. To use this mode the partition_table should have the efuse partition.
partition.csv: efuse_em, data, efuse, , 0x2000,

During startup, the eFuses are copied from flash or, in case if flash is empty, from real eFuse to RAM
and then update flash. This mode is useful when need to keep changes after reboot (testing secure_boot
and flash_encryption).
CONFIG_EFUSE_CODE_SCHEME_SELECTOR
Coding Scheme Compatibility
Selector eFuse code scheme.
Available options:
• None Only (EFUSE_CODE_SCHEME_COMPAT_NONE)
• 3/4 and None (EFUSE_CODE_SCHEME_COMPAT_3_4)
• Repeat, 3/4 and None (common table does not support it)
(EFUSE_CODE_SCHEME_COMPAT_REPEAT)
ESP-TLS Contains:
• CONFIG_ESP_TLS_INSECURE
• CONFIG_ESP_TLS_LIBRARY_CHOOSE
• CONFIG_ESP_TLS_CLIENT_SESSION_TICKETS
• CONFIG_ESP_DEBUG_WOLFSSL
• CONFIG_ESP_TLS_SERVER
• CONFIG_ESP_TLS_PSK_VERIFICATION
• CONFIG_ESP_TLS_SERVER_SESSION_TICKETS
• CONFIG_ESP_WOLFSSL_SMALL_CERT_VERIFY
• CONFIG_ESP_TLS_USE_SECURE_ELEMENT
CONFIG_ESP_TLS_LIBRARY_CHOOSE
Choose SSL/TLS library for ESP-TLS (See help for more Info)
Found in: Component config > ESP-TLS
The ESP-TLS APIs support multiple backend TLS libraries. Currently mbedTLS and WolfSSL are
supported. Different TLS libraries may support different features and have different resource usage.
Consult the ESP-TLS documentation in ESP-IDF Programming guide for more details.
Available options:
• mbedTLS (ESP_TLS_USING_MBEDTLS)
• wolfSSL (License info in wolfSSL directory README) (ESP_TLS_USING_WOLFSSL)
CONFIG_ESP_TLS_USE_SECURE_ELEMENT
Use Secure Element (ATECC608A) with ESP-TLS
Enable use of Secure Element for ESP-TLS, this enables internal support for ATECC608A peripheral
on ESPWROOM32SE, which can be used for TLS connection.
Default value:
• No (disabled)
CONFIG_ESP_TLS_SERVER
Enable ESP-TLS Server

Enable support for creating server side SSL/TLS session, available for mbedTLS as well as wolfSSL
TLS library.
Default value:
• No (disabled)
CONFIG_ESP_TLS_CLIENT_SESSION_TICKETS
Enable client session tickets
Enable session ticket support as specified in RFC5077.
Default value:
• No (disabled)
CONFIG_ESP_TLS_SERVER_SESSION_TICKETS
Enable server session tickets
Enable session ticket support as specified in RFC5077
Default value:
• No (disabled) if CONFIG_ESP_TLS_SERVER && ESP_TLS_USING_MBEDTLS && CON-
FIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS
CONFIG_ESP_TLS_SERVER_SESSION_TICKET_TIMEOUT
Server session ticket timeout in seconds
Found in: Component config > ESP-TLS > CONFIG_ESP_TLS_SERVER_SESSION_TICKETS
Sets the session ticket timeout used in the tls server.
Default value:
• 86400 if CONFIG_ESP_TLS_SERVER_SESSION_TICKETS
CONFIG_ESP_TLS_PSK_VERIFICATION
Enable PSK verification
Enable support for pre shared key ciphers, supported for both mbedTLS as well as wolfSSL TLS library.
Default value:
• No (disabled)
CONFIG_ESP_TLS_INSECURE
Allow potentially insecure options
You can enable some potentially insecure options. These options should only be used for testing pusposes.
Only enable these options if you are very sure.

CONFIG_ESP_TLS_SKIP_SERVER_CERT_VERIFY
Skip server certificate verification by default (WARNING: ONLY FOR TESTING PURPOSE, READ
HELP)
Found in: Component config > ESP-TLS > CONFIG_ESP_TLS_INSECURE
After enabling this option the esp-tls client will skip the server certificate verification by default. Note that
this option will only modify the default behaviour of esp-tls client regarding server cert verification. The
default behaviour should only be applicable when no other option regarding the server cert verification
is opted in the esp-tls config (e.g. crt_bundle_attach, use_global_ca_store etc.). WARNING : Enabling
this option comes with a potential risk of establishing a TLS connection with a server which has a fake
identity, provided that the server certificate is not provided either through API or other mechanism like
ca_store etc.
CONFIG_ESP_WOLFSSL_SMALL_CERT_VERIFY
Enable SMALL_CERT_VERIFY
Enables server verification with Intermediate CA cert, does not authenticate full chain of trust upto the
root CA cert (After Enabling this option client only needs to have Intermediate CA certificate of the
server to authenticate server, root CA cert is not necessary).
Default value:
• Yes (enabled) if ESP_TLS_USING_WOLFSSL
CONFIG_ESP_DEBUG_WOLFSSL
Enable debug logs for wolfSSL
Enable detailed debug prints for wolfSSL SSL library.
Default value:
• No (disabled) if ESP_TLS_USING_WOLFSSL
ESP32-specific Contains:
• CONFIG_ESP32_RTC_EXT_CRYST_ADDIT_CURRENT_METHOD
• CONFIG_ESP32_COMPATIBLE_PRE_V3_1_BOOTLOADERS
• CONFIG_ESP32_COMPATIBLE_PRE_V2_1_BOOTLOADERS
• CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ
• CONFIG_ESP32_DPORT_DIS_INTERRUPT_LVL
• CONFIG_ESP32_IRAM_AS_8BIT_ACCESSIBLE_MEMORY
• CONFIG_ESP32_ULP_COPROC_ENABLED
• CONFIG_ESP32_DEEP_SLEEP_WAKEUP_DELAY
• CONFIG_ESP32_BROWNOUT_DET
• CONFIG_ESP32_XTAL_FREQ_SEL
• CONFIG_ESP32_DEBUG_OCDAWARE
• CONFIG_ESP32_REV_MIN
• CONFIG_ESP32_NO_BLOBS
• CONFIG_ESP32_RTC_XTAL_CAL_RETRY
• CONFIG_ESP32_RTC_CLK_CAL_CYCLES
• CONFIG_ESP32_DISABLE_BASIC_ROM_CONSOLE
• CONFIG_ESP32_RTCDATA_IN_FAST_MEM
• CONFIG_ESP32_RTC_CLK_SRC
• CONFIG_ESP32_SPIRAM_SUPPORT
• CONFIG_ESP32_TIME_SYSCALL
• CONFIG_ESP32_USE_FIXED_STATIC_RAM_SIZE

• CONFIG_ESP32_TRAX
CONFIG_ESP32_REV_MIN
Minimum Supported ESP32 Revision
Found in: Component config > ESP32-specific
Minimum revision that ESP-IDF would support. ESP-IDF performs different strategy on different esp32
revision.
Available options:
• Rev 0 (ESP32_REV_MIN_0)
CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ
CPU frequency
CPU frequency to be set on application startup.
Available options:
• 40 MHz (ESP32_DEFAULT_CPU_FREQ_40)
CONFIG_ESP32_SPIRAM_SUPPORT
Support for external, SPI-connected RAM
This enables support for an external SPI RAM chip, connected in parallel with the main SPI flash chip.
Default value:
• No (disabled)
SPI RAM config Contains:

• CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY
• CONFIG_SPIRAM_ALLOW_NOINIT_SEG_EXTERNAL_MEMORY
• CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY
• CONFIG_SPIRAM_SPIWP_SD3_PIN
• CONFIG_SPIRAM_BANKSWITCH_ENABLE
• CONFIG_SPIRAM_2T_MODE
• CONFIG_SPIRAM_CACHE_WORKAROUND
• CONFIG_SPIRAM_BOOT_INIT
• CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL
• PSRAM clock and cs IO for ESP32-D2WD
• PSRAM clock and cs IO for ESP32-DOWD
• PSRAM clock and cs IO for ESP32-PICO
• CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL
• CONFIG_SPIRAM_MEMTEST
• CONFIG_SPIRAM_SPEED
• CONFIG_SPIRAM_OCCUPY_SPI_HOST
• CONFIG_SPIRAM_USE
• SPIRAM cache workaround debugging

• SPIRAM workaround libraries placement

• CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP
• CONFIG_SPIRAM_TYPE
• CONFIG_SPIRAM_CUSTOM_SPIWP_SD3_PIN
CONFIG_SPIRAM_TYPE
Type of SPI RAM chip in use
Found in: Component config > ESP32-specific > CONFIG_ESP32_SPIRAM_SUPPORT > SPI RAM config
Available options:
• Auto-detect (SPIRAM_TYPE_AUTO)
• ESP-PSRAM16 or APS1604 (SPIRAM_TYPE_ESPPSRAM16)
• ESP-PSRAM32 or IS25WP032 (SPIRAM_TYPE_ESPPSRAM32)
• ESP-PSRAM64 or LY68L6400 (SPIRAM_TYPE_ESPPSRAM64)
CONFIG_SPIRAM_SPEED
Set RAM clock speed
Select the speed for the SPI RAM chip. If SPI RAM is enabled, we only support three combinations of
SPI speed mode we supported now:
1. Flash SPI running at 40Mhz and RAM SPI running at 40Mhz
Note: If the third mode(80Mhz+80Mhz) is enabled for SPI RAM of type 32MBit, one of the HSPI/VSPI
host will be occupied by the system. Which SPI host to use can be selected by the config item
SPIRAM_OCCUPY_SPI_HOST. Application code should never touch HSPI/VSPI hardware in this
case. The option to select 80MHz will only be visible if the flash SPI speed is also 80MHz. (ESP-
TOOLPY_FLASHFREQ_80M is true)
Available options:
• 40MHz clock speed (SPIRAM_SPEED_40M)
• 80MHz clock speed (SPIRAM_SPEED_80M)
CONFIG_SPIRAM_BOOT_INIT
Initialize SPI RAM during startup
If this is enabled, the SPI RAM will be enabled during initial boot. Unless you have specific requirements,
you ll want to leave this enabled so memory allocated during boot-up can also be placed in SPI RAM.
Default value:
• Yes (enabled) if CONFIG_ESP32_SPIRAM_SUPPORT
CONFIG_SPIRAM_IGNORE_NOTFOUND
Ignore PSRAM when not found
> CONFIG_SPIRAM_BOOT_INIT
Normally, if psram initialization is enabled during compile time but not found at runtime, it is seen as an
error making the CPU panic. If this is enabled, booting will complete but no PSRAM will be available.
Default value:

• No (disabled) if CONFIG_SPIRAM_BOOT_INIT && CON-

FIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY && CON-
FIG_ESP32_SPIRAM_SUPPORT
CONFIG_SPIRAM_USE
SPI RAM access method
The SPI RAM can be accessed in multiple methods: by just having it available as an unmanaged mem-
ory region in the CPU s memory map, by integrating it in the heap as special memory needing
heap_caps_malloc to allocate, or by fully integrating it making malloc() also able to return SPI RAM
pointers.
Available options:
• Integrate RAM into memory map (SPIRAM_USE_MEMMAP)
• Make RAM allocatable using heap_caps_malloc( , MALLOC_CAP_SPIRAM) (SPI-
RAM_USE_CAPS_ALLOC)
• Make RAM allocatable using malloc() as well (SPIRAM_USE_MALLOC)
CONFIG_SPIRAM_MEMTEST
Run memory test on SPI RAM initialization
Runs a rudimentary memory test on initialization. Aborts when memory test fails. Disable this for
slightly faster startup.
Default value:
• Yes (enabled) if CONFIG_SPIRAM_BOOT_INIT && CONFIG_ESP32_SPIRAM_SUPPORT
CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL
Maximum malloc() size, in bytes, to always put in internal memory
If malloc() is capable of also allocating SPI-connected ram, its allocation strategy will prefer to allocate
chunks less than this size in internal memory, while allocations larger than this will be done from external
RAM. If allocation from the preferred region fails, an attempt is made to allocate from the non-preferred
region instead, so malloc() will not suddenly fail when either internal or external memory is full.
Range:
• from 0 to 131072 if SPIRAM_USE_MALLOC && CONFIG_ESP32_SPIRAM_SUPPORT
Default value:
• 16384 if SPIRAM_USE_MALLOC && CONFIG_ESP32_SPIRAM_SUPPORT
CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP
Try to allocate memories of WiFi and LWIP in SPIRAM firstly. If failed, allocate internal memory
Try to allocate memories of WiFi and LWIP in SPIRAM firstly. If failed, try to allocate internal memory
then.
Default value:
• No (disabled) if (SPIRAM_USE_CAPS_ALLOC || SPIRAM_USE_MALLOC) && CON-

CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL
Reserve this amount of bytes for data that specifically needs to be in DMA or internal memory
Because the external/internal RAM allocation strategy is not always perfect, it sometimes may happen
that the internal memory is entirely filled up. This causes allocations that are specifically done in internal
memory, for example the stack for new tasks or memory to service DMA or have memory that s also
available when SPI cache is down, to fail. This option reserves a pool specifically for requests like that;
the memory in this pool is not given out when a normal malloc() is called.
Set this to 0 to disable this feature.
Note that because FreeRTOS stacks are forced to internal memory, they will also use this memory pool;
be sure to keep this in mind when adjusting this value.
Note also that the DMA reserved pool may not be one single contiguous memory region, depending on
the configured size and the static memory usage of the app.
Range:
• from 0 to 262144 if SPIRAM_USE_MALLOC && CONFIG_ESP32_SPIRAM_SUPPORT
Default value:
• 32768 if SPIRAM_USE_MALLOC && CONFIG_ESP32_SPIRAM_SUPPORT
CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY
Allow .bss segment placed in external memory
If enabled, variables with EXT_RAM_ATTR attribute will be placed in SPIRAM instead of internal
DRAM. BSS section of lwip, net80211, pp, bt libraries will be automatically placed in SPIRAM. BSS
sections from other object files and libraries can also be placed in SPIRAM through linker fragment
scheme extram_bss.
Note that the variables placed in SPIRAM using EXT_RAM_ATTR will be zero initialized.
CONFIG_SPIRAM_ALLOW_NOINIT_SEG_EXTERNAL_MEMORY
Allow .noinit segment placed in external memory
If enabled, noinit variables can be placed in PSRAM using EXT_RAM_NOINIT_ATTR.
Note the values placed into this section will not be initialized at startup and should keep its value after
software restart.
CONFIG_SPIRAM_CACHE_WORKAROUND
Enable workaround for bug in SPI RAM cache for Rev1 ESP32s
Revision 1 of the ESP32 has a bug that can cause a write to PSRAM not to take place in some situations
when the cache line needs to be fetched from external RAM and an interrupt occurs. This enables a fix
in the compiler (-mfix-esp32-psram-cache-issue) that makes sure the specific code that is vulnerable to
this will not be emitted.
This will also not use any bits of newlib that are located in ROM, opting for a version that is compiled
with the workaround and located in flash instead.
The workaround is not required for ESP32 revision 3 and above.
Default value:

• Yes (enabled) if (SPIRAM_USE_MEMMAP || SPIRAM_USE_CAPS_ALLOC || SPI-

RAM_USE_MALLOC) && CONFIG_ESP32_SPIRAM_SUPPORT
SPIRAM cache workaround debugging Contains:

• CONFIG_SPIRAM_CACHE_WORKAROUND_STRATEGY
CONFIG_SPIRAM_CACHE_WORKAROUND_STRATEGY
Workaround strategy
> SPIRAM cache workaround debugging
Select the workaround strategy. Note that the strategy for precompiled libraries (libgcc, newlib, bt, wifi)
is not affected by this selection.
Unless you know you need a different strategy, it s suggested you stay with the default MEMW strategy.
Note that DUPLDST can interfere with hardware encryption and this will be automatically disabled if
this workaround is selected. Insert nops is the workaround that was used in older esp-idf versions.
This workaround still can cause faulty data transfers from/to SPI RAM in some situation.
Available options:
• Insert memw after vulnerable instructions (default) (SPI-
RAM_CACHE_WORKAROUND_STRATEGY_MEMW)
• Duplicate LD/ST for 32-bit, memw for 8/16 bit (SPI-
RAM_CACHE_WORKAROUND_STRATEGY_DUPLDST)
• Insert nops between vulnerable loads/stores (old strategy, obsolete) (SPI-
RAM_CACHE_WORKAROUND_STRATEGY_NOPS)
SPIRAM workaround libraries placement Contains:

• CONFIG_SPIRAM_CACHE_LIBCHAR_IN_IRAM
• CONFIG_SPIRAM_CACHE_LIBENV_IN_IRAM
• CONFIG_SPIRAM_CACHE_LIBFILE_IN_IRAM
• CONFIG_SPIRAM_CACHE_LIBIO_IN_IRAM
• CONFIG_SPIRAM_CACHE_LIBJMP_IN_IRAM
• CONFIG_SPIRAM_CACHE_LIBMATH_IN_IRAM
• CONFIG_SPIRAM_CACHE_LIBMEM_IN_IRAM
• CONFIG_SPIRAM_CACHE_LIBMISC_IN_IRAM
• CONFIG_SPIRAM_CACHE_LIBNUMPARSER_IN_IRAM
• CONFIG_SPIRAM_CACHE_LIBRAND_IN_IRAM
• CONFIG_SPIRAM_CACHE_LIBSTR_IN_IRAM
• CONFIG_SPIRAM_CACHE_LIBTIME_IN_IRAM
CONFIG_SPIRAM_CACHE_LIBJMP_IN_IRAM
Put libc s jump related functions in IRAM
> SPIRAM workaround libraries placement
The functions affected by this option are: longjmp and setjmp. Putting these function in IRAM will
allow them to be called when flash cache is disabled but it will also reduce the available size of free
IRAM for the user application.
Default value:
• Yes (enabled) if CONFIG_SPIRAM_CACHE_WORKAROUND && CON-

CONFIG_SPIRAM_CACHE_LIBMATH_IN_IRAM
Put libc s math related functions in IRAM
The functions affected by this option are: abs, div, labs, ldiv, quorem, fpclassify, and nan. Putting these
function in IRAM will allow them to be called when flash cache is disabled but it will also reduce the
available size of free IRAM for the user application.
Default value:
CONFIG_SPIRAM_CACHE_LIBNUMPARSER_IN_IRAM
Put libc s number parsing related functions in IRAM
The functions affected by this option are: utoa, itoa, atoi, atol, strtol, and strtoul. Putting these function
in IRAM will allow them to be called when flash cache is disabled but it will also reduce the available
size of free IRAM for the user application.
Default value:
CONFIG_SPIRAM_CACHE_LIBIO_IN_IRAM
Put libc s I/O related functions in IRAM
The functions affected by this option are: wcrtomb, fvwrite, wbuf, wsetup, fputwc, wctomb_r, ungetc,
makebuf, fflush, refill, and sccl. Putting these function in IRAM will allow them to be called when flash
cache is disabled but it will also reduce the available size of free IRAM for the user application.
Default value:
CONFIG_SPIRAM_CACHE_LIBTIME_IN_IRAM
Put libc s time related functions in IRAM
The functions affected by this option are: asctime, asctime_r, ctime, ctime_r, lcltime, lcltime_r, gmtime,
gmtime_r, strftime, mktime, tzset_r, tzset, time, gettzinfo, systimes, month_lengths, timelocal, tzvars,
tzlock, tzcalc_limits, and strptime. Putting these function in IRAM will allow them to be called when
flash cache is disabled but it will also reduce the available size of free IRAM for the user application.
Default value:

CONFIG_SPIRAM_CACHE_LIBCHAR_IN_IRAM
Put libc s characters related functions in IRAM
The functions affected by this option are: ctype_, toupper, tolower, toascii, strupr, bzero, isalnum, isal-
pha, isascii, isblank, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, and isupper. Putting these
Default value:
CONFIG_SPIRAM_CACHE_LIBMEM_IN_IRAM
Put libc s memory related functions in IRAM
The functions affected by this option are: memccpy, memchr memmove, and memrchr. Putting these
Default value:
CONFIG_SPIRAM_CACHE_LIBSTR_IN_IRAM
Put libc s string related functions in IRAM
The functions affected by this option are: strcasecmp, strcasestr, strchr, strcoll, strcpy, strcspn, strdup,
strdup_r, strlcat, strlcpy, strlen, strlwr, strncasecmp, strncat, strncmp, strncpy, strndup, strndup_r, str-
rchr, strsep, strspn, strstr, strtok_r, and strupr. Putting these function in IRAM will allow them to be
called when flash cache is disabled but it will also reduce the available size of free IRAM for the user
application.
Default value:
CONFIG_SPIRAM_CACHE_LIBRAND_IN_IRAM
Put libc s random related functions in IRAM
The functions affected by this option are: srand, rand, and rand_r. Putting these function in IRAM will
allow them to be called when flash cache is disabled but it will also reduce the available size of free
IRAM for the user application.
Default value:

CONFIG_SPIRAM_CACHE_LIBENV_IN_IRAM
Put libc s environment related functions in IRAM
The functions affected by this option are: environ, envlock, and getenv_r. Putting these function in
IRAM will allow them to be called when flash cache is disabled but it will also reduce the available size
of free IRAM for the user application.
Default value:
CONFIG_SPIRAM_CACHE_LIBFILE_IN_IRAM
Put libc s file related functions in IRAM
The functions affected by this option are: lock, isatty, fclose, open, close, creat, read, rshift, sbrk, stdio,
syssbrk, sysclose, sysopen, creat, sysread, syswrite, impure, fwalk, and findfp. Putting these function in
IRAM will allow them to be called when flash cache is disabled but it will also reduce the available size
of free IRAM for the user application.
Default value:
CONFIG_SPIRAM_CACHE_LIBMISC_IN_IRAM
Put libc s miscellaneous functions in IRAM, see help
The functions affected by this option are: raise and system Putting these function in IRAM will allow
them to be called when flash cache is disabled but it will also reduce the available size of free IRAM for
the user application.
Default value:
CONFIG_SPIRAM_BANKSWITCH_ENABLE
Enable bank switching for >4MiB external RAM
The ESP32 only supports 4MiB of external RAM in its address space. The hardware does support larger
memories, but these have to be bank-switched in and out of this address space. Enabling this allows you
to reserve some MMU pages for this, which allows the use of the esp_himem api to manage these banks.
#Note that this is limited to 62 banks, as esp_spiram_writeback_cache needs some kind of mapping of
#some banks below that mark to work. We cannot at this moment guarantee this to exist when himem
is #enabled.
If spiram 2T mode is enabled, the size of 64Mbit psram will be changed as 32Mbit, so himem will be
unusable.
Default value:

• Yes (enabled) if (SPIRAM_USE_MEMMAP || SPIRAM_USE_CAPS_ALLOC || SPI-

RAM_USE_MALLOC) && CONFIG_ESP32_SPIRAM_SUPPORT
CONFIG_SPIRAM_BANKSWITCH_RESERVE
Amount of 32K pages to reserve for bank switching
> CONFIG_SPIRAM_BANKSWITCH_ENABLE
Select the amount of banks reserved for bank switching. Note that the amount of RAM allocatable with
malloc/esp_heap_alloc_caps will decrease by 32K for each page reserved here.
Note that this reservation is only actually done if your program actually uses the himem API. Without
any himem calls, the reservation is not done and the original amount of memory will be available to
malloc/esp_heap_alloc_caps.
Range:
• from 1 to 62 if CONFIG_SPIRAM_BANKSWITCH_ENABLE && CON-
Default value:
• 8 if CONFIG_SPIRAM_BANKSWITCH_ENABLE && CONFIG_ESP32_SPIRAM_SUPPORT
CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY
Allow external memory as an argument to xTaskCreateStatic
Because some bits of the ESP32 code environment cannot be recompiled with the cache workaround,
normally tasks cannot be safely run with their stack residing in external memory; for this reason
xTaskCreate (and related task creaton functions) always allocate stack in internal memory and xTaskCre-
ateStatic will check if the memory passed to it is in internal memory. If you have a task that needs a large
amount of stack and does not call on ROM code in any way (no direct calls, but also no Bluetooth/WiFi),
you can try enable this to cause xTaskCreateStatic to allow tasks stack in external memory.
Default value:
• No (disabled) if SPIRAM_USE_MALLOC && CONFIG_ESP32_SPIRAM_SUPPORT
CONFIG_SPIRAM_OCCUPY_SPI_HOST
SPI host to use for 32MBit PSRAM
When both flash and PSRAM is working under 80MHz, and the PSRAM is of type 32MBit, one of the
HSPI/VSPI host will be used to output the clock. Select which one to use here.
Available options:
• HSPI host (SPI2) (SPIRAM_OCCUPY_HSPI_HOST)
• VSPI host (SPI3) (SPIRAM_OCCUPY_VSPI_HOST)
• Will not try to use any host, will abort if not able to use the PSRAM (SPI-
RAM_OCCUPY_NO_HOST)
PSRAM clock and cs IO for ESP32-DOWD Contains:

• CONFIG_D0WD_PSRAM_CLK_IO
• CONFIG_D0WD_PSRAM_CS_IO

CONFIG_D0WD_PSRAM_CLK_IO
PSRAM CLK IO number
> PSRAM clock and cs IO for ESP32-DOWD
The PSRAM CLOCK IO can be any unused GPIO, user can config it based on hardware design. If user
use 1.8V flash and 1.8V psram, this value can only be one of 6, 7, 8, 9, 10, 11, 16, 17.
Range:
• from 0 to 33 if CONFIG_ESP32_SPIRAM_SUPPORT && CON-
Default value:
• 17 if CONFIG_ESP32_SPIRAM_SUPPORT && CONFIG_ESP32_SPIRAM_SUPPORT
CONFIG_D0WD_PSRAM_CS_IO
PSRAM CS IO number
> PSRAM clock and cs IO for ESP32-DOWD
The PSRAM CS IO can be any unused GPIO, user can config it based on hardware design. If user use
1.8V flash and 1.8V psram, this value can only be one of 6, 7, 8, 9, 10, 11, 16, 17.
Range:
Default value:
PSRAM clock and cs IO for ESP32-D2WD Contains:

• CONFIG_D2WD_PSRAM_CLK_IO
• CONFIG_D2WD_PSRAM_CS_IO
CONFIG_D2WD_PSRAM_CLK_IO
PSRAM CLK IO number
> PSRAM clock and cs IO for ESP32-D2WD
User can config it based on hardware design. For ESP32-D2WD chip, the psram can only be 1.8V
psram, so this value can only be one of 6, 7, 8, 9, 10, 11, 16, 17.
Range:
Default value:
CONFIG_D2WD_PSRAM_CS_IO
PSRAM CS IO number
> PSRAM clock and cs IO for ESP32-D2WD
User can config it based on hardware design. For ESP32-D2WD chip, the psram can only be 1.8V
psram, so this value can only be one of 6, 7, 8, 9, 10, 11, 16, 17.
Range:


Default value:
PSRAM clock and cs IO for ESP32-PICO Contains:

• CONFIG_PICO_PSRAM_CS_IO
CONFIG_PICO_PSRAM_CS_IO
PSRAM CS IO number
> PSRAM clock and cs IO for ESP32-PICO
The PSRAM CS IO can be any unused GPIO, user can config it based on hardware design.
For ESP32-PICO chip, the psram share clock with flash, so user do not need to configure the clock
IO. For the reference hardware design, please refer to https://www.espressif.com/sites/default/files/
documentation/esp32-pico-d4_datasheet_en.pdf
Range:
Default value:
CONFIG_SPIRAM_CUSTOM_SPIWP_SD3_PIN
Use custom SPI PSRAM WP(SD3) Pin when flash pins set in eFuse (read help)
This setting is only used if the SPI flash pins have been overridden by setting the eFuses
SPI_PAD_CONFIG_xxx, and the SPI flash mode is DIO or DOUT.
When this is the case, the eFuse config only defines 3 of the 4 Quad I/O data pins. The WP pin (aka
ESP32 pin SD_DATA_3 or SPI flash pin IO2 ) is not specified in eFuse. The psram only has
QPI mode, so a WP pin setting is necessary.
If this config item is set to N (default), the correct WP pin will be automatically used for any Espressif
chip or module with integrated flash. If a custom setting is needed, set this config item to Y and specify
the GPIO number connected to the WP pin.
When flash mode is set to QIO or QOUT, the PSRAM WP pin will be set the same as the SPI Flash
WP pin configured in the bootloader.
Default value:
• No (disabled) if (ESPTOOLPY_FLASHMODE_DIO || ESP-
TOOLPY_FLASHMODE_DOUT) && CONFIG_ESP32_SPIRAM_SUPPORT
CONFIG_SPIRAM_SPIWP_SD3_PIN
Custom SPI PSRAM WP(SD3) Pin
The option Use custom SPI PSRAM WP(SD3) pin must be set or this value is ignored
If burning a customized set of SPI flash pins in eFuse and using DIO or DOUT mode for flash, set this
value to the GPIO number of the SPIRAM WP pin.
Range:

• from 0 to 33 if (ESPTOOLPY_FLASHMODE_DIO || ESP-

TOOLPY_FLASHMODE_DOUT) && CONFIG_ESP32_SPIRAM_SUPPORT
Default value:
• 7 if (ESPTOOLPY_FLASHMODE_DIO || ESPTOOLPY_FLASHMODE_DOUT) &&
CONFIG_ESP32_SPIRAM_SUPPORT
CONFIG_SPIRAM_2T_MODE
Enable SPI PSRAM 2T mode
Enable this option to fix single bit errors inside 64Mbit PSRAM.
Some 64Mbit PSRAM chips have a hardware issue in the RAM which causes bit errors at multiple fixed
bit positions.
Note: If this option is enabled, the 64Mbit PSRAM chip will appear to be 32Mbit in size. Applications
will not be affected unless the use the esp_himem APIs, which are not supported in 2T mode.
Default value:
• No (disabled) if CONFIG_ESP32_SPIRAM_SUPPORT && CON-
CONFIG_ESP32_TRAX
Use TRAX tracing feature
The ESP32 contains a feature which allows you to trace the execution path the processor has taken
through the program. This is stored in a chunk of 32K (16K for single-processor) of memory that can
t be used for general purposes anymore. Disable this if you do not know what this is.
Default value:
• No (disabled)
CONFIG_ESP32_TRAX_TWOBANKS
Reserve memory for tracing both pro as well as app cpu execution
Found in: Component config > ESP32-specific > CONFIG_ESP32_TRAX
The ESP32 contains a feature which allows you to trace the execution path the processor has taken
through the program. This is stored in a chunk of 32K (16K for single-processor) of memory that can
t be used for general purposes anymore. Disable this if you do not know what this is.
# Memory to reverse for trace, used in linker script
Default value:
• No (disabled) if CONFIG_ESP32_TRAX && CONFIG_FREERTOS_UNICORE
CONFIG_ESP32_ULP_COPROC_ENABLED
Enable Ultra Low Power (ULP) Coprocessor
Set to y if you plan to load a firmware for the coprocessor.
If this option is enabled, further coprocessor configuration will appear in the Components menu.
Default value:
• No (disabled)

CONFIG_ESP32_ULP_COPROC_RESERVE_MEM
RTC slow memory reserved for coprocessor
Found in: Component config > ESP32-specific > CONFIG_ESP32_ULP_COPROC_ENABLED
Bytes of memory to reserve for ULP coprocessor firmware & data.
Data is reserved at the beginning of RTC slow memory.
Range:
• from 32 to 8176 if CONFIG_ESP32_ULP_COPROC_ENABLED
• from 0 to 0 if CONFIG_ESP32_ULP_COPROC_ENABLED
Default value:
• 512 if CONFIG_ESP32_ULP_COPROC_ENABLED
• 0 if CONFIG_ESP32_ULP_COPROC_ENABLED
CONFIG_ESP32_DEBUG_OCDAWARE
Make exception and panic handlers JTAG/OCD aware
The FreeRTOS panic and unhandled exception handers can detect a JTAG OCD debugger and instead
of panicking, have the debugger stop on the offending instruction.
Default value:
• Yes (enabled)
CONFIG_ESP32_BROWNOUT_DET
Hardware brownout detect & reset
The ESP32 has a built-in brownout detector which can detect if the voltage is lower than a specific value.
If this happens, it will reset the chip in order to prevent unintended behaviour.
Default value:
• Yes (enabled)
CONFIG_ESP32_BROWNOUT_DET_LVL_SEL
Brownout voltage level
Found in: Component config > ESP32-specific > CONFIG_ESP32_BROWNOUT_DET
The brownout detector will reset the chip when the supply voltage is approximately below this level.
Note that there may be some variation of brownout voltage level between each ESP32 chip.
#The voltage levels here are estimates, more work needs to be done to figure out the exact voltages #of
the brownout threshold levels.
Available options:
• 2.43V +/- 0.05 (ESP32_BROWNOUT_DET_LVL_SEL_0)

CONFIG_ESP32_TIME_SYSCALL
Timers used for gettimeofday function
This setting defines which hardware timers are used to implement gettimeofday and time functions
in C library.
• If both high-resolution and RTC timers are used, timekeeping will continue in deep sleep. Time
will be reported at 1 microsecond resolution. This is the default, and the recommended option.
• If only high-resolution timer is used, gettimeofday will provide time at microsecond resolution.
Time will not be preserved when going into deep sleep mode.
• If only RTC timer is used, timekeeping will continue in deep sleep, but time will be measured at
6.(6) microsecond resolution. Also the gettimeofday function itself may take longer to run.
• If no timers are used, gettimeofday and time functions return -1 and set errno to ENOSYS.
• When RTC is used for timekeeping, two RTC_STORE registers are used to keep time in deep
sleep mode.
Available options:
• RTC and high-resolution timer (ESP32_TIME_SYSCALL_USE_RTC_FRC1)
• RTC (ESP32_TIME_SYSCALL_USE_RTC)
• High-resolution timer (ESP32_TIME_SYSCALL_USE_FRC1)
• None (ESP32_TIME_SYSCALL_USE_NONE)
CONFIG_ESP32_RTC_CLK_SRC
RTC clock source
Choose which clock is used as RTC clock source.
• Internal 150kHz oscillator option provides lowest deep sleep current consumption, and does
not require extra external components. However frequency stability with respect to temperature is
poor, so time may drift in deep/light sleep modes.
• External 32kHz crystal provides better frequency stability, at the expense of slightly higher (1uA)
deep sleep current consumption.
• External 32kHz oscillator allows using 32kHz clock generated by an external circuit. In this
case, external clock signal must be connected to 32K_XN pin. Amplitude should be <1.2V in
case of sine wave signal, and <1V in case of square wave signal. Common mode voltage should be
0.1 < Vcm < 0.5Vamp, where Vamp is the signal amplitude. Additionally, 1nF capacitor must be
connected between 32K_XP pin and ground. 32K_XP pin can not be used as a GPIO in this case.
• Internal 8.5MHz oscillator divided by 256 option results in higher deep sleep current (by 5uA)
but has better frequency stability than the internal 150kHz oscillator. It does not require external
components.
Available options:
• Internal 150kHz RC oscillator (ESP32_RTC_CLK_SRC_INT_RC)
• External 32kHz crystal (ESP32_RTC_CLK_SRC_EXT_CRYS)
• External 32kHz oscillator at 32K_XN pin (ESP32_RTC_CLK_SRC_EXT_OSC)
• Internal 8.5MHz oscillator, divided by 256 (~33kHz)
(ESP32_RTC_CLK_SRC_INT_8MD256)
CONFIG_ESP32_RTC_EXT_CRYST_ADDIT_CURRENT_METHOD
Additional current for external 32kHz crystal
With some 32kHz crystal configurations, the X32N and X32P pins may not have enough drive strength
to keep the crystal oscillating. Choose the method to provide additional current from touchpad 9 to the

external 32kHz crystal. Note that the deep sleep current is slightly high (4-5uA) and the touchpad and
the wakeup sources of both touchpad and ULP are not available in method 1 and method 2.
This problem is fixed in ESP32 ECO 3, so this workaround is not needed. Setting the project configura-
tion to minimum revision ECO3 will disable this option, , allow all wakeup sources, and save some code
size.
• None option will not provide additional current to external crystal
• Method 1 option can t ensure 100% to solve the external 32k crystal start failed issue, but the
touchpad can work in this method.
• Method 2 option can solve the external 32k issue, but the touchpad can t work in this method.
Available options:
• None (ESP32_RTC_EXT_CRYST_ADDIT_CURRENT_NONE)
• Method 1 (ESP32_RTC_EXT_CRYST_ADDIT_CURRENT)
• Method 2 (ESP32_RTC_EXT_CRYST_ADDIT_CURRENT_V2)
CONFIG_ESP32_RTC_CLK_CAL_CYCLES
Number of cycles for RTC_SLOW_CLK calibration
When the startup code initializes RTC_SLOW_CLK, it can perform calibration by comparing
the RTC_SLOW_CLK frequency with main XTAL frequency. This option sets the number of
RTC_SLOW_CLK cycles measured by the calibration routine. Higher numbers increase calibration
precision, which may be important for applications which spend a lot of time in deep sleep. Lower
numbers reduce startup time.
When this option is set to 0, clock calibration will not be performed at startup, and approximate clock
frequencies will be assumed:
• 150000 Hz if internal RC oscillator is used as clock source. For this use value 1024.
• 32768 Hz if the 32k crystal oscillator is used. For this use value 3000 or more. In case more value
will help improve the definition of the launch of the crystal. If the crystal could not start, it will be
switched to internal RC.
Range:
• from 0 to 27000 if ESP32_RTC_CLK_SRC_EXT_CRYS ||
ESP32_RTC_CLK_SRC_EXT_OSC || ESP32_RTC_CLK_SRC_INT_8MD256
• from 0 to 32766
Default value:
• 3000 if ESP32_RTC_CLK_SRC_EXT_CRYS || ESP32_RTC_CLK_SRC_EXT_OSC ||
ESP32_RTC_CLK_SRC_INT_8MD256
• 1024
CONFIG_ESP32_RTC_XTAL_CAL_RETRY
Number of attempts to repeat 32k XTAL calibration
Number of attempts to repeat 32k XTAL calibration before giving up and switching to the internal RC.
Increase this option if the 32k crystal oscillator does not start and switches to internal RC.
Default value:
• 1 if ESP32_RTC_CLK_SRC_EXT_CRYS
CONFIG_ESP32_DEEP_SLEEP_WAKEUP_DELAY
Extra delay in deep sleep wake stub (in us)

When ESP32 exits deep sleep, the CPU and the flash chip are powered on at the same time. CPU will
run deep sleep stub first, and then proceed to load code from flash. Some flash chips need sufficient
time to pass between power on and first read operation. By default, without any extra delay, this time is
approximately 900us, although some flash chip types need more than that.
By default extra delay is set to 2000us. When optimizing startup time for applications which require it,
this value may be reduced.
If you are seeing flash read err, 1000 message printed to the console after deep sleep reset, try
increasing this value.
Range:
• from 0 to 5000
Default value:
• 2000
CONFIG_ESP32_XTAL_FREQ_SEL
Main XTAL frequency
ESP32 currently supports the following XTAL frequencies:
• 26 MHz
• 40 MHz
Startup code can automatically estimate XTAL frequency. This feature uses the internal 8MHz os-
cillator as a reference. Because the internal oscillator frequency is temperature dependent, it is not
recommended to use automatic XTAL frequency detection in applications which need to work at high
ambient temperatures and use high-temperature qualified chips and modules.
Available options:
• 40 MHz (ESP32_XTAL_FREQ_40)
• 26 MHz (ESP32_XTAL_FREQ_26)
• Autodetect (ESP32_XTAL_FREQ_AUTO)
CONFIG_ESP32_DISABLE_BASIC_ROM_CONSOLE
Permanently disable BASIC ROM Console
If set, the first time the app boots it will disable the BASIC ROM Console permanently (by burning an
eFuse).
Otherwise, the BASIC ROM Console starts on reset if no valid bootloader is read from the flash.
(Enabling secure boot also disables the BASIC ROM Console by default.)
Default value:
• No (disabled)
CONFIG_ESP32_NO_BLOBS
No Binary Blobs
If enabled, this disables the linking of binary libraries in the application build. Note that after enabling
this Wi-Fi/Bluetooth will not work.
Default value:
• No (disabled) if CONFIG_BT_ENABLED

CONFIG_ESP32_COMPATIBLE_PRE_V2_1_BOOTLOADERS
App compatible with bootloaders before ESP-IDF v2.1
Bootloaders before ESP-IDF v2.1 did less initialisation of the system clock. This setting needs to be
enabled to build an app which can be booted by these older bootloaders.
If this setting is enabled, the app can be booted by any bootloader from IDF v1.0 up to the current
version.
If this setting is disabled, the app can only be booted by bootloaders from IDF v2.1 or newer.
Enabling this setting adds approximately 1KB to the app s IRAM usage.
Default value:
• No (disabled)
CONFIG_ESP32_COMPATIBLE_PRE_V3_1_BOOTLOADERS
App compatible with bootloader and partition table before ESP-IDF v3.1
Partition tables before ESP-IDF V3.1 do not contain an MD5 checksum field, and the bootloader before
ESP-IDF v3.1 cannot read a partition table that contains an MD5 checksum field.
Enable this option only if your app needs to boot on a bootloader and/or partition table that was generated
from a version *before* ESP-IDF v3.1.
If this option and Flash Encryption are enabled at the same time, and any data partitions in the partition
table are marked Encrypted, then the partition encrypted flag should be manually verified in the app
before accessing the partition (see CVE-2021-27926).
Default value:
• No (disabled)
CONFIG_ESP32_RTCDATA_IN_FAST_MEM
Place RTC_DATA_ATTR and RTC_RODATA_ATTR variables into RTC fast memory segment
This option allows to place .rtc_data and .rtc_rodata sections into RTC fast memory segment to free the
slow memory region for ULP programs. This option depends on the CONFIG_FREERTOS_UNICORE
option because RTC fast memory can be accessed only by PRO_CPU core.
Default value:
• No (disabled) if CONFIG_FREERTOS_UNICORE
CONFIG_ESP32_USE_FIXED_STATIC_RAM_SIZE
Use fixed static RAM size
If this option is disabled, the DRAM part of the heap starts right after the .bss section, within the
dram0_0 region. As a result, adding or removing some static variables will change the available heap
size.
If this option is enabled, the DRAM part of the heap starts right after the dram0_0 region, where its
length is set with ESP32_FIXED_STATIC_RAM_SIZE
Default value:
• No (disabled)

CONFIG_ESP32_FIXED_STATIC_RAM_SIZE
Fixed Static RAM size
Found in: Component config > ESP32-specific > CONFIG_ESP32_USE_FIXED_STATIC_RAM_SIZE
RAM size dedicated for static variables (.data & .bss sections). Please note that the actual length will be
reduced by BTDM_RESERVE_DRAM if Bluetooth controller is enabled.
Range:
• from 0 to 0x2c200 if CONFIG_ESP32_USE_FIXED_STATIC_RAM_SIZE
Default value:
• 0x1E000 if CONFIG_ESP32_USE_FIXED_STATIC_RAM_SIZE
CONFIG_ESP32_DPORT_DIS_INTERRUPT_LVL
Disable the interrupt level for the DPORT workarounds
To prevent interrupting DPORT workarounds, need to disable interrupt with a maximum used level in
the system.
Default value:
• 5
CONFIG_ESP32_IRAM_AS_8BIT_ACCESSIBLE_MEMORY
Enable IRAM as 8 bit accessible memory
If enabled, application can use IRAM as byte accessible region for storing data (Note: IRAM region
cannot be used as task stack)
This is possible due to handling of exceptions LoadStoreError (3) and LoadStoreAlignmentError (9) Each
unaligned read/write access will incur a penalty of maximum of 167 CPU cycles.
ADC-Calibration Contains:
• CONFIG_ADC_CAL_EFUSE_VREF_ENABLE
• CONFIG_ADC_CAL_LUT_ENABLE
• CONFIG_ADC_CAL_EFUSE_TP_ENABLE
CONFIG_ADC_CAL_EFUSE_TP_ENABLE
Use Two Point Values
Found in: Component config > ADC-Calibration
Some ESP32s have Two Point calibration values burned into eFuse BLOCK3. This option will allow
the ADC calibration component to characterize the ADC-Voltage curve using Two Point values if they
are available.
Default value:
• Yes (enabled)
CONFIG_ADC_CAL_EFUSE_VREF_ENABLE
Use eFuse Vref
Some ESP32s have Vref burned into eFuse BLOCK0. This option will allow the ADC calibration
component to characterize the ADC-Voltage curve using eFuse Vref if it is available.

Default value:
• Yes (enabled)
CONFIG_ADC_CAL_LUT_ENABLE
Use Lookup Tables
This option will allow the ADC calibration component to use Lookup Tables to correct for non-linear
behavior in 11db attenuation. Other attenuations do not exhibit non-linear behavior hence will not be
affected by this option.
Default value:
• Yes (enabled)
Common ESP-related Contains:

• CONFIG_ESP_ERR_TO_NAME_LOOKUP
CONFIG_ESP_ERR_TO_NAME_LOOKUP
Enable lookup of error code strings
Found in: Component config > Common ESP-related
Functions esp_err_to_name() and esp_err_to_name_r() return string representations of error codes from
a pre-generated lookup table. This option can be used to turn off the use of the look-up table in order
to save memory but this comes at the price of sacrificing distinguishable (meaningful) output string
representations.
Default value:
• Yes (enabled)
Ethernet Contains:
• CONFIG_ETH_USE_ESP32_EMAC
• CONFIG_ETH_USE_OPENETH
• CONFIG_ETH_USE_SPI_ETHERNET
CONFIG_ETH_USE_ESP32_EMAC
Support ESP32 internal EMAC controller
Found in: Component config > Ethernet
ESP32 integrates a 10/100M Ethernet MAC controller.
Default value:
• Yes (enabled)
Contains:
• CONFIG_ETH_DMA_RX_BUFFER_NUM
• CONFIG_ETH_DMA_TX_BUFFER_NUM
• CONFIG_ETH_SOFT_FLOW_CONTROL
• CONFIG_ETH_DMA_BUFFER_SIZE
• CONFIG_ETH_RMII_CLK_OUTPUT_GPIO0
• CONFIG_ETH_PHY_INTERFACE
• CONFIG_ETH_RMII_CLK_OUT_GPIO
• CONFIG_ETH_RMII_CLK_MODE

CONFIG_ETH_PHY_INTERFACE
PHY interface
Found in: Component config > Ethernet > CONFIG_ETH_USE_ESP32_EMAC
Select the communication interface between MAC and PHY chip.
Available options:
• Reduced Media Independent Interface (RMII) (ETH_PHY_INTERFACE_RMII)
CONFIG_ETH_RMII_CLK_MODE
RMII clock mode
Select external or internal RMII clock.
Available options:
• Input RMII clock from external (ETH_RMII_CLK_INPUT)
MAC will get RMII clock from outside. Note that ESP32 only supports GPIO0 to input the
RMII clock.
• Output RMII clock from internal (ETH_RMII_CLK_OUTPUT)
ESP32 can generate RMII clock by internal APLL. This clock can be routed to the external
PHY device. ESP32 supports to route the RMII clock to GPIO0/16/17.
CONFIG_ETH_RMII_CLK_OUTPUT_GPIO0
Output RMII clock from GPIO0 (Experimental!)
GPIO0 can be set to output a pre-divided PLL clock (test only!). Enabling this option will configure
GPIO0 to output a 50MHz clock. In fact this clock doesn t have directly relationship with EMAC
peripheral. Sometimes this clock won t work well with your PHY chip. You might need to add some
extra devices after GPIO0 (e.g. inverter). Note that outputting RMII clock on GPIO0 is an experimental
practice. If you want the Ethernet to work with WiFi, don t select GPIO0 output mode for stability.
Default value:
• No (disabled) if ETH_RMII_CLK_OUTPUT && CONFIG_ETH_USE_ESP32_EMAC
CONFIG_ETH_RMII_CLK_OUT_GPIO
RMII clock GPIO number
Set the GPIO number to output RMII Clock.
Range:
• from 16 to 17 if CONFIG_ETH_RMII_CLK_OUTPUT_GPIO0 &&
ETH_RMII_CLK_OUTPUT && CONFIG_ETH_USE_ESP32_EMAC
Default value:
• 17 if CONFIG_ETH_RMII_CLK_OUTPUT_GPIO0 && ETH_RMII_CLK_OUTPUT &&
CONFIG_ETH_USE_ESP32_EMAC
CONFIG_ETH_DMA_BUFFER_SIZE
Ethernet DMA buffer size (Byte)
Set the size of each buffer used by Ethernet MAC DMA.

Range:
• from 256 to 1600
Default value:
• 512
CONFIG_ETH_DMA_RX_BUFFER_NUM
Amount of Ethernet DMA Rx buffers
Number of DMA receive buffers. Each buffer s size is ETH_DMA_BUFFER_SIZE. Larger number
of buffers could increase throughput somehow.
Range:
• from 3 to 30
Default value:
• 10
CONFIG_ETH_DMA_TX_BUFFER_NUM
Amount of Ethernet DMA Tx buffers
Number of DMA transmit buffers. Each buffer s size is ETH_DMA_BUFFER_SIZE. Larger number
of buffers could increase throughput somehow.
Range:
• from 3 to 30
Default value:
• 10
CONFIG_ETH_SOFT_FLOW_CONTROL
Enable software flow control
Ethernet MAC engine on ESP32 doesn t feature a flow control logic. The MAC driver can perform
a software flow control if you enable this option. Note that, if the RX buffer number is small, enabling
software flow control will cause obvious performance loss.
Default value:
• No (disabled) if CONFIG_ETH_DMA_RX_BUFFER_NUM > 15 && CON-
FIG_ETH_USE_ESP32_EMAC
CONFIG_ETH_USE_SPI_ETHERNET
Support SPI to Ethernet Module
ESP-IDF can also support some SPI-Ethernet modules.
Default value:
• Yes (enabled)
Contains:
• CONFIG_ETH_SPI_ETHERNET_DM9051
• CONFIG_ETH_SPI_ETHERNET_KSZ8851SNL
• CONFIG_ETH_SPI_ETHERNET_W5500

CONFIG_ETH_SPI_ETHERNET_DM9051
Use DM9051
Found in: Component config > Ethernet > CONFIG_ETH_USE_SPI_ETHERNET
DM9051 is a fast Ethernet controller with an SPI interface. It s also integrated with a 10/100M PHY
and MAC. Select this to enable DM9051 driver.
CONFIG_ETH_SPI_ETHERNET_W5500
Use W5500 (MAC RAW)
W5500 is a HW TCP/IP embedded Ethernet controller. TCP/IP stack, 10/100 Ethernet MAC and
PHY are embedded in a single chip. However the driver in ESP-IDF only enables the RAW MAC
mode, making it compatible with the software TCP/IP stack. Say yes to enable W5500 driver.
CONFIG_ETH_SPI_ETHERNET_KSZ8851SNL
Use KSZ8851SNL
The KSZ8851SNL is a single-chip Fast Ethernet controller consisting of a 10/100 physical layer
transceiver (PHY), a MAC, and a Serial Peripheral Interface (SPI). Select this to enable KSZ8851SNL
driver.
CONFIG_ETH_USE_OPENETH
Support OpenCores Ethernet MAC (for use with QEMU)
OpenCores Ethernet MAC driver can be used when an ESP-IDF application is executed in QEMU. This
driver is not supported when running on a real chip.
Default value:
• No (disabled)
Contains:
• CONFIG_ETH_OPENETH_DMA_RX_BUFFER_NUM
• CONFIG_ETH_OPENETH_DMA_TX_BUFFER_NUM
CONFIG_ETH_OPENETH_DMA_RX_BUFFER_NUM
Number of Ethernet DMA Rx buffers
Found in: Component config > Ethernet > CONFIG_ETH_USE_OPENETH
Number of DMA receive buffers, each buffer is 1600 bytes.
Range:
• from 1 to 64 if CONFIG_ETH_USE_OPENETH
Default value:
• 4 if CONFIG_ETH_USE_OPENETH

CONFIG_ETH_OPENETH_DMA_TX_BUFFER_NUM
Number of Ethernet DMA Tx buffers
Found in: Component config > Ethernet > CONFIG_ETH_USE_OPENETH
Number of DMA transmit buffers, each buffer is 1600 bytes.
Range:
• from 1 to 64 if CONFIG_ETH_USE_OPENETH
Default value:
• 1 if CONFIG_ETH_USE_OPENETH
Event Loop Library Contains:

• CONFIG_ESP_EVENT_LOOP_PROFILING
• CONFIG_ESP_EVENT_POST_FROM_ISR
CONFIG_ESP_EVENT_LOOP_PROFILING
Enable event loop profiling
Found in: Component config > Event Loop Library
Enables collections of statistics in the event loop library such as the number of events posted to/recieved
by an event loop, number of callbacks involved, number of events dropped to to a full event loop queue,
run time of event handlers, and number of times/run time of each event handler.
Default value:
• No (disabled)
CONFIG_ESP_EVENT_POST_FROM_ISR
Support posting events from ISRs
Found in: Component config > Event Loop Library
Enable posting events from interrupt handlers.
Default value:
• Yes (enabled)
CONFIG_ESP_EVENT_POST_FROM_IRAM_ISR
Support posting events from ISRs placed in IRAM
Found in: Component config > Event Loop Library > CONFIG_ESP_EVENT_POST_FROM_ISR
Enable posting events from interrupt handlers placed in IRAM. Enabling this option places API functions
esp_event_post and esp_event_post_to in IRAM.
Default value:
• Yes (enabled)
GDB Stub Contains:

• CONFIG_ESP_GDBSTUB_SUPPORT_TASKS

CONFIG_ESP_GDBSTUB_SUPPORT_TASKS
Enable listing FreeRTOS tasks through GDB Stub
Found in: Component config > GDB Stub
If enabled, GDBStub can supply the list of FreeRTOS tasks to GDB. Thread list can be queried from
GDB using info threads command. Note that if GDB task lists were corrupted, this feature may not
work. If GDBStub fails, try disabling this feature.
CONFIG_ESP_GDBSTUB_MAX_TASKS
Maximum number of tasks supported by GDB Stub
Found in: Component config > GDB Stub > CONFIG_ESP_GDBSTUB_SUPPORT_TASKS
Set the number of tasks which GDB Stub will support.
Default value:
• 32 if CONFIG_ESP_GDBSTUB_SUPPORT_TASKS
ESP HTTP client Contains:

• CONFIG_ESP_HTTP_CLIENT_ENABLE_BASIC_AUTH
• CONFIG_ESP_HTTP_CLIENT_ENABLE_DIGEST_AUTH
• CONFIG_ESP_HTTP_CLIENT_ENABLE_HTTPS
CONFIG_ESP_HTTP_CLIENT_ENABLE_HTTPS
Enable https
Found in: Component config > ESP HTTP client
This option will enable https protocol by linking esp-tls library and initializing SSL transport
Default value:
• Yes (enabled)
CONFIG_ESP_HTTP_CLIENT_ENABLE_BASIC_AUTH
Enable HTTP Basic Authentication
This option will enable HTTP Basic Authentication. It is disabled by default as Basic auth uses unen-
crypted encoding, so it introduces a vulnerability when not using TLS
Default value:
• No (disabled)
CONFIG_ESP_HTTP_CLIENT_ENABLE_DIGEST_AUTH
Enable HTTP Digest Authentication
This option will enable HTTP Digest Authentication. It is enabled by default, but use of this configuration
is not recommended as the password can be derived from the exchange, so it introduces a vulnerability
when not using TLS
Default value:
• No (disabled)

HTTP Server Contains:

• CONFIG_HTTPD_PURGE_BUF_LEN
• CONFIG_HTTPD_LOG_PURGE_DATA
• CONFIG_HTTPD_MAX_REQ_HDR_LEN
• CONFIG_HTTPD_MAX_URI_LEN
• CONFIG_HTTPD_ERR_RESP_NO_DELAY
• CONFIG_HTTPD_WS_SUPPORT
CONFIG_HTTPD_MAX_REQ_HDR_LEN
Max HTTP Request Header Length
Found in: Component config > HTTP Server
This sets the maximum supported size of headers section in HTTP request packet to be processed by
the server
Default value:
• 512
CONFIG_HTTPD_MAX_URI_LEN
Max HTTP URI Length
This sets the maximum supported size of HTTP request URI to be processed by the server
Default value:
• 512
CONFIG_HTTPD_ERR_RESP_NO_DELAY
Use TCP_NODELAY socket option when sending HTTP error responses
Using TCP_NODEALY socket option ensures that HTTP error response reaches the client before the
underlying socket is closed. Please note that turning this off may cause multiple test failures
Default value:
• Yes (enabled)
CONFIG_HTTPD_PURGE_BUF_LEN
Length of temporary buffer for purging data
This sets the size of the temporary buffer used to receive and discard any remaining data that is received
from the HTTP client in the request, but not processed as part of the server HTTP request handler.
If the remaining data is larger than the available buffer size, the buffer will be filled in multiple iterations.
The buffer should be small enough to fit on the stack, but large enough to avoid excessive iterations.
Default value:
• 32

CONFIG_HTTPD_LOG_PURGE_DATA
Log purged content data at Debug level
Enabling this will log discarded binary HTTP request data at Debug level. For large content data this
may not be desirable as it will clutter the log.
Default value:
• No (disabled)
CONFIG_HTTPD_WS_SUPPORT
WebSocket server support
This sets the WebSocket server support.
Default value:
• No (disabled)
ESP HTTPS OTA Contains:

• CONFIG_OTA_ALLOW_HTTP
CONFIG_OTA_ALLOW_HTTP
Allow HTTP for OTA (WARNING: ONLY FOR TESTING PURPOSE, READ HELP)
Found in: Component config > ESP HTTPS OTA
It is highly recommended to keep HTTPS (along with server certificate validation) enabled. Enabling this
option comes with potential risk of: - Non-encrypted communication channel with server - Accepting
firmware upgrade image from server with fake identity
Default value:
• No (disabled)
ESP HTTPS server Contains:

• CONFIG_ESP_HTTPS_SERVER_ENABLE
CONFIG_ESP_HTTPS_SERVER_ENABLE
Enable ESP_HTTPS_SERVER component
Found in: Component config > ESP HTTPS server
Enable ESP HTTPS server component
Hardware Settings Contains:

• MAC Config
• Sleep Config
MAC Config Contains:

• CONFIG_ESP32_UNIVERSAL_MAC_ADDRESSES

CONFIG_ESP32_UNIVERSAL_MAC_ADDRESSES
Number of universally administered (by IEEE) MAC address
Found in: Component config > Hardware Settings > MAC Config
Configure the number of universally administered (by IEEE) MAC addresses. During initialization,
MAC addresses for each network interface are generated or derived from a single base MAC address.
If the number of universal MAC addresses is four, all four interfaces (WiFi station, WiFi softap, Blue-
tooth and Ethernet) receive a universally administered MAC address. These are generated sequentially
by adding 0, 1, 2 and 3 (respectively) to the final octet of the base MAC address. If the number of
universal MAC addresses is two, only two interfaces (WiFi station and Bluetooth) receive a universally
administered MAC address. These are generated sequentially by adding 0 and 1 (respectively) to the
base MAC address. The remaining two interfaces (WiFi softap and Ethernet) receive local MAC ad-
dresses. These are derived from the universal WiFi station and Bluetooth MAC addresses, respectively.
When using the default (Espressif-assigned) base MAC address, either setting can be used. When us-
ing a custom universal MAC address range, the correct setting will depend on the allocation of MAC
addresses in this range (either 2 or 4 per device.)
Available options:
• Two (ESP32_UNIVERSAL_MAC_ADDRESSES_TWO)
• Four (ESP32_UNIVERSAL_MAC_ADDRESSES_FOUR)
Sleep Config Contains:

• CONFIG_ESP_SLEEP_FLASH_LEAKAGE_WORKAROUND
• CONFIG_ESP_SLEEP_GPIO_RESET_WORKAROUND
• CONFIG_ESP_SLEEP_POWER_DOWN_FLASH
• CONFIG_ESP_SLEEP_PSRAM_LEAKAGE_WORKAROUND
CONFIG_ESP_SLEEP_POWER_DOWN_FLASH
Power down flash in light sleep when there is no SPIRAM
Found in: Component config > Hardware Settings > Sleep Config
If enabled, chip will try to power down flash as part of esp_light_sleep_start(), which costs more time
when chip wakes up. Can only be enabled if there is no SPIRAM configured. This option will in fact
consider VDD_SDIO auto power value (ESP_PD_OPTION_AUTO) as OFF. Also, it is possible to
force a power domain to stay ON during light sleep by using esp_sleep_pd_config() function.
Default value:
• Yes (enabled)
CONFIG_ESP_SLEEP_GPIO_RESET_WORKAROUND
light sleep GPIO reset workaround
esp32c3 and esp32s3 will reset at wake-up if GPIO is received a small electrostatic pulse during light
sleep, with specific condition
• GPIO needs to be configured as input-mode only
• The pin receives a small electrostatic pulse, and reset occurs when the pulse voltage is higher than
6V
For GPIO set to input mode only, it is not a good practice to leave it open/floating, The hardware design
needs to controlled it with determined supply or ground voltage is necessary.
This option provides a software workaround for this issue. Configure to isolate all GPIO pins in sleep
state.

CONFIG_ESP_SLEEP_PSRAM_LEAKAGE_WORKAROUND
PSRAM leakage current workaround in light sleep
When the CS pin of SPIRAM is not pulled up, the sleep current will increase during light sleep. If the
CS pin of SPIRAM has an external pull-up, you do not need to select this option, otherwise, you should
enable this option.
CONFIG_ESP_SLEEP_FLASH_LEAKAGE_WORKAROUND
Flash leakage current workaround in light sleep
When the CS pin of Flash is not pulled up, the sleep current will increase during light sleep. If the CS
pin of Flash has an external pull-up, you do not need to select this option, otherwise, you should enable
this option.
LCD and Touch Panel Contains:

• LCD Peripheral Configuration
LCD Peripheral Configuration Contains:

• CONFIG_LCD_PANEL_IO_FORMAT_BUF_SIZE
CONFIG_LCD_PANEL_IO_FORMAT_BUF_SIZE
LCD panel io format buffer size
Found in: Component config > LCD and Touch Panel > LCD Peripheral Configuration
LCD driver allocates an internal buffer to transform the data into a proper format, because of the endian
order mismatch. This option is to set the size of the buffer, in bytes.
Default value:
• 32
ESP NETIF Adapter Contains:

• CONFIG_ESP_NETIF_TCPIP_ADAPTER_COMPATIBLE_LAYER
• CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL
• CONFIG_ESP_NETIF_USE_TCPIP_STACK_LIB
CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL
IP Address lost timer interval (seconds)
Found in: Component config > ESP NETIF Adapter
The value of 0 indicates the IP lost timer is disabled, otherwise the timer is enabled.
The IP address may be lost because of some reasons, e.g. when the station disconnects from soft-AP,
or when DHCP IP renew fails etc. If the IP lost timer is enabled, it will be started everytime the IP is
lost. Event SYSTEM_EVENT_STA_LOST_IP will be raised if the timer expires. The IP lost timer is
stopped if the station get the IP again before the timer expires.
Range:
• from 0 to 65535
Default value:
• 120

CONFIG_ESP_NETIF_USE_TCPIP_STACK_LIB
TCP/IP Stack Library
Choose the TCP/IP Stack to work, for example, LwIP, uIP, etc.
Available options:
• LwIP (ESP_NETIF_TCPIP_LWIP)
lwIP is a small independent implementation of the TCP/IP protocol suite.
• Loopback (ESP_NETIF_LOOPBACK)
Dummy implementation of esp-netif functionality which connects driver transmit to receive
function. This option is for testing purpose only
CONFIG_ESP_NETIF_TCPIP_ADAPTER_COMPATIBLE_LAYER
Enable backward compatible tcpip_adapter interface
Backward compatible interface to tcpip_adapter is enabled by default to support legacy TCP/IP stack
initialisation code. Disable this option to use only esp-netif interface.
Default value:
• Yes (enabled)
PHY Contains:
• CONFIG_ESP_PHY_MAX_WIFI_TX_POWER
• CONFIG_ESP_PHY_REDUCE_TX_POWER
• CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE
• CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION
CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE
Store phy calibration data in NVS
Found in: Component config > PHY
If this option is enabled, NVS will be initialized and calibration data will be loaded from there. PHY
calibration will be skipped on deep sleep wakeup. If calibration data is not found, full calibration will
be performed and stored in NVS. Normally, only partial calibration will be performed. If this option is
disabled, full calibration will be performed.
If it s easy that your board calibrate bad data, choose n . Two cases for example, you should choose
n : 1.If your board is easy to be booted up with antenna disconnected. 2.Because of your board design,
each time when you do calibration, the result are too unstable. If unsure, choose y .
Default value:
• Yes (enabled)
CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION
Use a partition to store PHY init data
If enabled, PHY init data will be loaded from a partition. When using a custom partition table, make
sure that PHY data partition is included (type: data , subtype: phy ). With default partition tables,
this is done automatically. If PHY init data is stored in a partition, it has to be flashed there, otherwise
runtime error will occur.
If this option is not enabled, PHY init data will be embedded into the application binary.

If unsure, choose n .
Default value:
• No (disabled)
Contains:
• CONFIG_ESP_PHY_DEFAULT_INIT_IF_INVALID
• CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN
CONFIG_ESP_PHY_DEFAULT_INIT_IF_INVALID
Reset default PHY init data if invalid
Found in: Component config > PHY > CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION
If enabled, PHY init data will be restored to default if it cannot be verified successfully to avoid endless
bootloops.
If unsure, choose n .
Default value:
• No (disabled) if CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION
CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN
Support multiple PHY init data bin
Found in: Component config > PHY > CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION
If enabled, the corresponding PHY init data type can be automatically switched according to the country
code. China s PHY init data bin is used by default. Can be modified by country information in API
esp_wifi_set_country(). The priority of switching the PHY init data type is: 1. Country configured by
API esp_wifi_set_country() and the parameter policy is WIFI_COUNTRY_POLICY_MANUAL. 2.
Country notified by the connected AP. 3. Country configured by API esp_wifi_set_country() and the
parameter policy is WIFI_COUNTRY_POLICY_AUTO.
Default value:
• No (disabled) if CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION && CON-
FIG_ESP_PHY_INIT_DATA_IN_PARTITION
CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN_EMBED
Support embedded multiple phy init data bin to app bin
Found in: Component config > PHY > CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION > CON-
FIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN
If enabled, multiple phy init data bin will embedded into app bin If not enabled, multiple phy init data
bin will still leave alone, and need to be flashed by users.
Default value:
• No (disabled) if CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN && CON-
CONFIG_ESP_PHY_INIT_DATA_ERROR
Terminate operation when PHY init data error
Found in: Component config > PHY > CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION > CON-
FIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN
If enabled, when an error occurs while the PHY init data is updated, the program will terminate and
restart. If not enabled, the PHY init data will not be updated when an error occurs.

Default value:
• No (disabled) if CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN && CON-
CONFIG_ESP_PHY_MAX_WIFI_TX_POWER
Max WiFi TX power (dBm)
Set maximum transmit power for WiFi radio. Actual transmit power for high data rates may be lower
than this setting.
Range:
• from 10 to 20
Default value:
• 20
CONFIG_ESP_PHY_REDUCE_TX_POWER
Reduce PHY TX power when brownout reset
When brownout reset occurs, reduce PHY TX power to keep the code running.
Default value:
• Yes (enabled)
Power Management Contains:

• CONFIG_PM_SLP_DISABLE_GPIO
• CONFIG_PM_SLP_IRAM_OPT
• CONFIG_PM_RTOS_IDLE_OPT
• CONFIG_PM_ENABLE
CONFIG_PM_ENABLE
Support for power management
Found in: Component config > Power Management
If enabled, application is compiled with support for power management. This option has run-time over-
head (increased interrupt latency, longer time to enter idle state), and it also reduces accuracy of RTOS
ticks and timers used for timekeeping. Enable this option if application uses power management APIs.
Default value:
• No (disabled)
CONFIG_PM_DFS_INIT_AUTO
Enable dynamic frequency scaling (DFS) at startup
Found in: Component config > Power Management > CONFIG_PM_ENABLE
If enabled, startup code configures dynamic frequency scaling. Max CPU frequency is set to DE-
FAULT_CPU_FREQ_MHZ setting, min frequency is set to XTAL frequency. If disabled, DFS will
not be active until the application configures it using esp_pm_configure function.
Default value:
• No (disabled) if CONFIG_PM_ENABLE

CONFIG_PM_USE_RTC_TIMER_REF
Use RTC timer to prevent time drift (EXPERIMENTAL)
When APB clock frequency changes, high-resolution timer (esp_timer) scale and base value need to
be adjusted. Each adjustment may cause small error, and over time such small errors may cause time
drift. If this option is enabled, RTC timer will be used as a reference to compensate for the drift. It is
recommended that this option is only used if 32k XTAL is selected as RTC clock source.
Default value:
• No (disabled) if CONFIG_PM_ENABLE && ESP_TIMER_IMPL_FRC2
CONFIG_PM_PROFILING
Enable profiling counters for PM locks
If enabled, esp_pm_* functions will keep track of the amount of time each of the power management
locks has been held, and esp_pm_dump_locks function will print this information. This feature can be
used to analyze which locks are preventing the chip from going into a lower power state, and see what
time the chip spends in each power saving mode. This feature does incur some run-time overhead, so
should typically be disabled in production builds.
Default value:
CONFIG_PM_TRACE
Enable debug tracing of PM using GPIOs
If enabled, some GPIOs will be used to signal events such as RTOS ticks, frequency switching, entry/exit
from idle state. Refer to pm_trace.c file for the list of GPIOs. This feature is intended to be used when
analyzing/debugging behavior of power management implementation, and should be kept disabled in
applications.
Default value:
CONFIG_PM_SLP_IRAM_OPT
Put lightsleep related codes in internal RAM
If enabled, about 1.8KB of lightsleep related source code would be in IRAM and chip would sleep
longer for 760us at most each time. This feature is intended to be used when lower power consumption
is needed while there is enough place in IRAM to place source code.
CONFIG_PM_RTOS_IDLE_OPT
Put RTOS IDLE related codes in internal RAM
If enabled, about 260B of RTOS_IDLE related source code would be in IRAM and chip would sleep
longer for 40us at most each time. This feature is intended to be used when lower power consumption
is needed while there is enough place in IRAM to place source code.

CONFIG_PM_SLP_DISABLE_GPIO
Disable all GPIO when chip at sleep
This feature is intended to disable all GPIO pins at automantic sleep to get a lower power mode.
If enabled, chips will disable all GPIO pins at automantic sleep to reduce about 200~300 uA cur-
rent. If you want to specifically use some pins normally as chip wakes when chip sleeps, you
can call gpio_sleep_sel_dis to disable this feature on those pins. You can also keep this fea-
ture on and call gpio_sleep_set_direction and gpio_sleep_set_pull_mode to have a different
GPIO configuration at sleep. Waring: If you want to enable this option on ESP32, you should en-
able GPIO_ESP32_SUPPORT_SWITCH_SLP_PULL at first, otherwise you will not be able to switch
pullup/pulldown mode.
ESP System Settings Contains:

• CONFIG_ESP_SYSTEM_RTC_EXT_XTAL_BOOTSTRAP_CYCLES
• CONFIG_ESP_CONSOLE_UART
• CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP
• CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE
• CONFIG_ESP_TASK_WDT
• CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL
• CONFIG_ESP_INT_WDT
• CONFIG_ESP_MAIN_TASK_AFFINITY
• CONFIG_ESP_MAIN_TASK_STACK_SIZE
• Memory protection
• CONFIG_ESP_MINIMAL_SHARED_STACK_SIZE
• CONFIG_ESP_DEBUG_STUBS_ENABLE
• CONFIG_ESP_SYSTEM_PANIC
• CONFIG_ESP_PANIC_HANDLER_IRAM
• CONFIG_ESP_SYSTEM_EVENT_QUEUE_SIZE
• CONFIG_ESP_CONSOLE_UART_BAUDRATE
• CONFIG_ESP_CONSOLE_UART_NUM
• CONFIG_ESP_CONSOLE_UART_RX_GPIO
• CONFIG_ESP_CONSOLE_UART_TX_GPIO
CONFIG_ESP_SYSTEM_PANIC
Panic handler behaviour
Found in: Component config > ESP System Settings
If FreeRTOS detects unexpected behaviour or an unhandled exception, the panic handler is invoked.
Configure the panic handler s action here.
Available options:
• Print registers and halt (ESP_SYSTEM_PANIC_PRINT_HALT)
Outputs the relevant registers over the serial port and halt the processor. Needs a manual reset
to restart.
• Print registers and reboot (ESP_SYSTEM_PANIC_PRINT_REBOOT)
Outputs the relevant registers over the serial port and immediately reset the processor.
• Silent reboot (ESP_SYSTEM_PANIC_SILENT_REBOOT)
Just resets the processor without outputting anything
• GDBStub on panic (ESP_SYSTEM_PANIC_GDBSTUB)
Invoke gdbstub on the serial port, allowing for gdb to attach to it to do a postmortem of the
crash.
• GDBStub at runtime (ESP_SYSTEM_GDBSTUB_RUNTIME)
Invoke gdbstub on the serial port, allowing for gdb to attach to it and to do a debug on runtime.
This feature will switch system to single core mode.

CONFIG_ESP_SYSTEM_RTC_EXT_XTAL_BOOTSTRAP_CYCLES
Bootstrap cycles for external 32kHz crystal
To reduce the startup time of an external RTC crystal, we bootstrap it with a 32kHz square wave for a
fixed number of cycles. Setting 0 will disable bootstrapping (if disabled, the crystal may take longer to
start up or fail to oscillate under some conditions).
If this value is too high, a faulty crystal may initially start and then fail. If this value is too low, an
otherwise good crystal may not start.
To accurately determine if the crystal has started, set a larger Number of cycles for RTC_SLOW_CLK
calibration (about 3000).
CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP
Enable RTC fast memory for dynamic allocations
This config option allows to add RTC fast memory region to system heap with capability similar to that
of DRAM region but without DMA. This memory will be consumed first per heap initialization order
by early startup services and scheduler related code. Speed wise RTC fast memory operates on APB
clock and hence does not have much performance impact.
Memory protection Contains:

• CONFIG_ESP_SYSTEM_MEMPROT_FEATURE
CONFIG_ESP_SYSTEM_MEMPROT_FEATURE
Enable memory protection
Found in: Component config > ESP System Settings > Memory protection
If enabled, the permission control module watches all the memory access and fires the panic handler
if a permission violation is detected. This feature automatically splits the SRAM memory into data
and instruction segments and sets Read/Execute permissions for the instruction part (below given split-
ting address) and Read/Write permissions for the data part (above the splitting address). The memory
protection is effective on all access through the IRAM0 and DRAM0 buses.
CONFIG_ESP_SYSTEM_MEMPROT_FEATURE_LOCK
Lock memory protection settings
Found in: Component config > ESP System Settings > Memory protection > CON-
FIG_ESP_SYSTEM_MEMPROT_FEATURE
Once locked, memory protection settings cannot be changed anymore. The lock is reset only on the chip
startup.
Default value:
• Yes (enabled) if CONFIG_ESP_SYSTEM_MEMPROT_FEATURE
CONFIG_ESP_SYSTEM_EVENT_QUEUE_SIZE
System event queue size
Config system event queue size in different application.
Default value:

• 32
CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE
Event loop task stack size
Config system event task stack size in different application.
Default value:
• 2304
CONFIG_ESP_MAIN_TASK_STACK_SIZE
Main task stack size
Configure the main task stack size. This is the stack of the task which calls app_main(). If app_main()
returns then this task is deleted and its stack memory is freed.
Default value:
• 3584
CONFIG_ESP_MAIN_TASK_AFFINITY
Main task core affinity
Configure the main task core affinity. This is the used core of the task which calls app_main(). If
app_main() returns then this task is deleted.
Available options:
• CPU0 (ESP_MAIN_TASK_AFFINITY_CPU0)
• CPU1 (ESP_MAIN_TASK_AFFINITY_CPU1)
• No affinity (ESP_MAIN_TASK_AFFINITY_NO_AFFINITY)
CONFIG_ESP_MINIMAL_SHARED_STACK_SIZE
Minimal allowed size for shared stack
Minimal value of size, in bytes, accepted to execute a expression with shared stack.
Default value:
• 2048
CONFIG_ESP_CONSOLE_UART
Channel for console output
Select where to send console output (through stdout and stderr).
• Default is to use UART0 on pre-defined GPIOs.
• If Custom is selected, UART0 or UART1 can be chosen, and any pins can be selected.
• If None is selected, there will be no console output on any UART, except for initial output
from ROM bootloader. This ROM output can be suppressed by GPIO strapping or EFUSE, refer
to chip datasheet for details.
• On chips with USB OTG peripheral, USB CDC option redirects output to the CDC port. This
option uses the CDC driver in the chip ROM. This option is incompatible with TinyUSB stack.

• On chips with an USB serial/JTAG debug controller, selecting the option for that redirects output
to the CDC/ACM (serial port emulation) component of that device.
Available options:
• Default: UART0 (ESP_CONSOLE_UART_DEFAULT)
• USB CDC (ESP_CONSOLE_USB_CDC)
• USB Serial/JTAG Controller (ESP_CONSOLE_USB_SERIAL_JTAG)
• Custom UART (ESP_CONSOLE_UART_CUSTOM)
• None (ESP_CONSOLE_NONE)
CONFIG_ESP_CONSOLE_UART_NUM
UART peripheral to use for console output (0-1)
This UART peripheral is used for console output from the ESP-IDF Bootloader and the app.
If the configuration is different in the Bootloader binary compared to the app binary, UART is recon-
figured after the bootloader exits and the app starts.
Due to an ESP32 ROM bug, UART2 is not supported for console output via esp_rom_printf.
Available options:
• UART0 (ESP_CONSOLE_UART_CUSTOM_NUM_0)
• UART1 (ESP_CONSOLE_UART_CUSTOM_NUM_1)
CONFIG_ESP_CONSOLE_UART_TX_GPIO
UART TX on GPIO#
This GPIO is used for console UART TX output in the ESP-IDF Bootloader and the app (including boot
log output and default standard output and standard error of the app).
Range:
• from 0 to 46 if ESP_CONSOLE_UART_CUSTOM
Default value:
• 1 if ESP_CONSOLE_UART_CUSTOM
CONFIG_ESP_CONSOLE_UART_RX_GPIO
UART RX on GPIO#
This GPIO is used for UART RX input in the ESP-IDF Bootloader and the app (including default default
standard input of the app).
Note: The default ESP-IDF Bootloader configures this pin but doesn t read anything from the UART.
Range:
• from 0 to 46 if ESP_CONSOLE_UART_CUSTOM
Default value:

CONFIG_ESP_CONSOLE_UART_BAUDRATE
UART console baud rate
This baud rate is used by both the ESP-IDF Bootloader and the app (including boot log output and
default standard input/output/error of the app).
The app s maximum baud rate depends on the UART clock source. If Power Management is disabled,
the UART clock source is the APB clock and all baud rates in the available range will be sufficiently
accurate. If Power Management is enabled, REF_TICK clock source is used so the baud rate is divided
from 1MHz. Baud rates above 1Mbps are not possible and values between 500Kbps and 1Mbps may
not be accurate.
Range:
• from 1200 to 4000000 if CONFIG_PM_ENABLE
• from 1200 to 1000000 if CONFIG_PM_ENABLE
Default value:
• 115200
CONFIG_ESP_INT_WDT
Interrupt watchdog
This watchdog timer can detect if the FreeRTOS tick interrupt has not been called for a certain time,
either because a task turned off interrupts and did not turn them on for a long time, or because an
interrupt handler did not return. It will try to invoke the panic handler first and failing that reset the SoC.
Default value:
• Yes (enabled)
CONFIG_ESP_INT_WDT_TIMEOUT_MS
Interrupt watchdog timeout (ms)
Found in: Component config > ESP System Settings > CONFIG_ESP_INT_WDT
The timeout of the watchdog, in miliseconds. Make this higher than the FreeRTOS tick rate.
Range:
• from 10 to 10000
Default value:
• 300 if CONFIG_ESP32_SPIRAM_SUPPORT && CONFIG_ESP_INT_WDT
• 800 if CONFIG_ESP32_SPIRAM_SUPPORT && CONFIG_ESP_INT_WDT
CONFIG_ESP_INT_WDT_CHECK_CPU1
Also watch CPU1 tick interrupt
Found in: Component config > ESP System Settings > CONFIG_ESP_INT_WDT
Also detect if interrupts on CPU 1 are disabled for too long.
Default value:
• Yes (enabled) if CONFIG_ESP_INT_WDT && CONFIG_FREERTOS_UNICORE

CONFIG_ESP_TASK_WDT
Initialize Task Watchdog Timer on startup
The Task Watchdog Timer can be used to make sure individual tasks are still running. Enabling this
option will cause the Task Watchdog Timer to be initialized automatically at startup. The Task Watchdog
timer can be initialized after startup as well (see Task Watchdog Timer API Reference)
Default value:
• Yes (enabled)
CONFIG_ESP_TASK_WDT_PANIC
Invoke panic handler on Task Watchdog timeout
Found in: Component config > ESP System Settings > CONFIG_ESP_TASK_WDT
If this option is enabled, the Task Watchdog Timer will be configured to trigger the panic handler when
it times out. This can also be configured at run time (see Task Watchdog Timer API Reference)
Default value:
• No (disabled)
CONFIG_ESP_TASK_WDT_TIMEOUT_S
Task Watchdog timeout period (seconds)
Timeout period configuration for the Task Watchdog Timer in seconds. This is also configurable at run
time (see Task Watchdog Timer API Reference)
Range:
• from 1 to 60
Default value:
• 5
CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0
Watch CPU0 Idle Task
If this option is enabled, the Task Watchdog Timer will watch the CPU0 Idle Task. Having the Task
Watchdog watch the Idle Task allows for detection of CPU starvation as the Idle Task not being called is
usually a symptom of CPU starvation. Starvation of the Idle Task is detrimental as FreeRTOS household
tasks depend on the Idle Task getting some runtime every now and then.
Default value:
• Yes (enabled)
CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1
Watch CPU1 Idle Task
If this option is enabled, the Task Wtachdog Timer will wach the CPU1 Idle Task.
Default value:
• Yes (enabled) if CONFIG_ESP_TASK_WDT && CONFIG_FREERTOS_UNICORE

CONFIG_ESP_PANIC_HANDLER_IRAM
Place panic handler code in IRAM
If this option is disabled (default), the panic handler code is placed in flash not IRAM. This means that
if ESP-IDF crashes while flash cache is disabled, the panic handler will automatically re-enable flash
cache before running GDB Stub or Core Dump. This adds some minor risk, if the flash cache status is
also corrupted during the crash.
If this option is enabled, the panic handler code (including required UART functions) is placed in IRAM.
This may be necessary to debug some complex issues with crashes while flash cache is disabled (for
example, when writing to SPI flash) or when flash cache is corrupted when an exception is triggered.
Default value:
• No (disabled)
CONFIG_ESP_DEBUG_STUBS_ENABLE
OpenOCD debug stubs
Debug stubs are used by OpenOCD to execute pre-compiled onboard code which does some useful
debugging stuff, e.g. GCOV data dump.
Default value:
• COMPILER_OPTIMIZATION_LEVEL_DEBUG if CONFIG_ESP32_TRAX &&
ESP32S2_TRAX && ESP32S3_TRAX
CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL
Interrupt level to use for Interrupt Watchdog and other system checks
Interrupt level to use for Interrupt Watchdog and other system checks.
Available options:
• Level 5 interrupt (ESP_SYSTEM_CHECK_INT_LEVEL_5)
Using level 5 interrupt for Interrupt Watchdog and other system checks.
• Level 4 interrupt (ESP_SYSTEM_CHECK_INT_LEVEL_4)
Using level 4 interrupt for Interrupt Watchdog and other system checks.
IPC (Inter-Processor Call) Contains:

• CONFIG_ESP_IPC_TASK_STACK_SIZE
• CONFIG_ESP_IPC_USES_CALLERS_PRIORITY
CONFIG_ESP_IPC_TASK_STACK_SIZE
Inter-Processor Call (IPC) task stack size
Found in: Component config > IPC (Inter-Processor Call)
Configure the IPC tasks stack size. An IPC task runs on each core (in dual core mode), and allows for
cross-core function calls. See IPC documentation for more details. The default IPC stack size should be
enough for most common simple use cases. However, users can increase/decrease the stack size to their
needs.
Range:
• from 512 to 65536
Default value:

• 1024
CONFIG_ESP_IPC_USES_CALLERS_PRIORITY
IPC runs at caller s priority
Found in: Component config > IPC (Inter-Processor Call)
If this option is not enabled then the IPC task will keep behavior same as prior to that of ESP-IDF v4.0,
hence IPC task will run at (configMAX_PRIORITIES - 1) priority.
Default value:
• Yes (enabled) if CONFIG_FREERTOS_UNICORE
High resolution timer (esp_timer) Contains:

• CONFIG_ESP_TIMER_PROFILING
• CONFIG_ESP_TIMER_IMPL
• CONFIG_ESP_TIMER_TASK_STACK_SIZE
• CONFIG_ESP_TIMER_INTERRUPT_LEVEL
• CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD
CONFIG_ESP_TIMER_PROFILING
Enable esp_timer profiling features
Found in: Component config > High resolution timer (esp_timer)
If enabled, esp_timer_dump will dump information such as number of times the timer was started,
number of times the timer has triggered, and the total time it took for the callback to run. This option
has some effect on timer performance and the amount of memory used for timer storage, and should
only be used for debugging/testing purposes.
Default value:
• No (disabled)
CONFIG_ESP_TIMER_TASK_STACK_SIZE
High-resolution timer task stack size
Configure the stack size of timer_task task. This task is used to dispatch callbacks of timers created
using ets_timer and esp_timer APIs. If you are seing stack overflow errors in timer task, increase this
value.
Note that this is not the same as FreeRTOS timer task. To configure FreeRTOS timer task size, see
FreeRTOS timer task stack size option in FreeRTOS menu.
Range:
• from 2048 to 65536
Default value:
• 3584
CONFIG_ESP_TIMER_INTERRUPT_LEVEL
Interrupt level
It sets the interrupt level for esp_timer ISR in range 1..3. A higher level (3) helps to decrease the ISR
esp_timer latency.
Range:

• from 1 to 3
• from 1 to 1
Default value:
• 1
CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD
Support ISR dispatch method
Allows using ESP_TIMER_ISR dispatch method (ESP_TIMER_TASK dispatch method is also aval-
ible). - ESP_TIMER_TASK - Timer callbacks are dispatched from a high-priority esp_timer task. -
ESP_TIMER_ISR - Timer callbacks are dispatched directly from the timer interrupt handler. The ISR
dispatch can be used, in some cases, when a callback is very simple or need a lower-latency.
Default value:
• No (disabled)
CONFIG_ESP_TIMER_IMPL
Hardware timer to use for esp_timer
esp_timer APIs can be implemented using different hardware timers.
• FRC2 (legacy) implementation has been used in ESP-IDF v2.x - v4.1.
• LAC timer of Timer Group 0 implementation is simpler, and has smaller run time overhead
because software handling of timer overflow is not needed.
• SYSTIMER implementation is similar to LAC timer of Timer Group 0 but for non ESP32
chips.
Available options:
• FRC2 (legacy) timer (ESP_TIMER_IMPL_FRC2)
• LAC timer of Timer Group 0 (ESP_TIMER_IMPL_TG0_LAC)
• SYSTIMER (ESP_TIMER_IMPL_SYSTIMER)
Wi-Fi Contains:
• CONFIG_ESP32_WIFI_ENABLE_WPA3_SAE
• CONFIG_ESP32_WIFI_SOFTAP_BEACON_MAX_LEN
• CONFIG_ESP32_WIFI_CACHE_TX_BUFFER_NUM
• CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM
• CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM
• CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM
• CONFIG_ESP32_WIFI_STATIC_TX_BUFFER_NUM
• CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE
• CONFIG_ESP32_WIFI_SW_COEXIST_ENABLE
• CONFIG_ESP32_WIFI_TX_BUFFER
• CONFIG_ESP32_WIFI_AMPDU_RX_ENABLED
• CONFIG_ESP32_WIFI_AMPDU_TX_ENABLED
• CONFIG_ESP32_WIFI_AMSDU_TX_ENABLED
• CONFIG_ESP32_WIFI_CSI_ENABLED
• CONFIG_ESP_WIFI_GMAC_SUPPORT
• CONFIG_ESP32_WIFI_IRAM_OPT
• CONFIG_ESP32_WIFI_MGMT_SBUF_NUM
• CONFIG_ESP32_WIFI_NVS_ENABLED
• CONFIG_ESP32_WIFI_RX_IRAM_OPT
• CONFIG_ESP_WIFI_SLP_IRAM_OPT
• CONFIG_ESP_WIFI_SOFTAP_SUPPORT

• CONFIG_ESP32_WIFI_TASK_CORE_ID
CONFIG_ESP32_WIFI_SW_COEXIST_ENABLE
Software controls WiFi/Bluetooth coexistence
Found in: Component config > Wi-Fi
If enabled, WiFi & Bluetooth coexistence is controlled by software rather than hardware. Recommended
for heavy traffic scenarios. Both coexistence configuration options are automatically managed, no user
intervention is required. If only Bluetooth is used, it is recommended to disable this option to reduce
binary file size.
Default value:
• Yes (enabled) if CONFIG_BT_ENABLED
CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM
Max number of WiFi static RX buffers
Set the number of WiFi static RX buffers. Each buffer takes approximately 1.6KB of RAM. The static
rx buffers are allocated when esp_wifi_init is called, they are not freed until esp_wifi_deinit is called.
WiFi hardware use these buffers to receive all 802.11 frames. A higher number may allow higher
throughput but increases memory use. If ESP32_WIFI_AMPDU_RX_ENABLED is enabled, this
value is recommended to set equal or bigger than ESP32_WIFI_RX_BA_WIN in order to achieve better
throughput and compatibility with both stations and APs.
Range:
• from 2 to 25
Default value:
• 10 if CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP
• 16 if CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP
CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM
Max number of WiFi dynamic RX buffers
Set the number of WiFi dynamic RX buffers, 0 means unlimited RX buffers will be allocated (provided
sufficient free RAM). The size of each dynamic RX buffer depends on the size of the received data
frame.
For each received data frame, the WiFi driver makes a copy to an RX buffer and then delivers it to the
high layer TCP/IP stack. The dynamic RX buffer is freed after the higher layer has successfully received
the data frame.
For some applications, WiFi data frames may be received faster than the application can process them.
In these cases we may run out of memory if RX buffer number is unlimited (0).
If a dynamic RX buffer limit is set, it should be at least the number of static RX buffers.
Range:
• from 0 to 128 if CONFIG_LWIP_WND_SCALE
Default value:
• 32

CONFIG_ESP32_WIFI_TX_BUFFER
Type of WiFi TX buffers
Select type of WiFi TX buffers:
If Static is selected, WiFi TX buffers are allocated when WiFi is initialized and released when WiFi
is de-initialized. The size of each static TX buffer is fixed to about 1.6KB.
If Dynamic is selected, each WiFi TX buffer is allocated as needed when a data frame is delivered
to the Wifi driver from the TCP/IP stack. The buffer is freed after the data frame has been sent by the
WiFi driver. The size of each dynamic TX buffer depends on the length of each data frame sent by the
TCP/IP layer.
If PSRAM is enabled, Static should be selected to guarantee enough WiFi TX buffers. If PSRAM
is disabled, Dynamic should be selected to improve the utilization of RAM.
Available options:
• Static (ESP32_WIFI_STATIC_TX_BUFFER)
• Dynamic (ESP32_WIFI_DYNAMIC_TX_BUFFER)
CONFIG_ESP32_WIFI_STATIC_TX_BUFFER_NUM
Max number of WiFi static TX buffers
Set the number of WiFi static TX buffers. Each buffer takes approximately 1.6KB of RAM. The static
RX buffers are allocated when esp_wifi_init() is called, they are not released until esp_wifi_deinit() is
called.
For each transmitted data frame from the higher layer TCP/IP stack, the WiFi driver makes a copy of
it in a TX buffer. For some applications especially UDP applications, the upper layer can deliver frames
faster than WiFi layer can transmit. In these cases, we may run out of TX buffers.
Range:
• from 1 to 64 if ESP32_WIFI_STATIC_TX_BUFFER
Default value:
• 16 if ESP32_WIFI_STATIC_TX_BUFFER
CONFIG_ESP32_WIFI_CACHE_TX_BUFFER_NUM
Max number of WiFi cache TX buffers
Set the number of WiFi cache TX buffer number.
For each TX packet from uplayer, such as LWIP etc, WiFi driver needs to allocate a static TX buffer
and makes a copy of uplayer packet. If WiFi driver fails to allocate the static TX buffer, it caches the
uplayer packets to a dedicated buffer queue, this option is used to configure the size of the cached TX
queue.
Range:
• from 16 to 128 if CONFIG_ESP32_SPIRAM_SUPPORT || ESP32S2_SPIRAM_SUPPORT ||
ESP32S3_SPIRAM_SUPPORT
Default value:
• 32 if CONFIG_ESP32_SPIRAM_SUPPORT || ESP32S2_SPIRAM_SUPPORT ||

CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM
Max number of WiFi dynamic TX buffers
Set the number of WiFi dynamic TX buffers. The size of each dynamic TX buffer is not fixed, it depends
on the size of each transmitted data frame.
For each transmitted frame from the higher layer TCP/IP stack, the WiFi driver makes a copy of it in a
TX buffer. For some applications, especially UDP applications, the upper layer can deliver frames faster
than WiFi layer can transmit. In these cases, we may run out of TX buffers.
Range:
• from 1 to 128
Default value:
• 32
CONFIG_ESP32_WIFI_CSI_ENABLED
WiFi CSI(Channel State Information)
Select this option to enable CSI(Channel State Information) feature. CSI takes about CON-
FIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM KB of RAM. If CSI is not used, it is better to dis-
able this feature in order to save memory.
Default value:
• No (disabled)
CONFIG_ESP32_WIFI_AMPDU_TX_ENABLED
WiFi AMPDU TX
Select this option to enable AMPDU TX feature
Default value:
• Yes (enabled)
CONFIG_ESP32_WIFI_TX_BA_WIN
WiFi AMPDU TX BA window size
Found in: Component config > Wi-Fi > CONFIG_ESP32_WIFI_AMPDU_TX_ENABLED
Set the size of WiFi Block Ack TX window. Generally a bigger value means higher throughput but
more memory. Most of time we should NOT change the default value unless special reason, e.g. test
the maximum UDP TX throughput with iperf etc. For iperf test in shieldbox, the recommended value
is 9~12.
Range:
• from 2 to 32
Default value:
• 6
CONFIG_ESP32_WIFI_AMPDU_RX_ENABLED
WiFi AMPDU RX
Select this option to enable AMPDU RX feature

Default value:
• Yes (enabled)
CONFIG_ESP32_WIFI_RX_BA_WIN
WiFi AMPDU RX BA window size
Found in: Component config > Wi-Fi > CONFIG_ESP32_WIFI_AMPDU_RX_ENABLED
Set the size of WiFi Block Ack RX window. Generally a bigger value means higher throughput and
better compatibility but more memory. Most of time we should NOT change the default value unless
special reason, e.g. test the maximum UDP RX throughput with iperf etc. For iperf test in shieldbox,
the recommended value is 9~12. If PSRAM is used and WiFi memory is prefered to allocat in PSRAM
first, the default and minimum value should be 16 to achieve better throughput and compatibility with
both stations and APs.
Range:
• from 2 to 32
Default value:
• 6 if CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP && CON-
FIG_ESP32_WIFI_AMPDU_RX_ENABLED
• 16 if CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP && CON-
FIG_ESP32_WIFI_AMPDU_RX_ENABLED
CONFIG_ESP32_WIFI_AMSDU_TX_ENABLED
WiFi AMSDU TX
Select this option to enable AMSDU TX feature
Default value:
• No (disabled) if CONFIG_ESP32_SPIRAM_SUPPORT || ESP32S2_SPIRAM_SUPPORT ||
CONFIG_ESP32_WIFI_NVS_ENABLED
WiFi NVS flash
Select this option to enable WiFi NVS flash
Default value:
• Yes (enabled)
CONFIG_ESP32_WIFI_TASK_CORE_ID
WiFi Task Core ID
Pinned WiFi task to core 0 or core 1.
Available options:
• Core 0 (ESP32_WIFI_TASK_PINNED_TO_CORE_0)
• Core 1 (ESP32_WIFI_TASK_PINNED_TO_CORE_1)

CONFIG_ESP32_WIFI_SOFTAP_BEACON_MAX_LEN
Max length of WiFi SoftAP Beacon
ESP-MESH utilizes beacon frames to detect and resolve root node conflicts (see documentation). How-
ever the default length of a beacon frame can simultaneously hold only five root node identifier structures,
meaning that a root node conflict of up to five nodes can be detected at one time. In the occurence of
more root nodes conflict involving more than five root nodes, the conflict resolution process will detect
five of the root nodes, resolve the conflict, and re-detect more root nodes. This process will repeat until
all root node conflicts are resolved. However this process can generally take a very long time.
To counter this situation, the beacon frame length can be increased such that more root nodes can be
detected simultaneously. Each additional root node will require 36 bytes and should be added ontop
of the default beacon frame length of 752 bytes. For example, if you want to detect 10 root nodes
simultaneously, you need to set the beacon frame length as 932 (752+36*5).
Setting a longer beacon length also assists with debugging as the conflicting root nodes can be identified
more quickly.
Range:
• from 752 to 1256
Default value:
• 752
CONFIG_ESP32_WIFI_MGMT_SBUF_NUM
WiFi mgmt short buffer number
Set the number of WiFi management short buffer.
Range:
• from 6 to 32
Default value:
• 32
CONFIG_ESP32_WIFI_IRAM_OPT
WiFi IRAM speed optimization
Select this option to place frequently called Wi-Fi library functions in IRAM. When this option is dis-
abled, more than 10Kbytes of IRAM memory will be saved but Wi-Fi throughput will be reduced.
Default value:
• No (disabled) if CONFIG_BT_ENABLED && CONFIG_ESP32_SPIRAM_SUPPORT
• Yes (enabled)
CONFIG_ESP32_WIFI_RX_IRAM_OPT
WiFi RX IRAM speed optimization
Select this option to place frequently called Wi-Fi library RX functions in IRAM. When this option is
disabled, more than 17Kbytes of IRAM memory will be saved but Wi-Fi performance will be reduced.
Default value:
• No (disabled) if CONFIG_BT_ENABLED && CONFIG_ESP32_SPIRAM_SUPPORT
• Yes (enabled)

CONFIG_ESP32_WIFI_ENABLE_WPA3_SAE
Enable WPA3-Personal
Select this option to allow the device to establish a WPA3-Personal connection with eligible AP s.
PMF (Protected Management Frames) is a prerequisite feature for a WPA3 connection, it needs to be
explicitly configured before attempting connection. Please refer to the Wi-Fi Driver API Guide for
details.
Default value:
• Yes (enabled)
CONFIG_ESP_WIFI_SLP_IRAM_OPT
WiFi SLP IRAM speed optimization
Select this option to place called Wi-Fi library TBTT process and receive beacon functions
in IRAM. Some functions can be put in IRAM either by ESP32_WIFI_IRAM_OPT and
ESP32_WIFI_RX_IRAM_OPT, or this one. If already enabled ESP32_WIFI_IRAM_OPT,
the other 7.3KB IRAM memory would be taken by this option. If already enabled
ESP32_WIFI_RX_IRAM_OPT, the other 1.3KB IRAM memory would be taken by this option.
If neither of them are enabled, the other 7.4KB IRAM memory would be taken by this option. Wi-Fi
power-save mode average current would be reduced if this option is enabled.
CONFIG_ESP_WIFI_SLP_DEFAULT_MIN_ACTIVE_TIME
Minimum active time
Found in: Component config > Wi-Fi > CONFIG_ESP_WIFI_SLP_IRAM_OPT
The minimum timeout for waiting to receive data, unit: milliseconds.
Range:
• from 8 to 60 if CONFIG_ESP_WIFI_SLP_IRAM_OPT
Default value:
• 50 if CONFIG_ESP_WIFI_SLP_IRAM_OPT
CONFIG_ESP_WIFI_SLP_DEFAULT_MAX_ACTIVE_TIME
Maximum keep alive time
Found in: Component config > Wi-Fi > CONFIG_ESP_WIFI_SLP_IRAM_OPT
The maximum time that wifi keep alive, unit: seconds.
Range:
• from 10 to 60 if CONFIG_ESP_WIFI_SLP_IRAM_OPT
Default value:
• 10 if CONFIG_ESP_WIFI_SLP_IRAM_OPT
CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE
Power Management for station at disconnected
Select this option to enable power_management for station when disconnected. Chip will do modem-
sleep when rf module is not in use any more.

CONFIG_ESP_WIFI_GMAC_SUPPORT
WiFi GMAC Support(GMAC128 and GMAC256)
Select this option to enable GMAC support. GMAC support is compulsory for WiFi 192 bit certification.
Default value:
• No (disabled)
CONFIG_ESP_WIFI_SOFTAP_SUPPORT
WiFi SoftAP Support
WiFi module can be compiled without SoftAP to save code size.
Default value:
• Yes (enabled)
Core dump Contains:

• CONFIG_ESP_COREDUMP_CHECK_BOOT
• CONFIG_ESP_COREDUMP_DATA_FORMAT
• CONFIG_ESP_COREDUMP_CHECKSUM
• CONFIG_ESP_COREDUMP_TO_FLASH_OR_UART
• CONFIG_ESP_COREDUMP_UART_DELAY
• CONFIG_ESP_COREDUMP_DECODE
• CONFIG_ESP_COREDUMP_MAX_TASKS_NUM
CONFIG_ESP_COREDUMP_TO_FLASH_OR_UART
Data destination
Found in: Component config > Core dump
Select place to store core dump: flash, uart or none (to disable core dumps generation).
Core dumps to Flash are not available if PSRAM is used for task stacks.
If core dump is configured to be stored in flash and custom partition table is used add corresponding
entry to your CSV. For examples, please see predefined partition table CSV descriptions in the compo-
nents/partition_table directory.
Available options:
• Flash (ESP_COREDUMP_ENABLE_TO_FLASH)
• UART (ESP_COREDUMP_ENABLE_TO_UART)
• None (ESP_COREDUMP_ENABLE_TO_NONE)
CONFIG_ESP_COREDUMP_DATA_FORMAT
Core dump data format
Select the data format for core dump.
Available options:
• Binary format (ESP_COREDUMP_DATA_FORMAT_BIN)
• ELF format (ESP_COREDUMP_DATA_FORMAT_ELF)

CONFIG_ESP_COREDUMP_CHECKSUM
Core dump data integrity check
Select the integrity check for the core dump.
Available options:
• Use CRC32 for integrity verification (ESP_COREDUMP_CHECKSUM_CRC32)
• Use SHA256 for integrity verification (ESP_COREDUMP_CHECKSUM_SHA256)
CONFIG_ESP_COREDUMP_CHECK_BOOT
Check core dump data integrity on boot
When enabled, if any data are found on the flash core dump partition, they will be checked by calculating
their checksum.
Default value:
• Yes (enabled) if ESP_COREDUMP_ENABLE_TO_FLASH
CONFIG_ESP_COREDUMP_MAX_TASKS_NUM
Maximum number of tasks
Maximum number of tasks snapshots in core dump.
CONFIG_ESP_COREDUMP_UART_DELAY
Delay before print to UART
Config delay (in ms) before printing core dump to UART. Delay can be interrupted by pressing Enter
key.
Default value:
• 0 if ESP_COREDUMP_ENABLE_TO_UART
CONFIG_ESP_COREDUMP_DECODE
Handling of UART core dumps in IDF Monitor
Available options:
• Decode and show summary (info_corefile) (ESP_COREDUMP_DECODE_INFO)
• Don t decode (ESP_COREDUMP_DECODE_DISABLE)
FAT Filesystem support Contains:

• CONFIG_FATFS_API_ENCODING
• CONFIG_FATFS_USE_FASTSEEK
• CONFIG_FATFS_LONG_FILENAMES
• CONFIG_FATFS_MAX_LFN
• CONFIG_FATFS_FS_LOCK
• CONFIG_FATFS_VOLUME_COUNT
• CONFIG_FATFS_CHOOSE_CODEPAGE
• CONFIG_FATFS_ALLOC_PREFER_EXTRAM

• CONFIG_FATFS_TIMEOUT_MS
• CONFIG_FATFS_PER_FILE_CACHE
CONFIG_FATFS_VOLUME_COUNT
Number of volumes
Found in: Component config > FAT Filesystem support
Number of volumes (logical drives) to use.
Range:
• from 1 to 10
Default value:
• 2
CONFIG_FATFS_CHOOSE_CODEPAGE
OEM Code Page
OEM code page used for file name encodings.
If Dynamic is selected, code page can be chosen at runtime using f_setcp function. Note that choosing
this option will increase application size by ~480kB.
Available options:
• Dynamic (all code pages supported) (FATFS_CODEPAGE_DYNAMIC)
• US (CP437) (FATFS_CODEPAGE_437)
• Arabic (CP720) (FATFS_CODEPAGE_720)
• Greek (CP737) (FATFS_CODEPAGE_737)
• KBL (CP771) (FATFS_CODEPAGE_771)
• Baltic (CP775) (FATFS_CODEPAGE_775)
• Latin 1 (CP850) (FATFS_CODEPAGE_850)
• Latin 2 (CP852) (FATFS_CODEPAGE_852)
• Cyrillic (CP855) (FATFS_CODEPAGE_855)
• Turkish (CP857) (FATFS_CODEPAGE_857)
• Portugese (CP860) (FATFS_CODEPAGE_860)
• Icelandic (CP861) (FATFS_CODEPAGE_861)
• Hebrew (CP862) (FATFS_CODEPAGE_862)
• Canadian French (CP863) (FATFS_CODEPAGE_863)
• Arabic (CP864) (FATFS_CODEPAGE_864)
• Nordic (CP865) (FATFS_CODEPAGE_865)
• Russian (CP866) (FATFS_CODEPAGE_866)
• Greek 2 (CP869) (FATFS_CODEPAGE_869)
• Japanese (DBCS) (CP932) (FATFS_CODEPAGE_932)
• Simplified Chinese (DBCS) (CP936) (FATFS_CODEPAGE_936)
• Korean (DBCS) (CP949) (FATFS_CODEPAGE_949)
• Traditional Chinese (DBCS) (CP950) (FATFS_CODEPAGE_950)
CONFIG_FATFS_LONG_FILENAMES
Long filename support
Support long filenames in FAT. Long filename data increases memory usage. FATFS can be configured
to store the buffer for long filename data in stack or heap.
Available options:
• No long filenames (FATFS_LFN_NONE)

• Long filename buffer in heap (FATFS_LFN_HEAP)

• Long filename buffer on stack (FATFS_LFN_STACK)
CONFIG_FATFS_MAX_LFN
Max long filename length
Maximum long filename length. Can be reduced to save RAM.
Range:
• from 12 to 255
Default value:
• 255
CONFIG_FATFS_API_ENCODING
API character encoding
Choose encoding for character and string arguments/returns when using FATFS APIs. The encoding of
arguments will usually depend on text editor settings.
Available options:
• API uses ANSI/OEM encoding (FATFS_API_ENCODING_ANSI_OEM)
• API uses UTF-16 encoding (FATFS_API_ENCODING_UTF_16)
• API uses UTF-8 encoding (FATFS_API_ENCODING_UTF_8)
CONFIG_FATFS_FS_LOCK
Number of simultaneously open files protected by lock function
This option sets the FATFS configuration value _FS_LOCK. The option _FS_LOCK switches file lock
function to control duplicated file open and illegal operation to open objects.
* 0: Disable file lock function. To avoid volume corruption, application should avoid illegal open, remove
and rename to the open objects.
* >0: Enable file lock function. The value defines how many files/sub-directories can be opened simul-
taneously under file lock control.
Note that the file lock control is independent of re-entrancy.
Range:
• from 0 to 65535
Default value:
• 0
CONFIG_FATFS_TIMEOUT_MS
Timeout for acquiring a file lock, ms
This option sets FATFS configuration value _FS_TIMEOUT, scaled to milliseconds. Sets the number
of milliseconds FATFS will wait to acquire a mutex when operating on an open file. For example, if one
task is performing a lenghty operation, another task will wait for the first task to release the lock, and
time out after amount of time set by this option.
Default value:
• 10000

CONFIG_FATFS_PER_FILE_CACHE
Use separate cache for each file
This option affects FATFS configuration value _FS_TINY.
If this option is set, _FS_TINY is 0, and each open file has its own cache, size of the cache is equal to
the _MAX_SS variable (512 or 4096 bytes). This option uses more RAM if more than 1 file is open,
but needs less reads and writes to the storage for some operations.
If this option is not set, _FS_TINY is 1, and single cache is used for all open files, size is also equal to
_MAX_SS variable. This reduces the amount of heap used when multiple files are open, but increases
the number of read and write operations which FATFS needs to make.
Default value:
• Yes (enabled)
CONFIG_FATFS_ALLOC_PREFER_EXTRAM
Perfer external RAM when allocating FATFS buffers
When the option is enabled, internal buffers used by FATFS will be allocated from external RAM. If
the allocation from external RAM fails, the buffer will be allocated from the internal RAM. Disable this
option if optimizing for performance. Enable this option if optimizing for internal memory size.
Default value:
• Yes (enabled) if SPIRAM_USE_CAPS_ALLOC || SPIRAM_USE_MALLOC
CONFIG_FATFS_USE_FASTSEEK
Enable fast seek algorithm when using lseek function through VFS FAT
The fast seek feature enables fast backward/long seek operations without FAT access by using an in-
memory CLMT (cluster link map table). Please note, fast-seek is only allowed for read-mode files, if a
file is opened in write-mode, the seek mechanism will automatically fallback to the default implemen-
tation.
Default value:
• No (disabled)
CONFIG_FATFS_FAST_SEEK_BUFFER_SIZE
Fast seek CLMT buffer size
Found in: Component config > FAT Filesystem support > CONFIG_FATFS_USE_FASTSEEK
If fast seek algorithm is enabled, this defines the size of CLMT buffer used by this algorithm in 32-bit
word units. This value should be chosen based on prior knowledge of maximum elements of each file
entry would store.
Default value:
• 64 if CONFIG_FATFS_USE_FASTSEEK
Modbus configuration Contains:

• CONFIG_FMB_COMM_MODE_ASCII_EN
• CONFIG_FMB_COMM_MODE_RTU_EN
• CONFIG_FMB_COMM_MODE_TCP_EN
• CONFIG_FMB_CONTROLLER_NOTIFY_QUEUE_SIZE

• CONFIG_FMB_CONTROLLER_NOTIFY_TIMEOUT
• CONFIG_FMB_CONTROLLER_SLAVE_ID_SUPPORT
• CONFIG_FMB_CONTROLLER_STACK_SIZE
• CONFIG_FMB_PORT_TASK_PRIO
• CONFIG_FMB_PORT_TASK_STACK_SIZE
• CONFIG_FMB_QUEUE_LENGTH
• CONFIG_FMB_SERIAL_BUF_SIZE
• CONFIG_FMB_EVENT_QUEUE_TIMEOUT
• CONFIG_FMB_TIMER_PORT_ENABLED
• CONFIG_FMB_PORT_TASK_AFFINITY
• CONFIG_FMB_TIMER_USE_ISR_DISPATCH_METHOD
• CONFIG_FMB_SERIAL_ASCII_BITS_PER_SYMB
• CONFIG_FMB_SERIAL_ASCII_TIMEOUT_RESPOND_MS
• CONFIG_FMB_MASTER_DELAY_MS_CONVERT
• CONFIG_FMB_MASTER_TIMEOUT_MS_RESPOND
CONFIG_FMB_COMM_MODE_TCP_EN
Enable Modbus stack support for TCP communication mode
Found in: Component config > Modbus configuration
Enable Modbus TCP option for stack.
Default value:
• Yes (enabled)
CONFIG_FMB_TCP_PORT_DEFAULT
Modbus TCP port number
Found in: Component config > Modbus configuration > CONFIG_FMB_COMM_MODE_TCP_EN
Modbus default port number used by Modbus TCP stack
Range:
• from 0 to 65535
Default value:
• 502
CONFIG_FMB_TCP_PORT_MAX_CONN
Maximum allowed connections for TCP stack
Maximum allowed connections number for Modbus TCP stack. This is used by Modbus master and
slave port layer to establish connections. This parameter may decrease performance of Modbus stack
and can cause increasing of processing time (increase only if absolutely necessary).
Range:
• from 1 to 6
Default value:
• 5
CONFIG_FMB_TCP_CONNECTION_TOUT_SEC
Modbus TCP connection timeout
Modbus TCP connection timeout in seconds. Once expired the current connection with the client will
be closed and Modbus slave will be waiting for new connection to accept.

Range:
• from 1 to 3600
Default value:
• 20
CONFIG_FMB_COMM_MODE_RTU_EN
Enable Modbus stack support for RTU mode
Enable RTU Modbus communication mode option for Modbus serial stack.
Default value:
• Yes (enabled)
CONFIG_FMB_COMM_MODE_ASCII_EN
Enable Modbus stack support for ASCII mode
Enable ASCII Modbus communication mode option for Modbus serial stack.
Default value:
• Yes (enabled)
CONFIG_FMB_MASTER_TIMEOUT_MS_RESPOND
Slave respond timeout (Milliseconds)
If master sends a frame which is not broadcast, it has to wait sometime for slave response. if slave is not
respond in this time, the master will process timeout error.
Range:
• from 50 to 3000
Default value:
• 150
CONFIG_FMB_MASTER_DELAY_MS_CONVERT
Slave conversion delay (Milliseconds)
If master sends a broadcast frame, it has to wait conversion time to delay, then master can send next
frame.
Range:
• from 50 to 400
Default value:
• 200
CONFIG_FMB_QUEUE_LENGTH
Modbus serial task queue length
Modbus serial driver queue length. It is used by event queue task. See the serial driver API for more
information.
Range:

• from 0 to 200
Default value:
• 20
CONFIG_FMB_PORT_TASK_STACK_SIZE
Modbus port task stack size
Modbus port task stack size for rx/tx event processing. It may be adjusted when debugging is enabled
(for example).
Range:
• from 2048 to 8192
Default value:
• 4096
CONFIG_FMB_SERIAL_BUF_SIZE
Modbus serial task RX/TX buffer size
Modbus serial task RX and TX buffer size for UART driver initialization. This buffer is used for modbus
frame transfer. The Modbus protocol maximum frame size is 256 bytes. Bigger size can be used for
non standard implementations.
Range:
• from 0 to 2048
Default value:
• 256
CONFIG_FMB_SERIAL_ASCII_BITS_PER_SYMB
Number of data bits per ASCII character
This option defines the number of data bits per ASCII character.
Range:
• from 7 to 8
Default value:
• 8
CONFIG_FMB_SERIAL_ASCII_TIMEOUT_RESPOND_MS
Response timeout for ASCII communication mode (ms)
This option defines response timeout of slave in milliseconds for ASCII communication mode. Thus the
timeout will expire and allow the master program to handle the error.
Range:
• from 300 to 2000
Default value:
• 1000

CONFIG_FMB_PORT_TASK_PRIO
Modbus port task priority
Modbus port data processing task priority. The priority of Modbus controller task is equal to (CON-
FIG_FMB_PORT_TASK_PRIO - 1).
Range:
• from 3 to 23
Default value:
• 10
CONFIG_FMB_PORT_TASK_AFFINITY
Modbus task affinity
Allows setting the core affinity of the Modbus controller task, i.e. whether the task is pinned to particular
CPU, or allowed to run on any CPU.
Available options:
• No affinity (FMB_PORT_TASK_AFFINITY_NO_AFFINITY)
• CPU0 (FMB_PORT_TASK_AFFINITY_CPU0)
• CPU1 (FMB_PORT_TASK_AFFINITY_CPU1)
CONFIG_FMB_CONTROLLER_SLAVE_ID_SUPPORT
Modbus controller slave ID support
Modbus slave ID support enable. When enabled the Modbus <Report Slave ID> command is supported
by stack.
Default value:
• Yes (enabled)
CONFIG_FMB_CONTROLLER_SLAVE_ID
Modbus controller slave ID
Found in: Component config > Modbus configuration > CON-
FIG_FMB_CONTROLLER_SLAVE_ID_SUPPORT
Modbus slave ID value to identify modbus device in the network using <Report Slave ID> command.
Most significant byte of ID is used as short device ID and other three bytes used as long ID.
Range:
• from 0 to 4294967295
Default value:
• 0x00112233
CONFIG_FMB_CONTROLLER_NOTIFY_TIMEOUT
Modbus controller notification timeout (ms)
Modbus controller notification timeout in milliseconds. This timeout is used to send notification about
accessed parameters.
Range:

• from 0 to 200
Default value:
• 20
CONFIG_FMB_CONTROLLER_NOTIFY_QUEUE_SIZE
Modbus controller notification queue size
Modbus controller notification queue size. The notification queue is used to get information about ac-
cessed parameters.
Range:
• from 0 to 200
Default value:
• 20
CONFIG_FMB_CONTROLLER_STACK_SIZE
Modbus controller stack size
Modbus controller task stack size. The Stack size may be adjusted when debug mode is used which
requires more stack size (for example).
Range:
• from 0 to 8192
Default value:
• 4096
CONFIG_FMB_EVENT_QUEUE_TIMEOUT
Modbus stack event queue timeout (ms)
Modbus stack event queue timeout in milliseconds. This may help to optimize Modbus stack event
processing time.
Range:
• from 0 to 500
Default value:
• 20
CONFIG_FMB_TIMER_PORT_ENABLED
Modbus stack use timer for 3.5T symbol time measurement
If this option is set the Modbus stack uses timer for T3.5 time measurement. Else the internal UART
TOUT timeout is used for 3.5T symbol time measurement.
Default value:
• No (disabled)

CONFIG_FMB_TIMER_USE_ISR_DISPATCH_METHOD
Modbus timer uses ISR dispatch method
If this option is set the Modbus stack uses ISR dispatch method to send timeout events from the callback
function called from ISR. This option has dependency with the UART_ISR_IN_IRAM option which
places UART interrupt handler into IRAM to prevent delays related to processing of UART events.
Default value:
• No (disabled)
FreeRTOS Contains:
• CONFIG_FREERTOS_FPU_IN_ISR
• CONFIG_FREERTOS_CHECK_STACKOVERFLOW
• CONFIG_FREERTOS_CHECK_MUTEX_GIVEN_BY_OWNER
• CONFIG_FREERTOS_INTERRUPT_BACKTRACE
• CONFIG_FREERTOS_OPTIMIZED_SCHEDULER
• CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS
• CONFIG_FREERTOS_USE_TRACE_FACILITY
• CONFIG_FREERTOS_ENABLE_STATIC_TASK_CLEAN_UP
• CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT
• CONFIG_FREERTOS_TASK_FUNCTION_WRAPPER
• CONFIG_FREERTOS_ASSERT
• CONFIG_FREERTOS_QUEUE_REGISTRY_SIZE
• CONFIG_FREERTOS_TIMER_QUEUE_LENGTH
• CONFIG_FREERTOS_TIMER_TASK_PRIORITY
• CONFIG_FREERTOS_TIMER_TASK_STACK_DEPTH
• CONFIG_FREERTOS_ASSERT_ON_UNTESTED_FUNCTION
• CONFIG_FREERTOS_IDLE_TASK_STACKSIZE
• CONFIG_FREERTOS_ISR_STACKSIZE
• CONFIG_FREERTOS_MAX_TASK_NAME_LEN
• CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS
• CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH
• CONFIG_FREERTOS_UNICORE
• CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK
• CONFIG_FREERTOS_CHECK_PORT_CRITICAL_COMPLIANCE
• CONFIG_FREERTOS_HZ
• CONFIG_FREERTOS_USE_TICKLESS_IDLE
• CONFIG_FREERTOS_LEGACY_HOOKS
• CONFIG_FREERTOS_CORETIMER
CONFIG_FREERTOS_UNICORE
Run FreeRTOS only on first core
Found in: Component config > FreeRTOS
This version of FreeRTOS normally takes control of all cores of the CPU. Select this if you only want
to start it on the first core. This is needed when e.g. another process needs complete control over the
second core.
# This invisible config value sets the value of tskNO_AFFINITY in task.h. # Intended to be used as a
constant from other Kconfig files. # Value is (32-bit) INT_MAX.
CONFIG_FREERTOS_CORETIMER
Xtensa timer to use as the FreeRTOS tick source


FreeRTOS needs a timer with an associated interrupt to use as the main tick source to increase counters,
run timers and do pre-emptive multitasking with. There are multiple timers available to do this, with
different interrupt priorities. Check
Available options:
• Timer 0 (int 6, level 1) (FREERTOS_CORETIMER_0)
Select this to use timer 0
• Timer 1 (int 15, level 3) (FREERTOS_CORETIMER_1)
Select this to use timer 1
• SYSTIMER 0 (level 1) (FREERTOS_CORETIMER_SYSTIMER_LVL1)
Select this to use systimer with the 1 interrupt priority.
• SYSTIMER 0 (level 3) (FREERTOS_CORETIMER_SYSTIMER_LVL3)
Select this to use systimer with the 3 interrupt priority.
CONFIG_FREERTOS_OPTIMIZED_SCHEDULER
Enable FreeRTOS pĺatform optimized scheduler
On most platforms there are instructions can speedup the ready task searching. Enabling this option the
FreeRTOS with this instructions support will be built.
Default value:
• Yes (enabled) if CONFIG_FREERTOS_UNICORE
CONFIG_FREERTOS_HZ
Tick rate (Hz)
Select the tick rate at which FreeRTOS does pre-emptive context switching.
Range:
• from 1 to 1000
Default value:
• 100
CONFIG_FREERTOS_ASSERT_ON_UNTESTED_FUNCTION
Halt when an SMP-untested function is called
Some functions in FreeRTOS have not been thoroughly tested yet when moving to the SMP implemen-
tation of FreeRTOS. When this option is enabled, these fuctions will throw an assert().
Default value:
• Yes (enabled)
CONFIG_FREERTOS_CHECK_STACKOVERFLOW
Check for stack overflow
FreeRTOS can check for stack overflows in threads and trigger an user function called vApplication-
StackOverflowHook when this happens.
Available options:

• No checking (FREERTOS_CHECK_STACKOVERFLOW_NONE)
Do not check for stack overflows (configCHECK_FOR_STACK_OVERFLOW=0)
• Check by stack pointer value (FREERTOS_CHECK_STACKOVERFLOW_PTRVAL)
Check for stack overflows on each context switch by checking if the stack pointer is in a valid
range. Quick but does not detect stack overflows that happened between context switches
(configCHECK_FOR_STACK_OVERFLOW=1)
• Check using canary bytes (FREERTOS_CHECK_STACKOVERFLOW_CANARY)
Places some magic bytes at the end of the stack area and on each context switch, check if these
bytes are still intact. More thorough than just checking the pointer, but also slightly slower.
(configCHECK_FOR_STACK_OVERFLOW=2)
CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK
Set a debug watchpoint as a stack overflow check
FreeRTOS can check if a stack has overflown its bounds by checking either the value of the stack pointer
or by checking the integrity of canary bytes. (See FREERTOS_CHECK_STACKOVERFLOW for
more information.) These checks only happen on a context switch, and the situation that caused the stack
overflow may already be long gone by then. This option will use the last debug memory watchpoint to
allow breaking into the debugger (or panic ing) as soon as any of the last 32 bytes on the stack of a
task are overwritten. The side effect is that using gdb, you effectively have one hardware watchpoint less
because the last one is overwritten as soon as a task switch happens.
Another consequence is that due to alignment requirements of the watchpoint, the usable stack size
decreases by up to 60 bytes. This is because the watchpoint region has to be aligned to its size and the
size for the stack watchpoint in IDF is 32 bytes.
This check only triggers if the stack overflow writes within 32 bytes near the end of the stack, rather
than overshooting further, so it is worth combining this approach with one of the other stack overflow
check methods.
When this watchpoint is hit, gdb will stop with a SIGTRAP message. When no JTAG OCD is attached,
esp-idf will panic on an unhandled debug exception.
Default value:
• No (disabled)
CONFIG_FREERTOS_INTERRUPT_BACKTRACE
Enable backtrace from interrupt to task context
If this option is enabled, interrupt stack frame will be modified to point to the code of the interrupted
task as its return address. This helps the debugger (or the panic handler) show a backtrace from the
interrupt to the task which was interrupted. This also works for nested interrupts: higer level interrupt
stack can be traced back to the lower level interrupt. This option adds 4 instructions to the interrupt
dispatching code.
Default value:
• Yes (enabled)
CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS
Number of thread local storage pointers
FreeRTOS has the ability to store per-thread pointers in the task control block. This controls the number
of pointers available.

This value must be at least 1. Index 0 is reserved for use by the pthreads API thread-local-storage. Other
indexes can be used for any desired purpose.
Range:
• from 1 to 256
Default value:
• 1
CONFIG_FREERTOS_ASSERT
FreeRTOS assertions
Failed FreeRTOS configASSERT() assertions can be configured to behave in different ways.
By default these behave the same as the global project assert settings.
Available options:
• abort() on failed assertions (FREERTOS_ASSERT_FAIL_ABORT)
If a FreeRTOS configASSERT() fails, FreeRTOS will abort() and halt execution. The panic
handler can be configured to handle the outcome of an abort() in different ways.
If assertions are disabled for the entire project, they are also disabled in FreeRTOS and this
option is unavailable.
• Print and continue failed assertions (FREERTOS_ASSERT_FAIL_PRINT_CONTINUE)
If a FreeRTOS assertion fails, print it out and continue.
• Disable FreeRTOS assertions (FREERTOS_ASSERT_DISABLE)
FreeRTOS configASSERT() will not be compiled into the binary.
CONFIG_FREERTOS_IDLE_TASK_STACKSIZE
Idle Task stack size
The idle task has its own stack, sized in bytes. The default size is enough for most uses. Size can
be reduced to 768 bytes if no (or simple) FreeRTOS idle hooks are used and pthread local storage or
FreeRTOS local storage cleanup callbacks are not used.
The stack size may need to be increased above the default if the app installs idle or thread local storage
cleanup hooks that use a lot of stack memory.
Range:
• from 768 to 32768
Default value:
• 1536
CONFIG_FREERTOS_ISR_STACKSIZE
ISR stack size
The interrupt handlers have their own stack. The size of the stack can be defined here. Each processor
has its own stack, so the total size occupied will be twice this.
Range:
• from 2096 to 32768 if ESP_COREDUMP_DATA_FORMAT_ELF
• from 1536 to 32768
Default value:
• 2096 if ESP_COREDUMP_DATA_FORMAT_ELF
• 1536

CONFIG_FREERTOS_LEGACY_HOOKS
Use FreeRTOS legacy hooks
FreeRTOS offers a number of hooks/callback functions that are called when a timer tick hap-
pens, the idle thread runs etc. esp-idf replaces these by runtime registerable hooks using the
esp_register_freertos_xxx_hook system, but for legacy reasons the old hooks can also still be en-
abled. Please enable this only if you have code that for some reason can t be migrated to the
esp_register_freertos_xxx_hook system.
Default value:
• No (disabled)
CONFIG_FREERTOS_MAX_TASK_NAME_LEN
Maximum task name length
Changes the maximum task name length. Each task allocated will include this many bytes for a task
name. Using a shorter value saves a small amount of RAM, a longer value allows more complex names.
For most uses, the default of 16 is OK.
Range:
• from 1 to 256
Default value:
• 16
CONFIG_FREERTOS_ENABLE_STATIC_TASK_CLEAN_UP
Enable static task clean up hook
Enable this option to make FreeRTOS call the static task clean up hook when a task is deleted.
Bear in mind that if this option is enabled you will need to implement the following function:
void vPortCleanUpTCB ( void \*pxTCB ) {

// place clean up code here
}
Default value:
• No (disabled)
CONFIG_FREERTOS_TIMER_TASK_PRIORITY
FreeRTOS timer task priority
The timer service task (primarily) makes use of existing FreeRTOS features, allowing timer functionality
to be added to an application with minimal impact on the size of the application s executable binary.
Use this constant to define the priority that the timer task will run at.
Range:
• from 1 to 25
Default value:
• 1

CONFIG_FREERTOS_TIMER_TASK_STACK_DEPTH
FreeRTOS timer task stack size
The timer service task (primarily) makes use of existing FreeRTOS features, allowing timer functionality
to be added to an application with minimal impact on the size of the application s executable binary.
Use this constant to define the size (in bytes) of the stack allocated for the timer task.
Range:
• from 1536 to 32768
Default value:
• 2048
CONFIG_FREERTOS_TIMER_QUEUE_LENGTH
FreeRTOS timer queue length
FreeRTOS provides a set of timer related API functions. Many of these functions use a standard FreeR-
TOS queue to send commands to the timer service task. The queue used for this purpose is called the
timer command queue . The timer command queue is private to the FreeRTOS timer implemen-
tation, and cannot be accessed directly.
For most uses the default value of 10 is OK.
Range:
• from 5 to 20
Default value:
• 10
CONFIG_FREERTOS_QUEUE_REGISTRY_SIZE
FreeRTOS queue registry size
FreeRTOS uses the queue registry as a means for kernel aware debuggers to locate queues, semaphores,
and mutexes. The registry allows for a textual name to be associated with a queue for easy identification
within a debugging GUI. A value of 0 will disable queue registry functionality, and a value larger than 0
will specify the number of queues/semaphores/mutexes that the registry can hold.
Range:
• from 0 to 20
Default value:
• 0
CONFIG_FREERTOS_USE_TRACE_FACILITY
Enable FreeRTOS trace facility
If enabled, configUSE_TRACE_FACILITY will be defined as 1 in FreeRTOS. This will allow the usage
of trace facility functions such as uxTaskGetSystemState().
Default value:
• No (disabled)

CONFIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS
Enable FreeRTOS stats formatting functions
Found in: Component config > FreeRTOS > CONFIG_FREERTOS_USE_TRACE_FACILITY
If enabled, configUSE_STATS_FORMATTING_FUNCTIONS will be defined as 1 in FreeRTOS. This
will allow the usage of stats formatting functions such as vTaskList().
Default value:
• No (disabled) if CONFIG_FREERTOS_USE_TRACE_FACILITY
CONFIG_FREERTOS_VTASKLIST_INCLUDE_COREID
Enable display of xCoreID in vTaskList
Found in: Component config > FreeRTOS > CONFIG_FREERTOS_USE_TRACE_FACILITY > CON-
FIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS
If enabled, this will include an extra column when vTaskList is called to display the CoreID the task is
pinned to (0,1) or -1 if not pinned.
Default value:
• No (disabled) if CONFIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS
CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS
Enable FreeRTOS to collect run time stats
If enabled, configGENERATE_RUN_TIME_STATS will be defined as 1 in FreeRTOS. This will al-
low FreeRTOS to collect information regarding the usage of processor time amongst FreeRTOS tasks.
Run time stats are generated using either the ESP Timer or the CPU Clock as the clock source (Note
that run time stats are only valid until the clock source overflows). The function vTaskGetRunTimeS-
tats() will also be available if FREERTOS_USE_STATS_FORMATTING_FUNCTIONS and FREER-
TOS_USE_TRACE_FACILITY are enabled. vTaskGetRunTimeStats() will display the run time of
each task as a % of the total run time of all CPUs (task run time / no of CPUs) / (total run time / 100 )
Default value:
• No (disabled)
CONFIG_FREERTOS_RUN_TIME_STATS_CLK
Choose the clock source for run time stats
Found in: Component config > FreeRTOS > CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS
Choose the clock source for FreeRTOS run time stats. Options are CPU0 s CPU Clock or the ESP
Timer. Both clock sources are 32 bits. The CPU Clock can run at a higher frequency hence provide a
finer resolution but will overflow much quicker. Note that run time stats are only valid until the clock
source overflows.
Available options:
• Use ESP TIMER for run time stats (FREERTOS_RUN_TIME_STATS_USING_ESP_TIMER)
ESP Timer will be used as the clock source for FreeRTOS run time stats. The ESP Timer
runs at a frequency of 1MHz regardless of Dynamic Frequency Scaling. Therefore the ESP
Timer will overflow in approximately 4290 seconds.
• Use CPU Clock for run time stats (FREERTOS_RUN_TIME_STATS_USING_CPU_CLK)
CPU Clock will be used as the clock source for the generation of run time stats. The CPU
Clock has a frequency dependent on ESP32_DEFAULT_CPU_FREQ_MHZ and Dynamic
Frequency Scaling (DFS). Therefore the CPU Clock frequency can fluctuate between 80 to
240MHz. Run time stats generated using the CPU Clock represents the number of CPU
cycles each task is allocated and DOES NOT reflect the amount of time each task runs for

(as CPU clock frequency can change). If the CPU clock consistently runs at the maximum
frequency of 240MHz, it will overflow in approximately 17 seconds.
CONFIG_FREERTOS_USE_TICKLESS_IDLE
Tickless idle support
If power management support is enabled, FreeRTOS will be able to put the system into light sleep
mode when no tasks need to run for a number of ticks. This number can be set using FREER-
TOS_IDLE_TIME_BEFORE_SLEEP option. This feature is also known as automatic light sleep
.
Note that timers created using esp_timer APIs may prevent the system from entering sleep mode,
even when no tasks need to run. To skip unnecessary wake-up initialize a timer with the
skip_unhandled_events option as true.
If disabled, automatic light sleep support will be disabled.
Default value:
CONFIG_FREERTOS_IDLE_TIME_BEFORE_SLEEP
Minimum number of ticks to enter sleep mode for
Found in: Component config > FreeRTOS > CONFIG_FREERTOS_USE_TICKLESS_IDLE
FreeRTOS will enter light sleep mode if no tasks need to run for this number of ticks.
Range:
• from 2 to 4294967295 if CONFIG_FREERTOS_USE_TICKLESS_IDLE
Default value:
• 3 if CONFIG_FREERTOS_USE_TICKLESS_IDLE
CONFIG_FREERTOS_TASK_FUNCTION_WRAPPER
Enclose all task functions in a wrapper function
If enabled, all FreeRTOS task functions will be enclosed in a wrapper function. If a task function
mistakenly returns (i.e. does not delete), the call flow will return to the wrapper function. The wrapper
function will then log an error and abort the application. This option is also required for GDB backtraces
and C++ exceptions to work correctly inside top-level task functions.
Default value:
• Yes (enabled)
CONFIG_FREERTOS_CHECK_MUTEX_GIVEN_BY_OWNER
Check that mutex semaphore is given by owner task
If enabled, assert that when a mutex semaphore is given, the task giving the semaphore is the task which
is currently holding the mutex.
Default value:
• Yes (enabled)

CONFIG_FREERTOS_CHECK_PORT_CRITICAL_COMPLIANCE
Tests compliance with Vanilla FreeRTOS port*_CRITICAL calls
If enabled, context of port*_CRITICAL calls (ISR or Non-ISR) would be checked to be in compliance
with Vanilla FreeRTOS. e.g Calling port*_CRITICAL from ISR context would cause assert failure
Default value:
• No (disabled)
CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH
Place FreeRTOS functions into Flash
When enabled the selected Non-ISR FreeRTOS functions will be placed into Flash memory instead of
IRAM. This saves up to 8KB of IRAM depending on which functions are used.
Default value:
• No (disabled)
CONFIG_FREERTOS_FPU_IN_ISR
Allow use of float inside Level 1 ISR (EXPERIMENTAL)
When enabled, the usage of float type is allowed inside Level 1 ISRs.
Default value:
• No (disabled)
CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT
Enable task snapshot functions
When enabled, the functions related to snapshots, such as vTaskGetSnapshot or uxTaskGetSnapshotAll,
are compiled and linked.
Default value:
• Yes (enabled)
CONFIG_FREERTOS_PLACE_SNAPSHOT_FUNS_INTO_FLASH
Place task snapshot functions into flash
Found in: Component config > FreeRTOS > CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT
When enabled, the functions related to snapshots, such as vTaskGetSnapshot or uxTaskGetSnapshotAll,
will be placed in flash. Note that if enabled, these functions cannot be called when cache is disabled.
Default value:
• No (disabled) if CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT && CON-
FIG_ESP_PANIC_HANDLER_IRAM
Hardware Abstraction Layer (HAL) and Low Level (LL) Contains:

• CONFIG_HAL_DEFAULT_ASSERTION_LEVEL

CONFIG_HAL_DEFAULT_ASSERTION_LEVEL
Default HAL assertion level
Found in: Component config > Hardware Abstraction Layer (HAL) and Low Level (LL)
Set the assert behavior / level for HAL component. HAL component assert level can be set separately,
but the level can t exceed the system assertion level. e.g. If the system assertion is disabled, then the
HAL assertion can t be enabled either. If the system assertion is enable, then the HAL assertion can
still be disabled by this Kconfig option.
Available options:
• Same as system assertion level (HAL_ASSERTION_EQUALS_SYSTEM)
• Disabled (HAL_ASSERTION_DISABLE)
• Silent (HAL_ASSERTION_SILIENT)
• Enabled (HAL_ASSERTION_ENABLE)
Heap memory debugging Contains:

• CONFIG_HEAP_ABORT_WHEN_ALLOCATION_FAILS
• CONFIG_HEAP_TASK_TRACKING
• CONFIG_HEAP_CORRUPTION_DETECTION
• CONFIG_HEAP_TRACING_DEST
• CONFIG_HEAP_TRACING_STACK_DEPTH
CONFIG_HEAP_CORRUPTION_DETECTION
Heap corruption detection
Found in: Component config > Heap memory debugging
Enable heap poisoning features to detect heap corruption caused by out-of-bounds access to heap mem-
ory.
See the Heap Memory Debugging page of the IDF documentation for a description of each level of
heap corruption detection.
Available options:
• Basic (no poisoning) (HEAP_POISONING_DISABLED)
• Light impact (HEAP_POISONING_LIGHT)
• Comprehensive (HEAP_POISONING_COMPREHENSIVE)
CONFIG_HEAP_TRACING_DEST
Heap tracing
Enables the heap tracing API defined in esp_heap_trace.h.
This function causes a moderate increase in IRAM code side and a minor increase in heap function
(malloc/free/realloc) CPU overhead, even when the tracing feature is not used. So it s best to keep it
disabled unless tracing is being used.
Available options:
• Disabled (HEAP_TRACING_OFF)
• Standalone (HEAP_TRACING_STANDALONE)
• Host-based (HEAP_TRACING_TOHOST)

CONFIG_HEAP_TRACING_STACK_DEPTH
Heap tracing stack depth
Number of stack frames to save when tracing heap operation callers.
More stack frames uses more memory in the heap trace buffer (and slows down allocation), but can
provide useful information.
CONFIG_HEAP_TASK_TRACKING
Enable heap task tracking
Enables tracking the task responsible for each heap allocation.
This function depends on heap poisoning being enabled and adds four more bytes of overhead for each
block allocated.
CONFIG_HEAP_ABORT_WHEN_ALLOCATION_FAILS
Abort if memory allocation fails
When enabled, if a memory allocation operation fails it will cause a system abort.
Default value:
• No (disabled)
jsmn Contains:
• CONFIG_JSMN_PARENT_LINKS
• CONFIG_JSMN_STRICT
CONFIG_JSMN_PARENT_LINKS
Enable parent links
Found in: Component config > jsmn
You can access to parent node of parsed json
Default value:
• No (disabled)
CONFIG_JSMN_STRICT
Enable strict mode
Found in: Component config > jsmn
In strict mode primitives are: numbers and booleans
Default value:
• No (disabled)
libsodium Contains:
• CONFIG_LIBSODIUM_USE_MBEDTLS_SHA

CONFIG_LIBSODIUM_USE_MBEDTLS_SHA
Use mbedTLS SHA256 & SHA512 implementations
Found in: Component config > libsodium
If this option is enabled, libsodium will use thin wrappers around mbedTLS for SHA256 & SHA512
operations.
This saves some code size if mbedTLS is also used. However it is incompatible with hardware SHA
acceleration (due to the way libsodium s API manages SHA state).
Default value:
• Yes (enabled)
Log output Contains:

• CONFIG_LOG_DEFAULT_LEVEL
• CONFIG_LOG_TIMESTAMP_SOURCE
• CONFIG_LOG_MAXIMUM_LEVEL
• CONFIG_LOG_COLORS
CONFIG_LOG_DEFAULT_LEVEL
Default log verbosity
Found in: Component config > Log output
Specify how much output to see in logs by default. You can set lower verbosity level at runtime using
esp_log_level_set function.
By default, this setting limits which log statements are compiled into the program. For example, selecting
Warning would mean that changing log level to Debug at runtime will not be possible. To allow
increasing log level above the default at runtime, see the next option.
Available options:
• No output (LOG_DEFAULT_LEVEL_NONE)
• Error (LOG_DEFAULT_LEVEL_ERROR)
• Warning (LOG_DEFAULT_LEVEL_WARN)
• Info (LOG_DEFAULT_LEVEL_INFO)
• Debug (LOG_DEFAULT_LEVEL_DEBUG)
• Verbose (LOG_DEFAULT_LEVEL_VERBOSE)
CONFIG_LOG_MAXIMUM_LEVEL
Maximum log verbosity
This config option sets the highest log verbosity that it s possible to select at runtime by calling
esp_log_level_set(). This level may be higher than the default verbosity level which is set when the
app starts up.
This can be used enable debugging output only at a critical point, for a particular tag, or to minimize
startup time but then enable more logs once the firmware has loaded.
Note that increasing the maximum available log level will increase the firmware binary size.
This option only applies to logging from the app, the bootloader log level is fixed at compile time to the
separate Bootloader log verbosity setting.
Available options:
• Same as default (LOG_MAXIMUM_EQUALS_DEFAULT)
• Error (LOG_MAXIMUM_LEVEL_ERROR)
• Warning (LOG_MAXIMUM_LEVEL_WARN)

• Info (LOG_MAXIMUM_LEVEL_INFO)
• Debug (LOG_MAXIMUM_LEVEL_DEBUG)
• Verbose (LOG_MAXIMUM_LEVEL_VERBOSE)
CONFIG_LOG_COLORS
Use ANSI terminal colors in log output
Enable ANSI terminal color codes in bootloader output.
In order to view these, your terminal program must support ANSI color codes.
Default value:
• Yes (enabled)
CONFIG_LOG_TIMESTAMP_SOURCE
Log Timestamps
Choose what sort of timestamp is displayed in the log output:
• Milliseconds since boot is calulated from the RTOS tick count multiplied by the tick period. This
time will reset after a software reboot. e.g. (90000)
• System time is taken from POSIX time functions which use the ESP32 s RTC and FRC1 timers
to maintain an accurate time. The system time is initialized to 0 on startup, it can be set with an
SNTP sync, or with POSIX time functions. This time will not reset after a software reboot. e.g.
(00:01:30.000)
• NOTE: Currently this will not get used in logging from binary blobs (i.e WiFi & Bluetooth li-
braries), these will always print milliseconds since boot.
Available options:
• Milliseconds Since Boot (LOG_TIMESTAMP_SOURCE_RTOS)
• System Time (LOG_TIMESTAMP_SOURCE_SYSTEM)
LWIP Contains:
• Checksums
• DHCP server
• CONFIG_LWIP_DHCP_OPTIONS_LEN
• CONFIG_LWIP_DHCP_DISABLE_CLIENT_ID
• CONFIG_LWIP_DHCP_DISABLE_VENDOR_CLASS_ID
• CONFIG_LWIP_DHCP_DOES_ARP_CHECK
• CONFIG_LWIP_DHCP_RESTORE_LAST_IP
• CONFIG_LWIP_PPP_CHAP_SUPPORT
• CONFIG_LWIP_L2_TO_L3_COPY
• CONFIG_LWIP_IPV6_DHCP6
• CONFIG_LWIP_IP4_FRAG
• CONFIG_LWIP_IP6_FRAG
• CONFIG_LWIP_IP_FORWARD
• CONFIG_LWIP_NETBUF_RECVINFO
• CONFIG_LWIP_AUTOIP
• CONFIG_LWIP_IPV6
• CONFIG_LWIP_ENABLE_LCP_ECHO
• CONFIG_LWIP_ETHARP_TRUST_IP_MAC
• CONFIG_LWIP_ESP_LWIP_ASSERT
• CONFIG_LWIP_DEBUG
• CONFIG_LWIP_IRAM_OPTIMIZATION

• CONFIG_LWIP_STATS
• CONFIG_LWIP_TIMERS_ONDEMAND
• CONFIG_LWIP_DNS_SUPPORT_MDNS_QUERIES
• CONFIG_LWIP_PPP_MPPE_SUPPORT
• CONFIG_LWIP_PPP_MSCHAP_SUPPORT
• CONFIG_LWIP_PPP_NOTIFY_PHASE_SUPPORT
• CONFIG_LWIP_PPP_PAP_SUPPORT
• CONFIG_LWIP_PPP_DEBUG_ON
• CONFIG_LWIP_PPP_SUPPORT
• CONFIG_LWIP_IP4_REASSEMBLY
• CONFIG_LWIP_IP6_REASSEMBLY
• CONFIG_LWIP_SLIP_SUPPORT
• CONFIG_LWIP_SO_LINGER
• CONFIG_LWIP_SO_RCVBUF
• CONFIG_LWIP_SO_REUSE
• CONFIG_LWIP_NETIF_STATUS_CALLBACK
• CONFIG_LWIP_TCPIP_CORE_LOCKING
• CONFIG_LWIP_NETIF_API
• Hooks
• ICMP
• CONFIG_LWIP_LOCAL_HOSTNAME
• LWIP RAW API
• CONFIG_LWIP_IPV6_ND6_NUM_NEIGHBORS
• CONFIG_LWIP_IPV6_MEMP_NUM_ND6_QUEUE
• CONFIG_LWIP_MAX_SOCKETS
• CONFIG_LWIP_ESP_GRATUITOUS_ARP
• SNTP
• CONFIG_LWIP_USE_ONLY_LWIP_SELECT
• CONFIG_LWIP_NETIF_LOOPBACK
• TCP
• CONFIG_LWIP_TCPIP_TASK_AFFINITY
• CONFIG_LWIP_TCPIP_TASK_STACK_SIZE
• CONFIG_LWIP_TCPIP_RECVMBOX_SIZE
• UDP
• CONFIG_LWIP_IPV6_RDNSS_MAX_DNS_SERVERS
CONFIG_LWIP_LOCAL_HOSTNAME
Local netif hostname
Found in: Component config > LWIP
The default name this device will report to other devices on the network. Could be updated at runtime
with esp_netif_set_hostname()
Default value:
• espressif
CONFIG_LWIP_NETIF_API
Enable usage of standard POSIX APIs in LWIP
If this feature is enabled, standard POSIX APIs: if_indextoname(), if_nametoindex() could be
used to convert network interface index to name instead of IDF specific esp-netif APIs (such as
esp_netif_get_netif_impl_name())
Default value:
• No (disabled)

CONFIG_LWIP_TCPIP_CORE_LOCKING
Enable tcpip core locking
If Enable tcpip core locking,Creates a global mutex that is held during TCPIP thread operations.Can
be locked by client code to perform lwIP operations without changing into TCPIP thread using callbacks.
See LOCK_TCPIP_CORE() and UNLOCK_TCPIP_CORE().
If disable tcpip core locking,TCP IP will perform tasks through context switching
Default value:
• No (disabled)
CONFIG_LWIP_DNS_SUPPORT_MDNS_QUERIES
Enable mDNS queries in resolving host name
If this feature is enabled, standard API such as gethostbyname support .local addresses by sending one
shot multicast mDNS query
Default value:
• Yes (enabled)
CONFIG_LWIP_L2_TO_L3_COPY
Enable copy between Layer2 and Layer3 packets
If this feature is enabled, all traffic from layer2(WIFI Driver) will be copied to a new buffer before send-
ing it to layer3(LWIP stack), freeing the layer2 buffer. Please be notified that the total layer2 receiving
buffer is fixed and ESP32 currently supports 25 layer2 receiving buffer, when layer2 buffer runs out of
memory, then the incoming packets will be dropped in hardware. The layer3 buffer is allocated from
the heap, so the total layer3 receiving buffer depends on the available heap size, when heap runs out of
memory, no copy will be sent to layer3 and packet will be dropped in layer2. Please make sure you fully
understand the impact of this feature before enabling it.
Default value:
• No (disabled)
CONFIG_LWIP_IRAM_OPTIMIZATION
Enable LWIP IRAM optimization
If this feature is enabled, some functions relating to RX/TX in LWIP will be put into IRAM, it can
improve UDP/TCP throughput by >10% for single core mode, it doesn t help too much for dual core
mode. On the other hand, it needs about 10KB IRAM for these optimizations.
If this feature is disabled, all lwip functions will be put into FLASH.
Default value:
• No (disabled)
CONFIG_LWIP_TIMERS_ONDEMAND
Enable LWIP Timers on demand

If this feature is enabled, IGMP and MLD6 timers will be activated only when joining groups or receiving
QUERY packets.
This feature will reduce the power consumption for applications which do not use IGMP and MLD6.
Default value:
• Yes (enabled)
CONFIG_LWIP_MAX_SOCKETS
Max number of open sockets
Sockets take up a certain amount of memory, and allowing fewer sockets to be open at the same time
conserves memory. Specify the maximum amount of sockets here. The valid value is from 1 to 16.
Range:
• from 1 to 16
Default value:
• 10
CONFIG_LWIP_USE_ONLY_LWIP_SELECT
Support LWIP socket select() only (DEPRECATED)
This option is deprecated. Use VFS_SUPPORT_SELECT instead, which is the inverse of this option.
The virtual filesystem layer of select() redirects sockets to lwip_select() and non-socket file descriptors
to their respective driver implementations. If this option is enabled then all calls of select() will be
redirected to lwip_select(), therefore, select can be used for sockets only.
Default value:
• No (disabled)
CONFIG_LWIP_SO_LINGER
Enable SO_LINGER processing
Enabling this option allows SO_LINGER processing. l_onoff = 1,l_linger can set the timeout.
If l_linger=0, When a connection is closed, TCP will terminate the connection. This means that TCP
will discard any data packets stored in the socket send buffer and send an RST to the peer.
If l_linger!=0,Then closesocket() calls to block the process until the remaining data packets has been
sent or timed out.
Default value:
• No (disabled)
CONFIG_LWIP_SO_REUSE
Enable SO_REUSEADDR option
Enabling this option allows binding to a port which remains in TIME_WAIT.
Default value:
• Yes (enabled)

CONFIG_LWIP_SO_REUSE_RXTOALL
SO_REUSEADDR copies broadcast/multicast to all matches
Found in: Component config > LWIP > CONFIG_LWIP_SO_REUSE
Enabling this option means that any incoming broadcast or multicast packet will be copied to all of the
local sockets that it matches (may be more than one if SO_REUSEADDR is set on the socket.)
This increases memory overhead as the packets need to be copied, however they are only copied per
matching socket. You can safely disable it if you don t plan to receive broadcast or multicast traffic on
more than one socket at a time.
Default value:
• Yes (enabled)
CONFIG_LWIP_SO_RCVBUF
Enable SO_RCVBUF option
Enabling this option allows checking for available data on a netconn.
Default value:
• No (disabled)
CONFIG_LWIP_NETBUF_RECVINFO
Enable IP_PKTINFO option
Enabling this option allows checking for the destination address of a received IPv4 Packet.
Default value:
• No (disabled)
CONFIG_LWIP_IP4_FRAG
Enable fragment outgoing IP4 packets
Enabling this option allows fragmenting outgoing IP4 packets if their size exceeds MTU.
Default value:
• Yes (enabled)
CONFIG_LWIP_IP6_FRAG
Enable fragment outgoing IP6 packets
Enabling this option allows fragmenting outgoing IP6 packets if their size exceeds MTU.
Default value:
• Yes (enabled)

CONFIG_LWIP_IP4_REASSEMBLY
Enable reassembly incoming fragmented IP4 packets
Enabling this option allows reassemblying incoming fragmented IP4 packets.
Default value:
• No (disabled)
CONFIG_LWIP_IP6_REASSEMBLY
Enable reassembly incoming fragmented IP6 packets
Enabling this option allows reassemblying incoming fragmented IP6 packets.
Default value:
• No (disabled)
CONFIG_LWIP_IP_FORWARD
Enable IP forwarding
Enabling this option allows packets forwarding across multiple interfaces.
Default value:
• No (disabled)
CONFIG_LWIP_IPV4_NAPT
Enable NAT (new/experimental)
Found in: Component config > LWIP > CONFIG_LWIP_IP_FORWARD
Enabling this option allows Network Address and Port Translation.
Default value:
• No (disabled) if CONFIG_LWIP_IP_FORWARD
CONFIG_LWIP_STATS
Enable LWIP statistics
Enabling this option allows LWIP statistics
Default value:
• No (disabled)
CONFIG_LWIP_ETHARP_TRUST_IP_MAC
Enable LWIP ARP trust
Enabling this option allows ARP table to be updated.
If this option is enabled, the incoming IP packets cause the ARP table to be updated with the source
MAC and IP addresses supplied in the packet. You may want to disable this if you do not trust LAN
peers to have the correct addresses, or as a limited approach to attempt to handle spoofing. If disabled,
lwIP will need to make a new ARP request if the peer is not already in the ARP table, adding a little

latency. The peer *is* in the ARP table if it requested our address before. Also notice that this slows
down input processing of every IP packet!
There are two known issues in real application if this feature is enabled: - The LAN peer may have bug
to update the ARP table after the ARP entry is aged out. If the ARP entry on the LAN peer is aged out
but failed to be updated, all IP packets sent from LWIP to the LAN peer will be dropped by LAN peer.
- The LAN peer may not be trustful, the LAN peer may send IP packets to LWIP with two different
MACs, but the same IP address. If this happens, the LWIP has problem to receive IP packets from LAN
peer.
So the recommendation is to disable this option. Here the LAN peer means the other side to which the
ESP station or soft-AP is connected.
Default value:
• No (disabled)
CONFIG_LWIP_ESP_GRATUITOUS_ARP
Send gratuitous ARP periodically
Enable this option allows to send gratuitous ARP periodically.
This option solve the compatibility issues.If the ARP table of the AP is old, and the AP doesn t send
ARP request to update it s ARP table, this will lead to the STA sending IP packet fail. Thus we send
gratuitous ARP periodically to let AP update it s ARP table.
Default value:
• Yes (enabled)
CONFIG_LWIP_GARP_TMR_INTERVAL
GARP timer interval(seconds)
Found in: Component config > LWIP > CONFIG_LWIP_ESP_GRATUITOUS_ARP
Set the timer interval for gratuitous ARP. The default value is 60s
Default value:
• 60
CONFIG_LWIP_TCPIP_RECVMBOX_SIZE
TCPIP task receive mail box size
Set TCPIP task receive mail box size. Generally bigger value means higher throughput but more memory.
The value should be bigger than UDP/TCP mail box size.
Range:
Default value:
• 32
CONFIG_LWIP_DHCP_DOES_ARP_CHECK
DHCP: Perform ARP check on any offered address
Enabling this option performs a check (via ARP request) if the offered IP address is not already in use
by another host on the network.

Default value:
• Yes (enabled)
CONFIG_LWIP_DHCP_DISABLE_CLIENT_ID
DHCP: Disable Use of HW address as client identification
This option could be used to disable DHCP client identification with its MAC address. (Client id is used
by DHCP servers to uniquely identify clients and are included in the DHCP packets as an option 61) Set
this option to y in order to exclude option 61 from DHCP packets.
Default value:
• No (disabled)
CONFIG_LWIP_DHCP_DISABLE_VENDOR_CLASS_ID
DHCP: Disable Use of vendor class identification
This option could be used to disable DHCP client vendor class identification. Set this option to y in
order to exclude option 60 from DHCP packets.
Default value:
• Yes (enabled)
CONFIG_LWIP_DHCP_RESTORE_LAST_IP
DHCP: Restore last IP obtained from DHCP server
When this option is enabled, DHCP client tries to re-obtain last valid IP address obtained from DHCP
server. Last valid DHCP configuration is stored in nvs and restored after reset/power-up. If IP is still
available, there is no need for sending discovery message to DHCP server and save some time.
Default value:
• No (disabled)
CONFIG_LWIP_DHCP_OPTIONS_LEN
DHCP total option length
Set total length of outgoing DHCP option msg. Generally bigger value means it can carry more options
and values. If your code meets LWIP_ASSERT due to option value is too long. Please increase the
LWIP_DHCP_OPTIONS_LEN value.
Range:
• from 68 to 255
Default value:
• 68
DHCP server Contains:

• CONFIG_LWIP_DHCPS

CONFIG_LWIP_DHCPS
DHCPS: Enable IPv4 Dynamic Host Configuration Protocol Server (DHCPS)
Found in: Component config > LWIP > DHCP server
Enabling this option allows the device to run the DHCP server (to dynamically assign IPv4 addresses to
clients).
Default value:
• Yes (enabled)
CONFIG_LWIP_DHCPS_LEASE_UNIT
Multiplier for lease time, in seconds
Found in: Component config > LWIP > DHCP server > CONFIG_LWIP_DHCPS
The DHCP server is calculating lease time multiplying the sent and received times by this number of
seconds per unit. The default is 60, that equals one minute.
Range:
• from 1 to 3600
Default value:
• 60
CONFIG_LWIP_DHCPS_MAX_STATION_NUM
Maximum number of stations
Found in: Component config > LWIP > DHCP server > CONFIG_LWIP_DHCPS
The maximum number of DHCP clients that are connected to the server. After this number is exceeded,
DHCP server removes of the oldest device from it s address pool, without notification.
Range:
• from 1 to 64
Default value:
• 8
CONFIG_LWIP_AUTOIP
Enable IPV4 Link-Local Addressing (AUTOIP)
Enabling this option allows the device to self-assign an address in the 169.256/16 range if none is assigned
statically or via DHCP.
See RFC 3927.
Default value:
• No (disabled)
Contains:
• CONFIG_LWIP_AUTOIP_TRIES
• CONFIG_LWIP_AUTOIP_MAX_CONFLICTS
• CONFIG_LWIP_AUTOIP_RATE_LIMIT_INTERVAL

CONFIG_LWIP_AUTOIP_TRIES
DHCP Probes before self-assigning IPv4 LL address
Found in: Component config > LWIP > CONFIG_LWIP_AUTOIP
DHCP client will send this many probes before self-assigning a link local address.
From LWIP help: This can be set as low as 1 to get an AutoIP address very quickly, but you should
be prepared to handle a changing IP address when DHCP overrides AutoIP. (In the case of ESP-IDF,
this means multiple SYSTEM_EVENT_STA_GOT_IP events.)
Range:
• from 1 to 100 if CONFIG_LWIP_AUTOIP
Default value:
• 2 if CONFIG_LWIP_AUTOIP
CONFIG_LWIP_AUTOIP_MAX_CONFLICTS
Max IP conflicts before rate limiting
If the AUTOIP functionality detects this many IP conflicts while self-assigning an address, it will go into
a rate limited mode.
Range:
Default value:
CONFIG_LWIP_AUTOIP_RATE_LIMIT_INTERVAL
Rate limited interval (seconds)
If rate limiting self-assignment requests, wait this long between each request.
Range:
Default value:
CONFIG_LWIP_IPV6
Enable IPv6
Enable IPv6 function. If not use IPv6 function, set this option to n. If disabling LWIP_IPV6 then some
other components (coap and asio) will no longer be available.
Default value:
• Yes (enabled)
CONFIG_LWIP_IPV6_AUTOCONFIG
Enable IPV6 stateless address autoconfiguration (SLAAC)
Found in: Component config > LWIP > CONFIG_LWIP_IPV6
Enabling this option allows the devices to IPV6 stateless address autoconfiguration (SLAAC).
See RFC 4862.

Default value:
• No (disabled)
CONFIG_LWIP_IPV6_NUM_ADDRESSES
Number of IPv6 addresses on each network interface
The maximum number of IPv6 addresses on each interface. Any additional addresses will be discarded.
Default value:
• 3
CONFIG_LWIP_IPV6_FORWARD
Enable IPv6 forwarding between interfaces
Forwarding IPv6 packets between interfaces is only required when acting as a router.
Default value:
• No (disabled)
CONFIG_LWIP_IPV6_RDNSS_MAX_DNS_SERVERS
Use IPv6 Router Advertisement Recursive DNS Server Option
Use IPv6 Router Advertisement Recursive DNS Server Option (as per RFC 6106) to copy a defined
maximum number of DNS servers to the DNS module. Set this option to a number of desired DNS
servers advertised in the RA protocol. This feature is disabled when set to 0.
Default value:
• 0 if CONFIG_LWIP_IPV6_AUTOCONFIG
CONFIG_LWIP_IPV6_DHCP6
Enable DHCPv6 stateless address autoconfiguration
Enable DHCPv6 for IPv6 stateless address autoconfiguration. Note that the dhcpv6 client has to be
started using dhcp6_enable_stateless(netif); Note that the stateful address autoconfiguration is not sup-
ported.
Default value:
• No (disabled) if CONFIG_LWIP_IPV6_AUTOCONFIG
CONFIG_LWIP_NETIF_STATUS_CALLBACK
Enable status callback for network interfaces
Enable callbacks when the network interface is up/down and addresses are changed.
Default value:
• No (disabled)

CONFIG_LWIP_NETIF_LOOPBACK
Support per-interface loopback
Enabling this option means that if a packet is sent with a destination address equal to the interface s
own IP address, it will loop back and be received by this interface.
Default value:
• Yes (enabled)
Contains:
• CONFIG_LWIP_LOOPBACK_MAX_PBUFS
CONFIG_LWIP_LOOPBACK_MAX_PBUFS
Max queued loopback packets per interface
Found in: Component config > LWIP > CONFIG_LWIP_NETIF_LOOPBACK
Configure the maximum number of packets which can be queued for loopback on a given interface.
Reducing this number may cause packets to be dropped, but will avoid filling memory with queued
packet data.
Range:
• from 0 to 16
Default value:
• 8
TCP Contains:
• CONFIG_LWIP_TCP_WND_DEFAULT
• CONFIG_LWIP_TCP_SND_BUF_DEFAULT
• CONFIG_LWIP_TCP_RECVMBOX_SIZE
• CONFIG_LWIP_TCP_RTO_TIME
• CONFIG_LWIP_TCP_KEEP_CONNECTION_WHEN_IP_CHANGES
• CONFIG_LWIP_MAX_ACTIVE_TCP
• CONFIG_LWIP_MAX_LISTENING_TCP
• CONFIG_LWIP_TCP_MAXRTX
• CONFIG_LWIP_TCP_SYNMAXRTX
• CONFIG_LWIP_TCP_MSL
• CONFIG_LWIP_TCP_MSS
• CONFIG_LWIP_TCP_OVERSIZE
• CONFIG_LWIP_TCP_QUEUE_OOSEQ
• CONFIG_LWIP_TCP_SACK_OUT
• CONFIG_LWIP_WND_SCALE
• CONFIG_LWIP_TCP_HIGH_SPEED_RETRANSMISSION
• CONFIG_LWIP_TCP_TMR_INTERVAL
CONFIG_LWIP_MAX_ACTIVE_TCP
Maximum active TCP Connections
Found in: Component config > LWIP > TCP
The maximum number of simultaneously active TCP connections. The practical maximum limit is
determined by available heap memory at runtime.
Changing this value by itself does not substantially change the memory usage of LWIP, except for pre-
venting new TCP connections after the limit is reached.
Range:

• from 1 to 1024
Default value:
• 16
CONFIG_LWIP_MAX_LISTENING_TCP
Maximum listening TCP Connections
The maximum number of simultaneously listening TCP connections. The practical maximum limit is
determined by available heap memory at runtime.
Changing this value by itself does not substantially change the memory usage of LWIP, except for pre-
venting new listening TCP connections after the limit is reached.
Range:
• from 1 to 1024
Default value:
• 16
CONFIG_LWIP_TCP_HIGH_SPEED_RETRANSMISSION
TCP high speed retransmissions
Speed up the TCP retransmission interval. If disabled, it is recommended to change the number of SYN
retransmissions to 6, and TCP initial rto time to 3000.
Default value:
• Yes (enabled)
CONFIG_LWIP_TCP_MAXRTX
Maximum number of retransmissions of data segments
Set maximum number of retransmissions of data segments.
Range:
• from 3 to 12
Default value:
• 12
CONFIG_LWIP_TCP_SYNMAXRTX
Maximum number of retransmissions of SYN segments
Set maximum number of retransmissions of SYN segments.
Range:
• from 3 to 12
Default value:
• 6
• 12

CONFIG_LWIP_TCP_MSS
Maximum Segment Size (MSS)
Set maximum segment size for TCP transmission.
Can be set lower to save RAM, the default value 1460(ipv4)/1440(ipv6) will give best throughput. IPv4
TCP_MSS Range: 576 <= TCP_MSS <= 1460 IPv6 TCP_MSS Range: 1220<= TCP_mSS <= 1440
Range:
• from 536 to 1460
Default value:
• 1440
CONFIG_LWIP_TCP_TMR_INTERVAL
TCP timer interval(ms)
Set TCP timer interval in milliseconds.
Can be used to speed connections on bad networks. A lower value will redeliver unacked packets faster.
Default value:
• 250
CONFIG_LWIP_TCP_MSL
Maximum segment lifetime (MSL)
Set maximum segment lifetime in in milliseconds.
Default value:
• 60000
CONFIG_LWIP_TCP_SND_BUF_DEFAULT
Default send buffer size
Set default send buffer size for new TCP sockets.
Per-socket send buffer size can be changed at runtime with lwip_setsockopt(s, TCP_SNDBUF, ).
This value must be at least 2x the MSS size, and the default is 4x the default MSS size.
Setting a smaller default SNDBUF size can save some RAM, but will decrease performance.
Range:
Default value:
• 5744
CONFIG_LWIP_TCP_WND_DEFAULT
Default receive window size
Set default TCP receive window size for new TCP sockets.

Per-socket receive window size can be changed at runtime with lwip_setsockopt(s, TCP_WINDOW,
).
Setting a smaller default receive window size can save some RAM, but will significantly decrease per-
formance.
Range:
Default value:
• 5744
CONFIG_LWIP_TCP_RECVMBOX_SIZE
Default TCP receive mail box size
Set TCP receive mail box size. Generally bigger value means higher throughput but more
memory. The recommended value is: LWIP_TCP_WND_DEFAULT/TCP_MSS + 2, e.g. if
LWIP_TCP_WND_DEFAULT=14360, TCP_MSS=1436, then the recommended receive mail box
size is (14360/1436 + 2) = 12.
TCP receive mail box is a per socket mail box, when the application receives packets from TCP
socket, LWIP core firstly posts the packets to TCP receive mail box and the application then fetches
the packets from mail box. It means LWIP can caches maximum LWIP_TCP_RECCVMBOX_SIZE
packets for each TCP socket, so the maximum possible cached TCP packets for all TCP sockets is
LWIP_TCP_RECCVMBOX_SIZE multiples the maximum TCP socket number. In other words, the
bigger LWIP_TCP_RECVMBOX_SIZE means more memory. On the other hand, if the receiv mail
box is too small, the mail box may be full. If the mail box is full, the LWIP drops the packets. So
generally we need to make sure the TCP receive mail box is big enough to avoid packet drop between
LWIP core and application.
Range:
Default value:
• 6
CONFIG_LWIP_TCP_QUEUE_OOSEQ
Queue incoming out-of-order segments
Queue incoming out-of-order segments for later use.
Disable this option to save some RAM during TCP sessions, at the expense of increased retransmissions
if segments arrive out of order.
Default value:
• Yes (enabled)
CONFIG_LWIP_TCP_SACK_OUT
Support sending selective acknowledgements
TCP will support sending selective acknowledgements (SACKs).
Default value:
• No (disabled)

CONFIG_LWIP_TCP_KEEP_CONNECTION_WHEN_IP_CHANGES
Keep TCP connections when IP changed
This option is enabled when the following scenario happen: network dropped and reconnected, IP
changes is like: 192.168.0.2->0.0.0.0->192.168.0.2
Disable this option to keep consistent with the original LWIP code behavior.
Default value:
• No (disabled)
CONFIG_LWIP_TCP_OVERSIZE
Pre-allocate transmit PBUF size
Allows enabling oversize allocation of TCP transmission pbufs ahead of time, which can reduce the
length of pbuf chains used for transmission.
This will not make a difference to sockets where Nagle s algorithm is disabled.
Default value of MSS is fine for most applications, 25% MSS may save some RAM when only trans-
mitting small amounts of data. Disabled will have worst performance and fragmentation characteristics,
but uses least RAM overall.
Available options:
• MSS (LWIP_TCP_OVERSIZE_MSS)
• 25% MSS (LWIP_TCP_OVERSIZE_QUARTER_MSS)
• Disabled (LWIP_TCP_OVERSIZE_DISABLE)
CONFIG_LWIP_WND_SCALE
Support TCP window scale
Enable this feature to support TCP window scaling.
Default value:
• No (disabled) if CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP
CONFIG_LWIP_TCP_RCV_SCALE
Set TCP receiving window scaling factor
Found in: Component config > LWIP > TCP > CONFIG_LWIP_WND_SCALE
Enable this feature to support TCP window scaling.
Range:
Default value:
• 0 if CONFIG_LWIP_WND_SCALE
CONFIG_LWIP_TCP_RTO_TIME
Default TCP rto time
Set default TCP rto time for a reasonable initial rto. In bad network environment, recommend set value
of rto time to 1500.

Default value:
• 3000
• 1500
UDP Contains:
• CONFIG_LWIP_UDP_RECVMBOX_SIZE
• CONFIG_LWIP_MAX_UDP_PCBS
CONFIG_LWIP_MAX_UDP_PCBS
Maximum active UDP control blocks
Found in: Component config > LWIP > UDP
The maximum number of active UDP connections (ie UDP sockets sending/receiving data). The
practical maximum limit is determined by available heap memory at runtime.
Range:
• from 1 to 1024
Default value:
• 16
CONFIG_LWIP_UDP_RECVMBOX_SIZE
Default UDP receive mail box size
Found in: Component config > LWIP > UDP
Set UDP receive mail box size. The recommended value is 6.
UDP receive mail box is a per socket mail box, when the application receives packets from UDP
socket, LWIP core firstly posts the packets to UDP receive mail box and the application then fetches
the packets from mail box. It means LWIP can caches maximum UDP_RECCVMBOX_SIZE pack-
ets for each UDP socket, so the maximum possible cached UDP packets for all UDP sockets is
UDP_RECCVMBOX_SIZE multiples the maximum UDP socket number. In other words, the big-
ger UDP_RECVMBOX_SIZE means more memory. On the other hand, if the receiv mail box is too
small, the mail box may be full. If the mail box is full, the LWIP drops the packets. So generally we
need to make sure the UDP receive mail box is big enough to avoid packet drop between LWIP core
and application.
Range:
• from 6 to 64
Default value:
• 6
Checksums Contains:
• CONFIG_LWIP_CHECKSUM_CHECK_ICMP
• CONFIG_LWIP_CHECKSUM_CHECK_IP
• CONFIG_LWIP_CHECKSUM_CHECK_UDP
CONFIG_LWIP_CHECKSUM_CHECK_IP
Enable LWIP IP checksums
Found in: Component config > LWIP > Checksums
Enable checksum checking for received IP messages
Default value:
• No (disabled)

CONFIG_LWIP_CHECKSUM_CHECK_UDP
Enable LWIP UDP checksums
Enable checksum checking for received UDP messages
Default value:
• No (disabled)
CONFIG_LWIP_CHECKSUM_CHECK_ICMP
Enable LWIP ICMP checksums
Enable checksum checking for received ICMP messages
Default value:
• Yes (enabled)
CONFIG_LWIP_TCPIP_TASK_STACK_SIZE
TCP/IP Task Stack Size
Configure TCP/IP task stack size, used by LWIP to process multi-threaded TCP/IP operations. Setting
this stack too small will result in stack overflow crashes.
Range:
• from 2048 to 65536
Default value:
• 3072
CONFIG_LWIP_TCPIP_TASK_AFFINITY
TCP/IP task affinity
Allows setting LwIP tasks affinity, i.e. whether the task is pinned to CPU0, pinned to CPU1, or allowed
to run on any CPU. Currently this applies to TCP/IP task and Ping task.
Available options:
• No affinity (LWIP_TCPIP_TASK_AFFINITY_NO_AFFINITY)
• CPU0 (LWIP_TCPIP_TASK_AFFINITY_CPU0)
• CPU1 (LWIP_TCPIP_TASK_AFFINITY_CPU1)
CONFIG_LWIP_PPP_SUPPORT
Enable PPP support (new/experimental)
Enable PPP stack. Now only PPP over serial is possible.
PPP over serial support is experimental and unsupported.
Default value:
• No (disabled)
Contains:
• CONFIG_LWIP_PPP_ENABLE_IPV6

CONFIG_LWIP_PPP_ENABLE_IPV6
Enable IPV6 support for PPP connections (IPV6CP)
Found in: Component config > LWIP > CONFIG_LWIP_PPP_SUPPORT
Enable IPV6 support in PPP for the local link between the DTE (processor) and DCE (modem). There
are some modems which do not support the IPV6 addressing in the local link. If they are requested for
IPV6CP negotiation, they may time out. This would in turn fail the configuration for the whole link. If
your modem is not responding correctly to PPP Phase Network, try to disable IPV6 support.
Default value:
• Yes (enabled) if CONFIG_LWIP_PPP_SUPPORT && CONFIG_LWIP_IPV6
CONFIG_LWIP_IPV6_MEMP_NUM_ND6_QUEUE
Max number of IPv6 packets to queue during MAC resolution
Config max number of IPv6 packets to queue during MAC resolution.
Range:
• from 3 to 20
Default value:
• 3
CONFIG_LWIP_IPV6_ND6_NUM_NEIGHBORS
Max number of entries in IPv6 neighbor cache
Config max number of entries in IPv6 neighbor cache
Range:
• from 3 to 10
Default value:
• 5
CONFIG_LWIP_PPP_NOTIFY_PHASE_SUPPORT
Enable Notify Phase Callback
Enable to set a callback which is called on change of the internal PPP state machine.
Default value:
• No (disabled) if CONFIG_LWIP_PPP_SUPPORT
CONFIG_LWIP_PPP_PAP_SUPPORT
Enable PAP support
Enable Password Authentication Protocol (PAP) support
Default value:

CONFIG_LWIP_PPP_CHAP_SUPPORT
Enable CHAP support
Enable Challenge Handshake Authentication Protocol (CHAP) support
Default value:
CONFIG_LWIP_PPP_MSCHAP_SUPPORT
Enable MSCHAP support
Enable Microsoft version of the Challenge-Handshake Authentication Protocol (MSCHAP) support
Default value:
CONFIG_LWIP_PPP_MPPE_SUPPORT
Enable MPPE support
Enable Microsoft Point-to-Point Encryption (MPPE) support
Default value:
CONFIG_LWIP_ENABLE_LCP_ECHO
Enable LCP ECHO
Enable LCP echo keepalive requests
Default value:
CONFIG_LWIP_LCP_ECHOINTERVAL
Echo interval (s)
Found in: Component config > LWIP > CONFIG_LWIP_ENABLE_LCP_ECHO
Interval in seconds between keepalive LCP echo requests, 0 to disable.
Range:
• from 0 to 1000000 if CONFIG_LWIP_ENABLE_LCP_ECHO
Default value:
• 3 if CONFIG_LWIP_ENABLE_LCP_ECHO
CONFIG_LWIP_LCP_MAXECHOFAILS
Maximum echo failures
Found in: Component config > LWIP > CONFIG_LWIP_ENABLE_LCP_ECHO
Number of consecutive unanswered echo requests before failure is indicated.
Range:
• from 0 to 100000 if CONFIG_LWIP_ENABLE_LCP_ECHO

Default value:
• 3 if CONFIG_LWIP_ENABLE_LCP_ECHO
CONFIG_LWIP_PPP_DEBUG_ON
Enable PPP debug log output
Enable PPP debug log output
Default value:
CONFIG_LWIP_SLIP_SUPPORT
Enable SLIP support (new/experimental)
Enable SLIP stack. Now only SLIP over serial is possible.
SLIP over serial support is experimental and unsupported.
Default value:
• No (disabled)
Contains:
• CONFIG_LWIP_SLIP_DEBUG_ON
CONFIG_LWIP_SLIP_DEBUG_ON
Enable SLIP debug log output
Found in: Component config > LWIP > CONFIG_LWIP_SLIP_SUPPORT
Enable SLIP debug log output
Default value:
• No (disabled) if CONFIG_LWIP_SLIP_SUPPORT
ICMP Contains:
• CONFIG_LWIP_ICMP
• CONFIG_LWIP_BROADCAST_PING
• CONFIG_LWIP_MULTICAST_PING
CONFIG_LWIP_ICMP
ICMP: Enable ICMP
Found in: Component config > LWIP > ICMP
Enable ICMP module for check network stability
Default value:
• Yes (enabled)

CONFIG_LWIP_MULTICAST_PING
Respond to multicast pings
Default value:
• No (disabled)
CONFIG_LWIP_BROADCAST_PING
Respond to broadcast pings
Default value:
• No (disabled)
LWIP RAW API Contains:

• CONFIG_LWIP_MAX_RAW_PCBS
CONFIG_LWIP_MAX_RAW_PCBS
Maximum LWIP RAW PCBs
Found in: Component config > LWIP > LWIP RAW API
The maximum number of simultaneously active LWIP RAW protocol control blocks. The practical
maximum limit is determined by available heap memory at runtime.
Range:
• from 1 to 1024
Default value:
• 16
SNTP Contains:
• CONFIG_LWIP_SNTP_MAX_SERVERS
• CONFIG_LWIP_SNTP_UPDATE_DELAY
• CONFIG_LWIP_DHCP_GET_NTP_SRV
CONFIG_LWIP_SNTP_MAX_SERVERS
Maximum number of NTP servers
Found in: Component config > LWIP > SNTP
Set maximum number of NTP servers used by LwIP SNTP module. First argument of
sntp_setserver/sntp_setservername functions is limited to this value.
Range:
• from 1 to 16
Default value:
• 1
CONFIG_LWIP_DHCP_GET_NTP_SRV
Request NTP servers from DHCP

If enabled, LWIP will add NTP to Parameter-Request Option sent via DHCP-request. DHCP server
might reply with an NTP server address in option 42. SNTP callback for such replies should be set
accordingly (see sntp_servermode_dhcp() func.)
Default value:
• No (disabled)
CONFIG_LWIP_DHCP_MAX_NTP_SERVERS
Maximum number of NTP servers aquired via DHCP
Found in: Component config > LWIP > SNTP > CONFIG_LWIP_DHCP_GET_NTP_SRV
Set maximum number of NTP servers aquired via DHCP-offer. Should be less or equal to Maximum
number of NTP servers , any extra servers would be just ignored.
Range:
• from 1 to 16 if CONFIG_LWIP_DHCP_GET_NTP_SRV
Default value:
• 1 if CONFIG_LWIP_DHCP_GET_NTP_SRV
CONFIG_LWIP_SNTP_UPDATE_DELAY
Request interval to update time (ms)
This option allows you to set the time update period via SNTP. Default is 1 hour. Must not be below 15
seconds by specification. (SNTPv4 RFC 4330 enforces a minimum update time of 15 seconds).
Range:
• from 15000 to 4294967295
Default value:
• 3600000
CONFIG_LWIP_ESP_LWIP_ASSERT
Enable LWIP ASSERT checks
Enable this option keeps LWIP assertion checks enabled. It is recommended to keep this option enabled.
If asserts are disabled for the entire project, they are also disabled for LWIP and this option is ignored.
Default value:
• Yes (enabled) if COMPILER_OPTIMIZATION_ASSERTIONS_DISABLE
Hooks Contains:
• CONFIG_LWIP_HOOK_ND6_GET_GW
• CONFIG_LWIP_HOOK_IP6_ROUTE
• CONFIG_LWIP_HOOK_NETCONN_EXTERNAL_RESOLVE
• CONFIG_LWIP_HOOK_TCP_ISN
CONFIG_LWIP_HOOK_TCP_ISN
TCP ISN Hook
Found in: Component config > LWIP > Hooks
Enables to define a TCP ISN hook to randomize initial sequence number in TCP connection. The default
TCP ISN algorithm used in IDF (standardized in RFC 6528) produces ISN by combining an MD5 of
the new TCP id and a stable secret with the current time. This is because the lwIP implementation

(tcp_next_iss) is not very strong, as it does not take into consideration any platform specific entropy
source.
Set to LWIP_HOOK_TCP_ISN_CUSTOM to provide custom implementation. Set to
LWIP_HOOK_TCP_ISN_NONE to use lwIP implementation.
Available options:
• No hook declared (LWIP_HOOK_TCP_ISN_NONE)
• Default implementation (LWIP_HOOK_TCP_ISN_DEFAULT)
• Custom implementation (LWIP_HOOK_TCP_ISN_CUSTOM)
CONFIG_LWIP_HOOK_IP6_ROUTE
IPv6 route Hook
Enables custom IPv6 route hook. Setting this to default provides weak implementation stub that
could be overwritten in application code. Setting this to custom provides hook s declaration only
and expects the application to implement it.
Available options:
• No hook declared (LWIP_HOOK_IP6_ROUTE_NONE)
• Default (weak) implementation (LWIP_HOOK_IP6_ROUTE_DEFAULT)
• Custom implementation (LWIP_HOOK_IP6_ROUTE_CUSTOM)
CONFIG_LWIP_HOOK_ND6_GET_GW
IPv6 get gateway Hook
Enables custom IPv6 route hook. Setting this to default provides weak implementation stub that
Available options:
• No hook declared (LWIP_HOOK_ND6_GET_GW_NONE)
• Default (weak) implementation (LWIP_HOOK_ND6_GET_GW_DEFAULT)
• Custom implementation (LWIP_HOOK_ND6_GET_GW_CUSTOM)
CONFIG_LWIP_HOOK_NETCONN_EXTERNAL_RESOLVE
Netconn external resolve Hook
Enables custom DNS resolve hook. Setting this to default provides weak implementation stub that
Available options:
• No hook declared (LWIP_HOOK_NETCONN_EXT_RESOLVE_NONE)
• Default (weak) implementation (LWIP_HOOK_NETCONN_EXT_RESOLVE_DEFAULT)
• Custom implementation (LWIP_HOOK_NETCONN_EXT_RESOLVE_CUSTOM)
CONFIG_LWIP_DEBUG
Enable LWIP Debug
Enabling this option allows different kinds of lwIP debug output.

All lwIP debug features increase the size of the final binary.
Default value:
• No (disabled)
Contains:
• CONFIG_LWIP_API_LIB_DEBUG
• CONFIG_LWIP_DHCP_DEBUG
• CONFIG_LWIP_DHCP_STATE_DEBUG
• CONFIG_LWIP_ETHARP_DEBUG
• CONFIG_LWIP_ICMP_DEBUG
• CONFIG_LWIP_ICMP6_DEBUG
• CONFIG_LWIP_IP_DEBUG
• CONFIG_LWIP_IP6_DEBUG
• CONFIG_LWIP_NETIF_DEBUG
• CONFIG_LWIP_PBUF_DEBUG
• CONFIG_LWIP_SNTP_DEBUG
• CONFIG_LWIP_SOCKETS_DEBUG
• CONFIG_LWIP_TCP_DEBUG
CONFIG_LWIP_NETIF_DEBUG
Enable netif debug messages
Found in: Component config > LWIP > CONFIG_LWIP_DEBUG
Default value:
• No (disabled) if CONFIG_LWIP_DEBUG
CONFIG_LWIP_PBUF_DEBUG
Enable pbuf debug messages
Default value:
CONFIG_LWIP_ETHARP_DEBUG
Enable etharp debug messages
Default value:
CONFIG_LWIP_API_LIB_DEBUG
Enable api lib debug messages
Default value:
CONFIG_LWIP_SOCKETS_DEBUG
Enable socket debug messages
Default value:

CONFIG_LWIP_IP_DEBUG
Enable IP debug messages
Default value:
CONFIG_LWIP_ICMP_DEBUG
Enable ICMP debug messages
Default value:
• No (disabled) if CONFIG_LWIP_DEBUG && CONFIG_LWIP_ICMP
CONFIG_LWIP_DHCP_STATE_DEBUG
Enable DHCP state tracking
Default value:
CONFIG_LWIP_DHCP_DEBUG
Enable DHCP debug messages
Default value:
CONFIG_LWIP_IP6_DEBUG
Enable IP6 debug messages
Default value:
CONFIG_LWIP_ICMP6_DEBUG
Enable ICMP6 debug messages
Default value:
CONFIG_LWIP_TCP_DEBUG
Enable TCP debug messages
Default value:

CONFIG_LWIP_SNTP_DEBUG
Enable SNTP debug messages
Default value:
mbedTLS Contains:
• CONFIG_MBEDTLS_ASYMMETRIC_CONTENT_LEN
• Certificate Bundle
• Certificates
• CONFIG_MBEDTLS_CHACHA20_C
• CONFIG_MBEDTLS_DHM_C
• CONFIG_MBEDTLS_ECP_C
• CONFIG_MBEDTLS_ECDH_C
• CONFIG_MBEDTLS_ECJPAKE_C
• CONFIG_MBEDTLS_ECP_DP_BP256R1_ENABLED
• CONFIG_MBEDTLS_CMAC_C
• CONFIG_MBEDTLS_ECP_DP_CURVE25519_ENABLED
• CONFIG_MBEDTLS_ECDSA_DETERMINISTIC
• CONFIG_MBEDTLS_HARDWARE_AES
• CONFIG_MBEDTLS_ATCA_HW_ECDSA_SIGN
• CONFIG_MBEDTLS_ATCA_HW_ECDSA_VERIFY
• CONFIG_MBEDTLS_HARDWARE_MPI
• CONFIG_MBEDTLS_HARDWARE_SHA
• CONFIG_MBEDTLS_DEBUG
• CONFIG_MBEDTLS_ECP_RESTARTABLE
• CONFIG_MBEDTLS_HAVE_TIME
• CONFIG_MBEDTLS_RIPEMD160_C
• CONFIG_MBEDTLS_ECP_DP_SECP192K1_ENABLED
• CONFIG_MBEDTLS_ECP_DP_SECP192R1_ENABLED
• CONFIG_MBEDTLS_SHA512_C
• CONFIG_MBEDTLS_THREADING_C
• CONFIG_MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE
• CONFIG_MBEDTLS_X509_CHECK_KEY_USAGE
• CONFIG_MBEDTLS_LARGE_KEY_SOFTWARE_MPI
• CONFIG_MBEDTLS_HKDF_C
• CONFIG_MBEDTLS_SSL_PROTO_SSL3
• CONFIG_MBEDTLS_MEM_ALLOC_MODE
• CONFIG_MBEDTLS_ECP_NIST_OPTIM
• CONFIG_MBEDTLS_POLY1305_C
• CONFIG_MBEDTLS_SECURITY_RISKS
• CONFIG_MBEDTLS_SSL_ALPN
• CONFIG_MBEDTLS_SSL_PROTO_DTLS
• CONFIG_MBEDTLS_SSL_PROTO_GMTSSL1_1
• CONFIG_MBEDTLS_SSL_PROTO_TLS1
• CONFIG_MBEDTLS_SSL_PROTO_TLS1_1
• CONFIG_MBEDTLS_SSL_PROTO_TLS1_2

• CONFIG_MBEDTLS_SSL_RENEGOTIATION
• Symmetric Ciphers
• TLS Key Exchange Methods
• CONFIG_MBEDTLS_SSL_MAX_CONTENT_LEN
• CONFIG_MBEDTLS_TLS_MODE
• CONFIG_MBEDTLS_CLIENT_SSL_SESSION_TICKETS
• CONFIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS
• CONFIG_MBEDTLS_ROM_MD5
• CONFIG_MBEDTLS_DYNAMIC_BUFFER
CONFIG_MBEDTLS_MEM_ALLOC_MODE
Found in: Component config > mbedTLS
Allocation strategy for mbedTLS, essentially provides ability to allocate all required dynamic allocations
from,
• Custom allocation mode, by overwriting calloc()/free() using mbedtls_platform_set_calloc_free()
function
Recommended mode here is always internal (*), since that is most preferred from security perspective.
But if application requirement does not allow sufficient free internal memory then alternate mode can
be selected.
(*) In case of ESP32-S2/ESP32-S3, hardware allows encryption of external SPIRAM contents provided
hardware flash encryption feature is enabled. In that case, using external SPIRAM allocation strategy is
also safe choice from security perspective.
Available options:
• Internal memory (MBEDTLS_INTERNAL_MEM_ALLOC)
• External SPIRAM (MBEDTLS_EXTERNAL_MEM_ALLOC)
• Default alloc mode (MBEDTLS_DEFAULT_MEM_ALLOC)
• Custom alloc mode (MBEDTLS_CUSTOM_MEM_ALLOC)
• Internal IRAM (MBEDTLS_IRAM_8BIT_MEM_ALLOC)
Allows to use IRAM memory region as 8bit accessible region.
TLS input and output buffers will be allocated in IRAM section which is 32bit aligned mem-
ory. Every unaligned (8bit or 16bit) access will result in an exception and incur penalty of
certain clock cycles per unaligned read/write.
CONFIG_MBEDTLS_SSL_MAX_CONTENT_LEN
TLS maximum message content length
Maximum TLS message length (in bytes) supported by mbedTLS.
16384 is the default and this value is required to comply fully with TLS standards.
However you can set a lower value in order to save RAM. This is safe if the other end of the connection
supports Maximum Fragment Length Negotiation Extension (max_fragment_length, see RFC6066) or
you know for certain that it will never send a message longer than a certain number of bytes.
If the value is set too low, symptoms are a failed TLS handshake or a return value of
MBEDTLS_ERR_SSL_INVALID_RECORD (-0x7200).
Range:
• from 512 to 16384

Default value:
• 16384
CONFIG_MBEDTLS_ASYMMETRIC_CONTENT_LEN
Asymmetric in/out fragment length
If enabled, this option allows customizing TLS in/out fragment length in asymmetric way. Please note
that enabling this with default values saves 12KB of dynamic memory per TLS connection.
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_SSL_IN_CONTENT_LEN
TLS maximum incoming fragment length
Found in: Component config > mbedTLS > CONFIG_MBEDTLS_ASYMMETRIC_CONTENT_LEN
This defines maximum incoming fragment length, overriding default maximum content length
(MBEDTLS_SSL_MAX_CONTENT_LEN).
Range:
• from 512 to 16384
Default value:
• 16384
CONFIG_MBEDTLS_SSL_OUT_CONTENT_LEN
TLS maximum outgoing fragment length
Found in: Component config > mbedTLS > CONFIG_MBEDTLS_ASYMMETRIC_CONTENT_LEN
This defines maximum outgoing fragment length, overriding default maximum content length
(MBEDTLS_SSL_MAX_CONTENT_LEN).
Range:
• from 512 to 16384
Default value:
• 4096
CONFIG_MBEDTLS_DYNAMIC_BUFFER
Using dynamic TX/RX buffer
Using dynamic TX/RX buffer. After enabling this option, mbedTLS will allocate TX buffer when need
to send data and then free it if all data is sent, allocate RX buffer when need to receive data and then
free it when all data is used or read by upper layer.
By default, when SSL is initialized, mbedTLS also allocate TX and RX buffer with the default value
of MBEDTLS_SSL_OUT_CONTENT_LEN or MBEDTLS_SSL_IN_CONTENT_LEN , so
to save more heap, users can set the options to be an appropriate value.
Default value:
• No (disabled)

CONFIG_MBEDTLS_DYNAMIC_FREE_PEER_CERT
Free SSL peer certificate after its usage
Found in: Component config > mbedTLS > CONFIG_MBEDTLS_DYNAMIC_BUFFER
Free peer certificate after its usage in handshake process.
Default value:
• No (disabled) if CONFIG_MBEDTLS_DYNAMIC_BUFFER
CONFIG_MBEDTLS_DYNAMIC_FREE_CONFIG_DATA
Free private key and DHM data after its usage
Found in: Component config > mbedTLS > CONFIG_MBEDTLS_DYNAMIC_BUFFER
Free private key and DHM data after its usage in handshake process.
The option will decrease heap cost when handshake, but also lead to problem:
Becasue all certificate, private key and DHM data are freed so users should register certificate and private
key to ssl config object again.
Default value:
• No (disabled) if CONFIG_MBEDTLS_DYNAMIC_BUFFER
CONFIG_MBEDTLS_DYNAMIC_FREE_CA_CERT
Free SSL ca certificate after its usage
Found in: Component config > mbedTLS > CONFIG_MBEDTLS_DYNAMIC_BUFFER > CON-
FIG_MBEDTLS_DYNAMIC_FREE_CONFIG_DATA
Free ca certificate after its usage in the handshake process. This option will decrease the heap footprint
for the TLS handshake, but may lead to a problem: If the respective ssl object needs to perform the TLS
handshake again, the ca certificate should once again be registered to the ssl object.
Default value:
• Yes (enabled) if CONFIG_MBEDTLS_DYNAMIC_FREE_CONFIG_DATA
CONFIG_MBEDTLS_DEBUG
Enable mbedTLS debugging
Enable mbedTLS debugging functions at compile time.
If this option is enabled, you can include mbedtls/esp_debug.h and call
mbedtls_esp_enable_debug_log() at runtime in order to enable mbedTLS debug output via the
ESP log mechanism.
Default value:
• No (disabled)
CONFIG_MBEDTLS_DEBUG_LEVEL
Set mbedTLS debugging level
Found in: Component config > mbedTLS > CONFIG_MBEDTLS_DEBUG
Set mbedTLS debugging level
Available options:
• Warning (MBEDTLS_DEBUG_LEVEL_WARN)
• Info (MBEDTLS_DEBUG_LEVEL_INFO)

• Debug (MBEDTLS_DEBUG_LEVEL_DEBUG)
• Verbose (MBEDTLS_DEBUG_LEVEL_VERBOSE)
Certificate Bundle Contains:

• CONFIG_MBEDTLS_CERTIFICATE_BUNDLE
CONFIG_MBEDTLS_CERTIFICATE_BUNDLE
Enable trusted root certificate bundle
Found in: Component config > mbedTLS > Certificate Bundle
Enable support for large number of default root certificates
When enabled this option allows user to store default as well as customer specific root certificates in
compressed format rather than storing full certificate. For the root certificates the public key and the
subject name will be stored.
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_DEFAULT_CERTIFICATE_BUNDLE
Default certificate bundle options
Found in: Component config > mbedTLS > Certificate Bundle > CON-
FIG_MBEDTLS_CERTIFICATE_BUNDLE
Available options:
• Use the full default certificate bundle (MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_FULL)
• Use only the most common certificates from the default bundles
(MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_CMN)
Use only the most common certificates from the default bundles, reducing the size with 50%,
while still having around 99% coverage.
• Do not use the default certificate bundle (MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_NONE)
CONFIG_MBEDTLS_CUSTOM_CERTIFICATE_BUNDLE
Add custom certificates to the default bundle
FIG_MBEDTLS_CERTIFICATE_BUNDLE
Default value:
• No (disabled)
CONFIG_MBEDTLS_CUSTOM_CERTIFICATE_BUNDLE_PATH
Custom certificate bundle path
FIG_MBEDTLS_CERTIFICATE_BUNDLE > CONFIG_MBEDTLS_CUSTOM_CERTIFICATE_BUNDLE
Name of the custom certificate directory or file. This path is evaluated relative to the project root direc-
tory.

CONFIG_MBEDTLS_ECP_RESTARTABLE
Enable mbedTLS ecp restartable
Enable non-blocking ECC operations that can return early and be resumed.
Default value:
• No (disabled)
CONFIG_MBEDTLS_CMAC_C
Enable CMAC mode for block ciphers
Enable the CMAC (Cipher-based Message Authentication Code) mode for block ciphers.
Default value:
• No (disabled)
CONFIG_MBEDTLS_HARDWARE_AES
Enable hardware AES acceleration
Enable hardware accelerated AES encryption & decryption.
Note that if the ESP32 CPU is running at 240MHz, hardware AES does not offer any speed boost over
software AES.
Default value:
• Yes (enabled) if SPIRAM_CACHE_WORKAROUND_STRATEGY_DUPLDST
CONFIG_MBEDTLS_HARDWARE_MPI
Enable hardware MPI (bignum) acceleration
Enable hardware accelerated multiple precision integer operations.
Hardware accelerated multiplication, modulo multiplication, and modular exponentiation for up to 4096
bit results.
These operations are used by RSA.
Default value:
CONFIG_MBEDTLS_HARDWARE_SHA
Enable hardware SHA acceleration
Enable hardware accelerated SHA1, SHA256, SHA384 & SHA512 in mbedTLS.
Due to a hardware limitation, on the ESP32 hardware acceleration is only guaranteed if SHA digests
are calculated one at a time. If more than one SHA digest is calculated at the same time, one will be
calculated fully in hardware and the rest will be calculated (at least partially calculated) in software. This
happens automatically.
SHA hardware acceleration is faster than software in some situations but slower in others. You should
benchmark to find the best setting for you.

Default value:
CONFIG_MBEDTLS_ROM_MD5
Use MD5 implementation in ROM
Use ROM MD5 in mbedTLS.
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_ATCA_HW_ECDSA_SIGN
Enable hardware ECDSA sign acceleration when using ATECC608A
This option enables hardware acceleration for ECDSA sign function, only when using ATECC608A
cryptoauth chip (integrated with ESP32-WROOM-32SE)
Default value:
• No (disabled)
CONFIG_MBEDTLS_ATCA_HW_ECDSA_VERIFY
Enable hardware ECDSA verify acceleration when using ATECC608A
This option enables hardware acceleration for ECDSA sign function, only when using ATECC608A
cryptoauth chip (integrated with ESP32-WROOM-32SE)
Default value:
• No (disabled)
CONFIG_MBEDTLS_HAVE_TIME
Enable mbedtls time support
Enable use of time.h functions (time() and gmtime()) by mbedTLS.
This option doesn t require the system time to be correct, but enables functionality that requires relative
timekeeping - for example periodic expiry of TLS session tickets or session cache entries.
Disabling this option will save some firmware size, particularly if the rest of the firmware doesn t call
any standard timekeeeping functions.
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_HAVE_TIME_DATE
Enable mbedtls certificate expiry check
Found in: Component config > mbedTLS > CONFIG_MBEDTLS_HAVE_TIME
Enables X.509 certificate expiry checks in mbedTLS.
If this option is disabled (default) then X.509 certificate valid from and valid to timestamp fields
are ignored.

If this option is enabled, these fields are compared with the current system date and time. The time
is retrieved using the standard time() and gmtime() functions. If the certificate is not valid for the
current system time then verification will fail with code MBEDTLS_X509_BADCERT_FUTURE or
MBEDTLS_X509_BADCERT_EXPIRED.
Enabling this option requires adding functionality in the firmware to set the system clock to a valid
timestamp before using TLS. The recommended way to do this is via ESP-IDF s SNTP functionality,
but any method can be used.
In the case where only a small number of certificates are trusted by the device, please carefully consider
the tradeoffs of enabling this option. There may be undesired consequences, for example if all trusted
certificates expire while the device is offline and a TLS connection is required to update. Or if an issue
with the SNTP server means that the system time is invalid for an extended period after a reset.
Default value:
• No (disabled)
CONFIG_MBEDTLS_ECDSA_DETERMINISTIC
Enable deterministic ECDSA
Standard ECDSA is fragile in the sense that lack of entropy when signing may result in a compromise
of the long-term signing key.
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_SHA512_C
Enable the SHA-384 and SHA-512 cryptographic hash algorithms
Enable MBEDTLS_SHA512_C adds support for SHA-384 and SHA-512.
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_TLS_MODE
TLS Protocol Role
mbedTLS can be compiled with protocol support for the TLS server, TLS client, or both server and
client.
Reducing the number of TLS roles supported saves code size.
Available options:
• Server & Client (MBEDTLS_TLS_SERVER_AND_CLIENT)
• Server (MBEDTLS_TLS_SERVER_ONLY)
• Client (MBEDTLS_TLS_CLIENT_ONLY)
• None (MBEDTLS_TLS_DISABLED)
TLS Key Exchange Methods Contains:

• CONFIG_MBEDTLS_KEY_EXCHANGE_DHE_RSA
• CONFIG_MBEDTLS_KEY_EXCHANGE_ECJPAKE
• CONFIG_MBEDTLS_PSK_MODES
• CONFIG_MBEDTLS_KEY_EXCHANGE_RSA
• CONFIG_MBEDTLS_KEY_EXCHANGE_ELLIPTIC_CURVE

CONFIG_MBEDTLS_PSK_MODES
Enable pre-shared-key ciphersuites
Found in: Component config > mbedTLS > TLS Key Exchange Methods
Enable to show configuration for different types of pre-shared-key TLS authentatication methods.
Leaving this options disabled will save code size if they are not used.
Default value:
• No (disabled)
CONFIG_MBEDTLS_KEY_EXCHANGE_PSK
Enable PSK based ciphersuite modes
Found in: Component config > mbedTLS > TLS Key Exchange Methods > CON-
FIG_MBEDTLS_PSK_MODES
Enable to support symmetric key PSK (pre-shared-key) TLS key exchange modes.
Default value:
• No (disabled) if CONFIG_MBEDTLS_PSK_MODES
CONFIG_MBEDTLS_KEY_EXCHANGE_DHE_PSK
Enable DHE-PSK based ciphersuite modes
Enable to support Diffie-Hellman PSK (pre-shared-key) TLS authentication modes.
Default value:
• Yes (enabled) if CONFIG_MBEDTLS_PSK_MODES && CONFIG_MBEDTLS_DHM_C
CONFIG_MBEDTLS_KEY_EXCHANGE_ECDHE_PSK
Enable ECDHE-PSK based ciphersuite modes
Enable to support Elliptic-Curve-Diffie-Hellman PSK (pre-shared-key) TLS authentication modes.
Default value:
• Yes (enabled) if CONFIG_MBEDTLS_PSK_MODES && CONFIG_MBEDTLS_ECDH_C
CONFIG_MBEDTLS_KEY_EXCHANGE_RSA_PSK
Enable RSA-PSK based ciphersuite modes
Enable to support RSA PSK (pre-shared-key) TLS authentication modes.
Default value:
• Yes (enabled) if CONFIG_MBEDTLS_PSK_MODES

CONFIG_MBEDTLS_KEY_EXCHANGE_RSA
Enable RSA-only based ciphersuite modes
Enable to support ciphersuites with prefix TLS-RSA-WITH-
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_KEY_EXCHANGE_DHE_RSA
Enable DHE-RSA based ciphersuite modes
Enable to support ciphersuites with prefix TLS-DHE-RSA-WITH-
Default value:
• Yes (enabled) if CONFIG_MBEDTLS_DHM_C
CONFIG_MBEDTLS_KEY_EXCHANGE_ELLIPTIC_CURVE
Support Elliptic Curve based ciphersuites
Enable to show Elliptic Curve based ciphersuite mode options.
Disabling all Elliptic Curve ciphersuites saves code size and can give slightly faster TLS handshakes,
provided the server supports RSA-only ciphersuite modes.
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_KEY_EXCHANGE_ECDHE_RSA
Enable ECDHE-RSA based ciphersuite modes
FIG_MBEDTLS_KEY_EXCHANGE_ELLIPTIC_CURVE
Enable to support ciphersuites with prefix TLS-ECDHE-RSA-WITH-
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA
Enable ECDHE-ECDSA based ciphersuite modes
Default value:
• Yes (enabled)

CONFIG_MBEDTLS_KEY_EXCHANGE_ECDH_ECDSA
Enable ECDH-ECDSA based ciphersuite modes
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_KEY_EXCHANGE_ECDH_RSA
Enable ECDH-RSA based ciphersuite modes
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_KEY_EXCHANGE_ECJPAKE
Enable ECJPAKE based ciphersuite modes
Enable to support ciphersuites with prefix TLS-ECJPAKE-WITH-
Default value:
• No (disabled) if CONFIG_MBEDTLS_ECJPAKE_C && CON-
FIG_MBEDTLS_ECP_DP_SECP256R1_ENABLED
CONFIG_MBEDTLS_SSL_RENEGOTIATION
Support TLS renegotiation
The two main uses of renegotiation are (1) refresh keys on long-lived connections and (2) client authen-
tication after the initial handshake. If you don t need renegotiation, disabling it will save code size and
reduce the possibility of abuse/vulnerability.
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_SSL_PROTO_SSL3
Legacy SSL 3.0 support
Support the legacy SSL 3.0 protocol. Most servers will speak a newer TLS protocol these days.
Default value:
• No (disabled)

CONFIG_MBEDTLS_SSL_PROTO_TLS1
Support TLS 1.0 protocol
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_SSL_PROTO_TLS1_1
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_SSL_PROTO_TLS1_2
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_SSL_PROTO_GMTSSL1_1
Support GM/T SSL 1.1 protocol
Provisions for GM/T SSL 1.1 support
Default value:
• No (disabled)
CONFIG_MBEDTLS_SSL_PROTO_DTLS
Support DTLS protocol (all versions)
Requires TLS 1.1 to be enabled for DTLS 1.0 Requires TLS 1.2 to be enabled for DTLS 1.2
Default value:
• No (disabled)
CONFIG_MBEDTLS_SSL_ALPN
Support ALPN (Application Layer Protocol Negotiation)
Disabling this option will save some code size if it is not needed.
Default value:
• Yes (enabled)

CONFIG_MBEDTLS_CLIENT_SSL_SESSION_TICKETS
TLS: Client Support for RFC 5077 SSL session tickets
Client support for RFC 5077 session tickets. See mbedTLS documentation for more details. Disabling
this option will save some code size.
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_X509_CHECK_KEY_USAGE
Enable verification of the keyUsage extension
Disabling this avoids problems with mis-issued and/or misused (intermediate) CA and leaf certificates.
Depending on your PKI use, disabling this can be a security risk.
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE
Enable verification of the extendedKeyUsage extension
Disabling this avoids problems with mis-issued and/or misused certificates. Depending on your PKI use,
disabling this can be a security risk.
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS
TLS: Server Support for RFC 5077 SSL session tickets
Server support for RFC 5077 session tickets. See mbedTLS documentation for more details. Disabling
this option will save some code size.
Default value:
• Yes (enabled)
Symmetric Ciphers Contains:

• CONFIG_MBEDTLS_AES_C
• CONFIG_MBEDTLS_BLOWFISH_C
• CONFIG_MBEDTLS_CAMELLIA_C
• CONFIG_MBEDTLS_CCM_C
• CONFIG_MBEDTLS_DES_C
• CONFIG_MBEDTLS_GCM_C
• CONFIG_MBEDTLS_NIST_KW_C
• CONFIG_MBEDTLS_RC4_MODE
• CONFIG_MBEDTLS_XTEA_C

CONFIG_MBEDTLS_AES_C
AES block cipher
Found in: Component config > mbedTLS > Symmetric Ciphers
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_CAMELLIA_C
Camellia block cipher
Default value:
• No (disabled)
CONFIG_MBEDTLS_DES_C
DES block cipher (legacy, insecure)
Enables the DES block cipher to support 3DES-based TLS ciphersuites.
3DES is vulnerable to the Sweet32 attack and should only be enabled if absolutely necessary.
Default value:
• No (disabled)
CONFIG_MBEDTLS_RC4_MODE
RC4 Stream Cipher (legacy, insecure)
ARCFOUR (RC4) stream cipher can be disabled entirely, enabled but not added to default ciphersuites,
or enabled completely.
Please consider the security implications before enabling RC4.
Available options:
• Disabled (MBEDTLS_RC4_DISABLED)
• Enabled, not in default ciphersuites (MBEDTLS_RC4_ENABLED_NO_DEFAULT)
• Enabled (MBEDTLS_RC4_ENABLED)
CONFIG_MBEDTLS_BLOWFISH_C
Blowfish block cipher (read help)
Enables the Blowfish block cipher (not used for TLS sessions.)
The Blowfish cipher is not used for mbedTLS TLS sessions but can be used for other purposes. Read
up on the limitations of Blowfish (including Sweet32) before enabling.
Default value:
• No (disabled)

CONFIG_MBEDTLS_XTEA_C
XTEA block cipher
Enables the XTEA block cipher.
Default value:
• No (disabled)
CONFIG_MBEDTLS_CCM_C
CCM (Counter with CBC-MAC) block cipher modes
Enable Counter with CBC-MAC (CCM) modes for AES and/or Camellia ciphers.
Disabling this option saves some code size.
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_GCM_C
GCM (Galois/Counter) block cipher modes
Enable Galois/Counter Mode for AES and/or Camellia ciphers.
This option is generally faster than CCM.
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_NIST_KW_C
NIST key wrapping (KW) and KW padding (KWP)
Enable NIST key wrapping and key wrapping padding.
Default value:
• No (disabled)
CONFIG_MBEDTLS_RIPEMD160_C
Enable RIPEMD-160 hash algorithm
Enable the RIPEMD-160 hash algorithm.
Default value:
• No (disabled)
Certificates Contains:
• CONFIG_MBEDTLS_PEM_PARSE_C
• CONFIG_MBEDTLS_PEM_WRITE_C
• CONFIG_MBEDTLS_X509_CRL_PARSE_C
• CONFIG_MBEDTLS_X509_CSR_PARSE_C

CONFIG_MBEDTLS_PEM_PARSE_C
Read & Parse PEM formatted certificates
Found in: Component config > mbedTLS > Certificates
Enable decoding/parsing of PEM formatted certificates.
If your certificates are all in the simpler DER format, disabling this option will save some code size.
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_PEM_WRITE_C
Write PEM formatted certificates
Enable writing of PEM formatted certificates.
If writing certificate data only in DER format, disabling this option will save some code size.
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_X509_CRL_PARSE_C
X.509 CRL parsing
Support for parsing X.509 Certifificate Revocation Lists.
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_X509_CSR_PARSE_C
X.509 CSR parsing
Support for parsing X.509 Certifificate Signing Requests
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_ECP_C
Elliptic Curve Ciphers
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_DHM_C
Diffie-Hellman-Merkle key exchange (DHM)
Enable DHM. Needed to use DHE-xxx TLS ciphersuites.
Note that the security of Diffie-Hellman key exchanges depends on a suitable prime being used for the
exchange. Please see detailed warning text about this in file mbedtls/dhm.h file.

Default value:
• No (disabled)
CONFIG_MBEDTLS_ECDH_C
Elliptic Curve Diffie-Hellman (ECDH)
Enable ECDH. Needed to use ECDHE-xxx TLS ciphersuites.
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_ECDSA_C
Elliptic Curve DSA
Found in: Component config > mbedTLS > CONFIG_MBEDTLS_ECDH_C
Enable ECDSA. Needed to use ECDSA-xxx TLS ciphersuites.
Default value:
• Yes (enabled)
CONFIG_MBEDTLS_ECJPAKE_C
Elliptic curve J-PAKE
Enable ECJPAKE. Needed to use ECJPAKE-xxx TLS ciphersuites.
Default value:
• No (disabled)
CONFIG_MBEDTLS_ECP_DP_SECP192R1_ENABLED
Enable SECP192R1 curve
Enable support for SECP192R1 Elliptic Curve.
Default value:
• Yes (enabled) if (CONFIG_MBEDTLS_ATCA_HW_ECDSA_SIGN || CON-
FIG_MBEDTLS_ATCA_HW_ECDSA_VERIFY) && CONFIG_MBEDTLS_ECP_C
Default value:

Default value:
• Yes (enabled)
Default value:
Default value:
CONFIG_MBEDTLS_ECP_DP_SECP192K1_ENABLED
Enable SECP192K1 curve
Enable support for SECP192K1 Elliptic Curve.
Default value:
Default value:

Default value:
CONFIG_MBEDTLS_ECP_DP_BP256R1_ENABLED
Enable BP256R1 curve
support for DP Elliptic Curve.
Default value:
Default value:
Default value:
CONFIG_MBEDTLS_ECP_DP_CURVE25519_ENABLED
Enable CURVE25519 curve
Enable support for CURVE25519 Elliptic Curve.
Default value:
CONFIG_MBEDTLS_ECP_NIST_OPTIM
NIST modulo p optimisations
NIST modulo p optimisations increase Elliptic Curve operation performance.
Disabling this option saves some code size.
# end of Elliptic Curve options
Default value:
• Yes (enabled)

CONFIG_MBEDTLS_POLY1305_C
Poly1305 MAC algorithm
Enable support for Poly1305 MAC algorithm.
Default value:
• No (disabled)
CONFIG_MBEDTLS_CHACHA20_C
Chacha20 stream cipher
Enable support for Chacha20 stream cipher.
Default value:
• No (disabled)
CONFIG_MBEDTLS_CHACHAPOLY_C
ChaCha20-Poly1305 AEAD algorithm
Found in: Component config > mbedTLS > CONFIG_MBEDTLS_CHACHA20_C
Enable support for ChaCha20-Poly1305 AEAD algorithm.
Default value:
• No (disabled) if CONFIG_MBEDTLS_CHACHA20_C && CON-
FIG_MBEDTLS_POLY1305_C
CONFIG_MBEDTLS_HKDF_C
HKDF algorithm (RFC 5869)
Enable support for the Hashed Message Authentication Code (HMAC)-based key derivation function
(HKDF).
Default value:
• No (disabled)
CONFIG_MBEDTLS_THREADING_C
Enable the threading abstraction layer
If you do intend to use contexts between threads, you will need to enable this layer to prevent race
conditions.
Default value:
• No (disabled)
CONFIG_MBEDTLS_THREADING_ALT
Enable threading alternate implementation
Found in: Component config > mbedTLS > CONFIG_MBEDTLS_THREADING_C
Enable threading alt to allow your own alternate threading implementation.
Default value:

• Yes (enabled) if CONFIG_MBEDTLS_THREADING_C
CONFIG_MBEDTLS_THREADING_PTHREAD
Enable threading pthread implementation
Found in: Component config > mbedTLS > CONFIG_MBEDTLS_THREADING_C
Enable the pthread wrapper layer for the threading layer.
Default value:
• No (disabled) if CONFIG_MBEDTLS_THREADING_C
CONFIG_MBEDTLS_LARGE_KEY_SOFTWARE_MPI
Fallback to software implementation for larger MPI values
Fallback to software implementation for RSA key lengths larger than SOC_RSA_MAX_BIT_LEN. If
this is not active then the ESP will be unable to process keys greater than SOC_RSA_MAX_BIT_LEN.
Default value:
• No (disabled)
CONFIG_MBEDTLS_SECURITY_RISKS
Show configurations with potential security risks
Default value:
• No (disabled)
Contains:
• CONFIG_MBEDTLS_ALLOW_UNSUPPORTED_CRITICAL_EXT
CONFIG_MBEDTLS_ALLOW_UNSUPPORTED_CRITICAL_EXT
X.509 CRT parsing with unsupported critical extensions
Found in: Component config > mbedTLS > CONFIG_MBEDTLS_SECURITY_RISKS
Allow the X.509 certificate parser to load certificates with unsupported critical extensions
Default value:
• No (disabled) if CONFIG_MBEDTLS_SECURITY_RISKS
mDNS Contains:
• CONFIG_MDNS_MAX_SERVICES
• CONFIG_MDNS_SERVICE_ADD_TIMEOUT_MS
• CONFIG_MDNS_STRICT_MODE
• CONFIG_MDNS_TASK_AFFINITY
• CONFIG_MDNS_TASK_PRIORITY
• CONFIG_MDNS_TASK_STACK_SIZE
• CONFIG_MDNS_TIMER_PERIOD_MS
• CONFIG_MDNS_MULTIPLE_INSTANCE
• CONFIG_MDNS_NETWORKING_SOCKET

CONFIG_MDNS_MAX_SERVICES
Max number of services
Found in: Component config > mDNS
Services take up a certain amount of memory, and allowing fewer services to be open at the same time
conserves memory. Specify the maximum amount of services here. The valid value is from 1 to 64.
Range:
• from 1 to 64
Default value:
• 10
CONFIG_MDNS_TASK_PRIORITY
mDNS task priority
Allows setting mDNS task priority. Please do not set the task priority higher than priorities of system
tasks. Compile time warning/error would be emitted if the chosen task priority were too high.
Range:
• from 1 to 255
Default value:
• 1
CONFIG_MDNS_TASK_STACK_SIZE
mDNS task stack size
Allows setting mDNS task stacksize.
Default value:
• 4096
CONFIG_MDNS_TASK_AFFINITY
mDNS task affinity
Allows setting mDNS tasks affinity, i.e. whether the task is pinned to CPU0, pinned to CPU1, or allowed
to run on any CPU.
Available options:
• No affinity (MDNS_TASK_AFFINITY_NO_AFFINITY)
• CPU0 (MDNS_TASK_AFFINITY_CPU0)
• CPU1 (MDNS_TASK_AFFINITY_CPU1)
CONFIG_MDNS_SERVICE_ADD_TIMEOUT_MS
mDNS adding service timeout (ms)
Configures timeout for adding a new mDNS service. Adding a service fails if could not be completed
within this time.
Range:
• from 10 to 30000
Default value:

• 2000
CONFIG_MDNS_STRICT_MODE
mDNS strict mode
Configures strict mode. Set this to 1 for the mDNS library to strictly follow the RFC6762: Currently the
only strict feature: Do not repeat original questions in response packets (defined in RFC6762 sec. 6).
Default configuration is 0, i.e. non-strict mode, since some implementations, such as lwIP mdns resolver
(used by standard POSIX API like getaddrinfo, gethostbyname) could not correctly resolve advertised
names.
Default value:
• No (disabled)
CONFIG_MDNS_TIMER_PERIOD_MS
mDNS timer period (ms)
Configures period of mDNS timer, which periodically transmits packets and schedules mDNS searches.
Range:
• from 10 to 10000
Default value:
• 100
CONFIG_MDNS_NETWORKING_SOCKET
Use BSD sockets for mdns networking
Enables optional mdns networking implementation using BSD sockets in UDP multicast mode. This
option creates a new thread to serve receiving packets (TODO). This option uses additional N sockets,
where N is number of interfaces.
Default value:
• No (disabled)
CONFIG_MDNS_MULTIPLE_INSTANCE
Multiple instances under the same service type
Enables adding multiple service instances under the same service type.
Default value:
• Yes (enabled)
ESP-MQTT Configurations Contains:

• CONFIG_MQTT_CUSTOM_OUTBOX
• CONFIG_MQTT_TRANSPORT_SSL
• CONFIG_MQTT_TRANSPORT_WEBSOCKET
• CONFIG_MQTT_PROTOCOL_311
• CONFIG_MQTT_TASK_CORE_SELECTION_ENABLED
• CONFIG_MQTT_USE_CUSTOM_CONFIG
• CONFIG_MQTT_OUTBOX_EXPIRED_TIMEOUT_MS

• CONFIG_MQTT_REPORT_DELETED_MESSAGES
• CONFIG_MQTT_SKIP_PUBLISH_IF_DISCONNECTED
• CONFIG_MQTT_MSG_ID_INCREMENTAL
CONFIG_MQTT_PROTOCOL_311
Enable MQTT protocol 3.1.1
Found in: Component config > ESP-MQTT Configurations
If not, this library will use MQTT protocol 3.1
Default value:
• Yes (enabled)
CONFIG_MQTT_TRANSPORT_SSL
Enable MQTT over SSL
Enable MQTT transport over SSL with mbedtls
Default value:
• Yes (enabled)
CONFIG_MQTT_TRANSPORT_WEBSOCKET
Enable MQTT over Websocket
Enable MQTT transport over Websocket.
Default value:
• Yes (enabled)
CONFIG_MQTT_TRANSPORT_WEBSOCKET_SECURE
Enable MQTT over Websocket Secure
Found in: Component config > ESP-MQTT Configurations > CON-
FIG_MQTT_TRANSPORT_WEBSOCKET
Enable MQTT transport over Websocket Secure.
Default value:
• Yes (enabled)
CONFIG_MQTT_MSG_ID_INCREMENTAL
Use Incremental Message Id
Set this to true for the message id (2.3.1 Packet Identifier) to be generated as an incremental number
rather then a random value (used by default)
Default value:
• No (disabled)

CONFIG_MQTT_SKIP_PUBLISH_IF_DISCONNECTED
Skip publish if disconnected
Set this to true to avoid publishing (enqueueing messages) if the client is disconnected. The
MQTT client tries to publish all messages by default, even in the disconnected state (where
the qos1 and qos2 packets are stored in the internal outbox to be published later) The
MQTT_SKIP_PUBLISH_IF_DISCONNECTED option allows applications to override this behaviour
and not enqueue publish packets in the disconnected state.
Default value:
• No (disabled)
CONFIG_MQTT_REPORT_DELETED_MESSAGES
Report deleted messages
Set this to true to post events for all messages which were deleted from the outbox before being correctly
sent and confirmed.
Default value:
• No (disabled)
CONFIG_MQTT_USE_CUSTOM_CONFIG
MQTT Using custom configurations
Custom MQTT configurations.
Default value:
• No (disabled)
CONFIG_MQTT_TCP_DEFAULT_PORT
Default MQTT over TCP port
Found in: Component config > ESP-MQTT Configurations > CONFIG_MQTT_USE_CUSTOM_CONFIG
Default MQTT over TCP port
Default value:
• 1883 if CONFIG_MQTT_USE_CUSTOM_CONFIG
CONFIG_MQTT_SSL_DEFAULT_PORT
Default MQTT over SSL port
Default MQTT over SSL port
Default value:
• 8883 if CONFIG_MQTT_USE_CUSTOM_CONFIG && CONFIG_MQTT_TRANSPORT_SSL

CONFIG_MQTT_WS_DEFAULT_PORT
Default MQTT over Websocket port
Default MQTT over Websocket port
Default value:
• 80 if CONFIG_MQTT_USE_CUSTOM_CONFIG && CON-
FIG_MQTT_TRANSPORT_WEBSOCKET
CONFIG_MQTT_WSS_DEFAULT_PORT
Default MQTT over Websocket Secure port
Default MQTT over Websocket Secure port
Default value:
• 443 if CONFIG_MQTT_USE_CUSTOM_CONFIG && CON-
FIG_MQTT_TRANSPORT_WEBSOCKET && CONFIG_MQTT_TRANSPORT_WEBSOCKET_SECURE
CONFIG_MQTT_BUFFER_SIZE
Default MQTT Buffer Size
This buffer size using for both transmit and receive
Default value:
CONFIG_MQTT_TASK_STACK_SIZE
MQTT task stack size
MQTT task stack size
Default value:
CONFIG_MQTT_DISABLE_API_LOCKS
Disable API locks
Default config employs API locks to protect internal structures. It is possible to disable these locks if
the user code doesn t access MQTT API from multiple concurrent tasks
Default value:
• No (disabled) if CONFIG_MQTT_USE_CUSTOM_CONFIG
CONFIG_MQTT_TASK_PRIORITY
MQTT task priority
MQTT task priority. Higher number denotes higher priority.
Default value:

CONFIG_MQTT_TASK_CORE_SELECTION_ENABLED
Enable MQTT task core selection
This will enable core selection
Default value:
• false
CONFIG_MQTT_TASK_CORE_SELECTION
Core to use ?
Found in: Component config > ESP-MQTT Configurations > CON-
FIG_MQTT_TASK_CORE_SELECTION_ENABLED
Available options:
• Core 0 (MQTT_USE_CORE_0)
• Core 1 (MQTT_USE_CORE_1)
CONFIG_MQTT_CUSTOM_OUTBOX
Enable custom outbox implementation
Set to true if a specific implementation of message outbox is needed (e.g. persistant outbox in NVM or
similar).
Default value:
• No (disabled)
CONFIG_MQTT_OUTBOX_EXPIRED_TIMEOUT_MS
Outbox message expired timeout[ms]
Messages which stays in the outbox longer than this value before being published will be discarded.
Default value:
Newlib Contains:
• CONFIG_NEWLIB_NANO_FORMAT
• CONFIG_NEWLIB_STDIN_LINE_ENDING
• CONFIG_NEWLIB_STDOUT_LINE_ENDING
CONFIG_NEWLIB_STDOUT_LINE_ENDING
Line ending for UART output
Found in: Component config > Newlib
This option allows configuring the desired line endings sent to UART when a newline ( n , LF) appears
on stdout. Three options are possible:
CRLF: whenever LF is encountered, prepend it with CR

LF: no modification is applied, stdout is sent as is

CR: each occurence of LF is replaced with CR
This option doesn t affect behavior of the UART driver (drivers/uart.h).
Available options:
• CRLF (NEWLIB_STDOUT_LINE_ENDING_CRLF)
• LF (NEWLIB_STDOUT_LINE_ENDING_LF)
• CR (NEWLIB_STDOUT_LINE_ENDING_CR)
CONFIG_NEWLIB_STDIN_LINE_ENDING
Line ending for UART input
This option allows configuring which input sequence on UART produces a newline ( n , LF) on stdin.
Three options are possible:
CRLF: CRLF is converted to LF
LF: no modification is applied, input is sent to stdin as is
CR: each occurence of CR is replaced with LF
This option doesn t affect behavior of the UART driver (drivers/uart.h).
Available options:
• CRLF (NEWLIB_STDIN_LINE_ENDING_CRLF)
• LF (NEWLIB_STDIN_LINE_ENDING_LF)
• CR (NEWLIB_STDIN_LINE_ENDING_CR)
CONFIG_NEWLIB_NANO_FORMAT
Enable nano formatting options for printf/scanf family
ESP32 ROM contains parts of newlib C library, including printf/scanf family of functions. These func-
tions have been compiled with so-called nano formatting option. This option doesn t support 64-bit
integer formats and C99 features, such as positional arguments.
For more details about nano formatting option, please see newlib readme file, search for enable-
newlib-nano-formatted-io : https://sourceware.org/newlib/README
If this option is enabled, build system will use functions available in ROM, reducing the application
binary size. Functions available in ROM run faster than functions which run from flash. Functions
available in ROM can also run when flash instruction cache is disabled.
If you need 64-bit integer formatting support or C99 features, keep this option disabled.
Default value:
• No (disabled)
NVS Contains:
• CONFIG_NVS_ENCRYPTION
• CONFIG_NVS_COMPATIBLE_PRE_V4_3_ENCRYPTION_FLAG

CONFIG_NVS_ENCRYPTION
Enable NVS encryption
Found in: Component config > NVS
This option enables encryption for NVS. When enabled, AES-XTS is used to encrypt the complete NVS
data, except the page headers. It requires XTS encryption keys to be stored in an encrypted partition.
This means enabling flash encryption is a pre-requisite for this feature.
Default value:
• Yes (enabled) if CONFIG_SECURE_FLASH_ENC_ENABLED
CONFIG_NVS_COMPATIBLE_PRE_V4_3_ENCRYPTION_FLAG
NVS partition encrypted flag compatible with ESP-IDF before v4.3
Found in: Component config > NVS
Enabling this will ignore encrypted flag for NVS partitions. NVS encryption scheme is different
than hardware flash encryption and hence it is not recommended to have encrypted flag for NVS
partitions. This was not being checked in pre v4.3 IDF. Hence, if you have any devices where this flag
is kept enabled in partition table then enabling this config will allow to have same behavior as pre v4.3
IDF.
OpenSSL Contains:
• CONFIG_OPENSSL_DEBUG
• CONFIG_OPENSSL_ERROR_STACK
• CONFIG_OPENSSL_LOWLEVEL_DEBUG
• CONFIG_OPENSSL_DEBUG_LEVEL
• CONFIG_OPENSSL_ASSERT
CONFIG_OPENSSL_DEBUG
Enable OpenSSL debugging
Found in: Component config > OpenSSL
Enable OpenSSL debugging function.
If the option is enabled, SSL_DEBUG works.
Default value:
• No (disabled)
CONFIG_OPENSSL_ERROR_STACK
Enable OpenSSL error structure
Enable OpenSSL Error reporting
Default value:
• Yes (enabled)
CONFIG_OPENSSL_DEBUG_LEVEL
OpenSSL debugging level
OpenSSL debugging level.

Only function whose debugging level is higher than OPENSSL_DEBUG_LEVEL works.

For example: If OPENSSL_DEBUG_LEVEL = 2, you use function SSL_DEBUG(1, malloc failed
) . Because 1 < 2, it will not print.
Range:
• from 0 to 255 if CONFIG_OPENSSL_DEBUG
Default value:
• 0 if CONFIG_OPENSSL_DEBUG
CONFIG_OPENSSL_LOWLEVEL_DEBUG
Enable OpenSSL low-level module debugging
If the option is enabled, low-level module debugging function of OpenSSL is enabled, e.g. mbedtls
internal debugging function.
Default value:
• No (disabled) if CONFIG_OPENSSL_DEBUG
CONFIG_OPENSSL_ASSERT
Select OpenSSL assert function
OpenSSL function needs assert function to check if input parameters are valid.
If you want to use assert debugging function, OPENSSL_DEBUG should be enabled.
Available options:
• Do nothing (OPENSSL_ASSERT_DO_NOTHING)
Do nothing and SSL_ASSERT does not work.
• Check and exit (OPENSSL_ASSERT_EXIT)
Enable assert exiting, it will check and return error code.
• Show debugging message (OPENSSL_ASSERT_DEBUG)
Enable assert debugging, it will check and show debugging message.
• Show debugging message and exit (OPENSSL_ASSERT_DEBUG_EXIT)
Enable assert debugging and exiting, it will check, show debugging message and return error
code.
• Show debugging message and block (OPENSSL_ASSERT_DEBUG_BLOCK)
Enable assert debugging and blocking, it will check, show debugging message and block by
while (1); .
OpenThread Contains:
• CONFIG_OPENTHREAD_ENABLED
CONFIG_OPENTHREAD_ENABLED
OpenThread
Found in: Component config > OpenThread
Select this option to enable OpenThread and show the submenu with OpenThread configuration choices.
Default value:
• No (disabled)

CONFIG_OPENTHREAD_RADIO_TYPE
Config the Thread radio type
Found in: Component config > OpenThread > CONFIG_OPENTHREAD_ENABLED
Configure how OpenThread connects to the 15.4 radio
Available options:
• Native 15.4 radio (OPENTHREAD_RADIO_NATIVE)
Select this to use the native 15.4 radio.
• Connect via UART (OPENTHREAD_RADIO_SPINEL_UART)
Select this to connect to a Radio Co-Processor via UART.
CONFIG_OPENTHREAD_DEVICE_TYPE
Config the Thread device type
OpenThread can be configured to different device types (FTD, MTD, Radio)
Available options:
• Full Thread Device (OPENTHREAD_FTD)
Select this to enable Full Thread Device which can act as router and leader in a Thread net-
work.
• Minimal Thread Device (OPENTHREAD_MTD)
Select this to enable Minimal Thread Device which can only act as end device in a Thread
network. This will reduce the code size of the OpenThread stack.
• Radio Only Device (OPENTHREAD_RADIO)
Select this to enable Radio Only Device which cannot can only forward 15.4 packets to the
host. The OpenThread stack will be run on the host and OpenThread will have minimal
footprint on the radio only device.
CONFIG_OPENTHREAD_DIAG
Enable diag
Select this option to enable Diag in OpenThread. This will enable diag mode and a series of diag com-
mands in the OpenThread command line. These commands allow users to manipulate low-level features
of the storage and 15.4 radio.
Default value:
• Yes (enabled) if CONFIG_OPENTHREAD_ENABLED
CONFIG_OPENTHREAD_COMMISSIONER
Enable Commissioner
Select this option to enable commissioner in OpenThread. This will enable the device to act as a com-
missioner in the Thread network. A commissioner checks the pre-shared key from a joining device
with the Thread commissioning protocol and shares the network parameter with the joining device upon
success.
Default value:
• No (disabled) if CONFIG_OPENTHREAD_ENABLED

CONFIG_OPENTHREAD_JOINER
Enable Joiner
Select this option to enable Joiner in OpenThread. This allows a device to join the Thread network with
a pre-shared key using the Thread commissioning protocol.
Default value:
CONFIG_OPENTHREAD_SRP_CLIENT
Enable SRP Client
Select this option to enable SRP Client in OpenThread. This allows a device to register SRP services to
SRP Server.
Default value:
CONFIG_OPENTHREAD_BORDER_ROUTER
Enable Border Router
Select this option to enable border router features in OpenThread.
Default value:
CONFIG_OPENTHREAD_TREL
Enable Thread Radio Encapsulation Link
Found in: Component config > OpenThread > CONFIG_OPENTHREAD_ENABLED > CON-
FIG_OPENTHREAD_BORDER_ROUTER
Select this option to enable sending 15.4 frames through the backbone interface.
Default value:
• No (disabled) if CONFIG_OPENTHREAD_BORDER_ROUTER
CONFIG_OPENTHREAD_ESP_LIB_FROM_INTERNAL_SRC
Build esp_openthread libraries from source
Override the shipped libopenthread_br.a and libopenthread_port.a, for internal builds.
Default value:
CONFIG_OPENTHREAD_NUM_MESSAGE_BUFFERS
The number of openthread message buffers
Range:
• from 50 to 100 if CONFIG_OPENTHREAD_ENABLED

Default value:
• 65 if CONFIG_OPENTHREAD_ENABLED
PThreads Contains:
• CONFIG_PTHREAD_TASK_NAME_DEFAULT
• CONFIG_PTHREAD_TASK_CORE_DEFAULT
• CONFIG_PTHREAD_TASK_PRIO_DEFAULT
• CONFIG_PTHREAD_TASK_STACK_SIZE_DEFAULT
• CONFIG_PTHREAD_STACK_MIN
CONFIG_PTHREAD_TASK_PRIO_DEFAULT
Default task priority
Found in: Component config > PThreads
Priority used to create new tasks with default pthread parameters.
Range:
• from 0 to 255
Default value:
• 5
CONFIG_PTHREAD_TASK_STACK_SIZE_DEFAULT
Default task stack size
Stack size used to create new tasks with default pthread parameters.
Default value:
• 3072
CONFIG_PTHREAD_STACK_MIN
Minimum allowed pthread stack size
Minimum allowed pthread stack size set in attributes passed to pthread_create
Default value:
• 768
CONFIG_PTHREAD_TASK_CORE_DEFAULT
Default pthread core affinity
The default core to which pthreads are pinned.
Available options:
• No affinity (PTHREAD_DEFAULT_CORE_NO_AFFINITY)
• Core 0 (PTHREAD_DEFAULT_CORE_0)
• Core 1 (PTHREAD_DEFAULT_CORE_1)

CONFIG_PTHREAD_TASK_NAME_DEFAULT
Default name of pthreads
The default name of pthreads.
Default value:
• pthread
SPI Flash driver Contains:

• Auto-detect flash chips
• CONFIG_SPI_FLASH_BYPASS_BLOCK_ERASE
• CONFIG_SPI_FLASH_ENABLE_ENCRYPTED_READ_WRITE
• CONFIG_SPI_FLASH_ENABLE_COUNTERS
• CONFIG_SPI_FLASH_ROM_DRIVER_PATCH
• CONFIG_SPI_FLASH_YIELD_DURING_ERASE
• CONFIG_SPI_FLASH_CHECK_ERASE_TIMEOUT_DISABLED
• CONFIG_SPI_FLASH_WRITE_CHUNK_SIZE
• CONFIG_SPI_FLASH_OVERRIDE_CHIP_DRIVER_LIST
• CONFIG_SPI_FLASH_SIZE_OVERRIDE
• CONFIG_SPI_FLASH_SHARE_SPI1_BUS
• CONFIG_SPI_FLASH_USE_LEGACY_IMPL
• CONFIG_SPI_FLASH_VERIFY_WRITE
• CONFIG_SPI_FLASH_DANGEROUS_WRITE
CONFIG_SPI_FLASH_VERIFY_WRITE
Verify SPI flash writes
Found in: Component config > SPI Flash driver
If this option is enabled, any time SPI flash is written then the data will be read back and verified. This
can catch hardware problems with SPI flash, or flash which was not erased before verification.
Default value:
• No (disabled)
CONFIG_SPI_FLASH_LOG_FAILED_WRITE
Log errors if verification fails
Found in: Component config > SPI Flash driver > CONFIG_SPI_FLASH_VERIFY_WRITE
If this option is enabled, if SPI flash write verification fails then a log error line will be written with the
address, expected & actual values. This can be useful when debugging hardware SPI flash problems.
Default value:
• No (disabled) if CONFIG_SPI_FLASH_VERIFY_WRITE
CONFIG_SPI_FLASH_WARN_SETTING_ZERO_TO_ONE
Log warning if writing zero bits to ones
Found in: Component config > SPI Flash driver > CONFIG_SPI_FLASH_VERIFY_WRITE
If this option is enabled, any SPI flash write which tries to set zero bits in the flash to ones will log a
warning. Such writes will not result in the requested data appearing identically in flash once written, as
SPI NOR flash can only set bits to one when an entire sector is erased. After erasing, individual bits can
only be written from one to zero.

Note that some software (such as SPIFFS) which is aware of SPI NOR flash may write one bits as an
optimisation, relying on the data in flash becoming a bitwise AND of the new data and any existing data.
Such software will log spurious warnings if this option is enabled.
Default value:
• No (disabled) if CONFIG_SPI_FLASH_VERIFY_WRITE
CONFIG_SPI_FLASH_ENABLE_COUNTERS
Enable operation counters
This option enables the following APIs:
• spi_flash_reset_counters
• spi_flash_dump_counters
• spi_flash_get_counters
These APIs may be used to collect performance data for spi_flash APIs and to help understand behaviour
of libraries which use SPI flash.
Default value:
• 0
CONFIG_SPI_FLASH_ROM_DRIVER_PATCH
Enable SPI flash ROM driver patched functions
Enable this flag to use patched versions of SPI flash ROM driver functions. This option should be
enabled, if any one of the following is true: (1) need to write to flash on ESP32-D2WD; (2) main SPI
flash is connected to non-default pins; (3) main SPI flash chip is manufactured by ISSI.
Default value:
• Yes (enabled)
CONFIG_SPI_FLASH_DANGEROUS_WRITE
Writing to dangerous flash regions
SPI flash APIs can optionally abort or return a failure code if erasing or writing addresses that fall at
the beginning of flash (covering the bootloader and partition table) or that overlap the app partition that
contains the running app.
It is not recommended to ever write to these regions from an IDF app, and this check prevents logic
errors or corrupted firmware memory from damaging these regions.
Note that this feature *does not* check calls to the esp_rom_xxx SPI flash ROM functions. These
functions should not be called directly from IDF applications.
Available options:
• Aborts (SPI_FLASH_DANGEROUS_WRITE_ABORTS)
• Fails (SPI_FLASH_DANGEROUS_WRITE_FAILS)
• Allowed (SPI_FLASH_DANGEROUS_WRITE_ALLOWED)
CONFIG_SPI_FLASH_USE_LEGACY_IMPL
Use the legacy implementation before IDF v4.0

The implementation of SPI flash has been greatly changed in IDF v4.0. Enable this option to use the
legacy implementation.
Default value:
• No (disabled)
CONFIG_SPI_FLASH_SHARE_SPI1_BUS
Support other devices attached to SPI1 bus
Each SPI bus needs a lock for arbitration among devices. This allows multiple devices on a same bus,
but may reduce the speed of esp_flash driver access to the main flash chip.
If you only need to use esp_flash driver to access the main flash chip, disable this option, and the lock
will be bypassed on SPI1 bus. Otherwise if extra devices are needed to attach to SPI1 bus, enable this
option.
Default value:
• No (disabled) if CONFIG_SPI_FLASH_USE_LEGACY_IMPL
CONFIG_SPI_FLASH_BYPASS_BLOCK_ERASE
Bypass a block erase and always do sector erase
Some flash chips can have very high max erase times, especially for block erase (32KB or 64KB).
This option allows to bypass block erase and always do sector erase commands. This will be much
slower overall in most cases, but improves latency for other code to run.
Default value:
• No (disabled)
CONFIG_SPI_FLASH_YIELD_DURING_ERASE
Enables yield operation during flash erase
This allows to yield the CPUs between erase commands. Prevents starvation of other tasks.
Default value:
• Yes (enabled)
CONFIG_SPI_FLASH_ERASE_YIELD_DURATION_MS
Duration of erasing to yield CPUs (ms)
Found in: Component config > SPI Flash driver > CONFIG_SPI_FLASH_YIELD_DURING_ERASE
If a duration of one erase command is large then it will yield CPUs after finishing a current command.
Default value:
• 20
CONFIG_SPI_FLASH_ERASE_YIELD_TICKS
CPU release time (tick) for an erase operation
Found in: Component config > SPI Flash driver > CONFIG_SPI_FLASH_YIELD_DURING_ERASE
Defines how many ticks will be before returning to continue a erasing.
Default value:

• 1
CONFIG_SPI_FLASH_WRITE_CHUNK_SIZE
Flash write chunk size
Flash write is broken down in terms of multiple (smaller) write operations. This configuration options
helps to set individual write chunk size, smaller value here ensures that cache (and non-IRAM resident
interrupts) remains disabled for shorter duration.
Range:
• from 256 to 8192
Default value:
• 8192
CONFIG_SPI_FLASH_SIZE_OVERRIDE
Override flash size in bootloader header by ESPTOOLPY_FLASHSIZE
SPI Flash driver uses the flash size configured in bootloader header by default. Enable this option to
override flash size with latest ESPTOOLPY_FLASHSIZE value from the app header if the size in the
bootloader header is incorrect.
Default value:
• No (disabled)
CONFIG_SPI_FLASH_CHECK_ERASE_TIMEOUT_DISABLED
Flash timeout checkout disabled
This option is helpful if you are using a flash chip whose timeout is quite large or unpredictable.
Default value:
CONFIG_SPI_FLASH_OVERRIDE_CHIP_DRIVER_LIST
Override default chip driver list
This option allows the chip driver list to be customized, instead of using the default list provided by
ESP-IDF.
When this option is enabled, the default list is no longer compiled or linked. Instead, the de-
fault_registered_chips structure must be provided by the user.
See example: custom_chip_driver under examples/storage for more details.
Default value:
Auto-detect flash chips Contains:

• CONFIG_SPI_FLASH_SUPPORT_GD_CHIP
• CONFIG_SPI_FLASH_SUPPORT_ISSI_CHIP
• CONFIG_SPI_FLASH_SUPPORT_MXIC_CHIP
• CONFIG_SPI_FLASH_SUPPORT_WINBOND_CHIP

CONFIG_SPI_FLASH_SUPPORT_ISSI_CHIP
ISSI
Found in: Component config > SPI Flash driver > Auto-detect flash chips
Enable this to support auto detection of ISSI chips if chip vendor not directly given by chip\_drv
member of the chip struct. This adds support for variant chips, however will extend detecting time.
Default value:
• Yes (enabled)
CONFIG_SPI_FLASH_SUPPORT_MXIC_CHIP
MXIC
Enable this to support auto detection of MXIC chips if chip vendor not directly given by chip\_drv
Default value:
• Yes (enabled)
CONFIG_SPI_FLASH_SUPPORT_GD_CHIP
GigaDevice
Enable this to support auto detection of GD (GigaDevice) chips if chip vendor not directly given by
chip\_drv member of the chip struct. If you are using Wrover modules, please don t disable this,
otherwise your flash may not work in 4-bit mode.
This adds support for variant chips, however will extend detecting time and image size. Note that the
default chip driver supports the GD chips with product ID 60H.
Default value:
• Yes (enabled)
CONFIG_SPI_FLASH_SUPPORT_WINBOND_CHIP
Winbond
Enable this to support auto detection of Winbond chips if chip vendor not directly given by chip\_drv
Default value:
• Yes (enabled)
CONFIG_SPI_FLASH_ENABLE_ENCRYPTED_READ_WRITE
Enable encrypted partition read/write operations
This option enables flash read/write operations to encrypted partition/s. This option is kept enabled
irrespective of state of flash encryption feature. However, in case application is not using flash encryption
feature and is in need of some additional memory from IRAM region (~1KB) then this config can be
disabled.
Default value:
• Yes (enabled)

SPIFFS Configuration Contains:

• Debug Configuration
• CONFIG_SPIFFS_USE_MAGIC
• CONFIG_SPIFFS_GC_STATS
• CONFIG_SPIFFS_PAGE_CHECK
• CONFIG_SPIFFS_FOLLOW_SYMLINKS
• CONFIG_SPIFFS_MAX_PARTITIONS
• CONFIG_SPIFFS_USE_MTIME
• CONFIG_SPIFFS_GC_MAX_RUNS
• CONFIG_SPIFFS_OBJ_NAME_LEN
• CONFIG_SPIFFS_META_LENGTH
• SPIFFS Cache Configuration
• CONFIG_SPIFFS_PAGE_SIZE
• CONFIG_SPIFFS_MTIME_WIDE_64_BITS
CONFIG_SPIFFS_MAX_PARTITIONS
Maximum Number of Partitions
Found in: Component config > SPIFFS Configuration
Define maximum number of partitions that can be mounted.
Range:
• from 1 to 10
Default value:
• 3
SPIFFS Cache Configuration Contains:

• CONFIG_SPIFFS_CACHE
CONFIG_SPIFFS_CACHE
Enable SPIFFS Cache
Found in: Component config > SPIFFS Configuration > SPIFFS Cache Configuration
Enables/disable memory read caching of nucleus file system operations.
Default value:
• Yes (enabled)
CONFIG_SPIFFS_CACHE_WR
Enable SPIFFS Write Caching
Found in: Component config > SPIFFS Configuration > SPIFFS Cache Configuration > CON-
FIG_SPIFFS_CACHE
Enables memory write caching for file descriptors in hydrogen.
Default value:
• Yes (enabled)
CONFIG_SPIFFS_CACHE_STATS
Enable SPIFFS Cache Statistics
Found in: Component config > SPIFFS Configuration > SPIFFS Cache Configuration > CON-
FIG_SPIFFS_CACHE

Enable/disable statistics on caching. Debug/test purpose only.

Default value:
• No (disabled)
CONFIG_SPIFFS_PAGE_CHECK
Enable SPIFFS Page Check
Always check header of each accessed page to ensure consistent state. If enabled it will increase number
of reads from flash, especially if cache is disabled.
Default value:
• Yes (enabled)
CONFIG_SPIFFS_GC_MAX_RUNS
Set Maximum GC Runs
Define maximum number of GC runs to perform to reach desired free pages.
Range:
• from 1 to 255
Default value:
• 10
CONFIG_SPIFFS_GC_STATS
Enable SPIFFS GC Statistics
Enable/disable statistics on gc. Debug/test purpose only.
Default value:
• No (disabled)
CONFIG_SPIFFS_PAGE_SIZE
SPIFFS logical page size
Logical page size of SPIFFS partition, in bytes. Must be multiple of flash page size (which is usually 256
bytes). Larger page sizes reduce overhead when storing large files, and improve filesystem performance
when reading large files. Smaller page sizes reduce overhead when storing small (< page size) files.
Range:
• from 256 to 1024
Default value:
• 256
CONFIG_SPIFFS_OBJ_NAME_LEN
Set SPIFFS Maximum Name Length
Object name maximum length. Note that this length include the zero-termination character, meaning
maximum string of characters can at most be SPIFFS_OBJ_NAME_LEN - 1.

SPIFFS_OBJ_NAME_LEN + SPIFFS_META_LENGTH should not exceed SPIFFS_PAGE_SIZE -

64.
Range:
• from 1 to 256
Default value:
• 32
CONFIG_SPIFFS_FOLLOW_SYMLINKS
Enable symbolic links for image creation
If this option is enabled, symbolic links are taken into account during partition image creation.
Default value:
• No (disabled)
CONFIG_SPIFFS_USE_MAGIC
Enable SPIFFS Filesystem Magic
Enable this to have an identifiable spiffs filesystem. This will look for a magic in all sectors to determine
if this is a valid spiffs system or not at mount time.
Default value:
• Yes (enabled)
CONFIG_SPIFFS_USE_MAGIC_LENGTH
Enable SPIFFS Filesystem Length Magic
Found in: Component config > SPIFFS Configuration > CONFIG_SPIFFS_USE_MAGIC
If this option is enabled, the magic will also be dependent on the length of the filesystem. For exam-
ple, a filesystem configured and formatted for 4 megabytes will not be accepted for mounting with a
configuration defining the filesystem as 2 megabytes.
Default value:
• Yes (enabled)
CONFIG_SPIFFS_META_LENGTH
Size of per-file metadata field
This option sets the number of extra bytes stored in the file header. These bytes can be used in an
application-specific manner. Set this to at least 4 bytes to enable support for saving file modification
time.
SPIFFS_OBJ_NAME_LEN + SPIFFS_META_LENGTH should not exceed SPIFFS_PAGE_SIZE -
64.
Default value:
• 4

CONFIG_SPIFFS_USE_MTIME
Save file modification time
If enabled, then the first 4 bytes of per-file metadata will be used to store file modification time (mtime),
accessible through stat/fstat functions. Modification time is updated when the file is opened.
Default value:
• Yes (enabled)
CONFIG_SPIFFS_MTIME_WIDE_64_BITS
The time field occupies 64 bits in the image instead of 32 bits
If this option is not set, the time field is 32 bits (up to 2106 year), otherwise it is 64 bits and make
sure it matches SPIFFS_META_LENGTH. If the chip already has the spiffs image with the time
field = 32 bits then this option cannot be applied in this case. Erase it first before using this op-
tion. To resolve the Y2K38 problem for the spiffs, use a toolchain with support time_t 64 bits (see
SDK_TOOLCHAIN_SUPPORTS_TIME_WIDE_64_BITS).
Default value:
• No (disabled) if CONFIG_SPIFFS_META_LENGTH >= 8
Debug Configuration Contains:

• CONFIG_SPIFFS_DBG
• CONFIG_SPIFFS_API_DBG
• CONFIG_SPIFFS_CACHE_DBG
• CONFIG_SPIFFS_CHECK_DBG
• CONFIG_SPIFFS_TEST_VISUALISATION
• CONFIG_SPIFFS_GC_DBG
CONFIG_SPIFFS_DBG
Enable general SPIFFS debug
Found in: Component config > SPIFFS Configuration > Debug Configuration
Enabling this option will print general debug mesages to the console.
Default value:
• No (disabled)
CONFIG_SPIFFS_API_DBG
Enable SPIFFS API debug
Enabling this option will print API debug mesages to the console.
Default value:
• No (disabled)
CONFIG_SPIFFS_GC_DBG
Enable SPIFFS Garbage Cleaner debug
Enabling this option will print GC debug mesages to the console.

Default value:
• No (disabled)
CONFIG_SPIFFS_CACHE_DBG
Enable SPIFFS Cache debug
Enabling this option will print cache debug mesages to the console.
Default value:
• No (disabled)
CONFIG_SPIFFS_CHECK_DBG
Enable SPIFFS Filesystem Check debug
Enabling this option will print Filesystem Check debug mesages to the console.
Default value:
• No (disabled)
CONFIG_SPIFFS_TEST_VISUALISATION
Enable SPIFFS Filesystem Visualization
Enable this option to enable SPIFFS_vis function in the API.
Default value:
• No (disabled)
TCP Transport Contains:

• Websocket
Websocket Contains:
• CONFIG_WS_TRANSPORT
CONFIG_WS_TRANSPORT
Enable Websocket Transport
Found in: Component config > TCP Transport > Websocket
Enable support for creating websocket transport.
Default value:
• Yes (enabled)
CONFIG_WS_BUFFER_SIZE
Websocket transport buffer size
Found in: Component config > TCP Transport > Websocket > CONFIG_WS_TRANSPORT
Size of the buffer used for constructing the HTTP Upgrade request during connect
Default value:
• 1024

Unity unit testing library Contains:

• CONFIG_UNITY_ENABLE_COLOR
• CONFIG_UNITY_ENABLE_IDF_TEST_RUNNER
• CONFIG_UNITY_ENABLE_FIXTURE
• CONFIG_UNITY_ENABLE_BACKTRACE_ON_FAIL
• CONFIG_UNITY_ENABLE_64BIT
• CONFIG_UNITY_ENABLE_DOUBLE
• CONFIG_UNITY_ENABLE_FLOAT
CONFIG_UNITY_ENABLE_FLOAT
Support for float type
Found in: Component config > Unity unit testing library
If not set, assertions on float arguments will not be available.
Default value:
• Yes (enabled)
CONFIG_UNITY_ENABLE_DOUBLE
Support for double type
If not set, assertions on double arguments will not be available.
Default value:
• Yes (enabled)
CONFIG_UNITY_ENABLE_64BIT
Support for 64-bit integer types
If not set, assertions on 64-bit integer types will always fail. If this feature is enabled, take care not
to pass pointers (which are 32 bit) to UNITY_ASSERT_EQUAL, as that will cause pointer-to-int-cast
warnings.
Default value:
• No (disabled)
CONFIG_UNITY_ENABLE_COLOR
Colorize test output
If set, Unity will colorize test results using console escape sequences.
Default value:
• No (disabled)
CONFIG_UNITY_ENABLE_IDF_TEST_RUNNER
Include ESP-IDF test registration/running helpers
If set, then the following features will be available:
• TEST_CASE macro which performs automatic registration of test functions

• Functions to run registered test functions: unity_run_all_tests, unity_run_tests_with_filter,

unity_run_single_test_by_name.
• Interactive menu which lists test cases and allows choosing the tests to be run, available via
unity_run_menu function.
Disable if a different test registration mechanism is used.
Default value:
• Yes (enabled)
CONFIG_UNITY_ENABLE_FIXTURE
Include Unity test fixture
If set, unity_fixture.h header file and associated source files are part of the build. These provide an
optional set of macros and functions to implement test groups.
Default value:
• No (disabled)
CONFIG_UNITY_ENABLE_BACKTRACE_ON_FAIL
Print a backtrace when a unit test fails
If set, the unity framework will print the backtrace information before jumping back to the test menu.
The jumping is usually occurs in assert functions such as TEST_ASSERT, TEST_FAIL etc.
Default value:
• No (disabled)
Virtual file system Contains:

• CONFIG_VFS_SUPPORT_IO
CONFIG_VFS_SUPPORT_IO
Provide basic I/O functions
Found in: Component config > Virtual file system
If enabled, the following functions are provided by the VFS component.
open, close, read, write, pread, pwrite, lseek, fstat, fsync, ioctl, fcntl
Filesystem drivers can then be registered to handle these functions for specific paths.
Disabling this option can save memory when the support for these functions is not required.
Note that the following functions can still be used with socket file descriptors when this option is disabled:
close, read, write, ioctl, fcntl.
Default value:
• Yes (enabled)

CONFIG_VFS_SUPPORT_DIR
Provide directory related functions
Found in: Component config > Virtual file system > CONFIG_VFS_SUPPORT_IO
If enabled, the following functions are provided by the VFS component.
stat, link, unlink, rename, utime, access, truncate, rmdir, mkdir, opendir, closedir, readdir, readdir_r,
seekdir, telldir, rewinddir
Filesystem drivers can then be registered to handle these functions for specific paths.
Disabling this option can save memory when the support for these functions is not required.
Default value:
• Yes (enabled)
CONFIG_VFS_SUPPORT_SELECT
Provide select function
If enabled, select function is provided by the VFS component, and can be used on peripheral file de-
scriptors (such as UART) and sockets at the same time.
If disabled, the default select implementation will be provided by LWIP for sockets only.
Disabling this option can reduce code size if support for select on UART file descriptors is not
required.
Default value:
• Yes (enabled) if CONFIG_VFS_SUPPORT_IO && CON-
FIG_LWIP_USE_ONLY_LWIP_SELECT
CONFIG_VFS_SUPPRESS_SELECT_DEBUG_OUTPUT
Suppress select() related debug outputs
Found in: Component config > Virtual file system > CONFIG_VFS_SUPPORT_IO > CON-
FIG_VFS_SUPPORT_SELECT
Select() related functions might produce an unconveniently lot of debug outputs when one sets the default
log level to DEBUG or higher. It is possible to suppress these debug outputs by enabling this option.
Default value:
• Yes (enabled)
CONFIG_VFS_SUPPORT_TERMIOS
Provide termios.h functions
Disabling this option can save memory when the support for termios.h is not required.
Default value:
• Yes (enabled)
Host File System I/O (Semihosting) Contains:

• CONFIG_VFS_SEMIHOSTFS_MAX_MOUNT_POINTS
• CONFIG_VFS_SEMIHOSTFS_HOST_PATH_MAX_LEN

CONFIG_VFS_SEMIHOSTFS_MAX_MOUNT_POINTS
Host FS: Maximum number of the host filesystem mount points
Found in: Component config > Virtual file system > CONFIG_VFS_SUPPORT_IO > Host File System I/O
(Semihosting)
Define maximum number of host filesystem mount points.
Default value:
• 1
CONFIG_VFS_SEMIHOSTFS_HOST_PATH_MAX_LEN
Host FS: Maximum path length for the host base directory
Found in: Component config > Virtual file system > CONFIG_VFS_SUPPORT_IO > Host File System I/O
(Semihosting)
Define maximum path length for the host base directory which is to be mounted. If host path passed to
esp_vfs_semihost_register() is longer than this value it will be truncated.
Default value:
• 128
Wear Levelling Contains:

• CONFIG_WL_SECTOR_MODE
• CONFIG_WL_SECTOR_SIZE
CONFIG_WL_SECTOR_SIZE
Wear Levelling library sector size
Found in: Component config > Wear Levelling
Sector size used by wear levelling library. You can set default sector size or size that will fit to the flash
device sector size.
With sector size set to 4096 bytes, wear levelling library is more efficient. However if FAT filesystem is
used on top of wear levelling library, it will need more temporary storage: 4096 bytes for each mounted
filesystem and 4096 bytes for each opened file.
With sector size set to 512 bytes, wear levelling library will perform more operations with flash memory,
but less RAM will be used by FAT filesystem library (512 bytes for the filesystem and 512 bytes for each
file opened).
Available options:
• 512 (WL_SECTOR_SIZE_512)
• 4096 (WL_SECTOR_SIZE_4096)
CONFIG_WL_SECTOR_MODE
Sector store mode
Found in: Component config > Wear Levelling
Specify the mode to store data into flash:
• In Performance mode a data will be stored to the RAM and then stored back to the flash. Compared
to the Safety mode, this operation is faster, but if power will be lost when erase sector operation is
in progress, then the data from complete flash device sector will be lost.
• In Safety mode data from complete flash device sector will be read from flash, modified, and then
stored back to flash. Compared to the Performance mode, this operation is slower, but if power is
lost during erase sector operation, then the data from full flash device sector will not be lost.

Available options:
• Perfomance (WL_SECTOR_MODE_PERF)
• Safety (WL_SECTOR_MODE_SAFE)
Wi-Fi Provisioning Manager Contains:

• CONFIG_WIFI_PROV_BLE_BONDING
• CONFIG_WIFI_PROV_SCAN_MAX_ENTRIES
• CONFIG_WIFI_PROV_AUTOSTOP_TIMEOUT
CONFIG_WIFI_PROV_SCAN_MAX_ENTRIES
Max Wi-Fi Scan Result Entries
Found in: Component config > Wi-Fi Provisioning Manager
This sets the maximum number of entries of Wi-Fi scan results that will be kept by the provisioning
manager
Range:
• from 1 to 255
Default value:
• 16
CONFIG_WIFI_PROV_AUTOSTOP_TIMEOUT
Provisioning auto-stop timeout
Time (in seconds) after which the Wi-Fi provisioning manager will auto-stop after connecting to a Wi-Fi
network successfully.
Range:
• from 5 to 600
Default value:
• 30
CONFIG_WIFI_PROV_BLE_BONDING
Enable BLE bonding
This option is applicable only when provisioning transport is BLE.
Default value:
• No (disabled) if CONFIG_BT_ENABLED
Supplicant Contains:
• CONFIG_WPA_TESTING_OPTIONS
• CONFIG_WPA_11KV_SUPPORT
• CONFIG_WPA_SUITE_B_192
• CONFIG_WPA_WAPI_PSK
• CONFIG_WPA_DEBUG_PRINT
• CONFIG_WPA_WPS_STRICT
• CONFIG_WPA_MBEDTLS_CRYPTO

CONFIG_WPA_MBEDTLS_CRYPTO
Use MbedTLS crypto APIs
Found in: Component config > Supplicant
Select this option to use MbedTLS crypto APIs which utilize hardware acceleration.
Default value:
• Yes (enabled)
CONFIG_WPA_WAPI_PSK
Enable WAPI PSK support
Select this option to enable WAPI-PSK which is a Chinese National Standard Encryption for Wireless
LANs (GB 15629.11-2003).
Default value:
• No (disabled)
CONFIG_WPA_SUITE_B_192
Enable NSA suite B support with 192 bit key
Select this option to enable 192 bit NSA suite-B. This is necessary to support WPA3 192 bit security.
Default value:
• No (disabled)
CONFIG_WPA_DEBUG_PRINT
Print debug messages from WPA Supplicant
Select this option to print logging information from WPA supplicant, this includes handshake information
and key hex dumps depending on the project logging level.
Enabling this could increase the build size ~60kb depending on the project logging level.
Default value:
• No (disabled)
CONFIG_WPA_TESTING_OPTIONS
Add DPP testing code
Select this to enable unity test for DPP.
Default value:
• No (disabled)
CONFIG_WPA_WPS_STRICT
Strictly validate all WPS attributes
Select this option to enable validate each WPS attribute rigorously. Disabling this add the workaorunds
with various APs. Enabling this may cause inter operability issues with some APs.

Default value:
• No (disabled)
CONFIG_WPA_11KV_SUPPORT
Enable 802.11k, 802.11v APIs handling in supplicant
Select this option to enable 802.11k 802.11v APIs(RRM and BTM support). Only APIs which are
helpful for network assisted roaming are supported for now. Enable this option with BTM and RRM
enabled in sta config to make device ready for network assisted roaming. BTM: BSS transition man-
agement enables an AP to request a station to transition to a specific AP, or to indicate to a station a
set of preferred APs. RRM: Radio measurements enable STAs to understand the radio environment,
it enables STAs to observe and gather data on radio link performance and on the radio environment.
Current implementation adds beacon report, link measurement, neighbor report.
Default value:
• No (disabled)
Contains:
• CONFIG_WPA_MBO_SUPPORT
• CONFIG_WPA_SCAN_CACHE
CONFIG_WPA_SCAN_CACHE
Keep scan results in cache
Found in: Component config > Supplicant > CONFIG_WPA_11KV_SUPPORT
Keep scan results in cache, if not enabled, those will be flushed immediately.
Default value:
• No (disabled) if CONFIG_WPA_11KV_SUPPORT
CONFIG_WPA_MBO_SUPPORT
Enable MBO support in supplicant
Found in: Component config > Supplicant > CONFIG_WPA_11KV_SUPPORT
Select this option to enable WiFi Multiband operation certification support.
Default value:
• No (disabled) if CONFIG_WPA_11KV_SUPPORT
Compatibility options
Contains:
• CONFIG_LEGACY_INCLUDE_COMMON_HEADERS
CONFIG_LEGACY_INCLUDE_COMMON_HEADERS
Include headers across components as before IDF v4.0
Found in: Compatibility options
Soc, esp32, and driver components, the most common components. Some header of these components
are included implicitly by headers of other components before IDF v4.0. It s not required for high-level
components, but still included through long header chain everywhere.
This is harmful to the modularity. So it s changed in IDF v4.0.

You can still include these headers in a legacy way until it is totally deprecated by enable this option.
Default value:
• No (disabled)
Deprecated options and their replacements
• CONFIG_A2DP_ENABLE (CONFIG_BT_A2DP_ENABLE)
• CONFIG_A2D_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_A2D_TRACE_LEVEL)
– CONFIG_A2D_TRACE_LEVEL_NONE
– CONFIG_A2D_TRACE_LEVEL_ERROR
– CONFIG_A2D_TRACE_LEVEL_WARNING
– CONFIG_A2D_TRACE_LEVEL_API
– CONFIG_A2D_TRACE_LEVEL_EVENT
– CONFIG_A2D_TRACE_LEVEL_DEBUG
– CONFIG_A2D_TRACE_LEVEL_VERBOSE
• CONFIG_ADC2_DISABLE_DAC (CONFIG_ADC_DISABLE_DAC)
• CONFIG_APPL_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_APPL_TRACE_LEVEL)
– CONFIG_APPL_TRACE_LEVEL_NONE
– CONFIG_APPL_TRACE_LEVEL_ERROR
– CONFIG_APPL_TRACE_LEVEL_WARNING
– CONFIG_APPL_TRACE_LEVEL_API
– CONFIG_APPL_TRACE_LEVEL_EVENT
– CONFIG_APPL_TRACE_LEVEL_DEBUG
– CONFIG_APPL_TRACE_LEVEL_VERBOSE
• CONFIG_APP_ANTI_ROLLBACK (CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK)
• CONFIG_APP_ROLLBACK_ENABLE (CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE)
• CONFIG_APP_SECURE_VERSION (CONFIG_BOOTLOADER_APP_SECURE_VERSION)
• CONFIG_APP_SECURE_VERSION_SIZE_EFUSE_FIELD (CONFIG_BOOTLOADER_APP_SEC_VER_SIZE_EFUSE_FIELD
• CONFIG_AVCT_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_AVCT_TRACE_LEVEL)
– CONFIG_AVCT_TRACE_LEVEL_NONE
– CONFIG_AVCT_TRACE_LEVEL_ERROR
– CONFIG_AVCT_TRACE_LEVEL_WARNING
– CONFIG_AVCT_TRACE_LEVEL_API
– CONFIG_AVCT_TRACE_LEVEL_EVENT
– CONFIG_AVCT_TRACE_LEVEL_DEBUG
– CONFIG_AVCT_TRACE_LEVEL_VERBOSE
• CONFIG_AVDT_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_AVDT_TRACE_LEVEL)
– CONFIG_AVDT_TRACE_LEVEL_NONE
– CONFIG_AVDT_TRACE_LEVEL_ERROR
– CONFIG_AVDT_TRACE_LEVEL_WARNING
– CONFIG_AVDT_TRACE_LEVEL_API
– CONFIG_AVDT_TRACE_LEVEL_EVENT
– CONFIG_AVDT_TRACE_LEVEL_DEBUG
– CONFIG_AVDT_TRACE_LEVEL_VERBOSE
• CONFIG_AVRC_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_AVRC_TRACE_LEVEL)
– CONFIG_AVRC_TRACE_LEVEL_NONE
– CONFIG_AVRC_TRACE_LEVEL_ERROR
– CONFIG_AVRC_TRACE_LEVEL_WARNING
– CONFIG_AVRC_TRACE_LEVEL_API
– CONFIG_AVRC_TRACE_LEVEL_EVENT
– CONFIG_AVRC_TRACE_LEVEL_DEBUG
– CONFIG_AVRC_TRACE_LEVEL_VERBOSE
• CONFIG_BLE_ACTIVE_SCAN_REPORT_ADV_SCAN_RSP_INDIVIDUALLY (CON-
FIG_BT_BLE_ACT_SCAN_REP_ADV_SCAN)
• CONFIG_BLE_ADV_REPORT_DISCARD_THRSHOLD (CONFIG_BTDM_BLE_ADV_REPORT_DISCARD_THRSHOLD)
• CONFIG_BLE_ADV_REPORT_FLOW_CONTROL_NUM (CONFIG_BTDM_BLE_ADV_REPORT_FLOW_CTRL_NUM)

• CONFIG_BLE_ADV_REPORT_FLOW_CONTROL_SUPPORTED (CON-
FIG_BTDM_BLE_ADV_REPORT_FLOW_CTRL_SUPP)
• CONFIG_BLE_ESTABLISH_LINK_CONNECTION_TIMEOUT (CON-
FIG_BT_BLE_ESTAB_LINK_CONN_TOUT)
• CONFIG_BLE_HOST_QUEUE_CONGESTION_CHECK (CONFIG_BT_BLE_HOST_QUEUE_CONG_CHECK)
• CONFIG_BLE_MESH_GATT_PROXY (CONFIG_BLE_MESH_GATT_PROXY_SERVER)
• CONFIG_BLE_MESH_SCAN_DUPLICATE_EN (CONFIG_BTDM_BLE_MESH_SCAN_DUPL_EN)
• CONFIG_BLE_SCAN_DUPLICATE (CONFIG_BTDM_BLE_SCAN_DUPL)
• CONFIG_BLE_SMP_ENABLE (CONFIG_BT_BLE_SMP_ENABLE)
• CONFIG_BLUEDROID_MEM_DEBUG (CONFIG_BT_BLUEDROID_MEM_DEBUG)
• CONFIG_BLUEDROID_PINNED_TO_CORE_CHOICE (CONFIG_BT_BLUEDROID_PINNED_TO_CORE_CHOICE)
– CONFIG_BLUEDROID_PINNED_TO_CORE_0
– CONFIG_BLUEDROID_PINNED_TO_CORE_1
• CONFIG_BLUFI_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_BLUFI_TRACE_LEVEL)
– CONFIG_BLUFI_TRACE_LEVEL_NONE
– CONFIG_BLUFI_TRACE_LEVEL_ERROR
– CONFIG_BLUFI_TRACE_LEVEL_WARNING
– CONFIG_BLUFI_TRACE_LEVEL_API
– CONFIG_BLUFI_TRACE_LEVEL_EVENT
– CONFIG_BLUFI_TRACE_LEVEL_DEBUG
– CONFIG_BLUFI_TRACE_LEVEL_VERBOSE
• CONFIG_BNEP_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_BNEP_TRACE_LEVEL)
• CONFIG_BROWNOUT_DET (CONFIG_ESP32_BROWNOUT_DET)
• CONFIG_BROWNOUT_DET_LVL_SEL (CONFIG_ESP32_BROWNOUT_DET_LVL_SEL)
– CONFIG_BROWNOUT_DET_LVL_SEL_0
• CONFIG_BTC_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_BTC_TRACE_LEVEL)
– CONFIG_BTC_TRACE_LEVEL_NONE
– CONFIG_BTC_TRACE_LEVEL_ERROR
– CONFIG_BTC_TRACE_LEVEL_WARNING
– CONFIG_BTC_TRACE_LEVEL_API
– CONFIG_BTC_TRACE_LEVEL_EVENT
– CONFIG_BTC_TRACE_LEVEL_DEBUG
– CONFIG_BTC_TRACE_LEVEL_VERBOSE
• CONFIG_BTC_TASK_STACK_SIZE (CONFIG_BT_BTC_TASK_STACK_SIZE)
• CONFIG_BTDM_CONTROLLER_BLE_MAX_CONN (CONFIG_BTDM_CTRL_BLE_MAX_CONN)
• CONFIG_BTDM_CONTROLLER_BR_EDR_MAX_ACL_CONN (CON-
FIG_BTDM_CTRL_BR_EDR_MAX_ACL_CONN)
• CONFIG_BTDM_CONTROLLER_BR_EDR_MAX_SYNC_CONN (CON-
FIG_BTDM_CTRL_BR_EDR_MAX_SYNC_CONN)
• CONFIG_BTDM_CONTROLLER_FULL_SCAN_SUPPORTED (CON-
FIG_BTDM_CTRL_FULL_SCAN_SUPPORTED)
• CONFIG_BTDM_CONTROLLER_HCI_MODE_CHOICE (CONFIG_BTDM_CTRL_HCI_MODE_CHOICE)
– CONFIG_BTDM_CONTROLLER_HCI_MODE_VHCI
– CONFIG_BTDM_CONTROLLER_HCI_MODE_UART_H4
• CONFIG_BTDM_CONTROLLER_MODE (CONFIG_BTDM_CTRL_MODE)
– CONFIG_BTDM_CONTROLLER_MODE_BLE_ONLY
– CONFIG_BTDM_CONTROLLER_MODE_BR_EDR_ONLY
– CONFIG_BTDM_CONTROLLER_MODE_BTDM
• CONFIG_BTDM_CONTROLLER_MODEM_SLEEP (CONFIG_BTDM_CTRL_MODEM_SLEEP)

• CONFIG_BTDM_CONTROLLER_PINNED_TO_CORE_CHOICE (CON-
FIG_BTDM_CTRL_PINNED_TO_CORE_CHOICE)
• CONFIG_BTH_LOG_SDP_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_SDP_TRACE_LEVEL)
– CONFIG_SDP_TRACE_LEVEL_NONE
– CONFIG_SDP_TRACE_LEVEL_ERROR
– CONFIG_SDP_TRACE_LEVEL_WARNING
– CONFIG_SDP_TRACE_LEVEL_API
– CONFIG_SDP_TRACE_LEVEL_EVENT
– CONFIG_SDP_TRACE_LEVEL_DEBUG
– CONFIG_SDP_TRACE_LEVEL_VERBOSE
• CONFIG_BTIF_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_BTIF_TRACE_LEVEL)
– CONFIG_BTIF_TRACE_LEVEL_NONE
– CONFIG_BTIF_TRACE_LEVEL_ERROR
– CONFIG_BTIF_TRACE_LEVEL_WARNING
– CONFIG_BTIF_TRACE_LEVEL_API
– CONFIG_BTIF_TRACE_LEVEL_EVENT
– CONFIG_BTIF_TRACE_LEVEL_DEBUG
– CONFIG_BTIF_TRACE_LEVEL_VERBOSE
• CONFIG_BTM_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_BTM_TRACE_LEVEL)
– CONFIG_BTM_TRACE_LEVEL_NONE
– CONFIG_BTM_TRACE_LEVEL_ERROR
– CONFIG_BTM_TRACE_LEVEL_WARNING
– CONFIG_BTM_TRACE_LEVEL_API
– CONFIG_BTM_TRACE_LEVEL_EVENT
– CONFIG_BTM_TRACE_LEVEL_DEBUG
– CONFIG_BTM_TRACE_LEVEL_VERBOSE
• CONFIG_BTU_TASK_STACK_SIZE (CONFIG_BT_BTU_TASK_STACK_SIZE)
• CONFIG_CLASSIC_BT_ENABLED (CONFIG_BT_CLASSIC_ENABLED)
• CONFIG_COMPATIBLE_PRE_V2_1_BOOTLOADERS (CONFIG_ESP32_COMPATIBLE_PRE_V2_1_BOOTLOADERS)
• CONFIG_CONSOLE_UART (CONFIG_ESP_CONSOLE_UART)
– CONFIG_CONSOLE_UART_DEFAULT
– CONFIG_CONSOLE_UART_CUSTOM
– CONFIG_ESP_CONSOLE_UART_NONE
• CONFIG_CONSOLE_UART_BAUDRATE (CONFIG_ESP_CONSOLE_UART_BAUDRATE)
• CONFIG_CONSOLE_UART_NUM (CONFIG_ESP_CONSOLE_UART_NUM)
– CONFIG_CONSOLE_UART_CUSTOM_NUM_0
– CONFIG_CONSOLE_UART_CUSTOM_NUM_1
• CONFIG_CONSOLE_UART_RX_GPIO (CONFIG_ESP_CONSOLE_UART_RX_GPIO)
• CONFIG_CONSOLE_UART_TX_GPIO (CONFIG_ESP_CONSOLE_UART_TX_GPIO)
• CONFIG_CXX_EXCEPTIONS (CONFIG_COMPILER_CXX_EXCEPTIONS)
• CONFIG_CXX_EXCEPTIONS_EMG_POOL_SIZE (CONFIG_COMPILER_CXX_EXCEPTIONS_EMG_POOL_SIZE)
• CONFIG_DISABLE_BASIC_ROM_CONSOLE (CONFIG_ESP32_DISABLE_BASIC_ROM_CONSOLE)
• CONFIG_DISABLE_GCC8_WARNINGS (CONFIG_COMPILER_DISABLE_GCC8_WARNINGS)
• CONFIG_DUPLICATE_SCAN_CACHE_SIZE (CONFIG_BTDM_SCAN_DUPL_CACHE_SIZE)
• CONFIG_EFUSE_SECURE_VERSION_EMULATE (CONFIG_BOOTLOADER_EFUSE_SECURE_VERSION_EMULATE)
• CONFIG_ENABLE_STATIC_TASK_CLEAN_UP_HOOK (CONFIG_FREERTOS_ENABLE_STATIC_TASK_CLEAN_UP)
• CONFIG_ESP32C3_LIGHTSLEEP_GPIO_RESET_WORKAROUND (CON-
FIG_ESP_SLEEP_GPIO_RESET_WORKAROUND)
• CONFIG_ESP32C3_MEMPROT_FEATURE (CONFIG_ESP_SYSTEM_MEMPROT_FEATURE)
• CONFIG_ESP32C3_MEMPROT_FEATURE_LOCK (CONFIG_ESP_SYSTEM_MEMPROT_FEATURE_LOCK)
• CONFIG_ESP32H2_MEMPROT_FEATURE (CONFIG_ESP_SYSTEM_MEMPROT_FEATURE)
• CONFIG_ESP32H2_MEMPROT_FEATURE_LOCK (CONFIG_ESP_SYSTEM_MEMPROT_FEATURE_LOCK)
• CONFIG_ESP32S2_ALLOW_RTC_FAST_MEM_AS_HEAP (CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEA
• CONFIG_ESP32S2_MEMPROT_FEATURE (CONFIG_ESP_SYSTEM_MEMPROT_FEATURE)
• CONFIG_ESP32S2_MEMPROT_FEATURE_LOCK (CONFIG_ESP_SYSTEM_MEMPROT_FEATURE_LOCK)
• CONFIG_ESP32S2_PANIC (CONFIG_ESP_SYSTEM_PANIC)
– CONFIG_ESP32S2_PANIC_PRINT_HALT
– CONFIG_ESP32S2_PANIC_PRINT_REBOOT

– CONFIG_ESP32S2_PANIC_SILENT_REBOOT
– CONFIG_ESP32S2_PANIC_GDBSTUB
• CONFIG_ESP32_ALLOW_RTC_FAST_MEM_AS_HEAP (CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP)
• CONFIG_ESP32_APPTRACE_DESTINATION (CONFIG_APPTRACE_DESTINATION)
– CONFIG_ESP32_APPTRACE_DEST_TRAX
– CONFIG_ESP32_APPTRACE_DEST_NONE
• CONFIG_ESP32_APPTRACE_ONPANIC_HOST_FLUSH_TMO (CON-
FIG_APPTRACE_ONPANIC_HOST_FLUSH_TMO)
• CONFIG_ESP32_APPTRACE_PENDING_DATA_SIZE_MAX (CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX)
• CONFIG_ESP32_APPTRACE_POSTMORTEM_FLUSH_TRAX_THRESH (CON-
FIG_APPTRACE_POSTMORTEM_FLUSH_THRESH)
• CONFIG_ESP32_CORE_DUMP_DECODE (CONFIG_ESP_COREDUMP_DECODE)
– CONFIG_ESP32_CORE_DUMP_DECODE_INFO
– CONFIG_ESP32_CORE_DUMP_DECODE_DISABLE
• CONFIG_ESP32_CORE_DUMP_MAX_TASKS_NUM (CONFIG_ESP_COREDUMP_MAX_TASKS_NUM)
• CONFIG_ESP32_CORE_DUMP_UART_DELAY (CONFIG_ESP_COREDUMP_UART_DELAY)
• CONFIG_ESP32_DEBUG_STUBS_ENABLE (CONFIG_ESP_DEBUG_STUBS_ENABLE)
• CONFIG_ESP32_GCOV_ENABLE (CONFIG_APPTRACE_GCOV_ENABLE)
• CONFIG_ESP32_PANIC (CONFIG_ESP_SYSTEM_PANIC)
– CONFIG_ESP32S2_PANIC_PRINT_HALT
– CONFIG_ESP32S2_PANIC_PRINT_REBOOT
– CONFIG_ESP32S2_PANIC_SILENT_REBOOT
– CONFIG_ESP32S2_PANIC_GDBSTUB
• CONFIG_ESP32_PHY_CALIBRATION_AND_DATA_STORAGE (CON-
FIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE)
• CONFIG_ESP32_PHY_DEFAULT_INIT_IF_INVALID (CONFIG_ESP_PHY_DEFAULT_INIT_IF_INVALID)
• CONFIG_ESP32_PHY_INIT_DATA_ERROR (CONFIG_ESP_PHY_INIT_DATA_ERROR)
• CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION (CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION)
• CONFIG_ESP32_PHY_MAX_WIFI_TX_POWER (CONFIG_ESP_PHY_MAX_WIFI_TX_POWER)
• CONFIG_ESP32_PTHREAD_STACK_MIN (CONFIG_PTHREAD_STACK_MIN)
• CONFIG_ESP32_PTHREAD_TASK_CORE_DEFAULT (CONFIG_PTHREAD_TASK_CORE_DEFAULT)
– CONFIG_ESP32_DEFAULT_PTHREAD_CORE_NO_AFFINITY
– CONFIG_ESP32_DEFAULT_PTHREAD_CORE_0
– CONFIG_ESP32_DEFAULT_PTHREAD_CORE_1
• CONFIG_ESP32_PTHREAD_TASK_NAME_DEFAULT (CONFIG_PTHREAD_TASK_NAME_DEFAULT)
• CONFIG_ESP32_PTHREAD_TASK_PRIO_DEFAULT (CONFIG_PTHREAD_TASK_PRIO_DEFAULT)
• CONFIG_ESP32_PTHREAD_TASK_STACK_SIZE_DEFAULT (CONFIG_PTHREAD_TASK_STACK_SIZE_DEFAULT)
• CONFIG_ESP32_REDUCE_PHY_TX_POWER (CONFIG_ESP_PHY_REDUCE_TX_POWER)
• CONFIG_ESP32_RTC_CLOCK_SOURCE (CONFIG_ESP32_RTC_CLK_SRC)
– CONFIG_ESP32_RTC_CLOCK_SOURCE_INTERNAL_RC
– CONFIG_ESP32_RTC_CLOCK_SOURCE_EXTERNAL_CRYSTAL
– CONFIG_ESP32_RTC_CLOCK_SOURCE_EXTERNAL_OSC
– CONFIG_ESP32_RTC_CLOCK_SOURCE_INTERNAL_8MD256
• CONFIG_ESP32_RTC_XTAL_BOOTSTRAP_CYCLES (CONFIG_ESP_SYSTEM_RTC_EXT_XTAL_BOOTSTRAP_CYCLES)
• CONFIG_ESP32_SUPPORT_MULTIPLE_PHY_INIT_DATA_BIN (CON-
FIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN)
• CONFIG_ESP_GRATUITOUS_ARP (CONFIG_LWIP_ESP_GRATUITOUS_ARP)
• CONFIG_ESP_SYSTEM_PD_FLASH (CONFIG_ESP_SLEEP_POWER_DOWN_FLASH)
• CONFIG_ESP_TCP_KEEP_CONNECTION_WHEN_IP_CHANGES (CON-
FIG_LWIP_TCP_KEEP_CONNECTION_WHEN_IP_CHANGES)
• CONFIG_EVENT_LOOP_PROFILING (CONFIG_ESP_EVENT_LOOP_PROFILING)
• CONFIG_FLASH_ENCRYPTION_ENABLED (CONFIG_SECURE_FLASH_ENC_ENABLED)
• CONFIG_FLASH_ENCRYPTION_UART_BOOTLOADER_ALLOW_CACHE (CON-
FIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_CACHE)
• CONFIG_FLASH_ENCRYPTION_UART_BOOTLOADER_ALLOW_DECRYPT (CON-
FIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_DEC)
• CONFIG_FLASH_ENCRYPTION_UART_BOOTLOADER_ALLOW_ENCRYPT (CON-

FIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_ENC)
• CONFIG_GAP_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_GAP_TRACE_LEVEL)
– CONFIG_GAP_TRACE_LEVEL_NONE
– CONFIG_GAP_TRACE_LEVEL_ERROR
– CONFIG_GAP_TRACE_LEVEL_WARNING
– CONFIG_GAP_TRACE_LEVEL_API
– CONFIG_GAP_TRACE_LEVEL_EVENT
– CONFIG_GAP_TRACE_LEVEL_DEBUG
– CONFIG_GAP_TRACE_LEVEL_VERBOSE
• CONFIG_GARP_TMR_INTERVAL (CONFIG_LWIP_GARP_TMR_INTERVAL)
• CONFIG_GATTC_CACHE_NVS_FLASH (CONFIG_BT_GATTC_CACHE_NVS_FLASH)
• CONFIG_GATTC_ENABLE (CONFIG_BT_GATTC_ENABLE)
• CONFIG_GATTS_ENABLE (CONFIG_BT_GATTS_ENABLE)
• CONFIG_GATTS_SEND_SERVICE_CHANGE_MODE (CONFIG_BT_GATTS_SEND_SERVICE_CHANGE_MODE)
– CONFIG_GATTS_SEND_SERVICE_CHANGE_MANUAL
– CONFIG_GATTS_SEND_SERVICE_CHANGE_AUTO
• CONFIG_GATT_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_GATT_TRACE_LEVEL)
– CONFIG_GATT_TRACE_LEVEL_NONE
– CONFIG_GATT_TRACE_LEVEL_ERROR
– CONFIG_GATT_TRACE_LEVEL_WARNING
– CONFIG_GATT_TRACE_LEVEL_API
– CONFIG_GATT_TRACE_LEVEL_EVENT
– CONFIG_GATT_TRACE_LEVEL_DEBUG
– CONFIG_GATT_TRACE_LEVEL_VERBOSE
• CONFIG_GDBSTUB_MAX_TASKS (CONFIG_ESP_GDBSTUB_MAX_TASKS)
• CONFIG_GDBSTUB_SUPPORT_TASKS (CONFIG_ESP_GDBSTUB_SUPPORT_TASKS)
• CONFIG_HCI_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_HCI_TRACE_LEVEL)
– CONFIG_HCI_TRACE_LEVEL_NONE
– CONFIG_HCI_TRACE_LEVEL_ERROR
– CONFIG_HCI_TRACE_LEVEL_WARNING
– CONFIG_HCI_TRACE_LEVEL_API
– CONFIG_HCI_TRACE_LEVEL_EVENT
– CONFIG_HCI_TRACE_LEVEL_DEBUG
– CONFIG_HCI_TRACE_LEVEL_VERBOSE
• CONFIG_HFP_AUDIO_DATA_PATH (CONFIG_BT_HFP_AUDIO_DATA_PATH)
– CONFIG_HFP_AUDIO_DATA_PATH_PCM
– CONFIG_HFP_AUDIO_DATA_PATH_HCI
• CONFIG_HFP_ENABLE (CONFIG_BT_HFP_ENABLE)
• CONFIG_HFP_ROLE (CONFIG_BT_HFP_ROLE)
– CONFIG_HFP_CLIENT_ENABLE
– CONFIG_HFP_AG_ENABLE
• CONFIG_HID_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_HID_TRACE_LEVEL)
– CONFIG_HID_TRACE_LEVEL_NONE
– CONFIG_HID_TRACE_LEVEL_ERROR
– CONFIG_HID_TRACE_LEVEL_WARNING
– CONFIG_HID_TRACE_LEVEL_API
– CONFIG_HID_TRACE_LEVEL_EVENT
– CONFIG_HID_TRACE_LEVEL_DEBUG
– CONFIG_HID_TRACE_LEVEL_VERBOSE
• CONFIG_INT_WDT (CONFIG_ESP_INT_WDT)
• CONFIG_INT_WDT_CHECK_CPU1 (CONFIG_ESP_INT_WDT_CHECK_CPU1)
• CONFIG_INT_WDT_TIMEOUT_MS (CONFIG_ESP_INT_WDT_TIMEOUT_MS)
• CONFIG_IPC_TASK_STACK_SIZE (CONFIG_ESP_IPC_TASK_STACK_SIZE)
• CONFIG_L2CAP_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_L2CAP_TRACE_LEVEL)
– CONFIG_L2CAP_TRACE_LEVEL_NONE
– CONFIG_L2CAP_TRACE_LEVEL_ERROR
– CONFIG_L2CAP_TRACE_LEVEL_WARNING

– CONFIG_L2CAP_TRACE_LEVEL_API
– CONFIG_L2CAP_TRACE_LEVEL_EVENT
– CONFIG_L2CAP_TRACE_LEVEL_DEBUG
– CONFIG_L2CAP_TRACE_LEVEL_VERBOSE
• CONFIG_L2_TO_L3_COPY (CONFIG_LWIP_L2_TO_L3_COPY)
• CONFIG_LOG_BOOTLOADER_LEVEL (CONFIG_BOOTLOADER_LOG_LEVEL)
– CONFIG_LOG_BOOTLOADER_LEVEL_NONE
– CONFIG_LOG_BOOTLOADER_LEVEL_ERROR
– CONFIG_LOG_BOOTLOADER_LEVEL_WARN
– CONFIG_LOG_BOOTLOADER_LEVEL_INFO
– CONFIG_LOG_BOOTLOADER_LEVEL_DEBUG
– CONFIG_LOG_BOOTLOADER_LEVEL_VERBOSE
• CONFIG_MAIN_TASK_STACK_SIZE (CONFIG_ESP_MAIN_TASK_STACK_SIZE)
• CONFIG_MB_CONTROLLER_NOTIFY_QUEUE_SIZE (CONFIG_FMB_CONTROLLER_NOTIFY_QUEUE_SIZE)
• CONFIG_MB_CONTROLLER_NOTIFY_TIMEOUT (CONFIG_FMB_CONTROLLER_NOTIFY_TIMEOUT)
• CONFIG_MB_CONTROLLER_SLAVE_ID (CONFIG_FMB_CONTROLLER_SLAVE_ID)
• CONFIG_MB_CONTROLLER_SLAVE_ID_SUPPORT (CONFIG_FMB_CONTROLLER_SLAVE_ID_SUPPORT)
• CONFIG_MB_CONTROLLER_STACK_SIZE (CONFIG_FMB_CONTROLLER_STACK_SIZE)
• CONFIG_MB_EVENT_QUEUE_TIMEOUT (CONFIG_FMB_EVENT_QUEUE_TIMEOUT)
• CONFIG_MB_MASTER_DELAY_MS_CONVERT (CONFIG_FMB_MASTER_DELAY_MS_CONVERT)
• CONFIG_MB_MASTER_TIMEOUT_MS_RESPOND (CONFIG_FMB_MASTER_TIMEOUT_MS_RESPOND)
• CONFIG_MB_QUEUE_LENGTH (CONFIG_FMB_QUEUE_LENGTH)
• CONFIG_MB_SERIAL_BUF_SIZE (CONFIG_FMB_SERIAL_BUF_SIZE)
• CONFIG_MB_SERIAL_TASK_PRIO (CONFIG_FMB_PORT_TASK_PRIO)
• CONFIG_MB_SERIAL_TASK_STACK_SIZE (CONFIG_FMB_PORT_TASK_STACK_SIZE)
• CONFIG_MB_TIMER_PORT_ENABLED (CONFIG_FMB_TIMER_PORT_ENABLED)
• CONFIG_MCA_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_MCA_TRACE_LEVEL)
– CONFIG_MCA_TRACE_LEVEL_NONE
– CONFIG_MCA_TRACE_LEVEL_ERROR
– CONFIG_MCA_TRACE_LEVEL_WARNING
– CONFIG_MCA_TRACE_LEVEL_API
– CONFIG_MCA_TRACE_LEVEL_EVENT
– CONFIG_MCA_TRACE_LEVEL_DEBUG
– CONFIG_MCA_TRACE_LEVEL_VERBOSE
• CONFIG_MESH_DUPLICATE_SCAN_CACHE_SIZE (CONFIG_BTDM_MESH_DUPL_SCAN_CACHE_SIZE)
• CONFIG_MONITOR_BAUD (CONFIG_ESPTOOLPY_MONITOR_BAUD)
– CONFIG_MONITOR_BAUD_9600B
– CONFIG_MONITOR_BAUD_2MB
– CONFIG_MONITOR_BAUD_OTHER
• CONFIG_MONITOR_BAUD_OTHER_VAL (CONFIG_ESPTOOLPY_MONITOR_BAUD_OTHER_VAL)
• CONFIG_NIMBLE_ACL_BUF_COUNT (CONFIG_BT_NIMBLE_ACL_BUF_COUNT)
• CONFIG_NIMBLE_ACL_BUF_SIZE (CONFIG_BT_NIMBLE_ACL_BUF_SIZE)
• CONFIG_NIMBLE_ATT_PREFERRED_MTU (CONFIG_BT_NIMBLE_ATT_PREFERRED_MTU)
• CONFIG_NIMBLE_CRYPTO_STACK_MBEDTLS (CONFIG_BT_NIMBLE_CRYPTO_STACK_MBEDTLS)
• CONFIG_NIMBLE_DEBUG (CONFIG_BT_NIMBLE_DEBUG)
• CONFIG_NIMBLE_GAP_DEVICE_NAME_MAX_LEN (CONFIG_BT_NIMBLE_GAP_DEVICE_NAME_MAX_LEN)
• CONFIG_NIMBLE_HCI_EVT_BUF_SIZE (CONFIG_BT_NIMBLE_HCI_EVT_BUF_SIZE)
• CONFIG_NIMBLE_HCI_EVT_HI_BUF_COUNT (CONFIG_BT_NIMBLE_HCI_EVT_HI_BUF_COUNT)
• CONFIG_NIMBLE_HCI_EVT_LO_BUF_COUNT (CONFIG_BT_NIMBLE_HCI_EVT_LO_BUF_COUNT)
• CONFIG_NIMBLE_HS_FLOW_CTRL (CONFIG_BT_NIMBLE_HS_FLOW_CTRL)
• CONFIG_NIMBLE_HS_FLOW_CTRL_ITVL (CONFIG_BT_NIMBLE_HS_FLOW_CTRL_ITVL)
• CONFIG_NIMBLE_HS_FLOW_CTRL_THRESH (CONFIG_BT_NIMBLE_HS_FLOW_CTRL_THRESH)
• CONFIG_NIMBLE_HS_FLOW_CTRL_TX_ON_DISCONNECT (CON-
FIG_BT_NIMBLE_HS_FLOW_CTRL_TX_ON_DISCONNECT)

• CONFIG_NIMBLE_L2CAP_COC_MAX_NUM (CONFIG_BT_NIMBLE_L2CAP_COC_MAX_NUM)
• CONFIG_NIMBLE_MAX_BONDS (CONFIG_BT_NIMBLE_MAX_BONDS)
• CONFIG_NIMBLE_MAX_CCCDS (CONFIG_BT_NIMBLE_MAX_CCCDS)
• CONFIG_NIMBLE_MAX_CONNECTIONS (CONFIG_BT_NIMBLE_MAX_CONNECTIONS)
• CONFIG_NIMBLE_MEM_ALLOC_MODE (CONFIG_BT_NIMBLE_MEM_ALLOC_MODE)
– CONFIG_NIMBLE_MEM_ALLOC_MODE_INTERNAL
– CONFIG_NIMBLE_MEM_ALLOC_MODE_EXTERNAL
– CONFIG_NIMBLE_MEM_ALLOC_MODE_DEFAULT
• CONFIG_NIMBLE_MESH (CONFIG_BT_NIMBLE_MESH)
• CONFIG_NIMBLE_MESH_DEVICE_NAME (CONFIG_BT_NIMBLE_MESH_DEVICE_NAME)
• CONFIG_NIMBLE_MESH_FRIEND (CONFIG_BT_NIMBLE_MESH_FRIEND)
• CONFIG_NIMBLE_MESH_GATT_PROXY (CONFIG_BT_NIMBLE_MESH_GATT_PROXY)
• CONFIG_NIMBLE_MESH_LOW_POWER (CONFIG_BT_NIMBLE_MESH_LOW_POWER)
• CONFIG_NIMBLE_MESH_PB_ADV (CONFIG_BT_NIMBLE_MESH_PB_ADV)
• CONFIG_NIMBLE_MESH_PB_GATT (CONFIG_BT_NIMBLE_MESH_PB_GATT)
• CONFIG_NIMBLE_MESH_PROV (CONFIG_BT_NIMBLE_MESH_PROV)
• CONFIG_NIMBLE_MESH_PROXY (CONFIG_BT_NIMBLE_MESH_PROXY)
• CONFIG_NIMBLE_MESH_RELAY (CONFIG_BT_NIMBLE_MESH_RELAY)
• CONFIG_NIMBLE_MSYS1_BLOCK_COUNT (CONFIG_BT_NIMBLE_MSYS1_BLOCK_COUNT)
• CONFIG_NIMBLE_NVS_PERSIST (CONFIG_BT_NIMBLE_NVS_PERSIST)
• CONFIG_NIMBLE_PINNED_TO_CORE_CHOICE (CONFIG_BT_NIMBLE_PINNED_TO_CORE_CHOICE)
– CONFIG_NIMBLE_PINNED_TO_CORE_0
– CONFIG_NIMBLE_PINNED_TO_CORE_1
• CONFIG_NIMBLE_ROLE_BROADCASTER (CONFIG_BT_NIMBLE_ROLE_BROADCASTER)
• CONFIG_NIMBLE_ROLE_CENTRAL (CONFIG_BT_NIMBLE_ROLE_CENTRAL)
• CONFIG_NIMBLE_ROLE_OBSERVER (CONFIG_BT_NIMBLE_ROLE_OBSERVER)
• CONFIG_NIMBLE_ROLE_PERIPHERAL (CONFIG_BT_NIMBLE_ROLE_PERIPHERAL)
• CONFIG_NIMBLE_RPA_TIMEOUT (CONFIG_BT_NIMBLE_RPA_TIMEOUT)
• CONFIG_NIMBLE_SM_LEGACY (CONFIG_BT_NIMBLE_SM_LEGACY)
• CONFIG_NIMBLE_SM_SC (CONFIG_BT_NIMBLE_SM_SC)
• CONFIG_NIMBLE_SM_SC_DEBUG_KEYS (CONFIG_BT_NIMBLE_SM_SC_DEBUG_KEYS)
• CONFIG_NIMBLE_SVC_GAP_APPEARANCE (CONFIG_BT_NIMBLE_SVC_GAP_APPEARANCE)
• CONFIG_NIMBLE_SVC_GAP_DEVICE_NAME (CONFIG_BT_NIMBLE_SVC_GAP_DEVICE_NAME)
• CONFIG_NIMBLE_TASK_STACK_SIZE (CONFIG_BT_NIMBLE_TASK_STACK_SIZE)
• CONFIG_NO_BLOBS (CONFIG_ESP32_NO_BLOBS)
• CONFIG_NUMBER_OF_UNIVERSAL_MAC_ADDRESS (CONFIG_ESP32_UNIVERSAL_MAC_ADDRESSES)
– CONFIG_TWO_UNIVERSAL_MAC_ADDRESS
– CONFIG_FOUR_UNIVERSAL_MAC_ADDRESS
• CONFIG_OPTIMIZATION_ASSERTION_LEVEL (CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL)
– CONFIG_OPTIMIZATION_ASSERTIONS_ENABLED
– CONFIG_OPTIMIZATION_ASSERTIONS_SILENT
– CONFIG_OPTIMIZATION_ASSERTIONS_DISABLED
• CONFIG_OPTIMIZATION_COMPILER (CONFIG_COMPILER_OPTIMIZATION)
– CONFIG_COMPILER_OPTIMIZATION_LEVEL_DEBUG
– CONFIG_COMPILER_OPTIMIZATION_LEVEL_RELEASE
• CONFIG_OSI_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_OSI_TRACE_LEVEL)
– CONFIG_OSI_TRACE_LEVEL_NONE
– CONFIG_OSI_TRACE_LEVEL_ERROR
– CONFIG_OSI_TRACE_LEVEL_WARNING
– CONFIG_OSI_TRACE_LEVEL_API
– CONFIG_OSI_TRACE_LEVEL_EVENT
– CONFIG_OSI_TRACE_LEVEL_DEBUG
– CONFIG_OSI_TRACE_LEVEL_VERBOSE
• CONFIG_PAN_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_PAN_TRACE_LEVEL)
– CONFIG_PAN_TRACE_LEVEL_NONE

– CONFIG_PAN_TRACE_LEVEL_ERROR
– CONFIG_PAN_TRACE_LEVEL_WARNING
– CONFIG_PAN_TRACE_LEVEL_API
– CONFIG_PAN_TRACE_LEVEL_EVENT
– CONFIG_PAN_TRACE_LEVEL_DEBUG
– CONFIG_PAN_TRACE_LEVEL_VERBOSE
• CONFIG_POST_EVENTS_FROM_IRAM_ISR (CONFIG_ESP_EVENT_POST_FROM_IRAM_ISR)
• CONFIG_POST_EVENTS_FROM_ISR (CONFIG_ESP_EVENT_POST_FROM_ISR)
• CONFIG_PPP_CHAP_SUPPORT (CONFIG_LWIP_PPP_CHAP_SUPPORT)
• CONFIG_PPP_DEBUG_ON (CONFIG_LWIP_PPP_DEBUG_ON)
• CONFIG_PPP_MPPE_SUPPORT (CONFIG_LWIP_PPP_MPPE_SUPPORT)
• CONFIG_PPP_MSCHAP_SUPPORT (CONFIG_LWIP_PPP_MSCHAP_SUPPORT)
• CONFIG_PPP_NOTIFY_PHASE_SUPPORT (CONFIG_LWIP_PPP_NOTIFY_PHASE_SUPPORT)
• CONFIG_PPP_PAP_SUPPORT (CONFIG_LWIP_PPP_PAP_SUPPORT)
• CONFIG_PPP_SUPPORT (CONFIG_LWIP_PPP_SUPPORT)
• CONFIG_REDUCE_PHY_TX_POWER (CONFIG_ESP_PHY_REDUCE_TX_POWER)
• CONFIG_RFCOMM_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_RFCOMM_TRACE_LEVEL)
– CONFIG_RFCOMM_TRACE_LEVEL_NONE
– CONFIG_RFCOMM_TRACE_LEVEL_ERROR
– CONFIG_RFCOMM_TRACE_LEVEL_WARNING
– CONFIG_RFCOMM_TRACE_LEVEL_API
– CONFIG_RFCOMM_TRACE_LEVEL_EVENT
– CONFIG_RFCOMM_TRACE_LEVEL_DEBUG
– CONFIG_RFCOMM_TRACE_LEVEL_VERBOSE
• CONFIG_SCAN_DUPLICATE_TYPE (CONFIG_BTDM_SCAN_DUPL_TYPE)
– CONFIG_SCAN_DUPLICATE_BY_DEVICE_ADDR
– CONFIG_SCAN_DUPLICATE_BY_ADV_DATA
– CONFIG_SCAN_DUPLICATE_BY_ADV_DATA_AND_DEVICE_ADDR
• CONFIG_SEMIHOSTFS_HOST_PATH_MAX_LEN (CONFIG_VFS_SEMIHOSTFS_HOST_PATH_MAX_LEN)
• CONFIG_SEMIHOSTFS_MAX_MOUNT_POINTS (CONFIG_VFS_SEMIHOSTFS_MAX_MOUNT_POINTS)
• CONFIG_SMP_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_SMP_TRACE_LEVEL)
– CONFIG_SMP_TRACE_LEVEL_NONE
– CONFIG_SMP_TRACE_LEVEL_ERROR
– CONFIG_SMP_TRACE_LEVEL_WARNING
– CONFIG_SMP_TRACE_LEVEL_API
– CONFIG_SMP_TRACE_LEVEL_EVENT
– CONFIG_SMP_TRACE_LEVEL_DEBUG
– CONFIG_SMP_TRACE_LEVEL_VERBOSE
• CONFIG_SMP_SLAVE_CON_PARAMS_UPD_ENABLE (CONFIG_BT_SMP_SLAVE_CON_PARAMS_UPD_ENABLE)
• CONFIG_SPIRAM_SUPPORT (CONFIG_ESP32_SPIRAM_SUPPORT)
• CONFIG_SPI_FLASH_WRITING_DANGEROUS_REGIONS (CONFIG_SPI_FLASH_DANGEROUS_WRITE)
– CONFIG_SPI_FLASH_WRITING_DANGEROUS_REGIONS_ABORTS
– CONFIG_SPI_FLASH_WRITING_DANGEROUS_REGIONS_FAILS
– CONFIG_SPI_FLASH_WRITING_DANGEROUS_REGIONS_ALLOWED
• CONFIG_STACK_CHECK_MODE (CONFIG_COMPILER_STACK_CHECK_MODE)
– CONFIG_STACK_CHECK_NONE
– CONFIG_STACK_CHECK_NORM
– CONFIG_STACK_CHECK_STRONG
– CONFIG_STACK_CHECK_ALL
• CONFIG_SUPPORT_TERMIOS (CONFIG_VFS_SUPPORT_TERMIOS)
• CONFIG_SUPPRESS_SELECT_DEBUG_OUTPUT (CONFIG_VFS_SUPPRESS_SELECT_DEBUG_OUTPUT)
• CONFIG_SW_COEXIST_ENABLE (CONFIG_ESP32_WIFI_SW_COEXIST_ENABLE)
• CONFIG_SYSTEM_EVENT_QUEUE_SIZE (CONFIG_ESP_SYSTEM_EVENT_QUEUE_SIZE)
• CONFIG_SYSTEM_EVENT_TASK_STACK_SIZE (CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE)
• CONFIG_SYSVIEW_BUF_WAIT_TMO (CONFIG_APPTRACE_SV_BUF_WAIT_TMO)
• CONFIG_SYSVIEW_ENABLE (CONFIG_APPTRACE_SV_ENABLE)
• CONFIG_SYSVIEW_EVT_IDLE_ENABLE (CONFIG_APPTRACE_SV_EVT_IDLE_ENABLE)

• CONFIG_SYSVIEW_EVT_ISR_ENTER_ENABLE (CONFIG_APPTRACE_SV_EVT_ISR_ENTER_ENABLE)
• CONFIG_SYSVIEW_EVT_ISR_EXIT_ENABLE (CONFIG_APPTRACE_SV_EVT_ISR_EXIT_ENABLE)
• CONFIG_SYSVIEW_EVT_ISR_TO_SCHEDULER_ENABLE (CONFIG_APPTRACE_SV_EVT_ISR_TO_SCHED_ENABLE)
• CONFIG_SYSVIEW_EVT_OVERFLOW_ENABLE (CONFIG_APPTRACE_SV_EVT_OVERFLOW_ENABLE)
• CONFIG_SYSVIEW_EVT_TASK_CREATE_ENABLE (CONFIG_APPTRACE_SV_EVT_TASK_CREATE_ENABLE)
• CONFIG_SYSVIEW_EVT_TASK_START_EXEC_ENABLE (CONFIG_APPTRACE_SV_EVT_TASK_START_EXEC_ENABL
• CONFIG_SYSVIEW_EVT_TASK_START_READY_ENABLE (CONFIG_APPTRACE_SV_EVT_TASK_START_READY_ENA
• CONFIG_SYSVIEW_EVT_TASK_STOP_EXEC_ENABLE (CONFIG_APPTRACE_SV_EVT_TASK_STOP_EXEC_ENABLE)
• CONFIG_SYSVIEW_EVT_TASK_STOP_READY_ENABLE (CONFIG_APPTRACE_SV_EVT_TASK_STOP_READY_ENABL
• CONFIG_SYSVIEW_EVT_TASK_TERMINATE_ENABLE (CONFIG_APPTRACE_SV_EVT_TASK_TERMINATE_ENABLE)
• CONFIG_SYSVIEW_EVT_TIMER_ENTER_ENABLE (CONFIG_APPTRACE_SV_EVT_TIMER_ENTER_ENABLE)
• CONFIG_SYSVIEW_EVT_TIMER_EXIT_ENABLE (CONFIG_APPTRACE_SV_EVT_TIMER_EXIT_ENABLE)
• CONFIG_SYSVIEW_MAX_TASKS (CONFIG_APPTRACE_SV_MAX_TASKS)
• CONFIG_SYSVIEW_TS_SOURCE (CONFIG_APPTRACE_SV_TS_SOURCE)
– CONFIG_SYSVIEW_TS_SOURCE_CCOUNT
– CONFIG_SYSVIEW_TS_SOURCE_TIMER_00
– CONFIG_SYSVIEW_TS_SOURCE_ESP_TIMER
• CONFIG_TASK_WDT (CONFIG_ESP_TASK_WDT)
• CONFIG_TASK_WDT_CHECK_IDLE_TASK_CPU0 (CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0)
• CONFIG_TASK_WDT_CHECK_IDLE_TASK_CPU1 (CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1)
• CONFIG_TASK_WDT_PANIC (CONFIG_ESP_TASK_WDT_PANIC)
• CONFIG_TASK_WDT_TIMEOUT_S (CONFIG_ESP_TASK_WDT_TIMEOUT_S)
• CONFIG_TCPIP_RECVMBOX_SIZE (CONFIG_LWIP_TCPIP_RECVMBOX_SIZE)
• CONFIG_TCPIP_TASK_AFFINITY (CONFIG_LWIP_TCPIP_TASK_AFFINITY)
– CONFIG_TCPIP_TASK_AFFINITY_NO_AFFINITY
– CONFIG_TCPIP_TASK_AFFINITY_CPU0
– CONFIG_TCPIP_TASK_AFFINITY_CPU1
• CONFIG_TCPIP_TASK_STACK_SIZE (CONFIG_LWIP_TCPIP_TASK_STACK_SIZE)
• CONFIG_TCP_MAXRTX (CONFIG_LWIP_TCP_MAXRTX)
• CONFIG_TCP_MSL (CONFIG_LWIP_TCP_MSL)
• CONFIG_TCP_MSS (CONFIG_LWIP_TCP_MSS)
• CONFIG_TCP_OVERSIZE (CONFIG_LWIP_TCP_OVERSIZE)
– CONFIG_TCP_OVERSIZE_MSS
– CONFIG_TCP_OVERSIZE_QUARTER_MSS
– CONFIG_TCP_OVERSIZE_DISABLE
• CONFIG_TCP_QUEUE_OOSEQ (CONFIG_LWIP_TCP_QUEUE_OOSEQ)
• CONFIG_TCP_RECVMBOX_SIZE (CONFIG_LWIP_TCP_RECVMBOX_SIZE)
• CONFIG_TCP_SND_BUF_DEFAULT (CONFIG_LWIP_TCP_SND_BUF_DEFAULT)
• CONFIG_TCP_SYNMAXRTX (CONFIG_LWIP_TCP_SYNMAXRTX)
• CONFIG_TCP_WND_DEFAULT (CONFIG_LWIP_TCP_WND_DEFAULT)
• CONFIG_TIMER_QUEUE_LENGTH (CONFIG_FREERTOS_TIMER_QUEUE_LENGTH)
• CONFIG_TIMER_TASK_PRIORITY (CONFIG_FREERTOS_TIMER_TASK_PRIORITY)
• CONFIG_TIMER_TASK_STACK_DEPTH (CONFIG_FREERTOS_TIMER_TASK_STACK_DEPTH)
• CONFIG_TIMER_TASK_STACK_SIZE (CONFIG_ESP_TIMER_TASK_STACK_SIZE)
• CONFIG_TOOLPREFIX (CONFIG_SDK_TOOLPREFIX)
• CONFIG_UDP_RECVMBOX_SIZE (CONFIG_LWIP_UDP_RECVMBOX_SIZE)
• CONFIG_ULP_COPROC_ENABLED (CONFIG_ESP32_ULP_COPROC_ENABLED)
• CONFIG_ULP_COPROC_RESERVE_MEM (CONFIG_ESP32_ULP_COPROC_RESERVE_MEM)
• CONFIG_USE_ONLY_LWIP_SELECT (CONFIG_LWIP_USE_ONLY_LWIP_SELECT)
• CONFIG_WARN_WRITE_STRINGS (CONFIG_COMPILER_WARN_WRITE_STRINGS)
• CONFIG_WIFI_LWIP_ALLOCATION_FROM_SPIRAM_FIRST (CON-
FIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP)

2.10 Error Codes Reference

This section lists various error code constants defined in ESP-IDF.
For general information about error codes in ESP-IDF, see Error Handling.
ESP_FAIL (-1): Generic esp_err_t code indicating failure
ESP_OK (0): esp_err_t value indicating success (no error)
ESP_ERR_NO_MEM (0x101): Out of memory
ESP_ERR_INVALID_ARG (0x102): Invalid argument
ESP_ERR_INVALID_STATE (0x103): Invalid state
ESP_ERR_INVALID_SIZE (0x104): Invalid size
ESP_ERR_NOT_FOUND (0x105): Requested resource not found
ESP_ERR_NOT_SUPPORTED (0x106): Operation or feature not supported
ESP_ERR_TIMEOUT (0x107): Operation timed out
ESP_ERR_INVALID_RESPONSE (0x108): Received response was invalid
ESP_ERR_INVALID_CRC (0x109): CRC or checksum was invalid
ESP_ERR_INVALID_VERSION (0x10a): Version was invalid
ESP_ERR_INVALID_MAC (0x10b): MAC address was invalid
ESP_ERR_NOT_FINISHED (0x10c): There are items remained to retrieve
ESP_ERR_NVS_BASE (0x1100): Starting number of error codes
ESP_ERR_NVS_NOT_INITIALIZED (0x1101): The storage driver is not initialized
ESP_ERR_NVS_NOT_FOUND (0x1102): Id namespace doesn t exist yet and mode is NVS_READONLY
ESP_ERR_NVS_TYPE_MISMATCH (0x1103): The type of set or get operation doesn t match the type of value
stored in NVS
ESP_ERR_NVS_READ_ONLY (0x1104): Storage handle was opened as read only
ESP_ERR_NVS_NOT_ENOUGH_SPACE (0x1105): There is not enough space in the underlying storage to save the
value
ESP_ERR_NVS_INVALID_NAME (0x1106): Namespace name doesn t satisfy constraints
ESP_ERR_NVS_INVALID_HANDLE (0x1107): Handle has been closed or is NULL
ESP_ERR_NVS_REMOVE_FAILED (0x1108): The value wasn t updated because flash write operation has failed.
The value was written however, and update will be finished after re-initialization of nvs, provided that flash operation
doesn t fail again.
ESP_ERR_NVS_KEY_TOO_LONG (0x1109): Key name is too long
ESP_ERR_NVS_PAGE_FULL (0x110a): Internal error; never returned by nvs API functions
ESP_ERR_NVS_INVALID_STATE (0x110b): NVS is in an inconsistent state due to a previous error. Call
nvs_flash_init and nvs_open again, then retry.
ESP_ERR_NVS_INVALID_LENGTH (0x110c): String or blob length is not sufficient to store data
ESP_ERR_NVS_NO_FREE_PAGES (0x110d): NVS partition doesn t contain any empty pages. This may happen
if NVS partition was truncated. Erase the whole partition and call nvs_flash_init again.
ESP_ERR_NVS_VALUE_TOO_LONG (0x110e): String or blob length is longer than supported by the implemen-
tation
ESP_ERR_NVS_PART_NOT_FOUND (0x110f): Partition with specified name is not found in the partition table

ESP_ERR_NVS_NEW_VERSION_FOUND (0x1110): NVS partition contains data in new format and cannot be
recognized by this version of code
ESP_ERR_NVS_XTS_ENCR_FAILED (0x1111): XTS encryption failed while writing NVS entry
ESP_ERR_NVS_XTS_DECR_FAILED (0x1112): XTS decryption failed while reading NVS entry
ESP_ERR_NVS_XTS_CFG_FAILED (0x1113): XTS configuration setting failed
ESP_ERR_NVS_XTS_CFG_NOT_FOUND (0x1114): XTS configuration not found
ESP_ERR_NVS_ENCR_NOT_SUPPORTED (0x1115): NVS encryption is not supported in this version
ESP_ERR_NVS_KEYS_NOT_INITIALIZED (0x1116): NVS key partition is uninitialized
ESP_ERR_NVS_CORRUPT_KEY_PART (0x1117): NVS key partition is corrupt
ESP_ERR_NVS_CONTENT_DIFFERS (0x1118): Internal error; never returned by nvs API functions. NVS key is
different in comparison
ESP_ERR_NVS_WRONG_ENCRYPTION (0x1119): NVS partition is marked as encrypted with generic flash en-
cryption. This is forbidden since the NVS encryption works differently.
ESP_ERR_ULP_BASE (0x1200): Offset for ULP-related error codes
ESP_ERR_ULP_SIZE_TOO_BIG (0x1201): Program doesn t fit into RTC memory reserved for the ULP
ESP_ERR_ULP_INVALID_LOAD_ADDR (0x1202): Load address is outside of RTC memory reserved for the
ULP
ESP_ERR_ULP_DUPLICATE_LABEL (0x1203): More than one label with the same number was defined
ESP_ERR_ULP_UNDEFINED_LABEL (0x1204): Branch instructions references an undefined label
ESP_ERR_ULP_BRANCH_OUT_OF_RANGE (0x1205): Branch target is out of range of B instruction (try replacing
with BX)
ESP_ERR_OTA_BASE (0x1500): Base error code for ota_ops api
ESP_ERR_OTA_PARTITION_CONFLICT (0x1501): Error if request was to write or erase the current running
partition
ESP_ERR_OTA_SELECT_INFO_INVALID (0x1502): Error if OTA data partition contains invalid content
ESP_ERR_OTA_VALIDATE_FAILED (0x1503): Error if OTA app image is invalid
ESP_ERR_OTA_SMALL_SEC_VER (0x1504): Error if the firmware has a secure version less than the running
firmware.
ESP_ERR_OTA_ROLLBACK_FAILED (0x1505): Error if flash does not have valid firmware in passive partition
and hence rollback is not possible
ESP_ERR_OTA_ROLLBACK_INVALID_STATE (0x1506): Error if current active firmware is still marked in
pending validation state (ESP_OTA_IMG_PENDING_VERIFY), essentially first boot of firmware image post up-
grade and hence firmware upgrade is not possible
ESP_ERR_EFUSE (0x1600): Base error code for efuse api.
ESP_OK_EFUSE_CNT (0x1601): OK the required number of bits is set.
ESP_ERR_EFUSE_CNT_IS_FULL (0x1602): Error field is full.
ESP_ERR_EFUSE_REPEATED_PROG (0x1603): Error repeated programming of programmed bits is strictly for-
bidden.
ESP_ERR_CODING (0x1604): Error while a encoding operation.
ESP_ERR_NOT_ENOUGH_UNUSED_KEY_BLOCKS (0x1605): Error not enough unused key blocks available
ESP_ERR_DAMAGED_READING (0x1606): Error. Burn or reset was done during a reading operation leads to
damage read data. This error is internal to the efuse component and not returned by any public API.
ESP_ERR_IMAGE_BASE (0x2000)

ESP_ERR_IMAGE_FLASH_FAIL (0x2001)
ESP_ERR_IMAGE_INVALID (0x2002)
ESP_ERR_WIFI_BASE (0x3000): Starting number of WiFi error codes
ESP_ERR_WIFI_NOT_INIT (0x3001): WiFi driver was not installed by esp_wifi_init
ESP_ERR_WIFI_NOT_STARTED (0x3002): WiFi driver was not started by esp_wifi_start
ESP_ERR_WIFI_NOT_STOPPED (0x3003): WiFi driver was not stopped by esp_wifi_stop
ESP_ERR_WIFI_IF (0x3004): WiFi interface error
ESP_ERR_WIFI_MODE (0x3005): WiFi mode error
ESP_ERR_WIFI_STATE (0x3006): WiFi internal state error
ESP_ERR_WIFI_CONN (0x3007): WiFi internal control block of station or soft-AP error
ESP_ERR_WIFI_NVS (0x3008): WiFi internal NVS module error
ESP_ERR_WIFI_MAC (0x3009): MAC address is invalid
ESP_ERR_WIFI_SSID (0x300a): SSID is invalid
ESP_ERR_WIFI_PASSWORD (0x300b): Password is invalid
ESP_ERR_WIFI_TIMEOUT (0x300c): Timeout error
ESP_ERR_WIFI_WAKE_FAIL (0x300d): WiFi is in sleep state(RF closed) and wakeup fail
ESP_ERR_WIFI_WOULD_BLOCK (0x300e): The caller would block
ESP_ERR_WIFI_NOT_CONNECT (0x300f): Station still in disconnect status
ESP_ERR_WIFI_POST (0x3012): Failed to post the event to WiFi task
ESP_ERR_WIFI_INIT_STATE (0x3013): Invalid WiFi state when init/deinit is called
ESP_ERR_WIFI_STOP_STATE (0x3014): Returned when WiFi is stopping
ESP_ERR_WIFI_NOT_ASSOC (0x3015): The WiFi connection is not associated
ESP_ERR_WIFI_TX_DISALLOW (0x3016): The WiFi TX is disallowed
ESP_ERR_WIFI_REGISTRAR (0x3033): WPS registrar is not supported
ESP_ERR_WIFI_WPS_TYPE (0x3034): WPS type error
ESP_ERR_WIFI_WPS_SM (0x3035): WPS state machine is not initialized
ESP_ERR_ESPNOW_BASE (0x3064): ESPNOW error number base.
ESP_ERR_ESPNOW_NOT_INIT (0x3065): ESPNOW is not initialized.
ESP_ERR_ESPNOW_ARG (0x3066): Invalid argument
ESP_ERR_ESPNOW_NO_MEM (0x3067): Out of memory
ESP_ERR_ESPNOW_FULL (0x3068): ESPNOW peer list is full
ESP_ERR_ESPNOW_NOT_FOUND (0x3069): ESPNOW peer is not found
ESP_ERR_ESPNOW_INTERNAL (0x306a): Internal error
ESP_ERR_ESPNOW_EXIST (0x306b): ESPNOW peer has existed
ESP_ERR_ESPNOW_IF (0x306c): Interface error
ESP_ERR_DPP_FAILURE (0x3097): Generic failure during DPP Operation
ESP_ERR_DPP_TX_FAILURE (0x3098): DPP Frame Tx failed OR not Acked
ESP_ERR_DPP_INVALID_ATTR (0x3099): Encountered invalid DPP Attribute
ESP_ERR_MESH_BASE (0x4000): Starting number of MESH error codes

ESP_ERR_MESH_WIFI_NOT_START (0x4001)
ESP_ERR_MESH_NOT_INIT (0x4002)
ESP_ERR_MESH_NOT_CONFIG (0x4003)
ESP_ERR_MESH_NOT_START (0x4004)
ESP_ERR_MESH_NOT_SUPPORT (0x4005)
ESP_ERR_MESH_NOT_ALLOWED (0x4006)
ESP_ERR_MESH_NO_MEMORY (0x4007)
ESP_ERR_MESH_ARGUMENT (0x4008)
ESP_ERR_MESH_EXCEED_MTU (0x4009)
ESP_ERR_MESH_TIMEOUT (0x400a)
ESP_ERR_MESH_DISCONNECTED (0x400b)
ESP_ERR_MESH_QUEUE_FAIL (0x400c)
ESP_ERR_MESH_QUEUE_FULL (0x400d)
ESP_ERR_MESH_NO_PARENT_FOUND (0x400e)
ESP_ERR_MESH_NO_ROUTE_FOUND (0x400f)
ESP_ERR_MESH_OPTION_NULL (0x4010)
ESP_ERR_MESH_OPTION_UNKNOWN (0x4011)
ESP_ERR_MESH_XON_NO_WINDOW (0x4012)
ESP_ERR_MESH_INTERFACE (0x4013)
ESP_ERR_MESH_DISCARD_DUPLICATE (0x4014)
ESP_ERR_MESH_DISCARD (0x4015)
ESP_ERR_MESH_VOTING (0x4016)
ESP_ERR_MESH_XMIT (0x4017)
ESP_ERR_MESH_QUEUE_READ (0x4018)
ESP_ERR_MESH_PS (0x4019)
ESP_ERR_MESH_RECV_RELEASE (0x401a)
ESP_ERR_ESP_NETIF_BASE (0x5000)
ESP_ERR_ESP_NETIF_INVALID_PARAMS (0x5001)
ESP_ERR_ESP_NETIF_IF_NOT_READY (0x5002)
ESP_ERR_ESP_NETIF_DHCPC_START_FAILED (0x5003)
ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED (0x5004)
ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED (0x5005)
ESP_ERR_ESP_NETIF_NO_MEM (0x5006)
ESP_ERR_ESP_NETIF_DHCP_NOT_STOPPED (0x5007)
ESP_ERR_ESP_NETIF_DRIVER_ATTACH_FAILED (0x5008)
ESP_ERR_ESP_NETIF_INIT_FAILED (0x5009)
ESP_ERR_ESP_NETIF_DNS_NOT_CONFIGURED (0x500a)
ESP_ERR_ESP_NETIF_MLD6_FAILED (0x500b)
ESP_ERR_ESP_NETIF_IP6_ADDR_FAILED (0x500c)

ESP_ERR_FLASH_BASE (0x6000): Starting number of flash error codes

ESP_ERR_FLASH_OP_FAIL (0x6001)
ESP_ERR_FLASH_OP_TIMEOUT (0x6002)
ESP_ERR_FLASH_NOT_INITIALISED (0x6003)
ESP_ERR_FLASH_UNSUPPORTED_HOST (0x6004)
ESP_ERR_FLASH_UNSUPPORTED_CHIP (0x6005)
ESP_ERR_FLASH_PROTECTED (0x6006)
ESP_ERR_HTTP_BASE (0x7000): Starting number of HTTP error codes
ESP_ERR_HTTP_MAX_REDIRECT (0x7001): The error exceeds the number of HTTP redirects
ESP_ERR_HTTP_CONNECT (0x7002): Error open the HTTP connection
ESP_ERR_HTTP_WRITE_DATA (0x7003): Error write HTTP data
ESP_ERR_HTTP_FETCH_HEADER (0x7004): Error read HTTP header from server
ESP_ERR_HTTP_INVALID_TRANSPORT (0x7005): There are no transport support for the input scheme
ESP_ERR_HTTP_CONNECTING (0x7006): HTTP connection hasn t been established yet
ESP_ERR_HTTP_EAGAIN (0x7007): Mapping of errno EAGAIN to esp_err_t
ESP_ERR_HTTP_CONNECTION_CLOSED (0x7008): Read FIN from peer and the connection closed
ESP_ERR_ESP_TLS_BASE (0x8000): Starting number of ESP-TLS error codes
ESP_ERR_ESP_TLS_CANNOT_RESOLVE_HOSTNAME (0x8001): Error if hostname couldn t be resolved upon
tls connection
ESP_ERR_ESP_TLS_CANNOT_CREATE_SOCKET (0x8002): Failed to create socket
ESP_ERR_ESP_TLS_UNSUPPORTED_PROTOCOL_FAMILY (0x8003): Unsupported protocol family
ESP_ERR_ESP_TLS_FAILED_CONNECT_TO_HOST (0x8004): Failed to connect to host
ESP_ERR_ESP_TLS_SOCKET_SETOPT_FAILED (0x8005): failed to set/get socket option
ESP_ERR_ESP_TLS_CONNECTION_TIMEOUT (0x8006): new connection in esp_tls_low_level_conn connec-
tion timeouted
ESP_ERR_ESP_TLS_SE_FAILED (0x8007)
ESP_ERR_ESP_TLS_TCP_CLOSED_FIN (0x8008)
ESP_ERR_MBEDTLS_CERT_PARTLY_OK (0x8010): mbedtls parse certificates was partly successful
ESP_ERR_MBEDTLS_CTR_DRBG_SEED_FAILED (0x8011): mbedtls api returned error
ESP_ERR_MBEDTLS_SSL_SET_HOSTNAME_FAILED (0x8012): mbedtls api returned error
ESP_ERR_MBEDTLS_SSL_CONFIG_DEFAULTS_FAILED (0x8013): mbedtls api returned error
ESP_ERR_MBEDTLS_SSL_CONF_ALPN_PROTOCOLS_FAILED (0x8014): mbedtls api returned error
ESP_ERR_MBEDTLS_X509_CRT_PARSE_FAILED (0x8015): mbedtls api returned error
ESP_ERR_MBEDTLS_SSL_CONF_OWN_CERT_FAILED (0x8016): mbedtls api returned error
ESP_ERR_MBEDTLS_SSL_SETUP_FAILED (0x8017): mbedtls api returned error
ESP_ERR_MBEDTLS_SSL_WRITE_FAILED (0x8018): mbedtls api returned error
ESP_ERR_MBEDTLS_PK_PARSE_KEY_FAILED (0x8019): mbedtls api returned failed
ESP_ERR_MBEDTLS_SSL_HANDSHAKE_FAILED (0x801a): mbedtls api returned failed
ESP_ERR_MBEDTLS_SSL_CONF_PSK_FAILED (0x801b): mbedtls api returned failed
ESP_ERR_MBEDTLS_SSL_TICKET_SETUP_FAILED (0x801c): mbedtls api returned failed

ESP_ERR_WOLFSSL_SSL_SET_HOSTNAME_FAILED (0x8031): wolfSSL api returned error

ESP_ERR_WOLFSSL_SSL_CONF_ALPN_PROTOCOLS_FAILED (0x8032): wolfSSL api returned error
ESP_ERR_WOLFSSL_CERT_VERIFY_SETUP_FAILED (0x8033): wolfSSL api returned error
ESP_ERR_WOLFSSL_KEY_VERIFY_SETUP_FAILED (0x8034): wolfSSL api returned error
ESP_ERR_WOLFSSL_SSL_HANDSHAKE_FAILED (0x8035): wolfSSL api returned failed
ESP_ERR_WOLFSSL_CTX_SETUP_FAILED (0x8036): wolfSSL api returned failed
ESP_ERR_WOLFSSL_SSL_SETUP_FAILED (0x8037): wolfSSL api returned failed
ESP_ERR_WOLFSSL_SSL_WRITE_FAILED (0x8038): wolfSSL api returned failed
ESP_ERR_HTTPS_OTA_BASE (0x9000)
ESP_ERR_HTTPS_OTA_IN_PROGRESS (0x9001)
ESP_ERR_PING_BASE (0xa000)
ESP_ERR_PING_INVALID_PARAMS (0xa001)
ESP_ERR_PING_NO_MEM (0xa002)
ESP_ERR_HTTPD_BASE (0xb000): Starting number of HTTPD error codes
ESP_ERR_HTTPD_HANDLERS_FULL (0xb001): All slots for registering URI handlers have been consumed
ESP_ERR_HTTPD_HANDLER_EXISTS (0xb002): URI handler with same method and target URI already regis-
tered
ESP_ERR_HTTPD_INVALID_REQ (0xb003): Invalid request pointer
ESP_ERR_HTTPD_RESULT_TRUNC (0xb004): Result string truncated
ESP_ERR_HTTPD_RESP_HDR (0xb005): Response header field larger than supported
ESP_ERR_HTTPD_RESP_SEND (0xb006): Error occured while sending response packet
ESP_ERR_HTTPD_ALLOC_MEM (0xb007): Failed to dynamically allocate memory for resource
ESP_ERR_HTTPD_TASK (0xb008): Failed to launch server task/thread
ESP_ERR_HW_CRYPTO_BASE (0xc000): Starting number of HW cryptography module error codes
ESP_ERR_HW_CRYPTO_DS_HMAC_FAIL (0xc001): HMAC peripheral problem
ESP_ERR_HW_CRYPTO_DS_INVALID_KEY (0xc002)
ESP_ERR_HW_CRYPTO_DS_INVALID_DIGEST (0xc004)
ESP_ERR_HW_CRYPTO_DS_INVALID_PADDING (0xc005)


Chapter 3
ESP32 Hardware Reference
3.1 Chip Series Comparison

The comparison below covers key features of chips supported by ESP-IDF. For the full list of features please refer
to respective datasheets in Section Related Documents.
Table 1: Chip Series Comparison

Feature ESP32 Series ESP32-S2 Series ESP32-C3 Series ESP32-S3 Series
Launch 2016 2020 2020 2020
year
Variants See ESP32 Datasheet See ESP32-S2 See ESP32-C3 See ESP32-S3
(PDF) Datasheet (PDF) Datasheet (PDF) Datasheet (PDF)
Core Xtensa® dual-/single Xtensa® single-core 32-bit single-core Xtensa® dual-core
core 32-bit LX6 32-bit LX7 RISC-V 32-bit LX7
Wi-Fi 802.11 b/g/n, 2.4 GHz 802.11 b/g/n, 2.4 GHz 802.11 b/g/n, 2.4 GHz 802.11 b/g/n, 2.4 GHz
protocols
Bluetooth® Bluetooth v4.2 ✖ Bluetooth 5.0 Bluetooth 5.0
BR/EDR and Blue-
tooth Low Energy
Typical 240 MHz (160 MHz 240 MHz 160 MHz 240 MHz
fre- for ESP32-S0WD)
quency
SRAM 520 KB 320 KB 400 KB 512 KB
ROM 448 KB for booting 128 KB for booting 384 KB for booting 384 KB for booting
and core functions and core functions and core functions and core functions
Embedded 2 MB, 4 MB, or none, 2 MB, 4 MB, or none, 4 MB or none, de- 8 MB or none, de-
flash depending on variants depending on variants pending on variants pending on variants
External Up to 16 MB device, Up to 1 GB device, Up to 16 MB device, Up to 1 GB device, ad-
flash address 11 MB + 248 address 11.5 MB each address 8 MB each dress 32 MB each time
KB each time time time
External Up to 8 MB device, Up to 1 GB device, ✖ Up to 1 GB device, ad-
RAM address 4 MB each address 11.5 MB each dress 32 MB each time
time time
Cache ✓ Two-way set asso- ✓ Four-way set as- ✓ Eight-way set ✓ Four-way or eight-
ciative sociative, independent associative, 32-bit way set associative
instruction cache and data/instruction bus for instruction cache;
data cache width four-way set associa-
tive for data cache,
32-bit data/instruction
bus width
1723
Chapter 3. ESP32 Hardware Reference

Peripherals
ADC Two 12-bit, 18 chan- Two 12-bit, 20 chan- Two 12-bit SAR Two 12-bit SAR
nels nels ADCs, at most 6 ADCs, 20 channels
channels
DAC Two 8-bit channels Two 8-bit channels ✖ ✖
Timers Four 64-bit general- Four 64-bit general- Two 54-bit general- Four 54-bit general-
purpose timers, and purpose timers, and purpose timers, and purpose timers, and
three watchdog timers three watchdog timers three watchdog timers three watchdog timers
Temperature✖ 1 1 1
sensor
Touch 10 14 ✖ 14
sensor
Hall sen- 1 ✖ ✖ ✖
sor
GPIO 34 43 22 45
SPI 4 4 3 4
LCD in- 1 1 ✖ 1
terface
UART 3 21 21 3
I2C 2 2 1 2
I2S 2, can be config- 1, can be config- 1, can be config- 2, can be config-
ured to operate with ured to operate with ured to operate with ured to operate with
8/16/32/40/48-bit 8/16/24/32/48/64-bit 8/16/24/32-bit reso- 8/16/24/32-bit reso-
resolution as an input resolution as an input lution as an input or lution as an input or
or output channel. or output channel. output channel. output channel.
Camera 1 1 ✖ 1
interface
DMA Dedicated DMA Dedicated DMA to General-purpose, 3 General-purpose, 5
to UART, SPI, I2S, UART, SPI, AES, TX channels, 3 RX TX channels, 5 RX
SDIO slave, SD/MMC SHA, I2S, and ADC channels channels
host, EMAC, BT, and Controller
Wi-Fi
RMT 8 channels 4 channels 1 , can be 4 channels 2 , 2 TX 8 channels 2 , 4 TX
configured to TX/RX channels, 2 RX chan- channels, 4 RX chan-
channels nels nels
Pulse 8 channels 4 channels 1 ✖ 4 channels 1
counter
LED 16 channels 8 channels 1 6 channels 2 8 channels 1
PWM
MCPWM 2, six PWM outputs ✖ ✖ 2, six PWM outputs
USB ✖ 1 ✖ 1
OTG
TWAI® 1 1 1 1
controller
(com-
patible
with ISO
11898-1)
SD/SDIO/MMC 1 ✖ ✖ 1
host con-
troller
SDIO 1 ✖ ✖ ✖
slave
controller


Ethernet 1 ✖ ✖ ✖
MAC
ULP ULP FSM PicoRV32 core with 8 ✖ PicoRV32 core with 8
KB SRAM, ULP FSM KB SRAM, ULP FSM
Debug ✖ ✖ 1 ✖
Assist
Security
Secure ✓ ✓ Faster and safer, ✓ Faster and safer, ✓ Faster and safer,
boot compared with ESP32 compared with ESP32 compared with ESP32
Flash en- ✓ ✓ Support for ✓ Safer, compared ✓ Support for
cryption PSRAM encryption. with ESP32 PSRAM encryption.
Safer, compared with Safer, compared with
ESP32 ESP32
OTP 1024-bit 4096-bit 4096-bit 4096-bit
AES ✓ AES-128, AES- ✓ AES-128, AES- ✓ AES-128, AES- ✓ AES-128, AES-
192, AES-256 (FIPS 192, AES-256 (FIPS 256 (FIPS PUB 197); 256 (FIPS PUB 197);
PUB 197) PUB 197); DMA sup- DMA support DMA support
port
HASH SHA-1, SHA-256, SHA-1, SHA-224, SHA-1, SHA-224, SHA-1, SHA-224,
SHA-384, SHA-512 SHA-256, SHA- SHA-256 (FIPS PUB SHA-256, SHA-
(FIPS PUB 180-4) 384, SHA-512, 180-4); DMA support 384, SHA-512,
SHA-512/224, SHA- SHA-512/224, SHA-
512/256, SHA-512/t 512/256, SHA-512/t
(FIPS PUB 180-4); (FIPS PUB 180-4);
DMA support DMA support
RSA Up to 4096 bits Up to 4096 bits Up to 3072 bits Up to 4096 bits
RNG ✓ ✓ ✓ ✓
HMAC ✖ ✓ ✓ ✓
Digital ✖ ✓ ✓ ✓
signature
XTS ✖ ✓ XTS-AES-128, ✓ XTS-AES-128 ✓ XTS-AES-128,
XTS-AES-256 XTS-AES-256
Other
Deep- 100 μA (when ADC 22 μA (when touch No such pattern TBD
sleep work with a duty cycle sensors work with a
(ULP of 1%) duty cycle of 1%)
sensor-
monitored
pattern)
Size QFN48 5*5, 6*6, de- QFN56 7*7 QFN32 5*5 QFN56 7*7
pending on variants
• Note 1: Reduced chip area compared with ESP32

• Note 2: Reduced chip area compared with ESP32 and ESP32-S2
• Note 3: Die size: ESP32-C3 < ESP32-S2 < ESP32-S3 < ESP32
3.1.1 Related Documents

• ESP32-PICO Datasheets (PDF)
– ESP32-PICO-D4
– ESP32-PICO-V3
– ESP32-PICO-V3-02
• ESP32-S2 Datasheet (PDF)
• ESP32-C3 Datasheet (PDF)

• ESP32-S3 Datasheet (PDF)


Chapter 4
API Guides
4.1 Application Level Tracing library
4.1.1 Overview
IDF provides useful feature for program behavior analysis: application level tracing. It is implemented in the corre-
sponding library and can be enabled in menuconfig. This feature allows to transfer arbitrary data between host and
ESP32 via JTAG interface with small overhead on program execution.
Developers can use this library to send application specific state of execution to the host and receive commands or
other type of info in the opposite direction at runtime. The main use cases of this library are:
1. Collecting application specific data, see Application Specific Tracing
2. Lightweight logging to the host, see Logging to Host
3. System behavior analysis, see System Behavior Analysis with SEGGER SystemView
4. Source code coverage, see Gcov (Source Code Coverage)
Tracing components when working over JTAG interface are shown in the figure below.
4.1.2 Modes of Operation
The library supports two modes of operation:

Post-mortem mode. This is the default mode. The mode does not need interaction with the host side. In this mode
tracing module does not check whether host has read all the data from HW UP BUFFER buffer and overwrites old
data with the new ones. This mode is useful when only the latest trace data are interesting to the user, e.g. for
analyzing program s behavior just before the crash. Host can read the data later on upon user request, e.g. via
special OpenOCD command in case of working via JTAG interface.
Streaming mode. Tracing module enters this mode when host connects to ESP32. In this mode before writing
new data to HW UP BUFFER tracing module checks that there is enough space in it and if necessary waits for
the host to read data and free enough memory. Maximum waiting time is controlled via timeout values passed by
users to corresponding API routines. So when application tries to write data to trace buffer using finite value of
the maximum waiting time it is possible situation that this data will be dropped. Especially this is true for trac-
ing from time critical code (ISRs, OS scheduler code etc.) when infinite timeouts can lead to system malfunction.
In order to avoid loss of such critical data developers can enable additional data buffering via menuconfig option
CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX. This macro specifies the size of data which can be buffered in
above conditions. The option can also help to overcome situation when data transfer to the host is temporarily slowed
down, e.g due to USB bus congestions etc. But it will not help when average bitrate of trace data stream exceeds HW
interface capabilities.
1727
Chapter 4. API Guides
Fig. 1: Tracing Components when Working Over JTAG
4.1.3 Configuration Options and Dependencies
Using of this feature depends on two components:

1. Host side: Application tracing is done over JTAG, so it needs OpenOCD to be set up and running on host
machine. For instructions on how to set it up, please see JTAG Debugging for details.
2. Target side: Application tracing functionality can be enabled in menuconfig. Component config > Application
Level Tracing menu allows selecting destination for the trace data (HW interface for transport). Choosing any
of the destinations automatically enables CONFIG_APPTRACE_ENABLE option.
Note: In order to achieve higher data rates and minimize number of dropped packets it is recommended to optimize
setting of JTAG clock frequency, so it is at maximum and still provides stable operation of JTAG, see Optimize JTAG
speed.
There are two additional menuconfig options not mentioned above:

1. Threshold for flushing last trace data to host on panic (CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH).
This option is necessary due to the nature of working over JTAG. In that mode trace data are exposed to the
host in 16 KB blocks. In post-mortem mode when one block is filled it is exposed to the host and the previous
one becomes unavailable. In other words trace data are overwritten in 16 KB granularity. On panic the latest
data from the current input block are exposed to host and host can read them for post-analysis. System panic
may occur when very small amount of data are not exposed to the host yet. In this case the previous 16 KB of
collected data will be lost and host will see the latest, but very small piece of the trace. It can be insufficient
to diagnose the problem. This menuconfig option allows avoiding such situations. It controls the threshold
for flushing data in case of panic. For example user can decide that it needs not less then 512 bytes of the
recent trace data, so if there is less then 512 bytes of pending data at the moment of panic they will not be
flushed and will not overwrite previous 16 KB. The option is only meaningful in post-mortem mode and when
working over JTAG.
2. Timeout for flushing last trace data to host on panic (CONFIG_APPTRACE_ONPANIC_HOST_FLUSH_TMO).
The option is only meaningful in streaming mode and controls the maximum time tracing module will wait for
the host to read the last data in case of panic.

4.1.4 How to use this library
This library provides API for transferring arbitrary data between host and ESP32. When enabled in menuconfig
target application tracing module is initialized automatically at the system startup, so all what the user needs to do is
to call corresponding API to send, receive or flush the data.
Application Specific Tracing
In general user should decide what type of data should be transferred in every direction and how these data must be
interpreted (processed). The following steps must be performed to transfer data between target and host:
1. On target side user should implement algorithms for writing trace data to the host. Piece of code below shows
an example how to do this.
#include "esp_app_trace.h"
...
char buf[] = "Hello World!";
esp_err_t res = esp_apptrace_write(ESP_APPTRACE_DEST_TRAX, buf, strlen(buf),␣
,→ESP_APPTRACE_TMO_INFINITE);
if (res != ESP_OK) {
ESP_LOGE(TAG, "Failed to write data to host!");
return res;
}
esp_apptrace_write() function uses memcpy to copy user data to the internal buffer. In some cases it
can be more optimal to use esp_apptrace_buffer_get() and esp_apptrace_buffer_put()
functions. They allow developers to allocate buffer and fill it themselves. The following piece of code shows
how to do this.
...
int number = 10;
char *ptr = (char *)esp_apptrace_buffer_get(ESP_APPTRACE_DEST_TRAX, 32, 100/
,→*tmo in us*/);
if (ptr == NULL) {
ESP_LOGE(TAG, "Failed to get buffer!");
return ESP_FAIL;
}
sprintf(ptr, "Here is the number %d", number);
esp_err_t res = esp_apptrace_buffer_put(ESP_APPTRACE_DEST_TRAX, ptr, 100/*tmo␣
,→in us*/);
/* in case of error host tracing tool (e.g. OpenOCD) will report␣
,→incomplete user buffer */
ESP_LOGE(TAG, "Failed to put buffer!");

return res;
}
Also according to his needs user may want to receive data from the host. Piece of code below shows an example
how to do this.
...
char buf[32];
char down_buf[32];
size_t sz = sizeof(buf);
/* config down buffer */

esp_apptrace_down_buffer_config(down_buf, sizeof(down_buf));
/* check for incoming data and read them if any */
esp_err_t res = esp_apptrace_read(ESP_APPTRACE_DEST_TRAX, buf, &sz, 0/*do not␣
,→wait*/);


ESP_LOGE(TAG, "Failed to read data from host!");
return res;
}
if (sz > 0) {
/* we have data, process them */
...
}
esp_apptrace_read() function uses memcpy to copy host data to user buffer. In

some cases it can be more optimal to use esp_apptrace_down_buffer_get() and
esp_apptrace_down_buffer_put() functions. They allow developers to occupy chunk of
read buffer and process it in-place. The following piece of code shows how to do this.
...
char down_buf[32];
uint32_t *number;
size_t sz = 32;
/* config down buffer */

esp_apptrace_down_buffer_config(down_buf, sizeof(down_buf));
char *ptr = (char *)esp_apptrace_down_buffer_get(ESP_APPTRACE_DEST_TRAX, &sz,␣
,→100/*tmo in us*/);
if (ptr == NULL) {
ESP_LOGE(TAG, "Failed to get buffer!");
return ESP_FAIL;
}
if (sz > 4) {
number = (uint32_t *)ptr;
printf("Here is the number %d", *number);
} else {
printf("No data");
}
esp_err_t res = esp_apptrace_down_buffer_put(ESP_APPTRACE_DEST_TRAX, ptr, 100/
,→*tmo in us*/);
/* in case of error host tracing tool (e.g. OpenOCD) will report␣
,→incomplete user buffer */
ESP_LOGE(TAG, "Failed to put buffer!");

return res;
}
2. The next step is to build the program image and download it to the target as described in the Getting Started
Guide.
3. Run OpenOCD (see JTAG Debugging).
4. Connect to OpenOCD telnet server. It can be done using the following command in terminal telnet
<oocd_host> 4444. If telnet session is opened on the same machine which runs OpenOCD you can
use localhost as <oocd_host> in the command above.
5. Start trace data collection using special OpenOCD command. This command will transfer tracing data and
redirect them to specified file or socket (currently only files are supported as trace data destination). For
description of the corresponding commands see OpenOCD Application Level Tracing Commands.
6. The final step is to process received data. Since format of data is defined by user the processing stage is out
of the scope of this document. Good starting points for data processor are python scripts in $IDF_PATH/
tools/esp_app_trace: apptrace_proc.py (used for feature tests) and logtrace_proc.py
(see more details in section Logging to Host).
OpenOCD Application Level Tracing Commands HW UP BUFFER is shared between user data blocks and
filling of the allocated memory is performed on behalf of the API caller (in task or ISR context). In multithreading
environment it can happen that task/ISR which fills the buffer is preempted by another high priority task/ISR. So

it is possible situation that user data preparation process is not completed at the moment when that chunk is read
by the host. To handle such conditions tracing module prepends all user data chunks with header which contains
allocated user buffer size (2 bytes) and length of actually written data (2 bytes). So total length of the header is 4
bytes. OpenOCD command which reads trace data reports error when it reads incomplete user data chunk, but in
any case it puts contents of the whole user chunk (including unfilled area) to output file.
Below is the description of available OpenOCD application tracing commands.
Note: Currently OpenOCD does not provide commands to send arbitrary user data to the target.
Command usage:
esp apptrace [start <options>] | [stop] | [status] | [dump <cores_num>
<outfile>]
Sub-commands:
start Start tracing (continuous streaming).
stop Stop tracing.
status Get tracing status.
dump Dump all data from (post-mortem dump).
Start command syntax:
start <outfile> [poll_period [trace_size [stop_tmo [wait4halt
[skip_size]]]]
outfile Path to file to save data from both CPUs. This argument should have the following format: file://
path/to/file.
poll_period Data polling period (in ms) for available trace data. If greater than 0 then command runs in non-
blocking mode. By default 1 ms.
trace_size Maximum size of data to collect (in bytes). Tracing is stopped after specified amount of data is
received. By default -1 (trace size stop trigger is disabled).
stop_tmo Idle timeout (in sec). Tracing is stopped if there is no data for specified period of time. By default -1
(disable this stop trigger). Optionally set it to value longer than longest pause between tracing commands from
target.
wait4halt If 0 start tracing immediately, otherwise command waits for the target to be halted (after reset, by
breakpoint etc.) and then automatically resumes it and starts tracing. By default 0.
skip_size Number of bytes to skip at the start. By default 0.
Note: If poll_period is 0, OpenOCD telnet command line will not be available until tracing is stopped. You
must stop it manually by resetting the board or pressing Ctrl+C in OpenOCD window (not one with the telnet session).
Another option is to set trace_size and wait until this size of data is collected. At this point tracing stops
automatically.
Command usage examples:

1. Collect 2048 bytes of tracing data to a file trace.log . The file will be saved in openocd-esp32 directory.
esp apptrace start file://trace.log 1 2048 5 0 0
The tracing data will be retrieved and saved in non-blocking mode. This process will stop automatically after
2048 bytes are collected, or if no data are available for more than 5 seconds.
Note: Tracing data is buffered before it is made available to OpenOCD. If you see Data timeout! message,
then the target is likely sending not enough data to empty the buffer to OpenOCD before expiration of time-
out. Either increase the timeout or use a function esp_apptrace_flush() to flush the data on specific
intervals.
2. Retrieve tracing data indefinitely in non-blocking mode.

esp apptrace start file://trace.log 1 -1 -1 0 0
There is no limitation on the size of collected data and there is no any data timeout set. This process may be
stopped by issuing esp apptrace stop command on OpenOCD telnet prompt, or by pressing Ctrl+C in
OpenOCD window.
3. Retrieve tracing data and save them indefinitely.
esp apptrace start file://trace.log 0 -1 -1 0 0
OpenOCD telnet command line prompt will not be available until tracing is stopped. To stop tracing press
Ctrl+C in OpenOCD window.
4. Wait for target to be halted. Then resume target s operation and start data retrieval. Stop after collecting 2048
bytes of data:
esp apptrace start file://trace.log 0 2048 -1 1 0
To configure tracing immediately after reset use the openocd reset halt command.
Logging to Host
IDF implements useful feature: logging to host via application level tracing library. This is a kind of semihosting
when all ESP_LOGx calls send strings to be printed to the host instead of UART. This can be useful because printing
to host eliminates some steps performed when logging to UART. The most part of work is done on the host.
By default IDF s logging library uses vprintf-like function to write formatted output to dedicated UART. In general
it involves the following steps:
1. Format string is parsed to obtain type of each argument.
2. According to its type every argument is converted to string representation.
3. Format string combined with converted arguments is sent to UART.
Though implementation of vprintf-like function can be optimized to a certain level, all steps above have to be per-
formed in any case and every step takes some time (especially item 3). So it frequently occurs that with additional log
added to the program to identify the problem, the program behavior is changed and the problem cannot be reproduced
or in the worst cases the program cannot work normally at all and ends up with an error or even hangs.
Possible ways to overcome this problem are to use higher UART bitrates (or another faster interface) and/or move
string formatting procedure to the host.
Application level tracing feature can be used to transfer log information to host using esp_apptrace_vprintf
function. This function does not perform full parsing of the format string and arguments, instead it just calculates
number of arguments passed and sends them along with the format string address to the host. On the host log data
are processed and printed out by a special Python script.
Limitations Current implementation of logging over JTAG has some limitations:

1. Tracing from ESP_EARLY_LOGx macros is not supported.
2. No support for printf arguments which size exceeds 4 bytes (e.g. double and uint64_t).
3. Only strings from .rodata section are supported as format strings and arguments.
4. Maximum number of printf arguments is 256.
How To Use It In order to use logging via trace module user needs to perform the following steps:
1. On target side special vprintf-like function needs to be installed. As it was mentioned earlier this func-
tion is esp_apptrace_vprintf. It sends log data to the host. Example code is provided in sys-
tem/app_trace_to_host.
2. Follow instructions in items 2-5 in Application Specific Tracing.
3. To print out collected log records, run the following command in terminal: $IDF_PATH/tools/
esp_app_trace/logtrace_proc.py /path/to/trace/file /path/to/program/
elf/file.

Log Trace Processor Command Options Command usage:

logtrace_proc.py [-h] [--no-errors] <trace_file> <elf_file>
Positional arguments:
trace_file Path to log trace file
elf_file Path to program ELF file
Optional arguments:
-h, --help show this help message and exit
--no-errors, -n Do not print errors
System Behavior Analysis with SEGGER SystemView
Another useful IDF feature built on top of application tracing library is the system level tracing which produces traces
compatible with SEGGER SystemView tool (see SystemView). SEGGER SystemView is a real-time recording and
visualization tool that allows to analyze runtime behavior of an application.
Note: Currently IDF-based application is able to generate SystemView compatible traces in form of files to be
opened in SystemView application. The tracing process cannot yet be controlled using that tool.
How To Use It Support for this feature is enabled by Component config > Application Level Tracing > FreeR-
TOS SystemView Tracing (CONFIG_APPTRACE_SV_ENABLE) menuconfig option. There are several other options
enabled under the same menu:
1. ESP32 timer to use as SystemView timestamp source: (CONFIG_APPTRACE_SV_TS_SOURCE) selects the
source of timestamps for SystemView events. In single core mode timestamps are generated using ESP32
internal cycle counter running at maximum 240 Mhz (~4 ns granularity). In dual-core mode external timer
working at 40 Mhz is used, so timestamp granularity is 25 ns.
2. Individually enabled or disabled collection of SystemView events (CONFIG_APPTRACE_SV_EVT_XXX):
• Trace Buffer Overflow Event
• ISR Enter Event
• ISR Exit Event
• ISR Exit to Scheduler Event
• Task Start Execution Event
• Task Stop Execution Event
• Task Start Ready State Event
• Task Stop Ready State Event
• Task Create Event
• Task Terminate Event
• System Idle Event
• Timer Enter Event
• Timer Exit Event
IDF has all the code required to produce SystemView compatible traces, so user can just configure necessary project
options (see above), build, download the image to target and use OpenOCD to collect data as described in the previous
sections.
OpenOCD SystemView Tracing Command Options Command usage:

esp sysview [start <options>] | [stop] | [status]
Sub-commands:
start Start tracing (continuous streaming).
stop Stop tracing.
status Get tracing status.

Start command syntax:

start <outfile1> [outfile2] [poll_period [trace_size [stop_tmo]]]
outfile1 Path to file to save data from PRO CPU. This argument should have the following format: file://
path/to/file.
outfile2 Path to file to save data from APP CPU. This argument should have the following format: file://
path/to/file.
poll_period Data polling period (in ms) for available trace data. If greater then 0 then command runs in non-
blocking mode. By default 1 ms.
trace_size Maximum size of data to collect (in bytes). Tracing is stopped after specified amount of data is
received. By default -1 (trace size stop trigger is disabled).
stop_tmo Idle timeout (in sec). Tracing is stopped if there is no data for specified period of time. By default -1
(disable this stop trigger).
Note: If poll_period is 0 OpenOCD telnet command line will not be available until tracing is stopped. You must
stop it manually by resetting the board or pressing Ctrl+C in OpenOCD window (not one with the telnet session).
Another option is to set trace_size and wait until this size of data is collected. At this point tracing stops
automatically.
Command usage examples:

1. Collect SystemView tracing data to files pro-cpu.SVDat and app-cpu.SVDat . The files will be saved
in openocd-esp32 directory.
esp sysview start file://pro-cpu.SVDat file://app-cpu.SVDat
The tracing data will be retrieved and saved in non-blocking mode. To stop data this process enter esp
sysview stop command on OpenOCD telnet prompt, optionally pressing Ctrl+C in OpenOCD window.
2. Retrieve tracing data and save them indefinitely.
esp sysview start file://pro-cpu.SVDat file://app-cpu.SVDat 0 -1 -1
OpenOCD telnet command line prompt will not be available until tracing is stopped. To stop tracing, press
Ctrl+C in OpenOCD window.
Data Visualization After trace data are collected user can use special tool to visualize the results and inspect
behavior of the program.
Unfortunately SystemView does not support tracing from multiple cores. So when tracing from ESP32 working in
dual-core mode two files are generated: one for PRO CPU and another one for APP CPU. User can load every file
into separate instance of the tool.
It is uneasy and awkward to analyze data for every core in separate instance of the tool. Fortunately there is Eclipse
plugin called Impulse which can load several trace files and makes it possible to inspect events from both cores in one
view. Also this plugin has no limitation of 1,000,000 events as compared to free version of SystemView.
Good instruction on how to install, configure and visualize data in Impulse from one core can be found here.
Note: IDF uses its own mapping for SystemView FreeRTOS events IDs, so user needs to replace
original file with mapping $SYSVIEW_INSTALL_DIR/Description/SYSVIEW_FreeRTOS.txt with
$IDF_PATH/docs/api-guides/SYSVIEW_FreeRTOS.txt. Also contents of that IDF specific file should
be used when configuring SystemView serializer using above link.
Configure Impulse for Dual Core Traces After installing Impulse and ensuring that it can successfully load trace
files for each core in separate tabs users can add special Multi Adapter port and load both files into one view. To
do this, users need to do the following in Eclipse:

1. Open Signal Ports view. Go to Windows->Show View->Other menu. Find Signal Ports view in Impulse
folder and double-click on it.
2. In Signal Ports view right-click on Ports and select Add ->New Multi Adapter Port
3. In open dialog Press Add button and select New Pipe/File .
4. In open dialog select SystemView Serializer as Serializer and set path to PRO CPU trace file. Press OK.
5. Repeat steps 3-4 for APP CPU trace file.
6. Double-click on created port. View for this port should open.
7. Click Start/Stop Streaming button. Data should be loaded.
8. Use Zoom Out , Zoom In and Zoom Fit button to inspect data.
9. For settings measurement cursors and other features please see Impulse documentation).
Note: If you have problems with visualization (no data are shown or strange behavior of zoom action is observed)
you can try to delete current signal hierarchy and double click on the necessary file or port. Eclipse will ask you to
create new signal hierarchy.
Gcov (Source Code Coverage)
Basics of Gcov and Gcovr Source code coverage is data indicating the count and frequency of every program
execution path that has been taken within a program s runtime. Gcov is a GCC tool that, when used in concert
with the compiler, can generate log files indicating the execution count of each line of a source file. The Gcovr tool
is utility for managing Gcov and generating summarized code coverage results.
Generally, using Gcov to compile and run programs on the Host will undergo these steps:
1. Compile the source code using GCC with the --coverage option enabled. This will cause the compiler to
generate a .gcno notes files during compilation. The notes files contain information to reconstruct execution
path block graphs and map each block to source code line numbers. Each source file compiled with the -
-coverage option should have their own .gcno file of the same name (e.g., a main.c will generate a
main.gcno when compiled).
2. Execute the program. During execution, the program should generate .gcda data files. These data files
contain the counts of the number of times an execution path was taken. The program will generate a .gcda
file for each source file compiled with the --coverage option (e.g., main.c will generate a main.gcda.
3. Gcov or Gcovr can be used generate a code coverage based on the .gcno, .gcda, and source files. Gcov
will generate a text based coverage report for each source file in the form of a .gcov file, whilst Gcovr will
generate a coverage report in HTML format.
Gcov and Gcovr in ESP-IDF Using Gcov in ESP-IDF is complicated by the fact that the program is running
remotely from the Host (i.e., on the target). The code coverage data (i.e., the .gcda files) is initially stored on the
target itself. OpenOCD is then used to dump the code coverage data from the target to the host via JTAG during
runtime. Using Gcov in ESP-IDF can be split into the following steps.
1. Setting Up a Project for Gcov
2. Dumping Code Coverage Data
3. Generating Coverage Report
Setting Up a Project for Gcov
Compiler Option In order to obtain code coverage data in a project, one or more source files within the project
must be compiled with the --coverage option. In ESP-IDF, this can be achieved at the component level or the
individual source file level:
• To cause all source files in a component to be compiled with the --coverage option, you can add tar-
get_compile_options(${COMPONENT_LIB} PRIVATE --coverage) to the CMakeLists.
txt file of the component.

• To cause a select number of source files (e.g. sourec1.c and source2.c) in the same component to be
compiled with the --coverage option, you can add set_source_files_properties(source1.
c source2.c PROPERTIES COMPILE_FLAGS --coverage) to the CMakeLists.txt file of
the component.
When a source file is compiled with the --coverage option (e.g. gcov_example.c), the compiler will generate
the gcov_example.gcno file in the project s build directory.
Project Configuration Before building a project with source code coverage, ensure that the following project
configuration options are enabled by running idf.py menuconfig.
• Enable the application tracing module by choosing Trace Memory for the CON-
FIG_APPTRACE_DESTINATION option.
• Enable Gcov to host via the CONFIG_APPTRACE_GCOV_ENABLE
Dumping Code Coverage Data Once a project has been complied with the --coverage option and flashed
onto the target, code coverage data will be stored internally on the target (i.e., in trace memory) whilst the application
runs. The process of transferring code coverage data from the target to the Host is know as dumping.
The dumping of coverage data is done via OpenOCD (see JTAG Debugging on how to setup and run OpenOCD). A
dump is triggered by issuing commands to OpenOCD, therefore a telnet session to OpenOCD must be opened to issue
such commands (run telnet localhost 4444). Note that GDB could be used instead of telnet to issue com-
mands to OpenOCD, however all commands issued from GDB will need to be prefixed as mon <oocd_command>.
When the target dumps code coverage data, the .gcda files are stored in the project s build directory. For ex-
ample, if gcov_example_main.c of the main component was compiled with the --coverage option, then
dumping the code coverage data would generate a gcov_example_main.gcda in build/esp-idf/main/
CMakeFiles/__idf_main.dir/gcov_example_main.c.gcda. Note that the .gcno files produced
during compilation are also placed in the same directory.
The dumping of code coverage data can be done multiple times throughout an application s life time. Each dump
will simply update the .gcda file with the newest code coverage information. Code coverage data is accumulative,
thus the newest data will contain the total execution count of each code path over the application s entire lifetime.
ESP-IDF supports two methods of dumping code coverage data form the target to the host:
• Instant Run-Time Dumpgit
• Hard-coded Dump
Instant Run-Time Dump An Instant Run-Time Dump is triggered by calling the ESP32 gcov OpenOCD
command (via a telnet session). Once called, OpenOCD will immediately preempt the ESP32 s current state and
execute a builtin IDF Gcov debug stub function. The debug stub function will handle the dumping of data to the Host.
Upon completion, the ESP32 will resume it s current state.
Hard-coded Dump A Hard-coded Dump is triggered by the application itself by calling esp_gcov_dump()
from somewhere within the application. When called, the application will halt and wait for OpenOCD to connect and
retrieve the code coverage data. Once esp_gcov_dump() is called, the Host must execute the esp gcov dump
OpenOCD command (via a telnet session). The esp gcov dump command will cause OpenOCD to connect to
the ESP32, retrieve the code coverage data, then disconnect from the ESP32 thus allowing the application to resume.
Hard-coded Dumps can also be triggered multiple times throughout an application s lifetime.
Hard-coded dumps are useful if code coverage data is required at certain points of an application s lifetime by placing
esp_gcov_dump() where necessary (e.g., after application initialization, during each iteration of an application
s main loop).
GDB can be used to set a breakpoint on esp_gcov_dump(), then call mon esp gcov dump automatically
via the use a gdbinit script (see Using GDB from Command Line).
The following GDB script is will add a breakpoint at esp_gcov_dump(), then call the mon esp gcov dump
OpenOCD command.

b esp_gcov_dump
commands
mon esp gcov dump
end
Note: Note that all OpenOCD commands should be invoked in GDB as: mon <oocd_command>.
Generating Coverage Report Once the code coverage data has been dumped, the .gcno, .gcda and the source
files can be used to generate a code coverage report. A code coverage report is simply a report indicating the number
of times each line in a source file has been executed.
Both Gcov and Gcovr can be used to generate code coverage reports. Gcov is provided along with the Xtensa
toolchain, whilst Gcovr may need to be installed separately. For details on how to use Gcov or Gcovr, refer to
Gcov documentation and Gcovr documentation.
Adding Gcovr Build Target to Project To make report generation more convenient, users can define additional
build targets in their projects such report generation can be done with a single build command.
Add the following lines to the CMakeLists.txt file of your project.
include($ENV{IDF_PATH}/tools/cmake/gcov.cmake)
idf_create_coverage_report(${CMAKE_CURRENT_BINARY_DIR}/coverage_report)
idf_clean_coverage_report(${CMAKE_CURRENT_BINARY_DIR}/coverage_report)
The following commands can now be used:

• cmake --build build/ --target gcovr-report will generate an HTML coverage report in
$(BUILD_DIR_BASE)/coverage_report/html directory.
• cmake --build build/ --target cov-data-clean will remove all coverage data files.
4.2 Application Startup Flow

This note explains various steps which happen before app_main function of an ESP-IDF application is called.
The high level view of startup process is as follows:
1. First stage bootloader in ROM loads second-stage bootloader image to RAM (IRAM & DRAM) from flash
offset 0x1000.
2. Second stage bootloader loads partition table and main app image from flash. Main app incorporates both RAM
segments and read-only segments mapped via flash cache.
3. Application startup executes. At this point the second CPU and RTOS scheduler are started.
This process is explained in detail in the following sections.
4.2.1 First stage bootloader
After SoC reset, PRO CPU will start running immediately, executing reset vector code, while APP CPU will be
held in reset. During startup process, PRO CPU does all the initialization. APP CPU reset is de-asserted in the
call_start_cpu0 function of application startup code. Reset vector code is located in the mask ROM of the
ESP32 chip and cannot be modified.
Startup code called from the reset vector determines the boot mode by checking GPIO_STRAP_REG register for
bootstrap pin states. Depending on the reset reason, the following takes place:

1. Reset from deep sleep: if the value in RTC_CNTL_STORE6_REG is non-zero, and CRC value of RTC mem-
ory in RTC_CNTL_STORE7_REG is valid, use RTC_CNTL_STORE6_REG as an entry point address and
jump immediately to it. If RTC_CNTL_STORE6_REG is zero, or RTC_CNTL_STORE7_REG contains in-
valid CRC, or once the code called via RTC_CNTL_STORE6_REG returns, proceed with boot as if it was a
power-on reset. Note: to run customized code at this point, a deep sleep stub mechanism is provided. Please
see deep sleep documentation for this.
2. For power-on reset, software SOC reset, and watchdog SOC reset: check the GPIO_STRAP_REG register
if a custom boot mode (such as UART Download Mode) is requested. If this is the case, this custom loader
mode is executed from ROM. Otherwise, proceed with boot as if it was due to software CPU reset. Consult
ESP32 datasheet for a description of SoC boot modes and how to execute them.
3. For software CPU reset and watchdog CPU reset: configure SPI flash based on EFUSE values, and attempt to
load the code from flash. This step is described in more detail in the next paragraphs.
Note: During normal boot modes the RTC watchdog is enabled when this happens, so if the process is interrupted
or stalled then the watchdog will reset the SOC automatically and repeat the boot process. This may cause the SoC
to strap into a new boot mode, if the strapping GPIOs have changed.
Second stage bootloader binary image is loaded from flash starting at address 0x1000. If Secure Boot is in use then
the first 4 kB sector of flash is used to store secure boot IV and digest of the bootloader image. Otherwise, this sector
is unused.
4.2.2 Second stage bootloader
In ESP-IDF, the binary image which resides at offset 0x1000 in flash is the second stage bootloader. Second stage
bootloader source code is available in components/bootloader directory of ESP-IDF. Second stage bootloader is used
in ESP-IDF to add flexibility to flash layout (using partition tables), and allow for various flows associated with flash
encryption, secure boot, and over-the-air updates (OTA) to take place.
When the first stage bootloader is finished checking and loading the second stage bootloader, it jumps to the second
stage bootloader entry point found in the binary image header.
Second stage bootloader reads the partition table found by default at offset 0x8000 (configurable value). See partition
tables documentation for more information. The bootloader finds factory and OTA app partitions. If OTA app
partitions are found in the partition table, the bootloader consults the otadata partition to determine which one
should be booted. See Over The Air Updates (OTA) for more information.
For a full description of the configuration options available for the ESP-IDF bootloader, see Bootloader.
For the selected partition, second stage bootloader reads the binary image from flash one segment at a time:
• For segments with load addresses in internal IRAM (Instruction RAM) or DRAM (Data RAM), the contents are
copied from flash to the load address.
• For segments which have load addresses in DROM (data stored in Flash) or IROM (code executed from Flash)
regions, the flash MMU is configured to provide the correct mapping from the flash to the load address.
Note that the second stage bootloader configures flash MMU for both PRO and APP CPUs, but it only enables flash
MMU for PRO CPU. Reason for this is that second stage bootloader code is loaded into the memory region used by
APP CPU cache. The duty of enabling cache for APP CPU is passed on to the application.
Once all segments are processed - meaning code is loaded and flash MMU is set up, second stage bootloader verifies
the integrity of the application and then jumps to the application entry point found in the binary image header.
4.2.3 Application startup
Application startup covers everything that happens after the app starts executing and before the app_main function
starts running inside the main task. This is split into three stages:
• Port initialization of hardware and basic C runtime environment.
• System initialization of software services and FreeRTOS.

• Running the main task and calling app_main.
Note: Understanding all stages of ESP-IDF app initialization is often not necessary. To understand initialization
from the application developer s perspective only, skip forward to Running the main task.
Port Initialization
ESP-IDF application entry point is call_start_cpu0 function found in compo-

nents/esp_system/port/cpu_start.c. This function is executed by the second stage bootloader, and never returns.
This port-layer initialization function initializes the basic C Runtime Environment ( CRT ) and performs initial
configuration of the SoC s internal hardware:
• Reconfigure CPU exceptions for the app (allowing app interrupt handlers to run, and causing Fatal Errors to
be handled using the options configured for the app rather than the simpler error handler provided by ROM).
• If the option CONFIG_BOOTLOADER_WDT_ENABLE is not set then the RTC watchdog timer is disabled.
• Initialize internal memory (data & bss).
• Finish configuring the MMU cache.
• Enable PSRAM if configured.
• Set the CPU clocks to the frequencies configured for the project.
• Reconfigure the main SPI flash based on the app header settings (necessary for compatibility with bootloader
versions before ESP-IDF V4.0, see Bootloader compatibility).
• If the app is configured to run on multiple cores, start the other core and wait for it to initialize as well (inside
the similar port layer initialization function call_start_cpu1).
Once call_start_cpu0 completes running, it calls the system layer initialization function start_cpu0
found in components/esp_system/startup.c. Other cores will also complete port-layer initialization and call
start_other_cores found in the same file.
System Initialization
The main system initialization function is start_cpu0. By default, this function is weak-linked to the function
start_cpu0_default. This means that it s possible to override this function to add some additional initial-
ization steps.
The primary system initialization stage includes:
• Log information about this application (project name, App version, etc.) if default log level enables this.
• Initialize the heap allocator (before this point all allocations must be static or on the stack).
• Initialize newlib component syscalls and time functions.
• Configure the brownout detector.
• Setup libc stdin, stdout, and stderr according to the serial console configuration.
• Perform any security-related checks, including burning efuses that should be burned for this configuration (in-
cluding disabling ROM download mode on ESP32 V3, CONFIG_ESP32_DISABLE_BASIC_ROM_CONSOLE).
• Initialize SPI flash API support.
• Call global C++ constructors and any C functions marked with __attribute__((constructor)).
Secondary system initialization allows individual components to be initialized. If a component has an initialization
function annotated with the ESP_SYSTEM_INIT_FN macro, it will be called as part of secondary initialization.
Running the main task
After all other components are initialized, the main task is created and the FreeRTOS scheduler starts running.
After doing some more initialization tasks (that require the scheduler to have started), the main task runs the
application-provided function app_main in the firmware.

The main task that runs app_main has a fixed RTOS priority (one higher than the minimum) and a configurable
stack size.
The main task core affinity is also configurable: CONFIG_ESP_MAIN_TASK_AFFINITY.
Unlike normal FreeRTOS tasks (or embedded C main functions), the app_main task is allowed to return. If this
happens, The task is cleaned up and the system will continue running with other RTOS tasks scheduled normally.
Therefore, it is possible to implement app_main as either a function that creates other application tasks and then
returns, or as a main application task itself.
Second core startup
A similar but simpler startup process happens on the APP CPU:

When running system initialization, the code on PRO CPU sets the entry point for APP CPU, de-asserts APP CPU
reset, and waits for a global flag to be set by the code running on APP CPU, indicating that it has started. Once this
is done, APP CPU jumps to call_start_cpu1 function in components/esp_system/port/cpu_start.c.
While PRO CPU does initialization in start_cpu0 function, APP CPU runs start_cpu_other_cores
function. Similar to start_cpu0, this function is weak-linked and defaults to the
start_cpu_other_cores_default function but can be replaced with a different function by the
application.
The start_cpu_other_cores_default function does some core-specific system initializa-
tion and then waits for the PRO CPU to start the FreeRTOS scheduler, at which point it executes
esp_startup_start_app_other_cores which is another weak-linked function defaulting to
esp_startup_start_app_other_cores_default.
By default esp_startup_start_app_other_cores_default does nothing but spin in a busy-waiting
loop until the scheduler of the PRO CPU triggers an interrupt to start the RTOS scheduler on the APP CPU.
4.3 BluFi
4.3.1 Overview
The BluFi for ESP32 is a Wi-Fi network configuration function via Bluetooth channel. It provides a secure protocol
to pass Wi-Fi configuration and credentials to the ESP32. Using this information ESP32 can then e.g. connect to an
AP or establish a SoftAP.
Fragmenting, data encryption, checksum verification in the BluFi layer are the key elements of this process.
You can customize symmetric encryption, asymmetric encryption and checksum support customization. Here we use
the DH algorithm for key negotiation, 128-AES algorithm for data encryption, and CRC16 algorithm for checksum
verification.
4.3.2 The BluFi Flow
The BluFi networking flow includes the configuration of the SoftAP and Station.
The following uses Station as an example to illustrate the core parts of the procedure, including broadcast, connection,
service discovery, negotiation of the shared key, data transmission, connection status backhaul.
1. Set the ESP32 into GATT Server mode and then it will send broadcasts with specific advertising data. You
can customize this broadcast as needed, which is not a part of the BluFi Profile.
2. Use the App installed on the mobile phone to search for this particular broadcast. The mobile phone will
connect to ESP32 as the GATT Client once the broadcast is confirmed. The App used during this part is up
to you.
3. After the GATT connection is successfully established, the mobile phone will send a data frame for key nego-
tiation to ESP32 (see the section The Frame Formats Defined in BluFi for details).

4. After ESP32 receives the data frame of key negotiation, it will parse the content according to the user-defined
negotiation method.
5. The mobile phone works with ESP32 for key negotiation using the encryption algorithms such as DH, RSA or
ECC.
6. After the negotiation process is completed, the mobile phone will send a control frame for security-mode setup
to ESP32.
7. When receiving this control frame, ESP32 will be able to encrypt and decrypt the communication data using
the shared key and the security configuration.
8. The mobile phone sends the data frame defined in the section of The Frame Formats Defined in BluFi with
the Wi-Fi configuration information to ESP32, including SSID, password, etc.
9. The mobile phone sends a control frame of Wi-Fi connection request to ESP32. When receiving this control
frame, ESP32 will regard the communication of essential information as done and get ready to connect to the
Wi-Fi.
10. After connecting to the Wi-Fi, ESP32 will send a control frame of Wi-Fi connection status report to the mobile
phone to report the connection status. At this point the networking procedure is completed.
Note:
1. After ESP32 receives the control frame of security-mode configuration, it will execute the operations in ac-
cordance with the defined security mode.
2. The data lengths before and after symmetric encryption/decryption must stay the same. It also supports in-place
encryption and decryption.
4.3.3 The Flow Chart of BluFi
4.3.4 The Frame Formats Defined in BluFi
The frame formats for the communication between the mobile phone App and ESP32 are defined as follows:
The frame format with no fragment (8 bit)
Description Value
Type (Least Significant Bit) 1
Frame Control 1
Sequence Number 1
Data Length 1
Data ${Data Length}
CheckSum (Most Siginificant Bit) 2
If the Frame Ctrl bit is enabled, the Total length bit indicates the length of remaining part of the frame. It can tell
the remote how much memory needs to be alloced.
The frame format with fragments 8 bit
Description Value
Type (Least Significant Bit) 1
Frame Control (Frag) 1
Sequence Number 1
Data Length 1
Data
• Total Content Length: 2
• Content: ${Data Length} - 2
Normally, the control frame does not contain data bits, except for ACK Frame.

Fig. 2: BluFi Flow Chart

The format of ACK Frame 8 bit
Description Value
Type - ACK (Least Significant Bit) 1
Frame Control 1
Sequence Number 1
Data Length 1
Data Acked Sequence Number: 2
1. Type
The Type field, taking 1 byte, is divided into Type and Subtype, that Type uses the lower 2 bits and Subtype
uses the upper 6 bits.
• The control frame is not encrypted for the time being and supports to be verified;
• The data frame supports to be encrypted and verified.
1.1 Control Frame (Binary: 0x0 b 00)

Control Implication Explanation Note

Frame
0x0 ACK The data field of the ACK The data field consumes a byte and its value is
(b frame uses the same sequence the same as the sequence field of the frame to
000000) value of the frame to reply to. reply to.
0x1 Set ESP device to the To inform ESP device of the The data field consumes a byte. The higher 4
(b security mode. security mode to use when bits are for the security mode setting of the con-
000001) sending data, which is allowed trol frame, and the lower 4 bits are for the se-
to be reset multiple times dur- curity mode setting of the data frame.
ing the process. Each setting • b 0000: no checksum and no encryp-
affects the subsequent secu- tion;
rity mode used. • b 0001: with checksum but no encryp-
If it is not set, ESP device tion;
will send the control frame • b 0010: no checksum but with encryp-
and data frame with no check- tion;
sum and encryption by de- • b 0011: with both checksum and en-
fault. The data transmission cryption.
from the mobile phone to ESP
device is controlled by this
control frame.
0x2 Set the opmode of The frame contains opmode data[0] is for opmode settings, including:
(b Wi-Fi. settings for configuring the • 0x00: NULL
000010) Wi-Fi mode of ESP device. • 0x01: STA
• 0x02: SoftAP
• 0x03: SoftAP & STA
Please set the SSID/Password/Max Connection
Number of the AP mode in the first place if an
AP gets involved.
0x3 Connect ESP device To notify ESP device that the No data field is contained.
(b to the AP. essential information has been
000011) sent and it is allowed to con-
nect to the AP.
0x4 Disconnect ESP de- No data field is contained.
(b vice from the AP.
000100)
0x5 To get the informa-
• No data field is contained. When re-
(b tion of ESP device s
ceiving this control frame, ESP device
000101)Wi-Fi mode and it s
will send back a follow-up frame of Wi-
status.
Fi connection state report to the mobile
phone with the information of the cur-
rent opmode, connection status, SSID
and so on.
• The types of information sent to the mo-
bile phone is defined by the application
installed on the phone.
0x6 Disconnect the STA Date[0~5] is taken as the MAC address for the
(b device from the STA device. If there is a second STA device,
000110)SoftAP (in SoftAP then it uses data[6-11] and the rest can be done
mode). in the same manner.
0x7 Get the version infor-
(b mation.
000111)
0x8 Disconnect the BLE ESP device will disconnect the BLE GATT
(b GATT link. link after receives this command.
001000)
0x9 Get the Wi-Fi list. To get ESP device to scan the
No data field is contained. When receiving
(b Wi-Fi access points around.
this control frame, ESP device will send back
001001) a follow-up frame of Wi-Fi list report to the
mobile phone.
1.2 Data Frame (Binary: 0x1 b 01)

Data Implication Explanation Note

Frame
0x0 Send the negotiation The negotiation data will be The length of the data depends on the length
(b data. sent to the callback function field.
000000) registered in the application
layer.
0x1 Send the BSSID for To send the BSSID of the AP Please refer to Note 1 below.
(b STA mode. for the STA device to connect
000001) under the condition that the
SSID is hidden.
0x2 Send the SSID for To send the SSID of the AP Please refer to Note 1 below.
(b STA mode. for the STA device to connect.
000010)
0x3 Send the password for To send the password of the Please refer to Note 1 below.
(b STA mode. AP for the STA device to con-
000011) nect.
0x4 Send the SSID for Please refer to Note 1 below.
(b SoftAP mode.
000100)
0x5 Send the password for Please refer to Note 1 below.
(b SoftAPmode.
000101)
0x6 Set the maximum data[0] represents the value of the connection
(b connection number number, ranging from 1 to 4. When the trans-
000110)for SoftAP mode. mission direction is ESP device to the mobile
phone, it means to provide the mobile phone
with the needed information.
0x7 Set the authentication data[0]
(b mode for the SoftAP. • 0x00: OPEN
000111) • 0x01: WEP
• 0x02: WPA_PSK
• 0x03: WPA2_PSK
• 0x04: WPA_WPA2_PSK
When the transmission direction is ESP device
to the mobile phone, it means to provide the
mobile phone with the needed information.
0x8 Set the number of data[0] represents the quantity of the supported
(b channels for SoftAP channels, ranging from 1 to 14. When the
001000)mode. transmission direction is ESP device to the mo-
bile phone, it means to provide the mobile
phone with the needed information.
0x9 Username It provides the username of The length of the data depends on the length
(b the GATT client when using field.
001001) encryption of enterprise level.
0xa CA Certification It provides the CA Certifica- Please refer to Note 2 below.
(b tion when using encryption of
001010) enterprise level.
0xb Client Certification It provides the client certifica- Please refer to Note 2 below.
001011) enterprise level. Whether the
private key is contained or not
depends on the content of the
certification.
0xc Server Certification It provides the sever certifica- Please refer to Note 2 below.
001100) enterprise level. Whether the
private key is contained or not
depends on the content of the
certification.
Espressif
0xd Systems
Client Private Key 1746
It provides the private Release
key of Please refer to Note v5.0-dev-401-g451ce8a
2 below.
(b Submit Document
the client when using encryp- Feedback
001101) tion of enterprise level.
0xe Server Private Key It provides the private key of Please refer to Note 2 below.
Note:
• Note 1: The length of the data depends on the length field. When the transmission direction is ESP device to
the mobile phone, it means to provide the mobile phone with the needed information.
• Note 2: The length of the data depends on the length field. The frame supports to be fragmented if the data
length is not enough.
2. Frame Control
Control field, takes 1 byte and each bit has a different meaning.
Bit Meaning
0x01 Indicates whether the frame is encrypted.
• 1 means encryption
• 0 means unencrypted
The encrypted part of the frame includes the full clear data before the DATA field is
encrypted (no checksum). Control frame is not encrypted, so this bit is 0.
0x02 The data field that indicates whether a frame contains a checksum (such as
SHA1,MD5,CRC, etc.) for the end of the frame. Data field includes sequence + data
length + clear text. Both the control frame and the data frame can contain a check bit
or not.
0x04 Represents the data direction.
• 0 means the mobile phone to ESP device;
• 1 means ESP device to the mobile phone.
0x08 Indicates whether the other person is required to reply to an ACK.

• 0 indicates no requirement;
• 1 indicates to reply ACK.
0x10 Indicates whether there are subsequent data fragments.

• 0 indicates that there are no subsequent data fragments for this frame;
• 1 indicates that there are subsequent data fragments and used to transmit longer
data.
In the case of a frag frame, the total length of the current content section + subsequent
content section is given, in the first 2 bytes of the data field (that is, the content data of
the maximum support 64 K).
0x10~0x80 reserved
3. Sequence Control
Sequence control field. When a frame is sent,the value of sequence fied is automatically incremented by 1
regardless of the type of frame, which prevents Replay Attack. The sequence is cleared after each reconnection.
4. Length
The length of the data field that does not include CheckSum.
5. Data
The instruction of the data field is different according to various values of Type or Subtype. Please refer to the
table above.
6. CheckSum
This field takes 2 bytes that is used to check sequence + data length + clear text data .
4.3.5 The Security Implementation of ESP32
1. Securing data
To ensure that the transmission of the Wi-Fi SSID and password is secure, the message needs to be encrypted
using symmetric encryption algorithms, such as AES, DES and so on. Before using symmetric encryption
algorithms, the devices are required to negotiate (or generate) a shared key using an asymmetric encryption
algorithm (DH, RSA, ECC, etc).
2. Ensuring data integrity

To ensure data integrity, you need to add a checksum algorithm, such as SHA1, MD5, CRC, etc.
3. Securing identity (signature)
Algorithm like RSA can be used to secure identity. But for DH, it needs other algorithms as an companion for
signature.
4. Replay attack prevention
It is added to the Sequence field and used during the checksum verification.
For the coding of ESP32, you can determine and develop the security processing, such as key negotiation. The
mobile application sends the negotiation data to ESP32 and then the data will be sent to the application layer
for processing. If the application layer does not process it, you can use the DH encryption algorithm provided
by BluFi to negotiate the key.
The application layer needs to register several security-related functions to BluFi:
typedef void (*esp_blufi_negotiate_data_handler_t)(uint8_t *data, int len, uint8_t␣

,→**output_data, int *output_len, bool *need_free)
This function is for ESP32 to receive normal data during negotiation, and after processing is completed, the data will
be transmitted using Output_data and Output_len.
BluFi will send output_data from Negotiate_data_handler after Negotiate_data_handler is called.
Here are two * , because the length of the data to be emitted is unknown that requires the function to allocate
itself (malloc) or point to the global variable, and to inform whether the memory needs to be freed by NEED_FREE.
typedef int (* esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int␣

,→crypt_len)
The data to be encrypted and decrypted must use the same length. The IV8 is a 8 bit sequence value of frames, which
can be used as a 8 bit of IV.
typedef int (* esp_blufi_decrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int␣

,→crypt_len)
The data to be encrypted and decrypted must use the same length. The IV8 is a 8 bit sequence value of frames, which
can be used as a 8 bit of IV.
typedef uint16_t (*esp_blufi_checksum_func_t)(uint8_t iv8, uint8_t *data, int len)
This function is used to compute CheckSum and return a value of CheckSum. BluFi uses the returned value to
compare the CheckSum of the frame.
4.3.6 GATT Related Instructions
UUID
BluFi Service UUID: 0xFFFF, 16 bit

BluFi (the mobile -> ESP32): 0xFF01, writable
Blufi (ESP32 -> the mobile phone): 0xFF02, readable and callable
4.4 Bootloader
The ESP-IDF Software Bootloader performs the following functions:
1. Minimal initial configuration of internal modules;
2. Initialize Flash Encryption and/or Secure features, if configured;
3. Select the application partition to boot, based on the partition table and ota_data (if any);
4. Load this image to RAM (IRAM & DRAM) and transfer management to the image that was just loaded.

Bootloader is located at the address 0x1000 in the flash.

For a full description of the startup process including the the ESP-IDF bootloader, see Application Startup Flow.
4.4.1 Bootloader compatibility
It is recommended to update to newer versions of ESP-IDF: when they are released. The OTA (over the air) update
process can flash new apps in the field but cannot flash a new bootloader. For this reason, the bootloader supports
booting apps built from newer versions of ESP-IDF.
The bootloader does not support booting apps from older versions of ESP-IDF. When updating ESP-IDF manually
on an existing product that might need to downgrade the app to an older version, keep using the older ESP-IDF
bootloader binary as well.
Note: If testing an OTA update for an existing product in production, always test it using the same ESP-IDF
bootloader binary that is deployed in production.
Before ESP-IDF V2.1
Bootloaders built from very old versions of ESP-IDF (before ESP-IDF V2.1) perform less hardware configuration
than newer versions. When using a bootloader from these early ESP-IDF versions and building a new app, enable the
config option CONFIG_ESP32_COMPATIBLE_PRE_V2_1_BOOTLOADERS.
Before ESP-IDF V3.1
Bootloaders built from versions of ESP-IDF before V3.1 do not support MD5 checksums in the partition table bi-
nary. When using a bootloader from these ESP-IDF versions and building a new app, enable the config option
CONFIG_ESP32_COMPATIBLE_PRE_V3_1_BOOTLOADERS.
SPI Flash Configuration
Each ESP-IDF application or bootloader .bin file contains a header with CONFIG_ESPTOOLPY_FLASHMODE, CON-
FIG_ESPTOOLPY_FLASHFREQ, CONFIG_ESPTOOLPY_FLASHSIZE embedded in it. These are used to configure
the SPI flash during boot.
The First stage bootloader in ROM reads the Second stage bootloader header information from flash and uses this
infomation to load the rest of the Second stage bootloader from flash. However, at this time the system clock speed
is lower than configured and not all flash modes are supported. When the Second stage bootloader then runs, it will
reconfigure the flash using values read from the currently selected app binary s header (and NOT from the Second
stage bootloader header). This allows an OTA update to change the SPI flash settings in use.
Bootloaders prior to ESP-IDF V4.0 used the bootloader s own header to configure the SPI flash, meaning these
values could not be changed in an update. To maintain compatibility with older bootloaders, the app re-initializes the
flash settings during app startup using the configuration found in the app header.
4.4.2 Log Level
The default bootloader log level is Info . By setting the CONFIG_BOOTLOADER_LOG_LEVEL option, it s
possible to increase or decrease this level. This log level is separate from the log level used in the app (see Logging
library).
Reducing bootloader log verbosity can improve the overall project boot time by a small amount.

4.4.3 Factory reset
Sometimes it is desirable to have a way for the device to fall back to a known-good state, in case of some problem
with an update.
To roll back to the original factory device configuration and clear any user settings, configure the config item
CONFIG_BOOTLOADER_FACTORY_RESET in the bootloader.
The factory reset mechanism allows the device to be factory reset in two ways:
• Clear one or more data partitions. The CONFIG_BOOTLOADER_DATA_FACTORY_RESET option allows
users to specify which data partitions will be erased when the factory reset is executed.
Users can specify the names of partitions as a comma-delimited list with optional spaces for readability. (Like
this: nvs, phy_init, nvs_custom).
Make sure that the names of partitions specified in the option are the same as those found in the partition table.
Partitions of type app cannot be specified here.
• Boot from factory app partition. Enabling the CONFIG_BOOTLOADER_OTA_DATA_ERASE option will
cause the device to boot from the default factory app partition after a factory reset (or if there is no factory
app partition in the partition table then the default ota app partition is selected instead). This reset process
involves erasing the OTA data partition which holds the currently selected OTA partition slot. The factory
app partition slot (if it exists) is never updated via OTA, so resetting to this allows reverting to a known good
firmware application.
Either or both of these configuration options can be enabled independently.
In addition, the following configuration options control the reset condition:
• CONFIG_BOOTLOADER_NUM_PIN_FACTORY_RESET- The input GPIO number used to trigger a factory
reset. This GPIO must be pulled low or high (configurable) on reset to trigger this.
• CONFIG_BOOTLOADER_HOLD_TIME_GPIO- this is hold time of GPIO for reset/test mode (by default 5
seconds). The GPIO must be held continuously for this period of time after reset before a factory reset or test
partition boot (as applicable) is performed.
• CONFIG_BOOTLOADER_FACTORY_RESET_PIN_LEVEL - configure whether a factory reset should trigger
on a high or low level of the GPIO. If the GPIO has an internal pullup then this is enabled before the pin is
sampled, consult the ESP32 datasheet for details on pin internal pullups.
4.4.4 Boot from Test Firmware
It s possible to write a special firmware app for testing in production, and boot this firmware when needed. The
project partition table will need a dedicated app partition entry for this testing app, type app and subtype test (see
Partition Tables).
Implementing a dedicated test app firmware requires creating a totally separate ESP-IDF project for the test app (each
project in ESP-IDF only builds one app). The test app can be developed and tested independently of the main project,
and then integrated at production testing time as a pre-compiled .bin file which is flashed to the address of the main
project s test app partition.
To support this functionality in the main project s bootloader, set the configuration item CON-
FIG_BOOTLOADER_APP_TEST and configure the following two items:
• CONFIG_BOOTLOADER_NUM_PIN_APP_TEST - GPIO number to boot TEST partition. The selected GPIO
will be configured as an input with internal pull-up enabled. To trigger a test app, this GPIO must be pulled
low on reset.
Once the GPIO input is released (allowing it to be pulled up) and the device has been reboot, the normally
configured application will boot (factory or any OTA app partition slot).
• CONFIG_BOOTLOADER_HOLD_TIME_GPIO - this is hold time of GPIO for reset/test mode (by default 5
seconds). The GPIO must be held low continuously for this period of time after reset before a factory reset or
test partition boot (as applicable) is performed.

4.4.5 Rollback
Rollback and anti-rollback features must be configured in the bootloader as well.

Consult the App rollback and Anti-rollback sections in the OTA API reference document.
4.4.6 Watchdog
By default, the hardware RTC Watchdog timer remains running while the bootloader is running and will automatically
reset the chip if no app has successfully started after 9 seconds.
• The timeout period can be adjusted by setting CONFIG_BOOTLOADER_WDT_TIME_MS and recompiling the
bootloader.
• The app s behaviour can be adjusted so the RTC Watchdog remains enabled after app startup. The Watch-
dog would need to be explicitly reset (i.e., fed) by the app to avoid a reset. To do this, set the CON-
FIG_BOOTLOADER_WDT_DISABLE_IN_USER_CODE option, modify the app as needed, and then recom-
pile the app.
• The RTC Watchdog can be disabled in the bootloader by disabling the CON-
FIG_BOOTLOADER_WDT_ENABLE setting and recompiling the bootloader. This is not recommended.
4.4.7 Bootloader Size
When enabling additional bootloader functions, including Flash Encryption or Secure Boot, and especially if setting
a high CONFIG_BOOTLOADER_LOG_LEVEL level, then it is important to monitor the bootloader .bin file s size.
When using the default CONFIG_PARTITION_TABLE_OFFSET value 0x8000, the size limit is 0x7000 (28672) bytes.
If the bootloader binary is too large, then the bootloader build will fail with an error Bootloader binary size [..] is
too large for partition table offset . If the bootloader binary is flashed anyhow then the ESP32 will fail to boot -
errors will be logged about either invalid partition table or invalid bootloader checksum.
Options to work around this are:
• Set bootloader compiler optimization back to Size if it has been changed from this default value.
• Reduce bootloader log level. Setting log level to Warning, Error or None all significantly reduce the final binary
size (but may make it harder to debug).
• Set CONFIG_PARTITION_TABLE_OFFSET to a higher value than 0x8000, to place the partition table later
in the flash. This increases the space available for the bootloader. If the partition table CSV file con-
tains explicit partition offsets, they will need changing so no partition has an offset lower than CON-
FIG_PARTITION_TABLE_OFFSET + 0x1000. (This includes the default partition CSV files supplied
with ESP-IDF.)
When Secure Boot V2 is enabled, there is also an absolute binary size limit of 48KB (0xC000 bytes) (excluding the
4 KB signature), because the bootloader is first loaded into a fixed size buffer for verification.
4.4.8 Fast boot from Deep Sleep
The bootloader has the CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP option which allows the

wake-up time from deep sleep to be reduced (useful for reducing power consumption). This option is available when
CONFIG_SECURE_BOOT option is disabled. Reduction of time is achieved due to the lack of image verification.
During the first boot, the bootloader stores the address of the application being launched in the RTC FAST memory.
And during the awakening, this address is used for booting without any checks, thus fast loading is achieved.
4.4.9 Custom bootloader
The current bootloader implementation allows a project to extend it or modify it. There are two ways of doing it: by
implementing hooks or by overriding it. Both ways are presented in custom_bootloader folder in ESP-IDF examples:

• bootloader_hooks which presents how to connect some hooks to the bootloader initialization
• bootloader_override which presents how to override the bootloader implementation
In the bootloader space, you cannot use the drivers and functions from other components. If necessary, then the
required functionality should be placed in the project s bootloader_components directory (note that this will increase
its size).
If the bootloader grows too large then it can collide with the partition table, which is flashed at offset 0x8000 by
default. Increase the partition table offset value to place the partition table later in the flash. This increases the space
available for the bootloader.
4.5 Build System

This document explains the implementation of the ESP-IDF build system and the concept of components . Read
this document if you want to know how to organize and build a new ESP-IDF project or component.
4.5.1 Overview
An ESP-IDF project can be seen as an amalgamation of a number of components. For example, for a webserver that
shows the current humidity, there could be:
• The ESP-IDF base libraries (libc, ROM bindings, etc)
• The Wi-Fi drivers
• A TCP/IP stack
• The FreeRTOS operating system
• A webserver
• A driver for the humidity sensor
• Main code tying it all together
ESP-IDF makes these components explicit and configurable. To do that, when a project is compiled, the build system
will look up all the components in the ESP-IDF directories, the project directories and (optionally) in additional
custom component directories. It then allows the user to configure the ESP-IDF project using a text-based menu
system to customize each component. After the components in the project are configured, the build system will
compile the project.
Concepts
• A project is a directory that contains all the files and configuration to build a single app (executable),
as well as additional supporting elements such as a partition table, data/filesystem partitions, and a bootloader.
• Project configuration is held in a single file called sdkconfig in the root directory of the project. This
configuration file is modified via idf.py menuconfig to customise the configuration of the project. A
single project contains exactly one project configuration.
• An app is an executable which is built by ESP-IDF. A single project will usually build two apps - a project
app (the main executable, ie your custom firmware) and a bootloader app (the initial bootloader program
which launches the project app).
• components are modular pieces of standalone code which are compiled into static libraries (.a files) and
linked into an app. Some are provided by ESP-IDF itself, others may be sourced from other places.
• Target is the hardware for which an application is built. At the moment, ESP-IDF supports esp32,
esp32s2 and esp32c3 targets.
Some things are not part of the project:
• ESP-IDF is not part of the project. Instead it is standalone, and linked to the project via the IDF_PATH
environment variable which holds the path of the esp-idf directory. This allows the IDF framework to be
decoupled from your project.
• The toolchain for compilation is not part of the project. The toolchain should be installed in the system com-
mand line PATH.

4.5.2 Using the Build System
idf.py
The idf.py command line tool provides a front-end for easily managing your project builds. It manages the fol-
lowing tools:
• CMake, which configures the project to be built
• A command line build tool (either Ninja build or GNU Make)
• esptool.py for flashing the target.
The getting started guide contains a brief introduction to how to set up idf.py to configure, build, and flash projects.
idf.py should be run in an ESP-IDF project directory, ie one containing a CMakeLists.txt file. Older
style projects with a Makefile will not work with idf.py.
Type idf.py --help for a list of commands. Here are a summary of the most useful ones:
• idf.py set-target <target> sets the target (chip) for which the project is built. See Selecting the
Target.
• idf.py menuconfig runs the menuconfig tool to configure the project.
• idf.py build will build the project found in the current directory. This can involve multiple steps:
– Create the build directory if needed. The sub-directory build is used to hold build output, although
this can be changed with the -B option.
– Run CMake as necessary to configure the project and generate build files for the main build tool.
– Run the main build tool (Ninja or GNU Make). By default, the build tool is automatically detected but it
can be explicitly set by passing the -G option to idf.py.
Building is incremental so if no source files or configuration has changed since the last build, nothing will be
done.
• idf.py clean will clean the project by deleting build output files from the build directory, forcing a
full rebuild the next time the project is built. Cleaning doesn t delete CMake configuration output and some
other files.
• idf.py fullclean will delete the entire build directory contents. This includes all CMake configuration
output. The next time the project is built, CMake will configure it from scratch. Note that this option recursively
deletes all files in the build directory, so use with care. Project configuration is not deleted.
• idf.py flash will automatically build the project if necessary, and then flash it to the target. The -p and
-b options can be used to set serial port name and flasher baud rate, respectively.
• idf.py monitor will display serial output from the target. The -p option can be used to set the serial port
name. Type Ctrl-] to exit the monitor. See IDF Monitor for more details about using the monitor.
Multiple idf.py commands can be combined into one. For example, idf.py -p COM4 clean flash
monitor will clean the source tree, then build the project and flash it to the target before running the serial monitor.
For commands that are not known to idf.py an attempt to execute them as a build system target will be made.
The command idf.py supports shell autocompletion for bash, zsh and fish shells.
In order to make shell autocompletion supported, please make sure you have at least Python 3.5 and click 7.1 or newer
(see also).
To enable autocompletion for idf.py use the export command (see this). Autocompletion is initiated by pressing
the TAB key. Type idf.py - and press the TAB key to autocomplete options.
The autocomplete support for PowerShell is planned in the future.
Note: The environment variables ESPPORT and ESPBAUD can be used to set default values for the -p and -b
options, respectively. Providing these options on the command line overrides the default.
Advanced Commands
• idf.py app, idf.py bootloader, idf.py partition-table can be used to build only the
app, bootloader, or partition table from the project as applicable.

• There are matching commands idf.py app-flash, etc. to flash only that single part of the project to the
target.
• idf.py -p PORT erase-flash will use esptool.py to erase the target s entire flash chip.
• idf.py size prints some size information about the app. size-components and size-files are
similar commands which print more detailed per-component or per-source-file information, respectively. If
you define variable -DOUTPUT_JSON=1 when running CMake (or idf.py), the output will be formatted
as JSON not as human readable text. See idf.py-size for more information.
• idf.py reconfigure re-runs CMake even if it doesn t seem to need re-running. This isn t necessary
during normal usage, but can be useful after adding/removing files from the source tree, or when modifying
CMake cache variables. For example, idf.py -DNAME='VALUE' reconfigure can be used to set
variable NAME in CMake cache to value VALUE.
• idf.py python-clean deletes generated Python byte code from the IDF directory which may cause
issues when switching between IDF and Python versions. It is advised to run this target after switching versions
of Python.
• idf.py docs will open direct link to documentation for project s chip target and version in browser. To
see all options use idf.py docs --help
The order of multiple idf.py commands on the same invocation is not important, they will automatically be exe-
cuted in the correct order for everything to take effect (ie building before flashing, erasing before flashing, etc.).
idf.py options To list all available root level options, run idf.py --help. To list options that are specific for
a subcommand, run idf.py <command> --help, for example idf.py monitor --help. Here is a list
of some useful options:
• -C <dir> allows overriding the project directory from the default current working directory.
• -B <dir> allows overriding the build directory from the default build subdirectory of the project directory.
• --ccache flag can be used to enable CCache when compiling source files, if the CCache tool is installed.
This can dramatically reduce some build times.
Note that some older versions of CCache may exhibit bugs on some platforms, so if files are not rebuilt as expected
then try disabling CCache and build again. CCache can be enabled by default by setting the IDF_CCACHE_ENABLE
environment variable to a non-zero value.
• -v flag causes both idf.py and the build system to produce verbose build output. This can be useful for
debugging build problems.
• --cmake-warn-uninitialized (or -w) will cause CMake to print uninitialized variable warnings in-
side the project directory (not for directories not found inside the project directory). This only controls CMake
variable warnings inside CMake itself, not other types of build warnings. This option can also be set perma-
nently by setting the IDF_CMAKE_WARN_UNINITIALIZED environment variable to a non-zero value.
Start a new project
Use the command idf.py create-project for starting a new project. Execute idf.py create-
project --help for more information.
Example:
idf.py create-project --path my_projects my_new_project
This example will create a new project called my_new_project directly into the directory my_projects.
Using CMake Directly
idf.py is a wrapper around CMake for convenience. However, you can also invoke CMake directly if you prefer.
When idf.py does something, it prints each command that it runs for easy reference. For example, the idf.
py build command is the same as running these commands in a bash shell (or similar commands for Windows
Command Prompt):

mkdir -p build
cd build
cmake .. -G Ninja # or 'Unix Makefiles'
ninja
In the above list, the cmake command configures the project and generates build files for use with the final build
tool. In this case the final build tool is Ninja: running ninja actually builds the project.
It s not necessary to run cmake more than once. After the first build, you only need to run ninja each time.
ninja will automatically re-invoke cmake if the project needs reconfiguration.
If using CMake with ninja or make, there are also targets for more of the idf.py sub-commands - for example
running make menuconfig or ninja menuconfig in the build directory will work the same as idf.py
menuconfig.
Note: If you re already familiar with CMake, you may find the ESP-IDF CMake-based build system unusual
because it wraps a lot of CMake s functionality to reduce boilerplate. See writing pure CMake components for some
information about writing more CMake style components.
Flashing with ninja or make It s possible to build and flash directly from ninja or make by running a target like:
ninja flash
Or:
make app-flash
Available targets are: flash, app-flash (app only), bootloader-flash (bootloader only).
When flashing this way, optionally set the ESPPORT and ESPBAUD environment variables to specify the serial port
and baud rate. You can set environment variables in your operating system or IDE project. Alternatively, set them
directly on the command line:
ESPPORT=/dev/ttyUSB0 ninja flash
Note: Providing environment variables at the start of the command like this is Bash shell Syntax. It will work on
Linux and macOS. It won t work when using Windows Command Prompt, but it will work when using Bash-like
shells on Windows.
Or:
make -j3 app-flash ESPPORT=COM4 ESPBAUD=2000000
Note: Providing variables at the end of the command line is make syntax, and works for make on all platforms.
Using CMake in an IDE
You can also use an IDE with CMake integration. The IDE will want to know the path to the project s CMake-
Lists.txt file. IDEs with CMake integration often provide their own build tools (CMake calls these generators
) to build the source files as part of the IDE.
When adding custom non-build steps like flash to the IDE, it is recommended to execute idf.py for these
special commands.
For more detailed information about integrating ESP-IDF with CMake into an IDE, see Build System Metadata.

Setting up the Python Interpreter
ESP-IDF works well with all supported Python versions. It should work out-of-box even if you have a legacy system
where the default python interpreter is still Python 2.7, however, it is advised to switch to Python 3 if possible.
idf.py and other Python scripts will run with the default Python interpreter, i.e. python. You can switch to a
different one like python3 $IDF_PATH/tools/idf.py ..., or you can set up a shell alias or another script
to simplify the command.
If using CMake directly, running cmake -D PYTHON=python3 ... will cause CMake to override the default
Python interpreter.
If using an IDE with CMake, setting the PYTHON value as a CMake cache override in the IDE UI will override the
default Python interpreter.
To manage the Python version more generally via the command line, check out the tools pyenv or virtualenv. These
let you change the default Python version.
Possible issues The user of idf.py may sometimes experience ImportError described below.
Traceback (most recent call last):

File "/Users/user_name/e/esp-idf/tools/kconfig_new/confgen.py", line 27, in
,→<module>
import kconfiglib
ImportError: bad magic number in 'kconfiglib': b'\x03\xf3\r\n'
The exception is often caused by .pyc files generated by different Python versions. To solve the issue run the
following command:
idf.py python-clean
4.5.3 Example Project
An example project directory tree might look like this:
- myProject/
- CMakeLists.txt
- sdkconfig
- components/ - component1/ - CMakeLists.txt
- Kconfig
- src1.c
- component2/ - CMakeLists.txt
- Kconfig
- src1.c
- include/ - component2.h
- main/ - CMakeLists.txt
- src1.c
- src2.c
- build/
This example myProject contains the following elements:

• A top-level project CMakeLists.txt file. This is the primary file which CMake uses to learn how to build
the project; and may set project-wide CMake variables. It includes the file /tools/cmake/project.cmake which
implements the rest of the build system. Finally, it sets the project name and defines the project.
• sdkconfig project configuration file. This file is created/updated when idf.py menuconfig runs, and
holds configuration for all of the components in the project (including ESP-IDF itself). The sdkconfig file
may or may not be added to the source control system of the project.

• Optional components directory contains components that are part of the project. A project does not have
to contain custom components of this kind, but it can be useful for structuring reusable code or including third
party components that aren t part of ESP-IDF. Alternatively, EXTRA_COMPONENT_DIRS can be set in
the top-level CMakeLists.txt to look for components in other places. See the renaming main section for more
info. If you have a lot of source files in your project, we recommend grouping most into components instead
of putting them all in main .
• main directory is a special component that contains source code for the project itself. main is a default
name, the CMake variable COMPONENT_DIRS includes this component but you can modify this variable.
• build directory is where build output is created. This directory is created by idf.py if it doesn t already
exist. CMake configures the project and generates interim build files in this directory. Then, after the main
build process is run, this directory will also contain interim object files and libraries as well as final binary
output files. This directory is usually not added to source control or distributed with the project source code.
Component directories each contain a component CMakeLists.txt file. This file contains variable definitions to
control the build process of the component, and its integration into the overall project. See Component CMakeLists
Files for more details.
Each component may also include a Kconfig file defining the component configuration options that can be set via
menuconfig. Some components may also include Kconfig.projbuild and project_include.cmake
files, which are special files for overriding parts of the project.
4.5.4 Project CMakeLists File
Each project has a single top-level CMakeLists.txt file that contains build settings for the entire project. By
default, the project CMakeLists can be quite minimal.
Minimal Example CMakeLists
Minimal project:
cmake_minimum_required(VERSION 3.5)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(myProject)
Mandatory Parts
The inclusion of these three lines, in the order shown above, is necessary for every project:
• cmake_minimum_required(VERSION 3.5) tells CMake the minimum version that is required to
build the project. ESP-IDF is designed to work with CMake 3.5 or newer. This line must be the first line in
the CMakeLists.txt file.
• include($ENV{IDF_PATH}/tools/cmake/project.cmake) pulls in the rest of the CMake
functionality to configure the project, discover all the components, etc.
• project(myProject) creates the project itself, and specifies the project name. The project name is used
for the final binary output files of the app - ie myProject.elf, myProject.bin. Only one project can
be defined per CMakeLists file.
Optional Project Variables
These variables all have default values that can be overridden for custom behaviour. Look in
/tools/cmake/project.cmake for all of the implementation details.
• COMPONENT_DIRS: Directories to search for components. Defaults to IDF_PATH/components,
PROJECT_DIR/components, and EXTRA_COMPONENT_DIRS. Override this variable if you don t
want to search for components in these places.
• EXTRA_COMPONENT_DIRS: Optional list of additional directories to search for components. Paths can be
relative to the project directory, or absolute.

• COMPONENTS: A list of component names to build into the project. Defaults to all components found in the
COMPONENT_DIRS directories. Use this variable to trim down the project for faster build times. Note that
any component which requires another component via the REQUIRES or PRIV_REQUIRES arguments
on component registration will automatically have it added to this list, so the COMPONENTS list can be very
short.
Any paths in these variables can be absolute paths, or set relative to the project directory.
To set these variables, use the cmake set command ie set(VARIABLE "VALUE"). The set() commands
should be placed after the cmake_minimum(...) line but before the include(...) line.
Renaming main component
The build system provides special treatment to the main component. It is a component that gets automatically added
to the build provided that it is in the expected location, PROJECT_DIR/main. All other components in the build are
also added as its dependencies, saving the user from hunting down dependencies and providing a build that works right
out of the box. Renaming the main component causes the loss of these behind-the-scenes heavy lifting, requiring the
user to specify the location of the newly renamed component and manually specifying its dependencies. Specifically,
the steps to renaming main are as follows:
1. Rename main directory.
2. Set EXTRA_COMPONENT_DIRS in the project CMakeLists.txt to include the renamed main directory.
3. Specify the dependencies in the renamed component s CMakeLists.txt file via REQUIRES or
PRIV_REQUIRES arguments on component registration.
Overriding default build specifications
The build sets some global build specifications (compile flags, definitions, etc.) that gets used in compiling all sources
from all components.
For example, one of the default build specifications set is the compile option -Wextra. Suppose a user wants to use
override this with -Wno-extra, it should be done after project():
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(myProject)
idf_build_set_property(COMPILE_OPTIONS "-Wno-error" APPEND)
This ensures that the compile options set by the user won t be overriden by the default build specifications, since the
latter are set inside project().
4.5.5 Component CMakeLists Files
Each project contains one or more components. Components can be part of ESP-IDF, part of the project s own
components directory, or added from custom component directories (see above).
A component is any directory in the COMPONENT_DIRS list which contains a CMakeLists.txt file.
Searching for Components
The list of directories in COMPONENT_DIRS is searched for the project s components. Directories in this list can
either be components themselves (ie they contain a CMakeLists.txt file), or they can be top-level directories whose
sub-directories are components.
When CMake runs to configure the project, it logs the components included in the build. This list can be useful for
debugging the inclusion/exclusion of certain components.

Multiple components with the same name
When ESP-IDF is collecting all the components to compile, it will do this in the order specified by COMPO-
NENT_DIRS; by default, this means ESP-IDF s internal components first (IDF_PATH/components), then
any components in directories specified in EXTRA_COMPONENT_DIRS, and finally the project s components
(PROJECT_DIR/components). If two or more of these directories contain component sub-directories with the
same name, the component in the last place searched is used. This allows, for example, overriding ESP-IDF com-
ponents with a modified version by copying that component from the ESP-IDF components directory to the project
components directory and then modifying it there. If used in this way, the ESP-IDF directory itself can remain
untouched.
Note: If a component is overridden in an existing project by moving it to a new location, the project will not
automatically see the new component path. Run idf.py reconfigure (or delete the project build folder) and
then build again.
Minimal Component CMakeLists
The minimal component CMakeLists.txt file simply registers the component to the build system using
idf_component_register:
idf_component_register(SRCS "foo.c" "bar.c"
INCLUDE_DIRS "include"
REQUIRES mbedtls)
• SRCS is a list of source files (*.c, *.cpp, *.cc, *.S). These source files will be compiled into the com-
ponent library.
• INCLUDE_DIRS is a list of directories to add to the global include search path for any component which
requires this component, and also the main source files.
• REQUIRES is not actually required, but it is very often required to declare what other components this com-
ponent will use. See Component Requirements.
A library with the name of the component will be built and linked into the final app.
Directories are usually specified relative to the CMakeLists.txt file itself, although they can be absolute.
There are other arguments that can be passed to idf_component_register. These arguments are discussed
here.
See example component requirements and example component CMakeLists for more complete component CMake-
Lists.txt examples.
Create a new component
Use the command idf.py create-component for creating a new component. The new component will contain
set of files necessary for building a component. You may include the component s header file into your project and
use its functionality. For more information execute idf.py create-component --help.
Example:
idf.py -C components create-component my_component
The example will create a new component in the subdirectory components under the current working directory. For
more information about components follow the documentation page see above.
Preset Component Variables
The following component-specific variables are available for use inside component CMakeLists, but should not be
modified:

• COMPONENT_DIR: The component directory. Evaluates to the absolute path of the directory con-
taining CMakeLists.txt. The component path cannot contain spaces. This is the same as the
CMAKE_CURRENT_SOURCE_DIR variable.
• COMPONENT_NAME: Name of the component. Same as the name of the component directory.
• COMPONENT_ALIAS: Alias of the library created internally by the build system for the component.
• COMPONENT_LIB: Name of the library created internally by the build system for the component.
The following variables are set at the project level, but available for use in component CMakeLists:
• CONFIG_*: Each value in the project configuration has a corresponding variable available in cmake. All
names begin with CONFIG_. More information here.
• ESP_PLATFORM: Set to 1 when the CMake file is processed within ESP-IDF build system.
Build/Project Variables
The following are some project/build variables that are available as build properties and whose values can be queried
using idf_build_get_property from the component CMakeLists.txt:
• PROJECT_NAME: Name of the project, as set in project CMakeLists.txt file.
• PROJECT_DIR: Absolute path of the project directory containing the project CMakeLists. Same as the
CMAKE_SOURCE_DIR variable.
• COMPONENTS: Names of all components that are included in this build, formatted as a semicolon-delimited
CMake list.
• IDF_VER: Git version of ESP-IDF (produced by git describe)
• IDF_VERSION_MAJOR, IDF_VERSION_MINOR, IDF_VERSION_PATCH: Components of ESP-IDF
version, to be used in conditional expressions. Note that this information is less precise than that provided
by IDF_VER variable. v4.0-dev-*, v4.0-beta1, v4.0-rc1 and v4.0 will all have the same values
of IDF_VERSION_* variables, but different IDF_VER values.
• IDF_TARGET: Name of the target for which the project is being built.
• PROJECT_VER: Project version.
– If CONFIG_APP_PROJECT_VER_FROM_CONFIG option is set, the value of CON-
FIG_APP_PROJECT_VER will be used.
– Else, if PROJECT_VER variable is set in project CMakeLists.txt file, its value will be used.
– Else, if the PROJECT_DIR/version.txt exists, its contents will be used as PROJECT_VER.
– Else, if the project is located inside a Git repository, the output of git describe will be used.
– Otherwise, PROJECT_VER will be 1 .
Other build properties are listed here.
Controlling Component Compilation
To pass compiler options when compiling source files belonging to a particular component, use the tar-
get_compile_options function:
target_compile_options(${COMPONENT_LIB} PRIVATE -Wno-unused-variable)
To apply the compilation flags to a single source file, use the CMake set_source_files_properties command:
set_source_files_properties(mysrc.c
PROPERTIES COMPILE_FLAGS
-Wno-unused-variable
)
This can be useful if there is upstream code that emits warnings.

When using these commands, place them after the call to idf_component_register in the component
CMakeLists file.

4.5.6 Component Configuration
Each component can also have a Kconfig file, alongside CMakeLists.txt. This contains configuration settings
to add to the configuration menu for this component.
These settings are found under the Component Settings menu when menuconfig is run.
To create a component Kconfig file, it is easiest to start with one of the Kconfig files distributed with ESP-IDF.
For an example, see Adding conditional configuration.
4.5.7 Preprocessor Definitions
The ESP-IDF build system adds the following C preprocessor definitions on the command line:
• ESP_PLATFORM : Can be used to detect that build happens within ESP-IDF.
• IDF_VER : Defined to a git version string. E.g. v2.0 for a tagged release or v1.0-275-g0efaa4f for
an arbitrary commit.
4.5.8 Component Requirements
When compiling each component, the ESP-IDF build system recursively evaluates its dependencies. This means each
component needs to declare the components that it depends on ( requires ).
When writing a component
idf_component_register(...
REQUIRES mbedtls
PRIV_REQUIRES console spiffs)
• REQUIRES should be set to all components whose header files are #included from the public header files of
this component.
• PRIV_REQUIRES should be set to all components whose header files are #included from any source files in
this component, unless already listed in REQUIRES. Also any component which is required to be linked in
order for this component to function correctly.
• The values of REQUIRES and PRIV_REQUIRES should not depend on any configuration choices
(CONFIG_xxx macros). This is because requirements are expanded before configuration is loaded. Other
component variables (like include paths or source files) can depend on configuration choices.
• Not setting either or both REQUIRES variables is fine. If the component has no requirements except for the
Common component requirements needed for RTOS, libc, etc.
If a components only supports some target chips (values of IDF_TARGET) then it can specify RE-
QUIRED_IDF_TARGETS in the idf_component_register call to express these requirements. In this case
the build system will generate an error if the component is included into the build, but does not support the selected
target.
Note: In CMake terms, REQUIRES & PRIV_REQUIRES are approximate wrappers around the CMake functions
target_link_libraries(... PUBLIC ...) and target_link_libraries(... PRIVATE .
..).
Example of component requirements
Imagine there is a car component, which uses the engine component, which uses the spark_plug component:

- autoProject/
- CMakeLists.txt
- components/ - car/ - CMakeLists.txt
- car.c
- car.h
- engine/ - CMakeLists.txt
- engine.c
- include/ - engine.h
- spark_plug/ - CMakeLists.txt
- plug.c
- plug.h
Car component The car.h header file is the public interface for the car component. This header includes
engine.h directly because it uses some declarations from this header:
/* car.h */
#include "engine.h"
#ifdef ENGINE_IS_HYBRID
#define CAR_MODEL "Hybrid"
#endif
And car.c includes car.h as well:
/* car.c */
#include "car.h"
This means the car/CMakeLists.txt file needs to declare that car requires engine:
idf_component_register(SRCS "car.c"
INCLUDE_DIRS "."
REQUIRES engine)
• SRCS gives the list of source files in the car component.

• INCLUDE_DIRS gives the list of public include directories for this component. Because the public interface
is car.h, the directory containing car.h is listed here.
• REQUIRES gives the list of components required by the public interface of this component. Because car.h
is a public header and includes a header from engine, we include engine here. This makes sure that any
other component which includes car.h will be able to recursively include the required engine.h also.
Engine component The engine component also has a public header file include/engine.h, but this header
is simpler:
/* engine.h */
#define ENGINE_IS_HYBRID
void engine_start(void);
The implementation is in engine.c:
/* engine.c */
#include "engine.h"
#include "spark_plug.h"
...
In this component, engine depends on spark_plug but this is a private dependency. spark_plug.h is needed
to compile engine.c, but not needed to include engine.h.
This means that the engine/CMakeLists.txt file can use PRIV_REQUIRES:

idf_component_register(SRCS "engine.c"
PRIV_REQUIRES spark_plug)
As a result, source files in the car component don t need the spark_plug include directories added to their
compiler search path. This can speed up compilation, and stops compiler command lines from becoming longer than
necessary.
Spark Plug Component The spark_plug component doesn t depend on anything else. It has a public header
file spark_plug.h, but this doesn t include headers from any other components.
This means that the spark_plug/CMakeLists.txt file doesn t need any REQUIRES or PRIV_REQUIRES
clauses:
idf_component_register(SRCS "spark_plug.c"
INCLUDE_DIRS ".")
Source File Include Directories
Each component s source file is compiled with these include path directories, as specified in the passed arguments
to idf_component_register:
idf_component_register(..
PRIV_INCLUDE_DIRS "other")
• The current component s INCLUDE_DIRS and PRIV_INCLUDE_DIRS.

• The INCLUDE_DIRS belonging to all other components listed in the REQUIRES and PRIV_REQUIRES
parameters (ie all the current component s public and private dependencies).
• Recursively, all of the INCLUDE_DIRS of those components REQUIRES lists (ie all public dependencies of
this component s dependencies, recursively expanded).
Main component requirements
The component named main is special because it automatically requires all other components in the build. So it s
not necessary to pass REQUIRES or PRIV_REQUIRES to this component. See renaming main for a description of
what needs to be changed if no longer using the main component.
Common component requirements
To avoid duplication, every component automatically requires some common IDF components even if they are
not mentioned explicitly. Headers from these components can always be included.
The list of common components is: cxx, newlib, freertos, esp_hw_support, heap, log, lwip, soc, hal, esp_rom,
esp_common, esp_system.
Including components in the build
• By default, every component is included in the build.

• If you set the COMPONENTS variable to a minimal list of components used directly by your project, then the
build will expand to also include required components. The full list of components will be:
– Components mentioned explicitly in COMPONENTS.
– Those components requirements (evaluated recursively).
– The common components that every component depends on.
• Setting COMPONENTS to the minimal list of required components can significantly reduce compile times.

Circular Dependencies
It s possible for a project to contain Component A that requires (REQUIRES or PRIV_REQUIRES) Component
B, and Component B that requires Component A. This is known as a dependency cycle or a circular dependency.
CMake will usually handle circular dependencies automatically by repeating the component library names twice on
the linker command line. However this strategy doesn t always work, and it s possible the build will fail with a
linker error about Undefined reference to , referencing a symbol defined by one of the components inside the
circular dependency. This is particularly likely if there is a large circular dependency, i.e. A->B->C->D->A.
The best solution is to restructure the components to remove the circular dependency. In most cases, a software
architecture without circular dependencies has desirable properties of modularity and clean layering and will be more
maintainable in the long term. However, removing circular dependencies is not always possible.
To bypass a linker error caused by a circular dependency, the simplest workaround is to increase the CMake
LINK_INTERFACE_MULTIPLICITY property of one of the component libraries. This causes CMake to repeat
this library and its dependencies more than two times on the linker command line.
For example:
set_property(TARGET ${COMPONENT_LIB} APPEND PROPERTY LINK_INTERFACE_MULTIPLICITY 3)
• This line should be placed after idf_component_register in the component CMakeLists.txt file.
• If possible, place this line in the component that creates the circular dependency by depending on a lot of
other components. However, the line can be placed inside any component that is part of the cycle. Choosing
the component that owns the source file shown in the linker error message, or the component that defines the
symbol(s) mentioned in the linker error message, is a good place to start.
• Usually increasing the value to 3 (default is 2) is enough, but if this doesn t work then try increasing the
number further.
• Adding this option will make the linker command line longer, and the linking stage slower.
Advanced Workaround: Undefined Symbols If only one or two symbols is causing a circular dependency, and all
other dependencies are linear, then there is an alternative method to avoid linker errors: Specify the specific symbols
required for the reverse dependency as undefined symbols at link time.
For example, if component A depends on component B but component B also needs to reference reverse_ops
from component A (but nothing else), then you can add a line like the following to the component B CMakeLists.txt
to resolve the cycle at link time:
# This symbol is provided by 'Component A' at link time

target_link_libraries(${COMPONENT_LIB} INTERFACE "-u reverse_ops")
• The -u argument means that the linker will always include this symbol in the link, regardless of dependency
ordering.
• This line should be placed after idf_component_register in the component CMakeLists.txt file.
• If Component B doesn t need to access any headers of Component A , only link to a few symbol(s), then
this line can be used instead of any REQUIRES from B to A. This further simplifies the component structure
in the build system.
See the target_link_libraries documentation for more information about this CMake function.
Requirements in the build system implementation
• Very early in the CMake configuration process, the script expand_requirements.cmake is run. This
script does a partial evaluation of all component CMakeLists.txt files and builds a graph of component require-
ments (this graph may have cycles). The graph is used to generate a file component_depends.cmake in
the build directory.
• The main CMake process then includes this file and uses it to determine the list of components to include
in the build (internal BUILD_COMPONENTS variable). The BUILD_COMPONENTS variable is sorted so
dependencies are listed first, however as the component dependency graph has cycles this cannot be guaranteed

for all components. The order should be deterministic given the same set of components and component
dependencies.
• The value of BUILD_COMPONENTS is logged by CMake as Component names:
• Configuration is then evaluated for the components included in the build.
• Each component is included in the build normally and the CMakeLists.txt file is evaluated again to add the
component libraries to the build.
Component Dependency Order The order of components in the BUILD_COMPONENTS variable determines
other orderings during the build:
• Order that project_include.cmake files are included into the project.
• Order that the list of header paths is generated for compilation (via -I argument). (Note that for a given
component s source files, only that component s dependency s header paths are passed to the compiler.)
4.5.9 Overriding Parts of the Project
project_include.cmake
For components that have build requirements which must be evaluated before any component CMakeLists files are
evaluated, you can create a file called project_include.cmake in the component directory. This CMake file
is included when project.cmake is evaluating the entire project.
project_include.cmake files are used inside ESP-IDF, for defining project-wide build features such as es-
ptool.py command line arguments and the bootloader special app .
Unlike component CMakeLists.txt files, when including a project_include.cmake file the current
source directory (CMAKE_CURRENT_SOURCE_DIR and working directory) is the project directory. Use the vari-
able COMPONENT_DIR for the absolute directory of the component.
Note that project_include.cmake isn t necessary for the most common component uses - such as adding
include directories to the project, or LDFLAGS to the final linking step. These values can be customised via the
CMakeLists.txt file itself. See Optional Project Variables for details.
project_include.cmake files are included in the order given in BUILD_COMPONENTS variable (as logged
by CMake). This means that a component s project_include.cmake file will be included after it s all
dependencies project_include.cmake files, unless both components are part of a dependency cycle. This
is important if a project_include.cmake file relies on variables set by another component. See also above.
Take great care when setting variables or targets in a project_include.cmake file. As the values are included
into the top-level project CMake pass, they can influence or break functionality across all components!
KConfig.projbuild
This is an equivalent to project_include.cmake for Component Configuration KConfig files. If you want
to include configuration options at the top-level of menuconfig, rather than inside the Component Configuration
sub-menu, then these can be defined in the KConfig.projbuild file alongside the CMakeLists.txt file.
Take care when adding configuration values in this file, as they will be included across the entire project configuration.
Where possible, it s generally better to create a KConfig file for Component Configuration.
project_include.cmake files are used inside ESP-IDF, for defining project-wide build features such as es-
ptool.py command line arguments and the bootloader special app .
4.5.10 Configuration-Only Components
Special components which contain no source files, only Kconfig.projbuild and KConfig, can have a one-line
CMakeLists.txt file which calls the function idf_component_register() with no arguments specified.
This function will include the component in the project build, but no library will be built and no header files will be
added to any include paths.

4.5.11 Debugging CMake
For full details about CMake and CMake commands, see the CMake v3.5 documentation.
Some tips for debugging the ESP-IDF CMake-based build system:
• When CMake runs, it prints quite a lot of diagnostic information including lists of components and component
paths.
• Running cmake -DDEBUG=1 will produce more verbose diagnostic output from the IDF build system.
• Running cmake with the --trace or --trace-expand options will give a lot of information about
control flow. See the cmake command line documentation.
When included from a project CMakeLists file, the project.cmake file defines some utility modules and global
variables and then sets IDF_PATH if it was not set in the system environment.
It also defines an overridden custom version of the built-in CMake project function. This function is overridden
to add all of the ESP-IDF specific project functionality.
Warning On Undefined Variables
By default, idf.py passes the --warn-uninitialized flag to CMake so it will print a warning if an undefined
variable is referenced in the build. This can be very useful to find buggy CMake files.
If you don t want this behaviour, it can be disabled by passing --no-warnings to idf.py.
Browse the /tools/cmake/project.cmake file and supporting functions in /tools/cmake/ for more details.
4.5.12 Example Component CMakeLists
Because the build environment tries to set reasonable defaults that will work most of the time, component CMake-
Lists.txt can be very small or even empty (see Minimal Component CMakeLists). However, overriding component
variables is usually required for some functionality.
Here are some more advanced examples of component CMakeLists files.
Adding conditional configuration
The configuration system can be used to conditionally compile some files depending on the options selected in the
project configuration.
Kconfig:
config FOO_ENABLE_BAR
bool "Enable the BAR feature."
help
This enables the BAR feature of the FOO component.
CMakeLists.txt:
set(srcs "foo.c" "more_foo.c")
if(CONFIG_FOO_ENABLE_BAR)
list(APPEND srcs "bar.c")
endif()
idf_component_register(SRCS "${srcs}"
...)
This example makes use of the CMake if function and list APPEND function.
This can also be used to select or stub out an implementation, as such:

Kconfig:
config ENABLE_LCD_OUTPUT
bool "Enable LCD output."
help
Select this if your board has a LCD.
config ENABLE_LCD_CONSOLE
bool "Output console text to LCD"
depends on ENABLE_LCD_OUTPUT
help
Select this to output debugging output to the lcd
config ENABLE_LCD_PLOT
bool "Output temperature plots to LCD"
depends on ENABLE_LCD_OUTPUT
help
Select this to output temperature plots
CMakeLists.txt:
if(CONFIG_ENABLE_LCD_OUTPUT)
set(srcs lcd-real.c lcd-spi.c)
else()
set(srcs lcd-dummy.c)
endif()
# We need font if either console or plot is enabled

if(CONFIG_ENABLE_LCD_CONSOLE OR CONFIG_ENABLE_LCD_PLOT)
list(APPEND srcs "font.c")
endif()
idf_component_register(SRCS "${srcs}"
...)
Conditions which depend on the target
The current target is available to CMake files via IDF_TARGET variable.

In addition to that, if target xyz is used (IDF_TARGET=xyz), then Kconfig variable CON-
FIG_IDF_TARGET_XYZ will be set.
Note that component dependencies may depend on IDF_TARGET variable, but not on Kconfig variables. Also one
can not use Kconfig variables in include statements in CMake files, but IDF_TARGET can be used in such context.
Source Code Generation
Some components will have a situation where a source file isn t supplied with the component itself but has to be
generated from another file. Say our component has a header file that consists of the converted binary data of a BMP
file, converted using a hypothetical tool called bmp2h. The header file is then included in as C source file called
graphics_lib.c:
add_custom_command(OUTPUT logo.h
COMMAND bmp2h -i ${COMPONENT_DIR}/logo.bmp -o log.h
DEPENDS ${COMPONENT_DIR}/logo.bmp
VERBATIM)
add_custom_target(logo DEPENDS logo.h)

add_dependencies(${COMPONENT_LIB} logo)


set_property(DIRECTORY "${COMPONENT_DIR}" APPEND PROPERTY
ADDITIONAL_MAKE_CLEAN_FILES logo.h)
This answer is adapted from the CMake FAQ entry, which contains some other examples that will also work with
ESP-IDF builds.
In this example, logo.h will be generated in the current directory (the build directory) while logo.bmp comes with the
component and resides under the component path. Because logo.h is a generated file, it should be cleaned when the
project is cleaned. For this reason it is added to the ADDITIONAL_MAKE_CLEAN_FILES property.
Note: If generating files as part of the project CMakeLists.txt file, not a component CMakeLists.txt, then use
build property PROJECT_DIR instead of ${COMPONENT_DIR} and ${PROJECT_NAME}.elf instead of
${COMPONENT_LIB}.)
If a a source file from another component included logo.h, then add_dependencies would need to be called
to add a dependency between the two components, to ensure that the component source files were always compiled
in the correct order.
Embedding Binary Data
Sometimes you have a file with some binary or text data that you d like to make available to your component - but
you don t want to reformat the file as C source.
You can specify argument EMBED_FILES in the component registration, giving space-delimited names of the files
to embed:
EMBED_FILES server_root_cert.der)
Or if the file is a string, you can use the variable EMBED_TXTFILES. This will embed the contents of the text file
as a null-terminated string:
EMBED_TXTFILES server_root_cert.pem)
The file s contents will be added to the .rodata section in flash, and are available via symbol names as follows:
extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_

,→pem_start");
extern const uint8_t server_root_cert_pem_end[] asm("_binary_server_root_cert_

,→pem_end");
The names are generated from the full name of the file, as given in EMBED_FILES. Characters /, ., etc. are replaced
with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary
files.
To embed a file into a project, rather than a component, you can call the function target_add_binary_data
like this:
target_add_binary_data(myproject.elf "main/data.bin" TEXT)
Place this line after the project() line in your project CMakeLists.txt file. Replace myproject.elf with your
project name. The final argument can be TEXT to embed a null-terminated string, or BINARY to embed the content
as-is.
For an example of using this technique, see the main component of the file_serving example proto-
cols/http_server/file_serving/main/CMakeLists.txt - two files are loaded at build time and linked into the firmware.
It is also possible embed a generated file:

add_custom_command(OUTPUT my_processed_file.bin
COMMAND my_process_file_cmd my_unprocessed_file.bin)
target_add_binary_data(my_target "my_processed_file.bin" BINARY)
In the example above, my_processed_file.bin is generated from my_unprocessed_file.bin through

some command my_process_file_cmd, then embedded into the target.
To specify a dependence on a target, use the DEPENDS argument:
add_custom_target(my_process COMMAND ...)

target_add_binary_data(my_target "my_embed_file.bin" BINARY DEPENDS my_process)
The DEPENDS argument to target_add_binary_data ensures that the target executes first.
Code and Data Placements
ESP-IDF has a feature called linker script generation that enables components to define where its code and data will
be placed in memory through linker fragment files. These files are processed by the build system, and is used to
augment the linker script used for linking app binary. See Linker Script Generation for a quick start guide as well as
a detailed discussion of the mechanism.
Fully Overriding The Component Build Process
Obviously, there are cases where all these recipes are insufficient for a certain component, for example when the
component is basically a wrapper around another third-party component not originally intended to be compiled under
this build system. In that case, it s possible to forego the ESP-IDF build system entirely by using a CMake feature
called ExternalProject. Example component CMakeLists:
# External build process for quirc, runs in source dir and

# produces libquirc.a
externalproject_add(quirc_build
PREFIX ${COMPONENT_DIR}
SOURCE_DIR ${COMPONENT_DIR}/quirc
CONFIGURE_COMMAND ""
BUILD_IN_SOURCE 1
BUILD_COMMAND make CC=${CMAKE_C_COMPILER} libquirc.a
INSTALL_COMMAND ""
)
# Add libquirc.a to the build process

add_library(quirc STATIC IMPORTED GLOBAL)
add_dependencies(quirc quirc_build)
set_target_properties(quirc PROPERTIES IMPORTED_LOCATION

${COMPONENT_DIR}/quirc/libquirc.a)
set_target_properties(quirc PROPERTIES INTERFACE_INCLUDE_DIRECTORIES
${COMPONENT_DIR}/quirc/lib)
set_directory_properties( PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES

"${COMPONENT_DIR}/quirc/libquirc.a")
(The above CMakeLists.txt can be used to create a component named quirc that builds the quirc project using its
own Makefile.)
• externalproject_add defines an external build system.
– SOURCE_DIR, CONFIGURE_COMMAND, BUILD_COMMAND and INSTALL_COMMAND should al-
ways be set. CONFIGURE_COMMAND can be set to an empty string if the build system has no configure
step. INSTALL_COMMAND will generally be empty for ESP-IDF builds.
– Setting BUILD_IN_SOURCE means the build directory is the same as the source directory. Otherwise
you can set BUILD_DIR.

– Consult the ExternalProject documentation for more details about externalproject_add()

• The second set of commands adds a library target, which points to the imported library file built by the
external system. Some properties need to be set in order to add include directories and tell CMake where this
file is.
• Finally, the generated library is added to ADDITIONAL_MAKE_CLEAN_FILES. This means make
clean will delete this library. (Note that the other object files from the build won t be deleted.)
Note: When using an external build process with PSRAM, remember to add -mfix-esp32-psram-cache-
issue to the C compiler arguments. See CONFIG_SPIRAM_CACHE_WORKAROUND for details of this flag.
ExternalProject dependencies, clean builds CMake has some unusual behaviour around external project builds:
• ADDITIONAL_MAKE_CLEAN_FILES only works when make is used as the build system. If Ninja or
an IDE build system is used, it won t delete these files when cleaning.
• However, the ExternalProject configure & build commands will always be re-run after a clean is run.
• Therefore, there are two alternative recommended ways to configure the external build command:
1. Have the external BUILD_COMMAND run a full clean compile of all sources. The build command will
be run if any of the dependencies passed to externalproject_add with DEPENDS have changed,
or if this is a clean build (ie any of idf.py clean, ninja clean, or make clean was run.)
2. Have the external BUILD_COMMAND be an incremental build command. Pass the parameter
BUILD_ALWAYS 1 to externalproject_add. This means the external project will be built
each time a build is run, regardless of dependencies. This is only recommended if the external project
has correct incremental build behaviour, and doesn t take too long to run.
The best of these approaches for building an external project will depend on the project itself, its build system, and
whether you anticipate needing to frequently recompile the project.
4.5.13 Custom sdkconfig defaults
For example projects or other projects where you don t want to specify a full sdkconfig configuration, but you do
want to override some key values from the ESP-IDF defaults, it is possible to create a file sdkconfig.defaults
in the project directory. This file will be used when creating a new config from scratch, or when any new config value
hasn t yet been set in the sdkconfig file.
To override the name of this file or to specify multiple files, set the SDKCONFIG_DEFAULTS environment variable
or set SDKCONFIG_DEFAULTS in top-level CMakeLists.txt. If specifying multiple files, use semicolon as the list
separator. File names not specified as full paths are resolved relative to current project.
Some of the IDF examples include a sdkconfig.ci file. This is part of the continuous integration (CI) test
framework and is ignored by the normal build process.
Target-dependent sdkconfig defaults
In addition to sdkconfig.defaults file, build system will also load defaults from sdkconfig.defaults.
TARGET_NAME file, where TARGET_NAME is the value of IDF_TARGET. For example, for esp32 target, default
settings will be taken from sdkconfig.defaults first, and then from sdkconfig.defaults.esp32.
If SDKCONFIG_DEFAULTS is used to override the name of defaults file/files, the name of target-specific defaults
file will be derived from SDKCONFIG_DEFAULTS value/values using the rule above.
4.5.14 Flash arguments
There are some scenarios that we want to flash the target board without IDF. For this case we want to save the built
binaries, esptool.py and esptool write_flash arguments. It s simple to write a script to save binaries and esptool.py.

After running a project build, the build directory contains binary output files (.bin files) for the project and also the
following flashing data files:
• flash_project_args contains arguments to flash the entire project (app, bootloader, partition table,
PHY data if this is configured).
• flash_app_args contains arguments to flash only the app.
• flash_bootloader_args contains arguments to flash only the bootloader.
You can pass any of these flasher argument files to esptool.py as follows:
python esptool.py --chip esp32 write_flash @build/flash_project_args
Alternatively, it is possible to manually copy the parameters from the argument file and pass them on the command
line.
The build directory also contains a generated file flasher_args.json which contains project flash information,
in JSON format. This file is used by idf.py and can also be used by other tools which need information about the
project build.
4.5.15 Building the Bootloader
The bootloader is built by default as part of idf.py build, or can be built standalone via idf.py boot-
loader.
The bootloader is a special subproject inside /components/bootloader/subproject. It has its own project CMake-
Lists.txt file and builds separate .ELF and .BIN files to the main project. However it shares its configuration and build
directory with the main project.
The subproject is inserted as an external project from the top-level project, by the file /compo-
nents/bootloader/project_include.cmake. The main build process runs CMake for the subproject, which includes
discovering components (a subset of the main components) and generating a bootloader-specific config (derived
from the main sdkconfig).
4.5.16 Selecting the Target
ESP-IDF supports multiple targets (chips). The identifiers used for each chip are as follows:
• esp32 for ESP32-D0WD, ESP32-D2WD, ESP32-S0WD (ESP-SOLO), ESP32-U4WDH, ESP32-PICO-
D4
• esp32s2 for ESP32-S2
• esp32c3 for ESP32-C3
To select the target before building the project, use idf.py set-target <target> command, for example:
idf.py set-target esp32s2
Important: idf.py set-target will clear the build directory and re-generate the sdkconfig file from
scratch. The old sdkconfig file will be saved as sdkconfig.old.
Note: The behavior of idf.py set-target command is equivalent to:

1. clearing the build directory (idf.py fullclean)
2. removing the sdkconfig file (mv sdkconfig sdkconfig.old)
3. configuring the project with the new target (idf.py -DIDF_TARGET=esp32 reconfigure)
It is also possible to pass the desired IDF_TARGET as an environment variable (e.g. export
IDF_TARGET=esp32s2) or as a CMake variable (e.g. -DIDF_TARGET=esp32s2 argument to CMake or
idf.py). Setting the environment variable is a convenient method if you mostly work with one type of the chip.

To specify the _default_ value of IDF_TARGET for a given project, add CONFIG_IDF_TARGET value to
sdkconfig.defaults. For example, CONFIG_IDF_TARGET="esp32s2". This value will be used if
IDF_TARGET is not specified by other method: using an environment variable, CMake variable, or idf.py set-
target command.
If the target has not been set by any of these methods, the build system will default to esp32 target.
4.5.17 Writing Pure CMake Components
The ESP-IDF build system wraps CMake with the concept of components , and helper functions to automatically
integrate these components into a project build.
However, underneath the concept of components is a full CMake build system. It is also possible to make a
component which is pure CMake.
Here is an example minimal pure CMake component CMakeLists file for a component named json:
add_library(json STATIC
cJSON/cJSON.c
cJSON/cJSON_Utils.c)
target_include_directories(json PUBLIC cJSON)
• This is actually an equivalent declaration to the IDF json component /components/json/CMakeLists.txt.

• This file is quite simple as there are not a lot of source files. For components with a large number of files, the
globbing behaviour of ESP-IDF s component logic can make the component CMakeLists style simpler.)
• Any time a component adds a library target with the component name, the ESP-IDF build system will auto-
matically add this to the build, expose public include directories, etc. If a component wants to add a library
target with a different name, dependencies will need to be added manually via CMake commands.
4.5.18 Using Third-Party CMake Projects with Components
CMake is used for a lot of open-source C and C++ projects code that users can tap into for their applications.
One of the benefits of having a CMake build system is the ability to import these third-party projects, sometimes
even without modification! This allows for users to be able to get functionality that may not yet be provided by a
component, or use another library for the same functionality.
Importing a library might look like this for a hypothetical library foo to be used in the main component:
# Register the component

idf_component_register(...)
# Set values of hypothetical variables that control the build of `foo`

set(FOO_BUILD_STATIC OFF)
set(FOO_BUILD_TESTS OFF)
# Create and import the library targets

add_subdirectory(foo)
# Publicly link `foo` to `main` component

target_link_libraries(main PUBLIC foo)
For an actual example, take a look at build_system/cmake/import_lib. Take note that what needs to be done in order
to import the library may vary. It is recommended to read up on the library s documentation for instructions on
how to import it from other projects. Studying the library s CMakeLists.txt and build structure can also be helpful.
It is also possible to wrap a third-party library to be used as a component in this manner. For example, the mbedtls
component is a wrapper for Espressif s fork of mbedtls. See its component CMakeLists.txt .
The CMake variable ESP_PLATFORM is set to 1 whenever the ESP-IDF build system is being used. Tests such as
if (ESP_PLATFORM) can be used in generic CMake code if special IDF-specific logic is required.

Using ESP-IDF components from external libraries
The above example assumes that the external library foo (or tinyxml in the case of the import_lib example)
doesn t need to use any ESP-IDF APIs apart from common APIs such as libc, libstdc++, etc. If the external library
needs to use APIs provided by other ESP-IDF components, this needs to be specified in the external CMakeLists.txt
file by adding a dependency on the library target idf::<componentname>.
For example, in the foo/CMakeLists.txt file:
add_library(foo bar.c fizz.cpp buzz.cpp)
if(ESP_PLATFORM)
# On ESP-IDF, bar.c needs to include esp_spi_flash.h from the spi_flash component
target_link_libraries(foo PRIVATE idf::spi_flash)
endif()
4.5.19 Using Prebuilt Libraries with Components
Another possibility is that you have a prebuilt static library (.a file), built by some other build process.
The ESP-IDF build system provides a utility function add_prebuilt_library for users to be able to easily
import and use prebuilt libraries:
add_prebuilt_library(target_name lib_path [REQUIRES req1 req2 ...] [PRIV_REQUIRES␣
,→req1 req2 ...])
where:
• target_name- name that can be used to reference the imported library, such as when linking to other targets
• lib_path- path to prebuilt library; may be an absolute or relative path to the component directory
Optional arguments REQUIRES and PRIV_REQUIRES specify dependency on other components. These have the
same meaning as the arguments for idf_component_register.
Take note that the prebuilt library must have been compiled for the same target as the consuming project. Configu-
ration relevant to the prebuilt library must also match. If not paid attention to, these two factors may contribute to
subtle bugs in the app.
For an example, take a look at build_system/cmake/import_prebuilt.
4.5.20 Using ESP-IDF in Custom CMake Projects
ESP-IDF provides a template CMake project for easily creating an application. However, in some instances the user
might already have an existing CMake project or may want to create a custom one. In these cases it is desirable to be
able to consume IDF components as libraries to be linked to the user s targets (libraries/ executables).
It is possible to do so by using the build system APIs provided by tools/cmake/idf.cmake. For example:
project(my_custom_app C)
# Include CMake file that provides ESP-IDF CMake build system APIs.
include($ENV{IDF_PATH}/tools/cmake/idf.cmake)
# Include ESP-IDF components in the build, may be thought as an equivalent of

# add_subdirectory() but with some additional processing and magic for ESP-IDF␣
,→build
# specific build processes.

idf_build_process(esp32)
# Create the project executable and plainly link the newlib component to it using


# its alias, idf::newlib.
add_executable(${CMAKE_PROJECT_NAME}.elf main.c)
target_link_libraries(${CMAKE_PROJECT_NAME}.elf idf::newlib)
# Let the build system know what the project executable is to attach more targets,␣
,→dependencies, etc.
idf_build_executable(${CMAKE_PROJECT_NAME}.elf)
The example in build_system/cmake/idf_as_lib demonstrates the creation of an application equivalent to hello world
application using a custom CMake project.
Note: The IDF build system can only set compiler flags for source files that it builds. When an external CMake-
Lists.txt file is used and PSRAM is enabled, remember to add -mfix-esp32-psram-cache-issue to the C
compiler arguments. See CONFIG_SPIRAM_CACHE_WORKAROUND for details of this flag.
4.5.21 ESP-IDF CMake Build System API
idf-build-commands
idf_build_get_property(var property [GENERATOR_EXPRESSION])
Retrieve a build property property and store it in var accessible from the current scope. Specifying GENERA-
TOR_EXPRESSION will retrieve the generator expression string for that property, instead of the actual value, which
can be used with CMake commands that support generator expressions.
idf_build_set_property(property val [APPEND])
Set a build property property with value val. Specifying APPEND will append the specified value to the current value
of the property. If the property does not previously exist or it is currently empty, the specified value becomes the first
element/member instead.
idf_build_component(component_dir)
Present a directory component_dir that contains a component to the build system. Relative paths are converted to ab-
solute paths with respect to current directory. All calls to this command must be performed before idf_build_process.
This command does not guarantee that the component will be processed during build (see the COMPONENTS argu-
ment description for idf_build_process)
idf_build_process(target
[PROJECT_DIR project_dir]
[PROJECT_VER project_ver]
[PROJECT_NAME project_name]
[SDKCONFIG sdkconfig]
[SDKCONFIG_DEFAULTS sdkconfig_defaults]
[BUILD_DIR build_dir]
[COMPONENTS component1 component2 ...])
Performs the bulk of the behind-the-scenes magic for including ESP-IDF components such as component configu-
ration, libraries creation, dependency expansion and resolution. Among these functions, perhaps the most important
from a user s perspective is the libraries creation by calling each component s idf_component_register.
This command creates the libraries for each component, which are accessible using aliases in the form
idf::component_name. These aliases can be used to link the components to the user s own targets, either libraries
or executables.
The call requires the target chip to be specified with target argument. Optional arguments for the call include:
• PROJECT_DIR - directory of the project; defaults to CMAKE_SOURCE_DIR

• PROJECT_NAME - name of the project; defaults to CMAKE_PROJECT_NAME

• PROJECT_VER - version/revision of the project; defaults to 1
• SDKCONFIG - output path of generated sdkconfig file; defaults to PROJECT_DIR/sdkconfig or
CMAKE_SOURCE_DIR/sdkconfig depending if PROJECT_DIR is set
• SDKCONFIG_DEFAULTS - list of files containing default config to use in the build (list must contain full
paths); defaults to empty. For each value filename in the list, the config from file filename.target, if it exists, is
also loaded.
• BUILD_DIR - directory to place ESP-IDF build-related artifacts, such as generated binaries, text files, com-
ponents; defaults to CMAKE_BINARY_DIR
• COMPONENTS - select components to process among the components known by the build system (added via
idf_build_component). This argument is used to trim the build. Other components are automatically added if
they are required in the dependency chain, i.e. the public and private requirements of the components in this
list are automatically added, and in turn the public and private requirements of those requirements, so on and
so forth. If not specified, all components known to the build system are processed.
idf_build_executable(executable)
Specify the executable executable for ESP-IDF build. This attaches additional targets such as dependencies related
to flashing, generating additional binary files, etc. Should be called after idf_build_process.
idf_build_get_config(var config [GENERATOR_EXPRESSION])
Get the value of the specified config. Much like build properties, specifying GENERATOR_EXPRESSION will retrieve
the generator expression string for that config, instead of the actual value, which can be used with CMake commands
that support generator expressions. Actual config values are only known after call to idf_build_process,
however.
idf-build-properties
These are properties that describe the build. Values of build properties can be retrieved by using the build command
idf_build_get_property. For example, to get the Python interpreter used for the build:
idf_build_get_property(python PYTHON)
message(STATUS "The Python intepreter is: ${python}")
• BUILD_DIR - build directory; set from idf_build_process BUILD_DIR argument

• BUILD_COMPONENTS - list of components included in the build; set by idf_build_process
• BUILD_COMPONENT_ALIASES - list of library alias of components included in the build; set by
idf_build_process
• C_COMPILE_OPTIONS - compile options applied to all components C source files
• COMPILE_OPTIONS - compile options applied to all components source files, regardless of it being C or
C++
• COMPILE_DEFINITIONS - compile definitions applied to all component source files
• CXX_COMPILE_OPTIONS - compile options applied to all components C++ source files
• EXECUTABLE - project executable; set by call to idf_build_executable
• EXECUTABLE_NAME - name of project executable without extension; set by call to
idf_build_executable
• EXECUTABLE_DIR - path containing the output executable
• IDF_PATH - ESP-IDF path; set from IDF_PATH environment variable, if not, inferred from the location of
idf.cmake
• IDF_TARGET - target chip for the build; set from the required target argument for idf_build_process
• IDF_VER - ESP-IDF version; set from either a version file or the Git revision of the IDF_PATH repository
• INCLUDE_DIRECTORIES - include directories for all component source files
• KCONFIGS - list of Kconfig files found in components in build; set by idf_build_process
• KCONFIG_PROJBUILDS - list of Kconfig.projbuild files found in components in build; set by
idf_build_process
• PROJECT_NAME - name of the project; set from idf_build_process PROJECT_NAME argument
• PROJECT_DIR - directory of the project; set from idf_build_process PROJECT_DIR argument

• PROJECT_VER - version of the project; set from idf_build_process PROJECT_VER argument

• PYTHON - Python interpreter used for the build; set from PYTHON environment variable if available, if not
python is used
• SDKCONFIG - full path to output config file; set from idf_build_process SDKCONFIG argument
• SDKCONFIG_DEFAULTS - list of files containing default config to use in the build; set from
idf_build_process SDKCONFIG_DEFAULTS argument
• SDKCONFIG_HEADER - full path to C/C++ header file containing component configuration; set by
idf_build_process
• SDKCONFIG_CMAKE - full path to CMake file containing component configuration; set by
idf_build_process
• SDKCONFIG_JSON - full path to JSON file containing component configuration; set by
idf_build_process
• SDKCONFIG_JSON_MENUS - full path to JSON file containing config menus; set by
idf_build_process
idf-component-commands
idf_component_get_property(var component property [GENERATOR_EXPRESSION])
Retrieve a specified component s component property, property and store it in var accessible from the current scope.
Specifying GENERATOR_EXPRESSION will retrieve the generator expression string for that property, instead of the
actual value, which can be used with CMake commands that support generator expressions.
idf_component_set_property(component property val [APPEND])
Set a specified component s component property, property with value val. Specifying APPEND will append the
specified value to the current value of the property. If the property does not previously exist or it is currently empty,
the specified value becomes the first element/member instead.
idf_component_register([[SRCS src1 src2 ...] | [[SRC_DIRS dir1 dir2 ...] [EXCLUDE_

,→SRCS src1 src2 ...]]
[INCLUDE_DIRS dir1 dir2 ...]

[PRIV_INCLUDE_DIRS dir1 dir2 ...]
[REQUIRES component1 component2 ...]
[PRIV_REQUIRES component1 component2 ...]
[LDFRAGMENTS ldfragment1 ldfragment2 ...]
[REQUIRED_IDF_TARGETS target1 target2 ...]
[EMBED_FILES file1 file2 ...]
[EMBED_TXTFILES file1 file2 ...]
[KCONFIG kconfig]
[KCONFIG_PROJBUILD kconfig_projbuild])
Register a component to the build system. Much like the project() CMake command, this should be called
from the component s CMakeLists.txt directly (not through a function or macro) and is recommended to be
called before any other command. Here are some guidelines on what commands can not be called before
• commands that are not valid in CMake script mode
• custom commands defined in project_include.cmake
• build system API commands except idf_build_get_property; although consider whether the property
may not have been set yet
Commands that set and operate on variables are generally okay to call before idf_component_register.
The arguments for idf_component_register include:
• SRCS - component source files used for creating a static library for the component; if not specified, component
is a treated as a config-only component and an interface library is created instead.
• SRC_DIRS, EXCLUDE_SRCS - used to glob source files (.c, .cpp, .S) by specifying directories, instead of
specifying source files manually via SRCS. Note that this is subject to the limitations of globbing in CMake.
Source files specified in EXCLUDE_SRCS are removed from the globbed files.

• INCLUDE_DIRS - paths, relative to the component directory, which will be added to the include search path
for all other components which require the current component
• PRIV_INCLUDE_DIRS - directory paths, must be relative to the component directory, which will be added
to the include search path for this component s source files only
• REQUIRES - public component requirements for the component
• PRIV_REQUIRES - private component requirements for the component; ignored on config-only components
• LDFRAGMENTS - component linker fragment files
• REQUIRED_IDF_TARGETS - specify the only target the component supports
• KCONFIG - override the default Kconfig file
• KCONFIG_PROJBUILD - override the default Kconfig.projbuild file
The following are used for embedding data into the component, and is considered as source files when determining if
a component is config-only. This means that even if the component does not specify source files, a static library is
still created internally for the component if it specifies either:
• EMBED_FILES - binary files to be embedded in the component
• EMBED_TXTFILES - text files to be embedded in the component
idf-component-properties
These are properties that describe a component. Values of component properties can be retrieved by using the build
command idf_component_get_property. For example, to get the directory of the freertos component:
idf_component_get_property(dir freertos COMPONENT_DIR)

message(STATUS "The 'freertos' component directory is: ${dir}")
• COMPONENT_ALIAS - alias for COMPONENT_LIB used for linking the component to external targets;
set by idf_build_component and alias library itself is created by idf_component_register
• COMPONENT_DIR - component directory; set by idf_build_component
• COMPONENT_OVERRIDEN_DIR - contains the directory of the original component if this component over-
rides another component
• COMPONENT_LIB - name for created component static/interface library; set by
idf_build_component and library itself is created by idf_component_register
• COMPONENT_NAME - name of the component; set by idf_build_component based on the compo-
nent directory name
• COMPONENT_TYPE - type of the component, whether LIBRARY or CONFIG_ONLY. A component is of
type LIBRARY if it specifies source files or embeds a file
• EMBED_FILES - list of files to embed in component; set from idf_component_register EM-
BED_FILES argument
• EMBED_TXTFILES - list of text files to embed in component; set from idf_component_register
EMBED_TXTFILES argument
• INCLUDE_DIRS - list of component include directories; set from idf_component_register IN-
CLUDE_DIRS argument
• KCONFIG - component Kconfig file; set by idf_build_component
• KCONFIG_PROJBUILD - component Kconfig.projbuild; set by idf_build_component
• LDFRAGMENTS - list of component linker fragment files; set from idf_component_register LD-
FRAGMENTS argument
• PRIV_INCLUDE_DIRS - list of component private include directories; set from
idf_component_register PRIV_INCLUDE_DIRS on components of type LIBRARY
• PRIV_REQUIRES - list of private component dependentices; set from idf_component_register
PRIV_REQUIRES argument
• REQUIRED_IDF_TARGETS - list of targets the component supports; set from
idf_component_register EMBED_TXTFILES argument
• REQUIRES - list of public component dependencies; set from idf_component_register REQUIRES
argument
• SRCS - list of component source files; set from SRCS or SRC_DIRS/EXCLUDE_SRCS argument of
idf_component_register

4.5.22 File Globbing & Incremental Builds
The preferred way to include source files in an ESP-IDF component is to list them manually via SRCS argument to
idf_component_register(SRCS library/a.c library/b.c platform/platform.c

...)
This preference reflects the CMake best practice of manually listing source files. This could, however, be inconvenient
when there are lots of source files to add to the build. The ESP-IDF build system provides an alternative way for
specifying source files using SRC_DIRS:
idf_component_register(SRC_DIRS library platform

...)
This uses globbing behind the scenes to find source files in the specified directories. Be aware, however, that if a new
source file is added and this method is used, then CMake won t know to automatically re-run and this file won t
be added to the build.
The trade-off is acceptable when you re adding the file yourself, because you can trigger a clean build or run idf.
py reconfigure to manually re-run CMake. However, the problem gets harder when you share your project
with others who may check out a new version using a source control tool like Git
For components which are part of ESP-IDF, we use a third party Git CMake integration module
(/tools/cmake/third_party/GetGitRevisionDescription.cmake) which automatically re-runs CMake any time the
repository commit changes. This means if you check out a new ESP-IDF version, CMake will automatically re-
run.
For project components (not part of ESP-IDF), there are a few different options:
• If keeping your project file in Git, ESP-IDF will automatically track the Git revision and re-run CMake if the
revision changes.
• If some components are kept in a third git repository (not the project repository or ESP-IDF repository), you
can add a call to the git_describe function in a component CMakeLists file in order to automatically
trigger re-runs of CMake when the Git revision changes.
• If not using Git, remember to manually run idf.py reconfigure whenever a source file may change.
• To avoid this problem entirely, use SRCS argument to idf_component_register to list all source files
in project components.
The best option will depend on your particular project and its users.
4.5.23 Build System Metadata
For integration into IDEs and other build systems, when CMake runs the build process generates a number of metadata
files in the build/ directory. To regenerate these files, run cmake or idf.py reconfigure (or any other
idf.py build command).
• compile_commands.json is a standard format JSON file which describes every source file which is
compiled in the project. A CMake feature generates this file, and many IDEs know how to parse it.
• project_description.json contains some general information about the ESP-IDF project, configured
paths, etc.
• flasher_args.json contains esptool.py arguments to flash the project s binary files. There are also
flash_*_args files which can be used directly with esptool.py. See Flash arguments.
• CMakeCache.txt is the CMake cache file which contains other information about the CMake process,
toolchain, etc.
• config/sdkconfig.json is a JSON-formatted version of the project configuration values.
• config/kconfig_menus.json is a JSON-formatted version of the menus shown in menuconfig, for
use in external IDE UIs.

JSON Configuration Server
A tool called confserver.py is provided to allow IDEs to easily integrate with the configuration system logic.
confserver.py is designed to run in the background and interact with a calling process by reading and writing
JSON over process stdin & stdout.
You can run confserver.py from a project via idf.py confserver or ninja confserver, or a similar
target triggered from a different build generator.
For more information about confserver.py, see tools/kconfig_new/README.md.
4.5.24 Build System Internals
Build Scripts
The listfiles for the ESP-IDF build system reside in /tools/cmake. The modules which implement core build system
functionality are as follows:
• build.cmake - Build related commands i.e. build initialization, retrieving/setting build properties,
build processing.
• component.cmake - Component related commands i.e. adding components, retrieving/setting
component properties, registering components.
• kconfig.cmake - Generation of configuration files (sdkconfig, sdkconfig.h, sdkconfig.cmake, etc.)
from Kconfig files.
• ldgen.cmake - Generation of final linker script from linker fragment files.
• target.cmake - Setting build target and toolchain file.
• utilities.cmake - Miscellaneous helper commands.
Aside from these files, there are two other important CMake scripts in /tools/cmake:
• idf.cmake - Sets up the build and includes the core modules listed above. Included in CMake
projects in order to access ESP-IDF build system functionality.
• project.cmake - Includes idf.cmake and provides a custom project() command that takes
care of all the heavy lifting of building an executable. Included in the top-level CMakeLists.txt of
standard ESP-IDF projects.
The rest of the files in /tools/cmake are support or third-party scripts used in the build process.
Build Process
This section describes the standard ESP-IDF application build process. The build process can be broken down roughly
into four phases:
Fig. 3: ESP-IDF Build System Process
Initialization This phase sets up necessary parameters for the build.

• Upon inclusion of idf.cmake in project.cmake, the following steps are performed:
– Set IDF_PATH from environment variable or inferred from path to project.cmake
included in the top-level CMakeLists.txt.
– Add /tools/cmake to CMAKE_MODULE_PATH and include core modules plus the various
helper/third-party scripts.

– Set build tools/executables such as default Python interpreter.

– Get ESP-IDF git revision and store as IDF_VER.
– Set global build specifications i.e. compile options, compile definitions, include directo-
ries for all components in the build.
– Add components in components to the build.
• The initial part of the custom project() command performs the following steps:
– Set IDF_TARGET from environment variable or CMake cache and the corresponding
CMAKE_TOOLCHAIN_FILE to be used.
– Add components in EXTRA_COMPONENTS_DIRS to the build.
– Prepare arguments for calling command idf_build_process() from vari-
ables such as COMPONENTS/EXCLUDE_COMPONENTS, SDKCONFIG, SDKCON-
FIG_DEFAULTS.
The call to idf_build_process() command marks the end of this phase.
Enumeration
This phase builds a final list of components to be processed in the build, and is performed in the first
half of idf_build_process().
• Retrieve each component s public and private requirements. A child process is cre-
ated which executes each component s CMakeLists.txt in script mode. The values
of idf_component_register REQUIRES and PRIV_REQUIRES argument is re-
turned to the parent build process. This is called early expansion. The variable
CMAKE_BUILD_EARLY_EXPANSION is defined during this step.
• Recursively include components based on public and private requirements.
Processing
This phase processes the components in the build, and is the second half of idf_build_process().
• Load project configuration from sdkconfig file and generate an sdkconfig.cmake and sdkconfig.h
header. These define configuration variables/macros that are accessible from the build scripts and
C/C++ source/header files, respectively.
• Include each component s project_include.cmake.
• Add each component as a subdirectory, processing its CMakeLists.txt. The component CMake-
Lists.txt calls the registration command, idf_component_register which adds source files,
include directories, creates component library, links dependencies, etc.
Finalization
This phase is everything after idf_build_process().
• Create executable and link the component libraries to it.
• Generate project metadata files such as project_description.json and display relevant information
about the project built.
Browse /tools/cmake/project.cmake for more details.
4.5.25 Migrating from ESP-IDF GNU Make System
Some aspects of the CMake-based ESP-IDF build system are very similar to the older GNU Make-based system. The
developer needs to provide values the include directories, source files etc. There is a syntactical difference, however,
as the developer needs to pass these as arguments to the registration command, idf_component_register.
Automatic Conversion Tool
An automatic project conversion tool is available in tools/cmake/convert_to_cmake.py in ESP-IDF v4.x releases. The
script was removed in v5.0 because of its make build system dependency.

No Longer Available in CMake
Some features are significantly different or removed in the CMake-based system. The following variables no longer
exist in the CMake-based build system:
• COMPONENT_BUILD_DIR: Use CMAKE_CURRENT_BINARY_DIR instead.
• COMPONENT_LIBRARY: Defaulted to $(COMPONENT_NAME).a, but the library name could be overriden
by the component. The name of the component library can no longer be overriden by the component.
• CC, LD, AR, OBJCOPY: Full paths to each tool from the gcc xtensa cross-toolchain. Use
CMAKE_C_COMPILER, CMAKE_C_LINK_EXECUTABLE, CMAKE_OBJCOPY, etc instead. Full list here.
• HOSTCC, HOSTLD, HOSTAR: Full names of each tool from the host native toolchain. These are no longer
provided, external projects should detect any required host toolchain manually.
• COMPONENT_ADD_LDFLAGS: Used to override linker flags. Use the CMake target_link_libraries command
instead.
• COMPONENT_ADD_LINKER_DEPS: List of files that linking should depend on. target_link_libraries will
usually infer these dependencies automatically. For linker scripts, use the provided custom CMake function
target_linker_scripts.
• COMPONENT_SUBMODULES: No longer used, the build system will automatically enumerate all submodules
in the ESP-IDF repository.
• COMPONENT_EXTRA_INCLUDES: Used to be an alternative to COMPONENT_PRIV_INCLUDEDIRS for
absolute paths. Use PRIV_INCLUDE_DIRS argument to idf_component_register for all cases now
(can be relative or absolute).
• COMPONENT_OBJS: Previously, component sources could be specified as a list of object files. Now they can
be specified as a list of source files via SRCS argument to idf_component_register.
• COMPONENT_OBJEXCLUDE: Has been replaced with EXCLUDE_SRCS argument to
idf_component_register. Specify source files (as absolute paths or relative to component di-
rectory), instead.
• COMPONENT_EXTRA_CLEAN: Set property ADDITIONAL_MAKE_CLEAN_FILES instead but note
CMake has some restrictions around this functionality.
• COMPONENT_OWNBUILDTARGET & COMPONENT_OWNCLEANTARGET: Use CMake ExternalProject in-
stead. See Fully Overriding The Component Build Process for full details.
• COMPONENT_CONFIG_ONLY: Call idf_component_register without any arguments instead. See
Configuration-Only Components.
• CFLAGS, CPPFLAGS, CXXFLAGS: Use equivalent CMake commands instead. See Controlling Component
Compilation.
No Default Values
Unlike in the legacy Make-based build system, the following have no default values:
• Source directories (COMPONENT_SRCDIRS variable in Make, SRC_DIRS argument to
idf_component_register in CMake)
• Include directories (COMPONENT_ADD_INCLUDEDIRS variable in Make, INCLUDE_DIRS argument to
idf_component_register in CMake)
No Longer Necessary
• In the legacy Make-based build system, it is required to also set COMPONENT_SRCDIRS if COM-
PONENT_SRCS is set. In CMake, the equivalent is not necessary i.e. specifying SRC_DIRS to
idf_component_register if SRCS is also specified (in fact, SRCS is ignored if SRC_DIRS is speci-
fied).
Flashing from make
make flash and similar targets still work to build and flash. However, project sdkconfig no longer specifies
serial port and baud rate. Environment variables can be used to override these. See Flashing with ninja or make for
more details.

4.6 Deep Sleep Wake Stubs

ESP32 supports running a deep sleep wake stub when coming out of deep sleep. This function runs immediately
as soon as the chip wakes up - before any normal initialisation, bootloader, or ESP-IDF code has run. After the wake
stub runs, the SoC can go back to sleep or continue to start ESP-IDF normally.
Deep sleep wake stub code is loaded into RTC Fast Memory and any data which it uses must also be loaded into
RTC memory. RTC memory regions hold their contents during deep sleep.
4.6.1 Rules for Wake Stubs
Wake stub code must be carefully written:

• As the SoC has freshly woken from sleep, most of the peripherals are in reset states. The SPI flash is unmapped.
• The wake stub code can only call functions implemented in ROM or loaded into RTC Fast Memory (see below.)
• The wake stub code can only access data loaded in RTC memory. All other RAM will be unintiailised and
have random contents. The wake stub can use other RAM for temporary storage, but the contents will be
overwritten when the SoC goes back to sleep or starts ESP-IDF.
• RTC memory must include any read-only data (.rodata) used by the stub.
• Data in RTC memory is initialised whenever the SoC restarts, except when waking from deep sleep. When
waking from deep sleep, the values which were present before going to sleep are kept.
• Wake stub code is a part of the main esp-idf app. During normal running of esp-idf, functions can call the
wake stub functions or access RTC memory. It is as if these were regular parts of the app.
4.6.2 Implementing A Stub
The wake stub in esp-idf is called esp_wake_deep_sleep(). This function runs whenever the SoC wakes from
deep sleep. There is a default version of this function provided in esp-idf, but the default function is weak-linked so
if your app contains a function named esp_wake_deep_sleep() then this will override the default.
If supplying a custom wake stub, the first thing it does should be to call esp_default_wake_deep_sleep().
It is not necessary to implement esp_wake_deep_sleep() in your app in order to use deep sleep. It is only
necessary if you want to have special behaviour immediately on wake.
If you want to swap between different deep sleep stubs at runtime, it is also possible to do this by calling
the esp_set_deep_sleep_wake_stub() function. This is not necessary if you only use the default
esp_wake_deep_sleep() function.
All of these functions are declared in the esp_sleep.h header under components/esp32.
4.6.3 Loading Code Into RTC Memory
Wake stub code must be resident in RTC Fast Memory. This can be done in one of two ways.
The first way is to use the RTC_IRAM_ATTR attribute to place a function into RTC memory:
void RTC_IRAM_ATTR esp_wake_deep_sleep(void) {

esp_default_wake_deep_sleep();
// Add additional functionality here
}
The second way is to place the function into any source file whose name starts with rtc_wake_stub. Files names
rtc_wake_stub* have their contents automatically put into RTC memory by the linker.
The first way is simpler for very short and simple code, or for source files where you want to mix normal and
RTC code. The second way is simpler when you want to write longer pieces of code for RTC memory.

4.6.4 Loading Data Into RTC Memory
Data used by stub code must be resident in RTC memory.

The data can be placed in RTC Fast memory or in RTC Slow memory which is also used by the ULP.
Specifying this data can be done in one of two ways:
The first way is to use the RTC_DATA_ATTR and RTC_RODATA_ATTR to specify any data (writeable or read-only,
respectively) which should be loaded into RTC memory:
RTC_DATA_ATTR int wake_count;

static RTC_RODATA_ATTR const char fmt_str[] = "Wake count %d\n";
esp_rom_printf(fmt_str, wake_count++);
}
The RTC memory area where this data will be placed can be configured via menuconfig option named CON-
FIG_ESP32_RTCDATA_IN_FAST_MEM. This option allows to keep slow memory area for ULP programs and
once it is enabled the data marked with RTC_DATA_ATTR and RTC_RODATA_ATTR are placed in the RTC
fast memory segment otherwise it goes to RTC slow memory (default option). This option depends on the CON-
FIG_FREERTOS_UNICORE because RTC fast memory can be accessed only by PRO_CPU.
The attributes RTC_FAST_ATTR and RTC_SLOW_ATTR can be used to specify data that will be force placed into
RTC_FAST and RTC_SLOW memory respectively. Any access to data marked with RTC_FAST_ATTR is allowed
by PRO_CPU only and it is responsibility of user to make sure about it.
Unfortunately, any string constants used in this way must be declared as arrays and marked with
RTC_RODATA_ATTR, as shown in the example above.
The second way is to place the data into any source file whose name starts with rtc_wake_stub.
For example, the equivalent example in rtc_wake_stub_counter.c:
int wake_count;

esp_rom_printf("Wake count %d\n", wake_count++);
}
The second way is a better option if you need to use strings, or write other more complex code.
To reduce wake-up time use the CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP Kconfig option, see
more information in Fast boot from Deep Sleep.
4.7 Error Handling
4.7.1 Overview
Identifying and handling run-time errors is important for developing robust applications. There can be multiple kinds
of run-time errors:
• Recoverable errors:
– Errors indicated by functions through return values (error codes)
– C++ exceptions, thrown using throw keyword
• Unrecoverable (fatal) errors:
– Failed assertions (using assert macro and equivalent methods, see Assertions) and abort() calls.
– CPU exceptions: access to protected regions of memory, illegal instruction, etc.

– System level checks: watchdog timeout, cache access error, stack overflow, stack smashing, heap corrup-
tion, etc.
This guide explains ESP-IDF error handling mechanisms related to recoverable errors, and provides some common
error handling patterns.
For instructions on diagnosing unrecoverable errors, see Fatal Errors.
4.7.2 Error codes
The majority of ESP-IDF-specific functions use esp_err_t type to return error codes. esp_err_t is a signed
integer type. Success (no error) is indicated with ESP_OK code, which is defined as zero.
Various ESP-IDF header files define possible error codes using preprocessor defines. Usually these defines start
with ESP_ERR_ prefix. Common error codes for generic failures (out of memory, timeout, invalid argument, etc.)
are defined in esp_err.h file. Various components in ESP-IDF may define additional error codes for specific
situations.
For the complete list of error codes, see Error Code Reference.
4.7.3 Converting error codes to error messages
For each error code defined in ESP-IDF components, esp_err_t value can be converted to an error code
name using esp_err_to_name() or esp_err_to_name_r() functions. For example, passing 0x101 to
esp_err_to_name() will return ESP_ERR_NO_MEM string. Such strings can be used in log output to
make it easier to understand which error has happened.
Additionally, esp_err_to_name_r() function will attempt to interpret the error code as a standard POSIX error
code, if no matching ESP_ERR_ value is found. This is done using strerror_r function. POSIX error codes
(such as ENOENT, ENOMEM) are defined in errno.h and are typically obtained from errno variable. In ESP-IDF
this variable is thread-local: multiple FreeRTOS tasks have their own copies of errno. Functions which set errno
only modify its value for the task they run in.
This feature is enabled by default, but can be disabled to reduce application binary size. See CON-
FIG_ESP_ERR_TO_NAME_LOOKUP. When this feature is disabled, esp_err_to_name() and
esp_err_to_name_r() are still defined and can be called. In this case, esp_err_to_name() will
return UNKNOWN ERROR, and esp_err_to_name_r() will return Unknown error 0xXXXX(YYYYY),
where 0xXXXX and YYYYY are the hexadecimal and decimal representations of the error code, respectively.
4.7.4 ESP_ERROR_CHECK macro
ESP_ERROR_CHECK() macro serves similar purpose as assert, except that it checks esp_err_t value rather
than a bool condition. If the argument of ESP_ERROR_CHECK() is not equal ESP_OK, then an error message
is printed on the console, and abort() is called.
Error message will typically look like this:
ESP_ERROR_CHECK failed: esp_err_t 0x107 (ESP_ERR_TIMEOUT) at 0x400d1fdf
file: "/Users/user/esp/example/main/main.c" line 20

func: app_main
expression: sdmmc_card_init(host, &card)
Backtrace: 0x40086e7c:0x3ffb4ff0 0x40087328:0x3ffb5010 0x400d1fdf:0x3ffb5030␣

,→0x400d0816:0x3ffb5050
Note: If IDF monitor is used, addresses in the backtrace will be converted to file names and line numbers.

• The first line mentions the error code as a hexadecimal value, and the identifier used for this error in source code.
The latter depends on CONFIG_ESP_ERR_TO_NAME_LOOKUP option being set. Address in the program
where error has occured is printed as well.
• Subsequent lines show the location in the program where ESP_ERROR_CHECK() macro was called, and the
expression which was passed to the macro as an argument.
• Finally, backtrace is printed. This is part of panic handler output common to all fatal errors. See Fatal Errors
for more information about the backtrace.
4.7.5 ESP_ERROR_CHECK_WITHOUT_ABORT macro
ESP_ERROR_CHECK_WITHOUT_ABORT() macro serves similar purpose as ESP_ERROR_CHECK, except that

it won t call abort().
4.7.6 ESP_RETURN_ON_ERROR macro
ESP_RETURN_ON_ERROR() macro checks the error code, if the error code is not equal ESP_OK, it prints the
message and returns.
4.7.7 ESP_GOTO_ON_ERROR macro
ESP_GOTO_ON_ERROR() macro checks the error code, if the error code is not equal ESP_OK, it prints the
message, sets the local variable ret to the code, and then exits by jumping to goto_tag.
4.7.8 ESP_RETURN_ON_FALSE macro
ESP_RETURN_ON_FALSE() macro checks the condition, if the condition is not equal true, it prints the message
and returns with the supplied err_code.
4.7.9 ESP_GOTO_ON_FALSE macro
ESP_GOTO_ON_FALSE() macro checks the condition, if the condition is not equal true, it prints the message, sets
the local variable ret to the supplied err_code, and then exits by jumping to goto_tag.
4.7.10 CHECK MACROS Examples
Some examples:
static const char* TAG = "Test";
esp_err_t test_func(void)
{
esp_err_t ret = ESP_OK;
ESP_ERROR_CHECK(x); // err message␣

,→printed if `x` is not ÈSP_OK`, and then àbort()`.
ESP_ERROR_CHECK_WITHOUT_ABORT(x); // err message␣
,→printed if `x` is not ÈSP_OK`, without àbort()`.
ESP_RETURN_ON_ERROR(x, TAG, "fail reason 1"); // err message␣

,→printed if `x` is not ÈSP_OK`, and then function returns with code `x`.
ESP_GOTO_ON_ERROR(x, err, TAG, "fail reason 2"); // err message␣

,→printed if `x` is not ÈSP_OK`, `ret` is set to `x`, and then jumps to èrr`.
ESP_RETURN_ON_FALSE(a, err_code, TAG, "fail reason 3"); // err message␣

,→printed if à` is not `true`, and then function returns with code èrr_code`.


ESP_GOTO_ON_FALSE(a, err_code, err, TAG, "fail reason 4"); // err message␣
,→printed if à` is not `true`, `ret` is set to èrr_code`, and then jumps to␣
,→èrr`.
err:
// clean up
return ret;
}
Note: If the option CONFIG_COMPILER_OPTIMIZATION_CHECKS_SILENT in Kconfig is enabled, the err message

will be discarded, while the other action works as is.
The ESP_RETURN_XX and ESP_GOTO_xx macros can t be called from ISR. While there are xx_ISR versions
for each of them, e.g., ESP_RETURN_ON_ERROR_ISR, these macros could be used in ISR.
4.7.11 Error handling patterns
1. Attempt to recover. Depending on the situation, this might mean to retry the call after some time, or attempt
to de-initialize the driver and re-initialize it again, or fix the error condition using an out-of-band mechanism
(e.g reset an external peripheral which is not responding).
Example:
esp_err_t err;
do {
err = sdio_slave_send_queue(addr, len, arg, timeout);
// keep retrying while the sending queue is full
} while (err == ESP_ERR_TIMEOUT);
// handle other errors
}
2. Propagate the error to the caller. In some middleware components this means that a function must exit with
the same error code, making sure any resource allocations are rolled back.
Example:
sdmmc_card_t* card = calloc(1, sizeof(sdmmc_card_t));

if (card == NULL) {
return ESP_ERR_NO_MEM;
}
esp_err_t err = sdmmc_card_init(host, &card);
// Clean up
free(card);
// Propagate the error to the upper layer (e.g. to notify the user).
// Alternatively, application can define and return custom error code.
return err;
}
3. Convert into unrecoverable error, for example using ESP_ERROR_CHECK. See ESP_ERROR_CHECK macro
section for details.
Terminating the application in case of an error is usually undesirable behaviour for middleware components,
but is sometimes acceptable at application level.
Many ESP-IDF examples use ESP_ERROR_CHECK to handle errors from various APIs. This is not the best
practice for applications, and is done to make example code more concise.
Example:
ESP_ERROR_CHECK(spi_bus_initialize(host, bus_config, dma_chan));

4.7.12 C++ Exceptions
Support for C++ Exceptions in ESP-IDF is disabled by default, but can be enabled using CON-
FIG_COMPILER_CXX_EXCEPTIONS option.
Enabling exception handling normally increases application binary size by a few kB. Additionally it may be necessary
to reserve some amount of RAM for exception emergency pool. Memory from this pool will be used if it is not
possible to allocate exception object from the heap. Amount of memory in the emergency pool can be set using
CONFIG_COMPILER_CXX_EXCEPTIONS_EMG_POOL_SIZE variable.
If an exception is thrown, but there is no catch block, the program will be terminated by abort function, and
backtrace will be printed. See Fatal Errors for more information about backtraces.
See cxx/exceptions for an example of C++ exception handling.
4.8 ESP-BLE-MESH
Bluetooth® mesh networking enables many-to-many (m:m) device communications and is optimized for creating
large-scale device networks.
Devices may relay data to other devices not in direct radio range of the originating device. In this way, mesh networks
can span very large physical areas and contain large numbers of devices. It is ideally suited for building automation,
sensor networks, and other IoT solutions where tens, hundreds, or thousands of devices need to reliably and securely
communicate with one another.
Bluetooth mesh is not a wireless communications technology, but a networking technology. This technology is de-
pendent upon Bluetooth Low Energy (BLE) - a wireless communications protocol stack.
Built on top of Zephyr Bluetooth Mesh stack, the ESP-BLE-MESH implementation supports device provisioning and
node control. It also supports such node features as Proxy, Relay, Low power and Friend.
Please see the ESP-BLE-MESH Architecture for information about the implementation of ESP-BLE-MESH architec-
ture and ESP-BLE-MESH API Reference for information about respective API.
ESP-BLE-MESH is implemented and certified based on the latest Mesh Profile v1.0.1, users can refer here for the
certification details of ESP-BLE-MESH.
Note: If you are looking for Wi-Fi based implementation of mesh for ESP32, please check another product by
Espressif called ESP-WIF-MESH. For more information and documentation see ESP-WIFI-MESH.
4.8.1 Getting Started with ESP-BLE-MESH
This section is intended to help you get started with ESP-BLE-MESH for the hardware based on the ESP32 chip by
Espressif.
We are going to demonstrate process of setting and operation of a small ESP-BLE-MESH network of three nodes.
This process will cover device provisioning and node configuration, and then sending on/off commands to Generic
OnOff Server Models on specific nodes.
If you are new to ESP-IDF, please first set up development environment, compile , flash and run example application
following top level ESP-IDF Get Started documentation.
What You Need
Hardware:
• Three ESP32 boards, see options.
• USB cables to connect the boards.
• Computer configured with ESP-IDF.

• Mobile phone or tablet running Android or iOS.

Software:
• Example application bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server code to load to the ESP32 boards.
• Mobile App: nRF Mesh for Android or iOS. Optionally you can use some other Apps:
– EspBleMesh Android App
– Silicon Labs Android or iOS App
Installation Step by Step
This is a detailed roadmap to walk you through the installation process.
Step 1. Check Hardware Both ESP32-DevKitC and ESP-WROVER-KIT development boards are supported for
ESP-BLE-MESH implementation. You can choose particular board through menuconfig: idf.py menuconfig
> Example Configuration > Board selection for ESP-BLE-MESH
Note: If you plan to use ESP32-DevKitC, connect a RGB LED to GPIO pins 25, 26 and 27.
Step 2. Configure Software Enter the bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server example directory,

run idf.py menuconfig to select your board and then run idf.py build to compile the example.
Step 3. Upload Application to Nodes After the bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server example

is compiled successfully, users can run idf.py flash to upload the same generated binary files into each of the
three development boards.
Once boards are powered on, the RGB LED on each board should turn GREEN.
Fig. 4: ESP-BLE-MESH Devices Power On

Step 4. Provision Nodes In this section, we will use the nRF Mesh Android App to demonstrate how to provision
an unprovisioned device. Users can also get its iOS version from the App Store.
4.1 Scanner The Scanner is App s functionality to search for unprovisioned devices in range. Open the App,
press Scanner at the bottom and the search will start. After a short while we should see three unprovisioned devices
displayed.
Fig. 5: nRF Mesh - Scanner
4.2 Identify Users can select any unprovisioned device, then the App will try to set up a connection with the
selected device. After the BLE connection is established successfully (sometimes users need to try multiple times to
get connected), and proper ESP-BLE-MESH GATT Service is discovered, users can see the IDENTIFY interface
button on the screen. The IDENTIFY operation can be used to tell users which device is going to be provisioned.
Note: The IDENTIFY operation also needs some cooperation on the device side, then users can see which device is
in the provisioning process. Currently when pressing the IDENTIFY interface button, no signs can been seen from
the device except from the log on the serial monitor.
After the IDENTIFY interface button is pressed, users can see the PROVISION interface button.
4.3 Provision Then, the App will try to provision the unprovisioned device. When the device is provisioned suc-
cessfully, the RGB LED on the board will turn off, and the App will implement the following procedures:
1. Disconnect with the node
2. Try to reconnect with the node
3. Connect successfully and discover ESP-BLE-MESH GATT Service
4. Get Composition Data of the node and add AppKey to it
When all the procedures are finished, the node is configured properly. And after pressing OK, users can see that
unicast address is assigned, and Composition Data of the node is decoded successfully.

Fig. 6: nRF Mesh - IDENTIFY - PROVISION
Fig. 7: nRF Mesh - Configuration Complete

Sometimes in procedure 2, the App may fail to reconnect with the node. In this case, after pressing OK, users can
see that only unicast address of the node has been assigned, but no Composition Data has been got. Then users need
to press CONNECT on the top right, and the previously provisioned node will be displayed on the screen, and users
need to choose it and try to connect with the node.
Fig. 8: nRF Mesh - Initial Configuration Failed
After connecting successfully, the App will show the interface buttons which can be used to get Composition Data
and add AppKey.
If the device is the second or the third one which has been provisioned by the App, and after pressing CONNECT,
users can see two or three nodes on the screen. In this situation, users can choose any device to connect with, once
succeed then go back to the main screen to choose the node which needs to be configured.
Here an example of three devices listed.
• The left picture shows that the third device is provisioned successfully, but the App failed to connect with it.
When it tries to reconnect with the third node, three nodes are displayed on the App.
• The right picture shows that after connecting with any node successfully, the App displays the information of
the three nodes. Users can see that the App has got the Composition Data of the first and the second nodes,
but for the third one, only the unicast address has been assigned to it while the Composition Data is unknown.
4.4 Configuration When provisioning and initial configuration are finished, users can start to configure the node,
such as binding AppKey with each model with the elements, setting publication information to it, etc.
Example below shows how to bind AppKey with Generic OnOff Server Model within the Primary Element.
Note: No need to bind AppKey with the Configuration Server Model, since it only uses the DevKey to encrypt
messages in the Upper Transport Layer.
Step 5. Operate Network After all the Generic OnOff Server Models within the three elements are bound with
proper AppKey, users can use the App to turn on/off the RGB LED.

Fig. 9: nRF Mesh - Reconnect - Initial Configuration
Fig. 10: nRF Mesh - Reconnect - Three Nodes

Fig. 11: nRF Mesh - Model Bind AppKey
In the bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server example, the first Generic OnOff Server Model is used
to control the RED color, the second one is used to control the GREEN color and the third one is used to control
the BLUE color.
The following screenshot shows different board with different color on.
Note: For nRF Mesh iOS App [version 1.0.4], when the node contains more than one element, the App is not
behaving correctly. If users try to turn on/off the second or the third Generic OnOff Server Model, the message sent
by the App is destinated to the first Generic OnOff Server Model within the Primary Element.
4.8.2 ESP-BLE-MESH Examples
• ESP-BLE-MESH Node OnOff Server - shows the use of ESP-BLE-MESH as a node having a Configuration
Server model and a Generic OnOff Server model. A ESP-BLE-MESH Provisioner can then provision the
unprovisioned device and control a RGB LED representing on/off state, see example code .
• ESP-BLE-MESH Node OnOff Client - shows how a Generic OnOff Client model works within a node. The
node has a Configuration Server model and a Generic OnOff Client model, see example code .
• ESP-BLE-MESH Provisioner - shows how a device can act as an ESP-BLE-MESH Provisioner to provision
devices. The Provisioner has a Configuration Server model, a Configuration Client model and a Generic OnOff
Client model, see example code .
• ESP-BLE-MESH Fast Provisioning - Client and Server - this example is used for showing how fast provision-
ing can be used in order to create a mesh network. It takes no more than 60 seconds to provision 100 devices,
see example client code and example server code .
• ESP-BLE-MESH and Wi-Fi Coexistence - an example that demonstrates the Wi-Fi and Bluetooth
(BLE/BR/EDR) coexistence feature of ESP32. Simply put, users can use the Wi-Fi while operating Blue-
tooth, see example code .
• ESP-BLE-MESH Console - an example that implements BLE Mesh basic features. Within this example a node
can be scanned and provisioned by Provisioner and reply to get/set message from Provisioner, see example node
code .

Fig. 12: nRF Mesh - Generic OnOff Control
Fig. 13: Three ESP-BLE-MESH Nodes On

4.8.3 ESP-BLE-MESH Demo Videos
• Provisioning of ESP-BLE-MESH nodes using Smartphone App

• Espressif Fast Provisioning using ESP-BLE-MESH App
• Espressif ESP-BLE-MESH and Wi-Fi Coexistence
4.8.4 ESP-BLE-MESH FAQ
• 1. Provisioner Development
• 2. Node Development
• 3. ESP-BLE-MESH and Wi-Fi Coexistence
• 4. Fast Provisioning
• 5. Log Help
• 6. Example Help
• 7. Others
ESP-BLE-MESH Feature List
Supported Features
Mesh Core
• Provisioning: Node Role
– PB-ADV and PB-GATT
– OOB Authentication
• Provisioning: Provisioner Role
– PB-ADV and PB-GATT
– OOB Authentication
• Networking
– Relay
– Segmentation and Reassembly
– Key Refresh Procedure
– IV Update Procedure
– Friend
– Low Power
– Proxy Server
– Proxy Client
• Multiple Client Models Run Simultaneously
– Support multiple client models send packets to different nodes simultaneously
– No blocking between client model and server model
• NVS Storing
– Store provisioning and configuration information of ESP-BLE-MESH Node
Mesh Models
• Foundation models
– Configuration Server model
– Configuration Client model
– Health Server model
– Health Client model
• Generic client models
– Generic OnOff Client
– Generic Level Client
– Generic Default Transition Time Client

– Generic Power OnOff Client

– Generic Power Level Client
– Generic Battery Client
– Generic Location Client
– Generic Property Client
• Sensor client models
– Sensor Client
• Time and Scenes client models
– Time Client
– Scene Client
– Scheduler Client
• Lighting client models
– Light Lightness Client
– Light CTL Client
– Light HSL Client
– Light xyL Client
– Light LC Client
• Generic server models
– Generic OnOff Server
– Generic Level Server
– Generic Default Transition Time Server
– Generic Power OnOff Server
– Generic Power OnOff Setup Server
– Generic Power Level Server
– Generic Power Level Setup Server
– Generic Battery Server
– Generic Location Server
– Generic Location Setup Server
– Generic User Property Server
– Generic Admin Property Server
– Generic Manufacturer Property Server
– Generic Client Property Server
• Sensor server models
– Sensor Server
– Sensor Setup Server
• Time and Scenes server models
– Time Server
– Time Setup Server
– Scene Server
– Scene Setup Server
– Scheduler Server
– Scheduler Setup Server
• Lighting server models
– Light Lightness Server
– Light Lightness Setup Server
– Light CTL Server
– Light CTL Temperature Server
– Light CTL Setup Server
– Light HSL Server
– Light HSL Hue Server
– Light HSL Saturation Server
– Light HSL Setup Server
– Light xyL Server
– Light xyL Setup Server
– Light LC Server
– Light LC Setup Server

Mesh Applications
• ESP-BLE-MESH Node
– Tutorial
– Tutorial
– Example
• ESP-BLE-MESH Provisioner
– Tutorial
– Example
• ESP-BLE-MESH Fast Provisioning
– Fast Provisioning Client Model Tutorial
– Fast Provisioning Server Model Tutorial
– Example
– Demo Video
• ESP-BLE-MESH and Wi-Fi Coexistence
– Tutorial
– Example
– Demo Video
• ESP-BLE-MESH Console Commands
– Example
Future Release Features
Mesh Core
• Provisioner NVS Storage
Mesh Applications
• Fast OTA
• Friendship
ESP-BLE-MESH Architecture
This document introduces ESP-BLE-MESH architecture overview, ESP-BLE-MESH architecture implementation

as well as ESP-BLE-MESH auxiliary routines.
• ESP-BLE-MESH Architecture Overview
– Describes the five major parts of ESP-BLE-MESH architecture and the functionality of each part.
• ESP-BLE-MESH Architecture Implementation
– Describes the basic functions of ESP-BLE-MESH files, the correspondence between files and ESP-BLE-
MESH architecture, and the interface for calling among files.
• ESP-BLE-MESH Auxiliary Routines
– Describe the auxiliary routines of ESP-BLE-MESH, such as Mesh network management, Mesh features,
etc.
1. ESP-BLE-MESH Architecture Overview Currently ESP-BLE-MESH has implemented most functions of

Mesh Profile and all the Client Models defined in Mesh Model specification. Those missing functions/models are
under development and will be provided soon. ESP-BLE-MESH architecture has been granted the official Bluetooth
certification.
ESP-BLE-MESH architecture includes five key parts:
• Mesh Protocol Stack
– Mesh Networking is responsible for processing of messages of ESP-BLE-MESH nodes.
– Mesh Provisioning is responsible for provisioning flow of ESP-BLE-MESH devices.
– Mesh Models is responsible for the implementation of SIG-defined models.

Fig. 14: Figure 1.1 ESP-BLE-MESH Architecture Diagram

• Network Management
– Implements several network management procedures, including node removal procedure, IV Index re-
covery procedure, etc.
• Features
– Include several ESP-BLE-MESH features, e.g. Low Power feature, Friend feature, Relay feature, etc.
• Mesh Bearer Layer
– Includes Advertising Bearer and GATT Bearer. The bearer layer is crucial to ESP-BLE-
MESH protocol stack which is built on Bluetooth Low-Energy technology, because the protocol stack
must make use of the bearer layer to transmit data via the BLE advertising channel and connection chan-
nel.
• Applications
– Based on ESP-BLE-MESH protocol stack and Mesh Models.
– By calling API and handling Event, Applications interact with Mesh Networking and Mesh
Provisioning in ESP-BLE-MESH protocol stack, as well as a series of Models provided by Mesh
Models.
1.1 Mesh Protocol Stack
1.1.1 Mesh Networking Mesh Networking in the protocol stack architecture implements the following func-
tions:
• The communication between nodes in the Mesh network.
• Encryption and decryption of messages in the Mesh network.
• Management of Mesh network resources (Network Key, IV Index, etc.).
• Segmentation and reassembly of Mesh network messages.
• Model mapping of messages between different models.
• For more features, please see ESP-BLE-MESH Feature List.
The implementation of Mesh Networking functions is based on hierarchy structure. Functions of each layer are
shown in Table 1.1:
Table 1: Table 1.1 Mesh Networking Architecture Description

Layer Function
Access Layer Access Layer not only defines the format of application data, but also defines and controls
the encryption and decryption of the data packets conducted by Upper Transport Layer.
Upper Transport Upper Transport Layer encrypts, decrypts, and authenticates application data to and from
Layer the access layer; it also handles special messages called transport control messages ,
including messages related to friendship and heartbeat messages.
Lower Transport Lower Transport Layer handles segmentation and reassembly of PDU.
Layer
Network Layer Network Layer defines the address type and format of the network messages, and imple-
ments the relay function of the device.
1.1.2 Mesh Provisioning Mesh Provisioning in the protocol stack architecture implements the following
functions:
• Provisioning of unprovisioned devices.
• Allocation of Mesh network resources (unicast address, IV Index, NetKey, etc.).
• Four authentication methods support during provisioning.
• For more features, please see ESP-BLE-MESH Feature List.
The implementation of Mesh Provisioning functions is based on hierarchy structure. Functions of each layer
are shown in Table 1.2:

Table 2: Table 1.2 Mesh Provisioning Architecture Description

Layer Function
Provisioning PDUs Provisioning PDUs from different layers are handled using provisioning protocol.
Generic Provisioning The Provisioning PDUs are transmitted to an unprovisioned device using a Generic Pro-
PDU/Proxy PDU visioning layer or Proxy protocol layer.
PB-ADV/PB-GATT These layers define how the Provisioning PDUs are transmitted as transactions that can
be segmented and reassembled.
Advertising/ProvisioningThe provisioning bearers define how sessions are established such that the transactions
Service from the generic provisioning layer can be delivered to a single device.
1.1.3 Mesh Models Mesh Models in the protocol stack architecture implements the following functions:
• Configuration Client/Server Models
• Health Client/Server Models
• Generic Client/Server Models
• Sensor Client/Server Models
• Time and Scenes Client/Server Models
• Lighting Client/Server Models
Functions of each layer are shown in Table 1.3:
Table 3: Table 1.3 Mesh Models Architecture Description

Layer Function
Model Layer Model Layer implements models used to standardize the operation of typical user sce-
narios, including Generic Client/Server Models, Sensor Client/Server Models, Time and
Scenes Client/Server Models, Lighting Client/Server Models and several vendor models.
Foundation Model Foundation Model Layer implements models related to ESP-BLE-MESH configuration,
Layer management, self diagnosis, etc.
1.2 Mesh Network Management Network Management implements the following functions:
• Node removal procedure is used to remove a node from the network.
• IV Index recovery procedure is used to recover a node s IV Index.
• IV update procedure is used to update the nodes IV Index.
• Key refresh procedure is used to update the nodes NetKey, AppKey, etc.
• Network creation procedure is used to create a mesh network.
• NVS storage is used to store node s networking information.
1.3 Mesh Features Features includes the following options:

• Low Power feature is used to reduce node s power consumption.
• Friend feature is used to store messages for Low Power nodes.
• Relay feature is used to relay/forward Network PDUs received by a node over the advertising bearer.
• Proxy Server/Client are two node roles in proxy protocol, which enable nodes to send and receive Network
PDUs, mesh beacons, proxy configuration messages and Provisioning PDUs over a connection-oriented bearer.
1.4 Mesh Bearer Layer Bearers in the protocol stack architecture are responsible for passing of data between
ESP-BLE-MESH protocol stack and Bluetooth Low Energy Core.
Bearers can be taken as a carrier layer based on Bluetooth Low Energy Core, which implements the function of
receiving and transmitting data for the ESP-BLE-MESH protocol stack.

Table 4: Table 1.3 Mesh Bearers Description

Layer Function
GATT Bearer The GATT Bearer uses the Proxy protocol to transmit and receive Proxy PDUs between
two devices over a GATT connection.
Advertising Bearer When using the Advertising Bearer, a mesh packet shall be sent in the Advertising Data
of a Bluetooth Low Energy advertising PDU using the Mesh Message AD
Type.
1.5 Mesh Applications The Applications in the protocol stack architecture implement the corresponding
functions by calling the API provided by the ESP-BLE-MESH protocol stack and processing the Event reported by
the protocol stack. There are some common applications, such as gateway, lighting and etc.
Interaction between application layer Applications and API / Event
• Application layer calls API
– Call the provisioning-related API for provisioning.
– Call the model-related API to send messages.
– Call the device-attributes-related API to get local information about the device.
• Application layer processes Event
The application layer is designed based on events, which take parameters to the application layer. Events are
mainly divided into two categories.
– The events completed by calling API.
* Such as nodes sending messages.
– The events that the protocol stack actively reports to the application layer.
* The Event that the protocol stack actively reports.
* The Event that Model actively reports.
• The event is reported by the callback function registered by the application layer, and the callback function also
contains the corresponding processing of the event.
Interaction between API / Event and ESP-BLE-MESH protocol stack
• API used by user mainly calls functions provided by Mesh Networking, Mesh Provisioning and
Mesh Models.
• The interaction between API / Event and the protocol stack does not operate across the hierarchy of the
protocol stack. For example, API does not call functions related to Network Layer.
2. ESP-BLE-MESH Architecture Implementation The design and implementation of ESP-BLE-MESH archi-

tecture is based on layers and modules. In details, Section 2.1 (Mesh Networking Implementation), Section 2.2 (Mesh
Provisioning Implementation) and Section 2.3 (Mesh Bearers Implementation) are based on layers, and Section 2.4
(Mesh Models Implementation) is on modules.
• Layer-based Approach: With Layer-based approach, the architecture is designed according to the layers
specified in the Mesh Profile Specification. Each layer has its unique files which include APIs of this layer and
etc. The specific design is shown in Figure 2.1.
• Module-based Approach: Every file implements an independent function that can be called by other pro-
grams.
The design of ESP-BLE-MESH architecture uses layer-based approach. The sequence of layers which data packets
are processed through is fixed, i.e., the processing of packets will form a message flow. Thus, we could see flows
of messages from the Protocol Stack Interface Diagram in Figure 2.1.
2.1 Mesh Protocol Stack Implementation
2.1.1 Mesh Networking Implementation The list of files and the functions implemented in each file in Mesh
Networking are shown in Table 2.1:

Fig. 15: Figure 2.1 ESP-BLE-MESH Architecture Implementation Diagram

Table 5: Table 2.1 Mesh Networking File Description :widths: 40 150

:header-rows: 1
File Functionality
ac- ESP-BLE-MESH Access Layer
cess.c
trans- ESP-BLE-MESH Lower/Upper Transport Layer

port.c
net.c ESP-BLE-MESH Network Layer

adv.c A task used to send ESP-BLE-MESH advertising packets, a callback used to handle received adver-
tising packets and APIs used to allocate adv buffers
2.1.2 Mesh Provisioning Implementation The implementation of Mesh Provisioning is divided into two chunks
due to the Node/Provisioner coexistence.
Specific files that provide implementation of provisioning of Node are shown in Table 2.2:
Table 6: Table 2.2 Mesh Provisioning (Node) File Description

File Functionality
prov.c ESP-BLE-MESH Node provisioning (PB-ADV & PB-GATT)
proxy_server.c ESP-BLE-MESH Proxy Server related functionalities
beacon.c APIs used to handle ESP-BLE-MESH Beacons
Specific files that implement functions of Provisioner are shown in Table 2.3:
Table 7: Table 2.3 Mesh Provisioning (Provisioner) File Description

File Functionality
provisioner_prov.c ESP-BLE-MESH Provisioner provisioning (PB-ADV & PB-GATT)
proxy_client.c ESP-BLE-MESH Proxy Client related functionalities
provisioner_main.c ESP-BLE-MESH Provisioner networking related functionalities
2.1.3 Mesh Models Implementation Mesh Models are used to implement the specific functions of model in nodes.
Server model is used to maintain node status. Client model is used to obtain and modify node state.

Table 8: Table 2.4 Mesh Models File Description

File Functionality
cfg_cli.c Send Configuration Client messages and receive corresponding response messages
cfg_srv.c Receive Configuration Client messages and send proper response messages
health_cli.c Send Health Client messages and receive corresponding response messages
health_srv.c Receive Health Client messages and send proper response messages
client_common.c ESP-BLE-MESH model related operations
generic_client.c Send ESP-BLE-MESH Generic Client messages and receive corresponding response
messages
lighting_client.c Send ESP-BLE-MESH Lighting Client messages and receive corresponding response
messages
sensor_client.c Send ESP-BLE-MESH Sensor Client messages and receive corresponding response mes-
sages
time_scene_client.c Send ESP-BLE-MESH Time Scene Client messages and receive corresponding response
messages
generic_server.c Receive ESP-BLE-MESH Generic Client messages and send corresponding response
messages
lighting_server.c Receive ESP-BLE-MESH Lighting Client messages and send corresponding response
messages
sensor_server.c Receive ESP-BLE-MESH Sensor Client messages and send corresponding response mes-
sages
time_scene_server.c Receive ESP-BLE-MESH Time Scene Client messages and send corresponding response
messages
2.2 Mesh Bearers Implementation Portability is fully considered in the implementation of Mesh Bearers.
When the ESP-BLE-MESH protocol stack is being ported to other platforms, users only need to modify
mesh_bearer_adapt.c (example of NimBLE version ).
Table 9: Table 2.5 Mesh Bearers File Description

File Functionality
mesh_bearer_adapt.c ESP-BLE-MESH Bearer Layer adapter This file provides the interfaces used to receive
and send ESP-BLE-MESH ADV & GATT related packets.
Note: mesh_bearer_adapt.c is the implementation of Advertising Bearer and GATT Bearer in Mesh
Networking framework.
2.3 Mesh Applications Implementation We have provided a series of application examples for customer devel-
opment, and users can develop products based on ESP-BLE-MESH Examples.
3. Auxiliary Routine Auxiliary routine refers to optional functions in the ESP-BLE-MESH protocol stack. The
design of the auxiliary routine generally implement the truncation of code through CONFIG_BLE_MESH.
3.1 Features
• Low Power
• Friend
• Relay
• Proxy Client/Server

3.2 Network Management

• Node Removal procedure
• IV Index Recovery procedure
• IV Update procedure
• Key Refresh procedure
• Network Creation procedure
• NVS Storage
3.3 Auxiliary Routine Implementation When adopting the design of independent module, the two main factors
should be considered:
• The module can not be implemented hierarchically, and it can be completely independent, which means it does
not rely on the implementation of other modules.
• The functions in the module will be used repeatedly, so it is reasonable to design it into a module. Independent
module is shown in Table 3.1:
Table 10: Table 3.1 Module File Description

File Functionality
lpn.c ESP-BLE-MESH Low Power functionality
friend.c ESP-BLE-MESH Friend functionality
net.c ESP-BLE-MESH Relay feature, network creation, IV Update procedure, IV Index re-
covery procedure, Key Refresh procedure related functionalities
proxy_server.c ESP-BLE-MESH Proxy Server related functionalities
proxy_client.c ESP-BLE-MESH Proxy Client related functionalities
settings.c ESP-BLE-MESH NVS storage functionality
main.c ESP-BLE-MESH stack initialize, stack enable, node removal related functionalities
ESP-BLE-MESH FAQ
This document provides a summary of frequently asked questions about developing with ESP-BLE-MESH, and is
divided into seven sections:
• 1. Provisioner Development
• 2. Node Development
• 3. ESP-BLE-MESH and Wi-Fi Coexistence
• 4. Fast Provisioning
• 5. Log Help
• 6. Example Help
• 7. Others
Users could refer to the sections for quick answer to their questions. This document will be updated based on the
feedback collected via various channels.
1. Provisioner Development Generally, a Provisioner is used to provision unprovisioned devices and form a mesh
network. And after provisioning, roles of the unprovisioned devices will be changed to those of a node.
1.1 What is the flow for an unprovisioned device to join ESP-BLE-MESH network?
There are two phases for a device to join ESP-BLE-MESH network via a Provisioner, namely, provi-
sioning and configuration.
• The phase of provisioning is to assign unicast address, add NetKey and etc. to a device. By
provisioning, the device joins the ESP-BLE-MESH network and its role is changed from an un-
provisioned device to a node.

• The phase of configuration is to add AppKeys to the node and bind AppKeys to corresponding
models. And some items are optional during configuration, including adding subscription addresses
to the node, set publication information, etc. By configuration, the node can actually transmit
messages to a Provisioner and receive messages from it.
1.2 If a Provisioner wants to change states of a node, what requirements should be met for a Provisioner?
• Client model that corresponds to server model of the node is required.
• NetKey and AppKey used to encrypt messages shall be owned by both the node and the Provisioner.
• The address owned by the node shall be known, which could be its unicast address or subscription address.
1.3 How can NetKey and AppKey be used?

• NetKey is used for encryption of messages in Network Layer. Nodes with the same NetKey are assumed to
be in the same subnet while those with different NetKeys cannot communicate with each other.
• AppKey is used for encryption of messages in Upper Transport Layer. If client model and server model are
bound to different AppKeys, the communication cannot be achieved.
1.4 How to generate a NetKey or AppKey for Provisioner? Can we use a fixed NetKey or AppKey?
• The API esp_ble_mesh_provisioner_add_local_net_key() can be used to add a NetKey with
a fixed or random value.
• The API esp_ble_mesh_provisioner_add_local_app_key() can be used to add an AppKey
with a fixed or random value.
1.5 Is the unicast address of Provisioner fixed?

The value of prov_unicast_addr in esp_ble_mesh_prov_t is used to set the unicast address
of Provisioner, it can be set only once during initialization and can t be changed afterwards.
1.6 Can the address of Provisioner serve as destination address of the node-reporting-status message
The unicast address of Provisioner can be set only once during initialization and can t be changed after-
wards. In theory, it can serve as the destination address of the node-reporting-status message, provided
that the unicast address of the Provisioner is known by nodes. Nodes can know the unicast address of
Provisioner during configuration since Provisioner sends messages to them with its unicast address used
as the source address. Subscription address can also be used. Provisioner subscribes to a group address
or virtual address, and nodes send messages to the subscription address.
1.7 Is the unicast address of the node that is firstly provisioned by Provisioner to ESP-BLE-MESH network
fixed
The value of prov_start_address in esp_ble_mesh_prov_t is used to set the starting ad-
dress when the Provisioner provisions unprovisioned devices, i.e. the unicast address of the node it firstly
provisioned. It can be set only once during initialization and can t be changed afterwards.
1.8 Is the unicast address of the node that mobile App firstly provisioned fixed?
The App will decide the unicast address, and currently most of them are fixed.
1.9 How to know which unprovisioned device is the Provisioner that is provisioning currently?
The value of prov_attention in esp_ble_mesh_prov_t is used by Provisioner set to unpro-
visioned device during provisioning. It can be set only once during initialization and can t be changed
afterwards. When the unprovisioned device is joining the mesh network, it can display in a specific way
like flashing light to notify Provisioner that it is being provisioned.

1.10 How many ways to authenticate the devices during provisioning? Which way was used in the provided
examples ?
There are four authentication methods, i.e. No OOB, Static OOB, Output OOB and Input OOB. In the
provided examples, No OOB is used.
1.11 What information can be carried by the advertising packets of the unprovisioned device before provi-
sioning into the network?
• Device UUID
• OOB Info
• URL Hash (optional)
1.12 Can such information be used for device identification?

For example, each unprovisioned device contains a unique Device UUID, which can be used for device
identification.
1.13 How is the unicast address assigned when the node provisioned by Provisioner contains multiple ele-
ments?
• Provisioner will assign an unicast address for the primary element of the node, and unicast address of the
remaining elements are incremented one by one.
• For example: If an unprovisioned device has three elements, i.e. the primary element, the second element and
the third element. After provisioning, the primary element address of the node is 0x0002 while the second
element address is 0x0003, and the third element address is 0x0004.
1.14 How can Provisioner get and parse the Composition Data of nodes through Configuration Client Model?
• Provisioner can get the Composition Data of nodes using the Configuration Client Model API
esp_ble_mesh_config_client_set_state() with comp_data_get in the param-
eter esp_ble_mesh_cfg_client_get_state_t set properly.
• Users can refer to the following code to parse the Composition Data:
#include <stdio.h>
#include <string.h>
#include <stdint.h>
//test date: 0C001A0001000800030000010501000000800100001003103F002A00

//0C00 1A00 0100 0800 0300 0001 05 01 0000 0080 0100 0010 0310 3F002A00
// CID is 0x000C
// PID is 0x001A
// VID is 0x0001
// CRPL is 0x0008
// Features is 0x0003 Relay and Friend features.
// Loc is front 0x0100
// NumS is 5
// NumV is 1
// The Bluetooth SIG Models supported are: 0x0000, 0x8000, 0x0001, 0x1000,
,→ 0x1003
// The Vendor Models supported are: Company Identifier 0x003F and Model␣
,→Identifier 0x002A
typedef struct {
int16_t cid;
int16_t pid;
int16_t vid;
int16_t crpl;


int16_t features;
int16_t all_models;
uint8_t sig_models;
uint8_t vnd_models;
} esp_ble_mesh_composition_head;
typedef struct {
uint16_t model_id;
uint16_t vendor_id;
} tsModel;
typedef struct {
// reserve space for up to 20 SIG models
uint16_t SIG_models[20];
uint8_t numSIGModels;
// reserve space for up to 4 vendor models

tsModel Vendor_models[4];
uint8_t numVendorModels;
} esp_ble_mesh_composition_decode;
int decode_comp_data(esp_ble_mesh_composition_head *head, esp_ble_mesh_

,→composition_decode *data, uint8_t *mystr, int size)
{
int pos_sig_base;
int pos_vnd_base;
int i;
memcpy(head, mystr, sizeof(*head));
if(size < sizeof(*head) + head->sig_models * 2 + head->vnd_models *␣

,→ 4) {
return -1;
}
pos_sig_base = sizeof(*head) - 1;
for(i = 1; i < head->sig_models * 2; i = i + 2) {

data->SIG_models[i/2] = mystr[i + pos_sig_base] | (mystr[i + pos_
,→sig_base + 1] << 8);
printf("%d: %4.4x\n", i/2, data->SIG_models[i/2]);

}
pos_vnd_base = head->sig_models * 2 + pos_sig_base;
for(i = 1; i < head->vnd_models * 2; i = i + 2) {

data->Vendor_models[i/2].model_id = mystr[i + pos_vnd_base] |␣
,→(mystr[i + pos_vnd_base + 1] << 8);
printf("%d: %4.4x\n", i/2, data->Vendor_models[i/2].model_id);
data->Vendor_models[i/2].vendor_id = mystr[i + pos_vnd_base + 2]␣

,→ | (mystr[i + pos_vnd_base + 3] << 8);
printf("%d: %4.4x\n", i/2, data->Vendor_models[i/2].vendor_id);
}
return 0;
}
void app_main(void)
{
esp_ble_mesh_composition_head head = {0};


esp_ble_mesh_composition_decode data = {0};
uint8_t mystr[] = { 0x0C, 0x00, 0x1A, 0x00,
0x01, 0x00, 0x08, 0x00,
0x03, 0x00, 0x00, 0x01,
0x05, 0x01, 0x00, 0x00,
0x00, 0x80, 0x01, 0x00,
0x00, 0x10, 0x03, 0x10,
0x3F, 0x00, 0x2A, 0x00};
int ret;
ret = decode_comp_data(&head, &data, mystr, sizeof(mystr));

if (ret == -1) {
printf("decode_comp_data error");
}
}
1.15 How can Provisioner further configure nodes through obtained Composition Data?
Provisioner do the following configuration by calling the Configuration Client Model API
esp_ble_mesh_config_client_set_state().
• Add AppKey to nodes with app_key_add in the parameter
esp_ble_mesh_cfg_client_set_state_t set properly.
• Add subscription address to the models of nodes with model_sub_add in the parameter
• Set publication information to the models of nodes with model_pub_set in the parameter
1.16 Can nodes add corresponding configurations for themselves?

This method can be used in special cases like testing period.
• Here is an example to show nodes add new group addresses for their models.
esp_err_t example_add_fast_prov_group_address(uint16_t model_id, uint16_t␣
,→group_addr)
{
const esp_ble_mesh_comp_t *comp = NULL;
esp_ble_mesh_elem_t *element = NULL;
esp_ble_mesh_model_t *model = NULL;
int i, j;
if (!ESP_BLE_MESH_ADDR_IS_GROUP(group_addr)) {
return ESP_ERR_INVALID_ARG;
}
comp = esp_ble_mesh_get_composition_data();
if (!comp) {
return ESP_FAIL;
}
for (i = 0; i < comp->element_count; i++) {

element = &comp->elements[i];
model = esp_ble_mesh_find_sig_model(element, model_id);
if (!model) {
continue;
}
for (j = 0; j < ARRAY_SIZE(model->groups); j++) {
if (model->groups[j] == group_addr) {
break;


}
}
if (j != ARRAY_SIZE(model->groups)) {
ESP_LOGW(TAG, "%s: Group address already exists, element␣
,→index: %d", __func__, i);
continue;
}
for (j = 0; j < ARRAY_SIZE(model->groups); j++) {
if (model->groups[j] == ESP_BLE_MESH_ADDR_UNASSIGNED) {
model->groups[j] = group_addr;
break;
}
}
if (j == ARRAY_SIZE(model->groups)) {
ESP_LOGE(TAG, "%s: Model is full of group addresses, element␣
,→index: %d", __func__, i);
}
}
return ESP_OK;
}
Note: When the NVS storage of the node is enabled, group address added and AppKey bound by this method will
not be saved in the NVS when the device is powered off currently. These configuration information can only be saved
if they are configured by Configuration Client Model.
1.17 How does Provisioner control nodes by grouping?

Generally there are two approaches to implement group control in ESP-BLE-MESH network, group
address approach and virtual address approach. And supposing there are 10 devices, i.e., five devices
with blue lights and five devices with red lights.
• Method 1: 5 blue lights can subscribe to a group address, 5 red lights subscribe to another one. By
sending messages to different group addresses, Provisioner can realize group control.
• Method 2: 5 blue lights can subscribe to a virtual address, 5 red lights subscribe to another one.
By sending messages to different virtual addresses, Provisioner can realize group control.
1.18 How does Provisioner add nodes to multiple subnets?

Provisioner can add multiple NetKeys to nodes during configuration, and nodes sharing the same NetKey
belong to the same subnet. Provisioner can communicate with nodes on different subnets by using dif-
ferent NetKeys.
1.19 How does Provisioner know if a node in the mesh network is offline?
Node offline is usually defined as: the condition that the node cannot be properly communicated with
other nodes in the mesh network due to power failure or some other reasons.
There is no connection between nodes and nodes in the ESP-BLE-MESH network. They communicate
with each other through advertising channels.
An example is given here to show how to detect a node is offline by Provisioner.
• The node can periodically send heartbeat messages to Provisioner. And if Provisioner failed to
receive heartbeat messages in a certain period, the node is considered to be offline.

Note: The heartbeat message should be designed into a single package (less than 11 bytes), so the transmission and
reception of it can be more efficient.
1.20 What operations should be performed when Provisioner removes nodes from the network?
Usually when Provisioner tries to remove node from the mesh network, the procedure includes three
main steps:
• Firstly, Provisioner adds the node that need to be removed to the blacklist .
• Secondly, Provisioner performs the Key Refresh procedure.
• Lastly, the node performs node reset procedure, and switches itself to an unprovisioned device.
1.21 In the Key Refresh procedure, how does Provisioner update the Netkey owned by nodes?
• Provisioner updates the NetKey of nodes using the Configuration Client Model API
esp_ble_mesh_config_client_set_state() with net_key_update in the parameter
• Provisioner updates the AppKey of nodes using the Configuration Client Model API
esp_ble_mesh_config_client_set_state() with app_key_update in the parameter
1.22 How does Provisioner manage nodes in the mesh network?

ESP-BLE-MESH implements several functions related to basic node management in the example,
such as esp_ble_mesh_store_node_info(). And ESP-BLE-MESH also provides the API
esp_ble_mesh_provisioner_set_node_name() which can be used to set the node s local
name and the API esp_ble_mesh_provisioner_get_node_name() which can be used to
get the node s local name.
1.23 What does Provisioner need when trying to control the server model of nodes?
Provisioner must include corresponding client model before controlling the server model of nodes.
Provisioner shall add its local NetKey and AppKey.
• Provisioner add NetKey by calling the API esp_ble_mesh_provisioner_add_local_net_key().
• Provisioner add AppKey by calling the API esp_ble_mesh_provisioner_add_local_app_key().
Provisioner shall configure its own client model.
• Provisioner bind AppKey to its own client model by calling the API
esp_ble_mesh_provisioner_bind_app_key_to_local_model().
1.24 How does Provisoner control the server model of nodes?

ESP-BLE-MESH supports all SIG-defined client models. Provisioner can use these client models to
control the server models of nodes. And the client models are divided into 6 categories with each category
has the corresponding functions.
• Configuration Client Model
– The API esp_ble_mesh_config_client_get_state() can be used to get the
esp_ble_mesh_cfg_client_get_state_t values of Configuration Server Model.
– The API esp_ble_mesh_config_client_set_state() can be used to set the
esp_ble_mesh_cfg_client_set_state_t values of Configuration Server Model.
• Health Client Model
– The API esp_ble_mesh_health_client_get_state() can be used to get the
esp_ble_mesh_health_client_get_state_t values of Health Server Model.

– The API esp_ble_mesh_health_client_set_state() can be used to set the

esp_ble_mesh_health_client_set_state_t values of Health Server Model.
• Generic Client Models
– The API esp_ble_mesh_generic_client_get_state() can be used to get the
esp_ble_mesh_generic_client_get_state_t values of Generic Server Mod-
els.
– The API esp_ble_mesh_generic_client_set_state() can be used to set the
esp_ble_mesh_generic_client_set_state_t values of Generic Server Mod-
els.
• Lighting Client Models
– The API esp_ble_mesh_light_client_get_state() can be used to get the
esp_ble_mesh_light_client_get_state_t values of Lighting Server Models.
– The API esp_ble_mesh_light_client_set_state() can be used to set the
esp_ble_mesh_light_client_set_state_t values of Lighting Server Models.
• Sensor Client Models
– The API esp_ble_mesh_sensor_client_get_state() can be used to get the
esp_ble_mesh_sensor_client_get_state_t values of Sensor Server Model.
– The API esp_ble_mesh_sensor_client_set_state() can be used to set the
esp_ble_mesh_sensor_client_set_state_t values of Sensor Server Model.
• Time and Scenes Client Models
– The API esp_ble_mesh_time_scene_client_get_state() can be used to
get the esp_ble_mesh_time_scene_client_get_state_t values of Time
and Scenes Server Models.
– The API esp_ble_mesh_time_scene_client_set_state() can be used to
set the esp_ble_mesh_time_scene_client_set_state_t values of Time
and Scenes Server Models.
2. Node Development
2.1 What kind of models are included by nodes?

• In ESP-BLE-MESH, nodes are all composed of a series of models with each model implements some functions
of the node.
• Model has two types, client model and server model. Client model can get and set the states of server model.
• Model can also be divided into SIG model and vendor model. All behaviors of SIG models are officially defined
while behaviors of vendor models are defined by users.
2.2 Is the format of messages corresponding to each model fixed?

• Messages, which consist of opcode and payload, are divided by opcode.
• The type and the format of the messages corresponding to models are both fixed, which means the messages
transmitted between models are fixed.
2.3 Which functions can be used to send messages with the models of nodes?
• For client models, users can use the API esp_ble_mesh_client_model_send_msg() to send mes-
sages.
• For server models, users can use the API esp_ble_mesh_server_model_send_msg() to send mes-
sages.
• For publication, users call the API esp_ble_mesh_model_publish() to publish messages.
2.4 How to achieve the transmission of messages without packet loss?

Acknowledegd message is needed if users want to transmit messages without packet loss. The default
time to wait for corresponding response is set in CONFIG_BLE_MESH_CLIENT_MSG_TIMEOUT. If the
sender waits for the response until the timer expires, the corresponding timeout event would be triggered.

Note: Response timeout can be set in the API esp_ble_mesh_client_model_send_msg(). The default
value (4 seconds) would be applied if the parameter msg_timeout is set to 0.
2.5 How to send unacknowledged messages?

For client models, users can use the API esp_ble_mesh_client_model_send_msg() with
the parameter need_rsp set to false to send unacknowledged messages.
For server models, the messages sent by using the API esp_ble_mesh_server_model_send_msg()
are always unacknowledged messages.
2.6 How to add subscription address to models?

Subscription address can be added through Configuration Client Model.
2.7 What is the difference between messages sent and published by models?
Messages sent by calling the API esp_ble_mesh_client_model_send_msg() or
esp_ble_mesh_server_model_send_msg() will be sent in the duration determined by
the Network Transmit state.
Messages published by calling the API esp_ble_mesh_model_publish() will be published de-
termined by the Model Publication state. And the publication of messages is generally periodic or with
a fixed number of counts. The publication period and publication count are controlled by the Model
Publication state, and can be configured through Configuration Client Model.
2.8 How many bytes can be carried when sending unsegmented messages?
The total payload length (which can be set by users) of unsegmented message is 11 octets, so if the
opcode of the message is 2 octets, then the message can carry 9-octets of valid information. For vendor
messages, due to the 3-octets opcode, the remaining payload length is 8 octets.
2.9 When should the Relay feature of nodes be enabled?

Users can enable the Relay feature of all nodes when nodes detected in the mesh network are sparse.
For dense mesh network, users can choose to just enable the Relay feature of several nodes.
And users can enable the Relay feature by default if the mesh network size is unknown.
2.10 When should the Proxy feature of node be enabled?

If the unprovisioned device is expected to be provisioned by a phone, then it should enable the Proxy
feature since almost all the phones do not support sending ESP-BLE-MESH packets through advertis-
ing bearer currently. And after the unprovisioned device is provisioned successfully and becoming a
Proxy node, it will communicate with the phone using GATT bearer and using advertising bearer to
communicate with other nodes in the mesh network.
2.11 How to use the Proxy filter?

The Proxy filter is used to reduce the number of Network PDUs exchanged between a Proxy Client (e.g.
the phone) and a Proxy Server (e.g. the node). And with the Proxy filter, Proxy Client can explicitly
request to receive only mesh messages with certain destination addresses from Proxy Server.

2.12 When a message can be relayed by a Relay node?

If a message need to be relayed, the following conditions should be met.
• The message is in the mesh network.
• The message is not sent to the unicast address of the node.
• The value of TTL in the message is greater than 1.
2.13 If a message is segmented into several segments, should the other Relay nodes just relay when one of
these segments is received or wait until the message is received completely?
Relay nodes will forward segments when one of them are received rather than keeping waiting until all
the segments are received.
2.14 What is the principle of reducing power consumption using Low Power feature?
• When the radio is turned on for listening, the device is consuming energy. When low power feature of the node
is enabled, it will turn off its radio in the most of the time.
• And cooperation is needed between low power node and friend node, thus low power node can receive messages
at an appropriate or lower frequency without the need to keep listening.
• When there are some new messages for low power node, its friend node will store the messages for it. And low
power node can poll friend nodes to see if there are new messages at a fixed interval.
2.15 How to continue the communication on the network after powering-down and powering-up again?
Enable the configuration Store ESP-BLE-MESH Node configuration persistently
in menuconfig.
2.16 How to send out the self-test results of nodes?

It is recommended that nodes can publish its self-test results periodically through Health Server Model.
2.17 How to transmit information between nodes?

One possible application scenario for transmitting information between nodes is that spray nodes would
be triggered once smoke alarm detected high smoke concentration. There are two approaches in imple-
mentation.
• Approach 1 is that spray node subscribes to a group address. When smoke alarm detects high smoke
concentration, it will publish a message whose destination address is the group address which has
been subscribed by spray node.
• Approach 2 is that Provisioner can configure the unicast address of spray node to the smoke alarm.
When high smoke concentration is detected, smoke alarm can use send messages to the spray node
with the spray node s unicast address as the destination address.
2.18 Is gateway a must for nodes communication?

• Situation 1: nodes only communicate within the mesh network. In this situation, no gateway is need. ESP-BLE-
MESH network is a flooded network, messages in the network have no fixed paths, and nodes can communicate
with each other freely.
• Situation 2: if users want to control the nodes remotely, for example turn on some nodes before getting home,
then a gateway is needed.
2.19 When will the IV Update procedure be performed?

IV Update procedure would be performed once sequence number of messages sent detected by the
bottom layer of node reached a critical value.

2.20 How to perform IV Update procedure?

Nodes can perform IV Update procedure with Secure Network Beacon.
3. ESP-BLE-MESH and Wi-Fi Coexistence
3.1 Which modes does Wi-Fi support when it coexists with ESP-BLE-MESH?
Currently only Wi-Fi station mode supports the coexistence.
3.2 Why is the Wi-Fi throughput so low when Wi-Fi and ESP-BLE-MESH coexist?
The ESP32-DevKitC board without PSRAM can run properly but the throughput of it is low since it has
no PSRAM. When Bluetooth and Wi-Fi coexist, the throughput of ESP32-DevKitC with PSRAM can
be stabilized to more than 1Mbps.
And some configurations in menuconfig shall be enabled to support PSRAM.
• ESP32-specific --> Support for external,SPI-connected RAM --> Try
to allocate memories of Wi-Fi and LWIP...
• Bluetooth --> Bluedroid Enable --> BT/BLE will first malloc the
memory from the PSRAM
• Bluetooth --> Bluedroid Enable --> Use dynamic memory allocation
in BT/BLE stack.
• Bluetooth --> Bluetooth controller --> BLE full scan feature
supported.
• Wi-Fi --> Software controls Wi-Fi/Bluetooth coexistence --> Wi-Fi
4. Fast Provisioning
4.1 Why is fast provisioning needed?

Normally when they are several unprovisioned devices, users can provision them one by one. But when
it comes to a large number of unprovisioned devices (e.g. 100), provisioning them one by one will take
huge amount of time. With fast provisioning, users can provision 100 unprovisioned devices in about 50
seconds.
4.2 Why EspBleMesh App would wait for a long time during fast provisioning?
After the App provisioned one Proxy node, it will disconnect from the App during fast provisioning, and
reconnect with the App when all the nodes are provisioned.
4.3 Why is the number of node addresses displayed in the App is more than that of existing node addresses?
Each time after a fast provisioning process, and before starting a new one, the node addresses in the App
should be cleared, otherwise the number of the node address will be incorrect.
4.4 What is the usage of the count value which was input in EspBleMesh App?
The count value is provided to the Proxy node which is provisioned by the App so as to determine when
to start Proxy advertising in advance.
4.5 When will Configuration Client Model of the node running fast_prov_server example start to work?
Configuration Client Model will start to work after the Temporary Provisioner functionality is enabled.

4.6 Will the Temporary Provisioner functionality be enabled all the time?
After the nodes receive messages used to turn on/off lights, all the nodes will disable its Temporary
Provisioner functionality and become nodes.
5. Log Help You can find meaning of errors or warnings when they appear at the bottom of ESP-BLE-MESH
stack.
5.1 What is the meaning of warning ran out of retransmit attempts?

When the node transmits a segmented message, and due to some reasons, the receiver doesn t receive the
complete message. Then the node will retransmit the message. When the retransmission count reaches
the maximum number, which is 4 currently, then this warning will appear.
5.2 What is the meaning of warning Duplicate found in Network Message Cache?
When the node receives a message, it will compare the message with the ones stored in the network
cache. If the same has been found in the cache, which means it has been received before, then the
message will be dropped.
5.3 What is the meaning of warning Incomplete timer expired?

When the node doesn t receive all the segments of a segmented message during a certain period (e.g.
10 seconds), then the Incomplete timer will expire and this warning will appear.
5.4 What is the meaning of warning No matching TX context for ack?

When the node receives a segment ack and it doesn t find any self-send segmented message related
with this ack, then this warning will appear.
5.5 What is the meaning of warning No free slots for new incoming segmented messages?
When the node has no space for receiving new segmented message, this warning will appear. Users can
make the space larger through the configuration CONFIG_BLE_MESH_RX_SEG_MSG_COUNT.
5.6 What is the meaning of error Model not bound to Appkey 0x0000
When the node sends messages with a model and the model has not been bound to the AppKey with
AppKey Index 0x000, then this error will appear.
5.7 What is the meaning of error Busy sending message to DST xxxx?
This error means client model of the node has transmitted a message to the target node and now is waiting
for a response, users can not send messages to the same node with the same unicast address. After the
corresponding response is received or timer is expired, then another message can be sent.
6. Example Help
6.1 How are the ESP-BLE-MESH callback functions classified?

• The API esp_ble_mesh_register_prov_callback() is used to register callback function used to
handle provisioning and networking related events.
• The API esp_ble_mesh_register_config_client_callback() is used to register callback
function used to handle Configuration Client Model related events.
• The API esp_ble_mesh_register_config_server_callback() is used to register callback
function used to handle Configuration Server Model related events.

• The API esp_ble_mesh_register_health_client_callback() is used to register callback

function used to handle Health Client Model related events.
• The API esp_ble_mesh_register_health_server_callback() is used to register callback
function used to handle Health Server Model related events.
• The API esp_ble_mesh_register_generic_client_callback() is used to register callback
function used to handle Generic Client Models related events.
• The API esp_ble_mesh_register_light_client_callback() is used to register callback
function used to handle Lighting Client Models related events.
• The API esp_ble_mesh_register_sensor_client_callback() is used to register callback
function used to handle Sensor Client Model related events.
• The API esp_ble_mesh_register_time_scene_client_callback() is used to register call-
back function used to handle Time and Scenes Client Models related events.
• The API esp_ble_mesh_register_custom_model_callback() is used to register callback
function used to handle vendor model and unrealized server models related events.
7. Others
7.1 How to print the message context?

The examples use ESP_LOG_BUFFER_HEX() to print the message context while the ESP-BLE-
MESH protocol stack uses bt_hex().
7.2 Which API can be used to restart ESP32?

The API esp_restart().
7.3 How to monitor the remaining space of the stack of a task?

The API vTaskList() can be used to print the remaining space of the task stack periodically.
7.4 How to change the level of log without changing the menuconfig output level?
The API esp_log_level_set() can be used to change the log output level rather than using menu-
config to change it.

ESP-BLE-MESH Terminology
Table 11: Table 1 ESP-BLE-MESH Terminology - Role

Term Official Definition Detailed Explanation
Unprovisioned
A device that is not a member of a mesh Examples: lighting devices, temperature control devices,
Device network is known as an unprovisioned manufacturing equipments and electric doors, etc.
device.
Node A node is a provisioned device. The role of unprovisioned device will change to node af-
ter being provisioned to ESP-BLE-MESH network. Nodes
(such as lighting devices, temperature control devices, man-
ufacturing equipments, and electric doors) are devices that
can send, receive, or relay messages in ESP-BLE-MESH net-
work, and they can optionally support one or more subnets.
Relay A node that supports the Relay feature Relay nodes can receive and resend ESP-BLE-MESH mes-
Node and has the Relay feature enabled is sages, so the messages can be transferred further. Users can
known as a Relay node. decide whether or not to enable forwarding function of nodes
according to nodes status. Messages can be relayed for mul-
tiple times, and each relay is considered as a hop . Mes-
sages can hop up to 126 times, which is enough for message
transmission in a wide area.
Proxy A node that supports the Proxy feature Proxy nodes receive messages from one bearer (it generally
Node and has the Proxy feature enabled is includes advertising bearer and GATT bearer) and resend
known as a Proxy node. it from another one. The purpose is to connect communi-
cation equipments that only support GATT bearer to ESP-
BLE-MESH network. Generally, mobile apps need a Proxy
node to access Mesh network. Without Proxy nodes, mobile
apps cannot communicate with members in Mesh network.
Friend A node that supports the Friend feature, Friend node, like the backup of Low Power node (LPN), can
Node has the Friend feature enabled, and has store messages that are sent to Low Power node and security
a friendship with a node that supports updates; the stored information will be transferred to Low
the Low Power feature is known as a Power node when Low Power node needs it. Low Power
Friend node. node must establish friendship with another node that sup-
ports the Friend Feature to reduce duty cycle of its receiver,
thus power consumption of Low Power node can be reduced.
Low Power node needs to find a Friend node to establish a
friendship with it. The process involved is called friendship
establishment . Cooperation between Low Power node and
Friend nodes enables Low Power node to schedule the use of
the radio, thus Low Power node can receive messages at an
appropriate or lower frequency without the need of keeping
listening. Low Power node will poll Friend node to see if
there is new message.
Low A node that supports the Low Power By polling, Low Power node gets information from Friend
Power feature and has a friendship with a node, such as messages, security updates, and etc.
Node node that supports the Friend feature is
known as a Low Power node.
ProvisionerA node that is capable of adding a de- The device that can provision unprovisioned devices is called
vice to a mesh network. a Provisioner. This process usually needs to be implemented
through an app that is typically provided by the product man-
ufacturer and can be used on a gateway, a smartphone, tablet
or other carriers.

Table 12: Table 2 ESP-BLE-MESH Terminology - Composition

State A value representing a condition of an Each node in a ESP-BLE-MESH network has an indepen-
element that is exposed by an element dent set of state values that indicate certain states of the de-
of a node. vice, like brightness, and color of lighting device. Change
of state value will lead to change of the physical state of de-
vices. For example, changing the on/off state of a device is
actually turning on/off the device.
Model A model defines the basic functionality A node may contain multiple models, and each model de-
of a node. fines basic functionalities of nodes, like the states needed by
the nodes, the messages controlling the states, and actions
resulted from messages handling. The function implementa-
tion of the nodes is based on models, which can be divided
into SIG Model and Vendor Model, with the former defined
by SIG and latter defined by users.
Element An addressable entity within a device. A node can contain one or more elements, with each having
a unicast address and one or more models, and the models
contained by the same element must not be the same.
Composition
The Composition Data state contains By reading the value of the Composition Data state, users can
Data information about a node, the elements know basic information of the node, such as the number of
State it includes, and the supported models. elements, and the models in each element. Provisioner gets
this message to further provision the device, such as config-
uring subscription address and publishing address of nodes.
Table 13: Table 3 ESP-BLE-MESH Terminology - Features

Low The ability to operate within a mesh Low Power feature reduces power consumption of nodes.
Power network at significantly reduced re- When a Low Power node is searching for a Friend node, and
Fea- ceiver duty cycles only in conjunction there are multiple Friend nodes nearby, it selects the most
ture with a node supporting the Friend fea- suitable Friend node through algorithm.
ture.
Friend The ability to help a node support- By enabling friend feature, the node can help to store infor-
Fea- ing the Low Power feature to operate mation for Low Power node. The nodes enabled with friend
ture by storing messages destined for those feature may cause more power and memory consumption.
nodes.
Relay The ability to receive and retransmit The relay feature enables ESP-BLE-MESH messages to hop
Fea- mesh messages over the advertising among nodes for multiple times, and the transmission dis-
ture bearer to enable larger networks. tance can exceed the range of direct radio transmission be-
tween two nodes, thereby covering the entire network. When
a node is enabled with the relay feature to relay messages, it
only relays the messages of its own subnet, and does not re-
lay the messages of other subnets. The data integrity will
not be considered when the node enabled with relay feature
relays segmented messages. The node would relay every seg-
mented message once it receives one rather than waiting for
the complete message.
Proxy The ability to receive and retransmit The purpose of the proxy feature is to allow nodes without an
Fea- mesh messages between GATT and ad- advertising bearer to access the ESP-BLE-MESH network.
ture vertising bearers. The proxy feature is typically used in nodes that need to con-
nect to mobile apps.

Table 14: Table 4 ESP-BLE-MESH Terminology - Provisioning

PB- PB-ADV is a provisioning bearer used PB-ADV transfers packets generated during the provision-
ADV to provision a device using Generic ing process over the advertising channels. This way can only
Provisioning PDUs over the advertising be used for provisioning when provisioner and unprovisioned
channels. device both support PB-ADV.
PB- PB-GATT is a provisioning bearer PB-GATT uses connection channels to transfer packets gen-
GATT used to provision a device using erated during the provisioning process. If an unprovisioned
Proxy PDUs to encapsulate Provision- device wants to be provisioned through this method, it needs
ing PDUs within the Mesh Provision- to implement the related Mesh Provisioning Service. Unpro-
ing Service. visioned devices which don t implement such service cannot
be provisioned into mesh network through PB-GATT bearer.
Provisioning
Provisioning is a process of adding an The process of provisioning turns the unprovisioned device
unprovisioned device to a mesh net- into a node , making it a member of the ESP-BLE-MESH
work, managed by a Provisioner. network.
Authentication
Authentication is a step during the pro- There are four authentication methods for unprovisioned de-
Method visioning of nodes. vices: Output OOB, Input OOB, Static OOB, and No OOB.
Input Input Out-of-Band For example, a Provisioner generates and displays a random
OOB number, and then prompts users to take appropriate actions
to input the random number into the unprovisioned device.
Taking lighting switch as an example, users can press the but-
ton for several times in a certain period of time to input the
random number displayed on the Provisioner. Authentica-
tion method of the Input OOB is similar to that of Output
OOB, but the role of the device is reversed.
Output Output Out-of-Band For example, an unprovisioned device will choose a random
OOB number and output the number in a way that is compatible
with its functionality. If the unprovisioned device is a bulb,
it can flash a specified number of times. If the unprovisioned
device has an LCD screen, the random number can display
as a multi-digit value. Users who start provisioning should
input the observed number to authenticate the unprovisioned
device.
Static Static Out-of-Band Authentication method of Static OOB: use Static OOB in-
OOB formation. Use 0 as Static OOB information if No OOB
information is needed. Use Static OOB information to au-
thenticate devices which are going through provisioning if
OOB information is needed.
No No Out-of-Band Authentication method of No OOB: Set the value of the
OOB Static OOB field to 0. Using this way is like not authenti-
cating the unprovisioned devices.

Table 15: Table 5 ESP-BLE-MESH Terminology - Address

UnassignedThis is a special address type, with a The addresses owned by elements which has not been config-
Ad- value of 0x0000. Its use indicates that ured yet or no address has been allocated are unassigned ad-
dress an Element has not yet been configured dresses. These elements will not be used for messages trans-
or had a Unicast Address assigned to it. fer because they have no fixed address. Unassigned address
is recommended to set as the value of the address before set-
ting the address of user code.
Unicast A unicast address is a unique address During provisioning, the Provisioner will assign a unicast ad-
Ad- allocated to each element. dress to each element of node within the life cycle of the
dress nodes in the network. A unicast address may appear in the
source/destination address field of a message. Messages sent
to a unicast address can only be processed by the element
that owns the unicast address.
Virtual A virtual address represents a set of Associated with specific UUID labels, a virtual address may
Ad- destination addresses. Each virtual serve as the publishing or subscription address of the model.
dress address logically represents a Label A UUID label is a 128-bit value associated with elements
UUID, which is a 128-bit value that of one or more nodes. For virtual addresses, the 15th and
does not have to be managed centrally. 14th bits are set to 1 and 0 respectively; bits from 13th to
0 are set to hash values (providing 16384 hash values). The
hash is a derivation of the Label UUID. To use subscribing
elements to check the full 128-bit UUID is very inefficient
while hash values provide a more efficient way to determine
which elements that which messages are finally sent to.
Group A group address is an address that is Group address is another kind of multicast address in the
Ad- programmed into zero or more ele- ESP-BLE-MESH network, which is usually used to group
dress ments nodes. A message sent to the all-proxies address shall be
processed by the primary element of all nodes that have
the proxy functionality enabled. A message sent to the all-
friends address shall be processed by the primary element of
all nodes that have the friend functionality enabled. A mes-
sage sent to the all-relays address shall be processed by the
primary element of all nodes that have the relay functional-
ity enabled. A message sent to the all-nodes address shall be
processed by the primary element of all nodes.

Table 16: Table 6 ESP-BLE-MESH Terminology - Security

Device There is also a device key, which is a The device key enables you to provision the devices, config-
Key special application key that is unique to ure the nodes. The device key is used to encrypt Configu-
(De- each node, is known only to the node ration Messages, i.e. the message transferred between the
vKey) and a Configuration Client, and is used Provisioner and the node when the device is configured.
to secure communications between the
node and a Configuration Client.
ApplicationApplication keys are used to secure Application key is used for decryption of application data
Key communications at the upper transport before delivering application data to application layer and
(App- layer. encryption of them during the delivery of application layer.
Key) Some nodes in the network have a specific purpose and
can restrict access to potentially sensitive data based on the
needs of the application. With specific application keys,
these nodes are associated with specific applications. Gener-
ally speaking, the fields using different application keys in-
clude security (access control of buildings, machine rooms
and CEO offices), lighting (plant, exterior building and side-
walks) and HVAC systems. Application keys are bound to
Network keys. This means application keys are only used in
a context of a Network key they are bound to. An application
key shall only be bound to a single Network key.
Master The master security material is derived The corresponding friendship messages encrypted with the
Secu- from the network key (NetKey) and can friendship security material: 1. Friend Poll, 2. Friend Up-
rity be used by other nodes in the same net- date, 3. Friend Subscription List, add/delete/confirm, 4. The
Mate- work. Messages encrypted with master Stored Messages sent by friend nodes to Low Power node.
rial security material can be decoded by any The corresponding friendship messages encrypted with the
node in the same network. master security material: 1. Friend Clear, 2. Friend Clear
Confirm. Based on the setup of the applications, the mes-
sages sent from the Low Power node to the friend nodes will
be encrypted with the friendship security material or mas-
ter security material, with the former being used by the mes-
sages transmitted between Low Power node and friend nodes
and the latter being used by other network messages.
Table 17: Table 7 ESP-BLE-MESH Terminology - Message

Reassembly
Segmentation and reassembly (SAR) is The lower transport layer will automatically segment the
/ Seg- a method of communication network, message whose size is too big. The receiving end will return
menta- which is divided into small units before a response message, and the transmitting end will send the
tion transmitting packets and reassembled data packet again that the receiving end does not receive ac-
in a proper order at the communication cording to the response message. This is automatically com-
receiving end. pleted by the lower transport layer. Unsegmented messages
have at most 15 bytes, of which 4 bytes are transMIC, so the
remaining is 11 bytes; in the case of segmentation, there are
12 valid bytes in the first several packets, and 8 in the last
one. Special case: A shorter packet requires mandatory seg-
mentation from lower transport layer, in which case the valid
byte is 8 bytes.
Unacknowledged
There are two types of messages: Un- Based on the whether or not the receiving end needs to send
/ Ac- acknowledged or Acknowledged the response message, the messages sent are divided into two
knowl- kinds. The sending end should set the maximum number of
edged retransmission.

Table 18: Table 8 ESP-BLE-MESH Terminology - Foundation Models

Configuration
This model is used to represent a mesh The node must contain the Configuration Server Model,
Server network configuration of a device. which is responsible for maintaining configuration-related
Model states. The states that Configuration Server Model maintains
include: NetKey List, AppKey List, Model to AppKey List,
Node Identity, Key Refresh Phase, Heartbeat Publish, Heart-
beat Subscription, Network Transmit, Relay Retransmit etc.
Configuration
The model is used to represent an ele- The Configuration Client Model uses messages to control the
Client ment that can control and monitor the state maintained by the Configuration Server Model. The
Model configuration of a node. Provisioner must contain the Configuration Client Model,
with which the configuration messages, like Configuration
Composition Data Get can be sent.
Health This model is used to represent a mesh The Health Server Model is primarily used by devices to
Server network diagnostics of a device. check their states and see if there is an error. The states
Model maintained by Health Server model include: Current Fault,
Registered Fault, Health Period, and Attention Timer.
Health The model is used to represent an ele- The Health Client Model uses messages to control the state
Client ment that can control and monitor the maintained by the Health Server Model. The model can get
Model health of a node. the self-test information of other nodes through the message
Health Fault Get .
Table 19: Table 9 ESP-BLE-MESH Terminology - Network Management

Key This procedure is used when the secu- Key Refresh Procedure is used to update network key and
Re- rity of one or more network keys and/or application key of ESP-BLE-MESH network. Key Refresh
fresh one or more of the application keys has Procedure is used when the security of one or more network
proce- been compromised or could be com- keys and/or one or more application keys is threatened or
dure promised. potentially threatened. Keys are usually updated after some
nodes in the network are removed.
IV A node can also use an IV Update pro- The IV Update procedure is used to update the value of ESP-
(Ini- cedure to signal to peer nodes that it is BLE-MESH network s IV Index. This value is related to
tiali- updating the IV Index. the random number required for message encryption. To en-
sation sure that the value of the random number is not repeated, this
Vec- value is periodically incremented. IV Index is a 32-bit value
tor) and a shared network resource. For example, all nodes in a
Update mesh network share the same IV Index value. Starting from
Proce- 0x00000000, the IV Index increments during the IV Update
dure procedure and maintained by a specific process, ensuring the
IV Index shared in the mesh network is the same. This can be
done when the node believes that it has the risk of exhaust-
ing its sequence number, or when it determines that another
node is nearly exhausting its sequence number. Note: The
update time must not be less than 96 hours. It can be trig-
gered when a secure network beacon is received, or when the
node determines that its sequence number is greater than a
certain value.
For more terms, please see: ESP-BLE-MESH Glossary of Terms.
Bluetooth SIG Documentation
• BLE Mesh Core Specification

• BLE Mesh Model Specification
• An Intro to Bluetooth Mesh Part 1 / Part 2

• The Fundamental Concepts of Bluetooth Mesh Networking, Part 1 / Part 2

• Bluetooth Mesh Networking: Friendship
• Management of Devices in a Bluetooth Mesh Network
• Bluetooth Mesh Security Overview
• Provisioning a Bluetooth Mesh Network Part 1 / Part 2
4.9 ESP-WIFI-MESH
This guide provides information regarding the ESP-WIFI-MESH protocol. Please see the ESP-WIFI-MESH API
Reference for more information about API usage.
4.9.1 Overview
ESP-WIFI-MESH is a networking protocol built atop the Wi-Fi protocol. ESP-WIFI-MESH allows numerous de-
vices (henceforth referred to as nodes) spread over a large physical area (both indoors and outdoors) to be intercon-
nected under a single WLAN (Wireless Local-Area Network). ESP-WIFI-MESH is self-organizing and self-healing
meaning the network can be built and maintained autonomously.
The ESP-WIFI-MESH guide is split into the following sections:
1. Introduction
2. ESP-WIFI-MESH Concepts
3. Building a Network
4. Managing a Network
5. Data Transmission
6. Channel Switching
7. Performance
8. Further Notes
4.9.2 Introduction
Fig. 16: Traditional Wi-Fi Network Architecture
A traditional infrastructure Wi-Fi network is a point-to-multipoint network where a single central node known as the
access point (AP) is directly connected to all other nodes known as stations. The AP is responsible for arbitrating and

forwarding transmissions between the stations. Some APs also relay transmissions to/from an external IP network
via a router. Traditional infrastructure Wi-Fi networks suffer the disadvantage of limited coverage area due to the
requirement that every station must be in range to directly connect with the AP. Furthermore, traditional Wi-Fi
networks are susceptible to overloading as the maximum number of stations permitted in the network is limited by
the capacity of the AP.
Fig. 17: ESP-WIFI-MESH Network Architecture
ESP-WIFI-MESH differs from traditional infrastructure Wi-Fi networks in that nodes are not required to connect to
a central node. Instead, nodes are permitted to connect with neighboring nodes. Nodes are mutually responsible for
relaying each others transmissions. This allows an ESP-WIFI-MESH network to have much greater coverage area as
nodes can still achieve interconnectivity without needing to be in range of the central node. Likewise, ESP-WIFI-
MESH is also less susceptible to overloading as the number of nodes permitted on the network is no longer limited
by a single central node.
4.9.3 ESP-WIFI-MESH Concepts

Terminology
Term Description
Node Any device that is or can be part of an ESP-WIFI-MESH network
Root Node The top node in the network
Child Node A node X is a child node when it is connected to another node Y where the connection
makes node X more distant from the root node than node Y (in terms of number of
connections).
Parent Node The converse notion of a child node
Descendant Node Any node reachable by repeated proceeding from parent to child
Sibling Nodes Nodes that share the same parent node
Connection A traditional Wi-Fi association between an AP and a station. A node in ESP-WIFI-
MESH will use its station interface to associate with the softAP interface of another
node, thus forming a connection. The connection process includes the authentication
and association processes in Wi-Fi.
Upstream Connection The connection from a node to its parent node
Downstream Connection The connection from a node to one of its child nodes
Wireless Hop The portion of the path between source and destination nodes that corresponds to a
single wireless connection. A data packet that traverses a single connection is known
as single-hop whereas traversing multiple connections is known as multi-hop.
Subnetwork A subnetwork is subdivision of an ESP-WIFI-MESH network which consists of a
node and all of its descendant nodes. Therefore the subnetwork of the root node
consists of all nodes in an ESP-WIFI-MESH network.
MAC Address Media Access Control Address used to uniquely identify each node or router within
an ESP-WIFI-MESH network.
DS Distribution System (External IP Network)
Tree Topology
ESP-WIFI-MESH is built atop the infrastructure Wi-Fi protocol and can be thought of as a networking protocol that
combines many individual Wi-Fi networks into a single WLAN. In Wi-Fi, stations are limited to a single connection
with an AP (upstream connection) at any time, whilst an AP can be simultaneously connected to multiple stations
(downstream connections). However ESP-WIFI-MESH allows nodes to simultaneously act as a station and an AP.
Therefore a node in ESP-WIFI-MESH can have multiple downstream connections using its softAP interface,
whilst simultaneously having a single upstream connection using its station interface. This naturally results in a
tree network topology with a parent-child hierarchy consisting of multiple layers.
ESP-WIFI-MESH is a multiple hop (multi-hop) network meaning nodes can transmit packets to other nodes in the
network through one or more wireless hops. Therefore, nodes in ESP-WIFI-MESH not only transmit their own
packets, but simultaneously serve as relays for other nodes. Provided that a path exists between any two nodes
on the physical layer (via one or more wireless hops), any pair of nodes within an ESP-WIFI-MESH network can
communicate.
Note: The size (total number of nodes) in an ESP-WIFI-MESH network is dependent on the maximum number of
layers permitted in the network, and the maximum number of downstream connections each node can have. Both of
these variables can be configured to limit the size of the network.
Node Types
Root Node: The root node is the top node in the network and serves as the only interface between the ESP-WIFI-
MESH network and an external IP network. The root node is connected to a conventional Wi-Fi router and relays
packets to/from the external IP network to nodes within the ESP-WIFI-MESH network. There can only be one
root node within an ESP-WIFI-MESH network and the root node s upstream connection may only be with the
router. Referring to the diagram above, node A is the root node of the network.

Fig. 18: ESP-WIFI-MESH Tree Topology
Fig. 19: ESP-WIFI-MESH Node Types

Leaf Nodes: A leaf node is a node that is not permitted to have any child nodes (no downstream connections).
Therefore a leaf node can only transmit or receive its own packets, but cannot forward the packets of other nodes.
If a node is situated on the network s maximum permitted layer, it will be assigned as a leaf node. This prevents
the node from forming any downstream connections thus ensuring the network does not add an extra layer. Some
nodes without a softAP interface (station only) will also be assigned as leaf nodes due to the requirement of a softAP
interface for any downstream connections. Referring to the diagram above, nodes L/M/N are situated on the networks
maximum permitted layer hence have been assigned as leaf nodes .
Intermediate Parent Nodes: Connected nodes that are neither the root node or a leaf node are intermediate parent
nodes. An intermediate parent node must have a single upstream connection (a single parent node), but can have
zero to multiple downstream connections (zero to multiple child nodes). Therefore an intermediate parent node
can transmit and receive packets, but also forward packets sent from its upstream and downstream connections.
Referring to the diagram above, nodes B to J are intermediate parent nodes. Intermediate parent nodes without
downstream connections such as nodes E/F/G/I/J are not equivalent to leaf nodes as they are still permitted to
form downstream connections in the future.
Idle Nodes: Nodes that have yet to join the network are assigned as idle nodes. Idle nodes will attempt to form
an upstream connection with an intermediate parent node or attempt to become the root node under the correct
circumstances (see Automatic Root Node Selection). Referring to the diagram above, nodes K and O are idle nodes.
Beacon Frames & RSSI Thresholding
Every node in ESP-WIFI-MESH that is able to form downstream connections (i.e. has a softAP interface) will
periodically transmit Wi-Fi beacon frames. A node uses beacon frames to allow other nodes to detect its presence
and know of its status. Idle nodes will listen for beacon frames to generate a list of potential parent nodes, one of
which the idle node will form an upstream connection with. ESP-WIFI-MESH uses the Vendor Information Element
to store metadata such as:
• Node Type (Root, Intermediate Parent, Leaf, Idle)
• Current layer of Node
• Maximum number of layers permitted in the network
• Current number of child nodes
• Maximum number of downstream connections to accept
The signal strength of a potential upstream connection is represented by RSSI (Received Signal Strength Indication)
of the beacon frames of the potential parent node. To prevent nodes from forming a weak upstream connection,
ESP-WIFI-MESH implements an RSSI threshold mechanism for beacon frames. If a node detects a beacon frame
with an RSSI below a preconfigured threshold, the transmitting node will be disregarded when forming an upstream
connection.
Panel A of the illustration above demonstrates how the RSSI threshold affects the number of parent node candidates
an idle node has.
Panel B of the illustration above demonstrates how an RF shielding object can lower the RSSI of a potential parent
node. Due to the RF shielding object, the area in which the RSSI of node X is above the threshold is significantly
reduced. This causes the idle node to disregard node X even though node X is physically adjacent. The idle node will
instead form an upstream connection with the physically distant node Y due to a stronger RSSI.
Note: Nodes technically still receive all beacon frames on the MAC layer. The RSSI threshold is an ESP-WIFI-
MESH feature that simply filters out all received beacon frames that are below the preconfigured threshold.
Preferred Parent Node
When an idle node has multiple parent nodes candidates (potential parent nodes), the idle node will form an upstream
connection with the preferred parent node. The preferred parent node is determined based on the following criteria:
• Which layer the parent node candidate is situated on
• The number of downstream connections (child nodes) the parent node candidate currently has

Fig. 20: Effects of RSSI Thresholding
The selection of the preferred parent node will always prioritize the parent node candidate on the shallowest layer
of the network (including the root node). This helps minimize the total number of layers in an ESP-WIFI-MESH
network when upstream connections are formed. For example, given a second layer node and a third layer node, the
second layer node will always be preferred.
If there are multiple parent node candidates within the same layer, the parent node candidate with the least child
nodes will be preferred. This criteria has the effect of balancing the number of downstream connections amongst
nodes of the same layer.
Fig. 21: Preferred Parent Node Selection
Panel A of the illustration above demonstrates an example of how the idle node G selects a preferred parent node
given the five parent node candidates B/C/D/E/F. Nodes on the shallowest layer are preferred, hence nodes B/C are
prioritized since they are second layer nodes whereas nodes D/E/F are on the third layer. Node C is selected as the
preferred parent node due it having fewer downstream connections (fewer child nodes) compared to node B.
Panel B of the illustration above demonstrates the case where the root node is within range of the idle node G. In

other words, the root node s beacon frames are above the RSSI threshold when received by node G. The root node is
always the shallowest node in an ESP-WIFI-MESH network hence is always the preferred parent node given multiple
parent node candidates.
Note: Users may also define their own algorithm for selecting a preferred parent node, or force a node to only
connect with a specific parent node (see the Mesh Manual Networking Example).
Routing Tables
Each node within an ESP-WIFI-MESH network will maintain its individual routing table used to correctly route ESP-
WIFI-MESH packets (see ESP-WIFI-MESH Packet) to the correct destination node. The routing table of a particular
node will consist of the MAC addresses of all nodes within the particular node s subnetwork (including the
MAC address of the particular node itself). Each routing table is internally partitioned into multiple subtables with
each subtable corresponding to the subnetwork of each child node.
Fig. 22: ESP-WIFI-MESH Routing Tables Example
Using the diagram above as an example, the routing table of node B would consist of the MAC addresses of nodes B
to I (i.e. equivalent to the subnetwork of node B). Node B s routing table is internally partitioned into two subtables
containing of nodes C to F and nodes G to I (i.e. equivalent to the subnetworks of nodes C and G respectively).
ESP-WIFI-MESH utilizes routing tables to determine whether an ESP-WIFI-MESH packet should be for-
warded upstream or downstream based on the following rules.
1. If the packet s destination MAC address is within the current node s routing table and is not the current node,
select the subtable that contains the destination MAC address and forward the data packet downstream to the child
node corresponding to the subtable.
2. If the destination MAC address is not within the current node s routing table, forward the data packet upstream
to the current node s parent node. Doing so repeatedly will result in the packet arriving at the root node where the
routing table should contain all nodes within the network.
Note: Users can call esp_mesh_get_routing_table() to obtain a node s routing ta-

ble, or esp_mesh_get_routing_table_size() to obtain the size of a node s routing table.
esp_mesh_get_subnet_nodes_list() can be used to obtain the corresponding subtable of a spe-
cific child node. Likewise esp_mesh_get_subnet_nodes_num() can be used to obtain the size of the

subtable.
4.9.4 Building a Network
General Process
Warning: Before the ESP-WIFI-MESH network building process can begin, certain parts of the configuration
must be uniform across each node in the network (see mesh_cfg_t). Each node must be configured with the
same Mesh Network ID, router configuration, and softAP configuration.
An ESP-WIFI-MESH network building process involves selecting a root node, then forming downstream connections
layer by layer until all nodes have joined the network. The exact layout of the network can be dependent on factors
such as root node selection, parent node selection, and asynchronous power-on reset. However, the ESP-WIFI-MESH
network building process can be generalized into the following steps:
Fig. 23: ESP-WIFI-MESH Network Building Process
1. Root Node Selection The root node can be designated during configuration (see section on User Designated
Root Node), or dynamically elected based on the signal strength between each node and the router (see Automatic
Root Node Selection). Once selected, the root node will connect with the router and begin allowing downstream
connections to form. Referring to the figure above, node A is selected to be the root node hence node A forms an
upstream connection with the router.
2. Second Layer Formation Once the root node has connected to the router, idle nodes in range of the root
node will begin connecting with the root node thereby forming the second layer of the network. Once connected,
the second layer nodes become intermediate parent nodes (assuming maximum permitted layers > 2) hence the next
layer to form. Referring to the figure above, nodes B to D are in range of the root node. Therefore nodes B to D form
upstream connections with the root node and become intermediate parent nodes.
3. Formation of remaining layers The remaining idle nodes will connect with intermediate parent nodes within
range thereby forming a new layer in the network. Once connected, the idles nodes become intermediate parent node
or leaf nodes depending on the networks maximum permitted layers. This step is repeated until there are no more idle

nodes within the network or until the maximum permitted layer of the network has been reached. Referring to the
figure above, nodes E/F/G connect with nodes B/C/D respectively and become intermediate parent nodes themselves.
4. Limiting Tree Depth To prevent the network from exceeding the maximum permitted number of layers, nodes
on the maximum layer will automatically become leaf nodes once connected. This prevents any other idle node
from connecting with the leaf node thereby prevent a new layer form forming. However if an idle node has no
other potential parent node, it will remain idle indefinitely. Referring to the figure above, the network s number of
maximum permitted layers is set to four. Therefore when node H connects, it becomes a leaf node to prevent any
downstream connections from forming.
Automatic Root Node Selection
The automatic selection of a root node involves an election process amongst all idle nodes based on their signal
strengths with the router. Each idle node will transmit their MAC addresses and router RSSI values via Wi-Fi beacon
frames. The MAC address is used to uniquely identify each node in the network whilst the router RSSI is used
to indicate a node s signal strength with reference to the router.
Each node will then simultaneously scan for the beacon frames from other idle nodes. If a node detects a beacon
frame with a stronger router RSSI, the node will begin transmitting the contents of that beacon frame (i.e. voting for
the node with the stronger router RSSI). The process of transmission and scanning will repeat for a preconfigured
minimum number of iterations (10 iterations by default) and result in the beacon frame with the strongest router RSSI
being propagated throughout the network.
After all iterations, each node will individually check for its vote percentage (number of votes/number of
nodes participating in election) to determine if it should become the root node. If a node has a
vote percentage larger than a preconfigured threshold (90% by default), the node will become a root node.
The following diagram demonstrates how an ESP-WIFI-MESH network is built when the root node is automatically
selected.
Fig. 24: Root Node Election Example
1. On power-on reset, each node begins transmitting beacon frames consisting of their own MAC addresses and their
router RSSIs.
2. Over multiple iterations of transmission and scanning, the beacon frame with the strongest router RSSI is propa-
gated throughout the network. Node C has the strongest router RSSI (-10 dB) hence its beacon frame is propagated

throughout the network. All nodes participating in the election vote for node C thus giving node C a vote percentage
of 100%. Therefore node C becomes a root node and connects with the router.
3. Once Node C has connected with the router, nodes A/B/D/E connectwith node C as it is the preferred parent node
(i.e. the shallowest node). Nodes A/B/D/E form the second layer of the network.
4. Node F and G connect with nodes D and E respectively and the network building process is complete.
Note: The minimum number of iterations for the election process can be configured using
esp_mesh_set_attempts(). Users should adjust the number of iterations based on the number of
nodes within the network (i.e. the larger the network the larger number of scan iterations required).
Warning: Vote percentage threshold can also be configured using

esp_mesh_set_vote_percentage(). Setting a low vote percentage threshold can result in two
or more nodes becoming root nodes within the same ESP-WIFI-MESH network leading to the building of
multiple networks. If such is the case, ESP-WIFI-MESH has internal mechanisms to autonomously resolve the
root node conflict. The networks of the multiple root nodes will be combined into a single network with a single
root node. However, root node conflicts where two or more root nodes have the same router SSID but different
router BSSID are not handled.
User Designated Root Node
The root node can also be designated by user which will entail the designated root node to directly connect with the
router and forgo the election process. When a root node is designated, all other nodes within the network must also
forgo the election process to prevent the occurrence of a root node conflict. The following diagram demonstrates how
an ESP-WIFI-MESH network is built when the root node is designated by the user.
Fig. 25: Root Node Designation Example (Root Node = A, Max Layers = 4)
1. Node A is designated the root node by the user therefore directly connects with the router. All other nodes forgo
the election process.
2. Nodes C/D connect with node A as their preferred parent node. Both nodes form the second layer of the network.

3. Likewise, nodes B/E connect with node C, and node F connects with node D. Nodes B/E/F form the third layer
of the network.
4. Node G connects with node E, forming the fourth layer of the network. However the maximum permitted number
of layers in this network is configured as four, therefore node G becomes a leaf node to prevent any new layers from
forming.
Note: When designating a root node, the root node should call esp_mesh_set_parent() in order to directly
connect with the router. Likewise, all other nodes should call esp_mesh_fix_root() to forgo the election
process.
Parent Node Selection
By default, ESP-WIFI-MESH is self organizing meaning that each node will autonomously select which potential
parent node to form an upstream connection with. The autonomously selected parent node is known as the preferred
parent node. The criteria used for selecting the preferred parent node is designed to reduce the number of layers
in the ESP-WIFI-MESH network and to balance the number of downstream connections between potential parent
nodes (see section on Preferred Parent Node).
However ESP-WIFI-MESH also allows users to disable self-organizing behavior which will allow users to define their
own criteria for parent node selection, or to configure nodes to have designated parent nodes (see the Mesh Manual
Networking Example).
Asynchronous Power-on Reset
ESP-WIFI-MESH network building can be affected by the order in which nodes power-on. If certain nodes within
the network power-on asynchronously (i.e. separated by several minutes), the final structure of the network could
differ from the ideal case where all nodes are powered on synchronously. Nodes that are delayed in powering
on will adhere to the following rules:
Rule 1: If a root node already exists in the network, the delayed node will not attempt to elect a new root node, even
if it has a stronger RSSI with the router. The delayed node will instead join the network like any other idle node
by connecting with a preferred parent node. If the delayed node is the designated root node, all other nodes in the
network will remain idle until the delayed node powers-on.
Rule 2: If a delayed node forms an upstream connection and becomes an intermediate parent node, it may also
become the new preferred parent of other nodes (i.e. being a shallower node). This will cause the other nodes to
switch their upstream connections to connect with the delayed node (see Parent Node Switching).
Rule 3: If an idle node has a designated parent node which is delayed in powering-on, the idle node will not attempt to
form any upstream connections in the absence of its designated parent node. The idle node will remain idle indefinitely
until its designated parent node powers-on.
The following example demonstrates the effects of asynchronous power-on with regards to network building.
1. Nodes A/C/D/F/G/H are powered-on synchronously and begin the root node election process by broadcasting their
MAC addresses and router RSSIs. Node A is elected as the root node as it has the strongest RSSI.
2. Once node A becomes the root node, the remaining nodes begin forming upstream connections layer by layer with
their preferred parent nodes. The result is a network with five layers.
3. Node B/E are delayed in powering-on but neither attempt to become the root node even though they have stronger
router RSSIs (-20 dB and -10 dB) compared to node A. Instead both delayed nodes form upstream connections
with their preferred parent nodes A and C respectively. Both nodes B/E become intermediate parent nodes after
connecting.
4. Nodes D/G switch their upstream connections as node B is the new preferred parent node due to it being on a
shallower layer (second layer node). Due to the switch, the resultant network has three layers instead of the original
five layers.

Fig. 26: Network Building with Asynchronous Power On Example

Synchronous Power-On: Had all nodes powered-on synchronously, node E would have become the root node as it
has the strongest router RSSI (-10 dB). This would result in a significantly different network layout compared to the
network formed under the conditions of asynchronous power-on. However the synchronous power-on network
layout can still be reached if the user manually switches the root node (see esp_mesh_waive_root()).
Note: Differences in parent node selection caused by asynchronous power-on are autonomously corrected for to
some extent in ESP-WIFI-MESH (see Parent Node Switching)
Loop-back Avoidance, Detection, and Handling
A loop-back is the situation where a particular node forms an upstream connection with one of its descendant nodes
(a node within the particular node s subnetwork). This results in a circular connection path thereby breaking the
tree topology. ESP-WIFI-MESH prevents loop-back during parent selection by excluding nodes already present in
the selecting node s routing table (see Routing Tables) thus prevents a particular node from attempting to connect
to any node within its subnetwork.
In the event that a loop-back occurs, ESP-WIFI-MESH utilizes a path verification mechanism and energy transfer
mechanism to detect the loop-back occurrence. The parent node of the upstream connection that caused the loop-
back will then inform the child node of the loop-back and initiate a disconnection.
4.9.5 Managing a Network
ESP-WIFI-MESH is a self healing network meaning it can detect and correct for failures in network routing.
Failures occur when a parent node with one or more child nodes breaks down, or when the connection between a
parent node and its child nodes becomes unstable. Child nodes in ESP-WIFI-MESH will autonomously select a new
parent node and form an upstream connection with it to maintain network interconnectivity. ESP-WIFI-MESH can
handle both Root Node Failures and Intermediate Parent Node Failures.
Root Node Failure
If the root node breaks down, the nodes connected with it (second layer nodes) will promptly detect the failure of
the root node. The second layer nodes will initially attempt to reconnect with the root node. However after multiple
failed attempts, the second layer nodes will initialize a new round of root node election. The second layer node with
the strongest router RSSI will be elected as the new root node whilst the remaining second layer nodes will form
an upstream connection with the new root node (or a neighboring parent node if not in range).
If the root node and multiple downstream layers simultaneously break down (e.g. root node, second layer, and
third layer), the shallowest layer that is still functioning will initialize the root node election. The following example
illustrates an example of self healing from a root node break down.
1. Node C is the root node of the network. Nodes A/B/D/E are second layer nodes connected to node C.
2. Node C breaks down. After multiple failed attempts to reconnect, the second layer nodes begin the election process
by broadcasting their router RSSIs. Node B has the strongest router RSSI.
3. Node B is elected as the root node and begins accepting downstream connections. The remaining second layer
nodes A/D/E form upstream connections with node B thus the network is healed and can continue operating normally.
Note: If a designated root node breaks down, the remaining nodes will not autonomously attempt to elect a new
root node as an election process will never be attempted whilst a designated root node is used.

Fig. 27: Self Healing From Root Node Failure
Intermediate Parent Node Failure
If an intermediate parent node breaks down, the disconnected child nodes will initially attempt to reconnect with the
parent node. After multiple failed attempts to reconnect, each child node will begin to scan for potential parent nodes
(see Beacon Frames & RSSI Thresholding).
If other potential parent nodes are available, each child node will individually select a new preferred parent node (see
Preferred Parent Node) and form an upstream connection with it. If there are no other potential parent nodes for a
particular child node, it will remain idle indefinitely.
The following diagram illustrates an example of self healing from an Intermediate Parent Node break down.
Fig. 28: Self Healing From Intermediate Parent Node Failure
1. The following branch of the network consists of nodes A to G.

2. Node C breaks down. Nodes F/G detect the break down and attempt to reconnect with node C. After multiple
failed attempts to reconnect, nodes F/G begin to select a new preferred parent node.
3. Node G is out of range from any other parent node hence remains idle for the time being. Node F is in range of
nodes B/E, however node B is selected as it is the shallower node. Node F becomes an intermediate parent node after
connecting with Node B thus node G can connect with node F. The network is healed, however the network routing
as been affected and an extra layer has been added.
Note: If a child node has a designated parent node that breaks down, the child node will make no attempt to connect
with a new parent node. The child node will remain idle indefinitely.

Root Node Switching
ESP-WIFI-MESH does not automatically switch the root node unless the root node breaks down. Even if the root
node s router RSSI degrades to the point of disconnection, the root node will remain unchanged. Root node switching
is the act of explicitly starting a new election such that a node with a stronger router RSSI will be elected as the new
root node. This can be a useful method of adapting to degrading root node performance.
To trigger a root node switch, the current root node must explicitly call esp_mesh_waive_root() to trigger a
new election. The current root node will signal all nodes within the network to begin transmitting and scanning for
beacon frames (see Automatic Root Node Selection) whilst remaining connected to the network (i.e. not idle). If
another node receives more votes than the current root node, a root node switch will be initiated. The root node will
remain unchanged otherwise.
A newly elected root node sends a switch request to the current root node which in turn will respond with an
acknowledgment signifying both nodes are ready to switch. Once the acknowledgment is received, the newly elected
root node will disconnect from its parent and promptly form an upstream connection with the router thereby becoming
the new root node of the network. The previous root node will disconnect from the router whilst maintaining all of
its downstream connections and enter the idle state. The previous root node will then begin scanning for potential
parent nodes and selecting a preferred parent.
The following diagram illustrates an example of a root node switch.
Fig. 29: Root Node Switch Example
1. Node C is the current root node but has degraded signal strength with the router (-85db). The node C triggers a
new election and all nodes begin transmitting and scanning for beacon frames whilst still being connected.
2. After multiple rounds of transmission and scanning, node B is elected as the new root node. Node B sends node
C a switch request and node C responds with an acknowledgment.
3. Node B disconnects from its parent and connects with the router becoming the network s new root node. Node C
disconnects from the router, enters the idle state, and begins scanning for and selecting a new preferred parent node.
Node C maintains all its downstream connections throughout this process.
4. Node C selects node B as its preferred parent node, forms an upstream connection, and becomes a second layer
node. The network layout is similar after the switch as node C still maintains the same subnetwork. However each
node in node C s subnetwork has been placed one layer deeper as a result of the switch. Parent Node Switching may
adjust the network layout afterwards if any nodes have a new preferred parent node as a result of the root node switch.

Note: Root node switching must require an election hence is only supported when using a self-organized ESP-WIFI-
MESH network. In other words, root node switching cannot occur if a designated root node is used.
Parent Node Switching
Parent Node Switching entails a child node switching its upstream connection to another parent node of a shallower
layer. Parent Node Switching occurs autonomously meaning that a child node will change its upstream connection
automatically if a potential parent node of a shallower layer becomes available (i.e. due to a Asynchronous Power-on
Reset).
All potential parent nodes periodically transmit beacon frames (see Beacon Frames & RSSI Thresholding) allowing
for a child node to scan for the availability of a shallower parent node. Due to parent node switching, a self-organized
ESP-WIFI-MESH network can dynamically adjust its network layout to ensure each connection has a good RSSI and
that the number of layers in the network is minimized.
4.9.6 Data Transmission
ESP-WIFI-MESH Packet
ESP-WIFI-MESH network data transmissions use ESP-WIFI-MESH packets. ESP-WIFI-MESH packets are en-
tirely contained within the frame body of a Wi-Fi data frame. A multi-hop data transmission in an ESP-WIFI-
MESH network will involve a single ESP-WIFI-MESH packet being carried over each wireless hop by a different
Wi-Fi data frame.
The following diagram shows the structure of an ESP-WIFI-MESH packet and its relation with a Wi-Fi data frame.
Fig. 30: ESP-WIFI-MESH Packet
The header of an ESP-WIFI-MESH packet contains the MAC addresses of the source and destination nodes.
The options field contains information pertaining to the special types of ESP-WIFI-MESH packets such as a
group transmission or a packet originating from the external IP network (see MESH_OPT_SEND_GROUP and
MESH_OPT_RECV_DS_ADDR).
The payload of an ESP-WIFI-MESH packet contains the actual application data. This data can be raw binary data,
or encoded under an application layer protocol such as HTTP, MQTT, and JSON (see mesh_proto_t).
Note: When sending an ESP-WIFI-MESH packet to the external IP network, the destination address field of
the header will contain the IP address and port of the target server rather than the MAC address of a node (see
mesh_addr_t). Furthermore the root node will handle the formation of the outgoing TCP/IP packet.
Group Control & Multicasting
Multicasting is a feature that allows a single ESP-WIFI-MESH packet to be transmitted simultaneously to mul-
tiple nodes within the network. Multicasting in ESP-WIFI-MESH can be achieved by either specifying a list

of target nodes, or specifying a preconfigured group of nodes. Both methods of multicasting are called via
esp_mesh_send().
To multicast by specifying a list of target nodes, users must first set the ESP-WIFI-MESH packet s destina-
tion address to the Multicast-Group Address (01:00:5E:xx:xx:xx). This signifies that the ESP-WIFI-
MESH packet is a multicast packet with a group of addresses, and that the address should be obtained from the
header options. Users must then list the MAC addresses of the target nodes as options (see mesh_opt_t and
MESH_OPT_SEND_GROUP). This method of multicasting requires no prior setup but can incur a large amount of
overhead data as each target node s MAC address must be listed in the options field of the header.
Multicasting by group allows a ESP-WIFI-MESH packet to be transmitted to a preconfigured group of nodes. Each
grouping is identified by a unique ID, and a node can be placed into a group via esp_mesh_set_group_id().
Multicasting to a group involves setting the destination address of the ESP-WIFI-MESH packet to the target group ID.
Furthermore, the MESH_DATA_GROUP flag must set. Using groups to multicast incurs less overhead, but requires
nodes to previously added into groups.
Note: During a multicast, all nodes within the network still receive the ESP-WIFI-MESH packet on the MAC layer.
However, nodes not included in the MAC address list or the target group will simply filter out the packet.
Broadcasting
Broadcasting is a feature that allows a single ESP-WIFI-MESH packet to be transmitted simultaneously to all nodes
within the network. Each node essentially forwards a broadcast packet to all of its upstream and downstream con-
nections such that the packet propagates throughout the network as quickly as possible. However, ESP-WIFI-MESH
utilizes the following methods to avoid wasting bandwidth during a broadcast.
1. When an intermediate parent node receives a broadcast packet from its parent, it will forward the packet to each
of its child nodes whilst storing a copy of the packet for itself.
2. When an intermediate parent node is the source node of the broadcast, it will transmit the broadcast packet
upstream to is parent node and downstream to each of its child nodes.
3. When an intermediate parent node receives a broadcast packet from one of its child nodes, it will forward the
packet to its parent node and each of its remaining child nodes whilst storing a copy of the packet for itself.
4. When a leaf node is the source node of a broadcast, it will directly transmit the packet to its parent node.
5. When the root node is the source node of a broadcast, the root node will transmit the packet to all of its child
nodes.
6. When the root node receives a broadcast packet from one of its child nodes, it will forward the packet to each of
its remaining child nodes whilst storing a copy of the packet for itself.
7. When a node receives a broadcast packet with a source address matching its own MAC address, the node will
discard the broadcast packet.
8. When an intermediate parent node receives a broadcast packet from its parent node which was originally transmitted
from one of its child nodes, it will discard the broadcast packet
Upstream Flow Control
ESP-WIFI-MESH relies on parent nodes to control the upstream data flow of their immediate child nodes. To prevent
a parent node s message buffer from overflowing due to an overload of upstream transmissions, a parent node will
allocate a quota for upstream transmissions known as a receiving window for each of its child nodes. Each child
node must apply for a receiving window before it is permitted to transmit upstream. The size of a receiving
window can be dynamically adjusted. An upstream transmission from a child node to the parent node consists of the
following steps:
1. Before each transmission, the child node sends a window request to its parent node. The window request consists
of a sequence number which corresponds to the child node s data packet that is pending transmission.

2. The parent node receives the window request and compares the sequence number with the sequence number of the
previous packet sent by the child node. The comparison is used to calculate the size of the receiving window which
is transmitted back to the child node.
3. The child node transmits the data packet in accordance with the window size specified by the parent node. If the
child node depletes its receiving window, it must obtain another receiving windows by sending a request before it is
permitted to continue transmitting.
Note: ESP-WIFI-MESH does not support any downstream flow control.
Warning: Due to Parent Node Switching, packet loss may occur during upstream transmissions.
Due to the fact that the root node acts as the sole interface to an external IP network, it is critical that downstream
nodes are aware of the root node s connection status with the external IP network. Failing to do so can lead to
nodes attempting to pass data upstream to the root node whilst it is disconnected from the IP network. This results
in unnecessary transmissions and packet loss. ESP-WIFI-MESH address this issue by providing a mechanism to
stabilize the throughput of outgoing data based on the connection status between the root node and the external
IP network. The root node can broadcast its external IP network connection status to all other nodes by calling
esp_mesh_post_toDS_state().
Bi-Directional Data Stream
The following diagram illustrates the various network layers involved in an ESP-WIFI-MESH Bidirectional Data
Stream.
Fig. 31: ESP-WIFI-MESH Bidirectional Data Stream
Due to the use of Routing Tables, ESP-WIFI-MESH is able to handle pack forwarding entirely on the mesh
layer. A TCP/IP layer is only required on the root node when it transmits/receives a packet to/from an external IP
network.
4.9.7 Channel Switching
Background
In traditional Wi-Fi networks, channels are predetermined frequency ranges. In an infrastructure basic service set
(BSS), the serving AP and its connected stations must be on the same operating channels (1 to 14) in which beacons
are transmitted. Physically adjacent BSS (Basic Service Sets) operating on the same channel can lead to interference
and degraded performance.

In order to allow a BSS adapt to changing physical layer conditions and maintain performance, Wi-Fi contains mech-
anisms for network channel switching. A network channel switch is an attempt to move a BSS to a new operating
channel whilst minimizing disruption to the BSS during this process. However it should be recognized that a channel
switch may be unsuccessful in moving all stations to the new operating channel.
In an infrastructure Wi-Fi network, network channel switches are triggered by the AP with the aim of having the
AP and all connected stations synchronously switch to a new channel. Network channel switching is implemented
by embedding a Channel Switch Announcement (CSA) element within the AP s periodically transmitted beacon
frames. The CSA element is used to advertise to all connected stations regarding an upcoming network channel
switch and will be included in multiple beacon frames up until the switch occurs.
A CSA element contains information regarding the New Channel Number and a Channel Switch Count which
indicates the number of beacon frame intervals (TBTTs) remaining until the network channel switch occurs. There-
fore, the Channel Switch Count is decremented every beacon frame and allows connected stations to synchronize
their channel switch with the AP.
ESP-WIFI-MESH Network Channel Switching
ESP-WIFI-MESH Network Channel Switching also utilize beacon frames that contain a CSA element. However,
being a multi-hop network makes the switching process in ESP-WIFI-MESH is more complex due to the fact that a
beacon frame might not be able to reach all nodes within the network (i.e. in a single hop). Therefore, an ESP-WIFI-
MESH network relies on nodes to forward the CSA element so that it is propagated throughout the network.
When an intermediate parent node with one or more child nodes receives a beacon frame containing a CSA, the node
will forward the CSA element by including the element in its next transmitted beacon frame (i.e. with the same New
Channel Number and Channel Switch Count). Given that all nodes within an ESP-WIFI-MESH network receive
the same CSA, the nodes can synchronize their channel switches using the Channel Switch Count, albeit with a short
delay due to CSA element forwarding.
An ESP-WIFI-MESH network channel switch can be triggered by either the router or the root node.
Root Node Triggered A root node triggered channel switch can only occur when the ESP-WIFI-MESH
network is not connected to a router. By calling esp_mesh_switch_channel(), the root node will set an
initial Channel Switch Count value and begin including a CSA element in its beacon frames. Each CSA element is
then received by second layer nodes, and forwarded downstream in the their own beacon frames.
Router Triggered When an ESP-WIFI-MESH network is connected to a router, the entire network must use the
same channel as the router. Therefore, the root node will not be permitted to trigger a channel switch when it
is connected to a router.
When the root node receives beacon frame containing a CSA element from the router, the root node will set Channel
Switch Count value in the CSA element to a custom value before forwarding it downstream via beacon frames.
It will also decrement the Channel Switch Count of subsequent CSA elements relative to the custom value. This
custom value can be based on factors such as the number of network layers, the current number of nodes etc.
The setting the Channel Switch Count value to a custom value is due to the fact that the ESP-WIFI-MESH network and
its router may have a different and varying beacon intervals. Therefore, the Channel Switch Count value provided by
the router is irrelevant to an ESP-WIFI-MESH network. By using a custom value, nodes within the ESP-WIFI-MESH
network are able to switch channels synchronously relative to the ESP-WIFI-MESH network s beacon interval.
However, this will also result in the ESP-WIFI-MESH network s channel switch being unsynchronized with the
channel switch of the router and its connected stations.
Impact of Network Channel Switching
• Due to the ESP-WIFI-MESH network channel switch being unsynchronized with the router s channel switch, there w
– The ESP-WIFI-MESH network s channel switch time is dependent on the ESP-WIFI-MESH net-
work s beacon interval and the root node s custom Channel Switch Count value.

– The channel discrepancy prevents any data exchange between the root node and the router during
that ESP-WIFI-MESH network s switch.
– In the ESP-WIFI-MESH network, the root node and intermediate parent nodes will request their
connected child nodes to stop transmissions until the channel switch takes place by setting the Chan-
nel Switch Mode field in the CSA element to 1.
– Frequent router triggered network channel switches can degrade the ESP-WIFI-MESH network
s performance. Note that this can be caused by the ESP-WIFI-MESH network itself (e.g. due
to wireless medium contention with ESP-WIFI-MESH network). If this is the case, users should
disable the automatic channel switching on the router and use a specified channel instead.
• When there is a temporary channel discrepancy, the root node remains technically connected to the router.
– Disconnection occurs after the root node fails to receive any beacon frames or probe responses from
the router over a fixed number of router beacon intervals.
– Upon disconnection, the root node will automatically re-scan all channels for the presence of a router.
• If the root node is unable to receive any of the router s CSA beacon frames (e.g. due to short switch time given by the
– After the router switches channels, the root node will no longer be able to receive the router s
beacon frames and probe responses and result in a disconnection after a fixed number of beacon
intervals.
– The root node will re-scan all channels for the router after disconnection.
– The root node will maintain downstream connections throughout this process.
Note: Although ESP-WIFI-MESH network channel switching aims to move all nodes within the network to a new
operating channel, it should be recognized that a channel switch might not successfully move all nodes (e.g. due to
reasons such as node failures).
Channel and Router Switching Configuration
ESP-WIFI-MESH allows for autonomous channel switching to be enabled/disabled via configuration. Likewise,
autonomous router switching (i.e. when a root node autonomously connects to another router) can also be en-
abled/disabled by configuration. Autonomous channel switching and router switching is dependent on the following
configuration parameters and run-time conditions.
Allow Channel Switch: This parameter is set via the allow_channel_switch field of the mesh_cfg_t
structure and permits an ESP-WIFI-MESH network to dynamically switch channels when set.
Preset Channel: An ESP-WIFI-MESH network can have a preset channel by setting the channel field of the
mesh_cfg_t structure to the desired channel number. If this field is unset, the allow_channel_switch
parameter is overridden such that channel switches are always permitted.
Allow Router Switch: This parameter is set via the allow_router_switch field of the mesh_router_t
and permits an ESP-WIFI-MESH to dynamically switch to a different router when set.
Preset Router BSSID: An ESP-WIFI-MESH network can have a preset router by setting the bssid field
of the mesh_router_t structure to the BSSID of the desired router. If this field is unset, the al-
low_router_switch parameter is overridden such that router switches are always permitted.
Root Node Present: The presence of a root node will can also affect whether or a channel or router switch is
permitted.
The following table illustrates how the different combinations of parameters/conditions affect whether channel
switching and/or router switching is permitted. Note that X represents a don t care for the parameter.

Preset Chan- Allow Channel Preset Router Allow Router Root Node Permitted
nel Switch BSSID Switch Present Switches
N X N X X Channel and
Router
N X Y N X Channel Only
N X Y Y X Channel and
Router
Y Y N X X Channel and
Router
Y N N X N Router Only
Y N N X Y Channel and
Router
Y Y Y N X Channel Only
Y N Y N N N
Y N Y N Y Channel Only
Y Y Y Y X Channel and
Router
Y N Y Y N Router Only
Y N Y Y Y Channel and
Router
4.9.8 Performance
The performance of an ESP-WIFI-MESH network can be evaluated based on multiple metrics such as the following:
Network Building Time: The amount of time taken to build an ESP-WIFI-MESH network from scratch.
Healing Time: The amount of time taken for the network to detect a node break down and carry out appropriate
actions to heal the network (such as generating a new root node or forming new connections).
Per-hop latency: The latency of data transmission over one wireless hop. In other words, the time taken to transmit
a data packet from a parent node to a child node or vice versa.
Network Node Capacity: The total number of nodes the ESP-WIFI-MESH network can simultaneously support.
This number is determined by the maximum number of downstream connections a node can accept and the maximum
number of layers permissible in the network.
The following table lists the common performance figures of an ESP-WIFI-MESH network:
• Network Building Time: < 60 seconds
• Healing time:
– Root node break down: < 10 seconds
– Child node break down: < 5 seconds
• Per-hop latency: 10 to 30 milliseconds
Note: The following test conditions were used to generate the performance figures above.
• Number of test devices: 100
• Maximum Downstream Connections to Accept: 6
• Maximum Permissible Layers: 6
Note: Throughput depends on packet error rate and hop count.
Note: The throughput of root node s access to the external IP network is directly affected by the number of nodes
in the ESP-WIFI-MESH network and the bandwidth of the router.

Note: The performance figures can vary greatly between installations based on network configuration and operating
environment.
4.9.9 Further Notes
• Data transmission uses Wi-Fi WPA2-PSK encryption

• Mesh networking IE uses AES encryption
Router and internet icon made by Smashicons from www.flaticon.com
4.10 Core Dump
4.10.1 Overview
ESP-IDF provides support to generate core dumps on unrecoverable software errors. This useful technique allows
post-mortem analysis of software state at the moment of failure. Upon the crash system enters panic state, prints some
information and halts or reboots depending configuration. User can choose to generate core dump in order to analyse
the reason of failure on PC later on. Core dump contains snapshots of all tasks in the system at the moment of failure.
Snapshots include tasks control blocks (TCB) and stacks. So it is possible to find out what task, at what instruction
(line of code) and what callstack of that task lead to the crash. It is also possible dumping variables content on demand
if previously attributed accordingly. ESP-IDF provides special script espcoredump.py to help users to retrieve and
analyse core dumps. This tool provides two commands for core dumps analysis:
• info_corefile - prints crashed task s registers, callstack, list of available tasks in the system, memory
regions and contents of memory stored in core dump (TCBs and stacks)
• dbg_corefile - creates core dump ELF file and runs GDB debug session with this file. User can examine
memory, variables and tasks states manually. Note that since not all memory is saved in core dump only values
of variables allocated on stack will be meaningful
For more information about core dump internals see the - Core dump internals
4.10.2 Configurations
There are a number of core dump related configuration options which user can choose in project configuration menu
(idf.py menuconfig).
Core dump data destination (Components -> Core dump -> Data destination)
• Save core dump to Flash (Flash)
• Print core dump to UART (UART)
• Disable core dump generation (None)
Core dump data format (Components -> Core dump -> Core dump data format)
• ELF format (Executable and Linkable Format file for core dump)
• Binary format (Basic binary format for core dump)
The ELF format contains extended features and allow to save more information about broken tasks
and crashed software but it requires more space in the flash memory. This format of core dump is
recommended for new software designs and is flexible enough to extend saved information for future
revisions.
The Binary format is kept for compatibility standpoint, it uses less space in the memory to keep data and
provides better performance.
Core dump data integrity check (Components -> Core dump -> Core dump data integrity check)
• Use CRC32 for core dump integrity verification

• Use SHA256 for core dump integrity verification (only work in ELF format)
The CRC32 option provides better calculation performance and consumes less memory for storage.
The SHA256 hash algorithm provides greater probability of detecting corruption than a CRC32 with
multiple bit errors.
Maximum number of tasks snapshots in core dump (Components -> Core dump -> Maximum number of
tasks)
Delay before core dump is printed to UART (Components -> Core dump -> Delay before print to UART)
The value is in ms.
Handling of UART core dumps in IDF Monitor (Components -> Core dump -> Delay before print to UART)
The value is base64 encoded.
• Decode and show summary (info_corefile)
• Don t decode
4.10.3 Save core dump to flash
When this option is selected core dumps are saved to special partition on flash. When using default partition table
files which are provided with ESP-IDF it automatically allocates necessary space on flash, But if user wants to use its
own layout file together with core dump feature it should define separate partition for core dump as it is shown below:
# Name, Type, SubType, Offset, Size

# Note: if you have increased the bootloader size, make sure to update the offsets␣
,→to avoid overlap
nvs, data, nvs, 0x9000, 0x6000

phy_init, data, phy, 0xf000, 0x1000
factory, app, factory, 0x10000, 1M
coredump, data, coredump,, 64K
There are no special requirements for partition name. It can be chosen according to the user application needs, but
partition type should be data and sub-type should be coredump . Also when choosing partition size note that
core dump data structure introduces constant overhead of 20 bytes and per-task overhead of 12 bytes. This overhead
does not include size of TCB and stack for every task. So partition size should be at least 20 + max tasks number x
(12 + TCB size + max task stack size) bytes.
The example of generic command to analyze core dump from flash is: espcoredump.py -p </path/to/
serial/port> info_corefile </path/to/program/elf/file> or espcoredump.py -p </
path/to/serial/port> dbg_corefile </path/to/program/elf/file>
4.10.4 Print core dump to UART
When this option is selected base64-encoded core dumps are printed on UART upon system panic. In this case user
should save core dump text body to some file manually and then run the following command: espcoredump.py
--chip <target_chip_type> info_corefile -t b64 -c </path/to/saved/base64/
text> </path/to/program/elf/file> or espcoredump.py --chip <target_chip_type>
dbg_corefile -t b64 -c </path/to/saved/base64/text> </path/to/program/elf/
file>
Base64-encoded body of core dump will be between the following header and footer:
================= CORE DUMP START =================

<body of base64-encoded core dump, save it to file on disk>
================= CORE DUMP END ===================
The CORE DUMP START and CORE DUMP END lines must not be included in core dump text file.

4.10.5 ROM Functions in Backtraces
It is possible situation that at the moment of crash some tasks or/and crashed task itself have one or more ROM
functions in their callstacks. Since ROM is not part of the program ELF it will be impossible for GDB to parse such
callstacks, because it tries to analyse functions prologues to accomplish that. In that case callstack printing will be
broken with error message at the first ROM function. To overcome this issue you can use ROM ELF provided by
Espressif (https://dl.espressif.com/dl/esp32_rom.elf) and pass it to espcoredump.py .
4.10.6 Dumping variables on demand
Sometimes you want to read the last value of a variable to understand the root cause of a crash. Core dump supports
retrieving variable data over GDB by attributing special notations declared variables.
Supported notations and RAM regions
• COREDUMP_DRAM_ATTR places variable into DRAM area which will be included into dump.
• COREDUMP_RTC_ATTR places variable into RTC area which will be included into dump.
• COREDUMP_RTC_FAST_ATTR places variable into RTC_FAST area which will be included into dump.
Example
1. In Project Configuration Menu, enable COREDUMP TO FLASH, then save and exit.
2. In your project, create a global variable in DRAM area as such as:
// uint8_t global_var;
COREDUMP_DRAM_ATTR uint8_t global_var;
3. In main application, set the variable to any value and assert(0) to cause a crash.
global_var = 25;
assert(0);
4. Build, flash and run the application on a target device and wait for the dumping information.
5. Run the command below to start core dumping in GDB, where PORT is the device USB port:
espcoredump.py -p PORT dbg_corefile <path/to/elf>
6. In GDB shell, type p global_var to get the variable content:
(gdb) p global_var
$1 = 25 '\031'
4.10.7 Running espcoredump.py
Generic command syntax: espcoredump.py [options] command [args]

Script Options
chip {auto,esp32,esp32s2,esp32c3} Target chip type. Default value is auto
--port PORT, -p PORT Serial port device. Either chip or port need to be
specified to determine the port when you have multi-target
connected at the same time.
--baud BAUD, -b BAUD Serial port baud rate used when flashing/reading
--gdb-timeout-sec GDB_TIMEOUT_SEC Overwrite the default internal delay
for gdb responses
Commands dbg_corefile Starts GDB debugging session with specified corefile
info_corefile Print core dump info from file

Command Arguments
--debug DEBUG, -d DEBUG Log level (0..3)
--gdb GDB, -g GDB Path to gdb
--core CORE, -c CORE Path to core dump file (if skipped core dump will be
read from flash)
core-format {b64,elf,raw}, -t {b64,elf,raw} File specified with -c is an ELF ( elf ), raw
(raw) or base64-encoded (b64) binary
--off OFF, -o OFF Offset of coredump partition in flash (type idf.py partition-
table to see).
--save-core SAVE_CORE, -s SAVE_CORE Save core to file. Otherwise tem-
porary core file will be deleted. Does not work with -c
--rom-elf ROM_ELF, -r ROM_ELF Path to ROM ELF file. Will use <tar-
get>_rom.elf if not specified
--print-mem, -m Print memory dump. Only valid when info_corefile.
<prog> Path to program ELF file.
4.11 Event Handling

Several ESP-IDF components use events to inform application about state changes, such as connection or disconnec-
tion. This document gives an overview of these event mechanisms.
4.11.1 Wi-Fi, Ethernet, and IP Events
Before the introduction of esp_event library, events from Wi-Fi driver, Ethernet driver, and TCP/IP stack were
dispatched using the so-called legacy event loop. The following sections explain each of the methods.
esp_event Library Event Loop
esp_event library is designed to supersede the legacy event loop for the purposes of event handling in ESP-IDF. In
the legacy event loop, all possible event types and event data structures had to be defined in system_event_id_t
enumeration and system_event_info_t union, which made it impossible to send custom events to the event
loop, and use the event loop for other kinds of events (e.g. Mesh). Legacy event loop also supported only one event
handler function, therefore application components could not handle some of Wi-Fi or IP events themselves, and
required application to forward these events from its event handler function.
See esp_event library API reference for general information on using this library. Wi-Fi, Ethernet, and IP events are
sent to the default event loop provided by this library.
Legacy Event Loop
This event loop implementation is started using esp_event_loop_init() function. Application typically sup-
plies an event handler, a function with the following signature:
esp_err_t event_handler(void *ctx, system_event_t *event)

{
}
Both the pointer to event handler function, and an arbitrary context pointer are passed to
esp_event_loop_init().
When Wi-Fi, Ethernet, or IP stack generate an event, this event is sent to a high-priority event task via
a queue. Application-provided event handler function is called in the context of this task. Event task stack
size and event queue size can be adjusted using CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE and CON-
FIG_ESP_SYSTEM_EVENT_QUEUE_SIZE options, respectively.

Event handler receives a pointer to the event structure (system_event_t) which describes current event. This
structure follows a tagged union pattern: event_id member indicates the type of event, and event_info member
is a union of description structures. Application event handler will typically use switch(event->event_id)
to handle different kinds of events.
If application event handler needs to relay the event to some other task, it is important to note that event pointer
passed to the event handler is a pointer to temporary structure. To pass the event to another task, application has to
make a copy of the entire structure.
Event IDs and Corresponding Data Structures
Event ID (legacy event ID) Event data structure

Wi-Fi
WIFI_EVENT_WIFI_READY (SYSTEM_EVENT_WIFI_READY) n/a
WIFI_EVENT_SCAN_DONE (SYSTEM_EVENT_SCAN_DONE) wifi_event_sta_scan_done_t
WIFI_EVENT_STA_START (SYSTEM_EVENT_STA_START) n/a
WIFI_EVENT_STA_STOP (SYSTEM_EVENT_STA_STOP) n/a
WIFI_EVENT_STA_CONNECTED (SYS- wifi_event_sta_connected_t
TEM_EVENT_STA_CONNECTED)
WIFI_EVENT_STA_DISCONNECTED (SYS- wifi_event_sta_disconnected_t
TEM_EVENT_STA_DISCONNECTED)
WIFI_EVENT_STA_AUTHMODE_CHANGE (SYS- wifi_event_sta_authmode_change_t
TEM_EVENT_STA_AUTHMODE_CHANGE)
WIFI_EVENT_STA_WPS_ER_SUCCESS (SYS- n/a
TEM_EVENT_STA_WPS_ER_SUCCESS)
WIFI_EVENT_STA_WPS_ER_FAILED (SYS- wifi_event_sta_wps_fail_reason_t
TEM_EVENT_STA_WPS_ER_FAILED)
WIFI_EVENT_STA_WPS_ER_TIMEOUT (SYS- n/a
TEM_EVENT_STA_WPS_ER_TIMEOUT)
WIFI_EVENT_STA_WPS_ER_PIN (SYS- wifi_event_sta_wps_er_pin_t
TEM_EVENT_STA_WPS_ER_PIN)
WIFI_EVENT_AP_START (SYSTEM_EVENT_AP_START) n/a
WIFI_EVENT_AP_STOP (SYSTEM_EVENT_AP_STOP) n/a
WIFI_EVENT_AP_STACONNECTED (SYS- wifi_event_ap_staconnected_t
TEM_EVENT_AP_STACONNECTED)
WIFI_EVENT_AP_STADISCONNECTED (SYS- wifi_event_ap_stadisconnected_t
TEM_EVENT_AP_STADISCONNECTED)
WIFI_EVENT_AP_PROBEREQRECVED (SYS- wifi_event_ap_probe_req_rx_t
TEM_EVENT_AP_PROBEREQRECVED)
Ethernet
ETHERNET_EVENT_START (SYSTEM_EVENT_ETH_START) n/a
ETHERNET_EVENT_STOP (SYSTEM_EVENT_ETH_STOP) n/a
ETHERNET_EVENT_CONNECTED (SYS- n/a
TEM_EVENT_ETH_CONNECTED)
ETHERNET_EVENT_DISCONNECTED (SYS- n/a
TEM_EVENT_ETH_DISCONNECTED)
IP
IP_EVENT_STA_GOT_IP (SYSTEM_EVENT_STA_GOT_IP) ip_event_got_ip_t
IP_EVENT_STA_LOST_IP (SYSTEM_EVENT_STA_LOST_IP) n/a
IP_EVENT_AP_STAIPASSIGNED (SYS- n/a
TEM_EVENT_AP_STAIPASSIGNED)
IP_EVENT_GOT_IP6 (SYSTEM_EVENT_GOT_IP6) ip_event_got_ip6_t
IP_EVENT_ETH_GOT_IP (SYSTEM_EVENT_ETH_GOT_IP) ip_event_got_ip_t
IP_EVENT_ETH_LOST_IP (SYSTEM_EVENT_ETH_LOST_IP) n/a

4.11.2 Mesh Events
ESP-WIFI-MESH uses a system similar to the Legacy Event Loop to deliver events to the application. See System
Events for details.
4.11.3 Bluetooth Events
Various modules of the Bluetooth stack deliver events to applications via dedicated callback functions. Callback
functions receive the event type (enumerated value) and event data (union of structures for each event type). The
following list gives the registration API name, event enumeration type, and event parameters type.
• BLE GAP: esp_ble_gap_register_callback(), esp_gap_ble_cb_event_t,
esp_ble_gap_cb_param_t.
• BT GAP: esp_bt_gap_register_callback(), esp_bt_gap_cb_event_t,
esp_bt_gap_cb_param_t.
• GATTC: esp_ble_gattc_register_callback(), esp_bt_gattc_cb_event_t,
esp_bt_gattc_cb_param_t.
• GATTS: esp_ble_gatts_register_callback(), esp_bt_gatts_cb_event_t,
esp_bt_gatts_cb_param_t.
• SPP: esp_spp_register_callback(), esp_spp_cb_event_t, esp_spp_cb_param_t.
• Blufi: esp_blufi_register_callbacks(), esp_blufi_cb_event_t,
esp_blufi_cb_param_t.
• A2DP: esp_a2d_register_callback(), esp_a2d_cb_event_t, esp_a2d_cb_param_t.
• AVRC: esp_avrc_ct_register_callback(), esp_avrc_ct_cb_event_t,
esp_avrc_ct_cb_param_t.
• HFP Client: esp_hf_client_register_callback(), esp_hf_client_cb_event_t,
esp_hf_client_cb_param_t.
• HFP AG: esp_hf_ag_register_callback(), esp_hf_ag_cb_event_t,
esp_hf_ag_cb_param_t.
4.12 Support for External RAM
4.12.1 Introduction
ESP32 has a few hundred kilobytes of internal RAM, residing on the same die as the rest of the chip components. It
can be insufficient for some purposes, so ESP32 has the ability to also use up to 4 MB of external SPI RAM memory.
The external memory is incorporated in the memory map and, with certain restrictions, is usable in the same way as
internal data RAM.
4.12.2 Hardware
ESP32 supports SPI PSRAM (Psuedostatic RAM) connected in parallel with the SPI flash chip. While ESP32 is
capable of supporting several types of RAM chips, ESP-IDF currently only supports Espressif branded PSRAM chips
(e.g., ESP-PSRAM32, ESP-PSRAM64, etc).
Note: Some PSRAM chips are 1.8 V devices and some are 3.3 V. The working voltage of the PSRAM chip must
match the working voltage of the flash component. Consult the datasheet for your PSRAM chip and ESP32 device
to find out the working voltages. For a 1.8 V PSRAM chip, make sure to either set the MTDI pin to a high signal
level on bootup, or program ESP32 eFuses to always use the VDD_SIO level of 1.8 V. Not doing this can damage
the PSRAM and/or flash chip.

Note: Espressif produces both modules and system-in-package chips that integrate compatible PSRAM and flash
and are ready to mount on a product PCB. Consult the Espressif website for more information.
For specific details about connecting the SoC or module pins to an external PSRAM chip, consult the SoC or module
datasheet.
4.12.3 Configuring External RAM
ESP-IDF fully supports the use of external RAM in applications. Once the external RAM is initialized at startup,
ESP-IDF can be configured to integrate the external RAM in several ways:
• Integrate RAM into the ESP32 Memory Map
• Add External RAM to the Capability Allocator
• Provide External RAM via malloc() (default)
• Allow .bss Segment to be Placed in External Memory
• Allow .noinit Segment to be Placed in External Memory
Integrate RAM into the ESP32 Memory Map
Select this option by choosing Integrate RAM into memory map from CONFIG_SPIRAM_USE.
This is the most basic option for external SPI RAM integration. Most likely, you will need another, more advanced
option.
During the ESP-IDF startup, external RAM is mapped into the data address space, starting at address 0x3F800000
(byte-accessible). The length of this region is the same as the SPI RAM size (up to the limit of 4 MB).
Applications can manually place data in external memory by creating pointers to this region. So if an application uses
external memory, it is responsible for all management of the external SPI RAM: coordinating buffer usage, preventing
corruption, etc.
Add External RAM to the Capability Allocator
Select this option by choosing Make RAM allocatable using heap_caps_malloc( , MALLOC_CAP_SPIRAM)
from CONFIG_SPIRAM_USE.
When enabled, memory is mapped to address 0x3F800000 and also added to the capabilities-based heap memory
allocator using MALLOC_CAP_SPIRAM.
To allocate memory from external RAM, a program should call heap_caps_malloc(size, MAL-
LOC_CAP_SPIRAM). After use, this memory can be freed by calling the normal free() function.
Provide External RAM via malloc()
Select this option by choosing Make RAM allocatable using malloc() as well from CONFIG_SPIRAM_USE. This
is the default option.
In this case, memory is added to the capability allocator as described for the previous option. However, it is also
added to the pool of RAM that can be returned by the standard malloc() function.
This allows any application to use the external RAM without having to rewrite the code to use
heap_caps_malloc(..., MALLOC_CAP_SPIRAM).
An additional configuration item, CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL, can be used to set the size
threshold when a single allocation should prefer external memory:
• When allocating a size less than the threshold, the allocator will try internal memory first.
• When allocating a size equal to or larger than the threshold, the allocator will try external memory first.

If a suitable block of preferred internal/external memory is not available, the allocator will try the other type of
memory.
Because some buffers can only be allocated in internal memory, a second configuration item CON-
FIG_SPIRAM_MALLOC_RESERVE_INTERNAL defines a pool of internal memory which is reserved for only ex-
plicitly internal allocations (such as memory for DMA use). Regular malloc() will not allocate from this pool.
The MALLOC_CAP_DMA and MALLOC_CAP_INTERNAL flags can be used to allocate memory from this pool.
Allow .bss Segment to be Placed in External Memory
Enable this option by checking CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY. This configuration

setting is independent of the other three.
If enabled, a region of the address space starting from 0x3F800000 will be used to store zero-initialized data (BSS
segment) from the lwIP, net80211, libpp, and bluedroid ESP-IDF libraries.
Additional data can be moved from the internal BSS segment to external RAM by applying the macro
EXT_RAM_ATTR to any static declaration (which is not initialized to a non-zero value).
It is also possible to place the BSS section of a component or a library to external RAM using linker fragment scheme
extram_bss.
This option reduces the internal static memory used by the BSS segment.
Remaining external RAM can also be added to the capability heap allocator using the method shown above.
Allow .noinit Segment to be Placed in External Memory
Enable this option by checking CONFIG_SPIRAM_ALLOW_NOINIT_SEG_EXTERNAL_MEMORY. If enabled, a re-

gion of the address space provided in external RAM will be used to store non-initialized data. The values placed in
this segment will not be initialized or modified even during startup or restart.
By applying the macro EXT_RAM_NOINIT_ATTR, data could be moved from the internal NOINIT segment to
external RAM. Remaining external RAM can still be added to the capability heap allocator using the method shown
above, Add External RAM to the Capability Allocator.
4.12.4 Restrictions
External RAM use has the following restrictions:

• When flash cache is disabled (for example, if the flash is being written to), the external RAM also becomes
inaccessible; any reads from or writes to it will lead to an illegal cache access exception. This is also the reason
why ESP-IDF does not by default allocate any task stacks in external RAM (see below).
• External RAM cannot be used as a place to store DMA transaction descriptors or as a buffer for a DMA transfer
to read from or write into. Any buffers that will be used in combination with DMA must be allocated using
heap_caps_malloc(size, MALLOC_CAP_DMA) and can be freed using a standard free() call.
• External RAM uses the same cache region as the external flash. This means that frequently accessed variables
in external RAM can be read and modified almost as quickly as in internal ram. However, when accessing
large chunks of data (>32 KB), the cache can be insufficient, and speeds will fall back to the access speed of
the external RAM. Moreover, accessing large chunks of data can push out cached flash, possibly making
the execution of code slower afterwards.
• In general, external RAM cannot be used as task stack memory. Due to this, xTaskCreate() and similar
functions will always allocate internal memory for stack and task TCBs, and functions such as xTaskCre-
ateStatic() will check if the buffers passed are internal.
The option CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY can be used to place task stacks into external
memory. In these cases xTaskCreateStatic() must be used to specify a task stack buffer allocated from
external memory, otherwise task stacks will still be allocated from internal memory.

4.12.5 Failure to initialize
By default, failure to initialize external RAM will cause the ESP-IDF startup to abort. This can be
disabled by enabling the config item CONFIG_SPIRAM_IGNORE_NOTFOUND.
If CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY is enabled, the option to ignore failure
is not available as the linker will have assigned symbols to external memory addresses at link time.
• Regarding stacks in PSRAM: For tasks not calling on code in ROM in any way, directly or indirectly, the
menuconfig option CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY will eliminate the check in
xTaskCreateStatic, allowing a task s stack to be in external RAM. Using this is not advised, however.
• When used at 80 MHz clock speed, external RAM must also occupy either the HSPI or VSPI bus. Select which
SPI host will be used by CONFIG_SPIRAM_OCCUPY_SPI_HOST.
4.12.6 Chip revisions
There are some issues with certain revisions of ESP32 that have repercussions for use with external RAM. The issues
are documented in the ESP32 ECO document. In particular, ESP-IDF handles the bugs mentioned in the following
ways:
ESP32 rev v0
ESP-IDF has no workaround for the bugs in this revision of silicon, and it cannot be used to map external PSRAM
into ESP32 s main memory map.
ESP32 rev v1
The bugs in this revision of silicon cause issues if certain sequences of machine instructions operate on external
memory. (ESP32 ECO 3.2). As a workaround, the GCC compiler received the flag -mfix-esp32-psram-
cache-issue to filter these sequences and only output the code that can safely be executed. Enable this flag by
checking CONFIG_SPIRAM_CACHE_WORKAROUND.
Aside from linking to a recompiled version of Newlib with the additional flag, ESP-IDF also does the following:
• Avoids using some ROM functions
• Allocates static memory for the WiFi stack
ESP32 rev v3
ESP32 revision 3 ( ECO V3 ) fixes the PSRAM cache issue found in rev. 1. When CONFIG_ESP32_REV_MIN
option is set to rev. 3, compiler workarounds related to PSRAM will be disabled. For more information about ESP32
ECO V3, see ESP32 ECO V3 User Guide.
4.13 Fatal Errors
4.13.1 Overview
In certain situations, execution of the program can not be continued in a well defined way. In ESP-IDF, these situations
include:
• CPU Exceptions: Illegal Instruction, Load/Store Alignment Error, Load/Store Prohibited error, Double Ex-
ception.
• System level checks and safeguards:
– Interrupt watchdog timeout
– Task watchdog timeout (only fatal if CONFIG_ESP_TASK_WDT_PANIC is set)

– Cache access error

– Brownout detection event
– Stack overflow
– Stack smashing protection check
– Heap integrity check
– Undefined behavior sanitizer (UBSAN) checks
• Failed assertions, via assert, configASSERT and similar macros.
This guide explains the procedure used in ESP-IDF for handling these errors, and provides suggestions on trou-
bleshooting the errors.
4.13.2 Panic Handler
Every error cause listed in the Overview will be handled by panic handler.
Panic handler will start by printing the cause of the error to the console. For CPU exceptions, the message will be
similar to
Guru Meditation Error: Core 0 panic'ed (IllegalInstruction). Exception was␣
,→unhandled.
For some of the system level checks (interrupt watchdog, cache access error), the message will be similar to
Guru Meditation Error: Core 0 panic'ed (Cache disabled but cached memory␣
,→region accessed). Exception was unhandled.
In all cases, error cause will be printed in parentheses. See Guru Meditation Errors for a list of possible error causes.
Subsequent behavior of the panic handler can be set using CONFIG_ESP_SYSTEM_PANIC configuration choice. The
available options are:
• Print registers and reboot (CONFIG_ESP_SYSTEM_PANIC_PRINT_REBOOT) default option.
This will print register values at the point of the exception, print the backtrace, and restart the chip.
• Print registers and halt (CONFIG_ESP_SYSTEM_PANIC_PRINT_HALT)
Similar to the above option, but halt instead of rebooting. External reset is required to restart the program.
• Silent reboot (CONFIG_ESP_SYSTEM_PANIC_SILENT_REBOOT)
Don t print registers or backtrace, restart the chip immediately.
• Invoke GDB Stub (CONFIG_ESP_SYSTEM_PANIC_GDBSTUB)
Start GDB server which can communicate with GDB over console UART port. See GDB Stub for more details.
Behavior of panic handler is affected by two other configuration options.
• If CONFIG_ESP32_DEBUG_OCDAWARE is enabled (which is the default), panic handler will detect whether
a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In
this case registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not
used.
• If Core Dump feature is enabled, then system state (task stacks and registers) will be dumped either to Flash
or UART, for later analysis.
• If CONFIG_ESP_PANIC_HANDLER_IRAM is disabled (disabled by default), the panic handler code is placed
in flash memory not IRAM. This means that if ESP-IDF crashes while flash cache is disabled, the panic handler
will automatically re-enable flash cache before running GDB Stub or Core Dump. This adds some minor risk,
if the flash cache status is also corrupted during the crash.
If this option is enabled, the panic handler code (including required UART functions) is placed in IRAM. This
may be necessary to debug some complex issues with crashes while flash cache is disabled (for example, when
writing to SPI flash) or when flash cache is corrupted when an exception is triggered.
The following diagram illustrates panic handler behavior:
4.13.3 Register Dump and Backtrace
Unless CONFIG_ESP_SYSTEM_PANIC_SILENT_REBOOT option is enabled, panic handler prints some of the

CPU registers, and the backtrace, to the console

Fig. 32: Panic Handler Flowchart (click to enlarge)

Core 0 register dump:

PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 :␣
,→0x3ffb5030
A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 :␣

,→0x3ffb50dc
A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 :␣

,→0x3ffb5000
A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 :␣

,→0x06ff1ff8
A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE:␣

,→0x0000001d

,→0xffffffff
Backtrace: 0x400e14ed:0x3ffb5030 0x400d0802:0x3ffb5050
Register values printed are the register values in the exception frame, i.e. values at the moment when CPU exception
or other fatal error has occured.
Register dump is not printed if the panic handler was executed as a result of an abort() call.
In some cases, such as interrupt watchdog timeout, panic handler may print additional CPU registers (EPC1-EPC4)
and the registers/backtrace of the code running on the other CPU.
Backtrace line contains PC:SP pairs, where PC is the Program Counter and SP is Stack Pointer, for each stack frame
of the current task. If a fatal error happens inside an ISR, the backtrace may include PC:SP pairs both from the task
which was interrupted, and from the ISR.
If IDF Monitor is used, Program Counter values will be converted to code locations (function name, file name, and
line number), and the output will be annotated with additional lines
Core 0 register dump:

PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 :␣
,→0x3ffb5030
0x400e14ed: app_main at /Users/user/esp/example/main/main.cpp:36
A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 :␣

,→ 0x3ffb50dc
A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 :␣
,→0x3ffb5000
A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 :␣

,→0x06ff1ff8
0x40082d1c: _calloc_r at /Users/user/esp/esp-idf/components/newlib/syscalls.c:51
A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE:␣

,→0x0000001d

,→0xffffffff
Backtrace: 0x400e14ed:0x3ffb5030 0x400d0802:0x3ffb5050

0x400e14ed: app_main at /Users/user/esp/example/main/main.cpp:36
0x400d0802: main_task at /Users/user/esp/esp-idf/components/esp32/cpu_start.c:470
To find the location where a fatal error has happened, look at the lines which follow the Backtrace line. Fatal
error location is the top line, and subsequent lines show the call stack.
4.13.4 GDB Stub
If CONFIG_ESP_SYSTEM_PANIC_GDBSTUB option is enabled, panic handler will not reset the chip when fatal
error happens. Instead, it will start GDB remote protocol server, commonly referred to as GDB Stub. When this
happens, GDB instance running on the host computer can be instructed to connect to the ESP32 UART port.

If IDF Monitor is used, GDB is started automatically when GDB Stub prompt is detected on the UART. The output
would look like this:
Entering gdb stub now.

$T0b#e6GNU gdb (crosstool-NG crosstool-ng-1.22.0-80-gff1f415) 7.10
Copyright (C) 2015 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law. Type "show copying"
and "show warranty" for details.
This GDB was configured as "--host=x86_64-build_apple-darwin16.3.0 --target=xtensa-
,→esp32-elf".
Type "show configuration" for configuration details.

For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
<http://www.gnu.org/software/gdb/documentation/>.
For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from /Users/user/esp/example/build/example.elf...done.
Remote debugging using /dev/cu.usbserial-31301
0x400e1b41 in app_main ()
at /Users/user/esp/example/main/main.cpp:36
36 *((int*) 0) = 0;
(gdb)
GDB prompt can be used to inspect CPU registers, local and static variables, and arbitrary locations in memory. It
is not possible to set breakpoints, change PC, or continue execution. To reset the program, exit GDB and perform
external reset: Ctrl-T Ctrl-R in IDF Monitor, or using external reset button on the development board.
4.13.5 Guru Meditation Errors
This section explains the meaning of different error causes, printed in parens after Guru Meditation Error:
Core panic'ed message.
Note: See Wikipedia article for historical origins of Guru Meditation .
IllegalInstruction
This CPU exception indicates that the instruction which was executed was not a valid instruction. Most common
reasons for this error include:
• FreeRTOS task function has returned. In FreeRTOS, if task function needs to terminate, it should call
vTaskDelete() function and delete itself, instead of returning.
• Failure to load next instruction from SPI flash. This usually happens if:
– Application has reconfigured SPI flash pins as some other function (GPIO, UART, etc.). Consult Hard-
ware Design Guidelines and the Datasheet for the chip or module for details about SPI flash pins.
– Some external device was accidentally connected to SPI flash pins, and has interfered with communication
between ESP32 and SPI flash.
InstrFetchProhibited
This CPU exception indicates that CPU could not load an instruction because the the address of the instruction did
not belong to a valid region in instruction RAM or ROM.
Usually this means an attempt to call a function pointer, which does not point to valid code. PC (Program Counter)
register can be used as an indicator: it will be zero or will contain garbage value (not 0x4xxxxxxx).

LoadProhibited, StoreProhibited
This CPU exception happens when application attempts to read from or write to an invalid memory location. The
address which was written/read is found in EXCVADDR register in the register dump. If this address is zero, it usually
means that application attempted to dereference a NULL pointer. If this address is close to zero, it usually means that
application attempted to access member of a structure, but the pointer to the structure was NULL. If this address is
something else (garbage value, not in 0x3fxxxxxx - 0x6xxxxxxx range), it likely means that the pointer used
to access the data was either not initialized or was corrupted.
IntegerDivideByZero
Application has attempted to do integer division by zero.
LoadStoreAlignment
Application has attempted to read or write memory location, and address alignment did not match load/store size.
For example, 32-bit load can only be done from 4-byte aligned address, and 16-bit load can only be done from a
2-byte aligned address.
LoadStoreError
This exception may happen in the following cases:

• If the application has attempted to do an 8- or 16- bit load/store from a memory region which only supports
32-bit loads/stores. For example, dereferencing a char* pointer to intruction memory (IRAM, IROM) will
result in such an error.
• If the application has attempted a store to a read-only memory region, such as IROM or DROM.
Unhandled debug exception
This will usually be followed by a message like:
Debug exception reason: Stack canary watchpoint triggered (task_name)
This error indicates that application has written past the end of the stack of task_name task. Note that not every
stack overflow is guaranteed to trigger this error. It is possible that the task writes to stack beyond the stack canary
location, in which case the watchpoint will not be triggered.
Interrupt wdt timeout on CPU0 / CPU1
Indicates that interrupt watchdog timeout has occured. See Watchdogs for more information.
Cache disabled but cached memory region accessed
In some situations ESP-IDF will temporarily disable access to external SPI Flash and SPI RAM via caches. For
example, this happens with spi_flash APIs are used to read/write/erase/mmap regions of SPI Flash. In these situations,
tasks are suspended, and interrupt handlers not registered with ESP_INTR_FLAG_IRAM are disabled. Make sure
that any interrupt handlers registered with this flag have all the code and data in IRAM/DRAM. Refer to the SPI flash
API documentation for more details.

4.13.6 Other Fatal Errors
Brownout
ESP32 has a built-in brownout detector, which is enabled by default. Brownout detector can trigger system reset if
supply voltage goes below safe level. Brownout detector can be configured using CONFIG_ESP32_BROWNOUT_DET
and CONFIG_ESP32_BROWNOUT_DET_LVL_SEL options.
When brownout detector triggers, the following message is printed:
Brownout detector was triggered
Chip is reset after the message is printed.

Note that if supply voltage is dropping at a fast rate, only part of the message may be seen on the console.
Corrupt Heap
ESP-IDF heap implementation contains a number of run-time checks of heap structure. Additional checks ( Heap
Poisoning ) can be enabled in menuconfig. If one of the checks fails, message similar to the following will be printed:
CORRUPT HEAP: Bad tail at 0x3ffe270a. Expected 0xbaad5678 got 0xbaac5678

assertion "head != NULL" failed: file "/Users/user/esp/esp-idf/components/heap/
,→multi_heap_poisoning.c", line 201, function: multi_heap_free
abort() was called at PC 0x400dca43 on core 0
Consult Heap Memory Debugging documentation for further information.
Stack Smashing
Stack smashing protection (based on GCC -fstack-protector* flags) can be enabled in ESP-IDF using CON-
FIG_COMPILER_STACK_CHECK_MODE option. If stack smashing is detected, message similar to the following
will be printed:
Stack smashing protect failure!
abort() was called at PC 0x400d2138 on core 0
Backtrace: 0x4008e6c0:0x3ffc1780 0x4008e8b7:0x3ffc17a0 0x400d2138:0x3ffc17c0␣

,→0x400e79d5:0x3ffc17e0 0x400e79a7:0x3ffc1840 0x400e79df:0x3ffc18a0␣
,→0x400e2235:0x3ffc18c0 0x400e1916:0x3ffc18f0 0x400e19cd:0x3ffc1910␣
,→0x400e1a11:0x3ffc1930 0x400e1bb2:0x3ffc1950 0x400d2c44:0x3ffc1a80
The backtrace should point to the function where stack smashing has occured. Check the function code for unbounded
access to local arrays.
Undefined behavior sanitizer (UBSAN) checks
Undefined behavior sanitizer (UBSAN) is a compiler feature which adds run-time checks for potentially incorrect
operations, such as:
• overflows (multiplication overflow, signed integer overflow)
• shift base or exponent errors (e.g. shift by more than 32 bits)
• integer conversion errors
See GCC documentation of -fsanitize=undefined option for the complete list of supported checks.

Enabling UBSAN UBSAN is disabled by default. It can be enabled at file, component, or project level by adding
-fsanitize=undefined compiler option in the build system.
When enabling UBSAN for the code which uses hardware register header files (soc/xxx_reg.h), it is recom-
mended to disable shift-base sanitizer using -fno-sanitize=shift-base option. This is due to the fact that
ESP-IDF register header files currently contain patterns which cause false positives for this specific sanitizer option.
To enable UBSAN at project level, add the following at the end of the project CMakeLists.txt file:
idf_build_set_property(COMPILE_OPTIONS "-fsanitize=undefined" "-fno-sanitize=shift-

,→base" APPEND)
Alternatively, pass these options through EXTRA_CFLAGS and EXTRA_CXXFLAGS environment variables.
Enabling UBSAN results in significant increase of code and data size. Most applications, except for the trivial ones,
will not fit into the available RAM of the microcontroller when UBSAN is enabled for the whole application. There-
fore it is recommended that UBSAN is instead enabled for specific components under test.
To enable UBSAN for the specific component (component_name) from the project CMakeLists.txt file, add the
following at the end of the file:
idf_component_get_property(lib component_name COMPONENT_LIB)

target_compile_options(${lib} PRIVATE "-fsanitize=undefined" "-fno-sanitize=shift-
,→base")
Note: See the build system documentation for more information about build properties and component properties.
To enable UBSAN for the specific component (component_name) from CMakeLists.txt of the same component,
add the following at the end of the file:
target_compile_options(${COMPONENT_LIB} PRIVATE "-fsanitize=undefined" "-fno-

,→sanitize=shift-base")
UBSAN output When UBSAN detects an error, a message and the backtrace are printed, for example:
Undefined behavior of type out_of_bounds
Backtrace:0x4008b383:0x3ffcd8b0 0x4008c791:0x3ffcd8d0 0x4008c587:0x3ffcd8f0␣

,→0x4008c6be:0x3ffcd950 0x400db74f:0x3ffcd970 0x400db99c:0x3ffcd9a0
When using IDF Monitor, the backtrace will be decoded to function names and source code locations, pointing to the
location where the issue has happened (here it is main.c:128):
0x4008b383: panic_abort at /path/to/esp-idf/components/esp_system/panic.c:367
0x4008c791: esp_system_abort at /path/to/esp-idf/components/esp_system/system_api.

,→c:106
0x4008c587: __ubsan_default_handler at /path/to/esp-idf/components/esp_system/

,→ubsan.c:152
0x4008c6be: __ubsan_handle_out_of_bounds at /path/to/esp-idf/components/esp_system/

,→ubsan.c:223
0x400db74f: test_ub at main.c:128
0x400db99c: app_main at main.c:56 (discriminator 1)
The types of errors reported by UBSAN can be as follows:

Name Meaning
type_mismatch, Incorrect pointer value: null, unaligned, not compatible with the
type_mismatch_v1 given type.
add_overflow, sub_overflow, Integer overflow during addition, subtraction, multiplication, nega-
mul_overflow, negate_overflow tion.
divrem_overflow Integer division by 0 or INT_MIN.
shift_out_of_bounds Overflow in left or right shift operators.
out_of_bounds Access outside of bounds of an array.
unreachable Unreachable code executed.
missing_return Non-void function has reached its end without returning a value
(C++ only).
vla_bound_not_positive Size of variable length array is not positive.
load_invalid_value Value of bool or enum (C++ only) variable is invalid (out of
bounds).
nonnull_arg Null argument passed to a function which is declared with a non-
null attribute.
nonnull_return Null value returned from a function which is declared with re-
turns_nonnull attribute.
builtin_unreachable __builtin_unreachable function called.
pointer_overflow Overflow in pointer arithmetic.
4.14 Flash Encryption

This is a quick start guide to ESP32 s flash encryption feature. Using an application code example, it demonstrates
how to test and verify flash encryption operations during development and production.
4.14.1 Introduction
Flash encryption is intended for encrypting the contents of the ESP32 s off-chip flash memory. Once this feature is
enabled, firmware is flashed as plaintext, and then the data is encrypted in place on the first boot. As a result, physical
readout of flash will not be sufficient to recover most flash contents.
With flash encryption enabled, the following types of data are encrypted by default:
• Firmware bootloader
• Partition Table
• All app type partitions
Other types of data can be encrypted conditionally:
• Any partition marked with the encrypted flag in the partition table. For details, see Encrypted Partition
Flag.
• Secure Boot bootloader digest if Secure Boot is enabled (see below).
Secure Boot is a separate feature which can be used together with flash encryption to create an even more secure
environment.
Important: For production use, flash encryption should be enabled in the Release mode only.
Important: Enabling flash encryption limits the options for further updates of ESP32. Before using this feature,
read the document and make sure to understand the implications.

4.14.2 Relevant eFuses
The flash encryption operation is controlled by various eFuses available on ESP32. The list of eFuses
and their descriptions is given in the table below. The names in eFuse column are also used by es-
pefuse.py tool. For usage in the eFuse API, modify the name by adding ESP_EFUSE_, for example:
esp_efuse_read_field_bit(ESP_EFUSE_DISABLE_DL_ENCRYPT).
Table 20: eFuses Used in Flash Encryption

eFuse Description Bit Depth
CODING_SCHEME Controls actual number of block1 bits used to derive final 2
256-bit AES key. Possible values: 0 for 256 bits, 1 for 192
bits, 2 for 128 bits. Final AES key is derived based on the
FLASH_CRYPT_CONFIG value.
flash_encryption (block1) AES key storage. 256 bit key
block
FLASH_CRYPT_CONFIG Controls the AES encryption process. 4
DISABLE_DL_ENCRYPT If set, disables flash encryption operation while running in 1
Firmware Download mode.
DISABLE_DL_DECRYPT If set, disables flash decryption while running in UART 1
FLASH_CRYPT_CNT Enables/disables encryption at boot time. If even number 7
of bits set (0, 2, 4, 6) - encrypt flash at boot time. If odd
number of bits set (1, 3, 5, 7) - do not encrypt flash at boot
time.
Note:
• R/W access control is available for all the eFuse bits listed in the table above.
• The default value of these bits is 0 afer manufacturing.
Read and write access to eFuse bits is controlled by appropriate fields in the registers WR_DIS and RD_DIS.
For more information on ESP32 eFuses, see eFuse manager. To change protection bits of eFuse field using
espefuse.py, use these two commands: read_protect_efuse and write_protect_efuse. Example espefuse.py
write_protect_efuse DISABLE_DL_ENCRYPT.
4.14.3 Flash Encryption Process
Assuming that the eFuse values are in their default states and the firmware bootloader is compiled to support flash
encryption, the flash encryption process executes as shown below:
1. On the first power-on reset, all data in flash is un-encrypted (plaintext). The ROM bootloader loads the firmware
bootloader.
2. Firmware bootloader reads the FLASH_CRYPT_CNT eFuse value (0b0000000). Since the value is
0 (even number of bits set), it configures and enables the flash encryption block. It also sets the
FLASH_CRYPT_CONFIG eFuse to 0xF. For more information on the flash encryption block, see ESP32
Technical Reference Manual > eFuse Controller (eFuse) > Flash Encryption Block [PDF].
3. Firmware bootloader uses RNG (random) module to generate an AES-256 bit key and then writes it into the
flash_encryption eFuse. The key cannot be accessed via software as the write and read protection bits
for the flash_encryption eFuse are set. The flash encryption operations happen entirely by hardware,
and the key cannot be accessed via software.
4. Flash encryption block encrypts the flash contents - the firmware bootloader, applications and partitions marked
as encrypted. Encrypting in-place can take time, up to a minute for large partitions.
5. Firmware bootloader sets the first available bit in FLASH_CRYPT_CNT (0b0000001) to mark the flash con-
tents as encrypted. Odd number of bits is set.

6. For Development Mode, the firmware bootloader sets only the eFuse bits DISABLE_DL_DECRYPT
and DISABLE_DL_CACHE to allow the UART bootloader to re-flash encrypted binaries. Also, the
FLASH_CRYPT_CNT eFuse bits are NOT write-protected.
7. For Release Mode, the firmware bootloader sets the eFuse bits DISABLE_DL_ENCRYPT, DIS-
ABLE_DL_DECRYPT, and DISABLE_DL_CACHE to 1 to prevent the UART bootloader from decrypting
the flash contents. It also write-protects the FLASH_CRYPT_CNT eFuse bits. To modify this behavior, see
Enabling UART Bootloader Encryption/Decryption.
8. The device is then rebooted to start executing the encrypted image. The firmware bootloader calls the flash
decryption block to decrypt the flash contents and then loads the decrypted contents into IRAM.
During the development stage, there is a frequent need to program different plaintext flash images and test the flash
encryption process. This requires that Firmware Download mode is able to load new plaintext images as many times
as it might be needed. However, during manufacturing or production stages, Firmware Download mode should not
be allowed to access flash contents for security reasons.
Hence, two different flash encryption configurations were created: for development and for production. For details
on these configurations, see Section Flash Encryption Configuration.
4.14.4 Flash Encryption Configuration
The following flash encryption modes are available:

• Development Mode - recommended for use ONLY DURING DEVELOPMENT, as it does not prevent modi-
fication and readout of encrypted flash contents.
• Release Mode - recommended for manufacturing and production to prevent physical readout of encrypted flash
contents.
This section provides information on the mentioned flash encryption modes and step by step instructions on how to
use them.
Development Mode
During development, you can encrypt flash using either an ESP32 generated key or external host-generated key.
Using ESP32 Generated Key Development mode allows you to download multiple plaintext images using
To test flash encryption process, take the following steps:
1. Ensure that you have an ESP32 device with default flash encryption eFuse settings as shown in Relevant eFuses.
See how to check ESP32 Flash Encryption Status.
2. In Project Configuration Menu, do the following:
• Enable flash encryption on boot
• Select encryption mode (Development mode by default)
• Select UART ROM download mode (enabled by default. Note that for the esp32 target, the choice
is only available when CONFIG_ESP32_REV_MIN level is set to 3 (ESP32 V3)).
• Select the appropriate bootloader log verbosity
• Save the configuration and exit.
Enabling flash encryption will increase the size of bootloader, which might require updating partition table offset.
See Bootloader Size.
3. Run the command given below to build and flash the complete images.
idf.py flash monitor

Note: This command does not include any user files which should be written to the partitions on the
flash memory. Please write them manually before running this command otherwise the files should be
encrypted separately before writing.
This command will write to flash memory unencrypted images: the firmware bootloader, the parti-
tion table and applications. Once the flashing is complete, ESP32 will reset. On the next boot, the
firmware bootloader encrypts: the firmware bootloader, application partitions and partitions marked as
encrypted then resets. Encrypting in-place can take time, up to a minute for large partitions. After
that, the application is decrypted at runtime and executed.
A sample output of the first ESP32 boot after enabling flash encryption is given below:
--- idf_monitor on /dev/cu.SLAB_USBtoUART 115200 ---
--- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
ets Jun 8 2016 00:22:57

configsip: 0, SPIWP:0xee
load:0x3fff001c,len:8452
load:0x40078000,len:13608
load:0x40080400,len:6664
entry 0x40080764
I (28) boot: ESP-IDF v4.0-dev-850-gc4447462d-dirty 2nd stage bootloader
I (30) boot: Enabling RNG early entropy source...
I (35) boot: SPI Speed : 40MHz
I (39) boot: SPI Mode : DIO
I (43) boot: SPI Flash Size : 4MB
I (47) boot: Partition Table:
I (51) boot: ## Label Usage Type ST Offset Length
I (58) boot: 0 nvs WiFi data 01 02 0000a000 00006000
I (66) boot: 1 phy_init RF data 01 01 00010000 00001000
I (73) boot: 2 factory factory app 00 00 00020000 00100000
I (81) boot: End of partition table
I (85) esp_image: segment 0: paddr=0x00020020 vaddr=0x3f400020 size=0x0808c (␣
,→32908) map
I (105) esp_image: segment 1: paddr=0x000280b4 vaddr=0x3ffb0000 size=0x01ea4 ( ␣

,→7844) load
I (109) esp_image: segment 2: paddr=0x00029f60 vaddr=0x40080000 size=0x00400 ( ␣

,→1024) load
0x40080000: _WindowOverflow4 at esp-idf/esp-idf/components/freertos/xtensa_vectors.

,→S:1778
I (114) esp_image: segment 3: paddr=0x0002a368 vaddr=0x40080400 size=0x05ca8 (␣

,→23720) load
I (132) esp_image: segment 4: paddr=0x00030018 vaddr=0x400d0018 size=0x126a8 (␣

,→75432) map
0x400d0018: _flash_cache_start at ??:?
I (159) esp_image: segment 5: paddr=0x000426c8 vaddr=0x400860a8 size=0x01f4c ( ␣

,→8012) load
0x400860a8: prvAddNewTaskToReadyList at esp-idf/esp-idf/components/freertos/tasks.

,→c:4561
I (168) boot: Loaded app from partition at offset 0x20000

I (168) boot: Checking flash encryption...
I (168) flash_encrypt: Generating new flash encryption key...
I (187) flash_encrypt: Read & write protecting new key...


I (187) flash_encrypt: Setting CRYPT_CONFIG efuse to 0xF
W (188) flash_encrypt: Not disabling UART bootloader encryption
I (195) flash_encrypt: Disable UART bootloader decryption...
I (201) flash_encrypt: Disable UART bootloader MMU cache...
I (208) flash_encrypt: Disable JTAG...
I (212) flash_encrypt: Disable ROM BASIC interpreter fallback...
I (219) esp_image: segment 0: paddr=0x00001020 vaddr=0x3fff0018 size=0x00004 ( ␣
,→4)
I (227) esp_image: segment 1: paddr=0x0000102c vaddr=0x3fff001c size=0x02104 ( ␣

,→8452)
I (239) esp_image: segment 2: paddr=0x00003138 vaddr=0x40078000 size=0x03528 (␣

,→13608)
I (249) esp_image: segment 3: paddr=0x00006668 vaddr=0x40080400 size=0x01a08 ( ␣

,→6664)

,→32908) map

,→7844)

,→1024)

,→S:1778

,→23720)

,→75432) map

,→8012)

,→c:4561
I (722) flash_encrypt: Encrypting partition 2 at offset 0x20000...

I (13229) flash_encrypt: Flash encryption completed
I (13229) boot: Resetting with flash encryption enabled...
A sample output of subsequent ESP32 boots just mentions that flash encryption is already enabled:

load:0x40078000,len:13652
ho 0 tail 12 room 4
load:0x40080400,len:6664
entry 0x40080764


,→32908) map

,→7844) load

,→1024) load

,→S:1778

,→23720) load

,→75432) map

,→8012) load

,→c:4561
I (171) boot: Loaded app from partition at offset 0x20000

I (171) boot: Checking flash encryption...
I (171) flash_encrypt: flash encryption is enabled (3 plaintext flashes left)
I (178) boot: Disabling RNG early entropy source...
I (184) cpu_start: Pro cpu up.
I (188) cpu_start: Application information:
I (193) cpu_start: Project name: flash-encryption
I (198) cpu_start: App version: v4.0-dev-850-gc4447462d-dirty
I (205) cpu_start: Compile time: Jun 17 2019 16:32:52
I (211) cpu_start: ELF file SHA256: 8770c886bdf561a7...
I (217) cpu_start: ESP-IDF: v4.0-dev-850-gc4447462d-dirty
I (224) cpu_start: Starting app cpu, entry point is 0x40080e4c
0x40080e4c: call_start_cpu1 at esp-idf/esp-idf/components/esp32/cpu_start.c:265
I (0) cpu_start: App cpu up.

I (241) heap_init: At 3FFAE6E0 len 00001920 (6 KiB): DRAM
I (247) heap_init: At 3FFB2EC8 len 0002D138 (180 KiB): DRAM
I (254) heap_init: At 3FFE0440 len 00003AE0 (14 KiB): D/IRAM
I (260) heap_init: At 3FFE4350 len 0001BCB0 (111 KiB): D/IRAM
I (266) heap_init: At 40087FF4 len 0001800C (96 KiB): IRAM
I (273) cpu_start: Pro cpu start user code
I (291) cpu_start: Starting scheduler on PRO CPU.
I (0) cpu_start: Starting scheduler on APP CPU.
Sample program to check Flash Encryption

This is ESP32 chip with 2 CPU cores, WiFi/BT/BLE, silicon revision 1, 4MB external␣
,→flash
Flash encryption feature is enabled

Flash encryption mode is DEVELOPMENT
Flash in encrypted mode with flash_crypt_cnt = 1
Halting...
At this stage, if you need to update and re-flash binaries, see Re-flashing Updated Partitions.
Using Host Generated Key It is possible to pre-generate a flash encryption key on the host computer and burn
it into the eFuse. This allows you to pre-encrypt data on the host and flash already encrypted data without needing
a plaintext flash update. This feature can be used in both Development Mode and Release Mode. Without a pre-
generated key, data is flashed in plaintext and then ESP32 encrypts the data in-place.

Note: This option is not recommended for production, unless a separate key is generated for each individual device.
To use a host generated key, take the following steps:

2. Generate a random key by running:
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
3. Before the first encrypted boot, burn the key into your device s eFuse using the command below. This
action can be done only once.
espefuse.py --port PORT burn_key flash_encryption my_flash_encryption_key.

,→bin
If the key is not burned and the device is started after enabling flash encryption, the ESP32 will generate
a random key that software cannot access or modify.
• Select encryption mode (Development mode by default)
If using Development Mode, then the easiest way to update and re-flash binaries is Re-flashing Updated Partitions.
If using Release Mode, then it is possible to pre-encrypt the binaries on the host and then flash them as ciphertext.
See Manually Encrypting Files.
Re-flashing Updated Partitions If you update your application code (done in plaintext) and want to re-flash it,
you will need to encrypt it before flashing. To encrypt the application and flash it in one step, run:
idf.py encrypted-app-flash monitor
If all partitions needs to be updated in encrypted format, run:
idf.py encrypted-flash monitor

Release Mode
In Release mode, UART bootloader cannot perform flash encryption operations. New plaintext images can ONLY
be downloaded using the over-the-air (OTA) scheme which will encrypt the plaintext image before writing to flash.
To use this mode, take the following steps:
• Select Release mode (Note that once Release mode is selected, the DISABLE_DL_ENCRYPT and
DISABLE_DL_DECRYPT eFuse bits will be burned to disable flash encryption hardware in ROM
Download Mode.)
• Select UART ROM download mode (Permanently disabled (recommended)) (Note that this option is
only available when CONFIG_ESP32_REV_MIN is set to 3 (ESP32 V3).) The default choice is to
keep UART ROM download mode enabled, however it s recommended to permanently disable
this mode to reduce the options available to an attacker.
Once the flash encryption is enabled in Release mode, the bootloader will write-protect the FLASH_CRYPT_CNT
eFuse.
For subsequent plaintext field updates, use OTA scheme.
Note: If you have pre-generated the flash encryption key and stored a copy, and the UART download mode is not
permanently disabled via CONFIG_SECURE_UART_ROM_DL_MODE (ESP32 V3 only), then it is possible to update
the flash locally by pre-encrypting the files and then flashing the ciphertext. See Manually Encrypting Files.
Best Practices
When using Flash Encryption in production:

• Do not reuse the same flash encryption key between multiple devices. This means that an attacker who copies
encrypted data from one device cannot transfer it to a second device.
• When using ESP32 V3, if the UART ROM Download Mode is not needed for a production de-
vice then it should be disabled to provide an extra level of protection. Do this by calling

esp_efuse_disable_rom_download_mode() during application startup. Alternatively, config-

ure the project CONFIG_ESP32_REV_MIN level to 3 (targeting ESP32 V3 only) and select the CON-
FIG_SECURE_UART_ROM_DL_MODE to Permanently disable ROM Download Mode (recommended)
. The ability to disable ROM Download Mode is not available on earlier ESP32 versions.
• Enable Secure Boot as an extra layer of protection, and to prevent an attacker from selectively corrupting any
part of the flash before boot.
4.14.5 Possible Failures
Once flash encryption is enabled, the FLASH_CRYPT_CNT eFuse value will have an odd number of bits set. It
means that all the partitions marked with the encryption flag are expected to contain encrypted ciphertext. Below are
the three typical failure cases if the ESP32 is erroneously loaded with plaintext data:
1. If the bootloader partition is re-flashed with a plaintext firmware bootloader image, the ROM bootloader
will fail to load the firmware bootloader resulting in the following failure:
rst:0x3 (SW_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
flash read err, 1000
ets_main.c 371
ets Jun 8 2016 00:22:57

ets_main.c 371
ets Jun 8 2016 00:22:57

ets_main.c 371
ets Jun 8 2016 00:22:57

ets_main.c 371
ets Jun 8 2016 00:22:57

ets_main.c 371
ets Jun 8 2016 00:22:57
Note: This error also appears if the flash contents are erased or corrupted.
2. If the firmware bootloader is encrypted, but the partition table is re-flashed with a plaintext partition table
image, the bootloader will fail to read the partition table resulting in the following failure:
ho 0 tail 12 room 4
load:0x40078000,len:19168
load:0x40080400,len:6664
entry 0x40080764
I (60) boot: ESP-IDF v4.0-dev-763-g2c55fae6c-dirty 2nd stage bootloader


E (80) flash_parts: partition 0 invalid magic number 0x94f6
E (86) boot: Failed to verify partition table
E (91) boot: load partition table error!
3. If the bootloader and partition table are encrypted, but the application is re-flashed with a plaintext application
image, the bootloader will fail to load the application resulting in the following failure:

load:0x40078000,len:13616
load:0x40080400,len:6664
entry 0x40080764
W (120) esp_image: image at 0x20000 has invalid SPI mode 108
W (126) esp_image: image at 0x20000 has invalid SPI size 11
E (132) boot: Factory app partition is not bootable
E (138) boot: No bootable app partitions in the partition table
4.14.6 ESP32 Flash Encryption Status
To check if flash encryption on your ESP32 device is enabled, do one of the following:
• flash the application example security/flash_encryption onto your device. This application prints the
FLASH_CRYPT_CNT eFuse value and if flash encryption is enabled or disabled.
• Find the serial port name under which your ESP32 device is connected, replace PORT with your port name in
the following command, and run it:
espefuse.py -p PORT summary
4.14.7 Reading and Writing Data in Encrypted Flash
ESP32 application code can check if flash encryption is currently enabled by calling
esp_flash_encryption_enabled(). Also, a device can identify the flash encryption mode by call-
ing esp_get_flash_encryption_mode().
Once flash encryption is enabled, be more careful with accessing flash contents from code.

Scope of Flash Encryption
Whenever the FLASH_CRYPT_CNT eFuse is set to a value with an odd number of bits, all flash content accessed
via the MMU s flash cache is transparently decrypted. It includes:
• Executable application code in flash (IROM).
• All read-only data stored in flash (DROM).
• Any data accessed via spi_flash_mmap().
• The firmware bootloader image when it is read by the ROM bootloader.
Important: The MMU flash cache unconditionally decrypts all existing data. Data which is stored unencrypted
in flash memory will also be transparently decrypted via the flash cache and will appear to software as random
garbage.
Reading from Encrypted Flash
To read data without using a flash cache MMU mapping, you can use the partition read function
esp_partition_read(). This function will only decrypt data when it is read from an encrypted partition.
Data read from unencrypted partitions will not be decrypted. In this way, software can access encrypted and non-
encrypted flash in the same way.
You can also use the following SPI flash API functions:
• esp_flash_read() to read raw (encrypted) data which will not be decrypted
• esp_flash_read_encrypted() to read and decrypt data
The ROM function SPIRead() can read data without decryption, however, this function is not supported in esp-idf
applications.
Data stored using the Non-Volatile Storage (NVS) API is always stored and read decrypted from the perspective of
flash encryption. It is up to the library to provide encryption feature if required. Refer to NVS Encryption for more
details.
Writing to Encrypted Flash
It is recommended to use the partition write function esp_partition_write(). This function will only encrypt
data when it is written to an encrypted partition. Data written to unencrypted partitions will not be encrypted. In this
way, software can access encrypted and non-encrypted flash in the same way.
You can also pre-encrypt and write data using the function esp_flash_write_encrypted()
Also, the following ROM function exist but not supported in esp-idf applications:
• esp_rom_spiflash_write_encrypted pre-encrypts and writes data to flash
• SPIWrite writes unencrypted data to flash
Since data is encrypted in blocks, the minimum write size for encrypted data is 16 bytes and the alignment is also 16
bytes.
4.14.8 Updating Encrypted Flash
OTA Updates
OTA updates to encrypted partitions will automatically write encrypted data if the function
esp_partition_write() is used.
Before building the application image for OTA updating of an already encrypted device, enable the option Enable
flash encryption on boot in project configuration menu.
For general information about ESP-IDF OTA updates, please refer to OTA

Updating Encrypted Flash via Serial
Flashing an encrypted device via serial bootloader requires that the serial bootloader download interface has not been
permanently disabled via eFuse.
In Development Mode, the recommended method is Re-flashing Updated Partitions.
In Release Mode, if a copy of the same key stored in eFuse is available on the host then it s possible to pre-encrypt
files on the host and then flash them. See Manually Encrypting Files.
4.14.9 Disabling Flash Encryption
If flash encryption was enabled accidentally, flashing of plaintext data will soft-brick the ESP32. The device will
reboot continuously, printing the error flash read err, 1000 or invalid header: 0xXXXXXX.
For flash encryption in Development mode, encryption can be disabled by burning the FLASH_CRYPT_CNT eFuse.
It can only be done three times per chip by taking the following steps:
1. In Project Configuration Menu, disable Enable flash encryption on boot, then save and exit.
2. Open project configuration menu again and double-check that you have disabled this option! If this option is
left enabled, the bootloader will immediately re-enable encryption when it boots.
3. With flash encryption disabled, build and flash the new bootloader and application by running idf.py
flash.
4. Use espefuse.py (in components/esptool_py/esptool) to disable the FLASH_CRYPT_CNT
by running:
espefuse.py burn_efuse FLASH_CRYPT_CNT
Reset the ESP32. Flash encryption will be disabled, and the bootloader will boot as usual.
4.14.10 Key Points About Flash Encryption
• Flash memory contents is encrypted using AES-256. The flash encryption key is stored in the
flash_encryption eFuse internal to the chip and, by default, is protected from software access.
• The flash encryption algorithm is AES-256, where the key is tweaked with the offset address of each 32
byte block of flash. This means that every 32-byte block (two consecutive 16 byte AES blocks) is encrypted
with a unique key derived from the flash encryption key.
• Flash access is transparent via the flash cache mapping feature of ESP32 - any flash regions which are mapped
to the address space will be transparently decrypted when read.
Some data partitions might need to remain unencrypted for ease of access or might require the use of flash-
friendly update algorithms which are ineffective if the data is encrypted. NVS partitions for non-volatile storage
cannot be encrypted since the NVS library is not directly compatible with flash encryption. For details, refer
to NVS Encryption.
• If flash encryption might be used in future, the programmer must keep it in mind and take certain precautions
when writing code that uses encrypted flash.
• If secure boot is enabled, re-flashing the bootloader of an encrypted device requires a Re-flashable secure
boot digest (see Flash Encryption and Secure Boot).
Important: Do not interrupt power to the ESP32 while the first boot encryption pass is running. If
power is interrupted, the flash contents will be corrupted and will require flashing with unencrypted data
again. In this case, re-flashing will not count towards the flashing limit.

4.14.11 Limitations of Flash Encryption
Flash encryption protects firmware against unauthorised readout and modification. It is important to understand the
limitations of the flash encryption feature:
• Flash encryption is only as strong as the key. For this reason, we recommend keys are generated on the device
during first boot (default behaviour). If generating keys off-device, ensure proper procedure is followed and
don t share the same key between all production devices.
• Not all data is stored encrypted. If storing data on flash, check if the method you are using (library, API, etc.)
supports flash encryption.
• Flash encryption does not prevent an attacker from understanding the high-level layout of the flash. This is
because the same AES key is used for every pair of adjacent 16 byte AES blocks. When these adjacent 16
byte blocks contain identical content (such as empty or padding areas), these blocks will encrypt to produce
matching pairs of encrypted blocks. This may allow an attacker to make high-level comparisons between
encrypted devices (i.e. to tell if two devices are probably running the same firmware version).
• For the same reason, an attacker can always tell when a pair of adjacent 16 byte blocks (32 byte aligned)
contain two identical 16 byte sequences. Keep this in mind if storing sensitive data on the flash, design your
flash storage so this doesn t happen (using a counter byte or some other non-identical value every 16 bytes is
sufficient). NVS Encryption deals with this and is suitable for many uses.
• Flash encryption alone may not prevent an attacker from modifying the firmware of the device. To prevent
unauthorised firmware from running on the device, use flash encryption in combination with Secure Boot.
4.14.12 Flash Encryption and Secure Boot
It is recommended to use flash encryption in combination with Secure Boot. However, if Secure Boot is enabled,
additional restrictions apply to device re-flashing:
• OTA Updates are not restricted, provided that the new app is signed correctly with the Secure Boot signing key.
• Plaintext serial flash updates are only possible if the Re-flashable Secure Boot mode is selected and a Secure
Boot key was pre-generated and burned to the ESP32 (refer to Secure Boot). In such configuration, idf.py
bootloader will produce a pre-digested bootloader and secure boot digest file for flashing at offset 0x0.
When following the plaintext serial re-flashing steps it is necessary to re-flash this file before flashing other
plaintext data.
• Re-flashing via Pregenerated Flash Encryption Key is still possible, provided the bootloader is not re-flashed.
Re-flashing the bootloader requires the same Re-flashable option to be enabled in the Secure Boot config.
4.14.13 Advanced Features
The following section covers advanced features of flash encryption.
Encrypted Partition Flag
Some partitions are encrypted by default. Other partitions can be marked in the partition table description as requiring
encryption by adding the flag encrypted to the partitions flag field. As a result, data in these marked partitions
will be treated as encrypted in the same manner as an app partition.
# Name, Type, SubType, Offset, Size, Flags

nvs, data, nvs, 0x9000, 0x6000
phy_init, data, phy, 0xf000, 0x1000
factory, app, factory, 0x10000, 1M
secret_data, 0x40, 0x01, 0x20000, 256K, encrypted
For details on partition table description, see partition table.

Further information about encryption of partitions:
• Default partition tables do not include any encrypted data partitions.

• With flash encryption enabled, the app partition is always treated as encrypted and does not require marking.
• If flash encryption is not enabled, the flag encrypted has no effect.
• You can also consider protecting phy_init data from physical access, readout, or modification, by marking
the optional phy partition with the flag encrypted.
• The nvs partition cannot be encrypted, because the NVS library is not directly compatible with flash encryp-
tion.
Enabling UART Bootloader Encryption/Decryption
On the first boot, the flash encryption process burns by default the following eFuses:
• DISABLE_DL_ENCRYPT which disables flash encryption operation when running in UART bootloader boot
mode.
• DISABLE_DL_DECRYPT which disables transparent flash decryption when running in UART bootloader
mode, even if the eFuse FLASH_CRYPT_CNT is set to enable it in normal operation.
• DISABLE_DL_CACHE which disables the entire MMU flash cache when running in UART bootloader mode.
However, before the first boot you can choose to keep any of these features enabled by burning only selected eFuses
and write-protect the rest of eFuses with unset value 0. For example:
espefuse.py --port PORT burn_efuse DISABLE_DL_DECRYPT

espefuse.py --port PORT write_protect_efuse DISABLE_DL_ENCRYPT
Important: Leaving DISABLE_DL_DECRYPT unset (0) makes flash encryption useless.

An attacker with physical access to the chip can use UART bootloader mode with custom stub code to read out the
flash contents.
Setting FLASH_CRYPT_CONFIG
The eFuse FLASH_CRYPT_CONFIG determines the number of bits in the flash encryption key which are tweaked
with the block offset. For details, see Flash Encryption Algorithm.
On the first boot of the firmware bootloader, this value is set to the maximum 0xF.
It is possible to burn this eFuse manually and write protect it before the first boot in order to select different tweak
values. However, this is not recommended.
It is strongly recommended to never write-protect FLASH_CRYPT_CONFIG when it is unset. Otherwise, its value
will remain zero permanently, and no bits in the flash encryption key will be tweaked. As a result, the flash encryption
algorithm will be equivalent to AES ECB mode.
JTAG Debugging
By default, when Flash Encryption is enabled (in either Development or Release mode) then JTAG debugging is
disabled via eFuse. The bootloader does this on first boot, at the same time it enables flash encryption.
See JTAG with Flash Encryption or Secure Boot for more information about using JTAG Debugging with Flash
Encryption.
Manually Encrypting Files
Manually encrypting or decrypting files requires the flash encryption key to be pre-burned in eFuse (see Using Host
Generated Key) and a copy to be kept on the host. If the flash encryption is configured in Development Mode then it
s not necessary to keep a copy of the key or follow these steps, the simpler Re-flashing Updated Partitions steps can
be used.

The key file should be a single raw binary file (example: key.bin).
For example, these are the steps to encrypt the file build/my-app.bin to flash at offset 0x10000. Run espse-
cure.py as follows:
espsecure.py encrypt_flash_data --keyfile /path/to/key.bin --address 0x10000 --

,→output my-app-ciphertext.bin build/my-app.bin
The file my-app-ciphertext.bin can then be flashed to offset 0x10000 using esptool.py. To see all of the
command line options recommended for esptool.py, see the output printed when idf.py build succeeds.
Note: If the flashed ciphertext file is not recognized by the ESP32 when it boots, check that the keys match and that
the command line arguments match exactly, including the correct offset.
If your ESP32 uses non-default FLASH_CRYPT_CONFIG value in eFuse then you will need to pass the --
flash_crypt_conf argument to espsecure.py to set the matching value. This will not happen if the device
configured flash encryption by itself, but may happen if burning eFuses manually to enable flash encryption.
The command espsecure.py decrypt_flash_data can be used with the same options (and different
input/output files), to decrypt ciphertext flash contents or a previously encrypted file.
4.14.14 Technical Details
The following sections provide some reference information about the operation of flash encryption.
Flash Encryption Algorithm
• AES-256 operates on 16-byte blocks of data. The flash encryption engine encrypts and decrypts data in 32-byte
blocks - two AES blocks in series.
• The main flash encryption key is stored in the flash_encryption eFuse and, by default, is protected from
further writes or software readout.
• AES-256 key size is 256 bits (32 bytes) read from the flash_encryption eFuse. The hardware AES
engine uses the key in reversed byte order as compared to the storage order in flash_encryption.
– If the CODING_SCHEME eFuse is set to 0 (default, None Coding Scheme) then the eFuse key block
is 256 bits and the key is stored as-is (in reversed byte order).
– If the CODING_SCHEME eFuse is set to 1 (3/4 Encoding) then the eFuse key block is 192 bits (in
reversed byte order), so overall entropy is reduced. The hardware flash encryption still operates on a
256-bit key, after being read (and un-reversed), the key is extended as key = key[0:255] +
key[64:127].
• AES algorithm is used inverted in flash encryption, so the flash encryption encrypt operation is AES decrypt
and the decrypt operation is AES encrypt. This is for performance reasons and does not alter the effeciency
of the algorithm.
• Each 32-byte block (two adjacent 16-byte AES blocks) is encrypted with a unique key. The key is derived from
the main flash encryption key in flash_encryption, XORed with the offset of this block in the flash (a
key tweak ).
• The specific tweak depends on the FLASH_CRYPT_CONFIG eFuse setting. This is a 4-bit eFuse where each
bit enables XORing of a particular range of the key bits:
– Bit 1, bits 0-66 of the key are XORed.
It is recommended that FLASH_CRYPT_CONFIG is always left at the default value 0xF, so that all key bits
are XORed with the block offset. For details, see Setting FLASH_CRYPT_CONFIG.
• The high 19 bits of the block offset (bit 5 to bit 23) are XORed with the main flash encryption key. This range
is chosen for two reasons: the maximum flash size is 16MB (24 bits), and each block is 32 bytes so the least
significant 5 bits are always zero.

• There is a particular mapping from each of the 19 block offset bits to the 256 bits of the flash encryption key to
determine which bit is XORed with which. See the variable _FLASH_ENCRYPTION_TWEAK_PATTERN
in the espsecure.py source code for complete mapping.
• To see the full flash encryption algorithm implemented in Python, refer to the
_flash_encryption_operation() function in the espsecure.py source code.
4.15 ESP-IDF FreeRTOS SMP Changes
4.15.1 Overview
The vanilla FreeRTOS is designed to run on a single core. However the ESP32 is dual core containing a Protocol
CPU (known as CPU 0 or PRO_CPU) and an Application CPU (known as CPU 1 or APP_CPU). The two cores
are identical in practice and share the same memory. This allows the two cores to run tasks interchangeably between
them.
The ESP-IDF FreeRTOS is a modified version of vanilla FreeRTOS which supports symmetric multiprocessing
(SMP). ESP-IDF FreeRTOS is based on the Xtensa port of FreeRTOS v10.2.0. This guide outlines the major
differences between vanilla FreeRTOS and ESP-IDF FreeRTOS. The API reference for vanilla FreeRTOS can be
found via https://www.freertos.org/a00106.html
For information regarding features that are exclusive to ESP-IDF FreeRTOS, see ESP-IDF FreeRTOS Additions.
Tasks and Task Creation: Use xTaskCreatePinnedToCore() or xTaskCreateStaticPinnedTo-
Core() to create tasks in ESP-IDF FreeRTOS. The last parameter of the two functions is xCoreID. This pa-
rameter specifies which core the task is pinned to. Acceptable values are 0 for PRO_CPU, 1 for APP_CPU, or
tskNO_AFFINITY which allows the task to run on both.
Round Robin Scheduling: The ESP-IDF FreeRTOS scheduler implements a Best Effort Round-Robin Scheduling
instead of the ideal Round-Robin scheduling in vanilla FreeRTOS.
Scheduler Suspension: Suspending the scheduler in ESP-IDF FreeRTOS will only affect the scheduler on the the
calling core. In other words, calling vTaskSuspendAll() on PRO_CPU will not prevent APP_CPU from
scheduling, and vice versa. Use critical sections or semaphores instead for simultaneous access protection.
Tick Interrupt Synchronicity: Tick interrupts of PRO_CPU and APP_CPU are not synchronized. Do not expect to
use vTaskDelay() or vTaskDelayUntil() as an accurate method of synchronizing task execution between
the two cores. Use a counting semaphore instead as their context switches are not tied to tick interrupts due to
preemption.
Critical Sections & Disabling Interrupts: In ESP-IDF FreeRTOS, critical sections are implemented using mutexes.
Entering critical sections involve taking a mutex, then disabling the scheduler and interrupts of the calling core.
However the other core is left unaffected. If the other core attemps to take same mutex, it will spin until the calling
core has released the mutex by exiting the critical section.
Floating Point Arithmetic: The ESP32 supports hardware acceleration of single precision floating point arithmetic
(float). However the use of hardware acceleration leads to some behavioral restrictions in ESP-IDF FreeRTOS.
Therefore, tasks that utilize float will automatically be pinned to a core if not done so already. Furthermore,
float cannot be used in interrupt service routines.
Thread Local Storage Pointers & Deletion Callbacks: Deletion callbacks are called automatically during task deletion
and are used to free memory pointed to by TLSP. Call vTaskSetThreadLocalStoragePointerAndDel-
Callback() to set TLSP and Deletion Callbacks.
Configuring ESP-IDF FreeRTOS: Several aspects of ESP-IDF FreeRTOS can be set in the project configuration (idf.
py menuconfig) such as running ESP-IDF in Unicore (single core) Mode, or configuring the number of Thread
Local Storage Pointers each task will have.
It is not necessary to manually start the FreeRTOS scheduler by calling vTaskStartScheduler(). In ESP-IDF
the scheduler is started by the Application Startup Flow and is already running when the app_main function is called
(see Running the main task for details).

4.15.2 Tasks and Task Creation
Tasks in ESP-IDF FreeRTOS are designed to run on a particular core, therefore two new task creation functions have
been added to ESP-IDF FreeRTOS by appending PinnedToCore to the names of the task creation functions in
vanilla FreeRTOS. The vanilla FreeRTOS functions of xTaskCreate() and xTaskCreateStatic() have
led to the addition of xTaskCreatePinnedToCore() and xTaskCreateStaticPinnedToCore() in
ESP-IDF FreeRTOS
For more details see freertos/FreeRTOS-Kernel/tasks.c
The ESP-IDF FreeRTOS task creation functions are nearly identical to their vanilla counterparts with the exception
of the extra parameter known as xCoreID. This parameter specifies the core on which the task should run on and
can be one of the following values.
• 0 pins the task to PRO_CPU
• 1 pins the task to APP_CPU
• tskNO_AFFINITY allows the task to be run on both CPUs
For example xTaskCreatePinnedToCore(tsk_callback, APP_CPU Task , 1000, NULL,
10, NULL, 1) creates a task of priority 10 that is pinned to APP_CPU with a stack size of 1000 bytes. It should
be noted that the uxStackDepth parameter in vanilla FreeRTOS specifies a task s stack depth in terms of the
number of words, whereas ESP-IDF FreeRTOS specifies the stack depth in terms of bytes.
Note that the vanilla FreeRTOS functions xTaskCreate() and xTaskCreateStatic() have been defined
in ESP-IDF FreeRTOS as inline functions which call xTaskCreatePinnedToCore() and xTaskCreat-
eStaticPinnedToCore() respectively with tskNO_AFFINITY as the xCoreID value.
Each Task Control Block (TCB) in ESP-IDF stores the xCoreID as a member. Hence when each core calls the
scheduler to select a task to run, the xCoreID member will allow the scheduler to determine if a given task is
permitted to run on the core that called it.
4.15.3 Scheduling
The vanilla FreeRTOS implements scheduling in the vTaskSwitchContext() function. This function is re-
sponsible for selecting the highest priority task to run from a list of tasks in the Ready state known as the Ready
Tasks List (described in the next section). In ESP-IDF FreeRTOS, each core will call vTaskSwitchContext()
independently to select a task to run from the Ready Tasks List which is shared between both cores. There are sev-
eral differences in scheduling behavior between vanilla and ESP-IDF FreeRTOS such as differences in Round Robin
scheduling, scheduler suspension, and tick interrupt synchronicity.
Round Robin Scheduling
Given multiple tasks in the Ready state and of the same priority, vanilla FreeRTOS implements Round Robin schedul-
ing between multiple ready state tasks of the same priority. This will result in running those tasks in turn each time
the scheduler is called (e.g. when the tick interrupt occurs or when a task blocks/yields).
On the other hand, it is not possible for the ESP-IDF FreeRTOS scheduler to implement perfect Round Robin due
to the fact that a particular task may not be able to run on a particular core due to the following reasons:
• The task is pinned to the another core.
• For unpinned tasks, the task is already being run by another core.
Therefore, when a core searches the ready state task list for a task to run, the core may need to skip over a few tasks
in the same priority list or drop to a lower priority in order to find a ready state task that the core can run.
The ESP-IDF FreeRTOS scheduler implements a Best Effort Round Robin scheduling for ready state tasks of the
same priority by ensuring that tasks that have been selected to run will be placed at the back of the list, thus giving
unselected tasks a higher priority on the next scheduling iteration (i.e., the next tick interrupt or yield)
The following example demonstrates the Best Effort Round Robin Scheduling in action. Assume that:

• There are four ready state tasks of the same priority AX, B0, C1, D1 where: - The priority is the current
highest priority with ready state tasks - The first character represents the task s names (i.e., A, B, C, D)
- And the second character represents the tasks core pinning (and X means unpinned)
• The task list is always searched from the head
--------------------------------------------------------------------------------
1. Starting state. None of the ready state tasks have been selected to run
Head [ AX , B0 , C1 , D0 ] Tail
--------------------------------------------------------------------------------
2. Core 0 has tick interrupt and searches for a task to run.

Task A is selected and is moved to the back of the list
Core0--|
Head [ AX , B0 , C1 , D0 ] Tail
0
Head [ B0 , C1 , D0 , AX ] Tail
--------------------------------------------------------------------------------
3. Core 1 has a tick interrupt and searches for a task to run.

Task B cannot be run due to incompatible affinity, so core 1 skips to Task C.
Task C is selected and is moved to the back of the list
Core1-------| 0
Head [ B0 , C1 , D0 , AX ] Tail
0 1
Head [ B0 , D0 , AX , C1 ] Tail
--------------------------------------------------------------------------------
4. Core 0 has another tick interrupt and searches for a task to run.
Task B is selected and moved to the back of the list
Core0--| 1
Head [ B0 , D0 , AX , C1 ] Tail
1 0
Head [ D0 , AX , C1 , B0 ] Tail
--------------------------------------------------------------------------------
5. Core 1 has another tick and searches for a task to run.

Task D cannot be run due to incompatible affinity, so core 1 skips to Task A
Task A is selected and moved to the back of the list
Core1-------| 0
Head [ D0 , AX , C1 , B0 ] Tail
0 1
Head [ D0 , C1 , B0 , AX ] Tail
The implications to users regarding the Best Effort Round Robin Scheduling:
• Users cannot expect multiple ready state tasks of the same priority to run sequentially (as is the case in Vanilla
FreeRTOS). As demonstrated in the example above, a core may need to skip over tasks.
• However, given enough ticks, a task will eventually be given some processing time.

• If a core cannot find a task runnable task at the highest ready state priority, it will drop to a lower priority to
search for tasks.
• To achieve ideal round robin scheduling, users should ensure that all tasks of a particular priority are pinned to
the same core.
Scheduler Suspension
In vanilla FreeRTOS, suspending the scheduler via vTaskSuspendAll() will prevent calls of vTaskSwitch-
Context from context switching until the scheduler has been resumed with xTaskResumeAll(). However
servicing ISRs are still permitted. Therefore any changes in task states as a result from the current running task or
ISRs will not be executed until the scheduler is resumed. Scheduler suspension in vanilla FreeRTOS is a common
protection method against simultaneous access of data shared between tasks, whilst still allowing ISRs to be serviced.
In ESP-IDF FreeRTOS, xTaskSuspendAll() will only prevent calls of vTaskSwitchContext() from
switching contexts on the core that called for the suspension. Hence if PRO_CPU calls vTaskSuspendAll(),
APP_CPU will still be able to switch contexts. If data is shared between tasks that are pinned to different cores,
scheduler suspension is NOT a valid method of protection against simultaneous access. Consider using critical sec-
tions (disables interrupts) or semaphores (does not disable interrupts) instead when protecting shared resources in
ESP-IDF FreeRTOS.
In general, it s better to use other RTOS primitives like mutex semaphores to protect against data shared between
tasks, rather than vTaskSuspendAll().
Tick Interrupt Synchronicity
In ESP-IDF FreeRTOS, tasks on different cores that unblock on the same tick count might not run at exactly the
same time due to the scheduler calls from each core being independent, and the tick interrupts to each core being
unsynchronized.
In vanilla FreeRTOS the tick interrupt triggers a call to xTaskIncrementTick() which is responsible for incre-
menting the tick counter, checking if tasks which have called vTaskDelay() have fulfilled their delay period, and
moving those tasks from the Delayed Task List to the Ready Task List. The tick interrupt will then call the scheduler
if a context switch is necessary.
In ESP-IDF FreeRTOS, delayed tasks are unblocked with reference to the tick interrupt on PRO_CPU as PRO_CPU
is responsible for incrementing the shared tick count. However tick interrupts to each core might not be synchronized
(same frequency but out of phase) hence when PRO_CPU receives a tick interrupt, APP_CPU might not have
received it yet. Therefore if multiple tasks of the same priority are unblocked on the same tick count, the task pinned
to PRO_CPU will run immediately whereas the task pinned to APP_CPU must wait until APP_CPU receives its out
of sync tick interrupt. Upon receiving the tick interrupt, APP_CPU will then call for a context switch and finally
switches contexts to the newly unblocked task.
Therefore, task delays should NOT be used as a method of synchronization between tasks in ESP-IDF FreeRTOS.
Instead, consider using a counting semaphore to unblock multiple tasks at the same time.
4.15.4 Critical Sections & Disabling Interrupts
Vanilla FreeRTOS implements critical sections with taskENTER_CRITICAL() which calls portDIS-
ABLE_INTERRUPTS(). This prevents preemptive context switches and servicing of ISRs during a critical section.
Therefore, critical sections are used as a valid protection method against simultaneous access in vanilla FreeRTOS.
On the other hand, ESP32 has no hardware method for cores to disable each other s interrupts. Calling port-
DISABLE_INTERRUPTS() will have no effect on the interrupts of the other core. Therefore, disabling interrupts
is NOT a valid protection method against simultaneous access to shared data as it leaves the other core free to access
the data even if the current core has disabled its own interrupts.
For this reason, ESP-IDF FreeRTOS implements critical sections using special mutexes, referred by port-
MUX_Type objects. These are implemented on top of a specific spinlock component. Calls to taskEN-
TER_CRITICAL or taskEXIT_CRITICAL each provide a spinlock object as an argument. The spinlock is

associated with a shared resource requiring access protection. When entering a critical section in ESP-IDF FreeR-
TOS, the calling core will disable interrupts similar to the vanilla FreeRTOS implementation, and will then take the
spinlock and enter the critical section. The other core is unaffected at this point, unless it enters its own critical section
and attempts to take the same spinlock. In that case it will spin until the lock is released. Therefore, the ESP-IDF
FreeRTOS implementation of critical sections allows a core to have protected access to a shared resource without
disabling the other core. The other core will only be affected if it tries to concurrently access the same resource.
The ESP-IDF FreeRTOS critical section functions have been modified as follows
• taskENTER_CRITICAL(mux), taskENTER_CRITICAL_ISR(mux), portEN-
TER_CRITICAL(mux), portENTER_CRITICAL_ISR(mux) are all macro defined to call internal
function vPortEnterCritical()
• taskEXIT_CRITICAL(mux), taskEXIT_CRITICAL_ISR(mux), por-
tEXIT_CRITICAL(mux), portEXIT_CRITICAL_ISR(mux) are all macro defined to call internal
function vPortExitCritical()
• portENTER_CRITICAL_SAFE(mux), portEXIT_CRITICAL_SAFE(mux) macro identifies the
context of execution, i.e ISR or Non-ISR, and calls appropriate critical section functions (port*_CRITICAL
in Non-ISR and port*_CRITICAL_ISR in ISR) in order to be in compliance with Vanilla FreeRTOS.
For more details see esp_hw_support/include/soc/spinlock.h, freertos/FreeRTOS-Kernel/include/freertos/task.h, and
freertos/FreeRTOS-Kernel/tasks.c
It should be noted that when modifying vanilla FreeRTOS code to be ESP-IDF FreeRTOS compatible, it is trivial
to modify the type of critical section called as they are all defined to call the same function. As long as the same
spinlock is provided upon entering and exiting, the exact macro or function used for the call should not matter.
4.15.5 Floating Point Arithmetic
ESP-IDF FreeRTOS implements Lazy Context Switching for FPUs. In other words, the state of a core s FPU
registers are not immediately saved when a context switch occurs. Therefore, tasks that utilize float must be
pinned to a particular core upon creation. If not, ESP-IDF FreeRTOS will automatically pin the task in question to
whichever core the task was running on upon the task s first use of float. Likewise due to Lazy Context Switching,
only interrupt service routines of lowest priority (that is it the Level 1) can use float, higher priority interrupts do
not support FPU usage.
ESP32 does not support hardware acceleration for double precision floating point arithmetic (double). Instead
double is implemented via software hence the behavioral restrictions with regards to float do not apply to dou-
ble. Note that due to the lack of hardware acceleration, double operations may consume significantly larger
amount of CPU time in comparison to float.
4.15.6 Task Deletion
In FreeRTOS task deletion the freeing of task memory will occur immediately (within vTaskDelete()) if the task
being deleted is not currently running or is not pinned to the other core (with respect to the core vTaskDelete()
is called on). TLSP deletion callbacks will also run immediately if the same conditions are met.
However, calling vTaskDelete() to delete a task that is either currently running or pinned to the other core will
still result in the freeing of memory being delegated to the Idle Task.
4.15.7 Thread Local Storage Pointers & Deletion Callbacks
Thread Local Storage Pointers (TLSP) are pointers stored directly in the TCB. TLSP allow each task to have its own
unique set of pointers to data structures. However task deletion behavior in vanilla FreeRTOS does not automatically
free the memory pointed to by TLSP. Therefore if the memory pointed to by TLSP is not explicitly freed by the user
before task deletion, memory leak will occur.
ESP-IDF FreeRTOS provides the added feature of Deletion Callbacks. Deletion Callbacks are called automatically
during task deletion to free memory pointed to by TLSP. Each TLSP can have its own Deletion Callback. Note that
due to the to Task Deletion behavior, there can be instances where Deletion Callbacks are called in the context of

the Idle Tasks. Therefore Deletion Callbacks should never attempt to block and critical sections should be kept as
short as possible to minimize priority inversion.
Deletion callbacks are of type void (*TlsDeleteCallbackFunction_t)( int, void * ) where
the first parameter is the index number of the associated TLSP, and the second parameter is the TLSP itself.
Deletion callbacks are set alongside TLSP by calling vTaskSetThreadLocalStoragePointerAndDel-
Callback(). Calling the vanilla FreeRTOS function vTaskSetThreadLocalStoragePointer() will
simply set the TLSP s associated Deletion Callback to NULL meaning that no callback will be called for that TLSP
during task deletion. If a deletion callback is NULL, users should manually free the memory pointed to by the asso-
ciated TLSP before task deletion in order to avoid memory leak.
For more details see FreeRTOS API reference.
4.15.8 Configuring ESP-IDF FreeRTOS
The ESP-IDF FreeRTOS can be configured in the project configuration menu (idf.py menuconfig) under
Component Config/FreeRTOS. The following section highlights some of the ESP-IDF FreeRTOS configura-
tion options. For a full list of ESP-IDF FreeRTOS configurations, see FreeRTOS
CONFIG_FREERTOS_UNICORE will run ESP-IDF FreeRTOS only on PRO_CPU. Note that this is not equiva-
lent to running vanilla FreeRTOS. Note that this option may affect behavior of components other than freertos.
For more details regarding the effects of running ESP-IDF FreeRTOS on a single core, search for occurences of
CONFIG_FREERTOS_UNICORE in the ESP-IDF components.
CONFIG_FREERTOS_ASSERT_ON_UNTESTED_FUNCTION will trigger a halt in particular functions in ESP-IDF
FreeRTOS which have not been fully tested in an SMP context.
CONFIG_FREERTOS_TASK_FUNCTION_WRAPPER will enclose all task functions within a wrapper function. In
the case that a task function mistakenly returns (i.e. does not call vTaskDelete()), the call flow will return to the
wrapper function. The wrapper function will then log an error and abort the application, as illustrated below:
E (25) FreeRTOS: FreeRTOS task should not return. Aborting now!

abort() was called at PC 0x40085c53 on core 0
4.16 Hardware Abstraction

Hardware abstraction in ESP-IDF are a group of API that allow users to control peripherals at differing levels of
abstraction, as opposed to interfacing with hardware using only the ESP-IDF drivers. ESP-IDF Hardware abstraction
will likely be useful for users writing high performance bare-metal drivers, or for those attempting to port an ESP
chip to another platform.
This guide is split into the following sections:
1. Architecture
2. LL (Low Level) Layer
3. HAL (Hardware Abstraction Layer)
Warning: Hardware abstraction API (excluding the driver and xxx_types.h) should be considered an exper-
imental feature, thus cannot be considered public API. Hardware abstraction API do not adhere to the API name
changing restrictions of ESP-IDF s versioning scheme. In other words, it is possible that Hardware Abstraction
API may change in between non-major release versions.
Note: Although this document mainly focuses on hardware abstraction of peripherals (e.g., UART, SPI, I2C),
certain layers of hardware abstraction extend to other aspects of hardware as well (e.g., some of the CPU s features
are partially abstracted).

4.16.1 Architecture
Hardware abstraction in ESP-IDF is comprised of the following layers, ordered from low level (closer to hardware)
to high level (further away from hardware) of abstraction.
• Low Level (LL) Layer
• Hardware Abstraction Layer (HAL)
• Driver Layers
The LL Layer, and HAL are entirely contained within the hal component. Each layer is dependent on the layer
below it (i.e, driver depends on HAL, HAL depends on LL, LL depends on the register header files).
For a particular peripheral xxx, its hardware abstraction will generally consist of the header files described in the
table below. Files that are Target Specific will have a separate implementation for each target (i.e., a separate copy
for each chip). However, the #include directive will still be target-independent (i.e., will be the same for different
targets) as the build system will automatically include the correct version of the header and source files.
Table 21: Hardware Abstraction Header Files

Include Directive TargetDescription
Spe-
cific
#include 'soc/ Y This header contains a list of C macros specifying the various capabilities of
xxx_caps.h" the ESP32 s peripheral xxx. Hardware capabilities of a peripheral include
things such as the number of channels, DMA support, hardware FIFO/buffer
lengths, etc.
#include "soc/ Y The two headers contain a representation of a peripheral s registers in C struc-
xxx_struct.h" ture and C macro format respectively. Users can operate a peripheral at the
#include "soc/ register level via either of these two header files.
xxx_reg.h"
#include "soc/ Y If certain signals of a peripheral are mapped to a particular pin of the ESP32,
xxx_pins.h" their mappings are defined in this header as C macros.
#include "soc/ N This header is mainly used as a convenience header file to automatically include
xxx_periph.h" xxx_caps.h, xxx_struct.h, and xxx_reg.h.
#include "hal/ N This header contains type definitions and macros that are shared among the
xxx_types.h LL, HAL, and driver layers. Moreover, it is considered public API thus can
be included by the application level. The shared types and definitions usually
related to non-implementation specific concepts such as the following:
• Protocol related types/macros such a frames, modes, common bus
speeds, etc.
• Features/characteristics of an xxx peripheral that are likely to be present
on any implementation (implementation-independent) such as channels,
operating modes, signal amplification or attenuation intensities, etc.
#include "hal/ Y This header contains the Low Level (LL) Layer of hardware abstraction. LL
xxx_ll.h" Layer API are primarily used to abstract away register operations into readable
functions.
#include "hal/ Y The Hardware Abstraction Layer (HAL) is used to abstract away peripheral
xxx_hal.h" operation steps into functions (e.g., reading a buffer, starting a transmission,
handling an event, etc). The HAL is built on top of the LL Layer.
#include "driver/ N The driver layer is the highest level of ESP-IDF s hardware abstraction. Driver
xxx.h" layer API are meant to be called from ESP-IDF applications, and internally
utilize OS primitives. Thus, driver layer API are event-driven, and can used in
a multi-threaded environment.
4.16.2 LL (Low Level) Layer
The primary purpose of the LL Layer is to abstract away register field access into more easily understandable functions.
LL functions essentially translate various in/out arguments into the register fields of a peripheral in the form of get/set

functions. All the necessary bit shifting, masking, offsetting, and endianness of the register fields should be handled
by the LL functions.
//Inside xxx_ll.h
static inline void xxx_ll_set_baud_rate(xxx_dev_t *hw,

xxx_ll_clk_src_t clock_source,
uint32_t baud_rate) {
uint32_t src_clk_freq = (source_clk == XXX_SCLK_APB) ? APB_CLK_FREQ : REF_CLK_
,→FREQ;
uint32_t clock_divider = src_clk_freq / baud;

// Set clock select field
hw->clk_div_reg.divider = clock_divider >> 4;
// Set clock divider field
hw->config.clk_sel = (source_clk == XXX_SCLK_APB) ? 0 : 1;
}
static inline uint32_t xxx_ll_get_rx_byte_count(xxx_dev_t *hw) {

return hw->status_reg.rx_cnt;
}
The code snippet above illustrates typical LL functions for a peripheral xxx. LL functions typically have the following
characteristics:
• All LL functions are defined as static inline so that there is minimal overhead when calling these
functions due to compiler optimization.
• The first argument should be a pointer to a xxx_dev_t type. The xxx_dev_t type is a structure repre-
senting the peripheral s registers, thus the first argument is always a pointer to the starting address of the
peripheral s registers. Note that in some cases where the peripheral has multiple channels with identical
register layouts, xxx_dev_t *hw may point to the registers of a particular channel instead.
• LL functions should be short and in most cases are deterministic. In other words, the worst case runtime of
the LL function can be determined at compile time. Thus, any loops in LL functions should be finite bounded;
however, there are currently a few exceptions to this rule.
• LL functions are not thread safe, it is the responsibility of the upper layers (driver layer) to ensure that registers
or register fields are not accessed concurrently.
4.16.3 HAL (Hardware Abstraction Layer)
The HAL layer models the operational process of a peripheral as a set of general steps, where each step has an
associated function. For each step, the details of a peripheral s register implementation (i.e., which registers need to
be set/read) are hidden (abstracted away) by the HAL. By modelling peripheral operation as a set of functional steps,
any minor hardware implementation differences of the peripheral between different targets or chip versions can be
abstracted away by the HAL (i.e., handled transparently). In other words, the HAL API for a particular peripheral
will remain mostly the same across multiple targets/chip versions.
The following HAL function examples are selected from the Watchdog Timer HAL as each function maps to one
of the steps in a WDT s operation life cycle, thus illustrating how a HAL abstracts a peripheral s operation into
functional steps.
// Initialize one of the WDTs

void wdt_hal_init(wdt_hal_context_t *hal, wdt_inst_t wdt_inst, uint32_t prescaler,␣
,→bool enable_intr);
// Configure a particular timeout stage of the WDT

void wdt_hal_config_stage(wdt_hal_context_t *hal, wdt_stage_t stage, uint32_t␣
,→timeout, wdt_stage_action_t behavior);
// Start the WDT

void wdt_hal_enable(wdt_hal_context_t *hal);


// Feed (i.e., reset) the WDT
void wdt_hal_feed(wdt_hal_context_t *hal);
// Handle a WDT timeout

void wdt_hal_handle_intr(wdt_hal_context_t *hal);
// Stop the WDT

void wdt_hal_disable(wdt_hal_context_t *hal);
// De-initialize the WDT

void wdt_hal_deinit(wdt_hal_context_t *hal);
HAL functions will generally have the following characteristics:

• The first argument to a HAL function has the xxx_hal_context_t * type. The HAL context type is used
to store information about a particular instance of the peripheral (i.e. the context instance). A HAL context is
initialized by the xxx_hal_init() function and can store information such as the following:
– The channel number of this instance
– Pointer to the peripheral s (or channel s) registers (i.e., a xxx_dev_t * type)
– Information about an ongoing transaction (e.g., pointer to DMA descriptor list in use)
– Some configuration values for the instance (e.g., channel configurations)
– Variables to maintain state information regarding the instance (e.g., a flag to indicate if the instance is
waiting for transaction to complete)
• HAL functions should not contain any OS primitives such as queues, semaphores, mutexes, etc. All synchro-
nization/concurrency should be handled at higher layers (e.g., the driver).
• Some peripherals may have steps that cannot be further abstracted by the HAL, thus will end up being a direct
wrapper (or macro) for an LL function.
• Some HAL functions may be placed in IRAM thus may carry an IRAM_ATTR or be placed in a separate
xxx_hal_iram.c source file.
4.17 High-Level Interrupts

The Xtensa architecture has support for 32 interrupts, divided over 8 levels, plus an assortment of exceptions. On the
ESP32, the interrupt mux allows most interrupt sources to be routed to these interrupts using the interrupt allocator.
Normally, interrupts will be written in C, but ESP-IDF allows high-level interrupts to be written in assembly as well,
allowing for very low interrupt latencies.
4.17.1 Interrupt Levels
Level Symbol Remark

1 N/A Exception and level 0 interrupts. Handled by ESP-IDF
2-3 N/A Medium level interrupts. Handled by ESP-IDF
4 xt_highint4 Free to use (See 1)
5 xt_highint5 Normally used by ESP-IDF debug logic (See 1)
NMI xt_nmi Free to use
dbg xt_debugexception Debug exception. Called on e.g. a BREAK instruction. (See 2)
1. ESP-IDF debug logic can be configured to run on xt_highint4 or xt_highint5 in CON-
FIG_ESP_SYSTEM_CHECK_INT_LEVEL. Bluetooth s interrupt can be configured to run on level 4
by enabling CONFIG_BTDM_CTRL_HLI. If CONFIG_BTDM_CTRL_HLI is enabled, ESP-IDF debug logic
must be running on level 5 interrupt.
2. If CONFIG_BTDM_CTRL_HLI is enabled, xt_debugexception is used to fix live lock issue in ESP32 ECO3.
Using these symbols is done by creating an assembly file (suffix .S) and defining the named symbols, like this:

.section .iram1,"ax"
.global xt_highint5
.type xt_highint5,@function
.align 4
xt_highint5:
... your code here
rsr a0, EXCSAVE_5
rfi 5
For a real-life example, see the esp_system/port/soc/esp32/highint_hdl.S file; the panic handler interrupt is imple-
mented there.
4.17.2 Notes
• Do not call C code from a high-level interrupt; because these interrupts still run in critical sections, this can
cause crashes. (The panic handler interrupt does call normal C code, but this is OK because there is no intention
of returning to the normal code flow afterwards.)
And if CONFIG_BTDM_CTRL_HLI is enabled, it does call normal C code in high-level interrupt, but this is
OK becase we add some protection for it.
• Make sure your assembly code gets linked in. If the interrupt handler symbol is the only symbol the rest of the
code uses from this file, the linker will take the default ISR instead and not link the assembly file into the final
project. To get around this, in the assembly file, define a symbol, like this:
.global ld_include_my_isr_file
ld_include_my_isr_file:
The symbol is called ld_include_my_isr_file here but can have any arbitrary name not defined anywhere
else.
Then, in the component CMakeLists.txt, add this file as an unresolved symbol to the ld command line arguments:
target_link_libraries(${COMPONENT_TARGET} "-u ld_include_my_isr_file")
This should cause the linker to always include a file defining ld_include_my_isr_file, causing the ISR to
always be linked in.
• High-level interrupts can be routed and handled using esp_intr_alloc and associated functions. The handler
and handler arguments to esp_intr_alloc must be NULL, however.
• In theory, medium priority interrupts could also be handled in this way. For now, ESP-IDF does not support
this.
4.18 JTAG Debugging

This document provides a guide to installing OpenOCD for ESP32 and debugging using GDB. The document is
structured as follows:
Introduction Introduction to the purpose of this guide.
How it Works? Description how ESP32, JTAG interface, OpenOCD and GDB are interconnected and working to-
gether to enable debugging of ESP32.
Selecting JTAG Adapter What are the criteria and options to select JTAG adapter hardware.
Setup of OpenOCD Procedure to install OpenOCD and verify that it is installed.
Configuring ESP32 Target Configuration of OpenOCD software and setting up of JTAG adapter hardware, which
together make up the debugging target.
Launching Debugger Steps to start up a debug session with GDB from Eclipse and from Command Line.
Debugging Examples If you are not familiar with GDB, check this section for debugging examples provided from
Eclipse as well as from Command Line.
Building OpenOCD from Sources Procedure to build OpenOCD from sources for Windows, Linux and macOS op-
erating systems.

Tips and Quirks This section provides collection of tips and quirks related to JTAG debugging of ESP32 with
OpenOCD and GDB.
4.18.1 Introduction
The ESP32 has two powerful Xtensa cores, allowing for a great deal of variety of program architectures. The FreeR-
TOS OS that comes with ESP-IDF is capable of multi-core preemptive scheduling, allowing for an intuitive way of
writing software.
The downside of the ease of programming is that debugging without the right tools is harder: figuring out a bug that
is caused by two threads, running even simultaneously on two different CPU cores, can take a long time when all you
have are printf() statements. A better (and in many cases quicker) way to debug such problems is by using a
debugger, connected to the processors over a debug port.
Espressif has ported OpenOCD to support the ESP32 processor and the multi-core FreeRTOS which is the founda-
tion of most ESP32 apps). Additionally, some extra tools have been written to provide extra features that OpenOCD
does not support natively.
This document provides a guide to installing OpenOCD for ESP32 and debugging using GDB under Linux, Windows
and macOS. Except for OS specific installation procedures, the s/w user interface and use procedures are the same
across all supported operating systems.
Note: Screenshots presented in this document have been made for Eclipse Neon 3 running on Ubuntu 16.04 LTS.
There may be some small differences in what a particular user interface looks like, depending on whether you are
using Windows, macOS or Linux and / or a different release of Eclipse.
4.18.2 How it Works?
The key software and hardware components that perform debugging of ESP32 with OpenOCD over JTAG (Joint
Test Action Group) interface is presented in the diagram below under the Debugging With JTAG label. These
components include xtensa-esp32-elf-gdb debugger, OpenOCD on chip debugger, and the JTAG adapter connected
to ESP32 target.
Fig. 33: JTAG debugging - overview diagram

Likewise, the Application Loading and Monitoring label indicates the key software and hardware components that
allow an application to be compiled, built, and flashed to ESP32, as well as to provide means to monitor diagnostic
messages from ESP32.
Debugging With JTAG and Application Loading and Monitoring is integrated under the Eclipse IDE in order
to provide a quick and easy transition between writing/compiling/loading/debugging code. The Eclipse IDE (and the
integrated debugging software) is available for Windows, Linux and macOS platforms. Depending on user prefer-
ences, both the debugger and idf.py build can also be used directly from terminal/command line, instead of
Eclipse.
If the ESP-WROVER-KIT is used, then connection from PC to ESP32 is done effectively with a single USB cable.
This is made possible by the FT2232H chip, which provides two USB channels, one for JTAG and the other for
UART connection.
4.18.3 Selecting JTAG Adapter
The quickest and most convenient way to start with JTAG debugging is by using ESP-WROVER-KIT. Each version of
this development board has JTAG interface already built in. No need for an external JTAG adapter and extra wiring
/ cable to connect JTAG to ESP32. ESP-WROVER-KIT is using FT2232H JTAG interface operating at 20 MHz
clock speed, which is difficult to achieve with an external adapter.
If you decide to use separate JTAG adapter, look for one that is compatible with both the voltage levels on the ESP32
as well as with the OpenOCD software. The JTAG port on the ESP32 is an industry-standard JTAG port which
lacks (and does not need) the TRST pin. The JTAG I/O pins all are powered from the VDD_3P3_RTC pin (which
normally would be powered by a 3.3 V rail) so the JTAG adapter needs to be able to work with JTAG pins in that
voltage range.
On the software side, OpenOCD supports a fair amount of JTAG adapters. See http://openocd.org/doc/html/
Debug-Adapter-Hardware.html for an (unfortunately slightly incomplete) list of the adapters OpenOCD works with.
This page lists SWD-compatible adapters as well; take note that the ESP32 does not support SWD. JTAG adapters
that are hardcoded to a specific product line, e.g. ST-LINK debugging adapters for STM32 families, will not work.
The minimal signalling to get a working JTAG connection are TDI, TDO, TCK, TMS and GND. Some JTAG de-
buggers also need a connection from the ESP32 power line to a line called e.g. Vtar to set the working voltage. SRST
can optionally be connected to the CH_PD of the ESP32, although for now, support in OpenOCD for that line is
pretty minimal.
ESP-Prog is an example for using an external board for debugging by connecting it to the JTAG pins of ESP32.
4.18.4 Setup of OpenOCD
If you have already set up ESP-IDF with CMake build system according to the Getting Started Guide, then OpenOCD
is already installed. After setting up the environment in your terminal, you should be able to run OpenOCD. Check
this by executing the following command:
openocd --version
The output should be as follows (although the version may be more recent than listed here):
Open On-Chip Debugger v0.10.0-esp32-20190708 (2019-07-08-11:04)

Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
You may also verify that OpenOCD knows where its configuration scripts are located by printing the value of
OPENOCD_SCRIPTS environment variable, by typing echo $OPENOCD_SCRIPTS (for Linux and macOS)
or echo %OPENOCD_SCRIPTS% (for Windows). If a valid path is printed, then OpenOCD is set up correctly.
If any of these steps do not work, please go back to the setting up the tools section of the Getting Started Guide.

Note: It is also possible to build OpenOCD from source. Please refer to Building OpenOCD from Sources section
for details.
4.18.5 Configuring ESP32 Target
Once OpenOCD is installed, you can proceed to configuring the ESP32 target (i.e ESP32 board with JTAG interface).
Configuring the target is split into the following three steps:
• Configure and connect JTAG interface
• Run OpenOCD
• Upload application for debugging
Configure and connect JTAG interface
This step depends on the JTAG and ESP32 board you are using (see the two cases described below).
Configure ESP-WROVER-KIT JTAG Interface All versions of ESP-WROVER-KIT boards have built-in
JTAG functionality. Putting it to work requires setting jumpers or DIP switches to enable JTAG functionality, and
configuring USB drivers. Please refer to step by step instructions below.
Configure Hardware
• Enable on-board JTAG functionality by setting JP8 according to ESP-WROVER-KIT V4.1 Getting Started
Guide, Section Setup Options.
• Verify if ESP32 pins used for JTAG communication are not connected to some other h/w that may disturb
JTAG operation:
Table 22: ESP32 JTAG pins

ESP32 Pin JTAG Signal
MTDO / GPIO15 TDO
MTDI / GPIO12 TDI
MTCK / GPIO13 TCK
MTMS / GPIO14 TMS
GND GND
Configure USB Drivers Install and configure USB drivers, so OpenOCD is able to communicate with JTAG
interface on ESP-WROVER-KIT board as well as with UART interface used to upload application for flash. Follow
steps below specific to your operating system.
Note: ESP-WROVER-KIT uses an FT2232 adapter. The following instructions can also be used for other FT2232
based JTAG adapters.
Windows
1. Using standard USB A / micro USB B cable connect ESP-WROVER-KIT to the computer. Switch the ESP-
WROVER-KIT on.
2. Wait until USB ports of ESP-WROVER-KIT are recognized by Windows and drives are installed. If they do
not install automatically, then download them from https://www.ftdichip.com/Drivers/D2XX.htm and install
manually.
3. Download Zadig tool (Zadig_X.X.exe) from https://zadig.akeo.ie/ and run it.
4. In Zadig tool go to Options and check List All Devices .

5. Check the list of devices that should contain two ESP-WROVER-KIT specific USB entries: Dual RS232-HS
(Interface 0) and Dual RS232-HS (Interface 1) . The driver name would be FTDIBUS (vxxxx) and
USB ID: 0403 6010.
Fig. 34: Configuration of JTAG USB driver in Zadig tool
6. The first device (Dual RS232-HS (Interface 0)) is connected to the JTAG port of the ESP32. Original FT-
DIBUS (vxxxx) driver of this device should be replaced with WinUSB (v6xxxxx) . To do so, select Dual
RS232-HS (Interface 0) and reinstall attached driver to the WinUSB (v6xxxxx) , see picture above.
Note: Do not change the second device Dual RS232-HS (Interface 1) . It is routed to ESP32 s serial port
(UART) used for upload of application to ESP32 s flash.
Now ESP-WROVER-KIT s JTAG interface should be available to the OpenOCD. To carry on with debugging
environment setup, proceed to section Run OpenOCD.
Linux
1. Using standard USB A / micro USB B cable connect ESP-WROVER-KIT board to the computer. Power on
the board.
2. Open a terminal, enter ls -l /dev/ttyUSB* command and check, if board s USB ports are recognized
by the OS. You are looking for similar result:
user-name@computer-name:~/esp$ ls -l /dev/ttyUSB*
crw-rw---- 1 root dialout 188, 0 Jul 10 19:04 /dev/ttyUSB0
crw-rw---- 1 root dialout 188, 1 Jul 10 19:04 /dev/ttyUSB1
3. Following section Permissions delegation in OpenOCD s README, set up the access permissions to both
USB ports.
4. Log off and login, then cycle the power to the board to make the changes effective. In terminal enter again ls
-l /dev/ttyUSB* command to verify, if group-owner has changed from dialout to plugdev:
user-name@computer-name:~/esp$ ls -l /dev/ttyUSB*
crw-rw-r-- 1 root plugdev 188, 0 Jul 10 19:07 /dev/ttyUSB0
crw-rw-r-- 1 root plugdev 188, 1 Jul 10 19:07 /dev/ttyUSB1
If you see similar result and you are a member of plugdev group, then the set up is complete.
The /dev/ttyUSBn interface with lower number is used for JTAG communication. The other interface is
routed to ESP32 s serial port (UART) used for upload of application to ESP32 s flash.
Now ESP-WROVER-KIT s JTAG interface should be available to the OpenOCD. To carry on with debugging
environment setup, proceed to section Run OpenOCD.

MacOS On macOS, using FT2232 for JTAG and serial port at the same time needs some additional steps. When
the OS loads FTDI serial port driver, it does so for both channels of FT2232 chip. However only one of these channels
is used as a serial port, while the other is used as JTAG. If the OS has loaded FTDI serial port driver for the channel
used for JTAG, OpenOCD will not be able to connect to the chip. There are two ways around this:
1. Manually unload the FTDI serial port driver before starting OpenOCD, start OpenOCD, then load the serial
port driver.
2. Modify FTDI driver configuration so that it doesn t load itself for channel B of FT2232 chip, which is the
channel used for JTAG on ESP-WROVER-KIT.
Manually unloading the driver

1. Install FTDI driver from https://www.ftdichip.com/Drivers/VCP.htm
2. Connect USB cable to the ESP-WROVER-KIT.
3. Unload the serial port driver:
sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver
In some cases you may need to unload Apple s FTDI driver as well:
• macOS < 10.15:
sudo kextunload -b com.apple.driver.AppleUSBFTDI
• macOS 10.15:
sudo kextunload -b com.apple.DriverKit-AppleUSBFTDI
Warning: Attempting to use serial over the wrong channel with the FTDI driver will cause a kernel panic.
The ESP-WROVER-KIT uses channel A for JTAG and channel B for serial.
4. Run OpenOCD:
openocd -f board/esp32-wrover-kit-3.3v.cfg
5. In another terminal window, load FTDI serial port driver again:
sudo kextload -b com.FTDI.driver.FTDIUSBSerialDriver
Note: If you need to restart OpenOCD, there is no need to unload FTDI driver again just stop OpenOCD and
start it again. The driver only needs to be unloaded if ESP-WROVER-KIT was reconnected or power was toggled.
This procedure can be wrapped into a shell script, if desired.
Modifying FTDI driver In a nutshell, this approach requires modification to FTDI driver configuration file, which
prevents the driver from being loaded for channel B of FT2232H.
Note: Other boards may use channel A for JTAG, so use this option with caution.
Warning: This approach also needs signature verification of drivers to be disabled, so may not be acceptable
for all users.
1. Open FTDI driver configuration file using a text editor (note sudo):
sudo nano /Library/Extensions/FTDIUSBSerialDriver.kext/Contents/Info.plist
2. Find and delete the following lines:

<key>FT2232H_B</key>
<dict>
<key>CFBundleIdentifier</key>
<string>com.FTDI.driver.FTDIUSBSerialDriver</string>
<key>IOClass</key>
<string>FTDIUSBSerialDriver</string>
<key>IOProviderClass</key>
<string>IOUSBInterface</string>
<key>bConfigurationValue</key>
<integer>1</integer>
<key>bInterfaceNumber</key>
<key>bcdDevice</key>
<key>idProduct</key>
<key>idVendor</key>
</dict>
3. Save and close the file

4. Disable driver signature verification:
1. Open Apple logo menu, choose Restart
2. When you hear the chime after reboot, press CMD+R immediately
3. Once Recovery mode starts up, open Terminal
4. Run the command:
csrutil enable --without kext
5. Restart again
After these steps, serial port and JTAG can be used at the same time.
To carry on with debugging environment setup, proceed to section Run OpenOCD.
Configure Other JTAG Interface Refer to section Selecting JTAG Adapter for guidance what JTAG interface
to select, so it is able to operate with OpenOCD and ESP32. Then follow three configuration steps below to get it
working.
Configure Hardware
1. Identify all pins / signals on JTAG interface and ESP32 board, that should be connected to establish commu-
nication.

MTDO / GPIO15 TDO
MTDI / GPIO12 TDI
MTCK / GPIO13 TCK
MTMS / GPIO14 TMS
GND GND
2. Verify if ESP32 pins used for JTAG communication are not connected to some other h/w that may disturb
JTAG operation.
3. Connect identified pin / signals of ESP32 and JTAG interface.
Configure Drivers You may need to install driver s/w to make JTAG work with computer. Refer to documentation
of JTAG adapter, that should provide related details.

Connect Connect JTAG interface to the computer. Power on ESP32 and JTAG interface boards. Check if JTAG
interface is visible by computer.
To carry on with debugging environment setup, proceed to section Run OpenOCD.
Run OpenOCD
Once target is configured and connected to computer, you are ready to launch OpenOCD.
Open a terminal and set it up for using the ESP-IDF as described in the setting up the environment section of the
Getting Started Guide. Then run OpenOCD (this command works on Windows, Linux, and macOS):
openocd -f board/esp32-wrover-kit-3.3v.cfg
Note: The files provided after -f above are specific for ESP-WROVER-KIT with ESP32-WROOM-32 module.
You may need to provide different files depending on the hardware that is used. For guidance see Configuration of
OpenOCD for specific target.
For example, board/esp32c3-ftdi.cfg can be used for a custom board with an FT2232H or FT232H chip
used for JTAG connection, or with ESP-Prog.
You should now see similar output (this log is for ESP-WROVER-KIT with ESP32-WROOM-32 module):
user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32-wrover-kit-3.3v.cfg

Open On-Chip Debugger v0.10.0-esp32-20190708 (2019-07-08-11:04)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
none separate
adapter speed: 20000 kHz
force hard breakpoints
Info : ftdi: if you experience problems at higher adapter clocks, try the command
,→"ftdi_tdo_sample_edge falling"
Info : clock speed 20000 kHz

Info : JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica),␣
,→part: 0x2003, ver: 0x1)
Info : JTAG tap: esp32.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica),␣
,→part: 0x2003, ver: 0x1)
Info : esp32: Debug controller was reset (pwrstat=0x5F, after clear 0x0F).
Info : esp32: Core was reset (pwrstat=0x5F, after clear 0x0F).
• If there is an error indicating permission problems, please see section on Permissions delegation in the
OpenOCD README file located in the ~/esp/openocd-esp32 directory.
• In case there is an error in finding the configuration files, e.g. Can't find board/esp32-wrover-
kit-3.3v.cfg, check if the OPENOCD_SCRIPTS environment variable is set correctly. This variable is
used by OpenOCD to look for the files specified after the -f option. See Setup of OpenOCD section for details.
Also check if the file is indeed under the provided path.
• If you see JTAG errors (e.g., ...all ones or ...all zeroes), please check your JTAG connections,
whether other signals are connected to JTAG besides ESP32 s pins, and see if everything is powered on
correctly.
Upload application for debugging
Build and upload your application to ESP32 as usual, see Step 8. Build the Project.
Another option is to write application image to flash using OpenOCD via JTAG with commands like this:
openocd -f board/esp32-wrover-kit-3.3v.cfg -c "program_esp filename.bin 0x10000␣

,→verify exit"

OpenOCD flashing command program_esp has the following format:

program_esp <image_file> <offset> [verify] [reset] [exit]
• image_file - Path to program image file.
• offset - Offset in flash bank to write image.
• verify - Optional. Verify flash contents after writing.
• reset - Optional. Reset target after programing.
• exit - Optional. Finally exit OpenOCD.
You are now ready to start application debugging. Follow the steps described in the section below.
4.18.6 Launching Debugger
The toolchain for ESP32 features GNU Debugger, in short GDB. It is available with other toolchain programs under
filename: xtensa-esp32-elf-gdb. GDB can be called and operated directly from command line in a terminal. Another
option is to call it from within IDE (like Eclipse, Visual Studio Code, etc.) and operate indirectly with help of GUI
instead of typing commands in a terminal.
Both options of using debugger are discussed under links below.
• Eclipse
• Command Line
It is recommended to first check if debugger works from Command Line and then move to using Eclipse.
4.18.7 Debugging Examples
This section is intended for users not familiar with GDB. It presents example debugging session from Eclipse using
simple application available under get-started/blink and covers the following debugging actions:
1. Navigating through the code, call stack and threads
2. Setting and clearing breakpoints
3. Halting the target manually
4. Stepping through the code
5. Checking and setting memory
6. Watching and setting program variables
7. Setting conditional breakpoints
Similar debugging actions are provided using GDB from Command Line.
Before proceeding to examples, set up your ESP32 target and load it with get-started/blink.
4.18.8 Building OpenOCD from Sources
Please refer to separate documents listed below, that describe build process.
Building OpenOCD from Sources for Windows
The following instructions are alternative to downloading binary OpenOCD from Espressif GitHub. To quickly setup
the binary OpenOCD, instead of compiling it yourself, backup and proceed to section Setup of OpenOCD.
Note: Following instructions are assumed to be runned in MSYS2 environment with MINGW32 subsystem!

Install Dependencies Install packages that are required to compile OpenOCD:
pacman -S --noconfirm --needed autoconf automake git make \

mingw-w64-i686-gcc \
mingw-w64-i686-toolchain \
mingw-w64-i686-libtool \
mingw-w64-i686-pkg-config \
mingw-w64-cross-winpthreads-git \
p7zip
Download Sources of OpenOCD The sources for the ESP32-enabled variant of OpenOCD are available from
Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following
commands:
cd ~/esp
git clone --recursive https://github.com/espressif/openocd-esp32.git
The clone of sources should be now saved in ~/esp/openocd-esp32 directory.
Downloading libusb Build and export variables for a following OpenOCD compilation:
wget https://github.com/libusb/libusb/releases/download/v1.0.22/libusb-1.0.22.7z
7z x -olibusb ./libusb-1.0.22.7z
export CPPFLAGS="$CPPFLAGS -I${PWD}/libusb/include/libusb-1.0"
export LDFLAGS="$LDFLAGS -L${PWD}/libusb/MinGW32/.libs/dll"
Build OpenOCD Proceed with configuring and building OpenOCD:
cd ~/esp/openocd-esp32
export CPPFLAGS="$CPPFLAGS -D__USE_MINGW_ANSI_STDIO=1 -Wno-error"; export CFLAGS="
,→$CFLAGS -Wno-error"
./bootstrap
./configure --disable-doxygen-pdf --enable-ftdi --enable-jlink --enable-ulink --
,→build=i686-w64-mingw32 --host=i686-w64-mingw32
make
cp ../libusb/MinGW32/dll/libusb-1.0.dll ./src
cp /opt/i686-w64-mingw32/bin/libwinpthread-1.dll ./src
Optionally you can add make install step at the end. Skip it, if you have an existing OpenOCD (from e.g.
another development platform), as it may get overwritten. Also you could use export DESTDIR="/custom/
install/dir"; make install.
Note:
• Should an error occur, resolve it and try again until the command make works.
• If there is a submodule problem from OpenOCD, please cd to the openocd-esp32 directory and input
git submodule update --init.
• If the ./configure is successfully run, information of enabled JTAG will be printed under OpenOCD
configuration summary.
• If the information of your device is not shown in the log, use ./configure to enable it as described in
../openocd-esp32/doc/INSTALL.txt.
• For details concerning compiling OpenOCD, please refer to openocd-esp32/README.Windows.
• Don t forget to copy libusb-1.0.dll and libwinpthread-1.dll into OOCD_INSTALLDIR/bin from ~/esp/
openocd-esp32/src.
Once make process is successfully completed, the executable of OpenOCD will be saved in ~/esp/openocd-
esp32/src directory.

Full Listing A complete described previously process is provided below for the faster execution, e.g. as a shell
script:
pacman -S --noconfirm --needed autoconf automake git make mingw-w64-i686-gcc mingw-
,→w64-i686-toolchain mingw-w64-i686-libtool mingw-w64-i686-pkg-config mingw-w64-
,→cross-winpthreads-git p7zip
cd ~/esp
wget https://github.com/libusb/libusb/releases/download/v1.0.22/libusb-1.0.22.7z
7z x -olibusb ./libusb-1.0.22.7z
export CPPFLAGS="$CPPFLAGS -I${PWD}/libusb/include/libusb-1.0"; export LDFLAGS="
,→$LDFLAGS -L${PWD}/libusb/MinGW32/.libs/dll"
export CPPFLAGS="$CPPFLAGS -D__USE_MINGW_ANSI_STDIO=1 -Wno-error"; export CFLAGS="

,→$CFLAGS -Wno-error"
./bootstrap
./configure --disable-doxygen-pdf --enable-ftdi --enable-jlink --enable-ulink --
,→build=i686-w64-mingw32 --host=i686-w64-mingw32
make
cp ../libusb/MinGW32/dll/libusb-1.0.dll ./src
cp /opt/i686-w64-mingw32/bin/libwinpthread-1.dll ./src
# # optional
# export DESTDIR="$PWD"
# make install
# cp ./src/libusb-1.0.dll $DESTDIR/mingw32/bin
# cp ./src/libwinpthread-1.dll $DESTDIR/mingw32/bin
Next Steps To carry on with debugging environment setup, proceed to section Configuring ESP32 Target.
Building OpenOCD from Sources for Linux
commands:
cd ~/esp
Install Dependencies Install packages that are required to compile OpenOCD.
Note: Install the following packages one by one, check if installation was successful and then proceed to the next
package. Resolve reported problems before moving to the next step.
sudo apt-get install make

sudo apt-get install libtool
sudo apt-get install pkg-config
sudo apt-get install autoconf
sudo apt-get install automake


sudo apt-get install texinfo
sudo apt-get install libusb-1.0
Note:
• Version of pkg-config should be 0.2.3 or above.
• Version of autoconf should be 2.6.4 or above.
• Version of automake should be 1.9 or above.
• When using USB-Blaster, ASIX Presto, OpenJTAG and FT2232 as adapters, drivers libFTDI and FTD2XX
need to be downloaded and installed.
• When using CMSIS-DAP, HIDAPI is needed.
./bootstrap
./configure
make
Optionally you can add sudo make install step at the end. Skip it, if you have an existing OpenOCD (from
e.g. another development platform), as it may get overwritten.
Note:
• For details concerning compiling OpenOCD, please refer to openocd-esp32/README.
Once make process is successfully completed, the executable of OpenOCD will be saved in ~/openocd-esp32/
bin directory.
Building OpenOCD from Sources for MacOS
commands:
cd ~/esp

Install Dependencies Install packages that are required to compile OpenOCD using Homebrew:
brew install automake libtool libusb wget [email protected] pkg-config
./bootstrap
./configure
make
Optionally you can add sudo make install step at the end. Skip it, if you have an existing OpenOCD (from
e.g. another development platform), as it may get overwritten.
Note:
• For details concerning compiling OpenOCD, please refer to openocd-esp32/README.OSX.
Once make process is successfully completed, the executable of OpenOCD will be saved in ~/esp/openocd-
esp32/src/openocd directory.
The examples of invoking OpenOCD in this document assume using pre-built binary distribution described in section
Setup of OpenOCD.
To use binaries build locally from sources, change the path to OpenOCD executable to src/openocd and set
the OPENOCD_SCRIPTS environment variable so that OpenOCD can find the configuration files. For Linux and
macOS:
export OPENOCD_SCRIPTS=$PWD/tcl
For Windows:
cd %USERPROFILE%\esp\openocd-esp32
set "OPENOCD_SCRIPTS=%CD%\tcl"
Example of invoking OpenOCD build locally from sources, for Linux and macOS:
src/openocd -f board/esp32-wrover-kit-3.3v.cfg
and Windows:
src\openocd -f board\esp32-wrover-kit-3.3v.cfg
4.18.9 Tips and Quirks
This section provides collection of links to all tips and quirks referred to from various parts of this guide.

Tips and Quirks
This section provides collection of all tips and quirks referred to from various parts of this guide.
Breakpoints and watchpoints available ESP32 debugger supports 2 hardware implemented breakpoints and
64 software ones. Hardware breakpoints are implemented by ESP32 chip s logic and can be set anywhere
in the code: either in flash or IRAM program s regions. Additionally there are 2 types of software break-
points implemented by OpenOCD: flash (up to 32) and IRAM (up to 32) breakpoints. Currently GDB can not
set software breakpoints in flash. So until this limitation is removed those breakpoints have to be emulated by
OpenOCD as hardware ones (see below for details). ESP32 also supports two watchpoints, so two variables can be
watched for change or read by the GDB command watch myVariable. Note that menuconfig option CON-
FIG_FREERTOS_WATCHPOINT_END_OF_STACK uses the 2nd watchpoint and will not provide expected results,
if you also try to use it within OpenOCD / GDB. See menuconfig s help for detailed description.
What else should I know about breakpoints? Emulating part of hardware breakpoints using software flash ones
means that the GDB command hb myFunction which is invoked for function in flash will use pure hardware
breakpoint if it is avalable otherwise one of the 32 software flash breakpoints is used. The same rule applies to b
myFunction-like commands. In this case GDB will decide what type of breakpoint to set itself. If myFunction
is resided in writable region (IRAM) software IRAM breakpoint will be used otherwise hardware or software flash
breakpoint is used as it is done for hb command.
Flash Mappings vs SW Flash Breakpoints In order to set/clear software breakpoints in flash, OpenOCD needs
to know their flash addresses. To accomplish conversion from the ESP32 address space to the flash one, OpenOCD
uses mappings of program s code regions resided in flash. Those mappings are kept in the image header which is
prepended to program binary data (code and data segments) and is specific to every application image written to the
flash. So to support software flash breakpoints OpenOCD should know where application image under debugging is
resided in the flash. By default OpenOCD reads partition table at 0x8000 and uses mappings from the first found
application image, but there can be the cases when it will not work, e.g. partition table is not at standard flash location
or even there can be multiple images: one factory and two OTA and you may want to debbug any of them. To cover
all possible debugging scenarios OpenOCD supports special command which can be used to set arbitrary location of
application image to debug. The command has the following format:
esp appimage_offset <offset>
Offset should be in hex format. To reset to the default behaviour you can specify -1 as offset.
Note: Since GDB requests memory map from OpenOCD only once when connecting to it, this command should
be specified in one of the TCL configuration files, or passed to OpenOCD via its command line. In the latter case
command line should look like below:
openocd -f board/esp32-wrover-kit-3.3v.cfg -c "init; halt; esp appimage_offset␣

,→0x210000"
Another option is to execute that command via OpenOCD telnet session and then connect GDB, but it seems to be
less handy.
Why stepping with next does not bypass subroutine calls? When stepping through the code with next
command, GDB is internally setting a breakpoint (one out of two available) ahead in the code to bypass the subroutine
calls. This functionality will not work, if the two available breakpoints are already set elsewhere in the code. If this
is the case, delete breakpoints to have one spare . With both breakpoints already used, stepping through the code
with next command will work as like with step command and debugger will step inside subroutine calls.
Support options for OpenOCD at compile time ESP-IDF has some support options for OpenOCD debugging
which can be set at compile time:

• CONFIG_ESP32_DEBUG_OCDAWARE is enabled by default. If a panic or unhandled exception is thrown and

a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger.
• CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK (disabled by default) sets watchpoint index 1 (the
second of two) at the end of any task stack. This is the most accurate way to debug task stack overflows.
Click the link for more details.
Please see the project configuration menu menu for more details on setting compile-time options.
FreeRTOS support OpenOCD has explicit support for the ESP-IDF FreeRTOS. GDB can see FreeRTOS tasks
as threads. Viewing them all can be done using the GDB i threads command, changing to a certain task is
done with thread n, with n being the number of the thread. FreeRTOS detection can be disabled in target s
configuration. For more details see Configuration of OpenOCD for specific target.
Why to set SPI flash voltage in OpenOCD configuration? The MTDI pin of ESP32, being among four pins
used for JTAG communication, is also one of ESP32 s bootstrapping pins. On power up ESP32 is sampling binary
level on MTDI to set it s internal voltage regulator used to supply power to external SPI flash chip. If binary level on
MDTI pin on power up is low, the voltage regulator is set to deliver 3.3 V, if it is high, then the voltage is set to 1.8
V. The MTDI pin should have a pull-up or may rely on internal weak pull down resistor (see ESP32 Series Datasheet
for details), depending on the type of SPI chip used. Once JTAG is connected, it overrides the pull-up or pull-down
resistor that is supposed to do the bootstrapping.
To handle this issue OpenOCD s board configuration file (e.g. board\esp32-wrover-kit-3.3v.cfg for
ESP-WROVER-KIT board) provides ESP32_FLASH_VOLTAGE parameter to set the idle state of the TDO line to
a specified binary level, therefore reducing the chance of a bad bootup of application due to incorrect flash voltage.
Check specification of ESP32 module connected to JTAG, what is the power supply voltage of SPI flash chip. Then
set ESP32_FLASH_VOLTAGE accordingly. Most WROOM modules use 3.3 V flash. WROVER earlier than
ESP32-WROVER-B use 1.8 V flash, while ESP32-WROVER-B and -E modules use 3.3 V flash.
Optimize JTAG speed In order to achieve higher data rates and minimize number of dropped packets it is rec-
ommended to optimize setting of JTAG clock frequency, so it is at maximum and still provides stable operation of
JTAG. To do so use the following tips.
1. The upper limit of JTAG clock frequency is 20 MHz if CPU runs at 80 MHz, or 26 MHz if CPU runs at 160
MHz or 240 MHz.
2. Depending on particular JTAG adapter and the length of connecting cables, you may need to reduce JTAG
frequency below 20 / 26 MHz.
3. In particular reduce frequency, if you get DSR/DIR errors (and they do not relate to OpenOCD trying to read
from a memory range without physical memory being present there).
4. ESP-WROVER-KIT operates stable at 20 / 26 MHz.
What is the meaning of debugger s startup commands? On startup, debugger is issuing sequence of commands
to reset the chip and halt it at specific line of code. This sequence (shown below) is user defined to pick up at most
convenient / appropriate line and start debugging.
• set remote hardware-watchpoint-limit 2 Restrict GDB to using two hardware watchpoints
supported by the chip, 2 for ESP32. For more information see https://sourceware.org/gdb/onlinedocs/gdb/
Remote-Configuration.html.
• mon reset halt reset the chip and keep the CPUs halted
• flushregs monitor (mon) command can not inform GDB that the target state has changed. GDB will
assume that whatever stack the target had before mon reset halt will still be valid. In fact, after reset the
target state will change, and executing flushregs is a way to force GDB to get new state from the target.
• thb app_main insert a temporary hardware breakpoint at app_main, put here another function name
if required
• c resume the program. It will then stop at breakpoint inserted at app_main.

Configuration of OpenOCD for specific target There are several kinds of OpenOCD configuration files (*.
cfg). All configuration files are located in subdirectories of share/openocd/scripts directory of OpenOCD
distribution (or tcl/scripts directory of the source repository). For the purposes of this guide, the most impor-
tant ones are board, interface and target.
• interface configuration files describe the JTAG adapter. Examples of JTAG adapters are ESP-Prog and
J-Link.
• target configuration files describe specific chips, or in some cases, modules.
• board configuration files are provided for development boards with a built-in JTAG adapter. Such files in-
clude an interface configuration file to choose the adapter, and target configuration file to choose the
chip/module.
The following configuration files are available for ESP32:
Table 24: OpenOCD configuration files for ESP32

Name Description
board/esp32- Board configuration file for ESP-WROVER-KIT with a 3.3 V ESP32-WROOM-32
wrover-kit-3.3v. module or ESP32-WROVER-B / ESP32-WROVER-E module.
cfg
board/esp32- Board configuration file for ESP-WROVER-KIT with an 1.8 V ESP32-WROVER
wrover-kit-1.8v. module.
cfg
board/esp32- Board configuration file for ESP-Ethernet-KIT with a 3.3 V ESP32-WROVER-B /
ethernet-kit-3. ESP32-WROVER-E module.
3v.cfg
target/esp32.cfg ESP32 target configuration file. Can be used together with one of the interface/
configuration files.
target/esp32- Target configuration file for ESP32-SOLO-1 module. Different from esp32.cfg
solo-1.cfg in that it only configures one CPU.
interface/ftdi/ JTAG adapter configuration file for ESP-WROVER-KIT and ESP-Prog boards.
esp32_devkitj_v1.
cfg
If you are using one of the boards which have a pre-defined configuration file, you only need to pass one -f argument
to OpenOCD, specifying that file.
If you are using a board not listed here, you need to specify both the interface configuration file and target configuration
file.
Custom configuration files OpenOCD configuration files are written in TCL, and include a variety of choices for
customization and scripting. This can be useful for non-standard debugging situations. Please refer to OpenOCD
Manual for the TCL scripting reference.
OpenOCD configuration variables The following variables can be optionally set before including the ESP-specific
target configuration file. This can be done either in a custom configuration file, or from the command line.
The syntax for setting a variable in TCL is:
set VARIABLE_NAME value
To set a variable from the command line (replace the name of .cfg file with the correct file for your board):
openocd -c 'set VARIABLE_NAME value' -f board/esp-xxxxx-kit.cfg
It is important to set the variable before including the ESP-specific configuration file, otherwise the variable will not
have effect. You can set multiple variables by repeating the -c option.

Table 25: Common ESP-related OpenOCD variables

Variable Description
ESP_RTOS Set to none to disable RTOS support. In this case, thread list will not be available
in GDB. Can be useful when debugging FreeRTOS itself, and stepping through the
scheduler code.
ESP_FLASH_SIZE Set to 0 to disable Flash breakpoints support.
ESP_SEMIHOST_BASEDIR
Set to the path (on the host) which will be the default directory for semihosting func-
tions.
Table 26: ESP32-specific OpenOCD variables

Name Description
ESP32_FLASH_VOLTAGEWhen using 1.8 V flash ESP32 based modules, set this variable to 1.8. Refer to
Why to set SPI flash voltage in OpenOCD configuration?.
ESP32_ONLYCPU For multi-core targets, can be set to 1 to only enable single core debugging.
How debugger resets ESP32? The board can be reset by entering mon reset or mon reset halt into
GDB.
Do not use JTAG pins for something else Operation of JTAG may be disturbed, if some other h/w is connected
to JTAG pins besides ESP32 module and JTAG adapter. ESP32 JTAG is using the following pins:

MTDO / GPIO15 TDO
MTDI / GPIO12 TDI
MTCK / GPIO13 TCK
MTMS / GPIO14 TMS
GND GND
JTAG communication will likely fail, if configuration of JTAG pins is changed by user application. If OpenOCD
initializes correctly (detects the two Tensilica cores), but loses sync and spews out a lot of DTR/DIR errors when the
program is ran, it is likely that the application reconfigures the JTAG pins to something else, or the user forgot to
connect Vtar to a JTAG adapter that needed it.
Below is an excerpt from series of errors reported by GDB after the application stepped into the code that reconfigured
MTDO pin to be an input:
cpu0: xtensa_resume (line 431): DSR (FFFFFFFF) indicates target still busy!
cpu0: xtensa_resume (line 431): DSR (FFFFFFFF) indicates DIR instruction generated␣
,→an exception!
,→an overrun!
cpu1: xtensa_resume (line 431): DSR (FFFFFFFF) indicates target still busy!
,→an exception!
,→an overrun!
JTAG with Flash Encryption or Secure Boot By default, enabling Flash Encryption and/or Secure Boot will
disable JTAG debugging. On first boot, the bootloader will burn an eFuse bit to permanently disable JTAG at the
same time it enables the other features.
The project configuration option CONFIG_SECURE_BOOT_ALLOW_JTAG will keep JTAG enabled at this time,
removing all physical security but allowing debugging. (Although the name suggests Secure Boot, this option can be
applied even when only Flash Encryption is enabled).

However, OpenOCD may attempt to automatically read and write the flash in order to set software breakpoints. This
has two problems:
• Software breakpoints are incompatible with Flash Encryption, OpenOCD currently has no support for encrypt-
ing or decrypting flash contents.
• If Secure Boot is enabled, setting a software breakpoint will change the digest of a signed app and make the
signature invalid. This means if a software breakpoint is set and then a reset occurs, the signature verification
will fail on boot.
To disable software breakpoints while using JTAG, add an extra argument -c 'set ESP_FLASH_SIZE 0' to
the start of the OpenOCD command line, see OpenOCD configuration variables.
Note: For the same reason, the ESP-IDF app may fail bootloader verification of app signatures, when this option is
enabled and a software breakpoint is set.
JTAG and ESP32-WROOM-32 AT firmware Compatibility Issue The ESP32-WROOM series of modules
come pre-flashed with AT firmware. This firmware configures the pins GPIO12 to GPIO15 as SPI slave interface,
which makes using JTAG impossible.
To make JTAG available, build new firmware that is not using pins GPIO12 to GPIO15 dedicated to JTAG commu-
nication. After that, flash the firmware onto your module. See also Do not use JTAG pins for something else.
Reporting issues with OpenOCD / GDB In case you encounter a problem with OpenOCD or GDB programs
itself and do not find a solution searching available resources on the web, open an issue in the OpenOCD issue tracker
under https://github.com/espressif/openocd-esp32/issues.
1. In issue report provide details of your configuration:
a. JTAG adapter type, and the chip/module being debugged.
b. Release of ESP-IDF used to compile and load application that is being debugged.
c. Details of OS used for debugging.
d. Is OS running natively on a PC or on a virtual machine?
2. Create a simple example that is representative to observed issue. Describe steps how to reproduce it. In such
an example debugging should not be affected by non-deterministic behaviour introduced by the Wi-Fi stack,
so problems will likely be easier to reproduce, if encountered once.
3. Prepare logs from debugging session by adding additional parameters to start up commands.
OpenOCD:
openocd -l openocd_log.txt -d3 -f board/esp32-wrover-kit-3.3v.cfg
Logging to a file this way will prevent information displayed on the terminal. This may be a good thing taken
amount of information provided, when increased debug level -d3 is set. If you still like to see the log on the
screen, then use another command instead:
openocd -d3 -f board/esp32-wrover-kit-3.3v.cfg 2>&1 | tee openocd.log
Debugger:
xtensa-esp32-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
Optionally add command remotelogfile gdb_log.txt to the gdbinit file.

4. Attach both openocd_log.txt and gdb_log.txt files to your issue report.
Using Debugger
This section covers configuration and running debugger using several methods:
• from Eclipse

• from Command Line

• using idf.py debug targets
Eclipse
Note: It is recommended to first check if debugger works using idf.py debug targets or from Command Line and
then move to using Eclipse.
Debugging functionality is provided out of box in standard Eclipse installation. Another option is to use pluggins like
GDB Hardware Debugging plugin. We have found this plugin quite convenient and decided to use throughout this
guide.
To begin with, install GDB Hardware Debugging plugin by opening Eclipse and going to Help > Install New
Software.
Once installation is complete, configure debugging session following steps below. Please note that some of configu-
ration parameters are generic and some are project specific. This will be shown below by configuring debugging for
blink example project. If not done already, add this project to Eclipse workspace following guidance in section
Build and Flash with Eclipse IDE. The source of get-started/blink application is available in examples directory of
ESP-IDF repository.
1. In Eclipse go to Run > Debug Configuration. A new window will open. In the window s left pane double
click GDB Hardware Debugging (or select GDB Hardware Debugging and press the New button)
to create a new configuration.
2. In a form that will show up on the right, enter the Name: of this configuration, e.g. Blink checking .
3. On the Main tab below, under Project: , press Browse button and select the blink project.
4. In next line C/C++ Application: press Browse button and select blink.elf file. If blink.elf is
not there, then likely this project has not been build yet. See Build and Flash with Eclipse IDE how to do it.
5. Finally, under Build (if required) before launching click Disable auto build .
A sample window with settings entered in points 1 - 5 is shown below.
6. Click Debugger tab. In field GDB Command enter xtensa-esp32-elf-gdb to invoke debugger.
7. Change default configuration of Remote host by entering 3333 under the Port number .
Configuration entered in points 6 and 7 is shown on the following picture.
8. The last tab to that requires changing of default configuration is Startup . Under Initialization Commands
uncheck Reset and Delay (seconds) and Halt . Then, in entry field below, enter the following lines:
mon reset halt

flushregs
set remote hardware-watchpoint-limit 2
Note: If you want to update image in the flash automatically before starting new debug session add the
following lines of commands at the beginning of Initialization Commands textbox:
mon reset halt

mon program_esp ${workspace_loc:blink/build/blink.bin} 0x10000 verify
For description of program_esp command see Upload application for debugging.

9. Under Load Image and Symbols uncheck Load image option.
10. Further down on the same tab, establish an initial breakpoint to halt CPUs after they are reset by debugger. The
plugin will set this breakpoint at the beginning of the function entered under Set break point at: . Checkout
this option and enter app_main in provided field.
11. Checkout Resume option. This will make the program to resume after mon reset halt is invoked
per point 8. The program will then stop at breakpoint inserted at app_main.
Configuration described in points 8 - 11 is shown below.
If the Startup sequence looks convoluted and respective Initialization Commands are not clear to you,
check What is the meaning of debugger s startup commands? for additional explanation.
12. If you previously completed Configuring ESP32 Target steps described above, so the target is running and ready
to talk to debugger, go right to debugging by pressing Debug button. Otherwise press Apply to save
changes, go back to Configuring ESP32 Target and return here to start debugging.

Fig. 35: Configuration of GDB Hardware Debugging - Main tab

Fig. 36: Configuration of GDB Hardware Debugging - Debugger tab

Fig. 37: Configuration of GDB Hardware Debugging - Startup tab

Once all 1 - 12 configuration steps are satisfied, the new Eclipse perspective called Debug will open as shown on
example picture below.
Fig. 38: Debug Perspective in Eclipse
If you are not quite sure how to use GDB, check Eclipse example debugging session in section Debugging Examples.
Command Line
1. Begin with completing steps described under Configuring ESP32 Target. This is prerequisite to start a debugging
session.
2. Open a new terminal session and go to directory that contains project for debugging, e.g.
cd ~/esp/blink
3. When launching a debugger, you will need to provide couple of configuration parameters and commands.
Instead of entering them one by one in command line, create a configuration file and name it gdbinit:
target remote :3333

set remote hardware-watchpoint-limit 2
mon reset halt
flushregs
thb app_main
c
Save this file in current directory.

For more details what s inside gdbinit file, see What is the meaning of debugger s startup commands?
4. Now you are ready to launch GDB. Type the following in terminal:

xtensa-esp32-elf-gdb -x gdbinit build/blink.elf
5. If previous steps have been done correctly, you will see a similar log concluded with (gdb) prompt:
user-name@computer-name:~/esp/blink$ xtensa-esp32-elf-gdb -x gdbinit build/

,→blink.elf
GNU gdb (crosstool-NG crosstool-ng-1.22.0-61-gab8375a) 7.10

Copyright (C) 2015 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law. Type "show copying"
and "show warranty" for details.
This GDB was configured as "--host=x86_64-build_pc-linux-gnu --target=xtensa-
,→esp32-elf".
Type "show configuration" for configuration details.

For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
<http://www.gnu.org/software/gdb/documentation/>.
For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from build/blink.elf...done.
0x400d10d8 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/
,→components/esp32/./freertos_hooks.c:52
52 asm("waiti 0");
JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica),␣
,→part: 0x2003, ver: 0x1)
JTAG tap: esp32.slave tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica),␣

,→part: 0x2003, ver: 0x1)
esp32: Debug controller was reset (pwrstat=0x5F, after clear 0x0F).

esp32: Core was reset (pwrstat=0x5F, after clear 0x0F).
Target halted. PRO_CPU: PC=0x5000004B (active) APP_CPU: PC=0x00000000
esp32: target state: halted
esp32: Core was reset (pwrstat=0x1F, after clear 0x0F).
Target halted. PRO_CPU: PC=0x40000400 (active) APP_CPU: PC=0x40000400
esp32: target state: halted
Hardware assisted breakpoint 1 at 0x400db717: file /home/user-name/esp/blink/
,→main/./blink.c, line 43.
0x0: 0x00000000
Target halted. PRO_CPU: PC=0x400DB717 (active) APP_CPU: PC=0x400D10D8
[New Thread 1073428656]
[New Thread 1073413708]
[New Thread 1073431316]
[New Thread 1073410672]
[New Thread 1073408876]
[New Thread 1073432196]
[New Thread 1073411552]
[Switching to Thread 1073411996]
Temporary breakpoint 1, app_main () at /home/user-name/esp/blink/main/./blink.

,→c:43
43 xTaskCreate(&blink_task, "blink_task", 512, NULL, 5, NULL);

(gdb)
Note the third line from bottom that shows debugger halting at breakpoint established in gdbinit file at function
app_main(). Since the processor is halted, the LED should not be blinking. If this is what you see as well, you
are ready to start debugging.
If you are not quite sure how to use GDB, check Command Line example debugging session in section Debugging
Examples.

idf.py debug targets It is also possible to execute the described debugging tools conveniently from idf.py. These
commands are supported:
1. idf.py openocd
Runs OpenOCD in a console with configuration defined in the environment or via command line. It uses default
script directory defined as OPENOCD_SCRIPTS environmental variable, which is automatically added from
an Export script (export.sh or export.bat). It is possible to override the script location using command
line argument --openocd-scripts.
As for the JTAG configuration of the current board, please use the environmental variable
OPENOCD_COMMANDS or --openocd-commands command line argument. If none of the above
is defined, OpenOCD is started with -f board/esp32-wrover-kit-3.3v.cfg board definition.
2. idf.py gdb
Starts the gdb the same way as the Command Line, but generates the initial gdb scripts referring to the current
project elf file.
3. idf.py gdbtui
The same as 2, but starts the gdb with tui argument allowing very simple source code view.
4. idf.py gdbgui
Starts gdbgui debugger frontend enabling out-of-the-box debugging in a browser window.
It is possible to combine these debugging actions on a single command line allowing convenient setup of block-
ing and non-blocking actions in one step. idf.py implements a simple logic to move the background actions
(such as openocd) to the beginning and the interactive ones (such as gdb, monitor) to the end of the action list.
An example of a very useful combination is:
idf.py openocd gdbgui monitor
The above command runs OpenOCD in the background, starts gdbgui to open a browser window with active
debugger frontend and opens a serial monitor in the active console.
Debugging Examples
This section describes debugging with GDB from Eclipse as well as from Command Line.
Eclipse Verify if your target is ready and loaded with get-started/blink example. Configure and start debugger
following steps in section Eclipse. Pick up where target was left by debugger, i.e. having the application halted at
breakpoint established at app_main().
Examples in this section

3. Halting the target manually
Navigating through the code, call stack and threads When the target is halted, debugger shows the list of threads
in Debug window. The line of code where program halted is highlighted in another window below, as shown on
the following picture. The LED stops blinking.
Specific thread where the program halted is expanded showing the call stack. It represents function calls that lead up
to the highlighted line of code, where the target halted. The first line of call stack under Thread #1 contains the last
called function app_main(), that in turn was called from function main_task() shown in a line below. Each
line of the stack also contains the file name and line number where the function was called. By clicking / highlighting
the stack entries, in window below, you will see contents of this file.

Fig. 39: Debug Perspective in Eclipse

Fig. 40: Target halted during debugging

By expanding threads you can navigate throughout the application. Expand Thread #5 that contains much longer call
stack. You will see there, besides function calls, numbers like 0x4000000c. They represent addresses of binary
code not provided in source form.
Fig. 41: Navigate through the call stack
In another window on right, you can see the disassembled machine code no matter if your project provides it in source
or only the binary form.
Go back to the app_main() in Thread #1 to familiar code of blink.c file that will be examined in more details
in the following examples. Debugger makes it easy to navigate through the code of entire application. This comes
handy when stepping through the code and working with breakpoints and will be discussed below.
Setting and clearing breakpoints When debugging, we would like to be able to stop the application at critical
lines of code and then examine the state of specific variables, memory and registers / peripherals. To do so we are
using breakpoints. They provide a convenient way to quickly get to and halt the application at specific line.
Let s establish two breakpoints when the state of LED changes. Basing on code listing above, this happens at lines
33 and 36. To do so, hold the Control on the keyboard and double clink on number 33 in file blink.c file. A
dialog will open where you can confirm your selection by pressing OK button. If you do not like to see the dialog
just double click the line number. Set another breakpoint in line 36.
Information how many breakpoints are set and where is shown in window Breakpoints on top right. Click Show
Breakpoints Supported by Selected Target to refresh this list. Besides the two just set breakpoints the list may contain
temporary breakpoint at function app_main() established at debugger start. As maximum two breakpoints are
allowed (see Breakpoints and watchpoints available), you need to delete it, or debugging will fail.
If you now click Resume (click blink_task() under Tread #8 , if Resume button is grayed out), the
processor will run and halt at a breakpoint. Clicking Resume another time will make it run again, halt on second
breakpoint, and so on.

Fig. 42: Setting a breakpoint

Fig. 43: Three breakpoints are set / maximum two are allowed

You will be also able to see that LED is changing the state after each click to Resume program execution.
Read more about breakpoints under Breakpoints and watchpoints available and What else should I know about break-
points?
Halting the target manually When debugging, you may resume application and enter code waiting for some event
or staying in infinite loop without any break points defined. In such case, to go back to debugging mode, you can
break program execution manually by pressing Suspend button.
To check it, delete all breakpoints and click Resume . Then click Suspend . Application will be halted at
some random point and LED will stop blinking. Debugger will expand tread and highlight the line of code where
application halted.
Fig. 44: Target halted manually
In particular case above, the application has been halted in line 52 of code in file freertos_hooks.c Now you
can resume it again by pressing Resume button or do some debugging as discussed below.
Stepping through the code It is also possible to step through the code using Step Into (F5) and Step Over
(F6) commands. The difference is that Step Into (F5) is entering inside subroutines calls, while Step Over
(F6) steps over the call, treating it as a single source line.
Before being able to demonstrate this functionality, using information discussed in previous paragraph, make sure
that you have only one breakpoint defined at line 36 of blink.c.
Resume program by entering pressing F8 and let it halt. Now press Step Over (F6) , one by one couple of times,
to see how debugger is stepping one program line at a time.
If you press Step Into (F5) instead, then debugger will step inside subroutine calls.
In this particular case debugger stepped inside gpio_set_level(BLINK_GPIO, 0) and effectively moved to
gpio.c driver code.

Fig. 45: Stepping through the code with Step Over (F6)

Fig. 46: Stepping through the code with Step Into (F5)

See Why stepping with next does not bypass subroutine calls? for potential limitation of using next command.
Checking and setting memory To display or set contents of memory use Memory tab at the bottom of Debug
perspective.
With the Memory tab, we will read from and write to the memory location 0x3FF44004 labeled as
GPIO_OUT_REG used to set and clear individual GPIO s.
For more information, see ESP32 Technical Reference Manual > IO MUX and GPIO Matrix (GPIO, IO_MUX) [PDF].
Being in the same blink.c project as before, set two breakpoints right after gpio_set_level instruction. Click
Memory tab and then Add Memory Monitor button. Enter 0x3FF44004 in provided dialog.
Now resume program by pressing F8 and observe Monitor tab.
Fig. 47: Observing memory location 0x3FF44004 changing one bit to ON
You should see one bit being flipped over at memory location 0x3FF44004 (and LED changing the state) each time
F8 is pressed.
Fig. 48: Observing memory location 0x3FF44004 changing one bit to OFF
To set memory use the same Monitor tab and the same memory location. Type in alternate bit pattern as previously
observed. Immediately after pressing enter you will see LED changing the state.
Watching and setting program variables A common debugging tasks is checking the value of a program variable
as the program runs. To be able to demonstrate this functionality, update file blink.c by adding a declaration of

a global variable int i above definition of function blink_task. Then add i++ inside while(1) of this
function to get i incremented on each blink.
Exit debugger, so it is not confused with new code, build and flash the code to the ESP and restart debugger. There
is no need to restart OpenOCD.
Once application is halted, enter a breakpoint in the line where you put i++.
In next step, in the window with Breakpoints , click the Expressions tab. If this tab is not visible, then add it
by going to the top menu Window > Show View > Expressions. Then click Add new expression and enter i.
Resume program execution by pressing F8. Each time the program is halted you will see i value being incremented.
Fig. 49: Watching program variable i
To modify i enter a new number in Value column. After pressing Resume (F8) the program will keep
incrementing i starting from the new entered number.
Setting conditional breakpoints Here comes more interesting part. You may set a breakpoint to halt the program
execution, if certain condition is satisfied. Right click on the breakpoint to open a context menu and select Breakpoint
Properties . Change the selection under Type: to Hardware and enter a Condition: like i == 2.
If current value of i is less than 2 (change it if required) and program is resumed, it will blink LED in a loop until
condition i == 2 gets true and then finally halt.
Command Line Verify if your target is ready and loaded with get-started/blink example. Configure and start
debugger following steps in section Command Line. Pick up where target was left by debugger, i.e. having the
application halted at breakpoint established at app_main():

Fig. 50: Setting a conditional breakpoint

Temporary breakpoint 1, app_main () at /home/user-name/esp/blink/main/./blink.c:43

43 xTaskCreate(&blink_task, "blink_task", configMINIMAL_STACK_SIZE, NULL, 5,␣
,→NULL);
(gdb)
Examples in this section

3. Halting and resuming the application
Navigating through the code, call stack and threads When you see the (gdb) prompt, the application is halted.
LED should not be blinking.
To find out where exactly the code is halted, enter l or list, and debugger will show couple of lines of code around
the halt point (line 43 of code in file blink.c)
(gdb) l
38 }
39 }
40
41 void app_main()
42 {
43 xTaskCreate(&blink_task, "blink_task", configMINIMAL_STACK_SIZE, NULL, 5,␣
,→NULL);
44 }
(gdb)
Check how code listing works by entering, e.g. l 30, 40 to see particular range of lines of code.
You can use bt or backtrace to see what function calls lead up to this code:
(gdb) bt
#0 app_main () at /home/user-name/esp/blink/main/./blink.c:43
#1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/
,→esp32/./cpu_start.c:339
(gdb)
Line #0 of output provides the last function call before the application halted, i.e. app_main () we have listed
previously. The app_main () was in turn called by function main_task from line 339 of code located in file
cpu_start.c.
To get to the context of main_task in file cpu_start.c, enter frame N, where N = 1, because the
main_task is listed under #1):
(gdb) frame 1
#1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/
,→esp32/./cpu_start.c:339
339 app_main();
(gdb)
Enter l and this will reveal the piece of code that called app_main() (in line 339):
(gdb) l
334 ;
335 }


336 #endif
337 //Enable allocation in region where the startup stacks were located.
338 heap_caps_enable_nonos_stack_heaps();
339 app_main();
340 vTaskDelete(NULL);
341 }
342
(gdb)
By listing some lines before, you will see the function name main_task we have been looking for:
(gdb) l 326, 341

326 static void main_task(void* args)
327 {
328 // Now that the application is about to start, disable boot watchdogs
329 REG_CLR_BIT(TIMG_WDTCONFIG0_REG(0), TIMG_WDT_FLASHBOOT_MOD_EN_S);
330 REG_CLR_BIT(RTC_CNTL_WDTCONFIG0_REG, RTC_CNTL_WDT_FLASHBOOT_MOD_EN);
331 #if !CONFIG_FREERTOS_UNICORE
332 // Wait for FreeRTOS initialization to finish on APP CPU, before replacing␣
,→its startup stack
333 while (port_xSchedulerRunning[1] == 0) {

334 ;
335 }
336 #endif
337 //Enable allocation in region where the startup stacks were located.
338 heap_caps_enable_nonos_stack_heaps();
339 app_main();
340 vTaskDelete(NULL);
341 }
(gdb)
To see the other code, enter i threads. This will show the list of threads running on target:
(gdb) i threads
Id Target Id Frame
8 Thread 1073411336 (dport) 0x400d0848 in dport_access_init_core (arg=
,→<optimized out>)
at /home/user-name/esp/esp-idf/components/esp32/./dport_access.c:170
7 Thread 1073408744 (ipc0) xQueueGenericReceive (xQueue=0x3ffae694,␣
,→pvBuffer=0x0, xTicksToWait=1644638200,
xJustPeeking=0) at /home/user-name/esp/esp-idf/components/freertos/./queue.
,→c:1452
6 Thread 1073431096 (Tmr Svc) prvTimerTask (pvParameters=0x0)

at /home/user-name/esp/esp-idf/components/freertos/./timers.c:445
5 Thread 1073410208 (ipc1 : Running) 0x4000bfea in ?? ()
4 Thread 1073432224 (dport) dport_access_init_core (arg=0x0)
at /home/user-name/esp/esp-idf/components/esp32/./dport_access.c:150
3 Thread 1073413156 (IDLE) prvIdleTask (pvParameters=0x0)
at /home/user-name/esp/esp-idf/components/freertos/./tasks.c:3282
2 Thread 1073413512 (IDLE) prvIdleTask (pvParameters=0x0)
at /home/user-name/esp/esp-idf/components/freertos/./tasks.c:3282
* 1 Thread 1073411772 (main : Running) app_main () at /home/user-name/esp/blink/
,→main/./blink.c:43
(gdb)
The thread list shows the last function calls per each thread together with the name of C source file if available.
You can navigate to specific thread by entering thread N, where N is the thread Id. To see how it works go to
thread thread 5:
(gdb) thread 5


[Switching to thread 5 (Thread 1073410208)]
#0 0x4000bfea in ?? ()
(gdb)
Then check the backtrace:
(gdb) bt
#0 0x4000bfea in ?? ()
#1 0x40083a85 in vPortCPUReleaseMutex (mux=<optimized out>) at /home/user-name/
,→esp/esp-idf/components/freertos/./port.c:415
#2 0x40083fc8 in vTaskSwitchContext () at /home/user-name/esp/esp-idf/components/

,→freertos/./tasks.c:2846
#3 0x4008532b in _frxt_dispatch ()
#4 0x4008395c in xPortStartScheduler () at /home/user-name/esp/esp-idf/components/
,→freertos/./port.c:222
#5 0x4000000c in ?? ()
#6 0x4000000c in ?? ()
#7 0x4000000c in ?? ()
#8 0x4000000c in ?? ()
(gdb)
As you see, the backtrace may contain several entries. This will let you check what exact sequence of function calls
lead to the code where the target halted. Question marks ?? instead of a function name indicate that application is
available only in binary format, without any source file in C language. The value like 0x4000bfea is the memory
address of the function call.
Using bt, i threads, thread N and list commands we are now able to navigate through the code of entire
application. This comes handy when stepping through the code and working with breakpoints and will be discussed
below.
Setting and clearing breakpoints When debugging, we would like to be able to stop the application at critical
lines of code and then examine the state of specific variables, memory and registers / peripherals. To do so we are
using breakpoints. They provide a convenient way to quickly get to and halt the application at specific line.
Let s establish two breakpoints when the state of LED changes. Basing on code listing above this happens at lines
33 and 36. Breakpoints may be established using command break M where M is the code line number:
(gdb) break 33
Breakpoint 2 at 0x400db6f6: file /home/user-name/esp/blink/main/./blink.c, line 33.
(gdb) break 36
Breakpoint 3 at 0x400db704: file /home/user-name/esp/blink/main/./blink.c, line 36.
If you new enter c, the processor will run and halt at a breakpoint. Entering c another time will make it run again,
halt on second breakpoint, and so on:
(gdb) c
Continuing.
Target halted. PRO_CPU: PC=0x400DB6F6 (active) APP_CPU: PC=0x400D10D8
Breakpoint 2, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./

,→blink.c:33
33 gpio_set_level(BLINK_GPIO, 0);
(gdb) c
Continuing.
Target halted. PRO_CPU: PC=0x400DB6F8 (active) APP_CPU: PC=0x400D10D8
Target halted. PRO_CPU: PC=0x400DB704 (active) APP_CPU: PC=0x400D10D8

,→blink.c:36


(gdb)
You will be also able to see that LED is changing the state only if you resume program execution by entering c.
To examine how many breakpoints are set and where, use command info break:
(gdb) info break

Num Type Disp Enb Address What
2 breakpoint keep y 0x400db6f6 in blink_task at /home/user-name/esp/
,→blink/main/./blink.c:33
breakpoint already hit 1 time

3 breakpoint keep y 0x400db704 in blink_task at /home/user-name/esp/

(gdb)
Please note that breakpoint numbers (listed under Num) start with 2. This is because first breakpoint has been
already established at function app_main() by running command thb app_main on debugger launch. As it
was a temporary breakpoint, it has been automatically deleted and now is not listed anymore.
To remove breakpoints enter delete N command (in short d N), where N is the breakpoint number:
(gdb) delete 1
No breakpoint number 1.
(gdb) delete 2
(gdb)
Read more about breakpoints under Breakpoints and watchpoints available and What else should I know about break-
points?
Halting and resuming the application When debugging, you may resume application and enter code waiting for
some event or staying in infinite loop without any break points defined. In such case, to go back to debugging mode,
you can break program execution manually by entering Ctrl+C.
To check it delete all breakpoints and enter c to resume application. Then enter Ctrl+C. Application will be halted
at some random point and LED will stop blinking. Debugger will print the following:
(gdb) c
Continuing.
^CTarget halted. PRO_CPU: PC=0x400D0C00 APP_CPU: PC=0x400D0C00 (active)
[New Thread 1073433352]
Program received signal SIGINT, Interrupt.

0x400d0c00 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/
,→components/esp32/./freertos_hooks.c:52
52 asm("waiti 0");
(gdb)
In particular case above, the application has been halted in line 52 of code in file freertos_hooks.c. Now you
can resume it again by enter c or do some debugging as discussed below.
Note: In MSYS2 shell Ctrl+C does not halt the target but exists debugger. To resolve this issue consider debugging
with Eclipse or check a workaround under http://www.mingw.org/wiki/Workaround_for_GDB_Ctrl_C_Interrupt.
Stepping through the code It is also possible to step through the code using step and next commands (in short
s and n). The difference is that step is entering inside subroutines calls, while next steps over the call, treating it
as a single source line.

To demonstrate this functionality, using command break and delete discussed in previous paragraph, make sure
that you have only one breakpoint defined at line 36 of blink.c:
(gdb) info break

Num Type Disp Enb Address What
3 breakpoint keep y 0x400db704 in blink_task at /home/user-name/esp/

(gdb)
Resume program by entering c and let it halt:
(gdb) c
Continuing.
Target halted. PRO_CPU: PC=0x400DB754 (active) APP_CPU: PC=0x400D1128

,→blink.c:36
(gdb)
Then enter n couple of times to see how debugger is stepping one program line at a time:
(gdb) n
Target halted. PRO_CPU: PC=0x400DC04C (active) APP_CPU: PC=0x400D1128
Target halted. PRO_CPU: PC=0x400DB75B (active) APP_CPU: PC=0x400D1128
37 vTaskDelay(1000 / portTICK_PERIOD_MS);
(gdb) n
Target halted. PRO_CPU: PC=0x400DB75E (active) APP_CPU: PC=0x400D1128
Target halted. PRO_CPU: PC=0x400846FC (active) APP_CPU: PC=0x400D1128
(gdb)
If you enter s instead, then debugger will step inside subroutine calls:
(gdb) s
Target halted. PRO_CPU: PC=0x400DC04C (active) APP_CPU: PC=0x400D1128
Target halted. PRO_CPU: PC=0x400DC04F (active) APP_CPU: PC=0x400D1128
gpio_set_level (gpio_num=GPIO_NUM_4, level=0) at /home/user-name/esp/esp-idf/
,→components/driver/./gpio.c:183
183 GPIO_CHECK(GPIO_IS_VALID_OUTPUT_GPIO(gpio_num), "GPIO output gpio_num error

,→", ESP_ERR_INVALID_ARG);
(gdb)
In this particular case debugger stepped inside gpio_set_level(BLINK_GPIO, 0) and effectively moved to
gpio.c driver code.
See Why stepping with next does not bypass subroutine calls? for potential limitation of using next command.
Checking and setting memory Displaying the contents of memory is done with command x. With additional
parameters you may vary the format and count of memory locations displayed. Run help x to see more details.
Companion command to x is set that let you write values to the memory.
We will demonstrate how x and set work by reading from and writing to the memory location 0x3FF44004
labeled as GPIO_OUT_REG used to set and clear individual GPIO s.
For more information, see ESP32 Technical Reference Manual > IO MUX and GPIO Matrix (GPIO, IO_MUX) [PDF].

Being in the same blink.c project as before, set two breakpoints right after gpio_set_level instruction. Enter
two times c to get to the break point followed by x /1wx 0x3FF44004 to display contents of GPIO_OUT_REG
memory location:
(gdb) c
Continuing.

,→blink.c:34
(gdb) x /1wx 0x3FF44004
0x3ff44004: 0x00000000
(gdb) c
Continuing.

,→blink.c:37
(gdb) x /1wx 0x3FF44004
0x3ff44004: 0x00000010
(gdb)
If your are blinking LED connected to GPIO4, then you should see fourth bit being flipped each time the LED
changes the state:
0x3ff44004: 0x00000000
...
0x3ff44004: 0x00000010
Now, when the LED is off, that corresponds to 0x3ff44004: 0x00000000 being displayed, try using set
command to set this bit by writting 0x00000010 to the same memory location:
(gdb) x /1wx 0x3FF44004

0x3ff44004: 0x00000000
(gdb) set {unsigned int}0x3FF44004=0x000010
You should see the LED to turn on immediately after entering set {unsigned
int}0x3FF44004=0x000010 command.
Watching and setting program variables A common debugging tasks is checking the value of a program variable
as the program runs. To be able to demonstrate this functionality, update file blink.c by adding a declaration of
a global variable int i above definition of function blink_task. Then add i++ inside while(1) of this
function to get i incremented on each blink.
Exit debugger, so it is not confused with new code, build and flash the code to the ESP and restart debugger. There
is no need to restart OpenOCD.
Once application is halted, enter the command watch i:
(gdb) watch i
Hardware watchpoint 2: i
(gdb)
This will insert so called watchpoint in each place of code where variable i is being modified. Now enter
continue to resume the application and observe it being halted:

(gdb) c
Continuing.
[New Thread 1073432196]
Program received signal SIGTRAP, Trace/breakpoint trap.

0x400db751 in blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./
,→blink.c:33
33 i++;
(gdb)
Resume application couple more times so i gets incremented. Now you can enter print i (in short p i) to check
the current value of i:
(gdb) p i
$1 = 3
(gdb)
To modify the value of i use set command as below (you can then print it out to check if it has been indeed
changed):
(gdb) set var i = 0

(gdb) p i
$3 = 0
(gdb)
You may have up to two watchpoints, see Breakpoints and watchpoints available.
Setting conditional breakpoints Here comes more interesting part. You may set a breakpoint to halt the program
execution, if certain condition is satisfied. Delete existing breakpoints and try this:
(gdb) break blink.c:34 if (i == 2)

Breakpoint 3 at 0x400db753: file /home/user-name/esp/blink/main/./blink.c, line 34.
(gdb)
Above command sets conditional breakpoint to halt program execution in line 34 of blink.c if i == 2.
If current value of i is less than 2 and program is resumed, it will blink LED in a loop until condition i == 2 gets
true and then finally halt:
(gdb) set var i = 0

(gdb) c
Continuing.
Target halted. PRO_CPU: PC=0x400DB755 (active) APP_CPU: PC=0x400D112C

,→blink.c:34
(gdb)
Obtaining help on commands Commands presented so for should provide are very basis and intended to let you
quickly get started with JTAG debugging. Check help what are the other commands at you disposal. To obtain help
on syntax and functionality of particular command, being at (gdb) prompt type help and command name:

(gdb) help next

Step program, proceeding through subroutine calls.
Usage: next [N]
Unlike "step", if the current source line calls a subroutine,
this command does not enter the subroutine, but instead steps over
the call, in effect treating it as a single source line.
(gdb)
By typing just help, you will get top level list of command classes, to aid you drilling down to more details. Option-
ally refer to available GDB cheat sheets, for instance https://darkdust.net/files/GDB%20Cheat%20Sheet.pdf. Good
to have as a reference (even if not all commands are applicable in an embedded environment).
Ending debugger session To quit debugger enter q:

(gdb) q
A debugging session is active.
Inferior 1 [Remote target] will be detached.
Quit anyway? (y or n) y
Detaching from program: /home/user-name/esp/blink/build/blink.elf, Remote target
Ending remote debugging.
user-name@computer-name:~/esp/blink$
• Using Debugger
• Debugging Examples
• Tips and Quirks
• Application Level Tracing library
• Introduction to ESP-Prog Board
4.19 Linker Script Generation
4.19.1 Overview
There are several memory regions where code and data can be placed. Code and read-only data are placed by default
in flash, writable data in RAM, etc. However, it is sometimes necessary to change these default placements.
For example, it may be necessary to place critical code in RAM for performance reasons or to place code in RTC
memory for use in a wake stub or the ULP coprocessor.
With the linker script generation mechanism, it is possible to specify these placements at the component level within
ESP-IDF. The component presents information on how it would like to place its symbols, objects or the entire archive.
During build, the information presented by the components are collected, parsed and processed; and the placement
rules generated is used to link the app.
4.19.2 Quick Start
This section presents a guide for quickly placing code/data to RAM and RTC memory - placements ESP-IDF provides
out-of-the-box.
For this guide, suppose we have the following:
- components/
- my_component/
- CMakeLists.txt
- component.mk
- Kconfig


- src/
- my_src1.c
- my_src2.c
- my_src3.c
- my_linker_fragment_file.lf
• a component named my_component that is archived as library libmy_component.a during build

• three source files archived under the library, my_src1.c, my_src2.c and my_src3.c which are com-
piled as my_src1.o, my_src2.o and my_src3.o, respectively
• under my_src1.o, the function my_function1 is defined; under my_src2.o, the function
my_function2 is defined
• there is bool-type config PERFORMANCE_MODE (y/n) and int type config PERFORMANCE_LEVEL (with
range 0-3) in my_component s Kconfig
Creating and Specifying a Linker Fragment File
Before anything else, a linker fragment file needs to be created. A linker fragment file is simply a text file with a .lf
extension upon which the desired placements will be written. After creating the file, it is then necessary to present it
to the build system. The instructions for the build systems supported by ESP-IDF are as follows:
In the component s CMakeLists.txt file, specify argument LDFRAGMENTS in the
idf_component_register call. The value of LDFRAGMENTS can either be an absolute path or a
relative path from the component directory to the created linker fragment file.
# file paths relative to CMakeLists.txt

LDFRAGMENTS "path/to/linker_fragment_file.lf" "path/to/
,→another_linker_fragment_file.lf"
...
)
Specifying placements
It is possible to specify placements at the following levels of granularity:

• object file (.obj or .o files)
• symbol (function/variable)
• archive (.a files)
Placing object files Suppose the entirety of my_src1.o is performance-critical, so it is desirable to place it in
RAM. On the other hand, the entirety of my_src2.o contains symbols needed coming out of deep sleep, so it needs
to be put under RTC memory. In the the linker fragment file, we can write:
[mapping:my_component]
archive: libmy_component.a
entries:
my_src1 (noflash) # places all my_src1 code/read-only data under IRAM/DRAM
my_src2 (rtc) # places all my_src2 code/ data and read-only data under␣
,→RTC fast memory/RTC slow memory
What happens to my_src3.o? Since it is not specified, default placements are used for my_src3.o. More on
default placements here.
Placing symbols Continuing our example, suppose that among functions defined under object1.o, only
my_function1 is performance-critical; and under object2.o, only my_function2 needs to execute after
the chip comes out of deep sleep. This could be accomplished by writing:

entries:
my_src1:my_function1 (noflash)
my_src2:my_function2 (rtc)
The default placements are used for the rest of the functions in my_src1.o and my_src2.o and the entire ob-
ject3.o. Something similar can be achieved for placing data by writing the variable name instead of the function
name, like so:
my_src1:my_variable (noflash)
Warning: There are limitations in placing code/data at symbol granularity. In order to ensure proper placements,
an alternative would be to group relevant code and data into source files, and use object-granularity placements.
Placing entire archive In this example, suppose that the entire component archive needs to be placed in RAM.
This can be written as:
entries:
* (noflash)
Similarly, this places the entire component in RTC memory:
entries:
* (rtc)
Configuration-dependent placements Suppose that the entire component library should only have special place-
ment when a certain condition is true; for example, when CONFIG_PERFORMANCE_MODE == y. This could be
written as:
entries:
if PERFORMANCE_MODE = y:
* (noflash)
else:
* (default)
For a more complex config-dependent placement, suppose the following requirements: when
CONFIG_PERFORMANCE_LEVEL == 1, only object1.o is put in RAM; when CON-
FIG_PERFORMANCE_LEVEL == 2, object1.o and object2.o; and when CON-
FIG_PERFORMANCE_LEVEL == 3 all object files under the archive are to be put into RAM. When
these three are false however, put entire library in RTC memory. This scenario is a bit contrived, but, it can be
written as:
entries:
if PERFORMANCE_LEVEL = 1:
my_src1 (noflash)
elif PERFORMANCE_LEVEL = 2:
my_src1 (noflash)


my_src2 (noflash)
elif PERFORMANCE_LEVEL = 3:
my_src1 (noflash)
my_src2 (noflash)
my_src3 (noflash)
else:
* (rtc)
Nesting condition-checking is also possible. The following is equivalent to the snippet above:
entries:
if PERFORMANCE_LEVEL <= 3 && PERFORMANCE_LEVEL > 0:
if PERFORMANCE_LEVEL >= 1:
object1 (noflash)
object2 (noflash)
object2 (noflash)
else:
* (rtc)
The default placements
Up until this point, the term default placements has been mentioned as fallback placements when the placement
rules rtc and noflash are not specified. It is important to note that the tokens noflash or rtc are not merely
keywords, but are actually entities called fragments, specifically schemes.
In the same manner as rtc and noflash are schemes, there exists a default scheme which defines what the de-
fault placement rules should be. As the name suggests, it is where code and data are usually placed, i.e. code/constants
is placed in flash, variables placed in RAM, etc. More on the default scheme here.
Note: For an example of an ESP-IDF component using the linker script generation mechanism, see freer-
tos/CMakeLists.txt. freertos uses this to place its object files to the instruction RAM for performance reasons.
This marks the end of the quick start guide. The following text discusses the internals of the mechanism in a little bit
more detail. The following sections should be helpful in creating custom placements or modifying default behavior.
4.19.3 Linker Script Generation Internals
Linking is the last step in the process of turning C/C++ source files into an executable. It is performed by the
toolchain s linker, and accepts linker scripts which specify code/data placements, among other things. With the
linker script generation mechanism, this process is no different, except that the linker script passed to the linker is
dynamically generated from: (1) the collected linker fragment files and (2) linker script template.
Note: The tool that implements the linker script generation mechanism lives under tools/ldgen.
Linker Fragment Files
As mentioned in the quick start guide, fragment files are simple text files with the .lf extension containing the
desired placements. This is a simplified description of what fragment files contain, however. What fragment files
actually contain are fragments . Fragments are entities which contain pieces of information which, when put

together, form placement rules that tell where to place sections of object files in the output binary. There are three
types of fragments: sections, scheme and mapping.
Grammar The three fragment types share a common grammar:
[type:name]
key: value
key:
value
value
value
...
• type: Corresponds to the fragment type, can either be sections, scheme or mapping.
• name: The name of the fragment, should be unique for the specified fragment type.
• key, value: Contents of the fragment; each fragment type may support different keys and different grammars
for the key values.
Note: In cases where multiple fragments of the same type and name are encountered, an exception is thrown.
Note: The only valid characters for fragment names and keys are alphanumeric characters and underscore.
Condition Checking
Condition checking enable the linker script generation to be configuration-aware. Depending on whether expressions
involving configuration values are true or not, a particular set of values for a key can be used. The evaluation uses
eval_string from kconfiglib package and adheres to its required syntax and limitations. Supported operators are
as follows:
• comparison
– LessThan <
– LessThanOrEqualTo <=
– MoreThan >
– MoreThanOrEqualTo >=
– Equal =
– NotEqual !=
• logical
– Or ||
– And &&
– Negation !
• grouping
– Parenthesis ()
Condition checking behaves as you would expect an if...elseif/elif...else block in other languages.
Condition-checking is possible for both key values and entire fragments. The two sample fragments below are equiv-
alent:
# Value for keys is dependent on config

[type:name]
key_1:
if CONDITION = y:
value_1
else:
value_2
key_2:
if CONDITION = y:
value_a


else:
value_b
# Entire fragment definition is dependent on config

if CONDITION = y:
[type:name]
key_1:
value_1
key_2:
value_b
else:
[type:name]
key_1:
value_2
key_2:
value_b
Comments
Comment in linker fragment files begin with #. Like in other languages, comment are used to provide helpful de-
scriptions and documentation and are ignored during processing.
Compatibility with ESP-IDF v3.x Linker Script Fragment Files ESP-IDF v4.0 brings some changes to the
linker script fragment file grammar:
• indentation is enforced and improperly indented fragment files generate a parse exception; this was not enforced
in the old version but previous documentation and examples demonstrates properly indented grammar
• move to if...elif...else structure for conditionals, with the ability to nest checks and place entire
fragments themselves inside conditionals
• mapping fragments now requires a name like other fragment types
Linker script generator should be able to parse ESP-IDF v3.x linker fragment files that are indented properly (as
demonstrated by the ESP-IDF v3.x version of this document). Backward compatibility with the previous mapping
fragment grammar (optional name and the old grammar for conditionals) has also been retained but with a deprecation
warning. Users should switch to the newer grammar discussed in this document as support for the old grammar is
planned to be removed in the future.
Note that linker fragment files using the new ESP-IDF v4.0 grammar is not supported on ESP-IDF v3.x, however.
Types Sections
Sections fragments defines a list of object file sections that the GCC compiler emits. It may be a default section (e.g.
.text, .data) or it may be user defined section through the __attribute__ keyword.
The use of an optional + indicates the inclusion of the section in the list, as well as sections that start with it. This
is the preferred method over listing both explicitly.
[sections:name]
entries:
.section+
.section
...
Example:
# Non-preferred
[sections:text]
entries:
.text
.text.*


.literal
.literal.*
# Preferred, equivalent to the one above

[sections:text]
entries:
.text+ # means .text and .text.*
.literal+ # means .literal and .literal.*
Scheme
Scheme fragments define what target a sections fragment is assigned to.
[scheme:name]
entries:
sections -> target
sections -> target
...
Example:
[scheme:noflash]
entries:
text -> iram0_text # the entries under the sections fragment named␣
,→text will go to iram0_text
rodata -> dram0_data # the entries under the sections fragment named␣
,→rodata will go to dram0_data
The default scheme

There exists a special scheme with the name default. This scheme is special because catch-all placement rules
are generated from its entries. This means that, if one of its entries is text -> flash_text, the placement rule
will be generated for the target flash_text.
*(.literal .literal.* .text .text.*)
These catch-all rules then effectively serve as fallback rules for those whose mappings were not specified.
The default scheme is defined in esp_system/app.lf. The noflash and rtc scheme fragments which are
built-in schemes referenced in the quick start guide are also defined in this file.
Mapping
Mapping fragments define what scheme fragment to use for mappable entities, i.e. object files, function names,
variable names, archives.
[mapping:name]
archive: archive # output archive file name, as built (i.e. libxxx.
,→a)
entries:
object:symbol (scheme) # symbol granularity
object (scheme) # object granularity
* (scheme) # archive granularity
There are three levels of placement granularity:

• symbol: The object file name and symbol name are specified. The symbol name can be a function name or a
variable name.
• object: Only the object file name is specified.
• archive: * is specified, which is a short-hand for all the object files under the archive.
To know what an entry means, let us expand a sample object-granularity placement:

object (scheme)
Then expanding the scheme fragment from its entries definitions, we have:
object (sections -> target,

sections -> target,
...)
Expanding the sections fragment with its entries definition:
object (.section, # given this object file

.section, # put its sections listed here at this
... -> target, # target
.section,
.section, # same should be done for these sections
... -> target,
...) # and so on
Example:
[mapping:map]
archive: libfreertos.a
entries:
* (noflash)
Aside from the entity and scheme, flags can also be specified in an entry. The following flags are supported (note: <>
= argument name, [] = optional):
1. ALIGN(<alignment>[, pre, post])
Align the placement by the amount specified in alignment. Generates
2. SORT([<sort_by_first>, <sort_by_second>])
Emits SORT_BY_NAME, SORT_BY_ALIGNMENT, SORT_BY_INIT_PRIORITY or SORT in
the input section description.
Possible values for sort_by_first and sort_by_second are: name, alignment,
init_priority.
If both sort_by_first and sort_by_second are not specified, the input sections are sorted
by name. If both are specified, then the nested sorting follows the same rules discussed in https:
//sourceware.org/binutils/docs/ld/Input-Section-Wildcards.html.
3. KEEP()
Prevent the linker from discarding the placement by surrounding the input section description with
KEEP command. See https://sourceware.org/binutils/docs/ld/Input-Section-Keep.html for more
details.
4.SURROUND(<name>)
Generate symbols before and after the placement. The generated symbols follow the naming
_<name>_start and _<name>_end. For example, if name == sym1,
When adding flags, the specific section -> target in the scheme needs to be specified. For multiple section
-> target, use a comma as a separator. For example,
# Notes:
# A. semicolon after entity-scheme
# B. comma before section2 -> target2
# C. section1 -> target1 and section2 -> target2 should be defined in entries of␣
,→scheme1
entity1 (scheme1);
section1 -> target1 KEEP() ALIGN(4, pre, post),
section2 -> target2 SURROUND(sym) ALIGN(4, post) SORT()

Putting it all together, the following mapping fragment, for example,
[mapping:name]
archive: lib1.a
entries:
obj1 (noflash);
rodata -> dram0_data KEEP() SORT() ALIGN(8) SURROUND(my_sym)
generates an output on the linker script:
. = ALIGN(8)
_my_sym_start = ABSOLUTE(.)
KEEP(lib1.a:obj1.*( SORT(.rodata) SORT(.rodata.*) ))
_my_sym_end = ABSOLUTE(.)
Note that ALIGN and SURROUND, as mentioned in the flag descriptions, are order sensitive. Therefore, if for the
same mapping fragment these two are switched, the following is generated instead:
_my_sym_start = ABSOLUTE(.)
. = ALIGN(8)
KEEP(lib1.a:obj1.*( SORT(.rodata) SORT(.rodata.*) ))
_my_sym_end = ABSOLUTE(.)
On Symbol-Granularity Placements Symbol granularity placements is possible due to compiler flags -

ffunction-sections and -ffdata-sections. ESP-IDF compiles with these flags by default. If the user
opts to remove these flags, then the symbol-granularity placements will not work. Furthermore, even with the pres-
ence of these flags, there are still other limitations to keep in mind due to the dependence on the compiler s emitted
output sections.
For example, with -ffunction-sections, separate sections are emitted for each function; with section names
predictably constructed i.e. .text.{func_name} and .literal.{func_name}. This is not the case for
string literals within the function, as they go to pooled or generated section names.
With -fdata-sections, for global scope data the compiler predictably emits either .data.{var_name},
.rodata.{var_name} or .bss.{var_name}; and so Type I mapping entry works for these. However,
this is not the case for static data declared in function scope, as the generated section name is a result of mangling
the variable name with some other information.
Linker Script Template
The linker script template is the skeleton in which the generated placement rules are put into. It is an otherwise
ordinary linker script, with a specific marker syntax that indicates where the generated placement rules are placed.
To reference the placement rules collected under a target token, the following syntax is used:
mapping[target]
Example:
The example below is an excerpt from a possible linker script template. It defines an output section .iram0.text,
and inside is a marker referencing the target iram0_text.
.iram0.text :
{
/* Code marked as runnning out of IRAM */
_iram_text_start = ABSOLUTE(.);
/* Marker referencing iram0_text */

mapping[iram0_text]


_iram_text_end = ABSOLUTE(.);
} > iram0_0_seg
Suppose the generator collected the fragment definitions below:
[sections:text]
.text+
.literal+
[sections:iram]
.iram1+
[scheme:default]
entries:
text -> flash_text
iram -> iram0_text
[scheme:noflash]
entries:
text -> iram0_text
[mapping:freertos]
archive: libfreertos.a
entries:
* (noflash)
Then the corresponding excerpt from the generated linker script will be as follows:
.iram0.text :
{
/* Code marked as runnning out of IRAM */
_iram_text_start = ABSOLUTE(.);
/* Placement rules generated from the processed fragments, placed where the␣
,→ marker was in the template */
*(.iram1 .iram1.*)
*libfreertos.a:(.literal .text .literal.* .text.*)
_iram_text_end = ABSOLUTE(.);
} > iram0_0_seg
*libfreertos.a:(.literal .text .literal.* .text.*)

Rule generated from the entry * (noflash) of the freertos mapping fragment. All text sections
of all object files under the archive libfreertos.a will be collected under the target iram0_text
(as per the noflash scheme) and placed wherever in the template iram0_text is referenced by a
marker.
*(.iram1 .iram1.*)
Rule generated from the default scheme entry iram -> iram

ESP32 - ESP - IDF Programming Guide

Uploaded by

Copyright:

Available Formats

ESP32 - ESP - IDF Programming Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

ESP32 - ESP - IDF Programming Guide

Uploaded by

Copyright:

Available Formats

ESP-IDF Programming Guide

2 API Reference 127

4 API Guides 1727

5 ESP-IDF 5.0 Migration Guides 2079

6 Libraries and Frameworks 2081

7 Contributions Guide 2085

8 ESP-IDF Versions 2107

10 Copyrights and Licenses 2115

12 Switch Between Languages 2121

Get Started API Reference H/W Reference

API Guides Contribute Resources

Espressif Systems 1 Release v5.0-dev-401-g451ce8a

Espressif Systems 2 Release v5.0-dev-401-g451ce8a

1.2 What You Need

Fig. 1: Development of applications for ESP32

1.3 Development Board Overviews

1.3.1 ESP32-DevKitC V4 Getting Started Guide

What You Need

Espressif Systems 4 Release v5.0-dev-401-g451ce8a

Fig. 2: ESP32-DevKitC V4 with ESP32-WROOM-32 module soldered

Espressif Systems 5 Release v5.0-dev-401-g451ce8a

Key Component Description

Power Supply Options

Espressif Systems 6 Release v5.0-dev-401-g451ce8a

P: Power supply; I: Input; O: Output.

Espressif Systems 7 Release v5.0-dev-401-g451ce8a

Fig. 3: ESP32-DevKitC Pin Layout (click to enlarge)

Fig. 4: Location of C15 (yellow) on ESP32-DevKitC V4 board

Espressif Systems 8 Release v5.0-dev-401-g451ce8a

Start Application Development

Fig. 5: Dimensions of ESP32-DevKitC board with ESP32-WROOM-32 module soldered - back

• ESP32-DevKitC V4 schematics (PDF)

What You Need

Espressif Systems 9 Release v5.0-dev-401-g451ce8a

Overview ESP32-DevKitC V2 is a small-sized ESP32-based development board produced by Espressif. Most of

Fig. 6: ESP32-DevKitC V2 board layout

Key Com- Description

Espressif Systems 10 Release v5.0-dev-401-g451ce8a

1.3.2 ESP-WROVER-KIT V4.1 Getting Started Guide

What You Need

• ESP-WROVER-KIT V4.1 board

ESP-WROVER-KIT is an ESP32-based development board produced by Espressif.

Espressif Systems 11 Release v5.0-dev-401-g451ce8a

Fig. 7: ESP-WROVER-KIT block diagram

Fig. 8: ESP-WROVER-KIT board layout - front

Espressif Systems 12 Release v5.0-dev-401-g451ce8a

Fig. 9: ESP-WROVER-KIT board layout - back

• Then moving on to the second picture

Espressif Systems 13 Release v5.0-dev-401-g451ce8a

Key Component Description

Espressif Systems 14 Release v5.0-dev-401-g451ce8a

Espressif Systems 15 Release v5.0-dev-401-g451ce8a

Header Jumper Setting Description of Functionality

JP7 Power ESP-WROVER-KIT via an external power

JP7 Power ESP-WROVER-KIT via USB

JP2 Enable JTAG functionality

Espressif Systems 16 Release v5.0-dev-401-g451ce8a

Allocation of ESP32 Pins

Shared With I/O I/O Shared With