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.8.5 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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.18.10 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1902
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.10 Technical Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1978
4.26.11 Secure Boot & Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1980
4.26.12 Signed App Verification Without Hardware Secure Boot . . . . . . . . . . . . . . . . . . 1980
4.26.13 Advanced Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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.14 Technical Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1985
4.27.15 Secure Boot & Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1985
4.27.16 Signed App Verification Without Hardware Secure Boot . . . . . . . . . . . . . . . . . . 1985
4.27.17 Advanced Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1986

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

Espressif Systems 2 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
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
• Computer running Windows, Linux, or macOS
You can skip the introduction sections and go directly to Section Start Application Development.

Espressif Systems 4 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

Espressif Systems 5 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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).

Espressif Systems 6 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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
17 IO10 I/O GPIO10, D3
18 IO11 I/O GPIO11, CMD
19 5V0 P 5 V power supply

J3
No. Name Type Function
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
13 IO4 I/O GPIO4, ADC2_CH0, TOUCH_CH0
14 IO0 I/O GPIO0, ADC2_CH1, TOUCH_CH1, Boot
16 IO2 I/O GPIO2, ADC2_CH2, TOUCH_CH2
17 IO15 I/O GPIO15, ADC2_CH3, TOUCH_CH3, MTDO
17 IO8 I/O GPIO8, D1
18 IO7 I/O GPIO7, D0
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.

Espressif Systems 7 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

Submit Document Feedback
Chapter 1. Get Started

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
• Computer running Windows, Linux, or macOS

Espressif Systems 9 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

You can skip the introduction sections and go directly to Section Start Application Development.

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:
• 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.

Espressif Systems 10 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.
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.

Related Documents
• ESP32-DevKitC schematics (PDF)
• ESP32 Datasheet (PDF)
• ESP32-WROOM-32 Datasheet (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
• Computer running Windows, Linux, or macOS
You can skip the introduction sections and go directly to Section Start Application Development.

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.

Functional Description

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

Espressif Systems 11 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Fig. 7: ESP-WROVER-KIT block diagram

Fig. 8: ESP-WROVER-KIT board layout - front

Espressif Systems 12 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Fig. 9: ESP-WROVER-KIT board layout - back

• Then moving on to the second picture

Espressif Systems 13 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Key Component Description

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
Download mode for downloading firmware through the serial port.
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.

Espressif Systems 14 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.

Espressif Systems 15 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

Espressif Systems 16 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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
Camera IO39 IO36 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.

Espressif Systems 17 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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
10 GPIO34 D6 / Pixel Data Bit 6
11 GPIO39 D5 / Pixel Data Bit 5
12 GPIO36 D4 / Pixel Data Bit 4
13 GPIO19 D3 / Pixel Data Bit 3
14 GPIO18 D2 / Pixel Data Bit 2
15 GPIO5 D1 / Pixel Data Bit 1
16 GPIO4 D0 / Pixel Data Bit 0
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

Espressif Systems 18 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

Start Application Development

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.

Espressif Systems 19 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Related Documents

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

• ESP-WROVER-KIT V4.1 layout (DXF) may be opened online with Autodesk Viewer
• ESP32 Datasheet (PDF)
• 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
• USB 2.0 cable A to Micro-B
• Computer running Windows, Linux, or macOS
You can skip the introduction sections and go directly to Section Start Application Development.

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
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: 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.
The table below provides description in the following manner:
• Starting from the first picture s top right corner and going clockwise
• Then moving on to the second picture

Espressif Systems 20 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Fig. 10: ESP-WROVER-KIT block diagram

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
Chapter 1. Get Started

Fig. 11: ESP-WROVER-KIT board layout - front

Espressif Systems 22 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Fig. 12: ESP-WROVER-KIT board layout - back

Espressif Systems 23 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.

Espressif Systems 24 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Header Jumper Setting Description of Functionality

JP7 Power ESP-WROVER-KIT via an external power

supply

JP7 Power ESP-WROVER-KIT via USB

JP8 Enable JTAG functionality

Espressif Systems 25 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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
Camera IO35 IO34 Camera
Camera IO39 IO36 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 / 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.

Espressif Systems 26 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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
9 GPIO35 D7 / Pixel Data Bit 7
10 GPIO34 D6 / Pixel Data Bit 6
11 GPIO39 D5 / Pixel Data Bit 5
12 GPIO36 D4 / Pixel Data Bit 4
13 GPIO19 D3 / Pixel Data Bit 3
14 GPIO18 D2 / Pixel Data Bit 2
15 GPIO5 D1 / Pixel Data Bit 1
16 GPIO4 D0 / Pixel Data Bit 0
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

Espressif Systems 27 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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
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 JP11.

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.

Espressif Systems 28 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Related Documents
• ESP-WROVER-KIT V3 schematic (PDF)
• ESP32 Datasheet (PDF)
• ESP32-WROVER Datasheet (PDF)
• ESP32-WROOM-32 Datasheet (PDF)
• JTAG Debugging
• ESP32 Hardware Reference

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
• USB 2.0 cable A to Micro-B
• Computer running Windows, Linux, or macOS
You can skip the introduction sections and go directly to Section Start Application Development.

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
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: 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.
The table below provides description in the following manner:
• Starting from the first picture s top right corner and going clockwise
• Then moving on to the second picture

Espressif Systems 29 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Fig. 13: ESP-WROVER-KIT block diagram

Fig. 14: ESP-WROVER-KIT board layout - front

Espressif Systems 30 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Fig. 15: ESP-WROVER-KIT board layout - back

Espressif Systems 31 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.
USB USB interface. Power supply for the board as well as the communication interface between a computer
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
In- connected to a computer).
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.

Espressif Systems 32 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Header Jumper Setting Description of Functionality

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

JP7 Power ESP-WROVER-KIT via USB

Espressif
JP8 Systems Enable33JTAG functionality Release v5.0-dev-401-g451ce8a
Submit Document Feedback
Chapter 1. Get Started

Start Application Development 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 JP11.

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 V2 schematic (PDF)
• ESP32 Datasheet (PDF)
• ESP32-WROVER Datasheet (PDF)
• ESP32-WROOM-32 Datasheet (PDF)
• JTAG Debugging
• ESP32 Hardware Reference

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
• Computer running Windows, Linux, or macOS
You can skip the introduction sections and go directly to Section Start Application Development.

Espressif Systems 34 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.

Functionality Overview

The block diagram below shows the main components of ESP32-PICO-KIT and their interconnections.

Fig. 16: ESP32-PICO-KIT block diagram

Espressif Systems 35 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Functional Description

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.

Espressif Systems 36 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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:
• 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.

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.

Espressif Systems 37 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Header J2

No. Name Type Function

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

2 FLASH_SD3 (FSD3) I/O

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
Espressif Systems 38 Release v5.0-dev-401-g451ce8a
Submit Document Feedback GPIO3, U0RXD (See 3) ,
CLK_OUT2
Chapter 1. Get Started

Espressif Systems 39 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Header J3

No. Name Type Function

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

2 FLASH_SD0 (FSD0) I/O

GPIO17, HS1_DATA5
(See 1) , U2TXD,
EMAC_CLK_OUT_180

3 FLASH_SD2 (FSD2) I/O

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
Submit Document Feedback
ADC2_CH6, TOUCH6,
RTC_GPIO16, MTMS,
HSPICLK,
Chapter 1. Get Started

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.

Start Application Development

Before powering up your ESP32-PICO-KIT, 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

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 Hardware Reference

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.

Espressif Systems 41 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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
• Computer running Windows, Linux, or macOS
You can skip the introduction sections and go directly to Section Start Application Development.

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
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.

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

Espressif Systems 42 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

Espressif Systems 43 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.
LDO 5V-to-3.3V Low dropout voltage regulator (LDO).
USB- Single-chip USB-UART bridge provides up to 1 Mbps transfers rates.
UART
bridge
Micro USB interface. Power supply for the board as well as the communication interface between a computer
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.
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

Start Application Development Before powering up your ESP32-PICO-KIT V3, 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.

Related Documents
• ESP32-PICO-KIT V3 schematic (PDF)
• ESP32-PICO-D4 Datasheet (PDF)
• ESP32 Hardware Reference

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
• Computer running Windows, Linux, or macOS
You can skip the introduction sections and go directly to Section Start Application Development.

Espressif Systems 44 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

Espressif Systems 45 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.

Functionality Overview

The block diagram below shows the main components of ESP32-Ethernet-Kit and their interconnections.

Functional Description

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

Espressif Systems 46 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Fig. 23: ESP32-Ethernet-Kit block diagram (click to enlarge)

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

Espressif Systems 47 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

Espressif Systems 48 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.
USB USB interface. Power supply for the board as well as the communication interface between a computer
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.
5V The 5V power supply interface can be more convenient when the board is operating autonomously (not
In- connected to a computer).
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
But- downloading firmware through the serial port.
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
Chapter 1. Get Started

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)

Key Component Description
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).

Espressif Systems 50 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.

Espressif Systems 51 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Fig. 27: RMII Clock from ESP Internal APLL

Espressif Systems 52 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

Espressif Systems 53 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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
IO17 IO17 (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
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.

Espressif Systems 54 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Start Application Development

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
V1.2 Ethernet board (A) schematic.
• Replace ESP32-WROVER-B with ESP32-WROVER-E.

Other Versions of ESP32-Ethernet-Kit

• ESP32-Ethernet-Kit V1.0 Getting Started Guide

• ESP32-Ethernet-Kit V1.1 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 Datasheet (PDF)
• ESP32-WROVER-E Datasheet (PDF)
• JTAG Debugging
• ESP32 Hardware Reference
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.
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).

Espressif Systems 55 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

What You Need

• ESP32-Ethernet-Kit V1.0 board
• USB 2.0 A to Micro B Cable
• Computer running Windows, Linux, or macOS
You can skip the introduction sections and go directly to Section Start Application Development.

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
Transceiver (PHY). The PoE board (B) provides power over Ethernet functionality. The A board can work indepen-
dently, without the board B installed.

Fig. 28: ESP32-Ethernet-Kit V1.0

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.

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.

Espressif Systems 56 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Fig. 29: ESP32-Ethernet-Kit block diagram (click to enlarge)

Fig. 30: ESP32-Ethernet-Kit - Ethernet board (A) layout (click to enlarge)

Espressif Systems 57 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

Espressif Systems 58 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Key Description
Com-
po-
nent
ESP32- This ESP32 module features 64-Mbit PSRAM for flexible extended storage and data processing capabil-
WROVER- ities.
B
GPIO Five unpopulated through-hole solder pads to provide access to selected GPIOs of ESP32. For details,
Header see GPIO Header 2.
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
Tx/Rx Two LEDs to show the status of UART transmission.
LEDs
GPIO Provides access to some GPIOs of ESP32 that can be used depending on the position of the Function
Header Switch.
3
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.0 Ethernet board (A) schematic.
USB USB interface. Power supply for the board as well as the communication interface between a computer
Port and the board.
Power Power On/Off Switch. Toggling toward the Boot button powers the board on, toggling away from Boot
Switch powers the board off.
5V The 5V power supply interface can be more convenient when the board is operating autonomously (not
In- connected to a computer).
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 2A.
Con-
verter
Board A pair male 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/100Mbps.
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 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-
Chapter 1. Get Started

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. 31: ESP32-Ethernet-Kit - PoE board (B) layout (click to enlarge)

Key Component Description

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
2 GPIO12 Connected to FT2232H to provide JTAG functionality
3 GPIO13 Connected to FT2232H to provide JTAG functionality
4 GPIO15 Connected to FT2232H to provide JTAG functionality
5 GPIO4 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.

Espressif Systems 60 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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).

. 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: 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.

GPIO Header 1 This header exposes some GPIOs that are not used elsewhere on the ESP32-Ethernet-Kit.

. 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,
e.g. the ESP32-WROOM-32D or ESP32-SOLO-1.
2. Functionality depends on the settings of the Function Switch.

Espressif Systems 61 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

GPIO Allocation Summary

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.
4. 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,
e.g. the ESP32-WROOM-32D or ESP32-SOLO-1.

Start Application Development Before powering up your ESP32-Ethernet-Kit, please make sure that the board
is in good condition with no obvious signs of damage.

Espressif Systems 62 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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 the application, do not install any jumpers and do not connect any 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.0 board.

Related Documents
• ESP32-Ethernet-Kit V1.0 Ethernet board (A) schematic (PDF)
• ESP32-Ethernet-Kit V1.0 PoE board (B) schematic (PDF)
• ESP32 Datasheet (PDF)
• ESP32-WROVER-B Datasheet (PDF)
• JTAG Debugging
• ESP32 Hardware Reference
For other design documentation for the board, please contact us at [email protected].

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.
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.1 board
• USB 2.0 A to Micro B Cable
• Computer running Windows, Linux, or macOS
You can skip the introduction sections and go directly to Section Start Application Development.

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
Transceiver (PHY). The PoE board (B) provides power over Ethernet functionality. The A board can work indepen-
dently, without the board B installed.
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.

Functionality Overview The block diagram below shows the main components of ESP32-Ethernet-Kit and their
interconnections.

Espressif Systems 63 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

Fig. 33: ESP32-Ethernet-Kit block diagram (click to enlarge)

Espressif Systems 64 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

Fig. 34: 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.

Espressif Systems 65 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Key Description
Com-
po-
nent
ESP32- This ESP32 module features 64-Mbit PSRAM for flexible extended storage and data processing capabil-
WROVER- ities.
B
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. 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.
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.1 Ethernet board (A) schematic.
USB USB interface. Power supply for the board as well as the communication interface between a computer
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.
5V The 5V power supply interface can be more convenient when the board is operating autonomously (not
In- connected to a computer).
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 2A.
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/100Mbps.
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
But- downloading firmware through the serial port.
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
Chapter 1. Get Started

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. 35: ESP32-Ethernet-Kit - PoE board (B) layout (click to enlarge)

Table 2: Table PoE board (B)

Key Component Description
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.

Espressif Systems 67 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.

Espressif Systems 68 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Fig. 37: RMII Clock from ESP Internal APLL

Espressif Systems 69 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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).

. 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: 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.

GPIO Header 1 This header exposes some GPIOs that are not used elsewhere on the ESP32-Ethernet-Kit.

. 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:
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 PSRAM memory inside,
e.g. the ESP32-WROOM-32D or ESP32-SOLO-1.
2. Functionality depends on the settings of the Function Switch.

Espressif Systems 70 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

GPIO Allocation Summary

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
IO16 IO16 (NC) See note 2
IO17 IO17 (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.1 Ethernet board (A) schematic.
2. 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 PSRAM memory inside,
e.g. the ESP32-WROOM-32D or ESP32-SOLO-1.

Start Application Development 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.

Espressif Systems 71 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.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

• ESP32-Ethernet-Kit V1.0 Getting Started Guide

Related Documents
• ESP32-Ethernet-Kit V1.1 Ethernet board (A) schematic (PDF)
• ESP32-Ethernet-Kit V1.0 PoE board (B) schematic (PDF)
• ESP32 Datasheet (PDF)
• ESP32-WROVER-B Datasheet (PDF)
• JTAG Debugging
• ESP32 Hardware Reference
For other design documentation for the board, please contact us at [email protected].

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.

Espressif Systems 72 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

Espressif Systems 73 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Fig. 38: ESP32-DevKitS - front

Fig. 39: ESP32-DevKitS-R - front

Espressif Systems 74 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Key Component Description

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)
• Computer running Windows, Linux, or macOS

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

Espressif Systems 75 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Fig. 40: ESP32-DevKitS board dimensions - back

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

Espressif Systems 76 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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)

Power Supply Options There are three mutually exclusive ways to provide power to the board:
• Micro USB port, default power supply
• 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

Espressif Systems 77 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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 Datasheet (PDF)
• ESP32-WROOM-32 Datasheet (PDF)
• ESP32-WROOM-32D & ESP32-WROOM-32U Datasheet (PDF)
• ESP32-SOLO-1 Datasheet (PDF)
• ESP32-WROVER Datasheet (PDF)
• ESP32-WROVER-B Datasheet (PDF)
• ESP Product Selector

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

Espressif Systems 78 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

• 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
computer s USB port for flashing and debugging.
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.
• Related Documents: Gives links to related documentation.

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.
Below is the description of the items identified in the figure starting from the top left corner and going clockwise.

Espressif Systems 79 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

Espressif Systems 80 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.
LDO 5V-to-3.3V Low dropout voltage regulator (LDO).
USB- CP2102N, single-chip USB-to-UART bridge that offers up to 3 Mbps transfers rates.
to-
UART
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 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.
BOOT Download button. Holding down Boot and then pressing EN initiates Firmware Download mode for
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
is in good condition with no obvious signs of damage.

Required Hardware
• 1 x ESP32-PICO-KIT-1
• 1 x USB 2.0 A to Micro B cable

Espressif Systems 81 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

• 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.

Contents and Packaging

Retail Orders If you order one or several samples of the board, each ESP32-PICO-KIT-1 development board
comes in an individual package.
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 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)

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.

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.

Espressif Systems 82 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Header J2

No. Name Type Function

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
13 IO34 I ADC1_CH6, RTC_GPIO4
14 IO38 I GPIO38, ADC1_CH2, RTC_GPIO2
15 IO37 I GPIO37, ADC1_CH1, RTC_GPIO1
16 EN I CHIP_PU
17 GND P Ground
18 VDD33 P 3.3 V power supply
(3V3)

Header J3

No. Name Type Function

1 GND P Ground
2 SENSOR_VP
I GPIO36, ADC1_CH0, RTC_GPIO0
(FSVP)
3 SENSOR_VN
I GPIO39, ADC1_CH3, RTC_GPIO3
(FSVN)
4 IO25 I/O GPIO25, DAC_1, ADC2_CH8, RTC_GPIO6, EMAC_RXD0
5 IO26 I/O GPIO26, DAC_2, ADC2_CH9, RTC_GPIO7, EMAC_RXD1
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)

The following notes give more information about the items in the tables above.

Espressif Systems 83 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

1. This pin is connected to the pin of the USB bridge chip on the board.
2. 32.768 kHz crystal oscillator: a) input b) output
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)

• ESP Product Selector
• ESP32-PICO-KIT-1 Schematic (PDF)
• ESP32-PICO-KIT-1 PCB Layout (PDF)
For other design documentation for the board, please contact us at [email protected].

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
computer s USB port for flashing and debugging.
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.

Espressif Systems 84 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.
• Related Documents: Gives links to related documentation.

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.
Below is the description of the items identified in the figure starting from the top left corner and going clockwise.

Espressif Systems 85 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.
LDO 5V-to-3.3V Low dropout voltage regulator (LDO).
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.
BOOT Download button. Holding down Boot and then pressing EN initiates Firmware Download mode for
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

Espressif Systems 86 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Software Setup Please proceed to Get Started, where Section Installation Step by Step will quickly help you set up
the development environment.

Contents and Packaging

Retail Orders If you order one or several samples of the board, each ESP32-PICO-DevKitM-2 development board
comes in an individual package.
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 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)

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.

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.

Espressif Systems 87 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Header J2

No. Name Type Function

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 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
12 IO35 I ADC1_CH7, RTC_GPIO5
13 IO34 I ADC1_CH6, RTC_GPIO4
14 IO38 I GPIO38, ADC1_CH2, RTC_GPIO2
15 IO37 I GPIO37, ADC1_CH1, RTC_GPIO1
16 EN I CHIP_PU
17 GND P Ground
18 VDD33 P 3.3 V power supply
(3V3)

Header J3

No. Name Type Function

1 GND P Ground
2 SENSOR_VP
I GPIO36, ADC1_CH0, RTC_GPIO0
(FSVP)
3 SENSOR_VN
I GPIO39, ADC1_CH3, RTC_GPIO3
(FSVN)
4 IO25 I/O GPIO25, DAC_1, ADC2_CH8, RTC_GPIO6, EMAC_RXD0
5 IO26 I/O GPIO26, DAC_2, ADC2_CH9, RTC_GPIO7, EMAC_RXD1
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)

The following notes give more information about the items in the tables above.

Espressif Systems 88 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

1. This pin is connected to the pin of the USB bridge chip on the board.
2. 32.768 kHz crystal oscillator: a) input b) output
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

Hardware Revision Details

No previous versions available.

Related Documents

• ESP32-PICO-MINI-02 & ESP32-PICO-MINI-1U Datasheet (PDF)

• ESP Product Selector
• ESP32-PICO-DevKitM-2 Schematic (PDF)
• ESP32-PICO-DevKitM-2 PCB Layout (PDF)
For other design documentation for the board, please contact us at [email protected].

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.

Espressif Systems 89 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

Contents and Packaging

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.
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.

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.

Espressif Systems 90 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Fig. 51: ESP32-DevKitM-1 - front

Key Component Description

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
Download mode for downloading firmware through the serial port.
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)
• 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 and then flash an application example onto your ESP32-DevKitM-1.

Espressif Systems 91 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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:
• Micro USB port, default power supply
• 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.

No. Name Type Function

1 GND P Ground
2 3V3 P 3.3 V power supply
3 I36 I GPIO36, ADC1_CH0, RTC_GPIO0
4 I37 I GPIO37, ADC1_CH1, RTC_GPIO1
Continued on next page

Espressif Systems 92 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Table 4 – continued from previous page

No. Name Type Function
5 I38 I GPIO38, ADC1_CH2, RTC_GPIO2
6 I39 I GPIO39, ADC1_CH3, RTC_GPIO3
7 RST I Reset; High: enable; Low: powers off
8 I34 I GPIO34, ADC1_CH6, RTC_GPIO4
9 I35 I GPIO35, ADC1_CH7, RTC_GPIO5
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
12 IO25 I/O GPIO25, DAC_1, ADC2_CH8, RTC_GPIO6, EMAC_RXD0
13 IO26 I/O GPIO26, DAC_2, ADC2_CH9, RTC_GPIO7, EMAC_RXD1
14 IO27 I/O GPIO27, ADC2_CH7, TOUCH7, RTC_GPIO17, EMAC_RX_DV
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,
HS2_DATA2, SD_DATA2, EMAC_TXD3
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
28 IO19 I/O GPIO19, VSPIQ, U0CTS, EMAC_TXD0
29 IO22 I/O GPIO22, VSPIWP, U0RTS, EMAC_TXD1
30 IO21 I/O GPIO21, VSPIHD, EMAC_TX_EN
31 TXD0 I/O GPIO1, U0TXD, CLK_OUT3, EMAC_RXD2
32 RXD0 I/O GPIO3, U0RXD, CLK_OUT2

Hardware Revision Details

No previous versions available.

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
• ESP32 Datasheet (PDF)
• ESP Product Selector
For other design documentation for the board, please contact us at [email protected].

Espressif Systems 93 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

Espressif Systems 94 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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):

Espressif Systems 95 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Fig. 54: ESP-IDF PowerShell

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

Espressif Systems 96 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Fig. 56: ESP-IDF Command Prompt

Espressif Systems 97 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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:

Espressif Systems 98 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.

Espressif Systems 99 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

1.5.3 Standard Setup of Toolchain for Mac OS

Install Prerequisites

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.

Espressif Systems 100 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.
Consult ESP-IDF Versions for information about which ESP-IDF version to use in a given situation.
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.

Espressif Systems 101 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

1.7.2 Linux and macOS

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

Espressif Systems 102 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

1.8.2 Linux and macOS

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.

Espressif Systems 103 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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:

1.9.1 Linux and macOS

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.

1.11.1 Linux and macOS

cd ~/esp/hello_world
idf.py set-target esp32
idf.py menuconfig

Espressif Systems 104 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.

Espressif Systems 105 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

$ 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

Espressif Systems 106 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.

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

Hash of data verified.

Compressed 147104 bytes to 77364...
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)...

Hash of data verified.

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.

Espressif Systems 107 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

Restarting in 9 seconds...
Restarting in 8 seconds...
Restarting in 7 seconds...

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.

Espressif Systems 108 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

Espressif Systems 109 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

Espressif Systems 110 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

Espressif Systems 111 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.

Espressif Systems 112 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Fig. 60: Setting Serial Communication in PuTTY on Windows

Espressif Systems 113 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Fig. 61: Setting Serial Communication in PuTTY on Linux

Espressif Systems 114 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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:0x3fff0010,len:3464
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.

Espressif Systems 115 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.

Espressif Systems 116 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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:

Espressif Systems 117 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT :␣

,→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_

,→world/main/./hello_world_main.c:52

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

,→world/main/./hello_world_main.c:47

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

Espressif Systems 118 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.

Espressif Systems 119 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

• 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:
E (31) esp_image: image at 0x30000 has invalid magic byte
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
I (569) heap_init: Initializing. RAM available for dynamic allocation:
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.

Espressif Systems 120 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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.

Consult ESP-IDF Versions for information about which ESP-IDF version to use in a given situation.

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).

Espressif Systems 121 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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

Espressif Systems 122 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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
git submodule update --init
./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:

Espressif Systems 123 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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 Prerequisites
• 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:

Espressif Systems 124 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

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
git submodule update --init
./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.

Espressif Systems 125 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 1. Get Started

Espressif Systems 126 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
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.
Return ESP_OK - success, other - failed
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.
Return ESP_OK - success, other - failed
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.
Return ESP_OK - success, other - failed
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.
Return ESP_OK - success, other - failed
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.
Return ESP_OK - success, other - failed
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.
Return ESP_OK - success, other - failed
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.
Return ESP_OK - success, other - failed
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.

Espressif Systems 128 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
Return ESP_OK - success, other - failed
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.

Espressif Systems 129 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
Return ESP_OK - success, other - failed
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
• ESP_OK : success
• 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
• ESP_OK : success
• 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

Espressif Systems 130 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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)

Espressif Systems 131 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 132 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_CONN_HDL1 = 1
For connection handle 1
ESP_BLE_PWR_TYPE_CONN_HDL2 = 2
For connection handle 2
ESP_BLE_PWR_TYPE_CONN_HDL3 = 3
For connection handle 3
ESP_BLE_PWR_TYPE_CONN_HDL4 = 4
For connection handle 4
ESP_BLE_PWR_TYPE_CONN_HDL5 = 5
For connection handle 5
ESP_BLE_PWR_TYPE_CONN_HDL6 = 6
For connection handle 6
ESP_BLE_PWR_TYPE_CONN_HDL7 = 7
For connection handle 7
ESP_BLE_PWR_TYPE_CONN_HDL8 = 8
For connection handle 8
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

Espressif Systems 133 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
Corresponding to -9dbm
ESP_PWR_LVL_N6 = 2
Corresponding to -6dbm
ESP_PWR_LVL_N3 = 3
Corresponding to -3dbm
ESP_PWR_LVL_N0 = 4
Corresponding to 0dbm
ESP_PWR_LVL_P3 = 5
Corresponding to +3dbm
ESP_PWR_LVL_P6 = 6
Corresponding to +6dbm
ESP_PWR_LVL_P9 = 7
Corresponding to +9dbm
ESP_PWR_LVL_N14 = ESP_PWR_LVL_N12
Backward compatibility! Setting to -14dbm will actually result to -12dbm
ESP_PWR_LVL_N11 = ESP_PWR_LVL_N9
Backward compatibility! Setting to -11dbm will actually result to -9dbm
ESP_PWR_LVL_N8 = ESP_PWR_LVL_N6
Backward compatibility! Setting to -8dbm will actually result to -6dbm
ESP_PWR_LVL_N5 = ESP_PWR_LVL_N3
Backward compatibility! Setting to -5dbm will actually result to -3dbm
ESP_PWR_LVL_N2 = ESP_PWR_LVL_N0
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
ESP_PWR_LVL_P4 = ESP_PWR_LVL_P6
Backward compatibility! Setting to +4dbm will actually result to +6dbm
ESP_PWR_LVL_P7 = ESP_PWR_LVL_P9
Backward compatibility! Setting to +7dbm will actually result to +9dbm
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

Espressif Systems 134 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 135 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 136 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Overview Instructions

Application Example Instructions

API Reference

Header File
• components/bt/host/bluedroid/api/include/api/esp_bt_main.h

Espressif Systems 137 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• ESP_OK : Succeed
• Other : Failed
esp_err_t esp_bluedroid_init(void)
Init and alloc the resource for bluetooth, must be prior to every bluetooth stuff.
Return
• ESP_OK : Succeed
• Other : Failed
esp_err_t esp_bluedroid_deinit(void)
Deinit and free the resource for bluetooth, must be after every bluetooth stuff.
Return
• ESP_OK : Succeed
• 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

Application Example Instructions

API Reference

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

Espressif Systems 138 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_OK : Succeed
• 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

Overview Instructions

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
• ESP_OK : success
• 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
• ESP_OK : success
• other : failed

Espressif Systems 139 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• ESP_OK : success
• 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
• ESP_OK : success
• 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
• ESP_OK : success
– 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
• ESP_OK : success
• 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
• ESP_OK : success
• 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
• ESP_OK : success
• 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
• ESP_OK : success
• 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.

Espressif Systems 140 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Return
• ESP_OK : success
• 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
• ESP_OK : success
• other : failed
esp_err_t esp_ble_gap_config_local_privacy(bool privacy_enable)
Enable/disable privacy on the local device.
Return
• ESP_OK : success
• 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
• ESP_OK : success
• 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
• ESP_OK : success
• 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
• ESP_OK : success
• other : failed
esp_err_t esp_ble_gap_get_whitelist_size(uint16_t *length)
Get the whitelist size in the controller.
Return
• ESP_OK : success
• other : failed
Parameters
• [out] length: the white list length.

Espressif Systems 141 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• ESP_OK : success
• 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
• ESP_OK : success
• 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
• ESP_OK : success
• 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
• ESP_OK : success
• other : failed
Parameters

Espressif Systems 142 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• [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
• ESP_OK : success
• 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
• ESP_OK : success
• 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
• ESP_OK : success
• 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
• ESP_OK : success
• 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:

Espressif Systems 143 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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).
Return - ESP_OK : success
• 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.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success
• other : failed
Parameters
• [in] bd_addr: : BD address of the peer
• [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.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success
• other : failed
Parameters
• [in] bd_addr: : BD address of the peer device
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

Espressif Systems 144 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success
• other : failed
Parameters
• [in] bd_addr: BD address of the peer device.
• [out] conn_params: the connection parameters information
esp_err_t esp_gap_ble_set_channels(esp_gap_ble_channels channels)
BLE set channels.
Return - ESP_OK : success
• 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)
Return - ESP_OK : success
• other : failed
Parameters
• [in] bd_addr: BD address of the peer device.
• [out] authorize: Authorized the link or not.

Espressif Systems 145 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
Return - ESP_OK : success
• other : failed
Parameters
• [in] bd_addr: : BD address of the peer device
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.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success

Espressif Systems 146 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• 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.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success
• other : failed
Parameters
• [in] instance: : Used to identify an advertising set
esp_err_t esp_ble_gap_ext_adv_set_clear(void)
This function is used to remove all existing advertising sets from the Controller.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success
• other : failed
Parameters
• [in] instance: : identifies the advertising set whose periodic advertising parameters are being
configured.
• [in] params: : periodic adv parameters

Espressif Systems 147 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success
• other : failed
Parameters
• [in] instance: : Used to identify an advertising set
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.
Return - ESP_OK : success
• other : failed
Parameters
• [in] instance: : Used to identify an advertising set
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.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success

Espressif Systems 148 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• 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.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success
• 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.
Return - ESP_OK : success
• 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
esp_ble_gap_conn_params_t
*phy_2m_conn_params, const
esp_ble_gap_conn_params_t
*phy_coded_conn_params)
This function is used to set aux connection parameters.
Return - ESP_OK : success
• 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.

Espressif Systems 149 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 150 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 151 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 152 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

esp_bt_status_t status
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

esp_bt_status_t status
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

esp_bt_status_t status
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

Espressif Systems 153 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

esp_bt_status_t status
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

esp_bt_status_t status
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

esp_bt_status_t status
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

esp_bt_status_t status
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.

Espressif Systems 154 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_bt_status_t status
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

esp_bt_status_t status
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

esp_bt_status_t status
Indicate advertising stop operation success status

struct ble_ext_adv_start_cmpl_evt_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_ADV_START_COMPLETE_EVT.

Public Members

esp_bt_status_t status
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

esp_bt_status_t status
Indicate advertising stop operation success status

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

esp_bt_status_t status
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

esp_bt_status_t status
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.

Espressif Systems 155 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_bt_status_t status
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

esp_bt_status_t status
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

esp_bt_status_t status
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

esp_bt_status_t status
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

esp_bt_status_t status
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

esp_bt_status_t status
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.

Espressif Systems 156 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_bt_status_t status
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

esp_bt_status_t status
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

esp_bt_status_t status
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

esp_bt_status_t status
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

esp_bt_status_t status
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

esp_bt_status_t status
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.

Espressif Systems 157 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_bt_status_t status
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

uint16_t sync_handle
sync handle

struct ble_phy_update_cmpl_param
#include <esp_gap_ble_api.h> ESP_GAP_BLE_PHY_UPDATE_COMPLETE_EVT.

Public Members

esp_bt_status_t status
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.

Espressif Systems 158 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_bt_status_t status
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

esp_bt_status_t status
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

esp_bt_status_t status
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

esp_bt_status_t status
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

esp_bt_status_t status
Indicate the set scan param operation success status

Espressif Systems 159 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

esp_bt_status_t status
Indicate the set scan response data operation success status

Espressif Systems 160 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

esp_bt_status_t status
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

esp_bt_status_t status
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

esp_bt_status_t status
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

esp_bt_status_t status
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

esp_bt_status_t status
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.

Espressif Systems 161 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_bt_status_t status
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

esp_bt_status_t status
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

esp_bt_status_t status
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

esp_bt_status_t status
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.

Espressif Systems 162 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_bt_status_t status
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.

Espressif Systems 163 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
esp_ble_addr_type_t own_addr_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

Espressif Systems 164 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

uint16_t interval
connection interval
uint16_t latency
Slave latency for the connection in number of connection events. Range: 0x0000 to 0x01F3
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
Slave latency for the connection in number of connection events. Range: 0x0000 to 0x01F3
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_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

Espressif Systems 165 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
The security level of the security link
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
The security level of the security link
esp_bt_octet16_t csrk
The csrk key value

Espressif Systems 166 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

struct esp_ble_sec_key_notif_t
Structure associated with ESP_KEY_NOTIF_EVT.

Public Members

esp_bd_addr_t bd_addr
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

esp_bd_addr_t bd_addr
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

esp_bd_addr_t bd_addr
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

esp_bd_addr_t bd_addr
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

Espressif Systems 167 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

esp_bd_addr_t bd_addr
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
esp_ble_addr_type_t addr_type
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

Espressif Systems 168 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

esp_ble_addr_type_t own_addr_type
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
uint16_t scan_interval
ext scan interval
uint16_t scan_window
ext scan window
struct esp_ble_ext_scan_params_t
ext scan parameters

Public Members

esp_ble_addr_type_t own_addr_type
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

Espressif Systems 169 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

struct esp_ble_gap_conn_params_t
create extend connection parameters

Public Members

uint16_t scan_interval
init scan interval
uint16_t scan_window
init scan window
uint16_t interval_min
minimum interval
uint16_t interval_max
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

uint16_t interval_min
periodic advertising minimum interval
uint16_t interval_max
periodic advertising maximum interval
uint8_t properties
periodic advertising properties
struct esp_ble_gap_periodic_adv_sync_params_t
periodic adv sync parameters

Espressif Systems 170 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_ble_gap_sync_t filter_policy
periodic advertising sync filter policy
uint8_t sid
periodic advertising sid
esp_ble_addr_type_t addr_type
periodic advertising address type
esp_bd_addr_t addr
periodic advertising address
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
periodic advertising 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

Espressif Systems 171 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

struct esp_ble_gap_periodic_adv_report_t
periodic adv report parameters

Public Members

uint16_t sync_handle
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
uint16_t sync_handle
periodic advertising train handle
uint8_t sid
periodic advertising sid
esp_ble_addr_type_t addr_type
periodic advertising address type
esp_bd_addr_t adv_addr
periodic advertising address
esp_ble_gap_phy_t adv_phy
periodic advertising adv phy type
uint16_t period_adv_interval
periodic advertising 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

Espressif Systems 172 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 173 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 174 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 175 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 176 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 177 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 178 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_32SRV_PART = 0x04
ESP_BLE_AD_TYPE_32SRV_CMPL = 0x05
ESP_BLE_AD_TYPE_128SRV_PART = 0x06
ESP_BLE_AD_TYPE_128SRV_CMPL = 0x07
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

Espressif Systems 179 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 180 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 181 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 182 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Overview Instructions

Application Example Instructions

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.

Espressif Systems 183 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 184 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 185 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
Slave latency for the connection in number of connection events. Range: 0x0000 to 0x01F3
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_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_DB_SECONDARY_SERVICE

Espressif Systems 186 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
uint16_t start_handle
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

Espressif Systems 187 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 188 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 189 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 190 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 191 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 192 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
ESP_GATT_DB_SECONDARY_SERVICE
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

Espressif Systems 193 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Overview Instructions

Application Example Check bluetooth/bluedroid/ble folder in ESP-IDF examples, which contains the following
demos and their tutorials:
• 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
• ESP_OK : success
• other : failed
esp_err_t esp_ble_gatts_app_register(uint16_t app_id)
This function is called to register application identifier.
Return
• ESP_OK : success
• other : failed
esp_err_t esp_ble_gatts_app_unregister(esp_gatt_if_t gatts_if)
unregister with GATT Server.
Return
• ESP_OK : success
• 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

Espressif Systems 194 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• ESP_OK : success
• other : failed
Parameters
• [in] gatts_if: GATT server access interface
• [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
• ESP_OK : success
• other : failed
Parameters
• [in] gatts_attr_db: the pointer to the service attr tab
• [in] gatts_if: GATT server access interface
• [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
• ESP_OK : success
• 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
• ESP_OK : success
• 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
• ESP_OK : success
• other : failed

Espressif Systems 195 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• ESP_OK : success
• 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
• ESP_OK : success
• 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
• ESP_OK : success
• 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
• ESP_OK : success
• other : failed
Parameters
• [in] gatts_if: GATT server access interface
• [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
• ESP_OK : success
• other : failed
Parameters
• [in] gatts_if: GATT server access interface
• [in] conn_id: - connection identifier.

Espressif Systems 196 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• [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
• ESP_OK : success
• 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
• ESP_OK : success
• other : failed
Parameters
• [in] gatts_if: GATT server access interface
• [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
• ESP_OK : success
• other : failed
Parameters
• [in] gatts_if: GATT server access interface
• [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
• ESP_OK : success
• other : failed
Parameters
• [in] gatts_if: GATT server access interface
• [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

Espressif Systems 197 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 198 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

esp_gatt_status_t status
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

esp_gatt_status_t status
Operation status
uint16_t attr_handle
Characteristic attribute handle
uint16_t service_handle
Service 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.

Espressif Systems 199 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_gatt_status_t status
Operation status
uint16_t attr_handle
Included service attribute handle
uint16_t service_handle
Service attribute handle

struct gatts_cancel_open_evt_param
#include <esp_gatts_api.h> ESP_GATTS_CANCEL_OPEN_EVT.

Public Members

esp_gatt_status_t status
Operation status

struct gatts_close_evt_param
#include <esp_gatts_api.h> ESP_GATTS_CLOSE_EVT.

Public Members

esp_gatt_status_t status
Operation status
uint16_t conn_id
Connection id

struct gatts_conf_evt_param
#include <esp_gatts_api.h> ESP_GATTS_CONF_EVT.

Public Members

esp_gatt_status_t status
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

Espressif Systems 200 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

esp_gatt_status_t status
Operation status
uint16_t service_handle
Service attribute handle
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

esp_gatt_status_t status
Operation status
uint16_t service_handle
Service attribute handle

struct gatts_disconnect_evt_param
#include <esp_gatts_api.h> ESP_GATTS_DISCONNECT_EVT.

Public Members

uint16_t conn_id
Connection id
esp_bd_addr_t remote_bda
Remote bluetooth device address
esp_gatt_conn_reason_t reason
Indicate the reason of disconnection

Espressif Systems 201 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

esp_gatt_status_t status
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

Espressif Systems 202 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

struct gatts_reg_evt_param
#include <esp_gatts_api.h> ESP_GATTS_REG_EVT.

Public Members

esp_gatt_status_t status
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

esp_gatt_status_t status
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

esp_gatt_status_t status
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
uint16_t attr_handle
The attribute handle
esp_gatt_status_t status
Operation status

struct gatts_start_evt_param
#include <esp_gatts_api.h> ESP_GATTS_START_EVT.

Public Members

esp_gatt_status_t status
Operation status
uint16_t service_handle
Service attribute handle

struct gatts_stop_evt_param
#include <esp_gatts_api.h> ESP_GATTS_STOP_EVT.

Espressif Systems 203 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_gatt_status_t status
Operation status
uint16_t service_handle
Service attribute handle

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
The attribute 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
• event: : Event type
• gatts_if: : GATT server access interface, normally different gatts_if correspond to different
profile
• param: : Point to callback parameter, currently is union type

Enumerations

Espressif Systems 204 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 205 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Overview Instructions

Application Example Check bluetooth/bluedroid/ble folder in ESP-IDF examples, which contains the following
demos and their tutorials:
• 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

Espressif Systems 206 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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] gattc_if: Gatt client access interface.
• [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] gattc_if: Gatt client access interface.
• [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] gattc_if: Gatt client access interface.
• [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] gattc_if: Gatt client access interface.
• [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.

Espressif Systems 207 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Return
• ESP_OK: success
• other: failed
Parameters
• [in] gattc_if: Gatt client access interface.
• [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] gattc_if: Gatt client access interface.
• [in] conn_id: connection ID which identify the server.
• [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
cache, won t get from remote devices.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] gattc_if: Gatt client access interface.
• [in] conn_id: connection ID which identify the server.
• [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

Espressif Systems 208 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• [in] gattc_if: Gatt client access interface.

• [in] conn_id: connection ID which identify the server.
• [in] start_handle: the attribute start handle
• [in] end_handle: the attribute end 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
cache, won t get from remote devices.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] gattc_if: Gatt client access interface.
• [in] conn_id: connection ID which identify the server.
• [in] start_handle: the attribute start handle
• [in] end_handle: the attribute end handle
• [in] char_uuid: the characteristic uuid.
• [in] descr_uuid: the descriptor uuid.
• [out] result: The pointer to the descriptor in the given 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.
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
cache, won t get from remote devices.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] gattc_if: Gatt client access interface.
• [in] conn_id: connection ID which identify the server.
• [in] char_handle: the characteristic handle.
• [in] descr_uuid: the descriptor uuid.
• [out] result: The pointer to the descriptor in the given 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.
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

Espressif Systems 209 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• other: failed
Parameters
• [in] gattc_if: Gatt client access interface.
• [in] conn_id: connection ID which identify the server.
• [in] start_handle: the attribute start handle
• [in] end_handle: the attribute end handle
• [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] gattc_if: Gatt client access interface.
• [in] conn_id: connection ID which identify the server.
• [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] gattc_if: Gatt client access interface.
• [in] start_handle: the attribute start handle
• [in] end_handle: the attribute end handle
• [in] conn_id: connection ID which identify the server.
• [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] gattc_if: Gatt client access interface.
• [in] conn_id: : connection ID.

Espressif Systems 210 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• [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,
esp_gatt_auth_req_t auth_req)
This function is called to read a service s characteristics of the given characteristic UUID.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] gattc_if: Gatt client access interface.
• [in] conn_id: : connection ID.
• [in] start_handle: : the attribute start handle.
• [in] end_handle: : the attribute end handle
• [in] uuid: : The UUID of attribute which will be read.
• [in] auth_req: : authenticate request type
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] gattc_if: Gatt client access interface.
• [in] conn_id: : connection ID.
• [in] read_multi: : pointer to the read multiple parameter.
• [in] auth_req: : authenticate request type
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] gattc_if: Gatt client access interface.
• [in] conn_id: : connection ID.
• [in] handle: : descriptor handle to read.
• [in] auth_req: : authenticate request type
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] gattc_if: Gatt client access interface.
• [in] conn_id: : connection ID.
• [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.

Espressif Systems 211 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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,
esp_gatt_auth_req_t auth_req)
This function is called to write characteristic descriptor value.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] gattc_if: Gatt client access interface.
• [in] conn_id: : connection ID
• [in] handle: : descriptor hadle 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_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,
esp_gatt_auth_req_t auth_req)
This function is called to prepare write a characteristic value.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] gattc_if: Gatt client access interface.
• [in] conn_id: : connection ID.
• [in] handle: : characteristic handle to prepare write.
• [in] offset: : offset of the write value.
• [in] value_len: length of the value to be written.
• [in] value: : the value to be written.
• [in] auth_req: : authentication request.
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,
esp_gatt_auth_req_t auth_req)
This function is called to prepare write a characteristic descriptor value.
Return
• ESP_OK: success
• other: failed
Parameters
• [in] gattc_if: Gatt client access interface.
• [in] conn_id: : connection ID.
• [in] handle: : characteristic descriptor handle to prepare write.
• [in] offset: : offset of the write value.
• [in] value_len: length of the value to be written.
• [in] value: : the value to be written.
• [in] auth_req: : authentication request.
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] gattc_if: Gatt client access interface.
• [in] conn_id: : connection ID.

Espressif Systems 212 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• [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] gattc_if: Gatt client access interface.
• [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] gattc_if: Gatt client access interface.
• [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] gattc_if: Gatt client access interface.
• [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

Espressif Systems 213 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Parameters
• [in] gattc_if: Gatt client access interface.
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

Espressif Systems 214 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

esp_gatt_status_t status
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

esp_gatt_status_t status
Operation status
uint16_t conn_id
Connection id
esp_bd_addr_t remote_bda
Remote bluetooth device address
esp_gatt_conn_reason_t reason
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.

Espressif Systems 215 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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 gattc_dis_srvc_cmpl_evt_param
#include <esp_gattc_api.h> ESP_GATTC_DIS_SRVC_CMPL_EVT.

Public Members

esp_gatt_status_t status
Operation status
uint16_t conn_id
Connection id

struct gattc_disconnect_evt_param
#include <esp_gattc_api.h> ESP_GATTC_DISCONNECT_EVT.

Public Members

esp_gatt_conn_reason_t reason
disconnection reason
uint16_t conn_id
Connection id
esp_bd_addr_t remote_bda
Remote bluetooth device address

struct gattc_exec_cmpl_evt_param
#include <esp_gattc_api.h> ESP_GATTC_EXEC_EVT.

Public Members

esp_gatt_status_t status
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

esp_gatt_status_t status
Operation status
uint8_t num_addr
The number of address in the gattc cache address list

Espressif Systems 216 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
esp_bd_addr_t remote_bda
Remote bluetooth device address
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

esp_gatt_status_t status
Operation status
uint16_t conn_id
Connection id
esp_bd_addr_t remote_bda
Remote bluetooth device address
uint16_t mtu
MTU size

struct gattc_queue_full_evt_param
#include <esp_gattc_api.h> ESP_GATTC_QUEUE_FULL_EVT.

Public Members

esp_gatt_status_t status
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.

Espressif Systems 217 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_gatt_status_t status
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

esp_gatt_status_t status
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

esp_gatt_status_t status
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

esp_gatt_status_t status
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.

Espressif Systems 218 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

uint16_t conn_id
Connection id
uint16_t start_handle
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

esp_gatt_status_t status
Operation status

struct gattc_srvc_chg_evt_param
#include <esp_gattc_api.h> ESP_GATTC_SRVC_CHG_EVT.

Public Members

esp_bd_addr_t remote_bda
Remote bluetooth device address

struct gattc_unreg_for_notify_evt_param
#include <esp_gattc_api.h> ESP_GATTC_UNREG_FOR_NOTIFY_EVT.

Public Members

esp_gatt_status_t status
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

esp_gatt_status_t status
Operation status
uint16_t conn_id
Connection id
uint16_t handle
The Characteristic or descriptor handle

Espressif Systems 219 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• event: : Event type
• gattc_if: : GATT client access interface, normally different gattc_if correspond to different
profile
• param: : Point to callback parameter, currently is union type

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

Espressif Systems 220 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 221 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
Return ESP_OK - success, other - failed
Parameters
• [in] callbacks: callback functions
esp_err_t esp_blufi_profile_init(void)
This function is called to initialize blufi_profile.
Return ESP_OK - success, other - failed
esp_err_t esp_blufi_profile_deinit(void)
This function is called to de-initialize blufi_profile.
Return ESP_OK - success, other - failed
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.
Return ESP_OK - success, other - failed
Parameters
• opmode: : wifi opmode
• sta_conn_state: : station is already in connection or not

Espressif Systems 222 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• 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.
Return ESP_OK - success, other - failed
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.
Return ESP_OK - success, other - failed
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.
Return ESP_OK - success, other - failed
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

Espressif Systems 223 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

esp_bd_addr_t remote_bda
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.

Espressif Systems 224 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_bd_addr_t remote_bda
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.

Espressif Systems 225 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 226 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 227 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 228 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• event: : Event type
• param: : Point to callback parameter, currently is union type
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.

Espressif Systems 229 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• iv8: : initial vector(8bit), normally, blufi core will input packet sequence number
• 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
• iv8: : initial vector(8bit), normally, blufi core will input packet sequence number
• 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

Espressif Systems 230 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Overview Instructions

Application Example Instructions

Espressif Systems 231 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• [in] cod: Class of Device
static uint32_t esp_bt_gap_get_cod_minor_dev(uint32_t cod)
get minor service field of COD
Return minor service bits
Parameters
• [in] cod: Class of Device
static uint32_t esp_bt_gap_get_cod_format_type(uint32_t cod)
get format type of COD
Return format type
Parameters
• [in] cod: Class of Device
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
• [in] cod: Class of Device
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_OK : Succeed
• 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_OK : Succeed
• ESP_ERR_INVALID_ARG: if argument invalid
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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

Espressif Systems 232 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_OK : Succeed
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_ERR_INVALID_ARG: if invalid parameters are provided
• ESP_FAIL: others
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_OK : Succeed
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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_OK : Succeed
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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_bluedroid_enable() completes successfully.
esp_bt_gap_cb_t will be called with ESP_BT_GAP_RMT_SRVC_REC_EVT after service discovery ends
Return
• ESP_OK : Succeed
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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

Espressif Systems 233 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_OK : Succeed
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_ERR_INVALID_ARG: if param is invalid
• ESP_FAIL: others
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_OK : Succeed
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_ERR_INVALID_ARG: if param is invalid
• ESP_FAIL: others
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
• ESP_OK : Succeed
• ESP_FAIL: others
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
• ESP_OK : Succeed
• ESP_FAIL: others
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.
Return - ESP_OK : success
• ESP_FAIL : failed
Parameters
• [in] bd_addr: : BD address of the peer device
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_FAIL : failed
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.

Espressif Systems 234 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Return
• ESP_OK : Succeed
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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.
Return - ESP_OK : success
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• 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.
Return - ESP_OK : success
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• 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.
Return - ESP_OK : success
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• 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.
Return - ESP_OK : success
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• other : failed
Parameters
• [in] bd_addr: : BD address of the peer
• [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)

Espressif Systems 235 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Reply the confirm value to the peer device in the legacy connection stage.
Return - ESP_OK : success
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• 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_bt_gap_set_afh_channels(esp_bt_gap_afh_channels channels)
Set the AFH channels.
Return - ESP_OK : success
• 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 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.
Return - ESP_OK : success
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• 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.
Return - ESP_OK : success
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• 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

Espressif Systems 236 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
esp_bt_status_t stat
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
remote bluetooth device address
esp_bt_status_t status
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
remote bluetooth device address

Espressif Systems 237 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

esp_bt_status_t stat
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
remote bluetooth device address
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
remote bluetooth device address
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.

Espressif Systems 238 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_bd_addr_t bda
remote bluetooth device address

struct mode_chg_param
#include <esp_gap_bt_api.h> ESP_BT_GAP_MODE_CHG_EVT.

Public Members

esp_bd_addr_t bda
remote bluetooth device address
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
remote bluetooth device address
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

esp_bt_status_t stat
QoS status
esp_bd_addr_t bda
remote bluetooth device address
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

esp_bt_status_t stat
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 *.

Espressif Systems 239 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_bd_addr_t bda
remote bluetooth device address
esp_bt_status_t stat
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
remote bluetooth device address
esp_bt_status_t stat
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
remote bluetooth device address
esp_bt_status_t stat
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

esp_bt_status_t stat
set AFH channel status

Structures
struct esp_bt_cod_t
Class of device.

Public Members

uint32_t reserved_2 : 2
undefined

Espressif Systems 240 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 241 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_INCMPL_32BITS_UUID
Incomplete list of 32-bit service UUIDs
ESP_BT_EIR_TYPE_CMPL_32BITS_UUID
Complete list of 32-bit service UUIDs
ESP_BT_EIR_TYPE_INCMPL_128BITS_UUID
Incomplete list of 128-bit service UUIDs
ESP_BT_EIR_TYPE_CMPL_128BITS_UUID
Complete list of 128-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

Espressif Systems 242 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• event: : Event type
• param: : Pointer to callback parameter

Espressif Systems 243 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 244 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 245 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 246 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Overview Instructions

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
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: if callback is a NULL function pointer
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

Espressif Systems 247 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• ESP_INVALID_STATE: if bluetooth stack is not yet enabled

• ESP_FAIL: others
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_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_bda: remote bluetooth device address
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
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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

Espressif Systems 248 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• ESP_OK: success
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: if callback is a NULL function pointer
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
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_bda: remote bluetooth device address
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
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_bda: remote bluetooth device address

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.

Espressif Systems 249 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_bd_addr_t remote_bda
remote bluetooth device address
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
esp_bd_addr_t remote_bda
remote bluetooth device address

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_bd_addr_t remote_bda
remote bluetooth device address
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

Espressif Systems 250 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• event: : Event type
• param: : Pointer to callback parameter
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.

Espressif Systems 251 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 252 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Application Example 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

Espressif Systems 253 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• ESP_OK: success
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
esp_err_t esp_avrc_ct_deinit(void)
De-initialize AVRCP controller module. This function should be called after after esp_bluedroid_enable()
completes 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_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] tl: : transaction label, 0 to 15, consecutive commands should use different values
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
ESP_AVRC_CT_CONNECTION_STATE_EVT is received and AVRCP connection is established.
Return
• ESP_OK: success
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_ERR_NOT_SUPPORTED: if the event_id is not supported in current implementation
• ESP_FAIL: others
Parameters
• [in] tl: : transaction label, 0 to 15, consecutive commands should use different values.

Espressif Systems 254 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• [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
ESP_AVRC_CT_CONNECTION_STATE_EVT is received and AVRCP connection is established.
Return
• ESP_OK: success
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_ERR_NOT_SUPPORTED: if the event_id is not supported in current implementation
• ESP_FAIL: others
Parameters
• [in] tl: : transaction label, 0 to 15, consecutive commands should use different values
• [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
ESP_AVRC_CT_CONNECTION_STATE_EVT is received and AVRCP connection is established.
Return
• ESP_OK: success
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] tl: : transaction label, 0 to 15, consecutive commands should use different values.
• [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
ESP_AVRC_CT_CONNECTION_STATE_EVT is received and AVRCP connection is established.
Return
• ESP_OK: success
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] tl: : transaction label, 0 to 15, consecutive commands should use different values.
• [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
esp_bluedroid_enable() completes successfully.
Return
• ESP_OK: success
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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()
completes successfully. Note: AVRC cannot work independently, AVRC should be used along with A2DP
and AVRC should be initialized before A2DP.

Espressif Systems 255 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Return
• ESP_OK: success
• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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

Espressif Systems 256 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_STATE: if bluetooth stack is not enabled or AVRC TG is not initialized
• 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_STATE: if bluetooth stack is not enabled or AVRC TG is not initialized
• 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.

Espressif Systems 257 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 258 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

esp_bd_addr_t remote_bda
remote bluetooth device address

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
esp_bd_addr_t remote_bda
remote bluetooth device address

struct avrc_ct_set_volume_rsp_param
#include <esp_avrc_api.h> ESP_AVRC_CT_SET_ABSOLUTE_VOLUME_RSP_EVT.

Espressif Systems 259 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
esp_bd_addr_t remote_bda
remote bluetooth device address

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

Espressif Systems 260 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
esp_bd_addr_t remote_bda
remote bluetooth device address

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.

Espressif Systems 261 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• event: : Event type
• 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
• event: : Event type
• 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
ESP_AVRC_FEAT_FLAG_CAT2 = 0x0002
category 2

Espressif Systems 262 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

ESP_AVRC_FEAT_FLAG_CAT3 = 0x0004
category 3
ESP_AVRC_FEAT_FLAG_CAT4 = 0x0008
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
ESP_AVRC_PT_CMD_1 = 0x21
1

Espressif Systems 263 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

ESP_AVRC_PT_CMD_2 = 0x22
2
ESP_AVRC_PT_CMD_3 = 0x23
3
ESP_AVRC_PT_CMD_4 = 0x24
4
ESP_AVRC_PT_CMD_5 = 0x25
5
ESP_AVRC_PT_CMD_6 = 0x26
6
ESP_AVRC_PT_CMD_7 = 0x27
7
ESP_AVRC_PT_CMD_8 = 0x28
8
ESP_AVRC_PT_CMD_9 = 0x29
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

Espressif Systems 264 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
ESP_AVRC_PT_CMD_F2 = 0x72
F2
ESP_AVRC_PT_CMD_F3 = 0x73
F3
ESP_AVRC_PT_CMD_F4 = 0x74
F4
ESP_AVRC_PT_CMD_F5 = 0x75
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:

Espressif Systems 265 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
connection state changed event
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
connection state changed event
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

Espressif Systems 266 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 267 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 268 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 269 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Overview Instructions

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

Espressif Systems 270 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• [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

Espressif Systems 271 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• [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

Espressif Systems 272 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

esp_spp_status_t status
status
uint32_t port_status
PORT status
uint32_t handle
The connection handle

Espressif Systems 273 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

bool async
FALSE, if local initiates disconnect

struct spp_cong_evt_param
#include <esp_spp_api.h> ESP_SPP_CONG_EVT.

Public Members

esp_spp_status_t status
status
uint32_t handle
The connection 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

esp_spp_status_t status
status
uint32_t handle
The connection 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

esp_spp_status_t status
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

esp_spp_status_t status
status

struct spp_open_evt_param
#include <esp_spp_api.h> ESP_SPP_OPEN_EVT.

Espressif Systems 274 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_spp_status_t status
status
uint32_t handle
The connection 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

esp_spp_status_t status
status
uint32_t handle
The connection 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

esp_spp_status_t status
status
uint8_t scn
Server channel number

struct spp_start_evt_param
#include <esp_spp_api.h> ESP_SPP_START_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
uint8_t scn
Server channel number

Espressif Systems 275 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

bool use_co
TRUE to use co_rfc_data

struct spp_uninit_evt_param
#include <esp_spp_api.h> SPP_UNINIT_EVT.

Public Members

esp_spp_status_t status
status

struct spp_write_evt_param
#include <esp_spp_api.h> ESP_SPP_WRITE_EVT.

Public Members

esp_spp_status_t status
status
uint32_t handle
The connection 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

Espressif Systems 276 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 277 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Overview Instructions

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

Espressif Systems 278 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 279 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 280 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 281 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 282 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 283 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 284 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Overview Instructions

API Reference

Header File
• components/bt/host/bluedroid/api/include/api/esp_hf_client_api.h

Espressif Systems 285 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
esp_bluedroid_enable() completes successfully.
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: 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_OK: if the initialization request is sent successfully
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_bda: remote bluetooth device address
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
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_bda: remote bluetooth device address
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
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_bda: remote bluetooth device address
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

Espressif Systems 286 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Level Connection shall exist with AG.

Return
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_bda: remote bluetooth device address
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_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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.

Espressif Systems 287 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Return
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others

Espressif Systems 288 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: if callback is a NULL function pointer
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.

Espressif Systems 289 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
HF callback param of ESP_HF_CLIENT_BVRA_EVT
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
HF callback param of ESP_HF_CLIENT_BVRA_EVT
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

Espressif Systems 290 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
esp_bd_addr_t remote_bda
remote bluetooth device address

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.

Espressif Systems 291 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 292 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
esp_bd_addr_t remote_bda
remote bluetooth device address

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.

Espressif Systems 293 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 294 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
• [in] len: : size(in bytes) in buf
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
• [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.
• [in] len: : size(in bytes) in buf
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
• event: : Event type
• param: : Pointer to callback parameter

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

Espressif Systems 295 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
connection state changed event
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

Espressif Systems 296 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
esp_bluedroid_enable() completes successfully.
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: 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
• ESP_OK: if the initialization request is sent successfully
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_addr: remote bluetooth device address
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
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others

Espressif Systems 297 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_bda: remote bluetooth device address
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
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_bda: remote bluetooth device address
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
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_bda: remote bluetooth device address
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
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
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
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_bda: remote bluetooth device address
• [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

Espressif Systems 298 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

shall exist with HFP client.

Return
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_addr: remote bluetooth device address
• [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
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_bda: remote bluetooth device address
• [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
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_addr: remote bluetooth device address
• [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
Connection shall exist with HFP client.
Return
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_addr: remote bluetooth device address
• [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
• [in] roam: roam state

Espressif Systems 299 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• [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
shall exist with HFP client.
Return
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_addr: remote bluetooth device address
• [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-
nection shall exist with HFP client.
Return
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_addr: remote bluetooth device address
• [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-
nection shall exist with HFP client.
Return
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_addr: remote bluetooth device address
• [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
Connection shall exist with HFP client.
Return
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_addr: remote bluetooth device address

Espressif Systems 300 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• [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
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_addr: remote bluetooth device address
• [in] num_active: the number of active call
• [in] num_held: the number of held call
• [in] call_state: call state
• [in] call_setup_state: call setup state
• [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,
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)
Reject Incoming Call from AG. As a precondition to use this API, Service Level Connection shall exist with
HFP client.
Return
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_addr: remote bluetooth device address
• [in] num_active: the number of active call
• [in] num_held: the number of held call
• [in] call_state: call state
• [in] call_setup_state: call setup state
• [in] number: number of the incoming call
• [in] call_addr_type: call address type
esp_err_t esp_bt_hf_out_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)
Initiate a call from AG. As a precondition to use this API, Service Level Connection shall exist with HFP client.
Return
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_addr: remote bluetooth device address
• [in] num_active: the number of active call
• [in] num_held: the number of held call
• [in] call_state: call state
• [in] call_setup_state: call setup state
• [in] number: number of the outgoing call
• [in] call_addr_type: call address type

Espressif Systems 301 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

esp_err_t esp_bt_hf_end_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)
End an ongoing call. As a precondition to use this API, Service Level Connection shall exist with HFP client.
Return
• ESP_OK: disconnect request is sent to lower layer
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: others
Parameters
• [in] remote_addr: remote bluetooth device address
• [in] num_active: the number of active call
• [in] num_held: the number of held call
• [in] call_state: call state
• [in] call_setup_state: call setup state
• [in] number: number of the call
• [in] call_addr_type: call address type
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
• ESP_INVALID_STATE: if bluetooth stack is not yet enabled
• ESP_FAIL: if callback is a NULL function pointer
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

Espressif Systems 302 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_bd_addr_t remote_addr
Remote bluetooth device address
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
bluetooth proprietary call hold status indicator
int signal_strength
bluetooth proprietary call hold status indicator
esp_hf_roaming_status_t roam
bluetooth proprietary call hold status indicator
int battery_level
battery charge value, ranges from 0 to 5
esp_hf_call_held_status_t call_held_status
bluetooth proprietary call hold status indicator

struct hf_conn_stat_param
#include <esp_hf_ag_api.h> ESP_HS_CONNECTION_STATE_EVT.

Espressif Systems 303 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_bd_addr_t remote_bda
Remote bluetooth device address
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

esp_bd_addr_t remote_addr
remote bluetooth device address
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.

Espressif Systems 304 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_bd_addr_t remote_addr
Remote bluetooth device address
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

Espressif Systems 305 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• [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.
• [in] len: : size(in bytes) in buf
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
• [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.
• [in] len: : size(in bytes) in buf
typedef void (*esp_hf_cb_t)(esp_hf_cb_event_t event, esp_hf_cb_param_t *param)
HF AG callback function type.
Parameters
• event: : Event type
• param: : Pointer to callback parameter

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

Espressif Systems 306 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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:

Espressif Systems 307 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• 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.

Espressif Systems 308 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 309 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 310 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 311 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 312 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 313 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 314 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 315 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 316 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_ble_mesh_prov_bearer_t bearer
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

Espressif Systems 317 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
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_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.

Espressif Systems 318 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

int err_code
Indicate the result of binding AppKey with model by the node
uint16_t element_addr
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.

Espressif Systems 319 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 320 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
uint16_t element_addr
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.

Espressif Systems 321 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_ble_mesh_prov_bearer_t bearer
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

esp_ble_mesh_prov_bearer_t bearer
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
uint16_t unicast_addr
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.

Espressif Systems 322 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
Index of the provisioning link
char string[8]
String output by the Provisioner
uint32_t number
Number output by the Provisioner

Espressif Systems 323 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
Index of the provisioning link

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
esp_ble_mesh_prov_bearer_t bearer
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.

Espressif Systems 324 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 325 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
esp_ble_mesh_bd_addr_t addr
Device address of the Proxy Server
esp_ble_mesh_addr_type_t addr_type
Device address type
uint16_t net_idx
Corresponding NetKey Index

struct ble_mesh_proxy_client_connected_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROXY_CLIENT_CONNECTED_EVT.

Public Members

esp_ble_mesh_bd_addr_t addr
Device address of the Proxy Server
esp_ble_mesh_addr_type_t addr_type
Device address type
uint8_t conn_handle
Proxy connection handle
uint16_t net_idx
Corresponding NetKey Index

struct ble_mesh_proxy_client_disconnect_comp_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROXY_CLIENT_DISCONNECT_COMP_EVT.

Espressif Systems 326 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

int err_code
Indicate the result of Proxy Client disconnect
uint8_t conn_handle
Proxy connection handle

struct ble_mesh_proxy_client_disconnected_param
#include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROXY_CLIENT_DISCONNECTED_EVT.

Public Members

esp_ble_mesh_bd_addr_t addr
Device address of the Proxy Server
esp_ble_mesh_addr_type_t addr_type
Device address type
uint8_t conn_handle
Proxy connection handle
uint16_t net_idx
Corresponding NetKey Index
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

esp_ble_mesh_bd_addr_t addr
Device address
esp_ble_mesh_addr_type_t addr_type
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
Proxy connection handle
uint16_t server_addr
Proxy Server primary element address
uint16_t net_idx
Corresponding NetKey Index

Espressif Systems 327 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
Proxy connection handle
uint16_t net_idx
Corresponding NetKey Index

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
Proxy connection handle
uint16_t net_idx
Corresponding NetKey Index

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

Espressif Systems 328 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 329 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 330 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
esp_ble_mesh_model_t *model
Pointer to the model which receives the message
esp_ble_mesh_msg_ctx_t *ctx
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.

Espressif Systems 331 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

uint32_t opcode
Opcode of the received message
esp_ble_mesh_model_t *model
Pointer to the model which receives the message
esp_ble_mesh_msg_ctx_t *ctx
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
esp_ble_mesh_model_t *model
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

esp_ble_mesh_model_t *model
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
esp_ble_mesh_model_t *model
Pointer to the model which sends the message
esp_ble_mesh_msg_ctx_t *ctx
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.

Espressif Systems 332 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

int err_code
Indicate the result of updating server model state
esp_ble_mesh_model_t *model
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

uint16_t element_addr
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

esp_ble_mesh_model_t *model
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.

Espressif Systems 333 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 334 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 335 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
esp_ble_mesh_model_t *model
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

esp_ble_mesh_bd_addr_t addr
Device address
esp_ble_mesh_addr_type_t addr_type
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

Espressif Systems 336 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

esp_ble_mesh_prov_bearer_t bearer
Provisioning Bearer
struct esp_ble_mesh_device_delete_t
Information of the device which is going to be deleted.

Public Members

esp_ble_mesh_bd_addr_t addr
Device address
esp_ble_mesh_addr_type_t addr_type
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

esp_ble_mesh_bd_addr_t addr
Node device address
esp_ble_mesh_addr_type_t addr_type
Node device address type
uint8_t dev_uuid[16]
Device UUID
uint16_t oob_info
Node OOB information
uint16_t unicast_addr
Node unicast address
uint8_t element_num
Node element number
uint16_t net_idx
Node NetKey Index

Espressif Systems 337 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 338 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

esp_ble_mesh_model_t *model
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
esp_ble_mesh_model_t *model
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.

Espressif Systems 339 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
struct k_delayed_work timer
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;

Espressif Systems 340 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 341 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 342 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 343 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 344 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 345 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 346 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 347 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 348 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 349 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 350 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 351 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 352 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 353 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 354 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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 uint16_t UINT16
typedef uint32_t UINT32
typedef uint64_t UINT64
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.

Espressif Systems 355 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 356 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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)

Espressif Systems 357 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 358 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 359 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 360 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 361 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 362 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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().
Return ESP_OK on success or error code otherwise.
Parameters
• [in] param: Pointer to the structure of BLE Mesh deinit parameters.

Reading of Local Data Information

Espressif Systems 363 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 364 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
Parameters
• [in] app_key: AppKey to be added.
• [in] net_idx: NetKey Index.

Espressif Systems 365 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• [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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
esp_err_t esp_ble_mesh_lpn_disable(bool force)
Disable BLE Mesh device LPN functionality.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.

Send/Publish Messages, add Local AppKey, etc.

Header File
• components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_networking_api.h

Functions

Espressif Systems 366 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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).
Return ESP_OK on success or error code otherwise.
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.

Espressif Systems 367 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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).
Return ESP_OK on success or error code otherwise.
Parameters
• [in] model: BLE Mesh Client 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 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.
Return ESP_OK on success or error code otherwise.
Parameters
• [in] model: Mesh (client) Model publishing the message.
• [in] opcode: Message opcode.
• [in] length: Message length (exclude the message opcode).
• [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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
Parameters

Espressif Systems 368 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• [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.
Return ESP_OK on success or error code otherwise.
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.
Return Pointer of the node info struct or NULL on failure.
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.
Return Pointer of the node info struct or NULL on failure.
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 <

Espressif Systems 369 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
Parameters
• [in] element_addr: Provisioner local element address

Espressif Systems 370 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• [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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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
• [in] net_idx: Network key index.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.

Espressif Systems 371 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• 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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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)
Return ESP_OK on success or error code otherwise.
Parameters
• [in] index: Settings index.
• [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,

Espressif Systems 372 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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)
Return ESP_OK on success or error code otherwise.
Parameters
• [in] uid: Settings user id.
• [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.
Return ESP_OK on success or error code otherwise.
Parameters
• [in] index: Settings index.
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.
Return ESP_OK on success or error code otherwise.
Parameters
• [in] uid: Settings user id.
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
• [in] index: Settings index.
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
• [in] uid: Settings user id.
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] net_idx: Network key index.
• [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

Espressif Systems 373 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
Return ESP_OK on success or error code otherwise.
Parameters
• [in] callback: Pointer to the callback function.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
Parameters
• [in] string: String input by device.

Espressif Systems 374 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.

Espressif Systems 375 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Return ESP_OK on success or error code otherwise.

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.

Espressif Systems 376 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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).
Return ESP_OK on success or error code otherwise.
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

Espressif Systems 377 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
esp_err_t esp_ble_mesh_proxy_gatt_enable(void)
Enable BLE Mesh GATT Proxy Service.

Espressif Systems 378 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Return ESP_OK on success or error code otherwise.

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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
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.
Return ESP_OK on success or error code otherwise.
Parameters
• [in] conn_handle: Proxy connection handle.
• [in] net_idx: Corresponding NetKey Index.
• [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.
Return ESP_OK on success or error code otherwise.
Parameters
• [in] conn_handle: Proxy connection handle.
• [in] net_idx: Corresponding NetKey Index.
• [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.
Return ESP_OK on success or error code otherwise.
Parameters
• [in] conn_handle: Proxy connection handle.
• [in] net_idx: Corresponding NetKey Index.
• [in] addr: Pointer to the filter address.
• [in] addr_num: Number of the filter address.

Espressif Systems 379 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
Return ESP_OK on success or error code otherwise.
Parameters
• [in] callback: Pointer to the callback function.
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.
Return ESP_OK on success or error code otherwise.
Parameters
• [in] callback: Pointer to the callback function.
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
Return ESP_OK on success or error code otherwise.
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.
Note If you want to find the opcodes and corresponding meanings accepted by this API, please refer to
esp_ble_mesh_opcode_config_client_set_t in esp_ble_mesh_defs.h
Return ESP_OK on success or error code otherwise.
Parameters
• [in] params: Pointer to BLE Mesh common client parameters.

Espressif Systems 380 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• [in] set_state: Pointer to a union, each kind of opcode corresponds to one structure inside.
Shall not be set to NULL.

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

Espressif Systems 381 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 382 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 383 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 384 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_ble_mesh_model_t *model
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
struct k_delayed_work timer
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

Espressif Systems 385 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

uint16_t element_addr
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

uint16_t element_addr
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

uint16_t element_addr
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_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.

Espressif Systems 386 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

uint16_t net_idx
The network key index
struct esp_ble_mesh_cfg_sig_model_app_get_t
Parameters of Config SIG Model App Get.

Public Members

uint16_t element_addr
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

uint16_t element_addr
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_kr_phase_get_t
Parameters of Config Key Refresh Phase Get.

Public Members

uint16_t net_idx
The network key index
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.

Espressif Systems 387 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

uint8_t friend_state
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
The network key index
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
The network key index
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.

Espressif Systems 388 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

uint16_t element_addr
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
The company id, if not a vendor model, shall set to 0xFFFF
struct esp_ble_mesh_cfg_model_pub_set_t
Parameters of Config Model Publication Set.

Public Members

uint16_t element_addr
The element address
uint16_t publish_addr
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
The company id, if not a vendor model, shall set to 0xFFFF
struct esp_ble_mesh_cfg_model_sub_add_t
Parameters of Config Model Subscription Add.

Public Members

uint16_t element_addr
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
The company id, if not a vendor model, shall set to 0xFFFF
struct esp_ble_mesh_cfg_model_sub_delete_t
Parameters of Config Model Subscription Delete.

Espressif Systems 389 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

uint16_t element_addr
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
The company id, if not a vendor model, shall set to 0xFFFF
struct esp_ble_mesh_cfg_model_sub_overwrite_t
Parameters of Config Model Subscription Overwrite.

Public Members

uint16_t element_addr
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
The company id, if not a vendor model, shall set to 0xFFFF
struct esp_ble_mesh_cfg_model_sub_va_add_t
Parameters of Config Model Subscription Virtual Address Add.

Public Members

uint16_t element_addr
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
The company id, if not a vendor model, shall set to 0xFFFF
struct esp_ble_mesh_cfg_model_sub_va_delete_t
Parameters of Config Model Subscription Virtual Address Delete.

Public Members

uint16_t element_addr
The element address
uint8_t label_uuid[16]
The Label UUID of the virtual address to be removed from the Subscription List
uint16_t model_id
The model id

Espressif Systems 390 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

uint16_t company_id
The company id, if not a vendor model, shall set to 0xFFFF
struct esp_ble_mesh_cfg_model_sub_va_overwrite_t
Parameters of Config Model Subscription Virtual Address Overwrite.

Public Members

uint16_t element_addr
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
The company id, if not a vendor model, shall set to 0xFFFF
struct esp_ble_mesh_cfg_model_pub_va_set_t
Parameters of Config Model Publication Virtual Address Set.

Public Members

uint16_t element_addr
The element address
uint8_t label_uuid[16]
Value of the Label UUID 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
The company id, if not a vendor model, shall set to 0xFFFF
struct esp_ble_mesh_cfg_model_sub_delete_all_t
Parameters of Config Model Subscription Delete All.

Public Members

uint16_t element_addr
The element address
uint16_t model_id
The model id

Espressif Systems 391 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

uint16_t company_id
The company id, if not a vendor model, shall set to 0xFFFF
struct esp_ble_mesh_cfg_net_key_update_t
Parameters of Config NetKey Update.

Public Members

uint16_t net_idx
The network key index
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
The network key index
struct esp_ble_mesh_cfg_app_key_update_t
Parameters of Config AppKey Update.

Public Members

uint16_t net_idx
The network key index
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
The network key index
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
The network key index
uint8_t identity
New Node Identity state
struct esp_ble_mesh_cfg_model_app_unbind_t
Parameters of Config Model App Unbind.

Espressif Systems 392 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

uint16_t element_addr
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
The company id, if not a vendor model, shall set to 0xFFFF
struct esp_ble_mesh_cfg_kr_phase_set_t
Parameters of Config Key Refresh Phase Set.

Public Members

uint16_t net_idx
The network key index
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
Destination address for Heartbeat messages
uint8_t count
Number of Heartbeat messages to be sent
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
struct esp_ble_mesh_cfg_heartbeat_sub_set_t
Parameters of Config Model Heartbeat Subscription Set.

Espressif Systems 393 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

uint16_t src
Source address for Heartbeat messages
uint16_t dst
Destination address for Heartbeat messages
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)

Espressif Systems 394 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
uint16_t element_addr
Address of the element
uint16_t publish_addr
Value of the publish address
uint16_t app_idx
Index of the application key
bool cred_flag
Value of the Friendship Credential Flag
uint8_t ttl
Default TTL value for the outgoing messages
uint8_t period
Period for periodic status publishing
uint8_t transmit
Number of retransmissions and number of 50-millisecond steps between retransmissions
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
Status Code for the request message
uint16_t element_addr
Address of the element
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
Status Code for the request message

Espressif Systems 395 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
Status Code for the request message
uint16_t net_idx
Index of the NetKey
uint16_t app_idx
Index of the application key
struct esp_ble_mesh_cfg_mod_app_status_cb_t
Parameters of Config Model App Status

Public Members

uint8_t status
Status Code for the request message
uint16_t element_addr
Address of the element
uint16_t app_idx
Index of the application key
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

uint8_t friend_state
Friend state value
struct esp_ble_mesh_cfg_hb_pub_status_cb_t
Parameters of Config Heartbeat Publication Status

Public Members

uint8_t status
Status Code for the request message
uint16_t dst
Destination address for Heartbeat messages
uint8_t count
Number of Heartbeat messages remaining to be sent
uint8_t period
Period for sending Heartbeat messages

Espressif Systems 396 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

uint8_t ttl
TTL to be used when sending Heartbeat messages
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
Status Code for the request message
uint16_t src
Source address for Heartbeat messages
uint16_t dst
Destination address for Heartbeat messages
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
Maximum hops when receiving Heartbeat messages
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
Maximum hops when receiving Heartbeat messages
struct esp_ble_mesh_cfg_model_sub_list_cb_t
Parameters of Config SIG/Vendor Subscription List

Public Members

uint8_t status
Status Code for the request message
uint16_t element_addr
Address of the element
uint16_t company_id
Company ID
uint16_t model_id
Model ID

Espressif Systems 397 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
Status Code for the request message
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
Status Code for the request message
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
Status Code for the request message
uint16_t element_addr
Address of the element
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

Espressif Systems 398 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

uint8_t status
Status Code for the request message
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

uint16_t element_addr
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

Espressif Systems 399 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

uint16_t element_addr
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

uint16_t element_addr
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

Espressif Systems 400 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

uint16_t element_addr
Element Address
uint16_t app_idx
AppKey Index
uint16_t company_id
Company ID

Espressif Systems 401 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

uint16_t element_addr
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

esp_ble_mesh_model_t *model
Pointer to the server model structure
esp_ble_mesh_msg_ctx_t ctx
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.

Espressif Systems 402 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• event: Event type
• 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
• event: Event type
• param: Pointer to callback parameter

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.
Return ESP_OK on success or error code otherwise.
Parameters
• [in] callback: Pointer to the callback function.
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.

Espressif Systems 403 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Return ESP_OK on success or error code otherwise.

Parameters
• [in] callback: Pointer to the callback function.
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.
Note If you want to find the opcodes and corresponding meanings accepted by this API, please refer to
esp_ble_mesh_opcode_health_client_get_t in esp_ble_mesh_defs.h
Return ESP_OK on success or error code otherwise.
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_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.
Note If you want to find the opcodes and corresponding meanings accepted by this API, please refer to
esp_ble_mesh_opcode_health_client_set_t in esp_ble_mesh_defs.h
Return ESP_OK on success or error code otherwise.
Parameters
• [in] params: Pointer to BLE Mesh common client parameters.
• [in] set_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_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.
Return ESP_OK on success or error code otherwise.
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

Espressif Systems 404 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 405 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

esp_ble_mesh_model_t *model
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

Espressif Systems 406 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
Bluetooth assigned 16-bit 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
Bluetooth assigned 16-bit 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
Bluetooth assigned 16-bit 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
Bluetooth assigned 16-bit Company ID
struct net_buf_simple *fault_array
FaultArray field contains a sequence of 1-octet fault values

Espressif Systems 407 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
Appropriate error code
esp_ble_mesh_client_common_param_t *params
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

esp_ble_mesh_model_t *model
Pointer to the Health Server Model
uint16_t company_id
Bluetooth assigned 16-bit Company ID
struct esp_ble_mesh_health_fault_test_cb_t
Parameters of Health Fault Test event

Espressif Systems 408 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_ble_mesh_model_t *model
Pointer to the Health Server Model
uint8_t test_id
ID of a specific test to be performed
uint16_t company_id
Bluetooth assigned 16-bit Company ID
struct esp_ble_mesh_health_attention_on_cb_t
Parameter of Health Attention On event

Public Members

esp_ble_mesh_model_t *model
Pointer to the Health Server Model
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

esp_ble_mesh_model_t *model
Pointer to the Health Server Model

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.

Espressif Systems 409 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 410 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• event: Event type
• param: Pointer to callback parameter
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
• event: Event type
• param: Pointer to callback parameter

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

Espressif Systems 411 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
Return ESP_OK on success or error code otherwise.
Parameters
• [in] callback: Pointer to the callback function.
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.
Note If you want to find the opcodes and corresponding meanings accepted by this API, please refer to
esp_ble_mesh_generic_message_opcode_t in esp_ble_mesh_defs.h
Return ESP_OK on success or error code otherwise.
Parameters
• [in] params: Pointer to BLE Mesh common client 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.
Note If you want to find the opcodes and corresponding meanings accepted by this API, please refer to
esp_ble_mesh_generic_message_opcode_t in esp_ble_mesh_defs.h
Return ESP_OK on success or error code otherwise.
Parameters
• [in] params: Pointer to BLE Mesh common client 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.
Return ESP_OK on success or error code otherwise.
Parameters
• [in] callback: Pointer to the callback function.

Unions
union esp_ble_mesh_generic_client_get_state_t
#include <esp_ble_mesh_generic_model_api.h> Generic Client Model get message union.

Espressif Systems 412 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 413 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 414 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 415 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 416 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
Indicate if optional parameters are included
int16_t level
Target value of Generic Level 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_delta_set_t
Parameters of Generic Delta Set.

Public Members

bool op_en
Indicate if optional parameters are included
int32_t level
Delta change of Generic Level 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_move_set_t
Parameters of Generic Move Set.

Public Members

bool op_en
Indicate if optional parameters are included

Espressif Systems 417 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

int16_t delta_level
Delta Level step to calculate Move speed for Generic Level 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_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
The value of the Generic OnPowerUp state
struct esp_ble_mesh_gen_power_level_set_t
Parameters of Generic Power Level Set.

Public Members

bool op_en
Indicate if optional parameters are included
uint16_t power
Target value of Generic Power Actual 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_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.

Espressif Systems 418 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

uint16_t property_id
Property ID identifying a Generic User Property
struct net_buf_simple *property_value
Raw value for the User Property

Espressif Systems 419 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

struct esp_ble_mesh_gen_admin_property_get_t
Parameter of Generic Admin Property Get.

Public Members

uint16_t property_id
Property ID identifying a Generic Admin Property
struct esp_ble_mesh_gen_admin_property_set_t
Parameters of Generic Admin Property Set.

Public Members

uint16_t property_id
Property ID identifying a Generic Admin Property
uint8_t user_access
Enumeration indicating user access
struct net_buf_simple *property_value
Raw value for the Admin Property
struct esp_ble_mesh_gen_manufacturer_property_get_t
Parameter of Generic Manufacturer Property Get.

Public Members

uint16_t property_id
Property ID identifying a Generic Manufacturer Property
struct esp_ble_mesh_gen_manufacturer_property_set_t
Parameters of Generic Manufacturer Property Set.

Public Members

uint16_t property_id
Property ID identifying a Generic Manufacturer Property
uint8_t user_access
Enumeration indicating user access
struct esp_ble_mesh_gen_client_properties_get_t
Parameter of Generic Client Properties Get.

Public Members

uint16_t property_id
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.

Espressif Systems 420 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

bool op_en
Indicate if optional parameters are included
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
Indicate if optional parameters are included
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
Time to complete state transition (C.1)
struct esp_ble_mesh_gen_def_trans_time_status_cb_t
Parameter of Generic Default Transition Time Status.

Public Members

uint8_t trans_time
The value of the Generic Default Transition Time state
struct esp_ble_mesh_gen_onpowerup_status_cb_t
Parameter of Generic OnPowerUp Status.

Public Members

uint8_t onpowerup
The value of the Generic OnPowerUp state
struct esp_ble_mesh_gen_power_level_status_cb_t
Parameters of Generic Power Level Status.

Public Members

bool op_en
Indicate if optional parameters are included
uint16_t present_power
Current value of Generic Power Actual state
uint16_t target_power
Target value of Generic Power Actual state (optional)

Espressif Systems 421 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

uint8_t remain_time
Time to complete state transition (C.1)
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
Status Code for the request message
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_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

int32_t global_latitude
Global Coordinates (Latitude)
int32_t global_longitude
Global Coordinates (Longitude)

Espressif Systems 422 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

int16_t global_altitude
Global Altitude
struct esp_ble_mesh_gen_loc_local_status_cb_t
Parameters of Generic Location Local Status.

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_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
Indicate if optional parameters are included
uint16_t property_id
Property ID identifying a Generic User Property
uint8_t user_access
Enumeration indicating user access (optional)
struct net_buf_simple *property_value
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

struct net_buf_simple *property_ids

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.

Espressif Systems 423 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

bool op_en
Indicate if optional parameters are included
uint16_t property_id
Property ID identifying a Generic Admin Property
uint8_t user_access
Enumeration indicating user access (optional)
struct net_buf_simple *property_value
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

struct net_buf_simple *property_ids

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
Indicate if optional parameters are included
uint16_t property_id
Property ID identifying a Generic Manufacturer Property
uint8_t user_access
Enumeration indicating user access (optional)
struct net_buf_simple *property_value
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

struct net_buf_simple *property_ids

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
Appropriate error code
esp_ble_mesh_client_common_param_t *params
The client common parameters.
esp_ble_mesh_gen_client_status_cb_t status_cb
The generic status message callback values

Espressif Systems 424 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

esp_ble_mesh_model_t *model
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

Espressif Systems 425 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_ble_mesh_model_t *model
Pointer to the Generic Level 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_level_state_t state
Parameters of the Generic Level 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
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
The value of the Generic Default Transition Time state
struct esp_ble_mesh_gen_def_trans_time_srv_t
User data of Generic Default Transition Time Server Model

Public Members

esp_ble_mesh_model_t *model
Pointer to the Generic Default Transition Time 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_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
The value of the Generic OnPowerUp state
struct esp_ble_mesh_gen_power_onoff_srv_t
User data of Generic Power OnOff Server Model

Public Members

esp_ble_mesh_model_t *model
Pointer to the Generic Power OnOff Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages

Espressif Systems 426 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

esp_ble_mesh_model_t *model
Pointer to the Generic Power OnOff Setup 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_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
The value of the Generic Power Default state
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

esp_ble_mesh_model_t *model
Pointer to the Generic Power Level 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_power_level_state_t *state
Parameters of the Generic Power Level 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

Espressif Systems 427 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

esp_ble_mesh_model_t *model
Pointer to the Generic Power Level Setup 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_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

esp_ble_mesh_model_t *model
Pointer to the Generic Battery 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_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

int32_t global_latitude
The value of the Global Latitude field
int32_t global_longitude
The value of the Global Longitude field
int16_t global_altitude
The value of the Global Altitude field

Espressif Systems 428 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

int16_t local_north
The value of the Local North field
int16_t local_east
The value of the Local East field
int16_t local_altitude
The value of the Local Altitude field
uint8_t floor_number
The value of the Floor Number field
uint16_t uncertainty
The value of the Uncertainty field
struct esp_ble_mesh_gen_location_srv_t
User data of Generic Location Server Model

Public Members

esp_ble_mesh_model_t *model
Pointer to the Generic Location 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_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

esp_ble_mesh_model_t *model
Pointer to the Generic Location Setup 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_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

Espressif Systems 429 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

struct esp_ble_mesh_gen_user_prop_srv_t
User data of Generic User Property Server Model

Public Members

esp_ble_mesh_model_t *model
Pointer to the Generic User Property Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
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

esp_ble_mesh_model_t *model
Pointer to the Generic Admin Property Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
uint8_t property_count
Generic Admin Property count
esp_ble_mesh_generic_property_t *properties
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

esp_ble_mesh_model_t *model
Pointer to the Generic Manufacturer Property Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
uint8_t property_count
Generic Manufacturer Property count
esp_ble_mesh_generic_property_t *properties
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

esp_ble_mesh_model_t *model
Pointer to the Generic Client Property Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages

Espressif Systems 430 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
The value of Generic Level state
struct esp_ble_mesh_state_change_gen_move_set_t
Parameter of Generic Move Set state change event

Public Members

int16_t level
The value of Generic Level state
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

Espressif Systems 431 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
uint8_t floor_number
The Floor Number value of Generic Location state
uint16_t uncertainty
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

Espressif Systems 432 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

uint16_t property_id
Property ID identifying a Generic User Property
struct esp_ble_mesh_server_recv_gen_admin_property_get_t
Context of the received Generic Admin Property Get message

Public Members

uint16_t property_id
Property ID identifying a Generic Admin Property
struct esp_ble_mesh_server_recv_gen_manufacturer_property_get_t
Context of the received Generic Manufacturer Property message

Public Members

uint16_t property_id
Property ID identifying a Generic Manufacturer Property
struct esp_ble_mesh_server_recv_gen_client_properties_get_t
Context of the received Generic Client Properties Get message

Espressif Systems 433 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

uint16_t property_id
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
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_server_recv_gen_level_set_t
Context of the received Generic Level Set message

Public Members

bool op_en
Indicate if optional parameters are included
int16_t level
Target value of Generic Level 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_server_recv_gen_delta_set_t
Context of the received Generic Delta Set message

Public Members

bool op_en
Indicate if optional parameters are included
int32_t delta_level
Delta change of Generic Level state
uint8_t tid
Transaction ID
uint8_t trans_time
Time to complete state transition (optional)

Espressif Systems 434 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

uint8_t delay
Indicate message execution delay (C.1)
struct esp_ble_mesh_server_recv_gen_move_set_t
Context of the received Generic Move Set message

Public Members

bool op_en
Indicate if optional parameters are included
int16_t delta_level
Delta Level step to calculate Move speed for Generic Level 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_server_recv_gen_def_trans_time_set_t
Context of the received Generic Default Transition Time Set message

Public Members

uint8_t trans_time
The value of the Generic Default Transition Time state
struct esp_ble_mesh_server_recv_gen_onpowerup_set_t
Context of the received Generic OnPowerUp Set message

Public Members

uint8_t onpowerup
The value of the Generic OnPowerUp state
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
Indicate if optional parameters are included
uint16_t power
Target value of Generic Power Actual 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_server_recv_gen_power_default_set_t
Context of the received Generic Power Default Set message

Espressif Systems 435 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

uint16_t power
The value of the Generic Power Default state
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
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_server_recv_gen_loc_global_set_t
Context of the received Generic Location Global Set message

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_server_recv_gen_loc_local_set_t
Context of the received Generic Location Local Set message

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_server_recv_gen_user_property_set_t
Context of the received Generic User Property Set message

Public Members

uint16_t property_id
Property ID identifying a Generic User Property
struct net_buf_simple *property_value
Raw value for the User Property

Espressif Systems 436 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

struct esp_ble_mesh_server_recv_gen_admin_property_set_t
Context of the received Generic Admin Property Set message

Public Members

uint16_t property_id
Property ID identifying a Generic Admin Property
uint8_t user_access
Enumeration indicating user access
struct net_buf_simple *property_value
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

uint16_t property_id
Property ID identifying a Generic Manufacturer Property
uint8_t user_access
Enumeration indicating user access
struct esp_ble_mesh_generic_server_cb_param_t
Generic Server Model callback parameters

Public Members

esp_ble_mesh_model_t *model
Pointer to Generic Server Models
esp_ble_mesh_msg_ctx_t ctx
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.
• cli_data: Pointer to the unique struct esp_ble_mesh_client_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
• cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• cli_data: Pointer to the unique struct esp_ble_mesh_client_t.

Espressif Systems 437 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• cli_data: Pointer to the unique struct esp_ble_mesh_client_t.
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
• cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• cli_data: Pointer to the unique struct esp_ble_mesh_client_t.
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
• cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• cli_data: Pointer to the unique struct esp_ble_mesh_client_t.
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
• cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• cli_data: Pointer to the unique struct esp_ble_mesh_client_t.
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
• cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• cli_data: Pointer to the unique struct esp_ble_mesh_client_t.
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
• cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• cli_data: Pointer to the unique struct esp_ble_mesh_client_t.
ESP_BLE_MESH_MODEL_GEN_ONOFF_SRV(srv_pub, srv_data)
Generic Server Models related context.
Define a new Generic OnOff Server Model.

Espressif Systems 438 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
1. This model shall support model publication and model subscription.
Return New Generic Level 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_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.
1. This model shall support model publication and model subscription.
Return New Generic Default Transition Time 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_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.
2. This model shall support model publication and model subscription.
Return New Generic Power 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_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_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• 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.
1. This model shall support model publication and model subscription.
Return New Generic Power Level 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_power_level_srv_t.

Espressif Systems 439 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
1. This model shall support model subscription.
Return New Generic Power Level Setup 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_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.
1. This model shall support model publication and model subscription.
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_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• 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.
1. This model shall support model publication and model subscription.
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_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• 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.
1. This model shall support model subscription.
Return New Generic Location Setup 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_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.
1. This model shall support model publication and model subscription.
Return New Generic User Property 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_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.
1. This model shall support model publication and model subscription.
Return New Generic Admin Property 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_admin_prop_srv_t.

Espressif Systems 440 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
1. This model shall support model publication and model subscription.
Return New Generic Manufacturer Property 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_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.
1. This model shall support model publication and model subscription.
Return New Generic Client Property 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_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
• event: Event type
• param: Pointer to callback parameter
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
• event: Event type
• param: Pointer to callback parameter

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

Espressif Systems 441 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
Return ESP_OK on success or error code otherwise.
Parameters
• [in] callback: Pointer to the callback function.

Espressif Systems 442 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
Return ESP_OK on success or error code otherwise.
Parameters
• [in] params: Pointer to BLE Mesh common client 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.
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
Return ESP_OK on success or error code otherwise.
Parameters
• [in] params: Pointer to BLE Mesh common client 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.
Return ESP_OK on success or error code otherwise.
Parameters
• [in] callback: Pointer to the callback function.

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.

Espressif Systems 443 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 444 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
Indicate if optional parameters are included
uint16_t property_id
Property ID of a sensor (optional)
struct esp_ble_mesh_sensor_cadence_get_t
Parameter of Sensor Cadence Get

Public Members

uint16_t property_id
Property ID of a sensor
struct esp_ble_mesh_sensor_cadence_set_t
Parameters of Sensor Cadence Set

Espressif Systems 445 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

uint16_t property_id
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
Property ID of a sensor
struct esp_ble_mesh_sensor_setting_get_t
Parameters of Sensor Setting Get

Public Members

uint16_t sensor_property_id
Property ID of a sensor
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

uint16_t sensor_property_id
Property ID identifying a sensor
uint16_t sensor_setting_property_id
Setting ID identifying a setting within 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

Espressif Systems 446 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

bool op_en
Indicate if optional parameters are included
uint16_t property_id
Property ID for the sensor (optional)
struct esp_ble_mesh_sensor_column_get_t
Parameters of Sensor Column Get

Public Members

uint16_t property_id
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
Indicate if optional parameters are included
uint16_t property_id
Property identifying a sensor
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

uint16_t property_id
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

Espressif Systems 447 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

uint16_t sensor_property_id
Property ID identifying a sensor
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
uint16_t sensor_property_id
Property ID identifying a sensor
uint16_t sensor_setting_property_id
Setting ID identifying a setting within a sensor
uint8_t sensor_setting_access
Read/Write access rights for the setting (optional)
struct net_buf_simple *sensor_setting_raw
Raw value for the setting
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

uint16_t property_id
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

uint16_t property_id
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

Espressif Systems 448 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_client_common_param_t *params
The client common parameters.
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

uint16_t property_id
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

Espressif Systems 449 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
struct net_buf_simple *fast_cadence_low
The value of Fast Cadence Low field
struct net_buf_simple *fast_cadence_high
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

struct net_buf_simple *raw_value_x

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

uint16_t sensor_property_id
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

Espressif Systems 450 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

esp_ble_mesh_model_t *model
Pointer to the Sensor Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
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

esp_ble_mesh_model_t *model
Pointer to the Sensor Setup Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
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

uint16_t property_id
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

Espressif Systems 451 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
struct net_buf_simple *fast_cadence_low
The value of Fast Cadence Low state
struct net_buf_simple *fast_cadence_high
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

uint16_t property_id
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
Indicate if optional parameters are included
uint16_t property_id
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

uint16_t property_id
Property ID of a sensor
struct esp_ble_mesh_server_recv_sensor_settings_get_t
Context of the received Sensor Settings Get message

Public Members

uint16_t property_id
Property ID of a sensor
struct esp_ble_mesh_server_recv_sensor_setting_get_t
Context of the received Sensor Setting Get message

Espressif Systems 452 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

uint16_t property_id
Property ID of a sensor
uint16_t setting_property_id
Setting ID identifying a setting within a sensor
struct esp_ble_mesh_server_recv_sensor_get_t
Context of the received Sensor Get message

Public Members

bool op_en
Indicate if optional parameters are included
uint16_t property_id
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

uint16_t property_id
Property identifying a sensor
struct net_buf_simple *raw_value_x
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
Indicate if optional parameters are included
uint16_t property_id
Property identifying a sensor
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

uint16_t property_id
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

Espressif Systems 453 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

uint16_t property_id
Property ID identifying a sensor
uint16_t setting_property_id
Setting ID identifying a setting within a sensor
struct net_buf_simple *setting_raw
Raw value for the setting
struct esp_ble_mesh_sensor_server_cb_param_t
Sensor Server Model callback parameters

Public Members

esp_ble_mesh_model_t *model
Pointer to Sensor Server Models
esp_ble_mesh_msg_ctx_t ctx
Context of the received messages
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
• cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• cli_data: Pointer to the unique struct esp_ble_mesh_client_t.
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.
1. This model shall support model publication and model subscription.
Return New Sensor 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_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.
1. This model shall support model publication and model subscription.
Return New Sensor Setup 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_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

Espressif Systems 454 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 455 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• _data: Pointer to the start of the sensor data.
• _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
• _data: Pointer to the start of the sensor data.
• _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

Espressif Systems 456 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• event: Event type

• param: Pointer to callback parameter
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
• event: Event type
• param: Pointer to callback parameter

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
1. When get_auto_rsp is set to ESP_BLE_MESH_SERVER_AUTO_RSP, no event will be callback
to the application layer when Sensor 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 Sensor Set/Set Unack messages are received.
ESP_BLE_MESH_SENSOR_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 Sensor Get messages are received.
ESP_BLE_MESH_SENSOR_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 Sensor Set/Set Unack messages are received.
ESP_BLE_MESH_SENSOR_SERVER_EVT_MAX

Espressif Systems 457 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
Return ESP_OK on success or error code otherwise.
Parameters
• [in] callback: Pointer to the callback function.
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.
Note If you want to know the opcodes and corresponding meanings accepted by this API, please refer to
esp_ble_mesh_time_scene_message_opcode_t in esp_ble_mesh_defs.h
Return ESP_OK on success or error code otherwise.
Parameters
• [in] params: Pointer to BLE Mesh common client 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.
Note If you want to know the opcodes and corresponding meanings accepted by this API, please refer to
esp_ble_mesh_time_scene_message_opcode_t in esp_ble_mesh_defs.h
Return ESP_OK on success or error code otherwise.
Parameters
• [in] params: Pointer to BLE Mesh common client 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.
Return ESP_OK on success or error code otherwise.
Parameters
• [in] callback: Pointer to the callback function.

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.

Espressif Systems 458 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 459 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 460 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 461 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
Indicate if optional parameters are included
uint16_t scene_number
The number of scenes to be recalled
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_scene_delete_t
Parameter of Scene Delete

Public Members

uint16_t scene_number
The number of scenes to be deleted
struct esp_ble_mesh_scheduler_act_get_t
Parameter of Scheduler Action Get

Espressif Systems 462 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
uint16_t scene_number
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 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

Espressif Systems 463 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

uint8_t time_zone_offset
The local time zone offset in 15-minute increments
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
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_status_cb_t
Parameters of TAI-UTC Delta Status

Public Members

uint16_t tai_utc_delta_curr : 15
Current difference between TAI and UTC in seconds
uint16_t padding_1 : 1
Always 0b0. Other values are Prohibited.
uint16_t tai_utc_delta_new : 15
Upcoming difference between TAI and UTC in seconds
uint16_t padding_2 : 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_status_cb_t
Parameter of Time Role Status

Public Members

uint8_t time_role
The Time Role for the element
struct esp_ble_mesh_scene_status_cb_t
Parameters of Scene Status

Public Members

bool op_en
Indicate if optional parameters are included
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)

Espressif Systems 464 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

uint8_t remain_time
Time to complete state transition (C.1)
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
uint16_t current_scene
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
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
uint16_t scene_number
Transition time for this action

Espressif Systems 465 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

struct esp_ble_mesh_time_scene_client_cb_param_t
Time Scene 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_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

uint8_t tai_seconds[5]
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
uint8_t time_zone_offset_curr
The value of the Time Zone Offset Current field
uint8_t time_zone_offset_new
The value of the Time Zone Offset New state
uint8_t tai_zone_change[5]
The value of the TAI of Zone Chaneg field
uint16_t time_authority : 1
The value of the Time Authority bit
uint16_t tai_utc_delta_curr : 15
The value of the TAI-UTC Delta Current state
uint16_t tai_utc_delta_new : 15
The value of the TAI-UTC Delta New state
uint8_t tai_delta_change[5]
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

esp_ble_mesh_model_t *model
Pointer to the Time Server Model. Initialized internally.

Espressif Systems 466 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
esp_ble_mesh_time_state_t *state
Parameters of the Time state
struct esp_ble_mesh_time_setup_srv_t
User data of Time Setup Server Model

Public Members

esp_ble_mesh_model_t *model
Pointer to the Time Setup Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
esp_ble_mesh_time_state_t *state
Parameters of the Time 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

uint16_t scene_number
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.

Espressif Systems 467 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
uint16_t current_scene
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

esp_ble_mesh_model_t *model
Pointer to the Scene Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
esp_ble_mesh_scenes_state_t *state
Parameters of the Scenes 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_scene_setup_srv_t
User data of Scene Setup Server Model

Espressif Systems 468 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_ble_mesh_model_t *model
Pointer to the Scene Setup Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
esp_ble_mesh_scenes_state_t *state
Parameters of the Scenes 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
uint64_t day_of_week : 7
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
uint64_t trans_time : 8
The value of Transition time for this action
uint16_t scene_number
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

Espressif Systems 469 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_ble_mesh_model_t *model
Pointer to the Scheduler Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
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

esp_ble_mesh_model_t *model
Pointer to the Scheduler Setup Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
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 tai_seconds[5]
The current TAI time in seconds
uint8_t subsecond
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_curr : 15
Current difference between TAI and UTC in seconds
uint8_t time_zone_offset_curr
The local time zone offset in 15-minute increments
struct esp_ble_mesh_state_change_time_status_t
Parameters of Time Status state change event

Public Members

uint8_t tai_seconds[5]
The current TAI time in seconds
uint8_t subsecond
The sub-second time in units of 1/256 second
uint8_t uncertainty
The estimated uncertainty in 10-millisecond steps

Espressif Systems 470 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

uint16_t time_authority : 1
0 = No Time Authority, 1 = Time Authority
uint16_t tai_utc_delta_curr : 15
Current difference between TAI and UTC in seconds
uint8_t time_zone_offset_curr
The local time zone offset in 15-minute increments
struct esp_ble_mesh_state_change_time_zone_set_t
Parameters of Time Zone Set state change event

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_state_change_tai_utc_delta_set_t
Parameters of TAI UTC Delta Set state change event

Public Members

uint16_t tai_utc_delta_new : 15
Upcoming difference between TAI and UTC in seconds
uint8_t tai_delta_change[5]
TAI Seconds time of the upcoming TAI-UTC Delta change
struct esp_ble_mesh_state_change_time_role_set_t
Parameter of Time Role Set state change event

Public Members

uint8_t time_role
The Time Role for the element
struct esp_ble_mesh_state_change_scene_store_t
Parameter of Scene Store state change event

Public Members

uint16_t scene_number
The number of scenes to be stored
struct esp_ble_mesh_state_change_scene_recall_t
Parameter of Scene Recall state change event

Public Members

uint16_t scene_number
The number of scenes to be recalled
struct esp_ble_mesh_state_change_scene_delete_t
Parameter of Scene Delete state change event

Espressif Systems 471 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

uint16_t scene_number
The number of scenes to be deleted
struct esp_ble_mesh_state_change_scheduler_act_set_t
Parameter of Scheduler Action Set state change event

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
uint16_t scene_number
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 tai_seconds[5]
The current TAI time in seconds
uint8_t subsecond
The sub-second time in units of 1/256 second

Espressif Systems 472 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_server_recv_time_zone_set_t
Context of the received Time Zone Set message

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_server_recv_tai_utc_delta_set_t
Context of the received TAI UTC Delta Set message

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_server_recv_time_role_set_t
Context of the received Time Role Set message

Public Members

uint8_t time_role
The Time Role for the element
struct esp_ble_mesh_server_recv_scene_store_t
Context of the received Scene Store message

Public Members

uint16_t scene_number
The number of scenes to be stored
struct esp_ble_mesh_server_recv_scene_recall_t
Context of the received Scene Recall message

Espressif Systems 473 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

bool op_en
Indicate if optional parameters are included
uint16_t scene_number
The number of scenes to be recalled
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_server_recv_scene_delete_t
Context of the received Scene Delete message

Public Members

uint16_t scene_number
The number of scenes to be deleted
struct esp_ble_mesh_server_recv_scheduler_act_set_t
Context of the received Scheduler Action Set message

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
uint16_t scene_number
Scene number to be used for some actions
struct esp_ble_mesh_server_recv_time_status_t
Context of the received Time Status message

Espressif Systems 474 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

uint8_t tai_seconds[5]
The current TAI time in seconds
uint8_t subsecond
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_scene_server_cb_param_t
Time Scene Server Model callback parameters

Public Members

esp_ble_mesh_model_t *model
Pointer to Time and Scenes Server Models
esp_ble_mesh_msg_ctx_t ctx
Context of the received messages
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
• cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• cli_data: Pointer to the unique struct esp_ble_mesh_client_t.
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
• cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• cli_data: Pointer to the unique struct esp_ble_mesh_client_t.
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
• cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• cli_data: Pointer to the unique struct esp_ble_mesh_client_t.

Espressif Systems 475 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
1. This model shall support model publication and model subscription.
Return New Time 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_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.
1. This model shall support model publication and model subscription.
2. The model may be present only on the Primary element of a node.
Return New Scene 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_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.
1. This model shall support model subscription.
2. The model may be present only on the Primary element of a node.
Return New Scene Setup 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_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.
1. This model shall support model publication and model subscription.
2. The model may be present only on the Primary element of a node.
3. The model requires the Time Server model shall be present on the element.
Return New Scheduler 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_scheduler_srv_t.

Espressif Systems 476 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
1. This model shall support model subscription.
2. The model may be present only on the Primary element of a node.
Return New Scheduler Setup 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_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

Espressif Systems 477 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• event: Event type
• param: Pointer to callback parameter
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
• event: Event type

Espressif Systems 478 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• param: Pointer to callback parameter

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
1. When get_auto_rsp is set to ESP_BLE_MESH_SERVER_AUTO_RSP, no event will be callback
to the application layer when Time Scene 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 Time Scene Set/Set Unack messages are received.
ESP_BLE_MESH_TIME_SCENE_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 Time Scene Get messages are received.
ESP_BLE_MESH_TIME_SCENE_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 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.
Return ESP_OK on success or error code otherwise.
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.
Note If you want to know the opcodes and corresponding meanings accepted by this API, please refer to
esp_ble_mesh_light_message_opcode_t in esp_ble_mesh_defs.h

Espressif Systems 479 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Return ESP_OK on success or error code otherwise.

Parameters
• [in] params: Pointer to BLE Mesh common client 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.
Note If you want to know the opcodes and corresponding meanings accepted by this API, please refer to
esp_ble_mesh_light_message_opcode_t in esp_ble_mesh_defs.h
Return ESP_OK on success or error code otherwise.
Parameters
• [in] params: Pointer to BLE Mesh common client 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.
Return ESP_OK on success or error code otherwise.
Parameters
• [in] callback: Pointer to the callback function.

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

Espressif Systems 480 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 481 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 482 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 483 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 484 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
Indicate if optional parameters are included
uint16_t lightness
Target value of light lightness actual 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_light_lightness_linear_set_t
Parameters of Light Lightness Linear Set

Public Members

bool op_en
Indicate if optional parameters are included
uint16_t lightness
Target value of light lightness linear state
uint8_t tid
Transaction ID
uint8_t trans_time
Time to complete state transition (optional)

Espressif Systems 485 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

uint8_t delay
Indicate message execution delay (C.1)
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
Indicate if optional parameters are included
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
Time to complete state transition (optional)
uint8_t delay
Indicate message execution delay (C.1)
struct esp_ble_mesh_light_ctl_temperature_set_t
Parameters of Light CTL Temperature Set

Public Members

bool op_en
Indicate if optional parameters are included
uint16_t ctl_temperatrue
Target value of light ctl temperature state
int16_t ctl_delta_uv
Target value of light ctl delta UV state

Espressif Systems 486 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_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
uint16_t temperature
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
Indicate if optional parameters are included
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
Time to complete state transition (optional)
uint8_t delay
Indicate message execution delay (C.1)
struct esp_ble_mesh_light_hsl_hue_set_t
Parameters of Light HSL Hue Set

Espressif Systems 487 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

bool op_en
Indicate if optional parameters are included
uint16_t hue
Target value of light hsl hue 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_light_hsl_saturation_set_t
Parameters of Light HSL Saturation Set

Public Members

bool op_en
Indicate if optional parameters are included
uint16_t saturation
Target value of light hsl hue 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_light_hsl_default_set_t
Parameters of Light HSL Default Set

Public Members

uint16_t lightness
Value of light lightness default state
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

Espressif Systems 488 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
Time to complete state transition (optional)
uint8_t delay
Indicate message execution delay (C.1)
struct esp_ble_mesh_light_xyl_default_set_t
Parameters of Light xyL Default Set

Public Members

uint16_t lightness
The value of the Light Lightness Default state
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

Espressif Systems 489 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
Indicate whether optional parameters included
uint8_t light_onoff
The target value of the Light LC Light OnOff state
uint8_t tid
Transaction Identifier
uint8_t trans_time
Time to complete state transition (optional)
uint8_t delay
Indicate message execution delay (C.1)
struct esp_ble_mesh_light_lc_property_get_t
Parameter of Light LC Property Get

Public Members

uint16_t property_id
Property ID identifying a Light LC Property
struct esp_ble_mesh_light_lc_property_set_t
Parameters of Light LC Property Set

Public Members

uint16_t property_id
Property ID identifying a Light LC Property
struct net_buf_simple *property_value
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

Espressif Systems 490 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

bool op_en
Indicate if optional parameters are included
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
Time to complete state transition (C.1)
struct esp_ble_mesh_light_lightness_linear_status_cb_t
Parameters of Light Lightness Linear Status

Public Members

bool op_en
Indicate if optional parameters are included
uint16_t present_lightness
Current value of light lightness linear state
uint16_t target_lightness
Target value of light lightness linear state (optional)
uint8_t remain_time
Time to complete state transition (C.1)
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
Status Code for the request message
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

Espressif Systems 491 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

struct esp_ble_mesh_light_ctl_status_cb_t
Parameters of Light CTL Status

Public Members

bool op_en
Indicate if optional parameters are included
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
Time to complete state transition (C.1)
struct esp_ble_mesh_light_ctl_temperature_status_cb_t
Parameters of Light CTL Temperature Status

Public Members

bool op_en
Indicate if optional parameters are included
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
Time to complete state transition (C.1)
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
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_status_cb_t
Parameters of Light CTL Default Status

Espressif Systems 492 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

uint16_t lightness
Value of light lightness default state
uint16_t temperature
Value of light temperature default state
int16_t delta_uv
Value of light delta UV default state
struct esp_ble_mesh_light_hsl_status_cb_t
Parameters of Light HSL Status

Public Members

bool op_en
Indicate if optional parameters are included
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
Time to complete state transition (optional)
struct esp_ble_mesh_light_hsl_target_status_cb_t
Parameters of Light HSL Target Status

Public Members

bool op_en
Indicate if optional parameters are included
uint16_t hsl_lightness_target
Target value of light hsl lightness state
uint16_t hsl_hue_target
Target value of light hsl hue state
uint16_t hsl_saturation_target
Target value of light hsl saturation state
uint8_t remain_time
Time to complete state transition (optional)
struct esp_ble_mesh_light_hsl_hue_status_cb_t
Parameters of Light HSL Hue Status

Public Members

bool op_en
Indicate if optional parameters are included
uint16_t present_hue
Current value of light hsl hue state

Espressif Systems 493 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

uint16_t target_hue
Target value of light hsl hue state (optional)
uint8_t remain_time
Time to complete state transition (C.1)
struct esp_ble_mesh_light_hsl_saturation_status_cb_t
Parameters of Light HSL Saturation Status

Public Members

bool op_en
Indicate if optional parameters are included
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
Time to complete state transition (C.1)
struct esp_ble_mesh_light_hsl_default_status_cb_t
Parameters of Light HSL Default Status

Public Members

uint16_t lightness
Value of light lightness default state
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_status_cb_t
Parameters of Light HSL Range Status

Public Members

uint8_t status_code
Status code for the request message
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_status_cb_t
Parameters of Light xyL Status

Espressif Systems 494 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

bool op_en
Indicate whether optional parameters included
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
Time to complete state transition (optional)
struct esp_ble_mesh_light_xyl_target_status_cb_t
Parameters of Light xyL Target Status

Public Members

bool op_en
Indicate whether optional parameters included
uint16_t target_xyl_lightness
The target value of the Light xyL Lightness state
uint16_t target_xyl_x
The target value of the Light xyL x state
uint16_t target_xyl_y
The target value of the Light xyL y state
uint8_t remain_time
Time to complete state transition (optional)
struct esp_ble_mesh_light_xyl_default_status_cb_t
Parameters of Light xyL Default Status

Public Members

uint16_t lightness
The value of the Light Lightness Default state
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_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
The value of the xyL x Range Min field of the Light xyL x Range state

Espressif Systems 495 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_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
Indicate whether optional parameters included
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
Time to complete state transition (C.1)
struct esp_ble_mesh_light_lc_property_status_cb_t
Parameters of Light LC Property Status

Public Members

uint16_t property_id
Property ID identifying a Light LC Property
struct net_buf_simple *property_value
Raw value for the Light LC Property
struct esp_ble_mesh_light_client_cb_param_t
Lighting Client Model callback parameters

Espressif Systems 496 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

int error_code
Appropriate error code
esp_ble_mesh_client_common_param_t *params
The client common parameters.
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

esp_ble_mesh_model_t *model
Pointer to the Lighting Lightness Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
esp_ble_mesh_light_lightness_state_t *state
Parameters of the Light Lightness state
esp_ble_mesh_last_msg_info_t last
Parameters of the last received set message
esp_ble_mesh_state_transition_t actual_transition
Parameters of state transition
esp_ble_mesh_state_transition_t linear_transition
Parameters of state transition

Espressif Systems 497 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

esp_ble_mesh_model_t *model
Pointer to the Lighting Lightness Setup Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
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
uint16_t target_lightness
The target value of Light CTL Lightness state
uint16_t temperature
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 lightness_default
The value of Light Lightness Default 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

Espressif Systems 498 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

esp_ble_mesh_model_t *model
Pointer to the Lighting CTL Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
esp_ble_mesh_light_ctl_state_t *state
Parameters of the Light CTL 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
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

esp_ble_mesh_model_t *model
Pointer to the Lighting CTL Setup Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
esp_ble_mesh_light_ctl_state_t *state
Parameters of the Light CTL state
struct esp_ble_mesh_light_ctl_temp_srv_t
User data of Light CTL Temperature Server Model

Public Members

esp_ble_mesh_model_t *model
Pointer to the Lighting CTL Temperature Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
esp_ble_mesh_light_ctl_state_t *state
Parameters of the Light CTL 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
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

Espressif Systems 499 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
uint16_t target_lightness
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 lightness_default
The value of Light Lightness Default 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
uint16_t hue_range_min
The minimum value of Light HSL Hue Range state
uint16_t hue_range_max
The maximum value of Light HSL Hue Range state
uint16_t saturation_range_min
The minimum value of Light HSL Saturation state
uint16_t saturation_range_max
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

esp_ble_mesh_model_t *model
Pointer to the Lighting HSL Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
esp_ble_mesh_light_hsl_state_t *state
Parameters of the Light HSL 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

Espressif Systems 500 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

int32_t tt_delta_lightness
Delta change value of lightness state transition
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

esp_ble_mesh_model_t *model
Pointer to the Lighting HSL Setup Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
esp_ble_mesh_light_hsl_state_t *state
Parameters of the Light HSL state
struct esp_ble_mesh_light_hsl_hue_srv_t
User data of Light HSL Hue Server Model

Public Members

esp_ble_mesh_model_t *model
Pointer to the Lighting HSL Hue Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
esp_ble_mesh_light_hsl_state_t *state
Parameters of the Light HSL 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
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

esp_ble_mesh_model_t *model
Pointer to the Lighting HSL Saturation Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
esp_ble_mesh_light_hsl_state_t *state
Parameters of the Light HSL state
esp_ble_mesh_last_msg_info_t last
Parameters of the last received set message

Espressif Systems 501 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

esp_ble_mesh_state_transition_t transition
Parameters of state transition
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
uint16_t target_lightness
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 lightness_default
The value of Light Lightness Default 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

esp_ble_mesh_model_t *model
Pointer to the Lighting xyL Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
esp_ble_mesh_light_xyl_state_t *state
Parameters of the Light xyL state

Espressif Systems 502 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
int32_t tt_delta_lightness
Delta change value of lightness state transition
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

esp_ble_mesh_model_t *model
Pointer to the Lighting xyL Setup Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
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

Espressif Systems 503 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
A timing state that determines the time the controlled lights fade from the level determined by the Light
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
A timing state that determines the time the controlled lights fade from the level determined by the Light
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

Espressif Systems 504 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
struct k_delayed_work timer
Timer of Light LC state machine

Espressif Systems 505 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

esp_ble_mesh_model_t *model
Pointer to the Lighting LC Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
esp_ble_mesh_light_control_t *lc
Parameters of the Light controller
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_light_lc_setup_srv_t
User data of Light LC Setup Server Model

Public Members

esp_ble_mesh_model_t *model
Pointer to the Lighting LC Setup Server Model. Initialized internally.
esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl
Response control of the server model received messages
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

Espressif Systems 506 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
The value of Light Lightness Default state
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
uint16_t temperature
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

uint16_t temperature
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

Espressif Systems 507 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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 Lightness Default state
uint16_t temperature
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

Espressif Systems 508 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

uint16_t hue_range_min
The minimum hue value of Light HSL Range state
uint16_t hue_range_max
The maximum hue value of Light HSL Range state
uint16_t saturation_range_min
The minimum saturation value of Light HSL Range state
uint16_t saturation_range_max
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
The value of Light Lightness Default state
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

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_state_change_light_lc_mode_set_t
Parameter of Light LC Mode state change event

Espressif Systems 509 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

uint16_t property_id
The property id of Light LC Property state
struct net_buf_simple *property_value
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

uint16_t property_id
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

Espressif Systems 510 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

uint16_t property_id
Property ID identifying a Light LC Property
struct esp_ble_mesh_server_recv_light_lightness_set_t
Context of the received Light Lightness Set message

Public Members

bool op_en
Indicate if optional parameters are included
uint16_t lightness
Target value of light lightness actual 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_server_recv_light_lightness_linear_set_t
Context of the received Light Lightness Linear Set message

Public Members

bool op_en
Indicate if optional parameters are included
uint16_t lightness
Target value of light lightness linear 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_server_recv_light_lightness_default_set_t
Context of the received Light Lightness Default Set message

Public Members

uint16_t lightness
The value of the Light Lightness Default state
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
Value of range min field of light lightness range state

Espressif Systems 511 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

uint16_t range_max
Value of range max field of light lightness range state
struct esp_ble_mesh_server_recv_light_ctl_set_t
Context of the received Light CTL Set message

Public Members

bool op_en
Indicate if optional parameters are included
uint16_t lightness
Target value of light ctl lightness state
uint16_t temperature
Target value of light ctl temperature state
int16_t delta_uv
Target value of light ctl delta UV 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_server_recv_light_ctl_temperature_set_t
Context of the received Light CTL Temperature Set message

Public Members

bool op_en
Indicate if optional parameters are included
uint16_t temperature
Target value of light ctl temperature state
int16_t delta_uv
Target value of light ctl delta UV 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_server_recv_light_ctl_temperature_range_set_t
Context of the received Light CTL Temperature Range Set message

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

Espressif Systems 512 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
Value of light lightness default state
uint16_t temperature
Value of light temperature default state
int16_t delta_uv
Value of light delta UV default state
struct esp_ble_mesh_server_recv_light_hsl_set_t
Context of the received Light HSL Set message

Public Members

bool op_en
Indicate if optional parameters are included
uint16_t lightness
Target value of light hsl lightness state
uint16_t hue
Target value of light hsl hue state
uint16_t saturation
Target value of light hsl saturation 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_server_recv_light_hsl_hue_set_t
Context of the received Light HSL Hue Set message

Public Members

bool op_en
Indicate if optional parameters are included
uint16_t hue
Target value of light hsl hue 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_server_recv_light_hsl_saturation_set_t
Context of the received Light HSL Saturation Set message

Espressif Systems 513 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

bool op_en
Indicate if optional parameters are included
uint16_t saturation
Target value of light hsl hue 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_server_recv_light_hsl_default_set_t
Context of the received Light HSL Default Set message

Public Members

uint16_t lightness
Value of light lightness default state
uint16_t hue
Value of light hue default state
uint16_t saturation
Value of light saturation default state
struct esp_ble_mesh_server_recv_light_hsl_range_set_t
Context of the received Light HSL Range Set message

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_server_recv_light_xyl_set_t
Context of the received Light xyL Set message

Public Members

bool op_en
Indicate whether optional parameters included
uint16_t lightness
The target value of the Light xyL Lightness state
uint16_t x
The target value of the Light xyL x state

Espressif Systems 514 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

uint16_t y
The target value of the Light xyL y state
uint8_t tid
Transaction Identifier
uint8_t trans_time
Time to complete state transition (optional)
uint8_t delay
Indicate message execution delay (C.1)
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
The value of the Light Lightness Default state
uint16_t x
The value of the Light xyL x Default state
uint16_t y
The value of the Light xyL y Default state
struct esp_ble_mesh_server_recv_light_xyl_range_set_t
Context of the received Light xyl Range Set message

Public Members

uint16_t x_range_min
The value of the xyL x Range Min field of the Light xyL x Range state
uint16_t x_range_max
The value of the xyL x Range Max field of the Light xyL x Range state
uint16_t y_range_min
The value of the xyL y Range Min field of the Light xyL y Range state
uint16_t y_range_max
The value of the xyL y Range Max field of the Light xyL y Range state
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

Espressif Systems 515 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Public Members

bool op_en
Indicate whether optional parameters included
uint8_t light_onoff
The target value of the Light LC Light OnOff state
uint8_t tid
Transaction Identifier
uint8_t trans_time
Time to complete state transition (optional)
uint8_t delay
Indicate message execution delay (C.1)
struct esp_ble_mesh_server_recv_light_lc_property_set_t
Context of the received Light LC Property Set message

Public Members

uint16_t property_id
Property ID identifying a Light LC Property
struct net_buf_simple *property_value
Raw value for the Light LC Property
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

esp_ble_mesh_model_t *model
Pointer to Lighting Server Models
esp_ble_mesh_msg_ctx_t ctx
Context of the received messages
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
• cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• cli_data: Pointer to the unique struct esp_ble_mesh_client_t.

Espressif Systems 516 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• cli_data: Pointer to the unique struct esp_ble_mesh_client_t.
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
• cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• cli_data: Pointer to the unique struct esp_ble_mesh_client_t.
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
• cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• cli_data: Pointer to the unique struct esp_ble_mesh_client_t.
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
• cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• cli_data: Pointer to the unique struct esp_ble_mesh_client_t.
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.
1. This model shall support model publication and model subscription.
Return New Light Lightness 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_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.
1. This model shall support model subscription.
Return New Light Lightness Setup 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_light_lightness_setup_srv_t.

Espressif Systems 517 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
1. This model shall support model publication and model subscription.
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_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• 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.
1. This model shall support model subscription.
Return New Light CTL Setup 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_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.
1. This model shall support model publication and model subscription.
Return New Light CTL Temperature 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_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.
1. This model shall support model publication and model subscription.
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_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• 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.
1. This model shall support model subscription.

Espressif Systems 518 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Return New Light HSL Setup 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_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.
1. This model shall support model publication and model subscription.
Return New Light HSL Hue 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_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.
1. This model shall support model publication and model subscription.
Return New Light HSL Saturation 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_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.
1. This model shall support model publication and model subscription.
Return New Light xyL 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_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.
1. This model shall support model subscription.
Return New Light xyL Setup 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_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.
1. This model shall support model publication and model subscription.
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_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• 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.

Espressif Systems 519 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Note 1. The Light LC (Lightness Control) Setup model extends the Light LC Server model.
1. This model shall support model publication and model subscription.
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_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t.
• 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
• event: Event type
• param: Pointer to callback parameter
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
• event: Event type
• param: Pointer to callback parameter

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

Espressif Systems 520 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
1. When get_auto_rsp is set to ESP_BLE_MESH_SERVER_AUTO_RSP, no event will be callback
to the application layer when Lighting 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 Lighting Set/Set Unack messages are received.
ESP_BLE_MESH_LIGHTING_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 Lighting Get messages are received.
ESP_BLE_MESH_LIGHTING_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 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).

Espressif Systems 521 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• 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_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• 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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_INVALID_ARG: invalid argument
Parameters

Espressif Systems 522 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• [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_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_INVALID_ARG: invalid argument
• ESP_ERR_NO_MEM: out of memory
• 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_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
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_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
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_INIT: WiFi is not initialized by esp_wifi_init
• 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

Espressif Systems 523 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_WIFI_NOT_STARTED: WiFi was not started by esp_wifi_start
• ESP_ERR_INVALID_ARG: invalid argument
• 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_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_WIFI_NOT_STARTED: WiFi was not started by esp_wifi_start
• 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_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start
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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start
• ESP_ERR_INVALID_ARG: invalid argument
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

Espressif Systems 524 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• ESP_OK: succeed
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start
• ESP_ERR_INVALID_ARG: invalid argument
• ESP_ERR_NO_MEM: out of memory
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_NOT_INIT: WiFi is not initialized by esp_wifi_init
• 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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_WIFI_IF: invalid interface
• ESP_ERR_INVALID_ARG: invalid argument
• others: refer to error codes in esp_err.h
Parameters

Espressif Systems 525 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• 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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_WIFI_IF: invalid interface
• ESP_ERR_INVALID_ARG: invalid argument
• others: refer to error codes in esp_err.h
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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_WIFI_IF: invalid interface
• ESP_ERR_INVALID_ARG: invalid argument
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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_WIFI_IF: invalid interface
• ESP_ERR_INVALID_ARG: invalid argument
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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_INVALID_ARG: invalid argument
Parameters
• primary: store current primary channel
• [out] second: store current second channel

Espressif Systems 526 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_INVALID_ARG: invalid argument
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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_INVALID_ARG: invalid argument
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_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_INVALID_ARG: invalid argument
• ESP_ERR_WIFI_IF: invalid interface
• ESP_ERR_WIFI_MAC: invalid mac address
• ESP_ERR_WIFI_MODE: WiFi mode is wrong
• others: refer to error codes in esp_err.h
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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init

Espressif Systems 527 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• ESP_ERR_INVALID_ARG: invalid argument

• ESP_ERR_WIFI_IF: invalid interface
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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
Parameters
• cb: callback
esp_err_t esp_wifi_set_promiscuous(bool en)
Enable the promiscuous mode.
Return
• ESP_OK: succeed
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
Parameters
• en: false - disable, true - enable
esp_err_t esp_wifi_get_promiscuous(bool *en)
Get the promiscuous mode.
Return
• ESP_OK: succeed
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_INVALID_ARG: invalid argument
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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_INVALID_ARG: invalid argument
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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
Parameters
• filter: the subtype of the control packet filtered in promiscuous mode.

Espressif Systems 528 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_NOT_INIT: WiFi is not initialized by esp_wifi_init
• 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_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_INVALID_ARG: invalid argument
• ESP_ERR_WIFI_IF: invalid interface
• 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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_INVALID_ARG: invalid argument
• ESP_ERR_WIFI_IF: invalid interface
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_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_INVALID_ARG: invalid argument
• ESP_ERR_WIFI_MODE: WiFi mode is wrong
• 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

Espressif Systems 529 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• ESP_OK: succeed
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_INVALID_ARG: invalid argument
• ESP_ERR_NOT_FOUND: Requested resource not found
• ESP_ERR_WIFI_MODE: WiFi mode is wrong
• 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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_INVALID_ARG: invalid argument
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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
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

Espressif Systems 530 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• ESP_OK: succeed
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• 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_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_WIFI_NOT_START: WiFi is not started by esp_wifi_start
• ESP_ERR_WIFI_ARG: invalid argument
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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_WIFI_ARG: invalid argument
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

Espressif Systems 531 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
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_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_WIFI_NOT_START: WiFi is not started by esp_wifi_start or promiscuous mode is not en-
abled
• ESP_ERR_INVALID_ARG: invalid argument
Parameters
• config: configuration
esp_err_t esp_wifi_set_csi(bool en)
Enable or disable CSI.
return
• ESP_OK: succeed
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_WIFI_NOT_START: WiFi is not started by esp_wifi_start or promiscuous mode is not en-
abled
• ESP_ERR_INVALID_ARG: invalid argument
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_NOT_INIT: WiFi is not initialized by esp_wifi_init
• 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_NOT_INIT: WiFi is not initialized by esp_wifi_init
• 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

Espressif Systems 532 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• ESP_OK: succeed
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• 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_NOT_INIT: WiFi is not initialized by esp_wifi_init
• 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_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start
• 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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_WIFI_ARG: invalid argument
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

Espressif Systems 533 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_WIFI_ARG: invalid argument
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
• ifx: Interface to be configured.
• 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.
Attention 1. This API should be called after esp_wifi_init() and before esp_wifi_start().
Return
• ESP_OK: succeed
• others: failed
Parameters
• ifx: Interface to be configured.
• rate: Phy rate to be configured.

Espressif Systems 534 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_INVALID_ARG: invalid argument
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
• ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
• ESP_ERR_INVALID_ARG: invalid argument
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.
Attention 1. This API should be called after esp_wifi_init() and before esp_wifi_start().
Return
• ESP_OK: succeed
• others: failed
Parameters
• ifx: Interface to be configured.
• rate: Phy rate to be configured.

Structures

Espressif Systems 535 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 536 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 537 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 538 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 539 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 540 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
wifi_auth_mode_t authmode
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
wifi_auth_mode_t authmode
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

Espressif Systems 541 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
uint8_t password[64]
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

Espressif Systems 542 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

uint32_t reserved : 29
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
uint32_t reserved : 27
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.

Espressif Systems 543 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
unsigned __pad1__ : 16
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
unsigned __pad2__ : 16
reserved
unsigned smoothing : 1
reserved
unsigned not_sounding : 1
reserved
unsigned __pad3__ : 1
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
unsigned __pad4__ : 8
reserved

Espressif Systems 544 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
unsigned __pad5__ : 32
reserved
unsigned __pad6__ : 31
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)
unsigned __pad7__ : 12
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

Espressif Systems 545 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 546 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 547 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
wifi_auth_mode_t authmode
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

Espressif Systems 548 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 549 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 550 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 551 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 552 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 553 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 554 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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:

Espressif Systems 555 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 556 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
WIFI_PHY_RATE_2M_L = 0x01
2 Mbps with long preamble
WIFI_PHY_RATE_5M_L = 0x02
5.5 Mbps with long preamble
WIFI_PHY_RATE_11M_L = 0x03
11 Mbps with long preamble
WIFI_PHY_RATE_2M_S = 0x05
2 Mbps with short preamble
WIFI_PHY_RATE_5M_S = 0x06
5.5 Mbps with short preamble
WIFI_PHY_RATE_11M_S = 0x07
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

Espressif Systems 557 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

WIFI_PHY_RATE_MCS1_LGI = 0x11
MCS1 with long GI, 13 Mbps for 20MHz, 27 Mbps for 40MHz
WIFI_PHY_RATE_MCS2_LGI = 0x12
MCS2 with long GI, 19.5 Mbps for 20MHz, 40.5 Mbps for 40MHz
WIFI_PHY_RATE_MCS3_LGI = 0x13
MCS3 with long GI, 26 Mbps for 20MHz, 54 Mbps for 40MHz
WIFI_PHY_RATE_MCS4_LGI = 0x14
MCS4 with long GI, 39 Mbps for 20MHz, 81 Mbps for 40MHz
WIFI_PHY_RATE_MCS5_LGI = 0x15
MCS5 with long GI, 52 Mbps for 20MHz, 108 Mbps for 40MHz
WIFI_PHY_RATE_MCS6_LGI = 0x16
MCS6 with long GI, 58.5 Mbps for 20MHz, 121.5 Mbps for 40MHz
WIFI_PHY_RATE_MCS7_LGI = 0x17
MCS7 with long GI, 65 Mbps for 20MHz, 135 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
MCS1 with short GI, 14.4 Mbps for 20MHz, 30 Mbps for 40MHz
WIFI_PHY_RATE_MCS2_SGI = 0x1A
MCS2 with short GI, 21.7 Mbps for 20MHz, 45 Mbps for 40MHz
WIFI_PHY_RATE_MCS3_SGI = 0x1B
MCS3 with short GI, 28.9 Mbps for 20MHz, 60 Mbps for 40MHz
WIFI_PHY_RATE_MCS4_SGI = 0x1C
MCS4 with short GI, 43.3 Mbps for 20MHz, 90 Mbps for 40MHz
WIFI_PHY_RATE_MCS5_SGI = 0x1D
MCS5 with short GI, 57.8 Mbps for 20MHz, 120 Mbps for 40MHz
WIFI_PHY_RATE_MCS6_SGI = 0x1E
MCS6 with short GI, 65 Mbps for 20MHz, 135 Mbps for 40MHz
WIFI_PHY_RATE_MCS7_SGI = 0x1F
MCS7 with short GI, 72.2 Mbps for 20MHz, 150 Mbps for 40MHz
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

Espressif Systems 558 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 559 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 560 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
uint8_t password[64]
Password of the AP. Null terminated string.
bool bssid_set
whether set MAC address of target AP or not.

Espressif Systems 561 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 562 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 563 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_OK : succeed
esp_err_t esp_now_get_version(uint32_t *version)
Get the version of ESPNOW.
Return
• ESP_OK : succeed
• 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.

Espressif Systems 564 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Return
• ESP_OK : succeed
• 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_OK : succeed
• ESP_ERR_ESPNOW_NOT_INIT : ESPNOW is not initialized
esp_err_t esp_now_register_send_cb(esp_now_send_cb_t cb)
Register callback function of sending ESPNOW data.
Return
• ESP_OK : succeed
• ESP_ERR_ESPNOW_NOT_INIT : ESPNOW is not initialized
• ESP_ERR_ESPNOW_INTERNAL : internal error
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_OK : succeed
• ESP_ERR_ESPNOW_NOT_INIT : ESPNOW is not initialized
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_OK : succeed
• ESP_ERR_ESPNOW_NOT_INIT : ESPNOW is not initialized
• ESP_ERR_ESPNOW_ARG : invalid argument
• ESP_ERR_ESPNOW_INTERNAL : internal error
• 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_OK : succeed
• ESP_ERR_ESPNOW_NOT_INIT : ESPNOW is not initialized
• ESP_ERR_ESPNOW_ARG : invalid argument
• 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

Espressif Systems 565 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

esp_err_t esp_now_del_peer(const uint8_t *peer_addr)

Delete a peer from peer list.
Return
• ESP_OK : succeed
• ESP_ERR_ESPNOW_NOT_INIT : ESPNOW is not initialized
• ESP_ERR_ESPNOW_ARG : invalid argument
• ESP_ERR_ESPNOW_NOT_FOUND : peer is not found
Parameters
• peer_addr: peer MAC address
esp_err_t esp_now_mod_peer(const esp_now_peer_info_t *peer)
Modify a peer.
Return
• ESP_OK : succeed
• ESP_ERR_ESPNOW_NOT_INIT : ESPNOW is not initialized
• ESP_ERR_ESPNOW_ARG : invalid argument
• ESP_ERR_ESPNOW_FULL : peer list is full
Parameters
• peer: peer information
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
• ESP_OK : succeed
• ESP_ERR_ESPNOW_NOT_INIT : ESPNOW is not initialized
• ESP_ERR_ESPNOW_ARG : invalid argument
• ESP_ERR_ESPNOW_NOT_FOUND : peer is not found
Parameters
• peer_addr: peer MAC address
• peer: peer information
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
• ESP_OK : succeed
• ESP_ERR_ESPNOW_NOT_INIT : ESPNOW is not initialized
• ESP_ERR_ESPNOW_ARG : invalid argument
• ESP_ERR_ESPNOW_NOT_FOUND : peer is not found
Parameters
• from_head: fetch from head of list or not
• peer: peer information
bool esp_now_is_peer_exist(const uint8_t *peer_addr)
Peer exists or not.
Return
• true : peer exists
• false : peer not exists
Parameters
• peer_addr: peer MAC address
esp_err_t esp_now_get_peer_num(esp_now_peer_num_t *num)
Get the number of peers.
Return
• ESP_OK : succeed
• ESP_ERR_ESPNOW_NOT_INIT : ESPNOW is not initialized
• ESP_ERR_ESPNOW_ARG : invalid argument
Parameters

Espressif Systems 566 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• 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
• ESP_OK : succeed
• ESP_ERR_ESPNOW_NOT_INIT : ESPNOW is not initialized
• ESP_ERR_ESPNOW_ARG : invalid argument
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
• ESP_OK : succeed
• ESP_ERR_ESPNOW_NOT_INIT : ESPNOW is not initialized
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.

Espressif Systems 567 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 568 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 569 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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));

Espressif Systems 570 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 571 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 572 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• 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();

Espressif Systems 573 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

esp_mesh_set_self_organized(1, 0);

...

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

esp_mesh_set_self_organized(1, 1);

...

//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.

Espressif Systems 574 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 575 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• 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
• ESP_ERR_MESH_ARGUMENT

Espressif Systems 576 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• ESP_ERR_MESH_NOT_START
• ESP_ERR_MESH_TIMEOUT
• ESP_ERR_MESH_DISCARD
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_ARGUMENT
• ESP_ERR_MESH_NOT_START
• ESP_ERR_MESH_TIMEOUT
• ESP_ERR_MESH_DISCARD
• 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.

Espressif Systems 577 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• 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_ARGUMENT
• 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
• ESP_ERR_MESH_ARGUMENT
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
• ESP_ERR_MESH_ARGUMENT
Parameters
• [in] router: pointer to router configuration
esp_err_t esp_mesh_get_router(mesh_router_t *router)
Get router configuration.
Return
• ESP_OK
• ESP_ERR_MESH_ARGUMENT
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

Espressif Systems 578 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

esp_err_t esp_mesh_get_id(mesh_addr_t *id)

Get mesh network ID.
Return
• ESP_OK
• ESP_ERR_MESH_ARGUMENT
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
• ESP_ERR_MESH_NOT_ALLOWED
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.
Attention This API shall be called before mesh is started.
Return
• ESP_OK
• ESP_ERR_MESH_ARGUMENT
• ESP_ERR_MESH_NOT_ALLOWED
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.
Attention This API shall be called before mesh is started.
Return
• ESP_OK
• ESP_ERR_MESH_ARGUMENT
• ESP_ERR_MESH_NOT_ALLOWED
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.
Attention This API shall be called before mesh is started.

Espressif Systems 579 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Return
• ESP_OK
• ESP_ERR_MESH_ARGUMENT
• ESP_ERR_MESH_NOT_ALLOWED
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
Attention This API shall be called before mesh is started.
Return
• ESP_OK
• ESP_ERR_MESH_ARGUMENT
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.
Attention This API shall be called after having received the event
MESH_EVENT_PARENT_CONNECTED.
Return layer value
esp_err_t esp_mesh_get_parent_bssid(mesh_addr_t *bssid)
Get the parent BSSID.
Attention This API shall be called after having received the event
MESH_EVENT_PARENT_CONNECTED.
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

Espressif Systems 580 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• 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.
Attention This API is only called by the root.
Return
• ESP_OK
• ESP_ERR_MESH_QUEUE_FULL
• ESP_ERR_MESH_DISCARD
• 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.
Attention This API shall be called before mesh is started.
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.

Espressif Systems 581 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• 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
• ESP_ERR_MESH_ARGUMENT
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

Espressif Systems 582 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
Attention This API shall be called before mesh is started.
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
• ESP_MESH_ERR_ARGUMENT
Parameters
• [in] addr: pointer to deleted group ID address
• [in] num: the number of group ID addresses
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
• ESP_MESH_ERR_ARGUMENT
Parameters

Espressif Systems 583 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• [out] addr: pointer to group ID addresses

• [in] num: the number of 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)
Attention This API shall be called before mesh is started.
Return
• ESP_OK
• ESP_ERR_MESH_NOT_ALLOWED
• ESP_MESH_ERR_ARGUMENT
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
• ESP_MESH_ERR_ARGUMENT
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
• ESP_MESH_ERR_ARGUMENT
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.

Espressif Systems 584 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 585 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• ESP_OK
• ESP_ERR_WIFI_NOT_INIT
• ESP_ERR_WIFI_ARG
• 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
• ESP_ERR_MESH_NOT_START
• ESP_ERR_MESH_ARGUMENT
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
• ESP_ERR_MESH_NOT_START
• ESP_ERR_MESH_ARGUMENT
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
Attention This API is only called by the root.
Return
• ESP_OK

Espressif Systems 586 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• ESP_ERR_WIFI_NOT_INIT
• ESP_ERR_WIFI_ARG
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
Attention This API shall be called before mesh is started.
Return
• ESP_OK
• ESP_MESH_ERR_ARGUMENT
• ESP_ERR_MESH_NOT_ALLOWED
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.
Attention This API shall be called before mesh is started.
Return
• ESP_OK
• ESP_ERR_WIFI_NOT_INIT
• ESP_ERR_MESH_NOT_ALLOWED
esp_err_t esp_mesh_disable_ps(void)
Disable mesh Power Save function.
Attention This API shall be called before mesh is started.
Return
• ESP_OK
• ESP_ERR_WIFI_NOT_INIT
• ESP_ERR_MESH_NOT_ALLOWED
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.

Espressif Systems 587 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 588 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• 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.

Espressif Systems 589 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 590 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 591 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 592 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 593 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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 .
uint8_t password[64]
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

uint8_t password[64]
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

Espressif Systems 594 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 595 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 596 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 597 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 598 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 599 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 600 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 601 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 602 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 603 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 604 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 605 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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:

Espressif Systems 606 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Fig. 5: Ethernet RMII Interface

Espressif Systems 607 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• 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.

Espressif Systems 608 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

eth_mac_config_t mac_config = ETH_MAC_DEFAULT_CONFIG(); // apply default MAC␣

,→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
eth_mac_config_t mac_config = ETH_MAC_DEFAULT_CONFIG(); // apply default MAC␣
,→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.

Espressif Systems 609 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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)

Espressif Systems 610 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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,
int32_t event_id, void *event_data)
{
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()

Espressif Systems 611 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

/* 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

Espressif Systems 612 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• [in] hdl: handle of Ethernet driver
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
• [in] hdl: handle of Ethernet driver
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] hdl: handle of Ethernet driver
• [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

Espressif Systems 613 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Parameters
• [in] hdl: handle of Ethernet driver
• [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
• [in] hdl: handle of Ethernet driver
• [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

Espressif Systems 614 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• 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] hdl: handle of Ethernet driver
• [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
• [in] hdl: handle of Ethernet driver
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
• [in] hdl: handle of Ethernet driver

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

Espressif Systems 615 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• [in] eth_handle: handle of Ethernet driver
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
• [in] eth_handle: handle of Ethernet driver
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] eth_handle: handle of Ethernet driver
• [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_INVALID_ARG: read PHY register failed because of invalid argument
• ESP_ERR_TIMEOUT: write PHY register failed because of timeout
• ESP_FAIL: write PHY register failed because some other error occurred
Parameters
• [in] eth_handle: handle of Ethernet driver
• [in] phy_addr: PHY chip address (0~31)
• [in] phy_reg: PHY register index code
• [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.

Espressif Systems 616 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_OK: read PHY register successfully
• ESP_FAIL: read PHY register failed because some error occurred
Parameters
• [in] eth: mediator of Ethernet driver
• [in] phy_addr: PHY Chip address (0~31)
• [in] phy_reg: PHY register index code
• [out] reg_value: PHY register value
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_OK: write PHY register successfully
• ESP_FAIL: write PHY register failed because some error occurred
Parameters
• [in] eth: mediator of Ethernet driver
• [in] phy_addr: PHY Chip address (0~31)
• [in] phy_reg: PHY register index code
• [in] reg_value: PHY register value
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] eth: mediator of Ethernet driver
• [in] buffer: packet buffer
• [in] length: length of the packet

Espressif Systems 617 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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] eth: mediator of Ethernet driver
• [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:

Espressif Systems 618 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 619 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• [in] mac: Ethernet MAC instance
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
• [in] mac: Ethernet MAC instance
esp_err_t (*start)(esp_eth_mac_t *mac)
Start Ethernet MAC.

Espressif Systems 620 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Return
• ESP_OK: start Ethernet MAC successfully
• ESP_FAIL: start Ethernet MAC failed because some other error occurred
Parameters
• [in] mac: Ethernet MAC instance
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
• [in] mac: Ethernet MAC instance
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] mac: Ethernet MAC instance
• [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
• [in] mac: Ethernet MAC instance
• [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_OK: read PHY register successfully
• ESP_ERR_INVALID_ARG: read PHY register failed because of invalid argument
• 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
• [in] mac: Ethernet MAC instance
• [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_mac_t *mac, uint32_t phy_addr, uint32_t phy_reg, uint32_t
reg_value)

Espressif Systems 621 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Write PHY register.

Return
• ESP_OK: write PHY register successfully
• 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
• [in] mac: Ethernet MAC instance
• [in] phy_addr: PHY chip address (0~31)
• [in] phy_reg: PHY register index code
• [in] reg_value: PHY register value
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] mac: Ethernet MAC instance
• [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
• [in] mac: Ethernet MAC instance
• [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] mac: Ethernet MAC instance
• [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

Espressif Systems 622 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Parameters
• [in] mac: Ethernet MAC instance
• [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] mac: Ethernet MAC instance
• [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] mac: Ethernet MAC instance
• [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] mac: Ethernet MAC instance
• [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
• [in] mac: Ethernet MAC instance
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

Espressif Systems 623 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 624 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• 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_lan87xx(const eth_phy_config_t *config)
Create a PHY instance of LAN87xx.
Return
• instance: create PHY instance successfully
• NULL: create PHY instance failed because some error occurred
Parameters
• [in] config: configuration of PHY
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
• 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_dp83848(const eth_phy_config_t *config)
Create a PHY instance of DP83848.
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_ksz8041(const eth_phy_config_t *config)
Create a PHY instance of KSZ8041.
Return
• instance: create PHY instance successfully
• NULL: create PHY instance failed because some error occurred
Parameters
• [in] config: configuration of PHY

Espressif Systems 625 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

esp_eth_phy_t *esp_eth_phy_new_ksz8081(const eth_phy_config_t *config)

Create a PHY instance of KSZ8081.
Return
• instance: create PHY instance successfully
• NULL: create PHY instance failed because some error occurred
Parameters
• [in] config: configuration of PHY
static esp_eth_phy_t *esp_eth_phy_new_ksz8091(const eth_phy_config_t *config)
Create a PHY instance of KSZ8091.
Return
• instance: create PHY instance successfully
• NULL: create PHY instance failed because some error occurred
Parameters
• [in] config: configuration of PHY

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
• [in] phy: Ethernet PHY instance
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
• [in] phy: Ethernet PHY instance
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
• [in] phy: Ethernet PHY instance

Espressif Systems 626 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• [in] phy: Ethernet PHY instance
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] phy: Ethernet PHY instance
• [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
• [in] phy: Ethernet PHY instance
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] phy: Ethernet PHY instance
• [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] phy: Ethernet PHY instance
• [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
• [in] phy: Ethernet PHY instance
• [out] addr: PHY chip address

Espressif Systems 627 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• [in] phy: Ethernet PHY instance
• [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] phy: Ethernet PHY instance
• [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] phy: Ethernet PHY instance
• [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] phy: Ethernet PHY instance
• [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
• [in] phy: Ethernet PHY instance
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)

Espressif Systems 628 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 629 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• [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.

Espressif Systems 630 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Note Thie function will not return unless error happens when running the OpenThread stack.
Return
• ESP_OK on success
• ESP_ERR_NO_MEM if allocation has failed
• ESP_FAIL on other failures
esp_err_t esp_openthread_deinit(void)
This function performs OpenThread stack and platform driver deinitialization.
Return
• ESP_OK on success
• 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.

Espressif Systems 631 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 632 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• ESP_OK on success
• ESP_ERR_NO_MEM if allocation has failed
• ESP_ERR_INVALID_STATE if already initialized
void esp_openthread_lock_deinit(void)
This function deinitializes the OpenThread API lock.

Espressif Systems 633 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_OK on success
• ESP_ERR_NOT_SUPPORTED if feature not supported
• ESP_ERR_INVALID_STATE if already initialized
• ESP_FIAL on other failures
esp_err_t esp_openthread_border_router_deinit(void)
Deinitializes the border router features of OpenThread.
Return

Espressif Systems 634 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• ESP_OK on success
• 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)

Espressif Systems 635 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

(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

Espressif Systems 636 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• 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_OK on success
• 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

Espressif Systems 637 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_OK on success
• 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_OK on success
• 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
• [in] esp_netif: Handle to esp-netif instance
• base:
• event_id:
• data:

Espressif Systems 638 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
Note This API can be directly used as event handler
Parameters
• [in] esp_netif: Handle to esp-netif instance
• 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.
Note This API can be directly used as event handler
Parameters
• [in] esp_netif: Handle to esp-netif instance
• 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.
Note This API can be directly used as event handler
Parameters
• [in] esp_netif: Handle to esp-netif instance
• 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.
Note This API can be directly used as event handler
Parameters
• [in] esp_netif: Handle to esp-netif instance
• 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.
Note This API can be directly used as event handler
Parameters
• [in] esp_netif: Handle to esp-netif instance
• 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.
Note This API can be directly used as event handler
Parameters
• [in] esp_netif: Handle to esp-netif instance
• base:
• event_id:
• data:

Espressif Systems 639 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
Note This API can be directly used as event handler
Parameters
• [in] esp_netif: Handle to esp-netif instance
• 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.
Note This API can be directly used as event handler
Parameters
• [in] esp_netif: Handle to esp-netif instance
• 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] esp_netif: Handle to esp-netif instance
• [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_OK - success
• ESP_ERR_ESP_NETIF_IF_NOT_READY - interface status error
• ESP_ERR_NOT_SUPPORTED - mac not supported on this interface
Parameters
• [in] esp_netif: Handle to esp-netif instance
• [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_OK - success
• ESP_ERR_ESP_NETIF_IF_NOT_READY - interface status error
• ESP_ERR_ESP_NETIF_INVALID_PARAMS - parameter error
Parameters
• [in] esp_netif: Handle to esp-netif instance
• [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_OK - success
• ESP_ERR_ESP_NETIF_IF_NOT_READY - interface status error

Espressif Systems 640 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• ESP_ERR_ESP_NETIF_INVALID_PARAMS - parameter error

Parameters
• [in] esp_netif: Handle to esp-netif instance
• [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
• [in] esp_netif: Handle to esp-netif instance
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
• [in] esp_netif: Handle to esp-netif instance
• [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
• ESP_ERR_ESP_NETIF_INVALID_PARAMS
Parameters
• [in] esp_netif: Handle to esp-netif instance
• [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_INVALID_PARAMS
• ESP_ERR_ESP_NETIF_DHCP_NOT_STOPPED If DHCP server or client is still running
Parameters
• [in] esp_netif: Handle to esp-netif instance
• [in] ip_info: IP information to set on the specified interface

Espressif Systems 641 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• ESP_ERR_ESP_NETIF_INVALID_PARAMS
Parameters
• [in] esp_netif: Handle to esp-netif instance
• [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
• [in] esp_netif: Handle to esp-netif instance
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
• ESP_ERR_ESP_NETIF_INVALID_PARAMS
Parameters
• [in] esp_netif: Handle to esp-netif instance
• [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_INVALID_PARAMS
• ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED
• ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED
Parameters
• [in] esp_netif: Handle to esp-netif instance
• [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

Espressif Systems 642 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• ESP_OK
• ESP_ERR_ESP_NETIF_INVALID_PARAMS
• ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED
• ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED
Parameters
• [in] esp_netif: Handle to esp-netif instance
• [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_INVALID_PARAMS
• ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED
• ESP_ERR_ESP_NETIF_DHCPC_START_FAILED
Parameters
• [in] esp_netif: Handle to esp-netif instance
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_INVALID_PARAMS
• ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED
• ESP_ERR_ESP_NETIF_IF_NOT_READY
Parameters
• [in] esp_netif: Handle to esp-netif instance
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
• [in] esp_netif: Handle to esp-netif instance
• [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
• [in] esp_netif: Handle to esp-netif instance
• [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
• ESP_ERR_ESP_NETIF_INVALID_PARAMS
• ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED
Parameters
• [in] esp_netif: Handle to esp-netif instance

Espressif Systems 643 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_INVALID_PARAMS
• ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED
• ESP_ERR_ESP_NETIF_IF_NOT_READY
Parameters
• [in] esp_netif: Handle to esp-netif instance
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_OK on success
• ESP_ERR_ESP_NETIF_INVALID_PARAMS invalid params
Parameters
• [in] esp_netif: Handle to esp-netif instance
• [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_OK on success
• ESP_ERR_ESP_NETIF_INVALID_PARAMS invalid params
Parameters
• [in] esp_netif: Handle to esp-netif instance
• [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
• ESP_ERR_ESP_NETIF_INVALID_PARAMS

Espressif Systems 644 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Parameters
• [in] esp_netif: Handle to esp-netif instance
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
• [in] esp_netif: Handle to esp-netif instance
• [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
• [in] esp_netif: Handle to esp-netif instance
• [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
• [in] esp_netif: Handle to esp-netif instance
• [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 )

Espressif Systems 645 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_OK on success
• 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_OK on success
• 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
• [in] esp_netif: Handle to esp-netif instance
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
• [in] esp_netif: Handle to esp-netif instance
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
• [in] esp_netif: Handle to esp-netif instance
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
• [in] esp_netif: Handle to esp-netif instance
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
• [in] esp_netif: Handle to esp-netif instance

Espressif Systems 646 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• [in] esp_netif: Handle to esp-netif instance
• 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
• [in] esp_netif: Handle to esp-netif instance
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_OK on success
• 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_OK on success
• 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.

Espressif Systems 647 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_OK on success, error returned from esp_event_handler_register if failed
esp_err_t esp_wifi_clear_default_wifi_driver_and_handlers(void *esp_netif)
Clears default wifi event handlers for supplied network interface.
Return
• ESP_OK on success, error returned from esp_event_handler_register if failed
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.
Return pointer to esp-netif instance
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!
Return pointer to esp-netif instance
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)

Espressif Systems 648 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 649 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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,
(continues on next page)

Espressif Systems 650 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

(continued from previous page)

.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
• [in] esp_netif: Handle to esp-netif instance
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] esp_netif: Handle to esp-netif instance
• [in] data: Data to be transmitted
• [in] len: Length of the data frame

Espressif Systems 651 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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] esp_netif: Handle to esp-netif instance
• [in] data: Data to be transmitted
• [in] len: Length of the data frame
• [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] esp_netif: Handle to esp-netif instance
• [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.

Espressif Systems 652 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Attenuation Measurable input voltage range

ADC_ATTEN_DB_0 100 mV ~ 950 mV
ADC_ATTEN_DB_2_5 100 mV ~ 1250 mV
ADC_ATTEN_DB_6 150 mV ~ 1750 mV
ADC_ATTEN_DB_11 150 mV ~ 2450 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().

Espressif Systems 653 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• 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.

Espressif Systems 654 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 655 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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");
(continues on next page)

Espressif Systems 656 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

(continued from previous page)

} 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 "driver/adc.h"
#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):

#include "driver/adc.h"

...

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.

Espressif Systems 657 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 658 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 659 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 660 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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 capture width is 10Bit.
ADC_WIDTH_BIT_11 = 2
ADC capture width is 11Bit.

Espressif Systems 661 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

ADC_WIDTH_BIT_12 = 3
ADC capture width is 12Bit.
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.

Espressif Systems 662 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Return
• ESP_OK success
• ESP_ERR_INVALID_ARG Parameter error
Parameters
• adc_unit: ADC unit index
• 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
• ESP_ERR_INVALID_ARG Parameter error
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

Espressif Systems 663 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

of ADC1.
Return
• ESP_OK success
• ESP_ERR_INVALID_ARG Parameter error
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
• ESP_ERR_INVALID_ARG Parameter error
Parameters
• adc_unit: ADC unit index
• 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
• ESP_ERR_INVALID_ARG Parameter error
Parameters
• adc_unit: ADC unit index
• 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.

Espressif Systems 664 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_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 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
• ESP_ERR_INVALID_ARG Parameter error
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
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.

Espressif Systems 665 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_OK if success
• 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.

Espressif Systems 666 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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 1 is GPIO37
ADC1_CHANNEL_2
ADC1 channel 2 is GPIO38
ADC1_CHANNEL_3
ADC1 channel 3 is GPIO39
ADC1_CHANNEL_4
ADC1 channel 4 is GPIO32
ADC1_CHANNEL_5
ADC1 channel 5 is GPIO33
ADC1_CHANNEL_6
ADC1 channel 6 is GPIO34
ADC1_CHANNEL_7
ADC1 channel 7 is GPIO35
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 1 is GPIO0 (ESP32), GPIO12 (ESP32-S2)
ADC2_CHANNEL_2
ADC2 channel 2 is GPIO2 (ESP32), GPIO13 (ESP32-S2)
ADC2_CHANNEL_3
ADC2 channel 3 is GPIO15 (ESP32), GPIO14 (ESP32-S2)

Espressif Systems 667 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

ADC2_CHANNEL_4
ADC2 channel 4 is GPIO13 (ESP32), GPIO15 (ESP32-S2)
ADC2_CHANNEL_5
ADC2 channel 5 is GPIO12 (ESP32), GPIO16 (ESP32-S2)
ADC2_CHANNEL_6
ADC2 channel 6 is GPIO14 (ESP32), GPIO17 (ESP32-S2)
ADC2_CHANNEL_7
ADC2 channel 7 is GPIO27 (ESP32), GPIO18 (ESP32-S2)
ADC2_CHANNEL_8
ADC2 channel 8 is GPIO25 (ESP32), GPIO19 (ESP32-S2)
ADC2_CHANNEL_9
ADC2 channel 9 is GPIO26 (ESP32), GPIO20 (ESP32-S2)
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.

Espressif Systems 668 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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

Espressif Systems 669 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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_CHANNEL_1_GPIO_NUM
ADC1_GPIO38_CHANNEL
ADC1_CHANNEL_2_GPIO_NUM
ADC1_GPIO39_CHANNEL
ADC1_CHANNEL_3_GPIO_NUM
ADC1_GPIO32_CHANNEL

Espressif Systems 670 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

ADC1_CHANNEL_4_GPIO_NUM
ADC1_GPIO33_CHANNEL
ADC1_CHANNEL_5_GPIO_NUM
ADC1_GPIO34_CHANNEL
ADC1_CHANNEL_6_GPIO_NUM
ADC1_GPIO35_CHANNEL
ADC1_CHANNEL_7_GPIO_NUM
ADC2_GPIO4_CHANNEL
ADC2_CHANNEL_0_GPIO_NUM
ADC2_GPIO0_CHANNEL
ADC2_CHANNEL_1_GPIO_NUM
ADC2_GPIO2_CHANNEL
ADC2_CHANNEL_2_GPIO_NUM
ADC2_GPIO15_CHANNEL
ADC2_CHANNEL_3_GPIO_NUM
ADC2_GPIO13_CHANNEL
ADC2_CHANNEL_4_GPIO_NUM
ADC2_GPIO12_CHANNEL
ADC2_CHANNEL_5_GPIO_NUM
ADC2_GPIO14_CHANNEL
ADC2_CHANNEL_6_GPIO_NUM
ADC2_GPIO27_CHANNEL
ADC2_CHANNEL_7_GPIO_NUM
ADC2_GPIO25_CHANNEL
ADC2_CHANNEL_8_GPIO_NUM
ADC2_GPIO26_CHANNEL
ADC2_CHANNEL_9_GPIO_NUM

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.

Espressif Systems 671 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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
• ESP_OK if success
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

Espressif Systems 672 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

Parameters
• channel: DAC channel
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
• channel: DAC channel
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.

Espressif Systems 673 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.
DAC_CW_SCALE_2 = 0x1
1/2.
DAC_CW_SCALE_4 = 0x2
1/4.
DAC_CW_SCALE_8 = 0x3
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.

Espressif Systems 674 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

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.

Espressif Systems 675 Release v5.0-dev-401-g451ce8a

Submit Document Feedback
Chapter 2. API Reference

• 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: peripheral