Download PDF

Page not Found - ESP32-S3 - — ESP-IDF Programming Guide latest documentation

PDF Viewing Options

Not Your Device? Search For Manuals or Datasheets below:


File Info : application/pdf, 2195 Pages, 21.11MB

Document DEVICE REPORTesp-idf-en-v5.0-dev-1424-g2467aa7f6c-esp32s3
ESP32-S3
ESP-IDF Programming Guide
Release v5.0-dev-1424-g2467aa7f6c Espressif Systems Jan 29, 2022

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-S3-DevKitC-1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.3.2 ESP32-S3-DevKitM-1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1.4 Installation Step by Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

1.4.1 Setting up Development Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

1.4.2 Creating Your First Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

1.5 Step 1. Install prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

1.5.1 Standard Setup of Toolchain for Windows . . . . . . . . . . . . . . . . . . . . . . . . . 16

1.5.2 Standard Setup of Toolchain for Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

1.5.3 Standard Setup of Toolchain for Mac OS . . . . . . . . . . . . . . . . . . . . . . . . . . 21

1.6 Step 2. Get ESP-IDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

1.6.1 Linux and macOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

1.6.2 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

1.7 Step 3. Set up the tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

1.7.1 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

1.7.2 Linux and macOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

1.7.3 Alternative File Downloads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

1.7.4 Customizing the tools installation path . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

1.8 Step 4. Set up the environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

1.8.1 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

1.8.2 Linux and macOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

1.9 Step 5. Start a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

1.9.1 Linux and macOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

1.9.2 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

1.10 Step 6. Connect Your Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

1.11 Step 7. Configure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

1.11.1 Linux and macOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

1.11.2 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

1.12 Step 8. Build the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

1.13 Step 9. Flash onto the Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

1.13.1 Encountered Issues While Flashing? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

1.13.2 Normal Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

1.14 Step 10. Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

1.15 Updating ESP-IDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

1.16 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

1.16.1 Establish Serial Connection with ESP32-S3 . . . . . . . . . . . . . . . . . . . . . . . . . 31

1.16.2 Build and Flash with Eclipse IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

1.16.3 Getting Started with VS Code IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

1.16.4 IDF Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

1.16.5 Customized Setup of Toolchain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

2 API Reference

49

i

2.1 Bluetooth API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 2.1.1 Controller && VHCI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 2.1.2 BT COMMON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 2.1.3 BT LE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 2.1.4 NimBLE-based host APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 2.1.5 ESP-BLE-MESH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
2.2 Networking APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 2.2.1 Wi-Fi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 2.2.2 Ethernet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452 2.2.3 Thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474 2.2.4 ESP-NETIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479 2.2.5 IP Network Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496 2.2.6 Application Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
2.3 Peripherals API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500 2.3.1 Analog to Digital Converter (ADC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500 2.3.2 GPIO & RTC GPIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520 2.3.3 General Purpose Timer (GPTimer) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 2.3.4 Dedicated GPIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547 2.3.5 Hash-based Message Authentication Code (HMAC) . . . . . . . . . . . . . . . . . . . . 551 2.3.6 Digital Signature (DS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554 2.3.7 Inter-Integrated Circuit (I2C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 2.3.8 Inter-IC Sound (I2S) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574 2.3.9 LCD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589 2.3.10 LED Control (LEDC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602 2.3.11 Motor Control Pulse Width Modulator (MCPWM) . . . . . . . . . . . . . . . . . . . . . 616 2.3.12 Pulse Counter (PCNT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640 2.3.13 Remote Control (RMT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649 2.3.14 SD Pull-up Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669 2.3.15 SDMMC Host Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670 2.3.16 SD SPI Host Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675 2.3.17 Sigma-delta Modulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680 2.3.18 SPI Master Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683 2.3.19 SPI Slave Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701 2.3.20 Touch Sensor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707 2.3.21 Two-Wire Automotive Interface (TWAI) . . . . . . . . . . . . . . . . . . . . . . . . . . 728 2.3.22 Universal Asynchronous Receiver/Transmitter (UART) . . . . . . . . . . . . . . . . . . 744 2.3.23 USB Device Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766 2.3.24 USB Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773
2.4 Application Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801 2.4.1 ASIO port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801 2.4.2 ESP-MQTT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802 2.4.3 ESP-TLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813 2.4.4 OpenSSL-APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824 2.4.5 ESP HTTP Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 851 2.4.6 HTTP Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864 2.4.7 HTTPS server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886 2.4.8 ICMP Echo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 888 2.4.9 ESP Local Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 893 2.4.10 mDNS Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 901 2.4.11 ESP-Modbus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915 2.4.12 ESP WebSocket Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937 2.4.13 ESP Serial Slave Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 944 2.4.14 ESP x509 Certificate Bundle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 957 2.4.15 IP Network Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959
2.5 Provisioning API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959 2.5.1 Protocol Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959 2.5.2 Unified Provisioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969 2.5.3 Wi-Fi Provisioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 972
ii

2.6 Storage API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 989 2.6.1 FAT Filesystem Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 989 2.6.2 Manufacturing Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995 2.6.3 Non-volatile storage library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999 2.6.4 NVS Partition Generator Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1019 2.6.5 SD/SDIO/MMC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1025 2.6.6 SPI Flash API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1035 2.6.7 SPIFFS Filesystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1060 2.6.8 Virtual filesystem component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1063 2.6.9 Wear Levelling API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1076
2.7 System API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1080 2.7.1 App Image Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1080 2.7.2 Application Level Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1085 2.7.3 The Async memcpy API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1089 2.7.4 Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1092 2.7.5 eFuse Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1100 2.7.6 Error Codes and Helper Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1120 2.7.7 ESP HTTPS OTA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1122 2.7.8 POSIX Threads Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1126 2.7.9 Event Loop Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1130 2.7.10 FreeRTOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1146 2.7.11 FreeRTOS Additions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1250 2.7.12 Heap Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1267 2.7.13 Heap Memory Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1278 2.7.14 High Resolution Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1288 2.7.15 Inter-Processor Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1294 2.7.16 Call function with external stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1299 2.7.17 Interrupt allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1300 2.7.18 Logging library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1306 2.7.19 Miscellaneous System APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1311 2.7.20 Over The Air Updates (OTA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1318 2.7.21 Performance Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1328 2.7.22 Power Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1332 2.7.23 Random Number Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1338 2.7.24 Sleep Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1340 2.7.25 Watchdogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1349 2.7.26 System Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1352 2.7.27 Internal and Unstable APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1357
2.8 API Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1358 2.8.1 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1358 2.8.2 Configuration structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1358 2.8.3 Private APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1359 2.8.4 Components in example projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1359 2.8.5 API Stability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1360
2.9 Project Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1360 2.9.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1361 2.9.2 Project Configuration Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1361 2.9.3 Using sdkconfig.defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1361 2.9.4 Kconfig Formatting Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1361 2.9.5 Backward Compatibility of Kconfig Options . . . . . . . . . . . . . . . . . . . . . . . . 1362 2.9.6 Configuration Options Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1362
2.10 Error Codes Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1608

3 ESP32-S3 Hardware Reference

1615

3.1 Chip Series Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1615

3.1.1 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1617

4 API Guides

1619

iii

4.1 Application Level Tracing library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1619 4.1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1619 4.1.2 Modes of Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1619 4.1.3 Configuration Options and Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . 1620 4.1.4 How to use this library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1621
4.2 Application Startup Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1629 4.2.1 First stage bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1629 4.2.2 Second stage bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1630 4.2.3 Application startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1630
4.3 BluFi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1632 4.3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1632 4.3.2 The BluFi Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1632 4.3.3 The Flow Chart of BluFi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1633 4.3.4 The Frame Formats Defined in BluFi . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1634 4.3.5 The Security Implementation of ESP32-S3 . . . . . . . . . . . . . . . . . . . . . . . . . 1638 4.3.6 GATT Related Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1639
4.4 Bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1639 4.4.1 Bootloader compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1640 4.4.2 Log Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1640 4.4.3 Factory reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1640 4.4.4 Boot from Test Firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1641 4.4.5 Rollback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1641 4.4.6 Watchdog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1641 4.4.7 Bootloader Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1642 4.4.8 Fast boot from Deep Sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1642 4.4.9 Custom bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1642
4.5 Build System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1642 4.5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1642 4.5.2 Using the Build System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1643 4.5.3 Example Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1647 4.5.4 Project CMakeLists File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1648 4.5.5 Component CMakeLists Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1649 4.5.6 Component Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1651 4.5.7 Preprocessor Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1651 4.5.8 Component Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1652 4.5.9 Overriding Parts of the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1655 4.5.10 Configuration-Only Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1656 4.5.11 Debugging CMake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1656 4.5.12 Example Component CMakeLists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1657 4.5.13 Custom sdkconfig defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1661 4.5.14 Flash arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1661 4.5.15 Building the Bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1661 4.5.16 Selecting the Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1662 4.5.17 Writing Pure CMake Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1662 4.5.18 Using Third-Party CMake Projects with Components . . . . . . . . . . . . . . . . . . . 1663 4.5.19 Using Prebuilt Libraries with Components . . . . . . . . . . . . . . . . . . . . . . . . . 1663 4.5.20 Using ESP-IDF in Custom CMake Projects . . . . . . . . . . . . . . . . . . . . . . . . . 1664 4.5.21 ESP-IDF CMake Build System API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1664 4.5.22 File Globbing & Incremental Builds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1668 4.5.23 Build System Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1669 4.5.24 Build System Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1669 4.5.25 Migrating from ESP-IDF GNU Make System . . . . . . . . . . . . . . . . . . . . . . . 1671
4.6 Deep Sleep Wake Stubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1672 4.6.1 Rules for Wake Stubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1672 4.6.2 Implementing A Stub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1673 4.6.3 Loading Code Into RTC Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1673 4.6.4 Loading Data Into RTC Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1673 4.6.5 CRC Check For Wake Stubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1674
iv

4.7 Device Firmware Upgrade through USB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1674 4.7.1 Building the DFU Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1675 4.7.2 Flashing the Chip with the DFU Image . . . . . . . . . . . . . . . . . . . . . . . . . . . 1675
4.8 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1676 4.8.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1676 4.8.2 Error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1677 4.8.3 Converting error codes to error messages . . . . . . . . . . . . . . . . . . . . . . . . . . 1677 4.8.4 ESP_ERROR_CHECK macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1677 4.8.5 ESP_ERROR_CHECK_WITHOUT_ABORT macro . . . . . . . . . . . . . . . . . . . . . 1678 4.8.6 ESP_RETURN_ON_ERROR macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1678 4.8.7 ESP_GOTO_ON_ERROR macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1678 4.8.8 ESP_RETURN_ON_FALSE macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1678 4.8.9 ESP_GOTO_ON_FALSE macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1678 4.8.10 CHECK MACROS Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1678 4.8.11 Error handling patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1679 4.8.12 C++ Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1680
4.9 ESP-BLE-MESH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1680 4.9.1 Getting Started with ESP-BLE-MESH . . . . . . . . . . . . . . . . . . . . . . . . . . . 1680 4.9.2 ESP-BLE-MESH Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1686 4.9.3 ESP-BLE-MESH Demo Videos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1688 4.9.4 ESP-BLE-MESH FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1688 4.9.5 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1688
4.10 ESP-WIFI-MESH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1717 4.10.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1717 4.10.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1717 4.10.3 ESP-WIFI-MESH Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1718 4.10.4 Building a Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1724 4.10.5 Managing a Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1729 4.10.6 Data Transmission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1732 4.10.7 Channel Switching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1734 4.10.8 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1737 4.10.9 Further Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1738
4.11 Core Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1738 4.11.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1738 4.11.2 Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1738 4.11.3 Save core dump to flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1739 4.11.4 Print core dump to UART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1739 4.11.5 ROM Functions in Backtraces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1740 4.11.6 Dumping variables on demand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1740 4.11.7 Running espcoredump.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1740
4.12 Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1741 4.12.1 Wi-Fi, Ethernet, and IP Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1741 4.12.2 Mesh Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1744 4.12.3 Bluetooth Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1745
4.13 Support for External RAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1745 4.13.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1745 4.13.2 Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1745 4.13.3 Configuring External RAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1746 4.13.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1747 4.13.5 Failure to initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1747 4.13.6 Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1747
4.14 Fatal Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1747 4.14.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1747 4.14.2 Panic Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1748 4.14.3 Register Dump and Backtrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1748 4.14.4 GDB Stub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1750 4.14.5 Guru Meditation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1751 4.14.6 Other Fatal Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1753
v

4.15 Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1755 4.15.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1755 4.15.2 Relevant eFuses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1756 4.15.3 Flash Encryption Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1757 4.15.4 Flash Encryption Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1757 4.15.5 Possible Failures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1763 4.15.6 ESP32-S3 Flash Encryption Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1765 4.15.7 Reading and Writing Data in Encrypted Flash . . . . . . . . . . . . . . . . . . . . . . . 1765 4.15.8 Updating Encrypted Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1766 4.15.9 Disabling Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1766 4.15.10 Key Points About Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1767 4.15.11 Limitations of Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1767 4.15.12 Flash Encryption and Secure Boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1767 4.15.13 Advanced Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1767 4.15.14 External RAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1769 4.15.15 Technical Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1769
4.16 SPI Flash and External SPI RAM Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 1769 4.16.1 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1770 4.16.2 How to configure Flash and PSRAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1770 4.16.3 All Supported Modes and Speeds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1771 4.16.4 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1772
4.17 ESP-IDF FreeRTOS (SMP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1772 4.17.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1773 4.17.2 Symmetric Multiprocessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1773 4.17.3 Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1774 4.17.4 SMP Scheduler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1775 4.17.5 Critical Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1779 4.17.6 Misc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1780
4.18 Hardware Abstraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1781 4.18.1 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1781 4.18.2 LL (Low Level) Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1782 4.18.3 HAL (Hardware Abstraction Layer) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1783
4.19 High-Level Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1784 4.19.1 Interrupt Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1784 4.19.2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1784
4.20 JTAG Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1785 4.20.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1785 4.20.2 How it Works? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1786 4.20.3 Selecting JTAG Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1786 4.20.4 Setup of OpenOCD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1787 4.20.5 Configuring ESP32-S3 Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1787 4.20.6 Launching Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1790 4.20.7 Debugging Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1790 4.20.8 Building OpenOCD from Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1790 4.20.9 Tips and Quirks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1795 4.20.10 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1799
4.21 Linker Script Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1824 4.21.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1824 4.21.2 Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1824 4.21.3 Linker Script Generation Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1827
4.22 Memory Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1833 4.22.1 DRAM (Data RAM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1834 4.22.2 IRAM (Instruction RAM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1834 4.22.3 IROM (code executed from flash) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1835 4.22.4 RTC FAST memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1835 4.22.5 DROM (data stored in flash) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1835 4.22.6 RTC Slow memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1836 4.22.7 DMA Capable Requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1836
vi

4.22.8 DMA Buffer in the stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1836 4.23 lwIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1837
4.23.1 Supported APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1837 4.23.2 BSD Sockets API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1837 4.23.3 Netconn API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1841 4.23.4 lwIP FreeRTOS Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1841 4.23.5 IPv6 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1842 4.23.6 esp-lwip custom modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1842 4.23.7 Performance Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1843 4.24 OpenThread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1845 4.24.1 Mode of the OpenThread stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1845 4.24.2 How To Write an OpenThread Application . . . . . . . . . . . . . . . . . . . . . . . . . 1845 4.24.3 The OpenThread border router . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1846 4.25 Partition Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1846 4.25.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1847 4.25.2 Built-in Partition Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1847 4.25.3 Creating Custom Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1847 4.25.4 Generating Binary Partition Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1850 4.25.5 Partition Size Checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1850 4.25.6 Flashing the partition table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1850 4.25.7 Partition Tool (parttool.py) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1851 4.26 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1852 4.26.1 How to Optimize Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1852 4.26.2 Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1852 4.27 RF calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1868 4.27.1 Partial calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1868 4.27.2 Full calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1869 4.27.3 No calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1869 4.27.4 PHY initialization data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1869 4.28 Secure Boot V2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1869 4.28.1 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1869 4.28.2 Advantages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1870 4.28.3 Secure Boot V2 Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1870 4.28.4 Signature Block Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1871 4.28.5 Verifying a Signature Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1871 4.28.6 Verifying an Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1871 4.28.7 Bootloader Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1871 4.28.8 eFuse usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1872 4.28.9 How To Enable Secure Boot V2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1872 4.28.10 Restrictions after Secure Boot is enabled . . . . . . . . . . . . . . . . . . . . . . . . . . 1873 4.28.11 Generating Secure Boot Signing Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1873 4.28.12 Remote Signing of Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1873 4.28.13 Secure Boot Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1874 4.28.14 Key Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1874 4.28.15 Multiple Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1874 4.28.16 Key Revocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1874 4.28.17 Technical Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1875 4.28.18 Secure Boot & Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1875 4.28.19 Signed App Verification Without Hardware Secure Boot . . . . . . . . . . . . . . . . . . 1875 4.28.20 Advanced Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1876 4.29 Thread Local Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1876 4.29.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1876 4.29.2 FreeRTOS Native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1877 4.29.3 Pthread API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1877 4.29.4 C11 Standard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1877 4.30 Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1877 4.30.1 Downloadable Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1877 4.30.2 IDF Docker Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1886
vii

4.30.3 IDF Windows Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1888 4.30.4 IDF Component Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1889 4.30.5 IDF Clang Tidy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1890 4.31 ULP Coprocessor programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1891 4.31.1 Programming ULP FSM coprocessor using C macros (legacy) . . . . . . . . . . . . . . . 1891 4.31.2 Installing the Toolchain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1896 4.31.3 Compiling the ULP Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1896 4.31.4 Accessing the ULP Program Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 1897 4.31.5 Starting the ULP Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1898 4.32 ULP-RISC-V Coprocessor programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1899 4.32.1 Installing the ULP-RISC-V Toolchain . . . . . . . . . . . . . . . . . . . . . . . . . . . 1899 4.32.2 Compiling the ULP-RISC-V Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1899 4.32.3 Accessing the ULP-RISC-V Program Variables . . . . . . . . . . . . . . . . . . . . . . 1900 4.32.4 Starting the ULP-RISC-V Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1900 4.32.5 ULP-RISC-V Program Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1901 4.33 Unit Testing in ESP32-S3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1902 4.33.1 Normal Test Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1902 4.33.2 Multi-device Test Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1902 4.33.3 Multi-stage Test Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1903 4.33.4 Tests For Different Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1904 4.33.5 Building Unit Test App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1905 4.33.6 Running Unit Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1905 4.33.7 Timing Code with Cache Compensated Timer . . . . . . . . . . . . . . . . . . . . . . . 1906 4.33.8 Mocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1907 4.34 Unit Testing on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1909 4.34.1 Embedded Software Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1909 4.34.2 IDF Unit Tests on Linux Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1909 4.35 USB OTG Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1910 4.35.1 Hardware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1910 4.35.2 Software Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1911 4.35.3 Uploading the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1911 4.35.4 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1912 4.36 USB Serial/JTAG Controller Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1912 4.36.1 Hardware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1912 4.36.2 Software Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1913 4.36.3 Uploading the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1913 4.36.4 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1913 4.37 Wi-Fi Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1913 4.37.1 ESP32-S3 Wi-Fi Feature List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1914 4.37.2 How To Write a Wi-Fi Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1914 4.37.3 ESP32-S3 Wi-Fi API Error Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1915 4.37.4 ESP32-S3 Wi-Fi API Parameter Initialization . . . . . . . . . . . . . . . . . . . . . . . 1915 4.37.5 ESP32-S3 Wi-Fi Programming Model . . . . . . . . . . . . . . . . . . . . . . . . . . . 1915 4.37.6 ESP32-S3 Wi-Fi Event Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1915 4.37.7 ESP32-S3 Wi-Fi Station General Scenario . . . . . . . . . . . . . . . . . . . . . . . . . 1918 4.37.8 ESP32-S3 Wi-Fi AP General Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . 1921 4.37.9 ESP32-S3 Wi-Fi Scan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1921 4.37.10 ESP32-S3 Wi-Fi Station Connecting Scenario . . . . . . . . . . . . . . . . . . . . . . . 1928 4.37.11 ESP32-S3 Wi-Fi Station Connecting When Multiple APs Are Found . . . . . . . . . . . 1932 4.37.12 Wi-Fi Reconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1932 4.37.13 Wi-Fi Beacon Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1932 4.37.14 ESP32-S3 Wi-Fi Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1932 4.37.15 Wi-Fi Easy ConnectTM (DPP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1937 4.37.16 Wireless Network Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1938 4.37.17 Radio Resource Measurement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1938 4.37.18 ESP32-S3 Wi-Fi Power-saving Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1938 4.37.19 ESP32-S3 Wi-Fi Throughput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1939 4.37.20 Wi-Fi 80211 Packet Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1939
viii

4.37.21 Wi-Fi Sniffer Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1941 4.37.22 Wi-Fi Multiple Antennas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1942 4.37.23 Wi-Fi Channel State Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1943 4.37.24 Wi-Fi Channel State Information Configure . . . . . . . . . . . . . . . . . . . . . . . . . 1944 4.37.25 Wi-Fi HT20/40 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1945 4.37.26 Wi-Fi QoS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1945 4.37.27 Wi-Fi AMSDU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1946 4.37.28 Wi-Fi Fragment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1946 4.37.29 WPS Enrollee . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1946 4.37.30 Wi-Fi Buffer Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1946 4.37.31 How to improve Wi-Fi performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1947 4.37.32 Wi-Fi Menuconfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1951 4.37.33 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1954 4.38 Wi-Fi Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1958 4.38.1 ESP32-S3 Wi-Fi Security Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1960 4.38.2 Protected Management Frames (PMF) . . . . . . . . . . . . . . . . . . . . . . . . . . . 1960 4.38.3 WPA3-Personal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1961

5 ESP-IDF 5.0 Migration Guides

1963

5.1 Migrate Build System to ESP-IDF 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1963

5.1.1 Migrating from make to cmake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1963

5.1.2 Update fragment file grammar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1963

5.2 Migrate Windows Environment to ESP-IDF 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . 1963

5.3 Migrate Ethernet Drivers to ESP-IDF 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1963

5.3.1 esp_eth_ioctl() API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1963

5.3.2 KSZ8041/81 and LAN8720 Driver Update . . . . . . . . . . . . . . . . . . . . . . . . . 1964

5.3.3 ESP NETIF Glue Event Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1964

5.4 Migrate FreeRTOS to ESP-IDF 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1964

5.4.1 Tasks Snapshot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1964

5.4.2 FreeRTOS Asserts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1964

5.5 Migrate Peripherals to ESP-IDF 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1964

5.5.1 Peripheral Clock Gating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1964

5.5.2 SPI Flash Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1964

5.5.3 ADC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1965

5.5.4 GPIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1965

5.5.5 Timer Group Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1965

5.6 Removed or deprecated components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1966

5.7 Migrate System to ESP-IDF 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1966

5.7.1 Inter-Processor Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1966

5.7.2 ESP Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1966

5.7.3 Cache Error Interrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1967

5.7.4 Brownout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1967

5.7.5 Trax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1967

5.7.6 ROM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1967

5.7.7 ESP HW Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1967

5.7.8 SOC dependency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1967

5.7.9 APP Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1967

5.8 Migrate Tools to ESP-IDF 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1967

5.8.1 IDF Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1967

6 Libraries and Frameworks

1969

6.1 Cloud Frameworks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1969

6.1.1 ESP RainMaker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1969

6.1.2 AWS IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1969

6.1.3 Azure IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1969

6.1.4 Google IoT Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1969

6.1.5 Aliyun IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1969

6.1.6 Joylink IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1969

ix

6.1.7 Tencent IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1970 6.1.8 Tencentyun IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1970 6.1.9 Baidu IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1970 6.2 Espressifns Frameworks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1970 6.2.1 Espressif Audio Development Framework . . . . . . . . . . . . . . . . . . . . . . . . . 1970 6.2.2 ESP-CSI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1970 6.2.3 Espressif DSP Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1970 6.2.4 ESP-WIFI-MESH Development Framework . . . . . . . . . . . . . . . . . . . . . . . . 1971 6.2.5 ESP-WHO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1971 6.2.6 ESP RainMaker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1971 6.2.7 ESP-IoT-Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1971 6.2.8 ESP-Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1971

7 Contributions Guide

1973

7.1 How to Contribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1973

7.2 Before Contributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1973

7.3 Pull Request Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1973

7.4 Legal Part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1974

7.5 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1974

7.5.1 Espressif IoT Development Framework Style Guide . . . . . . . . . . . . . . . . . . . . 1974

7.5.2 Install pre-commit Hook for ESP-IDF Project . . . . . . . . . . . . . . . . . . . . . . . 1981

7.5.3 Documenting Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1982

7.5.4 Creating Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1987

7.5.5 API Documentation Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1988

7.5.6 Contributor Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1990

7.5.7 Copyright Header Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1992

8 ESP-IDF Versions

1995

8.1 Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1995

8.2 Which Version Should I Start With? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1995

8.3 Versioning Scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1995

8.4 Support Periods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1996

8.5 Checking the Current Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1997

8.6 Git Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1998

8.7 Updating ESP-IDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1998

8.7.1 Updating to Stable Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1999

8.7.2 Updating to a Pre-Release Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1999

8.7.3 Updating to Master Branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1999

8.7.4 Updating to a Release Branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2000

9 Resources

2001

9.1 PlatformIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2001

9.1.1 What is PlatformIO? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2001

9.1.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2001

9.1.3 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2002

9.1.4 Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2002

9.1.5 Project Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2002

9.1.6 Next Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2002

9.2 Useful Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2002

10 Copyrights and Licenses

2003

10.1 Software Copyrights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2003

10.1.1 Firmware Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2003

10.1.2 Build Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2004

10.1.3 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2004

10.2 ROM Source Code Copyrights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2004

10.3 Xtensa libhal MIT License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2004

10.4 TinyBasic Plus MIT License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2005

10.5 TJpgDec License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2005

x

11 About 12 Switch Between Languages Index Index

2007 2009 2011 2011

xi

xii

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

Get Started

API Reference

H/W Reference

API Guides

Contribute

Resources

Espressif Systems

1

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Table of contents

Espressif Systems

2

Release v5.0-dev-1424-g2467aa7f6c

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-S3 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-S3 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-S3 is a system on a chip that integrates the following features: · Wi-Fi (2.4 GHz band) · Bluetooth Low Energy · Dual high performance Xtensa® 32-bit LX7 CPU cores · Ultra Low Power co-processor running either RISC-V or FSM core · Multiple peripherals · Built-in security hardware · USB OTG interface · USB Serial/JTAG Controller
Powered by 40 nm technology, ESP32-S3 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-S3 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-S3 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-S3
3

Chapter 1. Get Started
· Build tools - CMake and Ninja to build a full Application for ESP32-S3 · ESP-IDF that essentially contains API (software libraries and source code) for ESP32-S3 and scripts to operate
the Toolchain 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-S3

1.3 Development Board Overviews
If you have one of ESP32-S3 development boards listed below, you can click on the link to learn more about its hardware.

1.3.1 ESP32-S3-DevKitC-1
This user guide will help you get started with ESP32-S3-DevKitC-1 and will also provide more in-depth information.
The ESP32-S3-DevKitC-1 is an entry-level development board equipped with either ESP32-S3-WROOM-1 or ESP32-S3-WROOM-1U, a general-purpose Wi-Fi + Bluetooth® LE MCU module that integrates complete WiFi and Bluetooth LE functions.
Most of the I/O pins on the module are broken out to the pin headers on both sides of this board for easy interfacing. Developers can either connect peripherals with jumper wires or mount ESP32-S3-DevKitC-1 on a breadboard.
The document consists of the following major sections:

Espressif Systems

4

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started
Fig. 2: ESP32-S3-DevKitC-1 with ESP32-S3-WROOM-1 Module
· Getting started: Overview of the board and hardware/software setup instructions to get started. · Hardware Reference: More detailed information about the boardns hardware. · Hardware Revision Details: Revision history, known issues, and links to user guides for previous versions (if
any) of the board. · Related Documents: Links to related documentation.
Getting Started This section provides a brief introduction of ESP32-S3-DevKitC-1, instructions on how to do the initial hardware setup and how to flash firmware onto it.

Fig. 3: ESP32-S3-DevKitC-1 - front Description of Components The key components of the board are described in a counter-clockwise direction.

Espressif Systems

5

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started

Key Component ESP32-S3-WROOM-1/1U
5 V to 3.3 V LDO Pin Headers
USB-to-UART Port
Boot Button Reset Button ESP32-S3 USB Port
USB-to-UART Bridge RGB LED 3.3 V Power On LED

Description ESP32-S3-WROOM-1 and ESP32-S3-WROOM-1U are two powerful, generic Wi-Fi + Bluetooth LE MCU modules that have a rich set of peripherals. They provide acceleration for neural network computing and signal processing workloads. ESP32-S3-WROOM-1 comes with a PCB antenna. ESP32-S3WROOM-1U comes with an external antenna connector. Power regulator that converts a 5 V supply into a 3.3 V output. All available GPIO pins (except for the SPI bus for flash) are broken out to the pin headers on the board for easy interfacing and programming. For details, please see Header Block. A Micro-USB port used for power supply to the board, for flashing applications to the chip, as well as for communication with the chip via the on-board USBto-UART bridge. Download button. Holding down Boot and then pressing Reset initiates Firmware Download mode for downloading firmware through the serial port. Press this button to restart the system. ESP32-S3 full-speed USB OTG interface, compliant with the USB 1.1 specification. The interface is used for power supply to the board, for flashing applications to the chip, for communication with the chip using USB 1.1 protocols, as well as for JTAG debugging. Single USB-to-UART bridge chip provides transfer rates up to 3 Mbps. Addressable RGB LED, driven by GPIO48. Turns on when the USB power is connected to the board.

Start Application Development Before powering up your board, please make sure that it is in good condition with no obvious signs of damage.
Required Hardware · ESP32-S3-DevKitC-1 · USB 2.0 cable (Standard-A to Micro-B) · Computer running Windows, Linux, or macOS
Note: Be sure to use an appropriate USB cable. Some cables are for charging only and do not provide the needed data lines nor work for programming the boards.

Hardware Setup Connect the board with the computer using USB-to-UART Port. Connection using ESP32-S3 USB Port is not fully implemented in software. In subsequent steps, USB-to-UART Port will be used by default.

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

Contents and Packaging

Retail orders If you order a few samples, each board comes in an individual package in either antistatic 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.

Espressif Systems

6

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started
Hardware Reference Block Diagram The block diagram below shows the components of ESP32-S3-DevKitC-1 and their interconnections.

Fig. 4: ESP32-S3-DevKitC-1 (click to enlarge)
Power Supply Options There are three mutually exclusive ways to provide power to the board: · USB-to-UART Port and ESP32-S3 USB Port (either one or both), default power supply (recommended) · 5V and G (GND) pins · 3V3 and G (GND) pins
Header Block The two tables below provide the Name and Function of the pins on both sides of the board (J1 and J3). The pin names are shown in ESP32-S3-DevKitC-1 - front. The numbering is the same as in the Board Schematic (PDF).

Espressif Systems

7

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started

J1

No. Name Type1 Function

1 3V3 P

3.3 V power supply

2 3V3 P

3.3 V power supply

3 RST I

EN

44

I/O/T RTC_GPIO4, GPIO4, TOUCH4, ADC1_CH3

55

I/O/T RTC_GPIO5, GPIO5, TOUCH5, ADC1_CH4

66

I/O/T RTC_GPIO6, GPIO6, TOUCH6, ADC1_CH5

77

I/O/T RTC_GPIO7, GPIO7, TOUCH7, ADC1_CH6

8 15

I/O/T RTC_GPIO15, GPIO15, U0RTS, ADC2_CH4, XTAL_32K_P

9 16

I/O/T RTC_GPIO16, GPIO16, U0CTS, ADC2_CH5, XTAL_32K_N

10 17

I/O/T RTC_GPIO17, GPIO17, U1TXD, ADC2_CH6

11 18

I/O/T RTC_GPIO18, GPIO18, U1RXD, ADC2_CH7, CLK_OUT3

12 8

I/O/T RTC_GPIO8, GPIO8, TOUCH8, ADC1_CH7, SUBSPICS1

13 3

I/O/T RTC_GPIO3, GPIO3, TOUCH3, ADC1_CH2

14 46

I/O/T GPIO46

15 9

I/O/T RTC_GPIO9, GPIO9, TOUCH9, ADC1_CH8, FSPIHD, SUBSPIHD

16 10

I/O/T RTC_GPIO10, GPIO10, TOUCH10, ADC1_CH9, FSPICS0, FSPIIO4, SUBSPICS0

17 11

I/O/T RTC_GPIO11, GPIO11, TOUCH11, ADC2_CH0, FSPID, FSPIIO5, SUBSPID

18 12

I/O/T RTC_GPIO12, GPIO12, TOUCH12, ADC2_CH1, FSPICLK, FSPIIO6, SUBSPI-

CLK

19 13

I/O/T RTC_GPIO13, GPIO13, TOUCH13, ADC2_CH2, FSPIQ, FSPIIO7, SUBSPIQ

20 14

I/O/T RTC_GPIO14, GPIO14, TOUCH14, ADC2_CH3, FSPIWP, FSPIDQS, SUBSPIWP

21 5V

P

5 V power supply

22 G

G

Ground

J3 No. Name Type Function

1G

G

Ground

2 TX I/O/T U0TXD, GPIO43, CLK_OUT1

3 RX I/O/T U0RXD, GPIO44, CLK_OUT2

41

I/O/T RTC_GPIO1, GPIO1, TOUCH1, ADC1_CH0

52

I/O/T RTC_GPIO2, GPIO2, TOUCH2, ADC1_CH1

6 42

I/O/T MTMS, GPIO42

7 41

I/O/T MTDI, GPIO41, CLK_OUT1

8 40

I/O/T MTDO, GPIO40, CLK_OUT2

9 39

I/O/T MTCK, GPIO39, CLK_OUT3, SUBSPICS1

10 38

I/O/T GPIO38, FSPIWP, SUBSPIWP

11 37

I/O/T SPIDQS, GPIO37, FSPIQ, SUBSPIQ

12 36

I/O/T SPIIO7, GPIO36, FSPICLK, SUBSPICLK

13 35

I/O/T SPIIO6, GPIO35, FSPID, SUBSPID

14 0

I/O/T RTC_GPIO0, GPIO0

15 45

I/O/T GPIO45

16 48

I/O/T GPIO48, SPICLK_N, SUBSPICLK_N_DIFF, RGB LED

17 47

I/O/T GPIO47, SPICLK_P, SUBSPICLK_P_DIFF

18 21

I/O/T RTC_GPIO21, GPIO21

19 20

I/O/T RTC_GPIO20, GPIO20, U1CTS, ADC2_CH9, CLK_OUT1, USB_D+

20 19

I/O/T RTC_GPIO19, GPIO19, U1RTS, ADC2_CH8, CLK_OUT2, USB_D-

21 G

G

Ground

22 G

G

Ground

For description of function names, please refer to Chip Datasheet (PDF).

P: Power supply; I: Input; O: Output; T: High impedance.

Espressif Systems

8

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started

Fig. 5: ESP32-S3-DevKitC-1 Pin Layout (click to enlarge)
Pin Layout
Hardware Revision Details
This is the first revision of this board released.
Related Documents
· ESP32-S3 Datasheet (PDF) · ESP32-S3-WROOM-1 & ESP32-S3-WROOM-1U Datasheet (PDF) · ESP32-S3-DevKitC-1 Schematic (PDF) · ESP32-S3-DevKitC-1 PCB layout (PDF) · ESP32-S3-DevKitC-1 Dimensions (PDF) · ESP32-S3-DevKitC-1 Dimensions source file (DXF) - You can view it with Autodesk Viewer online For further design documentation for the board, please contact us at [email protected].
1.3.2 ESP32-S3-DevKitM-1
This user guide will help you get started with ESP32-S3-DevKitM-1 and will also provide more in-depth information. The ESP32-S3-DevKitM-1 is an entry-level development board equipped with either ESP32-S3-MINI-1 or ESP32S3-MINI-1U, a module named for its small size. This board integrates complete Wi-Fi and Bluetooth Low Energy functions. Most of the I/O pins on the module are broken out to the pin headers on both sides of this board for easy interfacing. Developers can either connect peripherals with jumper wires or mount ESP32-S3-DevKitM-1 on a breadboard.

Espressif Systems

9

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started

Fig. 6: ESP32-S3-DevKitM-1 with ESP32-S3-MINI-1 Module

Espressif Systems

10

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started
The document consists of the following major sections: · Getting Started: Overview of the board and hardware/software setup instructions to get started. · Hardware Reference: More detailed information about the boardns hardware. · Related Documents: Links to related documentation.
Getting Started
This section provides a brief introduction of ESP32-S3-DevKitM-1, instructions on how to do the initial hardware setup and how to flash firmware onto it.

Fig. 7: ESP32-S3-DevKitM-1 - front
Description of Components The key components of the board are described in a counter-clockwise direction, starting from the ESP32-S3-MINI-1/1U module.

Espressif Systems

11

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started

Key Component ESP32-S3-MINI-1/1U
5 V to 3.3 V LDO Pin Headers
USB-to-UART Port
Boot Button Reset Button ESP32-S3 USB Port
USB-to-UART Bridge RGB LED 3.3 V Power On LED

Description ESP32-S3-MINI-1 and ESP32-S3-MINI-1U are two general-purpose Wi-Fi and Bluetooth LE combo modules that have a rich set of peripherals. ESP32S3-MINI-1 comes with a PCB antenna. ESP32-S3-MINI-1U comes with an external antenna connector. At the core of the modules is ESP32-S3FN8, a chip equipped with an 8 MB flash. Since flash is packaged in the chip, rather than integrated into the module, ESP32-S3-MINI-1/1U has a smaller package size. Power regulator that converts a 5 V supply into a 3.3 V output. All available GPIO pins (except for the SPI bus for flash) are broken out to the pin headers on the board for easy interfacing and programming. For details, please see Header Block. A Micro-USB port used for power supply to the board, for flashing applications to the chip, as well as for communication with the chip via the on-board USBto-UART bridge. Download button. Holding down Boot and then pressing Reset initiates Firmware Download mode for downloading firmware through the serial port. Press this button to restart ESP32-S3. ESP32-S3 full-speed USB OTG interface, compliant with the USB 1.1 specification. The interface is used for power supply to the board, for flashing applications to the chip, for communication with the chip using USB 1.1 protocols, as well as for JTAG debugging. Single USB-to-UART bridge chip provides transfer rates up to 3 Mbps. Addressable RGB LED, driven by GPIO48. Turns on when the USB power is connected to the board.

Start Application Development Before powering up your board, please make sure that it is in good condition with no obvious signs of damage.
Required Hardware · ESP32-S3-DevKitM-1 · USB 2.0 cable (Standard-A to Micro-B) · Computer running Windows, Linux, or macOS
Note: Be sure to use an appropriate USB cable. Some cables are for charging only and do not provide the needed data lines nor work for programming the boards.

Hardware Setup Connect the board with the computer using USB-to-UART Port. Connection using ESP32-S3 USB Port is not fully implemented in software. In subsequent steps, USB-to-UART Port will be used by default.
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 board.
Contents and Packaging
Retail Orders If you order a few samples, each board comes in an individual package in either antistatic bag or any packaging depending on your retailer. For retail orders, please go to https://www.espressif.com/en/company/contact/buy-a-sample.

Espressif Systems

12

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started
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 components of ESP32-S3-DevKitM-1 and their interconnections.

Fig. 8: ESP32-S3-DevKitM-1 (click to enlarge)
Power Supply Options There are three mutually exclusive ways to provide power to the board: · USB-to-UART Port and ESP32-S3 USB Port (either one or both), default power supply (recommended) · 5V and G (GND) pins · 3V3 and G (GND) pins
Header Block The two tables below provide the Name and Function of the pins on both sides of the board (J1 and J3). The pin names are shown in ESP32-S3-DevKitM-1 - front. The numbering is the same as in the Board Schematic (PDF).

Espressif Systems

13

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started

J1

No. Name Type1 Function

1 3V3 P

3.3 V power supply

20

I/O/T RTC_GPIO0, GPIO0

31

I/O/T RTC_GPIO1, GPIO1, TOUCH1, ADC1_CH0

42

I/O/T RTC_GPIO2, GPIO2, TOUCH2, ADC1_CH1

53

I/O/T RTC_GPIO3, GPIO3, TOUCH3, ADC1_CH2

64

I/O/T RTC_GPIO4, GPIO4, TOUCH4, ADC1_CH3

75

I/O/T RTC_GPIO5, GPIO5, TOUCH5, ADC1_CH4

86

I/O/T RTC_GPIO6, GPIO6, TOUCH6, ADC1_CH5

97

I/O/T RTC_GPIO7, GPIO7, TOUCH7, ADC1_CH6

10 8

I/O/T RTC_GPIO8, GPIO8, TOUCH8, ADC1_CH7, SUBSPICS1

11 9

I/O/T RTC_GPIO9, GPIO9, TOUCH9, ADC1_CH8, FSPIHD, SUBSPIHD

12 10

I/O/T RTC_GPIO10, GPIO10, TOUCH10, ADC1_CH9, FSPICS0, FSPIIO4, SUBSPICS0

13 11

I/O/T RTC_GPIO11, GPIO11, TOUCH11, ADC2_CH0, FSPID, FSPIIO5, SUBSPID

14 12

I/O/T RTC_GPIO12, GPIO12, TOUCH12, ADC2_CH1, FSPICLK, FSPIIO6, SUBSPI-

CLK

15 13

I/O/T RTC_GPIO13, GPIO13, TOUCH13, ADC2_CH2, FSPIQ, FSPIIO7, SUBSPIQ

16 14

I/O/T RTC_GPIO14, GPIO14, TOUCH14, ADC2_CH3, FSPIWP, FSPIDQS, SUBSPIWP

17 15

I/O/T RTC_GPIO15, GPIO15, U0RTS, ADC2_CH4, XTAL_32K_P

18 16

I/O/T RTC_GPIO16, GPIO16, U0CTS, ADC2_CH5, XTAL_32K_N

19 17

I/O/T RTC_GPIO17, GPIO17, U1TXD, ADC2_CH6

20 18

I/O/T RTC_GPIO18, GPIO18, U1RXD, ADC2_CH7, CLK_OUT3

21 5V

P

5 V power supply

22 G

G

Ground

J3 No. Name Type Function

1G

G

Ground

2 RST I

EN

3 46

I/O/T GPIO46

4 45

I/O/T GPIO45

5 RX I/O/T U0RXD, GPIO44, CLK_OUT2

6 TX I/O/T U0TXD, GPIO43, CLK_OUT1

7 42

I/O/T MTMS, GPIO42

8 41

I/O/T MTDI, GPIO41, CLK_OUT1

9 40

I/O/T MTDO, GPIO40, CLK_OUT2

10 39

I/O/T MTCK, GPIO39, CLK_OUT3, SUBSPICS1

11 38

I/O/T GPIO38, FSPIWP, SUBSPIWP

12 37

I/O/T SPIDQS, GPIO37, FSPIQ, SUBSPIQ

13 36

I/O/T SPIIO7, GPIO36, FSPICLK, SUBSPICLK

14 35

I/O/T SPIIO6, GPIO35, FSPID, SUBSPID

15 34

I/O/T SPIIO5, GPIO34, FSPICS0, SUBSPICS0

16 33

I/O/T SPIIO4, GPIO33, FSPIHD, SUBSPIHD

17 26

I/O/T SPICS1, GPIO26

18 21

I/O/T RTC_GPIO21, GPIO21

19 20

I/O/T RTC_GPIO20, GPIO20, U1CTS, ADC2_CH9, CLK_OUT1, USB_D+

20 19

I/O/T RTC_GPIO19, GPIO19, U1RTS, ADC2_CH8, CLK_OUT2, USB_D-

21 48

I/O/T SPICLK_N, GPIO48, SUBSPICLK_N_DIFF, RGB LED

22 47

I/O/T SPICLK_P, GPIO47, SUBSPICLK_P_DIFF

For description of function names, please refer to ESP32-S3 Datasheet (PDF).

P: Power supply; I: Input; O: Output; T: High impedance.

Espressif Systems

14

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started

Fig. 9: ESP32-S3-DevKitM-1 Pin Layout (click to enlarge)
Pin Layout
Hardware Revision Details
This is the first revision of this board released.
Related Documents
· ESP32-S3 Datasheet (PDF) · ESP32-S3-MINI-1 & ESP32-S3-MINI-1U Datasheet (PDF) · ESP32-S3-DevKitM-1 Schematic (PDF) · ESP32-S3-DevKitM-1 PCB layout (PDF) · ESP32-S3-DevKitM-1 Dimensions (PDF) · ESP32-S3-DevKitM-1 Dimensions source file (DXF) - You can view it with Autodesk Viewer online For further design documentation for the board, please contact us at [email protected].

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

Espressif Systems

15

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started
· 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 prerequisite tools include Python, Git, cross-compilers, CMake and Ninja build tools. For this Getting Started wenre 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 (nonASCII) unless the operating system is configured with oUnicode UTF-8psupport. System Administrator can enable the support via Control Panel - Change date, time, or number formats - Administrative tab - Change system locale - check the option oBeta: Use Unicode UTF-8 for worldwide language supportp - Ok and reboot the computer.
ESP-IDF Tools Installer
The easiest way to install ESP-IDFns prerequisites is to download one of ESP-IDF Tools Installers from this URL: https://dl.espressif.com/dl/esp-idf/?idf=4.4
What is the usecase for Online and Offline Installer Online Installer is very small and allows the installation of all available releases of ESP-IDF. The installer will download only necessary dependencies including Git For Windows during the installation process. The installer stores downloaded files in the cache directory %userprofile%\. espressif Offline Installer does not require any network connection. The installer contains all required dependencies including Git For Windows .

Espressif Systems

16

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started
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 %userprofile%\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 ESPIDF 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. 10: Completing the ESP-IDF Tools Setup Wizard with Run ESP-IDF PowerShell Environment
Run ESP-IDF Command Prompt (cmd.exe):
Using the Command Prompt
For the remaining Getting Started steps, wenre 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.

Espressif Systems

17

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started Fig. 11: ESP-IDF PowerShell

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

Espressif Systems

18

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started

Fig. 13: ESP-IDF Command Prompt

Espressif Systems

19

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started
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. Proceed 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 ESPIDF 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 oESP-IDF Command Promptp. 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 wasnnt started using that shortcut. If this is the case, follow the instructions below to add ESP-IDF tools to PATH. In the command prompt where you need to use ESP-IDF, change to the directory where ESP-IDF is installed, then execute export.bat: cd %userprofile%\esp\esp-idf export.bat
Alternatively in the Powershell where you need to use ESP-IDF, change to the directory where ESP-IDF is installed, then execute export.ps1: cd ~/esp/esp-idf export.ps1
When this is done, the tools will be available in this command prompt.

Espressif Systems

20

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started
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 python3setuptools 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 obackportsprepository, or installing of a ocmake3ppackage rather than ocmakep. · 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-S3. This can be solved by adding the current user to the dialout group.
Python compatibility
ESP-IDF supports Python 3.6 or newer. It is recommended to upgrade your operating system to a recent version satisfying this requirement. Other options include the installation of Python from sources or the use of a Python version management system such as pyenv.
Next Steps
To carry on with development environment setup, proceed to Step 2. Get ESP-IDF.
1.5.3 Standard Setup of Toolchain for Mac OS
Install Prerequisites
ESP-IDF will use the version of Python installed by default on macOS. · install pip:

Espressif Systems

21

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

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

22

Release v5.0-dev-1424-g2467aa7f6c

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-S3, 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 instructions 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

23

Release v5.0-dev-1424-g2467aa7f6c

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 esp32s3
or with Windows PowerShell cd ~/esp/esp-idf ./install.ps1 esp32s3
1.7.2 Linux and macOS
cd ~/esp/esp-idf ./install.sh esp32s3
or with Fish shell cd ~/esp/esp-idf ./install.fish esp32s3
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 Espressifns download server for GitHub asset downloads.
Note: This setting only controls individual tools downloaded from GitHub releases, it doesnnt 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 download 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

24

Release v5.0-dev-1424-g2467aa7f6c

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 oESP-IDF Command Promptpshortcut 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 shellns 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 shellns 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

25

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started
1.9 Step 5. Start a Project
Now you are ready to prepare your application for ESP32-S3. 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-S3 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-S3 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-S3 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 esp32s3 idf.py menuconfig

Espressif Systems

26

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started
1.11.2 Windows
cd %userprofile%\esp\hello_world idf.py set-target esp32s3 idf.py menuconfig
Setting the target with idf.py set-target esp32s3 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. 14: 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 ohello_wordp. This example will run with default configuration.
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, partition table, and application binaries.
$ idf.py build Running cmake in directory /path/to/hello_world/build Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"... Warn about uninitialized values. -- Found Git: /usr/bin/git (found version "2.17.0") -- Building empty aws_iot component due to configuration
(continues on next page)

Espressif Systems

27

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started

-- Component names: ... -- Component paths: ...

(continued from previous page)

... (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-S3 board by running: idf.py -p PORT [-b BAUD] flash
Replace PORT with your ESP32-S3 boardns 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 oFailed to connectp, 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-S3 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-S3). The DTR and RTS control lines are in turn connected to GPIO0 and CHIP_PU (EN) pins of ESP32-S3, thus changes in the voltage levels of DTR and RTS will boot ESP32-S3 into Firmware Download mode. As an example, check the schematic for the ESP32 DevKitC development board.
In general, you should have no problems with the official esp-idf development boards. However, esptool.py is not able to reset your hardware automatically in the following cases:
· Your hardware does not have the DTR and RTS lines connected to GPIO0 and CHIP_PU · The DTR and RTS lines are configured differently · There are no such serial control lines at all
Depending on the kind of hardware you have, it may also be possible to manually put your ESP32-S3 board into Firmware Download mode (reset).

Espressif Systems

28

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started
· 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 esp32s3 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_ reset write_flash --flash_mode dio --flash_freq 80m --flash_size 2MB 0x0 bootloader/bootloader.bin 0x10000 hello_world.bin 0x8000 partition_table/ partition-table.bin esptool.py v3.2-dev Serial port /dev/ttyUSB0 Connecting.... Chip is ESP32-S3 Features: WiFi, BLE Crystal is 40MHz MAC: 7c:df:a1:e0:00:64 Uploading stub... Running stub... Stub running... Changing baud rate to 460800 Changed. Configuring flash size... Flash will be erased from 0x00000000 to 0x00004fff... Flash will be erased from 0x00010000 to 0x00039fff... Flash will be erased from 0x00008000 to 0x00008fff... Compressed 18896 bytes to 11758... Writing at 0x00000000... (100 %) Wrote 18896 bytes (11758 compressed) at 0x00000000 in 0.5 seconds (effective 279.9 kbit/s)... Hash of data verified. Compressed 168208 bytes to 88178... Writing at 0x00010000... (16 %) Writing at 0x0001a80f... (33 %) Writing at 0x000201f1... (50 %) Writing at 0x00025dcf... (66 %) Writing at 0x0002d0be... (83 %) Writing at 0x00036c07... (100 %) Wrote 168208 bytes (88178 compressed) at 0x00010000 in 2.4 seconds (effective 569. 2 kbit/s)... Hash of data verified. Compressed 3072 bytes to 103... Writing at 0x00008000... (100 %) Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (effective 478.9 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 theohello_worldpapplication.
If yound like to use the Eclipse or VS Code IDE instead of running idf.py, check out the Eclipse guide, VS Code guide.

Espressif Systems

29

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started
1.14 Step 10. Monitor
To check ifohello_worldpis 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 oHello world!pprinted out by the application.
... Hello world! Restarting in 10 seconds... This is esp32s3 chip with 2 CPU core(s), This is esp32s3 chip with 2 CPU core(s), WiFi/BLE, silicon revision 0, 2MB external flash Minimum free heap size: 390684 bytes Restarting in 9 seconds... Restarting in 8 seconds... Restarting in 7 seconds...
To exit IDF monitor use the shortcut Ctrl+].
Note: You can combine building, flashing and monitoring into one step by running:
idf.py -p PORT flash monitor
Note: If a board with Octal Flash resets before the second-stage bootloader, please refer to Octal Flash Error Handling
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.
Thatns all that you need to get started with ESP32-S3! Now you are ready to try some other examples, or go straight to developing your own applications.
Important: Some of examples do not support ESP32-S3 because required hardware is not included in ESP32-S3 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-S3 target, or the table does not exist at all, the example will work on ESP32-S3.

Espressif Systems

30

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started
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-S3
This section provides guidance how to establish serial connection between ESP32-S3 and PC.
Connect ESP32-S3 to PC
Connect the ESP32-S3 board to the PC using the USB cable. If device driver does not install automatically, identify USB to serial converter chip on your ESP32-S3 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-S3 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-S3 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
Check port on Linux and macOS
To check the device name for the serial port of your ESP32-S3 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.*

Espressif Systems

31

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started

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

Espressif Systems

32

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started

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

Espressif Systems

33

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started

Note: macOS users: if you donnt 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 oSystem Software from developer lpwhere 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-S3.
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-S3. The log contents will depend on application loaded to ESP32-S3, 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.

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 USBtoUART7

/dev/cu.SLAB_

· 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-S3, see Example Output. To exit the screen session type Ctrl-A + \ .

Espressif Systems

34

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started

Fig. 17: Setting Serial Communication in PuTTY on Windows

Espressif Systems

35

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started

Fig. 18: Setting Serial Communication in PuTTY on Linux

Espressif Systems

36

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started
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-S3 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-S3.
Note: For some serial port wiring configurations, the serial RTS & DTR pins need to be disabled in the terminal program before the ESP32-S3 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-S3 development, then you can continue with Step 7. Configure.
1.16.2 Build and Flash with Eclipse IDE
ESP-IDF V4.0 has a new CMake-based build system as the default build system. There is a new ESP-IDF Eclipse Plugin that works with the CMake-based build system. Please refer to Espressif IDF Eclipse Plugins IDF for further instructions.
Note: In Espressif IDF Eclipse Plugins, though screenshots are captured from macOS, installation instructions are applicable for Windows, Linux and macOS.
1.16.3 Getting Started with VS Code IDE
We have official support for VS Code and we aim to provide complete end to end support for all actions related to ESP-IDF namely build, flash, monitor, debug, tracing, core-dump, System Trace Viewer, etc.

Espressif Systems

37

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started
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 devicens serial port. It also provides some IDF-specific features. This tool can be launched from an IDF project by running idf.py monitor.
Keyboard Shortcuts
For easy interaction with IDF Monitor, use the keyboard shortcuts given in the table.

Espressif Systems

38

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started

Keyboard Shortcut Ctrl+] Ctrl+T
· Ctrl+T
· Ctrl+]
· Ctrl+P
· Ctrl+R
· Ctrl+F
· Ctrl+A (or A)
· Ctrl+Y
· Ctrl+L
· Ctrl+I (or I)
· Ctrl+H (or H)

Action

Description

Exit the program Menu escape key Send the menu character itself to remote

Press and follow it by one of the keys given below.

Send the exit character itself to remote

Reset target into bootloader to pause app via RTS line
Reset target board via RTS

Resets the target, into bootloader via the RTS line (if connected), so that the board runs nothing. Useful when you need to wait for another device to startup. Resets the target board and re-starts the application via the RTS line (if connected).

Build and flash the project

Build and flash the app only

Stop/resume log output printing on screen

Stop/resume log output saved to file

Stop/resume timestamps

printing

Pauses idf_monitor to run the project flash target, then resumes 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. Pauses idf_monitor to run the app-flash target, then resumes idf_monitor. Similar to the flash target, but only the main app is built and re-flashed. Target encrypted-app-flash is run if idf_monitor was started with argument -E. Discards all incoming serial data while activated. Allows to quickly pause and examine log output without quitting the monitor. Creates a file in the project directory and the output is written to that file until this is disabled with the same keyboard shortcut (or IDF Monitor exits). IDF Monitor can print a timestamp in the beginning of each line. The timestamp format can be changed by the --timestampformat command line argument.

Display all keyboard shortcuts

· Ctrl+X (or X)

Exit the program

Ctrl+C

Interrupt running application

Pauses IDF monitor and run GDB project debugger to debug the application at runtime. This requires :ref:CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME option to be enabled.

Any keys pressed, other than Ctrl-] and Ctrl-T, will be sent through the serial port.

IDF-specific features

Automatic Address Decoding Whenever ESP-IDF outputs a hexadecimal code address of the form 0x4_______, IDF Monitor uses addr2line to look up the location in the source code and find the function name.
If an ESP-IDF app crashes and panics, a register dump and backtrace is produced, such as the following:

Guru Meditation Error of type StoreProhibited occurred on core unhandled. Register dump:

0. Exception was (continues on next page)

Espressif Systems

39

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started

PC

: 0x400f360d

0x3ffb7e00

A2

: 0x3ffb136c

0x00000000

A6

: 0x00000000

0x3ffb7dd0

A10

: 0x00000003

0x3ffba6d0

A14

: 0x00000047

0x0000001d

EXCVADDR: 0x00000000

0x00000000

PS A3 A7 A11 A15 LBEG

: 0x00060330 A0 : 0x00000005 A4 : 0x00000080 A8 : 0x00060f23 A12 : 0x0000000f SAR : 0x4000c46c LEND

(continued from previous page)

: 0x800dbf56 A1

:

: 0x00000000 A5

:

: 0x00000000 A9

:

: 0x00060f20 A13

:

: 0x00000019 EXCCAUSE:

: 0x4000c477 LCOUNT :

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/esp32s3/./cpu_start.c:254

To decode each address, IDF Monitor runs the following command in the background: xtensa-esp32s3-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS

Note: Set environment variable ESP_MONITOR_DECODE to 0 or call idf_monitor.py with specific command line option: idf_monitor.py --disable-address-decoding to disable address decoding.

Espressif Systems

40

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started

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 CONFIG_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-esp32s3-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 specifying a <log_level> or using * defaults to Verbose level.
Note: Use primary logging to disable at compilation the outputs you do not need through the logging library. Output filtering with IDF monitor is a secondary solution which can be useful for adjusting the filtering options without recompiling the application.
Your app tags must not contain spaces, asterisks *, or colons : to be compatible with the output filtering feature.
If the last line of the output in your app is not followed by a carriage return, the output filtering might get confused, i.e., the monitor starts to print the line and later finds out that the line should not have been written. This is a known issue and can be avoided by always adding a carriage return (especially when no output follows immediately afterwards).
Examples Of Filtering Rules:
· * can be used to match any tags. However, the string PRINT_FILTER="*:I tag1:E" with regards to tag1 prints errors only, because the rule for tag1 has a higher priority over the rule for *.
· The default (empty) rule is equivalent to *:V because matching every tag at the Verbose level or lower means matching everything.
· "*:N" suppresses not only the outputs from logging functions, but also the prints made by printf, etc. To avoid this, use *:E or a higher verbosity level.
· Rules "tag1:V", "tag1:v", "tag1:", "tag1:*", and "tag1" are equivalent. · Rule "tag1:W tag1:E" is equivalent to "tag1:E" because any consequent occurrence of the same tag
name overwrites the previous one. · Rule "tag1:I tag2:W" only prints tag1 at the Info verbosity level or lower and tag2 at the Warning
verbosity level or lower. · Rule "tag1:I tag2:W tag3:N" is essentially equivalent to the previous one because tag3:N specifies
that tag3 should not be printed.

Espressif Systems

41

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started
· 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 oidf.pypexits, it might stall for up to 30 seconds before IDF Monitor resumes. · When ogdbpis 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 cannt think of a reason why you need to build it yourself, then probably itns 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 donnt trust binaries downloaded from the Internet In any case, here are the instructions to compile the toolchain yourself.

Espressif Systems

42

Release v5.0-dev-1424-g2467aa7f6c

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 (obleeding edgep) version of ESP-IDF. It is fully functional and updated on weekly basis with the most recent features and bugfixes.
Note: GitHubns oDownload zip filepfeature 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 oAdd CMake to the system PATH for all userspor oAdd CMake to the system PATH for the current userp.
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

43

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started
Python Download the latest Python for Windows installer, and run it. The oCustomisepstep of the Python installer gives a list of options. The last option is oAdd python.exe to Pathp . Change this option to select oWill be installedp. 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-esp32s3-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-esp32s3-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 python3pip 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

44

Release v5.0-dev-1424-g2467aa7f6c

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 obackportsprepository, or installing of a ocmake3ppackage rather than ocmakep.
Compile the Toolchain from Source · Install dependencies: ­ CentOS 7: sudo yum install gawk gperf grep gettext ncurses-devel python3 python3devel automake bison flex texinfo help2man libtool make ­ Ubuntu pre-16.04: sudo apt-get install gawk gperf grep gettext libncurses-dev python pythondev 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 pythondev 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
Build the toolchain: ./ct-ng xtensa-esp32s3-elf ./ct-ng build chmod -R u+w builds/xtensa-esp32s3-elf
Toolchain will be built in ~/esp/crosstool-NG/builds/xtensa-esp32s3-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-esp32s3-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 xtensaesp32s3-elf available for all terminal sessions, add the following line to your ~/.profile file: export PATH="$HOME/esp/xtensa-esp32s3-elf/bin:$PATH"

Espressif Systems

45

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started
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 toolchainns path at the beginning of displayed string: $ printenv PATH /home/user-name/esp/xtensa-esp32s3-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

46

Release v5.0-dev-1424-g2467aa7f6c

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-esp32s3-elf ./ct-ng build chmod -R u+w builds/xtensa-esp32s3-elf
Toolchain will be built in ~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32s3-elf. To use it, you need to add ~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32s3-elf/bin to PATH environment variable.
Next Steps To carry on with development environment setup, proceed to Step 2. Get ESP-IDF.

Espressif Systems

47

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 1. Get Started

Espressif Systems

48

Release v5.0-dev-1424-g2467aa7f6c

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.

49

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, therens a mode and some connection configuration inocfgpto 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 ocfgpof 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

50

Release v5.0-dev-1424-g2467aa7f6c

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(). Additionally, 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

51

Release v5.0-dev-1424-g2467aa7f6c

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 operationp. 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 CONFIG_CTRL_BTDM_MODEM_SLEEP is set and oORIG modepis 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 oesp_bt_controller_wakeup_requestp.
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

52

Release v5.0-dev-1424-g2467aa7f6c

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

53

Release v5.0-dev-1424-g2467aa7f6c

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

54

Release v5.0-dev-1424-g2467aa7f6c

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

55

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
enum esp_power_level_t Bluetooth TX power level(index), itns 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

Espressif Systems

56

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

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

Espressif Systems

57

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

58

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_BT_STATUS_AUTH_FAILURE ESP_BT_STATUS_RMT_DEV_DOWN = 10 ESP_BT_STATUS_AUTH_REJECTED ESP_BT_STATUS_INVALID_STATIC_RAND_ADDR ESP_BT_STATUS_PENDING ESP_BT_STATUS_UNACCEPT_CONN_INTERVAL ESP_BT_STATUS_PARAM_OUT_OF_RANGE ESP_BT_STATUS_TIMEOUT ESP_BT_STATUS_PEER_LE_DATA_LEN_UNSUPPORTED ESP_BT_STATUS_CONTROL_LE_DATA_LEN_UNSUPPORTED ESP_BT_STATUS_ERR_ILLEGAL_PARAMETER_FMT ESP_BT_STATUS_MEMORY_FULL = 20 ESP_BT_STATUS_EIR_TOO_LARGE enum esp_bt_dev_type_t Bluetooth device type. Values: ESP_BT_DEVICE_TYPE_BREDR = 0x01 ESP_BT_DEVICE_TYPE_BLE = 0x02 ESP_BT_DEVICE_TYPE_DUMO = 0x03 enum esp_ble_addr_type_t BLE device address type. Values: BLE_ADDR_TYPE_PUBLIC = 0x00 BLE_ADDR_TYPE_RANDOM = 0x01 BLE_ADDR_TYPE_RPA_PUBLIC = 0x02 BLE_ADDR_TYPE_RPA_RANDOM = 0x03 enum esp_ble_wl_addr_type_t white list address type Values: BLE_WL_ADDR_TYPE_PUBLIC = 0x00 BLE_WL_ADDR_TYPE_RANDOM = 0x01

BT MAIN API Overview Instructions

Application Example Instructions

API Reference

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

Espressif Systems

59

Release v5.0-dev-1424-g2467aa7f6c

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

60

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Functions const uint8_t *esp_bt_dev_get_address(void)
Get bluetooth device address. Must use after oesp_bluedroid_enablep.
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

61

Release v5.0-dev-1424-g2467aa7f6c

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 tx_data_length)
This function is to set maximum LE data packet size.

remote_device,

uint16_t

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

62

Release v5.0-dev-1424-g2467aa7f6c

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

63

Release v5.0-dev-1424-g2467aa7f6c

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

64

Release v5.0-dev-1424-g2467aa7f6c

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'.
(continues on next page)

Espressif Systems

65

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)

To accept only `secure connection mode`, it is necessary do as following:

1. Set bit `ESP_LE_AUTH_REQ_SC_ONLY` (`param_type` is `ESP_BLE_SM_AUTHEN_REQ_MODE`), bit `ESP_LE_AUTH_BOND` and bit `ESP_LE_AUTH_REQ_MITM` is optional as required.

type` is

2. Set to `ESP_BLE_ONLY_ACCEPT_SPECIFIED_AUTH_ENABLE` (`param_ `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

Espressif Systems

66

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· [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
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 connections, 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.

Espressif Systems

67

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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.

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

Espressif Systems

68

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

69

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

70

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

This function is used to set aux connection parameters.

*phy_coded_conn_params)

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.

Espressif Systems

71

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· [in] phy_1m_conn_params: : Scan connectable advertisements on the LE 1M PHY. Connection parameters for the LE 1M PHY are provided.
· [in] phy_2m_conn_params: : Connection parameters for the LE 2M PHY are provided. · [in] phy_coded_conn_params: : Scan connectable advertisements on the LE Coded PHY.
Connection parameters for the LE Coded PHY are provided.
Unions union esp_ble_key_value_t
#include <esp_gap_ble_api.h> union type of the security key value
Public Members
esp_ble_penc_keys_t penc_key received peer encryption key
esp_ble_pcsrk_keys_t pcsrk_key received peer device SRK
esp_ble_pid_keys_t pid_key peer device ID key
esp_ble_lenc_keys_t lenc_key local encryption reproduction keys LTK = = d1(ER,DIV,0)
esp_ble_lcsrk_keys lcsrk_key local device CSRK = d1(ER,DIV,1)
union esp_ble_sec_t #include <esp_gap_ble_api.h> union associated with ble security
Public Members
esp_ble_sec_key_notif_t key_notif passkey notification
esp_ble_sec_req_t ble_req BLE SMP related request
esp_ble_key_t ble_key BLE SMP keys used when pairing
esp_ble_local_id_keys_t ble_id_keys BLE IR event
esp_ble_auth_cmpl_t auth_cmpl Authentication complete indication.
union esp_ble_gap_cb_param_t #include <esp_gap_ble_api.h> Gap callback parameters union.
Public Members
struct esp_ble_gap_cb_param_t::ble_adv_data_cmpl_evt_param adv_data_cmpl Event parameter of ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_scan_rsp_data_cmpl_evt_param scan_rsp_data_cmpl Event parameter of ESP_GAP_BLE_SCAN_RSP_DATA_SET_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_scan_param_cmpl_evt_param scan_param_cmpl Event parameter of ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT

Espressif Systems

72

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
struct esp_ble_gap_cb_param_t::ble_scan_result_evt_param scan_rst Event parameter of ESP_GAP_BLE_SCAN_RESULT_EVT
struct esp_ble_gap_cb_param_t::ble_adv_data_raw_cmpl_evt_param adv_data_raw_cmpl Event parameter of ESP_GAP_BLE_ADV_DATA_RAW_SET_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_scan_rsp_data_raw_cmpl_evt_param scan_rsp_data_raw_cmpl Event parameter of ESP_GAP_BLE_SCAN_RSP_DATA_RAW_SET_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_adv_start_cmpl_evt_param adv_start_cmpl Event parameter of ESP_GAP_BLE_ADV_START_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_scan_start_cmpl_evt_param scan_start_cmpl Event parameter of ESP_GAP_BLE_SCAN_START_COMPLETE_EVT
esp_ble_sec_t ble_security ble gap security union type
struct esp_ble_gap_cb_param_t::ble_scan_stop_cmpl_evt_param scan_stop_cmpl Event parameter of ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_adv_stop_cmpl_evt_param adv_stop_cmpl Event parameter of ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_set_rand_cmpl_evt_param set_rand_addr_cmpl Event parameter of ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT
struct esp_ble_gap_cb_param_t::ble_update_conn_params_evt_param update_conn_params Event parameter of ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT
struct esp_ble_gap_cb_param_t::ble_pkt_data_length_cmpl_evt_param pkt_data_lenth_cmpl Event parameter of ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_local_privacy_cmpl_evt_param local_privacy_cmpl Event parameter of ESP_GAP_BLE_SET_LOCAL_PRIVACY_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_remove_bond_dev_cmpl_evt_param remove_bond_dev_cmpl Event parameter of ESP_GAP_BLE_REMOVE_BOND_DEV_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_clear_bond_dev_cmpl_evt_param clear_bond_dev_cmpl Event parameter of ESP_GAP_BLE_CLEAR_BOND_DEV_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_get_bond_dev_cmpl_evt_param get_bond_dev_cmpl Event parameter of ESP_GAP_BLE_GET_BOND_DEV_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_read_rssi_cmpl_evt_param read_rssi_cmpl Event parameter of ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_update_whitelist_cmpl_evt_param update_whitelist_cmpl Event parameter of ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_update_duplicate_exceptional_list_cmpl_evt_param update_duplicate_excepti Event parameter of ESP_GAP_BLE_UPDATE_DUPLICATE_EXCEPTIONAL_LIST_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_set_channels_evt_param ble_set_channels Event parameter of ESP_GAP_BLE_SET_CHANNELS_EVT
struct esp_ble_gap_cb_param_t::ble_read_phy_cmpl_evt_param read_phy Event parameter of ESP_GAP_BLE_READ_PHY_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_set_perf_def_phy_cmpl_evt_param set_perf_def_phy Event parameter of ESP_GAP_BLE_SET_PREFERED_DEFAULT_PHY_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_set_perf_phy_cmpl_evt_param set_perf_phy Event parameter of ESP_GAP_BLE_SET_PREFERED_PHY_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_adv_set_rand_addr_cmpl_evt_param ext_adv_set_rand_addr Event parameter of ESP_GAP_BLE_EXT_ADV_SET_RAND_ADDR_COMPLETE_EVT

Espressif Systems

73

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
struct esp_ble_gap_cb_param_t::ble_ext_adv_set_params_cmpl_evt_param ext_adv_set_params Event parameter of ESP_GAP_BLE_EXT_ADV_SET_PARAMS_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_adv_data_set_cmpl_evt_param ext_adv_data_set Event parameter of ESP_GAP_BLE_EXT_ADV_DATA_SET_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_adv_scan_rsp_set_cmpl_evt_param scan_rsp_set Event parameter of ESP_GAP_BLE_EXT_SCAN_RSP_DATA_SET_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_adv_start_cmpl_evt_param ext_adv_start Event parameter of ESP_GAP_BLE_EXT_ADV_START_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_adv_stop_cmpl_evt_param ext_adv_stop Event parameter of ESP_GAP_BLE_EXT_ADV_STOP_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_adv_set_remove_cmpl_evt_param ext_adv_remove Event parameter of ESP_GAP_BLE_EXT_ADV_SET_REMOVE_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_adv_set_clear_cmpl_evt_param ext_adv_clear Event parameter of ESP_GAP_BLE_EXT_ADV_SET_CLEAR_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_periodic_adv_set_params_cmpl_param peroid_adv_set_params Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SET_PARAMS_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_periodic_adv_data_set_cmpl_param period_adv_data_set Event parameter of ESP_GAP_BLE_PERIODIC_ADV_DATA_SET_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_periodic_adv_start_cmpl_param period_adv_start Event parameter of ESP_GAP_BLE_PERIODIC_ADV_START_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_periodic_adv_stop_cmpl_param period_adv_stop Event parameter of ESP_GAP_BLE_PERIODIC_ADV_STOP_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_period_adv_create_sync_cmpl_param period_adv_create_sync Event parameter of ESP_GAP_BLE_PERIODIC_ADV_CREATE_SYNC_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_period_adv_sync_cancel_cmpl_param period_adv_sync_cancel Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SYNC_CANCEL_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_period_adv_sync_terminate_cmpl_param period_adv_sync_term Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SYNC_TERMINATE_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_period_adv_add_dev_cmpl_param period_adv_add_dev Event parameter of ESP_GAP_BLE_PERIODIC_ADV_ADD_DEV_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_period_adv_remove_dev_cmpl_param period_adv_remove_dev Event parameter of ESP_GAP_BLE_PERIODIC_ADV_REMOVE_DEV_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_period_adv_clear_dev_cmpl_param period_adv_clear_dev Event parameter of ESP_GAP_BLE_PERIODIC_ADV_CLEAR_DEV_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_set_ext_scan_params_cmpl_param set_ext_scan_params Event parameter of ESP_GAP_BLE_SET_EXT_SCAN_PARAMS_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_scan_start_cmpl_param ext_scan_start Event parameter of ESP_GAP_BLE_EXT_SCAN_START_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_scan_stop_cmpl_param ext_scan_stop Event parameter of ESP_GAP_BLE_EXT_SCAN_STOP_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_conn_params_set_cmpl_param ext_conn_params_set Event parameter of ESP_GAP_BLE_PREFER_EXT_CONN_PARAMS_SET_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_adv_terminate_param adv_terminate Event parameter of ESP_GAP_BLE_ADV_TERMINATED_EVT
struct esp_ble_gap_cb_param_t::ble_scan_req_received_param scan_req_received Event parameter of ESP_GAP_BLE_SCAN_REQ_RECEIVED_EVT

Espressif Systems

74

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
struct esp_ble_gap_cb_param_t::ble_channel_sel_alg_param channel_sel_alg Event parameter of ESP_GAP_BLE_CHANNEL_SELETE_ALGORITHM_EVT
struct esp_ble_gap_cb_param_t::ble_periodic_adv_sync_lost_param periodic_adv_sync_lost Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SYNC_LOST_EVT
struct esp_ble_gap_cb_param_t::ble_periodic_adv_sync_estab_param periodic_adv_sync_estab Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SYNC_ESTAB_EVT
struct esp_ble_gap_cb_param_t::ble_phy_update_cmpl_param phy_update Event parameter of ESP_GAP_BLE_PHY_UPDATE_COMPLETE_EVT
struct esp_ble_gap_cb_param_t::ble_ext_adv_report_param ext_adv_report Event parameter of ESP_GAP_BLE_EXT_ADV_REPORT_EVT
struct esp_ble_gap_cb_param_t::ble_periodic_adv_report_param period_adv_report Event parameter of ESP_GAP_BLE_PERIODIC_ADV_REPORT_EVT
struct ble_adv_data_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT.
Public Members
esp_bt_status_t status Indicate the set advertising data operation success status
struct ble_adv_data_raw_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_ADV_DATA_RAW_SET_COMPLETE_EVT.
Public Members
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

Espressif Systems

75

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
uint8_t adv_instance extend advertising handle
uint16_t conn_idx connection index
uint8_t completed_event the number of completed extend advertising events
struct ble_channel_sel_alg_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_CHANNEL_SELETE_ALGORITHM_EVT.
Public Members
uint16_t conn_handle connection handle
uint8_t channel_sel_alg channel selection algorithm
struct ble_clear_bond_dev_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_CLEAR_BOND_DEV_COMPLETE_EVT.
Public Members
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.

Espressif Systems

76

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

77

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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.
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.

Espressif Systems

78

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

79

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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.

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

Espressif Systems

80

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
esp_ble_gap_phy_t tx_phy tx phy type
esp_ble_gap_phy_t rx_phy rx phy type
struct ble_pkt_data_length_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVT.
Public Members
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

Espressif Systems

81

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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 devicens 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

Espressif Systems

82

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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.

Espressif Systems

83

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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.
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

Espressif Systems

84

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
uint16_t length The length of device_info
esp_duplicate_info_t device_info device information, when subcode is ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_CLEAN, the value is invalid
struct ble_update_whitelist_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT.
Public Members
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 oSupplement to the Bluetooth Core Specificationp.
Public Members
bool set_scan_rsp Set this advertising data as scan response or not

Espressif Systems

85

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
bool include_name Advertising data include device name or not
bool include_txpower Advertising data include TX power
int min_interval Advertising data show slave preferred connection min interval. The connection interval in the following manner: connIntervalmin = Conn_Interval_Min * 1.25 ms Conn_Interval_Min range: 0x0006 to 0x0C80 Value of 0xFFFF indicates no specific minimum. Values not defined above are reserved for future use.
int max_interval Advertising data show slave preferred connection max interval. The connection interval in the following 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

Espressif Systems

86

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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 advertising reports for each packet received
struct esp_gap_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_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

Espressif Systems

87

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
esp_bt_octet8_t rand The random number
uint16_t ediv The ediv value
uint8_t sec_level The security level of the security link
uint8_t key_size The key size(7~16) of the security link
struct esp_ble_pcsrk_keys_t BLE CSRK keys.
Public Members
uint32_t counter The counter
esp_bt_octet16_t csrk The csrk key
uint8_t sec_level The security level
struct esp_ble_pid_keys_t BLE pid keys.
Public Members
esp_bt_octet16_t irk The irk value
esp_ble_addr_type_t addr_type The address type
esp_bd_addr_t static_addr The static address
struct esp_ble_lenc_keys_t BLE Encryption reproduction keys.
Public Members
esp_bt_octet16_t ltk The long term key
uint16_t div The div value
uint8_t key_size The key size of the security link
uint8_t sec_level The security level of the security link
struct esp_ble_lcsrk_keys BLE SRK keys.

Espressif Systems

88

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

89

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

90

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

91

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
esp_ble_scan_filter_t filter_policy ext scan filter policy
esp_ble_scan_duplicate_t scan_duplicate ext scan duplicate scan
esp_ble_ext_scan_cfg_mask_t cfg_mask ext scan config mask
esp_ble_ext_scan_cfg_t uncoded_cfg ext scan uncoded config parameters
esp_ble_ext_scan_cfg_t coded_cfg ext scan coded config parameters
struct esp_ble_gap_conn_params_t create extend connection parameters
Public Members
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

Espressif Systems

92

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

93

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

uint8_t dir_addr_type direct address type
esp_bd_addr_t dir_addr direct address
esp_ble_gap_ext_adv_data_status_t data_status data type
uint8_t adv_data_len extend advertising data length
uint8_t adv_data[251] extend advertising data
struct esp_ble_gap_periodic_adv_report_t periodic adv report parameters

Public Members
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

Espressif Systems

94

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Macros ESP_BLE_ADV_FLAG_LIMIT_DISC
BLE_ADV_DATA_FLAG data flag bit definition used for advertising data flag ESP_BLE_ADV_FLAG_GEN_DISC ESP_BLE_ADV_FLAG_BREDR_NOT_SPT ESP_BLE_ADV_FLAG_DMT_CONTROLLER_SPT ESP_BLE_ADV_FLAG_DMT_HOST_SPT ESP_BLE_ADV_FLAG_NON_LIMIT_DISC ESP_LE_KEY_NONE ESP_LE_KEY_PENC ESP_LE_KEY_PID ESP_LE_KEY_PCSRK ESP_LE_KEY_PLK ESP_LE_KEY_LLK ESP_LE_KEY_LENC ESP_LE_KEY_LID ESP_LE_KEY_LCSRK ESP_LE_AUTH_NO_BOND ESP_LE_AUTH_BOND ESP_LE_AUTH_REQ_MITM ESP_LE_AUTH_REQ_BOND_MITM
0101 ESP_LE_AUTH_REQ_SC_ONLY ESP_LE_AUTH_REQ_SC_BOND ESP_LE_AUTH_REQ_SC_MITM ESP_LE_AUTH_REQ_SC_MITM_BOND ESP_BLE_ONLY_ACCEPT_SPECIFIED_AUTH_DISABLE ESP_BLE_ONLY_ACCEPT_SPECIFIED_AUTH_ENABLE ESP_BLE_OOB_DISABLE ESP_BLE_OOB_ENABLE ESP_IO_CAP_OUT ESP_IO_CAP_IO ESP_IO_CAP_IN ESP_IO_CAP_NONE ESP_IO_CAP_KBDISP ESP_BLE_APPEARANCE_UNKNOWN ESP_BLE_APPEARANCE_GENERIC_PHONE ESP_BLE_APPEARANCE_GENERIC_COMPUTER ESP_BLE_APPEARANCE_GENERIC_WATCH ESP_BLE_APPEARANCE_SPORTS_WATCH

Espressif Systems

95

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_BLE_APPEARANCE_GENERIC_CLOCK ESP_BLE_APPEARANCE_GENERIC_DISPLAY ESP_BLE_APPEARANCE_GENERIC_REMOTE ESP_BLE_APPEARANCE_GENERIC_EYEGLASSES ESP_BLE_APPEARANCE_GENERIC_TAG ESP_BLE_APPEARANCE_GENERIC_KEYRING ESP_BLE_APPEARANCE_GENERIC_MEDIA_PLAYER ESP_BLE_APPEARANCE_GENERIC_BARCODE_SCANNER ESP_BLE_APPEARANCE_GENERIC_THERMOMETER ESP_BLE_APPEARANCE_THERMOMETER_EAR ESP_BLE_APPEARANCE_GENERIC_HEART_RATE ESP_BLE_APPEARANCE_HEART_RATE_BELT ESP_BLE_APPEARANCE_GENERIC_BLOOD_PRESSURE ESP_BLE_APPEARANCE_BLOOD_PRESSURE_ARM ESP_BLE_APPEARANCE_BLOOD_PRESSURE_WRIST ESP_BLE_APPEARANCE_GENERIC_HID ESP_BLE_APPEARANCE_HID_KEYBOARD ESP_BLE_APPEARANCE_HID_MOUSE ESP_BLE_APPEARANCE_HID_JOYSTICK ESP_BLE_APPEARANCE_HID_GAMEPAD ESP_BLE_APPEARANCE_HID_DIGITIZER_TABLET ESP_BLE_APPEARANCE_HID_CARD_READER ESP_BLE_APPEARANCE_HID_DIGITAL_PEN ESP_BLE_APPEARANCE_HID_BARCODE_SCANNER ESP_BLE_APPEARANCE_GENERIC_GLUCOSE ESP_BLE_APPEARANCE_GENERIC_WALKING ESP_BLE_APPEARANCE_WALKING_IN_SHOE ESP_BLE_APPEARANCE_WALKING_ON_SHOE ESP_BLE_APPEARANCE_WALKING_ON_HIP ESP_BLE_APPEARANCE_GENERIC_CYCLING ESP_BLE_APPEARANCE_CYCLING_COMPUTER ESP_BLE_APPEARANCE_CYCLING_SPEED ESP_BLE_APPEARANCE_CYCLING_CADENCE ESP_BLE_APPEARANCE_CYCLING_POWER ESP_BLE_APPEARANCE_CYCLING_SPEED_CADENCE ESP_BLE_APPEARANCE_GENERIC_PULSE_OXIMETER ESP_BLE_APPEARANCE_PULSE_OXIMETER_FINGERTIP ESP_BLE_APPEARANCE_PULSE_OXIMETER_WRIST ESP_BLE_APPEARANCE_GENERIC_WEIGHT

Espressif Systems

96

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_BLE_APPEARANCE_GENERIC_PERSONAL_MOBILITY_DEVICE ESP_BLE_APPEARANCE_POWERED_WHEELCHAIR ESP_BLE_APPEARANCE_MOBILITY_SCOOTER ESP_BLE_APPEARANCE_GENERIC_CONTINUOUS_GLUCOSE_MONITOR ESP_BLE_APPEARANCE_GENERIC_INSULIN_PUMP ESP_BLE_APPEARANCE_INSULIN_PUMP_DURABLE_PUMP ESP_BLE_APPEARANCE_INSULIN_PUMP_PATCH_PUMP ESP_BLE_APPEARANCE_INSULIN_PEN ESP_BLE_APPEARANCE_GENERIC_MEDICATION_DELIVERY ESP_BLE_APPEARANCE_GENERIC_OUTDOOR_SPORTS ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_AND_NAV ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_POD ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_POD_AND_NAV ESP_GAP_BLE_CHANNELS_LEN ESP_GAP_BLE_ADD_WHITELIST_COMPLETE_EVT
This is the old name, just for backwards compatibility. ESP_BLE_ADV_DATA_LEN_MAX
Advertising data maximum length. ESP_BLE_SCAN_RSP_DATA_LEN_MAX
Scan response data maximum length. BLE_BIT(n) ESP_BLE_GAP_SET_EXT_ADV_PROP_NONCONN_NONSCANNABLE_UNDIRECTED ESP_BLE_GAP_SET_EXT_ADV_PROP_CONNECTABLE ESP_BLE_GAP_SET_EXT_ADV_PROP_SCANNABLE ESP_BLE_GAP_SET_EXT_ADV_PROP_DIRECTED ESP_BLE_GAP_SET_EXT_ADV_PROP_HD_DIRECTED ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY ESP_BLE_GAP_SET_EXT_ADV_PROP_ANON_ADV ESP_BLE_GAP_SET_EXT_ADV_PROP_INCLUDE_TX_PWR ESP_BLE_GAP_SET_EXT_ADV_PROP_MASK ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_IND ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_LD_DIR ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_HD_DIR ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_SCAN ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_NONCONN ESP_BLE_GAP_PHY_1M ESP_BLE_GAP_PHY_2M ESP_BLE_GAP_PHY_CODED ESP_BLE_GAP_NO_PREFER_TRANSMIT_PHY

Espressif Systems

97

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_BLE_GAP_NO_PREFER_RECEIVE_PHY ESP_BLE_GAP_PRI_PHY_1M ESP_BLE_GAP_PRI_PHY_CODED ESP_BLE_GAP_PHY_1M_PREF_MASK ESP_BLE_GAP_PHY_2M_PREF_MASK ESP_BLE_GAP_PHY_CODED_PREF_MASK ESP_BLE_GAP_PHY_OPTIONS_NO_PREF ESP_BLE_GAP_PHY_OPTIONS_PREF_S2_CODING ESP_BLE_GAP_PHY_OPTIONS_PREF_S8_CODING ESP_BLE_GAP_EXT_SCAN_CFG_UNCODE_MASK ESP_BLE_GAP_EXT_SCAN_CFG_CODE_MASK ESP_BLE_GAP_EXT_ADV_DATA_COMPLETE ESP_BLE_GAP_EXT_ADV_DATA_INCOMPLETE ESP_BLE_GAP_EXT_ADV_DATA_TRUNCATED ESP_BLE_GAP_SYNC_POLICY_BY_ADV_INFO ESP_BLE_GAP_SYNC_POLICY_BY_PERIODIC_LIST ESP_BLE_ADV_REPORT_EXT_ADV_IND ESP_BLE_ADV_REPORT_EXT_SCAN_IND ESP_BLE_ADV_REPORT_EXT_DIRECT_ADV ESP_BLE_ADV_REPORT_EXT_SCAN_RSP ESP_BLE_LEGACY_ADV_TYPE_IND ESP_BLE_LEGACY_ADV_TYPE_DIRECT_IND ESP_BLE_LEGACY_ADV_TYPE_SCAN_IND ESP_BLE_LEGACY_ADV_TYPE_NONCON_IND ESP_BLE_LEGACY_ADV_TYPE_SCAN_RSP_TO_ADV_IND ESP_BLE_LEGACY_ADV_TYPE_SCAN_RSP_TO_ADV_SCAN_IND
Type Definitions typedef uint8_t esp_ble_key_type_t typedef uint8_t esp_ble_auth_req_t
combination of the above bit pattern typedef uint8_t esp_ble_io_cap_t
combination of the io capability typedef uint8_t esp_gap_ble_channels[ESP_GAP_BLE_CHANNELS_LEN] typedef uint8_t esp_duplicate_info_t[ESP_BD_ADDR_LEN] typedef uint16_t esp_ble_ext_adv_type_mask_t typedef uint8_t esp_ble_gap_phy_t typedef uint8_t esp_ble_gap_all_phys_t typedef uint8_t esp_ble_gap_pri_phy_t typedef uint8_t esp_ble_gap_phy_mask_t

Espressif Systems

98

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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,

GAP callback function type.

*param)

Parameters · event: : Event type · param: : Point to callback parameter, currently is union type

esp_ble_gap_cb_param_t

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

Espressif Systems

99

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT = 19 When set the static rand address complete, the event comes
ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT When update connection parameters complete, the event comes
ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVT When set pkt length complete, the event comes
ESP_GAP_BLE_SET_LOCAL_PRIVACY_COMPLETE_EVT When Enable/disable privacy on the local device complete, the event comes
ESP_GAP_BLE_REMOVE_BOND_DEV_COMPLETE_EVT When remove the bond device complete, the event comes
ESP_GAP_BLE_CLEAR_BOND_DEV_COMPLETE_EVT When clear the bond device clear complete, the event comes
ESP_GAP_BLE_GET_BOND_DEV_COMPLETE_EVT When get the bond device list complete, the event comes
ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT When read the rssi complete, the event comes
ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT When add or remove whitelist complete, the event comes
ESP_GAP_BLE_UPDATE_DUPLICATE_EXCEPTIONAL_LIST_COMPLETE_EVT When update duplicate exceptional list complete, the event comes
ESP_GAP_BLE_SET_CHANNELS_EVT = 29 When setting BLE channels complete, the event comes
ESP_GAP_BLE_READ_PHY_COMPLETE_EVT ESP_GAP_BLE_SET_PREFERED_DEFAULT_PHY_COMPLETE_EVT ESP_GAP_BLE_SET_PREFERED_PHY_COMPLETE_EVT ESP_GAP_BLE_EXT_ADV_SET_RAND_ADDR_COMPLETE_EVT ESP_GAP_BLE_EXT_ADV_SET_PARAMS_COMPLETE_EVT ESP_GAP_BLE_EXT_ADV_DATA_SET_COMPLETE_EVT ESP_GAP_BLE_EXT_SCAN_RSP_DATA_SET_COMPLETE_EVT ESP_GAP_BLE_EXT_ADV_START_COMPLETE_EVT ESP_GAP_BLE_EXT_ADV_STOP_COMPLETE_EVT ESP_GAP_BLE_EXT_ADV_SET_REMOVE_COMPLETE_EVT ESP_GAP_BLE_EXT_ADV_SET_CLEAR_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_SET_PARAMS_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_DATA_SET_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_START_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_STOP_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_CREATE_SYNC_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_SYNC_CANCEL_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_SYNC_TERMINATE_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_ADD_DEV_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_REMOVE_DEV_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_CLEAR_DEV_COMPLETE_EVT

Espressif Systems

100

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_GAP_BLE_SET_EXT_SCAN_PARAMS_COMPLETE_EVT ESP_GAP_BLE_EXT_SCAN_START_COMPLETE_EVT ESP_GAP_BLE_EXT_SCAN_STOP_COMPLETE_EVT ESP_GAP_BLE_PREFER_EXT_CONN_PARAMS_SET_COMPLETE_EVT ESP_GAP_BLE_PHY_UPDATE_COMPLETE_EVT ESP_GAP_BLE_EXT_ADV_REPORT_EVT ESP_GAP_BLE_SCAN_TIMEOUT_EVT ESP_GAP_BLE_ADV_TERMINATED_EVT ESP_GAP_BLE_SCAN_REQ_RECEIVED_EVT ESP_GAP_BLE_CHANNEL_SELETE_ALGORITHM_EVT ESP_GAP_BLE_PERIODIC_ADV_REPORT_EVT ESP_GAP_BLE_PERIODIC_ADV_SYNC_LOST_EVT ESP_GAP_BLE_PERIODIC_ADV_SYNC_ESTAB_EVT ESP_GAP_BLE_EVT_MAX enum esp_ble_adv_data_type The type of advertising data(not adv_type) Values: ESP_BLE_AD_TYPE_FLAG = 0x01 ESP_BLE_AD_TYPE_16SRV_PART = 0x02 ESP_BLE_AD_TYPE_16SRV_CMPL = 0x03 ESP_BLE_AD_TYPE_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

Espressif Systems

101

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_BLE_AD_TYPE_SPAIR_C256 = 0x1d ESP_BLE_AD_TYPE_SPAIR_R256 = 0x1e ESP_BLE_AD_TYPE_32SOL_SRV_UUID = 0x1f ESP_BLE_AD_TYPE_32SERVICE_DATA = 0x20 ESP_BLE_AD_TYPE_128SERVICE_DATA = 0x21 ESP_BLE_AD_TYPE_LE_SECURE_CONFIRM = 0x22 ESP_BLE_AD_TYPE_LE_SECURE_RANDOM = 0x23 ESP_BLE_AD_TYPE_URI = 0x24 ESP_BLE_AD_TYPE_INDOOR_POSITION = 0x25 ESP_BLE_AD_TYPE_TRANS_DISC_DATA = 0x26 ESP_BLE_AD_TYPE_LE_SUPPORT_FEATURE = 0x27 ESP_BLE_AD_TYPE_CHAN_MAP_UPDATE = 0x28 ESP_BLE_AD_MANUFACTURER_SPECIFIC_TYPE = 0xFF enum esp_ble_adv_type_t Advertising mode. Values: ADV_TYPE_IND = 0x00 ADV_TYPE_DIRECT_IND_HIGH = 0x01 ADV_TYPE_SCAN_IND = 0x02 ADV_TYPE_NONCONN_IND = 0x03 ADV_TYPE_DIRECT_IND_LOW = 0x04 enum esp_ble_adv_channel_t Advertising channel mask. Values: ADV_CHNL_37 = 0x01 ADV_CHNL_38 = 0x02 ADV_CHNL_39 = 0x04 ADV_CHNL_ALL = 0x07 enum esp_ble_adv_filter_t Values: ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY = 0x00
Allow both scan and connection requests from anyone. ADV_FILTER_ALLOW_SCAN_WLST_CON_ANY
Allow both scan req from White List devices only and connection req from anyone. ADV_FILTER_ALLOW_SCAN_ANY_CON_WLST
Allow both scan req from anyone and connection req from White List devices only. ADV_FILTER_ALLOW_SCAN_WLST_CON_WLST
Allow scan and connection requests from White List devices only. enum esp_ble_sec_act_t
Values: ESP_BLE_SEC_ENCRYPT = 1 ESP_BLE_SEC_ENCRYPT_NO_MITM

Espressif Systems

102

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_BLE_SEC_ENCRYPT_MITM enum esp_ble_sm_param_t
Values: ESP_BLE_SM_PASSKEY = 0 ESP_BLE_SM_AUTHEN_REQ_MODE ESP_BLE_SM_IOCAP_MODE ESP_BLE_SM_SET_INIT_KEY ESP_BLE_SM_SET_RSP_KEY ESP_BLE_SM_MAX_KEY_SIZE ESP_BLE_SM_MIN_KEY_SIZE ESP_BLE_SM_SET_STATIC_PASSKEY ESP_BLE_SM_CLEAR_STATIC_PASSKEY ESP_BLE_SM_ONLY_ACCEPT_SPECIFIED_SEC_AUTH ESP_BLE_SM_OOB_SUPPORT ESP_BLE_APP_ENC_KEY_SIZE ESP_BLE_SM_MAX_PARAM enum esp_ble_scan_type_t Ble scan type. Values: BLE_SCAN_TYPE_PASSIVE = 0x0
Passive scan BLE_SCAN_TYPE_ACTIVE = 0x1
Active scan enum esp_ble_scan_filter_t
Ble scan filter type. Values: BLE_SCAN_FILTER_ALLOW_ALL = 0x0
Accept all : 1. advertisement packets except directed advertising packets not addressed to this device (default).
BLE_SCAN_FILTER_ALLOW_ONLY_WLST = 0x1 Accept only : 1. advertisement packets from devices where the advertiserns 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 advertiserns 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.

Espressif Systems

103

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
enum esp_ble_scan_duplicate_t Ble scan duplicate type.
Values:
BLE_SCAN_DUPLICATE_DISABLE = 0x0 the Link Layer should generate advertising reports to the host for each packet received
BLE_SCAN_DUPLICATE_ENABLE = 0x1 the Link Layer should filter out duplicate advertising reports to the Host
BLE_SCAN_DUPLICATE_MAX = 0x2 0x02 0xFF, Reserved for future use
enum esp_gap_search_evt_t Sub Event of ESP_GAP_BLE_SCAN_RESULT_EVT.
Values:
ESP_GAP_SEARCH_INQ_RES_EVT = 0 Inquiry result for a peer device.
ESP_GAP_SEARCH_INQ_CMPL_EVT = 1 Inquiry complete.
ESP_GAP_SEARCH_DISC_RES_EVT = 2 Discovery result for a peer device.
ESP_GAP_SEARCH_DISC_BLE_RES_EVT = 3 Discovery result for BLE GATT based service on a peer device.
ESP_GAP_SEARCH_DISC_CMPL_EVT = 4 Discovery complete.
ESP_GAP_SEARCH_DI_DISC_CMPL_EVT = 5 Discovery complete.
ESP_GAP_SEARCH_SEARCH_CANCEL_CMPL_EVT = 6 Search cancelled
ESP_GAP_SEARCH_INQ_DISCARD_NUM_EVT = 7 The number of pkt discarded by flow control
enum esp_ble_evt_type_t Ble scan result event type, to indicate the result is scan response or advertising data or other.
Values:
ESP_BLE_EVT_CONN_ADV = 0x00 Connectable undirected advertising (ADV_IND)
ESP_BLE_EVT_CONN_DIR_ADV = 0x01 Connectable directed advertising (ADV_DIRECT_IND)
ESP_BLE_EVT_DISC_ADV = 0x02 Scannable undirected advertising (ADV_SCAN_IND)
ESP_BLE_EVT_NON_CONN_ADV = 0x03 Non connectable undirected advertising (ADV_NONCONN_IND)
ESP_BLE_EVT_SCAN_RSP = 0x04 Scan Response (SCAN_RSP)
enum esp_ble_wl_opration_t Values:
ESP_BLE_WHITELIST_REMOVE = 0X00 remove mac from whitelist

Espressif Systems

104

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_BLE_WHITELIST_ADD = 0X01 add address to whitelist
enum esp_bt_duplicate_exceptional_subcode_type_t Values: ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_ADD = 0 Add device info into duplicate scan exceptional list ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_REMOVE Remove device info from duplicate scan exceptional list ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_CLEAN Clean duplicate scan exceptional list
enum esp_ble_duplicate_exceptional_info_type_t Values: ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_ADV_ADDR = 0 BLE advertising address , device info will be added into ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_ADDR_LIST ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_LINK_ID BLE mesh link ID, it is for BLE mesh, device info will be added into ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_LINK_ID_LIST ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_BEACON_TYPE BLE mesh beacon AD type, the format is | Len | 0x2B | Beacon Type | Beacon Data | ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_PROV_SRV_ADV BLE mesh provisioning service uuid, the format is | 0x02 | 0x01 | flags | 0x03 | 0x03 | 0x1827 | l. |` 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 | l. |`
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

Espressif Systems

105

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Header File · components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h
Unions union esp_gatt_rsp_t
#include <esp_gatt_defs.h> GATT remote read request response type.
Public Members
esp_gatt_value_t attr_value Gatt attribute structure
uint16_t handle Gatt attribute handle
Structures struct esp_gatt_id_t
Gatt id, include uuid and instance id.
Public Members
esp_bt_uuid_t uuid UUID
uint8_t inst_id Instance id
struct esp_gatt_srvc_id_t Gatt service id, include id (uuid and instance id) and primary flag.
Public Members
esp_gatt_id_t id Gatt id, include uuid and instance
bool is_primary This service is primary or not
struct esp_attr_desc_t Attribute description (used to create database)
Public Members
uint16_t uuid_length UUID length
uint8_t *uuid_p UUID value
uint16_t perm Attribute permission
uint16_t max_length Maximum length of the element
uint16_t length Current length of the element

Espressif Systems

106

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

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

Espressif Systems

107

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Public Members
uint16_t start_hdl Gatt start handle value of included 128 bit service
uint16_t end_hdl Gatt end handle value of included 128 bit service
struct esp_gatt_value_t Gatt attribute value.
Public Members
uint8_t value[ESP_GATT_MAX_ATTR_LEN] Gatt attribute value
uint16_t handle Gatt attribute handle
uint16_t offset Gatt attribute value offset
uint16_t len Gatt attribute value length
uint8_t auth_req Gatt authentication request
struct esp_gatt_conn_params_t Connection parameters information.
Public Members
uint16_t interval connection interval
uint16_t latency 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

Espressif Systems

108

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Public Members
esp_gatt_db_attr_type_t type The attribute type
uint16_t attribute_handle The attribute handle, itns valid for all of the type
uint16_t start_handle The service start handle, itns valid only when the type = ESP_GATT_DB_PRIMARY_SERVICE or ESP_GATT_DB_SECONDARY_SERVICE
uint16_t end_handle The service end handle, itns valid only when the type = ESP_GATT_DB_PRIMARY_SERVICE or ESP_GATT_DB_SECONDARY_SERVICE
esp_gatt_char_prop_t properties The characteristic properties, itns valid only when the type = ESP_GATT_DB_CHARACTERISTIC
esp_bt_uuid_t uuid The attribute uuid, itns 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

Espressif Systems

109

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

struct esp_gattc_incl_svc_elem_t include service element

Public Members
uint16_t handle The include service current attribute handle
uint16_t incl_srvc_s_handle The start handle of the service which has been included
uint16_t incl_srvc_e_handle The end handle of the service which has been included
esp_bt_uuid_t uuid The include service uuid

Macros ESP_GATT_UUID_IMMEDIATE_ALERT_SVC
All oESP_GATT_UUID_xxxpis 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

Espressif Systems

110

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_GATT_UUID_PRI_SERVICE ESP_GATT_UUID_SEC_SERVICE ESP_GATT_UUID_INCLUDE_SERVICE ESP_GATT_UUID_CHAR_DECLARE ESP_GATT_UUID_CHAR_EXT_PROP ESP_GATT_UUID_CHAR_DESCRIPTION ESP_GATT_UUID_CHAR_CLIENT_CONFIG ESP_GATT_UUID_CHAR_SRVR_CONFIG ESP_GATT_UUID_CHAR_PRESENT_FORMAT ESP_GATT_UUID_CHAR_AGG_FORMAT ESP_GATT_UUID_CHAR_VALID_RANGE ESP_GATT_UUID_EXT_RPT_REF_DESCR ESP_GATT_UUID_RPT_REF_DESCR ESP_GATT_UUID_NUM_DIGITALS_DESCR ESP_GATT_UUID_VALUE_TRIGGER_DESCR ESP_GATT_UUID_ENV_SENSING_CONFIG_DESCR ESP_GATT_UUID_ENV_SENSING_MEASUREMENT_DESCR ESP_GATT_UUID_ENV_SENSING_TRIGGER_DESCR ESP_GATT_UUID_TIME_TRIGGER_DESCR ESP_GATT_UUID_GAP_DEVICE_NAME ESP_GATT_UUID_GAP_ICON ESP_GATT_UUID_GAP_PREF_CONN_PARAM ESP_GATT_UUID_GAP_CENTRAL_ADDR_RESOL ESP_GATT_UUID_GATT_SRV_CHGD ESP_GATT_UUID_ALERT_LEVEL ESP_GATT_UUID_TX_POWER_LEVEL ESP_GATT_UUID_CURRENT_TIME ESP_GATT_UUID_LOCAL_TIME_INFO ESP_GATT_UUID_REF_TIME_INFO ESP_GATT_UUID_NW_STATUS ESP_GATT_UUID_NW_TRIGGER ESP_GATT_UUID_ALERT_STATUS ESP_GATT_UUID_RINGER_CP ESP_GATT_UUID_RINGER_SETTING ESP_GATT_UUID_GM_MEASUREMENT ESP_GATT_UUID_GM_CONTEXT ESP_GATT_UUID_GM_CONTROL_POINT ESP_GATT_UUID_GM_FEATURE ESP_GATT_UUID_SYSTEM_ID

Espressif Systems

111

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_GATT_UUID_MODEL_NUMBER_STR ESP_GATT_UUID_SERIAL_NUMBER_STR ESP_GATT_UUID_FW_VERSION_STR ESP_GATT_UUID_HW_VERSION_STR ESP_GATT_UUID_SW_VERSION_STR ESP_GATT_UUID_MANU_NAME ESP_GATT_UUID_IEEE_DATA ESP_GATT_UUID_PNP_ID ESP_GATT_UUID_HID_INFORMATION ESP_GATT_UUID_HID_REPORT_MAP ESP_GATT_UUID_HID_CONTROL_POINT ESP_GATT_UUID_HID_REPORT ESP_GATT_UUID_HID_PROTO_MODE ESP_GATT_UUID_HID_BT_KB_INPUT ESP_GATT_UUID_HID_BT_KB_OUTPUT ESP_GATT_UUID_HID_BT_MOUSE_INPUT ESP_GATT_HEART_RATE_MEAS
Heart Rate Measurement. ESP_GATT_BODY_SENSOR_LOCATION
Body Sensor Location. ESP_GATT_HEART_RATE_CNTL_POINT
Heart Rate Control Point. ESP_GATT_UUID_BATTERY_LEVEL ESP_GATT_UUID_SC_CONTROL_POINT ESP_GATT_UUID_SENSOR_LOCATION ESP_GATT_UUID_RSC_MEASUREMENT ESP_GATT_UUID_RSC_FEATURE ESP_GATT_UUID_CSC_MEASUREMENT ESP_GATT_UUID_CSC_FEATURE ESP_GATT_UUID_SCAN_INT_WINDOW ESP_GATT_UUID_SCAN_REFRESH ESP_GATT_ILLEGAL_UUID
GATT INVALID UUID. ESP_GATT_ILLEGAL_HANDLE
GATT INVALID HANDLE. ESP_GATT_ATTR_HANDLE_MAX
GATT attribute max handle. ESP_GATT_MAX_READ_MULTI_HANDLES ESP_GATT_PERM_READ
Attribute permissions. ESP_GATT_PERM_READ_ENCRYPTED

Espressif Systems

112

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_GATT_PERM_READ_ENC_MITM ESP_GATT_PERM_WRITE ESP_GATT_PERM_WRITE_ENCRYPTED ESP_GATT_PERM_WRITE_ENC_MITM ESP_GATT_PERM_WRITE_SIGNED ESP_GATT_PERM_WRITE_SIGNED_MITM ESP_GATT_PERM_READ_AUTHORIZATION ESP_GATT_PERM_WRITE_AUTHORIZATION ESP_GATT_CHAR_PROP_BIT_BROADCAST ESP_GATT_CHAR_PROP_BIT_READ ESP_GATT_CHAR_PROP_BIT_WRITE_NR ESP_GATT_CHAR_PROP_BIT_WRITE ESP_GATT_CHAR_PROP_BIT_NOTIFY ESP_GATT_CHAR_PROP_BIT_INDICATE ESP_GATT_CHAR_PROP_BIT_AUTH ESP_GATT_CHAR_PROP_BIT_EXT_PROP ESP_GATT_MAX_ATTR_LEN
GATT maximum attribute length. ESP_GATT_RSP_BY_APP ESP_GATT_AUTO_RSP ESP_GATT_IF_NONE
If callback report gattc_if/gatts_if as this macro, means this event is not correspond to any app
Type Definitions typedef uint16_t esp_gatt_perm_t typedef uint8_t esp_gatt_char_prop_t typedef uint8_t esp_gatt_if_t
Gatt interface type, different application on GATT client use different gatt_if
Enumerations enum esp_gatt_prep_write_type
Attribute write data type from the client. Values: ESP_GATT_PREP_WRITE_CANCEL = 0x00
Prepare write cancel ESP_GATT_PREP_WRITE_EXEC = 0x01
Prepare write execute enum esp_gatt_status_t
GATT success code and error codes. Values: ESP_GATT_OK = 0x0 ESP_GATT_INVALID_HANDLE = 0x01 ESP_GATT_READ_NOT_PERMIT = 0x02

Espressif Systems

113

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_GATT_WRITE_NOT_PERMIT = 0x03 ESP_GATT_INVALID_PDU = 0x04 ESP_GATT_INSUF_AUTHENTICATION = 0x05 ESP_GATT_REQ_NOT_SUPPORTED = 0x06 ESP_GATT_INVALID_OFFSET = 0x07 ESP_GATT_INSUF_AUTHORIZATION = 0x08 ESP_GATT_PREPARE_Q_FULL = 0x09 ESP_GATT_NOT_FOUND = 0x0a ESP_GATT_NOT_LONG = 0x0b ESP_GATT_INSUF_KEY_SIZE = 0x0c ESP_GATT_INVALID_ATTR_LEN = 0x0d ESP_GATT_ERR_UNLIKELY = 0x0e ESP_GATT_INSUF_ENCRYPTION = 0x0f ESP_GATT_UNSUPPORT_GRP_TYPE = 0x10 ESP_GATT_INSUF_RESOURCE = 0x11 ESP_GATT_NO_RESOURCES = 0x80 ESP_GATT_INTERNAL_ERROR = 0x81 ESP_GATT_WRONG_STATE = 0x82 ESP_GATT_DB_FULL = 0x83 ESP_GATT_BUSY = 0x84 ESP_GATT_ERROR = 0x85 ESP_GATT_CMD_STARTED = 0x86 ESP_GATT_ILLEGAL_PARAMETER = 0x87 ESP_GATT_PENDING = 0x88 ESP_GATT_AUTH_FAIL = 0x89 ESP_GATT_MORE = 0x8a ESP_GATT_INVALID_CFG = 0x8b ESP_GATT_SERVICE_STARTED = 0x8c ESP_GATT_ENCRYPED_MITM = ESP_GATT_OK ESP_GATT_ENCRYPED_NO_MITM = 0x8d ESP_GATT_NOT_ENCRYPTED = 0x8e ESP_GATT_CONGESTED = 0x8f ESP_GATT_DUP_REG = 0x90 ESP_GATT_ALREADY_OPEN = 0x91 ESP_GATT_CANCEL = 0x92 ESP_GATT_STACK_RSP = 0xe0 ESP_GATT_APP_RSP = 0xe1 ESP_GATT_UNKNOWN_ERROR = 0xef ESP_GATT_CCC_CFG_ERR = 0xfd

Espressif Systems

114

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_GATT_PRC_IN_PROGRESS = 0xfe
ESP_GATT_OUT_OF_RANGE = 0xff
enum esp_gatt_conn_reason_t Gatt Connection reason enum.
Values:
ESP_GATT_CONN_UNKNOWN = 0 Gatt connection unknown
ESP_GATT_CONN_L2C_FAILURE = 1 General L2cap failure
ESP_GATT_CONN_TIMEOUT = 0x08 Connection timeout
ESP_GATT_CONN_TERMINATE_PEER_USER = 0x13 Connection terminate by peer user
ESP_GATT_CONN_TERMINATE_LOCAL_HOST = 0x16 Connection terminated by local host
ESP_GATT_CONN_FAIL_ESTABLISH = 0x3e Connection fail to establish
ESP_GATT_CONN_LMP_TIMEOUT = 0x22 Connection fail for LMP response tout
ESP_GATT_CONN_CONN_CANCEL = 0x0100 L2CAP connection cancelled
ESP_GATT_CONN_NONE = 0x0101 No connection to cancel
enum esp_gatt_auth_req_t Gatt authentication request type.
Values:
ESP_GATT_AUTH_REQ_NONE = 0
ESP_GATT_AUTH_REQ_NO_MITM = 1
ESP_GATT_AUTH_REQ_MITM = 2
ESP_GATT_AUTH_REQ_SIGNED_NO_MITM = 3
ESP_GATT_AUTH_REQ_SIGNED_MITM = 4
enum esp_service_source_t Values:
ESP_GATT_SERVICE_FROM_REMOTE_DEVICE = 0
ESP_GATT_SERVICE_FROM_NVS_FLASH = 1
ESP_GATT_SERVICE_FROM_UNKNOWN = 2
enum esp_gatt_write_type_t Gatt write type.
Values:
ESP_GATT_WRITE_TYPE_NO_RSP = 1 Gatt write attribute need no response
ESP_GATT_WRITE_TYPE_RSP Gatt write attribute need remote response

Espressif Systems

115

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

116

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Create a service attribute tab.

srvc_inst_id)

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 included_service_handle)
This function is called to add an included service. This function have to be called between mesp_ble_gatts_create_servicenandmesp_ble_gatts_add_charn. 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.

Espressif Systems

117

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· [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 itns 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
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.

Espressif Systems

118

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Retrieve attribute value.

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

Espressif Systems

119

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t esp_ble_gatts_send_service_change_indication(esp_gatt_if_t

gatts_if,

Send service change indication.

esp_bd_addr_t remote_bda)

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

Espressif Systems

120

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
struct esp_ble_gatts_cb_param_t::gatts_cancel_open_evt_param cancel_open Gatt server callback param of ESP_GATTS_CANCEL_OPEN_EVT
struct esp_ble_gatts_cb_param_t::gatts_close_evt_param close Gatt server callback param of ESP_GATTS_CLOSE_EVT
struct esp_ble_gatts_cb_param_t::gatts_congest_evt_param congest Gatt server callback param of ESP_GATTS_CONGEST_EVT
struct esp_ble_gatts_cb_param_t::gatts_rsp_evt_param rsp Gatt server callback param of ESP_GATTS_RESPONSE_EVT
struct esp_ble_gatts_cb_param_t::gatts_add_attr_tab_evt_param add_attr_tab Gatt server callback param of ESP_GATTS_CREAT_ATTR_TAB_EVT
struct esp_ble_gatts_cb_param_t::gatts_set_attr_val_evt_param set_attr_val Gatt server callback param of ESP_GATTS_SET_ATTR_VAL_EVT
struct esp_ble_gatts_cb_param_t::gatts_send_service_change_evt_param service_change Gatt server callback param of ESP_GATTS_SEND_SERVICE_CHANGE_EVT
struct gatts_add_attr_tab_evt_param #include <esp_gatts_api.h> ESP_GATTS_CREAT_ATTR_TAB_EVT.
Public Members
esp_gatt_status_t status Operation status
esp_bt_uuid_t svc_uuid Service uuid type
uint8_t svc_inst_id Service id
uint16_t num_handle The number of the attribute handle to be added to the gatts database
uint16_t *handles The number to the handles
struct gatts_add_char_descr_evt_param #include <esp_gatts_api.h> ESP_GATTS_ADD_CHAR_DESCR_EVT.
Public Members
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.

Espressif Systems

121

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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.

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

Espressif Systems

122

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
uint16_t len The indication or notification value length, len is valid when send notification or indication failed
uint8_t *value The indication or notification value , value is valid when send notification or indication failed
struct gatts_congest_evt_param #include <esp_gatts_api.h> ESP_GATTS_LISTEN_EVT. ESP_GATTS_CONGEST_EVT
Public Members
uint16_t conn_id Connection id
bool congested Congested or not
struct gatts_connect_evt_param #include <esp_gatts_api.h> ESP_GATTS_CONNECT_EVT.
Public Members
uint16_t conn_id Connection id
uint8_t link_role Link role : master role = 0 ; slave role = 1
esp_bd_addr_t remote_bda Remote bluetooth device address
esp_gatt_conn_params_t conn_params current Connection parameters
struct gatts_create_evt_param #include <esp_gatts_api.h> ESP_GATTS_UNREG_EVT. ESP_GATTS_CREATE_EVT
Public Members
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

Espressif Systems

123

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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.

Espressif Systems

124

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Public Members
uint16_t conn_id Connection id
uint32_t trans_id Transfer id
esp_bd_addr_t bda The bluetooth device address which been read
uint16_t handle The attribute handle
uint16_t offset Offset of the value, if the value is too long
bool is_long The value is too long or not
bool need_rsp The read operation need to do response
struct gatts_reg_evt_param #include <esp_gatts_api.h> ESP_GATTS_REG_EVT.
Public Members
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.

Espressif Systems

125

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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.
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

Espressif Systems

126

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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_ble_gatts_cb_param_t *param) GATT Server callback function type.

esp_gatt_if_t

gatts_if,

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

Espressif Systems

127

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_GATTS_STOP_EVT = 13 When stop service complete, the event comes
ESP_GATTS_CONNECT_EVT = 14 When gatt client connect, the event comes
ESP_GATTS_DISCONNECT_EVT = 15 When gatt client disconnect, the event comes
ESP_GATTS_OPEN_EVT = 16 When connect to peer, the event comes
ESP_GATTS_CANCEL_OPEN_EVT = 17 When disconnect from peer, the event comes
ESP_GATTS_CLOSE_EVT = 18 When gatt server close, the event comes
ESP_GATTS_LISTEN_EVT = 19 When gatt listen to be connected the event comes
ESP_GATTS_CONGEST_EVT = 20 When congest happen, the event comes
ESP_GATTS_RESPONSE_EVT = 21 When gatt send response complete, the event comes
ESP_GATTS_CREAT_ATTR_TAB_EVT = 22 When gatt create table complete, the event comes
ESP_GATTS_SET_ATTR_VAL_EVT = 23 When gatt set attr value complete, the event comes
ESP_GATTS_SEND_SERVICE_CHANGE_EVT = 24 When gatt send service change indication complete, the event comes
GATT CLIENT API
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

Espressif Systems

128

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Functions esp_err_t esp_ble_gattc_register_callback(esp_gattc_cb_t callback)
This function is called to register application callbacks with GATTC module.

Return · ESP_OK: success · other: failed
Parameters · [in] callback: : pointer to the application callback function.
esp_err_t esp_ble_gattc_app_register(uint16_t app_id) This function is called to register application callbacks with GATTC module.

Return · ESP_OK: success · other: failed
Parameters · [in] app_id: : Application Identify (UUID), for different application

esp_err_t esp_ble_gattc_app_unregister(esp_gatt_if_t gattc_if) This function is called to unregister an application from GATTC module.

Return · ESP_OK: success · other: failed
Parameters · [in] gattc_if: Gatt client access interface.

esp_err_t esp_ble_gattc_open(esp_gatt_if_t

gattc_if,

esp_bd_addr_t

remote_bda,

esp_ble_addr_type_t remote_addr_type, bool is_direct)

Open a direct connection or add a background auto connection.

Return · ESP_OK: success · other: failed
Parameters · [in] 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

Espressif Systems

129

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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, wonnt get from remote devices. If want to get it from remote device, need to used the esp_ble_gattc_cache_refresh, then call esp_ble_gattc_get_service again.
Return · ESP_OK: success · other: failed
Parameters · [in] 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, wonnt 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, wonnt get from remote devices.

Espressif Systems

130

Release v5.0-dev-1424-g2467aa7f6c

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] 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, wonnt 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 · [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, wonnt 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)

Espressif Systems

131

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Find the descriptor with the given characteristic handle in the gattc cache Note: It just get descriptor from local cache, wonnt 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, wonnt 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] 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 isnnt ESP_GATT_DB_DESCRIPTOR, this parameter 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)

Espressif Systems

132

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

This function is called to get the GATT database. Note: It just get attribute data base from local cache, wonn 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 servicens 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. · [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 servicens 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 handle, esp_gatt_auth_req_t auth_req)
This function is called to read a characteristics descriptor.

Return

Espressif Systems

133

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

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

Espressif Systems

134

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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. · [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.

Espressif Systems

135

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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 devicens 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. ESP_GATTC_GET_ADDR_LIST_EVT event when get address list complete.

There will callback

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

Espressif Systems

136

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
struct esp_ble_gattc_cb_param_t::gattc_search_res_evt_param search_res Gatt client callback param of ESP_GATTC_SEARCH_RES_EVT
struct esp_ble_gattc_cb_param_t::gattc_read_char_evt_param read Gatt client callback param of ESP_GATTC_READ_CHAR_EVT
struct esp_ble_gattc_cb_param_t::gattc_write_evt_param write Gatt client callback param of ESP_GATTC_WRITE_DESCR_EVT
struct esp_ble_gattc_cb_param_t::gattc_exec_cmpl_evt_param exec_cmpl Gatt client callback param of ESP_GATTC_EXEC_EVT
struct esp_ble_gattc_cb_param_t::gattc_notify_evt_param notify Gatt client callback param of ESP_GATTC_NOTIFY_EVT
struct esp_ble_gattc_cb_param_t::gattc_srvc_chg_evt_param srvc_chg Gatt client callback param of ESP_GATTC_SRVC_CHG_EVT
struct esp_ble_gattc_cb_param_t::gattc_congest_evt_param congest Gatt client callback param of ESP_GATTC_CONGEST_EVT
struct esp_ble_gattc_cb_param_t::gattc_reg_for_notify_evt_param reg_for_notify Gatt client callback param of ESP_GATTC_REG_FOR_NOTIFY_EVT
struct esp_ble_gattc_cb_param_t::gattc_unreg_for_notify_evt_param unreg_for_notify Gatt client callback param of ESP_GATTC_UNREG_FOR_NOTIFY_EVT
struct esp_ble_gattc_cb_param_t::gattc_connect_evt_param connect Gatt client callback param of ESP_GATTC_CONNECT_EVT
struct esp_ble_gattc_cb_param_t::gattc_disconnect_evt_param disconnect Gatt client callback param of ESP_GATTC_DISCONNECT_EVT
struct esp_ble_gattc_cb_param_t::gattc_set_assoc_addr_cmp_evt_param set_assoc_cmp Gatt client callback param of ESP_GATTC_SET_ASSOC_EVT
struct esp_ble_gattc_cb_param_t::gattc_get_addr_list_evt_param get_addr_list Gatt client callback param of ESP_GATTC_GET_ADDR_LIST_EVT
struct esp_ble_gattc_cb_param_t::gattc_queue_full_evt_param queue_full Gatt client callback param of ESP_GATTC_QUEUE_FULL_EVT
struct esp_ble_gattc_cb_param_t::gattc_dis_srvc_cmpl_evt_param dis_srvc_cmpl Gatt client callback param of ESP_GATTC_DIS_SRVC_CMPL_EVT
struct gattc_cfg_mtu_evt_param #include <esp_gattc_api.h> ESP_GATTC_CFG_MTU_EVT.
Public Members
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.

Espressif Systems

137

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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.
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.

Espressif Systems

138

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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.

Espressif Systems

139

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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.
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.

Espressif Systems

140

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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.

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.

Espressif Systems

141

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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
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_ble_gattc_cb_param_t *param) GATT Client callback function type.

esp_gatt_if_t

gattc_if,

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

Espressif Systems

142

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_GATTC_SEARCH_RES_EVT = 7 When GATT service discovery result is got, the event comes
ESP_GATTC_READ_DESCR_EVT = 8 When GATT characteristic descriptor read completes, the event comes
ESP_GATTC_WRITE_DESCR_EVT = 9 When GATT characteristic descriptor write completes, the event comes
ESP_GATTC_NOTIFY_EVT = 10 When GATT notification or indication arrives, the event comes
ESP_GATTC_PREP_WRITE_EVT = 11 When GATT prepare-write operation completes, the event comes
ESP_GATTC_EXEC_EVT = 12 When write execution completes, the event comes
ESP_GATTC_ACL_EVT = 13 When ACL connection is up, the event comes
ESP_GATTC_CANCEL_OPEN_EVT = 14 When GATT client ongoing connection is cancelled, the event comes
ESP_GATTC_SRVC_CHG_EVT = 15 When oservice changedpoccurs, 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

Espressif Systems

143

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_GATTC_SCAN_FLT_CFG_EVT = 31 When Scan filter configuration completes, the event comes
ESP_GATTC_SCAN_FLT_PARAM_EVT = 32 When Scan filter parameters are set, the event comes
ESP_GATTC_SCAN_FLT_STATUS_EVT = 33 When Scan filter status is reported, the event comes
ESP_GATTC_ADV_VSC_EVT = 34 When advertising vendor spec content event is reported, the event comes
ESP_GATTC_REG_FOR_NOTIFY_EVT = 38 When register for notification of a service completes, the event comes
ESP_GATTC_UNREG_FOR_NOTIFY_EVT = 39 When unregister for notification of a service completes, the event comes
ESP_GATTC_CONNECT_EVT = 40 When the ble physical connection is set up, the event comes
ESP_GATTC_DISCONNECT_EVT = 41 When the ble physical connection disconnected, the event comes
ESP_GATTC_READ_MULTIPLE_EVT = 42 When the ble characteristic or descriptor multiple complete, the event comes
ESP_GATTC_QUEUE_FULL_EVT = 43 When the gattc command queue full, the event comes
ESP_GATTC_SET_ASSOC_EVT = 44 When the ble gattc set the associated address complete, the event comes
ESP_GATTC_GET_ADDR_LIST_EVT = 45 When the ble get gattc address list in cache finish, the event comes
ESP_GATTC_DIS_SRVC_CMPL_EVT = 46 When the ble discover service complete, the event comes
BLUFI API
Overview BLUFI is a profile based GATT to config ESP32 WIFI to connect/disconnect AP or setup a softap and etc. Use should concern these things:
1. The event sent from profile. Then you need to do something as the event indicate. 2. Security reference. You can write your own Security functions such as symmetrical encryption/decryption and
checksum functions. Even you can define the oKey Exchange/Negotiationpprocedure.
Application Example Check bluetooth folder in ESP-IDF examples, which contains the following application: · This is the BLUFI demo. This demo can set ESP32ns 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

Espressif Systems

144

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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 · 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.

Espressif Systems

145

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Public Members
struct esp_blufi_cb_param_t::blufi_init_finish_evt_param init_finish Blufi callback param of ESP_BLUFI_EVENT_INIT_FINISH
struct esp_blufi_cb_param_t::blufi_deinit_finish_evt_param deinit_finish Blufi callback param of ESP_BLUFI_EVENT_DEINIT_FINISH
struct esp_blufi_cb_param_t::blufi_set_wifi_mode_evt_param wifi_mode Blufi callback param of ESP_BLUFI_EVENT_INIT_FINISH
struct esp_blufi_cb_param_t::blufi_connect_evt_param connect Blufi callback param of ESP_BLUFI_EVENT_CONNECT
struct esp_blufi_cb_param_t::blufi_disconnect_evt_param disconnect Blufi callback param of ESP_BLUFI_EVENT_DISCONNECT
struct esp_blufi_cb_param_t::blufi_recv_sta_bssid_evt_param sta_bssid Blufi callback param of ESP_BLUFI_EVENT_RECV_STA_BSSID
struct esp_blufi_cb_param_t::blufi_recv_sta_ssid_evt_param sta_ssid Blufi callback param of ESP_BLUFI_EVENT_RECV_STA_SSID
struct esp_blufi_cb_param_t::blufi_recv_sta_passwd_evt_param sta_passwd Blufi callback param of ESP_BLUFI_EVENT_RECV_STA_PASSWD
struct esp_blufi_cb_param_t::blufi_recv_softap_ssid_evt_param softap_ssid Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_SSID
struct esp_blufi_cb_param_t::blufi_recv_softap_passwd_evt_param softap_passwd Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD
struct esp_blufi_cb_param_t::blufi_recv_softap_max_conn_num_evt_param softap_max_conn_num Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUM
struct esp_blufi_cb_param_t::blufi_recv_softap_auth_mode_evt_param softap_auth_mode Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE
struct esp_blufi_cb_param_t::blufi_recv_softap_channel_evt_param softap_channel Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL
struct esp_blufi_cb_param_t::blufi_recv_username_evt_param username Blufi callback param of ESP_BLUFI_EVENT_RECV_USERNAME
struct esp_blufi_cb_param_t::blufi_recv_ca_evt_param ca Blufi callback param of ESP_BLUFI_EVENT_RECV_CA_CERT
struct esp_blufi_cb_param_t::blufi_recv_client_cert_evt_param client_cert Blufi callback param of ESP_BLUFI_EVENT_RECV_CLIENT_CERT
struct esp_blufi_cb_param_t::blufi_recv_server_cert_evt_param server_cert Blufi callback param of ESP_BLUFI_EVENT_RECV_SERVER_CERT
struct esp_blufi_cb_param_t::blufi_recv_client_pkey_evt_param client_pkey Blufi callback param of ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY
struct esp_blufi_cb_param_t::blufi_recv_server_pkey_evt_param server_pkey Blufi callback param of ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY
struct esp_blufi_cb_param_t::blufi_get_error_evt_param report_error Blufi callback param of ESP_BLUFI_EVENT_REPORT_ERROR
struct esp_blufi_cb_param_t::blufi_recv_custom_data_evt_param custom_data Blufi callback param of ESP_BLUFI_EVENT_RECV_CUSTOM_DATA
struct blufi_connect_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_CONNECT.

Espressif Systems

146

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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.
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

Espressif Systems

147

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Public Members
uint8_t *cert Client certificate point
int cert_len Client certificate length
struct blufi_recv_client_pkey_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY
Public Members
uint8_t *pkey Client Private Key point, if Client certificate not contain Key
int pkey_len Client Private key length
struct blufi_recv_custom_data_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_CUSTOM_DATA.
Public Members
uint8_t *data Custom data
uint32_t data_len Custom data Length
struct blufi_recv_server_cert_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_SERVER_CERT
Public Members
uint8_t *cert Client certificate point
int cert_len Client certificate length
struct blufi_recv_server_pkey_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY
Public Members
uint8_t *pkey Client Private Key point, if Client certificate not contain Key
int pkey_len Client Private key length
struct blufi_recv_softap_auth_mode_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE.

Espressif Systems

148

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Public Members
wifi_auth_mode_t auth_mode Authentication mode
struct blufi_recv_softap_channel_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL.
Public Members
uint8_t channel Authentication mode
struct blufi_recv_softap_max_conn_num_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUM.
Public Members
int max_conn_num SSID
struct blufi_recv_softap_passwd_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD.
Public Members
uint8_t *passwd Password
int passwd_len Password Length
struct blufi_recv_softap_ssid_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_SOFTAP_SSID.
Public Members
uint8_t *ssid SSID
int ssid_len SSID length
struct blufi_recv_sta_bssid_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_STA_BSSID.
Public Members
uint8_t bssid[6] BSSID
struct blufi_recv_sta_passwd_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_STA_PASSWD.

Espressif Systems

149

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Public Members
uint8_t *passwd Password
int passwd_len Password Length
struct blufi_recv_sta_ssid_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_STA_SSID.
Public Members
uint8_t *ssid SSID
int ssid_len SSID length
struct blufi_recv_username_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_USERNAME.
Public Members
uint8_t *name Username point
int name_len Username length
struct blufi_set_wifi_mode_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_SET_WIFI_MODE.
Public Members
wifi_mode_t op_mode Wifi operation mode
Structures struct esp_blufi_extra_info_t
BLUFI extra information structure.
Public Members
uint8_t sta_bssid[6] BSSID of station interface
bool sta_bssid_set is BSSID of station interface set
uint8_t *sta_ssid SSID of station interface
int sta_ssid_len length of SSID of station interface
uint8_t *sta_passwd password of station interface

Espressif Systems

150

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
int sta_passwd_len length of password of station interface
uint8_t *softap_ssid SSID of softap interface
int softap_ssid_len length of SSID of softap interface
uint8_t *softap_passwd password of station interface
int softap_passwd_len length of password of station interface
uint8_t softap_authmode authentication mode of softap interface
bool softap_authmode_set is authentication mode of softap interface set
uint8_t softap_max_conn_num max connection number of softap interface
bool softap_max_conn_num_set is max connection number of softap interface set
uint8_t softap_channel channel of softap interface
bool softap_channel_set is channel of softap interface set
struct esp_blufi_ap_record_t Description of an WiFi AP.
Public Members
uint8_t ssid[33] SSID of AP
int8_t rssi signal strength of AP
struct esp_blufi_callbacks_t BLUFI callback functions type.
Public Members
esp_blufi_event_cb_t event_cb BLUFI event callback
esp_blufi_negotiate_data_handler_t negotiate_data_handler BLUFI negotiate data function for negotiate share key
esp_blufi_encrypt_func_t encrypt_func BLUFI encrypt data function with share key generated by negotiate_data_handler
esp_blufi_decrypt_func_t decrypt_func BLUFI decrypt data function with share key generated by negotiate_data_handler
esp_blufi_checksum_func_t checksum_func BLUFI check sum function (FCS)

Espressif Systems

151

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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
*param) BLUFI event callback function type.

event,

esp_blufi_cb_param_t

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,

BLUFI negotiate data handler.

bool *need_free)

Parameters · data: : data from phone · len: : length of data from phone · output_data: : data want to send to phone · output_len: : length of data want to send to phone · need_free: : output reporting if memory needs to be freed or not *

typedef int (*esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len) BLUFI encrypt the data after negotiate a share key.

Return Nonnegative number is encrypted length, if error, return negative number; Parameters
· iv8: : initial vector(8bit), normally, blufi core will input packet sequence number · crypt_data: : plain text and encrypted data, the encrypt function must support autochthonous
encrypt · crypt_len: : length of plain text

typedef int (*esp_blufi_decrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len) BLUFI decrypt the data after negotiate a share key.

Return Nonnegative number is decrypted length, if error, return negative number; Parameters
· 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

Espressif Systems

152

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_BLUFI_EVENT_SET_WIFI_OPMODE ESP_BLUFI_EVENT_BLE_CONNECT ESP_BLUFI_EVENT_BLE_DISCONNECT ESP_BLUFI_EVENT_REQ_CONNECT_TO_AP ESP_BLUFI_EVENT_REQ_DISCONNECT_FROM_AP ESP_BLUFI_EVENT_GET_WIFI_STATUS ESP_BLUFI_EVENT_DEAUTHENTICATE_STA ESP_BLUFI_EVENT_RECV_STA_BSSID ESP_BLUFI_EVENT_RECV_STA_SSID ESP_BLUFI_EVENT_RECV_STA_PASSWD ESP_BLUFI_EVENT_RECV_SOFTAP_SSID ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUM ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL ESP_BLUFI_EVENT_RECV_USERNAME ESP_BLUFI_EVENT_RECV_CA_CERT ESP_BLUFI_EVENT_RECV_CLIENT_CERT ESP_BLUFI_EVENT_RECV_SERVER_CERT ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY ESP_BLUFI_EVENT_RECV_SLAVE_DISCONNECT_BLE ESP_BLUFI_EVENT_GET_WIFI_LIST ESP_BLUFI_EVENT_REPORT_ERROR ESP_BLUFI_EVENT_RECV_CUSTOM_DATA enum esp_blufi_sta_conn_state_t BLUFI config status. Values: ESP_BLUFI_STA_CONN_SUCCESS = 0x00 ESP_BLUFI_STA_CONN_FAIL = 0x01 enum esp_blufi_init_state_t BLUFI init status. Values: ESP_BLUFI_INIT_OK = 0 ESP_BLUFI_INIT_FAILED enum esp_blufi_deinit_state_t BLUFI deinit status. Values: ESP_BLUFI_DEINIT_OK = 0 ESP_BLUFI_DEINIT_FAILED

Espressif Systems

153

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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 NimBLE-based host APIs
Overview
Apache MyNewt NimBLE is a highly configurable and BT SIG qualifiable BLE stack providing both host and controller 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. However, 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 requirements.

Fig. 1: ESP NimBLE Stack

Threading Model
The NimBLE host can run inside the application thread or can have its own independent thread. This flexibility is inherently provided by NimBLE design. By default, a thread is spawned by the porting function nimble_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.

Espressif Systems

154

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Programming Sequence
To begin with, make sure that the NimBLE stack is enabled from menuconfig choose NimBLE for the Bluetooth host.
Typical programming sequence with NimBLE stack consists of the following steps: · Initialize NVS flash using nvs_flash_init() API. This is because ESP controller uses NVS during initialization. · Call esp_nimble_hci_and_controller_init() to initialize ESP controller as well as transport 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

(continues on next page)

Espressif Systems

155

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
(continued from previous page)
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 nimble_port_run() will run the NimBLE host in the current task. Return
· ESP_OK if the initialization is successful · Appropriate error code from esp_err_t in case of an error esp_err_t esp_nimble_hci_deinit(void) Deinitialize VHCI transport layer between NimBLE Host and ESP Bluetooth controller. Note This function should be called after the NimBLE host is deinitialized. Return · ESP_OK if the deinitialization is successful · Appropriate error codes from esp_err_t in case of an error esp_err_t esp_nimble_hci_and_controller_deinit(void) Deinitialize VHCI transport layer between NimBLE Host and ESP Bluetooth controller and disable and deinitialize 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.5 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.

Espressif Systems

156

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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-BLEMESH Provisioner, which could provision unprovisioned devices into ESP-BLE-MESH nodes and configure the nodes with various features. For information how to start using ESP32 and ESP-BLE-MESH, please see the Section Getting Started with ESPBLE-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

Espressif Systems

157

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_link_close_evt_param node_prov_link_close Event parameter of ESP_BLE_MESH_NODE_PROV_LINK_CLOSE_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_output_num_evt_param node_prov_output_num Event parameter of ESP_BLE_MESH_NODE_PROV_OUTPUT_NUMBER_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_output_str_evt_param node_prov_output_str Event parameter of ESP_BLE_MESH_NODE_PROV_OUTPUT_STRING_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_input_evt_param node_prov_input Event parameter of ESP_BLE_MESH_NODE_PROV_INPUT_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provision_complete_evt_param node_prov_complete Event parameter of ESP_BLE_MESH_NODE_PROV_COMPLETE_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provision_reset_param node_prov_reset Event parameter of ESP_BLE_MESH_NODE_PROV_RESET_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_set_oob_pub_key_comp_param node_prov_set_oob_pub_key_co Event parameter of ESP_BLE_MESH_NODE_PROV_SET_OOB_PUB_KEY_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_input_number_comp_param node_prov_input_num_comp Event parameter of ESP_BLE_MESH_NODE_PROV_INPUT_NUM_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_input_string_comp_param node_prov_input_str_comp Event parameter of ESP_BLE_MESH_NODE_PROV_INPUT_STR_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_identity_enable_comp_param node_proxy_identity_enabl Event parameter of ESP_BLE_MESH_NODE_PROXY_IDENTITY_ENABLE_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_gatt_enable_comp_param node_proxy_gatt_enable_comp Event parameter of ESP_BLE_MESH_NODE_PROXY_GATT_ENABLE_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_gatt_disable_comp_param node_proxy_gatt_disable_com Event parameter of ESP_BLE_MESH_NODE_PROXY_GATT_DISABLE_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_node_add_local_net_key_comp_param node_add_net_key_comp Event parameter of ESP_BLE_MESH_NODE_ADD_LOCAL_NET_KEY_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_node_add_local_app_key_comp_param node_add_app_key_comp Event parameter of ESP_BLE_MESH_NODE_ADD_LOCAL_APP_KEY_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_node_bind_local_mod_app_comp_param node_bind_app_key_to_ Event parameter of ESP_BLE_MESH_NODE_BIND_APP_KEY_TO_MODEL_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_recv_unprov_adv_pkt_param provisioner_recv_unpr Event parameter of ESP_BLE_MESH_PROVISIONER_RECV_UNPROV_ADV_PKT_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_enable_comp_param provisioner_prov_enable Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_ENABLE_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_disable_comp_param provisioner_prov_disabl Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_DISABLE_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_link_open_evt_param provisioner_prov_link_open Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_LINK_OPEN_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_read_oob_pub_key_evt_param provisioner_prov Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_READ_OOB_PUB_KEY_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_input_evt_param provisioner_prov_input Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_INPUT_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_output_evt_param provisioner_prov_output Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_OUTPUT_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_link_close_evt_param provisioner_prov_link_clos Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_LINK_CLOSE_EVT

Espressif Systems

158

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

159

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

160

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
char uid[ESP_BLE_MESH_SETTINGS_UID_SIZE + 1] Provisioner settings user id
struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_open_settings_with_uid_comp ESP_BLE_MESH_PROVISIONER_OPEN_SETTINGS_WITH_UID_COMP_EVT.
Event parameters of ESP_BLE_MESH_PROVISIONER_OPEN_SETTINGS_WITH_UID_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_close_settings_with_index_comp ESP_BLE_MESH_PROVISIONER_CLOSE_SETTINGS_WITH_INDEX_COMP_EVT.
Event parameter of ESP_BLE_MESH_PROVISIONER_CLOSE_SETTINGS_WITH_INDEX_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_close_settings_with_uid_comp ESP_BLE_MESH_PROVISIONER_CLOSE_SETTINGS_WITH_UID_COMP_EVT.
Event parameters of ESP_BLE_MESH_PROVISIONER_CLOSE_SETTINGS_WITH_UID_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_delete_settings_with_index_comp ESP_BLE_MESH_PROVISIONER_DELETE_SETTINGS_WITH_INDEX_COMP_EVT.
Event parameter of ESP_BLE_MESH_PROVISIONER_DELETE_SETTINGS_WITH_INDEX_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_delete_settings_with_uid_comp ESP_BLE_MESH_PROVISIONER_DELETE_SETTINGS_WITH_UID_COMP_EVT.
Event parameters of ESP_BLE_MESH_PROVISIONER_DELETE_SETTINGS_WITH_UID_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_set_fast_prov_info_comp_param set_fast_prov_info_comp Event parameter of ESP_BLE_MESH_SET_FAST_PROV_INFO_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_set_fast_prov_action_comp_param set_fast_prov_action_comp Event parameter of ESP_BLE_MESH_SET_FAST_PROV_ACTION_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_heartbeat_msg_recv_param heartbeat_msg_recv Event parameter of ESP_BLE_MESH_HEARTBEAT_MESSAGE_RECV_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_enable_comp_param lpn_enable_comp Event parameter of ESP_BLE_MESH_LPN_ENABLE_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_disable_comp_param lpn_disable_comp Event parameter of ESP_BLE_MESH_LPN_DISABLE_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_poll_comp_param lpn_poll_comp Event parameter of ESP_BLE_MESH_LPN_POLL_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_friendship_establish_param lpn_friendship_establish Event parameter of ESP_BLE_MESH_LPN_FRIENDSHIP_ESTABLISH_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_friendship_terminate_param lpn_friendship_terminate Event parameter of ESP_BLE_MESH_LPN_FRIENDSHIP_TERMINATE_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_friend_friendship_establish_param frnd_friendship_establish Event parameter of ESP_BLE_MESH_FRIEND_FRIENDSHIP_ESTABLISH_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_friend_friendship_terminate_param frnd_friendship_terminate Event parameter of ESP_BLE_MESH_FRIEND_FRIENDSHIP_TERMINATE_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_recv_adv_pkt_param proxy_client_recv_adv_pkt Event parameter of ESP_BLE_MESH_PROXY_CLIENT_RECV_ADV_PKT_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_connected_param proxy_client_connected Event parameter of ESP_BLE_MESH_PROXY_CLIENT_CONNECTED_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_disconnected_param proxy_client_disconnected Event parameter of ESP_BLE_MESH_PROXY_CLIENT_DISCONNECTED_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_recv_filter_status_param proxy_client_recv_filte Event parameter of ESP_BLE_MESH_PROXY_CLIENT_RECV_FILTER_STATUS_EVT

Espressif Systems

161

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_connect_comp_param proxy_client_connect_comp Event parameter of ESP_BLE_MESH_PROXY_CLIENT_CONNECT_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_disconnect_comp_param proxy_client_disconnect Event parameter of ESP_BLE_MESH_PROXY_CLIENT_DISCONNECT_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_set_filter_type_comp_param proxy_client_set_filt Event parameter of ESP_BLE_MESH_PROXY_CLIENT_SET_FILTER_TYPE_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_add_filter_addr_comp_param proxy_client_add_fil Event parameter of ESP_BLE_MESH_PROXY_CLIENT_ADD_FILTER_ADDR_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_remove_filter_addr_comp_param proxy_client_remov Event parameter of ESP_BLE_MESH_PROXY_CLIENT_REMOVE_FILTER_ADDR_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_model_sub_group_addr_comp_param model_sub_group_addr_co Event parameters of ESP_BLE_MESH_MODEL_SUBSCRIBE_GROUP_ADDR_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_model_unsub_group_addr_comp_param model_unsub_group_addr Event parameters of ESP_BLE_MESH_MODEL_UNSUBSCRIBE_GROUP_ADDR_COMP_EVT
struct esp_ble_mesh_prov_cb_param_t::ble_mesh_deinit_mesh_comp_param deinit_mesh_comp Event parameter of ESP_BLE_MESH_DEINIT_MESH_COMP_EVT
struct ble_mesh_deinit_mesh_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_DEINIT_MESH_COMP_EVT.

Public Members
int err_code Indicate the result of BLE Mesh deinitialization
struct ble_mesh_friend_friendship_establish_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_FRIEND_FRIENDSHIP_ESTABLISH_EVT.

Public Members
uint16_t lpn_addr Low Power Node unicast address
struct ble_mesh_friend_friendship_terminate_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_FRIEND_FRIENDSHIP_TERMINATE_EVT.

Public Types
enum [anonymous] This enum value is the reason of friendship termination on the friend node side
Values:
ESP_BLE_MESH_FRND_FRIENDSHIP_TERMINATE_ESTABLISH_FAIL Friend Offer has been sent, but Friend Offer is not received within 1 second, friendship fails to be established
ESP_BLE_MESH_FRND_FRIENDSHIP_TERMINATE_POLL_TIMEOUT Friendship is established, PollTimeout timer expires and no Friend Poll/Sub Add/Sub Remove is received
ESP_BLE_MESH_FRND_FRIENDSHIP_TERMINATE_RECV_FRND_REQ Receive Friend Request from existing Low Power Node
ESP_BLE_MESH_FRND_FRIENDSHIP_TERMINATE_RECV_FRND_CLEAR Receive Friend Clear from other friend node

Espressif Systems

162

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_BLE_MESH_FRND_FRIENDSHIP_TERMINATE_DISABLE Friend feature disabled or corresponding NetKey is deleted
Public Members
uint16_t lpn_addr Low Power Node unicast address
esp_ble_mesh_prov_cb_param_t::ble_mesh_friend_friendship_terminate_param::[anonymous] reason This enum value is the reason of friendship termination on the friend node side Friendship terminated reason
struct ble_mesh_heartbeat_msg_recv_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_HEARTBEAT_MESSAGE_RECV_EVT.
Public Members
uint8_t hops Heartbeat hops (InitTTL - RxTTL + 1)
uint16_t feature Bit field of currently active features of the node
struct ble_mesh_input_evt_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_INPUT_EVT.
Public Members
esp_ble_mesh_input_action_t action Action of Input OOB Authentication
uint8_t size Size of Input OOB Authentication
struct ble_mesh_input_number_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_INPUT_NUM_COMP_EVT.
Public Members
int err_code Indicate the result of inputting number
struct ble_mesh_input_string_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_INPUT_STR_COMP_EVT.
Public Members
int err_code Indicate the result of inputting string
struct ble_mesh_link_close_evt_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_LINK_CLOSE_EVT.

Espressif Systems

163

Release v5.0-dev-1424-g2467aa7f6c

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 closed
struct ble_mesh_link_open_evt_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_LINK_OPEN_EVT.
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.

Espressif Systems

164

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Public Members
int err_code Indicate the result of local model subscribing group address
uint16_t element_addr Element address
uint16_t company_id Company ID
uint16_t model_id Model ID
uint16_t group_addr Group Address
struct ble_mesh_model_unsub_group_addr_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_MODEL_UNSUBSCRIBE_GROUP_ADDR_COMP_EVT.
Public Members
int err_code Indicate the result of local model unsubscribing group address
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

Espressif Systems

165

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
struct ble_mesh_node_bind_local_mod_app_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_BIND_APP_KEY_TO_MODEL_COMP_EVT.
Public Members
int err_code Indicate the result of binding AppKey with model by the node
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

166

Release v5.0-dev-1424-g2467aa7f6c

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

167

Release v5.0-dev-1424-g2467aa7f6c

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

168

Release v5.0-dev-1424-g2467aa7f6c

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

169

Release v5.0-dev-1424-g2467aa7f6c

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

170

Release v5.0-dev-1424-g2467aa7f6c

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

171

Release v5.0-dev-1424-g2467aa7f6c

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

172

Release v5.0-dev-1424-g2467aa7f6c

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

173

Release v5.0-dev-1424-g2467aa7f6c

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

174

Release v5.0-dev-1424-g2467aa7f6c

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

175

Release v5.0-dev-1424-g2467aa7f6c

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

176

Release v5.0-dev-1424-g2467aa7f6c

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

177

Release v5.0-dev-1424-g2467aa7f6c

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

178

Release v5.0-dev-1424-g2467aa7f6c

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

179

Release v5.0-dev-1424-g2467aa7f6c

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. bt_mesh_model_pub in mesh_access.h

This structure is associated with struct

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

180

Release v5.0-dev-1424-g2467aa7f6c

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. bt_mesh_model_op in mesh_access.h

This structure is associated with struct

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. bt_mesh_model_cb in mesh_access.h.

This structure is associated with struct

Public Members
esp_ble_mesh_cb_t init_cb Callback used during model initialization. Initialized by the stack.

Espressif Systems

181

Release v5.0-dev-1424-g2467aa7f6c

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

182

Release v5.0-dev-1424-g2467aa7f6c

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

183

Release v5.0-dev-1424-g2467aa7f6c

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

184

Release v5.0-dev-1424-g2467aa7f6c

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

185

Release v5.0-dev-1424-g2467aa7f6c

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 oset_auto_rsppto ESP_BLE_MESH_SERVER_RSP_BY_APP, the handler of the timer shall be initialized by the users.

Espressif Systems

186

Release v5.0-dev-1424-g2467aa7f6c

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

187

Release v5.0-dev-1424-g2467aa7f6c

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

188

Release v5.0-dev-1424-g2467aa7f6c

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

189

Release v5.0-dev-1424-g2467aa7f6c

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

190

Release v5.0-dev-1424-g2467aa7f6c

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

191

Release v5.0-dev-1424-g2467aa7f6c

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

192

Release v5.0-dev-1424-g2467aa7f6c

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

193

Release v5.0-dev-1424-g2467aa7f6c

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

194

Release v5.0-dev-1424-g2467aa7f6c

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

195

Release v5.0-dev-1424-g2467aa7f6c

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

196

Release v5.0-dev-1424-g2467aa7f6c

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

197

Release v5.0-dev-1424-g2467aa7f6c

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

198

Release v5.0-dev-1424-g2467aa7f6c

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

199

Release v5.0-dev-1424-g2467aa7f6c

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

200

Release v5.0-dev-1424-g2467aa7f6c

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

201

Release v5.0-dev-1424-g2467aa7f6c

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

202

Release v5.0-dev-1424-g2467aa7f6c

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

203

Release v5.0-dev-1424-g2467aa7f6c

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

204

Release v5.0-dev-1424-g2467aa7f6c

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

205

Release v5.0-dev-1424-g2467aa7f6c

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 completion event

Espressif Systems

206

Release v5.0-dev-1424-g2467aa7f6c

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

207

Release v5.0-dev-1424-g2467aa7f6c

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

208

Release v5.0-dev-1424-g2467aa7f6c

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

209

Release v5.0-dev-1424-g2467aa7f6c

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

210

Release v5.0-dev-1424-g2467aa7f6c

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

211

Release v5.0-dev-1424-g2467aa7f6c

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

212

Release v5.0-dev-1424-g2467aa7f6c

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

213

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t esp_ble_mesh_register_custom_model_callback(esp_ble_mesh_model_cb_t callback)
Register BLE Mesh callback for user-defined modelsnoperations. 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 message.

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

214

Release v5.0-dev-1424-g2467aa7f6c

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-

Send a model publication message.

vice_role)

Note Before calling this function, the user needs to ensure that the model publication 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

215

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· [in] index: Index of the node in the node queue. · [in] name: Name (end by m\0n) 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 m\0n).

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 unicast_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 m\0n).

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 oforploop combined with the macro CONFIG_BLE_MESH_MAX_PROV_NODES to get each nodens information. Before trying to read the nodens 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

216

Release v5.0-dev-1424-g2467aa7f6c

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) { ll} } ``` 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

This function is called by Provisioner to get the local app key value.

app_idx)

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

217

Release v5.0-dev-1424-g2467aa7f6c

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],

This function is called by Provisioner to add local network key.

uint16_t net_idx)

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],

This function is called by Provisioner to update a local network key.

uint16_t net_idx)

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 oREMOVEp, the ohb_srcpcan be set to the SRC (can only be a unicast address) of heartbeat messages, and the ohb_dstpcan 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 oADDp, the ohb_srcpcan be set to the SRC (can only be a unicast address) of heartbeat messages, and the ohb_dstpcan be set to the DST (unicast address or group address), at least one of them needs to be set.

Espressif Systems

218

Release v5.0-dev-1424-g2467aa7f6c

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 oerasepflag is set to false, the mesh information will be cleaned (e.g. removing NetKey, AppKey, nodes, etc) from the mesh stack. b) If the oerasepflag 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) ll
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 oerasepflag is set to false, the mesh information will be cleaned (e.g. removing NetKey, AppKey,

Espressif Systems

219

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

nodes, etc) from the mesh stack. b) If the oerasepflag 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) ll 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

220

Release v5.0-dev-1424-g2467aa7f6c

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 devicens Public Key X · [in] pub_key_y: Unprovisioned devicens Public Key Y · [in] private_key: Unprovisioned devicens 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

221

Release v5.0-dev-1424-g2467aa7f6c

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 doesnnt 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,
pub_key_x[32],
pub_key_y[32]) Provisioner inputs unprovisioned devicens oob public key.

uint8_t uint8_t

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 devicens Public Key X · [in] pub_key_y: Unprovisioned devicens 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.

Espressif Systems

222

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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.

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

Espressif Systems

223

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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 oesp_ble_mesh_provisioner_add_unprov_devpand oesp_ble_mesh_provisioner_prov_device_with_addrpby a Provisioner.
Parameters · [in] uuid: Device UUID of the unprovisioned device · [in] addr: Device address of the unprovisioned device · [in] addr_type: Device address type of the unprovisioned device · [in] bearer: Provisioning bearer going to be used by Provisioner · [in] oob_info: OOB info of the unprovisioned device · [in] unicast_addr: Unicast address going to be allocated for the unprovisioned device
esp_err_t esp_ble_mesh_provisioner_delete_dev(esp_ble_mesh_device_delete_t *del_dev) Delete device from queue, and reset current provisioning link with the device.
Note If the device is in the queue, remove it from the queue; if the device is being provisioned, terminate the provisioning procedure. Either one of the device address or device UUID can be used as input.
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 bruteforce 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.

Espressif Systems

224

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t esp_ble_mesh_provisioner_set_primary_elem_addr(uint16_t addr) This function is called by Provisioner to set own Primary element address.
Note This API must be invoked when BLE Mesh initialization is completed successfully, and can be invoked before Provisioner functionality is enabled. Once this API is invoked successfully, the prov_unicast_addr value in the struct esp_ble_mesh_prov_t will be ignored, and Provisioner will use this address as its own primary element address. And if the unicast address going to assigned for the next unprovisioned device 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.

Espressif Systems

225

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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.

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

Proxy Client adds address to the Proxy Server filter list.

addr_num)

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,

Proxy Client removes address from the Proxy Server filter list.

uint16_t addr_num)

Return ESP_OK on success or error code otherwise. Parameters

Espressif Systems

226

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· [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-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

Register BLE Mesh Config Client Model callback.

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

Register BLE Mesh Config Server Model callback.

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.

Espressif Systems

227

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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. · [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.

Espressif Systems

228

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

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

Espressif Systems

229

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

230

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

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

Espressif Systems

231

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Structures struct esp_ble_mesh_cfg_srv
Configuration Server Model context
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

Espressif Systems

232

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
esp_ble_mesh_cb_t heartbeat_recv_cb Optional heartbeat subscription tracking function
struct esp_ble_mesh_cfg_srv::[anonymous] heartbeat_sub Heartbeat Subscription
struct esp_ble_mesh_cfg_composition_data_get_t Parameters of Config Composition Data Get.
Public Members
uint8_t page Page number of the Composition Data.
struct esp_ble_mesh_cfg_model_pub_get_t Parameters of Config Model Publication Get.
Public Members
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.

Espressif Systems

233

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Public Members
uint16_t net_idx The network key index
struct esp_ble_mesh_cfg_node_identity_get_t Parameters of Config Node Identity Get.
Public Members
uint16_t net_idx 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.

Espressif Systems

234

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Public Members
uint8_t beacon New Secure Network Beacon state
struct esp_ble_mesh_cfg_default_ttl_set_t Parameters of Config Default TTL Set.
Public Members
uint8_t ttl The default TTL state value
struct esp_ble_mesh_cfg_friend_set_t Parameters of Config Friend Set.
Public Members
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.

Espressif Systems

235

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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.
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.

Espressif Systems

236

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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.
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

Espressif Systems

237

Release v5.0-dev-1424-g2467aa7f6c

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

Espressif Systems

238

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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.

Espressif Systems

239

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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.
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.

Espressif Systems

240

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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.
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

Espressif Systems

241

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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 retransmissions)
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

Espressif Systems

242

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

243

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

244

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

245

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

246

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

247

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

uint16_t model_id Model ID
struct esp_ble_mesh_state_change_cfg_netkey_add_t Parameters of Config NetKey Add

Public Members
uint16_t net_idx NetKey Index
uint8_t net_key[16] NetKey
struct esp_ble_mesh_state_change_cfg_netkey_update_t Parameters of Config NetKey Update

Public Members
uint16_t net_idx NetKey Index
uint8_t net_key[16] NetKey
struct esp_ble_mesh_state_change_cfg_netkey_delete_t Parameter of Config NetKey Delete

Public Members
uint16_t net_idx NetKey Index
struct esp_ble_mesh_state_change_cfg_appkey_add_t Parameters of Config AppKey Add

Public Members
uint16_t net_idx NetKey Index
uint16_t app_idx AppKey Index
uint8_t app_key[16] AppKey
struct esp_ble_mesh_state_change_cfg_appkey_update_t Parameters of Config AppKey Update

Public Members
uint16_t net_idx NetKey Index
uint16_t app_idx AppKey Index
uint8_t app_key[16] AppKey

Espressif Systems

248

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

249

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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.

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

Espressif Systems

250

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Register BLE Mesh Health Server Model callback.

callback)

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

Espressif Systems

251

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· [in] element: The element to which the Health Server Model belongs.

Unions union esp_ble_mesh_health_client_get_state_t
#include <esp_ble_mesh_health_model_api.h> For ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_GET ESP_BLE_MESH_MODEL_OP_ATTENTION_GET ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_GET the get_state parameter in the esp_ble_mesh_health_client_get_state function should not be set to NULL.

Public Members
esp_ble_mesh_health_fault_get_t fault_get For ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_GET.
union esp_ble_mesh_health_client_set_state_t #include <esp_ble_mesh_health_model_api.h> For ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_CLEAR ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_CLEAR_UNACK ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_TEST_UNACK ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_ ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_SET_UNACK ESP_BLE_MESH_MODEL_OP_ATTENTION_SET ESP_BLE_MESH_MODEL_OP_ATTENTION_SET_UNACK the set_state parameter in the esp_ble_mesh_health_client_set_state function should not be set to NULL.

Public Members

esp_ble_mesh_health_attention_set_t attention_set For ESP_BLE_MESH_MODEL_OP_ATTENTION_SET or ESP_BLE_MESH_MODEL_OP_ATTENTION_SET_UNA

esp_ble_mesh_health_period_set_t period_set

For

ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_SET

or

ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_SET_UNACK.

esp_ble_mesh_health_fault_test_t fault_test

For

ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_TEST

or

ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_TEST_UNACK.

esp_ble_mesh_health_fault_clear_t fault_clear

For

ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_CLEAR

or

ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_CLEAR_UNACK.

union esp_ble_mesh_health_client_common_cb_param_t #include <esp_ble_mesh_health_model_api.h> Health Client Model received message union.

Public Members
esp_ble_mesh_health_current_status_cb_t current_status The health current status value
esp_ble_mesh_health_fault_status_cb_t fault_status The health fault status value
esp_ble_mesh_health_period_status_cb_t period_status The health period status value
esp_ble_mesh_health_attention_status_cb_t attention_status The health attention status value
union esp_ble_mesh_health_server_cb_param_t #include <esp_ble_mesh_health_model_api.h> Health Server Model callback parameters union.

Espressif Systems

252

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Public Members
esp_ble_mesh_health_fault_update_comp_cb_t fault_update_comp ESP_BLE_MESH_HEALTH_SERVER_FAULT_UPDATE_COMP_EVT
esp_ble_mesh_health_fault_clear_cb_t fault_clear ESP_BLE_MESH_HEALTH_SERVER_FAULT_CLEAR_EVT
esp_ble_mesh_health_fault_test_cb_t fault_test ESP_BLE_MESH_HEALTH_SERVER_FAULT_TEST_EVT
esp_ble_mesh_health_attention_on_cb_t attention_on ESP_BLE_MESH_HEALTH_SERVER_ATTENTION_ON_EVT
esp_ble_mesh_health_attention_off_cb_t attention_off ESP_BLE_MESH_HEALTH_SERVER_ATTENTION_OFF_EVT
Structures struct esp_ble_mesh_health_srv_cb_t
ESP BLE Mesh Health Server callback
Public Members
esp_ble_mesh_cb_t fault_clear Clear health registered faults. Initialized by the stack.
esp_ble_mesh_cb_t fault_test Run a specific health test. Initialized by the stack.
esp_ble_mesh_cb_t attention_on Health attention on callback. Initialized by the stack.
esp_ble_mesh_cb_t attention_off Health attention off callback. Initialized by the stack.
struct esp_ble_mesh_health_test_t ESP BLE Mesh Health Server test Context
Public Members
uint8_t id_count Number of Health self-test ID
const uint8_t *test_ids Array of Health self-test IDs
uint16_t company_id Company ID used to identify the Health Fault state
uint8_t prev_test_id Current test ID of the health fault test
uint8_t current_faults[ESP_BLE_MESH_HEALTH_FAULT_ARRAY_SIZE] Array of current faults
uint8_t registered_faults[ESP_BLE_MESH_HEALTH_FAULT_ARRAY_SIZE] Array of registered faults
struct esp_ble_mesh_health_srv_t ESP BLE Mesh Health Server Model Context

Espressif Systems

253

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

254

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

255

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

256

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Macros ESP_BLE_MESH_MODEL_HEALTH_SRV(srv, pub)
Define a new Health Server Model.
Note The Health Server Model can only be included by a Primary Element. Return New Health Server Model instance. Parameters
· srv: Pointer to the unique struct esp_ble_mesh_health_srv_t. · pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. ESP_BLE_MESH_MODEL_HEALTH_CLI(cli_data) Define a new Health Client Model.
Note This API needs to be called for each element on which the application needs to have a Health Client Model.
Return New Health Client Model instance. Parameters
· cli_data: Pointer to the unique struct esp_ble_mesh_client_t.
ESP_BLE_MESH_HEALTH_PUB_DEFINE(_name, _max, _role) A helper to define a health publication context
Parameters · _name: Name given to the publication context variable. · _max: Maximum number of faults the element can have. · _role: Role of the device which contains the model.
ESP_BLE_MESH_HEALTH_STANDARD_TEST SIG identifier of Health Fault Test. 0x01 ~ 0xFF: Vendor Specific Test.
ESP_BLE_MESH_NO_FAULT Fault values of Health Fault Test. 0x33 ~ 0x7F: Reserved for Future Use. 0x80 ~ 0xFF: Vendor Specific Warning/Error.
ESP_BLE_MESH_BATTERY_LOW_WARNING
ESP_BLE_MESH_BATTERY_LOW_ERROR
ESP_BLE_MESH_SUPPLY_VOLTAGE_TOO_LOW_WARNING
ESP_BLE_MESH_SUPPLY_VOLTAGE_TOO_LOW_ERROR
ESP_BLE_MESH_SUPPLY_VOLTAGE_TOO_HIGH_WARNING
ESP_BLE_MESH_SUPPLY_VOLTAGE_TOO_HIGH_ERROR
ESP_BLE_MESH_POWER_SUPPLY_INTERRUPTED_WARNING
ESP_BLE_MESH_POWER_SUPPLY_INTERRUPTED_ERROR
ESP_BLE_MESH_NO_LOAD_WARNING
ESP_BLE_MESH_NO_LOAD_ERROR
ESP_BLE_MESH_OVERLOAD_WARNING
ESP_BLE_MESH_OVERLOAD_ERROR
ESP_BLE_MESH_OVERHEAT_WARNING
ESP_BLE_MESH_OVERHEAT_ERROR
ESP_BLE_MESH_CONDENSATION_WARNING
ESP_BLE_MESH_CONDENSATION_ERROR
ESP_BLE_MESH_VIBRATION_WARNING
ESP_BLE_MESH_VIBRATION_ERROR
ESP_BLE_MESH_CONFIGURATION_WARNING

Espressif Systems

257

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_BLE_MESH_CONFIGURATION_ERROR ESP_BLE_MESH_ELEMENT_NOT_CALIBRATED_WARNING ESP_BLE_MESH_ELEMENT_NOT_CALIBRATED_ERROR ESP_BLE_MESH_MEMORY_WARNING ESP_BLE_MESH_MEMORY_ERROR ESP_BLE_MESH_SELF_TEST_WARNING ESP_BLE_MESH_SELF_TEST_ERROR ESP_BLE_MESH_INPUT_TOO_LOW_WARNING ESP_BLE_MESH_INPUT_TOO_LOW_ERROR ESP_BLE_MESH_INPUT_TOO_HIGH_WARNING ESP_BLE_MESH_INPUT_TOO_HIGH_ERROR ESP_BLE_MESH_INPUT_NO_CHANGE_WARNING ESP_BLE_MESH_INPUT_NO_CHANGE_ERROR ESP_BLE_MESH_ACTUATOR_BLOCKED_WARNING ESP_BLE_MESH_ACTUATOR_BLOCKED_ERROR ESP_BLE_MESH_HOUSING_OPENED_WARNING ESP_BLE_MESH_HOUSING_OPENED_ERROR ESP_BLE_MESH_TAMPER_WARNING ESP_BLE_MESH_TAMPER_ERROR ESP_BLE_MESH_DEVICE_MOVED_WARNING ESP_BLE_MESH_DEVICE_MOVED_ERROR ESP_BLE_MESH_DEVICE_DROPPED_WARNING ESP_BLE_MESH_DEVICE_DROPPED_ERROR ESP_BLE_MESH_OVERFLOW_WARNING ESP_BLE_MESH_OVERFLOW_ERROR ESP_BLE_MESH_EMPTY_WARNING ESP_BLE_MESH_EMPTY_ERROR ESP_BLE_MESH_INTERNAL_BUS_WARNING ESP_BLE_MESH_INTERNAL_BUS_ERROR ESP_BLE_MESH_MECHANISM_JAMMED_WARNING ESP_BLE_MESH_MECHANISM_JAMMED_ERROR ESP_BLE_MESH_HEALTH_FAULT_ARRAY_SIZE
Type Definitions typedef void (*esp_ble_mesh_health_client_cb_t)(esp_ble_mesh_health_client_cb_event_t
event, esp_ble_mesh_health_client_cb_param_t *param) Bluetooth Mesh Health Client and Server Model function. Health Client Model callback function type Parameters · event: Event type

Espressif Systems

258

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Register BLE Mesh Generic Client Model callback.

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

Espressif Systems

259

Release v5.0-dev-1424-g2467aa7f6c

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

Register BLE Mesh Generic Server Model callback.

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.

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

Espressif Systems

260

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_ble_mesh_gen_def_trans_time_set_t def_trans_time_set

For

ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIME_SET

&

ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIME_SET_UNACK

esp_ble_mesh_gen_onpowerup_set_t power_set

For

ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_SET

&

ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_SET_UNACK

esp_ble_mesh_gen_power_level_set_t power_level_set

For

ESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_SET

&

ESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_SET_UNACK

esp_ble_mesh_gen_power_default_set_t power_default_set

For

ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULT_SET

&

ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULT_SET_UNACK

esp_ble_mesh_gen_power_range_set_t power_range_set

For

ESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_SET

&

ESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_SET_UNACK

esp_ble_mesh_gen_loc_global_set_t loc_global_set

For

ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_SET

&

ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_SET_UNACK

esp_ble_mesh_gen_loc_local_set_t loc_local_set

For

ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_SET

&

ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_SET_UNACK

esp_ble_mesh_gen_user_property_set_t user_property_set

For

ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTY_SET

&

ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTY_SET_UNACK

esp_ble_mesh_gen_admin_property_set_t admin_property_set

For

ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_SET

&

ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_SET_UNACK

esp_ble_mesh_gen_manufacturer_property_set_t manufacturer_property_set

For

ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_SET

&

ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_SET_UNACK

union esp_ble_mesh_gen_client_status_cb_t #include <esp_ble_mesh_generic_model_api.h> Generic Client Model received message union.

Public Members
esp_ble_mesh_gen_onoff_status_cb_t onoff_status For ESP_BLE_MESH_MODEL_OP_GEN_ONOFF_STATUS
esp_ble_mesh_gen_level_status_cb_t level_status For ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_STATUS
esp_ble_mesh_gen_def_trans_time_status_cb_t def_trans_time_status For ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIME_STATUS
esp_ble_mesh_gen_onpowerup_status_cb_t onpowerup_status For ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_STATUS
esp_ble_mesh_gen_power_level_status_cb_t power_level_status For ESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_STATUS
esp_ble_mesh_gen_power_last_status_cb_t power_last_status For ESP_BLE_MESH_MODEL_OP_GEN_POWER_LAST_STATUS
esp_ble_mesh_gen_power_default_status_cb_t power_default_status For ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULT_STATUS

Espressif Systems

261

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_ble_mesh_gen_power_range_status_cb_t power_range_status For ESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_STATUS
esp_ble_mesh_gen_battery_status_cb_t battery_status For ESP_BLE_MESH_MODEL_OP_GEN_BATTERY_STATUS
esp_ble_mesh_gen_loc_global_status_cb_t location_global_status For ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_STATUS
esp_ble_mesh_gen_loc_local_status_cb_t location_local_status ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_STATUS
esp_ble_mesh_gen_user_properties_status_cb_t user_properties_status ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTIES_STATUS
esp_ble_mesh_gen_user_property_status_cb_t user_property_status ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTY_STATUS
esp_ble_mesh_gen_admin_properties_status_cb_t admin_properties_status ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTIES_STATUS
esp_ble_mesh_gen_admin_property_status_cb_t admin_property_status ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_STATUS
esp_ble_mesh_gen_manufacturer_properties_status_cb_t manufacturer_properties_status ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTIES_STATUS
esp_ble_mesh_gen_manufacturer_property_status_cb_t manufacturer_property_status ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_STATUS
esp_ble_mesh_gen_client_properties_status_cb_t client_properties_status ESP_BLE_MESH_MODEL_OP_GEN_CLIENT_PROPERTIES_STATUS
union esp_ble_mesh_generic_server_state_change_t #include <esp_ble_mesh_generic_model_api.h> Generic Server Model state change value union.
Public Members
esp_ble_mesh_state_change_gen_onoff_set_t onoff_set The recv_op in ctx can be used to decide which state is changed. Generic OnOff Set
esp_ble_mesh_state_change_gen_level_set_t level_set Generic Level Set
esp_ble_mesh_state_change_gen_delta_set_t delta_set Generic Delta Set
esp_ble_mesh_state_change_gen_move_set_t move_set Generic Move Set
esp_ble_mesh_state_change_gen_def_trans_time_set_t def_trans_time_set Generic Default Transition Time Set
esp_ble_mesh_state_change_gen_onpowerup_set_t onpowerup_set Generic OnPowerUp Set
esp_ble_mesh_state_change_gen_power_level_set_t power_level_set Generic Power Level Set
esp_ble_mesh_state_change_gen_power_default_set_t power_default_set Generic Power Default Set
esp_ble_mesh_state_change_gen_power_range_set_t power_range_set Generic Power Range Set
esp_ble_mesh_state_change_gen_loc_global_set_t loc_global_set Generic Location Global Set

Espressif Systems

262

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_ble_mesh_state_change_gen_loc_local_set_t loc_local_set Generic Location Local Set
esp_ble_mesh_state_change_gen_user_property_set_t user_property_set Generic User Property Set
esp_ble_mesh_state_change_gen_admin_property_set_t admin_property_set Generic Admin Property Set
esp_ble_mesh_state_change_gen_manu_property_set_t manu_property_set Generic Manufacturer Property Set
union esp_ble_mesh_generic_server_recv_get_msg_t #include <esp_ble_mesh_generic_model_api.h> Generic Server Model received get message union.

Public Members
esp_ble_mesh_server_recv_gen_user_property_get_t user_property Generic User Property Get
esp_ble_mesh_server_recv_gen_admin_property_get_t admin_property Generic Admin Property Get
esp_ble_mesh_server_recv_gen_manufacturer_property_get_t manu_property Generic Manufacturer Property Get
esp_ble_mesh_server_recv_gen_client_properties_get_t client_properties Generic Client Properties Get
union esp_ble_mesh_generic_server_recv_set_msg_t #include <esp_ble_mesh_generic_model_api.h> Generic Server Model received set message union.

Public Members
esp_ble_mesh_server_recv_gen_onoff_set_t onoff Generic OnOff Set/Generic OnOff Set Unack
esp_ble_mesh_server_recv_gen_level_set_t level Generic Level Set/Generic Level Set Unack
esp_ble_mesh_server_recv_gen_delta_set_t delta Generic Delta Set/Generic Delta Set Unack
esp_ble_mesh_server_recv_gen_move_set_t move Generic Move Set/Generic Move Set Unack
esp_ble_mesh_server_recv_gen_def_trans_time_set_t def_trans_time Generic Default Transition Time Set/Generic Default Transition Time Set Unack
esp_ble_mesh_server_recv_gen_onpowerup_set_t onpowerup Generic OnPowerUp Set/Generic OnPowerUp Set Unack
esp_ble_mesh_server_recv_gen_power_level_set_t power_level Generic Power Level Set/Generic Power Level Set Unack
esp_ble_mesh_server_recv_gen_power_default_set_t power_default Generic Power Default Set/Generic Power Default Set Unack
esp_ble_mesh_server_recv_gen_power_range_set_t power_range Generic Power Range Set/Generic Power Range Set Unack
esp_ble_mesh_server_recv_gen_loc_global_set_t location_global Generic Location Global Set/Generic Location Global Set Unack
esp_ble_mesh_server_recv_gen_loc_local_set_t location_local Generic Location Local Set/Generic Location Local Set Unack

Espressif Systems

263

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
esp_ble_mesh_server_recv_gen_user_property_set_t user_property Generic User Property Set/Generic User Property Set Unack
esp_ble_mesh_server_recv_gen_admin_property_set_t admin_property Generic Admin Property Set/Generic Admin Property Set Unack
esp_ble_mesh_server_recv_gen_manufacturer_property_set_t manu_property Generic Manufacturer Property Set/Generic Manufacturer Property Set Unack
union esp_ble_mesh_generic_server_cb_value_t #include <esp_ble_mesh_generic_model_api.h> Generic Server Model callback value union.
Public Members
esp_ble_mesh_generic_server_state_change_t state_change ESP_BLE_MESH_GENERIC_SERVER_STATE_CHANGE_EVT
esp_ble_mesh_generic_server_recv_get_msg_t get ESP_BLE_MESH_GENERIC_SERVER_RECV_GET_MSG_EVT
esp_ble_mesh_generic_server_recv_set_msg_t set ESP_BLE_MESH_GENERIC_SERVER_RECV_SET_MSG_EVT
Structures struct esp_ble_mesh_gen_onoff_set_t
Bluetooth Mesh Generic Client Model Get and Set parameters structure. Parameters of Generic OnOff Set.
Public Members
bool op_en Indicate if optional parameters are included
uint8_t onoff Target value of Generic OnOff state
uint8_t tid Transaction ID
uint8_t trans_time Time to complete state transition (optional)
uint8_t delay Indicate message execution delay (C.1)
struct esp_ble_mesh_gen_level_set_t Parameters of Generic Level Set.
Public Members
bool op_en 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)

Espressif Systems

264

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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.

Espressif Systems

265

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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.
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)

Espressif Systems

266

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

267

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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.

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.

Espressif Systems

268

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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)
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.

Espressif Systems

269

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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)
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.

Espressif Systems

270

Release v5.0-dev-1424-g2467aa7f6c

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

Espressif Systems

271

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

272

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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 olevel + incoming deltapto calculate the target level. In another word,olast_levelpis used to recordolevelpof the last transaction, andolast_deltapis used to record the previously received delta_level value. The last value of the Generic Level state
int32_t last_delta The last delta change of the Generic Level state
bool move_start Indicate if the transition of the Generic Level state has been started
bool positive Indicate if the transition is positive or negative
struct esp_ble_mesh_gen_level_srv_t User data of Generic Level Server Model
Public Members
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.

Espressif Systems

273

Release v5.0-dev-1424-g2467aa7f6c

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

Espressif Systems

274

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

275

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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.

Espressif Systems

276

Release v5.0-dev-1424-g2467aa7f6c

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_gen_location_state_t *state Parameters of the Generic Location state
struct esp_ble_mesh_generic_property_t Parameters of Generic Property states
Public Members
uint16_t id The value of User/Admin/Manufacturer Property ID
uint8_t user_access The value of User Access field
uint8_t admin_access The value of Admin Access field
uint8_t manu_access The value of Manufacturer Access field
struct net_buf_simple *val The value of User/Admin/Manufacturer Property
struct esp_ble_mesh_gen_user_prop_srv_t User data of Generic User Property Server Model
Public Members
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

Espressif Systems

277

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

278

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

279

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

280

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

281

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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)
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

Espressif Systems

282

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

283

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

284

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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.
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.

Espressif Systems

285

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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.
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.

Espressif Systems

286

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

287

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

288

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Bluetooth Mesh Generic Server Model function.

*param)

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

Espressif Systems

289

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Register BLE Mesh Sensor Client Model callback.

callback)

Return ESP_OK on success or error code otherwise. Parameters
· [in] callback: Pointer to the callback function. 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.

Espressif Systems

290

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t esp_ble_mesh_register_sensor_server_callback(esp_ble_mesh_sensor_server_cb_t

Register BLE Mesh Sensor Server Model callback.

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.

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

Espressif Systems

291

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
esp_ble_mesh_sensor_setting_status_cb_t setting_status For ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_STATUS
esp_ble_mesh_sensor_status_cb_t sensor_status For ESP_BLE_MESH_MODEL_OP_SENSOR_STATUS
esp_ble_mesh_sensor_column_status_cb_t column_status For ESP_BLE_MESH_MODEL_OP_SENSOR_COLUMN_STATUS
esp_ble_mesh_sensor_series_status_cb_t series_status For ESP_BLE_MESH_MODEL_OP_SENSOR_SERIES_STATUS
union esp_ble_mesh_sensor_server_state_change_t #include <esp_ble_mesh_sensor_model_api.h> Sensor Server Model state change value union.
Public Members
esp_ble_mesh_state_change_sensor_cadence_set_t sensor_cadence_set The recv_op in ctx can be used to decide which state is changed. Sensor Cadence Set
esp_ble_mesh_state_change_sensor_setting_set_t sensor_setting_set Sensor Setting Set
union esp_ble_mesh_sensor_server_recv_get_msg_t #include <esp_ble_mesh_sensor_model_api.h> Sensor Server Model received get message union.
Public Members
esp_ble_mesh_server_recv_sensor_descriptor_get_t sensor_descriptor Sensor Descriptor Get
esp_ble_mesh_server_recv_sensor_cadence_get_t sensor_cadence Sensor Cadence Get
esp_ble_mesh_server_recv_sensor_settings_get_t sensor_settings Sensor Settings Get
esp_ble_mesh_server_recv_sensor_setting_get_t sensor_setting Sensor Setting Get
esp_ble_mesh_server_recv_sensor_get_t sensor_data Sensor Get
esp_ble_mesh_server_recv_sensor_column_get_t sensor_column Sensor Column Get
esp_ble_mesh_server_recv_sensor_series_get_t sensor_series Sensor Series Get
union esp_ble_mesh_sensor_server_recv_set_msg_t #include <esp_ble_mesh_sensor_model_api.h> Sensor Server Model received set message union.
Public Members
esp_ble_mesh_server_recv_sensor_cadence_set_t sensor_cadence Sensor Cadence Set
esp_ble_mesh_server_recv_sensor_setting_set_t sensor_setting Sensor Setting Set
union esp_ble_mesh_sensor_server_cb_value_t #include <esp_ble_mesh_sensor_model_api.h> Sensor Server Model callback value union.

Espressif Systems

292

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

293

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

294

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

295

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

296

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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 osizepin 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 osizepprecisely. The value of Status Trigger Delta Down field
struct net_buf_simple *trigger_delta_up The value of Status Trigger Delta Up field
uint8_t min_interval The value of Status Min Interval field
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 0x00xF, representing range of 1 16).

Espressif Systems

297

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Format B: The Length field is a 1-based uint7 value (valid range 0x00x7F, 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
esp_ble_mesh_sensor_cadence_t *cadence The Sensor Cadence state may be not supported by sensors based on device properties referencingononscalar characteristicspsuch asohistogramsporocomposite characteristicsp. 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

Espressif Systems

298

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

299

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

300

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

301

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

302

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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 ouint16p
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 0x00x7F, representing range of 1127). The value 0x7F represents a length of zero.
ESP_BLE_MESH_GET_SENSOR_DATA_FORMAT(_data) Get format of the sensor data.
Note Multiple sensor data may be concatenated. Make sure the _data pointer is updated before getting the format of the corresponding sensor data.
Return Format of the sensor data. Parameters
· _data: Pointer to the start of the sensor data.
ESP_BLE_MESH_GET_SENSOR_DATA_LENGTH(_data, _fmt) Get length of the sensor data.
Note Multiple sensor data may be concatenated. Make sure the _data pointer is updated before getting the length of the corresponding sensor data.
Return Length (zero-based) of the sensor data. Parameters
· _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.

Espressif Systems

303

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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 0x00xF, representing range of 116). 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 0x00x7F, representing range of 1127). 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 · 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

Espressif Systems

304

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

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

Register BLE Mesh Time Scene Client Model callback.

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

Espressif Systems

305

Release v5.0-dev-1424-g2467aa7f6c

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

Register BLE Mesh Time and Scenes Server Model callback.

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.

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

Espressif Systems

306

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_ble_mesh_scheduler_act_set_t scheduler_act_set

For

ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_SET

&

ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_SET_UNACK

union esp_ble_mesh_time_scene_client_status_cb_t #include <esp_ble_mesh_time_scene_model_api.h> Time Scene Client Model received message union.

Public Members
esp_ble_mesh_time_status_cb_t time_status For ESP_BLE_MESH_MODEL_OP_TIME_STATUS
esp_ble_mesh_time_zone_status_cb_t time_zone_status For ESP_BLE_MESH_MODEL_OP_TIME_ZONE_STATUS
esp_ble_mesh_tai_utc_delta_status_cb_t tai_utc_delta_status For ESP_BLE_MESH_MODEL_OP_TAI_UTC_DELTA_STATUS
esp_ble_mesh_time_role_status_cb_t time_role_status For ESP_BLE_MESH_MODEL_OP_TIME_ROLE_STATUS
esp_ble_mesh_scene_status_cb_t scene_status For ESP_BLE_MESH_MODEL_OP_SCENE_STATUS
esp_ble_mesh_scene_register_status_cb_t scene_register_status For ESP_BLE_MESH_MODEL_OP_SCENE_REGISTER_STATUS
esp_ble_mesh_scheduler_status_cb_t scheduler_status For ESP_BLE_MESH_MODEL_OP_SCHEDULER_STATUS
esp_ble_mesh_scheduler_act_status_cb_t scheduler_act_status For ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_STATUS
union esp_ble_mesh_time_scene_server_state_change_t #include <esp_ble_mesh_time_scene_model_api.h> Time Scene Server Model state change value union.

Public Members
esp_ble_mesh_state_change_time_set_t time_set The recv_op in ctx can be used to decide which state is changed. Time Set
esp_ble_mesh_state_change_time_status_t time_status Time Status
esp_ble_mesh_state_change_time_zone_set_t time_zone_set Time Zone Set
esp_ble_mesh_state_change_tai_utc_delta_set_t tai_utc_delta_set TAI UTC Delta Set
esp_ble_mesh_state_change_time_role_set_t time_role_set Time Role Set
esp_ble_mesh_state_change_scene_store_t scene_store Scene Store
esp_ble_mesh_state_change_scene_recall_t scene_recall Scene Recall
esp_ble_mesh_state_change_scene_delete_t scene_delete Scene Delete
esp_ble_mesh_state_change_scheduler_act_set_t scheduler_act_set Scheduler Action Set

Espressif Systems

307

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
union esp_ble_mesh_time_scene_server_recv_get_msg_t #include <esp_ble_mesh_time_scene_model_api.h> Time Scene Server Model received get message union.
Public Members
esp_ble_mesh_server_recv_scheduler_act_get_t scheduler_act Scheduler Action Get
union esp_ble_mesh_time_scene_server_recv_set_msg_t #include <esp_ble_mesh_time_scene_model_api.h> Time Scene Server Model received set message union.
Public Members
esp_ble_mesh_server_recv_time_set_t time Time Set
esp_ble_mesh_server_recv_time_zone_set_t time_zone Time Zone Set
esp_ble_mesh_server_recv_tai_utc_delta_set_t tai_utc_delta TAI-UTC Delta Set
esp_ble_mesh_server_recv_time_role_set_t time_role Time Role Set
esp_ble_mesh_server_recv_scene_store_t scene_store Scene Store/Scene Store Unack
esp_ble_mesh_server_recv_scene_recall_t scene_recall Scene Recall/Scene Recall Unack
esp_ble_mesh_server_recv_scene_delete_t scene_delete Scene Delete/Scene Delete Unack
esp_ble_mesh_server_recv_scheduler_act_set_t scheduler_act Scheduler Action Set/Scheduler Action Set Unack
union esp_ble_mesh_time_scene_server_recv_status_msg_t #include <esp_ble_mesh_time_scene_model_api.h> Time Scene Server Model received status message union.
Public Members
esp_ble_mesh_server_recv_time_status_t time_status Time Status
union esp_ble_mesh_time_scene_server_cb_value_t #include <esp_ble_mesh_time_scene_model_api.h> Time Scene Server Model callback value union.
Public Members
esp_ble_mesh_time_scene_server_state_change_t state_change ESP_BLE_MESH_TIME_SCENE_SERVER_STATE_CHANGE_EVT
esp_ble_mesh_time_scene_server_recv_get_msg_t get ESP_BLE_MESH_TIME_SCENE_SERVER_RECV_GET_MSG_EVT
esp_ble_mesh_time_scene_server_recv_set_msg_t set ESP_BLE_MESH_TIME_SCENE_SERVER_RECV_SET_MSG_EVT
esp_ble_mesh_time_scene_server_recv_status_msg_t status ESP_BLE_MESH_TIME_SCENE_SERVER_RECV_STATUS_MSG_EVT

Espressif Systems

308

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Structures struct esp_ble_mesh_time_set_t
Bluetooth Mesh Time Scene Client Model Get and Set parameters structure. Parameters of Time Set
Public Members
uint8_t tai_seconds[5] The current TAI time in seconds
uint8_t sub_second The sub-second time in units of 1/256 second
uint8_t uncertainty The estimated uncertainty in 10-millisecond steps
uint16_t time_authority : 1 0 = No Time Authority, 1 = Time Authority
uint16_t tai_utc_delta : 15 Current difference between TAI and UTC in seconds
uint8_t time_zone_offset The local time zone offset in 15-minute increments
struct esp_ble_mesh_time_zone_set_t Parameters of Time Zone Set
Public Members
uint8_t time_zone_offset_new Upcoming local time zone offset
uint8_t tai_zone_change[5] TAI Seconds time of the upcoming Time Zone Offset change
struct esp_ble_mesh_tai_utc_delta_set_t Parameters of TAI-UTC Delta Set
Public Members
uint16_t tai_utc_delta_new : 15 Upcoming difference between TAI and UTC in seconds
uint16_t padding : 1 Always 0b0. Other values are Prohibited.
uint8_t tai_delta_change[5] TAI Seconds time of the upcoming TAI-UTC Delta change
struct esp_ble_mesh_time_role_set_t Parameter of Time Role Set
Public Members
uint8_t time_role The Time Role for the element
struct esp_ble_mesh_scene_store_t Parameter of Scene Store

Espressif Systems

309

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

310

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

311

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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)
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

Espressif Systems

312

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

313

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

314

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

4. If a model is extending another model, the extending model shall determine the Stored with Scene behavior 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.

Public Members
const uint16_t scene_count The Scenes statens 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 elementns state that is marked as oStored with Scenephas 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.

Espressif Systems

315

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

316

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

317

Release v5.0-dev-1424-g2467aa7f6c

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

Espressif Systems

318

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

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

Espressif Systems

319

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

320

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

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

Espressif Systems

321

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

322

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

323

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

324

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_BLE_MESH_SCHEDULE_YEAR_ANY_YEAR Any year of the Scheduled year
ESP_BLE_MESH_SCHEDULE_DAY_ANY_DAY Any day of the Scheduled day
ESP_BLE_MESH_SCHEDULE_HOUR_ANY_HOUR Any hour of the Scheduled hour
ESP_BLE_MESH_SCHEDULE_HOUR_ONCE_A_DAY Any hour of the Scheduled Day
ESP_BLE_MESH_SCHEDULE_SEC_ANY_OF_HOUR Any minute of the Scheduled hour
ESP_BLE_MESH_SCHEDULE_SEC_EVERY_15_MIN Every 15 minutes of the Scheduled hour
ESP_BLE_MESH_SCHEDULE_SEC_EVERY_20_MIN Every 20 minutes of the Scheduled hour
ESP_BLE_MESH_SCHEDULE_SEC_ONCE_AN_HOUR Once of the Scheduled hour
ESP_BLE_MESH_SCHEDULE_SEC_ANY_OF_MIN Any second of the Scheduled minute
ESP_BLE_MESH_SCHEDULE_SEC_EVERY_15_SEC Every 15 seconds of the Scheduled minute
ESP_BLE_MESH_SCHEDULE_SEC_EVERY_20_SEC Every 20 seconds of the Scheduled minute
ESP_BLE_MESH_SCHEDULE_SEC_ONCE_AN_MIN Once of the Scheduled minute
ESP_BLE_MESH_SCHEDULE_ACT_TURN_OFF Scheduled Action - Turn Off
ESP_BLE_MESH_SCHEDULE_ACT_TURN_ON Scheduled Action - Turn On
ESP_BLE_MESH_SCHEDULE_ACT_SCENE_RECALL Scheduled Action - Scene Recall
ESP_BLE_MESH_SCHEDULE_ACT_NO_ACTION Scheduled Action - No Action
ESP_BLE_MESH_SCHEDULE_SCENE_NO_SCENE Scheduled Scene - No Scene
ESP_BLE_MESH_SCHEDULE_ENTRY_MAX_INDEX Maximum number of Scheduled entries
ESP_BLE_MESH_TIME_NONE Time Role - None
ESP_BLE_MESH_TIME_AUTHORITY Time Role - Mesh Time Authority
ESP_BLE_MESH_TIME_RELAY Time Role - Mesh Time Relay
ESP_BLE_MESH_TIME_CLINET Time Role - Mesh Time Client
ESP_BLE_MESH_SCENE_SUCCESS Scene operation - Success

Espressif Systems

325

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Bluetooth Mesh Time and Scenes Server Model function.

*param)

Time Scene Server Model callback function type

Parameters · event: Event type · 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.

Espressif Systems

326

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Register BLE Mesh Light Client Model callback.

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

Register BLE Mesh Lighting Server Model callback.

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

Espressif Systems

327

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

union esp_ble_mesh_light_client_set_state_t #include <esp_ble_mesh_lighting_model_api.h> Lighting Client Model set message union.

Public Members

esp_ble_mesh_light_lightness_set_t lightness_set

For

ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_SET

&

ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_SET_UNACK

esp_ble_mesh_light_lightness_linear_set_t lightness_linear_set

For

ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LINEAR_SET

&

ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LINEAR_SET_UNACK

esp_ble_mesh_light_lightness_default_set_t lightness_default_set

For

ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEFAULT_SET

&

ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEFAULT_SET_UNACK

esp_ble_mesh_light_lightness_range_set_t lightness_range_set

For

ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_RANGE_SET

&

ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_RANGE_SET_UNACK

esp_ble_mesh_light_ctl_set_t ctl_set For ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_SET_UNA

esp_ble_mesh_light_ctl_temperature_set_t ctl_temperature_set

For

ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_SET

&

ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_SET_UNACK

esp_ble_mesh_light_ctl_temperature_range_set_t ctl_temperature_range_set

For

ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_RANGE_SET

&

ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_RANGE_SET_UNACK

esp_ble_mesh_light_ctl_default_set_t ctl_default_set

For

ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULT_SET

&

ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULT_SET_UNACK

esp_ble_mesh_light_hsl_set_t hsl_set For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SET_UNAC

esp_ble_mesh_light_hsl_hue_set_t hsl_hue_set For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE

esp_ble_mesh_light_hsl_saturation_set_t hsl_saturation_set

For

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SATURATION_SET

&

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SATURATION_SET_UNACK

esp_ble_mesh_light_hsl_default_set_t hsl_default_set

For

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULT_SET

&

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULT_SET_UNACK

esp_ble_mesh_light_hsl_range_set_t hsl_range_set

For

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_SET

&

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_SET_UNACK

esp_ble_mesh_light_xyl_set_t xyl_set For ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_SET_UNA

esp_ble_mesh_light_xyl_default_set_t xyl_default_set

For

ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULT_SET

&

ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULT_SET_UNACK

esp_ble_mesh_light_xyl_range_set_t xyl_range_set

For

ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_SET

&

ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_SET_UNACK

Espressif Systems

328

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_ble_mesh_light_lc_mode_set_t lc_mode_set

For

ESP_BLE_MESH_MODEL_OP_LIGHT_LC_MODE_SET

&

ESP_BLE_MESH_MODEL_OP_LIGHT_LC_MODE_SET_UNACK

esp_ble_mesh_light_lc_om_set_t lc_om_set For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_OM_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_LC_OM_SET

esp_ble_mesh_light_lc_light_onoff_set_t lc_light_onoff_set

For

ESP_BLE_MESH_MODEL_OP_LIGHT_LC_LIGHT_ONOFF_SET

&

ESP_BLE_MESH_MODEL_OP_LIGHT_LC_LIGHT_ONOFF_SET_UNACK

esp_ble_mesh_light_lc_property_set_t lc_property_set

For

ESP_BLE_MESH_MODEL_OP_LIGHT_LC_PROPERTY_SET

&

ESP_BLE_MESH_MODEL_OP_LIGHT_LC_PROPERTY_SET_UNACK

union esp_ble_mesh_light_client_status_cb_t #include <esp_ble_mesh_lighting_model_api.h> Lighting Client Model received message union.

Public Members
esp_ble_mesh_light_lightness_status_cb_t lightness_status For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_STATUS
esp_ble_mesh_light_lightness_linear_status_cb_t lightness_linear_status For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LINEAR_STATUS
esp_ble_mesh_light_lightness_last_status_cb_t lightness_last_status For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LAST_STATUS
esp_ble_mesh_light_lightness_default_status_cb_t lightness_default_status For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEFAULT_STATUS
esp_ble_mesh_light_lightness_range_status_cb_t lightness_range_status For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_RANGE_STATUS
esp_ble_mesh_light_ctl_status_cb_t ctl_status For ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_STATUS
esp_ble_mesh_light_ctl_temperature_status_cb_t ctl_temperature_status For ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_STATUS
esp_ble_mesh_light_ctl_temperature_range_status_cb_t ctl_temperature_range_status For ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_RANGE_STATUS
esp_ble_mesh_light_ctl_default_status_cb_t ctl_default_status For ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULT_STATUS
esp_ble_mesh_light_hsl_status_cb_t hsl_status For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_STATUS
esp_ble_mesh_light_hsl_target_status_cb_t hsl_target_status For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_TARGET_STATUS
esp_ble_mesh_light_hsl_hue_status_cb_t hsl_hue_status For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_STATUS
esp_ble_mesh_light_hsl_saturation_status_cb_t hsl_saturation_status For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SATURATION_STATUS
esp_ble_mesh_light_hsl_default_status_cb_t hsl_default_status For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULT_STATUS
esp_ble_mesh_light_hsl_range_status_cb_t hsl_range_status For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_STATUS
esp_ble_mesh_light_xyl_status_cb_t xyl_status For ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_STATUS

Espressif Systems

329

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_ble_mesh_light_xyl_target_status_cb_t xyl_target_status For ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_TARGET_STATUS
esp_ble_mesh_light_xyl_default_status_cb_t xyl_default_status For ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULT_STATUS
esp_ble_mesh_light_xyl_range_status_cb_t xyl_range_status For ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_STATUS
esp_ble_mesh_light_lc_mode_status_cb_t lc_mode_status For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_MODE_STATUS
esp_ble_mesh_light_lc_om_status_cb_t lc_om_status For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_OM_STATUS
esp_ble_mesh_light_lc_light_onoff_status_cb_t lc_light_onoff_status For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_LIGHT_ONOFF_STATUS
esp_ble_mesh_light_lc_property_status_cb_t lc_property_status For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_PROPERTY_STATUS
union esp_ble_mesh_lighting_server_state_change_t #include <esp_ble_mesh_lighting_model_api.h> Lighting Server Model state change value union.
Public Members
esp_ble_mesh_state_change_light_lightness_set_t lightness_set The recv_op in ctx can be used to decide which state is changed. Light Lightness Set
esp_ble_mesh_state_change_light_lightness_linear_set_t lightness_linear_set Light Lightness Linear Set
esp_ble_mesh_state_change_light_lightness_default_set_t lightness_default_set Light Lightness Default Set
esp_ble_mesh_state_change_light_lightness_range_set_t lightness_range_set Light Lightness Range Set
esp_ble_mesh_state_change_light_ctl_set_t ctl_set Light CTL Set
esp_ble_mesh_state_change_light_ctl_temperature_set_t ctl_temp_set Light CTL Temperature Set
esp_ble_mesh_state_change_light_ctl_temperature_range_set_t ctl_temp_range_set Light CTL Temperature Range Set
esp_ble_mesh_state_change_light_ctl_default_set_t ctl_default_set Light CTL Default Set
esp_ble_mesh_state_change_light_hsl_set_t hsl_set Light HSL Set
esp_ble_mesh_state_change_light_hsl_hue_set_t hsl_hue_set Light HSL Hue Set
esp_ble_mesh_state_change_light_hsl_saturation_set_t hsl_saturation_set Light HSL Saturation Set
esp_ble_mesh_state_change_light_hsl_default_set_t hsl_default_set Light HSL Default Set
esp_ble_mesh_state_change_light_hsl_range_set_t hsl_range_set Light HSL Range Set
esp_ble_mesh_state_change_light_xyl_set_t xyl_set Light xyL Set

Espressif Systems

330

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_ble_mesh_state_change_light_xyl_default_set_t xyl_default_set Light xyL Default Set
esp_ble_mesh_state_change_light_xyl_range_set_t xyl_range_set Light xyL Range Set
esp_ble_mesh_state_change_light_lc_mode_set_t lc_mode_set Light LC Mode Set
esp_ble_mesh_state_change_light_lc_om_set_t lc_om_set Light LC Occupancy Mode Set
esp_ble_mesh_state_change_light_lc_light_onoff_set_t lc_light_onoff_set Light LC Light OnOff Set
esp_ble_mesh_state_change_light_lc_property_set_t lc_property_set Light LC Property Set
esp_ble_mesh_state_change_sensor_status_t sensor_status Sensor Status
union esp_ble_mesh_lighting_server_recv_get_msg_t #include <esp_ble_mesh_lighting_model_api.h> Lighting Server Model received get message union.

Public Members
esp_ble_mesh_server_recv_light_lc_property_get_t lc_property Light LC Property Get
union esp_ble_mesh_lighting_server_recv_set_msg_t #include <esp_ble_mesh_lighting_model_api.h> Lighting Server Model received set message union.

Public Members
esp_ble_mesh_server_recv_light_lightness_set_t lightness Light Lightness Set/Light Lightness Set Unack
esp_ble_mesh_server_recv_light_lightness_linear_set_t lightness_linear Light Lightness Linear Set/Light Lightness Linear Set Unack
esp_ble_mesh_server_recv_light_lightness_default_set_t lightness_default Light Lightness Default Set/Light Lightness Default Set Unack
esp_ble_mesh_server_recv_light_lightness_range_set_t lightness_range Light Lightness Range Set/Light Lightness Range Set Unack
esp_ble_mesh_server_recv_light_ctl_set_t ctl Light CTL Set/Light CTL Set Unack
esp_ble_mesh_server_recv_light_ctl_temperature_set_t ctl_temp Light CTL Temperature Set/Light CTL Temperature Set Unack
esp_ble_mesh_server_recv_light_ctl_temperature_range_set_t ctl_temp_range Light CTL Temperature Range Set/Light CTL Temperature Range Set Unack
esp_ble_mesh_server_recv_light_ctl_default_set_t ctl_default Light CTL Default Set/Light CTL Default Set Unack
esp_ble_mesh_server_recv_light_hsl_set_t hsl Light HSL Set/Light HSL Set Unack
esp_ble_mesh_server_recv_light_hsl_hue_set_t hsl_hue Light HSL Hue Set/Light HSL Hue Set Unack
esp_ble_mesh_server_recv_light_hsl_saturation_set_t hsl_saturation Light HSL Saturation Set/Light HSL Saturation Set Unack

Espressif Systems

331

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_ble_mesh_server_recv_light_hsl_default_set_t hsl_default Light HSL Default Set/Light HSL Default Set Unack
esp_ble_mesh_server_recv_light_hsl_range_set_t hsl_range Light HSL Range Set/Light HSL Range Set Unack
esp_ble_mesh_server_recv_light_xyl_set_t xyl Light xyL Set/Light xyL Set Unack
esp_ble_mesh_server_recv_light_xyl_default_set_t xyl_default Light xyL Default Set/Light xyL Default Set Unack
esp_ble_mesh_server_recv_light_xyl_range_set_t xyl_range Light xyL Range Set/Light xyL Range Set Unack
esp_ble_mesh_server_recv_light_lc_mode_set_t lc_mode Light LC Mode Set/Light LC Mode Set Unack
esp_ble_mesh_server_recv_light_lc_om_set_t lc_om Light LC OM Set/Light LC OM Set Unack
esp_ble_mesh_server_recv_light_lc_light_onoff_set_t lc_light_onoff Light LC Light OnOff Set/Light LC Light OnOff Set Unack
esp_ble_mesh_server_recv_light_lc_property_set_t lc_property Light LC Property Set/Light LC Property Set Unack
union esp_ble_mesh_lighting_server_recv_status_msg_t #include <esp_ble_mesh_lighting_model_api.h> Lighting Server Model received status message union.
Public Members
esp_ble_mesh_server_recv_sensor_status_t sensor_status Sensor Status
union esp_ble_mesh_lighting_server_cb_value_t #include <esp_ble_mesh_lighting_model_api.h> Lighting Server Model callback value union.
Public Members
esp_ble_mesh_lighting_server_state_change_t state_change ESP_BLE_MESH_LIGHTING_SERVER_STATE_CHANGE_EVT
esp_ble_mesh_lighting_server_recv_get_msg_t get ESP_BLE_MESH_LIGHTING_SERVER_RECV_GET_MSG_EVT
esp_ble_mesh_lighting_server_recv_set_msg_t set ESP_BLE_MESH_LIGHTING_SERVER_RECV_SET_MSG_EVT
esp_ble_mesh_lighting_server_recv_status_msg_t status ESP_BLE_MESH_LIGHTING_SERVER_RECV_STATUS_MSG_EVT
Structures struct esp_ble_mesh_light_lightness_set_t
Bluetooth Mesh Light Lightness Client Model Get and Set parameters structure. Parameters of Light Lightness Set
Public Members
bool op_en Indicate if optional parameters are included

Espressif Systems

332

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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)
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

Espressif Systems

333

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

334

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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)

Espressif Systems

335

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

336

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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)

Espressif Systems

337

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

338

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

339

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

340

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

341

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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)

Espressif Systems

342

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

343

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

344

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

345

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

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

Espressif Systems

346

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

347

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

348

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

349

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

350

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
uint32_t occupancy_mode : 1 The value of Light LC Occupancy Mode state
uint32_t light_onoff : 1 The present value of Light LC Light OnOff state
uint32_t target_light_onoff : 1 The target value of Light LC Light OnOff state
uint32_t occupancy : 1 The value of Light LC Occupancy state
uint32_t ambient_luxlevel : 24 The value of Light LC Ambient LuxLevel state
uint16_t linear_output
1. Light LC Linear Output = max((Lightness Out)^2/65535, Regulator Output) 2. If the Light LC Mode state is set to 0b1, the binding is enabled and upon a change of the Light LC
Linear Output state, the following operation shall be performed: Light Lightness Linear = Light LC Linear Output 3. If the Light LC Mode state is set to 0b0, the binding is disabled (i.e., upon a change of the Light LC Linear Output state, no operation on the Light Lightness Linear state is performed). The value of Light LC Linear Output state
struct esp_ble_mesh_light_lc_property_state_t Parameters of Light Property states. The Light LC Property states are read / write states that determine the configuration of a Light Lightness Controller. Each state is represented by a device property and is controlled by Light LC Property messages.
Public Members
uint32_t time_occupancy_delay A timing state that determines the delay for changing the Light LC Occupancy state upon receiving a Sensor Status message from an occupancy sensor. The value of Light LC Time Occupancy Delay state
uint32_t time_fade_on A timing state that determines the time the controlled lights fade to the level determined by the Light LC Lightness On state. The value of Light LC Time Fade On state
uint32_t time_run_on A timing state that determines the time the controlled lights stay at the level determined by the Light LC Lightness On state. The value of Light LC Time Run On state
uint32_t time_fade A timing state that determines the time the controlled lights fade from the level determined by the Light LC Lightness On state to the level determined by the Light Lightness Prolong state. The value of Light LC Time Fade state
uint32_t time_prolong A timing state that determines the time the controlled lights stay at the level determined by the Light LC Lightness Prolong state. The value of Light LC Time Prolong state
uint32_t time_fade_standby_auto 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

Espressif Systems

351

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
uint16_t lightness_on A lightness state that determines the perceptive light lightness at the Occupancy and Run internal controller states. The value of Light LC Lightness On state
uint16_t lightness_prolong A lightness state that determines the light lightness at the Prolong internal controller state. The value of Light LC Lightness Prolong state
uint16_t lightness_standby A lightness state that determines the light lightness at the Standby internal controller state. The value of Light LC Lightness Standby state
uint16_t ambient_luxlevel_on A uint16 state representing the Ambient LuxLevel level that determines if the controller transitions from the Light Control Standby state. The value of Light LC Ambient LuxLevel On state
uint16_t ambient_luxlevel_prolong A uint16 state representing the required Ambient LuxLevel level in the Prolong state. The value of Light LC Ambient LuxLevel Prolong state
uint16_t ambient_luxlevel_standby A uint16 state representing the required Ambient LuxLevel level in the Standby state. The value of Light LC Ambient LuxLevel Standby state
float regulator_kiu A float32 state representing the integral coefficient that determines the integral part of the equation defining 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 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 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 equation 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 equation 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

Espressif Systems

352

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

353

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

354

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

355

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Public Members
uint16_t saturation The value of Light HSL Saturation state
struct esp_ble_mesh_state_change_light_hsl_default_set_t Parameters of Light HSL Default state change event
Public Members
uint16_t lightness The value of Light HSL Lightness Default state
uint16_t hue The value of Light HSL Hue Default state
uint16_t saturation The value of Light HSL Saturation Default state
struct esp_ble_mesh_state_change_light_hsl_range_set_t Parameters of Light HSL Range state change event
Public Members
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

Espressif Systems

356

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

357

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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)

Espressif Systems

358

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

359

Release v5.0-dev-1424-g2467aa7f6c

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

Espressif Systems

360

Release v5.0-dev-1424-g2467aa7f6c

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_server_recv_light_hsl_saturation_set_t Context of the received Light HSL Saturation Set message
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

Espressif Systems

361

Release v5.0-dev-1424-g2467aa7f6c

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

Espressif Systems

362

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
struct esp_ble_mesh_server_recv_light_lc_mode_set_t Context of the received Light LC Mode Set message
Public Members
uint8_t mode The target value of the Light LC Mode state
struct esp_ble_mesh_server_recv_light_lc_om_set_t Context of the received Light OM Set message
Public Members
uint8_t mode The target value of the Light LC Occupancy Mode state
struct esp_ble_mesh_server_recv_light_lc_light_onoff_set_t Context of the received Light LC Light OnOff Set message
Public Members
bool op_en 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

Espressif Systems

363

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

364

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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.
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.

Espressif Systems

365

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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 element. 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 element 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.
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.

Espressif Systems

366

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Bluetooth Mesh Lighting Server Model function.

*param)

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

Espressif Systems

367

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_BLE_MESH_LIGHT_CLIENT_SET_STATE_EVT
ESP_BLE_MESH_LIGHT_CLIENT_PUBLISH_EVT
ESP_BLE_MESH_LIGHT_CLIENT_TIMEOUT_EVT
ESP_BLE_MESH_LIGHT_CLIENT_EVT_MAX enum esp_ble_mesh_lc_state_t
This enum value is the Light LC State Machine states
Values:
ESP_BLE_MESH_LC_OFF
ESP_BLE_MESH_LC_STANDBY
ESP_BLE_MESH_LC_FADE_ON
ESP_BLE_MESH_LC_RUN
ESP_BLE_MESH_LC_FADE
ESP_BLE_MESH_LC_PROLONG
ESP_BLE_MESH_LC_FADE_STANDBY_AUTO
ESP_BLE_MESH_LC_FADE_STANDBY_MANUAL
enum esp_ble_mesh_lighting_server_cb_event_t This enum value is the event of Lighting Server Model
Values:
ESP_BLE_MESH_LIGHTING_SERVER_STATE_CHANGE_EVT
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.
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

Espressif Systems

368

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

2.2 Networking APIs
2.2.1 Wi-Fi
Wi-Fi
Introduction The Wi-Fi libraries provide support for configuring and monitoring the ESP32-S3 Wi-Fi networking functionality. This includes configuration for:
· Station mode (aka STA mode or Wi-Fi client mode). ESP32-S3 connects to an access point. · AP mode (aka Soft-AP mode or Access Point mode). Stations connect to the ESP32-S3. · Station/AP-coexistence mode (ESP32-S3 is concurrently an access point and a station connected to another
access point). · Various security modes for the above (WPA, WPA2, WEP, etc.) · Scanning for access points (active & passive scanning). · Promiscuous mode for monitoring of IEEE802.11 Wi-Fi packets.
Application Examples The wifi directory of ESP-IDF examples contains the following applications:
· Code examples for Wi-Fi. · 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)
Initialize WiFi Allocate resource for WiFi driver, such as WiFi control structure, RX/TX buffer, WiFi NVS structure etc. This WiFi also starts 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 initialize the configuration to default
values, this can guarantee all the fields get correct value when more fields are added into wifi_init_config_t in future release. If you want to set your own initial values, overwrite the default values which are set by WIFI_INIT_CONFIG_DEFAULT. Please be notified that the field mmagicnof 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 initialized 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.

Espressif Systems

369

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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 · [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 reconnection after ESP32 received disconnect event, remember to add the maximum retry time, otherwise

Espressif Systems

370

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

the called scan will not work. This is especially true when the AP doesnnt exist, and you still try reconnection 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
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

Espressif Systems

371

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· 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 · 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 donnt 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 apns phy mode info through the struct member phy_11bphy_11gphy_11nphy_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

Espressif Systems

372

Release v5.0-dev-1424-g2467aa7f6c

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

Espressif Systems

373

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· 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

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 doesnnt validate the per-country rules, itns 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=pCNp, .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=pUSAp, .schan=1,

.nchan=11} and the country info of the AP to which the station is connected is {.cc=pJPp, .schan=1,

.nchan=14} then the country info that will be used is {.cc=pJPp, .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=pUSp, .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 o1a:XX:XX:XX:XX:XXp, but can not be o15:XX:XX:XX:XX:XXp.

Espressif Systems

374

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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 · 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.

Espressif Systems

375

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

376

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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 stans phy mode info through the struct member
phy_11bphy_11gphy_11nphy_lr in the wifi_sta_info_t struct. For example, phy_11b = 1 imply that sta support 802.11b mode
esp_err_t esp_wifi_ap_get_sta_aid(const uint8_t mac[6], uint16_t *aid) Get AID of STA connected with soft-AP.
Return · ESP_OK: succeed · ESP_ERR_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: STAns 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

Espressif Systems

377

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· 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
· 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. Donnt 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.

Espressif Systems

378

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Attention Currently only support for sending beacon/probe request/probe response/action and non-QoS data frame
Return · ESP_OK: success · ESP_ERR_WIFI_IF: Invalid interface · ESP_ERR_INVALID_ARG: Invalid parameter · ESP_ERR_WIFI_NO_MEM: out of memory
Parameters · ifx: interface if the Wi-Fi mode is Station, the ifx should be WIFI_IF_STA. If the Wi-Fi mode is SoftAP, the ifx should be WIFI_IF_AP. If the Wi-Fi mode is Station+SoftAP, the ifx should be WIFI_IF_STA or WIFI_IF_AP. If the ifx is wrong, the API returns ESP_ERR_WIFI_IF. · buffer: raw ieee80211 buffer · len: the length of raw buffer, the len must be <= 1500 Bytes and >= 24 Bytes · en_sys_seq: indicate whether use the internal sequence number. If en_sys_seq is false, the sequence in raw buffer is unchanged, otherwise it will be overwritten by WiFi driver with the system sequence number. Generally, if esp_wifi_80211_tx is called before the Wi-Fi connection has been set up, both en_sys_seq==true and en_sys_seq==false are fine. However, if the API is called after the Wi-Fi connection has been set up, en_sys_seq must be true, otherwise ESP_ERR_WIFI_ARG is returned.
esp_err_t esp_wifi_set_csi_rx_cb(wifi_csi_cb_t cb, void *ctx) Register the RX callback function of CSI data.
Each time a CSI data is received, the callback function will be called.
Return · ESP_OK: succeed · 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

Espressif Systems

379

Release v5.0-dev-1424-g2467aa7f6c

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

Espressif Systems

380

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

381

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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 donnt 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.
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 areo01p(world safe mode)oATp,pAUp,pBEp,pBGp,pBRp
, oCAp,pCHp,pCNp,pCYp,pCZp,pDEp,pDKp,pEEp,pESp,pFIp,pFRp,pGBp ,pGRp,pHKp,pHRp,pHUp, oIEp,pINp,pISp,pITp,pJPp,pKRp,pLIp,pLTp,p LUp,pLVp,pMTp,pMXp,pNLp,pNOp,pNZp,pPLp,pPTp, oROp,pSEp,pSIp,p SKp,pTWp,pUSp Attention 7. When country code o01p(world safe mode) is set, SoftAP mode wonnt contain country IE. Attention 8. The default country is oCNpand 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

Espressif Systems

382

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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 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

Espressif Systems

383

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
int nvs_enable WiFi NVS flash enable flag
int nano_enable Nano option for printf/scan family enable flag
int rx_ba_win WiFi Block Ack RX window size
int wifi_task_core_id WiFi Task Core ID
int beacon_max_len WiFi softAP maximum length of the beacon
int mgmt_sbuf_num WiFi management short buffer number, the minimum value is 6, the maximum value is 32
uint64_t feature_caps Enables additional WiFi features and capabilities
bool sta_disconnected_pm WiFi Power Management for station at disconnected status
int magic WiFi init magic number, it should be the last field
Macros ESP_ERR_WIFI_NOT_INIT
WiFi driver was not installed by esp_wifi_init ESP_ERR_WIFI_NOT_STARTED
WiFi driver was not started by esp_wifi_start
ESP_ERR_WIFI_NOT_STOPPED WiFi driver was not stopped by esp_wifi_stop
ESP_ERR_WIFI_IF WiFi interface error
ESP_ERR_WIFI_MODE WiFi mode error
ESP_ERR_WIFI_STATE WiFi internal state error
ESP_ERR_WIFI_CONN WiFi internal control block of station or soft-AP error
ESP_ERR_WIFI_NVS WiFi internal NVS module error
ESP_ERR_WIFI_MAC MAC address is invalid
ESP_ERR_WIFI_SSID SSID is invalid
ESP_ERR_WIFI_PASSWORD Password is invalid
ESP_ERR_WIFI_TIMEOUT Timeout error
ESP_ERR_WIFI_WAKE_FAIL WiFi is in sleep state(RF closed) and wakeup fail

Espressif Systems

384

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_ERR_WIFI_WOULD_BLOCK The caller would block
ESP_ERR_WIFI_NOT_CONNECT Station still in disconnect status
ESP_ERR_WIFI_POST Failed to post the event to WiFi task
ESP_ERR_WIFI_INIT_STATE Invalid WiFi state when init/deinit is called
ESP_ERR_WIFI_STOP_STATE Returned when WiFi is stopping
ESP_ERR_WIFI_NOT_ASSOC The WiFi connection is not associated
ESP_ERR_WIFI_TX_DISALLOW The WiFi TX is disallowed
WIFI_STATIC_TX_BUFFER_NUM WIFI_CACHE_TX_BUFFER_NUM WIFI_DYNAMIC_TX_BUFFER_NUM WIFI_CSI_ENABLED WIFI_AMPDU_RX_ENABLED WIFI_AMPDU_TX_ENABLED WIFI_AMSDU_TX_ENABLED WIFI_NVS_ENABLED WIFI_NANO_FORMAT_ENABLED WIFI_INIT_CONFIG_MAGIC WIFI_DEFAULT_RX_BA_WIN WIFI_TASK_CORE_ID WIFI_SOFTAP_BEACON_MAX_LEN WIFI_MGMT_SBUF_NUM WIFI_STA_DISCONNECTED_PM_ENABLED CONFIG_FEATURE_WPA3_SAE_BIT CONFIG_FEATURE_CACHE_TX_BUF_BIT CONFIG_FEATURE_FTM_INITIATOR_BIT CONFIG_FEATURE_FTM_RESPONDER_BIT WIFI_INIT_CONFIG_DEFAULT()
Type Definitions typedef void (*wifi_promiscuous_cb_t)(void *buf, wifi_promiscuous_pkt_type_t type)
The RX callback function in the promiscuous mode. Each time a packet is received, the callback function will be called. Parameters
· buf: Data received. Type of data in buffer (wifi_promiscuous_pkt_t or wifi_pkt_rx_ctrl_t) indicated by mtypenparameter.
· type: promiscuous packet type.

Espressif Systems

385

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
typedef void (*esp_vendor_ie_cb_t)(void *ctx, wifi_vendor_ie_type_t type, const uint8_t sa[6], const vendor_ie_data_t *vnd_ie, int rssi)
Function signature for received Vendor-Specific Information Element callback. Parameters
· ctx: Context argument, as passed to esp_wifi_set_vendor_ie_cb() when registering callback. · type: Information element type, based on frame type received. · sa: Source 802.11 address. · vnd_ie: Pointer to the vendor specific element data received. · rssi: Received signal strength indication. typedef void (*wifi_csi_cb_t)(void *ctx, wifi_csi_info_t *data) The RX callback function of Channel State Information(CSI) data.
Each time a CSI data is received, the callback function will be called.
Parameters · ctx: context argument, passed to esp_wifi_set_csi_rx_cb() when registering callback function. · data: CSI data received. The memory that it points to will be deallocated after callback function returns.
Header File · components/esp_wifi/include/esp_wifi_types.h
Unions union wifi_config_t
#include <esp_wifi_types.h> Configuration data for ESP32 AP or STA. The usage of this union (for ap or sta configuration) is determined by the accompanying interface argument passed to esp_wifi_set_config() or esp_wifi_get_config()
Public Members
wifi_ap_config_t ap configuration of AP
wifi_sta_config_t sta configuration of STA
Structures struct wifi_country_t
Structure describing WiFi country-based regional restrictions.
Public Members
char cc[3] country code string
uint8_t schan start channel
uint8_t nchan total channel number
int8_t max_tx_power This field is used for getting WiFi maximum transmitting power, call esp_wifi_set_max_tx_power to set the maximum transmitting power.

Espressif Systems

386

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
wifi_country_policy_t policy country policy
struct wifi_active_scan_time_t Range of active scan times per channel.
Public Members
uint32_t min minimum active scan time per channel, units: millisecond
uint32_t max maximum active scan time per channel, units: millisecond, values above 1500ms may cause station to disconnect from AP and are not recommended.
struct wifi_scan_time_t Aggregate of active & passive scan time per channel.
Public Members
wifi_active_scan_time_t active active scan time per channel, units: millisecond.
uint32_t passive passive scan time per channel, units: millisecond, values above 1500ms may cause station to disconnect from AP and are not recommended.
struct wifi_scan_config_t Parameters for an SSID scan.
Public Members
uint8_t *ssid SSID of AP
uint8_t *bssid MAC address of AP
uint8_t channel channel, scan the specific channel
bool show_hidden enable to scan AP whose SSID is hidden
wifi_scan_type_t scan_type scan type, active or passive
wifi_scan_time_t scan_time scan time per channel
struct wifi_ap_record_t Description of a WiFi AP.
Public Members
uint8_t bssid[6] MAC address of AP
uint8_t ssid[33] SSID of AP

Espressif Systems

387

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
uint8_t primary channel of AP
wifi_second_chan_t second secondary channel of AP
int8_t rssi signal strength of AP
wifi_auth_mode_t authmode authmode of AP
wifi_cipher_type_t pairwise_cipher pairwise cipher of AP
wifi_cipher_type_t group_cipher group cipher of AP
wifi_ant_t ant antenna used to receive beacon from AP
uint32_t phy_11b : 1 bit: 0 flag to identify if 11b mode is enabled or not
uint32_t phy_11g : 1 bit: 1 flag to identify if 11g mode is enabled or not
uint32_t phy_11n : 1 bit: 2 flag to identify if 11n mode is enabled or not
uint32_t phy_lr : 1 bit: 3 flag to identify if low rate is enabled or not
uint32_t wps : 1 bit: 4 flag to identify if WPS is supported or not
uint32_t ftm_responder : 1 bit: 5 flag to identify if FTM is supported in responder mode
uint32_t ftm_initiator : 1 bit: 6 flag to identify if FTM is supported in initiator mode
uint32_t reserved : 25 bit: 7..31 reserved
wifi_country_t country country information of AP
struct wifi_scan_threshold_t Structure describing parameters for a WiFi fast scan.
Public Members
int8_t rssi The minimum rssi to accept in the fast scan mode
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

Espressif Systems

388

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

389

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

390

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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 mlengthnfield, minus 4.
struct wifi_pkt_rx_ctrl_t Received packet radio metadata header, this is the common header at the beginning of all promiscuous mode RX callback buffers.
Public Members
signed rssi : 8 Received Signal Strength Indicator(RSSI) of packet. unit: dBm
unsigned rate : 5 PHY rate encoding of the packet. Only valid for non HT(11bg) packet
unsigned __pad0__ : 1 reserved
unsigned sig_mode : 2 0: non HT(11bg) packet; 1: HT(11n) packet; 3: VHT(11ac) packet
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

Espressif Systems

391

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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
unsigned __pad4__ : 8 reserved
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 __pad5__ : 8 reserved
unsigned timestamp : 32 timestamp. The local time when this packet is received. It is precise only if modem sleep or light sleep is not enabled. unit: microsecond
unsigned __pad6__ : 32 reserved
signed noise_floor : 8 noise floor of Radio Frequency Module(RF). unit: 0.25dBm
unsigned __pad7__ : 24 reserved
unsigned __pad8__ : 32 reserved
unsigned __pad9__ : 31 reserved
unsigned ant : 1 antenna number from which this packet is received. 0: WiFi antenna 0; 1: WiFi antenna 1
unsigned __pad10__ : 32 reserved
unsigned __pad11__ : 32 reserved
unsigned __pad12__ : 32 reserved
unsigned sig_len : 12 length of packet including Frame Check Sequence(FCS)

Espressif Systems

392

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
unsigned __pad13__ : 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 mbufnparameter 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 determined by packet type argument of callback.
struct wifi_promiscuous_filter_t Mask for filtering different packet types in promiscuous mode.
Public Members
uint32_t filter_mask OR of one or more filter values WIFI_PROMIS_FILTER_*
struct wifi_csi_config_t Channel state information(CSI) configuration type.
Public Members
bool lltf_en enable to receive legacy long training field(lltf) data. Default enabled
bool htltf_en enable to receive HT long training field(htltf) data. Default enabled
bool stbc_htltf2_en enable to receive space time block code HT long training field(stbc-htltf2) data. Default enabled
bool ltf_merge_en enable to generate htlft data by averaging lltf and ht_ltf data when receiving HT packet. Otherwise, use ht_ltf data directly. Default enabled
bool channel_filter_en enable to turn on channel filter to smooth adjacent sub-carrier. Disable it to keep independence of adjacent sub-carrier. Default enabled
bool manu_scale manually scale the CSI data by left shifting or automatically scale the CSI data. If set true, please set the shift bits. false: automatically. true: manually. Default false
uint8_t shift manually left shift bits of the scale of the CSI data. The range of the left shift bits is 0~15
struct wifi_csi_info_t CSI data type.

Espressif Systems

393

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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, itns ignored if rx_ant_mode is not WIFI_ANT_MODE_AUTO
wifi_ant_mode_t tx_ant_mode WiFi antenna mode for transmission, it can be set to WIFI_ANT_MODE_AUTO only if rx_ant_mode is set to WIFI_ANT_MODE_AUTO
uint8_t enabled_ant0 : 4 Index (in antenna GPIO configuration) of enabled WIFI_ANT_MODE_ANT0
uint8_t enabled_ant1 : 4 Index (in antenna GPIO configuration) of enabled WIFI_ANT_MODE_ANT1
struct wifi_action_tx_req_t Action Frame Tx Request.

Espressif Systems

394

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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 100ns 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 isuccess, 1 - failure
uint8_t number number of scan results
uint8_t scan_id scan sequence number, used for block scan
struct wifi_event_sta_connected_t Argument structure for WIFI_EVENT_STA_CONNECTED event
Public Members
uint8_t ssid[32] SSID of connected AP
uint8_t ssid_len SSID length of connected AP

Espressif Systems

395

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

396

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

struct wifi_event_ap_staconnected_t Argument structure for WIFI_EVENT_AP_STACONNECTED event

Public Members
uint8_t mac[6] MAC address of the station connected to ESP32 soft-AP
uint8_t aid the aid that ESP32 soft-AP gives to the station connected to
bool is_mesh_child flag to identify mesh child
struct wifi_event_ap_stadisconnected_t Argument structure for WIFI_EVENT_AP_STADISCONNECTED event

Public Members
uint8_t mac[6] MAC address of the station disconnects to ESP32 soft-AP
uint8_t aid the aid that ESP32 soft-AP gave to the station disconnects to
bool is_mesh_child flag to identify mesh child
struct wifi_event_ap_probe_req_rx_t Argument structure for WIFI_EVENT_AP_PROBEREQRECVED event

Public Members
int rssi Received probe request signal strength
uint8_t mac[6] MAC address of the station which send probe request
struct wifi_event_bss_rssi_low_t Argument structure for WIFI_EVENT_STA_BSS_RSSI_LOW event

Public Members
int32_t rssi RSSI value of bss
struct wifi_ftm_report_entry_t Argument structure for

Public Members
uint8_t dlog_token Dialog Token of the FTM frame
int8_t rssi RSSI of the FTM frame received
uint32_t rtt Round Trip Time in pSec with a peer

Espressif Systems

397

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

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

Espressif Systems

398

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Macros WIFI_OFFCHAN_TX_REQ WIFI_OFFCHAN_TX_CANCEL
WIFI_ROC_REQ
WIFI_ROC_CANCEL
WIFI_PROTOCOL_11B
WIFI_PROTOCOL_11G
WIFI_PROTOCOL_11N
WIFI_PROTOCOL_LR
ESP_WIFI_MAX_CONN_NUM max number of stations which can connect to ESP32 soft-AP
WIFI_VENDOR_IE_ELEMENT_ID
WIFI_PROMIS_FILTER_MASK_ALL filter all packets
WIFI_PROMIS_FILTER_MASK_MGMT filter the packets with type of WIFI_PKT_MGMT
WIFI_PROMIS_FILTER_MASK_CTRL filter the packets with type of WIFI_PKT_CTRL
WIFI_PROMIS_FILTER_MASK_DATA filter the packets with type of WIFI_PKT_DATA
WIFI_PROMIS_FILTER_MASK_MISC filter the packets with type of WIFI_PKT_MISC
WIFI_PROMIS_FILTER_MASK_DATA_MPDU filter the MPDU which is a kind of WIFI_PKT_DATA
WIFI_PROMIS_FILTER_MASK_DATA_AMPDU filter the AMPDU which is a kind of WIFI_PKT_DATA
WIFI_PROMIS_FILTER_MASK_FCSFAIL filter the FCS failed packets, do not open it in general
WIFI_PROMIS_CTRL_FILTER_MASK_ALL filter all control packets
WIFI_PROMIS_CTRL_FILTER_MASK_WRAPPER filter the control packets with subtype of Control Wrapper
WIFI_PROMIS_CTRL_FILTER_MASK_BAR filter the control packets with subtype of Block Ack Request
WIFI_PROMIS_CTRL_FILTER_MASK_BA filter the control packets with subtype of Block Ack
WIFI_PROMIS_CTRL_FILTER_MASK_PSPOLL filter the control packets with subtype of PS-Poll
WIFI_PROMIS_CTRL_FILTER_MASK_RTS filter the control packets with subtype of RTS
WIFI_PROMIS_CTRL_FILTER_MASK_CTS filter the control packets with subtype of CTS
WIFI_PROMIS_CTRL_FILTER_MASK_ACK filter the control packets with subtype of ACK
WIFI_PROMIS_CTRL_FILTER_MASK_CFEND filter the control packets with subtype of CF-END

Espressif Systems

399

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

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

Espressif Systems

400

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
WIFI_COUNTRY_POLICY_AUTO Country policy is auto, use the country info of AP to which the station is connected
WIFI_COUNTRY_POLICY_MANUAL Country policy is manual, always use the configured country info
enum wifi_auth_mode_t Values: WIFI_AUTH_OPEN = 0 authenticate mode : open WIFI_AUTH_WEP authenticate mode : WEP WIFI_AUTH_WPA_PSK authenticate mode : WPA_PSK WIFI_AUTH_WPA2_PSK authenticate mode : WPA2_PSK WIFI_AUTH_WPA_WPA2_PSK authenticate mode : WPA_WPA2_PSK WIFI_AUTH_WPA2_ENTERPRISE authenticate mode : WPA2_ENTERPRISE WIFI_AUTH_WPA3_PSK authenticate mode : WPA3_PSK WIFI_AUTH_WPA2_WPA3_PSK authenticate mode : WPA2_WPA3_PSK WIFI_AUTH_WAPI_PSK authenticate mode : WAPI_PSK WIFI_AUTH_MAX
enum wifi_err_reason_t Values: WIFI_REASON_UNSPECIFIED = 1 WIFI_REASON_AUTH_EXPIRE = 2 WIFI_REASON_AUTH_LEAVE = 3 WIFI_REASON_ASSOC_EXPIRE = 4 WIFI_REASON_ASSOC_TOOMANY = 5 WIFI_REASON_NOT_AUTHED = 6 WIFI_REASON_NOT_ASSOCED = 7 WIFI_REASON_ASSOC_LEAVE = 8 WIFI_REASON_ASSOC_NOT_AUTHED = 9 WIFI_REASON_DISASSOC_PWRCAP_BAD = 10 WIFI_REASON_DISASSOC_SUPCHAN_BAD = 11 WIFI_REASON_BSS_TRANSITION_DISASSOC = 12 WIFI_REASON_IE_INVALID = 13 WIFI_REASON_MIC_FAILURE = 14 WIFI_REASON_4WAY_HANDSHAKE_TIMEOUT = 15 WIFI_REASON_GROUP_KEY_UPDATE_TIMEOUT = 16

Espressif Systems

401

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
WIFI_REASON_IE_IN_4WAY_DIFFERS = 17 WIFI_REASON_GROUP_CIPHER_INVALID = 18 WIFI_REASON_PAIRWISE_CIPHER_INVALID = 19 WIFI_REASON_AKMP_INVALID = 20 WIFI_REASON_UNSUPP_RSN_IE_VERSION = 21 WIFI_REASON_INVALID_RSN_IE_CAP = 22 WIFI_REASON_802_1X_AUTH_FAILED = 23 WIFI_REASON_CIPHER_SUITE_REJECTED = 24 WIFI_REASON_INVALID_PMKID = 53 WIFI_REASON_BEACON_TIMEOUT = 200 WIFI_REASON_NO_AP_FOUND = 201 WIFI_REASON_AUTH_FAIL = 202 WIFI_REASON_ASSOC_FAIL = 203 WIFI_REASON_HANDSHAKE_TIMEOUT = 204 WIFI_REASON_CONNECTION_FAIL = 205 WIFI_REASON_AP_TSF_RESET = 206 WIFI_REASON_ROAMING = 207 enum wifi_second_chan_t Values: WIFI_SECOND_CHAN_NONE = 0
the channel width is HT20 WIFI_SECOND_CHAN_ABOVE
the channel width is HT40 and the secondary channel is above the primary channel WIFI_SECOND_CHAN_BELOW
the channel width is HT40 and the secondary channel is below the primary channel enum wifi_scan_type_t
Values: WIFI_SCAN_TYPE_ACTIVE = 0
active scan WIFI_SCAN_TYPE_PASSIVE
passive scan enum wifi_cipher_type_t
Values: WIFI_CIPHER_TYPE_NONE = 0
the cipher type is none WIFI_CIPHER_TYPE_WEP40
the cipher type is WEP40 WIFI_CIPHER_TYPE_WEP104
the cipher type is WEP104 WIFI_CIPHER_TYPE_TKIP
the cipher type is TKIP WIFI_CIPHER_TYPE_CCMP
the cipher type is CCMP

Espressif Systems

402

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
WIFI_CIPHER_TYPE_TKIP_CCMP the cipher type is TKIP and CCMP
WIFI_CIPHER_TYPE_AES_CMAC128 the cipher type is AES-CMAC-128
WIFI_CIPHER_TYPE_SMS4 the cipher type is SMS4
WIFI_CIPHER_TYPE_GCMP the cipher type is GCMP
WIFI_CIPHER_TYPE_GCMP256 the cipher type is GCMP-256
WIFI_CIPHER_TYPE_AES_GMAC128 the cipher type is AES-GMAC-128
WIFI_CIPHER_TYPE_AES_GMAC256 the cipher type is AES-GMAC-256
WIFI_CIPHER_TYPE_UNKNOWN the cipher type is unknown
enum wifi_ant_t WiFi antenna.
Values:
WIFI_ANT_ANT0 WiFi antenna 0
WIFI_ANT_ANT1 WiFi antenna 1
WIFI_ANT_MAX Invalid WiFi antenna
enum wifi_scan_method_t Values:
WIFI_FAST_SCAN = 0 Do fast scan, scan will end after find SSID match AP
WIFI_ALL_CHANNEL_SCAN All channel scan, scan will end after scan all the channel
enum wifi_sort_method_t Values:
WIFI_CONNECT_AP_BY_SIGNAL = 0 Sort match AP in scan list by RSSI
WIFI_CONNECT_AP_BY_SECURITY Sort match AP in scan list by security mode
enum wifi_ps_type_t Values:
WIFI_PS_NONE No power save
WIFI_PS_MIN_MODEM Minimum modem power saving. In this mode, station wakes up to receive beacon every DTIM period
WIFI_PS_MAX_MODEM Maximum modem power saving. In this mode, interval to receive beacons is determined by the listen_interval parameter in wifi_sta_config_t

Espressif Systems

403

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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 mbufnargument is wifi_promiscuous_pkt_t
WIFI_PKT_CTRL Control frame, indicates mbufnargument is wifi_promiscuous_pkt_t
WIFI_PKT_DATA Data frame, indiciates mbufnargument is wifi_promiscuous_pkt_t
WIFI_PKT_MISC Other type, such as MIMO etc.mbufnargument is wifi_promiscuous_pkt_t but the payload is zero length.
enum wifi_ant_mode_t WiFi antenna mode.
Values:
WIFI_ANT_MODE_ANT0 Enable WiFi antenna 0 only
WIFI_ANT_MODE_ANT1 Enable WiFi antenna 1 only

Espressif Systems

404

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

405

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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

Espressif Systems

406

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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 APns RSSI crossed configured threshold
WIFI_EVENT_ACTION_TX_STATUS Status indication of Action Tx operation
WIFI_EVENT_ROC_DONE Remain-on-Channel operation complete
WIFI_EVENT_STA_BEACON_TIMEOUT ESP32 station beacon timeout
WIFI_EVENT_MAX Invalid WiFi event ID
enum wifi_event_sta_wps_fail_reason_t Argument structure for WIFI_EVENT_STA_WPS_ER_FAILED event
Values:
WPS_FAIL_REASON_NORMAL = 0 ESP32 WPS normal fail reason
WPS_FAIL_REASON_RECV_M2D ESP32 WPS receive M2D frame
WPS_FAIL_REASON_MAX
enum wifi_ftm_status_t FTM operation status types.
Values:
FTM_STATUS_SUCCESS = 0 FTM exchange is successful
FTM_STATUS_UNSUPPORTED Peer does not support FTM

Espressif Systems

407

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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-S3 devices, check Provisioning API.

Application Example Connect ESP32-S3 to target AP using SmartConfig: wifi/smart_config.

API Reference

Header File · components/esp_wifi/include/esp_smartconfig.h

Functions const char *esp_smartconfig_get_version(void)
Get the version of SmartConfig.
Return · SmartConfig version const char.
esp_err_t esp_smartconfig_start(const smartconfig_start_config_t *config) Start SmartConfig, config ESP device to connect AP. You need to broadcast information by phone APP. Device sniffer special packets from the air that containing SSID and password of target AP.
Attention 1. This API can be called in station or softAP-station mode. Attention 2. Can not call esp_smartconfig_start twice before it finish, please call esp_smartconfig_stop first. Return
· ESP_OK: succeed · others: fail Parameters · config: pointer to smartconfig start configure structure
esp_err_t esp_smartconfig_stop(void) Stop SmartConfig, free the buffer taken by esp_smartconfig_start.
Attention Whether connect to AP succeed or not, this API should be called to free memory taken by smartconfig_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.

Espressif Systems

408

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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.
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.

Espressif Systems

409

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
uint8_t cellphone_ip[4] IP address of cellphone.
struct smartconfig_start_config_t Configure structure for esp_smartconfig_start
Public Members
bool enable_log Enable smartconfig logs.
bool esp_touch_v2_enable_crypt Enable ESPTouch v2 crypt.
char *esp_touch_v2_key ESPTouch v2 crypt key, len should be 16.
Macros SMARTCONFIG_START_CONFIG_DEFAULT()
Enumerations enum smartconfig_type_t
Values: SC_TYPE_ESPTOUCH = 0
protocol: ESPTouch SC_TYPE_AIRKISS
protocol: AirKiss SC_TYPE_ESPTOUCH_AIRKISS
protocol: ESPTouch and AirKiss SC_TYPE_ESPTOUCH_V2
protocol: ESPTouch v2 enum smartconfig_event_t
Smartconfig event declarations Values: SC_EVENT_SCAN_DONE
ESP32 station smartconfig has finished to scan for APs SC_EVENT_FOUND_CHANNEL
ESP32 station smartconfig has found the channel of the target AP SC_EVENT_GOT_SSID_PSWD
ESP32 station smartconfig got the SSID and password SC_EVENT_SEND_ACK_DONE
ESP32 station smartconfig has sent ACK to cellphone
ESP-NOW
Overview ESP-NOW is a kind of connectionless Wi-Fi communication protocol that is defined by Espressif. In ESP-NOW, application data is encapsulated in a vendor-specific action frame and then transmitted from one Wi-Fi device to another without connection. CTR with CBC-MAC Protocol(CCMP) is used to protect the action frame for security. ESP-NOW is widely used in smart light, remote controlling, sensor, etc.

Espressif Systems

410

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Frame Format ESP-NOW uses a vendor-specific action frame to transmit ESP-NOW data. The default ESPNOW 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 vendorspecific action frame will not be encrypted.
Encrypting multicast vendor-specific action frame is not supported.

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

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

Espressif Systems

411

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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 doesnnt 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.
Application Examples
· Example of sending and receiving ESP-NOW data between two devices: wifi/espnow. · For more application examples of how to use ESP-NOW, please visit ESP-NOW repository.
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.
Return · ESP_OK : succeed

Espressif Systems

412

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· 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 doesnnt 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
esp_err_t esp_now_del_peer(const uint8_t *peer_addr) Delete a peer from peer list.

Espressif Systems

413

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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 · num: number of peers

Espressif Systems

414

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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.

Public Members
int total_num Total number of ESPNOW peers, maximum value is ESP_NOW_MAX_TOTAL_PEER_NUM

Espressif Systems

415

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

int encrypt_num Number of encrypted ESPNOW peers, maximum value is ESP_NOW_MAX_ENCRYPT_PEER_NUM

Macros ESP_ERR_ESPNOW_BASE
ESPNOW error number base. ESP_ERR_ESPNOW_NOT_INIT
ESPNOW is not initialized.
ESP_ERR_ESPNOW_ARG Invalid argument
ESP_ERR_ESPNOW_NO_MEM Out of memory
ESP_ERR_ESPNOW_FULL ESPNOW peer list is full
ESP_ERR_ESPNOW_NOT_FOUND ESPNOW peer is not found
ESP_ERR_ESPNOW_INTERNAL Internal error
ESP_ERR_ESPNOW_EXIST ESPNOW peer has existed
ESP_ERR_ESPNOW_IF Interface error
ESP_NOW_ETH_ALEN Length of ESPNOW peer MAC address
ESP_NOW_KEY_LEN Length of ESPNOW peer local master key
ESP_NOW_MAX_TOTAL_PEER_NUM Maximum number of ESPNOW total peers
ESP_NOW_MAX_ENCRYPT_PEER_NUM Maximum number of ESPNOW encrypted peers
ESP_NOW_MAX_DATA_LEN Maximum length of ESPNOW data which is sent very time

Type Definitions typedef struct esp_now_peer_info esp_now_peer_info_t
ESPNOW peer information parameters. typedef struct esp_now_peer_num esp_now_peer_num_t
Number of ESPNOW peers which exist currently.
typedef void (*esp_now_recv_cb_t)(const uint8_t *mac_addr, const uint8_t *data, int data_len)
Callback function of receiving ESPNOW data.
Parameters · mac_addr: peer MAC address · data: received data · data_len: length of received data
typedef void (*esp_now_send_cb_t)(const uint8_t *mac_addr, esp_now_send_status_t status) Callback function of sending ESPNOW data.
Parameters · mac_addr: peer MAC address

Espressif Systems

416

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· 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 Framework.
ESP-WIFI-MESH Programming Model
Software Stack The ESP-WIFI-MESH software stack is built atop the Wi-Fi Driver/FreeRTOS and may use the LwIP Stack in some instances (i.e. the root node). The following diagram illustrates the ESP-WIFI-MESH software stack.

Fig. 2: ESP-WIFI-MESH Software Stack
System Events An application interfaces with ESP-WIFI-MESH via ESP-WIFI-MESH Events. Since ESPWIFI-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.

Espressif Systems

417

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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 connection/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 downstream respectively. Likewise, IP_EVENT_STA_GOT_IP and IP_EVENT_STA_LOST_IP can be used to indicate 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 WiFi 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-MESHns self-organizing behavior. Therefore, userns should not call Wi-Fi APIs after esp_mesh_start() is called, and before esp_mesh_stop() is called.
LwIP & ESP-WIFI-MESH The application can access the ESP-WIFI-MESH stack directly without having to go through the LwIP stack. The LwIP stack is only required by the root node to transmit/receive data to/from an external IP network. However, since every node can potentially become the root node (due to automatic root node selection), each node must still initialize the LwIP stack.
Each node is required to initialize LwIP by calling tcpip_adapter_init(). In order to prevent non-root node access to LwIP, the application should stop the following services after LwIP initialization:
· DHCP server service on the softAP interface. · DHCP client service on the station interface.
The following code snippet demonstrates how to initialize LwIP for ESP-WIFI-MESH applications.
/* tcpip initialization */ tcpip_adapter_init(); /*
* for mesh * stop DHCP server on softAP interface by default * stop DHCP client on station interface by default */ ESP_ERROR_CHECK(tcpip_adapter_dhcps_stop(TCPIP_ADAPTER_IF_AP)); ESP_ERROR_CHECK(tcpip_adapter_dhcpc_stop(TCPIP_ADAPTER_IF_STA));
Note: ESP-WIFI-MESH requires a root node to be connected with a router. Therefore, in the event that a node becomes the root, the corresponding handler must start the DHCP client service and immediately obtain an

Espressif Systems

418

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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 structure contains the following parameters used to configure ESP-WIFI-MESH:

Parameter Channel Mesh ID Router Mesh AP Crypto Functions

Description Range from 1 to 14 ID of ESP-WIFI-MESH Network, see mesh_addr_t Router Configuration, see mesh_router_t Mesh AP Configuration, see mesh_ap_cfg_t Crypto Functions for Mesh IE, see mesh_crypto_funcs_t

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

Espressif Systems

419

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

/* 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 autonomously scan/select/connect/reconnect to other nodes and routers. This feature allows an ESP-WIFI-MESH network 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 nodens 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 nodens current Wi-Fi state when disabling self organized networking.

Espressif Systems

420

Release v5.0-dev-1424-g2467aa7f6c

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 nodens 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 N
Y

Is Root Node N
Y
N
Y

Effects
· Nodes already connected to a parent node will remain connected.
· Nodes previously scanning for a parent nodes will stop scanning. Call esp_mesh_connect() to restart.
· A root node already connected to router will stay connected.
· A root node disconnected from router will need to call esp_mesh_connect() to reconnect.
· Nodes without a parent node will automatically select a preferred parent and connect.
· Nodes already connected to a parent node will disconnect, reselect a preferred parent node, and connect.
· For a root node to connect to a parent node, it must give up itns role as root. Therefore, a root node will disconnect from the router and all child nodes, select a preferred parent 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

421

Release v5.0-dev-1424-g2467aa7f6c

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 applicationns 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 following 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

422

Release v5.0-dev-1424-g2467aa7f6c

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

Espressif Systems

423

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_ERR_MESH_QUEUE_FULL · ESP_ERR_MESH_NO_ROUTE_FOUND · ESP_ERR_MESH_DISCARD Parameters · [in] to: the address of the final destination of the packet
­ If the packet is to the root, set this parameter to NULL. ­ If the packet is to an external IP network, set this parameter to the IPv4:PORT combination.
This packet will be delivered to the root firstly, then the root will forward this packet to the final IP server address. · [in] data: pointer to a sending mesh packet ­ Field size should not exceed MESH_MPS. Note that the size of one mesh packet should not exceed MESH_MTU. ­ Field proto should be set to data protocol in use (default is MESH_PROTO_BIN for binary). ­ Field tos should be set to transmission tos (type of service) in use (default is MESH_TOS_P2P for point-to-point reliable). · [in] flag: bitmap for data sent ­ Speed up the route search  If the packet is to the root and otopparameter 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 (otopparameter isnnt 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 isnnt 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

Espressif Systems

424

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_ERR_MESH_ARGUMENT · 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 isnnt immediately available (0:no wait, portMAX_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 timeout_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() hasnn
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() isnnt 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 isnnt 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)

Espressif Systems

425

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Set mesh stack configuration.
· Use MESH_INIT_CONFIG_DEFAULT() to initialize the default values, mesh IE is encrypted by default.
· 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 isnnt 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 couldnnt 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

Espressif Systems

426

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· [in] id: pointer to mesh network ID
esp_err_t esp_mesh_get_id(mesh_addr_t *id) Get mesh network ID.
Return · ESP_OK · 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 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.

event

Espressif Systems

427

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Attention This API shall be called before mesh is started. 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.

Espressif Systems

428

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Return · ESP_OK · ESP_FAIL
Parameters · [in] enable: enable or disable self-organized networking · [in] select_parent: Only valid when self-organized networking is enabled. ­ if select_parent is set to true, the root will give up its mesh root status and search for a new parent like other non-root devices.
bool esp_mesh_get_self_organized(void) Return whether enable self-organized networking or not.
Return true/false
esp_err_t esp_mesh_waive_root(const mesh_vote_t *vote, int reason) Cause the root device to give up (waive) its mesh root status.
· A device is elected root primarily based on RSSI from the external router. · If external router conditions change, users can call this API to perform a root switch. · In this API, users could specify a desired root address to replace itself or specify an attempts value to
ask current root to initiate a new round of voting. During the voting, a better root candidate would be expected to find to replace the current one. · If no desired root candidate, the vote will try a specified number of attempts (at least 15). If no better root candidate is found, keep the current one. If a better candidate is found, the new better one will send a root switch request to the current root, current root will respond with a root switch acknowledgment. · After that, the new candidate will connect to the router to be a new root, the previous root will disconnect with the router and choose another parent instead.
Root switch is completed with minimal disruption to the whole mesh network.
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)

Espressif Systems

429

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· If mesh softAP hasnnt received any data from an associated child within this time, mesh softAP will take this child inactive and disassociate it.
· If mesh softAP is encrypted, this value should be set a greater value, such as 30 seconds.
Return · ESP_OK · ESP_FAIL
Parameters · [in] seconds: the expired time
int esp_mesh_get_ap_assoc_expire(void) Get mesh softAP associate expired time.
Return seconds
int esp_mesh_get_total_node_num(void) Get total number of devices in current network (including the root)
Attention The returned value might be incorrect when the network is changing. Return total number of devices (including the root)
int esp_mesh_get_routing_table_size(void) Get the number of devices in this devicens sub-network (including self)
Return the number of devices over this devicens 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 devicens 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

Espressif Systems

430

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

int esp_mesh_available_txupQ_num(const mesh_addr_t *addr, uint32_t *xseqno_in) Return the number of packets could be accepted from the specified address.
Return the number of upQ for a certain address Parameters
· [in] addr: self address or an associate children address · [out] xseqno_in: sequence number of the last received packet from the specified address
esp_err_t esp_mesh_set_xon_qsize(int qsize) Set the number of queue.
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

Espressif Systems

431

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_OK · ESP_MESH_ERR_ARGUMENT Parameters · [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

Espressif Systems

432

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
int esp_mesh_get_root_healing_delay(void) Get delay time before network starts root healing.
Return delay time in milliseconds
esp_err_t esp_mesh_fix_root(bool enable) Enable network Fixed Root Setting.
· Enabling fixed root disables automatic election of the root node via voting. · All devices in the network shall use the same Fixed Root Setting (enabled or disabled). · If Fixed Root is enabled, users should make sure a root node is designated for the network.
Return · ESP_OK
Parameters · [in] enable: enable or not
bool esp_mesh_is_root_fixed(void) Check whether network Fixed Root Setting is enabled.
· Enable/disable network Fixed Root Setting by API esp_mesh_fix_root(). · Network Fixed Root Setting also changes with the oflagpvalue 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.

Espressif Systems

433

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Attention Different from esp_wifi_scan_get_ap_records(), this API only gets one of APs scanned each time. See omanual_networkingpexample.
Return · 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

Get nodes in the subnet of a specific child.

*nodes, int nodes_num)

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

Espressif Systems

434

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Attention This API is only called by the root. Return
· ESP_OK Parameters
· [in] new_bssid: the new router BSSID if the router changes · [in] csa_newchan: the new channel number to which the whole network is moving · [in] csa_count: channel switch period(beacon count), unit is based on beacon interval of its
softAP, the default value is 15.
esp_err_t esp_mesh_get_router_bssid(uint8_t *router_bssid) Get the router BSSID.
Return · ESP_OK · 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

Espressif Systems

435

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

bool esp_mesh_is_device_active(void) Check whether the device is in active state.

· If the device is not in active state, it will neither transmit nor receive frames.

Return true/false

esp_err_t esp_mesh_set_active_duty_cycle(int dev_duty, int dev_duty_type) Set the device duty cycle and type.

· The range of dev_duty values is 1 to 100. The default value is 10.

· dev_duty = 100, the PS will be stopped.

· dev_duty is better to not less than 5.

· dev_duty_type

could

be

MESH_PS_DEVICE_DUTY_REQUEST

or

MESH_PS_DEVICE_DUTY_DEMAND.

· If dev_duty_type is set to MESH_PS_DEVICE_DUTY_REQUEST, the device will use a nwk_duty

provided by the network.

· If dev_duty_type is set to MESH_PS_DEVICE_DUTY_DEMAND, the device will use the specified

dev_duty.

Attention This API can be called at any time after mesh is started.

Return

· ESP_OK

· ESP_FAIL

Parameters

· [in] dev_duty: device duty cycle

· [in]

dev_duty_type:

device PS duty cycle type,

MESH_PS_NETWORK_DUTY_MASTER

not accept

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 different 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,

Espressif Systems

436

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

437

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

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

Espressif Systems

438

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

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

Espressif Systems

439

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

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

Espressif Systems

440

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

441

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Public Members
uint8_t *data data
uint16_t size data size
mesh_proto_t proto data protocol
mesh_tos_t tos data type of service
struct mesh_router_t Router configuration.
Public Members
uint8_t ssid[32] SSID
uint8_t ssid_len length of SSID
uint8_t bssid[6] BSSID, if this value is specified, users should also specify oallow_router_switchp.
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 ofailp(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 + nonmesh_max_connection max 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

Espressif Systems

442

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
bool allow_channel_switch if this value is set, when ofailp(mesh_attempts_t) times is reached, device will change to a full channel scan for a network that could join. The default value is false.
mesh_addr_t mesh_id mesh network identification
mesh_router_t router router configuration
mesh_ap_cfg_t mesh_ap mesh softAP configuration
const mesh_crypto_funcs_t *crypto_funcs crypto functions
struct mesh_vote_t Vote.
Public Members
float percentage vote percentage threshold for approval of being a root
bool is_rc_specified if true, rc_addr shall be specified (Unimplemented). if false, attempts value shall be specified to make network start root election.
mesh_rc_config_t config vote address configuration
struct mesh_tx_pending_t The number of packets pending in the queue waiting to be sent by the mesh stack.
Public Members
int to_parent to parent queue
int to_parent_p2p to parent (P2P) queue
int to_child to child queue
int to_child_p2p to child (P2P) queue
int mgmt management queue
int broadcast broadcast and multicast queue
struct mesh_rx_pending_t The number of packets available in the queue waiting to be received by applications.
Public Members
int toDS to external DS

Espressif Systems

443

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

int toSelf to self
Macros MESH_ROOT_LAYER
root layer value MESH_MTU
max transmit unit(in bytes)
MESH_MPS max payload size(in bytes)
ESP_ERR_MESH_WIFI_NOT_START Mesh error code definition.
Wi-Fi isnnt started
ESP_ERR_MESH_NOT_INIT mesh isnnt initialized
ESP_ERR_MESH_NOT_CONFIG mesh isnnt configured
ESP_ERR_MESH_NOT_START mesh isnnt 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

Espressif Systems

444

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

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

Espressif Systems

445

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

446

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
MESH_EVENT_NO_PARENT_FOUND no parent found
MESH_EVENT_LAYER_CHANGE layer changes over the mesh network
MESH_EVENT_TODS_STATE state represents whether the root is able to access external IP network
MESH_EVENT_VOTE_STARTED the process of voting a new root is started either by children or by the root
MESH_EVENT_VOTE_STOPPED the process of voting a new root is stopped
MESH_EVENT_ROOT_ADDRESS the root address is obtained. It is posted by mesh stack automatically.
MESH_EVENT_ROOT_SWITCH_REQ root switch request sent from a new voted root candidate
MESH_EVENT_ROOT_SWITCH_ACK root switch acknowledgment responds the above request sent from current root
MESH_EVENT_ROOT_ASKED_YIELD the root is asked yield by a more powerful existing root. If self organized is disabled and this device is specified to be a root by users, users should set a new parent for this device. if self organized is enabled, this device will find a new parent by itself, users could ignore this event.
MESH_EVENT_ROOT_FIXED when devices join a network, if the setting of Fixed Root for one device is different from that of its parent, the device will update the setting the same as its parentns. 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:

Espressif Systems

447

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

MESH_IDLE hasnnt joined the mesh network yet
MESH_ROOT the only sink of the mesh network. Has the ability to access external IP network
MESH_NODE intermediate device. Has the ability to forward packets over the mesh network
MESH_LEAF has no forwarding ability
MESH_STA connect to router with a standlone Wi-Fi station mode, no network expansion capability
enum mesh_proto_t Protocol of transmitted application data.
Values:
MESH_PROTO_BIN binary
MESH_PROTO_HTTP HTTP protocol
MESH_PROTO_JSON JSON format
MESH_PROTO_MQTT MQTT protocol
MESH_PROTO_AP IP network mesh communication of nodens AP interface
MESH_PROTO_STA IP network mesh communication of nodens 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

Espressif Systems

448

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

MESH_REASON_PARENT_IDLE parent is idle
MESH_REASON_LEAF the connected device is changed to a leaf
MESH_REASON_DIFF_ID in different mesh ID
MESH_REASON_ROOTS root conflict is detected
MESH_REASON_PARENT_STOPPED parent has stopped the mesh
MESH_REASON_SCAN_FAIL scan fail
MESH_REASON_IE_UNKNOWN unknown IE
MESH_REASON_WAIVE_ROOT waive root
MESH_REASON_PARENT_WORSE parent with very poor RSSI
MESH_REASON_EMPTY_PASSWORD use an empty password to connect to an encrypted parent
MESH_REASON_PARENT_UNENCRYPTED connect to an unencrypted parent/router
enum esp_mesh_topology_t Mesh topology.
Values:
MESH_TOPO_TREE tree topology
MESH_TOPO_CHAIN chain topology
enum mesh_event_toDS_state_t The reachability of the root to a DS (distribute system)
Values:
MESH_TODS_UNREACHABLE the root isnnt 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 protocol 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

Espressif Systems

449

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· Works with electronic or printed QR codes, or human-readable strings · Supports both WPA2 and WPA3 networks Please refer to Wi-Fi Alliancens official page on Easy Connect for more information. ESP32-S3 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-S3 to their Wi-Fi network. The provisioning device needs to be connected to the AP which need not support Wi-Fi Easy ConnectTM. 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-S3 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.

Espressif Systems

450

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Listens on every Channel from Channel List for a pre-defined wait time.
Return · ESP_OK: Success · ESP_FAIL: Generic Failure · ESP_ERR_INVALID_STATE: ROC attempted before WiFi is started · ESP_ERR_NO_MEM: Memory allocation failed while posting ROC request
void esp_supp_dpp_stop_listen(void) Stop listening on Channels.
Stops listening on Channels and cancels ongoing listen operation.

Macros ESP_ERR_DPP_FAILURE
Generic failure during DPP Operation ESP_ERR_DPP_TX_FAILURE
DPP Frame Tx failed OR not Acked
ESP_ERR_DPP_INVALID_ATTR Encountered invalid DPP Attribute

Type Definitions typedef enum dpp_bootstrap_type esp_supp_dpp_bootstrap_t
Types of Bootstrap Methods for DPP. typedef void (*esp_supp_dpp_event_cb_t)(esp_supp_dpp_event_t evt, void *data)
Callback function for receiving DPP Events from Supplicant.
Callback function will be called with DPP related information.
Parameters · evt: DPP event ID · data: Event data payload

Enumerations enum dpp_bootstrap_type
Types of Bootstrap Methods for DPP.
Values:
DPP_BOOTSTRAP_QR_CODE QR Code Method
DPP_BOOTSTRAP_PKEX Proof of Knowledge Method
DPP_BOOTSTRAP_NFC_URI NFC URI record Method
enum esp_supp_dpp_event_t Types of Callback Events received from DPP Supplicant.
Values:
ESP_SUPP_DPP_URI_READY URI is ready through Bootstrapping
ESP_SUPP_DPP_CFG_RECVD Config received via DPP Authentication
ESP_SUPP_DPP_FAIL DPP Authentication failure

Espressif Systems

451

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Code examples for the Wi-Fi API are provided in the wifi directory of ESP-IDF examples. Code examples for ESP-WIFI-MESH are provided in the mesh directory of ESP-IDF examples.
2.2.2 Ethernet
Ethernet
Overview ESP-IDF provides a set of consistent and flexible APIs to support both internal Ethernet MAC (EMAC) controller and external SPI-Ethernet modules. This programming guide is split into the following sections:
1. Basic Ethernet Concepts 2. Configure MAC and PHY 3. Connect Driver to TCP/IP Stack 4. Misc control of Ethernet driver
Basic Ethernet Concepts Ethernet is an asynchronous Carrier Sense Multiple Access with Collision Detect (CSMA/CD) protocol/interface. It is generally not well suited for low power applications. However, with ubiquitous 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:

Espressif Systems

Fig. 4: Ethernet Data Frame Format

452

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Preamble and Start-of-Frame Delimiter The preamble contains seven bytes of 55H, it allows the receiver to lock onto the stream of data before the actual frame arrives. The Start-of-Frame Delimiter (SFD) is a binary sequence 10101011 (as seen on the physical medium). It is sometimes considered to be part of the preamble.
When transmitting and receiving data, the preamble and SFD bytes will automatically be generated or stripped from the packets.
Destination Address The destination address field contains a 6-byte length MAC address of the device that the packet is directed to. If the Least Significant bit in the first byte of the MAC address is set, the address is a multi-cast destination. For example, 01-00-00-00-F0-00 and 33-45-67-89-AB-CD are multi-cast addresses, while 00-00-0000-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 multicast, 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 implementing protocols such as the Internet Protocol (IP) or Address Resolution Protocol (ARP), should program this field with the appropriate type defined by the protocolns 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

Espressif Systems

453

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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, therenre two other common frame types in 10/100 Mbps Ethernet: control frames and VLAN tagged frames. Theynre not supported in ESP-IDF.

Configure MAC and PHY Ethernet driver is composed of two parts: MAC and PHY.
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:
· 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 incoming 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 situations. The value of this field can be ORnd with macros prefixed with ETH_MAC_FLAG_. For example, if the MAC driver should work when cache is disabled, then you should configure this field with ETH_MAC_FLAG_WORK_WITH_CACHE_DISABLE.
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 negotiation 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.

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,

(continues on next page)

Espressif Systems

454

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
(continued from previous page) .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 donnt 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 instructions 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 modulens spec and the examples in esp-idf.
Install Driver To install the Ethernet driver, we need to combine the instance of MAC and PHY and set some additional high-level configurations (i.e. not specific to either MAC or PHY) in esp_eth_config_t:
· mac: instance that created from MAC generator (e.g. esp_eth_mac_new_esp32()). · phy: instance that created from PHY generator (e.g. esp_eth_phy_new_ip101()). · check_link_period_ms: Ethernet driver starts an OS timer to check the link status periodically, this
field is used to set the interval, in milliseconds. · stack_input: In most of Ethernet IoT applications, any Ethernet frame that received by driver
should be passed to upper layer (e.g. TCP/IP stack). This field is set to a function which is responsible 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.

Espressif Systems

455

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

/** Event handler for Ethernet events */ static void eth_event_handler(void *arg, esp_event_base_t event_base,
int32_t event_id, void *event_data) {
uint8_t mac_addr[6] = {0}; /* we can get the ethernet driver handle from event data */ esp_eth_handle_t eth_handle = *(esp_eth_handle_t *)event_data;
switch (event_id) { case ETHERNET_EVENT_CONNECTED:
esp_eth_ioctl(eth_handle, ETH_CMD_G_MAC_ADDR, mac_addr); ESP_LOGI(TAG, "Ethernet Link Up"); ESP_LOGI(TAG, "Ethernet HW Addr %02x:%02x:%02x:%02x:%02x:%02x",
mac_addr[0], mac_addr[1], mac_addr[2], mac_addr[3], mac_ addr[4], mac_addr[5]);
break; case ETHERNET_EVENT_DISCONNECTED:
ESP_LOGI(TAG, "Ethernet Link Down"); break; case ETHERNET_EVENT_START: ESP_LOGI(TAG, "Ethernet Started"); break; case ETHERNET_EVENT_STOP: ESP_LOGI(TAG, "Ethernet Stopped"); break; default: break; } }
esp_event_loop_create_default(); // create a default event loop that running in background esp_event_handler_register(ETH_EVENT, ESP_EVENT_ANY_ID, &eth_event_handler, NULL); // register Ethernet event handler (to deal with user specific stuffs when event like link up/down happened)

Start Ethernet Driver After driver installation, we can start Ethernet immediately. esp_eth_start(eth_handle); // start Ethernet driver state machine

Connect Driver to TCP/IP Stack Up until now, we have installed the Ethernet driver. From the view of OSI (Open System Interconnection), wenre 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 cannt 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;
(continues on next page)

Espressif Systems

456

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
(continued from previous page) 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 usern 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 userns handlers.

Misc control of Ethernet driver The following functions should only be invoked after the Ethernet driver has been installed.
· Stop Ethernet driver: esp_eth_stop() · Update Ethernet data input path: esp_eth_update_input_path() · Misc get/set of Ethernet driver attributes: esp_eth_ioctl()
/* get MAC address */ uint8_t mac_addr[6]; memset(mac_addr, 0, sizeof(mac_addr)); esp_eth_ioctl(eth_handle, ETH_CMD_G_MAC_ADDR, mac_addr); ESP_LOGI(TAG, "Ethernet MAC Address: %02x:%02x:%02x:%02x:%02x:%02x",
mac_addr[0], mac_addr[1], mac_addr[2], mac_addr[3], mac_addr[4], mac_ addr[5]);
/* get PHY address */ int phy_addr = -1; esp_eth_ioctl(eth_handle, ETH_CMD_G_PHY_ADDR, &phy_addr); ESP_LOGI(TAG, "Ethernet PHY Address: %d", phy_addr);

Flow control Ethernet on MCU usually has a limitation in the number of frames it can handle during network congestion, because of the limitation in RAM size. A sending station might be transmitting data faster than the peer end can accept it. Ethernet flow control mechanism allows the receiving node to signal the sender requesting suspension of transmissions until the receiver catches up. The magic behind that is the pause frame, which was defined in IEEE 802.3x.
Pause frame is a special Ethernet frame used to carry the pause command, whose EtherType field is 0x8808, with the Control opcode set to 0x0001. Only stations configured for full-duplex operation may send pause frames. When a station wishes to pause the other end of a link, it sends a pause frame to the 48-bit reserved multicast address of 01-80-C2-00-00-01. The pause frame also includes the period of pause time being requested, in the form of a two-byte integer, ranging from 0 to 65535.

Espressif Systems

457

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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 orouterp: 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 therens no memory for driver · ESP_FAIL: install esp_eth driver failed because some other error occurred
Parameters · [in] config: configuration of the Ethernet driver · [out] out_hdl: handle of Ethernet driver
esp_err_t esp_eth_driver_uninstall(esp_eth_handle_t hdl) Uninstall Ethernet driver.
Note Itns not recommended to uninstall Ethernet driver unless it wonnt 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 reference · 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

Espressif Systems

458

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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 donnt 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 modification

esp_err_t esp_eth_transmit(esp_eth_handle_t hdl, void *buf, size_t length) General Transmit.

Return · ESP_OK: transmit frame buffer successfully · ESP_ERR_INVALID_ARG: transmit frame buffer failed because of some invalid argument · ESP_FAIL: transmit frame buffer failed because some other error occurred
Parameters · [in] 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 olengthpshould set by user, equals the size of buffer. After the function returned, the value of olengthpmeans 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 doesnnt 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 olengthpindicates 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.

Espressif Systems

459

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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 autonegotiation. data argument is pointer to memory of bool datatype to which the current configuration is to be stored.
· ETH_CMD_S_SPEED sets the Ethernet link speed. data argument is pointer to memory of eth_speed_t datatype from which the configuration option is read. Preconditions: Ethernet driver needs to be stopped and auto-negotiation disabled.
· ETH_CMD_G_SPEED gets current Ethernet link speed. data argument is pointer to memory of eth_speed_t datatype to which the speed is to be stored.
· ETH_CMD_S_PROMISCUOUS sets/resets Ethernet interface promiscuous mode. data argument is pointer to memory of bool datatype from which the configuration option is read.
· ETH_CMD_S_FLOW_CTRL sets/resets Ethernet interface flow control. data argument is pointer to memory of bool datatype from which the configuration option is read.
· ETH_CMD_S_DUPLEX_MODE sets the Ethernet duplex mode. data argument is pointer to memory of eth_duplex_t datatype from which the configuration option is read. Preconditions: Ethernet driver needs to be stopped and auto-negotiation disabled.
· ETH_CMD_G_DUPLEX_MODE gets current Ethernet link duplex mode. data argument is pointer to memory of eth_duplex_t datatype to which the duplex mode is to be stored.
· ETH_CMD_S_PHY_LOOPBACK sets/resets PHY to/from loopback mode. data argument is pointer to memory of bool datatype from which the configuration option is read.
Return · ESP_OK: process io command successfully · ESP_ERR_INVALID_ARG: process io command failed because of some invalid argument · ESP_FAIL: process io command failed because some other error occurred · ESP_ERR_NOT_SUPPORTED: requested feature is not supported
Parameters · [in] 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. Itns dangerous when thread A is using 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 wonnt 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

Espressif Systems

460

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

esp_err_t (*stack_input)(esp_eth_handle_t eth_handle, uint8_t *buffer, uint32_t length, void
*priv) Input frame buffer to userns stack.

Return · ESP_OK: input frame buffer to upper stack successfully · ESP_FAIL: error occurred when inputting buffer to upper stack
Parameters · [in] eth_handle: handle of Ethernet driver · [in] buffer: frame buffer that will get input to upper stack · [in] length: length of the frame buffer

esp_err_t (*on_lowlevel_init_done)(esp_eth_handle_t eth_handle) Callback function invoked when lowlevel initialization is finished.

Return · ESP_OK: process extra lowlevel initialization successfully · ESP_FAIL: error occurred when processing extra lowlevel initialization
Parameters · [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,

Read PHY register.

uint32_t *reg_value)

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

Espressif Systems

461

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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,

Write PHY register.

uint32_t reg_value)

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

Enumerations enum esp_eth_io_cmd_t
Command list for ioctl API.
Values:
ETH_CMD_G_MAC_ADDR Get MAC address
ETH_CMD_S_MAC_ADDR Set MAC address
ETH_CMD_G_PHY_ADDR Get PHY address
ETH_CMD_S_PHY_ADDR Set PHY address
ETH_CMD_G_AUTONEGO Get PHY Auto Negotiation
ETH_CMD_S_AUTONEGO Set PHY Auto Negotiation
ETH_CMD_G_SPEED Get Speed
ETH_CMD_S_SPEED Set Speed

Espressif Systems

462

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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
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: cannt 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,

Read PHY register.

uint32_t *reg_value)

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,

Write PHY register.

uint32_t reg_value)

Return · ESP_OK: write PHY register successfully · ESP_FAIL: write PHY register failed because some error occurred
Parameters · [in] eth: mediator of Ethernet driver

Espressif Systems

463

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· [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
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
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 eth_event_t Ethernet event declarations.
Values:
ETHERNET_EVENT_START Ethernet driver start
ETHERNET_EVENT_STOP Ethernet driver stop

Espressif Systems

464

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

465

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

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 ofolengthpshould set by user, equals the size of buffer.
After the function returned, the value of olengthpmeans 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 olengthpindicates 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

Read PHY register.

*reg_value)

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

Espressif Systems

466

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Write PHY register.

reg_value)

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

Espressif Systems

467

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· [in] duplex: MAC duplex
esp_err_t (*set_link)(esp_eth_mac_t *mac, eth_link_t link) Set link status of MAC.
Return · ESP_OK: set link status successfully · ESP_ERR_INVALID_ARG: set link status failed because of invalid argument · ESP_FAIL: set link status failed because some other error occurred
Parameters · [in] 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

Espressif Systems

468

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
uint32_t rx_task_prio Priority of the receive task
int smi_mdc_gpio_num SMI MDC GPIO number, set to -1 could bypass the SMI GPIO configuration
int smi_mdio_gpio_num SMI MDIO GPIO number, set to -1 could bypass the SMI GPIO configuration
uint32_t flags Flags that specify extra capability for mac driver
eth_data_interface_t interface EMAC Data interface to PHY (MII/RMII)
eth_mac_clock_config_t clock_config EMAC Interface clock configuration
Macros ETH_MAC_FLAG_WORK_WITH_CACHE_DISABLE
MAC driver can work when cache is disabled ETH_MAC_FLAG_PIN_TO_CORE
Pin MAC task to the CPU core where driver installation happened
ETH_MAC_DEFAULT_CONFIG() Default configuration for Ethernet MAC object.
Type Definitions typedef struct esp_eth_mac_s esp_eth_mac_t
Ethernet MAC.
Enumerations enum emac_rmii_clock_mode_t
RMII Clock Mode Options.
Values:
EMAC_CLK_DEFAULT Default values configured using Kconfig are going to be used when oDefaultpselected.
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.

Espressif Systems

469

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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 doesnnt have directly relationship with EMAC peripheral. Sometimes this clock wonnt 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, donnt select GPIO0 output mode for stability.
EMAC_CLK_OUT_GPIO = 16 Output RMII Clock from internal APLL Clock available at GPIO16.
EMAC_CLK_OUT_180_GPIO = 17 Inverted Output RMII Clock from internal APLL Clock available at GPIO17.
Header File
· components/esp_eth/include/esp_eth_phy.h
Functions esp_eth_phy_t *esp_eth_phy_new_ip101(const eth_phy_config_t *config)
Create a PHY instance of IP101.
Return · instance: create PHY instance successfully · NULL: create PHY instance failed because some error occurred
Parameters · [in] config: configuration of PHY
esp_eth_phy_t *esp_eth_phy_new_rtl8201(const eth_phy_config_t *config) Create a PHY instance of RTL8201.
Return · 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
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_ksz80xx(const eth_phy_config_t *config) Create a PHY instance of KSZ80xx.
The phy model from the KSZ80xx series is detected automatically. If the driver is unable to detect a supported model, NULL is returned.
Currently, the following models are supported: KSZ8001, KSZ8021, KSZ8031, KSZ8041, KSZ8051, KSZ8061, KSZ8081, KSZ8091
Return

Espressif Systems

470

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· 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 PHYns 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
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 *autonego_en_stat)
Configure auto negotiation.

Espressif Systems

471

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

472

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· 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)
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.

Espressif Systems

473

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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
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. Itns 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.

Espressif Systems

474

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

API Reference For manipulating the Thread network, the OpenThread api shall be used. The OpenThread api docs can be found at the OpenThread official website.
ESP-IDF provides extra apis for launching and managing the OpenThread stack, binding to network interfaces and border routing features.
Header File
· components/openthread/include/esp_openthread.h
Functions esp_err_t esp_openthread_init(const esp_openthread_platform_config_t *init_config)
Initializes the full OpenThread stack.
Note The OpenThread instance will also be initialized in this function. Return
· ESP_OK on success · ESP_ERR_NO_MEM if allocation has failed · ESP_ERR_INVALID_ARG if radio or host connection mode not supported · ESP_ERR_INVALID_STATE if already initialized Parameters · [in] init_config: The initialization configuration. esp_err_t esp_openthread_launch_mainloop(void) Launches the OpenThread main loop.
Note Thie function will not return unless error happens when running the OpenThread stack. Return
· ESP_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

Espressif Systems

475

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
fd_set error_fds The error file descriptors
int max_fd The max file descriptor
struct timeval timeout The timeout
struct esp_openthread_uart_config_t The uart port config for OpenThread.
Public Members
uart_port_t port UART port number
uart_config_t uart_config UART configuration, see uart_config_t docs
int rx_pin UART RX pin
int tx_pin UART TX pin
struct esp_openthread_radio_config_t The OpenThread radio configuration.
Public Members
esp_openthread_radio_mode_t radio_mode The radio mode
esp_openthread_uart_config_t radio_uart_config The uart configuration to RCP
struct esp_openthread_host_connection_config_t The OpenThread host connection configuration.
Public Members
esp_openthread_host_connection_mode_t host_connection_mode The host connection mode
esp_openthread_uart_config_t host_uart_config The uart configuration to host
struct esp_openthread_port_config_t The OpenThread port specific configuration.
Public Members
const char *storage_partition_name The partition for storing OpenThread dataset
uint8_t netif_queue_size The packet queue size for the network interface
uint8_t task_queue_size The task queue size

Espressif Systems

476

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
struct esp_openthread_platform_config_t The OpenThread platform configuration.
Public Members
esp_openthread_radio_config_t radio_config The radio configuration
esp_openthread_host_connection_config_t host_config The host connection configuration
esp_openthread_port_config_t port_config The port configuration
Enumerations enum esp_openthread_event_t
OpenThread event declarations.
Values:
OPENTHREAD_EVENT_START OpenThread stack start
OPENTHREAD_EVENT_STOP OpenThread stack stop
OPENTHREAD_EVENT_IF_UP OpenThread network interface up
OPENTHREAD_EVENT_IF_DOWN OpenThread network interface down
OPENTHREAD_EVENT_GOT_IP6 OpenThread stack added IPv6 address
OPENTHREAD_EVENT_LOST_IP6 OpenThread stack removed IPv6 address
OPENTHREAD_EVENT_MULTICAST_GROUP_JOIN OpenThread stack joined IPv6 multicast group
OPENTHREAD_EVENT_MULTICAST_GROUP_LEAVE OpenThread stack left IPv6 multicast group
OPENTHREAD_EVENT_TREL_ADD_IP6 OpenThread stack added TREL IPv6 address
OPENTHREAD_EVENT_TREL_REMOVE_IP6 OpenThread stack removed TREL IPv6 address
OPENTHREAD_EVENT_TREL_MULTICAST_GROUP_JOIN OpenThread stack joined TREL IPv6 multicast group
enum esp_openthread_radio_mode_t The radio mode of OpenThread.
Values:
RADIO_MODE_NATIVE = 0x0 Use the native 15.4 radio
RADIO_MODE_UART_RCP = 0x1 UART connection to a 15.4 capable radio co-processor (RCP)
RADIO_MODE_SPI_RCP = 0x2 SPI connection to a 15.4 capable radio co-processor (RCP)

Espressif Systems

477

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

478

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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 · 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 ESP-NETIF
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.

Espressif Systems

479

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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)

|

| | +-----------------------+

--------+

+===========================+

||

communication

||

NETWORK STACK

DRIVER

ESP-NETIF

||

||

+-----------------------+

||

|

|

||

|

l2tap_write |-------| |

|

|

|

|

l2tap_eth_filter |----------|

|

|

|

(E)

|

+-----------------------+

ESP-NETIF L2 TAP

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)

Espressif Systems

480

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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 ESPNETIF object (runtime) and configuring a network stack (compile time). In addition to that a set of API is provided to control network interface lifecycle and its TCP/IP properties. As an overview, the ESP-NETIF public interface could be divided into these 6 groups:
1) Initialization APIs (to create and configure ESP-NETIF instance) 2) Input/Output API (for passing data between IO driver and network stack) 3) Event or Action API
· Used for network interface lifecycle management · ESP-NETIF provides building blocks for designing event handlers
4) Setters and Getters for basic network interface properties 5) Network stack abstraction: enabling user interaction with TCP/IP stack
· Set interface up or down · DHCP server and client API · DNS API
6) Driver conversion utilities
D) Network stack Network stack has no public interaction with application code with regard to public interfaces and shall be fully abstracted by ESP-NETIF API.
E) ESP-NETIF L2 TAP Interface The ESP-NETIF L2 TAP interface is ESP-IDF mechanism utilized to access Data Link Layer (L2 per OSI/ISO) for frame reception and transmission from user application. Its typical usage in embedded world might be implementation of non-IP related protocols such as PTP, Wake on LAN and others. Note that only Ethernet (IEEE 802.3) is currently supported.
From user perspective, the ESP-NETIF L2 TAP interface is accessed using file descriptors of VFS which provides a file-like interfacing (using functions like open(), read(), write(), etc). Refer to Virtual filesystem component to learn more.
There is only one ESP-NETIF L2 TAP interface device (path name) available. However multiple file descriptors with different configuration can be opened at a time since the ESP-NETIF L2 TAP interface can be understood as generic entry point to the NETIF internal structure. Important is then specific configuration of particular file descriptor. It

Espressif Systems

481

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
can be configured to give an access to specific Network Interface identified by if_key (e.g. ETH_DEF) and to filter only specific frames based on their type (e.g. Ethernet type in case of IEEE 802.3). Filtering only specific frames is crucial since the ESP-NETIF L2 TAP needs to work along with IP stack and so the IP related traffic (IP, ARP, etc.) should not be passed directly to the user application. Even though such option is still configurable, it is not recommended in standard use cases. Filtering is also advantageous from a perspective the userns application gets access only to frame types it is interested in and the remaining traffic is either passed to other L2 TAP file descriptors or to IP stack.
ESP-NETIF L2 TAP Interface Usage Manual
Initialization To be able to use the ESP-NETIF L2 TAP interface, it needs to be enabled in Kconfig by CONFIG_ESP_NETIF_L2_TAP first and then registered by esp_vfs_l2tap_intf_register() prior usage of any VFS function.
open() Once the ESP-NETIF L2 TAP is registered, it can be opened at path name o/dev/net/tapp. The same path path name can be opened multiple times up to CONFIG_ESP_NETIF_L2_TAP_MAX_FDS and multiple file descriptors with with different configuration may access the Data Link Layer in the NETIF.
The ESP-NETIF L2 TAP can be opened with O_NONBLOCK file status flag to the read() does not block. Note that the write() may block in current implementation when accessing a Network interface since it is a shared resource among multiple ESP-NETIF L2 TAP file descriptors and IP stack, and there is currently no queuing mechanism deployed. The file status flag can be retrieved and modified using fcntl().
On success, open() returns the new file descriptor (a nonnegative integer). On error, -1 is returned and errno is set to indicate the error.
ioctl() The newly opened ESP-NETIF L2 TAP file descriptor needs to be configured prior its usage since it is not bounded to any specific Network Interface and no frame type filter is configured. The following configuration options are available to do so:
· L2TAP_S_INTF_DEVICE - bounds the file descriptor to specific Network Interface which is identified by its if_key. Network Interface if_key is passed to ioctl() as the third parameter. Note that default Network Interfaces if_keyns used in ESP-IDF can be found in esp_netif/include/esp_netif_defaults.h.
· L2TAP_S_RCV_FILTER - sets the filter to frames with this type to be passed to the file descriptor. In case of Ethernet frames, the frames are to be filtered based on Length/Ethernet type field. In case the filter value is set less than or equal to 0x05DC, the Ethernet type field is considered to represent IEEE802.3 Length Field and all frames with values in interval <0, 0x05DC> at that field are to be passed to the file descriptor. The IEEE802.2 logical link control (LLC) resolution is then expected to be performed by userns application. In case the filter value is set greater than 0x05DC, the Ethernet type field is considered to represent protocol identification and only frames which are equal to the set value are to be passed to the file descriptor.
All set configuration options have getter counterpart option to read the current settings.
Note: VLAN tagged frames are currently not recognized. If user needs to process VLAN tagged frames, they need set filter to be equal to VLAN tag (i.e. 0x8100 or 0x88A8) and process the VLAN tagged frames in user application.

On success, ioctl() returns 0. On error, -1 is returned, and errno is set to indicate the error. EBADF - not a valid file descriptor. EINVAL - invalid configuration argument. Ethernet type filter is already used by other file descriptor. ENODEV - no such Network Interface which is tried to be assigned to the file descriptor exists. ENOSPC - NETIF L2 receive hook is already taken by other function when trying to assign Network Interface to the file descriptor. ENOSYS - unsupported operation, passed configuration option does not exists.

Espressif Systems

482

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

read() Opened and configured ESP-NETIF L2 TAP file descriptor can be accessed by read() to get inbound frames. The read operation can be either blocking or non-blocking based on actual state of O_NONBLOCK file status flag. When the file status flag is set blocking, the read operation waits until a frame is received and context is switched to other task. When the file status flag is set non-blocking, the read operation returns immediately. In such case, either a frame is returned if it was already queued or the function indicates the queue is empty. The number of queued frames associated with one file descriptor is limited by CONFIG_ESP_NETIF_L2_TAP_RX_QUEUE_SIZE Kconfig option. Once the number of queued frames reach configured threshold, the newly arriving frames are dropped until the queue has enough room to accept incoming traffic (Tail Drop queue management).

On success, read() returns the number of bytes read. Zero is returned when size of the destination buffer is 0. On error, -1 is returned, and errno is set to indicate the error. EBADF - not a valid file descriptor. EAGAIN - the file descriptor has been marked non-blocking (O_NONBLOCK), and the read would block.

write() A raw Data Link Layer frame can be sent to Network Interface via opened and configured ESP-NETIF L2 TAP file descriptor. Userns application is responsible to construct the whole frame except for fields which are added automatically by the physical interface device. The following fields need to be constructed by the userns application in case of Ethernet link: source/destination MAC addresses, Ethernet type, actual protocol header and user data. See below for more information about Ethernet frame structure.

+-------------------+-------------------+-------------+----------------------------

---

--+

| Destination MAC |

Source MAC | Type/Length | Payload (protocol header/

data) ... |

+-------------------+-------------------+-------------+----------------------------

---

--+

6B

6B

2B

0-1486B

In other words, there is no additional frame processing performed by the ESP-NETIF L2 TAP interface. It only checks the Ethernet type of the frame is the same as the filter configured in the file descriptor. If the Ethernet type is different, an error is returned and the frame is not sent. Note that the write() may block in current implementation when accessing a Network interface since it is a shared resource among multiple ESP-NETIF L2 TAP file descriptors and IP stack, and there is currently no queuing mechanism deployed.

On success, write() returns the number of bytes written. Zero is returned when size of the input buffer is 0. On error, -1 is returned, and errno is set to indicate the error. EBADF - not a valid file descriptor. EBADMSG - Ethernet type of the frame is different then file descriptor configured filter. EIO - Network interface not available or busy.

close() Opened ESP-NETIF L2 TAP file descriptor can be closed by the close() to free its allocated resources. The ESP-NETIF L2 TAP implementation of close() may block. On the other hand, it is thread safe and can be called from different task than the file descriptor is actually used. If such situation occurs and one task is blocked in I/O operation and another task tries to close the file descriptor, the first task is unblocked. The firstns task read operation then ends with error.

On success, close() returns zero. On error, -1 is returned, and errno is set to indicate the error. EBADF - not a valid file descriptor.

select() Select is used in a standard way, just CONFIG_VFS_SUPPORT_SELECT needs to be enabled to be the select() function available.

Espressif Systems

483

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP-NETIF programmerns manual Please refer to the example section for basic initialization of default 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
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
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

Espressif Systems

484

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t esp_netif_set_driver_config(esp_netif_t

*esp_netif,

esp_netif_driver_ifconfig_t *driver_config)

Configures driver related options of esp_netif object.

const

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

esp_err_t esp_netif_transmit_hook_attach(esp_netif_t *esp_netif, void *hook_fn) Add transmit hook callback function reference into ESP-NETIF. This callback function is then called just prior the ESP-NETIF passes data to network driver.

Return · ESP_OK - success · ESP_ERR_INVALID_ARG
Parameters · [in] esp_netif: Handle to esp-netif instance · [in] hook_fn: reference to transmit hook call-back function

esp_err_t esp_netif_post_transmit_hook_attach(esp_netif_t *esp_netif, void *hook_fn) Add post transmit hook callback function reference into ESP-NETIF. This callback function is then called just after the ESP-NETIF passes data to network driver.

Note Intention of this function is either to release resources allocated by transmit hook function or for other use cases such as time stamping, etc.
Return · ESP_OK - success · ESP_ERR_INVALID_ARG
Parameters · [in] esp_netif: Handle to esp-netif instance · [in] hook_fn: reference to post transmit hook call-back function

Espressif Systems

485

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t esp_netif_recv_hook_attach(esp_netif_t *esp_netif, void *hook_fn) Add receive hook callback function reference into ESP-NETIF. This callback function is then called when network driver receives data.
Return · ESP_OK - success · ESP_ERR_INVALID_ARG
Parameters · [in] esp_netif: Handle to esp-netif instance · [in] hook_fn: reference to receive hook callback function
esp_err_t esp_netif_transmit_hook_detach(esp_netif_t *esp_netif) Removes reference to previously attachhed transmit hook callback function.
Return · ESP_OK - success · ESP_ERR_INVALID_ARG
Parameters · [in] esp_netif: Handle to esp-netif instance
esp_err_t esp_netif_post_transmit_hook_detach(esp_netif_t *esp_netif) Removes reference to previously attachhed posttransmit hook callback function.
Return · ESP_OK - success · ESP_ERR_INVALID_ARG
Parameters · [in] esp_netif: Handle to esp-netif instance
esp_err_t esp_netif_recv_hook_detach(esp_netif_t *esp_netif) Removes reference to previously attachhed receive hook callback function.
Return · ESP_OK - success · ESP_ERR_INVALID_ARG
Parameters · [in] esp_netif: Handle to esp-netif instance
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:
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

Espressif Systems

486

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· [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:
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

Espressif Systems

487

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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 · 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

Espressif Systems

488

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t esp_netif_get_ip_info(esp_netif_t *esp_netif, esp_netif_ip_info_t *ip_info) Get interfacens 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 interfacens old IP information.

Returns an ooldpIP 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 interfacens 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

esp_err_t esp_netif_set_old_ip_info(esp_netif_t *esp_netif,

Set interface old IP information.

*ip_info)

const esp_netif_ip_info_t

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 oIP lost timerpwill expire (after the configured interval) and set the old IP information to zero.

Return · ESP_OK · ESP_ERR_ESP_NETIF_INVALID_PARAMS

Espressif Systems

489

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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 · 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)

Espressif Systems

490

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Note The default event handlers for the SYSTEM_EVENT_STA_CONNECTED and SYSTEM_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

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,

Set DNS Server information.

esp_netif_dns_info_t *dns)

Espressif Systems

491

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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_BACKUP, ESP_NETIF_DNS_FALLBACK

· [in] dns: DNS Server address to set

ESP_NETIF_DNS_MAIN,

esp_err_t esp_netif_get_dns_info(esp_netif_t *esp_netif, esp_netif_dns_type_t type,

Get DNS Server information.

esp_netif_dns_info_t *dns)

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 interfacens 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_BACKUP, ESP_NETIF_DNS_FALLBACK

· [out] dns: DNS Server result is written here on success

ESP_NETIF_DNS_MAIN,

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

Espressif Systems

492

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· [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. o127.0.0.1p)
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. o127.0.0.1p) · [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: o2001:db8:85a3:0:0:0:2:1por o2001:db8::2:1p)
Return

Espressif Systems

493

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

op

2001:0db8:85a3:0000:0000:0000:0002:0001p)

· [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 instancens route-prio, or -1 if invalid paramters Parameters
· [in] esp_netif: Handle to esp-netif instance

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

Espressif Systems

494

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

495

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· 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_l() 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_config)
Creates esp_netif WiFi object based on the custom configuration.

esp_netif_inherent_config_t

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)

2.2.5 IP Network Layer
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 uninitialization is available.
Also replace #include "tcpip_adapter.h" with #include "esp_netif.h".

Espressif Systems

496

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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 connection to the TCP/IP stack. For example initialization code for WiFi has to explicitly call esp_netif_create_default_wifi_sta(); or esp_netif_create_default_wifi_ap(); after the TCP/IP stack and the event loop have been initialized. Please consult an example initialization code for these three interfaces:
· WiFi Station: wifi/getting_started/station/main/station_example_main.c · WiFi Access Point: wifi/getting_started/softAP/main/softap_example_main.c · Ethernet: ethernet/basic/main/ethernet_example_main.c
Replacing other tcpip_adapter API All the tcpip_adapter functions have their esp-netif counter-part. Please refer to the esp_netif.h grouped into these sections:
· Setters/Getters · DHCP · DNS · IP address
Default event handlers Event handlers are moved from tcpip_adapter to appropriate driver code. There is no change from application code perspective, all events shall be handled in the same way. Please note that within IP related event handlers, application code usually receives IP addresses in a form of esp-netif specific struct (not the LwIP structs, but binary compatible). This is the preferred way of printing the address:
ESP_LOGI(TAG, "got ip:" IPSTR "\n", IP2STR(&event->ip_info.ip));
Instead of
ESP_LOGI(TAG, "got ip:%s\n", ip4addr_ntoa(&event->ip_info.ip));
Since ip4addr_ntoa() is a LwIP API, the esp-netif provides esp_ip4addr_ntoa() as a replacement, but the above method is generally preferred.
IP addresses It is preferred to use esp-netif defined IP structures. Please note that the LwIP structs will still work when default compatibility enabled. * esp-netif IP address definitions
Next steps Additional step in porting an application to fully benefit from the ESP-NETIF is to disable the tcpip_adapter compatibility layer in the component configuration: ESP NETIF Adapter -> Enable backward 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 driverns lifecycle transitions.

Espressif Systems

497

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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 driverns 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 driverns 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;

esp-netif driver */

driver_impl

*h;

implementation */

} my_netif_driver_t;

/*!< base structure reserved as /*!< handle of driver

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 driverns code gets executed to mutually register callbacks between esp-netif and I/O driver instances. Typically the driver is started as well in the post-attach callback. An example of a simple post-attach callback is outlined below:
static esp_err_t my_post_attach_start(esp_netif_t * esp_netif, void * args) {
my_netif_driver_t *driver = args; const esp_netif_driver_ifconfig_t driver_ifconfig = {
.driver_free_rx_buffer = my_free_rx_buf, .transmit = my_transmit, .handle = driver->driver_impl }; driver->base.netif = esp_netif; ESP_ERROR_CHECK(esp_netif_set_driver_config(esp_netif, &driver_ifconfig)); my_driver_start(driver->driver_impl); return ESP_OK; }

Default handlers I/O drivers also typically provide default definitions of lifecycle behaviour of related network interfaces based on state transitions of I/O drivers. For example driver start -> network start, etc. An example of such a default handler is provided below:

Espressif Systems

498

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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

Espressif Systems

499

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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.6 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-S3 integrates 2 SAR (Successive Approximation Register) ADCs, supporting a total of 20 measurement channels (analog enabled pins). These channels are supported: ADC1:
· 10 channels: GPIO1 - GPIO10 ADC2:
· 10 channels: GPIO11 - GPIO20

ADC Attenuation

Vref is the reference voltage used internally by ESP32-S3 ADCs for measuring the input voltage. The ESP32-S3 ADCs can measure analog voltages from 0 V to Vref. Among different chips, the Vref varies, the median is 1.1 V. In order to convert voltages larger than Vref, input voltages can be attenuated before being input to the ADCs. There are 4 available attenuation options, the higher the attenuation is, the higher the measurable input voltage could be.

Attenuation ADC_ATTEN_DB_0 ADC_ATTEN_DB_2_5 ADC_ATTEN_DB_6 ADC_ATTEN_DB_11

Measurable input voltage range 0 mV ~ 950 mV 0 mV ~ 1250 mV 0 mV ~ 1750 mV 0 mV ~ 3100 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-S3 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:

Espressif Systems

500

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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, 8191
under Continuous Read mode.

For boards with eFuse ADC calibration bits, esp_adc_cal_raw_to_voltage() can be used to get the calibrated 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:
· Since the ADC2 module is also used by the Wi-Fi, reading operation of adc2_get_raw() may fail between esp_wifi_start() and esp_wifi_stop(). Use the return code to see whether the reading is successful.

Driver Usage Both of the ADC units support single read mode, which is suitable for low-frequency sampling operations. Note: ADC readings from a pin not connected to any signal are random.

ADC Single Read mode The ADC should be configured before reading is taken.
· For ADC1, configure desired precision and attenuation by calling functions adc1_config_width() and adc1_config_channel_atten().
· For ADC2, configure the attenuation by adc2_config_channel_atten(). The reading width of ADC2 is configured every time you take the reading.
Attenuation configuration is done per channel, see adc1_channel_t and adc2_channel_t, set as a parameter of above functions.
Then it is possible to read ADC conversion result with adc1_get_raw() and adc2_get_raw(). Reading width of ADC2 should be set as a parameter of adc2_get_raw() instead of in the configuration functions.
Single Read mode ADC example can be found in peripherals/adc/single_read directory of ESP-IDF examples.
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.
Note: See ADC Limitations for the limitation of using ADC single read mode.

Espressif Systems

501

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Minimizing Noise
The ESP32-S3 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.
ADC Calibration
ESP32-S3 ADC Calibration contains 2 steps: Hardware Calibration and Software Calibration.
Hardware Calibration Based on series of comparisons with the reference voltage, ESP32-S3 ADC determines each bit of the output digital result. Per design the ESP32-S3 ADC reference voltage is 1100 mV, however the true reference voltage can range from 1000 mV to 1200 mV among different chips. To minimize this difference, hardware calibration is introduced. Hardware calibration contains 2 steps:
1. Set an auto-calibration parameter of bandgap voltage reference. In this way, the difference mentioned above can be minimized.
2. Correct the offset of the ADC Vin-Dout characteristics. ADC characteristics is generally a function: f(x) = A * x + B, where B is the offset.
An uncalibrated ADC characteristics is as follows:

The offset in the uncalibrated characteristics is significant. Step 2 is to correct the offset to 0.
After hardware calibration, the ADC characteristics would be like:
Hardware calibration is done internally by the ADC driver. The consequent results are raw data. A transformation is needed to get the final result, see ADC Conversion.

Software Calibration To convert ADC raw data to calibrated digital data, following steps should be followed: 1. Check the eFuse to know if the software calibration is supported via esp_adc_cal_check_efuse().

Espressif Systems

502

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

2. Calculate the ADC calibration characteristics via esp_adc_cal_characterize(). The ADC software calibration characteristics are per ADC module and per attenuation. For example, characteristics of ADC1 channel 0 under 11 dB attenuation are the same as characteristics of ADC1 channel 2 under 11 dB attenuation. But characteristics of ADC1 channel 0 under 11 dB attenuation are different with characteristics of ADC2 channel 0 under 11 dB attenuation. Also characteristics of ADC1 channel 0 under 11 dB attenuation are different with characteristics of ADC1 channel 0 under 6 dB attenuation.
3. Get the actual voltage value via esp_adc_cal_raw_to_voltage(). After software calibration, the ADC characteristics would be like:
The results provided by the ADC calibration APIs indicate the actual voltage values. ADC software calibration example can be found in peripherals/adc/single_read directory of ESP-IDF examples.
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

Espressif Systems

503

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Header File
· components/driver/include/driver/adc.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 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.

Espressif Systems

504

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Due to ADC characteristics, most accurate results are obtained within the osuggested rangepshown 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 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
mECO_and_Workarounds_for_Bugs_in_ESP32nfor 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 remove 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

Espressif Systems

505

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· -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.
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 osuggested rangepshown in the following table.

+----------+-------------+-----------------+

|

| attenuation | suggested range |

| SoC |

(dB) |

(mV)

|

+==========+=============+=================+

(continues on next page)

Espressif Systems

506

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

|

|

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 |

+----------+-------------+-----------------+

(continued from previous page)

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
mECO_and_Workarounds_for_Bugs_in_ESP32nfor 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 remove the glitches on GPIO36 and GPIO39.
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 ADC2ns reference voltage to adc2_channe_tns IO.
This function routes the internal reference voltage of ADCn to one of ADC2ns channels. This reference voltage can then be manually measured for calibration purposes.

Espressif Systems

507

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Note ESP32 only supports output of ADC2ns 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 ADC2ns channels IO are supported)

esp_err_t adc2_vref_to_gpio(gpio_num_t gpio) Output ADC2 reference voltage to adc2_channe_tns IO.

This function routes the internal reference voltage of ADCn to one of ADC2ns 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 (ADC2ns channels are supported)

esp_err_t adc_digi_initialize(const adc_digi_init_config_t *init_config) Initialize the Digital ADC.

Return · ESP_ERR_INVALID_ARG If the combination of arguments is invalid. · ESP_ERR_NOT_FOUND No free interrupt found with the specified flags · ESP_ERR_NO_MEM If out of memory · ESP_OK On success
Parameters · init_config: Pointer to Digital ADC initilization config. adc_digi_init_config_t.

Refer to

esp_err_t adc_digi_read_bytes(uint8_t *buf, uint32_t length_max, uint32_t *out_length, uint32_t timeout_ms)
Read bytes from Digital ADC through DMA.

Return · ESP_ERR_INVALID_STATE Driver state is invalid. Usually it means the ADC sampling rate is faster than the task processing rate. · ESP_ERR_TIMEOUT Operation timed out · ESP_OK On success
Parameters · [out] buf: Buffer to read from ADC. · [in] length_max: Expected length of data read from the ADC. · [out] out_length: Real length of data read from the ADC via this API. · [in] timeout_ms: Time to wait for data via this API, in millisecond.

esp_err_t adc_digi_start(void) Start the Digital ADC and DMA peripherals. After this, the hardware starts working.

Return · ESP_ERR_INVALID_STATE Driver state is invalid. · ESP_OK On success

esp_err_t adc_digi_stop(void) Stop the Digital ADC and DMA peripherals. After this, the hardware stops working.

Return · ESP_ERR_INVALID_STATE Driver state is invalid. · ESP_OK On success

esp_err_t adc_digi_deinitialize(void) Deinitialize the Digital ADC.

Return

Espressif Systems

508

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· ESP_ERR_INVALID_STATE Driver state is invalid. · ESP_OK On success
esp_err_t adc_digi_controller_configure(const adc_digi_configuration_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.
Structures struct adc_digi_init_config_s
ADC DMA driver configuration.
Public Members
uint32_t max_store_buf_size Max length of the converted data that driver can store before they are processed.
uint32_t conv_num_each_intr Bytes of data that can be converted in 1 interrupt.
uint32_t adc1_chan_mask Channel list of ADC1 to be initialized.
uint32_t adc2_chan_mask Channel list of ADC2 to be initialized.
struct adc_digi_configuration_t ADC digital controller settings.
Public Members
bool conv_limit_en To limit ADC conversion times. Conversion stops after finishing conv_limit_num times conversion.
uint32_t conv_limit_num Set the upper limit of the number of ADC conversion triggers. Range: 1 ~ 255.
uint32_t pattern_num Number of ADC channels that will be used.
adc_digi_pattern_config_t *adc_pattern List of configs for each ADC channel that will be used.
uint32_t sample_freq_hz The expected ADC sampling frequency in Hz. Range: 611Hz ~ 83333Hz Fs = Fd / interval / 2 Fs: sampling frequency; Fd: digital controller frequency, no larger than 5M for better performance interval: interval between 2 measurement trigger signal, the smallest interval should not be smaller than the ADC measurement period, the largest interval should not be larger than 4095
adc_digi_convert_mode_t conv_mode ADC DMA conversion mode, see adc_digi_convert_mode_t.
adc_digi_output_format_t format ADC DMA conversion output format, see adc_digi_output_format_t.

Espressif Systems

509

Release v5.0-dev-1424-g2467aa7f6c

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
ADC_MAX_DELAY Digital ADC DMA read max timeout value, it may make the adc_digi_read_bytes block forever if the OS supports.
Type Definitions typedef struct adc_digi_init_config_s adc_digi_init_config_t
ADC DMA driver configuration.
Enumerations enum adc1_channel_t
Values:
ADC1_CHANNEL_0 = 0 ADC1 channel 0 is GPIO1
ADC1_CHANNEL_1 ADC1 channel 1 is GPIO2
ADC1_CHANNEL_2 ADC1 channel 2 is GPIO3
ADC1_CHANNEL_3 ADC1 channel 3 is GPIO4
ADC1_CHANNEL_4 ADC1 channel 4 is GPIO5
ADC1_CHANNEL_5 ADC1 channel 5 is GPIO6
ADC1_CHANNEL_6 ADC1 channel 6 is GPIO7
ADC1_CHANNEL_7 ADC1 channel 7 is GPIO8
ADC1_CHANNEL_8 ADC1 channel 8 is GPIO9
ADC1_CHANNEL_9 ADC1 channel 9 is GPIO10
ADC1_CHANNEL_MAX

Espressif Systems

510

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
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) 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
Header File · components/hal/include/hal/adc_types.h
Structures struct adc_digi_pattern_config_t
ADC digital controller pattern configuration.
Public Members
uint8_t atten Attenuation of this ADC channel.
uint8_t channel ADC channel.

Espressif Systems

511

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
uint8_t unit ADC unit.
uint8_t bit_width ADC output bit width.
struct adc_digi_output_data_t ADC digital controller (DMA mode) output data format. Used to analyze the acquired ADC (DMA) data.
Public Members
uint32_t data : 13 ADC real output data info. Resolution: 13 bit.
uint32_t channel : 4 ADC channel index info. If (channel < ADC_CHANNEL_MAX), The data is valid. If (channel > ADC_CHANNEL_MAX), The data is invalid.
uint32_t unit : 1 ADC unit index info. 0: ADC1; 1: ADC2.
uint32_t reserved17_31 : 14 Reserved17.
struct adc_digi_output_data_t::[anonymous]::[anonymous] type2 When the configured output format is 12bit. ADC_DIGI_FORMAT_11BIT
uint32_t val Raw data value
struct adc_arbiter_t ADC arbiter work mode and priority setting. Note ESP32-S2: Only ADC2 support arbiter.
Public Members
adc_arbiter_mode_t mode Refer to adc_arbiter_mode_t. Note: only support ADC2.
uint8_t rtc_pri RTC controller priority. Range: 0 ~ 2.
uint8_t dig_pri Digital controller priority. Range: 0 ~ 2.
uint8_t pwdet_pri Wi-Fi controller priority. Range: 0 ~ 2.
struct adc_digi_filter_t ADC digital controller (DMA mode) filter configuration. Note For ESP32-S2, The filter object of the ADC is fixed. Note For ESP32-S2, The filter object is always all enabled channels.
Public Members
adc_unit_t adc_unit Set adc unit number for filter. For ESP32-S2, Filter IDX0/IDX1 can only be used to filter all enabled channels of ADC1/ADC2 unit at the same time.
adc_channel_t channel Set adc channel number for filter. For ESP32-S2, itns always ADC_CHANNEL_MAX

Espressif Systems

512

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

adc_digi_filter_mode_t mode Set adc filter mode for filter. See adc_digi_filter_mode_t.
struct adc_digi_monitor_t ADC digital controller (DMA mode) monitor configuration.
Note For ESP32-S2, The monitor object of the ADC is fixed. Note For ESP32-S2, The monitor object is always all enabled channels.
Public Members
adc_unit_t adc_unit Set adc unit number for monitor. For ESP32-S2, monitor IDX0/IDX1 can only be used to monitor all enabled channels of ADC1/ADC2 unit at the same time.
adc_channel_t channel Set adc channel number for monitor. For ESP32-S2, itns always ADC_CHANNEL_MAX
adc_digi_monitor_mode_t mode Set adc monitor mode. See adc_digi_monitor_mode_t.
uint32_t threshold Set monitor threshold of adc digital controller.
Macros ADC_ARBITER_CONFIG_DEFAULT()
ADC arbiter default configuration.
Note ESP32S2: Only ADC2 supports (needs) an arbiter.
Enumerations enum adc_unit_t
ADC unit enumeration.
Note For ADC digital controller (DMA mode), ESP32 doesnnt 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, donnt use ADC_CHANNEL_8, ADC_CHANNEL_9. See adc1_channel_t.
Values:
ADC_CHANNEL_0 = 0 ADC channel
ADC_CHANNEL_1 ADC channel

Espressif Systems

513

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ADC_CHANNEL_2 ADC channel
ADC_CHANNEL_3 ADC channel
ADC_CHANNEL_4 ADC channel
ADC_CHANNEL_5 ADC channel
ADC_CHANNEL_6 ADC channel
ADC_CHANNEL_7 ADC channel
ADC_CHANNEL_8 ADC channel
ADC_CHANNEL_9 ADC channel
ADC_CHANNEL_MAX
enum adc_atten_t ADC attenuation parameter. Different parameters determine the range of the ADC. See adc1_config_channel_atten.
Values:
ADC_ATTEN_DB_0 = 0 No input attenumation, ADC can measure up to approx. 800 mV.
ADC_ATTEN_DB_2_5 = 1 The input voltage of ADC will be attenuated extending the range of measurement by about 2.5 dB (1.33 x)
ADC_ATTEN_DB_6 = 2 The input voltage of ADC will be attenuated extending the range of measurement by about 6 dB (2 x)
ADC_ATTEN_DB_11 = 3 The input voltage of ADC will be attenuated extending the range of measurement by about 11 dB (3.55 x)
ADC_ATTEN_MAX
enum adc_bits_width_t ADC resolution setting option.
Note Only used in single read mode
Values:
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.
Values:
ADC_CONV_SINGLE_UNIT_1 = 1 Only use ADC1 for conversion.
ADC_CONV_SINGLE_UNIT_2 = 2 Only use ADC2 for conversion.

Espressif Systems

514

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ADC_CONV_BOTH_UNIT = 3 Use Both ADC1 and ADC2 for conversion simultaneously.

ADC_CONV_ALTER_UNIT = 7 Use both ADC1 and ADC2 for conversion by turn. e.g. ADC1 -> ADC2 -> ADC1 -> ADC2 l..

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: (adc_digi_output_data_t). Note: For single convert mode.

0]-12 bits ADC data

ADC_DIGI_FORMAT_11BIT ADC to DMA data format, [15]-adc unit, [14:11]-channel, [10: (adc_digi_output_data_t). Note: For multi or alter convert mode.

0]-11 bits ADC data

ADC_DIGI_FORMAT_MAX

ADC_DIGI_OUTPUT_FORMAT_TYPE1 See adc_digi_output_data_t.type1

ADC_DIGI_OUTPUT_FORMAT_TYPE2 See adc_digi_output_data_t.type2

enum adc_arbiter_mode_t ADC arbiter work mode option.

Note ESP32-S2: Only ADC2 support arbiter.

Values:

ADC_ARB_MODE_SHIELD Force shield arbiter, Select the highest priority controller to work.

ADC_ARB_MODE_FIX Fixed priority switch controller mode.

ADC_ARB_MODE_LOOP Loop priority switch controller mode. Each controller has the same priority, and the arbiter will switch to the next controller after the measurement is completed.

enum adc_digi_filter_idx_t ADC digital controller (DMA mode) filter index options.

Note For ESP32-S2, The filter object of the ADC is fixed.

Values:

ADC_DIGI_FILTER_IDX0 = 0 The filter index 0. For ESP32-S2, It can only be used to filter all enabled channels of ADC1 unit at the same time.

ADC_DIGI_FILTER_IDX1 The filter index 1. For ESP32-S2, It can only be used to filter all enabled channels of ADC2 unit at the same time.

ADC_DIGI_FILTER_IDX_MAX

enum adc_digi_filter_mode_t ADC digital controller (DMA mode) filter type options. Expression: filter_data = (k-1)/k * last_data + new_data / k.

Values:

Espressif Systems

515

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ADC_DIGI_FILTER_IIR_2 = 0 The filter mode is first-order IIR filter. The coefficient is 2.
ADC_DIGI_FILTER_IIR_4 The filter mode is first-order IIR filter. The coefficient is 4.
ADC_DIGI_FILTER_IIR_8 The filter mode is first-order IIR filter. The coefficient is 8.
ADC_DIGI_FILTER_IIR_16 The filter mode is first-order IIR filter. The coefficient is 16.
ADC_DIGI_FILTER_IIR_64 The filter mode is first-order IIR filter. The coefficient is 64.
ADC_DIGI_FILTER_IIR_MAX enum adc_digi_monitor_idx_t
ADC digital controller (DMA mode) monitor index options. Note For ESP32-S2, The monitor object of the ADC is fixed. Values: ADC_DIGI_MONITOR_IDX0 = 0
The monitor index 0. For ESP32-S2, It can only be used to monitor all enabled channels of ADC1 unit at the same time. ADC_DIGI_MONITOR_IDX1 The monitor index 1. For ESP32-S2, It can only be used to monitor all enabled channels of ADC2 unit at the same time. ADC_DIGI_MONITOR_IDX_MAX enum adc_digi_monitor_mode_t Set monitor mode of adc digital controller. MONITOR_HIGH:If ADC_OUT > threshold, Generates monitor interrupt. MONITOR_LOW: If ADC_OUT < threshold, Generates monitor interrupt. Values: ADC_DIGI_MONITOR_HIGH = 0 If ADC_OUT > threshold, Generates monitor interrupt. ADC_DIGI_MONITOR_LOW If ADC_OUT < threshold, Generates monitor interrupt. ADC_DIGI_MONITOR_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
ADC Calibration
Header File · components/esp_adc_cal/include/esp_adc_cal.h

Espressif Systems

516

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

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 support 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 default_vref, esp_adc_cal_characteristics_t *chars)
Characterize an ADC at a particular attenuation.

This function will characterize the ADC at a particular attenuation and generate the ADC-Voltage curve in the form of [y = coeff_a * x + coeff_b]. Characterization can be based on Two Point values, eFuse Vref, or default Vref and the calibration values will be prioritized in that order.

Note For ESP32, Two Point values and eFuse Vref calibration can be enabled/disabled using menuconfig. For ESP32s2, only Two Point values calibration and only ADC_WIDTH_BIT_13 is supported. The parameter default_vref is unused.
Return · ESP_ADC_CAL_VAL_EFUSE_VREF: eFuse Vref used for characterization · ESP_ADC_CAL_VAL_EFUSE_TP: Two Point value used for characterization (only in Linear Mode) · ESP_ADC_CAL_VAL_DEFAULT_VREF: Default Vref used for characterization
Parameters · [in] adc_num: ADC to characterize (ADC_UNIT_1 or ADC_UNIT_2) · [in] atten: Attenuation to characterize · [in] bit_width: Bit width configuration of ADC · [in] default_vref: Default ADC reference voltage in mV (Only in ESP32, used if eFuse values is not available) · [out] chars: Pointer to empty structure used to store ADC characteristics

uint32_t esp_adc_cal_raw_to_voltage(uint32_t

adc_reading,

esp_adc_cal_characteristics_t *chars) Convert an ADC reading to voltage in mV.

const

This function converts an ADC reading to a voltage in mV based on the ADCns 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())

Espressif Systems

517

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return · ESP_OK: ADC read and converted to mV · ESP_ERR_INVALID_ARG: Error due to invalid arguments · ESP_ERR_INVALID_STATE: Reading result is invalid. Try to read again.
Parameters · [in] channel: ADC Channel to read · [in] chars: Pointer to initialized ADC characteristics structure · [out] voltage: Pointer to store converted voltage
Structures struct esp_adc_cal_characteristics_t
Structure storing characteristics of an ADC.
Note Call esp_adc_cal_characterize() to initialize the structure
Public Members
adc_unit_t adc_num ADC number
adc_atten_t atten ADC attenuation
adc_bits_width_t bit_width ADC bit width
uint32_t coeff_a Gradient of ADC-Voltage curve
uint32_t coeff_b Offset of ADC-Voltage curve
uint32_t vref Vref used by lookup table
const uint32_t *low_curve Pointer to low Vref curve of lookup table (NULL if unused)
const uint32_t *high_curve Pointer to high Vref curve of lookup table (NULL if unused)
uint8_t version ADC Calibration
Enumerations enum esp_adc_cal_value_t
Type of calibration value used in characterization.
Values:
ESP_ADC_CAL_VAL_EFUSE_VREF = 0 Characterization based on reference voltage stored in eFuse
ESP_ADC_CAL_VAL_EFUSE_TP = 1 Characterization based on Two Point values stored in eFuse
ESP_ADC_CAL_VAL_DEFAULT_VREF = 2 Characterization based on default reference voltage
ESP_ADC_CAL_VAL_EFUSE_TP_FIT = 3 Characterization based on Two Point values and fitting curve coefficients stored in eFuse
ESP_ADC_CAL_VAL_MAX

Espressif Systems

518

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_ADC_CAL_VAL_NOT_SUPPORTED = ESP_ADC_CAL_VAL_MAX
GPIO Lookup Macros
Header File · components/soc/esp32s3/include/soc/adc_channel.h
Macros ADC1_GPIO1_CHANNEL ADC1_CHANNEL_0_GPIO_NUM ADC1_GPIO2_CHANNEL ADC1_CHANNEL_1_GPIO_NUM ADC1_GPIO3_CHANNEL ADC1_CHANNEL_2_GPIO_NUM ADC1_GPIO4_CHANNEL ADC1_CHANNEL_3_GPIO_NUM ADC1_GPIO5_CHANNEL ADC1_CHANNEL_4_GPIO_NUM ADC1_GPIO6_CHANNEL ADC1_CHANNEL_5_GPIO_NUM ADC1_GPIO7_CHANNEL ADC1_CHANNEL_6_GPIO_NUM ADC1_GPIO8_CHANNEL ADC1_CHANNEL_7_GPIO_NUM ADC1_GPIO9_CHANNEL ADC1_CHANNEL_8_GPIO_NUM ADC1_GPIO10_CHANNEL ADC1_CHANNEL_9_GPIO_NUM ADC2_GPIO11_CHANNEL ADC2_CHANNEL_0_GPIO_NUM ADC2_GPIO12_CHANNEL ADC2_CHANNEL_1_GPIO_NUM ADC2_GPIO13_CHANNEL ADC2_CHANNEL_2_GPIO_NUM ADC2_GPIO14_CHANNEL ADC2_CHANNEL_3_GPIO_NUM ADC2_GPIO15_CHANNEL ADC2_CHANNEL_4_GPIO_NUM ADC2_GPIO16_CHANNEL ADC2_CHANNEL_5_GPIO_NUM

Espressif Systems

519

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ADC2_GPIO17_CHANNEL ADC2_CHANNEL_6_GPIO_NUM ADC2_GPIO18_CHANNEL ADC2_CHANNEL_7_GPIO_NUM ADC2_GPIO19_CHANNEL ADC2_CHANNEL_8_GPIO_NUM ADC2_GPIO20_CHANNEL ADC2_CHANNEL_9_GPIO_NUM

2.3.2 GPIO & RTC GPIO

Overview
The ESP32-S3 chip features 45 physical GPIO pads. Some GPIO pads cannot be used or do not have the corresponding pin on the chip package. For more details, see ESP32-S3 Technical Reference Manual > IO MUX and GPIO Matrix (GPIO, IO_MUX) [PDF]. Each pad can be used as a general purpose I/O or can be connected to an internal peripheral signal.
The table below provides more information on pin usage, and please note the comments in the table for GPIOs with restrictions.

GPIO GPIO0 GPIO1 GPIO2 GPIO3 GPIO4 GPIO5 GPIO6 GPIO7 GPIO8 GPIO9 GPIO10 GPIO11 GPIO12 GPIO13 GPIO14 GPIO15 GPIO16 GPIO17 GPIO18 GPIO19 GPIO20 GPIO21 GPIO26 GPIO27 GPIO28 GPIO29 GPIO30 GPIO31 GPIO32 GPIO33

Analog Function
ADC1_CH0 ADC1_CH1 ADC1_CH2 ADC1_CH3 ADC1_CH4 ADC1_CH5 ADC1_CH6 ADC1_CH7 ADC1_CH8 ADC1_CH9 ADC2_CH0 ADC2_CH1 ADC2_CH2 ADC2_CH3 ADC2_CH4 ADC2_CH5 ADC2_CH6 ADC2_CH7 ADC2_CH8 ADC2_CH9

RTC GPIO RTC_GPIO0 RTC_GPIO1 RTC_GPIO2 RTC_GPIO3 RTC_GPIO4 RTC_GPIO5 RTC_GPIO6 RTC_GPIO7 RTC_GPIO8 RTC_GPIO9 RTC_GPIO10 RTC_GPIO11 RTC_GPIO12 RTC_GPIO13 RTC_GPIO14 RTC_GPIO15 RTC_GPIO16 RTC_GPIO17 RTC_GPIO18 RTC_GPIO19 RTC_GPIO20 RTC_GPIO21

Comment Strapping pin
Strapping pin

USB-JTAG USB-JTAG

SPI0/1 SPI0/1 SPI0/1 SPI0/1 SPI0/1 SPI0/1 SPI0/1 SPI0/1

Continued on next page

Espressif Systems

520

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

GPIO GPIO34 GPIO35 GPIO36 GPIO37 GPIO38 GPIO39 GPIO40 GPIO41 GPIO42 GPIO43 GPIO44 GPIO45 GPIO46 GPIO47 GPIO48

Table 1 ­ continued from previous page

Analog Function

RTC GPIO

Comment

SPI0/1

SPI0/1

SPI0/1

SPI0/1

Strapping pin Strapping pin

Note: · Strapping pin: GPIO0, GPIO3, GPIO45 and GPIO46 are strapping pins. · SPI0/1: GPIO26-32 are usually used for SPI flash and PSRAM and not recommended for other uses. When using Octal Flash or Octal PSRAM or both, GPIO33~37 are connected to SPIIO4 ~ SPIIO7 and SPIDQS. Therefore on ESP32-S3R8 / ESP32-S3R8V board GPIO33~37 are also not recommended for other uses. · USB-JTAG: GPIO 19 and 20 are used by USB-JTAG by default. In order to use them as GPIOs, USB-JTAG will be disabled by the drivers.
There is also separate oRTC GPIOpsupport, which functions when GPIOs are routed to the oRTCplow-power and analog subsystem. These pin functions can be used when:
· In deep sleep · The Ultra Low Power co-processor is running · Analog functions such as ADC/DAC/etc are in use.
Application Example
GPIO output and input interrupt example: peripherals/gpio/generic_gpio.
API Reference - Normal GPIO
Header File · components/driver/include/driver/gpio.h
Functions esp_err_t gpio_config(const gpio_config_t *pGPIOConfig)
GPIO common configuration.
Configure GPIO's Mode,pull-up,PullDown,IntrType
Return · ESP_OK success · ESP_ERR_INVALID_ARG Parameter error
Parameters · pGPIOConfig: Pointer to GPIO configure struct

Espressif Systems

521

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t gpio_reset_pin(gpio_num_t gpio_num) Reset an gpio to default state (select gpio function, enable pullup and disable input and output).
Note This function also configures the IOMUX for this pin to the GPIO function, and disconnects any other peripheral output configured via GPIO Matrix.
Return Always return ESP_OK. Parameters
· gpio_num: GPIO number.
esp_err_t gpio_set_intr_type(gpio_num_t gpio_num, gpio_int_type_t intr_type) GPIO set interrupt trigger type.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · gpio_num: GPIO number. If you want to set the trigger type of e.g. of GPIO16, gpio_num should be GPIO_NUM_16 (16); · intr_type: Interrupt type, select from gpio_int_type_t
esp_err_t gpio_intr_enable(gpio_num_t gpio_num) Enable GPIO module interrupt signal.
Note Please do not use the interrupt of GPIO36 and GPIO39 when using ADC or Wi-Fi with sleep mode enabled. Please refer to the comments of adc1_get_raw. Please refer to section 3.11 of
mECO_and_Workarounds_for_Bugs_in_ESP32nfor 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 remove the glitches on GPIO36 and GPIO39.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · gpio_num: GPIO number. If you want to enable an interrupt on e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);
esp_err_t gpio_intr_disable(gpio_num_t gpio_num) Disable GPIO module interrupt signal.
Return · ESP_OK success · ESP_ERR_INVALID_ARG Parameter error
Parameters · gpio_num: GPIO number. If you want to disable the interrupt of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);
esp_err_t gpio_set_level(gpio_num_t gpio_num, uint32_t level) GPIO set output level.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG GPIO number error
Parameters · gpio_num: GPIO number. If you want to set the output level of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16); · level: Output level. 0: low ; 1: high
int gpio_get_level(gpio_num_t gpio_num) GPIO get input level.
Warning If the pad is not configured for input (or input and output) the returned value is always 0. Return
· 0 the GPIO input level is 0 · 1 the GPIO input level is 1 Parameters

Espressif Systems

522

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· gpio_num: GPIO number. If you want to get the logic level of e.g. pin GPIO16, gpio_num should be GPIO_NUM_16 (16);

esp_err_t gpio_set_direction(gpio_num_t gpio_num, gpio_mode_t mode) GPIO set direction.

Configure GPIO direction,such as output_only,input_only,output_and_input

Return · ESP_OK Success · ESP_ERR_INVALID_ARG GPIO error
Parameters · gpio_num: Configure GPIO pins number, it should be GPIO number. If you want to set direction of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16); · mode: GPIO direction

esp_err_t gpio_set_pull_mode(gpio_num_t gpio_num, gpio_pull_mode_t pull) Configure GPIO pull-up/pull-down resistors.

Only pins that support both input & output have integrated pull-up and pull-down resistors. Input-only GPIOs 34-39 do not.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG : Parameter error
Parameters · gpio_num: GPIO number. If you want to set pull up or down mode for e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16); · pull: GPIO pull up/down mode.

esp_err_t gpio_wakeup_enable(gpio_num_t gpio_num, gpio_int_type_t intr_type) Enable GPIO wake-up function.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · gpio_num: GPIO number. · intr_type: GPIO wake-up type. GPIO_INTR_HIGH_LEVEL can be used.

Only GPIO_INTR_LOW_LEVEL or

esp_err_t gpio_wakeup_disable(gpio_num_t gpio_num) Disable GPIO wake-up function.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · gpio_num: GPIO number

esp_err_t gpio_isr_register(void (*fn))void * , void *arg, int intr_alloc_flags, gpio_isr_handle_t *handleRegister GPIO interrupt handler, the handler is an ISR. The handler will be attached to the same CPU core that this function is running on.

This ISR function is called whenever any GPIO interrupt occurs. See the alternative gpio_install_isr_service() and gpio_isr_handler_add() API in order to have the driver support per-GPIO ISRs.

To disable or remove the ISR, pass the returned handle to the interrupt allocation functions.

Parameters · fn: Interrupt handler function. · arg: Parameter for handler function · intr_alloc_flags: Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info. · handle: Pointer to return handle. If non-NULL, a handle for the interrupt will be returned here.

Espressif Systems

523

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return · ESP_OK Success ; · ESP_ERR_INVALID_ARG GPIO error · ESP_ERR_NOT_FOUND No free interrupt found with the specified flags
esp_err_t gpio_pullup_en(gpio_num_t gpio_num) Enable pull-up on GPIO.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · gpio_num: GPIO number
esp_err_t gpio_pullup_dis(gpio_num_t gpio_num) Disable pull-up on GPIO.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · gpio_num: GPIO number
esp_err_t gpio_pulldown_en(gpio_num_t gpio_num) Enable pull-down on GPIO.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · gpio_num: GPIO number
esp_err_t gpio_pulldown_dis(gpio_num_t gpio_num) Disable pull-down on GPIO.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · gpio_num: GPIO number
esp_err_t gpio_install_isr_service(int intr_alloc_flags) Install the driverns GPIO ISR handler service, which allows per-pin GPIO interrupt handlers.
This function is incompatible with gpio_isr_register() - if that function is used, a single global ISR is registered for all GPIO interrupts. If this function is used, the ISR service provides a global GPIO ISR and individual pin handlers are registered via the gpio_isr_handler_add() function.
Return · ESP_OK Success · ESP_ERR_NO_MEM No memory to install this service · ESP_ERR_INVALID_STATE ISR service already installed. · ESP_ERR_NOT_FOUND No free interrupt found with the specified flags · ESP_ERR_INVALID_ARG GPIO error
Parameters · intr_alloc_flags: Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.
void gpio_uninstall_isr_service(void) Uninstall the driverns GPIO ISR service, freeing related resources.
esp_err_t gpio_isr_handler_add(gpio_num_t gpio_num, gpio_isr_t isr_handler, void *args) Add ISR handler for the corresponding GPIO pin.
Call this function after using gpio_install_isr_service() to install the driverns GPIO ISR handler service.

Espressif Systems

524

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
The pin ISR handlers no longer need to be declared with IRAM_ATTR, unless you pass the ESP_INTR_FLAG_IRAM flag when allocating the ISR in gpio_install_isr_service().
This ISR handler will be called from an ISR. So there is a stack size limit (configurable as oISR stack sizep in menuconfig). This limit is smaller compared to a global GPIO interrupt handler due to the additional level of indirection.
Return · ESP_OK Success · ESP_ERR_INVALID_STATE Wrong state, the ISR service has not been initialized. · ESP_ERR_INVALID_ARG Parameter error
Parameters · gpio_num: GPIO number · isr_handler: ISR handler function for the corresponding GPIO number. · args: parameter for ISR handler.
esp_err_t gpio_isr_handler_remove(gpio_num_t gpio_num) Remove ISR handler for the corresponding GPIO pin.
Return · ESP_OK Success · ESP_ERR_INVALID_STATE Wrong state, the ISR service has not been initialized. · ESP_ERR_INVALID_ARG Parameter error
Parameters · gpio_num: GPIO number
esp_err_t gpio_set_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t strength) Set GPIO pad drive capability.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · gpio_num: GPIO number, only support output GPIOs · strength: Drive capability of the pad
esp_err_t gpio_get_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t *strength) Get GPIO pad drive capability.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · gpio_num: GPIO number, only support output GPIOs · strength: Pointer to accept drive capability of the pad
esp_err_t gpio_hold_en(gpio_num_t gpio_num) Enable gpio pad hold function.
The gpio pad hold function works in both input and output modes, but must be output-capable gpios. If pad hold enabled: in output mode: the output level of the pad will be force locked and can not be changed. in input mode: the input value read will not change, regardless the changes of input signal.
The state of digital gpio cannot be held during Deep-sleep, and it will resume the hold function when the chip wakes up from Deep-sleep. If the digital gpio also needs to be held during Deep-sleep, gpio_deep_sleep_hold_en should also be called.
Power down or call gpio_hold_dis will disable this function.
Return · ESP_OK Success · ESP_ERR_NOT_SUPPORTED Not support pad hold function
Parameters · gpio_num: GPIO number, only support output-capable GPIOs

Espressif Systems

525

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t gpio_hold_dis(gpio_num_t gpio_num) Disable gpio pad hold function.

When the chip is woken up from Deep-sleep, the gpio will be set to the default mode, so, the gpio will output the default level if this function is called. If you donnt want the level changes, the gpio should be configured to a known state before this function is called. e.g. If you hold gpio18 high during Deep-sleep, after the chip is woken up and gpio_hold_dis is called, gpio18 will output low level(because gpio18 is input mode by default). If you donnt want this behavior, you should configure gpio18 as output mode and set it to hight level before calling gpio_hold_dis.

Return · ESP_OK Success · ESP_ERR_NOT_SUPPORTED Not support pad hold function
Parameters · gpio_num: GPIO number, only support output-capable GPIOs

void gpio_deep_sleep_hold_en(void) Enable all digital gpio pad hold function during Deep-sleep.

When the chip is in Deep-sleep mode, all digital gpio will hold the state before sleep, and when the chip is woken up, the status of digital gpio will not be held. Note that the pad hold feature only works when the chip is in Deep-sleep mode, when not in sleep mode, the digital gpio state can be changed even you have called this function.

Power down or call gpio_hold_dis will disable this function, otherwise, the digital gpio hold feature works as long as the chip enter Deep-sleep.

void gpio_deep_sleep_hold_dis(void) Disable all digital gpio pad hold function during Deep-sleep.

void gpio_iomux_in(uint32_t gpio_num, uint32_t signal_idx) Set pad input to a peripheral signal through the IOMUX.

Parameters · gpio_num: GPIO number of the pad. · signal_idx: Peripheral signal id to input. gpio_sig_map.h.

One of the *_IN_IDX signals in soc/

void gpio_iomux_out(uint8_t gpio_num, int func, bool oen_inv) Set peripheral output to an GPIO pad through the IOMUX.

Parameters · gpio_num: gpio_num GPIO number of the pad. · func: The function number of the peripheral pin to output pin. One of the FUNC_X_* of specified pin (X) in soc/io_mux_reg.h. · oen_inv: True if the output enable needs to be inverted, otherwise False.

esp_err_t gpio_force_hold_all(void) Force hold digital and rtc gpio pad.

Note GPIO force hold, whether the chip in sleep mode or wakeup mode.

esp_err_t gpio_force_unhold_all(void) Force unhold digital and rtc gpio pad.

Note GPIO force unhold, whether the chip in sleep mode or wakeup mode.

esp_err_t gpio_sleep_sel_en(gpio_num_t gpio_num) Enable SLP_SEL to change GPIO status automantically in lightsleep.

Return · ESP_OK Success
Parameters · gpio_num: GPIO number of the pad.

esp_err_t gpio_sleep_sel_dis(gpio_num_t gpio_num) Disable SLP_SEL to change GPIO status automantically in lightsleep.

Espressif Systems

526

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Return · ESP_OK Success
Parameters · gpio_num: GPIO number of the pad.
esp_err_t gpio_sleep_set_direction(gpio_num_t gpio_num, gpio_mode_t mode) GPIO set direction at sleep. Configure GPIO direction,such as output_only,input_only,output_and_input Return · ESP_OK Success · ESP_ERR_INVALID_ARG GPIO error Parameters · gpio_num: Configure GPIO pins number, it should be GPIO number. If you want to set direction of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16); · mode: GPIO direction
esp_err_t gpio_sleep_set_pull_mode(gpio_num_t gpio_num, gpio_pull_mode_t pull) Configure GPIO pull-up/pull-down resistors at sleep. Only pins that support both input & output have integrated pull-up and pull-down resistors. Input-only GPIOs 34-39 do not. Return · ESP_OK Success · ESP_ERR_INVALID_ARG : Parameter error Parameters · gpio_num: GPIO number. If you want to set pull up or down mode for e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16); · pull: GPIO pull up/down mode.
Macros GPIO_PIN_COUNT GPIO_IS_VALID_GPIO(gpio_num)
Check whether it is a valid GPIO number. GPIO_IS_VALID_OUTPUT_GPIO(gpio_num)
Check whether it can be a valid GPIO number of output mode.
Type Definitions typedef intr_handle_t gpio_isr_handle_t
Header File · components/hal/include/hal/gpio_types.h
Structures struct gpio_config_t
Configuration parameters of GPIO pad for gpio_config function.
Public Members
uint64_t pin_bit_mask GPIO pin: set with bit mask, each bit maps to a GPIO
gpio_mode_t mode GPIO mode: set input/output mode

Espressif Systems

527

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
gpio_pullup_t pull_up_en GPIO pull-up
gpio_pulldown_t pull_down_en GPIO pull-down
gpio_int_type_t intr_type GPIO interrupt type
Macros GPIO_SEL_0
Pin 0 selected GPIO_SEL_1
Pin 1 selected
GPIO_SEL_2 Pin 2 selected
GPIO_SEL_3 Pin 3 selected
GPIO_SEL_4 Pin 4 selected
GPIO_SEL_5 Pin 5 selected
GPIO_SEL_6 Pin 6 selected
GPIO_SEL_7 Pin 7 selected
GPIO_SEL_8 Pin 8 selected
GPIO_SEL_9 Pin 9 selected
GPIO_SEL_10 Pin 10 selected
GPIO_SEL_11 Pin 11 selected
GPIO_SEL_12 Pin 12 selected
GPIO_SEL_13 Pin 13 selected
GPIO_SEL_14 Pin 14 selected
GPIO_SEL_15 Pin 15 selected
GPIO_SEL_16 Pin 16 selected
GPIO_SEL_17 Pin 17 selected
GPIO_SEL_18 Pin 18 selected

Espressif Systems

528

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
GPIO_SEL_19 Pin 19 selected
GPIO_SEL_20 Pin 20 selected
GPIO_SEL_21 Pin 21 selected
GPIO_SEL_26 Pin 26 selected
GPIO_SEL_27 Pin 27 selected
GPIO_SEL_28 Pin 28 selected
GPIO_SEL_29 Pin 29 selected
GPIO_SEL_30 Pin 30 selected
GPIO_SEL_31 Pin 31 selected
GPIO_SEL_32 Pin 32 selected
GPIO_SEL_33 Pin 33 selected
GPIO_SEL_34 Pin 34 selected
GPIO_SEL_35 Pin 35 selected
GPIO_SEL_36 Pin 36 selected
GPIO_SEL_37 Pin 37 selected
GPIO_SEL_38 Pin 38 selected
GPIO_SEL_39 Pin 39 selected
GPIO_SEL_40 Pin 40 selected
GPIO_SEL_41 Pin 41 selected
GPIO_SEL_42 Pin 42 selected
GPIO_SEL_43 Pin 43 selected
GPIO_SEL_44 Pin 44 selected
GPIO_SEL_45 Pin 45 selected
Espressif Systems

529

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
GPIO_SEL_46 Pin 46 selected
GPIO_SEL_47 Pin 47 selected
GPIO_SEL_48 Pin 48 selected
GPIO_PIN_REG_0 GPIO_PIN_REG_1 GPIO_PIN_REG_2 GPIO_PIN_REG_3 GPIO_PIN_REG_4 GPIO_PIN_REG_5 GPIO_PIN_REG_6 GPIO_PIN_REG_7 GPIO_PIN_REG_8 GPIO_PIN_REG_9 GPIO_PIN_REG_10 GPIO_PIN_REG_11 GPIO_PIN_REG_12 GPIO_PIN_REG_13 GPIO_PIN_REG_14 GPIO_PIN_REG_15 GPIO_PIN_REG_16 GPIO_PIN_REG_17 GPIO_PIN_REG_18 GPIO_PIN_REG_19 GPIO_PIN_REG_20 GPIO_PIN_REG_21 GPIO_PIN_REG_22 GPIO_PIN_REG_23 GPIO_PIN_REG_24 GPIO_PIN_REG_25 GPIO_PIN_REG_26 GPIO_PIN_REG_27 GPIO_PIN_REG_28 GPIO_PIN_REG_29 GPIO_PIN_REG_30 GPIO_PIN_REG_31 GPIO_PIN_REG_32 GPIO_PIN_REG_33
Espressif Systems

530

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

GPIO_PIN_REG_34 GPIO_PIN_REG_35 GPIO_PIN_REG_36 GPIO_PIN_REG_37 GPIO_PIN_REG_38 GPIO_PIN_REG_39 GPIO_PIN_REG_40 GPIO_PIN_REG_41 GPIO_PIN_REG_42 GPIO_PIN_REG_43 GPIO_PIN_REG_44 GPIO_PIN_REG_45 GPIO_PIN_REG_46 GPIO_PIN_REG_47 GPIO_PIN_REG_48
Type Definitions typedef void (*gpio_isr_t)(void *)
Enumerations enum gpio_port_t
Values: GPIO_PORT_0 = 0 GPIO_PORT_MAX enum gpio_num_t Values: GPIO_NUM_NC = -1
Use to signal not connected to S/W GPIO_NUM_0 = 0
GPIO0, input and output GPIO_NUM_1 = 1
GPIO1, input and output GPIO_NUM_2 = 2
GPIO2, input and output GPIO_NUM_3 = 3
GPIO3, input and output GPIO_NUM_4 = 4
GPIO4, input and output GPIO_NUM_5 = 5
GPIO5, input and output GPIO_NUM_6 = 6
GPIO6, input and output GPIO_NUM_7 = 7
GPIO7, input and output

Espressif Systems

531

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
GPIO_NUM_8 = 8 GPIO8, input and output
GPIO_NUM_9 = 9 GPIO9, input and output
GPIO_NUM_10 = 10 GPIO10, input and output
GPIO_NUM_11 = 11 GPIO11, input and output
GPIO_NUM_12 = 12 GPIO12, input and output
GPIO_NUM_13 = 13 GPIO13, input and output
GPIO_NUM_14 = 14 GPIO14, input and output
GPIO_NUM_15 = 15 GPIO15, input and output
GPIO_NUM_16 = 16 GPIO16, input and output
GPIO_NUM_17 = 17 GPIO17, input and output
GPIO_NUM_18 = 18 GPIO18, input and output
GPIO_NUM_19 = 19 GPIO19, input and output
GPIO_NUM_20 = 20 GPIO20, input and output
GPIO_NUM_21 = 21 GPIO21, input and output
GPIO_NUM_26 = 26 GPIO26, input and output
GPIO_NUM_27 = 27 GPIO27, input and output
GPIO_NUM_28 = 28 GPIO28, input and output
GPIO_NUM_29 = 29 GPIO29, input and output
GPIO_NUM_30 = 30 GPIO30, input and output
GPIO_NUM_31 = 31 GPIO31, input and output
GPIO_NUM_32 = 32 GPIO32, input and output
GPIO_NUM_33 = 33 GPIO33, input and output
GPIO_NUM_34 = 34 GPIO34, input and output

Espressif Systems

532

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
GPIO_NUM_35 = 35 GPIO35, input and output
GPIO_NUM_36 = 36 GPIO36, input and output
GPIO_NUM_37 = 37 GPIO37, input and output
GPIO_NUM_38 = 38 GPIO38, input and output
GPIO_NUM_39 = 39 GPIO39, input and output
GPIO_NUM_40 = 40 GPIO40, input and output
GPIO_NUM_41 = 41 GPIO41, input and output
GPIO_NUM_42 = 42 GPIO42, input and output
GPIO_NUM_43 = 43 GPIO43, input and output
GPIO_NUM_44 = 44 GPIO44, input and output
GPIO_NUM_45 = 45 GPIO45, input and output
GPIO_NUM_46 = 46 GPIO46, input and output
GPIO_NUM_47 = 47 GPIO47, input and output
GPIO_NUM_48 = 48 GPIO48, input and output
GPIO_NUM_MAX
enum gpio_int_type_t Values:
GPIO_INTR_DISABLE = 0 Disable GPIO interrupt
GPIO_INTR_POSEDGE = 1 GPIO interrupt type : rising edge
GPIO_INTR_NEGEDGE = 2 GPIO interrupt type : falling edge
GPIO_INTR_ANYEDGE = 3 GPIO interrupt type : both rising and falling edge
GPIO_INTR_LOW_LEVEL = 4 GPIO interrupt type : input low level trigger
GPIO_INTR_HIGH_LEVEL = 5 GPIO interrupt type : input high level trigger
GPIO_INTR_MAX
enum gpio_mode_t Values:

Espressif Systems

533

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

GPIO_MODE_DISABLE = GPIO_MODE_DEF_DISABLE GPIO mode : disable input and output
GPIO_MODE_INPUT = GPIO_MODE_DEF_INPUT GPIO mode : input only
GPIO_MODE_OUTPUT = GPIO_MODE_DEF_OUTPUT GPIO mode : output only mode
GPIO_MODE_OUTPUT_OD = ((GPIO_MODE_DEF_OUTPUT) | (GPIO_MODE_DEF_OD)) GPIO mode : output only with open-drain mode
GPIO_MODE_INPUT_OUTPUT_OD = ((GPIO_MODE_DEF_INPUT) | (GPIO_MODE_DEF_OUTPUT) | (GPIO_MODE_D GPIO mode : output and input with open-drain mode
GPIO_MODE_INPUT_OUTPUT = ((GPIO_MODE_DEF_INPUT) | (GPIO_MODE_DEF_OUTPUT)) GPIO mode : output and input mode
enum gpio_pullup_t Values:
GPIO_PULLUP_DISABLE = 0x0 Disable GPIO pull-up resistor
GPIO_PULLUP_ENABLE = 0x1 Enable GPIO pull-up resistor
enum gpio_pulldown_t Values:
GPIO_PULLDOWN_DISABLE = 0x0 Disable GPIO pull-down resistor
GPIO_PULLDOWN_ENABLE = 0x1 Enable GPIO pull-down resistor
enum gpio_pull_mode_t Values:
GPIO_PULLUP_ONLY Pad pull up
GPIO_PULLDOWN_ONLY Pad pull down
GPIO_PULLUP_PULLDOWN Pad pull up + pull down
GPIO_FLOATING Pad floating
enum gpio_drive_cap_t Values:
GPIO_DRIVE_CAP_0 = 0 Pad drive capability: weak
GPIO_DRIVE_CAP_1 = 1 Pad drive capability: stronger
GPIO_DRIVE_CAP_2 = 2 Pad drive capability: medium
GPIO_DRIVE_CAP_DEFAULT = 2 Pad drive capability: medium
GPIO_DRIVE_CAP_3 = 3 Pad drive capability: strongest
GPIO_DRIVE_CAP_MAX

Espressif Systems

534

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

API Reference - RTC GPIO
Header File
· components/driver/include/driver/rtc_io.h
Functions bool rtc_gpio_is_valid_gpio(gpio_num_t gpio_num)
Determine if the specified GPIO is a valid RTC GPIO.
Return true if GPIO is valid for RTC GPIO use. false otherwise. Parameters
· gpio_num: GPIO number int rtc_io_number_get(gpio_num_t gpio_num)
Get RTC IO index number by gpio number.
Return >=0: Index of rtcio. -1 : The gpio is not rtcio. Parameters
· gpio_num: GPIO number
esp_err_t rtc_gpio_init(gpio_num_t gpio_num) Init a GPIO as RTC GPIO.
This function must be called when initializing a pad for an analog function.
Return · ESP_OK success · ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters · gpio_num: GPIO number (e.g. GPIO_NUM_12)
esp_err_t rtc_gpio_deinit(gpio_num_t gpio_num) Init a GPIO as digital GPIO.
Return · ESP_OK success · ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters · gpio_num: GPIO number (e.g. GPIO_NUM_12)
uint32_t rtc_gpio_get_level(gpio_num_t gpio_num) Get the RTC IO input level.
Return · 1 High level · 0 Low level · ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters · gpio_num: GPIO number (e.g. GPIO_NUM_12)
esp_err_t rtc_gpio_set_level(gpio_num_t gpio_num, uint32_t level) Set the RTC IO output level.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters · gpio_num: GPIO number (e.g. GPIO_NUM_12) · level: output level
esp_err_t rtc_gpio_set_direction(gpio_num_t gpio_num, rtc_gpio_mode_t mode) RTC GPIO set direction.
Configure RTC GPIO direction, such as output only, input only, output and input.

Espressif Systems

535

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return · ESP_OK Success · ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters · gpio_num: GPIO number (e.g. GPIO_NUM_12) · mode: GPIO direction
esp_err_t rtc_gpio_set_direction_in_sleep(gpio_num_t gpio_num, rtc_gpio_mode_t mode) RTC GPIO set direction in deep sleep mode or disable sleep status (default). In some application scenarios, IO needs to have another states during deep sleep.
NOTE: ESP32 support INPUT_ONLY mode. ESP32S2 support INPUT_ONLY, OUTPUT_ONLY, INPUT_OUTPUT mode.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters · gpio_num: GPIO number (e.g. GPIO_NUM_12) · mode: GPIO direction
esp_err_t rtc_gpio_pullup_en(gpio_num_t gpio_num) RTC GPIO pullup enable.
This function only works for RTC IOs. In general, call gpio_pullup_en, which will work both for normal GPIOs and RTC IOs.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters · gpio_num: GPIO number (e.g. GPIO_NUM_12)
esp_err_t rtc_gpio_pulldown_en(gpio_num_t gpio_num) RTC GPIO pulldown enable.
This function only works for RTC IOs. In general, call gpio_pulldown_en, which will work both for normal GPIOs and RTC IOs.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters · gpio_num: GPIO number (e.g. GPIO_NUM_12)
esp_err_t rtc_gpio_pullup_dis(gpio_num_t gpio_num) RTC GPIO pullup disable.
This function only works for RTC IOs. In general, call gpio_pullup_dis, which will work both for normal GPIOs and RTC IOs.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters · gpio_num: GPIO number (e.g. GPIO_NUM_12)
esp_err_t rtc_gpio_pulldown_dis(gpio_num_t gpio_num) RTC GPIO pulldown disable.
This function only works for RTC IOs. In general, call gpio_pulldown_dis, which will work both for normal GPIOs and RTC IOs.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG GPIO is not an RTC IO

Espressif Systems

536

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Parameters · gpio_num: GPIO number (e.g. GPIO_NUM_12)
esp_err_t rtc_gpio_set_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t strength) Set RTC GPIO pad drive capability.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · gpio_num: GPIO number, only support output GPIOs · strength: Drive capability of the pad
esp_err_t rtc_gpio_get_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t *strength) Get RTC GPIO pad drive capability.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · gpio_num: GPIO number, only support output GPIOs · strength: Pointer to accept drive capability of the pad
esp_err_t rtc_gpio_hold_en(gpio_num_t gpio_num) Enable hold function on an RTC IO pad.
Enabling HOLD function will cause the pad to latch current values of input enable, output enable, output value, function, drive strength values. This function is useful when going into light or deep sleep mode to prevent the pin configuration from changing.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters · gpio_num: GPIO number (e.g. GPIO_NUM_12)
esp_err_t rtc_gpio_hold_dis(gpio_num_t gpio_num) Disable hold function on an RTC IO pad.
Disabling hold function will allow the pad receive the values of input enable, output enable, output value, function, drive strength from RTC_IO peripheral.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters · gpio_num: GPIO number (e.g. GPIO_NUM_12)
esp_err_t rtc_gpio_isolate(gpio_num_t gpio_num) Helper function to disconnect internal circuits from an RTC IO This function disables input, output, pullup, pulldown, and enables hold feature for an RTC IO. Use this function if an RTC IO needs to be disconnected from internal circuits in deep sleep, to minimize leakage current.
In particular, for ESP32-WROVER module, call rtc_gpio_isolate(GPIO_NUM_12) before entering deep sleep, to reduce deep sleep current.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if GPIO is not an RTC IO
Parameters · gpio_num: GPIO number (e.g. GPIO_NUM_12).
esp_err_t rtc_gpio_force_hold_all(void) Enable force hold signal for all RTC IOs.

Espressif Systems

537

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Each RTC pad has aoforce holdpinput signal from the RTC controller. If this signal is set, pad latches current values of input enable, function, output enable, and other signals which come from the RTC mux. Force hold signal is enabled before going into deep sleep for pins which are used for EXT1 wakeup.
esp_err_t rtc_gpio_force_hold_dis_all(void) Disable force hold signal for all RTC IOs.
esp_err_t rtc_gpio_wakeup_enable(gpio_num_t gpio_num, gpio_int_type_t intr_type) Enable wakeup from sleep mode using specific GPIO.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if gpio_num is not an RTC IO, or intr_type is not one of GPIO_INTR_HIGH_LEVEL, GPIO_INTR_LOW_LEVEL.
Parameters · gpio_num: GPIO number · intr_type: Wakeup on high level (GPIO_INTR_HIGH_LEVEL) or low level (GPIO_INTR_LOW_LEVEL)
esp_err_t rtc_gpio_wakeup_disable(gpio_num_t gpio_num) Disable wakeup from sleep mode using specific GPIO.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if gpio_num is not an RTC IO
Parameters · gpio_num: GPIO number
Macros RTC_GPIO_IS_VALID_GPIO(gpio_num)
Header File
· components/hal/include/hal/rtc_io_types.h
Enumerations enum rtc_gpio_mode_t
RTCIO output/input mode type.
Values:
RTC_GPIO_MODE_INPUT_ONLY Pad input
RTC_GPIO_MODE_OUTPUT_ONLY Pad output
RTC_GPIO_MODE_INPUT_OUTPUT Pad input + output
RTC_GPIO_MODE_DISABLED Pad (output + input) disable
RTC_GPIO_MODE_OUTPUT_OD Pad open-drain output
RTC_GPIO_MODE_INPUT_OUTPUT_OD Pad input + open-drain output

Espressif Systems

538

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

2.3.3 General Purpose Timer (GPTimer)
Introduction
A general purpose timer is a hardware timer with high resolution and flexible alarm action. The behavior when the internal counter of a timer reaches a specific target value is called timer alarm. When a timer alarms, a user registered per-timer callback would be called.
Typically, a general purpose timer can be used in scenarios like:
· Free running as a wall clock, fetching a high-resolution time stamp at any time and any places · Generate period alarms, trigger events periodically · Generate one-shot alarm, respond in target time
Functional Overview
The following sections of this document cover the typical steps to install and operate a timer:
· Resource Allocation - covers which parameters should be set up to get a timer handle and how to recycle the resources when GPTimer finishes working.
· Set and Get count value - covers how to force the timer counting from a start point and how to get the count value at anytime.
· Set Up Alarm Action - covers the parameters that should be set up to enable the alarm event. · Register Event Callbacks - covers how to hook user specific code to the alarm event callback function. · Start and Stop timer - shows some typical use cases that start the timer with different alarm behavior. · Power Management - describes how different source clock selections can affect power consumption. · IRAM Safe - describes tips on how to make the timer interrupt and IO control functions work better along with
a disabled cache. · Thread Safety - lists which APIs are guaranteed to be thread safe by the driver.
Resource Allocation Different ESP chip might have different number of independent timer groups, and within each group, there could also be several independent timers. Refer to the datasheet to find out how many hardware timers exist (usually described in the oGeneral Purpose Timerpchapter).
From driverns point of view, a GPTimer instance is represented by gptimer_handle_t. The driver behind will manage all available hardware resources in a pool, so that users donnt need to care about which timer and which group it belongs to.
To install a timer instance, therens a configuration structure that needs to be given in advance: gptimer_config_t:
· clk_src selects the source clock for the timer. The available clocks are listed in gptimer_clock_source_t,1 you can only pick one of them. For the effect on power consumption of different clock source, please refer to Power management section.
· direction sets the counting direction of the timer, supported directions are listed in gptimer_count_direction_t, you can only pick one of them.
· resolution_hz sets the resolution of the internal counter. Each count step is equivalent to 1 / resolution_hz seconds.
· Optional intr_shared sets whether or not mark the timer interrupt source as a shared one. For the pros/cons of a shared interrupt, you can refer to Interrupt Handling.
With all the above configurations set in the structure, the structure can be passed to gptimer_new_timer() which will instantiate the timer instance and return a handle of the timer.
The function can fail due to various errors such as insufficient memory, invalid arguments, etc. Specifically, when there are no more free timers (i.e. all hardware resources have been used up), then ESP_ERR_NOT_FOUND will be returned. The total number of available timers is represented by the SOC_TIMER_GROUP_TOTAL_TIMERS and its value will depend on the ESP chip.
Some ESP chip might only support a sub-set of the clocks, if an unsupported clock source is specified, you will get a runtime error during timer installation.

Espressif Systems

539

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
If a previously created GPTimer instance is no longer required, you should recycle the timer by calling gptimer_del_timer(). This will allow the underlying HW timer to be used for other purposes. Before deleting a GPTimer handle, you should stop it by gptimer_stop() in advance or make sure it has not started yet by gptimer_start().
Creating a GPTimer Handle with Resolution of 1MHz gptimer_handle_t gptimer = NULL; gptimer_config_t timer_config = {
.clk_src = GPTIMER_CLK_SRC_APB, .direction = GPTIMER_COUNT_UP, .resolution_hz = 1 * 1000 * 1000, // 1MHz, 1 tick = 1us }; ESP_ERROR_CHECK(gptimer_new_timer(&timer_config, &gptimer));
Set and Get Count Value When the GPTimer is created, the internal counter will be reset to zero by default. The counter value can be updated asynchronously by gptimer_set_raw_count(). The maximum count value is dependent on the hardware timerns bit-width, which is also reflected by the SOC macro SOC_TIMER_GROUP_COUNTER_BIT_WIDTH. When updating the raw count of an active timer, the timer will immediately start counting from the new value. Count value can be retrieved by gptimer_get_raw_count(), at anytime.
Set Up Alarm Action Most of the use cases of GPTimer should set up the alarm action before starting the timer, except for the simple wall-clock scenario, where a free running timer is enough. To set up the alarm action, one should configure several members of gptimer_alarm_config_t based on how he takes use of the alarm event:
· alarm_count sets the target count value that will trigger the alarm event. You should also take the counting direction into consideration when setting the alarm value. Specially, alarm_count and reload_count cannt be set to the same value when auto_reload_on_alarm is true, as keeping reload with a target alarm count is meaningless.
· reload_count sets the count value to be reloaded when the alarm event happens. This configuration only takes effect when auto_reload_on_alarm is set to true.
· auto_reload_on_alarm flag sets whether to enable the auto-reload feature. If enabled, the hardware timer will reload the value of reload_count into counter immediately when alarm event happens.
To make the alarm configurations take effect, one should call gptimer_set_alarm_action(). Especially, if gptimer_alarm_config_t is set to NULL, the alarm function will be disabled.
Note: · If an alarm value is set and the timer has already crossed this value, the alarm will be triggered immediately.
Register Event Callbacks After the timer starts up, it can generate specific event (e.g. the oAlarm Eventp) dynamically. If you have some function that should be called when event happens, you should hook your function to the interrupt service routine by calling gptimer_register_event_callbacks(). All supported event callbacks are listed in the gptimer_event_callbacks_t:
· on_alarm sets callback function for alarm event. As this function is called within the ISR context, user must ensure that the function doesnnt attempt to block (e.g., by making sure that only FreeRTOS APIs with ISR suffix are called from within the function). The function prototype is declared in gptimer_alarm_cb_t.
One can save his own context to gptimer_register_event_callbacks() as well, via the parameter user_data. The user data will be directly passed to the callback functions.

Espressif Systems

540

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Start and Stop Timer To start a timer means to enable its internal counter, it can only be achieved by calling gptimer_start(). The timer can be stopped at any time (even in the interrupt context) by gptimer_stop(). One thing should be kept in mind, calling of gptimer_start() should have the same times of calling gptimer_stop() before you delete the timer, otherwise the driver might be put in an undetermined state. For example, the timer might keep a Power Management lock, which in return increase the power consumption. Also see Power management section.
Start Timer As a Wall Clock
ESP_ERROR_CHECK(gptimer_start(gptimer)); // Retrieve timestamp at anytime uint64_t count; ESP_ERROR_CHECK(gptimer_get_raw_count(gptimer, &count));

Trigger Period Events
typedef struct { uint64_t event_count;
} example_queue_element_t;
static bool example_timer_on_alarm_cb(gptimer_handle_t timer, const gptimer_alarm_ event_data_t *edata, void *user_ctx) {
BaseType_t high_task_awoken = pdFALSE; QueueHandle_t queue = (QueueHandle_t)user_ctx; // Retrieve count value from event data example_queue_element_t ele = {
.event_count = edata->count_value }; // Optional: send the event data to other task by OS queue // Don't introduce complex logics in callbacks. // Suggest dealing with event data in the main loop, instead of in this callback. xQueueSendFromISR(queue, &ele, &high_task_awoken); // return whether we need to yield at the end of ISR return high_task_awoken == pdTRUE; }
gptimer_alarm_config_t alarm_config = { .reload_count = 0, // counter will reload with 0 on alarm event .alarm_count = 1000000, // period = 1s @resolution 1MHz .flags.auto_reload_on_alarm = true, // enable auto-reload
}; ESP_ERROR_CHECK(gptimer_set_alarm_action(gptimer, &alarm_config));
gptimer_event_callbacks_t cbs = { .on_alarm = example_timer_on_alarm_cb, // register user callback
}; ESP_ERROR_CHECK(gptimer_register_event_callbacks(gptimer, &cbs, queue));
ESP_ERROR_CHECK(gptimer_start(gptimer));

Trigger One-Shot Event
typedef struct { uint64_t event_count;
} example_queue_element_t;
static bool example_timer_on_alarm_cb(gptimer_handle_t timer, const gptimer_alarm_ event_data_t *edata, void *user_ctx)
(continues on next page)

Espressif Systems

541

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

{ BaseType_t high_task_awoken = pdFALSE; QueueHandle_t queue = (QueueHandle_t)user_ctx; // Stop timer the sooner the better gptimer_stop(timer); // Retrieve count value from event data example_queue_element_t ele = { .event_count = edata->count_value }; // Optional: send the event data to other task by OS queue xQueueSendFromISR(queue, &ele, &high_task_awoken); // return whether we need to yield at the end of ISR return high_task_awoken == pdTRUE;
}

(continued from previous page)

gptimer_alarm_config_t alarm_config = { .alarm_count = 1 * 1000 * 1000, // alarm target = 1s @resolution 1MHz
}; ESP_ERROR_CHECK(gptimer_set_alarm_action(gptimer, &alarm_config));

gptimer_event_callbacks_t cbs = { .on_alarm = example_timer_on_alarm_cb, // register user callback
}; ESP_ERROR_CHECK(gptimer_register_event_callbacks(gptimer, &cbs, queue)); ESP_ERROR_CHECK(gptimer_start(gptimer));

Dynamic Alarm Update Alarm value can be updated dynamically inside the ISR handler callback, by changing the alarm_value of gptimer_alarm_event_data_t. Then the alarm value will be updated after the callback function returns.
typedef struct { uint64_t event_count;
} example_queue_element_t;

static bool example_timer_on_alarm_cb(gptimer_handle_t timer, const gptimer_alarm_ event_data_t *edata, void *user_ctx) {
BaseType_t high_task_awoken = pdFALSE; QueueHandle_t queue = (QueueHandle_t)user_data; // Retrieve count value from event data example_queue_element_t ele = {
.event_count = edata->count_value }; // Optional: send the event data to other task by OS queue xQueueSendFromISR(queue, &ele, &high_task_awoken); // reconfigure alarm value gptimer_alarm_config_t alarm_config = {
.alarm_count = edata->alarm_value + 1000000, // alarm in next 1s }; gptimer_set_alarm_action(timer, &alarm_config); // return whether we need to yield at the end of ISR return high_task_awoken == pdTRUE; }

gptimer_alarm_config_t alarm_config = { .alarm_count = 1000000, // initial alarm target = 1s @resolution 1MHz
}; ESP_ERROR_CHECK(gptimer_set_alarm_action(gptimer, &alarm_config));

gptimer_event_callbacks_t cbs = {

(continues on next page)

Espressif Systems

542

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
(continued from previous page) .on_alarm = example_timer_on_alarm_cb, // register user callback }; ESP_ERROR_CHECK(gptimer_register_event_callbacks(gptimer, &cbs, queue)); ESP_ERROR_CHECK(gptimer_start(gptimer, &alarm_config));
Power Management When power management is enabled (i.e. CONFIG_PM_ENABLE is on), the system will adjust the APB frequency before going into light sleep, thus potentially changing the period of a GPTimerns counting step and leading to inaccurate time keeping. However, the driver can prevent the system from changing APB frequency by acquiring a power management lock of type ESP_PM_APB_FREQ_MAX. Whenever the driver creates a GPTimer instance that has selected GPTIMER_CLK_SRC_APB as its clock source, the driver will guarantee that the power management lock is acquired when the timer is started by gptimer_start(). Likewise, the driver releases the lock when gptimer_stop() is called for that timer. This requires that the gptimer_start() and gptimer_stop() should appear in pairs.
IRAM Safe By default, the GPTimer interrupt will be deferred when the Cache is disabled for reasons like writing/erasing Flash. Thus the alarm interrupt will not get executed in time, which is not expected in a real-time application. Therens a Kconfig option CONFIG_GPTIMER_ISR_IRAM_SAFE that will:
1. Enable the interrupt being serviced even when cache is disabled 2. Place all functions that used by the ISR into IRAM2 3. Place driver object into DRAM (in case itns linked to PSRAM by accident) This will allow the interrupt to run while the cache is disabled but will come at the cost of increased IRAM consumption. Therens another Kconfig option CONFIG_GPTIMER_CTRL_FUNC_IN_IRAM that can put commonly used IO control functions into IRAM as well. So that these functions can also be executable when the cache is disabled. These IO control functions are as follows: · gptimer_start() · gptimer_stop() · gptimer_get_raw_count() · gptimer_set_raw_count() · gptimer_set_alarm_action()
Thread Safety The factory function gptimer_new_timer() is guaranteed to be thread safe by the driver, which means, user can call it from different RTOS tasks without protection by extra locks. Other functions that take the gptimer_handle_t as the first positional parameter, are not thread safe. The lifecycle of the gptimer handle is maintained by the user. So user should avoid calling them concurrently. If it has to, then one should introduce another mutex to prevent the gptimer handle being accessed concurrently.
Application Examples
Typical use cases of GPTimer are listed in the example: peripherals/timer_group/gptimer.
API Reference
Header File · components/driver/include/driver/gptimer.h
on_alarm callback and the functions invoked by itself should also be placed in IRAM, users need to take care of them by themselves.

Espressif Systems

543

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Functions esp_err_t gptimer_new_timer(const gptimer_config_t *config, gptimer_handle_t *ret_timer)
Create a new General Purpose Timer, and return the handle.
Note Once a timer is created, it is placed in the stopped state and will not start until gptimer_start() is called.
Return · ESP_OK: Create GPTimer successfully · ESP_ERR_INVALID_ARG: Create GPTimer failed because of invalid argument · ESP_ERR_NO_MEM: Create GPTimer failed because out of memory · ESP_ERR_NOT_FOUND: Create GPTimer failed because all hardware timers are used up and no more free one · ESP_FAIL: Create GPTimer failed because of other error
Parameters · [in] config: GPTimer configuration · [out] ret_timer: Returned timer handle
esp_err_t gptimer_del_timer(gptimer_handle_t timer) Delete the GPTimer handle.
Note A timer must be in a stop state before it can be deleted. Return
· ESP_OK: Delete GPTimer successfully · ESP_ERR_INVALID_ARG: Delete GPTimer failed because of invalid argument · ESP_ERR_INVALID_STATE: Delete GPTimer failed because the timer has not stopped · ESP_FAIL: Delete GPTimer failed because of other error Parameters · [in] timer: Timer handle created by gptimer_new_timer()
esp_err_t gptimer_set_raw_count(gptimer_handle_t timer, uint64_t value) Set GPTimer raw count value.
Note When updating the raw count of an active timer, the timer will immediately start counting from the new value.
Note This function is allowed to run within ISR context Note This function is allowed to be executed when Cache is disabled, by enabling CON-
FIG_GPTIMER_CTRL_FUNC_IN_IRAM Return
· ESP_OK: Set GPTimer raw count value successfully · ESP_ERR_INVALID_ARG: Set GPTimer raw count value failed because of invalid argument · ESP_FAIL: Set GPTimer raw count value failed because of other error Parameters · [in] timer: Timer handle created by gptimer_new_timer() · [in] value: Count value to be set
esp_err_t gptimer_get_raw_count(gptimer_handle_t timer, uint64_t *value) Get GPTimer raw count value.
Note With the raw count value and the resolution set in the gptimer_config_t, you can convert the count value into seconds.
Note This function is allowed to run within ISR context Note This function is allowed to be executed when Cache is disabled, by enabling CON-
FIG_GPTIMER_CTRL_FUNC_IN_IRAM Return
· ESP_OK: Get GPTimer raw count value successfully · ESP_ERR_INVALID_ARG: Get GPTimer raw count value failed because of invalid argument · ESP_FAIL: Get GPTimer raw count value failed because of other error Parameters · [in] timer: Timer handle created by gptimer_new_timer() · [out] value: Returned GPTimer count value
esp_err_t gptimer_register_event_callbacks(gptimer_handle_t timer, const gptimer_event_callbacks_t *cbs, void *user_data)

Espressif Systems

544

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Set callbacks for GPTimer.

Note The user registered callbacks are expected to be runnable within ISR context Return
· ESP_OK: Set event callbacks successfully · ESP_ERR_INVALID_ARG: Set event callbacks failed because of invalid argument · ESP_FAIL: Set event callbacks failed because of other error Parameters · [in] timer: Timer handle created by gptimer_new_timer() · [in] cbs: Group of callback functions · [in] user_data: User data, which will be passed to callback functions directly

esp_err_t gptimer_set_alarm_action(gptimer_handle_t timer, const gptimer_alarm_config_t *config)
Set alarm event actions for GPTimer.

Note This function is allowed to run within ISR context Note This function is allowed to be executed when Cache is disabled, by enabling CON-
FIG_GPTIMER_CTRL_FUNC_IN_IRAM Return
· ESP_OK: Set alarm action for GPTimer successfully · ESP_ERR_INVALID_ARG: Set alarm action for GPTimer failed because of invalid argument · ESP_FAIL: Set alarm action for GPTimer failed because of other error Parameters · [in] timer: Timer handle created by gptimer_new_timer() · [in] config: Alarm configuration, especially, set config to NULL means disabling the alarm
function

esp_err_t gptimer_start(gptimer_handle_t timer) Start GPTimer.

Note This function is allowed to run within ISR context Note This function is allowed to be executed when Cache is disabled, by enabling
FIG_GPTIMER_CTRL_FUNC_IN_IRAM Return
· ESP_OK: Start GPTimer successfully · ESP_ERR_INVALID_ARG: Start GPTimer failed because of invalid argument · ESP_ERR_INVALID_STATE: Start GPTimer failed because the timer is not in stop state · ESP_FAIL: Start GPTimer failed because of other error Parameters · [in] timer: Timer handle created by gptimer_new_timer()

CON-

esp_err_t gptimer_stop(gptimer_handle_t timer) Stop GPTimer.

Note This function is allowed to run within ISR context Note This function is allowed to be executed when Cache is disabled, by enabling
FIG_GPTIMER_CTRL_FUNC_IN_IRAM Return
· ESP_OK: Stop GPTimer successfully · ESP_ERR_INVALID_ARG: Stop GPTimer failed because of invalid argument · ESP_ERR_INVALID_STATE: Stop GPTimer failed because the timer is not in start state · ESP_FAIL: Stop GPTimer failed because of other error Parameters · [in] timer: Timer handle created by gptimer_new_timer()

CON-

Structures struct gptimer_alarm_event_data_t
GPTimer alarm event data.

Espressif Systems

545

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Public Members
uint64_t count_value Current count value
uint64_t alarm_value Current alarm value
struct gptimer_event_callbacks_t Group of supported GPTimer callbacks.
Note The callbacks are all running under ISR environment

Public Members
gptimer_alarm_cb_t on_alarm Timer alarm callback
struct gptimer_config_t General Purpose Timer configuration.

Public Members
gptimer_clock_source_t clk_src GPTimer clock source
gptimer_count_direction_t direction Count direction
uint32_t resolution_hz Counter resolution (working frequency) in Hz, hence, the step size of each count tick equals to (1 / resolution_hz) seconds
uint32_t intr_shared : 1 Set true, the timer interrupt number can be shared with other peripherals
struct gptimer_alarm_config_t General Purpose Timer alarm configuration.

Public Members
uint64_t alarm_count Alarm target count value
uint64_t reload_count Alarm reload count value, effect only when auto_reload_on_alarm is set to true
uint32_t auto_reload_on_alarm : 1 Reload the count value by hardware, immediately at the alarm event

Type Definitions

typedef struct gptimer_t *gptimer_handle_t

Type of General Purpose Timer handle.

typedef bool (*gptimer_alarm_cb_t)(gptimer_handle_t

timer,

const

gpti-

Timer alarm callback prototype.

mer_alarm_event_data_t *edata, void *user_ctx)

Return Whether a high priority task has been waken up by this function Parameters
· [in] timer: Timer handle created by gptimer_new_timer() · [in] edata: Alarm event data, fed by driver

Espressif Systems

546

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· [in] user_ctx: User data, passed from gptimer_register_event_callbacks()

Header File · components/hal/include/hal/timer_types.h

Enumerations enum gptimer_clock_source_t
GPTimer clock source.
Note The clock source listed here is not supported on all targets Note User should select the clock source based on real requirements:

GPTimer clock source GPTIMER_CLK_SRC_APB GPTIMER_CLK_SRC_XTAL

Features High resolution
Medium resolution, high accuracy

Power Management ESP_PM_APB_FREQ_MAX lock No PM lock

Values:
GPTIMER_CLK_SRC_APB Select APB as the source clock
GPTIMER_CLK_SRC_XTAL Select XTAL as the source clock
enum gptimer_count_direction_t GPTimer count direction.
Values:
GPTIMER_COUNT_DOWN Decrease count value
GPTIMER_COUNT_UP Increase count value

2.3.4 Dedicated GPIO
Overview
The dedicated GPIO is designed for CPU interaction with GPIO matrix and IO MUX. Any GPIO that is configured as odedicatedpcan be access by CPU instructions directly, which makes it easy to achieve a high GPIO flip speed, and simulate serial/parallel interface in a bit-banging way. As toggling a GPIO in this oCPU Dedicatedpway costs few overhead, it would be great for cases like performance measurement using an oscilloscope.

Create/Destroy GPIO Bundle
A GPIO bundle is a group of GPIOs, which can be manipulated at the same time in one CPU cycle. The maximal number of GPIOs that a bundle can contain is limited by each CPU. Whatns more, the GPIO bundle has a strong relevance to the CPU which it derives from. Any operations on the GPIO bundle should be put inside a task which is running on the same CPU core to the GPIO bundle belongs to. Likewise, only those ISRs who are installed on the same CPU core are allowed to do operations on that GPIO bundle.
Note: Dedicated GPIO is more of a CPU peripheral, so it has a strong relationship with CPU core. Itns highly recommended to install and operate GPIO bundle in a pin-to-core task. For example, if GPIOA is connected to CPU0, and the dedicated GPIO instruction is issued from CPU1, then itns impossible to control GPIOA.

Espressif Systems

547

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
To install a GPIO bundle, one needs to call dedic_gpio_new_bundle() to allocate the software resources and connect the dedicated channels to user selected GPIOs. Configurations for a GPIO bundle are covered in dedic_gpio_bundle_config_t structure:
· gpio_array: An array that contains GPIO number. · array_size: Element number of gpio_array. · flags: Extra flags to control the behavior of GPIO Bundle.
­ in_en and out_en are used to select whether to enable the input and output function (note, they can be enabled together).
­ in_invert and out_invert are used to select whether to invert the GPIO signal.
The following code shows how to install a output only GPIO bundle:
// configure GPIO const int bundleA_gpios[] = {0, 1}; gpio_config_t io_conf = {
.mode = GPIO_MODE_OUTPUT, }; for (int i = 0; i < sizeof(bundleA_gpios) / sizeof(bundleA_gpios[0]); i++) {
io_conf.pin_bit_mask = 1ULL << bundleA_gpios[i]; gpio_config(&io_conf); } // Create bundleA, output only dedic_gpio_bundle_handle_t bundleA = NULL; dedic_gpio_bundle_config_t bundleA_config = { .gpio_array = bundleA_gpios, .array_size = sizeof(bundleA_gpios) / sizeof(bundleA_gpios[0]), .flags = {
.out_en = 1, }, }; ESP_ERROR_CHECK(dedic_gpio_new_bundle(&bundleA_config, &bundleA));
To uninstall the GPIO bundle, one needs to call dedic_gpio_del_bundle().
Note: dedic_gpio_new_bundle() doesnnt cover any GPIO pad configuration (e.g. pull up/down, drive ability, output/input enable), so before installing a dedicated GPIO bundle, you have to configure the GPIO separately using GPIO driver API (e.g. gpio_config()). For more information about GPIO driver, please refer to GPIO API Reference.

GPIO Bundle Operations
Operations Write to GPIOs in the bundle by mask Read the value that input to bundle Read the value that output from bundle

Functions dedic_gpio_bundle_write() dedic_gpio_bundle_read_out() dedic_gpio_bundle_read_in()

Note: The functions above just wrap the customized instructions defined for ESP32-S3, for the details of those instructions, please refer to ESP32-S3 Technical Reference Manual > IO MUX and GPIO Matrix (GPIO, IO_MUX) [PDF].

Manipulate GPIOs by Writing Assembly Code
For advanced users, they can always manipulate the GPIOs by writing assembly code or invoking CPU Low Level APIs. The usual procedure could be:

Espressif Systems

548

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

1. Allocate a GPIO bundle: dedic_gpio_new_bundle() 2. Query the mask occupied by that bundle: dedic_gpio_get_out_mask()
dedic_gpio_get_in_mask() 3. Call CPU LL apis (e.g. cpu_ll_write_dedic_gpio_mask) or write assembly code with that mask 4. The fasted way of toggling IO is to use the dedicated oset/clearpinstructions:

or/and

CPU Arch Xtensa
RISCV

Set bits of GPIO
set_bit_gpio_out imm[7:0] csrrsi rd, csr, imm[4:0]

Clear bits of GPIO clr_bit_gpio_out imm[7:0] csrrci rd, csr, imm[4:0]

Remarks
immediate value width depends on the number of dedicated GPIO channels can only control the lowest 4 GPIO channels

For details of supported dedicated GPIO instructions, please refer to ESP32-S3 Technical Reference Manual > IO MUX and GPIO Matrix (GPIO, IO_MUX) [PDF]. The supported dedicated CPU instructions are also wrapped inside soc/cpu_ll.h as helper inline functions.

Note: Writing assembly code in application could make your code hard to port between targets, because those customized instructions are not guaranteed to remain the same format on different targets.

Application Example Matrix keyboard example based on dedicated GPIO: peripherals/gpio/matrix_keyboard.

API Reference
Header File · components/driver/include/driver/dedic_gpio.h

Functions esp_err_t dedic_gpio_get_out_mask(dedic_gpio_bundle_handle_t bundle, uint32_t *mask)
Get allocated channel mask.

Return · ESP_OK: Get channel mask successfully · ESP_ERR_INVALID_ARG: Get channel mask failed because of invalid argument · ESP_FAIL: Get channel mask failed because of other error
Note Each bundle should have at least one mask (in or/and out), based on bundle configuration. Note With the returned mask, user can directly invoke LL function likeocpu_ll_write_dedic_gpio_maskpor
write assembly code with dedicated GPIO instructions, to get better performance on GPIO manipulation. Parameters
· [in] bundle: Handle of GPIO bundle that returned from odedic_gpio_new_bundlep · [out] mask: Returned mask value for on specific direction (in or out) esp_err_t dedic_gpio_get_in_mask(dedic_gpio_bundle_handle_t bundle, uint32_t *mask)

esp_err_t dedic_gpio_new_bundle(const

dedic_gpio_bundle_config_t

dedic_gpio_bundle_handle_t *ret_bundle) Create GPIO bundle and return the handle.

*config,

Return · ESP_OK: Create GPIO bundle successfully · ESP_ERR_INVALID_ARG: Create GPIO bundle failed because of invalid argument · ESP_ERR_NO_MEM: Create GPIO bundle failed because of no capable memory · ESP_ERR_NOT_FOUND: Create GPIO bundle failed because of no enough continuous dedicated channels

Espressif Systems

549

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_FAIL: Create GPIO bundle failed because of other error Note One has to enable at least input or output mode in oconfigpparameter. Parameters
· [in] config: Configuration of GPIO bundle · [out] ret_bundle: Returned handle of the new created GPIO bundle

esp_err_t dedic_gpio_del_bundle(dedic_gpio_bundle_handle_t bundle) Destory GPIO bundle.

Return · ESP_OK: Destory GPIO bundle successfully · ESP_ERR_INVALID_ARG: Destory GPIO bundle failed because of invalid argument · ESP_FAIL: Destory GPIO bundle failed because of other error
Parameters · [in] bundle: Handle of GPIO bundle that returned from odedic_gpio_new_bundlep

void dedic_gpio_bundle_write(dedic_gpio_bundle_handle_t bundle, uint32_t mask, uint32_t

Write value to GPIO bundle.

value)

Note The mask is seen from the view of GPIO bundle. For example, bundleA contains [GPIO10, GPIO12, GPIO17], to set GPIO17 individually, the mask should be 0x04.
Note For performance reasons, this function doesnnt check the validity of any parameters, and is placed in IRAM.
Parameters · [in] bundle: Handle of GPIO bundle that returned from odedic_gpio_new_bundlep · [in] mask: Mask of the GPIOs to be written in the given bundle · [in] value: Value to write to given GPIO bundle, low bit represents low member in the bundle

uint32_t dedic_gpio_bundle_read_out(dedic_gpio_bundle_handle_t bundle) Read the value that output from the given GPIO bundle.

Return Value that output from the GPIO bundle, low bit represents low member in the bundle Note For performance reasons, this function doesnnt check the validity of any parameters, and is placed in
IRAM. Parameters
· [in] bundle: Handle of GPIO bundle that returned from odedic_gpio_new_bundlep

uint32_t dedic_gpio_bundle_read_in(dedic_gpio_bundle_handle_t bundle) Read the value that input to the given GPIO bundle.

Return Value that input to the GPIO bundle, low bit represents low member in the bundle Note For performance reasons, this function doesnnt check the validity of any parameters, and is placed in
IRAM. Parameters
· [in] bundle: Handle of GPIO bundle that returned from odedic_gpio_new_bundlep

Structures struct dedic_gpio_bundle_config_t
Type of Dedicated GPIO bundle configuration.

Public Members
const int *gpio_array Array of GPIO numbers, gpio_array[0] ~ gpio_array[size-1] <=> low_dedic_channel_num ~ high_dedic_channel_num
size_t array_size Number of GPIOs in gpio_array
unsigned int in_en : 1 Enable input

Espressif Systems

550

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
unsigned int in_invert : 1 Invert input signal
unsigned int out_en : 1 Enable output
unsigned int out_invert : 1 Invert output signal
struct dedic_gpio_bundle_config_t::[anonymous] flags Flags to control specific behaviour of GPIO bundle
Type Definitions typedef struct dedic_gpio_bundle_t *dedic_gpio_bundle_handle_t
Type of Dedicated GPIO bundle.
2.3.5 Hash-based Message Authentication Code (HMAC)
The HMAC (Hash-based Message Authentication Code) module provides hardware acceleration for SHA256HMAC generation using a key burned into an eFuse block. HMACs work with pre-shared secret keys and provide authenticity and integrity to a message. For more detailed information on the application workflow and the HMAC calculation process, see ESP32-S3 Technical Reference Manual > HMAC Accelerator (HMAC) [PDF].
Generalized Application Scheme
Let there be two parties, A and B. They want to verify the authenticity and integrity of messages sent between each other. Before they can start sending messages, they need to exchange the secret key via a secure channel. To verify Ans messages, B can do the following:
· A calculates the HMAC of the message it wants to send. · A sends the message and the HMAC to B. · B calculates HMAC of the received message itself. · B checks wether the received and calculated HMACs match. If they do match, the message is authentic. However, the HMAC itself isnnt bound to this use case. It can also be used for challenge-response protocols supporting HMAC or as a key input for further security modules (see below), etc.
HMAC on the ESP32-S3
On the ESP32-S3, the HMAC module works with a secret key burnt into the eFuses. This eFuse key can be made completely inaccessible for any resources outside the cryptographic modules, thus avoiding key leakage. Furthermore, the ESP32-S3 has three different application scenarios for its HMAC module:
1. HMAC is generated for software use 2. HMAC is used as a key for the Digital Signature (DS) module 3. HMAC is used for enabling the soft-disabled JTAG interface The first mode is also called Upstream mode, while the last two modes are also called Downstream modes.
eFuse Keys for HMAC Six physical eFuse blocks can be used as keys for the HMAC module: block 4 up to block 9. The enum hmac_key_id_t in the API maps them to HMAC_KEY0 lHMAC_KEY5. Each key has a corresponding eFuse parameter key purpose determining for which of the three HMAC application scenarios (see below) the key may be used:

Espressif Systems

551

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Key Purpose 8 7 6 5

Application Scenario HMAC generated for software use HMAC used as a key for the Digital Signature (DS) module HMAC used for enabling the soft-disabled JTAG interface HMAC both as a key for the DS module and for enabling JTAG

This is to prevent the usage of a key for a different function than originally intended.
To calculate an HMAC, the software has to provide the ID of the key block containing the secret key as well as the key purpose (see ESP32-S3 Technical Reference Manual > eFuse Controller (eFuse) [PDF]). Before the HMAC key calculation, the HMAC module looks up the purpose of the provided key block. The calculation only proceeds if the provided key purpose matches the purpose stored in the eFuses of the key block provided by the ID.

HMAC Generation for Software Key Purpose value: 8
In this case, the HMAC is given out to the software (e.g. to authenticate a message).
The API to calculate the HMAC is esp_hmac_calculate(). Only the message, message length and the eFuse key block ID have to be provided to that function. The rest, like setting the key purpose, is done automatically.

HMAC for Digital Signature Key Purpose values: 7, 5
The HMAC can be used as a key derivation function to decrypt private key parameters which are used by the Digital Signature module. A standard message is used by the hardware in that case. The user only needs to provide the eFuse key block and purpose on the HMAC side (additional parameters are required for the Digital Signature component in that case). Neither the key nor the actual HMAC are ever exposed to outside the HMAC module and DS component. The calculation of the HMAC and its hand-over to the DS component happen internally.
For more details, see ESP32-S3 Technical Reference Manual > Digital Signature (DS) [PDF].

HMAC for Enabling JTAG Key Purpose values: 6, 5
The third application is using the HMAC as a key to enable JTAG if it was soft-disabled before. Following is the procedure to re-enable the JTAG
Setup
1. Generate a 256-bit HMAC secret key to use for JTAG re-enable. 2. Write the key to an eFuse block with key purpose HMAC_DOWN_ALL (5) or HMAC_DOWN_JTAG (6).
This can be done using the ets_efuse_write_key() function in the firmware or using espefuse.py from the host. 3. Configure the eFuse key block to be read protected using the esp_efuse_set_read_protect(), so that software
cannot read back the value. 4. Burn the osoft JTAG disablepbit by esp_efuse_write_field_bit(ESP_EFUSE_SOFT_DIS_JTAG). This will
permanently disable JTAG unless the correct key value is provided by software.
JTAG enable
1. The key to re-enable JTAG is the output of the HMAC-SHA256 function using the secret key in eFuse and 32 0x00 bytes as the message.
2. Pass this key value when calling the esp_hmac_jtag_enable() function from the firmware. 3. To re-disable JTAG in the firmware, reset the system or call esp_hmac_jtag_disable().
For more details, see ESP32-S3 Technical Reference Manual > HMAC Accelerator (HMAC) [PDF].

Application Outline
Following code is an outline of how to set an eFuse key and then use it to calculate an HMAC for software usage. We use ets_efuse_write_key to set physical key block 4 in the eFuse for the HMAC module together with its purpose. ETS_EFUSE_KEY_PURPOSE_HMAC_UP (8) means that this key can only be used for HMAC generation for software usage:

Espressif Systems

552

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

#include "esp32s3/rom/efuse.h"
const uint8_t key_data[32] = { ... };
int ets_status = ets_efuse_write_key(ETS_EFUSE_BLOCK_KEY4, ETS_EFUSE_KEY_PURPOSE_HMAC_UP, key_data, sizeof(key_data));
if (ets_status == ESP_OK) { // written key
} else { // writing key failed, maybe written already
}
Now we can use the saved key to calculate an HMAC for software usage.
#include "esp_hmac.h"
uint8_t hmac[32];
const char *message = "Hello, HMAC!"; const size_t msg_len = 12;
esp_err_t result = esp_hmac_calculate(HMAC_KEY4, message, msg_len, hmac);
if (result == ESP_OK) { // HMAC written to hmac now
} else { // failure calculating HMAC
}
API Reference
Header File
· components/esp_hw_support/include/soc/esp32s3/esp_hmac.h
Functions esp_err_t esp_hmac_calculate(hmac_key_id_t key_id, const void *message, size_t message_len,
uint8_t *hmac) Calculate the HMAC of a given message.
Calculate the HMAC hmac of a given message message with length message_len. SHA256 is used for the calculation (fixed on ESP32S3).
Note Uses the HMAC peripheral in oupstreampmode. Return
· ESP_OK, if the calculation was successful, · ESP_ERR_INVALID_ARG if message or hmac is a nullptr or if key_id out of range · ESP_FAIL, if the hmac calculation failed Parameters · key_id: Determines which of the 6 key blocks in the efuses should be used for the HMAC cal-
cuation. The corresponding purpose field of the key block in the efuse must be set to the HMAC upstream purpose value. · message: the message for which to calculate the HMAC · message_len: message length · [out] hmac: the hmac result; the buffer behind the provided pointer must be 32 bytes long esp_err_t esp_hmac_jtag_enable(hmac_key_id_t key_id, const uint8_t *token) Use HMAC peripheral in Downstream mode to re-enable the JTAG, if it is not permanently disabled by HW.

Espressif Systems

553

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
In downstream mode, HMAC calculations performed by peripheral are used internally and not provided back to user.
Return · ESP_OK, if the calculation was successful, if the calculated HMAC value matches with provided token, JTAG will be re-enable otherwise JTAG will remain disabled. Return value does not indicate the JTAG status. · ESP_FAIL, if the hmac calculation failed or JTAG is permanently disabled by EFUSE_HARD_DIS_JTAG eFuse parameter. · ESP_ERR_INVALID_ARG, invalid input arguments
Parameters · key_id: Determines which of the 6 key blocks in the efuses should be used for the HMAC calculation. The corresponding purpose field of the key block in the efuse must be set to HMAC downstream purpose. · token: Pre calculated HMAC value of the 32-byte 0x00 using SHA-256 and the known private HMAC key. The key is already programmed to a eFuse key block. The key block number is provided as the first parameter to this function.
esp_err_t esp_hmac_jtag_disable(void) Disable the JTAG which might be enabled using the HMAC downstream mode. This function just clears the result generated by calling esp_hmac_jtag_enable() API.
Return · ESP_OK return ESP_OK after writing the HMAC_SET_INVALIDATE_JTAG_REG with value 1.
Enumerations enum hmac_key_id_t
The possible efuse keys for the HMAC peripheral
Values:
HMAC_KEY0 = 0
HMAC_KEY1
HMAC_KEY2
HMAC_KEY3
HMAC_KEY4
HMAC_KEY5
HMAC_KEY_MAX
2.3.6 Digital Signature (DS)
The Digital Signature (DS) module provides hardware acceleration of signing messages based on RSA. It uses preencrypted parameters to calculate a signature. The parameters are encrypted using HMAC as a key-derivation function. In turn, the HMAC uses eFuses as input key. The whole process happens in hardware so that neither the decryption key for the RSA parameters nor the input key for the HMAC key derivation function can be seen by the software while calculating the signature.
For more detailed information on the hardware involved in signature calculation and the registers used, see ESP32-S3 Technical Reference Manual > Digital Signature (DS) [PDF].
Private Key Parameters
The private key parameters for the RSA signature are stored in flash. To prevent unauthorized access, they are AESencrypted. The HMAC module is used as a key-derivation function to calculate the AES encryption key for the private

Espressif Systems

554

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
key parameters. In turn, the HMAC module uses a key from the eFuses key block which can be read-protected to prevent unauthorized access as well. Upon signature calculation invocation, the software only specifies which eFuse key to use, the corresponding eFuse key purpose, the location of the encrypted RSA parameters and the message.
Key Generation
Both the HMAC key and the RSA private key have to be created and stored before the DS peripheral can be used. This needs to be done in software on the ESP32-S3 or alternatively on a host. For this context, the IDF provides esp_efuse_write_block() to set the HMAC key and esp_hmac_calculate() to encrypt the private RSA key parameters. You can find instructions on how to calculate and assemble the private key parameters in ESP32-S3 Technical Reference Manual > Digital Signature (DS) [PDF].
Signature Calculation with IDF
For more detailed information on the workflow and the registers used, see ESP32-S3 Technical Reference Manual > Digital Signature (DS) [PDF]. Three parameters need to be prepared to calculate the digital signature:
1. the eFuse key block ID which is used as key for the HMAC, 2. the location of the encrypted private key parameters, 3. and the message to be signed. Since the signature calculation takes some time, there are two possible API versions to use in IDF. The first one is esp_ds_sign() and simply blocks until the calculation is finished. If software needs to do something else during the calculation, esp_ds_start_sign() can be called, followed by periodic calls to esp_ds_is_busy() to check when the calculation has finished. Once the calculation has finished, esp_ds_finish_sign() can be called to get the resulting signature.
Note: Note that this is only the basic DS building block, the message length is fixed. To create signatures of arbitrary messages, the input is normally a hash of the actual message, padded up to the required length. An API to do this is planned in the future.

Configure the DS peripheral for a TLS connection
The DS peripheral on ESP32-S3 chip must be configured before it can be used for a TLS connection. The configuration involves the following steps -
1) Randomly generate a 256 bit value called the Initialization Vector (IV). 2) Randomly generate a 256 bit value called the HMAC_KEY. 3) Calculate the encrypted private key paramters from the client private key (RSA) and the parameters generated
in the above steps. 4) Then burn the 256 bit HMAC_KEY on the efuse, which can only be read by the DS peripheral.
For more details, see ESP32-S3 Technical Reference Manual > Digital Signature (DS) [PDF].
To configure the DS peripheral for development purposes, you can use the python script configure_ds.py. More details about the configure_ds.py script can be found at mqtt example README .
The encrypted private key parameters obtained after the DS peripheral configuration are then to be kept in flash. Furthermore, they are to be passed to the DS peripheral which makes use of those parameters for the Digital Signature operation. Non Volatile Storage can be used to store the encrypted private key parameters in flash. The script configure_ds.py creates an NVS partition for the encrypted private key parameters. Then the script flashes this partition onto the ESP32-S3. The application then needs to read the DS data from NVS, which can be done with the function esp_read_ds_data_from_nvs in file ssl_mutual_auth/main/app_main.c

Espressif Systems

555

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

The process of initializing the DS peripheral and then performing the Digital Signature operation is done internally with help of ESP-TLS. Please refer to Digital Signature with ESP-TLS in ESP-TLS for more details. As mentioned in the ESP-TLS documentation, the application only needs to provide the encrypted private key parameters to the esp_tls context (as ds_data), which internally performs all necessary operations for initializing the DS peripheral and then performing the DS operation.

Example for SSL Mutual Authentication using DS
The example ssl_ds shows how to use the DS peripheral for mutual authentication. The example uses mqtt_client (Implemented through ESP-MQTT) to connect to broker test.mosquitto.org using ssl transport with mutual authentication. The ssl part is internally performed with ESP-TLS. See example README for more details.

API Reference
Header File · components/esp_hw_support/include/soc/esp32s3/esp_ds.h

Functions esp_err_t esp_ds_sign(const void *message, const esp_ds_data_t *data, hmac_key_id_t key_id, void
*signature) Sign the message.

This function is a wrapper around esp_ds_finish_sign() and esp_ds_start_sign(), so do not use them in parallel. It blocks until the signing is finished and then returns the signature.

Note This function locks the HMAC, SHA, AES and RSA components during its entire execution time.

Return

· ESP_OK if successful, the signature was written to the parameter signature.

· ESP_ERR_INVALID_ARG if one of the parameters is NULL or data->rsa_length is too long or 0

· ESP_ERR_HW_CRYPTO_DS_HMAC_FAIL if there was an HMAC failure during retrieval of

the decryption key

· ESP_ERR_NO_MEM if there hasnnt been enough memory to allocate the context object

· ESP_ERR_HW_CRYPTO_DS_INVALID_KEY if therens a problem with passing the HMAC

key to the DS component

· ESP_ERR_HW_CRYPTO_DS_INVALID_DIGEST if the message digest didnnt match; the sig-

nature is invalid.

· ESP_ERR_HW_CRYPTO_DS_INVALID_PADDING if the message padding is incorrect, the sig-

nature can be read though since the message digest matches.

Parameters

· message: the message to be signed; its length is determined by data->rsa_length

· data: the encrypted signing key data (AES encrypted RSA key + IV)

· key_id: the HMAC key ID determining the HMAC key of the HMAC which will be used to

decrypt the signing key data

· signature: the destination of the signature, should be (data->rsa_length + 1)*4 bytes long

esp_err_t esp_ds_start_sign(const void *message, const esp_ds_data_t *data, hmac_key_id_t

Start the signing process.

key_id, esp_ds_context_t **esp_ds_ctx)

This function yields a context object which needs to be passed to esp_ds_finish_sign() to finish the signing process.

Note This function locks the HMAC, SHA, AES and RSA components, so the user has to ensure to call esp_ds_finish_sign() in a timely manner.
Return · ESP_OK if successful, the ds operation was started now and has to be finished with esp_ds_finish_sign() · ESP_ERR_INVALID_ARG if one of the parameters is NULL or data->rsa_length is too long or 0

Espressif Systems

556

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_ERR_HW_CRYPTO_DS_HMAC_FAIL if there was an HMAC failure during retrieval of the decryption key
· ESP_ERR_NO_MEM if there hasnnt been enough memory to allocate the context object · ESP_ERR_HW_CRYPTO_DS_INVALID_KEY if therens a problem with passing the HMAC
key to the DS component Parameters
· message: the message to be signed; its length is determined by data->rsa_length · data: the encrypted signing key data (AES encrypted RSA key + IV) · key_id: the HMAC key ID determining the HMAC key of the HMAC which will be used to
decrypt the signing key data · esp_ds_ctx: the context object which is needed for finishing the signing process later
bool esp_ds_is_busy(void) Return true if the DS peripheral is busy, otherwise false.
Note Only valid if esp_ds_start_sign() was called before.
esp_err_t esp_ds_finish_sign(void *signature, esp_ds_context_t *esp_ds_ctx) Finish the signing process.
Return · ESP_OK if successful, the ds operation has been finished and the result is written to signature. · ESP_ERR_INVALID_ARG if one of the parameters is NULL · ESP_ERR_HW_CRYPTO_DS_INVALID_DIGEST if the message digest didnnt match; the signature is invalid. · ESP_ERR_HW_CRYPTO_DS_INVALID_PADDING if the message padding is incorrect, the signature can be read though since the message digest matches.
Parameters · signature: the destination of the signature, should be (data->rsa_length + 1)*4 bytes long · esp_ds_ctx: the context object retreived by esp_ds_start_sign()
esp_err_t esp_ds_encrypt_params(esp_ds_data_t *data, const void *iv, const esp_ds_p_data_t *p_data, const void *key)
Encrypt the private key parameters.
Return · ESP_OK if successful, the ds operation has been finished and the result is written to signature. · ESP_ERR_INVALID_ARG if one of the parameters is NULL or p_data->rsa_length is too long
Parameters · data: Output buffer to store encrypted data, suitable for later use generating signatures. The allocated memory must be in internal memory and word aligned since itns filled by DMA. Both is asserted at run time. · iv: Pointer to 16 byte IV buffer, will be copied into mdatan. Should be randomly generated bytes each time. · p_data: Pointer to input plaintext key data. The expectation is this data will be deleted after this process is done and mdatanis stored. · key: Pointer to 32 bytes of key data. Type determined by key_type parameter. The expectation is the corresponding HMAC key will be stored to efuse and then permanently erased.

Structures struct esp_digital_signature_data
Encrypted private key data. Recommended to store in flash in this format.
Note This struct has to match to one from the ROM code! This documentation is mostly taken from there.

Public Members
esp_digital_signature_length_t rsa_length RSA LENGTH register parameters (number of words in RSA key & operands, minus one). Max value 127 (for RSA 4096).

Espressif Systems

557

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
This value must match the length field encrypted and stored in mcn, or invalid results will be returned. (The DS peripheral will always use the value in mcn, not this value, so an attacker cannt alter the DS peripheral results this way, it will just truncate or extend the message and the resulting signature in software.) Note In IDF, the enum type length is the same as of type unsigned, so they can be used interchangably.
See the ROM code for the original declaration of struct ets_ds_data_t. uint8_t iv[ESP_DS_IV_LEN]
IV value used to encrypt mcn uint8_t c[ESP_DS_C_LEN]
Encrypted Digital Signature parameters. Result of AES-CBC encryption of plaintext values. Includes an encrypted message digest. struct esp_ds_p_data_t Plaintext parameters used by Digital Signature. Not used for signing with DS peripheral, but can be encrypted in-device by calling esp_ds_encrypt_params() Note This documentation is mostly taken from the ROM code.
Public Members
uint32_t Y[(4096) / 32] RSA exponent.
uint32_t M[(4096) / 32] RSA modulus.
uint32_t Rb[(4096) / 32] RSA r inverse operand.
uint32_t M_prime RSA M prime operand.
esp_digital_signature_length_t length RSA length.
Macros ESP32S3_ERR_HW_CRYPTO_DS_HMAC_FAIL
HMAC peripheral problem ESP32S3_ERR_HW_CRYPTO_DS_INVALID_KEY
given HMAC key isnnt correct, HMAC peripheral problem ESP32S3_ERR_HW_CRYPTO_DS_INVALID_DIGEST
message digest check failed, result is invalid ESP32S3_ERR_HW_CRYPTO_DS_INVALID_PADDING
padding check failed, but result is produced anyway and can be read ESP_DS_IV_LEN ESP_DS_C_LEN
Type Definitions typedef struct esp_ds_context esp_ds_context_t typedef struct esp_digital_signature_data esp_ds_data_t
Encrypted private key data. Recommended to store in flash in this format. Note This struct has to match to one from the ROM code! This documentation is mostly taken from there.

Espressif Systems

558

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Enumerations enum esp_digital_signature_length_t
Values: ESP_DS_RSA_1024 = (1024 / 32) - 1 ESP_DS_RSA_2048 = (2048 / 32) - 1 ESP_DS_RSA_3072 = (3072 / 32) - 1 ESP_DS_RSA_4096 = (4096 / 32) - 1
2.3.7 Inter-Integrated Circuit (I2C)
Overview
I2C is a serial, synchronous, half-duplex communication protocol that allows co-existence of multiple masters and slaves on the same bus. The I2C bus consists of two lines: serial data line (SDA) and serial clock (SCL). Both lines require pull-up resistors. With such advantages as simplicity and low manufacturing cost, I2C is mostly used for communication of low-speed peripheral devices over short distances (within one foot). ESP32-S3 has 2 I2C controller (also referred to as port), responsible for handling communications on the I2C bus. A single I2C controller can operate as master or slave.
Driver Features
I2C driver governs communications of devices over the I2C bus. The driver supports the following features: · Reading and writing bytes in Master mode · Slave mode · Reading and writing to registers which are in turn read/written by the master
Driver Usage
The following sections describe typical steps of configuring and operating the I2C driver: 1. Configuration - set the initialization parameters (master or slave mode, GPIO pins for SDA and SCL, clock speed, etc.) 2. Install Driver- activate the driver on one of the two I2C controllers as a master or slave 3. Depending on whether you configure the driver for a master or slave, choose the appropriate item a) Communication as Master - handle communications (master) b) Communication as Slave - respond to messages from the master (slave) 4. Interrupt Handling - configure and service I2C interrupts 5. Customized Configuration - adjust default I2C communication parameters (timings, bit order, etc.) 6. Error Handling - how to recognize and handle driver configuration and communication errors 7. Delete Driver- release resources used by the I2C driver when communication ends
Configuration To establish I2C communication, start by configuring the driver. This is done by setting the parameters of the structure i2c_config_t:
· Set I2C mode of operation - slave or master from i2c_mode_t · Configure communication pins
­ Assign GPIO pins for SDA and SCL signals ­ Set whether to enable ESP32-S3ns internal pull-ups · (Master only) Set I2C clock speed · (Slave only) Configure the following ­ Whether to enable 10 bit address mode

Espressif Systems

559

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

­ Define slave address
After that, initialize the configuration for a given I2C port. For this, call the function i2c_param_config() and pass to it the port number and the structure i2c_config_t.
Configuration example (master):

int i2c_master_port = 0;

i2c_config_t conf = {

.mode = I2C_MODE_MASTER,

.sda_io_num = I2C_MASTER_SDA_IO,

// select GPIO specific to your

project

.sda_pullup_en = GPIO_PULLUP_ENABLE,

.scl_io_num = I2C_MASTER_SCL_IO,

// select GPIO specific to your

project

.scl_pullup_en = GPIO_PULLUP_ENABLE,

.master.clk_speed = I2C_MASTER_FREQ_HZ, // select frequency specific to your

project

// .clk_flags = 0,

/*!< Optional, you can use I2C_SCLK_SRC_FLAG_*

flags to choose i2c source clock here. */

};

Configuration example (slave):
int i2c_slave_port = I2C_SLAVE_NUM; i2c_config_t conf_slave = {
.sda_io_num = I2C_SLAVE_SDA_IO, project
.sda_pullup_en = GPIO_PULLUP_ENABLE, .scl_io_num = I2C_SLAVE_SCL_IO, project .scl_pullup_en = GPIO_PULLUP_ENABLE, .mode = I2C_MODE_SLAVE, .slave.addr_10bit_en = 0, .slave.slave_addr = ESP_SLAVE_ADDR, };

// select GPIO specific to your // select GPIO specific to your
// address of your project

At this stage, i2c_param_config() also sets a few other I2C configuration parameters to default values that are defined by the I2C specification. For more details on the values and how to modify them, see Customized Configuration.

Source Clock Configuration Clock sources allocator is added for supporting different clock sources. The clock allocator will choose one clock source that meets all the requirements of frequency and capability (as requested in i2c_config_t::clk_flags).
When i2c_config_t::clk_flags is 0, the clock allocator will select only according to the desired frequency. If no special capabilities are needed, such as APB, you can configure the clock allocator to select the source clock only according to the desired frequency. For this, set i2c_config_t::clk_flags to 0. For clock characteristics, see the table below.
Note: A clock is not a valid option, if it doesnnt meet the requested capabilities, i.e. any bit of requested capabilities (clk_flags) is 0 in the clockns capabilities.

Espressif Systems

560

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Table 2: Characteristics of ESP32-S3 clock sources
Clock Clock MAX freq for SCL name fre-
quency XTAL 40 2 MHz clock MHz RTC 20 1 MHz clock MHz

Clock capabilities
/ I2C_SCLK_SRC_FLAG_AWARE_DFS, I2C_SCLK_SRC_FLAG_LIGHT_SLEEP

Explanations for i2c_config_t::clk_flags are as follows:
1. I2C_SCLK_SRC_FLAG_AWARE_DFS: Clockns baud rate will not change while APB clock is changing. 2. I2C_SCLK_SRC_FLAG_LIGHT_SLEEP: It supports Light-sleep mode, which APB clock cannot do. 3. Some flags may not be supported on ESP32-S3, reading technical reference manual before using it.

Note: The clock frequency of SCL in master mode should not be lager than max frequency for SCL mentioned in the table above.

Install Driver After the I2C driver is configured, install it by calling the function i2c_driver_install() with the following parameters:
· Port number, one of the two port numbers from i2c_port_t · Master or slave, selected from i2c_mode_t · (Slave only) Size of buffers to allocate for sending and receiving data. As I2C is a master-centric bus, data
can only go from the slave to the master at the masterns request. Therefore, the slave will usually have a send buffer where the slave application writes data. The data remains in the send buffer to be read by the master at the masterns own discretion. · Flags for allocating the interrupt (see ESP_INTR_FLAG_* values in esp_hw_support/include/esp_intr_alloc.h)
Communication as Master After installing the I2C driver, ESP32-S3 is ready to communicate with other I2C devices.
ESP32-S3ns I2C controller operating as master is responsible for establishing communication with I2C slave devices and sending commands to trigger a slave to action, for example, to take a measurement and send the readings back to the master.
For better process organization, the driver provides a container, called aocommand linkp, that should be populated with a sequence of commands and then passed to the I2C controller for execution.
Master Write The example below shows how to build a command link for an I2C master to send n bytes to a slave.
The following describes how a command link for a omaster writepis set up and what comes inside:
1. Create a command link with i2c_cmd_link_create(). Then, populate it with the series of data to be sent to the slave:
a) Start bit - i2c_master_start() b) Slave address - i2c_master_write_byte(). The single byte address is provided as an argument
of this function call. c) Data - One or more bytes as an argument of i2c_master_write() d) Stop bit - i2c_master_stop()
Both functions i2c_master_write_byte() and i2c_master_write() have an additional argument specifying whether the master should ensure that it has received the ACK bit. 2. Trigger the execution of the command link by I2C controller by calling i2c_master_cmd_begin(). Once the execution is triggered, the command link cannot be modified.

Espressif Systems

561

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Fig. 5: I2C command link - master write example
3. After the commands are transmitted, release the resources used by the command link by calling i2c_cmd_link_delete().
Master Read The example below shows how to build a command link for an I2C master to read n bytes from a slave.

Fig. 6: I2C command link - master read example
Compared to writing data, the command link is populated in Step 4 not with i2c_master_write... functions but with i2c_master_read_byte() and / or i2c_master_read(). Also, the last read in Step 5 is configured so that the master does not provide the ACK bit.
Indicating Write or Read After sending a slave address (see Step 3 on both diagrams above), the master either writes or reads from the slave. The information on what the master will actually do is hidden in the least significant bit of the slavens address. For this reason, the command link sent by the master to write data to the slave contains the address (ESP_SLAVE_ADDR << 1) | I2C_MASTER_WRITE and looks as follows:

Espressif Systems

562

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

i2c_master_write_byte(cmd, (ESP_SLAVE_ADDR << 1) | I2C_MASTER_WRITE, ACK_EN); Likewise, the command link to read from the slave looks as follows: i2c_master_write_byte(cmd, (ESP_SLAVE_ADDR << 1) | I2C_MASTER_READ, ACK_EN);

Communication as Slave After installing the I2C driver, ESP32-S3 is ready to communicate with other I2C devices.
The API provides the following functions for slaves
· i2c_slave_read_buffer() Whenever the master writes data to the slave, the slave will automatically store it in the receive buffer. This allows the slave application to call the function i2c_slave_read_buffer() at its own discretion. This function also has a parameter to specify block time if no data is in the receive buffer. This will allow the slave application to wait with a specified timeout for data to arrive to the buffer.
· i2c_slave_write_buffer() The send buffer is used to store all the data that the slave wants to send to the master in FIFO order. The data stays there until the master requests for it. The function i2c_slave_write_buffer() has a parameter to specify block time if the send buffer is full. This will allow the slave application to wait with a specified timeout for the adequate amount of space to become available in the send buffer.
A code example showing how to use these functions can be found in peripherals/i2c.

Interrupt Handling During driver installation, an interrupt handler is installed by default.

Customized Configuration As mentioned at the end of Section Configuration, when the function i2c_param_config() initializes the driver configuration for an I2C port, it also sets several I2C communication parameters to default values defined in the I2C specification. Some other related parameters are pre-configured in registers of the I2C controller.
All these parameters can be changed to user-defined values by calling dedicated functions given in the table below. Please note that the timing values are defined in APB clock cycles. The frequency of APB is specified in I2C_APB_CLK_FREQ.

Table 3: Other Configurable I2C Communication Parameters

Parameters to Change High time and low time for SCL pulses SCL and SDA signal timing used during generation of start signals SCL and SDA signal timing used during generation of stop signals Timing relationship between SCL and SDA signals when slave samples, as well as when master toggles I2C timeout Choice between transmitting / receiving the LSB or MSB first, choose one of the modes defined in i2c_trans_mode_t

Function i2c_set_period() i2c_set_start_timing() i2c_set_stop_timing() i2c_set_data_timing()
i2c_set_timeout() i2c_set_data_mode()

Each of the above functions has a _get_ counterpart to check the currently set value. For example, to check the I2C timeout value, call i2c_get_timeout().
To check the default parameter values which are set during the driver configuration process, please refer to the file driver/i2c.c and look for defines with the suffix _DEFAULT.
You can also select different pins for SDA and SCL signals and alter the configuration of pull-ups with the function i2c_set_pin(). If you want to modify already entered values, use the function i2c_param_config().

Espressif Systems

563

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Note: ESP32-S3ns internal pull-ups are in the range of tens of kOhm, which is, in most cases, insufficient for use as I2C pull-ups. Users are advised to use external pull-ups with values described in the I2C specification.
Error Handling The majority of I2C driver functions either return ESP_OK on successful completion or a specific error code on failure. It is a good practice to always check the returned values and implement error handling. The driver also prints out log messages that contain error details, e.g., when checking the validity of entered configuration. For details please refer to the file driver/i2c.c and look for defines with the suffix _ERR_STR.
Use dedicated interrupts to capture communication failures. For instance, if a slave stretches the clock for too long while preparing the data to send back to master, the interrupt I2C_TIME_OUT_INT will be triggered. For detailed information, see Interrupt Handling.
In case of a communication failure, you can reset the internal hardware buffers by calling the functions i2c_reset_tx_fifo() and i2c_reset_rx_fifo() for the send and receive buffers respectively.
Delete Driver When the I2C communication is established with the function i2c_driver_install() and is not required for some substantial amount of time, the driver may be deinitialized to release allocated resources by calling i2c_driver_delete().
Before calling i2c_driver_delete() to remove i2c driver, please make sure that all threads have stopped using the driver in any way, because this function does not guarantee thread safety.
Application Example
I2C master and slave example: peripherals/i2c.
API Reference
Header File
· components/driver/include/driver/i2c.h
Functions esp_err_t i2c_driver_install(i2c_port_t i2c_num, i2c_mode_t mode, size_t slv_rx_buf_len, size_t
slv_tx_buf_len, int intr_alloc_flags) Install an I2C driver.
Note In master mode, if the cache is likely to be disabled(such as write flash) and the slave is time-sensitive, ESP_INTR_FLAG_IRAM is suggested to be used. In this case, please use the memory allocated from internal RAM in i2c read and write function, because we can not access the psram(if psram is enabled) in interrupt handle function when cache is disabled.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error · ESP_FAIL Driver installation error
Parameters · i2c_num: I2C port number · mode: I2C mode (either master or slave) · slv_rx_buf_len: Receiving buffer size. Only slave mode will use this value, it is ignored in master mode. · slv_tx_buf_len: Sending buffer size. Only slave mode will use this value, it is ignored in master mode. · intr_alloc_flags: Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.

Espressif Systems

564

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t i2c_driver_delete(i2c_port_t i2c_num) Delete I2C driver.
Note This function does not guarantee thread safety. Please make sure that no thread will continuously hold semaphores before calling the delete function.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2c_num: I2C port to delete
esp_err_t i2c_param_config(i2c_port_t i2c_num, const i2c_config_t *i2c_conf) Configure an I2C bus with the given configuration.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2c_num: I2C port to configure · i2c_conf: Pointer to the I2C configuration
esp_err_t i2c_reset_tx_fifo(i2c_port_t i2c_num) reset I2C tx hardware fifo
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2c_num: I2C port number
esp_err_t i2c_reset_rx_fifo(i2c_port_t i2c_num) reset I2C rx fifo
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2c_num: I2C port number
esp_err_t i2c_set_pin(i2c_port_t i2c_num, int sda_io_num, int scl_io_num, bool sda_pullup_en, bool scl_pullup_en, i2c_mode_t mode)
Configure GPIO pins for I2C SCK and SDA signals.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2c_num: I2C port number · sda_io_num: GPIO number for I2C SDA signal · scl_io_num: GPIO number for I2C SCL signal · sda_pullup_en: Enable the internal pullup for SDA pin · scl_pullup_en: Enable the internal pullup for SCL pin · mode: I2C mode
esp_err_t i2c_master_write_to_device(i2c_port_t i2c_num, uint8_t device_address, const uint8_t *write_buffer, size_t write_size, TickType_t ticks_to_wait)
Perform a write to a device connected to a particular I2C port. This function is a wrapper to i2c_master_start(), i2c_master_write(), i2c_master_read(), etclIt shall only be called in I2C master mode.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error

Espressif Systems

565

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· ESP_FAIL Sending command error, slave hasnnt ACK the transfer. · ESP_ERR_INVALID_STATE I2C driver not installed or not in master mode. · ESP_ERR_TIMEOUT Operation timeout because the bus is busy. Parameters · i2c_num: I2C port number to perform the transfer on · device_address: I2C devicens 7-bit address · write_buffer: Bytes to send on the bus · write_size: Size, in bytes, of the write buffer · ticks_to_wait: Maximum ticks to wait before issuing a timeout.
esp_err_t i2c_master_read_from_device(i2c_port_t i2c_num, uint8_t device_address, uint8_t *read_buffer, size_t read_size, TickType_t ticks_to_wait)
Perform a read to a device connected to a particular I2C port. This function is a wrapper to i2c_master_start(), i2c_master_write(), i2c_master_read(), etclIt shall only be called in I2C master mode.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error · ESP_FAIL Sending command error, slave hasnnt ACK the transfer. · ESP_ERR_INVALID_STATE I2C driver not installed or not in master mode. · ESP_ERR_TIMEOUT Operation timeout because the bus is busy.
Parameters · i2c_num: I2C port number to perform the transfer on · device_address: I2C devicens 7-bit address · read_buffer: Buffer to store the bytes received on the bus · read_size: Size, in bytes, of the read buffer · ticks_to_wait: Maximum ticks to wait before issuing a timeout.
esp_err_t i2c_master_write_read_device(i2c_port_t i2c_num, uint8_t device_address, const uint8_t *write_buffer, size_t write_size, uint8_t *read_buffer, size_t read_size, TickType_t ticks_to_wait)
Perform a write followed by a read to a device on the I2C bus. A repeated start signal is used between the write and read, thus, the bus is not released until the two transactions are finished. This function is a wrapper to i2c_master_start(), i2c_master_write(), i2c_master_read(), etclIt shall only be called in I2C master mode.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error · ESP_FAIL Sending command error, slave hasnnt ACK the transfer. · ESP_ERR_INVALID_STATE I2C driver not installed or not in master mode. · ESP_ERR_TIMEOUT Operation timeout because the bus is busy.
Parameters · i2c_num: I2C port number to perform the transfer on · device_address: I2C devicens 7-bit address · write_buffer: Bytes to send on the bus · write_size: Size, in bytes, of the write buffer · read_buffer: Buffer to store the bytes received on the bus · read_size: Size, in bytes, of the read buffer · ticks_to_wait: Maximum ticks to wait before issuing a timeout.
i2c_cmd_handle_t i2c_cmd_link_create_static(uint8_t *buffer, uint32_t size) Create and initialize an I2C commands list with a given buffer. All the allocations for data or signals (START, STOP, ACK, l) will be performed within this buffer. This buffer must be valid during the whole transaction. After finishing the I2C transactions, it is required to call i2c_cmd_link_delete_static().
Note It is highly advised to not allocate this buffer on the stack. The size of the data used underneath may increase in the future, resulting in a possible stack overflow as the macro

Espressif Systems

566

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

I2C_LINK_RECOMMENDED_SIZE would also return a bigger value. A better option is to use a buffer allocated statically or dynamically (with malloc). Return Handle to the I2C command link or NULL if the buffer provided is too small, please use I2C_LINK_RECOMMENDED_SIZE macro to get the recommended size for the buffer. Parameters
· buffer: Buffer to use for commands allocations · size: Size in bytes of the buffer

i2c_cmd_handle_t i2c_cmd_link_create(void) Create and initialize an I2C commands list with a given buffer. After finishing the I2C transactions, it is required to call i2c_cmd_link_delete() to release and return the resources. The required bytes will be dynamically allocated.

Return Handle to the I2C command link or NULL in case of insufficient dynamic memory.

void i2c_cmd_link_delete_static(i2c_cmd_handle_t cmd_handle) Free the I2C commands list allocated statically with i2c_cmd_link_create_static.

Parameters · cmd_handle: I2C commands list allocated statically. This handle should be created thanks to i2c_cmd_link_create_static() function

void i2c_cmd_link_delete(i2c_cmd_handle_t cmd_handle) Free the I2C commands list.

Parameters · cmd_handle: I2C commands list. i2c_cmd_link_create() function

This handle should be created thanks to

esp_err_t i2c_master_start(i2c_cmd_handle_t cmd_handle) Queue a oSTART signalpto the given commands list. This function shall only be called in I2C master mode. Call i2c_master_cmd_begin() to send all the queued commands.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NO_MEM The static buffer used to create cmd_handler is too small · ESP_FAIL No more memory left on the heap
Parameters · cmd_handle: I2C commands list

esp_err_t i2c_master_write_byte(i2c_cmd_handle_t cmd_handle, uint8_t data, bool ack_en) Queue aowrite bytepcommand to the commands list. A single byte will be sent on the I2C port. This function shall only be called in I2C master mode. Call i2c_master_cmd_begin() to send all queued commands.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NO_MEM The static buffer used to create cmd_handler is too small · ESP_FAIL No more memory left on the heap
Parameters · cmd_handle: I2C commands list · data: Byte to send on the port · ack_en: Enable ACK signal

esp_err_t i2c_master_write(i2c_cmd_handle_t cmd_handle, const uint8_t *data, size_t data_len, bool ack_en)
Queue a owrite (multiple) bytespcommand to the commands list. This function shall only be called in I2C master mode. Call i2c_master_cmd_begin() to send all queued commands.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NO_MEM The static buffer used to create cmd_handler is too small

Espressif Systems

567

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· ESP_FAIL No more memory left on the heap Parameters
· cmd_handle: I2C commands list · data: Bytes to send. This buffer shall remain valid until the transaction is finished. If the PSRAM
is enabled and intr_flag is set to ESP_INTR_FLAG_IRAM, data should be allocated from internal RAM. · data_len: Length, in bytes, of the data buffer · ack_en: Enable ACK signal
esp_err_t i2c_master_read_byte(i2c_cmd_handle_t cmd_handle, uint8_t *data, i2c_ack_type_t ack) Queue aoread bytepcommand to the commands list. A single byte will be read on the I2C bus. This function shall only be called in I2C master mode. Call i2c_master_cmd_begin() to send all queued commands.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NO_MEM The static buffer used to create cmd_handler is too small · ESP_FAIL No more memory left on the heap
Parameters · cmd_handle: I2C commands list · data: Pointer where the received byte will the stored. This buffer shall remain valid until the transaction is finished. · ack: ACK signal
esp_err_t i2c_master_read(i2c_cmd_handle_t cmd_handle, uint8_t *data, size_t data_len, i2c_ack_type_t ack)
Queue a oread (multiple) bytespcommand to the commands list. Multiple bytes will be read on the I2C bus. This function shall only be called in I2C master mode. Call i2c_master_cmd_begin() to send all queued commands.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NO_MEM The static buffer used to create cmd_handler is too small · ESP_FAIL No more memory left on the heap
Parameters · cmd_handle: I2C commands list · data: Pointer where the received bytes will the stored. This buffer shall remain valid until the transaction is finished. · data_len: Size, in bytes, of the data buffer · ack: ACK signal
esp_err_t i2c_master_stop(i2c_cmd_handle_t cmd_handle) Queue a oSTOP signalpto the given commands list. This function shall only be called in I2C master mode. Call i2c_master_cmd_begin() to send all the queued commands.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NO_MEM The static buffer used to create cmd_handler is too small · ESP_FAIL No more memory left on the heap
Parameters · cmd_handle: I2C commands list
esp_err_t i2c_master_cmd_begin(i2c_port_t i2c_num, i2c_cmd_handle_t cmd_handle, TickType_t ticks_to_wait)
Send all the queued commands on the I2C bus, in master mode. The task will be blocked until all the commands have been sent out. The I2C APIs are not thread-safe, if you want to use one I2C port in different tasks, you need to take care of the multi-thread issue. This function shall only be called in I2C master mode.
Return · ESP_OK Success

Espressif Systems

568

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_ERR_INVALID_ARG Parameter error · ESP_FAIL Sending command error, slave hasnnt ACK the transfer. · ESP_ERR_INVALID_STATE I2C driver not installed or not in master mode. · ESP_ERR_TIMEOUT Operation timeout because the bus is busy. Parameters · i2c_num: I2C port number · cmd_handle: I2C commands list · ticks_to_wait: Maximum ticks to wait before issuing a timeout.
int i2c_slave_write_buffer(i2c_port_t i2c_num, const uint8_t *data, int size, TickType_t ticks_to_wait)
Write bytes to internal ringbuffer of the I2C slave data. When the TX fifo empty, the ISR will fill the hardware FIFO with the internal ringbufferns data.
Note This function shall only be called in I2C slave mode. Return
· ESP_FAIL (-1) Parameter error · Other (>=0) The number of data bytes pushed to the I2C slave buffer. Parameters · i2c_num: I2C port number · data: Bytes to write into internal buffer · size: Size, in bytes, of data buffer · ticks_to_wait: Maximum ticks to wait.
int i2c_slave_read_buffer(i2c_port_t i2c_num, uint8_t *data, size_t max_size, TickType_t ticks_to_wait)
Read bytes from I2C internal buffer. When the I2C bus receives data, the ISR will copy them from the hardware RX FIFO to the internal ringbuffer. Calling this function will then copy bytes from the internal ringbuffer to the data user buffer.
Note This function shall only be called in I2C slave mode. Return
· ESP_FAIL(-1) Parameter error · Others(>=0) The number of data bytes read from I2C slave buffer. Parameters · i2c_num: I2C port number · data: Buffer to fill with ringbufferns bytes · max_size: Maximum bytes to read · ticks_to_wait: Maximum waiting ticks
esp_err_t i2c_set_period(i2c_port_t i2c_num, int high_period, int low_period) Set I2C master clock period.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2c_num: I2C port number · high_period: Clock cycle number during SCL is high level, high_period is a 14 bit value · low_period: Clock cycle number during SCL is low level, low_period is a 14 bit value
esp_err_t i2c_get_period(i2c_port_t i2c_num, int *high_period, int *low_period) Get I2C master clock period.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2c_num: I2C port number · high_period: pointer to get clock cycle number during SCL is high level, will get a 14 bit value · low_period: pointer to get clock cycle number during SCL is low level, will get a 14 bit value
esp_err_t i2c_filter_enable(i2c_port_t i2c_num, uint8_t cyc_num)

Espressif Systems

569

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Enable hardware filter on I2C bus Sometimes the I2C bus is disturbed by high frequency noise(about 20ns), or the rising edge of the SCL clock is very slow, these may cause the master state machine to break. Enable hardware filter can filter out high frequency interference and make the master more stable.
Note Enable filter will slow down the SCL clock. Return
· ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error Parameters · i2c_num: I2C port number to filter · cyc_num: the APB cycles need to be filtered (0<= cyc_num <=7). When the period of a pulse is
less than cyc_num * APB_cycle, the I2C controller will ignore this pulse.
esp_err_t i2c_filter_disable(i2c_port_t i2c_num) Disable filter on I2C bus.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2c_num: I2C port number
esp_err_t i2c_set_start_timing(i2c_port_t i2c_num, int setup_time, int hold_time) set I2C master start signal timing
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2c_num: I2C port number · setup_time: clock number between the falling-edge of SDA and rising-edge of SCL for start mark, itns a 10-bit value. · hold_time: clock num between the falling-edge of SDA and falling-edge of SCL for start mark, itns a 10-bit value.
esp_err_t i2c_get_start_timing(i2c_port_t i2c_num, int *setup_time, int *hold_time) get I2C master start signal timing
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2c_num: I2C port number · setup_time: pointer to get setup time · hold_time: pointer to get hold time
esp_err_t i2c_set_stop_timing(i2c_port_t i2c_num, int setup_time, int hold_time) set I2C master stop signal timing
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2c_num: I2C port number · setup_time: clock num between the rising-edge of SCL and the rising-edge of SDA, itns a 10-bit value. · hold_time: clock number after the STOP bitns rising-edge, itns a 14-bit value.
esp_err_t i2c_get_stop_timing(i2c_port_t i2c_num, int *setup_time, int *hold_time) get I2C master stop signal timing
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error

Espressif Systems

570

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Parameters · i2c_num: I2C port number · setup_time: pointer to get setup time. · hold_time: pointer to get hold time.

esp_err_t i2c_set_data_timing(i2c_port_t i2c_num, int sample_time, int hold_time) set I2C data signal timing

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2c_num: I2C port number · sample_time: clock number I2C used to sample data on SDA after the rising-edge of SCL, itn s a 10-bit value · hold_time: clock number I2C used to hold the data after the falling-edge of SCL, itns a 10-bit value

esp_err_t i2c_get_data_timing(i2c_port_t i2c_num, int *sample_time, int *hold_time) get I2C data signal timing

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2c_num: I2C port number · sample_time: pointer to get sample time · hold_time: pointer to get hold time

esp_err_t i2c_set_timeout(i2c_port_t i2c_num, int timeout) set I2C timeout value

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2c_num: I2C port number · timeout: timeout value for I2C bus (unit: APB 80Mhz clock cycle)

esp_err_t i2c_get_timeout(i2c_port_t i2c_num, int *timeout) get I2C timeout value

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2c_num: I2C port number · timeout: pointer to get timeout value

esp_err_t i2c_set_data_mode(i2c_port_t i2c_num,

i2c_trans_mode_t

i2c_trans_mode_t rx_trans_mode) set I2C data transfer mode

tx_trans_mode,

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2c_num: I2C port number · tx_trans_mode: I2C sending data mode · rx_trans_mode: I2C receving data mode

esp_err_t i2c_get_data_mode(i2c_port_t i2c_num,

i2c_trans_mode_t

i2c_trans_mode_t *rx_trans_mode) get I2C data transfer mode

*tx_trans_mode,

Espressif Systems

571

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2c_num: I2C port number · tx_trans_mode: pointer to get I2C sending data mode · rx_trans_mode: pointer to get I2C receiving data mode
Structures struct i2c_config_t
I2C initialization parameters.
Public Members
i2c_mode_t mode I2C mode
int sda_io_num GPIO number for I2C sda signal
int scl_io_num GPIO number for I2C scl signal
bool sda_pullup_en Internal GPIO pull mode for I2C sda signal
bool scl_pullup_en Internal GPIO pull mode for I2C scl signal
uint32_t clk_speed I2C clock frequency for master mode, (no higher than 1MHz for now)
struct i2c_config_t::[anonymous]::[anonymous] master I2C master config
uint8_t addr_10bit_en I2C 10bit address mode enable for slave mode
uint16_t slave_addr I2C address for slave mode
uint32_t maximum_speed I2C expected clock speed from SCL.
struct i2c_config_t::[anonymous]::[anonymous] slave I2C slave config
uint32_t clk_flags Bitwise of I2C_SCLK_SRC_FLAG_**FOR_DFS** for clk source choice
Macros I2C_APB_CLK_FREQ
I2C source clock is APB clock, 80MHz I2C_NUM_MAX
I2C port max
I2C_NUM_0 I2C port 0
I2C_NUM_1 I2C port 1

Espressif Systems

572

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
I2C_SCLK_SRC_FLAG_FOR_NOMAL Any one clock source that is available for the specified frequency may be choosen
I2C_SCLK_SRC_FLAG_AWARE_DFS For REF tick clock, it wonnt change with APB.
I2C_SCLK_SRC_FLAG_LIGHT_SLEEP For light sleep mode.
I2C_INTERNAL_STRUCT_SIZE Minimum size, in bytes, of the internal private structure used to describe I2C commands link.
I2C_LINK_RECOMMENDED_SIZE(TRANSACTIONS) The following macro is used to determine the recommended size of the buffer to pass to i2c_cmd_link_create_static() function. It requires one parameter, TRANSACTIONS, describing the number of transactions intended to be performed on the I2C port. For example, if one wants to perform a read on an I2C device register, TRANSACTIONS must be at least 2, because the commands required are the following: · write device register · read register content Signals such as o(repeated) startp, ostopp, onackp, oackpshall not be counted.
Type Definitions typedef void *i2c_cmd_handle_t
I2C command handle
Header File · components/hal/include/hal/i2c_types.h
Macros I2C_CLK_FREQ_MAX
Use the highest speed that is available for the clock source picked by clk_flags.
Type Definitions typedef int i2c_port_t
I2C port number, can be I2C_NUM_0 ~ (I2C_NUM_MAX-1).
Enumerations enum i2c_mode_t
Values: I2C_MODE_SLAVE = 0
I2C slave mode I2C_MODE_MASTER
I2C master mode I2C_MODE_MAX enum i2c_rw_t Values: I2C_MASTER_WRITE = 0
I2C write data I2C_MASTER_READ
I2C read data

Espressif Systems

573

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

enum i2c_trans_mode_t Values:
I2C_DATA_MODE_MSB_FIRST = 0 I2C data msb first
I2C_DATA_MODE_LSB_FIRST = 1 I2C data lsb first
I2C_DATA_MODE_MAX
enum i2c_addr_mode_t Values:
I2C_ADDR_BIT_7 = 0 I2C 7bit address for slave mode
I2C_ADDR_BIT_10 I2C 10bit address for slave mode
I2C_ADDR_BIT_MAX
enum i2c_ack_type_t Values:
I2C_MASTER_ACK = 0x0 I2C ack for each byte read
I2C_MASTER_NACK = 0x1 I2C nack for each byte read
I2C_MASTER_LAST_NACK = 0x2 I2C nack for the last byte
I2C_MASTER_ACK_MAX
enum i2c_sclk_t I2C clock source, sorting from smallest to largest, place them in order. This can be expanded in the future use.
Values:
I2C_SCLK_DEFAULT = 0 I2C source clock not selected
I2C_SCLK_XTAL I2C source clock from XTAL, 40M
I2C_SCLK_RTC I2C source clock from 8M RTC, 8M
I2C_SCLK_MAX

2.3.8 Inter-IC Sound (I2S)
Overview
I2S (Inter-IC Sound) is a serial, synchronous communication protocol that is usually used for transmitting audio data between two digital audio devices.
ESP32-S3 contains two I2S peripheral(s). These peripherals can be configured to input and output sample data via the I2S driver.
An I2S bus consists of the following lines:
· Master clock line (operational) · Bit clock line · Channel select line · Serial data line

Espressif Systems

574

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Each I2S controller has the following features that can be configured using the I2S driver: · Operation as system master or slave · Capable of acting as transmitter or receiver · DMA controller that allows for streaming sample data without requiring the CPU to copy each data sample
Each controller can operate in half-duplex communication mode. Thus, the two controllers can be combined to establish full-duplex communication.
Functional Overview
Installing the Driver Install the I2S driver by calling the function :cpp:func`i2s_driver_install` and passing the following arguments:
· Port number · The structure i2s_config_t with defined communication parameters · Event queue size and handle Once :cpp:func`i2s_driver_install` returns ESP_OK, it means I2S has started. Configuration example:
static const int i2s_num = 0; // i2s port number
i2s_config_t i2s_config = { .mode = I2S_MODE_MASTER | I2S_MODE_TX, .sample_rate = 44100, .bits_per_sample = I2S_BITS_PER_SAMPLE_16BIT, .channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT, .communication_format = I2S_COMM_FORMAT_STAND_I2S, .tx_desc_auto_clear = false, .dma_desc_num = 8, .dma_frame_num = 64, .bits_per_chan = I2S_BITS_PER_SAMPLE_16BIT
};
i2s_driver_install(I2S_NUM, &i2s_config, 0, NULL);
Setting Communication Pins Once the driver is installed, configure physical GPIO pins to which signals will be routed. For this, call the function :cpp:func`i2s_set_pin` and pass the following arguments to it:
· Port number · The structure i2s_pin_config_t defining the GPIO pin numbers to which the driver should route the
MCK, BCK, WS, DATA out, and DATA in signals. If you want to keep a currently allocated pin number for a specific signal, or if this signal is unused, then pass the macro I2S_PIN_NO_CHANGE. See the example below.
Note: MCK only takes effect in I2S_MODE_MASTER mode.
static const i2s_pin_config_t pin_config = { .mck_io_num = 0, .bck_io_num = 4, .ws_io_num = 5, .data_out_num = 18, .data_in_num = I2S_PIN_NO_CHANGE
};
i2s_set_pin(i2s_num, &pin_config);

Espressif Systems

575

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Running I2S Communication To perform a transmission: · Prepare the data for sending · Call the function i2s_write() and pass the data buffer address and data length to it
The function will write the data to the DMA Tx buffer, and then the data will be transmitted automatically.
i2s_write(I2S_NUM, samples_data, ((bits+8)/16)*SAMPLE_PER_CYCLE*4, &i2s_bytes_ write, 100);
To retrieve received data, use the function i2s_read(). It will retrieve the data from the DMA Rx buffer, once the data is received by the I2S controller.
i2s_read(I2S_NUM, data_recv, ((bits+8)/16)*SAMPLE_PER_CYCLE*4, &i2s_bytes_read, 100);
You can temporarily stop the I2S driver by calling the function i2s_stop(), which will disable the I2S Tx/Rx units until the function i2s_start() is called. If the function :cpp:func`i2s_driver_install` is used, the driver will start up automatically eliminating the need to call i2s_start().

Deleting the Driver If the established communication is no longer required, the driver can be removed to free allocated resources by calling i2s_driver_uninstall().

Application Example
A code example for the I2S driver can be found in the directory peripherals/i2s. In addition, there is a short configuration examples for the I2S driver.

I2S configuration Example for general usage.
#include "driver/i2s.h"
static const int i2s_num = 0; // i2s port number
i2s_config_t i2s_config = { .mode = I2S_MODE_MASTER | I2S_MODE_TX, .sample_rate = 44100, .bits_per_sample = I2S_BITS_PER_SAMPLE_16BIT, .channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT, .communication_format = I2S_COMM_FORMAT_STAND_I2S .tx_desc_auto_clear = false, .dma_desc_num = 8, .dma_frame_num = 64
};
static const i2s_pin_config_t pin_config = { .bck_io_num = 4, .ws_io_num = 5, .data_out_num = 18, .data_in_num = I2S_PIN_NO_CHANGE
};
i2s_driver_install(i2s_num, &i2s_config, 0, NULL); //install and start i2s driver i2s_set_pin(i2s_num, &pin_config);
... /* You can reset parameters by calling 'i2s_set_clk'
* * The low 16 bits are the valid data bits in one chan and the high 16 bits are
(continues on next page)

Espressif Systems

576

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page) * the total bits in one chan. If high 16 bits is smaller than low 16 bits, it will * be set to a same value as low 16 bits. */ uint32_t bits_cfg = (I2S_BITS_PER_CHAN_32BIT << 16) | I2S_BITS_PER_SAMPLE_16BIT; i2s_set_clk(i2s_num, 22050, bits_cfg, I2S_CHANNEL_STEREO); ...
i2s_driver_uninstall(i2s_num); //stop & destroy i2s driver
I2S on ESP32-S3 support TDM mode, up to 16 channels are available in TDM mode. If you want to use TDM mode, set field channel_format of i2s_config_t to I2S_CHANNEL_FMT_MULTIPLE. Then enable the channels by setting chan_mask using masks in i2s_channel_t, the number of active channels and total channels will be calculate automatically. Also you can set a particular total channel number for it, but it shouldnnt be smaller than the largest channel you use.
If active channels are discrete, the inactive channels within total channels will be filled by a constant automatically. But if skip_msk is enabled, these inactive channels will be skiped.
#include "driver/i2s.h"
static const int i2s_num = 0; // i2s port number
i2s_config_t i2s_config = { .mode = I2S_MODE_MASTER | I2S_MODE_TX, .sample_rate = 44100, .bits_per_sample = I2S_BITS_PER_SAMPLE_16BIT, .channel_format = I2S_CHANNEL_FMT_MULTIPLE, .communication_format = I2S_COMM_FORMAT_STAND_I2S .tx_desc_auto_clear = false, .dma_desc_num = 8, .dma_frame_num = 64, .chan_mask = I2S_TDM_ACTIVE_CH0 | I2S_TDM_ACTIVE_CH2
};
static const i2s_pin_config_t pin_config = { .bck_io_num = 4, .ws_io_num = 5, .data_out_num = 18, .data_in_num = I2S_PIN_NO_CHANGE
};
i2s_driver_install(i2s_num, &i2s_config, 0, NULL); //install and start i2s driver i2s_set_pin(i2s_num, &pin_config);
... /* You can reset parameters by calling 'i2s_set_clk'
* * The low 16 bits are the valid data bits in one chan and the high 16 bits are * the total bits in one chan. If high 16 bits is smaller than low 16 bits, it will * be set to a same value as low 16 bits. */ uint32_t bits_cfg = (I2S_BITS_PER_CHAN_32BIT << 16) | I2S_BITS_PER_SAMPLE_16BIT; i2s_set_clk(i2s_port_t i2s_num, 22050, bits_cfg, I2S_TDM_ACTIVE_CH0 | I2S_TDM_ ACTIVE_CH1); // set clock ...
i2s_driver_uninstall(i2s_num); //stop & destroy i2s driver

Application Notes If you are using a high sample rate like more than 48 kHz or see the data being lost, the following information might help.

Espressif Systems

577

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Considering different applications have different requirements, dma_desc_num and dma_frame_num are made public. Here is the detailed explanation to these two fields:
· dma_desc_num: The total number of descriptors used by I2S DMA to receive/transmit data. A descriptor includes some information such as buffer address, the address of the next descriptor, and the buffer length. Since one descriptor points to one buffer, therefore, dma_desc_num can be interpreted as the total number of DMA buffers used to store data from DMA interrupt. Notice that these buffers are internal to i2s_read() and descriptors are created automatically inside of the I2S driver. Users only need to set the buffer number while the length is derived from the parameter described below.
· dma_frame_num: The number of frames for one-time sampling. The frame here means the total data from all the channels in one WS cycle. For example, if two channels in stereo mode (i.e., channel_format is set to I2S_CHANNEL_FMT_RIGHT_LEFT) are active, and each channel transfers 32 bits (i.e., bits_per_sample is set to I2S_BITS_PER_CHAN_32BIT), then the total number of bytes of a frame is channel_format * bits_per_sample = 2 * 32 / 8 = 8 bytes. For example, we assume that the current dma_frame_num is 100, then the length of the DMA buffer is 8 * 100 = 800 bytes. Note that the length of an internal DMA buffer shouldnnt be greater than 4092.
When the data received by DMA reach the size of internal DMA buffer, a receive interrupt is triggered, and an internal message queue will transport this buffer to i2s_read(). The main task of i2s_read() is to copy the data in the internal DMA buffer into the user given buffer. Since the internal DMA buffer is usually not equal to the user given buffer size, there are two cases:
· If the size of internal DMA buffers is smaller than the user given buffer size, i2s_read() will consume several internal DMA buffers to fill up the user given buffer. If the message queue of DMA buffer is not long enough, i2s_read() will be blocked on receive message queue untill getting enough data. You can estimate the time i2s_read() function is blocked by the formula block_time (sec) = (given_bufer_size) / (sample_rate * channel_num * channel_bytes). If we place i2s_read() in a while together with other functions we should also consider the time the loop execution is blocked by the other functions before i2s_read() is executed again. It is not allowed to exceed the max_wait_time (sec) = ((dma_desc_num 1) * dma_buffer_size) / (sample_rate), otherwise the internal message queue will overflow and in consequence some data will be lost.
· If the DMA buffer size is greater than the user given buffer size, it means i2s_read() would need to be called in a loop several times to take all the data, the max_wait_time may be exceeded, and the message queue overflow is likely to happen. Therefore it is quite risky to use a small user buffer for data receiving.
Here are a couple of tips when the sample rate is high:
1. Increasing dma_frame_num can help to reduce the I2S DMA interrupt frequency; 2. Increasing dma_desc_num can help to alow a longer max_wait_time to be spent by the other functions in
the loop conatining i2s_read() ;
while (1) { ... // Other operations (e.g. Waiting on a semaphore) i2s_read(I2S_NUM, user_given_buffer, user_given_buffer_size, &i2s_
bytes_read, 100); ... // Other operations (e.g. Sending the data to another thread.
Avoid any data processing here.) }
3. Increasing the size of the buffer internal to i2s_read() can help to increase the max_wait_time. When you process I2S data (like storing the data to an SD card) in another thread, the time spent in processing thread for one loop should not exceed the max_wait_time otherwise some data will be lost. So if the processing of the received data received is rather slow, please allow i2s_read() a big internal buffer for storing the read data;
4. Allocating at least two user given buffers can improve the data receipt efficiency. One buffer can continue to receive data while the other one is under processing. But we have to guarantee the buffer that is going to read data is not under processing in the other thread. We can use a semaphore or another lock to avoid overwriting the data in the buffer while it is still under processing;
uint8_t **user_given_buffers = (uint8_t **)calloc(buffer_num, sizeof(uint8_t *)); // Don't forget to check if user_given_buffers is NULL here
(continues on next page)

Espressif Systems

578

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)
for (int i = 0; i < buffer_num; i++) { user_given_buffers[i] = (uint8_t *)calloc(user_given_buffer_size,
sizeof(uint8_t)); // Don't forget to check if user_given_buffers[i] is NULL here
} int cnt = 0; while (1) {
... // Other operations (e.g. Waiting on a semaphore) i2s_read(I2S_NUM, user_given_buffer[cnt], user_given_buffer_size, & i2s_bytes_read, 100); ... // Other operations (e.g. Sending the data to another thread. Avoid any data processing here.) cnt++; cnt %= buffer_num; }
5. Increasing the priority of the thread that contains i2s_read() can help the data in the message queue to be taken more timely.
To check whether there are data lost, you can offer an event queue handler to the driver during installation:
QueueHandle_t evt_que; i2s_driver_install(i2s_num, &i2s_config, 10, &evt_que);
You will receive I2S_EVENT_RX_Q_OVF event when there are data lost.

API Reference
Header File · components/driver/include/driver/i2s.h

Functions esp_err_t i2s_set_pin(i2s_port_t i2s_num, const i2s_pin_config_t *pin)
Set I2S pin number.
Inside the pin configuration structure, set I2S_PIN_NO_CHANGE for any pin where the current configuration should not be changed.
Note The I2S peripheral output signals can be connected to multiple GPIO pads. However, the I2S peripheral input signal can only be connected to one GPIO pad.
Parameters · i2s_num: I2S port number · pin: I2S Pin structure, or NULL to set 2-channel 8-bit internal DAC pin configuration (GPIO25 & GPIO26)
Note if *pin is set as NULL, this function will initialize both of the built-in DAC channels by default. if you donnt want this to happen and you want to initialize only one of the DAC channels, you can call i2s_set_dac_mode instead.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error · ESP_FAIL IO error
esp_err_t i2s_set_pdm_rx_down_sample(i2s_port_t i2s_num, i2s_pdm_dsr_t downsample) Set PDM mode down-sample rate In PDM RX mode, there would be 2 rounds of downsample process in hardware. In the first downsample process, the sampling number can be 16 or 8. In the second downsample process, the sampling number is fixed as 8. So the clock frequency in PDM RX mode would be (fpcm * 64) or (fpcm * 128) accordingly.
Note After calling this function, it would call i2s_set_clk inside to update the clock frequency. Please call this function after I2S driver has been initialized.

Espressif Systems

579

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NO_MEM Out of memory
Parameters · i2s_num: I2S port number · downsample: i2s RX down sample rate for PDM mode.

esp_err_t i2s_set_pdm_tx_up_sample(i2s_port_t i2s_num, const i2s_pdm_tx_upsample_cfg_t

Set TX PDM mode up-sample rate.

*upsample_cfg)

Note If you have set PDM mode while calling mi2s_driver_installn, default PDM TX upsample parameters have already been set, no need to call this function again if you donnt have to change the default configuration
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NO_MEM Out of memory
Parameters · i2s_num: I2S port number · upsample_cfg: Set I2S PDM up-sample rate configuration

esp_err_t i2s_driver_install(i2s_port_t i2s_num, const i2s_config_t *i2s_config, int queue_size,

Install and start I2S driver.

void *i2s_queue)

This function must be called before any I2S driver read/write operations.

Parameters · i2s_num: I2S port number · i2s_config: I2S configurations - see i2s_config_t struct · queue_size: I2S event queue size/depth. · i2s_queue: I2S event queue handle, if set NULL, driver will not use an event queue.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NO_MEM Out of memory · ESP_ERR_INVALID_STATE Current I2S port is in use

esp_err_t i2s_driver_uninstall(i2s_port_t i2s_num) Uninstall I2S driver.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_INVALID_STATE I2S port has been uninstalled by others (e.g. LCD i80)
Parameters · i2s_num: I2S port number

esp_err_t i2s_write(i2s_port_t i2s_num, const void *src, size_t size, size_t *bytes_written, TickType_t ticks_to_wait)
Write data to I2S DMA transmit buffer.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2s_num: I2S port number · src: Source address to write from · size: Size of data in bytes · [out] bytes_written: Number of bytes written, if timeout, the result will be less than the size passed in.

Espressif Systems

580

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· ticks_to_wait: TX buffer wait timeout in RTOS ticks. If this many ticks pass without space becoming available in the DMA transmit buffer, then the function will return (note that if the data is written to the DMA buffer in pieces, the overall operation may still take longer than this timeout.) Pass portMAX_DELAY for no timeout.
esp_err_t i2s_write_expand(i2s_port_t i2s_num, const void *src, size_t size, size_t src_bits, size_t aim_bits, size_t *bytes_written, TickType_t ticks_to_wait)
Write data to I2S DMA transmit buffer while expanding the number of bits per sample. For example, expanding 16-bit PCM to 32-bit PCM.
Format of the data in source buffer is determined by the I2S configuration (see i2s_config_t).
Parameters · i2s_num: I2S port number · src: Source address to write from · size: Size of data in bytes · src_bits: Source audio bit · aim_bits: Bit wanted, no more than 32, and must be greater than src_bits · [out] bytes_written: Number of bytes written, if timeout, the result will be less than the size passed in. · ticks_to_wait: TX buffer wait timeout in RTOS ticks. If this many ticks pass without space becoming available in the DMA transmit buffer, then the function will return (note that if the data is written to the DMA buffer in pieces, the overall operation may still take longer than this timeout.) Pass portMAX_DELAY for no timeout.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
esp_err_t i2s_read(i2s_port_t i2s_num, void *dest, size_t size, size_t *bytes_read, TickType_t ticks_to_wait)
Read data from I2S DMA receive buffer.
Note If the built-in ADC mode is enabled, we should call i2s_adc_enable and i2s_adc_disable around the whole reading process, to prevent the data getting corrupted.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2s_num: I2S port number · dest: Destination address to read into · size: Size of data in bytes · [out] bytes_read: Number of bytes read, if timeout, bytes read will be less than the size passed in. · ticks_to_wait: RX buffer wait timeout in RTOS ticks. If this many ticks pass without bytes becoming available in the DMA receive buffer, then the function will return (note that if data is read from the DMA buffer in pieces, the overall operation may still take longer than this timeout.) Pass portMAX_DELAY for no timeout.
esp_err_t i2s_set_sample_rates(i2s_port_t i2s_num, uint32_t rate) Set sample rate used for I2S RX and TX.
The bit clock rate is determined by the sample rate and i2s_config_t configuration parameters (number of channels, bits_per_sample).
bit_clock = rate * (number of channels) * bits_per_sample
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NO_MEM Out of memory
Parameters · i2s_num: I2S port number

Espressif Systems

581

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· rate: I2S sample rate (ex: 8000, 44100l)
esp_err_t i2s_stop(i2s_port_t i2s_num) Stop I2S driver.
There is no need to call i2s_stop() before calling i2s_driver_uninstall().
Disables I2S TX/RX, until i2s_start() is called.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2s_num: I2S port number
esp_err_t i2s_start(i2s_port_t i2s_num) Start I2S driver.
It is not necessary to call this function after i2s_driver_install() (it is started automatically), however it is necessary to call it after i2s_stop().
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2s_num: I2S port number
esp_err_t i2s_zero_dma_buffer(i2s_port_t i2s_num) Zero the contents of the TX DMA buffer.
Pushes zero-byte samples into the TX DMA buffer, until it is full.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2s_num: I2S port number
esp_err_t i2s_pcm_config(i2s_port_t i2s_num, const i2s_pcm_cfg_t *pcm_cfg) Configure I2S a/u-law decompress or compress.
Note This function should be called after i2s driver installed Only take effecttive when the i2s mcommunication_formatnis set to mI2S_COMM_FORMAT_STAND_PCM_SHORTnor mI2S_COMM_FORMAT_STAND_PCM_LONGn
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · i2s_num: I2S port number · pcm_cfg: including mode selection and a/u-law decompress or compress configuration paramater
esp_err_t i2s_set_clk(i2s_port_t i2s_num, uint32_t rate, uint32_t bits_cfg, i2s_channel_t ch) Set clock & bit width used for I2S RX and TX.
Similar to i2s_set_sample_rates(), but also sets bit width.
1. stop i2s; 2. calculate mclk, bck, bck_factor 3. malloc dma buffer; 4. start i2s
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NO_MEM Out of memory
Parameters

Espressif Systems

582

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· i2s_num: I2S port number · rate: I2S sample rate (ex: 8000, 44100l) · bits_cfg: I2S bits configuration the low 16 bits is for data bits per sample in one channel (see mi2s_bits_per_sample_tn) the high 16 bits is for total bits in one channel (seemi2s_bits_per_chan_tn
) high 16bits =0 means same as the bits per sample. · ch: I2S channel, (I2S_CHANNEL_MONO, I2S_CHANNEL_STEREO or specific channel in
TDM mode)
float i2s_get_clk(i2s_port_t i2s_num) get clock set on particular port number.
Return · actual clock set by i2s driver
Parameters · i2s_num: I2S port number

Structures struct i2s_pcm_cfg_t
I2S PCM configuration.

Public Members
i2s_pcm_compress_t pcm_type I2S PCM a/u-law decompress or compress type
struct i2s_pdm_tx_upsample_cfg_t I2S PDM up-sample rate configuration.
Note TX PDM can only be set to the following two upsampling rate configurations: 1: fp = 960, fs = sample_rate / 100, in this case, Fpdm = 128*48000 2: fp = 960, fs = 480, in this case, Fpdm = 128*Fpcm = 128*sample_rate If the pdm receiver do not care the pdm serial clock, itns recommended set Fpdm = 128*48000. Otherwise, the second configuration should be applied.

Public Members
int sample_rate I2S PDM sample rate
int fp I2S PDM TX upsampling paramater. Normally it should be set to 960
int fs I2S PDM TX upsampling paramater. When it is set to 480, the pdm clock frequency Fpdm = 128 * sample_rate, when it is set to sample_rate / 100Fpdm will be fixed to 128*48000
struct i2s_pin_config_t I2S pin number for i2s_set_pin.

Public Members
int mck_io_num MCK in out pin. Note that ESP32 supports setting MCK on GPIO0/GPIO1/GPIO3 only
int bck_io_num BCK in out pin
int ws_io_num WS in out pin
int data_out_num DATA out pin

Espressif Systems

583

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
int data_in_num DATA in pin
struct i2s_driver_config_t I2S driver configuration parameters.
Public Members
i2s_mode_t mode I2S work mode
uint32_t sample_rate I2S sample rate
i2s_bits_per_sample_t bits_per_sample I2S sample bits in one channel
i2s_channel_fmt_t channel_format I2S channel format.
i2s_comm_format_t communication_format I2S communication format
int intr_alloc_flags Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info
int dma_desc_num The total number of descriptors used by I2S DMA to receive/transmit data
int dma_buf_count This is an alias to mdma_desc_numnfor backward compatibility
int dma_frame_num Number of frames for one-time sampling. The frame here means the total data from all the channels in a WS cycle
int dma_buf_len This is an alias to mdma_frame_numnfor backward compatibility
bool use_apll I2S using APLL as main I2S clock, enable it to get accurate clock
bool tx_desc_auto_clear I2S auto clear tx descriptor if there is underflow condition (helps in avoiding noise in case of data unavailability)
int fixed_mclk I2S using fixed MCLK output. If use_apll = true and fixed_mclk > 0, then the clock output for i2s is fixed and equal to the fixed_mclk value. If fixed_mclk set, mclk_multiple wonnt take effect
i2s_mclk_multiple_t mclk_multiple The multiple of I2S master clock(MCLK) to sample rate
i2s_bits_per_chan_t bits_per_chan I2S total bits in one channelonly take effect when larger thanmbits_per_samplen, defaultm0nmeans equal to mbits_per_samplen
i2s_channel_t chan_mask I2S active channel bit mask, set value in i2s_channel_t to enable specific channel, the bit map of active channel can not exceed (0x1<<total_chan).
uint32_t total_chan I2S Total number of channels. If it is smaller than the biggest active channel number, it will be set to this number automatically.

Espressif Systems

584

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
bool left_align Set to enable left alignment
bool big_edin Set to enable big edin
bool bit_order_msb Set to enable msb order
bool skip_msk Set to enable skip mask. If it is enabled, only the data of the enabled channels will be sent, otherwise all data stored in DMA TX buffer will be sent
struct i2s_event_t Event structure used in I2S event queue.
Public Members
i2s_event_type_t type I2S event type
size_t size I2S data size for I2S_DATA event
Macros I2S_PIN_NO_CHANGE
Use in i2s_pin_config_t for pins which should not be changed I2S_PDM_DEFAULT_UPSAMPLE_CONFIG(rate)
Default I2S PDM Up-Sampling Rate configuration.
Type Definitions typedef i2s_driver_config_t i2s_config_t typedef intr_handle_t i2s_isr_handle_t
Enumerations enum i2s_port_t
I2S port number, the max port number is (I2S_NUM_MAX -1). Values: I2S_NUM_0 = 0
I2S port 0 I2S_NUM_1 = 1
I2S port 1 I2S_NUM_MAX
I2S port max enum i2s_event_type_t
I2S event queue types. Values: I2S_EVENT_DMA_ERROR I2S_EVENT_TX_DONE
I2S DMA finish sent 1 buffer I2S_EVENT_RX_DONE
I2S DMA finish received 1 buffer

Espressif Systems

585

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
I2S_EVENT_TX_Q_OVF I2S DMA sent queue overflow
I2S_EVENT_RX_Q_OVF I2S DMA receive queue overflow
I2S_EVENT_MAX I2S event max index
Header File
· components/hal/include/hal/i2s_types.h
Enumerations enum i2s_bits_per_sample_t
I2S bit width per sample.
Values:
I2S_BITS_PER_SAMPLE_8BIT = 8 data bit-width: 8
I2S_BITS_PER_SAMPLE_16BIT = 16 data bit-width: 16
I2S_BITS_PER_SAMPLE_24BIT = 24 data bit-width: 24
I2S_BITS_PER_SAMPLE_32BIT = 32 data bit-width: 32
enum i2s_bits_per_chan_t I2S bit width per chan.
Values:
I2S_BITS_PER_CHAN_DEFAULT = (0) channel bit-width equals to data bit-width
I2S_BITS_PER_CHAN_8BIT = (8) channel bit-width: 8
I2S_BITS_PER_CHAN_16BIT = (16) channel bit-width: 16
I2S_BITS_PER_CHAN_24BIT = (24) channel bit-width: 24
I2S_BITS_PER_CHAN_32BIT = (32) channel bit-width: 32
enum i2s_channel_t I2S channel.
Values:
I2S_CHANNEL_MONO = (0x01 << 31) | 0x03 I2S channel (mono), two channel enabled. In this mode, you only need to send one channel data but the fifo will copy same data for another channel automatically, then both channels will transmit same data. The highest bit is for differentiating I2S_CHANNEL_STEREO since they both use two channels
I2S_CHANNEL_STEREO = 0x03 I2S channel (stereo), two channel enabled. In this mode, two channels will transmit different data.
I2S_TDM_ACTIVE_CH0 = (0x1 << 0) I2S channel 0 enabled

Espressif Systems

586

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
I2S_TDM_ACTIVE_CH1 = (0x1 << 1) I2S channel 1 enabled
I2S_TDM_ACTIVE_CH2 = (0x1 << 2) I2S channel 2 enabled
I2S_TDM_ACTIVE_CH3 = (0x1 << 3) I2S channel 3 enabled
I2S_TDM_ACTIVE_CH4 = (0x1 << 4) I2S channel 4 enabled
I2S_TDM_ACTIVE_CH5 = (0x1 << 5) I2S channel 5 enabled
I2S_TDM_ACTIVE_CH6 = (0x1 << 6) I2S channel 6 enabled
I2S_TDM_ACTIVE_CH7 = (0x1 << 7) I2S channel 7 enabled
I2S_TDM_ACTIVE_CH8 = (0x1 << 8) I2S channel 8 enabled
I2S_TDM_ACTIVE_CH9 = (0x1 << 9) I2S channel 9 enabled
I2S_TDM_ACTIVE_CH10 = (0x1 << 10) I2S channel 10 enabled
I2S_TDM_ACTIVE_CH11 = (0x1 << 11) I2S channel 11 enabled
I2S_TDM_ACTIVE_CH12 = (0x1 << 12) I2S channel 12 enabled
I2S_TDM_ACTIVE_CH13 = (0x1 << 13) I2S channel 13 enabled
I2S_TDM_ACTIVE_CH14 = (0x1 << 14) I2S channel 14 enabled
I2S_TDM_ACTIVE_CH15 = (0x1 << 15) I2S channel 15 enabled
enum i2s_comm_format_t I2S communication standard format.
Values:
I2S_COMM_FORMAT_STAND_I2S = 0X01 I2S communication I2S Philips standard, data launch at second BCK
I2S_COMM_FORMAT_STAND_MSB = 0X02 I2S communication MSB alignment standard, data launch at first BCK
I2S_COMM_FORMAT_STAND_PCM_SHORT = 0x04 PCM Short standard, also known as DSP mode. The period of synchronization signal (WS) is 1 bck cycle.
I2S_COMM_FORMAT_STAND_PCM_LONG = 0x0C PCM Long standard. The period of synchronization signal (WS) is channel_bit*bck cycles.
I2S_COMM_FORMAT_STAND_MAX standard max
I2S_COMM_FORMAT_I2S = 0x01 I2S communication format I2S, correspond to I2S_COMM_FORMAT_STAND_I2S

Espressif Systems

587

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

I2S_COMM_FORMAT_I2S_MSB = 0x01 I2S format MSB, (I2S_COMM_FORMAT_I2S |I2S_COMM_FORMAT_I2S_MSB) correspond to I2S_COMM_FORMAT_STAND_I2S
I2S_COMM_FORMAT_I2S_LSB = 0x02 I2S format LSB, (I2S_COMM_FORMAT_I2S |I2S_COMM_FORMAT_I2S_LSB) correspond to I2S_COMM_FORMAT_STAND_MSB
I2S_COMM_FORMAT_PCM = 0x04 I2S communication format PCM, correspond to I2S_COMM_FORMAT_STAND_PCM_SHORT
I2S_COMM_FORMAT_PCM_SHORT = 0x04 PCM Short, (I2S_COMM_FORMAT_PCM | I2S_COMM_FORMAT_PCM_SHORT) correspond to I2S_COMM_FORMAT_STAND_PCM_SHORT
I2S_COMM_FORMAT_PCM_LONG = 0x08 PCM Long, (I2S_COMM_FORMAT_PCM | I2S_COMM_FORMAT_PCM_LONG) correspond to I2S_COMM_FORMAT_STAND_PCM_LONG
enum i2s_channel_fmt_t I2S channel format type.
Values:
I2S_CHANNEL_FMT_RIGHT_LEFT Separated left and right channel
I2S_CHANNEL_FMT_ALL_RIGHT Load right channel data in both two channels
I2S_CHANNEL_FMT_ALL_LEFT Load left channel data in both two channels
I2S_CHANNEL_FMT_ONLY_RIGHT Only load data in right channel (mono mode)
I2S_CHANNEL_FMT_ONLY_LEFT Only load data in left channel (mono mode)
I2S_CHANNEL_FMT_MULTIPLE More than two channels are used
enum i2s_mode_t I2S Mode.
Values:
I2S_MODE_MASTER = (0x1 << 0) Master mode
I2S_MODE_SLAVE = (0x1 << 1) Slave mode
I2S_MODE_TX = (0x1 << 2) TX mode
I2S_MODE_RX = (0x1 << 3) RX mode
I2S_MODE_PDM = (0x1 << 6) I2S PDM mode
enum i2s_clock_src_t I2S source clock.
Values:
I2S_CLK_D2CLK = 0 Clock from PLL_D2_CLK(160M)

Espressif Systems

588

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
enum i2s_mclk_multiple_t The multiple of mclk to sample rate.
Values:
I2S_MCLK_MULTIPLE_DEFAULT = 0 Default value. mclk = sample_rate * 256
I2S_MCLK_MULTIPLE_128 = 128 mclk = sample_rate * 128
I2S_MCLK_MULTIPLE_256 = 256 mclk = sample_rate * 256
I2S_MCLK_MULTIPLE_384 = 384 mclk = sample_rate * 384
enum i2s_pcm_compress_t A/U-law decompress or compress configuration.
Values:
I2S_PCM_DISABLE = 0 Disable A/U law decopress or compress
I2S_PCM_A_DECOMPRESS A-law decompress
I2S_PCM_A_COMPRESS A-law compress
I2S_PCM_U_DECOMPRESS U-law decompress
I2S_PCM_U_COMPRESS U-law compress
enum i2s_pdm_dsr_t I2S PDM RX downsample mode.
Values:
I2S_PDM_DSR_8S = 0 downsampling number is 8 for PDM RX mode
I2S_PDM_DSR_16S downsampling number is 16 for PDM RX mode
I2S_PDM_DSR_MAX
enum i2s_pdm_sig_scale_t Values:
I2S_PDM_SIG_SCALING_DIV_2 = 0 I2S TX PDM sigmadelta signal scaling: /2
I2S_PDM_SIG_SCALING_MUL_1 = 1 I2S TX PDM sigmadelta signal scaling: x1
I2S_PDM_SIG_SCALING_MUL_2 = 2 I2S TX PDM sigmadelta signal scaling: x2
I2S_PDM_SIG_SCALING_MUL_4 = 3 I2S TX PDM sigmadelta signal scaling: x4
2.3.9 LCD

Espressif Systems

589

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Introduction
ESP chips can generate various kinds of timings that needed by common LCDs on the market, like SPI LCD, I80 LCD (a.k.a Intel 8080 parallel LCD), RGB LCD, I2C LCD, etc. The esp_lcd component is officially to support those LCDs with a group of universal APIs across chips.

Functional Overview
In esp_lcd, an LCD panel is represented by esp_lcd_panel_handle_t, which plays the role of an abstract frame buffer, regardless of the frame memory is allocated inside ESP chip or in external LCD controller. Based on the location of the frame buffer, the LCD panel allocation functions are mainly grouped into the following categories:
· RGB LCD panel - is simply based on a group of specific synchronous signals indicating where to start and stop a frame.
· Controller based LCD panel involves multiple steps to get a panel handle, like bus allocation, IO device registration and controller driver install.
After we get the LCD handle, the remaining LCD operations are the same for different LCD interfaces and vendors.

Application Example
LCD examples are located under: peripherals/lcd:
· Jpeg decoding and LCD display - peripherals/lcd/tjpgd · i80 controller based LCD and LVGL animation UI - peripherals/lcd/i80_controller · GC9A01 user customized driver and dash board UI - peripherals/lcd/gc9a01 · RGB panel example with scatter chart UI - peripherals/lcd/rgb_panel · I2C interfaced OLED display scrolling text - peripherals/lcd/i2c_oled

API Reference
Header File · components/hal/include/hal/lcd_types.h

Enumerations enum lcd_clock_source_t
LCD clock source.
Note User should select the clock source based on the real requirement:

LCD clock source LCD_CLK_SRC_PLL160M LCD_CLK_SRC_APLL LCD_CLK_SRC_XTAL

Features High resolution Configurable resolution Medium resolution

Power Management ESP_PM_APB_FREQ_MAX lock ESP_PM_NO_LIGHT_SLEEP lock No PM lock

Values:
LCD_CLK_SRC_PLL160M Select PLL160M as the source clock
LCD_CLK_SRC_APLL Select APLL as the source clock
LCD_CLK_SRC_XTAL Select XTAL as the source clock

Espressif Systems

590

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Header File · components/esp_lcd/include/esp_lcd_types.h

Type Definitions typedef struct esp_lcd_panel_io_t *esp_lcd_panel_io_handle_t
Type of LCD panel IO handle typedef struct esp_lcd_panel_t *esp_lcd_panel_handle_t
Type of LCD panel handle

Enumerations enum esp_lcd_color_space_t
LCD color space type definition.
Values:
ESP_LCD_COLOR_SPACE_RGB Color space: RGB
ESP_LCD_COLOR_SPACE_BGR Color space: BGR
ESP_LCD_COLOR_SPACE_MONOCHROME Color space: monochrome

Header File · components/esp_lcd/include/esp_lcd_panel_io.h

Functions esp_err_t esp_lcd_panel_io_tx_param(esp_lcd_panel_io_handle_t io, int lcd_cmd, const void
*param, size_t param_size) Transmit LCD command and corresponding parameters.

Note Commands sent by this function are short, so they are sent using polling transactions. The func-

tion does not return before the command tranfer is completed. If any queued transactions sent by

esp_lcd_panel_io_tx_color() are still pending when this function is called, this function will

wait until they are finished and the queue is empty before sending the command(s).

Return

· ESP_ERR_INVALID_ARG if parameter is invalid

· ESP_OK on success

Parameters

· [in] io: LCD panel IO handle, which is created by other factory API like

esp_lcd_new_panel_io_spi()

· [in] lcd_cmd: The specific LCD command

· [in] param: Buffer that holds the command specific parameters, set to NULL if no parameter

is needed for the command

· [in] param_size: Size of param in memory, in bytes, set to zero if no parameter is needed

for the command

esp_err_t esp_lcd_panel_io_tx_color(esp_lcd_panel_io_handle_t io, int lcd_cmd, const void

Transmit LCD RGB data.

*color, size_t color_size)

Note This function will package the command and RGB data into a transaction, and push into a queue. The real transmission is performed in the background (DMA+interrupt). The caller should take care of the lifecycle of the color buffer. Recycling of color buffer should be done in the callback on_color_trans_done().
Return · ESP_ERR_INVALID_ARG if parameter is invalid · ESP_OK on success

Espressif Systems

591

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Parameters · [in] io: LCD panel IO handle, which is created by factory API like esp_lcd_new_panel_io_spi() · [in] lcd_cmd: The specific LCD command · [in] color: Buffer that holds the RGB color data · [in] color_size: Size of color in memory, in bytes

esp_err_t esp_lcd_panel_io_del(esp_lcd_panel_io_handle_t io) Destory LCD panel IO handle (deinitialize panel and free all corresponding resource)

Return · ESP_ERR_INVALID_ARG if parameter is invalid · ESP_OK on success
Parameters · [in] io: LCD panel IO handle, which is created by factory API like esp_lcd_new_panel_io_spi()

esp_err_t esp_lcd_new_panel_io_spi(esp_lcd_spi_bus_handle_t

bus,

esp_lcd_panel_io_spi_config_t

esp_lcd_panel_io_handle_t *ret_io)

Create LCD panel IO handle, for SPI interface.

const *io_config,

Return · ESP_ERR_INVALID_ARG if parameter is invalid · ESP_ERR_NO_MEM if out of memory · ESP_OK on success
Parameters · [in] bus: SPI bus handle · [in] io_config: IO configuration, for SPI interface · [out] ret_io: Returned IO handle

esp_err_t esp_lcd_new_panel_io_i2c(esp_lcd_i2c_bus_handle_t

bus,

esp_lcd_panel_io_i2c_config_t

esp_lcd_panel_io_handle_t *ret_io)

Create LCD panel IO handle, for I2C interface.

const *io_config,

Return · ESP_ERR_INVALID_ARG if parameter is invalid · ESP_ERR_NO_MEM if out of memory · ESP_OK on success
Parameters · [in] bus: I2C bus handle · [in] io_config: IO configuration, for I2C interface · [out] ret_io: Returned IO handle

esp_err_t esp_lcd_new_i80_bus(const

esp_lcd_i80_bus_config_t

esp_lcd_i80_bus_handle_t *ret_bus) Create Intel 8080 bus handle.

*bus_config,

Return · ESP_ERR_INVALID_ARG if parameter is invalid · ESP_ERR_NO_MEM if out of memory · ESP_ERR_NOT_FOUND if no free bus is available · ESP_OK on success
Parameters · [in] bus_config: Bus configuration · [out] ret_bus: Returned bus handle

esp_err_t esp_lcd_del_i80_bus(esp_lcd_i80_bus_handle_t bus) Destory Intel 8080 bus handle.

Return · ESP_ERR_INVALID_ARG if parameter is invalid · ESP_ERR_INVALID_STATE if there still be some device attached to the bus

Espressif Systems

592

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_OK on success Parameters
· [in] bus: Intel 8080 bus handle, created by esp_lcd_new_i80_bus()

esp_err_t esp_lcd_new_panel_io_i80(esp_lcd_i80_bus_handle_t

bus,

esp_lcd_panel_io_i80_config_t

esp_lcd_panel_io_handle_t *ret_io)

Create LCD panel IO, for Intel 8080 interface.

const *io_config,

Return · ESP_ERR_INVALID_ARG if parameter is invalid · ESP_ERR_NOT_SUPPORTED if some configuration cannt be satisfied, e.g. pixel clock out of the range · ESP_ERR_NO_MEM if out of memory · ESP_OK on success
Parameters · [in] bus: Intel 8080 bus handle, created by esp_lcd_new_i80_bus() · [in] io_config: IO configuration, for i80 interface · [out] ret_io: Returned panel IO handle

Structures struct esp_lcd_panel_io_event_data_t
Type of LCD panel IO event data. struct esp_lcd_panel_io_spi_config_t
Panel IO configuration structure, for SPI interface.

Public Members
int cs_gpio_num GPIO used for CS line
int dc_gpio_num GPIO used to select the D/C line, set this to -1 if the D/C line not controlled by manually pulling high/low GPIO
int spi_mode Traditional SPI mode (0~3)
unsigned int pclk_hz Frequency of pixel clock
size_t trans_queue_depth Size of internal transaction queue
esp_lcd_panel_io_color_trans_done_cb_t on_color_trans_done Callback invoked when color data transfer has finished
void *user_ctx User private data, passed directly to on_color_trans_donens user_ctx
int lcd_cmd_bits Bit-width of LCD command
int lcd_param_bits Bit-width of LCD parameter
unsigned int dc_as_cmd_phase : 1 D/C line value is encoded into SPI transaction command phase
unsigned int dc_low_on_data : 1 If this flag is enabled, DC line = 0 means transfer data, DC line = 1 means transfer command; vice versa

Espressif Systems

593

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
unsigned int octal_mode : 1 transmit with octal mode (8 data lines), this mode is used to simulate Intel 8080 timing
struct esp_lcd_panel_io_i2c_config_t
Public Members
uint32_t dev_addr I2C device address
esp_lcd_panel_io_color_trans_done_cb_t on_color_trans_done Callback invoked when color data transfer has finished
void *user_ctx User private data, passed directly to on_color_trans_donens user_ctx
size_t control_phase_bytes I2C LCD panel will encode control information (e.g. D/C seclection) into control phase, in several bytes
unsigned int dc_bit_offset Offset of the D/C selection bit in control phase
int lcd_cmd_bits Bit-width of LCD command
int lcd_param_bits Bit-width of LCD parameter
unsigned int dc_low_on_data : 1 If this flag is enabled, DC line = 0 means transfer data, DC line = 1 means transfer command; vice versa
struct esp_lcd_i80_bus_config_t LCD Intel 8080 bus configuration structure.
Public Members
int dc_gpio_num GPIO used for D/C line
int wr_gpio_num GPIO used for WR line
lcd_clock_source_t clk_src Clock source for the I80 LCD peripheral
int data_gpio_nums[(16)] GPIOs used for data lines
size_t bus_width Number of data lines, 8 or 16
size_t max_transfer_bytes Maximum transfer size, this determines the length of internal DMA link
size_t psram_trans_align DMA transfer alignment for data allocated from PSRAM
size_t sram_trans_align DMA transfer alignment for data allocated from SRAM
struct esp_lcd_panel_io_i80_config_t Panel IO configuration structure, for intel 8080 interface.

Espressif Systems

594

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Public Members
int cs_gpio_num GPIO used for CS line, set to -1 will declaim exclusively use of I80 bus
unsigned int pclk_hz Frequency of pixel clock
size_t trans_queue_depth Transaction queue size, larger queue, higher throughput
esp_lcd_panel_io_color_trans_done_cb_t on_color_trans_done Callback invoked when color data was tranferred done
void *user_ctx User private data, passed directly to on_color_trans_donens user_ctx
int lcd_cmd_bits Bit-width of LCD command
int lcd_param_bits Bit-width of LCD parameter
unsigned int dc_idle_level : 1 Level of DC line in IDLE phase
unsigned int dc_cmd_level : 1 Level of DC line in CMD phase
unsigned int dc_dummy_level : 1 Level of DC line in DUMMY phase
unsigned int dc_data_level : 1 Level of DC line in DATA phase
struct esp_lcd_panel_io_i80_config_t::[anonymous] dc_levels Each i80 device might have its own D/C control logic
unsigned int cs_active_high : 1 If set, a high level of CS line will select the device, otherwise, CS line is low level active
unsigned int reverse_color_bits : 1 Reverse the data bits, D[N:0] -> D[0:N]
unsigned int swap_color_bytes : 1 Swap adjacent two color bytes
unsigned int pclk_active_neg : 1 The display will write data lines when therens a falling edge on WR signal (a.k.a the PCLK)
unsigned int pclk_idle_low : 1 The WR signal (a.k.a the PCLK) stays at low level in IDLE phase

Type Definitions typedef void *esp_lcd_spi_bus_handle_t
Type of LCD SPI bus handle typedef void *esp_lcd_i2c_bus_handle_t
Type of LCD I2C bus handle
typedef struct esp_lcd_i80_bus_t *esp_lcd_i80_bus_handle_t Type of LCD intel 8080 bus handle
typedef bool (*esp_lcd_panel_io_color_trans_done_cb_t)(esp_lcd_panel_io_handle_t panel_io, esp_lcd_panel_io_event_data_t *edata, void *user_ctx)
Declare the prototype of the function that will be invoked when panel IO finishes transferring color data.

Espressif Systems

595

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return Whether a high priority task has been waken up by this function Parameters
· [in] panel_io: LCD panel IO handle, which is created by factory API like esp_lcd_new_panel_io_spi()
· [in] edata: Panel IO event data, fed by driver · [in] user_ctx: User data, passed from esp_lcd_panel_io_xxx_config_t

Header File · components/esp_lcd/include/esp_lcd_panel_ops.h

Functions esp_err_t esp_lcd_panel_reset(esp_lcd_panel_handle_t panel)
Reset LCD panel.

Note Panel reset must be called before attempting to initialize the panel using esp_lcd_panel_init(). Return
· ESP_OK on success Parameters
· [in] panel: LCD panel handle, which is created by other factory API like esp_lcd_new_panel_st7789()
esp_err_t esp_lcd_panel_init(esp_lcd_panel_handle_t panel) Initialize LCD panel.

Note Before calling this function, make sure the LCD panel has finished the reset stage by esp_lcd_panel_reset().
Return · ESP_OK on success
Parameters · [in] panel: LCD panel handle, which is created by other factory API like esp_lcd_new_panel_st7789()

esp_err_t esp_lcd_panel_del(esp_lcd_panel_handle_t panel) Deinitialize the LCD panel.

Return · ESP_OK on success
Parameters · [in] panel: LCD panel handle, which is created by other factory API like esp_lcd_new_panel_st7789()

esp_err_t esp_lcd_panel_draw_bitmap(esp_lcd_panel_handle_t panel, int x_start, int y_start, int

Draw bitmap on LCD panel.

x_end, int y_end, const void *color_data)

Return · ESP_OK on success
Parameters · [in] panel: LCD panel handle, which is created by other factory API like esp_lcd_new_panel_st7789() · [in] x_start: Start index on x-axis (x_start included) · [in] y_start: Start index on y-axis (y_start included) · [in] x_end: End index on x-axis (x_end not included) · [in] y_end: End index on y-axis (y_end not included) · [in] color_data: RGB color data that will be dumped to the specific window range

esp_err_t esp_lcd_panel_mirror(esp_lcd_panel_handle_t panel, bool mirror_x, bool mirror_y) Mirror the LCD panel on specific axis.

Note Combined with esp_lcd_panel_swap_xy(), one can realize screen rotation Return

Espressif Systems

596

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· ESP_OK on success · ESP_ERR_NOT_SUPPORTED if this function is not supported by the panel Parameters · [in] panel: LCD panel handle, which is created by other factory API like
esp_lcd_new_panel_st7789() · [in] mirror_x: Whether the panel will be mirrored about the x axis · [in] mirror_y: Whether the panel will be mirrored about the y axis
esp_err_t esp_lcd_panel_swap_xy(esp_lcd_panel_handle_t panel, bool swap_axes) Swap/Exchange x and y axis.
Note Combined with esp_lcd_panel_mirror(), one can realize screen rotation Return
· ESP_OK on success · ESP_ERR_NOT_SUPPORTED if this function is not supported by the panel Parameters · [in] panel: LCD panel handle, which is created by other factory API like
esp_lcd_new_panel_st7789() · [in] swap_axes: Whether to swap the x and y axis
esp_err_t esp_lcd_panel_set_gap(esp_lcd_panel_handle_t panel, int x_gap, int y_gap) Set extra gap in x and y axis.
The gap is the space (in pixels) between the left/top sides of the LCD panel and the first row/column respectively of the actual contents displayed.
Note Setting a gap is useful when positioning or centering a frame that is smaller than the LCD. Return
· ESP_OK on success Parameters
· [in] panel: LCD panel handle, which is created by other factory API like esp_lcd_new_panel_st7789()
· [in] x_gap: Extra gap on x axis, in pixels · [in] y_gap: Extra gap on y axis, in pixels
esp_err_t esp_lcd_panel_invert_color(esp_lcd_panel_handle_t panel, bool invert_color_data) Invert the color (bit-wise invert the color data line)
Return · ESP_OK on success
Parameters · [in] panel: LCD panel handle, which is created by other factory API like esp_lcd_new_panel_st7789() · [in] invert_color_data: Whether to invert the color data
esp_err_t esp_lcd_panel_disp_off(esp_lcd_panel_handle_t panel, bool off) Turn off the display.
Return · ESP_OK on success · ESP_ERR_NOT_SUPPORTED if this function is not supported by the panel
Parameters · [in] panel: LCD panel handle, which is created by other factory API like esp_lcd_new_panel_st7789() · [in] off: Whether to turn off the screen
Header File
· components/esp_lcd/include/esp_lcd_panel_rgb.h
Functions

Espressif Systems

597

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t esp_lcd_new_rgb_panel(const esp_lcd_rgb_panel_config_t

Create RGB LCD panel.

esp_lcd_panel_handle_t *ret_panel)

Return · ESP_ERR_INVALID_ARG if parameter is invalid · ESP_ERR_NO_MEM if out of memory · ESP_ERR_NOT_FOUND if no free RGB panel is available · ESP_OK on success
Parameters · rgb_panel_config: RGB panel configuration · ret_panel: Returned LCD panel handle

*rgb_panel_config,

Structures struct esp_lcd_rgb_timing_t
LCD RGB timing structure.

*

*

--->

*

 HFP

*

<--->

*

|____|

*

|

|

*

|

|

*

|

|

*

|

|

*

|

|

*

|

|

*

|

|

*

|

|

*

|

|

*

|

|

*

|

|

* Total

|

|

* Height

|

|

*

|

|

*

|

|

*

|

|

*

|

|

*

|

|

Total Width <------------------------------------------------

HSYNC width HBP

Active Width



<---><--><-------------------------------------->

____ ____|_______________________________________

|___| |



|



__|

|



/|\ /|\ |

|



| VSYNC| |

|



|Width\|/ |__

|



|

/|\

|

|



| VBP |

|

|



|

\|/_____|_________|_______________________________________

|

/|\

|

| / / / / / / / / / / / / / / / / / / /

|

|

|

|/ / / / / / / / / / / / / / / / / / / /

|

|

|

|/ / / / / / / / / / / / / / / / / / / /

|

|

|

|/ / / / / / / / / / / / / / / / / / / /

|Active|

|

|/ / / / / / / / / / / / / / / / / / / /

|Heigh |

|

|/ / / / / / Active Display Area / / / /

|

|

|

|/ / / / / / / / / / / / / / / / / / / /

|

|

|

|/ / / / / / / / / / / / / / / / / / / /

|

|

|

|/ / / / / / / / / / / / / / / / / / / / (continues on next page)

Espressif Systems

598

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

*

|

|

*

|

|

*

|

|

*



|

*



|

*

____|

*

|

|

|

(continued from previous page) |/ / / / / / / / / / / / / / / / / / / /

|

|

|

|/ / / / / / / / / / / / / / / / / / / /

|

\|/_____|_________|_______________________________________

|

/|\

|



| VFP |

|



\|/ \|/_____|__________________________________________________

Public Members
unsigned int pclk_hz Frequency of pixel clock
unsigned int h_res Horizontal resolution, i.e. the number of pixels in a line
unsigned int v_res Vertical resolution, i.e. the number of lines in the frame
unsigned int hsync_pulse_width Horizontal sync width, unit: PCLK period
unsigned int hsync_back_porch Horizontal back porch, number of PCLK between hsync and start of line active data
unsigned int hsync_front_porch Horizontal front porch, number of PCLK between the end of active data and the next hsync
unsigned int vsync_pulse_width Vertical sync width, unit: number of lines
unsigned int vsync_back_porch Vertical back porch, number of invalid lines between vsync and start of frame
unsigned int vsync_front_porch Vertical front porch, number of invalid lines between then end of frame and the next vsync
unsigned int hsync_idle_low : 1 The hsync signal is low in IDLE state
unsigned int vsync_idle_low : 1 The vsync signal is low in IDLE state
unsigned int de_idle_high : 1 The de signal is high in IDLE state
unsigned int pclk_active_neg : 1 Whether the display data is clocked out at the falling edge of PCLK
unsigned int pclk_idle_high : 1 The PCLK stays at high level in IDLE phase
struct esp_lcd_rgb_panel_event_data_t Type of RGB LCD panel event data.
struct esp_lcd_rgb_panel_config_t LCD RGB panel configuration structure.

Espressif Systems

599

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Public Members
lcd_clock_source_t clk_src Clock source for the RGB LCD peripheral
esp_lcd_rgb_timing_t timings RGB timing parameters
size_t data_width Number of data lines
size_t sram_trans_align Alignment for framebuffer that allocated in SRAM
size_t psram_trans_align Alignment for framebuffer that allocated in PSRAM
int hsync_gpio_num GPIO used for HSYNC signal
int vsync_gpio_num GPIO used for VSYNC signal
int de_gpio_num GPIO used for DE signal, set to -1 if itns not used
int pclk_gpio_num GPIO used for PCLK signal
int data_gpio_nums[(16)] GPIOs used for data lines
int disp_gpio_num GPIO used for display control signal, set to -1 if itns not used
esp_lcd_rgb_panel_frame_trans_done_cb_t on_frame_trans_done Callback invoked when one frame buffer has transferred done
void *user_ctx User data which would be passed to on_frame_trans_donens user_ctx
unsigned int disp_active_low : 1 If this flag is enabled, a low level of display control signal can turn the screen on; vice versa
unsigned int relax_on_idle : 1 If this flag is enabled, the host wonnt refresh the LCD if nothing changed in hostns frame buffer (this is usefull for LCD with built-in GRAM)
unsigned int fb_in_psram : 1 If this flag is enabled, the frame buffer will be allocated from PSRAM preferentially
Type Definitions typedef bool (*esp_lcd_rgb_panel_frame_trans_done_cb_t)(esp_lcd_panel_handle_t
panel, esp_lcd_rgb_panel_event_data_t *edata, void *user_ctx) Declare the prototype of the function that will be invoked when panel IO finishes transferring color data.
Return Whether a high priority task has been waken up by this function Parameters
· [in] panel: LCD panel handle, returned from esp_lcd_new_rgb_panel · [in] edata: Panel event data, fed by driver · [in] user_ctx: User data, passed from esp_lcd_rgb_panel_config_t

Espressif Systems

600

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Header File · components/esp_lcd/include/esp_lcd_panel_vendor.h

Functions

esp_err_t esp_lcd_new_panel_st7789(const esp_lcd_panel_io_handle_t io, const

esp_lcd_panel_dev_config_t

*panel_dev_config,

esp_lcd_panel_handle_t *ret_panel)

Create LCD panel for model ST7789.

Return

· ESP_ERR_INVALID_ARG if parameter is invalid

· ESP_ERR_NO_MEM if out of memory

· ESP_OK on success

Parameters

· [in] io: LCD panel IO handle

· [in] panel_dev_config: general panel device configuration

· [out] ret_panel: Returned LCD panel handle

esp_err_t esp_lcd_new_panel_nt35510(const esp_lcd_panel_io_handle_t io, const

esp_lcd_panel_dev_config_t

*panel_dev_config,

esp_lcd_panel_handle_t *ret_panel) Create LCD panel for model NT35510.

Return · ESP_ERR_INVALID_ARG if parameter is invalid · ESP_ERR_NO_MEM if out of memory · ESP_OK on success
Parameters · [in] io: LCD panel IO handle · [in] panel_dev_config: general panel device configuration · [out] ret_panel: Returned LCD panel handle

esp_err_t esp_lcd_new_panel_ssd1306(const esp_lcd_panel_io_handle_t io, const

esp_lcd_panel_dev_config_t

*panel_dev_config,

esp_lcd_panel_handle_t *ret_panel)

Create LCD panel for model SSD1306.

Return · ESP_ERR_INVALID_ARG if parameter is invalid · ESP_ERR_NO_MEM if out of memory · ESP_OK on success
Parameters · [in] io: LCD panel IO handle · [in] panel_dev_config: general panel device configuration · [out] ret_panel: Returned LCD panel handle

Structures struct esp_lcd_panel_dev_config_t
Configuration structure for panel device.

Public Members
int reset_gpio_num GPIO used to reset the LCD panel, set to -1 if itns not used
esp_lcd_color_space_t color_space Set the color space used by the LCD panel
unsigned int bits_per_pixel Color depth, in bpp

Espressif Systems

601

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
unsigned int reset_active_high : 1 Setting this if the panel reset is high level active
2.3.10 LED Control (LEDC)
Introduction
The LED control (LEDC) peripheral is primarily designed to control the intensity of LEDs, although it can also be used to generate PWM signals for other purposes. It has 8 channels which can generate independent waveforms that can be used, for example, to drive RGB LED devices. The PWM controller can automatically increase or decrease the duty cycle gradually, allowing for fades without any processor interference.
Functionality Overview
Setting up a channel of the LEDC is done in three steps. Note that unlike ESP32, ESP32-S3 only supports configuring channels in olow speedpmode.
1. Timer Configuration by specifying the PWM signalns frequency and duty cycle resolution. 2. Channel Configuration by associating it with the timer and GPIO to output the PWM signal. 3. Change PWM Signal that drives the output in order to change LEDns intensity. This can be done under the
full control of software or with hardware fading functions. As an optional step, it is also possible to set up an interrupt on fade end.

Fig. 7: Key Settings of LED PWM Controllerns API
Timer Configuration Setting the timer is done by calling the function ledc_timer_config() and passing the data structure ledc_timer_config_t that contains the following configuration settings:
· Speed mode (value must be LEDC_LOW_SPEED_MODE) · Timer number ledc_timer_t · PWM signal frequency · Resolution of PWM duty · Source clock ledc_clk_cfg_t

Espressif Systems

602

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

The frequency and the duty resolution are interdependent. The higher the PWM frequency, the lower the duty resolution which is available, and vice versa. This relationship might be important if you are planning to use this API for purposes other than changing the intensity of LEDs. For more details, see Section Supported Range of Frequency and Duty Resolutions.
The source clock can also limit the PWM frequency. The higher the source clock frequency, the higher the maximum PWM frequency can be configured.

Clock name APB_CLK RTC20M_CLK
XTAL_CLK

Table 4: Characteristics of ESP32-S3 LEDC source clocks

Clock freq 80 MHz

Clock capabilities /

~20 MHz

Dynamic Frequency Scaling compatible, Light sleep compatible

40 MHz

Dynamic Frequency Scaling compatible

Note: For ESP32-S3, all timers share one clock source. In other words, it is impossible to use different clock sources for different timers.

Channel Configuration When the timer is set up, configure the desired channel (one out of ledc_channel_t). This is done by calling the function ledc_channel_config().
Similar to the timer configuration, the channel setup function should be passed a structure ledc_channel_config_t that contains the channelns configuration parameters.
At this point, the channel should start operating and generating the PWM signal on the selected GPIO, as configured in ledc_channel_config_t, with the frequency specified in the timer settings and the given duty cycle. The channel operation (signal generation) can be suspended at any time by calling the function ledc_stop().
Change PWM Signal Once the channel starts operating and generating the PWM signal with the constant duty cycle and frequency, there are a couple of ways to change this signal. When driving LEDs, primarily the duty cycle is changed to vary the light intensity.
The following two sections describe how to change the duty cycle using software and hardware fading. If required, the signalns frequency can also be changed; it is covered in Section Change PWM Frequency.
Note: All the timers and channels in the ESP32-S3ns LED PWM Controller only support low speed mode. Any change of PWM settings must be explicitly triggered by software (see below).

Change PWM Duty Cycle Using Software To set the duty cycle, use the dedicated function ledc_set_duty(). After that, call ledc_update_duty() to activate the changes. To check the currently set value, use the corresponding _get_ function ledc_get_duty().
Another way to set the duty cycle, as well as some other channel parameters, is by calling ledc_channel_config() covered in Section Channel Configuration.
The range of the duty cycle values passed to functions depends on selected duty_resolution and should be from 0 to (2 ** duty_resolution) - 1. For example, if the selected duty resolution is 10, then the duty cycle values can range from 0 to 1023. This provides the resolution of ~0.1%.
Change PWM Duty Cycle using Hardware The LEDC hardware provides the means to gradually transition from one duty cycle value to another. To use this functionality, enable fading with ledc_fade_func_install() and then configure it by calling one of the available fading functions:
· ledc_set_fade_with_time()

Espressif Systems

603

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· ledc_set_fade_with_step() · ledc_set_fade()
Start fading with ledc_fade_start(). A fade can be operated in blocking or non-blocking mode, please check ledc_fade_mode_t for the difference between the two available fade modes. Note that with either fade mode, the next fade or fixed-duty update will not take effect until the last fade finishes or is stopped. ledc_fade_stop() has to be called to stop a fade that is in progress.
To get a notification about the completion of a fade operation, a fade end callback function can be registered for each channel by calling ledc_cb_register() after the fade service being installed.
If not required anymore, fading and an associated interrupt can be disabled with ledc_fade_func_uninstall().
Change PWM Frequency The LEDC API provides several ways to change the PWM frequency oon the flyp:
· Set the frequency by calling ledc_set_freq(). There is a corresponding function ledc_get_freq() to check the current frequency.
· Change the frequency and the duty resolution by calling ledc_bind_channel_timer() to bind some other timer to the channel.
· Change the channelns timer by calling ledc_channel_config().
More Control Over PWM There are several lower level timer-specific functions that can be used to change PWM settings:
· ledc_timer_set() · ledc_timer_rst() · ledc_timer_pause() · ledc_timer_resume()
The first two functions are called obehind the scenespby ledc_channel_config() to provide a startup of a timer after it is configured.
Use Interrupts When configuring an LEDC channel, one of the parameters selected within ledc_channel_config_t is ledc_intr_type_t which triggers an interrupt on fade completion.
For registration of a handler to address this interrupt, call ledc_isr_register().
Supported Range of Frequency and Duty Resolutions
The LED PWM Controller is designed primarily to drive LEDs. It provides a large flexibility of PWM duty cycle settings. For instance, the PWM frequency of 5 kHz can have the maximum duty resolution of 13 bits. This means that the duty can be set anywhere from 0 to 100% with a resolution of ~0.012% (2 ** 13 = 8192 discrete levels of the LED intensity). Note, however, that these parameters depend on the clock signal clocking the LED PWM Controller timer which in turn clocks the channel (see timer configuration and the ESP32-S3 Technical Reference Manual > LED PWM Controller (LEDC) [PDF]).
The LEDC can be used for generating signals at much higher frequencies that are sufficient enough to clock other devices, e.g., a digital camera module. In this case, the maximum available frequency is 40 MHz with duty resolution of 1 bit. This means that the duty cycle is fixed at 50% and cannot be adjusted.
The LEDC API is designed to report an error when trying to set a frequency and a duty resolution that exceed the range of LEDCns hardware. For example, an attempt to set the frequency to 20 MHz and the duty resolution to 3 bits will result in the following error reported on a serial monitor:
E (196) ledc: requested frequency and duty resolution cannot be achieved, try reducing freq_hz or duty_resolution. div_param=128

Espressif Systems

604

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

In such a situation, either the duty resolution or the frequency must be reduced. For example, setting the duty resolution to 2 will resolve this issue and will make it possible to set the duty cycle at 25% steps, i.e., at 25%, 50% or 75%.
The LEDC driver will also capture and report attempts to configure frequency / duty resolution combinations that are below the supported minimum, e.g.:
E (196) ledc: requested frequency and duty resolution cannot be achieved, try increasing freq_hz or duty_resolution. div_param=128000000
The duty resolution is normally set using ledc_timer_bit_t. This enumeration covers the range from 10 to 15 bits. If a smaller duty resolution is required (from 10 down to 1), enter the equivalent numeric values directly.

Application Example
The LEDC change duty cycle and fading control example: peripherals/ledc/ledc_fade. The LEDC basic example: peripherals/ledc/ledc_basic.

API Reference
Header File · components/driver/include/driver/ledc.h

Functions esp_err_t ledc_channel_config(const ledc_channel_config_t *ledc_conf)
LEDC channel configuration Configure LEDC channel with the gpio_num/interrupt/source timer/frequency(Hz)/LEDC duty resolution.

given

channel/output

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · ledc_conf: Pointer of LEDC channel configure struct
esp_err_t ledc_timer_config(const ledc_timer_config_t *timer_conf) LEDC timer configuration Configure LEDC timer with the given source timer/frequency(Hz)/duty_resolution.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error · ESP_FAIL Can not find a proper pre-divider number base on the given frequency and the current duty_resolution.
Parameters · timer_conf: Pointer of LEDC timer configure struct

esp_err_t ledc_update_duty(ledc_mode_t speed_mode, ledc_channel_t channel) LEDC update channel parameters.

Note Call this function to activate the LEDC updated parameters. After ledc_set_duty, we need to call this function to update the settings. And the new LEDC parameters donnt take effect until the next PWM cycle.
Note ledc_set_duty, ledc_set_duty_with_hpoint and ledc_update_duty are not thread-safe, do not call these functions to control one LEDC channel in different tasks at the same time. A thread-safe version of API is ledc_set_duty_and_update
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters

Espressif Systems

605

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.
· channel: LEDC channel (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t
esp_err_t ledc_set_pin(int gpio_num, ledc_mode_t speed_mode, ledc_channel_t ledc_channel) Set LEDC output gpio.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · gpio_num: The LEDC output gpio · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode. · ledc_channel: LEDC channel (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t
esp_err_t ledc_stop(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t idle_level) LEDC stop. Disable LEDC output, and set idle level.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode. · channel: LEDC channel (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t · idle_level: Set output idle level after LEDC stops.
esp_err_t ledc_set_freq(ledc_mode_t speed_mode, ledc_timer_t timer_num, uint32_t freq_hz) LEDC set channel frequency (Hz)
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error · ESP_FAIL Can not find a proper pre-divider number base on the given frequency and the current duty_resolution.
Parameters · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode. · timer_num: LEDC timer index (0-3), select from ledc_timer_t · freq_hz: Set the LEDC frequency
uint32_t ledc_get_freq(ledc_mode_t speed_mode, ledc_timer_t timer_num) LEDC get channel frequency (Hz)
Return · 0 error · Others Current LEDC frequency
Parameters · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode. · timer_num: LEDC timer index (0-3), select from ledc_timer_t
esp_err_t ledc_set_duty_with_hpoint(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t duty, uint32_t hpoint)
LEDC set duty and hpoint value Only after calling ledc_update_duty will the duty update.
Note ledc_set_duty, ledc_set_duty_with_hpoint and ledc_update_duty are not thread-safe, do not call these functions to control one LEDC channel in different tasks at the same time. A thread-safe version of API is ledc_set_duty_and_update
Note For ESP32, hardware does not support any duty change while a fade operation is running in progress on that channel. Other duty operations will have to wait until the fade operation has finished.
Return

Espressif Systems

606

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error Parameters · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets
support high speed mode. · channel: LEDC channel (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t · duty: Set the LEDC duty, the range of duty setting is [0, (2**duty_resolution) - 1] · hpoint: Set the LEDC hpoint value(max: 0xfffff)
int ledc_get_hpoint(ledc_mode_t speed_mode, ledc_channel_t channel) LEDC get hpoint value, the counter value when the output is set high level.
Return · LEDC_ERR_VAL if parameter error · Others Current hpoint value of LEDC channel
Parameters · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode. · channel: LEDC channel (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t
esp_err_t ledc_set_duty(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t duty) LEDC set duty This function do not change the hpoint value of this channel. if needed, please call ledc_set_duty_with_hpoint. only after calling ledc_update_duty will the duty update.
Note ledc_set_duty, ledc_set_duty_with_hpoint and ledc_update_duty are not thread-safe, do not call these functions to control one LEDC channel in different tasks at the same time. A thread-safe version of API is ledc_set_duty_and_update.
Note For ESP32, hardware does not support any duty change while a fade operation is running in progress on that channel. Other duty operations will have to wait until the fade operation has finished.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode. · channel: LEDC channel (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t · duty: Set the LEDC duty, the range of duty setting is [0, (2**duty_resolution) - 1]
uint32_t ledc_get_duty(ledc_mode_t speed_mode, ledc_channel_t channel) LEDC get duty This function returns the duty at the present PWM cycle. You shouldnnt expect the function to return the new duty in the same cycle of calling ledc_update_duty, because duty update doesnnt take effect until the next cycle.
Return · LEDC_ERR_DUTY if parameter error · Others Current LEDC duty
Parameters · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode. · channel: LEDC channel (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t
esp_err_t ledc_set_fade(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t duty, ledc_duty_direction_t fade_direction, uint32_t step_num, uint32_t duty_cycle_num, uint32_t duty_scale)
LEDC set gradient Set LEDC gradient, After the function calls the ledc_update_duty function, the function can take effect.
Note For ESP32, hardware does not support any duty change while a fade operation is running in progress on that channel. Other duty operations will have to wait until the fade operation has finished.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error

Espressif Systems

607

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Parameters · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode. · channel: LEDC channel (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t · duty: Set the start of the gradient duty, the range of duty setting is [0, (2**duty_resolution) - 1] · fade_direction: Set the direction of the gradient · step_num: Set the number of the gradient · duty_cycle_num: Set how many LEDC tick each time the gradient lasts · duty_scale: Set gradient change amplitude
esp_err_t ledc_isr_register(void (*fn))void * , void *arg, int intr_alloc_flags, ledc_isr_handle_t *handleRegister LEDC interrupt handler, the handler is an ISR. The handler will be attached to the same CPU core that this function is running on.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Function pointer error.
Parameters · fn: Interrupt handler function. · arg: User-supplied argument passed to the handler function. · intr_alloc_flags: Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info. · handle: Pointer to return handle. If non-NULL, a handle for the interrupt will be returned here.
esp_err_t ledc_timer_set(ledc_mode_t speed_mode, ledc_timer_t timer_sel, uint32_t clock_divider, uint32_t duty_resolution, ledc_clk_src_t clk_src)
Configure LEDC settings.
Return · (-1) Parameter error · Other Current LEDC duty
Parameters · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode. · timer_sel: Timer index (0-3), there are 4 timers in LEDC module · clock_divider: Timer clock divide value, the timer clock is divided from the selected clock source · duty_resolution: Resolution of duty setting in number of bits. The range of duty values is [0, (2**duty_resolution)] · clk_src: Select LEDC source clock.
esp_err_t ledc_timer_rst(ledc_mode_t speed_mode, ledc_timer_t timer_sel) Reset LEDC timer.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode. · timer_sel: LEDC timer index (0-3), select from ledc_timer_t
esp_err_t ledc_timer_pause(ledc_mode_t speed_mode, ledc_timer_t timer_sel) Pause LEDC timer counter.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode. · timer_sel: LEDC timer index (0-3), select from ledc_timer_t

Espressif Systems

608

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t ledc_timer_resume(ledc_mode_t speed_mode, ledc_timer_t timer_sel) Resume LEDC timer.

Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode. · timer_sel: LEDC timer index (0-3), select from ledc_timer_t

esp_err_t ledc_bind_channel_timer(ledc_mode_t speed_mode, ledc_timer_t timer_sel)
Bind LEDC channel with the selected timer.

ledc_channel_t channel,

Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode. · channel: LEDC channel index (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t · timer_sel: LEDC timer index (0-3), select from ledc_timer_t

esp_err_t ledc_set_fade_with_step(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t target_duty, uint32_t scale, uint32_t cycle_num)
Set LEDC fade function.

Note Call ledc_fade_func_install() once before calling this function. Call ledc_fade_start() after this to start fading.
Note ledc_set_fade_with_step, ledc_set_fade_with_time and ledc_fade_start are not thread-safe, do not call these functions to control one LEDC channel in different tasks at the same time. A thread-safe version of API is ledc_set_fade_step_and_start
Note For ESP32, hardware does not support any duty change while a fade operation is running in progress on that channel. Other duty operations will have to wait until the fade operation has finished.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success · ESP_ERR_INVALID_STATE Fade function not installed. · ESP_FAIL Fade function init error
Parameters · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode. , · channel: LEDC channel index (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t · target_duty: Target duty of fading [0, (2**duty_resolution) - 1] · scale: Controls the increase or decrease step scale. · cycle_num: increase or decrease the duty every cycle_num cycles

esp_err_t ledc_set_fade_with_time(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t target_duty, int max_fade_time_ms)
Set LEDC fade function, with a limited time.

Note Call ledc_fade_func_install() once before calling this function. Call ledc_fade_start() after this to start fading.
Note ledc_set_fade_with_step, ledc_set_fade_with_time and ledc_fade_start are not thread-safe, do not call these functions to control one LEDC channel in different tasks at the same time. A thread-safe version of API is ledc_set_fade_step_and_start
Note For ESP32, hardware does not support any duty change while a fade operation is running in progress on that channel. Other duty operations will have to wait until the fade operation has finished.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success

Espressif Systems

609

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_ERR_INVALID_STATE Fade function not installed. · ESP_FAIL Fade function init error Parameters · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets
support high speed mode. , · channel: LEDC channel index (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t · target_duty: Target duty of fading [0, (2**duty_resolution) - 1] · max_fade_time_ms: The maximum time of the fading ( ms ).

esp_err_t ledc_fade_func_install(int intr_alloc_flags) Install LEDC fade function. This function will occupy interrupt of LEDC module.

Return · ESP_OK Success · ESP_ERR_INVALID_STATE Fade function already installed.
Parameters · intr_alloc_flags: Flags used to allocate the interrupt. ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.

One or multiple (ORred)

void ledc_fade_func_uninstall(void) Uninstall LEDC fade function.

esp_err_t ledc_fade_start(ledc_mode_t speed_mode, ledc_channel_t channel, ledc_fade_mode_t

Start LEDC fading.

fade_mode)

Note Call ledc_fade_func_install() once before calling this function. Call this API right after ledc_set_fade_with_time or ledc_set_fade_with_step before to start fading.
Note Starting fade operation with this API is not thread-safe, use with care. Note For ESP32, hardware does not support any duty change while a fade operation is running in progress on
that channel. Other duty operations will have to wait until the fade operation has finished. Return
· ESP_OK Success · ESP_ERR_INVALID_STATE Fade function not installed. · ESP_ERR_INVALID_ARG Parameter error. Parameters · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets
support high speed mode. · channel: LEDC channel number · fade_mode: Whether to block until fading done. See ledc_types.h ledc_fade_mode_t
for more info. Note that this function will not return until fading to the target duty if LEDC_FADE_WAIT_DONE mode is selected.

esp_err_t ledc_fade_stop(ledc_mode_t speed_mode, ledc_channel_t channel) Stop LEDC fading. Duty of the channel will stay at its present vlaue.

Note This API can be called if a new fixed duty or a new fade want to be set while the last fade operation is still running in progress.
Note Call this API will abort the fading operation only if it was started by calling ledc_fade_start with LEDC_FADE_NO_WAIT mode.
Note If a fade was started with LEDC_FADE_WAIT_DONE mode, calling this API afterwards is no use in stopping the fade. Fade will continue until it reachs the target duty.
Return · ESP_OK Success · ESP_ERR_INVALID_STATE Fade function not installed. · ESP_ERR_INVALID_ARG Parameter error.
Parameters · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode. · channel: LEDC channel number

Espressif Systems

610

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t ledc_set_duty_and_update(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t duty, uint32_t hpoint)
A thread-safe API to set duty for LEDC channel and return when duty updated.
Note For ESP32, hardware does not support any duty change while a fade operation is running in progress on that channel. Other duty operations will have to wait until the fade operation has finished.
Parameters · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode. · channel: LEDC channel (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t · duty: Set the LEDC duty, the range of duty setting is [0, (2**duty_resolution) - 1] · hpoint: Set the LEDC hpoint value(max: 0xfffff)
esp_err_t ledc_set_fade_time_and_start(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t target_duty, uint32_t max_fade_time_ms, ledc_fade_mode_t fade_mode)
A thread-safe API to set and start LEDC fade function, with a limited time.
Note Call ledc_fade_func_install() once, before calling this function. Note For ESP32, hardware does not support any duty change while a fade operation is running in progress on
that channel. Other duty operations will have to wait until the fade operation has finished. Return
· ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success · ESP_ERR_INVALID_STATE Fade function not installed. · ESP_FAIL Fade function init error Parameters · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets
support high speed mode. · channel: LEDC channel index (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t · target_duty: Target duty of fading [0, (2**duty_resolution) - 1] · max_fade_time_ms: The maximum time of the fading ( ms ). · fade_mode: choose blocking or non-blocking mode
esp_err_t ledc_set_fade_step_and_start(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t target_duty, uint32_t scale, uint32_t cycle_num, ledc_fade_mode_t fade_mode)
A thread-safe API to set and start LEDC fade function.
Note Call ledc_fade_func_install() once before calling this function. Note For ESP32, hardware does not support any duty change while a fade operation is running in progress on
that channel. Other duty operations will have to wait until the fade operation has finished. Return
· ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success · ESP_ERR_INVALID_STATE Fade function not installed. · ESP_FAIL Fade function init error Parameters · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets
support high speed mode. · channel: LEDC channel index (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t · target_duty: Target duty of fading [0, (2**duty_resolution) - 1] · scale: Controls the increase or decrease step scale. · cycle_num: increase or decrease the duty every cycle_num cycles · fade_mode: choose blocking or non-blocking mode
esp_err_t ledc_cb_register(ledc_mode_t speed_mode, ledc_channel_t channel, ledc_cbs_t *cbs, void *user_arg)
LEDC callback registration function.
Note The callback is called from an ISR, it must never attempt to block, and any FreeRTOS API called must be ISR capable.

Espressif Systems

611

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success · ESP_ERR_INVALID_STATE Fade function not installed. · ESP_FAIL Fade function init error
Parameters · speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode. · channel: LEDC channel index (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t · cbs: Group of LEDC callback functions · user_arg: user registered data for the callback function
Structures struct ledc_channel_config_t
Configuration parameters of LEDC channel for ledc_channel_config function.
Public Members
int gpio_num the LEDC output gpio_num, if you want to use gpio16, gpio_num = 16
ledc_mode_t speed_mode LEDC speed speed_mode, high-speed mode or low-speed mode
ledc_channel_t channel LEDC channel (0 - 7)
ledc_intr_type_t intr_type configure interrupt, Fade interrupt enable or Fade interrupt disable
ledc_timer_t timer_sel Select the timer source of channel (0 - 3)
uint32_t duty LEDC channel duty, the range of duty setting is [0, (2**duty_resolution)]
int hpoint LEDC channel hpoint value, the max value is 0xfffff
unsigned int output_invert : 1 Enable (1) or disable (0) gpio output invert
struct ledc_channel_config_t::[anonymous] flags LEDC flags
struct ledc_timer_config_t Configuration parameters of LEDC Timer timer for ledc_timer_config function.
Public Members
ledc_mode_t speed_mode LEDC speed speed_mode, high-speed mode or low-speed mode
ledc_timer_bit_t duty_resolution LEDC channel duty resolution
ledc_timer_bit_t bit_num Deprecated in ESP-IDF 3.0. This is an alias to mduty_resolutionnfor backward compatibility with ESP-IDF 2.1
ledc_timer_t timer_num The timer source of channel (0 - 3)

Espressif Systems

612

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

uint32_t freq_hz LEDC timer frequency (Hz)
ledc_clk_cfg_t clk_cfg Configure LEDC source clock. For low speed channels and high speed channels, you can specify the source clock using LEDC_USE_REF_TICK, LEDC_USE_APB_CLK or LEDC_AUTO_CLK. For low speed channels, you can also specify the source clock using LEDC_USE_RTC8M_CLK, in this case, all low speed channelns source clock must be RTC8M_CLK
struct ledc_cb_param_t LEDC callback parameter.

Public Members
ledc_cb_event_t event Event name
uint32_t speed_mode Speed mode of the LEDC channel group
uint32_t channel LEDC channel (0 - LEDC_CHANNEL_MAX-1)
uint32_t duty LEDC current duty of the channel, the range of duty is [0, (2**duty_resolution) - 1]
struct ledc_cbs_t Group of supported LEDC callbacks.
Note The callbacks are all running under ISR environment

Public Members
ledc_cb_t fade_cb LEDC fade_end callback function

Macros LEDC_APB_CLK_HZ LEDC_REF_CLK_HZ
LEDC_ERR_DUTY
LEDC_ERR_VAL

Type Definitions typedef intr_handle_t ledc_isr_handle_t typedef bool (*ledc_cb_t)(const ledc_cb_param_t *param, void *user_arg)
Type of LEDC event callback.
Parameters · param: LEDC callback parameter · user_arg: User registered data

Enumerations enum ledc_cb_event_t
LEDC callback event type. Values: LEDC_FADE_END_EVT
LEDC fade end event
Espressif Systems

613

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Header File
· components/hal/include/hal/ledc_types.h
Enumerations enum ledc_mode_t
Values:
LEDC_LOW_SPEED_MODE LEDC low speed speed_mode
LEDC_SPEED_MODE_MAX LEDC speed limit
enum ledc_intr_type_t Values:
LEDC_INTR_DISABLE = 0 Disable LEDC interrupt
LEDC_INTR_FADE_END Enable LEDC interrupt
LEDC_INTR_MAX
enum ledc_duty_direction_t Values:
LEDC_DUTY_DIR_DECREASE = 0 LEDC duty decrease direction
LEDC_DUTY_DIR_INCREASE = 1 LEDC duty increase direction
LEDC_DUTY_DIR_MAX
enum ledc_slow_clk_sel_t Values:
LEDC_SLOW_CLK_RTC8M = 0 LEDC low speed timer clock source is 8MHz RTC clock
LEDC_SLOW_CLK_APB LEDC low speed timer clock source is 80MHz APB clock
LEDC_SLOW_CLK_XTAL LEDC low speed timer clock source XTAL clock
enum ledc_clk_cfg_t In theory, the following enumeration shall be placed in LEDC driverns header. However, as the next enumeration, ledc_clk_src_t, makes the use of some of these values and to avoid mutual inclusion of the headers, we must define it here.
Values:
LEDC_AUTO_CLK = 0 The driver will automatically select the source clock(REF_TICK or APB) based on the giving resolution and duty parameter when init the timer
LEDC_USE_APB_CLK LEDC timer select APB clock as source clock
LEDC_USE_RTC8M_CLK LEDC timer select RTC8M_CLK as source clock. Only for low speed channels and this parameter must be the same for all low speed channels
LEDC_USE_XTAL_CLK LEDC timer select XTAL clock as source clock

Espressif Systems

614

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

enum ledc_clk_src_t Values:
LEDC_APB_CLK = LEDC_USE_APB_CLK LEDC timer clock divided from APB clock (80Mhz)
LEDC_SCLK = LEDC_USE_APB_CLK Selecting this value for LEDC_TICK_SEL_TIMER let the hardware take its source clock from LEDC_APB_CLK_SEL
enum ledc_timer_t Values:
LEDC_TIMER_0 = 0 LEDC timer 0
LEDC_TIMER_1 LEDC timer 1
LEDC_TIMER_2 LEDC timer 2
LEDC_TIMER_3 LEDC timer 3
LEDC_TIMER_MAX
enum ledc_channel_t Values:
LEDC_CHANNEL_0 = 0 LEDC channel 0
LEDC_CHANNEL_1 LEDC channel 1
LEDC_CHANNEL_2 LEDC channel 2
LEDC_CHANNEL_3 LEDC channel 3
LEDC_CHANNEL_4 LEDC channel 4
LEDC_CHANNEL_5 LEDC channel 5
LEDC_CHANNEL_6 LEDC channel 6
LEDC_CHANNEL_7 LEDC channel 7
LEDC_CHANNEL_MAX
enum ledc_timer_bit_t Values:
LEDC_TIMER_1_BIT = 1 LEDC PWM duty resolution of 1 bits
LEDC_TIMER_2_BIT LEDC PWM duty resolution of 2 bits
LEDC_TIMER_3_BIT LEDC PWM duty resolution of 3 bits
LEDC_TIMER_4_BIT LEDC PWM duty resolution of 4 bits

Espressif Systems

615

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

LEDC_TIMER_5_BIT LEDC PWM duty resolution of 5 bits
LEDC_TIMER_6_BIT LEDC PWM duty resolution of 6 bits
LEDC_TIMER_7_BIT LEDC PWM duty resolution of 7 bits
LEDC_TIMER_8_BIT LEDC PWM duty resolution of 8 bits
LEDC_TIMER_9_BIT LEDC PWM duty resolution of 9 bits
LEDC_TIMER_10_BIT LEDC PWM duty resolution of 10 bits
LEDC_TIMER_11_BIT LEDC PWM duty resolution of 11 bits
LEDC_TIMER_12_BIT LEDC PWM duty resolution of 12 bits
LEDC_TIMER_13_BIT LEDC PWM duty resolution of 13 bits
LEDC_TIMER_14_BIT LEDC PWM duty resolution of 14 bits
LEDC_TIMER_BIT_MAX
enum ledc_fade_mode_t Values:
LEDC_FADE_NO_WAIT = 0 LEDC fade function will return immediately
LEDC_FADE_WAIT_DONE LEDC fade function will block until fading to the target duty
LEDC_FADE_MAX

2.3.11 Motor Control Pulse Width Modulator (MCPWM)
ESP32-S3 has two MCPWM units which can be used to control different types of motors. Each unit has three pairs of PWM outputs.
Further in documentation the outputs of a single unit are labeled PWMxA / PWMxB.
More detailed block diagram of the MCPWM unit is shown below. Each A/B pair may be clocked by any one of the three timers Timer 0, 1 and 2. The same timer may be used to clock more than one pair of PWM outputs. Each unit is also able to collect inputs such as SYNC SIGNALS, detect FAULT SIGNALS like motor overcurrent or overvoltage, as well as obtain feedback with CAPTURE SIGNALS on e.g. a rotor position.
Description of this API starts with configuration of MCPWMns Timer and Generator submodules to provide the basic motor control functionality. Then it discusses more advanced submodules and functionalities of a Fault Handler, signal Capture and Carrier.

Contents
· Configure a basic functionality of the outputs · Operate the outputs to drive a motor · Adjust how the motor is driven · Synchronize sync timers to work together

Espressif Systems

616

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference Fig. 8: MCPWM Overview

Espressif Systems

Fig. 9: MCPWM Block Diagram

617

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· Capture external signals to provide additional control over the outputs · Use Fault Handler to detect and manage faults · Add a higher frequency Carrier, if output signals are passed through an isolation transformer · Extra configuration of Resolution.
Configure
The scope of configuration depends on the motor type, in particular how many outputs and inputs are required, and what will be the sequence of signals to drive the motor. In this case we will describe a simple configuration to control a brushed DC motor that is using only some of the available MCPWMns resources. An example circuit is shown below. It includes a H-Bridge to switch polarization of a voltage applied to the motor (M) and to provide sufficient current to drive it.

Fig. 10: Example of Brushed DC Motor Control with MCPWM
Configuration covers the following steps:
1. Selection of a MCPWM unit that will be used to drive the motor. There are two units available on-board of ESP32-S3 and enumerated in mcpwm_unit_t.
2. Initialization of two GPIOs as output signals within selected unit by calling mcpwm_gpio_init(). The two output signals are typically used to command the motor to rotate right or left. All available signal options are listed in mcpwm_io_signals_t. To set more than a single pin at a time, use function mcpwm_set_pin() together with mcpwm_pin_config_t.
3. Selection of a timer. There are three timers available within the unit. The timers are listed in mcpwm_timer_t.
4. Setting of the timer frequency and initial duty within mcpwm_config_t structure. 5. Setting timer resolution if necessary, by calling mcpwm_group_set_resolution() and
mcpwm_timer_set_resolution() 6. Calling of mcpwm_init() with the above parameters to make the configuration effective.

Operate
To operate a motor connected to the MCPWM unit, e.g. turn it left or right, or vary the speed, we should apply some control signals to the unitns outputs. The outputs are organized into three pairs. Within a pair they are labeledoAp and oBpand each driven by a submodule called an oGeneratorp. To provide a PWM signal, the Operator itself, which contains two Generator, should be clocked by one of three available Timers. To make the API simpler, each Timer is automatically associated by the API to drive an Operator of the same index, e.g. Timer 0 is associated with Operator 0.

Espressif Systems

618

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
There are the following basic ways to control the outputs:
· We can drive particular signal steady high or steady low with function mcpwm_set_signal_high() or mcpwm_set_signal_low(). This will make the motor to turn with a maximum speed or stop. Depending on selected output A or B the motor will rotate either right or left.
· Another option is to drive the outputs with the PWM signal by calling mcpwm_start() or mcpwm_stop(). The motor speed will be proportional to the PWM duty.
· To vary PWMns duty call mcpwm_set_duty() and provide the duty value in %. Optionally, you may call mcpwm_set_duty_in_us(), if you prefer to set the duty in microseconds. Checking of currently set value is possible by calling mcpwm_get_duty(). Phase of the PWM signal may be altered by calling mcpwm_set_duty_type(). The duty is set individually for each A and B output using mcpwm_generator_t in specific function calls. The duty value refers either to high or low output signal duration. This is configured when calling mcpwm_init(), as discussed in section Configure, and selecting one of options from mcpwm_duty_type_t.
Note: Call function mcpwm_set_duty_type() every time after mcpwm_set_signal_high() or mcpwm_set_signal_low() to resume with previously set duty cycle.

Adjust
There are couple of ways to adjust a signal on the outputs and changing how the motor operates.
· Set specific PWM frequency by calling mcpwm_set_frequency(). This may be required to adjust to electrical or mechanical characteristics of particular motor and driver. To check what frequency is set, use function mcpwm_get_frequency().
· Introduce a dead time between outputs A and B when they are changing the state to reverse direction of the motor rotation. This is to make up for on/off switching delay of the motor driver FETs. The dead time options are defined in mcpwm_deadtime_type_t and enabled by calling mcpwm_deadtime_enable(). To disable this functionality call mcpwm_deadtime_disable().
· Synchronize outputs of operator submodules, e.g. to get raising edge of PWM0A/B and PWM1A/B to start exactly at the same time, or shift them between each other by a given phase. Synchronization is triggered by SYNC SIGNALS shown on the block diagram of the MCPWM above, and defined in mcpwm_sync_signal_t. To attach the signal to a GPIO call mcpwm_gpio_init(). You can then enable synchronization with function mcpwm_sync_configure(). As input parameters provide MCPWM unit, timer to synchronize, the synchronization signal and a phase to delay the timer.

Note:

Synchronization signals are referred to using two different enumerations. First one

mcpwm_io_signals_t is used together with function mcpwm_gpio_init() when selecting a GPIO

as the signal input source. The second one mcpwm_sync_signal_t is used when enabling or disabling

synchronization with mcpwm_sync_configure() or mcpwm_sync_disable().

· Vary the pattern of the A/B output signals by getting MCPWM counters to count up, down and up/down (automatically changing the count direction). Respective configuration is done when calling mcpwm_init(), as discussed in section Configure, and selecting one of counter types from mcpwm_counter_type_t. For explanation of how A/B PWM output signals are generated, see ESP32-S3 Technical Reference Manual > Motor Control PWM (MCPWM) [PDF].

Synchronize
Each PWM timer has a synchronization input and a synchronization output. The synchronization input can be selected from other timersnsynchronization outputs or GPIO signals via the GPIO matrix. Timerns synchronization signal can be generated from either the input sync signal or when the count value reaches peak/zero. Thus, the PWM timers can be chained together with their phase-locked. During synchronization, the PWM timer clock prescaler will reset its counter in order to synchronize the PWM timer clock.
The functionality is enabled in following steps:

Espressif Systems

619

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

1. Make sure the PWM timer and operator are already configured so that sync will inherit its config (count mode, freq and duty).
2. Enabling sync input of the timer by invoking mcpwm_sync_configure(), selecting desired signal input from mcpwm_sync_signal_t, and setting the desired phase range from 0 to 999 which is mapped to 0%~99.9%. 0 means zero phase is applied and output is fired at the same time. And selecting desired counting direction.
3. Enabling one of sync event source from another timer or from external GPIO input.
To sync with another timer:
Enabling sync output of another timer by invoking mcpwm_set_timer_sync_output() and selecting desired event to generate sync output from mcpwm_timer_sync_trigger_t.
To sync with GPIO positive edge input (negative edge requires mcpwm_sync_invert_gpio_synchro()):
Configuring GPIOs to act as the sync signal inputs by calling functions mcpwm_gpio_init() or mcpwm_set_pin(), which were described in section Configure.
Itns normal condition that chained sync signal may have tens or even hundreds of nanoseconds of delay between each timer output due to hardware limitation. To sync two timers accurately it is required to have the third timer occupied to produce sync event that can be consumed parallel by other two timer, so that those two timer will have no delay between each other but have the same delay between the timer which provides events. Another solution is introducing an external GPIO event source so that all three timers can be synced together with no delay.
Software sync event which triggered on one timer can be propagated to other timers on ESP32-S3, which can be used as a tricky way to get all three timers synced without any extra requirement.
// configure timer0 as trigger source mcpwm_set_timer_sync_output(MCPWM_UNIT_0, MCPWM_TIMER_0, MCPWM_SWSYNC_SOURCE_ SYNCIN); mcpwm_sync_config_t sync_conf = {
.sync_sig = MCPWM_SELECT_TIMER0_SYNC, .timer_val = 0, .count_direction = MCPWM_TIMER_DIRECTION_UP, }; mcpwm_sync_configure(TARGET_MCPWM_UNIT, MCPWM_TIMER_0, &sync_conf); mcpwm_sync_configure(TARGET_MCPWM_UNIT, MCPWM_TIMER_1, &sync_conf); mcpwm_sync_configure(TARGET_MCPWM_UNIT, MCPWM_TIMER_2, &sync_conf); // then send soft sync event to timer0 mcpwm_timer_trigger_soft_sync(MCPWM_UNIT_0, MCPWM_TIMER_0);
If not required anymore, the capture functionality may be disabled with mcpwm_sync_disable().
Capture
One of requirements of BLDC (Brushless DC, see figure below) motor control is sensing of the rotor position. To facilitate this task each MCPWM unit provides three sensing inputs together with dedicated hardware. The hardware is able to detect the input signalns edge and measure time between signals. As result the control software is simpler and the CPU power may be used for other tasks.
The capture functionality may be used for other types of motors or tasks. The functionality is enabled in two steps:
1. Configuration of GPIOs to act as the capture signal inputs by calling functions mcpwm_gpio_init() or mcpwm_set_pin(), that were described in section Configure.
2. Enabling of the functionality itself by invoking mcpwm_capture_enable_channel(), selecting desired signal input from mcpwm_capture_channel_id_t, setting the signal edge, signal count prescaler and user callback within mcpwm_capture_config_t
Within the second step above a 32-bit capture timer is enabled. The timer runs continuously driven by the APB clock. The clock frequency is typically 80 MHz. On each capture event the capture timerns value is stored in timestamp register that may be then checked by calling mcpwm_capture_signal_get_value(). The edge of the last signal may be checked with mcpwm_capture_signal_get_edge(). Those data are also provided inside callback function as event data cap_event_data_t

Espressif Systems

620

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Fig. 11: Example of Brushless DC Motor Control with MCPWM
If not required anymore, the capture functionality may be disabled with mcpwm_capture_disable_channel().
Capture prescale is different from other modules as it is applied to the input signal, not the timer source. Prescaler has maintained its own level state with the initial value set to low and is detecting the positive edge of the input signal to change its internal state. That means if two pairs of positive and negative edges are passed to input, the prescalerns internal state will change twice. ISR will report on this internal state change, not the input signal. For example, setting prescale to 2 will generate ISR callback on each positive edge of input if both edge is selected via mcpwm_capture_config_t. Or each 2 positive edges of input if only one edge is selected though mcpwm_capture_config_t.
Fault Handler
Each unit of the MCPWM is able to sense external signals with information about failure of the motor, the motor driver or any other device connected to the MCPWM. There are three fault inputs per unit that may be routed to user selectable GPIOs. The MCPWM may be configured to perform one of four predefined actions on A/B outputs when a fault signal is received:
· lock current state of the output · set the output low · set the output high · toggle the output
The user should determine possible failure modes of the motor and what action should be performed on detection of particular fault, e.g. drive all outputs low for a brushed motor, or lock current state for a stepper motor, etc. As result of this action the motor should be put into a safe state to reduce likelihood of a damage caused by the fault.
The fault handler functionality is enabled in two steps:
1. Configuration of GPIOs to act as fault signal inputs. This is done in analogous way as described for capture signals in section above. It includes setting the signal level to trigger the fault as defined in mcpwm_fault_input_level_t.

Espressif Systems

621

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

2. Initialization of the fault handler by calling either mcpwm_fault_set_oneshot_mode() or mcpwm_fault_set_cyc_mode(). These functions set the mode that MCPWM should operate once fault signal becomes inactive. There are two modes possible: · State of MCPWM unit will be locked until reset - mcpwm_fault_set_oneshot_mode(). · The MCPWM will resume operation once fault signal becoming inactive mcpwm_fault_set_cyc_mode(). The function call parameters include selection of one of three fault inputs defined in mcpwm_fault_signal_t and specific action on outputs A and B defined in mcpwm_action_on_pwmxa_t and mcpwm_action_on_pwmxb_t.
Particular fault signal may be disabled at the runtime by calling mcpwm_fault_deinit().
Carrier
The MCPWM has a carrier submodule used if galvanic isolation from the motor driver is required by passing the A/B output signals through transformers. Any of A and B output signals may be at 100% duty and not changing whenever motor is required to run steady at the full load. Coupling of non alternating signals with a transformer is problematic, so the signals are modulated by the carrier submodule to create an AC waveform, to make the coupling possible. To use the carrier submodule, it should be first initialized by calling mcpwm_carrier_init(). The carrier parameters are defined in mcpwm_carrier_config_t structure invoked within the function call. Then the carrier functionality may be enabled by calling mcpwm_carrier_enable(). The carrier parameters may be then altered at a runtime by calling dedicated functions to change individual fields of the mcpwm_carrier_config_t structure, like mcpwm_carrier_set_period(), mcpwm_carrier_set_duty_cycle(), mcpwm_carrier_output_invert(), etc. This includes enabling and setting duration of the first pulse of the career with mcpwm_carrier_oneshot_mode_enable(). For more details, see ESP32-S3 Technical Reference Manual > Motor Control PWM (MCPWM) > PWM Carrier Submodule [PDF]. To disable carrier functionality call mcpwm_carrier_disable().
Interrupts
Registering of the MCPWM interrupt handler is possible by calling mcpwm_isr_register(). Note if mcpwm_capture_enable_channel() is used then a default ISR routine will be installed hence please do not call this function to register any more.
Resolution
The default resolution for MCPWM group and MCPWM timer are configured to 10MHz and 1MHz in mcpwm_init(), which might be not enough for some applications. The driver also provides two APIs that can be used to override the default resolution: mcpwm_group_set_resolution() and mcpwm_timer_set_resolution(). Note that, these two APIs wonnt update the frequency and duty automatically, to achieve that, one has to call mcpwm_set_frequency() and mcpwm_set_duty() accordingly. To get PWM pulse that is below 15Hz, please set the resolution to a lower value. For high frequency PWM with limited step range, please set them with higher value.
Application Example
MCPWM example are located under: peripherals/mcpwm: · Control of BLDC (brushless DC) motor with hall sensor feedback - peripherals/mcpwm/mcpwm_bldc_hall_control

Espressif Systems

622

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· Brushed DC motor control - peripherals/mcpwm/mcpwm_bdc_speed_control · Servo motor control - peripherals/mcpwm/mcpwm_servo_control · HC-SR04 sensor with capture - peripherals/mcpwm/mcpwm_capture_hc_sr04

API Reference
Header File · components/hal/include/hal/mcpwm_types.h

Enumerations enum mcpwm_timer_direction_t
Values:
MCPWM_TIMER_DIRECTION_UP Counting direction: Increase
MCPWM_TIMER_DIRECTION_DOWN Counting direction: Decrease
enum mcpwm_timer_event_t Values:
MCPWM_TIMER_EVENT_ZERO MCPWM timer counts to zero
MCPWM_TIMER_EVENT_PEAK MCPWM timer counts to peak
enum mcpwm_timer_count_mode_t Values:
MCPWM_TIMER_COUNT_MODE_PAUSE MCPWM timer paused
MCPWM_TIMER_COUNT_MODE_UP MCPWM timer counting up
MCPWM_TIMER_COUNT_MODE_DOWN MCPWM timer counting down
MCPWM_TIMER_COUNT_MODE_UP_DOWN MCPWM timer counting up and down
enum mcpwm_timer_execute_cmd_t Values:
MCPWM_TIMER_STOP_AT_ZERO MCPWM timer stops when couting to zero
MCPWM_TIMER_STOP_AT_PEAK MCPWM timer stops when counting to peak
MCPWM_TIMER_START_NO_STOP MCPWM timer starts couting
MCPWM_TIMER_START_STOP_AT_ZERO MCPWM timer starts counting and stops when couting to zero
MCPWM_TIMER_START_STOP_AT_PEAK MCPWM timer starts counting and stops when counting to peak
enum mcpwm_generator_action_t Values:
MCPWM_GEN_ACTION_KEEP Generator action: Keep the same level

Espressif Systems

623

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
MCPWM_GEN_ACTION_LOW Generator action: Force to low level
MCPWM_GEN_ACTION_HIGH Generator action: Force to high level
MCPWM_GEN_ACTION_TOGGLE Generator action: Toggle level
enum mcpwm_trip_type_t Values:
MCPWM_TRIP_TYPE_CBC CBC trip type, shut down the operator cycle by cycle
MCPWM_TRIP_TYPE_OST OST trip type, shut down the operator in one shot
Header File
· components/driver/include/driver/mcpwm.h
Functions esp_err_t mcpwm_gpio_init(mcpwm_unit_t mcpwm_num, mcpwm_io_signals_t io_signal, int
gpio_num) This function initializes each gpio signal for MCPWM.
Note This function initializes one gpio at a time. Return
· ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error Parameters · mcpwm_num: set MCPWM unit(0-1) · io_signal: set MCPWM signals, each MCPWM unit has 6 output(MCPWMXA, MCPWMXB)
and 9 input(SYNC_X, FAULT_X, CAP_X) mXnis timer_num(0-2) · gpio_num: set this to configure gpio for MCPWM, if you want to use gpio16, gpio_num = 16 esp_err_t mcpwm_set_pin(mcpwm_unit_t mcpwm_num, const mcpwm_pin_config_t *mcpwm_pin) Initialize MCPWM gpio structure.
Note This function initialize a group of MCPWM GPIOs at a time. Return
· ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error Parameters · mcpwm_num: set MCPWM unit(0-1) · mcpwm_pin: MCPWM pin structure
esp_err_t mcpwm_init(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num, const mcpwm_config_t *mcpwm_conf)
Initialize MCPWM parameters.
Note The default resolution configured for MCPWM group and timer are 160M / 16 = 10M and 10M / 10 = 1M The default resolution can be changed by calling mcpwm_group_set_resolution() and mcpwm_timer_set_resolution(), before calling this function.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers. · mcpwm_conf: configure structure mcpwm_config_t

Espressif Systems

624

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t mcpwm_group_set_resolution(mcpwm_unit_t mcpwm_num, unsigned long int resolution) Set resolution of the MCPWM group.

Note This will override default resolution of group(=10,000,000). This WILL NOT automatically update frequency and duty. Call mcpwm_set_frequency() and mcpwm_set_duty() manually to set them back.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · resolution: set expected frequency resolution

esp_err_t mcpwm_timer_set_resolution(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num,

Set resolution of each timer.

unsigned long int resolution)

Note This WILL override default resolution of timer(=1,000,000). This WILL NOT automatically update frequency and duty. Call mcpwm_set_frequency() and mcpwm_set_duty() manually to set them back.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers · resolution: set expected frequency resolution

esp_err_t mcpwm_set_frequency(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num, uint32_t frequency)
Set frequency(in Hz) of MCPWM timer.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers · frequency: set the frequency in Hz of each timer

esp_err_t mcpwm_set_duty(mcpwm_unit_t mcpwm_num, mcpwm_generator_t gen, float duty)
Set duty cycle of each operator(MCPWMXA/MCPWMXB)

mcpwm_timer_t

timer_num,

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers · gen: set the generator(MCPWMXA/MCPWMXB), mXnis operator number selected · duty: set duty cycle in %(i.e for 62.3% duty cycle, duty = 62.3) of each operator

esp_err_t mcpwm_set_duty_in_us(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num, mcpwm_generator_t gen, uint32_t duty_in_us)
Set duty cycle of each operator(MCPWMXA/MCPWMXB) in us.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers · gen: set the generator(MCPWMXA/MCPWMXB), mxnis operator number selected · duty_in_us: set duty value in microseconds of each operator

Espressif Systems

625

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t mcpwm_set_duty_type(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num, mcpwm_generator_t gen, mcpwm_duty_type_t duty_type)
Set duty either active high or active low(out of phase/inverted)

Note Call this function every time after mcpwm_set_signal_high or mcpwm_set_signal_low to resume with previously set duty cycle
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers · gen: set the generator(MCPWMXA/MCPWMXB), mxnis operator number selected · duty_type: set active low or active high duty type

uint32_t mcpwm_get_frequency(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num) Get frequency of timer.

Return · frequency of timer
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers

float mcpwm_get_duty(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num, mcpwm_operator_t gen)
Get duty cycle of each operator.

Return · duty cycle in % of each operator(56.7 means duty is 56.7%)
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers · gen: set the generator(MCPWMXA/MCPWMXB), mxnis operator number selected

uint32_t mcpwm_get_duty_in_us(mcpwm_unit_t mcpwm_num, mcpwm_operator_t gen)
Get duty cycle of each operator in us.

mcpwm_timer_t timer_num,

Return · duty cycle in us of each operator
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers · gen: set the generator(MCPWMXA/MCPWMXB), mxnis operator number selected

esp_err_t mcpwm_set_signal_high(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num, mcpwm_generator_t gen)
Use this function to set MCPWM signal high.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers · gen: set the operator(MCPWMXA/MCPWMXB), mxnis timer number selected

esp_err_t mcpwm_set_signal_low(mcpwm_unit_t mcpwm_num, mcpwm_generator_t gen)
Use this function to set MCPWM signal low.

mcpwm_timer_t timer_num,

Return · ESP_OK Success

Espressif Systems

626

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_ERR_INVALID_ARG Parameter error Parameters
· mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers · gen: set the operator(MCPWMXA/MCPWMXB), mxnis timer number selected

esp_err_t mcpwm_start(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num) Start MCPWM signal on timer mxn.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers

esp_err_t mcpwm_stop(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num) Start MCPWM signal on timer mxn.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers

esp_err_t mcpwm_carrier_init(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num, const mcpwm_carrier_config_t *carrier_conf)
Initialize carrier configuration.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers · carrier_conf: configure structure mcpwm_carrier_config_t

esp_err_t mcpwm_carrier_enable(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num) Enable MCPWM carrier submodule, for respective timer.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers

esp_err_t mcpwm_carrier_disable(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num) Disable MCPWM carrier submodule, for respective timer.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers

esp_err_t mcpwm_carrier_set_period(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num,

Set period of carrier.

uint8_t carrier_period)

Return · ESP_OK Success

Espressif Systems

627

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_ERR_INVALID_ARG Parameter error Parameters
· mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers · carrier_period: set the carrier period of each timer, carrier period = (carrier_period +
1)*800ns (carrier_period <= 15)

esp_err_t mcpwm_carrier_set_duty_cycle(mcpwm_unit_t mcpwm_num,

Set duty_cycle of carrier.

timer_num, uint8_t carrier_duty)

mcpwm_timer_t

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers · carrier_duty: set duty_cycle of carrier , carrier duty cycle = carrier_duty*12.5% (chop_duty <= 7)

esp_err_t mcpwm_carrier_oneshot_mode_enable(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num, uint8_t pulse_width)
Enable and set width of first pulse in carrier oneshot mode.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers · pulse_width: set pulse width of first pulse in oneshot mode, width = (carrier period)*(pulse_width +1) (pulse_width <= 15)

esp_err_t mcpwm_carrier_oneshot_mode_disable(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num)
Disable oneshot mode, width of first pulse = carrier period.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers

esp_err_t mcpwm_carrier_output_invert(mcpwm_unit_t mcpwm_num,

mcpwm_timer_t

timer_num, mcpwm_carrier_out_ivt_t carrier_ivt_mode)

Enable or disable carrier output inversion.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers · carrier_ivt_mode: enable or disable carrier output inversion

esp_err_t mcpwm_deadtime_enable(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num, mcpwm_deadtime_type_t dt_mode, uint32_t red, uint32_t fed)
Enable and initialize deadtime for each MCPWM timer.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters

Espressif Systems

628

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers · dt_mode: set deadtime mode · red: set rising edge delay = red*100ns · fed: set rising edge delay = fed*100ns

esp_err_t mcpwm_deadtime_disable(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num) Disable deadtime on MCPWM timer.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers

esp_err_t mcpwm_fault_init(mcpwm_unit_t mcpwm_num, mcpwm_fault_input_level_t intput_level, mcpwm_fault_signal_t fault_sig)
Initialize fault submodule, currently low level triggering is not supported.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · intput_level: set fault signal level, which will cause fault to occur · fault_sig: set the fault pin, which needs to be enabled

esp_err_t mcpwm_fault_set_oneshot_mode(mcpwm_unit_t mcpwm_num, mcpwm_timer_t

timer_num, mcpwm_fault_signal_t fault_sig,

mcpwm_output_action_t

action_on_pwmxa,

mcpwm_output_action_t action_on_pwmxb) Set oneshot mode on fault detection, once fault occur in oneshot mode reset is required to resume MCPWM

signals.

Note currently low level triggering is not supported Return
· ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers · fault_sig: set the fault pin, which needs to be enabled for oneshot mode · action_on_pwmxa: action to be taken on MCPWMXA when fault occurs, either no change or
high or low or toggle · action_on_pwmxb: action to be taken on MCPWMXB when fault occurs, either no change or
high or low or toggle

esp_err_t mcpwm_fault_set_cyc_mode(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num,

mcpwm_fault_signal_t fault_sig, mcpwm_output_action_t

action_on_pwmxa,

mcpwm_output_action_t

ac-

tion_on_pwmxb) Set cycle-by-cycle mode on fault detection, once fault occur in cyc mode MCPWM signal resumes as soon as

fault signal becomes inactive.

Note currently low level triggering is not supported Return
· ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers · fault_sig: set the fault pin, which needs to be enabled for cyc mode

Espressif Systems

629

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· action_on_pwmxa: action to be taken on MCPWMXA when fault occurs, either no change or high or low or toggle
· action_on_pwmxb: action to be taken on MCPWMXB when fault occurs, either no change or high or low or toggle

esp_err_t mcpwm_fault_deinit(mcpwm_unit_t mcpwm_num, mcpwm_fault_signal_t fault_sig) Disable fault signal.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · fault_sig: fault pin, which needs to be disabled

esp_err_t mcpwm_capture_enable(mcpwm_unit_t mcpwm_num, mcpwm_capture_signal_t cap_sig, mcpwm_capture_on_edge_t cap_edge, uint32_t num_of_pulse)
Initialize capture submodule.

Note Enabling capture feature would also enable the capture interrupt event, users have to register an interrupt handler by mcpwm_isr_register, and in there, query the capture data.
Note The capture timer uses APB_CLK (typically 80MHz) as the count source. Return
· ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error Parameters · mcpwm_num: set MCPWM unit(0-1) · cap_edge: set capture edge, BIT(0) - negative edge, BIT(1) - positive edge · cap_sig: capture pin, which needs to be enabled · num_of_pulse: Input capture signal prescaling, ranges from 0 to 255, representing prescaling
from 1 to 256.

esp_err_t mcpwm_capture_disable(mcpwm_unit_t mcpwm_num, mcpwm_capture_signal_t cap_sig) Disable capture signal.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · cap_sig: capture pin, which needs to be disabled

esp_err_t mcpwm_capture_enable_channel(mcpwm_unit_t

mcpwm_num,

mcpwm_capture_channel_id_t cap_channel, const

mcpwm_capture_config_t *cap_conf)

Enable capture channel.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · cap_channel: capture channel, which needs to be enabled · cap_conf: capture channel configuration

esp_err_t mcpwm_capture_disable_channel(mcpwm_unit_t

mcpwm_num,

Disable capture channel.

mcpwm_capture_channel_id_t cap_channel)

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1)

Espressif Systems

630

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· cap_channel: capture channel, which needs to be disabled

uint32_t mcpwm_capture_signal_get_value(mcpwm_unit_t

Get capture value.

mcpwm_capture_signal_t cap_sig)

mcpwm_num,

Return Captured value Parameters
· mcpwm_num: set MCPWM unit(0-1) · cap_sig: capture channel on which value is to be measured

uint32_t mcpwm_capture_signal_get_edge(mcpwm_unit_t

Get edge of capture signal.

mcpwm_capture_signal_t cap_sig)

mcpwm_num,

Return Capture signal edge: 1 - positive edge, 2 - negtive edge Parameters
· mcpwm_num: set MCPWM unit(0-1) · cap_sig: capture channel of whose edge is to be determined

esp_err_t mcpwm_sync_enable(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num, mcpwm_sync_signal_t sync_sig, uint32_t phase_val)
Initialize sync submodule and sets the signal that will cause the timer be loaded with pre-defined value.

Note Count direction is undefined within this API Return
· ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers · sync_sig: set the synchronization input signal · phase_val: phase value in 1/1000 (for 86.7%, phase_val = 867) which timer moves to on sync
signal

esp_err_t mcpwm_sync_configure(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num, const mcpwm_sync_config_t *sync_conf)
Initialize sync submodule and sets the signal that will cause the timer be loaded with pre-defined value.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers · sync_conf: sync configuration on this timer

esp_err_t mcpwm_sync_disable(mcpwm_unit_t mcpwm_num, mcpwm_timer_t timer_num) Disable sync submodule on given timer.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers

esp_err_t mcpwm_set_timer_sync_output(mcpwm_unit_t mcpwm_num,

mcpwm_timer_t

timer_num, mcpwm_timer_sync_trigger_t trigger)

Set sync output on given timer Configures what event triggers MCPWM timer to output a sync signal.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters

Espressif Systems

631

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers · trigger: set the trigger that will cause the timer to generate a software sync signal. Specifically,
MCPWM_SWSYNC_SOURCE_DISABLED will disable the timer from generating sync signal.

esp_err_t mcpwm_timer_trigger_soft_sync(mcpwm_unit_t timer_num)
Trigger a software sync event and sends it to a specific timer.

mcpwm_num,

mcpwm_timer_t

Note This software sync event will have the same effect as hw one, except that: · On esp32s3 the soft sync event can be routed to its output if MCPWM_SWSYNC_SOURCE_SYNCIN is selected via mcpwm_set_timer_sync_output() · On esp32 there is no such behavior and soft sync event will only take effect on this timer and can not be propagated to others.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Function pointer error.
Parameters · mcpwm_num: set MCPWM unit(0-1) · timer_num: set timer number(0-2) of MCPWM, each MCPWM unit has 3 timers

esp_err_t mcpwm_sync_invert_gpio_synchro(mcpwm_unit_t mcpwm_num, mcpwm_sync_signal_t

Set external GPIO sync input inverter.

sync_sig, bool invert)

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Function pointer error.
Parameters · mcpwm_num: set MCPWM unit(0-1) · sync_sig: set sync signal of MCPWM, only supports GPIO sync signal · invert: whether GPIO sync source input is inverted (to get negative edge trigger)

esp_err_t mcpwm_isr_register(mcpwm_unit_t mcpwm_num, void (*fn))void * , void *arg, int intr_alloc_flags, intr_handle_t *handleRegister MCPWM interrupt handler, the handler is an ISR. the handler will be attached to the same CPU core that this function is running on.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Function pointer error.
Parameters · mcpwm_num: set MCPWM unit(0-1) · fn: interrupt handler function. · arg: user-supplied argument passed to the handler function. · intr_alloc_flags: flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. see esp_intr_alloc.h for more info. · handle: pointer to return handle. If non-NULL, a handle for the interrupt will be returned here.

Structures struct mcpwm_pin_config_t
pin number for MCPWM

Public Members
int mcpwm0a_out_num MCPWM0A out pin
int mcpwm0b_out_num MCPWM0A out pin

Espressif Systems

632

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

int mcpwm1a_out_num MCPWM0A out pin
int mcpwm1b_out_num MCPWM0A out pin
int mcpwm2a_out_num MCPWM0A out pin
int mcpwm2b_out_num MCPWM0A out pin
int mcpwm_sync0_in_num SYNC0 in pin
int mcpwm_sync1_in_num SYNC1 in pin
int mcpwm_sync2_in_num SYNC2 in pin
int mcpwm_fault0_in_num FAULT0 in pin
int mcpwm_fault1_in_num FAULT1 in pin
int mcpwm_fault2_in_num FAULT2 in pin
int mcpwm_cap0_in_num CAP0 in pin
int mcpwm_cap1_in_num CAP1 in pin
int mcpwm_cap2_in_num CAP2 in pin
struct cap_event_data_t event data that will be passed into ISR callback
Public Members
mcpwm_capture_on_edge_t cap_edge Which signal edge is detected
uint32_t cap_value Corresponding timestamp when event occurs. Clock rate = APB(usually 80M)
struct mcpwm_config_t MCPWM config structure.
Public Members
uint32_t frequency Set frequency of MCPWM in Hz
float cmpr_a Set % duty cycle for operator a(MCPWMXA), i.e for 62.3% duty cycle, duty_a = 62.3
float cmpr_b Set % duty cycle for operator b(MCPWMXB), i.e for 48% duty cycle, duty_b = 48.0
mcpwm_duty_type_t duty_mode Set type of duty cycle

Espressif Systems

633

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

mcpwm_counter_type_t counter_mode Set type of MCPWM counter
struct mcpwm_carrier_config_t MCPWM carrier configuration structure.
Public Members
uint8_t carrier_period Set carrier period = (carrier_period + 1)*800ns, carrier_period should be < 16
uint8_t carrier_duty Set carrier duty cycle, carrier_duty should be less than 8 (increment every 12.5%)
uint8_t pulse_width_in_os Set pulse width of first pulse in one shot mode = (carrier period)*(pulse_width_in_os + 1), should be less then 16
mcpwm_carrier_os_t carrier_os_mode Enable or disable carrier oneshot mode
mcpwm_carrier_out_ivt_t carrier_ivt_mode Invert output of carrier
struct mcpwm_capture_config_t MCPWM config capture structure.
Public Members
mcpwm_capture_on_edge_t cap_edge Set capture edge
uint32_t cap_prescale Prescale of capture signal, ranging from 1 to 256
cap_isr_cb_t capture_cb User defined capture event callback, running under interrupt context
void *user_data User defined ISR callback function args
struct mcpwm_sync_config_t MCPWM config sync structure.
Public Members
mcpwm_sync_signal_t sync_sig Set sync input signal that will cause timer to sync
uint32_t timer_val Counter value to be set after sync, in 0 ~ 999, unit: 1 / 1000 * peak
mcpwm_timer_direction_t count_direction Counting direction to be set after sync
Macros MCPWM_OPR_A MCPWM_OPR_B MCPWM_OPR_MAX MCPWM_SELCT_SYNC0

Espressif Systems

634

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
MCPWM_SELCT_SYNC1
MCPWM_SELCT_SYNC2
MCPWM_NO_CHANGE_IN_MCPWMXA
MCPWM_FORCE_MCPWMXA_LOW
MCPWM_FORCE_MCPWMXA_HIGH
MCPWM_TOG_MCPWMXA
MCPWM_NO_CHANGE_IN_MCPWMXB
MCPWM_FORCE_MCPWMXB_LOW
MCPWM_FORCE_MCPWMXB_HIGH
MCPWM_TOG_MCPWMXB
Type Definitions typedef mcpwm_generator_t mcpwm_operator_t typedef mcpwm_output_action_t mcpwm_action_on_pwmxa_t
typedef mcpwm_output_action_t mcpwm_action_on_pwmxb_t
typedef mcpwm_capture_signal_t mcpwm_capture_channel_id_t MCPWM capture channel ID alias.
typedef bool (*cap_isr_cb_t)(mcpwm_unit_t mcpwm, mcpwm_capture_channel_id_t cap_channel, const cap_event_data_t *edata, void *user_data)
Type of capture event callback.
Note Since this an ISR callback so do not do anything that may block and call APIs that is designed to be used within ISR(usually has m_ISRnpostfix)
Return Whether a task switch is needed after the callback function returns, this is usually due to the callback wakes up some high priority task.
Parameters · mcpwm: MCPWM unit(0-1) · cap_channel: capture channel ID · edata: Capture event data, contains capture edge and capture value, fed by the driver · user_data: User registered data, passed from mcpwm_capture_config_t
Enumerations enum mcpwm_io_signals_t
IO signals for the MCPWM.
- 6 MCPWM output pins that generate PWM signals - 3 MCPWM fault input pins to detect faults like overcurrent, overvoltage, etc. - 3 MCPWM sync input pins to synchronize MCPWM outputs signals - 3 MCPWM capture input pins to gather feedback from controlled motors, using e.g. hall sensors
Values:
MCPWM0A = 0 PWM0A output pin
MCPWM0B PWM0B output pin
MCPWM1A PWM1A output pin

Espressif Systems

635

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

MCPWM1B PWM1B output pin
MCPWM2A PWM2A output pin
MCPWM2B PWM2B output pin
MCPWM_SYNC_0 SYNC0 input pin
MCPWM_SYNC_1 SYNC1 input pin
MCPWM_SYNC_2 SYNC2 input pin
MCPWM_FAULT_0 FAULT0 input pin
MCPWM_FAULT_1 FAULT1 input pin
MCPWM_FAULT_2 FAULT2 input pin
MCPWM_CAP_0 = 84 CAP0 input pin
MCPWM_CAP_1 CAP1 input pin
MCPWM_CAP_2 CAP2 input pin
enum mcpwm_unit_t Select MCPWM unit.
Values:
MCPWM_UNIT_0 MCPWM unit0 selected
MCPWM_UNIT_1 MCPWM unit1 selected
MCPWM_UNIT_MAX Max number of MCPWM units
enum mcpwm_timer_t Select MCPWM timer.
Values:
MCPWM_TIMER_0 Select MCPWM timer0
MCPWM_TIMER_1 Select MCPWM timer1
MCPWM_TIMER_2 Select MCPWM timer2
MCPWM_TIMER_MAX Max number of timers in a unit
enum mcpwm_generator_t Select MCPWM operator.
Values:

Espressif Systems

636

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

MCPWM_GEN_A Select MCPWMXA, where mXnis operator number
MCPWM_GEN_B Select MCPWMXB, where mXnis operator number
MCPWM_GEN_MAX Num of generators to each operator of MCPWM
enum mcpwm_carrier_os_t MCPWM carrier oneshot mode, in this mode the width of the first pulse of carrier can be programmed.
Values:
MCPWM_ONESHOT_MODE_DIS Enable oneshot mode
MCPWM_ONESHOT_MODE_EN Disable oneshot mode
enum mcpwm_carrier_out_ivt_t MCPWM carrier output inversion, high frequency carrier signal active with MCPWM signal is high.
Values:
MCPWM_CARRIER_OUT_IVT_DIS Enable carrier output inversion
MCPWM_CARRIER_OUT_IVT_EN Disable carrier output inversion
enum mcpwm_fault_signal_t MCPWM select fault signal input.
Values:
MCPWM_SELECT_F0 Select F0 as input
MCPWM_SELECT_F1 Select F1 as input
MCPWM_SELECT_F2 Select F2 as input
enum mcpwm_sync_signal_t MCPWM select sync signal input.
Values:
MCPWM_SELECT_NO_INPUT No sync input selected
MCPWM_SELECT_TIMER0_SYNC Select software sync signal from timer0 as input
MCPWM_SELECT_TIMER1_SYNC Select software sync signal from timer1 as input
MCPWM_SELECT_TIMER2_SYNC Select software sync signal from timer2 as input
MCPWM_SELECT_GPIO_SYNC0 Select GPIO SYNC0 as input
MCPWM_SELECT_GPIO_SYNC1 Select GPIO SYNC1 as input
MCPWM_SELECT_GPIO_SYNC2 Select GPIO SYNC2 as input

Espressif Systems

637

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
enum mcpwm_timer_sync_trigger_t MCPWM timer sync event trigger.
Values:
MCPWM_SWSYNC_SOURCE_SYNCIN the input sync signal will be routed to its sync output path
MCPWM_SWSYNC_SOURCE_TEZ sync signal generated when timer counts to zero
MCPWM_SWSYNC_SOURCE_TEP sync signal generated when timer counts to peak
MCPWM_SWSYNC_SOURCE_DISABLED timer does not generate sync signals
enum mcpwm_fault_input_level_t MCPWM select triggering level of fault signal.
Values:
MCPWM_LOW_LEVEL_TGR Fault condition occurs when fault input signal goes from high to low
MCPWM_HIGH_LEVEL_TGR Fault condition occurs when fault input signal goes low to high
enum mcpwm_capture_on_edge_t MCPWM select capture starts from which edge.
Values:
MCPWM_NEG_EDGE = BIT(0) Capture the negative edge
MCPWM_POS_EDGE = BIT(1) Capture the positive edge
MCPWM_BOTH_EDGE = BIT(1) | BIT(0) Capture both edges
enum mcpwm_intr_t Interrupt masks for MCPWM capture.
Values:
MCPWM_LL_INTR_CAP0 = BIT(27) Capture 0 happened.
MCPWM_LL_INTR_CAP1 = BIT(28) Capture 1 happened.
MCPWM_LL_INTR_CAP2 = BIT(29) Capture 2 happened.
enum mcpwm_counter_type_t Select type of MCPWM counter.
Values:
MCPWM_FREEZE_COUNTER Counter freeze
MCPWM_UP_COUNTER For asymmetric MCPWM
MCPWM_DOWN_COUNTER For asymmetric MCPWM

Espressif Systems

638

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

MCPWM_UP_DOWN_COUNTER For symmetric MCPWM, frequency is half of MCPWM frequency set
MCPWM_COUNTER_MAX Maximum counter mode
enum mcpwm_duty_type_t Select type of MCPWM duty cycle mode.
Values:
MCPWM_DUTY_MODE_0 = 0 Active high duty, i.e. duty cycle proportional to high time for asymmetric MCPWM
MCPWM_DUTY_MODE_1 Active low duty, i.e. duty cycle proportional to low time for asymmetric MCPWM, out of phase(inverted) MCPWM
MCPWM_HAL_GENERATOR_MODE_FORCE_LOW
MCPWM_HAL_GENERATOR_MODE_FORCE_HIGH
MCPWM_DUTY_MODE_MAX Num of duty cycle modes
enum mcpwm_deadtime_type_t MCPWM deadtime types, used to generate deadtime, RED refers to rising edge delay and FED refers to falling edge delay.
Values:
MCPWM_DEADTIME_BYPASS = 0 Bypass the deadtime
MCPWM_BYPASS_RED MCPWMXA Out = MCPWMXA In with no delay, MCPWMXB Out = MCPWMXA In with falling edge delay
MCPWM_BYPASS_FED MCPWMXA Out = MCPWMXA In with rising edge delay, MCPWMXB Out = MCPWMXB In with no delay
MCPWM_ACTIVE_HIGH_MODE MCPWMXA Out = MCPWMXA In with rising edge delay, MCPWMXB Out = MCPWMXA In with falling edge delay
MCPWM_ACTIVE_LOW_MODE MCPWMXA Out = MCPWMXA In with compliment of rising edge delay, MCPWMXB Out = MCPWMXA In with compliment of falling edge delay
MCPWM_ACTIVE_HIGH_COMPLIMENT_MODE MCPWMXA Out = MCPWMXA In with rising edge delay, MCPWMXB = MCPWMXA In with compliment of falling edge delay
MCPWM_ACTIVE_LOW_COMPLIMENT_MODE MCPWMXA Out = MCPWMXA In with compliment of rising edge delay, MCPWMXB Out = MCPWMXA In with falling edge delay
MCPWM_ACTIVE_RED_FED_FROM_PWMXA MCPWMXA Out = MCPWMXB Out = MCPWMXA In with rising edge delay as well as falling edge delay
MCPWM_ACTIVE_RED_FED_FROM_PWMXB MCPWMXA Out = MCPWMXB Out = MCPWMXB In with rising edge delay as well as falling edge delay
MCPWM_DEADTIME_TYPE_MAX Maximum number of supported dead time modes

Espressif Systems

639

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
enum mcpwm_output_action_t MCPWM select action to be taken on the output when event happens. Values: MCPWM_ACTION_NO_CHANGE = 0 No change in the output MCPWM_ACTION_FORCE_LOW Make output low MCPWM_ACTION_FORCE_HIGH Make output high MCPWM_ACTION_TOGGLE Make output toggle
enum mcpwm_capture_signal_t MCPWM select capture signal input. Values: MCPWM_SELECT_CAP0 Select CAP0 as input MCPWM_SELECT_CAP1 Select CAP1 as input MCPWM_SELECT_CAP2 Select CAP2 as input
2.3.12 Pulse Counter (PCNT)
Introduction
The PCNT (Pulse Counter) module is designed to count the number of rising and/or falling edges of an input signal. Each pulse counter unit has a 16-bit signed counter register and two channels that can be configured to either increment or decrement the counter. Each channel has a signal input that accepts signal edges to be detected, as well as a control input that can be used to enable or disable the signal input. The inputs have optional filters that can be used to discard unwanted glitches in the signal.
Functionality Overview
Description of functionality of this API has been broken down into four sections: · Configuration - describes counterns configuration parameters and how to setup the counter. · Operating the Counter - provides information on control functions to pause, measure and clear the counter. · Filtering Pulses - describes options to filtering pulses and the counter control signals. · Using Interrupts - presents how to trigger interrupts on specific states of the counter.
Configuration
The PCNT module has 8 independent counting ounitspnumbered from 0 to 7. In the API they are referred to using pcnt_unit_t. Each unit has two independent channels numbered as 0 and 1 and specified with pcnt_channel_t. The configuration is provided separately per unitns channel using pcnt_config_t and covers:
· The unit and the channel number this configuration refers to. · GPIO numbers of the pulse input and the pulse gate input.

Espressif Systems

640

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· Two pairs of parameters: pcnt_ctrl_mode_t and pcnt_count_mode_t to define how the counter reacts depending on the the status of control signal and how counting is done positive / negative edge of the pulses.
· Two limit values (minimum / maximum) that are used to establish watchpoints and trigger interrupts when the pulse count is meeting particular limit.
Setting up of particular channel is then done by calling a function pcnt_unit_config() with above pcnt_config_t as the input parameter. To disable the pulse or the control input pin in configuration, provide PCNT_PIN_NOT_USED instead of the GPIO number.
Operating the Counter
After doing setup with pcnt_unit_config(), the counter immediately starts to operate. The accumulated pulse count can be checked by calling pcnt_get_counter_value(). There are couple of functions that allow to control the counterns operation: pcnt_counter_pause(), pcnt_counter_resume() and pcnt_counter_clear() It is also possible to dynamically change the previously set up counter modes with pcnt_unit_config() by calling pcnt_set_mode(). If desired, the pulse input pin and the control input pin may be changed oon the flypusing pcnt_set_pin(). To disable particular input provide as a function parameter PCNT_PIN_NOT_USED instead of the GPIO number.
Note: For the counter not to miss any pulses, the pulse duration should be longer than one APB_CLK cycle (12.5 ns). The pulses are sampled on the edges of the APB_CLK clock and may be missed, if fall between the edges. This applies to counter operation with or without a filter.
Filtering Pulses
The PCNT unit features filters on each of the pulse and control inputs, adding the option to ignore short glitches in the signals. The length of ignored pulses is provided in APB_CLK clock cycles by calling pcnt_set_filter_value(). The current filter setting may be checked with pcnt_get_filter_value(). The APB_CLK clock is running at 80 MHz. The filter is put into operation / suspended by calling pcnt_filter_enable() / pcnt_filter_disable().
Using Interrupts
There are five counter state watch events, defined in pcnt_evt_type_t, that are able to trigger an interrupt. The event happens on the pulse counter reaching specific values:
· Minimum or maximum count values: counter_l_lim or counter_h_lim provided in pcnt_config_t as discussed in Configuration
· Threshold 0 or Threshold 1 values set using function pcnt_set_event_value(). · Pulse count = 0 To register, enable or disable an interrupt to service the above events, call pcnt_isr_register(), pcnt_intr_enable(). and pcnt_intr_disable(). To enable or disable events on reaching threshold values, you will also need to call functions pcnt_event_enable() and pcnt_event_disable(). In order to check what are the threshold values currently set, use function pcnt_get_event_value().

Espressif Systems

641

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Application Example
· Pulse counter with control signal and event interrupt example: peripherals/pcnt/pulse_count_event. · Parse the signal generated from rotary encoder: peripherals/pcnt/rotary_encoder.

API Reference
Header File · components/driver/include/driver/pcnt.h

Functions esp_err_t pcnt_unit_config(const pcnt_config_t *pcnt_config)
Configure Pulse Counter unit.

Note This function will disable three events: PCNT_EVT_L_LIM, PCNT_EVT_ZERO.
Return · ESP_OK Success · ESP_ERR_INVALID_STATE pcnt driver already initialized · ESP_ERR_INVALID_ARG Parameter error
Parameters · pcnt_config: Pointer of Pulse Counter unit configure parameter
esp_err_t pcnt_get_counter_value(pcnt_unit_t pcnt_unit, int16_t *count) Get pulse counter value.

PCNT_EVT_H_LIM,

Return · ESP_OK Success · ESP_ERR_INVALID_STATE pcnt driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error
Parameters · pcnt_unit: Pulse Counter unit number · count: Pointer to accept counter value

esp_err_t pcnt_counter_pause(pcnt_unit_t pcnt_unit) Pause PCNT counter of PCNT unit.

Return · ESP_OK Success · ESP_ERR_INVALID_STATE pcnt driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error
Parameters · pcnt_unit: PCNT unit number

esp_err_t pcnt_counter_resume(pcnt_unit_t pcnt_unit) Resume counting for PCNT counter.

Return · ESP_OK Success · ESP_ERR_INVALID_STATE pcnt driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error
Parameters · pcnt_unit: PCNT unit number, select from pcnt_unit_t

esp_err_t pcnt_counter_clear(pcnt_unit_t pcnt_unit) Clear and reset PCNT counter value to zero.

Return · ESP_OK Success · ESP_ERR_INVALID_STATE pcnt driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error

Espressif Systems

642

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Parameters · pcnt_unit: PCNT unit number, select from pcnt_unit_t
esp_err_t pcnt_intr_enable(pcnt_unit_t pcnt_unit) Enable PCNT interrupt for PCNT unit.
Note Each Pulse counter unit has five watch point events that share the same interrupt. Configure events with pcnt_event_enable() and pcnt_event_disable()
Return · ESP_OK Success · ESP_ERR_INVALID_STATE pcnt driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error
Parameters · pcnt_unit: PCNT unit number
esp_err_t pcnt_intr_disable(pcnt_unit_t pcnt_unit) Disable PCNT interrupt for PCNT unit.
Return · ESP_OK Success · ESP_ERR_INVALID_STATE pcnt driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error
Parameters · pcnt_unit: PCNT unit number
esp_err_t pcnt_event_enable(pcnt_unit_t unit, pcnt_evt_type_t evt_type) Enable PCNT event of PCNT unit.
Return · ESP_OK Success · ESP_ERR_INVALID_STATE pcnt driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error
Parameters · unit: PCNT unit number · evt_type: Watch point event type. All enabled events share the same interrupt (one interrupt per pulse counter unit).
esp_err_t pcnt_event_disable(pcnt_unit_t unit, pcnt_evt_type_t evt_type) Disable PCNT event of PCNT unit.
Return · ESP_OK Success · ESP_ERR_INVALID_STATE pcnt driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error
Parameters · unit: PCNT unit number · evt_type: Watch point event type. All enabled events share the same interrupt (one interrupt per pulse counter unit).
esp_err_t pcnt_set_event_value(pcnt_unit_t unit, pcnt_evt_type_t evt_type, int16_t value) Set PCNT event value of PCNT unit.
Return · ESP_OK Success · ESP_ERR_INVALID_STATE pcnt driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error
Parameters · unit: PCNT unit number · evt_type: Watch point event type. All enabled events share the same interrupt (one interrupt per pulse counter unit). · value: Counter value for PCNT event
esp_err_t pcnt_get_event_value(pcnt_unit_t unit, pcnt_evt_type_t evt_type, int16_t *value) Get PCNT event value of PCNT unit.

Espressif Systems

643

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return · ESP_OK Success · ESP_ERR_INVALID_STATE pcnt driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error
Parameters · unit: PCNT unit number · evt_type: Watch point event type. All enabled events share the same interrupt (one interrupt per pulse counter unit). · value: Pointer to accept counter value for PCNT event
esp_err_t pcnt_get_event_status(pcnt_unit_t unit, uint32_t *status) Get PCNT event status of PCNT unit.
Return · ESP_OK Success · ESP_ERR_INVALID_STATE pcnt driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error
Parameters · unit: PCNT unit number · status: Pointer to accept event status word
esp_err_t pcnt_isr_unregister(pcnt_isr_handle_t handle) Unregister PCNT interrupt handler (registered by pcnt_isr_register), the handler is an ISR. The handler will be attached to the same CPU core that this function is running on. If the interrupt service is registered by pcnt_isr_service_install, please call pcnt_isr_service_uninstall instead.
Return · ESP_OK Success · ESP_ERR_NOT_FOUND Can not find the interrupt that matches the flags. · ESP_ERR_INVALID_ARG Function pointer error.
Parameters · handle: handle to unregister the ISR service.
esp_err_t pcnt_isr_register(void (*fn))void * , void *arg, int intr_alloc_flags, pcnt_isr_handle_t *handleRegister PCNT interrupt handler, the handler is an ISR. The handler will be attached to the same CPU core that this function is running on. Please do not use pcnt_isr_service_install if this function was called.
Return · ESP_OK Success · ESP_ERR_NOT_FOUND Can not find the interrupt that matches the flags. · ESP_ERR_INVALID_ARG Function pointer error.
Parameters · fn: Interrupt handler function. · arg: Parameter for handler function · intr_alloc_flags: Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info. · handle: Pointer to return handle. If non-NULL, a handle for the interrupt will be returned here. Calling pcnt_isr_unregister to unregister this ISR service if needed, but only if the handle is not NULL.
esp_err_t pcnt_set_pin(pcnt_unit_t unit, pcnt_channel_t channel, int pulse_io, int ctrl_io) Configure PCNT pulse signal input pin and control input pin.
Note Set the signal input to PCNT_PIN_NOT_USED if unused. Return
· ESP_OK Success · ESP_ERR_INVALID_STATE pcnt driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error Parameters · unit: PCNT unit number · channel: PCNT channel number

Espressif Systems

644

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· pulse_io: Pulse signal input GPIO · ctrl_io: Control signal input GPIO
esp_err_t pcnt_filter_enable(pcnt_unit_t unit) Enable PCNT input filter.
Return · ESP_OK Success · ESP_ERR_INVALID_STATE pcnt driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error
Parameters · unit: PCNT unit number
esp_err_t pcnt_filter_disable(pcnt_unit_t unit) Disable PCNT input filter.
Return · ESP_OK Success · ESP_ERR_INVALID_STATE pcnt driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error
Parameters · unit: PCNT unit number
esp_err_t pcnt_set_filter_value(pcnt_unit_t unit, uint16_t filter_val) Set PCNT filter value.
Note filter_val is a 10-bit value, so the maximum filter_val should be limited to 1023. Return
· ESP_OK Success · ESP_ERR_INVALID_STATE pcnt driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error Parameters · unit: PCNT unit number · filter_val: PCNT signal filter value, counter in APB_CLK cycles. Any pulses lasting shorter
than this will be ignored when the filter is enabled.
esp_err_t pcnt_get_filter_value(pcnt_unit_t unit, uint16_t *filter_val) Get PCNT filter value.
Return · ESP_OK Success · ESP_ERR_INVALID_STATE pcnt driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error
Parameters · unit: PCNT unit number · filter_val: Pointer to accept PCNT filter value.
esp_err_t pcnt_set_mode(pcnt_unit_t unit, pcnt_channel_t channel, pcnt_count_mode_t pos_mode, pcnt_count_mode_t neg_mode, pcnt_ctrl_mode_t hctrl_mode, pcnt_ctrl_mode_t lctrl_mode)
Set PCNT counter mode.
Return · ESP_OK Success · ESP_ERR_INVALID_STATE pcnt driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error
Parameters · unit: PCNT unit number · channel: PCNT channel number · pos_mode: Counter mode when detecting positive edge · neg_mode: Counter mode when detecting negative edge · hctrl_mode: Counter mode when control signal is high level · lctrl_mode: Counter mode when control signal is low level

Espressif Systems

645

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
esp_err_t pcnt_isr_handler_add(pcnt_unit_t unit, void (*isr_handler))void * , void *argsAdd ISR handler for specified unit.
Call this function after using pcnt_isr_service_install() to install the PCNT driverns ISR handler service.
The ISR handlers do not need to be declared with IRAM_ATTR, unless you pass the ESP_INTR_FLAG_IRAM flag when allocating the ISR in pcnt_isr_service_install().
This ISR handler will be called from an ISR. So there is a stack size limit (configurable as oISR stack sizep in menuconfig). This limit is smaller compared to a global PCNT interrupt handler due to the additional level of indirection.
Return · ESP_OK Success · ESP_ERR_INVALID_STATE pcnt driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error
Parameters · unit: PCNT unit number · isr_handler: Interrupt handler function. · args: Parameter for handler function
esp_err_t pcnt_isr_service_install(int intr_alloc_flags) Install PCNT ISR service.
Note We can manage different interrupt service for each unit. This function will use the default ISR handle service, Calling pcnt_isr_service_uninstall to uninstall the default service if needed. Please do not use pcnt_isr_register if this function was called.
Return · ESP_OK Success · ESP_ERR_INVALID_STATE pcnt driver has not been initialized · ESP_ERR_NO_MEM No memory to install this service · ESP_ERR_INVALID_STATE ISR service already installed
Parameters · intr_alloc_flags: Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.
void pcnt_isr_service_uninstall(void) Uninstall PCNT ISR service, freeing related resources.
esp_err_t pcnt_isr_handler_remove(pcnt_unit_t unit) Delete ISR handler for specified unit.
Return · ESP_OK Success · ESP_ERR_INVALID_STATE pcnt driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error
Parameters · unit: PCNT unit number
Structures struct pcnt_config_t
Pulse Counter configuration for a single channel.
Public Members
int pulse_gpio_num Pulse input GPIO number, if you want to use GPIO16, enter pulse_gpio_num = 16, a negative value will be ignored
int ctrl_gpio_num Control signal input GPIO number, a negative value will be ignored

Espressif Systems

646

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
pcnt_ctrl_mode_t lctrl_mode PCNT low control mode
pcnt_ctrl_mode_t hctrl_mode PCNT high control mode
pcnt_count_mode_t pos_mode PCNT positive edge count mode
pcnt_count_mode_t neg_mode PCNT negative edge count mode
int16_t counter_h_lim Maximum counter value
int16_t counter_l_lim Minimum counter value
pcnt_unit_t unit PCNT unit number
pcnt_channel_t channel the PCNT channel
Macros PCNT_PIN_NOT_USED
When selected for a pin, this pin will not be used PCNT_MODE_KEEP
Control mode: wonnt change counter mode
PCNT_MODE_REVERSE Control mode: invert counter mode(increase -> decrease, decrease -> increase)
PCNT_MODE_DISABLE Control mode: Inhibit counter(counter value will not change in this condition)
PCNT_MODE_MAX
PCNT_COUNT_DIS Counter mode: Inhibit counter(counter value will not change in this condition)
PCNT_COUNT_INC Counter mode: Increase counter value
PCNT_COUNT_DEC Counter mode: Decrease counter value
PCNT_COUNT_MAX
Type Definitions typedef intr_handle_t pcnt_isr_handle_t typedef pcnt_channel_level_action_t pcnt_ctrl_mode_t
Selection of available modes that determine the counterns action depending on the state of the control signaln s input GPIO.
Note Configuration covers two actions, one for high, and one for low level on the control input
typedef pcnt_channel_edge_action_t pcnt_count_mode_t Selection of available modes that determine the counterns action on the edge of the pulse signalns input GPIO.
Note Configuration covers two actions, one for positive, and one for negative edge on the pulse input

Espressif Systems

647

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Enumerations enum pcnt_port_t
PCNT port number, the max port number is (PCNT_PORT_MAX - 1).
Values:
PCNT_PORT_0 PCNT port 0
PCNT_PORT_MAX PCNT port max
enum pcnt_unit_t Selection of all available PCNT units.
Values:
PCNT_UNIT_0 PCNT unit 0
PCNT_UNIT_1 PCNT unit 1
PCNT_UNIT_2 PCNT unit 2
PCNT_UNIT_3 PCNT unit 3
PCNT_UNIT_MAX
enum pcnt_channel_t Selection of channels available for a single PCNT unit.
Values:
PCNT_CHANNEL_0 PCNT channel 0
PCNT_CHANNEL_1 PCNT channel 1
PCNT_CHANNEL_MAX
enum pcnt_evt_type_t Selection of counterns events the may trigger an interrupt.
Values:
PCNT_EVT_THRES_1 = 1 << 2 PCNT watch point event: threshold1 value event
PCNT_EVT_THRES_0 = 1 << 3 PCNT watch point event: threshold0 value event
PCNT_EVT_L_LIM = 1 << 4 PCNT watch point event: Minimum counter value
PCNT_EVT_H_LIM = 1 << 5 PCNT watch point event: Maximum counter value
PCNT_EVT_ZERO = 1 << 6 PCNT watch point event: counter value zero event
PCNT_EVT_MAX
Header File
· components/hal/include/hal/pcnt_types.h

Espressif Systems

648

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Enumerations enum pcnt_channel_level_action_t
PCNT channel action on control level.
Values:
PCNT_CHANNEL_LEVEL_ACTION_KEEP Keep current count mode
PCNT_CHANNEL_LEVEL_ACTION_INVERSE Invert current count mode (increase -> decrease, decrease -> increase)
PCNT_CHANNEL_LEVEL_ACTION_HOLD Hold current count value
enum pcnt_channel_edge_action_t PCNT channel action on signal edge.
Values:
PCNT_CHANNEL_EDGE_ACTION_HOLD Hold current count value
PCNT_CHANNEL_EDGE_ACTION_INCREASE Increase count value
PCNT_CHANNEL_EDGE_ACTION_DECREASE Decrease count value
enum pcnt_unit_count_sign_t PCNT unit counter valuens sign.
Values:
PCNT_UNIT_COUNT_SIGN_ZERO_POS positive value to zero
PCNT_UNIT_COUNT_SIGN_ZERO_NEG negative value to zero
PCNT_UNIT_COUNT_SIGN_NEG counter value negative
PCNT_UNIT_COUNT_SIGN_POS counter value positive

2.3.13 Remote Control (RMT)
The RMT (Remote Control) module driver can be used to send and receive infrared remote control signals. Due to flexibility of RMT module, the driver can also be used to generate or receive many other types of signals.
The signal, which consists of a series of pulses, is generated by RMTns transmitter based on a list of values. The values define the pulse duration and a binary level, see below. The transmitter can also provide a carrier and modulate it with provided pulses.
The reverse operation is performed by the receiver, where a series of pulses is decoded into a list of values containing the pulse duration and binary level. A filter may be applied to remove high frequency noise from the input signal.
There couple of typical steps to setup and operate the RMT and they are discussed in the following sections:
1. Configure Driver 2. Transmit Data or Receive Data 3. Change Operation Parameters 4. Use Interrupts
The RMT has eight channels numbered from zero to seven. The first half (i.e. Channel 0 ~ 3) channels can only be configured for transmitting, and the other half (i.e. Channel 4 ~ 7) channels can only be configured for receiving. They are referred to using indexes defined in structure rmt_channel_t.

Espressif Systems

649

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference Fig. 12: RMT Transmitter Overview

Fig. 13: RMT Receiver Overview

Espressif Systems

650

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Configure Driver
There are several parameters that define how particular channel operates. Most of these parameters are configured by setting specific members of rmt_config_t structure. Some of the parameters are common to both transmit or receive mode, and some are mode specific. They are all discussed below.
Common Parameters
· The channel to be configured, select one from the rmt_channel_t enumerator. · The RMT operation mode - whether this channel is used to transmit or receive data, selected by setting a
rmt_mode members to one of the values from rmt_mode_t. · What is the pin number to transmit or receive RMT signals, selected by setting gpio_num. · How many memory blocks will be used by the channel, set with mem_block_num. · Extra miscellaneous parameters for the channel can be set in the flags.
­ When RMT_CHANNEL_FLAGS_AWARE_DFS is set, RMT channel will take REF_TICK or XTAL as source clock. The benefit is, RMT channel can continue work even when APB clock is changing. See power_management for more information.
­ When RMT_CHANNEL_FLAGS_INVERT_SIG is set, the driver will invert the RMT signal sending to or receiving from the channel. It just works like an external inverter connected to the GPIO of certain RMT channel.
· A clock divider, that will determine the range of pulse length generated by the RMT transmitter or discriminated by the receiver. Selected by setting clk_div to a value within [1 .. 255] range. The RMT source clock is typically APB CLK, 80Mhz by default. But when RMT_CHANNEL_FLAGS_AWARE_DFS is set in flags, RMT source clock is changed to REF_TICK or XTAL.
Note: The period of a square wave after the clock divider is called a mtickn. The length of the pulses generated by the RMT transmitter or discriminated by the receiver is configured in number of mticksn.
There are also couple of specific parameters that should be set up depending if selected channel is configured in Transmit Mode or Receive Mode:
Transmit Mode When configuring channel in transmit mode, set tx_config and the following members of rmt_tx_config_t:
· Transmit the currently configured data items in a loop - loop_en · Enable the RMT carrier signal - carrier_en · Frequency of the carrier in Hz - carrier_freq_hz · Duty cycle of the carrier signal in percent (%) - carrier_duty_percent · Level of the RMT output, when the carrier is applied - carrier_level · Enable the RMT output if idle - idle_output_en · Set the signal level on the RMT output if idle - idle_level · Specify maximum number of transmissions in a loop - loop_count
Receive Mode In receive mode, set rx_config and the following members of rmt_rx_config_t:
· Enable a filter on the input of the RMT receiver - filter_en · A threshold of the filter, set in the number of ticks - filter_ticks_thresh. Pulses shorter than this setting will
be filtered out. Note, that the range of entered tick values is [0..255]. · A pulse length threshold that will turn the RMT receiver idle, set in number of ticks - idle_threshold. The
receiver will ignore pulses longer than this setting. · Enable the RMT carrier demodulation - carrier_rm · Frequency of the carrier in Hz - carrier_freq_hz · Duty cycle of the carrier signal in percent (%) - carrier_duty_percent · Level of the RMT input, where the carrier is modulated to - carrier_level

Espressif Systems

651

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Finalize Configuration Once the rmt_config_t structure is populated with parameters, it should be then invoked with rmt_config() to make the configuration effective. The last configuration step is installation of the driver in memory by calling rmt_driver_install(). If rx_buf_size parameter of this function is > 0, then a ring buffer for incoming data will be allocated. A default ISR handler will be installed, see a note in Use Interrupts. Now, depending on how the channel is configured, we are ready to either Transmit Data or Receive Data. This is described in next two sections.
Transmit Data
Before being able to transmit some RMT pulses, we need to define the pulse pattern. The minimum pattern recognized by the RMT controller, later called an mitemn, is provided in a structure rmt_item32_t. Each item consists of two pairs of two values. The first value in a pair describes the signal duration in ticks and is 15 bits long, the second provides the signal level (high or low) and is contained in a single bit. A block of couple of items and the structure of an item is presented below.

Fig. 14: Structure of RMT items (L - signal level)
For a simple example how to define a block of items see peripherals/rmt/morse_code.
The items are provided to the RMT controller by calling function rmt_write_items(). This function also automatically triggers start of transmission. It may be called to wait for transmission completion or exit just after transmission start. In such case you can wait for the transmission end by calling rmt_wait_tx_done(). This function does not limit the number of data items to transmit. It is using an interrupt to successively copy the new data chunks to RMTns internal memory as previously provided data are sent out.
Another way to provide data for transmission is by calling rmt_fill_tx_items(). In this case transmission is not started automatically. To control the transmission process use rmt_tx_start() and rmt_tx_stop(). The number of items to sent is restricted by the size of memory blocks allocated in the RMT controllerns internal memory, see rmt_set_mem_block_num().

Receive Data
Before starting the receiver we need some storage for incoming items. The RMT controller has 384 x 32-bits of internal RAM shared between all eight channels. In typical scenarios it is not enough as an ultimate storage for all incoming (and outgoing) items. Therefore this API supports retrieval of incoming items on the fly to save them in a ring buffer of a size defined by the user. The

Espressif Systems

652

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

size is provided when calling rmt_driver_install() discussed above. To get a handle to this buffer call rmt_get_ringbuf_handle().
With the above steps complete we can start the receiver by calling rmt_rx_start() and then move to checking whatns inside the buffer. To do so, you can use common FreeRTOS functions that interact with the ring buffer. Please see an example how to do it in peripherals/rmt/ir_protocols.
To stop the receiver, call rmt_rx_stop().

Change Operation Parameters
Previously described function rmt_config() provides a convenient way to set several configuration parameters in one shot. This is usually done on application start. Then, when the application is running, the API provides an alternate way to update individual parameters by calling dedicated functions. Each function refers to the specific RMT channel provided as the first input parameter. Most of the functions have _get_ counterpart to read back the currently configured value.

Parameters Common to Transmit and Receive Mode
· Selection of a GPIO pin number on the input or output of the RMT - rmt_set_gpio() · Number of memory blocks allocated for the incoming or outgoing data - rmt_set_mem_pd() · Setting of the clock divider - rmt_set_clk_div() · Selection of the clock source, note that currently one clock source is supported, the APB clock which is 80Mhz
- rmt_set_source_clk()

Transmit Mode Parameters
· Enable or disable the loop back mode for the transmitter - rmt_set_tx_loop_mode() · Binary level on the output to apply the carrier - rmt_set_tx_carrier(), selected from
rmt_carrier_level_t · Determines the binary level on the output when transmitter is idle - rmt_set_idle_level(), selected
from rmt_idle_level_t
· Enable or disable loop count feature to automatically transmit items for N iterations, then trigger an ISR callback - rmt_set_tx_loop_count()
· Enable automatically stopping when the number of iterations matches the set loop count. Note this is not reliable for target that doesnnt support SOC_RMT_SUPPORT_TX_LOOP_AUTOSTOP. rmt_enable_tx_loop_autostop()

Receive Mode Parameters
· The filter setting - rmt_set_rx_filter() · The receiver threshold setting - rmt_set_rx_idle_thresh() · Whether the transmitter or receiver is entitled to access RMTns memory - rmt_set_memory_owner(),
selection is from rmt_mem_owner_t.

Use Interrupts
Registering of an interrupt handler for the RMT controller is done be calling rmt_isr_register().
Note: When calling rmt_driver_install() to use the system RMT driver, a default ISR is being installed. In such a case you cannot register a generic ISR handler with rmt_isr_register().
The RMT controller triggers interrupts on four specific events describes below. To enable interrupts on these events, the following functions are provided:
· The RMT receiver has finished receiving a signal - rmt_set_rx_intr_en()

Espressif Systems

653

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· The RMT transmitter has finished transmitting the signal - rmt_set_tx_intr_en() · The number of events the transmitter has sent matches a threshold value rmt_set_tx_thr_intr_en() · Ownership to the RMT memory block has been violated - rmt_set_err_intr_en() Setting or clearing an interrupt enable mask for specific channels and events may be also done by calling rmt_set_intr_enable_mask() or rmt_clr_intr_enable_mask(). When servicing an interrupt within an ISR, the interrupt need to explicitly cleared. To do so, set specific bits described as RMT.int_clr.val.chN_event_name and defined as a volatile struct in soc/esp32s3/include/soc/rmt_struct.h, where N is the RMT channel number [0, n] and the event_name is one of four events described above. If you do not need an ISR anymore, you can deregister it by calling a function rmt_isr_deregister().
Warning: Itns not recommended for users to register an interrupt handler in their applications. RMT driver is highly dependent on interrupt, especially when doing transaction in a ping-pong way, so the driver itself has registered a default handler called rmt_driver_isr_default. Instead, if what you want is to get a notification when transaction is done, go ahead with rmt_register_tx_end_callback().

Uninstall Driver
If the RMT driver has been installed with rmt_driver_install() for some specific period of time and then not required, the driver may be removed to free allocated resources by calling rmt_driver_uninstall().
Application Examples
· Using RMT to send morse code: peripherals/rmt/morse_code. · Using RMT to drive RGB LED strip: peripherals/rmt/led_strip. · NEC remote control TX and RX example: peripherals/rmt/ir_protocols. · Musical buzzer example: peripherals/rmt/musical_buzzer.
API Reference
Header File
· components/driver/include/driver/rmt.h
Functions esp_err_t rmt_set_clk_div(rmt_channel_t channel, uint8_t div_cnt)
Set RMT clock divider, channel clock is divided from source clock.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · div_cnt: RMT counter clock divider
esp_err_t rmt_get_clk_div(rmt_channel_t channel, uint8_t *div_cnt) Get RMT clock divider, channel clock is divided from source clock.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · div_cnt: pointer to accept RMT counter divider

Espressif Systems

654

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t rmt_set_rx_idle_thresh(rmt_channel_t channel, uint16_t thresh) Set RMT RX idle threshold value.
In receive mode, when no edge is detected on the input signal for longer than idle_thres channel clock cycles, the receive process is finished.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · thresh: RMT RX idle threshold
esp_err_t rmt_get_rx_idle_thresh(rmt_channel_t channel, uint16_t *thresh) Get RMT idle threshold value.
In receive mode, when no edge is detected on the input signal for longer than idle_thres channel clock cycles, the receive process is finished.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · thresh: pointer to accept RMT RX idle threshold value
esp_err_t rmt_set_mem_block_num(rmt_channel_t channel, uint8_t rmt_mem_num) Set RMT memory block number for RMT channel.
This function is used to configure the amount of memory blocks allocated to channel n
The 8 channels share a 512x32-bit RAM block which can be read and written by the processor cores over the APB bus, as well as read by the transmitters and written by the receivers.
The RAM address range for channel n is start_addr_CHn to end_addr_CHn, which are defined by:
Memory block start address is RMT_CHANNEL_MEM(n) (in soc/rmt_reg.h), that is, start_addr_chn = RMT base address + 0x800 + 64  4  n, and end_addr_chn = RMT base address + 0x800 + 64  4  n + 64  4  RMT_MEM_ SIZE_CHn mod 512  4
@note If memory block number of one channel is set to a value greater than 1, this channel will occupy the memory block of the next channel. Channel 0 can use at most 8 blocks of memory, accordingly channel 7 can only use one memory block.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · rmt_mem_num: RMT RX memory block number, one block has 64 * 32 bits.
esp_err_t rmt_get_mem_block_num(rmt_channel_t channel, uint8_t *rmt_mem_num) Get RMT memory block number.
Return · ESP_ERR_INVALID_ARG Parameter error

Espressif Systems

655

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_OK Success Parameters
· channel: RMT channel · rmt_mem_num: Pointer to accept RMT RX memory block number
esp_err_t rmt_set_tx_carrier(rmt_channel_t channel, bool carrier_en, uint16_t high_level, uint16_t low_level, rmt_carrier_level_t carrier_level)
Configure RMT carrier for TX signal.
Set different values for carrier_high and carrier_low to set different frequency of carrier.
The unit of carrier_high/low is the source clock tick, not the divided channel counter clock.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · carrier_en: Whether to enable output carrier. · high_level: High level duration of carrier · low_level: Low level duration of carrier. · carrier_level: Configure the way carrier wave is modulated for channel. ­ 1nb1:transmit on low output level ­ 1nb0:transmit on high output level
esp_err_t rmt_set_mem_pd(rmt_channel_t channel, bool pd_en) Set RMT memory in low power mode.
Reduce power consumed by memory. 1:memory is in low power state.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · pd_en: RMT memory low power enable.
esp_err_t rmt_get_mem_pd(rmt_channel_t channel, bool *pd_en) Get RMT memory low power mode.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · pd_en: Pointer to accept RMT memory low power mode.
esp_err_t rmt_tx_start(rmt_channel_t channel, bool tx_idx_rst) Set RMT start sending data from memory.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · tx_idx_rst: Set true to reset memory index for TX. Otherwise, transmitter will continue sending from the last index in memory.
esp_err_t rmt_tx_stop(rmt_channel_t channel) Set RMT stop sending.
Return

Espressif Systems

656

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success Parameters · channel: RMT channel
esp_err_t rmt_rx_start(rmt_channel_t channel, bool rx_idx_rst) Set RMT start receiving data.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · rx_idx_rst: Set true to reset memory index for receiver. Otherwise, receiver will continue receiving data to the last index in memory.
esp_err_t rmt_rx_stop(rmt_channel_t channel) Set RMT stop receiving data.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel
esp_err_t rmt_tx_memory_reset(rmt_channel_t channel) Reset RMT TX memory.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel
esp_err_t rmt_rx_memory_reset(rmt_channel_t channel) Reset RMT RX memory.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel
esp_err_t rmt_set_memory_owner(rmt_channel_t channel, rmt_mem_owner_t owner) Set RMT memory owner.
Note Setting memroy is only valid for RX channel. Return
· ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success Parameters · channel: RMT channel · owner: To set when the transmitter or receiver can process the memory of channel.
esp_err_t rmt_get_memory_owner(rmt_channel_t channel, rmt_mem_owner_t *owner) Get RMT memory owner.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · owner: Pointer to get memory owner.

Espressif Systems

657

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t rmt_set_tx_loop_mode(rmt_channel_t channel, bool loop_en) Set RMT tx loop mode.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · loop_en: Enable RMT transmitter loop sending mode. If set true, transmitter will continue sending from the first data to the last data in channel over and over again in a loop.
esp_err_t rmt_get_tx_loop_mode(rmt_channel_t channel, bool *loop_en) Get RMT tx loop mode.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · loop_en: Pointer to accept RMT transmitter loop sending mode.
esp_err_t rmt_set_rx_filter(rmt_channel_t channel, bool rx_filter_en, uint8_t thresh) Set RMT RX filter.
In receive mode, channel will ignore input pulse when the pulse width is smaller than threshold.
Counted in source clock, not divided counter clock.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · rx_filter_en: To enable RMT receiver filter. · thresh: Threshold of pulse width for receiver.
esp_err_t rmt_set_source_clk(rmt_channel_t channel, rmt_source_clk_t base_clk) Set RMT source clock.
RMT module has two clock sources: 1. APB clock which is 80Mhz 2. REF tick clock, which would be 1Mhz (not supported in this version).
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · base_clk: To choose source clock for RMT module.
esp_err_t rmt_get_source_clk(rmt_channel_t channel, rmt_source_clk_t *src_clk) Get RMT source clock.
RMT module has two clock sources: 1. APB clock which is 80Mhz 2. REF tick clock, which would be 1Mhz (not supported in this version).
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel

Espressif Systems

658

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· src_clk: Pointer to accept source clock for RMT module.
esp_err_t rmt_set_idle_level(rmt_channel_t channel, bool idle_out_en, rmt_idle_level_t level) Set RMT idle output level for transmitter.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · idle_out_en: To enable idle level output. · level: To set the output signalns level for channel in idle state.
esp_err_t rmt_get_idle_level(rmt_channel_t channel, bool *idle_out_en, rmt_idle_level_t *level) Get RMT idle output level for transmitter.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · idle_out_en: Pointer to accept value of enable idle. · level: Pointer to accept value of output signalns level in idle state for specified channel.
esp_err_t rmt_get_status(rmt_channel_t channel, uint32_t *status) Get RMT status.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · status: Pointer to accept channel status. Please refer to RMT_CHnSTATUS_REG(n=0~7) in rmt_reg.h for more details of each field.
esp_err_t rmt_set_rx_intr_en(rmt_channel_t channel, bool en) Set RMT RX interrupt enable.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · en: enable or disable RX interrupt.
esp_err_t rmt_set_err_intr_en(rmt_channel_t channel, bool en) Set RMT RX error interrupt enable.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · en: enable or disable RX err interrupt.
esp_err_t rmt_set_tx_intr_en(rmt_channel_t channel, bool en) Set RMT TX interrupt enable.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · en: enable or disable TX interrupt.

Espressif Systems

659

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t rmt_set_tx_thr_intr_en(rmt_channel_t channel, bool en, uint16_t evt_thresh) Set RMT TX threshold event interrupt enable.
An interrupt will be triggered when the number of transmitted items reaches the threshold value
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · en: enable or disable TX event interrupt. · evt_thresh: RMT event interrupt threshold value
esp_err_t rmt_set_gpio(rmt_channel_t channel, rmt_mode_t mode, gpio_num_t gpio_num, bool invert_signal)
Configure the GPIO used by RMT channel.
Return · ESP_ERR_INVALID_ARG Configure RMT GPIO failed because of wrong parameter · ESP_OK Configure RMT GPIO successfully
Parameters · channel: RMT channel · mode: RMT mode, either RMT_MODE_TX or RMT_MODE_RX · gpio_num: GPIO number, which is connected with certain RMT signal · invert_signal: Invert RMT signal physically by GPIO matrix
esp_err_t rmt_config(const rmt_config_t *rmt_param) Configure RMT parameters.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · rmt_param: RMT parameter struct
esp_err_t rmt_isr_register(void (*fn))void * , void *arg, int intr_alloc_flags, rmt_isr_handle_t *handleRegister RMT interrupt handler, the handler is an ISR.
The handler will be attached to the same CPU core that this function is running on.
Note If you already called rmt_driver_install to use system RMT driver, please do not register ISR handler again.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Function pointer error. · ESP_FAIL System driver installed, can not register ISR handler for RMT
Parameters · fn: Interrupt handler function. · arg: Parameter for the handler function · intr_alloc_flags: Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info. · handle: If non-zero, a handle to later clean up the ISR gets stored here.
esp_err_t rmt_isr_deregister(rmt_isr_handle_t handle) Deregister previously registered RMT interrupt handler.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Handle invalid
Parameters · handle: Handle obtained from rmt_isr_register

Espressif Systems

660

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
esp_err_t rmt_fill_tx_items(rmt_channel_t channel, const rmt_item32_t *item, uint16_t item_num, uint16_t mem_offset)
Fill memory data of channel with given RMT items.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · item: Pointer of items. · item_num: RMT sending items number. · mem_offset: Index offset of memory.
esp_err_t rmt_driver_install(rmt_channel_t channel, size_t rx_buf_size, int intr_alloc_flags) Initialize RMT driver.
Return · ESP_ERR_INVALID_STATE Driver is already installed, call rmt_driver_uninstall first. · ESP_ERR_NO_MEM Memory allocation failure · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · rx_buf_size: Size of RMT RX ringbuffer. Can be 0 if the RX ringbuffer is not used. · intr_alloc_flags: Flags for the RMT driver interrupt handler. Pass 0 for default flags. See esp_intr_alloc.h for details. If ESP_INTR_FLAG_IRAM is used, please do not use the memory allocated from psram when calling rmt_write_items.
esp_err_t rmt_driver_uninstall(rmt_channel_t channel) Uninstall RMT driver.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel
esp_err_t rmt_get_channel_status(rmt_channel_status_result_t *channel_status) Get the current status of eight channels.
Note Do not call this function if it is possible that rmt_driver_uninstall will be called at the same time.
Return · ESP_ERR_INVALID_ARG Parameter is NULL · ESP_OK Success
Parameters · [out] channel_status: store the current status of each channel
esp_err_t rmt_get_counter_clock(rmt_channel_t channel, uint32_t *clock_hz) Get speed of channelns internal counter clock.
Return · ESP_ERR_INVALID_ARG Parameter is NULL · ESP_OK Success
Parameters · channel: RMT channel · [out] clock_hz: counter clock speed, in hz
esp_err_t rmt_write_items(rmt_channel_t channel, const rmt_item32_t *rmt_item, int item_num, bool wait_tx_done)
RMT send waveform from rmt_item array.
This API allows user to send waveform with any length.

Espressif Systems

661

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Note This function will not copy data, instead, it will point to the original items, and send the waveform items. If wait_tx_done is set to true, this function will block and will not return until all items have been sent out. If wait_tx_done is set to false, this function will return immediately, and the driver interrupt will continue sending the items. We must make sure the item data will not be damaged when the driver is still sending items in driver interrupt.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · rmt_item: head point of RMT items array. If ESP_INTR_FLAG_IRAM is used, please do not use the memory allocated from psram when calling rmt_write_items. · item_num: RMT data item number. · wait_tx_done: ­ If set 1, it will block the task and wait for sending done. ­ If set 0, it will not wait and return immediately.
esp_err_t rmt_wait_tx_done(rmt_channel_t channel, TickType_t wait_time) Wait RMT TX finished.
Return · ESP_OK RMT Tx done successfully · ESP_ERR_TIMEOUT Exceeded the mwait_timengiven · ESP_ERR_INVALID_ARG Parameter error · ESP_FAIL Driver not installed
Parameters · channel: RMT channel · wait_time: Maximum time in ticks to wait for transmission to be complete. If set 0, return immediately with ESP_ERR_TIMEOUT if TX is busy (polling).
esp_err_t rmt_get_ringbuf_handle(rmt_channel_t channel, RingbufHandle_t *buf_handle) Get ringbuffer from RMT.
Users can get the RMT RX ringbuffer handle, and process the RX data.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · buf_handle: Pointer to buffer handle to accept RX ringbuffer handle.
esp_err_t rmt_translator_init(rmt_channel_t channel, sample_to_rmt_t fn) Init rmt translator and register user callback. The callback will convert the raw data that needs to be sent to rmt format. If a channel is initialized more than once, tha user callback will be replaced by the later.
Return · ESP_FAIL Init fail. · ESP_OK Init success.
Parameters · channel: RMT channel . · fn: Point to the data conversion function.
esp_err_t rmt_translator_set_context(rmt_channel_t channel, void *context) Set user context for the translator of specific channel.
Return · ESP_FAIL Set context fail · ESP_OK Set context success
Parameters · channel: RMT channel number · context: User context

Espressif Systems

662

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t rmt_translator_get_context(const size_t *item_num, void **context) Get the user context set by mrmt_translator_set_contextn.
Note This API must be invoked in the RMT translator callback function, and the first argument must be the actual parameter mitem_numnyou got in that callback function.
Return · ESP_FAIL Get context fail · ESP_OK Get context success
Parameters · item_num: Address of the memory which contains the number of translated items (Itns from driverns internal memroy) · context: Returned User context
esp_err_t rmt_write_sample(rmt_channel_t channel, const uint8_t *src, size_t src_size, bool wait_tx_done)
Translate uint8_t type of data into rmt format and send it out. Requires rmt_translator_init to init the translator first.
Return · ESP_FAIL Send fail · ESP_OK Send success
Parameters · channel: RMT channel . · src: Pointer to the raw data. · src_size: The size of the raw data. · wait_tx_done: Set true to wait all data send done.
rmt_tx_end_callback_t rmt_register_tx_end_callback(rmt_tx_end_fn_t function, void *arg) Registers a callback that will be called when transmission ends.
Called by rmt_driver_isr_default in interrupt context.
Note Requires rmt_driver_install to install the default ISR handler. Return the previous callback settings (members will be set to NULL if there was none) Parameters
· function: Function to be called from the default interrupt handler or NULL. · arg: Argument which will be provided to the callback when it is called.
esp_err_t rmt_set_rx_thr_intr_en(rmt_channel_t channel, bool en, uint16_t evt_thresh) Set RMT RX threshold event interrupt enable.
An interrupt will be triggered when the number of received items reaches the threshold value
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · en: enable or disable RX event interrupt. · evt_thresh: RMT event interrupt threshold value
esp_err_t rmt_add_channel_to_group(rmt_channel_t channel) Add channel into a synchronous group (channels in the same group can start transaction simultaneously)
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel
esp_err_t rmt_remove_channel_from_group(rmt_channel_t channel) Remove channel out of a group.
Return

Espressif Systems

663

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success Parameters · channel: RMT channel
esp_err_t rmt_set_tx_loop_count(rmt_channel_t channel, uint32_t count) Set loop count threshold value for RMT TX channel.
When tx loop count reaches this value, an ISR callback will notify user
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · count: loop count, 1 ~ 1023
esp_err_t rmt_enable_tx_loop_autostop(rmt_channel_t channel, bool en) Enable or disable the feature that when loop count reaches the threshold, RMT will stop transmitting.
· When the loop auto-stop feature is enabled will halt RMT transmission after the loop count reaches a certain threshold
· When disabled, the RMT transmission continue indefinitely until halted by the users
Note The auto-stop feature is implemented in hardware on particular targets (i.e. those with SOC_RMT_SUPPORT_TX_LOOP_AUTOSTOP defined). Otherwise, the auto-stop feature is implemented in software via the interrupt.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · en: enable bit
esp_err_t rmt_memory_rw_rst(rmt_channel_t channel) Reset RMT TX/RX memory index.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel
void rmt_set_intr_enable_mask(uint32_t mask) Set mask value to RMT interrupt enable register.
Parameters · mask: Bit mask to set to the register
void rmt_clr_intr_enable_mask(uint32_t mask) Clear mask value to RMT interrupt enable register.
Parameters · mask: Bit mask to clear the register
esp_err_t rmt_set_pin(rmt_channel_t channel, rmt_mode_t mode, gpio_num_t gpio_num) Set RMT pin.
Return · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success
Parameters · channel: RMT channel · mode: TX or RX mode for RMT · gpio_num: GPIO number to transmit or receive the signal.

Espressif Systems

664

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Structures struct rmt_item32_t
Definition of RMT item.
Public Members
uint32_t duration0 : 15 Duration of level0
uint32_t level0 : 1 Level of the first part
uint32_t duration1 : 15 Duration of level1
uint32_t level1 : 1 Level of the second part
uint32_t val Equivelent unsigned value for the RMT item
struct rmt_tx_config_t Data struct of RMT TX configure parameters.
Public Members
uint32_t carrier_freq_hz RMT carrier frequency
rmt_carrier_level_t carrier_level Level of the RMT output, when the carrier is applied
rmt_idle_level_t idle_level RMT idle level
uint8_t carrier_duty_percent RMT carrier duty (%)
uint32_t loop_count Maximum loop count
bool carrier_en RMT carrier enable
bool loop_en Enable sending RMT items in a loop
bool idle_output_en RMT idle level output enable
struct rmt_rx_config_t Data struct of RMT RX configure parameters.
Public Members
uint16_t idle_threshold RMT RX idle threshold
uint8_t filter_ticks_thresh RMT filter tick number
bool filter_en RMT receiver filter enable

Espressif Systems

665

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

bool rm_carrier RMT receiver remove carrier enable
uint32_t carrier_freq_hz RMT carrier frequency
uint8_t carrier_duty_percent RMT carrier duty (%)
rmt_carrier_level_t carrier_level The level to remove the carrier
struct rmt_config_t Data struct of RMT configure parameters.
Public Members
rmt_mode_t rmt_mode RMT mode: transmitter or receiver
rmt_channel_t channel RMT channel
gpio_num_t gpio_num RMT GPIO number
uint8_t clk_div RMT channel counter divider
uint8_t mem_block_num RMT memory block number
uint32_t flags RMT channel extra configurations, ORnd with RMT_CHANNEL_FLAGS_[*]
rmt_tx_config_t tx_config RMT TX parameter
rmt_rx_config_t rx_config RMT RX parameter
struct rmt_tx_end_callback_t Structure encapsulating a RMT TX end callback.
Public Members
rmt_tx_end_fn_t function Function which is called on RMT TX end
void *arg Optional argument passed to function
Macros RMT_CHANNEL_FLAGS_AWARE_DFS
Channel can work during APB clock scaling RMT_CHANNEL_FLAGS_INVERT_SIG
Invert RMT signal
RMT_MEM_ITEM_NUM Define memory space of each RMT channel (in words = 4 bytes)
RMT_DEFAULT_CONFIG_TX(gpio, channel_id) Default configuration for Tx channel.

Espressif Systems

666

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
RMT_DEFAULT_CONFIG_RX(gpio, channel_id) Default configuration for RX channel.
Type Definitions typedef intr_handle_t rmt_isr_handle_t
RMT interrupt handle. typedef void (*rmt_tx_end_fn_t)(rmt_channel_t channel, void *arg)
Type of RMT Tx End callback function. typedef void (*sample_to_rmt_t)(const void *src, rmt_item32_t *dest, size_t src_size, size_t
wanted_num, size_t *translated_size, size_t *item_num) User callback function to convert uint8_t type data to rmt format(rmt_item32_t).
This function may be called from an ISR, so, the code should be short and efficient.
Note In fact, item_num should be a multiple of translated_size, e.g. : When we convert each byte of uint8_t type data to rmt format data, the relation between item_num and translated_size should be item_num = translated_size*8.
Parameters · src: Pointer to the buffer storing the raw data that needs to be converted to rmt format. · [out] dest: Pointer to the buffer storing the rmt format data. · src_size: The raw data size. · wanted_num: The number of rmt format data that wanted to get. · [out] translated_size: The size of the raw data that has been converted to rmt format, it should return 0 if no data is converted in user callback. · [out] item_num: The number of the rmt format data that actually converted to, it can be less than wanted_num if there is not enough raw data, but cannot exceed wanted_num. it should return 0 if no data was converted.
Header File · components/hal/include/hal/rmt_types.h
Structures struct rmt_channel_status_result_t
Data struct of RMT channel status.
Public Members
rmt_channel_status_t status[RMT_CHANNEL_MAX] Store the current status of each channel
Enumerations enum rmt_channel_t
RMT channel ID. Values: RMT_CHANNEL_0
RMT channel number 0 RMT_CHANNEL_1
RMT channel number 1 RMT_CHANNEL_2
RMT channel number 2

Espressif Systems

667

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
RMT_CHANNEL_3 RMT channel number 3
RMT_CHANNEL_4 RMT channel number 4
RMT_CHANNEL_5 RMT channel number 5
RMT_CHANNEL_6 RMT channel number 6
RMT_CHANNEL_7 RMT channel number 7
RMT_CHANNEL_MAX Number of RMT channels
enum rmt_mem_owner_t RMT Internal Memory Owner.
Values:
RMT_MEM_OWNER_TX RMT RX mode, RMT transmitter owns the memory block
RMT_MEM_OWNER_RX RMT RX mode, RMT receiver owns the memory block
RMT_MEM_OWNER_MAX
enum rmt_source_clk_t Clock Source of RMT Channel.
Values:
RMT_BASECLK_APB = 1 RMT source clock is APB CLK, 80Mhz by default
RMT_BASECLK_XTAL = 3 RMT source clock is XTAL clock, 40Mhz by default
RMT_BASECLK_MAX
enum rmt_data_mode_t RMT Data Mode.
Note We highly recommended to use MEM mode not FIFO mode since there will be some gotcha in FIFO mode.
Values:
RMT_DATA_MODE_FIFO
RMT_DATA_MODE_MEM
RMT_DATA_MODE_MAX
enum rmt_mode_t RMT Channel Working Mode (TX or RX)
Values:
RMT_MODE_TX RMT TX mode
RMT_MODE_RX RMT RX mode
RMT_MODE_MAX

Espressif Systems

668

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

enum rmt_idle_level_t RMT Idle Level.
Values:
RMT_IDLE_LEVEL_LOW RMT TX idle level: low Level
RMT_IDLE_LEVEL_HIGH RMT TX idle level: high Level
RMT_IDLE_LEVEL_MAX
enum rmt_carrier_level_t RMT Carrier Level.
Values:
RMT_CARRIER_LEVEL_LOW RMT carrier wave is modulated for low Level output
RMT_CARRIER_LEVEL_HIGH RMT carrier wave is modulated for high Level output
RMT_CARRIER_LEVEL_MAX
enum rmt_channel_status_t RMT Channel Status.
Values:
RMT_CHANNEL_UNINIT RMT channel uninitialized
RMT_CHANNEL_IDLE RMT channel status idle
RMT_CHANNEL_BUSY RMT channel status busy

2.3.14 SD Pull-up Requirements
Espressif hardware products are designed for multiple use cases which may require different pull states on pins. For this reason, the pull state of particular pins on certain products will need to be adjusted to provide the pull-ups required in the SD bus.
SD pull-up requirements apply to cases where ESP32-S3 uses the SPI or SDMMC controller to communicate with SD cards. When an SD card is operating in SPI mode or 1-bit SD mode, the CMD and DATA (DAT0 - DAT3) lines of the SD bus must be pulled up by 10 kOhm resistors. SD cards and SDIO devices should also have pull-ups on all above-mentioned lines (regardless of whether these lines are connected to the host) in order to prevent them from entering a wrong state.
This document has the following structure:
· Overview of compatibility between the default pull states on pins of Espressifns products and the states required by the SD bus
· Solutions - ideas on how to resolve compatibility issues · Related information - other relevant information

Overview of Compatibility
This section provides an overview of compatibility issues that might occur when using SDIO (secure digital input output). Since the SD bus needs to be connected to pull-ups, these issues should be resolved regardless of whether they are related to master (host) or slave (device). Each issue has links to its respective solution. A solution for a host and device may differ.

Espressif Systems

669

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Systems on a Chip (SoCs) ESP32-S3 SDMMC host controller allows using any of GPIOs for any of SD interface signals. However, it is recommended to avoid using strapping GPIOs, GPIOs with internal weak pull-downs and GPIOs commonly used for other purposes to prevent conflicts:
· GPIO0 (strapping pin) · GPIO45, GPIO46 (strapping pins, internal weak pulldown) · GPIO26 - GPIO32 (commonly used for SPI Flash and PSRAM) · GPIO33 - GPIO37 (when using chips and modules with Octal SPI Flash or Octal PSRAM) · GPIO43, GPIO44 (GPIOs used for UART0 by default) · GPIO19, GPIO20 (GPIOs used for USB by default)
Systems in Packages (SIP)
Modules
Development Boards · ESP32-S3-DevKitC-1 ­ No Pull-ups · ESP32-S3-USB-OTG ­ The board may be used in 1-line and 4-line SD mode or SPI mode. ­ Required pull-ups are provided on GPIOs 33-38. · ESP32-S3-EYE ­ The board is limited to 1-line SD mode. ­ Required pull-ups are provided on GPIOs 38-40.
Solutions
No Pull-ups If you use a development board without pull-ups, you can do the following: · If your host and slave device are on separate boards, replace one of them with a board that has pull-ups. For the list of Espressifns development boards with pull-ups, go to Development Boards. · Attach external pull-ups by connecting each pin which requires a pull-up to VDD via a 10 kOhm resistor.
Related Information
2.3.15 SDMMC Host Driver
Overview
ESP32-S3ns SDMMC host peripheral has two slots. Each slot can be used independently to connect to an SD card, SDIO device or eMMC chip. Both slots (SDMMC_HOST_SLOT_0, SDMMC_HOST_SLOT_1) support 1-, 4- and 8-line SD interface. The slots are connected to ESP32-S3 GPIOs using GPIO matrix. This means that any GPIO may be used for each of the SD card signals.
Supported Speed Modes
SDMMC Host driver supports the following speed modes: · Default Speed (20 MHz), 1/4-line (with SD cards), and 1/4/8-line (with 3.3 V eMMC) · High Speed (40 MHz), 1/4-line (with SD cards), and 1/4/8-line (with 3.3 V eMMC) · High Speed DDR (40 MHz), 4-line (with 3.3 V eMMC)
Speed modes not supported at present:

Espressif Systems

670

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· High Speed DDR mode, 8-line eMMC · UHS-I 1.8 V modes, 4-line SD cards
Using the SDMMC Host Driver
Of all the functions listed below, only the following ones will be used directly by most applications: · sdmmc_host_init() · sdmmc_host_init_slot() · sdmmc_host_deinit()
Other functions, such as the ones given below, will be called by the SD/MMC protocol layer via function pointers in the sdmmc_host_t structure:
· sdmmc_host_set_bus_width() · sdmmc_host_set_card_clk() · sdmmc_host_do_transaction()
Configuring Bus Width and Frequency
With the default initializers for sdmmc_host_t and sdmmc_slot_config_t (SDMMC_HOST_DEFAULT and SDMMC_SLOT_CONFIG_DEFAULT), SDMMC Host driver will attempt to use the widest bus supported by the card (4 lines for SD, 8 lines for eMMC) and the frequency of 20 MHz. In the designs where communication at 40 MHz frequency can be achieved, it is possible to increase the bus frequency by changing the max_freq_khz field of sdmmc_host_t:
sdmmc_host_t host = SDMMC_HOST_DEFAULT(); host.max_freq_khz = SDMMC_FREQ_HIGHSPEED;
To configure the bus width, set the width field of sdmmc_slot_config_t. For example, to set 1-line mode:
sdmmc_slot_config_t slot = SDMMC_SLOT_CONFIG_DEFAULT(); slot.width = 1;
Configuring GPIOs
ESP32-S3 SDMMC Host can be configured to use arbitrary GPIOs for each of the signals. Configuration is performed by setting members of sdmmc_slot_config_t structure. For example, to use GPIOs 1-6 for CLK, CMD, D0 - D3 signals, respectively:
sdmmc_slot_config_t slot = SDMMC_SLOT_CONFIG_DEFAULT(); slot.clk = GPIO_NUM_1; slot.cmd = GPIO_NUM_2; slot.d0 = GPIO_NUM_3; slot.d1 = GPIO_NUM_4; slot.d2 = GPIO_NUM_5; slot.d3 = GPIO_NUM_6;
It is also possible to configure Card Detect and Write Protect pins. Similar to other signals, set cd and wp members of the same structure:
slot.cd = GPIO_NUM_7; slot.wp = GPIO_NUM_8;
SDMMC_SLOT_CONFIG_DEFAULT sets both to GPIO_NUM_NC, meaning that by default the signals are not used. Once sdmmc_slot_config_t structure is initialized this way, you can use it when calling sdmmc_host_init_slot() or one of the higher level functions, such as esp_vfs_fat_sdmmc_mount().

Espressif Systems

671

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

DDR Mode for eMMC chips
By default, DDR mode will be used if:
· SDMMC host frequency is set to SDMMC_FREQ_HIGHSPEED in sdmmc_host_t structure, and · eMMC chip reports DDR mode support in its CSD register
DDR mode places higher requirements for signal integrity. To disable DDR mode while keeping SDMMC_FREQ_HIGHSPEED frequency, clear SDMMC_HOST_FLAG_DDR bit in flags field of sdmmc_host_t:
sdmmc_host_t host = SDMMC_HOST_DEFAULT(); host.max_freq_khz = SDMMC_FREQ_HIGHSPEED; host.flags &= ~SDMMC_HOST_FLAG_DDR;

See also
See SD/SDIO/MMC Driver for the higher level driver which implements the protocol layer.
See SD SPI Host Driver for a similar driver which uses the SPI controller and is limited to SD protocolns SPI mode.
See SD Pull-up Requirements for pullup support and compatibilities of modules and development kits.
API Reference
Header File
· components/driver/include/driver/sdmmc_host.h
Functions esp_err_t sdmmc_host_init(void)
Initialize SDMMC host peripheral.
Note This function is not thread safe Return
· ESP_OK on success · ESP_ERR_INVALID_STATE if sdmmc_host_init was already called · ESP_ERR_NO_MEM if memory can not be allocated esp_err_t sdmmc_host_init_slot(int slot, const sdmmc_slot_config_t *slot_config) Initialize given slot of SDMMC peripheral.
On the ESP32, SDMMC peripheral has two slots:
· Slot 0: 8-bit wide, maps to HS1_* signals in PIN MUX · Slot 1: 4-bit wide, maps to HS2_* signals in PIN MUX
Card detect and write protect signals can be routed to arbitrary GPIOs using GPIO matrix.
Note This function is not thread safe Return
· ESP_OK on success · ESP_ERR_INVALID_STATE if host has not been initialized using sdmmc_host_init Parameters · slot: slot number (SDMMC_HOST_SLOT_0 or SDMMC_HOST_SLOT_1) · slot_config: additional configuration for the slot
esp_err_t sdmmc_host_set_bus_width(int slot, size_t width) Select bus width to be used for data transfer.
SD/MMC card must be initialized prior to this command, and a command to set bus width has to be sent to the card (e.g. SD_APP_SET_BUS_WIDTH)
Note This function is not thread safe

Espressif Systems

672

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return · ESP_OK on success · ESP_ERR_INVALID_ARG if slot number or width is not valid
Parameters · slot: slot number (SDMMC_HOST_SLOT_0 or SDMMC_HOST_SLOT_1) · width: bus width (1, 4, or 8 for slot 0; 1 or 4 for slot 1)
size_t sdmmc_host_get_slot_width(int slot) Get bus width configured in sdmmc_host_init_slot to be used for data transfer.
Return configured bus width of the specified slot. Parameters
· slot: slot number (SDMMC_HOST_SLOT_0 or SDMMC_HOST_SLOT_1)
esp_err_t sdmmc_host_set_card_clk(int slot, uint32_t freq_khz) Set card clock frequency.
Currently only integer fractions of 40MHz clock can be used. For High Speed cards, 40MHz can be used. For Default Speed cards, 20MHz can be used.
Note This function is not thread safe Return
· ESP_OK on success · other error codes may be returned in the future Parameters · slot: slot number (SDMMC_HOST_SLOT_0 or SDMMC_HOST_SLOT_1) · freq_khz: card clock frequency, in kHz
esp_err_t sdmmc_host_set_bus_ddr_mode(int slot, bool ddr_enabled) Enable or disable DDR mode of SD interface.
Return · ESP_OK on success · ESP_ERR_NOT_SUPPORTED if DDR mode is not supported on this slot
Parameters · slot: slot number (SDMMC_HOST_SLOT_0 or SDMMC_HOST_SLOT_1) · ddr_enabled: enable or disable DDR mode
esp_err_t sdmmc_host_do_transaction(int slot, sdmmc_command_t *cmdinfo) Send command to the card and get response.
This function returns when command is sent and response is received, or data is transferred, or timeout occurs.
Note This function is not thread safe w.r.t. init/deinit functions, and bus width/clock speed configuration functions. Multiple tasks can call sdmmc_host_do_transaction as long as other sdmmc_host_* functions are not called.
Attention Data buffer passed in cmdinfo->data must be in DMA capable memory Return
· ESP_OK on success · ESP_ERR_TIMEOUT if response or data transfer has timed out · ESP_ERR_INVALID_CRC if response or data transfer CRC check has failed · ESP_ERR_INVALID_RESPONSE if the card has sent an invalid response · ESP_ERR_INVALID_SIZE if the size of data transfer is not valid in SD protocol · ESP_ERR_INVALID_ARG if the data buffer is not in DMA capable memory Parameters · slot: slot number (SDMMC_HOST_SLOT_0 or SDMMC_HOST_SLOT_1) · cmdinfo: pointer to structure describing command and data to transfer
esp_err_t sdmmc_host_io_int_enable(int slot) Enable IO interrupts.
This function configures the host to accept SDIO interrupts.
Return returns ESP_OK, other errors possible in the future Parameters

Espressif Systems

673

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· slot: slot number (SDMMC_HOST_SLOT_0 or SDMMC_HOST_SLOT_1)
esp_err_t sdmmc_host_io_int_wait(int slot, TickType_t timeout_ticks) Block until an SDIO interrupt is received, or timeout occurs.
Return · ESP_OK on success (interrupt received) · ESP_ERR_TIMEOUT if the interrupt did not occur within timeout_ticks
Parameters · slot: slot number (SDMMC_HOST_SLOT_0 or SDMMC_HOST_SLOT_1) · timeout_ticks: number of RTOS ticks to wait for the interrupt
esp_err_t sdmmc_host_deinit(void) Disable SDMMC host and release allocated resources.
Note This function is not thread safe Return
· ESP_OK on success · ESP_ERR_INVALID_STATE if sdmmc_host_init function has not been called
esp_err_t sdmmc_host_pullup_en(int slot, int width) Enable the pull-ups of sd pins.
This function is deprecated. Please set SDMMC_SLOT_FLAG_INTERNAL_PULLUP flag in sdmmc_slot_config_t::flags instead.
Note You should always place actual pullups on the lines instead of using this function. Internal pullup resistance are high and not sufficient, may cause instability in products. This is for debug or examples only.
Return · ESP_OK: if success · ESP_ERR_INVALID_ARG: if configured width larger than maximum the slot can support
Parameters · slot: Slot to use, normally set it to 1. · width: Bit width of your configuration, 1 or 4.
Structures struct sdmmc_slot_config_t
Extra configuration for SDMMC peripheral slot
Public Members
gpio_num_t clk GPIO number of CLK signal.
gpio_num_t cmd GPIO number of CMD signal.
gpio_num_t d0 GPIO number of D0 signal.
gpio_num_t d1 GPIO number of D1 signal.
gpio_num_t d2 GPIO number of D2 signal.
gpio_num_t d3 GPIO number of D3 signal.
gpio_num_t d4 GPIO number of D4 signal. Ignored in 1- or 4- line mode.

Espressif Systems

674

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
gpio_num_t d5 GPIO number of D5 signal. Ignored in 1- or 4- line mode.
gpio_num_t d6 GPIO number of D6 signal. Ignored in 1- or 4- line mode.
gpio_num_t d7 GPIO number of D7 signal. Ignored in 1- or 4- line mode.
gpio_num_t gpio_cd GPIO number of card detect signal.
gpio_num_t cd GPIO number of card detect signal; shorter name.
gpio_num_t gpio_wp GPIO number of write protect signal.
gpio_num_t wp GPIO number of write protect signal; shorter name.
uint8_t width Bus width used by the slot (might be less than the max width supported)
uint32_t flags Features used by this slot.
Macros SDMMC_HOST_SLOT_0
SDMMC slot 0. SDMMC_HOST_SLOT_1
SDMMC slot 1.
SDMMC_HOST_DEFAULT() Default sdmmc_host_t structure initializer for SDMMC peripheral.
Uses SDMMC peripheral, with 4-bit mode enabled, and max frequency set to 20MHz
SDMMC_SLOT_FLAG_INTERNAL_PULLUP Enable internal pullups on enabled pins. The internal pullups are insufficient however, please make sure external pullups are connected on the bus. This is for debug / example purpose only.
SDMMC_SLOT_NO_CD indicates that card detect line is not used
SDMMC_SLOT_NO_WP indicates that write protect line is not used
SDMMC_SLOT_WIDTH_DEFAULT use the maximum possible width for the slot
SDMMC_SLOT_CONFIG_DEFAULT() Macro defining default configuration of SDMMC host slot
2.3.16 SD SPI Host Driver
Overview
The SD SPI host driver allows communicating with one or more SD cards by the SPI Master driver which makes use of the SPI host. Each card is accessed through an SD SPI device represented by an sdspi_dev_handle_t spi_handle returned when attaching the device to an SPI bus by calling sdspi_host_init_device. The bus should be already initialized before (by spi_bus_initialize).

Espressif Systems

675

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
With the help of SPI Master driver based on, the SPI bus can be shared among SD cards and other SPI devices. The SPI Master driver will handle exclusive access from different tasks. The SD SPI driver uses software-controlled CS signal.
How to Use
Firstly, use the macro SDSPI_DEVICE_CONFIG_DEFAULT to initialize a structure sdmmc_slot_config_t, which is used to initialize an SD SPI device. This macro will also fill in the default pin mappings, which is same as the pin mappings of SDMMC host driver. Modify the host and pins of the structure to desired value. Then call sdspi_host_init_device to initialize the SD SPI device and attach to its bus. Then use SDSPI_HOST_DEFAULT macro to initialize a sdmmc_host_t structure, which is used to store the state and configurations of upper layer (SD/SDIO/MMC driver). Modify the slot parameter of the structure to the SD SPI device spi_handle just returned from sdspi_host_init_device. Call sdmmc_card_init with the sdmmc_host_t to probe and initialize the SD card. Now you can use SD/SDIO/MMC driver functions to access your card!
Other Details
Only the following driverns API functions are normally used by most applications: · sdspi_host_init() · sdspi_host_init_device() · sdspi_host_remove_device() · sdspi_host_deinit()
Other functions are mostly used by the protocol level SD/SDIO/MMC driver via function pointers in the sdmmc_host_t structure. For more details, see the SD/SDIO/MMC Driver.
Note: SD over SPI does not support speeds above SDMMC_FREQ_DEFAULT due to the limitations of the SPI driver.

Warning: If you want to share the SPI bus among SD card and other SPI devices, there are some restrictions, see Sharing the SPI bus among SD card and other SPI devices.

Related Docs
Sharing the SPI bus among SD card and other SPI devices The SD card has a SPI mode, which allows it to be communicated to as a SPI device. But there are some restrictions that we need to pay attention to.

Pin loading of other devices When adding more devices onto the same bus, the overall pin loading increases. The loading consists of AC loading (pin capacitor) and DC loading (pull-ups).

AC loading SD cards, which are designed for high-speed communications, have small pin capacitors (AC loading) to work until 50MHz. However, the other attached devices will increase the pinns AC loading.
Heavy AC loading of a pin may prevent the pin from being toggled quickly. By using an oscilloscope, you will see the edges of the pin become smoother and not ideal any more (the gradient of the edge is smaller). The setup timing requirements of an SD card may be violoated when the card is connected to such bus. Even worse, the clock from the host may not be recognized by the SD card and other SPI devices on the same bus.
This issue may be more obvious if other attached devices are not designed to work at the same frequency as the SD card, because they may have larger pin capacitors.

Espressif Systems

676

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
To see if your pin AC loading is too heavy, you can try the following tests:
(Terminology: launch edge: at which clock edge the data start to toggle; latch edge: at which clock edge the data is supposed to be sampled by the receiver, for SD cad, itns the rising edge.)
1. Use an oscilloscope to see the clock and compare the data line to the clock. - If you see the clock is not fast enough (for example, the rising/falling edge is longer than 1/4 of the clock cycle), it means the clock is skewed too much. - If you see the data line unstable before the latch edge of the clock, it means the load of the data line is too large. You may also observed the corresponding phenomenon (data delayed largely from launching edge of clock) with logic analyzers. But itns not as obvious as with an oscilloscope.
2. Try to use slower clock frequency. If the lower frequency can work while the higher frequency cannt, itns an indication of the AC loading on the pins is too large.
If the AC loading of the pins is too large, you can either use other faster devices (with lower pin load) or slow down the clock speed.
DC loading The pull-ups required by SD cards are usually around 10 kOhm to 50 kOhm, which may be too strong for some other SPI devices.
Check the specification of your device about its DC output current , it should be larger than 700uA, otherwise the device output may not be read correctly.
Initialization sequence Note: If you see any problem in the following steps, please make sure the timing is correct first. You can try to slow down the clock speed (SDMMC_FREQ_PROBING = 400 KHz for SD card) to avoid the influence of pin AC loading (see above section).
When using ab SD card with other SPI devices on the same SPI bus, due to the restrictions of the SD card startup flow, the following initialization sequence should be followed: (See also storage/sd_card)
1. Initialize the SPI bus properly by spi_bus_initialize. 2. Tie the CS lines of all other devices than the SD card to high. This is to avoid conflicts to the SD card in the
following step. You can do this by either:
1. Attach devices to the SPI bus by calling spi_bus_add_device. This function will initialize the GPIO that is used as CS to the idle level: high.
2. Initialize GPIO on the CS pin that needs to be tied up before actually adding a new device. 3. Rely on the internal/external pull-up (not recommended) to pull-up all the CS pins when the GPIOs of
ESP are not initialized yet. You need to check carefull the pull-up is strong enough and there are no other pull-downs that will influence the pull-up (For example, internal pull-down should be enabled). 3. Mount the card to the filesystem by calling esp_vfs_fat_sdspi_mount. This step will put the SD card into the SPI mode, which SHOULD be done before all other SPI communications on the same bus. Otherwise the card will stay in the SD mode, in which mode it may randomly respond to any SPI communications on the bus, even when its CS line is not addressed. If you want to test this behavior, please also note that, once the card is put into SPI mode, it will not return to SD mode before next power cycle, i.e. powered down and powered up again. 4. Now you can talk to other SPI devices freely!
API Reference
Header File
· components/driver/include/driver/sdspi_host.h

Espressif Systems

677

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Functions esp_err_t sdspi_host_init(void)
Initialize SD SPI driver.
Note This function is not thread safe Return
· ESP_OK on success · other error codes may be returned in future versions esp_err_t sdspi_host_init_device(const sdspi_device_config_t *dev_config, sdspi_dev_handle_t
*out_handle) Attach and initialize an SD SPI device on the specific SPI bus.
Note This function is not thread safe Note Initialize the SPI bus by spi_bus_initialize() before calling this function. Note The SDIO over sdspi needs an extra interrupt line. Call gpio_install_isr_service() before
this function. Return
· ESP_OK on success · ESP_ERR_INVALID_ARG if sdspi_host_init_device has invalid arguments · ESP_ERR_NO_MEM if memory can not be allocated · other errors from the underlying spi_master and gpio drivers Parameters · dev_config: pointer to device configuration structure · out_handle: Output of the handle to the sdspi device.
esp_err_t sdspi_host_remove_device(sdspi_dev_handle_t handle) Remove an SD SPI device.
Return Always ESP_OK Parameters
· handle: Handle of the SD SPI device
esp_err_t sdspi_host_do_transaction(sdspi_dev_handle_t handle, sdmmc_command_t *cmdinfo) Send command to the card and get response.
This function returns when command is sent and response is received, or data is transferred, or timeout occurs.
Note This function is not thread safe w.r.t. init/deinit functions, and bus width/clock speed configuration functions. Multiple tasks can call sdspi_host_do_transaction as long as other sdspi_host_* functions are not called.
Return · ESP_OK on success · ESP_ERR_TIMEOUT if response or data transfer has timed out · ESP_ERR_INVALID_CRC if response or data transfer CRC check has failed · ESP_ERR_INVALID_RESPONSE if the card has sent an invalid response
Parameters · handle: Handle of the sdspi device · cmdinfo: pointer to structure describing command and data to transfer
esp_err_t sdspi_host_set_card_clk(sdspi_dev_handle_t host, uint32_t freq_khz) Set card clock frequency.
Currently only integer fractions of 40MHz clock can be used. For High Speed cards, 40MHz can be used. For Default Speed cards, 20MHz can be used.
Note This function is not thread safe Return
· ESP_OK on success · other error codes may be returned in the future Parameters · host: Handle of the sdspi device · freq_khz: card clock frequency, in kHz

Espressif Systems

678

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t sdspi_host_deinit(void) Release resources allocated using sdspi_host_init.
Note This function is not thread safe Return
· ESP_OK on success · ESP_ERR_INVALID_STATE if sdspi_host_init function has not been called
esp_err_t sdspi_host_io_int_enable(sdspi_dev_handle_t handle) Enable SDIO interrupt.
Return · ESP_OK on success
Parameters · handle: Handle of the sdspi device
esp_err_t sdspi_host_io_int_wait(sdspi_dev_handle_t handle, TickType_t timeout_ticks) Wait for SDIO interrupt until timeout.
Return · ESP_OK on success
Parameters · handle: Handle of the sdspi device · timeout_ticks: Ticks to wait before timeout.
esp_err_t sdspi_host_init_slot(int slot, const sdspi_slot_config_t *slot_config) Initialize SD SPI driver for the specific SPI controller.
Note This function is not thread safe Note The SDIO over sdspi needs an extra interrupt line. Call gpio_install_isr_service() before
this function. Parameters
· slot: SPI controller to use (SPI2_HOST or SPI3_HOST) · slot_config: pointer to slot configuration structure
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if sdspi_init_slot has invalid arguments · ESP_ERR_NO_MEM if memory can not be allocated · other errors from the underlying spi_master and gpio drivers

Structures struct sdspi_device_config_t
Extra configuration for SD SPI device.

Public Members
spi_host_device_t host_id SPI host to use, SPIx_HOST (see spi_types.h).
gpio_num_t gpio_cs GPIO number of CS signal.
gpio_num_t gpio_cd GPIO number of card detect signal.
gpio_num_t gpio_wp GPIO number of write protect signal.
gpio_num_t gpio_int GPIO number of interrupt line (input) for SDIO card.
struct sdspi_slot_config_t Extra configuration for SPI host.

Espressif Systems

679

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Public Members
gpio_num_t gpio_cs GPIO number of CS signal.
gpio_num_t gpio_cd GPIO number of card detect signal.
gpio_num_t gpio_wp GPIO number of write protect signal.
gpio_num_t gpio_int GPIO number of interrupt line (input) for SDIO card.
gpio_num_t gpio_miso GPIO number of MISO signal.
gpio_num_t gpio_mosi GPIO number of MOSI signal.
gpio_num_t gpio_sck GPIO number of SCK signal.
int dma_channel DMA channel to be used by SPI driver (1 or 2).
Macros SDSPI_DEFAULT_HOST SDSPI_HOST_DEFAULT()
Default sdmmc_host_t structure initializer for SD over SPI driver. Uses SPI mode and max frequency set to 20MHz mslotnshould be set to an sdspi device initialized by sdspi_host_init_device(). SDSPI_SLOT_NO_CD indicates that card detect line is not used SDSPI_SLOT_NO_WP indicates that write protect line is not used SDSPI_SLOT_NO_INT indicates that interrupt line is not used SDSPI_DEVICE_CONFIG_DEFAULT() Macro defining default configuration of SD SPI device. SDSPI_SLOT_CONFIG_DEFAULT() Macro defining default configuration of SPI host
Type Definitions typedef int sdspi_dev_handle_t
Handle representing an SD SPI device.
2.3.17 Sigma-delta Modulation
Introduction
ESP32-S3 has a second-order sigma-delta modulation module. This driver configures the channels of the sigma-delta module.

Espressif Systems

680

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Functionality Overview
There are 8 independent sigma-delta modulation channels identified with sigmadelta_channel_t. Each channel is capable to output the binary, hardware generated signal with the sigma-delta modulation. Selected channel should be set up by providing configuration parameters in sigmadelta_config_t and then applying this configuration with sigmadelta_config(). Another option is to call individual functions, that will configure all required parameters one by one:
· Prescaler of the sigma-delta generator - sigmadelta_set_prescale() · Duty of the output signal - sigmadelta_set_duty() · GPIO pin to output modulated signal - sigmadelta_set_pin() The range of the mdutyninput parameter of sigmadelta_set_duty() is from -128 to 127 (eight bit signed integer). If zero value is set, then the output signalns duty will be about 50%, see description of sigmadelta_set_duty().
Convert to analog signal (Optional)
Typically, if the sigma-delta signal is connected to an LED, you donnt have to add any filter between them (because our eyes are a low pass filter naturally). However, if you want to check the real voltage or watch the analog waveform, you need to design an analog low pass filter. Also, it is recommended to use an active filter instead of a passive filter to gain better isolation and not lose too much voltage. For example, you can take the following Sallen-Key topology Low Pass Filter as a reference.

Fig. 15: Sallen-Key Low Pass Filter
Application Example Sigma-delta Modulation example: peripherals/sigmadelta.

Espressif Systems

681

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
API Reference
Header File
· components/driver/include/driver/sigmadelta.h
Functions esp_err_t sigmadelta_config(const sigmadelta_config_t *config)
Configure Sigma-delta channel.
Return · ESP_OK Success · ESP_ERR_INVALID_STATE sigmadelta driver already initialized · ESP_ERR_INVALID_ARG Parameter error
Parameters · config: Pointer of Sigma-delta channel configuration struct
esp_err_t sigmadelta_set_duty(sigmadelta_channel_t channel, int8_t duty) Set Sigma-delta channel duty.
This function is used to set Sigma-delta channel duty, If you add a capacitor between the output pin and ground, the average output voltage will be Vdc = VDDIO / 256 * duty + VDDIO/2, where VDDIO is the power supply voltage.
Return · ESP_OK Success · ESP_ERR_INVALID_STATE sigmadelta driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error
Parameters · channel: Sigma-delta channel number · duty: Sigma-delta duty of one channel, the value ranges from -128 to 127, recommended range is -90 ~ 90. The waveform is more like a random one in this range.
esp_err_t sigmadelta_set_prescale(sigmadelta_channel_t channel, uint8_t prescale) Set Sigma-delta channelns clock pre-scale value. The source clock is APP_CLK, 80MHz. The clock frequency of the sigma-delta channel is APP_CLK / pre_scale.
Return · ESP_OK Success · ESP_ERR_INVALID_STATE sigmadelta driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error
Parameters · channel: Sigma-delta channel number · prescale: The divider of source clock, ranges from 0 to 255
esp_err_t sigmadelta_set_pin(sigmadelta_channel_t channel, gpio_num_t gpio_num) Set Sigma-delta signal output pin.
Return · ESP_OK Success · ESP_ERR_INVALID_STATE sigmadelta driver has not been initialized · ESP_ERR_INVALID_ARG Parameter error
Parameters · channel: Sigma-delta channel number · gpio_num: GPIO number of output pin.
Structures struct sigmadelta_config_t
Sigma-delta configure struct.

Espressif Systems

682

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Public Members
sigmadelta_channel_t channel Sigma-delta channel number
int8_t sigmadelta_duty Sigma-delta duty, duty ranges from -128 to 127.
uint8_t sigmadelta_prescale Sigma-delta prescale, prescale ranges from 0 to 255.
uint8_t sigmadelta_gpio Sigma-delta output io number, refer to gpio.h for more details.
Header File · components/hal/include/hal/sigmadelta_types.h
Enumerations enum sigmadelta_port_t
SIGMADELTA port number, the max port number is (SIGMADELTA_NUM_MAX -1). Values: SIGMADELTA_PORT_0
SIGMADELTA port 0 SIGMADELTA_PORT_MAX
SIGMADELTA port max enum sigmadelta_channel_t
Sigma-delta channel list. Values: SIGMADELTA_CHANNEL_0
Sigma-delta channel 0 SIGMADELTA_CHANNEL_1
Sigma-delta channel 1 SIGMADELTA_CHANNEL_2
Sigma-delta channel 2 SIGMADELTA_CHANNEL_3
Sigma-delta channel 3 SIGMADELTA_CHANNEL_4
Sigma-delta channel 4 SIGMADELTA_CHANNEL_5
Sigma-delta channel 5 SIGMADELTA_CHANNEL_6
Sigma-delta channel 6 SIGMADELTA_CHANNEL_7
Sigma-delta channel 7 SIGMADELTA_CHANNEL_MAX
Sigma-delta channel max
2.3.18 SPI Master Driver
SPI Master driver is a program that controls ESP32-S3ns SPI peripherals while they function as masters.

Espressif Systems

683

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Overview of ESP32-S3ns SPI peripherals
ESP32-S3 integrates 4 SPI peripherals.
· SPI0 and SPI1 are used internally to access the ESP32-S3ns attached flash memory. Both controllers share the same SPI bus signals, and there is an arbiter to determine which can access the bus. Currently, SPI Master driver does not support SPI1 bus.
· SPI2 and SPI3 are general purpose SPI controllers. They are open to users. SPI2 and SPI3 have independent signal buses with the same respective names. SPI2 has 6 CS lines. SPI3 has 3 CS lines. Each CS line can be used to drive one SPI slave.
Terminology
The terms used in relation to the SPI master driver are given in the table below.
Term Definition Host The SPI controller peripheral inside ESP32-S3 that initiates SPI transmissions over the bus, and acts as an
SPI Master. De- SPI slave device. An SPI bus may be connected to one or more Devices. Each Device shares the MOSI, vice MISO and SCLK signals but is only active on the bus when the Host asserts the Devicens individual CS
line. Bus A signal bus, common to all Devices connected to one Host. In general, a bus includes the following lines:
MISO, MOSI, SCLK, one or more CS lines, and, optionally, QUADWP and QUADHD. So Devices are connected to the same lines, with the exception that each Device has its own CS line. Several Devices can also share one CS line if connected in the daisy-chain manner. MOSIMaster Out, Slave In, a.k.a. D. Data transmission from a Host to Device. Also data0 signal in Octal/OPI mode. MISOMaster In, Slave Out, a.k.a. Q. Data transmission from a Device to Host. Also data1 signal in Octal/OPI mode. SCLKSerial Clock. Oscillating signal generated by a Host that keeps the transmission of data bits in sync. CS Chip Select. Allows a Host to select individual Device(s) connected to the bus in order to send or receive data. QUADWWrPite Protect signal. Used for 4-bit (qio/qout) transactions. Also for data2 signal in Octal/OPI mode. QUADHHoDld signal. Used for 4-bit (qio/qout) transactions. Also for data3 signal in Octal/OPI mode. DATA4Data4 signal in Octal/OPI mode. DATA5Data5 signal in Octal/OPI mode. DATA6Data6 signal in Octal/OPI mode. DATA7Data7 signal in Octal/OPI mode. As- The action of activating a line. sertion De- The action of returning the line back to inactive (back to idle) status. assertion Trans-One instance of a Host asserting a CS line, transferring data to and from a Device, and de-asserting the CS ac- line. Transactions are atomic, which means they can never be interrupted by another transaction. tion LaunchEdge of the clock at which the source register launches the signal onto the line. edge Latch Edge of the clock at which the destination register latches in the signal. edge

Driver Features
The SPI master driver governs communications of Hosts with Devices. The driver supports the following features: · Multi-threaded environments

Espressif Systems

684

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· Transparent handling of DMA transfers while reading and writing data · Automatic time-division multiplexing of data coming from different Devices on the same signal bus, see SPI
Bus Lock.
Warning: The SPI master driver has the concept of multiple Devices connected to a single bus (sharing a single ESP32-S3 SPI peripheral). As long as each Device is accessed by only one task, the driver is thread safe. However, if multiple tasks try to access the same SPI Device, the driver is not thread-safe. In this case, it is recommended to either:
· Refactor your application so that each SPI peripheral is only accessed by a single task at a time. · Add a mutex lock around the shared Device using xSemaphoreCreateMutex.

SPI Features

SPI Master

SPI Bus Lock To realize the multiplexing of different devices from different drivers (SPI Master, SPI Flash, etc.), an SPI bus lock is applied on each SPI bus. Drivers can attach their devices onto the bus with the arbitration of the lock.
Each bus lock are initialized with a BG (background) service registered, all devices request to do transactions on the bus should wait until the BG to be successfully disabled.
· For SPI1 bus, the BG is the cache, the bus lock will help to disable the cache before device operations starts, and enable it again after device releasing the lock. No devices on SPI1 is allowed using ISR (itns meaningless for the task to yield to other tasks when the cache is disabled).
· For other buses, the driver may register its ISR as the BG. The bus lock will block a device task when it requests for exclusive use of the bus, try to disable the ISR, and unblock the device task allowed to exclusively use the bus when the ISR is successfully disabled. When the task releases the lock, the lock will also try to resume the ISR if there are pending transactions to be done in the ISR.

SPI Transactions
An SPI bus transaction consists of five phases which can be found in the table below. Any of these phases can be skipped.

Phase Command Address Write
Dummy Read

Description In this phase, a command (0-16 bit) is written to the bus by the Host.
In this phase, an address (0-32 bit) is transmitted over the bus by the Host.
Host sends data to a Device. This data follows the optional command and address phases and is indistinguishable from them at the electrical level. This phase is configurable and is used to meet the timing requirements. Device sends data to its Host.

The attributes of a transaction are determined by the bus configuration structure spi_bus_config_t, device configuration structure spi_device_interface_config_t, and transaction configuration structure spi_transaction_t.
An SPI Host can send full-duplex transactions, during which the read and write phases occur simultaneously. The total transaction length is determined by the sum of the following members:
· spi_device_interface_config_t::command_bits · spi_device_interface_config_t::address_bits · spi_transaction_t::length

Espressif Systems

685

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
While the member spi_transaction_t::rxlength only determines the length of data received into the buffer.
In half-duplex transactions, the read and write phases are not simultaneous (one direction at a time). The lengths of the write and read phases are determined by length and rxlength members of the struct spi_transaction_t respectively.
The command and address phases are optional, as not every SPI device requires a command and/or address. This is reflected in the Devicens configuration: if command_bits and/or address_bits are set to zero, no command or address phase will occur.
The read and write phases can also be optional, as not every transaction requires both writing and reading data. If rx_buffer is NULL and SPI_TRANS_USE_RXDATA is not set, the read phase is skipped. If tx_buffer is NULL and SPI_TRANS_USE_TXDATA is not set, the write phase is skipped.
The driver supports two types of transactions: the interrupt transactions and polling transactions. The programmer can choose to use a different transaction type per Device. If your Device requires both transaction types, see Notes on Sending Mixed Transactions to the Same Device.
Interrupt Transactions Interrupt transactions will block the transaction routine until the transaction completes, thus allowing the CPU to run other tasks.
An application task can queue multiple transactions, and the driver will automatically handle them one-by-one in the interrupt service routine (ISR). It allows the task to switch to other procedures until all the transactions complete.
Polling Transactions Polling transactions do not use interrupts. The routine keeps polling the SPI Hostns status bit until the transaction is finished.
All the tasks that use interrupt transactions can be blocked by the queue. At this point, they will need to wait for the ISR to run twice before the transaction is finished. Polling transactions save time otherwise spent on queue handling and context switching, which results in smaller transaction duration. The disadvantage is that the CPU is busy while these transactions are in progress.
The spi_device_polling_end() routine needs an overhead of at least 1 us to unblock other tasks when the transaction is finished. It is strongly recommended to wrap a series of polling transactions using the functions spi_device_acquire_bus() and spi_device_release_bus() to avoid the overhead. For more information, see Bus Acquiring.
Transaction Line Mode Supported line modes for ESP32-S3 are listed as follows, to make use of these modes, set the member flags in the struct spi_transaction_t as shown in the Transaction Flag column. If you want to check if corresponding IO pins are set or not, set the member flags in the spi_bus_config_t as shown in the Bus IO setting Flag column.

Espressif Systems

686

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Mode name
Normal SPI Dual Output Dual I/O Quad Output Quad I/O Octal Output OPI

Command Line Width 1
1
1 1
1 1
8

Address Line Width

Data Line Width

Transaction Flag

1

1

0

1

2

SPI_TRANS_MODE_DIO

2

2

SPI_TRANS_MODE_DIO

SPI_TRANS_MULTILINE_ADDR

1

4

SPI_TRANS_MODE_QIO

4

4

SPI_TRANS_MODE_QIO

SPI_TRANS_MULTILINE_ADDR

1

8

SPI_TRANS_MODE_OCT

8

8

SPI_TRANS_MODE_OCT

SPI_TRANS_MULTILINE_ADDR

SPI_TRANS_MULTILINE_CMD

Bus IO setting Flag
0
SPICOMMON_BUSFLAG_DUAL | SPICOMMON_BUSFLAG_QUAD
| SPICOMMON_BUSFLAG_OCTAL
| |

Command and Address Phases During the command and address phases, the members cmd and addr in the struct spi_transaction_t are sent to the bus, nothing is read at this time. The default lengths of the command and address phases are set in spi_device_interface_config_t by calling spi_bus_add_device(). If the flags SPI_TRANS_VARIABLE_CMD and SPI_TRANS_VARIABLE_ADDR in the member spi_transaction_t::flags are not set, the driver automatically sets the length of these phases to default values during Device initialization.
If the lengths of the command and address phases need to be variable, declare the struct spi_transaction_ext_t, set the flags SPI_TRANS_VARIABLE_CMD and/or SPI_TRANS_VARIABLE_ADDR in the member spi_transaction_ext_t::base and configure the rest of base as usual. Then the length of each phase will be equal to command_bits and address_bits set in the struct spi_transaction_ext_t.
If the command and address phase need to be as the same number of lines as data phase, you need to set SPI_TRANS_MULTILINE_CMD and/or SPI_TRANS_MULTILINE_ADDR to the flags member in the struct spi_transaction_t. Also see Transaction Line Mode.
Write and Read Phases Normally, the data that needs to be transferred to or from a Device will be read from or written to a chunk of memory indicated by the members rx_buffer and tx_buffer of the structure spi_transaction_t. If DMA is enabled for transfers, the buffers are required to be:
1. Allocated in DMA-capable internal memory. If external PSRAM is enabled, this means using pvPortMallocCaps(size, MALLOC_CAP_DMA).
2. 32-bit aligned (staring from a 32-bit boundary and having a length of multiples of 4 bytes).
If these requirements are not satisfied, the transaction efficiency will be affected due to the allocation and copying of temporary buffers.
If using more than one data lines to transmit, please set SPI_DEVICE_HALFDUPLEX flag for the member flags in the struct spi_device_interface_config_t. And the member flags in the struct spi_transaction_t should be set as described in Transaction Line Mode.
Note: Half-duplex transactions with both read and write phases are not supported. Please use full duplex mode.

Espressif Systems

687

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Bus Acquiring Sometimes you might want to send SPI transactions exclusively and continuously so that it takes as little time as possible. For this, you can use bus acquiring, which helps to suspend transactions (both polling or interrupt) to other devices until the bus is released. To acquire and release a bus, use the functions spi_device_acquire_bus() and spi_device_release_bus().
Driver Usage
· Initialize an SPI bus by calling the function spi_bus_initialize(). Make sure to set the correct I/O pins in the struct spi_bus_config_t. Set the signals that are not needed to -1.
· Register a Device connected to the bus with the driver by calling the function spi_bus_add_device(). Make sure to configure any timing requirements the device might need with the parameter dev_config. You should now have obtained the Devicens handle which will be used when sending a transaction to it.
· To interact with the Device, fill one or more spi_transaction_t structs with any transaction parameters required. Then send the structs either using a polling transaction or an interrupt transaction: ­ Interrupt Either queue all transactions by calling the function spi_device_queue_trans() and, at a later time, query the result using the function spi_device_get_trans_result(), or handle all requests synchronously by feeding them into spi_device_transmit(). ­ Polling Call the function spi_device_polling_transmit() to send polling transactions. Alternatively, if you want to insert something in between, send the transactions by using spi_device_polling_start() and spi_device_polling_end().
· (Optional) To perform back-to-back transactions with a Device, call the function spi_device_acquire_bus() before sending transactions and spi_device_release_bus() after the transactions have been sent.
· (Optional) To unload the driver for a certain Device, call spi_bus_remove_device() with the Device handle as an argument.
· (Optional) To remove the driver for a bus, make sure no more drivers are attached and call spi_bus_free().
The example code for the SPI master driver can be found in the peripherals/spi_master directory of ESP-IDF examples.
Transactions with Data Not Exceeding 32 Bits When the transaction data size is equal to or less than 32 bits, it will be sub-optimal to allocate a buffer for the data. The data can be directly stored in the transaction struct instead. For transmitted data, it can be achieved by using the tx_data member and setting the SPI_TRANS_USE_TXDATA flag on the transmission. For received data, use rx_data and set SPI_TRANS_USE_RXDATA. In both cases, do not touch the tx_buffer or rx_buffer members, because they use the same memory locations as tx_data and rx_data.
Transactions with Integers Other Than uint8_t An SPI Host reads and writes data into memory byte by byte. By default, data is sent with the most significant bit (MSB) first, as LSB first used in rare cases. If a value less than 8 bits needs to be sent, the bits should be written into memory in the MSB first manner.
For example, if 0b00010 needs to be sent, it should be written into a uint8_t variable, and the length for reading should be set to 5 bits. The Device will still receive 8 bits with 3 additional orandompbits, so the reading must be performed correctly.
On top of that, ESP32-S3 is a little-endian chip, which means that the least significant byte of uint16_t and uint32_t variables is stored at the smallest address. Hence, if uint16_t is stored in memory, bits [7:0] are sent first, followed by bits [15:8].
For cases when the data to be transmitted has the size differing from uint8_t arrays, the following macros can be used to transform data to the format that can be sent by the SPI driver directly:
· SPI_SWAP_DATA_TX for data to be transmitted · SPI_SWAP_DATA_RX for data received

Espressif Systems

688

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Notes on Sending Mixed Transactions to the Same Device To reduce coding complexity, send only one type of transactions (interrupt or polling) to one Device. However, you still can send both interrupt and polling transactions alternately. The notes below explain how to do this.
The polling transactions should be initiated only after all the polling and interrupt transactions are finished.
Since an unfinished polling transaction blocks other transactions, please do not forget to call the function spi_device_polling_end() after spi_device_polling_start() to allow other transactions or to allow other Devices to use the bus. Remember that if there is no need to switch to other tasks during your polling transaction, you can initiate a transaction with spi_device_polling_transmit() so that it will be ended automatically.
In-flight polling transactions are disturbed by the ISR operation to accommodate interrupt transactions. Always make sure that all the interrupt transactions sent to the ISR are finished before you call spi_device_polling_start(). To do that, you can keep calling spi_device_get_trans_result() until all the transactions are returned.
To have better control of the calling sequence of functions, send mixed transactions to the same Device only within a single task.
Transfer Speed Considerations
There are three factors limiting the transfer speed:
· Transaction interval · SPI clock frequency · Cache miss of SPI functions, including callbacks
The main parameter that determines the transfer speed for large transactions is clock frequency. For multiple small transactions, the transfer speed is mostly determined by the length of transaction intervals.
Transaction Duration Transaction duration includes setting up SPI peripheral registers, copying data to FIFOs or setting up DMA links, and the time for SPI transaction.
Interrupt transactions allow appending extra overhead to accommodate the cost of FreeRTOS queues and the time needed for switching between tasks and the ISR.
For interrupt transactions, the CPU can switch to other tasks when a transaction is in progress. This saves the CPU time but increases the transaction duration. See Interrupt Transactions. For polling transactions, it does not block the task but allows to do polling when the transaction is in progress. For more information, see Polling Transactions.
If DMA is enabled, setting up the linked list requires about 2 us per transaction. When a master is transferring data, it automatically reads the data from the linked list. If DMA is not enabled, the CPU has to write and read each byte from the FIFO by itself. Usually, this is faster than 2 us, but the transaction length is limited to 64 bytes for both write and read.
Typical transaction duration for one byte of data are given below.
· Interrupt Transaction via DMA: 26 µs. · Interrupt Transaction via CPU: 24 µs. · Polling Transaction via DMA: 11 µs. · Polling Transaction via CPU: 9 µs.
SPI Clock Frequency Transferring each byte takes eight times the clock period 8/fspi.
Cache Miss The default config puts only the ISR into the IRAM. Other SPI related functions, including the driver itself and the callback, might suffer from cache misses and will need to wait until the code is read from flash. Select CONFIG_SPI_MASTER_IN_IRAM to put the whole SPI driver into IRAM and put the entire callback(s) and its callee functions into IRAM to prevent cache misses.

Espressif Systems

689

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

For an interrupt transaction, the overall cost is 20+8n/Fspi[MHz] [us] for n bytes transferred in one transaction. Hence, the transferring speed is: n/(20+8n/Fspi). An example of transferring speed at 8 MHz clock speed is given in the following table.

Frequency (MHz) 8 8 8 8 8

Transaction Interval (us) 25 25 25 25 25

Transaction Length (bytes) 1 8 16 64 128

Total Time (us) 26 33 41 89 153

Total Speed (KBps) 38.5 242.4 490.2 719.1 836.6

When a transaction length is short, the cost of transaction interval is high. If possible, try to squash several short transactions into one transaction to achieve a higher transfer speed.
Please note that the ISR is disabled during flash operation by default. To keep sending transactions during flash operations, enable CONFIG_SPI_MASTER_ISR_IN_IRAM and set ESP_INTR_FLAG_IRAM in the member spi_bus_config_t::intr_flags. In this case, all the transactions queued before starting flash operations will be handled by the ISR in parallel. Also note that the callback of each Device and their callee functions should be in IRAM, or your callback will crash due to cache miss. For more details, see IRAM-Safe Interrupt Handlers.

Application Example
The code example for using the SPI master half duplex mode to read/write a AT93C46D EEPROM (8-bit mode) can be found in the peripherals/spi_master/hd_eeprom directory of ESP-IDF examples.

API Reference - SPI Common
Header File · components/hal/include/hal/spi_types.h

Structures struct spi_line_mode_t
Line mode of SPI transaction phases: CMD, ADDR, DOUT/DIN.

Public Members
uint8_t cmd_lines The line width of command phase, e.g. 2-line-cmd-phase.
uint8_t addr_lines The line width of address phase, e.g. 1-line-addr-phase.
uint8_t data_lines The line width of data phase, e.g. 4-line-data-phase.

Enumerations enum spi_host_device_t
Enum with the three SPI peripherals that are software-accessible in it.
Values:
SPI1_HOST = 0 SPI1.

Espressif Systems

690

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

SPI2_HOST = 1 SPI2.
SPI3_HOST = 2 SPI3.
SPI_HOST_MAX invalid host value
enum spi_clock_source_t Values:
SPI_CLK_APB Select APB as the source clock.
SPI_CLK_XTAL Select XTAL as the source clock.
enum spi_event_t SPI Events.
Values:
SPI_EV_BUF_TX = BIT(0) The buffer has sent data to master.
SPI_EV_BUF_RX = BIT(1) The buffer has received data from master.
SPI_EV_SEND_DMA_READY = BIT(2) Slave has loaded its TX data buffer to the hardware (DMA).
SPI_EV_SEND = BIT(3) Master has received certain number of the data, the number is determined by Master.
SPI_EV_RECV_DMA_READY = BIT(4) Slave has loaded its RX data buffer to the hardware (DMA).
SPI_EV_RECV = BIT(5) Slave has received certain number of data from master, the number is determined by Master.
SPI_EV_CMD9 = BIT(6) Received CMD9 from master.
SPI_EV_CMDA = BIT(7) Received CMDA from master.
SPI_EV_TRANS = BIT(8) A transaction has done.

Header File · components/driver/include/driver/spi_common.h

Functions

esp_err_t spi_bus_initialize(spi_host_device_t host_id, const spi_bus_config_t *bus_config,

Initialize a SPI bus.

spi_dma_chan_t dma_chan)

Warning SPI0/1 is not supported Warning If a DMA channel is selected, any transmit and receive buffer used should be allocated in DMA-
capable memory. Warning The ISR of SPI is always executed on the core which calls this function. Never starve the ISR on
this core or the SPI transactions will not be handled. Return
· ESP_ERR_INVALID_ARG if configuration is invalid

Espressif Systems

691

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_ERR_INVALID_STATE if host already is in use · ESP_ERR_NOT_FOUND if there is no available DMA channel · ESP_ERR_NO_MEM if out of memory · ESP_OK on success Parameters · host_id: SPI peripheral that controls this bus · bus_config: Pointer to a spi_bus_config_t struct specifying how the host should be initialized · dma_chan: - Selecting a DMA channel for an SPI bus allows transactions on the bus with size only
limited by the amount of internal memory. ­ Selecting SPI_DMA_DISABLED limits the size of transactions. ­ Set to SPI_DMA_DISABLED if only the SPI flash uses this bus. ­ Set to SPI_DMA_CH_AUTO to let the driver to allocate the DMA channel.
esp_err_t spi_bus_free(spi_host_device_t host_id) Free a SPI bus.
Warning In order for this to succeed, all devices have to be removed first. Return
· ESP_ERR_INVALID_ARG if parameter is invalid · ESP_ERR_INVALID_STATE if not all devices on the bus are freed · ESP_OK on success Parameters · host_id: SPI peripheral to free
Structures struct spi_bus_config_t
This is a configuration structure for a SPI bus.
You can use this structure to specify the GPIO pins of the bus. Normally, the driver will use the GPIO matrix to route the signals. An exception is made when all signals either can be routed through the IO_MUX or are -1. In that case, the IO_MUX is used, allowing for >40MHz speeds.
Note Be advised that the slave driver does not use the quadwp/quadhd lines and fields in spi_bus_config_t refering to these lines will be ignored and can thus safely be left uninitialized.
Public Members
int mosi_io_num GPIO pin for Master Out Slave In (=spi_d) signal, or -1 if not used.
int data0_io_num GPIO pin for spi data0 signal in quad/octal mode, or -1 if not used.
int miso_io_num GPIO pin for Master In Slave Out (=spi_q) signal, or -1 if not used.
int data1_io_num GPIO pin for spi data1 signal in quad/octal mode, or -1 if not used.
int sclk_io_num GPIO pin for SPI Clock signal, or -1 if not used.
int quadwp_io_num GPIO pin for WP (Write Protect) signal, or -1 if not used.
int data2_io_num GPIO pin for spi data2 signal in quad/octal mode, or -1 if not used.
int quadhd_io_num GPIO pin for HD (Hold) signal, or -1 if not used.
int data3_io_num GPIO pin for spi data3 signal in quad/octal mode, or -1 if not used.

Espressif Systems

692

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

int data4_io_num GPIO pin for spi data4 signal in octal mode, or -1 if not used.
int data5_io_num GPIO pin for spi data5 signal in octal mode, or -1 if not used.
int data6_io_num GPIO pin for spi data6 signal in octal mode, or -1 if not used.
int data7_io_num GPIO pin for spi data7 signal in octal mode, or -1 if not used.
int max_transfer_sz Maximum transfer size, in bytes. Defaults to 4092 if 0 when DMA enabled, or to SOC_SPI_MAXIMUM_BUFFER_SIZE if DMA is disabled.
uint32_t flags Abilities of bus to be checked by the driver. Or-ed value of SPICOMMON_BUSFLAG_* flags.
int intr_flags Interrupt flag for the bus to set the priority, and IRAM attribute, see esp_intr_alloc.h. Note that the EDGE, INTRDISABLED attribute are ignored by the driver. Note that if ESP_INTR_FLAG_IRAM is set, ALL the callbacks of the driver, and their callee functions, should be put in the IRAM.

Macros SPI_MAX_DMA_LEN SPI_SWAP_DATA_TX(DATA, LEN)
Transform unsigned integer of length <= 32 bits to the format which can be sent by the SPI driver directly.
E.g. to send 9 bits of data, you can:
uint16_t data = SPI_SWAP_DATA_TX(0x145, 9);
Then points tx_buffer to &data.
Parameters · DATA: Data to be sent, can be uint8_t, uint16_t or uint32_t. · LEN: Length of data to be sent, since the SPI peripheral sends from the MSB, this helps to shift the data to the MSB.
SPI_SWAP_DATA_RX(DATA, LEN) Transform received data of length <= 32 bits to the format of an unsigned integer.
E.g. to transform the data of 15 bits placed in a 4-byte array to integer:
uint16_t data = SPI_SWAP_DATA_RX(*(uint32_t*)t->rx_data, 15);
Parameters · DATA: Data to be rearranged, can be uint8_t, uint16_t or uint32_t. · LEN: Length of data received, since the SPI peripheral writes from the MSB, this helps to shift the data to the LSB.
SPICOMMON_BUSFLAG_SLAVE Initialize I/O in slave mode.
SPICOMMON_BUSFLAG_MASTER Initialize I/O in master mode.
SPICOMMON_BUSFLAG_IOMUX_PINS Check using iomux pins. Or indicates the pins are configured through the IO mux rather than GPIO matrix.
SPICOMMON_BUSFLAG_GPIO_PINS Force the signals to be routed through GPIO matrix. Or indicates the pins are routed through the GPIO matrix.
SPICOMMON_BUSFLAG_SCLK Check existing of SCLK pin. Or indicates CLK line initialized.

Espressif Systems

693

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

SPICOMMON_BUSFLAG_MISO Check existing of MISO pin. Or indicates MISO line initialized.
SPICOMMON_BUSFLAG_MOSI Check existing of MOSI pin. Or indicates MOSI line initialized.
SPICOMMON_BUSFLAG_DUAL Check MOSI and MISO pins can output. Or indicates bus able to work under DIO mode.
SPICOMMON_BUSFLAG_WPHD Check existing of WP and HD pins. Or indicates WP & HD pins initialized.
SPICOMMON_BUSFLAG_QUAD Check existing of MOSI/MISO/WP/HD pins as output. Or indicates bus able to work under QIO mode.
SPICOMMON_BUSFLAG_IO4_IO7 Check existing of IO4~IO7 pins. Or indicates IO4~IO7 pins initialized.
SPICOMMON_BUSFLAG_OCTAL Check existing of MOSI/MISO/WP/HD/SPIIO4/SPIIO5/SPIIO6/SPIIO7 pins as output. Or indicates bus able to work under octal mode.
SPICOMMON_BUSFLAG_NATIVE_PINS

Type Definitions typedef spi_common_dma_t spi_dma_chan_t

Enumerations enum spi_common_dma_t
SPI DMA channels.
Values:
SPI_DMA_DISABLED = 0 Do not enable DMA for SPI.
SPI_DMA_CH_AUTO = 3 Enable DMA, channel is automatically selected by driver.

API Reference - SPI Master
Header File · components/driver/include/driver/spi_master.h

Functions esp_err_t spi_bus_add_device(spi_host_device_t host_id, const spi_device_interface_config_t
*dev_config, spi_device_handle_t *handle) Allocate a device on a SPI bus.
This initializes the internal structures for a device, plus allocates a CS pin on the indicated SPI master peripheral and routes it to the indicated GPIO. All SPI master devices have three CS pins and can thus control up to three devices.
Note While in general, speeds up to 80MHz on the dedicated SPI pins and 40MHz on GPIO-matrix-routed pins are supported, full-duplex transfers routed over the GPIO matrix only support speeds up to 26MHz.
Return · ESP_ERR_INVALID_ARG if parameter is invalid · ESP_ERR_NOT_FOUND if host doesnnt have any free CS slots · ESP_ERR_NO_MEM if out of memory · ESP_OK on success
Parameters

Espressif Systems

694

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· host_id: SPI peripheral to allocate device on · dev_config: SPI interface protocol config for the device · handle: Pointer to variable to hold the device handle esp_err_t spi_bus_remove_device(spi_device_handle_t handle) Remove a device from the SPI bus.

Return · ESP_ERR_INVALID_ARG if parameter is invalid · ESP_ERR_INVALID_STATE if device already is freed · ESP_OK on success
Parameters · handle: Device handle to free

esp_err_t spi_device_queue_trans(spi_device_handle_t handle, spi_transaction_t *trans_desc, Tick-

Type_t ticks_to_wait)

Queue a SPI transaction for interrupt transaction execution.

Get the result by

spi_device_get_trans_result.

Note Normally a device cannot start (queue) polling and interrupt transactions simultaneously.

Return

· ESP_ERR_INVALID_ARG if parameter is invalid.

This can happen if

SPI_TRANS_CS_KEEP_ACTIVE flag is specified while the bus was not acquired

(spi_device_acquire_bus() should be called first)

· ESP_ERR_TIMEOUT if there was no room in the queue before ticks_to_wait expired

· ESP_ERR_NO_MEM if allocating DMA-capable temporary buffer failed

· ESP_ERR_INVALID_STATE if previous transactions are not finished

· ESP_OK on success

Parameters

· handle: Device handle obtained using spi_host_add_dev

· trans_desc: Description of transaction to execute

· ticks_to_wait: Ticks to wait until therens room in the queue; use portMAX_DELAY to never

time out.

esp_err_t spi_device_get_trans_result(spi_device_handle_t handle,

spi_transaction_t

**trans_desc, TickType_t ticks_to_wait)

Get the result of a SPI transaction queued earlier by spi_device_queue_trans.

This routine will wait until a transaction to the given device succesfully completed. It will then return the description of the completed transaction so software can inspect the result and e.g. free the memory or re-use the buffers.

Return · ESP_ERR_INVALID_ARG if parameter is invalid · ESP_ERR_TIMEOUT if there was no completed transaction before ticks_to_wait expired · ESP_OK on success
Parameters · handle: Device handle obtained using spi_host_add_dev · trans_desc: Pointer to variable able to contain a pointer to the description of the transaction that is executed. The descriptor should not be modified until the descriptor is returned by spi_device_get_trans_result. · ticks_to_wait: Ticks to wait until therens a returned item; use portMAX_DELAY to never time out.

esp_err_t spi_device_transmit(spi_device_handle_t handle, spi_transaction_t *trans_desc) Send a SPI transaction, wait for it to complete, and return the result.

This function is the equivalent of calling spi_device_queue_trans() followed by spi_device_get_trans_result(). Do not use this when there is still a transaction separately queued (started) from spi_device_queue_trans() or polling_start/transmit that hasnnt been finalized.

Note This function is not thread safe when multiple tasks access the same SPI device. Normally a device cannot start (queue) polling and interrupt transactions simutanuously.
Return

Espressif Systems

695

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_ERR_INVALID_ARG if parameter is invalid · ESP_OK on success Parameters · handle: Device handle obtained using spi_host_add_dev · trans_desc: Description of transaction to execute

esp_err_t spi_device_polling_start(spi_device_handle_t handle, spi_transaction_t *trans_desc,
TickType_t ticks_to_wait) Immediately start a polling transaction.

Note Normally a device cannot start (queue) polling and interrupt transactions simutanuously. Moreover, a

device cannot start a new polling transaction if another polling transaction is not finished.

Return

· ESP_ERR_INVALID_ARG if parameter is invalid.

This can happen if

SPI_TRANS_CS_KEEP_ACTIVE flag is specified while the bus was not acquired

(spi_device_acquire_bus() should be called first)

· ESP_ERR_TIMEOUT if the device cannot get control of the bus before ticks_to_wait expired

· ESP_ERR_NO_MEM if allocating DMA-capable temporary buffer failed

· ESP_ERR_INVALID_STATE if previous transactions are not finished

· ESP_OK on success

Parameters

· handle: Device handle obtained using spi_host_add_dev

· trans_desc: Description of transaction to execute

· ticks_to_wait: Ticks to wait until therens room in the queue; currently only port-

MAX_DELAY is supported.

esp_err_t spi_device_polling_end(spi_device_handle_t handle, TickType_t ticks_to_wait) Poll until the polling transaction ends.

This routine will not return until the transaction to the given device has succesfully completed. The task is not blocked, but actively busy-spins for the transaction to be completed.

Return · ESP_ERR_INVALID_ARG if parameter is invalid · ESP_ERR_TIMEOUT if the transaction cannot finish before ticks_to_wait expired · ESP_OK on success
Parameters · handle: Device handle obtained using spi_host_add_dev · ticks_to_wait: Ticks to wait until therens a returned item; use portMAX_DELAY to never time out.

esp_err_t spi_device_polling_transmit(spi_device_handle_t handle, *trans_desc)
Send a polling transaction, wait for it to complete, and return the result.

spi_transaction_t

This function is the equivalent of calling spi_device_polling_start() followed by spi_device_polling_end(). Do not use this when there is still a transaction that hasnnt been finalized.

Note This function is not thread safe when multiple tasks access the same SPI device. Normally a device cannot start (queue) polling and interrupt transactions simutanuously.
Return · ESP_ERR_INVALID_ARG if parameter is invalid · ESP_OK on success
Parameters · handle: Device handle obtained using spi_host_add_dev · trans_desc: Description of transaction to execute

esp_err_t spi_device_acquire_bus(spi_device_handle_t device, TickType_t wait) Occupy the SPI bus for a device to do continuous transactions.

Transactions to all other devices will be put off until spi_device_release_bus is called.

Note The function will wait until all the existing transactions have been sent. Return

Espressif Systems

696

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· ESP_ERR_INVALID_ARG : wait is not set to portMAX_DELAY. · ESP_OK : Success. Parameters · device: The device to occupy the bus. · wait: Time to wait before the the bus is occupied by the device. Currently MUST set to port-
MAX_DELAY.
void spi_device_release_bus(spi_device_handle_t dev) Release the SPI bus occupied by the device. All other devices can start sending transactions.
Parameters · dev: The device to release the bus.
int spi_cal_clock(int fapb, int hz, int duty_cycle, uint32_t *reg_o) Calculate the working frequency that is most close to desired frequency, and also the register value.
Parameters · fapb: The frequency of apb clock, should be APB_CLK_FREQ. · hz: Desired working frequency · duty_cycle: Duty cycle of the spi clock · reg_o: Output of value to be set in clock register, or NULL if not needed.
Return Actual working frequency that most fit.
int spi_get_actual_clock(int fapb, int hz, int duty_cycle) Calculate the working frequency that is most close to desired frequency.
Return Actual working frequency that most fit. Parameters
· fapb: The frequency of apb clock, should be APB_CLK_FREQ. · hz: Desired working frequency · duty_cycle: Duty cycle of the spi clock
void spi_get_timing(bool gpio_is_used, int input_delay_ns, int eff_clk, int *dummy_o, int *cycles_remain_o)
Calculate the timing settings of specified frequency and settings.
Note If **dummy_o* is not zero, it means dummy bits should be applied in half duplex mode, and full duplex mode may not work.
Parameters · gpio_is_used: True if using GPIO matrix, or False if iomux pins are used. · input_delay_ns: Input delay from SCLK launch edge to MISO data valid. · eff_clk: Effective clock frequency (in Hz) from spi_cal_clock. · dummy_o: Address of dummy bits used output. Set to NULL if not needed. · cycles_remain_o: Address of cycles remaining (after dummy bits are used) output. ­ -1 If too many cycles remaining, suggest to compensate half a clock. ­ 0 If no remaining cycles or dummy bits are not used. ­ positive value: cycles suggest to compensate.
int spi_get_freq_limit(bool gpio_is_used, int input_delay_ns) Get the frequency limit of current configurations. SPI master working at this limit is OK, while above the limit, full duplex mode and DMA will not work, and dummy bits will be aplied in the half duplex mode.
Return Frequency limit of current configurations. Parameters
· gpio_is_used: True if using GPIO matrix, or False if native pins are used. · input_delay_ns: Input delay from SCLK launch edge to MISO data valid.
Structures struct spi_device_interface_config_t
This is a configuration for a SPI slave device that is connected to one of the SPI buses.

Espressif Systems

697

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Public Members
uint8_t command_bits Default amount of bits in command phase (0-16), used when SPI_TRANS_VARIABLE_CMD is not used, otherwise ignored.
uint8_t address_bits Default amount of bits in address phase (0-64), used when SPI_TRANS_VARIABLE_ADDR is not used, otherwise ignored.
uint8_t dummy_bits Amount of dummy bits to insert between address and data phase.
uint8_t mode SPI mode, representing a pair of (CPOL, CPHA) configuration:
· 0: (0, 0) · 1: (0, 1) · 2: (1, 0) · 3: (1, 1)
uint16_t duty_cycle_pos Duty cycle of positive clock, in 1/256th increments (128 = 50%/50% duty). Setting this to 0 (=not setting it) is equivalent to setting this to 128.
uint16_t cs_ena_pretrans Amount of SPI bit-cycles the cs should be activated before the transmission (0-16). This only works on half-duplex transactions.
uint8_t cs_ena_posttrans Amount of SPI bit-cycles the cs should stay active after the transmission (0-16)
int clock_speed_hz Clock speed, divisors of 80MHz, in Hz. See SPI_MASTER_FREQ_*.
int input_delay_ns Maximum data valid time of slave. The time required between SCLK and MISO valid, including the possible clock delay from slave to master. The driver uses this value to give an extra delay before the MISO is ready on the line. Leave at 0 unless you know you need a delay. For better timing performance at high frequency (over 8MHz), itns suggest to have the right value.
int spics_io_num CS GPIO pin for this device, or -1 if not used.
uint32_t flags Bitwise OR of SPI_DEVICE_* flags.
int queue_size Transaction queue size. This sets how many transactions can be min the airn(queued using spi_device_queue_trans but not yet finished using spi_device_get_trans_result) at the same time.
transaction_cb_t pre_cb Callback to be called before a transmission is started.
This callback is called within interrupt context should be in IRAM for best performance, see oTransferring Speedpsection in the SPI Master documentation for full details. If not, the callback may crash during flash operation when the driver is initialized with ESP_INTR_FLAG_IRAM.
transaction_cb_t post_cb Callback to be called after a transmission has completed.
This callback is called within interrupt context should be in IRAM for best performance, see oTransferring Speedpsection in the SPI Master documentation for full details. If not, the callback may crash during flash operation when the driver is initialized with ESP_INTR_FLAG_IRAM.

Espressif Systems

698

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
struct spi_transaction_t This structure describes one SPI transaction. The descriptor should not be modified until the transaction finishes.
Public Members
uint32_t flags Bitwise OR of SPI_TRANS_* flags.
uint16_t cmd Command data, of which the length is set in the command_bits of spi_device_interface_config_t. NOTE: this field, used to be ocommandpin ESP-IDF 2.1 and before, is re-written to be used in a new way in ESP-IDF 3.0.
Example: write 0x0123 and command_bits=12 to send command 0x12, 0x3_ (in previous version, you may have to write 0x3_12).
uint64_t addr Address data, of which the length is set in the address_bits of spi_device_interface_config_t. NOTE: this field, used to be oaddresspin ESP-IDF 2.1 and before, is re-written to be used in a new way in ESP-IDF3.0.
Example: write 0x123400 and address_bits=24 to send address of 0x12, 0x34, 0x00 (in previous version, you may have to write 0x12340000).
size_t length Total data length, in bits.
size_t rxlength Total data length received, should be not greater than length in full-duplex mode (0 defaults this to the value of length).
void *user User-defined variable. Can be used to store eg transaction ID.
const void *tx_buffer Pointer to transmit buffer, or NULL for no MOSI phase.
uint8_t tx_data[4] If SPI_TRANS_USE_TXDATA is set, data set here is sent directly from this variable.
void *rx_buffer Pointer to receive buffer, or NULL for no MISO phase. Written by 4 bytes-unit if DMA is used.
uint8_t rx_data[4] If SPI_TRANS_USE_RXDATA is set, data is received directly to this variable.
struct spi_transaction_ext_t This struct is for SPI transactions which may change their address and command length. Please do set the flags in base to SPI_TRANS_VARIABLE_CMD_ADR to use the bit length here.
Public Members
struct spi_transaction_t base Transaction data, so that pointer to spi_transaction_t can be converted into spi_transaction_ext_t.
uint8_t command_bits The command length in this transaction, in bits.
uint8_t address_bits The address length in this transaction, in bits.

Espressif Systems

699

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
uint8_t dummy_bits The dummy length in this transaction, in bits.
Macros SPI_MASTER_FREQ_8M
SPI master clock is divided by 80MHz apb clock. Below defines are example frequencies, and are accurate. Be free to specify a random frequency, it will be rounded to closest frequency (to macros below if above 8MHz). 8MHz SPI_MASTER_FREQ_9M 8.89MHz
SPI_MASTER_FREQ_10M 10MHz
SPI_MASTER_FREQ_11M 11.43MHz
SPI_MASTER_FREQ_13M 13.33MHz
SPI_MASTER_FREQ_16M 16MHz
SPI_MASTER_FREQ_20M 20MHz
SPI_MASTER_FREQ_26M 26.67MHz
SPI_MASTER_FREQ_40M 40MHz
SPI_MASTER_FREQ_80M 80MHz
SPI_DEVICE_TXBIT_LSBFIRST Transmit command/address/data LSB first instead of the default MSB first.
SPI_DEVICE_RXBIT_LSBFIRST Receive data LSB first instead of the default MSB first.
SPI_DEVICE_BIT_LSBFIRST Transmit and receive LSB first.
SPI_DEVICE_3WIRE Use MOSI (=spid) for both sending and receiving data.
SPI_DEVICE_POSITIVE_CS Make CS positive during a transaction instead of negative.
SPI_DEVICE_HALFDUPLEX Transmit data before receiving it, instead of simultaneously.
SPI_DEVICE_CLK_AS_CS Output clock on CS line if CS is active.
SPI_DEVICE_NO_DUMMY There are timing issue when reading at high frequency (the frequency is related to whether iomux pins are used, valid time after slave sees the clock).
· In half-duplex mode, the driver automatically inserts dummy bits before reading phase to fix the timing issue. Set this flag to disable this feature.
· In full-duplex mode, however, the hardware cannot use dummy bits, so there is no way to prevent data being read from getting corrupted. Set this flag to confirm that younre going to work with output only, or read without dummy bits at your own risk.

Espressif Systems

700

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
SPI_DEVICE_DDRCLK SPI_TRANS_MODE_DIO
Transmit/receive data in 2-bit mode. SPI_TRANS_MODE_QIO
Transmit/receive data in 4-bit mode. SPI_TRANS_USE_RXDATA
Receive into rx_data member of spi_transaction_t instead into memory at rx_buffer. SPI_TRANS_USE_TXDATA
Transmit tx_data member of spi_transaction_t instead of data at tx_buffer. Do not set tx_buffer when using this. SPI_TRANS_MODE_DIOQIO_ADDR Also transmit address in mode selected by SPI_MODE_DIO/SPI_MODE_QIO. SPI_TRANS_VARIABLE_CMD Use the command_bits in spi_transaction_ext_t rather than default value in spi_device_interface_config_t. SPI_TRANS_VARIABLE_ADDR Use the address_bits in spi_transaction_ext_t rather than default value in spi_device_interface_config_t. SPI_TRANS_VARIABLE_DUMMY Use the dummy_bits in spi_transaction_ext_t rather than default value in spi_device_interface_config_t. SPI_TRANS_CS_KEEP_ACTIVE Keep CS active after data transfer. SPI_TRANS_MULTILINE_CMD The data lines used at command phase is the same as data phase (otherwise, only one data line is used at command phase) SPI_TRANS_MODE_OCT Transmit/receive data in 8-bit mode. SPI_TRANS_MULTILINE_ADDR The data lines used at address phase is the same as data phase (otherwise, only one data line is used at address phase)
Type Definitions typedef struct spi_transaction_t spi_transaction_t typedef void (*transaction_cb_t)(spi_transaction_t *trans) typedef struct spi_device_t *spi_device_handle_t
Handle for a device on a SPI bus.
2.3.19 SPI Slave Driver
SPI Slave driver is a program that controls ESP32-S3ns SPI peripherals while they function as slaves.
Overview of ESP32-S3ns SPI peripherals
ESP32-S3 integrates two general purpose SPI controllers which can be used as slave nodes driven by an off-chip SPI master SPI2 and SPI3 have independent signal buses with the same respective names.

Espressif Systems

701

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Terminology

The terms used in relation to the SPI slave driver are given in the table below.

Term Host Device
Bus
· MISO · MOSI · SCLK · CS · QUADWP · QUADHD

Definition The SPI controller peripheral external to ESP32-S3 that initiates SPI transmissions over the bus, and acts as an SPI Master. SPI slave device (general purpose SPI controller). Each Device shares the MOSI, MISO and SCLK signals but is only active on the bus when the Host asserts the Devicens individual CS line. A signal bus, common to all Devices connected to one Host. In general, a bus includes the following lines: MISO, MOSI, SCLK, one or more CS lines, and, optionally, QUADWP and QUADHD. So Devices are connected to the same lines, with the exception that each Device has its own CS line. Several Devices can also share one CS line if connected in the daisy-chain manner. Master In, Slave Out, a.k.a. Q. Data transmission from a Device to Host.
Master Out, Slave in, a.k.a. D. Data transmission from a Host to Device.
Serial Clock. Oscillating signal generated by a Host that keeps the transmission of data bits in sync.
Chip Select. Allows a Host to select individual Device(s) connected to the bus in order to send or receive data. Write Protect signal. Only used for 4-bit (qio/qout) transactions.
Hold signal. Only used for 4-bit (qio/qout) transactions.

· Assertion Transaction
Launch edge Latch edge

The action of activating a line. The opposite action of returning the line back to inactive (back to idle) is called de-assertion. One instance of a Host asserting a CS line, transferring data to and from a Device, and de-asserting the CS line. Transactions are atomic, which means they can never be interrupted by another transaction. Edge of the clock at which the source register launches the signal onto the line. Edge of the clock at which the destination register latches in the signal.

Driver Features
The SPI slave driver allows using the SPI peripherals as full-duplex Devices. The driver can send/receive transactions up to 64 bytes in length, or utilize DMA to send/receive longer transactions. However, there are some known issues related to DMA.

Espressif Systems

702

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
SPI Transactions
A full-duplex SPI transaction begins when the Host asserts the CS line and starts sending out clock pulses on the SCLK line. Every clock pulse, a data bit is shifted from the Host to the Device on the MOSI line and back on the MISO line at the same time. At the end of the transaction, the Host de-asserts the CS line. The attributes of a transaction are determined by the configuration structure for an SPI host acting as a slave device spi_slave_interface_config_t, and transaction configuration structure spi_slave_transaction_t. As not every transaction requires both writing and reading data, you have a choice to configure the spi_transaction_t structure for TX only, RX only, or TX and RX transactions. If spi_slave_transaction_t::rx_buffer is set to NULL, the read phase will be skipped. If spi_slave_transaction_t::tx_buffer is set to NULL, the write phase will be skipped.
Note: A Host should not start a transaction before its Device is ready for receiving data. It is recommended to use another GPIO pin for a handshake signal to sync the Devices. For more details, see Transaction Interval.
Driver Usage
· Initialize an SPI peripheral as a Device by calling the function cpp:func:spi_slave_initialize. Make sure to set the correct I/O pins in the struct bus_config. Set the unused signals to -1.
· Before initiating transactions, fill one or more spi_slave_transaction_t structs with the transaction parameters required. Either queue all transactions by calling the function spi_slave_queue_trans() and, at a later time, query the result by using the function spi_slave_get_trans_result(), or handle all requests individually by feeding them into spi_slave_transmit(). The latter two functions will be blocked until the Host has initiated and finished a transaction, causing the queued data to be sent and received.
· (Optional) To unload the SPI slave driver, call spi_slave_free().
Transaction Data and Master/Slave Length Mismatches
Normally, the data that needs to be transferred to or from a Device is read or written to a chunk of memory indicated by the rx_buffer and tx_buffer members of the spi_transaction_t structure. The SPI driver can be configured to use DMA for transfers, in which case these buffers must be allocated in DMA-capable memory using pvPortMallocCaps(size, MALLOC_CAP_DMA). The amount of data that the driver can read or write to the buffers is limited by the member spi_transaction_t::length. However, this member does not define the actual length of an SPI transaction. A transactionns length is determined by a Host which drives the clock and CS lines. The actual length of the transmission can be read only after a transaction is finished from the member spi_slave_transaction_t::trans_len. If the length of the transmission is greater than the buffer length, only the initial number of bits specified in the length member will be sent and received. In this case, trans_len is set to length instead of the actual transaction length. To meet the actual transaction length requirements, set length to a value greater than the maximum trans_len expected. If the transmission length is shorter than the buffer length, only the data equal to the length of the buffer will be transmitted.
Speed and Timing Considerations
Transaction Interval The ESP32-S3 SPI slave peripherals are designed as general purpose Devices controlled by a CPU. As opposed to dedicated slaves, CPU-based SPI Devices have a limited number of pre-defined registers. All transactions must be handled by the CPU, which means that the transfers and responses are not real-time, and there might be noticeable latency.

Espressif Systems

703

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

As a solution, a Devicens response rate can be doubled by using the functions spi_slave_queue_trans() and then spi_slave_get_trans_result() instead of using spi_slave_transmit().
You can also configure a GPIO pin through which the Device will signal to the Host when it is ready for a new transaction. A code example of this can be found in peripherals/spi_slave.

SCLK Frequency Requirements The SPI slaves are designed to operate at up to 60 MHz. The data cannot be recognized or received correctly if the clock is too fast or does not have a 50% duty cycle.

Restrictions and Known Issues
1. If DMA is enabled, the rx buffer should be word-aligned (starting from a 32-bit boundary and having a length of multiples of 4 bytes). Otherwise, DMA may write incorrectly or not in a boundary aligned manner. The driver reports an error if this condition is not satisfied. Also, a Host should write lengths that are multiples of 4 bytes. The data with inappropriate lengths will be discarded.

Application Example
The code example for Device/Host communication can be found in the peripherals/spi_slave directory of ESP-IDF examples.

API Reference
Header File · components/driver/include/driver/spi_slave.h

Functions

esp_err_t spi_slave_initialize(spi_host_device_t host, const spi_bus_config_t *bus_config,

const

spi_slave_interface_config_t

*slave_config,

spi_dma_chan_t dma_chan)

Initialize a SPI bus as a slave interface.

Warning SPI0/1 is not supported Warning If a DMA channel is selected, any transmit and receive buffer used should be allocated in DMA-
capable memory. Warning The ISR of SPI is always executed on the core which calls this function. Never starve the ISR on
this core or the SPI transactions will not be handled. Return
· ESP_ERR_INVALID_ARG if configuration is invalid · ESP_ERR_INVALID_STATE if host already is in use · ESP_ERR_NOT_FOUND if there is no available DMA channel · ESP_ERR_NO_MEM if out of memory · ESP_OK on success Parameters · host: SPI peripheral to use as a SPI slave interface · bus_config: Pointer to a spi_bus_config_t struct specifying how the host should be initialized · slave_config: Pointer to a spi_slave_interface_config_t struct specifying the details for the slave
interface · dma_chan: - Selecting a DMA channel for an SPI bus allows transactions on the bus with size only
limited by the amount of internal memory. ­ Selecting SPI_DMA_DISABLED limits the size of transactions. ­ Set to SPI_DMA_DISABLED if only the SPI flash uses this bus. ­ Set to SPI_DMA_CH_AUTO to let the driver to allocate the DMA channel.

Espressif Systems

704

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t spi_slave_free(spi_host_device_t host) Free a SPI bus claimed as a SPI slave interface.

Return · ESP_ERR_INVALID_ARG if parameter is invalid · ESP_ERR_INVALID_STATE if not all devices on the bus are freed · ESP_OK on success
Parameters · host: SPI peripheral to free

esp_err_t spi_slave_queue_trans(spi_host_device_t host, const spi_slave_transaction_t
*trans_desc, TickType_t ticks_to_wait) Queue a SPI transaction for execution.

Queues a SPI transaction to be executed by this slave device. (The transaction queue size was specified when the slave device was initialised via spi_slave_initialize.) This function may block if the queue is full (depending on the ticks_to_wait parameter). No SPI operation is directly initiated by this function, the next queued transaction will happen when the master initiates a SPI transaction by pulling down CS and sending out clock signals.

This function hands over ownership of the buffers in trans_desc to the SPI slave driver; the application is not to access this memory until spi_slave_queue_trans is called to hand ownership back to the application.

Return · ESP_ERR_INVALID_ARG if parameter is invalid · ESP_OK on success
Parameters · host: SPI peripheral that is acting as a slave · trans_desc: Description of transaction to execute. Not const because we may want to write status back into the transaction description. · ticks_to_wait: Ticks to wait until therens room in the queue; use portMAX_DELAY to never time out.

esp_err_t spi_slave_get_trans_result(spi_host_device_t host,

spi_slave_transaction_t

**trans_desc, TickType_t ticks_to_wait)

Get the result of a SPI transaction queued earlier.

This routine will wait until a transaction to the given device (queued earlier with spi_slave_queue_trans) has succesfully completed. It will then return the description of the completed transaction so software can inspect the result and e.g. free the memory or re-use the buffers.

It is mandatory to eventually use this function for any transaction queued by spi_slave_queue_trans.

Return · ESP_ERR_INVALID_ARG if parameter is invalid · ESP_OK on success
Parameters · host: SPI peripheral to that is acting as a slave · [out] trans_desc: Pointer to variable able to contain a pointer to the description of the transaction that is executed · ticks_to_wait: Ticks to wait until therens a returned item; use portMAX_DELAY to never time out.

esp_err_t spi_slave_transmit(spi_host_device_t host, spi_slave_transaction_t *trans_desc, Tick-

Do a SPI transaction.

Type_t ticks_to_wait)

Essentially does the same as spi_slave_queue_trans followed by spi_slave_get_trans_result. Do not use this when there is still a transaction queued that hasnnt been finalized using spi_slave_get_trans_result.

Return · ESP_ERR_INVALID_ARG if parameter is invalid · ESP_OK on success
Parameters · host: SPI peripheral to that is acting as a slave

Espressif Systems

705

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· trans_desc: Pointer to variable able to contain a pointer to the description of the transaction that is executed. Not const because we may want to write status back into the transaction description.
· ticks_to_wait: Ticks to wait until therens a returned item; use portMAX_DELAY to never time out.

Structures struct spi_slave_interface_config_t
This is a configuration for a SPI host acting as a slave device.

Public Members
int spics_io_num CS GPIO pin for this device.
uint32_t flags Bitwise OR of SPI_SLAVE_* flags.
int queue_size Transaction queue size. This sets how many transactions can be min the airn(queued using spi_slave_queue_trans but not yet finished using spi_slave_get_trans_result) at the same time.
uint8_t mode SPI mode, representing a pair of (CPOL, CPHA) configuration:
· 0: (0, 0) · 1: (0, 1) · 2: (1, 0) · 3: (1, 1)
slave_transaction_cb_t post_setup_cb Callback called after the SPI registers are loaded with new data.
This callback is called within interrupt context should be in IRAM for best performance, see oTransferring Speedpsection in the SPI Master documentation for full details. If not, the callback may crash during flash operation when the driver is initialized with ESP_INTR_FLAG_IRAM.
slave_transaction_cb_t post_trans_cb Callback called after a transaction is done.
This callback is called within interrupt context should be in IRAM for best performance, see oTransferring Speedpsection in the SPI Master documentation for full details. If not, the callback may crash during flash operation when the driver is initialized with ESP_INTR_FLAG_IRAM. struct spi_slave_transaction_t This structure describes one SPI transaction

Public Members
size_t length Total data length, in bits.
size_t trans_len Transaction data length, in bits.
const void *tx_buffer Pointer to transmit buffer, or NULL for no MOSI phase.
void *rx_buffer Pointer to receive buffer, or NULL for no MISO phase. When the DMA is anabled, must start at WORD boundary (rx_buffer%4==0), and has length of a multiple of 4 bytes.
void *user User-defined variable. Can be used to store eg transaction ID.

Espressif Systems

706

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Macros SPI_SLAVE_TXBIT_LSBFIRST
Transmit command/address/data LSB first instead of the default MSB first. SPI_SLAVE_RXBIT_LSBFIRST
Receive data LSB first instead of the default MSB first. SPI_SLAVE_BIT_LSBFIRST
Transmit and receive LSB first.
Type Definitions typedef struct spi_slave_transaction_t spi_slave_transaction_t typedef void (*slave_transaction_cb_t)(spi_slave_transaction_t *trans)
2.3.20 Touch Sensor
Introduction
A touch sensor system is built on a substrate which carries electrodes and relevant connections under a protective flat surface. When a user touches the surface, the capacitance variation is used to evaluate if the touch was valid. Touch sensor on ESP32-S3 can support up to 14 capacitive touch pads / GPIOs. The sensing pads can be arranged in different combinations (e.g., matrix, slider), so that a larger area or more points can be detected. The touch pad sensing process is under the control of a hardware-implemented finite-state machine (FSM) which is initiated by software or a dedicated hardware timer. For design, operation, and control registers of a touch sensor, see ESP32-S3 Technical Reference Manual > On-Chip Sensors and Analog Signal Processing [PDF]. In-depth design details of touch sensors and firmware development guidelines for ESP32-S3 are available in Touch Sensor Application Note.
Functionality Overview
Description of API is broken down into groups of functions to provide a quick overview of the following features: · Initialization of touch pad driver · Configuration of touch pad GPIO pins · Taking measurements · Adjusting parameters of measurements · Filtering measurements · Touch detection methods · Setting up interrupts to report touch detection · Waking up from Sleep mode on interrupt
For detailed description of a particular function, please go to Section API Reference. Practical implementation of this API is covered in Section Application Examples.
Initialization Before using a touch pad, you need to initialize the touch pad driver by calling the function touch_pad_init(). This function sets several .._DEFAULT driver parameters listed in API Reference under Macros. It also removes the information about which pads have been touched before, if any, and disables interrupts. If the driver is not required anymore, deinitialize it by calling touch_pad_deinit().
Configuration Enabling the touch sensor functionality for a particular GPIO is done with touch_pad_config().

Espressif Systems

707

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Use the function touch_pad_set_fsm_mode() to select if touch pad measurement (operated by FSM) should be started automatically by a hardware timer, or by software. If software mode is selected, use touch_pad_sw_start() to start the FSM.
Touch State Measurements The following function come in handy to read raw measurements from the sensor: · touch_pad_read_raw_data()
It can also be used, for example, to evaluate a particular touch pad design by checking the range of sensor readings when a pad is touched or released. This information can be then used to establish a touch threshold. For the demonstration of how to read the touch pad data, check the application example peripherals/touch_sensor/touch_sensor_v2/touch_pad_read.
Optimization of Measurements A touch sensor has several configurable parameters to match the characteristics of a particular touch pad design. For instance, to sense smaller capacity changes, it is possible to narrow down the reference voltage range within which the touch pads are charged / discharged. The high and low reference voltages are set using the function touch_pad_set_voltage(). Besides the ability to discern smaller capacity changes, a positive side effect is reduction of power consumption for low power applications. A likely negative effect is an increase in measurement noise. If the dynamic range of obtained readings is still satisfactory, then further reduction of power consumption might be done by reducing the measurement time with touch_pad_set_meas_time(). The following list summarizes available measurement parameters and corresponding msetnfunctions:
· Touch pad charge / discharge parameters: ­ voltage range: touch_pad_set_voltage() ­ speed (slope): touch_pad_set_cnt_mode()
· Measurement time: touch_pad_set_meas_time() Relationship between the voltage range (high / low reference voltages), speed (slope), and measurement time is shown in the figure below.

Fig. 16: Touch pad - relationship between measurement parameters
The last chart Output represents the touch sensor reading, i.e., the count of pulses collected within the measurement time. All functions are provided in pairs to set a specific parameter and to get the current parameterns value, e.g., touch_pad_set_voltage() and touch_pad_get_voltage().

Espressif Systems

708

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Filtering of Measurements If measurements are noisy, you can filter them with provided API functions. The ESP32-S3ns touch functionality provide two sets of APIs for doing this. There is an internal touch channel that is not connected to any external GPIO. The measurements from this denoise pad can be used to filters out interference introduced on all channels, such as noise introduced by the power supply and external EMI. The denoise paramaters are set with the function touch_pad_denoise_set_config() and started by with touch_pad_denoise_enable() There is also a configurable hardware implemented IIR-filter (infinite impulse response). This IIRfilter is configured with the function touch_pad_filter_set_config() and enabled by calling touch_pad_filter_enable()
Touch Detection Touch detection is implemented in ESP32ns hardware based on the user-configured threshold and raw measurements executed by FSM. Use the functions touch_pad_get_status() to check which pads have been touched and touch_pad_clear_status() to clear the touch status information. Hardware touch detection can also be wired to interrupts. This is described in the next section. If measurements are noisy and capacity changes are small, hardware touch detection might be unreliable. To resolve this issue, instead of using hardware detection / provided interrupts, implement measurement filtering and perform touch detection in your own application. For sample implementation of both methods of touch detection, see peripherals/touch_sensor/touch_sensor_v2/touch_pad_interrupt.
Touch Triggered Interrupts Before enabling an interrupt on a touch detection, you should establish a touch detection threshold. Use the functions described in Touch State Measurements to read and display sensor measurements when a pad is touched and released. Apply a filter if measurements are noisy and relative capacity changes are small. Depending on your application and environment conditions, test the influence of temperature and power supply voltage changes on measured values. Once a detection threshold is established, it can be set during initialization with touch_pad_config() or at the runtime with touch_pad_set_thresh(). Finally, configure and manage interrupt calls using the following functions:
· touch_pad_isr_register() / touch_pad_isr_deregister() · touch_pad_intr_enable() / touch_pad_intr_disable() When interrupts are operational, you can obtain the information from which particular pad an interrupt came by invoking touch_pad_get_status() and clear the pad status with touch_pad_clear_status().
Application Examples
· Touch sensor read example: peripherals/touch_sensor/touch_sensor_v2/touch_pad_read. · Touch sensor interrupt example: peripherals/touch_sensor/touch_sensor_v2/touch_pad_interrupt.
API Reference
Header File · components/driver/esp32s3/include/driver/touch_sensor.h
Functions esp_err_t touch_pad_fsm_start(void)
Set touch sensor FSM start. Note Start FSM after the touch sensor FSM mode is set. Note Call this function will reset benchmark of all touch channels. Return
· ESP_OK on success

Espressif Systems

709

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t touch_pad_fsm_stop(void) Stop touch sensor FSM.
Return · ESP_OK on success
esp_err_t touch_pad_sw_start(void) Trigger a touch sensor measurement, only support in SW mode of FSM.
Return · ESP_OK on success
esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_times) Set touch sensor times of charge and discharge and sleep time. Excessive total time will slow down the touch response. Too small measurement time will not be sampled enough, resulting in inaccurate measurements.
Note The greater the duty cycle of the measurement time, the more system power is consumed. Return
· ESP_OK on success Parameters
· sleep_cycle: The touch sensor will sleep after each measurement. sleep_cycle decide the interval between each measurement. t_sleep = sleep_cycle / (RTC_SLOW_CLK frequency). The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function.
· meas_times: The times of charge and discharge in each measure process of touch channels. The timer frequency is 8Mhz. Range: 0 ~ 0xffff. Recommended typical value: Modify this value to make the measurement time around 1ms.
esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_times) Get touch sensor times of charge and discharge and sleep time.
Return · ESP_OK on success
Parameters · sleep_cycle: Pointer to accept sleep cycle number · meas_times: Pointer to accept measurement times count.
esp_err_t touch_pad_set_idle_channel_connect(touch_pad_conn_type_t type) Set connection type of touch channel in idle status. When a channel is in measurement mode, other initialized channels are in idle mode. The touch channel is generally adjacent to the trace, so the connection state of the idle channel affects the stability and sensitivity of the test channel. The CONN_HIGHZ(high resistance) setting increases the sensitivity of touch channels. The CONN_GND(grounding) setting increases the stability of touch channels.
Return · ESP_OK on success
Parameters · type: Select idle channel connect to high resistance state or ground.
esp_err_t touch_pad_get_idle_channel_connect(touch_pad_conn_type_t *type) Set connection type of touch channel in idle status. When a channel is in measurement mode, other initialized channels are in idle mode. The touch channel is generally adjacent to the trace, so the connection state of the idle channel affects the stability and sensitivity of the test channel. The CONN_HIGHZ(high resistance) setting increases the sensitivity of touch channels. The CONN_GND(grounding) setting increases the stability of touch channels.
Return · ESP_OK on success
Parameters · type: Pointer to connection type.
esp_err_t touch_pad_set_thresh(touch_pad_t touch_num, uint32_t threshold) Set the trigger threshold of touch sensor. The threshold determines the sensitivity of the touch sensor. The threshold is the original value of the trigger state minus the benchmark value.

Espressif Systems

710

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Note If set oTOUCH_PAD_THRESHOLD_MAXp, the touch is never be triggered. Return
· ESP_OK on success Parameters
· touch_num: touch pad index · threshold: threshold of touch sensor. Should be less than the max change value of touch.
esp_err_t touch_pad_get_thresh(touch_pad_t touch_num, uint32_t *threshold) Get touch sensor trigger threshold.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if argument is wrong
Parameters · touch_num: touch pad index · threshold: pointer to accept threshold
esp_err_t touch_pad_set_channel_mask(uint16_t enable_mask) Register touch channel into touch sensor scan group. The working mode of the touch sensor is cyclically scanned. This function will set the scan bits according to the given bitmask.
Note If set this mask, the FSM timer should be stop firsty. Note The touch sensor that in scan map, should be deinit GPIO function firstly by touch_pad_io_init. Return
· ESP_OK on success Parameters
· enable_mask: bitmask of touch sensor scan group. e.g. TOUCH_PAD_NUM14 -> BIT(14)
esp_err_t touch_pad_get_channel_mask(uint16_t *enable_mask) Get the touch sensor scan group bit mask.
Return · ESP_OK on success
Parameters · enable_mask: Pointer to bitmask of touch sensor scan group. e.g. TOUCH_PAD_NUM14 -> BIT(14)
esp_err_t touch_pad_clear_channel_mask(uint16_t enable_mask) Clear touch channel from touch sensor scan group. The working mode of the touch sensor is cyclically scanned. This function will clear the scan bits according to the given bitmask.
Note If clear all mask, the FSM timer should be stop firsty. Return
· ESP_OK on success Parameters
· enable_mask: bitmask of touch sensor scan group. e.g. TOUCH_PAD_NUM14 -> BIT(14)
esp_err_t touch_pad_config(touch_pad_t touch_num) Configure parameter for each touch channel.
Note Touch num 0 is denoise channel, please use touch_pad_denoise_enable to set denoise function Return
· ESP_OK Success · ESP_ERR_INVALID_ARG if argument wrong · ESP_FAIL if touch pad not initialized Parameters · touch_num: touch pad index
esp_err_t touch_pad_reset(void) Reset the FSM of touch module.
Note Call this function after touch_pad_fsm_stop. Return
· ESP_OK Success

Espressif Systems

711

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

touch_pad_t touch_pad_get_current_meas_channel(void) Get the current measure channel.
Note Should be called when touch sensor measurement is in cyclic scan mode. Return
· touch channel number
uint32_t touch_pad_read_intr_status_mask(void) Get the touch sensor interrupt status mask.
Return · touch interrupt bit
esp_err_t touch_pad_intr_enable(touch_pad_intr_mask_t int_mask) Enable touch sensor interrupt by bitmask.
Note This API can be called in ISR handler. Return
· ESP_OK on success Parameters
· int_mask: Pad mask to enable interrupts
esp_err_t touch_pad_intr_disable(touch_pad_intr_mask_t int_mask) Disable touch sensor interrupt by bitmask.
Note This API can be called in ISR handler. Return
· ESP_OK on success Parameters
· int_mask: Pad mask to disable interrupts
esp_err_t touch_pad_intr_clear(touch_pad_intr_mask_t int_mask) Clear touch sensor interrupt by bitmask.
Return · ESP_OK on success
Parameters · int_mask: Pad mask to clear interrupts
esp_err_t touch_pad_isr_register(intr_handler_t fn, void *arg, touch_pad_intr_mask_t intr_mask) Register touch-pad ISR. The handler will be attached to the same CPU core that this function is running on.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Arguments error · ESP_ERR_NO_MEM No memory
Parameters · fn: Pointer to ISR handler · arg: Parameter for ISR · intr_mask: Enable touch sensor interrupt handler by bitmask.
esp_err_t touch_pad_timeout_set(bool enable, uint32_t threshold) Enable/disable the timeout check and set timeout threshold for all touch sensor channels measurements. If enable: When the touch reading of a touch channel exceeds the measurement threshold, a timeout interrupt will be generated. If disable: the FSM does not check if the channel under measurement times out.
Note The threshold compared with touch readings. Note In order to avoid abnormal short circuit of some touch channels. This function should be turned on.
Ensure the normal operation of other touch channels. Return
· ESP_OK Success Parameters
· enable: true(default): Enable the timeout check; false: Disable the timeout check. · threshold: For all channels, the maximum value that will not be exceeded during normal oper-
ation.

Espressif Systems

712

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
esp_err_t touch_pad_timeout_resume(void) Call this interface after timeout to make the touch channel resume normal work. Point on the next channel to measure. If this API is not called, the touch FSM will stop the measurement after timeout interrupt.
Note Call this API after finishes the exception handling by user. Return
· ESP_OK Success
esp_err_t touch_pad_read_raw_data(touch_pad_t touch_num, uint32_t *raw_data) get raw data of touch sensor.
Note After the initialization is complete, the oraw_datapis max value. You need to wait for a measurement cycle before you can read the correct touch value.
Return · ESP_OK Success · ESP_FAIL Touch channel 0 havennt this parameter.
Parameters · touch_num: touch pad index · raw_data: pointer to accept touch sensor value
esp_err_t touch_pad_read_benchmark(touch_pad_t touch_num, uint32_t *benchmark) get benchmark of touch sensor.
Note After initialization, the benchmark value is the maximum during the first measurement period. Return
· ESP_OK Success · ESP_ERR_INVALID_ARG Touch channel 0 havennt this parameter. Parameters · touch_num: touch pad index · benchmark: pointer to accept touch sensor benchmark value
esp_err_t touch_pad_filter_read_smooth(touch_pad_t touch_num, uint32_t *smooth) Get smoothed data that obtained by filtering the raw data.
Parameters · touch_num: touch pad index · smooth: pointer to smoothed data
esp_err_t touch_pad_reset_benchmark(touch_pad_t touch_num) Force reset benchmark to raw data of touch sensor.
Return · ESP_OK Success
Parameters · touch_num: touch pad index ­ TOUCH_PAD_MAX Reset basaline of all channels
esp_err_t touch_pad_filter_set_config(const touch_filter_config_t *filter_info) set parameter of touch sensor filter and detection algorithm. For more details on the detection algorithm, please refer to the application documentation.
Return · ESP_OK Success
Parameters · filter_info: select filter type and threshold of detection algorithm
esp_err_t touch_pad_filter_get_config(touch_filter_config_t *filter_info) get parameter of touch sensor filter and detection algorithm. For more details on the detection algorithm, please refer to the application documentation.
Return · ESP_OK Success
Parameters · filter_info: select filter type and threshold of detection algorithm

Espressif Systems

713

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
esp_err_t touch_pad_filter_enable(void) enable touch sensor filter for detection algorithm. For more details on the detection algorithm, please refer to the application documentation.
Return · ESP_OK Success
esp_err_t touch_pad_filter_disable(void) disable touch sensor filter for detection algorithm. For more details on the detection algorithm, please refer to the application documentation.
Return · ESP_OK Success
esp_err_t touch_pad_denoise_set_config(const touch_pad_denoise_t *denoise) set parameter of denoise pad (TOUCH_PAD_NUM0). T0 is an internal channel that does not have a corresponding external GPIO. T0 will work simultaneously with the measured channel Tn. Finally, the actual measured value of Tn is the value after subtracting lower bits of T0. The noise reduction function filters out interference introduced simultaneously on all channels, such as noise introduced by power supplies and external EMI.
Return · ESP_OK Success
Parameters · denoise: parameter of denoise
esp_err_t touch_pad_denoise_get_config(touch_pad_denoise_t *denoise) get parameter of denoise pad (TOUCH_PAD_NUM0).
Return · ESP_OK Success
Parameters · denoise: Pointer to parameter of denoise
esp_err_t touch_pad_denoise_enable(void) enable denoise function. T0 is an internal channel that does not have a corresponding external GPIO. T0 will work simultaneously with the measured channel Tn. Finally, the actual measured value of Tn is the value after subtracting lower bits of T0. The noise reduction function filters out interference introduced simultaneously on all channels, such as noise introduced by power supplies and external EMI.
Return · ESP_OK Success
esp_err_t touch_pad_denoise_disable(void) disable denoise function.
Return · ESP_OK Success
esp_err_t touch_pad_denoise_read_data(uint32_t *data) Get denoise measure value (TOUCH_PAD_NUM0).
Return · ESP_OK Success
Parameters · data: Pointer to receive denoise value
esp_err_t touch_pad_waterproof_set_config(const touch_pad_waterproof_t *waterproof) set parameter of waterproof function.
The waterproof function includes a shielded channel (TOUCH_PAD_NUM14) and a guard channel.
Guard pad is used to detect the large area of water covering the touch panel.
(continues on next page)

Espressif Systems

714

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)
Shield pad is used to shield the influence of water droplets covering the touch panel.
It is generally designed as a grid and is placed around the touch buttons.

Return · ESP_OK Success
Parameters · waterproof: parameter of waterproof

esp_err_t touch_pad_waterproof_get_config(touch_pad_waterproof_t *waterproof) get parameter of waterproof function.

Return · ESP_OK Success
Parameters · waterproof: parameter of waterproof

esp_err_t touch_pad_waterproof_enable(void) Enable parameter of waterproof function. touch_pad_waterproof_set_config.

Should be called after function

Return · ESP_OK Success

esp_err_t touch_pad_waterproof_disable(void) Disable parameter of waterproof function.

Return · ESP_OK Success

esp_err_t touch_pad_proximity_enable(touch_pad_t touch_num, bool enabled) Enable/disable proximity function of touch channels. The proximity sensor measurement is the accumulation of touch channel measurements.

Note Supports up to three touch channels configured as proximity sensors. Return
· ESP_OK: Configured correctly. · ESP_ERR_INVALID_ARG: Touch channel number error. · ESP_ERR_NOT_SUPPORTED: Donnt support configured. Parameters · touch_num: touch pad index · enabled: true: enable the proximity function; false: disable the proximity function

esp_err_t touch_pad_proximity_set_count(touch_pad_t touch_num, uint32_t count) Set measure count of proximity channel. The proximity sensor measurement is the accumulation of touch channel measurements.

Note All proximity channels use the same count value. So please pass the parameter TOUCH_PAD_MAX. Return
· ESP_OK: Configured correctly. · ESP_ERR_INVALID_ARG: Touch channel number error. Parameters · touch_num: Touch pad index. In this version, pass the parameter TOUCH_PAD_MAX. · count: The cumulative times of measurements for proximity pad. Range: 0 ~ 255.

esp_err_t touch_pad_proximity_get_count(touch_pad_t touch_num, uint32_t *count) Get measure count of proximity channel. The proximity sensor measurement is the accumulation of touch channel measurements.

Note All proximity channels use the same count value. So please pass the parameter TOUCH_PAD_MAX. Return
· ESP_OK: Configured correctly. · ESP_ERR_INVALID_ARG: Touch channel number error.

Espressif Systems

715

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Parameters · touch_num: Touch pad index. In this version, pass the parameter TOUCH_PAD_MAX. · count: The cumulative times of measurements for proximity pad. Range: 0 ~ 255.
esp_err_t touch_pad_proximity_get_data(touch_pad_t touch_num, uint32_t *measure_out) Get the accumulated measurement of the proximity sensor. The proximity sensor measurement is the accumulation of touch channel measurements.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Touch num is not proximity
Parameters · touch_num: touch pad index · measure_out: If the accumulation process does not end, the measure_out is the process value.
esp_err_t touch_pad_sleep_channel_get_info(touch_pad_sleep_channel_t *slp_config) Get parameter of touch sensor sleep channel. The touch sensor can works in sleep mode to wake up sleep.
Note After the sleep channel is configured, Please use special functions for sleep channel. e.g. The user should uses touch_pad_sleep_channel_read_data instead of touch_pad_read_raw_data to obtain the sleep channel reading.
Return · ESP_OK Success
Parameters · slp_config: touch sleep pad config.
esp_err_t touch_pad_sleep_channel_enable(touch_pad_t pad_num, bool enable) Enable/Disable sleep channel function for touch sensor. The touch sensor can works in sleep mode to wake up sleep.
Note ESP32S2 only support one sleep channel. Note After the sleep channel is configured, Please use special functions for sleep channel. e.g. The user should
uses touch_pad_sleep_channel_read_data instead of touch_pad_read_raw_data to obtain the sleep channel reading. Return
· ESP_OK Success Parameters
· pad_num: Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode.
· enable: true: enable sleep pad for touch sensor; false: disable sleep pad for touch sensor;
esp_err_t touch_pad_sleep_channel_enable_proximity(touch_pad_t pad_num, bool enable) Enable/Disable proximity function for sleep channel. The touch sensor can works in sleep mode to wake up sleep.
Note ESP32S2 only support one sleep channel. Return
· ESP_OK Success Parameters
· pad_num: Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode.
· enable: true: enable proximity for sleep channel; false: disable proximity for sleep channel;
esp_err_t touch_pad_sleep_set_threshold(touch_pad_t pad_num, uint32_t touch_thres) Set the trigger threshold of touch sensor in deep sleep. The threshold determines the sensitivity of the touch sensor.
Note In general, the touch threshold during sleep can use the threshold parameter parameters before sleep. Return
· ESP_OK Success Parameters

Espressif Systems

716

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· pad_num: Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode.
· touch_thres: touch sleep pad threshold

esp_err_t touch_pad_sleep_get_threshold(touch_pad_t pad_num, uint32_t *touch_thres) Get the trigger threshold of touch sensor in deep sleep. The threshold determines the sensitivity of the touch sensor.

Note In general, the touch threshold during sleep can use the threshold parameter parameters before sleep. Return
· ESP_OK Success Parameters
· pad_num: Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode.
· touch_thres: touch sleep pad threshold

esp_err_t touch_pad_sleep_channel_read_benchmark(touch_pad_t pad_num,

Read benchmark of touch sensor sleep channel.

*benchmark)

uint32_t

Return · ESP_OK Success · ESP_ERR_INVALID_ARG parameter is NULL
Parameters · pad_num: Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. · benchmark: pointer to accept touch sensor benchmark value

esp_err_t touch_pad_sleep_channel_read_smooth(touch_pad_t pad_num,

uint32_t

*smooth_data) Read smoothed data of touch sensor sleep channel. Smoothed data is filtered from the raw data.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG parameter is NULL
Parameters · pad_num: Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. · smooth_data: pointer to accept touch sensor smoothed data

esp_err_t touch_pad_sleep_channel_read_data(touch_pad_t pad_num, uint32_t *raw_data) Read raw data of touch sensor sleep channel.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG parameter is NULL
Parameters · pad_num: Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. · raw_data: pointer to accept touch sensor raw data

esp_err_t touch_pad_sleep_channel_reset_benchmark(void) Reset benchmark of touch sensor sleep channel.

Return · ESP_OK Success

esp_err_t touch_pad_sleep_channel_read_proximity_cnt(touch_pad_t pad_num, uint32_t *proximity_cnt)
Read proximity count of touch sensor sleep channel.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG parameter is NULL
Parameters

Espressif Systems

717

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· pad_num: Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode.
· proximity_cnt: pointer to accept touch sensor proximity count value

esp_err_t touch_pad_sleep_channel_set_work_time(uint16_t sleep_cycle,

uint16_t

meas_times) Change the operating frequency of touch pad in deep sleep state. Reducing the operating frequency can ef-

fectively reduce power consumption. If this function is not called, the working frequency of touch in the deep

sleep state is the same as that in the wake-up state.

Return · ESP_OK Success
Parameters · sleep_cycle: The touch sensor will sleep after each measurement. sleep_cycle decide the interval between each measurement. t_sleep = sleep_cycle / (RTC_SLOW_CLK frequency). The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function. · meas_times: The times of charge and discharge in each measure process of touch channels. The timer frequency is 8Mhz. Range: 0 ~ 0xffff. Recommended typical value: Modify this value to make the measurement time around 1ms.

Header File · components/driver/include/driver/touch_sensor_common.h

Functions esp_err_t touch_pad_init(void)
Initialize touch module.
Note If default parameter donnt match the usage scenario, it can be changed after this function. Return
· ESP_OK Success · ESP_ERR_NO_MEM Touch pad init error · ESP_ERR_NOT_SUPPORTED Touch pad is providing current to external XTAL esp_err_t touch_pad_deinit(void) Un-install touch pad driver.
Note After this function is called, other touch functions are prohibited from being called. Return
· ESP_OK Success · ESP_FAIL Touch pad driver not initialized
esp_err_t touch_pad_io_init(touch_pad_t touch_num) Initialize touch pad GPIO.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if argument is wrong
Parameters · touch_num: touch pad index
esp_err_t touch_pad_set_voltage(touch_high_volt_t refh, touch_low_volt_t refl, touch_volt_atten_t atten)
Set touch sensor high voltage threshold of chanrge. The touch sensor measures the channel capacitance value by charging and discharging the channel. So the high threshold should be less than the supply voltage.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if argument is wrong
Parameters · refh: the value of DREFH · refl: the value of DREFL

Espressif Systems

718

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· atten: the attenuation on DREFH

esp_err_t touch_pad_get_voltage(touch_high_volt_t *refh, touch_volt_atten_t *atten)
Get touch sensor reference voltage,.

touch_low_volt_t *refl,

Return · ESP_OK on success
Parameters · refh: pointer to accept DREFH value · refl: pointer to accept DREFL value · atten: pointer to accept the attenuation on DREFH

esp_err_t touch_pad_set_cnt_mode(touch_pad_t touch_num, touch_cnt_slope_t slope, touch_tie_opt_t opt)
Set touch sensor charge/discharge speed for each pad. If the slope is 0, the counter would always be zero. If the slope is 1, the charging and discharging would be slow, accordingly. If the slope is set 7, which is the maximum value, the charging and discharging would be fast.

Note The higher the charge and discharge current, the greater the immunity of the touch channel, but it will increase the system power consumption.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if argument is wrong
Parameters · touch_num: touch pad index · slope: touch pad charge/discharge speed · opt: the initial voltage

esp_err_t touch_pad_get_cnt_mode(touch_pad_t touch_num, touch_tie_opt_t *opt)
Get touch sensor charge/discharge speed for each pad.

touch_cnt_slope_t *slope,

Return · ESP_OK on success · ESP_ERR_INVALID_ARG if argument is wrong
Parameters · touch_num: touch pad index · slope: pointer to accept touch pad charge/discharge slope · opt: pointer to accept the initial voltage

esp_err_t touch_pad_isr_deregister(void (*fn))void * , void *argDeregister the handler previously registered using touch_pad_isr_handler_register.

Return · ESP_OK on success · ESP_ERR_INVALID_STATE if a handler matching both fn and arg isnnt registered
Parameters · fn: handler function to call (as passed to touch_pad_isr_handler_register) · arg: argument of the handler (as passed to touch_pad_isr_handler_register)

esp_err_t touch_pad_get_wakeup_status(touch_pad_t *pad_num) Get the touch pad which caused wakeup from deep sleep.

Return · ESP_OK Success · ESP_ERR_INVALID_ARG parameter is NULL
Parameters · pad_num: pointer to touch pad which caused wakeup

esp_err_t touch_pad_set_fsm_mode(touch_fsm_mode_t mode) Set touch sensor FSM mode, the test action can be triggered by the timer, as well as by the software.

Return · ESP_OK on success

Espressif Systems

719

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_ERR_INVALID_ARG if argument is wrong Parameters
· mode: FSM mode
esp_err_t touch_pad_get_fsm_mode(touch_fsm_mode_t *mode) Get touch sensor FSM mode.
Return · ESP_OK on success
Parameters · mode: pointer to accept FSM mode
esp_err_t touch_pad_clear_status(void) To clear the touch sensor channel active status.
Note The FSM automatically updates the touch sensor status. It is generally not necessary to call this API to clear the status.
Return · ESP_OK on success
uint32_t touch_pad_get_status(void) Get the touch sensor channel active status mask. The bit position represents the channel number. The 0/1 status of the bit represents the trigger status.
Return · The touch sensor status. e.g. Touch1 trigger status is status_mask & (BIT1).
bool touch_pad_meas_is_done(void) Check touch sensor measurement status.
Return · True measurement is under way · False measurement done
GPIO Lookup Macros Some useful macros can be used to specified the GPIO number of a touch pad channel, or vice versa. e.g.
1. TOUCH_PAD_NUM5_GPIO_NUM is the GPIO number of channel 5 (12); 2. TOUCH_PAD_GPIO4_CHANNEL is the channel number of GPIO 4 (channel 0).
Header File
· components/soc/esp32s3/include/soc/touch_sensor_channel.h
Macros TOUCH_PAD_GPIO1_CHANNEL TOUCH_PAD_NUM1_GPIO_NUM
TOUCH_PAD_GPIO2_CHANNEL
TOUCH_PAD_NUM2_GPIO_NUM
TOUCH_PAD_GPIO3_CHANNEL
TOUCH_PAD_NUM3_GPIO_NUM
TOUCH_PAD_GPIO4_CHANNEL
TOUCH_PAD_NUM4_GPIO_NUM
TOUCH_PAD_GPIO5_CHANNEL
TOUCH_PAD_NUM5_GPIO_NUM
TOUCH_PAD_GPIO6_CHANNEL

Espressif Systems

720

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
TOUCH_PAD_NUM6_GPIO_NUM TOUCH_PAD_GPIO7_CHANNEL TOUCH_PAD_NUM7_GPIO_NUM TOUCH_PAD_GPIO8_CHANNEL TOUCH_PAD_NUM8_GPIO_NUM TOUCH_PAD_GPIO9_CHANNEL TOUCH_PAD_NUM9_GPIO_NUM TOUCH_PAD_GPIO10_CHANNEL TOUCH_PAD_NUM10_GPIO_NUM TOUCH_PAD_GPIO11_CHANNEL TOUCH_PAD_NUM11_GPIO_NUM TOUCH_PAD_GPIO12_CHANNEL TOUCH_PAD_NUM12_GPIO_NUM TOUCH_PAD_GPIO13_CHANNEL TOUCH_PAD_NUM13_GPIO_NUM TOUCH_PAD_GPIO14_CHANNEL TOUCH_PAD_NUM14_GPIO_NUM
Header File · components/hal/include/hal/touch_sensor_types.h
Structures struct touch_pad_denoise
Touch sensor denoise configuration
Public Members
touch_pad_denoise_grade_t grade Select denoise range of denoise channel. Determined by measuring the noise amplitude of the denoise channel.
touch_pad_denoise_cap_t cap_level Select internal reference capacitance of denoise channel. Ensure that the denoise readings are closest to the readings of the channel being measured. Use touch_pad_denoise_read_data to get the reading of denoise channel. The equivalent capacitance of the shielded channel can be calculated from the reading of denoise channel.
struct touch_pad_waterproof Touch sensor waterproof configuration
Public Members
touch_pad_t guard_ring_pad Waterproof. Select touch channel use for guard pad. Guard pad is used to detect the large area of water covering the touch panel.

Espressif Systems

721

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
touch_pad_shield_driver_t shield_driver Waterproof. Shield channel drive capability configuration. Shield pad is used to shield the influence of water droplets covering the touch panel. When the waterproof function is enabled, Touch14 is set as shield channel by default. The larger the parasitic capacitance on the shielding channel, the higher the drive capability needs to be set. The equivalent capacitance of the shield channel can be estimated through the reading value of the denoise channel(Touch0).
struct touch_filter_config Touch sensor filter configuration
Public Members
touch_filter_mode_t mode Set filter mode. The input of the filter is the raw value of touch reading, and the output of the filter is involved in the judgment of the touch state.
uint32_t debounce_cnt Set debounce count, such as n. If the measured values continue to exceed the threshold for n+1 times, the touch sensor state changes. Range: 0 ~ 7
uint32_t noise_thr Noise threshold coefficient. Higher = More noise resistance. The actual noise should be less than (noise coefficient * touch threshold). Range: 0 ~ 3. The coefficient is 0: 4/8; 1: 3/8; 2: 2/8; 3: 1;
uint32_t jitter_step Set jitter filter step size. Range: 0 ~ 15
touch_smooth_mode_t smh_lvl Level of filter applied on the original data against large noise interference.
struct touch_pad_sleep_channel_t Touch sensor channel sleep configuration
Public Members
touch_pad_t touch_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. If clear the sleep channel, point this pad to TOUCH_PAD_NUM0
bool en_proximity enable proximity function for sleep pad
Macros TOUCH_PAD_BIT_MASK_ALL TOUCH_PAD_SLOPE_DEFAULT TOUCH_PAD_TIE_OPT_DEFAULT TOUCH_PAD_BIT_MASK_MAX TOUCH_PAD_HIGH_VOLTAGE_THRESHOLD TOUCH_PAD_LOW_VOLTAGE_THRESHOLD TOUCH_PAD_ATTEN_VOLTAGE_THRESHOLD TOUCH_PAD_IDLE_CH_CONNECT_DEFAULT TOUCH_PAD_THRESHOLD_MAX
If set touch threshold max value, The touch sensor cannt be in touched status

Espressif Systems

722

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
TOUCH_PAD_SLEEP_CYCLE_DEFAULT Excessive total time will slow down the touch response. Too small measurement time will not be sampled enough, resulting in inaccurate measurements.
Note The greater the duty cycle of the measurement time, the more system power is consumed. The number of sleep cycle in each measure process of touch channels. The timer frequency is RTC_SLOW_CLK (can be 150k or 32k depending on the options). Range: 0 ~ 0xffff
TOUCH_PAD_MEASURE_CYCLE_DEFAULT The times of charge and discharge in each measure process of touch channels. The timer frequency is 8Mhz. Recommended typical value: Modify this value to make the measurement time around 1ms. Range: 0 ~ 0xffff
TOUCH_PAD_INTR_MASK_ALL All touch interrupt type enable.
TOUCH_PROXIMITY_MEAS_NUM_MAX Touch sensor proximity detection configuration
TOUCH_DEBOUNCE_CNT_MAX
TOUCH_NOISE_THR_MAX
TOUCH_JITTER_STEP_MAX
Type Definitions typedef struct touch_pad_denoise touch_pad_denoise_t
Touch sensor denoise configuration typedef struct touch_pad_waterproof touch_pad_waterproof_t
Touch sensor waterproof configuration
typedef struct touch_filter_config touch_filter_config_t Touch sensor filter configuration
Enumerations enum touch_pad_t
Touch pad channel
Values:
TOUCH_PAD_NUM0 = 0 Touch pad channel 0 is GPIO4(ESP32)
TOUCH_PAD_NUM1 Touch pad channel 1 is GPIO0(ESP32) / GPIO1(ESP32-S2)
TOUCH_PAD_NUM2 Touch pad channel 2 is GPIO2(ESP32) / GPIO2(ESP32-S2)
TOUCH_PAD_NUM3 Touch pad channel 3 is GPIO15(ESP32) / GPIO3(ESP32-S2)
TOUCH_PAD_NUM4 Touch pad channel 4 is GPIO13(ESP32) / GPIO4(ESP32-S2)
TOUCH_PAD_NUM5 Touch pad channel 5 is GPIO12(ESP32) / GPIO5(ESP32-S2)
TOUCH_PAD_NUM6 Touch pad channel 6 is GPIO14(ESP32) / GPIO6(ESP32-S2)
TOUCH_PAD_NUM7 Touch pad channel 7 is GPIO27(ESP32) / GPIO7(ESP32-S2)
TOUCH_PAD_NUM8 Touch pad channel 8 is GPIO33(ESP32) / GPIO8(ESP32-S2)

Espressif Systems

723

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

TOUCH_PAD_NUM9 Touch pad channel 9 is GPIO32(ESP32) / GPIO9(ESP32-S2)
TOUCH_PAD_NUM10 Touch channel 10 is GPIO10(ESP32-S2)
TOUCH_PAD_NUM11 Touch channel 11 is GPIO11(ESP32-S2)
TOUCH_PAD_NUM12 Touch channel 12 is GPIO12(ESP32-S2)
TOUCH_PAD_NUM13 Touch channel 13 is GPIO13(ESP32-S2)
TOUCH_PAD_NUM14 Touch channel 14 is GPIO14(ESP32-S2)
TOUCH_PAD_MAX enum touch_high_volt_t
Touch sensor high reference voltage
Values:
TOUCH_HVOLT_KEEP = -1 Touch sensor high reference voltage, no change
TOUCH_HVOLT_2V4 = 0 Touch sensor high reference voltage, 2.4V
TOUCH_HVOLT_2V5 Touch sensor high reference voltage, 2.5V
TOUCH_HVOLT_2V6 Touch sensor high reference voltage, 2.6V
TOUCH_HVOLT_2V7 Touch sensor high reference voltage, 2.7V
TOUCH_HVOLT_MAX
enum touch_low_volt_t Touch sensor low reference voltage
Values:
TOUCH_LVOLT_KEEP = -1 Touch sensor low reference voltage, no change
TOUCH_LVOLT_0V5 = 0 Touch sensor low reference voltage, 0.5V
TOUCH_LVOLT_0V6 Touch sensor low reference voltage, 0.6V
TOUCH_LVOLT_0V7 Touch sensor low reference voltage, 0.7V
TOUCH_LVOLT_0V8 Touch sensor low reference voltage, 0.8V
TOUCH_LVOLT_MAX
enum touch_volt_atten_t Touch sensor high reference voltage attenuation
Values:
TOUCH_HVOLT_ATTEN_KEEP = -1 Touch sensor high reference voltage attenuation, no change

Espressif Systems

724

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
TOUCH_HVOLT_ATTEN_1V5 = 0 Touch sensor high reference voltage attenuation, 1.5V attenuation
TOUCH_HVOLT_ATTEN_1V Touch sensor high reference voltage attenuation, 1.0V attenuation
TOUCH_HVOLT_ATTEN_0V5 Touch sensor high reference voltage attenuation, 0.5V attenuation
TOUCH_HVOLT_ATTEN_0V Touch sensor high reference voltage attenuation, 0V attenuation
TOUCH_HVOLT_ATTEN_MAX
enum touch_cnt_slope_t Touch sensor charge/discharge speed
Values:
TOUCH_PAD_SLOPE_0 = 0 Touch sensor charge / discharge speed, always zero
TOUCH_PAD_SLOPE_1 = 1 Touch sensor charge / discharge speed, slowest
TOUCH_PAD_SLOPE_2 = 2 Touch sensor charge / discharge speed
TOUCH_PAD_SLOPE_3 = 3 Touch sensor charge / discharge speed
TOUCH_PAD_SLOPE_4 = 4 Touch sensor charge / discharge speed
TOUCH_PAD_SLOPE_5 = 5 Touch sensor charge / discharge speed
TOUCH_PAD_SLOPE_6 = 6 Touch sensor charge / discharge speed
TOUCH_PAD_SLOPE_7 = 7 Touch sensor charge / discharge speed, fast
TOUCH_PAD_SLOPE_MAX
enum touch_tie_opt_t Touch sensor initial charge level
Values:
TOUCH_PAD_TIE_OPT_LOW = 0 Initial level of charging voltage, low level
TOUCH_PAD_TIE_OPT_HIGH = 1 Initial level of charging voltage, high level
TOUCH_PAD_TIE_OPT_MAX
enum touch_fsm_mode_t Touch sensor FSM mode
Values:
TOUCH_FSM_MODE_TIMER = 0 To start touch FSM by timer
TOUCH_FSM_MODE_SW To start touch FSM by software trigger
TOUCH_FSM_MODE_MAX

Espressif Systems

725

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
enum touch_trigger_mode_t Values:
TOUCH_TRIGGER_BELOW = 0 Touch interrupt will happen if counter value is less than threshold.
TOUCH_TRIGGER_ABOVE = 1 Touch interrupt will happen if counter value is larger than threshold.
TOUCH_TRIGGER_MAX
enum touch_trigger_src_t Values:
TOUCH_TRIGGER_SOURCE_BOTH = 0 wakeup interrupt is generated if both SET1 and SET2 are otouchedp
TOUCH_TRIGGER_SOURCE_SET1 = 1 wakeup interrupt is generated if SET1 is otouchedp
TOUCH_TRIGGER_SOURCE_MAX
enum touch_pad_intr_mask_t Values:
TOUCH_PAD_INTR_MASK_DONE = BIT(0) Measurement done for one of the enabled channels.
TOUCH_PAD_INTR_MASK_ACTIVE = BIT(1) Active for one of the enabled channels.
TOUCH_PAD_INTR_MASK_INACTIVE = BIT(2) Inactive for one of the enabled channels.
TOUCH_PAD_INTR_MASK_SCAN_DONE = BIT(3) Measurement done for all the enabled channels.
TOUCH_PAD_INTR_MASK_TIMEOUT = BIT(4) Timeout for one of the enabled channels.
TOUCH_PAD_INTR_MASK_PROXI_MEAS_DONE = BIT(5) For proximity sensor, when the number of measurements reaches the set count of measurements, an interrupt will be generated.
enum touch_pad_denoise_grade_t Values:
TOUCH_PAD_DENOISE_BIT12 = 0 Denoise range is 12bit
TOUCH_PAD_DENOISE_BIT10 = 1 Denoise range is 10bit
TOUCH_PAD_DENOISE_BIT8 = 2 Denoise range is 8bit
TOUCH_PAD_DENOISE_BIT4 = 3 Denoise range is 4bit
TOUCH_PAD_DENOISE_MAX
enum touch_pad_denoise_cap_t Values:
TOUCH_PAD_DENOISE_CAP_L0 = 0 Denoise channel internal reference capacitance is 5pf
TOUCH_PAD_DENOISE_CAP_L1 = 1 Denoise channel internal reference capacitance is 6.4pf

Espressif Systems

726

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

TOUCH_PAD_DENOISE_CAP_L2 = 2 Denoise channel internal reference capacitance is 7.8pf
TOUCH_PAD_DENOISE_CAP_L3 = 3 Denoise channel internal reference capacitance is 9.2pf
TOUCH_PAD_DENOISE_CAP_L4 = 4 Denoise channel internal reference capacitance is 10.6pf
TOUCH_PAD_DENOISE_CAP_L5 = 5 Denoise channel internal reference capacitance is 12.0pf
TOUCH_PAD_DENOISE_CAP_L6 = 6 Denoise channel internal reference capacitance is 13.4pf
TOUCH_PAD_DENOISE_CAP_L7 = 7 Denoise channel internal reference capacitance is 14.8pf
TOUCH_PAD_DENOISE_CAP_MAX = 8
enum touch_pad_shield_driver_t Touch sensor shield channel drive capability level
Values:
TOUCH_PAD_SHIELD_DRV_L0 = 0 The max equivalent capacitance in shield channel is 40pf
TOUCH_PAD_SHIELD_DRV_L1 The max equivalent capacitance in shield channel is 80pf
TOUCH_PAD_SHIELD_DRV_L2 The max equivalent capacitance in shield channel is 120pf
TOUCH_PAD_SHIELD_DRV_L3 The max equivalent capacitance in shield channel is 160pf
TOUCH_PAD_SHIELD_DRV_L4 The max equivalent capacitance in shield channel is 200pf
TOUCH_PAD_SHIELD_DRV_L5 The max equivalent capacitance in shield channel is 240pf
TOUCH_PAD_SHIELD_DRV_L6 The max equivalent capacitance in shield channel is 280pf
TOUCH_PAD_SHIELD_DRV_L7 The max equivalent capacitance in shield channel is 320pf
TOUCH_PAD_SHIELD_DRV_MAX
enum touch_pad_conn_type_t Touch channel idle state configuration
Values:
TOUCH_PAD_CONN_HIGHZ = 0 Idle status of touch channel is high resistance state
TOUCH_PAD_CONN_GND = 1 Idle status of touch channel is ground connection
TOUCH_PAD_CONN_MAX
enum touch_filter_mode_t Touch channel IIR filter coefficient configuration.
Note On ESP32S2. There is an error in the IIR calculation. The magnitude of the error is twice the filter coefficient. So please select a smaller filter coefficient on the basis of meeting the filtering requirements. Recommended filter coefficient selection IIR_16.

Espressif Systems

727

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Values: TOUCH_PAD_FILTER_IIR_4 = 0
The filter mode is first-order IIR filter. The coefficient is 4. TOUCH_PAD_FILTER_IIR_8
The filter mode is first-order IIR filter. The coefficient is 8. TOUCH_PAD_FILTER_IIR_16
The filter mode is first-order IIR filter. The coefficient is 16 (Typical value). TOUCH_PAD_FILTER_IIR_32
The filter mode is first-order IIR filter. The coefficient is 32. TOUCH_PAD_FILTER_IIR_64
The filter mode is first-order IIR filter. The coefficient is 64. TOUCH_PAD_FILTER_IIR_128
The filter mode is first-order IIR filter. The coefficient is 128. TOUCH_PAD_FILTER_IIR_256
The filter mode is first-order IIR filter. The coefficient is 256. TOUCH_PAD_FILTER_JITTER
The filter mode is jitter filter TOUCH_PAD_FILTER_MAX enum touch_smooth_mode_t Level of filter applied on the original data against large noise interference. Note On ESP32S2. There is an error in the IIR calculation. The magnitude of the error is twice the filter
coefficient. So please select a smaller filter coefficient on the basis of meeting the filtering requirements. Recommended filter coefficient selection IIR_2. Values: TOUCH_PAD_SMOOTH_OFF = 0 No filtering of raw data. TOUCH_PAD_SMOOTH_IIR_2 = 1 Filter the raw data. The coefficient is 2 (Typical value). TOUCH_PAD_SMOOTH_IIR_4 = 2 Filter the raw data. The coefficient is 4. TOUCH_PAD_SMOOTH_IIR_8 = 3 Filter the raw data. The coefficient is 8. TOUCH_PAD_SMOOTH_MAX
2.3.21 Two-Wire Automotive Interface (TWAI)
Overview
The Two-Wire Automotive Interface (TWAI) is a real-time serial communication protocol suited for automotive and industrial applications. It is compatible with ISO11898-1 Classical frames, thus can support Standard Frame Format (11-bit ID) and Extended Frame Format (29-bit ID). The ESP32-S3ns peripherals contains a TWAI controller that can be configured to communicate on a TWAI bus via an external transceiver.
Warning: The TWAI controller is not compatible with ISO11898-1 FD Format frames, and will interpret such frames as errors.
This programming guide is split into the following sections:

Espressif Systems

728

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
1. TWAI Protocol Summary 2. Signals Lines and Transceiver 3. Driver Configuration 4. Driver Operation 5. Examples
TWAI Protocol Summary
The TWAI is a multi-master, multi-cast, asynchronous, serial communication protocol. TWAI also supports error detection and signalling, and inbuilt message prioritization.
Multi-master: Any node on the bus can initiate the transfer of a message.
Multi-cast: When a node transmits a message, all nodes on the bus will receive the message (i.e., broadcast) thus ensuring data consistency across all nodes. However, some nodes can selectively choose which messages to accept via the use of acceptance filtering (multi-cast).
Asynchronous: The bus does not contain a clock signal. All nodes on the bus operate at the same bit rate and synchronize using the edges of the bits transmitted on the bus.
Error Detection and Signalling: Every node will constantly monitor the bus. When any node detects an error, it will signal the detection by transmitting an error frame. Other nodes will receive the error frame and transmit their own error frames in response. This will result in an error detection being propagated to all nodes on the bus.
Message Priorities: Messages contain an ID field. If two or more nodes attempt to transmit simultaneously, the node transmitting the message with the lower ID value will win arbitration of the bus. All other nodes will become receivers ensuring that there is at most one transmitter at any time.
TWAI Messages TWAI Messages are split into Data Frames and Remote Frames. Data Frames are used to deliver a data payload to other nodes, whereas a Remote Frame is used to request a Data Frame from other nodes (other nodes can optionally respond with a Data Frame). Data and Remote Frames have two frame formats known as Extended Frame and Standard Frame which contain a 29-bit ID and an 11-bit ID respectively. A TWAI message consists of the following fields:
· 29-bit or 11-bit ID: Determines the priority of the message (lower value has higher priority). · Data Length Code (DLC) between 0 to 8: Indicates the size (in bytes) of the data payload for a Data Frame,
or the amount of data to request for a Remote Frame. · Up to 8 bytes of data for a Data Frame (should match DLC).
Error States and Counters The TWAI protocol implements a feature known as ofault confinementpwhere a persistently erroneous node will eventually eliminate itself form the bus. This is implemented by requiring every node to maintain two internal error counters known as the Transmit Error Counter (TEC) and the Receive Error Counter (REC). The two error counters are incremented and decremented according to a set of rules (where the counters increase on an error, and decrease on a successful message transmission/reception). The values of the counters are used to determine a nodens error state, namely Error Active, Error Passive, and Bus-Off.
Error Active: A node is Error Active when both TEC and REC are less than 128 and indicates that the node is operating normally. Error Active nodes are allowed to participate in bus communications, and will actively signal the detection of any errors by automatically transmitting an Active Error Flag over the bus.
Error Passive: A node is Error Passive when either the TEC or REC becomes greater than or equal to 128. Error Passive nodes are still able to take part in bus communications, but will instead transmit a Passive Error Flag upon detection of an error.
Bus-Off: A node becomes Bus-Off when the TEC becomes greater than or equal to 256. A Bus-Off node is unable influence the bus in any manner (essentially disconnected from the bus) thus eliminating itself from the bus. A node will remain in the Bus-Off state until it undergoes bus-off recovery.

Espressif Systems

729

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Signals Lines and Transceiver
The TWAI controller does not contain a integrated transceiver. Therefore, to connect the TWAI controller to a TWAI bus, an external transceiver is required. The type of external transceiver used should depend on the applicationn s physical layer specification (e.g. using SN65HVD23x transceivers for ISO 11898-2 compatibility). The TWAI controllerns interface consists of 4 signal lines known as TX, RX, BUS-OFF, and CLKOUT. These four signal lines can be routed through the GPIO Matrix to the ESP32-S3ns GPIO pads.

Fig. 17: Signal lines of the TWAI controller
TX and RX: The TX and RX signal lines are required to interface with an external transceiver. Both signal lines represent/interpret a dominant bit as a low logic level (0V), and a recessive bit as a high logic level (3.3V). BUS-OFF: The BUS-OFF signal line is optional and is set to a low logic level (0V) whenever the TWAI controller reaches a bus-off state. The BUS-OFF signal line is set to a high logic level (3.3V) otherwise. CLKOUT: The CLKOUT signal line is optional and outputs a prescaled version of the controllerns source clock (APB Clock).
Note: An external transceiver must internally loopback the TX to RX such that a change in logic level to the TX signal line can be observed on the RX line. Failing to do so will cause the TWAI controller to interpret differences in logic levels between the two signal lines as a loss in arbitration or a bit error.

Driver Configuration
This section covers how to configure the TWAI driver.
Operating Modes The TWAI driver supports the following modes of operations: Normal Mode: The normal operating mode allows the TWAI controller to take part in bus activities such as transmitting and receiving messages/error frames. Acknowledgement from another node is required when transmitting a message. No Ack Mode: The No Acknowledgement mode is similar to normal mode, however acknowledgements are not required for a message transmission to be considered successful. This mode is useful when self testing the TWAI controller (loopback of transmissions).

Espressif Systems

730

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Listen Only Mode: This mode will prevent the TWAI controller from influencing the bus. Therefore, transmission of messages/acknowledgement/error frames will be disabled. However the TWAI controller will still be able to receive messages but will not acknowledge the message. This mode is suited for bus monitor applications.

Alerts The TWAI driver contains an alert feature that is used to notify the application layer of certain TWAI controller or TWAI bus events. Alerts are selectively enabled when the TWAI driver is installed, but can be reconfigured during runtime by calling twai_reconfigure_alerts(). The application can then wait for any enabled alerts to occur by calling twai_read_alerts(). The TWAI driver supports the following alerts:

Table 5: TWAI Driver Alerts

Alert Flag

Description

TWAI_ALERT_TX_IDLE

No more messages queued for transmission

TWAI_ALERT_TX_SUCCESS

The previous transmission was successful

TWAI_ALERT_RX_DATA

A frame has been received and added to the RX queue

TWAI_ALERT_BELOW_ERR_WARN

Both error counters have dropped below error warning limit

TWAI_ALERT_ERR_ACTIVE

TWAI controller has become error active

TWAI_ALERT_RECOVERY_IN_PROGRESSTWAI controller is undergoing bus recovery

TWAI_ALERT_BUS_RECOVERED

TWAI controller has successfully completed bus recovery

TWAI_ALERT_ARB_LOST

The previous transmission lost arbitration

TWAI_ALERT_ABOVE_ERR_WARN

One of the error counters have exceeded the error warning limit

TWAI_ALERT_BUS_ERROR

A (Bit, Stuff, CRC, Form, ACK) error has occurred on the bus

TWAI_ALERT_TX_FAILED

The previous transmission has failed

TWAI_ALERT_RX_QUEUE_FULL

The RX queue is full causing a received frame to be lost

TWAI_ALERT_ERR_PASS

TWAI controller has become error passive

TWAI_ALERT_BUS_OFF

Bus-off condition occurred. TWAI controller can no longer influ-

ence bus

Note: The TWAI controllerns error warning limit is used to preemptively warn the application of bus errors before the error passive state is reached. By default, the TWAI driver sets the error warning limit to 96. The TWAI_ALERT_ABOVE_ERR_WARN is raised when the TEC or REC becomes larger then or equal to the error warning limit. The TWAI_ALERT_BELOW_ERR_WARN is raised when both TEC and REC return back to values below 96.

Note: When enabling alerts, the TWAI_ALERT_AND_LOG flag can be used to cause the TWAI driver to log any raised alerts to UART. However, alert logging is disabled and TWAI_ALERT_AND_LOG if the CONFIG_TWAI_ISR_IN_IRAM option is enabled (see Placing ISR into IRAM).

Note: The TWAI_ALERT_ALL and TWAI_ALERT_NONE macros can also be used to enable/disable all alerts during configuration/reconfiguration.

Bit Timing The operating bit rate of the TWAI driver is configured using the twai_timing_config_t structure. The period of each bit is made up of multiple time quanta, and the period of a time quantum is determined by a prescaled version of the TWAI controllerns source clock. A single bit contains the following segments in the following order:
1. The Synchronization Segment consists of a single time quantum 2. Timing Segment 1 consists of 1 to 16 time quanta before sample point 3. Timing Segment 2 consists of 1 to 8 time quanta after sample point
The Baudrate Prescaler is used to determine the period of each time quantum by dividing the TWAI controllerns source clock (80 MHz APB clock). On the ESP32-S3, the brp can be any even number from 2 to 128.

Espressif Systems

731

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Fig. 18: Bit timing configuration for 500kbit/s given BRP = 8
The sample point of a bit is located on the intersection of Timing Segment 1 and 2. Enabling Triple Sampling will cause 3 time quanta to be sampled per bit instead of 1 (extra samples are located at the tail end of Timing Segment 1).
The Synchronization Jump Width is used to determine the maximum number of time quanta a single bit time can be lengthened/shortened for synchronization purposes. sjw can range from 1 to 4.
Note: Multiple combinations of brp, tseg_1, tseg_2, and sjw can achieve the same bit rate. Users should tune these values to the physical characteristics of their bus by taking into account factors such as propagation delay, node information processing time, and phase errors.
Bit timing macro initializers are also available for commonly used bit rates. The following macro initializers are provided by the TWAI driver.
· TWAI_TIMING_CONFIG_1MBITS() · TWAI_TIMING_CONFIG_800KBITS() · TWAI_TIMING_CONFIG_500KBITS() · TWAI_TIMING_CONFIG_250KBITS() · TWAI_TIMING_CONFIG_125KBITS() · TWAI_TIMING_CONFIG_100KBITS() · TWAI_TIMING_CONFIG_50KBITS() · TWAI_TIMING_CONFIG_25KBITS() · TWAI_TIMING_CONFIG_20KBITS() · TWAI_TIMING_CONFIG_16KBITS() · TWAI_TIMING_CONFIG_12_5KBITS() · TWAI_TIMING_CONFIG_10KBITS() · TWAI_TIMING_CONFIG_5KBITS() · TWAI_TIMING_CONFIG_1KBITS()
Acceptance Filter The TWAI controller contains a hardware acceptance filter which can be used to filter messages of a particular ID. A node that filters out a message will not receive the message, but will still acknowledge it. Acceptance filters can make a node more efficient by filtering out messages sent over the bus that are irrelevant to the node. The acceptance filter is configured using two 32-bit values within twai_filter_config_t known as the acceptance code and the acceptance mask.
The acceptance code specifies the bit sequence which a messagens ID, RTR, and data bytes must match in order for the message to be received by the TWAI controller. The acceptance mask is a bit sequence specifying which bits of the acceptance code can be ignored. This allows for a messages of different IDs to be accepted by a single acceptance code.
The acceptance filter can be used under Single or Dual Filter Mode. Single Filter Mode will use the acceptance code and mask to define a single filter. This allows for the first two data bytes of a standard frame to be filtered, or the entirety of an extended framens 29-bit ID. The following diagram illustrates how the 32-bit acceptance code and mask will be interpreted under Single Filter Mode (Note: The yellow and blue fields represent standard and extended frame formats respectively).
Dual Filter Mode will use the acceptance code and mask to define two separate filters allowing for increased flexibility of IDns to accept, but does not allow for all 29-bits of an extended ID to be filtered. The following diagram

Espressif Systems

732

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Fig. 19: Bit layout of single filter mode (Right side MSBit)
illustrates how the 32-bit acceptance code and mask will be interpreted under Dual Filter Mode (Note: The yellow and blue fields represent standard and extended frame formats respectively).
Fig. 20: Bit layout of dual filter mode (Right side MSBit)
Disabling TX Queue The TX queue can be disabled during configuration by setting the tx_queue_len member of twai_general_config_t to 0. This will allow applications that do not require message transmission to save a small amount of memory when using the TWAI driver.
Placing ISR into IRAM The TWAI driverns ISR (Interrupt Service Routine) can be placed into IRAM so that the ISR can still run whilst the cache is disabled. Placing the ISR into IRAM may be necessary to maintain the TWAI driverns functionality during lengthy cache disabling operations (such as SPI Flash writes, OTA updates etc). Whilst the cache is disabled, the ISR will continue to:
· Read received messages from the RX buffer and place them into the driverns RX queue. · Load messages pending transmission from the driverns TX queue and write them into the TX buffer. To place the TWAI driverns ISR, users must do the following: · Enable the CONFIG_TWAI_ISR_IN_IRAM option using idf.py menuconfig. · When calling twai_driver_install(), the intr_flags member of twai_general_config_t
should set the ESP_INTR_FLAG_IRAM set.
Note: When the CONFIG_TWAI_ISR_IN_IRAM option is enabled, the TWAI driver will no longer log any alerts (i.e., the TWAI_ALERT_AND_LOG flag will not have any effect).
Driver Operation The TWAI driver is designed with distinct states and strict rules regarding the functions or conditions that trigger a state transition. The following diagram illustrates the various states and their transitions.

Espressif Systems

733

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Fig. 21: State transition diagram of the TWAI driver (see table below)

Label A B C D E F G H

Transition Uninstalled -> Stopped Stopped -> Uninstalled Stopped -> Running Running -> Stopped Running -> Bus-Off Bus-Off -> Uninstalled Bus-Off -> Recovering Recovering -> Stopped

Action/Condition twai_driver_install() twai_driver_uninstall() twai_start() twai_stop() Transmit Error Counter >= 256 twai_driver_uninstall() twai_initiate_recovery() 128 occurrences of 11 consecutive recessive bits.

Driver States Uninstalled: In the uninstalled state, no memory is allocated for the driver and the TWAI controller is powered OFF.
Stopped: In this state, the TWAI controller is powered ON and the TWAI driver has been installed. However the TWAI controller will be unable to take part in any bus activities such as transmitting, receiving, or acknowledging messages.
Running: In the running state, the TWAI controller is able to take part in bus activities. Therefore messages can be transmitted/received/acknowledged. Furthermore the TWAI controller will be able to transmit error frames upon detection of errors on the bus.
Bus-Off: The bus-off state is automatically entered when the TWAI controllerns Transmit Error Counter becomes greater than or equal to 256. The bus-off state indicates the occurrence of severe errors on the bus or in the TWAI controller. Whilst in the bus-off state, the TWAI controller will be unable to take part in any bus activities. To exit the bus-off state, the TWAI controller must undergo the bus recovery process.
Recovering: The recovering state is entered when the TWAI controller undergoes bus recovery. The TWAI controller/TWAI driver will remain in the recovering state until the 128 occurrences of 11 consecutive recessive bits is observed on the bus.
Message Fields and Flags The TWAI driver distinguishes different types of messages by using the various bit field members of the twai_message_t structure. These bit field members determine whether a message is in standard or extended format, a remote frame, and the type of transmission to use when transmitting such a message.
These bit field members can also be toggled using the the flags member of twai_message_t and the following message flags:

Espressif Systems

734

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Message Flag

Description

TWAI_MSG_FLAG_EXTD

Message is in Extended Frame Format (29bit ID)

TWAI_MSG_FLAG_RTR

Message is a Remote Frame (Remote Transmission Request)

TWAI_MSG_FLAG_SS

Transmit message using Single Shot Transmission (Message will not be retrans-

mitted upon error or loss of arbitration). Unused for received message.

TWAI_MSG_FLAG_SELF

Transmit message using Self Reception Request (Transmitted message will also

received by the same node). Unused for received message.

TWAI_MSG_FLAG_DLC_NON_CMOMesPsagens Data length code is larger than 8. This will break compliance with

TWAI

TWAI_MSG_FLAG_NONE

Clears all bit fields. Equivalent to a Standard Frame Format (11bit ID) Data

Frame.

Examples
Configuration & Installation The following code snippet demonstrates how to configure, install, and start the TWAI driver via the use of the various configuration structures, macro initializers, the twai_driver_install() function, and the twai_start() function.
#include "driver/gpio.h" #include "driver/twai.h"
void app_main() {
//Initialize configuration structures using macro initializers twai_general_config_t g_config = TWAI_GENERAL_CONFIG_DEFAULT(GPIO_NUM_21, GPIO_ NUM_22, TWAI_MODE_NORMAL); twai_timing_config_t t_config = TWAI_TIMING_CONFIG_500KBITS(); twai_filter_config_t f_config = TWAI_FILTER_CONFIG_ACCEPT_ALL();
//Install TWAI driver if (twai_driver_install(&g_config, &t_config, &f_config) == ESP_OK) {
printf("Driver installed\n"); } else {
printf("Failed to install driver\n"); return; }
//Start TWAI driver if (twai_start() == ESP_OK) {
printf("Driver started\n"); } else {
printf("Failed to start driver\n"); return; }
...
}
The usage of macro initializers is not mandatory and each of the configuration structures can be manually.

Message Transmission The following code snippet demonstrates how to transmit a message via the usage of the twai_message_t type and twai_transmit() function. #include "driver/twai.h"
...
(continues on next page)

Espressif Systems

735

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

//Configure message to transmit twai_message_t message; message.identifier = 0xAAAA; message.extd = 1; message.data_length_code = 4; for (int i = 0; i < 4; i++) {
message.data[i] = 0; }
//Queue message for transmission if (twai_transmit(&message, pdMS_TO_TICKS(1000)) == ESP_OK) {
printf("Message queued for transmission\n"); } else {
printf("Failed to queue message for transmission\n"); }

(continued from previous page)

Message Reception The following code snippet demonstrates how to receive a message via the usage of the twai_message_t type and twai_receive() function.
#include "driver/twai.h"
...
//Wait for message to be received twai_message_t message; if (twai_receive(&message, pdMS_TO_TICKS(10000)) == ESP_OK) {
printf("Message received\n"); } else {
printf("Failed to receive message\n"); return; }
//Process received message if (message.extd) {
printf("Message is in Extended Format\n"); } else {
printf("Message is in Standard Format\n"); } printf("ID is %d\n", message.identifier); if (!(message.rtr)) {
for (int i = 0; i < message.data_length_code; i++) { printf("Data byte %d = %d\n", i, message.data[i]);
} }

Reconfiguring and Reading Alerts The following code snippet demonstrates how to reconfigure and read TWAI driver alerts via the use of the twai_reconfigure_alerts() and twai_read_alerts() functions.
#include "driver/twai.h"
...
//Reconfigure alerts to detect Error Passive and Bus-Off error states uint32_t alerts_to_enable = TWAI_ALERT_ERR_PASS | TWAI_ALERT_BUS_OFF; if (twai_reconfigure_alerts(alerts_to_enable, NULL) == ESP_OK) {
printf("Alerts reconfigured\n"); } else {
printf("Failed to reconfigure alerts"); (continues on next page)

Espressif Systems

736

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

}
//Block indefinitely until an alert occurs uint32_t alerts_triggered; twai_read_alerts(&alerts_triggered, portMAX_DELAY);

(continued from previous page)

Stop and Uninstall The following code demonstrates how to stop and uninstall the TWAI driver via the use of the twai_stop() and twai_driver_uninstall() functions.
#include "driver/twai.h"
...
//Stop the TWAI driver if (twai_stop() == ESP_OK) {
printf("Driver stopped\n"); } else {
printf("Failed to stop driver\n"); return; }
//Uninstall the TWAI driver if (twai_driver_uninstall() == ESP_OK) {
printf("Driver uninstalled\n"); } else {
printf("Failed to uninstall driver\n"); return; }

Multiple ID Filter Configuration The acceptance mask in twai_filter_config_t can be configured such that two or more IDs will be accepted for a single filter. For a particular filter to accept multiple IDs, the conflicting bit positions amongst the IDs must be set in the acceptance mask. The acceptance code can be set to any one of the IDs.
The following example shows how the calculate the acceptance mask given multiple IDs:
ID1 = 11'b101 1010 0000 ID2 = 11'b101 1010 0001 ID3 = 11'b101 1010 0100 ID4 = 11'b101 1010 1000 //Acceptance Mask MASK = 11'b000 0000 1101

Application Examples Network Example: The TWAI Network example demonstrates communication between two ESP32-S3s using the TWAI driver API. One TWAI node acts as a network master that initiates and ceases the transfer of a data from another node acting as a network slave. The example can be found via peripherals/twai/twai_network.
Alert and Recovery Example: This example demonstrates how to use the TWAI driverns alert and bus-off recovery API. The example purposely introduces errors on the bus to put the TWAI controller into the Bus-Off state. An alert is used to detect the Bus-Off state and trigger the bus recovery process. The example can be found via peripherals/twai/twai_alert_and_recovery.
Self Test Example: This example uses the No Acknowledge Mode and Self Reception Request to cause the TWAI controller to send and simultaneously receive a series of messages. This example can be used to verify if the connections between the TWAI controller and the external transceiver are working correctly. The example can be found via peripherals/twai/twai_self_test.

Espressif Systems

737

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
API Reference
Header File · components/hal/include/hal/twai_types.h
Structures struct twai_message_t
Structure to store a TWAI message. Note The flags member is deprecated
Public Members
uint32_t extd : 1 Extended Frame Format (29bit ID)
uint32_t rtr : 1 Message is a Remote Frame
uint32_t ss : 1 Transmit as a Single Shot Transmission. Unused for received.
uint32_t self : 1 Transmit as a Self Reception Request. Unused for received.
uint32_t dlc_non_comp : 1 Messagens Data length code is larger than 8. This will break compliance with ISO 11898-1
uint32_t reserved : 27 Reserved bits
uint32_t flags Deprecated: Alternate way to set bits using message flags
uint32_t identifier 11 or 29 bit identifier
uint8_t data_length_code Data length code
uint8_t data[TWAI_FRAME_MAX_DLC] Data bytes (not relevant in RTR frame)
struct twai_timing_config_t Structure for bit timing configuration of the TWAI driver. Note Macro initializers are available for this structure
Public Members
uint32_t brp Baudrate prescaler (i.e., APB clock divider). Any even number from 2 to 128 for ESP32, 2 to 32768 for ESP32S2. For ESP32 Rev 2 or later, multiples of 4 from 132 to 256 are also supported
uint8_t tseg_1 Timing segment 1 (Number of time quanta, between 1 to 16)
uint8_t tseg_2 Timing segment 2 (Number of time quanta, 1 to 8)
uint8_t sjw Synchronization Jump Width (Max time quanta jump for synchronize from 1 to 4)

Espressif Systems

738

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
bool triple_sampling Enables triple sampling when the TWAI controller samples a bit
struct twai_filter_config_t Structure for acceptance filter configuration of the TWAI driver (see documentation) Note Macro initializers are available for this structure
Public Members
uint32_t acceptance_code 32-bit acceptance code
uint32_t acceptance_mask 32-bit acceptance mask
bool single_filter Use Single Filter Mode (see documentation)
Macros TWAI_EXTD_ID_MASK
TWAI Constants. Bit mask for 29 bit Extended Frame Format ID TWAI_STD_ID_MASK Bit mask for 11 bit Standard Frame Format ID TWAI_FRAME_MAX_DLC Max data bytes allowed in TWAI TWAI_FRAME_EXTD_ID_LEN_BYTES EFF ID requires 4 bytes (29bit) TWAI_FRAME_STD_ID_LEN_BYTES SFF ID requires 2 bytes (11bit) TWAI_ERR_PASS_THRESH Error counter threshold for error passive
Enumerations enum twai_mode_t
TWAI Controller operating modes. Values: TWAI_MODE_NORMAL
Normal operating mode where TWAI controller can send/receive/acknowledge messages TWAI_MODE_NO_ACK
Transmission does not require acknowledgment. Use this mode for self testing TWAI_MODE_LISTEN_ONLY
The TWAI controller will not influence the bus (No transmissions or acknowledgments) but can receive messages
Header File · components/driver/include/driver/twai.h

Espressif Systems

739

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Functions

esp_err_t twai_driver_install(const

twai_general_config_t

*g_config,

const

twai_timing_config_t *t_config, const twai_filter_config_t

*f_config)

Install TWAI driver.

This function installs the TWAI driver using three configuration structures. The required memory is allocated and the TWAI driver is placed in the stopped state after running this function.

Note Macro initializers are available for the configuration structures (see documentation) Note To reinstall the TWAI driver, call twai_driver_uninstall() first Return
· ESP_OK: Successfully installed TWAI driver · ESP_ERR_INVALID_ARG: Arguments are invalid · ESP_ERR_NO_MEM: Insufficient memory · ESP_ERR_INVALID_STATE: Driver is already installed Parameters · [in] g_config: General configuration structure · [in] t_config: Timing configuration structure · [in] f_config: Filter configuration structure esp_err_t twai_driver_uninstall(void) Uninstall the TWAI driver.

This function uninstalls the TWAI driver, freeing the memory utilized by the driver. This function can only be called when the driver is in the stopped state or the bus-off state.

Warning The application must ensure that no tasks are blocked on TX/RX queues or alerts when this function is called.
Return · ESP_OK: Successfully uninstalled TWAI driver · ESP_ERR_INVALID_STATE: Driver is not in stopped/bus-off state, or is not installed

esp_err_t twai_start(void) Start the TWAI driver.

This function starts the TWAI driver, putting the TWAI driver into the running state. This allows the TWAI driver to participate in TWAI bus activities such as transmitting/receiving messages. The TX and RX queue are reset in this function, clearing any messages that are unread or pending transmission. This function can only be called when the TWAI driver is in the stopped state.

Return · ESP_OK: TWAI driver is now running · ESP_ERR_INVALID_STATE: Driver is not in stopped state, or is not installed

esp_err_t twai_stop(void) Stop the TWAI driver.

This function stops the TWAI driver, preventing any further message from being transmitted or received until twai_start() is called. Any messages in the TX queue are cleared. Any messages in the RX queue should be read by the application after this function is called. This function can only be called when the TWAI driver is in the running state.

Warning A message currently being transmitted/received on the TWAI bus will be ceased immediately. This may lead to other TWAI nodes interpreting the unfinished message as an error.
Return · ESP_OK: TWAI driver is now Stopped · ESP_ERR_INVALID_STATE: Driver is not in running state, or is not installed

esp_err_t twai_transmit(const twai_message_t *message, TickType_t ticks_to_wait) Transmit a TWAI message.

This function queues a TWAI message for transmission. Transmission will start immediately if no other messages are queued for transmission. If the TX queue is full, this function will block until more space becomes available or until it times out. If the TX queue is disabled (TX queue length = 0 in configuration), this function

Espressif Systems

740

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

will return immediately if another message is undergoing transmission. This function can only be called when the TWAI driver is in the running state and cannot be called under Listen Only Mode.
Note This function does not guarantee that the transmission is successful. The TX_SUCCESS/TX_FAILED alert can be enabled to alert the application upon the success/failure of a transmission.
Note The TX_IDLE alert can be used to alert the application when no other messages are awaiting transmission.
Return · ESP_OK: Transmission successfully queued/initiated · ESP_ERR_INVALID_ARG: Arguments are invalid · ESP_ERR_TIMEOUT: Timed out waiting for space on TX queue · ESP_FAIL: TX queue is disabled and another message is currently transmitting · ESP_ERR_INVALID_STATE: TWAI driver is not in running state, or is not installed · ESP_ERR_NOT_SUPPORTED: Listen Only Mode does not support transmissions
Parameters · [in] message: Message to transmit · [in] ticks_to_wait: Number of FreeRTOS ticks to block on the TX queue
esp_err_t twai_receive(twai_message_t *message, TickType_t ticks_to_wait) Receive a TWAI message.
This function receives a message from the RX queue. The flags field of the message structure will indicate the type of message received. This function will block if there are no messages in the RX queue
Warning The flags field of the received message should be checked to determine if the received message contains any data bytes.
Return · ESP_OK: Message successfully received from RX queue · ESP_ERR_TIMEOUT: Timed out waiting for message · ESP_ERR_INVALID_ARG: Arguments are invalid · ESP_ERR_INVALID_STATE: TWAI driver is not installed
Parameters · [out] message: Received message · [in] ticks_to_wait: Number of FreeRTOS ticks to block on RX queue
esp_err_t twai_read_alerts(uint32_t *alerts, TickType_t ticks_to_wait) Read TWAI driver alerts.
This function will read the alerts raised by the TWAI driver. If no alert has been issued when this function is called, this function will block until an alert occurs or until it timeouts.
Note Multiple alerts can be raised simultaneously. The application should check for all alerts that have been enabled.
Return · ESP_OK: Alerts read · ESP_ERR_TIMEOUT: Timed out waiting for alerts · ESP_ERR_INVALID_ARG: Arguments are invalid · ESP_ERR_INVALID_STATE: TWAI driver is not installed
Parameters · [out] alerts: Bit field of raised alerts (see documentation for alert flags) · [in] ticks_to_wait: Number of FreeRTOS ticks to block for alert
esp_err_t twai_reconfigure_alerts(uint32_t alerts_enabled, uint32_t *current_alerts) Reconfigure which alerts are enabled.
This function reconfigures which alerts are enabled. If there are alerts which have not been read whilst reconfiguring, this function can read those alerts.
Return · ESP_OK: Alerts reconfigured · ESP_ERR_INVALID_STATE: TWAI driver is not installed
Parameters · [in] alerts_enabled: Bit field of alerts to enable (see documentation for alert flags)

Espressif Systems

741

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· [out] current_alerts: Bit field of currently raised alerts. Set to NULL if unused
esp_err_t twai_initiate_recovery(void) Start the bus recovery process.
This function initiates the bus recovery process when the TWAI driver is in the bus-off state. Once initiated, the TWAI driver will enter the recovering state and wait for 128 occurrences of the bus-free signal on the TWAI bus before returning to the stopped state. This function will reset the TX queue, clearing any messages pending transmission.
Note The BUS_RECOVERED alert can be enabled to alert the application when the bus recovery process completes.
Return · ESP_OK: Bus recovery started · ESP_ERR_INVALID_STATE: TWAI driver is not in the bus-off state, or is not installed
esp_err_t twai_get_status_info(twai_status_info_t *status_info) Get current status information of the TWAI driver.
Return · ESP_OK: Status information retrieved · ESP_ERR_INVALID_ARG: Arguments are invalid · ESP_ERR_INVALID_STATE: TWAI driver is not installed
Parameters · [out] status_info: Status information
esp_err_t twai_clear_transmit_queue(void) Clear the transmit queue.
This function will clear the transmit queue of all messages.
Note The transmit queue is automatically cleared when twai_stop() or twai_initiate_recovery() is called. Return
· ESP_OK: Transmit queue cleared · ESP_ERR_INVALID_STATE: TWAI driver is not installed or TX queue is disabled
esp_err_t twai_clear_receive_queue(void) Clear the receive queue.
This function will clear the receive queue of all messages.
Note The receive queue is automatically cleared when twai_start() is called. Return
· ESP_OK: Transmit queue cleared · ESP_ERR_INVALID_STATE: TWAI driver is not installed
Structures struct twai_general_config_t
Structure for general configuration of the TWAI driver.
Note Macro initializers are available for this structure
Public Members
twai_mode_t mode Mode of TWAI controller
gpio_num_t tx_io Transmit GPIO number
gpio_num_t rx_io Receive GPIO number

Espressif Systems

742

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
gpio_num_t clkout_io CLKOUT GPIO number (optional, set to -1 if unused)
gpio_num_t bus_off_io Bus off indicator GPIO number (optional, set to -1 if unused)
uint32_t tx_queue_len Number of messages TX queue can hold (set to 0 to disable TX Queue)
uint32_t rx_queue_len Number of messages RX queue can hold
uint32_t alerts_enabled Bit field of alerts to enable (see documentation)
uint32_t clkout_divider CLKOUT divider. Can be 1 or any even number from 2 to 14 (optional, set to 0 if unused)
int intr_flags Interrupt flags to set the priority of the driverns ISR. Note that to use the ESP_INTR_FLAG_IRAM, the CONFIG_TWAI_ISR_IN_IRAM option should be enabled first.
struct twai_status_info_t Structure to store status information of TWAI driver.
Public Members
twai_state_t state Current state of TWAI controller (Stopped/Running/Bus-Off/Recovery)
uint32_t msgs_to_tx Number of messages queued for transmission or awaiting transmission completion
uint32_t msgs_to_rx Number of messages in RX queue waiting to be read
uint32_t tx_error_counter Current value of Transmit Error Counter
uint32_t rx_error_counter Current value of Receive Error Counter
uint32_t tx_failed_count Number of messages that failed transmissions
uint32_t rx_missed_count Number of messages that were lost due to a full RX queue (or errata workaround if enabled)
uint32_t rx_overrun_count Number of messages that were lost due to a RX FIFO overrun
uint32_t arb_lost_count Number of instances arbitration was lost
uint32_t bus_error_count Number of instances a bus error has occurred
Macros TWAI_IO_UNUSED
Marks GPIO as unused in TWAI configuration
Enumerations

Espressif Systems

743

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
enum twai_state_t TWAI driver states. Values: TWAI_STATE_STOPPED Stopped state. The TWAI controller will not participate in any TWAI bus activities TWAI_STATE_RUNNING Running state. The TWAI controller can transmit and receive messages TWAI_STATE_BUS_OFF Bus-off state. The TWAI controller cannot participate in bus activities until it has recovered TWAI_STATE_RECOVERING Recovering state. The TWAI controller is undergoing bus recovery
2.3.22 Universal Asynchronous Receiver/Transmitter (UART)
Overview
A Universal Asynchronous Receiver/Transmitter (UART) is a hardware feature that handles communication (i.e., timing requirements and data framing) using widely-adopted asynchronous serial communication interfaces, such as RS232, RS422, RS485. A UART provides a widely adopted and cheap method to realize full-duplex or half-duplex data exchange among different devices. The ESP32-S3 chip has three UART controllers (UART0, UART1, and UART2), each featuring an identical set of registers to simplify programming and for more flexibility. Each UART controller is independently configurable with parameters such as baud rate, data bit length, bit ordering, number of stop bits, parity bit etc. All the controllers are compatible with UART-enabled devices from various manufacturers and can also support Infrared Data Association protocols (IrDA).
Functional Overview
The following overview describes how to establish communication between an ESP32-S3 and other UART devices using the functions and data types of the UART driver. The overview reflects a typical programming workflow and is broken down into the sections provided below:
1. Setting Communication Parameters - Setting baud rate, data bits, stop bits, etc. 2. Setting Communication Pins - Assigning pins for connection to a device. 3. Driver Installation - Allocating ESP32-S3ns resources for the UART driver. 4. Running UART Communication - Sending / receiving data 5. Using Interrupts - Triggering interrupts on specific communication events 6. Deleting a Driver - Freeing allocated resources if a UART communication is no longer required Steps 1 to 3 comprise the configuration stage. Step 4 is where the UART starts operating. Steps 5 and 6 are optional. The UART driverns functions identify each of the UART controllers using uart_port_t. This identification is needed for all the following function calls.
Setting Communication Parameters UART communication parameters can be configured all in a single step or individually in multiple steps.
Single Step Call the function uart_param_config() and pass to it a uart_config_t structure. The uart_config_t structure should contain all the required parameters. See the example below.

Espressif Systems

744

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

const uart_port_t uart_num = UART_NUM_2; uart_config_t uart_config = {
.baud_rate = 115200, .data_bits = UART_DATA_8_BITS, .parity = UART_PARITY_DISABLE, .stop_bits = UART_STOP_BITS_1, .flow_ctrl = UART_HW_FLOWCTRL_CTS_RTS, .rx_flow_ctrl_thresh = 122, }; // Configure UART parameters ESP_ERROR_CHECK(uart_param_config(uart_num, &uart_config));
For more information on how to configure the hardware flow control options, please refer to peripherals/uart/uart_echo.

Multiple Steps Configure specific parameters individually by calling a dedicated function from the table given below. These functions are also useful if re-configuring a single parameter.

Table 6: Functions for Configuring specific parameters individually

Parameter to Configure

Function

Baud rate

uart_set_baudrate()

Number of transmitted bits

uart_set_word_length() selected out of uart_word_length_t

Parity control

uart_set_parity() selected out of uart_parity_t

Number of stop bits Hardware flow control mode

uart_set_stop_bits() selected out of uart_stop_bits_t

uart_set_hw_flow_ctrl()

selected

out

of

uart_hw_flowcontrol_t

Communication mode

uart_set_mode() selected out of uart_mode_t

Each of the above functions has a _get_ counterpart to check the currently set value. For example, to check the current baud rate value, call uart_get_baudrate().

Setting Communication Pins After setting communication parameters, configure the physical GPIO pins to which the other UART device will be connected. For this, call the function uart_set_pin() and specify the GPIO pin numbers to which the driver should route the Tx, Rx, RTS, and CTS signals. If you want to keep a currently allocated pin number for a specific signal, pass the macro UART_PIN_NO_CHANGE.
The same macro should be specified for pins that will not be used.
// Set UART pins(TX: IO4, RX: IO5, RTS: IO18, CTS: IO19) ESP_ERROR_CHECK(uart_set_pin(UART_NUM_2, 4, 5, 18, 19));

Driver Installation Once the communication pins are set, install the driver by calling uart_driver_install() and specify the following parameters:
· Size of Tx ring buffer · Size of Rx ring buffer · Event queue handle and size · Flags to allocate an interrupt
The function will allocate the required internal resources for the UART driver.
// Setup UART buffered IO with event queue const int uart_buffer_size = (1024 * 2); QueueHandle_t uart_queue; // Install UART driver using an event queue here ESP_ERROR_CHECK(uart_driver_install(UART_NUM_2, uart_buffer_size, \
uart_buffer_size, 10, &uart_queue, 0));

Espressif Systems

745

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Once this step is complete, you can connect the external UART device and check the communication.
Running UART Communication Serial communication is controlled by each UART controllerns finite state machine (FSM).
The process of sending data involves the following steps:
1. Write data into Tx FIFO buffer 2. FSM serializes the data 3. FSM sends the data out
The process of receiving data is similar, but the steps are reversed:
1. FSM processes an incoming serial stream and parallelizes it 2. FSM writes the data into Rx FIFO buffer 3. Read the data from Rx FIFO buffer
Therefore, an application will be limited to writing and reading data from a respective buffer using uart_write_bytes() and uart_read_bytes() respectively, and the FSM will do the rest.
Transmitting After preparing the data for transmission, call the function uart_write_bytes() and pass the data bufferns address and data length to it. The function will copy the data to the Tx ring buffer (either immediately or after enough space is available), and then exit. When there is free space in the Tx FIFO buffer, an interrupt service routine (ISR) moves the data from the Tx ring buffer to the Tx FIFO buffer in the background. The code below demonstrates the use of this function.
// Write data to UART. char* test_str = "This is a test string.\n"; uart_write_bytes(uart_num, (const char*)test_str, strlen(test_str));
The function uart_write_bytes_with_break() is similar to uart_write_bytes() but adds a serial break signal at the end of the transmission. Amserial break signalnmeans holding the Tx line low for a period longer than one data frame.
// Write data to UART, end with a break signal. uart_write_bytes_with_break(uart_num, "test break\n",strlen("test break\n"), 100);
Another function for writing data to the Tx FIFO buffer is uart_tx_chars(). Unlike uart_write_bytes(), this function will not block until space is available. Instead, it will write all data which can immediately fit into the hardware Tx FIFO, and then return the number of bytes that were written.
There is a mcompanionnfunction uart_wait_tx_done() that monitors the status of the Tx FIFO buffer and returns once it is empty.
// Wait for packet to be sent const uart_port_t uart_num = UART_NUM_2; ESP_ERROR_CHECK(uart_wait_tx_done(uart_num, 100)); // wait timeout is 100 RTOS ticks (TickType_t)
Receiving Once the data is received by the UART and saved in the Rx FIFO buffer, it needs to be retrieved using the function uart_read_bytes(). Before reading data, you can check the number of bytes available in the Rx FIFO buffer by calling uart_get_buffered_data_len(). An example of using these functions is given below.
// Read data from UART. const uart_port_t uart_num = UART_NUM_2; uint8_t data[128]; int length = 0; ESP_ERROR_CHECK(uart_get_buffered_data_len(uart_num, (size_t*)&length)); length = uart_read_bytes(uart_num, data, length, 100);

Espressif Systems

746

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

If the data in the Rx FIFO buffer is no longer needed, you can clear the buffer by calling uart_flush().
Software Flow Control If the hardware flow control is disabled, you can manually set the RTS and DTR signal levels by using the functions uart_set_rts() and uart_set_dtr() respectively.
Communication Mode Selection The UART controller supports a number of communication modes. A mode can be selected using the function uart_set_mode(). Once a specific mode is selected, the UART driver will handle the behavior of a connected UART device accordingly. As an example, it can control the RS485 driver chip using the RTS line to allow half-duplex RS485 communication.
// Setup UART in rs485 half duplex mode ESP_ERROR_CHECK(uart_set_mode(uart_num, UART_MODE_RS485_HALF_DUPLEX));

Using Interrupts There are many interrupts that can be generated following specific UART states or detected errors. The full list of available interrupts is provided in ESP32-S3 Technical Reference Manual > UART Controller (UART) > UART Interrupts and UHCI Interrupts [PDF]. You can enable or disable specific interrupts by calling uart_enable_intr_mask() or uart_disable_intr_mask() respectively. The mask of all interrupts is available as UART_INTR_MASK.
The uart_driver_install() function installs the driverns internal interrupt handler to manage the Tx and Rx ring buffers and provides high-level API functions like events (see below).
The API provides a convenient way to handle specific interrupts discussed in this document by wrapping them into dedicated functions:
· Event detection: There are several events defined in uart_event_type_t that may be reported to a user application using the FreeRTOS queue functionality. You can enable this functionality when calling uart_driver_install() described in Driver Installation. An example of using Event detection can be found in peripherals/uart/uart_events.
· FIFO space threshold or transmission timeout reached: The Tx and Rx FIFO buffers can trigger an interrupt when they are filled with a specific number of characters, or on a timeout of sending or receiving data. To use these interrupts, do the following: ­ Configure respective threshold values of the buffer length and timeout by entering them in the structure uart_intr_config_t and calling uart_intr_config() ­ Enable the interrupts using the functions uart_enable_tx_intr() and uart_enable_rx_intr() ­ Disable these interrupts using the corresponding functions uart_disable_tx_intr() or uart_disable_rx_intr()
· Pattern detection: An interrupt triggered on detecting ampatternnof the same character being received/sent repeatedly for a number of times. This functionality is demonstrated in the example peripherals/uart/uart_events. It can be used, e.g., to detect a command string followed by a specific number of identical characters (thempatternn) added at the end of the command string. The following functions are available: ­ Configure and enable this interrupt using uart_enable_pattern_det_intr() ­ Disable the interrupt using uart_disable_pattern_det_intr()
Macros The API also defines several macros. For example, UART_FIFO_LEN defines the length of hardware FIFO buffers; UART_BITRATE_MAX gives the maximum baud rate supported by the UART controllers, etc.
Deleting a Driver If the communication established with uart_driver_install() is no longer required, the driver can be removed to free allocated resources by calling uart_driver_delete().
Overview of RS485 specific communication options

Note: The following section will use [UART_REGISTER_NAME].[UART_FIELD_BIT] to refer to UART register fields/bits. For more information on a specific option bit, see ESP32-S3 Technical Reference Manual > UART

Espressif Systems

747

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Controller (UART) > Register Summary [PDF]. Use the register name to navigate to the register description and then find the field/bit.
· UART_RS485_CONF_REG.UART_RS485_EN: setting this bit enables RS485 communication mode support.
· UART_RS485_CONF_REG.UART_RS485TX_RX_EN: if this bit is set, the transmitterns output signal loops back to the receiverns input signal.
· UART_RS485_CONF_REG.UART_RS485RXBY_TX_EN: if this bit is set, the transmitter will still be sending data if the receiver is busy (remove collisions automatically by hardware).
The ESP32-S3ns RS485 UART hardware can detect signal collisions during transmission of a datagram and generate the interrupt UART_RS485_CLASH_INT if this interrupt is enabled. The term collision means that a transmitted datagram is not equal to the one received on the other end. Data collisions are usually associated with the presence of other active devices on the bus or might occur due to bus errors.
The collision detection feature allows handling collisions when their interrupts are activated and triggered. The interrupts UART_RS485_FRM_ERR_INT and UART_RS485_PARITY_ERR_INT can be used with the collision detection feature to control frame errors and parity bit errors accordingly in RS485 mode. This functionality is supported in the UART driver and can be used by selecting the UART_MODE_RS485_APP_CTRL mode (see the function uart_set_mode()).
The collision detection feature can work with circuit A and circuit C (see Section Interface Connection Options). In the case of using circuit A or B, the RTS pin connected to the DE pin of the bus driver should be controlled by the user application. Use the function uart_get_collision_flag() to check if the collision detection flag has been raised.
The ESP32-S3 UART controllers themselves do not support half-duplex communication as they cannot provide automatic control of the RTS pin connected to the ~RE/DE input of RS485 bus driver. However, half-duplex communication can be achieved via software control of the RTS pin by the UART driver. This can be enabled by selecting the UART_MODE_RS485_HALF_DUPLEX mode when calling uart_set_mode().
Once the host starts writing data to the Tx FIFO buffer, the UART driver automatically asserts the RTS pin (logic 1); once the last bit of the data has been transmitted, the driver de-asserts the RTS pin (logic 0). To use this mode, the software would have to disable the hardware flow control function. This mode works with all the used circuits shown below.
Interface Connection Options This section provides example schematics to demonstrate the basic aspects of ESP32-S3ns RS485 interface connection.
Note:
· The schematics below do not necessarily contain all required elements. · The analog devices ADM483 & ADM2483 are examples of common RS485 transceivers and can be replaced
with other similar transceivers.

Circuit A: Collision Detection Circuit

VCC ---------------+

|

+-------x-------+

RXD <------| R

|

|

B|----------<> B

TXD ------>| D ADM483 |

ESP

|

|

RS485 bus side

RTS ------>| DE

|

|

A|----------<> A

+----| /RE

|

| +-------x-------+

(continues on next page)

Espressif Systems

748

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

|

|

GND

GND

(continued from previous page)

This circuit is preferable because it allows for collision detection and is quite simple at the same time. The receiver in the line driver is constantly enabled, which allows the UART to monitor the RS485 bus. Echo suppression is performed by the UART peripheral when the bit UART_RS485_CONF_REG.UART_RS485TX_RX_EN is enabled.

Circuit B: Manual Switching Transmitter/Receiver Without Collision Detection

VCC ---------------+

|

+-------x-------+

RXD <------| R

|

|

B|-----------<> B

TXD ------>| D ADM483 |

ESP

|

|

RS485 bus side

RTS --+--->| DE

|

||

A|-----------<> A

+----| /RE

|

+-------x-------+

|

GND

This circuit does not allow for collision detection. It suppresses the null bytes that the hardware receives when the bit UART_RS485_CONF_REG.UART_RS485TX_RX_EN is set. The bit UART_RS485_CONF_REG. UART_RS485RXBY_TX_EN is not applicable in this case.

Circuit C: Auto Switching Transmitter/Receiver

VCC1 <-------------------+-----------+

+-------------------+----> VCC2

10K ____ |

|

|

|

+---|____|--+

+---x-----------x---+ 10K ____ |

|

|

| +---|____|--+

RX <----------+-------------------| RXD

||

10K ____

|

A|---+---------------<> A (+)

+-------|____|------| PV ADM2483

| | ____ 120

| ____

|

| +---|____|---+ RS485

bus side

VCC1 <--+--|____|--+------->| DE

|

|

10K

|

|

B|---+------------+--<> B (-)

---+ +-->| /RE

| | ____

10K

|

||

| +---|____|---+

____

| /-C

+---| TXD

| 10K

|

TX >---|____|--+_B_|/ NPN | |

|

|

|\

| +---x-----------x---+

|

| \-E

|

|

|

|

|

|

|

|

|

GND1 GND1 GND1

GND2

GND2

This galvanically isolated circuit does not require RTS pin control by a software application or driver because it controls the transceiver direction automatically. However, it requires suppressing null bytes during transmission by setting UART_RS485_CONF_REG.UART_RS485RXBY_TX_EN to 1 and UART_RS485_CONF_REG. UART_RS485TX_RX_EN to 0. This setup can work in any RS485 UART mode or even in UART_MODE_UART.

Application Examples The table below describes the code examples available in the directory peripherals/uart/.

Espressif Systems

749

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Code Example peripherals/uart/uart_echo peripherals/uart/uart_events peripherals/uart/uart_async_rxtxtasks peripherals/uart/uart_select peripherals/uart/uart_echo_rs485
peripherals/uart/nmea0183_parser

Description Configuring UART settings, installing the UART driver, and reading/writing over the UART1 interface. Reporting various communication events, using pattern detection interrupts. Transmitting and receiving data in two separate FreeRTOS tasks over the same UART. Using synchronous I/O multiplexing for UART file descriptors. Setting up UART driver to communicate over RS485 interface in halfduplex mode. This example is similar to peripherals/uart/uart_echo but allows communication through an RS485 interface chip connected to ESP32-S3 pins. Obtaining GPS information by parsing NMEA0183 statements received from GPS via the UART peripheral.

API Reference
Header File · components/driver/include/driver/uart.h

Functions esp_err_t uart_driver_install(uart_port_t uart_num, int rx_buffer_size, int tx_buffer_size, int
queue_size, QueueHandle_t *uart_queue, int intr_alloc_flags) Install UART driver and set the UART to the default configuration.
UART ISR handler will be attached to the same CPU core that this function is running on.
Note Rx_buffer_size should be greater than UART_FIFO_LEN. Tx_buffer_size should be either zero or greater than UART_FIFO_LEN.
Return · ESP_OK Success · ESP_FAIL Parameter error
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · rx_buffer_size: UART RX ring buffer size. · tx_buffer_size: UART TX ring buffer size. If set to zero, driver will not use TX buffer, TX function will block task until all data have been sent out. · queue_size: UART event queue size/depth. · uart_queue: UART event queue handle (out param). On success, a new queue handle is written here to provide access to UART events. If set to NULL, driver will not use an event queue. · intr_alloc_flags: Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info. Do not set ESP_INTR_FLAG_IRAM here (the driverns ISR handler is not located in IRAM)
esp_err_t uart_driver_delete(uart_port_t uart_num) Uninstall UART driver.
Return · ESP_OK Success · ESP_FAIL Parameter error
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1).
bool uart_is_driver_installed(uart_port_t uart_num) Checks whether the driver is installed or not.
Return · true driver is installed · false driver is not installed

Espressif Systems

750

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1).
esp_err_t uart_set_word_length(uart_port_t uart_num, uart_word_length_t data_bit) Set UART data bits.
Return · ESP_OK Success · ESP_FAIL Parameter error
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · data_bit: UART data bits
esp_err_t uart_get_word_length(uart_port_t uart_num, uart_word_length_t *data_bit) Get the UART data bit configuration.
Return · ESP_FAIL Parameter error · ESP_OK Success, result will be put in (*data_bit)
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · data_bit: Pointer to accept value of UART data bits.
esp_err_t uart_set_stop_bits(uart_port_t uart_num, uart_stop_bits_t stop_bits) Set UART stop bits.
Return · ESP_OK Success · ESP_FAIL Fail
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · stop_bits: UART stop bits
esp_err_t uart_get_stop_bits(uart_port_t uart_num, uart_stop_bits_t *stop_bits) Get the UART stop bit configuration.
Return · ESP_FAIL Parameter error · ESP_OK Success, result will be put in (*stop_bit)
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · stop_bits: Pointer to accept value of UART stop bits.
esp_err_t uart_set_parity(uart_port_t uart_num, uart_parity_t parity_mode) Set UART parity mode.
Return · ESP_FAIL Parameter error · ESP_OK Success
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · parity_mode: the enum of uart parity configuration
esp_err_t uart_get_parity(uart_port_t uart_num, uart_parity_t *parity_mode) Get the UART parity mode configuration.
Return · ESP_FAIL Parameter error · ESP_OK Success, result will be put in (*parity_mode)
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · parity_mode: Pointer to accept value of UART parity mode.
esp_err_t uart_set_baudrate(uart_port_t uart_num, uint32_t baudrate) Set UART baud rate.

Espressif Systems

751

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return · ESP_FAIL Parameter error · ESP_OK Success
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · baudrate: UART baud rate.

esp_err_t uart_get_baudrate(uart_port_t uart_num, uint32_t *baudrate) Get the UART baud rate configuration.

Return · ESP_FAIL Parameter error · ESP_OK Success, result will be put in (*baudrate)
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · baudrate: Pointer to accept value of UART baud rate

esp_err_t uart_set_line_inverse(uart_port_t uart_num, uint32_t inverse_mask) Set UART line inverse mode.

Return · ESP_OK Success · ESP_FAIL Parameter error
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · inverse_mask: Choose the wires that need to be inverted. Using the ORred mask of uart_signal_inv_t

esp_err_t uart_set_hw_flow_ctrl(uart_port_t uart_num, uart_hw_flowcontrol_t flow_ctrl, uint8_t

Set hardware flow control.

rx_thresh)

Return · ESP_OK Success · ESP_FAIL Parameter error
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · flow_ctrl: Hardware flow control mode · rx_thresh: Threshold of Hardware RX flow control (0 ~ UART_FIFO_LEN). Only when UART_HW_FLOWCTRL_RTS is set, will the rx_thresh value be set.

esp_err_t uart_set_sw_flow_ctrl(uart_port_t uart_num, bool enable, uint8_t rx_thresh_xon, uint8_t

Set software flow control.

rx_thresh_xoff)

Return · ESP_OK Success · ESP_FAIL Parameter error
Parameters · uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2 · enable: switch on or off · rx_thresh_xon: low water mark · rx_thresh_xoff: high water mark

esp_err_t uart_get_hw_flow_ctrl(uart_port_t uart_num, uart_hw_flowcontrol_t *flow_ctrl) Get the UART hardware flow control configuration.

Return · ESP_FAIL Parameter error · ESP_OK Success, result will be put in (*flow_ctrl)
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · flow_ctrl: Option for different flow control mode.

Espressif Systems

752

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t uart_clear_intr_status(uart_port_t uart_num, uint32_t clr_mask) Clear UART interrupt status.
Return · ESP_OK Success · ESP_FAIL Parameter error
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · clr_mask: Bit mask of the interrupt status to be cleared.
esp_err_t uart_enable_intr_mask(uart_port_t uart_num, uint32_t enable_mask) Set UART interrupt enable.
Return · ESP_OK Success · ESP_FAIL Parameter error
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · enable_mask: Bit mask of the enable bits.
esp_err_t uart_disable_intr_mask(uart_port_t uart_num, uint32_t disable_mask) Clear UART interrupt enable bits.
Return · ESP_OK Success · ESP_FAIL Parameter error
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · disable_mask: Bit mask of the disable bits.
esp_err_t uart_enable_rx_intr(uart_port_t uart_num) Enable UART RX interrupt (RX_FULL & RX_TIMEOUT INTERRUPT)
Return · ESP_OK Success · ESP_FAIL Parameter error
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1).
esp_err_t uart_disable_rx_intr(uart_port_t uart_num) Disable UART RX interrupt (RX_FULL & RX_TIMEOUT INTERRUPT)
Return · ESP_OK Success · ESP_FAIL Parameter error
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1).
esp_err_t uart_disable_tx_intr(uart_port_t uart_num) Disable UART TX interrupt (TX_FULL & TX_TIMEOUT INTERRUPT)
Return · ESP_OK Success · ESP_FAIL Parameter error
Parameters · uart_num: UART port number
esp_err_t uart_enable_tx_intr(uart_port_t uart_num, int enable, int thresh) Enable UART TX interrupt (TX_FULL & TX_TIMEOUT INTERRUPT)
Return · ESP_OK Success · ESP_FAIL Parameter error
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1).

Espressif Systems

753

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· enable: 1: enable; 0: disable · thresh: Threshold of TX interrupt, 0 ~ UART_FIFO_LEN
esp_err_t uart_set_pin(uart_port_t uart_num, int tx_io_num, int rx_io_num, int rts_io_num, int cts_io_num)
Assign signals of a UART peripheral to GPIO pins.
Note If the GPIO number configured for a UART signal matches one of the IOMUX signals for that GPIO, the signal will be connected directly via the IOMUX. Otherwise the GPIO and signal will be connected via the GPIO Matrix. For example, if on an ESP32 the call uart_set_pin(0, 1, 3, -1, -1) is performed, as GPIO1 is UART0ns default TX pin and GPIO3 is UART0ns default RX pin, both will be connected to respectively U0TXD and U0RXD through the IOMUX, totally bypassing the GPIO matrix. The check is performed on a per-pin basis. Thus, it is possible to have RX pin binded to a GPIO through the GPIO matrix, whereas TX is binded to its GPIO through the IOMUX.
Note Internal signal can be output to multiple GPIO pads. Only one GPIO pad can connect with input signal. Return
· ESP_OK Success · ESP_FAIL Parameter error Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · tx_io_num: UART TX pin GPIO number. · rx_io_num: UART RX pin GPIO number. · rts_io_num: UART RTS pin GPIO number. · cts_io_num: UART CTS pin GPIO number.
esp_err_t uart_set_rts(uart_port_t uart_num, int level) Manually set the UART RTS pin level.
Note UART must be configured with hardware flow control disabled. Return
· ESP_OK Success · ESP_FAIL Parameter error Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · level: 1: RTS output low (active); 0: RTS output high (block)
esp_err_t uart_set_dtr(uart_port_t uart_num, int level) Manually set the UART DTR pin level.
Return · ESP_OK Success · ESP_FAIL Parameter error
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · level: 1: DTR output low; 0: DTR output high
esp_err_t uart_set_tx_idle_num(uart_port_t uart_num, uint16_t idle_num) Set UART idle interval after tx FIFO is empty.
Return · ESP_OK Success · ESP_FAIL Parameter error
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · idle_num: idle interval after tx FIFO is empty(unit: the time it takes to send one bit under current baudrate)
esp_err_t uart_param_config(uart_port_t uart_num, const uart_config_t *uart_config) Set UART configuration parameters.
Return · ESP_OK Success · ESP_FAIL Parameter error

Espressif Systems

754

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · uart_config: UART parameter settings
esp_err_t uart_intr_config(uart_port_t uart_num, const uart_intr_config_t *intr_conf) Configure UART interrupts.
Return · ESP_OK Success · ESP_FAIL Parameter error
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · intr_conf: UART interrupt settings
esp_err_t uart_wait_tx_done(uart_port_t uart_num, TickType_t ticks_to_wait) Wait until UART TX FIFO is empty.
Return · ESP_OK Success · ESP_FAIL Parameter error · ESP_ERR_TIMEOUT Timeout
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · ticks_to_wait: Timeout, count in RTOS ticks
int uart_tx_chars(uart_port_t uart_num, const char *buffer, uint32_t len) Send data to the UART port from a given buffer and length.
This function will not wait for enough space in TX FIFO. It will just fill the available TX FIFO and return when the FIFO is full.
Note This function should only be used when UART TX buffer is not enabled. Return
· (-1) Parameter error · OTHERS (>=0) The number of bytes pushed to the TX FIFO Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · buffer: data buffer address · len: data length to send
int uart_write_bytes(uart_port_t uart_num, const void *src, size_t size) Send data to the UART port from a given buffer and length,.
If the UART driverns parameter mtx_buffer_sizenis set to zero: This function will not return until all the data have been sent out, or at least pushed into TX FIFO.
Otherwise, if the mtx_buffer_sizen> 0, this function will return after copying all the data to tx ring buffer, UART ISR will then move data from the ring buffer to TX FIFO gradually.
Return · (-1) Parameter error · OTHERS (>=0) The number of bytes pushed to the TX FIFO
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · src: data buffer address · size: data length to send
int uart_write_bytes_with_break(uart_port_t uart_num, const void *src, size_t size, int brk_len)
Send data to the UART port from a given buffer and length,.
If the UART driverns parameter mtx_buffer_sizenis set to zero: This function will not return until all the data and the break signal have been sent out. After all data is sent out, send a break signal.

Espressif Systems

755

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Otherwise, if the mtx_buffer_sizen> 0, this function will return after copying all the data to tx ring buffer, UART ISR will then move data from the ring buffer to TX FIFO gradually. After all data sent out, send a break signal.
Return · (-1) Parameter error · OTHERS (>=0) The number of bytes pushed to the TX FIFO
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · src: data buffer address · size: data length to send · brk_len: break signal duration(unit: the time it takes to send one bit at current baudrate)
int uart_read_bytes(uart_port_t uart_num, void *buf, uint32_t length, TickType_t ticks_to_wait) UART read bytes from UART buffer.
Return · (-1) Error · OTHERS (>=0) The number of bytes read from UART FIFO
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · buf: pointer to the buffer. · length: data length · ticks_to_wait: sTimeout, count in RTOS ticks
esp_err_t uart_flush(uart_port_t uart_num) Alias of uart_flush_input. UART ring buffer flush. This will discard all data in the UART RX buffer.
Note Instead of waiting the data sent out, this function will clear UART rx buffer. In order to send all the data in tx FIFO, we can use uart_wait_tx_done function.
Return · ESP_OK Success · ESP_FAIL Parameter error
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1).
esp_err_t uart_flush_input(uart_port_t uart_num) Clear input buffer, discard all the data is in the ring-buffer.
Note In order to send all the data in tx FIFO, we can use uart_wait_tx_done function. Return
· ESP_OK Success · ESP_FAIL Parameter error Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1).
esp_err_t uart_get_buffered_data_len(uart_port_t uart_num, size_t *size) UART get RX ring buffer cached data length.
Return · ESP_OK Success · ESP_FAIL Parameter error
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · size: Pointer of size_t to accept cached data length
esp_err_t uart_disable_pattern_det_intr(uart_port_t uart_num) UART disable pattern detect function. Designed for applications like mAT commandsn. When the hardware detects a series of one same character, the interrupt will be triggered.
Return · ESP_OK Success · ESP_FAIL Parameter error
Parameters

Espressif Systems

756

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· uart_num: UART port number, the max port number is (UART_NUM_MAX -1).
esp_err_t uart_enable_pattern_det_baud_intr(uart_port_t uart_num, char pattern_chr, uint8_t chr_num, int chr_tout, int post_idle, int pre_idle)
UART enable pattern detect function. Designed for applications like mAT commandsn. When the hardware detect a series of one same character, the interrupt will be triggered.
Return · ESP_OK Success · ESP_FAIL Parameter error
Parameters · uart_num: UART port number. · pattern_chr: character of the pattern. · chr_num: number of the character, 8bit value. · chr_tout: timeout of the interval between each pattern characters, 16bit value, unit is the baudrate cycle you configured. When the duration is more than this value, it will not take this data as at_cmd char. · post_idle: idle time after the last pattern character, 16bit value, unit is the baud-rate cycle you configured. When the duration is less than this value, it will not take the previous data as the last at_cmd char · pre_idle: idle time before the first pattern character, 16bit value, unit is the baud-rate cycle you configured. When the duration is less than this value, it will not take this data as the first at_cmd char.
int uart_pattern_pop_pos(uart_port_t uart_num) Return the nearest detected pattern position in buffer. The positions of the detected pattern are saved in a queue, this function will dequeue the first pattern position and move the pointer to next pattern position.
The following APIs will modify the pattern position info: uart_flush_input, uart_read_bytes, uart_driver_delete, uart_pop_pattern_pos It is the applicationns responsibility to ensure atomic access to the pattern queue and the rx data buffer when using pattern detect feature.
Note If the RX buffer is full and flow control is not enabled, the detected pattern may not be found in the rx buffer due to overflow.
Return · (-1) No pattern found for current index or parameter error · others the pattern position in rx buffer.
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1).
int uart_pattern_get_pos(uart_port_t uart_num) Return the nearest detected pattern position in buffer. The positions of the detected pattern are saved in a queue, This function do nothing to the queue.
The following APIs will modify the pattern position info: uart_flush_input, uart_read_bytes, uart_driver_delete, uart_pop_pattern_pos It is the applicationns responsibility to ensure atomic access to the pattern queue and the rx data buffer when using pattern detect feature.
Note If the RX buffer is full and flow control is not enabled, the detected pattern may not be found in the rx buffer due to overflow.
Return · (-1) No pattern found for current index or parameter error · others the pattern position in rx buffer.
Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1).
esp_err_t uart_pattern_queue_reset(uart_port_t uart_num, int queue_length) Allocate a new memory with the given length to save record the detected pattern position in rx buffer.
Return · ESP_ERR_NO_MEM No enough memory

Espressif Systems

757

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· ESP_ERR_INVALID_STATE Driver not installed · ESP_FAIL Parameter error · ESP_OK Success Parameters · uart_num: UART port number, the max port number is (UART_NUM_MAX -1). · queue_length: Max queue length for the detected pattern. If the queue length is not large
enough, some pattern positions might be lost. Set this value to the maximum number of patterns that could be saved in data buffer at the same time.
esp_err_t uart_set_mode(uart_port_t uart_num, uart_mode_t mode) UART set communication mode.
Note This function must be executed after uart_driver_install(), when the driver object is initialized. Return
· ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error Parameters · uart_num: Uart number to configure, the max port number is (UART_NUM_MAX -1). · mode: UART UART mode to set
esp_err_t uart_set_rx_full_threshold(uart_port_t uart_num, int threshold) Set uart threshold value for RX fifo full.
Note If application is using higher baudrate and it is observed that bytes in hardware RX fifo are overwritten then this threshold can be reduced
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_INVALID_STATE Driver is not installed
Parameters · uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2 · threshold: Threshold value above which RX fifo full interrupt is generated
esp_err_t uart_set_tx_empty_threshold(uart_port_t uart_num, int threshold) Set uart threshold values for TX fifo empty.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_INVALID_STATE Driver is not installed
Parameters · uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2 · threshold: Threshold value below which TX fifo empty interrupt is generated
esp_err_t uart_set_rx_timeout(uart_port_t uart_num, const uint8_t tout_thresh) UART set threshold timeout for TOUT feature.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_INVALID_STATE Driver is not installed
Parameters · uart_num: Uart number to configure, the max port number is (UART_NUM_MAX -1). · tout_thresh: This parameter defines timeout threshold in uart symbol periods. The maximum value of threshold is 126. tout_thresh = 1, defines TOUT interrupt timeout equal to transmission time of one symbol (~11 bit) on current baudrate. If the time is expired the UART_RXFIFO_TOUT_INT interrupt is triggered. If tout_thresh == 0, the TOUT feature is disabled.
esp_err_t uart_get_collision_flag(uart_port_t uart_num, bool *collision_flag) Returns collision detection flag for RS485 mode Function returns the collision detection flag into variable pointed by collision_flag. *collision_flag = true, if collision detected else it is equal to false. This function should be executed when actual transmission is completed (after uart_write_bytes()).

Espressif Systems

758

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return · ESP_OK Success · ESP_ERR_INVALID_ARG Parameter error
Parameters · uart_num: Uart number to configure the max port number is (UART_NUM_MAX -1). · collision_flag: Pointer to variable of type bool to return collision flag.
esp_err_t uart_set_wakeup_threshold(uart_port_t uart_num, int wakeup_threshold) Set the number of RX pin signal edges for light sleep wakeup.
UART can be used to wake up the system from light sleep. This feature works by counting the number of positive edges on RX pin and comparing the count to the threshold. When the count exceeds the threshold, system is woken up from light sleep. This function allows setting the threshold value.
Stop bit and parity bits (if enabled) also contribute to the number of edges. For example, letter manwith ASCII code 97 is encoded as 0100001101 on the wire (with 8n1 configuration), start and stop bits included. This sequence has 3 positive edges (transitions from 0 to 1). Therefore, to wake up the system when manis sent, set wakeup_threshold=3.
The character that triggers wakeup is not received by UART (i.e. it can not be obtained from UART FIFO). Depending on the baud rate, a few characters after that will also not be received. Note that when the chip enters and exits light sleep mode, APB frequency will be changing. To make sure that UART has correct baud rate all the time, select REF_TICK as UART clock source, by setting use_ref_tick field in uart_config_t to true.
Note in ESP32, the wakeup signal can only be input via IO_MUX (i.e. GPIO3 should be configured as function_1 to wake up UART0, GPIO9 should be configured as function_5 to wake up UART1), UART2 does not support light sleep wakeup feature.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if uart_num is incorrect or wakeup_threshold is outside of [3, 0x3ff] range.
Parameters · uart_num: UART number, the max port number is (UART_NUM_MAX -1). · wakeup_threshold: number of RX edges for light sleep wakeup, value is 3 .. 0x3ff.
esp_err_t uart_get_wakeup_threshold(uart_port_t uart_num, int *out_wakeup_threshold) Get the number of RX pin signal edges for light sleep wakeup.
See description of uart_set_wakeup_threshold for the explanation of UART wakeup feature.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if out_wakeup_threshold is NULL
Parameters · uart_num: UART number, the max port number is (UART_NUM_MAX -1). · [out] out_wakeup_threshold: output, set to the current value of wakeup threshold for the given UART.
esp_err_t uart_wait_tx_idle_polling(uart_port_t uart_num) Wait until UART tx memory empty and the last char send ok (polling mode).
· Return ­ ESP_OK on success ­ ESP_ERR_INVALID_ARG Parameter error ­ ESP_FAIL Driver not installed
Parameters · uart_num: UART number
esp_err_t uart_set_loop_back(uart_port_t uart_num, bool loop_back_en) Configure TX signal loop back to RX module, just for the test usage.
· Return ­ ESP_OK on success ­ ESP_ERR_INVALID_ARG Parameter error

Espressif Systems

759

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

­ ESP_FAIL Driver not installed
Parameters · uart_num: UART number · loop_back_en: Set ture to enable the loop back function, else set it false.
void uart_set_always_rx_timeout(uart_port_t uart_num, bool always_rx_timeout_en) Configure behavior of UART RX timeout interrupt.
When always_rx_timeout is true, timeout interrupt is triggered even if FIFO is full. This function can cause extra timeout interrupts triggered only to send the timeout event. Call this function only if you want to ensure timeout interrupt will always happen after a byte stream.
Parameters · uart_num: UART number · always_rx_timeout_en: Set to false enable the default behavior of timeout interrupt, set it to true to always trigger timeout interrupt.

Structures struct uart_intr_config_t
UART interrupt configuration parameters for uart_intr_config function.

Public Members

uint32_t intr_enable_mask UART interrupt enable mask, choose from UART_INT_ENA_REG(i), connect with bit-or operator

UART_XXXX_INT_ENA_M

uint8_t rx_timeout_thresh UART timeout interrupt threshold (unit: time of sending one byte)

uint8_t txfifo_empty_intr_thresh UART TX empty interrupt threshold.

uint8_t rxfifo_full_thresh UART RX full interrupt threshold.
struct uart_event_t Event structure used in UART event queue.

under

Public Members
uart_event_type_t type UART event type
size_t size UART data size for UART_DATA event
bool timeout_flag UART data read timeout flag for UART_DATA event (no new data received during configured RX TOUT) If the event is caused by FIFO-full interrupt, then there will be no event with the timeout flag before the next byte coming.

Macros UART_NUM_0
UART port 0 UART_NUM_1
UART port 1
UART_NUM_2 UART port 2

Espressif Systems

760

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
UART_NUM_MAX UART port max
UART_PIN_NO_CHANGE UART_FIFO_LEN
Length of the UART HW FIFO. UART_BITRATE_MAX
Maximum configurable bitrate.
Type Definitions typedef intr_handle_t uart_isr_handle_t
Enumerations enum uart_event_type_t
UART event types used in the ring buffer. Values: UART_DATA
UART data event UART_BREAK
UART break event UART_BUFFER_FULL
UART RX buffer full event UART_FIFO_OVF
UART FIFO overflow event UART_FRAME_ERR
UART RX frame error event UART_PARITY_ERR
UART RX parity event UART_DATA_BREAK
UART TX data and break event UART_PATTERN_DET
UART pattern detected UART_EVENT_MAX
UART event max index
Header File · components/hal/include/hal/uart_types.h
Structures struct uart_at_cmd_t
UART AT cmd char configuration parameters Note that this function may different on different chip. Please refer to the TRM at confirguration.
Public Members
uint8_t cmd_char UART AT cmd char

Espressif Systems

761

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
uint8_t char_num AT cmd char repeat number
uint32_t gap_tout gap time(in baud-rate) between AT cmd char
uint32_t pre_idle the idle time(in baud-rate) between the non AT char and first AT char
uint32_t post_idle the idle time(in baud-rate) between the last AT char and the none AT char
struct uart_sw_flowctrl_t UART software flow control configuration parameters.
Public Members
uint8_t xon_char Xon flow control char
uint8_t xoff_char Xoff flow control char
uint8_t xon_thrd If the software flow control is enabled and the data amount in rxfifo is less than xon_thrd, an xon_char will be sent
uint8_t xoff_thrd If the software flow control is enabled and the data amount in rxfifo is more than xoff_thrd, an xoff_char will be sent
struct uart_config_t UART configuration parameters for uart_param_config function.
Public Members
int baud_rate UART baud rate
uart_word_length_t data_bits UART byte size
uart_parity_t parity UART parity mode
uart_stop_bits_t stop_bits UART stop bits
uart_hw_flowcontrol_t flow_ctrl UART HW flow control mode (cts/rts)
uint8_t rx_flow_ctrl_thresh UART HW RTS threshold
uart_sclk_t source_clk UART source clock selection
bool use_ref_tick Deprecated method to select ref tick clock source, set source_clk field instead
Type Definitions typedef int uart_port_t
UART port number, can be UART_NUM_0 ~ (UART_NUM_MAX -1).

Espressif Systems

762

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Enumerations enum uart_mode_t
UART mode selection.
Values:
UART_MODE_UART = 0x00 mode: regular UART mode
UART_MODE_RS485_HALF_DUPLEX = 0x01 mode: half duplex RS485 UART mode control by RTS pin
UART_MODE_IRDA = 0x02 mode: IRDA UART mode
UART_MODE_RS485_COLLISION_DETECT = 0x03 mode: RS485 collision detection UART mode (used for test purposes)
UART_MODE_RS485_APP_CTRL = 0x04 mode: application control RS485 UART mode (used for test purposes)
enum uart_word_length_t UART word length constants.
Values:
UART_DATA_5_BITS = 0x0 word length: 5bits
UART_DATA_6_BITS = 0x1 word length: 6bits
UART_DATA_7_BITS = 0x2 word length: 7bits
UART_DATA_8_BITS = 0x3 word length: 8bits
UART_DATA_BITS_MAX = 0x4
enum uart_stop_bits_t UART stop bits number.
Values:
UART_STOP_BITS_1 = 0x1 stop bit: 1bit
UART_STOP_BITS_1_5 = 0x2 stop bit: 1.5bits
UART_STOP_BITS_2 = 0x3 stop bit: 2bits
UART_STOP_BITS_MAX = 0x4
enum uart_parity_t UART parity constants.
Values:
UART_PARITY_DISABLE = 0x0 Disable UART parity
UART_PARITY_EVEN = 0x2 Enable UART even parity
UART_PARITY_ODD = 0x3 Enable UART odd parity

Espressif Systems

763

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

enum uart_hw_flowcontrol_t UART hardware flow control modes.
Values:
UART_HW_FLOWCTRL_DISABLE = 0x0 disable hardware flow control
UART_HW_FLOWCTRL_RTS = 0x1 enable RX hardware flow control (rts)
UART_HW_FLOWCTRL_CTS = 0x2 enable TX hardware flow control (cts)
UART_HW_FLOWCTRL_CTS_RTS = 0x3 enable hardware flow control
UART_HW_FLOWCTRL_MAX = 0x4
enum uart_signal_inv_t UART signal bit map.
Values:
UART_SIGNAL_INV_DISABLE = 0 Disable UART signal inverse
UART_SIGNAL_IRDA_TX_INV = (0x1 << 0) inverse the UART irda_tx signal
UART_SIGNAL_IRDA_RX_INV = (0x1 << 1) inverse the UART irda_rx signal
UART_SIGNAL_RXD_INV = (0x1 << 2) inverse the UART rxd signal
UART_SIGNAL_CTS_INV = (0x1 << 3) inverse the UART cts signal
UART_SIGNAL_DSR_INV = (0x1 << 4) inverse the UART dsr signal
UART_SIGNAL_TXD_INV = (0x1 << 5) inverse the UART txd signal
UART_SIGNAL_RTS_INV = (0x1 << 6) inverse the UART rts signal
UART_SIGNAL_DTR_INV = (0x1 << 7) inverse the UART dtr signal
enum uart_sclk_t UART source clock.
Values:
UART_SCLK_APB = 0x0 UART source clock from APB
UART_SCLK_RTC = 0x1 UART source clock from RTC
UART_SCLK_XTAL = 0x2 UART source clock from XTAL
GPIO Lookup Macros The UART peripherals have dedicated IO_MUX pins to which they are connected directly. However, signals can also be routed to other pins using the less direct GPIO matrix. To use direct routes, you need to know which pin is a dedicated IO_MUX pin for a UART channel. GPIO Lookup Macros simplify the process of

Espressif Systems

764

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

finding and assigning IO_MUX pins. You choose a macro based on either the IO_MUX pin number, or a required UART channel name, and the macro will return the matching counterpart for you. See some examples below.
Note: These macros are useful if you need very high UART baud rates (over 40 MHz), which means you will have to use IO_MUX pins only. In other cases, these macros can be ignored, and you can use the GPIO Matrix as it allows you to configure any GPIO pin for any UART function.
1. UART_NUM_2_TXD_DIRECT_GPIO_NUM returns the IO_MUX pin number of UART channel 2 TXD pin (pin 17)
2. UART_GPIO19_DIRECT_CHANNEL returns the UART number of GPIO 19 when connected to the UART peripheral via IO_MUX (this is UART_NUM_0)
3. UART_CTS_GPIO19_DIRECT_CHANNEL returns the UART number of GPIO 19 when used as the UART CTS pin via IO_MUX (this is UART_NUM_0). Similar to the above macro but specifies the pin function which is also part of the IO_MUX assignment.

Header File · components/soc/esp32s3/include/soc/uart_channel.h

Macros UART_GPIO1_DIRECT_CHANNEL UART_NUM_0_TXD_DIRECT_GPIO_NUM UART_GPIO3_DIRECT_CHANNEL UART_NUM_0_RXD_DIRECT_GPIO_NUM UART_GPIO19_DIRECT_CHANNEL UART_NUM_0_CTS_DIRECT_GPIO_NUM UART_GPIO22_DIRECT_CHANNEL UART_NUM_0_RTS_DIRECT_GPIO_NUM UART_TXD_GPIO1_DIRECT_CHANNEL UART_RXD_GPIO3_DIRECT_CHANNEL UART_CTS_GPIO19_DIRECT_CHANNEL UART_RTS_GPIO22_DIRECT_CHANNEL UART_GPIO10_DIRECT_CHANNEL UART_NUM_1_TXD_DIRECT_GPIO_NUM UART_GPIO9_DIRECT_CHANNEL UART_NUM_1_RXD_DIRECT_GPIO_NUM UART_GPIO6_DIRECT_CHANNEL UART_NUM_1_CTS_DIRECT_GPIO_NUM UART_GPIO11_DIRECT_CHANNEL UART_NUM_1_RTS_DIRECT_GPIO_NUM UART_TXD_GPIO10_DIRECT_CHANNEL UART_RXD_GPIO9_DIRECT_CHANNEL UART_CTS_GPIO6_DIRECT_CHANNEL UART_RTS_GPIO11_DIRECT_CHANNEL UART_GPIO17_DIRECT_CHANNEL

Espressif Systems

765

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
UART_NUM_2_TXD_DIRECT_GPIO_NUM UART_GPIO16_DIRECT_CHANNEL UART_NUM_2_RXD_DIRECT_GPIO_NUM UART_GPIO8_DIRECT_CHANNEL UART_NUM_2_CTS_DIRECT_GPIO_NUM UART_GPIO7_DIRECT_CHANNEL UART_NUM_2_RTS_DIRECT_GPIO_NUM UART_TXD_GPIO17_DIRECT_CHANNEL UART_RXD_GPIO16_DIRECT_CHANNEL UART_CTS_GPIO8_DIRECT_CHANNEL UART_RTS_GPIO7_DIRECT_CHANNEL
2.3.23 USB Device Driver
Overview
The driver allows users to use ESP32-S3 chips to develop USB devices on top the TinyUSB stack. TinyUSB is integrating with ESP-IDF to provide USB features of the framework. Using this driver the chip works as a composite device supporting to represent several USB devices simultaneously. Currently, only the communications device class (CDC) type of the device with the ACM (Abstract Control Model) subclass is supported.
Features
· Configuration of device and string USB descriptors · USB Serial Device (CDC-ACM) · Input and output through USB Serial Device
Hardware USB Connection
· Any board with the ESP32-S3 chip with USB connectors or with exposed USBns D+ and D- (DATA+/DATA-) pins.
If the board has no USB connector but has the pins, connect pins directly to the host (e.g. with do-it-yourself cable from any USB connection cable). On ESP32-S3, connect GPIO 20 and 19 to D+/D- respectively:

Espressif Systems

766

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Driver Structure
As the basis is used the TinyUSB stack.
On top of it the driver implements:
· Customization of USB descriptors · Serial device support · Redirecting of standard streams through the Serial device · Encapsulated driverns task servicing the TinyuSB

Configuration
Via Menuconfig options you can specify:
· Several of descriptorns parameters (see: Descriptors Configuration bellow) · USB Serial low-level Configuration · The verbosity of the TinyUSBns log · Disable the TinyUSB main task (for the custom implementation)

Descriptors Configuration The driverns descriptors are provided by the tinyusb_config_t structurens descriptor and string_descriptor members. Therefore, users should initialize tinyusb_config_t to their desired descriptor before calling tinyusb_driver_install() to install driver.
However, the driver also provides a default descriptor. The driver can be installed with the default descriptor by setting the descriptor and string_descriptor members of tinyusb_config_t to NULL before calling tinyusb_driver_install(). The driverns default descriptor is specified using Menuconfig, where the following fields should be configured:
· PID · VID · bcdDevice · Manufacturer · Product name · Name of CDC device if it is On · Serial number
If you want to use own descriptors with extended modification, you can define them during the driver installation process

Install Driver

To initialize the driver, users should call tinyusb_driver_install(). The driverns configuration is specified in a tinyusb_config_t structure that is passed as an argument to tinyusb_driver_install().
Note that the tinyusb_config_t structure can be zero initialized (e.g. tinyusb_config_t tusb_cfg = { 0 }) or partially (as shown below). For any member that is initialized to 0 or NULL, the driver will use its default configuration values for that member (see example below)

tinyusb_config_t partial_init = {

.descriptor = NULL;

//Uses default descriptor specified in Menuconfig

.string_descriptor = NULL; //Uses default string specified in Menuconfig

.external_phy = false;

}

Espressif Systems

767

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

USB Serial Device (CDC-ACM)
If the CDC option is enabled in Menuconfig, the USB Serial Device could be initialized with tusb_cdc_acm_init() according to the settings from tinyusb_config_cdcacm_t (see example below).
tinyusb_config_cdcacm_t amc_cfg = { .usb_dev = TINYUSB_USBDEV_0, .cdc_port = TINYUSB_CDC_ACM_0, .rx_unread_buf_sz = 64, .callback_rx = NULL, .callback_rx_wanted_char = NULL, .callback_line_state_changed = NULL, .callback_line_coding_changed = NULL
}; tusb_cdc_acm_init(&amc_cfg);
To specify callbacks you can either set the pointer to your tusb_cdcacm_callback_t function in the configuration structure or call tinyusb_cdcacm_register_callback() after initialization.

USB Serial Console The driver allows to redirect all standard application strings (stdin/out/err) to the USB Serial Device and return them to UART using esp_tusb_init_console()/esp_tusb_deinit_console() functions.

Application Examples The table below describes the code examples available in the directory peripherals/usb/.

Code Example

Description

peripherals/usb/device/tusb_console How to set up ESP32-S3 chip to get log output via Serial Device connec-

tion

peripherals/usb/device/tusb_sample_descHriopwtotro set up ESP32-S3 chip to work as a Generic USB Device with a

user-defined descriptor

peripherals/usb/device/tusb_serial_devicHe ow to set up ESP32-S3 chip to work as a USB Serial Device

API Reference
Header File
· components/tinyusb/additions/include/tinyusb.h
Functions esp_err_t tinyusb_driver_install(const tinyusb_config_t *config)
This is an all-in-one helper function, including:
1. USB device driver initialization 2. Descriptors preparation 3. TinyUSB stack initialization 4. Creates and start a task to handle usb events
Note Donnt change Custom descriptor, but if it has to be done, Suggest to define as follows in order to match the Interface Association Descriptor (IAD): bDeviceClass = TUSB_CLASS_MISC, bDeviceSubClass = MISC_SUBCLASS_COMMON,
Parameters · config: tinyusb stack specific configuration
Return Value · ESP_ERR_INVALID_ARG: Install driver and tinyusb stack failed because of invalid argument

Espressif Systems

768

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_FAIL: Install driver and tinyusb stack failed because of internal error · ESP_OK: Install driver and tinyusb stack successfully

Structures struct tinyusb_config_t
Configuration structure of the tinyUSB core.

Public Members
tusb_desc_device_t *descriptor Pointer to a device descriptor
const char **string_descriptor Pointer to an array of string descriptors
bool external_phy Should USB use an external PHY

Header File · components/tinyusb/additions/include/tinyusb_types.h

Macros USB_ESPRESSIF_VID USB_STRING_DESCRIPTOR_ARRAY_SIZE

Enumerations enum tinyusb_usbdev_t
Values:
TINYUSB_USBDEV_0

Header File · components/tinyusb/additions/include/tusb_cdc_acm.h

Functions esp_err_t tusb_cdc_acm_init(const tinyusb_config_cdcacm_t *cfg)
Initialize CDC ACM. Initialization will be finished with the tud_cdc_line_state_cb callback.

Return esp_err_t Parameters
· cfg: - init configuration structure esp_err_t tinyusb_cdcacm_register_callback(tinyusb_cdcacm_itf_t itf, cdcacm_event_type_t
event_type, tusb_cdcacm_callback_t callback) Register a callback invoking on CDC event. If the callback had been already registered, it will be overwritten.

Return esp_err_t - ESP_OK or ESP_ERR_INVALID_ARG Parameters
· itf: - number of a CDC object · event_type: - type of registered event for a callback · callback: - callback function

esp_err_t tinyusb_cdcacm_unregister_callback(tinyusb_cdcacm_itf_t

itf,

cd-

cacm_event_type_t event_type)

Unregister a callback invoking on CDC event.

Return esp_err_t - ESP_OK or ESP_ERR_INVALID_ARG

Espressif Systems

769

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Parameters · itf: - number of a CDC object · event_type: - type of registered event for a callback
size_t tinyusb_cdcacm_write_queue_char(tinyusb_cdcacm_itf_t itf, char ch) Sent one character to a write buffer.
Return size_t - amount of queued bytes Parameters
· itf: - number of a CDC object · ch: - character to send
size_t tinyusb_cdcacm_write_queue(tinyusb_cdcacm_itf_t itf, const uint8_t *in_buf, size_t in_size)
Write data to write buffer from a byte array.
Return size_t - amount of queued bytes Parameters
· itf: - number of a CDC object · in_buf: - a source array · in_size: - size to write from arr_src
esp_err_t tinyusb_cdcacm_write_flush(tinyusb_cdcacm_itf_t itf, uint32_t timeout_ticks) Send all data from a write buffer. Use tinyusb_cdcacm_write_queue to add data to the buffer.
WARNING! TinyUSB can block output Endpoint for several RX callbacks, after will do additional flush
after the each trasfer. That can leads to the situation when you requested a flush, but it will fail until
ont of the next callbacks ends. SO USING OF THE FLUSH WITH TIMEOUTS IN CALLBACKS IS NOT RECOMENDED - YOU CAN GET A LOCK FOR THE TIMEOUT
Return esp_err_t - ESP_OK if (timeout_ticks > 0) and and flush was successful, ESP_ERR_TIMEOUT if timeout occurred3 or flush was successful with (timeout_ticks == 0) ESP_FAIL if flush was unsuccessful
Parameters · itf: - number of a CDC object · timeout_ticks: - waiting until flush will be considered as failed
esp_err_t tinyusb_cdcacm_read(tinyusb_cdcacm_itf_t itf, uint8_t *out_buf, size_t out_buf_sz, size_t *rx_data_size)
Read a content to the array, and defines itns size to the sz_store.
Return esp_err_t ESP_OK, ESP_FAIL or ESP_ERR_INVALID_STATE Parameters
· itf: - number of a CDC object · out_buf: - to this array will be stored the object from a CDC buffer · out_buf_sz: - size of buffer for results · rx_data_size: - to this address will be stored the objectns size
bool tusb_cdc_acm_initialized(tinyusb_cdcacm_itf_t itf) Check if the ACM initialized.
Return true or false Parameters
· itf: - number of a CDC object
Structures struct cdcacm_event_rx_wanted_char_data_t
Data provided to the input of the callback_rx_wanted_char callback.

Espressif Systems

770

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Public Members
char wanted_char Wanted character
struct cdcacm_event_line_state_changed_data_t Data provided to the input of the callback_line_state_changed callback.
Public Members
bool dtr Data Terminal Ready (DTR) line state
bool rts Request To Send (RTS) line state
struct cdcacm_event_line_coding_changed_data_t Data provided to the input of the line_coding_changed callback.
Public Members
const cdc_line_coding_t *p_line_coding New line coding value
struct cdcacm_event_t Describes an event passing to the input of a callbacks.
Public Members
cdcacm_event_type_t type Event type
cdcacm_event_rx_wanted_char_data_t rx_wanted_char_data Data input of the callback_rx_wanted_char callback
cdcacm_event_line_state_changed_data_t line_state_changed_data Data input of the callback_line_state_changed callback
cdcacm_event_line_coding_changed_data_t line_coding_changed_data Data input of the line_coding_changed callback
struct tinyusb_config_cdcacm_t Configuration structure for CDC-ACM.
Public Members
tinyusb_usbdev_t usb_dev Usb device to set up
tinyusb_cdcacm_itf_t cdc_port CDC port
size_t rx_unread_buf_sz Amount of data that can be passed to the AMC at once
tusb_cdcacm_callback_t callback_rx Pointer to the function with the tusb_cdcacm_callback_t type that will be handled as a callback
tusb_cdcacm_callback_t callback_rx_wanted_char Pointer to the function with the tusb_cdcacm_callback_t type that will be handled as a callback

Espressif Systems

771

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
tusb_cdcacm_callback_t callback_line_state_changed Pointer to the function with the tusb_cdcacm_callback_t type that will be handled as a callback
tusb_cdcacm_callback_t callback_line_coding_changed Pointer to the function with the tusb_cdcacm_callback_t type that will be handled as a callback
Type Definitions typedef void (*tusb_cdcacm_callback_t)(int itf, cdcacm_event_t *event)
CDC-ACM callback type.
Enumerations enum tinyusb_cdcacm_itf_t
CDC ports available to setup. Values: TINYUSB_CDC_ACM_0 = 0x0 TINYUSB_CDC_ACM_1 TINYUSB_CDC_ACM_MAX enum cdcacm_event_type_t Types of CDC ACM events. Values: CDC_EVENT_RX CDC_EVENT_RX_WANTED_CHAR CDC_EVENT_LINE_STATE_CHANGED CDC_EVENT_LINE_CODING_CHANGED
Header File · components/tinyusb/additions/include/tusb_console.h
Functions esp_err_t esp_tusb_init_console(int cdc_intf)
Redirect output to the USB serial. Return esp_err_t - ESP_OK, ESP_FAIL or an error code Parameters
· cdc_intf: - interface number of TinyUSBns CDC esp_err_t esp_tusb_deinit_console(int cdc_intf)
Switch log to the default output. Return esp_err_t Parameters
· cdc_intf: - interface number of TinyUSBns CDC
Header File · components/tinyusb/additions/include/tusb_tasks.h

Espressif Systems

772

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Functions esp_err_t tusb_run_task(void)
This helper function creates and starts a task which wraps tud_task(). The wrapper function basically wraps tud_task and some log. Default parameters: stack size and priority as configured, argument = NULL, not pinned to any core. If you have more requirements for this task, you can create your own task which calls tud_task as the last step. Return Value
· ESP_OK: run tinyusb main task successfully · ESP_FAIL: run tinyusb main task failed of internal error · ESP_ERR_INVALID_STATE: tinyusb main task has been created before esp_err_t tusb_stop_task(void) This helper function stops and destroys the task created by tusb_run_task() Return Value · ESP_OK: stop and destory tinyusb main task successfully · ESP_ERR_INVALID_STATE: tinyusb main task hasnnt been created yet
Header File · components/tinyusb/additions/include/vfs_tinyusb.h
Functions esp_err_t esp_vfs_tusb_cdc_register(int cdc_intf, char const *path)
Register TinyUSB CDC at VFS with path. Return esp_err_t ESP_OK or ESP_FAIL Parameters
· cdc_intf: - interface number of TinyUSBns CDC · path: - path where the CDC will be registered, /dev/tusb_cdc will be used if left NULL. esp_err_t esp_vfs_tusb_cdc_unregister(char const *path) Unregister TinyUSB CDC from VFS. Return esp_err_t ESP_OK or ESP_FAIL Parameters · path: - path where the CDC will be unregistered if NULL will be used /dev/tusb_cdc
2.3.24 USB Host
Warning: The USB Host Library API is a beta version thus is subject to change.
The document provides information regarding the USB Host Library. This document is split into the following sections:
Sections
· USB Host ­ Overview ­ Architecture ­ Usage ­ Examples ­ API Reference

Espressif Systems

773

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Overview
The USB Host Library (hereinafter referred to as the Host Library) is the lowest public facing API layer of the ESP-IDF USB Host Stack. In most cases, applications that require USB Host functionality will not need to interface with the Host Library directly. Instead, most applications will use the API provided by a host class driver that is implemented on top of the Host Library. However, users may want to use the Host Library directly for some of (but not limited to) the following reasons:
· The user needs to implement a custom host class driver such as a vendor specific class driver · The user has a requirement for a lower level of abstraction due to resource/latency requirements
Features & Limitations The Host Library has the following features: · Supports Full Speed (FS) and Low Speed (LS) Devices · Supports all four transfer types (Control, Bulk, Interrupt, and Isochronous) · Allows multiple class drivers to run simultaneously (i.e., multiple clients of the Host Library) · A single device can be used by multiple clients simultaneously (e.g., composite devices) · The Host Library itself (and the underlying Host Stack) does not internally instantiate any OS tasks. The number of tasks are entirely controlled by how the Host Library interface is used. However, a general rule of thumb regarding the number of tasks is (the number of host class drivers running + 1).
Currently, the Host Library (and the underlying Host Stack) has the following limitations: · Only supports a single device, but the Host Libraryns API is designed for multiple device support. · Only supports Asynchronous transfers · Transfer timeouts are not supported yet
Architecture

Fig. 22: Diagram of the key entities involved in USB Host functionality
The diagram above shows the key entities that are involved when implementing USB Host functionality. These entities are:

Espressif Systems

774

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· The Host Library · Clients of the Host Library · Devices · Host Library Daemon Task

Host Library The Host Library is the a lowest public facing layer of the USB Host Stack. Any other IDF component (such as a class driver or a user component) that needs to communicate with a connected USB device can only do so using the Host Library API either directly or indirectly.
The Host Libraryns API is split into two sub-sets, namely the Library API and Client API.
· The Client API handles the communication between a client of the Host Library and one or more USB devices. The Client API should only be called by registered clients of the Host Library.
· The Library API handles all of the Host Library processing that is not specific to a single client (e.g., device enumeration). Usually, the library API is called by a Host Library Daemon Task.

Clients A client of the Host Library is a software component (such as a host class driver or user component) that uses the Host Library to communicate with a USB device. Generally each client has a one-to-one relation with a task, meaning that for a particular client, all of its Client API calls should be done from the context of the same task.
By organizing the software components that use the Host Libraryns into clients, the Host Library can delegate the handling of all client events (i.e., the events specific to that client) to the clientns task. In other words, each client task is responsible for all the required processing and event handling associated with the USB communication that the client initiates.

Daemon Task Although the Host Library delegates the handling of client events to the clients themselves, there are still Library events (i.e., events that are not specific to a client) that need to be handled. Library event handling can include things such as:
· Handling USB device connection, enumeration, and disconnection · Rerouting control transfers to/from clients · Forwarding events to clients
Therefore, in addition to the client tasks, the Host Library also requires a task (usually the Host Library Daemon Task) to handle all of the library events.

Devices The Host Library hides the details of device handling (such as connection, memory allocation, and enumeration) from the clients. The clients are provided only with a list of already connected and enumerated devices to choose from. During enumeration, each device is configured to use configuration 1.
It is possible for a two or more clients to simultaneously communicate with the same device as long as they are not communicating to the same interface. However, multiple clients can simultaneously communicate with the same devicens default endpoint (EP0), which will result in their control transfers being serialized.
For a client to communicate with a device, the client must:
1. Open the device using the devicens address. This lets the Host Library know that the client is using that device. 2. Claim the interface(s) that will be used for communication. This prevents other clients from claiming the same
interface(s). 3. Send transfers to the endpoints in the claimed interface. The clientns task is responsible for handling its own
processing and events.

Usage
The Host Library (and the underlying Host Stack) will not create any tasks. All tasks (i.e., the client tasks and the Daemon Task) will need to be created by the class drivers or the user. Instead, the Host Library provides two event handler functions that will handle all of the required Host Library processing, thus these functions should be called repeatedly from the client tasks and the Daemon Task. Therefore, the implementation of client tasks and the Daemon Task will be the largely centered around the invocation of these event handler functions.

Espressif Systems

775

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Host Library & Daemon Task
Basic Usage The Host Library API provides usb_host_lib_handle_events() to handle library events. This function should be called repeatedly, typically from the daemon task. Some notable features regarding usb_host_lib_handle_events() are:
· The function can block until a library event needs handling · Event flags are returned on each invocation. These event flags are useful for knowing when the Host Library
can be uninstalled.
A bare-bones Daemon Task would resemble something like the following code snippet:
#include "usb/usb_host.h"
void daemon_task(void *arg) {
... bool exit = false; while (!exit) {
uint32_t event_flags; usb_host_lib_handle_events(portMAX_DELAY, &event_flags); if (event_flags & USB_HOST_LIB_EVENT_FLAGS_NO_CLIENTS) {
... } if (event_flags & USB_HOST_LIB_EVENT_FLAGS_ALL_FREE) {
... } ... } ... }
Note: See the peripherals/usb/host/usb_host_lib example for a full implementation of the Daemon Task

Fig. 23: Graph of Typical USB Host Library Lifecycle
Lifecycle The graph above illustrates the typical lifecycle of the Host Library with multiple clients and devices. Specifically, the example involvesl
· two registered clients (Client 1 and Client 2) · two connected devices (Device 1 and Device 2), where Client 1 communicates with Device 1 and Client 2
communicates with Device 2.

Espressif Systems

776

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

With reference the graph above, the typical lifecycle involves the following key stages.
1. The Host Library is installed by calling usb_host_install(). · Installation must be done before any other Host Library API is called. · Where usb_host_install() is called (e.g., from the Daemon Task or another task) will depend on the synchronization logic between the Daemon Task, client tasks, and the rest of the system.
2. Once the Host Library is installed, the clients can be registered by calling usb_host_client_register().
· This is typically called from the client task (where the client task waits for a signal from the Daemon Task).
· This can be called elsewhere if necessary as long it is called after usb_host_install(). 3. Device 1 connects and is then enumerated.
· Each registered client (in this case Client 1 and Client 2) are notified of the new device by way of the USB_HOST_CLIENT_EVENT_NEW_DEV event.
· Client 1 opens Device 1 and begins communication with it. 4. Similarly Device 2 connects and is enumerated.
· Client 1 and 2 are notified of a new device (via a USB_HOST_CLIENT_EVENT_NEW_DEV event). · Client 2 opens Device 2 and begins communication with it. 5. Device 1 suddenly disconnects. · Client 1 is notified by way of USB_HOST_CLIENT_EVENT_DEV_GONE and begins its cleanup. · Client 2 is not notified as it has not opened Device 1. 6. Client 1 completes its clean up and deregisters by calling usb_host_client_deregister(). · This is typically called from the client task before the task exits. · This can be called elsewhere if necessary as long as Client 1 has already completed its clean up. 7. Client 2 completes its communication with Device 2. Client 2 then closes Device 2 and deregisters itself.
· The Daemon Task is notified of the deregistration of all clients by way the USB_HOST_LIB_EVENT_FLAGS_NO_CLIENTS event flag as Client 2 is the last client to deregister.
· Device 2 is still allocated (i.e., not freed) as it is still connected albeit not currently opened by any client.
8. The Daemon Task decides to cleanup as there are no more clients. · The Daemon Task must free Device 2 first by calling usb_host_device_free_all(). · If usb_host_device_free_all() was able to free all devices, the function will return ESP_OK indicating that all devices have been freed. · If usb_host_device_free_all() was unable to free all devices (e.g., because the device is still opened by a client), the function will return ESP_ERR_NOT_FINISHED. · The Daemon Task must wait for usb_host_lib_handle_events() to return the USB_HOST_LIB_EVENT_FLAGS_ALL_FREE event flag in order to know when all devices have been freed.
9. Once the Daemon Task has verified that all clients have deregistered and all devices have been freed, it can now uninstall the Host Library by calling usb_host_uninstall().

Clients & Class Driver

Basic Usage The Host Library API provides usb_host_client_handle_events() to handle a particular clientns events. This function should be called repeatedly, typically from the clientns task. Some notable features regarding usb_host_client_handle_events() are:
· The function can block until a client event needs handling · The functionns primary purpose is to call the various event handling callbacks when a client event occurs.
The following callbacks are called from within usb_host_client_handle_events() thus allowing the client task to be notified of events.
· The client event callback of type usb_host_client_event_cb_t which delivers client event messages to the client. Client event messages indicate events such as the addition or removal of a device.
· The USB transfer completion callback of type usb_transfer_cb_t which indicates that a particular USB transfer previously submitted by the client has completed.

Espressif Systems

777

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Note: Given that the callbacks are called from within usb_host_client_handle_events(), users should avoid blocking from within the callbacks as this will result in usb_host_client_handle_events() being blocked as well, thus preventing other pending client events from being handled.

The following code snippet demonstrates a bare-bones host class driver and its client task. The code snippet contains:
· A simple client task function client_task that calls usb_host_client_handle_events() in a loop.
· Implementations of a client event callback and transfer completion callbacks. · Implementation of a simple state machine for the class driver. The class driver simply opens a device, sends
an OUT transfer to EP1, then closes the device.
#include <string.h> #include "usb/usb_host.h"

#define CLASS_DRIVER_ACTION_OPEN_DEV #define CLASS_DRIVER_ACTION_TRANSFER #define CLASS_DRIVER_ACTION_CLOSE_DEV

0x01 0x02 0x03

struct class_driver_control { uint32_t actions; uint8_t dev_addr; usb_host_client_handle_t client_hdl; usb_device_handle_t dev_hdl;
};

static void client_event_cb(const usb_host_client_event_msg_t *event_msg, void *arg) {
//This is function is called from within usb_host_client_handle_events(). Don 't block and try to keep it short
struct class_driver_control *class_driver_obj = (struct class_driver_control *)arg;
switch (event_msg->event) { case USB_HOST_CLIENT_EVENT_NEW_DEV: class_driver_obj->actions |= CLASS_DRIVER_ACTION_OPEN_DEV; class_driver_obj->dev_addr = event_msg->new_dev.address; //Store the
address of the new device break;
case USB_HOST_CLIENT_EVENT_DEV_GONE: class_driver_obj->actions |= CLASS_DRIVER_ACTION_CLOSE_DEV; break;
default: break;
} }

static void transfer_cb(usb_transfer_t *transfer) {
//This is function is called from within usb_host_client_handle_events(). Don 't block and try to keep it short
struct class_driver_control *class_driver_obj = (struct class_driver_control *)transfer->context;
printf("Transfer status %d, actual number of bytes transferred %d\n", transfer>status, transfer->actual_num_bytes);
class_driver_obj->actions |= CLASS_DRIVER_ACTION_CLOSE_DEV; }

void client_task(void *arg) {
... //Wait until Host Library is installed

(continues on next page)

Espressif Systems

778

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)
//Initialize class driver objects struct class_driver_control class_driver_obj = {0}; //Register the client usb_host_client_config_t client_config = {
.is_synchronous = false, .max_num_event_msg = 5, .async = {
.client_event_callback = client_event_cb, .callback_arg = &class_driver_obj, } }; usb_host_client_register(&client_config, &class_driver_obj.client_hdl); //Allocate a USB transfer usb_transfer_t *transfer; usb_host_transfer_alloc(1024, 0, &transfer);
//Event handling loop bool exit = false; while (!exit) {
//Call the client event handler function usb_host_client_handle_events(class_driver_obj.client_hdl, portMAX_DELAY); //Execute pending class driver actions if (class_driver_obj.actions & CLASS_DRIVER_ACTION_OPEN_DEV) {
//Open the device and claim interface 1 usb_host_device_open(class_driver_obj.client_hdl, class_driver_obj.dev_ addr, &class_driver_obj.dev_hdl); usb_host_interface_claim(class_driver_obj.client_hdl, class_driver_obj. dev_hdl, 1, 0); } if (class_driver_obj.actions & CLASS_DRIVER_ACTION_TRANSFER) { //Send an OUT transfer to EP1 memset(transfer->data_buffer, 0xAA, 1024); transfer->num_bytes = 1024; transfer->device_handle = class_driver_obj.dev_hdl; transfer->bEndpointAddress = 0x01; transfer->callback = transfer_cb; transfer->context = (void *)&class_driver_obj; usb_host_transfer_submit(transfer); } if (class_driver_obj.actions & CLASS_DRIVER_ACTION_CLOSE_DEV) { //Release the interface and close the device usb_host_interface_release(class_driver_obj.client_hdl, class_driver_ obj.dev_hdl, 1); usb_host_device_close(class_driver_obj.client_hdl, class_driver_obj. dev_hdl); exit = true; } ... //Handle any other actions required by the class driver }
//Cleanup class driver usb_host_transfer_free(transfer); usb_host_client_deregister(class_driver_obj.client_hdl); ... //Delete the task and any other signal Daemon Task if required }

Note: An actual host class driver will likely supported many more features, thus will have a much more complex state machine. A host class driver will likely also need to:
· Be able to open multiple devices · Parse an opened devicens descriptors to identify if the device is of the target class

Espressif Systems

779

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· Communicate with multiple endpoints of an interface in a particular order · Claim multiple interfaces of a device · Handle various errors

Lifecycle The typical life cycle of a client task and class driver will go through the following stages:
1. Wait for some signal regarding the Host Library being installed. 2. Register the client via usb_host_client_register() and allocate any other class driver resources
(e.g., allocating transfers using usb_host_transfer_alloc()). 3. For each new device that the class driver needs to communicate with:
a. Check if the device is already connected via usb_host_device_addr_list_fill(). b. If the device is not already connected, wait for a USB_HOST_CLIENT_EVENT_NEW_DEV event from
the client event callback. c. Open the device via usb_host_device_open(). d. Parse the device and configuration descriptors via usb_host_get_device_descriptor() and
usb_host_get_active_config_descriptor() respectively. e. Claim the necessary interfaces of the device via usb_host_interface_claim(). 4. Submit transfers to the device via usb_host_transfer_submit() or usb_host_transfer_submit_control(). 5. Once an opened device is no longer needed by the class driver, or has disconnected (as indicated by a USB_HOST_CLIENT_EVENT_DEV_GONE event): a. Stop any previously submitted transfers to the devicens endpoints by calling
usb_host_endpoint_halt() and usb_host_endpoint_flush() on those endpoints. b. Release all previously claimed interfaces via usb_host_interface_release(). c. Close the device via usb_host_device_close(). 6. Deregister the client via usb_host_client_deregister() and free any other class driver resources. 7. Delete the client task. Signal the Daemon Task if necessary.

Examples
Host Library Examples The peripherals/usb/host/usb_host_lib demonstrates basic usage of the USB Host Libraryns API to implement a pseudo class driver.

Class Driver Examples The USB Host Stack provides a number examples that implement host class drivers using the Host Libraryns API.

CDC-ACM
· A host class driver for the Communication Device Class (Abstract Control Model) is currently implemented as an example component (found via peripherals/usb/host/cdc/common/cdc_acm_host).
· The peripherals/usb/host/cdc/cdc_acm_host example uses the CDC-ACM host driver component to communicate with CDC-ACM devices
· The peripherals/usb/host/cdc/cdc_acm_bg96 example uses the CDC-ACM host driver component to communicate with non-compliant CDC-ACM devices (i.e., vendor-specific classes that support a subset of CDC-ACM features) such as the Quectel BG96 modem.

MSC
· A host class driver for the Mass Storage Class (Bulk-Only Transport) is current implemented as an example found via peripherals/usb/host/msc.

API Reference
The API of the USB Host Library is separated into the following header files. However, it is sufficient for applications to only #include "usb/usb_host.h" and all of USB Host Library headers will also be included.

Espressif Systems

780

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· usb/include/usb/usb_host.h contains the functions and types of the USB Host Library · usb/include/usb/usb_helpers.h contains various helper functions that are related to the USB protocol such as
descriptor parsing. · usb/include/usb/usb_types_stack.h contains types that are are used across multiple layers of the USB Host
stack. · usb/include/usb/usb_types_ch9.h contains types and macros related to Chapter 9 of the USB2.0 specification
(i.e., descriptors and standard requests).
Header File
· components/usb/include/usb/usb_host.h
Functions esp_err_t usb_host_install(const usb_host_config_t *config)
Install the USB Host Library.
· This function should only once to install the USB Host Library · This function should be called before any other USB Host Library functions are called
Note If skip_phy_setup is set in the install configuration, the user is responsible for ensuring that the underlying Host Controller is enabled and the USB PHY (internal or external) is already setup before this function is called.
Return esp_err_t Parameters
· [in] config: USB Host Library configuration esp_err_t usb_host_uninstall(void)
Uninstall the USB Host Library.
· This function should be called to uninstall the USB Host Library, thereby freeing its resources · All clients must have been deregistered before calling this function · All devices must have been freed by calling usb_host_device_free_all() and receiving the
USB_HOST_LIB_EVENT_FLAGS_ALL_FREE event flag
Note If skip_phy_setup was set when the Host Library was installed, the user is responsible for disabling the underlying Host Controller and USB PHY (internal or external).
Return esp_err_t
esp_err_t usb_host_lib_handle_events(TickType_t timeout_ticks, uint32_t *event_flags_ret) Handle USB Host Library events.
· This function handles all of the USB Host Libraryns processing and should be called repeatedly in a loop · Check event_flags_ret to see if an flags are set indicating particular USB Host Library events · This function should never be called by multiple threads simultaneously
Note This function can block Return esp_err_t Parameters
· [in] timeout_ticks: Timeout in ticks to wait for an event to occur · [out] event_flags_ret: Event flags that indicate what USB Host Library event occurred.
esp_err_t usb_host_lib_unblock(void) Unblock the USB Host Library handler.
· This function simply unblocks the USB Host Library event handling function (usb_host_lib_handle_events())
Return esp_err_t
esp_err_t usb_host_lib_info(usb_host_lib_info_t *info_ret) Get current information about the USB Host Library.
Return esp_err_t Parameters

Espressif Systems

781

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· [out] info_ret: USB Host Library Information

esp_err_t usb_host_client_register(const

usb_host_client_config_t

usb_host_client_handle_t *client_hdl_ret) Register a client of the USB Host Library.

*client_config,

· This function registers a client of the USB Host Library · Once a client is registered, its processing function usb_host_client_handle_events() should be called re-
peatedly

Return esp_err_t Parameters
· [in] client_config: Client configuration · [out] client_hdl_ret: Client handle

esp_err_t usb_host_client_deregister(usb_host_client_handle_t client_hdl) Deregister a USB Host Library client.

· This function deregisters a client of the USB Host Library · The client must have closed all previously opened devices before attempting to deregister

Return esp_err_t Parameters
· [in] client_hdl: Client handle

esp_err_t usb_host_client_handle_events(usb_host_client_handle_t client_hdl, TickType_t timeout_ticks)
USB Host Library client processing function.

· This function handles all of a clientns processing and should be called repeatedly in a loop · For a particular client, this function should never be called by multiple threads simultaneously

Note This function can block Return esp_err_t Parameters
· [in] client_hdl: Client handle · [in] timeout_ticks: Timeout in ticks to wait for an event to occur

esp_err_t usb_host_client_unblock(usb_host_client_handle_t client_hdl) Unblock a client.

· This function simply unblocks a client if it is blocked on the usb_host_client_handle_events() function. · This function is useful when need to unblock a client in order to deregister it.

Return esp_err_t Parameters
· [in] client_hdl: Client handle

esp_err_t usb_host_device_open(usb_host_client_handle_t client_hdl,

Open a device.

usb_device_handle_t *dev_hdl_ret)

uint8_t dev_addr,

· This function allows a client to open a device · A client must open a device first before attempting to use it (e.g., sending transfers, device requests etc.)

Return esp_err_t Parameters
· [in] client_hdl: Client handle · [in] dev_addr: Devicens address · [out] dev_hdl_ret: Devicens handle

esp_err_t usb_host_device_close(usb_host_client_handle_t

Close a device.

dev_hdl)

client_hdl,

usb_device_handle_t

· This function allows a client to close a device · A client must close a device after it has finished using the device (claimed interfaces must also be released) · A client must close all devices it has opened before deregistering

Espressif Systems

782

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Note This function can block Return esp_err_t Parameters
· [in] client_hdl: Client handle · [in] dev_hdl: Device handle

esp_err_t usb_host_device_free_all(void) Indicate that all devices can be freed when possible.

· This function marks all devices as waiting to be freed · If a device is not opened by any clients, it will be freed immediately · If a device is opened by at least one client, the device will be free when the last client closes that device. · Wait for the USB_HOST_LIB_EVENT_FLAGS_ALL_FREE flag to be set by
usb_host_lib_handle_events() in order to know when all devices have been freed · This function is useful when cleaning up devices before uninstalling the USB Host Library

Return · ESP_ERR_NOT_FINISHED: There are one or more devices that still need to be freed. Wait for USB_HOST_LIB_EVENT_FLAGS_ALL_FREE event · ESP_OK: All devices already freed (i.e., there were no devices) · Other: Error

esp_err_t usb_host_device_addr_list_fill(int list_len, uint8_t *dev_addr_list, int

Fill a list of device address.

*num_dev_ret)

· This function fills an empty list with the address of connected devices · The Device addresses can then used in usb_host_device_open() · If there are more devices than the list_len, this function will only fill up to list_len number of devices.

Return esp_err_t Parameters
· [in] list_len: Length of the empty list · [inout] dev_addr_list: Empty list to be filled · [out] num_dev_ret: Number of devices

esp_err_t usb_host_device_info(usb_device_handle_t dev_hdl, usb_device_info_t *dev_info) Get devicens information.

· This function gets some basic information of a device · The device must be opened first before attempting to get its information

Note This function can block Return esp_err_t Parameters
· [in] dev_hdl: Device handle · [out] dev_info: Device information

esp_err_t usb_host_get_device_descriptor(usb_device_handle_t

dev_hdl,

Get devicens device descriptor.

usb_device_desc_t **device_desc)

const

· A client must call usb_host_device_open() first · No control transfer is sent. The devicens descriptor is cached on enumeration · This function simple returns a pointer to the cached descriptor

Note No control transfer is sent. The devicens descriptor is cached on enumeration Return esp_err_t Parameters
· [in] dev_hdl: Device handle · [out] device_desc: Device descriptor

esp_err_t usb_host_get_active_config_descriptor(usb_device_handle_t dev_hdl, const
usb_config_desc_t **config_desc) Get devicens active configuration descriptor.

Espressif Systems

783

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· A client must call usb_host_device_open() first · No control transfer is sent. The devicens active configuration descriptor is cached on enumeration · This function simple returns a pointer to the cached descriptor
Note This function can block Note No control transfer is sent. A devicens active configuration descriptor is cached on enumeration Return esp_err_t Parameters
· [in] dev_hdl: Device handle · [out] config_desc: Configuration descriptor
esp_err_t usb_host_interface_claim(usb_host_client_handle_t client_hdl, usb_device_handle_t dev_hdl, uint8_t bInterfaceNumber, uint8_t bAlternateSetting)
Function for a client to claim a devicens interface.
· A client must claim a devicens interface before attempting to communicate with any of its endpoints · Once an interface is claimed by a client, it cannot be claimed by any other client.
Note This function can block Return esp_err_t Parameters
· [in] client_hdl: Client handle · [in] dev_hdl: Device handle · [in] bInterfaceNumber: Interface number · [in] bAlternateSetting: Interface alternate setting number
esp_err_t usb_host_interface_release(usb_host_client_handle_t client_hdl, usb_device_handle_t dev_hdl, uint8_t bInterfaceNumber)
Function for a client to release a previously claimed interface.
· A client should release a devicens interface after it no longer needs to communicate with the interface · A client must release all of its interfaces of a device it has claimed before being able to close the device
Note This function can block Return esp_err_t Parameters
· [in] client_hdl: Client handle · [in] dev_hdl: Device handle · [in] bInterfaceNumber: Interface number
esp_err_t usb_host_endpoint_halt(usb_device_handle_t dev_hdl, uint8_t bEndpointAddress) Halt a particular endpoint.
· The device must have been opened by a client · The endpoint must be part of an interface claimed by a client · Once halted, the endpoint must be cleared using usb_host_endpoint_clear() before it can communicate
again
Note This function can block Return esp_err_t Parameters
· dev_hdl: Device handle · bEndpointAddress: Endpoint address
esp_err_t usb_host_endpoint_flush(usb_device_handle_t dev_hdl, uint8_t bEndpointAddress) Flush a particular endpoint.
· The device must have been opened by a client · The endpoint must be part of an interface claimed by a client · The endpoint must have been halted (either through a transfer error, or usb_host_endpoint_halt()) · Flushing an endpoint will caused an queued up transfers to be canceled
Note This function can block Return esp_err_t

Espressif Systems

784

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Parameters · dev_hdl: Device handle · bEndpointAddress: Endpoint address

esp_err_t usb_host_endpoint_clear(usb_device_handle_t dev_hdl, uint8_t bEndpointAddress) Clear a halt on a particular endpoint.

· The device must have been opened by a client · The endpoint must be part of an interface claimed by a client · The endpoint must have been halted (either through a transfer error, or usb_host_endpoint_halt()) · If the endpoint has any queued up transfers, clearing a halt will resume their execution

Note This function can block Return esp_err_t Parameters
· dev_hdl: Device handle · bEndpointAddress: Endpoint address

esp_err_t usb_host_transfer_alloc(size_t data_buffer_size, int num_isoc_packets, usb_transfer_t

Allocate a transfer object.

**transfer)

· This function allocates a transfer object · Each transfer object has a fixed sized buffer specified on allocation · A transfer object can be re-used indefinitely · A transfer can be submitted using usb_host_transfer_submit() or usb_host_transfer_submit_control()

Return esp_err_t Parameters
· [in] data_buffer_size: Size of the transferns data buffer · [in] num_isoc_packets: Number of isochronous packets in transfer (set to 0 for non-
isochronous transfers) · [out] transfer: Transfer object

esp_err_t usb_host_transfer_free(usb_transfer_t *transfer) Free a transfer object.

· Free a transfer object previously allocated using usb_host_transfer_alloc() · The transfer must not be in-flight when attempting to free it · If a NULL pointer is passed, this function will simply return ESP_OK

Return esp_err_t Parameters
· [in] transfer: Transfer object

esp_err_t usb_host_transfer_submit(usb_transfer_t *transfer) Submit a non-control transfer.

· Submit a transfer to a particular endpoint. The device and endpoint number is specified inside the transfer · The transfer must be properly initialized before submitting · On completion, the transferns callback will be called from the clientns usb_host_client_handle_events()
function.

Return esp_err_t Parameters
· [in] transfer: Initialized transfer object

esp_err_t usb_host_transfer_submit_control(usb_host_client_handle_t

Submit a control transfer.

usb_transfer_t *transfer)

client_hdl,

· Submit a control transfer to a particular device. The client must have opened the device first · The transfer must be properly initialized before submitting. The first 8 bytes of the transferns data buffer
should contain the control transfer setup packet

Espressif Systems

785

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· On completion, the transferns callback will be called from the clientns usb_host_client_handle_events() function.
Return esp_err_t Parameters
· [in] client_hdl: Client handle · [in] transfer: Initialized transfer object
Structures struct usb_host_client_event_msg_t
Client event message. Client event messages are sent to each client of the USB Host Library in order to notify them of various USB Host Library events such as:
· Addition of new devices · Removal of existing devices Note The event message structure has a union with members corresponding to each particular event. Based
on the event type, only the relevant member field should be accessed.
Public Members
usb_host_client_event_t event Type of event
uint8_t address New devicens address
usb_device_handle_t dev_hdl The handle of the device that was gone
struct usb_host_lib_info_t Current information about the USB Host Library obtained via usb_host_lib_info()
Public Members
int num_devices Current number of connected (and enumerated) devices
int num_clients Current number of registered clients
struct usb_host_config_t USB Host Library configuration. Configuration structure of the USB Host Library. Provided in the usb_host_install() function
Public Members
bool skip_phy_setup If set, the USB Host Library will not configure the USB PHY thus allowing the user to manually configure the USB PHY before calling usb_host_install(). Users should set this if they want to use an external USB PHY. Otherwise, the USB Host Library will automatically configure the internal USB PHY
int intr_flags Interrupt flags for the underlying ISR used by the USB Host stack
struct usb_host_client_config_t USB Host Library Client configuration. Configuration structure for a USB Host Library client. Provided in usb_host_client_register()

Espressif Systems

786

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Public Members
bool is_synchronous Whether the client is asynchronous or synchronous or not. Set to false for now.
int max_num_event_msg Maximum number of event messages that can be stored (e.g., 3)
usb_host_client_event_cb_t client_event_callback Clientns event callback function
void *callback_arg Event callback function argument

Macros USB_HOST_LIB_EVENT_FLAGS_NO_CLIENTS
All clients have been deregistered from the USB Host Library USB_HOST_LIB_EVENT_FLAGS_ALL_FREE
The USB Host Library has freed all devices

Type Definitions typedef struct usb_host_client_handle_s *usb_host_client_handle_t
Handle to a USB Host Library asynchronous client.

An asynchronous client can be registered using usb_host_client_register()

Note Asynchronous API

typedef void (*usb_host_client_event_cb_t)(const

usb_host_client_event_msg_t

Client event callback.

*event_msg, void *arg)

· Each client of the USB Host Library must register an event callback to receive event messages from the USB Host Library.
· The client event callback is run from the context of the clients usb_host_client_handle_events() function

Enumerations enum usb_host_client_event_t
The type event in a client event message.
Values:
USB_HOST_CLIENT_EVENT_NEW_DEV A new device has been enumerated and added to the USB Host Library
USB_HOST_CLIENT_EVENT_DEV_GONE A device opened by the client is now gone

Header File · components/usb/include/usb/usb_helpers.h

Functions

const usb_standard_desc_t *usb_parse_next_descriptor(const

usb_standard_desc_t

*cur_desc, uint16_t wTotalLength, int

*offset)

Get the next descriptor.

Given a particular descriptor within a full configuration descriptor, get the next descriptor within the configuration descriptor. This is a convenience function that can be used to walk each individual descriptor within a full configuration descriptor.

Espressif Systems

787

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return usb_standard_desc_t* Next descriptor, NULL if end of configuration descriptor reached

Parameters

· [in] cur_desc: Current descriptor

· [in] wTotalLength: Total length of the configuration descriptor

· [inout] offset: Byte offset relative to the start of the configuration descriptor. On input, it is

the offset of the current descriptor. On output, it is the offset of the returned descriptor.

const usb_standard_desc_t *usb_parse_next_descriptor_of_type(const

usb_standard_desc_t

*cur_desc,

uint16_t

wTotalLength, uint8_t

bDescriptorType, int

Get the next descriptor of a particular type.

*offset)

Given a particular descriptor within a full configuration descriptor, get the next descriptor of a particular type (i.e., using the bDescriptorType value) within the configuration descriptor.

Return usb_standard_desc_t* Next descriptor, NULL if end descriptor is not found or configuration descriptor reached
Parameters · [in] cur_desc: Current descriptor · [in] wTotalLength: Total length of the configuration descriptor · [in] bDescriptorType: Type of the next descriptor to get · [inout] offset: Byte offset relative to the start of the configuration descriptor. On input, it is the offset of the current descriptor. On output, it is the offset of the returned descriptor.

int usb_parse_interface_number_of_alternate(const usb_config_desc_t *config_desc, uint8_t bInterfaceNumber)
Get the number of alternate settings for a bInterfaceNumber.

Given a particular configuration descriptor, for a particular bInterfaceNumber, get the number of alternate settings available for that interface (i.e., the max possible value of bAlternateSetting for that bInterfaceNumber).

Return int The number of alternate settings that the interface has, -1 if bInterfaceNumber not found Parameters
· [in] config_desc: Pointer to the start of a full configuration descriptor · [in] bInterfaceNumber: Interface number

const usb_intf_desc_t *usb_parse_interface_descriptor(const

usb_config_desc_t

*config_desc, uint8_t bInter-

faceNumber, uint8_t bAlternateSet-

ting, int *offset) Get a particular interface descriptor (using bInterfaceNumber and bAlternateSetting)

Given a full configuration descriptor, get a particular interface descriptor.

Note To get the number of alternate settings for a particular bInterfaceNumber, call usb_parse_interface_number_of_alternate()
Return const usb_intf_desc_t* Pointer to interface descriptor, NULL if not found. Parameters
· [in] config_desc: Pointer to the start of a full configuration descriptor · [in] bInterfaceNumber: Interface number · [in] bAlternateSetting: Alternate setting number · [out] offset: Byte offset of the interface descriptor relative to the start of the configuration
descriptor. Can be NULL.

const usb_ep_desc_t *usb_parse_endpoint_descriptor_by_index(const usb_intf_desc_t *intf_desc, int index, uint16_t wTotalLength, int *offset)
Get an endpoint descriptor within an interface descriptor.

Given an interface descriptor, get the Nth endpoint descriptor of the interface. The number of endpoints in an interface is indicated by the bNumEndpoints field of the interface descriptor.

Espressif Systems

788

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Note If bNumEndpoints is 0, it means the interface uses the default endpoint only Return const usb_ep_desc_t* Pointer to endpoint descriptor, NULL if not found. Parameters
· [in] intf_desc: Pointer to thee start of an interface descriptor · [in] index: Endpoint index · [in] wTotalLength: Total length of the containing configuration descriptor · [inout] offset: Byte offset relative to the start of the configuration descriptor. On input, it is
the offset of the interface descriptor. On output, it is the offset of the endpoint descriptor.

const usb_ep_desc_t *usb_parse_endpoint_descriptor_by_address(const

usb_config_desc_t

*config_desc, uint8_t

bInterfaceNumber,

uint8_t bAlternate-

Setting,

uint8_t

bEndpointAddress, int

*offset)

Get an endpoint descriptor based on an endpointns address.

Given a configuration descriptor, get an endpoint descriptor based on itns bEndpointAddress, bAlternateSetting, and bInterfaceNumber.

Return const usb_ep_desc_t* Pointer to endpoint descriptor, NULL if not found. Parameters
· [in] config_desc: Pointer to the start of a full configuration descriptor · [in] bInterfaceNumber: Interface number · [in] bAlternateSetting: Alternate setting number · [in] bEndpointAddress: Endpoint address · [out] offset: Byte offset of the endpoint descriptor relative to the start of the configuration
descriptor. Can be NULL

void usb_print_device_descriptor(const usb_device_desc_t *devc_desc) Print device descriptor.

Parameters · devc_desc: Device descriptor

void usb_print_config_descriptor(const

usb_config_desc_t

Print configuration descriptor.

print_class_descriptor_cb class_specific_cb)

*cfg_desc,

· This function prints the full contents of a configuration descriptor (including interface and endpoint descriptors)
· When a non-standard descriptor is encountered, this function will call the class_specific_cb if it is provided

Parameters · cfg_desc: Configuration descriptor · class_specific_cb: Class specific descriptor callback. Can be NULL

void usb_print_string_descriptor(const usb_str_desc_t *str_desc) Print a string descriptor.

This funciton will only print ASCII characters of the UTF-16 encoded string

Parameters · str_desc: String descriptor

static int usb_round_up_to_mps(int num_bytes, int mps) Round up to an integer multiple of endpointns MPS.

This is a convenience function to round up a size/length to an endpointns MPS (Maximum packet size). This is useful when calculating transfer or buffer lengths of IN endpoints.

· If MPS <= 0, this function will return 0

Espressif Systems

789

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· If num_bytes <= 0, this function will return 0
Return int Round up integer multiple of MPS Parameters
· [in] num_bytes: Number of bytes · [in] mps: MPS

Type Definitions typedef void (*print_class_descriptor_cb)(const usb_standard_desc_t *)
Print class specific descriptor callback.
Optional callback to be provided to usb_print_config_descriptor() function. The callback is called when when a non-standard descriptor is encountered. The callback should decode the descriptor as print it.

Header File · components/usb/include/usb/usb_types_stack.h

Structures struct usb_device_info_t
Basic information of an enumerated device.

Public Members
usb_speed_t speed Devicens speed
uint8_t dev_addr Devicens address
uint8_t bMaxPacketSize0 The maximum packet size of the devicens default endpoint
uint8_t bConfigurationValue Devicens current configuration number
const usb_str_desc_t *str_desc_manufacturer Pointer to Manufacturer string descriptor (can be NULL)
const usb_str_desc_t *str_desc_product Pointer to Product string descriptor (can be NULL)
const usb_str_desc_t *str_desc_serial_num Pointer to Serial Number string descriptor (can be NULL)
struct usb_isoc_packet_desc_t Isochronous packet descriptor.
If the number of bytes in an Isochronous transfer is larger than the MPS of the endpoint, the transfer is split into multiple packets transmitted at the endpointns specified interval. An array of Isochronous packet descriptors describes how an Isochronous transfer should be split into multiple packets.

Public Members
int num_bytes Number of bytes to transmit/receive in the packet. IN packets should be integer multiple of MPS
int actual_num_bytes Actual number of bytes transmitted/received in the packet
usb_transfer_status_t status Status of the packet

Espressif Systems

790

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

struct usb_transfer_s

Public Members
uint8_t *const data_buffer Pointer to data buffer
const size_t data_buffer_size Size of the data buffer in bytes
int num_bytes Number of bytes to transfer. Control transfers should include the size of the setup packet. Isochronous transfer should be the total transfer size of all packets. For non-control IN transfers, num_bytes should be an integer multiple of MPS.
int actual_num_bytes Actual number of bytes transferred
uint32_t flags Transfer flags
usb_device_handle_t device_handle Device handle
uint8_t bEndpointAddress Endpoint Address
usb_transfer_status_t status Status of the transfer
uint32_t timeout_ms Timeout (in milliseconds) of the packet (currently not supported yet)
usb_transfer_cb_t callback Transfer callback
void *context Context variable for transfer to associate transfer with something
const int num_isoc_packets Only relevant to Isochronous. Number of service periods (i.e., intervals) to transfer data buffer over.
usb_isoc_packet_desc_t isoc_packet_desc[] Descriptors for each Isochronous packet

Macros USB_TRANSFER_FLAG_ZERO_PACK
Terminate Bulk/Interrupt OUT transfer with a zero length packet.
OUT transfers normally terminate when the Host has transferred the exact amount of data it needs to the device. However, for bulk and interrupt OUT transfers, if the transfer size just happened to be a multiple of MPS, it will be impossible to know the boundary between two consecutive transfers to the same endpoint.
Therefore, this flag will cause the transfer to automatically add a zero length packet (ZLP) at the end of the transfer if the following conditions are met:
· The target endpoint is a Bulk/Interrupt OUT endpoint (Host to device) · The transferns length (i.e., transfer.num_bytes) is a multiple of the endpointns MPS
Otherwise, this flag has no effect.
Users should check whether their target devicens class requires a ZLP, as not all Bulk/Interrupt OUT endpoints require them. For example:
· For MSC Bulk Only Transport class, the Host MUST NEVER send a ZLP. Bulk transfer boundaries are determined by the CBW and CSW instead

Espressif Systems

791

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· For CDC Ethernet, the Host MUST ALWAYS send a ZLP if a segment (i.e., a transfer) is a multiple of MPS (See 3.3.1 Segment Delineation)
Note See USB2.0 specification 5.7.3 and 5.8.3 for more details Note IN transfers normally terminate when the Host as receive the exact amount of data it needs (must be
multiple of MPS) or the endpoint sends a short packet to the Host (For bulk OUT only). Indicates that a bulk OUT transfers should always terminate with a short packet, even if it means adding an extra zero length packet

Type Definitions typedef struct usb_device_handle_s *usb_device_handle_t
Handle of a USB Device connected to a USB Host. typedef struct usb_transfer_s usb_transfer_t
USB transfer structure.
This structure is used to represent a transfer from a software client to an endpoint over the USB bus. Some of the fields are made const on purpose as they are fixed on allocation. Users should call the appropriate USB Host Library function to allocate a USB transfer structure instead of allocating this structure themselves.
The transfer type is inferred from the endpoint this transfer is sent to. Depending on the transfer type, users should note the following:
· Bulk: This structure represents a single bulk transfer. If the number of bytes exceeds the endpointns MPS, the transfer will be split into multiple MPS sized packets followed by a short packet.
· Control: This structure represents a single control transfer. This first 8 bytes of the data_buffer must be filled with the setup packet (see usb_setup_packet_t). The num_bytes field should be the total size of the transfer (i.e., size of setup packet + wLength).
· Interrupt: Represents an interrupt transfer. If num_bytes exceeds the MPS of the endpoint, the transfer will be split into multiple packets, and each packet is transferred at the endpointns specified interval.
· Isochronous: Represents a stream of bytes that should be transferred to an endpoint at a fixed rate. The transfer is split into packets according to the each isoc_packet_desc. A packet is transferred at each interval of the endpoint. If an entire ISOC URB was transferred without error (skipped packets do not count as errors), the URBns overall status and the status of each packet descriptor will be updated, and the actual_num_bytes reflects the total bytes transferred over all packets. If the ISOC URB encounters an error, the entire URB is considered erroneous so only the overall status will updated.
Note For Bulk/Control/Interrupt IN transfers, the num_bytes must be a integer multiple of the endpointns MPS
Note This structure should be allocated via usb_host_transfer_alloc() Note Once the transfer has be submitted, users should not modify the structure until the transfer has completed
typedef void (*usb_transfer_cb_t)(usb_transfer_t *transfer) USB transfer completion callback.

Enumerations enum usb_speed_t
USB Standard Speeds.
Values:
USB_SPEED_LOW = 0 USB Low Speed (1.5 Mbit/s)
USB_SPEED_FULL USB Full Speed (12 Mbit/s)
enum usb_transfer_type_t The type of USB transfer.
Note The enum values need to match the bmAttributes field of an EP descriptor
Values:
USB_TRANSFER_TYPE_CTRL = 0

Espressif Systems

792

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
USB_TRANSFER_TYPE_ISOCHRONOUS USB_TRANSFER_TYPE_BULK USB_TRANSFER_TYPE_INTR enum usb_transfer_status_t The status of a particular transfer. Values: USB_TRANSFER_STATUS_COMPLETED
The transfer was successful (but may be short) USB_TRANSFER_STATUS_ERROR
The transfer failed because due to excessive errors (e.g. no response or CRC error) USB_TRANSFER_STATUS_TIMED_OUT
The transfer failed due to a time out USB_TRANSFER_STATUS_CANCELED
The transfer was canceled USB_TRANSFER_STATUS_STALL
The transfer was stalled USB_TRANSFER_STATUS_OVERFLOW
The transfer as more data was sent than was requested USB_TRANSFER_STATUS_SKIPPED
ISOC packets only. The packet was skipped due to system latency or bus overload USB_TRANSFER_STATUS_NO_DEVICE
The transfer failed because the target device is gone
Header File · components/usb/include/usb/usb_types_ch9.h
Unions union usb_setup_packet_t
#include <usb_types_ch9.h> Structure representing a USB control transfer setup packet. See Table 9-2 of USB2.0 specification for more details
Public Members
uint8_t bmRequestType Characteristics of request
uint8_t bRequest Specific request
uint16_t wValue Word-sized field that varies according to request
uint16_t wIndex Word-sized field that varies according to request; typically used to pass an index or offset
uint16_t wLength Number of bytes to transfer if there is a data stage
struct usb_setup_packet_t::[anonymous] [anonymous] uint8_t val[USB_SETUP_PACKET_SIZE]

Espressif Systems

793

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

union usb_standard_desc_t #include <usb_types_ch9.h> USB standard descriptor.
All USB standard descriptors start with these two bytes. Use this type when traversing over configuration descriptors
Public Members
uint8_t bLength Size of the descriptor in bytes
uint8_t bDescriptorType Descriptor Type
struct usb_standard_desc_t::[anonymous] USB_DESC_ATTR
uint8_t val[USB_STANDARD_DESC_SIZE]
union usb_device_desc_t #include <usb_types_ch9.h> Structure representing a USB device descriptor.
See Table 9-8 of USB2.0 specification for more details
Public Members
uint8_t bLength Size of the descriptor in bytes
uint8_t bDescriptorType DEVICE Descriptor Type
uint16_t bcdUSB USB Specification Release Number in Binary-Coded Decimal (i.e., 2.10 is 210H)
uint8_t bDeviceClass Class code (assigned by the USB-IF)
uint8_t bDeviceSubClass Subclass code (assigned by the USB-IF)
uint8_t bDeviceProtocol Protocol code (assigned by the USB-IF)
uint8_t bMaxPacketSize0 Maximum packet size for endpoint zero (only 8, 16, 32, or 64 are valid)
uint16_t idVendor Vendor ID (assigned by the USB-IF)
uint16_t idProduct Product ID (assigned by the manufacturer)
uint16_t bcdDevice Device release number in binary-coded decimal
uint8_t iManufacturer Index of string descriptor describing manufacturer
uint8_t iProduct Index of string descriptor describing product
uint8_t iSerialNumber Index of string descriptor describing the devicens serial number
uint8_t bNumConfigurations Number of possible configurations

Espressif Systems

794

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

struct usb_device_desc_t::[anonymous] USB_DESC_ATTR uint8_t val[USB_DEVICE_DESC_SIZE] union usb_config_desc_t #include <usb_types_ch9.h> Structure representing a short USB configuration descriptor. See Table 9-10 of USB2.0 specification for more details Note The full USB configuration includes all the interface and endpoint descriptors of that configuration.

Public Members
uint8_t bLength Size of the descriptor in bytes
uint8_t bDescriptorType CONFIGURATION Descriptor Type
uint16_t wTotalLength Total length of data returned for this configuration
uint8_t bNumInterfaces Number of interfaces supported by this configuration
uint8_t bConfigurationValue Value to use as an argument to the SetConfiguration() request to select this configuration
uint8_t iConfiguration Index of string descriptor describing this configuration
uint8_t bmAttributes Configuration characteristics
uint8_t bMaxPower Maximum power consumption of the USB device from the bus in this specific configuration when the device is fully operational.
struct usb_config_desc_t::[anonymous] USB_DESC_ATTR
uint8_t val[USB_CONFIG_DESC_SIZE]
union usb_iad_desc_t #include <usb_types_ch9.h> Structure representing a USB interface association descriptor.

Public Members
uint8_t bLength Size of the descriptor in bytes
uint8_t bDescriptorType INTERFACE ASSOCIATION Descriptor Type
uint8_t bFirstInterface Interface number of the first interface that is associated with this function
uint8_t bInterfaceCount Number of contiguous interfaces that are associated with this function
uint8_t bFunctionClass Class code (assigned by USB-IF)
uint8_t bFunctionSubClass Subclass code (assigned by USB-IF)
uint8_t bFunctionProtocol Protocol code (assigned by USB-IF)

Espressif Systems

795

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
uint8_t iFunction Index of string descriptor describing this function
struct usb_iad_desc_t::[anonymous] USB_DESC_ATTR uint8_t val[USB_IAD_DESC_SIZE] union usb_intf_desc_t #include <usb_types_ch9.h> Structure representing a USB interface descriptor. See Table 9-12 of USB2.0 specification for more details
Public Members
uint8_t bLength Size of the descriptor in bytes
uint8_t bDescriptorType INTERFACE Descriptor Type
uint8_t bInterfaceNumber Number of this interface.
uint8_t bAlternateSetting Value used to select this alternate setting for the interface identified in the prior field
uint8_t bNumEndpoints Number of endpoints used by this interface (excluding endpoint zero).
uint8_t bInterfaceClass Class code (assigned by the USB-IF)
uint8_t bInterfaceSubClass Subclass code (assigned by the USB-IF)
uint8_t bInterfaceProtocol Protocol code (assigned by the USB)
uint8_t iInterface Index of string descriptor describing this interface
struct usb_intf_desc_t::[anonymous] USB_DESC_ATTR uint8_t val[USB_INTF_DESC_SIZE] union usb_ep_desc_t #include <usb_types_ch9.h> Structure representing a USB endpoint descriptor. See Table 9-13 of USB2.0 specification for more details
Public Members
uint8_t bLength Size of the descriptor in bytes
uint8_t bDescriptorType ENDPOINT Descriptor Type
uint8_t bEndpointAddress The address of the endpoint on the USB device described by this descriptor
uint8_t bmAttributes This field describes the endpointns attributes when it is configured using the bConfigurationValue.
uint16_t wMaxPacketSize Maximum packet size this endpoint is capable of sending or receiving when this configuration is selected.

Espressif Systems

796

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

uint8_t bInterval Interval for polling Isochronous and Interrupt endpoints. Expressed in frames or microframes depending on the device operating speed (1 ms for Low-Speed and Full-Speed or 125 us for USB High-Speed and above).
struct usb_ep_desc_t::[anonymous] USB_DESC_ATTR uint8_t val[USB_EP_DESC_SIZE] union usb_str_desc_t #include <usb_types_ch9.h> Structure representing a USB string descriptor.
Public Members
uint8_t bLength Size of the descriptor in bytes
uint8_t bDescriptorType STRING Descriptor Type
uint16_t wData[] UTF-16LE encoded
struct usb_str_desc_t::[anonymous] USB_DESC_ATTR uint8_t val[USB_STR_DESC_SIZE]
Macros USB_DESC_ATTR USB_B_DESCRIPTOR_TYPE_DEVICE
Descriptor types from USB2.0 specification table 9.5. USB_B_DESCRIPTOR_TYPE_CONFIGURATION USB_B_DESCRIPTOR_TYPE_STRING USB_B_DESCRIPTOR_TYPE_INTERFACE USB_B_DESCRIPTOR_TYPE_ENDPOINT USB_B_DESCRIPTOR_TYPE_DEVICE_QUALIFIER USB_B_DESCRIPTOR_TYPE_OTHER_SPEED_CONFIGURATION USB_B_DESCRIPTOR_TYPE_INTERFACE_POWER USB_B_DESCRIPTOR_TYPE_OTG
Descriptor types from USB 2.0 ECN. USB_B_DESCRIPTOR_TYPE_DEBUG USB_B_DESCRIPTOR_TYPE_INTERFACE_ASSOCIATION USB_B_DESCRIPTOR_TYPE_SECURITY
Descriptor types from Wireless USB spec. USB_B_DESCRIPTOR_TYPE_KEY USB_B_DESCRIPTOR_TYPE_ENCRYPTION_TYPE USB_B_DESCRIPTOR_TYPE_BOS USB_B_DESCRIPTOR_TYPE_DEVICE_CAPABILITY USB_B_DESCRIPTOR_TYPE_WIRELESS_ENDPOINT_COMP USB_B_DESCRIPTOR_TYPE_WIRE_ADAPTER USB_B_DESCRIPTOR_TYPE_RPIPE

Espressif Systems

797

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
USB_B_DESCRIPTOR_TYPE_CS_RADIO_CONTROL USB_B_DESCRIPTOR_TYPE_PIPE_USAGE
Descriptor types from UAS specification. USB_SETUP_PACKET_SIZE
Size of a USB control transfer setup packet in bytes. USB_BM_REQUEST_TYPE_DIR_OUT
Bit masks belonging to the bmRequestType field of a setup packet. USB_BM_REQUEST_TYPE_DIR_IN USB_BM_REQUEST_TYPE_TYPE_STANDARD USB_BM_REQUEST_TYPE_TYPE_CLASS USB_BM_REQUEST_TYPE_TYPE_VENDOR USB_BM_REQUEST_TYPE_TYPE_RESERVED USB_BM_REQUEST_TYPE_TYPE_MASK USB_BM_REQUEST_TYPE_RECIP_DEVICE USB_BM_REQUEST_TYPE_RECIP_INTERFACE USB_BM_REQUEST_TYPE_RECIP_ENDPOINT USB_BM_REQUEST_TYPE_RECIP_OTHER USB_BM_REQUEST_TYPE_RECIP_MASK USB_B_REQUEST_GET_STATUS
Bit masks belonging to the bRequest field of a setup packet. USB_B_REQUEST_CLEAR_FEATURE USB_B_REQUEST_SET_FEATURE USB_B_REQUEST_SET_ADDRESS USB_B_REQUEST_GET_DESCRIPTOR USB_B_REQUEST_SET_DESCRIPTOR USB_B_REQUEST_GET_CONFIGURATION USB_B_REQUEST_SET_CONFIGURATION USB_B_REQUEST_GET_INTERFACE USB_B_REQUEST_SET_INTERFACE USB_B_REQUEST_SYNCH_FRAME USB_W_VALUE_DT_DEVICE
Bit masks belonging to the wValue field of a setup packet. USB_W_VALUE_DT_CONFIG USB_W_VALUE_DT_STRING USB_W_VALUE_DT_INTERFACE USB_W_VALUE_DT_ENDPOINT USB_W_VALUE_DT_DEVICE_QUALIFIER USB_W_VALUE_DT_OTHER_SPEED_CONFIG USB_W_VALUE_DT_INTERFACE_POWER

Espressif Systems

798

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

USB_SETUP_PACKET_INIT_SET_ADDR(setup_pkt_ptr, addr) Initializer for a SET_ADDRESS request. Sets the address of a connected device
USB_SETUP_PACKET_INIT_GET_DEVICE_DESC(setup_pkt_ptr) Initializer for a request to get a devicens device descriptor.
USB_SETUP_PACKET_INIT_GET_CONFIG(setup_pkt_ptr) Initializer for a request to get a devicens current configuration number.
USB_SETUP_PACKET_INIT_GET_CONFIG_DESC(setup_pkt_ptr, desc_index, desc_len) Initializer for a request to get one of the devicens current configuration descriptor. · desc_index indicates the configurationns index number · Number of bytes of the configuration descriptor to get
USB_SETUP_PACKET_INIT_SET_CONFIG(setup_pkt_ptr, config_num) Initializer for a request to set a devicens current configuration number.
USB_SETUP_PACKET_INIT_SET_INTERFACE(setup_pkt_ptr, intf_num, alt_setting_num) Initializer for a request to set an interfacens alternate setting.
USB_SETUP_PACKET_INIT_GET_STR_DESC(setup_pkt_ptr, string_index, lang_id, desc_len) Initializer for a request to get an string descriptor.
USB_STANDARD_DESC_SIZE Size of dummy USB standard descriptor.
USB_DEVICE_DESC_SIZE Size of a USB device descriptor in bytes.
USB_CLASS_PER_INTERFACE Possible base class values of the bDeviceClass field of a USB device descriptor.
USB_CLASS_AUDIO USB_CLASS_COMM USB_CLASS_HID USB_CLASS_PHYSICAL USB_CLASS_STILL_IMAGE USB_CLASS_PRINTER USB_CLASS_MASS_STORAGE USB_CLASS_HUB USB_CLASS_CDC_DATA USB_CLASS_CSCID USB_CLASS_CONTENT_SEC USB_CLASS_VIDEO USB_CLASS_WIRELESS_CONTROLLER USB_CLASS_PERSONAL_HEALTHCARE USB_CLASS_AUDIO_VIDEO USB_CLASS_BILLBOARD USB_CLASS_USB_TYPE_C_BRIDGE USB_CLASS_MISC USB_CLASS_APP_SPEC USB_CLASS_VENDOR_SPEC

Espressif Systems

799

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
USB_SUBCLASS_VENDOR_SPEC Vendor specific subclass code.
USB_CONFIG_DESC_SIZE Size of a short USB configuration descriptor in bytes. Note The size of a full USB configuration includes all the interface and endpoint descriptors of that configuration.
USB_BM_ATTRIBUTES_ONE Bit masks belonging to the bmAttributes field of a configuration descriptor.
USB_BM_ATTRIBUTES_SELFPOWER USB_BM_ATTRIBUTES_WAKEUP USB_BM_ATTRIBUTES_BATTERY USB_IAD_DESC_SIZE
Size of a USB interface association descriptor in bytes. USB_INTF_DESC_SIZE
Size of a USB interface descriptor in bytes. USB_EP_DESC_SIZE
Size of a USB endpoint descriptor in bytes. USB_B_ENDPOINT_ADDRESS_EP_NUM_MASK
Bit masks belonging to the bEndpointAddress field of an endpoint descriptor. USB_B_ENDPOINT_ADDRESS_EP_DIR_MASK USB_BM_ATTRIBUTES_XFERTYPE_MASK
Bit masks belonging to the bmAttributes field of an endpoint descriptor. USB_BM_ATTRIBUTES_XFER_CONTROL USB_BM_ATTRIBUTES_XFER_ISOC USB_BM_ATTRIBUTES_XFER_BULK USB_BM_ATTRIBUTES_XFER_INT USB_BM_ATTRIBUTES_SYNCTYPE_MASK USB_BM_ATTRIBUTES_SYNC_NONE USB_BM_ATTRIBUTES_SYNC_ASYNC USB_BM_ATTRIBUTES_SYNC_ADAPTIVE USB_BM_ATTRIBUTES_SYNC_SYNC USB_BM_ATTRIBUTES_USAGETYPE_MASK USB_BM_ATTRIBUTES_USAGE_DATA USB_BM_ATTRIBUTES_USAGE_FEEDBACK USB_BM_ATTRIBUTES_USAGE_IMPLICIT_FB USB_EP_DESC_GET_XFERTYPE(desc_ptr)
Macro helpers to get information about an endpoint from its descriptor. USB_EP_DESC_GET_EP_NUM(desc_ptr) USB_EP_DESC_GET_EP_DIR(desc_ptr) USB_EP_DESC_GET_MPS(desc_ptr) USB_STR_DESC_SIZE
Size of a short USB string descriptor in bytes.

Espressif Systems

800

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Enumerations enum usb_device_state_t
USB2.0 device states. See Table 9-1 of USB2.0 specification for more details Note The USB_DEVICE_STATE_NOT_ATTACHED is not part of the USB2.0 specification, but is a catch
all state for devices that need to be cleaned up after a sudden disconnection or port error. Values: USB_DEVICE_STATE_NOT_ATTACHED
The device was previously configured or suspended, but is no longer attached (either suddenly disconnected or a port error) USB_DEVICE_STATE_ATTACHED Device is attached to the USB, but is not powered. USB_DEVICE_STATE_POWERED Device is attached to the USB and powered, but has not been reset. USB_DEVICE_STATE_DEFAULT Device is attached to the USB and powered and has been reset, but has not been assigned a unique address. Device responds at the default address. USB_DEVICE_STATE_ADDRESS Device is attached to the USB, powered, has been reset, and a unique device address has been assigned. Device is not configured. USB_DEVICE_STATE_CONFIGURED Device is attached to the USB, powered, has been reset, has a unique address, is configured, and is not suspended. The host may now use the function provided by the device. USB_DEVICE_STATE_SUSPENDED Device is, at minimum, attached to the USB and is powered and has not seen bus activity for 3 ms. It may also have a unique address and be configured for use. However, because the device is suspended, the host may not use the devicens function. Code examples for this API section are provided in the peripherals directory of ESP-IDF examples.
2.4 Application Protocols
2.4.1 ASIO port
Overview
Asio is a cross-platform C++ library, see https://think-async.com. It provides a consistent asynchronous model using a modern C++ approach.
ASIO documentation Please refer to the original asio documentation at https://think-async.com/Asio/ Documentation. Asio also comes with a number of examples which could be find under Documentation/Examples on that web site.
Supported features ESP platform port currently supports only network asynchronous socket operations; does not support serial port. SSL/TLS support is disabled by default and could be enabled in component configuration menu by choosing TLS library from
· mbedTLS with OpenSSL translation layer (default option) · wolfSSL SSL support is very basic at this stage and it does include following features:

Espressif Systems

801

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· Verification callbacks · DH property files · Certificates/private keys file APIs Internal asio settings for ESP include · EXCEPTIONS are enabled in ASIO if enabled in menuconfig · TYPEID is enabled in ASIO if enabled in menuconfig
Application Example
ESP examples are based on standard asio protocols/asio: · protocols/asio/udp_echo_server · protocols/asio/tcp_echo_server · protocols/asio/asio_chat · protocols/asio/ssl_client_server
Please refer to the specific example README.md for details
2.4.2 ESP-MQTT
Overview
ESP-MQTT is an implementation of MQTT protocol client (MQTT is a lightweight publish/subscribe messaging protocol).
Features
· Supports MQTT over TCP, SSL with mbedtls, MQTT over Websocket, MQTT over Websocket Secure. · Easy to setup with URI · Multiple instances (Multiple clients in one application) · Support subscribing, publishing, authentication, last will messages, keep alive pings and all 3 QoS levels (it
should be a fully functional client).
Application Example
· protocols/mqtt/tcp: MQTT over tcp, default port 1883 · protocols/mqtt/ssl: MQTT over tcp, default port 8883 · protocols/mqtt/ssl_psk: MQTT over tcp using pre-shared keys for authentication, default port 8883 · protocols/mqtt/ws: MQTT over Websocket, default port 80 · protocols/mqtt/wss: MQTT over Websocket Secure, default port 443
Configuration
URI · Curently support mqtt, mqtts, ws, wss schemes · MQTT over TCP samples: ­ mqtt://mqtt.eclipseprojects.io: MQTT over TCP, default port 1883: ­ mqtt://mqtt.eclipseprojects.io:1884 MQTT over TCP, port 1884: ­ mqtt://username:[email protected]:1884 MQTT over TCP, port 1884, with username and password · MQTT over SSL samples: ­ mqtts://mqtt.eclipseprojects.io: MQTT over SSL, port 8883 ­ mqtts://mqtt.eclipseprojects.io:8884: MQTT over SSL, port 8884

Espressif Systems

802

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· MQTT over Websocket samples: ­ ws://mqtt.eclipseprojects.io:80/mqtt
· MQTT over Websocket Secure samples: ­ wss://mqtt.eclipseprojects.io:443/mqtt
· Minimal configurations:
const esp_mqtt_client_config_t mqtt_cfg = { .uri = "mqtt://mqtt.eclipseprojects.io", // .user_context = (void *)your_context
}; esp_mqtt_client_handle_t client = esp_mqtt_client_init(&mqtt_cfg); esp_mqtt_client_register_event(client, ESP_EVENT_ANY_ID, mqtt_event_handler, client); esp_mqtt_client_start(client);
· Note: By default mqtt client uses event loop library to post related mqtt events (connected, subscribed, published, etc.)
SSL
· Get certificate from server, example: mqtt.eclipseprojects.io openssl s_client showcerts -connect mqtt.eclipseprojects.io:8883 </dev/null 2>/dev/ null|openssl x509 -outform PEM >mqtt_eclipse_org.pem
· Check the sample application: examples/mqtt_ssl · Configuration:
const esp_mqtt_client_config_t mqtt_cfg = { .uri = "mqtts://mqtt.eclipseprojects.io:8883", .event_handle = mqtt_event_handler, .cert_pem = (const char *)mqtt_eclipse_org_pem_start,
};
If the certificate is not null-terminated then cert_len should also be set. Other SSL related configuration parameters are:
· use_global_ca_store: use the global certificate store to verify server certificate, see esp-tls.h for more information
· client_cert_pem: pointer to certificate data in PEM or DER format for SSL mutual authentication, default is NULL, not required if mutual authentication is not needed.
· client_cert_len: length of the buffer pointed to by client_cert_pem. May be 0 for null-terminated pem. · client_key_pem: pointer to private key data in PEM or DER format for SSL mutual authentication,
default is NULL, not required if mutual authentication is not needed. · client_key_len: length of the buffer pointed to by client_key_pem. May be 0 for null-terminated pem. · psk_hint_key: pointer to PSK struct defined in esp_tls.h to enable PSK authentication (as alternative to
certificate verification). If not NULL and server/client certificates are NULL, PSK is enabled · alpn_protos: NULL-terminated list of protocols to be used for ALPN.
Last Will and Testament MQTT allows for a last will and testament (LWT) message to notify other clients when a client ungracefully disconnects. This is configured by the following fields in the esp_mqtt_client_config_tstruct.
· lwt_topic: pointer to the LWT message topic · lwt_msg: pointer to the LWT message · lwt_msg_len: length of the LWT message, required if lwt_msg is not null-terminated · lwt_qos: quality of service for the LWT message · lwt_retain: specifies the retain flag of the LWT message
Other Configuration Parameters

Espressif Systems

803

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· disable_clean_session: determines the clean session flag for the connect message, defaults to a clean session
· keepalive: determines how many seconds the client will wait for a ping response before disconnecting, default is 120 seconds.
· disable_auto_reconnect: enable to stop the client from reconnecting to server after errors or disconnects
· user_context: custom context that will be passed to the event handler · task_prio: MQTT task priority, defaults to 5 · task_stack: MQTT task stack size, defaults to 6144 bytes, setting this will override setting from menu-
config · buffer_size: size of MQTT send/receive buffer, default is 1024 bytes · username: pointer to the username used for connecting to the broker · password: pointer to the password used for connecting to the broker · client_id: pointer to the client id, defaults to ESP32_%CHIPID% where %CHIPID% are the last 3 bytes
of MAC address in hex format · host: MQTT broker domain (ipv4 as string), setting the uri will override this · port: MQTT broker port, specifying the port in the uri will override this · transport: sets the transport protocol, setting the uri will override this · refresh_connection_after_ms: refresh connection after this value (in milliseconds) · event_handle: handle for MQTT events as a callback in legacy mode · event_loop_handle: handle for MQTT event loop library
For more options on esp_mqtt_client_config_t, please refer to API reference below
Change settings in Project Configuration Menu The settings for MQTT can be found using idf.py menuconfig, under Component config -> ESP-MQTT Configuration
The following settings are available:
· CONFIG_MQTT_PROTOCOL_311: Enables 3.1.1 version of MQTT protocol · CONFIG_MQTT_TRANSPORT_SSL, CONFIG_MQTT_TRANSPORT_WEBSOCKET: Enables specific MQTT
transport layer, such as SSL, WEBSOCKET, WEBSOCKET_SECURE · CONFIG_MQTT_CUSTOM_OUTBOX: Disables default implementation of mqtt_outbox, so a specific imple-
mentaion can be supplied
Events
The following events may be posted by the MQTT client:
· MQTT_EVENT_BEFORE_CONNECT: The client is initialized and about to start connecting to the broker. · MQTT_EVENT_CONNECTED: The client has successfully established a connection to the broker. The client
is now ready to send and receive data. · MQTT_EVENT_DISCONNECTED: The client has aborted the connection due to being unable to read or write
data, e.g. because the server is unavailable. · MQTT_EVENT_SUBSCRIBED: The broker has acknowledged the clientns subscribe request. The event data
will contain the message ID of the subscribe message. · MQTT_EVENT_UNSUBSCRIBED: The broker has acknowledged the clientns unsubscribe request. The event
data will contain the message ID of the unsubscribe message. · MQTT_EVENT_PUBLISHED: The broker has acknowledged the clientns publish message. This will only
be posted for Quality of Service level 1 and 2, as level 0 does not use acknowledgements. The event data will contain the message ID of the publish message. · MQTT_EVENT_DATA: The client has received a publish message. The event data contains: message ID, name of the topic it was published to, received data and its length. For data that exceeds the internal buffer multiple MQTT_EVENT_DATA will be posted and current_data_offset and total_data_len from event data updated to keep track of the fragmented message. · MQTT_EVENT_ERROR: The client has encountered an error. esp_mqtt_error_type_t from error_handle in the event data can be used to further determine the type of the error. The type of error will determine which parts of the error_handle struct is filled.

Espressif Systems

804

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

API Reference
Header File
· components/mqtt/esp-mqtt/include/mqtt_client.h
Functions esp_mqtt_client_handle_t esp_mqtt_client_init(const esp_mqtt_client_config_t *config)
Creates mqtt client handle based on the configuration.
Return mqtt_client_handle if successfully created, NULL on error Parameters
· config: mqtt configuration structure esp_err_t esp_mqtt_client_set_uri(esp_mqtt_client_handle_t client, const char *uri)
Sets mqtt connection URI. This API is usually used to overrides the URI configured in esp_mqtt_client_init.
Return ESP_FAIL if URI parse error, ESP_OK on success Parameters
· client: mqtt client handle · uri:
esp_err_t esp_mqtt_client_start(esp_mqtt_client_handle_t client) Starts mqtt client with already created client handle.
Return ESP_OK on success ESP_ERR_INVALID_ARG on wrong initialization ESP_FAIL on other error Parameters
· client: mqtt client handle
esp_err_t esp_mqtt_client_reconnect(esp_mqtt_client_handle_t client) This api is typically used to force reconnection upon a specific event.
Return ESP_OK on success ESP_ERR_INVALID_ARG on wrong initialization ESP_FAIL if client is in invalid state
Parameters · client: mqtt client handle
esp_err_t esp_mqtt_client_disconnect(esp_mqtt_client_handle_t client) This api is typically used to force disconnection from the broker.
Return ESP_OK on success ESP_ERR_INVALID_ARG on wrong initialization Parameters
· client: mqtt client handle
esp_err_t esp_mqtt_client_stop(esp_mqtt_client_handle_t client) Stops mqtt client tasks.
· Notes: · Cannot be called from the mqtt event handler
Return ESP_OK on success ESP_ERR_INVALID_ARG on wrong initialization ESP_FAIL if client is in invalid state
Parameters · client: mqtt client handle
int esp_mqtt_client_subscribe(esp_mqtt_client_handle_t client, const char *topic, int qos) Subscribe the client to defined topic with defined qos.
Notes:
· Client must be connected to send subscribe message · This API is could be executed from a user task or from a mqtt event callback i.e. internal mqtt task (API
is protected by internal mutex, so it might block if a longer data receive operation is in progress.
Return message_id of the subscribe message on success -1 on failure Parameters

Espressif Systems

805

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· client: mqtt client handle · topic: · qos:
int esp_mqtt_client_unsubscribe(esp_mqtt_client_handle_t client, const char *topic) Unsubscribe the client from defined topic.
Notes:
· Client must be connected to send unsubscribe message · It is thread safe, please refer to esp_mqtt_client_subscribe for details
Return message_id of the subscribe message on success -1 on failure Parameters
· client: mqtt client handle · topic:
int esp_mqtt_client_publish(esp_mqtt_client_handle_t client, const char *topic, const char *data, int len, int qos, int retain)
Client to send a publish message to the broker.
Notes:
· This API might block for several seconds, either due to network timeout (10s) or if publishing payloads longer than internal buffer (due to message fragmentation)
· Client doesnnt have to be connected for this API to work, enqueueing the messages with qos>1 (returning -1 for all the qos=0 messages if disconnected). If MQTT_SKIP_PUBLISH_IF_DISCONNECTED is enabled, this API will not attempt to publish when the client is not connected and will always return -1.
· It is thread safe, please refer to esp_mqtt_client_subscribe for details
Return message_id of the publish message (for QoS 0 message_id will always be zero) on success. -1 on failure.
Parameters · client: mqtt client handle · topic: topic string · data: payload string (set to NULL, sending empty payload message) · len: data length, if set to 0, length is calculated from payload string · qos: qos of publish message · retain: retain flag
int esp_mqtt_client_enqueue(esp_mqtt_client_handle_t client, const char *topic, const char *data, int len, int qos, int retain, bool store)
Enqueue a message to the outbox, to be sent later. Typically used for messages with qos>0, but could be also used for qos=0 messages if store=true.
This API generates and stores the publish message into the internal outbox and the actual sending to the network is performed in the mqtt-task context (in contrast to the esp_mqtt_client_publish() which sends the publish message immediately in the user taskns context). Thus, it could be used as a non blocking version of esp_mqtt_client_publish().
Return message_id if queued successfully, -1 otherwise Parameters
· client: mqtt client handle · topic: topic string · data: payload string (set to NULL, sending empty payload message) · len: data length, if set to 0, length is calculated from payload string · qos: qos of publish message · retain: retain flag · store: if true, all messages are enqueued; otherwise only qos1 and qos 2 are enqueued
esp_err_t esp_mqtt_client_destroy(esp_mqtt_client_handle_t client) Destroys the client handle.
Notes:

Espressif Systems

806

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· Cannot be called from the mqtt event handler

Return ESP_OK ESP_ERR_INVALID_ARG on wrong initialization Parameters
· client: mqtt client handle

esp_err_t esp_mqtt_set_config(esp_mqtt_client_handle_t client, const esp_mqtt_client_config_t
*config) Set configuration structure, typically used when updating the config (i.e. on obefore_connectpevent.

Return ESP_ERR_NO_MEM if failed to allocate ESP_ERR_INVALID_ARG if conflicts on transport configuration. ESP_OK on success
Parameters · client: mqtt client handle · config: mqtt configuration structure

esp_err_t esp_mqtt_client_register_event(esp_mqtt_client_handle_t

client,

esp_mqtt_event_id_t event, esp_event_handler_t

event_handler, void *event_handler_arg)

Registers mqtt event.

Return ESP_ERR_NO_MEM if failed to allocate ESP_ERR_INVALID_ARG on wrong initialization ESP_OK on success
Parameters · client: mqtt client handle · event: event type · event_handler: handler callback · event_handler_arg: handlers context

int esp_mqtt_client_get_outbox_size(esp_mqtt_client_handle_t client) Get outbox size.

Return outbox size 0 on wrong initialization Parameters
· client: mqtt client handle

Structures struct esp_mqtt_error_codes
MQTT error code structure to be passed as a contextual information into ERROR event.
Important: This structure extends esp_tls_last_error error structure and is backward compatible with it (so might be down-casted and treated as esp_tls_last_error error, but recommended to update applications if used this way previously)
Use this structure directly checking error_type first and then appropriate error code depending on the source of the error:
| error_type | related member variables | note | | MQTT_ERROR_TYPE_TCP_TRANSPORT | esp_tls_last_esp_err, esp_tls_stack_err, esp_tls_cert_verify_flags, sock_errno | Error reported from tcp_transport/esp-tls | | MQTT_ERROR_TYPE_CONNECTION_REFUSED | connect_return_code | Internal error reported from MQTT broker on connection |

Public Members
esp_err_t esp_tls_last_esp_err last esp_err code reported from esp-tls component
int esp_tls_stack_err tls specific error code reported from underlying tls stack
int esp_tls_cert_verify_flags tls flags reported from underlying tls stack during certificate verification

Espressif Systems

807

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_mqtt_error_type_t error_type error type referring to the source of the error
esp_mqtt_connect_return_code_t connect_return_code connection refused error code reported from MQTT broker on connection
int esp_transport_sock_errno errno from the underlying socket
struct esp_mqtt_event_t MQTT event configuration structure
Public Members
esp_mqtt_event_id_t event_id MQTT event type
esp_mqtt_client_handle_t client MQTT client handle for this event
void *user_context User context passed from MQTT client config
char *data Data associated with this event
int data_len Length of the data for this event
int total_data_len Total length of the data (longer data are supplied with multiple events)
int current_data_offset Actual offset for the data associated with this event
char *topic Topic associated with this event
int topic_len Length of the topic for this event associated with this event
int msg_id MQTT messaged id of message
int session_present MQTT session_present flag for connection event
esp_mqtt_error_codes_t *error_handle esp-mqtt error handle including esp-tls errors as well as internal mqtt errors
bool retain Retained flag of the message associated with this event
int qos qos of the messages associated with this event
bool dup dup flag of the message associated with this event
struct esp_mqtt_client_config_t MQTT client configuration structure
Public Members
mqtt_event_callback_t event_handle handle for MQTT events as a callback in legacy mode

Espressif Systems

808

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
esp_event_loop_handle_t event_loop_handle handle for MQTT event loop library
const char *host MQTT server domain (ipv4 as string)
const char *uri Complete MQTT broker URI
uint32_t port MQTT server port
bool set_null_client_id Selects a NULL client id
const char *client_id Set client id. Ignored if set_null_client_id == true If NULL set the default client id. Default client id is ESP32_CHIPID% where CHIPID% are last 3 bytes of MAC address in hex format
const char *username MQTT username
const char *password MQTT password
const char *lwt_topic LWT (Last Will and Testament) message topic (NULL by default)
const char *lwt_msg LWT message (NULL by default)
int lwt_qos LWT message qos
int lwt_retain LWT retained message flag
int lwt_msg_len LWT message length
int disable_clean_session mqtt clean session, default clean_session is true
int keepalive mqtt keepalive, default is 120 seconds
bool disable_auto_reconnect this mqtt client will reconnect to server (when errors/disconnect). Set disable_auto_reconnect=true to disable
void *user_context pass user context to this option, then can receive that context in event->user_context
int task_prio MQTT task priority, default is 5, can be changed in make menuconfig
int task_stack MQTT task stack size, default is 6144 bytes, can be changed in make menuconfig
int buffer_size size of MQTT send/receive buffer, default is 1024 (only receive buffer size if out_buffer_size defined)
const char *cert_pem Pointer to certificate data in PEM or DER format for server verify (with SSL), default is NULL, not required to verify the server. PEM-format must have a terminating NULL-character. DER-format requires the length to be passed in cert_len.

Espressif Systems

809

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

size_t cert_len Length of the buffer pointed to by cert_pem. May be 0 for null-terminated pem
const char *client_cert_pem Pointer to certificate data in PEM or DER format for SSL mutual authentication, default is NULL, not required if mutual authentication is not needed. If it is not NULL, also client_key_pem has to be provided. PEM-format must have a terminating NULL-character. DER-format requires the length to be passed in client_cert_len.
size_t client_cert_len Length of the buffer pointed to by client_cert_pem. May be 0 for null-terminated pem
const char *client_key_pem Pointer to private key data in PEM or DER format for SSL mutual authentication, default is NULL, not required if mutual authentication is not needed. If it is not NULL, also client_cert_pem has to be provided. PEM-format must have a terminating NULL-character. DER-format requires the length to be passed in client_key_len
size_t client_key_len Length of the buffer pointed to by client_key_pem. May be 0 for null-terminated pem
esp_mqtt_transport_t transport overrides URI transport
int refresh_connection_after_ms Refresh connection after this value (in milliseconds)
const struct psk_key_hint *psk_hint_key Pointer to PSK struct defined in esp_tls.h to enable PSK authentication (as alternative to certificate verification). If not NULL and server/client certificates are NULL, PSK is enabled
bool use_global_ca_store Use a global ca_store for all the connections in which this bool is set.
esp_err_t (*crt_bundle_attach)(void *conf) Pointer to ESP x509 Certificate Bundle attach function for the usage of certification bundles in mqtts
int reconnect_timeout_ms Reconnect to the broker after this value in miliseconds if auto reconnect is not disabled (defaults to 10s)
const char **alpn_protos NULL-terminated list of supported application protocols to be used for ALPN
const char *clientkey_password Client key decryption password string
int clientkey_password_len String length of the password pointed to by clientkey_password
esp_mqtt_protocol_ver_t protocol_ver MQTT protocol version used for connection, defaults to value from menuconfig
int out_buffer_size size of MQTT output buffer. If not defined, both output and input buffers have the same size defined as buffer_size
bool skip_cert_common_name_check Skip any validation of server certificate CN field, this reduces the security of TLS and makes the mqtt client susceptible to MITM attacks
bool use_secure_element enable secure element for enabling SSL connection
void *ds_data carrier of handle for digital signature parameters
int network_timeout_ms Abort network operation if it is not completed after this value, in milliseconds (defaults to 10s)

Espressif Systems

810

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

bool disable_keepalive Set disable_keepalive=true to turn off keep-alive mechanism, false by default (keepalive is active by default). Note: setting the config value keepalive to 0 doesnnt disable keepalive feature, but uses a default keepalive period
const char *path Path in the URI
int message_retransmit_timeout timeout for retansmit of failded packet
Macros MQTT_ERROR_TYPE_ESP_TLS
MQTT_ERROR_TYPE_TCP_TRANSPORT error type hold all sorts of transport layer errors, including ESPTLS error, but in the past only the errors from MQTT_ERROR_TYPE_ESP_TLS layer were reported, so the ESP-TLS error type is re-defined here for backward compatibility
Type Definitions typedef struct esp_mqtt_client *esp_mqtt_client_handle_t typedef struct esp_mqtt_error_codes esp_mqtt_error_codes_t
MQTT error code structure to be passed as a contextual information into ERROR event.
Important: This structure extends esp_tls_last_error error structure and is backward compatible with it (so might be down-casted and treated as esp_tls_last_error error, but recommended to update applications if used this way previously)
Use this structure directly checking error_type first and then appropriate error code depending on the source of the error:
| error_type | related member variables | note | | MQTT_ERROR_TYPE_TCP_TRANSPORT | esp_tls_last_esp_err, esp_tls_stack_err, esp_tls_cert_verify_flags, sock_errno | Error reported from tcp_transport/esp-tls | | MQTT_ERROR_TYPE_CONNECTION_REFUSED | connect_return_code | Internal error reported from MQTT broker on connection |
typedef esp_mqtt_event_t *esp_mqtt_event_handle_t
typedef esp_err_t (*mqtt_event_callback_t)(esp_mqtt_event_handle_t event)
Enumerations enum esp_mqtt_event_id_t
MQTT event types.
User event handler receives context data in esp_mqtt_event_t structure with
· user_context - user data from esp_mqtt_client_config_t · client - mqtt client handle · various other data depending on event type
Values:
MQTT_EVENT_ANY = -1
MQTT_EVENT_ERROR = 0 on error event, additional context: connection return code, error handle from esp_tls (if supported)
MQTT_EVENT_CONNECTED connected event, additional context: session_present flag
MQTT_EVENT_DISCONNECTED disconnected event
MQTT_EVENT_SUBSCRIBED subscribed event, additional context:

Espressif Systems

811

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· msg_id message id · data pointer to the received data · data_len length of the data for this event
MQTT_EVENT_UNSUBSCRIBED unsubscribed event
MQTT_EVENT_PUBLISHED published event, additional context: msg_id
MQTT_EVENT_DATA data event, additional context:
· msg_id message id · topic pointer to the received topic · topic_len length of the topic · data pointer to the received data · data_len length of the data for this event · current_data_offset offset of the current data for this event · total_data_len total length of the data received · retain retain flag of the message · qos qos level of the message · dup dup flag of the message Note: Multiple MQTT_EVENT_DATA could be fired for one message,
if it is longer than internal buffer. In that case only first event contains topic pointer and length, other contain data only with current data length and current data offset updating.
MQTT_EVENT_BEFORE_CONNECT The event occurs before connecting
MQTT_EVENT_DELETED Notification on delete of one message from the internal outbox, if the message couldnnt have been sent and acknowledged before expiring defined in OUTBOX_EXPIRED_TIMEOUT_MS. (events are not posted upon deletion of successfully acknowledged messages)
· This event id is posted only if MQTT_REPORT_DELETED_MESSAGES==1 · Additional context: msg_id (id of the deleted message). enum esp_mqtt_connect_return_code_t MQTT connection error codes propagated via ERROR event
Values:
MQTT_CONNECTION_ACCEPTED = 0 Connection accepted
MQTT_CONNECTION_REFUSE_PROTOCOL MQTT connection refused reason: Wrong protocol
MQTT_CONNECTION_REFUSE_ID_REJECTED MQTT connection refused reason: ID rejected
MQTT_CONNECTION_REFUSE_SERVER_UNAVAILABLE MQTT connection refused reason: Server unavailable
MQTT_CONNECTION_REFUSE_BAD_USERNAME MQTT connection refused reason: Wrong user
MQTT_CONNECTION_REFUSE_NOT_AUTHORIZED MQTT connection refused reason: Wrong username or password
enum esp_mqtt_error_type_t MQTT connection error codes propagated via ERROR event
Values:
MQTT_ERROR_TYPE_NONE = 0
MQTT_ERROR_TYPE_TCP_TRANSPORT

Espressif Systems

812

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
MQTT_ERROR_TYPE_CONNECTION_REFUSED enum esp_mqtt_transport_t
Values: MQTT_TRANSPORT_UNKNOWN = 0x0 MQTT_TRANSPORT_OVER_TCP
MQTT over TCP, using scheme: mqtt MQTT_TRANSPORT_OVER_SSL
MQTT over SSL, using scheme: mqtts MQTT_TRANSPORT_OVER_WS
MQTT over Websocket, using scheme:: ws MQTT_TRANSPORT_OVER_WSS
MQTT over Websocket Secure, using scheme: wss enum esp_mqtt_protocol_ver_t
MQTT protocol version used for connection Values: MQTT_PROTOCOL_UNDEFINED = 0 MQTT_PROTOCOL_V_3_1 MQTT_PROTOCOL_V_3_1_1
2.4.3 ESP-TLS
Overview
The ESP-TLS component provides a simplified API interface for accessing the commonly used TLS functionality. It supports common scenarios like CA certification validation, SNI, ALPN negotiation, non-blocking connection among others. All the configuration can be specified in the esp_tls_cfg_t data structure. Once done, TLS communication can be conducted using the following APIs:
· esp_tls_conn_new(): for opening a new TLS connection. · esp_tls_conn_read(): for reading from the connection. · esp_tls_conn_write(): for writing into the connection. · esp_tls_conn_destroy(): for freeing up the connection. Any application layer protocol like HTTP1, HTTP2 etc can be executed on top of this layer.
Application Example
Simple HTTPS example that uses ESP-TLS to establish a secure socket connection: protocols/https_request.
Tree structure for ESP-TLS component
 esp_tls.c  esp_tls.h  esp_tls_mbedtls.c  esp_tls_wolfssl.c  private_include
 esp_tls_mbedtls.h  esp_tls_wolfssl.h

Espressif Systems

813

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
The ESP-TLS component has a file esp-tls/esp_tls.h which contain the public API headers for the component. Internally ESP-TLS component uses one of the two SSL/TLS Libraries between mbedtls and wolfssl for its operation. API specific to mbedtls are present in esp-tls/private_include/esp_tls_mbedtls.h and API specific to wolfssl are present in esp-tls/private_include/esp_tls_wolfssl.h.
TLS Server verification
The ESP-TLS provides multiple options for TLS server verification on the client side. The ESP-TLS client can verify the server by validating the peerns server certificate or with the help of pre-shared keys. The user should select only one of the following options in the esp_tls_cfg_t structure for TLS server verification. If no option is selected then client will return a fatal error by default at the time of the TLS connection setup.
· cacert_buf and cacert_bytes: The CA certificate can be provided in a buffer to the esp_tls_cfg_t structure. The ESP-TLS will use the CA certificate present in the buffer to verify the server. The following variables in esp_tls_cfg_t structure must be set. ­ cacert_buf - pointer to the buffer which contains the CA cert. ­ cacert_bytes - size of the CA certificate in bytes.
· use_global_ca_store: The global_ca_store can be initialized and set at once. Then it can be used to verify the server for all the ESP-TLS connections which have set use_global_ca_store = true in their respective esp_tls_cfg_t structure. See API Reference section below on information regarding different API used for initializing and setting up the global_ca_store.
· crt_bundle_attach: The ESP x509 Certificate Bundle API provides an easy way to include a bundle of custom x509 root certificates for TLS server verification. More details can be found at ESP x509 Certificate Bundle
· psk_hint_key: To use pre-shared keys for server verification, CONFIG_ESP_TLS_PSK_VERIFICATION should be enabled in the ESP-TLS menuconfig. Then the pointer to PSK hint and key should be provided to the esp_tls_cfg_t structure. The ESP-TLS will use the PSK for server verification only when no other option regarding the server verification is selected.
· skip server verification: This is an insecure option provided in the ESP-TLS for testing purpose. The option can be set by enabling CONFIG_ESP_TLS_INSECURE and CONFIG_ESP_TLS_SKIP_SERVER_CERT_VERIFY in the ESP-TLS menuconfig. When this option is enabled the ESP-TLS will skip server verification by default when no other options for server verification are selected in the esp_tls_cfg_t structure. WARNING:Enabling this option comes with a potential risk of establishing a TLS connection with a server which has a fake identity, provided that the server certificate is not provided either through API or other mechanism like ca_store etc.
Underlying SSL/TLS Library Options
The ESP-TLS component has an option to use mbedtls or wolfssl as their underlying SSL/TLS library. By default only mbedtls is available and is used, wolfssl SSL/TLS library is available publicly at https://github.com/espressif/ esp-wolfssl. The repository provides wolfssl component in binary format, it also provides few examples which are useful for understanding the API. Please refer the repository README.md for information on licensing and other options. Please see below option for using wolfssl in your project.
Note: As the library options are internal to ESP-TLS, switching the libraries will not change ESP-TLS specific code for a project.

How to use wolfssl with ESP-IDF
There are two ways to use wolfssl in your project 1) Directly add wolfssl as a component in your project with following three commands.: (First change directory (cd) to your project directory) mkdir components

(continues on next page)

Espressif Systems

814

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

cd components git clone https://github.com/espressif/esp-wolfssl.git
2) Add wolfssl as an extra component in your project.
· Download wolfssl with:

(continued from previous page)

git clone https://github.com/espressif/esp-wolfssl.git
· Include esp-wolfssl in ESP-IDF with setting EXTRA_COMPONENT_DIRS in CMakeLists.txt of your project as done in wolfssl/examples. For reference see Optional Project variables in build-system.
After above steps, you will have option to choose wolfssl as underlying SSL/TLS library in configuration menu of your project as follows:

idf.py menuconfig -> ESP-TLS -> choose SSL/TLS Library -> mbedtls/wolfssl

Comparison between mbedtls and wolfssl
The following table shows a typical comparison between wolfssl and mbedtls when protocols/https_request example (which has server authentication) was run with both SSL/TLS libraries and with all respective configurations set to default. (mbedtls IN_CONTENT length and OUT_CONTENT length were set to 16384 bytes and 4096 bytes respectively)

Property Total Heap Consumed Task Stack Used Bin size

Wolfssl ~19 Kb ~2.2 Kb ~858 Kb

Mbedtls ~37 Kb ~3.6 Kb ~736 Kb

Note: These values are subject to change with change in configuration options and version of respective libraries.

Digital Signature with ESP-TLS
ESP-TLS provides support for using the Digital Signature (DS) with ESP32-S3. Use of the DS for TLS is supported only when ESP-TLS is used with mbedTLS (default stack) as its underlying SSL/TLS stack. For more details on Digital Signature, please refer to the Digital Signature Documentation. The technical details of Digital Signature such as how to calculate private key parameters can be found in ESP32-S3 Technical Reference Manual > Digital Signature (DS) [PDF]. The DS peripheral must be configured before it can be used to perform Digital Signature, see Configure the DS Peripheral in Digital Signature.
The DS peripheral must be initlized with the required encrypted private key parameters (obtained when the DS peripheral is configured). ESP-TLS internally initializes the DS peripheral when provided with the required DS context (DS parameters). Please see the below code snippet for passing the DS context to esp-tls context. The DS context passed to the esp-tls context should not be freed till the TLS connection is deleted.
#include "esp_tls.h" esp_ds_data_ctx_t *ds_ctx; /* initialize ds_ctx with encrypted private key parameters, which can be read from the nvs or provided through the application code */ esp_tls_cfg_t cfg = {
.clientcert_buf = /* the client cert */, .clientcert_bytes = /* length of the client cert */, /* other configurations options */ .ds_data = (void *)ds_ctx, };

Espressif Systems

815

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Note: When using Digital Signature for the TLS connection, along with the other required params, only the client cert (clientcert_buf) and the DS params (ds_data) are required and the client key (clientkey_buf) can be set to NULL.
· An example of mutual authentication with the DS peripheral can be found at ssl mutual auth which internally uses (ESP-TLS) for the TLS connection.
API Reference
Header File
· components/esp-tls/esp_tls.h
Functions esp_tls_t *esp_tls_init(void)
Create TLS connection.
This function allocates and initializes esp-tls structure handle.
Return tls Pointer to esp-tls as esp-tls handle if successfully initialized, NULL if allocation error esp_tls_t *esp_tls_conn_new(const char *hostname, int hostlen, int port, const esp_tls_cfg_t *cfg)
Create a new blocking TLS/SSL connection.
This function establishes a TLS/SSL connection with the specified host in blocking manner.
Note: This API is present for backward compatibility reasons. Alternative function with the same functionality is esp_tls_conn_new_sync (and its asynchronous version esp_tls_conn_new_async)
Return pointer to esp_tls_t, or NULL if connection couldnnt be opened. Parameters
· [in] hostname: Hostname of the host. · [in] hostlen: Length of hostname. · [in] port: Port number of the host. · [in] cfg: TLS configuration as esp_tls_cfg_t. If you wish to open non-TLS connection, keep this
NULL. For TLS connection, a pass pointer to esp_tls_cfg_t. At a minimum, this structure should be zero-initialized.
int esp_tls_conn_new_sync(const char *hostname, int hostlen, int port, const esp_tls_cfg_t *cfg, esp_tls_t *tls)
Create a new blocking TLS/SSL connection.
This function establishes a TLS/SSL connection with the specified host in blocking manner.
Return · -1 If connection establishment fails. · 1 If connection establishment is successful. · 0 If connection state is in progress.
Parameters · [in] hostname: Hostname of the host. · [in] hostlen: Length of hostname. · [in] port: Port number of the host. · [in] cfg: TLS configuration as esp_tls_cfg_t. If you wish to open non-TLS connection, keep this NULL. For TLS connection, a pass pointer to esp_tls_cfg_t. At a minimum, this structure should be zero-initialized. · [in] tls: Pointer to esp-tls as esp-tls handle.
esp_tls_t *esp_tls_conn_http_new(const char *url, const esp_tls_cfg_t *cfg) Create a new blocking TLS/SSL connection with a given oHTTPpurl.
The behaviour is same as esp_tls_conn_new() API. However this API accepts hostns url.
Return pointer to esp_tls_t, or NULL if connection couldnnt be opened.

Espressif Systems

816

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Parameters · [in] url: url of host. · [in] cfg: TLS configuration as esp_tls_cfg_t. If you wish to open non-TLS connection, keep this NULL. For TLS connection, a pass pointer to mesp_tls_cfg_tn. At a minimum, this structure should be zero-initialized.
int esp_tls_conn_new_async(const char *hostname, int hostlen, int port, const esp_tls_cfg_t *cfg, esp_tls_t *tls)
Create a new non-blocking TLS/SSL connection.
This function initiates a non-blocking TLS/SSL connection with the specified host, but due to its non-blocking nature, it doesnnt wait for the connection to get established.
Return · -1 If connection establishment fails. · 0 If connection establishment is in progress. · 1 If connection establishment is successful.
Parameters · [in] hostname: Hostname of the host. · [in] hostlen: Length of hostname. · [in] port: Port number of the host. · [in] cfg: TLS configuration as esp_tls_cfg_t. non_block member of this structure should be set to be true. · [in] tls: pointer to esp-tls as esp-tls handle.
int esp_tls_conn_http_new_async(const char *url, const esp_tls_cfg_t *cfg, esp_tls_t *tls) Create a new non-blocking TLS/SSL connection with a given oHTTPpurl.
The behaviour is same as esp_tls_conn_new() API. However this API accepts hostns url.
Return · -1 If connection establishment fails. · 0 If connection establishment is in progress. · 1 If connection establishment is successful.
Parameters · [in] url: url of host. · [in] cfg: TLS configuration as esp_tls_cfg_t. · [in] tls: pointer to esp-tls as esp-tls handle.
static ssize_t esp_tls_conn_write(esp_tls_t *tls, const void *data, size_t datalen) Write from buffer mdataninto specified tls connection.
Return · >=0 if write operation was successful, the return value is the number of bytes actually written to the TLS/SSL connection. · <0 if write operation was not successful, because either an error occured or an action must be taken by the calling process. · ESP_TLS_ERR_SSL_WANT_READ/ ESP_TLS_ERR_SSL_WANT_WRITE. if the handshake is incomplete and waiting for data to be available for reading. In this case this functions needs to be called again when the underlying transport is ready for operation.
Parameters · [in] tls: pointer to esp-tls as esp-tls handle. · [in] data: Buffer from which data will be written. · [in] datalen: Length of data buffer.
static ssize_t esp_tls_conn_read(esp_tls_t *tls, void *data, size_t datalen) Read from specified tls connection into the buffer mdatan.
Return · >0 if read operation was successful, the return value is the number of bytes actually read from the TLS/SSL connection. · 0 if read operation was not successful. The underlying connection was closed.

Espressif Systems

817

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· <0 if read operation was not successful, because either an error occured or an action must be taken by the calling process.
Parameters · [in] tls: pointer to esp-tls as esp-tls handle. · [in] data: Buffer to hold read data. · [in] datalen: Length of data buffer.
void esp_tls_conn_delete(esp_tls_t *tls) Compatible version of esp_tls_conn_destroy() to close the TLS/SSL connection.
Parameters · [in] tls: pointer to esp-tls as esp-tls handle.
int esp_tls_conn_destroy(esp_tls_t *tls) Close the TLS/SSL connection and free any allocated resources.
This function should be called to close each tls connection opened with esp_tls_conn_new() or esp_tls_conn_http_new() APIs.
Return - 0 on success · -1 if socket error or an invalid argument
Parameters · [in] tls: pointer to esp-tls as esp-tls handle.
ssize_t esp_tls_get_bytes_avail(esp_tls_t *tls) Return the number of application data bytes remaining to be read from the current record.
This API is a wrapper over mbedtlsns mbedtls_ssl_get_bytes_avail() API.
Return · -1 in case of invalid arg · bytes available in the application data record read buffer
Parameters · [in] tls: pointer to esp-tls as esp-tls handle.
esp_err_t esp_tls_get_conn_sockfd(esp_tls_t *tls, int *sockfd) Returns the connection socket file descriptor from esp_tls session.
Return - ESP_OK on success and value of sockfd will be updated with socket file descriptor for connection · ESP_ERR_INVALID_ARG if (tls == NULL || sockfd == NULL)
Parameters · [in] tls: handle to esp_tls context · [out] sockfd: int pointer to sockfd value.
esp_err_t esp_tls_init_global_ca_store(void) Create a global CA store, initially empty.
This function should be called if the application wants to use the same CA store for multiple connections. This function initialises the global CA store which can be then set by calling esp_tls_set_global_ca_store(). To be effective, this function must be called before any call to esp_tls_set_global_ca_store().
Return · ESP_OK if creating global CA store was successful. · ESP_ERR_NO_MEM if an error occured when allocating the mbedTLS resources.
esp_err_t esp_tls_set_global_ca_store(const unsigned char *cacert_pem_buf, const unsigned int cacert_pem_bytes)
Set the global CA store with the buffer provided in pem format.
This function should be called if the application wants to set the global CA store for multiple connections i.e. to add the certificates in the provided buffer to the certificate chain. This function implicitly calls esp_tls_init_global_ca_store() if it has not already been called. The application must call this function before calling esp_tls_conn_new().
Return · ESP_OK if adding certificates was successful.

Espressif Systems

818

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· Other if an error occured or an action must be taken by the calling process. Parameters
· [in] cacert_pem_buf: Buffer which has certificates in pem format. This buffer is used for creating a global CA store, which can be used by other tls connections.
· [in] cacert_pem_bytes: Length of the buffer.
void esp_tls_free_global_ca_store(void) Free the global CA store currently being used.
The memory being used by the global CA store to store all the parsed certificates is freed up. The application can call this API if it no longer needs the global CA store.
esp_err_t esp_tls_get_and_clear_last_error(esp_tls_error_handle_t h, int *esp_tls_code, int *esp_tls_flags)
Returns last error in esp_tls with detailed mbedtls related error codes. The error information is cleared internally upon return.
Return · ESP_ERR_INVALID_STATE if invalid parameters · ESP_OK (0) if no error occurred · specific error code (based on ESP_ERR_ESP_TLS_BASE) otherwise
Parameters · [in] h: esp-tls error handle. · [out] esp_tls_code: last error code returned from mbedtls api (set to zero if none) This pointer could be NULL if caller does not care about esp_tls_code · [out] esp_tls_flags: last certification verification flags (set to zero if none) This pointer could be NULL if caller does not care about esp_tls_code
esp_err_t esp_tls_get_and_clear_error_type(esp_tls_error_handle_t h, esp_tls_error_type_t err_type, int *error_code)
Returns the last error captured in esp_tls of a specific type The error information is cleared internally upon return.
Return · ESP_ERR_INVALID_STATE if invalid parameters · ESP_OK if a valid error returned and was cleared
Parameters · [in] h: esp-tls error handle. · [in] err_type: specific error type · [out] error_code: last error code returned from mbedtls api (set to zero if none) This pointer could be NULL if caller does not care about esp_tls_code
mbedtls_x509_crt *esp_tls_get_global_ca_store(void) Get the pointer to the global CA store currently being used.
The application must first call esp_tls_set_global_ca_store(). Then the same CA store could be used by the application for APIs other than esp_tls.
Note Modifying the pointer might cause a failure in verifying the certificates. Return
· Pointer to the global CA store currently being used if successful. · NULL if there is no global CA store set.
esp_err_t esp_tls_plain_tcp_connect(const char *host, int hostlen, int port, const esp_tls_cfg_t *cfg, esp_tls_error_handle_t error_handle, int *sockfd)
Creates a plain TCP connection, returning a valid socket fd on success or an error handle.
Return ESP_OK on success ESP_ERR_INVALID_ARG if invalid output parameters ESP-TLS based error codes on failure
Parameters · [in] host: Hostname of the host. · [in] hostlen: Length of hostname. · [in] port: Port number of the host. · [in] cfg: ESP-TLS configuration as esp_tls_cfg_t.

Espressif Systems

819

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· [out] error_handle: ESP-TLS error handle holding potential errors occurred during connection
· [out] sockfd: Socket descriptor if successfully connected on TCP layer
Structures struct psk_key_hint
ESP-TLS preshared key and hint structure.
Public Members
const uint8_t *key key in PSK authentication mode in binary format
const size_t key_size length of the key
const char *hint hint in PSK authentication mode in string format
struct tls_keep_alive_cfg esp-tls client session ticket ctx Keep alive parameters structure
Public Members
bool keep_alive_enable Enable keep-alive timeout
int keep_alive_idle Keep-alive idle time (second)
int keep_alive_interval Keep-alive interval time (second)
int keep_alive_count Keep-alive packet retry send count
struct esp_tls_cfg ESP-TLS configuration parameters. Note Note about format of certificates: · This structure includes certificates of a Certificate Authority, of client or server as well as private keys, which may be of PEM or DER format. In case of PEM format, the buffer must be NULL terminated (with NULL character included in certificate size). · Certificate Authorityns certificate may be a chain of certificates in case of PEM format, but could be only one certificate in case of DER format · Variables names of certificates and private key buffers and sizes are defined as unions providing backward compatibility for legacy *_pem_buf and *_pem_bytes names which suggested only PEM format was supported. It is encouraged to use generic names such as cacert_buf and cacert_bytes.
Public Members
const char **alpn_protos Application protocols required for HTTP2. If HTTP2/ALPN support is required, a list of protocols that should be negotiated. The format is length followed by protocol name. For the most common cases the following is ok: const char **alpn_protos = { oh2p, NULL }; · where mh2nis the protocol name

Espressif Systems

820

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
const unsigned char *cacert_buf Certificate Authorityns certificate in a buffer. Format may be PEM or DER, depending on mbedtlssupport This buffer should be NULL terminated in case of PEM
const unsigned char *cacert_pem_buf CA certificate buffer legacy name
unsigned int cacert_bytes Size of Certificate Authority certificate pointed to by cacert_buf (including NULL-terminator in case of PEM format)
unsigned int cacert_pem_bytes Size of Certificate Authority certificate legacy name
const unsigned char *clientcert_buf Client certificate in a buffer Format may be PEM or DER, depending on mbedtls-support This buffer should be NULL terminated in case of PEM
const unsigned char *clientcert_pem_buf Client certificate legacy name
unsigned int clientcert_bytes Size of client certificate pointed to by clientcert_pem_buf (including NULL-terminator in case of PEM format)
unsigned int clientcert_pem_bytes Size of client certificate legacy name
const unsigned char *clientkey_buf Client key in a buffer Format may be PEM or DER, depending on mbedtls-support This buffer should be NULL terminated in case of PEM
const unsigned char *clientkey_pem_buf Client key legacy name
unsigned int clientkey_bytes Size of client key pointed to by clientkey_pem_buf (including NULL-terminator in case of PEM format)
unsigned int clientkey_pem_bytes Size of client key legacy name
const unsigned char *clientkey_password Client key decryption password string
unsigned int clientkey_password_len String length of the password pointed to by clientkey_password
bool non_block Configure non-blocking mode. If set to true the underneath socket will be configured in non blocking mode after tls session is established
bool use_secure_element Enable this option to use secure element or atecc608a chip ( Integrated with ESP32-WROOM-32SE )
int timeout_ms Network timeout in milliseconds
bool use_global_ca_store Use a global ca_store for all the connections in which this bool is set.
const char *common_name If non-NULL, server certificate CN must match this name. If NULL, server certificate CN must match hostname.
bool skip_common_name Skip any validation of server certificate CN field

Espressif Systems

821

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

tls_keep_alive_cfg_t *keep_alive_cfg Enable TCP keep-alive timeout for SSL connection
const psk_hint_key_t *psk_hint_key Pointer to PSK hint and key. if not NULL (and certificates are NULL) then PSK authentication is enabled with configured setup. Important note: the pointer must be valid for connection
esp_err_t (*crt_bundle_attach)(void *conf) Function pointer to esp_crt_bundle_attach. Enables the use of certification bundle for server verification, must be enabled in menuconfig
void *ds_data Pointer for digital signature peripheral context
bool is_plain_tcp Use non-TLS connection: When set to true, the esp-tls uses plain TCP transport rather then TLS/SSL connection. Note, that it is possible to connect using a plain tcp transport directly with esp_tls_plain_tcp_connect() API
struct ifreq *if_name The name of interface for data to go through. Use the default interface without setting
struct esp_tls ESP-TLS Connection Handle.
Public Members
mbedtls_ssl_context ssl TLS/SSL context
mbedtls_entropy_context entropy mbedTLS entropy context structure
mbedtls_ctr_drbg_context ctr_drbg mbedTLS ctr drbg context structure. CTR_DRBG is deterministic random bit generation based on AES256
mbedtls_ssl_config conf TLS/SSL configuration to be shared between mbedtls_ssl_context structures
mbedtls_net_context server_fd mbedTLS wrapper type for sockets
mbedtls_x509_crt cacert Container for the X.509 CA certificate
mbedtls_x509_crt *cacert_ptr Pointer to the cacert being used.
mbedtls_x509_crt clientcert Container for the X.509 client certificate
mbedtls_pk_context clientkey Container for the private key of the client certificate
int sockfd Underlying socket file descriptor.
ssize_t (*read)(struct esp_tls *tls, char *data, size_t datalen) Callback function for reading data from TLS/SSL connection.
ssize_t (*write)(struct esp_tls *tls, const char *data, size_t datalen) Callback function for writing data to TLS/SSL connection.
esp_tls_conn_state_t conn_state ESP-TLS Connection state

Espressif Systems

822

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

fd_set rset read file descriptors
fd_set wset write file descriptors
bool is_tls indicates connection type (TLS or NON-TLS)
esp_tls_role_t role esp-tls role
· ESP_TLS_CLIENT · ESP_TLS_SERVER
esp_tls_error_handle_t error_handle handle to error descriptor

Type Definitions typedef enum esp_tls_conn_state esp_tls_conn_state_t
ESP-TLS Connection State. typedef enum esp_tls_role esp_tls_role_t
typedef struct psk_key_hint psk_hint_key_t ESP-TLS preshared key and hint structure.
typedef struct tls_keep_alive_cfg tls_keep_alive_cfg_t esp-tls client session ticket ctx
Keep alive parameters structure
typedef struct esp_tls_cfg esp_tls_cfg_t ESP-TLS configuration parameters.
Note Note about format of certificates: · This structure includes certificates of a Certificate Authority, of client or server as well as private keys, which may be of PEM or DER format. In case of PEM format, the buffer must be NULL terminated (with NULL character included in certificate size). · Certificate Authorityns certificate may be a chain of certificates in case of PEM format, but could be only one certificate in case of DER format · Variables names of certificates and private key buffers and sizes are defined as unions providing backward compatibility for legacy *_pem_buf and *_pem_bytes names which suggested only PEM format was supported. It is encouraged to use generic names such as cacert_buf and cacert_bytes.
typedef struct esp_tls esp_tls_t ESP-TLS Connection Handle.

Enumerations enum esp_tls_conn_state
ESP-TLS Connection State.
Values:
ESP_TLS_INIT = 0
ESP_TLS_CONNECTING
ESP_TLS_HANDSHAKE
ESP_TLS_FAIL
ESP_TLS_DONE enum esp_tls_role
Values:
ESP_TLS_CLIENT = 0

Espressif Systems

823

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_TLS_SERVER
2.4.4 OpenSSL-APIs
Note: The OpenSSL-API will be discontinued in ESP-IDF from v5.0. Please use ESP-TLS <esp_tls> instead.
The code of this API (located in openssl directory), does not contain OpenSSL itself but is intended as a wrapper for applications using the OpenSSL API. It uses mbedTLS to do the actual work, so anyone compiling openssl code needs the mbedtls library and header file. OpenSSL APIs not mentioned in this article are not open to public for the time, also do not have the corresponding function. If user calls it directly, it will always return an error or may show cannot link at compiling time.
Chapter Introduction
· Chapter 1. SSL Context Method Create · Chapter 2. SSL Context Function · Chapter 3. SSL Function · Chapter 4. SSL X509 Certification and Private Key Function
Chapter 1. SSL Context Method Create
1.1 const SSL_METHOD* SSLv3_client_method (void) Arguments: none
Return: SSLV3.0 version SSL context client method point
Description: create the target SSL context method
Example: void example(void) {
const SSL_METHOD *method = SSLv3_client_method(); ... }
1.2 const SSL_METHOD* TLSv1_client_method (void) Arguments: none
Return: TLSV1.0 version SSL context client method point
Description:

Espressif Systems

824

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
create the target SSL context method
Example: void example(void) {
const SSL_METHOD *method = TLSv1_client_method();
... }
1.3 const SSL_METHOD* TLSv1_1_client_method (void) Arguments: none
Return: TLSV1.1 version SSL context client method point
Description: create the target SSL context method
Example: void example(void) {
const SSL_METHOD *method = TLSv1_1_client_method();
... }
1.4 const SSL_METHOD* TLSv1_2_client_method (void) Arguments: none
Return: TLSV1.2 version SSL context client method point
Description: create the target SSL context method
Example: void example(void) {
const SSL_METHOD *method = TLSv1_2_client_method();
... }
1.5 const SSL_METHOD* TLS_client_method (void) Arguments: none

Espressif Systems

825

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return: TLSV1.2 version SSL context client method point
Description: create the default SSL context method, it's always to be TLSV1.2
Example: void example(void) {
const SSL_METHOD *method = TLSv1_2_client_method();
... }
1.6 const SSL_METHOD* SSLv3_server_method (void) Arguments: none
Return: SSLV3.0 version SSL context server method point
Description: create the target SSL context method
Example: void example(void) {
const SSL_METHOD *method = SSLv3_server_method();
... }
1.7 const SSL_METHOD* TLSv1_server_method (void) Arguments: none
Return: TLSV1.0 version SSL context server method point
Description: create the target SSL context method
Example: void example(void) {
const SSL_METHOD *method = TLSv1_server_method();
... }
1.8 const SSL_METHOD* TLSv1_1_server_method (void)

Espressif Systems

826

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Arguments: none

Return: TLSV1.1 version SSL context server method point

Description: create the target SSL context method

Example:
void example(void) {
const SSL_METHOD *method = TLSv1_1_server_method();

... }

1.9 const SSL_METHOD* TLSv1_2_server_method (void) Arguments: none

Return: TLSV1.2 version SSL context server method point

Description: create the target SSL context method

Example:
void example(void) {
const SSL_METHOD *method = TLSv1_2_server_method();

... }

1.10 const SSL_METHOD* TLS_server_method (void) Arguments: none

Return: TLSV1.2 version SSL context server method point

Description: create the default SSL context method, it's always to be TLSV1.2

Example:
void example(void) {
const SSL_METHOD *method = TLSv1_2_server_method();

(continues on next page)

Espressif Systems

827

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

... }

(continued from previous page)

Chapter 2. SSL Context Function
2.1 SSL_CTX* SSL_CTX_new (const SSL_METHOD * method) Arguments: method - the SSL context method point
Return: context point
Description: create a SSL context
Example: void example(void) {
SSL_CTX *ctx = SSL_CTX_new(SSLv3_server_method());
... }
2.2 void SSL_CTX_free (SSL_CTX * ctx) Arguments: ctx - the SSL context point
Return: none
Description: free a SSL context
Example: void example(void) {
SSL_CTX *ctx;
... ...
SSL_CTX_free(ctx); }
2.3 int SSL_CTX_set_ssl_version (SSL_CTX * ctx, const SSL_METHOD * meth) Arguments: ctx - SSL context point meth - SSL method point

Espressif Systems

828

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Return: 1 : OK 0 : failed
Description: set the SSL context version
Example: void example(void) {
SSL_CTX *ctx; const SSL_METHOD *meth; ... ... SSL_CTX_set_ssl_version(ctx, meth); }
2.4 const SSL_METHOD* SSL_CTX_get_ssl_method (SSL_CTX * ctx) Arguments: ctx - SSL context point
Return: SSL context method
Description: get the SSL context method
Example: void example(void) {
const SSL_METHOD *method; SSL_CTX *ctx; ... ... method = SSL_CTX_get_ssl_method(ctx); }
Chapter 3. SSL Function
3.1 SSL* SSL_new (SSL_CTX * ctx) Arguments: ctx - SSL context point
Return: SSL method
Description:

Espressif Systems

829

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

create a SSL
Example: void example(void) {
SSL *ssl; SSL_CTX *ctx;
... ...
ssl = SSL_new(ctx); }
3.2 void SSL_free (SSL * ssl) Arguments: ssl - SSL point
Return: none
Description: free SSL
Example: void example(void) {
SSL *ssl;
... ...
SSL_free(ssl); }
3.3 int SSL_do_handshake (SSL * ssl) Arguments: ssl - SSL point
Return: 1 : OK 0 : failed, connect is close by remote
-1 : a error catch
Description: perform the SSL handshake
Example: void example(void) {
SSL *ssl; int ret;

(continues on next page)

Espressif Systems

830

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

... ...
ret = SSL_do_handshake(ssl); }
3.4 int SSL_connect (SSL * ssl) Arguments: ssl - SSL point
Return: 1 : OK 0 : failed, connect is close by remote
-1 : a error catch
Description: connect to the remote SSL server
Example: void example(void) {
SSL *ssl; int ret;
... ...
ret = SSL_connect(ssl); }
3.5 int SSL_accept (SSL * ssl) Arguments: ssl - SSL point
Return: 1 : OK 0 : failed, connect is close by remote
-1 : a error catch
Description: accept the remote connection
Example: void example(void) {
SSL *ssl; int ret;
... ...
ret = SSL_accept(ssl); }
3.6 int SSL_shutdown (SSL * ssl)

(continued from previous page)

Espressif Systems

831

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Arguments: ssl - SSL point
Return: 1 : OK 0 : failed, connect is close by remote
-1 : a error catch
Description: shutdown the connection
Example: void example(void) {
SSL *ssl; int ret;
... ...
ret = SSL_shutdown(ssl); }
3.7 int SSL_clear (SSL * ssl) Arguments: ssl - SSL point
Return: 1 : OK 0 : failed
Description: shutdown the connection
Example: void example(void) {
SSL *ssl; int ret;
... ...
ret = SSL_clear(ssl); }
3.8 int SSL_read (SSL * ssl, void * buffer, int len) Arguments: ssl - point buffer - data buffer point len - data length
Return:

Espressif Systems

832

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
> 0 : OK, and return received data bytes = 0 : no data received or connection is closed < 0 : an error catch
Description:
read data from remote
Example:
void example(void) {
SSL *ssl; char *buf; int len; int ret;
... ...
ret = SSL_read(ssl, buf, len); }
3.9 int SSL_write (SSL * ssl, const void * buffer, int len) Arguments:
ssl - SSL point buffer - data buffer point len - data length
Return:
> 0 : OK, and return received data bytes = 0 : no data sent or connection is closed < 0 : an error catch
Description:
send the data to remote
Example:
void example(void) {
SSL *ssl; char *buf; int len; int ret;
... ...
ret = SSL_write(ssl, buf, len); }
3.10 SSL_CTX *SSL_get_SSL_CTX (const SSL * ssl) Arguments:
ssl - SSL point
Return:

Espressif Systems

833

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
SSL context
Description: get SSL context of the SSL
Example: void example(void) {
SSL *ssl; SSL_CTX *ctx; ... ... ctx = SSL_get_SSL_CTX(ssl); }
3.11 int SSL_get_shutdown (const SSL * ssl) Arguments: ssl - SSL point
Return: shutdown mode
Description: get SSL shutdown mode
Example: void example(void) {
SSL *ssl; int mode; ... ... mode = SSL_get_SSL_CTX(ssl); }
3.12 void SSL_set_shutdown (SSL * ssl, int mode) Arguments: ssl - SSL point
Return: shutdown mode
Description: set SSL shutdown mode
Example:

Espressif Systems

834

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

void example(void) {
SSL *ssl; int mode = 0;
... ...
SSL_set_shutdown(ssl, mode); }
3.13 const SSL_METHOD* SSL_get_ssl_method (SSL * ssl) Arguments:
ssl - SSL point
Return:
SSL method
Description:
set SSL shutdown mode
Example:
void example(void) {
SSL *ssl; const SSL_METHOD *method;
... ...
method = SSL_get_ssl_method(ssl); }
3.14 int SSL_set_ssl_method (SSL * ssl, const SSL_METHOD * method) Arguments:
ssl - SSL point meth - SSL method point
Return:
1 : OK 0 : failed
Description:
set the SSL method
Example:
void example(void) {
int ret; SSL *ssl; const SSL_METHOD *method;
... ...

(continues on next page)

Espressif Systems

835

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ret = SSL_set_ssl_method(ssl, method); }
3.15 int SSL_pending (const SSL * ssl) Arguments: ssl - SSL point
Return: data bytes
Description: get received data bytes
Example: void example(void) {
int ret; SSL *ssl;
... ...
ret = SSL_pending(ssl); }
3.16 int SSL_has_pending (const SSL * ssl) Arguments: ssl - SSL point
Return: 1 : Yes 0 : No
Description: check if data is received
Example: void example(void) {
int ret; SSL *ssl;
... ...
ret = SSL_has_pending(ssl); }
3.17 int SSL_get_fd (const SSL * ssl) Arguments: ssl - SSL point
Return:

(continued from previous page)

Espressif Systems

836

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

>= 0 : socket id < 0 : a error catch
Description: get the socket of the SSL
Example: void example(void) {
int ret; SSL *ssl;
... ...
ret = SSL_get_fd(ssl); }
3.18 int SSL_get_rfd (const SSL * ssl) Arguments: ssl - SSL point
Return: >= 0 : socket id
< 0 : a error catch
Description: get the read only socket of the SSL
Example: void example(void) {
int ret; SSL *ssl;
... ...
ret = SSL_get_rfd(ssl); }
3.19 int SSL_get_wfd (const SSL * ssl) Arguments: ssl - SSL point
Return: >= 0 : socket id
< 0 : a error catch
Description: get the write only socket of the SSL
Example:

Espressif Systems

837

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

void example(void) {
int ret; SSL *ssl;
... ...
ret = SSL_get_wfd(ssl); }
3.20 int SSL_set_fd (SSL * ssl, int fd) Arguments:
ssl - SSL point fd - socket id
Return:
1 : OK 0 : failed
Description:
set socket to SSL
Example:
void example(void) {
int ret; SSL *ssl; int socket;
... ...
ret = SSL_set_fd(ssl, socket); }
3.21 int SSL_set_rfd (SSL * ssl, int fd) Arguments:
ssl - SSL point fd - socket id
Return:
1 : OK 0 : failed
Description:
set read only socket to SSL
Example:
void example(void) {
int ret; SSL *ssl; int socket;

(continues on next page)

Espressif Systems

838

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

... ...
ret = SSL_set_rfd(ssl, socket); }
3.22 int SSL_set_wfd (SSL * ssl, int fd) Arguments: ssl - SSL point fd - socket id
Return: 1 : OK 0 : failed
Description: set write only socket to SSL
Example: void example(void) {
int ret; SSL *ssl; int socket;
... ...
ret = SSL_set_wfd(ssl, socket); }
3.23 int SSL_version (const SSL * ssl) Arguments: ssl - SSL point
Return: SSL version
Description: get SSL version
Example: void example(void) {
int version; SSL *ssl;
... ...
version = SSL_version(ssl); }
3.24 const char* SSL_get_version (const SSL * ssl)

(continued from previous page)

Espressif Systems

839

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Arguments: ssl - SSL point
Return: SSL version string
Description: get the SSL current version string
Example: void example(void) {
char *version; SSL *ssl; ... ... version = SSL_get_version(ssl); }
3.25 OSSL_HANDSHAKE_STATE SSL_get_state (const SSL * ssl) Arguments: ssl - SSL point
Return: SSL state
Description: get the SSL state
Example: void example(void) {
OSSL_HANDSHAKE_STATE state; SSL *ssl; ... ... state = SSL_get_state(ssl); }
3.26 const char* SSL_alert_desc_string (int value) Arguments: value - SSL description
Return: alert value string
Description:

Espressif Systems

840

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

get alert description string
Example: void example(void) {
int val; char *str;
... ...
str = SSL_alert_desc_string(val); }
3.27 const char* SSL_alert_desc_string_long (int value) Arguments: value - SSL description
Return: alert value long string
Description: get alert description long string
Example: void example(void) {
int val; char *str;
... ...
str = SSL_alert_desc_string_long(val); }
3.28 const char* SSL_alert_type_string (int value) Arguments: value - SSL type description
Return: alert type string
Description: get alert type string
Example: void example(void) {
int val; char *str;
... ...

(continues on next page)

Espressif Systems

841

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

str = SSL_alert_type_string(val); }
3.29 const char* SSL_alert_type_string_long (int value) Arguments: value - SSL type description
Return: alert type long string
Description: get alert type long string
Example: void example(void) {
int val; char *str;
... ...
str = SSL_alert_type_string_long(val); }
3.30 const char* SSL_rstate_string (SSL * ssl) Arguments: ssl - SSL point
Return: state string
Description: get the state string where SSL is reading
Example: void example(void) {
SSL *ssl; char *str;
... ...
str = SSL_rstate_string(ssl); }
3.31 const char* SSL_rstate_string_long (SSL * ssl) Arguments: ssl - SSL point
Return:

(continued from previous page)

Espressif Systems

842

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
state long string
Description: get the state long string where SSL is reading
Example: void example(void) {
SSL *ssl; char *str; ... ... str = SSL_rstate_string_long(ssl); }
3.32 const char* SSL_state_string (const SSL * ssl) Arguments: ssl - SSL point
Return: state string
Description: get the state string
Example: void example(void) {
SSL *ssl; const char *str; ... ... str = SSL_state_string(ssl); }
3.33 char* SSL_state_string_long (const SSL * ssl) Arguments: ssl - SSL point
Return: state long string
Description: get the state long string
Example:

Espressif Systems

843

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

void example(void) {
SSL *ssl; char *str;

... ...

str = SSL_state_string(ssl); }

3.34 int SSL_get_error (const SSL * ssl, int ret_code) Arguments:

ssl

- SSL point

ret_code - SSL return code

Return: SSL error number

Description: get SSL error code

Example:
void example(void) {
SSL *ssl; int ret; int err;

... ...

err = SSL_get_error(ssl, ret); }

3.35 int SSL_want (const SSL * ssl) Arguments: ssl - SSL point

Return: specifical statement

Description: get the SSL specifical statement

Example:
void example(void) {
SSL *ssl; int state;

... ...
state = SSL_want(ssl); }

Espressif Systems

844

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

3.36 int SSL_want_nothing (const SSL * ssl) Arguments: ssl - SSL point
Return: 0 : false 1 : true
Description: check if SSL want nothing
Example: void example(void) {
SSL *ssl; int ret;
... ...
ret = SSL_want(ssl); }
3.37 int SSL_want_read (const SSL * ssl) Arguments: ssl - SSL point
Return: 0 : false 1 : true
Description: check if SSL want to read
Example: void example(void) {
SSL *ssl; int ret;
... ...
ret = SSL_want_read(ssl); }
3.38 int SSL_want_write (const SSL * ssl) Arguments: ssl - SSL point
Return: 0 : false 1 : true

Espressif Systems

845

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Description:
check if SSL want to write
Example:
void example(void) {
SSL *ssl; int ret;
... ...
ret = SSL_want_write(ssl); }
Chapter 4. SSL X509 Certification and Private Key Function
4.1 X509 * d2i_X509 (X509 ** cert, const unsigned char * buffer, long len) Arguments:
cert - a point pointed to X509 certification buffer - a point pointed to the certification context memory point length - certification bytes
Return:
X509 certification object point
Description:
load a character certification context into system context. If '*cert' is pointed to the certification, then load certification into it. Or create a new X509 certification object
Example:
void example(void) {
X509 *new; X509 *cert; unsigned char *buffer; long len; ... ...
new = d2i_X509(&cert, buffer, len); }
4.2 int SSL_add_client_CA (SSL * ssl, X509 * x) Arguments:
ssl - SSL point x - CA certification point
Return:
1 : OK 0 : failed

Espressif Systems

846

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Description: add CA client certification into the SSL
Example: void example(void) {
int ret; SSL *ssl; X509 *new;
... ...
ret = SSL_add_client_CA(ssl, new); }
4.3 int SSL_CTX_add_client_CA (SSL_CTX * ctx, X509 * x) Arguments: ctx - SSL context point x - CA certification point
Return: 1 : OK 0 : failed
Description: add CA client certification into the SSL context
Example: void example(void) {
int ret; SSL_CTX *ctx; X509 *new;
... ...
ret = SSL_add_clSSL_CTX_add_client_CAient_CA(ctx, new); }
4.4 X509* SSL_get_certificate (const SSL * ssl) Arguments: ssl - SSL point
Return: SSL certification point
Description: get the SSL certification point
Example:

Espressif Systems

847

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

void example(void) {
SSL *ssl; X509 *cert;
... ...
cert = SSL_get_certificate(ssl); }
4.5 long SSL_get_verify_result (const SSL * ssl) Arguments:
ssl - SSL point
Return:
the result of verifying
Description:
get the verifying result of the SSL certification
Example:
void example(void) {
SSL *ssl; long ret;
... ...
ret = SSL_get_verify_result(ssl); }
4.6 int SSL_CTX_use_certificate (SSL_CTX * ctx, X509 * x) Arguments:
ctx - the SSL context point pkey - certification object point
Return:
1 : OK 0 : failed
Description:
load the certification into the SSL_CTX or SSL object
Example:
void example(void) {
int ret; SSL_CTX *ctx X509 *new;
... ...

(continues on next page)

Espressif Systems

848

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ret = SSL_CTX_use_certificate(ctx, new); }

(continued from previous page)

4.7 int SSL_CTX_use_certificate_ASN1 (SSL_CTX * ctx, int len, const unsigned char * d)
Arguments:
ctx - SSL context point len - certification length d - data point

Return:
1 : OK 0 : failed

Description: load the ASN1 certification into SSL context

Example:
void example(void) {
int ret; SSL_CTX *ctx; const unsigned char *buf; int len;
... ...
ret = SSL_CTX_use_certificate_ASN1(ctx, len, buf); }

4.8 int SSL_CTX_use_PrivateKey (SSL_CTX * ctx, EVP_PKEY * pkey) Arguments:
ctx - SSL context point pkey - private key object point

Return:
1 : OK 0 : failed

Description: load the private key into the context object

Example:
void example(void) {
int ret; SSL_CTX *ctx; EVP_PKEY *pkey;
... ...
ret = SSL_CTX_use_PrivateKey(ctx, pkey); }

Espressif Systems

849

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

4.9 int SSL_CTX_use_PrivateKey_ASN1 (int pk, SSL_CTX * ctx, const unsigned char * d, long len) Arguments:
ctx - SSL context point d - data point len - private key length
Return:
1 : OK 0 : failed
Description:
load the ASN1 private key into SSL context
Example:
void example(void) {
int ret; int pk; SSL_CTX *ctx; const unsigned char *buf; long len;
... ...
ret = SSL_CTX_use_PrivateKey_ASN1(pk, ctx, buf, len); }
4.10 int SSL_CTX_use_RSAPrivateKey_ASN1 (SSL_CTX * ctx, const unsigned char * d, long len) Arguments:
ctx - SSL context point d - data point len - private key length
Return:
1 : OK 0 : failed
Description:
load the RSA ASN1 private key into SSL context
Example:
void example(void) {
int ret; SSL_CTX *ctx; const unsigned char *buf; long len;
... ...
ret = SSL_CTX_use_RSAPrivateKey_ASN1(ctx, buf, len); }
4.11 int SSL_use_certificate_ASN1 (SSL * ssl, int len, const unsigned char * d)

Espressif Systems

850

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Arguments:
ssl - SSL point len - data bytes d - data point
Return:
1 : OK 0 : failed
Description:
load certification into the SSL
Example:
void example(void) {
int ret; SSL *ssl; const unsigned char *buf; long len;
... ...
ret = SSL_use_certificate_ASN1(ssl, len, buf); }
4.12 X509* SSL_get_peer_certificate (const SSL * ssl) Arguments:
ssl - SSL point
Return:
peer certification
Description:
get peer certification
Example:
void example(void) {
SSL *ssl; X509 *peer;
... ...
peer = SSL_get_peer_certificate(ssl); }

2.4.5 ESP HTTP Client
Overview
esp_http_client provides an API for making HTTP/S requests from ESP-IDF applications. The steps to use this API are as follows:

Espressif Systems

851

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· esp_http_client_init(): Creates an esp_http_client_config_t instance i.e. a HTTP client handle based on the given esp_http_client_config_t configuration. This function must be the first to be called; default values will be assumed for the configuration values that are not explicitly defined by the user.
· esp_http_client_perform(): Performs all operations of the esp_http_client - opening the connection, exchanging data and closing the connection (as required), while blocking the current task until its completion. All related events will be invoked through the event handler (as specified in esp_http_client_config_t).
· esp_http_client_cleanup(): Closes the connection (if any) and frees up all the memory allocated to the HTTP client instance. This must be the last function to be called after the completion of operations.

Application Example Simple example that uses ESP HTTP Client to make HTTP/S requests at protocols/esp_http_client.

Basic HTTP request
Check out the example functions http_rest_with_url and http_rest_with_hostname_path in the application example for implementation details.

Persistent Connections
Persistent connection means that the HTTP client can re-use the same connection for several exchanges. If the server does not request to close the connection with the Connection: close header, the connection is not dropped but is instead kept open and used for further requests.
To allow ESP HTTP client to take full advantage of persistent connections, one should make as many requests as possible using the same handle instance.
Check out the example functions http_rest_with_url and http_rest_with_hostname_path in the application example. Here, once the connection is created, multiple requests (GET, POST, PUT, etc.) are made before the connection is closed.

HTTPS Request
ESP HTTP client supports SSL connections using mbedTLS, with the url configuration starting with https scheme or transport_type set to HTTP_TRANSPORT_OVER_SSL. HTTPS support can be configured via CONFIG_ESP_HTTP_CLIENT_ENABLE_HTTPS (enabled by default).
Note: While making HTTPS requests, if server verification is needed, additional root certificate (in PEM format) needs to be provided to the cert_pem member in esp_http_client_config_t configuration. Users can also use the ESP x509 Certificate Bundle for server verification using the crt_bundle_attach member of the esp_http_client_config_t configuration.
Check out the example functions https_with_url and https_with_hostname_path in the application example. (Implementation details of the above note are found here)

HTTP Stream
Some applications need to open the connection and control the exchange of data actively (data streaming). In such cases, the application flow is different from regular requests. Example flow is given below:
· esp_http_client_init(): Create a HTTP client handle · esp_http_client_set_* or esp_http_client_delete_*: Modify the HTTP connection pa-
rameters (optional)

Espressif Systems

852

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· esp_http_client_open(): Open the HTTP connection with write_len parameter (content length that needs to be written to server), set write_len=0 for read-only connection
· esp_http_client_write(): Write data to server with a maximum length equal to write_len of esp_http_client_open() function; no need to call this function for write_len=0
· esp_http_client_fetch_headers(): Read the HTTP Server response headers, after sending the request headers and server data (if any). Returns the content-length from the server and can be succeeded by esp_http_client_get_status_code() for getting the HTTP status of the connection.
· esp_http_client_read(): Read the HTTP stream · esp_http_client_close(): Close the connection · esp_http_client_cleanup(): Release allocated resources
Check out the example function http_perform_as_stream_reader in the application example for implementation details.
HTTP Authentication
ESP HTTP client supports both Basic and Digest Authentication. · Users can provide the username and password in the url or the username and password members of the esp_http_client_config_t configuration. For auth_type = HTTP_AUTH_TYPE_BASIC, the HTTP client takes only 1 perform operation to pass the authentication process. · If auth_type = HTTP_AUTH_TYPE_NONE, but the username and password fields are present in the configuration, the HTTP client takes 2 perform operations. The client will receive the 401 Unauthorized header in its first attempt to connect to the server. Based on this information, it decides which authentication method to choose and performs it in the second operation. · Check out the example functions http_auth_basic, http_auth_basic_redirect (for Basic authentication) and http_auth_digest (for Digest authentication) in the application example for implementation details.
Examples of Authentication Configuration
· Authentication with URI
esp_http_client_config_t config = { .url = "http://user:[email protected]/basic-auth/user/passwd", .auth_type = HTTP_AUTH_TYPE_BASIC,
};
· Authentication with username and password entry
esp_http_client_config_t config = { .url = "http://httpbin.org/basic-auth/user/passwd", .username = "user", .password = "passwd", .auth_type = HTTP_AUTH_TYPE_BASIC,
};

API Reference
Header File · components/esp_http_client/include/esp_http_client.h

Functions esp_http_client_handle_t esp_http_client_init(const esp_http_client_config_t *config)
Start a HTTP session This function must be the first function to call, and it returns a esp_http_client_handle_t that you must use as input to other functions in the interface. This call MUST have a corresponding call to esp_http_client_cleanup when the operation is complete.

Espressif Systems

853

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return · esp_http_client_handle_t · NULL if any errors
Parameters · [in] config: The configurations, see http_client_config_t
esp_err_t esp_http_client_perform(esp_http_client_handle_t client) Invoke this function after esp_http_client_init and all the options calls are made, and will perform the transfer as described in the options. It must be called with the same esp_http_client_handle_t as input as the esp_http_client_init call returned. esp_http_client_perform performs the entire request in either blocking or non-blocking manner. By default, the API performs request in a blocking manner and returns when done, or if it failed, and in non-blocking manner, it returns if EAGAIN/EWOULDBLOCK or EINPROGRESS is encountered, or if it failed. And in case of non-blocking request, the user may call this API multiple times unless request & response is complete or there is a failure. To enable non-blocking esp_http_client_perform(), is_async member of esp_http_client_config_t must be set while making a call to esp_http_client_init() API. You can do any amount of calls to esp_http_client_perform while using the same esp_http_client_handle_t. The underlying connection may be kept open if the server allows it. If you intend to transfer more than one file, you are even encouraged to do so. esp_http_client will then attempt to re-use the same connection for the following transfers, thus making the operations faster, less CPU intense and using less network resources. Just note that you will have to use esp_http_client_set_** between the invokes to set options for the following esp_http_client_perform.
Note You must never call this function simultaneously from two places using the same client handle. Let the function return first before invoking it another time. If you want parallel transfers, you must use several esp_http_client_handle_t. This function include esp_http_client_open -> esp_http_client_write -> esp_http_client_fetch_headers -> esp_http_client_read (and option) esp_http_client_close.
Return · ESP_OK on successful · ESP_FAIL on error
Parameters · client: The esp_http_client handle
esp_err_t esp_http_client_set_url(esp_http_client_handle_t client, const char *url) Set URL for client, when performing this behavior, the options in the URL will replace the old ones.
Return · ESP_OK · ESP_FAIL
Parameters · [in] client: The esp_http_client handle · [in] url: The url
esp_err_t esp_http_client_set_post_field(esp_http_client_handle_t client, const char *data, int len)
Set post data, this function must be called before esp_http_client_perform. Note: The data parameter passed to this function is a pointer and this function will not copy the data.
Return · ESP_OK · ESP_FAIL
Parameters · [in] client: The esp_http_client handle · [in] data: post data pointer · [in] len: post length
int esp_http_client_get_post_field(esp_http_client_handle_t client, char **data) Get current post field information.
Return Size of post data Parameters
· [in] client: The client · [out] data: Point to post data pointer

Espressif Systems

854

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t esp_http_client_set_header(esp_http_client_handle_t client, const char *key, const char *value)
Set http request header, this function must be called after esp_http_client_init and before any perform function.
Return · ESP_OK · ESP_FAIL
Parameters · [in] client: The esp_http_client handle · [in] key: The header key · [in] value: The header value
esp_err_t esp_http_client_get_header(esp_http_client_handle_t client, const char *key, char **value)
Get http request header. The value parameter will be set to NULL if there is no header which is same as the key specified, otherwise the address of header value will be assigned to value parameter. This function must be called after esp_http_client_init.
Return · ESP_OK · ESP_FAIL
Parameters · [in] client: The esp_http_client handle · [in] key: The header key · [out] value: The header value
esp_err_t esp_http_client_get_username(esp_http_client_handle_t client, char **value) Get http request username. The address of username buffer will be assigned to value parameter. This function must be called after esp_http_client_init.
Return · ESP_OK · ESP_ERR_INVALID_ARG
Parameters · [in] client: The esp_http_client handle · [out] value: The username value
esp_err_t esp_http_client_set_username(esp_http_client_handle_t client, const char *username)
Set http request username. The value of username parameter will be assigned to username buffer. If the username parameter is NULL then username buffer will be freed.
Return · ESP_OK · ESP_ERR_INVALID_ARG
Parameters · [in] client: The esp_http_client handle · [in] username: The username value
esp_err_t esp_http_client_get_password(esp_http_client_handle_t client, char **value) Get http request password. The address of password buffer will be assigned to value parameter. This function must be called after esp_http_client_init.
Return · ESP_OK · ESP_ERR_INVALID_ARG
Parameters · [in] client: The esp_http_client handle · [out] value: The password value
esp_err_t esp_http_client_set_password(esp_http_client_handle_t client, const char *password)
Set http request password. The value of password parameter will be assigned to password buffer. If the password parameter is NULL then password buffer will be freed.

Espressif Systems

855

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return · ESP_OK · ESP_ERR_INVALID_ARG
Parameters · [in] client: The esp_http_client handle · [in] password: The password value

esp_err_t esp_http_client_set_authtype(esp_http_client_handle_t

Set http request auth_type.

esp_http_client_auth_type_t auth_type)

client,

Return · ESP_OK · ESP_ERR_INVALID_ARG
Parameters · [in] client: The esp_http_client handle · [in] auth_type: The esp_http_client auth type

int esp_http_client_get_errno(esp_http_client_handle_t client) Get HTTP client session errno.

Return · (-1) if invalid argument · errno
Parameters · [in] client: The esp_http_client handle

esp_err_t esp_http_client_set_method(esp_http_client_handle_t client, esp_http_client_method_t

Set http request method.

method)

Return · ESP_OK · ESP_ERR_INVALID_ARG
Parameters · [in] client: The esp_http_client handle · [in] method: The method

esp_err_t esp_http_client_set_timeout_ms(esp_http_client_handle_t client, int timeout_ms) Set http request timeout.

Return · ESP_OK · ESP_ERR_INVALID_ARG
Parameters · [in] client: The esp_http_client handle · [in] timeout_ms: The timeout value

esp_err_t esp_http_client_delete_header(esp_http_client_handle_t client, const char *key) Delete http request header.

Return · ESP_OK · ESP_FAIL
Parameters · [in] client: The esp_http_client handle · [in] key: The key

esp_err_t esp_http_client_open(esp_http_client_handle_t client, int write_len) This function will be open the connection, write all header strings and return.

Return · ESP_OK · ESP_FAIL

Espressif Systems

856

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Parameters · [in] client: The esp_http_client handle · [in] write_len: HTTP Content length need to write to the server
int esp_http_client_write(esp_http_client_handle_t client, const char *buffer, int len) This function will write data to the HTTP connection previously opened by esp_http_client_open()
Return · (-1) if any errors · Length of data written
Parameters · [in] client: The esp_http_client handle · buffer: The buffer · [in] len: This value must not be larger than the write_len parameter provided to esp_http_client_open()
int64_t esp_http_client_fetch_headers(esp_http_client_handle_t client) This function need to call after esp_http_client_open, it will read from http stream, process all receive headers.
Return · (0) if stream doesnnt contain content-length header, or chunked encoding (checked by esp_http_client_is_chunked response) · (-1: ESP_FAIL) if any errors · Download data length defined by content-length header
Parameters · [in] client: The esp_http_client handle
bool esp_http_client_is_chunked_response(esp_http_client_handle_t client) Check response data is chunked.
Return true or false Parameters
· [in] client: The esp_http_client handle
int esp_http_client_read(esp_http_client_handle_t client, char *buffer, int len) Read data from http stream.
Return · (-1) if any errors · Length of data was read
Parameters · [in] client: The esp_http_client handle · buffer: The buffer · [in] len: The length
int esp_http_client_get_status_code(esp_http_client_handle_t client) Get http response status code, the valid value if this function invoke after esp_http_client_perform
Return Status code Parameters
· [in] client: The esp_http_client handle
int64_t esp_http_client_get_content_length(esp_http_client_handle_t client) Get http response content length (from header Content-Length) the valid value if this function invoke after esp_http_client_perform
Return · (-1) Chunked transfer · Content-Length value as bytes
Parameters · [in] client: The esp_http_client handle
esp_err_t esp_http_client_close(esp_http_client_handle_t client) Close http connection, still kept all http request resources.

Espressif Systems

857

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return · ESP_OK · ESP_FAIL
Parameters · [in] client: The esp_http_client handle

esp_err_t esp_http_client_cleanup(esp_http_client_handle_t client) This function must be the last function to call for an session. It is the opposite of the esp_http_client_init function and must be called with the same handle as input that a esp_http_client_init call returned. This might close all connections this handle has used and possibly has kept open until now. Donnt call this function if you intend to transfer more files, re-using handles is a key to good performance with esp_http_client.

Return · ESP_OK · ESP_FAIL
Parameters · [in] client: The esp_http_client handle

esp_http_client_transport_t esp_http_client_get_transport_type(esp_http_client_handle_t

Get transport type.

client)

Return · HTTP_TRANSPORT_UNKNOWN · HTTP_TRANSPORT_OVER_TCP · HTTP_TRANSPORT_OVER_SSL
Parameters · [in] client: The esp_http_client handle

esp_err_t esp_http_client_set_redirection(esp_http_client_handle_t client) Set redirection URL. When received the 30x code from the server, the client stores the redirect URL provided by the server. This function will set the current URL to redirect to enable client to execute the redirection request.

Return · ESP_OK · ESP_FAIL
Parameters · [in] client: The esp_http_client handle

void esp_http_client_add_auth(esp_http_client_handle_t client) On receiving HTTP Status code 401, this API can be invoked to add authorization information.

Note There is a possibility of receiving body message with redirection status codes, thus make sure to flush off body data after calling this API.
Parameters · [in] client: The esp_http_client handle

bool esp_http_client_is_complete_data_received(esp_http_client_handle_t client) Checks if entire data in the response has been read without any error.

Return · true · false
Parameters · [in] client: The esp_http_client handle

int esp_http_client_read_response(esp_http_client_handle_t client, char *buffer, int len) Helper API to read larger data chunks This is a helper API which internally calls esp_http_client_read multiple times till the end of data is reached or till the buffer gets full.

Return · Length of data was read
Parameters

Espressif Systems

858

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· [in] client: The esp_http_client handle · buffer: The buffer · [in] len: The buffer length
esp_err_t esp_http_client_flush_response(esp_http_client_handle_t client, int *len) Process all remaining response data This uses an internal buffer to repeatedly receive, parse, and discard response data until complete data is processed. As no additional user-supplied buffer is required, this may be preferrable to esp_http_client_read_response in situations where the content of the response may be ignored.
Return · ESP_OK If successful, len will have discarded length · ESP_FAIL If failed to read response · ESP_ERR_INVALID_ARG If the client is NULL
Parameters · [in] client: The esp_http_client handle · len: Length of data discarded
esp_err_t esp_http_client_get_url(esp_http_client_handle_t client, char *url, const int len) Get URL from client.
Return · ESP_OK · ESP_FAIL
Parameters · [in] client: The esp_http_client handle · [inout] url: The buffer to store URL · [in] len: The buffer length
esp_err_t esp_http_client_get_chunk_length(esp_http_client_handle_t client, int *len) Get Chunk-Length from client.
Return · ESP_OK If successful, len will have length of current chunk · ESP_FAIL If the server is not a chunked server · ESP_ERR_INVALID_ARG If the client or len are NULL
Parameters · [in] client: The esp_http_client handle · [out] len: Variable to store length
Structures struct esp_http_client_event
HTTP Client events data.
Public Members
esp_http_client_event_id_t event_id event_id, to know the cause of the event
esp_http_client_handle_t client esp_http_client_handle_t context
void *data data of the event
int data_len data length of data
void *user_data user_data context, from esp_http_client_config_t user_data

Espressif Systems

859

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
char *header_key For HTTP_EVENT_ON_HEADER event_id, itns store current http header key
char *header_value For HTTP_EVENT_ON_HEADER event_id, itns store current http header value
struct esp_http_client_config_t HTTP configuration.
Public Members
const char *url HTTP URL, the information on the URL is most important, it overrides the other fields below, if any
const char *host Domain or IP as string
int port Port to connect, default depend on esp_http_client_transport_t (80 or 443)
const char *username Using for Http authentication
const char *password Using for Http authentication
esp_http_client_auth_type_t auth_type Http authentication type, see esp_http_client_auth_type_t
const char *path HTTP Path, if not set, default is /
const char *query HTTP query
const char *cert_pem SSL server certification, PEM format as string, if the client requires to verify server
size_t cert_len Length of the buffer pointed to by cert_pem. May be 0 for null-terminated pem
const char *client_cert_pem SSL client certification, PEM format as string, if the server requires to verify client
size_t client_cert_len Length of the buffer pointed to by client_cert_pem. May be 0 for null-terminated pem
const char *client_key_pem SSL client key, PEM format as string, if the server requires to verify client
size_t client_key_len Length of the buffer pointed to by client_key_pem. May be 0 for null-terminated pem
const char *client_key_password Client key decryption password string
size_t client_key_password_len String length of the password pointed to by client_key_password
const char *user_agent The User Agent string to send with HTTP requests
esp_http_client_method_t method HTTP Method
int timeout_ms Network timeout in milliseconds

Espressif Systems

860

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
bool disable_auto_redirect Disable HTTP automatic redirects
int max_redirection_count Max number of redirections on receiving HTTP redirect status code, using default value if zero
int max_authorization_retries Max connection retries on receiving HTTP unauthorized status code, using default value if zero. Disables authorization retry if -1
http_event_handle_cb event_handler HTTP Event Handle
esp_http_client_transport_t transport_type HTTP transport type, see esp_http_client_transport_t
int buffer_size HTTP receive buffer size
int buffer_size_tx HTTP transmit buffer size
void *user_data HTTP user_data context
bool is_async Set asynchronous mode, only supported with HTTPS for now
bool use_global_ca_store Use a global ca_store for all the connections in which this bool is set.
bool skip_cert_common_name_check Skip any validation of server certificate CN field
esp_err_t (*crt_bundle_attach)(void *conf) Function pointer to esp_crt_bundle_attach. Enables the use of certification bundle for server verification, must be enabled in menuconfig
bool keep_alive_enable Enable keep-alive timeout
int keep_alive_idle Keep-alive idle time. Default is 5 (second)
int keep_alive_interval Keep-alive interval time. Default is 5 (second)
int keep_alive_count Keep-alive packet retry send count. Default is 3 counts
struct ifreq *if_name The name of interface for data to go through. Use the default interface without setting
Macros DEFAULT_HTTP_BUF_SIZE ESP_ERR_HTTP_BASE
Starting number of HTTP error codes
ESP_ERR_HTTP_MAX_REDIRECT The error exceeds the number of HTTP redirects
ESP_ERR_HTTP_CONNECT Error open the HTTP connection
ESP_ERR_HTTP_WRITE_DATA Error write HTTP data

Espressif Systems

861

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_ERR_HTTP_FETCH_HEADER Error read HTTP header from server
ESP_ERR_HTTP_INVALID_TRANSPORT There are no transport support for the input scheme
ESP_ERR_HTTP_CONNECTING HTTP connection hasnnt been established yet
ESP_ERR_HTTP_EAGAIN Mapping of errno EAGAIN to esp_err_t
ESP_ERR_HTTP_CONNECTION_CLOSED Read FIN from peer and the connection closed
Type Definitions typedef struct esp_http_client *esp_http_client_handle_t typedef struct esp_http_client_event *esp_http_client_event_handle_t
typedef struct esp_http_client_event esp_http_client_event_t HTTP Client events data.
typedef esp_err_t (*http_event_handle_cb)(esp_http_client_event_t *evt)
Enumerations enum esp_http_client_event_id_t
HTTP Client events id.
Values:
HTTP_EVENT_ERROR = 0 This event occurs when there are any errors during execution
HTTP_EVENT_ON_CONNECTED Once the HTTP has been connected to the server, no data exchange has been performed
HTTP_EVENT_HEADERS_SENT After sending all the headers to the server
HTTP_EVENT_HEADER_SENT = HTTP_EVENT_HEADERS_SENT This header has been kept for backward compatability and will be deprecated in future versions esp-idf
HTTP_EVENT_ON_HEADER Occurs when receiving each header sent from the server
HTTP_EVENT_ON_DATA Occurs when receiving data from the server, possibly multiple portions of the packet
HTTP_EVENT_ON_FINISH Occurs when finish a HTTP session
HTTP_EVENT_DISCONNECTED The connection has been disconnected
HTTP_EVENT_REDIRECT Intercepting HTTP redirects to handle them manually
enum esp_http_client_transport_t HTTP Client transport.
Values:
HTTP_TRANSPORT_UNKNOWN = 0x0 Unknown
HTTP_TRANSPORT_OVER_TCP Transport over tcp

Espressif Systems

862

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
HTTP_TRANSPORT_OVER_SSL Transport over ssl
enum esp_http_client_method_t HTTP method.
Values:
HTTP_METHOD_GET = 0 HTTP GET Method
HTTP_METHOD_POST HTTP POST Method
HTTP_METHOD_PUT HTTP PUT Method
HTTP_METHOD_PATCH HTTP PATCH Method
HTTP_METHOD_DELETE HTTP DELETE Method
HTTP_METHOD_HEAD HTTP HEAD Method
HTTP_METHOD_NOTIFY HTTP NOTIFY Method
HTTP_METHOD_SUBSCRIBE HTTP SUBSCRIBE Method
HTTP_METHOD_UNSUBSCRIBE HTTP UNSUBSCRIBE Method
HTTP_METHOD_OPTIONS HTTP OPTIONS Method
HTTP_METHOD_COPY HTTP COPY Method
HTTP_METHOD_MOVE HTTP MOVE Method
HTTP_METHOD_LOCK HTTP LOCK Method
HTTP_METHOD_UNLOCK HTTP UNLOCK Method
HTTP_METHOD_PROPFIND HTTP PROPFIND Method
HTTP_METHOD_PROPPATCH HTTP PROPPATCH Method
HTTP_METHOD_MKCOL HTTP MKCOL Method
HTTP_METHOD_MAX
enum esp_http_client_auth_type_t HTTP Authentication type.
Values:
HTTP_AUTH_TYPE_NONE = 0 No authention

Espressif Systems

863

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

HTTP_AUTH_TYPE_BASIC HTTP Basic authentication
HTTP_AUTH_TYPE_DIGEST HTTP Disgest authentication
enum HttpStatus_Code Enum for the HTTP status codes. Values: HttpStatus_Ok = 200 HttpStatus_MultipleChoices = 300 HttpStatus_MovedPermanently = 301 HttpStatus_Found = 302 HttpStatus_TemporaryRedirect = 307 HttpStatus_BadRequest = 400 HttpStatus_Unauthorized = 401 HttpStatus_Forbidden = 403 HttpStatus_NotFound = 404 HttpStatus_InternalError = 500

2.4.6 HTTP Server
Overview
The HTTP Server component provides an ability for running a lightweight web server on ESP32-S3. Following are detailed steps to use the API exposed by HTTP Server:
· httpd_start(): Creates an instance of HTTP server, allocate memory/resources for it depending upon the specified configuration and outputs a handle to the server instance. The server has both, a listening socket (TCP) for HTTP traffic, and a control socket (UDP) for control signals, which are selected in a round robin fashion in the server task loop. The task priority and stack size are configurable during server instance creation by passing httpd_config_t structure to httpd_start(). TCP traffic is parsed as HTTP requests and, depending on the requested URI, user registered handlers are invoked which are supposed to send back HTTP response packets.
· httpd_stop(): This stops the server with the provided handle and frees up any associated memory/resources. This is a blocking function that first signals a halt to the server task and then waits for the task to terminate. While stopping, the task will close all open connections, remove registered URI handlers and reset all session context data to empty.
· httpd_register_uri_handler(): A URI handler is registered by passing object of type httpd_uri_t structure which has members including uri name, method type (eg. HTTPD_GET/ HTTPD_POST/HTTPD_PUT etc.), function pointer of type esp_err_t *handler (httpd_req_t *req) and user_ctx pointer to user context data.

Application Example
/* Our URI handler function to be called during GET /uri request */ esp_err_t get_handler(httpd_req_t *req) {
/* Send a simple response */ const char resp[] = "URI GET Response"; httpd_resp_send(req, resp, HTTPD_RESP_USE_STRLEN); return ESP_OK;
(continues on next page)

Espressif Systems

864

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page) }

/* Our URI handler function to be called during POST /uri request */ esp_err_t post_handler(httpd_req_t *req) {
/* Destination buffer for content of HTTP POST request. * httpd_req_recv() accepts char* only, but content could * as well be any binary data (needs type casting). * In case of string data, null termination will be absent, and * content length would give length of string */
char content[100];

/* Truncate if content length larger than the buffer */ size_t recv_size = MIN(req->content_len, sizeof(content));

int ret = httpd_req_recv(req, content, recv_size); if (ret <= 0) { /* 0 return value indicates connection closed */
/* Check if timeout occurred */ if (ret == HTTPD_SOCK_ERR_TIMEOUT) {
/* In case of timeout one can choose to retry calling * httpd_req_recv(), but to keep it simple, here we * respond with an HTTP 408 (Request Timeout) error */
httpd_resp_send_408(req); } /* In case of error, returning ESP_FAIL will
* ensure that the underlying socket is closed */ return ESP_FAIL; }

/* Send a simple response */ const char resp[] = "URI POST Response"; httpd_resp_send(req, resp, HTTPD_RESP_USE_STRLEN); return ESP_OK; }

/* URI handler structure for GET /uri */

httpd_uri_t uri_get = {

.uri

= "/uri",

.method = HTTP_GET,

.handler = get_handler,

.user_ctx = NULL

};

/* URI handler structure for POST /uri */

httpd_uri_t uri_post = {

.uri

= "/uri",

.method = HTTP_POST,

.handler = post_handler,

.user_ctx = NULL

};

/* Function for starting the webserver */ httpd_handle_t start_webserver(void) {
/* Generate default configuration */ httpd_config_t config = HTTPD_DEFAULT_CONFIG();

/* Empty handle to esp_http_server */ httpd_handle_t server = NULL;

/* Start the httpd server */

(continues on next page)

Espressif Systems

865

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)
if (httpd_start(&server, &config) == ESP_OK) { /* Register URI handlers */ httpd_register_uri_handler(server, &uri_get); httpd_register_uri_handler(server, &uri_post);
} /* If server failed to start, handle will be NULL */ return server; }
/* Function for stopping the webserver */ void stop_webserver(httpd_handle_t server) {
if (server) { /* Stop the httpd server */ httpd_stop(server);
} }

Simple HTTP server example Check HTTP server example under protocols/http_server/simple where handling of arbitrary content lengths, reading request headers and URL query parameters, and setting response headers is demonstrated.

Persistent Connections
HTTP server features persistent connections, allowing for the re-use of the same connection (session) for several transfers, all the while maintaining context specific data for the session. Context data may be allocated dynamically by the handler in which case a custom function may need to be specified for freeing this data when the connection/session is closed.

Persistent Connections Example
/* Custom function to free context */ void free_ctx_func(void *ctx) {
/* Could be something other than free */ free(ctx); }

esp_err_t adder_post_handler(httpd_req_t *req)

{

/* Create session's context if not already available */

if (! req->sess_ctx) {

req->sess_ctx = malloc(sizeof(ANY_DATA_TYPE)); /*!< Pointer to context

data */

req->free_ctx = free_ctx_func;

/*!< Function to free

context data */

}

/* Access context data */ ANY_DATA_TYPE *ctx_data = (ANY_DATA_TYPE *)req->sess_ctx;

/* Respond */ ............... ............... ...............

return ESP_OK; }

Espressif Systems

866

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Check the example under protocols/http_server/persistent_sockets.

Websocket server
HTTP server provides a simple websocket support if the feature is enabled in menuconfig, please see CONFIG_HTTPD_WS_SUPPORT. Please check the example under protocols/http_server/ws_echo_server

API Reference
Header File · components/esp_http_server/include/esp_http_server.h

Functions esp_err_t httpd_register_uri_handler(httpd_handle_t handle, const httpd_uri_t *uri_handler)
Registers a URI handler.
Example usage:
esp_err_t my_uri_handler(httpd_req_t* req) {
// Recv , Process and Send .... .... ....

// Fail condition if (....) {
// Return fail to close session // return ESP_FAIL; }

// On success return ESP_OK; }

// URI handler structure

httpd_uri_t my_uri {

.uri

= "/my_uri/path/xyz",

.method = HTTPD_GET,

.handler = my_uri_handler,

.user_ctx = NULL

};

// Register handler if (httpd_register_uri_handler(server_handle, &my_uri) != ESP_OK) {
// If failed to register handler .... }

Note URI handlers can be registered in real time as long as the server handle is valid.
Return · ESP_OK : On successfully registering the handler · ESP_ERR_INVALID_ARG : Null arguments · ESP_ERR_HTTPD_HANDLERS_FULL : If no slots left for new handler · ESP_ERR_HTTPD_HANDLER_EXISTS : If handler with same URI and method is already registered
Parameters · [in] handle: handle to HTTPD server instance

Espressif Systems

867

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· [in] uri_handler: pointer to handler that needs to be registered esp_err_t httpd_unregister_uri_handler(httpd_handle_t handle, const char *uri,
httpd_method_t method) Unregister a URI handler.

Return · ESP_OK : On successfully deregistering the handler · ESP_ERR_INVALID_ARG : Null arguments · ESP_ERR_NOT_FOUND : Handler with specified URI and method not found
Parameters · [in] handle: handle to HTTPD server instance · [in] uri: URI string · [in] method: HTTP method

esp_err_t httpd_unregister_uri(httpd_handle_t handle, const char *uri) Unregister all URI handlers with the specified uri string.

Return · ESP_OK : On successfully deregistering all such handlers · ESP_ERR_INVALID_ARG : Null arguments · ESP_ERR_NOT_FOUND : No handler registered with specified uri string
Parameters · [in] handle: handle to HTTPD server instance · [in] uri: uri string specifying all handlers that need to be deregisterd

esp_err_t httpd_sess_set_recv_override(httpd_handle_t hd, int sockfd, httpd_recv_func_t
recv_func) Override web serverns receive function (by session FD)

This function overrides the web serverns receive function. This same function is used to read HTTP request packets.

Note This API is supposed to be called either from the context of · an http session APIs where sockfd is a valid parameter · a URI handler where sockfd is obtained using httpd_req_to_sockfd()
Return · ESP_OK : On successfully registering override · ESP_ERR_INVALID_ARG : Null arguments
Parameters · [in] hd: HTTPD instance handle · [in] sockfd: Session socket FD · [in] recv_func: The receive function to be set for this session

esp_err_t httpd_sess_set_send_override(httpd_handle_t hd, int sockfd, httpd_send_func_t
send_func) Override web serverns send function (by session FD)

This function overrides the web serverns send function. This same function is used to send out any response to any HTTP request.

Note This API is supposed to be called either from the context of · an http session APIs where sockfd is a valid parameter · a URI handler where sockfd is obtained using httpd_req_to_sockfd()
Return · ESP_OK : On successfully registering override · ESP_ERR_INVALID_ARG : Null arguments
Parameters · [in] hd: HTTPD instance handle · [in] sockfd: Session socket FD · [in] send_func: The send function to be set for this session

esp_err_t httpd_sess_set_pending_override(httpd_handle_t

hd,

int

httpd_pending_func_t pending_func)

Override web serverns pending function (by session FD)

sockfd,

Espressif Systems

868

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

This function overrides the web serverns pending function. This function is used to test for pending bytes in a socket.
Note This API is supposed to be called either from the context of · an http session APIs where sockfd is a valid parameter · a URI handler where sockfd is obtained using httpd_req_to_sockfd()
Return · ESP_OK : On successfully registering override · ESP_ERR_INVALID_ARG : Null arguments
Parameters · [in] hd: HTTPD instance handle · [in] sockfd: Session socket FD · [in] pending_func: The receive function to be set for this session
int httpd_req_to_sockfd(httpd_req_t *r) Get the Socket Descriptor from the HTTP request.
This API will return the socket descriptor of the session for which URI handler was executed on reception of HTTP request. This is useful when user wants to call functions that require session socket fd, from within a URI handler, ie. : httpd_sess_get_ctx(), httpd_sess_trigger_close(), httpd_sess_update_lru_counter().
Note This API is supposed to be called only from the context of a URI handler where httpd_req_t* request pointer is valid.
Return · Socket descriptor : The socket descriptor for this request · -1 : Invalid/NULL request pointer
Parameters · [in] r: The request whose socket descriptor should be found
int httpd_req_recv(httpd_req_t *r, char *buf, size_t buf_len) API to read content data from the HTTP request.
This API will read HTTP content data from the HTTP request into provided buffer. Use content_len provided in httpd_req_t structure to know the length of data to be fetched. If content_len is too large for the buffer then user may have to make multiple calls to this function, each time fetching mbuf_lennnumber of bytes, while the pointer to content data is incremented internally by the same number.
Note · This API is supposed to be called only from the context of a URI handler where httpd_req_t* request pointer is valid. · If an error is returned, the URI handler must further return an error. This will ensure that the erroneous socket is closed and cleaned up by the web server. · Presently Chunked Encoding is not supported
Return · Bytes : Number of bytes read into the buffer successfully · 0 : Buffer length parameter is zero / connection closed by peer · HTTPD_SOCK_ERR_INVALID : Invalid arguments · HTTPD_SOCK_ERR_TIMEOUT : Timeout/interrupted while calling socket recv() · HTTPD_SOCK_ERR_FAIL : Unrecoverable error while calling socket recv()
Parameters · [in] r: The request being responded to · [in] buf: Pointer to a buffer that the data will be read into · [in] buf_len: Length of the buffer
size_t httpd_req_get_hdr_value_len(httpd_req_t *r, const char *field) Search for a field in request headers and return the string length of itns value.
Note · This API is supposed to be called only from the context of a URI handler where httpd_req_t* request pointer is valid. · Once httpd_resp_send() API is called all request headers are purged, so request headers need be copied into separate buffers if they are required later.
Return

Espressif Systems

869

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· Length : If field is found in the request URL · Zero : Field not found / Invalid request / Null arguments Parameters · [in] r: The request being responded to · [in] field: The header field to be searched in the request
esp_err_t httpd_req_get_hdr_value_str(httpd_req_t *r, const char *field, char *val, size_t val_size)
Get the value string of a field from the request headers.
Note · This API is supposed to be called only from the context of a URI handler where httpd_req_t* request pointer is valid. · Once httpd_resp_send() API is called all request headers are purged, so request headers need be copied into separate buffers if they are required later. · If output size is greater than input, then the value is truncated, accompanied by truncation error as return value. · Use httpd_req_get_hdr_value_len() to know the right buffer length
Return · ESP_OK : Field found in the request header and value string copied · ESP_ERR_NOT_FOUND : Key not found · ESP_ERR_INVALID_ARG : Null arguments · ESP_ERR_HTTPD_INVALID_REQ : Invalid HTTP request pointer · ESP_ERR_HTTPD_RESULT_TRUNC : Value string truncated
Parameters · [in] r: The request being responded to · [in] field: The field to be searched in the header · [out] val: Pointer to the buffer into which the value will be copied if the field is found · [in] val_size: Size of the user buffer ovalp
size_t httpd_req_get_url_query_len(httpd_req_t *r) Get Query string length from the request URL.
Note This API is supposed to be called only from the context of a URI handler where httpd_req_t* request pointer is valid
Return · Length : Query is found in the request URL · Zero : Query not found / Null arguments / Invalid request
Parameters · [in] r: The request being responded to
esp_err_t httpd_req_get_url_query_str(httpd_req_t *r, char *buf, size_t buf_len) Get Query string from the request URL.
Note · Presently, the user can fetch the full URL query string, but decoding will have to be performed by the user. Request headers can be read using httpd_req_get_hdr_value_str() to know the mContentTypen(eg. Content-Type: application/x-www-form-urlencoded) and then the appropriate decoding algorithm needs to be applied. · This API is supposed to be called only from the context of a URI handler where httpd_req_t* request pointer is valid · If output size is greater than input, then the value is truncated, accompanied by truncation error as return value · Prior to calling this function, one can use httpd_req_get_url_query_len() to know the query string length beforehand and hence allocate the buffer of right size (usually query string length + 1 for null termination) for storing the query string
Return · ESP_OK : Query is found in the request URL and copied to buffer · ESP_ERR_NOT_FOUND : Query not found · ESP_ERR_INVALID_ARG : Null arguments · ESP_ERR_HTTPD_INVALID_REQ : Invalid HTTP request pointer

Espressif Systems

870

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· ESP_ERR_HTTPD_RESULT_TRUNC : Query string truncated Parameters
· [in] r: The request being responded to · [out] buf: Pointer to the buffer into which the query string will be copied (if found) · [in] buf_len: Length of output buffer
esp_err_t httpd_query_key_value(const char *qry, const char *key, char *val, size_t val_size) Helper function to get a URL query tag from a query string of the type param1=val1&param2=val2.
Note · The components of URL query string (keys and values) are not URLdecoded. The user must check for mContent-Typenfield in the request headers and then depending upon the specified encoding (URLencoded or otherwise) apply the appropriate decoding algorithm. · If actual value size is greater than val_size, then the value is truncated, accompanied by truncation error as return value.
Return · ESP_OK : Key is found in the URL query string and copied to buffer · ESP_ERR_NOT_FOUND : Key not found · ESP_ERR_INVALID_ARG : Null arguments · ESP_ERR_HTTPD_RESULT_TRUNC : Value string truncated
Parameters · [in] qry: Pointer to query string · [in] key: The key to be searched in the query string · [out] val: Pointer to the buffer into which the value will be copied if the key is found · [in] val_size: Size of the user buffer ovalp
esp_err_t httpd_req_get_cookie_val(httpd_req_t *req, const char *cookie_name, char *val, size_t *val_size)
Get the value string of a cookie value from the oCookieprequest headers by cookie name.
Return · ESP_OK : Key is found in the cookie string and copied to buffer · ESP_ERR_NOT_FOUND : Key not found · ESP_ERR_INVALID_ARG : Null arguments · ESP_ERR_HTTPD_RESULT_TRUNC : Value string truncated · ESP_ERR_NO_MEM : Memory allocation failure
Parameters · [in] req: Pointer to the HTTP request · [in] cookie_name: The cookie name to be searched in the request · [out] val: Pointer to the buffer into which the value of cookie will be copied if the cookie is found · [inout] val_size: Pointer to size of the user buffer ovalp. This variable will contain cookie length if ESP_OK is returned and required buffer length incase ESP_ERR_HTTPD_RESULT_TRUNC is returned.
bool httpd_uri_match_wildcard(const char *uri_template, const char *uri_to_match, size_t match_upto)
Test if a URI matches the given wildcard template.
Template may end with o?pto make the previous character optional (typically a slash), o*pfor a wildcard match, and o?*pto make the previous character optional, and if present, allow anything to follow.
Example:
· * matches everything · /foo/? matches /foo and /foo/ · /foo/* (sans the backslash) matches /foo/ and /foo/bar, but not /foo or /fo · /foo/?* or /foo/*? (sans the backslash) matches /foo/, /foo/bar, and also /foo, but not /foox or /fo
The special characters o?pand o*panywhere else in the template will be taken literally.
Return true if a match was found Parameters

Espressif Systems

871

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· [in] uri_template: URI template (pattern) · [in] uri_to_match: URI to be matched · [in] match_upto: how many characters of the URI buffer to test (there may be trailing query
string etc.)
esp_err_t httpd_resp_send(httpd_req_t *r, const char *buf, ssize_t buf_len) API to send a complete HTTP response.
This API will send the data as an HTTP response to the request. This assumes that you have the entire response ready in a single buffer. If you wish to send response in incremental chunks use httpd_resp_send_chunk() instead.
If no status code and content-type were set, by default this will send 200 OK status code and content type as text/html. You may call the following functions before this API to configure the response headers : httpd_resp_set_status() - for setting the HTTP status string, httpd_resp_set_type() - for setting the Content Type, httpd_resp_set_hdr() - for appending any additional field value entries in the response header
Note · This API is supposed to be called only from the context of a URI handler where httpd_req_t* request pointer is valid. · Once this API is called, the request has been responded to. · No additional data can then be sent for the request. · Once this API is called, all request headers are purged, so request headers need be copied into separate buffers if they are required later.
Return · ESP_OK : On successfully sending the response packet · ESP_ERR_INVALID_ARG : Null request pointer · ESP_ERR_HTTPD_RESP_HDR : Essential headers are too large for internal buffer · ESP_ERR_HTTPD_RESP_SEND : Error in raw send · ESP_ERR_HTTPD_INVALID_REQ : Invalid request
Parameters · [in] r: The request being responded to · [in] buf: Buffer from where the content is to be fetched · [in] buf_len: Length of the buffer, HTTPD_RESP_USE_STRLEN to use strlen()
esp_err_t httpd_resp_send_chunk(httpd_req_t *r, const char *buf, ssize_t buf_len) API to send one HTTP chunk.
This API will send the data as an HTTP response to the request. This API will use chunked-encoding and send the response in the form of chunks. If you have the entire response contained in a single buffer, please use httpd_resp_send() instead.
If no status code and content-type were set, by default this will send 200 OK status code and content type as text/html. You may call the following functions before this API to configure the response headers httpd_resp_set_status() - for setting the HTTP status string, httpd_resp_set_type() - for setting the Content Type, httpd_resp_set_hdr() - for appending any additional field value entries in the response header
Note · This API is supposed to be called only from the context of a URI handler where httpd_req_t* request pointer is valid. · When you are finished sending all your chunks, you must call this function with buf_len as 0. · Once this API is called, all request headers are purged, so request headers need be copied into separate buffers if they are required later.
Return · ESP_OK : On successfully sending the response packet chunk · ESP_ERR_INVALID_ARG : Null request pointer · ESP_ERR_HTTPD_RESP_HDR : Essential headers are too large for internal buffer · ESP_ERR_HTTPD_RESP_SEND : Error in raw send · ESP_ERR_HTTPD_INVALID_REQ : Invalid request pointer
Parameters · [in] r: The request being responded to · [in] buf: Pointer to a buffer that stores the data

Espressif Systems

872

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· [in] buf_len: Length of the buffer, HTTPD_RESP_USE_STRLEN to use strlen()

static esp_err_t httpd_resp_sendstr(httpd_req_t *r, const char *str) API to send a complete string as HTTP response.

This API simply calls http_resp_send with buffer length set to string length assuming the buffer contains a null terminated string

Return · ESP_OK : On successfully sending the response packet · ESP_ERR_INVALID_ARG : Null request pointer · ESP_ERR_HTTPD_RESP_HDR : Essential headers are too large for internal buffer · ESP_ERR_HTTPD_RESP_SEND : Error in raw send · ESP_ERR_HTTPD_INVALID_REQ : Invalid request
Parameters · [in] r: The request being responded to · [in] str: String to be sent as response body

static esp_err_t httpd_resp_sendstr_chunk(httpd_req_t *r, const char *str) API to send a string as an HTTP response chunk.

This API simply calls http_resp_send_chunk with buffer length set to string length assuming the buffer contains a null terminated string

Return · ESP_OK : On successfully sending the response packet · ESP_ERR_INVALID_ARG : Null request pointer · ESP_ERR_HTTPD_RESP_HDR : Essential headers are too large for internal buffer · ESP_ERR_HTTPD_RESP_SEND : Error in raw send · ESP_ERR_HTTPD_INVALID_REQ : Invalid request
Parameters · [in] r: The request being responded to · [in] str: String to be sent as response body (NULL to finish response packet)

esp_err_t httpd_resp_set_status(httpd_req_t *r, const char *status) API to set the HTTP status code.

This API sets the status of the HTTP response to the value specified. By default, the m200 OKnresponse is sent as the response.

Note · This API is supposed to be called only from the context of a URI handler where httpd_req_t* request pointer is valid. · This API only sets the status to this value. The status isnnt sent out until any of the send APIs is executed. · Make sure that the lifetime of the status string is valid till send function is called.
Return · ESP_OK : On success · ESP_ERR_INVALID_ARG : Null arguments · ESP_ERR_HTTPD_INVALID_REQ : Invalid request pointer
Parameters · [in] r: The request being responded to · [in] status: The HTTP status code of this response

esp_err_t httpd_resp_set_type(httpd_req_t *r, const char *type) API to set the HTTP content type.

This API sets the mContent Typenfield of the response. The default content type is mtext/htmln.

Note

· This API is supposed to be called only from the context of a URI handler where httpd_req_t* request pointer is valid.
· This API only sets the content type to this value. The type isnnt sent out until any of the send APIs is executed.

Espressif Systems

873

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· Make sure that the lifetime of the type string is valid till send function is called. Return
· ESP_OK : On success · ESP_ERR_INVALID_ARG : Null arguments · ESP_ERR_HTTPD_INVALID_REQ : Invalid request pointer Parameters · [in] r: The request being responded to · [in] type: The Content Type of the response

esp_err_t httpd_resp_set_hdr(httpd_req_t *r, const char *field, const char *value) API to append any additional headers.

This API sets any additional header fields that need to be sent in the response.

Note · This API is supposed to be called only from the context of a URI handler where httpd_req_t* request pointer is valid. · The header isnnt sent out until any of the send APIs is executed. · The maximum allowed number of additional headers is limited to value of max_resp_headers in config structure. · Make sure that the lifetime of the field value strings are valid till send function is called.
Return · ESP_OK : On successfully appending new header · ESP_ERR_INVALID_ARG : Null arguments · ESP_ERR_HTTPD_RESP_HDR : Total additional headers exceed max allowed · ESP_ERR_HTTPD_INVALID_REQ : Invalid request pointer
Parameters · [in] r: The request being responded to · [in] field: The field name of the HTTP header · [in] value: The value of this HTTP header

esp_err_t httpd_resp_send_err(httpd_req_t *req, httpd_err_code_t error, const char *msg) For sending out error code in response to HTTP request.

Note · This API is supposed to be called only from the context of a URI handler where httpd_req_t* request pointer is valid. · Once this API is called, all request headers are purged, so request headers need be copied into separate buffers if they are required later. · If you wish to send additional data in the body of the response, please use the lower-level functions directly.
Return · ESP_OK : On successfully sending the response packet · ESP_ERR_INVALID_ARG : Null arguments · ESP_ERR_HTTPD_RESP_SEND : Error in raw send · ESP_ERR_HTTPD_INVALID_REQ : Invalid request pointer
Parameters · [in] req: Pointer to the HTTP request for which the response needs to be sent · [in] error: Error type to send · [in] msg: Error message string (pass NULL for default message)

static esp_err_t httpd_resp_send_404(httpd_req_t *r) Helper function for HTTP 404.

Send HTTP 404 message. If you wish to send additional data in the body of the response, please use the lower-level functions directly.

Note

· This API is supposed to be called only from the context of a URI handler where httpd_req_t* request pointer is valid.
· Once this API is called, all request headers are purged, so request headers need be copied into separate buffers if they are required later.

Espressif Systems

874

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return · ESP_OK : On successfully sending the response packet · ESP_ERR_INVALID_ARG : Null arguments · ESP_ERR_HTTPD_RESP_SEND : Error in raw send · ESP_ERR_HTTPD_INVALID_REQ : Invalid request pointer
Parameters · [in] r: The request being responded to
static esp_err_t httpd_resp_send_408(httpd_req_t *r) Helper function for HTTP 408.
Send HTTP 408 message. If you wish to send additional data in the body of the response, please use the lower-level functions directly.
Note · This API is supposed to be called only from the context of a URI handler where httpd_req_t* request pointer is valid. · Once this API is called, all request headers are purged, so request headers need be copied into separate buffers if they are required later.
Return · ESP_OK : On successfully sending the response packet · ESP_ERR_INVALID_ARG : Null arguments · ESP_ERR_HTTPD_RESP_SEND : Error in raw send · ESP_ERR_HTTPD_INVALID_REQ : Invalid request pointer
Parameters · [in] r: The request being responded to
static esp_err_t httpd_resp_send_500(httpd_req_t *r) Helper function for HTTP 500.
Send HTTP 500 message. If you wish to send additional data in the body of the response, please use the lower-level functions directly.
Note · This API is supposed to be called only from the context of a URI handler where httpd_req_t* request pointer is valid. · Once this API is called, all request headers are purged, so request headers need be copied into separate buffers if they are required later.
Return · ESP_OK : On successfully sending the response packet · ESP_ERR_INVALID_ARG : Null arguments · ESP_ERR_HTTPD_RESP_SEND : Error in raw send · ESP_ERR_HTTPD_INVALID_REQ : Invalid request pointer
Parameters · [in] r: The request being responded to
int httpd_send(httpd_req_t *r, const char *buf, size_t buf_len) Raw HTTP send.
Call this API if you wish to construct your custom response packet. When using this, all essential header, eg. HTTP version, Status Code, Content Type and Length, Encoding, etc. will have to be constructed manually, and HTTP delimeters (CRLF) will need to be placed correctly for separating sub-sections of the HTTP response packet.
If the send override function is set, this API will end up calling that function eventually to send data out.
Note · This API is supposed to be called only from the context of a URI handler where httpd_req_t* request pointer is valid. · Unless the response has the correct HTTP structure (which the user must now ensure) it is not guaranteed that it will be recognized by the client. For most cases, you wouldnnt have to call this API, but you would rather use either of : httpd_resp_send(), httpd_resp_send_chunk()
Return

Espressif Systems

875

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· Bytes : Number of bytes that were sent successfully · HTTPD_SOCK_ERR_INVALID : Invalid arguments · HTTPD_SOCK_ERR_TIMEOUT : Timeout/interrupted while calling socket send() · HTTPD_SOCK_ERR_FAIL : Unrecoverable error while calling socket send() Parameters · [in] r: The request being responded to · [in] buf: Buffer from where the fully constructed packet is to be read · [in] buf_len: Length of the buffer

int httpd_socket_send(httpd_handle_t hd, int sockfd, const char *buf, size_t buf_len, int flags) A low level API to send data on a given socket

This internally calls the default send function, or the function registered by httpd_sess_set_send_override().

Note This API is not recommended to be used in any request handler. Use this only for advanced use cases, wherein some asynchronous data is to be sent over a socket.

Return · Bytes : The number of bytes sent successfully · HTTPD_SOCK_ERR_INVALID : Invalid arguments · HTTPD_SOCK_ERR_TIMEOUT : Timeout/interrupted while calling socket send() · HTTPD_SOCK_ERR_FAIL : Unrecoverable error while calling socket send()
Parameters · [in] hd: server instance · [in] sockfd: session socket file descriptor · [in] buf: buffer with bytes to send · [in] buf_len: data size · [in] flags: flags for the send() function

int httpd_socket_recv(httpd_handle_t hd, int sockfd, char *buf, size_t buf_len, int flags) A low level API to receive data from a given socket

This internally calls the default recv function, or the function registered by httpd_sess_set_recv_override().

Note This API is not recommended to be used in any request handler. Use this only for advanced use cases, wherein some asynchronous communication is required.

Return · Bytes : The number of bytes received successfully · 0 : Buffer length parameter is zero / connection closed by peer · HTTPD_SOCK_ERR_INVALID : Invalid arguments · HTTPD_SOCK_ERR_TIMEOUT : Timeout/interrupted while calling socket recv() · HTTPD_SOCK_ERR_FAIL : Unrecoverable error while calling socket recv()
Parameters · [in] hd: server instance · [in] sockfd: session socket file descriptor · [in] buf: buffer with bytes to send · [in] buf_len: data size · [in] flags: flags for the send() function

esp_err_t httpd_register_err_handler(httpd_handle_t handle, httpd_err_code_t httpd_err_handler_func_t handler_fn)
Function for registering HTTP error handlers.

error,

This function maps a handler function to any supported error code given by httpd_err_code_t. See prototype httpd_err_handler_func_t above for details.

Return · ESP_OK : handler registered successfully · ESP_ERR_INVALID_ARG : invalid error code or server handle
Parameters · [in] handle: HTTP server handle · [in] error: Error type

Espressif Systems

876

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· [in] handler_fn: User implemented handler function (Pass NULL to unset any previously set handler)
esp_err_t httpd_start(httpd_handle_t *handle, const httpd_config_t *config) Starts the web server.
Create an instance of HTTP server and allocate memory/resources for it depending upon the specified configuration.
Example usage:
//Function for starting the webserver httpd_handle_t start_webserver(void) {
// Generate default configuration httpd_config_t config = HTTPD_DEFAULT_CONFIG();
// Empty handle to http_server httpd_handle_t server = NULL;
// Start the httpd server if (httpd_start(&server, &config) == ESP_OK) {
// Register URI handlers httpd_register_uri_handler(server, &uri_get); httpd_register_uri_handler(server, &uri_post); } // If server failed to start, handle will be NULL return server; }
Return · ESP_OK : Instance created successfully · ESP_ERR_INVALID_ARG : Null argument(s) · ESP_ERR_HTTPD_ALLOC_MEM : Failed to allocate memory for instance · ESP_ERR_HTTPD_TASK : Failed to launch server task
Parameters · [in] config: Configuration for new instance of the server · [out] handle: Handle to newly created instance of the server. NULL on error
esp_err_t httpd_stop(httpd_handle_t handle) Stops the web server.
Deallocates memory/resources used by an HTTP server instance and deletes it. Once deleted the handle can no longer be used for accessing the instance.
Example usage:
// Function for stopping the webserver void stop_webserver(httpd_handle_t server) {
// Ensure handle is non NULL if (server != NULL) {
// Stop the httpd server httpd_stop(server); } }
Return · ESP_OK : Server stopped successfully · ESP_ERR_INVALID_ARG : Handle argument is Null
Parameters · [in] handle: Handle to server returned by httpd_start

Espressif Systems

877

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t httpd_queue_work(httpd_handle_t handle, httpd_work_fn_t work, void *arg) Queue execution of a function in HTTPDns context.

This API queues a work function for asynchronous execution

Note Some protocols require that the web server generate some asynchronous data and send it to the persistently opened connection. This facility is for use by such protocols.
Return · ESP_OK : On successfully queueing the work · ESP_FAIL : Failure in ctrl socket · ESP_ERR_INVALID_ARG : Null arguments
Parameters · [in] handle: Handle to server returned by httpd_start · [in] work: Pointer to the function to be executed in the HTTPDns context · [in] arg: Pointer to the arguments that should be passed to this function

void *httpd_sess_get_ctx(httpd_handle_t handle, int sockfd) Get session context from socket descriptor.

Typically if a session context is created, it is available to URI handlers through the httpd_req_t structure. But, there are cases where the web serverns send/receive functions may require the context (for example, for accessing keying information etc). Since the send/receive function only have the socket descriptor at their disposal, this API provides them with a way to retrieve the session context.

Return · void* : Pointer to the context associated with this session · NULL : Empty context / Invalid handle / Invalid socket fd
Parameters · [in] handle: Handle to server returned by httpd_start · [in] sockfd: The socket descriptor for which the context should be extracted.

void httpd_sess_set_ctx(httpd_handle_t handle, int sockfd, void *ctx, httpd_free_ctx_fn_t free_fn) Set session context by socket descriptor.

Parameters · [in] handle: Handle to server returned by httpd_start · [in] sockfd: The socket descriptor for which the context should be extracted. · [in] ctx: Context object to assign to the session · [in] free_fn: Function that should be called to free the context

void *httpd_sess_get_transport_ctx(httpd_handle_t handle, int sockfd) Get session mtransportncontext by socket descriptor.

This context is used by the send/receive functions, for example to manage SSL context.

See httpd_sess_get_ctx()

Return · void* : Pointer to the transport context associated with this session · NULL : Empty context / Invalid handle / Invalid socket fd
Parameters · [in] handle: Handle to server returned by httpd_start · [in] sockfd: The socket descriptor for which the context should be extracted.

void httpd_sess_set_transport_ctx(httpd_handle_t handle, int sockfd,
httpd_free_ctx_fn_t free_fn) Set session mtransportncontext by socket descriptor.

void *ctx,

See httpd_sess_set_ctx() Parameters
· [in] handle: Handle to server returned by httpd_start · [in] sockfd: The socket descriptor for which the context should be extracted. · [in] ctx: Transport context object to assign to the session · [in] free_fn: Function that should be called to free the transport context

Espressif Systems

878

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
void *httpd_get_global_user_ctx(httpd_handle_t handle) Get HTTPD global user context (it was set in the server config struct)
Return global user context Parameters
· [in] handle: Handle to server returned by httpd_start
void *httpd_get_global_transport_ctx(httpd_handle_t handle) Get HTTPD global transport context (it was set in the server config struct)
Return global transport context Parameters
· [in] handle: Handle to server returned by httpd_start
esp_err_t httpd_sess_trigger_close(httpd_handle_t handle, int sockfd) Trigger an httpd session close externally.
Note Calling this API is only required in special circumstances wherein some application requires to close an httpd client session asynchronously.
Return · ESP_OK : On successfully initiating closure · ESP_FAIL : Failure to queue work · ESP_ERR_NOT_FOUND : Socket fd not found · ESP_ERR_INVALID_ARG : Null arguments
Parameters · [in] handle: Handle to server returned by httpd_start · [in] sockfd: The socket descriptor of the session to be closed
esp_err_t httpd_sess_update_lru_counter(httpd_handle_t handle, int sockfd) Update LRU counter for a given socket.
LRU Counters are internally associated with each session to monitor how recently a session exchanged traffic. When LRU purge is enabled, if a client is requesting for connection but maximum number of sockets/sessions is reached, then the session having the earliest LRU counter is closed automatically.
Updating the LRU counter manually prevents the socket from being purged due to the Least Recently Used (LRU) logic, even though it might not have received traffic for some time. This is useful when all open sockets/session are frequently exchanging traffic but the user specifically wants one of the sessions to be kept open, irrespective of when it last exchanged a packet.
Note Calling this API is only necessary if the LRU Purge Enable option is enabled. Return
· ESP_OK : Socket found and LRU counter updated · ESP_ERR_NOT_FOUND : Socket not found · ESP_ERR_INVALID_ARG : Null arguments Parameters · [in] handle: Handle to server returned by httpd_start · [in] sockfd: The socket descriptor of the session for which LRU counter is to be updated
esp_err_t httpd_get_client_list(httpd_handle_t handle, size_t *fds, int *client_fds) Returns list of current socket descriptors of active sessions.
Note Size of provided array has to be equal or greater then maximum number of opened sockets, configured upon initialization with max_open_sockets field in httpd_config_t structure.
Return · ESP_OK : Successfully retrieved session list · ESP_ERR_INVALID_ARG : Wrong arguments or list is longer than provided array
Parameters · [in] handle: Handle to server returned by httpd_start · [inout] fds: In: Size of provided client_fds array Out: Number of valid client fds returned in client_fds, · [out] client_fds: Array of client fds

Espressif Systems

879

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Structures struct httpd_config
HTTP Server Configuration Structure.
Note Use HTTPD_DEFAULT_CONFIG() to initialize the configuration to a default value and then modify only those fields that are specifically determined by the use case.
Public Members
unsigned task_priority Priority of FreeRTOS task which runs the server
size_t stack_size The maximum stack size allowed for the server task
BaseType_t core_id The core the HTTP server task will run on
uint16_t server_port TCP Port number for receiving and transmitting HTTP traffic
uint16_t ctrl_port UDP Port number for asynchronously exchanging control signals between various components of the server
uint16_t max_open_sockets Max number of sockets/clients connected at any time
uint16_t max_uri_handlers Maximum allowed uri handlers
uint16_t max_resp_headers Maximum allowed additional headers in HTTP response
uint16_t backlog_conn Number of backlog connections
bool lru_purge_enable Purge oLeast Recently Usedpconnection
uint16_t recv_wait_timeout Timeout for recv function (in seconds)
uint16_t send_wait_timeout Timeout for send function (in seconds)
void *global_user_ctx Global user context.
This field can be used to store arbitrary user data within the server context. The value can be retrieved using the server handle, available e.g. in the httpd_req_t struct.
When shutting down, the server frees up the user context by calling free() on the global_user_ctx field. If you wish to use a custom function for freeing the global user context, please specify that here.
httpd_free_ctx_fn_t global_user_ctx_free_fn Free function for global user context
void *global_transport_ctx Global transport context.
Similar to global_user_ctx, but used for session encoding or encryption (e.g. to hold the SSL context). It will be freed using free(), unless global_transport_ctx_free_fn is specified.
httpd_free_ctx_fn_t global_transport_ctx_free_fn Free function for global transport context

Espressif Systems

880

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
httpd_open_func_t open_fn Custom session opening callback.
Called on a new session socket just after accept(), but before reading any data.
This is an opportunity to set up e.g. SSL encryption using global_transport_ctx and the send/recv/pending session overrides.
If a context needs to be maintained between these functions, store it in the session using httpd_sess_set_transport_ctx() and retrieve it later with httpd_sess_get_transport_ctx()
Returning a value other than ESP_OK will immediately close the new socket.
httpd_close_func_t close_fn Custom session closing callback.
Called when a session is deleted, before freeing user and transport contexts and before closing the socket. This is a place for custom de-init code common to all sockets.
The server will only close the socket if no custom session closing callback is set. If a custom callback is used, close(sockfd) should be called in here for most cases.
Set the user or transport context to NULL if it was freed here, so the server does not try to free it again.
This function is run for all terminated sessions, including sessions where the socket was closed by the network stack - that is, the file descriptor may not be valid anymore.
httpd_uri_match_func_t uri_match_fn URI matcher function.
Called when searching for a matching URI: 1) whose request handler is to be executed right after an HTTP request is successfully parsed 2) in order to prevent duplication while registering a new URI handler using httpd_register_uri_handler()
Available options are: 1) NULL : Internally do basic matching using strncmp() 2) httpd_uri_match_wildcard() : URI wildcard matcher
Users can implement their own matching functions (See description of the httpd_uri_match_func_t function prototype) struct httpd_req HTTP Request Data Structure.
Public Members
httpd_handle_t handle Handle to server instance
int method The type of HTTP request, -1 if unsupported method
const char uri[HTTPD_MAX_URI_LEN + 1] The URI of this request (1 byte extra for null termination)
size_t content_len Length of the request body
void *aux Internally used members
void *user_ctx User context pointer passed during URI registration.
void *sess_ctx Session Context Pointer

Espressif Systems

881

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
A session context. Contexts are maintained across msessionsnfor a given open TCP connection. One session could have multiple request responses. The web server will ensure that the context persists across all these request and responses.
By default, this is NULL. URI Handlers can set this to any meaningful value.
If the underlying socket gets closed, and this pointer is non-NULL, the web server will free up the context by calling free(), unless free_ctx function is set.
httpd_free_ctx_fn_t free_ctx Pointer to free context hook
Function to free session context
If the web serverns socket closes, it frees up the session context by calling free() on the sess_ctx member. If you wish to use a custom function for freeing the session context, please specify that here.
bool ignore_sess_ctx_changes Flag indicating if Session Context changes should be ignored
By default, if you change the sess_ctx in some URI handler, the http server will internally free the earlier context (if non NULL), after the URI handler returns. If you want to manage the allocation/reallocation/freeing of sess_ctx yourself, set this flag to true, so that the server will not perform any checks on it. The context will be cleared by the server (by calling free_ctx or free()) only if the socket gets closed.
struct httpd_uri Structure for URI handler.
Public Members
const char *uri The URI to handle
httpd_method_t method Method supported by the URI
esp_err_t (*handler)(httpd_req_t *r) Handler to call for supported request method. This must return ESP_OK, or else the underlying socket will be closed.
void *user_ctx Pointer to user context data which will be available to handler
Macros HTTPD_MAX_REQ_HDR_LEN HTTPD_MAX_URI_LEN
HTTPD_SOCK_ERR_FAIL
HTTPD_SOCK_ERR_INVALID
HTTPD_SOCK_ERR_TIMEOUT
HTTPD_200 HTTP Response 200
HTTPD_204 HTTP Response 204
HTTPD_207 HTTP Response 207
HTTPD_400 HTTP Response 400

Espressif Systems

882

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

HTTPD_404 HTTP Response 404
HTTPD_408 HTTP Response 408
HTTPD_500 HTTP Response 500
HTTPD_TYPE_JSON HTTP Content type JSON
HTTPD_TYPE_TEXT HTTP Content type text/HTML
HTTPD_TYPE_OCTET HTTP Content type octext-stream
HTTPD_DEFAULT_CONFIG()
ESP_ERR_HTTPD_BASE Starting number of HTTPD error codes
ESP_ERR_HTTPD_HANDLERS_FULL All slots for registering URI handlers have been consumed
ESP_ERR_HTTPD_HANDLER_EXISTS URI handler with same method and target URI already registered
ESP_ERR_HTTPD_INVALID_REQ Invalid request pointer
ESP_ERR_HTTPD_RESULT_TRUNC Result string truncated
ESP_ERR_HTTPD_RESP_HDR Response header field larger than supported
ESP_ERR_HTTPD_RESP_SEND Error occured while sending response packet
ESP_ERR_HTTPD_ALLOC_MEM Failed to dynamically allocate memory for resource
ESP_ERR_HTTPD_TASK Failed to launch server task/thread
HTTPD_RESP_USE_STRLEN

Type Definitions typedef struct httpd_req httpd_req_t
HTTP Request Data Structure. typedef struct httpd_uri httpd_uri_t
Structure for URI handler.
typedef int (*httpd_send_func_t)(httpd_handle_t hd, int sockfd, const char *buf, size_t buf_len, int flags)
Prototype for HTTPDs low-level send function.
Note User specified send function must handle errors internally, depending upon the set value of errno, and return specific HTTPD_SOCK_ERR_ codes, which will eventually be conveyed as return value of httpd_send() function
Return · Bytes : The number of bytes sent successfully · HTTPD_SOCK_ERR_INVALID : Invalid arguments · HTTPD_SOCK_ERR_TIMEOUT : Timeout/interrupted while calling socket send() · HTTPD_SOCK_ERR_FAIL : Unrecoverable error while calling socket send()

Espressif Systems

883

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Parameters · [in] hd: server instance · [in] sockfd: session socket file descriptor · [in] buf: buffer with bytes to send · [in] buf_len: data size · [in] flags: flags for the send() function
typedef int (*httpd_recv_func_t)(httpd_handle_t hd, int sockfd, char *buf, size_t buf_len, int flags)
Prototype for HTTPDs low-level recv function.
Note User specified recv function must handle errors internally, depending upon the set value of errno, and return specific HTTPD_SOCK_ERR_ codes, which will eventually be conveyed as return value of httpd_req_recv() function
Return · Bytes : The number of bytes received successfully · 0 : Buffer length parameter is zero / connection closed by peer · HTTPD_SOCK_ERR_INVALID : Invalid arguments · HTTPD_SOCK_ERR_TIMEOUT : Timeout/interrupted while calling socket recv() · HTTPD_SOCK_ERR_FAIL : Unrecoverable error while calling socket recv()
Parameters · [in] hd: server instance · [in] sockfd: session socket file descriptor · [in] buf: buffer with bytes to send · [in] buf_len: data size · [in] flags: flags for the send() function
typedef int (*httpd_pending_func_t)(httpd_handle_t hd, int sockfd) Prototype for HTTPDs low-level oget pending bytespfunction.
Note User specified pending function must handle errors internally, depending upon the set value of errno, and return specific HTTPD_SOCK_ERR_ codes, which will be handled accordingly in the server task.
Return · Bytes : The number of bytes waiting to be received · HTTPD_SOCK_ERR_INVALID : Invalid arguments · HTTPD_SOCK_ERR_TIMEOUT : Timeout/interrupted while calling socket pending() · HTTPD_SOCK_ERR_FAIL : Unrecoverable error while calling socket pending()
Parameters · [in] hd: server instance · [in] sockfd: session socket file descriptor
typedef esp_err_t (*httpd_err_handler_func_t)(httpd_req_t *req, httpd_err_code_t error) Function prototype for HTTP error handling.
This function is executed upon HTTP errors generated during internal processing of an HTTP request. This is used to override the default behavior on error, which is to send HTTP error response and close the underlying socket.
Note · If implemented, the server will not automatically send out HTTP error response codes, therefore, httpd_resp_send_err() must be invoked inside this function if user wishes to generate HTTP error responses. · When invoked, the validity of uri, method, content_len and user_ctx fields of the httpd_req_t parameter is not guaranteed as the HTTP request may be partially received/parsed. · The function must return ESP_OK if underlying socket needs to be kept open. Any other value will ensure that the socket is closed. The return value is ignored when error is of type HTTPD_500_INTERNAL_SERVER_ERROR and the socket closed anyway.
Return · ESP_OK : error handled successful · ESP_FAIL : failure indicates that the underlying socket needs to be closed
Parameters · [in] req: HTTP request for which the error needs to be handled

Espressif Systems

884

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· [in] error: Error type

typedef void *httpd_handle_t HTTP Server Instance Handle.

Every instance of the server will have a unique handle.

typedef enum http_method httpd_method_t HTTP Method Type wrapper over oenum http_methodpavailable in ohttp_parserplibrary.

typedef void (*httpd_free_ctx_fn_t)(void *ctx) Prototype for freeing context data (if any)

Parameters · [in] ctx: object to free

typedef esp_err_t (*httpd_open_func_t)(httpd_handle_t hd, int sockfd) Function prototype for opening a session.

Called immediately after the socket was opened to set up the send/recv functions and other parameters of the socket.

Return · ESP_OK : On success · Any value other than ESP_OK will signal the server to close the socket immediately
Parameters · [in] hd: server instance · [in] sockfd: session socket file descriptor

typedef void (*httpd_close_func_t)(httpd_handle_t hd, int sockfd) Function prototype for closing a session.

Note Itns possible that the socket descriptor is invalid at this point, the function is called for all terminated sessions. Ensure proper handling of return codes.
Parameters · [in] hd: server instance · [in] sockfd: session socket file descriptor

typedef bool (*httpd_uri_match_func_t)(const char *reference_uri, const char

Function prototype for URI matching.

*uri_to_match, size_t match_upto)

Return true on match Parameters
· [in] reference_uri: URI/template with respect to which the other URI is matched · [in] uri_to_match: URI/template being matched to the reference URI/template · [in] match_upto: For specifying the actual length of uri_to_match up to which the match-
ing algorithm is to be applied (The maximum value is strlen(uri_to_match), independent of the length of reference_uri)

typedef struct httpd_config httpd_config_t HTTP Server Configuration Structure.

Note Use HTTPD_DEFAULT_CONFIG() to initialize the configuration to a default value and then modify only those fields that are specifically determined by the use case.

typedef void (*httpd_work_fn_t)(void *arg) Prototype of the HTTPD work function Please refer to httpd_queue_work() for more details.

Parameters · [in] arg: The arguments for this work function

Enumerations enum httpd_err_code_t
Error codes sent as HTTP response in case of errors encountered during processing of an HTTP request.

Espressif Systems

885

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Values: HTTPD_500_INTERNAL_SERVER_ERROR = 0 HTTPD_501_METHOD_NOT_IMPLEMENTED HTTPD_505_VERSION_NOT_SUPPORTED HTTPD_400_BAD_REQUEST HTTPD_401_UNAUTHORIZED HTTPD_403_FORBIDDEN HTTPD_404_NOT_FOUND HTTPD_405_METHOD_NOT_ALLOWED HTTPD_408_REQ_TIMEOUT HTTPD_411_LENGTH_REQUIRED HTTPD_414_URI_TOO_LONG HTTPD_431_REQ_HDR_FIELDS_TOO_LARGE HTTPD_ERR_CODE_MAX
2.4.7 HTTPS server
Overview
This component is built on top of esp_http_server. The HTTPS server takes advantage of hooks and function overrides in the regular HTTP server to provide encryption using OpenSSL. All documentation for esp_http_server applies also to a server you create this way.
Used APIs
The following API of esp_http_server should not be used with esp_https_server, as they are used internally to handle secure sessions and to maintain internal state:
·osendp, oreceivepand opendingpfunction overrides - secure socket handling ­ httpd_sess_set_send_override() ­ httpd_sess_set_recv_override() ­ httpd_sess_set_pending_override()
·otransport contextp- both global and session ­ httpd_sess_get_transport_ctx() - returns SSL used for the session ­ httpd_sess_set_transport_ctx() ­ httpd_get_global_transport_ctx() - returns the shared SSL context ­ httpd_config_t.global_transport_ctx ­ httpd_config_t.global_transport_ctx_free_fn ­ httpd_config_t.open_fn - used to set up secure sockets
Everything else can be used without limitations.
Usage
Please see the example protocols/https_server to learn how to set up a secure server. Basically all you need is to generate a certificate, embed it in the firmware, and provide its pointers and lengths to the start function via the init struct.

Espressif Systems

886

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
The server can be started with or without SSL by changing a flag in the init struct - httpd_ssl_config. transport_mode. This could be used e.g. for testing or in trusted environments where you prefer speed over security.
Performance
The initial session setup can take about two seconds, or more with slower clock speeds or more verbose logging. Subsequent requests through the open secure socket are much faster (down to under 100 ms).
API Reference
Header File · components/esp_https_server/include/esp_https_server.h
Functions esp_err_t httpd_ssl_start(httpd_handle_t *handle, httpd_ssl_config_t *config)
Create a SSL capable HTTP server (secure mode may be disabled in config) Return success Parameters
· [inout] config: - server config, must not be const. Does not have to stay valid after calling this function.
· [out] handle: - storage for the server handle, must be a valid pointer void httpd_ssl_stop(httpd_handle_t handle)
Stop the server. Blocks until the server is shut down. Parameters
· [in] handle:
Structures struct esp_https_server_user_cb_arg
Callback data struct, contains the ESP-TLS connection handle. struct httpd_ssl_config
HTTPS server config struct Please use HTTPD_SSL_CONFIG_DEFAULT() to initialize it.
Public Members
httpd_config_t httpd Underlying HTTPD server config Parameters like task stack size and priority can be adjusted here.
const uint8_t *cacert_pem CA certificate (here it is treated as server cert) Todo: Fix this change in release/v5.0 as it would be a breaking change i.e. Rename the nomenclature of variables holding different certs in https_server component as well as example 1)The cacert variable should hold the CA which is used to authenticate clients (should inherit current role of client_verify_cert_pem var) 2)There should be another variable servercert which whould hold servers own certificate (should inherit current role of cacert var)
size_t cacert_len CA certificate byte length
const uint8_t *client_verify_cert_pem Client verify authority certificate (CA used to sign clients, or client cert itself

Espressif Systems

887

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
size_t client_verify_cert_len Client verify authority cert len
const uint8_t *prvtkey_pem Private key
size_t prvtkey_len Private key byte length
httpd_ssl_transport_mode_t transport_mode Transport Mode (default secure)
uint16_t port_secure Port used when transport mode is secure (default 443)
uint16_t port_insecure Port used when transport mode is insecure (default 80)
bool session_tickets Enable tls session tickets
esp_https_server_user_cb *user_cb User callback for esp_https_server
Macros HTTPD_SSL_CONFIG_DEFAULT()
Default config struct init (http_server default config had to be copied for customization) Notes:
· port is set when starting the server, according to mtransport_moden · one socket uses ~ 40kB RAM with SSL, we reduce the default socket count to 4 · SSL sockets are usually long-lived, closing LRU prevents pool exhaustion DOS · Stack size may need adjustments depending on the user application
Type Definitions typedef struct esp_https_server_user_cb_arg esp_https_server_user_cb_arg_t
Callback data struct, contains the ESP-TLS connection handle. typedef void esp_https_server_user_cb(esp_https_server_user_cb_arg_t *user_cb)
Callback function prototype Can be used to get connection or client information (SSL context) E.g. Client certificate, Socket FD, Connection state, etc. Parameters
· user_cb: Callback data struct typedef struct httpd_ssl_config httpd_ssl_config_t
Enumerations enum httpd_ssl_transport_mode_t
Values: HTTPD_SSL_TRANSPORT_SECURE HTTPD_SSL_TRANSPORT_INSECURE
2.4.8 ICMP Echo

Espressif Systems

888

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Overview
ICMP (Internet Control Message Protocol) is used for diagnostic or control purposes or generated in response to errors in IP operations. The common network util ping is implemented based on the ICMP packets with the type field value of 0, also called Echo Reply.
During a ping session, the source host firstly sends out an ICMP echo request packet and wait for an ICMP echo reply with specific times. In this way, it also measures the round-trip time for the messages. After receiving a valid ICMP echo reply, the source host will generate statistics about the IP link layer (e.g. packet loss, elapsed time, etc).
It is common that IoT device needs to check whether a remote server is alive or not. The device should show the warnings to users when it got offline. It can be achieved by creating a ping session and sending/parsing ICMP echo packets periodically.
To make this internal procedure much easier for users, ESP-IDF provides some out-of-box APIs.

Create a new ping session To create a ping session, you need to fill in the esp_ping_config_t configuration structure firstly, specifying target IP address, interval times, and etc. Optionally, you can also register some callback functions with the esp_ping_callbacks_t` structure.
Example method to create a new ping session and register callbacks:
static void test_on_ping_success(esp_ping_handle_t hdl, void *args) {
// optionally, get callback arguments // const char* str = (const char*) args; // printf("%s\r\n", str); // "foo" uint8_t ttl; uint16_t seqno; uint32_t elapsed_time, recv_len; ip_addr_t target_addr; esp_ping_get_profile(hdl, ESP_PING_PROF_SEQNO, &seqno, sizeof(seqno)); esp_ping_get_profile(hdl, ESP_PING_PROF_TTL, &ttl, sizeof(ttl)); esp_ping_get_profile(hdl, ESP_PING_PROF_IPADDR, &target_addr, sizeof(target_ addr)); esp_ping_get_profile(hdl, ESP_PING_PROF_SIZE, &recv_len, sizeof(recv_len)); esp_ping_get_profile(hdl, ESP_PING_PROF_TIMEGAP, &elapsed_time, sizeof(elapsed_ time)); printf("%d bytes from %s icmp_seq=%d ttl=%d time=%d ms\n",
recv_len, inet_ntoa(target_addr.u_addr.ip4), seqno, ttl, elapsed_time); }
static void test_on_ping_timeout(esp_ping_handle_t hdl, void *args) {
uint16_t seqno; ip_addr_t target_addr; esp_ping_get_profile(hdl, ESP_PING_PROF_SEQNO, &seqno, sizeof(seqno)); esp_ping_get_profile(hdl, ESP_PING_PROF_IPADDR, &target_addr, sizeof(target_ addr)); printf("From %s icmp_seq=%d timeout\n", inet_ntoa(target_addr.u_addr.ip4), seqno); }
static void test_on_ping_end(esp_ping_handle_t hdl, void *args) {
uint32_t transmitted; uint32_t received; uint32_t total_time_ms;
esp_ping_get_profile(hdl, ESP_PING_PROF_REQUEST, &transmitted, sizeof(transmitted));
esp_ping_get_profile(hdl, ESP_PING_PROF_REPLY, &received, sizeof(received)); (continues on next page)

Espressif Systems

889

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)
esp_ping_get_profile(hdl, ESP_PING_PROF_DURATION, &total_time_ms, sizeof(total_ time_ms));
printf("%d packets transmitted, %d received, time %dms\n", transmitted, received, total_time_ms); }

void initialize_ping() {
/* convert URL to IP address */ ip_addr_t target_addr; struct addrinfo hint; struct addrinfo *res = NULL; memset(&hint, 0, sizeof(hint)); memset(&target_addr, 0, sizeof(target_addr)); getaddrinfo("www.espressif.com", NULL, &hint, &res); struct in_addr addr4 = ((struct sockaddr_in *) (res->ai_addr))->sin_addr; inet_addr_to_ip4addr(ip_2_ip4(&target_addr), &addr4); freeaddrinfo(res);

esp_ping_config_t ping_config = ESP_PING_DEFAULT_CONFIG();

ping_config.target_addr = target_addr;

// target IP address

ping_config.count = ESP_PING_COUNT_INFINITE; // ping in infinite mode, esp_

ping_stop can stop it

/* set callback functions */ esp_ping_callbacks_t cbs; cbs.on_ping_success = test_on_ping_success; cbs.on_ping_timeout = test_on_ping_timeout; cbs.on_ping_end = test_on_ping_end; cbs.cb_args = "foo"; // arguments that will feed to all callback functions, can be NULL cbs.cb_args = eth_event_group;

esp_ping_handle_t ping; esp_ping_new_session(&ping_config, &cbs, &ping); }

Start and Stop ping session You can start and stop ping session with the handle returned by esp_ping_new_session. Note that, the ping session wonnt start automatically after creation. If the ping session is stopped, and restart again, the sequence number in ICMP packets will recount from zero again.
Delete a ping session If a ping session wonnt be used any more, you can delete it with esp_ping_delete_session. Please make sure the ping session is in stop state (i.e. you have called esp_ping_stop before or the ping session has finished all the procedures) when you call this function.
Get runtime statistics As the example code above, you can call esp_ping_get_profile to get different runtime statistics of ping session in the callback function.
Application Example ICMP echo example: protocols/icmp_echo
API Reference Header File

Espressif Systems

890

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· components/lwip/include/apps/ping/ping_sock.h
Functions esp_err_t esp_ping_new_session(const esp_ping_config_t *config, const esp_ping_callbacks_t
*cbs, esp_ping_handle_t *hdl_out) Create a ping session.
Return · ESP_ERR_INVALID_ARG: invalid parameters (e.g. configuration is null, etc) · ESP_ERR_NO_MEM: out of memory · ESP_FAIL: other internal error (e.g. socket error) · ESP_OK: create ping session successfully, user can take the ping handle to do follow-on jobs
Parameters · config: ping configuration · cbs: a bunch of callback functions invoked by internal ping task · hdl_out: handle of ping session
esp_err_t esp_ping_delete_session(esp_ping_handle_t hdl) Delete a ping session.
Return · ESP_ERR_INVALID_ARG: invalid parameters (e.g. ping handle is null, etc) · ESP_OK: delete ping session successfully
Parameters · hdl: handle of ping session
esp_err_t esp_ping_start(esp_ping_handle_t hdl) Start the ping session.
Return · ESP_ERR_INVALID_ARG: invalid parameters (e.g. ping handle is null, etc) · ESP_OK: start ping session successfully
Parameters · hdl: handle of ping session
esp_err_t esp_ping_stop(esp_ping_handle_t hdl) Stop the ping session.
Return · ESP_ERR_INVALID_ARG: invalid parameters (e.g. ping handle is null, etc) · ESP_OK: stop ping session successfully
Parameters · hdl: handle of ping session
esp_err_t esp_ping_get_profile(esp_ping_handle_t hdl, esp_ping_profile_t profile, void *data, uint32_t size)
Get runtime profile of ping session.
Return · ESP_ERR_INVALID_ARG: invalid parameters (e.g. ping handle is null, etc) · ESP_ERR_INVALID_SIZE: the actual profile data size doesnnt match the osizepparameter · ESP_OK: get profile successfully
Parameters · hdl: handle of ping session · profile: type of profile · data: profile data · size: profile data size
Structures struct esp_ping_callbacks_t
Type of opingpcallback functions.

Espressif Systems

891

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Public Members
void *cb_args arguments for callback functions
void (*on_ping_success)(esp_ping_handle_t hdl, void *args) Invoked by internal ping thread when received ICMP echo reply packet.
void (*on_ping_timeout)(esp_ping_handle_t hdl, void *args) Invoked by internal ping thread when receive ICMP echo reply packet timeout.
void (*on_ping_end)(esp_ping_handle_t hdl, void *args) Invoked by internal ping thread when a ping session is finished.
struct esp_ping_config_t Type of opingpconfiguration.
Public Members
uint32_t count A opingpsession contains count procedures
uint32_t interval_ms Milliseconds between each ping procedure
uint32_t timeout_ms Timeout value (in milliseconds) of each ping procedure
uint32_t data_size Size of the data next to ICMP packet header
uint8_t tos Type of Service, a field specified in the IP header
ip_addr_t target_addr Target IP address, either IPv4 or IPv6
uint32_t task_stack_size Stack size of internal ping task
uint32_t task_prio Priority of internal ping task
uint32_t interface Netif index, interface=0 means NETIF_NO_INDEX
Macros ESP_PING_DEFAULT_CONFIG()
Default ping configuration. ESP_PING_COUNT_INFINITE
Set ping count to zero will ping target infinitely
Type Definitions typedef void *esp_ping_handle_t
Type of opingpsession handle.
Enumerations enum esp_ping_profile_t
Profile of ping session. Values:

Espressif Systems

892

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_PING_PROF_SEQNO Sequence number of a ping procedure
ESP_PING_PROF_TTL Time to live of a ping procedure
ESP_PING_PROF_REQUEST Number of request packets sent out
ESP_PING_PROF_REPLY Number of reply packets received
ESP_PING_PROF_IPADDR IP address of replied target
ESP_PING_PROF_SIZE Size of received packet
ESP_PING_PROF_TIMEGAP Elapsed time between request and reply packet
ESP_PING_PROF_DURATION Elapsed time of the whole ping session

2.4.9 ESP Local Control

Overview

ESP Local Control (esp_local_ctrl) component in ESP-IDF provides capability to control an ESP device over Wi-Fi + HTTPS or BLE. It provides access to application defined properties that are available for reading / writing via a set of configurable handlers.
Initialization of the esp_local_ctrl service over BLE transport is performed as follows:

esp_local_ctrl_config_t config = {

.transport = ESP_LOCAL_CTRL_TRANSPORT_BLE,

.transport_config = {

.ble = & (protocomm_ble_config_t) {

.device_name = SERVICE_NAME,

.service_uuid = {

/* LSB <---------------------------------------

* ---------------------------------------> MSB */

0x21, 0xd5, 0x3b, 0x8d, 0xbd, 0x75, 0x68, 0x8a,

0xb4, 0x42, 0xeb, 0x31, 0x4a, 0x1e, 0x98, 0x3d

}

}

},

.proto_sec = {

.version = PROTOCOM_SEC0,

.custom_handle = NULL,

.pop = NULL,

},

.handlers = {

/* User defined handler functions */

.get_prop_values = get_property_values,

.set_prop_values = set_property_values,

.usr_ctx

= NULL,

.usr_ctx_free_fn = NULL

},

/* Maximum number of properties that may be set */

.max_properties = 10

};

(continues on next page)

Espressif Systems

893

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

/* Start esp_local_ctrl service */ ESP_ERROR_CHECK(esp_local_ctrl_start(&config));

(continued from previous page)

Similarly for HTTPS transport:

/* Set the configuration */ httpd_ssl_config_t https_conf = HTTPD_SSL_CONFIG_DEFAULT();

/* Load server certificate */ extern const unsigned char cacert_pem_start[] asm("_binary_cacert_pem_ start"); extern const unsigned char cacert_pem_end[] asm("_binary_cacert_pem_end "); https_conf.cacert_pem = cacert_pem_start; https_conf.cacert_len = cacert_pem_end - cacert_pem_start;

/* Load server private key */ extern const unsigned char prvtkey_pem_start[] asm("_binary_prvtkey_pem_ start"); extern const unsigned char prvtkey_pem_end[] asm("_binary_prvtkey_pem_ end"); https_conf.prvtkey_pem = prvtkey_pem_start; https_conf.prvtkey_len = prvtkey_pem_end - prvtkey_pem_start;

esp_local_ctrl_config_t config = {

.transport = ESP_LOCAL_CTRL_TRANSPORT_HTTPD,

.transport_config = {

.httpd = &https_conf

},

.proto_sec = {

.version = PROTOCOM_SEC0,

.custom_handle = NULL,

.pop = NULL,

},

.handlers = {

/* User defined handler functions */

.get_prop_values = get_property_values,

.set_prop_values = set_property_values,

.usr_ctx

= NULL,

.usr_ctx_free_fn = NULL

},

/* Maximum number of properties that may be set */

.max_properties = 10

};

/* Start esp_local_ctrl service */ ESP_ERROR_CHECK(esp_local_ctrl_start(&config));

You may set security for transport in ESP local control using following options:
1. PROTOCOM_SEC1: specifies that end to end encryption is used. 2. PROTOCOM_SEC0: specifies that data will be exchanged as a plain text. 3. PROTOCOM_SEC_CUSTOM: you can define your own security requirement. Please note that you will also
have to provide custom_handle of type protocomm_security_t * in this context.

Creating a property
Now that we know how to start the esp_local_ctrl service, letns add a property to it. Each property must have a unique name (string), a type (e.g. enum), flags (bit fields) and size. The size is to be kept 0, if we want our property value to be of variable length (e.g. if its a string or bytestream). For

Espressif Systems

894

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

fixed length property value data-types, like int, float, etc., setting the size field to the right value, helps esp_local_ctrl to perform internal checks on arguments received with write requests.
The interpretation of type and flags fields is totally upto the application, hence they may be used as enumerations, bitfields, or even simple integers. One way is to use type values to classify properties, while flags to specify characteristics of a property.

Here is an example property which is to function as a timestamp. It is assumed that the application defines TYPE_TIMESTAMP and READONLY, which are used for setting the type and flags fields here.

/* Create a timestamp property */

esp_local_ctrl_prop_t timestamp = {

.name

= "timestamp",

.type

= TYPE_TIMESTAMP,

.size

= sizeof(int32_t),

.flags

= READONLY,

.ctx

= func_get_time,

.ctx_free_fn = NULL

};

/* Now register the property */ esp_local_ctrl_add_property(&timestamp);

Also notice that there is a ctx field, which is set to point to some custom func_get_time(). This can be used inside the property get / set handlers to retrieve timestamp.
Here is an example of get_prop_values() handler, which is used for retrieving the timestamp.
static esp_err_t get_property_values(size_t props_count, const esp_local_ctrl_prop_t *props, esp_local_ctrl_prop_val_t *prop_
values, void *usr_ctx)
{ for (uint32_t i = 0; i < props_count; i++) { ESP_LOGI(TAG, "Reading %s", props[i].name); if (props[i].type == TYPE_TIMESTAMP) { /* Obtain the timer function from ctx */ int32_t (*func_get_time)(void) = props[i].ctx;
/* Use static variable for saving the value. * This is essential because the value has to be * valid even after this function returns. * Alternative is to use dynamic allocation * and set the free_fn field */
static int32_t ts = func_get_time(); prop_values[i].data = &ts; } } return ESP_OK; }

Here is an example of set_prop_values() handler. Notice how we restrict from writing to read-only properties.

static esp_err_t set_property_values(size_t props_count,

const esp_local_ctrl_prop_t *props,

const esp_local_ctrl_prop_val_t

*prop_values,

void *usr_ctx)

{

for (uint32_t i = 0; i < props_count; i++) {

if (props[i].flags & READONLY) {

ESP_LOGE(TAG, "Cannot write to read-only property %s",

props[i].name);

(continues on next page)

Espressif Systems

895

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page) return ESP_ERR_INVALID_ARG; } else { ESP_LOGI(TAG, "Setting %s", props[i].name);
/* For keeping it simple, lets only log the incoming data */ ESP_LOG_BUFFER_HEX_LEVEL(TAG, prop_values[i].data,
prop_values[i].size, ESP_LOG_INFO); } } return ESP_OK; }
For complete example see protocols/esp_local_ctrl

Client Side Implementation

The client side implementation will have establish a protocomm session with the device first, over the supported mode of transport, and then send and receive protobuf messages understood by the esp_local_ctrl service. The service will translate these messages into requests and then call the appropriate handlers (set / get). Then, the generated response for each handler is again packed into a protobuf message and transmitted back to the client.
See below the various protobuf messages understood by the esp_local_ctrl service:
1. get_prop_count : This should simply return the total number of properties supported by the service 2. get_prop_values : This accepts an array of indices and should return the information (name, type, flags) and
values of the properties corresponding to those indices 3. set_prop_values : This accepts an array of indices and an array of new values, which are used for setting the
values of the properties corresponding to the indices
Note that indices may or may not be the same for a property, across multiple sessions. Therefore, the client must only use the names of the properties to uniquely identify them. So, every time a new session is established, the client should first call get_prop_count and then get_prop_values, hence form an index to name mapping for all properties. Now when calling set_prop_values for a set of properties, it must first convert the names to indexes, using the created mapping. As emphasized earlier, the client must refresh the index to name mapping every time a new session is established with the same device.
The various protocomm endpoints provided by esp_local_ctrl are listed below:

Table 7: Endpoints provided by ESP Local Control

Endpoint URI (HTTPS Server + Description

Name

mDNS)

(BLE +

GATT

Server)

esp_local_ctrlh/vtteprs:i/o/n<mdns-

Endpoint used for retrieving version string

hostname>.local/esp_local_ctrl/version

esp_local_ctrlh/cttopnst:r/o/<l mdns-

Endpoint used for sending / receiving control messages

hostname>.local/esp_local_ctrl/control

API Reference Header File
· components/esp_local_ctrl/include/esp_local_ctrl.h
Functions

Espressif Systems

896

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

const esp_local_ctrl_transport_t *esp_local_ctrl_get_transport_ble(void) Function for obtaining BLE transport mode.
const esp_local_ctrl_transport_t *esp_local_ctrl_get_transport_httpd(void) Function for obtaining HTTPD transport mode.
esp_err_t esp_local_ctrl_start(const esp_local_ctrl_config_t *config) Start local control service.
Return · ESP_OK : Success · ESP_FAIL : Failure
Parameters · [in] config: Pointer to configuration structure
esp_err_t esp_local_ctrl_stop(void) Stop local control service.
esp_err_t esp_local_ctrl_add_property(const esp_local_ctrl_prop_t *prop) Add a new property.
This adds a new property and allocates internal resources for it. The total number of properties that could be added is limited by configuration option max_properties
Return · ESP_OK : Success · ESP_FAIL : Failure
Parameters · [in] prop: Property description structure
esp_err_t esp_local_ctrl_remove_property(const char *name) Remove a property.
This finds a property by name, and releases the internal resources which are associated with it.
Return · ESP_OK : Success · ESP_ERR_NOT_FOUND : Failure
Parameters · [in] name: Name of the property to remove
const esp_local_ctrl_prop_t *esp_local_ctrl_get_property(const char *name) Get property description structure by name.
This API may be used to get a propertyns context structure esp_local_ctrl_prop_t when its name is known
Return · Pointer to property · NULL if not found
Parameters · [in] name: Name of the property to find
esp_err_t esp_local_ctrl_set_handler(const char *ep_name, protocomm_req_handler_t handler, void *user_ctx)
Register protocomm handler for a custom endpoint.
This API can be called by the application to register a protocomm handler for an endpoint after the local control service has started.
Note In case of BLE transport the names and uuids of all custom endpoints must be provided beforehand as a part of the protocomm_ble_config_t structure set in esp_local_ctrl_config_t, and passed to esp_local_ctrl_start().
Return · ESP_OK : Success · ESP_FAIL : Failure
Parameters

Espressif Systems

897

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· [in] ep_name: Name of the endpoint · [in] handler: Endpoint handler function · [in] user_ctx: User data
Unions union esp_local_ctrl_transport_config_t
#include <esp_local_ctrl.h> Transport mode (BLE / HTTPD) configuration.
Public Members
esp_local_ctrl_transport_config_ble_t *ble This is same as protocomm_ble_config_t. See protocomm_ble.h for available configuration parameters.
esp_local_ctrl_transport_config_httpd_t *httpd This is same as httpd_ssl_config_t. See esp_https_server.h for available configuration parameters.
Structures struct esp_local_ctrl_prop
Property description data structure, which is to be populated and passed to the esp_local_ctrl_add_property() function.
Once a property is added, its structure is available for read-only access inside get_prop_values() and set_prop_values() handlers.
Public Members
char *name Unique name of property
uint32_t type Type of property. This may be set to application defined enums
size_t size Size of the property value, which:
· if zero, the property can have values of variable size · if non-zero, the property can have values of fixed size only, therefore, checks are performed internally
by esp_local_ctrl when setting the value of such a property
uint32_t flags Flags set for this property. This could be a bit field. A flag may indicate property behavior, e.g. read-only / constant
void *ctx Pointer to some context data relevant for this property. This will be available for use inside the get_prop_values and set_prop_values handlers as a part of this property structure. When set, this is valid throughout the lifetime of a property, till either the property is removed or the esp_local_ctrl service is stopped.
void (*ctx_free_fn)(void *ctx) Function used by esp_local_ctrl to internally free the property context when esp_local_ctrl_remove_property() or esp_local_ctrl_stop() is called.
struct esp_local_ctrl_prop_val Property value data structure. This gets passed to the get_prop_values() and set_prop_values() handlers for the purpose of retrieving or setting the present value of a property.

Espressif Systems

898

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Public Members
void *data Pointer to memory holding property value
size_t size Size of property value
void (*free_fn)(void *data) This may be set by the application in get_prop_values() handler to tell esp_local_ctrl to call this function on the data pointer above, for freeing its resources after sending the get_prop_values response.
struct esp_local_ctrl_handlers Handlers for receiving and responding to local control commands for getting and setting properties.

Public Members

esp_err_t (*get_prop_values)(size_t props_count, const esp_local_ctrl_prop_t props[],
esp_local_ctrl_prop_val_t prop_values[], void *usr_ctx) Handler function to be implemented for retrieving current values of properties.

Note If any of the properties have fixed sizes, the size field of corresponding element in prop_values

need to be set

Return Returning different error codes will convey the corresponding protocol level errors to the client

:

· ESP_OK : Success

· ESP_ERR_INVALID_ARG : InvalidArgument

· ESP_ERR_INVALID_STATE : InvalidProto

· All other error codes : InternalError

Parameters

· [in] props_count: Total elements in the props array

· [in] props: Array of properties, the current values for which have been requested by the

client

· [out] prop_values: Array of empty property values, the elements of which need to be

populated with the current values of those properties specified by props argument

· [in]

usr_ctx: This provides value of the usr_ctx field of

esp_local_ctrl_handlers_t structure

esp_err_t (*set_prop_values)(size_t props_count, const esp_local_ctrl_prop_t props[], const
esp_local_ctrl_prop_val_t prop_values[], void *usr_ctx) Handler function to be implemented for changing values of properties.

Note If any of the properties have variable sizes, the size field of the corresponding element in

prop_values must be checked explicitly before making any assumptions on the size.

Return Returning different error codes will convey the corresponding protocol level errors to the client

:

· ESP_OK : Success

· ESP_ERR_INVALID_ARG : InvalidArgument

· ESP_ERR_INVALID_STATE : InvalidProto

· All other error codes : InternalError

Parameters

· [in] props_count: Total elements in the props array

· [in] props: Array of properties, the values for which the client requests to change

· [in] prop_values: Array of property values, the elements of which need to be used for

updating those properties specified by props argument

· [in]

usr_ctx: This provides value of the usr_ctx field of

esp_local_ctrl_handlers_t structure

void *usr_ctx Context pointer to be passed to above handler functions upon invocation. This is different from the

Espressif Systems

899

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
property level context, as this is valid throughout the lifetime of the esp_local_ctrl service, and freed only when the service is stopped. void (*usr_ctx_free_fn)(void *usr_ctx) Pointer to function which will be internally invoked on usr_ctx for freeing the context resources when esp_local_ctrl_stop() is called. struct esp_local_ctrl_proto_sec_cfg Protocom security configs
Public Members
esp_local_ctrl_proto_sec_t version This sets protocom security version, sec0/sec1 or custom If custom, user must provide handle via proto_sec_custom_handle below
void *custom_handle Custom security handle if security is set custom via proto_sec above This handle must follow protocomm_security_t signature
void *pop Proof of possession to be used for local control. Could be NULL.
struct esp_local_ctrl_config Configuration structure to pass to esp_local_ctrl_start()
Public Members
const esp_local_ctrl_transport_t *transport Transport layer over which service will be provided
esp_local_ctrl_transport_config_t transport_config Transport layer over which service will be provided
esp_local_ctrl_proto_sec_cfg_t proto_sec Security version and POP
esp_local_ctrl_handlers_t handlers Register handlers for responding to get/set requests on properties
size_t max_properties This limits the number of properties that are available at a time
Macros ESP_LOCAL_CTRL_TRANSPORT_BLE ESP_LOCAL_CTRL_TRANSPORT_HTTPD
Type Definitions typedef struct esp_local_ctrl_prop esp_local_ctrl_prop_t
Property description data structure, which is to be populated and passed to the esp_local_ctrl_add_property() function. Once a property is added, its structure is available for read-only access inside get_prop_values() and set_prop_values() handlers. typedef struct esp_local_ctrl_prop_val esp_local_ctrl_prop_val_t Property value data structure. This gets passed to the get_prop_values() and set_prop_values() handlers for the purpose of retrieving or setting the present value of a property. typedef struct esp_local_ctrl_handlers esp_local_ctrl_handlers_t Handlers for receiving and responding to local control commands for getting and setting properties.

Espressif Systems

900

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

typedef struct esp_local_ctrl_transport esp_local_ctrl_transport_t Transport mode (BLE / HTTPD) over which the service will be provided.
This is forward declaration of a private structure, implemented internally by esp_local_ctrl.
typedef struct protocomm_ble_config esp_local_ctrl_transport_config_ble_t Configuration for transport mode BLE.
This is a forward declaration for protocomm_ble_config_t. To use this, application must set CONFIG_BT_BLUEDROID_ENABLED and include protocomm_ble.h.
typedef struct httpd_ssl_config esp_local_ctrl_transport_config_httpd_t Configuration for transport mode HTTPD.
This is a forward declaration for httpd_ssl_config_t. To use this, application must set CONFIG_ESP_HTTPS_SERVER_ENABLE and include esp_https_server.h
typedef enum esp_local_ctrl_proto_sec esp_local_ctrl_proto_sec_t Security types for esp_local_control.
typedef struct esp_local_ctrl_proto_sec_cfg esp_local_ctrl_proto_sec_cfg_t Protocom security configs
typedef struct esp_local_ctrl_config esp_local_ctrl_config_t Configuration structure to pass to esp_local_ctrl_start()

Enumerations enum esp_local_ctrl_proto_sec
Security types for esp_local_control.
Values:
PROTOCOM_SEC0 = 0
PROTOCOM_SEC1
PROTOCOM_SEC_CUSTOM

2.4.10 mDNS Service
Overview
mDNS is a multicast UDP service that is used to provide local network service and host discovery. mDNS is installed by default on most operating systems or is available as separate package. On Mac OS it is installed by default and is called Bonjour. Apple releases an installer for Windows that can be found on Applens support page. On Linux, mDNS is provided by avahi and is usually installed by default.

mDNS Properties
· hostname: the hostname that the device will respond to. If not set, the hostname will be read from the interface. Example: my-esp32s3 will resolve to my-esp32s3.local
· default_instance: friendly name for your device, like Jhon's ESP32-S3 Thing. If not set, hostname will be used.
Example method to start mDNS for the STA interface and set hostname and default_instance:

void start_mdns_service() {
//initialize mDNS service esp_err_t err = mdns_init(); if (err) {
printf("MDNS Init failed: %d\n", err);

(continues on next page)

Espressif Systems

901

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

return; }
//set hostname mdns_hostname_set("my-esp32s3"); //set default instance mdns_instance_name_set("Jhon's ESP32-S3 Thing"); }

(continued from previous page)

mDNS Services mDNS can advertise information about network services that your device offers. Each service is defined by a few properties.
· instance_name: friendly name for your service, like Jhon's EESP32-S3 Web Server. If not defined, default_instance will be used.
· service_type: (required) service type, prepended with underscore. Some common types can be found here.
· proto: (required) protocol that the service runs on, prepended with underscore. Example: _tcp or _udp · port: (required) network port that the service runs on · txt: {var, val} array of strings, used to define properties for your service
Example method to add a few services and different properties:
void add_mdns_services() {
//add our services mdns_service_add(NULL, "_http", "_tcp", 80, NULL, 0); mdns_service_add(NULL, "_arduino", "_tcp", 3232, NULL, 0); mdns_service_add(NULL, "_myservice", "_udp", 1234, NULL, 0);
//NOTE: services must be added before their properties can be set //use custom instance for the web server mdns_service_instance_name_set("_http", "_tcp", "Jhon's ESP32-S3 Web Server");
mdns_txt_item_t serviceTxtData[3] = { {"board","{esp32s3}"}, {"u","user"}, {"p","password"}
}; //set txt data for service (will free and replace current data) mdns_service_txt_set("_http", "_tcp", serviceTxtData, 3);
//change service port mdns_service_port_set("_myservice", "_udp", 4321); }

mDNS Query mDNS provides methods for browsing for services and resolving hostns IP/IPv6 addresses.
Results for services are returned as a linked list of mdns_result_t objects.
Example method to resolve host IPs:
void resolve_mdns_host(const char * host_name) {
printf("Query A: %s.local", host_name);

struct ip4_addr addr; addr.addr = 0;

esp_err_t err = mdns_query_a(host_name, 2000, &addr);

(continues on next page)

Espressif Systems

902

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

if(err){ if(err == ESP_ERR_NOT_FOUND){ printf("Host was not found!"); return; } printf("Query Failed"); return;
}
printf(IPSTR, IP2STR(&addr)); }

(continued from previous page)

Example method to resolve local services:

static const char * if_str[] = {"STA", "AP", "ETH", "MAX"}; static const char * ip_protocol_str[] = {"V4", "V6", "MAX"};

void mdns_print_results(mdns_result_t * results){ mdns_result_t * r = results; mdns_ip_addr_t * a = NULL; int i = 1, t; while(r){ printf("%d: Interface: %s, Type: %s\n", i++, if_str[r->tcpip_if], ip_
protocol_str[r->ip_protocol]); if(r->instance_name){ printf(" PTR : %s\n", r->instance_name); } if(r->hostname){ printf(" SRV : %s.local:%u\n", r->hostname, r->port); } if(r->txt_count){ printf(" TXT : [%u] ", r->txt_count); for(t=0; t<r->txt_count; t++){ printf("%s=%s; ", r->txt[t].key, r->txt[t].value); } printf("\n"); } a = r->addr; while(a){ if(a->addr.type == IPADDR_TYPE_V6){ printf(" AAAA: " IPV6STR "\n", IPV62STR(a->addr.u_addr.ip6)); } else { printf(" A : " IPSTR "\n", IP2STR(&(a->addr.u_addr.ip4))); } a = a->next; } r = r->next;
}

}

void find_mdns_service(const char * service_name, const char * proto) {
ESP_LOGI(TAG, "Query PTR: %s.%s.local", service_name, proto);

mdns_result_t * results = NULL; esp_err_t err = mdns_query_ptr(service_name, proto, 3000, 20, if(err){
ESP_LOGE(TAG, "Query Failed"); return; }

&results); (continues on next page)

Espressif Systems

903

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

if(!results){ ESP_LOGW(TAG, "No results found!"); return;
}
mdns_print_results(results); mdns_query_results_free(results); }
Example of using the methods above:
void my_app_some_method(){ //search for esp32s3-mdns.local resolve_mdns_host("esp32s3-mdns");
//search for HTTP servers find_mdns_service("_http", "_tcp"); //or file servers find_mdns_service("_smb", "_tcp"); //windows sharing find_mdns_service("_afpovertcp", "_tcp"); //apple sharing find_mdns_service("_nfs", "_tcp"); //NFS server find_mdns_service("_ftp", "_tcp"); //FTP server //or networked printer find_mdns_service("_printer", "_tcp"); find_mdns_service("_ipp", "_tcp"); }

(continued from previous page)

Application Example
mDNS server/scanner example: protocols/mdns.
API Reference
Header File
· components/mdns/include/mdns.h
Functions esp_err_t mdns_init(void)
Initialize mDNS on given interface.
Return · ESP_OK on success · ESP_ERR_INVALID_STATE when failed to register event handler · ESP_ERR_NO_MEM on memory error · ESP_FAIL when failed to start mdns task
void mdns_free(void) Stop and free mDNS server.
esp_err_t mdns_hostname_set(const char *hostname) Set the hostname for mDNS server required if you want to advertise services.
Return · ESP_OK success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NO_MEM memory error
Parameters · hostname: Hostname to set

Espressif Systems

904

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t mdns_delegate_hostname_add(const char *hostname, const mdns_ip_addr_t *address_list)
Adds a hostname and address to be delegated A/AAAA queries will be replied for the hostname and services can be added to this host.
Return · ESP_OK success · ESP_ERR_INVALID_STATE mDNS is not running · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NO_MEM memory error
Parameters · hostname: Hostname to add · address_list: The IP address list of the host
esp_err_t mdns_delegate_hostname_remove(const char *hostname) Remove a delegated hostname All the services added to this host will also be removed.
Return · ESP_OK success · ESP_ERR_INVALID_STATE mDNS is not running · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NO_MEM memory error
Parameters · hostname: Hostname to remove
bool mdns_hostname_exists(const char *hostname) Query whether a hostname has been added.
Return · true The hostname has been added. · false The hostname has not been added.
Parameters · hostname: Hostname to query
esp_err_t mdns_instance_name_set(const char *instance_name) Set the default instance name for mDNS server.
Return · ESP_OK success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NO_MEM memory error
Parameters · instance_name: Instance name to set
esp_err_t mdns_service_add(const char *instance_name, const char *service_type, const char *proto, uint16_t port, mdns_txt_item_t txt[], size_t num_items)
Add service to mDNS server.
Note The value length of txt items will be automatically decided by strlen Return
· ESP_OK success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NO_MEM memory error · ESP_FAIL failed to add service Parameters · instance_name: instance name to set. If NULL, global instance name or hostname will be used.
Note that MDNS_MULTIPLE_INSTANCE config option needs to be enabled for adding multiple instances with the same instance type. · service_type: service type (_http, _ftp, etc) · proto: service protocol (_tcp, _udp) · port: service port · txt: string array of TXT data (eg. {{ovarp,pvalp},{ootherp,p2p}}) · num_items: number of items in TXT data

Espressif Systems

905

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t mdns_service_add_for_host(const char *instance_name, const char *service_type, const char *proto, const char *hostname, uint16_t port, mdns_txt_item_t txt[], size_t num_items)
Add service to mDNS server with a delegated hostname.
Note The value length of txt items will be automatically decided by strlen Return
· ESP_OK success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NO_MEM memory error · ESP_FAIL failed to add service Parameters · instance_name: instance name to set. If NULL, global instance name or hostname will be used
Note that MDNS_MULTIPLE_INSTANCE config option needs to be enabled for adding multiple instances with the same instance type. · service_type: service type (_http, _ftp, etc) · proto: service protocol (_tcp, _udp) · hostname: service hostname. If NULL, local hostname will be used. · port: service port · txt: string array of TXT data (eg. {{ovarp,pvalp},{ootherp,p2p}}) · num_items: number of items in TXT data
bool mdns_service_exists(const char *service_type, const char *proto, const char *hostname) Check whether a service has been added.
Return · true Correspondding service has been added. · false Service not found.
Parameters · service_type: service type (_http, _ftp, etc) · proto: service protocol (_tcp, _udp) · hostname: service hostname. If NULL, checks for the local hostname.
bool mdns_service_exists_with_instance(const char *instance, const char *service_type, const char *proto, const char *hostname)
Check whether a service has been added.
Return · true Correspondding service has been added. · false Service not found.
Parameters · instance: instance name · service_type: service type (_http, _ftp, etc) · proto: service protocol (_tcp, _udp) · hostname: service hostname. If NULL, checks for the local hostname.
esp_err_t mdns_service_remove(const char *service_type, const char *proto) Remove service from mDNS server.
Return · ESP_OK success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NOT_FOUND Service not found · ESP_ERR_NO_MEM memory error
Parameters · service_type: service type (_http, _ftp, etc) · proto: service protocol (_tcp, _udp)
esp_err_t mdns_service_remove_for_host(const char *instance, const char *service_type, const char *proto, const char *hostname)
Remove service from mDNS server with hostname.
Return

Espressif Systems

906

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_OK success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NOT_FOUND Service not found · ESP_ERR_NO_MEM memory error Parameters · instance: instance name · service_type: service type (_http, _ftp, etc) · proto: service protocol (_tcp, _udp) · hostname: service hostname. If NULL, local hostname will be used.

esp_err_t mdns_service_instance_name_set(const char *service_type, const char *proto,

Set instance name for service.

const char *instance_name)

Return · ESP_OK success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NOT_FOUND Service not found · ESP_ERR_NO_MEM memory error
Parameters · service_type: service type (_http, _ftp, etc) · proto: service protocol (_tcp, _udp) · instance_name: instance name to set

esp_err_t mdns_service_instance_name_set_for_host(const char *instance_old, const

char *service_type, const char

*proto, const char *hostname,

Set instance name for service with hostname.

const char *instance_name)

Return · ESP_OK success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NOT_FOUND Service not found · ESP_ERR_NO_MEM memory error
Parameters · instance_old: original instance name · service_type: service type (_http, _ftp, etc) · proto: service protocol (_tcp, _udp) · hostname: service hostname. If NULL, local hostname will be used. · instance_name: instance name to set

esp_err_t mdns_service_port_set(const char *service_type, const char *proto, uint16_t port) Set service port.

Return · ESP_OK success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NOT_FOUND Service not found · ESP_ERR_NO_MEM memory error
Parameters · service_type: service type (_http, _ftp, etc) · proto: service protocol (_tcp, _udp) · port: service port

esp_err_t mdns_service_port_set_for_host(const char *instance, const char *service_type, const char *proto, const char *hostname, uint16_t port)
Set service port with hostname.

Return · ESP_OK success · ESP_ERR_INVALID_ARG Parameter error

Espressif Systems

907

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· ESP_ERR_NOT_FOUND Service not found · ESP_ERR_NO_MEM memory error Parameters · instance: instance name · service_type: service type (_http, _ftp, etc) · proto: service protocol (_tcp, _udp) · hostname: service hostname. If NULL, local hostname will be used. · port: service port
esp_err_t mdns_service_txt_set(const char *service_type, const char *proto, mdns_txt_item_t txt[], uint8_t num_items)
Replace all TXT items for service.
Note The value length of txt items will be automatically decided by strlen Return
· ESP_OK success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NOT_FOUND Service not found · ESP_ERR_NO_MEM memory error Parameters · service_type: service type (_http, _ftp, etc) · proto: service protocol (_tcp, _udp) · txt: array of TXT data (eg. {{ovarp,pvalp},{ootherp,p2p}}) · num_items: number of items in TXT data
esp_err_t mdns_service_txt_set_for_host(const char *instance, const char *service_type, const char *proto, const char *hostname, mdns_txt_item_t txt[], uint8_t num_items)
Replace all TXT items for service with hostname.
Note The value length of txt items will be automatically decided by strlen Return
· ESP_OK success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NOT_FOUND Service not found · ESP_ERR_NO_MEM memory error Parameters · instance: instance name · service_type: service type (_http, _ftp, etc) · proto: service protocol (_tcp, _udp) · hostname: service hostname. If NULL, local hostname will be used. · txt: array of TXT data (eg. {{ovarp,pvalp},{ootherp,p2p}}) · num_items: number of items in TXT data
esp_err_t mdns_service_txt_item_set(const char *service_type, const char *proto, const char *key, const char *value)
Set/Add TXT item for service TXT record.
Note The value length will be automatically decided by strlen Return
· ESP_OK success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NOT_FOUND Service not found · ESP_ERR_NO_MEM memory error Parameters · service_type: service type (_http, _ftp, etc) · proto: service protocol (_tcp, _udp) · key: the key that you want to add/update · value: the new value of the key

Espressif Systems

908

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t mdns_service_txt_item_set_with_explicit_value_len(const

char

*service_type, const

char *proto, const

char *key, const

char *value, uint8_t

Set/Add TXT item for service TXT record.

value_len)

Return · ESP_OK success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NOT_FOUND Service not found · ESP_ERR_NO_MEM memory error
Parameters · service_type: service type (_http, _ftp, etc) · proto: service protocol (_tcp, _udp) · key: the key that you want to add/update · value: the new value of the key · value_len: the length of the value

esp_err_t mdns_service_txt_item_set_for_host(const char *instance, const char *service_type, const char *proto, const char *hostname, const char *key, const char *value)
Set/Add TXT item for service TXT record with hostname.

Note The value length will be automatically decided by strlen Return
· ESP_OK success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NOT_FOUND Service not found · ESP_ERR_NO_MEM memory error Parameters · instance: instance name · service_type: service type (_http, _ftp, etc) · proto: service protocol (_tcp, _udp) · hostname: service hostname. If NULL, local hostname will be used. · key: the key that you want to add/update · value: the new value of the key

esp_err_t mdns_service_txt_item_set_for_host_with_explicit_value_len(const

char

*instance,

const

char

*service_type,

const

char

*proto,

const

char

*hostname,

const

char

*key,

const

char

*value,

uint8_t

Set/Add TXT item for service TXT record with hostname and txt value length.

value_len)

Espressif Systems

909

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return · ESP_OK success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NOT_FOUND Service not found · ESP_ERR_NO_MEM memory error
Parameters · instance: instance name · service_type: service type (_http, _ftp, etc) · proto: service protocol (_tcp, _udp) · hostname: service hostname. If NULL, local hostname will be used. · key: the key that you want to add/update · value: the new value of the key · value_len: the length of the value

esp_err_t mdns_service_txt_item_remove(const char *service_type, const char *proto, const char *key)
Remove TXT item for service TXT record.

Return · ESP_OK success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NOT_FOUND Service not found · ESP_ERR_NO_MEM memory error
Parameters · service_type: service type (_http, _ftp, etc) · proto: service protocol (_tcp, _udp) · key: the key that you want to remove

esp_err_t mdns_service_txt_item_remove_for_host(const char *instance, const char *service_type, const char *proto, const char *hostname, const char *key)
Remove TXT item for service TXT record with hostname.

Return · ESP_OK success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NOT_FOUND Service not found · ESP_ERR_NO_MEM memory error
Parameters · instance: instance name · service_type: service type (_http, _ftp, etc) · proto: service protocol (_tcp, _udp) · hostname: service hostname. If NULL, local hostname will be used. · key: the key that you want to remove

esp_err_t mdns_service_subtype_add_for_host(const char *instance_name, const char

*service_type, const char *proto, const char

Add subtype for service.

*hostname, const char *subtype)

Return · ESP_OK success · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NOT_FOUND Service not found · ESP_ERR_NO_MEM memory error
Parameters · instance_name: instance name. If NULL, will find the first service with the same service type and protocol. · service_type: service type (_http, _ftp, etc) · proto: service protocol (_tcp, _udp) · hostname: service hostname. If NULL, local hostname will be used.

Espressif Systems

910

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· subtype: The subtype to add.
esp_err_t mdns_service_remove_all(void) Remove and free all services from mDNS server.
Return · ESP_OK success · ESP_ERR_INVALID_ARG Parameter error
esp_err_t mdns_query_async_delete(mdns_search_once_t *search) Deletes the finished query. Call this only after the search has ended!
Return · ESP_OK success · ESP_ERR_INVALID_STATE search has not finished · ESP_ERR_INVALID_ARG pointer to search object is NULL
Parameters · search: pointer to search object
bool mdns_query_async_get_results(mdns_search_once_t *search, uint32_t timeout, mdns_result_t **results, uint8_t *num_results)
Get results from search pointer. Results available as a pointer to the output parameter. Pointer to search object has to be deleted via mdns_query_async_delete once the query has finished. The results although have to be freed manually.
Return True if search has finished before or at timeout False if search timeout is over Parameters
· search: pointer to search object · timeout: time in milliseconds to wait for answers · results: pointer to the results of the query · num_results: pointer to the number of the actual result items (set to NULL to ignore this return
value)
mdns_search_once_t *mdns_query_async_new(const char *name, const char *service_type, const char *proto, uint16_t type, uint32_t timeout, size_t max_results, mdns_query_notify_t notifier)
Query mDNS for host or service asynchronousely. Search has to be tested for progress and deleted manually!
Return mdns_search_once_s pointer to new search object if query initiated successfully. NULL otherwise. Parameters
· name: service instance or host name (NULL for PTR queries) · service_type: service type (_http, _arduino, _ftp etc.) (NULL for host queries) · proto: service protocol (_tcp, _udp, etc.) (NULL for host queries) · type: type of query (MDNS_TYPE_*) · timeout: time in milliseconds during which mDNS query is active · max_results: maximum results to be collected · notifier: Notification function to be called when the result is ready, can be NULL
esp_err_t mdns_query_generic(const char *name, const char *service_type, const char *proto, uint16_t type, mdns_query_transmission_type_t transmission_type, uint32_t timeout, size_t max_results, mdns_result_t **results)
Generic mDNS query All following query methods are derived from this one.
Return · ESP_OK success · ESP_ERR_INVALID_STATE mDNS is not running · ESP_ERR_NO_MEM memory error · ESP_ERR_INVALID_ARG timeout was not given
Parameters · name: service instance or host name (NULL for PTR queries) · service_type: service type (_http, _arduino, _ftp etc.) (NULL for host queries) · proto: service protocol (_tcp, _udp, etc.) (NULL for host queries) · type: type of query (MDNS_TYPE_*) · transmission_type: either Unicast query, or Multicast query

Espressif Systems

911

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· timeout: time in milliseconds to wait for answers. · max_results: maximum results to be collected · results: pointer to the results of the query results must be freed using mdns_query_results_free
below
esp_err_t mdns_query(const char *name, const char *service_type, const char *proto, uint16_t type, uint32_t timeout, size_t max_results, mdns_result_t **results)
Query mDNS for host or service.
Note that querying PTR types sends Multicast query, all other types send Unicast queries
Return · ESP_OK success · ESP_ERR_INVALID_STATE mDNS is not running · ESP_ERR_NO_MEM memory error · ESP_ERR_INVALID_ARG timeout was not given
Parameters · name: service instance or host name (NULL for PTR queries) · service_type: service type (_http, _arduino, _ftp etc.) (NULL for host queries) · proto: service protocol (_tcp, _udp, etc.) (NULL for host queries) · type: type of query (MDNS_TYPE_*) · timeout: time in milliseconds to wait for answers. · max_results: maximum results to be collected · results: pointer to the results of the query results must be freed using mdns_query_results_free below
void mdns_query_results_free(mdns_result_t *results) Free query results.
Parameters · results: linked list of results to be freed
esp_err_t mdns_query_ptr(const char *service_type, const char *proto, uint32_t timeout, size_t max_results, mdns_result_t **results)
Query mDNS for service.
Return · ESP_OK success · ESP_ERR_INVALID_STATE mDNS is not running · ESP_ERR_NO_MEM memory error · ESP_ERR_INVALID_ARG parameter error
Parameters · service_type: service type (_http, _arduino, _ftp etc.) · proto: service protocol (_tcp, _udp, etc.) · timeout: time in milliseconds to wait for answer. · max_results: maximum results to be collected · results: pointer to the results of the query
esp_err_t mdns_query_srv(const char *instance_name, const char *service_type, const char *proto, uint32_t timeout, mdns_result_t **result)
Query mDNS for SRV record.
Return · ESP_OK success · ESP_ERR_INVALID_STATE mDNS is not running · ESP_ERR_NO_MEM memory error · ESP_ERR_INVALID_ARG parameter error
Parameters · instance_name: service instance name · service_type: service type (_http, _arduino, _ftp etc.) · proto: service protocol (_tcp, _udp, etc.) · timeout: time in milliseconds to wait for answer. · result: pointer to the result of the query

Espressif Systems

912

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
esp_err_t mdns_query_txt(const char *instance_name, const char *service_type, const char *proto, uint32_t timeout, mdns_result_t **result)
Query mDNS for TXT record.
Return · ESP_OK success · ESP_ERR_INVALID_STATE mDNS is not running · ESP_ERR_NO_MEM memory error · ESP_ERR_INVALID_ARG parameter error
Parameters · instance_name: service instance name · service_type: service type (_http, _arduino, _ftp etc.) · proto: service protocol (_tcp, _udp, etc.) · timeout: time in milliseconds to wait for answer. · result: pointer to the result of the query
esp_err_t mdns_query_a(const char *host_name, uint32_t timeout, esp_ip4_addr_t *addr) Query mDNS for A record.
Return · ESP_OK success · ESP_ERR_INVALID_STATE mDNS is not running · ESP_ERR_NO_MEM memory error · ESP_ERR_INVALID_ARG parameter error
Parameters · host_name: host name to look for · timeout: time in milliseconds to wait for answer. · addr: pointer to the resulting IP4 address
esp_err_t mdns_query_aaaa(const char *host_name, uint32_t timeout, esp_ip6_addr_t *addr) Query mDNS for A record.
Please note that hostname must not contain domain name, as mDNS uses m.localndomain.
Return · ESP_OK success · ESP_ERR_INVALID_STATE mDNS is not running · ESP_ERR_NO_MEM memory error · ESP_ERR_INVALID_ARG parameter error
Parameters · host_name: host name to look for · timeout: time in milliseconds to wait for answer. If 0, max_results needs to be defined · addr: pointer to the resulting IP6 address
esp_err_t mdns_handle_system_event(void *ctx, system_event_t *event) System event handler This method controls the service state on all active interfaces and applications are required to call it from the system event handler for normal operation of mDNS service.
Please note that hostname must not contain domain name, as mDNS uses m.localndomain.
Parameters · ctx: The system event context · event: The system event
Structures struct mdns_txt_item_t
mDNS basic text item structure Used in mdns_service_add()

Espressif Systems

913

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Public Members
const char *key item key name
const char *value item value string
struct mdns_ip_addr_s mDNS query linked list IP item
Public Members
esp_ip_addr_t addr IP address
struct mdns_ip_addr_s *next next IP, or NULL for the last IP in the list
struct mdns_result_s mDNS query result structure
Public Members
struct mdns_result_s *next next result, or NULL for the last result in the list
mdns_if_t tcpip_if interface index
uint32_t ttl time to live
mdns_ip_protocol_t ip_protocol ip_protocol type of the interface (v4/v6)
char *instance_name instance name
char *service_type service type
char *proto srevice protocol
char *hostname hostname
uint16_t port service port
mdns_txt_item_t *txt txt record
uint8_t *txt_value_len array of txt value len of each record
size_t txt_count number of txt items
mdns_ip_addr_t *addr linked list of IP addresses found

Espressif Systems

914

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Macros MDNS_TYPE_A MDNS_TYPE_PTR MDNS_TYPE_TXT MDNS_TYPE_AAAA MDNS_TYPE_SRV MDNS_TYPE_OPT MDNS_TYPE_NSEC MDNS_TYPE_ANY
Type Definitions typedef struct mdns_search_once_s mdns_search_once_t
Asynchronous query handle. typedef struct mdns_ip_addr_s mdns_ip_addr_t
mDNS query linked list IP item typedef enum mdns_if_internal mdns_if_t typedef struct mdns_result_s mdns_result_t
mDNS query result structure typedef void (*mdns_query_notify_t)(mdns_search_once_t *search)
Enumerations enum mdns_ip_protocol_t
mDNS enum to specify the ip_protocol type Values: MDNS_IP_PROTOCOL_V4 MDNS_IP_PROTOCOL_V6 MDNS_IP_PROTOCOL_MAX enum mdns_if_internal Values: MDNS_IF_STA = 0 MDNS_IF_AP = 1 MDNS_IF_ETH = 2 MDNS_IF_MAX enum mdns_query_transmission_type_t mDNS query type to be explicitly set to either Unicast or Multicast Values: MDNS_QUERY_UNICAST MDNS_QUERY_MULTICAST
2.4.11 ESP-Modbus
Overview
The Modbus serial communication protocol is de facto standard protocol widely used to connect industrial electronic devices. Modbus allows communication among many devices connected to the same network, for example, a system

Espressif Systems

915

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

that measures temperature and humidity and communicates the results to a computer. The Modbus protocol uses several types of data: Holding Registers, Input Registers, Coils (single bit output), Discrete Inputs. Versions of the Modbus protocol exist for serial port and for Ethernet and other protocols that support the Internet protocol suite. There are many variants of Modbus protocols, some of them are:
· Modbus RTU iThis is used in serial communication and makes use of a compact, binary representation of the data for protocol communication. The RTU format follows the commands/data with a cyclic redundancy check checksum as an error check mechanism to ensure the reliability of data. Modbus RTU is the most common implementation available for Modbus. A Modbus RTU message must be transmitted continuously without inter-character hesitations. Modbus messages are framed (separated) by idle (silent) periods. The RS-485 interface communication is usually used for this type.
· Modbus ASCII iThis is used in serial communication and makes use of ASCII characters for protocol communication. The ASCII format uses a longitudinal redundancy check checksum. Modbus ASCII messages are framed by leading colon (o:p) and trailing newline (CR/LF).
· Modbus TCP/IP or Modbus TCP iThis is a Modbus variant used for communications over TCP/IP networks, connecting over port 502. It does not require a checksum calculation, as lower layers already provide checksum protection.
The following document (and included code snippets) requires some familiarity with the Modbus protocol. Refer to the Modbus Organizationns with protocol specifications for specifics.
Messaging Model And Data Mapping
Modbus is an application protocol that defines rules for messaging structure and data organization that are independent of the data transmission medium. Traditional serial Modbus is a register-based protocol that defines message transactions that occur between master(s) and slave devices (multiple masters are allowed on using Modbus TCP/IP). The slave devices listen for communication from the master and simply respond as instructed. The master(s) always controls communication and may communicate directly to one slave, or all connected slaves, but the slaves cannot communicate directly with each other.
Note: It is assumed that the number of slaves and their register maps are known by the Modbus master before the start of stack.
The register map of each slave device is usually part of its device manual. A Slave device usually permits configuration of its short slave address and communication options that are used within the devicens network segment.
The Modbus protocol allows devices to map data to four types of registers (Holding, Input, Discrete, Coil). The figure below illustrates an example mapping of a devicens data to the four types of registers.
The following sections give an overview of how to use the ESP_Modbus component found under components/freemodbus. The sections cover initialization of a Modbus port, and the setup a master or slave device accordingly:
· Modbus Port Initialization · Modbus Slave API Overview · Modbus Master API Overview
Modbus Port Initialization The ESP_Modbus supports Modbus SERIAL and TCP ports and a port must be initialized before calling any other Modbus API. The functions below are used to create and then initialize Modbus controller interface (either master or slave) over a particular transmission medium (either Serial or TCP/IP):
· mbc_slave_init() · mbc_master_init() · mbc_slave_init_tcp() · mbc_master_init_tcp()
The API call uses the first parameter to recognize the type of port being initialized. Supported enumeration for different ports: MB_PORT_SERIAL_MASTER, MB_PORT_SERIAL_SLAVE accordingly. The parameters MB_PORT_TCP_MASTER, MB_PORT_TCP_SLAVE are reserved for internal usage.

Espressif Systems

916

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Fig. 24: Modbus segment diagram

Espressif Systems

Fig. 25: Modbus data mapping

917

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
void* master_handler = NULL; // Pointer to allocate interface structure // Initialization of Modbus master for serial port esp_err_t err = mbc_master_init(MB_PORT_SERIAL_MASTER, &master_handler); if (master_handler == NULL || err != ESP_OK) {
ESP_LOGE(TAG, "mb controller initialization fail."); }
This example code to initialize slave port:
void* slave_handler = NULL; // Pointer to allocate interface structure // Initialization of Modbus slave for TCP esp_err_t err = mbc_slave_init_tcp(&slave_handler); if (slave_handler == NULL || err != ESP_OK) {
// Error handling is performed here ESP_LOGE(TAG, "mb controller initialization fail."); }
Modbus Master API Overview
The following overview describes how to setup Modbus master communication. The overview reflects a typical programming workflow and is broken down into the sections provided below:
1. Modbus Port Initialization - Initialization of Modbus controller interface for the selected port. 2. Configuring Master Data Access - Configure data descriptors to access slave parameters. 3. Master Communication Options - Allows to setup communication options for selected port. 4. Master Communication - Start stack and sending / receiving data. 5. Modbus Master Teardown - Destroy Modbus controller and its resources.
Configuring Master Data Access The architectural approach of ESP_Modbus includes one level above standard Modbus IO driver. The additional layer is called Modbus controller and its goal is to add an abstraction such as CID - characteristic identifier. The CID is linked to a corresponding Modbus registers through the table called Data Dictionary and represents device physical parameter (such as temperature, humidity, etc.) in specific Modbus slave device. This approach allows the upper layer (e.g., MESH or MQTT) to be isolated from Modbus specifics thus simplify Modbus integration with other protocols/networks.
The Data Dictionary is the list in the Modbus master which shall be defined by user to link each CID to its corresponding Modbus registers representation using Register Mapping table of the Modbus slave being used. Each element in this data dictionary is of type mb_parameter_descriptor_t and represents the description of one physical characteristic:

Espressif Systems

918

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Table 8: Table 1 Modbus master Data Dictionary description

Field cid

DescriptionDetailed information CharacteristTiche identifier of characteristic (must be unique). ID

param_kCehayracteristSictring description of the characteristic. Name

param_uCnhairtacsteristPichysical Units of the characteristic. Units

mb_slavMeo_dabudsdr The short address of the device with correspond parameter UID. Slave Address

mb_paraMmo_dtbuyspe Type of Modbus register area. MB_PARAM_INPUT, MB_PARAM_HOLDING, Register MB_PARAM_COIL, MB_PARAM_DISCRETE - represents Input , Holding, Coil and Type Discrete input register area accordingly;
mb_reg_Msotdaburst Relative register address of the characteristic in the register area. Register Start

mb_sizeModbus Length of characteristic in registers. Register Size

param_oInfstfasnceet Offset to instance of the characteristic in bytes. It is used to calculate the absolute address Offset to the characteristic in the storage structure. It is optional field and can be set to zero if the parameter is not used in the application.

param_tDyatpae Type

Specifies type of the characteristic. PARAM_TYPE_U8, PARAM_TYPE_U16, PARAM_TYPE_U32 - Unsigned integer 8/16/32 bit type; PARAM_TYPE_FLOAT IEEE754 floating point format; PARAM_TYPE_ASCII - ASCII string or binary data;

param_sDiatzae The storage size of the characteristic (bytes). Size
param_oPaprtams eter Limits, options of characteristic used during processing of alarm in user application (optional) Options

accessParameter Can be used in user application to define the behavior of the characteristic dur-

access ing processing of data in user application; PAR_PERMS_READ_WRITE_TRIGGER,

type

PAR_PERMS_READ, PAR_PERMS_READ_WRITE_TRIGGER;

Note: The cid and param_key have to be unique. Please use the prefix to the parameter key if you have several similar parameters in your register map table.

Table 9: Table 2 Example Register mapping table of Modbus slave
CID RegisLternRgathnge TypeUnitsDescription 0 300004 MAX_UINUT32 Not Serial number of device (4 bytes) read-only
defined 1 300022 MAX_UINUT16 Not Software version (4 bytes) read-only defined 2 400004 -20..40 FLOADTegCRoom temperature in DegC. Writing a temperature value to this register for
single point calibration.

// Enumeration of modbus slave addresses accessed by master device enum {
MB_DEVICE_ADDR1 = 1, MB_DEVICE_ADDR2, MB_SLAVE_COUNT

(continues on next page)

Espressif Systems

919

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)
};
// Enumeration of all supported CIDs for device enum {
CID_SER_NUM1 = 0, CID_SW_VER1, CID_TEMP_DATA_1, CID_SER_NUM2, CID_SW_VER2, CID_TEMP_DATA_2 };
// Example Data Dictionary for Modbus parameters in 2 slaves in the segment mb_parameter_descriptor_t device_parameters[] = {
// CID, Name, Units, Modbus addr, register type, Modbus Reg Start Addr, Modbus Reg read length,
// Instance offset (NA), Instance type, Instance length (bytes), Options (NA), Permissions
{ CID_SER_NUM1, STR("Serial_number_1"), STR("--"), MB_DEVICE_ADDR1, MB_PARAM_ INPUT, 0, 2,
0, PARAM_TYPE_U32, 4, OPTS( 0,0,0 ), PAR_PERMS_READ_WRITE_ TRIGGER },
{ CID_SW_VER1, STR("Software_version_1"), STR("--"), MB_DEVICE_ADDR1, MB_PARAM_ INPUT, 2, 1,
0, PARAM_TYPE_U16, 2, OPTS( 0,0,0 ), PAR_PERMS_READ_WRITE_ TRIGGER },
{ CID_TEMP_DATA_1, STR("Temperature_1"), STR("C"), MB_DEVICE_ADDR1, MB_PARAM_ HOLDING, 0, 2,
0, PARAM_TYPE_FLOAT, 4, OPTS( 16, 30, 1 ), PAR_PERMS_READ_ WRITE_TRIGGER },
{ CID_SER_NUM2, STR("Serial_number_2"), STR("--"), MB_DEVICE_ADDR2, MB_PARAM_ INPUT, 0, 2,
0, PARAM_TYPE_U32, 4, OPTS( 0,0,0 ), PAR_PERMS_READ_WRITE_ TRIGGER },
{ CID_SW_VER2, STR("Software_version_2"), STR("--"), MB_DEVICE_ADDR2, MB_PARAM_ INPUT, 2, 1,
0, PARAM_TYPE_U16, 2, OPTS( 0,0,0 ), PAR_PERMS_READ_WRITE_ TRIGGER },
{ CID_TEMP_DATA_2, STR("Temperature_2"), STR("C"), MB_DEVICE_ADDR2, MB_PARAM_ HOLDING, 0, 2,
0, PARAM_TYPE_FLOAT, 4, OPTS( 20, 30, 1 ), PAR_PERMS_READ_ WRITE_TRIGGER }, }; // Calculate number of parameters in the table uint16_t num_device_parameters = (sizeof(device_parameters) / sizeof(device_ parameters[0]));
During initialization of the Modbus stack, a pointer to the Data Dictionary (called descriptor) must be provided as the parameter of the function below.
mbc_master_set_descriptor(): Initialization of master descriptor.
ESP_ERROR_CHECK(mbc_master_set_descriptor(&device_parameters[0], num_device_ parameters));
The Data Dictionary can be initialized from SD card, MQTT or other source before start of stack. Once the initialization and setup is done, the Modbus controller allows the reading of complex parameters from any slave included in descriptor table using its CID.

Master Communication Options Calling the setup function allows for specific communication options to be defined for port.

Espressif Systems

920

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

mbc_master_setup() The communication structure provided as a parameter is different for serial and TCP communication mode. Example setup for serial port:

mb_communication_info_t comm_info = {

.port = MB_PORT_NUM,

// Serial port number

.mode = MB_MODE_RTU,

// Modbus mode of communication (MB_MODE_RTU or MB_

MODE_ASCII)

.baudrate = 9600,

// Modbus communication baud rate

.parity = MB_PARITY_NONE // parity option for serial port

};

ESP_ERROR_CHECK(mbc_master_setup((void*)&comm_info));

Modbus master TCP port requires additional definition of IP address table where number of addresses should be equal to number of unique slave addresses in master Modbus Data Dictionary:
The order of IP address string corresponds to short slave address in the Data Dictionary.

#define MB_SLAVE_COUNT 2 // Number of slaves in the segment being accessed (as defined in Data Dictionary)

char* slave_ip_address_table[MB_SLAVE_COUNT] = {

"192.168.1.2",

// Address corresponds to UID1 and set to predefined value

by user

"192.168.1.3",

// corresponds to UID2 in the segment

NULL

// end of table

};

mb_communication_info_t comm_info = { .ip_port = MB_TCP_PORT,
= 502) .ip_addr_type = MB_IPV4, .ip_mode = MB_MODE_TCP, .ip_addr = (void*)slave_ip_address_table, .ip_netif_ptr = esp_netif_ptr
corresponding network interface };

// Modbus TCP port number (default
// version of IP protocol // Port communication mode // assign table of IP addresses // esp_netif_ptr pointer to the

ESP_ERROR_CHECK(mbc_master_setup((void*)&comm_info));

Note: Refer to esp_netif component for more information about network interface initialization.
The slave IP addresses in the table can be assigned automatically using mDNS service as described in the example. Refer to protocols/modbus/tcp/mb_tcp_master for more information.
Note: RS485 communication requires call to UART specific APIs to setup communication mode and pins. Refer to Running UART Communication section of UART documentation.

Master Communication The starting of the Modbus controller is the final step in enabling communication. This is performed using function below:
mbc_master_start()

esp_err_t err = mbc_master_start(); if (err != ESP_OK) {

(continues on next page)

Espressif Systems

921

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_LOGE(TAG, "mb controller start fail, err=%x.", err); }

(continued from previous page)

The list of functions below are used by the Modbus master stack from a userns application:
mbc_master_send_request(): This function executes a blocking Modbus request. The master sends a data request (as defined in parameter request structure mb_param_request_t) and then blocks until a response from corresponding slave and returns the status of command execution. This function provides a standard way for read/write access to Modbus devices in the network.
mbc_master_get_cid_info(): The function gets information about each characteristic supported in the data dictionary and returns the characteristicns description in the form of the mb_parameter_descriptor_t structure. Each characteristic is accessed using its CID.
mbc_master_get_parameter(): The function reads the data of a characteristic defined in the parameters of a Modbus slave device. The additional data for request is taken from parameter description table.
Example:
const mb_parameter_descriptor_t* param_descriptor = NULL; uint8_t temp_data[4] = {0}; // temporary buffer to hold maximum CID size uint8_t type = 0; ....
// Get the information for characteristic cid from data dictionary esp_err_t err = mbc_master_get_cid_info(cid, &param_descriptor); if ((err != ESP_ERR_NOT_FOUND) && (param_descriptor != NULL)) {
err = mbc_master_get_parameter(param_descriptor->cid, (char*)param_descriptor-> param_key, (uint8_t*)temp_data, &type);
if (err == ESP_OK) { ESP_LOGI(TAG, "Characteristic #%d %s (%s) value = (0x%08x) read successful.
", param_descriptor->cid, (char*)param_descriptor->param_key, (char*)param_descriptor->param_units, *(uint32_t*)temp_data);
} else { ESP_LOGE(TAG, "Characteristic #%d (%s) read fail, err = 0x%x (%s).", param_descriptor->cid, (char*)param_descriptor->param_key, (int)err, (char*)esp_err_to_name(err));
} } else {
ESP_LOGE(TAG, "Could not get information for characteristic %d.", cid); }

mbc_master_set_parameter()
The function writes characteristicns value defined as a name and cid parameter in corresponded slave device. The additional data for parameter request is taken from master parameter description table.
uint8_t type = 0; // Type of parameter uint8_t temp_data[4] = {0}; // temporary buffer
esp_err_t err = mbc_master_set_parameter(CID_TEMP_DATA_2, "Temperature_2", (uint8_ t*)temp_data, &type); if (err == ESP_OK) {
ESP_LOGI(TAG, "Set parameter data successfully."); } else {
ESP_LOGE(TAG, "Set data fail, err = 0x%x (%s).", (int)err, (char*)esp_err_to_ name(err)); }

Espressif Systems

922

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Modbus Master Teardown This function stops Modbus communication stack and destroys controller interface and free all used active objects. mbc_master_destroy()
ESP_ERROR_CHECK(mbc_master_destroy());

Modbus Slave API Overview
The sections below represent typical programming workflow for the slave API which should be called in following order:
1. Modbus Port Initialization - Initialization of Modbus controller interface for the selected port. 2. Configuring Slave Data Access - Configure data descriptors to access slave parameters. 3. Slave Communication Options - Allows to setup communication options for selected port. 4. Slave Communication - Start stack and sending / receiving data. Filter events when master accesses the register
areas. 5. Modbus Slave Teardown - Destroy Modbus controller and its resources.

Configuring Slave Data Access The following functions must be called when the Modbus controller slave port is already initialized. Refer to Modbus Port Initialization.
The slave stack requires the user to define structures (memory storage areas) that store the Modbus parameters accessed by stack. These structures should be prepared by the user and be assigned to the Modbus controller interface using mbc_slave_set_descriptor() API call before the start of communication. The slave task can call the mbc_slave_check_event() function which will block until the Modbus master access the slave. The slave task can then get information about the data being accessed.

Note: One slave can define several area descriptors per each type of Modbus register area with different start_offset.

Register area is defined by using the mb_register_area_descriptor_t structure.

Table 10: Table 3 Modbus register area descriptor
Field Description start_oZferfosbeatsed register relative offset for defined register area. Example: register address = 40002 ( 4x
register area - Function 3 - holding register ), start_offset = 2 type Type of the Modbus register area. Refer to mb_param_type_t for more information. addressA pointer to the memory area which is used to store the register data for this area descriptor. size The size of the memory area in bytes which is used to store register data.

mbc_slave_set_descriptor()

The function initializes Modbus communication descriptors for each type of Modbus register area (Holding Registers, Input Registers, Coils (single bit output), Discrete Inputs). Once areas are initialized and the mbc_slave_start() API is called the Modbus stack can access the data in user data structures by request from master.

#define MB_REG_INPUT_START_AREA0 #define MB_REG_HOLDING_START_AREA0 #define MB_REG_HOLD_CNT #define MB_REG_INPUT_CNT

(0) (0) (100) (100)

mb_register_area_descriptor_t reg_area; // Modbus register area descriptor

structure

unit16_t holding_reg_area[MB_REG_HOLD_CNT] = {0}; // storage area for holding

registers

unit16_t input_reg_area[MB_REG_INPUT_CNT] = {0}; // storage area for input

registers

(continues on next page)

Espressif Systems

923

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)

reg_area.type = MB_PARAM_HOLDING; register area reg_area.start_offset = MB_REG_HOLDING_START_AREA0; register area in Modbus protocol reg_area.address = (void*)&holding_reg_area[0]; storage instance reg_area.size = sizeof(holding_reg_area) << 1; register storage area in bytes ESP_ERROR_CHECK(mbc_slave_set_descriptor(reg_area));
reg_area.type = MB_PARAM_INPUT; reg_area.start_offset = MB_REG_INPUT_START_AREA0; reg_area.address = (void*)&input_reg_area[0]; reg_area.size = sizeof(input_reg_area) << 1; ESP_ERROR_CHECK(mbc_slave_set_descriptor(reg_area));

// Set type of // Offset of // Set pointer to // Set the size of

At least one area descriptor per each Modbus register type must be set in order to provide register access to its area. If the master tries to access an undefined area, the stack will generate a Modbus exception.
Direct access to register area from user application must be protected by critical section:
portENTER_CRITICAL(&param_lock); holding_reg_area[2] += 10; portEXIT_CRITICAL(&param_lock);

Slave Communication Options The function initializes the Modbus controller interface and its active context (tasks, RTOS objects and other resources). mbc_slave_setup() The function is used to setup communication parameters of the Modbus stack. Example initialization of Modbus TCP communication:

esp_netif_init(); ...

mb_communication_info_t comm_info = { .ip_port = MB_TCP_PORT,
= 502) .ip_addr_type = MB_IPV4, .ip_mode = MB_MODE_TCP, .ip_addr = NULL,
address to bind, NULL - bind to any client .ip_netif_ptr = esp_netif_ptr
corresponding network interface };

// Modbus TCP port number (default
// version of IP protocol // Port communication mode // This field keeps the client IP
// esp_netif_ptr - pointer to the

// Setup communication parameters and start stack ESP_ERROR_CHECK(mbc_slave_setup((void*)&comm_info));

Example initialization of Modbus serial communication:
#define MB_SLAVE_DEV_SPEED 9600 #define MB_SLAVE_ADDR 1 #define MB_SLAVE_PORT_NUM 2 ...
// Setup communication parameters and start stack mb_communication_info_t comm_info = {

(continues on next page)

Espressif Systems

924

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

.mode = MB_MODE_RTU, .slave_addr = MB_SLAVE_ADDR, .port = MB_SLAVE_PORT_NUM, .baudrate = MB_SLAVE_DEV_SPEED, .parity = MB_PARITY_NONE };

(continued from previous page)
// Communication type // Short address of the slave // UART physical port number // Baud rate for communication // Parity option

ESP_ERROR_CHECK(mbc_slave_setup((void*)&comm_info));

Slave Communication The function below is used to start Modbus controller interface and allows communication. mbc_slave_start() ESP_ERROR_CHECK(mbc_slave_start());

mbc_slave_check_event()
The blocking call to function waits for a event specified (represented as an event mask parameter). Once the master accesses the parameter and the event mask matches the parameter type, the application task will be unblocked and function will return the corresponding event mb_event_group_t which describes the type of register access being done.
mbc_slave_get_param_info()
The function gets information about accessed parameters from the Modbus controller event queue. The KConfig CONFIG_FMB_CONTROLLER_NOTIFY_QUEUE_SIZE key can be used to configure the notification queue size. The timeout parameter allows a timeout to be specified when waiting for a notification. The mb_param_info_t structure contains information about accessed parameter.

Table 11: Table 4 Description of the register info structure: mb_param_info_t
Field Description time_statmheptime stamp of the event when defined parameter is accessed mb_offsesttart Modbus register accessed by master type type of the Modbus register area being accessed (See the mb_event_group_t for more informa-
tion) address memory address that corresponds to accessed register in defined area descriptor size number of registers being accessed by master

Example to get event when holding or input registers accessed in the slave:

#define MB_READ_MASK #define MB_WRITE_MASK #define MB_READ_WRITE_MASK #define MB_PAR_INFO_GET_TOUT ....

(MB_EVENT_INPUT_REG_RD | MB_EVENT_HOLDING_REG_RD) (MB_EVENT_HOLDING_REG_WR) (MB_READ_MASK | MB_WRITE_MASK) (10 / portTICK_RATE_MS)

// The function blocks while waiting for register access mb_event_group_t event = mbc_slave_check_event(MB_READ_WRITE_MASK);

// Get information about data accessed from master ESP_ERROR_CHECK(mbc_slave_get_param_info(&reg_info, MB_PAR_INFO_GET_TOUT)); const char* rw_str = (event & MB_READ_MASK) ? "READ" : "WRITE";

// Filter events and process them accordingly if (event & (MB_EVENT_HOLDING_REG_WR | MB_EVENT_HOLDING_REG_RD)) {
ESP_LOGI(TAG, "HOLDING %s (%u us), ADDR:%u, TYPE:%u, INST_ADDR:0x%.4x, SIZE:%u ",
rw_str,
(continues on next page)

Espressif Systems

925

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
(continued from previous page) (uint32_t)reg_info.time_stamp, (uint32_t)reg_info.mb_offset, (uint32_t)reg_info.type, (uint32_t)reg_info.address, (uint32_t)reg_info.size); } else if (event & (MB_EVENT_INPUT_REG_RD)) { ESP_LOGI(TAG, "INPUT %s (%u us), ADDR:%u, TYPE:%u, INST_ADDR:0x%.4x, SIZE:%u", rw_str, (uint32_t)reg_info.time_stamp, (uint32_t)reg_info.mb_offset, (uint32_t)reg_info.type, (uint32_t)reg_info.address, (uint32_t)reg_info.size); }
Modbus Slave Teardown This function stops the Modbus communication stack, destroys the controller interface, and frees all used active objects allocated for the slave. mbc_slave_destroy()
ESP_ERROR_CHECK(mbc_slave_destroy());
Possible Communication Issues And Solutions
If the examples do not work as expected and slave and master boards are not able to communicate correctly, it is possible to find the reason for errors. The most important errors are described in master example output and formatted as below:
E (1692332) MB_CONTROLLER_MASTER: mbc_master_get_parameter(111): SERIAL master get parameter failure error=(0x107) (ESP_ERR_TIMEOUT).

Espressif Systems

926

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Table 12: Table 5 Modbus error codes and troubleshooting

Error Description 0x106ESP_ERR_NOT_SUPPORTED
- Invalid register request - slave returned an exception because the requested register is not supported.

Possible solution Refer to slave register map. Check the master data dictionary for correctness.

0x107ESP_ERR_TIMEOUT - Slave response timeout - Modbus slave did not send response during configured slave response timeout.

Measure and increase the maximum slave response timeout idf.py menuconfig, option CONFIG_FMB_MASTER_TIMEOUT_MS_RESPOND. Check physical connection or network configuration and make sure that the slave response can reach the master side. If the application has some high performance tasks with higher priority than CONFIG_FMB_PORT_TASK_PRIO it is recommended to place Modbus tasks on the other core using an option CONFIG_FMB_PORT_TASK_AFFINITY. Configure the Modbus taskns priority CONFIG_FMB_PORT_TASK_PRIO to ensure that the task gets sufficient processing time to handle Modbus stack events.

0x108ESP_ERR_INVALID_RESPONSCEheck the physical connection then refer to register map of your slave to - Received unsupported re- configure the master data dictionary properly. sponse from slave or frame check failure. Master can not execute command handler because the command is either not supported or is incorrect.

0x103ESP_ERR_INVALID_STATE - Critical failure or FSM sequence failure or master FSM is busy processing previous request.

Make sure your physical connection is working properly. Increase task stack size and check Modbus initialization sequence.

Application Example
The examples below use the FreeModbus library port for serial TCP slave and master implementations accordingly. The selection of stack is performed through KConfig menu optionoEnable Modbus stack support lpfor appropriate communication mode and related configuration keys.
· protocols/modbus/serial/mb_slave · protocols/modbus/serial/mb_master · protocols/modbus/tcp/mb_tcp_slave · protocols/modbus/tcp/mb_tcp_master Please refer to the specific example README.md for details.
Protocol References
· https://modbus.org/specs.php: Modbus Organization with protocol specifications.
API Reference
Header File · components/freemodbus/common/include/esp_modbus_common.h
Unions

Espressif Systems

927

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
union mb_communication_info_t #include <esp_modbus_common.h> Device communication structure to setup Modbus controller.
Public Members
mb_mode_type_t mode Modbus communication mode
uint8_t slave_addr Modbus slave address field (dummy for master)
uart_port_t port Modbus communication port (UART) number
uint32_t baudrate Modbus baudrate
uart_parity_t parity Modbus UART parity settings
uint16_t dummy_port Dummy field, unused
struct mb_communication_info_t::[anonymous] [anonymous] mb_mode_type_t ip_mode
Modbus communication mode uint16_t ip_port
Modbus port mb_tcp_addr_type_t ip_addr_type
Modbus address type void *ip_addr
Modbus address table for connection void *ip_netif_ptr
Modbus network interface struct mb_communication_info_t::[anonymous] [anonymous]
Macros MB_RETURN_ON_FALSE(a, err_code, tag, format, ...) MB_CONTROLLER_STACK_SIZE MB_CONTROLLER_PRIORITY MB_DEVICE_ADDRESS MB_DEVICE_SPEED MB_UART_PORT MB_PAR_INFO_TOUT MB_PARITY_NONE _XFER_4_RD(dst, src) _XFER_2_RD(dst, src) _XFER_4_WR(dst, src) _XFER_2_WR(dst, src)

Espressif Systems

928

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Type Definitions typedef esp_err_t (*iface_init)(void **)
common interface method types Interface method init typedef esp_err_t (*iface_destroy)(void)
Interface method destroy
typedef esp_err_t (*iface_setup)(void *) Interface method setup
typedef esp_err_t (*iface_start)(void) Interface method start
Enumerations enum mb_port_type_t
Types of actual Modbus implementation.
Values:
MB_PORT_SERIAL_MASTER = 0x00 Modbus port type serial master.
MB_PORT_SERIAL_SLAVE Modbus port type serial slave.
MB_PORT_TCP_MASTER Modbus port type TCP master.
MB_PORT_TCP_SLAVE Modbus port type TCP slave.
MB_PORT_COUNT Modbus port count.
MB_PORT_INACTIVE = 0xFF enum mb_event_group_t
Event group for parameters notification.
Values:
MB_EVENT_NO_EVENTS = 0x00
MB_EVENT_HOLDING_REG_WR = BIT0 Modbus Event Write Holding registers.
MB_EVENT_HOLDING_REG_RD = BIT1 Modbus Event Read Holding registers.
MB_EVENT_INPUT_REG_RD = BIT3 Modbus Event Read Input registers.
MB_EVENT_COILS_WR = BIT4 Modbus Event Write Coils.
MB_EVENT_COILS_RD = BIT5 Modbus Event Read Coils.
MB_EVENT_DISCRETE_RD = BIT6 Modbus Event Read Discrete bits.
MB_EVENT_STACK_STARTED = BIT7 Modbus Event Stack started
enum mb_param_type_t Type of Modbus parameter.
Values:

Espressif Systems

929

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

MB_PARAM_HOLDING = 0x00 Modbus Holding register.
MB_PARAM_INPUT Modbus Input register.
MB_PARAM_COIL Modbus Coils.
MB_PARAM_DISCRETE Modbus Discrete bits.
MB_PARAM_COUNT
MB_PARAM_UNKNOWN = 0xFF
enum mb_mode_type_t Modbus serial transmission modes (RTU/ASCII).
Values:
MB_MODE_RTU RTU transmission mode.
MB_MODE_ASCII ASCII transmission mode.
MB_MODE_TCP TCP communication mode.
MB_MODE_UDP UDP communication mode.
enum mb_tcp_addr_type_t Modbus TCP type of address.
Values:
MB_IPV4 = 0 TCP IPV4 addressing
MB_IPV6 = 1 TCP IPV6 addressing

Header File · components/freemodbus/common/include/esp_modbus_master.h

Functions esp_err_t mbc_master_init_tcp(void **handler)
Initialize Modbus controller and stack for TCP port.
Return · ESP_OK Success · ESP_ERR_NO_MEM Parameter error · ESP_ERR_NOT_SUPPORTED Port type not supported · ESP_ERR_INVALID_STATE Initialization failure
Parameters · [out] handler: handler(pointer) to master data structure
esp_err_t mbc_master_init(mb_port_type_t port_type, void **handler) Initialize Modbus Master controller and stack for Serial port.
Return · ESP_OK Success · ESP_ERR_NO_MEM Parameter error · ESP_ERR_NOT_SUPPORTED Port type not supported

Espressif Systems

930

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· ESP_ERR_INVALID_STATE Initialization failure Parameters
· [out] handler: handler(pointer) to master data structure · [in] port_type: type of stack
void mbc_master_init_iface(void *handler) Initialize Modbus Master controller interface handle.
Parameters · [in] handler: - pointer to master data structure
esp_err_t mbc_master_destroy(void) Destroy Modbus controller and stack.
Return · ESP_OK Success · ESP_ERR_INVALID_STATE Parameter error
esp_err_t mbc_master_start(void) Start Modbus communication stack.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Modbus stack start error
esp_err_t mbc_master_setup(void *comm_info) Set Modbus communication parameters for the controller.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Incorrect parameter data
Parameters · comm_info: Communication parameters structure.
esp_err_t mbc_master_set_descriptor(const mb_parameter_descriptor_t *descriptor, const uint16_t num_elements)
Assign parameter description table for Modbus controller interface.
Return · esp_err_t ESP_OK - set descriptor successfully · esp_err_t ESP_ERR_INVALID_ARG - invalid argument in function call
Parameters · [in] descriptor: pointer to parameter description table · num_elements: number of elements in the table
esp_err_t mbc_master_send_request(mb_param_request_t *request, void *data_ptr) Send data request as defined in parameter request, waits response from slave and returns status of command execution. This function provides standard way for read/write access to Modbus devices in the network.
Return · esp_err_t ESP_OK - request was successful · esp_err_t ESP_ERR_INVALID_ARG - invalid argument of function · esp_err_t ESP_ERR_INVALID_RESPONSE - an invalid response from slave · esp_err_t ESP_ERR_TIMEOUT - operation timeout or no response from slave · esp_err_t ESP_ERR_NOT_SUPPORTED - the request command is not supported by slave · esp_err_t ESP_FAIL - slave returned an exception or other failure
Parameters · [in] request: pointer to request structure of type mb_param_request_t · [in] data_ptr: pointer to data buffer to send or received data (dependent of command field in request)
esp_err_t mbc_master_get_cid_info(uint16_t cid, const mb_parameter_descriptor_t **param_info)
Get information about supported characteristic defined as cid. Uses parameter description table to get this

Espressif Systems

931

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
information. The function will check if characteristic defined as a cid parameter is supported and returns its description in param_info. Returns ESP_ERR_NOT_FOUND if characteristic is not supported.
Return · esp_err_t ESP_OK - request was successful and buffer contains the supported characteristic name · esp_err_t ESP_ERR_INVALID_ARG - invalid argument of function · esp_err_t ESP_ERR_NOT_FOUND - the characteristic (cid) not found · esp_err_t ESP_FAIL - unknown error during lookup table processing
Parameters · [in] cid: characteristic id · param_info: pointer to pointer of characteristic data.
esp_err_t mbc_master_get_parameter(uint16_t cid, char *name, uint8_t *value, uint8_t *type) Read parameter from modbus slave device whose name is defined by name and has cid. The additional data for request is taken from parameter description (lookup) table.
Return · esp_err_t ESP_OK - request was successful and value buffer contains representation of actual parameter data from slave · esp_err_t ESP_ERR_INVALID_ARG - invalid argument of function or parameter descriptor · esp_err_t ESP_ERR_INVALID_RESPONSE - an invalid response from slave · esp_err_t ESP_ERR_INVALID_STATE - invalid state during data processing or allocation failure · esp_err_t ESP_ERR_TIMEOUT - operation timed out and no response from slave · esp_err_t ESP_ERR_NOT_SUPPORTED - the request command is not supported by slave · esp_err_t ESP_ERR_NOT_FOUND - the parameter is not found in the parameter description table · esp_err_t ESP_FAIL - slave returned an exception or other failure
Parameters · [in] cid: id of the characteristic for parameter · [in] name: pointer into string name (key) of parameter (null terminated) · [out] value: pointer to data buffer of parameter · [out] type: parameter type associated with the name returned from parameter description table.
esp_err_t mbc_master_set_parameter(uint16_t cid, char *name, uint8_t *value, uint8_t *type) Set characteristicns value defined as a name and cid parameter. The additional data for cid parameter request is taken from master parameter lookup table.
Return · esp_err_t ESP_OK - request was successful and value was saved in the slave device registers · esp_err_t ESP_ERR_INVALID_ARG - invalid argument of function or parameter descriptor · esp_err_t ESP_ERR_INVALID_RESPONSE - an invalid response from slave during processing of parameter · esp_err_t ESP_ERR_INVALID_STATE - invalid state during data processing or allocation failure · esp_err_t ESP_ERR_TIMEOUT - operation timed out and no response from slave · esp_err_t ESP_ERR_NOT_SUPPORTED - the request command is not supported by slave · esp_err_t ESP_FAIL - slave returned an exception or other failure
Parameters · [in] cid: id of the characteristic for parameter · [in] name: pointer into string name (key) of parameter (null terminated) · [out] value: pointer to data buffer of parameter (actual representation of json value field in binary form) · [out] type: pointer to parameter type associated with the name returned from parameter lookup table.
Unions union mb_parameter_opt_t
#include <esp_modbus_master.h> Modbus parameter options for description table.

Espressif Systems

932

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Public Members
int opt1 Parameter option1
int opt2 Parameter option2
int opt3 Parameter option3
struct mb_parameter_opt_t::[anonymous] [anonymous]
int min Parameter minimum value
int max Parameter maximum value
int step Step of parameter change tracking
struct mb_parameter_opt_t::[anonymous] [anonymous]

Structures struct mb_parameter_descriptor_t
Characteristics descriptor type is used to describe characteristic and link it with Modbus parameters that reflect its data.

Public Members
uint16_t cid Characteristic cid
const char *param_key The key (name) of the parameter
const char *param_units The physical units of the parameter
uint8_t mb_slave_addr Slave address of device in the Modbus segment
mb_param_type_t mb_param_type Type of modbus parameter
uint16_t mb_reg_start This is the Modbus register address. This is the 0 based value.
uint16_t mb_size Size of mb parameter in registers
uint16_t param_offset Parameter name (OFFSET in the parameter structure)
mb_descr_type_t param_type Float, U8, U16, U32, ASCII, etc.
mb_descr_size_t param_size Number of bytes in the parameter.
mb_parameter_opt_t param_opts Parameter options used to check limits and etc.
mb_param_perms_t access Access permissions based on mode

Espressif Systems

933

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
struct mb_param_request_t Modbus register request type structure.
Public Members
uint8_t slave_addr Modbus slave address
uint8_t command Modbus command to send
uint16_t reg_start Modbus start register
uint16_t reg_size Modbus number of registers
Macros MB_MASTER_CHECK(a, err_code, format, ...) MB_MASTER_ASSERT(con)
Enumerations enum mb_descr_type_t
Modbus descriptor table parameter type defines. Values: PARAM_TYPE_U8 = 0x00
Unsigned 8 PARAM_TYPE_U16 = 0x01
Unsigned 16 PARAM_TYPE_U32 = 0x02
Unsigned 32 PARAM_TYPE_FLOAT = 0x03
Float type PARAM_TYPE_ASCII = 0x04
ASCII type enum mb_descr_size_t
Modbus descriptor table parameter size in bytes. Values: PARAM_SIZE_U8 = 0x01
Unsigned 8 PARAM_SIZE_U16 = 0x02
Unsigned 16 PARAM_SIZE_U32 = 0x04
Unsigned 32 PARAM_SIZE_FLOAT = 0x04
Float size PARAM_SIZE_ASCII = 0x08
ASCII size PARAM_SIZE_ASCII24 = 0x18
ASCII24 size

Espressif Systems

934

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

PARAM_MAX_SIZE
enum mb_param_perms_t Permissions for the characteristics.
Values:
PAR_PERMS_READ = 1 << BIT0 the characteristic of the device are readable
PAR_PERMS_WRITE = 1 << BIT1 the characteristic of the device are writable
PAR_PERMS_TRIGGER = 1 << BIT2 the characteristic of the device are triggerable
PAR_PERMS_READ_WRITE = PAR_PERMS_READ | PAR_PERMS_WRITE the characteristic of the device are readable & writable
PAR_PERMS_READ_TRIGGER = PAR_PERMS_READ | PAR_PERMS_TRIGGER the characteristic of the device are readable & triggerable
PAR_PERMS_WRITE_TRIGGER = PAR_PERMS_WRITE | PAR_PERMS_TRIGGER the characteristic of the device are writable & triggerable
PAR_PERMS_READ_WRITE_TRIGGER = PAR_PERMS_READ_WRITE | PAR_PERMS_TRIGGER the characteristic of the device are readable & writable & triggerable

Header File · components/freemodbus/common/include/esp_modbus_slave.h

Functions esp_err_t mbc_slave_init_tcp(void **handler)
Initialize Modbus Slave controller and stack for TCP port.
Return · ESP_OK Success · ESP_ERR_NO_MEM Parameter error · ESP_ERR_NOT_SUPPORTED Port type not supported · ESP_ERR_INVALID_STATE Initialization failure
Parameters · [out] handler: handler(pointer) to master data structure
esp_err_t mbc_slave_init(mb_port_type_t port_type, void **handler) Initialize Modbus Slave controller and stack for Serial port.
Return · ESP_OK Success · ESP_ERR_NO_MEM Parameter error · ESP_ERR_NOT_SUPPORTED Port type not supported · ESP_ERR_INVALID_STATE Initialization failure
Parameters · [out] handler: handler(pointer) to master data structure · [in] port_type: the type of port
void mbc_slave_init_iface(void *handler) Initialize Modbus Slave controller interface handle.
Parameters · [in] handler: - pointer to slave interface data structure
esp_err_t mbc_slave_destroy(void) Destroy Modbus controller and stack.
Return

Espressif Systems

935

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_OK Success · ESP_ERR_INVALID_STATE Parameter error
esp_err_t mbc_slave_start(void) Start Modbus communication stack.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Modbus stack start error
esp_err_t mbc_slave_setup(void *comm_info) Set Modbus communication parameters for the controller.
Return · ESP_OK Success · ESP_ERR_INVALID_ARG Incorrect parameter data
Parameters · comm_info: Communication parameters structure.
mb_event_group_t mbc_slave_check_event(mb_event_group_t group) Wait for specific event on parameter change.
Return · mb_event_group_t event bits triggered
Parameters · group: Group event bit mask to wait for change
esp_err_t mbc_slave_get_param_info(mb_param_info_t *reg_info, uint32_t timeout) Get parameter information.
Return · ESP_OK Success · ESP_ERR_TIMEOUT Can not get data from parameter queue or queue overflow
Parameters · [out] reg_info: parameter info structure · timeout: Timeout in milliseconds to read information from parameter queue
esp_err_t mbc_slave_set_descriptor(mb_register_area_descriptor_t descr_data) Set Modbus area descriptor.
Return · ESP_OK: The appropriate descriptor is set · ESP_ERR_INVALID_ARG: The argument is incorrect
Parameters · descr_data: Modbus registers area descriptor structure
Structures struct mb_param_info_t
Parameter access event information type.
Public Members
uint32_t time_stamp Timestamp of Modbus Event (uS)
uint16_t mb_offset Modbus register offset
mb_event_group_t type Modbus event type
uint8_t *address Modbus data storage address

Espressif Systems

936

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

size_t size Modbus event register size (number of registers)
struct mb_register_area_descriptor_t Parameter storage area descriptor.

Public Members
uint16_t start_offset Modbus start address for area descriptor
mb_param_type_t type Type of storage area descriptor
void *address Instance address for storage area descriptor
size_t size Instance size for area descriptor (bytes)

Macros MB_SLAVE_CHECK(a, err_code, format, ...) MB_SLAVE_ASSERT(con)

2.4.12 ESP WebSocket Client
Overview The ESP WebSocket client is an implementation of WebSocket protocol client for ESP32-S3

Features
· Supports WebSocket over TCP, TLS with mbedtls · Easy to setup with URI · Multiple instances (Multiple clients in one application)

Configuration
URI · Supports ws, wss schemes · WebSocket samples: ­ ws://echo.websocket.org: WebSocket over TCP, default port 80 ­ wss://echo.websocket.org: WebSocket over SSL, default port 443
Minimal configurations:
const esp_websocket_client_config_t ws_cfg = { .uri = "ws://echo.websocket.org",
};
The WebSocket client supports the use of both path and query in the URI. Sample:
const esp_websocket_client_config_t ws_cfg = { .uri = "ws://echo.websocket.org/connectionhandler?id=104",
};
If there are any options related to the URI in esp_websocket_client_config_t, the option defined by the URI will be overridden. Sample:

Espressif Systems

937

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
const esp_websocket_client_config_t ws_cfg = { .uri = "ws://echo.websocket.org:123", .port = 4567,
}; //WebSocket client will connect to websocket.org using port 4567
TLS Configuration:
const esp_websocket_client_config_t ws_cfg = { .uri = "wss://echo.websocket.org", .cert_pem = (const char *)websocket_org_pem_start,
};
Note: If you want to verify the server, then you need to provide a certificate in PEM format, and provide to cert_pem in websocket_client_config_t. If no certficate is provided then the TLS connection will default to not requiring verification.
PEM certificate for this example could be extracted from an openssl s_client command connecting to websocket.org. In case a host operating system has openssl and sed packages installed, one could execute the following command to download and save the root or intermediate root certificate to a file (Note for Windows users: Both Linux like environment or Windows native packages may be used). ` echo "" | openssl s_client -showcerts -connect websocket.org:443 | sed -n "1,/Root/d; /BEGIN/,/END/p" | openssl x509 -outform PEM >websocket_org.pem ` This command will extract the second certificate in the chain and save it as a pem-file.
Subprotocol The subprotocol field in the config struct can be used to request a subprotocol
const esp_websocket_client_config_t ws_cfg = { .uri = "ws://websocket.org", .subprotocol = "soap",
};
Note: The client is indifferent to the subprotocol field in the server response and will accept the connection no matter what the server replies.
For more options on esp_websocket_client_config_t, please refer to API reference below
Events
· WEBSOCKET_EVENT_CONNECTED: The client has successfully established a connection to the server. The client is now ready to send and receive data. Contains no event data.
· WEBSOCKET_EVENT_DISCONNECTED: The client has aborted the connection due to the transport layer failing to read data, e.g. because the server is unavailable. Contains no event data.
· WEBSOCKET_EVENT_DATA: The client has successfully received and parsed a WebSocket frame. The event data contains a pointer to the payload data, the length of the payload data as well as the opcode of the received frame. A message may be fragmented into multiple events if the length exceeds the buffer size. This event will also be posted for non-payload frames, e.g. pong or connection close frames.
· WEBSOCKET_EVENT_ERROR: Not used in the current implementation of the client. If the client handle is needed in the event handler it can be accessed through the pointer passed to the event handler:
esp_websocket_client_handle_t client = (esp_websocket_client_handle_t)handler_args;

Espressif Systems

938

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Limitations and Known Issues
· The client is able to request the use of a subprotocol from the server during the handshake, but does not do any subprotocol related checks on the response from the server.
Application Example
A simple WebSocket example that uses esp_websocket_client to establish a websocket connection and send/receive data with the websocket.org server can be found here: protocols/websocket.
Sending Text Data The WebSocket client supports sending data as a text data frame, which informs the application layer that the payload data is text data encoded as UTF-8. Example:
esp_websocket_client_send_text(client, data, len, portMAX_DELAY);
API Reference
Header File · components/esp_websocket_client/include/esp_websocket_client.h
Functions esp_websocket_client_handle_t esp_websocket_client_init(const esp_websocket_client_config_t
*config) Start a Websocket session This function must be the first function to call, and it returns a esp_websocket_client_handle_t that you must use as input to other functions in the interface. This call MUST have a corresponding call to esp_websocket_client_destroy when the operation is complete. Return
· esp_websocket_client_handle_t · NULL if any errors Parameters · [in] config: The configuration esp_err_t esp_websocket_client_set_uri(esp_websocket_client_handle_t client, const char
*uri) Set URL for client, when performing this behavior, the options in the URL will replace the old ones Must stop the WebSocket client before set URI if the client has been connected. Return esp_err_t Parameters
· [in] client: The client · [in] uri: The uri esp_err_t esp_websocket_client_start(esp_websocket_client_handle_t client) Open the WebSocket connection. Return esp_err_t Parameters · [in] client: The client esp_err_t esp_websocket_client_stop(esp_websocket_client_handle_t client) Stops the WebSocket connection without websocket closing handshake. This API stops ws client and closes TCP connection directly without sending close frames. It is a good practice to close the connection in a clean way using esp_websocket_client_close(). Notes: · Cannot be called from the websocket event handler

Espressif Systems

939

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return esp_err_t Parameters
· [in] client: The client
esp_err_t esp_websocket_client_destroy(esp_websocket_client_handle_t client) Destroy the WebSocket connection and free all resources. This function must be the last function to call for an session. It is the opposite of the esp_websocket_client_init function and must be called with the same handle as input that a esp_websocket_client_init call returned. This might close all connections this handle has used.
Notes:
· Cannot be called from the websocket event handler
Return esp_err_t Parameters
· [in] client: The client
int esp_websocket_client_send_bin(esp_websocket_client_handle_t client, const char *data, int len, TickType_t timeout)
Write binary data to the WebSocket connection (data send with WS OPCODE=02, i.e. binary)
Return · Number of data was sent · (-1) if any errors
Parameters · [in] client: The client · [in] data: The data · [in] len: The length · [in] timeout: Write data timeout in RTOS ticks
int esp_websocket_client_send_text(esp_websocket_client_handle_t client, const char *data, int len, TickType_t timeout)
Write textual data to the WebSocket connection (data send with WS OPCODE=01, i.e. text)
Return · Number of data was sent · (-1) if any errors
Parameters · [in] client: The client · [in] data: The data · [in] len: The length · [in] timeout: Write data timeout in RTOS ticks
esp_err_t esp_websocket_client_close(esp_websocket_client_handle_t client, TickType_t timeout)
Close the WebSocket connection in a clean way.
Sequence of clean close initiated by client:
· Client sends CLOSE frame · Client waits until server echos the CLOSE frame · Client waits until server closes the connection · Client is stopped the same way as by the esp_websocket_client_stop()
Notes: ­ Cannot be called from the websocket event handler
Return esp_err_t Parameters
· [in] client: The client · [in] timeout: Timeout in RTOS ticks for waiting
esp_err_t esp_websocket_client_close_with_code(esp_websocket_client_handle_t client, int code, const char *data, int len, TickType_t timeout)
Close the WebSocket connection in a clean way with custom code/data Closing sequence is the same as for

Espressif Systems

940

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_websocket_client_close()

Notes:

· Cannot be called from the websocket event handler

Return esp_err_t Parameters
· [in] client: The client · [in] code: Close status code as defined in RFC6455 section-7.4 · [in] data: Additional data to closing message · [in] len: The length of the additional data · [in] timeout: Timeout in RTOS ticks for waiting

bool esp_websocket_client_is_connected(esp_websocket_client_handle_t client) Check the WebSocket client connection state.

Return · true · false
Parameters · [in] client: The client handle

esp_err_t esp_websocket_register_events(esp_websocket_client_handle_t

client,

esp_websocket_event_id_t event, esp_event_handler_t

event_handler, void *event_handler_arg)

Register the Websocket Events.

Return esp_err_t Parameters
· client: The client handle · event: The event id · event_handler: The callback function · event_handler_arg: User context

Structures struct esp_websocket_event_data_t
Websocket event data.

Public Members
const char *data_ptr Data pointer
int data_len Data length
uint8_t op_code Received opcode
esp_websocket_client_handle_t client esp_websocket_client_handle_t context
void *user_context user_data context, from esp_websocket_client_config_t user_data
int payload_len Total payload length, payloads exceeding buffer will be posted through multiple events
int payload_offset Actual offset for the data associated with this event
struct esp_websocket_client_config_t Websocket client setup configuration.

Espressif Systems

941

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Public Members
const char *uri Websocket URI, the information on the URI can be overrides the other fields below, if any
const char *host Domain or IP as string
int port Port to connect, default depend on esp_websocket_transport_t (80 or 443)
const char *username Using for Http authentication - Not supported for now
const char *password Using for Http authentication - Not supported for now
const char *path HTTP Path, if not set, default is /
bool disable_auto_reconnect Disable the automatic reconnect function when disconnected
void *user_context HTTP user data context
int task_prio Websocket task priority
int task_stack Websocket task stack
int buffer_size Websocket buffer size
const char *cert_pem Pointer to certificate data in PEM or DER format for server verify (with SSL), default is NULL, not required to verify the server. PEM-format must have a terminating NULL-character. DER-format requires the length to be passed in cert_len.
size_t cert_len Length of the buffer pointed to by cert_pem. May be 0 for null-terminated pem
const char *client_cert Pointer to certificate data in PEM or DER format for SSL mutual authentication, default is NULL, not required if mutual authentication is not needed. If it is not NULL, also client_key has to be provided. PEM-format must have a terminating NULL-character. DER-format requires the length to be passed in client_cert_len.
size_t client_cert_len Length of the buffer pointed to by client_cert. May be 0 for null-terminated pem
const char *client_key Pointer to private key data in PEM or DER format for SSL mutual authentication, default is NULL, not required if mutual authentication is not needed. If it is not NULL, also client_cert has to be provided. PEM-format must have a terminating NULL-character. DER-format requires the length to be passed in client_key_len
size_t client_key_len Length of the buffer pointed to by client_key_pem. May be 0 for null-terminated pem
esp_websocket_transport_t transport Websocket transport type, see `esp_websocket_transport_t
const char *subprotocol Websocket subprotocol

Espressif Systems

942

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

const char *user_agent Websocket user-agent
const char *headers Websocket additional headers
int pingpong_timeout_sec Period before connection is aborted due to no PONGs received
bool disable_pingpong_discon Disable auto-disconnect due to no PONG received within pingpong_timeout_sec
bool use_global_ca_store Use a global ca_store for all the connections in which this bool is set.
bool skip_cert_common_name_check Skip any validation of server certificate CN field
bool keep_alive_enable Enable keep-alive timeout
int keep_alive_idle Keep-alive idle time. Default is 5 (second)
int keep_alive_interval Keep-alive interval time. Default is 5 (second)
int keep_alive_count Keep-alive packet retry send count. Default is 3 counts
size_t ping_interval_sec Websocket ping interval, defaults to 10 seconds if not set
struct ifreq *if_name The name of interface for data to go through. Use the default interface without setting

Type Definitions typedef struct esp_websocket_client *esp_websocket_client_handle_t

Enumerations enum esp_websocket_event_id_t
Websocket Client events id.
Values:
WEBSOCKET_EVENT_ANY = -1
WEBSOCKET_EVENT_ERROR = 0 This event occurs when there are any errors during execution
WEBSOCKET_EVENT_CONNECTED Once the Websocket has been connected to the server, no data exchange has been performed
WEBSOCKET_EVENT_DISCONNECTED The connection has been disconnected
WEBSOCKET_EVENT_DATA When receiving data from the server, possibly multiple portions of the packet
WEBSOCKET_EVENT_CLOSED The connection has been closed cleanly
WEBSOCKET_EVENT_MAX enum esp_websocket_transport_t
Websocket Client transport.
Values:

Espressif Systems

943

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

WEBSOCKET_TRANSPORT_UNKNOWN = 0x0 Transport unknown
WEBSOCKET_TRANSPORT_OVER_TCP Transport over tcp
WEBSOCKET_TRANSPORT_OVER_SSL Transport over ssl

2.4.13 ESP Serial Slave Link
Overview
Espressif provides several chips that can work as slaves. These slave devices rely on some common buses, and have their own communication protocols over those buses. The esp_serial_slave_link component is designed for the master to communicate with ESP slave devices through those protocols over the bus drivers. After an esp_serial_slave_link device is initialized properly, the application can use it to communicate with the ESP slave devices conveniently.

Espressif Device protocols For more details about Espressif device protocols, see the following documents.

ESP SPI Slave HD (Half Duplex) Mode Protocol

SPI Slave Capabilities of Espressif chips

SPI Slave HD Tohost intr Frhost intr TX DMA RX DMA Shared registers

ESP32 N

ESP32-S2 Y (v2) N 2* Y Y 72

ESP32-C3 Y (v2) N 2* Y Y 64

Introduction In the half duplex mode, the master has to use the protocol defined by the slave to communicate with the slave. Each transaction may consist of the following phases (list by the order they should exist):
· Command: 8-bit, master to slave This phase determines the rest phases of the transactions. See Supported Commands.
· Address: 8-bit, master to slave, optional For some commands (WRBUF, RDBUF), this phase specifies the address of the shared buffer to write to/read from. For other commands with this phase, they are meaningless but still have to exist in the transaction.
· Dummy: 8-bit, floating, optional This phase is the turnaround time between the master and the slave on the bus, and also provides enough time for the slave to prepare the data to send to the master.
· Data: variable length, the direction is also determined by the command. This may be a data OUT phase, in which the direction is slave to master, or a data IN phase, in which the direction is master to slave.
The direction means which side (master or slave) controls the MOSI, MISO, WP, and HD pins.

Espressif Systems

944

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Data IO Modes In some IO modes, more data wires can be used to send the data. As a result, the SPI clock cycles required for the same amount of data will be less than in the 1-bit mode. For example, in QIO mode, address and data (IN and OUT) should be sent on all 4 data wires (MOSI, MISO, WP, and HD). Here are the modes supported by the ESP32-S2 SPI slave and the wire number used in corresponding modes.

Mode 1-bit DOUT DIO QOUT QIO QPI

command WN 1 1 1 1 1 4

address WN 1 1 2 1 4 4

dummy cycles 1 4 4 4 4 4

data WN 1 2 2 4 4 4

Normally, which mode is used is determined by the command sent by the master (See Supported Commands), except the QPI mode.

QPI Mode The QPI mode is a special state of the SPI Slave. The master can send the ENQPI command to put the slave into the QPI mode state. In the QPI mode, the command is also sent in 4-bit, thus itns not compatible with the normal modes. The master should only send QPI commands when the slave is in QPI mode. To exit from the QPI mode, master can send the EXQPI command.

Supported Commands Note: The command name is in a master-oriented direction. For example, WRBUF means master writes the buffer of slave.

Name WRBUF
RDBUF
WRDMA
RDDMA
SEG_DONE ENQPI WR_DONE CMD8 CMD9 CMDA EXQPI

Description Write buffer

Command 0x01

Read buffer

0x02

Write DMA

0x03

Read DMA

0x04

Segments done

0x05

Enter QPI mode

0x06

Write segments done
Interrupt

0x07 0x08

Interrupt

0x09

Interrupt

0x0A

Exit QPI mode

0xDD

Address Buf addr
Buf addr
8 bits
8 bits
· · · · · · ·

Data master to slave, no longer than buffer size slave to master, no longer than buffer size master to slave, no longer than length provided by slave slave to master, no longer than length provided by slave
·
·
·
·
·
·
·

Espressif Systems

945

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Moreover, WRBUF, RDBUF, WRDMA, RDDMA commands have their 2-bit and 4-bit version. To do transactions in 2-bit or 4-bit mode, send the original command ORed by the corresponding command mask below. For example, command 0xA1 means WRBUF in QIO mode.

Mode 1-bit DOUT DIO QOUT QIO QPI

Mask 0x00 0x10 0x50 0x20 0xA0 0xA0

Segment Transaction Mode Segment transaction mode is the only mode supported by the SPI Slave HD driver for now. In this mode, for a transaction the slave load onto the DMA, the master is allowed to read or write in segments. This way the master doesnnt have to prepare a large buffer as the size of data provided by the slave. After the master finishes reading/writing a buffer, it has to send the corresponding termination command to the slave as a synchronization signal. The slave driver will update new data (if exist) onto the DMA upon seeing the termination command.
The termination command is WR_DONE (0x07) for the WRDMA and CMD8 (0x08) for the RDDMA.
Herens an example for the flow the master read data from the slave DMA:
1. The slave loads 4092 bytes of data onto the RDDMA 2. The master do seven RDDMA transactions, each of them is 512 bytes long, and reads the first 3584 bytes from
the slave 3. The master do the last RDDMA transaction of 512 bytes (equal, longer, or shorter than the total length loaded
by the slave are all allowed). The first 508 bytes are valid data from the slave, while the last 4 bytes are meaningless bytes. 4. The master sends CMD8 to the slave 5. The slave loads another 4092 bytes of data onto the RDDMA 6. The master can start new reading transactions after it sends the CMD8
Terminology
· ESSL: Abbreviation for ESP Serial Slave Link, the component described by this document. · Master: The device running the esp_serial_slave_link component. · ESSL device: a virtual device on the master associated with an ESP slave device. The device context has the
knowledge of the slave protocol above the bus, relying on some bus drivers to communicate with the slave. · ESSL device handle: a handle to ESSL device context containing the configuration, status and data required
by the ESSL component. The context stores the driver configurations, communication state, data shared by master and slave, etc. The context should be initialized before it is used, and get deinitialized if not used any more. The master application operates on the ESSL device through this handle. · ESP slave: the slave device connected to the bus, which ESSL component is designed to communicate with. · Bus: The bus over which the master and the slave communicate with each other. · Slave protocol: The special communication protocol specified by Espressif HW/SW over the bus. · TX buffer num: a counter, which is on the slave and can be read by the master, indicates the accumulated buffer numbers that the slave has loaded to the hardware to receive data from the master. · RX data size: a counter, which is on the slave and can be read by the master, indicates the accumulated data size that the slave has loaded to the hardware to send to the master.
Services provided by ESP slave
There are some common services provided by the Espressif slaves:
1. Tohost Interrupts: The slave can inform the master about certain events by the interrupt line. (optional)

Espressif Systems

946

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
2. Frhost Interrupts: The master can inform the slave about certain events. 3. Tx FIFO (master to slave): the slave can send data in stream to the master. The SDIO slave can also indicate
it has new data to send to master by the interrupt line. The slave updates the TX buffer num to inform the master how much data it can receive, and the master then read the TX buffer num, and take off the used buffer number to know how many buffers are remaining. 4. Rx FIFO (slave to master): the slave can receive data from the master in units of receiving buffers. The slave updates the RX data size to inform the master how much data it has prepared to send, and then the master read the data size, and take off the data length it has already received to know how many data is remaining. 5. Shared registers: the master can read some part of the registers on the slave, and also write these registers to let the slave read. The services provided by the slave depends on the slavens model. See SPI Slave Capabilities of Espressif chips for more details.
Initialization of ESP Serial Slave Link
ESP SDIO Slave The ESP SDIO slave link (ESSL SDIO) devices relies on the sdmmc component. It includes the usage of communicating with ESP SDIO Slave device via SDSPI feature. The ESSL device should be initialized as below:
1. Initialize a sdmmc card (see :doc:` Document of SDMMC driver </api-reference/storage/sdmmc>`) structure. 2. Call sdmmc_card_init() to initialize the card. 3. Initialize the ESSL device with essl_sdio_config_t. The card member should be the sd-
mmc_card_t got in step 2, and the recv_buffer_size member should be filled correctly according to prenegotiated value. 4. Call essl_init() to do initialization of the SDIO part. 5. Call essl_wait_for_ready() to wait for the slave to be ready.
ESP SPI Slave Note: If you are communicating with the ESP SDIO Slave device through SPI interface, you should use the SDIO interface instead.
Hasnnt been supported yet.
APIs
After the initialization process above is performed, you can call the APIs below to make use of the services provided by the slave:
Tohost Interrupts (optional) 1. Call essl_get_intr_ena() to know which events will trigger the interrupts to the master. 2. Call essl_set_intr_ena() to set the events that will trigger interrupts to the master. 3. Call essl_wait_int() to wait until interrupt from the slave, or timeout. 4. When interrupt is triggered, call essl_get_intr() to know which events are active, and call essl_clear_intr() to clear them.
Frhost Interrupts 1. Call essl_send_slave_intr() to trigger general purpose interrupt of the slave.

Espressif Systems

947

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

TX FIFO
1. Call essl_get_tx_buffer_num() to know how many buffers the slave has prepared to receive data from the master. This is optional. The master will poll tx_buffer_num when it try to send packets to the slave, until the slave has enough buffer or timeout.
2. Call essl_send_paket() to send data to the slave.

RX FIFO
1. Call essl_get_rx_data_size() to know how many data the slave has prepared to send to the master. This is optional. When the master tries to receive data from the slave, it will update the rx_data_size for once, if the current rx_data_size is shorter than the buffer size the master prepared to receive. And it may poll the rx_data_size if the rx_dat_size keeps 0, until timeout.
2. Call essl_get_packet() to receive data from the slave.

Reset counters (Optional) Call essl_reset_cnt() to reset the internal counter if you find the slave has reset its counter.

Application Example
The example below shows how ESP32-S3 SDIO host and slave communicate with each other. The host use the ESSL SDIO. peripherals/sdio. Please refer to the specific example README.md for details.

API Reference
Header File · components/esp_serial_slave_link/include/esp_serial_slave_link/essl.h

Functions esp_err_t essl_init(essl_handle_t handle, uint32_t wait_ms)
Initialize the slave.
Return · ESP_OK: If success · ESP_ERR_NOT_SUPPORTED: Current device does not support this function. · Other value returned from lower layer init.
Parameters · handle: Handle of an ESSL device. · wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.
esp_err_t essl_wait_for_ready(essl_handle_t handle, uint32_t wait_ms) Wait for interrupt of an ESSL slave device.
Return · ESP_OK: If success · ESP_ERR_NOT_SUPPORTED: Current device does not support this function. · One of the error codes from SDMMC host controller
Parameters · handle: Handle of an ESSL device. · wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.
esp_err_t essl_get_tx_buffer_num(essl_handle_t handle, uint32_t *out_tx_num, uint32_t wait_ms) Get buffer num for the host to send data to the slave. The buffers are size of buffer_size.
Return

Espressif Systems

948

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_OK: Success · ESP_ERR_NOT_SUPPORTED: This API is not supported in this mode · One of the error codes from SDMMC/SPI host controller Parameters · handle: Handle of a ESSL device. · out_tx_num: Output of buffer num that host can send data to ESSL slave. · wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.
esp_err_t essl_get_rx_data_size(essl_handle_t handle, uint32_t *out_rx_size, uint32_t wait_ms) Get the size, in bytes, of the data that the ESSL slave is ready to send
Return · ESP_OK: Success · ESP_ERR_NOT_SUPPORTED: This API is not supported in this mode · One of the error codes from SDMMC/SPI host controller
Parameters · handle: Handle of an ESSL device. · out_rx_size: Output of data size to read from slave, in bytes · wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.
esp_err_t essl_reset_cnt(essl_handle_t handle) Reset the counters of this component. Usually you donnt need to do this unless you know the slave is reset.
Return · ESP_OK: Success · ESP_ERR_NOT_SUPPORTED: This API is not supported in this mode · ESP_ERR_INVALID_ARG: Invalid argument, handle is not init.
Parameters · handle: Handle of an ESSL device.
esp_err_t essl_send_packet(essl_handle_t handle, const void *start, size_t length, uint32_t wait_ms) Send a packet to the ESSL Slave. The Slave receives the packet into buffers whose size is buffer_size (configured during initialization).
Return · ESP_OK Success · ESP_ERR_INVALID_ARG: Invalid argument, handle is not init or other argument is not valid. · ESP_ERR_TIMEOUT: No buffer to use, or error ftrom SDMMC host controller. · ESP_ERR_NOT_FOUND: Slave is not ready for receiving. · ESP_ERR_NOT_SUPPORTED: This API is not supported in this mode · One of the error codes from SDMMC/SPI host controller.
Parameters · handle: Handle of an ESSL device. · start: Start address of the packet to send · length: Length of data to send, if the packet is over-size, the it will be divided into blocks and hold into different buffers automatically. · wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.
esp_err_t essl_get_packet(essl_handle_t handle, void *out_data, size_t size, size_t *out_length, uint32_t wait_ms)
Get a packet from ESSL slave.
Return · ESP_OK Success: All the data has been read from the slave. · ESP_ERR_INVALID_ARG: Invalid argument, The handle is not initialized or the other arguments are invalid. · ESP_ERR_NOT_FINISHED: Read was successful, but there is still data remaining. · ESP_ERR_NOT_FOUND: Slave is not ready to send data. · ESP_ERR_NOT_SUPPORTED: This API is not supported in this mode · One of the error codes from SDMMC/SPI host controller.
Parameters · handle: Handle of an ESSL device.

Espressif Systems

949

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· [out] out_data: Data output address · size: The size of the output buffer, if the buffer is smaller than the size of data to receive from
slave, the driver returns ESP_ERR_NOT_FINISHED · [out] out_length: Output of length the data actually received from slave. · wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.
esp_err_t essl_write_reg(essl_handle_t handle, uint8_t addr, uint8_t value, uint8_t *value_o, uint32_t wait_ms)
Write general purpose R/W registers (8-bit) of ESSL slave.
Note sdio 28-31 are reserved, the lower API helps to skip. Return
· ESP_OK Success · One of the error codes from SDMMC/SPI host controller Parameters · handle: Handle of an ESSL device. · addr: Address of register to write. For SDIO, valid address: 0-59. For SPI, see essl_spi.h · value: Value to write to the register. · value_o: Output of the returned written value. · wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.
esp_err_t essl_read_reg(essl_handle_t handle, uint8_t add, uint8_t *value_o, uint32_t wait_ms) Read general purpose R/W registers (8-bit) of ESSL slave.
Return · ESP_OK Success · One of the error codes from SDMMC/SPI host controller
Parameters · handle: Handle of a essl device. · add: Address of register to read. For SDIO, Valid address: 0-27, 32-63 (28-31 reserved, return interrupt bits on read). For SPI, see essl_spi.h · value_o: Output value read from the register. · wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.
esp_err_t essl_wait_int(essl_handle_t handle, uint32_t wait_ms) wait for an interrupt of the slave
Return · ESP_OK: If interrupt is triggered. · ESP_ERR_NOT_SUPPORTED: Current device does not support this function. · ESP_ERR_TIMEOUT: No interrupts before timeout.
Parameters · handle: Handle of an ESSL device. · wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.
esp_err_t essl_clear_intr(essl_handle_t handle, uint32_t intr_mask, uint32_t wait_ms) Clear interrupt bits of ESSL slave. All the bits set in the mask will be cleared, while other bits will stay the same.
Return · ESP_OK: Success · ESP_ERR_NOT_SUPPORTED: Current device does not support this function. · One of the error codes from SDMMC host controller
Parameters · handle: Handle of an ESSL device. · intr_mask: Mask of interrupt bits to clear. · wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.
esp_err_t essl_get_intr(essl_handle_t handle, uint32_t *intr_raw, uint32_t *intr_st, uint32_t wait_ms) Get interrupt bits of ESSL slave.
Return · ESP_OK: Success

Espressif Systems

950

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_INVALID_ARG: If both intr_raw and intr_st are NULL. · ESP_ERR_NOT_SUPPORTED: Current device does not support this function. · One of the error codes from SDMMC host controller Parameters · handle: Handle of an ESSL device. · intr_raw: Output of the raw interrupt bits. Set to NULL if only masked bits are read. · intr_st: Output of the masked interrupt bits. set to NULL if only raw bits are read. · wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.
esp_err_t essl_set_intr_ena(essl_handle_t handle, uint32_t ena_mask, uint32_t wait_ms) Set interrupt enable bits of ESSL slave. The slave only sends interrupt on the line when there is a bit both the raw status and the enable are set.
Return · ESP_OK: Success · ESP_ERR_NOT_SUPPORTED: Current device does not support this function. · One of the error codes from SDMMC host controller
Parameters · handle: Handle of an ESSL device. · ena_mask: Mask of the interrupt bits to enable. · wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.
esp_err_t essl_get_intr_ena(essl_handle_t handle, uint32_t *ena_mask_o, uint32_t wait_ms) Get interrupt enable bits of ESSL slave.
Return · ESP_OK Success · One of the error codes from SDMMC host controller
Parameters · handle: Handle of an ESSL device. · ena_mask_o: Output of interrupt bit enable mask. · wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.
esp_err_t essl_send_slave_intr(essl_handle_t handle, uint32_t intr_mask, uint32_t wait_ms) Send interrupts to slave. Each bit of the interrupt will be triggered.
Return · ESP_OK: Success · ESP_ERR_NOT_SUPPORTED: Current device does not support this function. · One of the error codes from SDMMC host controller
Parameters · handle: Handle of an ESSL device. · intr_mask: Mask of interrupt bits to send to slave. · wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.

Type Definitions typedef struct essl_dev_t *essl_handle_t
Handle of an ESSL device.

Header File · components/esp_serial_slave_link/include/esp_serial_slave_link/essl_sdio.h

Functions esp_err_t essl_sdio_init_dev(essl_handle_t *out_handle, const essl_sdio_config_t *config)
Initialize the ESSL SDIO device and get its handle.
Return · ESP_OK: on success · ESP_ERR_NO_MEM: memory exhausted.

Espressif Systems

951

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Parameters · out_handle: Output of the handle. · config: Configuration for the ESSL SDIO device.
esp_err_t essl_sdio_deinit_dev(essl_handle_t handle) Deinitialize and free the space used by the ESSL SDIO device.
Return · ESP_OK: on success · ESP_ERR_INVALID_ARG: wrong handle passed
Parameters · handle: Handle of the ESSL SDIO device to deinit.

Structures struct essl_sdio_config_t
Configuration for the ESSL SDIO device.

Public Members
sdmmc_card_t *card The initialized sdmmc card pointer of the slave.
int recv_buffer_size The pre-negotiated recv buffer size used by both the host and the slave.

Header File · components/esp_serial_slave_link/include/esp_serial_slave_link/essl_spi.h

Functions esp_err_t essl_spi_init_dev(essl_handle_t *out_handle, const essl_spi_config_t *init_config)
Initialize the ESSL SPI device function list and get its handle.
Return · ESP_OK: On success · ESP_ERR_NO_MEM: Memory exhausted · ESP_ERR_INVALID_STATE: SPI driver is not initialized · ESP_ERR_INVALID_ARG: Wrong register ID
Parameters · [out] out_handle: Output of the handle · init_config: Configuration for the ESSL SPI device
esp_err_t essl_spi_deinit_dev(essl_handle_t handle) Deinitialize the ESSL SPI device and free the memory used by the device.
Return · ESP_OK: On success · ESP_ERR_INVALID_STATE: ESSL SPI is not in use
Parameters · handle: Handle of the ESSL SPI device
esp_err_t essl_spi_read_reg(void *arg, uint8_t addr, uint8_t *out_value, uint32_t wait_ms) Read from the shared registers.
Note The registers for Master/Slave synchronization are reserved. Do not use them. (see rx_sync_reg in essl_spi_config_t)
Return · ESP_OK: success · ESP_ERR_INVALID_STATE: ESSL SPI has not been initialized. · ESP_ERR_INVALID_ARG: The address argument is not valid. See note 1. · or other return value from :cpp:func:spi_device_transmit.

Espressif Systems

952

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Parameters · arg: Context of the component. (Member arg from essl_handle_t) · addr: Address of the shared registers. (Valid: 0 ~ SOC_SPI_MAXIMUM_BUFFER_SIZE, registers for M/S sync are reserved, see note1). · [out] out_value: Read buffer for the shared registers. · wait_ms: Time to wait before timeout (reserved for future use, user should set this to 0).
esp_err_t essl_spi_get_packet(void *arg, void *out_data, size_t size, uint32_t wait_ms) Get a packet from Slave.
Return · ESP_OK: On Success · ESP_ERR_INVALID_STATE: ESSL SPI has not been initialized. · ESP_ERR_INVALID_ARG: The output data address is neither DMA capable nor 4 byte-aligned · ESP_ERR_INVALID_SIZE: Master requires size bytes of data but Slave did not load enough bytes.
Parameters · arg: Context of the component. (Member arg from essl_handle_t) · [out] out_data: Output data address · size: The size of the output data. · wait_ms: Time to wait before timeout (reserved for future use, user should set this to 0).
esp_err_t essl_spi_write_reg(void *arg, uint8_t addr, uint8_t value, uint8_t *out_value, uint32_t wait_ms)
Write to the shared registers.
Note The registers for Master/Slave synchronization are reserved. Do not use them. (see tx_sync_reg in essl_spi_config_t)
Note Feature of checking the actual written value (out_value) is not supported. Return
· ESP_OK: success · ESP_ERR_INVALID_STATE: ESSL SPI has not been initialized. · ESP_ERR_INVALID_ARG: The address argument is not valid. See note 1. · ESP_ERR_NOT_SUPPORTED: Should set out_value to NULL. See note 2. · or other return value from :cpp:func:spi_device_transmit. Parameters · arg: Context of the component. (Member arg from essl_handle_t) · addr: Address of the shared registers. (Valid: 0 ~ SOC_SPI_MAXIMUM_BUFFER_SIZE, reg-
isters for M/S sync are reserved, see note1) · value: Buffer for data to send, should be align to 4. · [out] out_value: Not supported, should be set to NULL. · wait_ms: Time to wait before timeout (reserved for future use, user should set this to 0).
esp_err_t essl_spi_send_packet(void *arg, const void *data, size_t size, uint32_t wait_ms) Send a packet to Slave.
Return · ESP_OK: On success · ESP_ERR_INVALID_STATE: ESSL SPI has not been initialized. · ESP_ERR_INVALID_ARG: The data address is not DMA capable · ESP_ERR_INVALID_SIZE: Master will send size bytes of data but Slave did not load enough RX buffer
Parameters · arg: Context of the component. (Member arg from essl_handle_t) · data: Address of the data to send · size: Size of the data to send. · wait_ms: Time to wait before timeout (reserved for future use, user should set this to 0).
void essl_spi_reset_cnt(void *arg) Reset the counter in Master context.
Note Shall only be called if the slave has reset its counter. Else, Slave and Master would be desynchronized

Espressif Systems

953

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Parameters · arg: Context of the component. (Member arg from essl_handle_t)
esp_err_t essl_spi_rdbuf(spi_device_handle_t spi, uint8_t *out_data, int addr, int len, uint32_t flags) Read the shared buffer from the slave in ISR way.
Note The slavens HW doesnnt guarantee the data in one SPI transaction is consistent. It sends data in unit of byte. In other words, if the slave SW attempts to update the shared register when a rdbuf SPI transaction is in-flight, the data got by the master will be the combination of bytes of different writes of slave SW.
Note out_data should be prepared in words and in the DRAM. The buffer may be written in words by the DMA. When a byte is written, the remaining bytes in the same word will also be overwritten, even the len is shorter than a word.
Return · ESP_OK: on success · or other return value from :cpp:func:spi_device_transmit.
Parameters · spi: SPI device handle representing the slave · [out] out_data: Buffer for read data, strongly suggested to be in the DRAM and aligned to 4 · addr: Address of the slave shared buffer · len: Length to read · flags: SPI_TRANS_* flags to control the transaction mode of the transaction to send.
esp_err_t essl_spi_rdbuf_polling(spi_device_handle_t spi, uint8_t *out_data, int addr, int len, uint32_t flags)
Read the shared buffer from the slave in polling way.
Note out_data should be prepared in words and in the DRAM. The buffer may be written in words by the DMA. When a byte is written, the remaining bytes in the same word will also be overwritten, even the len is shorter than a word.
Return · ESP_OK: on success · or other return value from :cpp:func:spi_device_transmit.
Parameters · spi: SPI device handle representing the slave · [out] out_data: Buffer for read data, strongly suggested to be in the DRAM and aligned to 4 · addr: Address of the slave shared buffer · len: Length to read · flags: SPI_TRANS_* flags to control the transaction mode of the transaction to send.
esp_err_t essl_spi_wrbuf(spi_device_handle_t spi, const uint8_t *data, int addr, int len, uint32_t flags)
Write the shared buffer of the slave in ISR way.
Note out_data should be prepared in words and in the DRAM. The buffer may be written in words by the DMA. When a byte is written, the remaining bytes in the same word will also be overwritten, even the len is shorter than a word.
Return · ESP_OK: success · or other return value from :cpp:func:spi_device_transmit.
Parameters · spi: SPI device handle representing the slave · data: Buffer for data to send, strongly suggested to be in the DRAM · addr: Address of the slave shared buffer, · len: Length to write · flags: SPI_TRANS_* flags to control the transaction mode of the transaction to send.
esp_err_t essl_spi_wrbuf_polling(spi_device_handle_t spi, const uint8_t *data, int addr, int len, uint32_t flags)
Write the shared buffer of the slave in polling way.
Note out_data should be prepared in words and in the DRAM. The buffer may be written in words by the DMA. When a byte is written, the remaining bytes in the same word will also be overwritten, even the len is shorter than a word.

Espressif Systems

954

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Return · ESP_OK: success · or other return value from :cpp:func:spi_device_polling_transmit.
Parameters · spi: SPI device handle representing the slave · data: Buffer for data to send, strongly suggested to be in the DRAM · addr: Address of the slave shared buffer, · len: Length to write · flags: SPI_TRANS_* flags to control the transaction mode of the transaction to send.
esp_err_t essl_spi_rddma(spi_device_handle_t spi, uint8_t *out_data, int len, int seg_len, uint32_t flags)
Receive long buffer in segments from the slave through its DMA.
Note This function combines several :cpp:func:essl_spi_rddma_seg and one :cpp:func:essl_spi_rddma_done at the end. Used when the slave is working in segment mode.
Return · ESP_OK: success · or other return value from :cpp:func:spi_device_transmit.
Parameters · spi: SPI device handle representing the slave · [out] out_data: Buffer to hold the received data, strongly suggested to be in the DRAM and aligned to 4 · len: Total length of data to receive. · seg_len: Length of each segment, which is not larger than the maximum transaction length allowed for the spi device. Suggested to be multiples of 4. When set < 0, means send all data in one segment (the rddma_done will still be sent.) · flags: SPI_TRANS_* flags to control the transaction mode of the transaction to send.
esp_err_t essl_spi_rddma_seg(spi_device_handle_t spi, uint8_t *out_data, int seg_len, uint32_t flags) Read one data segment from the slave through its DMA.
Note To read long buffer, call :cpp:func:essl_spi_rddma instead. Return
· ESP_OK: success · or other return value from :cpp:func:spi_device_transmit. Parameters · spi: SPI device handle representing the slave · [out] out_data: Buffer to hold the received data. strongly suggested to be in the DRAM and
aligned to 4 · seg_len: Length of this segment · flags: SPI_TRANS_* flags to control the transaction mode of the transaction to send.
esp_err_t essl_spi_rddma_done(spi_device_handle_t spi, uint32_t flags) Send the rddma_done command to the slave. Upon receiving this command, the slave will stop sending the current buffer even there are data unsent, and maybe prepare the next buffer to send.
Note This is required only when the slave is working in segment mode. Return
· ESP_OK: success · or other return value from :cpp:func:spi_device_transmit. Parameters · spi: SPI device handle representing the slave · flags: SPI_TRANS_* flags to control the transaction mode of the transaction to send.
esp_err_t essl_spi_wrdma(spi_device_handle_t spi, const uint8_t *data, int len, int seg_len, uint32_t flags)
Send long buffer in segments to the slave through its DMA.
Note This function combines several :cpp:func:essl_spi_wrdma_seg and one :cpp:func:essl_spi_wrdma_done at the end. Used when the slave is working in segment

Espressif Systems

955

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
mode. Return
· ESP_OK: success · or other return value from :cpp:func:spi_device_transmit. Parameters · spi: SPI device handle representing the slave · data: Buffer for data to send, strongly suggested to be in the DRAM · len: Total length of data to send. · seg_len: Length of each segment, which is not larger than the maximum transaction length al-
lowed for the spi device. Suggested to be multiples of 4. When set < 0, means send all data in one segment (the wrdma_done will still be sent.) · flags: SPI_TRANS_* flags to control the transaction mode of the transaction to send.
esp_err_t essl_spi_wrdma_seg(spi_device_handle_t spi, const uint8_t *data, int seg_len, uint32_t flags)
Send one data segment to the slave through its DMA.
Note To send long buffer, call :cpp:func:essl_spi_wrdma instead. Return
· ESP_OK: success · or other return value from :cpp:func:spi_device_transmit. Parameters · spi: SPI device handle representing the slave · data: Buffer for data to send, strongly suggested to be in the DRAM · seg_len: Length of this segment · flags: SPI_TRANS_* flags to control the transaction mode of the transaction to send.
esp_err_t essl_spi_wrdma_done(spi_device_handle_t spi, uint32_t flags) Send the wrdma_done command to the slave. Upon receiving this command, the slave will stop receiving, process the received data, and maybe prepare the next buffer to receive.
Note This is required only when the slave is working in segment mode. Return
· ESP_OK: success · or other return value from :cpp:func:spi_device_transmit. Parameters · spi: SPI device handle representing the slave · flags: SPI_TRANS_* flags to control the transaction mode of the transaction to send.
Structures struct essl_spi_config_t
Configuration of ESSL SPI device.
Public Members
spi_device_handle_t *spi Pointer to SPI device handle.
uint32_t tx_buf_size The pre-negotiated Master TX buffer size used by both the host and the slave.
uint8_t tx_sync_reg The pre-negotiated register ID for Master-TX-SLAVE-RX synchronization. 1 word (4 Bytes) will be reserved for the synchronization.
uint8_t rx_sync_reg The pre-negotiated register ID for Master-RX-Slave-TX synchronization. 1 word (4 Bytes) will be reserved for the synchronization.

Espressif Systems

956

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
2.4.14 ESP x509 Certificate Bundle
Overview
The ESP x509 Certificate Bundle API provides an easy way to include a bundle of custom x509 root certificates for TLS server verification.
Note: The bundle is currently not available when using WolfSSL.
The bundle comes with the complete list of root certificates from Mozillans NSS root certificate store. Using the gen_crt_bundle.py python utility the certificatesnsubject name and public key are stored in a file and embedded in the ESP32-S3 binary. When generating the bundle you may choose between:
· The full root certificate bundle from Mozilla, containing more than 130 certificates. The current bundle was updated Tue Oct 5 09:35:35 2021 GMT.
· A pre-selected filter list of the name of the most commonly used root certificates, reducing the amount of certificates to around 35 while still having around 90 % coverage according to market share statistics.
In addition it is possible to specify a path to a certificate file or a directory containing certificates which then will be added to the generated bundle.
Note: Trusting all root certificates means the list will have to be updated if any of the certificates are retracted. This includes removing them from cacrt_all.pem.

Configuration
Most configuration is done through menuconfig. CMake will generate the bundle according to the configuration and embed it.
· CONFIG_MBEDTLS_CERTIFICATE_BUNDLE: automatically build and attach the bundle. · CONFIG_MBEDTLS_DEFAULT_CERTIFICATE_BUNDLE: decide which certificates to include from the com-
plete root list. · CONFIG_MBEDTLS_CUSTOM_CERTIFICATE_BUNDLE_PATH: specify the path of any additional certifi-
cates to embed in the bundle.
To enable the bundle when using ESP-TLS simply pass the function pointer to the bundle attach function:
esp_tls_cfg_t cfg = { .crt_bundle_attach = esp_crt_bundle_attach,
};
This is done to avoid embedding the certificate bundle unless activated by the user.
If using mbedTLS directly then the bundle may be activated by directly calling the attach function during the setup process:
mbedtls_ssl_config conf; mbedtls_ssl_config_init(&conf);
esp_crt_bundle_attach(&conf);

Generating the List of Root Certificates
The list of root certificates comes from Mozillans NSS root certificate store, which can be found here The list can be downloaded and created by running the script mk-ca-bundle.pl that is distributed as a part of curl. Another

Espressif Systems

957

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
alternative would be to download the finished list directly from the curl website: CA certificates extracted from Mozilla The common certificates bundle were made by selecting the authorities with a market share of more than 1 % from w3techns SSL Survey. These authorities were then used to pick the names of the certificates for the filter list, cmn_crt_authorities.csv, from this list provided by Mozilla.
Updating the Certificate Bundle
The bundle is embedded into the app and can be updated along with the app by an OTA update. If you want to include a more up-to-date bundle than the bundle currently included in IDF, then the certificate list can be downloaded from Mozilla as described in Updating the Certificate Bundle.
Application Example
Simple HTTPS example that uses ESP-TLS to establish a secure socket connection using the certificate bundle with two custom certificates added for verification: protocols/https_x509_bundle. HTTPS example that uses ESP-TLS and the default bundle: protocols/https_request. HTTPS example that uses mbedTLS and the default bundle: protocols/https_mbedtls.
API Reference
Header File · components/mbedtls/esp_crt_bundle/include/esp_crt_bundle.h
Functions esp_err_t esp_crt_bundle_attach(void *conf)
Attach and enable use of a bundle for certificate verification. Attach and enable use of a bundle for certificate verification through a verification callback. If no specific bundle has been set through esp_crt_bundle_set() it will default to the bundle defined in menuconfig and embedded in the binary. Return
· ESP_OK if adding certificates was successful. · Other if an error occured or an action must be taken by the calling process. Parameters · [in] conf: The config struct for the SSL connection. void esp_crt_bundle_detach(mbedtls_ssl_config *conf) Disable and dealloc the certification bundle. Removes the certificate verification callback and deallocates used resources Parameters · [in] conf: The config struct for the SSL connection. void esp_crt_bundle_set(const uint8_t *x509_bundle) Set the default certificate bundle used for verification. Overrides the default certificate bundle. In most use cases the bundle should be set through menuconfig. The bundle needs to be sorted by subject name since binary search is used to find certificates. Parameters · [in] x509_bundle: A pointer to the certificate bundle. Code examples for this API section are provided in the protocols directory of ESP-IDF examples.

Espressif Systems

958

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

2.4.15 IP Network Layer
Documentation for IP Network Layer protocols (below the Application Protocol layer) are provided in Networking APIs.

2.5 Provisioning API
2.5.1 Protocol Communication
Overview
Protocol Communication (protocomm) component manages secure sessions and provides framework for multiple transports. The application can also use protocomm layer directly to have application specific extensions for the provisioning (or non-provisioning) use cases.
Following features are available for provisioning : · Communication security at application level ­ protocomm_security0 (no security) ­ protocomm_security1 (curve25519 key exchange + AES-CTR encryption) · Proof-of-possession (support with protocomm_security1 only)
Protocomm internally uses protobuf (protocol buffers) for secure session establishment. Though users can implement their own security (even without using protobuf). One can even use protocomm without any security layer.
Protocomm provides framework for various transports - WiFi (SoftAP+HTTPD), BLE, console - in which case the handler invocation is automatically taken care of on the device side (see Transport Examples below for code snippets).
Note that the client still needs to establish session (only for protocomm_security1) by performing the two way handshake. See Unified Provisioning for more details about the secure handshake logic.

Transport Example (SoftAP + HTTP) with Security 1

For sample usage, see wifi_provisioning/src/scheme_softap.c
/* Endpoint handler to be registered with protocomm. * This simply echoes back the received data. */
esp_err_t echo_req_handler (uint32_t session_id, const uint8_t *inbuf, ssize_t inlen, uint8_t **outbuf, ssize_t *outlen, void *priv_data)
{ /* Session ID may be used for persistence */ printf("Session ID : %d", session_id);

/* Echo back the received data */

*outlen = inlen;

/* Output data length updated */

*outbuf = malloc(inlen); /* This will be deallocated outside */

memcpy(*outbuf, inbuf, inlen);

/* Private data that was passed at the time of endpoint creation */ uint32_t *priv = (uint32_t *) priv_data; if (priv) {
printf("Private data : %d", *priv); }

return ESP_OK; }

/* Example function for launching a protocomm instance over HTTP */ (continues on next page)

Espressif Systems

959

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

protocomm_t *start_pc(const char *pop_string) {
protocomm_t *pc = protocomm_new();

(continued from previous page)

/* Config for protocomm_httpd_start() */ protocomm_httpd_config_t pc_config = {
.data = { .config = PROTOCOMM_HTTPD_DEFAULT_CONFIG() } };
/* Start protocomm server on top of HTTP */ protocomm_httpd_start(pc, &pc_config);
/* Create Proof of Possession object from pop_string. It must be valid * throughout the scope of protocomm endpoint. This need not be
static, * ie. could be dynamically allocated and freed at the time of
endpoint * removal */
const static protocomm_security_pop_t pop_obj = { .data = (const uint8_t *) strdup(pop_string), .len = strlen(pop_string)
};
/* Set security for communication at application level. Just like for * request handlers, setting security creates an endpoint and
registers * the handler provided by protocomm_security1. One can similarly use * protocomm_security0. Only one type of security can be set for a * protocomm instance at a time. */
protocomm_set_security(pc, "security_endpoint", &protocomm_security1, &pop_obj);
/* Private data passed to the endpoint must be valid throughout the scope
* of protocomm endpoint. This need not be static, ie. could be dynamically
* allocated and freed at the time of endpoint removal */ static uint32_t priv_data = 1234;
/* Add a new endpoint for the protocomm instance, identified by a unique name
* and register a handler function along with private data to be passed at the
* time of handler execution. Multiple endpoints can be added as long as they
* are identified by unique names */ protocomm_add_endpoint(pc, "echo_req_endpoint",
echo_req_handler, (void *) &priv_data); return pc; }
/* Example function for stopping a protocomm instance */ void stop_pc(protocomm_t *pc) {
/* Remove endpoint identified by it's unique name */ protocomm_remove_endpoint(pc, "echo_req_endpoint");
/* Remove security endpoint identified by it's name */
(continues on next page)

Espressif Systems

960

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page) protocomm_unset_security(pc, "security_endpoint");
/* Stop HTTP server */ protocomm_httpd_stop(pc);
/* Delete (deallocate) the protocomm instance */ protocomm_delete(pc); }

Transport Example (BLE) with Security 0
For sample usage, see wifi_provisioning/src/scheme_ble.c
/* Example function for launching a secure protocomm instance over BLE */ protocomm_t *start_pc() {
protocomm_t *pc = protocomm_new();
/* Endpoint UUIDs */ protocomm_ble_name_uuid_t nu_lookup_table[] = {
{"security_endpoint", 0xFF51}, {"echo_req_endpoint", 0xFF52} };
/* Config for protocomm_ble_start() */ protocomm_ble_config_t config = {
.service_uuid = { /* LSB <--------------------------------------* ---------------------------------------> MSB */ 0xfb, 0x34, 0x9b, 0x5f, 0x80, 0x00, 0x00, 0x80, 0x00, 0x10, 0x00, 0x00, 0xFF, 0xFF, 0x00, 0x00,
}, .nu_lookup_count = sizeof(nu_lookup_table)/sizeof(nu_lookup_ table[0]), .nu_lookup = nu_lookup_table };
/* Start protocomm layer on top of BLE */ protocomm_ble_start(pc, &config);
/* For protocomm_security0, Proof of Possession is not used, and can be kept NULL */
protocomm_set_security(pc, "security_endpoint", &protocomm_security0, NULL);
protocomm_add_endpoint(pc, "echo_req_endpoint", echo_req_handler, NULL);
return pc; }
/* Example function for stopping a protocomm instance */ void stop_pc(protocomm_t *pc) {
protocomm_remove_endpoint(pc, "echo_req_endpoint"); protocomm_unset_security(pc, "security_endpoint");
/* Stop BLE protocomm service */ protocomm_ble_stop(pc);
protocomm_delete(pc); }

Espressif Systems

961

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

API Reference
Header File · components/protocomm/include/common/protocomm.h

Functions protocomm_t *protocomm_new(void)
Create a new protocomm instance.

This API will return a new dynamically allocated protocomm instance with all elements of the protocomm_t structure initialized to NULL.

Return · protocomm_t* : On success · NULL : No memory for allocating new instance
void protocomm_delete(protocomm_t *pc) Delete a protocomm instance.

This API will deallocate a protocomm instance that was created using protocomm_new().

Parameters · [in] pc: Pointer to the protocomm instance to be deleted

esp_err_t protocomm_add_endpoint(protocomm_t *pc, const char *ep_name, comm_req_handler_t h, void *priv_data)
Add endpoint request handler for a protocomm instance.

proto-

This API will bind an endpoint handler function to the specified endpoint name, along with any private data that needs to be pass to the handler at the time of call.

Note · An endpoint must be bound to a valid protocomm instance, created using protocomm_new(). · This function internally calls the registered add_endpoint() function of the selected transport which is a member of the protocomm_t instance structure.
Return · ESP_OK : Success · ESP_FAIL : Error adding endpoint / Endpoint with this name already exists · ESP_ERR_NO_MEM : Error allocating endpoint resource · ESP_ERR_INVALID_ARG : Null instance/name/handler arguments
Parameters · [in] pc: Pointer to the protocomm instance · [in] ep_name: Endpoint identifier(name) string · [in] h: Endpoint handler function · [in] priv_data: Pointer to private data to be passed as a parameter to the handler function on call. Pass NULL if not needed.

esp_err_t protocomm_remove_endpoint(protocomm_t *pc, const char *ep_name) Remove endpoint request handler for a protocomm instance.

This API will remove a registered endpoint handler identified by an endpoint name.

Note · This function internally calls the registered remove_endpoint() function which is a member of the protocomm_t instance structure.
Return · ESP_OK : Success · ESP_ERR_NOT_FOUND : Endpoint with specified name doesnnt exist · ESP_ERR_INVALID_ARG : Null instance/name arguments
Parameters · [in] pc: Pointer to the protocomm instance · [in] ep_name: Endpoint identifier(name) string

Espressif Systems

962

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t protocomm_open_session(protocomm_t *pc, uint32_t session_id) Allocates internal resources for new transport session.

Note · An endpoint must be bound to a valid protocomm instance, created using protocomm_new().
Return · ESP_OK : Request handled successfully · ESP_ERR_NO_MEM : Error allocating internal resource · ESP_ERR_INVALID_ARG : Null instance/name arguments
Parameters · [in] pc: Pointer to the protocomm instance · [in] session_id: Unique ID for a communication session

esp_err_t protocomm_close_session(protocomm_t *pc, uint32_t session_id) Frees internal resources used by a transport session.

Note · An endpoint must be bound to a valid protocomm instance, created using protocomm_new().
Return · ESP_OK : Request handled successfully · ESP_ERR_INVALID_ARG : Null instance/name arguments
Parameters · [in] pc: Pointer to the protocomm instance · [in] session_id: Unique ID for a communication session

esp_err_t protocomm_req_handle(protocomm_t *pc, const char *ep_name, uint32_t session_id, const uint8_t *inbuf, ssize_t inlen, uint8_t **outbuf, ssize_t *outlen)
Calls the registered handler of an endpoint session for processing incoming data and generating the response.

Note · An endpoint must be bound to a valid protocomm instance, created using protocomm_new(). · Resulting output buffer must be deallocated by the caller.
Return · ESP_OK : Request handled successfully · ESP_FAIL : Internal error in execution of registered handler · ESP_ERR_NO_MEM : Error allocating internal resource · ESP_ERR_NOT_FOUND : Endpoint with specified name doesnnt exist · ESP_ERR_INVALID_ARG : Null instance/name arguments
Parameters · [in] pc: Pointer to the protocomm instance · [in] ep_name: Endpoint identifier(name) string · [in] session_id: Unique ID for a communication session · [in] inbuf: Input buffer contains input request data which is to be processed by the registered handler · [in] inlen: Length of the input buffer · [out] outbuf: Pointer to internally allocated output buffer, where the resulting response data output from the registered handler is to be stored · [out] outlen: Buffer length of the allocated output buffer

esp_err_t protocomm_set_security(protocomm_t *pc, const char *ep_name, const protocomm_security_t *sec, const protocomm_security_pop_t *pop)
Add endpoint security for a protocomm instance.

This API will bind a security session establisher to the specified endpoint name, along with any proof of possession that may be required for authenticating a session client.

Note

· An endpoint must be bound to a valid protocomm instance, created using protocomm_new(). · The choice of security can be any protocomm_security_t instance. Choices proto-
comm_security0 and protocomm_security1 are readily available.

Espressif Systems

963

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return · ESP_OK : Success · ESP_FAIL : Error adding endpoint / Endpoint with this name already exists · ESP_ERR_INVALID_STATE : Security endpoint already set · ESP_ERR_NO_MEM : Error allocating endpoint resource · ESP_ERR_INVALID_ARG : Null instance/name/handler arguments
Parameters · [in] pc: Pointer to the protocomm instance · [in] ep_name: Endpoint identifier(name) string · [in] sec: Pointer to endpoint security instance · [in] pop: Pointer to proof of possession for authenticating a client
esp_err_t protocomm_unset_security(protocomm_t *pc, const char *ep_name) Remove endpoint security for a protocomm instance.
This API will remove a registered security endpoint identified by an endpoint name.
Return · ESP_OK : Success · ESP_ERR_NOT_FOUND : Endpoint with specified name doesnnt exist · ESP_ERR_INVALID_ARG : Null instance/name arguments
Parameters · [in] pc: Pointer to the protocomm instance · [in] ep_name: Endpoint identifier(name) string
esp_err_t protocomm_set_version(protocomm_t *pc, const char *ep_name, const char *version) Set endpoint for version verification.
This API can be used for setting an application specific protocol version which can be verified by clients through the endpoint.
Note · An endpoint must be bound to a valid protocomm instance, created using protocomm_new().
Return · ESP_OK : Success · ESP_FAIL : Error adding endpoint / Endpoint with this name already exists · ESP_ERR_INVALID_STATE : Version endpoint already set · ESP_ERR_NO_MEM : Error allocating endpoint resource · ESP_ERR_INVALID_ARG : Null instance/name/handler arguments
Parameters · [in] pc: Pointer to the protocomm instance · [in] ep_name: Endpoint identifier(name) string · [in] version: Version identifier(name) string
esp_err_t protocomm_unset_version(protocomm_t *pc, const char *ep_name) Remove version verification endpoint from a protocomm instance.
This API will remove a registered version endpoint identified by an endpoint name.
Return · ESP_OK : Success · ESP_ERR_NOT_FOUND : Endpoint with specified name doesnnt exist · ESP_ERR_INVALID_ARG : Null instance/name arguments
Parameters · [in] pc: Pointer to the protocomm instance · [in] ep_name: Endpoint identifier(name) string
Type Definitions typedef esp_err_t (*protocomm_req_handler_t)(uint32_t session_id, const uint8_t *inbuf,
ssize_t inlen, uint8_t **outbuf, ssize_t *outlen, void *priv_data) Function prototype for protocomm endpoint handler.

Espressif Systems

964

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
typedef struct protocomm protocomm_t This structure corresponds to a unique instance of protocomm returned when the API protocomm_new() is called. The remaining Protocomm APIs require this object as the first parameter. Note Structure of the protocomm object is kept private
Header File · components/protocomm/include/security/protocomm_security.h
Structures struct protocomm_security_pop
Proof Of Possession for authenticating a secure session.
Public Members
const uint8_t *data Pointer to buffer containing the proof of possession data
uint16_t len Length (in bytes) of the proof of possession data
struct protocomm_security Protocomm security object structure. The member functions are used for implementing secure protocomm sessions. Note This structure should not have any dynamic members to allow re-entrancy
Public Members
int ver Unique version number of security implementation
esp_err_t (*init)(protocomm_security_handle_t *handle) Function for initializing/allocating security infrastructure
esp_err_t (*cleanup)(protocomm_security_handle_t handle) Function for deallocating security infrastructure
esp_err_t (*new_transport_session)(protocomm_security_handle_t handle, uint32_t session_id)
Starts new secure transport session with specified ID esp_err_t (*close_transport_session)(protocomm_security_handle_t handle, uint32_t ses-
sion_id) Closes a secure transport session with specified ID esp_err_t (*security_req_handler)(protocomm_security_handle_t handle, const proto-
comm_security_pop_t *pop, uint32_t session_id, const uint8_t *inbuf, ssize_t inlen, uint8_t **outbuf, ssize_t *outlen, void *priv_data) Handler function for authenticating connection request and establishing secure session esp_err_t (*encrypt)(protocomm_security_handle_t handle, uint32_t session_id, const uint8_t *inbuf, ssize_t inlen, uint8_t *outbuf, ssize_t *outlen) Function which implements the encryption algorithm esp_err_t (*decrypt)(protocomm_security_handle_t handle, uint32_t session_id, const uint8_t *inbuf, ssize_t inlen, uint8_t *outbuf, ssize_t *outlen) Function which implements the decryption algorithm

Espressif Systems

965

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Type Definitions typedef struct protocomm_security_pop protocomm_security_pop_t
Proof Of Possession for authenticating a secure session. typedef void *protocomm_security_handle_t typedef struct protocomm_security protocomm_security_t
Protocomm security object structure. The member functions are used for implementing secure protocomm sessions. Note This structure should not have any dynamic members to allow re-entrancy
Header File · components/protocomm/include/security/protocomm_security0.h
Header File · components/protocomm/include/security/protocomm_security1.h
Header File · components/protocomm/include/transports/protocomm_httpd.h
Functions esp_err_t protocomm_httpd_start(protocomm_t *pc, const protocomm_httpd_config_t *config)
Start HTTPD protocomm transport. This API internally creates a framework to allow endpoint registration and security configuration for the protocomm. Note This is a singleton. ie. Protocomm can have multiple instances, but only one instance can be bound to
an HTTP transport layer. Return
· ESP_OK : Success · ESP_ERR_INVALID_ARG : Null arguments · ESP_ERR_NOT_SUPPORTED : Transport layer bound to another protocomm instance · ESP_ERR_INVALID_STATE : Transport layer already bound to this protocomm instance · ESP_ERR_NO_MEM : Memory allocation for server resource failed · ESP_ERR_HTTPD_* : HTTP server error on start Parameters · [in] pc: Protocomm instance pointer obtained from protocomm_new() · [in] config: Pointer to config structure for initializing HTTP server esp_err_t protocomm_httpd_stop(protocomm_t *pc) Stop HTTPD protocomm transport. This API cleans up the HTTPD transport protocomm and frees all the handlers registered with the protocomm. Return · ESP_OK : Success · ESP_ERR_INVALID_ARG : Null / incorrect protocomm instance pointer Parameters · [in] pc: Same protocomm instance that was passed to protocomm_httpd_start()
Unions union protocomm_httpd_config_data_t
#include <protocomm_httpd.h> Protocomm HTTPD Configuration Data

Espressif Systems

966

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Public Members
void *handle HTTP Server Handle, if ext_handle_provided is set to true
protocomm_http_server_config_t config HTTP Server Configuration, if a server is not already active
Structures struct protocomm_http_server_config_t
Config parameters for protocomm HTTP server.
Public Members
uint16_t port Port on which the HTTP server will listen
size_t stack_size Stack size of server task, adjusted depending upon stack usage of endpoint handler
unsigned task_priority Priority of server task
struct protocomm_httpd_config_t Config parameters for protocomm HTTP server.
Public Members
bool ext_handle_provided Flag to indicate of an external HTTP Server Handle has been provided. In such as case, protocomm will use the same HTTP Server and not start a new one internally.
protocomm_httpd_config_data_t data Protocomm HTTPD Configuration Data
Macros PROTOCOMM_HTTPD_DEFAULT_CONFIG()
Header File · components/protocomm/include/transports/protocomm_ble.h
Functions esp_err_t protocomm_ble_start(protocomm_t *pc, const protocomm_ble_config_t *config)
Start Bluetooth Low Energy based transport layer for provisioning. Initialize and start required BLE service for provisioning. This includes the initialization for characteristics/service for BLE. Return
· ESP_OK : Success · ESP_FAIL : Simple BLE start error · ESP_ERR_NO_MEM : Error allocating memory for internal resources · ESP_ERR_INVALID_STATE : Error in ble config · ESP_ERR_INVALID_ARG : Null arguments Parameters · [in] pc: Protocomm instance pointer obtained from protocomm_new() · [in] config: Pointer to config structure for initializing BLE

Espressif Systems

967

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t protocomm_ble_stop(protocomm_t *pc) Stop Bluetooth Low Energy based transport layer for provisioning.
Stops service/task responsible for BLE based interactions for provisioning
Note You might want to optionally reclaim memory from Bluetooth. Refer to the documentation of esp_bt_mem_release in that case.
Return · ESP_OK : Success · ESP_FAIL : Simple BLE stop error · ESP_ERR_INVALID_ARG : Null / incorrect protocomm instance
Parameters · [in] pc: Same protocomm instance that was passed to protocomm_ble_start()

Structures struct name_uuid
This structure maps handler required by protocomm layer to UUIDs which are used to uniquely identify BLE characteristics from a smartphone or a similar client device.

Public Members
const char *name Name of the handler, which is passed to protocomm layer
uint16_t uuid UUID to be assigned to the BLE characteristic which is mapped to the handler
struct protocomm_ble_config Config parameters for protocomm BLE service.

Public Members
char device_name[MAX_BLE_DEVNAME_LEN] BLE device name being broadcast at the time of provisioning
uint8_t service_uuid[BLE_UUID128_VAL_LENGTH] 128 bit UUID of the provisioning service
uint8_t *manufacturer_data BLE device manufacturer data pointer in advertisement
ssize_t manufacturer_data_len BLE device manufacturer data length in advertisement
ssize_t nu_lookup_count Number of entries in the Name-UUID lookup table
protocomm_ble_name_uuid_t *nu_lookup Pointer to the Name-UUID lookup table

Macros MAX_BLE_DEVNAME_LEN
BLE device name cannot be larger than this value 31 bytes (max scan response size) - 1 byte (length) - 1 byte (type) = 29 bytes BLE_UUID128_VAL_LENGTH
MAX_BLE_MANUFACTURER_DATA_LEN Theoretically, the limit for max manufacturer length remains same as BLE device name i.e. 31 bytes (max scan response size) - 1 byte (length) - 1 byte (type) = 29 bytes However, manufacturer data goes along with BLE device name in scan response. So, it is important to understand the actual length should be smaller than (29 - (BLE device name length) - 2).

Espressif Systems

968

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Type Definitions typedef struct name_uuid protocomm_ble_name_uuid_t
This structure maps handler required by protocomm layer to UUIDs which are used to uniquely identify BLE characteristics from a smartphone or a similar client device. typedef struct protocomm_ble_config protocomm_ble_config_t Config parameters for protocomm BLE service.
2.5.2 Unified Provisioning
Overview
Unified provisioning support in the ESP-IDF provides an extensible mechanism to the developers to configure the device with the Wi-Fi credentials and/or other custom configuration using various transports and different security schemes. Depending on the use-case it provides a complete and ready solution for Wi-Fi network provisioning along with example iOS and Android applications. Or developers can extend the device-side and phone-app side implementations to accommodate their requirements for sending additional configuration data. Following are the important features of this implementation.
1. Extensible Protocol: The protocol is completely flexible and it offers the ability for the developers to send custom configuration in the provisioning process. The data representation too is left to the application to decide.
2. Transport Flexibility: The protocol can work on Wi-Fi (SoftAP + HTTP server) or on BLE as a transport protocol. The framework provides an ability to add support for any other transport easily as long as commandresponse behaviour can be supported on the transport.
3. Security Scheme Flexibility: Itns understood that each use-case may require different security scheme to secure the data that is exchanged in the provisioning process. Some applications may work with SoftAP thatns WPA2 protected or BLE with ojust-workspsecurity. Or the applications may consider the transport to be insecure and may want application level security. The unified provisioning framework allows application to choose the security as deemed suitable.
4. Compact Data Representation: The protocol uses Google Protobufs as a data representation for session setup and Wi-Fi provisioning. They provide a compact data representation and ability to parse the data in multiple programming languages in native format. Please note that this data representation is not forced on application specific data and the developers may choose the representation of their choice.
Typical Provisioning Process
Deciding on Transport
Unified provisioning subsystem supports Wi-Fi (SoftAP+HTTP server) and BLE (GATT based) transport schemes. Following points need to be considered while selecting the best possible transport for provisioning.
1. BLE based transport has an advantage that in the provisioning process, the BLE communication channel stays intact between the device and the client. That provides reliable provisioning feedback.
2. BLE based provisioning implementation makes the user-experience better from the phone apps as on Android and iOS both, the phone app can discover and connect to the device without requiring user to go out of the phone app
3. BLE transport however consumes ~110KB memory at runtime. If the product does not use the BLE or BT functionality after provisioning is done, almost all the memory can be reclaimed back and can be added into the heap.
4. SoftAP based transport is highly interoperable; however as the same radio is shared between SoftAP and Station interface, the transport is not reliable in the phase when the Wi-Fi connection to external AP is attempted. Also, the client may roam back to different network when the SoftAP changes the channel at the time of Station connection.
5. SoftAP transport does not require much additional memory for the Wi-Fi use-cases 6. SoftAP based provisioning requires the phone app user to go tooSystem Settingspto connect to Wi-Fi network
hosted by the device in case of iOS. The discovery (scanning) as well as connection API is not available for the iOS applications.

Espressif Systems

969

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Espressif Systems

Fig. 26: Typical Provisioning Process

970

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Deciding on Security
Depending on the transport and other constraints the security scheme needs to be selected by the application developers. Following considerations need to be given from the provisioning security perspective: 1. The configuration data sent from the client to the device and the response has to be secured. 2. The client should authenticate the device it is connected to. 3. The device manufacturer may choose proof-of-possession - a unique per device secret to be entered on the provisioning client as a security measure to make sure that the user can provisions the device in the possession. There are two levels of security schemes. The developer may select one or combination depending on requirements.
1. Transport Security: SoftAP provisioning may choose WPA2 protected security with unique per-device passphrase. Per-device unique passphrase can also act as a proof-of-possession. For BLE, ojust-worksp security can be used as a transport level security after understanding the level of security it provides.
2. Application Security: The unified provisioning subsystem provides application level security (security1) that provides data protection and authentication (through proof-of-possession) if the application does not use the transport level security or if the transport level security is not sufficient for the use-case.
Device Discovery
The advertisement and device discovery is left to the application and depending on the protocol chosen, the phone apps and device firmware application can choose appropriate method to advertise and discovery. For the SoftAP+HTTP transport, typically the SSID (network name) of the AP hosted by the device can be used for discovery. For the BLE transport device name or primary service included in the advertisement or combination of both can be used for discovery.
Architecture
The below diagram shows architecture of unified provisioning. It relies on the base layer called Protocol Communication (Protocol Communication) which provides a framework for security schemes and transport mechanisms. Wi-Fi Provisioning layer uses Protocomm to provide simple callbacks to the application for setting the configuration and getting the Wi-Fi status. The application has control over implementation of these callbacks. In addition application can directly use protocomm to register custom handlers. Application creates a protocomm instance which is mapped to a specific transport and specific security scheme. Each transport in the protocomm has a concept of anoend-pointpwhich corresponds to logical channel for communication for specific type of information. For example security handshake happens on a different endpoint than the Wi-Fi configuration endpoint. Each end-point is identified using a string and depending on the transport internal representation of the end-point changes. In case of SoftAP+HTTP transport the end-point corresponds to URI whereas in case of BLE the end-point corresponds to GATT characteristic with specific UUID. Developers can create custom end-points and implement handler for the data that is received or sent over the same end-point.
Security Schemes
At present unified provisioning supports two security schemes: 1. Security0 - No security (No encryption) 2. Security1 - Curve25519 based key exchange, shared key derivation and AES256-CTR mode encryption of the data. It supports two modes :
a. Authorized - Proof of Possession (PoP) string used to authorize session and derive shared key b. No Auth (Null PoP) - Shared key derived through key exchange only Security1 scheme details are shown in the below sequence diagram

Espressif Systems

971

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Fig. 27: Unified Provisioning Architecture
Sample Code
Please refer to Protocol Communication and Wi-Fi Provisioning for API guides and code snippets on example usage. Application implementation can be found as an example under provisioning.
Provisioning Tools
Provisioning applications are available for various platforms, along with source code: · Android: ­ BLE Provisioning app on Play Store. ­ SoftAP Provisioning app on Play Store. ­ Source code on GitHub: esp-idf-provisioning-android. · iOS: ­ BLE Provisioning app on app store. ­ SoftAP Provisioning app on app Store. ­ Source code on GitHub: esp-idf-provisioning-ios. · Linux/MacOS/Windows : tools/esp_prov (a python based command line tool for provisioning)
The phone applications offer simple UI and thus more user centric, while the command line application is useful as a debugging tool for developers.
2.5.3 Wi-Fi Provisioning
Overview
This component provides APIs that control Wi-Fi provisioning service for receiving and configuring Wi-Fi credentials over SoftAP or BLE transport via secure Protocol Communication (protocomm) sessions. The set of

Espressif Systems

972

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Espressif Systems

Fig. 28: Security1

973

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

wifi_prov_mgr_ APIs help in quickly implementing a provisioning service having necessary features with minimal amount of code and sufficient flexibility.

Initialization wifi_prov_mgr_init() is called to configure and initialize the provisioning manager and thus this must be called prior to invoking any other wifi_prov_mgr_ APIs. Note that the manager relies on other components of IDF, namely NVS, TCP/IP, Event Loop and Wi-Fi (and optionally mDNS), hence these must be initialized beforehand. The manager can be de-initialized at any moment by making a call to wifi_prov_mgr_deinit().
wifi_prov_mgr_config_t config = { .scheme = wifi_prov_scheme_ble, .scheme_event_handler = WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BTDM
};
ESP_ERROR_CHECK( wifi_prov_mgr_init(config) );
The configuration structure wifi_prov_mgr_config_t has a few fields to specify the behavior desired of the manager :
· scheme : This is used to specify the provisioning scheme. Each scheme corresponds to one of the modes of transport supported by protocomm. Hence, we have three options : ­ wifi_prov_scheme_ble : BLE transport and GATT Server for handling provisioning commands ­ wifi_prov_scheme_softap : Wi-Fi SoftAP transport and HTTP Server for handling provisioning commands ­ wifi_prov_scheme_console : Serial transport and console for handling provisioning commands
· scheme_event_handler : An event handler defined along with scheme. Choosing appropriate scheme specific event handler allows the manager to take care of certain matters automatically. Presently this is not used for either SoftAP or Console based provisioning, but is very convenient for BLE. To understand how, we must recall that Bluetooth requires quite some amount of memory to function and once provisioning is finished, the main application may want to reclaim back this memory (or part of it, if it needs to use either BLE or classic BT). Also, upon every future reboot of a provisioned device, this reclamation of memory needs to be performed again. To reduce this complication in using wifi_prov_scheme_ble, the scheme specific handlers have been defined, and depending upon the chosen handler, the BLE / classic BT / BTDM memory will be freed automatically when the provisioning manager is de-initialized. The available options are: ­ WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BTDM - Free both classic BT and BLE (BTDM) memory. Used when main application doesnnt require Bluetooth at all. ­ WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BLE - Free only BLE memory. Used when main application requires classic BT. ­ WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BT - Free only classic BT. Used when main application requires BLE. In this case freeing happens right when the manager is initialized. ­ WIFI_PROV_EVENT_HANDLER_NONE - Donnt use any scheme specific handler. Used when provisioning scheme is not BLE (i.e. SoftAP or Console), or when main application wants to handle the memory reclaiming on its own, or needs both BLE and classic BT to function.
· app_event_handler (Deprecated) : It is now recommended to catch WIFI_PROV_EVENT``s that are emitted to the default event loop handler. See definition of ``wifi_prov_cb_event_t for the list of events that are generated by the provisioning service. Here is an excerpt showing some of the provisioning events:
static void event_handler(void* arg, esp_event_base_t event_base, int event_id, void* event_data)
{ if (event_base == WIFI_PROV_EVENT) { switch (event_id) { case WIFI_PROV_START: ESP_LOGI(TAG, "Provisioning started"); (continues on next page)

Espressif Systems

974

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)

break;

case WIFI_PROV_CRED_RECV: {

wifi_sta_config_t *wifi_sta_cfg = (wifi_sta_config_t

*)event_data;

ESP_LOGI(TAG, "Received Wi-Fi credentials"

"\n\tSSID

: %s\n\tPassword : %s",

(const char *) wifi_sta_cfg->ssid,

(const char *) wifi_sta_cfg->password);

break;

}

case WIFI_PROV_CRED_FAIL: {

wifi_prov_sta_fail_reason_t *reason = (wifi_prov_sta_fail_

reason_t *)event_data;

ESP_LOGE(TAG, "Provisioning failed!\n\tReason : %s"

"\n\tPlease reset to factory and retry

provisioning",

(*reason == WIFI_PROV_STA_AUTH_ERROR) ?

"Wi-Fi station authentication failed" : "Wi-Fi

access-point not found");

break;

}

case WIFI_PROV_CRED_SUCCESS:

ESP_LOGI(TAG, "Provisioning successful");

break;

case WIFI_PROV_END:

/* De-initialize manager once provisioning is finished */

wifi_prov_mgr_deinit();

break;

default:

break;

}

}

}

The manager can be de-initialized at any moment by making a call to wifi_prov_mgr_deinit().

Check Provisioning State Whether device is provisioned or not can be checked at runtime by calling wifi_prov_mgr_is_provisioned(). This internally checks if the Wi-Fi credentials are stored in NVS.
Note that presently manager does not have its own NVS namespace for storage of Wi-Fi credentials, instead it relies on the esp_wifi_ APIs to set and get the credentials stored in NVS from the default location.
If provisioning state needs to be reset, any of the following approaches may be taken :
· the associated part of NVS partition has to be erased manually · main application must implement some logic to call esp_wifi_ APIs for erasing the credentials
at runtime · main application must implement some logic to force start the provisioning irrespective of the
provisioning state
bool provisioned = false; ESP_ERROR_CHECK( wifi_prov_mgr_is_provisioned(&provisioned) );

Start Provisioning Service At the time of starting provisioning we need to specify a service name and the corresponding key. These translate to :
· Wi-Fi SoftAP SSID and passphrase, respectively, when scheme is wifi_prov_scheme_softap · BLE Device name (service key is ignored) when scheme is wifi_prov_scheme_ble
Also, since internally the manager uses protocomm, we have the option of choosing one of the security features provided by it :

Espressif Systems

975

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· Security 1 is secure communication which consists of a prior handshake involving X25519 key exchange along with authentication using a proof of possession (pop), followed by AES-CTR for encryption/decryption of subsequent messages
· Security 0 is simply plain text communication. In this case the pop is simply ignored See Provisioning for details about the security features.
const char *service_name = "my_device"; const char *service_key = "password";
wifi_prov_security_t security = WIFI_PROV_SECURITY_1; const char *pop = "abcd1234";
ESP_ERROR_CHECK( wifi_prov_mgr_start_provisioning(security, pop, service_ name, service_key) );
The provisioning service will automatically finish only if it receives valid Wi-Fi AP credentials followed by successfully connection of device to the AP (IP obtained). Regardless of that, the provisioning service can be stopped at any moment by making a call to wifi_prov_mgr_stop_provisioning().
Note: If the device fails to connect with the provided credentials, it wonnt accept new credentials anymore, but the provisioning service will keep on running (only to convey failure to the client), until the device is restarted. Upon restart the provisioning state will turn out to be true this time (as credentials will be found in NVS), but device will again fail to connect with those same credentials (unless an AP with the matching credentials somehow does become available). This situation can be fixed by resetting the credentials in NVS or force starting the provisioning service. This has been explained above in Check Provisioning State.

Waiting For Completion Typically, the main application will wait for the provisioning to finish, then de-initialize the manager to free up resources and finally start executing its own logic.

There are two ways for making this possible. wifi_prov_mgr_wait().

The simpler way is to use a blocking call to

// Start provisioning service ESP_ERROR_CHECK( wifi_prov_mgr_start_provisioning(security, pop, service_ name, service_key) );

// Wait for service to complete wifi_prov_mgr_wait();

// Finally de-initialize the manager wifi_prov_mgr_deinit();

The other way is to use the default event loop handler to catch WIFI_PROV_EVENT``s and call :cpp:func:`wifi_prov_mgr_deinit()` when event ID is ``WIFI_PROV_END:
static void event_handler(void* arg, esp_event_base_t event_base, int event_id, void* event_data)
{ if (event_base == WIFI_PROV_EVENT && event_id == WIFI_PROV_END) { /* De-initialize manager once provisioning is finished */ wifi_prov_mgr_deinit(); }
}

User Side Implementation When the service is started, the device to be provisioned is identified by the advertised service name which, depending upon the selected transport, is either the BLE device name or the SoftAP SSID.

Espressif Systems

976

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

When using SoftAP transport, for allowing service discovery, mDNS must be initialized before starting provisioning. In this case the hostname set by the main application is used, and the service type is internally set to _esp_wifi_prov.
When using BLE transport, a custom 128 bit UUID should be set using wifi_prov_scheme_ble_set_service_uuid(). This UUID will be included in the BLE advertisement and will correspond to the primary GATT service that provides provisioning endpoints as GATT characteristics. Each GATT characteristic will be formed using the primary service UUID as base, with different auto assigned 12th and 13th bytes (assume counting starts from 0th byte). Since, an endpoint characteristic UUID is auto assigned, it shouldnnt be used to identify the endpoint. Instead, client side applications should identify the endpoints by reading the User Characteristic Description (0x2901) descriptor for each characteristic, which contains the endpoint name of the characteristic. For example, if the service UUID is set to 55cc035e-fb27-4f80-be02-3c60828b7451, each endpoint characteristic will be assigned a UUID like 55cc____-fb27-4f80-be02-3c60828b7451, with unique values at the 12th and 13th bytes.
Once connected to the device, the provisioning related protocomm endpoints can be identified as follows :

Endpoint Name (BLE + GATT Server) provsession prov-scan
provconfig proto-ver

Table 13: Endpoints provided by Provisioning Service
URI (SoftAP + HTTP Server Description + mDNS)

http://<mdnshostname>.local/prov-session http://wifi-prov.local/ prov-scan http://<mdnshostname>.local/prov-config http://<mdnshostname>.local/proto-ver

Security endpoint used for session establishment Endpoint used for starting Wi-Fi scan and receiving scan results Endpoint used for configuring Wi-Fi credentials on device Endpoint for retrieving version info

Immediately after connecting, the client application may fetch the version / capabilities information from the proto-ver endpoint. All communications to this endpoint are un-encrypted, hence necessary information (that may be relevant for deciding compatibility) can be retrieved before establishing a secure session. The response is in JSON format and looks like : prov: { ver: v1.1, cap: [no_pop] }, my_app: { ver: 1.345, cap: [cloud, local_ctrl] },..... Here label prov provides provisioning service version (ver) and capabilities (cap). For now, only no_pop capability is supported, which indicates that the service doesnnt require proof of possession for authentication. Any application related version / capabilities will be given by other labels (like my_app in this example). These additional fields are set using wifi_prov_mgr_set_app_info().
User side applications need to implement the signature handshaking required for establishing and authenticating secure protocomm sessions as per the security scheme configured for use (this is not needed when manager is configured to use protocomm security 0).
See Unified Provisioning for more details about the secure handshake and encryption used. Applications must use the .proto files found under protocomm/proto, which define the Protobuf message structures supported by prov-session endpoint.
Once a session is established, Wi-Fi credentials are configured using the following set of wifi_config commands, serialized as Protobuf messages (the corresponding .proto files can be found under wifi_provisioning/proto) :
· get_status - For querying the Wi-Fi connection status. The device will respond with a status which will be one of connecting / connected / disconnected. If status is disconnected, a disconnection reason will also be included in the status response.
· set_config - For setting the Wi-Fi connection credentials · apply_config - For applying the credentials saved during set_config and start the Wi-Fi station
After session establishment, client can also request Wi-Fi scan results from the device. The results returned is a list of AP SSIDs, sorted in descending order of signal strength. This allows client applications to display APs nearby to the device at the time of provisioning, and users can select one of the SSIDs and provide the password which is

Espressif Systems

977

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

then sent using the wifi_config commands described above. The wifi_scan endpoint supports the following protobuf commands :
· scan_start - For starting Wi-Fi scan with various options : ­ blocking (input) - If true, the command returns only when the scanning is finished ­ passive (input) - If true scan is started in passive mode (this may be slower) instead of active mode ­ group_channels (input) - This specifies whether to scan all channels in one go (when zero) or perform scanning of channels in groups, with 120ms delay between scanning of consecutive groups, and the value of this parameter sets the number of channels in each group. This is useful when transport mode is SoftAP, where scanning all channels in one go may not give the Wi-Fi driver enough time to send out beacons, and hence may cause disconnection with any connected stations. When scanning in groups, the manager will wait for atleast 120ms after completing scan on a group of channels, and thus allow the driver to send out the beacons. For example, given that the total number of Wi-Fi channels is 14, then setting group_channels to 4, will create 5 groups, with each group having 3 channels, except the last one which will have 14 % 3 = 2 channels. So, when scan is started, the first 3 channels will be scanned, followed by a 120ms delay, and then the next 3 channels, and so on, until all the 14 channels have been scanned. One may need to adjust this parameter as having only few channels in a group may slow down the overall scan time, while having too many may again cause disconnection. Usually a value of 4 should work for most cases. Note that for any other mode of transport, e.g. BLE, this can be safely set to 0, and hence achieve the fastest overall scanning time. ­ period_ms (input) - Scan parameter specifying how long to wait on each channel
· scan_status - Gives the status of scanning process : ­ scan_finished (output) - When scan has finished this returns true ­ result_count (output) - This gives the total number of results obtained till now. If scan is yet happening this number will keep on updating
· scan_result - For fetching scan results. This can be called even if scan is still on going ­ start_index (input) - Starting index from where to fetch the entries from the results list ­ count (input) - Number of entries to fetch from the starting index ­ entries (output) - List of entries returned. Each entry consists of ssid, channel and rssi information

Additional Endpoints In case users want to have some additional protocomm endpoints customized to their requirements, this is done in two steps. First is creation of an endpoint with a specific name, and the second step is the registration of a handler for this endpoint. See protocomm for the function signature of an endpoint handler. A custom endpoint must be created after initialization and before starting the provisioning service. Whereas, the protocomm handler is registered for this endpoint only after starting the provisioning service.
wifi_prov_mgr_init(config); wifi_prov_mgr_endpoint_create("custom-endpoint"); wifi_prov_mgr_start_provisioning(security, pop, service_name, service_ key); wifi_prov_mgr_endpoint_register("custom-endpoint", custom_ep_handler, custom_ep_data);
When the provisioning service stops, the endpoint is unregistered automatically.
One can also choose to call wifi_prov_mgr_endpoint_unregister() to manually deactivate an endpoint at runtime. This can also be used to deactivate the internal endpoints used by the provisioning service.

When / How To Stop Provisioning Service? The default behavior is that once the device successfully connects using the Wi-Fi credentials set by the apply_config command, the provisioning service will be stopped (and BLE / SoftAP turned off) automatically after responding to the next get_status command. If get_status command is not received by the device, the service will be stopped after a 30s timeout.
On the other hand, if device was not able to connect using the provided Wi-Fi credentials, due to incorrect SSID / passphrase, the service will keep running, and get_status will keep responding with disconnected status and reason for disconnection. Any further attempts to provide another set of Wi-Fi credentials, will be rejected. These credentials will be preserved, unless the provisioning service is force started, or NVS erased.
If this default behavior is not desired, it can be disabled by calling wifi_prov_mgr_disable_auto_stop(). Now the provisioning service will only be stopped after an explicit call to

Espressif Systems

978

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
wifi_prov_mgr_stop_provisioning(), which returns immediately after scheduling a task for stopping the service. The service stops after a certain delay and WIFI_PROV_END event gets emitted. This delay is specified by the argument to wifi_prov_mgr_disable_auto_stop(). The customized behavior is useful for applications which want the provisioning service to be stopped some time after the Wi-Fi connection is successfully established. For example, if the application requires the device to connect to some cloud service and obtain another set of credentials, and exchange this credentials over a custom protocomm endpoint, then after successfully doing so stop the provisioning service by calling wifi_prov_mgr_stop_provisioning() inside the protocomm handler itself. The right amount of delay ensures that the transport resources are freed only after the response from the protocomm handler reaches the client side application.
Application Examples
For complete example implementation see provisioning/wifi_prov_mgr
Provisioning Tools
Provisioning applications are available for various platforms, along with source code: · Android: ­ BLE Provisioning app on Play Store. ­ SoftAP Provisioning app on Play Store. ­ Source code on GitHub: esp-idf-provisioning-android. · iOS: ­ BLE Provisioning app on app store. ­ SoftAP Provisioning app on app Store. ­ Source code on GitHub: esp-idf-provisioning-ios. · Linux/MacOS/Windows : tools/esp_prov (a python based command line tool for provisioning)
The phone applications offer simple UI and thus more user centric, while the command line application is useful as a debugging tool for developers.
API Reference
Header File · components/wifi_provisioning/include/wifi_provisioning/manager.h
Functions esp_err_t wifi_prov_mgr_init(wifi_prov_mgr_config_t config)
Initialize provisioning manager instance. Configures the manager and allocates internal resources Configuration specifies the provisioning scheme (transport) and event handlers Event WIFI_PROV_INIT is emitted right after initialization is complete Return
· ESP_OK : Success · ESP_FAIL : Fail Parameters · [in] config: Configuration structure void wifi_prov_mgr_deinit(void) Stop provisioning (if running) and release resource used by the manager. Event WIFI_PROV_DEINIT is emitted right after de-initialization is finished

Espressif Systems

979

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
If provisioning service is still active when this API is called, it first stops the service, hence emitting WIFI_PROV_END, and then performs the de-initialization
esp_err_t wifi_prov_mgr_is_provisioned(bool *provisioned) Checks if device is provisioned.
This checks if Wi-Fi credentials are present on the NVS
The Wi-Fi credentials are assumed to be kept in the same NVS namespace as used by esp_wifi component
If one were to call esp_wifi_set_config() directly instead of going through the provisioning process, this function will still yield true (i.e. device will be found to be provisioned)
Note Calling wifi_prov_mgr_start_provisioning() automatically resets the provision state, irrespective of what the state was prior to making the call.
Return · ESP_OK : Retrieved provision state successfully · ESP_FAIL : Wi-Fi not initialized · ESP_ERR_INVALID_ARG : Null argument supplied · ESP_ERR_INVALID_STATE : Manager not initialized
Parameters · [out] provisioned: True if provisioned, else false
esp_err_t wifi_prov_mgr_start_provisioning(wifi_prov_security_t security, const char *pop, const char *service_name, const char *service_key)
Start provisioning service.
This starts the provisioning service according to the scheme configured at the time of initialization. For scheme :
· wifi_prov_scheme_ble : This starts protocomm_ble, which internally initializes BLE transport and starts GATT server for handling provisioning requests
· wifi_prov_scheme_softap : This activates SoftAP mode of Wi-Fi and starts protocomm_httpd, which internally starts an HTTP server for handling provisioning requests (If mDNS is active it also starts advertising service with type _esp_wifi_prov._tcp)
Event WIFI_PROV_START is emitted right after provisioning starts without failure
Note This API will start provisioning service even if device is found to be already provisioned, i.e. wifi_prov_mgr_is_provisioned() yields true
Return · ESP_OK : Provisioning started successfully · ESP_FAIL : Failed to start provisioning service · ESP_ERR_INVALID_STATE : Provisioning manager not initialized or already started
Parameters · [in] security: Specify which protocomm security scheme to use : ­ WIFI_PROV_SECURITY_0 : For no security ­ WIFI_PROV_SECURITY_1 : x25519 secure handshake for session establishment followed by AES-CTR encryption of provisioning messages · [in] pop: Pointer to proof of possession string (NULL if not needed). This is relevant only for protocomm security 1, in which case it is used for authenticating secure session · [in] service_name: Unique name of the service. This translates to: ­ Wi-Fi SSID when provisioning mode is softAP ­ Device name when provisioning mode is BLE · [in] service_key: Key required by client to access the service (NULL if not needed). This translates to: ­ Wi-Fi password when provisioning mode is softAP ­ ignored when provisioning mode is BLE
void wifi_prov_mgr_stop_provisioning(void) Stop provisioning service.

Espressif Systems

980

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

If provisioning service is active, this API will initiate a process to stop the service and return. Once the service actually stops, the event WIFI_PROV_END will be emitted.
If wifi_prov_mgr_deinit() is called without calling this API first, it will automatically stop the provisioning service and emit the WIFI_PROV_END, followed by WIFI_PROV_DEINIT, before returning.
This API will generally be used along with wifi_prov_mgr_disable_auto_stop() in the scenario when the main application has registered its own endpoints, and wishes that the provisioning service is stopped only when some protocomm command from the client side application is received.
Calling this API inside an endpoint handler, with sufficient cleanup_delay, will allow the response / acknowledgment to be sent successfully before the underlying protocomm service is stopped.
Cleaup_delay is set when calling wifi_prov_mgr_disable_auto_stop(). If not specified, it defaults to 1000ms.
For straightforward cases, using this API is usually not necessary as provisioning is stopped automatically once WIFI_PROV_CRED_SUCCESS is emitted. Stopping is delayed (maximum 30 seconds) thus allowing the client side application to query for Wi-Fi state, i.e. after receiving the first query and sending Wi-Fi state connected response the service is stopped immediately.
void wifi_prov_mgr_wait(void) Wait for provisioning service to finish.
Calling this API will block until provisioning service is stopped i.e. till event WIFI_PROV_END is emitted.
This will not block if provisioning is not started or not initialized.
esp_err_t wifi_prov_mgr_disable_auto_stop(uint32_t cleanup_delay) Disable auto stopping of provisioning service upon completion.
By default, once provisioning is complete, the provisioning service is automatically stopped, and all endpoints (along with those registered by main application) are deactivated.
This API is useful in the case when main application wishes to close provisioning service only after it receives some protocomm command from the client side app. For example, after connecting to Wi-Fi, the device may want to connect to the cloud, and only once that is successfully, the device is said to be fully configured. But, then it is upto the main application to explicitly call wifi_prov_mgr_stop_provisioning() later when the device is fully configured and the provisioning service is no longer required.
Note This must be called before executing wifi_prov_mgr_start_provisioning() Return
· ESP_OK : Success · ESP_ERR_INVALID_STATE : Manager not initialized or provisioning service already started Parameters · [in] cleanup_delay: Sets the delay after which the actual cleanup of transport related re-
sources is done after a call to wifi_prov_mgr_stop_provisioning() returns. Minimum allowed value is 100ms. If not specified, this will default to 1000ms.
esp_err_t wifi_prov_mgr_set_app_info(const char *label, const char *version, const char **capabilities, size_t total_capabilities)
Set application version and capabilities in the JSON data returned by proto-ver endpoint.
This function can be called multiple times, to specify information about the various application specific services running on the device, identified by unique labels.
The provisioning service itself registers an entry in the JSON data, by the label oprovp, containing only provisioning service version and capabilities. Application services should use a label other than oprovpso as not to overwrite this.
Note This must be called before executing wifi_prov_mgr_start_provisioning() Return
· ESP_OK : Success · ESP_ERR_INVALID_STATE : Manager not initialized or provisioning service already started · ESP_ERR_NO_MEM : Failed to allocate memory for version string · ESP_ERR_INVALID_ARG : Null argument Parameters

Espressif Systems

981

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· [in] label: String indicating the application name. · [in] version: String indicating the application version. There is no constraint on format. · [in] capabilities: Array of strings with capabilities. These could be used by the client side
app to know the application registered endpoint capabilities · [in] total_capabilities: Size of capabilities array

esp_err_t wifi_prov_mgr_endpoint_create(const char *ep_name) Create an additional endpoint and allocate internal resources for it.

This API is to be called by the application if it wants to create an additional endpoint. All additional endpoints will be assigned UUIDs starting from 0xFF54 and so on in the order of execution.

protocomm handler for the created endpoint is to be registered later using wifi_prov_mgr_endpoint_register() after provisioning has started.

Note This API can only be called BEFORE provisioning is started Note Additional endpoints can be used for configuring client provided parameters other than Wi-Fi credentials,
that are necessary for the main application and hence must be set prior to starting the application Note After session establishment, the additional endpoints must be targeted first by the client side application
before sending Wi-Fi configuration, because once Wi-Fi configuration finishes the provisioning service is stopped and hence all endpoints are unregistered Return
· ESP_OK : Success · ESP_FAIL : Failure Parameters · [in] ep_name: unique name of the endpoint

esp_err_t wifi_prov_mgr_endpoint_register(const

char

*ep_name,

proto-

comm_req_handler_t handler, void *user_ctx)

Register a handler for the previously created endpoint.

This API can be called by the application to register a protocomm handler to any endpoint that was created using wifi_prov_mgr_endpoint_create().

Note This API can only be called AFTER provisioning has started Note Additional endpoints can be used for configuring client provided parameters other than Wi-Fi credentials,
that are necessary for the main application and hence must be set prior to starting the application Note After session establishment, the additional endpoints must be targeted first by the client side application
before sending Wi-Fi configuration, because once Wi-Fi configuration finishes the provisioning service is stopped and hence all endpoints are unregistered Return
· ESP_OK : Success · ESP_FAIL : Failure Parameters · [in] ep_name: Name of the endpoint · [in] handler: Endpoint handler function · [in] user_ctx: User data

void wifi_prov_mgr_endpoint_unregister(const char *ep_name) Unregister the handler for an endpoint.

This API can be called if the application wants to selectively unregister the handler of an endpoint while the provisioning is still in progress.

All the endpoint handlers are unregistered automatically when the provisioning stops.

Parameters · [in] ep_name: Name of the endpoint

esp_err_t wifi_prov_mgr_event_handler(void *ctx, system_event_t *event) Event handler for provisioning manager.

This is called from the main event handler and controls the provisioning managerns internal state machine depending on incoming Wi-Fi events

Espressif Systems

982

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Note : This function is DEPRECATED, because events are now handled internally using the event loop library, esp_event. Calling this will do nothing and simply return ESP_OK.
Return · ESP_OK : Event handled successfully
Parameters · [in] ctx: Event context data · [in] event: Event info
esp_err_t wifi_prov_mgr_get_wifi_state(wifi_prov_sta_state_t *state) Get state of Wi-Fi Station during provisioning.
Return · ESP_OK : Successfully retrieved Wi-Fi state · ESP_FAIL : Provisioning app not running
Parameters · [out] state: Pointer to wifi_prov_sta_state_t variable to be filled
esp_err_t wifi_prov_mgr_get_wifi_disconnect_reason(wifi_prov_sta_fail_reason_t *reason)
Get reason code in case of Wi-Fi station disconnection during provisioning.
Return · ESP_OK : Successfully retrieved Wi-Fi disconnect reason · ESP_FAIL : Provisioning app not running
Parameters · [out] reason: Pointer to wifi_prov_sta_fail_reason_t variable to be filled
esp_err_t wifi_prov_mgr_configure_sta(wifi_config_t *wifi_cfg) Runs Wi-Fi as Station with the supplied configuration.
Configures the Wi-Fi station mode to connect to the AP with SSID and password specified in config structure and sets Wi-Fi to run as station.
This is automatically called by provisioning service upon receiving new credentials.
If credentials are to be supplied to the manager via a different mode other than through protocomm, then this API needs to be called.
Event WIFI_PROV_CRED_RECV is emitted after credentials have been applied and Wi-Fi station started
Return · ESP_OK : Wi-Fi configured and started successfully · ESP_FAIL : Failed to set configuration
Parameters · [in] wifi_cfg: Pointer to Wi-Fi configuration structure
esp_err_t wifi_prov_mgr_reset_provisioning(void) Reset Wi-Fi provisioning config.
Calling this API will restore WiFi stack persistent settings to default values.
Return · ESP_OK : Reset provisioning config successfully · ESP_FAIL : Failed to reset provisioning config
esp_err_t wifi_prov_mgr_reset_sm_state_on_failure(void) Reset internal state machine and clear provisioned credentials.
This API can be used to restart provisioning in case invalid credentials are entered.
Return · ESP_OK : Reset provisioning state machine successfully · ESP_FAIL : Failed to reset provisioning state machine · ESP_ERR_INVALID_STATE : Manager not initialized

Espressif Systems

983

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Structures struct wifi_prov_event_handler_t
Event handler that is used by the manager while provisioning service is active.
Public Members
wifi_prov_cb_func_t event_cb Callback function to be executed on provisioning events
void *user_data User context data to pass as parameter to callback function
struct wifi_prov_scheme Structure for specifying the provisioning scheme to be followed by the manager. Note Ready to use schemes are available: · wifi_prov_scheme_ble : for provisioning over BLE transport + GATT server · wifi_prov_scheme_softap : for provisioning over SoftAP transport + HTTP server · wifi_prov_scheme_console : for provisioning over Serial UART transport + Console (for debugging)
Public Members
esp_err_t (*prov_start)(protocomm_t *pc, void *config) Function which is to be called by the manager when it is to start the provisioning service associated with a protocomm instance and a scheme specific configuration
esp_err_t (*prov_stop)(protocomm_t *pc) Function which is to be called by the manager to stop the provisioning service previously associated with a protocomm instance
void *(*new_config)(void) Function which is to be called by the manager to generate a new configuration for the provisioning service, that is to be passed to prov_start()
void (*delete_config)(void *config) Function which is to be called by the manager to delete a configuration generated using new_config()
esp_err_t (*set_config_service)(void *config, const char *service_name, const char *service_key)
Function which is to be called by the manager to set the service name and key values in the configuration structure esp_err_t (*set_config_endpoint)(void *config, const char *endpoint_name, uint16_t uuid) Function which is to be called by the manager to set a protocomm endpoint with an identifying name and UUID in the configuration structure wifi_mode_t wifi_mode Sets mode of operation of Wi-Fi during provisioning This is set to :
· WIFI_MODE_APSTA for SoftAP transport · WIFI_MODE_STA for BLE transport struct wifi_prov_mgr_config_t Structure for specifying the manager configuration.
Public Members
wifi_prov_scheme_t scheme Provisioning scheme to use. Following schemes are already available: · wifi_prov_scheme_ble : for provisioning over BLE transport + GATT server

Espressif Systems

984

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· wifi_prov_scheme_softap : for provisioning over SoftAP transport + HTTP server + mDNS (optional)
· wifi_prov_scheme_console : for provisioning over Serial UART transport + Console (for debugging)
wifi_prov_event_handler_t scheme_event_handler Event handler required by the scheme for incorporating scheme specific behavior while provisioning manager is running. Various options may be provided by the scheme for setting this field. Use WIFI_PROV_EVENT_HANDLER_NONE when not used. When using scheme wifi_prov_scheme_ble, the following options are available:
· WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BTDM · WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BLE · WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BT
wifi_prov_event_handler_t app_event_handler Event handler that can be set for the purpose of incorporating application specific behavior. Use WIFI_PROV_EVENT_HANDLER_NONE when not used.
Macros WIFI_PROV_EVENT_HANDLER_NONE
Event handler can be set to none if not used.
Type Definitions typedef void (*wifi_prov_cb_func_t)(void *user_data, wifi_prov_cb_event_t event, void
*event_data) typedef struct wifi_prov_scheme wifi_prov_scheme_t
Structure for specifying the provisioning scheme to be followed by the manager.
Note Ready to use schemes are available: · wifi_prov_scheme_ble : for provisioning over BLE transport + GATT server · wifi_prov_scheme_softap : for provisioning over SoftAP transport + HTTP server · wifi_prov_scheme_console : for provisioning over Serial UART transport + Console (for debugging)
typedef enum wifi_prov_security wifi_prov_security_t Security modes supported by the Provisioning Manager.
These are same as the security modes provided by protocomm
Enumerations enum wifi_prov_cb_event_t
Events generated by manager.
These events are generated in order of declaration and, for the stretch of time between initialization and deinitialization of the manager, each event is signaled only once
Values:
WIFI_PROV_INIT Emitted when the manager is initialized
WIFI_PROV_START Indicates that provisioning has started
WIFI_PROV_CRED_RECV Emitted when Wi-Fi AP credentials are received via protocomm endpoint wifi_config. The event data in this case is a pointer to the corresponding wifi_sta_config_t structure
WIFI_PROV_CRED_FAIL Emitted when device fails to connect to the AP of which the credentials were received earlier on event WIFI_PROV_CRED_RECV. The event data in this case is a pointer to the disconnection reason code with type wifi_prov_sta_fail_reason_t

Espressif Systems

985

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

WIFI_PROV_CRED_SUCCESS Emitted when device successfully connects to the AP of which the credentials were received earlier on event WIFI_PROV_CRED_RECV
WIFI_PROV_END Signals that provisioning service has stopped
WIFI_PROV_DEINIT Signals that manager has been de-initialized
enum wifi_prov_security Security modes supported by the Provisioning Manager.
These are same as the security modes provided by protocomm
Values:
WIFI_PROV_SECURITY_0 = 0 No security (plain-text communication)
WIFI_PROV_SECURITY_1 This secure communication mode consists of X25519 key exchange
· proof of possession (pop) based authentication · AES-CTR encryption

Header File · components/wifi_provisioning/include/wifi_provisioning/scheme_ble.h

Functions void wifi_prov_scheme_ble_event_cb_free_btdm(void *user_data, wifi_prov_cb_event_t
event, void *event_data) void wifi_prov_scheme_ble_event_cb_free_ble(void *user_data, wifi_prov_cb_event_t event,
void *event_data)
void wifi_prov_scheme_ble_event_cb_free_bt(void *user_data, wifi_prov_cb_event_t event, void *event_data)
esp_err_t wifi_prov_scheme_ble_set_service_uuid(uint8_t *uuid128) Set the 128 bit GATT service UUID used for provisioning.

This API is used to override the default 128 bit provisioning service UUID, which is 0000ffff-0000-10008000-00805f9b34fb.

This must be called before starting provisioning, i.e.

before making a call to

wifi_prov_mgr_start_provisioning(), otherwise the default UUID will be used.

Note The data being pointed to by the argument must be valid atleast till provisioning is started. Upon start, the manager will store an internal copy of this UUID, and this data can be freed or invalidated afterwords.
Return · ESP_OK : Success · ESP_ERR_INVALID_ARG : Null argument
Parameters · [in] uuid128: A custom 128 bit UUID

esp_err_t wifi_prov_scheme_ble_set_mfg_data(uint8_t *mfg_data, ssize_t mfg_data_len) Set manufacturer specific data in scan response.

This must be called before starting provisioning, i.e. wifi_prov_mgr_start_provisioning().

before making a call to

Note It is important to understand that length of custom manufacturer data should be within limits. The manufacturer data goes into scan response along with BLE device name. By default, BLE device name length is of 11 Bytes, however it can vary as per application use case. So, one has to honour the scan

Espressif Systems

986

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
response data size limits i.e. (mfg_data_len + 2) < 31 - (device_name_length + 2 ). If the mfg_data length exceeds this limit, the length will be truncated. Return
· ESP_OK : Success · ESP_ERR_INVALID_ARG : Null argument Parameters · [in] mfg_data: Custom manufacturer data · [in] mfg_data_len: Manufacturer data length
Macros WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BTDM WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BLE WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BT
Header File · components/wifi_provisioning/include/wifi_provisioning/scheme_softap.h
Functions void wifi_prov_scheme_softap_set_httpd_handle(void *handle)
Provide HTTPD Server handle externally. Useful in cases wherein applications need the webserver for some different operations, and do not want the wifi provisioning component to start/stop a new instance. Note This API should be called before wifi_prov_mgr_start_provisioning() Parameters
· [in] handle: Handle to HTTPD server instance
Header File · components/wifi_provisioning/include/wifi_provisioning/scheme_console.h
Header File · components/wifi_provisioning/include/wifi_provisioning/wifi_config.h
Functions esp_err_t wifi_prov_config_data_handler(uint32_t session_id, const uint8_t *inbuf, ssize_t
inlen, uint8_t **outbuf, ssize_t *outlen, void *priv_data) Handler for receiving and responding to requests from master. This is to be registered as the wifi_config endpoint handler (protocomm protocomm_req_handler_t) using protocomm_add_endpoint()
Structures struct wifi_prov_sta_conn_info_t
WiFi STA connected status information.
Public Members
char ip_addr[IP4ADDR_STRLEN_MAX] IP Address received by station

Espressif Systems

987

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

char bssid[6] BSSID of the AP to which connection was estalished
char ssid[33] SSID of the to which connection was estalished
uint8_t channel Channel of the AP
uint8_t auth_mode Authorization mode of the AP
struct wifi_prov_config_get_data_t WiFi status data to be sent in response to get_status request from master.

Public Members
wifi_prov_sta_state_t wifi_state WiFi state of the station
wifi_prov_sta_fail_reason_t fail_reason Reason for disconnection (valid only when wifi_state is WIFI_STATION_DISCONNECTED)
wifi_prov_sta_conn_info_t conn_info Connection information (valid only when wifi_state is WIFI_STATION_CONNECTED)
struct wifi_prov_config_set_data_t WiFi config data received by slave during set_config request from master.

Public Members
char ssid[33] SSID of the AP to which the slave is to be connected
char password[64] Password of the AP
char bssid[6] BSSID of the AP
uint8_t channel Channel of the AP
struct wifi_prov_config_handlers Internal handlers for receiving and responding to protocomm requests from master.
This is to be passed as priv_data for protocomm request handler (refer to wifi_prov_config_data_handler()) when calling protocomm_add_endpoint().

Public Members

esp_err_t (*get_status_handler)(wifi_prov_config_get_data_t *resp_data, wifi_prov_ctx_t **ctx)
Handler function called when connection status of the slave (in WiFi station mode) is requested

esp_err_t (*set_config_handler)(const

wifi_prov_config_set_data_t

*req_data,

wifi_prov_ctx_t **ctx)

Handler function called when WiFi connection configuration (eg. AP SSID, password, etc.) of the slave

(in WiFi station mode) is to be set to user provided values

esp_err_t (*apply_config_handler)(wifi_prov_ctx_t **ctx) Handler function for applying the configuration that was set in set_config_handler. After applying the station may get connected to the AP or may fail to connect. The slave must be ready to convey the updated connection status information when get_status_handler is invoked again by the master.

Espressif Systems

988

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
wifi_prov_ctx_t *ctx Context pointer to be passed to above handler functions upon invocation
Type Definitions typedef struct wifi_prov_ctx wifi_prov_ctx_t
Type of context data passed to each get/set/apply handler function set in wifi_prov_config_handlers structure. This is passed as an opaque pointer, thereby allowing it be defined later in application code as per requirements. typedef struct wifi_prov_config_handlers wifi_prov_config_handlers_t Internal handlers for receiving and responding to protocomm requests from master. This is to be passed as priv_data for protocomm request handler (refer to wifi_prov_config_data_handler()) when calling protocomm_add_endpoint().
Enumerations enum wifi_prov_sta_state_t
WiFi STA status for conveying back to the provisioning master. Values: WIFI_PROV_STA_CONNECTING WIFI_PROV_STA_CONNECTED WIFI_PROV_STA_DISCONNECTED enum wifi_prov_sta_fail_reason_t WiFi STA connection fail reason. Values: WIFI_PROV_STA_AUTH_ERROR WIFI_PROV_STA_AP_NOT_FOUND Code examples for above API are provided in the provisioning directory of ESP-IDF examples. Code example for above API is provided in wifi/smart_config Code example for above API is provided in wifi/wifi_easy_connect/dpp-enrollee
2.6 Storage API
2.6.1 FAT Filesystem Support
ESP-IDF uses the FatFs library to work with FAT filesystems. FatFs resides in the fatfs component. Although the library can be used directly, many of its features can be accessed via VFS, using the C standard library and POSIX API functions. Additionally, FatFs has been modified to support the runtime pluggable disk I/O layer. This allows mapping of FatFs drives to physical disks at runtime.
Using FatFs with VFS
The header file fatfs/vfs/esp_vfs_fat.h defines the functions for connecting FatFs and VFS. The function esp_vfs_fat_register() allocates a FATFS structure and registers a given path prefix in VFS. Subsequent operations on files starting with this prefix are forwarded to FatFs APIs. The function esp_vfs_fat_unregister_path() deletes the registration with VFS, and frees the FATFS structure.

Espressif Systems

989

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Most applications use the following workflow when working with esp_vfs_fat_ functions:
1. Call esp_vfs_fat_register() to specify: · Path prefix where to mount the filesystem (e.g. "/sdcard", "/spiflash") · FatFs drive number · A variable which will receive the pointer to the FATFS structure
2. Call ff_diskio_register() to register the disk I/O driver for the drive number used in Step 1. 3. Call the FatFs function f_mount, and optionally f_fdisk, f_mkfs, to mount the filesystem using the
same drive number which was passed to esp_vfs_fat_register(). For more information, see FatFs documentation. 4. Call the C standard library and POSIX API functions to perform such actions on files as open, read, write, erase, copy, etc. Use paths starting with the path prefix passed to esp_vfs_register() (for example, "/sdcard/hello.txt"). The filesystem uses 8.3 filenames format (SFN) by default. If you need to use long filenames (LFN), enable the CONFIG_FATFS_LONG_FILENAMES option. More details on the FatFs filenames are available here. 5. Optionally, by enabling the option CONFIG_FATFS_USE_FASTSEEK, use the POSIX lseek function to perform it faster, the fast seek will not work for files in write mode, so to take advantage of fast seek, you should open (or close and then reopen) the file in read-only mode. 6. Optionally, call the FatFs library functions directly. In this case, use paths without a VFS prefix (for example, "/hello.txt"). 7. Close all open files. 8. Call the FatFs function f_mount for the same drive number, with NULL FATFS* argument, to unmount the filesystem. 9. Call the FatFs function ff_diskio_register() with NULL ff_diskio_impl_t* argument and the same drive number to unregister the disk I/O driver. 10. Call esp_vfs_fat_unregister_path() with the path where the file system is mounted to remove FatFs from VFS, and free the FATFS structure allocated in Step 1.
The convenience functions esp_vfs_fat_sdmmc_mount, esp_vfs_fat_sdspi_mount and esp_vfs_fat_sdcard_unmount wrap the steps described above and also handle SD card initialization. These two functions are described in the next section.
esp_err_t esp_vfs_fat_register(const char *base_path, const char *fat_drive, size_t max_files, FATFS **out_fs)
Register FATFS with VFS component.
This function registers given FAT drive in VFS, at the specified base path. If only one drive is used, fat_drive argument can be an empty string. Refer to FATFS library documentation on how to specify FAT drive. This function also allocates FATFS structure which should be used for f_mount call.
Note This function doesnnt mount the drive into FATFS, it just connects POSIX and C standard library IO function with FATFS. You need to mount desired drive into FATFS separately.
Return · ESP_OK on success · ESP_ERR_INVALID_STATE if esp_vfs_fat_register was already called · ESP_ERR_NO_MEM if not enough memory or too many VFSes already registered
Parameters · base_path: path prefix where FATFS should be registered · fat_drive: FATFS drive specification; if only one drive is used, can be an empty string · max_files: maximum number of files which can be open at the same time · [out] out_fs: pointer to FATFS structure which can be used for FATFS f_mount call is returned via this argument.
esp_err_t esp_vfs_fat_unregister_path(const char *base_path) Un-register FATFS from VFS.
Note FATFS structure returned by esp_vfs_fat_register is destroyed after this call. Make sure to call f_mount function to unmount it before calling esp_vfs_fat_unregister_ctx. Difference between this function and the one above is that this one will release the correct drive, while the one above will release the last registered one
Return · ESP_OK on success

Espressif Systems

990

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_ERR_INVALID_STATE if FATFS is not registered in VFS Parameters
· base_path: path prefix where FATFS is registered. This is the same used when esp_vfs_fat_register was called

Using FatFs with VFS and SD cards

The header file fatfs/vfs/esp_vfs_fat.h defines convenience functions esp_vfs_fat_sdmmc_mount(), esp_vfs_fat_sdspi_mount() and esp_vfs_fat_sdcard_unmount(). These function perform Steps 13 and 79 respectively and handle SD card initialization, but provide only limited error handling. Developers are encouraged to check its source code and incorporate more advanced features into production applications.

The convenience function esp_vfs_fat_sdmmc_unmount() unmounts the filesystem and releases the resources acquired by esp_vfs_fat_sdmmc_mount().

esp_err_t esp_vfs_fat_sdmmc_mount(const char *base_path, const sdmmc_host_t *host_config, const void *slot_config, const esp_vfs_fat_mount_config_t *mount_config, sdmmc_card_t **out_card)
Convenience function to get FAT filesystem on SD card registered in VFS.

This is an all-in-one function which does the following:

· initializes SDMMC driver or SPI driver with configuration in host_config · initializes SD card with configuration in slot_config · mounts FAT partition on SD card using FATFS library, with configuration in mount_config · registers FATFS library with VFS, with prefix given by base_prefix variable

This function is intended to make example code more compact. For real world applications, developers should implement the logic of probing SD card, locating and mounting partition, and registering FATFS in VFS, with proper error checking and handling of exceptional conditions.

Note Use this API to mount a card through SDSPI is deprecated.

Please call

esp_vfs_fat_sdspi_mount() instead for that case.

Return

· ESP_OK on success

· ESP_ERR_INVALID_STATE if esp_vfs_fat_sdmmc_mount was already called

· ESP_ERR_NO_MEM if memory can not be allocated

· ESP_FAIL if partition can not be mounted

· other error codes from SDMMC or SPI drivers, SDMMC protocol, or FATFS drivers

Parameters

· base_path: path where partition should be registered (e.g. o/sdcardp)

· host_config: Pointer to structure describing SDMMC host. When using SDMMC peripheral,

this structure can be initialized using SDMMC_HOST_DEFAULT() macro. When using SPI pe-

ripheral, this structure can be initialized using SDSPI_HOST_DEFAULT() macro.

· slot_config: Pointer to structure with slot configuration. For SDMMC peripheral, pass a

pointer to sdmmc_slot_config_t structure initialized using SDMMC_SLOT_CONFIG_DEFAULT.

(Deprecated) For SPI peripheral, pass a pointer to sdspi_slot_config_t structure initialized using SD-

SPI_SLOT_CONFIG_DEFAULT().

· mount_config: pointer to structure with extra parameters for mounting FATFS

· [out] out_card: if not NULL, pointer to the card information structure will be returned via

this argument

esp_err_t esp_vfs_fat_sdspi_mount(const char *base_path, const sdmmc_host_t *host_config_input, const sdspi_device_config_t *slot_config, const esp_vfs_fat_mount_config_t *mount_config, sdmmc_card_t **out_card)
Convenience function to get FAT filesystem on SD card registered in VFS.

This is an all-in-one function which does the following:

· initializes an SPI Master device based on the SPI Master driver with configuration in slot_config, and attach it to an initialized SPI bus.

Espressif Systems

991

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· initializes SD card with configuration in host_config_input · mounts FAT partition on SD card using FATFS library, with configuration in mount_config · registers FATFS library with VFS, with prefix given by base_prefix variable
This function is intended to make example code more compact. For real world applications, developers should implement the logic of probing SD card, locating and mounting partition, and registering FATFS in VFS, with proper error checking and handling of exceptional conditions.
Note This function try to attach the new SD SPI device to the bus specified in host_config. Make sure the SPI bus specified in host_config->slot have been initialized by spi_bus_initialize() before.
Return · ESP_OK on success · ESP_ERR_INVALID_STATE if esp_vfs_fat_sdmmc_mount was already called · ESP_ERR_NO_MEM if memory can not be allocated · ESP_FAIL if partition can not be mounted · other error codes from SDMMC or SPI drivers, SDMMC protocol, or FATFS drivers
Parameters · base_path: path where partition should be registered (e.g. o/sdcardp) · host_config_input: Pointer to structure describing SDMMC host. This structure can be initialized using SDSPI_HOST_DEFAULT() macro. · slot_config: Pointer to structure with slot configuration. For SPI peripheral, pass a pointer to sdspi_device_config_t structure initialized using SDSPI_DEVICE_CONFIG_DEFAULT(). · mount_config: pointer to structure with extra parameters for mounting FATFS · [out] out_card: If not NULL, pointer to the card information structure will be returned via this argument. It is suggested to hold this handle and use it to unmount the card later if needed. Otherwise itns not suggested to use more than one card at the same time and unmount one of them in your application.
struct esp_vfs_fat_mount_config_t Configuration arguments for esp_vfs_fat_sdmmc_mount and esp_vfs_fat_spiflash_mount functions.
Public Members
bool format_if_mount_failed If FAT partition can not be mounted, and this parameter is true, create partition table and format the filesystem.
int max_files Max number of open files.
size_t allocation_unit_size If format_if_mount_failed is set, and mount fails, format the card with given allocation unit size. Must be a power of 2, between sector size and 128 * sector size. For SD cards, sector size is always 512 bytes. For wear_levelling, sector size is determined by CONFIG_WL_SECTOR_SIZE option.
Using larger allocation unit size will result in higher read/write performance and higher overhead when storing small files.
Setting this field to 0 will result in allocation unit set to the sector size.
esp_err_t esp_vfs_fat_sdcard_unmount(const char *base_path, sdmmc_card_t *card) Unmount an SD card from the FAT filesystem and release resources acquired using esp_vfs_fat_sdmmc_mount() or esp_vfs_fat_sdspi_mount()
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if the card argument is unregistered · ESP_ERR_INVALID_STATE if esp_vfs_fat_sdmmc_mount hasnnt been called

Espressif Systems

992

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Using FatFs with VFS in read-only mode
The header file fatfs/vfs/esp_vfs_fat.h also defines the convenience functions esp_vfs_fat_rawflash_mount() and esp_vfs_fat_rawflash_unmount(). These functions perform Steps 1-3 and 7-9 respectively for read-only FAT partitions. These are particularly helpful for data partitions written only once during factory provisioning which will not be changed by production application throughout the lifetime of the hardware.
esp_err_t esp_vfs_fat_rawflash_mount(const char *base_path, const char *partition_label, const esp_vfs_fat_mount_config_t *mount_config)
Convenience function to initialize read-only FAT filesystem and register it in VFS.
This is an all-in-one function which does the following:
· finds the partition with defined partition_label. Partition label should be configured in the partition table. · mounts FAT partition using FATFS library · registers FATFS library with VFS, with prefix given by base_prefix variable
Note Wear levelling is not used when FAT is mounted in read-only mode using this function. Return
· ESP_OK on success · ESP_ERR_NOT_FOUND if the partition table does not contain FATFS partition with given label · ESP_ERR_INVALID_STATE if esp_vfs_fat_rawflash_mount was already called for the same par-
tition · ESP_ERR_NO_MEM if memory can not be allocated · ESP_FAIL if partition can not be mounted · other error codes from SPI flash driver, or FATFS drivers Parameters · base_path: path where FATFS partition should be mounted (e.g. o/spiflashp) · partition_label: label of the partition which should be used · mount_config: pointer to structure with extra parameters for mounting FATFS
esp_err_t esp_vfs_fat_rawflash_unmount(const char *base_path, const char *partition_label)
Unmount FAT filesystem and release resources acquired using esp_vfs_fat_rawflash_mount.
Return · ESP_OK on success · ESP_ERR_INVALID_STATE if esp_vfs_fat_spiflash_mount hasnnt been called
Parameters · base_path: path where partition should be registered (e.g. o/spiflashp) · partition_label: label of partition to be unmounted
FatFS disk IO layer
FatFs has been extended with API functions that register the disk I/O driver at runtime.
They provide implementation of disk I/O functions for SD/MMC cards and can be registered for the given FatFs drive number using the function ff_diskio_register_sdmmc().
void ff_diskio_register(BYTE pdrv, const ff_diskio_impl_t *discio_impl) Register or unregister diskio driver for given drive number.
When FATFS library calls one of disk_xxx functions for driver number pdrv, corresponding function in discio_impl for given pdrv will be called.
Parameters · pdrv: drive number · discio_impl: pointer to ff_diskio_impl_t structure with diskio functions or NULL to unregister and free previously registered drive
struct ff_diskio_impl_t Structure of pointers to disk IO driver functions.

Espressif Systems

993

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

See FatFs documentation for details about these functions

Public Members

DSTATUS (*init)(unsigned char pdrv) disk initialization function

DSTATUS (*status)(unsigned char pdrv) disk status check function

DRESULT (*read)(unsigned char pdrv, unsigned char *buff, uint32_t sector, unsigned count) sector read function

DRESULT (*write)(unsigned char pdrv, const unsigned char *buff, uint32_t sector, unsigned count)
sector write function

DRESULT (*ioctl)(unsigned char pdrv, unsigned char cmd, void *buff) function to get info about disk and do some misc operations

void ff_diskio_register_sdmmc(unsigned char pdrv, sdmmc_card_t *card) Register SD/MMC diskio driver

Parameters · pdrv: drive number · card: pointer to sdmmc_card_t structure describing a card; card should be initialized before calling f_mount.

esp_err_t ff_diskio_register_wl_partition(unsigned char pdrv, wl_handle_t flash_handle) Register spi flash partition

Parameters · pdrv: drive number · flash_handle: handle of the wear levelling partition.

esp_err_t ff_diskio_register_raw_partition(unsigned char pdrv, const esp_partition_t

Register spi flash partition

*part_handle)

Parameters · pdrv: drive number · part_handle: pointer to raw flash partition.

FATFS partition generator
We provide a partition generator for FATFS (wl_fatfsgen.py) which is integrated into the build system and could be easily used in the user project.
The tool is used to create filesystem images on a host and populate it with content of the specified host folder.
The script is based on the partition generator (fatfsgen.py) and except for generating partition also initializes wear levelling.
Current implementation supports short file names and FAT12. Long file names, and FAT16 are subjects of the future work.

Build system integration with FATFS partition generator It is possible to invoke FATFS generator directly from the CMake build system by calling fatfs_create_spiflash_image:
fatfs_create_spiflash_image(<partition> <base_dir> [FLASH_IN_PROJECT])
If you prefer generating partition without wear levelling support you can use fatfs_create_rawflash_image:

Espressif Systems

994

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

fatfs_create_rawflash_image(<partition> <base_dir> [FLASH_IN_PROJECT])

fatfs_create_spiflash_image respectively fatfs_create_rawflash_image must be called from projectns CMakeLists.txt.

If you decided because of any reason to use fatfs_create_rawflash_image (without wear levelling support) beware that it supports mounting only in read-only mode in the device.

The arguments of the function are as follows:

1. partition - the name of the partition as defined in the partition table (e.g.

stor-

age/fatfsgen/partitions_example.csv).

2. base_dir - the directory that will be encoded to FATFS partition and optionally flashed into the device. Beware

that you have to specified suitable size of the partition in the partition table.

3. flag FLASH_IN_PROJECT - optionally, user can opt to have the image automatically flashed together with the

app binaries, partition tables, etc. on idf.py flash -p <PORT> by specifying FLASH_IN_PROJECT.

For example:

fatfs_create_spiflash_image(my_fatfs_partition my_folder FLASH_IN_PROJECT)

If FLASH_IN_PROJECT is not specified, the image will still be generated, but you will have to flash it manually using esptool.py or a custom build system target.
For an example, see storage/fatfsgen.

2.6.2 Manufacturing Utility
Introduction
This utility is designed to create instances of factory NVS partition images on a per-device basis for mass manufacturing purposes. The NVS partition images are created from CSV files containing user-provided configurations and values.
Please note that this utility only creates manufacturing binary images which then need to be flashed onto your devices using:
· esptool.py · Flash Download tool (available on Windows only).Just download it, unzip, and follow the instructions inside
the doc folder. · Direct flash programming using custom production tools.

Prerequisites
This utility is dependent on esp-idfns NVS partition utility. · Operating System requirements: ­ Linux / MacOS / Windows (standard distributions) · The following packages are needed to use this utility: ­ Python
Note: Before using this utility, please make sure that:
· The path to Python is added to the PATH environment variable. · You have installed the packages from requirement.txt, the file in the root of the esp-idf directory.

Espressif Systems

995

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference Workflow

CSV Configuration File
This file contains the configuration of the device to be flashed. The data in the configuration file has the following format (the REPEAT tag is optional):
name1,namespace, <-- First entry should be of type "namespace" key1,type1,encoding1 key2,type2,encoding2,REPEAT name2,namespace, key3,type3,encoding3 key4,type4,encoding4
Note: The first line in this file should always be the namespace entry.
Each line should have three parameters: key,type,encoding, separated by a comma. If the REPEAT tag is present, the value corresponding to this key in the master value CSV file will be the same for all devices. Please refer to README of the NVS Partition Generator utility for detailed description of each parameter. Below is a sample example of such a configuration file:
app,namespace, firmware_key,data,hex2bin serial_no,data,string,REPEAT device_no,data,i32
Note: Make sure there are no spaces:
· before and after m,n · at the end of each line in a CSV file

Master Value CSV File
This file contains details of the devices to be flashed. Each line in this file corresponds to a device instance. The data in the master value CSV file has the following format: key1,key2,key3,..... value1,value2,value3,....
Note: The first line in the file should always contain the key names. All the keys from the configuration file should be present here in the same order. This file can have additional columns (keys). The additional keys will be treated as metadata and would not be part of the final binary files.

Espressif Systems

996

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Each line should contain the value of the corresponding keys, separated by a comma. If the key has the REPEAT tag, its corresponding value must be entered in the second line only. Keep the entry empty for this value in the following lines.
The description of this parameter is as follows:
value Data value
Data value is the value of data corresponding to the key.
Below is a sample example of a master value CSV file:
id,firmware_key,serial_no,device_no 1,1a2b3c4d5e6faabb,A1,101 2,1a2b3c4d5e6fccdd,,102 3,1a2b3c4d5e6feeff,,103

Note: If the mREPEATntag is present, a new master value CSV file will be created in the same folder as the input Master CSV File with the values inserted at each line for the key with the mREPEATntag.
This utility creates intermediate CSV files which are used as input for the NVS partition utility to generate the binary files. The format of this intermediate CSV file is as follows:
key,type,encoding,value key,namespace, , key1,type1,encoding1,value1 key2,type2,encoding2,value2
An instance of an intermediate CSV file will be created for each device on an individual basis.

Running the utility Usage: python mfg_gen.py [-h] {generate,generate-key} ... Optional Arguments:

No. Parameter Description 1 -h, help show this help message and exit

Commands: Run mfg_gen.py {command} -h for additional help

No. Parameter Description

1 generate

Generate NVS partition

2 generate-key Generate keys for encryption

To generate factory images for each device (Default):
Usage:
python mfg_gen.py generate [-h] [--fileid FILEID] [--version {1,2}] [--keygen] [--keyfile KEYFILE] [--inputkey INPUTKEY] [--outdir OUTDIR] conf values prefix size

Espressif Systems

997

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Positional Arguments:

Parameter

Description

conf

Path to configuration csv file to parse

values

Path to values csv file to parse

prefix | Unique name for each output filename prefix

size | Size of NVS partition in bytes

(must be multiple of 4096)

Optional Arguments:

Parameter -h, help fileid FILEID version {1,2} keygen inputkey INPUTKEY outdir OUTDIR

Description show this help message and exit Unique file identifier(any key in values file) for each filename suffix (Default: numeric value(1,2,3l) Set multipage blob version. Version 1 - Multipage blob support disabled. Version 2 - Multipage blob support enabled. Default: Version 2 Generates key for encrypting NVS partition File having key for encrypting NVS partition
Output directory to store files created (Default: current directory)

You can run the utility to generate factory images for each device using the command below. A sample CSV file is provided with the utility:
python mfg_gen.py generate samples/sample_config.csv samples/sample_values_ singlepage_blob.csv Sample 0x3000
The master value CSV file should have the path in the file type relative to the directory from which you are running the utility. To generate encrypted factory images for each device: You can run the utility to encrypt factory images for each device using the command below. A sample CSV file is provided with the utility:
· Encrypt by allowing the utility to generate encryption keys:
python mfg_gen.py generate samples/sample_config.csv samples/sample_values_ singlepage_blob.csv Sample 0x3000 --keygen

Note: Encryption key of the following format <outdir>/keys/keys-<prefix>-<fileid>.bin is created. This newly created file having encryption keys in keys/ directory is compatible with NVS key-partition structure. Refer to NVS key partition for more details.
· Encrypt by providing the encryption keys as input binary file:
python mfg_gen.py generate samples/sample_config.csv samples/sample_values_ singlepage_blob.csv Sample 0x3000 --inputkey keys/sample_keys.bin
To generate only encryption keys: Usage:: python mfg_gen.py generate-key [-h] [keyfile KEYFILE] [outdir OUTDIR] Optional Arguments:

Espressif Systems

998

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Parameter -h, help keyfile KEYFILE outdir OUTDIR

Description show this help message and exit Path to output encryption keys file Output directory to store files created. (Default: current directory)

You can run the utility to generate only encryption keys using the command below:

python mfg_gen.py generate-key

Note: Encryption key of the following format <outdir>/keys/keys-<timestamp>.bin is created. Timestamp format is: %m-%d_%H-%M. To provide custom target filename use the keyfile argument.
Generated encryption key binary file can further be used to encrypt factory images created on the per device basis. The default numeric value: 1,2,3lof the fileid argument corresponds to each line bearing device instance values in the master value CSV file. While running the manufacturing utility, the following folders will be created in the specified outdir directory:
· bin/ for storing the generated binary files · csv/ for storing the generated intermediate CSV files · keys/ for storing encryption keys (when generating encrypted factory images)
2.6.3 Non-volatile storage library
Introduction
Non-volatile storage (NVS) library is designed to store key-value pairs in flash. This section introduces some concepts used by NVS.
Underlying storage Currently, NVS uses a portion of main flash memory through the esp_partition API. The library uses all the partitions with data type and nvs subtype. The application can choose to use the partition with the label nvs through the nvs_open() API function or any other partition by specifying its name using the nvs_open_from_partition() API function. Future versions of this library may have other storage backends to keep data in another flash chip (SPI or I2C), RTC, FRAM, etc.
Note: if an NVS partition is truncated (for example, when the partition table layout is changed), its contents should be erased. ESP-IDF build system provides a idf.py erase-flash target to erase all contents of the flash chip.

Note: NVS works best for storing many small values, rather than a few large values of the typemstringnandmblobn . If you need to store large blobs or strings, consider using the facilities provided by the FAT filesystem on top of the wear levelling library.

Keys and values NVS operates on key-value pairs. Keys are ASCII strings; the maximum key length is currently 15 characters. Values can have one of the following types:
· integer types: uint8_t, int8_t, uint16_t, int16_t, uint32_t, int32_t, uint64_t, int64_t
· zero-terminated string · variable length binary data (blob)

Espressif Systems

999

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Note: String values are currently limited to 4000 bytes. This includes the null terminator. Blob values are limited to 508,000 bytes or 97.6% of the partition size - 4000 bytes, whichever is lower.
Additional types, such as float and double might be added later.
Keys are required to be unique. Assigning a new value to an existing key works as follows:
· If the new value is of the same type as the old one, value is updated. · If the new value has a different data type, an error is returned.
Data type check is also performed when reading a value. An error is returned if the data type of the read operation does not match the data type of the value.
Namespaces To mitigate potential conflicts in key names between different components, NVS assigns each keyvalue pair to one of namespaces. Namespace names follow the same rules as key names, i.e., the maximum length is 15 characters. Namespace name is specified in the nvs_open() or nvs_open_from_partition call. This call returns an opaque handle, which is used in subsequent calls to the nvs_get_*, nvs_set_*, and nvs_commit() functions. This way, a handle is associated with a namespace, and key names will not collide with same names in other namespaces. Please note that the namespaces with the same name in different NVS partitions are considered as separate namespaces.
NVS iterators Iterators allow to list key-value pairs stored in NVS, based on specified partition name, namespace, and data type.
There are the following functions available:
· nvs_entry_find() returns an opaque handle, which is used in subsequent calls to the nvs_entry_next() and nvs_entry_info() functions.
· nvs_entry_next() returns iterator to the next key-value pair. · nvs_entry_info() returns information about each key-value pair
If none or no other key-value pair was found for given criteria, nvs_entry_find() and nvs_entry_next() return NULL. In that case, the iterator does not have to be released. If the iterator is no longer needed, you can release it by using the function nvs_release_iterator().
Security, tampering, and robustness NVS is not directly compatible with the ESP32-S3 flash encryption system. However, data can still be stored in encrypted form if NVS encryption is used together with ESP32-S3 flash encryption. Please refer to NVS Encryption for more details.
If NVS encryption is not used, it is possible for anyone with physical access to the flash chip to alter, erase, or add key-value pairs. With NVS encryption enabled, it is not possible to alter or add a key-value pair and get recognized as a valid pair without knowing corresponding NVS encryption keys. However, there is no tamper-resistance against the erase operation.
The library does try to recover from conditions when flash memory is in an inconsistent state. In particular, one should be able to power off the device at any point and time and then power it back on. This should not result in loss of data, except for the new key-value pair if it was being written at the moment of powering off. The library should also be able to initialize properly with any random data present in flash memory.
NVS Encryption
Data stored in NVS partitions can be encrypted using AES-XTS in the manner similar to the one mentioned in disk encryption standard IEEE P1619. For the purpose of encryption, each entry is treated as one sector and relative address of the entry (w.r.t. partition-start) is fed to the encryption algorithm as sector-number. The NVS Encryption can be enabled by enabling CONFIG_NVS_ENCRYPTION. The keys required for NVS encryption are stored in yet another partition, which is protected using Flash Encryption. Therefore, enabling Flash Encryption is a prerequisite for NVS encryption.

Espressif Systems

1000

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

The NVS Encryption is enabled by default when Flash Encryption is enabled. This is done because Wi-Fi driver stores credentials (like SSID and passphrase) in the default NVS partition. It is important to encrypt them as default choice if platform level encryption is already enabled.
For using NVS encryption, the partition table must contain the NVS key partition. Two partition tables containing the NVS key partition are provided for NVS encryption under the partition table option (menuconfig->Partition Table). They can be selected with the project configuration menu (idf.py menuconfig). Please refer to the example security/flash_encryption for how to configure and use NVS encryption feature.

NVS key partition
An application requiring NVS encryption support needs to be compiled with a key-partition of the type data and subtype key. This partition should be marked as encrypted and its size should be the minimum partition size (4KB). Refer to Partition Tables for more details. Two additional partition tables which contain the NVS key partition are provided under the partition table option (menuconfig->Partition Table). They can be directly used for NVS Encryption. The structure of these partitions is depicted below.

+-----------+--------------+-------------+----+

|

XTS encryption key (32)

|

+---------------------------------------------+

|

XTS tweak key (32)

|

+---------------------------------------------+

|

CRC32 (4)

|

+---------------------------------------------+

The XTS encryption keys in the NVS key partition can be generated in one of the following two ways.
1. Generate the keys on the ESP chip: When NVS encryption is enabled the nvs_flash_init() API function can be used to initialize the encrypted default NVS partition. The API function internally generates the XTS encryption keys on the ESP chip. The API function finds the first NVS key partition. Then the API function automatically generates and stores the NVS keys in that partition by making use of the nvs_flash_generate_keys() API function provided by nvs_flash/include/nvs_flash.h. New keys are generated and stored only when the respective key partiton is empty. The same key partition can then be used to read the security configurations for initializing a custom encrypted NVS partition with help of nvs_flash_secure_init_partition(). The API functions nvs_flash_secure_init() and nvs_flash_secure_init_partition() do not generate the keys internally. When these API functions are used for initializing encrypted NVS partitions, the keys can be generated after startup using the nvs_flash_generate_keys() API function provided by nvs_flash.h. The API function will then write those keys onto the key-partition in encrypted form.
2. Use pre-generated key partition: This option will be required by the user when keys in the NVS key partition are not generated by the application. The NVS key partition containing the XTS encryption keys can be generated with the help of NVS Partition Generator Utility. Then the user can store the pre generated key partition on the flash with help of the following two commands: i) Build and flash the partition table
idf.py partition-table partition-table-flash
ii) Store the keys in the NVS key partition (on the flash) with the help of parttool.py (see Partition Tool section in partition-tables for more details)
parttool.py --port /dev/ttyUSB0 --partition-table-offset "nvs_key partition offset" write_partition --partition-name="name of nvs_key partition" --input "nvs_key partition"

Since the key partition is marked as encrypted and Flash Encryption is enabled, the bootloader will encrypt this partition using flash encryption key on the first boot.
It is possible for an application to use different keys for different NVS partitions and thereby have multiple keypartitions. However, it is a responsibility of the application to provide correct key-partition/keys for the purpose of

Espressif Systems

1001

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
encryption/decryption.
Encrypted Read/Write The same NVS API functions nvs_get_* or nvs_set_* can be used for reading of, and writing to an encrypted nvs partition as well.
Encrypt the default NVS partition: To enable encryption for the default NVS partition no additional steps are necessary. When CONFIG_NVS_ENCRYPTION is enabled, the nvs_flash_init() API function internally performs some additional steps using the first NVS key partition found to enable encryption for the default NVS partition (refer to the API documentation for more details). Alternatively, nvs_flash_secure_init() API function can also be used to enable encryption for the default NVS partition.
Encrypt a custom NVS partition: To enable encryption for a custom NVS partition, nvs_flash_secure_init_partition() API function is used instead of nvs_flash_init_partition().
When nvs_flash_secure_init() and nvs_flash_secure_init_partition() API functions are used, the applications are expected to follow the steps below in order to perform NVS read/write operations with encryption enabled.
1. Find key partition and NVS data partition using esp_partition_find* API functions. 2. Populate the nvs_sec_cfg_t struct using the nvs_flash_read_security_cfg() or
nvs_flash_generate_keys() API functions. 3. Initialise NVS flash partition using the nvs_flash_secure_init() or
nvs_flash_secure_init_partition() API functions. 4. Open a namespace using the nvs_open() or nvs_open_from_partition() API functions. 5. Perform NVS read/write operations using nvs_get_* or nvs_set_*. 6. Deinitialise an NVS partition using nvs_flash_deinit().
NVS Partition Generator Utility
This utility helps generate NVS partition binary files which can be flashed separately on a dedicated partition via a flashing utility. Key-value pairs to be flashed onto the partition can be provided via a CSV file. For more details, please refer to NVS Partition Generator Utility.
Application Example
You can find code examples in the storage directory of ESP-IDF examples:
storage/nvs_rw_value
Demonstrates how to read a single integer value from, and write it to NVS.
The value checked in this example holds the number of the ESP32-S3 module restarts. The valuens function as a counter is only possible due to its storing in NVS.
The example also shows how to check if a read / write operation was successful, or if a certain value has not been initialized in NVS. The diagnostic procedure is provided in plain text to help you track the program flow and capture any issues on the way.
storage/nvs_rw_blob
Demonstrates how to read a single integer value and a blob (binary large object), and write them to NVS to preserve this value between ESP32-S3 module restarts.
· value - tracks the number of the ESP32-S3 module soft and hard restarts. · blob - contains a table with module run times. The table is read from NVS to dynamically allocated
RAM. A new run time is added to the table on each manually triggered soft restart, and then the added run time is written to NVS. Triggering is done by pulling down GPIO0.
The example also shows how to implement the diagnostic procedure to check if the read / write operation was successful.

Espressif Systems

1002

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

storage/nvs_rw_value_cxx
This example does exactly the same as storage/nvs_rw_value, except that it uses the C++ NVS handle class.

Internals
Log of key-value pairs NVS stores key-value pairs sequentially, with new key-value pairs being added at the end. When a value of any given key has to be updated, a new key-value pair is added at the end of the log and the old key-value pair is marked as erased.

Pages and entries NVS library uses two main entities in its operation: pages and entries. Page is a logical structure which stores a portion of the overall log. Logical page corresponds to one physical sector of flash memory. Pages which are in use have a sequence number associated with them. Sequence numbers impose an ordering on pages. Higher sequence numbers correspond to pages which were created later. Each page can be in one of the following states:
Empty/uninitialized Flash storage for the page is empty (all bytes are 0xff). Page is not used to store any data at this point and does not have a sequence number.
Active Flash storage is initialized, page header has been written to flash, page has a valid sequence number. Page has some empty entries and data can be written there. No more than one page can be in this state at any given moment.
Full Flash storage is in a consistent state and is filled with key-value pairs. Writing new key-value pairs into this page is not possible. It is still possible to mark some key-value pairs as erased.
Erasing Non-erased key-value pairs are being moved into another page so that the current page can be erased. This is a transient state, i.e., page should never stay in this state at the time when any API call returns. In case of a sudden power off, the move-and-erase process will be completed upon the next power-on.
Corrupted Page header contains invalid data, and further parsing of page data was canceled. Any items previously written into this page will not be accessible. The corresponding flash sector will not be erased immediately and will be kept along with sectors in uninitialized state for later use. This may be useful for debugging.
Mapping from flash sectors to logical pages does not have any particular order. The library will inspect sequence numbers of pages found in each flash sector and organize pages in a list based on these numbers.

+--------+

+--------+

+--------+

| Page 1 |

| Page 2 |

| Page 3 |

| Full +---> | Full +---> | Active |

| #11 |

| #12 |

| #14 |

+---+----+

+----+---+

+----+---+

|

|

|

|

|

|

|

|

|

+---v------+ +-----v----+ +------v---+

| Sector 3 | | Sector 0 | | Sector 2 |

+----------+ +----------+ +----------+

+--------+

| Page 4 |

| Empty |

|

|

+---+----+

|

|

|

+------v---+

| Sector 1 |

+----------+

<- states <- sequence numbers
<- physical sectors

Structure of a page For now, we assume that flash sector size is 4096 bytes and that ESP32-S3 flash encryption hardware operates on 32-byte blocks. It is possible to introduce some settings configurable at compile-time (e.g., via menuconfig) to accommodate flash chips with different sector sizes (although it is not clear if other components in the system, e.g., SPI flash driver and SPI flash cache can support these other sizes).
Page consists of three parts: header, entry state bitmap, and entries themselves. To be compatible with ESP32-S3 flash encryption, the entry size is 32 bytes. For integer types, an entry holds one key-value pair. For strings and blobs, an entry holds part of key-value pair (more on that in the entry structure description).
The following diagram illustrates the page structure. Numbers in parentheses indicate the size of each part in bytes.

Espressif Systems

1003

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

+-----------+--------------+-------------+-------------------------+

| State (4) | Seq. no. (4) | version (1) | Unused (19) | CRC32 (4) |

+-----------+--------------+-------------+-------------------------+

|

Entry state bitmap (32)

|

+------------------------------------------------------------------+

|

Entry 0 (32)

|

+------------------------------------------------------------------+

|

Entry 1 (32)

|

+------------------------------------------------------------------+

/

/

/

/

+------------------------------------------------------------------+

|

Entry 125 (32)

|

+------------------------------------------------------------------+

Header (32)

Page header and entry state bitmap are always written to flash unencrypted. Entries are encrypted if flash encryption feature of ESP32-S3 is used.
Page state values are defined in such a way that changing state is possible by writing 0 into some of the bits. Therefore it is not necessary to erase the page to change its state unless that is a change to the erased state.
The version field in the header reflects the NVS format version used. For backward compatibility reasons, it is decremented for every version upgrade starting at 0xff (i.e., 0xff for version-1, 0xfe for version-2 and so on).
CRC32 value in the header is calculated over the part which does not include a state value (bytes 4 to 28). The unused part is currently filled with 0xff bytes.
The following sections describe the structure of entry state bitmap and entry itself.

Entry and entry state bitmap Each entry can be in one of the following three states represented with two bits in the entry state bitmap. The final four bits in the bitmap (256 - 2 * 126) are not used.
Empty (2nb11) Nothing is written into the specific entry yet. It is in an uninitialized state (all bytes are 0xff). Written (2nb10) A key-value pair (or part of key-value pair which spans multiple entries) has been written into
the entry. Erased (2nb00) A key-value pair in this entry has been discarded. Contents of this entry will not be parsed any-
more.

Structure of entry For values of primitive types (currently integers from 1 to 8 bytes long), entry holds one keyvalue pair. For string and blob types, entry holds part of the whole key-value pair. For strings, in case when a key-value pair spans multiple entries, all entries are stored in the same page. Blobs are allowed to span over multiple pages by dividing them into smaller chunks. For tracking these chunks, an additional fixed length metadata entry is stored called oblob indexp. Earlier formats of blobs are still supported (can be read and modified). However, once the blobs are modified, they are stored using the new format.

+--------+----------+----------+----------------+-----------+---------------+---------+ | NS (1) | Type (1) | Span (1) | ChunkIndex (1) | CRC32 (4) | Key (16) | Data (8) | +--------+----------+----------+----------------+-----------+---------------+---------+

--+
|
--+ +-> Fixed length -|
----------+-------+

Primitive +--------> | Types
|

+------------------------------

|

Data (8)



+------------------------------

+---------+--------------+----(continues on next page)

Espressif Systems

1004

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)

|

+--------> | Size(4) | ChunkCount(1)|

ChunkStart(1) | Rsv(2)|

Data format ---+

Blob Index +---------+--------------+-----

----------+-------+

|

|

+----------+---------+-----------+

+-> Variable length --> | Size (2) | Rsv (2) | CRC32 (4) |

(Strings, Blob Data)

+----------+---------+-----------+

Individual fields in entry structure have the following meanings:
NS Namespace index for this entry. For more information on this value, see the section on namespaces implementation.
Type One byte indicating the value data type. See the ItemType enumeration in nvs_flash/include/nvs_handle.hpp for possible values.
Span Number of entries used by this key-value pair. For integer types, this is equal to 1. For strings and blobs, this depends on value length.
ChunkIndex Used to store the index of a blob-data chunk for blob types. For other types, this should be 0xff. CRC32 Checksum calculated over all the bytes in this entry, except for the CRC32 field itself. Key Zero-terminated ASCII string containing a key name. Maximum string length is 15 bytes, excluding a zero
terminator. Data For integer types, this field contains the value itself. If the value itself is shorter than 8 bytes, it is padded to
the right, with unused bytes filled with 0xff. For oblob indexpentry, these 8 bytes hold the following information about data-chunks:
· Size (Only for blob index.) Size, in bytes, of complete blob data. · ChunkCount (Only for blob index.) Total number of blob-data chunks into which the blob was divided
during storage. · ChunkStart (Only for blob index.) ChunkIndex of the first blob-data chunk of this blob. Subsequent
chunks have chunkIndex incrementally allocated (step of 1). For string and blob data chunks, these 8 bytes hold additional data about the value, which are described below:
· Size (Only for strings and blobs.) Size, in bytes, of actual data. For strings, this includes zero terminators. · CRC32 (Only for strings and blobs.) Checksum calculated over all bytes of data.
Variable length values (strings and blobs) are written into subsequent entries, 32 bytes per entry. The Span field of the first entry indicates how many entries are used.

Namespaces As mentioned above, each key-value pair belongs to one of the namespaces. Namespace identifiers (strings) are stored as keys of key-value pairs in namespace with index 0. Values corresponding to these keys are indexes of these namespaces.

+-------------------------------------------+

| NS=0 Type=uint8_t Key="wifi" Value=1

|

+-------------------------------------------+

| NS=1 Type=uint32_t Key="channel" Value=6 |

+-------------------------------------------+

| NS=0 Type=uint8_t Key="pwm" Value=2

|

+-------------------------------------------+

| NS=2 Type=uint16_t Key="channel" Value=20 |

+-------------------------------------------+

Entry describing namespace "wifi" Key "channel" in namespace "wifi" Entry describing namespace "pwm" Key "channel" in namespace "pwm"

Item hash list To reduce the number of reads from flash memory, each member of the Page class maintains a list of pairs: item index; item hash. This list makes searches much quicker. Instead of iterating over all entries, reading them from flash one at a time, Page::findItem first performs a search for the item hash in the hash list. This gives the item index within the page if such an item exists. Due to a hash collision, it is possible that a different item will be found. This is handled by falling back to iteration over items in flash.
Each node in the hash list contains a 24-bit hash and 8-bit item index. Hash is calculated based on item namespace, key name, and ChunkIndex. CRC32 is used for calculation; the result is truncated to 24 bits. To reduce the overhead

Espressif Systems

1005

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

for storing 32-bit entries in a linked list, the list is implemented as a double-linked list of arrays. Each array holds 29 entries, for the total size of 128 bytes, together with linked list pointers and a 32-bit count field. The minimum amount of extra RAM usage per page is therefore 128 bytes; maximum is 640 bytes.
API Reference
Header File
· components/nvs_flash/include/nvs_flash.h
Functions esp_err_t nvs_flash_init(void)
Initialize the default NVS partition.
This API initialises the default NVS partition. The default NVS partition is the one that is labeled onvspin the partition table.
When oNVS_ENCRYPTIONpis enabled in the menuconfig, this API enables the NVS encryption for the default NVS partition as follows
1. Read security configurations from the first NVS key partition listed in the partition table. (NVS key partition is any odataptype partition which has the subtype value set to onvs_keysp)
2. If the NVS key partiton obtained in the previous step is empty, generate and store new keys in that NVS key partiton.
3. Internally call onvs_flash_secure_init()pwith the security configurations obtained/generated in the previous steps.
Post initialization NVS read/write APIs remain the same irrespective of NVS encryption.
Return · ESP_OK if storage was successfully initialized. · ESP_ERR_NVS_NO_FREE_PAGES if the NVS storage contains no empty pages (which may happen if NVS partition was truncated) · ESP_ERR_NOT_FOUND if no partition with label onvspis found in the partition table · ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures · one of the error codes from the underlying flash storage driver · error codes from nvs_flash_read_security_cfg API (when oNVS_ENCRYPTIONpis enabled). · error codes from nvs_flash_generate_keys API (when oNVS_ENCRYPTIONpis enabled). · error codes from nvs_flash_secure_init_partition API (whenoNVS_ENCRYPTIONpis enabled) .
esp_err_t nvs_flash_init_partition(const char *partition_label) Initialize NVS flash storage for the specified partition.
Return · ESP_OK if storage was successfully initialized. · ESP_ERR_NVS_NO_FREE_PAGES if the NVS storage contains no empty pages (which may happen if NVS partition was truncated) · ESP_ERR_NOT_FOUND if specified partition is not found in the partition table · ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures · one of the error codes from the underlying flash storage driver
Parameters · [in] partition_label: Label of the partition. Must be no longer than 16 characters.
esp_err_t nvs_flash_init_partition_ptr(const esp_partition_t *partition) Initialize NVS flash storage for the partition specified by partition pointer.
Return · ESP_OK if storage was successfully initialized · ESP_ERR_NVS_NO_FREE_PAGES if the NVS storage contains no empty pages (which may happen if NVS partition was truncated) · ESP_ERR_INVALID_ARG in case partition is NULL · ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures

Espressif Systems

1006

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· one of the error codes from the underlying flash storage driver Parameters
· [in] partition: pointer to a partition obtained by the ESP partition API.
esp_err_t nvs_flash_deinit(void) Deinitialize NVS storage for the default NVS partition.
Default NVS partition is the partition with onvsplabel in the partition table.
Return · ESP_OK on success (storage was deinitialized) · ESP_ERR_NVS_NOT_INITIALIZED if the storage was not initialized prior to this call
esp_err_t nvs_flash_deinit_partition(const char *partition_label) Deinitialize NVS storage for the given NVS partition.
Return · ESP_OK on success · ESP_ERR_NVS_NOT_INITIALIZED if the storage for given partition was not initialized prior to this call
Parameters · [in] partition_label: Label of the partition
esp_err_t nvs_flash_erase(void) Erase the default NVS partition.
Erases all contents of the default NVS partition (one with label onvsp).
Note If the partition is initialized, this function first de-initializes it. Afterwards, the partition has to be initialized again to be used.
Return · ESP_OK on success · ESP_ERR_NOT_FOUND if there is no NVS partition labeled onvspin the partition table · different error in case de-initialization fails (shouldnnt happen)
esp_err_t nvs_flash_erase_partition(const char *part_name) Erase specified NVS partition.
Erase all content of a specified NVS partition
Note If the partition is initialized, this function first de-initializes it. Afterwards, the partition has to be initialized again to be used.
Return · ESP_OK on success · ESP_ERR_NOT_FOUND if there is no NVS partition with the specified name in the partition table · different error in case de-initialization fails (shouldnnt happen)
Parameters · [in] part_name: Name (label) of the partition which should be erased
esp_err_t nvs_flash_erase_partition_ptr(const esp_partition_t *partition) Erase custom partition.
Erase all content of specified custom partition.
Note If the partition is initialized, this function first de-initializes it. Afterwards, the partition has to be initialized again to be used.
Return · ESP_OK on success · ESP_ERR_NOT_FOUND if there is no partition with the specified parameters in the partition table · ESP_ERR_INVALID_ARG in case partition is NULL · one of the error codes from the underlying flash storage driver
Parameters · [in] partition: pointer to a partition obtained by the ESP partition API.
esp_err_t nvs_flash_secure_init(nvs_sec_cfg_t *cfg) Initialize the default NVS partition.

Espressif Systems

1007

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
This API initialises the default NVS partition. The default NVS partition is the one that is labeled onvspin the partition table.
Return · ESP_OK if storage has been initialized successfully. · ESP_ERR_NVS_NO_FREE_PAGES if the NVS storage contains no empty pages (which may happen if NVS partition was truncated) · ESP_ERR_NOT_FOUND if no partition with label onvspis found in the partition table · ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures · one of the error codes from the underlying flash storage driver
Parameters · [in] cfg: Security configuration (keys) to be used for NVS encryption/decryption. If cfg is NULL, no encryption is used.
esp_err_t nvs_flash_secure_init_partition(const char *partition_label, nvs_sec_cfg_t *cfg) Initialize NVS flash storage for the specified partition.
Return · ESP_OK if storage has been initialized successfully. · ESP_ERR_NVS_NO_FREE_PAGES if the NVS storage contains no empty pages (which may happen if NVS partition was truncated) · ESP_ERR_NOT_FOUND if specified partition is not found in the partition table · ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures · one of the error codes from the underlying flash storage driver
Parameters · [in] partition_label: Label of the partition. Note that internally, a reference to passed value is kept and it should be accessible for future operations · [in] cfg: Security configuration (keys) to be used for NVS encryption/decryption. If cfg is null, no encryption/decryption is used.
esp_err_t nvs_flash_generate_keys(const esp_partition_t *partition, nvs_sec_cfg_t *cfg) Generate and store NVS keys in the provided esp partition.
Return -ESP_OK, if cfg was read successfully; -ESP_INVALID_ARG, if partition or cfg; -or error codes from esp_partition_write/erase APIs.
Parameters · [in] partition: Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL. · [out] cfg: Pointer to nvs security configuration structure. Pointer must be non-NULL. Generated keys will be populated in this structure.
esp_err_t nvs_flash_read_security_cfg(const esp_partition_t *partition, nvs_sec_cfg_t *cfg) Read NVS security configuration from a partition.
Note Provided partition is assumed to be marked mencryptedn. Return -ESP_OK, if cfg was read successfully; -ESP_INVALID_ARG, if partition or cfg; -
ESP_ERR_NVS_KEYS_NOT_INITIALIZED, if the partition is not yet written with keys. ESP_ERR_NVS_CORRUPT_KEY_PART, if the partition containing keys is found to be corrupt -or error codes from esp_partition_read API. Parameters
· [in] partition: Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL.
· [out] cfg: Pointer to nvs security configuration structure. Pointer must be non-NULL.
Structures struct nvs_sec_cfg_t
Key for encryption and decryption.

Espressif Systems

1008

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Public Members
uint8_t eky[NVS_KEY_SIZE] XTS encryption and decryption key
uint8_t tky[NVS_KEY_SIZE] XTS tweak key
Macros NVS_KEY_SIZE
Header File
· components/nvs_flash/include/nvs.h
Functions esp_err_t nvs_set_i8(nvs_handle_t handle, const char *key, int8_t value)
set int8_t value for given key
Set value for the key, given its name. Note that the actual storage will not be updated until nvs_commit is called.
Return · ESP_OK if value was set successfully · ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL · ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only · ESP_ERR_NVS_INVALID_NAME if key name doesnnt satisfy constraints · ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the underlying storage to save the value · ESP_ERR_NVS_REMOVE_FAILED if the value wasnnt updated because flash write operation has failed. The value was written however, and update will be finished after re-initialization of nvs, provided that flash operation doesnnt fail again.
Parameters · [in] handle: Handle obtained from nvs_open function. Handles that were opened read only cannot be used. · [in] key: Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldnnt be empty. · [in] value: The value to set.
esp_err_t nvs_set_u8(nvs_handle_t handle, const char *key, uint8_t value) set uint8_t value for given key
This function is the same as nvs_set_i8 except for the data type.
esp_err_t nvs_set_i16(nvs_handle_t handle, const char *key, int16_t value) set int16_t value for given key
This function is the same as nvs_set_i8 except for the data type.
esp_err_t nvs_set_u16(nvs_handle_t handle, const char *key, uint16_t value) set uint16_t value for given key
This function is the same as nvs_set_i8 except for the data type.
esp_err_t nvs_set_i32(nvs_handle_t handle, const char *key, int32_t value) set int32_t value for given key
This function is the same as nvs_set_i8 except for the data type.
esp_err_t nvs_set_u32(nvs_handle_t handle, const char *key, uint32_t value) set uint32_t value for given key
This function is the same as nvs_set_i8 except for the data type.

Espressif Systems

1009

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
esp_err_t nvs_set_i64(nvs_handle_t handle, const char *key, int64_t value) set int64_t value for given key
This function is the same as nvs_set_i8 except for the data type.
esp_err_t nvs_set_u64(nvs_handle_t handle, const char *key, uint64_t value) set uint64_t value for given key
This function is the same as nvs_set_i8 except for the data type.
esp_err_t nvs_set_str(nvs_handle_t handle, const char *key, const char *value) set string for given key
Set value for the key, given its name. Note that the actual storage will not be updated until nvs_commit is called.
Return · ESP_OK if value was set successfully · ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL · ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only · ESP_ERR_NVS_INVALID_NAME if key name doesnnt satisfy constraints · ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the underlying storage to save the value · ESP_ERR_NVS_REMOVE_FAILED if the value wasnnt updated because flash write operation has failed. The value was written however, and update will be finished after re-initialization of nvs, provided that flash operation doesnnt fail again. · ESP_ERR_NVS_VALUE_TOO_LONG if the string value is too long
Parameters · [in] handle: Handle obtained from nvs_open function. Handles that were opened read only cannot be used. · [in] key: Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldnnt be empty. · [in] value: The value to set. For strings, the maximum length (including null character) is 4000 bytes, if there is one complete page free for writing. This decreases, however, if the free space is fragmented.
esp_err_t nvs_get_i8(nvs_handle_t handle, const char *key, int8_t *out_value) get int8_t value for given key
These functions retrieve value for the key, given its name. If key does not exist, or the requested variable type doesnnt match the type which was used when setting a value, an error is returned.
In case of any error, out_value is not modified.
out_value has to be a pointer to an already allocated variable of the given type.
// Example of using nvs_get_i32: int32_t max_buffer_size = 4096; // default value esp_err_t err = nvs_get_i32(my_handle, "max_buffer_size", &max_buffer_size); assert(err == ESP_OK || err == ESP_ERR_NVS_NOT_FOUND); // if ESP_ERR_NVS_NOT_FOUND was returned, max_buffer_size will still // have its default value.
Return · ESP_OK if the value was retrieved successfully · ESP_ERR_NVS_NOT_FOUND if the requested key doesnnt exist · ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL · ESP_ERR_NVS_INVALID_NAME if key name doesnnt satisfy constraints · ESP_ERR_NVS_INVALID_LENGTH if length is not sufficient to store data
Parameters · [in] handle: Handle obtained from nvs_open function. · [in] key: Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldnnt be empty.

Espressif Systems

1010

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· out_value: Pointer to the output value. May be NULL for nvs_get_str and nvs_get_blob, in this case required length will be returned in length argument.
esp_err_t nvs_get_u8(nvs_handle_t handle, const char *key, uint8_t *out_value) get uint8_t value for given key
This function is the same as nvs_get_i8 except for the data type.
esp_err_t nvs_get_i16(nvs_handle_t handle, const char *key, int16_t *out_value) get int16_t value for given key
This function is the same as nvs_get_i8 except for the data type.
esp_err_t nvs_get_u16(nvs_handle_t handle, const char *key, uint16_t *out_value) get uint16_t value for given key
This function is the same as nvs_get_i8 except for the data type.
esp_err_t nvs_get_i32(nvs_handle_t handle, const char *key, int32_t *out_value) get int32_t value for given key
This function is the same as nvs_get_i8 except for the data type.
esp_err_t nvs_get_u32(nvs_handle_t handle, const char *key, uint32_t *out_value) get uint32_t value for given key
This function is the same as nvs_get_i8 except for the data type.
esp_err_t nvs_get_i64(nvs_handle_t handle, const char *key, int64_t *out_value) get int64_t value for given key
This function is the same as nvs_get_i8 except for the data type.
esp_err_t nvs_get_u64(nvs_handle_t handle, const char *key, uint64_t *out_value) get uint64_t value for given key
This function is the same as nvs_get_i8 except for the data type.
esp_err_t nvs_get_str(nvs_handle_t handle, const char *key, char *out_value, size_t *length) get string value for given key
These functions retrieve the data of an entry, given its key. If key does not exist, or the requested variable type doesnnt match the type which was used when setting a value, an error is returned.
In case of any error, out_value is not modified.
All functions expect out_value to be a pointer to an already allocated variable of the given type.
nvs_get_str and nvs_get_blob functions support WinAPI-style length queries. To get the size necessary to store the value, call nvs_get_str or nvs_get_blob with zero out_value and non-zero pointer to length. Variable pointed to by length argument will be set to the required length. For nvs_get_str, this length includes the zero terminator. When calling nvs_get_str and nvs_get_blob with non-zero out_value, length has to be non-zero and has to point to the length available in out_value. It is suggested that nvs_get/set_str is used for zero-terminated C strings, and nvs_get/set_blob used for arbitrary data structures.
// Example (without error checking) of using nvs_get_str to get a string into dynamic array: size_t required_size; nvs_get_str(my_handle, "server_name", NULL, &required_size); char* server_name = malloc(required_size); nvs_get_str(my_handle, "server_name", server_name, &required_size);
// Example (without error checking) of using nvs_get_blob to get a binary data into a static array: uint8_t mac_addr[6]; size_t size = sizeof(mac_addr); nvs_get_blob(my_handle, "dst_mac_addr", mac_addr, &size);
Return

Espressif Systems

1011

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_OK if the value was retrieved successfully · ESP_ERR_NVS_NOT_FOUND if the requested key doesnnt exist · ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL · ESP_ERR_NVS_INVALID_NAME if key name doesnnt satisfy constraints · ESP_ERR_NVS_INVALID_LENGTH if length is not sufficient to store data Parameters · [in] handle: Handle obtained from nvs_open function. · [in] key: Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters.
Shouldnnt be empty. · [out] out_value: Pointer to the output value. May be NULL for nvs_get_str and
nvs_get_blob, in this case required length will be returned in length argument. · [inout] length: A non-zero pointer to the variable holding the length of out_value. In case
out_value a zero, will be set to the length required to hold the value. In case out_value is not zero, will be set to the actual length of the value written. For nvs_get_str this includes zero terminator.
esp_err_t nvs_get_blob(nvs_handle_t handle, const char *key, void *out_value, size_t *length) get blob value for given key
This function behaves the same as nvs_get_str, except for the data type.
esp_err_t nvs_open(const char *name, nvs_open_mode_t open_mode, nvs_handle_t *out_handle) Open non-volatile storage with a given namespace from the default NVS partition.
Multiple internal ESP-IDF and third party application modules can store their key-value pairs in the NVS module. In order to reduce possible conflicts on key names, each module can use its own namespace. The default NVS partition is the one that is labelled onvspin the partition table.
Return · ESP_OK if storage handle was opened successfully · ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized · ESP_ERR_NVS_PART_NOT_FOUND if the partition with label onvspis not found · ESP_ERR_NVS_NOT_FOUND id namespace doesnnt exist yet and mode is NVS_READONLY · ESP_ERR_NVS_INVALID_NAME if namespace name doesnnt satisfy constraints · ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures · other error codes from the underlying storage driver
Parameters · [in] name: Namespace name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldnnt be empty. · [in] open_mode: NVS_READWRITE or NVS_READONLY. If NVS_READONLY, will open a handle for reading only. All write requests will be rejected for this handle. · [out] out_handle: If successful (return code is zero), handle will be returned in this argument.
esp_err_t nvs_open_from_partition(const char *part_name, const char *name, nvs_open_mode_t open_mode, nvs_handle_t *out_handle)
Open non-volatile storage with a given namespace from specified partition.
The behaviour is same as nvs_open() API. However this API can operate on a specified NVS partition instead of default NVS partition. Note that the specified partition must be registered with NVS using nvs_flash_init_partition() API.
Return · ESP_OK if storage handle was opened successfully · ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized · ESP_ERR_NVS_PART_NOT_FOUND if the partition with specified name is not found · ESP_ERR_NVS_NOT_FOUND id namespace doesnnt exist yet and mode is NVS_READONLY · ESP_ERR_NVS_INVALID_NAME if namespace name doesnnt satisfy constraints · ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures · other error codes from the underlying storage driver
Parameters · [in] part_name: Label (name) of the partition of interest for object read/write/erase · [in] name: Namespace name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldnnt be empty.

Espressif Systems

1012

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· [in] open_mode: NVS_READWRITE or NVS_READONLY. If NVS_READONLY, will open a handle for reading only. All write requests will be rejected for this handle.
· [out] out_handle: If successful (return code is zero), handle will be returned in this argument.
esp_err_t nvs_set_blob(nvs_handle_t handle, const char *key, const void *value, size_t length) set variable length binary value for given key
This family of functions set value for the key, given its name. Note that actual storage will not be updated until nvs_commit function is called.
Return · ESP_OK if value was set successfully · ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL · ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only · ESP_ERR_NVS_INVALID_NAME if key name doesnnt satisfy constraints · ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the underlying storage to save the value · ESP_ERR_NVS_REMOVE_FAILED if the value wasnnt updated because flash write operation has failed. The value was written however, and update will be finished after re-initialization of nvs, provided that flash operation doesnnt fail again. · ESP_ERR_NVS_VALUE_TOO_LONG if the value is too long
Parameters · [in] handle: Handle obtained from nvs_open function. Handles that were opened read only cannot be used. · [in] key: Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldnnt be empty. · [in] value: The value to set. · [in] length: length of binary value to set, in bytes; Maximum length is 508000 bytes or (97.6% of the partition size - 4000) bytes whichever is lower.
esp_err_t nvs_erase_key(nvs_handle_t handle, const char *key) Erase key-value pair with given key name.
Note that actual storage may not be updated until nvs_commit function is called.
Return · ESP_OK if erase operation was successful · ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL · ESP_ERR_NVS_READ_ONLY if handle was opened as read only · ESP_ERR_NVS_NOT_FOUND if the requested key doesnnt exist · other error codes from the underlying storage driver
Parameters · [in] handle: Storage handle obtained with nvs_open. Handles that were opened read only cannot be used. · [in] key: Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldnnt be empty.
esp_err_t nvs_erase_all(nvs_handle_t handle) Erase all key-value pairs in a namespace.
Note that actual storage may not be updated until nvs_commit function is called.
Return · ESP_OK if erase operation was successful · ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL · ESP_ERR_NVS_READ_ONLY if handle was opened as read only · other error codes from the underlying storage driver
Parameters · [in] handle: Storage handle obtained with nvs_open. Handles that were opened read only cannot be used.
esp_err_t nvs_commit(nvs_handle_t handle) Write any pending changes to non-volatile storage.

Espressif Systems

1013

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

After setting any values, nvs_commit() must be called to ensure changes are written to non-volatile storage. Individual implementations may write to storage at other times, but this is not guaranteed.
Return · ESP_OK if the changes have been written successfully · ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL · other error codes from the underlying storage driver
Parameters · [in] handle: Storage handle obtained with nvs_open. Handles that were opened read only cannot be used.
void nvs_close(nvs_handle_t handle) Close the storage handle and free any allocated resources.
This function should be called for each handle opened with nvs_open once the handle is not in use any more. Closing the handle may not automatically write the changes to nonvolatile storage. This has to be done explicitly using nvs_commit function. Once this function is called on a handle, the handle should no longer be used.
Parameters · [in] handle: Storage handle to close
esp_err_t nvs_get_stats(const char *part_name, nvs_stats_t *nvs_stats) Fill structure nvs_stats_t. It provides info about used memory the partition.
This function calculates to runtime the number of used entries, free entries, total entries, and amount namespace in partition.
// Example of nvs_get_stats() to get the number of used entries and free entries: nvs_stats_t nvs_stats; nvs_get_stats(NULL, &nvs_stats); printf("Count: UsedEntries = (%d), FreeEntries = (%d), AllEntries = (%d)\n",
nvs_stats.used_entries, nvs_stats.free_entries, nvs_stats.total_ entries);
Return · ESP_OK if the changes have been written successfully. Return param nvs_stats will be filled. · ESP_ERR_NVS_PART_NOT_FOUND if the partition with label onamepis not found. Return param nvs_stats will be filled 0. · ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized. Return param nvs_stats will be filled 0. · ESP_ERR_INVALID_ARG if nvs_stats equal to NULL. · ESP_ERR_INVALID_STATE if there is page with the status of INVALID. Return param nvs_stats will be filled not with correct values because not all pages will be counted. Counting will be interrupted at the first INVALID page.
Parameters · [in] part_name: Partition name NVS in the partition table. If pass a NULL than will use NVS_DEFAULT_PART_NAME (onvsp). · [out] nvs_stats: Returns filled structure nvs_states_t. It provides info about used memory the partition.
esp_err_t nvs_get_used_entry_count(nvs_handle_t handle, size_t *used_entries) Calculate all entries in a namespace.
An entry represents the smallest storage unit in NVS. Strings and blobs may occupy more than one entry. Note that to find out the total number of entries occupied by the namespace, add one to the returned value used_entries (if err is equal to ESP_OK). Because the name space entry takes one entry.
// Example of nvs_get_used_entry_count() to get amount of all key-value pairs in one namespace: nvs_handle_t handle; nvs_open("namespace1", NVS_READWRITE, &handle); ...
(continues on next page)

Espressif Systems

1014

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)
size_t used_entries; size_t total_entries_namespace; if(nvs_get_used_entry_count(handle, &used_entries) == ESP_OK){
// the total number of entries occupied by the namespace total_entries_namespace = used_entries + 1; }

Return · ESP_OK if the changes have been written successfully. Return param used_entries will be filled valid value. · ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized. Return param used_entries will be filled 0. · ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL. Return param used_entries will be filled 0. · ESP_ERR_INVALID_ARG if used_entries equal to NULL. · Other error codes from the underlying storage driver. Return param used_entries will be filled 0.
Parameters · [in] handle: Handle obtained from nvs_open function. · [out] used_entries: Returns amount of used entries from a namespace.
nvs_iterator_t nvs_entry_find(const char *part_name, const char *namespace_name, nvs_type_t type)
Create an iterator to enumerate NVS entries based on one or more parameters.

// Example of listing all the key-value pairs of any type under specified

partition and namespace

nvs_iterator_t it = nvs_entry_find(partition, namespace, NVS_TYPE_ANY);

while (it != NULL) {

nvs_entry_info_t info;

nvs_entry_info(it, &info);

it = nvs_entry_next(it);

printf("key '%s', type '%d' \n", info.key, info.type);

};

// Note: no need to release iterator obtained from nvs_entry_find function when

//

nvs_entry_find or nvs_entry_next function return NULL, indicating no

other

//

element for specified criteria was found.

}

Return Iterator used to enumerate all the entries found, or NULL if no entry satisfying criteria was found. Iterator obtained through this function has to be released using nvs_release_iterator when not used any more.
Parameters · [in] part_name: Partition name · [in] namespace_name: Set this value if looking for entries with a specific namespace. Pass NULL otherwise. · [in] type: One of nvs_type_t values.
nvs_iterator_t nvs_entry_next(nvs_iterator_t iterator) Returns next item matching the iterator criteria, NULL if no such item exists.
Note that any copies of the iterator will be invalid after this call.
Return NULL if no entry was found, valid nvs_iterator_t otherwise. Parameters
· [in] iterator: Iterator obtained from nvs_entry_find function. Must be non-NULL.
void nvs_entry_info(nvs_iterator_t iterator, nvs_entry_info_t *out_info) Fills nvs_entry_info_t structure with information about entry pointed to by the iterator.
Parameters

Espressif Systems

1015

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· [in] iterator: Iterator obtained from nvs_entry_find or nvs_entry_next function. Must be non-NULL.
· [out] out_info: Structure to which entry information is copied. void nvs_release_iterator(nvs_iterator_t iterator)
Release iterator. Parameters
· [in] iterator: Release iterator obtained from nvs_entry_find function. NULL argument is allowed.
Structures struct nvs_entry_info_t
information about entry obtained from nvs_entry_info function
Public Members
char namespace_name[16] Namespace to which key-value belong
char key[16] Key of stored key-value pair
nvs_type_t type Type of stored key-value pair
struct nvs_stats_t Note Info about storage space NVS.
Public Members
size_t used_entries Amount of used entries.
size_t free_entries Amount of free entries.
size_t total_entries Amount all available entries.
size_t namespace_count Amount name space.
Macros ESP_ERR_NVS_BASE
Starting number of error codes ESP_ERR_NVS_NOT_INITIALIZED
The storage driver is not initialized ESP_ERR_NVS_NOT_FOUND
Id namespace doesnnt exist yet and mode is NVS_READONLY ESP_ERR_NVS_TYPE_MISMATCH
The type of set or get operation doesnnt match the type of value stored in NVS ESP_ERR_NVS_READ_ONLY
Storage handle was opened as read only ESP_ERR_NVS_NOT_ENOUGH_SPACE
There is not enough space in the underlying storage to save the value

Espressif Systems

1016

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_ERR_NVS_INVALID_NAME Namespace name doesnnt satisfy constraints
ESP_ERR_NVS_INVALID_HANDLE Handle has been closed or is NULL
ESP_ERR_NVS_REMOVE_FAILED The value wasnnt updated because flash write operation has failed. The value was written however, and update will be finished after re-initialization of nvs, provided that flash operation doesnnt fail again.
ESP_ERR_NVS_KEY_TOO_LONG Key name is too long
ESP_ERR_NVS_PAGE_FULL Internal error; never returned by nvs API functions
ESP_ERR_NVS_INVALID_STATE NVS is in an inconsistent state due to a previous error. Call nvs_flash_init and nvs_open again, then retry.
ESP_ERR_NVS_INVALID_LENGTH String or blob length is not sufficient to store data
ESP_ERR_NVS_NO_FREE_PAGES NVS partition doesnnt contain any empty pages. This may happen if NVS partition was truncated. Erase the whole partition and call nvs_flash_init again.
ESP_ERR_NVS_VALUE_TOO_LONG String or blob length is longer than supported by the implementation
ESP_ERR_NVS_PART_NOT_FOUND Partition with specified name is not found in the partition table
ESP_ERR_NVS_NEW_VERSION_FOUND NVS partition contains data in new format and cannot be recognized by this version of code
ESP_ERR_NVS_XTS_ENCR_FAILED XTS encryption failed while writing NVS entry
ESP_ERR_NVS_XTS_DECR_FAILED XTS decryption failed while reading NVS entry
ESP_ERR_NVS_XTS_CFG_FAILED XTS configuration setting failed
ESP_ERR_NVS_XTS_CFG_NOT_FOUND XTS configuration not found
ESP_ERR_NVS_ENCR_NOT_SUPPORTED NVS encryption is not supported in this version
ESP_ERR_NVS_KEYS_NOT_INITIALIZED NVS key partition is uninitialized
ESP_ERR_NVS_CORRUPT_KEY_PART NVS key partition is corrupt
ESP_ERR_NVS_WRONG_ENCRYPTION NVS partition is marked as encrypted with generic flash encryption. This is forbidden since the NVS encryption works differently.
ESP_ERR_NVS_CONTENT_DIFFERS Internal error; never returned by nvs API functions. NVS key is different in comparison
NVS_DEFAULT_PART_NAME Default partition name of the NVS partition in the partition table
NVS_PART_NAME_MAX_SIZE maximum length of partition name (excluding null terminator)

Espressif Systems

1017

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
NVS_KEY_NAME_MAX_SIZE Maximal length of NVS key name (including null terminator)
Type Definitions typedef uint32_t nvs_handle_t
Opaque pointer type representing non-volatile storage handle typedef nvs_handle_t nvs_handle
typedef nvs_open_mode_t nvs_open_mode
typedef struct nvs_opaque_iterator_t *nvs_iterator_t Opaque pointer type representing iterator to nvs entries
Enumerations enum nvs_open_mode_t
Mode of opening the non-volatile storage.
Values:
NVS_READONLY Read only
NVS_READWRITE Read and write
enum nvs_type_t Types of variables.
Values:
NVS_TYPE_U8 = 0x01 Type uint8_t
NVS_TYPE_I8 = 0x11 Type int8_t
NVS_TYPE_U16 = 0x02 Type uint16_t
NVS_TYPE_I16 = 0x12 Type int16_t
NVS_TYPE_U32 = 0x04 Type uint32_t
NVS_TYPE_I32 = 0x14 Type int32_t
NVS_TYPE_U64 = 0x08 Type uint64_t
NVS_TYPE_I64 = 0x18 Type int64_t
NVS_TYPE_STR = 0x21 Type string
NVS_TYPE_BLOB = 0x42 Type blob
NVS_TYPE_ANY = 0xff Must be last

Espressif Systems

1018

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

2.6.4 NVS Partition Generator Utility
Introduction
The utility nvs_flash/nvs_partition_generator/nvs_partition_gen.py creates a binary file based on key-value pairs provided in a CSV file. The binary file is compatible with NVS architecture defined in Non-Volatile Storage. This utility is ideally suited for generating a binary blob, containing data specific to ODM/OEM, which can be flashed externally at the time of device manufacturing. This allows manufacturers to generate many instances of the same application firmware with customized parameters for each device, such as a serial number.

Prerequisites
To use this utility in encryption mode, install the following packages: · cryptography package
All the required packages are included in requirements.txt in the root of the esp-idf directory.

CSV file format

Each line of a .csv file should contain 4 parameters, separated by a comma. The table below provides the description for each of these parameters.

No. Pa- Description

Notes

ram-

e-

ter

1 Key Key of the data. The data can be accessed later from an appli-

cation using this key.

2 Type Supported values are file, data and namespace.

3 En- Supported values are: u8, i8, u16, i16, u32, i32, u64, As of now, for the file

cod- i64, string, hex2bin, base64 and binary. This type, only hex2bin, base64,

ing specifies how actual data values are encoded in the resulting bi- string, and binary encoding

nary file. The difference between the string and binary is supported.

encoding is that string data is terminated with a NULL

character, whereas binary data is not.

4 Value Data value.

Encoding and Value cells for the

namespace field type should be

empty. Encoding and Value of

namespace is fixed and is not

configurable. Any values in these

cells are ignored.

Note: The first line of the CSV file should be the column header and it is not configurable. Comments (if provided) are allowed only as the first line of the CSV file, the following line then should always be the column header. Comments should always start with the # symbol.

Below is an example dump of such a CSV file:

key,type,encoding,value

<-- column header

namespace_name,namespace,, <-- First entry should be of type "namespace"

key1,data,u8,1

key2,file,string,/path/to/file

Note:

Espressif Systems

1019

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Make sure there are no spaces: · before and after m,n · at the end of each line in a CSV file

NVS Entry and Namespace association
When a namespace entry is encountered in a CSV file, each following entry will be treated as part of that namespace until the next namespace entry is found. At this point, all the following entries will be treated as part of the new namespace.
Note: First entry in a CSV file should always be a namespace entry.

Multipage Blob Support
By default, binary blobs are allowed to span over multiple pages and are written in the format mentioned in Section Structure of entry. If you intend to use an older format, the utility provides an option to disable this feature.

Encryption Support
The NVS Partition Generator utility also allows you to create an encrypted binary file. The utility uses the AES-XTS encryption. Please refer to NVS Encryption for more details.

Decryption Support
This utility allows you to decrypt an encrypted NVS binary file. The utility uses an NVS binary file encrypted using AES-XTS encryption. Please refer to NVS Encryption for more details.

Running the utility

Usage:

python nvs_partition_gen.py [-h] {generate,generate-key,encrypt,decrypt} ...

Optional Arguments:

+-----+------------+---------------------------------------------------------------

-------+

| No. | Parameter |

Description





|

+=====+============+======================================================================+

| 1 | -h, --help |

show this help message and exit





|

+-----+------------+---------------------------------------------------------------

-------+

Commands:

Run nvs_partition_gen.py {command} -h for additional help

+-----+--------------+-------------------------------------------------------------

-------+ | No. | Parameter |

Description





|

+=====+==============+====================================================================+

| 1 | generate

|

Generate NVS partition





|

(continues on next page)

Espressif Systems

1020

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)

+-----+--------------+-------------------------------------------------------------

-------+

| 2 | generate-key |

Generate keys for encryption





|

+-----+--------------+-------------------------------------------------------------

-------+

| 3 | encrypt

|

Generate NVS encrypted partition





|

+-----+--------------+-------------------------------------------------------------

-------+

| 4 | decrypt

|

Decrypt NVS encrypted partition





|

+-----+--------------+-------------------------------------------------------------

-------+

To generate NVS partition (Default):
Usage:
python nvs_partition_gen.py generate [-h] [--version {1,2}] [--outdir OUTDIR]
input output size

Positional Arguments:

+--------------+----------------------------------------------------------

------------+

| Parameter |

Description





|

+==============+======================================================================+

| input

|

Path to CSV file to parse





|

+--------------+----------------------------------------------------------

------------+

| output

|

Path to output NVS binary file





|

+--------------+----------------------------------------------------------

------------+

| size

|

Size of NVS partition in bytes (must be multiple

of 4096)

|

+--------------+----------------------------------------------------------

------------+

Optional Arguments:

+-----------------+-------------------------------------------------------

-------------+

| Parameter

|

Description





|

+=================+====================================================================+

| -h, --help

|

show this help message and exit





|

+-----------------+-------------------------------------------------------

-------------+

| --version {1,2} |

Set multipage blob version.





|

|

|

Version 1 - Multipage blob support disabled.





|

|

|

Version 2 - Multipage blob support enabled.





|

|

|

Default: Version 2





|

(continues on next page)

Espressif Systems

1021

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)

|

|





|

+-----------------+-------------------------------------------------------

-------------+

| --outdir OUTDIR |

Output directory to store files created





|

|

|

(Default: current directory)





|

+-----------------+-------------------------------------------------------

-------------+

You can run the utility to generate NVS partition using the command below: A sample CSV file is provided with the utility:
python nvs_partition_gen.py generate sample_singlepage_blob.csv sample.bin 0x3000

To generate only encryption keys: Usage:
python nvs_partition_gen.py generate-key [-h] [--keyfile KEYFILE] [--outdir OUTDIR]

Optional Arguments:

+--------------------+----------------------------------------------------

------------------+

| Parameter

|

Description





|

+====================+======================================================================+

| -h, --help

|

show this help message and exit





|

+--------------------+----------------------------------------------------

------------------+

| --keyfile KEYFILE |

Path to output encryption keys file





|

+--------------------+----------------------------------------------------

------------------+

| --outdir OUTDIR |

Output directory to store files created.





|

|

|

(Default: current directory)





|

+--------------------+----------------------------------------------------

------------------+

You can run the utility to generate only encryption keys using the command below: python nvs_partition_gen.py generate-key

To generate encrypted NVS partition: Usage:

python nvs_partition_gen.py encrypt [-h] [--version {1,2}] [--keygen] [--keyfile KEYFILE] [--inputkey
INPUTKEY] [--outdir OUTDIR] input output size

Positional Arguments:

(continues on next page)

Espressif Systems

1022

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)

+--------------+----------------------------------------------------------

------------+

| Parameter |

Description





|

+==============+======================================================================+

| input

|

Path to CSV file to parse





|

+--------------+----------------------------------------------------------

------------+

| output

|

Path to output NVS binary file





|

+--------------+----------------------------------------------------------

------------+

| size

|

Size of NVS partition in bytes (must be multiple

of 4096)

|

+--------------+----------------------------------------------------------

------------+

Optional Arguments:

+---------------------+---------------------------------------------------

-----------------+

| Parameter

|

Description





|

+=====================+====================================================================+

| -h, --help

|

show this help message and exit





|

|

|





|

+---------------------+---------------------------------------------------

-----------------+

| --version {1,2}

|

Set multipage blob version.





|

|

|

Version 1 - Multipage blob support disabled. 



|

|

|

Version 2 - Multipage blob support enabled. 



|

|

|

Default: Version 2





|

+---------------------+---------------------------------------------------

-----------------+

| --keygen

|

Generates key for encrypting NVS partition 



|

+---------------------+---------------------------------------------------

-----------------+

| --keyfile KEYFILE |

Path to output encryption keys file





|

+---------------------+---------------------------------------------------

-----------------+

| --inputkey INPUTKEY |

File having key for encrypting NVS partition 



|

+---------------------+---------------------------------------------------

-----------------+

| --outdir OUTDIR

|

Output directory to store files created





|

|

|

(Default: current directory)





|

+---------------------+---------------------------------------------------

-----------------+

You can run the utility to encrypt NVS partition using the command below: A sample CSV file is provided with the utility:

Espressif Systems

1023

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· Encrypt by allowing the utility to generate encryption keys: python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --keygen
Note: Encryption key of the following format <outdir>/keys/keys-<timestamp>.bin is created.
· Encrypt by allowing the utility to generate encryption keys and store it in provided custom filename: python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --keygen --keyfile sample_keys.bin
Note: Encryption key of the following format <outdir>/keys/sample_keys.bin is created.

Note: This newly created file having encryption keys in keys/ directory is compatible with NVS key-partition structure. Refer to NVS key partition for more details.
· Encrypt by providing the encryption keys as input binary file: python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --inputkey sample_keys.bin

To decrypt encrypted NVS partition: Usage:

python nvs_partition_gen.py decrypt [-h] [--outdir OUTDIR] input key output

Positional Arguments:

+--------------+----------------------------------------------------------

------------+

| Parameter |

Description





|

+==============+======================================================================+

| input

|

Path to encrypted NVS partition file to parse 



|

+--------------+----------------------------------------------------------

------------+

| key

|

Path to file having keys for decryption





|

+--------------+----------------------------------------------------------

------------+

| output

|

Path to output decrypted binary file





|

+--------------+----------------------------------------------------------

------------+

Optional Arguments:

+---------------------+---------------------------------------------------

-----------------+

| Parameter

|

Description





|

+=====================+====================================================================+

| -h, --help

|

show this help message and exit





|

(continues on next page)

Espressif Systems

1024

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)

+---------------------+---------------------------------------------------

-----------------+

| --outdir OUTDIR

|

Output directory to store files created





|

|

|

(Default: current directory)





|

+---------------------+---------------------------------------------------

-----------------+

You can run the utility to decrypt encrypted NVS partition using the command below: python nvs_partition_gen.py decrypt sample_encr.bin sample_keys.bin sample_decr.bin

You can also provide the format version number: · Multipage Blob Support Disabled (Version 1) · Multipage Blob Support Enabled (Version 2)

Multipage Blob Support Disabled (Version 1): You can run the utility in this format by setting the version parameter to 1, as shown below. A sample CSV file is provided with the utility:
python nvs_partition_gen.py generate sample_singlepage_blob.csv sample.bin 0x3000 -version 1

Multipage Blob Support Enabled (Version 2): You can run the utility in this format by setting the version parameter to 2, as shown below. A sample CSV file is provided with the utility: python nvs_partition_gen.py generate sample_multipage_blob.csv sample.bin 0x4000 -version 2
Note: Minimum NVS Partition Size needed is 0x3000 bytes.

Note: When flashing the binary onto the device, make sure it is consistent with the applicationns sdkconfig.

Caveats
· Utility does not check for duplicate keys and will write data pertaining to both keys. You need to make sure that the keys are distinct.
· Once a new page is created, no data will be written in the space left on the previous page. Fields in the CSV file need to be ordered in such a way as to optimize memory.
· Utility supports using multiline strings with file type and singleline strings with data type in the CSV file. · 64-bit datatype is not yet supported.
2.6.5 SD/SDIO/MMC Driver
Overview
The SD/SDIO/MMC driver currently supports SD memory, SDIO cards, and eMMC chips. This is a protocol level driver built on top of SDMMC and SD SPI host drivers. SDMMC and SD SPI host drivers (driver/include/driver/sdmmc_host.h and driver/include/driver/sdspi_host.h) provide API functions for:

Espressif Systems

1025

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· Sending commands to slave devices · Sending and receiving data · Handling error conditions within the bus For functions used to initialize and configure: · SDMMC host, see SDMMC Host API · SD SPI host, see SD SPI Host API The SDMMC protocol layer described in this document handles the specifics of the SD protocol, such as the card initialization and data transfer commands. The protocol layer works with the host via the sdmmc_host_t structure. This structure contains pointers to various functions of the host.
Application Example
An example which combines the SDMMC driver with the FATFS library is provided in the storage/sd_card directory of ESP-IDF examples. This example initializes the card, then writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information.
Combo (memory + IO) cards The driver does not support SD combo cards. Combo cards are treated as IO cards.
Thread safety Most applications need to use the protocol layer only in one task. For this reason, the protocol layer does not implement any kind of locking on the sdmmc_card_t structure, or when accessing SDMMC or SD SPI host drivers. Such locking is usually implemented on a higher layer, e.g., in the filesystem driver.
Protocol layer API
The protocol layer is given the sdmmc_host_t structure. This structure describes the SD/MMC host driver, lists its capabilities, and provides pointers to functions of the driver. The protocol layer stores card-specific information in the sdmmc_card_t structure. When sending commands to the SD/MMC host driver, the protocol layer uses the sdmmc_command_t structure to describe the command, arguments, expected return values, and data to transfer if there is any.
Using API with SD memory cards 1. To initialize the host, call the host driver functions, e.g., sdmmc_host_init(), sdmmc_host_init_slot(). 2. To initialize the card, call sdmmc_card_init() and pass to it the parameters host - the host driver information, and card - a pointer to the structure sdmmc_card_t which will be filled with information about the card when the function completes. 3. To read and write sectors of the card, use sdmmc_read_sectors() and sdmmc_write_sectors() respectively and pass to it the parameter card - a pointer to the card information structure. 4. If the card is not used anymore, call the host driver function - e.g., sdmmc_host_deinit() - to disable the host peripheral and free the resources allocated by the driver.
Using API with eMMC chips From the protocol layerns perspective, eMMC memory chips behave exactly like SD memory cards. Even though eMMCs are chips and do not have a card form factor, the terminology for SD cards can still be applied to eMMC due to the similarity of the protocol (sdmmc_card_t, sdmmc_card_init). Note that eMMC chips cannot be used over SPI, which makes them incompatible with the SD SPI host driver. To initialize eMMC memory and perform read/write operations, follow the steps listed for SD cards in the previous section.

Espressif Systems

1026

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Using API with SDIO cards Initialization and the probing process are the same as with SD memory cards. The only difference is in data transfer commands in SDIO mode.
During the card initialization and probing, performed with sdmmc_card_init(), the driver only configures the following registers of the IO card:
1. The IO portion of the card is reset by setting RES bit in the I/O Abort (0x06) register. 2. If 4-line mode is enabled in host and slot configuration, the driver attempts to set the Bus width field in the Bus
Interface Control (0x07) register. If setting the filed is successful, which means that the slave supports 4-line mode, the host is also switched to 4-line mode. 3. If high-speed mode is enabled in the host configuration, the SHS bit is set in the High Speed (0x13) register.
In particular, the driver does not set any bits in (1) I/O Enable and Int Enable registers, (2) I/O block sizes, etc. Applications can set them by calling sdmmc_io_write_byte().
For card configuration and data transfer, choose the pair of functions relevant to your case from the table below.

Action Read and write a single byte using IO_RW_DIRECT (CMD52) Read and write multiple bytes using IO_RW_EXTENDED (CMD53) in byte mode Read and write blocks of data using IO_RW_EXTENDED (CMD53) in block mode

Read Function

Write Function

sdmmc_io_read_byte(s)dmmc_io_write_byte()

sdmmc_io_read_bytess(d)mmc_io_write_bytes()

sdmmc_io_read_blocksd(m)mc_io_write_blocks()

SDIO interrupts can be enabled by the application using the function sdmmc_io_enable_int(). When using SDIO in 1-line mode, the D1 line also needs to be connected to use SDIO interrupts.
If you want the application to wait until the SDIO interrupt occurs, use sdmmc_io_wait_int().

API Reference
Header File · components/sdmmc/include/sdmmc_cmd.h

Functions esp_err_t sdmmc_card_init(const sdmmc_host_t *host, sdmmc_card_t *out_card)
Probe and initialize SD/MMC card using given host
Note Only SD cards (SDSC and SDHC/SDXC) are supported now. Support for MMC/eMMC cards will be added later.
Return · ESP_OK on success · One of the error codes from SDMMC host controller
Parameters · host: pointer to structure defining host controller · out_card: pointer to structure which will receive information about the card when the function completes
void sdmmc_card_print_info(FILE *stream, const sdmmc_card_t *card) Print information about the card to a stream.
Parameters · stream: stream obtained using fopen or fdopen · card: card information structure initialized using sdmmc_card_init
esp_err_t sdmmc_get_status(sdmmc_card_t *card) Get status of SD/MMC card
Return · ESP_OK on success

Espressif Systems

1027

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· One of the error codes from SDMMC host controller Parameters
· card: pointer to card information structure previously initialized using sdmmc_card_init
esp_err_t sdmmc_write_sectors(sdmmc_card_t *card, const void *src, size_t start_sector, size_t sector_count)
Write given number of sectors to SD/MMC card
Return · ESP_OK on success · One of the error codes from SDMMC host controller
Parameters · card: pointer to card information structure previously initialized using sdmmc_card_init · src: pointer to data buffer to read data from; data size must be equal to sector_count * card>csd.sector_size · start_sector: sector where to start writing · sector_count: number of sectors to write
esp_err_t sdmmc_read_sectors(sdmmc_card_t *card, void *dst, size_t start_sector, size_t sector_count)
Read given number of sectors from the SD/MMC card
Return · ESP_OK on success · One of the error codes from SDMMC host controller
Parameters · card: pointer to card information structure previously initialized using sdmmc_card_init · dst: pointer to data buffer to write into; buffer size must be at least sector_count * card>csd.sector_size · start_sector: sector where to start reading · sector_count: number of sectors to read
esp_err_t sdmmc_io_read_byte(sdmmc_card_t *card, uint32_t function, uint32_t reg, uint8_t *out_byte)
Read one byte from an SDIO card using IO_RW_DIRECT (CMD52)
Return · ESP_OK on success · One of the error codes from SDMMC host controller
Parameters · card: pointer to card information structure previously initialized using sdmmc_card_init · function: IO function number · reg: byte address within IO function · [out] out_byte: output, receives the value read from the card
esp_err_t sdmmc_io_write_byte(sdmmc_card_t *card, uint32_t function, uint32_t reg, uint8_t in_byte, uint8_t *out_byte)
Write one byte to an SDIO card using IO_RW_DIRECT (CMD52)
Return · ESP_OK on success · One of the error codes from SDMMC host controller
Parameters · card: pointer to card information structure previously initialized using sdmmc_card_init · function: IO function number · reg: byte address within IO function · in_byte: value to be written · [out] out_byte: if not NULL, receives new byte value read from the card (read-after-write).
esp_err_t sdmmc_io_read_bytes(sdmmc_card_t *card, uint32_t function, uint32_t addr, void *dst, size_t size)
Read multiple bytes from an SDIO card using IO_RW_EXTENDED (CMD53)

Espressif Systems

1028

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

This function performs read operation using CMD53 in byte mode. For block mode, see sdmmc_io_read_blocks.
Return · ESP_OK on success · ESP_ERR_INVALID_SIZE if size exceeds 512 bytes · One of the error codes from SDMMC host controller
Parameters · card: pointer to card information structure previously initialized using sdmmc_card_init · function: IO function number · addr: byte address within IO function where reading starts · dst: buffer which receives the data read from card · size: number of bytes to read
esp_err_t sdmmc_io_write_bytes(sdmmc_card_t *card, uint32_t function, uint32_t addr, const void *src, size_t size)
Write multiple bytes to an SDIO card using IO_RW_EXTENDED (CMD53)
This function performs write operation using CMD53 in byte mode. For block mode, see sdmmc_io_write_blocks.
Return · ESP_OK on success · ESP_ERR_INVALID_SIZE if size exceeds 512 bytes · One of the error codes from SDMMC host controller
Parameters · card: pointer to card information structure previously initialized using sdmmc_card_init · function: IO function number · addr: byte address within IO function where writing starts · src: data to be written · size: number of bytes to write
esp_err_t sdmmc_io_read_blocks(sdmmc_card_t *card, uint32_t function, uint32_t addr, void *dst, size_t size)
Read blocks of data from an SDIO card using IO_RW_EXTENDED (CMD53)
This function performs read operation using CMD53 in block mode. For byte mode, see sdmmc_io_read_bytes.
Return · ESP_OK on success · ESP_ERR_INVALID_SIZE if size is not divisible by 512 bytes · One of the error codes from SDMMC host controller
Parameters · card: pointer to card information structure previously initialized using sdmmc_card_init · function: IO function number · addr: byte address within IO function where writing starts · dst: buffer which receives the data read from card · size: number of bytes to read, must be divisible by the card block size.
esp_err_t sdmmc_io_write_blocks(sdmmc_card_t *card, uint32_t function, uint32_t addr, const void *src, size_t size)
Write blocks of data to an SDIO card using IO_RW_EXTENDED (CMD53)
This function performs write operation using CMD53 in block mode. For byte mode, see sdmmc_io_write_bytes.
Return · ESP_OK on success · ESP_ERR_INVALID_SIZE if size is not divisible by 512 bytes · One of the error codes from SDMMC host controller
Parameters · card: pointer to card information structure previously initialized using sdmmc_card_init · function: IO function number

Espressif Systems

1029

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· addr: byte address within IO function where writing starts · src: data to be written · size: number of bytes to read, must be divisible by the card block size.
esp_err_t sdmmc_io_enable_int(sdmmc_card_t *card) Enable SDIO interrupt in the SDMMC host
Return · ESP_OK on success · ESP_ERR_NOT_SUPPORTED if the host controller does not support IO interrupts
Parameters · card: pointer to card information structure previously initialized using sdmmc_card_init
esp_err_t sdmmc_io_wait_int(sdmmc_card_t *card, TickType_t timeout_ticks) Block until an SDIO interrupt is received
Slave uses D1 line to signal interrupt condition to the host. This function can be used to wait for the interrupt.
Return · ESP_OK if the interrupt is received · ESP_ERR_NOT_SUPPORTED if the host controller does not support IO interrupts · ESP_ERR_TIMEOUT if the interrupt does not happen in timeout_ticks
Parameters · card: pointer to card information structure previously initialized using sdmmc_card_init · timeout_ticks: time to wait for the interrupt, in RTOS ticks
esp_err_t sdmmc_io_get_cis_data(sdmmc_card_t *card, uint8_t *out_buffer, size_t buffer_size, size_t *inout_cis_size)
Get the data of CIS region of an SDIO card.
You may provide a buffer not sufficient to store all the CIS data. In this case, this function stores as much data into your buffer as possible. Also, this function will try to get and return the size required for you.
Return · ESP_OK: on success · ESP_ERR_INVALID_RESPONSE: if the card does not (correctly) support CIS. · ESP_ERR_INVALID_SIZE: CIS_CODE_END found, but buffer_size is less than required size, which is stored in the inout_cis_size then. · ESP_ERR_NOT_FOUND: if the CIS_CODE_END not found. Increase input value of inout_cis_size or set it to 0, if you still want to search for the end; output value of inout_cis_size is invalid in this case. · and other error code return from sdmmc_io_read_bytes
Parameters · card: pointer to card information structure previously initialized using sdmmc_card_init · out_buffer: Output buffer of the CIS data · buffer_size: Size of the buffer. · inout_cis_size: Mandatory, pointer to a size, input and output. ­ input: Limitation of maximum searching range, should be 0 or larger than buffer_size. The function searches for CIS_CODE_END until this range. Set to 0 to search infinitely. ­ output: The size required to store all the CIS data, if CIS_CODE_END is found.
esp_err_t sdmmc_io_print_cis_info(uint8_t *buffer, size_t buffer_size, FILE *fp) Parse and print the CIS information of an SDIO card.
Note Not all the CIS codes and all kinds of tuples are supported. If you see some unresolved code, you can add the parsing of these code in sdmmc_io.c and contribute to the IDF through the Github repository.
using sdmmc_card_init
Return · ESP_OK: on success · ESP_ERR_NOT_SUPPORTED: if the value from the card is not supported to be parsed. · ESP_ERR_INVALID_SIZE: if the CIS size fields are not correct.
Parameters

Espressif Systems

1030

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· buffer: Buffer to parse · buffer_size: Size of the buffer. · fp: File pointer to print to, set to NULL to print to stdout.
Header File · components/driver/include/driver/sdmmc_types.h
Structures struct sdmmc_csd_t
Decoded values from SD card Card Specific Data register
Public Members
int csd_ver CSD structure format
int mmc_ver MMC version (for CID format)
int capacity total number of sectors
int sector_size sector size in bytes
int read_block_len block length for reads
int card_command_class Card Command Class for SD
int tr_speed Max transfer speed
struct sdmmc_cid_t Decoded values from SD card Card IDentification register
Public Members
int mfg_id manufacturer identification number
int oem_id OEM/product identification number
char name[8] product name (MMC v1 has the longest)
int revision product revision
int serial product serial number
int date manufacturing date
struct sdmmc_scr_t Decoded values from SD Configuration Register

Espressif Systems

1031

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Public Members
int sd_spec SD Physical layer specification version, reported by card
int bus_width bus widths supported by card: BIT(0) i1-bit bus, BIT(2) i4-bit bus
struct sdmmc_ext_csd_t Decoded values of Extended Card Specific Data
Public Members
uint8_t power_class Power class used by the card
struct sdmmc_switch_func_rsp_t SD SWITCH_FUNC response buffer
Public Members
uint32_t data[512 / 8 / sizeof(uint32_t)] response data
struct sdmmc_command_t SD/MMC command information
Public Members
uint32_t opcode SD or MMC command index
uint32_t arg SD/MMC command argument
sdmmc_response_t response response buffer
void *data buffer to send or read into
size_t datalen length of data buffer
size_t blklen block length
int flags see below
esp_err_t error error returned from transfer
int timeout_ms response timeout, in milliseconds
struct sdmmc_host_t SD/MMC Host description This structure defines properties of SD/MMC host and functions of SD/MMC host which can be used by upper layers.

Espressif Systems

1032

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Public Members
uint32_t flags flags defining host properties
int slot slot number, to be passed to host functions
int max_freq_khz max frequency supported by the host
float io_voltage I/O voltage used by the controller (voltage switching is not supported)
esp_err_t (*init)(void) Host function to initialize the driver
esp_err_t (*set_bus_width)(int slot, size_t width) host function to set bus width
size_t (*get_bus_width)(int slot) host function to get bus width
esp_err_t (*set_bus_ddr_mode)(int slot, bool ddr_enable) host function to set DDR mode
esp_err_t (*set_card_clk)(int slot, uint32_t freq_khz) host function to set card clock frequency
esp_err_t (*do_transaction)(int slot, sdmmc_command_t *cmdinfo) host function to do a transaction
esp_err_t (*deinit)(void) host function to deinitialize the driver
esp_err_t (*deinit_p)(int slot) host function to deinitialize the driver, called with the slot
esp_err_t (*io_int_enable)(int slot) Host function to enable SDIO interrupt line
esp_err_t (*io_int_wait)(int slot, TickType_t timeout_ticks) Host function to wait for SDIO interrupt line to be active
int command_timeout_ms timeout, in milliseconds, of a single command. Set to 0 to use the default value.
struct sdmmc_card_t SD/MMC card information structure
Public Members
sdmmc_host_t host Host with which the card is associated
uint32_t ocr OCR (Operation Conditions Register) value
sdmmc_cid_t cid decoded CID (Card IDentification) register value
sdmmc_response_t raw_cid raw CID of MMC card to be decoded after the CSD is fetched in the data transfer mode
sdmmc_csd_t csd decoded CSD (Card-Specific Data) register value

Espressif Systems

1033

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
sdmmc_scr_t scr decoded SCR (SD card Configuration Register) value
sdmmc_ext_csd_t ext_csd decoded EXT_CSD (Extended Card Specific Data) register value
uint16_t rca RCA (Relative Card Address)
uint16_t max_freq_khz Maximum frequency, in kHz, supported by the card
uint32_t is_mem : 1 Bit indicates if the card is a memory card
uint32_t is_sdio : 1 Bit indicates if the card is an IO card
uint32_t is_mmc : 1 Bit indicates if the card is MMC
uint32_t num_io_functions : 3 If is_sdio is 1, contains the number of IO functions on the card
uint32_t log_bus_width : 2 log2(bus width supported by card)
uint32_t is_ddr : 1 Card supports DDR mode
uint32_t reserved : 23 Reserved for future expansion
Macros SDMMC_HOST_FLAG_1BIT
host supports 1-line SD and MMC protocol SDMMC_HOST_FLAG_4BIT
host supports 4-line SD and MMC protocol
SDMMC_HOST_FLAG_8BIT host supports 8-line MMC protocol
SDMMC_HOST_FLAG_SPI host supports SPI protocol
SDMMC_HOST_FLAG_DDR host supports DDR mode for SD/MMC
SDMMC_HOST_FLAG_DEINIT_ARG host deinit function called with the slot argument
SDMMC_FREQ_DEFAULT SD/MMC Default speed (limited by clock divider)
SDMMC_FREQ_HIGHSPEED SD High speed (limited by clock divider)
SDMMC_FREQ_PROBING SD/MMC probing speed
SDMMC_FREQ_52M MMC 52MHz speed
SDMMC_FREQ_26M MMC 26MHz speed

Espressif Systems

1034

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Type Definitions typedef uint32_t sdmmc_response_t[4]
SD/MMC command response buffer
2.6.6 SPI Flash API
Overview
The spi_flash component contains API functions related to reading, writing, erasing, memory mapping for data in the external flash. The spi_flash component also has higher-level API functions which work with partitions defined in the partition table. Different from the API before IDF v4.0, the functionality of esp_flash_* APIs is not limited to theomainpSPI flash chip (the same SPI flash chip from which program runs). With different chip pointers, you can access to external flash chips connected to not only SPI0/1 but also other SPI buses like SPI2.
Note: Instead of through the cache connected to the SPI0 peripheral, most esp_flash_* APIs go through other SPI peripherals like SPI1, SPI2, etc.. This makes them able to access to not only the main flash, but also external flash. However due to limitations of the cache, operations through the cache are limited to the main flash. The address range limitation for these operations are also on the cache side. The cache is not able to access external flash chips or address range above its capabilities. These cache operations include: mmap, encrypted read/write, executing code or access to variables in the flash.
Note: Flash APIs after IDF v4.0 are no longer atomic. A writing operation during another on-going read operation, on the overlapped flash address, may cause the return data from the read operation to be partly same as before, and partly updated as new written.
Kconfig option CONFIG_SPI_FLASH_USE_LEGACY_IMPL can be used to switch spi_flash_* functions back to the implementation before ESP-IDF v4.0. However, the code size may get bigger if you use the new API and the old API at the same time. Encrypted reads and writes use the old implementation, even if CONFIG_SPI_FLASH_USE_LEGACY_IMPL is not enabled. As such, encrypted flash operations are only supported with the main flash chip (and not with other flash chips, that is on SPI1 with different CS, or on other SPI buses). Reading through cache is only supported on the main flash, which is determined by the HW.
Support for Features of Flash Chips
Flash features of different vendors are operated in different ways and need special support. The fast/slow read and Dual mode (DOUT/DIO) of almost all 24-bits address flash chips are supported, because they donnt need any vendor-specific commands. Quad mode (QIO/QOUT) is supported on following chip types:
1. ISSI 2. GD 3. MXIC 4. FM 5. Winbond 6. XMC 7. BOYA Octal mode (OPI) are supported on following chip types: 1. MXIC

Espressif Systems

1035

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
To know how to configure menuconfig for a board with different Flash and PSRAM, please refer to the SPI Flash and External SPI RAM Configuration The 32-bit address range of following chip type is supported:
1. W25Q256 2. GD25Q256 Users can also customize their own flash chip driver, see Overriding Default Chip Drivers for more details.

Warning: Customizing SPI Flash Chip Drivers is considered an oexpertpfeature. Users should only do so at their own risk. (See the notes below)

Overriding Default Chip Drivers During the SPI Flash driverns initialization (i.e., esp_flash_init()), there is a chip detection step during which the driver will iterate through a Default Chip Driver List and determine which chip driver can properly support the currently connected flash chip. The Default Chip Drivers are provided by the IDF, thus are updated in together with each IDF version. However IDF also allows users to customize their own chip drivers.
Users should note the following when customizing chip drivers:
1. You may need to rely on some non-public IDF functions, which have slight possibility to change between IDF versions. On the one hand, these changes may be useful bug fixes for your driver, on the other hand, they may also be breaking changes (i.e., breaks your code).
2. Some IDF bug fixes to other chip drivers will not be automatically applied to your own custom chip drivers. 3. If the protection of flash is not handled properly, there may be some random reliability issues. 4. If you update to a newer IDF version that has support for more chips, you will have to manually add those new
chip drivers into your custom chip driver list. Otherwise the driver will only search for the drivers in custom list you provided.

Steps For Creating Custom Chip Drivers and Overriding the IDF Default Driver List
1. Enable the CONFIG_SPI_FLASH_OVERRIDE_CHIP_DRIVER_LIST config option. This will prevent compilation and linking of the Default Chip Driver List (default_registered_chips) provided by IDF. Instead, the linker will search for the structure of the same name (default_registered_chips) that must be provided by the user.
2. Add a new component in your project, e.g. custom_chip_driver. 3. Copy the necessary chip driver files from the spi_flash component in IDF. This may include:
· spi_flash_chip_drivers.c (to provide the default_registered_chips structure) · Any of the spi_flash_chip_*.c files that matches your own flash model best · CMakeLists.txt and linker.lf files Modify the files above properly.
Note:
· When writing your own flash chip driver, you can set your flash chip capabilities through spi_flash_chip_***(vendor)_get_caps and points the function pointer get_chip_caps for protection to the spi_flash_chip_***_get_caps function. The steps are as follows. 1. Please check whether your flash chip have the capabilities listed in spi_flash_caps_t by checking the flash datasheet. 2. Write a function named spi_flash_chip_***(vendor)_get_caps. Take the example below as a reference. (if the flash support suspend and read unique id). 3. Points the the pointer get_chip_caps (in spi_flash_chip_t) to the function mentioned above.
spi_flash_caps_t spi_flash_chip_***(vendor)_get_caps(esp_flash_t *chip) {
spi_flash_caps_t caps_flags = 0; // 32-bit-address flash is not supported flash-suspend is supported
(continues on next page)

Espressif Systems

1036

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

caps_flags |= SPI_FLAHS_CHIP_CAP_SUSPEND; // flash read unique id. caps_flags |= SPI_FLASH_CHIP_CAP_UNIQUE_ID; return caps_flags; }

(continued from previous page)

const spi_flash_chip_t esp_flash_chip_eon = { // Other function pointers .get_chip_caps = spi_flash_chip_eon_get_caps,
};
· You also can see how to implement this in the example storage/custom_flash_driver.

4. Add linking dependency from spi_flash component to the new custom_chip_driver component, by adding the

following lines after the idf_component_register, in the CMakeLists.txt file of the custom_chip_driver compo-

nent:

idf_component_get_property(spi_flash_lib

spi_flash

COMPONENT_LIB)

set_property(TARGET

${spi_flash_lib}

APPEND

PROPERTY

INTER-

FACE_LINK_LIBRARIES $<LINK_ONLY:${COMPONENT_LIB}>)

5. The linker.lf is used to put every chip driver that you are going to use whilst cache is disabled into internal

RAM. See Linker Script Generation for more details. Make sure this file covers all the source files that you add.

6. Build your project, and you will see the new flash driver is used.

Example See also storage/custom_flash_driver.

Initializing a Flash Device
To use esp_flash_* APIs, you need to have a chip initialized on a certain SPI bus.
1. Call spi_bus_initialize() to properly initialize an SPI bus. This functions initialize the resources (I/O, DMA, interrupts) shared among devices attached to this bus.
2. Call spi_bus_add_flash_device() to attach the flash device onto the bus. This allocates memory, and fill the members for the esp_flash_t structure. The CS I/O is also initialized here.
3. Call esp_flash_init() to actually communicate with the chip. This will also detect the chip type, and influence the following operations.
Note: Multiple flash chips can be attached to the same bus now. However, using esp_flash_* devices and spi_device_* devices on the same SPI bus is not supported yet.

SPI Flash Access API
This is the set of API functions for working with data in flash:
· esp_flash_read() reads data from flash to RAM · esp_flash_write() writes data from RAM to flash · esp_flash_erase_region() erases specific region of flash · esp_flash_erase_chip() erases the whole flash · esp_flash_get_chip_size() returns flash chip size, in bytes, as configured in menuconfig
Generally, try to avoid using the raw SPI flash functions to the omainpSPI flash chip in favour of partition-specific functions.

Espressif Systems

1037

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
SPI Flash Size
The SPI flash size is configured by writing a field in the software bootloader image header, flashed at offset 0x1000. By default, the SPI flash size is detected by esptool.py when this bootloader is written to flash, and the header is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting CONFIG_ESPTOOLPY_FLASHSIZE in project configuration. If it is necessary to override the configured flash size at runtime, it is possible to set the chip_size member of the g_rom_flashchip structure. This size is used by esp_flash_* functions (in both software & ROM) to check the bounds.
Concurrency Constraints for flash on SPI1
Concurrency Constraints for flash on SPI1 The SPI0/1 bus is shared between the instruction & data cache (for firmware execution) and the SPI1 peripheral (controlled by the drivers including this SPI Flash driver). Hence, operations to SPI1 will cause significant influence to the whole system. This kind of operations include calling SPI Flash API or other drivers on SPI1 bus, any operations like read/write/erase or other user defined SPI operations, regardless to the main flash or other SPI slave devices. On ESP32-S3, these caches must be disabled while reading/writing/erasing.
When the caches are disabled Under this condition, all CPUs should always execute code and access data from internal RAM. The APIs documented in this file will disable the caches automatically and transparently. The way that these APIs disable the caches will suspend all the other tasks. Besides, all non-IRAM-safe interrupts will be disabled. The other core will be polling in a busy loop. These will be restored until the Flash operation completes. See also OS Functions, SPI Bus Lock. There are no such constraints and impacts for flash chips on other SPI buses than SPI0/1. For differences between internal RAM (e.g. IRAM, DRAM) and flash cache, please refer to the application memory layout documentation.
IRAM-Safe Interrupt Handlers For interrupt handlers which need to execute when the cache is disabled (e.g., for low latency operations), set the ESP_INTR_FLAG_IRAM flag when the interrupt handler is registered. You must ensure that all data and functions accessed by these interrupt handlers, including the ones that handlers call, are located in IRAM or DRAM. See How to place code in IRAM. If a function or symbol is not correctly put into IRAM/DRAM, and the interrupt handler reads from the flash cache during a flash operation, it will cause a crash due to Illegal Instruction exception (for code which should be in IRAM) or garbage data to be read (for constant data which should be in DRAM).
Note: When working with string in ISRs, it is not advised to use printf and other output functions. For debugging purposes, use ESP_DRAM_LOGE() and similar macros when logging from ISRs. Make sure that both TAG and format string are placed into DRAM in that case.
Non-IRAM-Safe Interrupt Handlers If the ESP_INTR_FLAG_IRAM flag is not set when registering, the interrupt handler will not get executed when the caches are disabled. Once the caches are restored, the non-IRAM-safe interrupts will be re-enabled. After this moment, the interrupt handler will run normally again. This means that as long as caches are disabled, users wonnt see the corresponding hardware event happening.

Espressif Systems

1038

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Attention: The SPI0/1 bus is shared between the instruction & data cache (for firmware execution) and the SPI1 peripheral (controlled by the drivers including this SPI flash driver). Hence, calling SPI Flash API on SPI1 bus (including the main flash) will cause significant influence to the whole system. See Concurrency Constraints for flash on SPI1 for more details.
Partition Table API
ESP-IDF projects use a partition table to maintain information about various regions of SPI flash memory (bootloader, various application binaries, data, filesystems). More information on partition tables can be found here.
This component provides API functions to enumerate partitions found in the partition table and perform operations on them. These functions are declared in esp_partition.h:
· esp_partition_find() checks a partition table for entries with specific type, returns an opaque iterator. · esp_partition_get() returns a structure describing the partition for a given iterator. · esp_partition_next() shifts the iterator to the next found partition. · esp_partition_iterator_release() releases iterator returned by esp_partition_find. · esp_partition_find_first() - a convenience function which returns the structure describing the
first partition found by esp_partition_find. · esp_partition_read(), esp_partition_write(), esp_partition_erase_range()
are equivalent to spi_flash_read(), spi_flash_write(), spi_flash_erase_range(), but operate within partition boundaries.
Note: Application code should mostly use these esp_partition_* API functions instead of lower level esp_flash_* API functions. Partition table API functions do bounds checking and calculate correct offsets in flash, based on data stored in a partition table.

SPI Flash Encryption
It is possible to encrypt the contents of SPI flash and have it transparently decrypted by hardware. Refer to the Flash Encryption documentation for more details.
Memory Mapping API
ESP32-S3 features memory hardware which allows regions of flash memory to be mapped into instruction and data address spaces. This mapping works only for read operations. It is not possible to modify contents of flash memory by writing to a mapped memory region. Mapping happens in 64 KB pages. Memory mapping hardware can map flash into the data address space and the instruction address space. See the technical reference manual for more details and limitations about memory mapping hardware. Note that some pages are used to map the application itself into memory, so the actual number of available pages may be less than the capability of the hardware. Reading data from flash using a memory mapped region is the only way to decrypt contents of flash when flash encryption is enabled. Decryption is performed at the hardware level. Memory mapping API are declared in esp_spi_flash.h and esp_partition.h:
· spi_flash_mmap() maps a region of physical flash addresses into instruction space or data space of the CPU.
· spi_flash_munmap() unmaps previously mapped region. · esp_partition_mmap() maps part of a partition into the instruction space or data space of the CPU. Differences between spi_flash_mmap() and esp_partition_mmap() are as follows:

Espressif Systems

1039

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· spi_flash_mmap() must be given a 64 KB aligned physical address. · esp_partition_mmap() may be given any arbitrary offset within the partition, it will adjust the returned
pointer to mapped memory as necessary. Note that since memory mapping happens in pages, it may be possible to read data outside of the partition provided to esp_partition_mmap, regardless of the partition boundary.
Note: mmap is supported by cache, so it can only be used on main flash.
SPI Flash Implementation
The esp_flash_t structure holds chip data as well as three important parts of this API: 1. The host driver, which provides the hardware support to access the chip; 2. The chip driver, which provides compatibility service to different chips; 3. The OS functions, provides support of some OS functions (e.g. lock, delay) in different stages (1st/2st boot, or the app).
Host driver The host driver relies on an interface (spi_flash_host_driver_t) defined in the spi_flash_types.h (in the hal/include/hal folder). This interface provides some common functions to communicate with the chip. In other files of the SPI HAL, some of these functions are implemented with existing ESP32-S3 memory-spi functionalities. However due to the speed limitations of ESP32-S3, the HAL layer cannt provide high-speed implementations to some reading commands (So we didnnt do it at all). The files (memspi_host_driver.h and .c) implement the high-speed version of these commands with the common_command function provided in the HAL, and wrap these functions as spi_flash_host_driver_t for upper layer to use. You can also implement your own host driver, even with the GPIO. As long as all the functions in the spi_flash_host_driver_t are implemented, the esp_flash API can access to the flash regardless of the low-level hardware.
Chip Driver The chip driver, defined in spi_flash_chip_driver.h, wraps basic functions provided by the host driver for the API layer to use. Some operations need some commands to be sent first, or read some status after. Some chips need different command or value, or need special communication ways. There is a type of chip called generic chip which stands for common chips. Other special chip drivers can be developed on the base of the generic chip. The chip driver relies on the host driver.
OS Functions Currently the OS function layer provides entries of a lock and delay. The lock (see SPI Bus Lock) is used to resolve the conflicts among the access of devices on the same SPI bus, and the SPI Flash chip access. E.g.
1. On SPI1 bus, the cache (used to fetch the data (code) in the Flash and PSRAM) should be disabled when the flash chip on the SPI0/1 is being accessed.
2. On the other buses, the flash driver needs to disable the ISR registered by SPI Master driver, to avoid conflicts. 3. Some devices of SPI Master driver may requires to use the bus monopolized during a period. (especially when
the device doesnnt have CS wire, or the wire is controlled by the software like SDSPI driver). The delay is used by some long operations which requires the master to wait or polling periodically. The top API wraps these the chip driver and OS functions into an entire component, and also provides some argument checking.

Espressif Systems

1040

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

OS functions can also help to avoid a watchdog timeout when erasing large flash areas. During this time, the CPU is occupied with the flash erasing task. This stops other tasks from being executed. Among these tasks is the idle task to feed the watchdog timer (WDT). If the configuration option CONFIG_ESP_TASK_WDT_PANIC is selected and the flash operation time is longer than the watchdog timeout period, the system will reboot.

Itns pretty hard to totally eliminate this risk, because the erasing time varies with different flash chips, making it hard to be compatible in flash drivers. Therefore, users need to pay attention to it. Please use the following guidelines:

1. It is recommended to enable the CONFIG_SPI_FLASH_YIELD_DURING_ERASE option to allow the scheduler to re-schedule during erasing flash memory. Besides, following parameters can also be used.

· Increase

CONFIG_SPI_FLASH_ERASE_YIELD_TICKS

or

decrease

CON-

FIG_SPI_FLASH_ERASE_YIELD_DURATION_MS in menuconfig.

· You can also increase CONFIG_ESP_TASK_WDT_TIMEOUT_S in menuconfig for a larger watchdog timeout

period. However, with larger watchdog timeout period, previously detected timeouts may no longer be detected.

2. Please be aware of the consequences of enabling the CONFIG_ESP_TASK_WDT_PANIC option when doing long-running SPI flash operations which will trigger the panic handler when it times out. However, this option can also help dealing with unexpected exceptions in your application. Please decide whether this is needed to be enabled according to actual condition.
3. During your development, please carefully review the actual flash operation according to the specific requirements and time limits on erasing flash memory of your projects. Always allow reasonable redundancy based on your specific product requirements when configuring the flash erasing timeout threshold, thus improving the reliability of your product.

See Also
· Partition Table documentation · Over The Air Update (OTA) API provides high-level API for updating app firmware stored in flash. · Non-Volatile Storage (NVS) API provides a structured API for storing small pieces of data in SPI flash.

Implementation Details
In order to perform some flash operations, it is necessary to make sure that both CPUs are not running any code from flash for the duration of the flash operation: - In a single-core setup, the SDK does it by disabling interrupts/scheduler before performing the flash operation. - In a dual-core setup, this is slightly more complicated as the SDK needs to make sure that the other CPU is not running any code from flash.
When SPI flash API is called on CPU A (can be PRO or APP), start the spi_flash_op_block_func function on CPU B using the esp_ipc_call API. This API wakes up a high priority task on CPU B and tells it to execute a given function, in this case, spi_flash_op_block_func. This function disables cache on CPU B and signals that the cache is disabled by setting the s_flash_op_can_start flag. Then the task on CPU A disables cache as well and proceeds to execute flash operation.
While a flash operation is running, interrupts can still run on CPUs A and B. It is assumed that all interrupt code is placed into RAM. Once the interrupt allocation API is added, a flag should be added to request the interrupt to be disabled for the duration of a flash operations.
Once the flash operation is complete, the function on CPU A sets another flag, s_flash_op_complete, to let the task on CPU B know that it can re-enable cache and release the CPU. Then the function on CPU A re-enables the cache on CPU A as well and returns control to the calling code.
Additionally, all API functions are protected with a mutex (s_flash_op_mutex).
In a single core environment (CONFIG_FREERTOS_UNICORE enabled), you need to disable both caches, so that no inter-CPU communication can take place.

API Reference - SPI Flash Header File

Espressif Systems

1041

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· components/spi_flash/include/esp_flash_spi_init.h

Functions

esp_err_t spi_bus_add_flash_device(esp_flash_t

**out_chip,

esp_flash_spi_device_config_t *config) Add a SPI Flash device onto the SPI bus.

const

The bus should be already initialized by spi_bus_initialization.

Return · ESP_ERR_INVALID_ARG: out_chip is NULL, or some field in the config is invalid. · ESP_ERR_NO_MEM: failed to allocate memory for the chip structures. · ESP_OK: success.
Parameters · out_chip: Pointer to hold the initialized chip. · config: Configuration of the chips to initialize.
esp_err_t spi_bus_remove_flash_device(esp_flash_t *chip) Remove a SPI Flash device from the SPI bus.

Return · ESP_ERR_INVALID_ARG: The chip is invalid. · ESP_OK: success.
Parameters · chip: The flash device to remove.

Structures struct esp_flash_spi_device_config_t
Configurations for the SPI Flash to init.

Public Members
spi_host_device_t host_id Bus to use.
int cs_io_num GPIO pin to output the CS signal.
esp_flash_io_mode_t io_mode IO mode to read from the Flash.
esp_flash_speed_t speed Speed of the Flash clock.
int input_delay_ns Input delay of the data pins, in ns. Set to 0 if unknown.
int cs_id CS line ID, ignored when not host_id is not SPI1_HOST, or CONFIG_SPI_FLASH_SHARE_SPI1_BUS is enabled. In this case, the CS line used is automatically assigned by the SPI bus lock.

Header File · components/spi_flash/include/esp_flash.h

Functions esp_err_t esp_flash_init(esp_flash_t *chip)
Initialise SPI flash chip interface.
This function must be called before any other API functions are called for this chip.

Espressif Systems

1042

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Note Only the host and read_mode fields of the chip structure must be initialised before this function is called. Other fields may be auto-detected if left set to zero or NULL.
Note If the chip->drv pointer is NULL, chip chip_drv will be auto-detected based on its manufacturer & product IDs. See esp_flash_registered_flash_drivers pointer for details of this process.
Return ESP_OK on success, or a flash error code if initialisation fails. Parameters
· chip: Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. bool esp_flash_chip_driver_initialized(const esp_flash_t *chip)
Check if appropriate chip driver is set.
Return true if set, otherwise false. Parameters
· chip: Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
esp_err_t esp_flash_read_id(esp_flash_t *chip, uint32_t *out_id) Read flash ID via the common oRDIDpSPI flash command.
ID is a 24-bit value. Lower 16 bits of midnare the chip ID, upper 8 bits are the manufacturer ID.
Parameters · chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init() · [out] out_id: Pointer to receive ID value.
Return ESP_OK on success, or a flash error code if operation failed.
esp_err_t esp_flash_get_size(esp_flash_t *chip, uint32_t *out_size) Detect flash size based on flash ID.
Note Most flash chips use a common format for flash ID, where the lower 4 bits specify the size as a power of 2. If the manufacturer doesnnt follow this convention, the size may be incorrectly detected.
Return ESP_OK on success, or a flash error code if operation failed. Parameters
· chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init() · [out] out_size: Detected size in bytes.
esp_err_t esp_flash_read_unique_chip_id(esp_flash_t *chip, uint64_t *out_id) Read flash unique ID via the common oRDUIDpSPI flash command.
ID is a 64-bit value.
Parameters · chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init(). · [out] out_id: Pointer to receive unique ID value.
Return · ESP_OK on success, or a flash error code if operation failed. · ESP_ERR_NOT_SUPPORTED if the chip doesnnt support read id.
esp_err_t esp_flash_erase_chip(esp_flash_t *chip) Erase flash chip contents.
Return · ESP_OK on success, · ESP_ERR_NOT_SUPPORTED if the chip is not able to perform the operation. This is indicated by WREN = 1 after the command is sent. · Other flash error code if operation failed.
Parameters · chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()
esp_err_t esp_flash_erase_region(esp_flash_t *chip, uint32_t start, uint32_t len) Erase a region of the flash chip.
Sector size is specifyed in chip->drv->sector_size field (typically 4096 bytes.) ESP_ERR_INVALID_ARG will be returned if the start & length are not a multiple of this size.
Parameters

Espressif Systems

1043

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init() · start: Address to start erasing flash. Must be sector aligned. · len: Length of region to erase. Must also be sector aligned.

Erase is performed using block (multi-sector) erases where possible (block size is specified in chip->drv>block_erase_size field, typically 65536 bytes). Remaining sectors are erased using individual sector erase commands.

Return · ESP_OK on success, · ESP_ERR_NOT_SUPPORTED if the chip is not able to perform the operation. This is indicated by WREN = 1 after the command is sent. · Other flash error code if operation failed.

esp_err_t esp_flash_get_chip_write_protect(esp_flash_t *chip, bool *write_protected) Read if the entire chip is write protected.

Note A correct result for this flag depends on the SPI flash chip model and chip_drv in use (via themchip->drvn field).
Return ESP_OK on success, or a flash error code if operation failed. Parameters
· chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init() · [out] write_protected: Pointer to boolean, set to the value of the write protect flag.

esp_err_t esp_flash_set_chip_write_protect(esp_flash_t *chip, bool write_protect) Set write protection for the SPI flash chip.

Some SPI flash chips may require a power cycle before write protect status can be cleared. Otherwise, write protection can be removed via a follow-up call to this function.

Note Correct behaviour of this function depends on the SPI flash chip model and chip_drv in use (via the mchip->drvnfield).
Parameters · chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init() · write_protect: Boolean value for the write protect flag

Return ESP_OK on success, or a flash error code if operation failed.

esp_err_t esp_flash_get_protectable_regions(const esp_flash_t *chip, esp_flash_region_t **out_regions, *out_num_regions)
Read the list of individually protectable regions of this SPI flash chip.

const uint32_t

Note Correct behaviour of this function depends on the SPI flash chip model and chip_drv in use (via the mchip->drvnfield).
Return ESP_OK on success, or a flash error code if operation failed. Parameters
· chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init() · [out] out_regions: Pointer to receive a pointer to the array of protectable regions of the
chip. · [out] out_num_regions: Pointer to an integer receiving the count of protectable regions in
the array returned in mregionsn.

esp_err_t esp_flash_get_protected_region(esp_flash_t *chip, const esp_flash_region_t *region, bool *out_protected)
Detect if a region of the SPI flash chip is protected.

Note It is possible for this result to be false and write operations to still fail, if protection is enabled for the entire chip.
Note Correct behaviour of this function depends on the SPI flash chip model and chip_drv in use (via the mchip->drvnfield).
Return ESP_OK on success, or a flash error code if operation failed. Parameters
· chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()

Espressif Systems

1044

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· region: Pointer to a struct describing a protected region. This must match one of the regions returned from esp_flash_get_protectable_regions(l).
· [out] out_protected: Pointer to a flag which is set based on the protected status for this region.
esp_err_t esp_flash_set_protected_region(esp_flash_t *chip, const esp_flash_region_t *region, bool protect)
Update the protected status for a region of the SPI flash chip.
Note It is possible for the region protection flag to be cleared and write operations to still fail, if protection is enabled for the entire chip.
Note Correct behaviour of this function depends on the SPI flash chip model and chip_drv in use (via the mchip->drvnfield).
Return ESP_OK on success, or a flash error code if operation failed. Parameters
· chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init() · region: Pointer to a struct describing a protected region. This must match one of the regions
returned from esp_flash_get_protectable_regions(l). · protect: Write protection flag to set.
esp_err_t esp_flash_read(esp_flash_t *chip, void *buffer, uint32_t address, uint32_t length) Read data from the SPI flash chip.
There are no alignment constraints on buffer, address or length.
Parameters · chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init() · buffer: Pointer to a buffer where the data will be read. To get better performance, this should be in the DRAM and word aligned. · address: Address on flash to read from. Must be less than chip->size field. · length: Length (in bytes) of data to read.
Note If on-chip flash encryption is used, this function returns raw (ie encrypted) data. Use the flash cache to transparently decrypt data.
Return · ESP_OK: success · ESP_ERR_NO_MEM: Buffer is in external PSRAM which cannot be concurrently accessed, and a temporary internal buffer could not be allocated. · or a flash error code if operation failed.
esp_err_t esp_flash_write(esp_flash_t *chip, const void *buffer, uint32_t address, uint32_t length) Write data to the SPI flash chip.
There are no alignment constraints on buffer, address or length.
Parameters · chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init() · address: Address on flash to write to. Must be previously erased (SPI NOR flash can only write bits 1->0). · buffer: Pointer to a buffer with the data to write. To get better performance, this should be in the DRAM and word aligned. · length: Length (in bytes) of data to write.
Return · ESP_OK on success, · ESP_ERR_NOT_SUPPORTED if the chip is not able to perform the operation. This is indicated by WREN = 1 after the command is sent. · Other flash error code if operation failed.
esp_err_t esp_flash_write_encrypted(esp_flash_t *chip, uint32_t address, const void *buffer, uint32_t length)
Encrypted and write data to the SPI flash chip using on-chip hardware flash encryption.
Note Both address & length must be 16 byte aligned, as this is the encryption block size

Espressif Systems

1045

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return · ESP_OK: on success · ESP_ERR_NOT_SUPPORTED: encrypted write not supported for this chip. · ESP_ERR_INVALID_ARG: Either the address, buffer or length is invalid. · or other flash error code from spi_flash_write_encrypted().
Parameters · chip: Pointer to identify flash chip. Must be NULL (the main flash chip). For other chips, encrypted write is not supported. · address: Address on flash to write to. 16 byte aligned. Must be previously erased (SPI NOR flash can only write bits 1->0). · buffer: Pointer to a buffer with the data to write. · length: Length (in bytes) of data to write. 16 byte aligned.
esp_err_t esp_flash_read_encrypted(esp_flash_t *chip, uint32_t address, void *out_buffer, uint32_t length)
Read and decrypt data from the SPI flash chip using on-chip hardware flash encryption.
Return · ESP_OK: on success · ESP_ERR_NOT_SUPPORTED: encrypted read not supported for this chip. · or other flash error code from spi_flash_read_encrypted().
Parameters · chip: Pointer to identify flash chip. Must be NULL (the main flash chip). For other chips, encrypted read is not supported. · address: Address on flash to read from. · out_buffer: Pointer to a buffer for the data to read to. · length: Length (in bytes) of data to read.
static bool esp_flash_is_quad_mode(const esp_flash_t *chip) Returns true if chip is configured for Quad I/O or Quad Fast Read.
Return true if flash works in quad mode, otherwise false Parameters
· chip: Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.

Structures struct esp_flash_region_t
Structure for describing a region of flash.

Public Members
uint32_t offset Start address of this region.
uint32_t size Size of the region.
struct esp_flash_os_functions_t OS-level integration hooks for accessing flash chips inside a running OS.
Itns in the public header because some instances should be allocated statically in the startup code. May be updated according to hardware version and new flash chip feature requirements, shouldnnt be treated as public API.
For advanced developers, you may replace some of them with your implementations at your own risk.

Public Members
esp_err_t (*start)(void *arg) Called before commencing any flash operation. Does not need to be recursive (ie is called at most once for each call to mendn).

Espressif Systems

1046

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
esp_err_t (*end)(void *arg) Called after completing any flash operation.
esp_err_t (*region_protected)(void *arg, size_t start_addr, size_t size) Called before any erase/write operations to check whether the region is limited by the OS
esp_err_t (*delay_us)(void *arg, uint32_t us) Delay for at least musnmicroseconds. Called in between mstartnand mendn.
void *(*get_temp_buffer)(void *arg, size_t reqest_size, size_t *out_size) Called for get temp buffer when buffer from application cannot be directly read into/write from.
void (*release_temp_buffer)(void *arg, void *temp_buf) Called for release temp buffer.
esp_err_t (*check_yield)(void *arg, uint32_t chip_status, uint32_t *out_request) Yield to other tasks. Called during erase operations.
Return ESP_OK means yield needs to be called (got an event to handle), while ESP_ERR_TIMEOUT means skip yield.
esp_err_t (*yield)(void *arg, uint32_t *out_status) Yield to other tasks. Called during erase operations.
int64_t (*get_system_time)(void *arg) Called for get system time.
struct esp_flash_t Structure to describe a SPI flash chip connected to the system.
Structure must be initialized before use (passed to esp_flash_init()). Itns in the public header because some instances should be allocated statically in the startup code. May be updated according to hardware version and new flash chip feature requirements, shouldnnt be treated as public API.
For advanced developers, you may replace some of them with your implementations at your own risk.
Public Members
spi_flash_host_inst_t *host Pointer to hardware-specific ohost_driverpstructure. Must be initialized before used.
const spi_flash_chip_t *chip_drv Pointer to chip-model-specific oadapterpstructure. If NULL, will be detected during initialisation.
const esp_flash_os_functions_t *os_func Pointer to os-specific hook structure. Call esp_flash_init_os_functions() to setup this field, after the host is properly initialized.
void *os_func_data Pointer to argument for os-specific hooks. Left NULL and will be initialized with os_func.
esp_flash_io_mode_t read_mode Configured SPI flash read mode. Set before esp_flash_init is called.
uint32_t size Size of SPI flash in bytes. If 0, size will be detected during initialisation.
uint32_t chip_id Detected chip id.
uint32_t busy : 1 This flag is used to verify chipns status.
uint32_t reserved_flags : 31 reserved.

Espressif Systems

1047

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Macros SPI_FLASH_YIELD_REQ_YIELD SPI_FLASH_YIELD_REQ_SUSPEND SPI_FLASH_YIELD_STA_RESUME
Type Definitions typedef struct spi_flash_chip_t spi_flash_chip_t typedef struct esp_flash_t esp_flash_t
Header File · components/hal/include/hal/spi_flash_types.h
Structures struct spi_flash_trans_t
Definition of a common transaction. Also holds the return value.
Public Members
uint8_t reserved Reserved, must be 0.
uint8_t mosi_len Output data length, in bytes.
uint8_t miso_len Input data length, in bytes.
uint8_t address_bitlen Length of address in bits, set to 0 if command does not need an address.
uint32_t address Address to perform operation on.
const uint8_t *mosi_data Output data to salve.
uint8_t *miso_data [out] Input data from slave, little endian
uint32_t flags Flags for this transaction. Set to 0 for now.
uint16_t command Command to send.
uint8_t dummy_bitlen Basic dummy bits to use.
uint32_t io_mode Flash working mode when SPI_FLASH_IGNORE_BASEIO is specified.
struct spi_flash_sus_cmd_conf Configuration structure for the flash chip suspend feature.
Public Members
uint32_t sus_mask SUS/SUS1/SUS2 bit in flash register.

Espressif Systems

1048

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

uint32_t cmd_rdsr : 8 Read flash status register(2) command.
uint32_t sus_cmd : 8 Flash suspend command.
uint32_t res_cmd : 8 Flash resume command.
uint32_t reserved : 8 Reserved, set to 0.
struct spi_flash_encryption_t Structure for flash encryption operations.

Public Members

void (*flash_encryption_enable)(void) Enable the flash encryption.

void (*flash_encryption_disable)(void) Disable the flash encryption.

void (*flash_encryption_data_prepare)(uint32_t address, const uint32_t *buffer,

Prepare flash encryption before operation.

uint32_t size)

Note address and buffer must be 8-word aligned. Parameters
· address: The destination address in flash for the write operation. · buffer: Data for programming · size: Size to program.

void (*flash_encryption_done)(void) flash data encryption operation is done.

void (*flash_encryption_destroy)(void) Destroy encrypted result

bool (*flash_encryption_check)(uint32_t address, uint32_t length) Check if is qualified to encrypt the buffer

Parameters · address: the address of written flash partition. · length: Buffer size.

struct spi_flash_host_inst_t SPI Flash Host driver instance

Public Members
const struct spi_flash_host_driver_s *driver Pointer to the implementation function table.
struct spi_flash_host_driver_s Host driver configuration and context structure.

Public Members
esp_err_t (*dev_config)(spi_flash_host_inst_t *host) Configure the device-related register before transactions. This saves some time to re-configure those registers when we send continuously

Espressif Systems

1049

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
esp_err_t (*common_command)(spi_flash_host_inst_t *host, spi_flash_trans_t *t) Send an user-defined spi transaction to the device.
esp_err_t (*read_id)(spi_flash_host_inst_t *host, uint32_t *id) Read flash ID.
void (*erase_chip)(spi_flash_host_inst_t *host) Erase whole flash chip.
void (*erase_sector)(spi_flash_host_inst_t *host, uint32_t start_address) Erase a specific sector by its start address.
void (*erase_block)(spi_flash_host_inst_t *host, uint32_t start_address) Erase a specific block by its start address.
esp_err_t (*read_status)(spi_flash_host_inst_t *host, uint8_t *out_sr) Read the status of the flash chip.
esp_err_t (*set_write_protect)(spi_flash_host_inst_t *host, bool wp) Disable write protection.
void (*program_page)(spi_flash_host_inst_t *host, const void *buffer, uint32_t address, uint32_t length)
Program a page of the flash. Check max_write_bytes for the maximum allowed writing length.
bool (*supports_direct_write)(spi_flash_host_inst_t *host, const void *p) Check whether given buffer can be directly used to write
int (*write_data_slicer)(spi_flash_host_inst_t *host, uint32_t address, uint32_t len, uint32_t *align_addr, uint32_t page_size)
Slicer for write data. The program_page should be called iteratively with the return value of this function.
Return Length that can be actually written in one program_page call Parameters
· address: Beginning flash address to write · len: Length request to write · align_addr: Output of the aligned address to write to · page_size: Physical page size of the flash chip
esp_err_t (*read)(spi_flash_host_inst_t *host, void *buffer, uint32_t address, uint32_t read_len) Read data from the flash. Check max_read_bytes for the maximum allowed reading length.
bool (*supports_direct_read)(spi_flash_host_inst_t *host, const void *p) Check whether given buffer can be directly used to read
int (*read_data_slicer)(spi_flash_host_inst_t *host, uint32_t address, uint32_t len, uint32_t *align_addr, uint32_t page_size)
Slicer for read data. The read should be called iteratively with the return value of this function.
Return Length that can be actually read in one read call Parameters
· address: Beginning flash address to read · len: Length request to read · align_addr: Output of the aligned address to read · page_size: Physical page size of the flash chip
uint32_t (*host_status)(spi_flash_host_inst_t *host) Check the host status, 0:busy, 1:idle, 2:suspended.
esp_err_t (*configure_host_io_mode)(spi_flash_host_inst_t *host, uint32_t command, uint32_t addr_bitlen, int dummy_bitlen_base, esp_flash_io_mode_t io_mode)
Configure the host to work at different read mode. Responsible to compensate the timing and set IO mode.

Espressif Systems

1050

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

void (*poll_cmd_done)(spi_flash_host_inst_t *host) Internal use, poll the HW until the last operation is done.
esp_err_t (*flush_cache)(spi_flash_host_inst_t *host, uint32_t addr, uint32_t size) For some host (SPI1), they are shared with a cache. When the data is modified, the cache needs to be flushed. Left NULL if not supported.
void (*check_suspend)(spi_flash_host_inst_t *host) Suspend check erase/program operation, reserved for ESP32-C3 and ESP32-S3 spi flash ROM IMPL.
void (*resume)(spi_flash_host_inst_t *host) Resume flash from suspend manually
void (*suspend)(spi_flash_host_inst_t *host) Set flash in suspend status manually
esp_err_t (*sus_setup)(spi_flash_host_inst_t *host, const spi_flash_sus_cmd_conf *sus_conf) Suspend feature setup for setting cmd and status register mask.
Macros SPI_FLASH_TRANS_FLAG_CMD16
Send command of 16 bits. SPI_FLASH_TRANS_FLAG_IGNORE_BASEIO
Not applying the basic io mode configuration for this transaction.
SPI_FLASH_TRANS_FLAG_BYTE_SWAP Used for DTR mode, to swap the bytes of a pair of rising/falling edge.
ESP_FLASH_SPEED_MIN Lowest speed supported by the driver, currently 5 MHz.
SPI_FLASH_CONFIG_CONF_BITS OR the io_mode with this mask, to enable the dummy output feature or replace the first several dummy bits into address to meet the requirements of conf bits. (Used in DIO/QIO/OIO mode)
SPI_FLASH_OPI_FLAG A flag for flash work in opi mode, the io mode below are opi, above are SPI/QSPI mode. DO NOT use this value in any API.
SPI_FLASH_READ_MODE_MIN Slowest io mode supported by ESP32, currently SlowRd.
Type Definitions typedef struct spi_flash_host_driver_s spi_flash_host_driver_t
Enumerations enum esp_flash_speed_t
SPI flash clock speed values, always refer to them by the enum rather than the actual value (more speed may be appended into the list).
A strategy to select the maximum allowed speed is to enumerate from the ESP_FLSH_SPEED_MAX-1 or highest frequency supported by your flash, and decrease the speed until the probing success.
Values:
ESP_FLASH_5MHZ = 0 The flash runs under 5MHz.
ESP_FLASH_10MHZ The flash runs under 10MHz.
ESP_FLASH_20MHZ The flash runs under 20MHz.

Espressif Systems

1051

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_FLASH_26MHZ The flash runs under 26MHz.
ESP_FLASH_40MHZ The flash runs under 40MHz.
ESP_FLASH_80MHZ The flash runs under 80MHz.
ESP_FLASH_120MHZ The flash runs under 120MHz, 120MHZ can only be used by main flash after timing tuning in system. Do not use this directely in any API.
ESP_FLASH_SPEED_MAX The maximum frequency supported by the host is ESP_FLASH_SPEED_MAX-1.
enum esp_flash_io_mode_t Mode used for reading from SPI flash.
Values:
SPI_FLASH_SLOWRD = 0 Data read using single I/O, some limits on speed.
SPI_FLASH_FASTRD Data read using single I/O, no limit on speed.
SPI_FLASH_DOUT Data read using dual I/O.
SPI_FLASH_DIO Both address & data transferred using dual I/O.
SPI_FLASH_QOUT Data read using quad I/O.
SPI_FLASH_QIO Both address & data transferred using quad I/O.
SPI_FLASH_OPI_STR = SPI_FLASH_OPI_FLAG Only support on OPI flash, flash read and write under STR mode.
SPI_FLASH_OPI_DTR Only support on OPI flash, flash read and write under DTR mode.
SPI_FLASH_READ_MODE_MAX The fastest io mode supported by the host is ESP_FLASH_READ_MODE_MAX-1.

API Reference - Partition Table
Header File · components/spi_flash/include/esp_partition.h

Functions esp_partition_iterator_t esp_partition_find(esp_partition_type_t type, esp_partition_subtype_t sub-
type, const char *label) Find partition based on one or more parameters.
Return iterator which can be used to enumerate all the partitions found, or NULL if no partitions were found. Iterator obtained through this function has to be released using esp_partition_iterator_release when not used any more.
Parameters · type: Partition type, one of esp_partition_type_t values or an 8-bit unsigned integer. To find all partitions, no matter the type, use ESP_PARTITION_TYPE_ANY, and set subtype argument to ESP_PARTITION_SUBTYPE_ANY.

Espressif Systems

1052

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· subtype: Partition subtype, one of esp_partition_subtype_t values or an 8-bit unsigned integer.

To find all partitions of given type, use ESP_PARTITION_SUBTYPE_ANY.

· label: (optional) Partition label. Set this value if looking for partition with a specific name. Pass

NULL otherwise.

const esp_partition_t *esp_partition_find_first(esp_partition_type_t

type,

esp_partition_subtype_t subtype, const

char *label) Find first partition based on one or more parameters.

Return pointer to esp_partition_t structure, or NULL if no partition is found. This pointer is valid for the lifetime of the application.
Parameters · type: Partition type, one of esp_partition_type_t values or an 8-bit unsigned integer. To find all partitions, no matter the type, use ESP_PARTITION_TYPE_ANY, and set subtype argument to ESP_PARTITION_SUBTYPE_ANY. · subtype: Partition subtype, one of esp_partition_subtype_t values or an 8-bit unsigned integer To find all partitions of given type, use ESP_PARTITION_SUBTYPE_ANY. · label: (optional) Partition label. Set this value if looking for partition with a specific name. Pass NULL otherwise.

const esp_partition_t *esp_partition_get(esp_partition_iterator_t iterator) Get esp_partition_t structure for given partition.

Return pointer to esp_partition_t structure. This pointer is valid for the lifetime of the application. Parameters
· iterator: Iterator obtained using esp_partition_find. Must be non-NULL.

esp_partition_iterator_t esp_partition_next(esp_partition_iterator_t iterator) Move partition iterator to the next partition found.

Any copies of the iterator will be invalid after this call.

Return NULL if no partition was found, valid esp_partition_iterator_t otherwise. Parameters
· iterator: Iterator obtained using esp_partition_find. Must be non-NULL.

void esp_partition_iterator_release(esp_partition_iterator_t iterator) Release partition iterator.

Parameters · iterator: Iterator obtained using esp_partition_find. The iterator is allowed to be NULL, so it is not necessary to check its value before calling this function.

const esp_partition_t *esp_partition_verify(const esp_partition_t *partition) Verify partition data.

Given a pointer to partition data, verify this partition exists in the partition table (all fields match.)

This function is also useful to take partition data which may be in a RAM buffer and convert it to a pointer to the permanent partition data stored in flash.

Pointers returned from this function can be compared directly to the address of any pointer returned from esp_partition_get(), as a test for equality.

Return · If partition not found, returns NULL. · If found, returns a pointer to the esp_partition_t structure in flash. This pointer is always valid for the lifetime of the application.
Parameters · partition: Pointer to partition data to verify. Must be non-NULL. All fields of this structure must match the partition table entry in flash for this function to return a successful match.

esp_err_t esp_partition_read(const esp_partition_t *partition, size_t src_offset, void *dst, size_t size)
Read data from the partition.

Espressif Systems

1053

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Partitions marked with an encryption flag will automatically be be read and decrypted via a cache mapping.

Return ESP_OK, if data was read successfully; ESP_ERR_INVALID_ARG, if src_offset exceeds partition size; ESP_ERR_INVALID_SIZE, if read would go out of bounds of the partition; or one of error codes from lower-level flash driver.
Parameters · partition: Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL. · dst: Pointer to the buffer where data should be stored. Pointer must be non-NULL and buffer must be at least msizenbytes long. · src_offset: Address of the data to be read, relative to the beginning of the partition. · size: Size of data to be read, in bytes.

esp_err_t esp_partition_write(const esp_partition_t *partition, size_t dst_offset, const void *src,

Write data to the partition.

size_t size)

Before writing data to flash, corresponding region of flash needs to be erased. This can be done using esp_partition_erase_range function.

Partitions marked with an encryption flag will automatically be written via the spi_flash_write_encrypted() function. If writing to an encrypted partition, all write offsets and lengths must be multiples of 16 bytes. See the spi_flash_write_encrypted() function for more details. Unencrypted partitions do not have this restriction.

Note Prior to writing to flash memory, make sure it has been erased with esp_partition_erase_range call. Return ESP_OK, if data was written successfully; ESP_ERR_INVALID_ARG, if dst_offset exceeds parti-
tion size; ESP_ERR_INVALID_SIZE, if write would go out of bounds of the partition; or one of error codes from lower-level flash driver. Parameters
· partition: Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL.
· dst_offset: Address where the data should be written, relative to the beginning of the partition. · src: Pointer to the source buffer. Pointer must be non-NULL and buffer must be at least msizen
bytes long. · size: Size of data to be written, in bytes.

esp_err_t esp_partition_read_raw(const esp_partition_t *partition, size_t src_offset, void *dst, size_t size)
Read data from the partition without any transformation/decryption.

Note This function is essentially the same as esp_partition_read() above. It just never decrypts data but returns it as is.
Return ESP_OK, if data was read successfully; ESP_ERR_INVALID_ARG, if src_offset exceeds partition size; ESP_ERR_INVALID_SIZE, if read would go out of bounds of the partition; or one of error codes from lower-level flash driver.
Parameters · partition: Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL. · dst: Pointer to the buffer where data should be stored. Pointer must be non-NULL and buffer must be at least msizenbytes long. · src_offset: Address of the data to be read, relative to the beginning of the partition. · size: Size of data to be read, in bytes.

esp_err_t esp_partition_write_raw(const esp_partition_t *partition, size_t dst_offset, const void *src, size_t size)
Write data to the partition without any transformation/encryption.

Before writing data to flash, corresponding region of flash needs to be erased. This can be done using esp_partition_erase_range function.

Note This function is essentially the same as esp_partition_write() above. It just never encrypts data but writes it as is.

Note Prior to writing to flash memory, make sure it has been erased with esp_partition_erase_range call.

Espressif Systems

1054

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Return ESP_OK, if data was written successfully; ESP_ERR_INVALID_ARG, if dst_offset exceeds partition size; ESP_ERR_INVALID_SIZE, if write would go out of bounds of the partition; or one of the error codes from lower-level flash driver.
Parameters · partition: Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL. · dst_offset: Address where the data should be written, relative to the beginning of the partition. · src: Pointer to the source buffer. Pointer must be non-NULL and buffer must be at least msizen bytes long. · size: Size of data to be written, in bytes.
esp_err_t esp_partition_erase_range(const esp_partition_t *partition, size_t offset, size_t size) Erase part of the partition.
Return ESP_OK, if the range was erased successfully; ESP_ERR_INVALID_ARG, if iterator or dst are NULL; ESP_ERR_INVALID_SIZE, if erase would go out of bounds of the partition; or one of error codes from lower-level flash driver.
Parameters · partition: Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL. · offset: Offset from the beginning of partition where erase operation should start. Must be aligned to 4 kilobytes. · size: Size of the range which should be erased, in bytes. Must be divisible by 4 kilobytes.
esp_err_t esp_partition_mmap(const esp_partition_t *partition, size_t offset, size_t size, spi_flash_mmap_memory_t memory, const void **out_ptr, spi_flash_mmap_handle_t *out_handle)
Configure MMU to map partition into data memory.
Unlike spi_flash_mmap function, which requires a 64kB aligned base address, this function doesnnt impose such a requirement. If offset results in a flash address which is not aligned to 64kB boundary, address will be rounded to the lower 64kB boundary, so that mapped region includes requested range. Pointer returned via out_ptr argument will be adjusted to point to the requested offset (not necessarily to the beginning of mmap-ed region).
To release mapped memory, pass handle returned via out_handle argument to spi_flash_munmap function.
Return ESP_OK, if successful Parameters
· partition: Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL.
· offset: Offset from the beginning of partition where mapping should start. · size: Size of the area to be mapped. · memory: Memory space where the region should be mapped · out_ptr: Output, pointer to the mapped memory region · out_handle: Output, handle which should be used for spi_flash_munmap call
esp_err_t esp_partition_get_sha256(const esp_partition_t *partition, uint8_t *sha_256) Get SHA-256 digest for required partition.
For apps with SHA-256 appended to the app image, the result is the appended SHA-256 value for the app image content. The hash is verified before returning, if app content is invalid then the function returns ESP_ERR_IMAGE_INVALID. For apps without SHA-256 appended to the image, the result is the SHA256 of all bytes in the app image. For other partition types, the result is the SHA-256 of the entire partition.
Return · ESP_OK: In case of successful operation. · ESP_ERR_INVALID_ARG: The size was 0 or the sha_256 was NULL. · ESP_ERR_NO_MEM: Cannot allocate memory for sha256 operation. · ESP_ERR_IMAGE_INVALID: App partition doesnnt contain a valid app image. · ESP_FAIL: An allocation error occurred.
Parameters

Espressif Systems

1055

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· [in] partition: Pointer to info for partition containing app or data. (fields: address, size and type, are required to be filled).
· [out] sha_256: Returned SHA-256 digest for a given partition.

bool esp_partition_check_identity(const esp_partition_t *partition_1, const esp_partition_t *partition_2)
Check for the identity of two partitions by SHA-256 digest.

Return · True: In case of the two firmware is equal. · False: Otherwise
Parameters · [in] partition_1: Pointer to info for partition 1 containing app or data. (fields: address, size and type, are required to be filled). · [in] partition_2: Pointer to info for partition 2 containing app or data. (fields: address, size and type, are required to be filled).

esp_err_t esp_partition_register_external(esp_flash_t *flash_chip, size_t offset, size_t

size, const char *label, esp_partition_type_t

type, esp_partition_subtype_t subtype, const

Register a partition on an external flash chip.

esp_partition_t **out_partition)

This API allows designating certain areas of external flash chips (identified by the esp_flash_t structure) as partitions. This allows using them with components which access SPI flash through the esp_partition API.

Return · ESP_OK on success · ESP_ERR_NOT_SUPPORTED if CONFIG_CONFIG_SPI_FLASH_USE_LEGACY_IMPL is enabled · ESP_ERR_NO_MEM if memory allocation has failed · ESP_ERR_INVALID_ARG if the new partition overlaps another partition on the same flash chip · ESP_ERR_INVALID_SIZE if the partition doesnnt fit into the flash chip size
Parameters · flash_chip: Pointer to the structure identifying the flash chip · offset: Address in bytes, where the partition starts · size: Size of the partition in bytes · label: Partition name · type: One of the partition types (ESP_PARTITION_TYPE_*), or an integer. Note that applications can not be booted from external flash chips, so using ESP_PARTITION_TYPE_APP is not supported. · subtype: One of the partition subtypes (ESP_PARTITION_SUBTYPE_*), or an integer. · [out] out_partition: Output, if non-NULL, receives the pointer to the resulting esp_partition_t structure

esp_err_t esp_partition_deregister_external(const esp_partition_t *partition) Deregister the partition previously registered using esp_partition_register_external.

Return · ESP_OK on success · ESP_ERR_NOT_FOUND if the partition pointer is not found · ESP_ERR_INVALID_ARG if the partition comes from the partition table · ESP_ERR_INVALID_ARG if the partition was not registered using esp_partition_register_external function.
Parameters · partition: pointer to the partition structure obtained from esp_partition_register_external,

Structures struct esp_partition_t
partition information structure
This is not the format in flash, that format is esp_partition_info_t.

Espressif Systems

1056

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
However, this is the format used by this API.
Public Members
esp_flash_t *flash_chip SPI flash chip on which the partition resides
esp_partition_type_t type partition type (app/data)
esp_partition_subtype_t subtype partition subtype
uint32_t address starting address of the partition in flash
uint32_t size size of the partition, in bytes
char label[17] partition label, zero-terminated ASCII string
bool encrypted flag is set to true if partition is encrypted
Macros ESP_PARTITION_SUBTYPE_OTA(i)
Convenience macro to get esp_partition_subtype_t value for the i-th OTA partition.
Type Definitions typedef struct esp_partition_iterator_opaque_ *esp_partition_iterator_t
Opaque partition iterator type.
Enumerations enum esp_partition_type_t
Partition type. Note Partition types with integer value 0x00-0x3F are reserved for partition types defined by ESP-IDF. Any
other integer value 0x40-0xFE can be used by individual applications, without restriction. Values: ESP_PARTITION_TYPE_APP = 0x00
Application partition type. ESP_PARTITION_TYPE_DATA = 0x01
Data partition type. ESP_PARTITION_TYPE_ANY = 0xff
Used to search for partitions with any type. enum esp_partition_subtype_t
Partition subtype. Application-defined partition types (0x40-0xFE) can set any numeric subtype value. Note These ESP-IDF-defined partition subtypes apply to partitions of type ESP_PARTITION_TYPE_APP
and ESP_PARTITION_TYPE_DATA. Values: ESP_PARTITION_SUBTYPE_APP_FACTORY = 0x00
Factory application partition.

Espressif Systems

1057

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_PARTITION_SUBTYPE_APP_OTA_MIN = 0x10 Base for OTA partition subtypes.
ESP_PARTITION_SUBTYPE_APP_OTA_0 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 0 OTA partition 0.
ESP_PARTITION_SUBTYPE_APP_OTA_1 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 1 OTA partition 1.
ESP_PARTITION_SUBTYPE_APP_OTA_2 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 2 OTA partition 2.
ESP_PARTITION_SUBTYPE_APP_OTA_3 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 3 OTA partition 3.
ESP_PARTITION_SUBTYPE_APP_OTA_4 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 4 OTA partition 4.
ESP_PARTITION_SUBTYPE_APP_OTA_5 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 5 OTA partition 5.
ESP_PARTITION_SUBTYPE_APP_OTA_6 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 6 OTA partition 6.
ESP_PARTITION_SUBTYPE_APP_OTA_7 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 7 OTA partition 7.
ESP_PARTITION_SUBTYPE_APP_OTA_8 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 8 OTA partition 8.
ESP_PARTITION_SUBTYPE_APP_OTA_9 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 9 OTA partition 9.
ESP_PARTITION_SUBTYPE_APP_OTA_10 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 10 OTA partition 10.
ESP_PARTITION_SUBTYPE_APP_OTA_11 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 11 OTA partition 11.
ESP_PARTITION_SUBTYPE_APP_OTA_12 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 12 OTA partition 12.
ESP_PARTITION_SUBTYPE_APP_OTA_13 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 13 OTA partition 13.
ESP_PARTITION_SUBTYPE_APP_OTA_14 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 14 OTA partition 14.
ESP_PARTITION_SUBTYPE_APP_OTA_15 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 15 OTA partition 15.
ESP_PARTITION_SUBTYPE_APP_OTA_MAX = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 16 Max subtype of OTA partition.
ESP_PARTITION_SUBTYPE_APP_TEST = 0x20 Test application partition.
ESP_PARTITION_SUBTYPE_DATA_OTA = 0x00 OTA selection partition.
ESP_PARTITION_SUBTYPE_DATA_PHY = 0x01 PHY init data partition.
ESP_PARTITION_SUBTYPE_DATA_NVS = 0x02 NVS partition.
ESP_PARTITION_SUBTYPE_DATA_COREDUMP = 0x03 COREDUMP partition.

Espressif Systems

1058

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_PARTITION_SUBTYPE_DATA_NVS_KEYS = 0x04 Partition for NVS keys.
ESP_PARTITION_SUBTYPE_DATA_EFUSE_EM = 0x05 Partition for emulate eFuse bits.
ESP_PARTITION_SUBTYPE_DATA_UNDEFINED = 0x06 Undefined (or unspecified) data partition.
ESP_PARTITION_SUBTYPE_DATA_ESPHTTPD = 0x80 ESPHTTPD partition.
ESP_PARTITION_SUBTYPE_DATA_FAT = 0x81 FAT partition.
ESP_PARTITION_SUBTYPE_DATA_SPIFFS = 0x82 SPIFFS partition.
ESP_PARTITION_SUBTYPE_ANY = 0xff Used to search for partitions with any subtype.
API Reference - Flash Encrypt
Header File
· components/bootloader_support/include/esp_flash_encrypt.h
Functions static bool esp_flash_encryption_enabled(void)
Is flash encryption currently enabled in hardware?
Flash encryption is enabled if the FLASH_CRYPT_CNT efuse has an odd number of bits set.
Return true if flash encryption is enabled. esp_err_t esp_flash_encrypt_check_and_update(void)
esp_err_t esp_flash_encrypt_region(uint32_t src_addr, size_t data_length) Encrypt-in-place a block of flash sectors.
Note This function resets RTC_WDT between operations with sectors. Return ESP_OK if all operations succeeded, ESP_ERR_FLASH_OP_FAIL if SPI flash fails,
ESP_ERR_FLASH_OP_TIMEOUT if flash times out. Parameters
· src_addr: Source offset in flash. Should be multiple of 4096 bytes. · data_length: Length of data to encrypt in bytes. Will be rounded up to next multiple of 4096
bytes.
void esp_flash_write_protect_crypt_cnt(void) Write protect FLASH_CRYPT_CNT.
Intended to be called as a part of boot process if flash encryption is enabled but secure boot is not used. This should protect against serial re-flashing of an unauthorised code in absence of secure boot.
Note On ESP32 V3 only, write protecting FLASH_CRYPT_CNT will also prevent disabling UART Download Mode. If both are wanted, call esp_efuse_disable_rom_download_mode() before calling this function.
esp_flash_enc_mode_t esp_get_flash_encryption_mode(void) Return the flash encryption mode.
The API is called during boot process but can also be called by application to check the current flash encryption mode of ESP32
Return

Espressif Systems

1059

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

void esp_flash_encryption_init_checks(void) Check the flash encryption mode during startup. Verifies the flash encryption config during startup: Note This function is called automatically during app startup, it doesnnt need to be called from the app. · Correct any insecure flash encryption settings if hardware Secure Boot is enabled. · Log warnings if the efuse config doesnnt match the project config in any way
esp_err_t esp_flash_encryption_enable_secure_features(void) Set all secure eFuse features related to flash encryption. Return · ESP_OK - Successfully
void esp_flash_encryption_set_release_mode(void) Switches Flash Encryption from oDevelopmentpto oReleasep. If already in oReleasepmode, the function will do nothing. If flash encryption efuse is not enabled yet then abort. It burns: · pdisable encrypt in dl modep · set FLASH_CRYPT_CNT efuse to max
Enumerations enum esp_flash_enc_mode_t
Values: ESP_FLASH_ENC_MODE_DISABLED ESP_FLASH_ENC_MODE_DEVELOPMENT ESP_FLASH_ENC_MODE_RELEASE
2.6.7 SPIFFS Filesystem
Overview
SPIFFS is a file system intended for SPI NOR flash devices on embedded targets. It supports wear levelling, file system consistency checks, and more.
Notes
· Currently, SPIFFS does not support directories, it produces a flat structure. If SPIFFS is mounted under /spiffs, then creating a file with the path /spiffs/tmp/myfile.txt will create a file called /tmp/ myfile.txt in SPIFFS, instead of myfile.txt in the directory /spiffs/tmp.
· It is not a real-time stack. One write operation might take much longer than another. · For now, it does not detect or handle bad blocks. · SPIFFS is able to reliably utilize only around 75% of assigned partition space. · When the filesystem is running out of space, the garbage collector is trying to find free space by scanning the
filesystem multiple times, which can take up to several seconds per write function call, depending on required space. This is caused by the SPIFFS design and the issue has been reported multiple times (e.g. here) and in the official SPIFFS github repository. The issue can be partially mitigated by the SPIFFS configuration. · Deleting a file does not always remove the whole file, which leaves unusable sections throughout the filesystem.
Tools
spiffsgen.py spiffsgen.py is a write-only Python SPIFFS implementation used to create filesystem images from the contents of a host folder. To use spiffsgen.py, open Terminal and run:

Espressif Systems

1060

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
python spiffsgen.py <image_size> <base_dir> <output_file>
The required arguments are as follows: · image_size: size of the partition onto which the created SPIFFS image will be flashed. · base_dir: directory for which the SPIFFS image needs to be created. · output_file: SPIFFS image output file.
There are also other arguments that control image generation. Documentation on these arguments can be found in the toolns help:
python spiffsgen.py --help
These optional arguments correspond to a possible SPIFFS build configuration. To generate the right image, please make sure that you use the same arguments/configuration as were used to build SPIFFS. As a guide, the help output indicates the SPIFFS build configuration to which the argument corresponds. In cases when these arguments are not specified, the default values shown in the help output will be used. When the image is created, it can be flashed using esptool.py or parttool.py. Aside from invoking the spiffsgen.py standalone by manually running it from the command line or a script, it is also possible to invoke spiffsgen.py directly from the build system by calling spiffs_create_partition_image:
spiffs_create_partition_image(<partition> <base_dir> [FLASH_IN_PROJECT] [DEPENDS dep dep dep...])
This is more convenient as the build configuration is automatically passed to the tool, ensuring that the generated image is valid for that build. An example of this is while the image_size is required for the standalone invocation, only the partition name is required when using spiffs_create_partition_image the image size is automatically obtained from the projectns partition table. spiffs_create_partition_image must be called from one of the component CMakeLists.txt files. Optionally, users can opt to have the image automatically flashed together with the app binaries, partition tables, etc. on idf.py flash by specifying FLASH_IN_PROJECT. For example:
spiffs_create_partition_image(my_spiffs_partition my_folder FLASH_IN_PROJECT)
If FLASH_IN_PROJECT/SPIFFS_IMAGE_FLASH_IN_PROJECT is not specified, the image will still be generated, but you will have to flash it manually using esptool.py, parttool.py, or a custom build system target. There are cases where the contents of the base directory itself is generated at build time. Users can use DEPENDS/SPIFFS_IMAGE_DEPENDS to specify targets that should be executed before generating the image:
add_custom_target(dep COMMAND ...)
spiffs_create_partition_image(my_spiffs_partition my_folder DEPENDS dep)
For an example, see storage/spiffsgen.
mkspiffs Another tool for creating SPIFFS partition images is mkspiffs. Similar to spiffsgen.py, it can be used to create an image from a given folder and then flash that image using esptool.py For that, you need to obtain the following parameters:
· Block Size: 4096 (standard for SPI Flash) · Page Size: 256 (standard for SPI Flash) · Image Size: Size of the partition in bytes (can be obtained from a partition table) · Partition Offset: Starting address of the partition (can be obtained from a partition table) To pack a folder into a 1-Megabyte image, run:

Espressif Systems

1061

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

mkspiffs -c [src_folder] -b 4096 -p 256 -s 0x100000 spiffs.bin
To flash the image onto ESP32-S3 at offset 0x110000, run:
python esptool.py --chip esp32s3 --port [port] --baud [baud] write_flash -z 0x110000 spiffs.bin
Notes on which SPIFFS tool to use The two tools presented above offer very similar functionality. However, there are reasons to prefer one over the other, depending on the use case. Use spiffsgen.py in the following cases:
1. If you want to simply generate a SPIFFS image during the build. spiffsgen.py makes it very convenient by providing functions/commands from the build system itself.
2. If the host has no C/C++ compiler available, because spiffsgen.py does not require compilation. Use mkspiffs in the following cases:
1. If you need to unpack SPIFFS images in addition to image generation. For now, it is not possible with spiffsgen.py.
2. If you have an environment where a Python interpreter is not available, but a host compiler is available. Otherwise, a pre-compiled mkspiffs binary can do the job. However, there is no build system integration for mkspiffs and the user has to do the corresponding work: compiling mkspiffs during build (if a precompiled binary is not used), creating build rules/targets for the output files, passing proper parameters to the tool, etc.
See also
· Partition Table documentation
Application Example
An example of using SPIFFS is provided in the storage/spiffs directory. This example initializes and mounts a SPIFFS partition, then writes and reads data from it using POSIX and C library APIs. See the README.md file in the example directory for more information.
High-level API Reference
Header File · components/spiffs/include/esp_spiffs.h
Functions esp_err_t esp_vfs_spiffs_register(const esp_vfs_spiffs_conf_t *conf)
Register and mount SPIFFS to VFS with given path prefix. Return
· ESP_OK if success · ESP_ERR_NO_MEM if objects could not be allocated · ESP_ERR_INVALID_STATE if already mounted or partition is encrypted · ESP_ERR_NOT_FOUND if partition for SPIFFS was not found · ESP_FAIL if mount or format fails Parameters · conf: Pointer to esp_vfs_spiffs_conf_t configuration structure esp_err_t esp_vfs_spiffs_unregister(const char *partition_label) Unregister and unmount SPIFFS from VFS

Espressif Systems

1062

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Return · ESP_OK if successful · ESP_ERR_INVALID_STATE already unregistered
Parameters · partition_label: Same label as passed to esp_vfs_spiffs_register.
bool esp_spiffs_mounted(const char *partition_label) Check if SPIFFS is mounted
Return · true if mounted · false if not mounted
Parameters · partition_label: Optional, label of the partition to check. If not specified, first partition with subtype=spiffs is used.
esp_err_t esp_spiffs_format(const char *partition_label) Format the SPIFFS partition
Return · ESP_OK if successful · ESP_FAIL on error
Parameters · partition_label: Same label as passed to esp_vfs_spiffs_register.
esp_err_t esp_spiffs_info(const char *partition_label, size_t *total_bytes, size_t *used_bytes) Get information for SPIFFS
Return · ESP_OK if success · ESP_ERR_INVALID_STATE if not mounted
Parameters · partition_label: Same label as passed to esp_vfs_spiffs_register · [out] total_bytes: Size of the file system · [out] used_bytes: Current used bytes in the file system
Structures struct esp_vfs_spiffs_conf_t
Configuration structure for esp_vfs_spiffs_register.
Public Members
const char *base_path File path prefix associated with the filesystem.
const char *partition_label Optional, label of SPIFFS partition to use. If set to NULL, first partition with subtype=spiffs will be used.
size_t max_files Maximum files that could be open at the same time.
bool format_if_mount_failed If true, it will format the file system if it fails to mount.
2.6.8 Virtual filesystem component

Espressif Systems

1063

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Overview
Virtual filesystem (VFS) component provides a unified interface for drivers which can perform operations on file-like objects. These can be real filesystems (FAT, SPIFFS, etc.) or device drivers which provide a file-like interface.
This component allows C library functions, such as fopen and fprintf, to work with FS drivers. At a high level, each FS driver is associated with some path prefix. When one of C library functions needs to open a file, the VFS component searches for the FS driver associated with the file path and forwards the call to that driver. VFS also forwards read, write, and other calls for the given file to the same FS driver.
For example, one can register a FAT filesystem driver with the /fat prefix and call fopen("/fat/file.txt", "w"). The VFS component will then call the function open of the FAT driver and pass the argument /file.txt to it together with appropriate mode flags. All subsequent calls to C library functions for the returned FILE* stream will also be forwarded to the FAT driver.

FS registration

To register an FS driver, an application needs to define an instance of the esp_vfs_t structure and populate it with function pointers to FS APIs:
esp_vfs_t myfs = { .flags = ESP_VFS_FLAG_DEFAULT, .write = &myfs_write, .open = &myfs_open, .fstat = &myfs_fstat, .close = &myfs_close, .read = &myfs_read,
};
ESP_ERROR_CHECK(esp_vfs_register("/data", &myfs, NULL));

Depending on the way how the FS driver declares its API functions, either read, write, etc., or read_p, write_p, etc., should be used.
Case 1: API functions are declared without an extra context pointer (the FS driver is a singleton):
ssize_t myfs_write(int fd, const void * data, size_t size);
// In definition of esp_vfs_t: .flags = ESP_VFS_FLAG_DEFAULT, .write = &myfs_write,
// ... other members initialized

// When registering FS, context pointer (third argument) is NULL: ESP_ERROR_CHECK(esp_vfs_register("/data", &myfs, NULL));

Case 2: API functions are declared with an extra context pointer (the FS driver supports multiple instances):
ssize_t myfs_write(myfs_t* fs, int fd, const void * data, size_t size);
// In definition of esp_vfs_t: .flags = ESP_VFS_FLAG_CONTEXT_PTR, .write_p = &myfs_write,
// ... other members initialized

// When registering FS, pass the FS context pointer into the third argument // (hypothetical myfs_mount function is used for illustrative purposes) myfs_t* myfs_inst1 = myfs_mount(partition1->offset, partition1->size); ESP_ERROR_CHECK(esp_vfs_register("/data1", &myfs, myfs_inst1));

// Can register another instance:

(continues on next page)

Espressif Systems

1064

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)
myfs_t* myfs_inst2 = myfs_mount(partition2->offset, partition2->size); ESP_ERROR_CHECK(esp_vfs_register("/data2", &myfs, myfs_inst2));

Synchronous input/output multiplexing Synchronous input/output multiplexing by select() is supported in the VFS component. The implementation works in the following way.
1. select() is called with file descriptors which could belong to various VFS drivers. 2. The file descriptors are divided into groups each belonging to one VFS driver. 3. The file descriptors belonging to non-socket VFS drivers are handed over to the given VFS drivers by
start_select(), described later on this page. This function represents the driver-specific implementation of select() for the given driver. This should be a non-blocking call which means the function should immediately return after setting up the environment for checking events related to the given file descriptors. 4. The file descriptors belonging to the socket VFS driver are handed over to the socket driver by socket_select() described later on this page. This is a blocking call which means that it will return only if there is an event related to socket file descriptors or a non-socket driver signals socket_select() to exit. 5. Results are collected from each VFS driver and all drivers are stopped by de-initialization of the environment for checking events. 6. The select() call ends and returns the appropriate results.
Non-socket VFS drivers If you want to use select() with a file descriptor belonging to a non-socket VFS driver, then you need to register the driver with functions start_select() and end_select() similarly to the following example:
// In definition of esp_vfs_t: .start_select = &uart_start_select, .end_select = &uart_end_select,
// ... other members initialized
start_select() is called for setting up the environment for detection of read/write/error conditions on file descriptors belonging to the given VFS driver.
end_select() is called to stop/deinitialize/free the environment which was setup by start_select().
Note: end_select() might be called without a previous start_select() call in some rare circumstances. end_select() should fail gracefully if this is the case (i.e., should not crash but return an error instead).
Please refer to the reference implementation for the UART peripheral in vfs/vfs_uart.c and most particularly to the functions esp_vfs_dev_uart_register(), uart_start_select(), and uart_end_select() for more information.
Please check the following examples that demonstrate the use of select() with VFS file descriptors:
· peripherals/uart/uart_select · system/select
Socket VFS drivers A socket VFS driver is using its own internal implementation of select() and non-socket VFS drivers notify it upon read/write/error conditions.
A socket VFS driver needs to be registered with the following functions defined:
// In definition of esp_vfs_t: .socket_select = &lwip_select, .get_socket_select_semaphore = &lwip_get_socket_select_semaphore, .stop_socket_select = &lwip_stop_socket_select, .stop_socket_select_isr = &lwip_stop_socket_select_isr,
// ... other members initialized

Espressif Systems

1065

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

socket_select() is the internal implementation of select() for the socket driver. It works only with file descriptors belonging to the socket VFS.
get_socket_select_semaphore() returns the signalization object (semaphore) which will be used in nonsocket drivers to stop the waiting in socket_select().
stop_socket_select() call is used to stop the waiting in socket_select() by passing the object returned by get_socket_select_semaphore().
stop_socket_select_isr() has the same functionality as stop_socket_select() but it can be used from ISR.
Please see lwip/port/esp32/vfs_lwip.c for a reference socket driver implementation using LWIP.

Note:

If you use select() for socket file descriptors only then you can disable the CON-

FIG_VFS_SUPPORT_SELECT option to reduce the code size and improve performance. You should not change

the socket driver during an active select() call or you might experience some undefined behavior.

Paths
Each registered FS has a path prefix associated with it. This prefix can be considered as a omount pointpof this partition.
In case when mount points are nested, the mount point with the longest matching path prefix is used when opening the file. For instance, suppose that the following filesystems are registered in VFS:
· FS 1 on /data · FS 2 on /data/static
Then:
· FS 1 will be used when opening a file called /data/log.txt · FS 2 will be used when opening a file called /data/static/index.html · Even if /index.html" does not exist in FS 2, FS 1 will not be searched for /static/index.html.
As a general rule, mount point names must start with the path separator (/) and must contain at least one character after path separator. However, an empty mount point name is also supported and might be used in cases when an application needs to provide aofallbackpfilesystem or to override VFS functionality altogether. Such filesystem will be used if no prefix matches the path given.
VFS does not handle dots (.) in path names in any special way. VFS does not treat .. as a reference to the parent directory. In the above example, using a path /data/static/../log.txt will not result in a call to FS 1 to open /log.txt. Specific FS drivers (such as FATFS) might handle dots in file names differently.
When opening files, the FS driver receives only relative paths to files. For example:
1. The myfs driver is registered with /data as a path prefix. 2. The application calls fopen("/data/config.json", ...). 3. The VFS component calls myfs_open("/config.json", ...). 4. The myfs driver opens the /config.json file.
VFS does not impose any limit on total file path length, but it does limit the FS path prefix to ESP_VFS_PATH_MAX characters. Individual FS drivers may have their own filename length limitations.
File descriptors
File descriptors are small positive integers from 0 to FD_SETSIZE - 1, where FD_SETSIZE is defined in newlibn s sys/types.h. The largest file descriptors (configured by CONFIG_LWIP_MAX_SOCKETS) are reserved for sockets. The VFS component contains a lookup-table called s_fd_table for mapping global file descriptors to VFS driver indexes registered in the s_vfs array.

Espressif Systems

1066

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Standard IO streams (stdin, stdout, stderr)
If the menuconfig option UART for console output is not set to None, then stdin, stdout, and stderr are configured to read from, and write to, a UART. It is possible to use UART0 or UART1 for standard IO. By default, UART0 is used with 115200 baud rate; TX pin is GPIO1; RX pin is GPIO3. These parameters can be changed in menuconfig.
Writing to stdout or stderr will send characters to the UART transmit FIFO. Reading from stdin will retrieve characters from the UART receive FIFO.
By default, VFS uses simple functions for reading from and writing to UART. Writes busy-wait until all data is put into UART FIFO, and reads are non-blocking, returning only the data present in the FIFO. Due to this non-blocking read behavior, higher level C library calls, such as fscanf("%d\n", &var);, might not have desired results.
Applications which use the UART driver can instruct VFS to use the driverns interrupt driven, blocking read and write functions instead. This can be done using a call to the esp_vfs_dev_uart_use_driver function. It is also possible to revert to the basic non-blocking functions using a call to esp_vfs_dev_uart_use_nonblocking.
VFS also provides an optional newline conversion feature for input and output. Internally, most applications send and receive lines terminated by the LF (mnnn n) character. Different terminal programs may require different line termination, such as CR or CRLF. Applications can configure this separately for input and output either via menuconfig, or by calls to the functions esp_vfs_dev_uart_port_set_rx_line_endings and esp_vfs_dev_uart_port_set_tx_line_endings.

Standard streams and FreeRTOS tasks FILE objects for stdin, stdout, and stderr are shared between all FreeRTOS tasks, but the pointers to these objects are stored in per-task struct _reent.
The following code is transferred to fprintf(__getreent()->_stderr, "42\n"); by the preprocessor:
fprintf(stderr, "42\n");
The __getreent() function returns a per-task pointer to struct _reent in newlib libc. This structure is allocated on the TCB of each task. When a task is initialized, _stdin, _stdout, and _stderr members of struct _reent are set to the values of _stdin, _stdout, and _stderr of _GLOBAL_REENT (i.e., the structure which is used before FreeRTOS is started).
Such a design has the following consequences:
· It is possible to set stdin, stdout, and stderr for any given task without affecting other tasks, e.g., by doing stdin = fopen("/dev/uart/1", "r").
· Closing default stdin, stdout, or stderr using fclose will close the FILE stream object, which will affect all other tasks.
· To change the default stdin, stdout, stderr streams for new tasks, modify _GLOBAL_REENT>_stdin (_stdout, _stderr) before creating the task.

Event fds
eventfd() call is a powerful tool to notify a select() based loop of custom events. The eventfd() implementation in ESP-IDF is generally the same as described in man(2) eventfd except for:
· esp_vfs_eventfd_register() has to be called before calling eventfd() · Options EFD_CLOEXEC, EFD_NONBLOCK and EFD_SEMAPHORE are not supported in flags. · Option EFD_SUPPORT_ISR has been added in flags. This flag is required to read and write the eventfd in
an interrupt handler.
Note that creating an eventfd with EFD_SUPPORT_ISR will cause interrupts to be temporarily disabled when reading, writing the file and during the beginning and the ending of the select() when this file is set.

API Reference Header File Espressif Systems

1067

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· components/vfs/include/esp_vfs.h
Functions ssize_t esp_vfs_write(struct _reent *r, int fd, const void *data, size_t size)
These functions are to be used in newlib syscall table. They will be called by newlib when it needs to use any of the syscalls. off_t esp_vfs_lseek(struct _reent *r, int fd, off_t size, int mode)
ssize_t esp_vfs_read(struct _reent *r, int fd, void *dst, size_t size)
int esp_vfs_open(struct _reent *r, const char *path, int flags, int mode)
int esp_vfs_close(struct _reent *r, int fd)
int esp_vfs_fstat(struct _reent *r, int fd, struct stat *st)
int esp_vfs_stat(struct _reent *r, const char *path, struct stat *st)
int esp_vfs_link(struct _reent *r, const char *n1, const char *n2)
int esp_vfs_unlink(struct _reent *r, const char *path)
int esp_vfs_rename(struct _reent *r, const char *src, const char *dst)
int esp_vfs_utime(const char *path, const struct utimbuf *times)
esp_err_t esp_vfs_register(const char *base_path, const esp_vfs_t *vfs, void *ctx) Register a virtual filesystem for given path prefix.
Return ESP_OK if successful, ESP_ERR_NO_MEM if too many VFSes are registered. Parameters
· base_path: file path prefix associated with the filesystem. Must be a zero-terminated C string, may be empty. If not empty, must be up to ESP_VFS_PATH_MAX characters long, and at least 2 characters long. Name must start with ao/pand must not end witho/p. For example,o/datapor
o/dev/spipare valid. These VFSes would then be called to handle file paths such aso/data/myfile.txtp or o/dev/spi/0p. In the special case of an empty base_path, a ofallbackpVFS is registered. Such VFS will handle paths which are not matched by any other registered VFS.
· vfs: Pointer to esp_vfs_t, a structure which maps syscalls to the filesystem driver functions. VFS component doesnnt assume ownership of this pointer.
· ctx: If vfs->flags has ESP_VFS_FLAG_CONTEXT_PTR set, a pointer which should be passed to VFS functions. Otherwise, NULL.
esp_err_t esp_vfs_register_fd_range(const esp_vfs_t *vfs, void *ctx, int min_fd, int max_fd) Special case function for registering a VFS that uses a method other than open() to open new file descriptors from the interval <min_fd; max_fd).
This is a special-purpose function intended for registering LWIP sockets to VFS.
Return ESP_OK if successful, ESP_ERR_NO_MEM if too many VFSes are registered, ESP_ERR_INVALID_ARG if the file descriptor boundaries are incorrect.
Parameters · vfs: Pointer to esp_vfs_t. Meaning is the same as for esp_vfs_register(). · ctx: Pointer to context structure. Meaning is the same as for esp_vfs_register(). · min_fd: The smallest file descriptor this VFS will use. · max_fd: Upper boundary for file descriptors this VFS will use (the biggest file descriptor plus one).
esp_err_t esp_vfs_register_with_id(const esp_vfs_t *vfs, void *ctx, esp_vfs_id_t *vfs_id) Special case function for registering a VFS that uses a method other than open() to open new file descriptors. In comparison with esp_vfs_register_fd_range, this function doesnnt pre-registers an interval of file descriptors. File descriptors can be registered later, by using esp_vfs_register_fd.
Return ESP_OK if successful, ESP_ERR_NO_MEM if too many VFSes are registered, ESP_ERR_INVALID_ARG if the file descriptor boundaries are incorrect.
Parameters · vfs: Pointer to esp_vfs_t. Meaning is the same as for esp_vfs_register().

Espressif Systems

1068

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· ctx: Pointer to context structure. Meaning is the same as for esp_vfs_register(). · vfs_id: Here will be written the VFS ID which can be passed to esp_vfs_register_fd for registering
file descriptors.
esp_err_t esp_vfs_unregister(const char *base_path) Unregister a virtual filesystem for given path prefix
Return ESP_OK if successful, ESP_ERR_INVALID_STATE if VFS for given prefix hasnnt been registered Parameters
· base_path: file prefix previously used in esp_vfs_register call
esp_err_t esp_vfs_unregister_with_id(esp_vfs_id_t vfs_id) Unregister a virtual filesystem with the given index
Return ESP_OK if successful, ESP_ERR_INVALID_STATE if VFS for the given index hasnnt been registered
Parameters · vfs_id: The VFS ID returned by esp_vfs_register_with_id
esp_err_t esp_vfs_register_fd(esp_vfs_id_t vfs_id, int *fd) Special function for registering another file descriptor for a VFS registered by esp_vfs_register_with_id.
Return ESP_OK if the registration is successful, ESP_ERR_NO_MEM if too many file descriptors are registered, ESP_ERR_INVALID_ARG if the arguments are incorrect.
Parameters · vfs_id: VFS identificator returned by esp_vfs_register_with_id. · fd: The registered file descriptor will be written to this address.
esp_err_t esp_vfs_register_fd_with_local_fd(esp_vfs_id_t vfs_id, int local_fd, bool permanent, int *fd)
Special function for registering another file descriptor with given local_fd for a VFS registered by esp_vfs_register_with_id.
Return ESP_OK if the registration is successful, ESP_ERR_NO_MEM if too many file descriptors are registered, ESP_ERR_INVALID_ARG if the arguments are incorrect.
Parameters · vfs_id: VFS identificator returned by esp_vfs_register_with_id. · local_fd: The fd in the local vfs. Passing -1 will set the local fd as the (*fd) value. · permanent: Whether the fd should be treated as permannet (not removed after close()) · fd: The registered file descriptor will be written to this address.
esp_err_t esp_vfs_unregister_fd(esp_vfs_id_t vfs_id, int fd) Special function for unregistering a file descriptor belonging to a VFS registered by esp_vfs_register_with_id.
Return ESP_OK if the registration is successful, ESP_ERR_INVALID_ARG if the arguments are incorrect. Parameters
· vfs_id: VFS identificator returned by esp_vfs_register_with_id. · fd: File descriptor which should be unregistered.
int esp_vfs_select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *errorfds, struct timeval *timeout)
Synchronous I/O multiplexing which implements the functionality of POSIX select() for VFS.
Return The number of descriptors set in the descriptor sets, or -1 when an error (specified by errno) have occurred.
Parameters · nfds: Specifies the range of descriptors which should be checked. The first nfds descriptors will be checked in each set. · readfds: If not NULL, then points to a descriptor set that on input specifies which descriptors should be checked for being ready to read, and on output indicates which descriptors are ready to read. · writefds: If not NULL, then points to a descriptor set that on input specifies which descriptors should be checked for being ready to write, and on output indicates which descriptors are ready to write.

Espressif Systems

1069

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· errorfds: If not NULL, then points to a descriptor set that on input specifies which descriptors should be checked for error conditions, and on output indicates which descriptors have error conditions.
· timeout: If not NULL, then points to timeval structure which specifies the time period after which the functions should time-out and return. If it is NULL, then the function will not time-out. Note that the timeout period is rounded up to the system tick and incremented by one.
void esp_vfs_select_triggered(esp_vfs_select_sem_t sem) Notification from a VFS driver about a read/write/error condition.
This function is called when the VFS driver detects a read/write/error condition as it was requested by the previous call to start_select.
Parameters · sem: semaphore structure which was passed to the driver by the start_select call
void esp_vfs_select_triggered_isr(esp_vfs_select_sem_t sem, BaseType_t *woken) Notification from a VFS driver about a read/write/error condition (ISR version)
This function is called when the VFS driver detects a read/write/error condition as it was requested by the previous call to start_select.
Parameters · sem: semaphore structure which was passed to the driver by the start_select call · woken: is set to pdTRUE if the function wakes up a task with higher priority
ssize_t esp_vfs_pread(int fd, void *dst, size_t size, off_t offset) Implements the VFS layer of POSIX pread()
Return A positive return value indicates the number of bytes read. -1 is return on failure and errno is set accordingly.
Parameters · fd: File descriptor used for read · dst: Pointer to the buffer where the output will be written · size: Number of bytes to be read · offset: Starting offset of the read
ssize_t esp_vfs_pwrite(int fd, const void *src, size_t size, off_t offset) Implements the VFS layer of POSIX pwrite()
Return A positive return value indicates the number of bytes written. -1 is return on failure and errno is set accordingly.
Parameters · fd: File descriptor used for write · src: Pointer to the buffer from where the output will be read · size: Number of bytes to write · offset: Starting offset of the write

Structures struct esp_vfs_select_sem_t
VFS semaphore type for select()

Public Members
bool is_sem_local type of osempis SemaphoreHandle_t when true, defined by socket driver otherwise
void *sem semaphore instance
struct esp_vfs_t VFS definition structure.
This structure should be filled with pointers to corresponding FS driver functions.

Espressif Systems

1070

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
VFS component will translate all FDs so that the filesystem implementation sees them starting at zero. The caller sees a global FD which is prefixed with an pre-filesystem-implementation.
Some FS implementations expect some state (e.g. pointer to some structure) to be passed in as a first argument. For these implementations, populate the members of this structure which have _p suffix, set flags member to ESP_VFS_FLAG_CONTEXT_PTR and provide the context pointer to esp_vfs_register function. If the implementation doesnnt use this extra argument, populate the members without _p suffix and set flags member to ESP_VFS_FLAG_DEFAULT.
If the FS driver doesnnt provide some of the functions, set corresponding members to NULL.
Public Members
int flags ESP_VFS_FLAG_CONTEXT_PTR or ESP_VFS_FLAG_DEFAULT
ssize_t (*write_p)(void *p, int fd, const void *data, size_t size) Write with context pointer
ssize_t (*write)(int fd, const void *data, size_t size) Write without context pointer
off_t (*lseek_p)(void *p, int fd, off_t size, int mode) Seek with context pointer
off_t (*lseek)(int fd, off_t size, int mode) Seek without context pointer
ssize_t (*read_p)(void *ctx, int fd, void *dst, size_t size) Read with context pointer
ssize_t (*read)(int fd, void *dst, size_t size) Read without context pointer
ssize_t (*pread_p)(void *ctx, int fd, void *dst, size_t size, off_t offset) pread with context pointer
ssize_t (*pread)(int fd, void *dst, size_t size, off_t offset) pread without context pointer
ssize_t (*pwrite_p)(void *ctx, int fd, const void *src, size_t size, off_t offset) pwrite with context pointer
ssize_t (*pwrite)(int fd, const void *src, size_t size, off_t offset) pwrite without context pointer
int (*open_p)(void *ctx, const char *path, int flags, int mode) open with context pointer
int (*open)(const char *path, int flags, int mode) open without context pointer
int (*close_p)(void *ctx, int fd) close with context pointer
int (*close)(int fd) close without context pointer
int (*fstat_p)(void *ctx, int fd, struct stat *st) fstat with context pointer
int (*fstat)(int fd, struct stat *st) fstat without context pointer
int (*stat_p)(void *ctx, const char *path, struct stat *st) stat with context pointer

Espressif Systems

1071

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
int (*stat)(const char *path, struct stat *st) stat without context pointer
int (*link_p)(void *ctx, const char *n1, const char *n2) link with context pointer
int (*link)(const char *n1, const char *n2) link without context pointer
int (*unlink_p)(void *ctx, const char *path) unlink with context pointer
int (*unlink)(const char *path) unlink without context pointer
int (*rename_p)(void *ctx, const char *src, const char *dst) rename with context pointer
int (*rename)(const char *src, const char *dst) rename without context pointer
DIR *(*opendir_p)(void *ctx, const char *name) opendir with context pointer
DIR *(*opendir)(const char *name) opendir without context pointer
struct dirent *(*readdir_p)(void *ctx, DIR *pdir) readdir with context pointer
struct dirent *(*readdir)(DIR *pdir) readdir without context pointer
int (*readdir_r_p)(void *ctx, DIR *pdir, struct dirent *entry, struct dirent **out_dirent) readdir_r with context pointer
int (*readdir_r)(DIR *pdir, struct dirent *entry, struct dirent **out_dirent) readdir_r without context pointer
long (*telldir_p)(void *ctx, DIR *pdir) telldir with context pointer
long (*telldir)(DIR *pdir) telldir without context pointer
void (*seekdir_p)(void *ctx, DIR *pdir, long offset) seekdir with context pointer
void (*seekdir)(DIR *pdir, long offset) seekdir without context pointer
int (*closedir_p)(void *ctx, DIR *pdir) closedir with context pointer
int (*closedir)(DIR *pdir) closedir without context pointer
int (*mkdir_p)(void *ctx, const char *name, mode_t mode) mkdir with context pointer
int (*mkdir)(const char *name, mode_t mode) mkdir without context pointer
int (*rmdir_p)(void *ctx, const char *name) rmdir with context pointer
int (*rmdir)(const char *name) rmdir without context pointer

Espressif Systems

1072

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
int (*fcntl_p)(void *ctx, int fd, int cmd, int arg) fcntl with context pointer
int (*fcntl)(int fd, int cmd, int arg) fcntl without context pointer
int (*ioctl_p)(void *ctx, int fd, int cmd, va_list args) ioctl with context pointer
int (*ioctl)(int fd, int cmd, va_list args) ioctl without context pointer
int (*fsync_p)(void *ctx, int fd) fsync with context pointer
int (*fsync)(int fd) fsync without context pointer
int (*access_p)(void *ctx, const char *path, int amode) access with context pointer
int (*access)(const char *path, int amode) access without context pointer
int (*truncate_p)(void *ctx, const char *path, off_t length) truncate with context pointer
int (*truncate)(const char *path, off_t length) truncate without context pointer
int (*utime_p)(void *ctx, const char *path, const struct utimbuf *times) utime with context pointer
int (*utime)(const char *path, const struct utimbuf *times) utime without context pointer
int (*tcsetattr_p)(void *ctx, int fd, int optional_actions, const struct termios *p) tcsetattr with context pointer
int (*tcsetattr)(int fd, int optional_actions, const struct termios *p) tcsetattr without context pointer
int (*tcgetattr_p)(void *ctx, int fd, struct termios *p) tcgetattr with context pointer
int (*tcgetattr)(int fd, struct termios *p) tcgetattr without context pointer
int (*tcdrain_p)(void *ctx, int fd) tcdrain with context pointer
int (*tcdrain)(int fd) tcdrain without context pointer
int (*tcflush_p)(void *ctx, int fd, int select) tcflush with context pointer
int (*tcflush)(int fd, int select) tcflush without context pointer
int (*tcflow_p)(void *ctx, int fd, int action) tcflow with context pointer
int (*tcflow)(int fd, int action) tcflow without context pointer
pid_t (*tcgetsid_p)(void *ctx, int fd) tcgetsid with context pointer

Espressif Systems

1073

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

pid_t (*tcgetsid)(int fd) tcgetsid without context pointer
int (*tcsendbreak_p)(void *ctx, int fd, int duration) tcsendbreak with context pointer
int (*tcsendbreak)(int fd, int duration) tcsendbreak without context pointer
esp_err_t (*start_select)(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, esp_vfs_select_sem_t sem, void **end_select_args)
start_select is called for setting up synchronous I/O multiplexing of the desired file descriptors in the given VFS
int (*socket_select)(int nfds, fd_set *readfds, fd_set *writefds, fd_set *errorfds, struct timeval *timeout)
socket select function for socket FDs with the functionality of POSIX select(); this should be set only for the socket VFS
void (*stop_socket_select)(void *sem) called by VFS to interrupt the socket_select call when select is activated from a non-socket VFS driver; set only for the socket driver
void (*stop_socket_select_isr)(void *sem, BaseType_t *woken) stop_socket_select which can be called from ISR; set only for the socket driver
void *(*get_socket_select_semaphore)(void) end_select is called to stop the I/O multiplexing and deinitialize the environment created by start_select for the given VFS
esp_err_t (*end_select)(void *end_select_args) get_socket_select_semaphore returns semaphore allocated in the socket driver; set only for the socket driver
Macros MAX_FDS
Maximum number of (global) file descriptors. ESP_VFS_PATH_MAX
Maximum length of path prefix (not including zero terminator)
ESP_VFS_FLAG_DEFAULT Default value of flags member in esp_vfs_t structure.
ESP_VFS_FLAG_CONTEXT_PTR Flag which indicates that FS needs extra context pointer in syscalls.
Type Definitions typedef int esp_vfs_id_t
Header File
· components/vfs/include/esp_vfs_dev.h
Functions void esp_vfs_dev_uart_register(void)
add /dev/uart virtual filesystem driver
This function is called from startup code to enable serial output void esp_vfs_dev_uart_set_rx_line_endings(esp_line_endings_t mode)
Set the line endings expected to be received on UART.
This specifies the conversion between line endings received on UART and newlines (mn, LF) passed into stdin:

Espressif Systems

1074

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· ESP_LINE_ENDINGS_CRLF: convert CRLF to LF · ESP_LINE_ENDINGS_CR: convert CR to LF · ESP_LINE_ENDINGS_LF: no modification
Note this function is not thread safe w.r.t. reading from UART Parameters
· mode: line endings expected on UART
void esp_vfs_dev_uart_set_tx_line_endings(esp_line_endings_t mode) Set the line endings to sent to UART.
This specifies the conversion between newlines (mn, LF) on stdout and line endings sent over UART:
· ESP_LINE_ENDINGS_CRLF: convert LF to CRLF · ESP_LINE_ENDINGS_CR: convert LF to CR · ESP_LINE_ENDINGS_LF: no modification
Note this function is not thread safe w.r.t. writing to UART Parameters
· mode: line endings to send to UART
int esp_vfs_dev_uart_port_set_rx_line_endings(int uart_num, esp_line_endings_t mode) Set the line endings expected to be received on specified UART.
This specifies the conversion between line endings received on UART and newlines (mn, LF) passed into stdin:
· ESP_LINE_ENDINGS_CRLF: convert CRLF to LF · ESP_LINE_ENDINGS_CR: convert CR to LF · ESP_LINE_ENDINGS_LF: no modification
Note this function is not thread safe w.r.t. reading from UART Return 0 if successed, or -1 when an error (specified by errno) have occurred. Parameters
· uart_num: the UART number · mode: line endings to send to UART
int esp_vfs_dev_uart_port_set_tx_line_endings(int uart_num, esp_line_endings_t mode) Set the line endings to sent to specified UART.
This specifies the conversion between newlines (mn, LF) on stdout and line endings sent over UART:
· ESP_LINE_ENDINGS_CRLF: convert LF to CRLF · ESP_LINE_ENDINGS_CR: convert LF to CR · ESP_LINE_ENDINGS_LF: no modification
Note this function is not thread safe w.r.t. writing to UART Return 0 if successed, or -1 when an error (specified by errno) have occurred. Parameters
· uart_num: the UART number · mode: line endings to send to UART
void esp_vfs_dev_uart_use_nonblocking(int uart_num) set VFS to use simple functions for reading and writing UART Read is non-blocking, write is busy waiting until TX FIFO has enough space. These functions are used by default.
Parameters · uart_num: UART peripheral number
void esp_vfs_dev_uart_use_driver(int uart_num) set VFS to use UART driver for reading and writing
Note application must configure UART driver before calling these functions With these functions, read and write are blocking and interrupt-driven.
Parameters · uart_num: UART peripheral number

Espressif Systems

1075

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

void esp_vfs_usb_serial_jtag_use_driver(void) set VFS to use USB-SERIAL-JTAG driver for reading and writing
Note application must configure USB-SERIAL-JTAG driver before calling these functions With these functions, read and write are blocking and interrupt-driven.
void esp_vfs_usb_serial_jtag_use_nonblocking(void) set VFS to use simple functions for reading and writing UART Read is non-blocking, write is busy waiting until TX FIFO has enough space. These functions are used by default.

Header File · components/vfs/include/esp_vfs_eventfd.h

Functions esp_err_t esp_vfs_eventfd_register(const esp_vfs_eventfd_config_t *config)
Registers the event vfs.
Return ESP_OK if successful, ESP_ERR_NO_MEM if too many VFSes are registered. esp_err_t esp_vfs_eventfd_unregister(void)
Unregisters the event vfs.
Return ESP_OK if successful, ESP_ERR_INVALID_STATE if VFS for given prefix hasnnt been registered
int eventfd(unsigned int initval, int flags)

Structures struct esp_vfs_eventfd_config_t
Eventfd vfs initialization settings.

Public Members
size_t max_fds The maxinum number of eventfds supported

Macros EFD_SUPPORT_ISR ESP_VFS_EVENTD_CONFIG_DEFAULT()

2.6.9 Wear Levelling API
Overview
Most of flash memory and especially SPI flash that is used in ESP32-S3 has a sector-based organization and also has a limited number of erase/modification cycles per memory sector. The wear levelling component helps to distribute wear and tear among sectors more evenly without requiring any attention from the user.
The wear levelling component provides API functions related to reading, writing, erasing, and memory mapping of data in external SPI flash through the partition component. The component also has higher-level API functions which work with the FAT filesystem defined in FAT filesystem.
The wear levelling component, together with the FAT FS component, uses FAT FS sectors of 4096 bytes, which is a standard size for flash memory. With this size, the component shows the best performance but needs additional memory in RAM.
To save internal memory, the component has two additional modes which both use sectors of 512 bytes:
· Performance mode. Erase sector operation data is stored in RAM, the sector is erased, and then data is copied back to flash memory. However, if a device is powered off for any reason, all 4096 bytes of data is lost.

Espressif Systems

1076

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· Safety mode. The data is first saved to flash memory, and after the sector is erased, the data is saved back. If a device is powered off, the data can be recovered as soon as the device boots up.
The default settings are as follows: - Sector size is 512 bytes - Performance mode
You can change the settings through the configuration menu.
The wear levelling component does not cache data in RAM. The write and erase functions modify flash directly, and flash contents are consistent when the function returns.

Wear Levelling access API functions
This is the set of API functions for working with data in flash:
· wl_mount - initializes the wear levelling module and mounts the specified partition · wl_unmount - unmounts the partition and deinitializes the wear levelling module · wl_erase_range - erases a range of addresses in flash · wl_write - writes data to a partition · wl_read - reads data from a partition · wl_size - returns the size of available memory in bytes · wl_sector_size - returns the size of one sector
As a rule, try to avoid using raw wear levelling functions and use filesystem-specific functions instead.

Memory Size
The memory size is calculated in the wear levelling module based on partition parameters. The module uses some sectors of flash for internal data.

See also
· FAT Filesystem · Partition Table documentation

Application Example
An example which combines the wear levelling driver with the FATFS library is provided in the storage/wear_levelling directory. This example initializes the wear levelling driver, mounts FATFS partition, as well as writes and reads data from it using POSIX and C library APIs. See the storage/wear_levelling/README.md file for more information.

High level API Reference
Header Files · fatfs/vfs/esp_vfs_fat.h

Functions esp_err_t esp_vfs_fat_spiflash_mount(const char *base_path, const char *partition_label,
const esp_vfs_fat_mount_config_t *mount_config, wl_handle_t *wl_handle) Convenience function to initialize FAT filesystem in SPI flash and register it in VFS.
This is an all-in-one function which does the following:
· finds the partition with defined partition_label. Partition label should be configured in the partition table. · initializes flash wear levelling library on top of the given partition · mounts FAT partition using FATFS library on top of flash wear levelling library · registers FATFS library with VFS, with prefix given by base_prefix variable

Espressif Systems

1077

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

This function is intended to make example code more compact.
Return · ESP_OK on success · ESP_ERR_NOT_FOUND if the partition table does not contain FATFS partition with given label · ESP_ERR_INVALID_STATE if esp_vfs_fat_spiflash_mount was already called · ESP_ERR_NO_MEM if memory can not be allocated · ESP_FAIL if partition can not be mounted · other error codes from wear levelling library, SPI flash driver, or FATFS drivers
Parameters · base_path: path where FATFS partition should be mounted (e.g. o/spiflashp) · partition_label: label of the partition which should be used · mount_config: pointer to structure with extra parameters for mounting FATFS · [out] wl_handle: wear levelling driver handle
struct esp_vfs_fat_mount_config_t Configuration arguments for esp_vfs_fat_sdmmc_mount and esp_vfs_fat_spiflash_mount functions.
Public Members
bool format_if_mount_failed If FAT partition can not be mounted, and this parameter is true, create partition table and format the filesystem.
int max_files Max number of open files.
size_t allocation_unit_size If format_if_mount_failed is set, and mount fails, format the card with given allocation unit size. Must be a power of 2, between sector size and 128 * sector size. For SD cards, sector size is always 512 bytes. For wear_levelling, sector size is determined by CONFIG_WL_SECTOR_SIZE option.
Using larger allocation unit size will result in higher read/write performance and higher overhead when storing small files.
Setting this field to 0 will result in allocation unit set to the sector size.
esp_err_t esp_vfs_fat_spiflash_unmount(const char *base_path, wl_handle_t wl_handle) Unmount FAT filesystem and release resources acquired using esp_vfs_fat_spiflash_mount.
Return · ESP_OK on success · ESP_ERR_INVALID_STATE if esp_vfs_fat_spiflash_mount hasnnt been called
Parameters · base_path: path where partition should be registered (e.g. o/spiflashp) · wl_handle: wear levelling driver handle returned by esp_vfs_fat_spiflash_mount
Mid level API Reference
Header File
· components/wear_levelling/include/wear_levelling.h
Functions esp_err_t wl_mount(const esp_partition_t *partition, wl_handle_t *out_handle)
Mount WL for defined partition.
Return · ESP_OK, if the allocation was successfully; · ESP_ERR_INVALID_ARG, if WL allocation was unsuccessful; · ESP_ERR_NO_MEM, if there was no memory to allocate WL components;

Espressif Systems

1078

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Parameters · partition: that will be used for access · out_handle: handle of the WL instance
esp_err_t wl_unmount(wl_handle_t handle) Unmount WL for defined partition.
Return · ESP_OK, if the operation completed successfully; · or one of error codes from lower-level flash driver.
Parameters · handle: WL partition handle
esp_err_t wl_erase_range(wl_handle_t handle, size_t start_addr, size_t size) Erase part of the WL storage.
Return · ESP_OK, if the range was erased successfully; · ESP_ERR_INVALID_ARG, if iterator or dst are NULL; · ESP_ERR_INVALID_SIZE, if erase would go out of bounds of the partition; · or one of error codes from lower-level flash driver.
Parameters · handle: WL handle that are related to the partition · start_addr: Address where erase operation should start. Must be aligned to the result of function wl_sector_size(l). · size: Size of the range which should be erased, in bytes. Must be divisible by result of function wl_sector_size(l)..
esp_err_t wl_write(wl_handle_t handle, size_t dest_addr, const void *src, size_t size) Write data to the WL storage.
Before writing data to flash, corresponding region of flash needs to be erased. This can be done using wl_erase_range function.
Note Prior to writing to WL storage, make sure it has been erased with wl_erase_range call. Return
· ESP_OK, if data was written successfully; · ESP_ERR_INVALID_ARG, if dst_offset exceeds partition size; · ESP_ERR_INVALID_SIZE, if write would go out of bounds of the partition; · or one of error codes from lower-level flash driver. Parameters · handle: WL handle that are related to the partition · dest_addr: Address where the data should be written, relative to the beginning of the partition. · src: Pointer to the source buffer. Pointer must be non-NULL and buffer must be at least msizen
bytes long. · size: Size of data to be written, in bytes.
esp_err_t wl_read(wl_handle_t handle, size_t src_addr, void *dest, size_t size) Read data from the WL storage.
Return · ESP_OK, if data was read successfully; · ESP_ERR_INVALID_ARG, if src_offset exceeds partition size; · ESP_ERR_INVALID_SIZE, if read would go out of bounds of the partition; · or one of error codes from lower-level flash driver.
Parameters · handle: WL module instance that was initialized before · dest: Pointer to the buffer where data should be stored. Pointer must be non-NULL and buffer must be at least msizenbytes long. · src_addr: Address of the data to be read, relative to the beginning of the partition. · size: Size of data to be read, in bytes.
size_t wl_size(wl_handle_t handle) Get size of the WL storage.

Espressif Systems

1079

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return usable size, in bytes Parameters
· handle: WL module handle that was initialized before
size_t wl_sector_size(wl_handle_t handle) Get sector size of the WL instance.
Return sector size, in bytes Parameters
· handle: WL module handle that was initialized before
Macros WL_INVALID_HANDLE
Type Definitions typedef int32_t wl_handle_t
wear levelling handle Code examples for this API section are provided in the storage directory of ESP-IDF examples.

2.7 System API
2.7.1 App Image Format
An application image consists of the following structures:
1. The esp_image_header_t structure describes the mode of SPI flash and the count of memory segments. 2. The esp_image_segment_header_t structure describes each segment, its length, and its location in
ESP32-S3ns memory, followed by the data with a length of data_len. The data offset for each segment in the image is calculated in the following way:
· offset for 0 Segment = sizeof(esp_image_header_t) + sizeof(esp_image_segment_header_t). · offset for 1 Segment = offset for 0 Segment + length of 0 Segment +
sizeof(esp_image_segment_header_t). · offset for 2 Segment = offset for 1 Segment + length of 1 Segment +
sizeof(esp_image_segment_header_t). ·l
The count of each segment is defined in the segment_count field that is stored in esp_image_header_t. The count cannot be more than ESP_IMAGE_MAX_SEGMENTS.
To get the list of your image segments, please run the following command:
esptool.py --chip esp32s3 image_info build/app.bin
esptool.py v2.3.1 Image version: 1 Entry point: 40080ea4 13 segments Segment 1: len 0x13ce0 load 0x3f400020 file_offs 0x00000018 SOC_DROM Segment 2: len 0x00000 load 0x3ff80000 file_offs 0x00013d00 SOC_RTC_DRAM Segment 3: len 0x00000 load 0x3ff80000 file_offs 0x00013d08 SOC_RTC_DRAM Segment 4: len 0x028e0 load 0x3ffb0000 file_offs 0x00013d10 DRAM Segment 5: len 0x00000 load 0x3ffb28e0 file_offs 0x000165f8 DRAM Segment 6: len 0x00400 load 0x40080000 file_offs 0x00016600 SOC_IRAM Segment 7: len 0x09600 load 0x40080400 file_offs 0x00016a08 SOC_IRAM Segment 8: len 0x62e4c load 0x400d0018 file_offs 0x00020010 SOC_IROM Segment 9: len 0x06cec load 0x40089a00 file_offs 0x00082e64 SOC_IROM Segment 10: len 0x00000 load 0x400c0000 file_offs 0x00089b58 SOC_RTC_IRAM
(continues on next page)

Espressif Systems

1080

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)
Segment 11: len 0x00004 load 0x50000000 file_offs 0x00089b60 SOC_RTC_DATA Segment 12: len 0x00000 load 0x50000004 file_offs 0x00089b6c SOC_RTC_DATA Segment 13: len 0x00000 load 0x50000004 file_offs 0x00089b74 SOC_RTC_DATA Checksum: e8 (valid)Validation Hash: 407089ca0eae2bbf83b4120979d3354b1c938a49cb7a0c997f240474ef2ec76b (valid)
You can also see the information on segments in the IDF logs while your application is booting:
I (443) esp_image: segment 0: paddr=0x00020020 vaddr=0x3f400020 size=0x13ce0 ( 81120) map I (489) esp_image: segment 1: paddr=0x00033d08 vaddr=0x3ff80000 size=0x00000 ( 0) load I (530) esp_image: segment 2: paddr=0x00033d10 vaddr=0x3ff80000 size=0x00000 ( 0) load I (571) esp_image: segment 3: paddr=0x00033d18 vaddr=0x3ffb0000 size=0x028e0 ( 10464) load I (612) esp_image: segment 4: paddr=0x00036600 vaddr=0x3ffb28e0 size=0x00000 ( 0) load I (654) esp_image: segment 5: paddr=0x00036608 vaddr=0x40080000 size=0x00400 ( 1024) load I (695) esp_image: segment 6: paddr=0x00036a10 vaddr=0x40080400 size=0x09600 ( 38400) load I (737) esp_image: segment 7: paddr=0x00040018 vaddr=0x400d0018 size=0x62e4c (405068) map I (847) esp_image: segment 8: paddr=0x000a2e6c vaddr=0x40089a00 size=0x06cec ( 27884) load I (888) esp_image: segment 9: paddr=0x000a9b60 vaddr=0x400c0000 size=0x00000 ( 0) load I (929) esp_image: segment 10: paddr=0x000a9b68 vaddr=0x50000000 size=0x00004 ( 4) load I (971) esp_image: segment 11: paddr=0x000a9b74 vaddr=0x50000004 size=0x00000 ( 0) load I (1012) esp_image: segment 12: paddr=0x000a9b7c vaddr=0x50000004 size=0x00000 ( 0) load
For more details on the type of memory segments and their address ranges, see ESP32-S3 Technical Reference Manual > System and Memory > Internal Memory [PDF].
3. The image has a single checksum byte after the last segment. This byte is written on a sixteen byte padded boundary, so the application image might need padding.
4. If the hash_appended field from esp_image_header_t is set then a SHA256 checksum will be appended. The value of SHA256 is calculated on the range from the first byte and up to this field. The length of this field is 32 bytes.
5. If the options CONFIG_SECURE_SIGNED_APPS_SCHEME is set to ECDSA then the application image will have additional 68 bytes for an ECDSA signature, which includes:
· version word (4 bytes), · signature data (64 bytes).
Application Description
The DROM segment starts with the esp_app_desc_t structure which carries specific fields describing the application:
· magic_word - the magic word for the esp_app_desc structure. · secure_version - see Anti-rollback. · version - see App version. * · project_name is filled from PROJECT_NAME. * · time and date - compile time and date. · idf_ver - version of ESP-IDF. *

Espressif Systems

1081

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· app_elf_sha256 - contains sha256 for the elf application file.
* - The maximum length is 32 characters, including null-termination character. For example, if the length of PROJECT_NAME exceeds 32 characters, the excess characters will be disregarded.
This structure is useful for identification of images uploaded OTA because it has a fixed offset = sizeof(esp_image_header_t) + sizeof(esp_image_segment_header_t). As soon as a device receives the first fragment containing this structure, it has all the information to determine whether the update should be continued or not.

Adding a Custom Structure to an Application
Users also have the opportunity to have similar structure with a fixed offset relative to the beginning of the image. The following pattern can be used to add a custom structure to your image:
const __attribute__((section(".rodata_custom_desc"))) esp_custom_app_desc_t custom_ app_desc = { ... }
Offset for custom structure is sizeof(esp_image_header_t) + sizeof(esp_image_segment_header_t) + sizeof(esp_app_desc_t). To guarantee that the custom structure is located in the image even if it is not used, you need to add target_link_libraries(${COMPONENT_TARGET} "-u custom_app_desc") into CMakeLists. txt.

API Reference
Header File · components/bootloader_support/include/esp_app_format.h

Structures struct esp_image_header_t
Main header of binary image.

Public Members
uint8_t magic Magic word ESP_IMAGE_HEADER_MAGIC
uint8_t segment_count Count of memory segments
uint8_t spi_mode flash read mode (esp_image_spi_mode_t as uint8_t)
uint8_t spi_speed : 4 flash frequency (esp_image_spi_freq_t as uint8_t)
uint8_t spi_size : 4 flash chip size (esp_image_flash_size_t as uint8_t)
uint32_t entry_addr Entry address
uint8_t wp_pin WP pin when SPI pins set via efuse (read by ROM bootloader, the IDF bootloader uses software to configure the WP pin and sets this field to 0xEE=disabled)
uint8_t spi_pin_drv[3] Drive settings for the SPI flash pins (read by ROM bootloader)

Espressif Systems

1082

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
esp_chip_id_t chip_id Chip identification number
uint8_t min_chip_rev Minimum chip revision supported by image
uint8_t reserved[8] Reserved bytes in additional header space, currently unused
uint8_t hash_appended If 1, a SHA256 digest osimple hashp(of the entire image) is appended after the checksum. Included in image length. This digest is separate to secure boot and only used for detecting corruption. For secure boot signed images, the signature is appended after this (and the simple hash is included in the signed data).
struct esp_image_segment_header_t Header of binary image segment.
Public Members
uint32_t load_addr Address of segment
uint32_t data_len Length of data
struct esp_app_desc_t Description about application.
Public Members
uint32_t magic_word Magic word ESP_APP_DESC_MAGIC_WORD
uint32_t secure_version Secure version
uint32_t reserv1[2] reserv1
char version[32] Application version
char project_name[32] Project name
char time[16] Compile time
char date[16] Compile date
char idf_ver[32] Version IDF
uint8_t app_elf_sha256[32] sha256 of elf file
uint32_t reserv2[20] reserv2

Espressif Systems

1083

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Macros ESP_IMAGE_HEADER_MAGIC
The magic word for the esp_image_header_t structure. ESP_IMAGE_MAX_SEGMENTS
Max count of segments in the image.
ESP_APP_DESC_MAGIC_WORD The magic word for the esp_app_desc structure that is in DROM.
Enumerations enum esp_chip_id_t
ESP chip ID.
Values:
ESP_CHIP_ID_ESP32 = 0x0000 chip ID: ESP32
ESP_CHIP_ID_ESP32S2 = 0x0002 chip ID: ESP32-S2
ESP_CHIP_ID_ESP32C3 = 0x0005 chip ID: ESP32-C3
ESP_CHIP_ID_ESP32S3 = 0x0009 chip ID: ESP32-S3
ESP_CHIP_ID_ESP32C2 = 0x000C chip ID: ESP32-C2
ESP_CHIP_ID_INVALID = 0xFFFF Invalid chip ID (we defined it to make sure the esp_chip_id_t is 2 bytes size)
enum esp_image_spi_mode_t SPI flash mode, used in esp_image_header_t.
Values:
ESP_IMAGE_SPI_MODE_QIO SPI mode QIO
ESP_IMAGE_SPI_MODE_QOUT SPI mode QOUT
ESP_IMAGE_SPI_MODE_DIO SPI mode DIO
ESP_IMAGE_SPI_MODE_DOUT SPI mode DOUT
ESP_IMAGE_SPI_MODE_FAST_READ SPI mode FAST_READ
ESP_IMAGE_SPI_MODE_SLOW_READ SPI mode SLOW_READ
enum esp_image_spi_freq_t SPI flash clock frequency.
Values:
ESP_IMAGE_SPI_SPEED_40M SPI clock frequency 40 MHz
ESP_IMAGE_SPI_SPEED_26M SPI clock frequency 26 MHz

Espressif Systems

1084

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_IMAGE_SPI_SPEED_20M SPI clock frequency 20 MHz
ESP_IMAGE_SPI_SPEED_80M = 0xF SPI clock frequency 80 MHz
enum esp_image_flash_size_t Supported SPI flash sizes.
Values:
ESP_IMAGE_FLASH_SIZE_1MB = 0 SPI flash size 1 MB
ESP_IMAGE_FLASH_SIZE_2MB SPI flash size 2 MB
ESP_IMAGE_FLASH_SIZE_4MB SPI flash size 4 MB
ESP_IMAGE_FLASH_SIZE_8MB SPI flash size 8 MB
ESP_IMAGE_FLASH_SIZE_16MB SPI flash size 16 MB
ESP_IMAGE_FLASH_SIZE_MAX SPI flash size MAX
2.7.2 Application Level Tracing
Overview
IDF provides a useful feature for program behavior analysis called Application Level Tracing. The feature can be enabled in menuconfig and allows transfer of arbitrary data between the host and ESP32-S3 via JTAG interface with minimal overhead on program execution. Developers can use this library to send application specific state of execution to the host and receive commands or other type of info in the opposite direction at runtime. The main use cases of this library are:
1. Collecting application specific data, see Application Specific Tracing 2. Lightweight logging to the host, see Logging to Host 3. System behaviour analysis, see System Behavior Analysis with SEGGER SystemView
API Reference
Header File
· components/app_trace/include/esp_app_trace.h
Functions esp_err_t esp_apptrace_init(void)
Initializes application tracing module.
Note Should be called before any esp_apptrace_xxx call. Return ESP_OK on success, otherwise see esp_err_t void esp_apptrace_down_buffer_config(uint8_t *buf, uint32_t size) Configures down buffer.
Note Needs to be called before initiating any data transfer using esp_apptrace_buffer_get and esp_apptrace_write. This function does not protect internal data by lock.
Parameters · buf: Address of buffer to use for down channel (host to target) data.

Espressif Systems

1085

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· size: Size of the buffer.

uint8_t *esp_apptrace_buffer_get(esp_apptrace_dest_t dest, uint32_t size, uint32_t tmo) Allocates buffer for trace data. Once the data in the buffer is ready to be sent, esp_apptrace_buffer_put must be called to indicate it.

Return non-NULL on success, otherwise NULL. Parameters
· dest: Indicates HW interface to send data. · size: Size of data to write to trace buffer. · tmo: Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely.

esp_err_t esp_apptrace_buffer_put(esp_apptrace_dest_t dest, uint8_t *ptr, uint32_t tmo) Indicates that the data in the buffer is ready to be sent. This function is a counterpart of and must be preceded by esp_apptrace_buffer_get.

Return ESP_OK on success, otherwise see esp_err_t Parameters
· dest: Indicates HW interface to send data. Should be identical to the same parameter in call to esp_apptrace_buffer_get.
· ptr: Address of trace buffer to release. Should be the value returned by call to esp_apptrace_buffer_get.
· tmo: Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely.

esp_err_t esp_apptrace_write(esp_apptrace_dest_t dest, const void *data, uint32_t size, uint32_t

Writes data to trace buffer.

tmo)

Return ESP_OK on success, otherwise see esp_err_t Parameters
· dest: Indicates HW interface to send data. · data: Address of data to write to trace buffer. · size: Size of data to write to trace buffer. · tmo: Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely.

int esp_apptrace_vprintf_to(esp_apptrace_dest_t dest, uint32_t tmo, const char *fmt, va_list ap) vprintf-like function to send log messages to host via specified HW interface.

Return Number of bytes written. Parameters
· dest: Indicates HW interface to send data. · tmo: Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely. · fmt: Address of format string. · ap: List of arguments.

int esp_apptrace_vprintf(const char *fmt, va_list ap) vprintf-like function to send log messages to host.

Return Number of bytes written. Parameters
· fmt: Address of format string. · ap: List of arguments.

esp_err_t esp_apptrace_flush(esp_apptrace_dest_t dest, uint32_t tmo) Flushes remaining data in trace buffer to host.

Return ESP_OK on success, otherwise see esp_err_t Parameters
· dest: Indicates HW interface to flush data on. · tmo: Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely.

esp_err_t esp_apptrace_flush_nolock(esp_apptrace_dest_t dest, uint32_t min_sz, uint32_t tmo) Flushes remaining data in trace buffer to host without locking internal data. This is a special version of esp_apptrace_flush which should be called from panic handler.

Espressif Systems

1086

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return ESP_OK on success, otherwise see esp_err_t Parameters
· dest: Indicates HW interface to flush data on. · min_sz: Threshold for flushing data. If current filling level is above this value, data will be flushed.
TRAX destinations only. · tmo: Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely.
esp_err_t esp_apptrace_read(esp_apptrace_dest_t dest, void *data, uint32_t *size, uint32_t tmo) Reads host data from trace buffer.
Return ESP_OK on success, otherwise see esp_err_t Parameters
· dest: Indicates HW interface to read the data on. · data: Address of buffer to put data from trace buffer. · size: Pointer to store size of read data. Before call to this function pointed memory must hold
requested size of data · tmo: Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely.
uint8_t *esp_apptrace_down_buffer_get(esp_apptrace_dest_t dest, uint32_t *size, uint32_t tmo) Retrieves incoming data buffer if any. Once data in the buffer is processed, esp_apptrace_down_buffer_put must be called to indicate it.
Return non-NULL on success, otherwise NULL. Parameters
· dest: Indicates HW interface to receive data. · size: Address to store size of available data in down buffer. Must be initialized with requested
value. · tmo: Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely.
esp_err_t esp_apptrace_down_buffer_put(esp_apptrace_dest_t dest, uint8_t *ptr, uint32_t tmo) Indicates that the data in the down buffer is processed. This function is a counterpart of and must be preceded by esp_apptrace_down_buffer_get.
Return ESP_OK on success, otherwise see esp_err_t Parameters
· dest: Indicates HW interface to receive data. Should be identical to the same parameter in call to esp_apptrace_down_buffer_get.
· ptr: Address of trace buffer to release. Should be the value returned by call to esp_apptrace_down_buffer_get.
· tmo: Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely.
bool esp_apptrace_host_is_connected(esp_apptrace_dest_t dest) Checks whether host is connected.
Return true if host is connected, otherwise false Parameters
· dest: Indicates HW interface to use.
void *esp_apptrace_fopen(esp_apptrace_dest_t dest, const char *path, const char *mode) Opens file on host. This function has the same semantic as mfopennexcept for the first argument.
Return non zero file handle on success, otherwise 0 Parameters
· dest: Indicates HW interface to use. · path: Path to file. · mode: Mode string. See fopen for details.
int esp_apptrace_fclose(esp_apptrace_dest_t dest, void *stream) Closes file on host. This function has the same semantic as mfclosenexcept for the first argument.
Return Zero on success, otherwise non-zero. See fclose for details. Parameters
· dest: Indicates HW interface to use. · stream: File handle returned by esp_apptrace_fopen.

Espressif Systems

1087

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
size_t esp_apptrace_fwrite(esp_apptrace_dest_t dest, const void *ptr, size_t size, size_t nmemb, void *stream)
Writes to file on host. This function has the same semantic as mfwritenexcept for the first argument.
Return Number of written items. See fwrite for details. Parameters
· dest: Indicates HW interface to use. · ptr: Address of data to write. · size: Size of an item. · nmemb: Number of items to write. · stream: File handle returned by esp_apptrace_fopen.
size_t esp_apptrace_fread(esp_apptrace_dest_t dest, void *ptr, size_t size, size_t nmemb, void *stream)
Read file on host. This function has the same semantic as mfreadnexcept for the first argument.
Return Number of read items. See fread for details. Parameters
· dest: Indicates HW interface to use. · ptr: Address to store read data. · size: Size of an item. · nmemb: Number of items to read. · stream: File handle returned by esp_apptrace_fopen.
int esp_apptrace_fseek(esp_apptrace_dest_t dest, void *stream, long offset, int whence) Set position indicator in file on host. This function has the same semantic as mfseeknexcept for the first argument.
Return Zero on success, otherwise non-zero. See fseek for details. Parameters
· dest: Indicates HW interface to use. · stream: File handle returned by esp_apptrace_fopen. · offset: Offset. See fseek for details. · whence: Position in file. See fseek for details.
int esp_apptrace_ftell(esp_apptrace_dest_t dest, void *stream) Get current position indicator for file on host. This function has the same semantic as mftellnexcept for the first argument.
Return Current position in file. See ftell for details. Parameters
· dest: Indicates HW interface to use. · stream: File handle returned by esp_apptrace_fopen.
int esp_apptrace_fstop(esp_apptrace_dest_t dest) Indicates to the host that all file operations are complete. This function should be called after all file operations are finished and indicate to the host that it can perform cleanup operations (close open files etc.).
Return ESP_OK on success, otherwise see esp_err_t Parameters
· dest: Indicates HW interface to use.
void esp_gcov_dump(void) Triggers gcov info dump. This function waits for the host to connect to target before dumping data.
Enumerations enum esp_apptrace_dest_t
Application trace data destinations bits.
Values:
ESP_APPTRACE_DEST_JTAG = 1 JTAG destination.

Espressif Systems

1088

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_APPTRACE_DEST_TRAX = ESP_APPTRACE_DEST_JTAG xxx_TRAX name is obsolete, use more common xxx_JTAG
ESP_APPTRACE_DEST_UART0 UART0 destination.
ESP_APPTRACE_DEST_MAX = ESP_APPTRACE_DEST_UART0
ESP_APPTRACE_DEST_NUM

Header File · components/app_trace/include/esp_sysview_trace.h

Functions static esp_err_t esp_sysview_flush(uint32_t tmo)
Flushes remaining data in SystemView trace buffer to host.

Return ESP_OK. Parameters
· tmo: Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinetly. int esp_sysview_vprintf(const char *format, va_list args)
vprintf-like function to sent log messages to the host.

Return Number of bytes written. Parameters
· format: Address of format string. · args: List of arguments.

esp_err_t esp_sysview_heap_trace_start(uint32_t tmo) Starts SystemView heap tracing.

Return ESP_OK on success, ESP_ERR_TIMEOUT if operation has been timed out. Parameters
· tmo: Timeout (in us) to wait for the host to be connected. Use -1 to wait forever.

esp_err_t esp_sysview_heap_trace_stop(void) Stops SystemView heap tracing.

Return ESP_OK.

void esp_sysview_heap_trace_alloc(void *addr, uint32_t size, const void *callers) Sends heap allocation event to the host.

Parameters · addr: Address of allocated block. · size: Size of allocated block. · callers: Pointer to array with callstack addresses. FIG_HEAP_TRACING_STACK_DEPTH.

Array size must be CON-

void esp_sysview_heap_trace_free(void *addr, const void *callers) Sends heap de-allocation event to the host.

Parameters · addr: Address of de-allocated block. · callers: Pointer to array with callstack addresses. FIG_HEAP_TRACING_STACK_DEPTH.

Array size must be CON-

2.7.3 The Async memcpy API

Espressif Systems

1089

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Overview
ESP32-S3 has a DMA engine which can help to offload internal memory copy operations from the CPU in a asynchronous way.
The async memcpy API wraps all DMA configurations and operations, the signature of esp_async_memcpy() is almost the same to the standard libc one.
Thanks to the benefit of the DMA, we donnt have to wait for each memory copy to be done before we issue another memcpy request. By the way, itns still possible to know when memcpy is finished by listening in the memcpy callback function.
Configure and Install driver
esp_async_memcpy_install() is used to install the driver with userns configuration. Please note that async memcpy has to be called with the handle returned from esp_async_memcpy_install().
Driver configuration is described in async_memcpy_config_t: backlog: This is used to configured the maximum number of DMA operation that can be working at the background at the same time. sram_trans_align: Declare SRAM alignment for both data address and copy size, set to zero if the data has no restriction in alignment. If set to a quadruple value (i.e. 4X), the driver will enable the burst mode internally, which is helpful for some performance related application. psram_trans_align: Declare PSRAM alignment for both data address and copy size. User has to give it a valid value (only 16, 32, 64 are supported) if the destination of memcpy is located in PSRAM. The default alignment (i.e. 16) will be applied if itns set to zero. Internally, the driver configures the size of block used by DMA to access PSRAM, according to the alignment. flags: This is used to enable some special driver features.
ASYNC_MEMCPY_DEFAULT_CONFIG provides a default configuration, which specifies the backlog to 8.
async_memcpy_config_t config = ASYNC_MEMCPY_DEFAULT_CONFIG(); // update the maximum data stream supported by underlying DMA engine config.backlog = 16; async_memcpy_t driver = NULL; ESP_ERROR_CHECK(esp_async_memcpy_install(&config, &driver)); // install driver, return driver handle

Send memory copy request
esp_async_memcpy() is the API to send memory copy request to DMA engine. It must be called after driver is installed successfully. This API is thread safe, so it can be called from different tasks.
Different from the libc version of memcpy, user should also pass a callback to esp_async_memcpy(), if itns necessary to be notified when the memory copy is done. The callback is executed in the ISR context, make sure you wonnt violate the the restriction applied to ISR handler.
Besides that, the callback function should reside in IRAM space by applying IRAM_ATTR attribute. The prototype of the callback function is async_memcpy_isr_cb_t, please note that, the callback function should return true if it wakes up a high priority task by some API like xSemaphoreGiveFromISR().
Semphr_Handle_t semphr; //already initialized in somewhere
// Callback implementation, running in ISR context static IRAM_ATTR bool my_async_memcpy_cb(async_memcpy_t mcp_hdl, async_memcpy_ event_t *event, void *cb_args) {
SemaphoreHandle_t sem = (SemaphoreHandle_t)cb_args; BaseType_t high_task_wakeup = pdFALSE; SemphrGiveInISR(semphr, &high_task_wakeup); // high_task_wakeup set to pdTRUE if some high priority task unblocked return high_task_wakeup == pdTRUE;
(continues on next page)

Espressif Systems

1090

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page) }
// Called from user's context ESP_ERROR_CHECK(esp_async_memcpy(driver_handle, to, from, copy_len, my_async_ memcpy_cb, my_semaphore)); //Do something else here SemphrTake(my_semaphore, ...); //wait until the buffer copy is done

Uninstall driver (optional)
esp_async_memcpy_uninstall() is used to uninstall asynchronous memcpy driver. Itns not necessary to uninstall the driver after each memcpy operation. If you know your application wonnt use this driver anymore, then this API can recycle the memory for you.

API Reference
Header File · components/esp_hw_support/include/esp_async_memcpy.h

Functions

esp_err_t esp_async_memcpy_install(const async_memcpy_config_t *config, async_memcpy_t

Install async memcpy driver.

*asmcp)

Return · ESP_OK: Install async memcpy driver successfully · ESP_ERR_INVALID_ARG: Install async memcpy driver failed because of invalid argument · ESP_ERR_NO_MEM: Install async memcpy driver failed because out of memory · ESP_FAIL: Install async memcpy driver failed because of other error
Parameters · [in] config: Configuration of async memcpy · [out] asmcp: Handle of async memcpy that returned from this API. If driver installation is failed, asmcp would be assigned to NULL.
esp_err_t esp_async_memcpy_uninstall(async_memcpy_t asmcp) Uninstall async memcpy driver.

Return · ESP_OK: Uninstall async memcpy driver successfully · ESP_ERR_INVALID_ARG: Uninstall async memcpy driver failed because of invalid argument · ESP_FAIL: Uninstall async memcpy driver failed because of other error
Parameters · [in] asmcp: Handle of async memcpy driver that returned from esp_async_memcpy_install

esp_err_t esp_async_memcpy(async_memcpy_t asmcp, void *dst, void *src, size_t n, async_memcpy_isr_cb_t cb_isr, void *cb_args)
Send an asynchronous memory copy request.

Return · ESP_OK: Send memory copy request successfully · ESP_ERR_INVALID_ARG: Send memory copy request failed because of invalid argument · ESP_FAIL: Send memory copy request failed because of other error
Note The callback function is invoked in interrupt context, never do blocking jobs in the callback. Parameters
· [in] asmcp: Handle of async memcpy driver that returned from esp_async_memcpy_install · [in] dst: Destination address (copy to) · [in] src: Source address (copy from) · [in] n: Number of bytes to copy

Espressif Systems

1091

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· [in] cb_isr: Callback function, which got invoked in interrupt context. Set to NULL can bypass the callback.
· [in] cb_args: User defined argument to be passed to the callback function

Structures struct async_memcpy_event_t
Type of async memcpy event object.

Public Members
void *data Event data
struct async_memcpy_config_t Type of async memcpy configuration.

Public Members
uint32_t backlog Maximum number of streams that can be handled simultaneously
size_t sram_trans_align DMA transfer alignment (both in size and address) for SRAM memory
size_t psram_trans_align DMA transfer alignment (both in size and address) for PSRAM memory
uint32_t flags Extra flags to control async memcpy feature

Macros ASYNC_MEMCPY_DEFAULT_CONFIG()
Default configuration for async memcpy.

Type Definitions typedef struct async_memcpy_context_t *async_memcpy_t
Type of async memcpy handle. typedef bool (*async_memcpy_isr_cb_t)(async_memcpy_t mcp_hdl,
*event, void *cb_args) Type of async memcpy interrupt callback function.

async_memcpy_event_t

Return Whether a high priority task is woken up by the callback function Note User can call OS primitives (semaphore, mutex, etc) in the callback function. Keep in mind, if any OS
primitive wakes high priority task up, the callback should return true. Parameters
· mcp_hdl: Handle of async memcpy · event: Event object, which contains related data, reserved for future · cb_args: User defined arguments, passed from esp_async_memcpy function

2.7.4 Console
ESP-IDF provides console component, which includes building blocks needed to develop an interactive console over serial port. This component includes following facilities:
· Line editing, provided by linenoise library. This includes handling of backspace and arrow keys, scrolling through command history, command auto-completion, and argument hints.
· Splitting of command line into arguments.

Espressif Systems

1092

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· Argument parsing, provided by argtable3 library. This library includes APIs used for parsing GNU style command line arguments.
· Functions for registration and dispatching of commands. · Functions to establish a basic REPL (Read-Evaluate-Print-Loop) environment.
Note: These facilities can be used together or independently. For example, it is possible to use line editing and command registration features, but use getopt or custom code for argument parsing, instead of argtable3. Likewise, it is possible to use simpler means of command input (such as fgets) together with the rest of the means for command splitting and argument parsing.

Line editing
Line editing feature lets users compose commands by typing them, erasing symbols using mbackspacenkey, navigating within the command using left/right keys, navigating to previously typed commands using up/down keys, and performing autocompletion using mtabnkey.
Note: This feature relies on ANSI escape sequence support in the terminal application. As such, serial monitors which display raw UART data can not be used together with the line editing library. If you see [6n or similar escape sequence when running system/console example instead of a command prompt (e.g. esp> ), it means that the serial monitor does not support escape sequences. Programs which are known to work are GNU screen, minicom, and idf_monitor.py (which can be invoked using idf.py monitor from project directory).
Here is an overview of functions provided by linenoise library.

Configuration Linenoise library does not need explicit initialization. However, some configuration defaults may need to be changed before invoking the main line editing function.
linenoiseClearScreen()
Clear terminal screen using an escape sequence and position the cursor at the top left corner.
linenoiseSetMultiLine()
Switch between single line and multi line editing modes. In single line mode, if the length of the command exceeds the width of the terminal, the command text is scrolled within the line to show the end of the text. In this case the beginning of the text is hidden. Single line needs less data to be sent to refresh screen on each key press, so exhibits less glitching compared to the multi line mode. On the flip side, editing commands and copying command text from terminal in single line mode is harder. Default is single line mode.
linenoiseAllowEmpty()
Set whether linenoise library will return a zero-length string (if true) or NULL (if false) for empty lines. By default, zero-length strings are returned.
linenoiseSetMaxLineLen()
Set maximum length of the line for linenoise library. Default length is 4096. If you need optimize RAM memory usage, you can do it by this function by setting a value less than default 4 KB.

Main loop linenoise()
In most cases, console applications have some form of read/eval loop. linenoise() is the single function which handles userns key presses and returns completed line oncementernkey is pressed. As such, it handles the mreadnpart of the loop.
linenoiseFree()
This function must be called to release the command line buffer obtained from linenoise() function.

Espressif Systems

1093

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Hints and completions linenoiseSetCompletionCallback() When user presses mtabnkey, linenoise library invokes completion callback. The callback should inspect the contents of the command typed so far and provide a list of possible completions using calls to linenoiseAddCompletion() function. linenoiseSetCompletionCallback() function should be called to register this completion callback, if completion feature is desired. console component provides a ready made function to provide completions for registered commands, esp_console_get_completion() (see below).
linenoiseAddCompletion() Function to be called by completion callback to inform the library about possible completions of the currently typed command.
linenoiseSetHintsCallback() Whenever user input changes, linenoise invokes hints callback. This callback can inspect the command line typed so far, and provide a string with hints (which can include list of command arguments, for example). The library then displays the hint text on the same line where editing happens, possibly with a different color.
linenoiseSetFreeHintsCallback() If hint string returned by hints callback is dynamically allocated or needs to be otherwise recycled, the function which performs such cleanup should be registered via linenoiseSetFreeHintsCallback().
History linenoiseHistorySetMaxLen() This function sets the number of most recently typed commands to be kept in memory. Users can navigate the history using up/down arrows.
linenoiseHistoryAdd() Linenoise does not automatically add commands to history. Instead, applications need to call this function to add command strings to the history.
linenoiseHistorySave() Function saves command history from RAM to a text file, for example on an SD card or on a filesystem in flash memory.
linenoiseHistoryLoad() Counterpart to linenoiseHistorySave(), loads history from a file.
linenoiseHistoryFree() Releases memory used to store command history. Call this function when done working with linenoise library.
Splitting of command line into arguments
console component provides esp_console_split_argv() function to split command line string into arguments. The function returns the number of arguments found (argc) and fills an array of pointers which can be passed as argv argument to any function which accepts arguments in argc, argv format. The command line is split into arguments according to the following rules:
· Arguments are separated by spaces · If spaces within arguments are required, they can be escaped using \ (backslash) character. · Other escape sequences which are recognized are \\ (which produces literal backslash) and \", which pro-
duces a double quote.

Espressif Systems

1094

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· Arguments can be quoted using double quotes. Quotes may appear only in the beginning and at the end of the argument. Quotes within the argument must be escaped as mentioned above. Quotes surrounding the argument are stripped by esp_console_split_argv function.
Examples: · abc def 1 20 .3  [ abc, def, 1, 20, .3 ] · abc "123 456" def  [ abc, 123 456, def ] · `a\ b\\c\"  [ a b\c" ]
Argument parsing
For argument parsing, console component includes argtable3 library. Please see tutorial for an introduction to argtable3. Github repository also includes examples.
Command registration and dispatching
console component includes utility functions which handle registration of commands, matching commands typed by the user to registered ones, and calling these commands with the arguments given on the command line. Application first initializes command registration module using a call to esp_console_init(), and calls esp_console_cmd_register() function to register command handlers. For each command, application provides the following information (in the form of esp_console_cmd_t structure):
· Command name (string without spaces) · Help text explaining what the command does · Optional hint text listing the arguments of the command. If application uses Argtable3 for argument pars-
ing, hint text can be generated automatically by providing a pointer to argtable argument definitions structure instead. · The command handler function. A few other functions are provided by the command registration module: esp_console_run() This function takes the command line string, splits it into argc/argv argument list using esp_console_split_argv(), looks up the command in the list of registered components, and if it is found, executes its handler. esp_console_register_help_command() Adds help command to the list of registered commands. This command prints the list of all the registered commands, along with their arguments and help texts. esp_console_get_completion() Callback function to be used with linenoiseSetCompletionCallback() from linenoise library. Provides completions to linenoise based on the list of registered commands. esp_console_get_hint() Callback function to be used with linenoiseSetHintsCallback() from linenoise library. Provides argument hints for registered commands to linenoise.
Initialize console REPL environment
To establish a basic REPL environment, console component provides several useful APIs, combining those functions described above.

Espressif Systems

1095

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

In a typical application, you only need to call esp_console_new_repl_uart() to initialize the REPL environment based on UART device, including driver install, basic console configuration, spawning a thread to do REPL task and register several useful commands (e.g. help).
After that, you can register your own commands with esp_console_cmd_register(). The REPL environment keeps in init state until you call esp_console_start_repl().
Likewise, if your REPL environment is based on USB_SERIAL_JTAG device, you only need to call esp_console_new_repl_usb_serial_jtag() at first step. And call other functions as usual.

Application Example
Example application illustrating usage of the console component is available in system/console directory. This example shows how to initialize UART and VFS functions, set up linenoise library, read and handle commands from UART, and store command history in Flash. See README.md in the example directory for more details.
Besides that, ESP-IDF contains several useful examples which based on console component and can be treated as otoolspwhen developing applications. For example, peripherals/i2c/i2c_tools, wifi/iperf.

API Reference
Header File · components/console/esp_console.h

Functions esp_err_t esp_console_init(const esp_console_config_t *config)
initialize console module
Note Call this once before using other console module features Return
· ESP_OK on success · ESP_ERR_NO_MEM if out of memory · ESP_ERR_INVALID_STATE if already initialized · ESP_ERR_INVALID_ARG if the configuration is invalid Parameters · config: console configuration esp_err_t esp_console_deinit(void) de-initialize console module
Note Call this once when done using console module functions Return
· ESP_OK on success · ESP_ERR_INVALID_STATE if not initialized yet
esp_err_t esp_console_cmd_register(const esp_console_cmd_t *cmd) Register console command.
Return · ESP_OK on success · ESP_ERR_NO_MEM if out of memory · ESP_ERR_INVALID_ARG if command description includes invalid arguments
Parameters · cmd: pointer to the command description; can point to a temporary value
esp_err_t esp_console_run(const char *cmdline, int *cmd_ret) Run command line.
Return · ESP_OK, if command was run · ESP_ERR_INVALID_ARG, if the command line is empty, or only contained whitespace

Espressif Systems

1096

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_ERR_NOT_FOUND, if command with given name wasnnt registered · ESP_ERR_INVALID_STATE, if esp_console_init wasnnt called Parameters · cmdline: command line (command name followed by a number of arguments) · [out] cmd_ret: return code from the command (set if command was run)
size_t esp_console_split_argv(char *line, char **argv, size_t argv_size) Split command line into arguments in place.

* - This function finds whitespace-separated arguments in the given input line.

*

*

'abc def 1 20 .3' -> [ 'abc', 'def', '1', '20', '.3' ]

*

* - Argument which include spaces may be surrounded with quotes. In this case

* spaces are preserved and quotes are stripped.

*

*

'abc "123 456" def' -> [ 'abc', '123 456', 'def' ]

*

* - Escape sequences may be used to produce backslash, double quote, and space:

*

*

'a\ b\\c\"' -> [ 'a b\c"' ]

*

Note Pointers to at most argv_size - 1 arguments are returned in argv array. The pointer after the last one (i.e. argv[argc]) is set to NULL.
Return number of arguments found (argc) Parameters
· line: pointer to buffer to parse; it is modified in place · argv: array where the pointers to arguments are written · argv_size: number of elements in argv_array (max. number of arguments)
void esp_console_get_completion(const char *buf, linenoiseCompletions *lc) Callback which provides command completion for linenoise library.
When using linenoise for line editing, command completion support can be enabled like this:
linenoiseSetCompletionCallback(&esp_console_get_completion);
Parameters · buf: the string typed by the user · lc: linenoiseCompletions to be filled in
const char *esp_console_get_hint(const char *buf, int *color, int *bold) Callback which provides command hints for linenoise library.
When using linenoise for line editing, hints support can be enabled as follows:
linenoiseSetHintsCallback((linenoiseHintsCallback*) &esp_console_get_hint);
The extra cast is needed because linenoiseHintsCallback is defined as returning a char* instead of const char*.
Return string containing the hint text. This string is persistent and should not be freed (i.e. linenoiseSetFreeHintsCallback should not be used).
Parameters · buf: line typed by the user · [out] color: ANSI color code to be used when displaying the hint · [out] bold: set to 1 if hint has to be displayed in bold
esp_err_t esp_console_register_help_command(void) Register a mhelpncommand.
Default mhelpncommand prints the list of registered commands along with hints and help strings.
Return · ESP_OK on success · ESP_ERR_INVALID_STATE, if esp_console_init wasnnt called

Espressif Systems

1097

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t esp_console_new_repl_uart(const esp_console_dev_uart_config_t

const

esp_console_repl_config_t

esp_console_repl_t **ret_repl)

Establish a console REPL environment over UART driver.

*dev_config, *repl_config,

Note This is an all-in-one function to establish the environment needed for REPL, includes: · Install the UART driver on the console UART (8n1, 115200, REF_TICK clock source) · Configures the stdin/stdout to go through the UART driver · Initializes linenoise · Spawn new thread to run REPL in the background
Attention This function is meant to be used in the examples to make the code more compact. Applications which use console functionality should be based on the underlying linenoise and esp_console functions.
Return · ESP_OK on success · ESP_FAIL Parameter error
Parameters · [in] dev_config: UART device configuration · [in] repl_config: REPL configuration · [out] ret_repl: return REPL handle after initialization succeed, return NULL otherwise

esp_err_t esp_console_new_repl_usb_cdc(const

esp_console_dev_usb_cdc_config_t

*dev_config, const esp_console_repl_config_t

*repl_config, esp_console_repl_t **ret_repl)

Establish a console REPL environment over USB CDC.

Note This is a all-in-one function to establish the environment needed for REPL, includes: · Initializes linenoise · Spawn new thread to run REPL in the background
Attention This function is meant to be used in the examples to make the code more compact. Applications which use console functionality should be based on the underlying linenoise and esp_console functions.
Return · ESP_OK on success · ESP_FAIL Parameter error
Parameters · [in] dev_config: USB CDC configuration · [in] repl_config: REPL configuration · [out] ret_repl: return REPL handle after initialization succeed, return NULL otherwise

esp_err_t esp_console_start_repl(esp_console_repl_t *repl) Start REPL environment.

Note Once the REPL gets started, it wonnt be stopped until the user calls repl->del(repl) to destroy the REPL environment.
Return · ESP_OK on success · ESP_ERR_INVALID_STATE, if repl has started already
Parameters · [in] repl: REPL handle returned from esp_console_new_repl_xxx

Structures struct esp_console_config_t
Parameters for console initialization.

Public Members
size_t max_cmdline_length length of command line buffer, in bytes
size_t max_cmdline_args maximum number of command line arguments to parse

Espressif Systems

1098

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
int hint_color ASCII color code of hint text.
int hint_bold Set to 1 to print hint text in bold.
struct esp_console_repl_config_t Parameters for console REPL (Read Eval Print Loop)
Public Members
uint32_t max_history_len maximum length for the history
const char *history_save_path file path used to save history commands, set to NULL wonnt save to file system
uint32_t task_stack_size repl task stack size
uint32_t task_priority repl task priority
const char *prompt prompt (NULL represents default: oesp> o)
size_t max_cmdline_length maximum length of a command line. If 0, default value will be used
struct esp_console_dev_uart_config_t Parameters for console device: UART.
Public Members
int channel UART channel number (count from zero)
int baud_rate Comunication baud rate.
int tx_gpio_num GPIO number for TX path, -1 means using default one.
int rx_gpio_num GPIO number for RX path, -1 means using default one.
struct esp_console_dev_usb_cdc_config_t Parameters for console device: USB CDC. Note Itns an empty structure for now, reserved for future
struct esp_console_cmd_t Console command description.
Public Members
const char *command Command name. Must not be NULL, must not contain spaces. The pointer must be valid until the call to esp_console_deinit.
const char *help Help text for the command, shown by help command. If set, the pointer must be valid until the call to esp_console_deinit. If not set, the command will not be listed in mhelpnoutput.

Espressif Systems

1099

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
const char *hint Hint text, usually lists possible arguments. If set to NULL, and margtablenfield is non-NULL, hint will be generated automatically
esp_console_cmd_func_t func Pointer to a function which implements the command.
void *argtable Array or structure of pointers to arg_xxx structures, may be NULL. Used to generate hint text if mhintn is set to NULL. Array/structure which this field points to must end with an arg_end. Only used for the duration of esp_console_cmd_register call.
struct esp_console_repl_s Console REPL base structure.
Public Members
esp_err_t (*del)(esp_console_repl_t *repl) Delete console REPL environment. Return · ESP_OK on success · ESP_FAIL on errors Parameters · [in] repl: REPL handle returned from esp_console_new_repl_xxx
Macros ESP_CONSOLE_CONFIG_DEFAULT()
Default console configuration value. ESP_CONSOLE_REPL_CONFIG_DEFAULT()
Default console repl configuration value. ESP_CONSOLE_DEV_UART_CONFIG_DEFAULT() ESP_CONSOLE_DEV_CDC_CONFIG_DEFAULT()
Type Definitions typedef struct linenoiseCompletions linenoiseCompletions typedef int (*esp_console_cmd_func_t)(int argc, char **argv)
Console command main function. Return console command return code, 0 indicates osuccessp Parameters
· argc: number of arguments · argv: array with argc entries, each pointing to a zero-terminated string argument typedef struct esp_console_repl_s esp_console_repl_t Type defined for console REPL.
2.7.5 eFuse Manager
Introduction
The eFuse Manager library is designed to structure access to eFuse bits and make using these easy. This library operates eFuse bits by a structure name which is assigned in eFuse table. This sections introduces some concepts used by eFuse Manager.

Espressif Systems

1100

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Hardware description
The ESP32-S3 has a number of eFuses which can store system and user parameters. Each eFuse is a one-bit field which can be programmed to 1 after which it cannot be reverted back to 0. Some of system parameters are using these eFuse bits directly by hardware modules and have special place (for example EFUSE_BLK0).
For more details, see ESP32-S3 Technical Reference Manual > eFuse Controller (eFuse) [PDF]. Some eFuse bits are available for user applications.
ESP32-S3 has 11 eFuse blocks each of the size of 256 bits (not all bits are available):
· EFUSE_BLK0 is used entirely for system purposes; · EFUSE_BLK1 is used entirely for system purposes; · EFUSE_BLK2 is used entirely for system purposes; · EFUSE_BLK3 or EFUSE_BLK_USER_DATA can be used for user purposes; · EFUSE_BLK4 or EFUSE_BLK_KEY0 can be used as key (for secure_boot or flash_encryption) or for user
purposes; · EFUSE_BLK5 or EFUSE_BLK_KEY1 can be used as key (for secure_boot or flash_encryption) or for user
purposes; · EFUSE_BLK6 or EFUSE_BLK_KEY2 can be used as key (for secure_boot or flash_encryption) or for user
purposes; · EFUSE_BLK7 or EFUSE_BLK_KEY3 can be used as key (for secure_boot or flash_encryption) or for user
purposes; · EFUSE_BLK8 or EFUSE_BLK_KEY4 can be used as key (for secure_boot or flash_encryption) or for user
purposes; · EFUSE_BLK9 or EFUSE_BLK_KEY5 can be used as key (for secure_boot or flash_encryption) or for user
purposes; · EFUSE_BLK10 or EFUSE_BLK_SYS_DATA_PART2 is reseved for system purposes.
Each block is divided into 8 32-bits registers.

eFuse Manager component
The component has API functions for reading and writing fields. Access to the fields is carried out through the structures that describe the location of the eFuse bits in the blocks. The component provides the ability to form fields of any length and from any number of individual bits. The description of the fields is made in a CSV file in a table form. To generate from a tabular form (CSV file) in the C-source uses the tool efuse_table_gen.py. The tool checks the CSV file for uniqueness of field names and bit intersection, in case of using a custom file from the userns project directory, the utility will check with the common CSV file.
CSV files:
· common (esp_efuse_table.csv) - contains eFuse fields which are used inside the IDF. C-source generation should be done manually when changing this file (run command idf.py efuse-common-table). Note that changes in this file can lead to incorrect operation.
· custom - (optional and can be enabled by CONFIG_EFUSE_CUSTOM_TABLE) contains eFuse fields that are used by the user in their application. C-source generation should be done manually when changing this file and running idf.py efuse-custom-table.

Description CSV file

The CSV file contains a description of the eFuse fields. In the simple case, one field has one line of description. Table header:

# field_name, efuse_block(EFUSE_BLK0..EFUSE_BLK10), bit_start(0..255),

count(1..256),

comment

bit_

Individual params in CSV file the following meanings:

Espressif Systems

1101

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

field_name Name of field. The prefix ESP_EFUSE_ will be added to the name, and this field name will be available in the code. This name will be used to access the fields. The name must be unique for all fields. If the line has an empty name, then this line is combined with the previous field. This allows you to set an arbitrary order of bits in the field, and expand the field as well (see MAC_FACTORY field in the common table). The field_name supports structured format using . to show that the field belongs to another field (see WR_DIS and RD_DIS in the common table).
efuse_block Block number. It determines where the eFuse bits will be placed for this field. Available EFUSE_BLK0..EFUSE_BLK10.
bit_start Start bit number (0..255). The bit_start field can be omitted. In this case, it will be set to bit_start + bit_count from the previous record, if it has the same efuse_block. Otherwise (if efuse_block is different, or this is the first entry), an error will be generated.
bit_count The number of bits to use in this field (1..-). This parameter can not be omitted. This field also may be MAX_BLK_LEN in this case, the field length will have the maximum block length.
comment This param is using for comment field, it also move to C-header file. The comment field can be omitted.
If a non-sequential bit order is required to describe a field, then the field description in the following lines should be continued without specifying a name, this will indicate that it belongs to one field. For example two fields MAC_FACTORY and MAC_FACTORY_CRC:

# Factory MAC address #

#######################

MAC_FACTORY,

EFUSE_BLK0, 72, 8, Factory MAC addr [0]

,

EFUSE_BLK0, 64, 8, Factory MAC addr [1]

,

EFUSE_BLK0, 56, 8, Factory MAC addr [2]

,

EFUSE_BLK0, 48, 8, Factory MAC addr [3]

,

EFUSE_BLK0, 40, 8, Factory MAC addr [4]

,

EFUSE_BLK0, 32, 8, Factory MAC addr [5]

MAC_FACTORY_CRC,

EFUSE_BLK0, 80, 8, CRC8 for factory MAC address

This field will available in code as ESP_EFUSE_MAC_FACTORY and ESP_EFUSE_MAC_FACTORY_CRC.

Structured efuse fields

WR_DIS,

EFUSE_BLK0, 0, 32,

WR_DIS.RD_DIS,

EFUSE_BLK0, 0, 1,

RD_DIS

WR_DIS.FIELD_1,

EFUSE_BLK0, 1, 1,

FIELD_1

WR_DIS.FIELD_2,

EFUSE_BLK0, 2, 4,

FIELD_2 (includes B1 and B2)

WR_DIS.FIELD_2.B1,

EFUSE_BLK0, 2, 2,

FIELD_2.B1

WR_DIS.FIELD_2.B2,

EFUSE_BLK0, 4, 2,

FIELD_2.B2

WR_DIS.FIELD_3,

EFUSE_BLK0, 5, 1,

FIELD_3

WR_DIS.FIELD_3.ALIAS,

EFUSE_BLK0, 5, 1,

FIELD_3 (just a alias for WR_DIS.FIELD_3)

WR_DIS.FIELD_4,

EFUSE_BLK0, 7, 1,

FIELD_4

Write protection Write protection for Write protection for Write protection for Write protection for Write protection for Write protection for Write protection for Write protection for

The structured eFuse field looks like WR_DIS.RD_DIS where the dot points that this field belongs to the parent field - WR_DIS and can not be out of the parentns range.
It is possible to use some levels of structured fields as WR_DIS.FIELD_2.B1 and B2. These fields should not be crossed each other and should be in the range of two fields: WR_DIS and WR_DIS.FIELD_2.
It is possible to create aliases for fields with the same range, see WR_DIS.FIELD_3 and WR_DIS.FIELD_3. ALIAS.

Espressif Systems

1102

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

The IDF names for structured efuse fields should be unique. The efuse_table_gen tool will generate the final names where the dot will be replaced by _. The names for using in IDF are ESP_EFUSE_WR_DIS, ESP_EFUSE_WR_DIS_RD_DIS, ESP_EFUSE_WR_DIS_FIELD_2_B1, etc.
efuse_table_gen.py tool
The tool is designed to generate C-source files from CSV file and validate fields. First of all, the check is carried out on the uniqueness of the names and overlaps of the field bits. If an additional custom file is used, it will be checked with the existing common file (esp_efuse_table.csv). In case of errors, a message will be displayed and the string that caused the error. C-source files contain structures of type esp_efuse_desc_t. To generate a common files, use the following command idf.py efuse-common-table or:
cd $IDF_PATH/components/efuse/ ./efuse_table_gen.py esp32s3/esp_efuse_table.csv
After generation in the folder $IDF_PATH/components/efuse/esp32s3 create: · esp_efuse_table.c file. · In include folder esp_efuse_table.c file.
To generate a custom files, use the following command idf.py efuse-custom-table or:
cd $IDF_PATH/components/efuse/ ./efuse_table_gen.py esp32s3/esp_efuse_table.csv PROJECT_PATH/main/esp_efuse_ custom_table.csv
After generation in the folder PROJECT_PATH/main create: · esp_efuse_custom_table.c file. · In include folder esp_efuse_custom_table.c file.
To use the generated fields, you need to include two files:
#include "esp_efuse.h" #include "esp_efuse_table.h" or "esp_efuse_custom_table.h"

Supported coding scheme
Coding schemes are used to protect against data corruption. ESP32-S3 supports two coding schemes:
· None. EFUSE_BLK0 is stored with four backups, meaning each bit is stored four times. This backup scheme is automatically applied by the hardware and is not visible to software. EFUSE_BLK0 can be written many times.
· RS. EFUSE_BLK1 - EFUSE_BLK10 use Reed-Solomon coding scheme that supports up to 5 bytes of automatic error correction. Software will encode the 32-byte EFUSE_BLKx using RS (44, 32) to generate a 12-byte check code, and then burn the EFUSE_BLKx and the check code into eFuse at the same time. The eFuse Controller automatically decodes the RS encoding and applies error correction when reading back the eFuse block. Because the RS check codes are generated across the entire 256-bit eFuse block, each block can only be written to one time.
To write some fields into one block, or different blocks in one time, you need to use the batch writing mode. Firstly set this mode through esp_efuse_batch_write_begin() function then write some fields as usual using the esp_efuse_write_... functions. At the end to burn them, call the esp_efuse_batch_write_commit() function. It burns prepared data to the eFuse blocks and disables the batch recording mode.

eFuse API Access to the fields is via a pointer to the description structure. API functions have some basic operation:

Espressif Systems

1103

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· esp_efuse_read_field_blob() - returns an array of read eFuse bits. · esp_efuse_read_field_cnt() - returns the number of bits programmed as o1p. · esp_efuse_write_field_blob() - writes an array. · esp_efuse_write_field_cnt() - writes a required count of bits as o1p. · esp_efuse_get_field_size() - returns the number of bits by the field name. · esp_efuse_read_reg() - returns value of eFuse register. · esp_efuse_write_reg() - writes value to eFuse register. · esp_efuse_get_coding_scheme() - returns eFuse coding scheme for blocks. · esp_efuse_read_block() - reads key to eFuse block starting at the offset and the required size. · esp_efuse_write_block() - writes key to eFuse block starting at the offset and the required size. · esp_efuse_batch_write_begin() - set the batch mode of writing fields. · esp_efuse_batch_write_commit() - writes all prepared data for batch writing mode and reset the
batch writing mode. · esp_efuse_batch_write_cancel() - reset the batch writing mode and prepared data. · esp_efuse_get_key_dis_read() - Returns a read protection for the key block. · esp_efuse_set_key_dis_read() - Sets a read protection for the key block. · esp_efuse_get_key_dis_write() - Returns a write protection for the key block. · esp_efuse_set_key_dis_write() - Sets a write protection for the key block. · esp_efuse_get_key_purpose() - Returns the current purpose set for an eFuse key block. · esp_efuse_write_key() - Programs a block of key data to an eFuse block · esp_efuse_write_keys() - Programs keys to unused eFuse blocks · esp_efuse_find_purpose() - Finds a key block with the particular purpose set. · esp_efuse_get_keypurpose_dis_write() - Returns a write protection of the key purpose field
for an eFuse key block (for esp32 always true). · esp_efuse_key_block_unused() - Returns true if the key block is unused, false otherwise.
For frequently used fields, special functions are made, like this esp_efuse_get_chip_ver(), esp_efuse_get_pkg_ver().
eFuse API for keys
EFUSE_BLK_KEY0 - EFUSE_BLK_KEY5 are intended to keep up to 6 keys with a length of 256-bits. Each key has an ESP_EFUSE_KEY_PURPOSE_x field which defines the purpose of these keys. The purpose field is described in esp_efuse_purpose_t.
The purposes like ESP_EFUSE_KEY_PURPOSE_XTS_AES_... are used for flash encryption.
The purposes like ESP_EFUSE_KEY_PURPOSE_SECURE_BOOT_DIGEST... are used for secure boot.
There are some eFuse APIs useful to work with states of keys.
· esp_efuse_get_purpose_field() - Returns a pointer to a key purpose for an eFuse key block. · esp_efuse_get_key() - Returns a pointer to a key block. · esp_efuse_set_key_purpose() - Sets a key purpose for an eFuse key block. · esp_efuse_set_keypurpose_dis_write() - Sets a write protection of the key purpose field for an
eFuse key block. · esp_efuse_find_unused_key_block() - Search for an unused key block and return the first one
found. · esp_efuse_count_unused_key_blocks() - Returns the number of unused eFuse key blocks in the
range EFUSE_BLK_KEY0..EFUSE_BLK_KEY_MAX · esp_efuse_get_digest_revoke() - Returns the status of the Secure Boot public key digest revoca-
tion bit. · esp_efuse_set_digest_revoke() - Sets the Secure Boot public key digest revocation bit. · esp_efuse_get_write_protect_of_digest_revoke() - Returns a write protection of the Se-
cure Boot public key digest revocation bit. · esp_efuse_set_write_protect_of_digest_revoke() - Sets a write protection of the Secure
Boot public key digest revocation bit.

Espressif Systems

1104

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

How to add a new field

1. Find a free bits for field. Show esp_efuse_table.csv file or run idf.py show-efuse-table or the next command:

$ ./efuse_table_gen.py esp32s3/esp_efuse_table.csv --info

eFuse coding scheme: NONE

#

field_name

efuse_block

bit_start

1

WR_DIS_FLASH_CRYPT_CNT

EFUSE_BLK0

2

2

WR_DIS_BLK1

EFUSE_BLK0

7

3

WR_DIS_BLK2

EFUSE_BLK0

8

4

WR_DIS_BLK3

EFUSE_BLK0

9

5

RD_DIS_BLK1

EFUSE_BLK0

16

6

RD_DIS_BLK2

EFUSE_BLK0

17

7

RD_DIS_BLK3

EFUSE_BLK0

18

8

FLASH_CRYPT_CNT

EFUSE_BLK0

20

9

MAC_FACTORY

EFUSE_BLK0

32

10

MAC_FACTORY

EFUSE_BLK0

40

11

MAC_FACTORY

EFUSE_BLK0

48

12

MAC_FACTORY

EFUSE_BLK0

56

13

MAC_FACTORY

EFUSE_BLK0

64

14

MAC_FACTORY

EFUSE_BLK0

72

15

MAC_FACTORY_CRC

EFUSE_BLK0

80

16

CHIP_VER_DIS_APP_CPU

EFUSE_BLK0

96

17

CHIP_VER_DIS_BT

EFUSE_BLK0

97

18

CHIP_VER_PKG

EFUSE_BLK0

105

19

CHIP_CPU_FREQ_LOW

EFUSE_BLK0

108

20

CHIP_CPU_FREQ_RATED

EFUSE_BLK0

109

21

CHIP_VER_REV1

EFUSE_BLK0

111

22

ADC_VREF_AND_SDIO_DREF

EFUSE_BLK0

136

23

XPD_SDIO_REG

EFUSE_BLK0

142

24

SDIO_TIEH

EFUSE_BLK0

143

25

SDIO_FORCE

EFUSE_BLK0

144

26

ENCRYPT_CONFIG

EFUSE_BLK0

188

27

CONSOLE_DEBUG_DISABLE

EFUSE_BLK0

194

28

ABS_DONE_0

EFUSE_BLK0

196

29

DISABLE_JTAG

EFUSE_BLK0

198

30

DISABLE_DL_ENCRYPT

EFUSE_BLK0

199

31

DISABLE_DL_DECRYPT

EFUSE_BLK0

200

32

DISABLE_DL_CACHE

EFUSE_BLK0

201

33

ENCRYPT_FLASH_KEY

EFUSE_BLK1

0

34

SECURE_BOOT_KEY

EFUSE_BLK2

0

35

MAC_CUSTOM_CRC

EFUSE_BLK3

0

36

MAC_CUSTOM

EFUSE_BLK3

8

37

ADC1_TP_LOW

EFUSE_BLK3

96

38

ADC1_TP_HIGH

EFUSE_BLK3

103

39

ADC2_TP_LOW

EFUSE_BLK3

112

40

ADC2_TP_HIGH

EFUSE_BLK3

119

41

SECURE_VERSION

EFUSE_BLK3

128

42

MAC_CUSTOM_VER

EFUSE_BLK3

184

bit_count 1 1 1 1 1 1 1 7 8 8 8 8 8 8 8 1 1 3 1 1 1 6 1 1 1 4 1 1 1 1 1 1
256 256
8 48 7 9 7 9 32 8

Used bits in eFuse table: EFUSE_BLK0 [2 2] [7 9] [16 18] [20 27] [32 87] [96 97] [105 109] [111 111] [136 144] [188 191] [194 194] [196 196] [198 201]

EFUSE_BLK1 [0 255]

EFUSE_BLK2 [0 255]

(continues on next page)

Espressif Systems

1105

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

EFUSE_BLK3 [0 55] [96 159] [184 191]

(continued from previous page)

Note: Not printed ranges are free for using. (bits in EFUSE_BLK0 are reserved for Espressif)

Parsing eFuse CSV input file $IDF_PATH/components/efuse/esp32s3/esp_efuse_table. csv ... Verifying eFuse table...

The number of bits not included in square brackets is free (bits in EFUSE_BLK0 are reserved for Espressif). All fields are checked for overlapping.
2. Fill a line for field: field_name, efuse_block, bit_start, bit_count, comment. 3. Run a show_efuse_table command to check eFuse table. To generate source files run
efuse_common_table or efuse_custom_table command.

Debug eFuse & Unit tests
Virtual eFuses The Kconfig option CONFIG_EFUSE_VIRTUAL will virtualize eFuse values inside the eFuse Manager, so writes are emulated and no eFuse values are permanently changed. This can be useful for debugging app and unit tests. During startup, the eFuses are copied to RAM. All eFuse operations (read and write) are performed with RAM instead of the real eFuse registers.
In addition to the CONFIG_EFUSE_VIRTUAL option there is CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH option that adds a feature to keep eFuses in flash memory. To use this mode the partition_table should have the efuse partition. partition.csv: "efuse_em, data, efuse, , 0x2000,". During startup, the eFuses are copied from flash or, in case if flash is empty, from real eFuse to RAM and then update flash. This option allows keeping eFuses after reboots (possible to test secure_boot and flash_encryption features with this option).

espefuse.py esptool includes a useful tool for reading/writing ESP32-S3 eFuse bits - espefuse.py. espefuse.py -p PORT summary

Connecting....

Detecting chip type... ESP32-S3

espefuse.py v3.1-dev

EFUSE_NAME (Block)

Description = [Meaningful

Value] [Readable/Writeable] (Hex Value)

--------------------------------------------------------------------------

--------------

Calibration fuses:

TEMP_SENSOR_CAL (BLOCK2)

Temperature calibration





= -9.200000000000001 R/W (0b101011100)

ADC1_MODE0_D2 (BLOCK2)

ADC1 calibration 1





= -28 R/W (0x87)

ADC1_MODE1_D2 (BLOCK2)

ADC1 calibration 2





= -28 R/W (0x87)

ADC1_MODE2_D2 (BLOCK2)

ADC1 calibration 3





= -28 R/W (0x87)

ADC1_MODE3_D2 (BLOCK2)

ADC1 calibration 4





= -24 R/W (0x86)

ADC2_MODE0_D2 (BLOCK2)

ADC2 calibration 5





= 12 R/W (0x03)

ADC2_MODE1_D2 (BLOCK2)

ADC2 calibration 6





= 8 R/W (0x02)

ADC2_MODE2_D2 (BLOCK2)

ADC2 calibration 7





= 12 R/W (0x03)

ADC2_MODE3_D2 (BLOCK2)

ADC2 calibration 8





= 16 R/W (0x04)

(continues on next page)

Espressif Systems

1106

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)

ADC1_MODE0_D1 (BLOCK2)

ADC1 calibration 9





= -20 R/W (0b100101)

ADC1_MODE1_D1 (BLOCK2)

ADC1 calibration 10





= -12 R/W (0b100011)

ADC1_MODE2_D1 (BLOCK2)

ADC1 calibration 11





= -12 R/W (0b100011)

ADC1_MODE3_D1 (BLOCK2)

ADC1 calibration 12





= -4 R/W (0b100001)

ADC2_MODE0_D1 (BLOCK2)

ADC2 calibration 13





= -12 R/W (0b100011)

ADC2_MODE1_D1 (BLOCK2)

ADC2 calibration 14





= -8 R/W (0b100010)

ADC2_MODE2_D1 (BLOCK2)

ADC2 calibration 15





= -8 R/W (0b100010)

ADC2_MODE3_D1 (BLOCK2)

ADC2 calibration 16





= -4 R/W (0b100001)

Config fuses:

DIS_ICACHE (BLOCK0)

Disables ICache





= False R/W (0b0)

DIS_DCACHE (BLOCK0)

Disables DCache





= False R/W (0b0)

DIS_DOWNLOAD_ICACHE (BLOCK0)

Disables Icache when SoC is in

Download mode

= False R/W (0b0)

DIS_DOWNLOAD_DCACHE (BLOCK0)

Disables Dcache when SoC is in

Download mode

= False R/W (0b0)

DIS_FORCE_DOWNLOAD (BLOCK0)

Disables forcing chip into

Download mode

= False R/W (0b0)

DIS_CAN (BLOCK0)

Disables the TWAI Controller

hardware

= False R/W (0b0)

DIS_BOOT_REMAP (BLOCK0)

Disables capability to Remap RAM

to ROM address sp = False R/W (0b0)

ace

FLASH_TPUW (BLOCK0)

Configures flash startup delay

after SoC power-up, = 0 R/W (0x0)

unit is (ms/2). When the value is

15, delay is 7.

5 ms

DIS_LEGACY_SPI_BOOT (BLOCK0)

Disables Legacy SPI boot mode 



= False R/W (0b0)

UART_PRINT_CHANNEL (BLOCK0)

Selects the default UART for

printing boot msg

= UART0 R/W (0b0)

DIS_USB_DOWNLOAD_MODE (BLOCK0)

Disables use of USB in UART

download boot mode

= False R/W (0b0)

UART_PRINT_CONTROL (BLOCK0)

Sets the default UART boot

message output mode

= Enabled R/W (0b00)

FLASH_TYPE (BLOCK0)

Selects SPI flash type





= 4 data lines R/W (0b0)

FORCE_SEND_RESUME (BLOCK0)

Forces ROM code to send an SPI

flash resume comman = False R/W (0b0)

d during SPI boot

BLOCK_USR_DATA (BLOCK3)

User data

= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

00 00 00 00 00 00 00 00 R/W

Efuse fuses: WR_DIS (BLOCK0) individual eFuses RD_DIS (BLOCK0) BLOCK4-10

Disables programming of = 0 R/W (0x00000000)
Disables software reading from = 0 R/W (0b0000000)

(continues on next page)

Espressif Systems

1107

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)

Identity fuses:

BLOCK0_VERSION (BLOCK0)

BLOCK0 efuse version





= 0 R/W (0b00)

SECURE_VERSION (BLOCK0)

Secure version (used by ESP-IDF

anti-rollback feat = 0 R/W (0x0000)

ure)

MAC (BLOCK1)

Factory MAC Address

= 7c:df:a1:00:3a:6e: (OK) R/W

WAFER_VERSION (BLOCK1)

WAFER version





= A R/W (0b000)

PKG_VERSION (BLOCK1)

Package version

= ESP32-S3, QFN 7x7 56 pins R/W (0x0)

BLOCK1_VERSION (BLOCK1)

BLOCK1 efuse version





= 0 R/W (0b000)

OPTIONAL_UNIQUE_ID (BLOCK2)(0 errors): Optional unique 128-bit ID

= 7d 33 b8 bb 0b 13 b3 c8 71 37 0e e8 7c ab d5 92 R/W

BLOCK2_VERSION (BLOCK2)

Version of BLOCK2





= With calibration R/W (0b001)

CUSTOM_MAC (BLOCK3)

Custom MAC Address

= 00:00:00:00:00:00 (OK) R/W

Security fuses:

SOFT_DIS_JTAG (BLOCK0)

Software disables JTAG. When

software disabled, JT = False R/W (0b000)

AG can be activated temporarily

by HMAC peripheral

HARD_DIS_JTAG (BLOCK0)

Hardware disables JTAG

permanently

= False R/W (0b0)

DIS_DOWNLOAD_MANUAL_ENCRYPT (BLOCK0)

Disables flash encryption when

in download boot mo = False R/W (0b0)

des

SPI_BOOT_CRYPT_CNT (BLOCK0)

Enables encryption and

decryption, when an SPI boo = Disable R/W (0b000)

t mode is set. Enabled when 1 or

3 bits are set,di

sabled otherwise

SECURE_BOOT_KEY_REVOKE0 (BLOCK0)

If set, revokes use of secure

boot key digest 0 = False R/W (0b0)

SECURE_BOOT_KEY_REVOKE1 (BLOCK0)

If set, revokes use of secure

boot key digest 1 = False R/W (0b0)

SECURE_BOOT_KEY_REVOKE2 (BLOCK0)

If set, revokes use of secure

boot key digest 2 = False R/W (0b0)

KEY_PURPOSE_0 (BLOCK0)

KEY0 purpose





= USER R/W (0x0)

KEY_PURPOSE_1 (BLOCK0)

KEY1 purpose





= USER R/W (0x0)

KEY_PURPOSE_2 (BLOCK0)

KEY2 purpose





= USER R/W (0x0)

KEY_PURPOSE_3 (BLOCK0)

KEY3 purpose





= USER R/W (0x0)

KEY_PURPOSE_4 (BLOCK0)

KEY4 purpose





= USER R/W (0x0)

KEY_PURPOSE_5 (BLOCK0)

KEY5 purpose





= USER R/W (0x0)

SECURE_BOOT_EN (BLOCK0)

Enables secure boot





= False R/W (0b0)

SECURE_BOOT_AGGRESSIVE_REVOKE (BLOCK0) Enables aggressive secure boot

key revocation mode = False R/W (0b0)

DIS_DOWNLOAD_MODE (BLOCK0)

Disables all Download boot modes



= False R/W (0b0)

ENABLE_SECURITY_DOWNLOAD (BLOCK0)

Enables secure UART download

mode (read/write flas = False R/W (0b0)

(continues on next page)

Espressif Systems

1108

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)

h only)

BLOCK_KEY0 (BLOCK4)(0 errors):

Purpose: USER

Encryption key0 or user data

= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

00 00 00 00 00 00 00 00 R/W

BLOCK_KEY1 (BLOCK5)(0 errors):

Purpose: USER

Encryption key1 or user data

= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

00 00 00 00 00 00 00 00 R/W

BLOCK_KEY2 (BLOCK6)(0 errors):

Purpose: USER

Encryption key2 or user data

= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

00 00 00 00 00 00 00 00 R/W

BLOCK_KEY3 (BLOCK7)(0 errors):

Purpose: USER

Encryption key3 or user data

= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

00 00 00 00 00 00 00 00 R/W

BLOCK_KEY4 (BLOCK8)(0 errors):

Purpose: USER

Encryption key4 or user data

= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

00 00 00 00 00 00 00 00 R/W

BLOCK_KEY5 (BLOCK9)(0 errors):

Purpose: USER

Encryption key5 or user data

= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

00 00 00 00 00 00 00 00 R/W

BLOCK_SYS_DATA2 (BLOCK10)

System data (part 2)

= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

00 00 00 00 00 00 00 00 R/W

Spi_Pad_Config fuses:

SPI_PAD_CONFIG_CLK (BLOCK1)

SPI CLK pad





= 0 R/W (0b000000)

SPI_PAD_CONFIG_Q (BLOCK1)

SPI Q (D1) pad





= 0 R/W (0b000000)

SPI_PAD_CONFIG_D (BLOCK1)

SPI D (D0) pad





= 0 R/W (0b000000)

SPI_PAD_CONFIG_CS (BLOCK1)

SPI CS pad





= 0 R/W (0b000000)

SPI_PAD_CONFIG_HD (BLOCK1)

SPI HD (D3) pad





= 0 R/W (0b000000)

SPI_PAD_CONFIG_WP (BLOCK1)

SPI WP (D2) pad





= 0 R/W (0b000000)

SPI_PAD_CONFIG_DQS (BLOCK1)

SPI DQS pad





= 0 R/W (0b000000)

SPI_PAD_CONFIG_D4 (BLOCK1)

SPI D4 pad





= 0 R/W (0b000000)

SPI_PAD_CONFIG_D5 (BLOCK1)

SPI D5 pad





= 0 R/W (0b000000)

SPI_PAD_CONFIG_D6 (BLOCK1)

SPI D6 pad





= 0 R/W (0b000000)

SPI_PAD_CONFIG_D7 (BLOCK1)

SPI D7 pad





= 0 R/W (0b000000)

Usb Config fuses: DIS_USB (BLOCK0)


= False R/W (0b0)

Disables the USB OTG hardware  (continues on next page)

Espressif Systems

1109

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

USB_EXCHG_PINS (BLOCK0)



= False R/W (0b0)

EXT_PHY_ENABLE (BLOCK0)



= False R/W (0b0)

USB_FORCE_NOPERSIST (BLOCK0)



= False R/W (0b0)

(continued from previous page) Exchanges USB D+ and D- pins 

Enables external USB PHY



Forces to set USB BVALID to 1 

Vdd_Spi Config fuses:

VDD_SPI_FORCE (BLOCK0)

Force using VDD_SPI_XPD and VDD_

SPI_TIEH to config = False R/W (0b0)

ure VDD_SPI LDO

VDD_SPI_XPD (BLOCK0)

The VDD_SPI regulator is powered

on

= False R/W (0b0)

VDD_SPI_TIEH (BLOCK0)

The VDD_SPI power supply voltage

at reset

= Connect to 1.8V LDO R/W (0b0)

PIN_POWER_SELECTION (BLOCK0)

Sets default power supply for

GPIO33..37, set when = VDD3P3_CPU R/W (0b0)

SPI flash is initialized

Wdt Config fuses: WDT_DELAY_SEL (BLOCK0) threshold at startup

Selects RTC WDT timeout = 0 R/W (0b00)

Flash voltage (VDD_SPI) determined by GPIO45 on reset (GPIO45=High: VDD_ SPI pin is powered from internal 1.8V LDO GPIO45=Low or NC: VDD_SPI pin is powered directly from VDD3P3_RTC_IO via resistor Rspi. Typically this voltage is 3.3 V).

To get a dump for all eFuse registers. espefuse.py -p PORT dump

Connecting....

Detecting chip type... ESP32-S3

BLOCK0

(

) [0 ] read_regs: 00000000 00000000

00000000 00000000 00000000 00000000

MAC_SPI_8M_0 (BLOCK1

) [1 ] read_regs: a1003a6e 00007cdf

00000000 00000000 00000000 00000000

BLOCK_SYS_DATA (BLOCK2

) [2 ] read_regs: bbb8337d c8b3130b

e80e3771 92d5ab7c 8787ae10 02038687 38e50403 8628a386

BLOCK_USR_DATA (BLOCK3

) [3 ] read_regs: 00000000 00000000

00000000 00000000 00000000 00000000 00000000 00000000

BLOCK_KEY0

(BLOCK4

) [4 ] read_regs: 00000000 00000000

00000000 00000000 00000000 00000000 00000000 00000000

BLOCK_KEY1

(BLOCK5

) [5 ] read_regs: 00000000 00000000

00000000 00000000 00000000 00000000 00000000 00000000

BLOCK_KEY2

(BLOCK6

) [6 ] read_regs: 00000000 00000000

00000000 00000000 00000000 00000000 00000000 00000000

BLOCK_KEY3

(BLOCK7

) [7 ] read_regs: 00000000 00000000

00000000 00000000 00000000 00000000 00000000 00000000

BLOCK_KEY4

(BLOCK8

) [8 ] read_regs: 00000000 00000000

00000000 00000000 00000000 00000000 00000000 00000000

BLOCK_KEY5

(BLOCK9

) [9 ] read_regs: 00000000 00000000

00000000 00000000 00000000 00000000 00000000 00000000

BLOCK_SYS_DATA2 (BLOCK10

) [10] read_regs: 00000000 00000000

00000000 00000000 00000000 00000000 00000000 00000000

espefuse.py v3.1-dev

Header File · components/efuse/include/esp_efuse.h

Espressif Systems

1110

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Functions esp_err_t esp_efuse_read_field_blob(const esp_efuse_desc_t *field[], void *dst, size_t
dst_size_bits) Reads bits from EFUSE field and writes it into an array.

The number of read bits will be limited to the minimum value from the description of the bits in ofieldp structure orodst_size_bitsprequired size. Useoesp_efuse_get_field_size()pfunction to determine the length of the field.

Note Please note that reading in the batch mode does not show uncommitted changes. Return
· ESP_OK: The operation was successfully completed. · ESP_ERR_INVALID_ARG: Error in the passed arguments. Parameters · [in] field: A pointer to the structure describing the fields of efuse. · [out] dst: A pointer to array that will contain the result of reading. · [in] dst_size_bits: The number of bits required to read. If the requested number of bits
is greater than the field, the number will be limited to the field size. bool esp_efuse_read_field_bit(const esp_efuse_desc_t *field[])
Read a single bit eFuse field as a boolean value.

Note The value must exist and must be a single bit wide. If there is any possibility of an error in the provided arguments, call esp_efuse_read_field_blob() and check the returned value instead.
Note If assertions are enabled and the parameter is invalid, execution will abort Note Please note that reading in the batch mode does not show uncommitted changes. Return
· true: The field parameter is valid and the bit is set. · false: The bit is not set, or the parameter is invalid and assertions are disabled. Parameters · [in] field: A pointer to the structure describing the fields of efuse.

esp_err_t esp_efuse_read_field_cnt(const esp_efuse_desc_t *field[], size_t *out_cnt) Reads bits from EFUSE field and returns number of bits programmed as o1p.

If the bits are set not sequentially, they will still be counted.

Note Please note that reading in the batch mode does not show uncommitted changes. Return
· ESP_OK: The operation was successfully completed. · ESP_ERR_INVALID_ARG: Error in the passed arguments. Parameters · [in] field: A pointer to the structure describing the fields of efuse. · [out] out_cnt: A pointer that will contain the number of programmed as o1pbits.

esp_err_t esp_efuse_write_field_blob(const esp_efuse_desc_t *field[], const void *src, size_t

Writes array to EFUSE field.

src_size_bits)

The number of write bits will be limited to the minimum value from the description of the bits in ofieldp structure orosrc_size_bitsprequired size. Useoesp_efuse_get_field_size()pfunction to determine the length of the field. After the function is completed, the writing registers are cleared.

Return · ESP_OK: The operation was successfully completed. · ESP_ERR_INVALID_ARG: Error in the passed arguments. · ESP_ERR_EFUSE_REPEATED_PROG: Error repeated programming of programmed bits is strictly forbidden. · ESP_ERR_CODING: Error range of data does not match the coding scheme.
Parameters · [in] field: A pointer to the structure describing the fields of efuse. · [in] src: A pointer to array that contains the data for writing. · [in] src_size_bits: The number of bits required to write.

Espressif Systems

1111

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t esp_efuse_write_field_cnt(const esp_efuse_desc_t *field[], size_t cnt) Writes a required count of bits as o1pto EFUSE field.
If there are no free bits in the field to set the required number of bits to o1p, ESP_ERR_EFUSE_CNT_IS_FULL error is returned, the field will not be partially recorded. After the function is completed, the writing registers are cleared.
Return · ESP_OK: The operation was successfully completed. · ESP_ERR_INVALID_ARG: Error in the passed arguments. · ESP_ERR_EFUSE_CNT_IS_FULL: Not all requested cnt bits is set.
Parameters · [in] field: A pointer to the structure describing the fields of efuse. · [in] cnt: Required number of programmed as o1pbits.
esp_err_t esp_efuse_write_field_bit(const esp_efuse_desc_t *field[]) Write a single bit eFuse field to 1.
For use with eFuse fields that are a single bit. This function will write the bit to value 1 if it is not already set, or does nothing if the bit is already set.
This is equivalent to calling esp_efuse_write_field_cnt() with the cnt parameter equal to 1, except that it will return ESP_OK if the field is already set to 1.
Return · ESP_OK: The operation was successfully completed, or the bit was already set to value 1. · ESP_ERR_INVALID_ARG: Error in the passed arugments, including if the efuse field is not 1 bit wide.
Parameters · [in] field: Pointer to the structure describing the efuse field.
esp_err_t esp_efuse_set_write_protect(esp_efuse_block_t blk) Sets a write protection for the whole block.
After that, it is impossible to write to this block. The write protection does not apply to block 0.
Return · ESP_OK: The operation was successfully completed. · ESP_ERR_INVALID_ARG: Error in the passed arguments. · ESP_ERR_EFUSE_CNT_IS_FULL: Not all requested cnt bits is set. · ESP_ERR_NOT_SUPPORTED: The block does not support this command.
Parameters · [in] blk: Block number of eFuse. (EFUSE_BLK1, EFUSE_BLK2 and EFUSE_BLK3)
esp_err_t esp_efuse_set_read_protect(esp_efuse_block_t blk) Sets a read protection for the whole block.
After that, it is impossible to read from this block. The read protection does not apply to block 0.
Return · ESP_OK: The operation was successfully completed. · ESP_ERR_INVALID_ARG: Error in the passed arguments. · ESP_ERR_EFUSE_CNT_IS_FULL: Not all requested cnt bits is set. · ESP_ERR_NOT_SUPPORTED: The block does not support this command.
Parameters · [in] blk: Block number of eFuse. (EFUSE_BLK1, EFUSE_BLK2 and EFUSE_BLK3)
int esp_efuse_get_field_size(const esp_efuse_desc_t *field[]) Returns the number of bits used by field.
Return Returns the number of bits used by field. Parameters
· [in] field: A pointer to the structure describing the fields of efuse.
uint32_t esp_efuse_read_reg(esp_efuse_block_t blk, unsigned int num_reg) Returns value of efuse register.

Espressif Systems

1112

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

This is a thread-safe implementation. Example: EFUSE_BLK2_RDATA3_REG where (blk=2, num_reg=3)

Note Please note that reading in the batch mode does not show uncommitted changes. Return Value of register Parameters
· [in] blk: Block number of eFuse. · [in] num_reg: The register number in the block.

esp_err_t esp_efuse_write_reg(esp_efuse_block_t blk, unsigned int num_reg, uint32_t val) Write value to efuse register.

Apply a coding scheme if necessary. This is a thread-safe implementation. EFUSE_BLK3_WDATA0_REG where (blk=3, num_reg=0)

Example:

Return · ESP_OK: The operation was successfully completed. · ESP_ERR_EFUSE_REPEATED_PROG: Error repeated programming of programmed bits is strictly forbidden.
Parameters · [in] blk: Block number of eFuse. · [in] num_reg: The register number in the block. · [in] val: Value to write.

esp_efuse_coding_scheme_t esp_efuse_get_coding_scheme(esp_efuse_block_t blk) Return efuse coding scheme for blocks.

Note: The coding scheme is applicable only to 1, 2 and 3 blocks. For 0 block, the coding scheme is always NONE.

Return Return efuse coding scheme for blocks Parameters
· [in] blk: Block number of eFuse.

esp_err_t esp_efuse_read_block(esp_efuse_block_t blk, void *dst_key, size_t offset_in_bits, size_t size_bits)
Read key to efuse block starting at the offset and the required size.

Note Please note that reading in the batch mode does not show uncommitted changes. Return
· ESP_OK: The operation was successfully completed. · ESP_ERR_INVALID_ARG: Error in the passed arguments. · ESP_ERR_CODING: Error range of data does not match the coding scheme. Parameters · [in] blk: Block number of eFuse. · [in] dst_key: A pointer to array that will contain the result of reading. · [in] offset_in_bits: Start bit in block. · [in] size_bits: The number of bits required to read.

esp_err_t esp_efuse_write_block(esp_efuse_block_t blk, const void *src_key, size_t offset_in_bits, size_t size_bits)
Write key to efuse block starting at the offset and the required size.

Return · ESP_OK: The operation was successfully completed. · ESP_ERR_INVALID_ARG: Error in the passed arguments. · ESP_ERR_CODING: Error range of data does not match the coding scheme. · ESP_ERR_EFUSE_REPEATED_PROG: Error repeated programming of programmed bits
Parameters · [in] blk: Block number of eFuse. · [in] src_key: A pointer to array that contains the key for writing. · [in] offset_in_bits: Start bit in block. · [in] size_bits: The number of bits required to write.

uint8_t esp_efuse_get_chip_ver(void) Returns chip version from efuse.

Espressif Systems

1113

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return chip version
uint32_t esp_efuse_get_pkg_ver(void) Returns chip package from efuse.
Return chip package
void esp_efuse_reset(void) Reset efuse write registers.
Efuse write registers are written to zero, to negate any changes that have been staged here.
Note This function is not threadsafe, if calling code updates efuse values from multiple tasks then this is callern s responsibility to serialise.
esp_err_t esp_efuse_disable_rom_download_mode(void) Disable ROM Download Mode via eFuse.
Permanently disables the ROM Download Mode feature. Once disabled, if the SoC is booted with strapping pins set for ROM Download Mode then an error is printed instead.
Note Not all SoCs support this option. An error will be returned if called on an ESP32 with a silicon revision lower than 3, as these revisions do not support this option.
Note If ROM Download Mode is already disabled, this function does nothing and returns success. Return
· ESP_OK If the eFuse was successfully burned, or had already been burned. · ESP_ERR_NOT_SUPPORTED (ESP32 only) This SoC is not capable of disabling UART down-
load mode · ESP_ERR_INVALID_STATE (ESP32 only) This eFuse is write protected and cannot be written
esp_err_t esp_efuse_set_rom_log_scheme(esp_efuse_rom_log_scheme_t log_scheme) Set boot ROM log scheme via eFuse.
Note By default, the boot ROM will always print to console. This API can be called to set the log scheme only once per chip, once the value is changed from the default it cannt be changed again.
Return · ESP_OK If the eFuse was successfully burned, or had already been burned. · ESP_ERR_NOT_SUPPORTED (ESP32 only) This SoC is not capable of setting ROM log scheme · ESP_ERR_INVALID_STATE This eFuse is write protected or has been burned already
Parameters · log_scheme: Supported ROM log scheme
esp_err_t esp_efuse_enable_rom_secure_download_mode(void) Switch ROM Download Mode to Secure Download mode via eFuse.
Permanently enables Secure Download mode. This mode limits the use of ROM Download Mode functions to simple flash read, write and erase operations, plus a command to return a summary of currently enabled security features.
Note If Secure Download mode is already enabled, this function does nothing and returns success. Note Disabling the ROM Download Mode also disables Secure Download Mode. Return
· ESP_OK If the eFuse was successfully burned, or had already been burned. · ESP_ERR_INVALID_STATE ROM Download Mode has been disabled via eFuse, so Secure
Download mode is unavailable.
uint32_t esp_efuse_read_secure_version(void) Return secure_version from efuse field.
Return Secure version from efuse field
bool esp_efuse_check_secure_version(uint32_t secure_version) Check secure_version from app and secure_version and from efuse field.
Return · True: If version of app is equal or more then secure_version from efuse.
Parameters

Espressif Systems

1114

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· secure_version: Secure version from app.
esp_err_t esp_efuse_update_secure_version(uint32_t secure_version) Write efuse field by secure_version value.
Update the secure_version value is available if the coding scheme is None. Note: Do not use this function in your applications. This function is called as part of the other API.
Return · ESP_OK: Successful. · ESP_FAIL: secure version of app cannot be set to efuse field. · ESP_ERR_NOT_SUPPORTED: Anti rollback is not supported with the 3/4 and Repeat coding scheme.
Parameters · [in] secure_version: Secure version from app.
esp_err_t esp_efuse_batch_write_begin(void) Set the batch mode of writing fields.
This mode allows you to write the fields in the batch mode when need to burn several efuses at one time. To enable batch mode call begin() then perform as usually the necessary operations read and write and at the end call commit() to actually burn all written efuses. The batch mode can be used nested. The commit will be done by the last commit() function. The number of begin() functions should be equal to the number of commit() functions.
Note: If batch mode is enabled by the first task, at this time the second task cannot write/read efuses. The second task will wait for the first task to complete the batch operation.
Note Please note that reading in the batch mode does not show uncommitted changes.
// Example of using the batch writing mode.
// set the batch writing mode esp_efuse_batch_write_begin();
// use any writing functions as usual esp_efuse_write_field_blob(ESP_EFUSE_...); esp_efuse_write_field_cnt(ESP_EFUSE_...); esp_efuse_set_write_protect(EFUSE_BLKx); esp_efuse_write_reg(EFUSE_BLKx, ...); esp_efuse_write_block(EFUSE_BLKx, ...); esp_efuse_write(ESP_EFUSE_1, 3); // ESP_EFUSE_1 == 1, here we write a new value = 3. The changes will be burn by the commit() function. esp_efuse_read_...(ESP_EFUSE_1); // this function returns ESP_EFUSE_1 == 1 because uncommitted changes are not readable, it will be available only after commit. ...
// esp_efuse_batch_write APIs can be called recursively. esp_efuse_batch_write_begin(); esp_efuse_set_write_protect(EFUSE_BLKx); esp_efuse_batch_write_commit(); // the burn will be skipped here, it will be done in the last commit().
...
// Write all of these fields to the efuse registers esp_efuse_batch_write_commit(); esp_efuse_read_...(ESP_EFUSE_1); // this function returns ESP_EFUSE_1 == 3.
Return · ESP_OK: Successful.
esp_err_t esp_efuse_batch_write_cancel(void) Reset the batch mode of writing fields.

Espressif Systems

1115

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

It will reset the batch writing mode and any written changes.
Return · ESP_OK: Successful. · ESP_ERR_INVALID_STATE: Tha batch mode was not set.
esp_err_t esp_efuse_batch_write_commit(void) Writes all prepared data for the batch mode.
Must be called to ensure changes are written to the efuse registers. After this the batch writing mode will be reset.
Return · ESP_OK: Successful. · ESP_ERR_INVALID_STATE: The deferred writing mode was not set.
bool esp_efuse_block_is_empty(esp_efuse_block_t block) Checks that the given block is empty.
Return · True: The block is empty. · False: The block is not empty or was an error.
bool esp_efuse_get_key_dis_read(esp_efuse_block_t block) Returns a read protection for the key block.
Return True: The key block is read protected False: The key block is readable. Parameters
· [in] block: A key block in the range EFUSE_BLK_KEY0..EFUSE_BLK_KEY_MAX
esp_err_t esp_efuse_set_key_dis_read(esp_efuse_block_t block) Sets a read protection for the key block.
Return · ESP_OK: Successful. · ESP_ERR_INVALID_ARG: Error in the passed arguments. · ESP_ERR_EFUSE_REPEATED_PROG: Error repeated programming of programmed bits is strictly forbidden. · ESP_ERR_CODING: Error range of data does not match the coding scheme.
Parameters · [in] block: A key block in the range EFUSE_BLK_KEY0..EFUSE_BLK_KEY_MAX
bool esp_efuse_get_key_dis_write(esp_efuse_block_t block) Returns a write protection for the key block.
Return True: The key block is write protected False: The key block is writeable. Parameters
· [in] block: A key block in the range EFUSE_BLK_KEY0..EFUSE_BLK_KEY_MAX
esp_err_t esp_efuse_set_key_dis_write(esp_efuse_block_t block) Sets a write protection for the key block.
Return · ESP_OK: Successful. · ESP_ERR_INVALID_ARG: Error in the passed arguments. · ESP_ERR_EFUSE_REPEATED_PROG: Error repeated programming of programmed bits is strictly forbidden. · ESP_ERR_CODING: Error range of data does not match the coding scheme.
Parameters · [in] block: A key block in the range EFUSE_BLK_KEY0..EFUSE_BLK_KEY_MAX
bool esp_efuse_key_block_unused(esp_efuse_block_t block) Returns true if the key block is unused, false otherwise.
An unused key block is all zero content, not read or write protected, and has purpose 0 (ESP_EFUSE_KEY_PURPOSE_USER)

Espressif Systems

1116

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return · True if key block is unused, · False if key block is used or the specified block index is not a key block.
Parameters · block: key block to check.
bool esp_efuse_find_purpose(esp_efuse_purpose_t purpose, esp_efuse_block_t *block) Find a key block with the particular purpose set.
Return · True: If found, · False: If not found (value at block pointer is unchanged).
Parameters · [in] purpose: Purpose to search for. · [out] block: Pointer in the range EFUSE_BLK_KEY0..EFUSE_BLK_KEY_MAX which will be set to the key block if found. Can be NULL, if only need to test the key block exists.
bool esp_efuse_get_keypurpose_dis_write(esp_efuse_block_t block) Returns a write protection of the key purpose field for an efuse key block.
Note For ESP32: no keypurpose, it returns always True. Return True: The key purpose is write protected. False: The key purpose is writeable. Parameters
· [in] block: A key block in the range EFUSE_BLK_KEY0..EFUSE_BLK_KEY_MAX
esp_efuse_purpose_t esp_efuse_get_key_purpose(esp_efuse_block_t block) Returns the current purpose set for an efuse key block.
Return · Value: If Successful, it returns the value of the purpose related to the given key block. · ESP_EFUSE_KEY_PURPOSE_MAX: Otherwise.
Parameters · [in] block: A key block in the range EFUSE_BLK_KEY0..EFUSE_BLK_KEY_MAX
const esp_efuse_desc_t **esp_efuse_get_purpose_field(esp_efuse_block_t block) Returns a pointer to a key purpose for an efuse key block.
To get the value of this field use esp_efuse_read_field_blob() or esp_efuse_get_key_purpose().
Parameters · [in] block: A key block in the range EFUSE_BLK_KEY0..EFUSE_BLK_KEY_MAX
Return Pointer: If Successful returns a pointer to the corresponding efuse field otherwise NULL.
const esp_efuse_desc_t **esp_efuse_get_key(esp_efuse_block_t block) Returns a pointer to a key block.
Return Pointer: If Successful returns a pointer to the corresponding efuse field otherwise NULL. Parameters
· [in] block: A key block in the range EFUSE_BLK_KEY0..EFUSE_BLK_KEY_MAX
esp_err_t esp_efuse_set_key_purpose(esp_efuse_block_t block, esp_efuse_purpose_t purpose) Sets a key purpose for an efuse key block.
Return · ESP_OK: Successful. · ESP_ERR_INVALID_ARG: Error in the passed arguments. · ESP_ERR_EFUSE_REPEATED_PROG: Error repeated programming of programmed bits is strictly forbidden. · ESP_ERR_CODING: Error range of data does not match the coding scheme.
Parameters · [in] block: A key block in the range EFUSE_BLK_KEY0..EFUSE_BLK_KEY_MAX · [in] purpose: Key purpose.
esp_err_t esp_efuse_set_keypurpose_dis_write(esp_efuse_block_t block) Sets a write protection of the key purpose field for an efuse key block.

Espressif Systems

1117

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return · ESP_OK: Successful. · ESP_ERR_INVALID_ARG: Error in the passed arguments. · ESP_ERR_EFUSE_REPEATED_PROG: Error repeated programming of programmed bits is strictly forbidden. · ESP_ERR_CODING: Error range of data does not match the coding scheme.
Parameters · [in] block: A key block in the range EFUSE_BLK_KEY0..EFUSE_BLK_KEY_MAX
esp_efuse_block_t esp_efuse_find_unused_key_block(void) Search for an unused key block and return the first one found.
See esp_efuse_key_block_unused for a description of an unused key block.
Return First unused key block, or EFUSE_BLK_KEY_MAX if no unused key block is found.
unsigned esp_efuse_count_unused_key_blocks(void) Return the number of unused efuse key blocks in the range EFUSE_BLK_KEY0..EFUSE_BLK_KEY_MAX.
bool esp_efuse_get_digest_revoke(unsigned num_digest) Returns the status of the Secure Boot public key digest revocation bit.
Return · True: If key digest is revoked, · False; If key digest is not revoked.
Parameters · [in] num_digest: The number of digest in range 0..2
esp_err_t esp_efuse_set_digest_revoke(unsigned num_digest) Sets the Secure Boot public key digest revocation bit.
Return · ESP_OK: Successful. · ESP_ERR_INVALID_ARG: Error in the passed arguments. · ESP_ERR_EFUSE_REPEATED_PROG: Error repeated programming of programmed bits is strictly forbidden. · ESP_ERR_CODING: Error range of data does not match the coding scheme.
Parameters · [in] num_digest: The number of digest in range 0..2
bool esp_efuse_get_write_protect_of_digest_revoke(unsigned num_digest) Returns a write protection of the Secure Boot public key digest revocation bit.
Return True: The revocation bit is write protected. False: The revocation bit is writeable. Parameters
· [in] num_digest: The number of digest in range 0..2
esp_err_t esp_efuse_set_write_protect_of_digest_revoke(unsigned num_digest) Sets a write protection of the Secure Boot public key digest revocation bit.
Return · ESP_OK: Successful. · ESP_ERR_INVALID_ARG: Error in the passed arguments. · ESP_ERR_EFUSE_REPEATED_PROG: Error repeated programming of programmed bits is strictly forbidden. · ESP_ERR_CODING: Error range of data does not match the coding scheme.
Parameters · [in] num_digest: The number of digest in range 0..2
esp_err_t esp_efuse_write_key(esp_efuse_block_t block, esp_efuse_purpose_t purpose, const void *key, size_t key_size_bytes)
Program a block of key data to an efuse block.
The burn of a key, protection bits, and a purpose happens in batch mode.
Return

Espressif Systems

1118

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_OK: Successful. · ESP_ERR_INVALID_ARG: Error in the passed arguments. · ESP_ERR_INVALID_STATE: Error in efuses state, unused block not found. · ESP_ERR_EFUSE_REPEATED_PROG: Error repeated programming of programmed bits is
strictly forbidden. · ESP_ERR_CODING: Error range of data does not match the coding scheme. Parameters · [in] block: Block to read purpose for. Must be in range EFUSE_BLK_KEY0 to
EFUSE_BLK_KEY_MAX. Key block must be unused (esp_efuse_key_block_unused). · [in] purpose: Purpose to set for this key. Purpose must be already unset. · [in] key: Pointer to data to write. · [in] key_size_bytes: Bytes length of data to write.
esp_err_t esp_efuse_write_keys(const esp_efuse_purpose_t purposes[], uint8_t keys[][32], unsigned number_of_keys)
Program keys to unused efuse blocks.
The burn of keys, protection bits, and purposes happens in batch mode.
Return · ESP_OK: Successful. · ESP_ERR_INVALID_ARG: Error in the passed arguments. · ESP_ERR_INVALID_STATE: Error in efuses state, unused block not found. · ESP_ERR_NOT_ENOUGH_UNUSED_KEY_BLOCKS: Error not enough unused key blocks available · ESP_ERR_EFUSE_REPEATED_PROG: Error repeated programming of programmed bits is strictly forbidden. · ESP_ERR_CODING: Error range of data does not match the coding scheme.
Parameters · [in] purposes: Array of purposes (purpose[number_of_keys]). · [in] keys: Array of keys (uint8_t keys[number_of_keys][32]). Each key is 32 bytes long. · [in] number_of_keys: The number of keys to write (up to 6 keys).
esp_err_t esp_secure_boot_read_key_digests(ets_secure_boot_key_digests_t *trusted_keys) Read key digests from efuse. Any revoked/missing digests will be marked as NULL.
Return · ESP_OK: Successful. · ESP_FAIL: If trusted_keys is NULL or there is no valid digest.
Parameters · [out] trusted_keys: The number of digest in range 0..2

Structures struct esp_efuse_desc_t
Type definition for an eFuse field.

Public Members
esp_efuse_block_t efuse_block : 8 Block of eFuse
uint8_t bit_start Start bit [0..255]
uint16_t bit_count Length of bit field [1..-]

Macros ESP_ERR_EFUSE
Base error code for efuse api.

Espressif Systems

1119

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_OK_EFUSE_CNT OK the required number of bits is set.
ESP_ERR_EFUSE_CNT_IS_FULL Error field is full.
ESP_ERR_EFUSE_REPEATED_PROG Error repeated programming of programmed bits is strictly forbidden.
ESP_ERR_CODING Error while a encoding operation.
ESP_ERR_NOT_ENOUGH_UNUSED_KEY_BLOCKS Error not enough unused key blocks available
ESP_ERR_DAMAGED_READING Error. Burn or reset was done during a reading operation leads to damage read data. This error is internal to the efuse component and not returned by any public API.

Enumerations enum esp_efuse_rom_log_scheme_t
Type definition for ROM log scheme.
Values:
ESP_EFUSE_ROM_LOG_ALWAYS_ON Always enable ROM logging
ESP_EFUSE_ROM_LOG_ON_GPIO_LOW ROM logging is enabled when specific GPIO level is low during start up
ESP_EFUSE_ROM_LOG_ON_GPIO_HIGH ROM logging is enabled when specific GPIO level is high during start up
ESP_EFUSE_ROM_LOG_ALWAYS_OFF Disable ROM logging permanently

2.7.6 Error Codes and Helper Functions
This section lists definitions of common ESP-IDF error codes and several helper functions related to error handling. For general information about error codes in ESP-IDF, see Error Handling. For the full list of error codes defined in ESP-IDF, see Error Code Reference.

API Reference
Header File · components/esp_common/include/esp_err.h

Functions const char *esp_err_to_name(esp_err_t code)
Returns string for esp_err_t error codes.
This function finds the error code in a pre-generated lookup-table and returns its string representation.
The function is generated by the Python script tools/gen_esp_err_to_name.py which should be run each time an esp_err_t error is modified, created or removed from the IDF project.
Return string error message Parameters
· code: esp_err_t error code

Espressif Systems

1120

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

const char *esp_err_to_name_r(esp_err_t code, char *buf, size_t buflen) Returns string for esp_err_t and system error codes.
This function finds the error code in a pre-generated lookup-table of esp_err_t errors and returns its string representation. If the error code is not found then it is attempted to be found among system errors.
The function is generated by the Python script tools/gen_esp_err_to_name.py which should be run each time an esp_err_t error is modified, created or removed from the IDF project.
Return buf containing the string error message Parameters
· code: esp_err_t error code · [out] buf: buffer where the error message should be written · buflen: Size of buffer buf. At most buflen bytes are written into the buf buffer (including the
terminating null byte).
Macros ESP_OK
esp_err_t value indicating success (no error) ESP_FAIL
Generic esp_err_t code indicating failure
ESP_ERR_NO_MEM Out of memory
ESP_ERR_INVALID_ARG Invalid argument
ESP_ERR_INVALID_STATE Invalid state
ESP_ERR_INVALID_SIZE Invalid size
ESP_ERR_NOT_FOUND Requested resource not found
ESP_ERR_NOT_SUPPORTED Operation or feature not supported
ESP_ERR_TIMEOUT Operation timed out
ESP_ERR_INVALID_RESPONSE Received response was invalid
ESP_ERR_INVALID_CRC CRC or checksum was invalid
ESP_ERR_INVALID_VERSION Version was invalid
ESP_ERR_INVALID_MAC MAC address was invalid
ESP_ERR_NOT_FINISHED There are items remained to retrieve
ESP_ERR_WIFI_BASE Starting number of WiFi error codes
ESP_ERR_MESH_BASE Starting number of MESH error codes
ESP_ERR_FLASH_BASE Starting number of flash error codes

Espressif Systems

1121

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_ERR_HW_CRYPTO_BASE Starting number of HW cryptography module error codes
ESP_ERR_MEMPROT_BASE Starting number of Memory Protection API error codes
ESP_ERROR_CHECK(x) Macro which can be used to check the error code, and terminate the program in case the code is not ESP_OK. Prints the error code, error location, and the failed statement to serial output.
Disabled if assertions are disabled.
ESP_ERROR_CHECK_WITHOUT_ABORT(x) Macro which can be used to check the error code. Prints the error code, error location, and the failed statement to serial output. In comparison with ESP_ERROR_CHECK(), this prints the same error message but isnnt terminating the program.
Type Definitions typedef int esp_err_t
2.7.7 ESP HTTPS OTA
Overview
esp_https_ota provides simplified APIs to perform firmware upgrades over HTTPS. Itns an abstraction layer over existing OTA APIs.
Application Example
esp_err_t do_firmware_upgrade() {
esp_http_client_config_t config = { .url = CONFIG_FIRMWARE_UPGRADE_URL, .cert_pem = (char *)server_cert_pem_start,
}; esp_err_t ret = esp_https_ota(&config); if (ret == ESP_OK) {
esp_restart(); } else {
return ESP_FAIL; } return ESP_OK; }

Partial Image Download over HTTPS
To use partial image download feature, enable partial_http_download configuration in esp_https_ota_config_t. When this configuration is enabled, firmware image will be downloaded in multiple HTTP requests of specified size. Maximum content length of each request can be specified by setting max_http_request_size to required value.
This option is useful while fetching image from a service like AWS S3, where mbedTLS Rx buffer size (CONFIG_MBEDTLS_SSL_IN_CONTENT_LEN) can be set to lower value which is not possible without enabling this configuration.
Default value of mbedTLS Rx buffer size is set to 16K. By using partial_http_download with max_http_request_size of 4K, size of mbedTLS Rx buffer can be reduced to 4K. With this configuration, memory saving of around 12K is expected.

Espressif Systems

1122

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Signature Verification
For additional security, signature of OTA firmware images can be verified. For that, refer Secure OTA Updates Without Secure boot
API Reference
Header File
· components/esp_https_ota/include/esp_https_ota.h
Functions esp_err_t esp_https_ota(const esp_http_client_config_t *config)
HTTPS OTA Firmware upgrade.
This function allocates HTTPS OTA Firmware upgrade context, establishes HTTPS connection, reads image data from HTTP stream and writes it to OTA partition and finishes HTTPS OTA Firmware upgrade operation. This API supports URL redirection, but if CA cert of URLs differ then it should be appended to cert_pem member of config.
Note This API handles the entire OTA operation, so if this API is being used then no other APIs from esp_https_ota component should be called. If more information and control is needed during the HTTPS OTA process, then one can use esp_https_ota_begin and subsequent APIs. If this API returns successfully, esp_restart() must be called to boot from the new firmware image.
Return · ESP_OK: OTA data updated, next reboot will use specified partition. · ESP_FAIL: For generic failure. · ESP_ERR_INVALID_ARG: Invalid argument · ESP_ERR_OTA_VALIDATE_FAILED: Invalid app image · ESP_ERR_NO_MEM: Cannot allocate memory for OTA operation. · ESP_ERR_FLASH_OP_TIMEOUT or ESP_ERR_FLASH_OP_FAIL: Flash write failed. · For other return codes, refer OTA documentation in esp-idfns app_update component.
Parameters · [in] config: pointer to esp_http_client_config_t structure.
esp_err_t esp_https_ota_begin(esp_https_ota_config_t *ota_config, esp_https_ota_handle_t *handle)
Start HTTPS OTA Firmware upgrade.
This function initializes ESP HTTPS OTA context and establishes HTTPS connection. This function must be invoked first. If this function returns successfully, then esp_https_ota_perform should be called to continue with the OTA process and there should be a call to esp_https_ota_finish on completion of OTA operation or on failure in subsequent operations. This API supports URL redirection, but if CA cert of URLs differ then it should be appended to cert_pem member of http_config, which is a part of ota_config. In case of error, this API explicitly sets handle to NULL.
Note This API is blocking, so setting is_async member of http_config structure will result in an error. Return
· ESP_OK: HTTPS OTA Firmware upgrade context initialised and HTTPS connection established · ESP_FAIL: For generic failure. · ESP_ERR_INVALID_ARG: Invalid argument (missing/incorrect config, certificate, etc.) · For other return codes, refer documentation in app_update component and esp_http_client compo-
nent in esp-idf. Parameters
· [in] ota_config: pointer to esp_https_ota_config_t structure · [out] handle: pointer to an allocated data of type esp_https_ota_handle_t which will
be initialised in this function
esp_err_t esp_https_ota_perform(esp_https_ota_handle_t https_ota_handle) Read image data from HTTP stream and write it to OTA partition.

Espressif Systems

1123

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

This function reads image data from HTTP stream and writes it to OTA partition. This function must be called only if esp_https_ota_begin() returns successfully. This function must be called in a loop since it returns after every HTTP read operation thus giving you the flexibility to stop OTA operation midway.
Return · ESP_ERR_HTTPS_OTA_IN_PROGRESS: OTA update is in progress, call this API again to continue. · ESP_OK: OTA update was successful · ESP_FAIL: OTA update failed · ESP_ERR_INVALID_ARG: Invalid argument · ESP_ERR_OTA_VALIDATE_FAILED: Invalid app image · ESP_ERR_NO_MEM: Cannot allocate memory for OTA operation. · ESP_ERR_FLASH_OP_TIMEOUT or ESP_ERR_FLASH_OP_FAIL: Flash write failed. · For other return codes, refer OTA documentation in esp-idfns app_update component.
Parameters · [in] https_ota_handle: pointer to esp_https_ota_handle_t structure
bool esp_https_ota_is_complete_data_received(esp_https_ota_handle_t https_ota_handle) Checks if complete data was received or not.
Note This API can be called just before esp_https_ota_finish() to validate if the complete image was indeed received.
Return · false · true
Parameters · [in] https_ota_handle: pointer to esp_https_ota_handle_t structure
esp_err_t esp_https_ota_finish(esp_https_ota_handle_t https_ota_handle) Clean-up HTTPS OTA Firmware upgrade and close HTTPS connection.
This function closes the HTTP connection and frees the ESP HTTPS OTA context. This function switches the boot partition to the OTA partition containing the new firmware image.
Note If this API returns successfully, esp_restart() must be called to boot from the new firmware image esp_https_ota_finish should not be called after calling esp_https_ota_abort
Return · ESP_OK: Clean-up successful · ESP_ERR_INVALID_STATE · ESP_ERR_INVALID_ARG: Invalid argument · ESP_ERR_OTA_VALIDATE_FAILED: Invalid app image
Parameters · [in] https_ota_handle: pointer to esp_https_ota_handle_t structure
esp_err_t esp_https_ota_abort(esp_https_ota_handle_t https_ota_handle) Clean-up HTTPS OTA Firmware upgrade and close HTTPS connection.
This function closes the HTTP connection and frees the ESP HTTPS OTA context.
Note esp_https_ota_abort should not be called after calling esp_https_ota_finish Return
· ESP_OK: Clean-up successful · ESP_ERR_INVALID_STATE: Invalid ESP HTTPS OTA state · ESP_FAIL: OTA not started · ESP_ERR_NOT_FOUND: OTA handle not found · ESP_ERR_INVALID_ARG: Invalid argument Parameters · [in] https_ota_handle: pointer to esp_https_ota_handle_t structure
esp_err_t esp_https_ota_get_img_desc(esp_https_ota_handle_t https_ota_handle, esp_app_desc_t *new_app_info)
Reads app description from image header. The app description provides information like the oFirmware versionpof the image.

Espressif Systems

1124

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Note This API can be called only after esp_https_ota_begin() and before esp_https_ota_perform(). Calling this API is not mandatory.
Return · ESP_ERR_INVALID_ARG: Invalid arguments · ESP_FAIL: Failed to read image descriptor · ESP_OK: Successfully read image descriptor
Parameters · [in] https_ota_handle: pointer to esp_https_ota_handle_t structure · [out] new_app_info: pointer to an allocated esp_app_desc_t structure
int esp_https_ota_get_image_len_read(esp_https_ota_handle_t https_ota_handle) This function returns OTA image data read so far.
Note This API should be called only if esp_https_ota_perform() has been called atleast once or if esp_https_ota_get_img_desc has been called before.
Return · -1 On failure · total bytes read so far
Parameters · [in] https_ota_handle: pointer to esp_https_ota_handle_t structure
int esp_https_ota_get_image_size(esp_https_ota_handle_t https_ota_handle) This function returns OTA image total size.
Note This API should be called after esp_https_ota_begin() has been already called. This can be used to create some sort of progress indication (in combination with esp_https_ota_get_image_len_read())
Return · -1 On failure or chunked encoding · total bytes of image
Parameters · [in] https_ota_handle: pointer to esp_https_ota_handle_t structure
Structures struct esp_https_ota_config_t
ESP HTTPS OTA configuration.
Public Members
const esp_http_client_config_t *http_config ESP HTTP client configuration
http_client_init_cb_t http_client_init_cb Callback after ESP HTTP client is initialised
bool bulk_flash_erase Erase entire flash partition during initialization. By default flash partition is erased during write operation and in chunk of 4K sector size
bool partial_http_download Enable Firmware image to be downloaded over multiple HTTP requests
int max_http_request_size Maximum request size for partial HTTP download
Macros ESP_ERR_HTTPS_OTA_BASE ESP_ERR_HTTPS_OTA_IN_PROGRESS

Espressif Systems

1125

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Type Definitions typedef void *esp_https_ota_handle_t typedef esp_err_t (*http_client_init_cb_t)(esp_http_client_handle_t)
2.7.8 POSIX Threads Support
Overview
ESP-IDF is based on FreeRTOS but offers a range of POSIX-compatible APIs that allow easy porting of third party code. This includes support for common parts of the POSIX Threads opthreadspAPI. POSIX Threads are implemented in ESP-IDF as wrappers around equivalent FreeRTOS features. The runtime memory or performance overhead of using the pthreads API is quite low, but not every feature available in either pthreads or FreeRTOS is available via the ESP-IDF pthreads support. Pthreads can be used in ESP-IDF by including standard pthread.h header, which is included in the toolchain libc. An additional ESP-IDF specific header, esp_pthread.h, provides additional non-POSIX APIs for using some ESP-IDF features with pthreads. C++ Standard Library implementations for std::thread, std::mutex, std::condition_variable, etc. are implemented using pthreads (via GCC libstdc++). Therefore, restrictions mentioned here also apply to the equivalent C++ standard library functionality.
RTOS Integration
Unlike many operating systems using POSIX Threads, ESP-IDF is a real-time operating system with a real-time scheduler. This means that a thread will only stop running if a higher priority task is ready to run, the thread blocks on an OS synchronization structure like a mutex, or the thread calls any of the functions sleep, vTaskDelay(), or usleep.
Note: If calling a standard libc or C++ sleep function, such as usleep defined in unistd.h, then the task will only block and yield the CPU if the sleep time is longer than one FreeRTOS tick period. If the time is shorter, the thread will busy-wait instead of yielding to another RTOS task.
By default, all POSIX Threads have the same RTOS priority, but it is possible to change this by calling a custom API.
Standard features
The following standard APIs are implemented in ESP-IDF. Refer to standard POSIX Threads documentation, or pthread.h, for details about the standard arguments and behaviour of each function. Differences or limitations compared to the standard APIs are noted below.
Thread APIs · pthread_create() - The attr argument is supported for setting stack size and detach state only. Other attribute fields are ignored. - Unlike FreeRTOS task functions, the start_routine function is allowed to return. A odetachedptype thread is automatically deleted if the function returns. The default ojoinablep type thread will be suspended until pthread_join() is called on it. · pthread_join() · pthread_detach() · pthread_exit() · sched_yield() · pthread_self() - An assert will fail if this function is called from a FreeRTOS task which is not a pthread. · pthread_equal()

Espressif Systems

1126

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Thread Attributes · pthread_attr_init() · pthread_attr_destroy() - This function doesnnt need to free any resources and instead resets the attr structure to defaults (implementation is same as pthread_attr_init()). · pthread_attr_getstacksize() / pthread_attr_setstacksize() · pthread_attr_getdetachstate() / pthread_attr_setdetachstate()
Once · pthread_once()
Static initializer constant PTHREAD_ONCE_INIT is supported.
Note: This function can be called from tasks created using either pthread or FreeRTOS APIs

Mutexes POSIX Mutexes are implemented as FreeRTOS Mutex Semaphores (normal type for ofastpor oerror checkpmutexes, and Recursive type fororecursivepmutexes). This means that they have the same priority inheritance behaviour as mutexes created with xSemaphoreCreateMutex().
· pthread_mutex_init() · pthread_mutex_destroy() · pthread_mutex_lock() · pthread_mutex_timedlock() · pthread_mutex_trylock() · pthread_mutex_unlock() · pthread_mutexattr_init() · pthread_mutexattr_destroy() · pthread_mutexattr_gettype() / pthread_mutexattr_settype()
Static initializer constant PTHREAD_MUTEX_INITIALIZER is supported, but the non-standard static initializer constants for other mutex types are not supported.
Note: These functions can be called from tasks created using either pthread or FreeRTOS APIs

Condition Variables
· pthread_cond_init() - The attr argument is not implemented and is ignored. · pthread_cond_destroy() · pthread_cond_signal() · pthread_cond_broadcast() · pthread_cond_wait() · pthread_cond_timedwait()
Static initializer constant PTHREAD_COND_INITIALIZER is supported.
· The resolution of pthread_cond_timedwait() timeouts is the RTOS tick period (see CONFIG_FREERTOS_HZ). Timeouts may be delayed up to one tick period after the requested timeout.
Note: These functions can be called from tasks created using either pthread or FreeRTOS APIs

Read/Write Locks
· pthread_rwlock_init() - The attr argument is not implemented and is ignored. · pthread_rwlock_destroy()

Espressif Systems

1127

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· pthread_rwlock_rdlock() · pthread_rwlock_wrlock() · pthread_rwlock_unlock() Static initializer constant PTHREAD_RWLOCK_INITIALIZER is supported.
Note: These functions can be called from tasks created using either pthread or FreeRTOS APIs

Thread-Specific Data · pthread_key_create() - The destr_function argument is supported and will be called if a thread function exits normally, calls pthread_exit(), or if the underlying task is deleted directly using the FreeRTOS function vTaskDelete(). · pthread_key_delete() · pthread_setspecific() / pthread_getspecific()
Note: These functions can be called from tasks created using either pthread or FreeRTOS APIs
Note: There are other options for thread local storage in ESP-IDF, including options with higher performance. See Thread Local Storage.

Not Implemented
The pthread.h header is a standard header and includes additional APIs and features which are not implemented in ESP-IDF. These include:
· pthread_cancel() returns ENOSYS if called. · pthread_condattr_init() returns ENOSYS if called.
Other POSIX Threads functions (not listed here) are not implemented and will produce either a compiler or a linker error if referenced from an ESP-IDF application. If you identify a useful API that you would like to see implemented in ESP-IDF, please open a feature request on GitHub <https://github.com/espressif/esp-idf/issues> with the details.

ESP-IDF Extensions
The API esp_pthread_set_cfg() defined in the esp_pthreads.h header offers custom extensions to control how subsequent calls to pthread_create() will behave. Currently, the following configuration can be set:
· Default stack size of new threads, if not specified when calling pthread_create() (overrides CONFIG_PTHREAD_TASK_STACK_SIZE_DEFAULT ).
· RTOS priority of new threads (overrides CONFIG_PTHREAD_TASK_PRIO_DEFAULT). · Core affinity / core pinning of new threads (overrides CONFIG_PTHREAD_TASK_CORE_DEFAULT). · FreeRTOS task name for new threads (overrides CONFIG_PTHREAD_TASK_NAME_DEFAULT)
This configuration is scoped to the calling thread (or FreeRTOS task), meaning that esp_pthread_set_cfg() can be called independently in different threads or tasks. If the inherit_cfg flag is set in the current configuration then any new thread created will inherit the creatorns configuration (if that thread calls pthread_create() recursively), otherwise the new thread will have the default configuration.

Examples
· system/pthread demonstrates using the pthreads API to create threads · cxx/pthread demonstrates using C++ Standard Library functions with threads

Espressif Systems

1128

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
API Reference
Header File
· components/pthread/include/esp_pthread.h
Functions esp_pthread_cfg_t esp_pthread_get_default_config(void)
Creates a default pthread configuration based on the values set via menuconfig.
Return A default configuration structure. esp_err_t esp_pthread_set_cfg(const esp_pthread_cfg_t *cfg)
Configure parameters for creating pthread.
This API allows you to configure how the subsequent pthread_create() call will behave. This call can be used to setup configuration parameters like stack size, priority, configuration inheritance etc.
If the minheritnflag in the configuration structure is enabled, then the same configuration is also inherited in the thread subtree.
Note Passing non-NULL attributes to pthread_create() will override the stack_size parameter set using this API
Return · ESP_OK if configuration was successfully set · ESP_ERR_NO_MEM if out of memory · ESP_ERR_INVALID_ARG if stack_size is less than PTHREAD_STACK_MIN
Parameters · cfg: The pthread config parameters
esp_err_t esp_pthread_get_cfg(esp_pthread_cfg_t *p) Get current pthread creation configuration.
This will retrieve the current configuration that will be used for creating threads.
Return · ESP_OK if the configuration was available · ESP_ERR_NOT_FOUND if a configuration wasnnt previously set
Parameters · p: Pointer to the pthread config structure that will be updated with the currently configured parameters
esp_err_t esp_pthread_init(void) Initialize pthread library.
Structures struct esp_pthread_cfg_t
pthread configuration structure that influences pthread creation
Public Members
size_t stack_size The stack size of the pthread.
size_t prio The threadns priority.
bool inherit_cfg Inherit this configuration further.
const char *thread_name The thread name.

Espressif Systems

1129

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

int pin_to_core The core id to pin the thread to. Has the same value range as xCoreId argument of xTaskCreatePinnedToCore.
Macros PTHREAD_STACK_MIN
2.7.9 Event Loop Library
Overview
The event loop library allows components to declare events to which other components can register handlers code which will execute when those events occur. This allows loosely coupled components to attach desired behavior to changes in state of other components without application involvement. For instance, a high level connection handling library may subscribe to events produced by the Wi-Fi subsystem directly and act on those events. This also simplifies event processing by serializing and deferring code execution to another context.
Using esp_event APIs
There are two objects of concern for users of this library: events and event loops.
Events are occurrences of note. For example, for Wi-Fi, a successful connection to the access point may be an event. Events are referenced using a two part identifier which are discussed more here. Event loops are the vehicle by which events get posted by event sources and handled by event handler functions. These two appear prominently in the event loop library APIs.
Using this library roughly entails the following flow:
1. A user defines a function that should run when an event is posted to a loop. This function is referred to as the event handler. It should have the same signature as esp_event_handler_t.
2. An event loop is created using esp_event_loop_create(), which outputs a handle to the loop of type esp_event_loop_handle_t. Event loops created using this API are referred to as user event loops. There is, however, a special type of event loop called the default event loop which are discussed here.
3. Components register event handlers to the loop using esp_event_handler_register_with(). Handlers can be registered with multiple loops, more on that here.
4. Event sources post an event to the loop using esp_event_post_to(). 5. Components wanting to remove their handlers from being called can do so by unregistering from the loop using
esp_event_handler_unregister_with(). 6. Event loops which are no longer needed can be deleted using esp_event_loop_delete().
In code, the flow above may look like as follows:
// 1. Define the event handler void run_on_event(void* handler_arg, esp_event_base_t base, int32_t id, void* event_data) {
// Event handler logic }
void app_main() {
// 2. A configuration structure of type esp_event_loop_args_t is needed to specify the properties of the loop to be
// created. A handle of type esp_event_loop_handle_t is obtained, which is needed by the other APIs to reference the loop
// to perform their operations on. esp_event_loop_args_t loop_args = {
.queue_size = ..., (continues on next page)

Espressif Systems

1130

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

.task_name = ... .task_priority = ..., .task_stack_size = ..., .task_core_id = ... };

(continued from previous page)

esp_event_loop_handle_t loop_handle;

esp_event_loop_create(&loop_args, &loop_handle);

// 3. Register event handler defined in (1). MY_EVENT_BASE and MY_EVENT_ID specifies a hypothetical
// event that handler run_on_event should execute on when it gets posted to the loop.
esp_event_handler_register_with(loop_handle, MY_EVENT_BASE, MY_EVENT_ID, run_ on_event, ...);

...

// 4. Post events to the loop. This queues the event on the event loop. At some point in time
// the event loop executes the event handler registered to the posted event, in this case run_on_event.
// For simplicity sake this example calls esp_event_post_to from app_main, but posting can be done from
// any other tasks (which is the more interesting use case). esp_event_post_to(loop_handle, MY_EVENT_BASE, MY_EVENT_ID, ...);

...

// 5. Unregistering an unneeded handler esp_event_handler_unregister_with(loop_handle, MY_EVENT_BASE, MY_EVENT_ID, run_ on_event);

...

// 6. Deleting an unneeded event loop esp_event_loop_delete(loop_handle); }

Declaring and defining events
As mentioned previously, events consists of two-part identifiers: the event base and the event ID. The event base identifies an independent group of events; the event ID identifies the event within that group. Think of the event base and event ID as a personns last name and first name, respectively. A last name identifies a family, and the first name identifies a person within that family. The event loop library provides macros to declare and define the event base easily. Event base declaration: ESP_EVENT_DECLARE_BASE(EVENT_BASE)
Event base definition: ESP_EVENT_DEFINE_BASE(EVENT_BASE)
Note: In IDF, the base identifiers for system events are uppercase and are postfixed with _EVENT. For example, the base for Wi-Fi events is declared and defined as WIFI_EVENT, the ethernet event base ETHERNET_EVENT,

Espressif Systems

1131

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

and so on. The purpose is to have event bases look like constants (although they are global variables considering the defintions of macros ESP_EVENT_DECLARE_BASE and ESP_EVENT_DEFINE_BASE).
For event IDns, declaring them as enumerations is recommended. Once again, for visibility, these are typically placed in public header files.
Event ID:
enum { EVENT_ID_1, EVENT_ID_2, EVENT_ID_3, ...
}

Default Event Loop
The default event loop is a special type of loop used for system events (Wi-Fi events, for example). The handle for this loop is hidden from the user. The creation, deletion, handler registration/unregistration and posting of events is done through a variant of the APIs for user event loops. The table below enumerates those variants, and the user event loops equivalent.

User Event Loops esp_event_loop_create() esp_event_loop_delete() esp_event_handler_register_with() esp_event_handler_unregister_with() esp_event_post_to()

Default Event Loops esp_event_loop_create_default() esp_event_loop_delete_default() esp_event_handler_register() esp_event_handler_unregister() esp_event_post()

If you compare the signatures for both, they are mostly similar except the for the lack of loop handle specification for the default event loop APIs.
Other than the API difference and the special designation to which system events are posted to, there is no difference to how default event loops and user event loops behave. It is even possible for users to post their own events to the default event loop, should the user opt to not create their own loops to save memory.

Notes on Handler Registration
It is possible to register a single handler to multiple events individually, i.e. using multiple calls to esp_event_handler_register_with(). For those multiple calls, the specific event base and event ID can be specified with which the handler should execute.
However, in some cases it is desirable for a handler to execute on (1) all events that get posted to a loop or (2) all events of a particular base identifier. This is possible using the special event base identifier ESP_EVENT_ANY_BASE and special event ID ESP_EVENT_ANY_ID. These special identifiers may be passed as the event base and event ID arguments for esp_event_handler_register_with().
Therefore, the valid arguments to esp_event_handler_register_with() are:
1. <event base>, <event ID> - handler executes when the event with base <event base> and event ID <event ID> gets posted to the loop
2. <event base>, ESP_EVENT_ANY_ID - handler executes when any event with base <event base> gets posted to the loop
3. ESP_EVENT_ANY_BASE, ESP_EVENT_ANY_ID - handler executes when any event gets posted to the loop
As an example, suppose the following handler registrations were performed:

Espressif Systems

1132

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_event_handler_register_with(loop_handle, MY_EVENT_BASE, MY_EVENT_ID, run_on_ event_1, ...); esp_event_handler_register_with(loop_handle, MY_EVENT_BASE, ESP_EVENT_ANY_ID, run_ on_event_2, ...); esp_event_handler_register_with(loop_handle, ESP_EVENT_ANY_BASE, ESP_EVENT_ANY_ID, run_on_event_3, ...);
If the hypothetical event MY_EVENT_BASE, MY_EVENT_ID is posted, all three handlers run_on_event_1, run_on_event_2, and run_on_event_3 would execute.
If the hypothetical event MY_EVENT_BASE, MY_OTHER_EVENT_ID is posted, only run_on_event_2 and run_on_event_3 would execute.
If the hypothetical event MY_OTHER_EVENT_BASE, MY_OTHER_EVENT_ID is posted, only run_on_event_3 would execute.

Handler Registration and Handler Dispatch Order The general rule is that for handlers that match a certain posted event during dispatch, those which are registered first also gets executed first. The user can then control which handlers get executed first by registering them before other handlers, provided that all registrations are performed using a single task. If the user plans to take advantage of this behavior, caution must be exercised if there are multiple tasks registering handlers. While the mfirst registered, first executednbehavior still holds true, the task which gets executed first will also get their handlers registered first. Handlers registered one after the other by a single task will still be dispatched in the order relative to each other, but if that task gets pre-empted in between registration by another task which also registers handlers; then during dispatch those handlers will also get executed in between.

Event loop profiling
A configuration option CONFIG_ESP_EVENT_LOOP_PROFILING can be enabled in order to activate statistics collection for all event loops created. The function esp_event_dump() can be used to output the collected statistics to a file stream. More details on the information included in the dump can be found in the esp_event_dump() API Reference.

Application Example
Examples on using the esp_event library can be found in system/esp_event. The examples cover event declaration, loop creation, handler registration and unregistration and event posting. Other examples which also adopt esp_event library:
· NMEA Parser , which will decode the statements received from GPS.

API Reference
Header File · components/esp_event/include/esp_event.h

Functions

esp_err_t esp_event_loop_create(const

esp_event_loop_args_t

Create a new event loop.

esp_event_loop_handle_t *event_loop)

*event_loop_args,

Return · ESP_OK: Success · ESP_ERR_INVALID_ARG: event_loop_args or event_loop was NULL · ESP_ERR_NO_MEM: Cannot allocate memory for event loops list · ESP_FAIL: Failed to create task loop

Espressif Systems

1133

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· Others: Fail Parameters
· [in] event_loop_args: configuration structure for the event loop to create · [out] event_loop: handle to the created event loop esp_err_t esp_event_loop_delete(esp_event_loop_handle_t event_loop) Delete an existing event loop.

Return · ESP_OK: Success · Others: Fail
Parameters · [in] event_loop: event loop to delete, must not be NULL

esp_err_t esp_event_loop_create_default(void) Create default event loop.

Return · ESP_OK: Success · ESP_ERR_NO_MEM: Cannot allocate memory for event loops list · ESP_FAIL: Failed to create task loop · Others: Fail

esp_err_t esp_event_loop_delete_default(void) Delete the default event loop.

Return · ESP_OK: Success · Others: Fail

esp_err_t esp_event_loop_run(esp_event_loop_handle_t event_loop, TickType_t ticks_to_run) Dispatch events posted to an event loop.

This function is used to dispatch events posted to a loop with no dedicated task, i.e. task name was set to NULL in event_loop_args argument during loop creation. This function includes an argument to limit the amount of time it runs, returning control to the caller when that time expires (or some time afterwards). There is no guarantee that a call to this function will exit at exactly the time of expiry. There is also no guarantee that events have been dispatched during the call, as the function might have spent all the allotted time waiting on the event queue. Once an event has been dequeued, however, it is guaranteed to be dispatched. This guarantee contributes to not being able to exit exactly at time of expiry as (1) blocking on internal mutexes is necessary for dispatching the dequeued event, and (2) during dispatch of the dequeued event there is no way to control the time occupied by handler code execution. The guaranteed time of exit is therefore the allotted time + amount of time required to dispatch the last dequeued event.

In cases where waiting on the queue times out, ESP_OK is returned and not ESP_ERR_TIMEOUT, since it is normal behavior.

Note encountering an unknown event that has been posted to the loop will only generate a warning, not an error.
Return · ESP_OK: Success · Others: Fail
Parameters · [in] event_loop: event loop to dispatch posted events from, must not be NULL · [in] ticks_to_run: number of ticks to run the loop

esp_err_t esp_event_handler_register(esp_event_base_t event_base, int32_t

esp_event_handler_t

event_handler,

*event_handler_arg)

Register an event handler to the system event loop (legacy).

event_id, void

This function can be used to register a handler for either: (1) specific events, (2) all events of a certain event base, or (3) all events known by the system event loop.

Espressif Systems

1134

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Note This function is obsolete and will be deprecated soon, please use esp_event_handler_instance_register() instead.

· specific events: specify exact event_base and event_id · all events of a certain base: specify exact event_base and use ESP_EVENT_ANY_ID as the event_id · all events known by the loop: use ESP_EVENT_ANY_BASE for event_base and
ESP_EVENT_ANY_ID as the event_id

Registering multiple handlers to events is possible. Registering a single handler to multiple events is also possible. However, registering the same handler to the same event multiple times would cause the previous registrations to be overwritten.

Note the event loop library does not maintain a copy of event_handler_arg, therefore the user should ensure that event_handler_arg still points to a valid location by the time the handler gets called
Return · ESP_OK: Success · ESP_ERR_NO_MEM: Cannot allocate memory for the handler · ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID · Others: Fail
Parameters · [in] event_base: the base ID of the event to register the handler for · [in] event_id: the ID of the event to register the handler for · [in] event_handler: the handler function which gets called when the event is dispatched · [in] event_handler_arg: data, aside from event data, that is passed to the handler when it is called

esp_err_t esp_event_handler_register_with(esp_event_loop_handle_t

event_loop,

esp_event_base_t event_base, int32_t event_id,

esp_event_handler_t event_handler, void

*event_handler_arg)

Register an event handler to a specific loop (legacy).

This function behaves in the same manner as esp_event_handler_register, except the additional specification of the event loop to register the handler to.

Note This function is obsolete and will be deprecated soon, esp_event_handler_instance_register_with() instead.

please use

Note the event loop library does not maintain a copy of event_handler_arg, therefore the user should ensure that event_handler_arg still points to a valid location by the time the handler gets called
Return · ESP_OK: Success · ESP_ERR_NO_MEM: Cannot allocate memory for the handler · ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID · Others: Fail
Parameters · [in] event_loop: the event loop to register this handler function to, must not be NULL · [in] event_base: the base ID of the event to register the handler for · [in] event_id: the ID of the event to register the handler for · [in] event_handler: the handler function which gets called when the event is dispatched · [in] event_handler_arg: data, aside from event data, that is passed to the handler when it is called

esp_err_t esp_event_handler_instance_register_with(esp_event_loop_handle_t

event_loop,

esp_event_base_t

event_base, int32_t event_id,

esp_event_handler_t event_handler,

void

*event_handler_arg,

esp_event_handler_instance_t

Register an instance of event handler to a specific loop.

*instance)

This function can be used to register a handler for either: (1) specific events, (2) all events of a certain event

Espressif Systems

1135

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

base, or (3) all events known by the system event loop.

· specific events: specify exact event_base and event_id · all events of a certain base: specify exact event_base and use ESP_EVENT_ANY_ID as the event_id · all events known by the loop: use ESP_EVENT_ANY_BASE for event_base and
ESP_EVENT_ANY_ID as the event_id

Besides the error, the function returns an instance object as output parameter to identify each registration. This is necessary to remove (unregister) the registration before the event loop is deleted.

Registering multiple handlers to events, registering a single handler to multiple events as well as registering the same handler to the same event multiple times is possible. Each registration yields a distinct instance object which identifies it over the registration lifetime.

Note the event loop library does not maintain a copy of event_handler_arg, therefore the user should ensure that event_handler_arg still points to a valid location by the time the handler gets called
Return · ESP_OK: Success · ESP_ERR_NO_MEM: Cannot allocate memory for the handler · ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID or instance is NULL · Others: Fail
Parameters · [in] event_loop: the event loop to register this handler function to, must not be NULL · [in] event_base: the base ID of the event to register the handler for · [in] event_id: the ID of the event to register the handler for · [in] event_handler: the handler function which gets called when the event is dispatched · [in] event_handler_arg: data, aside from event data, that is passed to the handler when it is called · [out] instance: An event handler instance object related to the registered event handler and data, can be NULL. This needs to be kept if the specific callback instance should be unregistered before deleting the whole event loop. Registering the same event handler multiple times is possible and yields distinct instance objects. The data can be the same for all registrations. If no unregistration is needed, but the handler should be deleted when the event loop is deleted, instance can be NULL.

esp_err_t esp_event_handler_instance_register(esp_event_base_t event_base, int32_t

event_id,

esp_event_handler_t

event_handler, void *event_handler_arg,

esp_event_handler_instance_t *instance)

Register an instance of event handler to the default loop.

This function does the same as esp_event_handler_instance_register_with, except that it registers the handler to the default event loop.

Note the event loop library does not maintain a copy of event_handler_arg, therefore the user should ensure that event_handler_arg still points to a valid location by the time the handler gets called
Return · ESP_OK: Success · ESP_ERR_NO_MEM: Cannot allocate memory for the handler · ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID or instance is NULL · Others: Fail
Parameters · [in] event_base: the base ID of the event to register the handler for · [in] event_id: the ID of the event to register the handler for · [in] event_handler: the handler function which gets called when the event is dispatched · [in] event_handler_arg: data, aside from event data, that is passed to the handler when it is called · [out] instance: An event handler instance object related to the registered event handler and data, can be NULL. This needs to be kept if the specific callback instance should be unregistered before deleting the whole event loop. Registering the same event handler multiple times is possible and yields distinct instance objects. The data can be the same for all registrations. If no unregistration is needed, but the handler should be deleted when the event loop is deleted, instance can be NULL.

Espressif Systems

1136

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t esp_event_handler_unregister(esp_event_base_t event_base, int32_t event_id, esp_event_handler_t event_handler)
Unregister a handler with the system event loop (legacy).

Unregisters a handler, so it will no longer be called during dispatch. Handlers can be unregistered for any combination of event_base and event_id which were previously registered. To unregister a handler, the event_base and event_id arguments must match exactly the arguments passed to esp_event_handler_register() when that handler was registered. Passing ESP_EVENT_ANY_BASE and/or ESP_EVENT_ANY_ID will only unregister handlers that were registered with the same wildcard arguments.

Note This function is obsolete and will be deprecated soon, esp_event_handler_instance_unregister() instead.

please use

Note When using ESP_EVENT_ANY_ID, handlers registered to specific event IDs using the same base will not be unregistered. When using ESP_EVENT_ANY_BASE, events registered to specific bases will also not be unregistered. This avoids accidental unregistration of handlers registered by other users or components.
Return ESP_OK success Return ESP_ERR_INVALID_ARG invalid combination of event base and event ID Return others fail Parameters
· [in] event_base: the base of the event with which to unregister the handler · [in] event_id: the ID of the event with which to unregister the handler · [in] event_handler: the handler to unregister

esp_err_t esp_event_handler_unregister_with(esp_event_loop_handle_t

event_loop,

esp_event_base_t event_base, int32_t event_id,

esp_event_handler_t event_handler)

Unregister a handler from a specific event loop (legacy).

This function behaves in the same manner as esp_event_handler_unregister, except the additional specification of the event loop to unregister the handler with.

Note This function is obsolete and will be deprecated soon, esp_event_handler_instance_unregister_with() instead.

please use

Return · ESP_OK: Success · ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID · Others: Fail
Parameters · [in] event_loop: the event loop with which to unregister this handler function, must not be NULL · [in] event_base: the base of the event with which to unregister the handler · [in] event_id: the ID of the event with which to unregister the handler · [in] event_handler: the handler to unregister

esp_err_t esp_event_handler_instance_unregister_with(esp_event_loop_handle_t

event_loop, esp_event_base_t

event_base, int32_t event_id,

esp_event_handler_instance_t

Unregister a handler instance from a specific event loop.

instance)

Unregisters a handler instance, so it will no longer be called during dispatch. Handler instances can be unregistered for any combination of event_base and event_id which were previously registered. To unregister a handler instance, the event_base and event_id arguments must match exactly the arguments passed to esp_event_handler_instance_register() when that handler instance was registered. Passing ESP_EVENT_ANY_BASE and/or ESP_EVENT_ANY_ID will only unregister handler instances that were registered with the same wildcard arguments.

Note When using ESP_EVENT_ANY_ID, handlers registered to specific event IDs using the same base will not be unregistered. When using ESP_EVENT_ANY_BASE, events registered to specific bases will

Espressif Systems

1137

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

also not be unregistered. This avoids accidental unregistration of handlers registered by other users or components. Return
· ESP_OK: Success · ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID · Others: Fail Parameters · [in] event_loop: the event loop with which to unregister this handler function, must not be
NULL · [in] event_base: the base of the event with which to unregister the handler · [in] event_id: the ID of the event with which to unregister the handler · [in] instance: the instance object of the registration to be unregistered

esp_err_t esp_event_handler_instance_unregister(esp_event_base_t event_base, int32_t

event_id, esp_event_handler_instance_t

Unregister a handler from the system event loop.

instance)

This function does the same as esp_event_handler_instance_unregister_with, except that it unregisters the handler instance from the default event loop.

Return · ESP_OK: Success · ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID · Others: Fail
Parameters · [in] event_base: the base of the event with which to unregister the handler · [in] event_id: the ID of the event with which to unregister the handler · [in] instance: the instance object of the registration to be unregistered

esp_err_t esp_event_post(esp_event_base_t event_base, int32_t event_id, void *event_data, size_t
event_data_size, TickType_t ticks_to_wait) Posts an event to the system default event loop. The event loop library keeps a copy of event_data and manages
the copyns lifetime automatically (allocation + deletion); this ensures that the data the handler receives is
always valid.

Return · ESP_OK: Success · ESP_ERR_TIMEOUT: Time to wait for event queue to unblock expired, queue full when posting from ISR · ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID · Others: Fail
Parameters · [in] event_base: the event base that identifies the event · [in] event_id: the event ID that identifies the event · [in] event_data: the data, specific to the event occurrence, that gets passed to the handler · [in] event_data_size: the size of the event data · [in] ticks_to_wait: number of ticks to block on a full event queue

esp_err_t esp_event_post_to(esp_event_loop_handle_t event_loop, esp_event_base_t event_base, int32_t event_id, void *event_data, size_t event_data_size, TickType_t ticks_to_wait)
Posts an event to the specified event loop. The event loop library keeps a copy of event_data and manages the copyns lifetime automatically (allocation + deletion); this ensures that the data the handler receives is always valid.

This function behaves in the same manner as esp_event_post_to, except the additional specification of the event loop to post the event to.

Return · ESP_OK: Success · ESP_ERR_TIMEOUT: Time to wait for event queue to unblock expired, queue full when posting from ISR

Espressif Systems

1138

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID · Others: Fail Parameters · [in] event_loop: the event loop to post to, must not be NULL · [in] event_base: the event base that identifies the event · [in] event_id: the event ID that identifies the event · [in] event_data: the data, specific to the event occurrence, that gets passed to the handler · [in] event_data_size: the size of the event data · [in] ticks_to_wait: number of ticks to block on a full event queue
esp_err_t esp_event_isr_post(esp_event_base_t event_base, int32_t event_id, void *event_data, size_t event_data_size, BaseType_t *task_unblocked)
Special variant of esp_event_post for posting events from interrupt handlers.
Note this function is only available when CONFIG_ESP_EVENT_POST_FROM_ISR is enabled Note when this function is called from an interrupt handler placed in IRAM, this function should be placed in
IRAM as well by enabling CONFIG_ESP_EVENT_POST_FROM_IRAM_ISR Return
· ESP_OK: Success · ESP_FAIL: Event queue for the default event loop full · ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID, data size of more than
4 bytes · Others: Fail Parameters · [in] event_base: the event base that identifies the event · [in] event_id: the event ID that identifies the event · [in] event_data: the data, specific to the event occurrence, that gets passed to the handler · [in] event_data_size: the size of the event data; max is 4 bytes · [out] task_unblocked: an optional parameter (can be NULL) which indicates that an event
task with higher priority than currently running task has been unblocked by the posted event; a context switch should be requested before the interrupt is existed.
esp_err_t esp_event_isr_post_to(esp_event_loop_handle_t event_loop, esp_event_base_t event_base, int32_t event_id, void *event_data, size_t event_data_size, BaseType_t *task_unblocked)
Special variant of esp_event_post_to for posting events from interrupt handlers.
Note this function is only available when CONFIG_ESP_EVENT_POST_FROM_ISR is enabled Note when this function is called from an interrupt handler placed in IRAM, this function should be placed in
IRAM as well by enabling CONFIG_ESP_EVENT_POST_FROM_IRAM_ISR Return
· ESP_OK: Success · ESP_FAIL: Event queue for the loop full · ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID, data size of more than
4 bytes · Others: Fail Parameters · [in] event_loop: the event loop to post to, must not be NULL · [in] event_base: the event base that identifies the event · [in] event_id: the event ID that identifies the event · [in] event_data: the data, specific to the event occurrence, that gets passed to the handler · [in] event_data_size: the size of the event data · [out] task_unblocked: an optional parameter (can be NULL) which indicates that an event
task with higher priority than currently running task has been unblocked by the posted event; a context switch should be requested before the interrupt is existed.
esp_err_t esp_event_dump(FILE *file) Dumps statistics of all event loops.
Dumps event loop info in the format:

Espressif Systems

1139

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

event loop handler handler ...
event loop handler handler ...
where:
event loop format: address,name rx:total_received dr:total_dropped where: address - memory address of the event loop name - name of the event loop, 'none' if no dedicated task total_received - number of successfully posted events total_dropped - number of events unsuccessfully posted due to queue
being full
handler format: address ev:base,id inv:total_invoked run:total_runtime where: address - address of the handler function base,id - the event specified by event base and ID this handler
executes total_invoked - number of times this handler has been invoked total_runtime - total amount of time used for invoking this handler
Note this function is a noop when CONFIG_ESP_EVENT_LOOP_PROFILING is disabled Return
· ESP_OK: Success · ESP_ERR_NO_MEM: Cannot allocate memory for event loops list · Others: Fail Parameters · [in] file: the file stream to output to
Structures struct esp_event_loop_args_t
Configuration for creating event loops.
Public Members
int32_t queue_size size of the event loop queue
const char *task_name name of the event loop task; if NULL, a dedicated task is not created for event loop
UBaseType_t task_priority priority of the event loop task, ignored if task name is NULL
uint32_t task_stack_size stack size of the event loop task, ignored if task name is NULL
BaseType_t task_core_id core to which the event loop task is pinned to, ignored if task name is NULL
Header File

Espressif Systems

1140

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· components/esp_event/include/esp_event_base.h

Macros ESP_EVENT_DECLARE_BASE(id) ESP_EVENT_DEFINE_BASE(id)
ESP_EVENT_ANY_BASE register handler for any event base
ESP_EVENT_ANY_ID register handler for any event id

Type Definitions typedef void *esp_event_loop_handle_t
a number that identifies an event with respect to a base typedef void (*esp_event_handler_t)(void *event_handler_arg, esp_event_base_t event_base,
int32_t event_id, void *event_data) function called when an event is posted to the queue
typedef void *esp_event_handler_instance_t context identifying an instance of a registered event handler

Related Documents Legacy event loop

API Reference

Header File · components/esp_event/include/esp_event_legacy.h

Functions esp_err_t esp_event_send(system_event_t *event)
Send an event to event task.

Other task/modules, such as the tcpip_adapter, can call this API to send an event to event task

Note This API is part of the legacy event system. New code should use event library API in esp_event.h

Return ESP_OK : succeed

Return others : fail

Parameters

· event: Event to send

esp_err_t esp_event_send_internal(esp_event_base_t event_base, int32_t event_id, void

*event_data, size_t event_data_size, TickType_t

Send an event to event task.

ticks_to_wait)

Other task/modules, such as the tcpip_adapter, can call this API to send an event to event task

Note This API is used by Wi-Fi Driver only.

Return ESP_OK : succeed Return others : fail Parameters
· [in] event_base: the event base that identifies the event · [in] event_id: the event ID that identifies the event · [in] event_data: the data, specific to the event occurrence, that gets passed to the handler

Espressif Systems

1141

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· [in] event_data_size: the size of the event data · [in] ticks_to_wait: number of ticks to block on a full event queue
esp_err_t esp_event_process_default(system_event_t *event) Default event handler for system events.
This function performs default handling of system events. When using esp_event_loop APIs, it is called automatically before invoking the user-provided callback function.
Note This API is part of the legacy event system. New code should use event library API in esp_event.h
Applications which implement a custom event loop must call this function as part of event processing.
Return ESP_OK if an event was handled successfully Parameters
· event: pointer to event to be handled
void esp_event_set_default_eth_handlers(void) Install default event handlers for Ethernet interface.
Note This API is part of the legacy event system. New code should use event library API in esp_event.h
void esp_event_set_default_wifi_handlers(void) Install default event handlers for Wi-Fi interfaces (station and AP)
Note This API is part of the legacy event system. New code should use event library API in esp_event.h
esp_err_t esp_event_loop_init(system_event_cb_t cb, void *ctx) Initialize event loop.
Create the event handler and task
Note This API is part of the legacy event system. New code should use event library API in esp_event.h
Return · ESP_OK: succeed · others: fail
Parameters · cb: application specified event callback, it can be modified by call esp_event_set_cb · ctx: reserved for user
system_event_cb_t esp_event_loop_set_cb(system_event_cb_t cb, void *ctx) Set application specified event callback function.
Note This API is part of the legacy event system. New code should use event library API in esp_event.h Attention 1. If cb is NULL, means application donnt need to handle If cb is not NULL, it will be call when
an event is received, after the default event callback is completed Return old callback Parameters
· cb: application callback function · ctx: argument to be passed to callback
Unions union system_event_info_t
#include <esp_event_legacy.h> Union of all possible system_event argument structures
Public Members
system_event_sta_connected_t connected ESP32 station connected to AP
system_event_sta_disconnected_t disconnected ESP32 station disconnected to AP

Espressif Systems

1142

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

system_event_sta_scan_done_t scan_done ESP32 station scan (APs) done
system_event_sta_authmode_change_t auth_change the auth mode of AP ESP32 station connected to changed
system_event_sta_got_ip_t got_ip ESP32 station got IP, first time got IP or when IP is changed
system_event_sta_wps_er_pin_t sta_er_pin ESP32 station WPS enrollee mode PIN code received
system_event_sta_wps_fail_reason_t sta_er_fail_reason ESP32 station WPS enrollee mode failed reason code received
system_event_sta_wps_er_success_t sta_er_success ESP32 station WPS enrollee success
system_event_ap_staconnected_t sta_connected a station connected to ESP32 soft-AP
system_event_ap_stadisconnected_t sta_disconnected a station disconnected to ESP32 soft-AP
system_event_ap_probe_req_rx_t ap_probereqrecved ESP32 soft-AP receive probe request packet
system_event_ftm_report_t ftm_report Report of FTM procedure
system_event_ap_staipassigned_t ap_staipassigned ESP32 soft-AP assign an IP to the station
system_event_got_ip6_t got_ip6 ESP32 station ` or ap or ethernet ipv6 addr state change to preferred
Structures struct system_event_t
Event, as a tagged enum
Public Members
system_event_id_t event_id event ID
system_event_info_t event_info event information
Macros SYSTEM_EVENT_AP_STA_GOT_IP6
Type Definitions typedef wifi_event_sta_wps_fail_reason_t system_event_sta_wps_fail_reason_t
Argument structure of SYSTEM_EVENT_STA_WPS_ER_FAILED event typedef wifi_event_sta_scan_done_t system_event_sta_scan_done_t
Argument structure of SYSTEM_EVENT_SCAN_DONE event
typedef wifi_event_sta_connected_t system_event_sta_connected_t Argument structure of SYSTEM_EVENT_STA_CONNECTED event
typedef wifi_event_sta_disconnected_t system_event_sta_disconnected_t Argument structure of SYSTEM_EVENT_STA_DISCONNECTED event

Espressif Systems

1143

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
typedef wifi_event_sta_authmode_change_t system_event_sta_authmode_change_t Argument structure of SYSTEM_EVENT_STA_AUTHMODE_CHANGE event
typedef wifi_event_sta_wps_er_pin_t system_event_sta_wps_er_pin_t Argument structure of SYSTEM_EVENT_STA_WPS_ER_PIN event
typedef wifi_event_sta_wps_er_success_t system_event_sta_wps_er_success_t Argument structure of SYSTEM_EVENT_STA_WPS_ER_PIN event
typedef wifi_event_ap_staconnected_t system_event_ap_staconnected_t Argument structure of event
typedef wifi_event_ap_stadisconnected_t system_event_ap_stadisconnected_t Argument structure of event
typedef wifi_event_ap_probe_req_rx_t system_event_ap_probe_req_rx_t Argument structure of event
typedef wifi_event_ftm_report_t system_event_ftm_report_t Argument structure of SYSTEM_EVENT_FTM_REPORT event
typedef ip_event_ap_staipassigned_t system_event_ap_staipassigned_t Argument structure of event
typedef ip_event_got_ip_t system_event_sta_got_ip_t Argument structure of event
typedef ip_event_got_ip6_t system_event_got_ip6_t Argument structure of event
typedef esp_err_t (*system_event_handler_t)(esp_event_base_t event_base, int32_t event_id, void *event_data, size_t event_data_size, TickType_t ticks_to_wait)
Event handler function type
typedef esp_err_t (*system_event_cb_t)(void *ctx, system_event_t *event) Application specified event callback function.
Note This API is part of the legacy event system. New code should use event library API in esp_event.h Return
· ESP_OK: succeed · others: fail Parameters · ctx: reserved for user · event: event type defined in this file
Enumerations enum system_event_id_t
System event types enumeration
Values:
SYSTEM_EVENT_WIFI_READY = 0 ESP32 Wi-Fi ready
SYSTEM_EVENT_SCAN_DONE ESP32 finish scanning AP
SYSTEM_EVENT_STA_START ESP32 station start
SYSTEM_EVENT_STA_STOP ESP32 station stop
SYSTEM_EVENT_STA_CONNECTED ESP32 station connected to AP

Espressif Systems

1144

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
SYSTEM_EVENT_STA_DISCONNECTED ESP32 station disconnected from AP
SYSTEM_EVENT_STA_AUTHMODE_CHANGE the auth mode of AP connected by ESP32 station changed
SYSTEM_EVENT_STA_GOT_IP ESP32 station got IP from connected AP
SYSTEM_EVENT_STA_LOST_IP ESP32 station lost IP and the IP is reset to 0
SYSTEM_EVENT_STA_BSS_RSSI_LOW ESP32 station connected BSS rssi goes below threshold
SYSTEM_EVENT_STA_WPS_ER_SUCCESS ESP32 station wps succeeds in enrollee mode
SYSTEM_EVENT_STA_WPS_ER_FAILED ESP32 station wps fails in enrollee mode
SYSTEM_EVENT_STA_WPS_ER_TIMEOUT ESP32 station wps timeout in enrollee mode
SYSTEM_EVENT_STA_WPS_ER_PIN ESP32 station wps pin code in enrollee mode
SYSTEM_EVENT_STA_WPS_ER_PBC_OVERLAP ESP32 station wps overlap in enrollee mode
SYSTEM_EVENT_AP_START ESP32 soft-AP start
SYSTEM_EVENT_AP_STOP ESP32 soft-AP stop
SYSTEM_EVENT_AP_STACONNECTED a station connected to ESP32 soft-AP
SYSTEM_EVENT_AP_STADISCONNECTED a station disconnected from ESP32 soft-AP
SYSTEM_EVENT_AP_STAIPASSIGNED ESP32 soft-AP assign an IP to a connected station
SYSTEM_EVENT_AP_PROBEREQRECVED Receive probe request packet in soft-AP interface
SYSTEM_EVENT_ACTION_TX_STATUS Receive status of Action frame transmitted
SYSTEM_EVENT_ROC_DONE Indicates the completion of Remain-on-Channel operation status
SYSTEM_EVENT_STA_BEACON_TIMEOUT ESP32 station beacon timeout
SYSTEM_EVENT_FTM_REPORT Receive report of FTM procedure
SYSTEM_EVENT_GOT_IP6 ESP32 station or ap or ethernet interface v6IP addr is preferred
SYSTEM_EVENT_ETH_START ESP32 ethernet start
SYSTEM_EVENT_ETH_STOP ESP32 ethernet stop

Espressif Systems

1145

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

SYSTEM_EVENT_ETH_CONNECTED ESP32 ethernet phy link up
SYSTEM_EVENT_ETH_DISCONNECTED ESP32 ethernet phy link down
SYSTEM_EVENT_ETH_GOT_IP ESP32 ethernet got IP from connected AP
SYSTEM_EVENT_ETH_LOST_IP ESP32 ethernet lost IP and the IP is reset to 0
SYSTEM_EVENT_MAX Number of members in this enum
2.7.10 FreeRTOS
Overview
This section contains documentation of FreeRTOS types, functions, and macros. It is automatically generated from FreeRTOS header files.
Note: ESP-IDF FreeRTOS is based on Vanilla FreeRTOS v10.4.3
· For more information about the SMP changes of ESP-IDF FreeRTOS, see ESP-IDF FreeRTOS (SMP) · For more information about the features added to ESP-IDF FreeRTOS, see FreeRTOS Additions.
Configuration
Vanilla FreeRTOS allows ports and applications to configure the kernel by adding various #define config... macros to FreeRTOSConfig.h. Through these macros, the kernelns scheduling behavior and various kernel features can be enabled or disabled. However, in ESP-IDF FreeRTOS, the ``FreeRTOSConfig.h`` file is considered a private and must not be modified by users. Any FreeRTOS configuration that is exposed to the user will be done so via menuconfig.
ESP-IDF FreeRTOS can be configured in the project configuration menu (idf.py menuconfig) under Component Config/FreeRTOS. The following section highlights some of the ESP-IDF FreeRTOS configuration options. For a full list of ESP-IDF FreeRTOS configurations, see Project Configuration
· CONFIG_FREERTOS_UNICORE will run ESP-IDF FreeRTOS only on CPU0. Note that this is not equivalent to running Vanilla FreeRTOS. Futhermore, this option may affect behavior of components other than freertos. For more details regarding the effects of running ESP-IDF FreeRTOS on a single core, refer to ESP-IDF FreeRTOS Single Core. Alternatively, users can also search for occurrences of CONFIG_FREERTOS_UNICORE in the ESP-IDF components.
· CONFIG_FREERTOS_ASSERT_ON_UNTESTED_FUNCTION will trigger a halt in functions in ESP-IDF FreeRTOS that have not been fully tested in an SMP context.
· CONFIG_FREERTOS_TASK_FUNCTION_WRAPPER will enclose all task functions within a wrapper function. In the case that a task function mistakenly returns (i.e. does not call vTaskDelete()), the call flow will return to the wrapper function. The wrapper function will then log an error and abort the application, as illustrated below:
E (25) FreeRTOS: FreeRTOS task should not return. Aborting now! abort() was called at PC 0x40085c53 on core 0

ESP-IDF FreeRTOS Applications
Unlike Vanilla FreeRTOS, users must not call vTaskStartScheduler(). Instead, ESP-IDF FreeRTOS is started automatically. The entry point is a user defined void app_main(void) function.

Espressif Systems

1146

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· Typically, users would spawn the rest of their applications task from app_main. · The app_main function is allowed to return at any point (i.e., before the application terminates). · The app_main function is called from the main task.
The main task is one of multiple tasks that are automatically spawned by ESP-IDF during startup. These tasks are:

Task Name Main Task (main)
Idle Tasks (IDLEx) IPC Tasks (ipcx)

Table 14: List of Tasks Created During Startup

Affinity CPU0
CPU0 and CPU1 CPU0 and CPU1

PrioriDtyescription 1 Task that simply calls app_main. This task will
self delete when app_main returns 0 Idle tasks created for (and pinned to) each CPU 24 IPC tasks created for (and pinned to ) each CPU. IPC
tasks are used to implement the IPC feature. See Inter-Processor Call for more details.

Task API
Header File
· components/freertos/FreeRTOS-Kernel/include/freertos/task.h
Functions BaseType_t xTaskCreatePinnedToCore(TaskFunction_t pvTaskCode, const char *const pc-
Name, const uint32_t usStackDepth, void *const pvParameters, UBaseType_t uxPriority, TaskHandle_t *const pvCreatedTask, const BaseType_t xCoreID) Create a new task with a specified affinity.
This function is similar to xTaskCreate, but allows setting task affinity in SMP system.
Return pdPASS if the task was successfully created and added to a ready list, otherwise an error code defined in the file projdefs.h
Parameters · pvTaskCode: Pointer to the task entry function. Tasks must be implemented to never return (i.e. continuous loop), or should be terminated using vTaskDelete function. · pcName: A descriptive name for the task. This is mainly used to facilitate debugging. Max length defined by configMAX_TASK_NAME_LEN - default is 16. · usStackDepth: The size of the task stack specified as the number of bytes. Note that this differs from vanilla FreeRTOS. · pvParameters: Pointer that will be used as the parameter for the task being created. · uxPriority: The priority at which the task should run. Systems that include MPU support can optionally create tasks in a privileged (system) mode by setting bit portPRIVILEGE_BIT of the priority parameter. For example, to create a privileged task at priority 2 the uxPriority parameter should be set to ( 2 | portPRIVILEGE_BIT ). · pvCreatedTask: Used to pass back a handle by which the created task can be referenced. · xCoreID: If the value is tskNO_AFFINITY, the created task is not pinned to any CPU, and the scheduler can run it on any core available. Values 0 or 1 indicate the index number of the CPU which the task should be pinned to. Specifying values larger than (portNUM_PROCESSORS - 1) will cause the function to fail.
static BaseType_t xTaskCreate(TaskFunction_t pvTaskCode, const char *const pcName, const uint32_t usStackDepth, void *const pvParameters, UBaseType_t uxPriority, TaskHandle_t *const pxCreatedTask)
Create a new task and add it to the list of tasks that are ready to run.
Internally, within the FreeRTOS implementation, tasks use two blocks of memory. The first block is used to hold the taskns data structures. The second block is used by the task as its stack. If a task is created using xTaskCreate() then both blocks of memory are automatically dynamically allocated inside the xTaskCreate() function. (see https://www.FreeRTOS.org/a00111.html). If a task is created using xTaskCreateStatic() then

Espressif Systems

1147

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
the application writer must provide the required memory. xTaskCreateStatic() therefore allows a task to be created without using any dynamic memory allocation.
See xTaskCreateStatic() for a version that does not use any dynamic memory allocation.
xTaskCreate() can only be used to create a task that has unrestricted access to the entire microcontroller memory map. Systems that include MPU support can alternatively create an MPU constrained task using xTaskCreateRestricted().
Example usage:
// Task to be created. void vTaskCode( void * pvParameters ) {
for( ;; ) {
// Task code goes here. } }
// Function that creates a task. void vOtherFunction( void ) { static uint8_t ucParameterToPass; TaskHandle_t xHandle = NULL;
// Create the task, storing the handle. Note that the passed parameter ucParameterToPass
// must exist for the lifetime of the task, so in this case is declared static. If it was just an
// an automatic stack variable it might no longer exist, or at least have been corrupted, by the time
// the new task attempts to access it. xTaskCreate( vTaskCode, "NAME", STACK_SIZE, &ucParameterToPass, tskIDLE_ PRIORITY, &xHandle ); configASSERT( xHandle );
// Use the handle to delete the task. if( xHandle != NULL ) {
vTaskDelete( xHandle ); } }
Return pdPASS if the task was successfully created and added to a ready list, otherwise an error code defined in the file projdefs.h
Note If program uses thread local variables (ones specified with o__threadpkeyword) then storage for them will be allocated on the taskns stack.
Parameters · pvTaskCode: Pointer to the task entry function. Tasks must be implemented to never return (i.e. continuous loop), or should be terminated using vTaskDelete function. · pcName: A descriptive name for the task. This is mainly used to facilitate debugging. Max length defined by configMAX_TASK_NAME_LEN - default is 16. · usStackDepth: The size of the task stack specified as the number of bytes. Note that this differs from vanilla FreeRTOS. · pvParameters: Pointer that will be used as the parameter for the task being created. · uxPriority: The priority at which the task should run. Systems that include MPU support can optionally create tasks in a privileged (system) mode by setting bit portPRIVILEGE_BIT of the priority parameter. For example, to create a privileged task at priority 2 the uxPriority parameter should be set to ( 2 | portPRIVILEGE_BIT ). · pvCreatedTask: Used to pass back a handle by which the created task can be referenced.

Espressif Systems

1148

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

TaskHandle_t xTaskCreateStaticPinnedToCore(TaskFunction_t pvTaskCode, const char

*const pcName, const uint32_t ulStack-

Depth, void *const pvParameters, UBase-

Type_t uxPriority, StackType_t *const pxS-

tackBuffer, StaticTask_t *const pxTaskBuffer,

Create a new task with a specified affinity.

const BaseType_t xCoreID)

This function is similar to xTaskCreateStatic, but allows specifying task affinity in an SMP system.

Return If neither pxStackBuffer or pxTaskBuffer are NULL, then the task will be created and pdPASS is returned. If either pxStackBuffer or pxTaskBuffer are NULL then the task will not be created and errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY is returned.
Parameters · pvTaskCode: Pointer to the task entry function. Tasks must be implemented to never return (i.e. continuous loop), or should be terminated using vTaskDelete function. · pcName: A descriptive name for the task. This is mainly used to facilitate debugging. The maximum length of the string is defined by configMAX_TASK_NAME_LEN in FreeRTOSConfig.h. · ulStackDepth: The size of the task stack specified as the number of bytes. Note that this differs from vanilla FreeRTOS. · pvParameters: Pointer that will be used as the parameter for the task being created. · uxPriority: The priority at which the task will run. · pxStackBuffer: Must point to a StackType_t array that has at least ulStackDepth indexes the array will then be used as the taskns stack, removing the need for the stack to be allocated dynamically. · pxTaskBuffer: Must point to a variable of type StaticTask_t, which will then be used to hold the taskns data structures, removing the need for the memory to be allocated dynamically. · xCoreID: If the value is tskNO_AFFINITY, the created task is not pinned to any CPU, and the scheduler can run it on any core available. Values 0 or 1 indicate the index number of the CPU which the task should be pinned to. Specifying values larger than (portNUM_PROCESSORS - 1) will cause the function to fail.

static TaskHandle_t xTaskCreateStatic(TaskFunction_t pvTaskCode, const char *const pcName, const uint32_t ulStackDepth, void *const pvParameters, UBaseType_t uxPriority, StackType_t *const puxStackBuffer, StaticTask_t *const pxTaskBuffer)
Create a new task and add it to the list of tasks that are ready to run.

Internally, within the FreeRTOS implementation, tasks use two blocks of memory. The first block is used to hold the taskns data structures. The second block is used by the task as its stack. If a task is created using xTaskCreate() then both blocks of memory are automatically dynamically allocated inside the xTaskCreate() function. (see http://www.freertos.org/a00111.html). If a task is created using xTaskCreateStatic() then the application writer must provide the required memory. xTaskCreateStatic() therefore allows a task to be created without using any dynamic memory allocation.

Example usage:

// Dimensions the buffer that the task being created will use as its stack. // NOTE: This is the number of bytes the stack will hold, not the number of // words as found in vanilla FreeRTOS. #define STACK_SIZE 200

// Structure that will hold the TCB of the task being created. StaticTask_t xTaskBuffer;

// Buffer that the task being created will use as its stack. Note this is // an array of StackType_t variables. The size of StackType_t is dependent on // the RTOS port. StackType_t xStack[ STACK_SIZE ];

(continues on next page)

Espressif Systems

1149

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)
// Function that implements the task being created. void vTaskCode( void * pvParameters ) {
// The parameter value is expected to be 1 as 1 is passed in the // pvParameters value in the call to xTaskCreateStatic(). configASSERT( ( uint32_t ) pvParameters == 1UL );

for( ;; ) {
// Task code goes here. } }

// Function that creates a task. void vOtherFunction( void ) {
TaskHandle_t xHandle = NULL;

// Create the task without using any dynamic memory allocation.

xHandle = xTaskCreateStatic(

vTaskCode,

// Function that implements the task.

"NAME",

// Text name for the task.

STACK_SIZE,

// Stack size in bytes, not words.

( void * ) 1, // Parameter passed into the task.

tskIDLE_PRIORITY,// Priority at which the task is created.

xStack,

// Array to use as the task's stack.

&xTaskBuffer ); // Variable to hold the task's data

structure.

// puxStackBuffer and pxTaskBuffer were not NULL, so the task will have // been created, and xHandle will be the task's handle. Use the handle // to suspend the task. vTaskSuspend( xHandle ); }

Return If neither pxStackBuffer or pxTaskBuffer are NULL, then the task will be created and pdPASS is returned. If either pxStackBuffer or pxTaskBuffer are NULL then the task will not be created and errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY is returned.
Note If program uses thread local variables (ones specified with o__threadpkeyword) then storage for them will be allocated on the taskns stack.
Parameters · pvTaskCode: Pointer to the task entry function. Tasks must be implemented to never return (i.e. continuous loop), or should be terminated using vTaskDelete function. · pcName: A descriptive name for the task. This is mainly used to facilitate debugging. The maximum length of the string is defined by configMAX_TASK_NAME_LEN in FreeRTOSConfig.h. · ulStackDepth: The size of the task stack specified as the number of bytes. Note that this differs from vanilla FreeRTOS. · pvParameters: Pointer that will be used as the parameter for the task being created. · uxPriority: The priority at which the task will run. · pxStackBuffer: Must point to a StackType_t array that has at least ulStackDepth indexes the array will then be used as the taskns stack, removing the need for the stack to be allocated dynamically. · pxTaskBuffer: Must point to a variable of type StaticTask_t, which will then be used to hold the taskns data structures, removing the need for the memory to be allocated dynamically.
void vTaskAllocateMPURegions(TaskHandle_t xTask, const MemoryRegion_t *const pxRegions)
Only available when configSUPPORT_DYNAMIC_ALLOCATION is set to 1.
xTaskCreateRestricted() should only be used in systems that include an MPU implementation.

Espressif Systems

1150

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Create a new task and add it to the list of tasks that are ready to run. The function parameters define the memory regions and associated access permissions allocated to the task.
See xTaskCreateRestrictedStatic() for a version that does not use any dynamic memory allocation.
return pdPASS if the task was successfully created and added to a ready list, otherwise an error code defined in the file projdefs.h
Parameters · pxTaskDefinition: Pointer to a structure that contains a member for each of the normal xTaskCreate() parameters (see the xTaskCreate() API documentation) plus an optional stack buffer and the memory region definitions. · pxCreatedTask: Used to pass back a handle by which the created task can be referenced.
Example usage:

// Create an TaskParameters_t structure that defines the task to be created.

static const TaskParameters_t xCheckTaskParameters =

{

vATask,

// pvTaskCode - the function that implements the task.

"ATask", // pcName - just a text name for the task to assist debugging.

100,

// usStackDepth - the stack size DEFINED IN WORDS.

NULL,

// pvParameters - passed into the task function as the function

parameters.

( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the

portPRIVILEGE_BIT if the task should run in a privileged state.

cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack.

// xRegions - Allocate up to three separate memory regions for access by

// the task, with appropriate access permissions. Different processors have

// different memory alignment requirements - refer to the FreeRTOS

documentation

// for full information.

{

// Base address

Length Parameters

{ cReadWriteArray,

32,

portMPU_REGION_READ_WRITE },

{ cReadOnlyArray,

32,

portMPU_REGION_READ_ONLY },

{ cPrivilegedOnlyAccessArray, 128, portMPU_REGION_PRIVILEGED_READ_

WRITE }

}

};

int main( void ) { TaskHandle_t xHandle;

// Create a task from the const structure defined above. The task handle // is requested (the second parameter is not NULL) but in this case just for // demonstration purposes as its not actually used. xTaskCreateRestricted( &xRegTest1Parameters, &xHandle );

// Start the scheduler. vTaskStartScheduler();

// Will only get here if there was insufficient memory to create the idle // and/or timer task. for( ;; ); }

Only available when configSUPPORT_STATIC_ALLOCATION is set to 1.
xTaskCreateRestrictedStatic() should only be used in systems that include an MPU implementation.
Internally, within the FreeRTOS implementation, tasks use two blocks of memory. The first block is used to hold the taskns data structures. The second block is used by the task as its stack. If a task is created using

Espressif Systems

1151

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

xTaskCreateRestricted() then the stack is provided by the application writer, and the memory used to hold the taskns data structure is automatically dynamically allocated inside the xTaskCreateRestricted() function. If a task is created using xTaskCreateRestrictedStatic() then the application writer must provide the memory used to hold the taskns data structures too. xTaskCreateRestrictedStatic() therefore allows a memory protected task to be created without using any dynamic memory allocation.
return pdPASS if the task was successfully created and added to a ready list, otherwise an error code defined in the file projdefs.h
Parameters · pxTaskDefinition: Pointer to a structure that contains a member for each of the normal xTaskCreate() parameters (see the xTaskCreate() API documentation) plus an optional stack buffer and the memory region definitions. If configSUPPORT_STATIC_ALLOCATION is set to 1 the structure contains an additional member, which is used to point to a variable of type StaticTask_t which is then used to hold the taskns data structure. · pxCreatedTask: Used to pass back a handle by which the created task can be referenced.
Example usage:

// Create an TaskParameters_t structure that defines the task to be created.

// The StaticTask_t variable is only included in the structure when

// configSUPPORT_STATIC_ALLOCATION is set to 1. The PRIVILEGED_DATA macro can

// be used to force the variable into the RTOS kernel's privileged data area.

static PRIVILEGED_DATA StaticTask_t xTaskBuffer;

static const TaskParameters_t xCheckTaskParameters =

{

vATask,

// pvTaskCode - the function that implements the task.

"ATask", // pcName - just a text name for the task to assist debugging.

100,

// usStackDepth - the stack size DEFINED IN BYTES.

NULL,

// pvParameters - passed into the task function as the function

parameters.

( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the

portPRIVILEGE_BIT if the task should run in a privileged state.

cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack.

// xRegions - Allocate up to three separate memory regions for access by

// the task, with appropriate access permissions. Different processors have

// different memory alignment requirements - refer to the FreeRTOS

documentation

// for full information.

{

// Base address

Length Parameters

{ cReadWriteArray,

32,

portMPU_REGION_READ_WRITE },

{ cReadOnlyArray,

32,

portMPU_REGION_READ_ONLY },

{ cPrivilegedOnlyAccessArray, 128, portMPU_REGION_PRIVILEGED_READ_

WRITE }

}

&xTaskBuffer; // Holds the task's data structure. };

int main( void ) { TaskHandle_t xHandle;

// Create a task from the const structure defined above. The task handle // is requested (the second parameter is not NULL) but in this case just for // demonstration purposes as its not actually used. xTaskCreateRestricted( &xRegTest1Parameters, &xHandle );

// Start the scheduler. vTaskStartScheduler();

(continues on next page)

Espressif Systems

1152

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)
// Will only get here if there was insufficient memory to create the idle // and/or timer task. for( ;; ); }

Memory regions are assigned to a restricted task when the task is created by a call to xTaskCreateRestricted(). These regions can be redefined using vTaskAllocateMPURegions().
Example usage:

// Define an array of MemoryRegion_t structures that configures an MPU region

// allowing read/write access for 1024 bytes starting at the beginning of the

// ucOneKByte array. The other two of the maximum 3 definable regions are

// unused so set to zero.

static const MemoryRegion_t xAltRegions[ portNUM_CONFIGURABLE_REGIONS ] =

{

// Base address

Length

Parameters

{ ucOneKByte,

1024,

portMPU_REGION_READ_WRITE },

{ 0,

0,

0 },

{ 0,

0,

0}

};

void vATask( void *pvParameters ) {
// This task was created such that it has access to certain regions of // memory as defined by the MPU configuration. At some point it is // desired that these MPU regions are replaced with that defined in the // xAltRegions const struct above. Use a call to vTaskAllocateMPURegions() // for this purpose. NULL is used as the task handle to indicate that this // function should modify the MPU regions of the calling task. vTaskAllocateMPURegions( NULL, xAltRegions );

// Now the task can continue its function, but from this point on can only // access its stack and the ucOneKByte array (unless any other statically // defined or shared regions have been declared elsewhere). }

Parameters · xTask: The handle of the task being updated. · pxRegions: A pointer to an MemoryRegion_t structure that contains the new memory region definitions.
void vTaskDelete(TaskHandle_t xTaskToDelete) INCLUDE_vTaskDelete must be defined as 1 for this function to be available. See the configuration section for more information.
Remove a task from the RTOS real time kernelns management. The task being deleted will be removed from all ready, blocked, suspended and event lists.
NOTE: The idle task is responsible for freeing the kernel allocated memory from tasks that have been deleted. It is therefore important that the idle task is not starved of microcontroller processing time if your application makes any calls to vTaskDelete (). Memory allocated by the task code is not automatically freed, and should be freed before the task is deleted.
See the demo application file death.c for sample code that utilises vTaskDelete ().
Example usage:
void vOtherFunction( void ) { TaskHandle_t xHandle;

(continues on next page)

Espressif Systems

1153

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
(continued from previous page) // Create the task, storing the handle. xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
// Use the handle to delete the task. vTaskDelete( xHandle ); }
Parameters · xTaskToDelete: The handle of the task to be deleted. Passing NULL will cause the calling task to be deleted.
void vTaskDelay(const TickType_t xTicksToDelay) Delay a task for a given number of ticks. The actual time that the task remains blocked depends on the tick rate. The constant portTICK_PERIOD_MS can be used to calculate real time from the tick rate - with the resolution of one tick period.
INCLUDE_vTaskDelay must be defined as 1 for this function to be available. See the configuration section for more information.
vTaskDelay() specifies a time at which the task wishes to unblock relative to the time at which vTaskDelay() is called. For example, specifying a block period of 100 ticks will cause the task to unblock 100 ticks after vTaskDelay() is called. vTaskDelay() does not therefore provide a good method of controlling the frequency of a periodic task as the path taken through the code, as well as other task and interrupt activity, will effect the frequency at which vTaskDelay() gets called and therefore the time at which the task next executes. See xTaskDelayUntil() for an alternative API function designed to facilitate fixed frequency execution. It does this by specifying an absolute time (rather than a relative time) at which the calling task should unblock.
Example usage:
void vTaskFunction( void * pvParameters ) { // Block for 500ms. const TickType_t xDelay = 500 / portTICK_PERIOD_MS;
for( ;; ) {
// Simply toggle the LED every 500ms, blocking between each toggle. vToggleLED(); vTaskDelay( xDelay ); } }
Parameters · xTicksToDelay: The amount of time, in tick periods, that the calling task should block.
BaseType_t xTaskDelayUntil(TickType_t *const pxPreviousWakeTime, const TickType_t xTimeIncrement)
INCLUDE_xTaskDelayUntil must be defined as 1 for this function to be available. See the configuration section for more information.
Delay a task until a specified time. This function can be used by periodic tasks to ensure a constant execution frequency.
This function differs from vTaskDelay () in one important aspect: vTaskDelay () will cause a task to block for the specified number of ticks from the time vTaskDelay () is called. It is therefore difficult to use vTaskDelay () by itself to generate a fixed execution frequency as the time between a task starting to execute and that task calling vTaskDelay () may not be fixed [the task may take a different path though the code between calls, or may get interrupted or preempted a different number of times each time it executes].
Whereas vTaskDelay () specifies a wake time relative to the time at which the function is called, xTaskDelayUntil () specifies the absolute (exact) time at which it wishes to unblock.

Espressif Systems

1154

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

The macro pdMS_TO_TICKS() can be used to calculate the number of ticks from a time specified in milliseconds with a resolution of one tick period.
Example usage:
// Perform an action every 10 ticks. void vTaskFunction( void * pvParameters ) { TickType_t xLastWakeTime; const TickType_t xFrequency = 10; BaseType_t xWasDelayed;
// Initialise the xLastWakeTime variable with the current time. xLastWakeTime = xTaskGetTickCount (); for( ;; ) {
// Wait for the next cycle. xWasDelayed = xTaskDelayUntil( &xLastWakeTime, xFrequency );
// Perform action here. xWasDelayed value can be used to determine // whether a deadline was missed if the code here took too long. } }

Return Value which can be used to check whether the task was actually delayed. Will be pdTRUE if the task way delayed and pdFALSE otherwise. A task will not be delayed if the next expected wake time is in the past.
Parameters · pxPreviousWakeTime: Pointer to a variable that holds the time at which the task was last unblocked. The variable must be initialised with the current time prior to its first use (see the example below). Following this the variable is automatically updated within xTaskDelayUntil (). · xTimeIncrement: The cycle time period. The task will be unblocked at time *pxPreviousWakeTime + xTimeIncrement. Calling xTaskDelayUntil with the same xTimeIncrement parameter value will cause the task to execute with a fixed interface period.
BaseType_t xTaskAbortDelay(TaskHandle_t xTask) INCLUDE_xTaskAbortDelay must be defined as 1 in FreeRTOSConfig.h for this function to be available.
A task will enter the Blocked state when it is waiting for an event. The event it is waiting for can be a temporal event (waiting for a time), such as when vTaskDelay() is called, or an event on an object, such as when xQueueReceive() or ulTaskNotifyTake() is called. If the handle of a task that is in the Blocked state is used in a call to xTaskAbortDelay() then the task will leave the Blocked state, and return from whichever function call placed the task into the Blocked state.
There is no mFromISRnversion of this function as an interrupt would need to know which object a task was blocked on in order to know which actions to take. For example, if the task was blocked on a queue the interrupt handler would then need to know if the queue was locked.
Return If the task referenced by xTask was not in the Blocked state then pdFAIL is returned. Otherwise pdPASS is returned.
Parameters · xTask: The handle of the task to remove from the Blocked state.
UBaseType_t uxTaskPriorityGet(const TaskHandle_t xTask) INCLUDE_uxTaskPriorityGet must be defined as 1 for this function to be available. See the configuration section for more information.
Obtain the priority of any task.
Example usage:

void vAFunction( void ) {

(continues on next page)

Espressif Systems

1155

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

TaskHandle_t xHandle;

(continued from previous page)

// Create a task, storing the handle. xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );

// ...

// Use the handle to obtain the priority of the created task. // It was created with tskIDLE_PRIORITY, but may have changed // it itself. if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY ) {
// The task has changed it's priority. }

// ...

// Is our priority higher than the created task? if( uxTaskPriorityGet( xHandle ) < uxTaskPriorityGet( NULL ) ) {
// Our priority (obtained using NULL handle) is higher. } }

Return The priority of xTask. Parameters
· xTask: Handle of the task to be queried. Passing a NULL handle results in the priority of the calling task being returned.
UBaseType_t uxTaskPriorityGetFromISR(const TaskHandle_t xTask) A version of uxTaskPriorityGet() that can be used from an ISR.
eTaskState eTaskGetState(TaskHandle_t xTask) INCLUDE_eTaskGetState must be defined as 1 for this function to be available. See the configuration section for more information.
Obtain the state of any task. States are encoded by the eTaskState enumerated type.
Return The state of xTask at the time the function was called. Note the state of the task might change between the function being called, and the functions return value being tested by the calling task.
Parameters · xTask: Handle of the task to be queried.
void vTaskGetInfo(TaskHandle_t xTask, TaskStatus_t *pxTaskStatus, BaseType_t xGetFreeStackSpace, eTaskState eState)
configUSE_TRACE_FACILITY must be defined as 1 for this function to be available. See the configuration section for more information.
Populates a TaskStatus_t structure with information about a task.
Example usage:
void vAFunction( void ) { TaskHandle_t xHandle; TaskStatus_t xTaskDetails;

// Obtain the handle of a task from its name. xHandle = xTaskGetHandle( "Task_Name" );

// Check the handle is not NULL. configASSERT( xHandle );

(continues on next page)

Espressif Systems

1156

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)
// Use the handle to obtain further information about the task. vTaskGetInfo( xHandle,
&xTaskDetails, pdTRUE, // Include the high water mark in xTaskDetails. eInvalid ); // Include the task state in xTaskDetails. }
Parameters · xTask: Handle of the task being queried. If xTask is NULL then information will be returned about the calling task. · pxTaskStatus: A pointer to the TaskStatus_t structure that will be filled with information about the task referenced by the handle passed using the xTask parameter. · xGetFreeStackSpace: The TaskStatus_t structure contains a member to report the stack high water mark of the task being queried. Calculating the stack high water mark takes a relatively long time, and can make the system temporarily unresponsive - so the xGetFreeStackSpace parameter is provided to allow the high water mark checking to be skipped. The high watermark value will only be written to the TaskStatus_t structure if xGetFreeStackSpace is not set to pdFALSE; · eState: The TaskStatus_t structure contains a member to report the state of the task being queried. Obtaining the task state is not as fast as a simple assignment - so the eState parameter is provided to allow the state information to be omitted from the TaskStatus_t structure. To obtain state information then set eState to eInvalid - otherwise the value passed in eState will be reported as the task state in the TaskStatus_t structure.
void vTaskPrioritySet(TaskHandle_t xTask, UBaseType_t uxNewPriority) INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available. See the configuration section for more information.
Set the priority of any task.
A context switch will occur before the function returns if the priority being set is higher than the currently executing task.
Example usage:
void vAFunction( void ) { TaskHandle_t xHandle;
// Create a task, storing the handle. xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
// ...
// Use the handle to raise the priority of the created task. vTaskPrioritySet( xHandle, tskIDLE_PRIORITY + 1 );
// ...
// Use a NULL handle to raise our priority to the same value. vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 ); }
Parameters · xTask: Handle to the task for which the priority is being set. Passing a NULL handle results in the priority of the calling task being set. · uxNewPriority: The priority to which the task will be set.
void vTaskSuspend(TaskHandle_t xTaskToSuspend) INCLUDE_vTaskSuspend must be defined as 1 for this function to be available. See the configuration section for more information.

Espressif Systems

1157

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Suspend any task. When suspended a task will never get any microcontroller processing time, no matter what its priority. Calls to vTaskSuspend are not accumulative - i.e. calling vTaskSuspend () twice on the same task still only requires one call to vTaskResume () to ready the suspended task. Example usage:
void vAFunction( void ) { TaskHandle_t xHandle;
// Create a task, storing the handle. xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
// ...
// Use the handle to suspend the created task. vTaskSuspend( xHandle );
// ...
// The created task will not run during this period, unless // another task calls vTaskResume( xHandle ).
//...

// Suspend ourselves. vTaskSuspend( NULL );
// We cannot get here unless another task calls vTaskResume // with our handle as the parameter. }
Parameters · xTaskToSuspend: Handle to the task being suspended. Passing a NULL handle will cause the calling task to be suspended.
void vTaskResume(TaskHandle_t xTaskToResume) INCLUDE_vTaskSuspend must be defined as 1 for this function to be available. See the configuration section for more information.
Resumes a suspended task.
A task that has been suspended by one or more calls to vTaskSuspend () will be made available for running again by a single call to vTaskResume ().
Example usage:
void vAFunction( void ) { TaskHandle_t xHandle;
// Create a task, storing the handle. xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
// ...
// Use the handle to suspend the created task. vTaskSuspend( xHandle );
(continues on next page)

Espressif Systems

1158

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

// ...

(continued from previous page)

// The created task will not run during this period, unless // another task calls vTaskResume( xHandle ).

//...

// Resume the suspended task ourselves. vTaskResume( xHandle );
// The created task will once again get microcontroller processing // time in accordance with its priority within the system. }
Parameters · xTaskToResume: Handle to the task being readied.
BaseType_t xTaskResumeFromISR(TaskHandle_t xTaskToResume) INCLUDE_xTaskResumeFromISR must be defined as 1 for this function to be available. See the configuration section for more information.
An implementation of vTaskResume() that can be called from within an ISR.
A task that has been suspended by one or more calls to vTaskSuspend () will be made available for running again by a single call to xTaskResumeFromISR ().
xTaskResumeFromISR() should not be used to synchronise a task with an interrupt if there is a chance that the interrupt could arrive prior to the task being suspended - as this can lead to interrupts being missed. Use of a semaphore as a synchronisation mechanism would avoid this eventuality.
Return pdTRUE if resuming the task should result in a context switch, otherwise pdFALSE. This is used by the ISR to determine if a context switch may be required following the ISR.
Parameters · xTaskToResume: Handle to the task being readied.
void vTaskStartScheduler(void) Starts the real time kernel tick processing. After calling the kernel has control over which tasks are executed and when.
NOTE: In ESP-IDF the scheduler is started automatically during application startup, vTaskStartScheduler() should not be called from ESP-IDF applications.
See the demo application file main.c for an example of creating tasks and starting the kernel.
Example usage:
void vAFunction( void ) {
// Create at least one task before starting the kernel. xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
// Start the real time kernel with preemption. vTaskStartScheduler ();
// Will not get here unless a task calls vTaskEndScheduler () }
void vTaskEndScheduler(void) NOTE: At the time of writing only the x86 real mode port, which runs on a PC in place of DOS, implements this function.
Stops the real time kernel tick. All created tasks will be automatically deleted and multitasking (either preemptive or cooperative) will stop. Execution then resumes from the point where vTaskStartScheduler () was

Espressif Systems

1159

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

called, as if vTaskStartScheduler () had just returned.
See the demo application file main. c in the demo/PC directory for an example that uses vTaskEndScheduler ().
vTaskEndScheduler () requires an exit function to be defined within the portable layer (see vPortEndScheduler () in port. c for the PC port). This performs hardware specific operations such as stopping the kernel tick.
vTaskEndScheduler () will cause all of the resources allocated by the kernel to be freed - but will not free resources allocated by application tasks.
Example usage:
void vTaskCode( void * pvParameters ) {
for( ;; ) {
// Task code goes here.
// At some point we want to end the real time kernel processing // so call ... vTaskEndScheduler (); } }
void vAFunction( void ) {
// Create at least one task before starting the kernel. xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
// Start the real time kernel with preemption. vTaskStartScheduler ();
// Will only get here when the vTaskCode () task has called // vTaskEndScheduler (). When we get here we are back to single task // execution. }
void vTaskSuspendAll(void) Suspends the scheduler without disabling interrupts. Context switches will not occur while the scheduler is suspended.
After calling vTaskSuspendAll () the calling task will continue to execute without risk of being swapped out until a call to xTaskResumeAll () has been made.
API functions that have the potential to cause a context switch (for example, vTaskDelayUntil(), xQueueSend(), etc.) must not be called while the scheduler is suspended.
Example usage:
void vTask1( void * pvParameters ) {
for( ;; ) {
// Task code goes here.
// ...
// At some point the task wants to perform a long operation during // which it does not want to get swapped out. It cannot use // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the // operation may cause interrupts to be missed - including the // ticks.
(continues on next page)

Espressif Systems

1160

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page) // Prevent the real time kernel swapping out the task. vTaskSuspendAll ();
// Perform the operation here. There is no need to use critical // sections as we have all the microcontroller processing time. // During this time interrupts will still operate and the kernel // tick count will be maintained.
// ...
// The operation is complete. Restart the kernel. xTaskResumeAll (); } }
BaseType_t xTaskResumeAll(void) Resumes scheduler activity after it was suspended by a call to vTaskSuspendAll().
xTaskResumeAll() only resumes the scheduler. It does not unsuspend tasks that were previously suspended by a call to vTaskSuspend().
Example usage:
void vTask1( void * pvParameters ) {
for( ;; ) {
// Task code goes here.
// ...
// At some point the task wants to perform a long operation during // which it does not want to get swapped out. It cannot use // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the // operation may cause interrupts to be missed - including the // ticks.
// Prevent the real time kernel swapping out the task. vTaskSuspendAll ();
// Perform the operation here. There is no need to use critical // sections as we have all the microcontroller processing time. // During this time interrupts will still operate and the real // time kernel tick count will be maintained.
// ...
// The operation is complete. Restart the kernel. We want to force // a context switch - but there is no point if resuming the scheduler // caused a context switch already. if( !xTaskResumeAll () ) {
taskYIELD (); } } }
Return If resuming the scheduler caused a context switch then pdTRUE is returned, otherwise pdFALSE is returned.
TickType_t xTaskGetTickCount(void)
Return The count of ticks since vTaskStartScheduler was called.

Espressif Systems

1161

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

TickType_t xTaskGetTickCountFromISR(void)
This is a version of xTaskGetTickCount() that is safe to be called from an ISR - provided that TickType_t is the natural word size of the microcontroller being used or interrupt nesting is either not supported or not being used.
Return The count of ticks since vTaskStartScheduler was called.
UBaseType_t uxTaskGetNumberOfTasks(void)
Return The number of tasks that the real time kernel is currently managing. This includes all ready, blocked and suspended tasks. A task that has been deleted but not yet freed by the idle task will also be included in the count.
char *pcTaskGetName(TaskHandle_t xTaskToQuery)
Return The text (human readable) name of the task referenced by the handle xTaskToQuery. A task can query its own name by either passing in its own handle, or by setting xTaskToQuery to NULL.
TaskHandle_t xTaskGetHandle(const char *pcNameToQuery) NOTE: This function takes a relatively long time to complete and should be used sparingly.
Return The handle of the task that has the human readable name pcNameToQuery. NULL is returned if no matching name is found. INCLUDE_xTaskGetHandle must be set to 1 in FreeRTOSConfig.h for pcTaskGetHandle() to be available.
UBaseType_t uxTaskGetStackHighWaterMark(TaskHandle_t xTask) Returns the high water mark of the stack associated with xTask.
INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in FreeRTOSConfig.h for this function to be available.
Returns the high water mark of the stack associated with xTask. That is, the minimum free stack space there has been (in bytes not words, unlike vanilla FreeRTOS) since the task started. The smaller the returned number the closer the task has come to overflowing its stack.
uxTaskGetStackHighWaterMark() and uxTaskGetStackHighWaterMark2() are the same except for their return type. Using configSTACK_DEPTH_TYPE allows the user to determine the return type. It gets around the problem of the value overflowing on 8-bit types without breaking backward compatibility for applications that expect an 8-bit return type.
Return The smallest amount of free stack space there has been (in bytes not words, unlike vanilla FreeRTOS) since the task referenced by xTask was created.
Parameters · xTask: Handle of the task associated with the stack to be checked. Set xTask to NULL to check the stack of the calling task.
configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2(TaskHandle_t xTask) Returns the start of the stack associated with xTask.
INCLUDE_uxTaskGetStackHighWaterMark2 must be set to 1 in FreeRTOSConfig.h for this function to be available.
Returns the high water mark of the stack associated with xTask. That is, the minimum free stack space there has been (in words, so on a 32 bit machine a value of 1 means 4 bytes) since the task started. The smaller the returned number the closer the task has come to overflowing its stack.
uxTaskGetStackHighWaterMark() and uxTaskGetStackHighWaterMark2() are the same except for their return type. Using configSTACK_DEPTH_TYPE allows the user to determine the return type. It gets around the problem of the value overflowing on 8-bit types without breaking backward compatibility for applications that expect an 8-bit return type.
Return The smallest amount of free stack space there has been (in words, so actual spaces on the stack rather than bytes) since the task referenced by xTask was created.
Parameters · xTask: Handle of the task associated with the stack to be checked. Set xTask to NULL to check the stack of the calling task.

Espressif Systems

1162

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

uint8_t *pxTaskGetStackStart(TaskHandle_t xTask) Returns the start of the stack associated with xTask.

INCLUDE_pxTaskGetStackStart must be set to 1 in FreeRTOSConfig.h for this function to be available.

Returns the lowest stack memory address, regardless of whether the stack grows up or down.

Return A pointer to the start of the stack. Parameters
· xTask: Handle of the task associated with the stack returned. Set xTask to NULL to return the stack of the calling task.

void vTaskSetApplicationTaskTag(TaskHandle_t xTask, TaskHookFunction_t pxHookFunction) Sets pxHookFunction to be the task hook function used by the task xTask.

Parameters · xTask: Handle of the task to set the hook function for Passing xTask as NULL has the effect of setting the calling tasks hook function. · pxHookFunction: Pointer to the hook function.

TaskHookFunction_t xTaskGetApplicationTaskTag(TaskHandle_t xTask) Returns the pxHookFunction value assigned to the task xTask. Do not call from an interrupt service routine call xTaskGetApplicationTaskTagFromISR() instead.

TaskHookFunction_t xTaskGetApplicationTaskTagFromISR(TaskHandle_t xTask) Returns the pxHookFunction value assigned to the task xTask. Can be called from an interrupt service routine.

void vTaskSetThreadLocalStoragePointer(TaskHandle_t xTaskToSet, BaseType_t xIndex, void *pvValue)
Set local storage pointer specific to the given task.

Each task contains an array of pointers that is dimensioned by the configNUM_THREAD_LOCAL_STORAGE_POINTERS setting in FreeRTOSConfig.h. The kernel does not use the pointers itself, so the application writer can use the pointers for any purpose they wish.

Parameters

· xTaskToSet: Task to set thread local storage pointer for

· xIndex:

The index of the pointer to set,

figNUM_THREAD_LOCAL_STORAGE_POINTERS - 1.

· pvValue: Pointer value to set.

from 0 to con-

void *pvTaskGetThreadLocalStoragePointer(TaskHandle_t xTaskToQuery, BaseType_t xIndex)
Get local storage pointer specific to the given task.

Each task contains an array of pointers that is dimensioned by the configNUM_THREAD_LOCAL_STORAGE_POINTERS setting in FreeRTOSConfig.h. The kernel does not use the pointers itself, so the application writer can use the pointers for any purpose they wish.

Return Pointer value

Parameters

· xTaskToQuery: Task to get thread local storage pointer for

· xIndex:

The index of the pointer to get,

figNUM_THREAD_LOCAL_STORAGE_POINTERS - 1.

from 0 to con-

void vTaskSetThreadLocalStoragePointerAndDelCallback(TaskHandle_t xTaskToSet, BaseType_t xIndex, void *pvValue, TlsDeleteCallbackFunction_t pvDelCallback)
Set local storage pointer and deletion callback.

Each task contains an array of pointers that is dimensioned by the configNUM_THREAD_LOCAL_STORAGE_POINTERS setting in FreeRTOSConfig.h. The kernel does not use the pointers itself, so the application writer can use the pointers for any purpose they wish.

Local storage pointers set for a task can reference dynamically allocated resources. This function is similar to vTaskSetThreadLocalStoragePointer, but provides a way to release these resources when the task gets deleted.

Espressif Systems

1163

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

For each pointer, a callback function can be set. This function will be called when task is deleted, with the local storage pointer index and value as arguments.

Parameters

· xTaskToSet: Task to set thread local storage pointer for

· xIndex:

The index of the pointer to set, from 0 to con-

figNUM_THREAD_LOCAL_STORAGE_POINTERS - 1.

· pvValue: Pointer value to set.

· pvDelCallback: Function to call to dispose of the local storage pointer when the task is deleted.

void vApplicationGetIdleTaskMemory(StaticTask_t **ppxIdleTaskTCBBuffer,

Stack-

Type_t

**ppxIdleTaskStackBuffer,

uint32_t

*pulIdleTaskStackSize) This function is used to provide a statically allocated block of memory to FreeRTOS to hold the Idle Task TCB.

This function is required when configSUPPORT_STATIC_ALLOCATION is set. For more information see

this URI: https://www.FreeRTOS.org/a00110.html#configSUPPORT_STATIC_ALLOCATION

Parameters · ppxIdleTaskTCBBuffer: A handle to a statically allocated TCB buffer · ppxIdleTaskStackBuffer: A handle to a statically allocated Stack buffer for thie idle task · pulIdleTaskStackSize: A pointer to the number of elements that will fit in the allocated stack buffer

BaseType_t xTaskCallApplicationTaskHook(TaskHandle_t xTask, void *pvParameter) Calls the hook function associated with xTask. Passing xTask as NULL has the effect of calling the Running tasks (the calling task) hook function.

Parameters · xTask: Handle of the task to call the hook for. · pvParameter: Parameter passed to the hook function for the task to interpret as it wants. The return value is the value returned by the task hook function registered by the user.

TaskHandle_t xTaskGetIdleTaskHandle(void) xTaskGetIdleTaskHandle() is only available if INCLUDE_xTaskGetIdleTaskHandle is set to 1 in FreeRTOSConfig.h.

Simply returns the handle of the idle task. It is not valid to call xTaskGetIdleTaskHandle() before the scheduler has been started.

UBaseType_t uxTaskGetSystemState(TaskStatus_t *const pxTaskStatusArray, const UBase-
Type_t uxArraySize, uint32_t *const pulTotalRunTime) configUSE_TRACE_FACILITY must be defined as 1 in FreeRTOSConfig.h for uxTaskGetSystemState() to
be available.

uxTaskGetSystemState() populates an TaskStatus_t structure for each task in the system. TaskStatus_t structures contain, among other things, members for the task handle, task name, task priority, task state, and total amount of run time consumed by the task. See the TaskStatus_t structure definition in this file for the full member list.

NOTE: This function is intended for debugging use only as its use results in the scheduler remaining suspended for an extended period.

Example usage:

// This example demonstrates how a human readable table of run time stats // information is generated from raw data provided by uxTaskGetSystemState(). // The human readable table is written to pcWriteBuffer void vTaskGetRunTimeStats( char *pcWriteBuffer ) { TaskStatus_t *pxTaskStatusArray; volatile UBaseType_t uxArraySize, x; uint32_t ulTotalRunTime, ulStatsAsPercentage;

// Make sure the write buffer does not contain a string.

(continues on next page)

Espressif Systems

1164

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

*pcWriteBuffer = 0x00;

(continued from previous page)

// Take a snapshot of the number of tasks in case it changes while this // function is executing. uxArraySize = uxTaskGetNumberOfTasks();

// Allocate a TaskStatus_t structure for each task. An array could be // allocated statically at compile time. pxTaskStatusArray = pvPortMalloc( uxArraySize * sizeof( TaskStatus_t ) );

if( pxTaskStatusArray != NULL ) {
// Generate raw status information about each task. uxArraySize = uxTaskGetSystemState( pxTaskStatusArray, uxArraySize, & ulTotalRunTime );

// For percentage calculations. ulTotalRunTime /= 100UL;

// Avoid divide by zero errors. if( ulTotalRunTime > 0 ) {
// For each populated position in the pxTaskStatusArray array, // format the raw data as human readable ASCII data for( x = 0; x < uxArraySize; x++ ) {
// What percentage of the total run time has the task used? // This will always be rounded down to the nearest integer. // ulTotalRunTimeDiv100 has already been divided by 100. ulStatsAsPercentage = pxTaskStatusArray[ x ].ulRunTimeCounter / ulTotalRunTime;

if( ulStatsAsPercentage > 0UL ) {
sprintf( pcWriteBuffer, "%s\t\t%lu\t\t%lu%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter, ulStatsAsPercentage );
} else {
// If the percentage is zero here then the task has // consumed less than 1% of the total run time. sprintf( pcWriteBuffer, "%s\t\t%lu\t\t<1%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter ); }

pcWriteBuffer += strlen( ( char * ) pcWriteBuffer ); } }

// The array is no longer needed, free the memory it consumes. vPortFree( pxTaskStatusArray ); } }

Return The number of TaskStatus_t structures that were populated by uxTaskGetSystemState(). This should equal the number returned by the uxTaskGetNumberOfTasks() API function, but will be zero if the value passed in the uxArraySize parameter was too small.
Parameters · pxTaskStatusArray: A pointer to an array of TaskStatus_t structures. The array must contain at least one TaskStatus_t structure for each task that is under the control of the RTOS. The number

Espressif Systems

1165

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

of tasks under the control of the RTOS can be determined using the uxTaskGetNumberOfTasks() API function. · uxArraySize: The size of the array pointed to by the pxTaskStatusArray parameter. The size is specified as the number of indexes in the array, or the number of TaskStatus_t structures contained in the array, not by the number of bytes in the array. · pulTotalRunTime: If configGENERATE_RUN_TIME_STATS is set to 1 in FreeRTOSConfig.h then *pulTotalRunTime is set by uxTaskGetSystemState() to the total run time (as defined by the run time stats clock, see https://www.FreeRTOS.org/rtos-run-time-stats.html) since the target booted. pulTotalRunTime can be set to NULL to omit the total run time information.
void vTaskList(char *pcWriteBuffer) List all the current tasks.
configUSE_TRACE_FACILITY and configUSE_STATS_FORMATTING_FUNCTIONS must both be defined as 1 for this function to be available. See the configuration section of the FreeRTOS.org website for more information.
NOTE 1: This function will disable interrupts for its duration. It is not intended for normal application runtime use but as a debug aid.
Lists all the current tasks, along with their current state and stack usage high water mark.
Tasks are reported as blocked (mBn), ready (mRn), deleted (mDn) or suspended (mSn).
PLEASE NOTE:
This function is provided for convenience only, and is used by many of the demo applications. Do not consider it to be part of the scheduler.
vTaskList() calls uxTaskGetSystemState(), then formats part of the uxTaskGetSystemState() output into a human readable table that displays task names, states and stack usage.
vTaskList() has a dependency on the sprintf() C library function that might bloat the code size, use a lot of stack, and provide different results on different platforms. An alternative, tiny, third party, and limited functionality implementation of sprintf() is provided in many of the FreeRTOS/Demo sub-directories in a file called printfstdarg.c (note printf-stdarg.c does not provide a full snprintf() implementation!).
It is recommended that production systems call uxTaskGetSystemState() directly to get access to raw stats data, rather than indirectly through a call to vTaskList().
Parameters · pcWriteBuffer: A buffer into which the above mentioned details will be written, in ASCII form. This buffer is assumed to be large enough to contain the generated report. Approximately 40 bytes per task should be sufficient.
void vTaskGetRunTimeStats(char *pcWriteBuffer) Get the state of running tasks as a string
configGENERATE_RUN_TIME_STATS and configUSE_STATS_FORMATTING_FUNCTIONS must both be defined as 1 for this function to be available. The application must also then provide definitions for portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and portGET_RUN_TIME_COUNTER_VALUE() to configure a peripheral timer/counter and return the timers current count value respectively. The counter should be at least 10 times the frequency of the tick count.
NOTE 1: This function will disable interrupts for its duration. It is not intended for normal application runtime use but as a debug aid.
Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total accumulated execution time being stored for each task. The resolution of the accumulated time value depends on the frequency of the timer configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro. Calling vTaskGetRunTimeStats() writes the total execution time of each task into a buffer, both as an absolute count value and as a percentage of the total system execution time.
NOTE 2:
This function is provided for convenience only, and is used by many of the demo applications. Do not consider it to be part of the scheduler.

Espressif Systems

1166

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

vTaskGetRunTimeStats() calls uxTaskGetSystemState(), then formats part of the uxTaskGetSystemState() output into a human readable table that displays the amount of time each task has spent in the Running state in both absolute and percentage terms.
vTaskGetRunTimeStats() has a dependency on the sprintf() C library function that might bloat the code size, use a lot of stack, and provide different results on different platforms. An alternative, tiny, third party, and limited functionality implementation of sprintf() is provided in many of the FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note printf-stdarg.c does not provide a full snprintf() implementation!).
It is recommended that production systems call uxTaskGetSystemState() directly to get access to raw stats data, rather than indirectly through a call to vTaskGetRunTimeStats().
Parameters · pcWriteBuffer: A buffer into which the execution times will be written, in ASCII form. This buffer is assumed to be large enough to contain the generated report. Approximately 40 bytes per task should be sufficient.
uint32_t ulTaskGetIdleRunTimeCounter(void) configGENERATE_RUN_TIME_STATS and configUSE_STATS_FORMATTING_FUNCTIONS must both be defined as 1 for this function to be available. The application must also then provide definitions for portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and portGET_RUN_TIME_COUNTER_VALUE() to configure a peripheral timer/counter and return the timers current count value respectively. The counter should be at least 10 times the frequency of the tick count.
Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total accumulated execution time being stored for each task. The resolution of the accumulated time value depends on the frequency of the timer configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro. While uxTaskGetSystemState() and vTaskGetRunTimeStats() writes the total execution time of each task into a buffer, ulTaskGetIdleRunTimeCounter() returns the total execution time of just the idle task.
Return The total run time of the idle task. This is the amount of time the idle task has actually been executing. The unit of time is dependent on the frequency configured using the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and portGET_RUN_TIME_COUNTER_VALUE() macros.
BaseType_t xTaskGenericNotify(TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue)
See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these functions to be available.
Sends a direct to task notification to a task, with an optional value and action.
Each task has a private array of onotification valuesp(or mnotificationsn), each of which is a 32-bit unsigned integer (uint32_t). The constant configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the array, and (for backward compatibility) defaults to 1 if left undefined. Prior to FreeRTOS V10.4.0 there was only one notification value per task.
Events can be sent to a task using an intermediary object. Examples of such objects are queues, semaphores, mutexes and event groups. Task notifications are a method of sending an event directly to a task without the need for such an intermediary object.
A notification sent to a task can optionally perform an action, such as update, overwrite or increment one of the taskns notification values. In that way task notifications can be used to send data to a task, or be used as light weight and fast binary or counting semaphores.
A task can use xTaskNotifyWaitIndexed() to [optionally] block to wait for a notification to be pending, or ulTaskNotifyTakeIndexed() to [optionally] block to wait for a notification value to have a non-zero value. The task does not consume any CPU time while it is in the Blocked state.
A notification sent to a task will remain pending until it is cleared by the task calling xTaskNotifyWaitIndexed() or ulTaskNotifyTakeIndexed() (or their un-indexed equivalents). If the task was already in the Blocked state to wait for a notification when the notification arrives then the task will automatically be removed from the Blocked state (unblocked) and the notification cleared.

Espressif Systems

1167

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
NOTE Each notification within the array operates independently - a task can only block on one notification within the array at a time and will not be unblocked by a notification sent to any other array index.
Backward compatibility information: Prior to FreeRTOS V10.4.0 each task had a single onotification valuep , and all task notification API functions operated on that value. Replacing the single notification value with an array of notification values necessitated a new set of API functions that could address specific notifications within the array. xTaskNotify() is the original API function, and remains backward compatible by always operating on the notification value at index 0 in the array. Calling xTaskNotify() is equivalent to calling xTaskNotifyIndexed() with the uxIndexToNotify parameter set to 0.
eSetBits - The target notification value is bitwise ORed with ulValue. xTaskNotifyIndexed() always returns pdPASS in this case.
Parameters · xTaskToNotify: The handle of the task being notified. The handle to a task can be returned from the xTaskCreate() API function used to create the task, and the handle of the currently running task can be obtained by calling xTaskGetCurrentTaskHandle(). · uxIndexToNotify: The index within the target taskns array of notification values to which the notification is to be sent. uxIndexToNotify must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotify() does not have this parameter and always sends notifications to index 0. · ulValue: Data that can be sent with the notification. How the data is used depends on the value of the eAction parameter. · eAction: Specifies how the notification updates the taskns notification value, if at all. Valid values for eAction are as follows:
eIncrement - The target notification value is incremented. ulValue is not used and xTaskNotifyIndexed() always returns pdPASS in this case.
eSetValueWithOverwrite - The target notification value is set to the value of ulValue, even if the task being notified had not yet processed the previous notification at the same array index (the task already had a notification pending at that index). xTaskNotifyIndexed() always returns pdPASS in this case.
eSetValueWithoutOverwrite - If the task being notified did not already have a notification pending at the same array index then the target notification value is set to ulValue and xTaskNotifyIndexed() will return pdPASS. If the task being notified already had a notification pending at the same array index then no action is performed and pdFAIL is returned.
eNoAction - The task receives a notification at the specified array index without the notification value at that index being updated. ulValue is not used and xTaskNotifyIndexed() always returns pdPASS in this case.
pulPreviousNotificationValue - Can be used to pass out the subject taskns notification value before any bits are modified by the notify function.
Return Dependent on the value of eAction. See the description of the eAction parameter.
BaseType_t xTaskGenericNotifyFromISR(TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue, BaseType_t *pxHigherPriorityTaskWoken)
See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these functions to be available.
A version of xTaskNotifyIndexed() that can be used from an interrupt service routine (ISR).
Each task has a private array of onotification valuesp(or mnotificationsn), each of which is a 32-bit unsigned integer (uint32_t). The constant configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the array, and (for backward compatibility) defaults to 1 if left undefined. Prior to FreeRTOS V10.4.0 there was only one notification value per task.
Events can be sent to a task using an intermediary object. Examples of such objects are queues, semaphores, mutexes and event groups. Task notifications are a method of sending an event directly to a task without the need for such an intermediary object.

Espressif Systems

1168

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
A notification sent to a task can optionally perform an action, such as update, overwrite or increment one of the taskns notification values. In that way task notifications can be used to send data to a task, or be used as light weight and fast binary or counting semaphores.
A task can use xTaskNotifyWaitIndexed() to [optionally] block to wait for a notification to be pending, or ulTaskNotifyTakeIndexed() to [optionally] block to wait for a notification value to have a non-zero value. The task does not consume any CPU time while it is in the Blocked state.
A notification sent to a task will remain pending until it is cleared by the task calling xTaskNotifyWaitIndexed() or ulTaskNotifyTakeIndexed() (or their un-indexed equivalents). If the task was already in the Blocked state to wait for a notification when the notification arrives then the task will automatically be removed from the Blocked state (unblocked) and the notification cleared.
NOTE Each notification within the array operates independently - a task can only block on one notification within the array at a time and will not be unblocked by a notification sent to any other array index.
Backward compatibility information: Prior to FreeRTOS V10.4.0 each task had a single onotification valuep , and all task notification API functions operated on that value. Replacing the single notification value with an array of notification values necessitated a new set of API functions that could address specific notifications within the array. xTaskNotifyFromISR() is the original API function, and remains backward compatible by always operating on the notification value at index 0 within the array. Calling xTaskNotifyFromISR() is equivalent to calling xTaskNotifyIndexedFromISR() with the uxIndexToNotify parameter set to 0.
eSetBits - The taskns notification value is bitwise ORed with ulValue. xTaskNotify() always returns pdPASS in this case.
Parameters · uxIndexToNotify: The index within the target taskns array of notification values to which the notification is to be sent. uxIndexToNotify must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyFromISR() does not have this parameter and always sends notifications to index 0. · xTaskToNotify: The handle of the task being notified. The handle to a task can be returned from the xTaskCreate() API function used to create the task, and the handle of the currently running task can be obtained by calling xTaskGetCurrentTaskHandle(). · ulValue: Data that can be sent with the notification. How the data is used depends on the value of the eAction parameter. · eAction: Specifies how the notification updates the taskns notification value, if at all. Valid values for eAction are as follows:
eIncrement - The taskns notification value is incremented. ulValue is not used and xTaskNotify() always returns pdPASS in this case.
eSetValueWithOverwrite - The taskns notification value is set to the value of ulValue, even if the task being notified had not yet processed the previous notification (the task already had a notification pending). xTaskNotify() always returns pdPASS in this case.
eSetValueWithoutOverwrite - If the task being notified did not already have a notification pending then the taskns notification value is set to ulValue and xTaskNotify() will return pdPASS. If the task being notified already had a notification pending then no action is performed and pdFAIL is returned.
eNoAction - The task receives a notification without its notification value being updated. ulValue is not used and xTaskNotify() always returns pdPASS in this case.
Return Dependent on the value of eAction. See the description of the eAction parameter. Parameters
· pxHigherPriorityTaskWoken: xTaskNotifyFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the task to which the notification was sent to leave the Blocked state, and the unblocked task has a priority higher than the currently running task. If xTaskNotifyFromISR() sets this value to pdTRUE then a context switch should be requested before the interrupt is exited. How a context switch is requested from an ISR is dependent on the port - see the documentation page for the port in use.

Espressif Systems

1169

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

BaseType_t xTaskGenericNotifyWait(UBaseType_t uxIndexToWaitOn, uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait)
Waits for a direct to task notification to be pending at a given index within an array of direct to task notifications.
See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this function to be available.
Each task has a private array of onotification valuesp(or mnotificationsn), each of which is a 32-bit unsigned integer (uint32_t). The constant configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the array, and (for backward compatibility) defaults to 1 if left undefined. Prior to FreeRTOS V10.4.0 there was only one notification value per task.
Events can be sent to a task using an intermediary object. Examples of such objects are queues, semaphores, mutexes and event groups. Task notifications are a method of sending an event directly to a task without the need for such an intermediary object.
A notification sent to a task can optionally perform an action, such as update, overwrite or increment one of the taskns notification values. In that way task notifications can be used to send data to a task, or be used as light weight and fast binary or counting semaphores.
A notification sent to a task will remain pending until it is cleared by the task calling xTaskNotifyWaitIndexed() or ulTaskNotifyTakeIndexed() (or their un-indexed equivalents). If the task was already in the Blocked state to wait for a notification when the notification arrives then the task will automatically be removed from the Blocked state (unblocked) and the notification cleared.
A task can use xTaskNotifyWaitIndexed() to [optionally] block to wait for a notification to be pending, or ulTaskNotifyTakeIndexed() to [optionally] block to wait for a notification value to have a non-zero value. The task does not consume any CPU time while it is in the Blocked state.
NOTE Each notification within the array operates independently - a task can only block on one notification within the array at a time and will not be unblocked by a notification sent to any other array index.
Backward compatibility information: Prior to FreeRTOS V10.4.0 each task had a single onotification valuep , and all task notification API functions operated on that value. Replacing the single notification value with an array of notification values necessitated a new set of API functions that could address specific notifications within the array. xTaskNotifyWait() is the original API function, and remains backward compatible by always operating on the notification value at index 0 in the array. Calling xTaskNotifyWait() is equivalent to calling xTaskNotifyWaitIndexed() with the uxIndexToWaitOn parameter set to 0.
Return If a notification was received (including notifications that were already pending when xTaskNotifyWait was called) then pdPASS is returned. Otherwise pdFAIL is returned.
Parameters · uxIndexToWaitOn: The index within the calling taskns array of notification values on which the calling task will wait for a notification to be received. uxIndexToWaitOn must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyWait() does not have this parameter and always waits for notifications on index 0. · ulBitsToClearOnEntry: Bits that are set in ulBitsToClearOnEntry value will be cleared in the calling taskns notification value before the task checks to see if any notifications are pending, and optionally blocks if no notifications are pending. Setting ulBitsToClearOnEntry to ULONG_MAX (if limits.h is included) or 0xffffffffUL (if limits.h is not included) will have the effect of resetting the taskns notification value to 0. Setting ulBitsToClearOnEntry to 0 will leave the taskns notification value unchanged. · ulBitsToClearOnExit: If a notification is pending or received before the calling task exits the xTaskNotifyWait() function then the taskns notification value (see the xTaskNotify() API function) is passed out using the pulNotificationValue parameter. Then any bits that are set in ulBitsToClearOnExit will be cleared in the taskns notification value (note *pulNotificationValue is set before any bits are cleared). Setting ulBitsToClearOnExit to ULONG_MAX (if limits.h is included) or 0xffffffffUL (if limits.h is not included) will have the effect of resetting the taskns notification value to 0 before the function exits. Setting ulBitsToClearOnExit to 0 will leave the taskns notification value unchanged when the function exits (in which case the value passed out in pulNotificationValue will match the taskns notification value).

Espressif Systems

1170

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· pulNotificationValue: Used to pass the taskns notification value out of the function. Note the value passed out will not be effected by the clearing of any bits caused by ulBitsToClearOnExit being non-zero.
· xTicksToWait: The maximum amount of time that the task should wait in the Blocked state for a notification to be received, should a notification not already be pending when xTaskNotifyWait() was called. The task will not consume any processing time while it is in the Blocked state. This is specified in kernel ticks, the macro pdMS_TO_TICKS( value_in_ms ) can be used to convert a time specified in milliseconds to a time specified in ticks.
void vTaskGenericNotifyGiveFromISR(TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, BaseType_t *pxHigherPriorityTaskWoken)
A version of xTaskNotifyGiveIndexed() that can be called from an interrupt service routine (ISR).
See https://www.FreeRTOS.org/RTOS-task-notifications.html for more details.
configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this macro to be available.
Each task has a private array of onotification valuesp(or mnotificationsn), each of which is a 32-bit unsigned integer (uint32_t). The constant configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the array, and (for backward compatibility) defaults to 1 if left undefined. Prior to FreeRTOS V10.4.0 there was only one notification value per task.
Events can be sent to a task using an intermediary object. Examples of such objects are queues, semaphores, mutexes and event groups. Task notifications are a method of sending an event directly to a task without the need for such an intermediary object.
A notification sent to a task can optionally perform an action, such as update, overwrite or increment one of the taskns notification values. In that way task notifications can be used to send data to a task, or be used as light weight and fast binary or counting semaphores.
vTaskNotifyGiveIndexedFromISR() is intended for use when task notifications are used as light weight and faster binary or counting semaphore equivalents. Actual FreeRTOS semaphores are given from an ISR using the xSemaphoreGiveFromISR() API function, the equivalent action that instead uses a task notification is vTaskNotifyGiveIndexedFromISR().
When task notifications are being used as a binary or counting semaphore equivalent then the task being notified should wait for the notification using the ulTaskNotificationTakeIndexed() API function rather than the xTaskNotifyWaitIndexed() API function.
NOTE Each notification within the array operates independently - a task can only block on one notification within the array at a time and will not be unblocked by a notification sent to any other array index.
Backward compatibility information: Prior to FreeRTOS V10.4.0 each task had a single onotification valuep , and all task notification API functions operated on that value. Replacing the single notification value with an array of notification values necessitated a new set of API functions that could address specific notifications within the array. xTaskNotifyFromISR() is the original API function, and remains backward compatible by always operating on the notification value at index 0 within the array. Calling xTaskNotifyGiveFromISR() is equivalent to calling xTaskNotifyGiveIndexedFromISR() with the uxIndexToNotify parameter set to 0.
Parameters · xTaskToNotify: The handle of the task being notified. The handle to a task can be returned from the xTaskCreate() API function used to create the task, and the handle of the currently running task can be obtained by calling xTaskGetCurrentTaskHandle(). · uxIndexToNotify: The index within the target taskns array of notification values to which the notification is to be sent. uxIndexToNotify must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyGiveFromISR() does not have this parameter and always sends notifications to index 0. · pxHigherPriorityTaskWoken: vTaskNotifyGiveFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the task to which the notification was sent to leave the Blocked state, and the unblocked task has a priority higher than the currently running task. If vTaskNotifyGiveFromISR() sets this value to pdTRUE then a context switch should be requested before the interrupt is exited. How a context switch is requested from an ISR is dependent on the port - see the documentation page for the port in use.

Espressif Systems

1171

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
uint32_t ulTaskGenericNotifyTake(UBaseType_t uxIndexToWaitOn, BaseType_t xClearCountOnExit, TickType_t xTicksToWait)
Waits for a direct to task notification on a particular index in the calling taskns notification array in a manner similar to taking a counting semaphore.
See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this function to be available.
Each task has a private array of onotification valuesp(or mnotificationsn), each of which is a 32-bit unsigned integer (uint32_t). The constant configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the array, and (for backward compatibility) defaults to 1 if left undefined. Prior to FreeRTOS V10.4.0 there was only one notification value per task.
Events can be sent to a task using an intermediary object. Examples of such objects are queues, semaphores, mutexes and event groups. Task notifications are a method of sending an event directly to a task without the need for such an intermediary object.
A notification sent to a task can optionally perform an action, such as update, overwrite or increment one of the taskns notification values. In that way task notifications can be used to send data to a task, or be used as light weight and fast binary or counting semaphores.
ulTaskNotifyTakeIndexed() is intended for use when a task notification is used as a faster and lighter weight binary or counting semaphore alternative. Actual FreeRTOS semaphores are taken using the xSemaphoreTake() API function, the equivalent action that instead uses a task notification is ulTaskNotifyTakeIndexed().
When a task is using its notification value as a binary or counting semaphore other tasks should send notifications to it using the xTaskNotifyGiveIndexed() macro, or xTaskNotifyIndex() function with the eAction parameter set to eIncrement.
ulTaskNotifyTakeIndexed() can either clear the taskns notification value at the array index specified by the uxIndexToWaitOn parameter to zero on exit, in which case the notification value acts like a binary semaphore, or decrement the notification value on exit, in which case the notification value acts like a counting semaphore.
A task can use ulTaskNotifyTakeIndexed() to [optionally] block to wait for the taskns notification value to be non-zero. The task does not consume any CPU time while it is in the Blocked state.
Where as xTaskNotifyWaitIndexed() will return when a notification is pending, ulTaskNotifyTakeIndexed() will return when the taskns notification value is not zero.
NOTE Each notification within the array operates independently - a task can only block on one notification within the array at a time and will not be unblocked by a notification sent to any other array index.
Backward compatibility information: Prior to FreeRTOS V10.4.0 each task had a single onotification valuep , and all task notification API functions operated on that value. Replacing the single notification value with an array of notification values necessitated a new set of API functions that could address specific notifications within the array. ulTaskNotifyTake() is the original API function, and remains backward compatible by always operating on the notification value at index 0 in the array. Calling ulTaskNotifyTake() is equivalent to calling ulTaskNotifyTakeIndexed() with the uxIndexToWaitOn parameter set to 0.
Return The taskns notification count before it is either cleared to zero or decremented (see the xClearCountOnExit parameter).
Parameters · uxIndexToWaitOn: The index within the calling taskns array of notification values on which the calling task will wait for a notification to be non-zero. uxIndexToWaitOn must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyTake() does not have this parameter and always waits for notifications on index 0. · xClearCountOnExit: if xClearCountOnExit is pdFALSE then the taskns notification value is decremented when the function exits. In this way the notification value acts like a counting semaphore. If xClearCountOnExit is not pdFALSE then the taskns notification value is cleared to zero when the function exits. In this way the notification value acts like a binary semaphore. · xTicksToWait: The maximum amount of time that the task should wait in the Blocked state for the taskns notification value to be greater than zero, should the count not already be greater than zero when ulTaskNotifyTake() was called. The task will not consume any processing time while it

Espressif Systems

1172

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

is in the Blocked state. This is specified in kernel ticks, the macro pdMS_TO_TICKS( value_in_ms ) can be used to convert a time specified in milliseconds to a time specified in ticks.
BaseType_t xTaskGenericNotifyStateClear(TaskHandle_t xTask, UBaseType_t uxIndexToClear)
See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these functions to be available.
Each task has a private array of onotification valuesp(or mnotificationsn), each of which is a 32-bit unsigned integer (uint32_t). The constant configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the array, and (for backward compatibility) defaults to 1 if left undefined. Prior to FreeRTOS V10.4.0 there was only one notification value per task.
If a notification is sent to an index within the array of notifications then the notification at that index is said to be mpendingnuntil it is read or explicitly cleared by the receiving task. xTaskNotifyStateClearIndexed() is the function that clears a pending notification without reading the notification value. The notification value at the same array index is not altered. Set xTask to NULL to clear the notification state of the calling task.
Backward compatibility information: Prior to FreeRTOS V10.4.0 each task had a single onotification valuep , and all task notification API functions operated on that value. Replacing the single notification value with an array of notification values necessitated a new set of API functions that could address specific notifications within the array. xTaskNotifyStateClear() is the original API function, and remains backward compatible by always operating on the notification value at index 0 within the array. Calling xTaskNotifyStateClear() is equivalent to calling xTaskNotifyStateClearIndexed() with the uxIndexToNotify parameter set to 0.
Return pdTRUE if the taskns notification state was set to eNotWaitingNotification, otherwise pdFALSE. Parameters
· xTask: The handle of the RTOS task that will have a notification state cleared. Set xTask to NULL to clear a notification state in the calling task. To obtain a taskns handle create the task using xTaskCreate() and make use of the pxCreatedTask parameter, or create the task using xTaskCreateStatic() and store the returned value, or use the taskns name in a call to xTaskGetHandle().
· uxIndexToClear: The index within the target taskns array of notification values to act upon. For example, setting uxIndexToClear to 1 will clear the state of the notification at index 1 within the array. uxIndexToClear must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. ulTaskNotifyStateClear() does not have this parameter and always acts on the notification at index 0.
uint32_t ulTaskGenericNotifyValueClear(TaskHandle_t xTask, UBaseType_t uxIndexToClear, uint32_t ulBitsToClear)
See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these functions to be available.
Each task has a private array of onotification valuesp(or mnotificationsn), each of which is a 32-bit unsigned integer (uint32_t). The constant configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the array, and (for backward compatibility) defaults to 1 if left undefined. Prior to FreeRTOS V10.4.0 there was only one notification value per task.
ulTaskNotifyValueClearIndexed() clears the bits specified by the ulBitsToClear bit mask in the notification value at array index uxIndexToClear of the task referenced by xTask.
Backward compatibility information: Prior to FreeRTOS V10.4.0 each task had a single onotification valuep , and all task notification API functions operated on that value. Replacing the single notification value with an array of notification values necessitated a new set of API functions that could address specific notifications within the array. ulTaskNotifyValueClear() is the original API function, and remains backward compatible by always operating on the notification value at index 0 within the array. Calling ulTaskNotifyValueClear() is equivalent to calling ulTaskNotifyValueClearIndexed() with the uxIndexToClear parameter set to 0.
Return The value of the target taskns notification value before the bits specified by ulBitsToClear were cleared.
Parameters · xTask: The handle of the RTOS task that will have bits in one of its notification values cleared. Set xTask to NULL to clear bits in a notification value of the calling task. To obtain a taskns handle create the task using xTaskCreate() and make use of the pxCreatedTask parameter, or create the

Espressif Systems

1173

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

task using xTaskCreateStatic() and store the returned value, or use the taskns name in a call to xTaskGetHandle(). · uxIndexToClear: The index within the target taskns array of notification values in which to clear the bits. uxIndexToClear must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. ulTaskNotifyValueClear() does not have this parameter and always clears bits in the notification value at index 0. · ulBitsToClear: Bit mask of the bits to clear in the notification value of xTask. Set a bit to 1 to clear the corresponding bits in the taskns notification value. Set ulBitsToClear to 0xffffffff (UINT_MAX on 32-bit architectures) to clear the notification value to 0. Set ulBitsToClear to 0 to query the taskns notification value without clearing any bits.
void vTaskSetTimeOutState(TimeOut_t *const pxTimeOut)
BaseType_t xTaskCheckForTimeOut(TimeOut_t *const pxTimeOut, TickType_t *const pxTicksToWait)
Determines if pxTicksToWait ticks has passed since a time was captured using a call to vTaskSetTimeOutState(). The captured time includes the tick count and the number of times the tick count has overflowed.
Example Usage:
// Driver library function used to receive uxWantedBytes from an Rx buffer // that is filled by a UART interrupt. If there are not enough bytes in the // Rx buffer then the task enters the Blocked state until it is notified that // more data has been placed into the buffer. If there is still not enough // data then the task re-enters the Blocked state, and xTaskCheckForTimeOut() // is used to re-calculate the Block time to ensure the total amount of time // spent in the Blocked state does not exceed MAX_TIME_TO_WAIT. This // continues until either the buffer contains at least uxWantedBytes bytes, // or the total amount of time spent in the Blocked state reaches // MAX_TIME_TO_WAIT  at which point the task reads however many bytes are // available up to a maximum of uxWantedBytes.
size_t xUART_Receive( uint8_t *pucBuffer, size_t uxWantedBytes ) { size_t uxReceived = 0; TickType_t xTicksToWait = MAX_TIME_TO_WAIT; TimeOut_t xTimeOut;
// Initialize xTimeOut. This records the time at which this function // was entered. vTaskSetTimeOutState( &xTimeOut );
// Loop until the buffer contains the wanted number of bytes, or a // timeout occurs. while( UART_bytes_in_rx_buffer( pxUARTInstance ) < uxWantedBytes ) {
// The buffer didn't contain enough data so this task is going to // enter the Blocked state. Adjusting xTicksToWait to account for // any time that has been spent in the Blocked state within this // function so far to ensure the total amount of time spent in the // Blocked state does not exceed MAX_TIME_TO_WAIT. if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) != pdFALSE ) {
//Timed out before the wanted number of bytes were available, // exit the loop. break; }
// Wait for a maximum of xTicksToWait ticks to be notified that the // receive interrupt has placed more data into the buffer. ulTaskNotifyTake( pdTRUE, xTicksToWait ); }
(continues on next page)

Espressif Systems

1174

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)
// Attempt to read uxWantedBytes from the receive buffer into pucBuffer. // The actual number of bytes read (which might be less than // uxWantedBytes) is returned. uxReceived = UART_read_from_receive_buffer( pxUARTInstance,
pucBuffer, uxWantedBytes );
return uxReceived; }
Return If timeout has occurred, pdTRUE is returned. Otherwise pdFALSE is returned and pxTicksToWait is updated to reflect the number of remaining ticks.
See https://www.FreeRTOS.org/xTaskCheckForTimeOut.html Parameters
· pxTimeOut: The time status as captured previously using vTaskSetTimeOutState. If the timeout has not yet occurred, it is updated to reflect the current time status.
· pxTicksToWait: The number of ticks to check for timeout i.e. if pxTicksToWait ticks have passed since pxTimeOut was last updated (either by vTaskSetTimeOutState() or xTaskCheckForTimeOut()), the timeout has occurred. If the timeout has not occurred, pxTicksToWait is updated to reflect the number of remaining ticks.
BaseType_t xTaskCatchUpTicks(TickType_t xTicksToCatchUp)

Macros tskKERNEL_VERSION_NUMBER tskKERNEL_VERSION_MAJOR
tskKERNEL_VERSION_MINOR
tskKERNEL_VERSION_BUILD
tskMPU_REGION_READ_ONLY
tskMPU_REGION_READ_WRITE
tskMPU_REGION_EXECUTE_NEVER
tskMPU_REGION_NORMAL_MEMORY
tskMPU_REGION_DEVICE_MEMORY
tskDEFAULT_INDEX_TO_NOTIFY
tskNO_AFFINITY
tskIDLE_PRIORITY Defines the priority used by the idle task. This must not be modified.
taskYIELD() Macro for forcing a context switch.
taskENTER_CRITICAL() Macro to mark the start of a critical code region. Preemptive context switches cannot occur when in a critical region.
Note This may alter the stack (depending on the portable implementation) so must be used with care!
taskENTER_CRITICAL_FROM_ISR()
taskENTER_CRITICAL_ISR()
taskEXIT_CRITICAL() Macro to mark the end of a critical code region. Preemptive context switches cannot occur when in a critical region.
Note This may alter the stack (depending on the portable implementation) so must be used with care!

Espressif Systems

1175

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
taskEXIT_CRITICAL_FROM_ISR(x)
taskEXIT_CRITICAL_ISR()
taskDISABLE_INTERRUPTS() Macro to disable all maskable interrupts.
taskENABLE_INTERRUPTS() Macro to enable microcontroller interrupts.
taskSCHEDULER_SUSPENDED
taskSCHEDULER_NOT_STARTED
taskSCHEDULER_RUNNING
vTaskDelayUntil(pxPreviousWakeTime, xTimeIncrement)
xTaskNotify(xTaskToNotify, ulValue, eAction)
xTaskNotifyIndexed(xTaskToNotify, uxIndexToNotify, ulValue, eAction)
xTaskNotifyAndQuery(xTaskToNotify, ulValue, eAction, pulPreviousNotifyValue) See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
xTaskNotifyAndQueryIndexed() performs the same operation as xTaskNotifyIndexed() with the addition that it also returns the subject taskns prior notification value (the notification value at the time the function is called rather than when the function returns) in the additional pulPreviousNotifyValue parameter.
xTaskNotifyAndQuery() performs the same operation as xTaskNotify() with the addition that it also returns the subject taskns prior notification value (the notification value as it was at the time the function is called, rather than when the function returns) in the additional pulPreviousNotifyValue parameter.
xTaskNotifyAndQueryIndexed(xTaskToNotify, uxIndexToNotify, ulValue, eAction, pulPreviousNotifyValue)
xTaskNotifyFromISR(xTaskToNotify, ulValue, eAction, pxHigherPriorityTaskWoken)
xTaskNotifyIndexedFromISR(xTaskToNotify, uxIndexToNotify, ulValue, eAction, pxHigherPriorityTaskWoken)
xTaskNotifyAndQueryIndexedFromISR(xTaskToNotify, uxIndexToNotify, ulValue, eAction, pulPreviousNotificationValue, pxHigherPriorityTaskWoken)
See https://www.FreeRTOS.org/RTOS-task-notifications.html for details.
xTaskNotifyAndQueryIndexedFromISR() performs the same operation as xTaskNotifyIndexedFromISR() with the addition that it also returns the subject taskns prior notification value (the notification value at the time the function is called rather than at the time the function returns) in the additional pulPreviousNotifyValue parameter.
xTaskNotifyAndQueryFromISR() performs the same operation as xTaskNotifyFromISR() with the addition that it also returns the subject taskns prior notification value (the notification value at the time the function is called rather than at the time the function returns) in the additional pulPreviousNotifyValue parameter.
xTaskNotifyAndQueryFromISR(xTaskToNotify, ulValue, eAction, pulPreviousNotificationValue, pxHigherPriorityTaskWoken)
xTaskNotifyWait(ulBitsToClearOnEntry, ulBitsToClearOnExit, pulNotificationValue, xTicksToWait)
xTaskNotifyWaitIndexed(uxIndexToWaitOn, ulBitsToClearOnEntry, ulBitsToClearOnExit, pulNotificationValue, xTicksToWait)
xTaskNotifyGive(xTaskToNotify) Sends a direct to task notification to a particular index in the target taskns notification array in a manner similar to giving a counting semaphore.
See https://www.FreeRTOS.org/RTOS-task-notifications.html for more details.
configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these macros to be available.

Espressif Systems

1176

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Each task has a private array of onotification valuesp(or mnotificationsn), each of which is a 32-bit unsigned integer (uint32_t). The constant configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the array, and (for backward compatibility) defaults to 1 if left undefined. Prior to FreeRTOS V10.4.0 there was only one notification value per task.
Events can be sent to a task using an intermediary object. Examples of such objects are queues, semaphores, mutexes and event groups. Task notifications are a method of sending an event directly to a task without the need for such an intermediary object.
A notification sent to a task can optionally perform an action, such as update, overwrite or increment one of the taskns notification values. In that way task notifications can be used to send data to a task, or be used as light weight and fast binary or counting semaphores.
xTaskNotifyGiveIndexed() is a helper macro intended for use when task notifications are used as light weight and faster binary or counting semaphore equivalents. Actual FreeRTOS semaphores are given using the xSemaphoreGive() API function, the equivalent action that instead uses a task notification is xTaskNotifyGiveIndexed().
When task notifications are being used as a binary or counting semaphore equivalent then the task being notified should wait for the notification using the ulTaskNotificationTakeIndexed() API function rather than the xTaskNotifyWaitIndexed() API function.
NOTE Each notification within the array operates independently - a task can only block on one notification within the array at a time and will not be unblocked by a notification sent to any other array index.
Backward compatibility information: Prior to FreeRTOS V10.4.0 each task had a single onotification valuep , and all task notification API functions operated on that value. Replacing the single notification value with an array of notification values necessitated a new set of API functions that could address specific notifications within the array. xTaskNotifyGive() is the original API function, and remains backward compatible by always operating on the notification value at index 0 in the array. Calling xTaskNotifyGive() is equivalent to calling xTaskNotifyGiveIndexed() with the uxIndexToNotify parameter set to 0.
Return xTaskNotifyGive() is a macro that calls xTaskNotify() with the eAction parameter set to eIncrement - so pdPASS is always returned.
Parameters · xTaskToNotify: The handle of the task being notified. The handle to a task can be returned from the xTaskCreate() API function used to create the task, and the handle of the currently running task can be obtained by calling xTaskGetCurrentTaskHandle(). · uxIndexToNotify: The index within the target taskns array of notification values to which the notification is to be sent. uxIndexToNotify must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyGive() does not have this parameter and always sends notifications to index 0.
xTaskNotifyGiveIndexed(xTaskToNotify, uxIndexToNotify)
vTaskNotifyGiveFromISR(xTaskToNotify, pxHigherPriorityTaskWoken)
vTaskNotifyGiveIndexedFromISR(xTaskToNotify, uxIndexToNotify, pxHigherPriorityTaskWoken)
ulTaskNotifyTake(xClearCountOnExit, xTicksToWait)
ulTaskNotifyTakeIndexed(uxIndexToWaitOn, xClearCountOnExit, xTicksToWait)
xTaskNotifyStateClear(xTask)
xTaskNotifyStateClearIndexed(xTask, uxIndexToClear)
ulTaskNotifyValueClear(xTask, ulBitsToClear)
ulTaskNotifyValueClearIndexed(xTask, uxIndexToClear, ulBitsToClear)
Type Definitions typedef struct tskTaskControlBlock *TaskHandle_t typedef BaseType_t (*TaskHookFunction_t)(void *)

Espressif Systems

1177

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

typedef void (*TlsDeleteCallbackFunction_t)(int, void *) Prototype of local storage pointer deletion callback.

Enumerations enum eTaskState
Task states returned by eTaskGetState. Values: eRunning = 0 eReady eBlocked eSuspended eDeleted eInvalid enum eNotifyAction Values: eNoAction = 0 eSetBits eIncrement eSetValueWithOverwrite eSetValueWithoutOverwrite enum eSleepModeStatus Possible return values for eTaskConfirmSleepModeStatus(). Values: eAbortSleep = 0 eStandardSleep eNoTasksWaitingTimeout

Queue API
Header File · components/freertos/FreeRTOS-Kernel/include/freertos/queue.h

Functions BaseType_t xQueueGenericSend(QueueHandle_t xQueue, const void *const pvItemToQueue, Tick-
Type_t xTicksToWait, const BaseType_t xCopyPosition) It is preferred that the macros xQueueSend(), xQueueSendToFront() and xQueueSendToBack() are used in place of calling this function directly.
Post an item on a queue. The item is queued by copy, not by reference. This function must not be called from an interrupt service routine. See xQueueSendFromISR () for an alternative which may be used in an ISR.
Example usage:

struct AMessage {
char ucMessageID; char ucData[ 20 ]; } xMessage;

(continues on next page)

Espressif Systems

1178

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
(continued from previous page)
uint32_t ulVar = 10UL;
void vATask( void *pvParameters ) { QueueHandle_t xQueue1, xQueue2; struct AMessage *pxMessage;
// Create a queue capable of containing 10 uint32_t values. xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) );
// Create a queue capable of containing 10 pointers to AMessage structures. // These should be passed by pointer as they contain a lot of data. xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
// ...
if( xQueue1 != 0 ) {
// Send an uint32_t. Wait for 10 ticks for space to become // available if necessary. if( xQueueGenericSend( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10, queueSEND_TO_BACK ) != pdPASS ) {
// Failed to post the message, even after 10 ticks. } }
if( xQueue2 != 0 ) {
// Send a pointer to a struct AMessage object. Don't block if the // queue is already full. pxMessage = & xMessage; xQueueGenericSend( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0, queueSEND_TO_BACK ); }
// ... Rest of task code. }
Return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL. Parameters
· xQueue: The handle to the queue on which the item is to be posted. · pvItemToQueue: A pointer to the item that is to be placed on the queue. The size of the items
the queue will hold was defined when the queue was created, so this many bytes will be copied from pvItemToQueue into the queue storage area. · xTicksToWait: The maximum amount of time the task should block waiting for space to become available on the queue, should it already be full. The call will return immediately if this is set to 0 and the queue is full. The time is defined in tick periods so the constant portTICK_PERIOD_MS should be used to convert to real time if this is required. · xCopyPosition: Can take the value queueSEND_TO_BACK to place the item at the back of the queue, or queueSEND_TO_FRONT to place the item at the front of the queue (for high priority messages). BaseType_t xQueuePeek(QueueHandle_t xQueue, void *const pvBuffer, TickType_t xTicksToWait) Receive an item from a queue without removing the item from the queue. The item is received by copy so a buffer of adequate size must be provided. The number of bytes copied into the buffer was defined when the queue was created.
Successfully received items remain on the queue so will be returned again by the next call, or a call to xQueueReceive().

Espressif Systems

1179

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

This macro must not be used in an interrupt service routine. See xQueuePeekFromISR() for an alternative that can be called from an interrupt service routine.
Example usage:
struct AMessage {
char ucMessageID; char ucData[ 20 ]; } xMessage;
QueueHandle_t xQueue;
// Task to create a queue and post a value. void vATask( void *pvParameters ) { struct AMessage *pxMessage;
// Create a queue capable of containing 10 pointers to AMessage structures. // These should be passed by pointer as they contain a lot of data. xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) ); if( xQueue == 0 ) {
// Failed to create the queue. }
// ...
// Send a pointer to a struct AMessage object. Don't block if the // queue is already full. pxMessage = & xMessage; xQueueSend( xQueue, ( void * ) &pxMessage, ( TickType_t ) 0 );
// ... Rest of task code. }
// Task to peek the data from the queue. void vADifferentTask( void *pvParameters ) { struct AMessage *pxRxedMessage;
if( xQueue != 0 ) {
// Peek a message on the created queue. Block for 10 ticks if a // message is not immediately available. if( xQueuePeek( xQueue, &( pxRxedMessage ), ( TickType_t ) 10 ) ) {
// pcRxedMessage now points to the struct AMessage variable posted // by vATask, but the item still remains on the queue. } }
// ... Rest of task code. }
Return pdTRUE if an item was successfully received from the queue, otherwise pdFALSE. Parameters
· xQueue: The handle to the queue from which the item is to be received. · pvBuffer: Pointer to the buffer into which the received item will be copied. · xTicksToWait: The maximum amount of time the task should block waiting for an item to
receive should the queue be empty at the time of the call. The time is defined in tick periods so the constant portTICK_PERIOD_MS should be used to convert to real time if this is required. xQueuePeek() will return immediately if xTicksToWait is 0 and the queue is empty.

Espressif Systems

1180

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

BaseType_t xQueuePeekFromISR(QueueHandle_t xQueue, void *const pvBuffer) A version of xQueuePeek() that can be called from an interrupt service routine (ISR).
Receive an item from a queue without removing the item from the queue. The item is received by copy so a buffer of adequate size must be provided. The number of bytes copied into the buffer was defined when the queue was created.
Successfully received items remain on the queue so will be returned again by the next call, or a call to xQueueReceive().
Return pdTRUE if an item was successfully received from the queue, otherwise pdFALSE. Parameters
· xQueue: The handle to the queue from which the item is to be received. · pvBuffer: Pointer to the buffer into which the received item will be copied.
BaseType_t xQueueReceive(QueueHandle_t xQueue, void *const pvBuffer, TickType_t xTicksToWait) Receive an item from a queue. The item is received by copy so a buffer of adequate size must be provided. The number of bytes copied into the buffer was defined when the queue was created.
Successfully received items are removed from the queue.
This function must not be used in an interrupt service routine. See xQueueReceiveFromISR for an alternative that can.
Example usage:

struct AMessage {
char ucMessageID; char ucData[ 20 ]; } xMessage;

QueueHandle_t xQueue;

// Task to create a queue and post a value. void vATask( void *pvParameters ) { struct AMessage *pxMessage;

// Create a queue capable of containing 10 pointers to AMessage structures. // These should be passed by pointer as they contain a lot of data. xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) ); if( xQueue == 0 ) {
// Failed to create the queue. }

// ...

// Send a pointer to a struct AMessage object. Don't block if the // queue is already full. pxMessage = & xMessage; xQueueSend( xQueue, ( void * ) &pxMessage, ( TickType_t ) 0 );

// ... Rest of task code. }

// Task to receive from the queue. void vADifferentTask( void *pvParameters ) { struct AMessage *pxRxedMessage;

if( xQueue != 0 ) {

(continues on next page)

Espressif Systems

1181

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)
// Receive a message on the created queue. Block for 10 ticks if a // message is not immediately available. if( xQueueReceive( xQueue, &( pxRxedMessage ), ( TickType_t ) 10 ) ) {
// pcRxedMessage now points to the struct AMessage variable posted // by vATask. } }
// ... Rest of task code. }

Return pdTRUE if an item was successfully received from the queue, otherwise pdFALSE. Parameters
· xQueue: The handle to the queue from which the item is to be received. · pvBuffer: Pointer to the buffer into which the received item will be copied. · xTicksToWait: The maximum amount of time the task should block waiting for an item to
receive should the queue be empty at the time of the call. xQueueReceive() will return immediately if xTicksToWait is zero and the queue is empty. The time is defined in tick periods so the constant portTICK_PERIOD_MS should be used to convert to real time if this is required.
UBaseType_t uxQueueMessagesWaiting(const QueueHandle_t xQueue) Return the number of messages stored in a queue.
Return The number of messages available in the queue. Parameters
· xQueue: A handle to the queue being queried.
UBaseType_t uxQueueSpacesAvailable(const QueueHandle_t xQueue) Return the number of free spaces available in a queue. This is equal to the number of items that can be sent to the queue before the queue becomes full if no items are removed.
Return The number of spaces available in the queue. Parameters
· xQueue: A handle to the queue being queried.
void vQueueDelete(QueueHandle_t xQueue) Delete a queue - freeing all the memory allocated for storing of items placed on the queue.
Parameters · xQueue: A handle to the queue to be deleted.
BaseType_t xQueueGenericSendFromISR(QueueHandle_t xQueue, const void *const pvItemToQueue, BaseType_t *const pxHigherPriorityTaskWoken, const BaseType_t xCopyPosition)
It is preferred that the macros xQueueSendFromISR(), xQueueSendToFrontFromISR() and xQueueSendToBackFromISR() be used in place of calling this function directly. xQueueGiveFromISR() is an equivalent for use by semaphores that donnt actually copy any data.
Post an item on a queue. It is safe to use this function from within an interrupt service routine.
Items are queued by copy not reference so it is preferable to only queue small items, especially when called from an ISR. In most cases it would be preferable to store a pointer to the item being queued.
Example usage for buffered IO (where the ISR can obtain more than one value per call):

void vBufferISR( void ) { char cIn; BaseType_t xHigherPriorityTaskWokenByPost;

// We have not woken a task at the start of the ISR. xHigherPriorityTaskWokenByPost = pdFALSE;

(continues on next page)

Espressif Systems

1182

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)

// Loop until the buffer is empty. do {
// Obtain a byte from the buffer. cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );

// Post each byte. xQueueGenericSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWokenByPost,  queueSEND_TO_BACK );

} while( portINPUT_BYTE( BUFFER_COUNT ) );

// Now the buffer is empty we can switch context if necessary. // name of the yield function required is port specific. if( xHigherPriorityTaskWokenByPost ) {
taskYIELD_YIELD_FROM_ISR(); } }

Note that the

Return pdTRUE if the data was successfully sent to the queue, otherwise errQUEUE_FULL. Parameters
· xQueue: The handle to the queue on which the item is to be posted. · pvItemToQueue: A pointer to the item that is to be placed on the queue. The size of the items
the queue will hold was defined when the queue was created, so this many bytes will be copied from pvItemToQueue into the queue storage area. · [out] pxHigherPriorityTaskWoken: xQueueGenericSendFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task to unblock, and the unblocked task has a priority higher than the currently running task. If xQueueGenericSendFromISR() sets this value to pdTRUE then a context switch should be requested before the interrupt is exited. · xCopyPosition: Can take the value queueSEND_TO_BACK to place the item at the back of the queue, or queueSEND_TO_FRONT to place the item at the front of the queue (for high priority messages).
BaseType_t xQueueGiveFromISR(QueueHandle_t xQueue, BaseType_t *const pxHigherPriorityTaskWoken)
BaseType_t xQueueReceiveFromISR(QueueHandle_t xQueue, void *const pvBuffer, BaseType_t *const pxHigherPriorityTaskWoken)
Receive an item from a queue. It is safe to use this function from within an interrupt service routine.
Example usage:
QueueHandle_t xQueue;
// Function to create a queue and post some values. void vAFunction( void *pvParameters ) { char cValueToPost; const TickType_t xTicksToWait = ( TickType_t )0xff;
// Create a queue capable of containing 10 characters. xQueue = xQueueCreate( 10, sizeof( char ) ); if( xQueue == 0 ) {
// Failed to create the queue. }
// ...

(continues on next page)

Espressif Systems

1183

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page) // Post some characters that will be used within an ISR. If the queue // is full then this task will block for xTicksToWait ticks. cValueToPost = 'a'; xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait ); cValueToPost = 'b'; xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait );
// ... keep posting characters ... this task may block when the queue // becomes full.
cValueToPost = 'c'; xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait ); }
// ISR that outputs all the characters received on the queue. void vISR_Routine( void ) { BaseType_t xTaskWokenByReceive = pdFALSE; char cRxedChar;
while( xQueueReceiveFromISR( xQueue, ( void * ) &cRxedChar, & xTaskWokenByReceive) ) {
// A character was received. Output the character now. vOutputCharacter( cRxedChar );
// If removing the character from the queue woke the task that was // posting onto the queue cTaskWokenByReceive will have been set to // pdTRUE. No matter how many times this loop iterates only one // task will be woken. }
if( cTaskWokenByPost != ( char ) pdFALSE; {
taskYIELD (); } }
Return pdTRUE if an item was successfully received from the queue, otherwise pdFALSE. Parameters
· xQueue: The handle to the queue from which the item is to be received. · pvBuffer: Pointer to the buffer into which the received item will be copied. · [out] pxHigherPriorityTaskWoken: A task may be blocked waiting for space to become
available on the queue. If xQueueReceiveFromISR causes such a task to unblock *pxTaskWoken will get set to pdTRUE, otherwise *pxTaskWoken will remain unchanged.
BaseType_t xQueueIsQueueEmptyFromISR(const QueueHandle_t xQueue)
BaseType_t xQueueIsQueueFullFromISR(const QueueHandle_t xQueue)
UBaseType_t uxQueueMessagesWaitingFromISR(const QueueHandle_t xQueue)
void vQueueAddToRegistry(QueueHandle_t xQueue, const char *pcQueueName) The registry is provided as a means for kernel aware debuggers to locate queues, semaphores and mutexes. Call vQueueAddToRegistry() add a queue, semaphore or mutex handle to the registry if you want the handle to be available to a kernel aware debugger. If you are not using a kernel aware debugger then this function can be ignored.
configQUEUE_REGISTRY_SIZE defines the maximum number of handles the registry can hold. configQUEUE_REGISTRY_SIZE must be greater than 0 within FreeRTOSConfig.h for the registry to be available. Its value does not effect the number of queues, semaphores and mutexes that can be created - just the number that the registry can hold.

Espressif Systems

1184

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Parameters · xQueue: The handle of the queue being added to the registry. This is the handle returned by a call to xQueueCreate(). Semaphore and mutex handles can also be passed in here. · pcQueueName: The name to be associated with the handle. This is the name that the kernel aware debugger will display. The queue registry only stores a pointer to the string - so the string must be persistent (global or preferably in ROM/Flash), not on the stack.
void vQueueUnregisterQueue(QueueHandle_t xQueue) The registry is provided as a means for kernel aware debuggers to locate queues, semaphores and mutexes. Call vQueueAddToRegistry() add a queue, semaphore or mutex handle to the registry if you want the handle to be available to a kernel aware debugger, and vQueueUnregisterQueue() to remove the queue, semaphore or mutex from the register. If you are not using a kernel aware debugger then this function can be ignored.
Parameters · xQueue: The handle of the queue being removed from the registry.
const char *pcQueueGetName(QueueHandle_t xQueue) The queue registry is provided as a means for kernel aware debuggers to locate queues, semaphores and mutexes. Call pcQueueGetName() to look up and return the name of a queue in the queue registry from the queuens handle.
Return If the queue is in the registry then a pointer to the name of the queue is returned. If the queue is not in the registry then NULL is returned.
Parameters · xQueue: The handle of the queue the name of which will be returned.
QueueHandle_t xQueueGenericCreate(const UBaseType_t uxQueueLength, const UBaseType_t uxItemSize, const uint8_t ucQueueType)
Generic version of the function used to create a queue using dynamic memory allocation. This is called by other functions and macros that create other RTOS objects that use the queue structure as their base.
QueueHandle_t xQueueGenericCreateStatic(const UBaseType_t uxQueueLength, const UBaseType_t uxItemSize, uint8_t *pucQueueStorage, StaticQueue_t *pxStaticQueue, const uint8_t ucQueueType)
Generic version of the function used to create a queue using dynamic memory allocation. This is called by other functions and macros that create other RTOS objects that use the queue structure as their base.
QueueSetHandle_t xQueueCreateSet(const UBaseType_t uxEventQueueLength) Queue sets provide a mechanism to allow a task to block (pend) on a read operation from multiple queues or semaphores simultaneously.
See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this function.
A queue set must be explicitly created using a call to xQueueCreateSet() before it can be used. Once created, standard FreeRTOS queues and semaphores can be added to the set using calls to xQueueAddToSet(). xQueueSelectFromSet() is then used to determine which, if any, of the queues or semaphores contained in the set is in a state where a queue read or semaphore take operation would be successful.
Note 1: See the documentation on https://www.FreeRTOS.org/RTOS-queue-sets.html for reasons why queue sets are very rarely needed in practice as there are simpler methods of blocking on multiple objects.
Note 2: Blocking on a queue set that contains a mutex will not cause the mutex holder to inherit the priority of the blocked task.
Note 3: An additional 4 bytes of RAM is required for each space in a every queue added to a queue set. Therefore counting semaphores that have a high maximum count value should not be added to a queue set.
Note 4: A receive (in the case of a queue) or take (in the case of a semaphore) operation must not be performed on a member of a queue set unless a call to xQueueSelectFromSet() has first returned a handle to that set member.
Return If the queue set is created successfully then a handle to the created queue set is returned. Otherwise NULL is returned.
Parameters

Espressif Systems

1185

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· uxEventQueueLength: Queue sets store events that occur on the queues and semaphores contained in the set. uxEventQueueLength specifies the maximum number of events that can be queued at once. To be absolutely certain that events are not lost uxEventQueueLength should be set to the total sum of the length of the queues added to the set, where binary semaphores and mutexes have a length of 1, and counting semaphores have a length set by their maximum count value. Examples: ­ If a queue set is to hold a queue of length 5, another queue of length 12, and a binary semaphore, then uxEventQueueLength should be set to (5 + 12 + 1), or 18. ­ If a queue set is to hold three binary semaphores then uxEventQueueLength should be set to (1 + 1 + 1 ), or 3. ­ If a queue set is to hold a counting semaphore that has a maximum count of 5, and a counting semaphore that has a maximum count of 3, then uxEventQueueLength should be set to (5 + 3), or 8.
BaseType_t xQueueAddToSet(QueueSetMemberHandle_t xQueueOrSemaphore, QueueSetHandle_t xQueueSet)
Adds a queue or semaphore to a queue set that was previously created by a call to xQueueCreateSet().
See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this function.
Note 1: A receive (in the case of a queue) or take (in the case of a semaphore) operation must not be performed on a member of a queue set unless a call to xQueueSelectFromSet() has first returned a handle to that set member.
Return If the queue or semaphore was successfully added to the queue set then pdPASS is returned. If the queue could not be successfully added to the queue set because it is already a member of a different queue set then pdFAIL is returned.
Parameters · xQueueOrSemaphore: The handle of the queue or semaphore being added to the queue set (cast to an QueueSetMemberHandle_t type). · xQueueSet: The handle of the queue set to which the queue or semaphore is being added.
BaseType_t xQueueRemoveFromSet(QueueSetMemberHandle_t xQueueOrSemaphore, QueueSetHandle_t xQueueSet)
Removes a queue or semaphore from a queue set. A queue or semaphore can only be removed from a set if the queue or semaphore is empty.
See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this function.
Return If the queue or semaphore was successfully removed from the queue set then pdPASS is returned. If the queue was not in the queue set, or the queue (or semaphore) was not empty, then pdFAIL is returned.
Parameters · xQueueOrSemaphore: The handle of the queue or semaphore being removed from the queue set (cast to an QueueSetMemberHandle_t type). · xQueueSet: The handle of the queue set in which the queue or semaphore is included.
QueueSetMemberHandle_t xQueueSelectFromSet(QueueSetHandle_t xQueueSet, const TickType_t xTicksToWait)
xQueueSelectFromSet() selects from the members of a queue set a queue or semaphore that either contains data (in the case of a queue) or is available to take (in the case of a semaphore). xQueueSelectFromSet() effectively allows a task to block (pend) on a read operation on all the queues and semaphores in a queue set simultaneously.
See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this function.
Note 1: See the documentation on https://www.FreeRTOS.org/RTOS-queue-sets.html for reasons why queue sets are very rarely needed in practice as there are simpler methods of blocking on multiple objects.
Note 2: Blocking on a queue set that contains a mutex will not cause the mutex holder to inherit the priority of the blocked task.
Note 3: A receive (in the case of a queue) or take (in the case of a semaphore) operation must not be performed on a member of a queue set unless a call to xQueueSelectFromSet() has first returned a handle to that set member.

Espressif Systems

1186

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return xQueueSelectFromSet() will return the handle of a queue (cast to a QueueSetMemberHandle_t type) contained in the queue set that contains data, or the handle of a semaphore (cast to a QueueSetMemberHandle_t type) contained in the queue set that is available, or NULL if no such queue or semaphore exists before before the specified block time expires.
Parameters · xQueueSet: The queue set on which the task will (potentially) block. · xTicksToWait: The maximum time, in ticks, that the calling task will remain in the Blocked state (with other tasks executing) to wait for a member of the queue set to be ready for a successful queue read or semaphore take operation.
QueueSetMemberHandle_t xQueueSelectFromSetFromISR(QueueSetHandle_t xQueueSet) A version of xQueueSelectFromSet() that can be used from an ISR.

Macros xQueueCreate(uxQueueLength, uxItemSize)
Creates a new queue instance, and returns a handle by which the new queue can be referenced.
Internally, within the FreeRTOS implementation, queues use two blocks of memory. The first block is used to hold the queuens data structures. The second block is used to hold items placed into the queue. If a queue is created using xQueueCreate() then both blocks of memory are automatically dynamically allocated inside the xQueueCreate() function. (see https://www.FreeRTOS.org/a00111.html). If a queue is created using xQueueCreateStatic() then the application writer must provide the memory that will get used by the queue. xQueueCreateStatic() therefore allows a queue to be created without using any dynamic memory allocation.
https://www.FreeRTOS.org/Embedded-RTOS-Queues.html
Example usage:
struct AMessage {
char ucMessageID; char ucData[ 20 ]; };
void vATask( void *pvParameters ) { QueueHandle_t xQueue1, xQueue2;
// Create a queue capable of containing 10 uint32_t values. xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) ); if( xQueue1 == 0 ) {
// Queue was not created and must not be used. }
// Create a queue capable of containing 10 pointers to AMessage structures. // These should be passed by pointer as they contain a lot of data. xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) ); if( xQueue2 == 0 ) {
// Queue was not created and must not be used. }
// ... Rest of task code. }
Return If the queue is successfully create then a handle to the newly created queue is returned. If the queue cannot be created then 0 is returned.
Parameters · uxQueueLength: The maximum number of items that the queue can contain. · uxItemSize: The number of bytes each item in the queue will require. Items are queued by copy, not by reference, so this is the number of bytes that will be copied for each posted item. Each item

Espressif Systems

1187

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

on the queue must be the same size. xQueueCreateStatic(uxQueueLength, uxItemSize, pucQueueStorage, pxQueueBuffer)
Creates a new queue instance, and returns a handle by which the new queue can be referenced.
Internally, within the FreeRTOS implementation, queues use two blocks of memory. The first block is used to hold the queuens data structures. The second block is used to hold items placed into the queue. If a queue is created using xQueueCreate() then both blocks of memory are automatically dynamically allocated inside the xQueueCreate() function. (see https://www.FreeRTOS.org/a00111.html). If a queue is created using xQueueCreateStatic() then the application writer must provide the memory that will get used by the queue. xQueueCreateStatic() therefore allows a queue to be created without using any dynamic memory allocation.
https://www.FreeRTOS.org/Embedded-RTOS-Queues.html
Example usage:

struct AMessage {
char ucMessageID; char ucData[ 20 ]; };

#define QUEUE_LENGTH 10 #define ITEM_SIZE sizeof( uint32_t )

// xQueueBuffer will hold the queue structure. StaticQueue_t xQueueBuffer;

// ucQueueStorage will hold the items posted to the queue. Must be at least // [(queue length) * ( queue item size)] bytes long. uint8_t ucQueueStorage[ QUEUE_LENGTH * ITEM_SIZE ];

void vATask( void *pvParameters ) { QueueHandle_t xQueue1;

// Create a queue capable of containing 10 uint32_t values.

xQueue1 = xQueueCreate( QUEUE_LENGTH, // The number of items the queue can

hold.

ITEM_SIZE

// The size of each item in the queue

&( ucQueueStorage[ 0 ] ), // The buffer that will

hold the items in the queue.

&xQueueBuffer ); // The buffer that will hold the

queue structure.

// The queue is guaranteed to be created successfully as no dynamic memory // allocation is used. Therefore xQueue1 is now a handle to a valid queue.

// ... Rest of task code. }

Return If the queue is created then a handle to the created queue is returned. If pxQueueBuffer is NULL then NULL is returned.
Parameters · uxQueueLength: The maximum number of items that the queue can contain. · uxItemSize: The number of bytes each item in the queue will require. Items are queued by copy, not by reference, so this is the number of bytes that will be copied for each posted item. Each item on the queue must be the same size. · pucQueueStorage: If uxItemSize is not zero then pucQueueStorageBuffer must point to a uint8_t array that is at least large enough to hold the maximum number of items that can be in the queue at any one time - which is ( uxQueueLength * uxItemsSize ) bytes. If uxItemSize is zero then pucQueueStorageBuffer can be NULL. · pxQueueBuffer: Must point to a variable of type StaticQueue_t, which will be used to hold the queuens data structure.

Espressif Systems

1188

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

xQueueSendToFront(xQueue, pvItemToQueue, xTicksToWait) Post an item to the front of a queue. The item is queued by copy, not by reference. This function must not be called from an interrupt service routine. See xQueueSendFromISR () for an alternative which may be used in an ISR.
Example usage:
struct AMessage {
char ucMessageID; char ucData[ 20 ]; } xMessage;
uint32_t ulVar = 10UL;
void vATask( void *pvParameters ) { QueueHandle_t xQueue1, xQueue2; struct AMessage *pxMessage;
// Create a queue capable of containing 10 uint32_t values. xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) );
// Create a queue capable of containing 10 pointers to AMessage structures. // These should be passed by pointer as they contain a lot of data. xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
// ...
if( xQueue1 != 0 ) {
// Send an uint32_t. Wait for 10 ticks for space to become // available if necessary. if( xQueueSendToFront( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10 ) != pdPASS ) {
// Failed to post the message, even after 10 ticks. } }
if( xQueue2 != 0 ) {
// Send a pointer to a struct AMessage object. Don't block if the // queue is already full. pxMessage = & xMessage; xQueueSendToFront( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0 ); }
// ... Rest of task code. }
Return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL. Parameters
· xQueue: The handle to the queue on which the item is to be posted. · pvItemToQueue: A pointer to the item that is to be placed on the queue. The size of the items
the queue will hold was defined when the queue was created, so this many bytes will be copied from pvItemToQueue into the queue storage area. · xTicksToWait: The maximum amount of time the task should block waiting for space to become available on the queue, should it already be full. The call will return immediately if this is set to 0 and the queue is full. The time is defined in tick periods so the constant portTICK_PERIOD_MS should be used to convert to real time if this is required.
xQueueSendToBack(xQueue, pvItemToQueue, xTicksToWait)

Espressif Systems

1189

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
This is a macro that calls xQueueGenericSend().
Post an item to the back of a queue. The item is queued by copy, not by reference. This function must not be called from an interrupt service routine. See xQueueSendFromISR () for an alternative which may be used in an ISR.
Example usage:
struct AMessage {
char ucMessageID; char ucData[ 20 ]; } xMessage;
uint32_t ulVar = 10UL;
void vATask( void *pvParameters ) { QueueHandle_t xQueue1, xQueue2; struct AMessage *pxMessage;
// Create a queue capable of containing 10 uint32_t values. xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) );
// Create a queue capable of containing 10 pointers to AMessage structures. // These should be passed by pointer as they contain a lot of data. xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
// ...
if( xQueue1 != 0 ) {
// Send an uint32_t. Wait for 10 ticks for space to become // available if necessary. if( xQueueSendToBack( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10 ) != pdPASS ) {
// Failed to post the message, even after 10 ticks. } }
if( xQueue2 != 0 ) {
// Send a pointer to a struct AMessage object. Don't block if the // queue is already full. pxMessage = & xMessage; xQueueSendToBack( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0 ); }
// ... Rest of task code. }
Return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL. Parameters
· xQueue: The handle to the queue on which the item is to be posted. · pvItemToQueue: A pointer to the item that is to be placed on the queue. The size of the items
the queue will hold was defined when the queue was created, so this many bytes will be copied from pvItemToQueue into the queue storage area. · xTicksToWait: The maximum amount of time the task should block waiting for space to become available on the queue, should it already be full. The call will return immediately if this is set to 0 and the queue is full. The time is defined in tick periods so the constant portTICK_PERIOD_MS should be used to convert to real time if this is required.

Espressif Systems

1190

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

xQueueSend(xQueue, pvItemToQueue, xTicksToWait) This is a macro that calls xQueueGenericSend(). It is included for backward compatibility with versions of FreeRTOS.org that did not include the xQueueSendToFront() and xQueueSendToBack() macros. It is equivalent to xQueueSendToBack().
Post an item on a queue. The item is queued by copy, not by reference. This function must not be called from an interrupt service routine. See xQueueSendFromISR () for an alternative which may be used in an ISR.
Example usage:
struct AMessage {
char ucMessageID; char ucData[ 20 ]; } xMessage;
uint32_t ulVar = 10UL;
void vATask( void *pvParameters ) { QueueHandle_t xQueue1, xQueue2; struct AMessage *pxMessage;
// Create a queue capable of containing 10 uint32_t values. xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) );
// Create a queue capable of containing 10 pointers to AMessage structures. // These should be passed by pointer as they contain a lot of data. xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
// ...
if( xQueue1 != 0 ) {
// Send an uint32_t. Wait for 10 ticks for space to become // available if necessary. if( xQueueSend( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10 ) != pdPASS ) {
// Failed to post the message, even after 10 ticks. } }
if( xQueue2 != 0 ) {
// Send a pointer to a struct AMessage object. Don't block if the // queue is already full. pxMessage = & xMessage; xQueueSend( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0 ); }
// ... Rest of task code. }
Return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL. Parameters
· xQueue: The handle to the queue on which the item is to be posted. · pvItemToQueue: A pointer to the item that is to be placed on the queue. The size of the items
the queue will hold was defined when the queue was created, so this many bytes will be copied from pvItemToQueue into the queue storage area. · xTicksToWait: The maximum amount of time the task should block waiting for space to become available on the queue, should it already be full. The call will return immediately if this is set to 0 and the queue is full. The time is defined in tick periods so the constant portTICK_PERIOD_MS

Espressif Systems

1191

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

should be used to convert to real time if this is required.
xQueueOverwrite(xQueue, pvItemToQueue) Only for use with queues that have a length of one - so the queue is either empty or full.
Post an item on a queue. If the queue is already full then overwrite the value held in the queue. The item is queued by copy, not by reference.
This function must not be called from an interrupt service routine. See xQueueOverwriteFromISR () for an alternative which may be used in an ISR.
Example usage:
void vFunction( void *pvParameters ) { QueueHandle_t xQueue; uint32_t ulVarToSend, ulValReceived;
// Create a queue to hold one uint32_t value. It is strongly // recommended *not* to use xQueueOverwrite() on queues that can // contain more than one value, and doing so will trigger an assertion // if configASSERT() is defined. xQueue = xQueueCreate( 1, sizeof( uint32_t ) );
// Write the value 10 to the queue using xQueueOverwrite(). ulVarToSend = 10; xQueueOverwrite( xQueue, &ulVarToSend );
// Peeking the queue should now return 10, but leave the value 10 in // the queue. A block time of zero is used as it is known that the // queue holds a value. ulValReceived = 0; xQueuePeek( xQueue, &ulValReceived, 0 );
if( ulValReceived != 10 ) {
// Error unless the item was removed by a different task. }
// The queue is still full. Use xQueueOverwrite() to overwrite the // value held in the queue with 100. ulVarToSend = 100; xQueueOverwrite( xQueue, &ulVarToSend );
// This time read from the queue, leaving the queue empty once more. // A block time of 0 is used again. xQueueReceive( xQueue, &ulValReceived, 0 );
// The value read should be the last value written, even though the // queue was already full when the value was written. if( ulValReceived != 100 ) {
// Error! }
// ... }
Return xQueueOverwrite() is a macro that calls xQueueGenericSend(), and therefore has the same return values as xQueueSendToFront(). However, pdPASS is the only value that can be returned because xQueueOverwrite() will write to the queue even when the queue is already full.
Parameters · xQueue: The handle of the queue to which the data is being sent. · pvItemToQueue: A pointer to the item that is to be placed on the queue. The size of the items

Espressif Systems

1192

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

the queue will hold was defined when the queue was created, so this many bytes will be copied from pvItemToQueue into the queue storage area.
xQueueSendToFrontFromISR(xQueue, pvItemToQueue, pxHigherPriorityTaskWoken) This is a macro that calls xQueueGenericSendFromISR().
Post an item to the front of a queue. It is safe to use this macro from within an interrupt service routine.
Items are queued by copy not reference so it is preferable to only queue small items, especially when called from an ISR. In most cases it would be preferable to store a pointer to the item being queued.
Example usage for buffered IO (where the ISR can obtain more than one value per call):
void vBufferISR( void ) { char cIn; BaseType_t xHigherPrioritTaskWoken;
// We have not woken a task at the start of the ISR. xHigherPriorityTaskWoken = pdFALSE;
// Loop until the buffer is empty. do {
// Obtain a byte from the buffer. cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );
// Post the byte. xQueueSendToFrontFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );
} while( portINPUT_BYTE( BUFFER_COUNT ) );
// Now the buffer is empty we can switch context if necessary. if( xHigherPriorityTaskWoken ) {
portYIELD_FROM_ISR (); } }

Return pdTRUE if the data was successfully sent to the queue, otherwise errQUEUE_FULL. Parameters
· xQueue: The handle to the queue on which the item is to be posted. · pvItemToQueue: A pointer to the item that is to be placed on the queue. The size of the items
the queue will hold was defined when the queue was created, so this many bytes will be copied from pvItemToQueue into the queue storage area. · [out] pxHigherPriorityTaskWoken: xQueueSendToFrontFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task to unblock, and the unblocked task has a priority higher than the currently running task. If xQueueSendToFromFromISR() sets this value to pdTRUE then a context switch should be requested before the interrupt is exited.
xQueueSendToBackFromISR(xQueue, pvItemToQueue, pxHigherPriorityTaskWoken) This is a macro that calls xQueueGenericSendFromISR().
Post an item to the back of a queue. It is safe to use this macro from within an interrupt service routine.
Items are queued by copy not reference so it is preferable to only queue small items, especially when called from an ISR. In most cases it would be preferable to store a pointer to the item being queued.
Example usage for buffered IO (where the ISR can obtain more than one value per call):

void vBufferISR( void ) { char cIn; BaseType_t xHigherPriorityTaskWoken;

(continues on next page)

Espressif Systems

1193

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)
// We have not woken a task at the start of the ISR. xHigherPriorityTaskWoken = pdFALSE;
// Loop until the buffer is empty. do {
// Obtain a byte from the buffer. cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );
// Post the byte. xQueueSendToBackFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );
} while( portINPUT_BYTE( BUFFER_COUNT ) );
// Now the buffer is empty we can switch context if necessary. if( xHigherPriorityTaskWoken ) {
portYIELD_FROM_ISR (); } }
Return pdTRUE if the data was successfully sent to the queue, otherwise errQUEUE_FULL. Parameters
· xQueue: The handle to the queue on which the item is to be posted. · pvItemToQueue: A pointer to the item that is to be placed on the queue. The size of the items
the queue will hold was defined when the queue was created, so this many bytes will be copied from pvItemToQueue into the queue storage area. · [out] pxHigherPriorityTaskWoken: xQueueSendToBackFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task to unblock, and the unblocked task has a priority higher than the currently running task. If xQueueSendToBackFromISR() sets this value to pdTRUE then a context switch should be requested before the interrupt is exited.
xQueueOverwriteFromISR(xQueue, pvItemToQueue, pxHigherPriorityTaskWoken) A version of xQueueOverwrite() that can be used in an interrupt service routine (ISR).
Only for use with queues that can hold a single item - so the queue is either empty or full.
Post an item on a queue. If the queue is already full then overwrite the value held in the queue. The item is queued by copy, not by reference.
Example usage:
QueueHandle_t xQueue;
void vFunction( void *pvParameters ) {
// Create a queue to hold one uint32_t value. It is strongly // recommended *not* to use xQueueOverwriteFromISR() on queues that can // contain more than one value, and doing so will trigger an assertion // if configASSERT() is defined. xQueue = xQueueCreate( 1, sizeof( uint32_t ) ); }
void vAnInterruptHandler( void ) { // xHigherPriorityTaskWoken must be set to pdFALSE before it is used. BaseType_t xHigherPriorityTaskWoken = pdFALSE; uint32_t ulVarToSend, ulValReceived;
// Write the value 10 to the queue using xQueueOverwriteFromISR(). ulVarToSend = 10;
(continues on next page)

Espressif Systems

1194

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page) xQueueOverwriteFromISR( xQueue, &ulVarToSend, &xHigherPriorityTaskWoken );
// The queue is full, but calling xQueueOverwriteFromISR() again will still // pass because the value held in the queue will be overwritten with the // new value. ulVarToSend = 100; xQueueOverwriteFromISR( xQueue, &ulVarToSend, &xHigherPriorityTaskWoken );
// Reading from the queue will now return 100.
// ...
if( xHigherPrioritytaskWoken == pdTRUE ) {
// Writing to the queue caused a task to unblock and the unblocked task // has a priority higher than or equal to the priority of the currently // executing task (the task this interrupt interrupted). Perform a context // switch so this interrupt returns directly to the unblocked task. portYIELD_FROM_ISR(); // or portEND_SWITCHING_ISR() depending on the port. } }

Return xQueueOverwriteFromISR() is a macro that calls xQueueGenericSendFromISR(), and therefore has the same return values as xQueueSendToFrontFromISR(). However, pdPASS is the only value that can be returned because xQueueOverwriteFromISR() will write to the queue even when the queue is already full.
Parameters · xQueue: The handle to the queue on which the item is to be posted. · pvItemToQueue: A pointer to the item that is to be placed on the queue. The size of the items the queue will hold was defined when the queue was created, so this many bytes will be copied from pvItemToQueue into the queue storage area. · [out] pxHigherPriorityTaskWoken: xQueueOverwriteFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task to unblock, and the unblocked task has a priority higher than the currently running task. If xQueueOverwriteFromISR() sets this value to pdTRUE then a context switch should be requested before the interrupt is exited.
xQueueSendFromISR(xQueue, pvItemToQueue, pxHigherPriorityTaskWoken) This is a macro that calls xQueueGenericSendFromISR(). It is included for backward compatibility with versions of FreeRTOS.org that did not include the xQueueSendToBackFromISR() and xQueueSendToFrontFromISR() macros.
Post an item to the back of a queue. It is safe to use this function from within an interrupt service routine.
Items are queued by copy not reference so it is preferable to only queue small items, especially when called from an ISR. In most cases it would be preferable to store a pointer to the item being queued.
Example usage for buffered IO (where the ISR can obtain more than one value per call):

void vBufferISR( void ) { char cIn; BaseType_t xHigherPriorityTaskWoken;

// We have not woken a task at the start of the ISR. xHigherPriorityTaskWoken = pdFALSE;

// Loop until the buffer is empty. do {
// Obtain a byte from the buffer.

(continues on next page)

Espressif Systems

1195

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );

(continued from previous page)

// Post the byte. xQueueSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );

} while( portINPUT_BYTE( BUFFER_COUNT ) );

// Now the buffer is empty we can switch context if necessary. if( xHigherPriorityTaskWoken ) {
// Actual macro used here is port specific. portYIELD_FROM_ISR (); } }

Return pdTRUE if the data was successfully sent to the queue, otherwise errQUEUE_FULL. Parameters
· xQueue: The handle to the queue on which the item is to be posted. · pvItemToQueue: A pointer to the item that is to be placed on the queue. The size of the items
the queue will hold was defined when the queue was created, so this many bytes will be copied from pvItemToQueue into the queue storage area. · [out] pxHigherPriorityTaskWoken: xQueueSendFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task to unblock, and the unblocked task has a priority higher than the currently running task. If xQueueSendFromISR() sets this value to pdTRUE then a context switch should be requested before the interrupt is exited.
xQueueReset(xQueue) Reset a queue back to its original empty state. The return value is now obsolete and is always set to pdPASS.

Type Definitions typedef struct QueueDefinition *QueueHandle_t typedef struct QueueDefinition *QueueSetHandle_t
Type by which queue sets are referenced. For example, a call to xQueueCreateSet() returns an xQueueSet variable that can then be used as a parameter to xQueueSelectFromSet(), xQueueAddToSet(), etc.
typedef struct QueueDefinition *QueueSetMemberHandle_t Queue sets can contain both queues and semaphores, so the QueueSetMemberHandle_t is defined as a type to be used where a parameter or return value can be either an QueueHandle_t or an SemaphoreHandle_t.

Semaphore API
Header File · components/freertos/FreeRTOS-Kernel/include/freertos/semphr.h

Macros semBINARY_SEMAPHORE_QUEUE_LENGTH semSEMAPHORE_QUEUE_ITEM_LENGTH
semGIVE_BLOCK_TIME
vSemaphoreCreateBinary(xSemaphore)
xSemaphoreCreateBinary() Creates a new binary semaphore instance, and returns a handle by which the new semaphore can be referenced.
In many usage scenarios it is faster and more memory efficient to use a direct to task notification in place of a binary semaphore! https://www.FreeRTOS.org/RTOS-task-notifications.html

Espressif Systems

1196

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Internally, within the FreeRTOS implementation, binary semaphores use a block of memory, in which the semaphore structure is stored. If a binary semaphore is created using xSemaphoreCreateBinary() then the required memory is automatically dynamically allocated inside the xSemaphoreCreateBinary() function. (see https://www.FreeRTOS.org/a00111.html). If a binary semaphore is created using xSemaphoreCreateBinaryStatic() then the application writer must provide the memory. xSemaphoreCreateBinaryStatic() therefore allows a binary semaphore to be created without using any dynamic memory allocation.
The old vSemaphoreCreateBinary() macro is now deprecated in favour of this xSemaphoreCreateBinary() function. Note that binary semaphores created using the vSemaphoreCreateBinary() macro are created in a state such that the first call to mtakenthe semaphore would pass, whereas binary semaphores created using xSemaphoreCreateBinary() are created in a state such that the the semaphore must first be mgivennbefore it can be mtakenn.
This type of semaphore can be used for pure synchronisation between tasks or between an interrupt and a task. The semaphore need not be given back once obtained, so one task/interrupt can continuouslymgiventhe semaphore while another continuouslymtakesnthe semaphore. For this reason this type of semaphore does not use a priority inheritance mechanism. For an alternative that does use priority inheritance see xSemaphoreCreateMutex().
Example usage:
SemaphoreHandle_t xSemaphore = NULL;
void vATask( void * pvParameters ) {
// Semaphore cannot be used before a call to vSemaphoreCreateBinary(). // This is a macro so pass the variable in directly. xSemaphore = xSemaphoreCreateBinary();
if( xSemaphore != NULL ) {
// The semaphore was created successfully. // The semaphore can now be used. } }
Return Handle to the created semaphore, or NULL if the memory required to hold the semaphorens data structures could not be allocated.
xSemaphoreCreateBinaryStatic(pxStaticSemaphore) Creates a new binary semaphore instance, and returns a handle by which the new semaphore can be referenced.
NOTE: In many usage scenarios it is faster and more memory efficient to use a direct to task notification in place of a binary semaphore! https://www.FreeRTOS.org/RTOS-task-notifications.html
Internally, within the FreeRTOS implementation, binary semaphores use a block of memory, in which the semaphore structure is stored. If a binary semaphore is created using xSemaphoreCreateBinary() then the required memory is automatically dynamically allocated inside the xSemaphoreCreateBinary() function. (see https://www.FreeRTOS.org/a00111.html). If a binary semaphore is created using xSemaphoreCreateBinaryStatic() then the application writer must provide the memory. xSemaphoreCreateBinaryStatic() therefore allows a binary semaphore to be created without using any dynamic memory allocation.
This type of semaphore can be used for pure synchronisation between tasks or between an interrupt and a task. The semaphore need not be given back once obtained, so one task/interrupt can continuouslymgiventhe semaphore while another continuouslymtakesnthe semaphore. For this reason this type of semaphore does not use a priority inheritance mechanism. For an alternative that does use priority inheritance see xSemaphoreCreateMutex().
Example usage:
SemaphoreHandle_t xSemaphore = NULL; StaticSemaphore_t xSemaphoreBuffer;
(continues on next page)

Espressif Systems

1197

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)
void vATask( void * pvParameters ) {
// Semaphore cannot be used before a call to xSemaphoreCreateBinary() or // xSemaphoreCreateBinaryStatic(). // The semaphore's data structures will be placed in the xSemaphoreBuffer // variable, the address of which is passed into the function. The // function's parameter is not NULL, so the function will not attempt any // dynamic memory allocation, and therefore the function will not return // return NULL. xSemaphore = xSemaphoreCreateBinaryStatic( &xSemaphoreBuffer );
// Rest of task code goes here. }

Return If the semaphore is created then a handle to the created semaphore is returned. If pxSemaphoreBuffer is NULL then NULL is returned.
Parameters · pxStaticSemaphore: Must point to a variable of type StaticSemaphore_t, which will then be used to hold the semaphorens data structure, removing the need for the memory to be allocated dynamically.
xSemaphoreTake(xSemaphore, xBlockTime) Macro to obtain a semaphore. The semaphore must have previously been created with a call to xSemaphoreCreateBinary(), xSemaphoreCreateMutex() or xSemaphoreCreateCounting().
param xSemaphore A handle to the semaphore being taken - obtained when the semaphore was created.
param xBlockTime The time in ticks to wait for the semaphore to become available. The macro portTICK_PERIOD_MS can be used to convert this to a real time. A block time of zero can be used to poll the semaphore. A block time of portMAX_DELAY can be used to block indefinitely (provided INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h).
Example usage:
SemaphoreHandle_t xSemaphore = NULL;

// A task that creates a semaphore. void vATask( void * pvParameters ) {
// Create the semaphore to guard a shared resource. vSemaphoreCreateBinary( xSemaphore ); }

// A task that uses the semaphore. void vAnotherTask( void * pvParameters ) {
// ... Do other things.

if( xSemaphore != NULL ) {
// See if we can obtain the semaphore. If the semaphore is not available // wait 10 ticks to see if it becomes free. if( xSemaphoreTake( xSemaphore, ( TickType_t ) 10 ) == pdTRUE ) {
// We were able to obtain the semaphore and can now access the // shared resource.

// ...

// We have finished accessing the shared resource. // semaphore. xSemaphoreGive( xSemaphore );

Release the (continues on next page)

Espressif Systems

1198

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page) } else {
// We could not obtain the semaphore and can therefore not access // the shared resource safely. } } }
Return pdTRUE if the semaphore was obtained. pdFALSE if xBlockTime expired without the semaphore becoming available.
xSemaphoreTakeRecursive(xMutex, xBlockTime) Macro to recursively obtain, or mtaken, a mutex type semaphore. The mutex must have previously been created using a call to xSemaphoreCreateRecursiveMutex();
configUSE_RECURSIVE_MUTEXES must be set to 1 in FreeRTOSConfig.h for this macro to be available.
This macro must not be used on mutexes created using xSemaphoreCreateMutex().
A mutex used recursively can be mtakennrepeatedly by the owner. The mutex doesnnt become available again until the owner has called xSemaphoreGiveRecursive() for each successfulmtakenrequest. For example, if a task successfully mtakesnthe same mutex 5 times then the mutex will not be available to any other task until it has also mgivennthe mutex back exactly five times.
Example usage:
SemaphoreHandle_t xMutex = NULL;
// A task that creates a mutex. void vATask( void * pvParameters ) {
// Create the mutex to guard a shared resource. xMutex = xSemaphoreCreateRecursiveMutex(); }
// A task that uses the mutex. void vAnotherTask( void * pvParameters ) {
// ... Do other things.
if( xMutex != NULL ) {
// See if we can obtain the mutex. If the mutex is not available // wait 10 ticks to see if it becomes free. if( xSemaphoreTakeRecursive( xSemaphore, ( TickType_t ) 10 ) == pdTRUE ) {
// We were able to obtain the mutex and can now access the // shared resource.
// ... // For some reason due to the nature of the code further calls to // xSemaphoreTakeRecursive() are made on the same mutex. In real // code these would not be just sequential calls as this would make // no sense. Instead the calls are likely to be buried inside // a more complex call structure. xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 ); xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 );
// The mutex has now been 'taken' three times, so will not be // available to another task until it has also been given back // three times. Again it is unlikely that real code would have
(continues on next page)

Espressif Systems

1199

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page) // these calls sequentially, but instead buried in a more complex // call structure. This is just for illustrative purposes. xSemaphoreGiveRecursive( xMutex ); xSemaphoreGiveRecursive( xMutex ); xSemaphoreGiveRecursive( xMutex );
// Now the mutex can be taken by other tasks. } else {
// We could not obtain the mutex and can therefore not access // the shared resource safely. } } }
Return pdTRUE if the semaphore was obtained. pdFALSE if xBlockTime expired without the semaphore becoming available.
Parameters · xMutex: A handle to the mutex being obtained. This is the handle returned by xSemaphoreCreateRecursiveMutex(); · xBlockTime: The time in ticks to wait for the semaphore to become available. The macro portTICK_PERIOD_MS can be used to convert this to a real time. A block time of zero can be used to poll the semaphore. If the task already owns the semaphore then xSemaphoreTakeRecursive() will return immediately no matter what the value of xBlockTime.
xSemaphoreGive(xSemaphore) Macro to release a semaphore. The semaphore must have previously been created with a call to xSemaphoreCreateBinary(), xSemaphoreCreateMutex() or xSemaphoreCreateCounting(). and obtained using sSemaphoreTake().
This macro must not be used from an ISR. See xSemaphoreGiveFromISR () for an alternative which can be used from an ISR.
This macro must also not be used on semaphores created using xSemaphoreCreateRecursiveMutex().
Example usage:
SemaphoreHandle_t xSemaphore = NULL;
void vATask( void * pvParameters ) {
// Create the semaphore to guard a shared resource. vSemaphoreCreateBinary( xSemaphore );
if( xSemaphore != NULL ) {
if( xSemaphoreGive( xSemaphore ) != pdTRUE ) {
// We would expect this call to fail because we cannot give // a semaphore without first "taking" it! }
// Obtain the semaphore - don't block if the semaphore is not // immediately available. if( xSemaphoreTake( xSemaphore, ( TickType_t ) 0 ) ) {
// We now have the semaphore and can access the shared resource.
// ...
(continues on next page)

Espressif Systems

1200

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)
// We have finished accessing the shared resource so can free the // semaphore. if( xSemaphoreGive( xSemaphore ) != pdTRUE ) {
// We would not expect this call to fail because we must have // obtained the semaphore to get here. } } } }
Return pdTRUE if the semaphore was released. pdFALSE if an error occurred. Semaphores are implemented using queues. An error can occur if there is no space on the queue to post a message - indicating that the semaphore was not first obtained correctly.
Parameters · xSemaphore: A handle to the semaphore being released. This is the handle returned when the semaphore was created.
xSemaphoreGiveRecursive(xMutex) Macro to recursively release, or mgiven, a mutex type semaphore. The mutex must have previously been created using a call to xSemaphoreCreateRecursiveMutex();
configUSE_RECURSIVE_MUTEXES must be set to 1 in FreeRTOSConfig.h for this macro to be available.
This macro must not be used on mutexes created using xSemaphoreCreateMutex().
A mutex used recursively can be mtakennrepeatedly by the owner. The mutex doesnnt become available again until the owner has called xSemaphoreGiveRecursive() for each successfulmtakenrequest. For example, if a task successfully mtakesnthe same mutex 5 times then the mutex will not be available to any other task until it has also mgivennthe mutex back exactly five times.
Example usage:
SemaphoreHandle_t xMutex = NULL;
// A task that creates a mutex. void vATask( void * pvParameters ) {
// Create the mutex to guard a shared resource. xMutex = xSemaphoreCreateRecursiveMutex(); }
// A task that uses the mutex. void vAnotherTask( void * pvParameters ) {
// ... Do other things.
if( xMutex != NULL ) {
// See if we can obtain the mutex. If the mutex is not available // wait 10 ticks to see if it becomes free. if( xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 ) == pdTRUE ) {
// We were able to obtain the mutex and can now access the // shared resource.
// ... // For some reason due to the nature of the code further calls to // xSemaphoreTakeRecursive() are made on the same mutex. In real // code these would not be just sequential calls as this would make // no sense. Instead the calls are likely to be buried inside // a more complex call structure.
(continues on next page)

Espressif Systems

1201

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)
xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 ); xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 );
// The mutex has now been 'taken' three times, so will not be // available to another task until it has also been given back // three times. Again it is unlikely that real code would have // these calls sequentially, it would be more likely that the calls // to xSemaphoreGiveRecursive() would be called as a call stack // unwound. This is just for demonstrative purposes. xSemaphoreGiveRecursive( xMutex ); xSemaphoreGiveRecursive( xMutex ); xSemaphoreGiveRecursive( xMutex );
// Now the mutex can be taken by other tasks. } else {
// We could not obtain the mutex and can therefore not access // the shared resource safely. } } }

Return pdTRUE if the semaphore was given. Parameters
· xMutex: A handle to the mutex being released, or mgivenn. This is the handle returned by xSemaphoreCreateMutex();
xSemaphoreGiveFromISR(xSemaphore, pxHigherPriorityTaskWoken) Macro to release a semaphore. The semaphore must have previously been created with a call to xSemaphoreCreateBinary() or xSemaphoreCreateCounting().
Mutex type semaphores (those created using a call to xSemaphoreCreateMutex()) must not be used with this macro.
This macro can be used from an ISR.
Example usage:

#define LONG_TIME 0xffff #define TICKS_TO_WAIT 10 SemaphoreHandle_t xSemaphore = NULL;

// Repetitive task. void vATask( void * pvParameters ) {
for( ;; ) {
// We want this task to run every 10 ticks of a timer. // was created before this task was started.

The semaphore

// Block waiting for the semaphore to become available. if( xSemaphoreTake( xSemaphore, LONG_TIME ) == pdTRUE ) {
// It is time to execute.

// ...

// We have finished our task. Return to the top of the loop where // we will block on the semaphore until it is time to execute // again. Note when using the semaphore for synchronisation with an // ISR in this manner there is no need to 'give' the semaphore back.
(continues on next page)

Espressif Systems

1202

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

} } }

(continued from previous page)

// Timer ISR void vTimerISR( void * pvParameters ) { static uint8_t ucLocalTickCount = 0; static BaseType_t xHigherPriorityTaskWoken;

// A timer tick has occurred.

// ... Do other time functions.

// Is it time for vATask () to run? xHigherPriorityTaskWoken = pdFALSE; ucLocalTickCount++; if( ucLocalTickCount >= TICKS_TO_WAIT ) {
// Unblock the task by releasing the semaphore. xSemaphoreGiveFromISR( xSemaphore, &xHigherPriorityTaskWoken );

// Reset the count so we release the semaphore again in 10 ticks time. ucLocalTickCount = 0; }

if( xHigherPriorityTaskWoken != pdFALSE ) {
// We can force a context switch here. Context switching from an // ISR uses port specific syntax. Check the demo task for your port // to find the syntax required. } }

Return pdTRUE if the semaphore was successfully given, otherwise errQUEUE_FULL. Parameters
· xSemaphore: A handle to the semaphore being released. This is the handle returned when the semaphore was created.
· pxHigherPriorityTaskWoken: xSemaphoreGiveFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE if giving the semaphore caused a task to unblock, and the unblocked task has a priority higher than the currently running task. If xSemaphoreGiveFromISR() sets this value to pdTRUE then a context switch should be requested before the interrupt is exited.
xSemaphoreTakeFromISR(xSemaphore, pxHigherPriorityTaskWoken) Macro to take a semaphore from an ISR. The semaphore must have previously been created with a call to xSemaphoreCreateBinary() or xSemaphoreCreateCounting().
Mutex type semaphores (those created using a call to xSemaphoreCreateMutex()) must not be used with this macro.
This macro can be used from an ISR, however taking a semaphore from an ISR is not a common operation. It is likely to only be useful when taking a counting semaphore when an interrupt is obtaining an object from a resource pool (when the semaphore count indicates the number of resources available).
Return pdTRUE if the semaphore was successfully taken, otherwise pdFALSE Parameters
· xSemaphore: A handle to the semaphore being taken. This is the handle returned when the semaphore was created.
· [out] pxHigherPriorityTaskWoken: xSemaphoreTakeFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE if taking the semaphore caused a task to unblock, and the unblocked task has a priority higher than the currently running task. If xSemaphoreTakeFromISR() sets this value to pdTRUE then a context switch should be requested before the interrupt is exited.

Espressif Systems

1203

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
xSemaphoreCreateMutex() Creates a new mutex type semaphore instance, and returns a handle by which the new mutex can be referenced.
Internally, within the FreeRTOS implementation, mutex semaphores use a block of memory, in which the mutex structure is stored. If a mutex is created using xSemaphoreCreateMutex() then the required memory is automatically dynamically allocated inside the xSemaphoreCreateMutex() function. (see https: //www.FreeRTOS.org/a00111.html). If a mutex is created using xSemaphoreCreateMutexStatic() then the application writer must provided the memory. xSemaphoreCreateMutexStatic() therefore allows a mutex to be created without using any dynamic memory allocation.
Mutexes created using this function can be accessed using the xSemaphoreTake() and xSemaphoreGive() macros. The xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros must not be used.
This type of semaphore uses a priority inheritance mechanism so a taskmtakingna semaphore MUST ALWAYS mgiventhe semaphore back once the semaphore it is no longer required.
Mutex type semaphores cannot be used from within interrupt service routines.
See xSemaphoreCreateBinary() for an alternative implementation that can be used for pure synchronisation (where one task or interrupt always mgivesnthe semaphore and another always mtakesnthe semaphore) and from within interrupt service routines.
Example usage:
SemaphoreHandle_t xSemaphore;
void vATask( void * pvParameters ) {
// Semaphore cannot be used before a call to xSemaphoreCreateMutex(). // This is a macro so pass the variable in directly. xSemaphore = xSemaphoreCreateMutex();
if( xSemaphore != NULL ) {
// The semaphore was created successfully. // The semaphore can now be used. } }
Return If the mutex was successfully created then a handle to the created semaphore is returned. If there was not enough heap to allocate the mutex data structures then NULL is returned.
xSemaphoreCreateMutexStatic(pxMutexBuffer) Creates a new mutex type semaphore instance, and returns a handle by which the new mutex can be referenced.
Internally, within the FreeRTOS implementation, mutex semaphores use a block of memory, in which the mutex structure is stored. If a mutex is created using xSemaphoreCreateMutex() then the required memory is automatically dynamically allocated inside the xSemaphoreCreateMutex() function. (see https: //www.FreeRTOS.org/a00111.html). If a mutex is created using xSemaphoreCreateMutexStatic() then the application writer must provided the memory. xSemaphoreCreateMutexStatic() therefore allows a mutex to be created without using any dynamic memory allocation.
Mutexes created using this function can be accessed using the xSemaphoreTake() and xSemaphoreGive() macros. The xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros must not be used.
This type of semaphore uses a priority inheritance mechanism so a taskmtakingna semaphore MUST ALWAYS mgiventhe semaphore back once the semaphore it is no longer required.
Mutex type semaphores cannot be used from within interrupt service routines.
See xSemaphoreCreateBinary() for an alternative implementation that can be used for pure synchronisation (where one task or interrupt always mgivesnthe semaphore and another always mtakesnthe semaphore) and from within interrupt service routines.
Example usage:

Espressif Systems

1204

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

SemaphoreHandle_t xSemaphore; StaticSemaphore_t xMutexBuffer;
void vATask( void * pvParameters ) {
// A mutex cannot be used before it has been created. xMutexBuffer is // into xSemaphoreCreateMutexStatic() so no dynamic memory allocation is // attempted. xSemaphore = xSemaphoreCreateMutexStatic( &xMutexBuffer );
// As no dynamic memory allocation was performed, xSemaphore cannot be NULL, // so there is no need to check it. }

Return If the mutex was successfully created then a handle to the created mutex is returned. If pxMutexBuffer was NULL then NULL is returned.
Parameters · pxMutexBuffer: Must point to a variable of type StaticSemaphore_t, which will be used to hold the mutexns data structure, removing the need for the memory to be allocated dynamically.
xSemaphoreCreateCounting(uxMaxCount, uxInitialCount) Creates a new recursive mutex type semaphore instance, and returns a handle by which the new recursive mutex can be referenced.
Internally, within the FreeRTOS implementation, recursive mutexs use a block of memory, in which the mutex structure is stored. If a recursive mutex is created using xSemaphoreCreateRecursiveMutex() then the required memory is automatically dynamically allocated inside the xSemaphoreCreateRecursiveMutex() function. (see http://www.freertos.org/a00111.html). If a recursive mutex is created using xSemaphoreCreateRecursiveMutexStatic() then the application writer must provide the memory that will get used by the mutex. xSemaphoreCreateRecursiveMutexStatic() therefore allows a recursive mutex to be created without using any dynamic memory allocation.
Mutexes created using this macro can be accessed using the xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros. The xSemaphoreTake() and xSemaphoreGive() macros must not be used.
A mutex used recursively can be mtakennrepeatedly by the owner. The mutex doesnnt become available again until the owner has called xSemaphoreGiveRecursive() for each successfulmtakenrequest. For example, if a task successfully mtakesnthe same mutex 5 times then the mutex will not be available to any other task until it has also mgivennthe mutex back exactly five times.
This type of semaphore uses a priority inheritance mechanism so a taskmtakingna semaphore MUST ALWAYS mgiventhe semaphore back once the semaphore it is no longer required.
Mutex type semaphores cannot be used from within interrupt service routines.
See vSemaphoreCreateBinary() for an alternative implementation that can be used for pure synchronisation (where one task or interrupt always mgivesnthe semaphore and another always mtakesnthe semaphore) and from within interrupt service routines.
Example usage:

SemaphoreHandle_t xSemaphore;

void vATask( void * pvParameters ) {
// Semaphore cannot be used before a call to xSemaphoreCreateMutex(). // This is a macro so pass the variable in directly. xSemaphore = xSemaphoreCreateRecursiveMutex();

if( xSemaphore != NULL ) {
// The semaphore was created successfully. // The semaphore can now be used.

(continues on next page)

Espressif Systems

1205

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

} }

(continued from previous page)

Creates a new recursive mutex type semaphore instance, and returns a handle by which the new recursive mutex can be referenced.
Return xSemaphore Handle to the created mutex semaphore. Should be of type SemaphoreHandle_t.
Internally, within the FreeRTOS implementation, recursive mutexs use a block of memory, in which the mutex structure is stored. If a recursive mutex is created using xSemaphoreCreateRecursiveMutex() then the required memory is automatically dynamically allocated inside the xSemaphoreCreateRecursiveMutex() function. (see https://www.FreeRTOS.org/a00111.html). If a recursive mutex is created using xSemaphoreCreateRecursiveMutexStatic() then the application writer must provide the memory that will get used by the mutex. xSemaphoreCreateRecursiveMutexStatic() therefore allows a recursive mutex to be created without using any dynamic memory allocation.
Mutexes created using this macro can be accessed using the xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros. The xSemaphoreTake() and xSemaphoreGive() macros must not be used.
A mutex used recursively can be mtakennrepeatedly by the owner. The mutex doesnnt become available again until the owner has called xSemaphoreGiveRecursive() for each successfulmtakenrequest. For example, if a task successfully mtakesnthe same mutex 5 times then the mutex will not be available to any other task until it has also mgivennthe mutex back exactly five times.
This type of semaphore uses a priority inheritance mechanism so a taskmtakingna semaphore MUST ALWAYS mgiventhe semaphore back once the semaphore it is no longer required.
Mutex type semaphores cannot be used from within interrupt service routines.
See xSemaphoreCreateBinary() for an alternative implementation that can be used for pure synchronisation (where one task or interrupt always mgivesnthe semaphore and another always mtakesnthe semaphore) and from within interrupt service routines.
Example usage:
SemaphoreHandle_t xSemaphore; StaticSemaphore_t xMutexBuffer;
void vATask( void * pvParameters ) {
// A recursive semaphore cannot be used before it is created. Here a // recursive mutex is created using xSemaphoreCreateRecursiveMutexStatic(). // The address of xMutexBuffer is passed into the function, and will hold // the mutexes data structures - so no dynamic memory allocation will be // attempted. xSemaphore = xSemaphoreCreateRecursiveMutexStatic( &xMutexBuffer );
// As no dynamic memory allocation was performed, xSemaphore cannot be NULL, // so there is no need to check it. }

Creates a new counting semaphore instance, and returns a handle by which the new counting semaphore can be referenced.
Return If the recursive mutex was successfully created then a handle to the created recursive mutex is returned. If pxMutexBuffer was NULL then NULL is returned.
Parameters · pxStaticSemaphore: Must point to a variable of type StaticSemaphore_t, which will then be used to hold the recursive mutexns data structure, removing the need for the memory to be allocated dynamically.
In many usage scenarios it is faster and more memory efficient to use a direct to task notification in place of a counting semaphore! https://www.FreeRTOS.org/RTOS-task-notifications.html

Espressif Systems

1206

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Internally, within the FreeRTOS implementation, counting semaphores use a block of memory, in which the counting semaphore structure is stored. If a counting semaphore is created using xSemaphoreCreateCounting() then the required memory is automatically dynamically allocated inside the xSemaphoreCreateCounting() function. (see https://www.FreeRTOS.org/a00111.html). If a counting semaphore is created using xSemaphoreCreateCountingStatic() then the application writer can instead optionally provide the memory that will get used by the counting semaphore. xSemaphoreCreateCountingStatic() therefore allows a counting semaphore to be created without using any dynamic memory allocation.
Counting semaphores are typically used for two things:
1) Counting events.
In this usage scenario an event handler will mgivena semaphore each time an event occurs (incrementing the semaphore count value), and a handler task will mtakena semaphore each time it processes an event (decrementing the semaphore count value). The count value is therefore the difference between the number of events that have occurred and the number that have been processed. In this case it is desirable for the initial count value to be zero.
2) Resource management.
In this usage scenario the count value indicates the number of resources available. To obtain control of a resource a task must first obtain a semaphore - decrementing the semaphore count value. When the count value reaches zero there are no free resources. When a task finishes with the resource itmgivesnthe semaphore back - incrementing the semaphore count value. In this case it is desirable for the initial count value to be equal to the maximum count value, indicating that all resources are free.
Example usage:
SemaphoreHandle_t xSemaphore;
void vATask( void * pvParameters ) { SemaphoreHandle_t xSemaphore = NULL;
// Semaphore cannot be used before a call to xSemaphoreCreateCounting(). // The max value to which the semaphore can count should be 10, and the // initial value assigned to the count should be 0. xSemaphore = xSemaphoreCreateCounting( 10, 0 );
if( xSemaphore != NULL ) {
// The semaphore was created successfully. // The semaphore can now be used. } }
Return Handle to the created semaphore. Null if the semaphore could not be created. Parameters
· uxMaxCount: The maximum count value that can be reached. When the semaphore reaches this value it can no longer be mgivenn.
· uxInitialCount: The count value assigned to the semaphore when it is created.
xSemaphoreCreateCountingStatic(uxMaxCount, uxInitialCount, pxSemaphoreBuffer) Creates a new counting semaphore instance, and returns a handle by which the new counting semaphore can be referenced.
In many usage scenarios it is faster and more memory efficient to use a direct to task notification in place of a counting semaphore! https://www.FreeRTOS.org/RTOS-task-notifications.html
Internally, within the FreeRTOS implementation, counting semaphores use a block of memory, in which the counting semaphore structure is stored. If a counting semaphore is created using xSemaphoreCreateCounting() then the required memory is automatically dynamically allocated inside the xSemaphoreCreateCounting() function. (see https://www.FreeRTOS.org/a00111.html). If a counting semaphore is created using

Espressif Systems

1207

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
xSemaphoreCreateCountingStatic() then the application writer must provide the memory. xSemaphoreCreateCountingStatic() therefore allows a counting semaphore to be created without using any dynamic memory allocation.
Counting semaphores are typically used for two things:
1) Counting events.
In this usage scenario an event handler will mgivena semaphore each time an event occurs (incrementing the semaphore count value), and a handler task will mtakena semaphore each time it processes an event (decrementing the semaphore count value). The count value is therefore the difference between the number of events that have occurred and the number that have been processed. In this case it is desirable for the initial count value to be zero.
2) Resource management.
In this usage scenario the count value indicates the number of resources available. To obtain control of a resource a task must first obtain a semaphore - decrementing the semaphore count value. When the count value reaches zero there are no free resources. When a task finishes with the resource itmgivesnthe semaphore back - incrementing the semaphore count value. In this case it is desirable for the initial count value to be equal to the maximum count value, indicating that all resources are free.
Example usage:
SemaphoreHandle_t xSemaphore; StaticSemaphore_t xSemaphoreBuffer;
void vATask( void * pvParameters ) { SemaphoreHandle_t xSemaphore = NULL;
// Counting semaphore cannot be used before they have been created. Create // a counting semaphore using xSemaphoreCreateCountingStatic(). The max // value to which the semaphore can count is 10, and the initial value // assigned to the count will be 0. The address of xSemaphoreBuffer is // passed in and will be used to hold the semaphore structure, so no dynamic // memory allocation will be used. xSemaphore = xSemaphoreCreateCounting( 10, 0, &xSemaphoreBuffer );
// No memory allocation was attempted so xSemaphore cannot be NULL, so there // is no need to check its value. }
Return If the counting semaphore was successfully created then a handle to the created counting semaphore is returned. If pxSemaphoreBuffer was NULL then NULL is returned.
Parameters · uxMaxCount: The maximum count value that can be reached. When the semaphore reaches this value it can no longer be mgivenn. · uxInitialCount: The count value assigned to the semaphore when it is created. · pxSemaphoreBuffer: Must point to a variable of type StaticSemaphore_t, which will then be used to hold the semaphorens data structure, removing the need for the memory to be allocated dynamically.
vSemaphoreDelete(xSemaphore) Delete a semaphore. This function must be used with care. For example, do not delete a mutex type semaphore if the mutex is held by a task.
Parameters · xSemaphore: A handle to the semaphore to be deleted.
xSemaphoreGetMutexHolder(xSemaphore) If xMutex is indeed a mutex type semaphore, return the current mutex holder. If xMutex is not a mutex type semaphore, or the mutex is available (not held by a task), return NULL.

Espressif Systems

1208

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Note: This is a good way of determining if the calling task is the mutex holder, but not a good way of determining the identity of the mutex holder as the holder may change between the function exiting and the returned value being tested.
xSemaphoreGetMutexHolderFromISR(xSemaphore) If xMutex is indeed a mutex type semaphore, return the current mutex holder. If xMutex is not a mutex type semaphore, or the mutex is available (not held by a task), return NULL.
uxSemaphoreGetCount(xSemaphore) If the semaphore is a counting semaphore then uxSemaphoreGetCount() returns its current count value. If the semaphore is a binary semaphore then uxSemaphoreGetCount() returns 1 if the semaphore is available, and 0 if the semaphore is not available.
Type Definitions typedef QueueHandle_t SemaphoreHandle_t
Timer API
Header File
· components/freertos/FreeRTOS-Kernel/include/freertos/timers.h
Functions TimerHandle_t xTimerCreate(const char *const pcTimerName, const TickType_t xTimerPeriod-
InTicks, const UBaseType_t uxAutoReload, void *const pvTimerID, TimerCallbackFunction_t pxCallbackFunction) TimerHandle_t xTimerCreate( const char * const pcTimerName, TickType_t xTimerPeriodInTicks, UBaseType_t uxAutoReload, void * pvTimerID, TimerCallbackFunction_t pxCallbackFunction );
Creates a new software timer instance, and returns a handle by which the created software timer can be referenced.
Internally, within the FreeRTOS implementation, software timers use a block of memory, in which the timer data structure is stored. If a software timer is created using xTimerCreate() then the required memory is automatically dynamically allocated inside the xTimerCreate() function. (see https://www.FreeRTOS.org/a00111. html). If a software timer is created using xTimerCreateStatic() then the application writer must provide the memory that will get used by the software timer. xTimerCreateStatic() therefore allows a software timer to be created without using any dynamic memory allocation.
Timers are created in the dormant state. The xTimerStart(), xTimerReset(), xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and xTimerChangePeriodFromISR() API functions can all be used to transition a timer into the active state.
Example usage:
* #define NUM_TIMERS 5 * * // An array to hold handles to the created timers. * TimerHandle_t xTimers[ NUM_TIMERS ]; * * // An array to hold a count of the number of times each timer expires. * int32_t lExpireCounters[ NUM_TIMERS ] = { 0 }; * * // Define a callback function that will be used by multiple timer instances. * // The callback function does nothing but count the number of times the * // associated timer expires, and stop the timer once the timer has expired * // 10 times. * void vTimerCallback( TimerHandle_t pxTimer ) *{ * int32_t lArrayIndex;
(continues on next page)

Espressif Systems

1209

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)

* const int32_t xMaxExpiryCountBeforeStopping = 10;

*

*

// Optionally do something if the pxTimer parameter is NULL.

*

configASSERT( pxTimer );

*

*

// Which timer expired?

*

lArrayIndex = ( int32_t ) pvTimerGetTimerID( pxTimer );

*

*

// Increment the number of times that pxTimer has expired.

*

lExpireCounters[ lArrayIndex ] += 1;

*

*

// If the timer has expired 10 times then stop it from running.

*

if( lExpireCounters[ lArrayIndex ] == xMaxExpiryCountBeforeStopping )

*

{

*

// Do not use a block time if calling a timer API function from a

*

// timer callback function, as doing so could cause a deadlock!

*

xTimerStop( pxTimer, 0 );

*

}

*}

*

* void main( void )

*{

* int32_t x;

*

*

// Create then start some timers. Starting the timers before the

scheduler

*

// has been started means the timers will start running immediately that

*

// the scheduler starts.

*

for( x = 0; x < NUM_TIMERS; x++ )

*

{

*

xTimers[ x ] = xTimerCreate( "Timer",

// Just a text name,

not used by the kernel.

*

( 100 * x ), // The timer period

in ticks.

*

pdTRUE,

// The timers will

auto-reload themselves when they expire.

*

( void * ) x, // Assign each timer

a unique id equal to its array index.

*

vTimerCallback // Each timer calls

the same callback when it expires.

*

);

*

*

if( xTimers[ x ] == NULL )

*

{

*

// The timer was not created.

*

}

*

else

*

{

*

// Start the timer. No block time is specified, and even if one

was

*

// it would be ignored because the scheduler has not yet been

*

// started.

*

if( xTimerStart( xTimers[ x ], 0 ) != pdPASS )

*

{

*

// The timer could not be set into the Active state.

*

}

*

}

*

}

*

*

// ...

*

// Create tasks here.

(continues on next page)

Espressif Systems

1210

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)

*

// ...

*

*

// Starting the scheduler will start the timers running as they have

already

*

// been set into the active state.

*

vTaskStartScheduler();

*

*

// Should not reach here.

*

for( ;; );

*}

*

Return If the timer is successfully created then a handle to the newly created timer is returned. If the timer cannot be created (because either there is insufficient FreeRTOS heap remaining to allocate the timer structures, or the timer period was set to 0) then NULL is returned.
Parameters · pcTimerName: A text name that is assigned to the timer. This is done purely to assist debugging. The kernel itself only ever references a timer by its handle, and never by its name. · xTimerPeriodInTicks: The timer period. The time is defined in tick periods so the constant portTICK_PERIOD_MS can be used to convert a time that has been specified in milliseconds. For example, if the timer must expire after 100 ticks, then xTimerPeriodInTicks should be set to 100. Alternatively, if the timer must expire after 500ms, then xPeriod can be set to ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or equal to 1000. Time timer period must be greater than 0. · uxAutoReload: If uxAutoReload is set to pdTRUE then the timer will expire repeatedly with a frequency set by the xTimerPeriodInTicks parameter. If uxAutoReload is set to pdFALSE then the timer will be a one-shot timer and enter the dormant state after it expires. · pvTimerID: An identifier that is assigned to the timer being created. Typically this would be used in the timer callback function to identify which timer expired when the same callback function is assigned to more than one timer. · pxCallbackFunction: The function to call when the timer expires. Callback functions must have the prototype defined by TimerCallbackFunction_t, which isovoid vCallbackFunction( TimerHandle_t xTimer );p.
TimerHandle_t xTimerCreateStatic(const char *const pcTimerName, const TickType_t xTimerPeriodInTicks, const UBaseType_t uxAutoReload, void *const pvTimerID, TimerCallbackFunction_t pxCallbackFunction, StaticTimer_t *pxTimerBuffer)
TimerHandle_t xTimerCreateStatic(const char * const pcTimerName, TickType_t xTimerPeriodInTicks, UBaseType_t uxAutoReload, void * pvTimerID, TimerCallbackFunction_t pxCallbackFunction, StaticTimer_t *pxTimerBuffer );
Creates a new software timer instance, and returns a handle by which the created software timer can be referenced.
Internally, within the FreeRTOS implementation, software timers use a block of memory, in which the timer data structure is stored. If a software timer is created using xTimerCreate() then the required memory is automatically dynamically allocated inside the xTimerCreate() function. (see https://www.FreeRTOS.org/a00111. html). If a software timer is created using xTimerCreateStatic() then the application writer must provide the memory that will get used by the software timer. xTimerCreateStatic() therefore allows a software timer to be created without using any dynamic memory allocation.
Timers are created in the dormant state. The xTimerStart(), xTimerReset(), xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and xTimerChangePeriodFromISR() API functions can all be used to transition a timer into the active state.
Example usage:
* * // The buffer used to hold the software timer's data structure. * static StaticTimer_t xTimerBuffer;
(continues on next page)

Espressif Systems

1211

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)

*

* // A variable that will be incremented by the software timer's callback

* // function.

* UBaseType_t uxVariableToIncrement = 0;

*

* // A software timer callback function that increments a variable passed to

* // it when the software timer was created. After the 5th increment the

* // callback function stops the software timer.

* static void prvTimerCallback( TimerHandle_t xExpiredTimer )

*{

* UBaseType_t *puxVariableToIncrement;

* BaseType_t xReturned;

*

*

// Obtain the address of the variable to increment from the timer ID.

*

puxVariableToIncrement = ( UBaseType_t * ) pvTimerGetTimerID(

xExpiredTimer );

*

*

// Increment the variable to show the timer callback has executed.

*

( *puxVariableToIncrement )++;

*

*

// If this callback has executed the required number of times, stop the

*

// timer.

*

if( *puxVariableToIncrement == 5 )

*

{

*

// This is called from a timer callback so must not block.

*

xTimerStop( xExpiredTimer, staticDONT_BLOCK );

*

}

*}

*

*

* void main( void )

*{

*

// Create the software time. xTimerCreateStatic() has an extra parameter

*

// than the normal xTimerCreate() API function. The parameter is a

pointer

*

// to the StaticTimer_t structure that will hold the software timer

*

// structure. If the parameter is passed as NULL then the structure

will be

*

// allocated dynamically, just as if xTimerCreate() had been called.

*

xTimer = xTimerCreateStatic( "T1",

// Text name for the task.

 Helps debugging only. Not used by FreeRTOS.

*

xTimerPeriod,

// The period of the

timer in ticks.

*

pdTRUE,

// This is an auto-reload

timer.

*

( void * ) &uxVariableToIncrement, // A

variable incremented by the software timer's callback function

*

prvTimerCallback, // The function to

execute when the timer expires.

*

&xTimerBuffer ); // The buffer that will

hold the software timer structure.

*

*

// The scheduler has not started yet so a block time is not used.

*

xReturned = xTimerStart( xTimer, 0 );

*

*

// ...

*

// Create tasks here.

*

// ...

*

*

// Starting the scheduler will start the timers running as they have

already

(continues on next page)

Espressif Systems

1212

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

*

// been set into the active state.

*

vTaskStartScheduler();

*

*

// Should not reach here.

*

for( ;; );

*}

*

(continued from previous page)

Return If the timer is created then a handle to the created timer is returned. If pxTimerBuffer was NULL then NULL is returned.
Parameters · pcTimerName: A text name that is assigned to the timer. This is done purely to assist debugging. The kernel itself only ever references a timer by its handle, and never by its name. · xTimerPeriodInTicks: The timer period. The time is defined in tick periods so the constant portTICK_PERIOD_MS can be used to convert a time that has been specified in milliseconds. For example, if the timer must expire after 100 ticks, then xTimerPeriodInTicks should be set to 100. Alternatively, if the timer must expire after 500ms, then xPeriod can be set to ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or equal to 1000. The timer period must be greater than 0. · uxAutoReload: If uxAutoReload is set to pdTRUE then the timer will expire repeatedly with a frequency set by the xTimerPeriodInTicks parameter. If uxAutoReload is set to pdFALSE then the timer will be a one-shot timer and enter the dormant state after it expires. · pvTimerID: An identifier that is assigned to the timer being created. Typically this would be used in the timer callback function to identify which timer expired when the same callback function is assigned to more than one timer. · pxCallbackFunction: The function to call when the timer expires. Callback functions must have the prototype defined by TimerCallbackFunction_t, which isovoid vCallbackFunction( TimerHandle_t xTimer );p. · pxTimerBuffer: Must point to a variable of type StaticTimer_t, which will be then be used to hold the software timerns data structures, removing the need for the memory to be allocated dynamically.
void *pvTimerGetTimerID(const TimerHandle_t xTimer) void *pvTimerGetTimerID( TimerHandle_t xTimer );
Returns the ID assigned to the timer.
IDs are assigned to timers using the pvTimerID parameter of the call to xTimerCreated() that was used to create the timer, and by calling the vTimerSetTimerID() API function.
If the same callback function is assigned to multiple timers then the timer ID can be used as time specific (timer local) storage.
Example usage:
Return The ID assigned to the timer being queried. Parameters
· xTimer: The timer being queried.
See the xTimerCreate() API function example usage scenario.
void vTimerSetTimerID(TimerHandle_t xTimer, void *pvNewID) void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID );
Sets the ID assigned to the timer.
IDs are assigned to timers using the pvTimerID parameter of the call to xTimerCreated() that was used to create the timer.
If the same callback function is assigned to multiple timers then the timer ID can be used as time specific (timer local) storage.
Example usage:

Espressif Systems

1213

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Parameters · xTimer: The timer being updated. · pvNewID: The ID to assign to the timer.
See the xTimerCreate() API function example usage scenario.
BaseType_t xTimerIsTimerActive(TimerHandle_t xTimer) BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer );
Queries a timer to see if it is active or dormant.
A timer will be dormant if: 1) It has been created but not started, or 2) It is an expired one-shot timer that has not been restarted.
Timers are created in the dormant state. The xTimerStart(), xTimerReset(), xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and xTimerChangePeriodFromISR() API functions can all be used to transition a timer into the active state.
Example usage:

* // This function assumes xTimer has already been created.

* void vAFunction( TimerHandle_t xTimer )

*{

*

if( xTimerIsTimerActive( xTimer ) != pdFALSE ) // or more simply and

equivalently "if( xTimerIsTimerActive( xTimer ) )"

*

{

*

// xTimer is active, do something.

*

}

*

else

*

{

*

// xTimer is not active, do something else.

*

}

*}

*

Return pdFALSE will be returned if the timer is dormant. A value other than pdFALSE will be returned if the timer is active.
Parameters · xTimer: The timer being queried.
TaskHandle_t xTimerGetTimerDaemonTaskHandle(void) xTimerGetTimerDaemonTaskHandle() is only available if INCLUDE_xTimerGetTimerDaemonTaskHandle is set to 1 in FreeRTOSConfig.h.
Simply returns the handle of the timer service/daemon task. It it not valid to call xTimerGetTimerDaemonTaskHandle() before the scheduler has been started.
BaseType_t xTimerPendFunctionCallFromISR(PendedFunction_t xFunctionToPend, void *pvParameter1, uint32_t ulParameter2, BaseType_t *pxHigherPriorityTaskWoken)
BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend, void *pvParameter1, uint32_t ulParameter2, BaseType_t *pxHigherPriorityTaskWoken );
Used from application interrupt service routines to defer the execution of a function to the RTOS daemon task (the timer service task, hence this function is implemented in timers.c and is prefixed with mTimern).
Ideally an interrupt service routine (ISR) is kept as short as possible, but sometimes an ISR either has a lot of processing to do, or needs to perform processing that is not deterministic. In these cases xTimerPendFunctionCallFromISR() can be used to defer processing of a function to the RTOS daemon task.
A mechanism is provided that allows the interrupt to return directly to the task that will subsequently execute the pended callback function. This allows the callback function to execute contiguously in time with the interrupt - just as if the callback had executed in the interrupt itself.
Example usage:

Espressif Systems

1214

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

*

* // The callback function that will execute in the context of the daemon

task.

* // Note callback functions must all use this same prototype.

* void vProcessInterface( void *pvParameter1, uint32_t ulParameter2 )

*{

*

BaseType_t xInterfaceToService;

*

*

// The interface that requires servicing is passed in the second

*

// parameter. The first parameter is not used in this case.

*

xInterfaceToService = ( BaseType_t ) ulParameter2;

*

*

// ...Perform the processing here...

*}

*

* // An ISR that receives data packets from multiple interfaces

* void vAnISR( void )

*{

*

BaseType_t xInterfaceToService, xHigherPriorityTaskWoken;

*

*

// Query the hardware to determine which interface needs processing.

*

xInterfaceToService = prvCheckInterfaces();

*

*

// The actual processing is to be deferred to a task. Request the

*

// vProcessInterface() callback function is executed, passing in the

*

// number of the interface that needs processing. The interface to

*

// service is passed in the second parameter. The first parameter is

*

// not used in this case.

*

xHigherPriorityTaskWoken = pdFALSE;

*

xTimerPendFunctionCallFromISR( vProcessInterface, NULL, ( uint32_t )

xInterfaceToService, &xHigherPriorityTaskWoken );

*

*

// If xHigherPriorityTaskWoken is now set to pdTRUE then a context

*

// switch should be requested. The macro used is port specific and will

*

// be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() - refer to

*

// the documentation page for the port being used.

*

portYIELD_FROM_ISR( xHigherPriorityTaskWoken );

*

*}

*

Return pdPASS is returned if the message was successfully sent to the timer daemon task, otherwise pdFALSE is returned.
Parameters · xFunctionToPend: The function to execute from the timer service/ daemon task. The function must conform to the PendedFunction_t prototype. · pvParameter1: The value of the callback functionns first parameter. The parameter has a void * type to allow it to be used to pass any type. For example, unsigned longs can be cast to a void *, or the void * can be used to point to a structure. · ulParameter2: The value of the callback functionns second parameter. · pxHigherPriorityTaskWoken: As mentioned above, calling this function will result in a message being sent to the timer daemon task. If the priority of the timer daemon task (which is set using configTIMER_TASK_PRIORITY in FreeRTOSConfig.h) is higher than the priority of the currently running task (the task the interrupt interrupted) then *pxHigherPriorityTaskWoken will be set to pdTRUE within xTimerPendFunctionCallFromISR(), indicating that a context switch should be requested before the interrupt exits. For that reason *pxHigherPriorityTaskWoken must be initialised to pdFALSE. See the example code below.
BaseType_t xTimerPendFunctionCall(PendedFunction_t xFunctionToPend, void *pvParameter1, uint32_t ulParameter2, TickType_t xTicksToWait)
BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend, void *pvParameter1, uint32_t

Espressif Systems

1215

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ulParameter2, TickType_t xTicksToWait );
Used to defer the execution of a function to the RTOS daemon task (the timer service task, hence this function is implemented in timers.c and is prefixed with mTimern).
Return pdPASS is returned if the message was successfully sent to the timer daemon task, otherwise pdFALSE is returned.
Parameters · xFunctionToPend: The function to execute from the timer service/ daemon task. The function must conform to the PendedFunction_t prototype. · pvParameter1: The value of the callback functionns first parameter. The parameter has a void * type to allow it to be used to pass any type. For example, unsigned longs can be cast to a void *, or the void * can be used to point to a structure. · ulParameter2: The value of the callback functionns second parameter. · xTicksToWait: Calling this function will result in a message being sent to the timer daemon task on a queue. xTicksToWait is the amount of time the calling task should remain in the Blocked state (so not using any processing time) for space to become available on the timer queue if the queue is found to be full.
const char *pcTimerGetName(TimerHandle_t xTimer) const char * const pcTimerGetName( TimerHandle_t xTimer );
Returns the name that was assigned to a timer when the timer was created.
Return The name assigned to the timer specified by the xTimer parameter. Parameters
· xTimer: The handle of the timer being queried.
void vTimerSetReloadMode(TimerHandle_t xTimer, const UBaseType_t uxAutoReload) void vTimerSetReloadMode( TimerHandle_t xTimer, const UBaseType_t uxAutoReload );
Updates a timer to be either an auto-reload timer, in which case the timer automatically resets itself each time it expires, or a one-shot timer, in which case the timer will only expire once unless it is manually restarted.
Parameters · xTimer: The handle of the timer being updated. · uxAutoReload: If uxAutoReload is set to pdTRUE then the timer will expire repeatedly with a frequency set by the timerns period (see the xTimerPeriodInTicks parameter of the xTimerCreate() API function). If uxAutoReload is set to pdFALSE then the timer will be a one-shot timer and enter the dormant state after it expires.
UBaseType_t uxTimerGetReloadMode(TimerHandle_t xTimer) UBaseType_t uxTimerGetReloadMode( TimerHandle_t xTimer );
Queries a timer to determine if it is an auto-reload timer, in which case the timer automatically resets itself each time it expires, or a one-shot timer, in which case the timer will only expire once unless it is manually restarted.
Return If the timer is an auto-reload timer then pdTRUE is returned, otherwise pdFALSE is returned. Parameters
· xTimer: The handle of the timer being queried.
TickType_t xTimerGetPeriod(TimerHandle_t xTimer) TickType_t xTimerGetPeriod( TimerHandle_t xTimer );
Returns the period of a timer.
Return The period of the timer in ticks. Parameters
· xTimer: The handle of the timer being queried.
TickType_t xTimerGetExpiryTime(TimerHandle_t xTimer) TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer );
Returns the time in ticks at which the timer will expire. If this is less than the current tick count then the expiry time has overflowed from the current time.

Espressif Systems

1216

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return If the timer is running then the time in ticks at which the timer will next expire is returned. If the timer is not running then the return value is undefined.
Parameters · xTimer: The handle of the timer being queried.

void vApplicationGetTimerTaskMemory(StaticTask_t **ppxTimerTaskTCBBuffer, Stack-

Type_t **ppxTimerTaskStackBuffer,

uint32_t

*pulTimerTaskStackSize) This function is used to provide a statically allocated block of memory to FreeRTOS to hold the Timer Task

TCB. This function is required when configSUPPORT_STATIC_ALLOCATION is set. For more information

see this URI: https://www.FreeRTOS.org/a00110.html#configSUPPORT_STATIC_ALLOCATION

Parameters · ppxTimerTaskTCBBuffer: A handle to a statically allocated TCB buffer · ppxTimerTaskStackBuffer: A handle to a statically allocated Stack buffer for thie idle task · pulTimerTaskStackSize: A pointer to the number of elements that will fit in the allocated stack buffer

Macros tmrCOMMAND_EXECUTE_CALLBACK_FROM_ISR tmrCOMMAND_EXECUTE_CALLBACK
tmrCOMMAND_START_DONT_TRACE
tmrCOMMAND_START
tmrCOMMAND_RESET
tmrCOMMAND_STOP
tmrCOMMAND_CHANGE_PERIOD
tmrCOMMAND_DELETE
tmrFIRST_FROM_ISR_COMMAND
tmrCOMMAND_START_FROM_ISR
tmrCOMMAND_RESET_FROM_ISR
tmrCOMMAND_STOP_FROM_ISR
tmrCOMMAND_CHANGE_PERIOD_FROM_ISR
xTimerStart(xTimer, xTicksToWait) BaseType_t xTimerStart( TimerHandle_t xTimer, TickType_t xTicksToWait );
Timer functionality is provided by a timer service/daemon task. Many of the public FreeRTOS timer API functions send commands to the timer service task through a queue called the timer command queue. The timer command queue is private to the kernel itself and is not directly accessible to application code. The length of the timer command queue is set by the configTIMER_QUEUE_LENGTH configuration constant.
xTimerStart() starts a timer that was previously created using the xTimerCreate() API function. If the timer had already been started and was already in the active state, then xTimerStart() has equivalent functionality to the xTimerReset() API function.
Starting a timer ensures the timer is in the active state. If the timer is not stopped, deleted, or reset in the mean time, the callback function associated with the timer will get called mnnticks after xTimerStart() was called, where mnnis the timers defined period.
It is valid to call xTimerStart() before the scheduler has been started, but when this is done the timer will not actually start until the scheduler is started, and the timers expiry time will be relative to when the scheduler is started, not relative to when xTimerStart() was called.
The configUSE_TIMERS configuration constant must be set to 1 for xTimerStart() to be available.
Example usage:

Espressif Systems

1217

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Return pdFAIL will be returned if the start command could not be sent to the timer command queue even after xTicksToWait ticks had passed. pdPASS will be returned if the command was successfully sent to the timer command queue. When the command is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in the system, although the timers expiry time is relative to when xTimerStart() is actually called. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.
Parameters · xTimer: The handle of the timer being started/restarted. · xTicksToWait: Specifies the time, in ticks, that the calling task should be held in the Blocked state to wait for the start command to be successfully sent to the timer command queue, should the queue already be full when xTimerStart() was called. xTicksToWait is ignored if xTimerStart() is called before the scheduler is started.
See the xTimerCreate() API function example usage scenario.
xTimerStop(xTimer, xTicksToWait) BaseType_t xTimerStop( TimerHandle_t xTimer, TickType_t xTicksToWait );
Timer functionality is provided by a timer service/daemon task. Many of the public FreeRTOS timer API functions send commands to the timer service task through a queue called the timer command queue. The timer command queue is private to the kernel itself and is not directly accessible to application code. The length of the timer command queue is set by the configTIMER_QUEUE_LENGTH configuration constant.
xTimerStop() stops a timer that was previously started using either of the The xTimerStart(), xTimerReset(), xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() or xTimerChangePeriodFromISR() API functions.
Stopping a timer ensures the timer is not in the active state.
The configUSE_TIMERS configuration constant must be set to 1 for xTimerStop() to be available.
Example usage:
Return pdFAIL will be returned if the stop command could not be sent to the timer command queue even after xTicksToWait ticks had passed. pdPASS will be returned if the command was successfully sent to the timer command queue. When the command is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in the system. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.
Parameters · xTimer: The handle of the timer being stopped. · xTicksToWait: Specifies the time, in ticks, that the calling task should be held in the Blocked state to wait for the stop command to be successfully sent to the timer command queue, should the queue already be full when xTimerStop() was called. xTicksToWait is ignored if xTimerStop() is called before the scheduler is started.
See the xTimerCreate() API function example usage scenario.
xTimerChangePeriod(xTimer, xNewPeriod, xTicksToWait) BaseType_t xTimerChangePeriod( TimerHandle_t xTimer, TickType_t xNewPeriod, TickType_t xTicksToWait );
Timer functionality is provided by a timer service/daemon task. Many of the public FreeRTOS timer API functions send commands to the timer service task through a queue called the timer command queue. The timer command queue is private to the kernel itself and is not directly accessible to application code. The length of the timer command queue is set by the configTIMER_QUEUE_LENGTH configuration constant.
xTimerChangePeriod() changes the period of a timer that was previously created using the xTimerCreate() API function.
xTimerChangePeriod() can be called to change the period of an active or dormant state timer.
The configUSE_TIMERS configuration constant must be set to 1 for xTimerChangePeriod() to be available.
Example usage:

Espressif Systems

1218

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

* // This function assumes xTimer has already been created. If the timer

* // referenced by xTimer is already active when it is called, then the timer

* // is deleted. If the timer referenced by xTimer is not active when it is

* // called, then the period of the timer is set to 500ms and the timer is

* // started.

* void vAFunction( TimerHandle_t xTimer )

*{

*

if( xTimerIsTimerActive( xTimer ) != pdFALSE ) // or more simply and

equivalently "if( xTimerIsTimerActive( xTimer ) )"

*

{

*

// xTimer is already active - delete it.

*

xTimerDelete( xTimer );

*

}

*

else

*

{

*

// xTimer is not active, change its period to 500ms. This will also

*

// cause the timer to start. Block for a maximum of 100 ticks if the

*

// change period command cannot immediately be sent to the timer

*

// command queue.

*

if( xTimerChangePeriod( xTimer, 500 / portTICK_PERIOD_MS, 100 ) ==

pdPASS )

*

{

*

// The command was successfully sent.

*

}

*

else

*

{

*

// The command could not be sent, even after waiting for 100

ticks

*

// to pass. Take appropriate action here.

*

}

*

}

*}

*

Return pdFAIL will be returned if the change period command could not be sent to the timer command queue even after xTicksToWait ticks had passed. pdPASS will be returned if the command was successfully sent to the timer command queue. When the command is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in the system. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.
Parameters · xTimer: The handle of the timer that is having its period changed. · xNewPeriod: The new period for xTimer. Timer periods are specified in tick periods, so the constant portTICK_PERIOD_MS can be used to convert a time that has been specified in milliseconds. For example, if the timer must expire after 100 ticks, then xNewPeriod should be set to 100. Alternatively, if the timer must expire after 500ms, then xNewPeriod can be set to ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or equal to 1000. · xTicksToWait: Specifies the time, in ticks, that the calling task should be held in the Blocked state to wait for the change period command to be successfully sent to the timer command queue, should the queue already be full when xTimerChangePeriod() was called. xTicksToWait is ignored if xTimerChangePeriod() is called before the scheduler is started.
xTimerDelete(xTimer, xTicksToWait) BaseType_t xTimerDelete( TimerHandle_t xTimer, TickType_t xTicksToWait );
Timer functionality is provided by a timer service/daemon task. Many of the public FreeRTOS timer API functions send commands to the timer service task through a queue called the timer command queue. The timer command queue is private to the kernel itself and is not directly accessible to application code. The length of the timer command queue is set by the configTIMER_QUEUE_LENGTH configuration constant.
xTimerDelete() deletes a timer that was previously created using the xTimerCreate() API function.
The configUSE_TIMERS configuration constant must be set to 1 for xTimerDelete() to be available.

Espressif Systems

1219

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Example usage:
Return pdFAIL will be returned if the delete command could not be sent to the timer command queue even after xTicksToWait ticks had passed. pdPASS will be returned if the command was successfully sent to the timer command queue. When the command is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in the system. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.
Parameters · xTimer: The handle of the timer being deleted. · xTicksToWait: Specifies the time, in ticks, that the calling task should be held in the Blocked state to wait for the delete command to be successfully sent to the timer command queue, should the queue already be full when xTimerDelete() was called. xTicksToWait is ignored if xTimerDelete() is called before the scheduler is started.
See the xTimerChangePeriod() API function example usage scenario.
xTimerReset(xTimer, xTicksToWait) BaseType_t xTimerReset( TimerHandle_t xTimer, TickType_t xTicksToWait );
Timer functionality is provided by a timer service/daemon task. Many of the public FreeRTOS timer API functions send commands to the timer service task through a queue called the timer command queue. The timer command queue is private to the kernel itself and is not directly accessible to application code. The length of the timer command queue is set by the configTIMER_QUEUE_LENGTH configuration constant.
xTimerReset() re-starts a timer that was previously created using the xTimerCreate() API function. If the timer had already been started and was already in the active state, then xTimerReset() will cause the timer to re-evaluate its expiry time so that it is relative to when xTimerReset() was called. If the timer was in the dormant state then xTimerReset() has equivalent functionality to the xTimerStart() API function.
Resetting a timer ensures the timer is in the active state. If the timer is not stopped, deleted, or reset in the mean time, the callback function associated with the timer will get called mnnticks after xTimerReset() was called, where mnnis the timers defined period.
It is valid to call xTimerReset() before the scheduler has been started, but when this is done the timer will not actually start until the scheduler is started, and the timers expiry time will be relative to when the scheduler is started, not relative to when xTimerReset() was called.
The configUSE_TIMERS configuration constant must be set to 1 for xTimerReset() to be available.
Example usage:

* // When a key is pressed, an LCD back-light is switched on. If 5 seconds

pass

* // without a key being pressed, then the LCD back-light is switched off. In

* // this case, the timer is a one-shot timer.

*

* TimerHandle_t xBacklightTimer = NULL;

*

* // The callback function assigned to the one-shot timer. In this case the

* // parameter is not used.

* void vBacklightTimerCallback( TimerHandle_t pxTimer )

*{

*

// The timer expired, therefore 5 seconds must have passed since a key

*

// was pressed. Switch off the LCD back-light.

*

vSetBacklightState( BACKLIGHT_OFF );

*}

*

* // The key press event handler.

* void vKeyPressEventHandler( char cKey )

*{

*

// Ensure the LCD back-light is on, then reset the timer that is

*

// responsible for turning the back-light off after 5 seconds of

*

// key inactivity. Wait 10 ticks for the command to be successfully sent

*

// if it cannot be sent immediately.

(continues on next page)

Espressif Systems

1220

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)

*

vSetBacklightState( BACKLIGHT_ON );

*

if( xTimerReset( xBacklightTimer, 100 ) != pdPASS )

*

{

*

// The reset command was not executed successfully. Take appropriate

*

// action here.

*

}

*

*

// Perform the rest of the key processing here.

*}

*

* void main( void )

*{

* int32_t x;

*

*

// Create then start the one-shot timer that is responsible for turning

*

// the back-light off if no keys are pressed within a 5 second period.

*

xBacklightTimer = xTimerCreate( "BacklightTimer",

// Just a

text name, not used by the kernel.

*

( 5000 / portTICK_PERIOD_MS), // The

timer period in ticks.

*

pdFALSE,

// The timer

is a one-shot timer.

*

0,

// The id is

not used by the callback so can take any value.

*

vBacklightTimerCallback

// The

callback function that switches the LCD back-light off.

*

);

*

*

if( xBacklightTimer == NULL )

*

{

*

// The timer was not created.

*

}

*

else

*

{

*

// Start the timer. No block time is specified, and even if one was

*

// it would be ignored because the scheduler has not yet been

*

// started.

*

if( xTimerStart( xBacklightTimer, 0 ) != pdPASS )

*

{

*

// The timer could not be set into the Active state.

*

}

*

}

*

*

// ...

*

// Create tasks here.

*

// ...

*

*

// Starting the scheduler will start the timer running as it has already

*

// been set into the active state.

*

vTaskStartScheduler();

*

*

// Should not reach here.

*

for( ;; );

*}

*

Return pdFAIL will be returned if the reset command could not be sent to the timer command queue even after xTicksToWait ticks had passed. pdPASS will be returned if the command was successfully sent to the timer command queue. When the command is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in the system, although the timers expiry time is relative to when xTimerStart() is actually called. The timer service/daemon task priority is set by the

Espressif Systems

1221

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

configTIMER_TASK_PRIORITY configuration constant. Parameters
· xTimer: The handle of the timer being reset/started/restarted. · xTicksToWait: Specifies the time, in ticks, that the calling task should be held in the Blocked
state to wait for the reset command to be successfully sent to the timer command queue, should the queue already be full when xTimerReset() was called. xTicksToWait is ignored if xTimerReset() is called before the scheduler is started.
xTimerStartFromISR(xTimer, pxHigherPriorityTaskWoken) BaseType_t xTimerStartFromISR( TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken );
A version of xTimerStart() that can be called from an interrupt service routine.
Example usage:

* // This scenario assumes xBacklightTimer has already been created. When a

* // key is pressed, an LCD back-light is switched on. If 5 seconds pass

* // without a key being pressed, then the LCD back-light is switched off. In

* // this case, the timer is a one-shot timer, and unlike the example given for

* // the xTimerReset() function, the key press event handler is an interrupt

* // service routine.

*

* // The callback function assigned to the one-shot timer. In this case the

* // parameter is not used.

* void vBacklightTimerCallback( TimerHandle_t pxTimer )

*{

*

// The timer expired, therefore 5 seconds must have passed since a key

*

// was pressed. Switch off the LCD back-light.

*

vSetBacklightState( BACKLIGHT_OFF );

*}

*

* // The key press interrupt service routine.

* void vKeyPressEventInterruptHandler( void )

*{

* BaseType_t xHigherPriorityTaskWoken = pdFALSE;

*

*

// Ensure the LCD back-light is on, then restart the timer that is

*

// responsible for turning the back-light off after 5 seconds of

*

// key inactivity. This is an interrupt service routine so can only

*

// call FreeRTOS API functions that end in "FromISR".

*

vSetBacklightState( BACKLIGHT_ON );

*

*

// xTimerStartFromISR() or xTimerResetFromISR() could be called here

*

// as both cause the timer to re-calculate its expiry time.

*

// xHigherPriorityTaskWoken was initialised to pdFALSE when it was

*

// declared (in this function).

*

if( xTimerStartFromISR( xBacklightTimer, &xHigherPriorityTaskWoken ) !=

pdPASS )

*

{

*

// The start command was not executed successfully. Take appropriate

*

// action here.

*

}

*

*

// Perform the rest of the key processing here.

*

*

// If xHigherPriorityTaskWoken equals pdTRUE, then a context switch

*

// should be performed. The syntax required to perform a context switch

*

// from inside an ISR varies from port to port, and from compiler to

*

// compiler. Inspect the demos for the port you are using to find the

*

// actual syntax required.

*

if( xHigherPriorityTaskWoken != pdFALSE )

*

{

*

// Call the interrupt safe yield function here (actual function

(continues on next page)

Espressif Systems

1222

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

*

// depends on the FreeRTOS port being used).

*

}

*}

*

(continued from previous page)

Return pdFAIL will be returned if the start command could not be sent to the timer command queue. pdPASS will be returned if the command was successfully sent to the timer command queue. When the command is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in the system, although the timers expiry time is relative to when xTimerStartFromISR() is actually called. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.
Parameters · xTimer: The handle of the timer being started/restarted. · pxHigherPriorityTaskWoken: The timer service/daemon task spends most of its time in the Blocked state, waiting for messages to arrive on the timer command queue. Calling xTimerStartFromISR() writes a message to the timer command queue, so has the potential to transition the timer service/daemon task out of the Blocked state. If calling xTimerStartFromISR() causes the timer service/daemon task to leave the Blocked state, and the timer service/ daemon task has a priority equal to or greater than the currently executing task (the task that was interrupted), then *pxHigherPriorityTaskWoken will get set to pdTRUE internally within the xTimerStartFromISR() function. If xTimerStartFromISR() sets this value to pdTRUE then a context switch should be performed before the interrupt exits.
xTimerStopFromISR(xTimer, pxHigherPriorityTaskWoken) BaseType_t xTimerStopFromISR( TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken );
A version of xTimerStop() that can be called from an interrupt service routine.
Example usage:

* // This scenario assumes xTimer has already been created and started. When

* // an interrupt occurs, the timer should be simply stopped.

*

* // The interrupt service routine that stops the timer.

* void vAnExampleInterruptServiceRoutine( void )

*{

* BaseType_t xHigherPriorityTaskWoken = pdFALSE;

*

*

// The interrupt has occurred - simply stop the timer.

*

// xHigherPriorityTaskWoken was set to pdFALSE where it was defined

*

// (within this function). As this is an interrupt service routine, only

*

// FreeRTOS API functions that end in "FromISR" can be used.

*

if( xTimerStopFromISR( xTimer, &xHigherPriorityTaskWoken ) != pdPASS )

*

{

*

// The stop command was not executed successfully. Take appropriate

*

// action here.

*

}

*

*

// If xHigherPriorityTaskWoken equals pdTRUE, then a context switch

*

// should be performed. The syntax required to perform a context switch

*

// from inside an ISR varies from port to port, and from compiler to

*

// compiler. Inspect the demos for the port you are using to find the

*

// actual syntax required.

*

if( xHigherPriorityTaskWoken != pdFALSE )

*

{

*

// Call the interrupt safe yield function here (actual function

*

// depends on the FreeRTOS port being used).

*

}

*}

*

Espressif Systems

1223

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return pdFAIL will be returned if the stop command could not be sent to the timer command queue. pdPASS will be returned if the command was successfully sent to the timer command queue. When the command is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in the system. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.
Parameters · xTimer: The handle of the timer being stopped. · pxHigherPriorityTaskWoken: The timer service/daemon task spends most of its time in the Blocked state, waiting for messages to arrive on the timer command queue. Calling xTimerStopFromISR() writes a message to the timer command queue, so has the potential to transition the timer service/daemon task out of the Blocked state. If calling xTimerStopFromISR() causes the timer service/daemon task to leave the Blocked state, and the timer service/ daemon task has a priority equal to or greater than the currently executing task (the task that was interrupted), then *pxHigherPriorityTaskWoken will get set to pdTRUE internally within the xTimerStopFromISR() function. If xTimerStopFromISR() sets this value to pdTRUE then a context switch should be performed before the interrupt exits.
xTimerChangePeriodFromISR(xTimer, xNewPeriod, pxHigherPriorityTaskWoken) BaseType_t xTimerChangePeriodFromISR( TimerHandle_t xTimer, TickType_t xNewPeriod, BaseType_t *pxHigherPriorityTaskWoken );
A version of xTimerChangePeriod() that can be called from an interrupt service routine.
Example usage:

* // This scenario assumes xTimer has already been created and started. When

* // an interrupt occurs, the period of xTimer should be changed to 500ms.

*

* // The interrupt service routine that changes the period of xTimer.

* void vAnExampleInterruptServiceRoutine( void )

*{

* BaseType_t xHigherPriorityTaskWoken = pdFALSE;

*

*

// The interrupt has occurred - change the period of xTimer to 500ms.

*

// xHigherPriorityTaskWoken was set to pdFALSE where it was defined

*

// (within this function). As this is an interrupt service routine, only

*

// FreeRTOS API functions that end in "FromISR" can be used.

*

if( xTimerChangePeriodFromISR( xTimer, &xHigherPriorityTaskWoken ) !=

pdPASS )

*

{

*

// The command to change the timers period was not executed

*

// successfully. Take appropriate action here.

*

}

*

*

// If xHigherPriorityTaskWoken equals pdTRUE, then a context switch

*

// should be performed. The syntax required to perform a context switch

*

// from inside an ISR varies from port to port, and from compiler to

*

// compiler. Inspect the demos for the port you are using to find the

*

// actual syntax required.

*

if( xHigherPriorityTaskWoken != pdFALSE )

*

{

*

// Call the interrupt safe yield function here (actual function

*

// depends on the FreeRTOS port being used).

*

}

*}

*

Return pdFAIL will be returned if the command to change the timers period could not be sent to the timer command queue. pdPASS will be returned if the command was successfully sent to the timer command queue. When the command is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in the system. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.

Espressif Systems

1224

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Parameters · xTimer: The handle of the timer that is having its period changed. · xNewPeriod: The new period for xTimer. Timer periods are specified in tick periods, so the constant portTICK_PERIOD_MS can be used to convert a time that has been specified in milliseconds. For example, if the timer must expire after 100 ticks, then xNewPeriod should be set to 100. Alternatively, if the timer must expire after 500ms, then xNewPeriod can be set to ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or equal to 1000. · pxHigherPriorityTaskWoken: The timer service/daemon task spends most of its time in the Blocked state, waiting for messages to arrive on the timer command queue. Calling xTimerChangePeriodFromISR() writes a message to the timer command queue, so has the potential to transition the timer service/ daemon task out of the Blocked state. If calling xTimerChangePeriodFromISR() causes the timer service/daemon task to leave the Blocked state, and the timer service/daemon task has a priority equal to or greater than the currently executing task (the task that was interrupted), then *pxHigherPriorityTaskWoken will get set to pdTRUE internally within the xTimerChangePeriodFromISR() function. If xTimerChangePeriodFromISR() sets this value to pdTRUE then a context switch should be performed before the interrupt exits.
xTimerResetFromISR(xTimer, pxHigherPriorityTaskWoken) BaseType_t xTimerResetFromISR( TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken );
A version of xTimerReset() that can be called from an interrupt service routine.
Example usage:

* // This scenario assumes xBacklightTimer has already been created. When a

* // key is pressed, an LCD back-light is switched on. If 5 seconds pass

* // without a key being pressed, then the LCD back-light is switched off. In

* // this case, the timer is a one-shot timer, and unlike the example given for

* // the xTimerReset() function, the key press event handler is an interrupt

* // service routine.

*

* // The callback function assigned to the one-shot timer. In this case the

* // parameter is not used.

* void vBacklightTimerCallback( TimerHandle_t pxTimer )

*{

*

// The timer expired, therefore 5 seconds must have passed since a key

*

// was pressed. Switch off the LCD back-light.

*

vSetBacklightState( BACKLIGHT_OFF );

*}

*

* // The key press interrupt service routine.

* void vKeyPressEventInterruptHandler( void )

*{

* BaseType_t xHigherPriorityTaskWoken = pdFALSE;

*

*

// Ensure the LCD back-light is on, then reset the timer that is

*

// responsible for turning the back-light off after 5 seconds of

*

// key inactivity. This is an interrupt service routine so can only

*

// call FreeRTOS API functions that end in "FromISR".

*

vSetBacklightState( BACKLIGHT_ON );

*

*

// xTimerStartFromISR() or xTimerResetFromISR() could be called here

*

// as both cause the timer to re-calculate its expiry time.

*

// xHigherPriorityTaskWoken was initialised to pdFALSE when it was

*

// declared (in this function).

*

if( xTimerResetFromISR( xBacklightTimer, &xHigherPriorityTaskWoken ) !=

pdPASS )

*

{

*

// The reset command was not executed successfully. Take appropriate

*

// action here.

*

}

*

(continues on next page)

Espressif Systems

1225

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)

*

// Perform the rest of the key processing here.

*

*

// If xHigherPriorityTaskWoken equals pdTRUE, then a context switch

*

// should be performed. The syntax required to perform a context switch

*

// from inside an ISR varies from port to port, and from compiler to

*

// compiler. Inspect the demos for the port you are using to find the

*

// actual syntax required.

*

if( xHigherPriorityTaskWoken != pdFALSE )

*

{

*

// Call the interrupt safe yield function here (actual function

*

// depends on the FreeRTOS port being used).

*

}

*}

*

Return pdFAIL will be returned if the reset command could not be sent to the timer command queue. pdPASS will be returned if the command was successfully sent to the timer command queue. When the command is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in the system, although the timers expiry time is relative to when xTimerResetFromISR() is actually called. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.
Parameters · xTimer: The handle of the timer that is to be started, reset, or restarted. · pxHigherPriorityTaskWoken: The timer service/daemon task spends most of its time in the Blocked state, waiting for messages to arrive on the timer command queue. Calling xTimerResetFromISR() writes a message to the timer command queue, so has the potential to transition the timer service/daemon task out of the Blocked state. If calling xTimerResetFromISR() causes the timer service/daemon task to leave the Blocked state, and the timer service/ daemon task has a priority equal to or greater than the currently executing task (the task that was interrupted), then *pxHigherPriorityTaskWoken will get set to pdTRUE internally within the xTimerResetFromISR() function. If xTimerResetFromISR() sets this value to pdTRUE then a context switch should be performed before the interrupt exits.

Type Definitions typedef struct tmrTimerControl *TimerHandle_t typedef void (*TimerCallbackFunction_t)(TimerHandle_t xTimer)
typedef void (*PendedFunction_t)(void *, uint32_t)

Event Group API
Header File · components/freertos/FreeRTOS-Kernel/include/freertos/event_groups.h

Functions EventGroupHandle_t xEventGroupCreate(void)
Create a new event group.
Internally, within the FreeRTOS implementation, event groups use a [small] block of memory, in which the event groupns structure is stored. If an event groups is created using xEventGroupCreate() then the required memory is automatically dynamically allocated inside the xEventGroupCreate() function. (see https://www.FreeRTOS.org/a00111.html). If an event group is created using xEventGroupCreateStatic() then the application writer must instead provide the memory that will get used by the event group. xEventGroupCreateStatic() therefore allows an event group to be created without using any dynamic memory allocation.
Although event groups are not related to ticks, for internal implementation reasons the number of bits available for use in an event group is dependent on the configUSE_16_BIT_TICKS setting in FreeRTOSConfig.h.

Espressif Systems

1226

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

If configUSE_16_BIT_TICKS is 1 then each event group contains 8 usable bits (bit 0 to bit 7). If configUSE_16_BIT_TICKS is set to 0 then each event group has 24 usable bits (bit 0 to bit 23). The EventBits_t type is used to store event bits within an event group.
Example usage:
// Declare a variable to hold the created event group. EventGroupHandle_t xCreatedEventGroup;
// Attempt to create the event group. xCreatedEventGroup = xEventGroupCreate();
// Was the event group created successfully? if( xCreatedEventGroup == NULL ) {
// The event group was not created because there was insufficient // FreeRTOS heap available. } else { // The event group was created. }
Return If the event group was created then a handle to the event group is returned. If there was insufficient FreeRTOS heap available to create the event group then NULL is returned. See https://www.FreeRTOS. org/a00111.html
EventGroupHandle_t xEventGroupCreateStatic(StaticEventGroup_t *pxEventGroupBuffer) Create a new event group.
Internally, within the FreeRTOS implementation, event groups use a [small] block of memory, in which the event groupns structure is stored. If an event groups is created using xEventGroupCreate() then the required memory is automatically dynamically allocated inside the xEventGroupCreate() function. (see https://www.FreeRTOS.org/a00111.html). If an event group is created using xEventGroupCreateStatic() then the application writer must instead provide the memory that will get used by the event group. xEventGroupCreateStatic() therefore allows an event group to be created without using any dynamic memory allocation.
Although event groups are not related to ticks, for internal implementation reasons the number of bits available for use in an event group is dependent on the configUSE_16_BIT_TICKS setting in FreeRTOSConfig.h. If configUSE_16_BIT_TICKS is 1 then each event group contains 8 usable bits (bit 0 to bit 7). If configUSE_16_BIT_TICKS is set to 0 then each event group has 24 usable bits (bit 0 to bit 23). The EventBits_t type is used to store event bits within an event group.
Example usage:
// StaticEventGroup_t is a publicly accessible structure that has the same // size and alignment requirements as the real event group structure. It is // provided as a mechanism for applications to know the size of the event // group (which is dependent on the architecture and configuration file // settings) without breaking the strict data hiding policy by exposing the // real event group internals. This StaticEventGroup_t variable is passed // into the xSemaphoreCreateEventGroupStatic() function and is used to store // the event group's data structures StaticEventGroup_t xEventGroupBuffer;
// Create the event group without dynamically allocating any memory. xEventGroup = xEventGroupCreateStatic( &xEventGroupBuffer );
Return If the event group was created then a handle to the event group is returned. If pxEventGroupBuffer was NULL then NULL is returned.
Parameters · pxEventGroupBuffer: pxEventGroupBuffer must point to a variable of type StaticEventGroup_t, which will be then be used to hold the event groupns data structures, removing the need for the memory to be allocated dynamically.

Espressif Systems

1227

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

EventBits_t xEventGroupWaitBits(EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToWaitFor, const BaseType_t xClearOnExit, const BaseType_t xWaitForAllBits, TickType_t xTicksToWait)
[Potentially] block to wait for one or more bits to be set within a previously created event group.
This function cannot be called from an interrupt.
Example usage:

#define BIT_0 ( 1 << 0 ) #define BIT_4 ( 1 << 4 )

void aFunction( EventGroupHandle_t xEventGroup ) { EventBits_t uxBits; const TickType_t xTicksToWait = 100 / portTICK_PERIOD_MS;

// Wait a maximum of 100ms for either bit 0 or bit 4 to be set within

// the event group. Clear the bits before exiting.

uxBits = xEventGroupWaitBits(

xEventGroup, // The event group being tested.

BIT_0 | BIT_4, // The bits within the event group to wait

for.

pdTRUE,

// BIT_0 and BIT_4 should be cleared before

returning.

pdFALSE,

// Don't wait for both bits, either bit will

do.

xTicksToWait ); // Wait a maximum of 100ms for either bit to

be set.

if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) ) {
// xEventGroupWaitBits() returned because both bits were set. } else if( ( uxBits & BIT_0 ) != 0 ) {
// xEventGroupWaitBits() returned because just BIT_0 was set. } else if( ( uxBits & BIT_4 ) != 0 ) {
// xEventGroupWaitBits() returned because just BIT_4 was set. } else {
// xEventGroupWaitBits() returned because xTicksToWait ticks passed // without either BIT_0 or BIT_4 becoming set. } }

Return The value of the event group at the time either the bits being waited for became set, or the block time expired. Test the return value to know which bits were set. If xEventGroupWaitBits() returned because its timeout expired then not all the bits being waited for will be set. If xEventGroupWaitBits() returned because the bits it was waiting for were set then the returned value is the event group value before any bits were automatically cleared in the case that xClearOnExit parameter was set to pdTRUE.
Parameters · xEventGroup: The event group in which the bits are being tested. The event group must have previously been created using a call to xEventGroupCreate(). · uxBitsToWaitFor: A bitwise value that indicates the bit or bits to test inside the event group. For example, to wait for bit 0 and/or bit 2 set uxBitsToWaitFor to 0x05. To wait for bits 0 and/or bit 1 and/or bit 2 set uxBitsToWaitFor to 0x07. Etc. · xClearOnExit: If xClearOnExit is set to pdTRUE then any bits within uxBitsToWaitFor that are set within the event group will be cleared before xEventGroupWaitBits() returns if the wait condition was met (if the function returns for a reason other than a timeout). If xClearOnExit is set to

Espressif Systems

1228

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
pdFALSE then the bits set in the event group are not altered when the call to xEventGroupWaitBits() returns. · xWaitForAllBits: If xWaitForAllBits is set to pdTRUE then xEventGroupWaitBits() will return when either all the bits in uxBitsToWaitFor are set or the specified block time expires. If xWaitForAllBits is set to pdFALSE then xEventGroupWaitBits() will return when any one of the bits set in uxBitsToWaitFor is set or the specified block time expires. The block time is specified by the xTicksToWait parameter. · xTicksToWait: The maximum amount of time (specified in mticksn) to wait for one/all (depending on the xWaitForAllBits value) of the bits specified by uxBitsToWaitFor to become set.
EventBits_t xEventGroupClearBits(EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear)
Clear bits within an event group. This function cannot be called from an interrupt.
Example usage:
#define BIT_0 ( 1 << 0 ) #define BIT_4 ( 1 << 4 )
void aFunction( EventGroupHandle_t xEventGroup ) { EventBits_t uxBits;
// Clear bit 0 and bit 4 in xEventGroup. uxBits = xEventGroupClearBits(
xEventGroup, // The event group being updated. BIT_0 | BIT_4 );// The bits being cleared.
if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) ) {
// Both bit 0 and bit 4 were set before xEventGroupClearBits() was // called. Both will now be clear (not set). } else if( ( uxBits & BIT_0 ) != 0 ) { // Bit 0 was set before xEventGroupClearBits() was called. It will // now be clear. } else if( ( uxBits & BIT_4 ) != 0 ) { // Bit 4 was set before xEventGroupClearBits() was called. It will // now be clear. } else { // Neither bit 0 nor bit 4 were set in the first place. } }
Return The value of the event group before the specified bits were cleared. Parameters
· xEventGroup: The event group in which the bits are to be cleared. · uxBitsToClear: A bitwise value that indicates the bit or bits to clear in the event group. For
example, to clear bit 3 only, set uxBitsToClear to 0x08. To clear bit 3 and bit 0 set uxBitsToClear to 0x09.
EventBits_t xEventGroupSetBits(EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet) Set bits within an event group. This function cannot be called from an interrupt. xEventGroupSetBitsFromISR() is a version that can be called from an interrupt.
Setting bits in an event group will automatically unblock tasks that are blocked waiting for the bits.
Example usage:

Espressif Systems

1229

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

#define BIT_0 ( 1 << 0 ) #define BIT_4 ( 1 << 4 )
void aFunction( EventGroupHandle_t xEventGroup ) { EventBits_t uxBits;
// Set bit 0 and bit 4 in xEventGroup. uxBits = xEventGroupSetBits(
xEventGroup, // The event group being updated. BIT_0 | BIT_4 );// The bits being set.
if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) ) {
// Both bit 0 and bit 4 remained set when the function returned. } else if( ( uxBits & BIT_0 ) != 0 ) {
// Bit 0 remained set when the function returned, but bit 4 was // cleared. It might be that bit 4 was cleared automatically as a // task that was waiting for bit 4 was removed from the Blocked // state. } else if( ( uxBits & BIT_4 ) != 0 ) { // Bit 4 remained set when the function returned, but bit 0 was // cleared. It might be that bit 0 was cleared automatically as a // task that was waiting for bit 0 was removed from the Blocked // state. } else { // Neither bit 0 nor bit 4 remained set. It might be that a task // was waiting for both of the bits to be set, and the bits were // cleared as the task left the Blocked state. } }
Return The value of the event group at the time the call to xEventGroupSetBits() returns. There are two reasons why the returned value might have the bits specified by the uxBitsToSet parameter cleared. First, if setting a bit results in a task that was waiting for the bit leaving the blocked state then it is possible the bit will be cleared automatically (see the xClearBitOnExit parameter of xEventGroupWaitBits()). Second, any unblocked (or otherwise Ready state) task that has a priority above that of the task that called xEventGroupSetBits() will execute and may change the event group value before the call to xEventGroupSetBits() returns.
Parameters · xEventGroup: The event group in which the bits are to be set. · uxBitsToSet: A bitwise value that indicates the bit or bits to set. For example, to set bit 3 only, set uxBitsToSet to 0x08. To set bit 3 and bit 0 set uxBitsToSet to 0x09.
EventBits_t xEventGroupSync(EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, const EventBits_t uxBitsToWaitFor, TickType_t xTicksToWait)
Atomically set bits within an event group, then wait for a combination of bits to be set within the same event group. This functionality is typically used to synchronise multiple tasks, where each task has to wait for the other tasks to reach a synchronisation point before proceeding.
This function cannot be used from an interrupt.
The function will return before its block time expires if the bits specified by the uxBitsToWait parameter are set, or become set within that time. In this case all the bits specified by uxBitsToWait will be automatically cleared before the function returns.
Example usage:

Espressif Systems

1230

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

// Bits used by the three tasks.

#define TASK_0_BIT

( 1 << 0 )

#define TASK_1_BIT

( 1 << 1 )

#define TASK_2_BIT

( 1 << 2 )

#define ALL_SYNC_BITS ( TASK_0_BIT | TASK_1_BIT | TASK_2_BIT )

// Use an event group to synchronise three tasks. It is assumed this event // group has already been created elsewhere. EventGroupHandle_t xEventBits;

void vTask0( void *pvParameters ) { EventBits_t uxReturn; TickType_t xTicksToWait = 100 / portTICK_PERIOD_MS;

for( ;; ) {
// Perform task functionality here.

// Set bit 0 in the event flag to note this task has reached the // sync point. The other two tasks will set the other two bits defined // by ALL_SYNC_BITS. All three tasks have reached the synchronisation // point when all the ALL_SYNC_BITS are set. Wait a maximum of 100ms // for this to happen. uxReturn = xEventGroupSync( xEventBits, TASK_0_BIT, ALL_SYNC_BITS, xTicksToWait );

if( ( uxReturn & ALL_SYNC_BITS ) == ALL_SYNC_BITS ) {
// All three tasks reached the synchronisation point before the call // to xEventGroupSync() timed out. } } }

void vTask1( void *pvParameters ) {
for( ;; ) {
// Perform task functionality here.

// Set bit 1 in the event flag to note this task has reached the // synchronisation point. The other two tasks will set the other two // bits defined by ALL_SYNC_BITS. All three tasks have reached the // synchronisation point when all the ALL_SYNC_BITS are set. Wait // indefinitely for this to happen. xEventGroupSync( xEventBits, TASK_1_BIT, ALL_SYNC_BITS, portMAX_DELAY );

// xEventGroupSync() was called with an indefinite block time, so // this task will only reach here if the synchronisation was made by all // three tasks, so there is no need to test the return value. } }

void vTask2( void *pvParameters ) {
for( ;; ) {
// Perform task functionality here.

// Set bit 2 in the event flag to note this task has reached the (continues on next page)

Espressif Systems

1231

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)
// synchronisation point. The other two tasks will set the other two // bits defined by ALL_SYNC_BITS. All three tasks have reached the // synchronisation point when all the ALL_SYNC_BITS are set. Wait // indefinitely for this to happen. xEventGroupSync( xEventBits, TASK_2_BIT, ALL_SYNC_BITS, portMAX_DELAY );
// xEventGroupSync() was called with an indefinite block time, so // this task will only reach here if the synchronisation was made by all // three tasks, so there is no need to test the return value. } }
Return The value of the event group at the time either the bits being waited for became set, or the block time expired. Test the return value to know which bits were set. If xEventGroupSync() returned because its timeout expired then not all the bits being waited for will be set. If xEventGroupSync() returned because all the bits it was waiting for were set then the returned value is the event group value before any bits were automatically cleared.
Parameters · xEventGroup: The event group in which the bits are being tested. The event group must have previously been created using a call to xEventGroupCreate(). · uxBitsToSet: The bits to set in the event group before determining if, and possibly waiting for, all the bits specified by the uxBitsToWait parameter are set. · uxBitsToWaitFor: A bitwise value that indicates the bit or bits to test inside the event group. For example, to wait for bit 0 and bit 2 set uxBitsToWaitFor to 0x05. To wait for bits 0 and bit 1 and bit 2 set uxBitsToWaitFor to 0x07. Etc. · xTicksToWait: The maximum amount of time (specified in mticksn) to wait for all of the bits specified by uxBitsToWaitFor to become set.
EventBits_t xEventGroupGetBitsFromISR(EventGroupHandle_t xEventGroup) A version of xEventGroupGetBits() that can be called from an ISR.
Return The event group bits at the time xEventGroupGetBitsFromISR() was called. Parameters
· xEventGroup: The event group being queried.
void vEventGroupDelete(EventGroupHandle_t xEventGroup) Delete an event group that was previously created by a call to xEventGroupCreate(). Tasks that are blocked on the event group will be unblocked and obtain 0 as the event groupns value.
Parameters · xEventGroup: The event group being deleted.

Macros xEventGroupClearBitsFromISR(xEventGroup, uxBitsToClear)
A version of xEventGroupClearBits() that can be called from an interrupt.
Setting bits in an event group is not a deterministic operation because there are an unknown number of tasks that may be waiting for the bit or bits being set. FreeRTOS does not allow nondeterministic operations to be performed while interrupts are disabled, so protects event groups that are accessed from tasks by suspending the scheduler rather than disabling interrupts. As a result event groups cannot be accessed directly from an interrupt service routine. Therefore xEventGroupClearBitsFromISR() sends a message to the timer task to have the clear operation performed in the context of the timer task.
Example usage:
#define BIT_0 ( 1 << 0 ) #define BIT_4 ( 1 << 4 )
// An event group which it is assumed has already been created by a call to // xEventGroupCreate().
(continues on next page)

Espressif Systems

1232

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

EventGroupHandle_t xEventGroup;

(continued from previous page)

void anInterruptHandler( void )

{

// Clear bit 0 and bit 4 in xEventGroup.

xResult = xEventGroupClearBitsFromISR(

xEventGroup,

// The event group being updated.

BIT_0 | BIT_4 ); // The bits being set.

if( xResult == pdPASS ) {
// The message was posted successfully. } }

Return If the request to execute the function was posted successfully then pdPASS is returned, otherwise pdFALSE is returned. pdFALSE will be returned if the timer service queue was full.
Parameters · xEventGroup: The event group in which the bits are to be cleared. · uxBitsToClear: A bitwise value that indicates the bit or bits to clear. For example, to clear bit 3 only, set uxBitsToClear to 0x08. To clear bit 3 and bit 0 set uxBitsToClear to 0x09.
xEventGroupSetBitsFromISR(xEventGroup, uxBitsToSet, pxHigherPriorityTaskWoken) A version of xEventGroupSetBits() that can be called from an interrupt.
Setting bits in an event group is not a deterministic operation because there are an unknown number of tasks that may be waiting for the bit or bits being set. FreeRTOS does not allow nondeterministic operations to be performed in interrupts or from critical sections. Therefore xEventGroupSetBitsFromISR() sends a message to the timer task to have the set operation performed in the context of the timer task - where a scheduler lock is used in place of a critical section.
Example usage:
#define BIT_0 ( 1 << 0 ) #define BIT_4 ( 1 << 4 )
// An event group which it is assumed has already been created by a call to // xEventGroupCreate(). EventGroupHandle_t xEventGroup;
void anInterruptHandler( void ) { BaseType_t xHigherPriorityTaskWoken, xResult;
// xHigherPriorityTaskWoken must be initialised to pdFALSE. xHigherPriorityTaskWoken = pdFALSE;

// Set bit 0 and bit 4 in xEventGroup. xResult = xEventGroupSetBitsFromISR(
xEventGroup, // The event group being updated. BIT_0 | BIT_4 // The bits being set. &xHigherPriorityTaskWoken );

// Was the message posted successfully? if( xResult == pdPASS ) {
// If xHigherPriorityTaskWoken is now set to pdTRUE then a context // switch should be requested. The macro used is port specific and // will be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() // refer to the documentation page for the port being used. portYIELD_FROM_ISR( xHigherPriorityTaskWoken ); }
(continues on next page)

Espressif Systems

1233

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)
}
Return If the request to execute the function was posted successfully then pdPASS is returned, otherwise pdFALSE is returned. pdFALSE will be returned if the timer service queue was full.
Parameters · xEventGroup: The event group in which the bits are to be set. · uxBitsToSet: A bitwise value that indicates the bit or bits to set. For example, to set bit 3 only, set uxBitsToSet to 0x08. To set bit 3 and bit 0 set uxBitsToSet to 0x09. · pxHigherPriorityTaskWoken: As mentioned above, calling this function will result in a message being sent to the timer daemon task. If the priority of the timer daemon task is higher than the priority of the currently running task (the task the interrupt interrupted) then *pxHigherPriorityTaskWoken will be set to pdTRUE by xEventGroupSetBitsFromISR(), indicating that a context switch should be requested before the interrupt exits. For that reason *pxHigherPriorityTaskWoken must be initialised to pdFALSE. See the example code below.
xEventGroupGetBits(xEventGroup) Returns the current value of the bits in an event group. This function cannot be used from an interrupt.
Return The event group bits at the time xEventGroupGetBits() was called. Parameters
· xEventGroup: The event group being queried.

Type Definitions typedef struct EventGroupDef_t *EventGroupHandle_t typedef TickType_t EventBits_t

Stream Buffer API
Header File · components/freertos/FreeRTOS-Kernel/include/freertos/stream_buffer.h

Functions size_t xStreamBufferSend(StreamBufferHandle_t xStreamBuffer, const void *pvTxData, size_t
xDataLengthBytes, TickType_t xTicksToWait) Sends bytes to a stream buffer. The bytes are copied into the stream buffer.
: Uniquely among FreeRTOS objects, the stream buffer implementation (so also the message buffer implementation, as message buffers are built on top of stream buffers) assumes there is only one task or interrupt that will write to the buffer (the writer), and only one task or interrupt that will read from the buffer (the reader). It is safe for the writer and reader to be different tasks or interrupts, but, unlike other FreeRTOS objects, it is not safe to have multiple different writers or multiple different readers. If there are to be multiple different writers then the application writer must place each call to a writing API function (such as xStreamBufferSend()) inside a critical section and set the send block time to 0. Likewise, if there are to be multiple different readers then the application writer must place each call to a reading API function (such as xStreamBufferReceive()) inside a critical section and set the receive block time to 0.
Use xStreamBufferSend() to write to a stream buffer from a task. Use xStreamBufferSendFromISR() to write to a stream buffer from an interrupt service routine (ISR).
Example use:

void vAFunction( StreamBufferHandle_t xStreamBuffer ) { size_t xBytesSent; uint8_t ucArrayToSend[] = { 0, 1, 2, 3 }; char *pcStringToSend = "String to send"; const TickType_t x100ms = pdMS_TO_TICKS( 100 );

(continues on next page)

Espressif Systems

1234

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)
// Send an array to the stream buffer, blocking for a maximum of 100ms to // wait for enough space to be available in the stream buffer. xBytesSent = xStreamBufferSend( xStreamBuffer, ( void * ) ucArrayToSend, sizeof( ucArrayToSend ), x100ms );
if( xBytesSent != sizeof( ucArrayToSend ) ) {
// The call to xStreamBufferSend() times out before there was enough // space in the buffer for the data to be written, but it did // successfully write xBytesSent bytes. }
// Send the string to the stream buffer. Return immediately if there is not // enough space in the buffer. xBytesSent = xStreamBufferSend( xStreamBuffer, ( void * ) pcStringToSend, strlen( pcStringToSend ), 0 );
if( xBytesSent != strlen( pcStringToSend ) ) {
// The entire string could not be added to the stream buffer because // there was not enough free space in the buffer, but xBytesSent bytes // were sent. Could try again to send the remaining bytes. } }
Return The number of bytes written to the stream buffer. If a task times out before it can write all xDataLengthBytes into the buffer it will still write as many bytes as possible.
Parameters · xStreamBuffer: The handle of the stream buffer to which a stream is being sent. · pvTxData: A pointer to the buffer that holds the bytes to be copied into the stream buffer. · xDataLengthBytes: The maximum number of bytes to copy from pvTxData into the stream buffer. · xTicksToWait: The maximum amount of time the task should remain in the Blocked state to wait for enough space to become available in the stream buffer, should the stream buffer contain too little space to hold the another xDataLengthBytes bytes. The block time is specified in tick periods, so the absolute time it represents is dependent on the tick frequency. The macro pdMS_TO_TICKS() can be used to convert a time specified in milliseconds into a time specified in ticks. Setting xTicksToWait to portMAX_DELAY will cause the task to wait indefinitely (without timing out), provided INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. If a task times out before it can write all xDataLengthBytes into the buffer it will still write as many bytes as possible. A task does not use any CPU time when it is in the blocked state.
size_t xStreamBufferSendFromISR(StreamBufferHandle_t xStreamBuffer, const void *pvTxData, size_t xDataLengthBytes, BaseType_t *const pxHigherPriorityTaskWoken)
Interrupt safe version of the API function that sends a stream of bytes to the stream buffer.
: Uniquely among FreeRTOS objects, the stream buffer implementation (so also the message buffer implementation, as message buffers are built on top of stream buffers) assumes there is only one task or interrupt that will write to the buffer (the writer), and only one task or interrupt that will read from the buffer (the reader). It is safe for the writer and reader to be different tasks or interrupts, but, unlike other FreeRTOS objects, it is not safe to have multiple different writers or multiple different readers. If there are to be multiple different writers then the application writer must place each call to a writing API function (such as xStreamBufferSend()) inside a critical section and set the send block time to 0. Likewise, if there are to be multiple different readers then the application writer must place each call to a reading API function (such as xStreamBufferReceive()) inside a critical section and set the receive block time to 0.
Use xStreamBufferSend() to write to a stream buffer from a task. Use xStreamBufferSendFromISR() to write to a stream buffer from an interrupt service routine (ISR).
Example use:

Espressif Systems

1235

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

// A stream buffer that has already been created. StreamBufferHandle_t xStreamBuffer;
void vAnInterruptServiceRoutine( void ) { size_t xBytesSent; char *pcStringToSend = "String to send"; BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE.
// Attempt to send the string to the stream buffer. xBytesSent = xStreamBufferSendFromISR( xStreamBuffer,
( void * ) pcStringToSend, strlen( pcStringToSend ), &xHigherPriorityTaskWoken );
if( xBytesSent != strlen( pcStringToSend ) ) {
// There was not enough free space in the stream buffer for the entire // string to be written, ut xBytesSent bytes were written. }
// If xHigherPriorityTaskWoken was set to pdTRUE inside // xStreamBufferSendFromISR() then a task that has a priority above the // priority of the currently executing task was unblocked and a context // switch should be performed to ensure the ISR returns to the unblocked // task. In most FreeRTOS ports this is done by simply passing // xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the // variables value, and perform the context switch if necessary. Check the // documentation for the port in use for port specific instructions. taskYIELD_FROM_ISR( xHigherPriorityTaskWoken ); }
Return The number of bytes actually written to the stream buffer, which will be less than xDataLengthBytes if the stream buffer didnnt have enough free space for all the bytes to be written.
Parameters · xStreamBuffer: The handle of the stream buffer to which a stream is being sent. · pvTxData: A pointer to the data that is to be copied into the stream buffer. · xDataLengthBytes: The maximum number of bytes to copy from pvTxData into the stream buffer. · pxHigherPriorityTaskWoken: It is possible that a stream buffer will have a task blocked on it waiting for data. Calling xStreamBufferSendFromISR() can make data available, and so cause a task that was waiting for data to leave the Blocked state. If calling xStreamBufferSendFromISR() causes a task to leave the Blocked state, and the unblocked task has a priority higher than the currently executing task (the task that was interrupted), then, internally, xStreamBufferSendFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE. If xStreamBufferSendFromISR() sets this value to pdTRUE, then normally a context switch should be performed before the interrupt is exited. This will ensure that the interrupt returns directly to the highest priority Ready state task. *pxHigherPriorityTaskWoken should be set to pdFALSE before it is passed into the function. See the example code below for an example.
size_t xStreamBufferReceive(StreamBufferHandle_t xStreamBuffer, void *pvRxData, size_t xBufferLengthBytes, TickType_t xTicksToWait)
Receives bytes from a stream buffer.
: Uniquely among FreeRTOS objects, the stream buffer implementation (so also the message buffer implementation, as message buffers are built on top of stream buffers) assumes there is only one task or interrupt that will write to the buffer (the writer), and only one task or interrupt that will read from the buffer (the reader). It is safe for the writer and reader to be different tasks or interrupts, but, unlike other FreeRTOS objects, it is not safe to have multiple different writers or multiple different readers. If there are to be multiple different writers then the application writer must place each call to a writing API function (such as xStreamBufferSend()) inside a critical section and set the send block time to 0. Likewise, if there are to be multiple different readers then

Espressif Systems

1236

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

the application writer must place each call to a reading API function (such as xStreamBufferReceive()) inside a critical section and set the receive block time to 0.
Use xStreamBufferReceive() to read from a stream buffer from a task. Use xStreamBufferReceiveFromISR() to read from a stream buffer from an interrupt service routine (ISR).
Example use:
void vAFunction( StreamBuffer_t xStreamBuffer ) { uint8_t ucRxData[ 20 ]; size_t xReceivedBytes; const TickType_t xBlockTime = pdMS_TO_TICKS( 20 );
// Receive up to another sizeof( ucRxData ) bytes from the stream buffer. // Wait in the Blocked state (so not using any CPU processing time) for a // maximum of 100ms for the full sizeof( ucRxData ) number of bytes to be // available. xReceivedBytes = xStreamBufferReceive( xStreamBuffer,
( void * ) ucRxData, sizeof( ucRxData ), xBlockTime );
if( xReceivedBytes > 0 ) {
// A ucRxData contains another xRecievedBytes bytes of data, which can // be processed here.... } }

Return The number of bytes actually read from the stream buffer, which will be less than xBufferLengthBytes if the call to xStreamBufferReceive() timed out before xBufferLengthBytes were available.
Parameters · xStreamBuffer: The handle of the stream buffer from which bytes are to be received. · pvRxData: A pointer to the buffer into which the received bytes will be copied. · xBufferLengthBytes: The length of the buffer pointed to by the pvRxData parameter. This sets the maximum number of bytes to receive in one call. xStreamBufferReceive will return as many bytes as possible up to a maximum set by xBufferLengthBytes. · xTicksToWait: The maximum amount of time the task should remain in the Blocked state to wait for data to become available if the stream buffer is empty. xStreamBufferReceive() will return immediately if xTicksToWait is zero. The block time is specified in tick periods, so the absolute time it represents is dependent on the tick frequency. The macro pdMS_TO_TICKS() can be used to convert a time specified in milliseconds into a time specified in ticks. Setting xTicksToWait to portMAX_DELAY will cause the task to wait indefinitely (without timing out), provided INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. A task does not use any CPU time when it is in the Blocked state.
size_t xStreamBufferReceiveFromISR(StreamBufferHandle_t xStreamBuffer, void *pvRxData, size_t xBufferLengthBytes, BaseType_t *const pxHigherPriorityTaskWoken)
An interrupt safe version of the API function that receives bytes from a stream buffer.
Use xStreamBufferReceive() to read bytes from a stream buffer from a task. Use xStreamBufferReceiveFromISR() to read bytes from a stream buffer from an interrupt service routine (ISR).
Example use:
// A stream buffer that has already been created. StreamBuffer_t xStreamBuffer;

void vAnInterruptServiceRoutine( void ) { uint8_t ucRxData[ 20 ];

(continues on next page)

Espressif Systems

1237

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

size_t xReceivedBytes; BaseType_t xHigherPriorityTaskWoken = pdFALSE;

(continued from previous page) // Initialised to pdFALSE.

// Receive the next stream from the stream buffer. xReceivedBytes = xStreamBufferReceiveFromISR( xStreamBuffer,
( void * ) ucRxData, sizeof( ucRxData ), &xHigherPriorityTaskWoken );

if( xReceivedBytes > 0 ) {
// ucRxData contains xReceivedBytes read from the stream buffer. // Process the stream here.... }

// If xHigherPriorityTaskWoken was set to pdTRUE inside // xStreamBufferReceiveFromISR() then a task that has a priority above the // priority of the currently executing task was unblocked and a context // switch should be performed to ensure the ISR returns to the unblocked // task. In most FreeRTOS ports this is done by simply passing // xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the // variables value, and perform the context switch if necessary. Check the // documentation for the port in use for port specific instructions. taskYIELD_FROM_ISR( xHigherPriorityTaskWoken ); }

Return The number of bytes read from the stream buffer, if any. Parameters
· xStreamBuffer: The handle of the stream buffer from which a stream is being received. · pvRxData: A pointer to the buffer into which the received bytes are copied. · xBufferLengthBytes: The length of the buffer pointed to by the pvRxData parameter. This
sets the maximum number of bytes to receive in one call. xStreamBufferReceive will return as many bytes as possible up to a maximum set by xBufferLengthBytes. · pxHigherPriorityTaskWoken: It is possible that a stream buffer will have a task blocked on it waiting for space to become available. Calling xStreamBufferReceiveFromISR() can make space available, and so cause a task that is waiting for space to leave the Blocked state. If calling xStreamBufferReceiveFromISR() causes a task to leave the Blocked state, and the unblocked task has a priority higher than the currently executing task (the task that was interrupted), then, internally, xStreamBufferReceiveFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE. If xStreamBufferReceiveFromISR() sets this value to pdTRUE, then normally a context switch should be performed before the interrupt is exited. That will ensure the interrupt returns directly to the highest priority Ready state task. *pxHigherPriorityTaskWoken should be set to pdFALSE before it is passed into the function. See the code example below for an example.
void vStreamBufferDelete(StreamBufferHandle_t xStreamBuffer) Deletes a stream buffer that was previously created using a call to xStreamBufferCreate() or xStreamBufferCreateStatic(). If the stream buffer was created using dynamic memory (that is, by xStreamBufferCreate()), then the allocated memory is freed.
A stream buffer handle must not be used after the stream buffer has been deleted.
Parameters · xStreamBuffer: The handle of the stream buffer to be deleted.
BaseType_t xStreamBufferIsFull(StreamBufferHandle_t xStreamBuffer) Queries a stream buffer to see if it is full. A stream buffer is full if it does not have any free space, and therefore cannot accept any more data.
Return If the stream buffer is full then pdTRUE is returned. Otherwise pdFALSE is returned. Parameters
· xStreamBuffer: The handle of the stream buffer being queried.

Espressif Systems

1238

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

BaseType_t xStreamBufferIsEmpty(StreamBufferHandle_t xStreamBuffer) Queries a stream buffer to see if it is empty. A stream buffer is empty if it does not contain any data.
Return If the stream buffer is empty then pdTRUE is returned. Otherwise pdFALSE is returned. Parameters
· xStreamBuffer: The handle of the stream buffer being queried.
BaseType_t xStreamBufferReset(StreamBufferHandle_t xStreamBuffer) Resets a stream buffer to its initial, empty, state. Any data that was in the stream buffer is discarded. A stream buffer can only be reset if there are no tasks blocked waiting to either send to or receive from the stream buffer.
Return If the stream buffer is reset then pdPASS is returned. If there was a task blocked waiting to send to or read from the stream buffer then the stream buffer is not reset and pdFAIL is returned.
Parameters · xStreamBuffer: The handle of the stream buffer being reset.
size_t xStreamBufferSpacesAvailable(StreamBufferHandle_t xStreamBuffer) Queries a stream buffer to see how much free space it contains, which is equal to the amount of data that can be sent to the stream buffer before it is full.
Return The number of bytes that can be written to the stream buffer before the stream buffer would be full. Parameters
· xStreamBuffer: The handle of the stream buffer being queried.
size_t xStreamBufferBytesAvailable(StreamBufferHandle_t xStreamBuffer) Queries a stream buffer to see how much data it contains, which is equal to the number of bytes that can be read from the stream buffer before the stream buffer would be empty.
Return The number of bytes that can be read from the stream buffer before the stream buffer would be empty. Parameters
· xStreamBuffer: The handle of the stream buffer being queried.
BaseType_t xStreamBufferSetTriggerLevel(StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel)
A stream bufferns trigger level is the number of bytes that must be in the stream buffer before a task that is blocked on the stream buffer to wait for data is moved out of the blocked state. For example, if a task is blocked on a read of an empty stream buffer that has a trigger level of 1 then the task will be unblocked when a single byte is written to the buffer or the taskns block time expires. As another example, if a task is blocked on a read of an empty stream buffer that has a trigger level of 10 then the task will not be unblocked until the stream buffer contains at least 10 bytes or the taskns block time expires. If a reading taskns block time expires before the trigger level is reached then the task will still receive however many bytes are actually available. Setting a trigger level of 0 will result in a trigger level of 1 being used. It is not valid to specify a trigger level that is greater than the buffer size.
A trigger level is set when the stream buffer is created, and can be modified using xStreamBufferSetTriggerLevel().
Return If xTriggerLevel was less than or equal to the stream bufferns length then the trigger level will be updated and pdTRUE is returned. Otherwise pdFALSE is returned.
Parameters · xStreamBuffer: The handle of the stream buffer being updated. · xTriggerLevel: The new trigger level for the stream buffer.
BaseType_t xStreamBufferSendCompletedFromISR(StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken)
For advanced users only.
The sbSEND_COMPLETED() macro is called from within the FreeRTOS APIs when data is sent to a message buffer or stream buffer. If there was a task that was blocked on the message or stream buffer waiting for data to arrive then the sbSEND_COMPLETED() macro sends a notification to the task to remove it from the Blocked state. xStreamBufferSendCompletedFromISR() does the same thing. It is provided to enable application writers to implement their own version of sbSEND_COMPLETED(), and MUST NOT BE USED AT ANY OTHER TIME.
See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for additional information.

Espressif Systems

1239

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return If a task was removed from the Blocked state then pdTRUE is returned. Otherwise pdFALSE is returned.
Parameters · xStreamBuffer: The handle of the stream buffer to which data was written. · pxHigherPriorityTaskWoken: *pxHigherPriorityTaskWoken should be initialised to pdFALSE before it is passed into xStreamBufferSendCompletedFromISR(). If calling xStreamBufferSendCompletedFromISR() removes a task from the Blocked state, and the task has a priority above the priority of the currently running task, then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a context switch should be performed before exiting the ISR.

BaseType_t xStreamBufferReceiveCompletedFromISR(StreamBufferHandle_t

xStreamBuffer,

BaseType_t

*pxHigherPriorityTaskWoken)

For advanced users only.

The sbRECEIVE_COMPLETED() macro is called from within the FreeRTOS APIs when data is read out of a message buffer or stream buffer. If there was a task that was blocked on the message or stream buffer waiting for data to arrive then the sbRECEIVE_COMPLETED() macro sends a notification to the task to remove it from the Blocked state. xStreamBufferReceiveCompletedFromISR() does the same thing. It is provided to enable application writers to implement their own version of sbRECEIVE_COMPLETED(), and MUST NOT BE USED AT ANY OTHER TIME.

See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for additional information.

Return If a task was removed from the Blocked state then pdTRUE is returned. Otherwise pdFALSE is returned.
Parameters · xStreamBuffer: The handle of the stream buffer from which data was read. · pxHigherPriorityTaskWoken: *pxHigherPriorityTaskWoken should be initialised to pdFALSE before it is passed into xStreamBufferReceiveCompletedFromISR(). If calling xStreamBufferReceiveCompletedFromISR() removes a task from the Blocked state, and the task has a priority above the priority of the currently running task, then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a context switch should be performed before exiting the ISR.

Macros xStreamBufferCreate(xBufferSizeBytes, xTriggerLevelBytes)
Creates a new stream buffer using dynamically allocated memory. See xStreamBufferCreateStatic() for a version that uses statically allocated memory (memory that is allocated at compile time).
configSUPPORT_DYNAMIC_ALLOCATION must be set to 1 or left undefined in FreeRTOSConfig.h for xStreamBufferCreate() to be available.
Example use:
void vAFunction( void ) { StreamBufferHandle_t xStreamBuffer; const size_t xStreamBufferSizeBytes = 100, xTriggerLevel = 10;
// Create a stream buffer that can hold 100 bytes. The memory used to hold // both the stream buffer structure and the data in the stream buffer is // allocated dynamically. xStreamBuffer = xStreamBufferCreate( xStreamBufferSizeBytes, xTriggerLevel );
if( xStreamBuffer == NULL ) {
// There was not enough heap memory space available to create the // stream buffer. } else {
(continues on next page)

Espressif Systems

1240

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page) // The stream buffer was created successfully and can now be used. } }
Return If NULL is returned, then the stream buffer cannot be created because there is insufficient heap memory available for FreeRTOS to allocate the stream buffer data structures and storage area. A nonNULL value being returned indicates that the stream buffer has been created successfully - the returned value should be stored as the handle to the created stream buffer.
Parameters · xBufferSizeBytes: The total number of bytes the stream buffer will be able to hold at any one time. · xTriggerLevelBytes: The number of bytes that must be in the stream buffer before a task that is blocked on the stream buffer to wait for data is moved out of the blocked state. For example, if a task is blocked on a read of an empty stream buffer that has a trigger level of 1 then the task will be unblocked when a single byte is written to the buffer or the taskns block time expires. As another example, if a task is blocked on a read of an empty stream buffer that has a trigger level of 10 then the task will not be unblocked until the stream buffer contains at least 10 bytes or the taskn s block time expires. If a reading taskns block time expires before the trigger level is reached then the task will still receive however many bytes are actually available. Setting a trigger level of 0 will result in a trigger level of 1 being used. It is not valid to specify a trigger level that is greater than the buffer size.
xStreamBufferCreateStatic(xBufferSizeBytes, xTriggerLevelBytes, pucStreamBufferStorageArea, pxStaticStreamBuffer)
Creates a new stream buffer using statically allocated memory. See xStreamBufferCreate() for a version that uses dynamically allocated memory.
configSUPPORT_STATIC_ALLOCATION must be set to 1 in FreeRTOSConfig.h for xStreamBufferCreateStatic() to be available.
Example use:
// Used to dimension the array used to hold the streams. The available space // will actually be one less than this, so 999. #define STORAGE_SIZE_BYTES 1000
// Defines the memory that will actually hold the streams within the stream // buffer. static uint8_t ucStorageBuffer[ STORAGE_SIZE_BYTES ];
// The variable used to hold the stream buffer structure. StaticStreamBuffer_t xStreamBufferStruct;
void MyFunction( void ) { StreamBufferHandle_t xStreamBuffer; const size_t xTriggerLevel = 1;
xStreamBuffer = xStreamBufferCreateStatic( sizeof( ucBufferStorage ), xTriggerLevel, ucBufferStorage, &xStreamBufferStruct );
// As neither the pucStreamBufferStorageArea or pxStaticStreamBuffer // parameters were NULL, xStreamBuffer will not be NULL, and can be used to // reference the created stream buffer in other stream buffer API calls.
// Other code that uses the stream buffer can go here. }
Return If the stream buffer is created successfully then a handle to the created stream buffer is returned. If either pucStreamBufferStorageArea or pxStaticstreamBuffer are NULL then NULL is returned.

Espressif Systems

1241

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Parameters · xBufferSizeBytes: The size, in bytes, of the buffer pointed to by the pucStreamBufferStorageArea parameter. · xTriggerLevelBytes: The number of bytes that must be in the stream buffer before a task that is blocked on the stream buffer to wait for data is moved out of the blocked state. For example, if a task is blocked on a read of an empty stream buffer that has a trigger level of 1 then the task will be unblocked when a single byte is written to the buffer or the taskns block time expires. As another example, if a task is blocked on a read of an empty stream buffer that has a trigger level of 10 then the task will not be unblocked until the stream buffer contains at least 10 bytes or the taskn s block time expires. If a reading taskns block time expires before the trigger level is reached then the task will still receive however many bytes are actually available. Setting a trigger level of 0 will result in a trigger level of 1 being used. It is not valid to specify a trigger level that is greater than the buffer size. · pucStreamBufferStorageArea: Must point to a uint8_t array that is at least xBufferSizeBytes + 1 big. This is the array to which streams are copied when they are written to the stream buffer. · pxStaticStreamBuffer: Must point to a variable of type StaticStreamBuffer_t, which will be used to hold the stream bufferns data structure.
Type Definitions typedef struct StreamBufferDef_t *StreamBufferHandle_t
Message Buffer API
Header File
· components/freertos/FreeRTOS-Kernel/include/freertos/message_buffer.h
Macros xMessageBufferCreate(xBufferSizeBytes)
Creates a new message buffer using dynamically allocated memory. See xMessageBufferCreateStatic() for a version that uses statically allocated memory (memory that is allocated at compile time).
configSUPPORT_DYNAMIC_ALLOCATION must be set to 1 or left undefined in FreeRTOSConfig.h for xMessageBufferCreate() to be available.
Example use:
void vAFunction( void ) { MessageBufferHandle_t xMessageBuffer; const size_t xMessageBufferSizeBytes = 100;
// Create a message buffer that can hold 100 bytes. The memory used to hold // both the message buffer structure and the messages themselves is allocated // dynamically. Each message added to the buffer consumes an additional 4 // bytes which are used to hold the lengh of the message. xMessageBuffer = xMessageBufferCreate( xMessageBufferSizeBytes );
if( xMessageBuffer == NULL ) {
// There was not enough heap memory space available to create the // message buffer. } else { // The message buffer was created successfully and can now be used. }

Espressif Systems

1242

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Return If NULL is returned, then the message buffer cannot be created because there is insufficient heap memory available for FreeRTOS to allocate the message buffer data structures and storage area. A nonNULL value being returned indicates that the message buffer has been created successfully - the returned value should be stored as the handle to the created message buffer.
Parameters · xBufferSizeBytes: The total number of bytes (not messages) the message buffer will be able to hold at any one time. When a message is written to the message buffer an additional sizeof( size_t ) bytes are also written to store the messagens length. sizeof( size_t ) is typically 4 bytes on a 32-bit architecture, so on most 32-bit architectures a 10 byte message will take up 14 bytes of message buffer space.
xMessageBufferCreateStatic(xBufferSizeBytes, pucMessageBufferStorageArea, pxStaticMessageBuffer)
Creates a new message buffer using statically allocated memory. See xMessageBufferCreate() for a version that uses dynamically allocated memory.
Example use:
// Used to dimension the array used to hold the messages. The available space // will actually be one less than this, so 999. #define STORAGE_SIZE_BYTES 1000
// Defines the memory that will actually hold the messages within the message // buffer. static uint8_t ucStorageBuffer[ STORAGE_SIZE_BYTES ];
// The variable used to hold the message buffer structure. StaticMessageBuffer_t xMessageBufferStruct;
void MyFunction( void ) { MessageBufferHandle_t xMessageBuffer;
xMessageBuffer = xMessageBufferCreateStatic( sizeof( ucBufferStorage ), ucBufferStorage, &xMessageBufferStruct );
// As neither the pucMessageBufferStorageArea or pxStaticMessageBuffer // parameters were NULL, xMessageBuffer will not be NULL, and can be used to // reference the created message buffer in other message buffer API calls.
// Other code that uses the message buffer can go here. }
Return If the message buffer is created successfully then a handle to the created message buffer is returned. If either pucMessageBufferStorageArea or pxStaticmessageBuffer are NULL then NULL is returned.
Parameters · xBufferSizeBytes: The size, in bytes, of the buffer pointed to by the pucMessageBufferStorageArea parameter. When a message is written to the message buffer an additional sizeof( size_t ) bytes are also written to store the messagens length. sizeof( size_t ) is typically 4 bytes on a 32-bit architecture, so on most 32-bit architecture a 10 byte message will take up 14 bytes of message buffer space. The maximum number of bytes that can be stored in the message buffer is actually (xBufferSizeBytes - 1). · pucMessageBufferStorageArea: Must point to a uint8_t array that is at least xBufferSizeBytes + 1 big. This is the array to which messages are copied when they are written to the message buffer. · pxStaticMessageBuffer: Must point to a variable of type StaticMessageBuffer_t, which will be used to hold the message bufferns data structure.
xMessageBufferSend(xMessageBuffer, pvTxData, xDataLengthBytes, xTicksToWait) Sends a discrete message to the message buffer. The message can be any length that fits within the bufferns free space, and is copied into the buffer.

Espressif Systems

1243

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

: Uniquely among FreeRTOS objects, the stream buffer implementation (so also the message buffer implementation, as message buffers are built on top of stream buffers) assumes there is only one task or interrupt that will write to the buffer (the writer), and only one task or interrupt that will read from the buffer (the reader). It is safe for the writer and reader to be different tasks or interrupts, but, unlike other FreeRTOS objects, it is not safe to have multiple different writers or multiple different readers. If there are to be multiple different writers then the application writer must place each call to a writing API function (such as xMessageBufferSend()) inside a critical section and set the send block time to 0. Likewise, if there are to be multiple different readers then the application writer must place each call to a reading API function (such as xMessageBufferRead()) inside a critical section and set the receive block time to 0.
Use xMessageBufferSend() to write to a message buffer from a task. Use xMessageBufferSendFromISR() to write to a message buffer from an interrupt service routine (ISR).
Example use:
void vAFunction( MessageBufferHandle_t xMessageBuffer ) { size_t xBytesSent; uint8_t ucArrayToSend[] = { 0, 1, 2, 3 }; char *pcStringToSend = "String to send"; const TickType_t x100ms = pdMS_TO_TICKS( 100 );
// Send an array to the message buffer, blocking for a maximum of 100ms to // wait for enough space to be available in the message buffer. xBytesSent = xMessageBufferSend( xMessageBuffer, ( void * ) ucArrayToSend, sizeof( ucArrayToSend ), x100ms );
if( xBytesSent != sizeof( ucArrayToSend ) ) {
// The call to xMessageBufferSend() times out before there was enough // space in the buffer for the data to be written. }
// Send the string to the message buffer. Return immediately if there is // not enough space in the buffer. xBytesSent = xMessageBufferSend( xMessageBuffer, ( void * ) pcStringToSend, strlen( pcStringToSend ), 0 );
if( xBytesSent != strlen( pcStringToSend ) ) {
// The string could not be added to the message buffer because there was // not enough free space in the buffer. } }
Return The number of bytes written to the message buffer. If the call to xMessageBufferSend() times out before there was enough space to write the message into the message buffer then zero is returned. If the call did not time out then xDataLengthBytes is returned.
Parameters · xMessageBuffer: The handle of the message buffer to which a message is being sent. · pvTxData: A pointer to the message that is to be copied into the message buffer. · xDataLengthBytes: The length of the message. That is, the number of bytes to copy from pvTxData into the message buffer. When a message is written to the message buffer an additional sizeof( size_t ) bytes are also written to store the messagens length. sizeof( size_t ) is typically 4 bytes on a 32-bit architecture, so on most 32-bit architecture setting xDataLengthBytes to 20 will reduce the free space in the message buffer by 24 bytes (20 bytes of message data and 4 bytes to hold the message length). · xTicksToWait: The maximum amount of time the calling task should remain in the Blocked state to wait for enough space to become available in the message buffer, should the message buffer have insufficient space when xMessageBufferSend() is called. The calling task will never block if xTicksToWait is zero. The block time is specified in tick periods, so the absolute time it represents is dependent on the tick frequency. The macro pdMS_TO_TICKS() can be used to convert a time

Espressif Systems

1244

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

specified in milliseconds into a time specified in ticks. Setting xTicksToWait to portMAX_DELAY will cause the task to wait indefinitely (without timing out), provided INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. Tasks do not use any CPU time when they are in the Blocked state.
xMessageBufferSendFromISR(xMessageBuffer, pvTxData, xDataLengthBytes, pxHigherPriorityTaskWoken)
Interrupt safe version of the API function that sends a discrete message to the message buffer. The message can be any length that fits within the bufferns free space, and is copied into the buffer.
: Uniquely among FreeRTOS objects, the stream buffer implementation (so also the message buffer implementation, as message buffers are built on top of stream buffers) assumes there is only one task or interrupt that will write to the buffer (the writer), and only one task or interrupt that will read from the buffer (the reader). It is safe for the writer and reader to be different tasks or interrupts, but, unlike other FreeRTOS objects, it is not safe to have multiple different writers or multiple different readers. If there are to be multiple different writers then the application writer must place each call to a writing API function (such as xMessageBufferSend()) inside a critical section and set the send block time to 0. Likewise, if there are to be multiple different readers then the application writer must place each call to a reading API function (such as xMessageBufferRead()) inside a critical section and set the receive block time to 0.
Use xMessageBufferSend() to write to a message buffer from a task. Use xMessageBufferSendFromISR() to write to a message buffer from an interrupt service routine (ISR).
Example use:
// A message buffer that has already been created. MessageBufferHandle_t xMessageBuffer;
void vAnInterruptServiceRoutine( void ) { size_t xBytesSent; char *pcStringToSend = "String to send"; BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE.
// Attempt to send the string to the message buffer. xBytesSent = xMessageBufferSendFromISR( xMessageBuffer,
( void * ) pcStringToSend, strlen( pcStringToSend ), &xHigherPriorityTaskWoken );
if( xBytesSent != strlen( pcStringToSend ) ) {
// The string could not be added to the message buffer because there was // not enough free space in the buffer. }
// If xHigherPriorityTaskWoken was set to pdTRUE inside // xMessageBufferSendFromISR() then a task that has a priority above the // priority of the currently executing task was unblocked and a context // switch should be performed to ensure the ISR returns to the unblocked // task. In most FreeRTOS ports this is done by simply passing // xHigherPriorityTaskWoken into portYIELD_FROM_ISR(), which will test the // variables value, and perform the context switch if necessary. Check the // documentation for the port in use for port specific instructions. portYIELD_FROM_ISR( xHigherPriorityTaskWoken ); }
Return The number of bytes actually written to the message buffer. If the message buffer didnnt have enough free space for the message to be stored then 0 is returned, otherwise xDataLengthBytes is returned.
Parameters · xMessageBuffer: The handle of the message buffer to which a message is being sent. · pvTxData: A pointer to the message that is to be copied into the message buffer. · xDataLengthBytes: The length of the message. That is, the number of bytes to copy from pvTxData into the message buffer. When a message is written to the message buffer an additional

Espressif Systems

1245

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

sizeof( size_t ) bytes are also written to store the messagens length. sizeof( size_t ) is typically 4 bytes on a 32-bit architecture, so on most 32-bit architecture setting xDataLengthBytes to 20 will reduce the free space in the message buffer by 24 bytes (20 bytes of message data and 4 bytes to hold the message length). · pxHigherPriorityTaskWoken: It is possible that a message buffer will have a task blocked on it waiting for data. Calling xMessageBufferSendFromISR() can make data available, and so cause a task that was waiting for data to leave the Blocked state. If calling xMessageBufferSendFromISR() causes a task to leave the Blocked state, and the unblocked task has a priority higher than the currently executing task (the task that was interrupted), then, internally, xMessageBufferSendFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE. If xMessageBufferSendFromISR() sets this value to pdTRUE, then normally a context switch should be performed before the interrupt is exited. This will ensure that the interrupt returns directly to the highest priority Ready state task. *pxHigherPriorityTaskWoken should be set to pdFALSE before it is passed into the function. See the code example below for an example.
xMessageBufferReceive(xMessageBuffer, pvRxData, xBufferLengthBytes, xTicksToWait) Receives a discrete message from a message buffer. Messages can be of variable length and are copied out of the buffer.
: Uniquely among FreeRTOS objects, the stream buffer implementation (so also the message buffer implementation, as message buffers are built on top of stream buffers) assumes there is only one task or interrupt that will write to the buffer (the writer), and only one task or interrupt that will read from the buffer (the reader). It is safe for the writer and reader to be different tasks or interrupts, but, unlike other FreeRTOS objects, it is not safe to have multiple different writers or multiple different readers. If there are to be multiple different writers then the application writer must place each call to a writing API function (such as xMessageBufferSend()) inside a critical section and set the send block time to 0. Likewise, if there are to be multiple different readers then the application writer must place each call to a reading API function (such as xMessageBufferRead()) inside a critical section and set the receive block time to 0.
Use xMessageBufferReceive() to read from a message buffer from a task. Use xMessageBufferReceiveFromISR() to read from a message buffer from an interrupt service routine (ISR).
Example use:

void vAFunction( MessageBuffer_t xMessageBuffer ) { uint8_t ucRxData[ 20 ]; size_t xReceivedBytes; const TickType_t xBlockTime = pdMS_TO_TICKS( 20 );

// Receive the next message from the message buffer. Wait in the Blocked // state (so not using any CPU processing time) for a maximum of 100ms for // a message to become available. xReceivedBytes = xMessageBufferReceive( xMessageBuffer,
( void * ) ucRxData, sizeof( ucRxData ), xBlockTime );

if( xReceivedBytes > 0 ) {
// A ucRxData contains a message that is xReceivedBytes long. // the message here.... } }

Process

Return The length, in bytes, of the message read from the message buffer, if any. If xMessageBufferReceive() times out before a message became available then zero is returned. If the length of the message is greater than xBufferLengthBytes then the message will be left in the message buffer and zero is returned.
Parameters · xMessageBuffer: The handle of the message buffer from which a message is being received. · pvRxData: A pointer to the buffer into which the received message is to be copied. · xBufferLengthBytes: The length of the buffer pointed to by the pvRxData parameter. This

Espressif Systems

1246

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

sets the maximum length of the message that can be received. If xBufferLengthBytes is too small to hold the next message then the message will be left in the message buffer and 0 will be returned. · xTicksToWait: The maximum amount of time the task should remain in the Blocked state to wait for a message, should the message buffer be empty. xMessageBufferReceive() will return immediately if xTicksToWait is zero and the message buffer is empty. The block time is specified in tick periods, so the absolute time it represents is dependent on the tick frequency. The macro pdMS_TO_TICKS() can be used to convert a time specified in milliseconds into a time specified in ticks. Setting xTicksToWait to portMAX_DELAY will cause the task to wait indefinitely (without timing out), provided INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. Tasks do not use any CPU time when they are in the Blocked state.
xMessageBufferReceiveFromISR(xMessageBuffer, pvRxData, xBufferLengthBytes, pxHigherPriorityTaskWoken)
An interrupt safe version of the API function that receives a discrete message from a message buffer. Messages can be of variable length and are copied out of the buffer.
: Uniquely among FreeRTOS objects, the stream buffer implementation (so also the message buffer implementation, as message buffers are built on top of stream buffers) assumes there is only one task or interrupt that will write to the buffer (the writer), and only one task or interrupt that will read from the buffer (the reader). It is safe for the writer and reader to be different tasks or interrupts, but, unlike other FreeRTOS objects, it is not safe to have multiple different writers or multiple different readers. If there are to be multiple different writers then the application writer must place each call to a writing API function (such as xMessageBufferSend()) inside a critical section and set the send block time to 0. Likewise, if there are to be multiple different readers then the application writer must place each call to a reading API function (such as xMessageBufferRead()) inside a critical section and set the receive block time to 0.
Use xMessageBufferReceive() to read from a message buffer from a task. Use xMessageBufferReceiveFromISR() to read from a message buffer from an interrupt service routine (ISR).
Example use:

// A message buffer that has already been created. MessageBuffer_t xMessageBuffer;

void vAnInterruptServiceRoutine( void ) { uint8_t ucRxData[ 20 ]; size_t xReceivedBytes; BaseType_t xHigherPriorityTaskWoken = pdFALSE;

// Initialised to pdFALSE.

// Receive the next message from the message buffer. xReceivedBytes = xMessageBufferReceiveFromISR( xMessageBuffer,
( void * ) ucRxData, sizeof( ucRxData ), &xHigherPriorityTaskWoken );

if( xReceivedBytes > 0 ) {
// A ucRxData contains a message that is xReceivedBytes long. // the message here.... }

Process

// If xHigherPriorityTaskWoken was set to pdTRUE inside // xMessageBufferReceiveFromISR() then a task that has a priority above the // priority of the currently executing task was unblocked and a context // switch should be performed to ensure the ISR returns to the unblocked // task. In most FreeRTOS ports this is done by simply passing // xHigherPriorityTaskWoken into portYIELD_FROM_ISR(), which will test the // variables value, and perform the context switch if necessary. Check the // documentation for the port in use for port specific instructions. portYIELD_FROM_ISR( xHigherPriorityTaskWoken ); }

Espressif Systems

1247

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return The length, in bytes, of the message read from the message buffer, if any. Parameters
· xMessageBuffer: The handle of the message buffer from which a message is being received. · pvRxData: A pointer to the buffer into which the received message is to be copied. · xBufferLengthBytes: The length of the buffer pointed to by the pvRxData parameter. This
sets the maximum length of the message that can be received. If xBufferLengthBytes is too small to hold the next message then the message will be left in the message buffer and 0 will be returned. · pxHigherPriorityTaskWoken: It is possible that a message buffer will have a task blocked on it waiting for space to become available. Calling xMessageBufferReceiveFromISR() can make space available, and so cause a task that is waiting for space to leave the Blocked state. If calling xMessageBufferReceiveFromISR() causes a task to leave the Blocked state, and the unblocked task has a priority higher than the currently executing task (the task that was interrupted), then, internally, xMessageBufferReceiveFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE. If xMessageBufferReceiveFromISR() sets this value to pdTRUE, then normally a context switch should be performed before the interrupt is exited. That will ensure the interrupt returns directly to the highest priority Ready state task. *pxHigherPriorityTaskWoken should be set to pdFALSE before it is passed into the function. See the code example below for an example.
vMessageBufferDelete(xMessageBuffer) Deletes a message buffer that was previously created using a call to xMessageBufferCreate() or xMessageBufferCreateStatic(). If the message buffer was created using dynamic memory (that is, by xMessageBufferCreate()), then the allocated memory is freed.
A message buffer handle must not be used after the message buffer has been deleted.
Parameters · xMessageBuffer: The handle of the message buffer to be deleted.
xMessageBufferIsFull(xMessageBuffer) Tests to see if a message buffer is full. A message buffer is full if it cannot accept any more messages, of any size, until space is made available by a message being removed from the message buffer.
Return If the message buffer referenced by xMessageBuffer is full then pdTRUE is returned. Otherwise pdFALSE is returned.
Parameters · xMessageBuffer: The handle of the message buffer being queried.
xMessageBufferIsEmpty(xMessageBuffer) Tests to see if a message buffer is empty (does not contain any messages).
Return If the message buffer referenced by xMessageBuffer is empty then pdTRUE is returned. Otherwise pdFALSE is returned.
Parameters · xMessageBuffer: The handle of the message buffer being queried.
xMessageBufferReset(xMessageBuffer) Resets a message buffer to its initial empty state, discarding any message it contained.
A message buffer can only be reset if there are no tasks blocked on it.
Return If the message buffer was reset then pdPASS is returned. If the message buffer could not be reset because either there was a task blocked on the message queue to wait for space to become available, or to wait for a a message to be available, then pdFAIL is returned.
Parameters · xMessageBuffer: The handle of the message buffer being reset.
xMessageBufferSpaceAvailable(xMessageBuffer) Returns the number of bytes of free space in the message buffer.
Return The number of bytes that can be written to the message buffer before the message buffer would be full. When a message is written to the message buffer an additional sizeof( size_t ) bytes are also written to store the messagens length. sizeof( size_t ) is typically 4 bytes on a 32-bit architecture, so if xMessageBufferSpacesAvailable() returns 10, then the size of the largest message that can be written to the message buffer is 6 bytes.

Espressif Systems

1248

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Parameters · xMessageBuffer: The handle of the message buffer being queried.
xMessageBufferSpacesAvailable(xMessageBuffer)
xMessageBufferNextLengthBytes(xMessageBuffer) Returns the length (in bytes) of the next message in a message buffer. Useful if xMessageBufferReceive() returned 0 because the size of the buffer passed into xMessageBufferReceive() was too small to hold the next message.
Return The length (in bytes) of the next message in the message buffer, or 0 if the message buffer is empty. Parameters
· xMessageBuffer: The handle of the message buffer being queried.
xMessageBufferSendCompletedFromISR(xMessageBuffer, pxHigherPriorityTaskWoken) For advanced users only.
The sbSEND_COMPLETED() macro is called from within the FreeRTOS APIs when data is sent to a message buffer or stream buffer. If there was a task that was blocked on the message or stream buffer waiting for data to arrive then the sbSEND_COMPLETED() macro sends a notification to the task to remove it from the Blocked state. xMessageBufferSendCompletedFromISR() does the same thing. It is provided to enable application writers to implement their own version of sbSEND_COMPLETED(), and MUST NOT BE USED AT ANY OTHER TIME.
See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for additional information.
Return If a task was removed from the Blocked state then pdTRUE is returned. Otherwise pdFALSE is returned.
Parameters · xMessageBuffer: The handle of the stream buffer to which data was written. · pxHigherPriorityTaskWoken: *pxHigherPriorityTaskWoken should be initialised to pdFALSE before it is passed into xMessageBufferSendCompletedFromISR(). If calling xMessageBufferSendCompletedFromISR() removes a task from the Blocked state, and the task has a priority above the priority of the currently running task, then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a context switch should be performed before exiting the ISR.
xMessageBufferReceiveCompletedFromISR(xMessageBuffer, pxHigherPriorityTaskWoken) For advanced users only.
The sbRECEIVE_COMPLETED() macro is called from within the FreeRTOS APIs when data is read out of a message buffer or stream buffer. If there was a task that was blocked on the message or stream buffer waiting for data to arrive then the sbRECEIVE_COMPLETED() macro sends a notification to the task to remove it from the Blocked state. xMessageBufferReceiveCompletedFromISR() does the same thing. It is provided to enable application writers to implement their own version of sbRECEIVE_COMPLETED(), and MUST NOT BE USED AT ANY OTHER TIME.
See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for additional information.
Return If a task was removed from the Blocked state then pdTRUE is returned. Otherwise pdFALSE is returned.
Parameters · xMessageBuffer: The handle of the stream buffer from which data was read. · pxHigherPriorityTaskWoken: *pxHigherPriorityTaskWoken should be initialised to pdFALSE before it is passed into xMessageBufferReceiveCompletedFromISR(). If calling xMessageBufferReceiveCompletedFromISR() removes a task from the Blocked state, and the task has a priority above the priority of the currently running task, then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a context switch should be performed before exiting the ISR.

Type Definitions typedef void *MessageBufferHandle_t
Type by which message buffers are referenced. For example, a call to xMessageBufferCreate() returns an MessageBufferHandle_t variable that can then be used as a parameter to xMessageBufferSend(), xMessageBufferReceive(), etc.

Espressif Systems

1249

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
2.7.11 FreeRTOS Additions
This document describes the additional features added to ESP-IDF FreeRTOS. This document is split into the following parts:
Contents
· FreeRTOS Additions ­ Overview ­ Ring Buffers ­ Hooks ­ TLSP Deletion Callbacks ­ Component Specific Properties ­ API Reference

Overview
ESP-IDF FreeRTOS is modified version of based on the Xtensa port of FreeRTOS v10.4.3 with significant modifications for SMP compatibility (see ESP-IDF FreeRTOS SMP Changes). However, various new features specific to ESP-IDF FreeRTOS have been added. The features are as follows:
· Ring buffers: Ring buffers provide a FIFO buffer that can accept entries of arbitrary lengths. · Hooks: ESP-IDF FreeRTOS hooks provides support for registering extra Idle and Tick hooks at run time.
Moreover, the hooks can be asymmetric among both CPUs. · Thread Local Storage Pointer (TLSP) Deletion Callbacks: TLSP Deletion callbacks are run automatically
when a task is deleted, thus allowing users to clean up their TLSPs automatically. · Component Specific Properties: Currently added only one component specific property
ORIG_INCLUDE_PATH.
Ring Buffers
The ESP-IDF FreeRTOS ring buffer is a strictly FIFO buffer that supports arbitrarily sized items. Ring buffers are a more memory efficient alternative to FreeRTOS queues in situations where the size of items is variable. The capacity of a ring buffer is not measured by the number of items it can store, but rather by the amount of memory used for storing items. The ring buffer provides API to send an item, or to allocate space for an item in the ring buffer to be filled manually by the user. For efficiency reasons, items are always retrieved from the ring buffer by reference. As a result, all retrieved items must also be returned to the ring buffer by using vRingbufferReturnItem() or vRingbufferReturnItemFromISR(), in order for them to be removed from the ring buffer completely. The ring buffers are split into the three following types:
No-Split buffers will guarantee that an item is stored in contiguous memory and will not attempt to split an item under any circumstances. Use No-Split buffers when items must occupy contiguous memory. Only this buffer type allows you to get the data item address and write to the item by yourself. Refer the documentation of the functions xRingbufferSendAcquire() and xRingbufferSendComplete() for more details.
Allow-Split buffers will allow an item to be split in two parts when wrapping around the end of the buffer if there is enough space at the tail and the head of the buffer combined to store the item. Allow-Split buffers are more memory efficient than No-Split buffers but can return an item in two parts when retrieving.
Byte buffers do not store data as separate items. All data is stored as a sequence of bytes, and any number of bytes can be sent or retrieved each time. Use byte buffers when separate items do not need to be maintained (e.g. a byte stream).
Note: No-Split buffers and Allow-Split buffers will always store items at 32-bit aligned addresses. Therefore, when retrieving an item, the item pointer is guaranteed to be 32-bit aligned. This is useful especially when you need to send some data to the DMA.

Espressif Systems

1250

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Note: Each item stored in No-Split or Allow-Split buffers will require an additional 8 bytes for a header. Item sizes will also be rounded up to a 32-bit aligned size (multiple of 4 bytes), however the true item size is recorded within the header. The sizes of No-Split and Allow-Split buffers will also be rounded up when created.

Usage The following example demonstrates the usage of xRingbufferCreate() and xRingbufferSend() to create a ring buffer and then send an item to it.
#include "freertos/ringbuf.h" static char tx_item[] = "test_item";
...
//Create ring buffer RingbufHandle_t buf_handle; buf_handle = xRingbufferCreate(1028, RINGBUF_TYPE_NOSPLIT); if (buf_handle == NULL) {
printf("Failed to create ring buffer\n"); }
//Send an item UBaseType_t res = xRingbufferSend(buf_handle, tx_item, sizeof(tx_item), pdMS_ TO_TICKS(1000)); if (res != pdTRUE) {
printf("Failed to send item\n"); }
The following example demonstrates the usage of xRingbufferSendAcquire() and xRingbufferSendComplete() instead of xRingbufferSend() to acquire memory on the ring buffer (of type RINGBUF_TYPE_NOSPLIT) and then send an item to it. This adds one more step, but allows getting the address of the memory to write to, and writing to the memory yourself.
#include "freertos/ringbuf.h" #include "soc/lldesc.h"
typedef struct { lldesc_t dma_desc; uint8_t buf[1];
} dma_item_t;
#define DMA_ITEM_SIZE(N) (sizeof(lldesc_t)+(((N)+3)&(~3)))
...
//Retrieve space for DMA descriptor and corresponding data buffer //This has to be done with SendAcquire, or the address may be different when we copy dma_item_t item; UBaseType_t res = xRingbufferSendAcquire(buf_handle,
&item, DMA_ITEM_SIZE(buffer_size), pdMS_TO_TICKS(1000)); if (res != pdTRUE) {
printf("Failed to acquire memory for item\n"); } item->dma_desc = (lldesc_t) {
.size = buffer_size, .length = buffer_size, .eof = 0, .owner = 1, .buf = &item->buf, };
(continues on next page)

Espressif Systems

1251

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

//Actually send to the ring buffer for consumer to use res = xRingbufferSendComplete(buf_handle, &item); if (res != pdTRUE) {
printf("Failed to send item\n"); }

(continued from previous page)

The following example demonstrates retrieving and returning an item from a No-Split ring buffer using xRingbufferReceive() and vRingbufferReturnItem()
...
//Receive an item from no-split ring buffer size_t item_size; char *item = (char *)xRingbufferReceive(buf_handle, &item_size, pdMS_TO_ TICKS(1000));
//Check received item if (item != NULL) {
//Print item for (int i = 0; i < item_size; i++) {
printf("%c", item[i]); } printf("\n"); //Return Item vRingbufferReturnItem(buf_handle, (void *)item); } else { //Failed to receive item printf("Failed to receive item\n"); }

The following example demonstrates retrieving and returning an item from an Allow-Split ring buffer using xRingbufferReceiveSplit() and vRingbufferReturnItem()
...
//Receive an item from allow-split ring buffer size_t item_size1, item_size2; char *item1, *item2; BaseType_t ret = xRingbufferReceiveSplit(buf_handle, (void **)&item1, (void **)&item2, &item_size1, &item_size2, pdMS_TO_TICKS(1000));
//Check received item if (ret == pdTRUE && item1 != NULL) {
for (int i = 0; i < item_size1; i++) { printf("%c", item1[i]);
} vRingbufferReturnItem(buf_handle, (void *)item1); //Check if item was split if (item2 != NULL) {
for (int i = 0; i < item_size2; i++) { printf("%c", item2[i]);
} vRingbufferReturnItem(buf_handle, (void *)item2); } printf("\n"); } else { //Failed to receive item printf("Failed to receive item\n"); }

The following example demonstrates retrieving and returning an item from a byte buffer using xRingbufferReceiveUpTo() and vRingbufferReturnItem()

Espressif Systems

1252

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
...
//Receive data from byte buffer size_t item_size; char *item = (char *)xRingbufferReceiveUpTo(buf_handle, &item_size, pdMS_TO_ TICKS(1000), sizeof(tx_item));
//Check received data if (item != NULL) {
//Print item for (int i = 0; i < item_size; i++) {
printf("%c", item[i]); } printf("\n"); //Return Item vRingbufferReturnItem(buf_handle, (void *)item); } else { //Failed to receive item printf("Failed to receive item\n"); }
For ISR safe versions of the functions used above, call xRingbufferSendFromISR(), xRingbufferReceiveFromISR(), xRingbufferReceiveSplitFromISR(), xRingbufferReceiveUpToFromISR(), and vRingbufferReturnItemFromISR()
Note: Two calls to RingbufferReceive[UpTo][FromISR]() are required if the bytes wraps around the end of the ring buffer.
Sending to Ring Buffer The following diagrams illustrate the differences between No-Split and Allow-Split buffers as compared to byte buffers with regard to sending items/data. The diagrams assume that three items of sizes 18, 3, and 27 bytes are sent respectively to a buffer of 128 bytes.

Fig. 29: Sending items to No-Split or Allow-Split ring buffers
For No-Split and Allow-Split buffers, a header of 8 bytes precedes every data item. Furthermore, the space occupied by each item is rounded up to the nearest 32-bit aligned size in order to maintain overall 32-bit alignment. However, the true size of the item is recorded inside the header which will be returned when the item is retrieved.
Referring to the diagram above, the 18, 3, and 27 byte items are rounded up to 20, 4, and 28 bytes respectively. An 8 byte header is then added in front of each item.
Byte buffers treat data as a sequence of bytes and does not incur any overhead (no headers). As a result, all data sent to a byte buffer is merged into a single item.
Referring to the diagram above, the 18, 3, and 27 byte items are sequentially written to the byte buffer and merged into a single item of 48 bytes.

Using SendAcquire and SendComplete Items in No-Split buffers are acquired (by SendAcquire) in strict FIFO order and must be sent to the buffer by SendComplete for the data to be accessible by the consumer.

Espressif Systems

1253

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Fig. 30: Sending items to byte buffers Multiple items can be sent or acquired without calling SendComplete, and the items do not necessarily need to be completed in the order they were acquired. However, the receiving of data items must occur in FIFO order, therefore not calling SendComplete for the earliest acquired item will prevent the subsequent items from being received. The following diagrams illustrate what will happen when SendAcquire and SendComplete donnt happen in the same order. At the beginning, there is already a data item of 16 bytes sent to the ring buffer. Then SendAcquire is called to acquire space of 20, 8, 24 bytes on the ring buffer.

Fig. 31: SendAcquire/SendComplete items in No-Split ring buffers
After that, we fill (use) the buffers, and send them to the ring buffer by SendComplete in the order of 8, 24, 20. When 8 bytes and 24 bytes data are sent, the consumer still can only get the 16 bytes data item. Hence, if SendComplete is not called for the 20 bytes, it will not be available, nor will the data items following the 20 bytes item.
When the 20 bytes item is finally completed, all the 3 data items can be received now, in the order of 20, 8, 24 bytes, right after the 16 bytes item existing in the buffer at the beginning.
Allow-Split buffers and byte buffers do not allow using SendAcquire or SendComplete since acquired buffers are required to be complete (not wrapped).
Wrap around The following diagrams illustrate the differences between No-Split, Allow-Split, and byte buffers when a sent item requires a wrap around. The diagrams assume a buffer of 128 bytes with 56 bytes of free space that wraps around and a sent item of 28 bytes.

Espressif Systems

Fig. 32: Wrap around in No-Split buffers

1254

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
No-Split buffers will only store an item in continuous free space and will not split an item under any circumstances. When the free space at the tail of the buffer is insufficient to completely store the item and its header, the free space at the tail will be marked as dummy data. The buffer will then wrap around and store the item in the free space at the head of the buffer. Referring to the diagram above, the 16 bytes of free space at the tail of the buffer is insufficient to store the 28 byte item. Therefore, the 16 bytes is marked as dummy data and the item is written to the free space at the head of the buffer instead.
Fig. 33: Wrap around in Allow-Split buffers Allow-Split buffers will attempt to split the item into two parts when the free space at the tail of the buffer is insufficient to store the item data and its header. Both parts of the split item will have their own headers (therefore incurring an extra 8 bytes of overhead). Referring to the diagram above, the 16 bytes of free space at the tail of the buffer is insufficient to store the 28 byte item. Therefore, the item is split into two parts (8 and 20 bytes) and written as two parts to the buffer.
Note: Allow-Split buffers treat both parts of the split item as two separate items, therefore call xRingbufferReceiveSplit() instead of xRingbufferReceive() to receive both parts of a split item in a thread safe manner.

Fig. 34: Wrap around in byte buffers
Byte buffers will store as much data as possible into the free space at the tail of buffer. The remaining data will then be stored in the free space at the head of the buffer. No overhead is incurred when wrapping around in byte buffers.
Referring to the diagram above, the 16 bytes of free space at the tail of the buffer is insufficient to completely store the 28 bytes of data. Therefore, the 16 bytes of free space is filled with data, and the remaining 12 bytes are written to the free space at the head of the buffer. The buffer now contains data in two separate continuous parts, and each continuous part will be treated as a separate item by the byte buffer.

Retrieving/Returning The following diagrams illustrate the differences between No-Split and Allow-Split buffers as compared to byte buffers in retrieving and returning data.
Items in No-Split buffers and Allow-Split buffers are retrieved in strict FIFO order and must be returned for the occupied space to be freed. Multiple items can be retrieved before returning, and the items do not necessarily need to be returned in the order they were retrieved. However, the freeing of space must occur in FIFO order, therefore not returning the earliest retrieved item will prevent the space of subsequent items from being freed.

Espressif Systems

1255

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Fig. 35: Retrieving/Returning items in No-Split and Allow-Split ring buffers
Referring to the diagram above, the 16, 20, and 8 byte items are retrieved in FIFO order. However, the items are not returned in the order they were retrieved. First, the 20 byte item is returned followed by the 8 byte and the 16 byte items. The space is not freed until the first item, i.e., the 16 byte item is returned.

Fig. 36: Retrieving/Returning data in byte buffers
Byte buffers do not allow multiple retrievals before returning (every retrieval must be followed by a return before another retrieval is permitted). When using xRingbufferReceive() or xRingbufferReceiveFromISR(), all continuous stored data will be retrieved. xRingbufferReceiveUpTo() or xRingbufferReceiveUpToFromISR() can be used to restrict the maximum number of bytes retrieved. Since every retrieval must be followed by a return, the space will be freed as soon as the data is returned.
Referring to the diagram above, the 38 bytes of continuous stored data at the tail of the buffer is retrieved, returned, and freed. The next call to xRingbufferReceive() or xRingbufferReceiveFromISR() then wraps around and does the same to the 30 bytes of continuous stored data at the head of the buffer.

Ring Buffers with Queue Sets Ring buffers can be added to FreeRTOS queue sets using xRingbufferAddToQueueSetRead() such that every time a ring buffer receives an item or data, the queue set is notified. Once added to a queue set, every attempt to retrieve an item from a ring buffer should be preceded by a call to xQueueSelectFromSet(). To check whether the selected queue set member is the ring buffer, call xRingbufferCanRead().
The following example demonstrates queue set usage with ring buffers.
#include "freertos/queue.h" #include "freertos/ringbuf.h"
...
//Create ring buffer and queue set RingbufHandle_t buf_handle = xRingbufferCreate(1028, RINGBUF_TYPE_NOSPLIT);
(continues on next page)

Espressif Systems

1256

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

QueueSetHandle_t queue_set = xQueueCreateSet(3);

(continued from previous page)

//Add ring buffer to queue set if (xRingbufferAddToQueueSetRead(buf_handle, queue_set) != pdTRUE) {
printf("Failed to add to queue set\n"); }

...

//Block on queue set xQueueSetMemberHandle member = xQueueSelectFromSet(queue_set, pdMS_TO_ TICKS(1000));

//Check if member is ring buffer if (member != NULL && xRingbufferCanRead(buf_handle, member) == pdTRUE) {
//Member is ring buffer, receive item from ring buffer size_t item_size; char *item = (char *)xRingbufferReceive(buf_handle, &item_size, 0);

//Handle item ...

} else { ...
}

Ring Buffers with Static Allocation The xRingbufferCreateStatic() can be used to create ring buffers with specific memory requirements (such as a ring buffer being allocated in external RAM). All blocks of memory used by a ring buffer must be manually allocated beforehand then passed to the xRingbufferCreateStatic() to be initialized as a ring buffer. These blocks include the following:
· The ring bufferns data structure of type StaticRingbuffer_t · The ring bufferns storage area of size xBufferSize. Note that xBufferSize must be 32-bit aligned
for No-Split and Allow-Split buffers.
The manner in which these blocks are allocated will depend on the users requirements (e.g. all blocks being statically declared, or dynamically allocated with specific capabilities such as external RAM).

Note: When deleting a ring buffer created via xRingbufferCreateStatic(), the function vRingbufferDelete() will not free any of the memory blocks. This must be done manually by the user after vRingbufferDelete() is called.

The code snippet below demonstrates a ring buffer being allocated entirely in external RAM.
#include "freertos/ringbuf.h" #include "freertos/semphr.h" #include "esp_heap_caps.h"

#define BUFFER_SIZE #define BUFFER_TYPE ...

400

//32-bit aligned size

RINGBUF_TYPE_NOSPLIT

//Allocate ring buffer data structure and storage area into external RAM StaticRingbuffer_t *buffer_struct = (StaticRingbuffer_t *)heap_caps_ malloc(sizeof(StaticRingbuffer_t), MALLOC_CAP_SPIRAM); uint8_t *buffer_storage = (uint8_t *)heap_caps_malloc(sizeof(uint8_t)*BUFFER_SIZE, MALLOC_CAP_SPIRAM);

(continues on next page)

Espressif Systems

1257

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
(continued from previous page) //Create a ring buffer with manually allocated memory RingbufHandle_t handle = xRingbufferCreateStatic(BUFFER_SIZE, BUFFER_TYPE, buffer_ storage, buffer_struct);
...
//Delete the ring buffer after used vRingbufferDelete(handle);
//Manually free all blocks of memory free(buffer_struct); free(buffer_storage);
Priority Inversion Ideally, ring buffers can be used with multiple tasks in an SMP fashion where the highest priority task will always be serviced first. However due to the usage of binary semaphores in the ring bufferns underlying implementation, priority inversion may occur under very specific circumstances. The ring buffer governs sending by a binary semaphore which is given whenever space is freed on the ring buffer. The highest priority task waiting to send will repeatedly take the semaphore until sufficient free space becomes available or until it times out. Ideally this should prevent any lower priority tasks from being serviced as the semaphore should always be given to the highest priority task. However, in between iterations of acquiring the semaphore, there is a gap in the critical section which may permit another task (on the other core or with an even higher priority) to free some space on the ring buffer and as a result give the semaphore. Therefore, the semaphore will be given before the highest priority task can re-acquire the semaphore. This will result in the semaphore being acquired by the second-highest priority task waiting to send, hence causing priority inversion. This side effect will not affect ring buffer performance drastically given if the number of tasks using the ring buffer simultaneously is low, and the ring buffer is not operating near maximum capacity.
Hooks
FreeRTOS consists of Idle Hooks and Tick Hooks which allow for application specific functionality to be added to the Idle Task and Tick Interrupt. ESP-IDF provides its own Idle and Tick Hook API in addition to the hooks provided by vanilla FreeRTOS. ESP-IDF hooks have the added benefit of being run time configurable and asymmetrical.
Vanilla FreeRTOS Hooks Idle and Tick Hooks in vanilla FreeRTOS are implemented by the user defining the functions vApplicationIdleHook() and vApplicationTickHook() respectively somewhere in the application. Vanilla FreeRTOS will run the user defined Idle Hook and Tick Hook on every iteration of the Idle Task and Tick Interrupt respectively. Vanilla FreeRTOS hooks are referred to as Legacy Hooks in ESP-IDF FreeRTOS. To enable legacy hooks, CONFIG_FREERTOS_LEGACY_HOOKS should be enabled in project configuration menu. Due to vanilla FreeRTOS being designed for single core, vApplicationIdleHook() and vApplicationTickHook() can only be defined once. However, the ESP32-S3 is dual-core in nature, therefore same Idle Hook and Tick Hook are used for both cores (in other words, the hooks are symmetrical for both cores).
ESP-IDF Idle and Tick Hooks For some use-cases it may be necessary for the Idle Tasks or Tick Interrupts to execute multiple hooks that are configurable at run time. Furthermore, due to the dual-core nature of the ESP32-S3, it may be necessary for some applications to have separate hooks for each core. Therefore, ESP-IDF provides its own hooks API in addition to the legacy hooks provided by vanilla FreeRTOS.

Espressif Systems

1258

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
The ESP-IDF tick and idle hooks are registered at run time. Each tick hook and idle hook must be registered to a specific CPU. When the idle task runs or a tick interrupt occurs on a particular CPU, the CPU will run each of its registered idle hook and tick hook in turn.
Note: Tick interrupt stays active whilst cache is disabled and hence vApplicationTickHook() (legacy case) or ESP-IDF tick hooks must be placed in internal RAM. Please refer to the SPI flash API documentation for more details.
TLSP Deletion Callbacks
Vanilla FreeRTOS provides a Thread Local Storage Pointers (TLSP) feature. These are pointers stored directly in the Task Control Block (TCB) of a particular task. TLSPs allow each task to have its own unique set of pointers to data structures. Vanilla FreeRTOS expects users tol
· set a taskns TLSPs by calling vTaskSetThreadLocalStoragePointer() after the task has been created.
· get a taskns TLSPs by calling pvTaskGetThreadLocalStoragePointer() during the taskns lifetime.
· free the memory pointed to by the TLSPs before the task is deleted. However, there can be instances where users may want the freeing of TLSP memory to be automatic. Therefore, ESPIDF FreeRTOS provides the additional feature of TLSP deletion callbacks. These user provided deletion callbacks are called automatically when a task is deleted, thus allows the TLSP memory to be cleaned up without needing to add the cleanup logic explicitly to the code of every task. The TLSP deletion callbacks are set in a similar fashion to the TLSPs themselves.
· vTaskSetThreadLocalStoragePointerAndDelCallback() sets both a particular TLSP and its associated callback.
· Calling the Vanilla FreeRTOS function vTaskSetThreadLocalStoragePointer() will simply set the TLSPns associated Deletion Callback to NULL meaning that no callback will be called for that TLSP during task deletion.
When implementing TLSP callbacks, users should note the following: · The callback must never attempt to block or yield and critical sections should be kept as short as possible · The callback is called shortly before a deleted taskns memory is freed. Thus, the callback can either be called from vTaskDelete() itself, or from the idle task.
Component Specific Properties
Besides standard component variables that are available with basic cmake build properties, FreeRTOS component also provides arguments (only one so far) for simpler integration with other modules:
· ORIG_INCLUDE_PATH - contains an absolute path to freertos root include folder. Thus instead of #include ofreertos/FreeRTOS.hp you can refer to headers directly: #include oFreeRTOS.hp.
API Reference
Ring Buffer API
Header File · components/esp_ringbuf/include/freertos/ringbuf.h

Espressif Systems

1259

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Functions RingbufHandle_t xRingbufferCreate(size_t xBufferSize, RingbufferType_t xBufferType)
Create a ring buffer.
Note xBufferSize of no-split/allow-split buffers will be rounded up to the nearest 32-bit aligned size. Return A handle to the created ring buffer, or NULL in case of error. Parameters
· [in] xBufferSize: Size of the buffer in bytes. Note that items require space for a header in no-split/allow-split buffers
· [in] xBufferType: Type of ring buffer, see documentation. RingbufHandle_t xRingbufferCreateNoSplit(size_t xItemSize, size_t xItemNum)
Create a ring buffer of type RINGBUF_TYPE_NOSPLIT for a fixed item_size.
This API is similar to xRingbufferCreate(), but it will internally allocate additional space for the headers.
Return A RingbufHandle_t handle to the created ring buffer, or NULL in case of error. Parameters
· [in] xItemSize: Size of each item to be put into the ring buffer · [in] xItemNum: Maximum number of items the buffer needs to hold simultaneously
RingbufHandle_t xRingbufferCreateStatic(size_t xBufferSize, RingbufferType_t xBufferType, uint8_t *pucRingbufferStorage, StaticRingbuffer_t *pxStaticRingbuffer)
Create a ring buffer but manually provide the required memory.
Note xBufferSize of no-split/allow-split buffers MUST be 32-bit aligned. Return A handle to the created ring buffer Parameters
· [in] xBufferSize: Size of the buffer in bytes. · [in] xBufferType: Type of ring buffer, see documentation · [in] pucRingbufferStorage: Pointer to the ring bufferns storage area. Storage area must
have the same size as specified by xBufferSize · [in] pxStaticRingbuffer: Pointed to a struct of type StaticRingbuffer_t which will be
used to hold the ring bufferns data structure
BaseType_t xRingbufferSend(RingbufHandle_t xRingbuffer, const void *pvItem, size_t xItemSize, TickType_t xTicksToWait)
Insert an item into the ring buffer.
Attempt to insert an item into the ring buffer. This function will block until enough free space is available or until it times out.
Note For no-split/allow-split ring buffers, the actual size of memory that the item will occupy will be rounded up to the nearest 32-bit aligned size. This is done to ensure all items are always stored in 32-bit aligned fashion.
Return · pdTRUE if succeeded · pdFALSE on time-out or when the data is larger than the maximum permissible size of the buffer
Parameters · [in] xRingbuffer: Ring buffer to insert the item into · [in] pvItem: Pointer to data to insert. NULL is allowed if xItemSize is 0. · [in] xItemSize: Size of data to insert. · [in] xTicksToWait: Ticks to wait for room in the ring buffer.
BaseType_t xRingbufferSendFromISR(RingbufHandle_t xRingbuffer, const void *pvItem, size_t xItemSize, BaseType_t *pxHigherPriorityTaskWoken)
Insert an item into the ring buffer in an ISR.
Attempt to insert an item into the ring buffer from an ISR. This function will return immediately if there is insufficient free space in the buffer.
Note For no-split/allow-split ring buffers, the actual size of memory that the item will occupy will be rounded up to the nearest 32-bit aligned size. This is done to ensure all items are always stored in 32-bit aligned fashion.

Espressif Systems

1260

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Return · pdTRUE if succeeded · pdFALSE when the ring buffer does not have space.
Parameters · [in] xRingbuffer: Ring buffer to insert the item into · [in] pvItem: Pointer to data to insert. NULL is allowed if xItemSize is 0. · [in] xItemSize: Size of data to insert. · [out] pxHigherPriorityTaskWoken: Value pointed to will be set to pdTRUE if the function woke up a higher priority task.
BaseType_t xRingbufferSendAcquire(RingbufHandle_t xRingbuffer, void **ppvItem, size_t xItemSize, TickType_t xTicksToWait)
Acquire memory from the ring buffer to be written to by an external source and to be sent later.
Attempt to allocate buffer for an item to be sent into the ring buffer. This function will block until enough free space is available or until it times out.
The item, as well as the following items SendAcquire or Send after it, will not be able to be read from the ring buffer until this item is actually sent into the ring buffer.
Note Only applicable for no-split ring buffers now, the actual size of memory that the item will occupy will be rounded up to the nearest 32-bit aligned size. This is done to ensure all items are always stored in 32-bit aligned fashion.
Return · pdTRUE if succeeded · pdFALSE on time-out or when the data is larger than the maximum permissible size of the buffer
Parameters · [in] xRingbuffer: Ring buffer to allocate the memory · [out] ppvItem: Double pointer to memory acquired (set to NULL if no memory were retrieved) · [in] xItemSize: Size of item to acquire. · [in] xTicksToWait: Ticks to wait for room in the ring buffer.
BaseType_t xRingbufferSendComplete(RingbufHandle_t xRingbuffer, void *pvItem) Actually send an item into the ring buffer allocated before by xRingbufferSendAcquire.
Note Only applicable for no-split ring buffers. Only call for items allocated by xRingbufferSendAcquire.
Return · pdTRUE if succeeded · pdFALSE if fail for some reason.
Parameters · [in] xRingbuffer: Ring buffer to insert the item into · [in] pvItem: Pointer to item in allocated memory to insert.
void *xRingbufferReceive(RingbufHandle_t xRingbuffer, size_t *pxItemSize, TickType_t xTicksToWait)
Retrieve an item from the ring buffer.
Attempt to retrieve an item from the ring buffer. This function will block until an item is available or until it times out.
Note A call to vRingbufferReturnItem() is required after this to free the item retrieved. Return
· Pointer to the retrieved item on success; *pxItemSize filled with the length of the item. · NULL on timeout, *pxItemSize is untouched in that case. Parameters · [in] xRingbuffer: Ring buffer to retrieve the item from · [out] pxItemSize: Pointer to a variable to which the size of the retrieved item will be written. · [in] xTicksToWait: Ticks to wait for items in the ring buffer.
void *xRingbufferReceiveFromISR(RingbufHandle_t xRingbuffer, size_t *pxItemSize) Retrieve an item from the ring buffer in an ISR.

Espressif Systems

1261

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Attempt to retrieve an item from the ring buffer. This function returns immediately if there are no items available for retrieval

Note A call to vRingbufferReturnItemFromISR() is required after this to free the item retrieved. Note Byte buffers do not allow multiple retrievals before returning an item Note Two calls to RingbufferReceiveFromISR() are required if the bytes wrap around the end of the ring
buffer. Return
· Pointer to the retrieved item on success; *pxItemSize filled with the length of the item. · NULL when the ring buffer is empty, *pxItemSize is untouched in that case. Parameters · [in] xRingbuffer: Ring buffer to retrieve the item from · [out] pxItemSize: Pointer to a variable to which the size of the retrieved item will be written.

BaseType_t xRingbufferReceiveSplit(RingbufHandle_t xRingbuffer, void **ppvHeadItem,
void **ppvTailItem, size_t *pxHeadItemSize, size_t
*pxTailItemSize, TickType_t xTicksToWait) Retrieve a split item from an allow-split ring buffer.

Attempt to retrieve a split item from an allow-split ring buffer. If the item is not split, only a single item is retried. If the item is split, both parts will be retrieved. This function will block until an item is available or until it times out.

Note Call(s) to vRingbufferReturnItem() is required after this to free up the item(s) retrieved. Note This function should only be called on allow-split buffers Return
· pdTRUE if an item (split or unsplit) was retrieved · pdFALSE when no item was retrieved Parameters · [in] xRingbuffer: Ring buffer to retrieve the item from · [out] ppvHeadItem: Double pointer to first part (set to NULL if no items were retrieved) · [out] ppvTailItem: Double pointer to second part (set to NULL if item is not split) · [out] pxHeadItemSize: Pointer to size of first part (unmodified if no items were retrieved) · [out] pxTailItemSize: Pointer to size of second part (unmodified if item is not split) · [in] xTicksToWait: Ticks to wait for items in the ring buffer.

BaseType_t xRingbufferReceiveSplitFromISR(RingbufHandle_t

xRingbuffer,

void

**ppvHeadItem, void **ppvTailItem, size_t

*pxHeadItemSize, size_t *pxTailItemSize)

Retrieve a split item from an allow-split ring buffer in an ISR.

Attempt to retrieve a split item from an allow-split ring buffer. If the item is not split, only a single item is retried. If the item is split, both parts will be retrieved. This function returns immediately if there are no items available for retrieval

Note Calls to vRingbufferReturnItemFromISR() is required after this to free up the item(s) retrieved. Note This function should only be called on allow-split buffers Return
· pdTRUE if an item (split or unsplit) was retrieved · pdFALSE when no item was retrieved Parameters · [in] xRingbuffer: Ring buffer to retrieve the item from · [out] ppvHeadItem: Double pointer to first part (set to NULL if no items were retrieved) · [out] ppvTailItem: Double pointer to second part (set to NULL if item is not split) · [out] pxHeadItemSize: Pointer to size of first part (unmodified if no items were retrieved) · [out] pxTailItemSize: Pointer to size of second part (unmodified if item is not split)

void *xRingbufferReceiveUpTo(RingbufHandle_t xRingbuffer, size_t *pxItemSize, TickType_t xTicksToWait, size_t xMaxSize)
Retrieve bytes from a byte buffer, specifying the maximum amount of bytes to retrieve.

Attempt to retrieve data from a byte buffer whilst specifying a maximum number of bytes to retrieve. This function will block until there is data available for retrieval or until it times out.

Espressif Systems

1262

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Note A call to vRingbufferReturnItem() is required after this to free up the data retrieved. Note This function should only be called on byte buffers Note Byte buffers do not allow multiple retrievals before returning an item Note Two calls to RingbufferReceiveUpTo() are required if the bytes wrap around the end of the ring buffer. Return
· Pointer to the retrieved item on success; *pxItemSize filled with the length of the item. · NULL on timeout, *pxItemSize is untouched in that case. Parameters · [in] xRingbuffer: Ring buffer to retrieve the item from · [out] pxItemSize: Pointer to a variable to which the size of the retrieved item will be written. · [in] xTicksToWait: Ticks to wait for items in the ring buffer. · [in] xMaxSize: Maximum number of bytes to return.
void *xRingbufferReceiveUpToFromISR(RingbufHandle_t xRingbuffer, size_t *pxItemSize, size_t xMaxSize)
Retrieve bytes from a byte buffer, specifying the maximum amount of bytes to retrieve. Call this from an ISR.
Attempt to retrieve bytes from a byte buffer whilst specifying a maximum number of bytes to retrieve. This function will return immediately if there is no data available for retrieval.
Note A call to vRingbufferReturnItemFromISR() is required after this to free up the data received. Note This function should only be called on byte buffers Note Byte buffers do not allow multiple retrievals before returning an item Return
· Pointer to the retrieved item on success; *pxItemSize filled with the length of the item. · NULL when the ring buffer is empty, *pxItemSize is untouched in that case. Parameters · [in] xRingbuffer: Ring buffer to retrieve the item from · [out] pxItemSize: Pointer to a variable to which the size of the retrieved item will be written. · [in] xMaxSize: Maximum number of bytes to return.
void vRingbufferReturnItem(RingbufHandle_t xRingbuffer, void *pvItem) Return a previously-retrieved item to the ring buffer.
Note If a split item is retrieved, both parts should be returned by calling this function twice Parameters
· [in] xRingbuffer: Ring buffer the item was retrieved from · [in] pvItem: Item that was received earlier
void vRingbufferReturnItemFromISR(RingbufHandle_t xRingbuffer, void *pvItem, BaseType_t *pxHigherPriorityTaskWoken)
Return a previously-retrieved item to the ring buffer from an ISR.
Note If a split item is retrieved, both parts should be returned by calling this function twice Parameters
· [in] xRingbuffer: Ring buffer the item was retrieved from · [in] pvItem: Item that was received earlier · [out] pxHigherPriorityTaskWoken: Value pointed to will be set to pdTRUE if the
function woke up a higher priority task.
void vRingbufferDelete(RingbufHandle_t xRingbuffer) Delete a ring buffer.
Note This function will not deallocate any memory if the ring buffer was created using xRingbufferCreateStatic(). Deallocation must be done manually be the user.
Parameters · [in] xRingbuffer: Ring buffer to delete
size_t xRingbufferGetMaxItemSize(RingbufHandle_t xRingbuffer) Get maximum size of an item that can be placed in the ring buffer.
This function returns the maximum size an item can have if it was placed in an empty ring buffer.
Note The max item size for a no-split buffer is limited to ((buffer_size/2)-header_size). This limit is imposed

Espressif Systems

1263

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

so that an item of max item size can always be sent to an empty no-split buffer regardless of the internal positions of the bufferns read/write/free pointers. Return Maximum size, in bytes, of an item that can be placed in a ring buffer. Parameters
· [in] xRingbuffer: Ring buffer to query

size_t xRingbufferGetCurFreeSize(RingbufHandle_t xRingbuffer) Get current free size available for an item/data in the buffer.

This gives the real time free space available for an item/data in the ring buffer. This represents the maximum size an item/data can have if it was currently sent to the ring buffer.

Warning This API is not thread safe. So, if multiple threads are accessing the same ring buffer, it is the applicationns responsibility to ensure atomic access to this API and the subsequent Send
Note An empty no-split buffer has a max current free size for an item that is limited to ((buffer_size/2)header_size). See API reference for xRingbufferGetMaxItemSize().
Return Current free size, in bytes, available for an entry Parameters
· [in] xRingbuffer: Ring buffer to query

BaseType_t xRingbufferAddToQueueSetRead(RingbufHandle_t xRingbuffer, QueueSetHandle_t xQueueSet)
Add the ring bufferns read semaphore to a queue set.

The ring bufferns read semaphore indicates that data has been written to the ring buffer. This function adds the ring bufferns read semaphore to a queue set.

Return · pdTRUE on success, pdFALSE otherwise
Parameters · [in] xRingbuffer: Ring buffer to add to the queue set · [in] xQueueSet: Queue set to add the ring bufferns read semaphore to

BaseType_t xRingbufferCanRead(RingbufHandle_t xRingbuffer, QueueSetMemberHandle_t xMember)
Check if the selected queue set member is the ring bufferns read semaphore.

This API checks if queue set member returned from xQueueSelectFromSet() is the read semaphore of this ring buffer. If so, this indicates the ring buffer has items waiting to be retrieved.

Return · pdTRUE when semaphore belongs to ring buffer · pdFALSE otherwise.
Parameters · [in] xRingbuffer: Ring buffer which should be checked · [in] xMember: Member returned from xQueueSelectFromSet

BaseType_t xRingbufferRemoveFromQueueSetRead(RingbufHandle_t xRingbuffer, SetHandle_t xQueueSet)
Remove the ring bufferns read semaphore from a queue set.

Queue-

This specifically removes a ring bufferns read semaphore from a queue set. The read semaphore is used to indicate when data has been written to the ring buffer

Return · pdTRUE on success · pdFALSE otherwise
Parameters · [in] xRingbuffer: Ring buffer to remove from the queue set · [in] xQueueSet: Queue set to remove the ring bufferns read semaphore from

void vRingbufferGetInfo(RingbufHandle_t xRingbuffer, UBaseType_t *uxFree, UBaseType_t *uxRead, UBaseType_t *uxWrite, UBaseType_t *uxAcquire, UBaseType_t *uxItemsWaiting)
Get information about ring buffer status.

Espressif Systems

1264

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Get information of a ring bufferns current status such as free/read/write/acquire pointer positions, and number of items waiting to be retrieved. Arguments can be set to NULL if they are not required.
Parameters · [in] xRingbuffer: Ring buffer to remove from the queue set · [out] uxFree: Pointer use to store free pointer position · [out] uxRead: Pointer use to store read pointer position · [out] uxWrite: Pointer use to store write pointer position · [out] uxAcquire: Pointer use to store acquire pointer position · [out] uxItemsWaiting: Pointer use to store number of items (bytes for byte buffer) waiting to be retrieved
void xRingbufferPrintInfo(RingbufHandle_t xRingbuffer) Debugging function to print the internal pointers in the ring buffer.
Parameters · xRingbuffer: Ring buffer to show
Structures struct xSTATIC_RINGBUFFER
Struct that is equivalent in size to the ring bufferns data structure.
The contents of this struct are not meant to be used directly. This structure is meant to be used when creating a statically allocated ring buffer where this struct is of the exact size required to store a ring bufferns control data structure.
Type Definitions typedef void *RingbufHandle_t
Type by which ring buffers are referenced. For example, a call to xRingbufferCreate() returns a RingbufHandle_t variable that can then be used as a parameter to xRingbufferSend(), xRingbufferReceive(), etc. typedef struct xSTATIC_RINGBUFFER StaticRingbuffer_t Struct that is equivalent in size to the ring bufferns data structure.
The contents of this struct are not meant to be used directly. This structure is meant to be used when creating a statically allocated ring buffer where this struct is of the exact size required to store a ring bufferns control data structure.
Enumerations enum RingbufferType_t
Values:
RINGBUF_TYPE_NOSPLIT = 0 No-split buffers will only store an item in contiguous memory and will never split an item. Each item requires an 8 byte overhead for a header and will always internally occupy a 32-bit aligned size of space.
RINGBUF_TYPE_ALLOWSPLIT Allow-split buffers will split an item into two parts if necessary in order to store it. Each item requires an 8 byte overhead for a header, splitting incurs an extra header. Each item will always internally occupy a 32-bit aligned size of space.
RINGBUF_TYPE_BYTEBUF Byte buffers store data as a sequence of bytes and do not maintain separate items, therefore byte buffers have no overhead. All data is stored as a sequence of byte and any number of bytes can be sent or retrieved each time.
RINGBUF_TYPE_MAX
Hooks API

Espressif Systems

1265

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Header File · components/esp_system/include/esp_freertos_hooks.h

Functions esp_err_t esp_register_freertos_idle_hook_for_cpu(esp_freertos_idle_cb_t new_idle_cb,
UBaseType_t cpuid) Register a callback to be called from the specified corens idle hook. The callback should return true if it should be called by the idle hook once per interrupt (or FreeRTOS tick), and return false if it should be called repeatedly as fast as possible by the idle hook.

Warning Idle callbacks MUST NOT, UNDER ANY CIRCUMSTANCES, CALL A FUNCTION THAT MIGHT BLOCK.
Return · ESP_OK: Callback registered to the specified corens idle hook · ESP_ERR_NO_MEM: No more space on the specified corens idle hook to register callback · ESP_ERR_INVALID_ARG: cpuid is invalid
Parameters · [in] new_idle_cb: Callback to be called · [in] cpuid: id of the core
esp_err_t esp_register_freertos_idle_hook(esp_freertos_idle_cb_t new_idle_cb) Register a callback to the idle hook of the core that calls this function. The callback should return true if it should be called by the idle hook once per interrupt (or FreeRTOS tick), and return false if it should be called repeatedly as fast as possible by the idle hook.

Warning Idle callbacks MUST NOT, UNDER ANY CIRCUMSTANCES, CALL A FUNCTION THAT MIGHT BLOCK.
Return · ESP_OK: Callback registered to the calling corens idle hook · ESP_ERR_NO_MEM: No more space on the calling corens idle hook to register callback
Parameters · [in] new_idle_cb: Callback to be called

esp_err_t esp_register_freertos_tick_hook_for_cpu(esp_freertos_tick_cb_t new_tick_cb,
UBaseType_t cpuid) Register a callback to be called from the specified corens tick hook.

Return · ESP_OK: Callback registered to specified corens tick hook · ESP_ERR_NO_MEM: No more space on the specified corens tick hook to register the callback · ESP_ERR_INVALID_ARG: cpuid is invalid
Parameters · [in] new_tick_cb: Callback to be called · [in] cpuid: id of the core

esp_err_t esp_register_freertos_tick_hook(esp_freertos_tick_cb_t new_tick_cb) Register a callback to be called from the calling corens tick hook.

Return · ESP_OK: Callback registered to the calling corens tick hook · ESP_ERR_NO_MEM: No more space on the calling corens tick hook to register the callback
Parameters · [in] new_tick_cb: Callback to be called

void esp_deregister_freertos_idle_hook_for_cpu(esp_freertos_idle_cb_t
UBaseType_t cpuid) Unregister an idle callback from the idle hook of the specified core.

old_idle_cb,

Parameters · [in] old_idle_cb: Callback to be unregistered · [in] cpuid: id of the core

Espressif Systems

1266

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

void esp_deregister_freertos_idle_hook(esp_freertos_idle_cb_t old_idle_cb) Unregister an idle callback. If the idle callback is registered to the idle hooks of both cores, the idle hook will be unregistered from both cores.

Parameters · [in] old_idle_cb: Callback to be unregistered

void esp_deregister_freertos_tick_hook_for_cpu(esp_freertos_tick_cb_t
UBaseType_t cpuid) Unregister a tick callback from the tick hook of the specified core.

old_tick_cb,

Parameters · [in] old_tick_cb: Callback to be unregistered · [in] cpuid: id of the core

void esp_deregister_freertos_tick_hook(esp_freertos_tick_cb_t old_tick_cb) Unregister a tick callback. If the tick callback is registered to the tick hooks of both cores, the tick hook will be unregistered from both cores.

Parameters · [in] old_tick_cb: Callback to be unregistered

Type Definitions typedef bool (*esp_freertos_idle_cb_t)(void) typedef void (*esp_freertos_tick_cb_t)(void)

2.7.12 Heap Memory Allocation
Stack and Heap
ESP-IDF applications use the common computer architecture patterns of stack (dynamic memory allocated by program control flow) and heap (dynamic memory allocated by function calls), as well as statically allocated memory (allocated at compile time).
Because ESP-IDF is a multi-threaded RTOS environment, each RTOS task has its own stack. By default, each of these stacks is allocated from the heap when the task is created. (See xTaskCreateStatic() for the alternative where stacks are statically allocated.)
Because ESP32-S3 uses multiple types of RAM, it also contains multiple heaps with different capabilities. A capabilities-based memory allocator allows apps to make heap allocations for different purposes.
For most purposes, the standard libc malloc() and free() functions can be used for heap allocation without any special consideration.
However, in order to fully make use of all of the memory types and their characteristics, ESP-IDF also has a capabilities-based heap memory allocator. If you want to have memory with certain properties (for example, DMACapable Memory or executable-memory), you can create an OR-mask of the required capabilities and pass that to heap_caps_malloc().

Memory Capabilities
The ESP32-S3 contains multiple types of RAM:
· DRAM (Data RAM) is memory used to hold data. This is the most common kind of memory accessed as heap.
· IRAM (Instruction RAM) usually holds executable data only. If accessed as generic memory, all accesses must be 32-bit aligned.
· D/IRAM is RAM which can be used as either Instruction or Data RAM.

Espressif Systems

1267

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
For more details on these internal memory types, see Memory Types. Itns also possible to connect external SPI RAM to the ESP32-S3 - external RAM can be integrated into the ESP32-S3n s memory map using the flash cache, and accessed similarly to DRAM. DRAM uses capability MALLOC_CAP_8BIT (accessible in single byte reads and writes). When calling malloc(), the ESP-IDF malloc() implementation internally calls heap_caps_malloc(size, MALLOC_CAP_8BIT) in order to allocate DRAM that is byte-addressable. To test the free DRAM heap size at runtime, call cpp:func:heap_caps_get_free_size(MALLOC_CAP_8BIT). Because malloc uses the capabilities-based allocation system, memory allocated using heap_caps_malloc() can be freed by calling the standard free() function.
Available Heap
DRAM At startup, the DRAM heap contains all data memory which is not statically allocated by the app. Reducing statically allocated buffers will increase the amount of available free heap. To find the amount of statically allocated memory, use the idf.py size command.
Note: At runtime, the available heap DRAM may be less than calculated at compile time, because at startup some memory is allocated from the heap before the FreeRTOS scheduler is started (including memory for the stacks of initial FreeRTOS tasks).

IRAM At startup, the IRAM heap contains all instruction memory which is not used by the app executable code. The idf.py size command can be used to find the amount of IRAM used by the app.
D/IRAM Some memory in the ESP32-S3 is available as either DRAM or IRAM. If memory is allocated from a D/IRAM region, the free heap size for both types of memory will decrease.
Heap Sizes At startup, all ESP-IDF apps log a summary of all heap addresses (and sizes) at level Info: I (252) heap_init: Initializing. RAM available for dynamic allocation: I (259) heap_init: At 3FFAE6E0 len 00001920 (6 KiB): DRAM I (265) heap_init: At 3FFB2EC8 len 0002D138 (180 KiB): DRAM I (272) heap_init: At 3FFE0440 len 00003AE0 (14 KiB): D/IRAM I (278) heap_init: At 3FFE4350 len 0001BCB0 (111 KiB): D/IRAM I (284) heap_init: At 4008944C len 00016BB4 (90 KiB): IRAM
Finding available heap See Heap Information.
Special Capabilities
DMA-Capable Memory Use the MALLOC_CAP_DMA flag to allocate memory which is suitable for use with hardware DMA engines (for example SPI and I2S). This capability flag excludes any external PSRAM.
32-Bit Accessible Memory If a certain memory structure is only addressed in 32-bit units, for example an array of ints or pointers, it can be useful to allocate it with the MALLOC_CAP_32BIT flag. This also allows the allocator to give out IRAM memory; something which it cannt do for a normal malloc() call. This can help to use all the available memory in the ESP32-S3. Memory allocated with MALLOC_CAP_32BIT can only be accessed via 32-bit reads and writes, any other type of access will generate a fatal LoadStoreError exception.

Espressif Systems

1268

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

External SPI Memory When external RAM is enabled, external SPI RAM under 4MiB in size can be allocated using standard malloc calls, or via heap_caps_malloc(MALLOC_CAP_SPIRAM), depending on configuration. See Configuring External RAM for more details.
API Reference - Heap Allocation
Header File
· components/heap/include/esp_heap_caps.h
Functions esp_err_t heap_caps_register_failed_alloc_callback(esp_alloc_failed_hook_t callback)
registers a callback function to be invoked if a memory allocation operation fails
Return ESP_OK if callback was registered. Parameters
· callback: caller defined callback to be invoked void *heap_caps_malloc(size_t size, uint32_t caps)
Allocate a chunk of memory which has the given capabilities.
Equivalent semantics to libc malloc(), for capability-aware memory.
In IDF, malloc(p) is equivalent to heap_caps_malloc(p, MALLOC_CAP_8BIT).
Return A pointer to the memory allocated on success, NULL on failure Parameters
· size: Size, in bytes, of the amount of memory to allocate · caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory to be returned
void heap_caps_free(void *ptr) Free memory previously allocated via heap_caps_malloc() or heap_caps_realloc().
Equivalent semantics to libc free(), for capability-aware memory.
In IDF, free(p) is equivalent to heap_caps_free(p).
Parameters · ptr: Pointer to memory previously returned from heap_caps_malloc() or heap_caps_realloc(). Can be NULL.
void *heap_caps_realloc(void *ptr, size_t size, uint32_t caps) Reallocate memory previously allocated via heap_caps_malloc() or heap_caps_realloc().
Equivalent semantics to libc realloc(), for capability-aware memory.
In IDF, realloc(p, s) is equivalent to heap_caps_realloc(p, s, MALLOC_CAP_8BIT).
mcapsnparameter can be different to the capabilities that any original mptrnwas allocated with. In this way, realloc can be used to omovepa buffer if necessary to ensure it meets a new set of capabilities.
Return Pointer to a new buffer of size msizenwith capabilities mcapsn, or NULL if allocation failed. Parameters
· ptr: Pointer to previously allocated memory, or NULL for a new allocation. · size: Size of the new buffer requested, or 0 to free the buffer. · caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory desired for the new
allocation.
void *heap_caps_aligned_alloc(size_t alignment, size_t size, uint32_t caps) Allocate an aligned chunk of memory which has the given capabilities.
Equivalent semantics to libc aligned_alloc(), for capability-aware memory.
Return A pointer to the memory allocated on success, NULL on failure Parameters
· alignment: How the pointer received needs to be aligned must be a power of two

Espressif Systems

1269

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· size: Size, in bytes, of the amount of memory to allocate · caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory to be returned
void heap_caps_aligned_free(void *ptr) Used to deallocate memory previously allocated with heap_caps_aligned_alloc.
Note This function is deprecated, please consider using heap_caps_free() instead Parameters
· ptr: Pointer to the memory allocated
void *heap_caps_aligned_calloc(size_t alignment, size_t n, size_t size, uint32_t caps) Allocate an aligned chunk of memory which has the given capabilities. The initialized value in the memory is set to zero.
Return A pointer to the memory allocated on success, NULL on failure Parameters
· alignment: How the pointer received needs to be aligned must be a power of two · n: Number of continuing chunks of memory to allocate · size: Size, in bytes, of a chunk of memory to allocate · caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory to be returned
void *heap_caps_calloc(size_t n, size_t size, uint32_t caps) Allocate a chunk of memory which has the given capabilities. The initialized value in the memory is set to zero.
Equivalent semantics to libc calloc(), for capability-aware memory.
In IDF, calloc(p) is equivalent to heap_caps_calloc(p, MALLOC_CAP_8BIT).
Return A pointer to the memory allocated on success, NULL on failure Parameters
· n: Number of continuing chunks of memory to allocate · size: Size, in bytes, of a chunk of memory to allocate · caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory to be returned
size_t heap_caps_get_total_size(uint32_t caps) Get the total size of all the regions that have the given capabilities.
This function takes all regions capable of having the given capabilities allocated in them and adds up the total space they have.
Return total size in bytes Parameters
· caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory
size_t heap_caps_get_free_size(uint32_t caps) Get the total free size of all the regions that have the given capabilities.
This function takes all regions capable of having the given capabilities allocated in them and adds up the free space they have.
Note Note that because of heap fragmentation it is probably not possible to allocate a single block of memory of this size. Use heap_caps_get_largest_free_block() for this purpose.
Return Amount of free bytes in the regions Parameters
· caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory
size_t heap_caps_get_minimum_free_size(uint32_t caps) Get the total minimum free memory of all regions with the given capabilities.
This adds all the low watermarks of the regions capable of delivering the memory with the given capabilities.
Note Note the result may be less than the global all-time minimum available heap of this kind, as olow watermarkspare tracked per-region. Individual regionsnheaps may have reached theirolow watermarksp at different points in time. However, this result still gives aoworst casepindication for all-time minimum free heap.
Return Amount of free bytes in the regions

Espressif Systems

1270

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Parameters · caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory
size_t heap_caps_get_largest_free_block(uint32_t caps) Get the largest free block of memory able to be allocated with the given capabilities.
Returns the largest value of s for which heap_caps_malloc(s, caps) will succeed.
Return Size of the largest free block in bytes. Parameters
· caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory
void heap_caps_get_info(multi_heap_info_t *info, uint32_t caps) Get heap info for all regions with the given capabilities.
Calls multi_heap_info() on all heaps which share the given capabilities. The information returned is an aggregate across all matching heaps. The meanings of fields are the same as defined for multi_heap_info_t, except that minimum_free_bytes has the same caveats described in heap_caps_get_minimum_free_size().
Parameters · info: Pointer to a structure which will be filled with relevant heap metadata. · caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory
void heap_caps_print_heap_info(uint32_t caps) Print a summary of all memory with the given capabilities.
Calls multi_heap_info on all heaps which share the given capabilities, and prints a two-line summary for each, then a total summary.
Parameters · caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory
bool heap_caps_check_integrity_all(bool print_errors) Check integrity of all heap memory in the system.
Calls multi_heap_check on all heaps. Optionally print errors if heaps are corrupt.
Calling this function is equivalent to calling heap_caps_check_integrity with the caps argument set to MALLOC_CAP_INVALID.
Return True if all heaps are valid, False if at least one heap is corrupt. Parameters
· print_errors: Print specific errors if heap corruption is found.
bool heap_caps_check_integrity(uint32_t caps, bool print_errors) Check integrity of all heaps with the given capabilities.
Calls multi_heap_check on all heaps which share the given capabilities. Optionally print errors if the heaps are corrupt.
See also heap_caps_check_integrity_all to check all heap memory in the system and heap_caps_check_integrity_addr to check memory around a single address.
Return True if all heaps are valid, False if at least one heap is corrupt. Parameters
· caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory · print_errors: Print specific errors if heap corruption is found.
bool heap_caps_check_integrity_addr(intptr_t addr, bool print_errors) Check integrity of heap memory around a given address.
This function can be used to check the integrity of a single region of heap memory, which contains the given address.
This can be useful if debugging heap integrity for corruption at a known address, as it has a lower overhead than checking all heap regions. Note that if the corrupt address moves around between runs (due to timing or other factors) then this approach wonnt work, and you should call heap_caps_check_integrity or heap_caps_check_integrity_all instead.

Espressif Systems

1271

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Note The entire heap region around the address is checked, not only the adjacent heap blocks. Return True if the heap containing the specified address is valid, False if at least one heap is corrupt or the
address doesnnt belong to a heap region. Parameters
· addr: Address in memory. Check for corruption in region containing this address. · print_errors: Print specific errors if heap corruption is found.
void heap_caps_malloc_extmem_enable(size_t limit) Enable malloc() in external memory and set limit below which malloc() attempts are placed in internal memory.
When external memory is in use, the allocation strategy is to initially try to satisfy smaller allocation requests with internal memory and larger requests with external memory. This sets the limit between the two, as well as generally enabling allocation in external memory.
Parameters · limit: Limit, in bytes.
void *heap_caps_malloc_prefer(size_t size, size_t num, ...) Allocate a chunk of memory as preference in decreasing order.
Attention The variable parameters are bitwise OR of MALLOC_CAP_* flags indicating the type of memory. This API prefers to allocate memory with the first parameter. If failed, allocate memory with the next parameter. It will try in this order until allocating a chunk of memory successfully or fail to allocate memories with any of the parameters.
Return A pointer to the memory allocated on success, NULL on failure Parameters
· size: Size, in bytes, of the amount of memory to allocate · num: Number of variable parameters
void *heap_caps_realloc_prefer(void *ptr, size_t size, size_t num, ...) Reallocate a chunk of memory as preference in decreasing order.
Return Pointer to a new buffer of size msizen, or NULL if allocation failed. Parameters
· ptr: Pointer to previously allocated memory, or NULL for a new allocation. · size: Size of the new buffer requested, or 0 to free the buffer. · num: Number of variable paramters
void *heap_caps_calloc_prefer(size_t n, size_t size, size_t num, ...) Allocate a chunk of memory as preference in decreasing order.
Return A pointer to the memory allocated on success, NULL on failure Parameters
· n: Number of continuing chunks of memory to allocate · size: Size, in bytes, of a chunk of memory to allocate · num: Number of variable paramters
void heap_caps_dump(uint32_t caps) Dump the full structure of all heaps with matching capabilities.
Prints a large amount of output to serial (because of locking limitations, the output bypasses stdout/stderr). For each (variable sized) block in each matching heap, the following output is printed on a single line:
· Block address (the data buffer returned by malloc is 4 bytes after this if heap debugging is set to Basic, or 8 bytes otherwise).
· Data size (the data size may be larger than the size requested by malloc, either due to heap fragmentation or because of heap debugging level).
· Address of next block in the heap. · If the block is free, the address of the next free block is also printed.
Parameters · caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory
void heap_caps_dump_all(void) Dump the full structure of all heaps.

Espressif Systems

1272

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Covers all registered heaps. Prints a large amount of output to serial.
Output is the same as for heap_caps_dump.
size_t heap_caps_get_allocated_size(void *ptr) Return the size that a particular pointer was allocated with.
Note The app will crash with an assertion failure if the pointer is not valid. Return Size of the memory allocated at this block. Parameters
· ptr: Pointer to currently allocated heap memory. Must be a pointer value previously returned by heap_caps_malloc, malloc, calloc, etc. and not yet freed.
Macros MALLOC_CAP_EXEC
Flags to indicate the capabilities of the various memory systems.
Memory must be able to run executable code MALLOC_CAP_32BIT
Memory must allow for aligned 32-bit data accesses.
MALLOC_CAP_8BIT Memory must allow for 8/16/l-bit data accesses.
MALLOC_CAP_DMA Memory must be able to accessed by DMA.
MALLOC_CAP_PID2 Memory must be mapped to PID2 memory space (PIDs are not currently used)
MALLOC_CAP_PID3 Memory must be mapped to PID3 memory space (PIDs are not currently used)
MALLOC_CAP_PID4 Memory must be mapped to PID4 memory space (PIDs are not currently used)
MALLOC_CAP_PID5 Memory must be mapped to PID5 memory space (PIDs are not currently used)
MALLOC_CAP_PID6 Memory must be mapped to PID6 memory space (PIDs are not currently used)
MALLOC_CAP_PID7 Memory must be mapped to PID7 memory space (PIDs are not currently used)
MALLOC_CAP_SPIRAM Memory must be in SPI RAM.
MALLOC_CAP_INTERNAL Memory must be internal; specifically it should not disappear when flash/spiram cache is switched off.
MALLOC_CAP_DEFAULT Memory can be returned in a non-capability-specific memory allocation (e.g. malloc(), calloc()) call.
MALLOC_CAP_IRAM_8BIT Memory must be in IRAM and allow unaligned access.
MALLOC_CAP_RETENTION
MALLOC_CAP_RTCRAM Memory must be in RTC fast memory.
MALLOC_CAP_INVALID Memory cannt be used / list end marker.

Espressif Systems

1273

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Type Definitions typedef void (*esp_alloc_failed_hook_t)(size_t size, uint32_t caps, const char *func-
tion_name) callback called when an allocation operation fails, if registered Parameters
· size: in bytes of failed allocation · caps: capabilities requested of failed allocation · function_name: function which generated the failure
Thread Safety Heap functions are thread safe, meaning they can be called from different tasks simultaneously without any limitations. It is technically possible to call malloc, free, and related functions from interrupt handler (ISR) context. However this is not recommended, as heap function calls may delay other interrupts. It is strongly recommended to refactor applications so that any buffers used by an ISR are pre-allocated outside of the ISR. Support for calling heap functions from ISRs may be removed in a future update.
Heap Tracing & Debugging
The following features are documented on the Heap Memory Debugging page: · Heap Information (free space, etc.) · Heap Corruption Detection · Heap Tracing (memory leak detection, monitoring, etc.)
API Reference - Initialisation
Header File · components/heap/include/esp_heap_caps_init.h
Functions void heap_caps_init(void)
Initialize the capability-aware heap allocator. This is called once in the IDF startup code. Do not call it at other times. void heap_caps_enable_nonos_stack_heaps(void) Enable heap(s) in memory regions where the startup stacks are located. On startup, the pro/app CPUs have a certain memory region they use as stack, so we cannot do allocations in the regions these stack frames are. When FreeRTOS is completely started, they do not use that memory anymore and heap(s) there can be enabled. esp_err_t heap_caps_add_region(intptr_t start, intptr_t end) Add a region of memory to the collection of heaps at runtime. Most memory regions are defined in soc_memory_layout.c for the SoC, and are registered via heap_caps_init(). Some regions cannt be used immediately and are later enabled via heap_caps_enable_nonos_stack_heaps(). Call this function to add a region of memory to the heap at some later time. This function does not consider any of the oreservedpregions or other data in soc_memory_layout, caller needs to consider this themselves. All memory within the region specified by start & end parameters must be otherwise unused. The capabilities of the newly registered memory will be determined by the start address, as looked up in the regions specified in soc_memory_layout.c. Use heap_caps_add_region_with_caps() to register a region with custom capabilities.

Espressif Systems

1274

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return ESP_OK on success, ESP_ERR_INVALID_ARG if a parameter is invalid, ESP_ERR_NOT_FOUND if the specified start address doesnnt reside in a known region, or any error returned by heap_caps_add_region_with_caps().
Parameters · start: Start address of new region. · end: End address of new region.
esp_err_t heap_caps_add_region_with_caps(const uint32_t caps[], intptr_t start, intptr_t end) Add a region of memory to the collection of heaps at runtime, with custom capabilities.
Similar to heap_caps_add_region(), only custom memory capabilities are specified by the caller.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if a parameter is invalid · ESP_ERR_NO_MEM if no memory to register new heap. · ESP_ERR_INVALID_SIZE if the memory region is too small to fit a heap · ESP_FAIL if region overlaps the start and/or end of an existing region
Parameters · caps: Ordered array of capability masks for the new region, in order of priority. Must have length SOC_MEMORY_TYPE_NO_PRIOS. Does not need to remain valid after the call returns. · start: Start address of new region. · end: End address of new region.
Implementation Notes
Knowledge about the regions of memory in the chip comes from the osocpcomponent, which contains memory layout information for the chip, and the different capabilities of each region. Each regionns capabilities are prioritised, so that (for example) dedicated DRAM and IRAM regions will be used for allocations ahead of the more versatile D/IRAM regions.
Each contiguous region of memory contains its own memory heap. The heaps are created using the multi_heap functionality. multi_heap allows any contiguous region of memory to be used as a heap.
The heap capabilities allocator uses knowledge of the memory regions to initialize each individual heap. Allocation functions in the heap capabilities API will find the most appropriate heap for the allocation (based on desired capabilities, available space, and preferences for each regionns use) and then calling multi_heap_malloc() or multi_heap_calloc() for the heap situated in that particular region.
Calling free() involves finding the particular heap corresponding to the freed address, and then calling multi_heap_free() on that particular multi_heap instance.
API Reference - Multi Heap API
(Note: The multi heap API is used internally by the heap capabilities allocator. Most IDF programs will never need to call this API directly.)
Header File
· components/heap/include/multi_heap.h
Functions void *multi_heap_aligned_alloc(multi_heap_handle_t heap, size_t size, size_t alignment)
allocate a chunk of memory with specific alignment
Return pointer to the memory allocated, NULL on failure Parameters
· heap: Handle to a registered heap. · size: size in bytes of memory chunk

Espressif Systems

1275

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· alignment: how the memory must be aligned void *multi_heap_malloc(multi_heap_handle_t heap, size_t size)
malloc() a buffer in a given heap
Semantics are the same as standard malloc(), only the returned buffer will be allocated in the specified heap.
Return Pointer to new memory, or NULL if allocation fails. Parameters
· heap: Handle to a registered heap. · size: Size of desired buffer.
void multi_heap_aligned_free(multi_heap_handle_t heap, void *p) free() a buffer aligned in a given heap.
Note This function is deprecated, consider using multi_heap_free() instead Parameters
· heap: Handle to a registered heap. · p: NULL, or a pointer previously returned from multi_heap_aligned_alloc() for the same heap.
void multi_heap_free(multi_heap_handle_t heap, void *p) free() a buffer in a given heap.
Semantics are the same as standard free(), only the argument mpnmust be NULL or have been allocated in the specified heap.
Parameters · heap: Handle to a registered heap. · p: NULL, or a pointer previously returned from multi_heap_malloc() or multi_heap_realloc() for the same heap.
void *multi_heap_realloc(multi_heap_handle_t heap, void *p, size_t size) realloc() a buffer in a given heap.
Semantics are the same as standard realloc(), only the argument mpnmust be NULL or have been allocated in the specified heap.
Return New buffer of msizencontaining contents of mpn, or NULL if reallocation failed. Parameters
· heap: Handle to a registered heap. · p: NULL, or a pointer previously returned from multi_heap_malloc() or multi_heap_realloc() for
the same heap. · size: Desired new size for buffer.
size_t multi_heap_get_allocated_size(multi_heap_handle_t heap, void *p) Return the size that a particular pointer was allocated with.
Return Size of the memory allocated at this block. May be more than the original size argument, due to padding and minimum block sizes.
Parameters · heap: Handle to a registered heap. · p: Pointer, must have been previously returned from multi_heap_malloc() or multi_heap_realloc() for the same heap.
multi_heap_handle_t multi_heap_register(void *start, size_t size) Register a new heap for use.
This function initialises a heap at the specified address, and returns a handle for future heap operations.
There is no equivalent function for deregistering a heap - if all blocks in the heap are free, you can immediately start using the memory for other purposes.
Return Handle of a new heap ready for use, or NULL if the heap region was too small to be initialised. Parameters
· start: Start address of the memory to use for a new heap. · size: Size (in bytes) of the new heap.

Espressif Systems

1276

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
void multi_heap_set_lock(multi_heap_handle_t heap, void *lock) Associate a private lock pointer with a heap.
The lock argument is supplied to the MULTI_HEAP_LOCK() and MULTI_HEAP_UNLOCK() macros, defined in multi_heap_platform.h.
The lock in question must be recursive.
When the heap is first registered, the associated lock is NULL.
Parameters · heap: Handle to a registered heap. · lock: Optional pointer to a locking structure to associate with this heap.
void multi_heap_dump(multi_heap_handle_t heap) Dump heap information to stdout.
For debugging purposes, this function dumps information about every block in the heap to stdout.
Parameters · heap: Handle to a registered heap.
bool multi_heap_check(multi_heap_handle_t heap, bool print_errors) Check heap integrity.
Walks the heap and checks all heap data structures are valid. If any errors are detected, an error-specific message can be optionally printed to stderr. Print behaviour can be overridden at compile time by defining MULTI_CHECK_FAIL_PRINTF in multi_heap_platform.h.
Return true if heap is valid, false otherwise. Parameters
· heap: Handle to a registered heap. · print_errors: If true, errors will be printed to stderr.
size_t multi_heap_free_size(multi_heap_handle_t heap) Return free heap size.
Returns the number of bytes available in the heap.
Equivalent to the total_free_bytes member returned by multi_heap_get_heap_info().
Note that the heap may be fragmented, so the actual maximum size for a single malloc() may be lower. To know this size, see the largest_free_block member returned by multi_heap_get_heap_info().
Return Number of free bytes. Parameters
· heap: Handle to a registered heap.
size_t multi_heap_minimum_free_size(multi_heap_handle_t heap) Return the lifetime minimum free heap size.
Equivalent to the minimum_free_bytes member returned by multi_heap_get_info().
Returns the lifetimeolow watermarkpof possible values returned from multi_free_heap_size(), for the specified heap.
Return Number of free bytes. Parameters
· heap: Handle to a registered heap.
void multi_heap_get_info(multi_heap_handle_t heap, multi_heap_info_t *info) Return metadata about a given heap.
Fills a multi_heap_info_t structure with information about the specified heap.
Parameters · heap: Handle to a registered heap. · info: Pointer to a structure to fill with heap metadata.

Espressif Systems

1277

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Structures struct multi_heap_info_t
Structure to access heap metadata via multi_heap_get_info.

Public Members
size_t total_free_bytes Total free bytes in the heap. Equivalent to multi_free_heap_size().
size_t total_allocated_bytes Total bytes allocated to data in the heap.
size_t largest_free_block Size of the largest free block in the heap. This is the largest malloc-able size.
size_t minimum_free_bytes Lifetime minimum free heap size. Equivalent to multi_minimum_free_heap_size().
size_t allocated_blocks Number of (variable size) blocks allocated in the heap.
size_t free_blocks Number of (variable size) free blocks in the heap.
size_t total_blocks Total number of (variable size) blocks in the heap.

Type Definitions typedef struct multi_heap_info *multi_heap_handle_t
Opaque handle to a registered heap.

2.7.13 Heap Memory Debugging
Overview
ESP-IDF integrates tools for requesting heap information, detecting heap corruption, and tracing memory leaks. These can help track down memory-related bugs. For general information about the heap memory allocator, see the Heap Memory Allocation page.

Heap Information
To obtain information about the state of the heap:
· xPortGetFreeHeapSize() is a FreeRTOS function which returns the number of free bytes in the (data memory) heap. This is equivalent to calling heap_caps_get_free_size(MALLOC_CAP_8BIT).
· heap_caps_get_free_size() can also be used to return the current free memory for different memory capabilities.
· heap_caps_get_largest_free_block() can be used to return the largest free block in the heap. This is the largest single allocation which is currently possible. Tracking this value and comparing to total free heap allows you to detect heap fragmentation.
· xPortGetMinimumEverFreeHeapSize() and the related heap_caps_get_minimum_free_size() can be used to track the heap olow watermarkpsince boot.
· heap_caps_get_info() returns a multi_heap_info_t structure which contains the information from the above functions, plus some additional heap-specific data (number of allocations, etc.).
· heap_caps_print_heap_info() prints a summary to stdout of the information returned by heap_caps_get_info().
· heap_caps_dump() and heap_caps_dump_all() will output detailed information about the structure of each block in the heap. Note that this can be large amount of output.

Espressif Systems

1278

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Heap Corruption Detection
Heap corruption detection allows you to detect various types of heap memory errors:
· Out of bounds writes & buffer overflow. · Writes to freed memory. · Reads from freed or uninitialized memory,
Assertions The heap implementation (multi_heap.c, etc.) includes a lot of assertions which will fail if the heap memory is corrupted. To detect heap corruption most effectively, ensure that assertions are enabled in the project configuration menu under Compiler options -> CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL.
If a heap integrity assertion fails, a line will be printed like CORRUPT HEAP: multi_heap.c:225 detected at 0x3ffbb71c. The memory address which is printed is the address of the heap structure which has corrupt content.
Itns also possible to manually check heap integrity by calling heap_caps_check_integrity_all() or related functions. This function checks all of requested heap memory for integrity, and can be used even if assertions are disabled. If the integrity check prints an error, it will also contain the address(es) of corrupt heap structures.
Memory Allocation Failed Hook Users can use heap_caps_register_failed_alloc_callback() to register a callback that will be invoked every time an allocation operation fails.
Additionally, users can enable the generation of a system abort if an allocation operation fails by following the steps below: - In the project configuration menu, navigate to Component config -> Heap Memory Debugging and select Abort if memory allocation fails option (see CONFIG_HEAP_ABORT_WHEN_ALLOCATION_FAILS).
The example below shows how to register an allocation failure callback:
#include "esp_heap_caps.h"
void heap_caps_alloc_failed_hook(size_t requested_size, uint32_t caps, const char *function_name) {
printf("%s was called but failed to allocate %d bytes with 0x%X capabilities. \n ",function_name, requested_size, caps); }
void app_main() {
... esp_err_t error = heap_caps_register_failed_alloc_callback(heap_caps_alloc_ failed_hook); ... void *ptr = heap_caps_malloc(allocation_size, MALLOC_CAP_DEFAULT); ... }

Finding Heap Corruption Memory corruption can be one of the hardest classes of bugs to find and fix, as one area of memory can be corrupted from a totally different place. Some tips:

· A crash with a CORRUPT HEAP: message will usually include a stack trace, but this stack trace is rarely

useful. The crash is the symptom of memory corruption when the system realises the heap is corrupt, but

usually the corruption happened elsewhere and earlier in time.

· Increasing the Heap memory debugging Configuration level tooLight impactporoComprehensivepcan give

you a more accurate message with the first corrupt memory address.

· Adding

regular

calls

to

heap_caps_check_integrity_all()

or

heap_caps_check_integrity_addr() in your code will help you pin down the exact time

Espressif Systems

1279

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
that the corruption happened. You can move these checks around to oclose in onpthe section of code that corrupted the heap. · Based on the memory address which is being corrupted, you can use JTAG debugging to set a watchpoint on this address and have the CPU halt when it is written to. · If you donnt have JTAG, but you do know roughly when the corruption happens, then you can set a watchpoint in software just beforehand via esp_cpu_set_watchpoint(). A fatal exception will occur when the watchpoint triggers. The following is an example of how to use the function esp_cpu_set_watchpoint(0, (void *)addr, 4, ESP_WATCHPOINT_STORE). Note that watchpoints are per-CPU and are set on the current running CPU only, so if you donnt know which CPU is corrupting memory then you will need to call this function on both CPUs. · For buffer overflows, heap tracing in HEAP_TRACE_ALL mode lets you see which callers are allocating which addresses from the heap. See Heap Tracing To Find Heap Corruption for more details. If you can find the function which allocates memory with an address immediately before the address which is corrupted, this will probably be the function which overflows the buffer. · Calling heap_caps_dump() or heap_caps_dump_all() can give an indication of what heap blocks are surrounding the corrupted region and may have overflowed/underflowed/etc.
Configuration Temporarily increasing the heap corruption detection level can give more detailed information about heap corruption errors.
In the project configuration menu, under Component config there is a menu Heap memory debugging. The setting CONFIG_HEAP_CORRUPTION_DETECTION can be set to one of three levels:
Basic (no poisoning) This is the default level. No special heap corruption features are enabled, but provided assertions are enabled (the default configuration) then a heap corruption error will be printed if any of the heapns internal data structures appear overwritten or corrupted. This usually indicates a buffer overrun or out of bounds write.
If assertions are enabled, an assertion will also trigger if a double-free occurs (the same memory is freed twice).
Calling heap_caps_check_integrity() in Basic mode will check the integrity of all heap structures, and print errors if any appear to be corrupted.
Light Impact At this level, heap memory is additionally opoisonedpwith head and tail ocanary bytespbefore and after each block which is allocated. If an application writes outside the bounds of allocated buffers, the canary bytes will be corrupted and the integrity check will fail.
The head canary word is 0xABBA1234 (3412BAAB in byte order), and the tail canary word is 0xBAAD5678 (7856ADBA in byte order).
oBasicpheap corruption checks can also detect most out of bounds writes, but this setting is more precise as even a single byte overrun can be detected. With Basic heap checks, the number of overrun bytes before a failure is detected will depend on the properties of the heap.
Enabling oLight Impactpchecking increases memory usage, each individual allocation will use 9 to 12 additional bytes of memory (depending on alignment).
Each time free() is called in Light Impact mode, the head and tail canary bytes of the buffer being freed are checked against the expected values.
When heap_caps_check_integrity() is called, all allocated blocks of heap memory have their canary bytes checked against the expected values.
In both cases, the check is that the first 4 bytes of an allocated block (before the buffer returned to the user) should be the word 0xABBA1234. Then the last 4 bytes of the allocated block (after the buffer returned to the user) should be the word 0xBAAD5678.
Different values usually indicate buffer underrun or overrun, respectively.

Espressif Systems

1280

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Comprehensive This level incorporates the olight impactpdetection features plus additional checks for uninitialised-access and use-after-free bugs. In this mode, all freshly allocated memory is filled with the pattern 0xCE, and all freed memory is filled with the pattern 0xFE.
Enabling oComprehensivepdetection has a substantial runtime performance impact (as all memory needs to be set to the allocation patterns each time a malloc/free completes, and the memory also needs to be checked each time.) However, it allows easier detection of memory corruption bugs which are much more subtle to find otherwise. It is recommended to only enable this mode when debugging, not in production.

Crashes in Comprehensive Mode If an application crashes reading/writing an address related to 0xCECECECE in Comprehensive mode, this indicates it has read uninitialized memory. The application should be changed to either use calloc() (which zeroes memory), or initialize the memory before using it. The value 0xCECECECE may also be seen in stack-allocated automatic variables, because in IDF most task stacks are originally allocated from the heap and in C stack memory is uninitialized by default.
If an application crashes and the exception register dump indicates that some addresses or values were 0xFEFEFEFE, this indicates it is reading heap memory after it has been freed (a ouse after free bugp.) The application should be changed to not access heap memory after it has been freed.
If a call to malloc() or realloc() causes a crash because it expected to find the pattern 0xFEFEFEFE in free memory and a different pattern was found, then this indicates the app has a use-after-free bug where it is writing to memory which has already been freed.

Manual Heap Checks in Comprehensive Mode Calls to heap_caps_check_integrity() may print errors relating to 0xFEFEFEFE, 0xABBA1234 or 0xBAAD5678. In each case the checker is expecting to find a given pattern, and will error out if this is not found:
· For free heap blocks, the checker expects to find all bytes set to 0xFE. Any other values indicate a use-after-free bug where free memory has been incorrectly overwritten.
· For allocated heap blocks, the behaviour is the same as for Light Impact mode. The canary bytes 0xABBA1234 and 0xBAAD5678 are checked at the head and tail of each allocated buffer, and any variation indicates a buffer overrun/underrun.

Heap Task Tracking
Heap Task Tracking can be used to get per task info for heap memory allocation. Application has to specify the heap capabilities for which the heap allocation is to be tracked. Example code is provided in system/heap_task_tracking

Heap Tracing
Heap Tracing allows tracing of code which allocates/frees memory. Two tracing modes are supported:
· Standalone. In this mode trace data are kept on-board, so the size of gathered information is limited by the buffer assigned for that purposes. Analysis is done by the on-board code. There are a couple of APIs available for accessing and dumping collected info.
· Host-based. This mode does not have the limitation of the standalone mode, because trace data are sent to the host over JTAG connection using app_trace library. Later on they can be analysed using special tools.
Heap tracing can perform two functions:
· Leak checking: find memory which is allocated and never freed. · Heap use analysis: show all functions that are allocating/freeing memory while the trace is running.

How To Diagnose Memory Leaks If you suspect a memory leak, the first step is to figure out which part of the program is leaking memory. Use the xPortGetFreeHeapSize(), heap_caps_get_free_size(), or related functions to track memory use over the life of the application. Try to narrow the leak down to a single function or sequence of functions where free memory always decreases and never recovers.

Espressif Systems

1281

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Standalone Mode Once younve identified the code which you think is leaking:
· In the project configuration menu, navigate to Component settings -> Heap Memory Debugging -> Heap tracing and select Standalone option (see CONFIG_HEAP_TRACING_DEST).
· Call the function heap_trace_init_standalone() early in the program, to register a buffer which can be used to record the memory trace.
· Call the function heap_trace_start() to begin recording all mallocs/frees in the system. Call this immediately before the piece of code which you suspect is leaking memory.
· Call the function heap_trace_stop() to stop the trace once the suspect piece of code has finished executing.
· Call the function heap_trace_dump() to dump the results of the heap trace.
An example:
#include "esp_heap_trace.h"
#define NUM_RECORDS 100 static heap_trace_record_t trace_record[NUM_RECORDS]; // This buffer must be in internal RAM
...
void app_main() {
... ESP_ERROR_CHECK( heap_trace_init_standalone(trace_record, NUM_RECORDS) ); ... }
void some_function() {
ESP_ERROR_CHECK( heap_trace_start(HEAP_TRACE_LEAKS) );
do_something_you_suspect_is_leaking();
ESP_ERROR_CHECK( heap_trace_stop() ); heap_trace_dump(); ... }
The output from the heap trace will look something like this:
2 allocations trace (100 entry buffer) 32 bytes (@ 0x3ffaf214) allocated CPU 0 ccount 0x2e9b7384 caller 0x400d276d:0x400d27c1 0x400d276d: leak_some_memory at /path/to/idf/examples/get-started/blink/main/./ blink.c:27
0x400d27c1: blink_task at /path/to/idf/examples/get-started/blink/main/./blink.c:52
8 bytes (@ 0x3ffaf804) allocated CPU 0 ccount 0x2e9b79c0 caller 0x400d2776:0x400d27c1 0x400d2776: leak_some_memory at /path/to/idf/examples/get-started/blink/main/./ blink.c:29
0x400d27c1: blink_task at /path/to/idf/examples/get-started/blink/main/./blink.c:52
40 bytes 'leaked' in trace (2 allocations) total allocations 2 total frees 0
(Above example output is using IDF Monitor to automatically decode PC addresses to their source files & line number.)
The first line indicates how many allocation entries are in the buffer, compared to its total size.

Espressif Systems

1282

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
In HEAP_TRACE_LEAKS mode, for each traced memory allocation which has not already been freed a line is printed with:
· XX bytes is the number of bytes allocated · @ 0x... is the heap address returned from malloc/calloc. · CPU x is the CPU (0 or 1) running when the allocation was made. · ccount 0x... is the CCOUNT (CPU cycle count) register value when the allocation was mode. Is different
for CPU 0 vs CPU 1. · caller 0x... gives the call stack of the call to malloc()/free(), as a list of PC addresses. These can be
decoded to source files and line numbers, as shown above.
The depth of the call stack recorded for each trace entry can be configured in the project configuration menu, under Heap Memory Debugging -> Enable heap tracing -> Heap tracing stack depth. Up to 10 stack frames can be recorded for each allocation (the default is 2). Each additional stack frame increases the memory usage of each heap_trace_record_t record by eight bytes.
Finally, the total number of mleakednbytes (bytes allocated but not freed while trace was running) is printed, and the total number of allocations this represents.
A warning will be printed if the trace buffer was not large enough to hold all the allocations which happened. If you see this warning, consider either shortening the tracing period or increasing the number of records in the trace buffer.
Host-Based Mode Once younve identified the code which you think is leaking:
· In the project configuration menu, navigate to Component settings -> Heap Memory Debugging -> CONFIG_HEAP_TRACING_DEST and select Host-Based.
· In the project configuration menu, navigate to Component settings -> Application Level Tracing -> CONFIG_APPTRACE_DESTINATION and select Trace memory.
· In the project configuration menu, navigate to Component settings -> Application Level Tracing -> FreeRTOS SystemView Tracing and enable CONFIG_APPTRACE_SV_ENABLE.
· Call the function heap_trace_init_tohost() early in the program, to initialize JTAG heap tracing module.
· Call the function heap_trace_start() to begin recording all mallocs/frees in the system. Call this immediately before the piece of code which you suspect is leaking memory. In host-based mode, the argument to this function is ignored, and the heap tracing module behaves like HEAP_TRACE_ALL was passed: all allocations and deallocations are sent to the host.
· Call the function heap_trace_stop() to stop the trace once the suspect piece of code has finished executing.
An example:
#include "esp_heap_trace.h"
...
void app_main() {
... ESP_ERROR_CHECK( heap_trace_init_tohost() ); ... }
void some_function() {
ESP_ERROR_CHECK( heap_trace_start(HEAP_TRACE_LEAKS) );
do_something_you_suspect_is_leaking();
ESP_ERROR_CHECK( heap_trace_stop() ); ... }

Espressif Systems

1283

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

To gather and analyse heap trace do the following on the host:
1. Build the program and download it to the target as described in Getting Started Guide. 2. Run OpenOCD (see JTAG Debugging).
Note: In order to use this feature you need OpenOCD version v0.10.0-esp32-20181105 or later.
3. You can use GDB to start and/or stop tracing automatically. To do this you need to prepare special gdbinit file:
target remote :3333
mon reset halt flushregs
tb heap_trace_start commands mon esp sysview start file:///tmp/heap.svdat c end
tb heap_trace_stop commands mon esp sysview stop end
c
Using this file GDB will connect to the target, reset it, and start tracing when program hits breakpoint at heap_trace_start(). Trace data will be saved to /tmp/heap_log.svdat. Tracing will be stopped when program hits breakpoint at heap_trace_stop().
4. Run GDB using the following command xtensa-esp32s3-elf-gdb -x gdbinit </path/to/ program/elf>
5. Quit GDB when program stops at heap_trace_stop(). Trace data are saved in /tmp/heap.svdat 6. Run processing script $IDF_PATH/tools/esp_app_trace/sysviewtrace_proc.py -p -b
</path/to/program/elf> /tmp/heap_log.svdat
The output from the heap trace will look something like this:
Parse trace from '/tmp/heap.svdat'... Stop parsing trace. (Timeout 0.000000 sec while reading 1 bytes!) Process events from '['/tmp/heap.svdat']'... [0.002244575] HEAP: Allocated 1 bytes @ 0x3ffaffd8 from task "alloc" on core 0 by: /home/user/projects/esp/esp-idf/examples/system/sysview_tracing_heap_log/main/ sysview_heap_log.c:47 /home/user/projects/esp/esp-idf/components/freertos/port.c:355 (discriminator 1)
[0.002258425] HEAP: Allocated 2 bytes @ 0x3ffaffe0 from task "alloc" on core 0 by: /home/user/projects/esp/esp-idf/examples/system/sysview_tracing_heap_log/main/ sysview_heap_log.c:48 /home/user/projects/esp/esp-idf/components/freertos/port.c:355 (discriminator 1)
[0.002563725] HEAP: Freed bytes @ 0x3ffaffe0 from task "free" on core 0 by: /home/user/projects/esp/esp-idf/examples/system/sysview_tracing_heap_log/main/ sysview_heap_log.c:31 (discriminator 9) /home/user/projects/esp/esp-idf/components/freertos/port.c:355 (discriminator 1)
[0.002782950] HEAP: Freed bytes @ 0x3ffb40b8 from task "main" on core 0 by: /home/user/projects/esp/esp-idf/components/freertos/tasks.c:4590 /home/user/projects/esp/esp-idf/components/freertos/tasks.c:4590
(continues on next page)

Espressif Systems

1284

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page)

[0.002798700] HEAP: Freed bytes @ 0x3ffb50bc from task "main" on core 0 by: /home/user/projects/esp/esp-idf/components/freertos/tasks.c:4590 /home/user/projects/esp/esp-idf/components/freertos/tasks.c:4590

[0.102436025] HEAP: Allocated 2 bytes @ 0x3ffaffe0 from task "alloc" on core 0 by: /home/user/projects/esp/esp-idf/examples/system/sysview_tracing_heap_log/main/ sysview_heap_log.c:47 /home/user/projects/esp/esp-idf/components/freertos/port.c:355 (discriminator 1)

[0.102449800] HEAP: Allocated 4 bytes @ 0x3ffaffe8 from task "alloc" on core 0 by: /home/user/projects/esp/esp-idf/examples/system/sysview_tracing_heap_log/main/ sysview_heap_log.c:48 /home/user/projects/esp/esp-idf/components/freertos/port.c:355 (discriminator 1)

[0.102666150] HEAP: Freed bytes @ 0x3ffaffe8 from task "free" on core 0 by: /home/user/projects/esp/esp-idf/examples/system/sysview_tracing_heap_log/main/ sysview_heap_log.c:31 (discriminator 9) /home/user/projects/esp/esp-idf/components/freertos/port.c:355 (discriminator 1)

[0.202436200] HEAP: Allocated 3 bytes @ 0x3ffaffe8 from task "alloc" on core 0 by: /home/user/projects/esp/esp-idf/examples/system/sysview_tracing_heap_log/main/ sysview_heap_log.c:47 /home/user/projects/esp/esp-idf/components/freertos/port.c:355 (discriminator 1)

[0.202451725] HEAP: Allocated 6 bytes @ 0x3ffafff0 from task "alloc" on core 0 by: /home/user/projects/esp/esp-idf/examples/system/sysview_tracing_heap_log/main/ sysview_heap_log.c:48 /home/user/projects/esp/esp-idf/components/freertos/port.c:355 (discriminator 1)

[0.202667075] HEAP: Freed bytes @ 0x3ffafff0 from task "free" on core 0 by: /home/user/projects/esp/esp-idf/examples/system/sysview_tracing_heap_log/main/ sysview_heap_log.c:31 (discriminator 9) /home/user/projects/esp/esp-idf/components/freertos/port.c:355 (discriminator 1)

[0.302436000] HEAP: Allocated 4 bytes @ 0x3ffafff0 from task "alloc" on core 0 by: /home/user/projects/esp/esp-idf/examples/system/sysview_tracing_heap_log/main/ sysview_heap_log.c:47 /home/user/projects/esp/esp-idf/components/freertos/port.c:355 (discriminator 1)

[0.302451475] HEAP: Allocated 8 bytes @ 0x3ffb40b8 from task "alloc" on core 0 by: /home/user/projects/esp/esp-idf/examples/system/sysview_tracing_heap_log/main/ sysview_heap_log.c:48 /home/user/projects/esp/esp-idf/components/freertos/port.c:355 (discriminator 1)

[0.302667500] HEAP: Freed bytes @ 0x3ffb40b8 from task "free" on core 0 by: /home/user/projects/esp/esp-idf/examples/system/sysview_tracing_heap_log/main/ sysview_heap_log.c:31 (discriminator 9) /home/user/projects/esp/esp-idf/components/freertos/port.c:355 (discriminator 1)

Processing completed. Processed 1019 events =============== HEAP TRACE REPORT =============== Processed 14 heap events. [0.002244575] HEAP: Allocated 1 bytes @ 0x3ffaffd8 from task "alloc" on core 0 by: /home/user/projects/esp/esp-idf/examples/system/sysview_tracing_heap_log/main/ sysview_heap_log.c:47 /home/user/projects/esp/esp-idf/components/freertos/port.c:355 (discriminator 1)

[0.102436025] HEAP: Allocated 2 bytes @ 0x3ffaffe0 from task "alloc" on core 0 by:

/home/user/projects/esp/esp-idf/examples/system/sysview_tracing_heap_log/main/

sysview_heap_log.c:47

(continues on next page)

Espressif Systems

1285

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

(continued from previous page) /home/user/projects/esp/esp-idf/components/freertos/port.c:355 (discriminator 1)
[0.202436200] HEAP: Allocated 3 bytes @ 0x3ffaffe8 from task "alloc" on core 0 by: /home/user/projects/esp/esp-idf/examples/system/sysview_tracing_heap_log/main/ sysview_heap_log.c:47 /home/user/projects/esp/esp-idf/components/freertos/port.c:355 (discriminator 1)
[0.302436000] HEAP: Allocated 4 bytes @ 0x3ffafff0 from task "alloc" on core 0 by: /home/user/projects/esp/esp-idf/examples/system/sysview_tracing_heap_log/main/ sysview_heap_log.c:47 /home/user/projects/esp/esp-idf/components/freertos/port.c:355 (discriminator 1)
Found 10 leaked bytes in 4 blocks.
Heap Tracing To Find Heap Corruption Heap tracing can also be used to help track down heap corruption. When a region in heap is corrupted, it may be from some other part of the program which allocated memory at a nearby address.
If you have some idea at what time the corruption occurred, enabling heap tracing in HEAP_TRACE_ALL mode allows you to record all the functions which allocated memory, and the addresses of the allocations.
Using heap tracing in this way is very similar to memory leak detection as described above. For memory which is allocated and not freed, the output is the same. However, records will also be shown for memory which has been freed.
Performance Impact Enabling heap tracing in menuconfig increases the code size of your program, and has a very small negative impact on performance of heap allocation/free operations even when heap tracing is not running.
When heap tracing is running, heap allocation/free operations are substantially slower than when heap tracing is stopped. Increasing the depth of stack frames recorded for each allocation (see above) will also increase this performance impact.
False-Positive Memory Leaks Not everything printed by heap_trace_dump() is necessarily a memory leak. Among things which may show up here, but are not memory leaks:
· Any memory which is allocated after heap_trace_start() but then freed after heap_trace_stop() will appear in the leak dump.
· Allocations may be made by other tasks in the system. Depending on the timing of these tasks, itns quite possible this memory is freed after heap_trace_stop() is called.
· The first time a task uses stdio - for example, when it calls printf() - a lock (RTOS mutex semaphore) is allocated by the libc. This allocation lasts until the task is deleted.
· Certain uses of printf(), such as printing floating point numbers, will allocate some memory from the heap on demand. These allocations last until the task is deleted.
· The Bluetooth, Wi-Fi, and TCP/IP libraries will allocate heap memory buffers to handle incoming or outgoing data. These memory buffers are usually short-lived, but some may be shown in the heap leak trace if the data was received/transmitted by the lower levels of the network while the leak trace was running.
· TCP connections will continue to use some memory after they are closed, because of the TIME_WAIT state. After the TIME_WAIT period has completed, this memory will be freed.
One way to differentiate between orealpand ofalse positivepmemory leaks is to call the suspect code multiple times while tracing is running, and look for patterns (multiple matching allocations) in the heap trace output.
API Reference - Heap Tracing
Header File
· components/heap/include/esp_heap_trace.h

Espressif Systems

1286

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Functions esp_err_t heap_trace_init_standalone(heap_trace_record_t *record_buffer, size_t num_records)
Initialise heap tracing in standalone mode.
This function must be called before any other heap tracing functions.
To disable heap tracing and allow the buffer to be freed, stop tracing and then call heap_trace_init_standalone(NULL, 0);
Return · ESP_ERR_NOT_SUPPORTED Project was compiled without heap tracing enabled in menuconfig. · ESP_ERR_INVALID_STATE Heap tracing is currently in progress. · ESP_OK Heap tracing initialised successfully.
Parameters · record_buffer: Provide a buffer to use for heap trace data. Must remain valid any time heap tracing is enabled, meaning it must be allocated from internal memory not in PSRAM. · num_records: Size of the heap trace buffer, as number of record structures.
esp_err_t heap_trace_init_tohost(void) Initialise heap tracing in host-based mode.
This function must be called before any other heap tracing functions.
Return · ESP_ERR_INVALID_STATE Heap tracing is currently in progress. · ESP_OK Heap tracing initialised successfully.
esp_err_t heap_trace_start(heap_trace_mode_t mode) Start heap tracing. All heap allocations & frees will be traced, until heap_trace_stop() is called.
Note heap_trace_init_standalone() must be called to provide a valid buffer, before this function is called. Note Calling this function while heap tracing is running will reset the heap trace state and continue tracing. Return
· ESP_ERR_NOT_SUPPORTED Project was compiled without heap tracing enabled in menuconfig. · ESP_ERR_INVALID_STATE A non-zero-length buffer has not been set via
heap_trace_init_standalone(). · ESP_OK Tracing is started. Parameters · mode: Mode for tracing.
­ HEAP_TRACE_ALL means all heap allocations and frees are traced. ­ HEAP_TRACE_LEAKS means only suspected memory leaks are traced. (When memory is
freed, the record is removed from the trace buffer.)
esp_err_t heap_trace_stop(void) Stop heap tracing.
Return · ESP_ERR_NOT_SUPPORTED Project was compiled without heap tracing enabled in menuconfig. · ESP_ERR_INVALID_STATE Heap tracing was not in progress. · ESP_OK Heap tracing stopped..
esp_err_t heap_trace_resume(void) Resume heap tracing which was previously stopped.
Unlike heap_trace_start(), this function does not clear the buffer of any pre-existing trace records.
The heap trace mode is the same as when heap_trace_start() was last called (or HEAP_TRACE_ALL if heap_trace_start() was never called).
Return · ESP_ERR_NOT_SUPPORTED Project was compiled without heap tracing enabled in menuconfig. · ESP_ERR_INVALID_STATE Heap tracing was already started. · ESP_OK Heap tracing resumed.
size_t heap_trace_get_count(void) Return number of records in the heap trace buffer.

Espressif Systems

1287

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

It is safe to call this function while heap tracing is running. esp_err_t heap_trace_get(size_t index, heap_trace_record_t *record)
Return a raw record from the heap trace buffer. Note It is safe to call this function while heap tracing is running, however in HEAP_TRACE_LEAK mode
record indexing may skip entries unless heap tracing is stopped first. Return
· ESP_ERR_NOT_SUPPORTED Project was compiled without heap tracing enabled in menuconfig. · ESP_ERR_INVALID_STATE Heap tracing was not initialised. · ESP_ERR_INVALID_ARG Index is out of bounds for current heap trace record count. · ESP_OK Record returned successfully. Parameters · index: Index (zero-based) of the record to return. · [out] record: Record where the heap trace record will be copied. void heap_trace_dump(void) Dump heap trace record data to stdout. Note It is safe to call this function while heap tracing is running, however in HEAP_TRACE_LEAK mode the dump may skip entries unless heap tracing is stopped first.
Structures struct heap_trace_record_t
Trace record data type. Stores information about an allocated region of memory.
Public Members
uint32_t ccount CCOUNT of the CPU when the allocation was made. LSB (bit value 1) is the CPU number (0 or 1).
void *address Address which was allocated.
size_t size Size of the allocation.
void *alloced_by[CONFIG_HEAP_TRACING_STACK_DEPTH] Call stack of the caller which allocated the memory.
void *freed_by[CONFIG_HEAP_TRACING_STACK_DEPTH] Call stack of the caller which freed the memory (all zero if not freed.)
Macros CONFIG_HEAP_TRACING_STACK_DEPTH
Enumerations enum heap_trace_mode_t
Values: HEAP_TRACE_ALL HEAP_TRACE_LEAKS
2.7.14 High Resolution Timer
Overview
Although FreeRTOS provides software timers, these timers have a few limitations:

Espressif Systems

1288

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· Maximum resolution is equal to RTOS tick period · Timer callbacks are dispatched from a low-priority task
Hardware timers are free from both of the limitations, but often they are less convenient to use. For example, application components may need timer events to fire at certain times in the future, but the hardware timer only contains one ocomparepvalue used for interrupt generation. This means that some facility needs to be built on top of the hardware timer to manage the list of pending events can dispatch the callbacks for these events as corresponding hardware interrupts happen.
An interrupt level of the handler depends on the CONFIG_ESP_TIMER_INTERRUPT_LEVEL option. It allows to set this: 1, 2 or 3 level (by default 1). Raising the level, the interrupt handler can reduce the timer processing delay.
esp_timer set of APIs provides one-shot and periodic timers, microsecond time resolution, and 64-bit range.
Internally, esp_timer uses a 64-bit hardware timer, where the implementation depends on CONFIG_ESP_TIMER_IMPL. Available options are:
· SYSTIMER
Timer callbacks can be dispatched by two methods:
· ESP_TIMER_TASK · ESP_TIMER_ISR. Available only if CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD is en-
abled (by default disabled).
ESP_TIMER_TASK. Timer callbacks are dispatched from a high-priority esp_timer task. Because all the callbacks are dispatched from the same task, it is recommended to only do the minimal possible amount of work from the callback itself, posting an event to a lower priority task using a queue instead.
If other tasks with priority higher than esp_timer are running, callback dispatching will be delayed until esp_timer task has a chance to run. For example, this will happen if an SPI Flash operation is in progress.
ESP_TIMER_ISR. Timer callbacks are dispatched directly from the timer interrupt handler. This method is useful for some simple callbacks which aim for lower latency.
Creating and starting a timer, and dispatching the callback takes some time. Therefore, there is a lower limit to the timeout value of one-shot esp_timer. If esp_timer_start_once() is called with a timeout value less than 20us, the callback will be dispatched only after approximately 20us.
Periodic esp_timer also imposes a 50us restriction on the minimal timer period. Periodic software timers with period of less than 50us are not practical since they would consume most of the CPU time. Consider using dedicated hardware peripherals or DMA features if you find that a timer with small period is required.
Using esp_timer APIs
Single timer is represented by esp_timer_handle_t type. Timer has a callback function associated with it. This callback function is called from the esp_timer task each time the timer elapses.
· To create a timer, call esp_timer_create(). · To delete the timer when it is no longer needed, call esp_timer_delete().
The timer can be started in one-shot mode or in periodic mode.
· To start the timer in one-shot mode, call esp_timer_start_once(), passing the time interval after which the callback should be called. When the callback gets called, the timer is considered to be stopped.
· To start the timer in periodic mode, call esp_timer_start_periodic(), passing the period with which the callback should be called. The timer keeps running until esp_timer_stop() is called.
Note that the timer must not be running when esp_timer_start_once() or esp_timer_start_periodic() is called. To restart a running timer, call esp_timer_stop() first, then call one of the start functions.

Espressif Systems

1289

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Callback functions
Note: Keep the callback functions as short as possible otherwise it will affect all timers.
Timer callbacks which are processed by ESP_TIMER_ISR method should not call the context switch call - portYIELD_FROM_ISR(), instead of this you should use the esp_timer_isr_dispatch_need_yield() function. The context switch will be done after all ISR dispatch timers have been processed, if required by the system.
esp_timer during the light sleep
During light sleep, the esp_timer counter stops and no callback functions are called. Instead, the time is counted by the RTC counter. Upon waking up, the system gets the difference between the counters and calls a function that advances the esp_timer counter. Since the counter has been advanced, the system starts calling callbacks that were not called during sleep. The number of callbacks depends on the duration of the sleep and the period of the timers. It can lead to overflow of some queues. This only applies to periodic timers, one-shot timers will be called once. This behavior can be changed by calling esp_timer_stop() before sleeping. In some cases, this can be inconvenient, and instead of the stop function, you can use the skip_unhandled_events option during esp_timer_create(). When the skip_unhandled_events is true, if a periodic timer expires one or more times during light sleep then only one callback is called on wake. Using the skip_unhandled_events option with automatic light sleep (see Power Management APIs) helps to reduce the consumption of the system when it is in light sleep. The duration of light sleep is also determined by esp_timers. Timers with skip_unhandled_events option will not wake up the system.
Handling callbacks
esp_timer is designed to achieve a high-resolution low latency timer and the ability to handle delayed events. If the timer is late then the callback will be called as soon as possible, it will not be lost. In the worst case, when the timer has not been processed for more than one period (for periodic timers), in this case the callbacks will be called one after the other without waiting for the set period. This can be bad for some applications, and the skip_unhandled_events option was introduced to eliminate this behavior. If skip_unhandled_events is set then a periodic timer that has expired multiple times without being able to call the callback will still result in only one callback event once processing is possible.
Obtaining Current Time
esp_timer also provides a convenience function to obtain the time passed since start-up, with microsecond precision: esp_timer_get_time(). This function returns the number of microseconds since esp_timer was initialized, which usually happens shortly before app_main function is called. Unlike gettimeofday function, values returned by esp_timer_get_time():
· Start from zero after the chip wakes up from deep sleep · Do not have timezone or DST adjustments applied
Application Example
The following example illustrates usage of esp_timer APIs: system/esp_timer.
API Reference
Header File

Espressif Systems

1290

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· components/esp_timer/include/esp_timer.h
Functions esp_err_t esp_timer_early_init(void)
Minimal initialization of esp_timer.
This function can be called very early in startup process, after this call only esp_timer_get_time function can be used.
Note This function is called from startup code. Applications do not need to call this function before using other esp_timer APIs.
Return · ESP_OK on success
esp_err_t esp_timer_init(void) Initialize esp_timer library.
Note This function is called from startup code. Applications do not need to call this function before using other esp_timer APIs. Before calling this function, esp_timer_early_init must be called by the startup code.
Return · ESP_OK on success · ESP_ERR_NO_MEM if allocation has failed · ESP_ERR_INVALID_STATE if already initialized · other errors from interrupt allocator
esp_err_t esp_timer_deinit(void) De-initialize esp_timer library.
Note Normally this function should not be called from applications Return
· ESP_OK on success · ESP_ERR_INVALID_STATE if not yet initialized
esp_err_t esp_timer_create(const esp_timer_create_args_t *create_args, esp_timer_handle_t *out_handle)
Create an esp_timer instance.
Note When done using the timer, delete it with esp_timer_delete function. Return
· ESP_OK on success · ESP_ERR_INVALID_ARG if some of the create_args are not valid · ESP_ERR_INVALID_STATE if esp_timer library is not initialized yet · ESP_ERR_NO_MEM if memory allocation fails Parameters · create_args: Pointer to a structure with timer creation arguments. Not saved by the library,
can be allocated on the stack. · [out] out_handle: Output, pointer to esp_timer_handle_t variable which will hold the created
timer handle.
esp_err_t esp_timer_start_once(esp_timer_handle_t timer, uint64_t timeout_us) Start one-shot timer.
Timer should not be running when this function is called.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if the handle is invalid · ESP_ERR_INVALID_STATE if the timer is already running
Parameters · timer: timer handle created using esp_timer_create · timeout_us: timer timeout, in microseconds relative to the current moment

Espressif Systems

1291

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t esp_timer_start_periodic(esp_timer_handle_t timer, uint64_t period) Start a periodic timer.
Timer should not be running when this function is called. This function will start the timer which will trigger every mperiodnmicroseconds.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if the handle is invalid · ESP_ERR_INVALID_STATE if the timer is already running
Parameters · timer: timer handle created using esp_timer_create · period: timer period, in microseconds
esp_err_t esp_timer_stop(esp_timer_handle_t timer) Stop the timer.
This function stops the timer previously started using esp_timer_start_once or esp_timer_start_periodic.
Return · ESP_OK on success · ESP_ERR_INVALID_STATE if the timer is not running
Parameters · timer: timer handle created using esp_timer_create
esp_err_t esp_timer_delete(esp_timer_handle_t timer) Delete an esp_timer instance.
The timer must be stopped before deleting. A one-shot timer which has expired does not need to be stopped.
Return · ESP_OK on success · ESP_ERR_INVALID_STATE if the timer is running
Parameters · timer: timer handle allocated using esp_timer_create
int64_t esp_timer_get_time(void) Get time in microseconds since boot.
Return number of microseconds since underlying timer has been started
int64_t esp_timer_get_next_alarm(void) Get the timestamp when the next timeout is expected to occur.
Return Timestamp of the nearest timer event, in microseconds. The timebase is the same as for the values returned by esp_timer_get_time.
int64_t esp_timer_get_next_alarm_for_wake_up(void) Get the timestamp when the next timeout is expected to occur skipping those which have skip_unhandled_events flag.
Return Timestamp of the nearest timer event, in microseconds. The timebase is the same as for the values returned by esp_timer_get_time.
esp_err_t esp_timer_get_period(esp_timer_handle_t timer, uint64_t *period) Get the period of a timer.
This function fetches the timeout period of a timer.
Note The timeout period is the time interval with which a timer restarts after expiry. For one-shot timers, the period is 0 as there is no periodicity associated with such timers.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if the arguments are invalid
Parameters · timer: timer handle allocated using esp_timer_create · period: memory to store the timer period value in microseconds

Espressif Systems

1292

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t esp_timer_get_expiry_time(esp_timer_handle_t timer, uint64_t *expiry) Get the expiry time of a one-shot timer.
This function fetches the expiry time of a one-shot timer.
Note This API returns a valid expiry time only for a one-shot timer. It returns an error if the timer handle passed to the function is for a periodic timer.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if the arguments are invalid · ESP_ERR_NOT_SUPPORTED if the timer type is periodic
Parameters · timer: timer handle allocated using esp_timer_create · expiry: memory to store the timeout value in microseconds
esp_err_t esp_timer_dump(FILE *stream) Dump the list of timers to a stream.
If CONFIG_ESP_TIMER_PROFILING option is enabled, this prints the list of all the existing timers. Otherwise, only the list active timers is printed.
The format is:
name period alarm times_armed times_triggered total_callback_run_time
where:
name itimer name (if CONFIG_ESP_TIMER_PROFILING is defined), or timer pointer period iperiod of timer, in microseconds, or 0 for one-shot timer alarm - time of the next alarm, in microseconds since boot, or 0 if the timer is not started
The following fields are printed if CONFIG_ESP_TIMER_PROFILING is defined:
times_armed inumber of times the timer was armed via esp_timer_start_X times_triggered - number of times the callback was called total_callback_run_time - total time taken by callback to execute, across all calls
Return · ESP_OK on success · ESP_ERR_NO_MEM if can not allocate temporary buffer for the output
Parameters · stream: stream (such as stdout) to dump the information to
bool esp_timer_is_active(esp_timer_handle_t timer) Returns status of a timer, active or not.
This function is used to identify if the timer is still active or not.
Return · 1 if timer is still active · 0 if timer is not active.
Parameters · timer: timer handle created using esp_timer_create
Structures struct esp_timer_create_args_t
Timer configuration passed to esp_timer_create.
Public Members
esp_timer_cb_t callback Function to call when timer expires.
void *arg Argument to pass to the callback.

Espressif Systems

1293

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
esp_timer_dispatch_t dispatch_method Call the callback from task or from ISR.
const char *name Timer name, used in esp_timer_dump function.
bool skip_unhandled_events Skip unhandled events for periodic timers.
Type Definitions typedef struct esp_timer *esp_timer_handle_t
Opaque type representing a single esp_timer. typedef void (*esp_timer_cb_t)(void *arg)
Timer callback function type. Parameters
· arg: pointer to opaque user-specific data
Enumerations enum esp_timer_dispatch_t
Method for dispatching timer callback. Values: ESP_TIMER_TASK
Callback is called from timer task. ESP_TIMER_MAX
Count of the methods for dispatching timer callback.
2.7.15 Inter-Processor Call
Note: The IPC is an Inter-Processor Call and NOT Inter-Process Communication as found on other operating systems.
Overview
Due to the dual core nature of the ESP32-S3, there are instances where a certain callback must be run in the context of a particular CPU such as:
· When allocating an ISR to an interrupt source of a particular CPU (applies to freeing a particular CPUns interrupt source as well).
· On particular chips (such as the ESP32), accessing memory that is exclusive to a particular CPU (such as RTC Fast Memory).
· Reading the registers/state of another CPU. The IPC (Inter-Processor Call) feature allows a particular CPU (the calling CPU) to trigger the execution of a callback function on another CPU (the target CPU). The IPC feature allows execution of a callback function on the target CPU in either a task context, or a High Priority Interrupt context (see High-Level Interrupts for more details). Depending on the context that the callback function is executed in, different restrictions apply to the implementation of the callback function.

Espressif Systems

1294

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

IPC in Task Context
The IPC feature implements callback execution in a task context by creating an IPC task for each CPU during application startup. When the calling CPU needs to execute a callback on the target CPU, the callback will execute in the context of the target CPUns IPC task.
When using IPCs in a task context, users need to consider the following:
· IPC callbacks should ideally be simple and short. An IPC callback should avoid attempting to block or yield.
· The IPC tasks are created at the highest possible priority (i.e., configMAX_PRIORITIES - 1) thus the callback should also run at that priority as a result. However, CONFIG_ESP_IPC_USES_CALLERS_PRIORITY is enabled by default which will temporarily lower the priority of the target CPUns IPC task to the calling CPU before executing the callback.
· Depending on the complexity of the callback, users may need to configure the stack size of the IPC task via CONFIG_ESP_IPC_TASK_STACK_SIZE.
· The IPC feature is internally protected by a mutex. Therefore, simultaneous IPC calls from two or more calling CPUs will be handled on a first come first serve basis.

API Usage Task Context IPC callbacks have the following restrictions:
· The callback must be of type void func(void *arg) · The callback should avoid attempting to block or yield as this will result in the target CPUns IPC task blocking
or yielding. · The callback must avoid changing any aspect of the IPC task (e.g., by calling vTaskPrioritySet(NULL,
x)).
The IPC feature offers the API listed below to execute a callback in a task context on a target CPU. The API allows the calling CPU to block until the callbackns execution has completed, or return immediately once the callbackns execution has started.
· esp_ipc_call() will trigger an IPC call on the target CPU. This function will block until the target CPUn s IPC task begins execution of the callback.
· esp_ipc_call_blocking() will trigger an IPC on the target CPU. This function will block until the target CPUns IPC task completes execution of the callback.

IPC in ISR Context
In some cases, we need to quickly obtain the state of another CPU such as in a core dump, GDB stub, various unit tests, and DPORT workaround. For such scenarios, the IPC feature supports execution of callbacks in a High Priority Interrupt context. The IPC feature implements the High Priority Interrupt context by reserving a High Priority Interrupt on each CPU for IPC usage. When a calling CPU needs to execute a callback on the target CPU, the callback will execute in the context of the High Priority Interrupt of the target CPU.
When using IPCs in High Priority Interrupt context, users need to consider the following:
· Since the callback is executed in a High Priority Interrupt context, the callback must be written entirely in assembly. See the API Usage below for more details regarding writing assembly callbacks.
· The priority of the reserved High Priority Interrupt is dependent on the CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL option
· When the callback executes: ­ The calling CPU will disable interrupts of level 3 and lower ­ Although the priority of the reserved interrupt depends on CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL, during the execution IPC ISR callback, the target CPU will disable interrupts of level 5 and lower regardless of what CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL is set to.

API Usage High Priority Interrupt IPC callbacks have the following restrictions: · The callback must be of type void func(void *arg) but implemented entirely in assembly

Espressif Systems

1295

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· The callback is invoked via the CALLX0 instruction with register windowing disabled, thus the callback:

­ Must not call any register window related instructions (e.g., entry and retw). ­ Must not call other C functions as register windowing is disabled · The callback should be placed in IRAM at a 4-byte aligned address · (On invocation of/after returning from) the callback, the registers a2, a3, a4 are (saved/restored) automatically thu

­ a2 will contain the void *arg of the callback ­ a3/a4 are free to use as scratch registers
The IPC feature offers the API listed below to execute a callback in a High Priority Interrupt context.
· esp_ipc_isr_asm_call() will trigger an IPC call on the target CPU. This function will busy-wait until the target CPU begins execution of the callback.
· esp_ipc_isr_asm_call_blocking() will trigger an IPC call on the target CPU. This function will busy-wait until the target CPU completes execution of the callback.
The following code-blocks demonstrates a High Priority Interrupt IPC callback written in assembly that simply reads the target CPUns cycle count.

/* esp_test_ipc_isr_get_cycle_count_other_cpu(void *arg) */

// this function reads CCOUNT of the target CPU and stores it in arg.

// use only a2, a3 and a4 regs here.

.section .iram1, "ax"

.align

4

.global

esp_test_ipc_isr_get_cycle_count_other_cpu

.type

esp_test_ipc_isr_get_cycle_count_other_cpu, @function

// Args:

// a2 - void* arg

esp_test_ipc_isr_get_cycle_count_other_cpu:

rsr.ccount a3

s32i a3, a2, 0

ret

unit32_t cycle_count; esp_ipc_isr_asm_call_blocking(esp_test_ipc_isr_get_cycle_count_other_cpu, (void *)cycle_count);

Note: The number of scratch registers available for use is sufficient for most simple use cases. But if your callback requires more scratch registers, void *arg can point to a buffer that is used as a register save area. The callback can then save and restore more registers. See the system/ipc/ipc_isr.

Note:

For more examples of High Priority Interrupt IPC callbacks, see compo-

nents/esp_system/port/arch/xtensa/esp_ipc_isr_routines.S and :components/esp_system/test/test_ipc_isr.S

The High Priority Interrupt IPC API also provides the following convenience functions that can stall/resume the target CPU. These API utilize the High Priority Interrupt IPC, but supply their own internal callbacks:
· esp_ipc_isr_stall_other_cpu() stalls the target CPU. The calling CPU disables interrupts of level 3 and lower while the target CPU will busy-wait with interrupts of level 5 and lower disabled. The target CPU will busy-wait until esp_ipc_isr_release_other_cpu() is called.
· esp_ipc_isr_release_other_cpu() resumes the target CPU.

API Reference
Header File · components/esp_system/include/esp_ipc.h

Espressif Systems

1296

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Functions esp_err_t esp_ipc_call(uint32_t cpu_id, esp_ipc_func_t func, void *arg)
Execute a callback on a given CPU.
Execute a given callback on a particular CPU. The callback must be of type oesp_ipc_func_tpand will be invoked in the context of the target CPUns IPC task.
· This function will block the target CPUns IPC task has begun execution of the callback · If another IPC call is ongoing, this function will block until the ongoing IPC call completes · The stack size of the IPC task can be configured via the CONFIG_ESP_IPC_TASK_STACK_SIZE
option
Note In single-core mode, returns ESP_ERR_INVALID_ARG for cpu_id 1. Return
· ESP_ERR_INVALID_ARG if cpu_id is invalid · ESP_ERR_INVALID_STATE if the FreeRTOS scheduler is not running · ESP_OK otherwise Parameters · [in] cpu_id: CPU where the given function should be executed (0 or 1) · [in] func: Pointer to a function of type void func(void* arg) to be executed · [in] arg: Arbitrary argument of type void* to be passed into the function esp_err_t esp_ipc_call_blocking(uint32_t cpu_id, esp_ipc_func_t func, void *arg) Execute a callback on a given CPU until and block until it completes.
This function is identical to esp_ipc_call() except that this function will block until the execution of the callback completes.
Note In single-core mode, returns ESP_ERR_INVALID_ARG for cpu_id 1. Return
· ESP_ERR_INVALID_ARG if cpu_id is invalid · ESP_ERR_INVALID_STATE if the FreeRTOS scheduler is not running · ESP_OK otherwise Parameters · [in] cpu_id: CPU where the given function should be executed (0 or 1) · [in] func: Pointer to a function of type void func(void* arg) to be executed · [in] arg: Arbitrary argument of type void* to be passed into the function
Type Definitions typedef void (*esp_ipc_func_t)(void *arg)
IPC Callback.
A callback of this type should be provided as an argument when calling esp_ipc_call() or esp_ipc_call_blocking().

Header File
· components/esp_system/include/esp_ipc_isr.h
Functions void esp_ipc_isr_asm_call(esp_ipc_isr_func_t func, void *arg)
Execute an assembly callback on the other CPU.
Execute a given callback on the other CPU in the context of a High Priority Interrupt.
· This function will busy-wait in a critical section until the other CPU has started execution of the callback · The callback must be written in assembly, is invoked using a CALLX0 instruction, and has a2, a3, a4 as
scratch registers. See docs for more details
Note This function is not available in single-core mode. Parameters
· [in] func: Pointer to a function of type void func(void* arg) to be executed

Espressif Systems

1297

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· [in] arg: Arbitrary argument of type void* to be passed into the function void esp_ipc_isr_asm_call_blocking(esp_ipc_isr_func_t func, void *arg)
Execute an assembly callback on the other CPU and busy-wait until it completes.
This function is identical to esp_ipc_isr_asm_call() except that this function will busy-wait until the execution of the callback completes.
Note This function is not available in single-core mode. Parameters
· [in] func: Pointer to a function of type void func(void* arg) to be executed · [in] arg: Arbitrary argument of type void* to be passed into the function
void esp_ipc_isr_stall_other_cpu(void) Stall the other CPU.
This function will stall the other CPU. The other CPU is stalled by busy-waiting in the context of a High Priority Interrupt. The other CPU will not be resumed until esp_ipc_isr_release_other_cpu() is called.
· This function is internally implemented using IPC ISR · This function is used for DPORT workaround. · If the stall feature is paused using esp_ipc_isr_stall_pause(), this function will have no effect
Note This function is not available in single-core mode.
void esp_ipc_isr_release_other_cpu(void) Release the other CPU.
This function will release the other CPU that was previously stalled from calling esp_ipc_isr_stall_other_cpu()
· This function is used for DPORT workaround. · If the stall feature is paused using esp_ipc_isr_stall_pause(), this function will have no effect
Note This function is not available in single-core mode.
void esp_ipc_isr_stall_pause(void) Puase the CPU stall feature.
This function will pause the CPU stall feature. Once paused, calls to esp_ipc_isr_stall_other_cpu() and esp_ipc_isr_release_other_cpu() will have no effect. If a IPC ISR call is already in progress, this function will busy-wait until the call completes before pausing the CPU stall feature.
void esp_ipc_isr_stall_abort(void) Abort a CPU stall.
This function will abort any stalling routine of the other CPU due to a pervious call to esp_ipc_isr_stall_other_cpu(). This function aborts the stall in a non-recoverable manner, thus should only be called in case of a panic().
· This function is used in panic handling code
void esp_ipc_isr_stall_resume(void) Resume the CPU stall feature.
This function will resume the CPU stall feature that was previously paused by calling esp_ipc_isr_stall_pause(). Once resumed, calls to esp_ipc_isr_stall_other_cpu() and esp_ipc_isr_release_other_cpu() will have effect again.
Type Definitions typedef void (*esp_ipc_isr_func_t)(void *arg)
IPC ISR Callback.
A callback of this type should be provided as an argument when calling esp_ipc_isr_asm_call() or esp_ipc_isr_asm_call_blocking().

Espressif Systems

1298

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
2.7.16 Call function with external stack
Overview
A given function can be executed with a user allocated stack space which is independent of current task stack, this mechanism can be used to save stack space wasted by tasks which call a common function with intensive stack usage such as printf. The given function can be called inside the shared stack space which is a callback function deferred by calling esp_execute_shared_stack_function(), passing that function as parameter
Usage
esp_execute_shared_stack_function() takes four arguments:
· a mutex object allocated by the caller, which is used to protect if the same function shares its allocated stack · a pointer to the top of stack used for that fuction · the size of stack in bytes · a pointer to the shared stack function
The user defined function will be deferred as a callback and can be called using the user allocated space without taking space from current task stack.
The usage may look like the code below:
void external_stack_function(void) {
printf("Executing this printf from external stack! \n"); }
//Let's suppose we want to call printf using a separated stack space //allowing the app to reduce its stack size. void app_main() {
//Allocate a stack buffer, from heap or as a static form: portSTACK_TYPE *shared_stack = malloc(8192 * sizeof(portSTACK_TYPE)); assert(shared_stack != NULL);
//Allocate a mutex to protect its usage: SemaphoreHandle_t printf_lock = xSemaphoreCreateMutex(); assert(printf_lock != NULL);
//Call the desired function using the macro helper: esp_execute_shared_stack_function(printf_lock,
shared_stack, 8192, external_stack_function);
vSemaphoreDelete(printf_lock); free(shared_stack); }

API Reference
Header File · components/esp_system/include/esp_expression_with_stack.h

Functions void esp_execute_shared_stack_function(SemaphoreHandle_t lock, void *stack,
stack_size, shared_stack_function function) Calls user defined shared stack space function.

size_t

Espressif Systems

1299

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Note if either lock, stack or stack size is invalid, the expression will be called using the current stack. Parameters
· lock: Mutex object to protect in case of shared stack · stack: Pointer to user alocated stack · stack_size: Size of current stack in bytes · function: pointer to the shared stack function to be executed
Macros ESP_EXECUTE_EXPRESSION_WITH_STACK(lock, stack, stack_size, expression)
Type Definitions typedef void (*shared_stack_function)(void)
2.7.17 Interrupt allocation
Overview
The ESP32-S3 has two cores, with 32 interrupts. Each interrupt has a certain priority level, most (but not all) interrupts are connected to the interrupt mux. Because there are more interrupt sources than interrupts, sometimes it makes sense to share an interrupt in multiple drivers. The esp_intr_alloc() abstraction exists to hide all these implementation details. A driver can allocate an interrupt for a certain peripheral by calling esp_intr_alloc() (or esp_intr_alloc_intrstatus()). It can use the flags passed to this function to set the type of interrupt allocated, specifying a particular level or trigger method. The interrupt allocation code will then find an applicable interrupt, use the interrupt mux to hook it up to the peripheral, and install the given interrupt handler and ISR to it. This code presents two different types of interrupts, handled differently: shared interrupts and non-shared interrupts. The simplest ones are non-shared interrupts: a separate interrupt is allocated per esp_intr_alloc() call and this interrupt is solely used for the peripheral attached to it, with only one ISR that will get called. On the other hand, shared interrupts can have multiple peripherals triggering them, with multiple ISRs being called when one of the peripherals attached signals an interrupt. Thus, ISRs that are intended for shared interrupts should check the interrupt status of the peripheral they service in order to check if any action is required. Non-shared interrupts can be either level- or edge-triggered. Shared interrupts can only be level interrupts due to the chance of missed interrupts when edge interrupts are used. For example, letns say DevA and DevB share an interrupt. DevB signals an interrupt, so INT line goes high. The ISR handler calls code for DevA but does nothing. Then, ISR handler calls code for DevB, but while doing that, DevA signals an interrupt. DevBns ISR is done, it clears interrupt status for DevB and exits interrupt code. Now, an interrupt for DevA is still pending, but because the INT line never went low, as DevA kept it high even when the interrupt for DevB was cleared, the interrupt is never serviced.
Multicore issues
Peripherals that can generate interrupts can be divided in two types: · External peripherals, within the ESP32-S3 but outside the Xtensa cores themselves. Most ESP32-S3 peripherals are of this type. · Internal peripherals, part of the Xtensa CPU cores themselves.
Interrupt handling differs slightly between these two types of peripherals.

Espressif Systems

1300

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Internal peripheral interrupts Each Xtensa CPU core has its own set of six internal peripherals:
· Three timer comparators · A performance monitor · Two software interrupts.
Internal interrupt sources are defined in esp_intr_alloc.h as ETS_INTERNAL_*_INTR_SOURCE.
These peripherals can only be configured from the core they are associated with. When generating an interrupt, the interrupt they generate is hard-wired to their associated core; itns not possible to have, for example, an internal timer comparator of one core generate an interrupt on another core. That is why these sources can only be managed using a task running on that specific core. Internal interrupt sources are still allocatable using esp_intr_alloc() as normal, but they cannot be shared and will always have a fixed interrupt level (namely, the one associated in hardware with the peripheral).
External Peripheral Interrupts The remaining interrupt sources are from external peripherals. These are defined in soc/soc.h as ETS_*_INTR_SOURCE.
Non-internal interrupt slots in both CPU cores are wired to an interrupt multiplexer, which can be used to route any external interrupt source to any of these interrupt slots.
· Allocating an external interrupt will always allocate it on the core that does the allocation. · Freeing an external interrupt must always happen on the same core it was allocated on. · Disabling and enabling external interrupts from another core is allowed. · Multiple external interrupt sources can share an interrupt slot by passing ESP_INTR_FLAG_SHARED as a
flag to esp_intr_alloc().
Care should be taken when calling esp_intr_alloc() from a task which is not pinned to a core. During task switching, these tasks can migrate between cores. Therefore it is impossible to tell which CPU the interrupt is allocated on, which makes it difficult to free the interrupt handle and may also cause debugging difficulties. It is advised to use xTaskCreatePinnedToCore() with a specific CoreID argument to create tasks that will allocate interrupts. In the case of internal interrupt sources, this is required.
IRAM-Safe Interrupt Handlers
The ESP_INTR_FLAG_IRAM flag registers an interrupt handler that always runs from IRAM (and reads all its data from DRAM), and therefore does not need to be disabled during flash erase and write operations.
This is useful for interrupts which need a guaranteed minimum execution latency, as flash write and erase operations can be slow (erases can take tens or hundreds of milliseconds to complete).
It can also be useful to keep an interrupt handler in IRAM if it is called very frequently, to avoid flash cache misses.
Refer to the SPI flash API documentation for more details.
Multiple Handlers Sharing A Source
Several handlers can be assigned to a same source, given that all handlers are allocated using the ESP_INTR_FLAG_SHARED flag. They will all be allocated to the interrupt, which the source is attached to, and called sequentially when the source is active. The handlers can be disabled and freed individually. The source is attached to the interrupt (enabled), if one or more handlers are enabled, otherwise detached. A handler will never be called when disabled, while its source may still be triggered if any one of its handler enabled.
Sources attached to non-shared interrupt do not support this feature.
Though the framework support this feature, you have to use it very carefully. There usually exist two ways to stop an interrupt from being triggered: disable the source or mask peripheral interrupt status. IDF only handles enabling and disabling of the source itself, leaving status and mask bits to be handled by users. Status bits shall either be masked before the handler responsible for it is disabled, either be masked and then properly handled in another enabled interrupt. Please note that leaving some status bits unhandled without masking them, while

Espressif Systems

1301

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
disabling the handlers for them, will cause the interrupt(s) to be triggered indefinitely, resulting therefore in a system crash.
API Reference
Header File
· components/esp_hw_support/include/esp_intr_alloc.h
Functions esp_err_t esp_intr_mark_shared(int intno, int cpu, bool is_in_iram)
Mark an interrupt as a shared interrupt.
This will mark a certain interrupt on the specified CPU as an interrupt that can be used to hook shared interrupt handlers to.
Return ESP_ERR_INVALID_ARG if cpu or intno is invalid ESP_OK otherwise Parameters
· intno: The number of the interrupt (0-31) · cpu: CPU on which the interrupt should be marked as shared (0 or 1) · is_in_iram: Shared interrupt is for handlers that reside in IRAM and the int can be left enabled
while the flash cache is disabled. esp_err_t esp_intr_reserve(int intno, int cpu)
Reserve an interrupt to be used outside of this framework.
This will mark a certain interrupt on the specified CPU as reserved, not to be allocated for any reason.
Return ESP_ERR_INVALID_ARG if cpu or intno is invalid ESP_OK otherwise Parameters
· intno: The number of the interrupt (0-31) · cpu: CPU on which the interrupt should be marked as shared (0 or 1)
esp_err_t esp_intr_alloc(int source, int flags, intr_handler_t handler, void *arg, intr_handle_t *ret_handle)
Allocate an interrupt with the given parameters.
This finds an interrupt that matches the restrictions as given in the flags parameter, maps the given interrupt source to it and hooks up the given interrupt handler (with optional argument) as well. If needed, it can return a handle for the interrupt as well.
The interrupt will always be allocated on the core that runs this function.
If ESP_INTR_FLAG_IRAM flag is used, and handler address is not in IRAM or RTC_FAST_MEM, then ESP_ERR_INVALID_ARG is returned.
Return ESP_ERR_INVALID_ARG if the combination of arguments is invalid. ESP_ERR_NOT_FOUND No free interrupt found with the specified flags ESP_OK otherwise
Parameters · source: The interrupt source. One of the ETS_*_INTR_SOURCE interrupt mux sources, as defined in soc/soc.h, or one of the internal ETS_INTERNAL_*_INTR_SOURCE sources as defined in this header. · flags: An ORred mask of the ESP_INTR_FLAG_* defines. These restrict the choice of interrupts that this routine can choose from. If this value is 0, it will default to allocating a non-shared interrupt of level 1, 2 or 3. If this is ESP_INTR_FLAG_SHARED, it will allocate a shared interrupt of level 1. Setting ESP_INTR_FLAG_INTRDISABLED will return from this function with the interrupt disabled. · handler: The interrupt handler. Must be NULL when an interrupt of level >3 is requested, because these types of interrupts arennt C-callable. · arg: Optional argument for passed to the interrupt handler · ret_handle: Pointer to an intr_handle_t to store a handle that can later be used to request details or free the interrupt. Can be NULL if no handle is required.

Espressif Systems

1302

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t esp_intr_alloc_intrstatus(int source, int flags, uint32_t intrstatusreg, uint32_t intrstatusmask, intr_handler_t handler, void *arg, intr_handle_t *ret_handle)
Allocate an interrupt with the given parameters.
This essentially does the same as esp_intr_alloc, but allows specifying a register and mask combo. For shared interrupts, the handler is only called if a read from the specified register, ANDed with the mask, returns nonzero. By passing an interrupt status register address and a fitting mask, this can be used to accelerate interrupt handling in the case a shared interrupt is triggered; by checking the interrupt statuses first, the code can decide which ISRs can be skipped
Return ESP_ERR_INVALID_ARG if the combination of arguments is invalid. ESP_ERR_NOT_FOUND No free interrupt found with the specified flags ESP_OK otherwise
Parameters · source: The interrupt source. One of the ETS_*_INTR_SOURCE interrupt mux sources, as defined in soc/soc.h, or one of the internal ETS_INTERNAL_*_INTR_SOURCE sources as defined in this header. · flags: An ORred mask of the ESP_INTR_FLAG_* defines. These restrict the choice of interrupts that this routine can choose from. If this value is 0, it will default to allocating a non-shared interrupt of level 1, 2 or 3. If this is ESP_INTR_FLAG_SHARED, it will allocate a shared interrupt of level 1. Setting ESP_INTR_FLAG_INTRDISABLED will return from this function with the interrupt disabled. · intrstatusreg: The address of an interrupt status register · intrstatusmask: A mask. If a read of address intrstatusreg has any of the bits that are 1 in the mask set, the ISR will be called. If not, it will be skipped. · handler: The interrupt handler. Must be NULL when an interrupt of level >3 is requested, because these types of interrupts arennt C-callable. · arg: Optional argument for passed to the interrupt handler · ret_handle: Pointer to an intr_handle_t to store a handle that can later be used to request details or free the interrupt. Can be NULL if no handle is required.
esp_err_t esp_intr_free(intr_handle_t handle) Disable and free an interrupt.
Use an interrupt handle to disable the interrupt and release the resources associated with it. If the current core is not the core that registered this interrupt, this routine will be assigned to the core that allocated this interrupt, blocking and waiting until the resource is successfully released.
Note When the handler shares its source with other handlers, the interrupt status bits itns responsible for should be managed properly before freeing it. see esp_intr_disable for more details. Please do not call this function in esp_ipc_call_blocking.
Return ESP_ERR_INVALID_ARG the handle is NULL ESP_FAIL failed to release this handle ESP_OK otherwise
Parameters · handle: The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
int esp_intr_get_cpu(intr_handle_t handle) Get CPU number an interrupt is tied to.
Return The core number where the interrupt is allocated Parameters
· handle: The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
int esp_intr_get_intno(intr_handle_t handle) Get the allocated interrupt for a certain handle.
Return The interrupt number Parameters
· handle: The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
esp_err_t esp_intr_disable(intr_handle_t handle) Disable the interrupt associated with the handle.
Note

Espressif Systems

1303

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
1. For local interrupts (ESP_INTERNAL_* sources), this function has to be called on the CPU the interrupt is allocated on. Other interrupts have no such restriction.
2. When several handlers sharing a same interrupt source, interrupt status bits, which are handled in the handler to be disabled, should be masked before the disabling, or handled in other enabled interrupts properly. Miss of interrupt status handling will cause infinite interrupt calls and finally system crash.
Return ESP_ERR_INVALID_ARG if the combination of arguments is invalid. ESP_OK otherwise Parameters
· handle: The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
esp_err_t esp_intr_enable(intr_handle_t handle) Enable the interrupt associated with the handle.
Note For local interrupts (ESP_INTERNAL_* sources), this function has to be called on the CPU the interrupt is allocated on. Other interrupts have no such restriction.
Return ESP_ERR_INVALID_ARG if the combination of arguments is invalid. ESP_OK otherwise Parameters
· handle: The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
esp_err_t esp_intr_set_in_iram(intr_handle_t handle, bool is_in_iram) Set the oin IRAMpstatus of the handler.
Note Does not work on shared interrupts. Return ESP_ERR_INVALID_ARG if the combination of arguments is invalid. ESP_OK otherwise Parameters
· handle: The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus · is_in_iram: Whether the handler associated with this handle resides in IRAM. Handlers residing
in IRAM can be called when cache is disabled.
void esp_intr_noniram_disable(void) Disable interrupts that arennt specifically marked as running from IRAM.
void esp_intr_noniram_enable(void) Re-enable interrupts disabled by esp_intr_noniram_disable.
void esp_intr_enable_source(int inum) enable the interrupt source based on its number
Parameters · inum: interrupt number from 0 to 31
void esp_intr_disable_source(int inum) disable the interrupt source based on its number
Parameters · inum: interrupt number from 0 to 31
static int esp_intr_flags_to_level(int flags) Get the lowest interrupt level from the flags.
Parameters · flags: The same flags that pass to esp_intr_alloc_intrstatus API
Macros ESP_INTR_FLAG_LEVEL1
Interrupt allocation flags.
These flags can be used to specify which interrupt qualities the code calling esp_intr_alloc* needs. Accept a Level 1 interrupt vector (lowest priority) ESP_INTR_FLAG_LEVEL2 Accept a Level 2 interrupt vector.
ESP_INTR_FLAG_LEVEL3 Accept a Level 3 interrupt vector.

Espressif Systems

1304

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_INTR_FLAG_LEVEL4 Accept a Level 4 interrupt vector.
ESP_INTR_FLAG_LEVEL5 Accept a Level 5 interrupt vector.
ESP_INTR_FLAG_LEVEL6 Accept a Level 6 interrupt vector.
ESP_INTR_FLAG_NMI Accept a Level 7 interrupt vector (highest priority)
ESP_INTR_FLAG_SHARED Interrupt can be shared between ISRs.
ESP_INTR_FLAG_EDGE Edge-triggered interrupt.
ESP_INTR_FLAG_IRAM ISR can be called if cache is disabled.
ESP_INTR_FLAG_INTRDISABLED Return with this interrupt disabled.
ESP_INTR_FLAG_LOWMED Low and medium prio interrupts. These can be handled in C.
ESP_INTR_FLAG_HIGH High level interrupts. Need to be handled in assembly.
ESP_INTR_FLAG_LEVELMASK Mask for all level flags.
ETS_INTERNAL_TIMER0_INTR_SOURCE Platform timer 0 interrupt source.
The esp_intr_alloc* functions can allocate an int for all ETS_*_INTR_SOURCE interrupt sources that are routed through the interrupt mux. Apart from these sources, each core also has some internal sources that do not pass through the interrupt mux. To allocate an interrupt for these sources, pass these pseudo-sources to the functions.
ETS_INTERNAL_TIMER1_INTR_SOURCE Platform timer 1 interrupt source.
ETS_INTERNAL_TIMER2_INTR_SOURCE Platform timer 2 interrupt source.
ETS_INTERNAL_SW0_INTR_SOURCE Software int source 1.
ETS_INTERNAL_SW1_INTR_SOURCE Software int source 2.
ETS_INTERNAL_PROFILING_INTR_SOURCE Int source for profiling.
ETS_INTERNAL_INTR_SOURCE_OFF Provides SystemView with positive IRQ IDs, otherwise scheduler events are not shown properly
ESP_INTR_ENABLE(inum) Enable interrupt by interrupt number
ESP_INTR_DISABLE(inum) Disable interrupt by interrupt number

Espressif Systems

1305

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Type Definitions typedef void (*intr_handler_t)(void *arg)
Function prototype for interrupt handler function typedef struct intr_handle_data_t intr_handle_data_t
Interrupt handler associated data structure typedef intr_handle_data_t *intr_handle_t
Handle to an interrupt handler
2.7.18 Logging library
Overview
The logging library provides two ways for setting log verbosity: · At compile time: in menuconfig, set the verbosity level using the option CONFIG_LOG_DEFAULT_LEVEL. · Optionally, also in menuconfig, set the maximum verbosity level using the option CONFIG_LOG_MAXIMUM_LEVEL. By default this is the same as the default level, but it can be set higher in order to compile more optional logs into the firmware. · At runtime: all logs for verbosity levels lower than CONFIG_LOG_DEFAULT_LEVEL are enabled by default. The function esp_log_level_set() can be used to set a logging level on a per module basis. Modules are identified by their tags, which are human-readable ASCII zero-terminated strings.
There are the following verbosity levels: · Error (lowest) · Warning · Info · Debug · Verbose (highest)
Note: The function esp_log_level_set() cannot set logging levels higher than specified by CONFIG_LOG_MAXIMUM_LEVEL. To increase log level for a specific file above this maximum at compile time, use the macro LOG_LOCAL_LEVEL (see the details below).

How to use this library
In each C file that uses logging functionality, define the TAG variable as shown below:
static const char* TAG = "MyModule";
Then use one of logging macros to produce output, e.g:
ESP_LOGW(TAG, "Baud rate error %.1f%%. Requested: %d baud, actual: %d baud", error * 100, baud_req, baud_real);
Several macros are available for different verbosity levels: · ESP_LOGE - error (lowest) · ESP_LOGW - warning · ESP_LOGI - info · ESP_LOGD - debug · ESP_LOGV - verbose (highest)
Additionally, there are ESP_EARLY_LOGx versions for each of these macros, e.g. ESP_EARLY_LOGE. These versions have to be used explicitly in the early startup code only, before heap allocator and syscalls have been initialized. Normal ESP_LOGx macros can also be used while compiling the bootloader, but they will fall back to the same implementation as ESP_EARLY_LOGx macros.

Espressif Systems

1306

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

There are also ESP_DRAM_LOGx versions for each of these macros, e.g. ESP_DRAM_LOGE. These versions are used in some places where logging may occur with interrupts disabled or with flash cache inaccessible. Use of this macros should be as sparing as possible, as logging in these types of code should be avoided for performance reasons.

Note: Inside critical sections interrupts are disabled so itns only possible to use ESP_DRAM_LOGx (preferred) or ESP_EARLY_LOGx. Even though itns possible to log in these situations, itns better if your program can be structured not to require it.

To override default verbosity level at file or component scope, define the LOG_LOCAL_LEVEL macro. At file scope, define it before including esp_log.h, e.g.:
#define LOG_LOCAL_LEVEL ESP_LOG_VERBOSE #include "esp_log.h"

At component scope, define it in the component makefile:
target_compile_definitions(${COMPONENT_LIB} PUBLIC "-DLOG_LOCAL_LEVEL=ESP_LOG_ VERBOSE")

To configure logging output per module at runtime, add calls to the function esp_log_level_set() as follows:

esp_log_level_set("*", ESP_LOG_ERROR); esp_log_level_set("wifi", ESP_LOG_WARN); esp_log_level_set("dhcpc", ESP_LOG_INFO);

// set all components to ERROR level // enable WARN logs from WiFi stack // enable INFO logs from DHCP client

Note: The oDRAMpand oEARLYplog macro variants documented above do not support per module setting of log verbosity. These macros will always log at the odefaultpverbosity level, which can only be changed at runtime by calling esp_log_level("*", level).

Logging to Host via JTAG By default, the logging library uses the vprintf-like function to write formatted output to the dedicated UART. By calling a simple API, all log output may be routed to JTAG instead, making logging several times faster. For details, please refer to Section Logging to Host.
Application Example
The logging library is commonly used by most esp-idf components and examples. For demonstration of log functionality, check ESP-IDFns examples directory. The most relevant examples that deal with logging are the following:
· system/ota · storage/sd_card · protocols/https_request
API Reference
Header File · components/log/include/esp_log.h
Functions void esp_log_level_set(const char *tag, esp_log_level_t level)
Set log level for given tag. If logging for given component has already been enabled, changes previous setting.

Espressif Systems

1307

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Note Note that this function can not raise log level above the level set using CONFIG_LOG_MAXIMUM_LEVEL setting in menuconfig. To raise log level above the default one for a given file, define LOG_LOCAL_LEVEL to one of the ESP_LOG_* values, before including esp_log.h in this file.
Parameters · tag: Tag of the log entries to enable. Must be a non-NULL zero terminated string. Value o*p resets log level for all tags to the given value. · level: Selects log level to enable. Only logs at this and lower verbosity levels will be shown.
esp_log_level_t esp_log_level_get(const char *tag) Get log level for a given tag, can be used to avoid expensive log statements.
Return The current log level for the given tag Parameters
· tag: Tag of the log to query current level. Must be a non-NULL zero terminated string.
vprintf_like_t esp_log_set_vprintf(vprintf_like_t func) Set function used to output log entries.
By default, log output goes to UART0. This function can be used to redirect log output to some other destination, such as file or network. Returns the original log handler, which may be necessary to return output to the previous destination.
Note Please note that function callback here must be re-entrant as it can be invoked in parallel from multiple thread context.
Return func old Function used for output. Parameters
· func: new Function used for output. Must have same signature as vprintf.
uint32_t esp_log_timestamp(void) Function which returns timestamp to be used in log output.
This function is used in expansion of ESP_LOGx macros. In the 2nd stage bootloader, and at early application startup stage this function uses CPU cycle counter as time source. Later when FreeRTOS scheduler start running, it switches to FreeRTOS tick count.
For now, we ignore millisecond counter overflow.
Return timestamp, in milliseconds
char *esp_log_system_timestamp(void) Function which returns system timestamp to be used in log output.
This function is used in expansion of ESP_LOGx macros to print the system time asoHH:MM:SS.sssp. The system time is initialized to 0 on startup, this can be set to the correct time with an SNTP sync, or manually with standard POSIX time functions.
Currently, this will not get used in logging from binary blobs (i.e. Wi-Fi & Bluetooth libraries), these will still print the RTOS tick time.
Return timestamp, in oHH:MM:SS.sssp
uint32_t esp_log_early_timestamp(void) Function which returns timestamp to be used in log output.
This function uses HW cycle counter and does not depend on OS, so it can be safely used after application crash.
Return timestamp, in milliseconds
void esp_log_write(esp_log_level_t level, const char *tag, const char *format, ...) Write message into the log.
This function is not intended to be used directly. Instead, use one of ESP_LOGE, ESP_LOGW, ESP_LOGI, ESP_LOGD, ESP_LOGV macros.
This function or these macros should not be used from an interrupt.

Espressif Systems

1308

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

void esp_log_writev(esp_log_level_t level, const char *tag, const char *format, va_list args) Write message into the log, va_list variant.
This function is provided to ease integration toward other logging framework, so that esp_log can be used as a log sink.
See esp_log_write()

Macros ESP_LOG_BUFFER_HEX_LEVEL(tag, buffer, buff_len, level)
Log a buffer of hex bytes at specified level, separated into 16 bytes each line.
Parameters · tag: description tag · buffer: Pointer to the buffer array · buff_len: length of buffer in bytes · level: level of the log
ESP_LOG_BUFFER_CHAR_LEVEL(tag, buffer, buff_len, level) Log a buffer of characters at specified level, separated into 16 bytes each line. Buffer should contain only printable characters.
Parameters · tag: description tag · buffer: Pointer to the buffer array · buff_len: length of buffer in bytes · level: level of the log
ESP_LOG_BUFFER_HEXDUMP(tag, buffer, buff_len, level) Dump a buffer to the log at specified level.
The dump log shows just like the one below:

W (195) log_example: 0x3ffb4280

2c 20 |ESP32 is great, |

W (195) log_example: 0x3ffb4290

77 69 |working along wi|

W (205) log_example: 0x3ffb42a0



|th the IDF..|

45 53 50 33 32 20 69 73 20 67 72 65 61 74

77 6f 72 6b 69 6e 67 20 61 6c 6f 6e 67 20

74 68 20 74 68 65 20 49 44 46 2e 00



It is highly recommended to use terminals with over 102 text width.
Parameters · tag: description tag · buffer: Pointer to the buffer array · buff_len: length of buffer in bytes · level: level of the log
ESP_LOG_BUFFER_HEX(tag, buffer, buff_len) Log a buffer of hex bytes at Info level.
See esp_log_buffer_hex_level Parameters
· tag: description tag · buffer: Pointer to the buffer array · buff_len: length of buffer in bytes
ESP_LOG_BUFFER_CHAR(tag, buffer, buff_len) Log a buffer of characters at Info level. Buffer should contain only printable characters.
See esp_log_buffer_char_level Parameters
· tag: description tag · buffer: Pointer to the buffer array · buff_len: length of buffer in bytes

Espressif Systems

1309

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

portGET_ARGUMENT_COUNT_INNER(zero, one, count, ...) macro to output logs in startup code, before heap allocator and syscalls have been initialized. Log at ESP_LOG_ERROR level.
See printf,ESP_LOGE,ESP_DRAM_LOGE
ESP_EARLY_LOGE(tag, format, ...) In the future, we want to switch to C++20. We also want to become compatible with clang. Hence, we provide two versions of the following macros which are using variadic arguments. The first one is using the GNU extension ##__VA_ARGS__. The second one is using the C++20 feature VA_OPT(,). This allows users to compile their code with standard C++20 enabled instead of the GNU extension. Below C++20, we havennt found any good alternative to using ##__VA_ARGS__.
ESP_EARLY_LOGW(tag, format, ...) macro to output logs in startup code at ESP_LOG_WARN level.
See ESP_EARLY_LOGE,ESP_LOGE, printf
ESP_EARLY_LOGI(tag, format, ...) macro to output logs in startup code at ESP_LOG_INFO level.
See ESP_EARLY_LOGE,ESP_LOGE, printf
ESP_EARLY_LOGD(tag, format, ...) macro to output logs in startup code at ESP_LOG_DEBUG level.
See ESP_EARLY_LOGE,ESP_LOGE, printf
ESP_EARLY_LOGV(tag, format, ...) macro to output logs in startup code at ESP_LOG_VERBOSE level.
See ESP_EARLY_LOGE,ESP_LOGE, printf
_ESP_LOG_EARLY_ENABLED(log_level)
ESP_LOG_EARLY_IMPL(tag, format, log_level, log_tag_letter, ...)
ESP_LOGE(tag, format, ...)
ESP_LOGW(tag, format, ...)
ESP_LOGI(tag, format, ...)
ESP_LOGD(tag, format, ...)
ESP_LOGV(tag, format, ...)
ESP_LOG_LEVEL(level, tag, format, ...) runtime macro to output logs at a specified level.
See printf Parameters
· tag: tag of the log, which can be used to change the log level by esp_log_level_set at runtime.
· level: level of the output log. · format: format of the output log. See printf · ...: variables to be replaced into the log. See printf
ESP_LOG_LEVEL_LOCAL(level, tag, format, ...) runtime macro to output logs at a specified level. Also check the level with LOG_LOCAL_LEVEL.
See printf, ESP_LOG_LEVEL
ESP_DRAM_LOGE(tag, format, ...) Macro to output logs when the cache is disabled. Log at ESP_LOG_ERROR level.
Similar to
Usage: ESP_DRAM_LOGE(DRAM_STR("my_tag"), "format", orESP_DRAM_LOGE(TAG, oformatp, l)`, where TAG is a char* that points to a str in the DRAM.

Espressif Systems

1310

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Note Unlike normal logging macros, itns possible to use this macro when interrupts are disabled or inside an ISR.
See ESP_EARLY_LOGE, the log level cannot be changed per-tag, however esp_log_level_set(o*p, level) will set the default level which controls these log lines also.
Note Placing log strings in DRAM reduces available DRAM, so only use when absolutely essential. See esp_rom_printf,ESP_LOGE ESP_DRAM_LOGW(tag, format, ...) macro to output logs when the cache is disabled at ESP_LOG_WARN level. See ESP_DRAM_LOGW,ESP_LOGW, esp_rom_printf ESP_DRAM_LOGI(tag, format, ...) macro to output logs when the cache is disabled at ESP_LOG_INFO level. See ESP_DRAM_LOGI,ESP_LOGI, esp_rom_printf ESP_DRAM_LOGD(tag, format, ...) macro to output logs when the cache is disabled at ESP_LOG_DEBUG level. See ESP_DRAM_LOGD,ESP_LOGD, esp_rom_printf ESP_DRAM_LOGV(tag, format, ...) macro to output logs when the cache is disabled at ESP_LOG_VERBOSE level. See ESP_DRAM_LOGV,ESP_LOGV, esp_rom_printf
Type Definitions typedef int (*vprintf_like_t)(const char *, va_list)
Enumerations enum esp_log_level_t
Log level. Values: ESP_LOG_NONE
No log output ESP_LOG_ERROR
Critical errors, software module can not recover on its own ESP_LOG_WARN
Error conditions from which recovery measures have been taken ESP_LOG_INFO
Information messages which describe normal flow of events ESP_LOG_DEBUG
Extra information which is not necessary for normal use (values, pointers, sizes, etc). ESP_LOG_VERBOSE
Bigger chunks of debugging information, or frequent messages which can potentially flood the output.
2.7.19 Miscellaneous System APIs
Software reset
To perform software reset of the chip, esp_restart() function is provided. When the function is called, execution of the program will stop, both CPUs will be reset, application will be loaded by the bootloader and started again.

Espressif Systems

1311

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Additionally, esp_register_shutdown_handler() function is provided to register a routine which needs to be called prior to restart (when done by esp_restart()). This is similar to the functionality of atexit POSIX function.

Reset reason
ESP-IDF application can be started or restarted due to a variety of reasons. To get the last reset reason, call esp_reset_reason() function. See description of esp_reset_reason_t for the list of possible reset reasons.

Heap memory
Two heap memory related functions are provided:
· esp_get_free_heap_size() returns the current size of free heap memory · esp_get_minimum_free_heap_size() returns the minimum size of free heap memory that was
available during program execution.
Note that ESP-IDF supports multiple heaps with different capabilities. Functions mentioned in this section return the size of heap memory which can be allocated using malloc family of functions. For further information about heap memory see Heap Memory Allocation.

MAC Address
These APIs allow querying and customizing MAC addresses for different network interfaces that supported (e.g. Wi-Fi, Bluetooth, Ethernet).
To fetch MAC address for a specific interface (e.g. Wi-Fi, Bluetooth, Ethernet), call the function esp_read_mac() function.
In ESP-IDF these addresses are calculated from a single Base MAC address. By default, the Espressif base MAC address is used. This MAC is pre-programmed into ESP32-S3 eFuse from the factory.

Interface
Wi-Fi Station Wi-Fi SoftAP Bluetooth Ethernet

MAC address (4 universally administered, de- MAC address (2 universally adminis-

fault)

tered)

base_mac

base_mac

base_mac, +1 to the last octet
base_mac, +2 to the last octet base_mac, +3 to the last octet

Local MAC derived from Wi-Fi Station MAC) base_mac, +1 to the last octet Local MAC (derived from Bluetooth MAC)

Note: The default configuration is 4 universally administered MAC addresses, and this is recommended when using Espressif-provided MAC addresses.

Note: ESP32-S3 has no integrated Ethernet MAC, but itns still possible to calculate an Ethernet MAC address. This MAC address can only be used with an external interface such as an SPI-Ethernet device, see Ethernet.

Custom Base MAC The default Base MAC is pre-programmed by Espressif in eFuse BLK1. To set a custom Base MAC instead, call the function esp_base_mac_addr_set() before initializing any network interfaces or calling the esp_read_mac() function. The customized MAC address can be stored in any supported storage device (e.g. Flash, NVS, etc).

Espressif Systems

1312

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
The custom base MAC addresses should be allocated such that derived MAC addresses will not overlap. Configure the option CONFIG_ESP32S3_UNIVERSAL_MAC_ADDRESSES to set the number of valid universal MAC addresses that can be derived from the custom base MAC, according to the table above.
Note: It is also possible to call the function esp_netif_set_mac() to set the specific MAC used by a network interface, after network initialization. Itns recommended to use the Base MAC approach documented here instead, to avoid the possibility of the original MAC address briefly appearing on the network before it is changed.

Custom MAC address in eFuse When reading custom MAC addresses from eFuse, ESP-IDF provides a helper function esp_efuse_mac_get_custom(). This loads the MAC address from eFuse BLK3. This function assumes that the custom base MAC address is stored in the following format:

Field

# of bits Range of bits

MAC address 48

200:248

Note: The eFuse BLK3 uses RS-coding during a burn operation it means that all eFuse fields in this block must be burnt at the same time.
Once MAC address has been obtained using esp_efuse_mac_get_custom(), call esp_base_mac_addr_set() to set this MAC address as base MAC address.

Local vs Universal MAC addresses ESP32-S3 comes pre-programmed with enough valid Espressif universally administered MAC addresses for all internal interfaces. The specific calculations to derive an interfacens MAC address from the base MAC address is shown in the table above.
When using a custom MAC address scheme, itns possible that not all interfaces can be assigned a universally administered MAC address. In these cases, a locally administered MAC address is assigned. Note that these addresses are intended for use on a single local network, only.
See this article for the definition of local and universally administered MAC addresses.
Function esp_derive_local_mac() is called internally to derive a local MAC address from a universal MAC address. The process is as follows:
1. The U/L bit (bit value 0x2) is set in the first octet of the universal MAC address, creating a local MAC address. 2. If this bit is already set in the supplied universal MAC address (meaning: the supplied ouniversalpMAC
address was in fact already a local MAC address), then the first octet of the local MAC address is XORed with 0x4.

Chip version
esp_chip_info() function fills esp_chip_info_t structure with information about the chip. This includes the chip revision, number of CPU cores, and a bit mask of features enabled in the chip.

SDK version
esp_get_idf_version() returns a string describing the IDF version which was used to compile the application. This is the same value as the one available through IDF_VER variable of the build system. The version string generally has the format of git describe output.
To get the version at build time, additional version macros are provided. They can be used to enable or disable parts of the program depending on IDF version.
· ESP_IDF_VERSION_MAJOR, ESP_IDF_VERSION_MINOR, ESP_IDF_VERSION_PATCH are defined to integers representing major, minor, and patch version.

Espressif Systems

1313

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· ESP_IDF_VERSION_VAL and ESP_IDF_VERSION can be used when implementing version checks:
#include "esp_idf_version.h"
#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(4, 0, 0) // enable functionality present in IDF v4.0
#endif
App version
Application version is stored in esp_app_desc_t structure. It is located in DROM sector and has a fixed offset from the beginning of the binary file. The structure is located after esp_image_header_t and esp_image_segment_header_t structures. The field version has string type and max length 32 chars. To set version in your project manually you need to set PROJECT_VER variable in your project CMakeLists.txt/Makefile:
· In application CMakeLists.txt put set(PROJECT_VER "0.1.0.1") before including project. cmake.
If CONFIG_APP_PROJECT_VER_FROM_CONFIG option is set, the value of CONFIG_APP_PROJECT_VER will be used. Otherwise, if PROJECT_VER variable is not set in the project then it will be retrieved from either $(PROJECT_PATH)/version.txt file (if present) else using git command git describe. If neither is available then PROJECT_VER will be set to o1p. Application can make use of this by calling esp_ota_get_app_description() or esp_ota_get_partition_description() functions.
API Reference
Header File · components/esp_system/include/esp_system.h
Functions esp_err_t esp_register_shutdown_handler(shutdown_handler_t handle)
Register shutdown handler. This function allows you to register a handler that gets invoked before the application is restarted using esp_restart function. Return
· ESP_OK on success · ESP_ERR_INVALID_STATE if the handler has already been registered · ESP_ERR_NO_MEM if no more shutdown handler slots are available Parameters · handle: function to execute on restart esp_err_t esp_unregister_shutdown_handler(shutdown_handler_t handle) Unregister shutdown handler. This function allows you to unregister a handler which was previously registered using esp_register_shutdown_handler function. · ESP_OK on success · ESP_ERR_INVALID_STATE if the given handler hasnnt been registered before void esp_restart(void) Restart PRO and APP CPUs. This function can be called both from PRO and APP CPUs. After successful restart, CPU reset reason will be SW_CPU_RESET. Peripherals (except for Wi-Fi, BT, UART0, SPI1, and legacy timers) are not reset. This function does not return.

Espressif Systems

1314

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_reset_reason_t esp_reset_reason(void) Get reason of last reset.
Return See description of esp_reset_reason_t for explanation of each value.
uint32_t esp_get_free_heap_size(void) Get the size of available heap.
Note Note that the returned value may be larger than the maximum contiguous block which can be allocated. Return Available heap size, in bytes.
uint32_t esp_get_free_internal_heap_size(void) Get the size of available internal heap.
Note Note that the returned value may be larger than the maximum contiguous block which can be allocated. Return Available internal heap size, in bytes.
uint32_t esp_get_minimum_free_heap_size(void) Get the minimum heap that has ever been available.
Return Minimum free heap ever available
void esp_system_abort(const char *details) Trigger a software abort.
Parameters · details: Details that will be displayed during panic handling.

Type Definitions typedef void (*shutdown_handler_t)(void)
Shutdown handler type

Enumerations enum esp_reset_reason_t
Reset reasons.
Values:
ESP_RST_UNKNOWN Reset reason can not be determined.
ESP_RST_POWERON Reset due to power-on event.
ESP_RST_EXT Reset by external pin (not applicable for ESP32)
ESP_RST_SW Software reset via esp_restart.
ESP_RST_PANIC Software reset due to exception/panic.
ESP_RST_INT_WDT Reset (software or hardware) due to interrupt watchdog.
ESP_RST_TASK_WDT Reset due to task watchdog.
ESP_RST_WDT Reset due to other watchdogs.
ESP_RST_DEEPSLEEP Reset after exiting deep sleep mode.
ESP_RST_BROWNOUT Brownout reset (software or hardware)

Espressif Systems

1315

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_RST_SDIO Reset over SDIO.
Header File · components/esp_common/include/esp_idf_version.h
Functions const char *esp_get_idf_version(void)
Return full IDF version string, same as mgit describenoutput. Note If you are printing the ESP-IDF version in a log file or other information, this function provides more
information than using the numerical version macros. For example, numerical version macros donnt differentiate between development, pre-release and release versions, but the output of this function does. Return constant string from IDF_VER
Macros ESP_IDF_VERSION_MAJOR
Major version number (X.x.x) ESP_IDF_VERSION_MINOR
Minor version number (x.X.x) ESP_IDF_VERSION_PATCH
Patch version number (x.x.X) ESP_IDF_VERSION_VAL(major, minor, patch)
Macro to convert IDF version number into an integer To be used in comparisons, such as ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(4, 0, 0) ESP_IDF_VERSION Current IDF version, as an integer To be used in comparisons, such as ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(4, 0, 0)
Header File · components/esp_hw_support/include/esp_mac.h
Functions esp_err_t esp_base_mac_addr_set(const uint8_t *mac)
Set base MAC address with the MAC address which is stored in BLK3 of EFUSE or external storage e.g. flash and EEPROM. Base MAC address is used to generate the MAC addresses used by network interfaces. If using a custom base MAC address, call this API before initializing any network interfaces. Refer to the ESP-IDF Programming Guide for details about how the Base MAC is used. Note Base MAC must be a unicast MAC (least significant bit of first byte must be zero). Note If not using a valid OUI, set the olocally administeredpbit (bit value 0x02 in the first byte) to avoid
collisions. Return ESP_OK on success ESP_ERR_INVALID_ARG If mac is NULL or is not a unicast MAC Parameters
· mac: base MAC address, length: 6 bytes/8 bytes. length: 6 bytes for MAC-48 8 bytes for EUI64(used for IEEE 802.15.4)
esp_err_t esp_base_mac_addr_get(uint8_t *mac) Return base MAC address which is set using esp_base_mac_addr_set. Note If no custom Base MAC has been set, this returns the pre-programmed Espressif base MAC address.

Espressif Systems

1316

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return ESP_OK on success ESP_ERR_INVALID_ARG mac is NULL ESP_ERR_INVALID_MAC base MAC address has not been set
Parameters · mac: base MAC address, length: 6 bytes/8 bytes. length: 6 bytes for MAC-48 8 bytes for EUI64(used for IEEE 802.15.4)
esp_err_t esp_efuse_mac_get_custom(uint8_t *mac) Return base MAC address which was previously written to BLK3 of EFUSE.
Base MAC address is used to generate the MAC addresses used by the networking interfaces. This API returns the custom base MAC address which was previously written to EFUSE BLK3 in a specified format.
Writing this EFUSE allows setting of a different (non-Espressif) base MAC address. It is also possible to store a custom base MAC address elsewhere, see esp_base_mac_addr_set() for details.
Note This function is currently only supported on ESP32. Return ESP_OK on success ESP_ERR_INVALID_ARG mac is NULL ESP_ERR_INVALID_MAC CUS-
TOM_MAC address has not been set, all zeros (for esp32-xx) ESP_ERR_INVALID_VERSION An invalid MAC version field was read from BLK3 of EFUSE (for esp32) ESP_ERR_INVALID_CRC An invalid MAC CRC was read from BLK3 of EFUSE (for esp32) Parameters
· mac: base MAC address, length: 6 bytes/8 bytes. length: 6 bytes for MAC-48 8 bytes for EUI64(used for IEEE 802.15.4)
esp_err_t esp_efuse_mac_get_default(uint8_t *mac) Return base MAC address which is factory-programmed by Espressif in EFUSE.
Return ESP_OK on success ESP_ERR_INVALID_ARG mac is NULL Parameters
· mac: base MAC address, length: 6 bytes/8 bytes. length: 6 bytes for MAC-48 8 bytes for EUI64(used for IEEE 802.15.4)
esp_err_t esp_read_mac(uint8_t *mac, esp_mac_type_t type) Read base MAC address and set MAC address of the interface.
This function first get base MAC address using esp_base_mac_addr_get(). Then calculates the MAC address of the specific interface requested, refer to ESP-IDF Programming Guide for the algorithm.
Return ESP_OK on success Parameters
· mac: base MAC address, length: 6 bytes/8 bytes. length: 6 bytes for MAC-48 8 bytes for EUI64(used for IEEE 802.15.4)
· type: Type of MAC address to return
esp_err_t esp_derive_local_mac(uint8_t *local_mac, const uint8_t *universal_mac) Derive local MAC address from universal MAC address.
This function copies a universal MAC address and then sets the olocally
administeredpbit (bit 0x2) in the first octet, creating a locally administered MAC address.
If the universal MAC address argument is already a locally administered MAC address, then the first octet is XORed with 0x4 in order to create a different locally administered MAC address.
Return ESP_OK on success Parameters
· mac: base MAC address, length: 6 bytes/8 bytes. length: 6 bytes for MAC-48 8 bytes for EUI64(used for IEEE 802.15.4)
· universal_mac: Source universal MAC address, length: 6 bytes.

Enumerations enum esp_mac_type_t
Values:
ESP_MAC_WIFI_STA

Espressif Systems

1317

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_MAC_WIFI_SOFTAP ESP_MAC_BT ESP_MAC_ETH ESP_MAC_IEEE802154
2.7.20 Over The Air Updates (OTA)
OTA Process Overview
The OTA update mechanism allows a device to update itself based on data received while the normal firmware is running (for example, over Wi-Fi or Bluetooth.) OTA requires configuring the Partition Table of the device with at least two oOTA app slotppartitions (i.e. ota_0 and ota_1) and an oOTA Data Partitionp. The OTA operation functions write a new app firmware image to whichever OTA app slot that is currently not selected for booting. Once the image is verified, the OTA Data partition is updated to specify that this image should be used for the next boot.
OTA Data Partition
An OTA data partition (type data, subtype ota) must be included in the Partition Table of any project which uses the OTA functions. For factory boot settings, the OTA data partition should contain no data (all bytes erased to 0xFF). In this case the esp-idf software bootloader will boot the factory app if it is present in the partition table. If no factory app is included in the partition table, the first available OTA slot (usually ota_0) is booted. After the first OTA update, the OTA data partition is updated to specify which OTA app slot partition should be booted next. The OTA data partition is two flash sectors (0x2000 bytes) in size, to prevent problems if there is a power failure while it is being written. Sectors are independently erased and written with matching data, and if they disagree a counter field is used to determine which sector was written more recently.
App rollback
The main purpose of the application rollback is to keep the device working after the update. This feature allows you to roll back to the previous working application in case a new application has critical errors. When the rollback process is enabled and an OTA update provides a new version of the app, one of three things can happen:
· The application works fine, esp_ota_mark_app_valid_cancel_rollback() marks the running application with the state ESP_OTA_IMG_VALID. There are no restrictions on booting this application.
· The application has critical errors and further work is not possible, a rollback to the previous application is required, esp_ota_mark_app_invalid_rollback_and_reboot() marks the running application with the state ESP_OTA_IMG_INVALID and reset. This application will not be selected by the bootloader for boot and will boot the previously working application.
· If the CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is set, and a reset occurs without calling either function then the application is rolled back.
Note: The state is not written to the binary image of the application but rather to the otadata partition. The partition contains a ota_seq counter which is a pointer to the slot (ota_0, ota_1, l) from which the application will be selected for boot.

Espressif Systems

1318

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

App OTA State States control the process of selecting a boot app:

States

Restriction of selecting a boot app in bootloader

ESP_OTA_IMG_VALNIDone restriction. Will be selected.

ESP_OTA_IMG_UNDNEoFneINreEsDtriction. Will be selected.

ESP_OTA_IMG_INVWALilIlDnot be selected.

ESP_OTA_IMG_ABOWRiTllEnDot be selected.

ESP_OTA_IMG_NEWIf CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is set it will

be selected only once. In bootloader the state immediately changes to

ESP_OTA_IMG_PENDING_VERIFY.

ESP_OTA_IMG_PENIDf ICNOGN_FVIGE_RBIOFYOTLOADER_APP_ROLLBACK_ENABLE option is set it will not be se-

lected, and the state will change to ESP_OTA_IMG_ABORTED.

If CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is not enabled (by default), then the use of the following functions esp_ota_mark_app_valid_cancel_rollback() and esp_ota_mark_app_invalid_rollback_and_reboot() are optional, and ESP_OTA_IMG_NEW and ESP_OTA_IMG_PENDING_VERIFY states are not used.
An option in Kconfig CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE allows you to track the first boot of a new application. In this case, the application must confirm its operability by calling esp_ota_mark_app_valid_cancel_rollback() function, otherwise the application will be rolled back upon reboot. It allows you to control the operability of the application during the boot phase. Thus, a new application has only one attempt to boot successfully.

Rollback Process The description of the rollback FIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is enabled:

process

when

CON-

· The new application is successfully downloaded and esp_ota_set_boot_partition() function makes this partition bootable and sets the state ESP_OTA_IMG_NEW. This state means that the application is new and should be monitored for its first boot.
· Reboot esp_restart(). · The bootloader checks for the ESP_OTA_IMG_PENDING_VERIFY state if it is set, then it will be written
to ESP_OTA_IMG_ABORTED. · The bootloader selects a new application to boot so that the state is not set as ESP_OTA_IMG_INVALID or
ESP_OTA_IMG_ABORTED. · The bootloader checks the selected application for ESP_OTA_IMG_NEW state if it is set, then it will
be written to ESP_OTA_IMG_PENDING_VERIFY. This state means that the application requires confirmation of its operability, if this does not happen and a reboot occurs, this state will be overwritten to ESP_OTA_IMG_ABORTED (see above) and this application will no longer be able to start, i.e. there will be a rollback to the previous working application. · A new application has started and should make a self-test. · If the self-test has completed successfully, then you must call the function esp_ota_mark_app_valid_cancel_rollback() because the application is awaiting confirmation of operability (ESP_OTA_IMG_PENDING_VERIFY state). · If the self-test fails then call esp_ota_mark_app_invalid_rollback_and_reboot() function to roll back to the previous working application, while the invalid application is set ESP_OTA_IMG_INVALID state. · If the application has not been confirmed, the state remains ESP_OTA_IMG_PENDING_VERIFY, and the next boot it will be changed to ESP_OTA_IMG_ABORTED. That will prevent re-boot of this application. There will be a rollback to the previous working application.

Unexpected Reset If a power loss or an unexpected crash occurs at the time of the first boot of a new application, it will roll back the application.
Recommendation: Perform the self-test procedure as quickly as possible, to prevent rollback due to power loss.
Only OTA partitions can be rolled back. Factory partition is not rolled back.

Espressif Systems

1319

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Booting invalid/aborted apps Booting an application which was previously set to ESP_OTA_IMG_INVALID or ESP_OTA_IMG_ABORTED is possible:
· Get the last invalid application partition esp_ota_get_last_invalid_partition(). · Pass the received partition to esp_ota_set_boot_partition(), this will update the otadata. · Restart esp_restart(). The bootloader will boot the specified application.
To determine if self-tests should be run during startup of an application, call the esp_ota_get_state_partition() function. If result is ESP_OTA_IMG_PENDING_VERIFY then self-testing and subsequent confirmation of operability is required.

Where the states are set A brief description of where the states are set:
· ESP_OTA_IMG_VALID state is set by esp_ota_mark_app_valid_cancel_rollback() function.
· ESP_OTA_IMG_UNDEFINED state is set by esp_ota_set_boot_partition() function if CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is not enabled.
· ESP_OTA_IMG_NEW state is set by esp_ota_set_boot_partition() function if CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is enabled.
· ESP_OTA_IMG_INVALID state is set by esp_ota_mark_app_invalid_rollback_and_reboot() function.
· ESP_OTA_IMG_ABORTED state is set if there was no confirmation of the application operability and occurs reboots (if CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is enabled).
· ESP_OTA_IMG_PENDING_VERIFY state is set in a bootloader if CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is enabled and selected app has ESP_OTA_IMG_NEW state.

Anti-rollback
Anti-rollback prevents rollback to application with security version lower than one programmed in eFuse of chip.
This function works if set CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK option. In the bootloader, when selecting a bootable application, an additional security version check is added which is on the chip and in the application image. The version in the bootable firmware must be greater than or equal to the version in the chip.
CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK and CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE options are used together. In this case, rollback is possible only on the security version which is equal or higher than the version in the chip.

A typical anti-rollback scheme is
· New firmware released with the elimination of vulnerabilities with the previous version of security. · After the developer makes sure that this firmware is working. He can increase the security version and release
a new firmware. · Download new application. · To make it bootable, run the function esp_ota_set_boot_partition(). If the security version of
the new application is smaller than the version in the chip, the new application will be erased. Update to new firmware is not possible. · Reboot. · In the bootloader, an application with a security version greater than or equal to the version in the chip will be selected. If otadata is in the initial state, and one firmware was loaded via a serial channel, whose secure version is higher than the chip, then the secure version of efuse will be immediately updated in the bootloader. · New application booted. Then the application should perform diagnostics of the operation and if it is completed successfully, you should call esp_ota_mark_app_valid_cancel_rollback() function to mark the running application with the ESP_OTA_IMG_VALID state and update the secure version on chip. Note that if was called esp_ota_mark_app_invalid_rollback_and_reboot() function a rollback may not happen as the device may not have any bootable apps. It will then return ESP_ERR_OTA_ROLLBACK_FAILED error and stay in the ESP_OTA_IMG_PENDING_VERIFY state. · The next update of app is possible if a running app is in the ESP_OTA_IMG_VALID state.

Espressif Systems

1320

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Recommendation:
If you want to avoid the download/erase overhead in case of the app from the server has security version lower than the running app, you have to get new_app_info.secure_version from the first package of an image and compare it with the secure version of efuse. Use esp_efuse_check_secure_version(new_app_info. secure_version) function if it is true then continue downloading otherwise abort.

.... bool image_header_was_checked = false; while (1) {
int data_read = esp_http_client_read(client, ota_write_data, BUFFSIZE); ... if (data_read > 0) {
if (image_header_was_checked == false) { esp_app_desc_t new_app_info; if (data_read > sizeof(esp_image_header_t) + sizeof(esp_image_segment_
header_t) + sizeof(esp_app_desc_t)) { // check current version with downloading if (esp_efuse_check_secure_version(new_app_info.secure_version) ==
false) { ESP_LOGE(TAG, "This a new app can not be downloaded due to a
secure version is lower than stored in efuse."); http_cleanup(client); task_fatal_error();
}

image_header_was_checked = true;

} } ...

esp_ota_begin(update_partition, OTA_SIZE_UNKNOWN, &update_handle); } } esp_ota_write( update_handle, (const void *)ota_write_data, data_read);

Restrictions:

· The number of bits in the secure_version field is limited to 16 bits. This means that only 16 times you can do an anti-rollback. You can reduce the length of this efuse field using CONFIG_BOOTLOADER_APP_SEC_VER_SIZE_EFUSE_FIELD option.
· Factory and Test partitions are not supported in anti rollback scheme and hence partition table should not have partition with SubType set to factory or test.

security_version:

· In application image it is stored in esp_app_desc structure. FIG_BOOTLOADER_APP_SECURE_VERSION.

The number is set CON-

Secure OTA Updates Without Secure boot
The verification of signed OTA updates can be performed even without enabling hardware secure boot. This can be achieved by setting CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT and CONFIG_SECURE_SIGNED_ON_UPDATE_NO_SECURE_BOOT

OTA Tool (otatool.py)
The component app_update provides a tool otatool.py for performing OTA partition-related operations on a target device. The following operations can be performed using the tool:
· read contents of otadata partition (read_otadata) · erase otadata partition, effectively resetting device to factory app (erase_otadata)

Espressif Systems

1321

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· switch OTA partitions (switch_ota_partition) · erasing OTA partition (erase_ota_partition) · write to OTA partition (write_ota_partition) · read contents of OTA partition (read_ota_partition)
The tool can either be imported and used from another Python script or invoked from shell script for users wanting to perform operation programmatically. This is facilitated by the toolns Python API and command-line interface, respectively.

Python API Before anything else, make sure that the otatool module is imported.
import sys import os
idf_path = os.environ["IDF_PATH"] # get value of IDF_PATH from environment otatool_dir = os.path.join(idf_path, "components", "app_update") # otatool.py lives in $IDF_PATH/components/app_update
sys.path.append(otatool_dir) # this enables Python to find otatool module from otatool import * # import all names inside otatool module
The starting point for using the toolns Python API to do is create a OtatoolTarget object:
# Create a partool.py target device connected on serial port /dev/ttyUSB1 target = OtatoolTarget("/dev/ttyUSB1")
The created object can now be used to perform operations on the target device:
# Erase otadata, reseting the device to factory app target.erase_otadata()
# Erase contents of OTA app slot 0 target.erase_ota_partition(0)
# Switch boot partition to that of app slot 1 target.switch_ota_partition(1)
# Read OTA partition 'ota_3' and save contents to a file named 'ota_3.bin' target.read_ota_partition("ota_3", "ota_3.bin")
The OTA partition to operate on is specified using either the app slot number or the partition name. More information on the Python API is available in the docstrings for the tool.

Command-line Interface The command-line interface of otatool.py has the following structure:
otatool.py [command-args] [subcommand] [subcommand-args]
- command-args - these are arguments that are needed for executing the main command (parttool.py), mostly pertaining to the target device - subcommand - this is the operation to be performed - subcommand-args - these are arguments that are specific to the chosen operation

# Erase otadata, resetting the device to factory app otatool.py --port "/dev/ttyUSB1" erase_otadata
# Erase contents of OTA app slot 0 otatool.py --port "/dev/ttyUSB1" erase_ota_partition --slot 0
# Switch boot partition to that of app slot 1

(continues on next page)

Espressif Systems

1322

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

otatool.py --port "/dev/ttyUSB1" switch_ota_partition --slot 1

(continued from previous page)

# Read OTA partition 'ota_3' and save contents to a file named 'ota_3.bin' otatool.py --port "/dev/ttyUSB1" read_ota_partition --name=ota_3 --output=ota_3.bin

More information can be obtained by specifying help as argument:
# Display possible subcommands and show main command argument descriptions otatool.py --help

# Show descriptions for specific subcommand arguments otatool.py [subcommand] --help

See also
· Partition Table documentation · Lower-Level SPI Flash/Partition API · ESP HTTPS OTA

Application Example End-to-end example of OTA firmware update workflow: system/ota.

API Reference
Header File · components/app_update/include/esp_ota_ops.h

Functions const esp_app_desc_t *esp_ota_get_app_description(void)
Return esp_app_desc structure. This structure includes app version.

Return description for running app.

Return Pointer to esp_app_desc structure. int esp_ota_get_app_elf_sha256(char *dst, size_t size)
Fill the provided buffer with SHA256 of the ELF file, formatted as hexadecimal, null-terminated. If the buffer size is not sufficient to fit the entire SHA256 in hex plus a null terminator, the largest possible number of bytes will be written followed by a null.

Return Number of bytes written to dst (including null terminator) Parameters
· dst: Destination buffer · size: Size of the buffer

esp_err_t esp_ota_begin(const esp_partition_t *partition, size_t image_size, esp_ota_handle_t *out_handle)
Commence an OTA update writing to the specified partition.

The specified partition is erased to the specified image size.

If image size is not yet known, pass OTA_SIZE_UNKNOWN which will cause the entire partition to be erased.

On success, this function allocates memory that remains in use until esp_ota_end() is called with the returned handle.

Note:

If the rollback option is enabled and the running application has

the ESP_OTA_IMG_PENDING_VERIFY state then it will lead to the

Espressif Systems

1323

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_ERR_OTA_ROLLBACK_INVALID_STATE error. Confirm the running app before to run download a new app, use esp_ota_mark_app_valid_cancel_rollback() function for it (this should be done as early as possible when you first download a new application).
Return · ESP_OK: OTA operation commenced successfully. · ESP_ERR_INVALID_ARG: partition or out_handle arguments were NULL, or partition doesnnt point to an OTA app partition. · ESP_ERR_NO_MEM: Cannot allocate memory for OTA operation. · ESP_ERR_OTA_PARTITION_CONFLICT: Partition holds the currently running firmware, cannot update in place. · ESP_ERR_NOT_FOUND: Partition argument not found in partition table. · ESP_ERR_OTA_SELECT_INFO_INVALID: The OTA data partition contains invalid data. · ESP_ERR_INVALID_SIZE: Partition doesnnt fit in configured flash size. · ESP_ERR_FLASH_OP_TIMEOUT or ESP_ERR_FLASH_OP_FAIL: Flash write failed. · ESP_ERR_OTA_ROLLBACK_INVALID_STATE: If the running app has not confirmed state. Before performing an update, the application must be valid.
Parameters · partition: Pointer to info for partition which will receive the OTA update. Required. · image_size: Size of new OTA app image. Partition will be erased in order to receive this size of image. If 0 or OTA_SIZE_UNKNOWN, the entire partition is erased. · out_handle: On success, returns a handle which should be used for subsequent esp_ota_write() and esp_ota_end() calls.
esp_err_t esp_ota_write(esp_ota_handle_t handle, const void *data, size_t size) Write OTA update data to partition.
This function can be called multiple times as data is received during the OTA operation. Data is written sequentially to the partition.
Return · ESP_OK: Data was written to flash successfully. · ESP_ERR_INVALID_ARG: handle is invalid. · ESP_ERR_OTA_VALIDATE_FAILED: First byte of image contains invalid app image magic byte. · ESP_ERR_FLASH_OP_TIMEOUT or ESP_ERR_FLASH_OP_FAIL: Flash write failed. · ESP_ERR_OTA_SELECT_INFO_INVALID: OTA data partition has invalid contents
Parameters · handle: Handle obtained from esp_ota_begin · data: Data buffer to write · size: Size of data buffer in bytes.
esp_err_t esp_ota_write_with_offset(esp_ota_handle_t handle, const void *data, size_t size, uint32_t offset)
Write OTA update data to partition at an offset.
This function can write data in non-contiguous manner. If flash encryption is enabled, data should be 16 bytes aligned.
Note While performing OTA, if the packets arrive out of order, esp_ota_write_with_offset() can be used to write data in non-contiguous manner. Use of esp_ota_write_with_offset() in combination with esp_ota_write() is not recommended.
Return · ESP_OK: Data was written to flash successfully. · ESP_ERR_INVALID_ARG: handle is invalid. · ESP_ERR_OTA_VALIDATE_FAILED: First byte of image contains invalid app image magic byte. · ESP_ERR_FLASH_OP_TIMEOUT or ESP_ERR_FLASH_OP_FAIL: Flash write failed. · ESP_ERR_OTA_SELECT_INFO_INVALID: OTA data partition has invalid contents
Parameters · handle: Handle obtained from esp_ota_begin · data: Data buffer to write · size: Size of data buffer in bytes · offset: Offset in flash partition

Espressif Systems

1324

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t esp_ota_end(esp_ota_handle_t handle) Finish OTA update and validate newly written app image.

Note After calling esp_ota_end(), the handle is no longer valid and any memory associated with it is freed (regardless of result).
Return · ESP_OK: Newly written OTA app image is valid. · ESP_ERR_NOT_FOUND: OTA handle was not found. · ESP_ERR_INVALID_ARG: Handle was never written to. · ESP_ERR_OTA_VALIDATE_FAILED: OTA image is invalid (either not a valid app image, or if secure boot is enabled - signature failed to verify.) · ESP_ERR_INVALID_STATE: If flash encryption is enabled, this result indicates an internal error writing the final encrypted bytes to flash.
Parameters · handle: Handle obtained from esp_ota_begin().

esp_err_t esp_ota_abort(esp_ota_handle_t handle) Abort OTA update, free the handle and memory associated with it.

Return · ESP_OK: Handle and its associated memory is freed successfully. · ESP_ERR_NOT_FOUND: OTA handle was not found.
Parameters · handle: obtained from esp_ota_begin().

esp_err_t esp_ota_set_boot_partition(const esp_partition_t *partition) Configure OTA data for a new boot partition.

Note If this function returns ESP_OK, calling esp_restart() will boot the newly configured app partition. Return
· ESP_OK: OTA data updated, next reboot will use specified partition. · ESP_ERR_INVALID_ARG: partition argument was NULL or didnnt point to a valid OTA partition
of type oappp. · ESP_ERR_OTA_VALIDATE_FAILED: Partition contained invalid app image. Also returned if
secure boot is enabled and signature validation failed. · ESP_ERR_NOT_FOUND: OTA data partition not found. · ESP_ERR_FLASH_OP_TIMEOUT or ESP_ERR_FLASH_OP_FAIL: Flash erase or write failed. Parameters · partition: Pointer to info for partition containing app image to boot.

const esp_partition_t *esp_ota_get_boot_partition(void) Get partition info of currently configured boot app.

If esp_ota_set_boot_partition() has been called, the partition which was set by that function will be returned.

If esp_ota_set_boot_partition() has not been called, the result is usually the same as esp_ota_get_running_partition(). The two results are not equal if the configured boot partition does not contain a valid app (meaning that the running partition will be an app that the bootloader chose via fallback).

If the OTA data partition is not present or not valid then the result is the first app partition found in the partition table. In priority order, this means: the factory app, the first OTA app slot, or the test app partition.

Note that there is no guarantee the returned partition is a valid app.

Use

esp_image_verify(ESP_IMAGE_VERIFY, l) to verify if the returned partition contains a bootable

image.

Return Pointer to info for partition structure, or NULL if partition table is invalid or a flash read operation failed. Any returned pointer is valid for the lifetime of the application.

const esp_partition_t *esp_ota_get_running_partition(void) Get partition info of currently running app.

This function is different to esp_ota_get_boot_partition() in that it ignores any change of selected boot partition caused by esp_ota_set_boot_partition(). Only the app whose code is currently running will have its partition

Espressif Systems

1325

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

information returned.

The partition returned by this function may also differ from esp_ota_get_boot_partition() if the configured boot partition is somehow invalid, and the bootloader fell back to a different app partition at boot.

Return Pointer to info for partition structure, or NULL if no partition is found or flash read operation failed. Returned pointer is valid for the lifetime of the application.

const esp_partition_t *esp_ota_get_next_update_partition(const *start_from)
Return the next OTA app partition which should be written with a new firmware.

esp_partition_t

Call this function to find an OTA app partition which can be passed to esp_ota_begin().

Finds next partition round-robin, starting from the current running partition.

Return Pointer to info for partition which should be updated next. NULL result indicates invalid OTA data partition, or that no eligible OTA app slot partition was found.
Parameters · start_from: If set, treat this partition info as describing the current running partition. Can be NULL, in which case esp_ota_get_running_partition() is used to find the currently running partition. The result of this function is never the same as this argument.

esp_err_t esp_ota_get_partition_description(const

esp_partition_t

esp_app_desc_t *app_desc)

Returns esp_app_desc structure for app partition. This structure includes app version.

*partition,

Returns a description for the requested app partition.

Return · ESP_OK Successful. · ESP_ERR_NOT_FOUND app_desc structure is not found. Magic word is incorrect. · ESP_ERR_NOT_SUPPORTED Partition is not application. · ESP_ERR_INVALID_ARG Arguments is NULL or if partitionns offset exceeds partition size. · ESP_ERR_INVALID_SIZE Read would go out of bounds of the partition. · or one of error codes from lower-level flash driver.
Parameters · [in] partition: Pointer to app partition. (only app partition) · [out] app_desc: Structure of info about app.

uint8_t esp_ota_get_app_partition_count(void) Returns number of ota partitions provided in partition table.

Return · Number of OTA partitions

esp_err_t esp_ota_mark_app_valid_cancel_rollback(void) This function is called to indicate that the running app is working well.

Return · ESP_OK: if successful.

esp_err_t esp_ota_mark_app_invalid_rollback_and_reboot(void) This function is called to roll back to the previously workable app with reboot.

If rollback is successful then device will reset else API will return with error code. Checks applications on a flash drive that can be booted in case of rollback. If the flash does not have at least one app (except the running app) then rollback is not possible.

Return · ESP_FAIL: if not successful. · ESP_ERR_OTA_ROLLBACK_FAILED: The rollback is not possible due to flash does not have any apps.

const esp_partition_t *esp_ota_get_last_invalid_partition(void) Returns last partition with invalid state (ESP_OTA_IMG_INVALID or ESP_OTA_IMG_ABORTED).

Espressif Systems

1326

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Return partition.

esp_err_t esp_ota_get_state_partition(const esp_partition_t *partition, esp_ota_img_states_t

Returns state for given partition.

*ota_state)

Return · ESP_OK: Successful. · ESP_ERR_INVALID_ARG: partition or ota_state arguments were NULL. · ESP_ERR_NOT_SUPPORTED: partition is not ota. · ESP_ERR_NOT_FOUND: Partition table does not have otadata or state was not found for given partition.
Parameters · [in] partition: Pointer to partition. · [out] ota_state: state of partition (if this partition has a record in otadata).

esp_err_t esp_ota_erase_last_boot_app_partition(void) Erase previous boot app partition and corresponding otadata select for this partition.

When current app is marked to as valid then you can erase previous app partition.

Return · ESP_OK: Successful, otherwise ESP_ERR.

bool esp_ota_check_rollback_is_possible(void) Checks applications on the slots which can be booted in case of rollback.

These applications should be valid (marked in otadata as not UNDEFINED, INVALID or ABORTED and crc is good) and be able booted, and secure_version of app >= secure_version of efuse (if anti-rollback is enabled).

Return · True: Returns true if the slots have at least one app (except the running app). · False: The rollback is not possible.

esp_err_t esp_ota_revoke_secure_boot_public_key(esp_ota_secure_boot_public_key_index_t index)
Revokes the old signature digest. To be called in the application after the rollback logic.

Relevant for Secure boot v2 on ESP32-S2, ESP32-S3, ESP32-C3, ESP32-H2 where upto 3 key digests can be stored (Key #N-1, Key #N, Key #N+1). When key #N-1 used to sign an app is invalidated, an OTA update is to be sent with an app signed with key #N-1 & Key #N. After successfully booting the OTA app should call this function to revoke Key #N-1.

Return · ESP_OK: If revocation is successful. · ESP_ERR_INVALID_ARG: If the index of the public key to be revoked is incorrect. · ESP_FAIL: If secure boot v2 has not been enabled.
Parameters · index: - The index of the signature block to be revoked

Macros OTA_SIZE_UNKNOWN
Used for esp_ota_begin() if new image size is unknown OTA_WITH_SEQUENTIAL_WRITES
Used for esp_ota_begin() if new image size is unknown and erase can be done in incremental manner (assuming write operation is in continuous sequence)
ESP_ERR_OTA_BASE Base error code for ota_ops api
ESP_ERR_OTA_PARTITION_CONFLICT Error if request was to write or erase the current running partition
ESP_ERR_OTA_SELECT_INFO_INVALID Error if OTA data partition contains invalid content

Espressif Systems

1327

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_ERR_OTA_VALIDATE_FAILED Error if OTA app image is invalid
ESP_ERR_OTA_SMALL_SEC_VER Error if the firmware has a secure version less than the running firmware.
ESP_ERR_OTA_ROLLBACK_FAILED Error if flash does not have valid firmware in passive partition and hence rollback is not possible
ESP_ERR_OTA_ROLLBACK_INVALID_STATE Error if current active firmware is still marked in pending validation state (ESP_OTA_IMG_PENDING_VERIFY), essentially first boot of firmware image post upgrade and hence firmware upgrade is not possible
Type Definitions typedef uint32_t esp_ota_handle_t
Opaque handle for an application OTA update. esp_ota_begin() returns a handle which is then used for subsequent calls to esp_ota_write() and esp_ota_end().
Enumerations enum esp_ota_secure_boot_public_key_index_t
Secure Boot V2 public key indexes. Values: SECURE_BOOT_PUBLIC_KEY_INDEX_0
Points to the 0th index of the Secure Boot v2 public key SECURE_BOOT_PUBLIC_KEY_INDEX_1
Points to the 1st index of the Secure Boot v2 public key SECURE_BOOT_PUBLIC_KEY_INDEX_2
Points to the 2nd index of the Secure Boot v2 public key
Debugging OTA Failure
2.7.21 Performance Monitor
The Performance Monitor component provides APIs to use ESP32-S3 internal performance counters to profile functions and applications.
Application Example
An example which combines performance monitor is provided in examples/system/perfmon directory. This example initializes the performance monitor structure and execute them with printing the statistics.
High level API Reference
Header Files · perfmon/include/perfmon.h
API Reference
Header File · components/perfmon/include/xtensa_perfmon_access.h

Espressif Systems

1328

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Fig. 37: How to Debug When OTA Fails (click to enlarge)

Espressif Systems

1329

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Functions esp_err_t xtensa_perfmon_init(int id, uint16_t select, uint16_t mask, int kernelcnt, int tracelevel)
Init Performance Monitoor.
Initialize performance monitor register with define values
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if one of the arguments is not correct
Parameters · [in] id: performance counter number · [in] select: select value from PMCTRLx register · [in] mask: mask value from PMCTRLx register · [in] kernelcnt: kernelcnt value from PMCTRLx register · [in] tracelevel: tracelevel value from PMCTRLx register
esp_err_t xtensa_perfmon_reset(int id) Reset PM counter.
Reset PM counter. Writes 0 to the PMx register.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if id out of range
Parameters · [in] id: performance counter number
void xtensa_perfmon_start(void) Start PM counters.
Start all PM counters synchronously. Write 1 to the PGM register
void xtensa_perfmon_stop(void) Stop PM counters.
Stop all PM counters synchronously. Write 0 to the PGM register
uint32_t xtensa_perfmon_value(int id) Read PM counter.
Read value of defined PM counter.
Return · Performance counter value
Parameters · [in] id: performance counter number
esp_err_t xtensa_perfmon_overflow(int id) Read PM overflow state.
Read overflow value of defined PM counter.
Return · ESP_OK if there is no overflow (overflow = 0) · ESP_FAIL if overflow occure (overflow = 1)
Parameters · [in] id: performance counter number
void xtensa_perfmon_dump(void) Dump PM values.
Dump all PM register to the console.
Header File
· components/perfmon/include/xtensa_perfmon_apis.h

Espressif Systems

1330

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Functions esp_err_t xtensa_perfmon_exec(const xtensa_perfmon_config_t *config)
Execute PM.
Execute performance counter for dedicated function with defined parameters
Return · ESP_OK if no errors · ESP_ERR_INVALID_ARG if one of the required parameters not defined · ESP_FAIL - counter overflow
Parameters · [in] config: pointer to the configuration structure
void xtensa_perfmon_view_cb(void *params, uint32_t select, uint32_t mask, uint32_t value) Dump PM results.
Callback to dump perfmon result to a FILE* stream specified in perfmon_config_t::callback_params. If callback_params is set to NULL, will print to stdout
Parameters · [in] params: used parameters passed from configuration (callback_params). This parameter expected as FILE* hanle, where data will be stored. If this parameter NULL, then data will be stored to the stdout. · [in] select: select value for current counter · [in] mask: mask value for current counter · [in] value: counter value for current counter
Structures struct xtensa_perfmon_config
Performance monitor configuration structure.
Structure to configure performance counter to measure dedicated function
Public Members
int repeat_count how much times function will be called before the calback will be repeated
float max_deviation Difference between min and max counter number 0..1, 0 - no difference, 1 - not used
void *call_params This pointer will be passed to the call_function as a parameter
void (*call_function)(void *params) pointer to the function that have to be called
void (*callback)(void *params, uint32_t select, uint32_t mask, uint32_t value) pointer to the function that will be called with result parameters
void *callback_params parameter that will be passed to the callback
int tracelevel trace level for all counters. In case of negative value, the filter will be ignored. If itns >=0, then the perfmon will count only when interrupt level > tracelevel. Itns useful to monitor interrupts.
uint32_t counters_size amount of counter in the list
const uint32_t *select_mask list of the select/mask parameters

Espressif Systems

1331

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Type Definitions typedef struct xtensa_perfmon_config xtensa_perfmon_config_t
Performance monitor configuration structure.
Structure to configure performance counter to measure dedicated function
2.7.22 Power Management
Overview
Power management algorithm included in ESP-IDF can adjust the advanced peripheral bus (APB) frequency, CPU frequency, and put the chip into light sleep mode to run an application at smallest possible power consumption, given the requirements of application components.
Application components can express their requirements by creating and acquiring power management locks.
For example:
· Driver for a peripheral clocked from APB can request the APB frequency to be set to 80 MHz while the peripheral is used.
· RTOS can request the CPU to run at the highest configured frequency while there are tasks ready to run. · A peripheral driver may need interrupts to be enabled, which means it will have to request disabling light sleep.
Since requesting higher APB or CPU frequencies or disabling light sleep causes higher current consumption, please keep the usage of power management locks by components to a minimum.
Configuration
Power management can be enabled at compile time, using the option CONFIG_PM_ENABLE.
Enabling power management features comes at the cost of increased interrupt latency. Extra latency depends on a number of factors, such as the CPU frequency, single/dual core mode, whether or not frequency switch needs to be done. Minimum extra latency is 0.2 us (when the CPU frequency is 240 MHz and frequency scaling is not enabled). Maximum extra latency is 40 us (when frequency scaling is enabled, and a switch from 40 MHz to 80 MHz is performed on interrupt entry).
Dynamic frequency scaling (DFS) and automatic light sleep can be enabled in an application by calling the function esp_pm_configure(). Its argument is a structure defining the frequency scaling settings, esp_pm_config_esp32s3_t. In this structure, three fields need to be initialized:
· max_freq_mhz: Maximum CPU frequency in MHz, i.e., the frequency used when the ESP_PM_CPU_FREQ_MAX lock is acquired. This field will usually be set to the default CPU frequency.
· min_freq_mhz: Minimum CPU frequency in MHz, i.e., the frequency used when only the ESP_PM_APB_FREQ_MAX lock is acquired. This field can be set to the XTAL frequency value, or the XTAL frequency divided by an integer. Note that 10 MHz is the lowest frequency at which the default REF_TICK clock of 1 MHz can be generated.
· light_sleep_enable: Whether the system should automatically enter light sleep when no locks are acquired (true/false). Alternatively, if you enable the option CONFIG_PM_DFS_INIT_AUTO in menuconfig, the maximum CPU frequency will be determined by the CONFIG_ESP32S3_DEFAULT_CPU_FREQ_MHZ setting, and the minimum CPU frequency will be locked to the XTAL frequency.
Note: Automatic light sleep is based on FreeRTOS Tickless Idle functionality. If automatic light sleep is requested while the option CONFIG_FREERTOS_USE_TICKLESS_IDLE is not enabled in menuconfig, esp_pm_configure() will return the error ESP_ERR_NOT_SUPPORTED.

Note: In light sleep, peripherals are clock gated, and interrupts (from GPIOs and internal peripherals) will not be generated. A wakeup source described in the Sleep Modes documentation can be used to trigger wakeup from the

Espressif Systems

1332

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

light sleep state. For example, the EXT0 and EXT1 wakeup sources can be used to wake up the chip via a GPIO.

Power Management Locks

Applications have the ability to acquire/release locks in order to control the power management algorithm. When an application acquires a lock, the power management algorithm operation is restricted in a way described below. When the lock is released, such restrictions are removed.
Power management locks have acquire/release counters. If the lock has been acquired a number of times, it needs to be released the same number of times to remove associated restrictions.
ESP32-S3 supports three types of locks described in the table below.

Lock

Description

ESP_PM_CPU_FREQ_MAX Requests CPU frequency to be at the maximum value set

with esp_pm_configure(). For ESP32-S3, this value can be set to

80 MHz, 160 MHz, or 240 MHz.

ESP_PM_APB_FREQ_MAX Requests the APB frequency to be at the maximum supported value. For

ESP32-S3, this is 80 MHz.

ESP_PM_NO_LIGHT_SLEEP Disables automatic switching to light sleep.

ESP32-S3 Power Management Algorithm
The table below shows how CPU and APB frequencies will be switched if dynamic frequency scaling is enabled. You can specify the maximum CPU frequency with either esp_pm_configure() or CONFIG_ESP32S3_DEFAULT_CPU_FREQ_MHZ.

Espressif Systems

1333

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Max CPU Frequency Set 240
160
80

Lock Acquisition ESP_PM_CPU_FREQ_MAX acquired
ESP_PM_APB_FREQ_MAX acquired, ESP_PM_CPU_FREQ_MAX not acquired None
ESP_PM_CPU_FREQ_MAX acquired
ESP_PM_APB_FREQ_MAX acquired, ESP_PM_CPU_FREQ_MAX not acquired None
Any of ESP_PM_CPU_FREQ_MAX or ESP_PM_APB_FREQ_MAX acquired
None

CPU and APB Frequncies
CPU: 240 MHz APB: 80 MHz
CPU: 80 MHz APB: 80 MHz Min values for both frequencies set with esp_pm_configure()
CPU: 160 MHz APB: 80 MHz
CPU: 80 MHz APB: 80 MHz Min values for both frequencies set with esp_pm_configure()
CPU: 80 MHz APB: 80 MHz
Min values for both frequencies set with esp_pm_configure()

If none of the locks are acquired, and light sleep is enabled in a call to esp_pm_configure(), the system will go into light sleep mode. The duration of light sleep will be determined by:
· FreeRTOS tasks blocked with finite timeouts · Timers registered with High resolution timer APIs
Light sleep duration will be chosen to wake up the chip before the nearest event (task being unblocked, or timer elapses).
To skip unnecessary wake-up you can consider initializing an esp_timer with the skip_unhandled_events option as true. Timers with this flag will not wake up the system and it helps to reduce consumption.

Dynamic Frequency Scaling and Peripheral Drivers
When DFS is enabled, the APB frequency can be changed multiple times within a single RTOS tick. The APB frequency change does not affect the operation of some peripherals, while other peripherals may have issues. For example, Timer Group peripheral timers will keep counting, however, the speed at which they count will change proportionally to the APB frequency.
The following peripherals work normally even when the APB frequency is changing:
· UART: if REF_TICK is used as a clock source. See use_ref_tick member of uart_config_t. · LEDC: if REF_TICK is used as a clock source. See ledc_timer_config() function. · RMT: if REF_TICK or XTAL is used as a clock source. See flags member of rmt_config_t and macro
RMT_CHANNEL_FLAGS_AWARE_DFS.

Espressif Systems

1334

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· GPTimer: if APB is used as the clock source. See clk_src member of gptimer_config_t.

Currently, the following peripheral drivers are aware of DFS and will use the ESP_PM_APB_FREQ_MAX lock for the duration of the transaction:

· SPI master · I2C · I2S (If the APLL clock is used, then it will use the ESP_PM_NO_LIGHT_SLEEP lock) · SDMMC

The following drivers will hold the ESP_PM_APB_FREQ_MAX lock while the driver is enabled:

· SPI slave: between calls to spi_slave_initialize() and spi_slave_free().

· Ethernet: between calls to esp_eth_driver_install() and esp_eth_driver_uninstall().

· WiFi: between calls to esp_wifi_start() and esp_wifi_stop(). If modem sleep is enabled, the

lock will be released for the periods of time when radio is disabled.

· TWAI: between calls to twai_driver_install() and twai_driver_uninstall().

· Bluetooth:

between

calls

to

esp_bt_controller_enable()

and

esp_bt_controller_disable().

If Bluetooth modem sleep is enabled, the

ESP_PM_APB_FREQ_MAX lock will be released for the periods of time when radio is disabled. However

the ESP_PM_NO_LIGHT_SLEEP lock will still be held.

The following peripheral drivers are not aware of DFS yet. Applications need to acquire/release locks themselves, when necessary:

· PCNT · Sigma-delta · The legacy timer group driver (note, the new GPTimer will hold the ESP_PM_APB_FREQ_MAX lock while
the timer is working, if the clock source is set to APB) · MCPWM

API Reference
Header File · components/esp_pm/include/esp_pm.h

Functions esp_err_t esp_pm_configure(const void *config)
Set implementation-specific power management configuration.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if the configuration values are not correct · ESP_ERR_NOT_SUPPORTED if certain combination of values is not supported, or if CONFIG_PM_ENABLE is not enabled in sdkconfig
Parameters · config: pointer to implementation-specific configuration structure (e.g. esp_pm_config_esp32)
esp_err_t esp_pm_get_configuration(void *config) Get implementation-specific power management configuration.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if the pointer is null
Parameters · config: pointer to implementation-specific configuration structure (e.g. esp_pm_config_esp32)
esp_err_t esp_pm_lock_create(esp_pm_lock_type_t lock_type, int arg, const char *name, esp_pm_lock_handle_t *out_handle)
Initialize a lock handle for certain power management parameter.
When lock is created, initially it is not taken. Call esp_pm_lock_acquire to take the lock.

Espressif Systems

1335

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

This function must not be called from an ISR.
Return · ESP_OK on success · ESP_ERR_NO_MEM if the lock structure can not be allocated · ESP_ERR_INVALID_ARG if out_handle is NULL or type argument is not valid · ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig
Parameters · lock_type: Power management constraint which the lock should control · arg: argument, value depends on lock_type, see esp_pm_lock_type_t · name: arbitrary string identifying the lock (e.g.owifiporospip). Used by the esp_pm_dump_locks function to list existing locks. May be set to NULL. If not set to NULL, must point to a string which is valid for the lifetime of the lock. · [out] out_handle: handle returned from this function. Use this handle when calling esp_pm_lock_delete, esp_pm_lock_acquire, esp_pm_lock_release. Must not be NULL.
esp_err_t esp_pm_lock_acquire(esp_pm_lock_handle_t handle) Take a power management lock.
Once the lock is taken, power management algorithm will not switch to the mode specified in a call to esp_pm_lock_create, or any of the lower power modes (higher numeric values of mmoden).
The lock is recursive, in the sense that if esp_pm_lock_acquire is called a number of times, esp_pm_lock_release has to be called the same number of times in order to release the lock.
This function may be called from an ISR.
This function is not thread-safe w.r.t. calls to other esp_pm_lock_* functions for the same handle.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if the handle is invalid · ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig
Parameters · handle: handle obtained from esp_pm_lock_create function
esp_err_t esp_pm_lock_release(esp_pm_lock_handle_t handle) Release the lock taken using esp_pm_lock_acquire.
Call to this functions removes power management restrictions placed when taking the lock.
Locks are recursive, so if esp_pm_lock_acquire is called a number of times, esp_pm_lock_release has to be called the same number of times in order to actually release the lock.
This function may be called from an ISR.
This function is not thread-safe w.r.t. calls to other esp_pm_lock_* functions for the same handle.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if the handle is invalid · ESP_ERR_INVALID_STATE if lock is not acquired · ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig
Parameters · handle: handle obtained from esp_pm_lock_create function
esp_err_t esp_pm_lock_delete(esp_pm_lock_handle_t handle) Delete a lock created using esp_pm_lock.
The lock must be released before calling this function.
This function must not be called from an ISR.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if the handle argument is NULL · ESP_ERR_INVALID_STATE if the lock is still acquired

Espressif Systems

1336

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig Parameters
· handle: handle obtained from esp_pm_lock_create function esp_err_t esp_pm_dump_locks(FILE *stream)
Dump the list of all locks to stderr This function dumps debugging information about locks created using esp_pm_lock_create to an output stream. This function must not be called from an ISR. If esp_pm_lock_acquire/release are called while this function is running, inconsistent results may be reported. Return
· ESP_OK on success · ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig Parameters · stream: stream to print information to; use stdout or stderr to print to the console; use fmemo-
pen/open_memstream to print to a string buffer.
Type Definitions typedef struct esp_pm_lock *esp_pm_lock_handle_t
Opaque handle to the power management lock.
Enumerations enum esp_pm_lock_type_t
Power management constraints. Values: ESP_PM_CPU_FREQ_MAX
Require CPU frequency to be at the maximum value set via esp_pm_configure. Argument is unused and should be set to 0. ESP_PM_APB_FREQ_MAX Require APB frequency to be at the maximum value supported by the chip. Argument is unused and should be set to 0. ESP_PM_NO_LIGHT_SLEEP Prevent the system from going into light sleep. Argument is unused and should be set to 0.
Header File · components/esp_pm/include/esp32s3/pm.h
Structures struct esp_pm_config_esp32s3_t
Power management config for ESP32. Pass a pointer to this structure as an argument to esp_pm_configure function.
Public Members
int max_freq_mhz Maximum CPU frequency, in MHz
int min_freq_mhz Minimum CPU frequency to use when no locks are taken, in MHz
bool light_sleep_enable Enter light sleep when no locks are taken

Espressif Systems

1337

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
2.7.23 Random Number Generation
ESP32-S3 contains a hardware random number generator, values from it can be obtained using the APIs esp_random() and esp_fill_random(). The hardware RNG produces true random numbers under any of the following conditions:
· RF subsystem is enabled (i.e. Wi-Fi or Bluetooth are enabled). · An internal entropy source has been enabled by calling bootloader_random_enable() and not yet
disabled by calling bootloader_random_disable(). · While the ESP-IDF Second stage bootloader is running. This is because the default ESP-IDF boot-
loader implementation calls bootloader_random_enable() when the bootloader starts, and bootloader_random_disable() before executing the app. When any of these conditions are true, samples of physical noise are continuously mixed into the internal hardware RNG state to provide entropy. Consult the ESP32-S3 Technical Reference Manual > Random Number Generator (RNG) [PDF] chapter for more details. If none of the above conditions are true, the output of the RNG should be considered pseudo-random only.
Startup
During startup, ESP-IDF bootloader temporarily enables a non-RF entropy source (internal reference voltage noise) that provides entropy for any first boot key generation. However, after the app starts executing then normally only pseudo-random numbers are available until Wi-Fi or Bluetooth are initialized. To re-enable the entropy source temporarily during app startup, or for an application that does not use Wi-Fi or Bluetooth, call the function bootloader_random_enable() to re-enable the internal entropy source. The function bootloader_random_disable() must be called to disable the entropy source again before using ADC, Wi-Fi or Bluetooth.
Note: The entropy source enabled during the boot process by the ESP-IDF Second Stage Bootloader will seed the internal RNG state with some entropy. However, the internal hardware RNG state is not large enough to provide a continuous stream of true random numbers. This is why a continuous entropy source must be enabled whenever true random numbers are required.
Note: If an application requires a source of true random numbers but it is not possible to permanently enable a hardware entropy source, consider using a strong software DRBG implementation such as the mbedTLS CTR-DRBG or HMAC-DRBG, with an initial seed of entropy from hardware RNG true random numbers.
Secondary Entropy
ESP32-S3 RNG contains a secondary entropy source, based on sampling an asynchronous 8MHz internal oscillator (see the Technical Reference Manual for details). This entropy source is always enabled in ESP-IDF and continuously mixed into the RNG state by hardware. In testing, this secondary entropy source was sufficient to pass the Dieharder random number test suite without the main entropy source enabled (test input was created by concatenating short samples from a continuously resetting ESP32-S3). However, it is currently only guaranteed that true random numbers will be produced when the main entropy source is also enabled as described above.
API Reference
Header File · components/esp_hw_support/include/esp_random.h

Espressif Systems

1338

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Functions uint32_t esp_random(void)
Get one random 32-bit word from hardware RNG. If Wi-Fi or Bluetooth are enabled, this function returns true random numbers. In other situations, if true random numbers are required then consult the ESP-IDF Programming GuideoRandom Number Generationp section for necessary prerequisites. This function automatically busy-waits to ensure enough external entropy has been introduced into the hardware RNG state, before returning a new random number. This delay is very short (always less than 100 CPU cycles). Return Random value between 0 and UINT32_MAX void esp_fill_random(void *buf, size_t len) Fill a buffer with random bytes from hardware RNG. Note This function is implemented via calls to esp_random(), so the same constraints apply. Parameters
· buf: Pointer to buffer to fill with random numbers. · len: Length of buffer in bytes
Header File · components/bootloader_support/include/bootloader_random.h
Functions void bootloader_random_enable(void)
Enable an entropy source for RNG if RF is disabled. The exact internal entropy source mechanism depends on the chip in use but all SoCs use the SAR ADC to continuously mix random bits (an internal noise reading) into the HWRNG. Consult the SoC Technical Reference Manual for more information. Can also be used from app code early during operation, if true random numbers are required before RF is initialised. Consult ESP-IDF Programming Guide oRandom Number Generationpsection for details. void bootloader_random_disable(void) Disable entropy source for RNG. Disables internal entropy source. Must be called after bootloader_random_enable() and before RF features, ADC, or I2S (ESP32 only) are initialized. Consult the ESP-IDF Programming Guide oRandom Number Generationpsection for details. void bootloader_fill_random(void *buffer, size_t length) Fill buffer with mlengthnrandom bytes. Note If this function is being called from app code only, and never from the bootloader, then itns better to
call esp_fill_random(). Parameters
· buffer: Pointer to buffer · length: This many bytes of random data will be copied to buffer
getrandom
A compatible version of the Linux getrandom() function is also provided for ease of porting:
#include <sys/random.h>
ssize_t getrandom(void *buf, size_t buflen, unsigned int flags);
This function is implemented by calling esp_fill_random() internally.

Espressif Systems

1339

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
The flags argument is ignored, this function is always non-blocking but the strength of any random numbers is dependent on the same conditions described above. Return value is -1 (with errno set to EFAULT) if the buf argument is NULL, and equal to buflen otherwise.
2.7.24 Sleep Modes
Overview
ESP32-S3 is capable of light sleep and deep sleep power saving modes. In light sleep mode, digital peripherals, most of the RAM, and CPUs are clock-gated, and supply voltage is reduced. Upon exit from light sleep, peripherals and CPUs resume operation, their internal state is preserved. In deep sleep mode, CPUs, most of the RAM, and all the digital peripherals which are clocked from APB_CLK are powered off. The only parts of the chip which can still be powered on are:
· RTC controller · RTC peripherals · ULP coprocessor · RTC fast memory · RTC slow memory Wakeup from deep and light sleep modes can be done using several sources. These sources can be combined, in this case the chip will wake up when any one of the sources is triggered. Wakeup sources can be enabled using esp_sleep_enable_X_wakeup APIs and can be disabled using esp_sleep_disable_wakeup_source() API. Next section describes these APIs in detail. Wakeup sources can be configured at any moment before entering light or deep sleep mode. Additionally, the application can force specific powerdown modes for the RTC peripherals and RTC memories using esp_sleep_pd_config() API. Once wakeup sources are configured, application can enter sleep mode using esp_light_sleep_start() or esp_deep_sleep_start() APIs. At this point the hardware will be configured according to the requested wakeup sources, and RTC controller will either power down or power off the CPUs and digital peripherals. If WiFi connection needs to be maintained, enable WiFi modem sleep, and enable automatic light sleep feature (see Power Management APIs). This will allow the system to wake up from sleep automatically when required by WiFi driver, thereby maintaining connection to the AP.
WiFi/BT and sleep modes
In deep sleep and light sleep modes, wireless peripherals are powered down. Before entering deep sleep or light sleep modes, applications must disable WiFi and BT using appropriate calls (esp_bluedroid_disable(), esp_bt_controller_disable(), esp_wifi_stop()). WiFi and BT connections will not be maintained in deep sleep or light sleep, even if these functions are not called.
Wakeup sources
Timer RTC controller has a built in timer which can be used to wake up the chip after a predefined amount of time. Time is specified at microsecond precision, but the actual resolution depends on the clock source selected for RTC SLOW_CLK. For details on RTC clock options, see ESP32-S3 Technical Reference Manual > ULP Coprocessor [PDF]. This wakeup mode doesnnt require RTC peripherals or RTC memories to be powered on during sleep. esp_sleep_enable_timer_wakeup() function can be used to enable deep sleep wakeup using a timer.

Espressif Systems

1340

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Touch pad RTC IO module contains logic to trigger wakeup when a touch sensor interrupt occurs. You need to configure the touch pad interrupt before the chip starts deep sleep. esp_sleep_enable_touchpad_wakeup() function can be used to enable this wakeup source.
External wakeup (ext0) RTC IO module contains logic to trigger wakeup when one of RTC GPIOs is set to a predefined logic level. RTC IO is part of RTC peripherals power domain, so RTC peripherals will be kept powered on during deep sleep if this wakeup source is requested. Because RTC IO module is enabled in this mode, internal pullup or pulldown resistors can also be used. They need to be configured by the application using rtc_gpio_pullup_en() and rtc_gpio_pulldown_en() functions, before calling esp_sleep_start(). esp_sleep_enable_ext0_wakeup() function can be used to enable this wakeup source.
Warning: After wake up from sleep, IO pad used for wakeup will be configured as RTC IO. Before using this pad as digital GPIO, reconfigure it using rtc_gpio_deinit(gpio_num) function.
External wakeup (ext1) RTC controller contains logic to trigger wakeup using multiple RTC GPIOs. One of the two logic functions can be used to trigger wakeup:
· wake up if any of the selected pins is high (ESP_EXT1_WAKEUP_ANY_HIGH) · wake up if all the selected pins are low (ESP_EXT1_WAKEUP_ALL_LOW) This wakeup source is implemented by the RTC controller. As such, RTC peripherals and RTC memories can be powered down in this mode. However, if RTC peripherals are powered down, internal pullup and pulldown resistors will be disabled. To use internal pullup or pulldown resistors, request RTC peripherals power domain to be kept on during sleep, and configure pullup/pulldown resistors using rtc_gpio_ functions, before entering sleep:
esp_sleep_pd_config(ESP_PD_DOMAIN_RTC_PERIPH, ESP_PD_OPTION_ON); gpio_pullup_dis(gpio_num); gpio_pulldown_en(gpio_num);
Warning: After wake up from sleep, IO pad(s) used for wakeup will be configured as RTC IO. Before using these pads as digital GPIOs, reconfigure them using rtc_gpio_deinit(gpio_num) function.
esp_sleep_enable_ext1_wakeup() function can be used to enable this wakeup source.
ULP coprocessor wakeup ULP coprocessor can run while the chip is in sleep mode, and may be used to poll sensors, monitor ADC or touch sensor values, and wake up the chip when a specific event is detected. ULP coprocessor is part of RTC peripherals power domain, and it runs the program stored in RTC slow memory. RTC slow memory will be powered on during sleep if this wakeup mode is requested. RTC peripherals will be automatically powered on before ULP coprocessor starts running the program; once the program stops running, RTC peripherals are automatically powered down again. esp_sleep_enable_ulp_wakeup() function can be used to enable this wakeup source.
GPIO wakeup (light sleep only) In addition to EXT0 and EXT1 wakeup sources described above, one more method of wakeup from external inputs is available in light sleep mode. With this wakeup source, each pin can be individually configured to trigger wakeup on high or low level using gpio_wakeup_enable() function. Unlike EXT0 and EXT1 wakeup sources, which can only be used with RTC IOs, this wakeup source can be used with any IO (RTC or digital). esp_sleep_enable_gpio_wakeup() function can be used to enable this wakeup source.

Espressif Systems

1341

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Warning: Before entering light sleep mode, check if any GPIO pin to be driven is part of the VDD_SPI power domain. If so, this power domain must be configured to remain ON during sleep. For example, on ESP32-WROOM-32 board, GPIO16 and GPIO17 are linked to VDD_SPI power domain. If they are configured to remain high during light sleep, the power domain should be configured to remain powered ON. This can be done with esp_sleep_pd_config(): esp_sleep_pd_config(ESP_PD_DOMAIN_VDDSDIO, ESP_PD_OPTION_ON);
UART wakeup (light sleep only) When ESP32-S3 receives UART input from external devices, it is often required to wake up the chip when input data is available. UART peripheral contains a feature which allows waking up the chip from light sleep when a certain number of positive edges on RX pin are seen. This number of positive edges can be set using uart_set_wakeup_threshold() function. Note that the character which triggers wakeup (and any characters before it) will not be received by the UART after wakeup. This means that the external device typically needs to send an extra character to the ESP32-S3 to trigger wakeup, before sending the data. esp_sleep_enable_uart_wakeup() function can be used to enable this wakeup source.
Power-down of RTC peripherals and memories
By default, esp_deep_sleep_start() and esp_light_sleep_start() functions will power down all RTC power domains which are not needed by the enabled wakeup sources. To override this behaviour, esp_sleep_pd_config() function is provided. If some variables in the program are placed into RTC slow memory (for example, using RTC_DATA_ATTR attribute), RTC slow memory will be kept powered on by default. This can be overridden using esp_sleep_pd_config() function, if desired.
Entering light sleep
esp_light_sleep_start() function can be used to enter light sleep once wakeup sources are configured. It is also possible to go into light sleep with no wakeup sources configured, in this case the chip will be in light sleep mode indefinitely, until external reset is applied.
Entering deep sleep
esp_deep_sleep_start() function can be used to enter deep sleep once wakeup sources are configured. It is also possible to go into deep sleep with no wakeup sources configured, in this case the chip will be in deep sleep mode indefinitely, until external reset is applied.
Configuring IOs
Some ESP32-S3 IOs have internal pullups or pulldowns, which are enabled by default. If an external circuit drives this pin in deep sleep mode, current consumption may increase due to current flowing through these pullups and pulldowns. To isolate a pin, preventing extra current draw, call rtc_gpio_isolate() function. For example, on ESP32-WROVER module, GPIO12 is pulled up externally. GPIO12 also has an internal pulldown in the ESP32 chip. This means that in deep sleep, some current will flow through these external and internal resistors, increasing deep sleep current above the minimal possible value. Add the following code before esp_deep_sleep_start() to remove this extra current:
rtc_gpio_isolate(GPIO_NUM_12);

Espressif Systems

1342

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

UART output handling
Before entering sleep mode, esp_deep_sleep_start() will flush the contents of UART FIFOs. When entering light sleep mode using esp_light_sleep_start(), UART FIFOs will not be flushed. Instead, UART output will be suspended, and remaining characters in the FIFO will be sent out after wakeup from light sleep.
Checking sleep wakeup cause
esp_sleep_get_wakeup_cause() function can be used to check which wakeup source has triggered wakeup from sleep mode. For touch pad, it is possible to identify touch pad which has caused wakeup using esp_sleep_get_touchpad_wakeup_status() functions. For ext1 wakeup sources, it is possible to identify pin which has caused wakeup using esp_sleep_get_ext1_wakeup_status() functions.
Disable sleep wakeup source
Previously configured wakeup source can be disabled later using esp_sleep_disable_wakeup_source() API. This function deactivates trigger for the given wakeup source. Additionally it can disable all triggers if the argument is ESP_SLEEP_WAKEUP_ALL.
Application Example
Implementation of basic functionality of deep sleep is shown in protocols/sntp example, where ESP module is periodically waken up to retrieve time from NTP server. More extensive example in system/deep_sleep illustrates usage of various deep sleep wakeup triggers and ULP coprocessor programming.
API Reference
Header File · components/esp_hw_support/include/esp_sleep.h
Functions esp_err_t esp_sleep_disable_wakeup_source(esp_sleep_source_t source)
Disable wakeup source. This function is used to deactivate wake up trigger for source defined as parameter of the function. See docs/sleep-modes.rst for details. Note This function does not modify wake up configuration in RTC. It will be performed in esp_sleep_start
function. Return
· ESP_OK on success · ESP_ERR_INVALID_STATE if trigger was not active Parameters · source: - number of source to disable of type esp_sleep_source_t esp_err_t esp_sleep_enable_ulp_wakeup(void) Enable wakeup by ULP coprocessor. Note In revisions 0 and 1 of the ESP32, ULP wakeup source cannot be used when RTC_PERIPH power domain is forced to be powered on (ESP_PD_OPTION_ON) or when ext0 wakeup source is used.

Espressif Systems

1343

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Return · ESP_OK on success · ESP_ERR_NOT_SUPPORTED if additional current by touch (CONFIG_ESP32_RTC_EXT_CRYST_ADDIT_CURRENT) is enabled. · ESP_ERR_INVALID_STATE if ULP co-processor is not enabled or if wakeup triggers conflict
esp_err_t esp_sleep_enable_timer_wakeup(uint64_t time_in_us) Enable wakeup by timer.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if value is out of range (TBD)
Parameters · time_in_us: time before wakeup, in microseconds
esp_err_t esp_sleep_enable_touchpad_wakeup(void) Enable wakeup by touch sensor.
Note In revisions 0 and 1 of the ESP32, touch wakeup source can not be used when RTC_PERIPH power domain is forced to be powered on (ESP_PD_OPTION_ON) or when ext0 wakeup source is used.
Note The FSM mode of the touch button should be configured as the timer trigger mode. Return
· ESP_OK on success · ESP_ERR_NOT_SUPPORTED if additional current by touch (CON-
FIG_ESP32_RTC_EXT_CRYST_ADDIT_CURRENT) is enabled. · ESP_ERR_INVALID_STATE if wakeup triggers conflict
touch_pad_t esp_sleep_get_touchpad_wakeup_status(void) Get the touch pad which caused wakeup.
If wakeup was caused by another source, this function will return TOUCH_PAD_MAX;
Return touch pad which caused wakeup
bool esp_sleep_is_valid_wakeup_gpio(gpio_num_t gpio_num) Returns true if a GPIO number is valid for use as wakeup source.
Note For SoCs with RTC IO capability, this can be any valid RTC IO input pin. Return True if this GPIO number will be accepted as a sleep wakeup source. Parameters
· gpio_num: Number of the GPIO to test for wakeup source capability
esp_err_t esp_sleep_enable_ext0_wakeup(gpio_num_t gpio_num, int level) Enable wakeup using a pin.
This function uses external wakeup feature of RTC_IO peripheral. It will work only if RTC peripherals are kept on during sleep.
This feature can monitor any pin which is an RTC IO. Once the pin transitions into the state given by level argument, the chip will be woken up.
Note This function does not modify pin configuration. The pin is configured in esp_sleep_start, immediately before entering sleep mode.
Note In revisions 0 and 1 of the ESP32, ext0 wakeup source can not be used together with touch or ULP wakeup sources.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if the selected GPIO is not an RTC GPIO, or the mode is invalid · ESP_ERR_INVALID_STATE if wakeup triggers conflict
Parameters · gpio_num: GPIO number used as wakeup source. Only GPIOs which are have RTC functionality can be used: 0,2,4,12-15,25-27,32-39. · level: input level which will trigger wakeup (0=low, 1=high)

Espressif Systems

1344

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

esp_err_t esp_sleep_enable_ext1_wakeup(uint64_t mask, esp_sleep_ext1_wakeup_mode_t mode) Enable wakeup using multiple pins.
This function uses external wakeup feature of RTC controller. It will work even if RTC peripherals are shut down during sleep.
This feature can monitor any number of pins which are in RTC IOs. Once any of the selected pins goes into the state given by mode argument, the chip will be woken up.
Note This function does not modify pin configuration. The pins are configured in esp_sleep_start, immediately before entering sleep mode.
Note Internal pullups and pulldowns donnt work when RTC peripherals are shut down. In this case, external resistors need to be added. Alternatively, RTC peripherals (and pullups/pulldowns) may be kept enabled using esp_sleep_pd_config function.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if any of the selected GPIOs is not an RTC GPIO, or mode is invalid
Parameters · mask: bit mask of GPIO numbers which will cause wakeup. Only GPIOs which have RTC functionality can be used in this bit map: 0,2,4,12-15,25-27,32-39. · mode: select logic function used to determine wakeup condition: ­ ESP_EXT1_WAKEUP_ALL_LOW: wake up when all selected GPIOs are low ­ ESP_EXT1_WAKEUP_ANY_HIGH: wake up when any of the selected GPIOs is high
esp_err_t esp_sleep_enable_gpio_wakeup(void) Enable wakeup from light sleep using GPIOs.
Each GPIO supports wakeup function, which can be triggered on either low level or high level. Unlike EXT0 and EXT1 wakeup sources, this method can be used both for all IOs: RTC IOs and digital IOs. It can only be used to wakeup from light sleep though.
To enable wakeup, first call gpio_wakeup_enable, specifying gpio number and wakeup level, for each GPIO which is used for wakeup. Then call this function to enable wakeup feature.
Note In revisions 0 and 1 of the ESP32, GPIO wakeup source can not be used together with touch or ULP wakeup sources.
Return · ESP_OK on success · ESP_ERR_INVALID_STATE if wakeup triggers conflict
esp_err_t esp_sleep_enable_uart_wakeup(int uart_num) Enable wakeup from light sleep using UART.
Use uart_set_wakeup_threshold function to configure UART wakeup threshold.
Wakeup from light sleep takes some time, so not every character sent to the UART can be received by the application.
Note ESP32 does not support wakeup from UART2. Return
· ESP_OK on success · ESP_ERR_INVALID_ARG if wakeup from given UART is not supported Parameters · uart_num: UART port to wake up from
esp_err_t esp_sleep_enable_wifi_wakeup(void) Enable wakeup by WiFi MAC.
Return · ESP_OK on success
esp_err_t esp_sleep_disable_wifi_wakeup(void) Disable wakeup by WiFi MAC.
Return · ESP_OK on success

Espressif Systems

1345

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
uint64_t esp_sleep_get_ext1_wakeup_status(void) Get the bit mask of GPIOs which caused wakeup (ext1)
If wakeup was caused by another source, this function will return 0.
Return bit mask, if GPIOn caused wakeup, BIT(n) will be set
esp_err_t esp_sleep_pd_config(esp_sleep_pd_domain_t domain, esp_sleep_pd_option_t option) Set power down mode for an RTC power domain in sleep mode.
If not set set using this API, all power domains default to ESP_PD_OPTION_AUTO.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if either of the arguments is out of range
Parameters · domain: power domain to configure · option: power down option (ESP_PD_OPTION_OFF, ESP_PD_OPTION_ON, or ESP_PD_OPTION_AUTO)
void esp_deep_sleep_start(void) Enter deep sleep with the configured wakeup options.
This function does not return.
esp_err_t esp_light_sleep_start(void) Enter light sleep with the configured wakeup options.
Return · ESP_OK on success (returned after wakeup) · ESP_ERR_INVALID_STATE if WiFi or BT is not stopped
void esp_deep_sleep(uint64_t time_in_us) Enter deep-sleep mode.
The device will automatically wake up after the deep-sleep time Upon waking up, the device calls deep sleep wake stub, and then proceeds to load application.
Call to this function is equivalent to a call to esp_deep_sleep_enable_timer_wakeup followed by a call to esp_deep_sleep_start.
esp_deep_sleep does not shut down WiFi, BT, and higher level protocol connections gracefully. Make sure relevant WiFi and BT stack functions are called to close any connections and deinitialize the peripherals. These include:
· esp_bluedroid_disable · esp_bt_controller_disable · esp_wifi_stop
This function does not return.
Note The device will wake up immediately if the deep-sleep time is set to 0 Parameters
· time_in_us: deep-sleep time, unit: microsecond
esp_sleep_wakeup_cause_t esp_sleep_get_wakeup_cause(void) Get the wakeup source which caused wakeup from sleep.
Return cause of wake up from last sleep (deep sleep or light sleep)
void esp_wake_deep_sleep(void) Default stub to run on wake from deep sleep.
Allows for executing code immediately on wake from sleep, before the software bootloader or ESP-IDF app has started up.
This function is weak-linked, so you can implement your own version to run code immediately when the chip wakes from sleep.

Espressif Systems

1346

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
See docs/deep-sleep-stub.rst for details.
void esp_set_deep_sleep_wake_stub(esp_deep_sleep_wake_stub_fn_t new_stub) Install a new stub at runtime to run on wake from deep sleep.
If implementing esp_wake_deep_sleep() then it is not necessary to call this function.
However, it is possible to call this function to substitute a different deep sleep stub. Any function used as a deep sleep stub must be marked RTC_IRAM_ATTR, and must obey the same rules given for esp_wake_deep_sleep().
esp_deep_sleep_wake_stub_fn_t esp_get_deep_sleep_wake_stub(void) Get current wake from deep sleep stub.
Return Return current wake from deep sleep stub, or NULL if no stub is installed.
void esp_default_wake_deep_sleep(void) The default esp-idf-provided esp_wake_deep_sleep() stub.
See docs/deep-sleep-stub.rst for details.
void esp_deep_sleep_disable_rom_logging(void) Disable logging from the ROM code after deep sleep.
Using LSB of RTC_STORE4.
esp_err_t esp_sleep_cpu_pd_low_init(bool enable) CPU Power down low-level initialize.
Return · ESP_OK on success · ESP_ERR_NO_MEM not enough retention memory
Parameters · enable: enable or disable CPU power down during light sleep
void esp_sleep_config_gpio_isolate(void) Configure to isolate all GPIO pins in sleep state.
void esp_sleep_enable_gpio_switch(bool enable) Enable or disable GPIO pins status switching between slept status and waked status.
Parameters · enable: decide whether to switch status or not
Type Definitions typedef esp_sleep_source_t esp_sleep_wakeup_cause_t typedef void (*esp_deep_sleep_wake_stub_fn_t)(void)
Function type for stub to run on wake from sleep.
Enumerations enum esp_sleep_ext1_wakeup_mode_t
Logic function used for EXT1 wakeup mode.
Values:
ESP_EXT1_WAKEUP_ALL_LOW = 0 Wake the chip when all selected GPIOs go low.
ESP_EXT1_WAKEUP_ANY_HIGH = 1 Wake the chip when any of the selected GPIOs go high.
enum esp_sleep_pd_domain_t Power domains which can be powered down in sleep mode.
Values:

Espressif Systems

1347

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_PD_DOMAIN_RTC_PERIPH RTC IO, sensors and ULP co-processor.
ESP_PD_DOMAIN_RTC_SLOW_MEM RTC slow memory.
ESP_PD_DOMAIN_RTC_FAST_MEM RTC fast memory.
ESP_PD_DOMAIN_XTAL XTAL oscillator.
ESP_PD_DOMAIN_CPU CPU core.
ESP_PD_DOMAIN_RTC8M Internal 8M oscillator.
ESP_PD_DOMAIN_VDDSDIO VDD_SDIO.
ESP_PD_DOMAIN_MAX Number of domains.
enum esp_sleep_pd_option_t Power down options.
Values:
ESP_PD_OPTION_OFF Power down the power domain in sleep mode.
ESP_PD_OPTION_ON Keep power domain enabled during sleep mode.
ESP_PD_OPTION_AUTO Keep power domain enabled in sleep mode, if it is needed by one of the wakeup options. Otherwise power it down.
enum esp_sleep_source_t Sleep wakeup cause.
Values:
ESP_SLEEP_WAKEUP_UNDEFINED In case of deep sleep, reset was not caused by exit from deep sleep.
ESP_SLEEP_WAKEUP_ALL Not a wakeup cause, used to disable all wakeup sources with esp_sleep_disable_wakeup_source.
ESP_SLEEP_WAKEUP_EXT0 Wakeup caused by external signal using RTC_IO.
ESP_SLEEP_WAKEUP_EXT1 Wakeup caused by external signal using RTC_CNTL.
ESP_SLEEP_WAKEUP_TIMER Wakeup caused by timer.
ESP_SLEEP_WAKEUP_TOUCHPAD Wakeup caused by touchpad.
ESP_SLEEP_WAKEUP_ULP Wakeup caused by ULP program.
ESP_SLEEP_WAKEUP_GPIO Wakeup caused by GPIO (light sleep only)
ESP_SLEEP_WAKEUP_UART Wakeup caused by UART (light sleep only)

Espressif Systems

1348

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_SLEEP_WAKEUP_WIFI Wakeup caused by WIFI (light sleep only)
ESP_SLEEP_WAKEUP_COCPU Wakeup caused by COCPU int.
ESP_SLEEP_WAKEUP_COCPU_TRAP_TRIG Wakeup caused by COCPU crash.
ESP_SLEEP_WAKEUP_BT Wakeup caused by BT (light sleep only)
2.7.25 Watchdogs
Overview
The ESP-IDF has support for multiple types of watchdogs, with the two main ones being: The Interrupt Watchdog Timer and the Task Watchdog Timer (TWDT). The Interrupt Watchdog Timer and the TWDT can both be enabled using Project Configuration Menu, however the TWDT can also be enabled during runtime. The Interrupt Watchdog is responsible for detecting instances where FreeRTOS task switching is blocked for a prolonged period of time. The TWDT is responsible for detecting instances of tasks running without yielding for a prolonged period.
Interrupt watchdog The interrupt watchdog makes sure the FreeRTOS task switching interrupt isnnt blocked for a long time. This is bad because no other tasks, including potentially important ones like the WiFi task and the idle task, cannt get any CPU runtime. A blocked task switching interrupt can happen because a program runs into an infinite loop with interrupts disabled or hangs in an interrupt.
The default action of the interrupt watchdog is to invoke the panic handler. causing a register dump and an opportunity for the programmer to find out, using either OpenOCD or gdbstub, what bit of code is stuck with interrupts disabled. Depending on the configuration of the panic handler, it can also blindly reset the CPU, which may be preferred in a production environment.
The interrupt watchdog is built around the hardware watchdog in timer group 1. If this watchdog for some reason cannot execute the NMI handler that invokes the panic handler (e.g. because IRAM is overwritten by garbage), it will hard-reset the SOC. If the panic handler executes, it will display the panic reason as oInterrupt wdt timeout on CPU0por oInterrupt wdt timeout on CPU1p(as applicable).
Configuration The interrupt watchdog is enabled by default via the CONFIG_ESP_INT_WDT configuration flag. The timeout is configured by setting CONFIG_ESP_INT_WDT_TIMEOUT_MS. The default timeout is higher if PSRAM support is enabled, as a critical section or interrupt routine that accesses a large amount of PSRAM will take longer to complete in some circumstances. The INT WDT timeout should always be longer than the period between FreeRTOS ticks (see CONFIG_FREERTOS_HZ).
Tuning If you find the Interrupt watchdog timeout is triggering because an interrupt or critical section is running longer than the timeout period, consider rewriting the code: critical sections should be made as short as possible, with non-critical computation happening outside the critical section. Interrupt handlers should also perform the minimum possible amount of computation, consider pushing data into a queue from the ISR and processing it in a task instead. Neither critical sections or interrupt handlers should ever block waiting for another event to occur.
If changing the code to reduce the processing time is not possible or desirable, itns possible to increase the CONFIG_ESP_INT_WDT_TIMEOUT_MS setting instead.
Task Watchdog Timer The Task Watchdog Timer (TWDT) is responsible for detecting instances of tasks running for a prolonged period of time without yielding. This is a symptom of CPU starvation and is usually caused by a higher priority task looping without yielding to a lower-priority task thus starving the lower priority task from CPU time. This can be an indicator of poorly written code that spinloops on a peripheral, or a task that is stuck in an infinite loop.

Espressif Systems

1349

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

By default the TWDT will watch the Idle task, however any task can subscribe to be watched by the TWDT. Each watched task must mresetnthe TWDT periodically to indicate that they have been allocated CPU time. If a task does not reset within the TWDT timeout period, a warning will be printed with information about which tasks failed to reset the TWDT in time and which tasks are currently running.
It is also possible to redefine the function esp_task_wdt_isr_user_handler in the user code, in order to receive the timeout event and handle it differently.
The TWDT is built around the Hardware Watchdog Timer in Timer Group 0. The TWDT can be initialized by calling esp_task_wdt_init() which will configure the hardware timer. A task can then subscribe to the TWDT using esp_task_wdt_add() in order to be watched. Each subscribed task must periodically call esp_task_wdt_reset() to reset the TWDT. Failure by any subscribed tasks to periodically call esp_task_wdt_reset() indicates that one or more tasks have been starved of CPU time or are stuck in a loop somewhere.
A watched task can be unsubscribed from the TWDT using esp_task_wdt_delete(). A task that has been unsubscribed should no longer call esp_task_wdt_reset(). Once all tasks have unsubscribed form the TWDT, the TWDT can be deinitialized by calling esp_task_wdt_deinit().
The default timeout period for the TWDT is set using config item CONFIG_ESP_TASK_WDT_TIMEOUT_S. This should be set to at least as long as you expect any single task will need to monopolise the CPU (for example, if you expect the app will do a long intensive calculation and should not yield to other tasks). It is also possible to change this timeout at runtime by calling esp_task_wdt_init().
Note: It might cause severe watchdog timeout issue when erasing large flash areas. Here are two methods to avoid this issue:
· Increase CONFIG_ESP_TASK_WDT_TIMEOUT_S in menuconfig for a larger watchdog timeout period. · You can also call esp_task_wdt_init() to increase the watchdog timeout period before erasing a large
flash area.
For more information, you can refer to SPI Flash.
The following config options control TWDT configuration at startup. They are all enabled by default:
· CONFIG_ESP_TASK_WDT - the TWDT is initialized automatically during startup. If this option is disabled, it is still possible to initialize the Task WDT at runtime by calling esp_task_wdt_init().
· CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0 - CPU0 Idle task is subscribed to the TWDT during startup. If this option is disabled, it is still possible to subscribe the idle task by calling esp_task_wdt_add() at any time.
· CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1 - CPU1 Idle task is subscribed to the TWDT during startup.
JTAG and watchdogs While debugging using OpenOCD, the CPUs will be halted every time a breakpoint is reached. However if the watchdog timers continue to run when a breakpoint is encountered, they will eventually trigger a reset making it very difficult to debug code. Therefore OpenOCD will disable the hardware timers of both the interrupt and task watchdogs at every breakpoint. Moreover, OpenOCD will not reenable them upon leaving the breakpoint. This means that interrupt watchdog and task watchdog functionality will essentially be disabled. No warnings or panics from either watchdogs will be generated when the ESP32-S3 is connected to OpenOCD via JTAG.
XTAL32K Watchdog Timer (XTWDT) The XTAL32K watchdog makes sure the (optional) external 32 KHz crystal or oscillator is functioning correctly.
When XTAL32K_CLK works as the clock source of RTC_SLOW_CLK and stops oscillating, the XTAL32K watchdog timer will detect this and generate an interrupt. It also provides functionality for automatically switching over to the internal, but less accurate oscillator as the RTC_SLOW_CLK source.
Since the switch to the backup clock is done in hardware it can also happen during deep sleep. This means that even if XTAL32K_CLK stops functioning while the chip in deep sleep, waiting for a timer to expire, it will still be able to wake-up as planned.

Espressif Systems

1350

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
If the XTAL32K_CLK starts functioning normally again, you can call esp_xt_wdt_restore_clk to switch back to this clock source and re-enable the watchdog timer.
Configuration When the external 32KHz crystal or oscillator is selected (CONFIG_ESP32S3_RTC_CLK_SRC) the XTAL32K watchdog can be enabled via the CONFIG_ESP_XT_WDT configuration flag. The timeout is configured by setting CONFIG_ESP_XT_WDT_TIMEOUT. The automatic backup clock functionality is enabled via the ref:CONFIG_ESP_XT_WDT_BACKUP_CLK_ENABLE configuration.
Interrupt Watchdog API Reference
Header File · esp_system/include/esp_int_wdt.h
Functions
void esp_int_wdt_init(void) Initialize the non-CPU-specific parts of interrupt watchdog. This is called in the init code if the interrupt watchdog is enabled in menuconfig.
Task Watchdog API Reference
A full example using the Task Watchdog is available in esp-idf: system/task_watchdog
Header File · components/esp_system/include/esp_task_wdt.h
Functions esp_err_t esp_task_wdt_init(uint32_t timeout, bool panic)
Initialize the Task Watchdog Timer (TWDT) This function configures and initializes the TWDT. If the TWDT is already initialized when this function is called, this function will update the TWDTns timeout period and panic configurations instead. After initializing the TWDT, any task can elect to be watched by the TWDT by subscribing to it using esp_task_wdt_add(). Return
· ESP_OK: Initialization was successful · ESP_ERR_NO_MEM: Initialization failed due to lack of memory Note esp_task_wdt_init() must only be called after the scheduler started Parameters · [in] timeout: Timeout period of TWDT in seconds · [in] panic: Flag that controls whether the panic handler will be executed when the TWDT
times out esp_err_t esp_task_wdt_deinit(void)
Deinitialize the Task Watchdog Timer (TWDT) This function will deinitialize the TWDT. Calling this function whilst tasks are still subscribed to the TWDT, or when the TWDT is already deinitialized, will result in an error code being returned. Return
· ESP_OK: TWDT successfully deinitialized · ESP_ERR_INVALID_STATE: Error, tasks are still subscribed to the TWDT · ESP_ERR_NOT_FOUND: Error, TWDT has already been deinitialized

Espressif Systems

1351

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
esp_err_t esp_task_wdt_add(TaskHandle_t handle) Subscribe a task to the Task Watchdog Timer (TWDT)
This function subscribes a task to the TWDT. Each subscribed task must periodically call esp_task_wdt_reset() to prevent the TWDT from elapsing its timeout period. Failure to do so will result in a TWDT timeout. If the task being subscribed is one of the Idle Tasks, this function will automatically enable esp_task_wdt_reset() to called from the Idle Hook of the Idle Task. Calling this function whilst the TWDT is uninitialized or attempting to subscribe an already subscribed task will result in an error code being returned.
Return · ESP_OK: Successfully subscribed the task to the TWDT · ESP_ERR_INVALID_ARG: Error, the task is already subscribed · ESP_ERR_NO_MEM: Error, could not subscribe the task due to lack of memory · ESP_ERR_INVALID_STATE: Error, the TWDT has not been initialized yet
Parameters · [in] handle: Handle of the task. Input NULL to subscribe the current running task to the TWDT
esp_err_t esp_task_wdt_reset(void) Reset the Task Watchdog Timer (TWDT) on behalf of the currently running task.
This function will reset the TWDT on behalf of the currently running task. Each subscribed task must periodically call this function to prevent the TWDT from timing out. If one or more subscribed tasks fail to reset the TWDT on their own behalf, a TWDT timeout will occur. If the IDLE tasks have been subscribed to the TWDT, they will automatically call this function from their idle hooks. Calling this function from a task that has not subscribed to the TWDT, or when the TWDT is uninitialized will result in an error code being returned.
Return · ESP_OK: Successfully reset the TWDT on behalf of the currently running task · ESP_ERR_NOT_FOUND: Error, the current running task has not subscribed to the TWDT · ESP_ERR_INVALID_STATE: Error, the TWDT has not been initialized yet
esp_err_t esp_task_wdt_delete(TaskHandle_t handle) Unsubscribes a task from the Task Watchdog Timer (TWDT)
This function will unsubscribe a task from the TWDT. After being unsubscribed, the task should no longer call esp_task_wdt_reset(). If the task is an IDLE task, this function will automatically disable the calling of esp_task_wdt_reset() from the Idle Hook. Calling this function whilst the TWDT is uninitialized or attempting to unsubscribe an already unsubscribed task from the TWDT will result in an error code being returned.
Return · ESP_OK: Successfully unsubscribed the task from the TWDT · ESP_ERR_INVALID_ARG: Error, the task is already unsubscribed · ESP_ERR_INVALID_STATE: Error, the TWDT has not been initialized yet
Parameters · [in] handle: Handle of the task. Input NULL to unsubscribe the current running task.
esp_err_t esp_task_wdt_status(TaskHandle_t handle) Query whether a task is subscribed to the Task Watchdog Timer (TWDT)
This function will query whether a task is currently subscribed to the TWDT, or whether the TWDT is initialized.
Return : · ESP_OK: The task is currently subscribed to the TWDT · ESP_ERR_NOT_FOUND: The task is currently not subscribed to the TWDT · ESP_ERR_INVALID_STATE: The TWDT is not initialized, therefore no tasks can be subscribed
Parameters · [in] handle: Handle of the task. Input NULL to query the current running task.
2.7.26 System Time

Espressif Systems

1352

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Overview
System time can be kept using either one time source or two time sources simultaneously. The choice depends on the application purpose and accuracy requirements for system time.
There are the following two time sources:
· RTC timer: Allows keeping the system time during any resets and sleep modes, only the power-up reset leads to resetting the RTC timer. The frequency deviation depends on an RTC Clock Source and affects accuracy only in sleep modes, in which case the time will be measured at 6.6667 us resolution.
· High-resolution timer: Not available during any reset and sleep modes. The reason for using this timer is to achieve greater accuracy. It uses the APB_CLK clock source (typically 80 MHz), which has a frequency deviation of less than ±10 ppm. Time will be measured at 1 us resolution.
The settings for the system time source are as follows:
· RTC and high-resolution timer (default) · RTC · High-resolution timer · None
It is recommended to stick to the default setting which provides maximum accuracy. If you want to choose a different timer, configure CONFIG_ESP32S3_TIME_SYSCALL in project configuration.

RTC Clock Source
The RTC timer has the following clock sources:
· Internal 150kHz RC oscillator (default): Features the lowest deep sleep current consumption and no dependence on any external components. However, as frequency stability is affected by temperature fluctuations, time may drift in both Deep and Light sleep modes.
· External 32kHz crystal: Requires a 32kHz crystal to be connected to the 32K_XP and 32K_XN pins. Provides better frequency stability at the expense of slightly higher (by 1 uA) Deep sleep current consumption.
· External 32kHz oscillator at 32K_XN pin: Allows using 32kHz clock generated by an external circuit. The external clock signal must be connected to the 32K_XN pin. The amplitude should be less than 1.2 V for sine wave signal and less than 1 V for square wave signal. Common mode voltage should be in the range of 0.1 < Vcm < 0.5xVamp, where Vamp is signal amplitude. Additionally, a 1 nF capacitor must be placed between the 32K_XP pin and ground. In this case, the 32K_XP pin cannot be used as a GPIO pin.
· Internal 8.5MHz oscillator, divided by 256 (~33kHz): Provides better frequency stability than the internal 150kHz RC oscillator at the expense of higher (by 5 uA) deep sleep current consumption. It also does not require external components.
The choice depends on your requirements for system time accuracy and power consumption in sleep modes. To modify the RTC clock source, set CONFIG_ESP32S3_RTC_CLK_SRC in project configuration.
More details on wiring requirements for the External 32kHz crystal and External 32kHz oscillator at 32K_XN pin sources can be found in Section Crystal Oscillator of ESP32-S3 Hardware Design Guidelines <https://www.espressif.com/sites/default/files/documentation/esp32s3_hardware_design_guidelines_en.pdf#page=11>.

Get Current Time

To get the current time, use the POSIX function gettimeofday(). Additionally, you can use the following standard C library functions to obtain time and manipulate it:

gettimeofday time asctime clock ctime

(continues on next page)

Espressif Systems

1353

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

difftime gmtime localtime mktime strftime adjtime*

(continued from previous page)

* To stop smooth time adjustment and update the current time immediately, use the POSIX function settimeofday().
If you need to obtain time with one second resolution, use the following method:
time_t now; char strftime_buf[64]; struct tm timeinfo;
time(&now); // Set timezone to China Standard Time setenv("TZ", "CST-8", 1); tzset();
localtime_r(&now, &timeinfo); strftime(strftime_buf, sizeof(strftime_buf), "%c", &timeinfo); ESP_LOGI(TAG, "The current date/time in Shanghai is: %s", strftime_buf);

If you need to obtain time with one microsecond resolution, use the code snippet below:
struct timeval tv_now; gettimeofday(&tv_now, NULL); int64_t time_us = (int64_t)tv_now.tv_sec * 1000000L + (int64_t)tv_now.tv_usec;

SNTP Time Synchronization
To set the current time, you can use the POSIX functions settimeofday() and adjtime(). They are used internally in the lwIP SNTP library to set current time when a response from the NTP server is received. These functions can also be used separately from the lwIP SNTP library.
A function to use inside the lwIP SNTP library depends on a sync mode for system time. Use the function sntp_set_sync_mode() to set one of the following sync modes:
· SNTP_SYNC_MODE_IMMED (default) updates system time immediately upon receiving a response from the SNTP server after using settimeofday().
· SNTP_SYNC_MODE_SMOOTH updates time smoothly by gradually reducing time error using the function adjtime(). If the difference between the SNTP response time and system time is more than 35 minutes, update system time immediately by using settimeofday().
The lwIP SNTP library has API functions for setting a callback function for a certain event. You might need the following functions:
· sntp_set_time_sync_notification_cb() - use it for setting a callback function that will notify of the time synchronization process
· sntp_get_sync_status() and sntp_set_sync_status() - use it to get/set time synchronization status
To start synchronization via SNTP, just call the following three functions.
sntp_setoperatingmode(SNTP_OPMODE_POLL); sntp_setservername(0, "pool.ntp.org"); sntp_init();

Espressif Systems

1354

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
An application with this initialization code will periodically synchronize the time. The time synchronization period is determined by CONFIG_LWIP_SNTP_UPDATE_DELAY (default value is one hour). To modify the variable, set CONFIG_LWIP_SNTP_UPDATE_DELAY in project configuration. A code example that demonstrates the implementation of time synchronization based on the lwIP SNTP library is provided in protocols/sntp directory.
Timezones
To set local timezone, use the following POSIX functions: 1. Call setenv() to set the TZ environment variable to the correct value depending on the device location. The format of the time string is the same as described in the GNU libc documentation (although the implementation is different). 2. Call tzset() to update C library runtime data for the new time zone.
Once these steps are completed, call the standard C library function localtime(), and it will return correct local time taking into account the time zone offset and daylight saving time.
64-bit time_t
ESP-IDF uses 32-bit time_t type by default. To address Y2K38 issue, you may need to use 64-bit time_t type when building the application. Currently this requires building the cross-compiler toolchain from scratch. See the instructions for building the toolchain in Setup Linux Toolchain from Scratch. To enable 64-bit time_t support in the toolchain, you need to remove the --enable-newlib-long-time_t option from the crosstool-NG/samples/xtensaesp32-elf/crosstool.config file before building the toolchain. If you need to make the program compatible with both 32-bit and 64-bit time_t, you may use the following methods:
· In C or C++ source files, _USE_LONG_TIME_T preprocessor macro will be defined if 32-bit time_t is used. You need to include <sys/types.h> to make this macro available.
· In CMake files, TIME_T_SIZE IDF build property will be set to the size of time_t, in bytes. You may call idf_build_get_property(var TIME_T_SIZE) to get the value of this property into a CMake variable var. See build system API reference for more information about idf_build_get_property.
Note that the size of time_t type also affects the sizes of other types, for example struct timeval, struct stat, struct utimbuf.
API Reference
Header File · components/lwip/include/apps/esp_sntp.h
Functions void sntp_sync_time(struct timeval *tv)
This function updates the system time. This is a weak-linked function. It is possible to replace all SNTP update functionality by placing a sntp_sync_time() function in the app firmware source. If the default implementation is used, calling sntp_set_sync_mode() allows the time synchronization mode to be changed to instant or smooth. If a callback function is registered via sntp_set_time_sync_notification_cb(), it will be called following time synchronization. Parameters
· tv: Time received from SNTP server.

Espressif Systems

1355

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
void sntp_set_sync_mode(sntp_sync_mode_t sync_mode) Set the sync mode.
Modes allowed: SNTP_SYNC_MODE_IMMED and SNTP_SYNC_MODE_SMOOTH.
Parameters · sync_mode: Sync mode.
sntp_sync_mode_t sntp_get_sync_mode(void) Get set sync mode.
Return SNTP_SYNC_MODE_IMMED: Update time immediately. SNTP_SYNC_MODE_SMOOTH: Smooth time updating.
sntp_sync_status_t sntp_get_sync_status(void) Get status of time sync.
After the update is completed, the status will be returned as SNTP_SYNC_STATUS_COMPLETED. After that, the status will be reset to SNTP_SYNC_STATUS_RESET. If the update operation is not completed yet, the status will be SNTP_SYNC_STATUS_RESET. If a smooth mode was chosen and the synchronization is still continuing (adjtime works), then it will be SNTP_SYNC_STATUS_IN_PROGRESS.
Return SNTP_SYNC_STATUS_RESET: Reset status. SNTP_SYNC_STATUS_COMPLETED: Time is synchronized. SNTP_SYNC_STATUS_IN_PROGRESS: Smooth time sync in progress.
void sntp_set_sync_status(sntp_sync_status_t sync_status) Set status of time sync.
Parameters · sync_status: status of time sync (see sntp_sync_status_t)
void sntp_set_time_sync_notification_cb(sntp_sync_time_cb_t callback) Set a callback function for time synchronization notification.
Parameters · callback: a callback function
void sntp_set_sync_interval(uint32_t interval_ms) Set the sync interval of SNTP operation.
Note: SNTPv4 RFC 4330 enforces a minimum sync interval of 15 seconds. This sync interval will be used in the next attempt update time throught SNTP. To apply the new sync interval call the sntp_restart() function, otherwise, it will be applied after the last interval expired.
Parameters · interval_ms: The sync interval in ms. It cannot be lower than 15 seconds, otherwise 15 seconds will be set.
uint32_t sntp_get_sync_interval(void) Get the sync interval of SNTP operation.
Return the sync interval
bool sntp_restart(void) Restart SNTP.
Return True - Restart False - SNTP was not initialized yet
Type Definitions typedef void (*sntp_sync_time_cb_t)(struct timeval *tv)
SNTP callback function for notifying about time sync event.
Parameters · tv: Time received from SNTP server.

Espressif Systems

1356

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Enumerations enum sntp_sync_mode_t
SNTP time update mode.
Values:
SNTP_SYNC_MODE_IMMED Update system time immediately when receiving a response from the SNTP server.
SNTP_SYNC_MODE_SMOOTH Smooth time updating. Time error is gradually reduced using adjtime function. If the difference between SNTP response time and system time is large (more than 35 minutes) then update immediately.
enum sntp_sync_status_t SNTP sync status.
Values:
SNTP_SYNC_STATUS_RESET
SNTP_SYNC_STATUS_COMPLETED
SNTP_SYNC_STATUS_IN_PROGRESS

2.7.27 Internal and Unstable APIs
This section is listing some APIs that are internal or likely to be changed or removed in the next releases of ESP-IDF.

API Reference
Header File · components/esp_rom/include/esp_rom_sys.h

Functions int esp_rom_printf(const char *fmt, ...)
Print formated string to console device.
Note float and long long data are not supported! Return int: Total number of characters written on success; A negative number on failure. Parameters
· fmt: Format string · ...: Additional arguments, depending on the format string void esp_rom_delay_us(uint32_t us) Pauses execution for us microseconds.
Parameters · us: Number of microseconds to pause
void esp_rom_install_channel_putc(int channel, void (*putc))char c esp_rom_printf can print message to different channels simultaneously. This function can help install the low level putc function for esp_rom_printf.
Parameters · channel: Channel number (startting from 1) · putc: Function pointer to the putc implementation. Set NULL can disconnect esp_rom_printf with putc.
void esp_rom_install_uart_printf(void) Install UART1 as the default console channel, equivalent to esp_rom_install_channel_putc(1, esp_rom_uart_putc)
soc_reset_reason_t esp_rom_get_reset_reason(int cpu_no) Get reset reason of CPU.

Espressif Systems

1357

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Return Reset reason code (see in soc/reset_reasons.h) Parameters
· cpu_no: CPU number Code examples for this API section are provided in the system directory of ESP-IDF examples.
2.8 API Conventions
This document describes conventions and assumptions common to ESP-IDF Application Programming Interfaces (APIs). ESP-IDF provides several kinds of programming interfaces:
· C functions, structures, enums, type definitions and preprocessor macros declared in public header files of ESPIDF components. Various pages in the API Reference section of the programming guide contain descriptions of these functions, structures and types.
· Build system functions, predefined variables and options. These are documented in the build system guide. · Kconfig options can can be used in code and in the build system (CMakeLists.txt) files. · Host tools and their command line parameters are also part of ESP-IDF interface. ESP-IDF consists of components written specifically for ESP-IDF as well as third-party libraries. In some cases, an ESP-IDF-specific wrapper is added to the third-party library, providing an interface that is either simpler or better integrated with the rest of ESP-IDF facilities. In other cases, the original API of the third-party library is presented to the application developers. Following sections explain some of the aspects of ESP-IDF APIs and their usage.
2.8.1 Error handling
Most ESP-IDF APIs return error codes defined with esp_err_t type. See Error Handling section for more information about error handling approaches. Error Code Reference contains the list of error codes returned by ESP-IDF components.
2.8.2 Configuration structures
Important: Correct initialization of configuration structures is an important part in making the application compatible with future versions of ESP-IDF.
Most initialization or configuration functions in ESP-IDF take as an argument a pointer to a configuration structure. For example:
const esp_timer_create_args_t my_timer_args = { .callback = &my_timer_callback, .arg = callback_arg, .name = "my_timer"
}; esp_timer_handle_t my_timer; esp_err_t err = esp_timer_create(&my_timer_args, &my_timer);
Initialization functions never store the pointer to the configuration structure, so it is safe to allocate the structure on the stack. The application must initialize all fields of the structure. The following is incorrect:

Espressif Systems

1358

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
esp_timer_create_args_t my_timer_args; my_timer_args.callback = &my_timer_callback; /* Incorrect! Fields .arg and .name are not initialized */ esp_timer_create(&my_timer_args, &my_timer);
Most ESP-IDF examples use C99 designated initializers for structure initialization, since they provide a concise way of setting a subset of fields, and zero-initializing the remaining fields:
const esp_timer_create_args_t my_timer_args = { .callback = &my_timer_callback, /* Correct, fields .arg and .name are zero-initialized */
};
C++ language doesnnt support the designated initializers syntax until C++20, however GCC compiler partially supports it as an extension. When using ESP-IDF APIs in C++ code, you may consider using the following pattern:
esp_timer_create_args_t my_timer_args = {}; /* All the fields are zero-initialized */ my_timer_args.callback = &my_timer_callback;
Default initializers
For some configuration structures, ESP-IDF provides macros for setting default values of fields:
httpd_config_t config = HTTPD_DEFAULT_CONFIG(); /* HTTPD_DEFAULT_CONFIG expands to a designated initializer.
Now all fields are set to the default values. Any field can still be modified: */ config.server_port = 8081; httpd_handle_t server; esp_err_t err = httpd_start(&server, &config);
It is recommended to use default initializer macros whenever they are provided for a particular configuration structure.
2.8.3 Private APIs
Certain header files in ESP-IDF contain APIs intended to be used only in ESP-IDF source code, and not by the applications. Such header files often contain private or esp_private in their name or path. Certain components, such as hal only contain private APIs. Private APIs may be removed or changed in an incompatible way between minor or patch releases.
2.8.4 Components in example projects
ESP-IDF examples contain a variety of projects demonstrating usage of ESP-IDF APIs. In order to reduce code duplication in the examples, a few common helpers are defined inside components that are used by multiple examples. This includes components located in common_components directory, as well as some of the components located in the examples themselves. These components are not considered to be part of the ESP-IDF API. It is not recommended to reference these components directly in custom projects (via EXTRA_COMPONENT_DIRS build system variable), as they may change significantly between ESP-IDF versions. When starting a new project based on an ESP-IDF example, copy both the project and the common components it depends on out of ESP-IDF, and treat the common components as part of the project. Note that the common components are written with examples in mind, and might not include all the error handling required for production applications. Take time to read the code and understand if it applicable to your use case.

Espressif Systems

1359

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
2.8.5 API Stability
ESP-IDF uses Semantic Versioning as explained in the versions page. Minor and bugfix releases of ESP-IDF guarantee compatibility with previous releases. The sections below explain different aspects and limitations to compatibility.
Source level compatibility
ESP-IDF guarantees source level compatibility of C functions, structures, enums, type definitions and preprocessor macros declared in public header files of ESP-IDF components. Source level compatibility implies that the application can be recompiled with the newer version of ESP-IDF without changes. The following changes are allowed between minor versions and do not break source level compatibility:
· Deprecating functions (using the deprecated attribute) and header files (using a preprocessor #warning). Deprecations are listed in ESP-IDF relese notes. It is recommended to update the source code to use the newer functions or files that replace the deprecated ones, however this is not mandatory. Deprecated functions and files can be removed in major versions of ESP-IDF.
· Renaming components, moving source and header files between components iprovided that the build system ensures that correct files are still found.
· Renaming Kconfig options. Kconfig system renaming mechanism ensures that the original Kconfig option names can still be used by the application in sdkconfig file, CMake files and source code.
Lack of binary compatibility
ESP-IDF does not guarantee binary compatibility between releases. This means that if a precompiled library is built with one ESP-IDF version, it is not guaranteed to work the same way with the next minor or bugfix release. The following are the possible changes that keep source level compatibility but not binary compatibility:
· Changing numerical values for C enum members. · Adding new structure members or changing the order of members. See Configuration structures for tips that
help ensure compatibility. · Replacing an extern function with a static inline one with the same signature, or vice versa. · Replacing a function-like macro with a compatible C function.
Other exceptions from compatibility
While we try to make upgrading to a new ESP-IDF version easy, there are parts of ESP-IDF that may change between minor versions in an incompatible way. We appreciate issue reports about any unintended breaking changes that donn t fall into the categories below.
· Private APIs. · Components in example projects. · Features clearly marked as obetap, opreviewp, or oexperimentalp. · Changes made to mitigate security issues or to replace insecure default behaviors with a secure ones. · Features which were never functional. For example, if it was never possible to use a certain function or an
enumeration value, it may get renamed (as part of fixing it) or removed. This includes software features which depend on non-functional chip hardware features. · Unexpected or undefined behavior (for example, due to missing validation of argument ranges) that is not documented explicitly may be fixed/changed. · Location of Kconfig options in menuconfig. · Location and names of example projects.
2.9 Project Configuration

Espressif Systems

1360

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
2.9.1 Introduction
ESP-IDF uses kconfiglib which is a Python-based extension to the Kconfig system which provides a compile-time project configuration mechanism. Kconfig is based around options of several types: integer, string, boolean. Kconfig files specify dependencies between options, default values of the options, the way the options are grouped together, etc. For the complete list of available features please see Kconfig and kconfiglib extentions.
2.9.2 Project Configuration Menu
Application developers can open a terminal-based project configuration menu with the idf.py menuconfig build target. After being updated, this configuration is saved inside sdkconfig file in the project root directory. Based on sdkconfig, application build targets will generate sdkconfig.h file in the build directory, and will make sdkconfig options available to the project build system and source files.
2.9.3 Using sdkconfig.defaults
In some cases, such as when sdkconfig file is under revision control, the fact that sdkconfig file gets changed by the build system may be inconvenient. The build system offers a way to avoid this, in the form of sdkconfig. defaults file. This file is never touched by the build system, and can be created manually or automatically. It can contain all the options which matter for the given application and are different from the default ones. The format is the same as that of the sdkconfig file. sdkconfig.defaults can be created manually when one remembers all the changed configurations. Otherwise, the file can be generated automatically by running the idf.py savedefconfig command. Once sdkconfig.defaults is created, sdkconfig can be deleted and added to the ignore list of the revision control system (e.g. .gitignore file for git). Project build targets will automatically create sdkconfig file, populated with the settings from sdkconfig.defaults file, and the rest of the settings will be set to their default values. Note that the build process will not override settings that are already in sdkconfig by ones from sdkconfig.defaults. For more information, see Custom sdkconfig defaults.
2.9.4 Kconfig Formatting Rules
The following attributes of Kconfig files are standardized: · Within any menu, option names should have a consistent prefix. The prefix length is currently set to at least 3 characters. · The indentation style is 4 characters created by spaces. All sub-items belonging to a parent item are indented by one level deeper. For example, menu is indented by 0 characters, the config inside of the menu by 4 characters, the help of the config by 8 characters and the text of the help by 12 characters. · No trailing spaces are allowed at the end of the lines. · The maximum length of options is set to 40 characters. · The maximum length of lines is set to 120 characters.
Format checker
tools/check_kconfigs.py is provided for checking the Kconfig formatting rules. The checker checks all Kconfig and Kconfig.projbuild files in the ESP-IDF directory and generates a new file with suffix .new with some recommendations how to fix issues (if there are any). Please note that the checker cannot correct all rules and the responsibility of the developer is to check and make final corrections in order to pass the tests. For example, indentations will be corrected if there isnnt some misleading previous formatting but it cannot come up with a common prefix for options inside a menu.

Espressif Systems

1361

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
2.9.5 Backward Compatibility of Kconfig Options
The standard Kconfig tools ignore unknown options in sdkconfig. So if a developer has custom settings for options which are renamed in newer ESP-IDF releases then the given setting for the option would be silently ignored. Therefore, several features have been adopted to avoid this:
1. confgen.py is used by the tool chain to pre-process sdkconfig files before anything else, for example menuconfig, would read them. As the consequence, the settings for old options will be kept and not ignored.
2. confgen.py recursively finds all sdkconfig.rename files in ESP-IDF directory which contain old and new Kconfig option names. Old options are replaced by new ones in the sdkconfig file.
3. confgen.py post-processes sdkconfig files and generates all build outputs (sdkconfig.h, sdkconfig.cmake, auto.conf) by adding a list of compatibility statements, i.e. value of the old option is set the value of the new option (after modification). This is done in order to not break customer codes where old option might still be used.
4. Deprecated options and their replacements are automatically generated by confgen.py.
2.9.6 Configuration Options Reference
Subsequent sections contain the list of available ESP-IDF options, automatically generated from Kconfig files. Note that depending on the options selected, some options listed here may not be visible by default in the interface of menuconfig.
By convention, all option names are upper case with underscores. When Kconfig generates sdkconfig and sdkconfig.h files, option names are prefixed with CONFIG_. So if an option ENABLE_FOO is defined in a Kconfig file and selected in menuconfig, then sdkconfig and sdkconfig.h files will have CONFIG_ENABLE_FOO defined. In this reference, option names are also prefixed with CONFIG_, same as in the source code.
Build type
Contains:
· CONFIG_APP_BUILD_TYPE · CONFIG_APP_REPRODUCIBLE_BUILD
CONFIG_APP_BUILD_TYPE
Application build type
Found in: Build type
Select the way the application is built.
By default, the application is built as a binary file in a format compatible with the ESP-IDF bootloader. In addition to this application, 2nd stage bootloader is also built. Application and bootloader binaries can be written into flash and loaded/executed from there.
Another option, useful for only very small and limited applications, is to only link the .elf file of the application, such that it can be loaded directly into RAM over JTAG. Note that since IRAM and DRAM sizes are very limited, it is not possible to build any complex application this way. However for kinds of testing and debugging, this option may provide faster iterations, since the application does not need to be written into flash. Note that at the moment, ESP-IDF does not contain all the startup code required to initialize the CPUs and ROM memory (data/bss). Therefore it is necessary to execute a bit of ROM code prior to executing the application. A gdbinit file may look as follows (for ESP32):
# Connect to a running instance of OpenOCD target remote :3333 # Reset and halt the target mon reset halt # Run to a specific point in ROM code, # where most of initialization is complete. thb *0x40007d54 c # Load the application into RAM load # Run till app_main tb app_main c
Execute this gdbinit file as follows:

Espressif Systems

1362

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

xtensa-esp32-elf-gdb build/app-name.elf -x gdbinit

Example gdbinit files for other targets can be found in tools/test_apps/system/gdb_loadable_elf/

Recommended sdkconfig.defaults for building loadable ELF files is as follows. CONFIG_APP_BUILD_TYPE_ELF_RAM is required, other options help reduce application memory footprint.

CONFIG_APP_BUILD_TYPE_ELF_RAM=y CONFIG_VFS_SUPPORT_TERMIOS= CONFIG_NEWLIB_NANO_FORMAT=y CONFIG_ESP_SYSTEM_PANIC_PRINT_HALT=y CONFIG_ESP_DEBUG_STUBS_ENABLE= CONFIG_ESP_ERR_TO_NAME_LOOKUP=

Available options:

· Default

(binary

application

+

2nd

stage

bootloader)

(APP_BUILD_TYPE_APP_2NDBOOT)

· ELF file, loadable into RAM (EXPERIMENTAL)) (APP_BUILD_TYPE_ELF_RAM)

CONFIG_APP_REPRODUCIBLE_BUILD
Enable reproducible build
Found in: Build type
If enabled, all date, time, and path information would be eliminated. A .gdbinit file would be create automatically. (or will be append if you have one already)
Default value: · No (disabled)

Application manager
Contains:
· CONFIG_APP_EXCLUDE_PROJECT_NAME_VAR · CONFIG_APP_EXCLUDE_PROJECT_VER_VAR · CONFIG_APP_PROJECT_VER_FROM_CONFIG · CONFIG_APP_RETRIEVE_LEN_ELF_SHA · CONFIG_APP_COMPILE_TIME_DATE

CONFIG_APP_COMPILE_TIME_DATE
Use time/date stamp for app
Found in: Application manager
If set, then the app will be built with the current time/date stamp. It is stored in the app description structure. If not set, time/date stamp will be excluded from app image. This can be useful for getting the same binary image files made from the same source, but at different times.
Default value: · Yes (enabled)

CONFIG_APP_EXCLUDE_PROJECT_VER_VAR
Exclude PROJECT_VER from firmware image
Found in: Application manager
The PROJECT_VER variable from the build system will not affect the firmware image. This value will not be contained in the esp_app_desc structure.
Default value: · No (disabled)

Espressif Systems

1363

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_APP_EXCLUDE_PROJECT_NAME_VAR
Exclude PROJECT_NAME from firmware image
Found in: Application manager
The PROJECT_NAME variable from the build system will not affect the firmware image. This value will not be contained in the esp_app_desc structure.
Default value: · No (disabled)

CONFIG_APP_PROJECT_VER_FROM_CONFIG
Get the project version from Kconfig
Found in: Application manager
If this is enabled, then config item APP_PROJECT_VER will be used for the variable PROJECT_VER. Other ways to set PROJECT_VER will be ignored.
Default value: · No (disabled)

CONFIG_APP_PROJECT_VER Project version Found in: Application manager > CONFIG_APP_PROJECT_VER_FROM_CONFIG Project version Default value: · 1 if CONFIG_APP_PROJECT_VER_FROM_CONFIG

CONFIG_APP_RETRIEVE_LEN_ELF_SHA
The length of APP ELF SHA is stored in RAM(chars)
Found in: Application manager
At startup, the app will read this many hex characters from the embedded APP ELF SHA-256 hash value and store it in static RAM. This ensures the app ELF SHA-256 value is always available if it needs to be printed by the panic handler code. Changing this value will change the size of a static buffer, in bytes.
Range: · from 8 to 64
Default value: · 16

Bootloader config
Contains:
· CONFIG_BOOTLOADER_LOG_LEVEL · CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION · CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE · CONFIG_BOOTLOADER_FLASH_XMC_SUPPORT · CONFIG_BOOTLOADER_APP_TEST · CONFIG_BOOTLOADER_FACTORY_RESET · CONFIG_BOOTLOADER_HOLD_TIME_GPIO · CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC · CONFIG_BOOTLOADER_SKIP_VALIDATE_ALWAYS

Espressif Systems

1364

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· CONFIG_BOOTLOADER_SKIP_VALIDATE_ON_POWER_ON · CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP · CONFIG_BOOTLOADER_WDT_ENABLE · CONFIG_BOOTLOADER_VDDSDIO_BOOST
CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION Bootloader optimization Level Found in: Bootloader config This option sets compiler optimization level (gcc -O argument) for the bootloader. · The default oSizepsetting will add the -0s flag to CFLAGS. · The oDebugpsetting will add the -Og flag to CFLAGS. · The oPerformancepsetting will add the -O2 flag to CFLAGS. · The oNonepsetting will add the -O0 flag to CFLAGS. Note that custom optimization levels may be unsupported. Available options: · Size (-Os) (BOOTLOADER_COMPILER_OPTIMIZATION_SIZE) · Debug (-Og) (BOOTLOADER_COMPILER_OPTIMIZATION_DEBUG) · Optimize for performance (-O2) (BOOTLOADER_COMPILER_OPTIMIZATION_PERF) · Debug without optimization (-O0) (BOOTLOADER_COMPILER_OPTIMIZATION_NONE)
CONFIG_BOOTLOADER_LOG_LEVEL Bootloader log verbosity Found in: Bootloader config Specify how much output to see in bootloader logs. Available options: · No output (BOOTLOADER_LOG_LEVEL_NONE) · Error (BOOTLOADER_LOG_LEVEL_ERROR) · Warning (BOOTLOADER_LOG_LEVEL_WARN) · Info (BOOTLOADER_LOG_LEVEL_INFO) · Debug (BOOTLOADER_LOG_LEVEL_DEBUG) · Verbose (BOOTLOADER_LOG_LEVEL_VERBOSE)
CONFIG_BOOTLOADER_VDDSDIO_BOOST VDDSDIO LDO voltage Found in: Bootloader config If this option is enabled, and VDDSDIO LDO is set to 1.8V (using eFuse or MTDI bootstrapping pin), bootloader will change LDO settings to output 1.9V instead. This helps prevent flash chip from browning out during flash programming operations. This option has no effect if VDDSDIO is set to 3.3V, or if the internal VDDSDIO regulator is disabled via eFuse. Available options: · 1.8V (BOOTLOADER_VDDSDIO_BOOST_1_8V) · 1.9V (BOOTLOADER_VDDSDIO_BOOST_1_9V)

Espressif Systems

1365

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_BOOTLOADER_FACTORY_RESET GPIO triggers factory reset Found in: Bootloader config Allows to reset the device to factory settings: - clear one or more data partitions; - boot from ofactoryp partition. The factory reset will occur if there is a GPIO input held at the configured level while device starts up. See settings below. Default value: · No (disabled)
CONFIG_BOOTLOADER_NUM_PIN_FACTORY_RESET Number of the GPIO input for factory reset Found in: Bootloader config > CONFIG_BOOTLOADER_FACTORY_RESET The selected GPIO will be configured as an input with internal pull-up enabled (note that on some SoCs. not all pins have an internal pull-up, consult the hardware datasheet for details.) To trigger a factory reset, this GPIO must be held high or low (as configured) on startup. Default value: · 4 if CONFIG_BOOTLOADER_FACTORY_RESET
CONFIG_BOOTLOADER_FACTORY_RESET_PIN_LEVEL Factory reset GPIO level Found in: Bootloader config > CONFIG_BOOTLOADER_FACTORY_RESET Pin level for factory reset, can be triggered on low or high. Available options: · Reset on GPIO low (BOOTLOADER_FACTORY_RESET_PIN_LOW) · Reset on GPIO high (BOOTLOADER_FACTORY_RESET_PIN_HIGH)
CONFIG_BOOTLOADER_OTA_DATA_ERASE Clear OTA data on factory reset (select factory partition) Found in: Bootloader config > CONFIG_BOOTLOADER_FACTORY_RESET The device will boot from ofactoryppartition (or OTA slot 0 if no factory partition is present) after a factory reset.
CONFIG_BOOTLOADER_DATA_FACTORY_RESET Comma-separated names of partitions to clear on factory reset Found in: Bootloader config > CONFIG_BOOTLOADER_FACTORY_RESET Allows customers to select which data partitions will be erased while factory reset. Specify the names of partitions as a comma-delimited with optional spaces for readability. (Like this:
onvs, phy_init, lp) Make sure that the name specified in the partition table and here are the same. Partitions of type oapppcannot be specified here. Default value: ·onvspif CONFIG_BOOTLOADER_FACTORY_RESET

Espressif Systems

1366

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_BOOTLOADER_APP_TEST
GPIO triggers boot from test app partition
Found in: Bootloader config
Allows to run the test app from oTESTppartition. A boot from otestppartition will occur if there is a GPIO input pulled low while device starts up. See settings below.
Default value: · No (disabled) if CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK

CONFIG_BOOTLOADER_NUM_PIN_APP_TEST
Number of the GPIO input to boot TEST partition
Found in: Bootloader config > CONFIG_BOOTLOADER_APP_TEST
The selected GPIO will be configured as an input with internal pull-up enabled. To trigger a test app, this GPIO must be pulled low on reset. After the GPIO input is deactivated and the device reboots, the old application will boot. (factory or OTA[x]). Note that GPIO34-39 do not have an internal pullup and an external one must be provided.
Range: · from 0 to 39 if CONFIG_BOOTLOADER_APP_TEST
Default value: · 18 if CONFIG_BOOTLOADER_APP_TEST

CONFIG_BOOTLOADER_HOLD_TIME_GPIO
Hold time of GPIO for reset/test mode (seconds)
Found in: Bootloader config
The GPIO must be held low continuously for this period of time after reset before a factory reset or test partition boot (as applicable) is performed.
Default value: · 5 if CONFIG_BOOTLOADER_FACTORY_RESET || CONFIG_BOOTLOADER_APP_TEST

CONFIG_BOOTLOADER_WDT_ENABLE
Use RTC watchdog in start code
Found in: Bootloader config
Tracks the execution time of startup code. If the execution time is exceeded, the RTC_WDT will restart system. It is also useful to prevent a lock up in start code caused by an unstable power source. NOTE: Tracks the execution time starts from the bootloader code - re-set timeout, while selecting the source for slow_clk - and ends calling app_main. Re-set timeout is needed due to WDT uses a SLOW_CLK clock source. After changing a frequency slow_clk a time of WDT needs to re-set for new frequency. slow_clk depends on ESP32_RTC_CLK_SRC (INTERNAL_RC or EXTERNAL_CRYSTAL).
Default value: · Yes (enabled)

CONFIG_BOOTLOADER_WDT_DISABLE_IN_USER_CODE
Allows RTC watchdog disable in user code
Found in: Bootloader config > CONFIG_BOOTLOADER_WDT_ENABLE
If this option is set, the ESP-IDF app must explicitly reset, feed, or disable the rtc_wdt in the appns own code. If this option is not set (default), then rtc_wdt will be disabled by ESP-IDF before calling the app_main() function.

Espressif Systems

1367

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Use function rtc_wdt_feed() for resetting counter of rtc_wdt. Use function rtc_wdt_disable() for disabling rtc_wdt.
Default value: · No (disabled)

CONFIG_BOOTLOADER_WDT_TIME_MS
Timeout for RTC watchdog (ms)
Found in: Bootloader config > CONFIG_BOOTLOADER_WDT_ENABLE
Verify that this parameter is correct and more then the execution time. Pay attention to options such as reset to factory, trigger test partition and encryption on boot - these options can increase the execution time. Note: RTC_WDT will reset while encryption operations will be performed.
Range: · from 0 to 120000
Default value: · 9000

CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE
Enable app rollback support
Found in: Bootloader config
After updating the app, the bootloader runs a new app with the oESP_OTA_IMG_PENDING_VERIFYpstate set. This state prevents the re-run of this app.
After the first boot of the new app in the user code, the function should be called to confirm the operability of the app or vice versa about its non-operability. If the app is working, then it is marked as valid. Otherwise, it is marked as not valid and rolls back to the previous working app. A reboot is performed, and the app is booted before the software update. Note: If during the first boot a new app the power goes out or the WDT works, then roll back will happen. Rollback is possible only between the apps with the same security versions.
Default value: · No (disabled)

CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK Enable app anti-rollback support Found in: Bootloader config > CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE This option prevents rollback to previous firmware/application image with lower security version. Default value: · No (disabled) if CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE

CONFIG_BOOTLOADER_APP_SECURE_VERSION
eFuse secure version of app
Found in: Bootloader config > CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE > CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK
The secure version is the sequence number stored in the header of each firmware. The security version is set in the bootloader, version is recorded in the eFuse field as the number of set ones. The allocated number of bits in the efuse field for storing the security version is limited (see BOOTLOADER_APP_SEC_VER_SIZE_EFUSE_FIELD option).
Bootloader: When bootloader selects an app to boot, an app is selected that has a security version greater or equal that recorded in eFuse field. The app is booted with a higher (or equal) secure version.

Espressif Systems

1368

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
The security version is worth increasing if in previous versions there is a significant vulnerability and their use is not acceptable. Your partition table should has a scheme with ota_0 + ota_1 (without factory). Default value:
· 0 if CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK
CONFIG_BOOTLOADER_APP_SEC_VER_SIZE_EFUSE_FIELD Size of the efuse secure version field Found in: Bootloader config > CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE > CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK The size of the efuse secure version field. Its length is limited to 32 bits for ESP32 and 16 bits for ESP32-S2. This determines how many times the security version can be increased. Range: · from 1 to 16 if CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK Default value: · 16 if CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK
CONFIG_BOOTLOADER_EFUSE_SECURE_VERSION_EMULATE Emulate operations with efuse secure version(only test) Found in: Bootloader config > CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE > CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK This option allows to emulate read/write operations with all eFuses and efuse secure version. It allows to test anti-rollback implemention without permanent write eFuse bits. There should be an entry in partition table with following details: emul_efuse, data, efuse, , 0x2000. This option enables: EFUSE_VIRTUAL and EFUSE_VIRTUAL_KEEP_IN_FLASH. Default value: · No (disabled) if CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK
CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP Skip image validation when exiting deep sleep Found in: Bootloader config This option disables the normal validation of an image coming out of deep sleep (checksums, SHA256, and signature). This is a trade-off between wakeup performance from deep sleep, and image integrity checks. Only enable this if you know what you are doing. It should not be used in conjunction with using deep_sleep() entry and changing the active OTA partition as this would skip the validation upon first load of the new OTA partition. It is possible to enable this option with Secure Boot if oallow insecure optionspis enabled, however itn s strongly recommended to NOT enable it as it may allow a Secure Boot bypass. Default value: · No (disabled) if (CONFIG_SECURE_BOOT && CONFIG_SECURE_BOOT_INSECURE) || CONFIG_SECURE_BOOT

Espressif Systems

1369

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_BOOTLOADER_SKIP_VALIDATE_ON_POWER_ON Skip image validation from power on reset (READ HELP FIRST) Found in: Bootloader config Some applications need to boot very quickly from power on. By default, the entire app binary is read from flash and verified which takes up a significant portion of the boot time. Enabling this option will skip validation of the app when the SoC boots from power on. Note that in this case itns not possible for the bootloader to detect if an app image is corrupted in the flash, therefore itn s not possible to safely fall back to a different app partition. Flash corruption of this kind is unlikely but can happen if there is a serious firmware bug or physical damage. Following other reset types, the bootloader will still validate the app image. This increases the chances that flash corruption resulting in a crash can be detected following soft reset, and the bootloader will fall back to a valid app image. To increase the chances of successfully recovering from a flash corruption event, keep the option BOOTLOADER_WDT_ENABLE enabled and consider also enabling BOOTLOADER_WDT_DISABLE_IN_USER_CODE - then manually disable the RTC Watchdog once the app is running. In addition, enable both the Task and Interrupt watchdog timers with reset options set. Default value: · No (disabled)
CONFIG_BOOTLOADER_SKIP_VALIDATE_ALWAYS Skip image validation always (READ HELP FIRST) Found in: Bootloader config Selecting this option prevents the bootloader from ever validating the app image before booting it. Any flash corruption of the selected app partition will make the entire SoC unbootable. Although flash corruption is a very rare case, it is not recommended to select this option. Consider selecting oSkip image validation from power on resetpinstead. However, if boot time is the only important factor then it can be enabled. Default value: · No (disabled)
CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC Reserve RTC FAST memory for custom purposes Found in: Bootloader config This option allows the customer to place data in the RTC FAST memory, this area remains valid when rebooted, except for power loss. This memory is located at a fixed address and is available for both the bootloader and the application. (The application and bootoloader must be compiled with the same option). The RTC FAST memory has access only through PRO_CPU. Default value: · No (disabled)
CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC_SIZE Size in bytes for custom purposes Found in: Bootloader config > CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC This option reserves in RTC FAST memory the area for custom purposes. If you want to create your own bootloader and save more information in this area of memory, you can increase it. It must be a multiple of 4 bytes. This area (rtc_retain_mem_t) is reserved and has access from the bootloader and an application.

Espressif Systems

1370

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Range: · from 0 to 0x10 if CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC
Default value: · 0 if CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC
CONFIG_BOOTLOADER_FLASH_XMC_SUPPORT Enable the support for flash chips of XMC (READ HELP FIRST) Found in: Bootloader config Perform the startup flow recommended by XMC. Please consult XMC for the details of this flow. XMC chips will be forbidden to be used, when this option is disabled. DONnT DISABLE THIS UNLESS YOU KNOW WHAT YOU ARE DOING. Default value: · Yes (enabled)
Security features
Contains: · CONFIG_SECURE_BOOT_INSECURE · CONFIG_SECURE_SIGNED_APPS_SCHEME · CONFIG_SECURE_FLASH_CHECK_ENC_EN_IN_APP · CONFIG_SECURE_BOOT_ENABLE_AGGRESSIVE_KEY_REVOKE · CONFIG_SECURE_FLASH_ENC_ENABLED · CONFIG_SECURE_BOOT · Potentially insecure options · CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT · CONFIG_SECURE_BOOT_VERIFICATION_KEY · CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES · CONFIG_SECURE_UART_ROM_DL_MODE · CONFIG_SECURE_SIGNED_ON_UPDATE_NO_SECURE_BOOT
CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT Require signed app images Found in: Security features Require apps to be signed to verify their integrity. This option uses the same app signature scheme as hardware secure boot, but unlike hardware secure boot it does not prevent the bootloader from being physically updated. This means that the device can be secured against remote network access, but not physical access. Compared to using hardware Secure Boot this option is much simpler to implement.
CONFIG_SECURE_SIGNED_APPS_SCHEME App Signing Scheme Found in: Security features Select the Secure App signing scheme. Depends on the Chip Revision. There are two options: 1. ECDSA based secure boot scheme. (Only choice for Secure Boot V1) Supported in ESP32 and ESP32ECO3. 2. The RSA based secure boot scheme. (Only choice for Secure Boot V2) Supported in ESP32ECO3 (ESP32 Chip Revision 3 onwards), ESP32-S2, ESP32-C3, ESP32-S3. Available options:

Espressif Systems

1371

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· ECDSA (SECURE_SIGNED_APPS_ECDSA_SCHEME) Embeds the ECDSA public key in the bootloader and signs the application with an ECDSA key. Refer to the documentation before enabling.
· RSA (SECURE_SIGNED_APPS_RSA_SCHEME) Appends the RSA-3072 based Signature block to the application. Refer to <Secure Boot Version 2 documentation link> before enabling.
CONFIG_SECURE_SIGNED_ON_UPDATE_NO_SECURE_BOOT
Verify app signature on update
Found in: Security features
If this option is set, any OTA updated apps will have the signature verified before being considered valid.
When enabled, the signature is automatically checked whenever the esp_ota_ops.h APIs are used for OTA updates, or esp_image_format.h APIs are used to verify apps.
If hardware secure boot is enabled, this option is always enabled and cannot be disabled. If hardware secure boot is not enabled, this option still adds significant security against network-based attackers by preventing spoofing of OTA updates.
Default value: · Yes (enabled) if CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT
CONFIG_SECURE_BOOT
Enable hardware Secure Boot in bootloader (READ DOCS FIRST)
Found in: Security features
Build a bootloader which enables Secure Boot on first boot.
Once enabled, Secure Boot will not boot a modified bootloader. The bootloader will only load a partition table or boot an app if the data has a verified digital signature. There are implications for reflashing updated apps once secure boot is enabled.
When enabling secure boot, JTAG and ROM BASIC Interpreter are permanently disabled by default.
Default value: · No (disabled)
CONFIG_SECURE_BOOT_VERSION
Select secure boot version
Found in: Security features > CONFIG_SECURE_BOOT
Select the Secure Boot Version. Depends on the Chip Revision. Secure Boot V2 is the new RSA based secure boot scheme. Supported in ESP32-ECO3 (ESP32 Chip Revision 3 onwards), ESP32-S2, ESP32-C3 ECO3. Secure Boot V1 is the AES based secure boot scheme. Supported in ESP32 and ESP32-ECO3.
Available options: · Enable Secure Boot version 1 (SECURE_BOOT_V1_ENABLED) Build a bootloader which enables secure boot version 1 on first boot. Refer to the Secure Boot section of the ESP-IDF Programmerns Guide for this version before enabling. · Enable Secure Boot version 2 (SECURE_BOOT_V2_ENABLED) Build a bootloader which enables Secure Boot version 2 on first boot. Refer to Secure Boot V2 section of the ESP-IDF Programmerns Guide for this version before enabling.

Espressif Systems

1372

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES Sign binaries during build Found in: Security features Once secure boot or signed app requirement is enabled, app images are required to be signed. If enabled (default), these binary files are signed as part of the build process. The file named inoSecure boot private signing keypwill be used to sign the image. If disabled, unsigned app/partition data will be built. They must be signed manually using espsecure.py. Version 1 to enable ECDSA Based Secure Boot and Version 2 to enable RSA based Secure Boot. (for example, on a remote signing server.)
CONFIG_SECURE_BOOT_SIGNING_KEY Secure boot private signing key Found in: Security features > CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES Path to the key file used to sign app images. Key file is an ECDSA private key (NIST256p curve) in PEM format for Secure Boot V1. Key file is an RSA private key in PEM format for Secure Boot V2. Path is evaluated relative to the project directory. You can generate a new signing key by running the following command: espsecure.py generate_signing_key secure_boot_signing_key.pem See the Secure Boot section of the ESP-IDF Programmerns Guide for this version for details. Default value: ·osecure_boot_signing_key.pempif CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES

CONFIG_SECURE_BOOT_VERIFICATION_KEY Secure boot public signature verification key Found in: Security features Path to a public key file used to verify signed images. Secure Boot V1: This ECDSA public key is compiled into the bootloader and/or app, to verify app images. Secure Boot V2: This RSA public key is compiled into the signature block at the end of the bootloader/app. Key file is in raw binary format, and can be extracted from a PEM formatted private key using the espsecure.py extract_public_key command. Refer to the Secure Boot section of the ESP-IDF Programmerns Guide for this version before enabling.
CONFIG_SECURE_BOOT_ENABLE_AGGRESSIVE_KEY_REVOKE Enable Aggressive key revoke strategy Found in: Security features If this option is set, ROM bootloader will revoke the public key digest burned in efuse block if it fails to verify the signature of software bootloader with it. Revocation of keys does not happen when enabling secure boot. Once secure boot is enabled, key revocation checks will be done on subsequent boot-up, while verifying the software bootloader This feature provides a strong resistance against physical attacks on the device. NOTE: Once a digest slot is revoked, it can never be used again to verify an image This can lead to permanent bricking of the device, in case all keys are revoked because of signature verification failure. Default value:

Espressif Systems

1373

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· No (disabled) if CONFIG_SECURE_BOOT
CONFIG_SECURE_BOOT_INSECURE Allow potentially insecure options Found in: Security features You can disable some of the default protections offered by secure boot, in order to enable testing or a custom combination of security features. Only enable these options if you are very sure. Refer to the Secure Boot section of the ESP-IDF Programmerns Guide for this version before enabling. Default value: · No (disabled) if CONFIG_SECURE_BOOT
CONFIG_SECURE_FLASH_ENC_ENABLED Enable flash encryption on boot (READ DOCS FIRST) Found in: Security features If this option is set, flash contents will be encrypted by the bootloader on first boot. Note: After first boot, the system will be permanently encrypted. Re-flashing an encrypted system is complicated and not always possible. Read Flash Encryption before enabling. Default value: · No (disabled)
CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE Size of generated AES-XTS key Found in: Security features > CONFIG_SECURE_FLASH_ENC_ENABLED Size of generated AES-XTS key. AES-128 uses a 256-bit key (32 bytes) which occupies one Efuse key block. AES-256 uses a 512-bit key (64 bytes) which occupies two Efuse key blocks. This setting is ignored if either type of key is already burned to Efuse before the first boot. In this case, the pre-burned key is used and no new key is generated. Available options: · AES-128 (256-bit key) (SECURE_FLASH_ENCRYPTION_AES128) · AES-256 (512-bit key) (SECURE_FLASH_ENCRYPTION_AES256)
CONFIG_SECURE_FLASH_ENCRYPTION_MODE Enable usage mode Found in: Security features > CONFIG_SECURE_FLASH_ENC_ENABLED By default Development mode is enabled which allows ROM download mode to perform flash encryption operations (plaintext is sent to the device, and it encrypts it internally and writes ciphertext to flash.) This mode is not secure, itns possible for an attacker to write their own chosen plaintext to flash. Release mode should always be selected for production or manufacturing. Once enabled itns no longer possible for the device in ROM Download Mode to use the flash encryption hardware. Refer to the Flash Encryption section of the ESP-IDF Programmerns Guide for details.

Espressif Systems

1374

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Available options: · Development (NOT SECURE) (SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT) · Release (SECURE_FLASH_ENCRYPTION_MODE_RELEASE)

Potentially insecure options Contains:
· CONFIG_SECURE_BOOT_V2_ALLOW_EFUSE_RD_DIS · CONFIG_SECURE_BOOT_ALLOW_SHORT_APP_PARTITION · CONFIG_SECURE_BOOT_ALLOW_JTAG · CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_ENC · CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_CACHE · CONFIG_SECURE_BOOT_ALLOW_UNUSED_DIGEST_SLOTS · CONFIG_SECURE_FLASH_REQUIRE_ALREADY_ENABLED

CONFIG_SECURE_BOOT_ALLOW_JTAG

Allow JTAG Debugging

Found in: Security features > Potentially insecure options

If not set (default), the bootloader will permanently disable JTAG (across entire chip) on first boot when either secure boot or flash encryption is enabled.

Setting this option leaves JTAG on for debugging, which negates all protections of flash encryption and some of the protections of secure boot.

Only set this option in testing environments.

Default value:

· No

(disabled)

if

CONFIG_SECURE_BOOT_INSECURE

||

SE-

CURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT

CONFIG_SECURE_BOOT_ALLOW_SHORT_APP_PARTITION
Allow app partition length not 64KB aligned
Found in: Security features > Potentially insecure options
If not set (default), app partition size must be a multiple of 64KB. App images are padded to 64KB length, and the bootloader checks any trailing bytes after the signature (before the next 64KB boundary) have not been written. This is because flash cache maps entire 64KB pages into the address space. This prevents an attacker from appending unverified data after the app image in the flash, causing it to be mapped into the address space.
Setting this option allows the app partition length to be unaligned, and disables padding of the app image to this length. It is generally not recommended to set this option, unless you have a legacy partitioning scheme which doesnnt support 64KB aligned partition lengths.

CONFIG_SECURE_BOOT_V2_ALLOW_EFUSE_RD_DIS
Allow additional read protecting of efuses
Found in: Security features > Potentially insecure options
If not set (default, recommended), on first boot the bootloader will burn the WR_DIS_RD_DIS efuse when Secure Boot is enabled. This prevents any more efuses from being read protected.
If this option is set, it will remain possible to write the EFUSE_RD_DIS efuse field after Secure Boot is enabled. This may allow an attacker to read-protect the BLK2 efuse (for ESP32) and BLOCK4BLOCK10 (i.e. BLOCK_KEY0-BLOCK_KEY5)(for other chips) holding the public key digest, causing an immediate denial of service and possibly allowing an additional fault injection attack to bypass the signature protection.

Espressif Systems

1375

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

NOTE: Once a BLOCK is read-protected, the application will read all zeros from that block NOTE: If oUART ROM download mode (Permanently disabled (recommended))por oUART ROM download mode (Permanently switch to Secure mode (recommended))pis set, then it is __NOT__ possible to read/write efuses using espefuse.py utility. However, efuse can be read/written from the application
CONFIG_SECURE_BOOT_ALLOW_UNUSED_DIGEST_SLOTS Leave unused digest slots available (not revoke) Found in: Security features > Potentially insecure options If not set (default), during startup in the app all unused digest slots will be revoked. To revoke unused slot will be called esp_efuse_set_digest_revoke(num_digest) for each digest. Revoking unused digest slots makes ensures that no trusted keys can be added later by an attacker. If set, it means that you have a plan to use unused digests slots later. Default value: · No (disabled) if CONFIG_SECURE_BOOT_INSECURE
CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_ENC Leave UART bootloader encryption enabled Found in: Security features > Potentially insecure options If not set (default), the bootloader will permanently disable UART bootloader encryption access on first boot. If set, the UART bootloader will still be able to access hardware encryption. It is recommended to only set this option in testing environments. Default value: · No (disabled) if SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT
CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_CACHE Leave UART bootloader flash cache enabled Found in: Security features > Potentially insecure options If not set (default), the bootloader will permanently disable UART bootloader flash cache access on first boot. If set, the UART bootloader will still be able to access the flash cache. Only set this option in testing environments. Default value: · No (disabled) if SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT
CONFIG_SECURE_FLASH_REQUIRE_ALREADY_ENABLED Require flash encryption to be already enabled Found in: Security features > Potentially insecure options If not set (default), and flash encryption is not yet enabled in eFuses, the 2nd stage bootloader will enable flash encryption: generate the flash encryption key and program eFuses. If this option is set, and flash encryption is not yet enabled, the bootloader will error out and reboot. If flash encryption is enabled in eFuses, this option does not change the bootloader behavior. Only use this option in testing environments, to avoid accidentally enabling flash encryption on the wrong device. The device needs to have flash encryption already enabled using espefuse.py. Default value: · No (disabled) if SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT

Espressif Systems

1376

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_SECURE_FLASH_CHECK_ENC_EN_IN_APP
Check Flash Encryption enabled on app startup
Found in: Security features
If set (default), in an app during startup code, there is a check of the flash encryption eFuse bit is on (as the bootloader should already have set it). The app requires this bit is on to continue work otherwise abort.
If not set, the app does not care if the flash encryption eFuse bit is set or not.
Default value: · Yes (enabled) if CONFIG_SECURE_FLASH_ENC_ENABLED
CONFIG_SECURE_UART_ROM_DL_MODE
UART ROM download mode
Found in: Security features
Available options: · UART ROM download mode (Permanently disabled (recommended)) (SECURE_DISABLE_ROM_DL_MODE) If set, during startup the app will burn an eFuse bit to permanently disable the UART ROM Download Mode. This prevents any future use of esptool.py, espefuse.py and similar tools. Once disabled, if the SoC is booted with strapping pins set for ROM Download Mode then an error is printed instead. It is recommended to enable this option in any production application where Flash Encryption and/or Secure Boot is enabled and access to Download Mode is not required. It is also possible to permanently disable Download Mode by calling esp_efuse_disable_rom_download_mode() at runtime. · UART ROM download mode (Permanently switch to Secure mode (recommended)) (SECURE_ENABLE_SECURE_ROM_DL_MODE) If set, during startup the app will burn an eFuse bit to permanently switch the UART ROM Download Mode into a separate Secure Download mode. This option can only work if Download Mode is not already disabled by eFuse. Secure Download mode limits the use of Download Mode functions to simple flash read, write and erase operations, plus a command to return a summary of currently enabled security features. Secure Download mode is not compatible with the esptool.py flasher stub feature, espefuse.py, read/writing memory or registers, encrypted download, or any other features that interact with unsupported Download Mode commands. Secure Download mode should be enabled in any application where Flash Encryption and/or Secure Boot is enabled. Disabling this option does not immediately cancel the benefits of the security features, but it increases the potential oattack surfacepfor an attacker to try and bypass them with a successful physical attack. It is also possible to enable secure download mode at runtime by calling esp_efuse_enable_rom_secure_download_mode() Note: Secure Download mode is not available for ESP32 (includes revisions till ECO3). · UART ROM download mode (Enabled (not recommended)) (SECURE_INSECURE_ALLOW_DL_MODE) This is a potentially insecure option. Enabling this option will allow the full UART download mode to stay enabled. This option SHOULD NOT BE ENABLED for production use cases.
Boot ROM Behavior
Contains:
· CONFIG_BOOT_ROM_LOG_SCHEME

Espressif Systems

1377

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_BOOT_ROM_LOG_SCHEME
Permanently change Boot ROM output
Found in: Boot ROM Behavior
Controls the Boot ROM log behavior. The rom log behavior can only be changed for once, specific eFuse bit(s) will be burned at app boot stage.
Available options: · Always Log (BOOT_ROM_LOG_ALWAYS_ON) Always print ROM logs, this is the default behavior. · Permanently disable logging (BOOT_ROM_LOG_ALWAYS_OFF) Donnt print ROM logs. · Log on GPIO High (BOOT_ROM_LOG_ON_GPIO_HIGH) Print ROM logs when GPIO level is high during start up. The GPIO number is chip dependent, e.g. on ESP32-S2, the control GPIO is GPIO46. · Log on GPIO Low (BOOT_ROM_LOG_ON_GPIO_LOW) Print ROM logs when GPIO level is low during start up. The GPIO number is chip dependent, e.g. on ESP32-S2, the control GPIO is GPIO46.

Serial flasher config
Contains:
· CONFIG_ESPTOOLPY_AFTER · CONFIG_ESPTOOLPY_BEFORE · CONFIG_ESPTOOLPY_FLASHSIZE_DETECT · CONFIG_ESPTOOLPY_NO_STUB · CONFIG_ESPTOOLPY_OCT_FLASH · CONFIG_ESPTOOLPY_FLASH_SAMPLE_MODE · CONFIG_ESPTOOLPY_FLASHSIZE · CONFIG_ESPTOOLPY_FLASHMODE · CONFIG_ESPTOOLPY_FLASHFREQ

CONFIG_ESPTOOLPY_NO_STUB
Disable download stub
Found in: Serial flasher config
The flasher tool sends a precompiled download stub first by default. That stub allows things like compressed downloads and more. Usually you should not need to disable that feature
Default value: · No (disabled)

CONFIG_ESPTOOLPY_OCT_FLASH Enable Octal Flash Found in: Serial flasher config Default value: · No (disabled)

CONFIG_ESPTOOLPY_FLASHMODE Flash SPI mode Found in: Serial flasher config Mode the flash chip is flashed in, as well as the default mode for the binary to run in.

Espressif Systems

1378

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Available options: · QIO (ESPTOOLPY_FLASHMODE_QIO) · QOUT (ESPTOOLPY_FLASHMODE_QOUT) · DIO (ESPTOOLPY_FLASHMODE_DIO) · DOUT (ESPTOOLPY_FLASHMODE_DOUT) · OPI (ESPTOOLPY_FLASHMODE_OPI)
CONFIG_ESPTOOLPY_FLASH_SAMPLE_MODE Flash Sampling Mode Found in: Serial flasher config Available options: · STR Mode (ESPTOOLPY_FLASH_SAMPLE_MODE_STR) · DTR Mode (ESPTOOLPY_FLASH_SAMPLE_MODE_DTR)
CONFIG_ESPTOOLPY_FLASHFREQ Flash SPI speed Found in: Serial flasher config The SPI flash frequency to be used. Available options: · 120 MHz (ESPTOOLPY_FLASHFREQ_120M) · 80 MHz (ESPTOOLPY_FLASHFREQ_80M) · 40 MHz (ESPTOOLPY_FLASHFREQ_40M) · 26 MHz (ESPTOOLPY_FLASHFREQ_26M) · 20 MHz (ESPTOOLPY_FLASHFREQ_20M)
CONFIG_ESPTOOLPY_FLASHSIZE Flash size Found in: Serial flasher config SPI flash size, in megabytes Available options: · 1 MB (ESPTOOLPY_FLASHSIZE_1MB) · 2 MB (ESPTOOLPY_FLASHSIZE_2MB) · 4 MB (ESPTOOLPY_FLASHSIZE_4MB) · 8 MB (ESPTOOLPY_FLASHSIZE_8MB) · 16 MB (ESPTOOLPY_FLASHSIZE_16MB)
CONFIG_ESPTOOLPY_FLASHSIZE_DETECT Detect flash size when flashing bootloader Found in: Serial flasher config If this option is set, flashing the project will automatically detect the flash size of the target chip and update the bootloader image before it is flashed. Default value: · Yes (enabled)

Espressif Systems

1379

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_ESPTOOLPY_BEFORE
Before flashing
Found in: Serial flasher config
Configure whether esptool.py should reset the ESP32 before flashing.
Automatic resetting depends on the RTS & DTR signals being wired from the serial port to the ESP32. Most USB development boards do this internally.
Available options: · Reset to bootloader (ESPTOOLPY_BEFORE_RESET) · No reset (ESPTOOLPY_BEFORE_NORESET)

CONFIG_ESPTOOLPY_AFTER
After flashing
Found in: Serial flasher config
Configure whether esptool.py should reset the ESP32 after flashing.
Automatic resetting depends on the RTS & DTR signals being wired from the serial port to the ESP32. Most USB development boards do this internally.
Available options: · Reset after flashing (ESPTOOLPY_AFTER_RESET) · Stay in bootloader (ESPTOOLPY_AFTER_NORESET)

Partition Table
Contains:
· CONFIG_PARTITION_TABLE_CUSTOM_FILENAME · CONFIG_PARTITION_TABLE_MD5 · CONFIG_PARTITION_TABLE_OFFSET · CONFIG_PARTITION_TABLE_TYPE

CONFIG_PARTITION_TABLE_TYPE
Partition Table
Found in: Partition Table
The partition table to flash to the ESP32. The partition table determines where apps, data and other resources are expected to be found.
The predefined partition table CSV descriptions can be found in the components/partition_table directory. These are mostly intended for example and development use, itns expect that for production use you will copy one of these CSV files and create a custom partition CSV for your application.
Available options: · Single factory app, no OTA (PARTITION_TABLE_SINGLE_APP) This is the default partition table, designed to fit into a 2MB or larger flash with a single 1MB app partition. The corresponding CSV file in the IDF directory is components/partition_table/partitions_singleapp.csv This partition table is not suitable for an app that needs OTA (over the air update) capability. · Single factory app (large), no OTA (PARTITION_TABLE_SINGLE_APP_LARGE) This is a variation of the default partition table, that expands the 1MB app partition size to 1.5MB to fit more code. The corresponding CSV file in the IDF directory is components/partition_table/partitions_singleapp_large.csv

Espressif Systems

1380

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

This partition table is not suitable for an app that needs OTA (over the air update) capability.

· Factory app, two OTA definitions (PARTITION_TABLE_TWO_OTA)

This is a basic OTA-enabled partition table with a factory app partition plus two OTA app

partitions. All are 1MB, so this partition table requires 4MB or larger flash size.

The corresponding CSV file in the IDF directory is compo-

nents/partition_table/partitions_two_ota.csv

· Custom partition table CSV (PARTITION_TABLE_CUSTOM)

Specify the path to the partition table CSV to use for your project.

Consult the Partition Table section in the ESP-IDF Programmers Guide for more information.

· Single factory app,

no OTA, encrypted NVS (PARTI-

TION_TABLE_SINGLE_APP_ENCRYPTED_NVS)

This is a variation of the default oSingle factory app, no OTAppartition table that supports

encrypted NVS when using flash encryption. See the Flash Encryption section in the ESP-IDF

Programmers Guide for more information.

The corresponding CSV file in the IDF directory is compo-

nents/partition_table/partitions_singleapp_encr_nvs.csv

· Single factory app (large), no OTA, encrypted NVS (PARTI-

TION_TABLE_SINGLE_APP_LARGE_ENC_NVS)

This is a variation of the oSingle factory app (large), no OTAppartition table that supports

encrypted NVS when using flash encryption. See the Flash Encryption section in the ESP-IDF

Programmers Guide for more information.

The corresponding CSV file in the IDF directory is compo-

nents/partition_table/partitions_singleapp_large_encr_nvs.csv

· Factory app, two OTA definitions, encrypted NVS (PARTI-

TION_TABLE_TWO_OTA_ENCRYPTED_NVS)

This is a variation of the oFactory app, two OTA definitionsppartition table that supports

encrypted NVS when using flash encryption. See the Flash Encryption section in the ESP-IDF

Programmers Guide for more information.

The corresponding CSV file in the IDF directory is compo-

nents/partition_table/partitions_two_ota_encr_nvs.csv

CONFIG_PARTITION_TABLE_CUSTOM_FILENAME Custom partition CSV file Found in: Partition Table Name of the custom partition CSV filename. This path is evaluated relative to the project root directory. Default value: ·opartitions.csvp

CONFIG_PARTITION_TABLE_OFFSET
Offset of partition table
Found in: Partition Table
The address of partition table (by default 0x8000). Allows you to move the partition table, it gives more space for the bootloader. Note that the bootloader and app will both need to be compiled with the same PARTITION_TABLE_OFFSET value.
This number should be a multiple of 0x1000.
Note that partition offsets in the partition table CSV file may need to be changed if this value is set to a higher value. To have each partition offset adapt to the configured partition table offset, leave all partition offsets blank in the CSV file.
Default value: ·o0x8000p

Espressif Systems

1381

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_PARTITION_TABLE_MD5
Generate an MD5 checksum for the partition table
Found in: Partition Table
Generate an MD5 checksum for the partition table for protecting the integrity of the table. The generation should be turned off for legacy bootloaders which cannot recognize the MD5 checksum in the partition table.
Default value: · Yes (enabled) if ESP32_COMPATIBLE_PRE_V3_1_BOOTLOADERS
Compiler options
Contains:
· CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL · CONFIG_COMPILER_OPTIMIZATION_CHECKS_SILENT · CONFIG_COMPILER_DISABLE_GCC8_WARNINGS · CONFIG_COMPILER_DUMP_RTL_FILES · CONFIG_COMPILER_WARN_WRITE_STRINGS · CONFIG_COMPILER_CXX_EXCEPTIONS · CONFIG_COMPILER_CXX_RTTI · CONFIG_COMPILER_OPTIMIZATION · CONFIG_COMPILER_HIDE_PATHS_MACROS · CONFIG_COMPILER_STACK_CHECK_MODE
CONFIG_COMPILER_OPTIMIZATION
Optimization Level
Found in: Compiler options
This option sets compiler optimization level (gcc -O argument) for the app.
· The oDefaultpsetting will add the -0g flag to CFLAGS. · The oSizepsetting will add the -0s flag to CFLAGS. · The oPerformancepsetting will add the -O2 flag to CFLAGS. · The oNonepsetting will add the -O0 flag to CFLAGS.
The oSizepsetting cause the compiled code to be smaller and faster, but may lead to difficulties of correlating code addresses to source file lines when debugging.
The oPerformancepsetting causes the compiled code to be larger and faster, but will be easier to correlated code addresses to source file lines.
oNonepwith -O0 produces compiled code without optimization.
Note that custom optimization levels may be unsupported.
Compiler optimization for the IDF bootloader is set separately, see the BOOTLOADER_COMPILER_OPTIMIZATION setting.
Available options: · Debug (-Og) (COMPILER_OPTIMIZATION_DEFAULT) · Optimize for size (-Os) (COMPILER_OPTIMIZATION_SIZE) · Optimize for performance (-O2) (COMPILER_OPTIMIZATION_PERF) · Debug without optimization (-O0) (COMPILER_OPTIMIZATION_NONE)

Espressif Systems

1382

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL
Assertion level
Found in: Compiler options
Assertions can be:
· Enabled. Failure will print verbose assertion details. This is the default. · Set to osilentpto save code size (failed assertions will abort() but user needs to use the aborting
address to find the line number with the failed assertion.) · Disabled entirely (not recommended for most configurations.) -DNDEBUG is added to
CPPFLAGS in this case.
Available options: · Enabled (COMPILER_OPTIMIZATION_ASSERTIONS_ENABLE) Enable assertions. Assertion content and line number will be printed on failure. · Silent (saves code size) (COMPILER_OPTIMIZATION_ASSERTIONS_SILENT) Enable silent assertions. Failed assertions will abort(), user needs to use the aborting address to find the line number with the failed assertion. · Disabled (sets -DNDEBUG) (COMPILER_OPTIMIZATION_ASSERTIONS_DISABLE) If assertions are disabled, -DNDEBUG is added to CPPFLAGS.
CONFIG_COMPILER_OPTIMIZATION_CHECKS_SILENT
Disable messages in ESP_RETURN_ON_* and ESP_EXIT_ON_* macros
Found in: Compiler options
If enabled, the error messages will be discarded in following check macros: ESP_RETURN_ON_ERROR - ESP_EXIT_ON_ERROR - ESP_RETURN_ON_FALSE ESP_EXIT_ON_FALSE
Default value: · No (disabled)
CONFIG_COMPILER_HIDE_PATHS_MACROS
Replace ESP-IDF and project paths in binaries
Found in: Compiler options
When expanding the __FILE__ and __BASE_FILE__ macros, replace paths inside ESP-IDF with paths relative to the placeholder stringoIDFp, and convert paths inside the project directory to relative paths.
This allows building the project with assertions or other code that embeds file paths, without the binary containing the exact path to the IDF or project directories.
This option passes -fmacro-prefix-map options to the GCC command line. To replace additional paths in your binaries, modify the project CMakeLists.txt file to pass custom -fmacro-prefix-map or -ffile-prefixmap arguments.
Default value: · Yes (enabled)
CONFIG_COMPILER_CXX_EXCEPTIONS
Enable C++ exceptions
Found in: Compiler options
Enabling this option compiles all IDF C++ files with exception support enabled.
Disabling this option disables C++ exception support in all compiled files, and any libstdc++ code which throws an exception will abort instead.

Espressif Systems

1383

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Enabling this option currently adds an additional ~500 bytes of heap overhead when an exception is thrown in user code for the first time. Default value:
· No (disabled) Contains:
· CONFIG_COMPILER_CXX_EXCEPTIONS_EMG_POOL_SIZE
CONFIG_COMPILER_CXX_EXCEPTIONS_EMG_POOL_SIZE Emergency Pool Size Found in: Compiler options > CONFIG_COMPILER_CXX_EXCEPTIONS Size (in bytes) of the emergency memory pool for C++ exceptions. This pool will be used to allocate memory for thrown exceptions when there is not enough memory on the heap. Default value: · 0 if CONFIG_COMPILER_CXX_EXCEPTIONS
CONFIG_COMPILER_CXX_RTTI Enable C++ run-time type info (RTTI) Found in: Compiler options Enabling this option compiles all C++ files with RTTI support enabled. This increases binary size (typically by tens of kB) but allows using dynamic_cast conversion and typeid operator. Default value: · No (disabled)
CONFIG_COMPILER_STACK_CHECK_MODE Stack smashing protection mode Found in: Compiler options Stack smashing protection mode. Emit extra code to check for buffer overflows, such as stack smashing attacks. This is done by adding a guard variable to functions with vulnerable objects. The guards are initialized when a function is entered and then checked when the function exits. If a guard check fails, program is halted. Protection has the following modes: · In NORMAL mode (GCC flag: -fstack-protector) only functions that call alloca, and functions with buffers larger than 8 bytes are protected. · STRONG mode (GCC flag: -fstack-protector-strong) is like NORMAL, but includes additional functions to be protected those that have local array definitions, or have references to local frame addresses. · In OVERALL mode (GCC flag: -fstack-protector-all) all functions are protected. Modes have the following impact on code performance and coverage: · performance: NORMAL > STRONG > OVERALL · coverage: NORMAL < STRONG < OVERALL The performance impact includes increasing the amount of stack memory required for each task. Available options: · None (COMPILER_STACK_CHECK_MODE_NONE) · Normal (COMPILER_STACK_CHECK_MODE_NORM) · Strong (COMPILER_STACK_CHECK_MODE_STRONG) · Overall (COMPILER_STACK_CHECK_MODE_ALL)

Espressif Systems

1384

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_COMPILER_WARN_WRITE_STRINGS
Enable -Wwrite-strings warning flag
Found in: Compiler options
Adds -Wwrite-strings flag for the C/C++ compilers.
For C, this gives string constants the type const char[] so that copying the address of one into a non-const char \* pointer produces a warning. This warning helps to find at compile time code that tries to write into a string constant.
For C++, this warns about the deprecated conversion from string literals to char \*.
Default value: · No (disabled)

CONFIG_COMPILER_DISABLE_GCC8_WARNINGS
Disable new warnings introduced in GCC 6 - 8
Found in: Compiler options
Enable this option if using GCC 6 or newer, and wanting to disable warnings which donnt appear with GCC 5.
Default value: · No (disabled)

CONFIG_COMPILER_DUMP_RTL_FILES Dump RTL files during compilation Found in: Compiler options If enabled, RTL files will be produced during compilation. These files can be used by other tools, for example to calculate call graphs.

Component config
Contains:
· ADC-Calibration · Application Level Tracing · Bluetooth · CoAP Configuration · Common ESP-related · Core dump · Driver configurations · eFuse Bit Manager · CONFIG_BLE_MESH · ESP HTTP client · ESP HTTPS OTA · ESP HTTPS server · ESP NETIF Adapter · ESP System Settings · ESP-ASIO · ESP-MQTT Configurations · ESP-TLS · ESP32S3-Specific · Ethernet · Event Loop Library · FAT Filesystem support

Espressif Systems

1385

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· FreeRTOS · GDB Stub · Hardware Abstraction Layer (HAL) and Low Level (LL) · Hardware Settings · Heap memory debugging · High resolution timer (esp_timer) · HTTP Server · IPC (Inter-Processor Call) · LCD and Touch Panel · Log output · LWIP · mbedTLS · mDNS · Modbus configuration · Newlib · NVS · OpenSSL · OpenThread · PHY · Power Management · PThreads · SPI Flash driver · SPIFFS Configuration · Supplicant · TCP Transport · TinyUSB Stack · Ultra Low Power (ULP) Co-processor · Unity unit testing library · USB-OTG · Virtual file system · Wear Levelling · Wi-Fi · Wi-Fi Provisioning Manager
Application Level Tracing Contains:
· CONFIG_APPTRACE_DESTINATION · FreeRTOS SystemView Tracing · CONFIG_APPTRACE_GCOV_ENABLE · CONFIG_APPTRACE_BUF_SIZE · CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX · CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH · CONFIG_APPTRACE_ONPANIC_HOST_FLUSH_TMO
CONFIG_APPTRACE_DESTINATION
Data Destination
Found in: Component config > Application Level Tracing
Select destination for application trace: JTAG or none (to disable).
Available options: · JTAG (APPTRACE_DEST_JTAG) · None (APPTRACE_DEST_NONE)
CONFIG_APPTRACE_ONPANIC_HOST_FLUSH_TMO

Espressif Systems

1386

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Timeout for flushing last trace data to host on panic Found in: Component config > Application Level Tracing Timeout for flushing last trace data to host in case of panic. In ms. Use -1 to disable timeout and wait forever.
CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH Threshold for flushing last trace data to host on panic Found in: Component config > Application Level Tracing Threshold for flushing last trace data to host on panic in post-mortem mode. This is minimal amount of data needed to perform flush. In bytes.
CONFIG_APPTRACE_BUF_SIZE Size of the apptrace buffer Found in: Component config > Application Level Tracing Size of the memory buffer for trace data in bytes.
CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX Size of the pending data buffer Found in: Component config > Application Level Tracing Size of the buffer for events in bytes. It is useful for buffering events from the time critical code (scheduler, ISRs etc). If this parameter is 0 then events will be discarded when main HW buffer is full.
FreeRTOS SystemView Tracing Contains: · CONFIG_APPTRACE_SV_ENABLE
CONFIG_APPTRACE_SV_ENABLE SystemView Tracing Enable Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing Enables supporrt for SEGGER SystemView tracing functionality.
CONFIG_APPTRACE_SV_TS_SOURCE Timer to use as timestamp source Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing > CONFIG_APPTRACE_SV_ENABLE SystemView needs to use a hardware timer as the source of timestamps when tracing. This option selects the timer for it. Available options: · CPU cycle counter (CCOUNT) (APPTRACE_SV_TS_SOURCE_CCOUNT) · General Purpose Timer (Timer Group) (APPTRACE_SV_TS_SOURCE_GPTIMER) · esp_timer high resolution timer (APPTRACE_SV_TS_SOURCE_ESP_TIMER)

Espressif Systems

1387

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_APPTRACE_SV_MAX_TASKS Maximum supported tasks Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing > CONFIG_APPTRACE_SV_ENABLE Configures maximum supported tasks in sysview debug
CONFIG_APPTRACE_SV_BUF_WAIT_TMO Trace buffer wait timeout Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing > CONFIG_APPTRACE_SV_ENABLE Configures timeout (in us) to wait for free space in trace buffer. Set to -1 to wait forever and avoid lost events.
CONFIG_APPTRACE_SV_EVT_OVERFLOW_ENABLE Trace Buffer Overflow Event Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing > CONFIG_APPTRACE_SV_ENABLE Enables oTrace Buffer Overflowpevent.
CONFIG_APPTRACE_SV_EVT_ISR_ENTER_ENABLE ISR Enter Event Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing > CONFIG_APPTRACE_SV_ENABLE Enables oISR Enterpevent.
CONFIG_APPTRACE_SV_EVT_ISR_EXIT_ENABLE ISR Exit Event Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing > CONFIG_APPTRACE_SV_ENABLE Enables oISR Exitpevent.
CONFIG_APPTRACE_SV_EVT_ISR_TO_SCHED_ENABLE ISR Exit to Scheduler Event Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing > CONFIG_APPTRACE_SV_ENABLE Enables oISR to Schedulerpevent.
CONFIG_APPTRACE_SV_EVT_TASK_START_EXEC_ENABLE Task Start Execution Event Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing > CONFIG_APPTRACE_SV_ENABLE Enables oTask Start Executionpevent.

Espressif Systems

1388

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_APPTRACE_SV_EVT_TASK_STOP_EXEC_ENABLE Task Stop Execution Event Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing > CONFIG_APPTRACE_SV_ENABLE Enables oTask Stop Executionpevent.
CONFIG_APPTRACE_SV_EVT_TASK_START_READY_ENABLE Task Start Ready State Event Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing > CONFIG_APPTRACE_SV_ENABLE Enables oTask Start Ready Statepevent.
CONFIG_APPTRACE_SV_EVT_TASK_STOP_READY_ENABLE Task Stop Ready State Event Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing > CONFIG_APPTRACE_SV_ENABLE Enables oTask Stop Ready Statepevent.
CONFIG_APPTRACE_SV_EVT_TASK_CREATE_ENABLE Task Create Event Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing > CONFIG_APPTRACE_SV_ENABLE Enables oTask Createpevent.
CONFIG_APPTRACE_SV_EVT_TASK_TERMINATE_ENABLE Task Terminate Event Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing > CONFIG_APPTRACE_SV_ENABLE Enables oTask Terminatepevent.
CONFIG_APPTRACE_SV_EVT_IDLE_ENABLE System Idle Event Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing > CONFIG_APPTRACE_SV_ENABLE Enables oSystem Idlepevent.
CONFIG_APPTRACE_SV_EVT_TIMER_ENTER_ENABLE Timer Enter Event Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing > CONFIG_APPTRACE_SV_ENABLE Enables oTimer Enterpevent.

Espressif Systems

1389

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_APPTRACE_SV_EVT_TIMER_EXIT_ENABLE Timer Exit Event Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing > CONFIG_APPTRACE_SV_ENABLE Enables oTimer Exitpevent.
CONFIG_APPTRACE_GCOV_ENABLE GCOV to Host Enable Found in: Component config > Application Level Tracing Enables support for GCOV data transfer to host.
ESP-ASIO Contains: · CONFIG_ASIO_SSL_SUPPORT
CONFIG_ASIO_SSL_SUPPORT Enable SSL/TLS support of ASIO Found in: Component config > ESP-ASIO Enable support for basic SSL/TLS features, available for mbedTLS/OpenSSL as well as wolfSSL TLS library. Default value: · No (disabled)
CONFIG_ASIO_SSL_LIBRARY_CHOICE Choose SSL/TLS library for ESP-TLS (See help for more Info) Found in: Component config > ESP-ASIO > CONFIG_ASIO_SSL_SUPPORT The ASIO support multiple backend TLS libraries. Currently the mbedTLS with a thin ESP-OpenSSL port layer (default choice) and WolfSSL are supported. Different TLS libraries may support different features and have different resource usage. Consult the ESP-TLS documentation in ESP-IDF Programming guide for more details. Available options: · esp-openssl (ASIO_USE_ESP_OPENSSL) · wolfSSL (License info in wolfSSL directory README) (ASIO_USE_ESP_WOLFSSL)
CONFIG_ASIO_SSL_BIO_SIZE Size of BIO object Found in: Component config > ESP-ASIO > CONFIG_ASIO_SSL_SUPPORT Size in bytes of SSL-BIO implementation. Reducing the BIO size saves more RAM, but may slow down input output operations due to fragmentation. Default value: · 1024 if CONFIG_ASIO_SSL_SUPPORT

Espressif Systems

1390

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Bluetooth Contains:
· Bluedroid Options · CONFIG_BT_ENABLED · NimBLE Options
CONFIG_BT_ENABLED
Bluetooth
Found in: Component config > Bluetooth
Select this option to enable Bluetooth and show the submenu with Bluetooth configuration choices.
Bluetooth controller Contains:
· CONFIG_BT_CTRL_BLE_ADV_REPORT_FLOW_CTRL_SUPP · CONFIG_BT_CTRL_DFT_TX_POWER_LEVEL · CONFIG_BT_CTRL_BLE_MAX_ACT · CONFIG_BT_CTRL_BLE_SCAN_DUPL · CONFIG_BT_CTRL_BLE_STATIC_ACL_TX_BUF_NB · CONFIG_BT_CTRL_HW_CCA_VAL · CONFIG_BT_CTRL_COEX_PHY_CODED_TX_RX_TLIM · CONFIG_BT_CTRL_CE_LENGTH_TYPE · CONFIG_BT_CTRL_RX_ANTENNA_INDEX · CONFIG_BT_CTRL_TX_ANTENNA_INDEX · CONFIG_BT_CTRL_AGC_RECORRECT_EN · CONFIG_BT_CTRL_HCI_MODE_CHOICE · CONFIG_BT_CTRL_HW_CCA · MODEM SLEEP Options · CONFIG_BT_CTRL_PINNED_TO_CORE_CHOICE · CONFIG_BT_CTRL_ADV_DUP_FILT_MAX
CONFIG_BT_CTRL_BLE_MAX_ACT
BLE Max Instances
Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller
BLE maximum instances of bluetooth controller.
Range: · from 1 to 10 if CONFIG_BT_ENABLED
Default value: · 10 if CONFIG_BT_ENABLED
CONFIG_BT_CTRL_BLE_STATIC_ACL_TX_BUF_NB
BLE static ACL TX buffer numbers
Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller
BLE ACL buffer have two methods to be allocated. One is persistent allocating (alloate when controller initialise, never free until controller de-initialise) another is dynamically allocating (allocate before TX and free after TX).
Range: · from 0 to 12 if CONFIG_BT_ENABLED
Default value: · 0 if CONFIG_BT_ENABLED

Espressif Systems

1391

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_BT_CTRL_PINNED_TO_CORE_CHOICE The cpu core which bluetooth controller run Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller Specify the cpu core to run bluetooth controller. Can not specify no-affinity. Available options: · Core 0 (PRO CPU) (BT_CTRL_PINNED_TO_CORE_0) · Core 1 (APP CPU) (BT_CTRL_PINNED_TO_CORE_1)
CONFIG_BT_CTRL_HCI_MODE_CHOICE HCI mode Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller Specify HCI mode as VHCI or UART(H4) Available options: · VHCI (BT_CTRL_HCI_MODE_VHCI) Normal option. Mostly, choose this VHCI when bluetooth host run on ESP32S3, too. · UART(H4) (BT_CTRL_HCI_MODE_UART_H4) If use external bluetooth host which run on other hardware and use UART as the HCI interface, choose this option.
CONFIG_BT_CTRL_ADV_DUP_FILT_MAX The maxinum number of 5.0 extend duplicate scan filter Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller The maxinum number of suplicate scan filter Range: · from 1 to 500 if CONFIG_BT_ENABLED Default value: · 30 if CONFIG_BT_ENABLED
CONFIG_BT_CTRL_HW_CCA HW CCA check enable Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller It enables HW CCA feature in controller Default value: · No (disabled) if CONFIG_BT_ENABLED
CONFIG_BT_CTRL_HW_CCA_VAL CCA threshold value Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller It is the threshold value of HW CCA, if the value is 30, it means CCA threshold is -30 dBm. Range: · from 20 to 60 if CONFIG_BT_ENABLED Default value: · 20 if CONFIG_BT_ENABLED

Espressif Systems

1392

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_BT_CTRL_CE_LENGTH_TYPE
Connection event length determination method
Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller
Specify connection event length determination
Available options: · ORIGINAL (BT_CTRL_CE_LENGTH_TYPE_ORIG) · Use CE parameter for HCI command (BT_CTRL_CE_LENGTH_TYPE_CE) · Use Espressif self-defined method (BT_CTRL_CE_LENGTH_TYPE_SD)

CONFIG_BT_CTRL_TX_ANTENNA_INDEX
default Tx anntena used
Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller
Specify default Tx antenna used for bluetooth
Available options: · Antenna 0 (BT_CTRL_TX_ANTENNA_INDEX_0) · Antenna 1 (BT_CTRL_TX_ANTENNA_INDEX_1)

CONFIG_BT_CTRL_RX_ANTENNA_INDEX
default Rx anntena used
Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller
Specify default Rx antenna used for bluetooth
Available options: · Antenna 0 (BT_CTRL_RX_ANTENNA_INDEX_0) · Antenna 1 (BT_CTRL_RX_ANTENNA_INDEX_1)

CONFIG_BT_CTRL_DFT_TX_POWER_LEVEL

BLE default Tx power level

Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller

Specify default Tx power level

Available options:

· -27dBm (BT_CTRL_DFT_TX_POWER_LEVEL_N27)

· -24dBm (BT_CTRL_DFT_TX_POWER_LEVEL_N24)

· -21dBm (BT_CTRL_DFT_TX_POWER_LEVEL_N21)

· -18dBm (BT_CTRL_DFT_TX_POWER_LEVEL_N18)

· -15dBm (BT_CTRL_DFT_TX_POWER_LEVEL_N15)

· -12dBm (BT_CTRL_DFT_TX_POWER_LEVEL_N12)

·

-9dBm

(BT_CTRL_DFT_TX_POWER_LEVEL_N9)

·

-6dBm

(BT_CTRL_DFT_TX_POWER_LEVEL_N6)

·

-3dBm

(BT_CTRL_DFT_TX_POWER_LEVEL_N3)

· 0dBm (BT_CTRL_DFT_TX_POWER_LEVEL_N0)

·

+3dBm

(BT_CTRL_DFT_TX_POWER_LEVEL_P3)

·

+6dBm

(BT_CTRL_DFT_TX_POWER_LEVEL_P6)

·

+9dBm

(BT_CTRL_DFT_TX_POWER_LEVEL_P9)

· +12dBm (BT_CTRL_DFT_TX_POWER_LEVEL_P12)

· +15dBm (BT_CTRL_DFT_TX_POWER_LEVEL_P15)

· +18dBm (BT_CTRL_DFT_TX_POWER_LEVEL_P18)

Espressif Systems

1393

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_BT_CTRL_BLE_ADV_REPORT_FLOW_CTRL_SUPP
BLE adv report flow control supported
Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller
The function is mainly used to enable flow control for advertising reports. When it is enabled, advertising reports will be discarded by the controller if the number of unprocessed advertising reports exceeds the size of BLE adv report flow control.
Default value: · Yes (enabled) if CONFIG_BT_ENABLED
CONFIG_BT_CTRL_BLE_ADV_REPORT_FLOW_CTRL_NUM
BLE adv report flow control number
Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller > CONFIG_BT_CTRL_BLE_ADV_REPORT_FLOW_CTRL_SUPP
The number of unprocessed advertising report that bluetooth host can save.If you set BT_CTRL_BLE_ADV_REPORT_FLOW_CTRL_NUM to a small value, this may cause adv packets lost. If you set BT_CTRL_BLE_ADV_REPORT_FLOW_CTRL_NUM to a large value, bluetooth host may cache a lot of adv packets and this may cause system memory run out. For example, if you set it to 50, the maximum memory consumed by host is 35 * 50 bytes. Please set BT_CTRL_BLE_ADV_REPORT_FLOW_CTRL_NUM according to your system free memory and handle adv packets as fast as possible, otherwise it will cause adv packets lost.
Range: · from 50 to 1000 if CONFIG_BT_CTRL_BLE_ADV_REPORT_FLOW_CTRL_SUPP && CONFIG_BT_ENABLED
Default value: · 100 if CONFIG_BT_CTRL_BLE_ADV_REPORT_FLOW_CTRL_SUPP && CONFIG_BT_ENABLED

CONFIG_BT_CTRL_BLE_ADV_REPORT_DISCARD_THRSHOLD
BLE adv lost event threshold value
Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller > CONFIG_BT_CTRL_BLE_ADV_REPORT_FLOW_CTRL_SUPP
When adv report flow control is enabled, The ADV lost event will be generated when the number of ADV packets lost in the controller reaches this threshold. It is better to set a larger value. If you set BT_CTRL_BLE_ADV_REPORT_DISCARD_THRSHOLD to a small value or printf every adv lost event, it may cause adv packets lost more.
Range: · from 1 to 1000 if CONFIG_BT_CTRL_BLE_ADV_REPORT_FLOW_CTRL_SUPP && CONFIG_BT_ENABLED
Default value: · 20 if CONFIG_BT_CTRL_BLE_ADV_REPORT_FLOW_CTRL_SUPP && CONFIG_BT_ENABLED
CONFIG_BT_CTRL_BLE_SCAN_DUPL
BLE Scan Duplicate Options
Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller
This select enables parameters setting of BLE scan duplicate.
Default value: · Yes (enabled) if CONFIG_BT_ENABLED

Espressif Systems

1394

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_BT_CTRL_SCAN_DUPL_TYPE
Scan Duplicate Type
Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller > CONFIG_BT_CTRL_BLE_SCAN_DUPL
Scan duplicate have three ways. one isoScan Duplicate By Device Addressp, This way is to use advertiser address filtering. The adv packet of the same address is only allowed to be reported once. Another way isoScan Duplicate By Device Address And Advertising Datap. This way is to use advertising data and device address filtering. All different adv packets with the same address are allowed to be reported. The last way is oScan Duplicate By Advertising Datap. This way is to use advertising data filtering. All same advertising data only allow to be reported once even though they are from different devices.
Available options: · Scan Duplicate By Device Address (BT_CTRL_SCAN_DUPL_TYPE_DEVICE) This way is to use advertiser address filtering. The adv packet of the same address is only allowed to be reported once · Scan Duplicate By Advertising Data (BT_CTRL_SCAN_DUPL_TYPE_DATA) This way is to use advertising data filtering. All same advertising data only allow to be reported once even though they are from different devices. · Scan Duplicate By Device Address And Advertising Data (BT_CTRL_SCAN_DUPL_TYPE_DATA_DEVICE) This way is to use advertising data and device address filtering. All different adv packets with the same address are allowed to be reported.
CONFIG_BT_CTRL_SCAN_DUPL_CACHE_SIZE
Maximum number of devices in scan duplicate filter
Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller > CONFIG_BT_CTRL_BLE_SCAN_DUPL
Maximum number of devices which can be recorded in scan duplicate filter. When the maximum amount of device in the filter is reached, the cache will be refreshed.
Range: · from 10 to 1000 if CONFIG_BT_CTRL_BLE_SCAN_DUPL && CONFIG_BT_ENABLED
Default value: · 100 if CONFIG_BT_CTRL_BLE_SCAN_DUPL && CONFIG_BT_ENABLED

CONFIG_BT_CTRL_BLE_MESH_SCAN_DUPL_EN Special duplicate scan mechanism for BLE Mesh scan Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller > CONFIG_BT_CTRL_BLE_SCAN_DUPL This enables the BLE scan duplicate for special BLE Mesh scan. Default value: · No (disabled) if CONFIG_BT_CTRL_BLE_SCAN_DUPL && CONFIG_BT_ENABLED
CONFIG_BT_CTRL_MESH_DUPL_SCAN_CACHE_SIZE Maximum number of Mesh adv packets in scan duplicate filter Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller > CONFIG_BT_CTRL_BLE_SCAN_DUPL > CONFIG_BT_CTRL_BLE_MESH_SCAN_DUPL_EN Maximum number of adv packets which can be recorded in duplicate scan cache for BLE Mesh. When the maximum amount of device in the filter is reached, the cache will be refreshed. Range:

Espressif Systems

1395

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· from 10 to 1000 if CONFIG_BT_CTRL_BLE_MESH_SCAN_DUPL_EN && CONFIG_BT_ENABLED
Default value: · 100 if CONFIG_BT_CTRL_BLE_MESH_SCAN_DUPL_EN && CONFIG_BT_ENABLED
CONFIG_BT_CTRL_COEX_PHY_CODED_TX_RX_TLIM Coexistence: limit on MAX Tx/Rx time for coded-PHY connection Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller When using PHY-Coded in BLE connection, limitation on max tx/rx time can be applied to better avoid dramatic performance deterioration of Wi-Fi. Available options: · Force Enable (BT_CTRL_COEX_PHY_CODED_TX_RX_TLIM_EN) Always enable the limitation on max tx/rx time for Coded-PHY connection · Force Disable (BT_CTRL_COEX_PHY_CODED_TX_RX_TLIM_DIS) Disable the limitation on max tx/rx time for Coded-PHY connection
MODEM SLEEP Options Contains: · CONFIG_BT_CTRL_MODEM_SLEEP
CONFIG_BT_CTRL_MODEM_SLEEP Bluetooth modem sleep Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller > MODEM SLEEP Options Enable/disable bluetooth controller low power mode. Modem sleep is not supported to be used with UART HCI. Default value: · No (disabled) if BT_CTRL_HCI_MODE_UART_H4 && CONFIG_BT_ENABLED
CONFIG_BT_CTRL_MODEM_SLEEP_MODE_1 Bluetooth Modem sleep Mode 1 Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller > MODEM SLEEP Options > CONFIG_BT_CTRL_MODEM_SLEEP Mode 1 is the currently supported sleep mode. In this mode, bluetooth controller sleeps between and BLE events. A low power clock is used to maintain bluetooth reference clock. Default value: · Yes (enabled) if CONFIG_BT_CTRL_MODEM_SLEEP && CONFIG_BT_ENABLED
CONFIG_BT_CTRL_LOW_POWER_CLOCK Bluetooth low power clock Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller > MODEM SLEEP Options > CONFIG_BT_CTRL_MODEM_SLEEP > CONFIG_BT_CTRL_MODEM_SLEEP_MODE_1 Select the low power clock source for bluetooth controller Available options:

Espressif Systems

1396

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· Main crystal (BT_CTRL_LPCLK_SEL_MAIN_XTAL) Main crystal can be used as low power clock for bluetooth modem sleep. If this option is selected, bluetooth modem sleep can work under Dynamic Frequency Scaling(DFS) enabled, but cannot work when light sleep is enabled. Main crystal has a relatively better performance than other bluetooth low power clock sources.
· External 32kHz crystal (BT_CTRL_LPCLK_SEL_EXT_32K_XTAL) External 32kHz crystal has a nominal frequency of 32.768kHz and provides good frequency stability. If used as Bluetooth low power clock, External 32kHz can support Bluetooth modem sleep to be used with both DFS and light sleep.
· Internal 150kHz RC oscillator (BT_CTRL_LPCLK_SEL_RTC_SLOW) Internal 150kHz RC oscillator. The accuracy of this clock is a lot larger than 500ppm which is required in Bluetooth communication, so donnt select this option in scenarios such as BLE connection state.

CONFIG_BT_CTRL_AGC_RECORRECT_EN Enable HW AGC recorrect Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller Enable uncoded phy AGC recorrect Default value: · No (disabled) if CONFIG_BT_ENABLED

CONFIG_BT_CTRL_CODED_AGC_RECORRECT_EN
Enable coded phy AGC recorrect
Found in: Component config > Bluetooth > CONFIG_BT_ENABLED > Bluetooth controller > CONFIG_BT_CTRL_AGC_RECORRECT_EN
Enable coded phy AGC recorrect
Default value: · No (disabled) if CONFIG_BT_CTRL_AGC_RECORRECT_EN && CONFIG_BT_ENABLED

CONFIG_BT_HOST
Bluetooth Host
Found in: Component config > Bluetooth > CONFIG_BT_ENABLED
This helps to choose Bluetooth host stack
Available options: · Bluedroid - Dual-mode (BT_BLUEDROID_ENABLED) This option is recommended for classic Bluetooth or for dual-mode usecases · NimBLE - BLE only (BT_NIMBLE_ENABLED) This option is recommended for BLE only usecases to save on memory · Controller Only (BT_CONTROLLER_ONLY) This option is recommended when you want to communicate directly with the controller (without any host) or when you are using any other host stack not supported by Espressif (not mentioned here).

Bluedroid Options Contains:
· CONFIG_BT_BLE_HOST_QUEUE_CONG_CHECK · CONFIG_BT_BLUEDROID_MEM_DEBUG · CONFIG_BT_BTU_TASK_STACK_SIZE · CONFIG_BT_BTC_TASK_STACK_SIZE · CONFIG_BT_BLE_ENABLED

Espressif Systems

1397

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· BT DEBUG LOG LEVEL · CONFIG_BT_ACL_CONNECTIONS · CONFIG_BT_ALLOCATION_FROM_SPIRAM_FIRST · CONFIG_BT_STACK_NO_LOG · CONFIG_BT_BLE_42_FEATURES_SUPPORTED · CONFIG_BT_BLE_50_FEATURES_SUPPORTED · CONFIG_BT_MULTI_CONNECTION_ENBALE · CONFIG_BT_MAX_DEVICE_NAME_LEN · CONFIG_BT_BLE_ACT_SCAN_REP_ADV_SCAN · CONFIG_BT_BLUEDROID_PINNED_TO_CORE_CHOICE · CONFIG_BT_BLE_ESTAB_LINK_CONN_TOUT · CONFIG_BT_BLE_RPA_SUPPORTED · CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY
CONFIG_BT_BTC_TASK_STACK_SIZE Bluetooth event (callback to application) task stack size Found in: Component config > Bluetooth > Bluedroid Options This select btc task stack size Default value: · 3072 if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_BLUEDROID_PINNED_TO_CORE_CHOICE The cpu core which Bluedroid run Found in: Component config > Bluetooth > Bluedroid Options Which the cpu core to run Bluedroid. Can choose core0 and core1. Can not specify no-affinity. Available options: · Core 0 (PRO CPU) (BT_BLUEDROID_PINNED_TO_CORE_0) · Core 1 (APP CPU) (BT_BLUEDROID_PINNED_TO_CORE_1)
CONFIG_BT_BTU_TASK_STACK_SIZE Bluetooth Bluedroid Host Stack task stack size Found in: Component config > Bluetooth > Bluedroid Options This select btu task stack size Default value: · 4096 if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_BLUEDROID_MEM_DEBUG Bluedroid memory debug Found in: Component config > Bluetooth > Bluedroid Options Bluedroid memory debug Default value: · No (disabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED

Espressif Systems

1398

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_BT_BLE_ENABLED Bluetooth Low Energy Found in: Component config > Bluetooth > Bluedroid Options This enables Bluetooth Low Energy Default value: · Yes (enabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_GATTS_ENABLE Include GATT server module(GATTS) Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED This option can be disabled when the app work only on gatt client mode Default value: · Yes (enabled) if CONFIG_BT_BLE_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_GATTS_PPCP_CHAR_GAP Enable Peripheral Preferred Connection Parameters characteristic in GAP service Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED > CONFIG_BT_GATTS_ENABLE This enables oPeripheral Preferred Connection Parameterspcharacteristic (UUID: 0x2A04) in GAP service that has connection parameters like min/max connection interval, slave latency and supervision timeout multiplier Default value: · No (disabled) if CONFIG_BT_GATTS_ENABLE && BT_BLUEDROID_ENABLED
CONFIG_BT_BLE_BLUFI_ENABLE Include blufi function Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED > CONFIG_BT_GATTS_ENABLE This option can be close when the app does not require blufi function. Default value: · No (disabled) if CONFIG_BT_GATTS_ENABLE && BT_BLUEDROID_ENABLED
CONFIG_BT_GATT_MAX_SR_PROFILES Max GATT Server Profiles Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED > CONFIG_BT_GATTS_ENABLE Maximum GATT Server Profiles Count Range: · from 1 to 32 if CONFIG_BT_GATTS_ENABLE && BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED Default value: · 8 if CONFIG_BT_GATTS_ENABLE && BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED

Espressif Systems

1399

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_BT_GATTS_SEND_SERVICE_CHANGE_MODE

GATTS Service Change Mode

Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED > CONFIG_BT_GATTS_ENABLE

Service change indication mode for GATT Server.

Available options:

· GATTS manually send service change indication (BT_GATTS_SEND_SERVICE_CHANGE_MANUAL)

Manually

send

service

change

indication

through

API

esp_ble_gatts_send_service_change_indication()

· GATTS

automatically

send

service

change

indication

(BT_GATTS_SEND_SERVICE_CHANGE_AUTO)

Let Bluedroid handle the service change indication internally

CONFIG_BT_GATTC_ENABLE Include GATT client module(GATTC) Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED This option can be close when the app work only on gatt server mode Default value: · Yes (enabled) if CONFIG_BT_BLE_ENABLED && BT_BLUEDROID_ENABLED

CONFIG_BT_GATTC_CACHE_NVS_FLASH
Save gattc cache data to nvs flash
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED > CONFIG_BT_GATTC_ENABLE
This select can save gattc cache data to nvs flash
Default value: · No (disabled) if CONFIG_BT_GATTC_ENABLE && BT_BLUEDROID_ENABLED

CONFIG_BT_GATTC_CONNECT_RETRY_COUNT
The number of attempts to reconnect if the connection establishment failed
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED > CONFIG_BT_GATTC_ENABLE
The number of attempts to reconnect if the connection establishment failed
Range: · from 0 to 7 if CONFIG_BT_GATTC_ENABLE && BT_BLUEDROID_ENABLED
Default value: · 3 if CONFIG_BT_GATTC_ENABLE && BT_BLUEDROID_ENABLED

CONFIG_BT_BLE_SMP_ENABLE Include BLE security module(SMP) Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED This option can be close when the app not used the ble security connect. Default value: · Yes (enabled) if CONFIG_BT_BLE_ENABLED && BT_BLUEDROID_ENABLED

Espressif Systems

1400

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_BT_SMP_SLAVE_CON_PARAMS_UPD_ENABLE
Slave enable connection parameters update during pairing
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED > CONFIG_BT_BLE_SMP_ENABLE
In order to reduce the pairing time, slave actively initiates connection parameters update during pairing.
Default value: · No (disabled) if CONFIG_BT_BLE_SMP_ENABLE && BT_BLUEDROID_ENABLED
CONFIG_BT_STACK_NO_LOG
Disable BT debug logs (minimize bin size)
Found in: Component config > Bluetooth > Bluedroid Options
This select can save the rodata code size
Default value: · No (disabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
BT DEBUG LOG LEVEL Contains:
· CONFIG_BT_LOG_A2D_TRACE_LEVEL · CONFIG_BT_LOG_APPL_TRACE_LEVEL · CONFIG_BT_LOG_AVCT_TRACE_LEVEL · CONFIG_BT_LOG_AVDT_TRACE_LEVEL · CONFIG_BT_LOG_AVRC_TRACE_LEVEL · CONFIG_BT_LOG_BLUFI_TRACE_LEVEL · CONFIG_BT_LOG_BNEP_TRACE_LEVEL · CONFIG_BT_LOG_BTC_TRACE_LEVEL · CONFIG_BT_LOG_BTIF_TRACE_LEVEL · CONFIG_BT_LOG_BTM_TRACE_LEVEL · CONFIG_BT_LOG_GAP_TRACE_LEVEL · CONFIG_BT_LOG_GATT_TRACE_LEVEL · CONFIG_BT_LOG_HCI_TRACE_LEVEL · CONFIG_BT_LOG_HID_TRACE_LEVEL · CONFIG_BT_LOG_L2CAP_TRACE_LEVEL · CONFIG_BT_LOG_MCA_TRACE_LEVEL · CONFIG_BT_LOG_OSI_TRACE_LEVEL · CONFIG_BT_LOG_PAN_TRACE_LEVEL · CONFIG_BT_LOG_RFCOMM_TRACE_LEVEL · CONFIG_BT_LOG_SDP_TRACE_LEVEL · CONFIG_BT_LOG_SMP_TRACE_LEVEL
CONFIG_BT_LOG_HCI_TRACE_LEVEL
HCI layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for HCI layer
Available options: · NONE (BT_LOG_HCI_TRACE_LEVEL_NONE) · ERROR (BT_LOG_HCI_TRACE_LEVEL_ERROR) · WARNING (BT_LOG_HCI_TRACE_LEVEL_WARNING) · API (BT_LOG_HCI_TRACE_LEVEL_API) · EVENT (BT_LOG_HCI_TRACE_LEVEL_EVENT) · DEBUG (BT_LOG_HCI_TRACE_LEVEL_DEBUG)

Espressif Systems

1401

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· VERBOSE (BT_LOG_HCI_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_BTM_TRACE_LEVEL
BTM layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for BTM layer
Available options: · NONE (BT_LOG_BTM_TRACE_LEVEL_NONE) · ERROR (BT_LOG_BTM_TRACE_LEVEL_ERROR) · WARNING (BT_LOG_BTM_TRACE_LEVEL_WARNING) · API (BT_LOG_BTM_TRACE_LEVEL_API) · EVENT (BT_LOG_BTM_TRACE_LEVEL_EVENT) · DEBUG (BT_LOG_BTM_TRACE_LEVEL_DEBUG) · VERBOSE (BT_LOG_BTM_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_L2CAP_TRACE_LEVEL
L2CAP layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for L2CAP layer
Available options: · NONE (BT_LOG_L2CAP_TRACE_LEVEL_NONE) · ERROR (BT_LOG_L2CAP_TRACE_LEVEL_ERROR) · WARNING (BT_LOG_L2CAP_TRACE_LEVEL_WARNING) · API (BT_LOG_L2CAP_TRACE_LEVEL_API) · EVENT (BT_LOG_L2CAP_TRACE_LEVEL_EVENT) · DEBUG (BT_LOG_L2CAP_TRACE_LEVEL_DEBUG) · VERBOSE (BT_LOG_L2CAP_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_RFCOMM_TRACE_LEVEL
RFCOMM layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for RFCOMM layer
Available options: · NONE (BT_LOG_RFCOMM_TRACE_LEVEL_NONE) · ERROR (BT_LOG_RFCOMM_TRACE_LEVEL_ERROR) · WARNING (BT_LOG_RFCOMM_TRACE_LEVEL_WARNING) · API (BT_LOG_RFCOMM_TRACE_LEVEL_API) · EVENT (BT_LOG_RFCOMM_TRACE_LEVEL_EVENT) · DEBUG (BT_LOG_RFCOMM_TRACE_LEVEL_DEBUG) · VERBOSE (BT_LOG_RFCOMM_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_SDP_TRACE_LEVEL
SDP layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for SDP layer
Available options: · NONE (BT_LOG_SDP_TRACE_LEVEL_NONE)

Espressif Systems

1402

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· ERROR (BT_LOG_SDP_TRACE_LEVEL_ERROR) · WARNING (BT_LOG_SDP_TRACE_LEVEL_WARNING) · API (BT_LOG_SDP_TRACE_LEVEL_API) · EVENT (BT_LOG_SDP_TRACE_LEVEL_EVENT) · DEBUG (BT_LOG_SDP_TRACE_LEVEL_DEBUG) · VERBOSE (BT_LOG_SDP_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_GAP_TRACE_LEVEL
GAP layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for GAP layer
Available options: · NONE (BT_LOG_GAP_TRACE_LEVEL_NONE) · ERROR (BT_LOG_GAP_TRACE_LEVEL_ERROR) · WARNING (BT_LOG_GAP_TRACE_LEVEL_WARNING) · API (BT_LOG_GAP_TRACE_LEVEL_API) · EVENT (BT_LOG_GAP_TRACE_LEVEL_EVENT) · DEBUG (BT_LOG_GAP_TRACE_LEVEL_DEBUG) · VERBOSE (BT_LOG_GAP_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_BNEP_TRACE_LEVEL
BNEP layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for BNEP layer
Available options: · NONE (BT_LOG_BNEP_TRACE_LEVEL_NONE) · ERROR (BT_LOG_BNEP_TRACE_LEVEL_ERROR) · WARNING (BT_LOG_BNEP_TRACE_LEVEL_WARNING) · API (BT_LOG_BNEP_TRACE_LEVEL_API) · EVENT (BT_LOG_BNEP_TRACE_LEVEL_EVENT) · DEBUG (BT_LOG_BNEP_TRACE_LEVEL_DEBUG) · VERBOSE (BT_LOG_BNEP_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_PAN_TRACE_LEVEL
PAN layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for PAN layer
Available options: · NONE (BT_LOG_PAN_TRACE_LEVEL_NONE) · ERROR (BT_LOG_PAN_TRACE_LEVEL_ERROR) · WARNING (BT_LOG_PAN_TRACE_LEVEL_WARNING) · API (BT_LOG_PAN_TRACE_LEVEL_API) · EVENT (BT_LOG_PAN_TRACE_LEVEL_EVENT) · DEBUG (BT_LOG_PAN_TRACE_LEVEL_DEBUG) · VERBOSE (BT_LOG_PAN_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_A2D_TRACE_LEVEL

Espressif Systems

1403

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

A2D layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for A2D layer
Available options: · NONE (BT_LOG_A2D_TRACE_LEVEL_NONE) · ERROR (BT_LOG_A2D_TRACE_LEVEL_ERROR) · WARNING (BT_LOG_A2D_TRACE_LEVEL_WARNING) · API (BT_LOG_A2D_TRACE_LEVEL_API) · EVENT (BT_LOG_A2D_TRACE_LEVEL_EVENT) · DEBUG (BT_LOG_A2D_TRACE_LEVEL_DEBUG) · VERBOSE (BT_LOG_A2D_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_AVDT_TRACE_LEVEL
AVDT layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for AVDT layer
Available options: · NONE (BT_LOG_AVDT_TRACE_LEVEL_NONE) · ERROR (BT_LOG_AVDT_TRACE_LEVEL_ERROR) · WARNING (BT_LOG_AVDT_TRACE_LEVEL_WARNING) · API (BT_LOG_AVDT_TRACE_LEVEL_API) · EVENT (BT_LOG_AVDT_TRACE_LEVEL_EVENT) · DEBUG (BT_LOG_AVDT_TRACE_LEVEL_DEBUG) · VERBOSE (BT_LOG_AVDT_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_AVCT_TRACE_LEVEL
AVCT layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for AVCT layer
Available options: · NONE (BT_LOG_AVCT_TRACE_LEVEL_NONE) · ERROR (BT_LOG_AVCT_TRACE_LEVEL_ERROR) · WARNING (BT_LOG_AVCT_TRACE_LEVEL_WARNING) · API (BT_LOG_AVCT_TRACE_LEVEL_API) · EVENT (BT_LOG_AVCT_TRACE_LEVEL_EVENT) · DEBUG (BT_LOG_AVCT_TRACE_LEVEL_DEBUG) · VERBOSE (BT_LOG_AVCT_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_AVRC_TRACE_LEVEL
AVRC layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for AVRC layer
Available options: · NONE (BT_LOG_AVRC_TRACE_LEVEL_NONE) · ERROR (BT_LOG_AVRC_TRACE_LEVEL_ERROR) · WARNING (BT_LOG_AVRC_TRACE_LEVEL_WARNING) · API (BT_LOG_AVRC_TRACE_LEVEL_API) · EVENT (BT_LOG_AVRC_TRACE_LEVEL_EVENT)

Espressif Systems

1404

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· DEBUG (BT_LOG_AVRC_TRACE_LEVEL_DEBUG) · VERBOSE (BT_LOG_AVRC_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_MCA_TRACE_LEVEL
MCA layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for MCA layer
Available options: · NONE (BT_LOG_MCA_TRACE_LEVEL_NONE) · ERROR (BT_LOG_MCA_TRACE_LEVEL_ERROR) · WARNING (BT_LOG_MCA_TRACE_LEVEL_WARNING) · API (BT_LOG_MCA_TRACE_LEVEL_API) · EVENT (BT_LOG_MCA_TRACE_LEVEL_EVENT) · DEBUG (BT_LOG_MCA_TRACE_LEVEL_DEBUG) · VERBOSE (BT_LOG_MCA_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_HID_TRACE_LEVEL
HID layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for HID layer
Available options: · NONE (BT_LOG_HID_TRACE_LEVEL_NONE) · ERROR (BT_LOG_HID_TRACE_LEVEL_ERROR) · WARNING (BT_LOG_HID_TRACE_LEVEL_WARNING) · API (BT_LOG_HID_TRACE_LEVEL_API) · EVENT (BT_LOG_HID_TRACE_LEVEL_EVENT) · DEBUG (BT_LOG_HID_TRACE_LEVEL_DEBUG) · VERBOSE (BT_LOG_HID_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_APPL_TRACE_LEVEL
APPL layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for APPL layer
Available options: · NONE (BT_LOG_APPL_TRACE_LEVEL_NONE) · ERROR (BT_LOG_APPL_TRACE_LEVEL_ERROR) · WARNING (BT_LOG_APPL_TRACE_LEVEL_WARNING) · API (BT_LOG_APPL_TRACE_LEVEL_API) · EVENT (BT_LOG_APPL_TRACE_LEVEL_EVENT) · DEBUG (BT_LOG_APPL_TRACE_LEVEL_DEBUG) · VERBOSE (BT_LOG_APPL_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_GATT_TRACE_LEVEL
GATT layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for GATT layer
Available options:

Espressif Systems

1405

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· NONE (BT_LOG_GATT_TRACE_LEVEL_NONE) · ERROR (BT_LOG_GATT_TRACE_LEVEL_ERROR) · WARNING (BT_LOG_GATT_TRACE_LEVEL_WARNING) · API (BT_LOG_GATT_TRACE_LEVEL_API) · EVENT (BT_LOG_GATT_TRACE_LEVEL_EVENT) · DEBUG (BT_LOG_GATT_TRACE_LEVEL_DEBUG) · VERBOSE (BT_LOG_GATT_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_SMP_TRACE_LEVEL
SMP layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for SMP layer
Available options: · NONE (BT_LOG_SMP_TRACE_LEVEL_NONE) · ERROR (BT_LOG_SMP_TRACE_LEVEL_ERROR) · WARNING (BT_LOG_SMP_TRACE_LEVEL_WARNING) · API (BT_LOG_SMP_TRACE_LEVEL_API) · EVENT (BT_LOG_SMP_TRACE_LEVEL_EVENT) · DEBUG (BT_LOG_SMP_TRACE_LEVEL_DEBUG) · VERBOSE (BT_LOG_SMP_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_BTIF_TRACE_LEVEL
BTIF layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for BTIF layer
Available options: · NONE (BT_LOG_BTIF_TRACE_LEVEL_NONE) · ERROR (BT_LOG_BTIF_TRACE_LEVEL_ERROR) · WARNING (BT_LOG_BTIF_TRACE_LEVEL_WARNING) · API (BT_LOG_BTIF_TRACE_LEVEL_API) · EVENT (BT_LOG_BTIF_TRACE_LEVEL_EVENT) · DEBUG (BT_LOG_BTIF_TRACE_LEVEL_DEBUG) · VERBOSE (BT_LOG_BTIF_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_BTC_TRACE_LEVEL
BTC layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for BTC layer
Available options: · NONE (BT_LOG_BTC_TRACE_LEVEL_NONE) · ERROR (BT_LOG_BTC_TRACE_LEVEL_ERROR) · WARNING (BT_LOG_BTC_TRACE_LEVEL_WARNING) · API (BT_LOG_BTC_TRACE_LEVEL_API) · EVENT (BT_LOG_BTC_TRACE_LEVEL_EVENT) · DEBUG (BT_LOG_BTC_TRACE_LEVEL_DEBUG) · VERBOSE (BT_LOG_BTC_TRACE_LEVEL_VERBOSE)

Espressif Systems

1406

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_BT_LOG_OSI_TRACE_LEVEL
OSI layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for OSI layer
Available options: · NONE (BT_LOG_OSI_TRACE_LEVEL_NONE) · ERROR (BT_LOG_OSI_TRACE_LEVEL_ERROR) · WARNING (BT_LOG_OSI_TRACE_LEVEL_WARNING) · API (BT_LOG_OSI_TRACE_LEVEL_API) · EVENT (BT_LOG_OSI_TRACE_LEVEL_EVENT) · DEBUG (BT_LOG_OSI_TRACE_LEVEL_DEBUG) · VERBOSE (BT_LOG_OSI_TRACE_LEVEL_VERBOSE)

CONFIG_BT_LOG_BLUFI_TRACE_LEVEL
BLUFI layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for BLUFI layer
Available options: · NONE (BT_LOG_BLUFI_TRACE_LEVEL_NONE) · ERROR (BT_LOG_BLUFI_TRACE_LEVEL_ERROR) · WARNING (BT_LOG_BLUFI_TRACE_LEVEL_WARNING) · API (BT_LOG_BLUFI_TRACE_LEVEL_API) · EVENT (BT_LOG_BLUFI_TRACE_LEVEL_EVENT) · DEBUG (BT_LOG_BLUFI_TRACE_LEVEL_DEBUG) · VERBOSE (BT_LOG_BLUFI_TRACE_LEVEL_VERBOSE)

CONFIG_BT_ACL_CONNECTIONS
BT/BLE MAX ACL CONNECTIONS(1~7)
Found in: Component config > Bluetooth > Bluedroid Options
Maximum BT/BLE connection count
Range: · from 1 to 7 if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
Default value: · 4 if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED

CONFIG_BT_MULTI_CONNECTION_ENBALE Enable BLE multi-conections Found in: Component config > Bluetooth > Bluedroid Options Enable this option if there are multiple connections Default value: · Yes (enabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED

CONFIG_BT_ALLOCATION_FROM_SPIRAM_FIRST BT/BLE will first malloc the memory from the PSRAM Found in: Component config > Bluetooth > Bluedroid Options This select can save the internal RAM if there have the PSRAM

Espressif Systems

1407

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Default value: · No (disabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY Use dynamic memory allocation in BT/BLE stack Found in: Component config > Bluetooth > Bluedroid Options This select can make the allocation of memory will become more flexible Default value: · No (disabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_BLE_HOST_QUEUE_CONG_CHECK BLE queue congestion check Found in: Component config > Bluetooth > Bluedroid Options When scanning and scan duplicate is not enabled, if there are a lot of adv packets around or application layer handling adv packets is slow, it will cause the controller memory to run out. if enabled, adv packets will be lost when host queue is congested. Default value: · No (disabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_BLE_ACT_SCAN_REP_ADV_SCAN Report adv data and scan response individually when BLE active scan Found in: Component config > Bluetooth > Bluedroid Options Originally, when doing BLE active scan, Bluedroid will not report adv to application layer until receive scan response. This option is used to disable the behavior. When enable this option, Bluedroid will report adv data or scan response to application layer immediately. # Memory reserved at start of DRAM for Bluetooth stack Default value: · No (disabled) if BT_BLUEDROID_ENABLED && (BTDM_CTRL_MODE_BTDM || BTDM_CTRL_MODE_BLE_ONLY) && BT_BLUEDROID_ENABLED
CONFIG_BT_BLE_ESTAB_LINK_CONN_TOUT Timeout of BLE connection establishment Found in: Component config > Bluetooth > Bluedroid Options Bluetooth Connection establishment maximum time, if connection time exceeds this value, the connection establishment fails, ESP_GATTC_OPEN_EVT or ESP_GATTS_OPEN_EVT is triggered. Range: · from 1 to 60 if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED Default value: · 30 if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_MAX_DEVICE_NAME_LEN length of bluetooth device name Found in: Component config > Bluetooth > Bluedroid Options

Espressif Systems

1408

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Bluetooth Device name length shall be no larger than 248 octets, If the broadcast data cannot contain the complete device name, then only the shortname will be displayed, the rest parts that cannt fit in will be truncated.
Range: · from 32 to 248 if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
Default value: · 32 if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED

CONFIG_BT_BLE_RPA_SUPPORTED
Update RPA to Controller
Found in: Component config > Bluetooth > Bluedroid Options
This enables controller RPA list function. For ESP32, ESP32 only support network privacy mode. If this option is enabled, ESP32 will only accept advertising packets from peer devices that contain private address, HW will not receive the advertising packets contain identity address after IRK changed. If this option is disabled, address resolution will be performed in the host, so the functions that require controller to resolve address in the white list cannot be used. This option is disabled by default on ESP32, please enable or disable this option according to your own needs.
For ESP32C3 and esp32s3, devices support network privacy mode and device privacy mode, users can switch the two modes according to their own needs. So this option is enabled by default.
Default value: · Yes (enabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED

CONFIG_BT_BLE_50_FEATURES_SUPPORTED Enable BLE 5.0 features Found in: Component config > Bluetooth > Bluedroid Options This enables BLE 5.0 features, this option only support esp32c3/esp32s3 chip Default value: · Yes (enabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED

CONFIG_BT_BLE_42_FEATURES_SUPPORTED Enable BLE 4.2 features Found in: Component config > Bluetooth > Bluedroid Options This enables BLE 4.2 features. Default value: · No (disabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED

NimBLE Options Contains:
· CONFIG_BT_NIMBLE_ACL_BUF_COUNT · CONFIG_BT_NIMBLE_ACL_BUF_SIZE · CONFIG_BT_NIMBLE_SVC_GAP_DEVICE_NAME · CONFIG_BT_NIMBLE_HS_STOP_TIMEOUT_MS · CONFIG_BT_NIMBLE_ROLE_BROADCASTER · CONFIG_BT_NIMBLE_ROLE_CENTRAL · CONFIG_BT_NIMBLE_MESH · CONFIG_BT_NIMBLE_ROLE_OBSERVER · CONFIG_BT_NIMBLE_ROLE_PERIPHERAL · CONFIG_BT_NIMBLE_BLUFI_ENABLE · CONFIG_BT_NIMBLE_ENABLE_CONN_REATTEMPT

Espressif Systems

1409

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· CONFIG_BT_NIMBLE_USE_ESP_TIMER · CONFIG_BT_NIMBLE_EXT_ADV · CONFIG_BT_NIMBLE_DEBUG · CONFIG_BT_NIMBLE_HOST_BASED_PRIVACY · CONFIG_BT_NIMBLE_HS_FLOW_CTRL · CONFIG_BT_NIMBLE_SVC_GAP_APPEARANCE · CONFIG_BT_NIMBLE_HCI_EVT_BUF_SIZE · CONFIG_BT_NIMBLE_HCI_EVT_HI_BUF_COUNT · CONFIG_BT_NIMBLE_HCI_EVT_LO_BUF_COUNT · CONFIG_BT_NIMBLE_GAP_DEVICE_NAME_MAX_LEN · CONFIG_BT_NIMBLE_MAX_BONDS · CONFIG_BT_NIMBLE_MAX_CCCDS · CONFIG_BT_NIMBLE_MAX_CONNECTIONS · CONFIG_BT_NIMBLE_L2CAP_COC_MAX_NUM · CONFIG_BT_NIMBLE_MEM_ALLOC_MODE · CONFIG_BT_NIMBLE_MSYS1_BLOCK_COUNT · CONFIG_BT_NIMBLE_LOG_LEVEL · CONFIG_BT_NIMBLE_TASK_STACK_SIZE · CONFIG_BT_NIMBLE_CRYPTO_STACK_MBEDTLS · CONFIG_BT_NIMBLE_NVS_PERSIST · CONFIG_BT_NIMBLE_ATT_PREFERRED_MTU · CONFIG_BT_NIMBLE_RPA_TIMEOUT · CONFIG_BT_NIMBLE_SM_LEGACY · CONFIG_BT_NIMBLE_SM_SC · CONFIG_BT_NIMBLE_PINNED_TO_CORE_CHOICE · CONFIG_BT_NIMBLE_SM_SC_DEBUG_KEYS
CONFIG_BT_NIMBLE_MEM_ALLOC_MODE
Memory allocation strategy
Found in: Component config > Bluetooth > NimBLE Options
Allocation strategy for NimBLE host stack, essentially provides ability to allocate all required dynamic allocations from,
· Internal DRAM memory only · External SPIRAM memory only · Either internal or external memory based on default malloc() behavior in ESP-IDF · Internal IRAM memory wherever applicable else internal DRAM
Available options: · Internal memory (BT_NIMBLE_MEM_ALLOC_MODE_INTERNAL) · External SPIRAM (BT_NIMBLE_MEM_ALLOC_MODE_EXTERNAL) · Default alloc mode (BT_NIMBLE_MEM_ALLOC_MODE_DEFAULT) · Internal IRAM (BT_NIMBLE_MEM_ALLOC_MODE_IRAM_8BIT) Allows to use IRAM memory region as 8bit accessible region. Every unaligned (8bit or 16bit) access will result in an exception and incur penalty of certain clock cycles per unaligned read/write.
CONFIG_BT_NIMBLE_LOG_LEVEL
NimBLE Host log verbosity
Found in: Component config > Bluetooth > NimBLE Options
Select NimBLE log level. Please make a note that the selected NimBLE log verbosity can not exceed the level set in oComponent config > Log output > Default log verbosityp.
Available options: · No logs (BT_NIMBLE_LOG_LEVEL_NONE)

Espressif Systems

1410

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· Error logs (BT_NIMBLE_LOG_LEVEL_ERROR) · Warning logs (BT_NIMBLE_LOG_LEVEL_WARNING) · Info logs (BT_NIMBLE_LOG_LEVEL_INFO) · Debug logs (BT_NIMBLE_LOG_LEVEL_DEBUG)
CONFIG_BT_NIMBLE_MAX_CONNECTIONS Maximum number of concurrent connections Found in: Component config > Bluetooth > NimBLE Options Defines maximum number of concurrent BLE connections. For ESP32, user is expected to configure BTDM_CTRL_BLE_MAX_CONN from controller menu along with this option. Similarly for ESP32C3 or ESP32-S3, user is expected to configure BT_CTRL_BLE_MAX_ACT from controller menu. Range: · from 1 to 8 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED Default value: · 3 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MAX_BONDS Maximum number of bonds to save across reboots Found in: Component config > Bluetooth > NimBLE Options Defines maximum number of bonds to save for peer security and our security Default value: · 3 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MAX_CCCDS Maximum number of CCC descriptors to save across reboots Found in: Component config > Bluetooth > NimBLE Options Defines maximum number of CCC descriptors to save Default value: · 8 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_L2CAP_COC_MAX_NUM Maximum number of connection oriented channels Found in: Component config > Bluetooth > NimBLE Options Defines maximum number of BLE Connection Oriented Channels. When set to (0), BLE COC is not compiled in Range: · from 0 to 9 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED Default value: · 0 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_PINNED_TO_CORE_CHOICE The CPU core on which NimBLE host will run Found in: Component config > Bluetooth > NimBLE Options The CPU core on which NimBLE host will run. You can choose Core 0 or Core 1. Cannot specify no-affinity

Espressif Systems

1411

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Available options: · Core 0 (PRO CPU) (BT_NIMBLE_PINNED_TO_CORE_0) · Core 1 (APP CPU) (BT_NIMBLE_PINNED_TO_CORE_1)
CONFIG_BT_NIMBLE_TASK_STACK_SIZE NimBLE Host task stack size Found in: Component config > Bluetooth > NimBLE Options This configures stack size of NimBLE host task Default value: · 5120 if CONFIG_BLE_MESH && BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED · 4096 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_ROLE_CENTRAL Enable BLE Central role Found in: Component config > Bluetooth > NimBLE Options Default value: · Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_ROLE_PERIPHERAL Enable BLE Peripheral role Found in: Component config > Bluetooth > NimBLE Options Default value: · Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_ROLE_BROADCASTER Enable BLE Broadcaster role Found in: Component config > Bluetooth > NimBLE Options Default value: · Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_ROLE_OBSERVER Enable BLE Observer role Found in: Component config > Bluetooth > NimBLE Options Default value: · Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_NVS_PERSIST Persist the BLE Bonding keys in NVS Found in: Component config > Bluetooth > NimBLE Options Enable this flag to make bonding persistent across device reboots Default value: · Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED

Espressif Systems

1412

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_BT_NIMBLE_SM_LEGACY Security manager legacy pairing Found in: Component config > Bluetooth > NimBLE Options Enable security manager legacy pairing Default value: · Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED

CONFIG_BT_NIMBLE_SM_SC Security manager secure connections (4.2) Found in: Component config > Bluetooth > NimBLE Options Enable security manager secure connections Default value: · Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED

CONFIG_BT_NIMBLE_DEBUG Enable extra runtime asserts and host debugging Found in: Component config > Bluetooth > NimBLE Options This enables extra runtime asserts and host debugging Default value: · No (disabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED

CONFIG_BT_NIMBLE_SM_SC_DEBUG_KEYS
Use predefined public-private key pair
Found in: Component config > Bluetooth > NimBLE Options
If this option is enabled, SM uses predefined DH key pair as described in Core Specification, Vol. 3, Part H, 2.3.5.6.1. This allows to decrypt air traffic easily and thus should only be used for debugging.
Default value: · No (disabled) if CONFIG_BT_NIMBLE_SM_SC && BT_NIMBLE_ENABLED

CONFIG_BT_NIMBLE_SVC_GAP_DEVICE_NAME
BLE GAP default device name
Found in: Component config > Bluetooth > NimBLE Options
The Device Name characteristic shall contain the name of the device as an UTF-8 string. This name can be changed by using API ble_svc_gap_device_name_set()
Default value: ·onimblepif BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED

CONFIG_BT_NIMBLE_GAP_DEVICE_NAME_MAX_LEN Maximum length of BLE device name in octets Found in: Component config > Bluetooth > NimBLE Options Device Name characteristic value shall be 0 to 248 octets in length Default value: · 31 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED

Espressif Systems

1413

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_BT_NIMBLE_ATT_PREFERRED_MTU Preferred MTU size in octets Found in: Component config > Bluetooth > NimBLE Options This is the default value of ATT MTU indicated by the device during an ATT MTU exchange. This value can be changed using API ble_att_set_preferred_mtu() Default value: · 256 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_SVC_GAP_APPEARANCE External appearance of the device Found in: Component config > Bluetooth > NimBLE Options Standard BLE GAP Appearance value in HEX format e.g. 0x02C0 Default value: · 0 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_ACL_BUF_COUNT ACL Buffer count Found in: Component config > Bluetooth > NimBLE Options The number of ACL data buffers. Default value: · 20 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_ACL_BUF_SIZE ACL Buffer size Found in: Component config > Bluetooth > NimBLE Options This is the maximum size of the data portion of HCI ACL data packets. It does not include the HCI data header (of 4 bytes) Default value: · 255 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_HCI_EVT_BUF_SIZE HCI Event Buffer size Found in: Component config > Bluetooth > NimBLE Options This is the size of each HCI event buffer in bytes. In case of extended advertising, packets can be fragmented. 257 bytes is the maximum size of a packet. Default value: · 257 if CONFIG_BT_NIMBLE_EXT_ADV && BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED · 70 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED

Espressif Systems

1414

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_BT_NIMBLE_HCI_EVT_HI_BUF_COUNT High Priority HCI Event Buffer count Found in: Component config > Bluetooth > NimBLE Options This is the high priority HCI eventsnbuffer size. High-priority event buffers are for everything except advertising reports. If there are no free high-priority event buffers then host will try to allocate a lowpriority buffer instead Default value: · 30 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_HCI_EVT_LO_BUF_COUNT Low Priority HCI Event Buffer count Found in: Component config > Bluetooth > NimBLE Options This is the low priority HCI eventsnbuffer size. Low-priority event buffers are only used for advertising reports. If there are no free low-priority event buffers, then an incoming advertising report will get dropped Default value: · 8 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MSYS1_BLOCK_COUNT MSYS_1 Block Count Found in: Component config > Bluetooth > NimBLE Options MSYS is a system level mbuf registry. For prepare write & prepare responses MBUFs are allocated out of msys_1 pool. For NIMBLE_MESH enabled cases, this block count is increased by 8 than user defined count. Default value: · 12 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_HS_FLOW_CTRL Enable Host Flow control Found in: Component config > Bluetooth > NimBLE Options Enable Host Flow control Default value: · Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_HS_FLOW_CTRL_ITVL Host Flow control interval Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_HS_FLOW_CTRL Host flow control interval in msecs Default value: · 1000 if CONFIG_BT_NIMBLE_HS_FLOW_CTRL && BT_NIMBLE_ENABLED

Espressif Systems

1415

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_BT_NIMBLE_HS_FLOW_CTRL_THRESH Host Flow control threshold Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_HS_FLOW_CTRL Host flow control threshold, if the number of free buffers are at or below this threshold, send an immediate number-of-completed-packets event Default value: · 2 if CONFIG_BT_NIMBLE_HS_FLOW_CTRL && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_HS_FLOW_CTRL_TX_ON_DISCONNECT Host Flow control on disconnect Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_HS_FLOW_CTRL Enable this option to send number-of-completed-packets event to controller after disconnection Default value: · Yes (enabled) if CONFIG_BT_NIMBLE_HS_FLOW_CTRL && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_RPA_TIMEOUT RPA timeout in seconds Found in: Component config > Bluetooth > NimBLE Options Time interval between RPA address change. This is applicable in case of Host based RPA Range: · from 1 to 41400 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED Default value: · 900 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH Enable BLE mesh functionality Found in: Component config > Bluetooth > NimBLE Options Enable BLE Mesh functionality Default value: · No (disabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
Contains: · CONFIG_BT_NIMBLE_MESH_PROVISIONER · CONFIG_BT_NIMBLE_MESH_PROV · CONFIG_BT_NIMBLE_MESH_GATT_PROXY · CONFIG_BT_NIMBLE_MESH_FRIEND · CONFIG_BT_NIMBLE_MESH_LOW_POWER · CONFIG_BT_NIMBLE_MESH_PROXY · CONFIG_BT_NIMBLE_MESH_RELAY · CONFIG_BT_NIMBLE_MESH_DEVICE_NAME · CONFIG_BT_NIMBLE_MESH_NODE_COUNT
CONFIG_BT_NIMBLE_MESH_PROXY Enable mesh proxy functionality Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH

Espressif Systems

1416

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Enable proxy. This is automatically set whenever NIMBLE_MESH_PB_GATT or NIMBLE_MESH_GATT_PROXY is set Default value:
· No (disabled) if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_PROV Enable BLE mesh provisioning Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH Enable mesh provisioning Default value: · Yes (enabled) if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_PB_ADV Enable mesh provisioning over advertising bearer Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH > CONFIG_BT_NIMBLE_MESH_PROV Enable this option to allow the device to be provisioned over the advertising bearer Default value: · Yes (enabled) if CONFIG_BT_NIMBLE_MESH_PROV && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_PB_GATT Enable mesh provisioning over GATT bearer Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH > CONFIG_BT_NIMBLE_MESH_PROV Enable this option to allow the device to be provisioned over the GATT bearer Default value: · Yes (enabled) if CONFIG_BT_NIMBLE_MESH_PROV && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_GATT_PROXY Enable GATT Proxy functionality Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH This option enables support for the Mesh GATT Proxy Service, i.e. the ability to act as a proxy between a Mesh GATT Client and a Mesh network Default value: · Yes (enabled) if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_RELAY Enable mesh relay functionality Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH Support for acting as a Mesh Relay Node Default value: · No (disabled) if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED

Espressif Systems

1417

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_BT_NIMBLE_MESH_LOW_POWER Enable mesh low power mode Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH Enable this option to be able to act as a Low Power Node Default value: · No (disabled) if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_FRIEND Enable mesh friend functionality Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH Enable this option to be able to act as a Friend Node Default value: · No (disabled) if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_DEVICE_NAME Set mesh device name Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH This value defines Bluetooth Mesh device/node name Default value: ·onimble-mesh-nodepif CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_NODE_COUNT Set mesh node count Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH Defines mesh node count. Default value: · 1 if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_PROVISIONER Enable BLE mesh provisioner Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH Enable mesh provisioner. Default value: · 0 if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_CRYPTO_STACK_MBEDTLS Override TinyCrypt with mbedTLS for crypto computations Found in: Component config > Bluetooth > NimBLE Options Enable this option to choose mbedTLS instead of TinyCrypt for crypto computations. Default value: · Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED

Espressif Systems

1418

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_BT_NIMBLE_HS_STOP_TIMEOUT_MS BLE host stop timeout in msec Found in: Component config > Bluetooth > NimBLE Options BLE Host stop procedure timeout in milliseconds. Default value: · 2000 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED

CONFIG_BT_NIMBLE_HOST_BASED_PRIVACY
Enable host based privacy for random address.
Found in: Component config > Bluetooth > NimBLE Options
Use this option to do host based Random Private Address resolution. If this option is disabled then controller based privacy is used.
Default value: · No (disabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED

CONFIG_BT_NIMBLE_ENABLE_CONN_REATTEMPT Enable connection reattempts on connection establishment error Found in: Component config > Bluetooth > NimBLE Options Enable to make the NimBLE host to reattempt GAP connection on connection establishment failure. Default value: · Yes (enabled) if BT_NIMBLE_ENABLED

CONFIG_BT_NIMBLE_MAX_CONN_REATTEMPT

Maximum number connection reattempts

Found in:

Component config > Bluetooth > NimBLE Options > CON-

FIG_BT_NIMBLE_ENABLE_CONN_REATTEMPT

Defines maximum number of connection reattempts.

Range: · from 1 to 7 if BT_NIMBLE_ENABLED && CONFIG_BT_NIMBLE_ENABLE_CONN_REATTEMPT && BT_NIMBLE_ENABLED
Default value: · 3 if BT_NIMBLE_ENABLED && CONFIG_BT_NIMBLE_ENABLE_CONN_REATTEMPT && BT_NIMBLE_ENABLED

CONFIG_BT_NIMBLE_EXT_ADV Enable extended advertising. Found in: Component config > Bluetooth > NimBLE Options Enable this option to do extended advertising. Extended advertising will be supported from BLE 5.0 onwards.

Espressif Systems

1419

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_BT_NIMBLE_MAX_EXT_ADV_INSTANCES
Maximum number of extended advertising instances.
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_EXT_ADV
Change this option to set maximum number of extended advertising instances. Minimum there is always one instance of advertising. Enter how many more advertising instances you want.
Range: · from 0 to 4 if CONFIG_BT_NIMBLE_EXT_ADV && BT_NIMBLE_ENABLED
Default value: · 1 if CONFIG_BT_NIMBLE_EXT_ADV && CONFIG_BT_NIMBLE_EXT_ADV && BT_NIMBLE_ENABLED · 0 if CONFIG_BT_NIMBLE_EXT_ADV && BT_NIMBLE_ENABLED

CONFIG_BT_NIMBLE_MAX_EXT_ADV_DATA_LEN
Maximum length of the advertising data.
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_EXT_ADV
Defines size of extended advertising data. Size should not increase 1650.
Range: · from 0 to 1650 if CONFIG_BT_NIMBLE_EXT_ADV && BT_NIMBLE_ENABLED
Default value: · 1650 if CONFIG_BT_NIMBLE_EXT_ADV && CONFIG_BT_NIMBLE_EXT_ADV && BT_NIMBLE_ENABLED · 0 if CONFIG_BT_NIMBLE_EXT_ADV && BT_NIMBLE_ENABLED

CONFIG_BT_NIMBLE_ENABLE_PERIODIC_ADV Enable periodic advertisement. Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_EXT_ADV Enable this option to start periodic advertisement. Default value: · Yes (enabled) if CONFIG_BT_NIMBLE_EXT_ADV && BT_NIMBLE_ENABLED

CONFIG_BT_NIMBLE_MAX_PERIODIC_SYNCS

Maximum number of periodic advertising syncs.

Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_EXT_ADV > CONFIG_BT_NIMBLE_ENABLE_PERIODIC_ADV

Set this option to set the upper limit for number of periodic sync connections. This should be less than maximum connections allowed by controller.

Range:

· from 1 to 8 if CONFIG_BT_NIMBLE_ENABLE_PERIODIC_ADV &&

BT_NIMBLE_ENABLED

Default value:

·1

if

CONFIG_BT_NIMBLE_ENABLE_PERIODIC_ADV

&&

CON-

FIG_BT_NIMBLE_ENABLE_PERIODIC_ADV && BT_NIMBLE_ENABLED

· 0 if CONFIG_BT_NIMBLE_ENABLE_PERIODIC_ADV && BT_NIMBLE_ENABLED

Espressif Systems

1420

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_BT_NIMBLE_BLUFI_ENABLE
Enable blufi functionality
Found in: Component config > Bluetooth > NimBLE Options
Set this option to enable blufi functionality.
Default value: · No (disabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_USE_ESP_TIMER
Enable Esp Timer for Nimble
Found in: Component config > Bluetooth > NimBLE Options
Set this option to use Esp Timer which has higher priority timer instead of FreeRTOS timer
Default value: · Yes (enabled) if BT_NIMBLE_ENABLED
CONFIG_BLE_MESH
ESP BLE Mesh Support
Found in: Component config
This option enables ESP BLE Mesh support. The specific features that are available may depend on other features that have been enabled in the stack, such as Bluetooth Support, Bluedroid Support & GATT support.
Contains:
· BLE Mesh and BLE coexistence support · CONFIG_BLE_MESH_GATT_PROXY_CLIENT · CONFIG_BLE_MESH_GATT_PROXY_SERVER · BLE Mesh NET BUF DEBUG LOG LEVEL · CONFIG_BLE_MESH_PROV · CONFIG_BLE_MESH_PROXY · BLE Mesh specific test option · BLE Mesh STACK DEBUG LOG LEVEL · CONFIG_BLE_MESH_NO_LOG · CONFIG_BLE_MESH_IVU_DIVIDER · CONFIG_BLE_MESH_FAST_PROV · CONFIG_BLE_MESH_FREERTOS_STATIC_ALLOC · CONFIG_BLE_MESH_CRPL · CONFIG_BLE_MESH_RX_SDU_MAX · CONFIG_BLE_MESH_MODEL_KEY_COUNT · CONFIG_BLE_MESH_APP_KEY_COUNT · CONFIG_BLE_MESH_MODEL_GROUP_COUNT · CONFIG_BLE_MESH_LABEL_COUNT · CONFIG_BLE_MESH_SUBNET_COUNT · CONFIG_BLE_MESH_TX_SEG_MAX · CONFIG_BLE_MESH_RX_SEG_MSG_COUNT · CONFIG_BLE_MESH_TX_SEG_MSG_COUNT · CONFIG_BLE_MESH_MEM_ALLOC_MODE · CONFIG_BLE_MESH_MSG_CACHE_SIZE · CONFIG_BLE_MESH_ADV_BUF_COUNT · CONFIG_BLE_MESH_PB_GATT · CONFIG_BLE_MESH_PB_ADV · CONFIG_BLE_MESH_RELAY · CONFIG_BLE_MESH_SETTINGS

Espressif Systems

1421

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· CONFIG_BLE_MESH_DEINIT · CONFIG_BLE_MESH_USE_DUPLICATE_SCAN · Support for BLE Mesh Client/Server models · Support for BLE Mesh Foundation models · CONFIG_BLE_MESH_NODE · CONFIG_BLE_MESH_PROVISIONER · CONFIG_BLE_MESH_FRIEND · CONFIG_BLE_MESH_LOW_POWER · CONFIG_BLE_MESH_HCI_5_0 · CONFIG_BLE_MESH_IV_UPDATE_TEST · CONFIG_BLE_MESH_CLIENT_MSG_TIMEOUT

CONFIG_BLE_MESH_HCI_5_0 Support sending 20ms non-connectable adv packets Found in: Component config > CONFIG_BLE_MESH It is a temporary solution and needs further modifications. Default value: · Yes (enabled) if CONFIG_BLE_MESH

CONFIG_BLE_MESH_USE_DUPLICATE_SCAN
Support Duplicate Scan in BLE Mesh
Found in: Component config > CONFIG_BLE_MESH
Enable this option to allow using specific duplicate scan filter in BLE Mesh, and Scan Duplicate Type must be set by choosing the option in the Bluetooth Controller section in menuconfig, which is oScan Duplicate By Device Address and Advertising Datap.
Default value: · Yes (enabled) if BT_BLUEDROID_ENABLED && CONFIG_BLE_MESH

CONFIG_BLE_MESH_MEM_ALLOC_MODE
Memory allocation strategy
Found in: Component config > CONFIG_BLE_MESH
Allocation strategy for BLE Mesh stack, essentially provides ability to allocate all required dynamic allocations from,
· Internal DRAM memory only · External SPIRAM memory only · Either internal or external memory based on default malloc() behavior in ESP-IDF · Internal IRAM memory wherever applicable else internal DRAM
Recommended mode here is always internal (*), since that is most preferred from security perspective. But if application requirement does not allow sufficient free internal memory then alternate mode can be selected.
(*) In case of ESP32-S2/ESP32-S3, hardware allows encryption of external SPIRAM contents provided hardware flash encryption feature is enabled. In that case, using external SPIRAM allocation strategy is also safe choice from security perspective.
Available options: · Internal DRAM (BLE_MESH_MEM_ALLOC_MODE_INTERNAL) · External SPIRAM (BLE_MESH_MEM_ALLOC_MODE_EXTERNAL) · Default alloc mode (BLE_MESH_MEM_ALLOC_MODE_DEFAULT) Enable this option to use the default memory allocation strategy when external SPIRAM is enabled. See the SPIRAM options for more details.

Espressif Systems

1422

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· Internal IRAM (BLE_MESH_MEM_ALLOC_MODE_IRAM_8BIT) Allows to use IRAM memory region as 8bit accessible region. Every unaligned (8bit or 16bit) access will result in an exception and incur penalty of certain clock cycles per unaligned read/write.

CONFIG_BLE_MESH_FREERTOS_STATIC_ALLOC
Enable FreeRTOS static allocation
Found in: Component config > CONFIG_BLE_MESH
Enable this option to use FreeRTOS static allocation APIs for BLE Mesh, which provides the ability to use different dynamic memory (i.e. SPIRAM or IRAM) for FreeRTOS objects. If this option is disabled, the FreeRTOS static allocation APIs will not be used, and internal DRAM will be allocated for FreeRTOS objects.
Default value: · No (disabled) if (ESP32_SPIRAM_SUPPORT || ESP32_IRAM_AS_8BIT_ACCESSIBLE_MEMORY) && CONFIG_BLE_MESH

CONFIG_BLE_MESH_FREERTOS_STATIC_ALLOC_MODE

Memory allocation for FreeRTOS objects

Found in:

Component config > CONFIG_BLE_MESH > CON-

FIG_BLE_MESH_FREERTOS_STATIC_ALLOC

Choose the memory to be used for FreeRTOS objects.

Available options: · External SPIRAM (BLE_MESH_FREERTOS_STATIC_ALLOC_EXTERNAL) If enabled, BLE Mesh allocates dynamic memory from external SPIRAM for FreeRTOS objects, i.e. mutex, queue, and task stack. External SPIRAM can only be used for task stack when SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY is enabled. See the SPIRAM options for more details. · Internal IRAM (BLE_MESH_FREERTOS_STATIC_ALLOC_IRAM_8BIT) If enabled, BLE Mesh allocates dynamic memory from internal IRAM for FreeRTOS objects, i.e. mutex, queue. Note: IRAM region cannot be used as task stack.

CONFIG_BLE_MESH_DEINIT Support de-initialize BLE Mesh stack Found in: Component config > CONFIG_BLE_MESH If enabled, users can use the function esp_ble_mesh_deinit() to de-initialize the whole BLE Mesh stack. Default value: · Yes (enabled) if CONFIG_BLE_MESH

BLE Mesh and BLE coexistence support Contains:
· CONFIG_BLE_MESH_SUPPORT_BLE_SCAN · CONFIG_BLE_MESH_SUPPORT_BLE_ADV

CONFIG_BLE_MESH_SUPPORT_BLE_ADV Support sending normal BLE advertising packets Found in: Component config > CONFIG_BLE_MESH > BLE Mesh and BLE coexistence support When selected, users can send normal BLE advertising packets with specific API.

Espressif Systems

1423

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Default value: · No (disabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_BLE_ADV_BUF_COUNT Number of advertising buffers for BLE advertising packets Found in: Component config > CONFIG_BLE_MESH > BLE Mesh and BLE coexistence support > CONFIG_BLE_MESH_SUPPORT_BLE_ADV Number of advertising buffers for BLE packets available. Range: · from 1 to 255 if CONFIG_BLE_MESH_SUPPORT_BLE_ADV && CONFIG_BLE_MESH Default value: · 3 if CONFIG_BLE_MESH_SUPPORT_BLE_ADV && CONFIG_BLE_MESH
CONFIG_BLE_MESH_SUPPORT_BLE_SCAN Support scanning normal BLE advertising packets Found in: Component config > CONFIG_BLE_MESH > BLE Mesh and BLE coexistence support When selected, users can register a callback and receive normal BLE advertising packets in the application layer. Default value: · No (disabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_FAST_PROV Enable BLE Mesh Fast Provisioning Found in: Component config > CONFIG_BLE_MESH Enable this option to allow BLE Mesh fast provisioning solution to be used. When there are multiple unprovisioned devices around, fast provisioning can greatly reduce the time consumption of the whole provisioning process. When this option is enabled, and after an unprovisioned device is provisioned into a node successfully, it can be changed to a temporary Provisioner. Default value: · No (disabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_NODE Support for BLE Mesh Node Found in: Component config > CONFIG_BLE_MESH Enable the device to be provisioned into a node. This option should be enabled when an unprovisioned device is going to be provisioned into a node and communicate with other nodes in the BLE Mesh network.
CONFIG_BLE_MESH_PROVISIONER Support for BLE Mesh Provisioner Found in: Component config > CONFIG_BLE_MESH Enable the device to be a Provisioner. The option should be enabled when a device is going to act as a Provisioner and provision unprovisioned devices into the BLE Mesh network.

Espressif Systems

1424

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_BLE_MESH_WAIT_FOR_PROV_MAX_DEV_NUM
Maximum number of unprovisioned devices that can be added to device queue
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_PROVISIONER
This option specifies how many unprovisioned devices can be added to device queue for provisioning. Users can use this option to define the size of the queue in the bottom layer which is used to store unprovisioned device information (e.g. Device UUID, address).
Range: · from 1 to 100 if CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH
Default value: · 10 if CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_MAX_PROV_NODES
Maximum number of devices that can be provisioned by Provisioner
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_PROVISIONER
This option specifies how many devices can be provisioned by a Provisioner. This value indicates the maximum number of unprovisioned devices which can be provisioned by a Provisioner. For instance, if the value is 6, it means the Provisioner can provision up to 6 unprovisioned devices. Theoretically a Provisioner without the limitation of its memory can provision up to 32766 unprovisioned devices, here we limit the maximum number to 100 just to limit the memory used by a Provisioner. The bigger the value is, the more memory it will cost by a Provisioner to store the information of nodes.
Range: · from 1 to 1000 if CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH
Default value: · 10 if CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH

CONFIG_BLE_MESH_PBA_SAME_TIME
Maximum number of PB-ADV running at the same time by Provisioner
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_PROVISIONER
This option specifies how many devices can be provisioned at the same time using PB-ADV. For examples, if the value is 2, it means a Provisioner can provision two unprovisioned devices with PB-ADV at the same time.
Range: · from 1 to 10 if CONFIG_BLE_MESH_PB_ADV && CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH
Default value: · 2 if CONFIG_BLE_MESH_PB_ADV && CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_PBG_SAME_TIME
Maximum number of PB-GATT running at the same time by Provisioner
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_PROVISIONER
This option specifies how many devices can be provisioned at the same time using PB-GATT. For example, if the value is 2, it means a Provisioner can provision two unprovisioned devices with PB-GATT at the same time.
Range: · from 1 to 5 if CONFIG_BLE_MESH_PB_GATT && CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH
Default value:

Espressif Systems

1425

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· 1 if CONFIG_BLE_MESH_PB_GATT && CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH

CONFIG_BLE_MESH_PROVISIONER_SUBNET_COUNT
Maximum number of mesh subnets that can be created by Provisioner
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_PROVISIONER
This option specifies how many subnets per network a Provisioner can create. Indeed, this value decides the number of network keys which can be added by a Provisioner.
Range: · from 1 to 4096 if CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH
Default value: · 3 if CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH

CONFIG_BLE_MESH_PROVISIONER_APP_KEY_COUNT
Maximum number of application keys that can be owned by Provisioner
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_PROVISIONER
This option specifies how many application keys the Provisioner can have. Indeed, this value decides the number of the application keys which can be added by a Provisioner.
Range: · from 1 to 4096 if CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH
Default value: · 3 if CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH

CONFIG_BLE_MESH_PROVISIONER_RECV_HB
Support receiving Heartbeat messages
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_PROVISIONER
When this option is enabled, Provisioner can call specific functions to enable or disable receiving Heartbeat messages and notify them to the application layer.
Default value: · No (disabled) if CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH

CONFIG_BLE_MESH_PROVISIONER_RECV_HB_FILTER_SIZE

Maximum number of filter entries for receiving Heartbeat messages

Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_PROVISIONER > CONFIG_BLE_MESH_PROVISIONER_RECV_HB

This option specifies how many heartbeat filter entries Provisioner supports. The heartbeat filter (acceptlist or rejectlist) entries are used to store a list of SRC and DST which can be used to decide if a heartbeat message will be processed and notified to the application layer by Provisioner. Note: The filter is an empty rejectlist by default.

Range:

· from 1 to 1000 if CONFIG_BLE_MESH_PROVISIONER_RECV_HB &&

FIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH

Default value:

·3

if

CONFIG_BLE_MESH_PROVISIONER_RECV_HB

&&

FIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH

CONCON-

Espressif Systems

1426

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_BLE_MESH_PROV BLE Mesh Provisioning support Found in: Component config > CONFIG_BLE_MESH Enable this option to support BLE Mesh Provisioning functionality. For BLE Mesh, this option should be always enabled. Default value: · Yes (enabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_PB_ADV Provisioning support using the advertising bearer (PB-ADV) Found in: Component config > CONFIG_BLE_MESH Enable this option to allow the device to be provisioned over the advertising bearer. This option should be enabled if PB-ADV is going to be used during provisioning procedure. Default value: · Yes (enabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_UNPROVISIONED_BEACON_INTERVAL Interval between two consecutive Unprovisioned Device Beacon Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_PB_ADV This option specifies the interval of sending two consecutive unprovisioned device beacon, users can use this option to change the frequency of sending unprovisioned device beacon. For example, if the value is 5, it means the unprovisioned device beacon will send every 5 seconds. When the option of BLE_MESH_FAST_PROV is selected, the value is better to be 3 seconds, or less. Range: · from 1 to 100 if CONFIG_BLE_MESH_NODE && CONFIG_BLE_MESH_PB_ADV && CONFIG_BLE_MESH Default value: · 5 if CONFIG_BLE_MESH_NODE && CONFIG_BLE_MESH_PB_ADV && CONFIG_BLE_MESH · 3 if CONFIG_BLE_MESH_FAST_PROV && CONFIG_BLE_MESH_NODE && CONFIG_BLE_MESH_PB_ADV && CONFIG_BLE_MESH
CONFIG_BLE_MESH_PB_GATT Provisioning support using GATT (PB-GATT) Found in: Component config > CONFIG_BLE_MESH Enable this option to allow the device to be provisioned over GATT. This option should be enabled if PB-GATT is going to be used during provisioning procedure. # Virtual option enabled whenever any Proxy protocol is needed
CONFIG_BLE_MESH_PROXY BLE Mesh Proxy protocol support Found in: Component config > CONFIG_BLE_MESH Enable this option to support BLE Mesh Proxy protocol used by PB-GATT and other proxy pdu transmission. Default value:

Espressif Systems

1427

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· Yes (enabled) if CONFIG_BLE_MESH

CONFIG_BLE_MESH_GATT_PROXY_SERVER
BLE Mesh GATT Proxy Server
Found in: Component config > CONFIG_BLE_MESH
This option enables support for Mesh GATT Proxy Service, i.e. the ability to act as a proxy between a Mesh GATT Client and a Mesh network. This option should be enabled if a node is going to be a Proxy Server.
Default value: · Yes (enabled) if CONFIG_BLE_MESH_NODE && CONFIG_BLE_MESH

CONFIG_BLE_MESH_NODE_ID_TIMEOUT
Node Identity advertising timeout
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_GATT_PROXY_SERVER
This option determines for how long the local node advertises using Node Identity. The given value is in seconds. The specification limits this to 60 seconds and lists it as the recommended value as well. So leaving the default value is the safest option. When an unprovisioned device is provisioned successfully and becomes a node, it will start to advertise using Node Identity during the time set by this option. And after that, Network ID will be advertised.
Range: · from 1 to 60 if CONFIG_BLE_MESH_GATT_PROXY_SERVER && CONFIG_BLE_MESH
Default value: · 60 if CONFIG_BLE_MESH_GATT_PROXY_SERVER && CONFIG_BLE_MESH

CONFIG_BLE_MESH_PROXY_FILTER_SIZE

Maximum number of filter entries per Proxy Client

Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_GATT_PROXY_SERVER

This option specifies how many Proxy Filter entries the local node supports. The entries of Proxy filter (whitelist or blacklist) are used to store a list of addresses which can be used to decide which messages will be forwarded to the Proxy Client by the Proxy Server.

Range: · from 1 to 32767 if CONFIG_BLE_MESH_GATT_PROXY_SERVER && FIG_BLE_MESH
Default value: · 4 if CONFIG_BLE_MESH_GATT_PROXY_SERVER && CONFIG_BLE_MESH

CON-

CONFIG_BLE_MESH_GATT_PROXY_CLIENT
BLE Mesh GATT Proxy Client
Found in: Component config > CONFIG_BLE_MESH
This option enables support for Mesh GATT Proxy Client. The Proxy Client can use the GATT bearer to send mesh messages to a node that supports the advertising bearer.
Default value: · No (disabled) if CONFIG_BLE_MESH

Espressif Systems

1428

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_BLE_MESH_SETTINGS
Store BLE Mesh configuration persistently
Found in: Component config > CONFIG_BLE_MESH
When selected, the BLE Mesh stack will take care of storing/restoring the BLE Mesh configuration persistently in flash. If the device is a BLE Mesh node, when this option is enabled, the configuration of the device will be stored persistently, including unicast address, NetKey, AppKey, etc. And if the device is a BLE Mesh Provisioner, the information of the device will be stored persistently, including the information of provisioned nodes, NetKey, AppKey, etc.
Default value: · No (disabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_STORE_TIMEOUT
Delay (in seconds) before storing anything persistently
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_SETTINGS
This value defines in seconds how soon any pending changes are actually written into persistent storage (flash) after a change occurs. The option allows nodes to delay a certain period of time to save proper information to flash. The default value is 0, which means information will be stored immediately once there are updates.
Range: · from 0 to 1000000 if CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH
Default value: · 0 if CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH

CONFIG_BLE_MESH_SEQ_STORE_RATE
How often the sequence number gets updated in storage
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_SETTINGS
This value defines how often the local sequence number gets updated in persistent storage (i.e. flash). e.g. a value of 100 means that the sequence number will be stored to flash on every 100th increment. If the node sends messages very frequently a higher value makes more sense, whereas if the node sends infrequently a value as low as 0 (update storage for every increment) can make sense. When the stack gets initialized it will add sequence number to the last stored one, so that it starts off with a value thatn s guaranteed to be larger than the last one used before power off.
Range: · from 0 to 1000000 if CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH
Default value: · 0 if CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH
CONFIG_BLE_MESH_RPL_STORE_TIMEOUT
Minimum frequency that the RPL gets updated in storage
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_SETTINGS
This value defines in seconds how soon the RPL (Replay Protection List) gets written to persistent storage after a change occurs. If the node receives messages frequently, then a large value is recommended. If the node receives messages rarely, then the value can be as low as 0 (which means the RPL is written into the storage immediately). Note that if the node operates in a security-sensitive case, and there is a risk of sudden power-off, then a value of 0 is strongly recommended. Otherwise, a power loss before RPL being written into the storage may introduce message replay attacks and system security will be in a vulnerable state.
Range:

Espressif Systems

1429

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· from 0 to 1000000 if CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH Default value:
· 0 if CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH

CONFIG_BLE_MESH_SETTINGS_BACKWARD_COMPATIBILITY
A specific option for settings backward compatibility
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_SETTINGS
This option is created to solve the issue of failure in recovering node information after mesh stack updates. In the old version mesh stack, there is no key of omesh/rolepin nvs. In the new version mesh stack, key of omesh/rolepis added in nvs, recovering node information needs to check omesh/rolep key in nvs and implements selective recovery of mesh node information. Therefore, there may be failure in recovering node information during node restarting after OTA.
The new version mesh stack adds the option of omesh/rolepbecause we have added the support of storing Provisioner information, while the old version only supports storing node information.
If users are updating their nodes from old version to new version, we recommend enabling this option, so that system could set the flag in advance before recovering node information and make sure the node information recovering could work as expected.
Default value: · No (disabled) if CONFIG_BLE_MESH_NODE && CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH

CONFIG_BLE_MESH_SPECIFIC_PARTITION
Use a specific NVS partition for BLE Mesh
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_SETTINGS
When selected, the mesh stack will use a specified NVS partition instead of default NVS partition. Note that the specified partition must be registered with NVS using nvs_flash_init_partition() API, and the partition must exists in the csv file. When Provisioner needs to store a large amount of nodesninformation in the flash (e.g. more than 20), this option is recommended to be enabled.
Default value: · No (disabled) if CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH

CONFIG_BLE_MESH_PARTITION_NAME

Name of the NVS partition for BLE Mesh

Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_SETTINGS > CONFIG_BLE_MESH_SPECIFIC_PARTITION

This value defines the name of the specified NVS partition used by the mesh stack.

Default value:

·oble_meshpif

CONFIG_BLE_MESH_SPECIFIC_PARTITION

&&

CON-

FIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH

CONFIG_BLE_MESH_USE_MULTIPLE_NAMESPACE
Support using multiple NVS namespaces by Provisioner
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_SETTINGS
When selected, Provisioner can use different NVS namespaces to store different instances of mesh information. For example, if in the first room, Provisioner uses NetKey A, AppKey A and provisions three devices, these information will be treated as mesh information instance A. When the Provisioner

Espressif Systems

1430

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

moves to the second room, it uses NetKey B, AppKey B and provisions two devices, then the information will be treated as mesh information instance B. Here instance A and instance B will be stored in different namespaces. With this option enabled, Provisioner needs to use specific functions to open the corresponding NVS namespace, restore the mesh information, release the mesh information or erase the mesh information.
Default value: · No (disabled) if CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH

CONFIG_BLE_MESH_MAX_NVS_NAMESPACE
Maximum number of NVS namespaces
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_SETTINGS > CONFIG_BLE_MESH_USE_MULTIPLE_NAMESPACE
This option specifies the maximum NVS namespaces supported by Provisioner.
Range: · from 1 to 255 if CONFIG_BLE_MESH_USE_MULTIPLE_NAMESPACE && CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH
Default value: · 2 if CONFIG_BLE_MESH_USE_MULTIPLE_NAMESPACE && CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH

CONFIG_BLE_MESH_SUBNET_COUNT
Maximum number of mesh subnets per network
Found in: Component config > CONFIG_BLE_MESH
This option specifies how many subnets a Mesh network can have at the same time. Indeed, this value decides the number of the network keys which can be owned by a node.
Range: · from 1 to 4096 if CONFIG_BLE_MESH
Default value: · 3 if CONFIG_BLE_MESH

CONFIG_BLE_MESH_APP_KEY_COUNT
Maximum number of application keys per network
Found in: Component config > CONFIG_BLE_MESH
This option specifies how many application keys the device can store per network. Indeed, this value decides the number of the application keys which can be owned by a node.
Range: · from 1 to 4096 if CONFIG_BLE_MESH
Default value: · 3 if CONFIG_BLE_MESH

CONFIG_BLE_MESH_MODEL_KEY_COUNT Maximum number of application keys per model Found in: Component config > CONFIG_BLE_MESH This option specifies the maximum number of application keys to which each model can be bound. Range: · from 1 to 4096 if CONFIG_BLE_MESH

Espressif Systems

1431

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Default value: · 3 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_MODEL_GROUP_COUNT
Maximum number of group address subscriptions per model
Found in: Component config > CONFIG_BLE_MESH
This option specifies the maximum number of addresses to which each model can be subscribed.
Range: · from 1 to 4096 if CONFIG_BLE_MESH
Default value: · 3 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_LABEL_COUNT
Maximum number of Label UUIDs used for Virtual Addresses
Found in: Component config > CONFIG_BLE_MESH
This option specifies how many Label UUIDs can be stored. Indeed, this value decides the number of the Virtual Addresses can be supported by a node.
Range: · from 0 to 4096 if CONFIG_BLE_MESH
Default value: · 3 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_CRPL
Maximum capacity of the replay protection list
Found in: Component config > CONFIG_BLE_MESH
This option specifies the maximum capacity of the replay protection list. It is similar to Network message cache size, but has a different purpose. The replay protection list is used to prevent a node from replay attack, which will store the source address and sequence number of the received mesh messages. For Provisioner, the replay protection list size should not be smaller than the maximum number of nodes whose information can be stored. And the element number of each node should also be taken into consideration. For example, if Provisioner can provision up to 20 nodes and each node contains two elements, then the replay protection list size of Provisioner should be at least 40.
Range: · from 2 to 65535 if CONFIG_BLE_MESH
Default value: · 10 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_MSG_CACHE_SIZE
Network message cache size
Found in: Component config > CONFIG_BLE_MESH
Number of messages that are cached for the network. This helps prevent unnecessary decryption operations and unnecessary relays. This option is similar to Replay protection list, but has a different purpose. A node is not required to cache the entire Network PDU and may cache only part of it for tracking, such as values for SRC/SEQ or others.
Range: · from 2 to 65535 if CONFIG_BLE_MESH
Default value:

Espressif Systems

1432

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· 10 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_ADV_BUF_COUNT
Number of advertising buffers
Found in: Component config > CONFIG_BLE_MESH
Number of advertising buffers available. The transport layer reserves ADV_BUF_COUNT - 3 buffers for outgoing segments. The maximum outgoing SDU size is 12 times this value (out of which 4 or 8 bytes are used for the Transport Layer MIC). For example, 5 segments means the maximum SDU size is 60 bytes, which leaves 56 bytes for application layer data using a 4-byte MIC, or 52 bytes using an 8-byte MIC.
Range: · from 6 to 256 if CONFIG_BLE_MESH
Default value: · 60 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_IVU_DIVIDER
Divider for IV Update state refresh timer
Found in: Component config > CONFIG_BLE_MESH
When the IV Update state enters Normal operation or IV Update in Progress, we need to keep track of how many hours has passed in the state, since the specification requires us to remain in the state at least for 96 hours (Update in Progress has an additional upper limit of 144 hours).
In order to fulfill the above requirement, even if the node might be powered off once in a while, we need to store persistently how many hours the node has been in the state. This doesnnt necessarily need to happen every hour (thanks to the flexible duration range). The exact cadence will depend a lot on the ways that the node will be used and what kind of power source it has.
Since there is no single optimal answer, this configuration option allows specifying a divider, i.e. how many intervals the 96 hour minimum gets split into. After each interval the duration that the node has been in the current state gets stored to flash. E.g. the default value of 4 means that the state is saved every 24 hours (96 / 4).
Range: · from 2 to 96 if CONFIG_BLE_MESH
Default value: · 4 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_TX_SEG_MSG_COUNT
Maximum number of simultaneous outgoing segmented messages
Found in: Component config > CONFIG_BLE_MESH
Maximum number of simultaneous outgoing multi-segment and/or reliable messages. The default value is 1, which means the device can only send one segmented message at a time. And if another segmented message is going to be sent, it should wait for the completion of the previous one. If users are going to send multiple segmented messages at the same time, this value should be configured properly.
Range: · from 1 to if CONFIG_BLE_MESH
Default value: · 1 if CONFIG_BLE_MESH

Espressif Systems

1433

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_BLE_MESH_RX_SEG_MSG_COUNT
Maximum number of simultaneous incoming segmented messages
Found in: Component config > CONFIG_BLE_MESH
Maximum number of simultaneous incoming multi-segment and/or reliable messages. The default value is 1, which means the device can only receive one segmented message at a time. And if another segmented message is going to be received, it should wait for the completion of the previous one. If users are going to receive multiple segmented messages at the same time, this value should be configured properly.
Range: · from 1 to 255 if CONFIG_BLE_MESH
Default value: · 1 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_RX_SDU_MAX
Maximum incoming Upper Transport Access PDU length
Found in: Component config > CONFIG_BLE_MESH
Maximum incoming Upper Transport Access PDU length. Leave this to the default value, unless you really need to optimize memory usage.
Range: · from 36 to 384 if CONFIG_BLE_MESH
Default value: · 384 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_TX_SEG_MAX
Maximum number of segments in outgoing messages
Found in: Component config > CONFIG_BLE_MESH
Maximum number of segments supported for outgoing messages. This value should typically be finetuned based on what models the local node supports, i.e. whatns the largest message payload that the node needs to be able to send. This value affects memory and call stack consumption, which is why the default is lower than the maximum that the specification would allow (32 segments).
The maximum outgoing SDU size is 12 times this number (out of which 4 or 8 bytes is used for the Transport Layer MIC). For example, 5 segments means the maximum SDU size is 60 bytes, which leaves 56 bytes for application layer data using a 4-byte MIC and 52 bytes using an 8-byte MIC.
Be sure to specify a sufficient number of advertising buffers when setting this option to a higher value. There must be at least three more advertising buffers (BLE_MESH_ADV_BUF_COUNT) as there are outgoing segments.
Range: · from 2 to 32 if CONFIG_BLE_MESH
Default value: · 32 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_RELAY
Relay support
Found in: Component config > CONFIG_BLE_MESH
Support for acting as a Mesh Relay Node. Enabling this option will allow a node to support the Relay feature, and the Relay feature can still be enabled or disabled by proper configuration messages. Disabling this option will let a node not support the Relay feature.

Espressif Systems

1434

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Default value: · Yes (enabled) if CONFIG_BLE_MESH_NODE && CONFIG_BLE_MESH
CONFIG_BLE_MESH_RELAY_ADV_BUF Use separate advertising buffers for relay packets Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_RELAY When selected, self-send packets will be put in a high-priority queue and relay packets will be put in a low-priority queue. Default value: · No (disabled) if CONFIG_BLE_MESH_RELAY && CONFIG_BLE_MESH
CONFIG_BLE_MESH_RELAY_ADV_BUF_COUNT Number of advertising buffers for relay packets Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_RELAY > CONFIG_BLE_MESH_RELAY_ADV_BUF Number of advertising buffers for relay packets available. Range: · from 6 to 256 if CONFIG_BLE_MESH_RELAY_ADV_BUF && CONFIG_BLE_MESH_RELAY && CONFIG_BLE_MESH Default value: · 60 if CONFIG_BLE_MESH_RELAY_ADV_BUF && CONFIG_BLE_MESH_RELAY && CONFIG_BLE_MESH
CONFIG_BLE_MESH_LOW_POWER Support for Low Power features Found in: Component config > CONFIG_BLE_MESH Enable this option to operate as a Low Power Node. If low power consumption is required by a node, this option should be enabled. And once the node enters the mesh network, it will try to find a Friend node and establish a friendship.
CONFIG_BLE_MESH_LPN_ESTABLISHMENT Perform Friendship establishment using low power Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER Perform the Friendship establishment using low power with the help of a reduced scan duty cycle. The downside of this is that the node may miss out on messages intended for it until it has successfully set up Friendship with a Friend node. When this option is enabled, the node will stop scanning for a period of time after a Friend Request or Friend Poll is sent, so as to reduce more power consumption. Default value: · No (disabled) if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_LPN_AUTO Automatically start looking for Friend nodes once provisioned Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER Once provisioned, automatically enable LPN functionality and start looking for Friend nodes. If this option is disabled LPN mode needs to be manually enabled by calling bt_mesh_lpn_set(true). When an

Espressif Systems

1435

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

unprovisioned device is provisioned successfully and becomes a node, enabling this option will trigger the node starts to send Friend Request at a certain period until it finds a proper Friend node.
Default value: · No (disabled) if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH

CONFIG_BLE_MESH_LPN_AUTO_TIMEOUT
Time from last received message before going to LPN mode
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER > CONFIG_BLE_MESH_LPN_AUTO
Time in seconds from the last received message, that the node waits out before starting to look for Friend nodes.
Range: · from 0 to 3600 if CONFIG_BLE_MESH_LPN_AUTO && CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
Default value: · 15 if CONFIG_BLE_MESH_LPN_AUTO && CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH

CONFIG_BLE_MESH_LPN_RETRY_TIMEOUT
Retry timeout for Friend requests
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER
Time in seconds between Friend Requests, if a previous Friend Request did not yield any acceptable Friend Offers.
Range: · from 1 to 3600 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
Default value: · 6 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH

CONFIG_BLE_MESH_LPN_RSSI_FACTOR
RSSIFactor, used in Friend Offer Delay calculation
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER
The contribution of the RSSI, measured by the Friend node, used in Friend Offer Delay calculations. 0 = 1, 1 = 1.5, 2 = 2, 3 = 2.5. RSSIFactor, one of the parameters carried by Friend Request sent by Low Power node, which is used to calculate the Friend Offer Delay.
Range: · from 0 to 3 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
Default value: · 0 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH

CONFIG_BLE_MESH_LPN_RECV_WIN_FACTOR
ReceiveWindowFactor, used in Friend Offer Delay calculation
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER
The contribution of the supported Receive Window used in Friend Offer Delay calculations. 0 = 1, 1 = 1.5, 2 = 2, 3 = 2.5. ReceiveWindowFactor, one of the parameters carried by Friend Request sent by Low Power node, which is used to calculate the Friend Offer Delay.
Range: · from 0 to 3 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH

Espressif Systems

1436

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Default value: · 0 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_LPN_MIN_QUEUE_SIZE
Minimum size of the acceptable friend queue (MinQueueSizeLog)
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER
The MinQueueSizeLog field is defined as log_2(N), where N is the minimum number of maximum size Lower Transport PDUs that the Friend node can store in its Friend Queue. As an example, MinQueueSizeLog value 1 gives N = 2, and value 7 gives N = 128.
Range: · from 1 to 7 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
Default value: · 1 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_LPN_RECV_DELAY
Receive delay requested by the local node
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER
The ReceiveDelay is the time between the Low Power node sending a request and listening for a response. This delay allows the Friend node time to prepare the response. The value is in units of milliseconds.
Range: · from 10 to 255 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
Default value: · 100 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_LPN_POLL_TIMEOUT
The value of the PollTimeout timer
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER
PollTimeout timer is used to measure time between two consecutive requests sent by a Low Power node. If no requests are received the Friend node before the PollTimeout timer expires, then the friendship is considered terminated. The value is in units of 100 milliseconds, so e.g. a value of 300 means 30 seconds. The smaller the value, the faster the Low Power node tries to get messages from corresponding Friend node and vice versa.
Range: · from 10 to 244735 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
Default value: · 300 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_LPN_INIT_POLL_TIMEOUT
The starting value of the PollTimeout timer
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER
The initial value of the PollTimeout timer when Friendship is to be established for the first time. After this, the timeout gradually grows toward the actual PollTimeout, doubling in value for each iteration. The value is in units of 100 milliseconds, so e.g. a value of 300 means 30 seconds.
Range: · from 10 to if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
Default value: · if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH

Espressif Systems

1437

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_BLE_MESH_LPN_SCAN_LATENCY Latency for enabling scanning Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER Latency (in milliseconds) is the time it takes to enable scanning. In practice, it means how much time in advance of the Receive Window, the request to enable scanning is made. Range: · from 0 to 50 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH Default value: · 10 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_LPN_GROUPS Number of groups the LPN can subscribe to Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER Maximum number of groups to which the LPN can subscribe. Range: · from 0 to 16384 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH Default value: · 8 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_FRIEND Support for Friend feature Found in: Component config > CONFIG_BLE_MESH Enable this option to be able to act as a Friend Node.
CONFIG_BLE_MESH_FRIEND_RECV_WIN Friend Receive Window Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_FRIEND Receive Window in milliseconds supported by the Friend node. Range: · from 1 to 255 if CONFIG_BLE_MESH_FRIEND && CONFIG_BLE_MESH Default value: · 255 if CONFIG_BLE_MESH_FRIEND && CONFIG_BLE_MESH
CONFIG_BLE_MESH_FRIEND_QUEUE_SIZE Minimum number of buffers supported per Friend Queue Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_FRIEND Minimum number of buffers available to be stored for each local Friend Queue. This option decides the size of each buffer which can be used by a Friend node to store messages for each Low Power node. Range: · from 2 to 65536 if CONFIG_BLE_MESH_FRIEND && CONFIG_BLE_MESH Default value: · 16 if CONFIG_BLE_MESH_FRIEND && CONFIG_BLE_MESH

Espressif Systems

1438

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_BLE_MESH_FRIEND_SUB_LIST_SIZE Friend Subscription List Size Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_FRIEND Size of the Subscription List that can be supported by a Friend node for a Low Power node. And Low Power node can send Friend Subscription List Add or Friend Subscription List Remove messages to the Friend node to add or remove subscription addresses. Range: · from 0 to 1023 if CONFIG_BLE_MESH_FRIEND && CONFIG_BLE_MESH Default value: · 3 if CONFIG_BLE_MESH_FRIEND && CONFIG_BLE_MESH
CONFIG_BLE_MESH_FRIEND_LPN_COUNT Number of supported LPN nodes Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_FRIEND Number of Low Power Nodes with which a Friend can have Friendship simultaneously. A Friend node can have friendship with multiple Low Power nodes at the same time, while a Low Power node can only establish friendship with only one Friend node at the same time. Range: · from 1 to 1000 if CONFIG_BLE_MESH_FRIEND && CONFIG_BLE_MESH Default value: · 2 if CONFIG_BLE_MESH_FRIEND && CONFIG_BLE_MESH
CONFIG_BLE_MESH_FRIEND_SEG_RX Number of incomplete segment lists per LPN Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_FRIEND Number of incomplete segment lists tracked for each FriendsnLPN. In other words, this determines from how many elements can segmented messages destined for the Friend queue be received simultaneously. Range: · from 1 to 1000 if CONFIG_BLE_MESH_FRIEND && CONFIG_BLE_MESH Default value: · 1 if CONFIG_BLE_MESH_FRIEND && CONFIG_BLE_MESH
CONFIG_BLE_MESH_NO_LOG Disable BLE Mesh debug logs (minimize bin size) Found in: Component config > CONFIG_BLE_MESH Select this to save the BLE Mesh related rodata code size. Enabling this option will disable the output of BLE Mesh debug log. Default value: · No (disabled) if CONFIG_BLE_MESH && CONFIG_BLE_MESH
BLE Mesh STACK DEBUG LOG LEVEL Contains: · CONFIG_BLE_MESH_STACK_TRACE_LEVEL

Espressif Systems

1439

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_BLE_MESH_STACK_TRACE_LEVEL BLE_MESH_STACK Found in: Component config > CONFIG_BLE_MESH > BLE Mesh STACK DEBUG LOG LEVEL Define BLE Mesh trace level for BLE Mesh stack. Available options: · NONE (BLE_MESH_TRACE_LEVEL_NONE) · ERROR (BLE_MESH_TRACE_LEVEL_ERROR) · WARNING (BLE_MESH_TRACE_LEVEL_WARNING) · INFO (BLE_MESH_TRACE_LEVEL_INFO) · DEBUG (BLE_MESH_TRACE_LEVEL_DEBUG) · VERBOSE (BLE_MESH_TRACE_LEVEL_VERBOSE)
BLE Mesh NET BUF DEBUG LOG LEVEL Contains: · CONFIG_BLE_MESH_NET_BUF_TRACE_LEVEL
CONFIG_BLE_MESH_NET_BUF_TRACE_LEVEL BLE_MESH_NET_BUF Found in: Component config > CONFIG_BLE_MESH > BLE Mesh NET BUF DEBUG LOG LEVEL Define BLE Mesh trace level for BLE Mesh net buffer. Available options: · NONE (BLE_MESH_NET_BUF_TRACE_LEVEL_NONE) · ERROR (BLE_MESH_NET_BUF_TRACE_LEVEL_ERROR) · WARNING (BLE_MESH_NET_BUF_TRACE_LEVEL_WARNING) · INFO (BLE_MESH_NET_BUF_TRACE_LEVEL_INFO) · DEBUG (BLE_MESH_NET_BUF_TRACE_LEVEL_DEBUG) · VERBOSE (BLE_MESH_NET_BUF_TRACE_LEVEL_VERBOSE)
CONFIG_BLE_MESH_CLIENT_MSG_TIMEOUT Timeout(ms) for client message response Found in: Component config > CONFIG_BLE_MESH Timeout value used by the node to get response of the acknowledged message which is sent by the client model. This value indicates the maximum time that a client model waits for the response of the sent acknowledged messages. If a client model uses 0 as the timeout value when sending acknowledged messages, then the default value will be used which is four seconds. Range: · from 100 to 1200000 if CONFIG_BLE_MESH Default value: · 4000 if CONFIG_BLE_MESH
Support for BLE Mesh Foundation models Contains: · CONFIG_BLE_MESH_CFG_CLI · CONFIG_BLE_MESH_HEALTH_CLI · CONFIG_BLE_MESH_HEALTH_SRV

Espressif Systems

1440

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_BLE_MESH_CFG_CLI Configuration Client model Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Foundation models Enable support for Configuration Client model.
CONFIG_BLE_MESH_HEALTH_CLI Health Client model Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Foundation models Enable support for Health Client model.
CONFIG_BLE_MESH_HEALTH_SRV Health Server model Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Foundation models Enable support for Health Server model. Default value: · Yes (enabled) if CONFIG_BLE_MESH
Support for BLE Mesh Client/Server models Contains: · CONFIG_BLE_MESH_GENERIC_BATTERY_CLI · CONFIG_BLE_MESH_GENERIC_DEF_TRANS_TIME_CLI · CONFIG_BLE_MESH_GENERIC_LEVEL_CLI · CONFIG_BLE_MESH_GENERIC_LOCATION_CLI · CONFIG_BLE_MESH_GENERIC_ONOFF_CLI · CONFIG_BLE_MESH_GENERIC_POWER_LEVEL_CLI · CONFIG_BLE_MESH_GENERIC_POWER_ONOFF_CLI · CONFIG_BLE_MESH_GENERIC_PROPERTY_CLI · CONFIG_BLE_MESH_GENERIC_SERVER · CONFIG_BLE_MESH_LIGHT_CTL_CLI · CONFIG_BLE_MESH_LIGHT_HSL_CLI · CONFIG_BLE_MESH_LIGHT_LC_CLI · CONFIG_BLE_MESH_LIGHT_LIGHTNESS_CLI · CONFIG_BLE_MESH_LIGHT_XYL_CLI · CONFIG_BLE_MESH_LIGHTING_SERVER · CONFIG_BLE_MESH_SCENE_CLI · CONFIG_BLE_MESH_SCHEDULER_CLI · CONFIG_BLE_MESH_SENSOR_CLI · CONFIG_BLE_MESH_SENSOR_SERVER · CONFIG_BLE_MESH_TIME_SCENE_SERVER · CONFIG_BLE_MESH_TIME_CLI
CONFIG_BLE_MESH_GENERIC_ONOFF_CLI Generic OnOff Client model Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Generic OnOff Client model.

Espressif Systems

1441

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_BLE_MESH_GENERIC_LEVEL_CLI Generic Level Client model Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Generic Level Client model.
CONFIG_BLE_MESH_GENERIC_DEF_TRANS_TIME_CLI Generic Default Transition Time Client model Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Generic Default Transition Time Client model.
CONFIG_BLE_MESH_GENERIC_POWER_ONOFF_CLI Generic Power OnOff Client model Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Generic Power OnOff Client model.
CONFIG_BLE_MESH_GENERIC_POWER_LEVEL_CLI Generic Power Level Client model Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Generic Power Level Client model.
CONFIG_BLE_MESH_GENERIC_BATTERY_CLI Generic Battery Client model Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Generic Battery Client model.
CONFIG_BLE_MESH_GENERIC_LOCATION_CLI Generic Location Client model Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Generic Location Client model.
CONFIG_BLE_MESH_GENERIC_PROPERTY_CLI Generic Property Client model Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Generic Property Client model.
CONFIG_BLE_MESH_SENSOR_CLI Sensor Client model Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Sensor Client model.

Espressif Systems

1442

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_BLE_MESH_TIME_CLI Time Client model Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Time Client model.
CONFIG_BLE_MESH_SCENE_CLI Scene Client model Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Scene Client model.
CONFIG_BLE_MESH_SCHEDULER_CLI Scheduler Client model Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Scheduler Client model.
CONFIG_BLE_MESH_LIGHT_LIGHTNESS_CLI Light Lightness Client model Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Light Lightness Client model.
CONFIG_BLE_MESH_LIGHT_CTL_CLI Light CTL Client model Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Light CTL Client model.
CONFIG_BLE_MESH_LIGHT_HSL_CLI Light HSL Client model Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Light HSL Client model.
CONFIG_BLE_MESH_LIGHT_XYL_CLI Light XYL Client model Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Light XYL Client model.
CONFIG_BLE_MESH_LIGHT_LC_CLI Light LC Client model Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Light LC Client model.

Espressif Systems

1443

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_BLE_MESH_GENERIC_SERVER Generic server models Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Generic server models. Default value: · Yes (enabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_SENSOR_SERVER Sensor server models Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Sensor server models. Default value: · Yes (enabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_TIME_SCENE_SERVER Time and Scenes server models Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Time and Scenes server models. Default value: · Yes (enabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_LIGHTING_SERVER Lighting server models Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Lighting server models. Default value: · Yes (enabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_IV_UPDATE_TEST Test the IV Update Procedure Found in: Component config > CONFIG_BLE_MESH This option removes the 96 hour limit of the IV Update Procedure and lets the state to be changed at any time. If IV Update test mode is going to be used, this option should be enabled. Default value: · No (disabled) if CONFIG_BLE_MESH
BLE Mesh specific test option Contains: · CONFIG_BLE_MESH_DEBUG · CONFIG_BLE_MESH_SHELL · CONFIG_BLE_MESH_SELF_TEST

Espressif Systems

1444

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_BLE_MESH_SELF_TEST Perform BLE Mesh self-tests Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option This option adds extra self-tests which are run every time BLE Mesh networking is initialized. Default value: · No (disabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_TEST_AUTO_ENTER_NETWORK Unprovisioned device enters mesh network automatically Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_SELF_TEST With this option enabled, an unprovisioned device can automatically enters mesh network using a specific test function without the pro- visioning procedure. And on the Provisioner side, a test function needs to be invoked to add the node information into the mesh stack. Default value: · Yes (enabled) if CONFIG_BLE_MESH_SELF_TEST && CONFIG_BLE_MESH
CONFIG_BLE_MESH_TEST_USE_WHITE_LIST Use white list to filter mesh advertising packets Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_SELF_TEST With this option enabled, users can use white list to filter mesh advertising packets while scanning. Default value: · No (disabled) if CONFIG_BLE_MESH_SELF_TEST && CONFIG_BLE_MESH
CONFIG_BLE_MESH_SHELL Enable BLE Mesh shell Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option Activate shell module that provides BLE Mesh commands to the console. Default value: · No (disabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_DEBUG Enable BLE Mesh debug logs Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option Enable debug logs for the BLE Mesh functionality. Default value: · No (disabled) if CONFIG_BLE_MESH

Espressif Systems

1445

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_BLE_MESH_DEBUG_NET Network layer debug Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG Enable Network layer debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_TRANS Transport layer debug Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG Enable Transport layer debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_BEACON Beacon debug Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG Enable Beacon-related debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_CRYPTO Crypto debug Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG Enable cryptographic debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_PROV Provisioning debug Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG Enable Provisioning debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_ACCESS Access layer debug Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG Enable Access layer debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_MODEL Foundation model debug Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG Enable Foundation Models debug logs for the BLE Mesh functionality.

Espressif Systems

1446

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_BLE_MESH_DEBUG_ADV Advertising debug Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG Enable advertising debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_LOW_POWER Low Power debug Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG Enable Low Power debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_FRIEND Friend debug Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG Enable Friend debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_PROXY Proxy debug Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG Enable Proxy protocol debug logs for the BLE Mesh functionality.
CoAP Configuration Contains: · CONFIG_COAP_MBEDTLS_ENCRYPTION_MODE · CONFIG_COAP_MBEDTLS_DEBUG
CONFIG_COAP_MBEDTLS_ENCRYPTION_MODE CoAP Encryption method Found in: Component config > CoAP Configuration If the CoAP information is to be encrypted, the encryption environment can be set up in one of two ways (default being Pre-Shared key mode) · Encrypt using defined Pre-Shared Keys (PSK if uri includes coaps://) · Encrypt using defined Public Key Infrastructure (PKI if uri includes coaps://) Available options: · Pre-Shared Keys (COAP_MBEDTLS_PSK) · PKI Certificates (COAP_MBEDTLS_PKI)

Espressif Systems

1447

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_COAP_MBEDTLS_DEBUG Enable CoAP debugging Found in: Component config > CoAP Configuration Enable CoAP debugging functions at compile time for the example code. If this option is enabled, call coap_set_log_level() at runtime in order to enable CoAP debug output via the ESP log mechanism. Default value: · No (disabled)
CONFIG_COAP_MBEDTLS_DEBUG_LEVEL Set CoAP debugging level Found in: Component config > CoAP Configuration > CONFIG_COAP_MBEDTLS_DEBUG Set CoAP debugging level Available options: · Emergency (COAP_LOG_EMERG) · Alert (COAP_LOG_ALERT) · Critical (COAP_LOG_CRIT) · Error (COAP_LOG_ERROR) · Warning (COAP_LOG_WARNING) · Notice (COAP_LOG_NOTICE) · Info (COAP_LOG_INFO) · Debug (COAP_LOG_DEBUG) · mbedTLS (COAP_LOG_MBEDTLS)
Driver configurations Contains: · ADC configuration · GDMA Configuration · GPTimer Configuration · MCPWM configuration · SPI configuration · TWAI configuration · UART configuration
ADC configuration Contains: · CONFIG_ADC_DISABLE_DAC · CONFIG_ADC_FORCE_XPD_FSM
CONFIG_ADC_FORCE_XPD_FSM Use the FSM to control ADC power Found in: Component config > Driver configurations > ADC configuration ADC power can be controlled by the FSM instead of software. This allows the ADC to be shut off when it is not working leading to lower power consumption. However using the FSM control ADC power will increase the noise of ADC. Default value: · No (disabled)

Espressif Systems

1448

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_ADC_DISABLE_DAC Disable DAC when ADC2 is used on GPIO 25 and 26 Found in: Component config > Driver configurations > ADC configuration If this is set, the ADC2 driver will disable the output of the DAC corresponding to the specified channel. This is the default value. For testing, disable this option so that we can measure the output of DAC by internal ADC. Default value: · Yes (enabled)
MCPWM configuration Contains: · CONFIG_MCPWM_ISR_IN_IRAM
CONFIG_MCPWM_ISR_IN_IRAM Place MCPWM ISR function into IRAM Found in: Component config > Driver configurations > MCPWM configuration If this option is not selected, the MCPWM interrupt will be deferred when the Cache is in a disabled state (e.g. Flash write/erase operation). Note that if this option is selected, all user registered ISR callbacks should never try to use cache as well. (with IRAM_ATTR) Default value: · No (disabled)
SPI configuration Contains: · CONFIG_SPI_MASTER_ISR_IN_IRAM · CONFIG_SPI_SLAVE_ISR_IN_IRAM · CONFIG_SPI_MASTER_IN_IRAM · CONFIG_SPI_SLAVE_IN_IRAM
CONFIG_SPI_MASTER_IN_IRAM Place transmitting functions of SPI master into IRAM Found in: Component config > Driver configurations > SPI configuration Normally only the ISR of SPI master is placed in the IRAM, so that it can work without the flash when interrupt is triggered. For other functions, therens some possibility that the flash cache miss when running inside and out of SPI functions, which may increase the interval of SPI transactions. Enable this to put queue\_trans, get\_trans\_result and transmit functions into the IRAM to avoid possible cache miss. During unit test, this is enabled to measure the ideal case of api. Default value: · No (disabled)
CONFIG_SPI_MASTER_ISR_IN_IRAM Place SPI master ISR function into IRAM Found in: Component config > Driver configurations > SPI configuration Place the SPI master ISR in to IRAM to avoid possible cache miss.

Espressif Systems

1449

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Also you can forbid the ISR being disabled during flash writing access, by add ESP_INTR_FLAG_IRAM when initializing the driver. Default value:
· Yes (enabled)
CONFIG_SPI_SLAVE_IN_IRAM Place transmitting functions of SPI slave into IRAM Found in: Component config > Driver configurations > SPI configuration Normally only the ISR of SPI slave is placed in the IRAM, so that it can work without the flash when interrupt is triggered. For other functions, therens some possibility that the flash cache miss when running inside and out of SPI functions, which may increase the interval of SPI transactions. Enable this to put queue\_trans, get\_trans\_result and transmit functions into the IRAM to avoid possible cache miss. Default value: · No (disabled)
CONFIG_SPI_SLAVE_ISR_IN_IRAM Place SPI slave ISR function into IRAM Found in: Component config > Driver configurations > SPI configuration Place the SPI slave ISR in to IRAM to avoid possible cache miss. Also you can forbid the ISR being disabled during flash writing access, by add ESP_INTR_FLAG_IRAM when initializing the driver. Default value: · Yes (enabled)
TWAI configuration Contains: · CONFIG_TWAI_ISR_IN_IRAM
CONFIG_TWAI_ISR_IN_IRAM Place TWAI ISR function into IRAM Found in: Component config > Driver configurations > TWAI configuration Place the TWAI ISR in to IRAM. This will allow the ISR to avoid cache misses, and also be able to run whilst the cache is disabled (such as when writing to SPI Flash). Note that if this option is enabled: Users should also set the ESP_INTR_FLAG_IRAM in the driver configuration structure when installing the driver (see docs for specifics). - Alert logging (i.e., setting of the TWAI_ALERT_AND_LOG flag) will have no effect. Default value: · No (disabled)
UART configuration Contains: · CONFIG_UART_ISR_IN_IRAM

Espressif Systems

1450

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_UART_ISR_IN_IRAM Place UART ISR function into IRAM Found in: Component config > Driver configurations > UART configuration If this option is not selected, UART interrupt will be disabled for a long time and may cause data lost when doing spi flash operation. Default value: · No (disabled)
GDMA Configuration Contains: · CONFIG_GDMA_ISR_IRAM_SAFE · CONFIG_GDMA_CTRL_FUNC_IN_IRAM
CONFIG_GDMA_CTRL_FUNC_IN_IRAM Place GDMA control functions into IRAM Found in: Component config > Driver configurations > GDMA Configuration Place GDMA control functions (like start/stop/append/reset) into IRAM, so that these functions can be IRAM-safe and able to be called in the other IRAM interrupt context. Enabling this option can improve driver performance as well. Default value: · No (disabled)
CONFIG_GDMA_ISR_IRAM_SAFE GDMA ISR IRAM-Safe Found in: Component config > Driver configurations > GDMA Configuration This will ensure the GDMA interrupt handler is IRAM-Safe, allow to avoid flash cache misses, and also be able to run whilst the cache is disabled. (e.g. SPI Flash write). Default value: · No (disabled)
GPTimer Configuration Contains: · CONFIG_GPTIMER_ISR_IRAM_SAFE · CONFIG_GPTIMER_CTRL_FUNC_IN_IRAM · CONFIG_GPTIMER_SUPPRESS_DEPRECATE_WARN
CONFIG_GPTIMER_CTRL_FUNC_IN_IRAM Place GPTimer control functions into IRAM Found in: Component config > Driver configurations > GPTimer Configuration Place GPTimer control functions (like start/stop) into IRAM, so that these functions can be IRAM-safe and able to be called in the other IRAM interrupt context. Enabling this option can improve driver performance as well. Default value: · No (disabled)

Espressif Systems

1451

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_GPTIMER_ISR_IRAM_SAFE
GPTimer ISR IRAM-Safe
Found in: Component config > Driver configurations > GPTimer Configuration
This will ensure the GPTimer interrupt handle is IRAM-Safe, allow to avoid flash cache misses, and also be able to run whilst the cache is disabled. (e.g. SPI Flash write)
Default value: · No (disabled)

CONFIG_GPTIMER_SUPPRESS_DEPRECATE_WARN
Suppress leagcy driver deprecated warning
Found in: Component config > Driver configurations > GPTimer Configuration
Wether to suppress the deprecation warnings when using legacy timer group driver (driver/timer.h). If you want to continue using the legacy driver, and donnt want to see related deprecation warnings, you can enable this option.
Default value: · No (disabled)

eFuse Bit Manager Contains:
· CONFIG_EFUSE_VIRTUAL · CONFIG_EFUSE_CUSTOM_TABLE

CONFIG_EFUSE_CUSTOM_TABLE Use custom eFuse table Found in: Component config > eFuse Bit Manager Allows to generate a structure for eFuse from the CSV file. Default value: · No (disabled)

CONFIG_EFUSE_CUSTOM_TABLE_FILENAME Custom eFuse CSV file Found in: Component config > eFuse Bit Manager > CONFIG_EFUSE_CUSTOM_TABLE Name of the custom eFuse CSV filename. This path is evaluated relative to the project root directory. Default value: ·omain/esp_efuse_custom_table.csvpif CONFIG_EFUSE_CUSTOM_TABLE

CONFIG_EFUSE_VIRTUAL
Simulate eFuse operations in RAM
Found in: Component config > eFuse Bit Manager
Ifonp- No virtual mode. All eFuse operations are real and use eFuse registers. Ifoyp- The virtual mode is enabled and all eFuse operations (read and write) are redirected to RAM instead of eFuse registers, all permanent changes (via eFuse) are disabled. Log output will state changes that would be applied, but they will not be.
During startup, the eFuses are copied into RAM. This mode is useful for fast tests.
Default value:

Espressif Systems

1452

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· No (disabled)

CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH
Keep eFuses in flash
Found in: Component config > eFuse Bit Manager > CONFIG_EFUSE_VIRTUAL
In addition to the oSimulate eFuse operations in RAMpoption, this option just adds a feature to keep eFuses after reboots in flash memory. To use this mode the partition_table should have the efuse partition. partition.csv: oefuse_em, data, efuse, , 0x2000,p
During startup, the eFuses are copied from flash or, in case if flash is empty, from real eFuse to RAM and then update flash. This mode is useful when need to keep changes after reboot (testing secure_boot and flash_encryption).

ESP-TLS Contains:
· CONFIG_ESP_TLS_INSECURE · CONFIG_ESP_TLS_LIBRARY_CHOOSE · CONFIG_ESP_TLS_CLIENT_SESSION_TICKETS · CONFIG_ESP_DEBUG_WOLFSSL · CONFIG_ESP_TLS_SERVER · CONFIG_ESP_TLS_PSK_VERIFICATION · CONFIG_ESP_TLS_SERVER_SESSION_TICKETS · CONFIG_ESP_WOLFSSL_SMALL_CERT_VERIFY · CONFIG_ESP_TLS_USE_DS_PERIPHERAL

CONFIG_ESP_TLS_LIBRARY_CHOOSE
Choose SSL/TLS library for ESP-TLS (See help for more Info)
Found in: Component config > ESP-TLS
The ESP-TLS APIs support multiple backend TLS libraries. Currently mbedTLS and WolfSSL are supported. Different TLS libraries may support different features and have different resource usage. Consult the ESP-TLS documentation in ESP-IDF Programming guide for more details.
Available options: · mbedTLS (ESP_TLS_USING_MBEDTLS) · wolfSSL (License info in wolfSSL directory README) (ESP_TLS_USING_WOLFSSL)

CONFIG_ESP_TLS_USE_DS_PERIPHERAL
Use Digital Signature (DS) Peripheral with ESP-TLS
Found in: Component config > ESP-TLS
Enable use of the Digital Signature Peripheral for ESP-TLS.The DS peripheral can only be used when it is appropriately configured for TLS. Consult the ESP-TLS documentation in ESP-IDF Programming Guide for more details.
Default value: · Yes (enabled)

CONFIG_ESP_TLS_SERVER Enable ESP-TLS Server Found in: Component config > ESP-TLS Enable support for creating server side SSL/TLS session, available for mbedTLS as well as wolfSSL TLS library.

Espressif Systems

1453

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Default value: · No (disabled)
CONFIG_ESP_TLS_CLIENT_SESSION_TICKETS Enable client session tickets Found in: Component config > ESP-TLS Enable session ticket support as specified in RFC5077. Default value: · No (disabled)
CONFIG_ESP_TLS_SERVER_SESSION_TICKETS Enable server session tickets Found in: Component config > ESP-TLS Enable session ticket support as specified in RFC5077 Default value: · No (disabled) if CONFIG_ESP_TLS_SERVER && ESP_TLS_USING_MBEDTLS && CONFIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS
CONFIG_ESP_TLS_SERVER_SESSION_TICKET_TIMEOUT Server session ticket timeout in seconds Found in: Component config > ESP-TLS > CONFIG_ESP_TLS_SERVER_SESSION_TICKETS Sets the session ticket timeout used in the tls server. Default value: · 86400 if CONFIG_ESP_TLS_SERVER_SESSION_TICKETS
CONFIG_ESP_TLS_PSK_VERIFICATION Enable PSK verification Found in: Component config > ESP-TLS Enable support for pre shared key ciphers, supported for both mbedTLS as well as wolfSSL TLS library. Default value: · No (disabled)
CONFIG_ESP_TLS_INSECURE Allow potentially insecure options Found in: Component config > ESP-TLS You can enable some potentially insecure options. These options should only be used for testing pusposes. Only enable these options if you are very sure.

Espressif Systems

1454

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_ESP_TLS_SKIP_SERVER_CERT_VERIFY Skip server certificate verification by default (WARNING: ONLY FOR TESTING PURPOSE, READ HELP) Found in: Component config > ESP-TLS > CONFIG_ESP_TLS_INSECURE After enabling this option the esp-tls client will skip the server certificate verification by default. Note that this option will only modify the default behaviour of esp-tls client regarding server cert verification. The default behaviour should only be applicable when no other option regarding the server cert verification is opted in the esp-tls config (e.g. crt_bundle_attach, use_global_ca_store etc.). WARNING : Enabling this option comes with a potential risk of establishing a TLS connection with a server which has a fake identity, provided that the server certificate is not provided either through API or other mechanism like ca_store etc.
CONFIG_ESP_WOLFSSL_SMALL_CERT_VERIFY Enable SMALL_CERT_VERIFY Found in: Component config > ESP-TLS Enables server verification with Intermediate CA cert, does not authenticate full chain of trust upto the root CA cert (After Enabling this option client only needs to have Intermediate CA certificate of the server to authenticate server, root CA cert is not necessary). Default value: · Yes (enabled) if ESP_TLS_USING_WOLFSSL
CONFIG_ESP_DEBUG_WOLFSSL Enable debug logs for wolfSSL Found in: Component config > ESP-TLS Enable detailed debug prints for wolfSSL SSL library. Default value: · No (disabled) if ESP_TLS_USING_WOLFSSL
ESP32S3-Specific Contains: · Cache config · CONFIG_ESP32S3_DEFAULT_CPU_FREQ_MHZ · CONFIG_ESP32S3_DEEP_SLEEP_WAKEUP_DELAY · CONFIG_ESP32S3_BROWNOUT_DET · CONFIG_ESP32S3_DEBUG_OCDAWARE · CONFIG_ESP32S3_NO_BLOBS · CONFIG_ESP32S3_RTC_CLK_CAL_CYCLES · CONFIG_ESP32S3_RTCDATA_IN_FAST_MEM · CONFIG_ESP32S3_RTC_CLK_SRC · CONFIG_ESP32S3_SPIRAM_SUPPORT · CONFIG_ESP32S3_TIME_SYSCALL · CONFIG_ESP32S3_USE_FIXED_STATIC_RAM_SIZE · CONFIG_ESP32S3_TRAX
CONFIG_ESP32S3_DEFAULT_CPU_FREQ_MHZ CPU frequency Found in: Component config > ESP32S3-Specific CPU frequency to be set on application startup.

Espressif Systems

1455

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Available options: · 40 MHz (ESP32S3_DEFAULT_CPU_FREQ_40) · 80 MHz (ESP32S3_DEFAULT_CPU_FREQ_80) · 160 MHz (ESP32S3_DEFAULT_CPU_FREQ_160) · 240 MHz (ESP32S3_DEFAULT_CPU_FREQ_240)
Cache config Contains: · CONFIG_ESP32S3_DCACHE_ASSOCIATED_WAYS · CONFIG_ESP32S3_DATA_CACHE_LINE_SIZE · CONFIG_ESP32S3_DATA_CACHE_SIZE · CONFIG_ESP32S3_ICACHE_ASSOCIATED_WAYS · CONFIG_ESP32S3_INSTRUCTION_CACHE_LINE_SIZE · CONFIG_ESP32S3_INSTRUCTION_CACHE_SIZE
CONFIG_ESP32S3_INSTRUCTION_CACHE_SIZE Instruction cache size Found in: Component config > ESP32S3-Specific > Cache config Instruction cache size to be set on application startup. If you use 16KB instruction cache rather than 32KB instruction cache, then the other 16KB will be managed by heap allocator. Available options: · 16KB (ESP32S3_INSTRUCTION_CACHE_16KB) · 32KB (ESP32S3_INSTRUCTION_CACHE_32KB)
CONFIG_ESP32S3_ICACHE_ASSOCIATED_WAYS Instruction cache associated ways Found in: Component config > ESP32S3-Specific > Cache config Instruction cache associated ways to be set on application startup. Available options: · 4 ways (ESP32S3_INSTRUCTION_CACHE_4WAYS) · 8 ways (ESP32S3_INSTRUCTION_CACHE_8WAYS)
CONFIG_ESP32S3_INSTRUCTION_CACHE_LINE_SIZE Instruction cache line size Found in: Component config > ESP32S3-Specific > Cache config Instruction cache line size to be set on application startup. Available options: · 16 Bytes (ESP32S3_INSTRUCTION_CACHE_LINE_16B) · 32 Bytes (ESP32S3_INSTRUCTION_CACHE_LINE_32B)
CONFIG_ESP32S3_DATA_CACHE_SIZE Data cache size Found in: Component config > ESP32S3-Specific > Cache config Data cache size to be set on application startup. If you use 32KB data cache rather than 64KB data cache, the other 32KB will be added to the heap. Available options: · 16KB (ESP32S3_DATA_CACHE_16KB)

Espressif Systems

1456

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· 32KB (ESP32S3_DATA_CACHE_32KB) · 64KB (ESP32S3_DATA_CACHE_64KB)

CONFIG_ESP32S3_DCACHE_ASSOCIATED_WAYS
Data cache associated ways
Found in: Component config > ESP32S3-Specific > Cache config
Data cache associated ways to be set on application startup.
Available options: · 4 ways (ESP32S3_DATA_CACHE_4WAYS) · 8 ways (ESP32S3_DATA_CACHE_8WAYS)

CONFIG_ESP32S3_DATA_CACHE_LINE_SIZE
Data cache line size
Found in: Component config > ESP32S3-Specific > Cache config
Data cache line size to be set on application startup.
Available options: · 16 Bytes (ESP32S3_DATA_CACHE_LINE_16B) · 32 Bytes (ESP32S3_DATA_CACHE_LINE_32B) · 64 Bytes (ESP32S3_DATA_CACHE_LINE_64B)

CONFIG_ESP32S3_SPIRAM_SUPPORT Support for external, SPI-connected RAM Found in: Component config > ESP32S3-Specific This enables support for an external SPI RAM chip, connected in parallel with the main SPI flash chip. Default value: · No (disabled)

SPI RAM config Contains:
· CONFIG_SPIRAM_FETCH_INSTRUCTIONS · CONFIG_SPIRAM_RODATA · CONFIG_SPIRAM_ECC_ENABLE · CONFIG_SPIRAM_BOOT_INIT · CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL · CONFIG_SPIRAM_MODE · PSRAM Clock and CS IO for ESP32S3 · CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL · CONFIG_SPIRAM_MEMTEST · CONFIG_SPIRAM_SPEED · CONFIG_SPIRAM_USE · CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP · CONFIG_SPIRAM_TYPE

CONFIG_SPIRAM_MODE Mode (QUAD/OCT) of SPI RAM chip in use Found in: Component config > ESP32S3-Specific > CONFIG_ESP32S3_SPIRAM_SUPPORT > SPI RAM config Available options:

Espressif Systems

1457

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· Quad Mode PSRAM (SPIRAM_MODE_QUAD) · Octal Mode PSRAM (SPIRAM_MODE_OCT)

CONFIG_SPIRAM_TYPE
Type of SPIRAM chip in use
Found in: Component config > ESP32S3-Specific > CONFIG_ESP32S3_SPIRAM_SUPPORT > SPI RAM config
Available options: · Auto-detect (SPIRAM_TYPE_AUTO) · ESP-PSRAM16 or APS1604 (SPIRAM_TYPE_ESPPSRAM16) · ESP-PSRAM32 or IS25WP032 (SPIRAM_TYPE_ESPPSRAM32) · ESP-PSRAM64 , LY68L6400 or APS6408 (SPIRAM_TYPE_ESPPSRAM64)

PSRAM Clock and CS IO for ESP32S3 Contains:
· CONFIG_DEFAULT_PSRAM_CLK_IO · CONFIG_DEFAULT_PSRAM_CS_IO

CONFIG_DEFAULT_PSRAM_CLK_IO
PSRAM CLK IO number
Found in: Component config > ESP32S3-Specific > CONFIG_ESP32S3_SPIRAM_SUPPORT > SPI RAM config > PSRAM Clock and CS IO for ESP32S3
The PSRAM Clock IO can be any unused GPIO, please refer to your hardware design.
Range: · from 0 to 33 if CONFIG_ESP32S3_SPIRAM_SUPPORT && CONFIG_ESP32S3_SPIRAM_SUPPORT
Default value: · 30 if CONFIG_ESP32S3_SPIRAM_SUPPORT && CONFIG_ESP32S3_SPIRAM_SUPPORT

CONFIG_DEFAULT_PSRAM_CS_IO
PSRAM CS IO number
Found in: Component config > ESP32S3-Specific > CONFIG_ESP32S3_SPIRAM_SUPPORT > SPI RAM config > PSRAM Clock and CS IO for ESP32S3
The PSRAM CS IO can be any unused GPIO, please refer to your hardware design.
Range: · from 0 to 33 if CONFIG_ESP32S3_SPIRAM_SUPPORT && CONFIG_ESP32S3_SPIRAM_SUPPORT
Default value: · 26 if CONFIG_ESP32S3_SPIRAM_SUPPORT && CONFIG_ESP32S3_SPIRAM_SUPPORT

CONFIG_SPIRAM_FETCH_INSTRUCTIONS
Cache fetch instructions from SPI RAM
Found in: Component config > ESP32S3-Specific > CONFIG_ESP32S3_SPIRAM_SUPPORT > SPI RAM config
If enabled, instruction in flash will be copied into SPIRAM. If SPIRAM_RODATA also enabled, you can run the instruction when erasing or programming the flash.
Default value: · No (disabled) if CONFIG_ESP32S3_SPIRAM_SUPPORT

Espressif Systems

1458

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_SPIRAM_RODATA
Cache load read only data from SPI RAM
Found in: Component config > ESP32S3-Specific > CONFIG_ESP32S3_SPIRAM_SUPPORT > SPI RAM config
If enabled, rodata in flash will be copied into SPIRAM. If SPIRAM_FETCH_INSTRUCTIONS is also enabled, you can run the instruction when erasing or programming the flash.
Default value: · No (disabled) if CONFIG_ESP32S3_SPIRAM_SUPPORT

CONFIG_SPIRAM_SPEED
Set RAM clock speed
Found in: Component config > ESP32S3-Specific > CONFIG_ESP32S3_SPIRAM_SUPPORT > SPI RAM config
Select the speed for the SPI RAM chip.
Available options: · 120MHz clock speed (SPIRAM_SPEED_120M) · 80MHz clock speed (SPIRAM_SPEED_80M) · 40Mhz clock speed (SPIRAM_SPEED_40M)

CONFIG_SPIRAM_BOOT_INIT
Initialize SPI RAM during startup
Found in: Component config > ESP32S3-Specific > CONFIG_ESP32S3_SPIRAM_SUPPORT > SPI RAM config
If this is enabled, the SPI RAM will be enabled during initial boot. Unless you have specific requirements, younll want to leave this enabled so memory allocated during boot-up can also be placed in SPI RAM.
Default value: · Yes (enabled) if CONFIG_ESP32S3_SPIRAM_SUPPORT

CONFIG_SPIRAM_IGNORE_NOTFOUND

Ignore PSRAM when not found

Found in: Component config > ESP32S3-Specific > CONFIG_ESP32S3_SPIRAM_SUPPORT > SPI RAM config > CONFIG_SPIRAM_BOOT_INIT

Normally, if psram initialization is enabled during compile time but not found at runtime, it is seen as an error making the CPU panic. If this is enabled, booting will complete but no PSRAM will be available.

Default value:

· No

(disabled)

if

CONFIG_SPIRAM_BOOT_INIT

&&

CON-

FIG_ESP32S3_SPIRAM_SUPPORT

CONFIG_SPIRAM_USE
SPI RAM access method
Found in: Component config > ESP32S3-Specific > CONFIG_ESP32S3_SPIRAM_SUPPORT > SPI RAM config
The SPI RAM can be accessed in multiple methods: by just having it available as an unmanaged memory region in the CPUns memory map, by integrating it in the heap as mspecialnmemory needing heap_caps_malloc to allocate, or by fully integrating it making malloc() also able to return SPI RAM pointers.

Espressif Systems

1459

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Available options: · Integrate RAM into memory map (SPIRAM_USE_MEMMAP) · Make RAM allocatable using heap_caps_malloc(l, MALLOC_CAP_SPIRAM) (SPIRAM_USE_CAPS_ALLOC) · Make RAM allocatable using malloc() as well (SPIRAM_USE_MALLOC)

CONFIG_SPIRAM_MEMTEST

Run memory test on SPI RAM initialization

Found in: Component config > ESP32S3-Specific > CONFIG_ESP32S3_SPIRAM_SUPPORT > SPI RAM config

Runs a rudimentary memory test on initialization. Aborts when memory test fails. Disable this for slightly faster startup.

Default value:

· Yes

(enabled)

if

CONFIG_SPIRAM_BOOT_INIT

&&

CON-

FIG_ESP32S3_SPIRAM_SUPPORT

CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL
Maximum malloc() size, in bytes, to always put in internal memory
Found in: Component config > ESP32S3-Specific > CONFIG_ESP32S3_SPIRAM_SUPPORT > SPI RAM config
If malloc() is capable of also allocating SPI-connected ram, its allocation strategy will prefer to allocate chunks less than this size in internal memory, while allocations larger than this will be done from external RAM. If allocation from the preferred region fails, an attempt is made to allocate from the non-preferred region instead, so malloc() will not suddenly fail when either internal or external memory is full.
Range: · from 0 to 131072 if SPIRAM_USE_MALLOC && CONFIG_ESP32S3_SPIRAM_SUPPORT
Default value: · 16384 if SPIRAM_USE_MALLOC && CONFIG_ESP32S3_SPIRAM_SUPPORT

CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP
Try to allocate memories of WiFi and LWIP in SPIRAM firstly. If failed, allocate internal memory
Found in: Component config > ESP32S3-Specific > CONFIG_ESP32S3_SPIRAM_SUPPORT > SPI RAM config
Try to allocate memories of WiFi and LWIP in SPIRAM firstly. If failed, try to allocate internal memory then.
Default value: · No (disabled) if (SPIRAM_USE_CAPS_ALLOC || SPIRAM_USE_MALLOC) && CONFIG_ESP32S3_SPIRAM_SUPPORT

CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL
Reserve this amount of bytes for data that specifically needs to be in DMA or internal memory
Found in: Component config > ESP32S3-Specific > CONFIG_ESP32S3_SPIRAM_SUPPORT > SPI RAM config
Because the external/internal RAM allocation strategy is not always perfect, it sometimes may happen that the internal memory is entirely filled up. This causes allocations that are specifically done in internal memory, for example the stack for new tasks or memory to service DMA or have memory thatns also available when SPI cache is down, to fail. This option reserves a pool specifically for requests like that; the memory in this pool is not given out when a normal malloc() is called.

Espressif Systems

1460

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Set this to 0 to disable this feature. Note that because FreeRTOS stacks are forced to internal memory, they will also use this memory pool; be sure to keep this in mind when adjusting this value. Note also that the DMA reserved pool may not be one single contiguous memory region, depending on the configured size and the static memory usage of the app. Range:
· from 0 to 262144 if SPIRAM_USE_MALLOC && CONFIG_ESP32S3_SPIRAM_SUPPORT Default value:
· 32768 if SPIRAM_USE_MALLOC && CONFIG_ESP32S3_SPIRAM_SUPPORT
CONFIG_SPIRAM_ECC_ENABLE Enable SPI RAM ECC Found in: Component config > ESP32S3-Specific > CONFIG_ESP32S3_SPIRAM_SUPPORT > SPI RAM config Enable MSPI Error-Correcting Code function when accessing SPIRAM. If enabled, 1/16 of the SPI RAM total size will be reserved for error-correcting code. Default value: · No (disabled) if SPIRAM_MODE_OCT && CONFIG_ESP32S3_SPIRAM_SUPPORT
CONFIG_ESP32S3_TRAX Use TRAX tracing feature Found in: Component config > ESP32S3-Specific The esp32-s3 contains a feature which allows you to trace the execution path the processor has taken through the program. This is stored in a chunk of 32K (16K for single-processor) of memory that cann t be used for general purposes anymore. Disable this if you do not know what this is. Default value: · No (disabled)
CONFIG_ESP32S3_TRAX_TWOBANKS Reserve memory for tracing both pro as well as app cpu execution Found in: Component config > ESP32S3-Specific > CONFIG_ESP32S3_TRAX The esp32-s3 contains a feature which allows you to trace the execution path the processor has taken through the program. This is stored in a chunk of 32K (16K for single-processor) of memory that cann t be used for general purposes anymore. Disable this if you do not know what this is. Default value: · No (disabled) if CONFIG_ESP32S3_TRAX && CONFIG_FREERTOS_UNICORE
CONFIG_ESP32S3_DEBUG_OCDAWARE Make exception and panic handlers JTAG/OCD aware Found in: Component config > ESP32S3-Specific The FreeRTOS panic and unhandled exception handers can detect a JTAG OCD debugger and instead of panicking, have the debugger stop on the offending instruction. Default value: · Yes (enabled)

Espressif Systems

1461

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_ESP32S3_BROWNOUT_DET
Hardware brownout detect & reset
Found in: Component config > ESP32S3-Specific
The ESP32-S3 has a built-in brownout detector which can detect if the voltage is lower than a specific value. If this happens, it will reset the chip in order to prevent unintended behaviour.
Default value: · Yes (enabled)

CONFIG_ESP32S3_BROWNOUT_DET_LVL_SEL
Brownout voltage level
Found in: Component config > ESP32S3-Specific > CONFIG_ESP32S3_BROWNOUT_DET
The brownout detector will reset the chip when the supply voltage is approximately below this level. Note that there may be some variation of brownout voltage level between each ESP3-S3 chip.
#The voltage levels here are estimates, more work needs to be done to figure out the exact voltages #of the brownout threshold levels.
Available options: · 2.44V (ESP32S3_BROWNOUT_DET_LVL_SEL_7) · 2.56V (ESP32S3_BROWNOUT_DET_LVL_SEL_6) · 2.67V (ESP32S3_BROWNOUT_DET_LVL_SEL_5) · 2.84V (ESP32S3_BROWNOUT_DET_LVL_SEL_4) · 2.98V (ESP32S3_BROWNOUT_DET_LVL_SEL_3) · 3.19V (ESP32S3_BROWNOUT_DET_LVL_SEL_2) · 3.30V (ESP32S3_BROWNOUT_DET_LVL_SEL_1)

CONFIG_ESP32S3_TIME_SYSCALL
Timers used for gettimeofday function
Found in: Component config > ESP32S3-Specific
This setting defines which hardware timers are used to implementmgettimeofdaynandmtimenfunctions in C library.
· If both high-resolution and RTC timers are used, timekeeping will continue in deep sleep. Time will be reported at 1 microsecond resolution. This is the default, and the recommended option.
· If only high-resolution timer is used, gettimeofday will provide time at microsecond resolution. Time will not be preserved when going into deep sleep mode.
· If only RTC timer is used, timekeeping will continue in deep sleep, but time will be measured at 6.(6) microsecond resolution. Also the gettimeofday function itself may take longer to run.
· If no timers are used, gettimeofday and time functions return -1 and set errno to ENOSYS. · When RTC is used for timekeeping, two RTC_STORE registers are used to keep time in deep
sleep mode.
Available options: · RTC and high-resolution timer (ESP32S3_TIME_SYSCALL_USE_RTC_FRC1) · RTC (ESP32S3_TIME_SYSCALL_USE_RTC) · High-resolution timer (ESP32S3_TIME_SYSCALL_USE_FRC1) · None (ESP32S3_TIME_SYSCALL_USE_NONE)

CONFIG_ESP32S3_RTC_CLK_SRC RTC clock source Found in: Component config > ESP32S3-Specific Choose which clock is used as RTC clock source.

Espressif Systems

1462

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Available options:

· Internal 150kHz RC oscillator (ESP32S3_RTC_CLK_SRC_INT_RC)

· External 32kHz crystal (ESP32S3_RTC_CLK_SRC_EXT_CRYS)

· External 32kHz oscillator at 32K_XP pin (ESP32S3_RTC_CLK_SRC_EXT_OSC)

· Internal

8MHz

oscillator,

divided

by

256

(~32kHz)

(ESP32S3_RTC_CLK_SRC_INT_8MD256)

CONFIG_ESP32S3_RTC_CLK_CAL_CYCLES
Number of cycles for RTC_SLOW_CLK calibration
Found in: Component config > ESP32S3-Specific
When the startup code initializes RTC_SLOW_CLK, it can perform calibration by comparing the RTC_SLOW_CLK frequency with main XTAL frequency. This option sets the number of RTC_SLOW_CLK cycles measured by the calibration routine. Higher numbers increase calibration precision, which may be important for applications which spend a lot of time in deep sleep. Lower numbers reduce startup time.
When this option is set to 0, clock calibration will not be performed at startup, and approximate clock frequencies will be assumed:
· 150000 Hz if internal RC oscillator is used as clock source. For this use value 1024. · 32768 Hz if the 32k crystal oscillator is used. For this use value 3000 or more. In case more value
will help improve the definition of the launch of the crystal. If the crystal could not start, it will be switched to internal RC.
Range: · from 0 to 27000 if ESP32S3_RTC_CLK_SRC_EXT_CRYS || ESP32S3_RTC_CLK_SRC_EXT_OSC || ESP32S3_RTC_CLK_SRC_INT_8MD256 · from 0 to 32766
Default value: · 3000 if ESP32S3_RTC_CLK_SRC_EXT_CRYS || ESP32S3_RTC_CLK_SRC_EXT_OSC || ESP32S3_RTC_CLK_SRC_INT_8MD256 · 1024

CONFIG_ESP32S3_DEEP_SLEEP_WAKEUP_DELAY
Extra delay in deep sleep wake stub (in us)
Found in: Component config > ESP32S3-Specific
When ESP32S3 exits deep sleep, the CPU and the flash chip are powered on at the same time. CPU will run deep sleep stub first, and then proceed to load code from flash. Some flash chips need sufficient time to pass between power on and first read operation. By default, without any extra delay, this time is approximately 900us, although some flash chip types need more than that.
By default extra delay is set to 2000us. When optimizing startup time for applications which require it, this value may be reduced.
If you are seeing oflash read err, 1000pmessage printed to the console after deep sleep reset, try increasing this value.
Range: · from 0 to 5000
Default value: · 2000
CONFIG_ESP32S3_NO_BLOBS
No Binary Blobs
Found in: Component config > ESP32S3-Specific

Espressif Systems

1463

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

If enabled, this disables the linking of binary libraries in the application build. Note that after enabling this Wi-Fi/Bluetooth will not work.
Default value: · No (disabled) if CONFIG_BT_ENABLED

CONFIG_ESP32S3_RTCDATA_IN_FAST_MEM
Place RTC_DATA_ATTR and RTC_RODATA_ATTR variables into RTC fast memory segment
Found in: Component config > ESP32S3-Specific
This option allows to place .rtc_data and .rtc_rodata sections into RTC fast memory segment to free the slow memory region for ULP programs.
Default value: · No (disabled)

CONFIG_ESP32S3_USE_FIXED_STATIC_RAM_SIZE
Use fixed static RAM size
Found in: Component config > ESP32S3-Specific
If this option is disabled, the DRAM part of the heap starts right after the .bss section, within the dram0_0 region. As a result, adding or removing some static variables will change the available heap size.
If this option is enabled, the DRAM part of the heap starts right after the dram0_0 region, where its length is set with ESP32S3_FIXED_STATIC_RAM_SIZE
Default value: · No (disabled)

CONFIG_ESP32S3_FIXED_STATIC_RAM_SIZE
Fixed Static RAM size
Found in: Component config > ESP32S3-Specific > CONFIG_ESP32S3_USE_FIXED_STATIC_RAM_SIZE
RAM size dedicated for static variables (.data & .bss sections).
Range: · from 0 to 0x34000 if CONFIG_ESP32S3_USE_FIXED_STATIC_RAM_SIZE
Default value: ·o0x10000pif CONFIG_ESP32S3_USE_FIXED_STATIC_RAM_SIZE

ADC-Calibration

Common ESP-related Contains: · CONFIG_ESP_ERR_TO_NAME_LOOKUP

CONFIG_ESP_ERR_TO_NAME_LOOKUP
Enable lookup of error code strings
Found in: Component config > Common ESP-related
Functions esp_err_to_name() and esp_err_to_name_r() return string representations of error codes from a pre-generated lookup table. This option can be used to turn off the use of the look-up table in order to save memory but this comes at the price of sacrificing distinguishable (meaningful) output string representations.

Espressif Systems

1464

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Default value: · Yes (enabled)

Ethernet Contains:
· CONFIG_ETH_USE_OPENETH · CONFIG_ETH_USE_SPI_ETHERNET

CONFIG_ETH_USE_SPI_ETHERNET
Support SPI to Ethernet Module
Found in: Component config > Ethernet
ESP-IDF can also support some SPI-Ethernet modules.
Default value: · Yes (enabled)
Contains:
· CONFIG_ETH_SPI_ETHERNET_DM9051 · CONFIG_ETH_SPI_ETHERNET_KSZ8851SNL · CONFIG_ETH_SPI_ETHERNET_W5500

CONFIG_ETH_SPI_ETHERNET_DM9051 Use DM9051 Found in: Component config > Ethernet > CONFIG_ETH_USE_SPI_ETHERNET DM9051 is a fast Ethernet controller with an SPI interface. Itns also integrated with a 10/100M PHY and MAC. Select this to enable DM9051 driver.

CONFIG_ETH_SPI_ETHERNET_W5500
Use W5500 (MAC RAW)
Found in: Component config > Ethernet > CONFIG_ETH_USE_SPI_ETHERNET
W5500 is a HW TCP/IP embedded Ethernet controller. TCP/IP stack, 10/100 Ethernet MAC and PHY are embedded in a single chip. However the driver in ESP-IDF only enables the RAW MAC mode, making it compatible with the software TCP/IP stack. Say yes to enable W5500 driver.

CONFIG_ETH_SPI_ETHERNET_KSZ8851SNL
Use KSZ8851SNL
Found in: Component config > Ethernet > CONFIG_ETH_USE_SPI_ETHERNET
The KSZ8851SNL is a single-chip Fast Ethernet controller consisting of a 10/100 physical layer transceiver (PHY), a MAC, and a Serial Peripheral Interface (SPI). Select this to enable KSZ8851SNL driver.

CONFIG_ETH_USE_OPENETH Support OpenCores Ethernet MAC (for use with QEMU) Found in: Component config > Ethernet OpenCores Ethernet MAC driver can be used when an ESP-IDF application is executed in QEMU. This driver is not supported when running on a real chip. Default value:

Espressif Systems

1465

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· No (disabled) Contains:
· CONFIG_ETH_OPENETH_DMA_RX_BUFFER_NUM · CONFIG_ETH_OPENETH_DMA_TX_BUFFER_NUM
CONFIG_ETH_OPENETH_DMA_RX_BUFFER_NUM Number of Ethernet DMA Rx buffers Found in: Component config > Ethernet > CONFIG_ETH_USE_OPENETH Number of DMA receive buffers, each buffer is 1600 bytes. Range: · from 1 to 64 if CONFIG_ETH_USE_OPENETH Default value: · 4 if CONFIG_ETH_USE_OPENETH
CONFIG_ETH_OPENETH_DMA_TX_BUFFER_NUM Number of Ethernet DMA Tx buffers Found in: Component config > Ethernet > CONFIG_ETH_USE_OPENETH Number of DMA transmit buffers, each buffer is 1600 bytes. Range: · from 1 to 64 if CONFIG_ETH_USE_OPENETH Default value: · 1 if CONFIG_ETH_USE_OPENETH
Event Loop Library Contains: · CONFIG_ESP_EVENT_LOOP_PROFILING · CONFIG_ESP_EVENT_POST_FROM_ISR
CONFIG_ESP_EVENT_LOOP_PROFILING Enable event loop profiling Found in: Component config > Event Loop Library Enables collections of statistics in the event loop library such as the number of events posted to/recieved by an event loop, number of callbacks involved, number of events dropped to to a full event loop queue, run time of event handlers, and number of times/run time of each event handler. Default value: · No (disabled)
CONFIG_ESP_EVENT_POST_FROM_ISR Support posting events from ISRs Found in: Component config > Event Loop Library Enable posting events from interrupt handlers. Default value: · Yes (enabled)

Espressif Systems

1466

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_ESP_EVENT_POST_FROM_IRAM_ISR
Support posting events from ISRs placed in IRAM
Found in: Component config > Event Loop Library > CONFIG_ESP_EVENT_POST_FROM_ISR
Enable posting events from interrupt handlers placed in IRAM. Enabling this option places API functions esp_event_post and esp_event_post_to in IRAM.
Default value: · Yes (enabled)

GDB Stub Contains: · CONFIG_ESP_GDBSTUB_SUPPORT_TASKS

CONFIG_ESP_GDBSTUB_SUPPORT_TASKS
Enable listing FreeRTOS tasks through GDB Stub
Found in: Component config > GDB Stub
If enabled, GDBStub can supply the list of FreeRTOS tasks to GDB. Thread list can be queried from GDB using minfo threadsncommand. Note that if GDB task lists were corrupted, this feature may not work. If GDBStub fails, try disabling this feature.

CONFIG_ESP_GDBSTUB_MAX_TASKS Maximum number of tasks supported by GDB Stub Found in: Component config > GDB Stub > CONFIG_ESP_GDBSTUB_SUPPORT_TASKS Set the number of tasks which GDB Stub will support. Default value: · 32 if CONFIG_ESP_GDBSTUB_SUPPORT_TASKS

ESP HTTP client Contains:
· CONFIG_ESP_HTTP_CLIENT_ENABLE_BASIC_AUTH · CONFIG_ESP_HTTP_CLIENT_ENABLE_DIGEST_AUTH · CONFIG_ESP_HTTP_CLIENT_ENABLE_HTTPS

CONFIG_ESP_HTTP_CLIENT_ENABLE_HTTPS Enable https Found in: Component config > ESP HTTP client This option will enable https protocol by linking esp-tls library and initializing SSL transport Default value: · Yes (enabled)

CONFIG_ESP_HTTP_CLIENT_ENABLE_BASIC_AUTH
Enable HTTP Basic Authentication
Found in: Component config > ESP HTTP client
This option will enable HTTP Basic Authentication. It is disabled by default as Basic auth uses unencrypted encoding, so it introduces a vulnerability when not using TLS
Default value: · No (disabled)

Espressif Systems

1467

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_ESP_HTTP_CLIENT_ENABLE_DIGEST_AUTH
Enable HTTP Digest Authentication
Found in: Component config > ESP HTTP client
This option will enable HTTP Digest Authentication. It is enabled by default, but use of this configuration is not recommended as the password can be derived from the exchange, so it introduces a vulnerability when not using TLS
Default value: · No (disabled)

HTTP Server Contains:
· CONFIG_HTTPD_PURGE_BUF_LEN · CONFIG_HTTPD_LOG_PURGE_DATA · CONFIG_HTTPD_MAX_REQ_HDR_LEN · CONFIG_HTTPD_MAX_URI_LEN · CONFIG_HTTPD_ERR_RESP_NO_DELAY · CONFIG_HTTPD_WS_SUPPORT

CONFIG_HTTPD_MAX_REQ_HDR_LEN
Max HTTP Request Header Length
Found in: Component config > HTTP Server
This sets the maximum supported size of headers section in HTTP request packet to be processed by the server
Default value: · 512

CONFIG_HTTPD_MAX_URI_LEN Max HTTP URI Length Found in: Component config > HTTP Server This sets the maximum supported size of HTTP request URI to be processed by the server Default value: · 512

CONFIG_HTTPD_ERR_RESP_NO_DELAY
Use TCP_NODELAY socket option when sending HTTP error responses
Found in: Component config > HTTP Server
Using TCP_NODEALY socket option ensures that HTTP error response reaches the client before the underlying socket is closed. Please note that turning this off may cause multiple test failures
Default value: · Yes (enabled)

CONFIG_HTTPD_PURGE_BUF_LEN Length of temporary buffer for purging data Found in: Component config > HTTP Server This sets the size of the temporary buffer used to receive and discard any remaining data that is received from the HTTP client in the request, but not processed as part of the server HTTP request handler.

Espressif Systems

1468

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

If the remaining data is larger than the available buffer size, the buffer will be filled in multiple iterations. The buffer should be small enough to fit on the stack, but large enough to avoid excessive iterations.
Default value: · 32

CONFIG_HTTPD_LOG_PURGE_DATA
Log purged content data at Debug level
Found in: Component config > HTTP Server
Enabling this will log discarded binary HTTP request data at Debug level. For large content data this may not be desirable as it will clutter the log.
Default value: · No (disabled)

CONFIG_HTTPD_WS_SUPPORT WebSocket server support Found in: Component config > HTTP Server This sets the WebSocket server support. Default value: · No (disabled)

ESP HTTPS OTA Contains: · CONFIG_OTA_ALLOW_HTTP

CONFIG_OTA_ALLOW_HTTP
Allow HTTP for OTA (WARNING: ONLY FOR TESTING PURPOSE, READ HELP)
Found in: Component config > ESP HTTPS OTA
It is highly recommended to keep HTTPS (along with server certificate validation) enabled. Enabling this option comes with potential risk of: - Non-encrypted communication channel with server - Accepting firmware upgrade image from server with fake identity
Default value: · No (disabled)

ESP HTTPS server Contains: · CONFIG_ESP_HTTPS_SERVER_ENABLE

CONFIG_ESP_HTTPS_SERVER_ENABLE Enable ESP_HTTPS_SERVER component Found in: Component config > ESP HTTPS server Enable ESP HTTPS server component

Hardware Settings Contains:
· MAC Config · RTC Clock Config · Sleep Config

Espressif Systems

1469

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
MAC Config Contains: · CONFIG_ESP32S3_UNIVERSAL_MAC_ADDRESSES
CONFIG_ESP32S3_UNIVERSAL_MAC_ADDRESSES Number of universally administered (by IEEE) MAC address Found in: Component config > Hardware Settings > MAC Config Configure the number of universally administered (by IEEE) MAC addresses. During initialization, MAC addresses for each network interface are generated or derived from a single base MAC address. If the number of universal MAC addresses is four, all four interfaces (WiFi station, WiFi softap, Bluetooth and Ethernet) receive a universally administered MAC address. These are generated sequentially by adding 0, 1, 2 and 3 (respectively) to the final octet of the base MAC address. If the number of universal MAC addresses is two, only two interfaces (WiFi station and Bluetooth) receive a universally administered MAC address. These are generated sequentially by adding 0 and 1 (respectively) to the base MAC address. The remaining two interfaces (WiFi softap and Ethernet) receive local MAC addresses. These are derived from the universal WiFi station and Bluetooth MAC addresses, respectively. When using the default (Espressif-assigned) base MAC address, either setting can be used. When using a custom universal MAC address range, the correct setting will depend on the allocation of MAC addresses in this range (either 2 or 4 per device.) Available options: · Two (ESP32S3_UNIVERSAL_MAC_ADDRESSES_TWO) · Four (ESP32S3_UNIVERSAL_MAC_ADDRESSES_FOUR)
Sleep Config Contains: · CONFIG_ESP_SLEEP_FLASH_LEAKAGE_WORKAROUND · CONFIG_ESP_SLEEP_GPIO_RESET_WORKAROUND · CONFIG_ESP_SLEEP_POWER_DOWN_FLASH · CONFIG_ESP_SLEEP_PSRAM_LEAKAGE_WORKAROUND
CONFIG_ESP_SLEEP_POWER_DOWN_FLASH Power down flash in light sleep when there is no SPIRAM Found in: Component config > Hardware Settings > Sleep Config If enabled, chip will try to power down flash as part of esp_light_sleep_start(), which costs more time when chip wakes up. Can only be enabled if there is no SPIRAM configured. This option will in fact consider VDD_SDIO auto power value (ESP_PD_OPTION_AUTO) as OFF. Also, it is possible to force a power domain to stay ON during light sleep by using esp_sleep_pd_config() function. Default value: · Yes (enabled)
CONFIG_ESP_SLEEP_GPIO_RESET_WORKAROUND light sleep GPIO reset workaround Found in: Component config > Hardware Settings > Sleep Config esp32c3 and esp32s3 will reset at wake-up if GPIO is received a small electrostatic pulse during light sleep, with specific condition · GPIO needs to be configured as input-mode only · The pin receives a small electrostatic pulse, and reset occurs when the pulse voltage is higher than 6V

Espressif Systems

1470

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
For GPIO set to input mode only, it is not a good practice to leave it open/floating, The hardware design needs to controlled it with determined supply or ground voltage is necessary. This option provides a software workaround for this issue. Configure to isolate all GPIO pins in sleep state. Default value:
· Yes (enabled)
CONFIG_ESP_SLEEP_PSRAM_LEAKAGE_WORKAROUND PSRAM leakage current workaround in light sleep Found in: Component config > Hardware Settings > Sleep Config When the CS pin of SPIRAM is not pulled up, the sleep current will increase during light sleep. If the CS pin of SPIRAM has an external pull-up, you do not need to select this option, otherwise, you should enable this option.
CONFIG_ESP_SLEEP_FLASH_LEAKAGE_WORKAROUND Flash leakage current workaround in light sleep Found in: Component config > Hardware Settings > Sleep Config When the CS pin of Flash is not pulled up, the sleep current will increase during light sleep. If the CS pin of Flash has an external pull-up, you do not need to select this option, otherwise, you should enable this option.
RTC Clock Config Contains: · CONFIG_RTC_CLOCK_BBPLL_POWER_ON_WITH_USB
CONFIG_RTC_CLOCK_BBPLL_POWER_ON_WITH_USB Keep BBPLL clock always work Found in: Component config > Hardware Settings > RTC Clock Config When the chip goes sleep or software reset, the clock source would change to XTAL and switch off the BBPLL clock for saving power. However, this might make the USB_SERIAL_JTAG down which depends on BBPLL as its unique clock source. Therefore, this is used for keeping bbpll clock always on when USB_SERIAL_JTAG PORT is using. If you want to use USB_SERIAL_JTAG under sw_reset case or sleep-wakeup case, you shoule select this option. But be aware that this might increase the power consumption. Default value: · Yes (enabled)
LCD and Touch Panel Contains: · LCD Peripheral Configuration
LCD Peripheral Configuration Contains: · CONFIG_LCD_PANEL_IO_FORMAT_BUF_SIZE

Espressif Systems

1471

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_LCD_PANEL_IO_FORMAT_BUF_SIZE LCD panel io format buffer size Found in: Component config > LCD and Touch Panel > LCD Peripheral Configuration LCD driver allocates an internal buffer to transform the data into a proper format, because of the endian order mismatch. This option is to set the size of the buffer, in bytes. Default value: · 32
ESP NETIF Adapter Contains: · CONFIG_ESP_NETIF_TCPIP_ADAPTER_COMPATIBLE_LAYER · CONFIG_ESP_NETIF_L2_TAP · CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL · CONFIG_ESP_NETIF_USE_TCPIP_STACK_LIB
CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL IP Address lost timer interval (seconds) Found in: Component config > ESP NETIF Adapter The value of 0 indicates the IP lost timer is disabled, otherwise the timer is enabled. The IP address may be lost because of some reasons, e.g. when the station disconnects from soft-AP, or when DHCP IP renew fails etc. If the IP lost timer is enabled, it will be started everytime the IP is lost. Event SYSTEM_EVENT_STA_LOST_IP will be raised if the timer expires. The IP lost timer is stopped if the station get the IP again before the timer expires. Range: · from 0 to 65535 Default value: · 120
CONFIG_ESP_NETIF_USE_TCPIP_STACK_LIB TCP/IP Stack Library Found in: Component config > ESP NETIF Adapter Choose the TCP/IP Stack to work, for example, LwIP, uIP, etc. Available options: · LwIP (ESP_NETIF_TCPIP_LWIP) lwIP is a small independent implementation of the TCP/IP protocol suite. · Loopback (ESP_NETIF_LOOPBACK) Dummy implementation of esp-netif functionality which connects driver transmit to receive function. This option is for testing purpose only
CONFIG_ESP_NETIF_TCPIP_ADAPTER_COMPATIBLE_LAYER Enable backward compatible tcpip_adapter interface Found in: Component config > ESP NETIF Adapter Backward compatible interface to tcpip_adapter is enabled by default to support legacy TCP/IP stack initialisation code. Disable this option to use only esp-netif interface. Default value: · Yes (enabled)

Espressif Systems

1472

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_ESP_NETIF_L2_TAP Enable netif L2 TAP support Found in: Component config > ESP NETIF Adapter A user program can read/write link layer (L2) frames from/to ESP TAP device. The ESP TAP device can be currently associated only with Ethernet physical interfaces.

CONFIG_ESP_NETIF_L2_TAP_MAX_FDS
Maximum number of opened L2 TAP File descriptors
Found in: Component config > ESP NETIF Adapter > CONFIG_ESP_NETIF_L2_TAP
Maximum number of opened File descriptors (FDns) associated with ESP TAP device. ESP TAP FDn s take up a certain amount of memory, and allowing fewer FDns to be opened at the same time conserves memory.
Range: · from 1 to 10 if CONFIG_ESP_NETIF_L2_TAP
Default value: · 5 if CONFIG_ESP_NETIF_L2_TAP

CONFIG_ESP_NETIF_L2_TAP_RX_QUEUE_SIZE
Size of L2 TAP Rx queue
Found in: Component config > ESP NETIF Adapter > CONFIG_ESP_NETIF_L2_TAP
Maximum number of frames queued in opened File descriptor. Once the queue is full, the newly arriving frames are dropped until the queue has enough room to accept incoming traffic (Tail Drop queue management).
Range: · from 1 to 100 if CONFIG_ESP_NETIF_L2_TAP
Default value: · 20 if CONFIG_ESP_NETIF_L2_TAP

PHY Contains:
· CONFIG_ESP_PHY_ENABLE_USB · CONFIG_ESP_PHY_MAX_WIFI_TX_POWER · CONFIG_ESP_PHY_MAC_BB_PD · CONFIG_ESP_PHY_REDUCE_TX_POWER · CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE · CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION

CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE
Store phy calibration data in NVS
Found in: Component config > PHY
If this option is enabled, NVS will be initialized and calibration data will be loaded from there. PHY calibration will be skipped on deep sleep wakeup. If calibration data is not found, full calibration will be performed and stored in NVS. Normally, only partial calibration will be performed. If this option is disabled, full calibration will be performed.
If itns easy that your board calibrate bad data, choosemnn. Two cases for example, you should choose mnn: 1.If your board is easy to be booted up with antenna disconnected. 2.Because of your board design,
each time when you do calibration, the result are too unstable. If unsure, choose myn.
Default value:

Espressif Systems

1473

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· Yes (enabled)
CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION Use a partition to store PHY init data Found in: Component config > PHY If enabled, PHY init data will be loaded from a partition. When using a custom partition table, make sure that PHY data partition is included (type:mdatan, subtype:mphyn). With default partition tables, this is done automatically. If PHY init data is stored in a partition, it has to be flashed there, otherwise runtime error will occur. If this option is not enabled, PHY init data will be embedded into the application binary. If unsure, choose mnn. Default value: · No (disabled)
Contains: · CONFIG_ESP_PHY_DEFAULT_INIT_IF_INVALID · CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN
CONFIG_ESP_PHY_DEFAULT_INIT_IF_INVALID Reset default PHY init data if invalid Found in: Component config > PHY > CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION If enabled, PHY init data will be restored to default if it cannot be verified successfully to avoid endless bootloops. If unsure, choose mnn. Default value: · No (disabled) if CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION
CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN Support multiple PHY init data bin Found in: Component config > PHY > CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION If enabled, the corresponding PHY init data type can be automatically switched according to the country code. Chinans PHY init data bin is used by default. Can be modified by country information in API esp_wifi_set_country(). The priority of switching the PHY init data type is: 1. Country configured by API esp_wifi_set_country() and the parameter policy is WIFI_COUNTRY_POLICY_MANUAL. 2. Country notified by the connected AP. 3. Country configured by API esp_wifi_set_country() and the parameter policy is WIFI_COUNTRY_POLICY_AUTO. Default value: · No (disabled) if CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION && CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION
CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN_EMBED Support embedded multiple phy init data bin to app bin Found in: Component config > PHY > CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION > CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN If enabled, multiple phy init data bin will embedded into app bin If not enabled, multiple phy init data bin will still leave alone, and need to be flashed by users.

Espressif Systems

1474

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Default value: · No (disabled) if CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN && CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION
CONFIG_ESP_PHY_INIT_DATA_ERROR Terminate operation when PHY init data error Found in: Component config > PHY > CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION > CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN If enabled, when an error occurs while the PHY init data is updated, the program will terminate and restart. If not enabled, the PHY init data will not be updated when an error occurs. Default value: · No (disabled) if CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN && CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION
CONFIG_ESP_PHY_MAX_WIFI_TX_POWER Max WiFi TX power (dBm) Found in: Component config > PHY Set maximum transmit power for WiFi radio. Actual transmit power for high data rates may be lower than this setting. Range: · from 10 to 20 Default value: · 20
CONFIG_ESP_PHY_MAC_BB_PD Power down MAC and baseband of Wi-Fi and Bluetooth when PHY is disabled Found in: Component config > PHY If enabled, the MAC and baseband of Wi-Fi and Bluetooth will be powered down when PHY is disabled. Enabling this setting reduces power consumption by a small amount but increases RAM use by approximately 4 KB(Wi-Fi only), 2 KB(Bluetooth only) or 5.3 KB(Wi-Fi + Bluetooth). Default value: · No (disabled) if CONFIG_FREERTOS_USE_TICKLESS_IDLE
CONFIG_ESP_PHY_REDUCE_TX_POWER Reduce PHY TX power when brownout reset Found in: Component config > PHY When brownout reset occurs, reduce PHY TX power to keep the code running. Default value: · Yes (enabled) if ESP32_BROWNOUT_DET
CONFIG_ESP_PHY_ENABLE_USB Enable USB when phy init Found in: Component config > PHY When using USB Serial/JTAG/OTG/CDC, PHY should enable USB, otherwise USB module can not work properly. Notice: Enabling this configuration option will slightly impact wifi performance.

Espressif Systems

1475

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Default value: · Yes (enabled) · No (disabled)

Power Management Contains:
· CONFIG_PM_SLP_DISABLE_GPIO · CONFIG_PM_POWER_DOWN_CPU_IN_LIGHT_SLEEP · CONFIG_PM_SLP_IRAM_OPT · CONFIG_PM_RTOS_IDLE_OPT · CONFIG_PM_ENABLE

CONFIG_PM_ENABLE
Support for power management
Found in: Component config > Power Management
If enabled, application is compiled with support for power management. This option has run-time overhead (increased interrupt latency, longer time to enter idle state), and it also reduces accuracy of RTOS ticks and timers used for timekeeping. Enable this option if application uses power management APIs.
Default value: · No (disabled)

CONFIG_PM_DFS_INIT_AUTO
Enable dynamic frequency scaling (DFS) at startup
Found in: Component config > Power Management > CONFIG_PM_ENABLE
If enabled, startup code configures dynamic frequency scaling. Max CPU frequency is set to DEFAULT_CPU_FREQ_MHZ setting, min frequency is set to XTAL frequency. If disabled, DFS will not be active until the application configures it using esp_pm_configure function.
Default value: · No (disabled) if CONFIG_PM_ENABLE

CONFIG_PM_PROFILING
Enable profiling counters for PM locks
Found in: Component config > Power Management > CONFIG_PM_ENABLE
If enabled, esp_pm_* functions will keep track of the amount of time each of the power management locks has been held, and esp_pm_dump_locks function will print this information. This feature can be used to analyze which locks are preventing the chip from going into a lower power state, and see what time the chip spends in each power saving mode. This feature does incur some run-time overhead, so should typically be disabled in production builds.
Default value: · No (disabled) if CONFIG_PM_ENABLE

CONFIG_PM_TRACE
Enable debug tracing of PM using GPIOs
Found in: Component config > Power Management > CONFIG_PM_ENABLE
If enabled, some GPIOs will be used to signal events such as RTOS ticks, frequency switching, entry/exit from idle state. Refer to pm_trace.c file for the list of GPIOs. This feature is intended to be used when analyzing/debugging behavior of power management implementation, and should be kept disabled in applications.

Espressif Systems

1476

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Default value: · No (disabled) if CONFIG_PM_ENABLE

CONFIG_PM_SLP_IRAM_OPT
Put lightsleep related codes in internal RAM
Found in: Component config > Power Management
If enabled, about 1.8KB of lightsleep related source code would be in IRAM and chip would sleep longer for 760us at most each time. This feature is intended to be used when lower power consumption is needed while there is enough place in IRAM to place source code.

CONFIG_PM_RTOS_IDLE_OPT
Put RTOS IDLE related codes in internal RAM
Found in: Component config > Power Management
If enabled, about 260B of RTOS_IDLE related source code would be in IRAM and chip would sleep longer for 40us at most each time. This feature is intended to be used when lower power consumption is needed while there is enough place in IRAM to place source code.

CONFIG_PM_SLP_DISABLE_GPIO
Disable all GPIO when chip at sleep
Found in: Component config > Power Management
This feature is intended to disable all GPIO pins at automantic sleep to get a lower power mode. If enabled, chips will disable all GPIO pins at automantic sleep to reduce about 200~300 uA current. If you want to specifically use some pins normally as chip wakes when chip sleeps, you can call mgpio_sleep_sel_disnto disable this feature on those pins. You can also keep this feature on and call mgpio_sleep_set_directionnand mgpio_sleep_set_pull_modento have a different GPIO configuration at sleep. Waring: If you want to enable this option on ESP32, you should enable GPIO_ESP32_SUPPORT_SWITCH_SLP_PULL at first, otherwise you will not be able to switch pullup/pulldown mode.

CONFIG_PM_POWER_DOWN_CPU_IN_LIGHT_SLEEP
Power down CPU in light sleep
Found in: Component config > Power Management
If enabled, the CPU will be powered down in light sleep. On esp32c3 soc, enabling this option will consume 1.68 KB of internal RAM and will reduce sleep current consumption by about 100 uA. On esp32s3 soc, enabling this option will consume 8.58 KB of internal RAM and will reduce sleep current consumption by about 650 uA.
Default value: · Yes (enabled)

CONFIG_PM_POWER_DOWN_TAGMEM_IN_LIGHT_SLEEP

Power down I/D-cache tag memory in light sleep

Found in:

Component config > Power Management > CON-

FIG_PM_POWER_DOWN_CPU_IN_LIGHT_SLEEP

If enabled, the I/D-cache tag memory will be retained in light sleep. Depending on the the cache configuration, if this option is enabled, it will consume up to 9 KB of internal RAM.

Default value:

Espressif Systems

1477

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· Yes (enabled)
ESP System Settings Contains:
· CONFIG_ESP_SYSTEM_RTC_EXT_XTAL_BOOTSTRAP_CYCLES · CONFIG_ESP_CONSOLE_UART · CONFIG_ESP_CONSOLE_SECONDARY · CONFIG_ESP_CONSOLE_USB_CDC_SUPPORT_ETS_PRINTF · CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP · CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE · CONFIG_ESP_TASK_WDT · CONFIG_ESP_XT_WDT · CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL · CONFIG_ESP_INT_WDT · CONFIG_ESP_MAIN_TASK_AFFINITY · CONFIG_ESP_MAIN_TASK_STACK_SIZE · Memory protection · CONFIG_ESP_MINIMAL_SHARED_STACK_SIZE · CONFIG_ESP_DEBUG_STUBS_ENABLE · CONFIG_ESP_SYSTEM_PANIC · CONFIG_ESP_PANIC_HANDLER_IRAM · CONFIG_ESP_CONSOLE_USB_CDC_RX_BUF_SIZE · CONFIG_ESP_SYSTEM_EVENT_QUEUE_SIZE · CONFIG_ESP_CONSOLE_UART_BAUDRATE · CONFIG_ESP_CONSOLE_UART_NUM · CONFIG_ESP_CONSOLE_UART_RX_GPIO · CONFIG_ESP_CONSOLE_UART_TX_GPIO
CONFIG_ESP_SYSTEM_PANIC
Panic handler behaviour
Found in: Component config > ESP System Settings
If FreeRTOS detects unexpected behaviour or an unhandled exception, the panic handler is invoked. Configure the panic handlerns action here.
Available options: · Print registers and halt (ESP_SYSTEM_PANIC_PRINT_HALT) Outputs the relevant registers over the serial port and halt the processor. Needs a manual reset to restart. · Print registers and reboot (ESP_SYSTEM_PANIC_PRINT_REBOOT) Outputs the relevant registers over the serial port and immediately reset the processor. · Silent reboot (ESP_SYSTEM_PANIC_SILENT_REBOOT) Just resets the processor without outputting anything · GDBStub on panic (ESP_SYSTEM_PANIC_GDBSTUB) Invoke gdbstub on the serial port, allowing for gdb to attach to it to do a postmortem of the crash. · GDBStub at runtime (ESP_SYSTEM_GDBSTUB_RUNTIME) Invoke gdbstub on the serial port, allowing for gdb to attach to it and to do a debug on runtime. This feature will switch system to single core mode.
CONFIG_ESP_SYSTEM_RTC_EXT_XTAL_BOOTSTRAP_CYCLES
Bootstrap cycles for external 32kHz crystal
Found in: Component config > ESP System Settings

Espressif Systems

1478

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
To reduce the startup time of an external RTC crystal, we bootstrap it with a 32kHz square wave for a fixed number of cycles. Setting 0 will disable bootstrapping (if disabled, the crystal may take longer to start up or fail to oscillate under some conditions). If this value is too high, a faulty crystal may initially start and then fail. If this value is too low, an otherwise good crystal may not start. To accurately determine if the crystal has started, set a largeroNumber of cycles for RTC_SLOW_CLK calibrationp(about 3000).
CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP Enable RTC fast memory for dynamic allocations Found in: Component config > ESP System Settings This config option allows to add RTC fast memory region to system heap with capability similar to that of DRAM region but without DMA. This memory will be consumed first per heap initialization order by early startup services and scheduler related code. Speed wise RTC fast memory operates on APB clock and hence does not have much performance impact. Default value: · Yes (enabled)
Memory protection Contains: · CONFIG_ESP_SYSTEM_MEMPROT_FEATURE
CONFIG_ESP_SYSTEM_MEMPROT_FEATURE Enable memory protection Found in: Component config > ESP System Settings > Memory protection If enabled, the permission control module watches all the memory access and fires the panic handler if a permission violation is detected. This feature automatically splits the SRAM memory into data and instruction segments and sets Read/Execute permissions for the instruction part (below given splitting address) and Read/Write permissions for the data part (above the splitting address). The memory protection is effective on all access through the IRAM0 and DRAM0 buses.
CONFIG_ESP_SYSTEM_MEMPROT_FEATURE_LOCK Lock memory protection settings Found in: Component config > ESP System Settings > Memory protection > CONFIG_ESP_SYSTEM_MEMPROT_FEATURE Once locked, memory protection settings cannot be changed anymore. The lock is reset only on the chip startup. Default value: · Yes (enabled) if CONFIG_ESP_SYSTEM_MEMPROT_FEATURE
CONFIG_ESP_SYSTEM_EVENT_QUEUE_SIZE System event queue size Found in: Component config > ESP System Settings Config system event queue size in different application. Default value: · 32

Espressif Systems

1479

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE Event loop task stack size Found in: Component config > ESP System Settings Config system event task stack size in different application. Default value: · 2304
CONFIG_ESP_MAIN_TASK_STACK_SIZE Main task stack size Found in: Component config > ESP System Settings Configure theomain taskpstack size. This is the stack of the task which calls app_main(). If app_main() returns then this task is deleted and its stack memory is freed. Default value: · 3584
CONFIG_ESP_MAIN_TASK_AFFINITY Main task core affinity Found in: Component config > ESP System Settings Configure the omain taskpcore affinity. This is the used core of the task which calls app_main(). If app_main() returns then this task is deleted. Available options: · CPU0 (ESP_MAIN_TASK_AFFINITY_CPU0) · CPU1 (ESP_MAIN_TASK_AFFINITY_CPU1) · No affinity (ESP_MAIN_TASK_AFFINITY_NO_AFFINITY)
CONFIG_ESP_MINIMAL_SHARED_STACK_SIZE Minimal allowed size for shared stack Found in: Component config > ESP System Settings Minimal value of size, in bytes, accepted to execute a expression with shared stack. Default value: · 2048
CONFIG_ESP_CONSOLE_UART Channel for console output Found in: Component config > ESP System Settings Select where to send console output (through stdout and stderr). · Default is to use UART0 on pre-defined GPIOs. · If oCustompis selected, UART0 or UART1 can be chosen, and any pins can be selected. · If oNonepis selected, there will be no console output on any UART, except for initial output from ROM bootloader. This ROM output can be suppressed by GPIO strapping or EFUSE, refer to chip datasheet for details. · On chips with USB OTG peripheral,oUSB CDCpoption redirects output to the CDC port. This option uses the CDC driver in the chip ROM. This option is incompatible with TinyUSB stack. · On chips with an USB serial/JTAG debug controller, selecting the option for that redirects output to the CDC/ACM (serial port emulation) component of that device.

Espressif Systems

1480

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Available options: · Default: UART0 (ESP_CONSOLE_UART_DEFAULT) · USB CDC (ESP_CONSOLE_USB_CDC) · USB Serial/JTAG Controller (ESP_CONSOLE_USB_SERIAL_JTAG) · Custom UART (ESP_CONSOLE_UART_CUSTOM) · None (ESP_CONSOLE_NONE)
CONFIG_ESP_CONSOLE_SECONDARY
Channel for console secondary output
Found in: Component config > ESP System Settings
This secondary option supports output through other specific port like USB_SERIAL_JTAG when UART0 port as a primary is selected but not connected. This secondary output currently only supports non-blocking mode without using REPL. If you want to output in blocking mode with REPL or input through this secondary port, please change the primary config to this port in Channel for console output menu.
Available options: · No secondary console (ESP_CONSOLE_SECONDARY_NONE) · USB_SERIAL_JTAG PORT (ESP_CONSOLE_SECONDARY_USB_SERIAL_JTAG) This option supports output through USB_SERIAL_JTAG port when the UART0 port is not connected. The output currently only supports non-blocking mode without using the console. If you want to output in blocking mode with REPL or input through USB_SERIAL_JTAG port, please change the primary config to ESP_CONSOLE_USB_SERIAL_JTAG above.
CONFIG_ESP_CONSOLE_UART_NUM
UART peripheral to use for console output (0-1)
Found in: Component config > ESP System Settings
This UART peripheral is used for console output from the ESP-IDF Bootloader and the app.
If the configuration is different in the Bootloader binary compared to the app binary, UART is reconfigured after the bootloader exits and the app starts.
Due to an ESP32 ROM bug, UART2 is not supported for console output via esp_rom_printf.
Available options: · UART0 (ESP_CONSOLE_UART_CUSTOM_NUM_0) · UART1 (ESP_CONSOLE_UART_CUSTOM_NUM_1)
CONFIG_ESP_CONSOLE_UART_TX_GPIO
UART TX on GPIO#
Found in: Component config > ESP System Settings
This GPIO is used for console UART TX output in the ESP-IDF Bootloader and the app (including boot log output and default standard output and standard error of the app).
If the configuration is different in the Bootloader binary compared to the app binary, UART is reconfigured after the bootloader exits and the app starts.
Range: · from 0 to 46 if ESP_CONSOLE_UART_CUSTOM
Default value: · 43 if ESP_CONSOLE_UART_CUSTOM

Espressif Systems

1481

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_ESP_CONSOLE_UART_RX_GPIO
UART RX on GPIO#
Found in: Component config > ESP System Settings
This GPIO is used for UART RX input in the ESP-IDF Bootloader and the app (including default default standard input of the app).
Note: The default ESP-IDF Bootloader configures this pin but doesnnt read anything from the UART.
If the configuration is different in the Bootloader binary compared to the app binary, UART is reconfigured after the bootloader exits and the app starts.
Range: · from 0 to 46 if ESP_CONSOLE_UART_CUSTOM
Default value: · 44 if ESP_CONSOLE_UART_CUSTOM
CONFIG_ESP_CONSOLE_UART_BAUDRATE
UART console baud rate
Found in: Component config > ESP System Settings
This baud rate is used by both the ESP-IDF Bootloader and the app (including boot log output and default standard input/output/error of the app).
The appns maximum baud rate depends on the UART clock source. If Power Management is disabled, the UART clock source is the APB clock and all baud rates in the available range will be sufficiently accurate. If Power Management is enabled, REF_TICK clock source is used so the baud rate is divided from 1MHz. Baud rates above 1Mbps are not possible and values between 500Kbps and 1Mbps may not be accurate.
If the configuration is different in the Bootloader binary compared to the app binary, UART is reconfigured after the bootloader exits and the app starts.
Range: · from 1200 to 4000000 if CONFIG_PM_ENABLE · from 1200 to 1000000 if CONFIG_PM_ENABLE
Default value: · 115200
CONFIG_ESP_CONSOLE_USB_CDC_RX_BUF_SIZE
Size of USB CDC RX buffer
Found in: Component config > ESP System Settings
Set the size of USB CDC RX buffer. Increase the buffer size if your application is often receiving data over USB CDC.
Range: · from 4 to 16384 if ESP_CONSOLE_USB_CDC
Default value: · 64 if ESP_CONSOLE_USB_CDC
CONFIG_ESP_CONSOLE_USB_CDC_SUPPORT_ETS_PRINTF
Enable esp_rom_printf / ESP_EARLY_LOG via USB CDC
Found in: Component config > ESP System Settings
If enabled, esp_rom_printf and ESP_EARLY_LOG output will also be sent over USB CDC. Disabling this option saves about 1kB or RAM.

Espressif Systems

1482

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Default value: · No (disabled) if ESP_CONSOLE_USB_CDC

CONFIG_ESP_INT_WDT
Interrupt watchdog
Found in: Component config > ESP System Settings
This watchdog timer can detect if the FreeRTOS tick interrupt has not been called for a certain time, either because a task turned off interrupts and did not turn them on for a long time, or because an interrupt handler did not return. It will try to invoke the panic handler first and failing that reset the SoC.
Default value: · Yes (enabled)

CONFIG_ESP_INT_WDT_TIMEOUT_MS
Interrupt watchdog timeout (ms)
Found in: Component config > ESP System Settings > CONFIG_ESP_INT_WDT
The timeout of the watchdog, in miliseconds. Make this higher than the FreeRTOS tick rate.
Range: · from 10 to 10000
Default value: · 300 if ESP32_SPIRAM_SUPPORT && CONFIG_ESP_INT_WDT · 800 if ESP32_SPIRAM_SUPPORT && CONFIG_ESP_INT_WDT

CONFIG_ESP_INT_WDT_CHECK_CPU1 Also watch CPU1 tick interrupt Found in: Component config > ESP System Settings > CONFIG_ESP_INT_WDT Also detect if interrupts on CPU 1 are disabled for too long. Default value: · Yes (enabled) if CONFIG_ESP_INT_WDT && CONFIG_FREERTOS_UNICORE

CONFIG_ESP_TASK_WDT
Initialize Task Watchdog Timer on startup
Found in: Component config > ESP System Settings
The Task Watchdog Timer can be used to make sure individual tasks are still running. Enabling this option will cause the Task Watchdog Timer to be initialized automatically at startup. The Task Watchdog timer can be initialized after startup as well (see Task Watchdog Timer API Reference)
Default value: · Yes (enabled)

CONFIG_ESP_TASK_WDT_PANIC
Invoke panic handler on Task Watchdog timeout
Found in: Component config > ESP System Settings > CONFIG_ESP_TASK_WDT
If this option is enabled, the Task Watchdog Timer will be configured to trigger the panic handler when it times out. This can also be configured at run time (see Task Watchdog Timer API Reference)
Default value: · No (disabled)

Espressif Systems

1483

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_ESP_TASK_WDT_TIMEOUT_S Task Watchdog timeout period (seconds) Found in: Component config > ESP System Settings > CONFIG_ESP_TASK_WDT Timeout period configuration for the Task Watchdog Timer in seconds. This is also configurable at run time (see Task Watchdog Timer API Reference) Range: · from 1 to 60 Default value: ·5
CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0 Watch CPU0 Idle Task Found in: Component config > ESP System Settings > CONFIG_ESP_TASK_WDT If this option is enabled, the Task Watchdog Timer will watch the CPU0 Idle Task. Having the Task Watchdog watch the Idle Task allows for detection of CPU starvation as the Idle Task not being called is usually a symptom of CPU starvation. Starvation of the Idle Task is detrimental as FreeRTOS household tasks depend on the Idle Task getting some runtime every now and then. Default value: · Yes (enabled)
CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1 Watch CPU1 Idle Task Found in: Component config > ESP System Settings > CONFIG_ESP_TASK_WDT If this option is enabled, the Task Wtachdog Timer will wach the CPU1 Idle Task. Default value: · Yes (enabled) if CONFIG_ESP_TASK_WDT && CONFIG_FREERTOS_UNICORE
CONFIG_ESP_XT_WDT Initialize XTAL32K watchdog timer on startup Found in: Component config > ESP System Settings This watchdog timer can detect oscillation failure of the XTAL32K_CLK. When such a failure is detected the hardware can be set up to automatically switch to BACKUP32K_CLK and generate an interrupt.
CONFIG_ESP_XT_WDT_TIMEOUT XTAL32K watchdog timeout period Found in: Component config > ESP System Settings > CONFIG_ESP_XT_WDT Timeout period configuration for the XTAL32K watchdog timer based on RTC_CLK. Range: · from 1 to 255 if CONFIG_ESP_XT_WDT Default value: · 200 if CONFIG_ESP_XT_WDT

Espressif Systems

1484

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_ESP_XT_WDT_BACKUP_CLK_ENABLE
Automatically switch to BACKUP32K_CLK when timer expires
Found in: Component config > ESP System Settings > CONFIG_ESP_XT_WDT
Enable this to automatically switch to BACKUP32K_CLK as the source of RTC_SLOW_CLK when the watchdog timer expires.
Default value: · Yes (enabled) if CONFIG_ESP_XT_WDT

CONFIG_ESP_PANIC_HANDLER_IRAM
Place panic handler code in IRAM
Found in: Component config > ESP System Settings
If this option is disabled (default), the panic handler code is placed in flash not IRAM. This means that if ESP-IDF crashes while flash cache is disabled, the panic handler will automatically re-enable flash cache before running GDB Stub or Core Dump. This adds some minor risk, if the flash cache status is also corrupted during the crash.
If this option is enabled, the panic handler code (including required UART functions) is placed in IRAM. This may be necessary to debug some complex issues with crashes while flash cache is disabled (for example, when writing to SPI flash) or when flash cache is corrupted when an exception is triggered.
Default value: · No (disabled)

CONFIG_ESP_DEBUG_STUBS_ENABLE

OpenOCD debug stubs

Found in: Component config > ESP System Settings

Debug stubs are used by OpenOCD to execute pre-compiled onboard code which does some useful debugging stuff, e.g. GCOV data dump.

Default value:

·oCOMPILER_OPTIMIZATION_LEVEL_DEBUGpif

ESP32_TRAX

&&

ESP32S2_TRAX && CONFIG_ESP32S3_TRAX

CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL
Interrupt level to use for Interrupt Watchdog and other system checks
Found in: Component config > ESP System Settings
Interrupt level to use for Interrupt Watchdog and other system checks.
Available options: · Level 5 interrupt (ESP_SYSTEM_CHECK_INT_LEVEL_5) Using level 5 interrupt for Interrupt Watchdog and other system checks. · Level 4 interrupt (ESP_SYSTEM_CHECK_INT_LEVEL_4) Using level 4 interrupt for Interrupt Watchdog and other system checks.

IPC (Inter-Processor Call) Contains:
· CONFIG_ESP_IPC_TASK_STACK_SIZE · CONFIG_ESP_IPC_USES_CALLERS_PRIORITY

Espressif Systems

1485

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_ESP_IPC_TASK_STACK_SIZE Inter-Processor Call (IPC) task stack size Found in: Component config > IPC (Inter-Processor Call) Configure the IPC tasks stack size. An IPC task runs on each core (in dual core mode), and allows for cross-core function calls. See IPC documentation for more details. The default IPC stack size should be enough for most common simple use cases. However, users can increase/decrease the stack size to their needs. Range: · from 512 to 65536 Default value: · 1024
CONFIG_ESP_IPC_USES_CALLERS_PRIORITY IPC runs at callerns priority Found in: Component config > IPC (Inter-Processor Call) If this option is not enabled then the IPC task will keep behavior same as prior to that of ESP-IDF v4.0, hence IPC task will run at (configMAX_PRIORITIES - 1) priority. Default value: · Yes (enabled) if CONFIG_FREERTOS_UNICORE
High resolution timer (esp_timer) Contains: · CONFIG_ESP_TIMER_PROFILING · CONFIG_ESP_TIMER_IMPL · CONFIG_ESP_TIMER_TASK_STACK_SIZE · CONFIG_ESP_TIMER_INTERRUPT_LEVEL · CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD
CONFIG_ESP_TIMER_PROFILING Enable esp_timer profiling features Found in: Component config > High resolution timer (esp_timer) If enabled, esp_timer_dump will dump information such as number of times the timer was started, number of times the timer has triggered, and the total time it took for the callback to run. This option has some effect on timer performance and the amount of memory used for timer storage, and should only be used for debugging/testing purposes. Default value: · No (disabled)
CONFIG_ESP_TIMER_TASK_STACK_SIZE High-resolution timer task stack size Found in: Component config > High resolution timer (esp_timer) Configure the stack size of otimer_taskptask. This task is used to dispatch callbacks of timers created using ets_timer and esp_timer APIs. If you are seing stack overflow errors in timer task, increase this value. Note that this is not the same as FreeRTOS timer task. To configure FreeRTOS timer task size, see
oFreeRTOS timer task stack sizepoption in oFreeRTOSpmenu. Range:

Espressif Systems

1486

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· from 2048 to 65536 Default value:
· 3584
CONFIG_ESP_TIMER_INTERRUPT_LEVEL
Interrupt level
Found in: Component config > High resolution timer (esp_timer)
It sets the interrupt level for esp_timer ISR in range 1..3. A higher level (3) helps to decrease the ISR esp_timer latency.
Range: · from 1 to 1
Default value: ·1
CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD
Support ISR dispatch method
Found in: Component config > High resolution timer (esp_timer)
Allows using ESP_TIMER_ISR dispatch method (ESP_TIMER_TASK dispatch method is also avalible). - ESP_TIMER_TASK - Timer callbacks are dispatched from a high-priority esp_timer task. ESP_TIMER_ISR - Timer callbacks are dispatched directly from the timer interrupt handler. The ISR dispatch can be used, in some cases, when a callback is very simple or need a lower-latency.
Default value: · No (disabled)
CONFIG_ESP_TIMER_IMPL
Hardware timer to use for esp_timer
Found in: Component config > High resolution timer (esp_timer)
esp_timer APIs can be implemented using different hardware timers.
·oFRC2 (legacy)pimplementation has been used in ESP-IDF v2.x - v4.1. ·oLAC timer of Timer Group 0pimplementation is simpler, and has smaller run time overhead
because software handling of timer overflow is not needed. ·oSYSTIMERpimplementation is similar to oLAC timer of Timer Group 0pbut for non ESP32
chips.
Available options: · FRC2 (legacy) timer (ESP_TIMER_IMPL_FRC2) · LAC timer of Timer Group 0 (ESP_TIMER_IMPL_TG0_LAC) · SYSTIMER (ESP_TIMER_IMPL_SYSTIMER)
Wi-Fi Contains:
· CONFIG_ESP32_WIFI_ENABLE_WPA3_SAE · CONFIG_ESP32_WIFI_SOFTAP_BEACON_MAX_LEN · CONFIG_ESP32_WIFI_CACHE_TX_BUFFER_NUM · CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM · CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM · CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM · CONFIG_ESP32_WIFI_STATIC_TX_BUFFER_NUM · CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE · CONFIG_ESP32_WIFI_SW_COEXIST_ENABLE

Espressif Systems

1487

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· CONFIG_ESP32_WIFI_TX_BUFFER · CONFIG_ESP32_WIFI_AMPDU_RX_ENABLED · CONFIG_ESP32_WIFI_AMPDU_TX_ENABLED · CONFIG_ESP32_WIFI_AMSDU_TX_ENABLED · CONFIG_ESP32_WIFI_CSI_ENABLED · CONFIG_ESP_WIFI_FTM_ENABLE · CONFIG_ESP_WIFI_GCMP_SUPPORT · CONFIG_ESP_WIFI_GMAC_SUPPORT · CONFIG_ESP32_WIFI_IRAM_OPT · CONFIG_ESP32_WIFI_MGMT_SBUF_NUM · CONFIG_ESP32_WIFI_NVS_ENABLED · CONFIG_ESP32_WIFI_RX_IRAM_OPT · CONFIG_ESP_WIFI_SLP_IRAM_OPT · CONFIG_ESP_WIFI_SOFTAP_SUPPORT · CONFIG_ESP32_WIFI_TASK_CORE_ID

CONFIG_ESP32_WIFI_SW_COEXIST_ENABLE
Software controls WiFi/Bluetooth coexistence
Found in: Component config > Wi-Fi
If enabled, WiFi & Bluetooth coexistence is controlled by software rather than hardware. Recommended for heavy traffic scenarios. Both coexistence configuration options are automatically managed, no user intervention is required. If only Bluetooth is used, it is recommended to disable this option to reduce binary file size.
Default value: · Yes (enabled) if CONFIG_BT_ENABLED

CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM
Max number of WiFi static RX buffers
Found in: Component config > Wi-Fi
Set the number of WiFi static RX buffers. Each buffer takes approximately 1.6KB of RAM. The static rx buffers are allocated when esp_wifi_init is called, they are not freed until esp_wifi_deinit is called.
WiFi hardware use these buffers to receive all 802.11 frames. A higher number may allow higher throughput but increases memory use. If ESP32_WIFI_AMPDU_RX_ENABLED is enabled, this value is recommended to set equal or bigger than ESP32_WIFI_RX_BA_WIN in order to achieve better throughput and compatibility with both stations and APs.
Range: · from 2 to 25
Default value: · 10 if CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP · 16 if CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP

CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM
Max number of WiFi dynamic RX buffers
Found in: Component config > Wi-Fi
Set the number of WiFi dynamic RX buffers, 0 means unlimited RX buffers will be allocated (provided sufficient free RAM). The size of each dynamic RX buffer depends on the size of the received data frame.
For each received data frame, the WiFi driver makes a copy to an RX buffer and then delivers it to the high layer TCP/IP stack. The dynamic RX buffer is freed after the higher layer has successfully received the data frame.

Espressif Systems

1488

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

For some applications, WiFi data frames may be received faster than the application can process them. In these cases we may run out of memory if RX buffer number is unlimited (0).
If a dynamic RX buffer limit is set, it should be at least the number of static RX buffers.
Range: · from 0 to 128 if CONFIG_LWIP_WND_SCALE · from 0 to 1024 if CONFIG_LWIP_WND_SCALE
Default value: · 32

CONFIG_ESP32_WIFI_TX_BUFFER
Type of WiFi TX buffers
Found in: Component config > Wi-Fi
Select type of WiFi TX buffers:
IfoStaticpis selected, WiFi TX buffers are allocated when WiFi is initialized and released when WiFi is de-initialized. The size of each static TX buffer is fixed to about 1.6KB.
If oDynamicpis selected, each WiFi TX buffer is allocated as needed when a data frame is delivered to the Wifi driver from the TCP/IP stack. The buffer is freed after the data frame has been sent by the WiFi driver. The size of each dynamic TX buffer depends on the length of each data frame sent by the TCP/IP layer.
If PSRAM is enabled, oStaticpshould be selected to guarantee enough WiFi TX buffers. If PSRAM is disabled, oDynamicpshould be selected to improve the utilization of RAM.
Available options: · Static (ESP32_WIFI_STATIC_TX_BUFFER) · Dynamic (ESP32_WIFI_DYNAMIC_TX_BUFFER)

CONFIG_ESP32_WIFI_STATIC_TX_BUFFER_NUM
Max number of WiFi static TX buffers
Found in: Component config > Wi-Fi
Set the number of WiFi static TX buffers. Each buffer takes approximately 1.6KB of RAM. The static RX buffers are allocated when esp_wifi_init() is called, they are not released until esp_wifi_deinit() is called.
For each transmitted data frame from the higher layer TCP/IP stack, the WiFi driver makes a copy of it in a TX buffer. For some applications especially UDP applications, the upper layer can deliver frames faster than WiFi layer can transmit. In these cases, we may run out of TX buffers.
Range: · from 1 to 64 if ESP32_WIFI_STATIC_TX_BUFFER
Default value: · 16 if ESP32_WIFI_STATIC_TX_BUFFER

CONFIG_ESP32_WIFI_CACHE_TX_BUFFER_NUM
Max number of WiFi cache TX buffers
Found in: Component config > Wi-Fi
Set the number of WiFi cache TX buffer number.
For each TX packet from uplayer, such as LWIP etc, WiFi driver needs to allocate a static TX buffer and makes a copy of uplayer packet. If WiFi driver fails to allocate the static TX buffer, it caches the uplayer packets to a dedicated buffer queue, this option is used to configure the size of the cached TX queue.

Espressif Systems

1489

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Range: · from 16 to 128 if ESP32_SPIRAM_SUPPORT || ESP32S2_SPIRAM_SUPPORT || CONFIG_ESP32S3_SPIRAM_SUPPORT
Default value: · 32 if ESP32_SPIRAM_SUPPORT || ESP32S2_SPIRAM_SUPPORT || CONFIG_ESP32S3_SPIRAM_SUPPORT

CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM
Max number of WiFi dynamic TX buffers
Found in: Component config > Wi-Fi
Set the number of WiFi dynamic TX buffers. The size of each dynamic TX buffer is not fixed, it depends on the size of each transmitted data frame.
For each transmitted frame from the higher layer TCP/IP stack, the WiFi driver makes a copy of it in a TX buffer. For some applications, especially UDP applications, the upper layer can deliver frames faster than WiFi layer can transmit. In these cases, we may run out of TX buffers.
Range: · from 1 to 128
Default value: · 32

CONFIG_ESP32_WIFI_CSI_ENABLED
WiFi CSI(Channel State Information)
Found in: Component config > Wi-Fi
Select this option to enable CSI(Channel State Information) feature. CSI takes about CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM KB of RAM. If CSI is not used, it is better to disable this feature in order to save memory.
Default value: · No (disabled)

CONFIG_ESP32_WIFI_AMPDU_TX_ENABLED WiFi AMPDU TX Found in: Component config > Wi-Fi Select this option to enable AMPDU TX feature Default value: · Yes (enabled)

CONFIG_ESP32_WIFI_TX_BA_WIN
WiFi AMPDU TX BA window size
Found in: Component config > Wi-Fi > CONFIG_ESP32_WIFI_AMPDU_TX_ENABLED
Set the size of WiFi Block Ack TX window. Generally a bigger value means higher throughput but more memory. Most of time we should NOT change the default value unless special reason, e.g. test the maximum UDP TX throughput with iperf etc. For iperf test in shieldbox, the recommended value is 9~12.
Range: · from 2 to 32
Default value: ·6

Espressif Systems

1490

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_ESP32_WIFI_AMPDU_RX_ENABLED WiFi AMPDU RX Found in: Component config > Wi-Fi Select this option to enable AMPDU RX feature Default value: · Yes (enabled)

CONFIG_ESP32_WIFI_RX_BA_WIN

WiFi AMPDU RX BA window size

Found in: Component config > Wi-Fi > CONFIG_ESP32_WIFI_AMPDU_RX_ENABLED

Set the size of WiFi Block Ack RX window. Generally a bigger value means higher throughput and better compatibility but more memory. Most of time we should NOT change the default value unless special reason, e.g. test the maximum UDP RX throughput with iperf etc. For iperf test in shieldbox, the recommended value is 9~12. If PSRAM is used and WiFi memory is prefered to allocat in PSRAM first, the default and minimum value should be 16 to achieve better throughput and compatibility with both stations and APs.

Range:

· from 2 to 32

Default value:

·6

if

CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP

&&

CON-

FIG_ESP32_WIFI_AMPDU_RX_ENABLED

· 16

if

CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP

&&

CON-

FIG_ESP32_WIFI_AMPDU_RX_ENABLED

CONFIG_ESP32_WIFI_AMSDU_TX_ENABLED
WiFi AMSDU TX
Found in: Component config > Wi-Fi
Select this option to enable AMSDU TX feature
Default value: · No (disabled) if ESP32_SPIRAM_SUPPORT || ESP32S2_SPIRAM_SUPPORT || CONFIG_ESP32S3_SPIRAM_SUPPORT

CONFIG_ESP32_WIFI_NVS_ENABLED WiFi NVS flash Found in: Component config > Wi-Fi Select this option to enable WiFi NVS flash Default value: · Yes (enabled)

CONFIG_ESP32_WIFI_TASK_CORE_ID WiFi Task Core ID Found in: Component config > Wi-Fi Pinned WiFi task to core 0 or core 1. Available options: · Core 0 (ESP32_WIFI_TASK_PINNED_TO_CORE_0)

Espressif Systems

1491

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· Core 1 (ESP32_WIFI_TASK_PINNED_TO_CORE_1)
CONFIG_ESP32_WIFI_SOFTAP_BEACON_MAX_LEN Max length of WiFi SoftAP Beacon Found in: Component config > Wi-Fi ESP-MESH utilizes beacon frames to detect and resolve root node conflicts (see documentation). However the default length of a beacon frame can simultaneously hold only five root node identifier structures, meaning that a root node conflict of up to five nodes can be detected at one time. In the occurence of more root nodes conflict involving more than five root nodes, the conflict resolution process will detect five of the root nodes, resolve the conflict, and re-detect more root nodes. This process will repeat until all root node conflicts are resolved. However this process can generally take a very long time. To counter this situation, the beacon frame length can be increased such that more root nodes can be detected simultaneously. Each additional root node will require 36 bytes and should be added ontop of the default beacon frame length of 752 bytes. For example, if you want to detect 10 root nodes simultaneously, you need to set the beacon frame length as 932 (752+36*5). Setting a longer beacon length also assists with debugging as the conflicting root nodes can be identified more quickly. Range: · from 752 to 1256 Default value: · 752
CONFIG_ESP32_WIFI_MGMT_SBUF_NUM WiFi mgmt short buffer number Found in: Component config > Wi-Fi Set the number of WiFi management short buffer. Range: · from 6 to 32 Default value: · 32
CONFIG_ESP32_WIFI_IRAM_OPT WiFi IRAM speed optimization Found in: Component config > Wi-Fi Select this option to place frequently called Wi-Fi library functions in IRAM. When this option is disabled, more than 10Kbytes of IRAM memory will be saved but Wi-Fi throughput will be reduced. Default value: · No (disabled) if CONFIG_BT_ENABLED && ESP32_SPIRAM_SUPPORT · Yes (enabled)
CONFIG_ESP32_WIFI_RX_IRAM_OPT WiFi RX IRAM speed optimization Found in: Component config > Wi-Fi Select this option to place frequently called Wi-Fi library RX functions in IRAM. When this option is disabled, more than 17Kbytes of IRAM memory will be saved but Wi-Fi performance will be reduced. Default value:

Espressif Systems

1492

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· No (disabled) if CONFIG_BT_ENABLED && ESP32_SPIRAM_SUPPORT · Yes (enabled)

CONFIG_ESP32_WIFI_ENABLE_WPA3_SAE
Enable WPA3-Personal
Found in: Component config > Wi-Fi
Select this option to allow the device to establish a WPA3-Personal connection with eligible APns. PMF (Protected Management Frames) is a prerequisite feature for a WPA3 connection, it needs to be explicitly configured before attempting connection. Please refer to the Wi-Fi Driver API Guide for details.
Default value: · Yes (enabled)

CONFIG_ESP_WIFI_SLP_IRAM_OPT
WiFi SLP IRAM speed optimization
Found in: Component config > Wi-Fi
Select this option to place called Wi-Fi library TBTT process and receive beacon functions in IRAM. Some functions can be put in IRAM either by ESP32_WIFI_IRAM_OPT and ESP32_WIFI_RX_IRAM_OPT, or this one. If already enabled ESP32_WIFI_IRAM_OPT, the other 7.3KB IRAM memory would be taken by this option. If already enabled ESP32_WIFI_RX_IRAM_OPT, the other 1.3KB IRAM memory would be taken by this option. If neither of them are enabled, the other 7.4KB IRAM memory would be taken by this option. Wi-Fi power-save mode average current would be reduced if this option is enabled.

CONFIG_ESP_WIFI_SLP_DEFAULT_MIN_ACTIVE_TIME
Minimum active time
Found in: Component config > Wi-Fi > CONFIG_ESP_WIFI_SLP_IRAM_OPT
The minimum timeout for waiting to receive data, unit: milliseconds.
Range: · from 8 to 60 if CONFIG_ESP_WIFI_SLP_IRAM_OPT
Default value: · 50 if CONFIG_ESP_WIFI_SLP_IRAM_OPT

CONFIG_ESP_WIFI_SLP_DEFAULT_MAX_ACTIVE_TIME
Maximum keep alive time
Found in: Component config > Wi-Fi > CONFIG_ESP_WIFI_SLP_IRAM_OPT
The maximum time that wifi keep alive, unit: seconds.
Range: · from 10 to 60 if CONFIG_ESP_WIFI_SLP_IRAM_OPT
Default value: · 10 if CONFIG_ESP_WIFI_SLP_IRAM_OPT

CONFIG_ESP_WIFI_FTM_ENABLE WiFi FTM Found in: Component config > Wi-Fi Enable feature Fine Timing Measurement for calculating WiFi Round-Trip-Time (RTT).

Espressif Systems

1493

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Default value: · No (disabled)
CONFIG_ESP_WIFI_FTM_INITIATOR_SUPPORT FTM Initiator support Found in: Component config > Wi-Fi > CONFIG_ESP_WIFI_FTM_ENABLE Default value: · Yes (enabled) if CONFIG_ESP_WIFI_FTM_ENABLE
CONFIG_ESP_WIFI_FTM_RESPONDER_SUPPORT FTM Responder support Found in: Component config > Wi-Fi > CONFIG_ESP_WIFI_FTM_ENABLE Default value: · Yes (enabled) if CONFIG_ESP_WIFI_FTM_ENABLE
CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE Power Management for station at disconnected Found in: Component config > Wi-Fi Select this option to enable power_management for station when disconnected. Chip will do modemsleep when rf module is not in use any more.
CONFIG_ESP_WIFI_GCMP_SUPPORT WiFi GCMP Support(GCMP128 and GCMP256) Found in: Component config > Wi-Fi Select this option to enable GCMP support. GCMP support is compulsory for WiFi Suite-B support. Default value: · No (disabled)
CONFIG_ESP_WIFI_GMAC_SUPPORT WiFi GMAC Support(GMAC128 and GMAC256) Found in: Component config > Wi-Fi Select this option to enable GMAC support. GMAC support is compulsory for WiFi 192 bit certification. Default value: · No (disabled)
CONFIG_ESP_WIFI_SOFTAP_SUPPORT WiFi SoftAP Support Found in: Component config > Wi-Fi WiFi module can be compiled without SoftAP to save code size. Default value: · Yes (enabled)

Espressif Systems

1494

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Core dump Contains: · CONFIG_ESP_COREDUMP_CHECK_BOOT · CONFIG_ESP_COREDUMP_DATA_FORMAT · CONFIG_ESP_COREDUMP_CHECKSUM · CONFIG_ESP_COREDUMP_TO_FLASH_OR_UART · CONFIG_ESP_COREDUMP_UART_DELAY · CONFIG_ESP_COREDUMP_DECODE · CONFIG_ESP_COREDUMP_MAX_TASKS_NUM
CONFIG_ESP_COREDUMP_TO_FLASH_OR_UART Data destination Found in: Component config > Core dump Select place to store core dump: flash, uart or none (to disable core dumps generation). Core dumps to Flash are not available if PSRAM is used for task stacks. If core dump is configured to be stored in flash and custom partition table is used add corresponding entry to your CSV. For examples, please see predefined partition table CSV descriptions in the components/partition_table directory. Available options: · Flash (ESP_COREDUMP_ENABLE_TO_FLASH) · UART (ESP_COREDUMP_ENABLE_TO_UART) · None (ESP_COREDUMP_ENABLE_TO_NONE)
CONFIG_ESP_COREDUMP_DATA_FORMAT Core dump data format Found in: Component config > Core dump Select the data format for core dump. Available options: · Binary format (ESP_COREDUMP_DATA_FORMAT_BIN) · ELF format (ESP_COREDUMP_DATA_FORMAT_ELF)
CONFIG_ESP_COREDUMP_CHECKSUM Core dump data integrity check Found in: Component config > Core dump Select the integrity check for the core dump. Available options: · Use CRC32 for integrity verification (ESP_COREDUMP_CHECKSUM_CRC32) · Use SHA256 for integrity verification (ESP_COREDUMP_CHECKSUM_SHA256)
CONFIG_ESP_COREDUMP_CHECK_BOOT Check core dump data integrity on boot Found in: Component config > Core dump When enabled, if any data are found on the flash core dump partition, they will be checked by calculating their checksum. Default value: · Yes (enabled) if ESP_COREDUMP_ENABLE_TO_FLASH

Espressif Systems

1495

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_ESP_COREDUMP_MAX_TASKS_NUM Maximum number of tasks Found in: Component config > Core dump Maximum number of tasks snapshots in core dump.
CONFIG_ESP_COREDUMP_UART_DELAY Delay before print to UART Found in: Component config > Core dump Config delay (in ms) before printing core dump to UART. Delay can be interrupted by pressing Enter key. Default value: · 0 if ESP_COREDUMP_ENABLE_TO_UART
CONFIG_ESP_COREDUMP_DECODE Handling of UART core dumps in IDF Monitor Found in: Component config > Core dump Available options: · Decode and show summary (info_corefile) (ESP_COREDUMP_DECODE_INFO) · Donnt decode (ESP_COREDUMP_DECODE_DISABLE)
FAT Filesystem support Contains: · CONFIG_FATFS_API_ENCODING · CONFIG_FATFS_USE_FASTSEEK · CONFIG_FATFS_LONG_FILENAMES · CONFIG_FATFS_MAX_LFN · CONFIG_FATFS_FS_LOCK · CONFIG_FATFS_VOLUME_COUNT · CONFIG_FATFS_CHOOSE_CODEPAGE · CONFIG_FATFS_ALLOC_PREFER_EXTRAM · CONFIG_FATFS_TIMEOUT_MS · CONFIG_FATFS_PER_FILE_CACHE
CONFIG_FATFS_VOLUME_COUNT Number of volumes Found in: Component config > FAT Filesystem support Number of volumes (logical drives) to use. Range: · from 1 to 10 Default value: ·2
CONFIG_FATFS_CHOOSE_CODEPAGE OEM Code Page Found in: Component config > FAT Filesystem support OEM code page used for file name encodings.

Espressif Systems

1496

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

IfoDynamicpis selected, code page can be chosen at runtime using f_setcp function. Note that choosing this option will increase application size by ~480kB.
Available options: · Dynamic (all code pages supported) (FATFS_CODEPAGE_DYNAMIC) · US (CP437) (FATFS_CODEPAGE_437) · Arabic (CP720) (FATFS_CODEPAGE_720) · Greek (CP737) (FATFS_CODEPAGE_737) · KBL (CP771) (FATFS_CODEPAGE_771) · Baltic (CP775) (FATFS_CODEPAGE_775) · Latin 1 (CP850) (FATFS_CODEPAGE_850) · Latin 2 (CP852) (FATFS_CODEPAGE_852) · Cyrillic (CP855) (FATFS_CODEPAGE_855) · Turkish (CP857) (FATFS_CODEPAGE_857) · Portugese (CP860) (FATFS_CODEPAGE_860) · Icelandic (CP861) (FATFS_CODEPAGE_861) · Hebrew (CP862) (FATFS_CODEPAGE_862) · Canadian French (CP863) (FATFS_CODEPAGE_863) · Arabic (CP864) (FATFS_CODEPAGE_864) · Nordic (CP865) (FATFS_CODEPAGE_865) · Russian (CP866) (FATFS_CODEPAGE_866) · Greek 2 (CP869) (FATFS_CODEPAGE_869) · Japanese (DBCS) (CP932) (FATFS_CODEPAGE_932) · Simplified Chinese (DBCS) (CP936) (FATFS_CODEPAGE_936) · Korean (DBCS) (CP949) (FATFS_CODEPAGE_949) · Traditional Chinese (DBCS) (CP950) (FATFS_CODEPAGE_950)

CONFIG_FATFS_LONG_FILENAMES
Long filename support
Found in: Component config > FAT Filesystem support
Support long filenames in FAT. Long filename data increases memory usage. FATFS can be configured to store the buffer for long filename data in stack or heap.
Available options: · No long filenames (FATFS_LFN_NONE) · Long filename buffer in heap (FATFS_LFN_HEAP) · Long filename buffer on stack (FATFS_LFN_STACK)

CONFIG_FATFS_MAX_LFN
Max long filename length
Found in: Component config > FAT Filesystem support
Maximum long filename length. Can be reduced to save RAM.
Range: · from 12 to 255
Default value: · 255

CONFIG_FATFS_API_ENCODING API character encoding Found in: Component config > FAT Filesystem support Choose encoding for character and string arguments/returns when using FATFS APIs. The encoding of arguments will usually depend on text editor settings.

Espressif Systems

1497

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Available options: · API uses ANSI/OEM encoding (FATFS_API_ENCODING_ANSI_OEM) · API uses UTF-16 encoding (FATFS_API_ENCODING_UTF_16) · API uses UTF-8 encoding (FATFS_API_ENCODING_UTF_8)
CONFIG_FATFS_FS_LOCK Number of simultaneously open files protected by lock function Found in: Component config > FAT Filesystem support This option sets the FATFS configuration value _FS_LOCK. The option _FS_LOCK switches file lock function to control duplicated file open and illegal operation to open objects. * 0: Disable file lock function. To avoid volume corruption, application should avoid illegal open, remove and rename to the open objects. * >0: Enable file lock function. The value defines how many files/sub-directories can be opened simultaneously under file lock control. Note that the file lock control is independent of re-entrancy. Range: · from 0 to 65535 Default value: ·0
CONFIG_FATFS_TIMEOUT_MS Timeout for acquiring a file lock, ms Found in: Component config > FAT Filesystem support This option sets FATFS configuration value _FS_TIMEOUT, scaled to milliseconds. Sets the number of milliseconds FATFS will wait to acquire a mutex when operating on an open file. For example, if one task is performing a lenghty operation, another task will wait for the first task to release the lock, and time out after amount of time set by this option. Default value: · 10000
CONFIG_FATFS_PER_FILE_CACHE Use separate cache for each file Found in: Component config > FAT Filesystem support This option affects FATFS configuration value _FS_TINY. If this option is set, _FS_TINY is 0, and each open file has its own cache, size of the cache is equal to the _MAX_SS variable (512 or 4096 bytes). This option uses more RAM if more than 1 file is open, but needs less reads and writes to the storage for some operations. If this option is not set, _FS_TINY is 1, and single cache is used for all open files, size is also equal to _MAX_SS variable. This reduces the amount of heap used when multiple files are open, but increases the number of read and write operations which FATFS needs to make. Default value: · Yes (enabled)

Espressif Systems

1498

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_FATFS_ALLOC_PREFER_EXTRAM
Perfer external RAM when allocating FATFS buffers
Found in: Component config > FAT Filesystem support
When the option is enabled, internal buffers used by FATFS will be allocated from external RAM. If the allocation from external RAM fails, the buffer will be allocated from the internal RAM. Disable this option if optimizing for performance. Enable this option if optimizing for internal memory size.
Default value: · Yes (enabled) if SPIRAM_USE_CAPS_ALLOC || SPIRAM_USE_MALLOC
CONFIG_FATFS_USE_FASTSEEK
Enable fast seek algorithm when using lseek function through VFS FAT
Found in: Component config > FAT Filesystem support
The fast seek feature enables fast backward/long seek operations without FAT access by using an inmemory CLMT (cluster link map table). Please note, fast-seek is only allowed for read-mode files, if a file is opened in write-mode, the seek mechanism will automatically fallback to the default implementation.
Default value: · No (disabled)
CONFIG_FATFS_FAST_SEEK_BUFFER_SIZE
Fast seek CLMT buffer size
Found in: Component config > FAT Filesystem support > CONFIG_FATFS_USE_FASTSEEK
If fast seek algorithm is enabled, this defines the size of CLMT buffer used by this algorithm in 32-bit word units. This value should be chosen based on prior knowledge of maximum elements of each file entry would store.
Default value: · 64 if CONFIG_FATFS_USE_FASTSEEK
Modbus configuration Contains:
· CONFIG_FMB_COMM_MODE_ASCII_EN · CONFIG_FMB_COMM_MODE_RTU_EN · CONFIG_FMB_COMM_MODE_TCP_EN · CONFIG_FMB_CONTROLLER_NOTIFY_QUEUE_SIZE · CONFIG_FMB_CONTROLLER_NOTIFY_TIMEOUT · CONFIG_FMB_CONTROLLER_SLAVE_ID_SUPPORT · CONFIG_FMB_CONTROLLER_STACK_SIZE · CONFIG_FMB_PORT_TASK_PRIO · CONFIG_FMB_PORT_TASK_STACK_SIZE · CONFIG_FMB_QUEUE_LENGTH · CONFIG_FMB_SERIAL_BUF_SIZE · CONFIG_FMB_EVENT_QUEUE_TIMEOUT · CONFIG_FMB_TIMER_PORT_ENABLED · CONFIG_FMB_PORT_TASK_AFFINITY · CONFIG_FMB_TIMER_USE_ISR_DISPATCH_METHOD · CONFIG_FMB_SERIAL_ASCII_BITS_PER_SYMB · CONFIG_FMB_SERIAL_ASCII_TIMEOUT_RESPOND_MS · CONFIG_FMB_MASTER_DELAY_MS_CONVERT · CONFIG_FMB_MASTER_TIMEOUT_MS_RESPOND

Espressif Systems

1499

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_FMB_COMM_MODE_TCP_EN Enable Modbus stack support for TCP communication mode Found in: Component config > Modbus configuration Enable Modbus TCP option for stack. Default value: · Yes (enabled)
CONFIG_FMB_TCP_PORT_DEFAULT Modbus TCP port number Found in: Component config > Modbus configuration > CONFIG_FMB_COMM_MODE_TCP_EN Modbus default port number used by Modbus TCP stack Range: · from 0 to 65535 Default value: · 502
CONFIG_FMB_TCP_PORT_MAX_CONN Maximum allowed connections for TCP stack Found in: Component config > Modbus configuration > CONFIG_FMB_COMM_MODE_TCP_EN Maximum allowed connections number for Modbus TCP stack. This is used by Modbus master and slave port layer to establish connections. This parameter may decrease performance of Modbus stack and can cause increasing of processing time (increase only if absolutely necessary). Range: · from 1 to 6 Default value: ·5
CONFIG_FMB_TCP_CONNECTION_TOUT_SEC Modbus TCP connection timeout Found in: Component config > Modbus configuration > CONFIG_FMB_COMM_MODE_TCP_EN Modbus TCP connection timeout in seconds. Once expired the current connection with the client will be closed and Modbus slave will be waiting for new connection to accept. Range: · from 1 to 3600 Default value: · 20
CONFIG_FMB_COMM_MODE_RTU_EN Enable Modbus stack support for RTU mode Found in: Component config > Modbus configuration Enable RTU Modbus communication mode option for Modbus serial stack. Default value: · Yes (enabled)

Espressif Systems

1500

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_FMB_COMM_MODE_ASCII_EN Enable Modbus stack support for ASCII mode Found in: Component config > Modbus configuration Enable ASCII Modbus communication mode option for Modbus serial stack. Default value: · Yes (enabled)
CONFIG_FMB_MASTER_TIMEOUT_MS_RESPOND Slave respond timeout (Milliseconds) Found in: Component config > Modbus configuration If master sends a frame which is not broadcast, it has to wait sometime for slave response. if slave is not respond in this time, the master will process timeout error. Range: · from 50 to 3000 Default value: · 150
CONFIG_FMB_MASTER_DELAY_MS_CONVERT Slave conversion delay (Milliseconds) Found in: Component config > Modbus configuration If master sends a broadcast frame, it has to wait conversion time to delay, then master can send next frame. Range: · from 50 to 400 Default value: · 200
CONFIG_FMB_QUEUE_LENGTH Modbus serial task queue length Found in: Component config > Modbus configuration Modbus serial driver queue length. It is used by event queue task. See the serial driver API for more information. Range: · from 0 to 200 Default value: · 20
CONFIG_FMB_PORT_TASK_STACK_SIZE Modbus port task stack size Found in: Component config > Modbus configuration Modbus port task stack size for rx/tx event processing. It may be adjusted when debugging is enabled (for example). Range: · from 2048 to 8192 Default value:

Espressif Systems

1501

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· 4096
CONFIG_FMB_SERIAL_BUF_SIZE Modbus serial task RX/TX buffer size Found in: Component config > Modbus configuration Modbus serial task RX and TX buffer size for UART driver initialization. This buffer is used for modbus frame transfer. The Modbus protocol maximum frame size is 256 bytes. Bigger size can be used for non standard implementations. Range: · from 0 to 2048 Default value: · 256
CONFIG_FMB_SERIAL_ASCII_BITS_PER_SYMB Number of data bits per ASCII character Found in: Component config > Modbus configuration This option defines the number of data bits per ASCII character. Range: · from 7 to 8 Default value: ·8
CONFIG_FMB_SERIAL_ASCII_TIMEOUT_RESPOND_MS Response timeout for ASCII communication mode (ms) Found in: Component config > Modbus configuration This option defines response timeout of slave in milliseconds for ASCII communication mode. Thus the timeout will expire and allow the master program to handle the error. Range: · from 300 to 2000 Default value: · 1000
CONFIG_FMB_PORT_TASK_PRIO Modbus port task priority Found in: Component config > Modbus configuration Modbus port data processing task priority. The priority of Modbus controller task is equal to (CONFIG_FMB_PORT_TASK_PRIO - 1). Range: · from 3 to 23 Default value: · 10

Espressif Systems

1502

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_FMB_PORT_TASK_AFFINITY
Modbus task affinity
Found in: Component config > Modbus configuration
Allows setting the core affinity of the Modbus controller task, i.e. whether the task is pinned to particular CPU, or allowed to run on any CPU.
Available options: · No affinity (FMB_PORT_TASK_AFFINITY_NO_AFFINITY) · CPU0 (FMB_PORT_TASK_AFFINITY_CPU0) · CPU1 (FMB_PORT_TASK_AFFINITY_CPU1)

CONFIG_FMB_CONTROLLER_SLAVE_ID_SUPPORT
Modbus controller slave ID support
Found in: Component config > Modbus configuration
Modbus slave ID support enable. When enabled the Modbus <Report Slave ID> command is supported by stack.
Default value: · Yes (enabled)

CONFIG_FMB_CONTROLLER_SLAVE_ID

Modbus controller slave ID

Found in:

Component config > Modbus configuration > CON-

FIG_FMB_CONTROLLER_SLAVE_ID_SUPPORT

Modbus slave ID value to identify modbus device in the network using <Report Slave ID> command. Most significant byte of ID is used as short device ID and other three bytes used as long ID.

Range: · from 0 to 4294967295
Default value: ·o0x00112233p

CONFIG_FMB_CONTROLLER_NOTIFY_TIMEOUT
Modbus controller notification timeout (ms)
Found in: Component config > Modbus configuration
Modbus controller notification timeout in milliseconds. This timeout is used to send notification about accessed parameters.
Range: · from 0 to 200
Default value: · 20

CONFIG_FMB_CONTROLLER_NOTIFY_QUEUE_SIZE Modbus controller notification queue size Found in: Component config > Modbus configuration Modbus controller notification queue size. The notification queue is used to get information about accessed parameters. Range:

Espressif Systems

1503

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· from 0 to 200 Default value:
· 20
CONFIG_FMB_CONTROLLER_STACK_SIZE Modbus controller stack size Found in: Component config > Modbus configuration Modbus controller task stack size. The Stack size may be adjusted when debug mode is used which requires more stack size (for example). Range: · from 0 to 8192 Default value: · 4096
CONFIG_FMB_EVENT_QUEUE_TIMEOUT Modbus stack event queue timeout (ms) Found in: Component config > Modbus configuration Modbus stack event queue timeout in milliseconds. This may help to optimize Modbus stack event processing time. Range: · from 0 to 500 Default value: · 20
CONFIG_FMB_TIMER_PORT_ENABLED Modbus stack use timer for 3.5T symbol time measurement Found in: Component config > Modbus configuration If this option is set the Modbus stack uses timer for T3.5 time measurement. Else the internal UART TOUT timeout is used for 3.5T symbol time measurement. Default value: · No (disabled)
CONFIG_FMB_TIMER_USE_ISR_DISPATCH_METHOD Modbus timer uses ISR dispatch method Found in: Component config > Modbus configuration If this option is set the Modbus stack uses ISR dispatch method to send timeout events from the callback function called from ISR. This option has dependency with the UART_ISR_IN_IRAM option which places UART interrupt handler into IRAM to prevent delays related to processing of UART events. Default value: · No (disabled)
FreeRTOS Contains: · CONFIG_FREERTOS_CHECK_STACKOVERFLOW · CONFIG_FREERTOS_CHECK_MUTEX_GIVEN_BY_OWNER · CONFIG_FREERTOS_INTERRUPT_BACKTRACE · CONFIG_FREERTOS_OPTIMIZED_SCHEDULER

Espressif Systems

1504

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS · CONFIG_FREERTOS_USE_TRACE_FACILITY · CONFIG_FREERTOS_ENABLE_STATIC_TASK_CLEAN_UP · CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT · CONFIG_FREERTOS_TASK_FUNCTION_WRAPPER · CONFIG_FREERTOS_QUEUE_REGISTRY_SIZE · CONFIG_FREERTOS_TIMER_QUEUE_LENGTH · CONFIG_FREERTOS_TIMER_TASK_PRIORITY · CONFIG_FREERTOS_TIMER_TASK_STACK_DEPTH · CONFIG_FREERTOS_ASSERT_ON_UNTESTED_FUNCTION · CONFIG_FREERTOS_IDLE_TASK_STACKSIZE · CONFIG_FREERTOS_ISR_STACKSIZE · CONFIG_FREERTOS_MAX_TASK_NAME_LEN · CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS · CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH · CONFIG_FREERTOS_UNICORE · CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK · CONFIG_FREERTOS_CHECK_PORT_CRITICAL_COMPLIANCE · CONFIG_FREERTOS_HZ · CONFIG_FREERTOS_USE_TICKLESS_IDLE · CONFIG_FREERTOS_LEGACY_HOOKS · CONFIG_FREERTOS_CORETIMER

CONFIG_FREERTOS_UNICORE
Run FreeRTOS only on first core
Found in: Component config > FreeRTOS
This version of FreeRTOS normally takes control of all cores of the CPU. Select this if you only want to start it on the first core. This is needed when e.g. another process needs complete control over the second core.
# This invisible config value sets the value of tskNO_AFFINITY in task.h. # Intended to be used as a constant from other Kconfig files. # Value is (32-bit) INT_MAX.

CONFIG_FREERTOS_CORETIMER
Xtensa timer to use as the FreeRTOS tick source
Found in: Component config > FreeRTOS
FreeRTOS needs a timer with an associated interrupt to use as the main tick source to increase counters, run timers and do pre-emptive multitasking with. There are multiple timers available to do this, with different interrupt priorities. Check
Available options: · Timer 0 (int 6, level 1) (FREERTOS_CORETIMER_0) Select this to use timer 0 · Timer 1 (int 15, level 3) (FREERTOS_CORETIMER_1) Select this to use timer 1 · SYSTIMER 0 (level 1) (FREERTOS_CORETIMER_SYSTIMER_LVL1) Select this to use systimer with the 1 interrupt priority. · SYSTIMER 0 (level 3) (FREERTOS_CORETIMER_SYSTIMER_LVL3) Select this to use systimer with the 3 interrupt priority.

CONFIG_FREERTOS_OPTIMIZED_SCHEDULER Enable FreeRTOS patform optimized scheduler Found in: Component config > FreeRTOS

Espressif Systems

1505

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

On most platforms there are instructions can speedup the ready task searching. Enabling this option the FreeRTOS with this instructions support will be built.
Default value: · Yes (enabled) if CONFIG_FREERTOS_UNICORE
CONFIG_FREERTOS_HZ
Tick rate (Hz)
Found in: Component config > FreeRTOS
Select the tick rate at which FreeRTOS does pre-emptive context switching.
Range: · from 1 to 1000
Default value: · 100
CONFIG_FREERTOS_ASSERT_ON_UNTESTED_FUNCTION
Halt when an SMP-untested function is called
Found in: Component config > FreeRTOS
Some functions in FreeRTOS have not been thoroughly tested yet when moving to the SMP implementation of FreeRTOS. When this option is enabled, these fuctions will throw an assert().
Default value: · Yes (enabled)
CONFIG_FREERTOS_CHECK_STACKOVERFLOW
Check for stack overflow
Found in: Component config > FreeRTOS
FreeRTOS can check for stack overflows in threads and trigger an user function called vApplicationStackOverflowHook when this happens.
Available options: · No checking (FREERTOS_CHECK_STACKOVERFLOW_NONE) Do not check for stack overflows (configCHECK_FOR_STACK_OVERFLOW=0) · Check by stack pointer value (FREERTOS_CHECK_STACKOVERFLOW_PTRVAL) Check for stack overflows on each context switch by checking if the stack pointer is in a valid range. Quick but does not detect stack overflows that happened between context switches (configCHECK_FOR_STACK_OVERFLOW=1) · Check using canary bytes (FREERTOS_CHECK_STACKOVERFLOW_CANARY) Places some magic bytes at the end of the stack area and on each context switch, check if these bytes are still intact. More thorough than just checking the pointer, but also slightly slower. (configCHECK_FOR_STACK_OVERFLOW=2)
CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK
Set a debug watchpoint as a stack overflow check
Found in: Component config > FreeRTOS
FreeRTOS can check if a stack has overflown its bounds by checking either the value of the stack pointer or by checking the integrity of canary bytes. (See FREERTOS_CHECK_STACKOVERFLOW for more information.) These checks only happen on a context switch, and the situation that caused the stack overflow may already be long gone by then. This option will use the last debug memory watchpoint to allow breaking into the debugger (or panicning) as soon as any of the last 32 bytes on the stack of a

Espressif Systems

1506

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

task are overwritten. The side effect is that using gdb, you effectively have one hardware watchpoint less because the last one is overwritten as soon as a task switch happens.
Another consequence is that due to alignment requirements of the watchpoint, the usable stack size decreases by up to 60 bytes. This is because the watchpoint region has to be aligned to its size and the size for the stack watchpoint in IDF is 32 bytes.
This check only triggers if the stack overflow writes within 32 bytes near the end of the stack, rather than overshooting further, so it is worth combining this approach with one of the other stack overflow check methods.
When this watchpoint is hit, gdb will stop with a SIGTRAP message. When no JTAG OCD is attached, esp-idf will panic on an unhandled debug exception.
Default value: · No (disabled)

CONFIG_FREERTOS_INTERRUPT_BACKTRACE
Enable backtrace from interrupt to task context
Found in: Component config > FreeRTOS
If this option is enabled, interrupt stack frame will be modified to point to the code of the interrupted task as its return address. This helps the debugger (or the panic handler) show a backtrace from the interrupt to the task which was interrupted. This also works for nested interrupts: higer level interrupt stack can be traced back to the lower level interrupt. This option adds 4 instructions to the interrupt dispatching code.
Default value: · Yes (enabled)

CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS
Number of thread local storage pointers
Found in: Component config > FreeRTOS
FreeRTOS has the ability to store per-thread pointers in the task control block. This controls the number of pointers available.
This value must be at least 1. Index 0 is reserved for use by the pthreads API thread-local-storage. Other indexes can be used for any desired purpose.
Range: · from 1 to 256
Default value: ·1

CONFIG_FREERTOS_IDLE_TASK_STACKSIZE
Idle Task stack size
Found in: Component config > FreeRTOS
The idle task has its own stack, sized in bytes. The default size is enough for most uses. Size can be reduced to 768 bytes if no (or simple) FreeRTOS idle hooks are used and pthread local storage or FreeRTOS local storage cleanup callbacks are not used.
The stack size may need to be increased above the default if the app installs idle or thread local storage cleanup hooks that use a lot of stack memory.
Range: · from 768 to 32768
Default value:

Espressif Systems

1507

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· 1536
CONFIG_FREERTOS_ISR_STACKSIZE ISR stack size Found in: Component config > FreeRTOS The interrupt handlers have their own stack. The size of the stack can be defined here. Each processor has its own stack, so the total size occupied will be twice this. Range: · from 2096 to 32768 if ESP_COREDUMP_DATA_FORMAT_ELF · from 1536 to 32768 Default value: · 2096 if ESP_COREDUMP_DATA_FORMAT_ELF · 1536
CONFIG_FREERTOS_LEGACY_HOOKS Use FreeRTOS legacy hooks Found in: Component config > FreeRTOS FreeRTOS offers a number of hooks/callback functions that are called when a timer tick happens, the idle thread runs etc. esp-idf replaces these by runtime registerable hooks using the esp_register_freertos_xxx_hook system, but for legacy reasons the old hooks can also still be enabled. Please enable this only if you have code that for some reason cannt be migrated to the esp_register_freertos_xxx_hook system. Default value: · No (disabled)
CONFIG_FREERTOS_MAX_TASK_NAME_LEN Maximum task name length Found in: Component config > FreeRTOS Changes the maximum task name length. Each task allocated will include this many bytes for a task name. Using a shorter value saves a small amount of RAM, a longer value allows more complex names. For most uses, the default of 16 is OK. Range: · from 1 to 256 Default value: · 16
CONFIG_FREERTOS_ENABLE_STATIC_TASK_CLEAN_UP Enable static task clean up hook Found in: Component config > FreeRTOS Enable this option to make FreeRTOS call the static task clean up hook when a task is deleted. Bear in mind that if this option is enabled you will need to implement the following function:
void vPortCleanUpTCB ( void \*pxTCB ) { // place clean up code here
}
Default value:

Espressif Systems

1508

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· No (disabled)

CONFIG_FREERTOS_TIMER_TASK_PRIORITY
FreeRTOS timer task priority
Found in: Component config > FreeRTOS
The timer service task (primarily) makes use of existing FreeRTOS features, allowing timer functionality to be added to an application with minimal impact on the size of the applicationns executable binary.
Use this constant to define the priority that the timer task will run at.
Range: · from 1 to 25
Default value: ·1

CONFIG_FREERTOS_TIMER_TASK_STACK_DEPTH
FreeRTOS timer task stack size
Found in: Component config > FreeRTOS
The timer service task (primarily) makes use of existing FreeRTOS features, allowing timer functionality to be added to an application with minimal impact on the size of the applicationns executable binary.
Use this constant to define the size (in bytes) of the stack allocated for the timer task.
Range: · from 1536 to 32768
Default value: · 2048

CONFIG_FREERTOS_TIMER_QUEUE_LENGTH
FreeRTOS timer queue length
Found in: Component config > FreeRTOS
FreeRTOS provides a set of timer related API functions. Many of these functions use a standard FreeRTOS queue to send commands to the timer service task. The queue used for this purpose is called the mtimer command queuen. The mtimer command queuenis private to the FreeRTOS timer implementation, and cannot be accessed directly.
For most uses the default value of 10 is OK.
Range: · from 5 to 20
Default value: · 10

CONFIG_FREERTOS_QUEUE_REGISTRY_SIZE
FreeRTOS queue registry size
Found in: Component config > FreeRTOS
FreeRTOS uses the queue registry as a means for kernel aware debuggers to locate queues, semaphores, and mutexes. The registry allows for a textual name to be associated with a queue for easy identification within a debugging GUI. A value of 0 will disable queue registry functionality, and a value larger than 0 will specify the number of queues/semaphores/mutexes that the registry can hold.
Range: · from 0 to 20

Espressif Systems

1509

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Default value: ·0
CONFIG_FREERTOS_USE_TRACE_FACILITY Enable FreeRTOS trace facility Found in: Component config > FreeRTOS If enabled, configUSE_TRACE_FACILITY will be defined as 1 in FreeRTOS. This will allow the usage of trace facility functions such as uxTaskGetSystemState(). Default value: · No (disabled)
CONFIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS Enable FreeRTOS stats formatting functions Found in: Component config > FreeRTOS > CONFIG_FREERTOS_USE_TRACE_FACILITY If enabled, configUSE_STATS_FORMATTING_FUNCTIONS will be defined as 1 in FreeRTOS. This will allow the usage of stats formatting functions such as vTaskList(). Default value: · No (disabled) if CONFIG_FREERTOS_USE_TRACE_FACILITY
CONFIG_FREERTOS_VTASKLIST_INCLUDE_COREID Enable display of xCoreID in vTaskList Found in: Component config > FreeRTOS > CONFIG_FREERTOS_USE_TRACE_FACILITY > CONFIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS If enabled, this will include an extra column when vTaskList is called to display the CoreID the task is pinned to (0,1) or -1 if not pinned. Default value: · No (disabled) if CONFIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS
CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS Enable FreeRTOS to collect run time stats Found in: Component config > FreeRTOS If enabled, configGENERATE_RUN_TIME_STATS will be defined as 1 in FreeRTOS. This will allow FreeRTOS to collect information regarding the usage of processor time amongst FreeRTOS tasks. Run time stats are generated using either the ESP Timer or the CPU Clock as the clock source (Note that run time stats are only valid until the clock source overflows). The function vTaskGetRunTimeStats() will also be available if FREERTOS_USE_STATS_FORMATTING_FUNCTIONS and FREERTOS_USE_TRACE_FACILITY are enabled. vTaskGetRunTimeStats() will display the run time of each task as a % of the total run time of all CPUs (task run time / no of CPUs) / (total run time / 100 ) Default value: · No (disabled)
CONFIG_FREERTOS_RUN_TIME_STATS_CLK Choose the clock source for run time stats Found in: Component config > FreeRTOS > CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS

Espressif Systems

1510

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Choose the clock source for FreeRTOS run time stats. Options are CPU0ns CPU Clock or the ESP Timer. Both clock sources are 32 bits. The CPU Clock can run at a higher frequency hence provide a finer resolution but will overflow much quicker. Note that run time stats are only valid until the clock source overflows.
Available options: · Use ESP TIMER for run time stats (FREERTOS_RUN_TIME_STATS_USING_ESP_TIMER) ESP Timer will be used as the clock source for FreeRTOS run time stats. The ESP Timer runs at a frequency of 1MHz regardless of Dynamic Frequency Scaling. Therefore the ESP Timer will overflow in approximately 4290 seconds. · Use CPU Clock for run time stats (FREERTOS_RUN_TIME_STATS_USING_CPU_CLK) CPU Clock will be used as the clock source for the generation of run time stats. The CPU Clock has a frequency dependent on ESP32_DEFAULT_CPU_FREQ_MHZ and Dynamic Frequency Scaling (DFS). Therefore the CPU Clock frequency can fluctuate between 80 to 240MHz. Run time stats generated using the CPU Clock represents the number of CPU cycles each task is allocated and DOES NOT reflect the amount of time each task runs for (as CPU clock frequency can change). If the CPU clock consistently runs at the maximum frequency of 240MHz, it will overflow in approximately 17 seconds.
CONFIG_FREERTOS_USE_TICKLESS_IDLE
Tickless idle support
Found in: Component config > FreeRTOS
If power management support is enabled, FreeRTOS will be able to put the system into light sleep mode when no tasks need to run for a number of ticks. This number can be set using FREERTOS_IDLE_TIME_BEFORE_SLEEP option. This feature is also known as oautomatic light sleepp .
Note that timers created using esp_timer APIs may prevent the system from entering sleep mode, even when no tasks need to run. To skip unnecessary wake-up initialize a timer with the oskip_unhandled_eventspoption as true.
If disabled, automatic light sleep support will be disabled.
Default value: · No (disabled) if CONFIG_PM_ENABLE
CONFIG_FREERTOS_IDLE_TIME_BEFORE_SLEEP
Minimum number of ticks to enter sleep mode for
Found in: Component config > FreeRTOS > CONFIG_FREERTOS_USE_TICKLESS_IDLE
FreeRTOS will enter light sleep mode if no tasks need to run for this number of ticks.
Range: · from 2 to 4294967295 if CONFIG_FREERTOS_USE_TICKLESS_IDLE
Default value: · 3 if CONFIG_FREERTOS_USE_TICKLESS_IDLE
CONFIG_FREERTOS_TASK_FUNCTION_WRAPPER
Enclose all task functions in a wrapper function
Found in: Component config > FreeRTOS
If enabled, all FreeRTOS task functions will be enclosed in a wrapper function. If a task function mistakenly returns (i.e. does not delete), the call flow will return to the wrapper function. The wrapper function will then log an error and abort the application. This option is also required for GDB backtraces and C++ exceptions to work correctly inside top-level task functions.

Espressif Systems

1511

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Default value: · Yes (enabled)
CONFIG_FREERTOS_CHECK_MUTEX_GIVEN_BY_OWNER Check that mutex semaphore is given by owner task Found in: Component config > FreeRTOS If enabled, assert that when a mutex semaphore is given, the task giving the semaphore is the task which is currently holding the mutex. Default value: · Yes (enabled)
CONFIG_FREERTOS_CHECK_PORT_CRITICAL_COMPLIANCE Tests compliance with Vanilla FreeRTOS port*_CRITICAL calls Found in: Component config > FreeRTOS If enabled, context of port*_CRITICAL calls (ISR or Non-ISR) would be checked to be in compliance with Vanilla FreeRTOS. e.g Calling port*_CRITICAL from ISR context would cause assert failure Default value: · No (disabled)
CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH Place FreeRTOS functions into Flash Found in: Component config > FreeRTOS When enabled the selected Non-ISR FreeRTOS functions will be placed into Flash memory instead of IRAM. This saves up to 8KB of IRAM depending on which functions are used. Default value: · No (disabled)
CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT Enable task snapshot functions Found in: Component config > FreeRTOS When enabled, the functions related to snapshots, such as vTaskGetSnapshot or uxTaskGetSnapshotAll, are compiled and linked. Default value: · Yes (enabled)
CONFIG_FREERTOS_PLACE_SNAPSHOT_FUNS_INTO_FLASH Place task snapshot functions into flash Found in: Component config > FreeRTOS > CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT When enabled, the functions related to snapshots, such as vTaskGetSnapshot or uxTaskGetSnapshotAll, will be placed in flash. Note that if enabled, these functions cannot be called when cache is disabled. Default value: · No (disabled) if CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT && CONFIG_ESP_PANIC_HANDLER_IRAM

Espressif Systems

1512

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Hardware Abstraction Layer (HAL) and Low Level (LL) Contains: · CONFIG_HAL_DEFAULT_ASSERTION_LEVEL
CONFIG_HAL_DEFAULT_ASSERTION_LEVEL Default HAL assertion level Found in: Component config > Hardware Abstraction Layer (HAL) and Low Level (LL) Set the assert behavior / level for HAL component. HAL component assert level can be set separately, but the level cannt exceed the system assertion level. e.g. If the system assertion is disabled, then the HAL assertion cannt be enabled either. If the system assertion is enable, then the HAL assertion can still be disabled by this Kconfig option. Available options: · Same as system assertion level (HAL_ASSERTION_EQUALS_SYSTEM) · Disabled (HAL_ASSERTION_DISABLE) · Silent (HAL_ASSERTION_SILIENT) · Enabled (HAL_ASSERTION_ENABLE)
Heap memory debugging Contains: · CONFIG_HEAP_ABORT_WHEN_ALLOCATION_FAILS · CONFIG_HEAP_TASK_TRACKING · CONFIG_HEAP_CORRUPTION_DETECTION · CONFIG_HEAP_TRACING_DEST · CONFIG_HEAP_TRACING_STACK_DEPTH
CONFIG_HEAP_CORRUPTION_DETECTION Heap corruption detection Found in: Component config > Heap memory debugging Enable heap poisoning features to detect heap corruption caused by out-of-bounds access to heap memory. See the oHeap Memory Debuggingppage of the IDF documentation for a description of each level of heap corruption detection. Available options: · Basic (no poisoning) (HEAP_POISONING_DISABLED) · Light impact (HEAP_POISONING_LIGHT) · Comprehensive (HEAP_POISONING_COMPREHENSIVE)
CONFIG_HEAP_TRACING_DEST Heap tracing Found in: Component config > Heap memory debugging Enables the heap tracing API defined in esp_heap_trace.h. This function causes a moderate increase in IRAM code side and a minor increase in heap function (malloc/free/realloc) CPU overhead, even when the tracing feature is not used. So itns best to keep it disabled unless tracing is being used. Available options: · Disabled (HEAP_TRACING_OFF) · Standalone (HEAP_TRACING_STANDALONE) · Host-based (HEAP_TRACING_TOHOST)

Espressif Systems

1513

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_HEAP_TRACING_STACK_DEPTH Heap tracing stack depth Found in: Component config > Heap memory debugging Number of stack frames to save when tracing heap operation callers. More stack frames uses more memory in the heap trace buffer (and slows down allocation), but can provide useful information.
CONFIG_HEAP_TASK_TRACKING Enable heap task tracking Found in: Component config > Heap memory debugging Enables tracking the task responsible for each heap allocation. This function depends on heap poisoning being enabled and adds four more bytes of overhead for each block allocated.
CONFIG_HEAP_ABORT_WHEN_ALLOCATION_FAILS Abort if memory allocation fails Found in: Component config > Heap memory debugging When enabled, if a memory allocation operation fails it will cause a system abort. Default value: · No (disabled)
Log output Contains: · CONFIG_LOG_DEFAULT_LEVEL · CONFIG_LOG_TIMESTAMP_SOURCE · CONFIG_LOG_MAXIMUM_LEVEL · CONFIG_LOG_COLORS
CONFIG_LOG_DEFAULT_LEVEL Default log verbosity Found in: Component config > Log output Specify how much output to see in logs by default. You can set lower verbosity level at runtime using esp_log_level_set function. By default, this setting limits which log statements are compiled into the program. For example, selecting
oWarningpwould mean that changing log level to oDebugpat runtime will not be possible. To allow increasing log level above the default at runtime, see the next option. Available options: · No output (LOG_DEFAULT_LEVEL_NONE) · Error (LOG_DEFAULT_LEVEL_ERROR) · Warning (LOG_DEFAULT_LEVEL_WARN) · Info (LOG_DEFAULT_LEVEL_INFO) · Debug (LOG_DEFAULT_LEVEL_DEBUG) · Verbose (LOG_DEFAULT_LEVEL_VERBOSE)

Espressif Systems

1514

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_LOG_MAXIMUM_LEVEL
Maximum log verbosity
Found in: Component config > Log output
This config option sets the highest log verbosity that itns possible to select at runtime by calling esp_log_level_set(). This level may be higher than the default verbosity level which is set when the app starts up.
This can be used enable debugging output only at a critical point, for a particular tag, or to minimize startup time but then enable more logs once the firmware has loaded.
Note that increasing the maximum available log level will increase the firmware binary size.
This option only applies to logging from the app, the bootloader log level is fixed at compile time to the separate oBootloader log verbositypsetting.
Available options: · Same as default (LOG_MAXIMUM_EQUALS_DEFAULT) · Error (LOG_MAXIMUM_LEVEL_ERROR) · Warning (LOG_MAXIMUM_LEVEL_WARN) · Info (LOG_MAXIMUM_LEVEL_INFO) · Debug (LOG_MAXIMUM_LEVEL_DEBUG) · Verbose (LOG_MAXIMUM_LEVEL_VERBOSE)

CONFIG_LOG_COLORS Use ANSI terminal colors in log output Found in: Component config > Log output Enable ANSI terminal color codes in bootloader output. In order to view these, your terminal program must support ANSI color codes. Default value: · Yes (enabled)

CONFIG_LOG_TIMESTAMP_SOURCE
Log Timestamps
Found in: Component config > Log output
Choose what sort of timestamp is displayed in the log output:
· Milliseconds since boot is calulated from the RTOS tick count multiplied by the tick period. This time will reset after a software reboot. e.g. (90000)
· System time is taken from POSIX time functions which use the ESP32ns RTC and FRC1 timers to maintain an accurate time. The system time is initialized to 0 on startup, it can be set with an SNTP sync, or with POSIX time functions. This time will not reset after a software reboot. e.g. (00:01:30.000)
· NOTE: Currently this will not get used in logging from binary blobs (i.e WiFi & Bluetooth libraries), these will always print milliseconds since boot.
Available options: · Milliseconds Since Boot (LOG_TIMESTAMP_SOURCE_RTOS) · System Time (LOG_TIMESTAMP_SOURCE_SYSTEM)

LWIP Contains:
· Checksums · DHCP server · CONFIG_LWIP_DHCP_OPTIONS_LEN

Espressif Systems

1515

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· CONFIG_LWIP_DHCP_DISABLE_CLIENT_ID · CONFIG_LWIP_DHCP_DISABLE_VENDOR_CLASS_ID · CONFIG_LWIP_DHCP_DOES_ARP_CHECK · CONFIG_LWIP_DHCP_RESTORE_LAST_IP · CONFIG_LWIP_PPP_CHAP_SUPPORT · CONFIG_LWIP_L2_TO_L3_COPY · CONFIG_LWIP_IPV6_DHCP6 · CONFIG_LWIP_IP4_FRAG · CONFIG_LWIP_IP6_FRAG · CONFIG_LWIP_IP_FORWARD · CONFIG_LWIP_NETBUF_RECVINFO · CONFIG_LWIP_AUTOIP · CONFIG_LWIP_IPV6 · CONFIG_LWIP_ENABLE_LCP_ECHO · CONFIG_LWIP_ESP_LWIP_ASSERT · CONFIG_LWIP_DEBUG · CONFIG_LWIP_IRAM_OPTIMIZATION · CONFIG_LWIP_STATS · CONFIG_LWIP_TIMERS_ONDEMAND · CONFIG_LWIP_DNS_SUPPORT_MDNS_QUERIES · CONFIG_LWIP_PPP_MPPE_SUPPORT · CONFIG_LWIP_PPP_MSCHAP_SUPPORT · CONFIG_LWIP_PPP_NOTIFY_PHASE_SUPPORT · CONFIG_LWIP_PPP_PAP_SUPPORT · CONFIG_LWIP_PPP_DEBUG_ON · CONFIG_LWIP_PPP_SUPPORT · CONFIG_LWIP_IP4_REASSEMBLY · CONFIG_LWIP_IP6_REASSEMBLY · CONFIG_LWIP_SLIP_SUPPORT · CONFIG_LWIP_SO_LINGER · CONFIG_LWIP_SO_RCVBUF · CONFIG_LWIP_SO_REUSE · CONFIG_LWIP_NETIF_STATUS_CALLBACK · CONFIG_LWIP_TCPIP_CORE_LOCKING · CONFIG_LWIP_NETIF_API · Hooks · ICMP · CONFIG_LWIP_LOCAL_HOSTNAME · LWIP RAW API · CONFIG_LWIP_IPV6_ND6_NUM_NEIGHBORS · CONFIG_LWIP_IPV6_MEMP_NUM_ND6_QUEUE · CONFIG_LWIP_MAX_SOCKETS · CONFIG_LWIP_ESP_GRATUITOUS_ARP · SNTP · CONFIG_LWIP_USE_ONLY_LWIP_SELECT · CONFIG_LWIP_NETIF_LOOPBACK · TCP · CONFIG_LWIP_TCPIP_TASK_AFFINITY · CONFIG_LWIP_TCPIP_TASK_STACK_SIZE · CONFIG_LWIP_TCPIP_RECVMBOX_SIZE · UDP · CONFIG_LWIP_IPV6_RDNSS_MAX_DNS_SERVERS
CONFIG_LWIP_LOCAL_HOSTNAME
Local netif hostname
Found in: Component config > LWIP

Espressif Systems

1516

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
The default name this device will report to other devices on the network. Could be updated at runtime with esp_netif_set_hostname() Default value:
·oespressifp
CONFIG_LWIP_NETIF_API Enable usage of standard POSIX APIs in LWIP Found in: Component config > LWIP If this feature is enabled, standard POSIX APIs: if_indextoname(), if_nametoindex() could be used to convert network interface index to name instead of IDF specific esp-netif APIs (such as esp_netif_get_netif_impl_name()) Default value: · No (disabled)
CONFIG_LWIP_TCPIP_CORE_LOCKING Enable tcpip ` core locking Found in: Component config > LWIP If Enable tcpip ` core locking,Creates a global mutex that is held during TCPIP thread operations.Can be locked by client code to perform lwIP operations without changing into TCPIP thread using callbacks. See LOCK_TCPIP_CORE() and UNLOCK_TCPIP_CORE(). If disable tcpip ` core locking,TCP IP will perform tasks through context switching Default value: · No (disabled)
CONFIG_LWIP_DNS_SUPPORT_MDNS_QUERIES Enable mDNS queries in resolving host name Found in: Component config > LWIP If this feature is enabled, standard API such as gethostbyname support .local addresses by sending one shot multicast mDNS query Default value: · Yes (enabled)
CONFIG_LWIP_L2_TO_L3_COPY Enable copy between Layer2 and Layer3 packets Found in: Component config > LWIP If this feature is enabled, all traffic from layer2(WIFI Driver) will be copied to a new buffer before sending it to layer3(LWIP stack), freeing the layer2 buffer. Please be notified that the total layer2 receiving buffer is fixed and ESP32 currently supports 25 layer2 receiving buffer, when layer2 buffer runs out of memory, then the incoming packets will be dropped in hardware. The layer3 buffer is allocated from the heap, so the total layer3 receiving buffer depends on the available heap size, when heap runs out of memory, no copy will be sent to layer3 and packet will be dropped in layer2. Please make sure you fully understand the impact of this feature before enabling it. Default value: · No (disabled)

Espressif Systems

1517

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_LWIP_IRAM_OPTIMIZATION
Enable LWIP IRAM optimization
Found in: Component config > LWIP
If this feature is enabled, some functions relating to RX/TX in LWIP will be put into IRAM, it can improve UDP/TCP throughput by >10% for single core mode, it doesnnt help too much for dual core mode. On the other hand, it needs about 10KB IRAM for these optimizations.
If this feature is disabled, all lwip functions will be put into FLASH.
Default value: · No (disabled)

CONFIG_LWIP_TIMERS_ONDEMAND
Enable LWIP Timers on demand
Found in: Component config > LWIP
If this feature is enabled, IGMP and MLD6 timers will be activated only when joining groups or receiving QUERY packets.
This feature will reduce the power consumption for applications which do not use IGMP and MLD6.
Default value: · Yes (enabled)

CONFIG_LWIP_MAX_SOCKETS
Max number of open sockets
Found in: Component config > LWIP
Sockets take up a certain amount of memory, and allowing fewer sockets to be open at the same time conserves memory. Specify the maximum amount of sockets here. The valid value is from 1 to 16.
Range: · from 1 to 16
Default value: · 10

CONFIG_LWIP_USE_ONLY_LWIP_SELECT Support LWIP socket select() only (DEPRECATED) Found in: Component config > LWIP This option is deprecated. Do not use this option, use VFS_SUPPORT_SELECT instead. Default value: · No (disabled)

CONFIG_LWIP_SO_LINGER
Enable SO_LINGER processing
Found in: Component config > LWIP
Enabling this option allows SO_LINGER processing. l_onoff = 1,l_linger can set the timeout.
If l_linger=0, When a connection is closed, TCP will terminate the connection. This means that TCP will discard any data packets stored in the socket send buffer and send an RST to the peer.
If l_linger!=0,Then closesocket() calls to block the process until the remaining data packets has been sent or timed out.

Espressif Systems

1518

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Default value: · No (disabled)
CONFIG_LWIP_SO_REUSE Enable SO_REUSEADDR option Found in: Component config > LWIP Enabling this option allows binding to a port which remains in TIME_WAIT. Default value: · Yes (enabled)
CONFIG_LWIP_SO_REUSE_RXTOALL SO_REUSEADDR copies broadcast/multicast to all matches Found in: Component config > LWIP > CONFIG_LWIP_SO_REUSE Enabling this option means that any incoming broadcast or multicast packet will be copied to all of the local sockets that it matches (may be more than one if SO_REUSEADDR is set on the socket.) This increases memory overhead as the packets need to be copied, however they are only copied per matching socket. You can safely disable it if you donnt plan to receive broadcast or multicast traffic on more than one socket at a time. Default value: · Yes (enabled)
CONFIG_LWIP_SO_RCVBUF Enable SO_RCVBUF option Found in: Component config > LWIP Enabling this option allows checking for available data on a netconn. Default value: · No (disabled)
CONFIG_LWIP_NETBUF_RECVINFO Enable IP_PKTINFO option Found in: Component config > LWIP Enabling this option allows checking for the destination address of a received IPv4 Packet. Default value: · No (disabled)
CONFIG_LWIP_IP4_FRAG Enable fragment outgoing IP4 packets Found in: Component config > LWIP Enabling this option allows fragmenting outgoing IP4 packets if their size exceeds MTU. Default value: · Yes (enabled)

Espressif Systems

1519

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_LWIP_IP6_FRAG Enable fragment outgoing IP6 packets Found in: Component config > LWIP Enabling this option allows fragmenting outgoing IP6 packets if their size exceeds MTU. Default value: · Yes (enabled)
CONFIG_LWIP_IP4_REASSEMBLY Enable reassembly incoming fragmented IP4 packets Found in: Component config > LWIP Enabling this option allows reassemblying incoming fragmented IP4 packets. Default value: · No (disabled)
CONFIG_LWIP_IP6_REASSEMBLY Enable reassembly incoming fragmented IP6 packets Found in: Component config > LWIP Enabling this option allows reassemblying incoming fragmented IP6 packets. Default value: · No (disabled)
CONFIG_LWIP_IP_FORWARD Enable IP forwarding Found in: Component config > LWIP Enabling this option allows packets forwarding across multiple interfaces. Default value: · No (disabled)
CONFIG_LWIP_IPV4_NAPT Enable NAT (new/experimental) Found in: Component config > LWIP > CONFIG_LWIP_IP_FORWARD Enabling this option allows Network Address and Port Translation. Default value: · No (disabled) if CONFIG_LWIP_IP_FORWARD
CONFIG_LWIP_STATS Enable LWIP statistics Found in: Component config > LWIP Enabling this option allows LWIP statistics Default value: · No (disabled)

Espressif Systems

1520

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_LWIP_ESP_GRATUITOUS_ARP Send gratuitous ARP periodically Found in: Component config > LWIP Enable this option allows to send gratuitous ARP periodically. This option solve the compatibility issues.If the ARP table of the AP is old, and the AP doesnnt send ARP request to update itns ARP table, this will lead to the STA sending IP packet fail. Thus we send gratuitous ARP periodically to let AP update itns ARP table. Default value: · Yes (enabled)
CONFIG_LWIP_GARP_TMR_INTERVAL GARP timer interval(seconds) Found in: Component config > LWIP > CONFIG_LWIP_ESP_GRATUITOUS_ARP Set the timer interval for gratuitous ARP. The default value is 60s Default value: · 60
CONFIG_LWIP_TCPIP_RECVMBOX_SIZE TCPIP task receive mail box size Found in: Component config > LWIP Set TCPIP task receive mail box size. Generally bigger value means higher throughput but more memory. The value should be bigger than UDP/TCP mail box size. Range: · from 6 to 64 if CONFIG_LWIP_WND_SCALE · from 6 to 1024 if CONFIG_LWIP_WND_SCALE Default value: · 32
CONFIG_LWIP_DHCP_DOES_ARP_CHECK DHCP: Perform ARP check on any offered address Found in: Component config > LWIP Enabling this option performs a check (via ARP request) if the offered IP address is not already in use by another host on the network. Default value: · Yes (enabled)
CONFIG_LWIP_DHCP_DISABLE_CLIENT_ID DHCP: Disable Use of HW address as client identification Found in: Component config > LWIP This option could be used to disable DHCP client identification with its MAC address. (Client id is used by DHCP servers to uniquely identify clients and are included in the DHCP packets as an option 61) Set this option to oypin order to exclude option 61 from DHCP packets. Default value: · No (disabled)

Espressif Systems

1521

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_LWIP_DHCP_DISABLE_VENDOR_CLASS_ID
DHCP: Disable Use of vendor class identification
Found in: Component config > LWIP
This option could be used to disable DHCP client vendor class identification. Set this option to oypin order to exclude option 60 from DHCP packets.
Default value: · Yes (enabled)

CONFIG_LWIP_DHCP_RESTORE_LAST_IP
DHCP: Restore last IP obtained from DHCP server
Found in: Component config > LWIP
When this option is enabled, DHCP client tries to re-obtain last valid IP address obtained from DHCP server. Last valid DHCP configuration is stored in nvs and restored after reset/power-up. If IP is still available, there is no need for sending discovery message to DHCP server and save some time.
Default value: · No (disabled)

CONFIG_LWIP_DHCP_OPTIONS_LEN
DHCP total option length
Found in: Component config > LWIP
Set total length of outgoing DHCP option msg. Generally bigger value means it can carry more options and values. If your code meets LWIP_ASSERT due to option value is too long. Please increase the LWIP_DHCP_OPTIONS_LEN value.
Range: · from 68 to 255
Default value: · 68 · 108

DHCP server Contains: · CONFIG_LWIP_DHCPS

CONFIG_LWIP_DHCPS
DHCPS: Enable IPv4 Dynamic Host Configuration Protocol Server (DHCPS)
Found in: Component config > LWIP > DHCP server
Enabling this option allows the device to run the DHCP server (to dynamically assign IPv4 addresses to clients).
Default value: · Yes (enabled)

CONFIG_LWIP_DHCPS_LEASE_UNIT Multiplier for lease time, in seconds Found in: Component config > LWIP > DHCP server > CONFIG_LWIP_DHCPS The DHCP server is calculating lease time multiplying the sent and received times by this number of seconds per unit. The default is 60, that equals one minute.

Espressif Systems

1522

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Range: · from 1 to 3600
Default value: · 60
CONFIG_LWIP_DHCPS_MAX_STATION_NUM Maximum number of stations Found in: Component config > LWIP > DHCP server > CONFIG_LWIP_DHCPS The maximum number of DHCP clients that are connected to the server. After this number is exceeded, DHCP server removes of the oldest device from itns address pool, without notification. Range: · from 1 to 64 Default value: ·8
CONFIG_LWIP_AUTOIP Enable IPV4 Link-Local Addressing (AUTOIP) Found in: Component config > LWIP Enabling this option allows the device to self-assign an address in the 169.256/16 range if none is assigned statically or via DHCP. See RFC 3927. Default value: · No (disabled)
Contains: · CONFIG_LWIP_AUTOIP_TRIES · CONFIG_LWIP_AUTOIP_MAX_CONFLICTS · CONFIG_LWIP_AUTOIP_RATE_LIMIT_INTERVAL
CONFIG_LWIP_AUTOIP_TRIES DHCP Probes before self-assigning IPv4 LL address Found in: Component config > LWIP > CONFIG_LWIP_AUTOIP DHCP client will send this many probes before self-assigning a link local address. From LWIP help: oThis can be set as low as 1 to get an AutoIP address very quickly, but you should be prepared to handle a changing IP address when DHCP overrides AutoIP.p(In the case of ESP-IDF, this means multiple SYSTEM_EVENT_STA_GOT_IP events.) Range: · from 1 to 100 if CONFIG_LWIP_AUTOIP Default value: · 2 if CONFIG_LWIP_AUTOIP
CONFIG_LWIP_AUTOIP_MAX_CONFLICTS Max IP conflicts before rate limiting Found in: Component config > LWIP > CONFIG_LWIP_AUTOIP If the AUTOIP functionality detects this many IP conflicts while self-assigning an address, it will go into a rate limited mode.

Espressif Systems

1523

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Range: · from 1 to 100 if CONFIG_LWIP_AUTOIP
Default value: · 9 if CONFIG_LWIP_AUTOIP
CONFIG_LWIP_AUTOIP_RATE_LIMIT_INTERVAL Rate limited interval (seconds) Found in: Component config > LWIP > CONFIG_LWIP_AUTOIP If rate limiting self-assignment requests, wait this long between each request. Range: · from 5 to 120 if CONFIG_LWIP_AUTOIP Default value: · 20 if CONFIG_LWIP_AUTOIP
CONFIG_LWIP_IPV6 Enable IPv6 Found in: Component config > LWIP Enable IPv6 function. If not use IPv6 function, set this option to n. If disabling LWIP_IPV6 then some other components (coap and asio) will no longer be available. Default value: · Yes (enabled)
CONFIG_LWIP_IPV6_AUTOCONFIG Enable IPV6 stateless address autoconfiguration (SLAAC) Found in: Component config > LWIP > CONFIG_LWIP_IPV6 Enabling this option allows the devices to IPV6 stateless address autoconfiguration (SLAAC). See RFC 4862. Default value: · No (disabled)
CONFIG_LWIP_IPV6_NUM_ADDRESSES Number of IPv6 addresses on each network interface Found in: Component config > LWIP > CONFIG_LWIP_IPV6 The maximum number of IPv6 addresses on each interface. Any additional addresses will be discarded. Default value: ·3
CONFIG_LWIP_IPV6_FORWARD Enable IPv6 forwarding between interfaces Found in: Component config > LWIP > CONFIG_LWIP_IPV6 Forwarding IPv6 packets between interfaces is only required when acting as a router. Default value: · No (disabled)

Espressif Systems

1524

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_LWIP_IPV6_RDNSS_MAX_DNS_SERVERS Use IPv6 Router Advertisement Recursive DNS Server Option Found in: Component config > LWIP Use IPv6 Router Advertisement Recursive DNS Server Option (as per RFC 6106) to copy a defined maximum number of DNS servers to the DNS module. Set this option to a number of desired DNS servers advertised in the RA protocol. This feature is disabled when set to 0. Default value: · 0 if CONFIG_LWIP_IPV6_AUTOCONFIG
CONFIG_LWIP_IPV6_DHCP6 Enable DHCPv6 stateless address autoconfiguration Found in: Component config > LWIP Enable DHCPv6 for IPv6 stateless address autoconfiguration. Note that the dhcpv6 client has to be started using dhcp6_enable_stateless(netif); Note that the stateful address autoconfiguration is not supported. Default value: · No (disabled) if CONFIG_LWIP_IPV6_AUTOCONFIG
CONFIG_LWIP_NETIF_STATUS_CALLBACK Enable status callback for network interfaces Found in: Component config > LWIP Enable callbacks when the network interface is up/down and addresses are changed. Default value: · No (disabled)
CONFIG_LWIP_NETIF_LOOPBACK Support per-interface loopback Found in: Component config > LWIP Enabling this option means that if a packet is sent with a destination address equal to the interfacens own IP address, it will oloop backpand be received by this interface. Disabling this option disables support of loopback interface in lwIP Default value: · Yes (enabled)
Contains: · CONFIG_LWIP_LOOPBACK_MAX_PBUFS
CONFIG_LWIP_LOOPBACK_MAX_PBUFS Max queued loopback packets per interface Found in: Component config > LWIP > CONFIG_LWIP_NETIF_LOOPBACK Configure the maximum number of packets which can be queued for loopback on a given interface. Reducing this number may cause packets to be dropped, but will avoid filling memory with queued packet data. Range: · from 0 to 16

Espressif Systems

1525

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Default value: ·8
TCP Contains:
· CONFIG_LWIP_TCP_WND_DEFAULT · CONFIG_LWIP_TCP_SND_BUF_DEFAULT · CONFIG_LWIP_TCP_RECVMBOX_SIZE · CONFIG_LWIP_TCP_RTO_TIME · CONFIG_LWIP_MAX_ACTIVE_TCP · CONFIG_LWIP_MAX_LISTENING_TCP · CONFIG_LWIP_TCP_MAXRTX · CONFIG_LWIP_TCP_SYNMAXRTX · CONFIG_LWIP_TCP_MSL · CONFIG_LWIP_TCP_MSS · CONFIG_LWIP_TCP_OVERSIZE · CONFIG_LWIP_TCP_QUEUE_OOSEQ · CONFIG_LWIP_WND_SCALE · CONFIG_LWIP_TCP_HIGH_SPEED_RETRANSMISSION · CONFIG_LWIP_TCP_TMR_INTERVAL
CONFIG_LWIP_MAX_ACTIVE_TCP
Maximum active TCP Connections
Found in: Component config > LWIP > TCP
The maximum number of simultaneously active TCP connections. The practical maximum limit is determined by available heap memory at runtime.
Changing this value by itself does not substantially change the memory usage of LWIP, except for preventing new TCP connections after the limit is reached.
Range: · from 1 to 1024
Default value: · 16
CONFIG_LWIP_MAX_LISTENING_TCP
Maximum listening TCP Connections
Found in: Component config > LWIP > TCP
The maximum number of simultaneously listening TCP connections. The practical maximum limit is determined by available heap memory at runtime.
Changing this value by itself does not substantially change the memory usage of LWIP, except for preventing new listening TCP connections after the limit is reached.
Range: · from 1 to 1024
Default value: · 16
CONFIG_LWIP_TCP_HIGH_SPEED_RETRANSMISSION
TCP high speed retransmissions
Found in: Component config > LWIP > TCP

Espressif Systems

1526

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Speed up the TCP retransmission interval. If disabled, it is recommended to change the number of SYN retransmissions to 6, and TCP initial rto time to 3000. Default value:
· Yes (enabled)
CONFIG_LWIP_TCP_MAXRTX Maximum number of retransmissions of data segments Found in: Component config > LWIP > TCP Set maximum number of retransmissions of data segments. Range: · from 3 to 12 Default value: · 12
CONFIG_LWIP_TCP_SYNMAXRTX Maximum number of retransmissions of SYN segments Found in: Component config > LWIP > TCP Set maximum number of retransmissions of SYN segments. Range: · from 3 to 12 Default value: ·6 · 12
CONFIG_LWIP_TCP_MSS Maximum Segment Size (MSS) Found in: Component config > LWIP > TCP Set maximum segment size for TCP transmission. Can be set lower to save RAM, the default value 1460(ipv4)/1440(ipv6) will give best throughput. IPv4 TCP_MSS Range: 576 <= TCP_MSS <= 1460 IPv6 TCP_MSS Range: 1220<= TCP_mSS <= 1440 Range: · from 536 to 1460 Default value: · 1440
CONFIG_LWIP_TCP_TMR_INTERVAL TCP timer interval(ms) Found in: Component config > LWIP > TCP Set TCP timer interval in milliseconds. Can be used to speed connections on bad networks. A lower value will redeliver unacked packets faster. Default value: · 250

Espressif Systems

1527

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_LWIP_TCP_MSL Maximum segment lifetime (MSL) Found in: Component config > LWIP > TCP Set maximum segment lifetime in in milliseconds. Default value: · 60000
CONFIG_LWIP_TCP_SND_BUF_DEFAULT Default send buffer size Found in: Component config > LWIP > TCP Set default send buffer size for new TCP sockets. Per-socket send buffer size can be changed at runtime with lwip_setsockopt(s, TCP_SNDBUF, l). This value must be at least 2x the MSS size, and the default is 4x the default MSS size. Setting a smaller default SNDBUF size can save some RAM, but will decrease performance. Range: · from 2440 to 65535 if CONFIG_LWIP_WND_SCALE · from 2440 to 1024000 if CONFIG_LWIP_WND_SCALE Default value: · 5744
CONFIG_LWIP_TCP_WND_DEFAULT Default receive window size Found in: Component config > LWIP > TCP Set default TCP receive window size for new TCP sockets. Per-socket receive window size can be changed at runtime with lwip_setsockopt(s, TCP_WINDOW, l ). Setting a smaller default receive window size can save some RAM, but will significantly decrease performance. Range: · from 2440 to 65535 if CONFIG_LWIP_WND_SCALE · from 2440 to 1024000 if CONFIG_LWIP_WND_SCALE Default value: · 5744
CONFIG_LWIP_TCP_RECVMBOX_SIZE Default TCP receive mail box size Found in: Component config > LWIP > TCP Set TCP receive mail box size. Generally bigger value means higher throughput but more memory. The recommended value is: LWIP_TCP_WND_DEFAULT/TCP_MSS + 2, e.g. if LWIP_TCP_WND_DEFAULT=14360, TCP_MSS=1436, then the recommended receive mail box size is (14360/1436 + 2) = 12. TCP receive mail box is a per socket mail box, when the application receives packets from TCP socket, LWIP core firstly posts the packets to TCP receive mail box and the application then fetches the packets from mail box. It means LWIP can caches maximum LWIP_TCP_RECCVMBOX_SIZE packets for each TCP socket, so the maximum possible cached TCP packets for all TCP sockets is

Espressif Systems

1528

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
LWIP_TCP_RECCVMBOX_SIZE multiples the maximum TCP socket number. In other words, the bigger LWIP_TCP_RECVMBOX_SIZE means more memory. On the other hand, if the receiv mail box is too small, the mail box may be full. If the mail box is full, the LWIP drops the packets. So generally we need to make sure the TCP receive mail box is big enough to avoid packet drop between LWIP core and application. Range:
· from 6 to 64 if CONFIG_LWIP_WND_SCALE · from 6 to 1024 if CONFIG_LWIP_WND_SCALE Default value: ·6
CONFIG_LWIP_TCP_QUEUE_OOSEQ Queue incoming out-of-order segments Found in: Component config > LWIP > TCP Queue incoming out-of-order segments for later use. Disable this option to save some RAM during TCP sessions, at the expense of increased retransmissions if segments arrive out of order. Default value: · Yes (enabled)
CONFIG_LWIP_TCP_SACK_OUT Support sending selective acknowledgements Found in: Component config > LWIP > TCP > CONFIG_LWIP_TCP_QUEUE_OOSEQ TCP will support sending selective acknowledgements (SACKs). Default value: · No (disabled)
CONFIG_LWIP_TCP_OVERSIZE Pre-allocate transmit PBUF size Found in: Component config > LWIP > TCP Allows enabling ooversizepallocation of TCP transmission pbufs ahead of time, which can reduce the length of pbuf chains used for transmission. This will not make a difference to sockets where Naglens algorithm is disabled. Default value of MSS is fine for most applications, 25% MSS may save some RAM when only transmitting small amounts of data. Disabled will have worst performance and fragmentation characteristics, but uses least RAM overall. Available options: · MSS (LWIP_TCP_OVERSIZE_MSS) · 25% MSS (LWIP_TCP_OVERSIZE_QUARTER_MSS) · Disabled (LWIP_TCP_OVERSIZE_DISABLE)
CONFIG_LWIP_WND_SCALE Support TCP window scale Found in: Component config > LWIP > TCP Enable this feature to support TCP window scaling.

Espressif Systems

1529

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Default value: · No (disabled) if CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP
CONFIG_LWIP_TCP_RCV_SCALE Set TCP receiving window scaling factor Found in: Component config > LWIP > TCP > CONFIG_LWIP_WND_SCALE Enable this feature to support TCP window scaling. Range: · from 0 to 14 if CONFIG_LWIP_WND_SCALE Default value: · 0 if CONFIG_LWIP_WND_SCALE
CONFIG_LWIP_TCP_RTO_TIME Default TCP rto time Found in: Component config > LWIP > TCP Set default TCP rto time for a reasonable initial rto. In bad network environment, recommend set value of rto time to 1500. Default value: · 3000 · 1500
UDP Contains: · CONFIG_LWIP_UDP_RECVMBOX_SIZE · CONFIG_LWIP_MAX_UDP_PCBS
CONFIG_LWIP_MAX_UDP_PCBS Maximum active UDP control blocks Found in: Component config > LWIP > UDP The maximum number of active UDP oconnectionsp(ie UDP sockets sending/receiving data). The practical maximum limit is determined by available heap memory at runtime. Range: · from 1 to 1024 Default value: · 16
CONFIG_LWIP_UDP_RECVMBOX_SIZE Default UDP receive mail box size Found in: Component config > LWIP > UDP Set UDP receive mail box size. The recommended value is 6. UDP receive mail box is a per socket mail box, when the application receives packets from UDP socket, LWIP core firstly posts the packets to UDP receive mail box and the application then fetches the packets from mail box. It means LWIP can caches maximum UDP_RECCVMBOX_SIZE packets for each UDP socket, so the maximum possible cached UDP packets for all UDP sockets is UDP_RECCVMBOX_SIZE multiples the maximum UDP socket number. In other words, the bigger UDP_RECVMBOX_SIZE means more memory. On the other hand, if the receiv mail box is too small, the mail box may be full. If the mail box is full, the LWIP drops the packets. So generally we

Espressif Systems

1530

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
need to make sure the UDP receive mail box is big enough to avoid packet drop between LWIP core and application. Range:
· from 6 to 64 Default value:
·6
Checksums Contains: · CONFIG_LWIP_CHECKSUM_CHECK_ICMP · CONFIG_LWIP_CHECKSUM_CHECK_IP · CONFIG_LWIP_CHECKSUM_CHECK_UDP
CONFIG_LWIP_CHECKSUM_CHECK_IP Enable LWIP IP checksums Found in: Component config > LWIP > Checksums Enable checksum checking for received IP messages Default value: · No (disabled)
CONFIG_LWIP_CHECKSUM_CHECK_UDP Enable LWIP UDP checksums Found in: Component config > LWIP > Checksums Enable checksum checking for received UDP messages Default value: · No (disabled)
CONFIG_LWIP_CHECKSUM_CHECK_ICMP Enable LWIP ICMP checksums Found in: Component config > LWIP > Checksums Enable checksum checking for received ICMP messages Default value: · Yes (enabled)
CONFIG_LWIP_TCPIP_TASK_STACK_SIZE TCP/IP Task Stack Size Found in: Component config > LWIP Configure TCP/IP task stack size, used by LWIP to process multi-threaded TCP/IP operations. Setting this stack too small will result in stack overflow crashes. Range: · from 2048 to 65536 Default value: · 3072

Espressif Systems

1531

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_LWIP_TCPIP_TASK_AFFINITY
TCP/IP task affinity
Found in: Component config > LWIP
Allows setting LwIP tasks affinity, i.e. whether the task is pinned to CPU0, pinned to CPU1, or allowed to run on any CPU. Currently this applies to oTCP/IPptask and oPingptask.
Available options: · No affinity (LWIP_TCPIP_TASK_AFFINITY_NO_AFFINITY) · CPU0 (LWIP_TCPIP_TASK_AFFINITY_CPU0) · CPU1 (LWIP_TCPIP_TASK_AFFINITY_CPU1)

CONFIG_LWIP_PPP_SUPPORT Enable PPP support (new/experimental) Found in: Component config > LWIP Enable PPP stack. Now only PPP over serial is possible. PPP over serial support is experimental and unsupported. Default value: · No (disabled)
Contains: · CONFIG_LWIP_PPP_ENABLE_IPV6

CONFIG_LWIP_PPP_ENABLE_IPV6
Enable IPV6 support for PPP connections (IPV6CP)
Found in: Component config > LWIP > CONFIG_LWIP_PPP_SUPPORT
Enable IPV6 support in PPP for the local link between the DTE (processor) and DCE (modem). There are some modems which do not support the IPV6 addressing in the local link. If they are requested for IPV6CP negotiation, they may time out. This would in turn fail the configuration for the whole link. If your modem is not responding correctly to PPP Phase Network, try to disable IPV6 support.
Default value: · Yes (enabled) if CONFIG_LWIP_PPP_SUPPORT && CONFIG_LWIP_IPV6

CONFIG_LWIP_IPV6_MEMP_NUM_ND6_QUEUE
Max number of IPv6 packets to queue during MAC resolution
Found in: Component config > LWIP
Config max number of IPv6 packets to queue during MAC resolution.
Range: · from 3 to 20
Default value: ·3

CONFIG_LWIP_IPV6_ND6_NUM_NEIGHBORS Max number of entries in IPv6 neighbor cache Found in: Component config > LWIP Config max number of entries in IPv6 neighbor cache Range:

Espressif Systems

1532

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· from 3 to 10 Default value:
·5
CONFIG_LWIP_PPP_NOTIFY_PHASE_SUPPORT Enable Notify Phase Callback Found in: Component config > LWIP Enable to set a callback which is called on change of the internal PPP state machine. Default value: · No (disabled) if CONFIG_LWIP_PPP_SUPPORT
CONFIG_LWIP_PPP_PAP_SUPPORT Enable PAP support Found in: Component config > LWIP Enable Password Authentication Protocol (PAP) support Default value: · No (disabled) if CONFIG_LWIP_PPP_SUPPORT
CONFIG_LWIP_PPP_CHAP_SUPPORT Enable CHAP support Found in: Component config > LWIP Enable Challenge Handshake Authentication Protocol (CHAP) support Default value: · No (disabled) if CONFIG_LWIP_PPP_SUPPORT
CONFIG_LWIP_PPP_MSCHAP_SUPPORT Enable MSCHAP support Found in: Component config > LWIP Enable Microsoft version of the Challenge-Handshake Authentication Protocol (MSCHAP) support Default value: · No (disabled) if CONFIG_LWIP_PPP_SUPPORT
CONFIG_LWIP_PPP_MPPE_SUPPORT Enable MPPE support Found in: Component config > LWIP Enable Microsoft Point-to-Point Encryption (MPPE) support Default value: · No (disabled) if CONFIG_LWIP_PPP_SUPPORT

Espressif Systems

1533

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_LWIP_ENABLE_LCP_ECHO Enable LCP ECHO Found in: Component config > LWIP Enable LCP echo keepalive requests Default value: · No (disabled) if CONFIG_LWIP_PPP_SUPPORT
CONFIG_LWIP_LCP_ECHOINTERVAL Echo interval (s) Found in: Component config > LWIP > CONFIG_LWIP_ENABLE_LCP_ECHO Interval in seconds between keepalive LCP echo requests, 0 to disable. Range: · from 0 to 1000000 if CONFIG_LWIP_ENABLE_LCP_ECHO Default value: · 3 if CONFIG_LWIP_ENABLE_LCP_ECHO
CONFIG_LWIP_LCP_MAXECHOFAILS Maximum echo failures Found in: Component config > LWIP > CONFIG_LWIP_ENABLE_LCP_ECHO Number of consecutive unanswered echo requests before failure is indicated. Range: · from 0 to 100000 if CONFIG_LWIP_ENABLE_LCP_ECHO Default value: · 3 if CONFIG_LWIP_ENABLE_LCP_ECHO
CONFIG_LWIP_PPP_DEBUG_ON Enable PPP debug log output Found in: Component config > LWIP Enable PPP debug log output Default value: · No (disabled) if CONFIG_LWIP_PPP_SUPPORT
CONFIG_LWIP_SLIP_SUPPORT Enable SLIP support (new/experimental) Found in: Component config > LWIP Enable SLIP stack. Now only SLIP over serial is possible. SLIP over serial support is experimental and unsupported. Default value: · No (disabled)
Contains: · CONFIG_LWIP_SLIP_DEBUG_ON

Espressif Systems

1534

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_LWIP_SLIP_DEBUG_ON Enable SLIP debug log output Found in: Component config > LWIP > CONFIG_LWIP_SLIP_SUPPORT Enable SLIP debug log output Default value: · No (disabled) if CONFIG_LWIP_SLIP_SUPPORT
ICMP Contains: · CONFIG_LWIP_ICMP · CONFIG_LWIP_BROADCAST_PING · CONFIG_LWIP_MULTICAST_PING
CONFIG_LWIP_ICMP ICMP: Enable ICMP Found in: Component config > LWIP > ICMP Enable ICMP module for check network stability Default value: · Yes (enabled)
CONFIG_LWIP_MULTICAST_PING Respond to multicast pings Found in: Component config > LWIP > ICMP Default value: · No (disabled)
CONFIG_LWIP_BROADCAST_PING Respond to broadcast pings Found in: Component config > LWIP > ICMP Default value: · No (disabled)
LWIP RAW API Contains: · CONFIG_LWIP_MAX_RAW_PCBS
CONFIG_LWIP_MAX_RAW_PCBS Maximum LWIP RAW PCBs Found in: Component config > LWIP > LWIP RAW API The maximum number of simultaneously active LWIP RAW protocol control blocks. The practical maximum limit is determined by available heap memory at runtime. Range: · from 1 to 1024 Default value: · 16

Espressif Systems

1535

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

SNTP Contains:
· CONFIG_LWIP_SNTP_MAX_SERVERS · CONFIG_LWIP_SNTP_UPDATE_DELAY · CONFIG_LWIP_DHCP_GET_NTP_SRV

CONFIG_LWIP_SNTP_MAX_SERVERS
Maximum number of NTP servers
Found in: Component config > LWIP > SNTP
Set maximum number of NTP servers used by LwIP SNTP module. sntp_setserver/sntp_setservername functions is limited to this value.
Range: · from 1 to 16
Default value: ·1

First argument of

CONFIG_LWIP_DHCP_GET_NTP_SRV
Request NTP servers from DHCP
Found in: Component config > LWIP > SNTP
If enabled, LWIP will addmNTPnto Parameter-Request Option sent via DHCP-request. DHCP server might reply with an NTP server address in option 42. SNTP callback for such replies should be set accordingly (see sntp_servermode_dhcp() func.)
Default value: · No (disabled)

CONFIG_LWIP_DHCP_MAX_NTP_SERVERS
Maximum number of NTP servers aquired via DHCP
Found in: Component config > LWIP > SNTP > CONFIG_LWIP_DHCP_GET_NTP_SRV
Set maximum number of NTP servers aquired via DHCP-offer. Should be less or equal to oMaximum number of NTP serversp, any extra servers would be just ignored.
Range: · from 1 to 16 if CONFIG_LWIP_DHCP_GET_NTP_SRV
Default value: · 1 if CONFIG_LWIP_DHCP_GET_NTP_SRV

CONFIG_LWIP_SNTP_UPDATE_DELAY
Request interval to update time (ms)
Found in: Component config > LWIP > SNTP
This option allows you to set the time update period via SNTP. Default is 1 hour. Must not be below 15 seconds by specification. (SNTPv4 RFC 4330 enforces a minimum update time of 15 seconds).
Range: · from 15000 to 4294967295
Default value: · 3600000

Espressif Systems

1536

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_LWIP_ESP_LWIP_ASSERT Enable LWIP ASSERT checks Found in: Component config > LWIP Enable this option keeps LWIP assertion checks enabled. It is recommended to keep this option enabled. If asserts are disabled for the entire project, they are also disabled for LWIP and this option is ignored. Default value: · Yes (enabled) if COMPILER_OPTIMIZATION_ASSERTIONS_DISABLE

Hooks Contains:
· CONFIG_LWIP_HOOK_ND6_GET_GW · CONFIG_LWIP_HOOK_IP6_INPUT · CONFIG_LWIP_HOOK_IP6_ROUTE · CONFIG_LWIP_HOOK_NETCONN_EXTERNAL_RESOLVE · CONFIG_LWIP_HOOK_TCP_ISN

CONFIG_LWIP_HOOK_TCP_ISN

TCP ISN Hook

Found in: Component config > LWIP > Hooks

Enables to define a TCP ISN hook to randomize initial sequence number in TCP connection. The default TCP ISN algorithm used in IDF (standardized in RFC 6528) produces ISN by combining an MD5 of the new TCP id and a stable secret with the current time. This is because the lwIP implementation (tcp_next_iss) is not very strong, as it does not take into consideration any platform specific entropy source.

Set to LWIP_HOOK_TCP_ISN_CUSTOM to provide custom implementation. LWIP_HOOK_TCP_ISN_NONE to use lwIP implementation.

Set to

Available options: · No hook declared (LWIP_HOOK_TCP_ISN_NONE) · Default implementation (LWIP_HOOK_TCP_ISN_DEFAULT) · Custom implementation (LWIP_HOOK_TCP_ISN_CUSTOM)

CONFIG_LWIP_HOOK_IP6_ROUTE
IPv6 route Hook
Found in: Component config > LWIP > Hooks
Enables custom IPv6 route hook. Setting this to odefaultpprovides weak implementation stub that could be overwritten in application code. Setting this to ocustompprovides hookns declaration only and expects the application to implement it.
Available options: · No hook declared (LWIP_HOOK_IP6_ROUTE_NONE) · Default (weak) implementation (LWIP_HOOK_IP6_ROUTE_DEFAULT) · Custom implementation (LWIP_HOOK_IP6_ROUTE_CUSTOM)

CONFIG_LWIP_HOOK_ND6_GET_GW IPv6 get gateway Hook Found in: Component config > LWIP > Hooks

Espressif Systems

1537

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Enables custom IPv6 route hook. Setting this to odefaultpprovides weak implementation stub that could be overwritten in application code. Setting this to ocustompprovides hookns declaration only and expects the application to implement it.
Available options: · No hook declared (LWIP_HOOK_ND6_GET_GW_NONE) · Default (weak) implementation (LWIP_HOOK_ND6_GET_GW_DEFAULT) · Custom implementation (LWIP_HOOK_ND6_GET_GW_CUSTOM)

CONFIG_LWIP_HOOK_NETCONN_EXTERNAL_RESOLVE
Netconn external resolve Hook
Found in: Component config > LWIP > Hooks
Enables custom DNS resolve hook. Setting this to odefaultpprovides weak implementation stub that could be overwritten in application code. Setting this to ocustompprovides hookns declaration only and expects the application to implement it.
Available options: · No hook declared (LWIP_HOOK_NETCONN_EXT_RESOLVE_NONE) · Default (weak) implementation (LWIP_HOOK_NETCONN_EXT_RESOLVE_DEFAULT) · Custom implementation (LWIP_HOOK_NETCONN_EXT_RESOLVE_CUSTOM)

CONFIG_LWIP_HOOK_IP6_INPUT
IPv6 packet input
Found in: Component config > LWIP > Hooks
Enables custom IPv6 packet input. Setting this to odefaultpprovides weak implementation stub that could be overwritten in application code. Setting this to ocustompprovides hookns declaration only and expects the application to implement it.
Available options: · No hook declared (LWIP_HOOK_IP6_INPUT_NONE) · Default (weak) implementation (LWIP_HOOK_IP6_INPUT_DEFAULT) · Custom implementation (LWIP_HOOK_IP6_INPUT_CUSTOM)

CONFIG_LWIP_DEBUG
Enable LWIP Debug
Found in: Component config > LWIP
Enabling this option allows different kinds of lwIP debug output.
All lwIP debug features increase the size of the final binary.
Default value: · No (disabled)
Contains:
· CONFIG_LWIP_API_LIB_DEBUG · CONFIG_LWIP_DHCP_DEBUG · CONFIG_LWIP_DHCP_STATE_DEBUG · CONFIG_LWIP_ETHARP_DEBUG · CONFIG_LWIP_ICMP_DEBUG · CONFIG_LWIP_ICMP6_DEBUG · CONFIG_LWIP_IP_DEBUG · CONFIG_LWIP_IP6_DEBUG · CONFIG_LWIP_NETIF_DEBUG · CONFIG_LWIP_PBUF_DEBUG

Espressif Systems

1538

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· CONFIG_LWIP_SNTP_DEBUG · CONFIG_LWIP_SOCKETS_DEBUG · CONFIG_LWIP_TCP_DEBUG
CONFIG_LWIP_NETIF_DEBUG Enable netif debug messages Found in: Component config > LWIP > CONFIG_LWIP_DEBUG Default value: · No (disabled) if CONFIG_LWIP_DEBUG
CONFIG_LWIP_PBUF_DEBUG Enable pbuf debug messages Found in: Component config > LWIP > CONFIG_LWIP_DEBUG Default value: · No (disabled) if CONFIG_LWIP_DEBUG
CONFIG_LWIP_ETHARP_DEBUG Enable etharp debug messages Found in: Component config > LWIP > CONFIG_LWIP_DEBUG Default value: · No (disabled) if CONFIG_LWIP_DEBUG
CONFIG_LWIP_API_LIB_DEBUG Enable api lib debug messages Found in: Component config > LWIP > CONFIG_LWIP_DEBUG Default value: · No (disabled) if CONFIG_LWIP_DEBUG
CONFIG_LWIP_SOCKETS_DEBUG Enable socket debug messages Found in: Component config > LWIP > CONFIG_LWIP_DEBUG Default value: · No (disabled) if CONFIG_LWIP_DEBUG
CONFIG_LWIP_IP_DEBUG Enable IP debug messages Found in: Component config > LWIP > CONFIG_LWIP_DEBUG Default value: · No (disabled) if CONFIG_LWIP_DEBUG

Espressif Systems

1539

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_LWIP_ICMP_DEBUG Enable ICMP debug messages Found in: Component config > LWIP > CONFIG_LWIP_DEBUG Default value: · No (disabled) if CONFIG_LWIP_DEBUG && CONFIG_LWIP_ICMP
CONFIG_LWIP_DHCP_STATE_DEBUG Enable DHCP state tracking Found in: Component config > LWIP > CONFIG_LWIP_DEBUG Default value: · No (disabled) if CONFIG_LWIP_DEBUG
CONFIG_LWIP_DHCP_DEBUG Enable DHCP debug messages Found in: Component config > LWIP > CONFIG_LWIP_DEBUG Default value: · No (disabled) if CONFIG_LWIP_DEBUG
CONFIG_LWIP_IP6_DEBUG Enable IP6 debug messages Found in: Component config > LWIP > CONFIG_LWIP_DEBUG Default value: · No (disabled) if CONFIG_LWIP_DEBUG
CONFIG_LWIP_ICMP6_DEBUG Enable ICMP6 debug messages Found in: Component config > LWIP > CONFIG_LWIP_DEBUG Default value: · No (disabled) if CONFIG_LWIP_DEBUG
CONFIG_LWIP_TCP_DEBUG Enable TCP debug messages Found in: Component config > LWIP > CONFIG_LWIP_DEBUG Default value: · No (disabled) if CONFIG_LWIP_DEBUG
CONFIG_LWIP_SNTP_DEBUG Enable SNTP debug messages Found in: Component config > LWIP > CONFIG_LWIP_DEBUG Default value: · No (disabled) if CONFIG_LWIP_DEBUG

Espressif Systems

1540

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

mbedTLS Contains:
· CONFIG_MBEDTLS_ASYMMETRIC_CONTENT_LEN · Certificate Bundle · Certificates · CONFIG_MBEDTLS_CHACHA20_C · CONFIG_MBEDTLS_DHM_C · CONFIG_MBEDTLS_ECP_C · CONFIG_MBEDTLS_ECDH_C · CONFIG_MBEDTLS_ECJPAKE_C · CONFIG_MBEDTLS_ECP_DP_BP256R1_ENABLED · CONFIG_MBEDTLS_ECP_DP_BP384R1_ENABLED · CONFIG_MBEDTLS_ECP_DP_BP512R1_ENABLED · CONFIG_MBEDTLS_CMAC_C · CONFIG_MBEDTLS_ECP_DP_CURVE25519_ENABLED · CONFIG_MBEDTLS_ECDSA_DETERMINISTIC · CONFIG_MBEDTLS_HARDWARE_AES · CONFIG_MBEDTLS_ATCA_HW_ECDSA_SIGN · CONFIG_MBEDTLS_ATCA_HW_ECDSA_VERIFY · CONFIG_MBEDTLS_HARDWARE_MPI · CONFIG_MBEDTLS_HARDWARE_SHA · CONFIG_MBEDTLS_DEBUG · CONFIG_MBEDTLS_ECP_RESTARTABLE · CONFIG_MBEDTLS_HAVE_TIME · CONFIG_MBEDTLS_RIPEMD160_C · CONFIG_MBEDTLS_ECP_DP_SECP192K1_ENABLED · CONFIG_MBEDTLS_ECP_DP_SECP192R1_ENABLED · CONFIG_MBEDTLS_ECP_DP_SECP224K1_ENABLED · CONFIG_MBEDTLS_ECP_DP_SECP224R1_ENABLED · CONFIG_MBEDTLS_ECP_DP_SECP256K1_ENABLED · CONFIG_MBEDTLS_ECP_DP_SECP256R1_ENABLED · CONFIG_MBEDTLS_ECP_DP_SECP384R1_ENABLED · CONFIG_MBEDTLS_ECP_DP_SECP521R1_ENABLED · CONFIG_MBEDTLS_SHA512_C · CONFIG_MBEDTLS_THREADING_C · CONFIG_MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE · CONFIG_MBEDTLS_X509_CHECK_KEY_USAGE · CONFIG_MBEDTLS_LARGE_KEY_SOFTWARE_MPI · CONFIG_MBEDTLS_HKDF_C · CONFIG_MBEDTLS_SSL_PROTO_SSL3 · mbedTLS v2.28.x related · CONFIG_MBEDTLS_MEM_ALLOC_MODE · CONFIG_MBEDTLS_ECP_NIST_OPTIM · CONFIG_MBEDTLS_POLY1305_C · CONFIG_MBEDTLS_SECURITY_RISKS · CONFIG_MBEDTLS_SSL_ALPN · CONFIG_MBEDTLS_SSL_PROTO_DTLS · CONFIG_MBEDTLS_SSL_PROTO_GMTSSL1_1 · CONFIG_MBEDTLS_SSL_PROTO_TLS1 · CONFIG_MBEDTLS_SSL_PROTO_TLS1_1 · CONFIG_MBEDTLS_SSL_PROTO_TLS1_2 · CONFIG_MBEDTLS_SSL_RENEGOTIATION · Symmetric Ciphers · TLS Key Exchange Methods · CONFIG_MBEDTLS_SSL_MAX_CONTENT_LEN · CONFIG_MBEDTLS_TLS_MODE · CONFIG_MBEDTLS_CLIENT_SSL_SESSION_TICKETS · CONFIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS · CONFIG_MBEDTLS_ROM_MD5

Espressif Systems

1541

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· CONFIG_MBEDTLS_DYNAMIC_BUFFER
CONFIG_MBEDTLS_MEM_ALLOC_MODE
Memory allocation strategy
Found in: Component config > mbedTLS
Allocation strategy for mbedTLS, essentially provides ability to allocate all required dynamic allocations from,
· Internal DRAM memory only · External SPIRAM memory only · Either internal or external memory based on default malloc() behavior in ESP-IDF · Custom allocation mode, by overwriting calloc()/free() using mbedtls_platform_set_calloc_free()
function · Internal IRAM memory wherever applicable else internal DRAM
Recommended mode here is always internal (*), since that is most preferred from security perspective. But if application requirement does not allow sufficient free internal memory then alternate mode can be selected.
(*) In case of ESP32-S2/ESP32-S3, hardware allows encryption of external SPIRAM contents provided hardware flash encryption feature is enabled. In that case, using external SPIRAM allocation strategy is also safe choice from security perspective.
Available options: · Internal memory (MBEDTLS_INTERNAL_MEM_ALLOC) · External SPIRAM (MBEDTLS_EXTERNAL_MEM_ALLOC) · Default alloc mode (MBEDTLS_DEFAULT_MEM_ALLOC) · Custom alloc mode (MBEDTLS_CUSTOM_MEM_ALLOC) · Internal IRAM (MBEDTLS_IRAM_8BIT_MEM_ALLOC) Allows to use IRAM memory region as 8bit accessible region. TLS input and output buffers will be allocated in IRAM section which is 32bit aligned memory. Every unaligned (8bit or 16bit) access will result in an exception and incur penalty of certain clock cycles per unaligned read/write.

CONFIG_MBEDTLS_SSL_MAX_CONTENT_LEN TLS maximum message content length Found in: Component config > mbedTLS Maximum TLS message length (in bytes) supported by mbedTLS. 16384 is the default and this value is required to comply fully with TLS standards. However you can set a lower value in order to save RAM. This is safe if the other end of the connection supports Maximum Fragment Length Negotiation Extension (max_fragment_length, see RFC6066) or you know for certain that it will never send a message longer than a certain number of bytes. If the value is set too low, symptoms are a failed TLS handshake or a return value of MBEDTLS_ERR_SSL_INVALID_RECORD (-0x7200). Range: · from 512 to 16384 Default value: · 16384
CONFIG_MBEDTLS_ASYMMETRIC_CONTENT_LEN Asymmetric in/out fragment length Found in: Component config > mbedTLS

Espressif Systems

1542

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
If enabled, this option allows customizing TLS in/out fragment length in asymmetric way. Please note that enabling this with default values saves 12KB of dynamic memory per TLS connection. Default value:
· Yes (enabled)
CONFIG_MBEDTLS_SSL_IN_CONTENT_LEN TLS maximum incoming fragment length Found in: Component config > mbedTLS > CONFIG_MBEDTLS_ASYMMETRIC_CONTENT_LEN This defines maximum incoming fragment length, overriding default maximum content length (MBEDTLS_SSL_MAX_CONTENT_LEN). Range: · from 512 to 16384 Default value: · 16384
CONFIG_MBEDTLS_SSL_OUT_CONTENT_LEN TLS maximum outgoing fragment length Found in: Component config > mbedTLS > CONFIG_MBEDTLS_ASYMMETRIC_CONTENT_LEN This defines maximum outgoing fragment length, overriding default maximum content length (MBEDTLS_SSL_MAX_CONTENT_LEN). Range: · from 512 to 16384 Default value: · 4096
CONFIG_MBEDTLS_DYNAMIC_BUFFER Using dynamic TX/RX buffer Found in: Component config > mbedTLS Using dynamic TX/RX buffer. After enabling this option, mbedTLS will allocate TX buffer when need to send data and then free it if all data is sent, allocate RX buffer when need to receive data and then free it when all data is used or read by upper layer. By default, when SSL is initialized, mbedTLS also allocate TX and RX buffer with the default value of oMBEDTLS_SSL_OUT_CONTENT_LENpor oMBEDTLS_SSL_IN_CONTENT_LENp, so to save more heap, users can set the options to be an appropriate value. Default value: · No (disabled) if CONFIG_MBEDTLS_SSL_PROTO_DTLS && CONFIG_MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH
CONFIG_MBEDTLS_DYNAMIC_FREE_PEER_CERT Free SSL peer certificate after its usage Found in: Component config > mbedTLS > CONFIG_MBEDTLS_DYNAMIC_BUFFER Free peer certificate after its usage in handshake process. Default value: · No (disabled) if CONFIG_MBEDTLS_DYNAMIC_BUFFER

Espressif Systems

1543

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_MBEDTLS_DYNAMIC_FREE_CONFIG_DATA Free private key and DHM data after its usage Found in: Component config > mbedTLS > CONFIG_MBEDTLS_DYNAMIC_BUFFER Free private key and DHM data after its usage in handshake process. The option will decrease heap cost when handshake, but also lead to problem: Becasue all certificate, private key and DHM data are freed so users should register certificate and private key to ssl config object again. Default value: · No (disabled) if CONFIG_MBEDTLS_DYNAMIC_BUFFER
CONFIG_MBEDTLS_DYNAMIC_FREE_CA_CERT Free SSL CA certificate after its usage Found in: Component config > mbedTLS > CONFIG_MBEDTLS_DYNAMIC_BUFFER > CONFIG_MBEDTLS_DYNAMIC_FREE_CONFIG_DATA Free CA certificate after its usage in the handshake process. This option will decrease the heap footprint for the TLS handshake, but may lead to a problem: If the respective ssl object needs to perform the TLS handshake again, the CA certificate should once again be registered to the ssl object. Default value: · Yes (enabled) if CONFIG_MBEDTLS_DYNAMIC_FREE_CONFIG_DATA
CONFIG_MBEDTLS_DEBUG Enable mbedTLS debugging Found in: Component config > mbedTLS Enable mbedTLS debugging functions at compile time. If this option is enabled, you can include ombedtls/esp_debug.hpand call mbedtls_esp_enable_debug_log() at runtime in order to enable mbedTLS debug output via the ESP log mechanism. Default value: · No (disabled)
CONFIG_MBEDTLS_DEBUG_LEVEL Set mbedTLS debugging level Found in: Component config > mbedTLS > CONFIG_MBEDTLS_DEBUG Set mbedTLS debugging level Available options: · Warning (MBEDTLS_DEBUG_LEVEL_WARN) · Info (MBEDTLS_DEBUG_LEVEL_INFO) · Debug (MBEDTLS_DEBUG_LEVEL_DEBUG) · Verbose (MBEDTLS_DEBUG_LEVEL_VERBOSE)
mbedTLS v2.28.x related Contains: · DTLS-based configurations · CONFIG_MBEDTLS_SSL_CONTEXT_SERIALIZATION · CONFIG_MBEDTLS_X509_TRUSTED_CERT_CALLBACK · CONFIG_MBEDTLS_SSL_KEEP_PEER_CERTIFICATE

Espressif Systems

1544

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· CONFIG_MBEDTLS_ECDH_LEGACY_CONTEXT · CONFIG_MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH

CONFIG_MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH
Variable SSL buffer length
Found in: Component config > mbedTLS > mbedTLS v2.28.x related
This enables the SSL buffer to be resized automatically based on the negotiated maximum fragment length in each direction.
Default value: · No (disabled)

CONFIG_MBEDTLS_ECDH_LEGACY_CONTEXT

Use a backward compatible ECDH context (Experimental)

Found in: Component config > mbedTLS > mbedTLS v2.28.x related

Use the legacy ECDH context format.

Define this option only if you enable

MBEDTLS_ECP_RESTARTABLE or if you want to access ECDH context fields directly.

Default value:

· Yes

(enabled)

if

CONFIG_MBEDTLS_ECDH_C

&&

CON-

FIG_MBEDTLS_ECP_RESTARTABLE

CONFIG_MBEDTLS_X509_TRUSTED_CERT_CALLBACK Enable trusted certificate callbacks Found in: Component config > mbedTLS > mbedTLS v2.28.x related Enables users to configure the set of trusted certificates through a callback instead of a linked list. See mbedTLS documentation for required API and more details. Default value: · No (disabled)

CONFIG_MBEDTLS_SSL_CONTEXT_SERIALIZATION
Enable serialization of the TLS context structures
Found in: Component config > mbedTLS > mbedTLS v2.28.x related
Enable serialization of the TLS context structures This is a local optimization in handling a single, potentially long-lived connection.
See mbedTLS documentation for required API and more details. Disabling this option will save some code size.
Default value: · No (disabled)

CONFIG_MBEDTLS_SSL_KEEP_PEER_CERTIFICATE Keep peer certificate after handshake completion Found in: Component config > mbedTLS > mbedTLS v2.28.x related Keep the peerns certificate after completion of the handshake. Disabling this option will save about 4kB of heap and some code size. See mbedTLS documentation for required API and more details.

Espressif Systems

1545

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Default value: · Yes (enabled) if CONFIG_MBEDTLS_DYNAMIC_FREE_PEER_CERT

DTLS-based configurations Contains:
· CONFIG_MBEDTLS_SSL_DTLS_SRTP · CONFIG_MBEDTLS_SSL_DTLS_CONNECTION_ID

CONFIG_MBEDTLS_SSL_DTLS_CONNECTION_ID
Support for the DTLS Connection ID extension
Found in: Component config > mbedTLS > mbedTLS v2.28.x related > DTLS-based configurations
Enable support for the DTLS Connection ID extension which allows to identify DTLS connections across changes in the underlying transport. The Connection ID extension is still in draft state. Refer: version draft-ietf-tls-dtls-connection-id-05
Default value: · No (disabled) if CONFIG_MBEDTLS_SSL_PROTO_DTLS

CONFIG_MBEDTLS_SSL_CID_IN_LEN_MAX
Maximum length of CIDs used for incoming DTLS messages
Found in: Component config > mbedTLS > mbedTLS v2.28.x related > DTLS-based configurations > CONFIG_MBEDTLS_SSL_DTLS_CONNECTION_ID
Maximum length of CIDs used for incoming DTLS messages
Range: · from 0 to 32 if CONFIG_MBEDTLS_SSL_DTLS_CONNECTION_ID
Default value: · 32 if CONFIG_MBEDTLS_SSL_DTLS_CONNECTION_ID

CONFIG_MBEDTLS_SSL_CID_OUT_LEN_MAX
Maximum length of CIDs used for outgoing DTLS messages
Found in: Component config > mbedTLS > mbedTLS v2.28.x related > DTLS-based configurations > CONFIG_MBEDTLS_SSL_DTLS_CONNECTION_ID
Maximum length of CIDs used for outgoing DTLS messages
Range: · from 0 to 32 if CONFIG_MBEDTLS_SSL_DTLS_CONNECTION_ID
Default value: · 32 if CONFIG_MBEDTLS_SSL_DTLS_CONNECTION_ID

CONFIG_MBEDTLS_SSL_CID_PADDING_GRANULARITY
Record plaintext padding (for DTLS 1.2)
Found in: Component config > mbedTLS > mbedTLS v2.28.x related > DTLS-based configurations > CONFIG_MBEDTLS_SSL_DTLS_CONNECTION_ID
Controls the use of record plaintext padding when using the Connection ID extension in DTLS 1.2.
The padding will always be chosen so that the length of the padded plaintext is a multiple of the value of this option.
Notes: A value of 1 means that no padding will be used for outgoing records. On systems lacking division instructions, a power of two should be preferred.
Range:

Espressif Systems

1546

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· from 0 to 32 if CONFIG_MBEDTLS_SSL_DTLS_CONNECTION_ID Default value:
· 16 if CONFIG_MBEDTLS_SSL_DTLS_CONNECTION_ID

CONFIG_MBEDTLS_SSL_DTLS_SRTP
Enable support for negotiation of DTLS-SRTP (RFC 5764)
Found in: Component config > mbedTLS > mbedTLS v2.28.x related > DTLS-based configurations
Enable support for negotiation of DTLS-SRTP (RFC 5764) through the use_srtp extension.
See mbedTLS documentation for required API and more details. Disabling this option will save some code size.
Default value: · No (disabled) if CONFIG_MBEDTLS_SSL_PROTO_DTLS

Certificate Bundle Contains: · CONFIG_MBEDTLS_CERTIFICATE_BUNDLE

CONFIG_MBEDTLS_CERTIFICATE_BUNDLE
Enable trusted root certificate bundle
Found in: Component config > mbedTLS > Certificate Bundle
Enable support for large number of default root certificates
When enabled this option allows user to store default as well as customer specific root certificates in compressed format rather than storing full certificate. For the root certificates the public key and the subject name will be stored.
Default value: · Yes (enabled)

CONFIG_MBEDTLS_DEFAULT_CERTIFICATE_BUNDLE

Default certificate bundle options

Found in:

Component config > mbedTLS > Certificate Bundle > CON-

FIG_MBEDTLS_CERTIFICATE_BUNDLE

Available options: · Use the full default certificate bundle (MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_FULL) · Use only the most common certificates from the default bundles (MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_CMN) Use only the most common certificates from the default bundles, reducing the size with 50%, while still having around 99% coverage. · Do not use the default certificate bundle (MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_NONE)

CONFIG_MBEDTLS_CUSTOM_CERTIFICATE_BUNDLE

Add custom certificates to the default bundle

Found in:

Component config > mbedTLS > Certificate Bundle > CON-

FIG_MBEDTLS_CERTIFICATE_BUNDLE

Default value: · No (disabled)

Espressif Systems

1547

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_MBEDTLS_CUSTOM_CERTIFICATE_BUNDLE_PATH

Custom certificate bundle path

Found in:

Component config > mbedTLS > Certificate Bundle > CON-

FIG_MBEDTLS_CERTIFICATE_BUNDLE > CONFIG_MBEDTLS_CUSTOM_CERTIFICATE_BUNDLE

Name of the custom certificate directory or file. This path is evaluated relative to the project root directory.

CONFIG_MBEDTLS_ECP_RESTARTABLE Enable mbedTLS ecp restartable Found in: Component config > mbedTLS Enable onon-blockingpECC operations that can return early and be resumed. Default value: · No (disabled)

CONFIG_MBEDTLS_CMAC_C Enable CMAC mode for block ciphers Found in: Component config > mbedTLS Enable the CMAC (Cipher-based Message Authentication Code) mode for block ciphers. Default value: · No (disabled)

CONFIG_MBEDTLS_HARDWARE_AES
Enable hardware AES acceleration
Found in: Component config > mbedTLS
Enable hardware accelerated AES encryption & decryption.
Note that if the ESP32 CPU is running at 240MHz, hardware AES does not offer any speed boost over software AES.
Default value: · Yes (enabled) if SPIRAM_CACHE_WORKAROUND_STRATEGY_DUPLDST

CONFIG_MBEDTLS_AES_USE_INTERRUPT
Use interrupt for long AES operations
Found in: Component config > mbedTLS > CONFIG_MBEDTLS_HARDWARE_AES
Use an interrupt to coordinate long AES operations.
This allows other code to run on the CPU while an AES operation is pending. Otherwise the CPU busy-waits.
Default value: · Yes (enabled)

Espressif Systems

1548

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_MBEDTLS_HARDWARE_MPI Enable hardware MPI (bignum) acceleration Found in: Component config > mbedTLS Enable hardware accelerated multiple precision integer operations. Hardware accelerated multiplication, modulo multiplication, and modular exponentiation for up to SOC_RSA_MAX_BIT_LEN bit results. These operations are used by RSA. Default value: · Yes (enabled) if SPIRAM_CACHE_WORKAROUND_STRATEGY_DUPLDST
CONFIG_MBEDTLS_MPI_USE_INTERRUPT Use interrupt for MPI exp-mod operations Found in: Component config > mbedTLS > CONFIG_MBEDTLS_HARDWARE_MPI Use an interrupt to coordinate long MPI operations. This allows other code to run on the CPU while an MPI operation is pending. Otherwise the CPU busy-waits. Default value: · Yes (enabled)
CONFIG_MBEDTLS_HARDWARE_SHA Enable hardware SHA acceleration Found in: Component config > mbedTLS Enable hardware accelerated SHA1, SHA256, SHA384 & SHA512 in mbedTLS. Due to a hardware limitation, on the ESP32 hardware acceleration is only guaranteed if SHA digests are calculated one at a time. If more than one SHA digest is calculated at the same time, one will be calculated fully in hardware and the rest will be calculated (at least partially calculated) in software. This happens automatically. SHA hardware acceleration is faster than software in some situations but slower in others. You should benchmark to find the best setting for you. Default value: · Yes (enabled) if SPIRAM_CACHE_WORKAROUND_STRATEGY_DUPLDST
CONFIG_MBEDTLS_ROM_MD5 Use MD5 implementation in ROM Found in: Component config > mbedTLS Use ROM MD5 in mbedTLS. Default value: · Yes (enabled)
CONFIG_MBEDTLS_ATCA_HW_ECDSA_SIGN Enable hardware ECDSA sign acceleration when using ATECC608A Found in: Component config > mbedTLS

Espressif Systems

1549

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
This option enables hardware acceleration for ECDSA sign function, only when using ATECC608A cryptoauth chip (integrated with ESP32-WROOM-32SE) Default value:
· No (disabled)
CONFIG_MBEDTLS_ATCA_HW_ECDSA_VERIFY Enable hardware ECDSA verify acceleration when using ATECC608A Found in: Component config > mbedTLS This option enables hardware acceleration for ECDSA sign function, only when using ATECC608A cryptoauth chip (integrated with ESP32-WROOM-32SE) Default value: · No (disabled)
CONFIG_MBEDTLS_HAVE_TIME Enable mbedtls time support Found in: Component config > mbedTLS Enable use of time.h functions (time() and gmtime()) by mbedTLS. This option doesnnt require the system time to be correct, but enables functionality that requires relative timekeeping - for example periodic expiry of TLS session tickets or session cache entries. Disabling this option will save some firmware size, particularly if the rest of the firmware doesnnt call any standard timekeeeping functions. Default value: · Yes (enabled)
CONFIG_MBEDTLS_HAVE_TIME_DATE Enable mbedtls certificate expiry check Found in: Component config > mbedTLS > CONFIG_MBEDTLS_HAVE_TIME Enables X.509 certificate expiry checks in mbedTLS. If this option is disabled (default) then X.509 certificate ovalid frompand ovalid toptimestamp fields are ignored. If this option is enabled, these fields are compared with the current system date and time. The time is retrieved using the standard time() and gmtime() functions. If the certificate is not valid for the current system time then verification will fail with code MBEDTLS_X509_BADCERT_FUTURE or MBEDTLS_X509_BADCERT_EXPIRED. Enabling this option requires adding functionality in the firmware to set the system clock to a valid timestamp before using TLS. The recommended way to do this is via ESP-IDFns SNTP functionality, but any method can be used. In the case where only a small number of certificates are trusted by the device, please carefully consider the tradeoffs of enabling this option. There may be undesired consequences, for example if all trusted certificates expire while the device is offline and a TLS connection is required to update. Or if an issue with the SNTP server means that the system time is invalid for an extended period after a reset. Default value: · No (disabled)

Espressif Systems

1550

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_MBEDTLS_ECDSA_DETERMINISTIC Enable deterministic ECDSA Found in: Component config > mbedTLS Standard ECDSA isofragilepin the sense that lack of entropy when signing may result in a compromise of the long-term signing key. Default value: · Yes (enabled)
CONFIG_MBEDTLS_SHA512_C Enable the SHA-384 and SHA-512 cryptographic hash algorithms Found in: Component config > mbedTLS Enable MBEDTLS_SHA512_C adds support for SHA-384 and SHA-512. Default value: · Yes (enabled)
CONFIG_MBEDTLS_TLS_MODE TLS Protocol Role Found in: Component config > mbedTLS mbedTLS can be compiled with protocol support for the TLS server, TLS client, or both server and client. Reducing the number of TLS roles supported saves code size. Available options: · Server & Client (MBEDTLS_TLS_SERVER_AND_CLIENT) · Server (MBEDTLS_TLS_SERVER_ONLY) · Client (MBEDTLS_TLS_CLIENT_ONLY) · None (MBEDTLS_TLS_DISABLED)
TLS Key Exchange Methods Contains: · CONFIG_MBEDTLS_KEY_EXCHANGE_DHE_RSA · CONFIG_MBEDTLS_KEY_EXCHANGE_ECJPAKE · CONFIG_MBEDTLS_PSK_MODES · CONFIG_MBEDTLS_KEY_EXCHANGE_RSA · CONFIG_MBEDTLS_KEY_EXCHANGE_ELLIPTIC_CURVE
CONFIG_MBEDTLS_PSK_MODES Enable pre-shared-key ciphersuites Found in: Component config > mbedTLS > TLS Key Exchange Methods Enable to show configuration for different types of pre-shared-key TLS authentatication methods. Leaving this options disabled will save code size if they are not used. Default value: · No (disabled)

Espressif Systems

1551

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_MBEDTLS_KEY_EXCHANGE_PSK Enable PSK based ciphersuite modes Found in: Component config > mbedTLS > TLS Key Exchange Methods > CONFIG_MBEDTLS_PSK_MODES Enable to support symmetric key PSK (pre-shared-key) TLS key exchange modes. Default value: · No (disabled) if CONFIG_MBEDTLS_PSK_MODES
CONFIG_MBEDTLS_KEY_EXCHANGE_DHE_PSK Enable DHE-PSK based ciphersuite modes Found in: Component config > mbedTLS > TLS Key Exchange Methods > CONFIG_MBEDTLS_PSK_MODES Enable to support Diffie-Hellman PSK (pre-shared-key) TLS authentication modes. Default value: · Yes (enabled) if CONFIG_MBEDTLS_PSK_MODES && CONFIG_MBEDTLS_DHM_C
CONFIG_MBEDTLS_KEY_EXCHANGE_ECDHE_PSK Enable ECDHE-PSK based ciphersuite modes Found in: Component config > mbedTLS > TLS Key Exchange Methods > CONFIG_MBEDTLS_PSK_MODES Enable to support Elliptic-Curve-Diffie-Hellman PSK (pre-shared-key) TLS authentication modes. Default value: · Yes (enabled) if CONFIG_MBEDTLS_PSK_MODES && CONFIG_MBEDTLS_ECDH_C
CONFIG_MBEDTLS_KEY_EXCHANGE_RSA_PSK Enable RSA-PSK based ciphersuite modes Found in: Component config > mbedTLS > TLS Key Exchange Methods > CONFIG_MBEDTLS_PSK_MODES Enable to support RSA PSK (pre-shared-key) TLS authentication modes. Default value: · Yes (enabled) if CONFIG_MBEDTLS_PSK_MODES
CONFIG_MBEDTLS_KEY_EXCHANGE_RSA Enable RSA-only based ciphersuite modes Found in: Component config > mbedTLS > TLS Key Exchange Methods Enable to support ciphersuites with prefix TLS-RSA-WITHDefault value: · Yes (enabled)
CONFIG_MBEDTLS_KEY_EXCHANGE_DHE_RSA Enable DHE-RSA based ciphersuite modes Found in: Component config > mbedTLS > TLS Key Exchange Methods Enable to support ciphersuites with prefix TLS-DHE-RSA-WITH-

Espressif Systems

1552

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Default value: · Yes (enabled) if CONFIG_MBEDTLS_DHM_C
CONFIG_MBEDTLS_KEY_EXCHANGE_ELLIPTIC_CURVE Support Elliptic Curve based ciphersuites Found in: Component config > mbedTLS > TLS Key Exchange Methods Enable to show Elliptic Curve based ciphersuite mode options. Disabling all Elliptic Curve ciphersuites saves code size and can give slightly faster TLS handshakes, provided the server supports RSA-only ciphersuite modes. Default value: · Yes (enabled)
CONFIG_MBEDTLS_KEY_EXCHANGE_ECDHE_RSA Enable ECDHE-RSA based ciphersuite modes Found in: Component config > mbedTLS > TLS Key Exchange Methods > CONFIG_MBEDTLS_KEY_EXCHANGE_ELLIPTIC_CURVE Enable to support ciphersuites with prefix TLS-ECDHE-RSA-WITHDefault value: · Yes (enabled)
CONFIG_MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA Enable ECDHE-ECDSA based ciphersuite modes Found in: Component config > mbedTLS > TLS Key Exchange Methods > CONFIG_MBEDTLS_KEY_EXCHANGE_ELLIPTIC_CURVE Enable to support ciphersuites with prefix TLS-ECDHE-RSA-WITHDefault value: · Yes (enabled)
CONFIG_MBEDTLS_KEY_EXCHANGE_ECDH_ECDSA Enable ECDH-ECDSA based ciphersuite modes Found in: Component config > mbedTLS > TLS Key Exchange Methods > CONFIG_MBEDTLS_KEY_EXCHANGE_ELLIPTIC_CURVE Enable to support ciphersuites with prefix TLS-ECDHE-RSA-WITHDefault value: · Yes (enabled)
CONFIG_MBEDTLS_KEY_EXCHANGE_ECDH_RSA Enable ECDH-RSA based ciphersuite modes Found in: Component config > mbedTLS > TLS Key Exchange Methods > CONFIG_MBEDTLS_KEY_EXCHANGE_ELLIPTIC_CURVE Enable to support ciphersuites with prefix TLS-ECDHE-RSA-WITHDefault value: · Yes (enabled)

Espressif Systems

1553

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_MBEDTLS_KEY_EXCHANGE_ECJPAKE

Enable ECJPAKE based ciphersuite modes

Found in: Component config > mbedTLS > TLS Key Exchange Methods

Enable to support ciphersuites with prefix TLS-ECJPAKE-WITH-

Default value:

· No

(disabled)

if

CONFIG_MBEDTLS_ECJPAKE_C

&&

CON-

FIG_MBEDTLS_ECP_DP_SECP256R1_ENABLED

CONFIG_MBEDTLS_SSL_RENEGOTIATION
Support TLS renegotiation
Found in: Component config > mbedTLS
The two main uses of renegotiation are (1) refresh keys on long-lived connections and (2) client authentication after the initial handshake. If you donnt need renegotiation, disabling it will save code size and reduce the possibility of abuse/vulnerability.
Default value: · Yes (enabled)

CONFIG_MBEDTLS_SSL_PROTO_SSL3 Legacy SSL 3.0 support Found in: Component config > mbedTLS Support the legacy SSL 3.0 protocol. Most servers will speak a newer TLS protocol these days. Default value: · No (disabled)

CONFIG_MBEDTLS_SSL_PROTO_TLS1 Support TLS 1.0 protocol Found in: Component config > mbedTLS Default value: · Yes (enabled)

CONFIG_MBEDTLS_SSL_PROTO_TLS1_1 Support TLS 1.1 protocol Found in: Component config > mbedTLS Default value: · Yes (enabled)

CONFIG_MBEDTLS_SSL_PROTO_TLS1_2 Support TLS 1.2 protocol Found in: Component config > mbedTLS Default value: · Yes (enabled)

Espressif Systems

1554

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_MBEDTLS_SSL_PROTO_GMTSSL1_1 Support GM/T SSL 1.1 protocol Found in: Component config > mbedTLS Provisions for GM/T SSL 1.1 support Default value: · No (disabled)

CONFIG_MBEDTLS_SSL_PROTO_DTLS Support DTLS protocol (all versions) Found in: Component config > mbedTLS Requires TLS 1.1 to be enabled for DTLS 1.0 Requires TLS 1.2 to be enabled for DTLS 1.2 Default value: · No (disabled)

CONFIG_MBEDTLS_SSL_ALPN Support ALPN (Application Layer Protocol Negotiation) Found in: Component config > mbedTLS Disabling this option will save some code size if it is not needed. Default value: · Yes (enabled)

CONFIG_MBEDTLS_CLIENT_SSL_SESSION_TICKETS
TLS: Client Support for RFC 5077 SSL session tickets
Found in: Component config > mbedTLS
Client support for RFC 5077 session tickets. See mbedTLS documentation for more details. Disabling this option will save some code size.
Default value: · Yes (enabled)

CONFIG_MBEDTLS_X509_CHECK_KEY_USAGE
Enable verification of the keyUsage extension
Found in: Component config > mbedTLS
Disabling this avoids problems with mis-issued and/or misused (intermediate) CA and leaf certificates. Depending on your PKI use, disabling this can be a security risk.
Default value: · Yes (enabled)

CONFIG_MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE Enable verification of the extendedKeyUsage extension Found in: Component config > mbedTLS Disabling this avoids problems with mis-issued and/or misused certificates. Depending on your PKI use, disabling this can be a security risk. Default value:

Espressif Systems

1555

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· Yes (enabled)
CONFIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS TLS: Server Support for RFC 5077 SSL session tickets Found in: Component config > mbedTLS Server support for RFC 5077 session tickets. See mbedTLS documentation for more details. Disabling this option will save some code size. Default value: · Yes (enabled)
Symmetric Ciphers Contains: · CONFIG_MBEDTLS_AES_C · CONFIG_MBEDTLS_BLOWFISH_C · CONFIG_MBEDTLS_CAMELLIA_C · CONFIG_MBEDTLS_CCM_C · CONFIG_MBEDTLS_DES_C · CONFIG_MBEDTLS_GCM_C · CONFIG_MBEDTLS_NIST_KW_C · CONFIG_MBEDTLS_RC4_MODE · CONFIG_MBEDTLS_XTEA_C
CONFIG_MBEDTLS_AES_C AES block cipher Found in: Component config > mbedTLS > Symmetric Ciphers Default value: · Yes (enabled)
CONFIG_MBEDTLS_CAMELLIA_C Camellia block cipher Found in: Component config > mbedTLS > Symmetric Ciphers Default value: · No (disabled)
CONFIG_MBEDTLS_DES_C DES block cipher (legacy, insecure) Found in: Component config > mbedTLS > Symmetric Ciphers Enables the DES block cipher to support 3DES-based TLS ciphersuites. 3DES is vulnerable to the Sweet32 attack and should only be enabled if absolutely necessary. Default value: · No (disabled)

Espressif Systems

1556

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_MBEDTLS_RC4_MODE RC4 Stream Cipher (legacy, insecure) Found in: Component config > mbedTLS > Symmetric Ciphers ARCFOUR (RC4) stream cipher can be disabled entirely, enabled but not added to default ciphersuites, or enabled completely. Please consider the security implications before enabling RC4. Available options: · Disabled (MBEDTLS_RC4_DISABLED) · Enabled, not in default ciphersuites (MBEDTLS_RC4_ENABLED_NO_DEFAULT) · Enabled (MBEDTLS_RC4_ENABLED)
CONFIG_MBEDTLS_BLOWFISH_C Blowfish block cipher (read help) Found in: Component config > mbedTLS > Symmetric Ciphers Enables the Blowfish block cipher (not used for TLS sessions.) The Blowfish cipher is not used for mbedTLS TLS sessions but can be used for other purposes. Read up on the limitations of Blowfish (including Sweet32) before enabling. Default value: · No (disabled)
CONFIG_MBEDTLS_XTEA_C XTEA block cipher Found in: Component config > mbedTLS > Symmetric Ciphers Enables the XTEA block cipher. Default value: · No (disabled)
CONFIG_MBEDTLS_CCM_C CCM (Counter with CBC-MAC) block cipher modes Found in: Component config > mbedTLS > Symmetric Ciphers Enable Counter with CBC-MAC (CCM) modes for AES and/or Camellia ciphers. Disabling this option saves some code size. Default value: · Yes (enabled)
CONFIG_MBEDTLS_GCM_C GCM (Galois/Counter) block cipher modes Found in: Component config > mbedTLS > Symmetric Ciphers Enable Galois/Counter Mode for AES and/or Camellia ciphers. This option is generally faster than CCM. Default value: · Yes (enabled)

Espressif Systems

1557

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_MBEDTLS_NIST_KW_C NIST key wrapping (KW) and KW padding (KWP) Found in: Component config > mbedTLS > Symmetric Ciphers Enable NIST key wrapping and key wrapping padding. Default value: · No (disabled)
CONFIG_MBEDTLS_RIPEMD160_C Enable RIPEMD-160 hash algorithm Found in: Component config > mbedTLS Enable the RIPEMD-160 hash algorithm. Default value: · No (disabled)
Certificates Contains: · CONFIG_MBEDTLS_PEM_PARSE_C · CONFIG_MBEDTLS_PEM_WRITE_C · CONFIG_MBEDTLS_X509_CRL_PARSE_C · CONFIG_MBEDTLS_X509_CSR_PARSE_C
CONFIG_MBEDTLS_PEM_PARSE_C Read & Parse PEM formatted certificates Found in: Component config > mbedTLS > Certificates Enable decoding/parsing of PEM formatted certificates. If your certificates are all in the simpler DER format, disabling this option will save some code size. Default value: · Yes (enabled)
CONFIG_MBEDTLS_PEM_WRITE_C Write PEM formatted certificates Found in: Component config > mbedTLS > Certificates Enable writing of PEM formatted certificates. If writing certificate data only in DER format, disabling this option will save some code size. Default value: · Yes (enabled)
CONFIG_MBEDTLS_X509_CRL_PARSE_C X.509 CRL parsing Found in: Component config > mbedTLS > Certificates Support for parsing X.509 Certifificate Revocation Lists. Default value: · Yes (enabled)

Espressif Systems

1558

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_MBEDTLS_X509_CSR_PARSE_C X.509 CSR parsing Found in: Component config > mbedTLS > Certificates Support for parsing X.509 Certifificate Signing Requests Default value: · Yes (enabled)
CONFIG_MBEDTLS_ECP_C Elliptic Curve Ciphers Found in: Component config > mbedTLS Default value: · Yes (enabled)
CONFIG_MBEDTLS_DHM_C Diffie-Hellman-Merkle key exchange (DHM) Found in: Component config > mbedTLS Enable DHM. Needed to use DHE-xxx TLS ciphersuites. Note that the security of Diffie-Hellman key exchanges depends on a suitable prime being used for the exchange. Please see detailed warning text about this in file mbedtls/dhm.h file. Default value: · No (disabled)
CONFIG_MBEDTLS_ECDH_C Elliptic Curve Diffie-Hellman (ECDH) Found in: Component config > mbedTLS Enable ECDH. Needed to use ECDHE-xxx TLS ciphersuites. Default value: · Yes (enabled)
CONFIG_MBEDTLS_ECDSA_C Elliptic Curve DSA Found in: Component config > mbedTLS > CONFIG_MBEDTLS_ECDH_C Enable ECDSA. Needed to use ECDSA-xxx TLS ciphersuites. Default value: · Yes (enabled)
CONFIG_MBEDTLS_ECJPAKE_C Elliptic curve J-PAKE Found in: Component config > mbedTLS Enable ECJPAKE. Needed to use ECJPAKE-xxx TLS ciphersuites. Default value: · No (disabled)

Espressif Systems

1559

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_MBEDTLS_ECP_DP_SECP192R1_ENABLED
Enable SECP192R1 curve
Found in: Component config > mbedTLS
Enable support for SECP192R1 Elliptic Curve.
Default value: · Yes (enabled) if (CONFIG_MBEDTLS_ATCA_HW_ECDSA_SIGN || FIG_MBEDTLS_ATCA_HW_ECDSA_VERIFY) && CONFIG_MBEDTLS_ECP_C

CON-

CONFIG_MBEDTLS_ECP_DP_SECP224R1_ENABLED
Enable SECP224R1 curve
Found in: Component config > mbedTLS
Enable support for SECP224R1 Elliptic Curve.
Default value: · Yes (enabled) if (CONFIG_MBEDTLS_ATCA_HW_ECDSA_SIGN || FIG_MBEDTLS_ATCA_HW_ECDSA_VERIFY) && CONFIG_MBEDTLS_ECP_C

CON-

CONFIG_MBEDTLS_ECP_DP_SECP256R1_ENABLED Enable SECP256R1 curve Found in: Component config > mbedTLS Enable support for SECP256R1 Elliptic Curve. Default value: · Yes (enabled)

CONFIG_MBEDTLS_ECP_DP_SECP384R1_ENABLED
Enable SECP384R1 curve
Found in: Component config > mbedTLS
Enable support for SECP384R1 Elliptic Curve.
Default value: · Yes (enabled) if (CONFIG_MBEDTLS_ATCA_HW_ECDSA_SIGN || FIG_MBEDTLS_ATCA_HW_ECDSA_VERIFY) && CONFIG_MBEDTLS_ECP_C

CON-

CONFIG_MBEDTLS_ECP_DP_SECP521R1_ENABLED
Enable SECP521R1 curve
Found in: Component config > mbedTLS
Enable support for SECP521R1 Elliptic Curve.
Default value: · Yes (enabled) if (CONFIG_MBEDTLS_ATCA_HW_ECDSA_SIGN || FIG_MBEDTLS_ATCA_HW_ECDSA_VERIFY) && CONFIG_MBEDTLS_ECP_C

CON-

CONFIG_MBEDTLS_ECP_DP_SECP192K1_ENABLED Enable SECP192K1 curve Found in: Component config > mbedTLS Enable support for SECP192K1 Elliptic Curve.

Espressif Systems

1560

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Default value: · Yes (enabled) if (CONFIG_MBEDTLS_ATCA_HW_ECDSA_SIGN || FIG_MBEDTLS_ATCA_HW_ECDSA_VERIFY) && CONFIG_MBEDTLS_ECP_C

CON-

CONFIG_MBEDTLS_ECP_DP_SECP224K1_ENABLED
Enable SECP224K1 curve
Found in: Component config > mbedTLS
Enable support for SECP224K1 Elliptic Curve.
Default value: · Yes (enabled) if (CONFIG_MBEDTLS_ATCA_HW_ECDSA_SIGN || FIG_MBEDTLS_ATCA_HW_ECDSA_VERIFY) && CONFIG_MBEDTLS_ECP_C

CON-

CONFIG_MBEDTLS_ECP_DP_SECP256K1_ENABLED
Enable SECP256K1 curve
Found in: Component config > mbedTLS
Enable support for SECP256K1 Elliptic Curve.
Default value: · Yes (enabled) if (CONFIG_MBEDTLS_ATCA_HW_ECDSA_SIGN || FIG_MBEDTLS_ATCA_HW_ECDSA_VERIFY) && CONFIG_MBEDTLS_ECP_C

CON-

CONFIG_MBEDTLS_ECP_DP_BP256R1_ENABLED
Enable BP256R1 curve
Found in: Component config > mbedTLS
support for DP Elliptic Curve.
Default value: · Yes (enabled) if (CONFIG_MBEDTLS_ATCA_HW_ECDSA_SIGN || FIG_MBEDTLS_ATCA_HW_ECDSA_VERIFY) && CONFIG_MBEDTLS_ECP_C

CON-

CONFIG_MBEDTLS_ECP_DP_BP384R1_ENABLED
Enable BP384R1 curve
Found in: Component config > mbedTLS
support for DP Elliptic Curve.
Default value: · Yes (enabled) if (CONFIG_MBEDTLS_ATCA_HW_ECDSA_SIGN || FIG_MBEDTLS_ATCA_HW_ECDSA_VERIFY) && CONFIG_MBEDTLS_ECP_C

CON-

CONFIG_MBEDTLS_ECP_DP_BP512R1_ENABLED
Enable BP512R1 curve
Found in: Component config > mbedTLS
support for DP Elliptic Curve.
Default value: · Yes (enabled) if (CONFIG_MBEDTLS_ATCA_HW_ECDSA_SIGN || FIG_MBEDTLS_ATCA_HW_ECDSA_VERIFY) && CONFIG_MBEDTLS_ECP_C

CON-

Espressif Systems

1561

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_MBEDTLS_ECP_DP_CURVE25519_ENABLED
Enable CURVE25519 curve
Found in: Component config > mbedTLS
Enable support for CURVE25519 Elliptic Curve.
Default value: · Yes (enabled) if (CONFIG_MBEDTLS_ATCA_HW_ECDSA_SIGN || FIG_MBEDTLS_ATCA_HW_ECDSA_VERIFY) && CONFIG_MBEDTLS_ECP_C

CON-

CONFIG_MBEDTLS_ECP_NIST_OPTIM NIST mmodulo pnoptimisations Found in: Component config > mbedTLS NIST mmodulo pnoptimisations increase Elliptic Curve operation performance. Disabling this option saves some code size. # end of Elliptic Curve options Default value: · Yes (enabled)

CONFIG_MBEDTLS_POLY1305_C Poly1305 MAC algorithm Found in: Component config > mbedTLS Enable support for Poly1305 MAC algorithm. Default value: · No (disabled)

CONFIG_MBEDTLS_CHACHA20_C Chacha20 stream cipher Found in: Component config > mbedTLS Enable support for Chacha20 stream cipher. Default value: · No (disabled)

CONFIG_MBEDTLS_CHACHAPOLY_C
ChaCha20-Poly1305 AEAD algorithm
Found in: Component config > mbedTLS > CONFIG_MBEDTLS_CHACHA20_C
Enable support for ChaCha20-Poly1305 AEAD algorithm.
Default value: · No (disabled) if CONFIG_MBEDTLS_CHACHA20_C && CONFIG_MBEDTLS_POLY1305_C

Espressif Systems

1562

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_MBEDTLS_HKDF_C HKDF algorithm (RFC 5869) Found in: Component config > mbedTLS Enable support for the Hashed Message Authentication Code (HMAC)-based key derivation function (HKDF). Default value: · No (disabled)
CONFIG_MBEDTLS_THREADING_C Enable the threading abstraction layer Found in: Component config > mbedTLS If you do intend to use contexts between threads, you will need to enable this layer to prevent race conditions. Default value: · No (disabled)
CONFIG_MBEDTLS_THREADING_ALT Enable threading alternate implementation Found in: Component config > mbedTLS > CONFIG_MBEDTLS_THREADING_C Enable threading alt to allow your own alternate threading implementation. Default value: · Yes (enabled) if CONFIG_MBEDTLS_THREADING_C
CONFIG_MBEDTLS_THREADING_PTHREAD Enable threading pthread implementation Found in: Component config > mbedTLS > CONFIG_MBEDTLS_THREADING_C Enable the pthread wrapper layer for the threading layer. Default value: · No (disabled) if CONFIG_MBEDTLS_THREADING_C
CONFIG_MBEDTLS_LARGE_KEY_SOFTWARE_MPI Fallback to software implementation for larger MPI values Found in: Component config > mbedTLS Fallback to software implementation for RSA key lengths larger than SOC_RSA_MAX_BIT_LEN. If this is not active then the ESP will be unable to process keys greater than SOC_RSA_MAX_BIT_LEN. Default value: · No (disabled)
CONFIG_MBEDTLS_SECURITY_RISKS Show configurations with potential security risks Found in: Component config > mbedTLS Default value: · No (disabled)

Espressif Systems

1563

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Contains: · CONFIG_MBEDTLS_ALLOW_UNSUPPORTED_CRITICAL_EXT

CONFIG_MBEDTLS_ALLOW_UNSUPPORTED_CRITICAL_EXT X.509 CRT parsing with unsupported critical extensions Found in: Component config > mbedTLS > CONFIG_MBEDTLS_SECURITY_RISKS Allow the X.509 certificate parser to load certificates with unsupported critical extensions Default value: · No (disabled) if CONFIG_MBEDTLS_SECURITY_RISKS

mDNS Contains:
· CONFIG_MDNS_MAX_SERVICES · CONFIG_MDNS_SERVICE_ADD_TIMEOUT_MS · CONFIG_MDNS_STRICT_MODE · CONFIG_MDNS_TASK_AFFINITY · CONFIG_MDNS_TASK_PRIORITY · CONFIG_MDNS_TASK_STACK_SIZE · CONFIG_MDNS_TIMER_PERIOD_MS · CONFIG_MDNS_MULTIPLE_INSTANCE · CONFIG_MDNS_NETWORKING_SOCKET

CONFIG_MDNS_MAX_SERVICES
Max number of services
Found in: Component config > mDNS
Services take up a certain amount of memory, and allowing fewer services to be open at the same time conserves memory. Specify the maximum amount of services here. The valid value is from 1 to 64.
Range: · from 1 to 64
Default value: · 10

CONFIG_MDNS_TASK_PRIORITY
mDNS task priority
Found in: Component config > mDNS
Allows setting mDNS task priority. Please do not set the task priority higher than priorities of system tasks. Compile time warning/error would be emitted if the chosen task priority were too high.
Range: · from 1 to 255
Default value: ·1

CONFIG_MDNS_TASK_STACK_SIZE mDNS task stack size Found in: Component config > mDNS Allows setting mDNS task stacksize. Default value:

Espressif Systems

1564

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· 4096
CONFIG_MDNS_TASK_AFFINITY mDNS task affinity Found in: Component config > mDNS Allows setting mDNS tasks affinity, i.e. whether the task is pinned to CPU0, pinned to CPU1, or allowed to run on any CPU. Available options: · No affinity (MDNS_TASK_AFFINITY_NO_AFFINITY) · CPU0 (MDNS_TASK_AFFINITY_CPU0) · CPU1 (MDNS_TASK_AFFINITY_CPU1)
CONFIG_MDNS_SERVICE_ADD_TIMEOUT_MS mDNS adding service timeout (ms) Found in: Component config > mDNS Configures timeout for adding a new mDNS service. Adding a service fails if could not be completed within this time. Range: · from 10 to 30000 Default value: · 2000
CONFIG_MDNS_STRICT_MODE mDNS strict mode Found in: Component config > mDNS Configures strict mode. Set this to 1 for the mDNS library to strictly follow the RFC6762: Currently the only strict feature: Do not repeat original questions in response packets (defined in RFC6762 sec. 6). Default configuration is 0, i.e. non-strict mode, since some implementations, such as lwIP mdns resolver (used by standard POSIX API like getaddrinfo, gethostbyname) could not correctly resolve advertised names. Default value: · No (disabled)
CONFIG_MDNS_TIMER_PERIOD_MS mDNS timer period (ms) Found in: Component config > mDNS Configures period of mDNS timer, which periodically transmits packets and schedules mDNS searches. Range: · from 10 to 10000 Default value: · 100

Espressif Systems

1565

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_MDNS_NETWORKING_SOCKET Use BSD sockets for mdns networking Found in: Component config > mDNS Enables optional mdns networking implementation using BSD sockets in UDP multicast mode. This option creates a new thread to serve receiving packets (TODO). This option uses additional N sockets, where N is number of interfaces. Default value: · No (disabled)
CONFIG_MDNS_MULTIPLE_INSTANCE Multiple instances under the same service type Found in: Component config > mDNS Enables adding multiple service instances under the same service type. Default value: · Yes (enabled)
ESP-MQTT Configurations Contains: · CONFIG_MQTT_CUSTOM_OUTBOX · CONFIG_MQTT_TRANSPORT_SSL · CONFIG_MQTT_TRANSPORT_WEBSOCKET · CONFIG_MQTT_PROTOCOL_311 · CONFIG_MQTT_TASK_CORE_SELECTION_ENABLED · CONFIG_MQTT_USE_CUSTOM_CONFIG · CONFIG_MQTT_OUTBOX_EXPIRED_TIMEOUT_MS · CONFIG_MQTT_REPORT_DELETED_MESSAGES · CONFIG_MQTT_SKIP_PUBLISH_IF_DISCONNECTED · CONFIG_MQTT_MSG_ID_INCREMENTAL
CONFIG_MQTT_PROTOCOL_311 Enable MQTT protocol 3.1.1 Found in: Component config > ESP-MQTT Configurations If not, this library will use MQTT protocol 3.1 Default value: · Yes (enabled)
CONFIG_MQTT_TRANSPORT_SSL Enable MQTT over SSL Found in: Component config > ESP-MQTT Configurations Enable MQTT transport over SSL with mbedtls Default value: · Yes (enabled)

Espressif Systems

1566

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_MQTT_TRANSPORT_WEBSOCKET Enable MQTT over Websocket Found in: Component config > ESP-MQTT Configurations Enable MQTT transport over Websocket. Default value: · Yes (enabled)

CONFIG_MQTT_TRANSPORT_WEBSOCKET_SECURE

Enable MQTT over Websocket Secure

Found in:

Component config > ESP-MQTT Configurations > CON-

FIG_MQTT_TRANSPORT_WEBSOCKET

Enable MQTT transport over Websocket Secure.

Default value: · Yes (enabled)

CONFIG_MQTT_MSG_ID_INCREMENTAL
Use Incremental Message Id
Found in: Component config > ESP-MQTT Configurations
Set this to true for the message id (2.3.1 Packet Identifier) to be generated as an incremental number rather then a random value (used by default)
Default value: · No (disabled)

CONFIG_MQTT_SKIP_PUBLISH_IF_DISCONNECTED
Skip publish if disconnected
Found in: Component config > ESP-MQTT Configurations
Set this to true to avoid publishing (enqueueing messages) if the client is disconnected. The MQTT client tries to publish all messages by default, even in the disconnected state (where the qos1 and qos2 packets are stored in the internal outbox to be published later) The MQTT_SKIP_PUBLISH_IF_DISCONNECTED option allows applications to override this behaviour and not enqueue publish packets in the disconnected state.
Default value: · No (disabled)

CONFIG_MQTT_REPORT_DELETED_MESSAGES
Report deleted messages
Found in: Component config > ESP-MQTT Configurations
Set this to true to post events for all messages which were deleted from the outbox before being correctly sent and confirmed.
Default value: · No (disabled)

Espressif Systems

1567

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_MQTT_USE_CUSTOM_CONFIG MQTT Using custom configurations Found in: Component config > ESP-MQTT Configurations Custom MQTT configurations. Default value: · No (disabled)

CONFIG_MQTT_TCP_DEFAULT_PORT Default MQTT over TCP port Found in: Component config > ESP-MQTT Configurations > CONFIG_MQTT_USE_CUSTOM_CONFIG Default MQTT over TCP port Default value: · 1883 if CONFIG_MQTT_USE_CUSTOM_CONFIG

CONFIG_MQTT_SSL_DEFAULT_PORT Default MQTT over SSL port Found in: Component config > ESP-MQTT Configurations > CONFIG_MQTT_USE_CUSTOM_CONFIG Default MQTT over SSL port Default value: · 8883 if CONFIG_MQTT_USE_CUSTOM_CONFIG && CONFIG_MQTT_TRANSPORT_SSL

CONFIG_MQTT_WS_DEFAULT_PORT

Default MQTT over Websocket port

Found in: Component config > ESP-MQTT Configurations > CONFIG_MQTT_USE_CUSTOM_CONFIG

Default MQTT over Websocket port

Default value:

· 80

if

CONFIG_MQTT_USE_CUSTOM_CONFIG

&&

CON-

FIG_MQTT_TRANSPORT_WEBSOCKET

CONFIG_MQTT_WSS_DEFAULT_PORT

Default MQTT over Websocket Secure port

Found in: Component config > ESP-MQTT Configurations > CONFIG_MQTT_USE_CUSTOM_CONFIG

Default MQTT over Websocket Secure port

Default value:

· 443

if

CONFIG_MQTT_USE_CUSTOM_CONFIG

&&

CON-

FIG_MQTT_TRANSPORT_WEBSOCKET && CONFIG_MQTT_TRANSPORT_WEBSOCKET_SECURE

CONFIG_MQTT_BUFFER_SIZE Default MQTT Buffer Size Found in: Component config > ESP-MQTT Configurations > CONFIG_MQTT_USE_CUSTOM_CONFIG This buffer size using for both transmit and receive Default value: · 1024 if CONFIG_MQTT_USE_CUSTOM_CONFIG

Espressif Systems

1568

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_MQTT_TASK_STACK_SIZE MQTT task stack size Found in: Component config > ESP-MQTT Configurations > CONFIG_MQTT_USE_CUSTOM_CONFIG MQTT task stack size Default value: · 6144 if CONFIG_MQTT_USE_CUSTOM_CONFIG

CONFIG_MQTT_DISABLE_API_LOCKS
Disable API locks
Found in: Component config > ESP-MQTT Configurations > CONFIG_MQTT_USE_CUSTOM_CONFIG
Default config employs API locks to protect internal structures. It is possible to disable these locks if the user code doesnnt access MQTT API from multiple concurrent tasks
Default value: · No (disabled) if CONFIG_MQTT_USE_CUSTOM_CONFIG

CONFIG_MQTT_TASK_PRIORITY MQTT task priority Found in: Component config > ESP-MQTT Configurations > CONFIG_MQTT_USE_CUSTOM_CONFIG MQTT task priority. Higher number denotes higher priority. Default value: · 5 if CONFIG_MQTT_USE_CUSTOM_CONFIG

CONFIG_MQTT_TASK_CORE_SELECTION_ENABLED Enable MQTT task core selection Found in: Component config > ESP-MQTT Configurations This will enable core selection Default value: ·ofalsep

CONFIG_MQTT_TASK_CORE_SELECTION

Core to use ?

Found in:

Component config > ESP-MQTT Configurations > CON-

FIG_MQTT_TASK_CORE_SELECTION_ENABLED

Available options: · Core 0 (MQTT_USE_CORE_0) · Core 1 (MQTT_USE_CORE_1)

CONFIG_MQTT_CUSTOM_OUTBOX
Enable custom outbox implementation
Found in: Component config > ESP-MQTT Configurations
Set to true if a specific implementation of message outbox is needed (e.g. persistent outbox in NVM or similar). Note: Implementation of the custom outbox must be added to the mqtt component. These CMake commands could be used to append the custom implementation to lib-mqtt sources:

Espressif Systems

1569

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

idf_component_get_property(mqtt mqtt COMPONENT_LIB) set_property(TARGET ${mqtt} PROPERTY SOURCES ${PROJECT_DIR}/custom_outbox.c APPEND) Default value:
· No (disabled)
CONFIG_MQTT_OUTBOX_EXPIRED_TIMEOUT_MS Outbox message expired timeout[ms] Found in: Component config > ESP-MQTT Configurations Messages which stays in the outbox longer than this value before being published will be discarded. Default value: · 30000 if CONFIG_MQTT_USE_CUSTOM_CONFIG
Newlib Contains: · CONFIG_NEWLIB_NANO_FORMAT · CONFIG_NEWLIB_STDIN_LINE_ENDING · CONFIG_NEWLIB_STDOUT_LINE_ENDING
CONFIG_NEWLIB_STDOUT_LINE_ENDING Line ending for UART output Found in: Component config > Newlib This option allows configuring the desired line endings sent to UART when a newline (mnn, LF) appears on stdout. Three options are possible: CRLF: whenever LF is encountered, prepend it with CR LF: no modification is applied, stdout is sent as is CR: each occurence of LF is replaced with CR This option doesnnt affect behavior of the UART driver (drivers/uart.h). Available options: · CRLF (NEWLIB_STDOUT_LINE_ENDING_CRLF) · LF (NEWLIB_STDOUT_LINE_ENDING_LF) · CR (NEWLIB_STDOUT_LINE_ENDING_CR)
CONFIG_NEWLIB_STDIN_LINE_ENDING Line ending for UART input Found in: Component config > Newlib This option allows configuring which input sequence on UART produces a newline (mnn, LF) on stdin. Three options are possible: CRLF: CRLF is converted to LF LF: no modification is applied, input is sent to stdin as is CR: each occurence of CR is replaced with LF This option doesnnt affect behavior of the UART driver (drivers/uart.h). Available options: · CRLF (NEWLIB_STDIN_LINE_ENDING_CRLF) · LF (NEWLIB_STDIN_LINE_ENDING_LF) · CR (NEWLIB_STDIN_LINE_ENDING_CR)

Espressif Systems

1570

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_NEWLIB_NANO_FORMAT Enable mnanonformatting options for printf/scanf family Found in: Component config > Newlib ESP32 ROM contains parts of newlib C library, including printf/scanf family of functions. These functions have been compiled with so-calledonanopformatting option. This option doesnnt support 64-bit integer formats and C99 features, such as positional arguments. For more details about onanopformatting option, please see newlib readme file, search for menablenewlib-nano-formatted-ion: https://sourceware.org/newlib/README If this option is enabled, build system will use functions available in ROM, reducing the application binary size. Functions available in ROM run faster than functions which run from flash. Functions available in ROM can also run when flash instruction cache is disabled. If you need 64-bit integer formatting support or C99 features, keep this option disabled. Default value: · No (disabled)
NVS Contains: · CONFIG_NVS_ENCRYPTION · CONFIG_NVS_COMPATIBLE_PRE_V4_3_ENCRYPTION_FLAG
CONFIG_NVS_ENCRYPTION Enable NVS encryption Found in: Component config > NVS This option enables encryption for NVS. When enabled, AES-XTS is used to encrypt the complete NVS data, except the page headers. It requires XTS encryption keys to be stored in an encrypted partition. This means enabling flash encryption is a pre-requisite for this feature. Default value: · Yes (enabled) if CONFIG_SECURE_FLASH_ENC_ENABLED
CONFIG_NVS_COMPATIBLE_PRE_V4_3_ENCRYPTION_FLAG NVS partition encrypted flag compatible with ESP-IDF before v4.3 Found in: Component config > NVS Enabling this will ignore oencryptedpflag for NVS partitions. NVS encryption scheme is different than hardware flash encryption and hence it is not recommended to have oencryptedpflag for NVS partitions. This was not being checked in pre v4.3 IDF. Hence, if you have any devices where this flag is kept enabled in partition table then enabling this config will allow to have same behavior as pre v4.3 IDF.
OpenSSL Contains: · CONFIG_OPENSSL_DEBUG · CONFIG_OPENSSL_ERROR_STACK · CONFIG_OPENSSL_LOWLEVEL_DEBUG · CONFIG_OPENSSL_DEBUG_LEVEL · CONFIG_OPENSSL_ASSERT

Espressif Systems

1571

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_OPENSSL_DEBUG Enable OpenSSL debugging Found in: Component config > OpenSSL Enable OpenSSL debugging function. If the option is enabled, oSSL_DEBUGpworks. Default value: · No (disabled)
CONFIG_OPENSSL_ERROR_STACK Enable OpenSSL error structure Found in: Component config > OpenSSL Enable OpenSSL Error reporting Default value: · Yes (enabled)
CONFIG_OPENSSL_DEBUG_LEVEL OpenSSL debugging level Found in: Component config > OpenSSL OpenSSL debugging level. Only function whose debugging level is higher than oOPENSSL_DEBUG_LEVELpworks. For example: If OPENSSL_DEBUG_LEVEL = 2, you use functionoSSL_DEBUG(1,omalloc failedp )p. Because 1 < 2, it will not print. Range: · from 0 to 255 if CONFIG_OPENSSL_DEBUG Default value: · 0 if CONFIG_OPENSSL_DEBUG
CONFIG_OPENSSL_LOWLEVEL_DEBUG Enable OpenSSL low-level module debugging Found in: Component config > OpenSSL If the option is enabled, low-level module debugging function of OpenSSL is enabled, e.g. mbedtls internal debugging function. Default value: · No (disabled) if CONFIG_OPENSSL_DEBUG
CONFIG_OPENSSL_ASSERT Select OpenSSL assert function Found in: Component config > OpenSSL OpenSSL function needs oassertpfunction to check if input parameters are valid. If you want to use assert debugging function, oOPENSSL_DEBUGpshould be enabled. Available options: · Do nothing (OPENSSL_ASSERT_DO_NOTHING) Do nothing and oSSL_ASSERTpdoes not work.

Espressif Systems

1572

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· Check and exit (OPENSSL_ASSERT_EXIT) Enable assert exiting, it will check and return error code.
· Show debugging message (OPENSSL_ASSERT_DEBUG) Enable assert debugging, it will check and show debugging message.
· Show debugging message and exit (OPENSSL_ASSERT_DEBUG_EXIT) Enable assert debugging and exiting, it will check, show debugging message and return error code.
· Show debugging message and block (OPENSSL_ASSERT_DEBUG_BLOCK) Enable assert debugging and blocking, it will check, show debugging message and block by
owhile (1);p.
OpenThread Contains: · CONFIG_OPENTHREAD_ENABLED
CONFIG_OPENTHREAD_ENABLED OpenThread Found in: Component config > OpenThread Select this option to enable OpenThread and show the submenu with OpenThread configuration choices. Default value: · No (disabled)
CONFIG_OPENTHREAD_RADIO_TYPE Config the Thread radio type Found in: Component config > OpenThread > CONFIG_OPENTHREAD_ENABLED Configure how OpenThread connects to the 15.4 radio Available options: · Native 15.4 radio (OPENTHREAD_RADIO_NATIVE) Select this to use the native 15.4 radio. · Connect via UART (OPENTHREAD_RADIO_SPINEL_UART) Select this to connect to a Radio Co-Processor via UART.
CONFIG_OPENTHREAD_DEVICE_TYPE Config the Thread device type Found in: Component config > OpenThread > CONFIG_OPENTHREAD_ENABLED OpenThread can be configured to different device types (FTD, MTD, Radio) Available options: · Full Thread Device (OPENTHREAD_FTD) Select this to enable Full Thread Device which can act as router and leader in a Thread network. · Minimal Thread Device (OPENTHREAD_MTD) Select this to enable Minimal Thread Device which can only act as end device in a Thread network. This will reduce the code size of the OpenThread stack. · Radio Only Device (OPENTHREAD_RADIO) Select this to enable Radio Only Device which can only forward 15.4 packets to the host. The OpenThread stack will be run on the host and OpenThread will have minimal footprint on the radio only device.

Espressif Systems

1573

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_OPENTHREAD_DIAG Enable diag Found in: Component config > OpenThread > CONFIG_OPENTHREAD_ENABLED Select this option to enable Diag in OpenThread. This will enable diag mode and a series of diag commands in the OpenThread command line. These commands allow users to manipulate low-level features of the storage and 15.4 radio. Default value: · Yes (enabled) if CONFIG_OPENTHREAD_ENABLED
CONFIG_OPENTHREAD_COMMISSIONER Enable Commissioner Found in: Component config > OpenThread > CONFIG_OPENTHREAD_ENABLED Select this option to enable commissioner in OpenThread. This will enable the device to act as a commissioner in the Thread network. A commissioner checks the pre-shared key from a joining device with the Thread commissioning protocol and shares the network parameter with the joining device upon success. Default value: · No (disabled) if CONFIG_OPENTHREAD_ENABLED
CONFIG_OPENTHREAD_JOINER Enable Joiner Found in: Component config > OpenThread > CONFIG_OPENTHREAD_ENABLED Select this option to enable Joiner in OpenThread. This allows a device to join the Thread network with a pre-shared key using the Thread commissioning protocol. Default value: · No (disabled) if CONFIG_OPENTHREAD_ENABLED
CONFIG_OPENTHREAD_SRP_CLIENT Enable SRP Client Found in: Component config > OpenThread > CONFIG_OPENTHREAD_ENABLED Select this option to enable SRP Client in OpenThread. This allows a device to register SRP services to SRP Server. Default value: · No (disabled) if CONFIG_OPENTHREAD_ENABLED
CONFIG_OPENTHREAD_BORDER_ROUTER Enable Border Router Found in: Component config > OpenThread > CONFIG_OPENTHREAD_ENABLED Select this option to enable border router features in OpenThread. Default value: · No (disabled) if CONFIG_OPENTHREAD_ENABLED

Espressif Systems

1574

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_OPENTHREAD_TREL
Enable Thread Radio Encapsulation Link
Found in: Component config > OpenThread > CONFIG_OPENTHREAD_ENABLED > CONFIG_OPENTHREAD_BORDER_ROUTER
Select this option to enable sending 15.4 frames through the backbone interface.
Default value: · No (disabled) if CONFIG_OPENTHREAD_BORDER_ROUTER

CONFIG_OPENTHREAD_ESP_LIB_FROM_INTERNAL_SRC Build esp_openthread libraries from source Found in: Component config > OpenThread > CONFIG_OPENTHREAD_ENABLED Override the shipped libopenthread_br.a and libopenthread_port.a, for internal builds. Default value: · No (disabled) if CONFIG_OPENTHREAD_ENABLED

CONFIG_OPENTHREAD_NUM_MESSAGE_BUFFERS
The number of openthread message buffers
Found in: Component config > OpenThread > CONFIG_OPENTHREAD_ENABLED
Range: · from 50 to 100 if CONFIG_OPENTHREAD_ENABLED
Default value: · 65 if CONFIG_OPENTHREAD_ENABLED

PThreads Contains:
· CONFIG_PTHREAD_TASK_NAME_DEFAULT · CONFIG_PTHREAD_TASK_CORE_DEFAULT · CONFIG_PTHREAD_TASK_PRIO_DEFAULT · CONFIG_PTHREAD_TASK_STACK_SIZE_DEFAULT · CONFIG_PTHREAD_STACK_MIN

CONFIG_PTHREAD_TASK_PRIO_DEFAULT
Default task priority
Found in: Component config > PThreads
Priority used to create new tasks with default pthread parameters.
Range: · from 0 to 255
Default value: ·5

CONFIG_PTHREAD_TASK_STACK_SIZE_DEFAULT Default task stack size Found in: Component config > PThreads Stack size used to create new tasks with default pthread parameters. Default value: · 3072

Espressif Systems

1575

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_PTHREAD_STACK_MIN Minimum allowed pthread stack size Found in: Component config > PThreads Minimum allowed pthread stack size set in attributes passed to pthread_create Default value: · 768

CONFIG_PTHREAD_TASK_CORE_DEFAULT
Default pthread core affinity
Found in: Component config > PThreads
The default core to which pthreads are pinned.
Available options: · No affinity (PTHREAD_DEFAULT_CORE_NO_AFFINITY) · Core 0 (PTHREAD_DEFAULT_CORE_0) · Core 1 (PTHREAD_DEFAULT_CORE_1)

CONFIG_PTHREAD_TASK_NAME_DEFAULT Default name of pthreads Found in: Component config > PThreads The default name of pthreads. Default value: ·opthreadp

SPI Flash driver Contains:
· Auto-detect flash chips · CONFIG_SPI_FLASH_BYPASS_BLOCK_ERASE · CONFIG_SPI_FLASH_ENABLE_ENCRYPTED_READ_WRITE · CONFIG_SPI_FLASH_ENABLE_COUNTERS · CONFIG_SPI_FLASH_ROM_DRIVER_PATCH · CONFIG_SPI_FLASH_YIELD_DURING_ERASE · CONFIG_SPI_FLASH_CHECK_ERASE_TIMEOUT_DISABLED · CONFIG_SPI_FLASH_WRITE_CHUNK_SIZE · CONFIG_SPI_FLASH_OVERRIDE_CHIP_DRIVER_LIST · CONFIG_SPI_FLASH_SIZE_OVERRIDE · CONFIG_SPI_FLASH_SHARE_SPI1_BUS · CONFIG_SPI_FLASH_ROM_IMPL · CONFIG_SPI_FLASH_USE_LEGACY_IMPL · CONFIG_SPI_FLASH_VERIFY_WRITE · CONFIG_SPI_FLASH_DANGEROUS_WRITE

CONFIG_SPI_FLASH_VERIFY_WRITE
Verify SPI flash writes
Found in: Component config > SPI Flash driver
If this option is enabled, any time SPI flash is written then the data will be read back and verified. This can catch hardware problems with SPI flash, or flash which was not erased before verification.
Default value: · No (disabled)

Espressif Systems

1576

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_SPI_FLASH_LOG_FAILED_WRITE Log errors if verification fails Found in: Component config > SPI Flash driver > CONFIG_SPI_FLASH_VERIFY_WRITE If this option is enabled, if SPI flash write verification fails then a log error line will be written with the address, expected & actual values. This can be useful when debugging hardware SPI flash problems. Default value: · No (disabled) if CONFIG_SPI_FLASH_VERIFY_WRITE
CONFIG_SPI_FLASH_WARN_SETTING_ZERO_TO_ONE Log warning if writing zero bits to ones Found in: Component config > SPI Flash driver > CONFIG_SPI_FLASH_VERIFY_WRITE If this option is enabled, any SPI flash write which tries to set zero bits in the flash to ones will log a warning. Such writes will not result in the requested data appearing identically in flash once written, as SPI NOR flash can only set bits to one when an entire sector is erased. After erasing, individual bits can only be written from one to zero. Note that some software (such as SPIFFS) which is aware of SPI NOR flash may write one bits as an optimisation, relying on the data in flash becoming a bitwise AND of the new data and any existing data. Such software will log spurious warnings if this option is enabled. Default value: · No (disabled) if CONFIG_SPI_FLASH_VERIFY_WRITE
CONFIG_SPI_FLASH_ENABLE_COUNTERS Enable operation counters Found in: Component config > SPI Flash driver This option enables the following APIs: · spi_flash_reset_counters · spi_flash_dump_counters · spi_flash_get_counters These APIs may be used to collect performance data for spi_flash APIs and to help understand behaviour of libraries which use SPI flash. Default value: ·0
CONFIG_SPI_FLASH_ROM_DRIVER_PATCH Enable SPI flash ROM driver patched functions Found in: Component config > SPI Flash driver Enable this flag to use patched versions of SPI flash ROM driver functions. This option should be enabled, if any one of the following is true: (1) need to write to flash on ESP32-D2WD; (2) main SPI flash is connected to non-default pins; (3) main SPI flash chip is manufactured by ISSI. Default value: · Yes (enabled)

Espressif Systems

1577

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_SPI_FLASH_ROM_IMPL Use esp_flash implementation in ROM Found in: Component config > SPI Flash driver Enable this flag to use new SPI flash driver functions from ROM instead of ESP-IDF. If keeping this as onpin your project, you will have less free IRAM. But you can use all of our flash features. If making this asoypin your project, you will increase free IRAM. But you may miss out on some flash features and support for new flash chips. Currently the ROM cannot support the following features: · SPI_FLASH_AUTO_SUSPEND (C3, S3) Default value: · No (disabled)
CONFIG_SPI_FLASH_DANGEROUS_WRITE Writing to dangerous flash regions Found in: Component config > SPI Flash driver SPI flash APIs can optionally abort or return a failure code if erasing or writing addresses that fall at the beginning of flash (covering the bootloader and partition table) or that overlap the app partition that contains the running app. It is not recommended to ever write to these regions from an IDF app, and this check prevents logic errors or corrupted firmware memory from damaging these regions. Note that this feature *does not* check calls to the esp_rom_xxx SPI flash ROM functions. These functions should not be called directly from IDF applications. Available options: · Aborts (SPI_FLASH_DANGEROUS_WRITE_ABORTS) · Fails (SPI_FLASH_DANGEROUS_WRITE_FAILS) · Allowed (SPI_FLASH_DANGEROUS_WRITE_ALLOWED)
CONFIG_SPI_FLASH_USE_LEGACY_IMPL Use the legacy implementation before IDF v4.0 Found in: Component config > SPI Flash driver The implementation of SPI flash has been greatly changed in IDF v4.0. Enable this option to use the legacy implementation. Default value: · No (disabled)
CONFIG_SPI_FLASH_SHARE_SPI1_BUS Support other devices attached to SPI1 bus Found in: Component config > SPI Flash driver Each SPI bus needs a lock for arbitration among devices. This allows multiple devices on a same bus, but may reduce the speed of esp_flash driver access to the main flash chip. If you only need to use esp_flash driver to access the main flash chip, disable this option, and the lock will be bypassed on SPI1 bus. Otherwise if extra devices are needed to attach to SPI1 bus, enable this option.

Espressif Systems

1578

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Default value: · No (disabled) if CONFIG_SPI_FLASH_USE_LEGACY_IMPL

CONFIG_SPI_FLASH_BYPASS_BLOCK_ERASE
Bypass a block erase and always do sector erase
Found in: Component config > SPI Flash driver
Some flash chips can have very high omaxperase times, especially for block erase (32KB or 64KB). This option allows to bypass oblock erasepand always do sector erase commands. This will be much slower overall in most cases, but improves latency for other code to run.
Default value: · No (disabled)

CONFIG_SPI_FLASH_YIELD_DURING_ERASE
Enables yield operation during flash erase
Found in: Component config > SPI Flash driver
This allows to yield the CPUs between erase commands. Prevents starvation of other tasks. Please use this configuration together with SPI\_FLASH\_ERASE\_YIELD\_DURATION\_MS and SPI\ _FLASH\_ERASE\_YIELD\_TICKS after carefully checking flash datasheet to avoid a watchdog timeout. For more information, please check SPI Flash API reference documenation under section OS Function.
Default value: · Yes (enabled)

CONFIG_SPI_FLASH_ERASE_YIELD_DURATION_MS Duration of erasing to yield CPUs (ms) Found in: Component config > SPI Flash driver > CONFIG_SPI_FLASH_YIELD_DURING_ERASE If a duration of one erase command is large then it will yield CPUs after finishing a current command. Default value: · 20

CONFIG_SPI_FLASH_ERASE_YIELD_TICKS CPU release time (tick) for an erase operation Found in: Component config > SPI Flash driver > CONFIG_SPI_FLASH_YIELD_DURING_ERASE Defines how many ticks will be before returning to continue a erasing. Default value: ·1

CONFIG_SPI_FLASH_WRITE_CHUNK_SIZE
Flash write chunk size
Found in: Component config > SPI Flash driver
Flash write is broken down in terms of multiple (smaller) write operations. This configuration options helps to set individual write chunk size, smaller value here ensures that cache (and non-IRAM resident interrupts) remains disabled for shorter duration.
Range: · from 256 to 8192

Espressif Systems

1579

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Default value: · 8192
CONFIG_SPI_FLASH_SIZE_OVERRIDE Override flash size in bootloader header by ESPTOOLPY_FLASHSIZE Found in: Component config > SPI Flash driver SPI Flash driver uses the flash size configured in bootloader header by default. Enable this option to override flash size with latest ESPTOOLPY_FLASHSIZE value from the app header if the size in the bootloader header is incorrect. Default value: · No (disabled)
CONFIG_SPI_FLASH_CHECK_ERASE_TIMEOUT_DISABLED Flash timeout checkout disabled Found in: Component config > SPI Flash driver This option is helpful if you are using a flash chip whose timeout is quite large or unpredictable. Default value: · No (disabled) if CONFIG_SPI_FLASH_USE_LEGACY_IMPL
CONFIG_SPI_FLASH_OVERRIDE_CHIP_DRIVER_LIST Override default chip driver list Found in: Component config > SPI Flash driver This option allows the chip driver list to be customized, instead of using the default list provided by ESP-IDF. When this option is enabled, the default list is no longer compiled or linked. Instead, the default_registered_chips structure must be provided by the user. See example: custom_chip_driver under examples/storage for more details. Default value: · No (disabled) if CONFIG_SPI_FLASH_USE_LEGACY_IMPL
Auto-detect flash chips Contains: · CONFIG_SPI_FLASH_SUPPORT_BOYA_CHIP · CONFIG_SPI_FLASH_SUPPORT_GD_CHIP · CONFIG_SPI_FLASH_SUPPORT_ISSI_CHIP · CONFIG_SPI_FLASH_SUPPORT_MXIC_CHIP · CONFIG_SPI_FLASH_SUPPORT_MXIC_OPI_CHIP · CONFIG_SPI_FLASH_SUPPORT_TH_CHIP · CONFIG_SPI_FLASH_SUPPORT_WINBOND_CHIP
CONFIG_SPI_FLASH_SUPPORT_ISSI_CHIP ISSI Found in: Component config > SPI Flash driver > Auto-detect flash chips Enable this to support auto detection of ISSI chips if chip vendor not directly given by chip\_drv member of the chip struct. This adds support for variant chips, however will extend detecting time. Default value:

Espressif Systems

1580

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· Yes (enabled)
CONFIG_SPI_FLASH_SUPPORT_MXIC_CHIP MXIC Found in: Component config > SPI Flash driver > Auto-detect flash chips Enable this to support auto detection of MXIC chips if chip vendor not directly given by chip\_drv member of the chip struct. This adds support for variant chips, however will extend detecting time. Default value: · Yes (enabled)
CONFIG_SPI_FLASH_SUPPORT_GD_CHIP GigaDevice Found in: Component config > SPI Flash driver > Auto-detect flash chips Enable this to support auto detection of GD (GigaDevice) chips if chip vendor not directly given by chip\_drv member of the chip struct. If you are using Wrover modules, please donnt disable this, otherwise your flash may not work in 4-bit mode. This adds support for variant chips, however will extend detecting time and image size. Note that the default chip driver supports the GD chips with product ID 60H. Default value: · Yes (enabled)
CONFIG_SPI_FLASH_SUPPORT_WINBOND_CHIP Winbond Found in: Component config > SPI Flash driver > Auto-detect flash chips Enable this to support auto detection of Winbond chips if chip vendor not directly given by chip\_drv member of the chip struct. This adds support for variant chips, however will extend detecting time. Default value: · Yes (enabled)
CONFIG_SPI_FLASH_SUPPORT_BOYA_CHIP BOYA Found in: Component config > SPI Flash driver > Auto-detect flash chips Enable this to support auto detection of BOYA chips if chip vendor not directly given by chip\_drv member of the chip struct. This adds support for variant chips, however will extend detecting time. Default value: · Yes (enabled)
CONFIG_SPI_FLASH_SUPPORT_TH_CHIP TH Found in: Component config > SPI Flash driver > Auto-detect flash chips Enable this to support auto detection of TH chips if chip vendor not directly given by chip\_drv member of the chip struct. This adds support for variant chips, however will extend detecting time. Default value: · Yes (enabled)

Espressif Systems

1581

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_SPI_FLASH_SUPPORT_MXIC_OPI_CHIP mxic (opi) Found in: Component config > SPI Flash driver > Auto-detect flash chips Enable this to support auto detection of Octal MXIC chips if chip vendor not directly given by chip\ _drv member of the chip struct. This adds support for variant chips, however will extend detecting time. Default value: · Yes (enabled)
CONFIG_SPI_FLASH_ENABLE_ENCRYPTED_READ_WRITE Enable encrypted partition read/write operations Found in: Component config > SPI Flash driver This option enables flash read/write operations to encrypted partition/s. This option is kept enabled irrespective of state of flash encryption feature. However, in case application is not using flash encryption feature and is in need of some additional memory from IRAM region (~1KB) then this config can be disabled. Default value: · Yes (enabled)
SPIFFS Configuration Contains: · Debug Configuration · CONFIG_SPIFFS_USE_MAGIC · CONFIG_SPIFFS_GC_STATS · CONFIG_SPIFFS_PAGE_CHECK · CONFIG_SPIFFS_FOLLOW_SYMLINKS · CONFIG_SPIFFS_MAX_PARTITIONS · CONFIG_SPIFFS_USE_MTIME · CONFIG_SPIFFS_GC_MAX_RUNS · CONFIG_SPIFFS_OBJ_NAME_LEN · CONFIG_SPIFFS_META_LENGTH · SPIFFS Cache Configuration · CONFIG_SPIFFS_PAGE_SIZE · CONFIG_SPIFFS_MTIME_WIDE_64_BITS
CONFIG_SPIFFS_MAX_PARTITIONS Maximum Number of Partitions Found in: Component config > SPIFFS Configuration Define maximum number of partitions that can be mounted. Range: · from 1 to 10 Default value: ·3
SPIFFS Cache Configuration Contains: · CONFIG_SPIFFS_CACHE

Espressif Systems

1582

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_SPIFFS_CACHE Enable SPIFFS Cache Found in: Component config > SPIFFS Configuration > SPIFFS Cache Configuration Enables/disable memory read caching of nucleus file system operations. Default value: · Yes (enabled)
CONFIG_SPIFFS_CACHE_WR Enable SPIFFS Write Caching Found in: Component config > SPIFFS Configuration > SPIFFS Cache Configuration > CONFIG_SPIFFS_CACHE Enables memory write caching for file descriptors in hydrogen. Default value: · Yes (enabled)
CONFIG_SPIFFS_CACHE_STATS Enable SPIFFS Cache Statistics Found in: Component config > SPIFFS Configuration > SPIFFS Cache Configuration > CONFIG_SPIFFS_CACHE Enable/disable statistics on caching. Debug/test purpose only. Default value: · No (disabled)
CONFIG_SPIFFS_PAGE_CHECK Enable SPIFFS Page Check Found in: Component config > SPIFFS Configuration Always check header of each accessed page to ensure consistent state. If enabled it will increase number of reads from flash, especially if cache is disabled. Default value: · Yes (enabled)
CONFIG_SPIFFS_GC_MAX_RUNS Set Maximum GC Runs Found in: Component config > SPIFFS Configuration Define maximum number of GC runs to perform to reach desired free pages. Range: · from 1 to 255 Default value: · 10

Espressif Systems

1583

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_SPIFFS_GC_STATS Enable SPIFFS GC Statistics Found in: Component config > SPIFFS Configuration Enable/disable statistics on gc. Debug/test purpose only. Default value: · No (disabled)
CONFIG_SPIFFS_PAGE_SIZE SPIFFS logical page size Found in: Component config > SPIFFS Configuration Logical page size of SPIFFS partition, in bytes. Must be multiple of flash page size (which is usually 256 bytes). Larger page sizes reduce overhead when storing large files, and improve filesystem performance when reading large files. Smaller page sizes reduce overhead when storing small (< page size) files. Range: · from 256 to 1024 Default value: · 256
CONFIG_SPIFFS_OBJ_NAME_LEN Set SPIFFS Maximum Name Length Found in: Component config > SPIFFS Configuration Object name maximum length. Note that this length include the zero-termination character, meaning maximum string of characters can at most be SPIFFS_OBJ_NAME_LEN - 1. SPIFFS_OBJ_NAME_LEN + SPIFFS_META_LENGTH should not exceed SPIFFS_PAGE_SIZE 64. Range: · from 1 to 256 Default value: · 32
CONFIG_SPIFFS_FOLLOW_SYMLINKS Enable symbolic links for image creation Found in: Component config > SPIFFS Configuration If this option is enabled, symbolic links are taken into account during partition image creation. Default value: · No (disabled)
CONFIG_SPIFFS_USE_MAGIC Enable SPIFFS Filesystem Magic Found in: Component config > SPIFFS Configuration Enable this to have an identifiable spiffs filesystem. This will look for a magic in all sectors to determine if this is a valid spiffs system or not at mount time. Default value: · Yes (enabled)

Espressif Systems

1584

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_SPIFFS_USE_MAGIC_LENGTH Enable SPIFFS Filesystem Length Magic Found in: Component config > SPIFFS Configuration > CONFIG_SPIFFS_USE_MAGIC If this option is enabled, the magic will also be dependent on the length of the filesystem. For example, a filesystem configured and formatted for 4 megabytes will not be accepted for mounting with a configuration defining the filesystem as 2 megabytes. Default value: · Yes (enabled)
CONFIG_SPIFFS_META_LENGTH Size of per-file metadata field Found in: Component config > SPIFFS Configuration This option sets the number of extra bytes stored in the file header. These bytes can be used in an application-specific manner. Set this to at least 4 bytes to enable support for saving file modification time. SPIFFS_OBJ_NAME_LEN + SPIFFS_META_LENGTH should not exceed SPIFFS_PAGE_SIZE 64. Default value: ·4
CONFIG_SPIFFS_USE_MTIME Save file modification time Found in: Component config > SPIFFS Configuration If enabled, then the first 4 bytes of per-file metadata will be used to store file modification time (mtime), accessible through stat/fstat functions. Modification time is updated when the file is opened. Default value: · Yes (enabled)
CONFIG_SPIFFS_MTIME_WIDE_64_BITS The time field occupies 64 bits in the image instead of 32 bits Found in: Component config > SPIFFS Configuration If this option is not set, the time field is 32 bits (up to 2106 year), otherwise it is 64 bits and make sure it matches SPIFFS_META_LENGTH. If the chip already has the spiffs image with the time field = 32 bits then this option cannot be applied in this case. Erase it first before using this option. To resolve the Y2K38 problem for the spiffs, use a toolchain with 64-bit time_t support. Default value: · No (disabled) if CONFIG_SPIFFS_META_LENGTH >= 8
Debug Configuration Contains: · CONFIG_SPIFFS_DBG · CONFIG_SPIFFS_API_DBG · CONFIG_SPIFFS_CACHE_DBG · CONFIG_SPIFFS_CHECK_DBG · CONFIG_SPIFFS_TEST_VISUALISATION · CONFIG_SPIFFS_GC_DBG

Espressif Systems

1585

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_SPIFFS_DBG Enable general SPIFFS debug Found in: Component config > SPIFFS Configuration > Debug Configuration Enabling this option will print general debug mesages to the console. Default value: · No (disabled)
CONFIG_SPIFFS_API_DBG Enable SPIFFS API debug Found in: Component config > SPIFFS Configuration > Debug Configuration Enabling this option will print API debug mesages to the console. Default value: · No (disabled)
CONFIG_SPIFFS_GC_DBG Enable SPIFFS Garbage Cleaner debug Found in: Component config > SPIFFS Configuration > Debug Configuration Enabling this option will print GC debug mesages to the console. Default value: · No (disabled)
CONFIG_SPIFFS_CACHE_DBG Enable SPIFFS Cache debug Found in: Component config > SPIFFS Configuration > Debug Configuration Enabling this option will print cache debug mesages to the console. Default value: · No (disabled)
CONFIG_SPIFFS_CHECK_DBG Enable SPIFFS Filesystem Check debug Found in: Component config > SPIFFS Configuration > Debug Configuration Enabling this option will print Filesystem Check debug mesages to the console. Default value: · No (disabled)
CONFIG_SPIFFS_TEST_VISUALISATION Enable SPIFFS Filesystem Visualization Found in: Component config > SPIFFS Configuration > Debug Configuration Enable this option to enable SPIFFS_vis function in the API. Default value: · No (disabled)

Espressif Systems

1586

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

TCP Transport Contains: · Websocket
Websocket Contains: · CONFIG_WS_TRANSPORT
CONFIG_WS_TRANSPORT Enable Websocket Transport Found in: Component config > TCP Transport > Websocket Enable support for creating websocket transport. Default value: · Yes (enabled)
CONFIG_WS_BUFFER_SIZE Websocket transport buffer size Found in: Component config > TCP Transport > Websocket > CONFIG_WS_TRANSPORT Size of the buffer used for constructing the HTTP Upgrade request during connect Default value: · 1024
TinyUSB Stack Contains: · CONFIG_TINYUSB
CONFIG_TINYUSB Use TinyUSB Stack Found in: Component config > TinyUSB Stack Enable TinyUSB stack support. Note that, esp-idf only uses the device stack provided by TinyUSB. Default value: · No (disabled)
CONFIG_TINYUSB_DEBUG_LEVEL TinyUSB log level (0-3) Found in: Component config > TinyUSB Stack > CONFIG_TINYUSB Specify verbosity of TinyUSB log output. Range: · from 0 to 3 if CONFIG_TINYUSB Default value: · 0 if CONFIG_TINYUSB
TinyUSB task configuration Contains: · CONFIG_TINYUSB_NO_DEFAULT_TASK · CONFIG_TINYUSB_TASK_PRIORITY · CONFIG_TINYUSB_TASK_STACK_SIZE

Espressif Systems

1587

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_TINYUSB_NO_DEFAULT_TASK Do not create a TinyUSB task Found in: Component config > TinyUSB Stack > CONFIG_TINYUSB > TinyUSB task configuration This option allows to not create the FreeRTOS task during the driver initialization. User will have to handle TinyUSB events manually. Default value: · No (disabled) if CONFIG_TINYUSB
CONFIG_TINYUSB_TASK_PRIORITY TinyUSB task priority Found in: Component config > TinyUSB Stack > CONFIG_TINYUSB > TinyUSB task configuration Set the priority of the default TinyUSB main task. Default value: · 5 if CONFIG_TINYUSB_NO_DEFAULT_TASK && CONFIG_TINYUSB
CONFIG_TINYUSB_TASK_STACK_SIZE TinyUSB task stack size (bytes) Found in: Component config > TinyUSB Stack > CONFIG_TINYUSB > TinyUSB task configuration Set the stack size of the default TinyUSB main task. Default value: · 4096 if CONFIG_TINYUSB_NO_DEFAULT_TASK && CONFIG_TINYUSB
Descriptor configuration Contains: · CONFIG_TINYUSB_DESC_BCD_DEVICE · CONFIG_TINYUSB_DESC_CDC_STRING · CONFIG_TINYUSB_DESC_HID_STRING · CONFIG_TINYUSB_DESC_MANUFACTURER_STRING · CONFIG_TINYUSB_DESC_MSC_STRING · CONFIG_TINYUSB_DESC_CUSTOM_PID · CONFIG_TINYUSB_DESC_USE_DEFAULT_PID · CONFIG_TINYUSB_DESC_PRODUCT_STRING · CONFIG_TINYUSB_DESC_SERIAL_STRING · CONFIG_TINYUSB_DESC_CUSTOM_VID · CONFIG_TINYUSB_DESC_USE_ESPRESSIF_VID
CONFIG_TINYUSB_DESC_USE_ESPRESSIF_VID VID: Use Espressifns vendor ID Found in: Component config > TinyUSB Stack > CONFIG_TINYUSB > Descriptor configuration Enable this option, USB device will use Espressifns vendor ID as its VID. This is helpful at product develop stage. Default value: · Yes (enabled) if CONFIG_TINYUSB

Espressif Systems

1588

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_TINYUSB_DESC_CUSTOM_VID VID: Custom vendor ID Found in: Component config > TinyUSB Stack > CONFIG_TINYUSB > Descriptor configuration Custom Vendor ID. Default value: ·o0x1234pif CONFIG_TINYUSB_DESC_USE_ESPRESSIF_VID && CONFIG_TINYUSB
CONFIG_TINYUSB_DESC_USE_DEFAULT_PID PID: Use a default PID assigned to TinyUSB Found in: Component config > TinyUSB Stack > CONFIG_TINYUSB > Descriptor configuration Default TinyUSB PID assigning uses values 0x4000l0x4007. Default value: · Yes (enabled) if CONFIG_TINYUSB
CONFIG_TINYUSB_DESC_CUSTOM_PID PID: Custom product ID Found in: Component config > TinyUSB Stack > CONFIG_TINYUSB > Descriptor configuration Custom Product ID. Default value: ·o0x5678pif CONFIG_TINYUSB_DESC_USE_DEFAULT_PID && CONFIG_TINYUSB
CONFIG_TINYUSB_DESC_BCD_DEVICE bcdDevice Found in: Component config > TinyUSB Stack > CONFIG_TINYUSB > Descriptor configuration Version of the firmware of the USB device. Default value: ·o0x0100pif CONFIG_TINYUSB
CONFIG_TINYUSB_DESC_MANUFACTURER_STRING Manufacturer name Found in: Component config > TinyUSB Stack > CONFIG_TINYUSB > Descriptor configuration Name of the manufacturer of the USB device. Default value: ·oEspressif Systemspif CONFIG_TINYUSB
CONFIG_TINYUSB_DESC_PRODUCT_STRING Product name Found in: Component config > TinyUSB Stack > CONFIG_TINYUSB > Descriptor configuration Name of the USB device. Default value: ·oEspressif Devicepif CONFIG_TINYUSB

Espressif Systems

1589

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_TINYUSB_DESC_SERIAL_STRING Serial string Found in: Component config > TinyUSB Stack > CONFIG_TINYUSB > Descriptor configuration Serial number of the USB device. Default value: · 123456 if CONFIG_TINYUSB
CONFIG_TINYUSB_DESC_CDC_STRING CDC Device String Found in: Component config > TinyUSB Stack > CONFIG_TINYUSB > Descriptor configuration Name of the CDC device. Default value: ·oEspressif CDC Devicepif CONFIG_TINYUSB_CDC_ENABLED && CONFIG_TINYUSB
CONFIG_TINYUSB_DESC_MSC_STRING MSC Device String Found in: Component config > TinyUSB Stack > CONFIG_TINYUSB > Descriptor configuration Name of the MSC device. Default value: ·oEspressif MSC Devicepif CONFIG_TINYUSB_MSC_ENABLED && CONFIG_TINYUSB
CONFIG_TINYUSB_DESC_HID_STRING HID Device String Found in: Component config > TinyUSB Stack > CONFIG_TINYUSB > Descriptor configuration Name of the HID device Default value: ·oEspressif HID Devicepif TINYUSB_HID_ENABLED && CONFIG_TINYUSB
Massive Storage Class (MSC) Contains: · CONFIG_TINYUSB_MSC_ENABLED
CONFIG_TINYUSB_MSC_ENABLED Enable TinyUSB MSC feature Found in: Component config > TinyUSB Stack > CONFIG_TINYUSB > Massive Storage Class (MSC) Enable TinyUSB MSC feature. Default value: · No (disabled) if CONFIG_TINYUSB_CDC_COUNT < 2 && CONFIG_TINYUSB

Espressif Systems

1590

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_TINYUSB_MSC_BUFSIZE MSC FIFO size Found in: Component config > TinyUSB Stack > CONFIG_TINYUSB > Massive Storage Class (MSC) > CONFIG_TINYUSB_MSC_ENABLED MSC FIFO size, in bytes. Default value: · 512 if CONFIG_TINYUSB_MSC_ENABLED && CONFIG_TINYUSB
Communication Device Class (CDC) Contains: · CONFIG_TINYUSB_CDC_ENABLED
CONFIG_TINYUSB_CDC_ENABLED Enable TinyUSB CDC feature Found in: Component config > TinyUSB Stack > CONFIG_TINYUSB > Communication Device Class (CDC) Enable TinyUSB CDC feature. Default value: · No (disabled) if CONFIG_TINYUSB
CONFIG_TINYUSB_CDC_COUNT CDC Channel Count Found in: Component config > TinyUSB Stack > CONFIG_TINYUSB > Communication Device Class (CDC) > CONFIG_TINYUSB_CDC_ENABLED Number of independent serial ports. Range: · from 1 to 2 if CONFIG_TINYUSB_CDC_ENABLED && CONFIG_TINYUSB Default value: · 1 if CONFIG_TINYUSB_CDC_ENABLED && CONFIG_TINYUSB
CONFIG_TINYUSB_CDC_RX_BUFSIZE CDC FIFO size of RX channel Found in: Component config > TinyUSB Stack > CONFIG_TINYUSB > Communication Device Class (CDC) > CONFIG_TINYUSB_CDC_ENABLED CDC FIFO size of RX channel. Default value: · 64 if CONFIG_TINYUSB_CDC_ENABLED && CONFIG_TINYUSB
CONFIG_TINYUSB_CDC_TX_BUFSIZE CDC FIFO size of TX channel Found in: Component config > TinyUSB Stack > CONFIG_TINYUSB > Communication Device Class (CDC) > CONFIG_TINYUSB_CDC_ENABLED CDC FIFO size of TX channel. Default value: · 64 if CONFIG_TINYUSB_CDC_ENABLED && CONFIG_TINYUSB

Espressif Systems

1591

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Ultra Low Power (ULP) Co-processor Contains: · CONFIG_ULP_COPROC_ENABLED

CONFIG_ULP_COPROC_ENABLED
Enable Ultra Low Power (ULP) Co-processor
Found in: Component config > Ultra Low Power (ULP) Co-processor
Enable this feature if you plan to use the ULP Co-processor. Once this option is enabled, further ULP co-processor configuration will appear in the menu.
Default value: · No (disabled)

CONFIG_ULP_COPROC_TYPE
ULP Co-processor type
Found in: Component config > Ultra Low Power (ULP) Co-processor > CONFIG_ULP_COPROC_ENABLED
Choose the ULP Coprocessor type: ULP FSM (Finite State Machine) or ULP RISC-V. Please note that ESP32 only supports ULP FSM.
Available options: · ULP FSM (Finite State Machine) (ULP_COPROC_TYPE_FSM) · ULP RISC-V (ULP_COPROC_TYPE_RISCV)

CONFIG_ULP_COPROC_RESERVE_MEM
RTC slow memory reserved for coprocessor
Found in: Component config > Ultra Low Power (ULP) Co-processor > CONFIG_ULP_COPROC_ENABLED
Bytes of memory to reserve for ULP Co-processor firmware & data. Data is reserved at the beginning of RTC slow memory.
Range: · from 32 to 8176 if CONFIG_ULP_COPROC_ENABLED
Default value: · 4096 if CONFIG_ULP_COPROC_ENABLED

Unity unit testing library Contains:
· CONFIG_UNITY_ENABLE_COLOR · CONFIG_UNITY_ENABLE_IDF_TEST_RUNNER · CONFIG_UNITY_ENABLE_FIXTURE · CONFIG_UNITY_ENABLE_BACKTRACE_ON_FAIL · CONFIG_UNITY_ENABLE_64BIT · CONFIG_UNITY_ENABLE_DOUBLE · CONFIG_UNITY_ENABLE_FLOAT

CONFIG_UNITY_ENABLE_FLOAT Support for float type Found in: Component config > Unity unit testing library If not set, assertions on float arguments will not be available. Default value:

Espressif Systems

1592

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· Yes (enabled)

CONFIG_UNITY_ENABLE_DOUBLE Support for double type Found in: Component config > Unity unit testing library If not set, assertions on double arguments will not be available. Default value: · Yes (enabled)

CONFIG_UNITY_ENABLE_64BIT
Support for 64-bit integer types
Found in: Component config > Unity unit testing library
If not set, assertions on 64-bit integer types will always fail. If this feature is enabled, take care not to pass pointers (which are 32 bit) to UNITY_ASSERT_EQUAL, as that will cause pointer-to-int-cast warnings.
Default value: · No (disabled)

CONFIG_UNITY_ENABLE_COLOR Colorize test output Found in: Component config > Unity unit testing library If set, Unity will colorize test results using console escape sequences. Default value: · No (disabled)

CONFIG_UNITY_ENABLE_IDF_TEST_RUNNER
Include ESP-IDF test registration/running helpers
Found in: Component config > Unity unit testing library
If set, then the following features will be available:
· TEST_CASE macro which performs automatic registration of test functions · Functions to run registered test functions: unity_run_all_tests, unity_run_tests_with_filter,
unity_run_single_test_by_name. · Interactive menu which lists test cases and allows choosing the tests to be run, available via
unity_run_menu function.
Disable if a different test registration mechanism is used.
Default value: · Yes (enabled)

CONFIG_UNITY_ENABLE_FIXTURE Include Unity test fixture Found in: Component config > Unity unit testing library If set, unity_fixture.h header file and associated source files are part of the build. These provide an optional set of macros and functions to implement test groups. Default value:

Espressif Systems

1593

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· No (disabled)
CONFIG_UNITY_ENABLE_BACKTRACE_ON_FAIL Print a backtrace when a unit test fails Found in: Component config > Unity unit testing library If set, the unity framework will print the backtrace information before jumping back to the test menu. The jumping is usually occurs in assert functions such as TEST_ASSERT, TEST_FAIL etc. Default value: · No (disabled)
USB-OTG Contains: · CONFIG_USB_HOST_HW_BUFFER_BIAS · CONFIG_USB_HOST_CONTROL_TRANSFER_MAX_SIZE
CONFIG_USB_HOST_CONTROL_TRANSFER_MAX_SIZE Largest size (in bytes) of transfers to/from default endpoints Found in: Component config > USB-OTG Each USB device attached is allocated a dedicated buffer for its OUT/IN transfers to/from the devicens control endpoint. The maximum size of that buffer is determined by this option. The limited size of the transfer buffer have the following implications: - The maximum length of control transfers is limited Devicens with configuration descriptors larger than this limit cannot be supported Default value: · 256
CONFIG_USB_HOST_HW_BUFFER_BIAS Hardware FIFO size biasing Found in: Component config > USB-OTG The underlying hardware has size adjustable FIFOs to cache USB packets on reception (IN) or for transmission (OUT). The size of these FIFOs will affect the largest MPS (maximum packet size) and the maximum number of packets that can be cached at any one time. The hardware contains the following FIFOS: RX (for all IN packets), Non-periodic TX (for Bulk and Control OUT packets), and Periodic TX (for Interrupt and Isochronous OUT packets). This configuration option allows biasing the FIFO sizes towards a particular use case, which may be necessary for devices that have endpoints with large MPS. The MPS limits for each biasing are listed below: Balanced: - IN (all transfer types), 408 bytes - OUT non-periodic (Bulk/Control), 192 bytes (i.e., 3 x 64 byte packets) - OUT periodic (Interrupt/Isochronous), 192 bytes Bias IN: - IN (all transfer types), 600 bytes - OUT non-periodic (Bulk/Control), 64 bytes (i.e., 1 x 64 byte packets) - OUT periodic (Interrupt/Isochronous), 128 bytes Bias Periodic OUT: - IN (all transfer types), 128 bytes - OUT non-periodic (Bulk/Control), 64 bytes (i.e., 1 x 64 byte packets) - OUT periodic (Interrupt/Isochronous), 600 bytes Available options: · Balanced (USB_HOST_HW_BUFFER_BIAS_BALANCED) · Bias IN (USB_HOST_HW_BUFFER_BIAS_IN) · Periodic OUT (USB_HOST_HW_BUFFER_BIAS_PERIODIC_OUT)

Espressif Systems

1594

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

Virtual file system Contains: · CONFIG_VFS_SUPPORT_IO

CONFIG_VFS_SUPPORT_IO Provide basic I/O functions Found in: Component config > Virtual file system If enabled, the following functions are provided by the VFS component. open, close, read, write, pread, pwrite, lseek, fstat, fsync, ioctl, fcntl Filesystem drivers can then be registered to handle these functions for specific paths. Disabling this option can save memory when the support for these functions is not required. Note that the following functions can still be used with socket file descriptors when this option is disabled: close, read, write, ioctl, fcntl. Default value: · Yes (enabled)

CONFIG_VFS_SUPPORT_DIR Provide directory related functions Found in: Component config > Virtual file system > CONFIG_VFS_SUPPORT_IO If enabled, the following functions are provided by the VFS component. stat, link, unlink, rename, utime, access, truncate, rmdir, mkdir, opendir, closedir, readdir, readdir_r, seekdir, telldir, rewinddir Filesystem drivers can then be registered to handle these functions for specific paths. Disabling this option can save memory when the support for these functions is not required. Default value: · Yes (enabled)

CONFIG_VFS_SUPPORT_SELECT

Provide select function

Found in: Component config > Virtual file system > CONFIG_VFS_SUPPORT_IO

If enabled, select function is provided by the VFS component, and can be used on peripheral file descriptors (such as UART) and sockets at the same time.

If disabled, the default select implementation will be provided by LWIP for sockets only.

Disabling this option can reduce code size if support for oselectpon UART file descriptors is not required.

Default value:

· Yes

(enabled)

if

CONFIG_VFS_SUPPORT_IO

&&

CON-

FIG_LWIP_USE_ONLY_LWIP_SELECT

Espressif Systems

1595

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_VFS_SUPPRESS_SELECT_DEBUG_OUTPUT Suppress select() related debug outputs Found in: Component config > Virtual file system > CONFIG_VFS_SUPPORT_IO > CONFIG_VFS_SUPPORT_SELECT Select() related functions might produce an unconveniently lot of debug outputs when one sets the default log level to DEBUG or higher. It is possible to suppress these debug outputs by enabling this option. Default value: · Yes (enabled)
CONFIG_VFS_SUPPORT_TERMIOS Provide termios.h functions Found in: Component config > Virtual file system > CONFIG_VFS_SUPPORT_IO Disabling this option can save memory when the support for termios.h is not required. Default value: · Yes (enabled)
Host File System I/O (Semihosting) Contains: · CONFIG_VFS_SEMIHOSTFS_MAX_MOUNT_POINTS · CONFIG_VFS_SEMIHOSTFS_HOST_PATH_MAX_LEN
CONFIG_VFS_SEMIHOSTFS_MAX_MOUNT_POINTS Host FS: Maximum number of the host filesystem mount points Found in: Component config > Virtual file system > CONFIG_VFS_SUPPORT_IO > Host File System I/O (Semihosting) Define maximum number of host filesystem mount points. Default value: ·1
CONFIG_VFS_SEMIHOSTFS_HOST_PATH_MAX_LEN Host FS: Maximum path length for the host base directory Found in: Component config > Virtual file system > CONFIG_VFS_SUPPORT_IO > Host File System I/O (Semihosting) Define maximum path length for the host base directory which is to be mounted. If host path passed to esp_vfs_semihost_register() is longer than this value it will be truncated. Default value: · 128
Wear Levelling Contains: · CONFIG_WL_SECTOR_MODE · CONFIG_WL_SECTOR_SIZE

Espressif Systems

1596

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
CONFIG_WL_SECTOR_SIZE Wear Levelling library sector size Found in: Component config > Wear Levelling Sector size used by wear levelling library. You can set default sector size or size that will fit to the flash device sector size. With sector size set to 4096 bytes, wear levelling library is more efficient. However if FAT filesystem is used on top of wear levelling library, it will need more temporary storage: 4096 bytes for each mounted filesystem and 4096 bytes for each opened file. With sector size set to 512 bytes, wear levelling library will perform more operations with flash memory, but less RAM will be used by FAT filesystem library (512 bytes for the filesystem and 512 bytes for each file opened). Available options: · 512 (WL_SECTOR_SIZE_512) · 4096 (WL_SECTOR_SIZE_4096)
CONFIG_WL_SECTOR_MODE Sector store mode Found in: Component config > Wear Levelling Specify the mode to store data into flash: · In Performance mode a data will be stored to the RAM and then stored back to the flash. Compared to the Safety mode, this operation is faster, but if power will be lost when erase sector operation is in progress, then the data from complete flash device sector will be lost. · In Safety mode data from complete flash device sector will be read from flash, modified, and then stored back to flash. Compared to the Performance mode, this operation is slower, but if power is lost during erase sector operation, then the data from full flash device sector will not be lost. Available options: · Perfomance (WL_SECTOR_MODE_PERF) · Safety (WL_SECTOR_MODE_SAFE)
Wi-Fi Provisioning Manager Contains: · CONFIG_WIFI_PROV_BLE_BONDING · CONFIG_WIFI_PROV_SCAN_MAX_ENTRIES · CONFIG_WIFI_PROV_AUTOSTOP_TIMEOUT
CONFIG_WIFI_PROV_SCAN_MAX_ENTRIES Max Wi-Fi Scan Result Entries Found in: Component config > Wi-Fi Provisioning Manager This sets the maximum number of entries of Wi-Fi scan results that will be kept by the provisioning manager Range: · from 1 to 255 Default value: · 16

Espressif Systems

1597

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_WIFI_PROV_AUTOSTOP_TIMEOUT
Provisioning auto-stop timeout
Found in: Component config > Wi-Fi Provisioning Manager
Time (in seconds) after which the Wi-Fi provisioning manager will auto-stop after connecting to a Wi-Fi network successfully.
Range: · from 5 to 600
Default value: · 30

CONFIG_WIFI_PROV_BLE_BONDING Enable BLE bonding Found in: Component config > Wi-Fi Provisioning Manager This option is applicable only when provisioning transport is BLE. Default value: · No (disabled) if CONFIG_BT_ENABLED

Supplicant Contains:
· CONFIG_WPA_TESTING_OPTIONS · CONFIG_WPA_11KV_SUPPORT · CONFIG_WPA_SUITE_B_192 · CONFIG_WPA_WAPI_PSK · CONFIG_WPA_DEBUG_PRINT · CONFIG_WPA_WPS_STRICT · CONFIG_WPA_MBEDTLS_CRYPTO

CONFIG_WPA_MBEDTLS_CRYPTO Use MbedTLS crypto APIs Found in: Component config > Supplicant Select this option to use MbedTLS crypto APIs which utilize hardware acceleration. Default value: · Yes (enabled)

CONFIG_WPA_WAPI_PSK
Enable WAPI PSK support
Found in: Component config > Supplicant
Select this option to enable WAPI-PSK which is a Chinese National Standard Encryption for Wireless LANs (GB 15629.11-2003).
Default value: · No (disabled)

CONFIG_WPA_SUITE_B_192 Enable NSA suite B support with 192 bit key Found in: Component config > Supplicant Select this option to enable 192 bit NSA suite-B. This is necessary to support WPA3 192 bit security.

Espressif Systems

1598

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
Default value: · No (disabled)
CONFIG_WPA_DEBUG_PRINT Print debug messages from WPA Supplicant Found in: Component config > Supplicant Select this option to print logging information from WPA supplicant, this includes handshake information and key hex dumps depending on the project logging level. Enabling this could increase the build size ~60kb depending on the project logging level. Default value: · No (disabled)
CONFIG_WPA_TESTING_OPTIONS Add DPP testing code Found in: Component config > Supplicant Select this to enable unity test for DPP. Default value: · No (disabled)
CONFIG_WPA_WPS_STRICT Strictly validate all WPS attributes Found in: Component config > Supplicant Select this option to enable validate each WPS attribute rigorously. Disabling this add the workaorunds with various APs. Enabling this may cause inter operability issues with some APs. Default value: · No (disabled)
CONFIG_WPA_11KV_SUPPORT Enable 802.11k, 802.11v APIs handling in supplicant Found in: Component config > Supplicant Select this option to enable 802.11k 802.11v APIs(RRM and BTM support). Only APIs which are helpful for network assisted roaming are supported for now. Enable this option with BTM and RRM enabled in sta config to make device ready for network assisted roaming. BTM: BSS transition management enables an AP to request a station to transition to a specific AP, or to indicate to a station a set of preferred APs. RRM: Radio measurements enable STAs to understand the radio environment, it enables STAs to observe and gather data on radio link performance and on the radio environment. Current implementation adds beacon report, link measurement, neighbor report. Default value: · No (disabled)
Contains: · CONFIG_WPA_MBO_SUPPORT · CONFIG_WPA_SCAN_CACHE

Espressif Systems

1599

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

CONFIG_WPA_SCAN_CACHE Keep scan results in cache Found in: Component config > Supplicant > CONFIG_WPA_11KV_SUPPORT Keep scan results in cache, if not enabled, those will be flushed immediately. Default value: · No (disabled) if CONFIG_WPA_11KV_SUPPORT

CONFIG_WPA_MBO_SUPPORT Enable MBO support in supplicant Found in: Component config > Supplicant > CONFIG_WPA_11KV_SUPPORT Select this option to enable WiFi Multiband operation certification support. Default value: · No (disabled) if CONFIG_WPA_11KV_SUPPORT

Deprecated options and their replacements
· CONFIG_A2D_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_A2D_TRACE_LEVEL) ­ CONFIG_A2D_TRACE_LEVEL_NONE ­ CONFIG_A2D_TRACE_LEVEL_ERROR ­ CONFIG_A2D_TRACE_LEVEL_WARNING ­ CONFIG_A2D_TRACE_LEVEL_API ­ CONFIG_A2D_TRACE_LEVEL_EVENT ­ CONFIG_A2D_TRACE_LEVEL_DEBUG ­ CONFIG_A2D_TRACE_LEVEL_VERBOSE
· CONFIG_ADC2_DISABLE_DAC (CONFIG_ADC_DISABLE_DAC) · CONFIG_APPL_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_APPL_TRACE_LEVEL)
­ CONFIG_APPL_TRACE_LEVEL_NONE ­ CONFIG_APPL_TRACE_LEVEL_ERROR ­ CONFIG_APPL_TRACE_LEVEL_WARNING ­ CONFIG_APPL_TRACE_LEVEL_API ­ CONFIG_APPL_TRACE_LEVEL_EVENT ­ CONFIG_APPL_TRACE_LEVEL_DEBUG ­ CONFIG_APPL_TRACE_LEVEL_VERBOSE · CONFIG_APP_ANTI_ROLLBACK (CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK) · CONFIG_APP_ROLLBACK_ENABLE (CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE) · CONFIG_APP_SECURE_VERSION (CONFIG_BOOTLOADER_APP_SECURE_VERSION) · CONFIG_APP_SECURE_VERSION_SIZE_EFUSE_FIELD (CONFIG_BOOTLOADER_APP_SEC_VER_SIZE_EFUSE_FIELD · CONFIG_AVCT_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_AVCT_TRACE_LEVEL) ­ CONFIG_AVCT_TRACE_LEVEL_NONE ­ CONFIG_AVCT_TRACE_LEVEL_ERROR ­ CONFIG_AVCT_TRACE_LEVEL_WARNING ­ CONFIG_AVCT_TRACE_LEVEL_API ­ CONFIG_AVCT_TRACE_LEVEL_EVENT ­ CONFIG_AVCT_TRACE_LEVEL_DEBUG ­ CONFIG_AVCT_TRACE_LEVEL_VERBOSE · CONFIG_AVDT_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_AVDT_TRACE_LEVEL) ­ CONFIG_AVDT_TRACE_LEVEL_NONE ­ CONFIG_AVDT_TRACE_LEVEL_ERROR ­ CONFIG_AVDT_TRACE_LEVEL_WARNING ­ CONFIG_AVDT_TRACE_LEVEL_API ­ CONFIG_AVDT_TRACE_LEVEL_EVENT ­ CONFIG_AVDT_TRACE_LEVEL_DEBUG ­ CONFIG_AVDT_TRACE_LEVEL_VERBOSE

Espressif Systems

1600

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· CONFIG_AVRC_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_AVRC_TRACE_LEVEL)

­ CONFIG_AVRC_TRACE_LEVEL_NONE

­ CONFIG_AVRC_TRACE_LEVEL_ERROR

­ CONFIG_AVRC_TRACE_LEVEL_WARNING

­ CONFIG_AVRC_TRACE_LEVEL_API

­ CONFIG_AVRC_TRACE_LEVEL_EVENT

­ CONFIG_AVRC_TRACE_LEVEL_DEBUG

­ CONFIG_AVRC_TRACE_LEVEL_VERBOSE

· CONFIG_BLE_ACTIVE_SCAN_REPORT_ADV_SCAN_RSP_INDIVIDUALLY

(CON-

FIG_BT_BLE_ACT_SCAN_REP_ADV_SCAN )

· CONFIG_BLE_ESTABLISH_LINK_CONNECTION_TIMEOUT

(CON-

FIG_BT_BLE_ESTAB_LINK_CONN_TOUT )

· CONFIG_BLE_HOST_QUEUE_CONGESTION_CHECK (CONFIG_BT_BLE_HOST_QUEUE_CONG_CHECK)

· CONFIG_BLE_MESH_GATT_PROXY (CONFIG_BLE_MESH_GATT_PROXY_SERVER)

· CONFIG_BLE_SMP_ENABLE (CONFIG_BT_BLE_SMP_ENABLE)

· CONFIG_BLUEDROID_MEM_DEBUG (CONFIG_BT_BLUEDROID_MEM_DEBUG)

· CONFIG_BLUEDROID_PINNED_TO_CORE_CHOICE (CONFIG_BT_BLUEDROID_PINNED_TO_CORE_CHOICE)

­ CONFIG_BLUEDROID_PINNED_TO_CORE_0 ­ CONFIG_BLUEDROID_PINNED_TO_CORE_1 · CONFIG_BLUFI_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_BLUFI_TRACE_LEVEL) ­ CONFIG_BLUFI_TRACE_LEVEL_NONE ­ CONFIG_BLUFI_TRACE_LEVEL_ERROR ­ CONFIG_BLUFI_TRACE_LEVEL_WARNING ­ CONFIG_BLUFI_TRACE_LEVEL_API ­ CONFIG_BLUFI_TRACE_LEVEL_EVENT ­ CONFIG_BLUFI_TRACE_LEVEL_DEBUG ­ CONFIG_BLUFI_TRACE_LEVEL_VERBOSE · CONFIG_BNEP_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_BNEP_TRACE_LEVEL) · CONFIG_BTC_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_BTC_TRACE_LEVEL) ­ CONFIG_BTC_TRACE_LEVEL_NONE ­ CONFIG_BTC_TRACE_LEVEL_ERROR ­ CONFIG_BTC_TRACE_LEVEL_WARNING ­ CONFIG_BTC_TRACE_LEVEL_API ­ CONFIG_BTC_TRACE_LEVEL_EVENT ­ CONFIG_BTC_TRACE_LEVEL_DEBUG ­ CONFIG_BTC_TRACE_LEVEL_VERBOSE · CONFIG_BTC_TASK_STACK_SIZE (CONFIG_BT_BTC_TASK_STACK_SIZE) · CONFIG_BTH_LOG_SDP_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_SDP_TRACE_LEVEL) ­ CONFIG_SDP_TRACE_LEVEL_NONE ­ CONFIG_SDP_TRACE_LEVEL_ERROR ­ CONFIG_SDP_TRACE_LEVEL_WARNING ­ CONFIG_SDP_TRACE_LEVEL_API ­ CONFIG_SDP_TRACE_LEVEL_EVENT ­ CONFIG_SDP_TRACE_LEVEL_DEBUG ­ CONFIG_SDP_TRACE_LEVEL_VERBOSE · CONFIG_BTIF_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_BTIF_TRACE_LEVEL) ­ CONFIG_BTIF_TRACE_LEVEL_NONE ­ CONFIG_BTIF_TRACE_LEVEL_ERROR ­ CONFIG_BTIF_TRACE_LEVEL_WARNING ­ CONFIG_BTIF_TRACE_LEVEL_API ­ CONFIG_BTIF_TRACE_LEVEL_EVENT ­ CONFIG_BTIF_TRACE_LEVEL_DEBUG ­ CONFIG_BTIF_TRACE_LEVEL_VERBOSE · CONFIG_BTM_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_BTM_TRACE_LEVEL) ­ CONFIG_BTM_TRACE_LEVEL_NONE ­ CONFIG_BTM_TRACE_LEVEL_ERROR ­ CONFIG_BTM_TRACE_LEVEL_WARNING

Espressif Systems

1601

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

­ CONFIG_BTM_TRACE_LEVEL_API

­ CONFIG_BTM_TRACE_LEVEL_EVENT

­ CONFIG_BTM_TRACE_LEVEL_DEBUG

­ CONFIG_BTM_TRACE_LEVEL_VERBOSE

· CONFIG_BTU_TASK_STACK_SIZE (CONFIG_BT_BTU_TASK_STACK_SIZE)

· CONFIG_CONSOLE_UART (CONFIG_ESP_CONSOLE_UART)

­ CONFIG_CONSOLE_UART_DEFAULT

­ CONFIG_CONSOLE_UART_CUSTOM

­ CONFIG_ESP_CONSOLE_UART_NONE

· CONFIG_CONSOLE_UART_BAUDRATE (CONFIG_ESP_CONSOLE_UART_BAUDRATE)

· CONFIG_CONSOLE_UART_NUM (CONFIG_ESP_CONSOLE_UART_NUM)

­ CONFIG_CONSOLE_UART_CUSTOM_NUM_0

­ CONFIG_CONSOLE_UART_CUSTOM_NUM_1

· CONFIG_CONSOLE_UART_RX_GPIO (CONFIG_ESP_CONSOLE_UART_RX_GPIO)

· CONFIG_CONSOLE_UART_TX_GPIO (CONFIG_ESP_CONSOLE_UART_TX_GPIO)

· CONFIG_CXX_EXCEPTIONS (CONFIG_COMPILER_CXX_EXCEPTIONS)

· CONFIG_CXX_EXCEPTIONS_EMG_POOL_SIZE (CONFIG_COMPILER_CXX_EXCEPTIONS_EMG_POOL_SIZE)

· CONFIG_DISABLE_GCC8_WARNINGS (CONFIG_COMPILER_DISABLE_GCC8_WARNINGS)

· CONFIG_EFUSE_SECURE_VERSION_EMULATE (CONFIG_BOOTLOADER_EFUSE_SECURE_VERSION_EMULATE)

· CONFIG_ENABLE_STATIC_TASK_CLEAN_UP_HOOK (CONFIG_FREERTOS_ENABLE_STATIC_TASK_CLEAN_UP)

· CONFIG_ESP32C3_LIGHTSLEEP_GPIO_RESET_WORKAROUND

(CON-

FIG_ESP_SLEEP_GPIO_RESET_WORKAROUND)

· CONFIG_ESP32C3_MEMPROT_FEATURE (CONFIG_ESP_SYSTEM_MEMPROT_FEATURE)

· CONFIG_ESP32C3_MEMPROT_FEATURE_LOCK (CONFIG_ESP_SYSTEM_MEMPROT_FEATURE_LOCK)

· CONFIG_ESP32H2_MEMPROT_FEATURE (CONFIG_ESP_SYSTEM_MEMPROT_FEATURE)

· CONFIG_ESP32H2_MEMPROT_FEATURE_LOCK (CONFIG_ESP_SYSTEM_MEMPROT_FEATURE_LOCK)

· CONFIG_ESP32S2_ALLOW_RTC_FAST_MEM_AS_HEAP (CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEA

· CONFIG_ESP32S2_MEMPROT_FEATURE (CONFIG_ESP_SYSTEM_MEMPROT_FEATURE)

· CONFIG_ESP32S2_MEMPROT_FEATURE_LOCK (CONFIG_ESP_SYSTEM_MEMPROT_FEATURE_LOCK)

· CONFIG_ESP32S2_PANIC (CONFIG_ESP_SYSTEM_PANIC)

­ CONFIG_ESP32S2_PANIC_PRINT_HALT

­ CONFIG_ESP32S2_PANIC_PRINT_REBOOT

­ CONFIG_ESP32S2_PANIC_SILENT_REBOOT

­ CONFIG_ESP32S2_PANIC_GDBSTUB

· CONFIG_ESP32_ALLOW_RTC_FAST_MEM_AS_HEAP (CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP)

· CONFIG_ESP32_APPTRACE_DESTINATION (CONFIG_APPTRACE_DESTINATION)

­ CONFIG_ESP32_APPTRACE_DEST_TRAX

­ CONFIG_ESP32_APPTRACE_DEST_NONE

· CONFIG_ESP32_APPTRACE_ONPANIC_HOST_FLUSH_TMO

(CON-

FIG_APPTRACE_ONPANIC_HOST_FLUSH_TMO)

· CONFIG_ESP32_APPTRACE_PENDING_DATA_SIZE_MAX (CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX)

· CONFIG_ESP32_APPTRACE_POSTMORTEM_FLUSH_TRAX_THRESH

(CON-

FIG_APPTRACE_POSTMORTEM_FLUSH_THRESH )

· CONFIG_ESP32_CORE_DUMP_DECODE (CONFIG_ESP_COREDUMP_DECODE)

­ CONFIG_ESP32_CORE_DUMP_DECODE_INFO

­ CONFIG_ESP32_CORE_DUMP_DECODE_DISABLE

· CONFIG_ESP32_CORE_DUMP_MAX_TASKS_NUM (CONFIG_ESP_COREDUMP_MAX_TASKS_NUM)

· CONFIG_ESP32_CORE_DUMP_UART_DELAY (CONFIG_ESP_COREDUMP_UART_DELAY)

· CONFIG_ESP32_DEBUG_STUBS_ENABLE (CONFIG_ESP_DEBUG_STUBS_ENABLE)

· CONFIG_ESP32_GCOV_ENABLE (CONFIG_APPTRACE_GCOV_ENABLE)

· CONFIG_ESP32_PANIC (CONFIG_ESP_SYSTEM_PANIC)

­ CONFIG_ESP32S2_PANIC_PRINT_HALT

­ CONFIG_ESP32S2_PANIC_PRINT_REBOOT

­ CONFIG_ESP32S2_PANIC_SILENT_REBOOT

­ CONFIG_ESP32S2_PANIC_GDBSTUB

· CONFIG_ESP32_PHY_CALIBRATION_AND_DATA_STORAGE

(CON-

FIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE)

· CONFIG_ESP32_PHY_DEFAULT_INIT_IF_INVALID (CONFIG_ESP_PHY_DEFAULT_INIT_IF_INVALID)

Espressif Systems

1602

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· CONFIG_ESP32_PHY_INIT_DATA_ERROR (CONFIG_ESP_PHY_INIT_DATA_ERROR) · CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION (CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION) · CONFIG_ESP32_PHY_MAC_BB_PD (CONFIG_ESP_PHY_MAC_BB_PD) · CONFIG_ESP32_PHY_MAX_WIFI_TX_POWER (CONFIG_ESP_PHY_MAX_WIFI_TX_POWER) · CONFIG_ESP32_PTHREAD_STACK_MIN (CONFIG_PTHREAD_STACK_MIN) · CONFIG_ESP32_PTHREAD_TASK_CORE_DEFAULT (CONFIG_PTHREAD_TASK_CORE_DEFAULT)

­ CONFIG_ESP32_DEFAULT_PTHREAD_CORE_NO_AFFINITY

­ CONFIG_ESP32_DEFAULT_PTHREAD_CORE_0

­ CONFIG_ESP32_DEFAULT_PTHREAD_CORE_1

· CONFIG_ESP32_PTHREAD_TASK_NAME_DEFAULT (CONFIG_PTHREAD_TASK_NAME_DEFAULT)

· CONFIG_ESP32_PTHREAD_TASK_PRIO_DEFAULT (CONFIG_PTHREAD_TASK_PRIO_DEFAULT)

· CONFIG_ESP32_PTHREAD_TASK_STACK_SIZE_DEFAULT (CONFIG_PTHREAD_TASK_STACK_SIZE_DEFAULT)

· CONFIG_ESP32_REDUCE_PHY_TX_POWER (CONFIG_ESP_PHY_REDUCE_TX_POWER)

· CONFIG_ESP32_RTC_XTAL_BOOTSTRAP_CYCLES (CONFIG_ESP_SYSTEM_RTC_EXT_XTAL_BOOTSTRAP_CYCLES)

· CONFIG_ESP32_SUPPORT_MULTIPLE_PHY_INIT_DATA_BIN

(CON-

FIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN )

· CONFIG_ESP_GRATUITOUS_ARP (CONFIG_LWIP_ESP_GRATUITOUS_ARP)

· CONFIG_ESP_SYSTEM_PD_FLASH (CONFIG_ESP_SLEEP_POWER_DOWN_FLASH)

· CONFIG_ESP_SYSTEM_PM_POWER_DOWN_CPU (CONFIG_PM_POWER_DOWN_CPU_IN_LIGHT_SLEEP)

· CONFIG_EVENT_LOOP_PROFILING (CONFIG_ESP_EVENT_LOOP_PROFILING)

· CONFIG_FLASH_ENCRYPTION_ENABLED (CONFIG_SECURE_FLASH_ENC_ENABLED)

· CONFIG_FLASH_ENCRYPTION_UART_BOOTLOADER_ALLOW_CACHE

(CON-

FIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_CACHE)

· CONFIG_FLASH_ENCRYPTION_UART_BOOTLOADER_ALLOW_ENCRYPT

(CON-

FIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_ENC)

· CONFIG_GAP_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_GAP_TRACE_LEVEL)

­ CONFIG_GAP_TRACE_LEVEL_NONE

­ CONFIG_GAP_TRACE_LEVEL_ERROR

­ CONFIG_GAP_TRACE_LEVEL_WARNING

­ CONFIG_GAP_TRACE_LEVEL_API

­ CONFIG_GAP_TRACE_LEVEL_EVENT

­ CONFIG_GAP_TRACE_LEVEL_DEBUG

­ CONFIG_GAP_TRACE_LEVEL_VERBOSE

· CONFIG_GARP_TMR_INTERVAL (CONFIG_LWIP_GARP_TMR_INTERVAL)

· CONFIG_GATTC_CACHE_NVS_FLASH (CONFIG_BT_GATTC_CACHE_NVS_FLASH)

· CONFIG_GATTC_ENABLE (CONFIG_BT_GATTC_ENABLE)

· CONFIG_GATTS_ENABLE (CONFIG_BT_GATTS_ENABLE)

· CONFIG_GATTS_SEND_SERVICE_CHANGE_MODE (CONFIG_BT_GATTS_SEND_SERVICE_CHANGE_MODE)

­ CONFIG_GATTS_SEND_SERVICE_CHANGE_MANUAL ­ CONFIG_GATTS_SEND_SERVICE_CHANGE_AUTO · CONFIG_GATT_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_GATT_TRACE_LEVEL) ­ CONFIG_GATT_TRACE_LEVEL_NONE ­ CONFIG_GATT_TRACE_LEVEL_ERROR ­ CONFIG_GATT_TRACE_LEVEL_WARNING ­ CONFIG_GATT_TRACE_LEVEL_API ­ CONFIG_GATT_TRACE_LEVEL_EVENT ­ CONFIG_GATT_TRACE_LEVEL_DEBUG ­ CONFIG_GATT_TRACE_LEVEL_VERBOSE · CONFIG_GDBSTUB_MAX_TASKS (CONFIG_ESP_GDBSTUB_MAX_TASKS) · CONFIG_GDBSTUB_SUPPORT_TASKS (CONFIG_ESP_GDBSTUB_SUPPORT_TASKS) · CONFIG_HCI_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_HCI_TRACE_LEVEL) ­ CONFIG_HCI_TRACE_LEVEL_NONE ­ CONFIG_HCI_TRACE_LEVEL_ERROR ­ CONFIG_HCI_TRACE_LEVEL_WARNING ­ CONFIG_HCI_TRACE_LEVEL_API ­ CONFIG_HCI_TRACE_LEVEL_EVENT

Espressif Systems

1603

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

­ CONFIG_HCI_TRACE_LEVEL_DEBUG ­ CONFIG_HCI_TRACE_LEVEL_VERBOSE · CONFIG_HID_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_HID_TRACE_LEVEL) ­ CONFIG_HID_TRACE_LEVEL_NONE ­ CONFIG_HID_TRACE_LEVEL_ERROR ­ CONFIG_HID_TRACE_LEVEL_WARNING ­ CONFIG_HID_TRACE_LEVEL_API ­ CONFIG_HID_TRACE_LEVEL_EVENT ­ CONFIG_HID_TRACE_LEVEL_DEBUG ­ CONFIG_HID_TRACE_LEVEL_VERBOSE · CONFIG_INT_WDT (CONFIG_ESP_INT_WDT) · CONFIG_INT_WDT_CHECK_CPU1 (CONFIG_ESP_INT_WDT_CHECK_CPU1) · CONFIG_INT_WDT_TIMEOUT_MS (CONFIG_ESP_INT_WDT_TIMEOUT_MS) · CONFIG_IPC_TASK_STACK_SIZE (CONFIG_ESP_IPC_TASK_STACK_SIZE) · CONFIG_L2CAP_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_L2CAP_TRACE_LEVEL) ­ CONFIG_L2CAP_TRACE_LEVEL_NONE ­ CONFIG_L2CAP_TRACE_LEVEL_ERROR ­ CONFIG_L2CAP_TRACE_LEVEL_WARNING ­ CONFIG_L2CAP_TRACE_LEVEL_API ­ CONFIG_L2CAP_TRACE_LEVEL_EVENT ­ CONFIG_L2CAP_TRACE_LEVEL_DEBUG ­ CONFIG_L2CAP_TRACE_LEVEL_VERBOSE · CONFIG_L2_TO_L3_COPY (CONFIG_LWIP_L2_TO_L3_COPY) · CONFIG_LOG_BOOTLOADER_LEVEL (CONFIG_BOOTLOADER_LOG_LEVEL) ­ CONFIG_LOG_BOOTLOADER_LEVEL_NONE ­ CONFIG_LOG_BOOTLOADER_LEVEL_ERROR ­ CONFIG_LOG_BOOTLOADER_LEVEL_WARN ­ CONFIG_LOG_BOOTLOADER_LEVEL_INFO ­ CONFIG_LOG_BOOTLOADER_LEVEL_DEBUG ­ CONFIG_LOG_BOOTLOADER_LEVEL_VERBOSE · CONFIG_MAC_BB_PD (CONFIG_ESP_PHY_MAC_BB_PD) · CONFIG_MAIN_TASK_STACK_SIZE (CONFIG_ESP_MAIN_TASK_STACK_SIZE) · CONFIG_MB_CONTROLLER_NOTIFY_QUEUE_SIZE (CONFIG_FMB_CONTROLLER_NOTIFY_QUEUE_SIZE) · CONFIG_MB_CONTROLLER_NOTIFY_TIMEOUT (CONFIG_FMB_CONTROLLER_NOTIFY_TIMEOUT) · CONFIG_MB_CONTROLLER_SLAVE_ID (CONFIG_FMB_CONTROLLER_SLAVE_ID) · CONFIG_MB_CONTROLLER_SLAVE_ID_SUPPORT (CONFIG_FMB_CONTROLLER_SLAVE_ID_SUPPORT) · CONFIG_MB_CONTROLLER_STACK_SIZE (CONFIG_FMB_CONTROLLER_STACK_SIZE) · CONFIG_MB_EVENT_QUEUE_TIMEOUT (CONFIG_FMB_EVENT_QUEUE_TIMEOUT) · CONFIG_MB_MASTER_DELAY_MS_CONVERT (CONFIG_FMB_MASTER_DELAY_MS_CONVERT) · CONFIG_MB_MASTER_TIMEOUT_MS_RESPOND (CONFIG_FMB_MASTER_TIMEOUT_MS_RESPOND) · CONFIG_MB_QUEUE_LENGTH (CONFIG_FMB_QUEUE_LENGTH) · CONFIG_MB_SERIAL_BUF_SIZE (CONFIG_FMB_SERIAL_BUF_SIZE) · CONFIG_MB_SERIAL_TASK_PRIO (CONFIG_FMB_PORT_TASK_PRIO) · CONFIG_MB_SERIAL_TASK_STACK_SIZE (CONFIG_FMB_PORT_TASK_STACK_SIZE) · CONFIG_MB_TIMER_PORT_ENABLED (CONFIG_FMB_TIMER_PORT_ENABLED) · CONFIG_MCA_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_MCA_TRACE_LEVEL) ­ CONFIG_MCA_TRACE_LEVEL_NONE ­ CONFIG_MCA_TRACE_LEVEL_ERROR ­ CONFIG_MCA_TRACE_LEVEL_WARNING ­ CONFIG_MCA_TRACE_LEVEL_API ­ CONFIG_MCA_TRACE_LEVEL_EVENT ­ CONFIG_MCA_TRACE_LEVEL_DEBUG ­ CONFIG_MCA_TRACE_LEVEL_VERBOSE · CONFIG_NIMBLE_ACL_BUF_COUNT (CONFIG_BT_NIMBLE_ACL_BUF_COUNT) · CONFIG_NIMBLE_ACL_BUF_SIZE (CONFIG_BT_NIMBLE_ACL_BUF_SIZE) · CONFIG_NIMBLE_ATT_PREFERRED_MTU (CONFIG_BT_NIMBLE_ATT_PREFERRED_MTU) · CONFIG_NIMBLE_CRYPTO_STACK_MBEDTLS (CONFIG_BT_NIMBLE_CRYPTO_STACK_MBEDTLS) · CONFIG_NIMBLE_DEBUG (CONFIG_BT_NIMBLE_DEBUG)

Espressif Systems

1604

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· CONFIG_NIMBLE_GAP_DEVICE_NAME_MAX_LEN (CONFIG_BT_NIMBLE_GAP_DEVICE_NAME_MAX_LEN)

· CONFIG_NIMBLE_HCI_EVT_BUF_SIZE (CONFIG_BT_NIMBLE_HCI_EVT_BUF_SIZE)

· CONFIG_NIMBLE_HCI_EVT_HI_BUF_COUNT (CONFIG_BT_NIMBLE_HCI_EVT_HI_BUF_COUNT)

· CONFIG_NIMBLE_HCI_EVT_LO_BUF_COUNT (CONFIG_BT_NIMBLE_HCI_EVT_LO_BUF_COUNT)

· CONFIG_NIMBLE_HS_FLOW_CTRL (CONFIG_BT_NIMBLE_HS_FLOW_CTRL)

· CONFIG_NIMBLE_HS_FLOW_CTRL_ITVL (CONFIG_BT_NIMBLE_HS_FLOW_CTRL_ITVL)

· CONFIG_NIMBLE_HS_FLOW_CTRL_THRESH (CONFIG_BT_NIMBLE_HS_FLOW_CTRL_THRESH)

· CONFIG_NIMBLE_HS_FLOW_CTRL_TX_ON_DISCONNECT

(CON-

FIG_BT_NIMBLE_HS_FLOW_CTRL_TX_ON_DISCONNECT )

· CONFIG_NIMBLE_L2CAP_COC_MAX_NUM (CONFIG_BT_NIMBLE_L2CAP_COC_MAX_NUM)

· CONFIG_NIMBLE_MAX_BONDS (CONFIG_BT_NIMBLE_MAX_BONDS)

· CONFIG_NIMBLE_MAX_CCCDS (CONFIG_BT_NIMBLE_MAX_CCCDS)

· CONFIG_NIMBLE_MAX_CONNECTIONS (CONFIG_BT_NIMBLE_MAX_CONNECTIONS)

· CONFIG_NIMBLE_MEM_ALLOC_MODE (CONFIG_BT_NIMBLE_MEM_ALLOC_MODE)

­ CONFIG_NIMBLE_MEM_ALLOC_MODE_INTERNAL

­ CONFIG_NIMBLE_MEM_ALLOC_MODE_EXTERNAL

­ CONFIG_NIMBLE_MEM_ALLOC_MODE_DEFAULT

· CONFIG_NIMBLE_MESH (CONFIG_BT_NIMBLE_MESH)

· CONFIG_NIMBLE_MESH_DEVICE_NAME (CONFIG_BT_NIMBLE_MESH_DEVICE_NAME)

· CONFIG_NIMBLE_MESH_FRIEND (CONFIG_BT_NIMBLE_MESH_FRIEND)

· CONFIG_NIMBLE_MESH_GATT_PROXY (CONFIG_BT_NIMBLE_MESH_GATT_PROXY)

· CONFIG_NIMBLE_MESH_LOW_POWER (CONFIG_BT_NIMBLE_MESH_LOW_POWER)

· CONFIG_NIMBLE_MESH_PB_ADV (CONFIG_BT_NIMBLE_MESH_PB_ADV)

· CONFIG_NIMBLE_MESH_PB_GATT (CONFIG_BT_NIMBLE_MESH_PB_GATT)

· CONFIG_NIMBLE_MESH_PROV (CONFIG_BT_NIMBLE_MESH_PROV)

· CONFIG_NIMBLE_MESH_PROXY (CONFIG_BT_NIMBLE_MESH_PROXY)

· CONFIG_NIMBLE_MESH_RELAY (CONFIG_BT_NIMBLE_MESH_RELAY)

· CONFIG_NIMBLE_MSYS1_BLOCK_COUNT (CONFIG_BT_NIMBLE_MSYS1_BLOCK_COUNT)

· CONFIG_NIMBLE_NVS_PERSIST (CONFIG_BT_NIMBLE_NVS_PERSIST)

· CONFIG_NIMBLE_PINNED_TO_CORE_CHOICE (CONFIG_BT_NIMBLE_PINNED_TO_CORE_CHOICE)

­ CONFIG_NIMBLE_PINNED_TO_CORE_0 ­ CONFIG_NIMBLE_PINNED_TO_CORE_1 · CONFIG_NIMBLE_ROLE_BROADCASTER (CONFIG_BT_NIMBLE_ROLE_BROADCASTER) · CONFIG_NIMBLE_ROLE_CENTRAL (CONFIG_BT_NIMBLE_ROLE_CENTRAL) · CONFIG_NIMBLE_ROLE_OBSERVER (CONFIG_BT_NIMBLE_ROLE_OBSERVER) · CONFIG_NIMBLE_ROLE_PERIPHERAL (CONFIG_BT_NIMBLE_ROLE_PERIPHERAL) · CONFIG_NIMBLE_RPA_TIMEOUT (CONFIG_BT_NIMBLE_RPA_TIMEOUT) · CONFIG_NIMBLE_SM_LEGACY (CONFIG_BT_NIMBLE_SM_LEGACY) · CONFIG_NIMBLE_SM_SC (CONFIG_BT_NIMBLE_SM_SC) · CONFIG_NIMBLE_SM_SC_DEBUG_KEYS (CONFIG_BT_NIMBLE_SM_SC_DEBUG_KEYS) · CONFIG_NIMBLE_SVC_GAP_APPEARANCE (CONFIG_BT_NIMBLE_SVC_GAP_APPEARANCE) · CONFIG_NIMBLE_SVC_GAP_DEVICE_NAME (CONFIG_BT_NIMBLE_SVC_GAP_DEVICE_NAME) · CONFIG_NIMBLE_TASK_STACK_SIZE (CONFIG_BT_NIMBLE_TASK_STACK_SIZE) · CONFIG_OPTIMIZATION_ASSERTION_LEVEL (CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL)

­ CONFIG_OPTIMIZATION_ASSERTIONS_ENABLED ­ CONFIG_OPTIMIZATION_ASSERTIONS_SILENT ­ CONFIG_OPTIMIZATION_ASSERTIONS_DISABLED · CONFIG_OPTIMIZATION_COMPILER (CONFIG_COMPILER_OPTIMIZATION) ­ CONFIG_COMPILER_OPTIMIZATION_LEVEL_DEBUG ­ CONFIG_COMPILER_OPTIMIZATION_LEVEL_RELEASE · CONFIG_OSI_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_OSI_TRACE_LEVEL) ­ CONFIG_OSI_TRACE_LEVEL_NONE ­ CONFIG_OSI_TRACE_LEVEL_ERROR ­ CONFIG_OSI_TRACE_LEVEL_WARNING ­ CONFIG_OSI_TRACE_LEVEL_API ­ CONFIG_OSI_TRACE_LEVEL_EVENT

Espressif Systems

1605

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

­ CONFIG_OSI_TRACE_LEVEL_DEBUG ­ CONFIG_OSI_TRACE_LEVEL_VERBOSE · CONFIG_PAN_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_PAN_TRACE_LEVEL) ­ CONFIG_PAN_TRACE_LEVEL_NONE ­ CONFIG_PAN_TRACE_LEVEL_ERROR ­ CONFIG_PAN_TRACE_LEVEL_WARNING ­ CONFIG_PAN_TRACE_LEVEL_API ­ CONFIG_PAN_TRACE_LEVEL_EVENT ­ CONFIG_PAN_TRACE_LEVEL_DEBUG ­ CONFIG_PAN_TRACE_LEVEL_VERBOSE · CONFIG_POST_EVENTS_FROM_IRAM_ISR (CONFIG_ESP_EVENT_POST_FROM_IRAM_ISR) · CONFIG_POST_EVENTS_FROM_ISR (CONFIG_ESP_EVENT_POST_FROM_ISR) · CONFIG_PPP_CHAP_SUPPORT (CONFIG_LWIP_PPP_CHAP_SUPPORT) · CONFIG_PPP_DEBUG_ON (CONFIG_LWIP_PPP_DEBUG_ON) · CONFIG_PPP_MPPE_SUPPORT (CONFIG_LWIP_PPP_MPPE_SUPPORT) · CONFIG_PPP_MSCHAP_SUPPORT (CONFIG_LWIP_PPP_MSCHAP_SUPPORT) · CONFIG_PPP_NOTIFY_PHASE_SUPPORT (CONFIG_LWIP_PPP_NOTIFY_PHASE_SUPPORT) · CONFIG_PPP_PAP_SUPPORT (CONFIG_LWIP_PPP_PAP_SUPPORT) · CONFIG_PPP_SUPPORT (CONFIG_LWIP_PPP_SUPPORT) · CONFIG_REDUCE_PHY_TX_POWER (CONFIG_ESP_PHY_REDUCE_TX_POWER) · CONFIG_RFCOMM_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_RFCOMM_TRACE_LEVEL) ­ CONFIG_RFCOMM_TRACE_LEVEL_NONE ­ CONFIG_RFCOMM_TRACE_LEVEL_ERROR ­ CONFIG_RFCOMM_TRACE_LEVEL_WARNING ­ CONFIG_RFCOMM_TRACE_LEVEL_API ­ CONFIG_RFCOMM_TRACE_LEVEL_EVENT ­ CONFIG_RFCOMM_TRACE_LEVEL_DEBUG ­ CONFIG_RFCOMM_TRACE_LEVEL_VERBOSE · CONFIG_SEMIHOSTFS_HOST_PATH_MAX_LEN (CONFIG_VFS_SEMIHOSTFS_HOST_PATH_MAX_LEN) · CONFIG_SEMIHOSTFS_MAX_MOUNT_POINTS (CONFIG_VFS_SEMIHOSTFS_MAX_MOUNT_POINTS) · CONFIG_SMP_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_SMP_TRACE_LEVEL) ­ CONFIG_SMP_TRACE_LEVEL_NONE ­ CONFIG_SMP_TRACE_LEVEL_ERROR ­ CONFIG_SMP_TRACE_LEVEL_WARNING ­ CONFIG_SMP_TRACE_LEVEL_API ­ CONFIG_SMP_TRACE_LEVEL_EVENT ­ CONFIG_SMP_TRACE_LEVEL_DEBUG ­ CONFIG_SMP_TRACE_LEVEL_VERBOSE · CONFIG_SMP_SLAVE_CON_PARAMS_UPD_ENABLE (CONFIG_BT_SMP_SLAVE_CON_PARAMS_UPD_ENABLE) · CONFIG_SPI_FLASH_WRITING_DANGEROUS_REGIONS (CONFIG_SPI_FLASH_DANGEROUS_WRITE)
­ CONFIG_SPI_FLASH_WRITING_DANGEROUS_REGIONS_ABORTS ­ CONFIG_SPI_FLASH_WRITING_DANGEROUS_REGIONS_FAILS ­ CONFIG_SPI_FLASH_WRITING_DANGEROUS_REGIONS_ALLOWED · CONFIG_STACK_CHECK_MODE (CONFIG_COMPILER_STACK_CHECK_MODE) ­ CONFIG_STACK_CHECK_NONE ­ CONFIG_STACK_CHECK_NORM ­ CONFIG_STACK_CHECK_STRONG ­ CONFIG_STACK_CHECK_ALL · CONFIG_SUPPORT_TERMIOS (CONFIG_VFS_SUPPORT_TERMIOS) · CONFIG_SUPPRESS_SELECT_DEBUG_OUTPUT (CONFIG_VFS_SUPPRESS_SELECT_DEBUG_OUTPUT) · CONFIG_SW_COEXIST_ENABLE (CONFIG_ESP32_WIFI_SW_COEXIST_ENABLE) · CONFIG_SYSTEM_EVENT_QUEUE_SIZE (CONFIG_ESP_SYSTEM_EVENT_QUEUE_SIZE) · CONFIG_SYSTEM_EVENT_TASK_STACK_SIZE (CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE) · CONFIG_SYSVIEW_BUF_WAIT_TMO (CONFIG_APPTRACE_SV_BUF_WAIT_TMO) · CONFIG_SYSVIEW_ENABLE (CONFIG_APPTRACE_SV_ENABLE) · CONFIG_SYSVIEW_EVT_IDLE_ENABLE (CONFIG_APPTRACE_SV_EVT_IDLE_ENABLE) · CONFIG_SYSVIEW_EVT_ISR_ENTER_ENABLE (CONFIG_APPTRACE_SV_EVT_ISR_ENTER_ENABLE)

Espressif Systems

1606

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

· CONFIG_SYSVIEW_EVT_ISR_EXIT_ENABLE (CONFIG_APPTRACE_SV_EVT_ISR_EXIT_ENABLE) · CONFIG_SYSVIEW_EVT_ISR_TO_SCHEDULER_ENABLE (CONFIG_APPTRACE_SV_EVT_ISR_TO_SCHED_ENABLE) · CONFIG_SYSVIEW_EVT_OVERFLOW_ENABLE (CONFIG_APPTRACE_SV_EVT_OVERFLOW_ENABLE) · CONFIG_SYSVIEW_EVT_TASK_CREATE_ENABLE (CONFIG_APPTRACE_SV_EVT_TASK_CREATE_ENABLE) · CONFIG_SYSVIEW_EVT_TASK_START_EXEC_ENABLE (CONFIG_APPTRACE_SV_EVT_TASK_START_EXEC_ENABL · CONFIG_SYSVIEW_EVT_TASK_START_READY_ENABLE (CONFIG_APPTRACE_SV_EVT_TASK_START_READY_ENA · CONFIG_SYSVIEW_EVT_TASK_STOP_EXEC_ENABLE (CONFIG_APPTRACE_SV_EVT_TASK_STOP_EXEC_ENABLE) · CONFIG_SYSVIEW_EVT_TASK_STOP_READY_ENABLE (CONFIG_APPTRACE_SV_EVT_TASK_STOP_READY_ENABL · CONFIG_SYSVIEW_EVT_TASK_TERMINATE_ENABLE (CONFIG_APPTRACE_SV_EVT_TASK_TERMINATE_ENABLE) · CONFIG_SYSVIEW_EVT_TIMER_ENTER_ENABLE (CONFIG_APPTRACE_SV_EVT_TIMER_ENTER_ENABLE) · CONFIG_SYSVIEW_EVT_TIMER_EXIT_ENABLE (CONFIG_APPTRACE_SV_EVT_TIMER_EXIT_ENABLE) · CONFIG_SYSVIEW_MAX_TASKS (CONFIG_APPTRACE_SV_MAX_TASKS) · CONFIG_SYSVIEW_TS_SOURCE (CONFIG_APPTRACE_SV_TS_SOURCE)
­ CONFIG_SYSVIEW_TS_SOURCE_CCOUNT ­ CONFIG_SYSVIEW_TS_SOURCE_ESP_TIMER · CONFIG_TASK_WDT (CONFIG_ESP_TASK_WDT) · CONFIG_TASK_WDT_CHECK_IDLE_TASK_CPU0 (CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0) · CONFIG_TASK_WDT_CHECK_IDLE_TASK_CPU1 (CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1) · CONFIG_TASK_WDT_PANIC (CONFIG_ESP_TASK_WDT_PANIC) · CONFIG_TASK_WDT_TIMEOUT_S (CONFIG_ESP_TASK_WDT_TIMEOUT_S) · CONFIG_TCPIP_RECVMBOX_SIZE (CONFIG_LWIP_TCPIP_RECVMBOX_SIZE) · CONFIG_TCPIP_TASK_AFFINITY (CONFIG_LWIP_TCPIP_TASK_AFFINITY) ­ CONFIG_TCPIP_TASK_AFFINITY_NO_AFFINITY ­ CONFIG_TCPIP_TASK_AFFINITY_CPU0 ­ CONFIG_TCPIP_TASK_AFFINITY_CPU1 · CONFIG_TCPIP_TASK_STACK_SIZE (CONFIG_LWIP_TCPIP_TASK_STACK_SIZE) · CONFIG_TCP_MAXRTX (CONFIG_LWIP_TCP_MAXRTX) · CONFIG_TCP_MSL (CONFIG_LWIP_TCP_MSL) · CONFIG_TCP_MSS (CONFIG_LWIP_TCP_MSS) · CONFIG_TCP_OVERSIZE (CONFIG_LWIP_TCP_OVERSIZE) ­ CONFIG_TCP_OVERSIZE_MSS ­ CONFIG_TCP_OVERSIZE_QUARTER_MSS ­ CONFIG_TCP_OVERSIZE_DISABLE · CONFIG_TCP_QUEUE_OOSEQ (CONFIG_LWIP_TCP_QUEUE_OOSEQ) · CONFIG_TCP_RECVMBOX_SIZE (CONFIG_LWIP_TCP_RECVMBOX_SIZE) · CONFIG_TCP_SND_BUF_DEFAULT (CONFIG_LWIP_TCP_SND_BUF_DEFAULT) · CONFIG_TCP_SYNMAXRTX (CONFIG_LWIP_TCP_SYNMAXRTX) · CONFIG_TCP_WND_DEFAULT (CONFIG_LWIP_TCP_WND_DEFAULT) · CONFIG_TIMER_QUEUE_LENGTH (CONFIG_FREERTOS_TIMER_QUEUE_LENGTH) · CONFIG_TIMER_TASK_PRIORITY (CONFIG_FREERTOS_TIMER_TASK_PRIORITY) · CONFIG_TIMER_TASK_STACK_DEPTH (CONFIG_FREERTOS_TIMER_TASK_STACK_DEPTH) · CONFIG_TIMER_TASK_STACK_SIZE (CONFIG_ESP_TIMER_TASK_STACK_SIZE) · CONFIG_UDP_RECVMBOX_SIZE (CONFIG_LWIP_UDP_RECVMBOX_SIZE) · CONFIG_USB_CDC_ENABLED (CONFIG_TINYUSB_CDC_ENABLED) · CONFIG_USB_CDC_RX_BUFSIZE (CONFIG_TINYUSB_CDC_RX_BUFSIZE) · CONFIG_USB_CDC_TX_BUFSIZE (CONFIG_TINYUSB_CDC_TX_BUFSIZE) · CONFIG_USB_DEBUG_LEVEL (CONFIG_TINYUSB_DEBUG_LEVEL) · CONFIG_USB_DESC_BCDDEVICE (CONFIG_TINYUSB_DESC_BCD_DEVICE) · CONFIG_USB_DESC_CDC_STRING (CONFIG_TINYUSB_DESC_CDC_STRING) · CONFIG_USB_DESC_CUSTOM_PID (CONFIG_TINYUSB_DESC_CUSTOM_PID) · CONFIG_USB_DESC_CUSTOM_VID (CONFIG_TINYUSB_DESC_CUSTOM_VID) · CONFIG_USB_DESC_HID_STRING (CONFIG_TINYUSB_DESC_HID_STRING) · CONFIG_USB_DESC_MANUFACTURER_STRING (CONFIG_TINYUSB_DESC_MANUFACTURER_STRING) · CONFIG_USB_DESC_MSC_STRING (CONFIG_TINYUSB_DESC_MSC_STRING) · CONFIG_USB_DESC_PRODUCT_STRING (CONFIG_TINYUSB_DESC_PRODUCT_STRING) · CONFIG_USB_DESC_SERIAL_STRING (CONFIG_TINYUSB_DESC_SERIAL_STRING) · CONFIG_USB_DESC_USE_DEFAULT_PID (CONFIG_TINYUSB_DESC_USE_DEFAULT_PID) · CONFIG_USB_DESC_USE_ESPRESSIF_VID (CONFIG_TINYUSB_DESC_USE_ESPRESSIF_VID)

Espressif Systems

1607

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
· CONFIG_USB_DO_NOT_CREATE_TASK (CONFIG_TINYUSB_NO_DEFAULT_TASK) · CONFIG_USB_ENABLED (CONFIG_TINYUSB) · CONFIG_USB_MSC_BUFSIZE (CONFIG_TINYUSB_MSC_BUFSIZE) · CONFIG_USB_MSC_ENABLED (CONFIG_TINYUSB_MSC_ENABLED) · CONFIG_USB_TASK_PRIORITY (CONFIG_TINYUSB_TASK_PRIORITY) · CONFIG_WARN_WRITE_STRINGS (CONFIG_COMPILER_WARN_WRITE_STRINGS)
2.10 Error Codes Reference
This section lists various error code constants defined in ESP-IDF. For general information about error codes in ESP-IDF, see Error Handling. ESP_FAIL (-1): Generic esp_err_t code indicating failure ESP_OK (0): esp_err_t value indicating success (no error) ESP_ERR_NO_MEM (0x101): Out of memory ESP_ERR_INVALID_ARG (0x102): Invalid argument ESP_ERR_INVALID_STATE (0x103): Invalid state ESP_ERR_INVALID_SIZE (0x104): Invalid size ESP_ERR_NOT_FOUND (0x105): Requested resource not found ESP_ERR_NOT_SUPPORTED (0x106): Operation or feature not supported ESP_ERR_TIMEOUT (0x107): Operation timed out ESP_ERR_INVALID_RESPONSE (0x108): Received response was invalid ESP_ERR_INVALID_CRC (0x109): CRC or checksum was invalid ESP_ERR_INVALID_VERSION (0x10a): Version was invalid ESP_ERR_INVALID_MAC (0x10b): MAC address was invalid ESP_ERR_NOT_FINISHED (0x10c): There are items remained to retrieve ESP_ERR_NVS_BASE (0x1100): Starting number of error codes ESP_ERR_NVS_NOT_INITIALIZED (0x1101): The storage driver is not initialized ESP_ERR_NVS_NOT_FOUND (0x1102): Id namespace doesnnt exist yet and mode is NVS_READONLY ESP_ERR_NVS_TYPE_MISMATCH (0x1103): The type of set or get operation doesnnt match the type of value stored in NVS ESP_ERR_NVS_READ_ONLY (0x1104): Storage handle was opened as read only ESP_ERR_NVS_NOT_ENOUGH_SPACE (0x1105): There is not enough space in the underlying storage to save the value ESP_ERR_NVS_INVALID_NAME (0x1106): Namespace name doesnnt satisfy constraints ESP_ERR_NVS_INVALID_HANDLE (0x1107): Handle has been closed or is NULL ESP_ERR_NVS_REMOVE_FAILED (0x1108): The value wasnnt updated because flash write operation has failed. The value was written however, and update will be finished after re-initialization of nvs, provided that flash operation doesnnt fail again. ESP_ERR_NVS_KEY_TOO_LONG (0x1109): Key name is too long ESP_ERR_NVS_PAGE_FULL (0x110a): Internal error; never returned by nvs API functions ESP_ERR_NVS_INVALID_STATE (0x110b): NVS is in an inconsistent state due to a previous error. Call nvs_flash_init and nvs_open again, then retry.

Espressif Systems

1608

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_ERR_NVS_INVALID_LENGTH (0x110c): String or blob length is not sufficient to store data ESP_ERR_NVS_NO_FREE_PAGES (0x110d): NVS partition doesnnt contain any empty pages. This may happen if NVS partition was truncated. Erase the whole partition and call nvs_flash_init again. ESP_ERR_NVS_VALUE_TOO_LONG (0x110e): String or blob length is longer than supported by the implementation ESP_ERR_NVS_PART_NOT_FOUND (0x110f): Partition with specified name is not found in the partition table ESP_ERR_NVS_NEW_VERSION_FOUND (0x1110): NVS partition contains data in new format and cannot be recognized by this version of code ESP_ERR_NVS_XTS_ENCR_FAILED (0x1111): XTS encryption failed while writing NVS entry ESP_ERR_NVS_XTS_DECR_FAILED (0x1112): XTS decryption failed while reading NVS entry ESP_ERR_NVS_XTS_CFG_FAILED (0x1113): XTS configuration setting failed ESP_ERR_NVS_XTS_CFG_NOT_FOUND (0x1114): XTS configuration not found ESP_ERR_NVS_ENCR_NOT_SUPPORTED (0x1115): NVS encryption is not supported in this version ESP_ERR_NVS_KEYS_NOT_INITIALIZED (0x1116): NVS key partition is uninitialized ESP_ERR_NVS_CORRUPT_KEY_PART (0x1117): NVS key partition is corrupt ESP_ERR_NVS_CONTENT_DIFFERS (0x1118): Internal error; never returned by nvs API functions. NVS key is different in comparison ESP_ERR_NVS_WRONG_ENCRYPTION (0x1119): NVS partition is marked as encrypted with generic flash encryption. This is forbidden since the NVS encryption works differently. ESP_ERR_ULP_BASE (0x1200): Offset for ULP-related error codes ESP_ERR_ULP_SIZE_TOO_BIG (0x1201): Program doesnnt fit into RTC memory reserved for the ULP ESP_ERR_ULP_INVALID_LOAD_ADDR (0x1202): Load address is outside of RTC memory reserved for the ULP ESP_ERR_ULP_DUPLICATE_LABEL (0x1203): More than one label with the same number was defined ESP_ERR_ULP_UNDEFINED_LABEL (0x1204): Branch instructions references an undefined label ESP_ERR_ULP_BRANCH_OUT_OF_RANGE (0x1205): Branch target is out of range of B instruction (try replacing with BX) ESP_ERR_OTA_BASE (0x1500): Base error code for ota_ops api ESP_ERR_OTA_PARTITION_CONFLICT (0x1501): Error if request was to write or erase the current running partition ESP_ERR_OTA_SELECT_INFO_INVALID (0x1502): Error if OTA data partition contains invalid content ESP_ERR_OTA_VALIDATE_FAILED (0x1503): Error if OTA app image is invalid ESP_ERR_OTA_SMALL_SEC_VER (0x1504): Error if the firmware has a secure version less than the running firmware. ESP_ERR_OTA_ROLLBACK_FAILED (0x1505): Error if flash does not have valid firmware in passive partition and hence rollback is not possible ESP_ERR_OTA_ROLLBACK_INVALID_STATE (0x1506): Error if current active firmware is still marked in pending validation state (ESP_OTA_IMG_PENDING_VERIFY), essentially first boot of firmware image post upgrade and hence firmware upgrade is not possible ESP_ERR_EFUSE (0x1600): Base error code for efuse api. ESP_OK_EFUSE_CNT (0x1601): OK the required number of bits is set. ESP_ERR_EFUSE_CNT_IS_FULL (0x1602): Error field is full.

Espressif Systems

1609

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_ERR_EFUSE_REPEATED_PROG (0x1603): Error repeated programming of programmed bits is strictly forbidden. ESP_ERR_CODING (0x1604): Error while a encoding operation. ESP_ERR_NOT_ENOUGH_UNUSED_KEY_BLOCKS (0x1605): Error not enough unused key blocks available ESP_ERR_DAMAGED_READING (0x1606): Error. Burn or reset was done during a reading operation leads to damage read data. This error is internal to the efuse component and not returned by any public API. ESP_ERR_IMAGE_BASE (0x2000) ESP_ERR_IMAGE_FLASH_FAIL (0x2001) ESP_ERR_IMAGE_INVALID (0x2002) ESP_ERR_WIFI_BASE (0x3000): Starting number of WiFi error codes ESP_ERR_WIFI_NOT_INIT (0x3001): WiFi driver was not installed by esp_wifi_init ESP_ERR_WIFI_NOT_STARTED (0x3002): WiFi driver was not started by esp_wifi_start ESP_ERR_WIFI_NOT_STOPPED (0x3003): WiFi driver was not stopped by esp_wifi_stop ESP_ERR_WIFI_IF (0x3004): WiFi interface error ESP_ERR_WIFI_MODE (0x3005): WiFi mode error ESP_ERR_WIFI_STATE (0x3006): WiFi internal state error ESP_ERR_WIFI_CONN (0x3007): WiFi internal control block of station or soft-AP error ESP_ERR_WIFI_NVS (0x3008): WiFi internal NVS module error ESP_ERR_WIFI_MAC (0x3009): MAC address is invalid ESP_ERR_WIFI_SSID (0x300a): SSID is invalid ESP_ERR_WIFI_PASSWORD (0x300b): Password is invalid ESP_ERR_WIFI_TIMEOUT (0x300c): Timeout error ESP_ERR_WIFI_WAKE_FAIL (0x300d): WiFi is in sleep state(RF closed) and wakeup fail ESP_ERR_WIFI_WOULD_BLOCK (0x300e): The caller would block ESP_ERR_WIFI_NOT_CONNECT (0x300f): Station still in disconnect status ESP_ERR_WIFI_POST (0x3012): Failed to post the event to WiFi task ESP_ERR_WIFI_INIT_STATE (0x3013): Invalid WiFi state when init/deinit is called ESP_ERR_WIFI_STOP_STATE (0x3014): Returned when WiFi is stopping ESP_ERR_WIFI_NOT_ASSOC (0x3015): The WiFi connection is not associated ESP_ERR_WIFI_TX_DISALLOW (0x3016): The WiFi TX is disallowed ESP_ERR_WIFI_REGISTRAR (0x3033): WPS registrar is not supported ESP_ERR_WIFI_WPS_TYPE (0x3034): WPS type error ESP_ERR_WIFI_WPS_SM (0x3035): WPS state machine is not initialized ESP_ERR_ESPNOW_BASE (0x3064): ESPNOW error number base. ESP_ERR_ESPNOW_NOT_INIT (0x3065): ESPNOW is not initialized. ESP_ERR_ESPNOW_ARG (0x3066): Invalid argument ESP_ERR_ESPNOW_NO_MEM (0x3067): Out of memory ESP_ERR_ESPNOW_FULL (0x3068): ESPNOW peer list is full ESP_ERR_ESPNOW_NOT_FOUND (0x3069): ESPNOW peer is not found ESP_ERR_ESPNOW_INTERNAL (0x306a): Internal error

Espressif Systems

1610

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_ERR_ESPNOW_EXIST (0x306b): ESPNOW peer has existed ESP_ERR_ESPNOW_IF (0x306c): Interface error ESP_ERR_DPP_FAILURE (0x3097): Generic failure during DPP Operation ESP_ERR_DPP_TX_FAILURE (0x3098): DPP Frame Tx failed OR not Acked ESP_ERR_DPP_INVALID_ATTR (0x3099): Encountered invalid DPP Attribute ESP_ERR_MESH_BASE (0x4000): Starting number of MESH error codes ESP_ERR_MESH_WIFI_NOT_START (0x4001) ESP_ERR_MESH_NOT_INIT (0x4002) ESP_ERR_MESH_NOT_CONFIG (0x4003) ESP_ERR_MESH_NOT_START (0x4004) ESP_ERR_MESH_NOT_SUPPORT (0x4005) ESP_ERR_MESH_NOT_ALLOWED (0x4006) ESP_ERR_MESH_NO_MEMORY (0x4007) ESP_ERR_MESH_ARGUMENT (0x4008) ESP_ERR_MESH_EXCEED_MTU (0x4009) ESP_ERR_MESH_TIMEOUT (0x400a) ESP_ERR_MESH_DISCONNECTED (0x400b) ESP_ERR_MESH_QUEUE_FAIL (0x400c) ESP_ERR_MESH_QUEUE_FULL (0x400d) ESP_ERR_MESH_NO_PARENT_FOUND (0x400e) ESP_ERR_MESH_NO_ROUTE_FOUND (0x400f) ESP_ERR_MESH_OPTION_NULL (0x4010) ESP_ERR_MESH_OPTION_UNKNOWN (0x4011) ESP_ERR_MESH_XON_NO_WINDOW (0x4012) ESP_ERR_MESH_INTERFACE (0x4013) ESP_ERR_MESH_DISCARD_DUPLICATE (0x4014) ESP_ERR_MESH_DISCARD (0x4015) ESP_ERR_MESH_VOTING (0x4016) ESP_ERR_MESH_XMIT (0x4017) ESP_ERR_MESH_QUEUE_READ (0x4018) ESP_ERR_MESH_PS (0x4019) ESP_ERR_MESH_RECV_RELEASE (0x401a) ESP_ERR_ESP_NETIF_BASE (0x5000) ESP_ERR_ESP_NETIF_INVALID_PARAMS (0x5001) ESP_ERR_ESP_NETIF_IF_NOT_READY (0x5002) ESP_ERR_ESP_NETIF_DHCPC_START_FAILED (0x5003) ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED (0x5004) ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED (0x5005) ESP_ERR_ESP_NETIF_NO_MEM (0x5006)

Espressif Systems

1611

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference

ESP_ERR_ESP_NETIF_DHCP_NOT_STOPPED (0x5007) ESP_ERR_ESP_NETIF_DRIVER_ATTACH_FAILED (0x5008) ESP_ERR_ESP_NETIF_INIT_FAILED (0x5009) ESP_ERR_ESP_NETIF_DNS_NOT_CONFIGURED (0x500a) ESP_ERR_ESP_NETIF_MLD6_FAILED (0x500b) ESP_ERR_ESP_NETIF_IP6_ADDR_FAILED (0x500c) ESP_ERR_FLASH_BASE (0x6000): Starting number of flash error codes ESP_ERR_FLASH_OP_FAIL (0x6001) ESP_ERR_FLASH_OP_TIMEOUT (0x6002) ESP_ERR_FLASH_NOT_INITIALISED (0x6003) ESP_ERR_FLASH_UNSUPPORTED_HOST (0x6004) ESP_ERR_FLASH_UNSUPPORTED_CHIP (0x6005) ESP_ERR_FLASH_PROTECTED (0x6006) ESP_ERR_HTTP_BASE (0x7000): Starting number of HTTP error codes ESP_ERR_HTTP_MAX_REDIRECT (0x7001): The error exceeds the number of HTTP redirects ESP_ERR_HTTP_CONNECT (0x7002): Error open the HTTP connection ESP_ERR_HTTP_WRITE_DATA (0x7003): Error write HTTP data ESP_ERR_HTTP_FETCH_HEADER (0x7004): Error read HTTP header from server ESP_ERR_HTTP_INVALID_TRANSPORT (0x7005): There are no transport support for the input scheme ESP_ERR_HTTP_CONNECTING (0x7006): HTTP connection hasnnt been established yet ESP_ERR_HTTP_EAGAIN (0x7007): Mapping of errno EAGAIN to esp_err_t ESP_ERR_HTTP_CONNECTION_CLOSED (0x7008): Read FIN from peer and the connection closed ESP_ERR_ESP_TLS_BASE (0x8000): Starting number of ESP-TLS error codes ESP_ERR_ESP_TLS_CANNOT_RESOLVE_HOSTNAME (0x8001): Error if hostname couldnnt be resolved upon tls connection ESP_ERR_ESP_TLS_CANNOT_CREATE_SOCKET (0x8002): Failed to create socket ESP_ERR_ESP_TLS_UNSUPPORTED_PROTOCOL_FAMILY (0x8003): Unsupported protocol family ESP_ERR_ESP_TLS_FAILED_CONNECT_TO_HOST (0x8004): Failed to connect to host ESP_ERR_ESP_TLS_SOCKET_SETOPT_FAILED (0x8005): failed to set/get socket option ESP_ERR_ESP_TLS_CONNECTION_TIMEOUT (0x8006): new connection in esp_tls_low_level_conn connection timeouted ESP_ERR_ESP_TLS_SE_FAILED (0x8007) ESP_ERR_ESP_TLS_TCP_CLOSED_FIN (0x8008) ESP_ERR_MBEDTLS_CERT_PARTLY_OK (0x8010): mbedtls parse certificates was partly successful ESP_ERR_MBEDTLS_CTR_DRBG_SEED_FAILED (0x8011): mbedtls api returned error ESP_ERR_MBEDTLS_SSL_SET_HOSTNAME_FAILED (0x8012): mbedtls api returned error ESP_ERR_MBEDTLS_SSL_CONFIG_DEFAULTS_FAILED (0x8013): mbedtls api returned error ESP_ERR_MBEDTLS_SSL_CONF_ALPN_PROTOCOLS_FAILED (0x8014): mbedtls api returned error ESP_ERR_MBEDTLS_X509_CRT_PARSE_FAILED (0x8015): mbedtls api returned error ESP_ERR_MBEDTLS_SSL_CONF_OWN_CERT_FAILED (0x8016): mbedtls api returned error

Espressif Systems

1612

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_ERR_MBEDTLS_SSL_SETUP_FAILED (0x8017): mbedtls api returned error ESP_ERR_MBEDTLS_SSL_WRITE_FAILED (0x8018): mbedtls api returned error ESP_ERR_MBEDTLS_PK_PARSE_KEY_FAILED (0x8019): mbedtls api returned failed ESP_ERR_MBEDTLS_SSL_HANDSHAKE_FAILED (0x801a): mbedtls api returned failed ESP_ERR_MBEDTLS_SSL_CONF_PSK_FAILED (0x801b): mbedtls api returned failed ESP_ERR_MBEDTLS_SSL_TICKET_SETUP_FAILED (0x801c): mbedtls api returned failed ESP_ERR_WOLFSSL_SSL_SET_HOSTNAME_FAILED (0x8031): wolfSSL api returned error ESP_ERR_WOLFSSL_SSL_CONF_ALPN_PROTOCOLS_FAILED (0x8032): wolfSSL api returned error ESP_ERR_WOLFSSL_CERT_VERIFY_SETUP_FAILED (0x8033): wolfSSL api returned error ESP_ERR_WOLFSSL_KEY_VERIFY_SETUP_FAILED (0x8034): wolfSSL api returned error ESP_ERR_WOLFSSL_SSL_HANDSHAKE_FAILED (0x8035): wolfSSL api returned failed ESP_ERR_WOLFSSL_CTX_SETUP_FAILED (0x8036): wolfSSL api returned failed ESP_ERR_WOLFSSL_SSL_SETUP_FAILED (0x8037): wolfSSL api returned failed ESP_ERR_WOLFSSL_SSL_WRITE_FAILED (0x8038): wolfSSL api returned failed ESP_ERR_HTTPS_OTA_BASE (0x9000) ESP_ERR_HTTPS_OTA_IN_PROGRESS (0x9001) ESP_ERR_PING_BASE (0xa000) ESP_ERR_PING_INVALID_PARAMS (0xa001) ESP_ERR_PING_NO_MEM (0xa002) ESP_ERR_HTTPD_BASE (0xb000): Starting number of HTTPD error codes ESP_ERR_HTTPD_HANDLERS_FULL (0xb001): All slots for registering URI handlers have been consumed ESP_ERR_HTTPD_HANDLER_EXISTS (0xb002): URI handler with same method and target URI already registered ESP_ERR_HTTPD_INVALID_REQ (0xb003): Invalid request pointer ESP_ERR_HTTPD_RESULT_TRUNC (0xb004): Result string truncated ESP_ERR_HTTPD_RESP_HDR (0xb005): Response header field larger than supported ESP_ERR_HTTPD_RESP_SEND (0xb006): Error occured while sending response packet ESP_ERR_HTTPD_ALLOC_MEM (0xb007): Failed to dynamically allocate memory for resource ESP_ERR_HTTPD_TASK (0xb008): Failed to launch server task/thread ESP_ERR_HW_CRYPTO_BASE (0xc000): Starting number of HW cryptography module error codes ESP_ERR_HW_CRYPTO_DS_HMAC_FAIL (0xc001): HMAC peripheral problem ESP_ERR_HW_CRYPTO_DS_INVALID_KEY (0xc002) ESP_ERR_HW_CRYPTO_DS_INVALID_DIGEST (0xc004) ESP_ERR_HW_CRYPTO_DS_INVALID_PADDING (0xc005) ESP_ERR_MEMPROT_BASE (0xd000): Starting number of Memory Protection API error codes ESP_ERR_MEMPROT_MEMORY_TYPE_INVALID (0xd001) ESP_ERR_MEMPROT_SPLIT_ADDR_INVALID (0xd002) ESP_ERR_MEMPROT_SPLIT_ADDR_OUT_OF_RANGE (0xd003) ESP_ERR_MEMPROT_SPLIT_ADDR_UNALIGNED (0xd004)

Espressif Systems

1613

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 2. API Reference
ESP_ERR_MEMPROT_UNIMGMT_BLOCK_INVALID (0xd005) ESP_ERR_MEMPROT_WORLD_INVALID (0xd006) ESP_ERR_MEMPROT_AREA_INVALID (0xd007)

Espressif Systems

1614

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 3
ESP32-S3 Hardware Reference

3.1 Chip Series Comparison

The comparison below covers key features of chips supported by ESP-IDF. For the full list of features please refer to respective datasheets in Section Related Documents.

Feature ESP32 Series

Launch 2016

year

Variants See ESP32 Datasheet

(PDF)

Core

Xtensa® dual-/single

core 32-bit LX6

Wi-Fi

802.11 b/g/n, 2.4 GHz

protocols

Bluetooth® Bluetooth

v4.2

BR/EDR and Blue-

tooth Low Energy

Typical 240 MHz (160 MHz

fre-

for ESP32-S0WD)

quency

SRAM 520 KB

ROM

448 KB for booting

and core functions

Embedded 2 MB, 4 MB, or none,

flash

depending on variants

External Up to 16 MB device,

flash

address 11 MB + 248

KB each time

External Up to 8 MB device,

RAM

address 4 MB each

time

Cache

 Two-way set asso-

ciative

Table 1: Chip Series Comparison

ESP32-S2 Series 2020

ESP32-C3 Series 2020

ESP32-S3 Series 2020

See

ESP32-S2

Datasheet (PDF)

Xtensa® single-core

32-bit LX7

802.11 b/g/n, 2.4 GHz

See

ESP32-C3

Datasheet (PDF)

32-bit single-core

RISC-V

802.11 b/g/n, 2.4 GHz

See

ESP32-S3

Datasheet (PDF)

Xtensa® dual-core

32-bit LX7

802.11 b/g/n, 2.4 GHz



Bluetooth 5.0

Bluetooth 5.0

240 MHz

160 MHz

240 MHz

320 KB 128 KB for booting and core functions 2 MB, 4 MB, or none, depending on variants Up to 1 GB device, address 11.5 MB each time Up to 1 GB device, address 11.5 MB each time   Four-way set associative, independent instruction cache and data cache

400 KB 384 KB for booting and core functions 4 MB or none, depending on variants Up to 16 MB device, address 8 MB each time 

512 KB 384 KB for booting and core functions 8 MB or none, depending on variants Up to 1 GB device, address 32 MB each time
Up to 1 GB device, address 32 MB each time

  Eight-way set  Four-way or eight-

associative, 32-bit way set associative

data/instruction bus for instruction cache;

width

four-way set associa-

tive for data cache,

32-bit data/instruction

bus width

Continued on next page

1615

Chapter 3. ESP32-S3 Hardware Reference

Table 1 ­ continued from previous page

Feature ESP32 Series

ESP32-S2 Series ESP32-C3 Series ESP32-S3 Series

Peripherals

ADC

Two 12-bit, 18 chan- Two 12-bit, 20 chan- Two 12-bit SAR Two 12-bit SAR

nels

nels

ADCs, at most 6 ADCs, 20 channels

channels

DAC

Two 8-bit channels

Two 8-bit channels





Timers Four 64-bit general- Four 64-bit general- Two 54-bit general- Four 54-bit general-

purpose timers, and purpose timers, and purpose timers, and purpose timers, and

three watchdog timers three watchdog timers three watchdog timers three watchdog timers

Temperature 

1

1

1

sensor

Touch

10

14



14

sensor

Hall sen- 1







sor

GPIO

34

43

22

45

SPI

4

4

3

4

LCD in- 1

1



1

terface

UART 3

21

21

3

I2C

2

2

1

2

I2S

2, can be config- 1, can be config- 1, can be config- 2, can be config-

ured to operate with ured to operate with ured to operate with ured to operate with

8/16/32/40/48-bit

8/16/24/32/48/64-bit 8/16/24/32-bit reso- 8/16/24/32-bit reso-

resolution as an input resolution as an input lution as an input or lution as an input or

or output channel.

or output channel.

output channel.

output channel.

Camera 1

1



1

interface

DMA

Dedicated DMA Dedicated DMA to General-purpose, 3 General-purpose, 5

to UART, SPI, I2S, UART, SPI, AES, TX channels, 3 RX TX channels, 5 RX

SDIO slave, SD/MMC SHA, I2S, and ADC channels

channels

host, EMAC, BT, and Controller

Wi-Fi

RMT

8 channels

4 channels 1, can be 4 channels 2, 2 TX 8 channels 2, 4 TX

configured to TX/RX channels, 2 RX chan- channels, 4 RX chan-

channels

nels

nels

Pulse

8 channels

4 channels 1



4 channels 1

counter

LED

16 channels

8 channels 1

6 channels 2

8 channels 1

PWM

MCPWM 2, six PWM outputs  



2, six PWM outputs

USB



1



1

OTG

TWAI® 1

1

1

1

controller

(com-

patible

with ISO

11898-1)

SD/SDIO/MM1 C





1

host con-

troller

SDIO

1







slave

controller

Continued on next page

Espressif Systems

1616

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 3. ESP32-S3 Hardware Reference

Feature Ethernet MAC ULP
Debug Assist Security Secure boot Flash encryption
OTP AES
HASH
RSA RNG HMAC Digital signature XTS
Other Deepsleep (ULP sensormonitored pattern) Size

ESP32 Series 1
ULP FSM


Table 1 ­ continued from previous page

ESP32-S2 Series ESP32-C3 Series





PicoRV32 core with 8  

KB SRAM, ULP FSM



1



1024-bit   AES-128, AES192, AES-256 (FIPS PUB 197)
SHA-1, SHA-256, SHA-384, SHA-512 (FIPS PUB 180-4)
Up to 4096 bits   

  Faster and safer,

compared with ESP32

  Support for

PSRAM encryption.

Safer, compared with

ESP32

4096-bit

  AES-128, AES-

192, AES-256 (FIPS

PUB 197); DMA sup-

port

SHA-1, SHA-224,

SHA-256, SHA-

384,

SHA-512,

SHA-512/224, SHA-

512/256, SHA-512/t

(FIPS PUB 180-4);

DMA support

Up to 4096 bits







  Faster and safer, compared with ESP32   Safer, compared with ESP32
4096-bit   AES-128, AES256 (FIPS PUB 197); DMA support
SHA-1, SHA-224, SHA-256 (FIPS PUB 180-4); DMA support
Up to 3072 bits   



  XTS-AES-128,  XTS-AES-128

XTS-AES-256

100 A (when ADC 22 A (when touch No such pattern

work with a duty cycle sensors work with a

of 1%)

duty cycle of 1%)

QFN48 5*5, 6*6, de- QFN56 7*7 pending on variants

QFN32 5*5

ESP32-S3 Series 
PicoRV32 core with 8 KB SRAM, ULP FSM 

  Faster and safer, compared with ESP32   Support for PSRAM encryption. Safer, compared with ESP32 4096-bit   AES-128, AES256 (FIPS PUB 197); DMA support

SHA-1, SHA-224,

SHA-256, SHA-

384,

SHA-512,

SHA-512/224, SHA-

512/256, SHA-512/t

(FIPS PUB 180-4);

DMA support

Up to 4096 bits







  XTS-AES-128, XTS-AES-256

TBD

QFN56 7*7

· Note 1: Reduced chip area compared with ESP32 · Note 2: Reduced chip area compared with ESP32 and ESP32-S2 · Note 3: Die size: ESP32-C3 < ESP32-S2 < ESP32-S3 < ESP32

3.1.1 Related Documents
· ESP32 Datasheet (PDF) · ESP32-PICO Datasheets (PDF)
­ ESP32-PICO-D4 ­ ESP32-PICO-V3 ­ ESP32-PICO-V3-02 · ESP32-S2 Datasheet (PDF) · ESP32-C3 Datasheet (PDF)

Espressif Systems

1617

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 3. ESP32-S3 Hardware Reference
· ESP32-S3 Datasheet (PDF) · ESP Product Selector

Espressif Systems

1618

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4
API Guides
4.1 Application Level Tracing library
4.1.1 Overview
IDF provides a useful feature for program behavior analysis called Application Level Tracing. The feature can be enabled in menuconfig and allows transfer of arbitrary data between the host and ESP32-S3 via JTAG interface with minimal overhead on program execution. Developers can use this library to send application specific state of execution to the host and receive commands or other type of info in the opposite direction at runtime. The main use cases of this library are:
1. Collecting application specific data, see Application Specific Tracing 2. Lightweight logging to the host, see Logging to Host 3. System behavior analysis, see System Behavior Analysis with SEGGER SystemView 4. Source code coverage, see Gcov (Source Code Coverage) Tracing components when working over JTAG interface are shown in the figure below.
4.1.2 Modes of Operation
The library supports two modes of operation: Post-mortem mode. This is the default mode. The mode does not need interaction with the host side. In this mode, the tracing module does not check whether host has read all the data from the HW UP BUFFER and overwrites it with new data. This mode is useful when only the latest trace data is interesting to the user, e.g. for analyzing the programns behavior just before a crash. Host can read the data later upon user request, e.g. via a special OpenOCD command in case of working via JTAG interface. Streaming mode. Tracing module enters this mode when host connects to ESP32-S3. In this mode, before writing new data to HW UP BUFFER, the tracing module checks that there is enough space in it and if necessary waits for the host to read data and free enough memory. Maximum waiting time is controlled via timeout values passed by users to corresponding API routines. When an application tries to write data to the trace buffer with a finite wait time, it is possible that the data will be dropped. This is especially true when tracing from time critical code (ISRs, OS scheduler code etc.) where infinite timeouts can lead to a system malfunction. In order to avoid loss of such critical data, developers can enable additional data buffering via menuconfig option CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX. This macro specifies the size of data which can be buffered in such scenarios. This option can also help to overcome a situation when data transfer to the host is temporarily slowed down, e.g. due to USB bus congestions, etc. But it will not help when the average bitrate of the trace data stream exceeds the HW interface capabilities.
1619

Chapter 4. API Guides

Fig. 1: Tracing Components when Working Over JTAG

4.1.3 Configuration Options and Dependencies
Using of this feature depends on two components:
1. Host side: Application tracing is done over JTAG, so it needs OpenOCD to be set up and running on host machine. For instructions on how to set it up, please see JTAG Debugging for details.
2. Target side: Application tracing functionality can be enabled in menuconfig. Component config > Application Level Tracing menu allows selecting destination for the trace data (HW interface for transport). Choosing any of the destinations automatically enables CONFIG_APPTRACE_ENABLE option.
Note: In order to achieve higher data rates and minimize the number of dropped packets, it is recommended to optimize the setting of the JTAG clock frequency, so it is at maximum and still provides stable operation of JTAG, see Optimize JTAG speed.
There are two additional menuconfig options that are available to users:
1. Threshold for flushing last trace data to host on panic (CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH). This option is useful when working over JTAG wherein the trace data is exposed to the host in 16 KB blocks. In post-mortem mode, when one block is filled it is exposed to the host and the previous one becomes unavailable. In other words, the trace data is overwritten in 16 KB granularity. On panic, the latest data from the current input block is exposed to the host and the host can read it for post-analysis. System panic may occur when a very small amount of data has been accumulated but not yet exposed to the host. In this case the previous 16 KB of collected data will be lost and the host will see the latest, very small piece of the trace. This data may be insufficient to diagnose the problem. Thus, this menuconfig option allows avoiding such situations. It controls the threshold for flushing data in case of a panic. For example, users can decide that they need no less than 512 bytes of the recent trace data for meaningful analysis. If there is less than 512 bytes of pending data at the moment of panic, it will not be flushed and will not overwrite the previous 16 KB. The option is only meaningful in post-mortem mode and when working over JTAG.
2. Timeout for flushing last trace data to host on panic (CONFIG_APPTRACE_ONPANIC_HOST_FLUSH_TMO). The option is only meaningful in streaming mode and controls the maximum time tracing module will wait for the host to read the last data in case of panic.

Espressif Systems

1620

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

4.1.4 How to use this library
This library provides APIs for transferring arbitrary data between the host and ESP32-S3. When enabled in menuconfig, target application tracing module is initialized automatically at the system startup. All that the user needs to do is to call corresponding APIs to send, receive or flush the data.

Application Specific Tracing
In general the user should decide what type of data should be transferred in either direction and how this data must be interpreted (processed). The following steps must be performed to transfer data between ESP32-S3 and the host:
1. On target side user should implement algorithms for writing trace data to the host. The following piece of code demonstrates an example of how to do this.
#include "esp_app_trace.h" ... char buf[] = "Hello World!"; esp_err_t res = esp_apptrace_write(ESP_APPTRACE_DEST_TRAX, buf, strlen(buf), ESP_APPTRACE_TMO_INFINITE); if (res != ESP_OK) {
ESP_LOGE(TAG, "Failed to write data to host!"); return res; }
esp_apptrace_write() function uses memcpy to copy user data to the internal buffer. In some cases it can be more optimal to use esp_apptrace_buffer_get() and esp_apptrace_buffer_put() functions. They allow developers to allocate buffer and fill it themselves. The following piece of code shows how to do this.
#include "esp_app_trace.h" ... int number = 10; char *ptr = (char *)esp_apptrace_buffer_get(ESP_APPTRACE_DEST_TRAX, 32, 100/ *tmo in us*/); if (ptr == NULL) {
ESP_LOGE(TAG, "Failed to get buffer!"); return ESP_FAIL; } sprintf(ptr, "Here is the number %d", number); esp_err_t res = esp_apptrace_buffer_put(ESP_APPTRACE_DEST_TRAX, ptr, 100/*tmo in us*/); if (res != ESP_OK) { /* in case of error host tracing tool (e.g. OpenOCD) will report incomplete user buffer */ ESP_LOGE(TAG, "Failed to put buffer!"); return res; }
The user may also want to receive data from the host. The following piece of code shows an example of how to do this.
#include "esp_app_trace.h" ... char buf[32]; char down_buf[32]; size_t sz = sizeof(buf);
/* config down buffer */ esp_apptrace_down_buffer_config(down_buf, sizeof(down_buf)); /* check for incoming data and read them if any */ esp_err_t res = esp_apptrace_read(ESP_APPTRACE_DEST_TRAX, buf, &sz, 0/*do not wait*/);
(continues on next page)

Espressif Systems

1621

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

if (res != ESP_OK) { ESP_LOGE(TAG, "Failed to read data from host!"); return res;
} if (sz > 0) {
/* we have data, process them */ ... }

(continued from previous page)

esp_apptrace_read() function uses memcpy to copy host data to user buffer. In some cases it can be more optimal to use esp_apptrace_down_buffer_get() and esp_apptrace_down_buffer_put() functions. They allow developers to occupy chunk of read buffer and process it in-place. The following piece of code shows how to do this.

#include "esp_app_trace.h" ... char down_buf[32]; uint32_t *number; size_t sz = 32;

/* config down buffer */ esp_apptrace_down_buffer_config(down_buf, sizeof(down_buf)); char *ptr = (char *)esp_apptrace_down_buffer_get(ESP_APPTRACE_DEST_TRAX, &sz, 100/*tmo in us*/); if (ptr == NULL) {
ESP_LOGE(TAG, "Failed to get buffer!"); return ESP_FAIL; } if (sz > 4) { number = (uint32_t *)ptr; printf("Here is the number %d", *number); } else { printf("No data"); } esp_err_t res = esp_apptrace_down_buffer_put(ESP_APPTRACE_DEST_TRAX, ptr, 100/ *tmo in us*/); if (res != ESP_OK) { /* in case of error host tracing tool (e.g. OpenOCD) will report incomplete user buffer */ ESP_LOGE(TAG, "Failed to put buffer!"); return res; }
2. The next step is to build the program image and download it to the target as described in the Getting Started Guide.
3. Run OpenOCD (see JTAG Debugging). 4. Connect to OpenOCD telnet server. It can be done using the following command in terminal telnet
<oocd_host> 4444. If telnet session is opened on the same machine which runs OpenOCD you can use localhost as <oocd_host> in the command above. 5. Start trace data collection using special OpenOCD command. This command will transfer tracing data and redirect them to specified file or socket (currently only files are supported as trace data destination). For description of the corresponding commands see OpenOCD Application Level Tracing Commands. 6. The final step is to process received data. Since format of data is defined by user the processing stage is out of the scope of this document. Good starting points for data processor are python scripts in $IDF_PATH/ tools/esp_app_trace: apptrace_proc.py (used for feature tests) and logtrace_proc.py (see more details in section Logging to Host).

OpenOCD Application Level Tracing Commands HW UP BUFFER is shared between user data blocks and filling of the allocated memory is performed on behalf of the API caller (in task or ISR context). In a multithreaded environment, it can happen that the task/ISR which fills the buffer is preempted by another high priority task/ISR.

Espressif Systems

1622

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
It is possible that the user data preparation process is not complete when that chunk is read by the host. To handle such scenarios, the tracing module prepends all user data chunks with a header that contains allocated user buffer size (2 bytes) and the length of the actual written data (2 bytes). So total length of the header is 4 bytes. OpenOCD command which reads trace data reports an error when it reads an incomplete user data chunk. In any case, it puts the contents of the whole user chunk (including unfilled area) to the output file.
Below is the description of available OpenOCD application tracing commands.
Note: Currently, OpenOCD does not provide commands to send arbitrary user data to the target.
Command usage:
esp apptrace [start <options>] | [stop] | [status] | [dump <cores_num> <outfile>]
Sub-commands:
start Start tracing (continuous streaming). stop Stop tracing. status Get tracing status. dump Dump all data from (post-mortem dump).
Start command syntax:
start <outfile> [poll_period [trace_size [stop_tmo [wait4halt [skip_size]]]]
outfile Path to file to save data from both CPUs. This argument should have the following format: file:// path/to/file.
poll_period Data polling period (in ms) for available trace data. If greater than 0 then command runs in nonblocking mode. By default, 1 ms.
trace_size Maximum size of data to collect (in bytes). Tracing is stopped after specified amount of data is received. By default -1 (trace size stop trigger is disabled).
stop_tmo Idle timeout (in sec). Tracing is stopped if there is no data for a specified period of time. By default -1 (disable this stop trigger). Optionally set it to a value longer than the longest pause between tracing commands from the target.
wait4halt If 0 start tracing immediately, otherwise command waits for the target to be halted (after reset, by breakpoint etc.) and then automatically resumes it and starts tracing. By default, 0.
skip_size Number of bytes to skip at the start. By default, 0.
Note: If poll_period is 0, OpenOCD telnet command line will not be available until tracing is stopped. You must stop it manually by resetting the board or pressing Ctrl+C in OpenOCD window (not one with the telnet session). Another option is to set trace_size and wait until this size of data is collected. At this point tracing stops automatically.
Command usage examples:
1. Collect 2048 bytes of tracing data to a fileotrace.logp. The file will be saved inoopenocd-esp32pdirectory.
esp apptrace start file://trace.log 1 2048 5 0 0
The tracing data will be retrieved and saved in non-blocking mode. This process will stop automatically after 2048 bytes are collected, or if no data are available for more than 5 seconds.
Note: Tracing data is buffered before it is made available to OpenOCD. If you see aoData timeout!pmessage, it is likely that the target is not sending enough data to empty the buffer to OpenOCD before the timeout. Either increase the timeout or use a function esp_apptrace_flush() to flush the data on specific intervals.
2. Retrieve tracing data indefinitely in non-blocking mode.

Espressif Systems

1623

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
esp apptrace start file://trace.log 1 -1 -1 0 0
There is no limitation on the size of collected data and there is no data timeout set. This process may be stopped by issuing esp apptrace stop command on OpenOCD telnet prompt, or by pressing Ctrl+C in OpenOCD window. 3. Retrieve tracing data and save them indefinitely.
esp apptrace start file://trace.log 0 -1 -1 0 0
OpenOCD telnet command line prompt will not be available until tracing is stopped. To stop tracing press Ctrl+C in OpenOCD window. 4. Wait for target to be halted. Then resume targetns operation and start data retrieval. Stop after collecting 2048 bytes of data:
esp apptrace start file://trace.log 0 2048 -1 1 0
To configure tracing immediately after reset use the openocd reset halt command.
Logging to Host
IDF implements a useful feature: logging to host via application level tracing library. This is a kind of semihosting when all ESP_LOGx calls are redirected to the host instead of UART. This can be useful because oprinting to hostp eliminates some steps performed when logging to UART. Most part of the work is done on the host.
By default, IDFns logging library uses a vprintf-like function to write formatted output to dedicated UART. In general, it involves the following steps:
1. Format string is parsed to obtain type of each argument. 2. According to its type every argument is converted to string representation. 3. Format string combined with converted arguments is sent to UART.
Though the implementation of a vprintf-like function can be optimized to a certain level, all steps above have to be performed in any case and every step takes some time (especially item 3). Hence, it is quite common to observe that with additional logging added to a program for debugging, the program behavior changes and the problem is not reproduced. In the worst case, the program may not work normally at all and ends up with an error or even hangs.
Possible ways to overcome this problem are to use higher UART bitrates (or another faster interface) and/or move string formatting procedure to the host.
Application level tracing feature can be used to transfer log information to the host using esp_apptrace_vprintf function. This function does not perform full parsing of the format string and arguments, and instead just calculates the number of arguments passed and sends them along with the format string address to the host. On the host, log data are processed and printed out by a special Python script.
Limitations Current implementation of logging over JTAG has some limitations:
1. Tracing from ESP_EARLY_LOGx macros is not supported. 2. No support for printf arguments which size exceeds 4 bytes (e.g. double and uint64_t). 3. Only strings from .rodata section are supported as format strings and arguments. 4. Maximum number of printf arguments is 256.
How To Use It In order to use logging via trace module user needs to perform the following steps:
1. On target side, the user must use the esp_apptrace_vprintf() function to send log data to the host. Example code is provided in system/app_trace_to_host.
2. Follow instructions in items 2-5 in Application Specific Tracing. 3. To print out collected log records, run the following command in terminal: $IDF_PATH/tools/
esp_app_trace/logtrace_proc.py /path/to/trace/file /path/to/program/ elf/file.

Espressif Systems

1624

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Log Trace Processor Command Options Command usage: logtrace_proc.py [-h] [--no-errors] <trace_file> <elf_file> Positional arguments: trace_file Path to log trace file elf_file Path to program ELF file Optional arguments: -h, --help show this help message and exit --no-errors, -n Do not print errors
System Behavior Analysis with SEGGER SystemView
Another useful IDF feature built on top of application tracing library is the system level tracing which produces traces compatible with SEGGER SystemView tool (see SystemView). SEGGER SystemView is a real-time recording and visualization tool that allows to analyze runtime behavior of an application.
Note: Currently, IDF based applications are able to generate SystemView compatible traces in form of files to be opened in the SystemView application. The tracing process cannot yet be controlled using that tool.

How To Use It Support for this feature is enabled by Component config > Application Level Tracing > FreeRTOS SystemView Tracing (CONFIG_APPTRACE_SV_ENABLE) menuconfig option. There are several other options enabled under the same menu:
1. ESP32-S3 timer to use as SystemView timestamp source: (CONFIG_APPTRACE_SV_TS_SOURCE) selects the source of timestamps for SystemView events. In single core mode timestamps are generated using ESP32S3 internal cycle counter running at maximum 240 Mhz (~4 ns granularity). In dual-core mode external timer working at 40 Mhz is used, so timestamp granularity is 25 ns.
2. Individually enabled or disabled collection of SystemView events (CONFIG_APPTRACE_SV_EVT_XXX): · Trace Buffer Overflow Event · ISR Enter Event · ISR Exit Event · ISR Exit to Scheduler Event · Task Start Execution Event · Task Stop Execution Event · Task Start Ready State Event · Task Stop Ready State Event · Task Create Event · Task Terminate Event · System Idle Event · Timer Enter Event · Timer Exit Event
IDF has all the code required to produce SystemView compatible traces, so user can just configure necessary project options (see above), build, download the image to target and use OpenOCD to collect data as described in the previous sections.
OpenOCD SystemView Tracing Command Options Command usage:
esp sysview [start <options>] | [stop] | [status]
Sub-commands:
start Start tracing (continuous streaming). stop Stop tracing. status Get tracing status.

Espressif Systems

1625

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Start command syntax: start <outfile1> [outfile2] [poll_period [trace_size [stop_tmo]]]
outfile1 Path to file to save data from PRO CPU. This argument should have the following format: file:// path/to/file.
outfile2 Path to file to save data from APP CPU. This argument should have the following format: file:// path/to/file.
poll_period Data polling period (in ms) for available trace data. If greater than 0 then command runs in nonblocking mode. By default, 1 ms.
trace_size Maximum size of data to collect (in bytes). Tracing is stopped after specified amount of data is received. By default -1 (trace size stop trigger is disabled).
stop_tmo Idle timeout (in sec). Tracing is stopped if there is no data for specified period of time. By default -1 (disable this stop trigger).
Note: If poll_period is 0 OpenOCD telnet command line will not be available until tracing is stopped. You must stop it manually by resetting the board or pressing Ctrl+C in OpenOCD window (not one with the telnet session). Another option is to set trace_size and wait until this size of data is collected. At this point tracing stops automatically.
Command usage examples: 1. Collect SystemView tracing data to files opro-cpu.SVDatpand oapp-cpu.SVDatp. The files will be saved in oopenocd-esp32pdirectory.
esp sysview start file://pro-cpu.SVDat file://app-cpu.SVDat
The tracing data will be retrieved and saved in non-blocking mode. To stop data this process enter esp sysview stop command on OpenOCD telnet prompt, optionally pressing Ctrl+C in OpenOCD window. 2. Retrieve tracing data and save them indefinitely.
esp sysview start file://pro-cpu.SVDat file://app-cpu.SVDat 0 -1 -1
OpenOCD telnet command line prompt will not be available until tracing is stopped. To stop tracing, press Ctrl+C in OpenOCD window.
Data Visualization After trace data is collected, users can use a special tool to visualize the results and inspect behavior of the program. Unfortunately SystemView does not support tracing from multiple cores. So when tracing from ESP32-S3 working in dual-core mode two files are generated: one for PRO CPU and another one for APP CPU. Users can load both files into separate instances of the tool. It is uneasy and awkward to analyze data for every core in separate instance of the tool. Fortunately there is an Eclipse plugin called Impulse which can load several trace files and makes it possible to inspect events from both cores in one view. Also, this plugin has no limitation of 1,000,000 events as compared to free version of SystemView. Good instruction on how to install, configure and visualize data in Impulse from one core can be found here.
Note: IDF uses its own mapping for SystemView FreeRTOS events IDs, so user needs to replace original file with mapping $SYSVIEW_INSTALL_DIR/Description/SYSVIEW_FreeRTOS.txt with $IDF_PATH/docs/api-guides/SYSVIEW_FreeRTOS.txt. Also contents of that IDF specific file should be used when configuring SystemView serializer using above link.
Configure Impulse for Dual Core Traces After installing Impulse and ensuring that it can successfully load trace files for each core in separate tabsusers can add special Multi Adapter port and load both files into one view. To do this, users need to do the following in Eclipse:

Espressif Systems

1626

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
1. OpenmSignal Portsnview. Go to Windows->Show View->Other menu. FindmSignal Portsnview in Impulse folder and double-click on it.
2. In mSignal Portsnview right-click on mPortsnand select mAdd ln->New Multi Adapter Port 3. In open dialog Press mAddnbutton and select mNew Pipe/Filen. 4. In open dialog select mSystemView Serializernas Serializer and set path to PRO CPU trace file. Press OK. 5. Repeat steps 3-4 for APP CPU trace file. 6. Double-click on created port. View for this port should open. 7. Click Start/Stop Streaming button. Data should be loaded. 8. Use mZoom Outn, mZoom Innand mZoom Fitnbutton to inspect data. 9. For settings measurement cursors and other features please see Impulse documentation).
Note: If you have problems with visualization (no data are shown or strange behavior of zoom action is observed) you can try to delete current signal hierarchy and double-click on the necessary file or port. Eclipse will ask you to create new signal hierarchy.
Gcov (Source Code Coverage)
Basics of Gcov and Gcovr Source code coverage is data indicating the count and frequency of every program execution path that has been taken within a programns runtime. Gcov is a GCC tool that, when used in concert with the compiler, can generate log files indicating the execution count of each line of a source file. The Gcovr tool is utility for managing Gcov and generating summarized code coverage results.
Generally, using Gcov to compile and run programs on the Host will undergo these steps:
1. Compile the source code using GCC with the --coverage option enabled. This will cause the compiler to generate a .gcno notes files during compilation. The notes files contain information to reconstruct execution path block graphs and map each block to source code line numbers. Each source file compiled with the -coverage option should have their own .gcno file of the same name (e.g., a main.c will generate a main.gcno when compiled).
2. Execute the program. During execution, the program should generate .gcda data files. These data files contain the counts of the number of times an execution path was taken. The program will generate a .gcda file for each source file compiled with the --coverage option (e.g., main.c will generate a main.gcda.
3. Gcov or Gcovr can be used generate a code coverage based on the .gcno, .gcda, and source files. Gcov will generate a text based coverage report for each source file in the form of a .gcov file, whilst Gcovr will generate a coverage report in HTML format.
Gcov and Gcovr in ESP-IDF Using Gcov in ESP-IDF is complicated due to the fact that the program is running remotely and not on the host (i.e., on the target). The code coverage data (i.e., the .gcda files) is initially stored on the target itself. OpenOCD is then used to dump the code coverage data from the target to the host via JTAG during runtime. Using Gcov in ESP-IDF can be split into the following steps.
1. Setting Up a Project for Gcov 2. Dumping Code Coverage Data 3. Generating Coverage Report
Setting Up a Project for Gcov
Compiler Option In order to obtain code coverage data in a project, one or more source files within the project must be compiled with the --coverage option. In ESP-IDF, this can be achieved at the component level or the individual source file level:
· To cause all source files in a component to be compiled with the --coverage option, you can add target_compile_options(${COMPONENT_LIB} PRIVATE --coverage) to the CMakeLists. txt file of the component.

Espressif Systems

1627

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

· To cause a select number of source files (e.g. source1.c and source2.c) in the same component to be compiled with the --coverage option, you can add set_source_files_properties(source1. c source2.c PROPERTIES COMPILE_FLAGS --coverage) to the CMakeLists.txt file of the component.
When a source file is compiled with the --coverage option (e.g. gcov_example.c), the compiler will generate the gcov_example.gcno file in the projectns build directory.
Project Configuration Before building a project with source code coverage, ensure that the following project configuration options are enabled by running idf.py menuconfig.
· Enable the application tracing module by choosing Trace Memory for the CONFIG_APPTRACE_DESTINATION option.
· Enable Gcov to host via the CONFIG_APPTRACE_GCOV_ENABLE
Dumping Code Coverage Data Once a project has been complied with the --coverage option and flashed onto the target, code coverage data will be stored internally on the target (i.e., in trace memory) whilst the application runs. The process of transferring code coverage data from the target to the Host is known as dumping.
The dumping of coverage data is done via OpenOCD (see JTAG Debugging on how to setup and run OpenOCD). A dump is triggered by issuing commands to OpenOCD, therefore a telnet session to OpenOCD must be opened to issue such commands (run telnet localhost 4444). Note that GDB could be used instead of telnet to issue commands to OpenOCD, however all commands issued from GDB will need to be prefixed as mon <oocd_command>.
When the target dumps code coverage data, the .gcda files are stored in the projectns build directory. For example, if gcov_example_main.c of the main component was compiled with the --coverage option, then dumping the code coverage data would generate a gcov_example_main.gcda in build/esp-idf/main/ CMakeFiles/__idf_main.dir/gcov_example_main.c.gcda. Note that the .gcno files produced during compilation are also placed in the same directory.
The dumping of code coverage data can be done multiple times throughout an applicationns lifetime. Each dump will simply update the .gcda file with the newest code coverage information. Code coverage data is accumulative, thus the newest data will contain the total execution count of each code path over the applicationns entire lifetime.
ESP-IDF supports two methods of dumping code coverage data form the target to the host:
· Instant Run-Time Dump · Hard-coded Dump
Instant Run-Time Dump An Instant Run-Time Dump is triggered by calling the ESP32-S3 gcov OpenOCD command (via a telnet session). Once called, OpenOCD will immediately preempt the ESP32-S3ns current state and execute a builtin IDF Gcov debug stub function. The debug stub function will handle the dumping of data to the Host. Upon completion, the ESP32-S3 will resume its current state.
Hard-coded Dump A Hard-coded Dump is triggered by the application itself by calling esp_gcov_dump() from somewhere within the application. When called, the application will halt and wait for OpenOCD to connect and retrieve the code coverage data. Once esp_gcov_dump() is called, the Host must execute the esp gcov dump OpenOCD command (via a telnet session). The esp gcov dump command will cause OpenOCD to connect to the ESP32-S3, retrieve the code coverage data, then disconnect from the ESP32-S3 thus allowing the application to resume. Hard-coded Dumps can also be triggered multiple times throughout an applicationns lifetime.
Hard-coded dumps are useful if code coverage data is required at certain points of an applicationns lifetime by placing esp_gcov_dump() where necessary (e.g., after application initialization, during each iteration of an applicationn s main loop).
GDB can be used to set a breakpoint on esp_gcov_dump(), then call mon esp gcov dump automatically via the use a gdbinit script (see Using GDB from Command Line).
The following GDB script is will add a breakpoint at esp_gcov_dump(), then call the mon esp gcov dump OpenOCD command.

Espressif Systems

1628

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
b esp_gcov_dump commands mon esp gcov dump end
Note: Note that all OpenOCD commands should be invoked in GDB as: mon <oocd_command>.
Generating Coverage Report Once the code coverage data has been dumped, the .gcno, .gcda and the source files can be used to generate a code coverage report. A code coverage report is simply a report indicating the number of times each line in a source file has been executed. Both Gcov and Gcovr can be used to generate code coverage reports. Gcov is provided along with the Xtensa toolchain, whilst Gcovr may need to be installed separately. For details on how to use Gcov or Gcovr, refer to Gcov documentation and Gcovr documentation.
Adding Gcov Build Target to Project To make report generation more convenient, users can define additional build targets in their projects such that the report generation can be done with a single build command. Add the following lines to the CMakeLists.txt file of your project.
include($ENV{IDF_PATH}/tools/cmake/gcov.cmake) idf_create_coverage_report(${CMAKE_CURRENT_BINARY_DIR}/coverage_report) idf_clean_coverage_report(${CMAKE_CURRENT_BINARY_DIR}/coverage_report)
The following commands can now be used: · cmake --build build/ --target gcovr-report will generate an HTML coverage report in $(BUILD_DIR_BASE)/coverage_report/html directory. · cmake --build build/ --target cov-data-clean will remove all coverage data files.
4.2 Application Startup Flow
This note explains various steps which happen before app_main function of an ESP-IDF application is called. The high level view of startup process is as follows:
1. First stage bootloader in ROM loads second-stage bootloader image to RAM (IRAM & DRAM) from flash offset 0x0.
2. Second stage bootloader loads partition table and main app image from flash. Main app incorporates both RAM segments and read-only segments mapped via flash cache.
3. Application startup executes. At this point the second CPU and RTOS scheduler are started. This process is explained in detail in the following sections.
4.2.1 First stage bootloader
After SoC reset, PRO CPU will start running immediately, executing reset vector code, while APP CPU will be held in reset. During startup process, PRO CPU does all the initialization. APP CPU reset is de-asserted in the call_start_cpu0 function of application startup code. Reset vector code is located in the mask ROM of the ESP32-S3 chip and cannot be modified. Startup code called from the reset vector determines the boot mode by checking GPIO_STRAP_REG register for bootstrap pin states. Depending on the reset reason, the following takes place:

Espressif Systems

1629

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
1. Reset from deep sleep: if the value in RTC_CNTL_STORE6_REG is non-zero, and CRC value of RTC memory in RTC_CNTL_STORE7_REG is valid, use RTC_CNTL_STORE6_REG as an entry point address and jump immediately to it. If RTC_CNTL_STORE6_REG is zero, or RTC_CNTL_STORE7_REG contains invalid CRC, or once the code called via RTC_CNTL_STORE6_REG returns, proceed with boot as if it was a power-on reset. Note: to run customized code at this point, a deep sleep stub mechanism is provided. Please see deep sleep documentation for this.
2. For power-on reset, software SOC reset, and watchdog SOC reset: check the GPIO_STRAP_REG register if a custom boot mode (such as UART Download Mode) is requested. If this is the case, this custom loader mode is executed from ROM. Otherwise, proceed with boot as if it was due to software CPU reset. Consult ESP32-S3 datasheet for a description of SoC boot modes and how to execute them.
3. For software CPU reset and watchdog CPU reset: configure SPI flash based on EFUSE values, and attempt to load the code from flash. This step is described in more detail in the next paragraphs.
Note: During normal boot modes the RTC watchdog is enabled when this happens, so if the process is interrupted or stalled then the watchdog will reset the SOC automatically and repeat the boot process. This may cause the SoC to strap into a new boot mode, if the strapping GPIOs have changed.
Second stage bootloader binary image is loaded from the start of flash at offset 0x0.
4.2.2 Second stage bootloader
In ESP-IDF, the binary image which resides at offset 0x0 in flash is the second stage bootloader. Second stage bootloader source code is available in components/bootloader directory of ESP-IDF. Second stage bootloader is used in ESP-IDF to add flexibility to flash layout (using partition tables), and allow for various flows associated with flash encryption, secure boot, and over-the-air updates (OTA) to take place.
When the first stage bootloader is finished checking and loading the second stage bootloader, it jumps to the second stage bootloader entry point found in the binary image header.
Second stage bootloader reads the partition table found by default at offset 0x8000 (configurable value). See partition tables documentation for more information. The bootloader finds factory and OTA app partitions. If OTA app partitions are found in the partition table, the bootloader consults the otadata partition to determine which one should be booted. See Over The Air Updates (OTA) for more information.
For a full description of the configuration options available for the ESP-IDF bootloader, see Bootloader.
For the selected partition, second stage bootloader reads the binary image from flash one segment at a time:
· For segments with load addresses in internal IRAM (Instruction RAM) or DRAM (Data RAM), the contents are copied from flash to the load address.
· For segments which have load addresses in DROM (data stored in flash) or IROM (code executed from flash) regions, the flash MMU is configured to provide the correct mapping from the flash to the load address.
Note that the second stage bootloader configures flash MMU for both PRO and APP CPUs, but it only enables flash MMU for PRO CPU. Reason for this is that second stage bootloader code is loaded into the memory region used by APP CPU cache. The duty of enabling cache for APP CPU is passed on to the application.
Once all segments are processed - meaning code is loaded and flash MMU is set up, second stage bootloader verifies the integrity of the application and then jumps to the application entry point found in the binary image header.
4.2.3 Application startup
Application startup covers everything that happens after the app starts executing and before the app_main function starts running inside the main task. This is split into three stages:
· Port initialization of hardware and basic C runtime environment. · System initialization of software services and FreeRTOS. · Running the main task and calling app_main.

Espressif Systems

1630

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Note: Understanding all stages of ESP-IDF app initialization is often not necessary. To understand initialization from the application developerns perspective only, skip forward to Running the main task.
Port Initialization
ESP-IDF application entry point is call_start_cpu0 function found in components/esp_system/port/cpu_start.c. This function is executed by the second stage bootloader, and never returns.
This port-layer initialization function initializes the basic C Runtime Environment (oCRTp) and performs initial configuration of the SoCns internal hardware:
· Reconfigure CPU exceptions for the app (allowing app interrupt handlers to run, and causing Fatal Errors to be handled using the options configured for the app rather than the simpler error handler provided by ROM).
· If the option CONFIG_BOOTLOADER_WDT_ENABLE is not set then the RTC watchdog timer is disabled. · Initialize internal memory (data & bss). · Finish configuring the MMU cache. · Enable PSRAM if configured. · Set the CPU clocks to the frequencies configured for the project. · If the app is configured to run on multiple cores, start the other core and wait for it to initialize as well (inside
the similar oport layerpinitialization function call_start_cpu1).
Once call_start_cpu0 completes running, it calls the osystem layerpinitialization function start_cpu0 found in components/esp_system/startup.c. Other cores will also complete port-layer initialization and call start_other_cores found in the same file.
System Initialization
The main system initialization function is start_cpu0. By default, this function is weak-linked to the function start_cpu0_default. This means that itns possible to override this function to add some additional initialization steps.
The primary system initialization stage includes:
· Log information about this application (project name, App version, etc.) if default log level enables this. · Initialize the heap allocator (before this point all allocations must be static or on the stack). · Initialize newlib component syscalls and time functions. · Configure the brownout detector. · Setup libc stdin, stdout, and stderr according to the serial console configuration. · Perform any security-related checks, including burning efuses that should be burned for this configuration
(including permanently limiting ROM download modes). · Initialize SPI flash API support. · Call global C++ constructors and any C functions marked with __attribute__((constructor)).
Secondary system initialization allows individual components to be initialized. If a component has an initialization function annotated with the ESP_SYSTEM_INIT_FN macro, it will be called as part of secondary initialization.
Running the main task
After all other components are initialized, the main task is created and the FreeRTOS scheduler starts running.
After doing some more initialization tasks (that require the scheduler to have started), the main task runs the application-provided function app_main in the firmware.
The main task that runs app_main has a fixed RTOS priority (one higher than the minimum) and a configurable stack size.
The main task core affinity is also configurable: CONFIG_ESP_MAIN_TASK_AFFINITY.

Espressif Systems

1631

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Unlike normal FreeRTOS tasks (or embedded C main functions), the app_main task is allowed to return. If this happens, The task is cleaned up and the system will continue running with other RTOS tasks scheduled normally. Therefore, it is possible to implement app_main as either a function that creates other application tasks and then returns, or as a main application task itself.

Second core startup

A similar but simpler startup process happens on the APP CPU:

When running system initialization, the code on PRO CPU sets the entry point for APP CPU, de-asserts APP CPU reset, and waits for a global flag to be set by the code running on APP CPU, indicating that it has started. Once this is done, APP CPU jumps to call_start_cpu1 function in components/esp_system/port/cpu_start.c.

While PRO CPU does initialization in start_cpu0 function, APP CPU runs start_cpu_other_cores

function.

Similar to start_cpu0, this function is weak-linked and defaults to the

start_cpu_other_cores_default function but can be replaced with a different function by the

application.

The start_cpu_other_cores_default function does some core-specific system initialization and then waits for the PRO CPU to start the FreeRTOS scheduler, at which point it executes esp_startup_start_app_other_cores which is another weak-linked function defaulting to esp_startup_start_app_other_cores_default.

By default esp_startup_start_app_other_cores_default does nothing but spin in a busy-waiting loop until the scheduler of the PRO CPU triggers an interrupt to start the RTOS scheduler on the APP CPU.

4.3 BluFi
4.3.1 Overview
The BluFi for ESP32-S3 is a Wi-Fi network configuration function via Bluetooth channel. It provides a secure protocol to pass Wi-Fi configuration and credentials to the ESP32-S3. Using this information ESP32-S3 can then e.g. connect to an AP or establish a SoftAP.
Fragmenting, data encryption, checksum verification in the BluFi layer are the key elements of this process.
You can customize symmetric encryption, asymmetric encryption and checksum support customization. Here we use the DH algorithm for key negotiation, 128-AES algorithm for data encryption, and CRC16 algorithm for checksum verification.
4.3.2 The BluFi Flow
The BluFi networking flow includes the configuration of the SoftAP and Station.
The following uses Station as an example to illustrate the core parts of the procedure, including broadcast, connection, service discovery, negotiation of the shared key, data transmission, connection status backhaul.
1. Set the ESP32-S3 into GATT Server mode and then it will send broadcasts with specific advertising data. You can customize this broadcast as needed, which is not a part of the BluFi Profile.
2. Use the App installed on the mobile phone to search for this particular broadcast. The mobile phone will connect to ESP32-S3 as the GATT Client once the broadcast is confirmed. The App used during this part is up to you.
3. After the GATT connection is successfully established, the mobile phone will send a data frame for key negotiation to ESP32-S3 (see the section The Frame Formats Defined in BluFi for details).
4. After ESP32-S3 receives the data frame of key negotiation, it will parse the content according to the userdefined negotiation method.
5. The mobile phone works with ESP32-S3 for key negotiation using the encryption algorithms such as DH, RSA or ECC.

Espressif Systems

1632

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
6. After the negotiation process is completed, the mobile phone will send a control frame for security-mode setup to ESP32-S3.
7. When receiving this control frame, ESP32-S3 will be able to encrypt and decrypt the communication data using the shared key and the security configuration.
8. The mobile phone sends the data frame defined in the section of The Frame Formats Defined in BluFiwith the Wi-Fi configuration information to ESP32-S3, including SSID, password, etc.
9. The mobile phone sends a control frame of Wi-Fi connection request to ESP32-S3. When receiving this control frame, ESP32-S3 will regard the communication of essential information as done and get ready to connect to the Wi-Fi.
10. After connecting to the Wi-Fi, ESP32-S3 will send a control frame of Wi-Fi connection status report to the mobile phoneto report the connection status. At this point the networking procedure is completed.
Note: 1. After ESP32-S3 receives the control frame of security-mode configuration, it will execute the operations in accordance with the defined security mode. 2. The data lengths before and after symmetric encryption/decryption must stay the same. It also supports in-place encryption and decryption.
4.3.3 The Flow Chart of BluFi

Espressif Systems

Fig. 2: BluFi Flow Chart

1633

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

4.3.4 The Frame Formats Defined in BluFi
The frame formats for the communication between the mobile phone App and ESP32-S3 are defined as follows: The frame format with no fragment (8 bit)

Description Type (Least Significant Bit) Frame Control Sequence Number Data Length Data CheckSum (Most Siginificant Bit)

Value 1 1 1 1 ${Data Length} 2

If the Frame Ctrl bit is enabled, the Total length bit indicates the length of remaining part of the frame. It can tell the remote how much memory needs to be alloced.
The frame format with fragmentsc8 bit

Description Type (Least Significant Bit) Frame Control (Frag) Sequence Number Data Length Data
CheckSum (Most Siginificant Bit)

Value 1 1 1 1
· Total Content Length: 2 · Content: ${Data Length} - 2
2

Normally, the control frame does not contain data bits, except for ACK Frame. The format of ACK Framec8 bit

Description Type - ACK (Least Significant Bit) Frame Control Sequence Number Data Length Data CheckSum (Most Siginificant Bit)

Value 1 1 1 1 Acked Sequence Number: 2 2

1. Type The Type field, taking 1 byte, is divided into Type and Subtype, that Type uses the lower 2 bits and Subtype uses the upper 6 bits. · The control frame is not encrypted for the time being and supports to be verified; · The data frame supports to be encrypted and verified.
1.1 Control Frame (Binary: 0x0 bn00)

Espressif Systems

1634

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Control Implication Frame 0x0 ACK (bn 000000) 0x1 Set ESP device to the (bn security mode. 000001)
0x2 Set the opmode of (bn Wi-Fi. 000010)
0x3 Connect ESP device (bn to the AP. 000011) 0x4 Disconnect ESP de(bn vice from the AP. 000100) 0x5 To get the informa(bn tion of ESP devicens 000101)Wi-Fi mode and itns
status.

Explanation
The data field of the ACK frame uses the same sequence value of the frame to reply to. To inform ESP device of the security mode to use when sending data, which is allowed to be reset multiple times during the process. Each setting affects the subsequent security mode used. If it is not set, ESP device will send the control frame and data frame with no checksum and encryption by default. The data transmission from the mobile phone to ESP device is controlled by this control frame. The frame contains opmode settings for configuring the Wi-Fi mode of ESP device.
To notify ESP device that the essential information has been sent and it is allowed to connect to the AP.

Note
The data field consumes a byte and its value is the same as the sequence field of the frame to reply to. The data field consumes a byte. The higher 4 bits are for the security mode setting of the control frame, and the lower 4 bits are for the security mode setting of the data frame.
· bn0000: no checksum and no encryption;
· bn0001: with checksum but no encryption;
· bn0010: no checksum but with encryption;
· bn0011: with both checksum and encryption.
data[0] is for opmode settings, including: · 0x00: NULL · 0x01: STA · 0x02: SoftAP · 0x03: SoftAP & STA
Please set the SSID/Password/Max Connection Number of the AP mode in the first place if an AP gets involved. No data field is contained.
No data field is contained.
· No data field is contained. When receiving this control frame, ESP device will send back a follow-up frame of WiFi connection state report to the mobile phone with the information of the current opmode, connection status, SSID and so on.
· The types of information sent to the mobile phone is defined by the application installed on the phone.

0x6 Disconnect the STA (bn device from the 000110)SoftAP (in SoftAP
mode). 0x7 Get the version infor(bn mation. 000111) 0x8 Disconnect the BLE (bn GATT link. 001000) 0x9 Get the Wi-Fi list. (bn Es0p0r1e0ss0i1f)Systems

Date[0~5] is taken as the MAC address for the STA device. If there is a second STA device, then it uses data[6-11] and the rest can be done in the same manner.

ESP device will disconnect the BLE GATT link after receives this command.

To get ESP device to scan the No data field is contained. When receiving

Wi-Fi access points around. this control frame, ESP device will send back

Submit

1635 Document

Feeamdbofobalilcloekwp-huopRnefer.laemasee

vo5f.0W-di-eFvi-1li4s2t4r-egp2o4r6t 7toaat7hfe6c

Chapter 4. API Guides 1.2 Data Frame (Binary: 0x1 bn01)

Espressif Systems

1636

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Data Implication Frame 0x0 Send the negotiation (bn data. 000000)
0x1 Send the BSSID for (bn STA mode. 000001)
0x2 Send the SSID for (bn STA mode. 000010) 0x3 Send the password for (bn STA mode. 000011) 0x4 Send the SSID for (bn SoftAP mode. 000100) 0x5 Send the password for (bn SoftAPmode. 000101) 0x6 Set the maximum (bn connection number 000110)for SoftAP mode.
0x7 Set the authentication (bn mode for the SoftAP. 000111)
0x8 Set the number of (bn channels for SoftAP 001000)mode.
0x9 Username (bn 001001) 0xa CA Certification (bn 001010) 0xb Client Certification (bn 001011)
0xc Server Certification (bn 001100)
Es0pxrdessif SCylisetenmt Psrivate Key (bn 001101) 0xe Server Private Key

Explanation

Note

The negotiation data will be sent to the callback function registered in the application layer. To send the BSSID of the AP for the STA device to connect under the condition that the SSID is hidden. To send the SSID of the AP for the STA device to connect.

The length of the data depends on the length field. Please refer to Note 1 below.
Please refer to Note 1 below.

To send the password of the AP for the STA device to connect.

Please refer to Note 1 below. Please refer to Note 1 below.

Please refer to Note 1 below.

data[0] represents the value of the connection number, ranging from 1 to 4. When the transmission direction is ESP device to the mobile phone, it means to provide the mobile phone with the needed information. data[0]
· 0x00: OPEN · 0x01: WEP · 0x02: WPA_PSK · 0x03: WPA2_PSK · 0x04: WPA_WPA2_PSK When the transmission direction is ESP device to the mobile phone, it means to provide the mobile phone with the needed information. data[0] represents the quantity of the supported channels, ranging from 1 to 14. When the transmission direction is ESP device to the mobile phone, it means to provide the mobile phone with the needed information. It provides the username of The length of the data depends on the length the GATT client when using field. encryption of enterprise level. It provides the CA Certifica- Please refer to Note 2 below. tion when using encryption of enterprise level. It provides the client certifica- Please refer to Note 2 below. tion when using encryption of enterprise level. Whether the private key is contained or not depends on the content of the certification. It provides the sever certifica- Please refer to Note 2 below. tion when using encryption of enterprise level. Whether the private key is contained or not depends on the content of the certification. It provides the priva1te63ke7y of Please referRteoleNasoetev52.0b-edloewv-.1424-g2467aa7f6c the cliSenutbwmhietnDuosicnugmenecnrytpF- eedback tion of enterprise level. It provides the private key of Please refer to Note 2 below.

Chapter 4. API Guides

Note:
· Note 1: The length of the data depends on the length field. When the transmission direction is ESP device to the mobile phone, it means to provide the mobile phone with the needed information.
· Note 2: The length of the data depends on the length field. The frame supports to be fragmented if the data length is not enough.

2. Frame Control Control field, takes 1 byte and each bit has a different meaning.

Bit

Meaning

0x01

Indicates whether the frame is encrypted.

· 1 means encryption

· 0 means unencrypted

The encrypted part of the frame includes the full clear data before the DATA field is

encrypted (no checksum). Control frame is not encrypted, so this bit is 0.

0x02

The data field that indicates whether a frame contains a checksum (such as

SHA1,MD5,CRC, etc.) for the end of the frame. Data field includes sequence + data

length + clear text. Both the control frame and the data frame can contain a check bit

or not.

0x04

Represents the data direction.

· 0 means the mobile phone to ESP device;

· 1 means ESP device to the mobile phone.

0x08

Indicates whether the other person is required to reply to an ACK.

· 0 indicates no requirement;

· 1 indicates to reply ACK.

0x10 0x10~0x80

Indicates whether there are subsequent data fragments. · 0 indicates that there are no subsequent data fragments for this frame; · 1 indicates that there are subsequent data fragments and used to transmit longer data.
In the case of a frag frame, the total length of the current content section + subsequent content section is given, in the first 2 bytes of the data field (that is, the content data of the maximum support 64 K). reserved

3. Sequence Control Sequence control field. When a frame is sent,the value of sequence fied is automatically incremented by 1 regardless of the type of frame, which prevents Replay Attack. The sequence is cleared after each reconnection.
4. Length The length of the data field that does not include CheckSum.
5. Data The instruction of the data field is different according to various values of Type or Subtype. Please refer to the table above.
6. CheckSum This field takes 2 bytes that is used to check osequence + data length + clear text datap.

4.3.5 The Security Implementation of ESP32-S3
1. Securing data To ensure that the transmission of the Wi-Fi SSID and password is secure, the message needs to be encrypted using symmetric encryption algorithms, such as AES, DES and so on. Before using symmetric encryption algorithms, the devices are required to negotiate (or generate) a shared key using an asymmetric encryption algorithm (DH, RSA, ECC, etc).
2. Ensuring data integrity

Espressif Systems

1638

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
To ensure data integrity, you need to add a checksum algorithm, such as SHA1, MD5, CRC, etc. 3. Securing identity (signature)
Algorithm like RSA can be used to secure identity. But for DH, it needs other algorithms as an companion for signature. 4. Replay attack prevention It is added to the Sequence field and used during the checksum verification. For the coding of ESP32-S3, you can determine and develop the security processing, such as key negotiation. The mobile application sends the negotiation data to ESP32-S3 and then the data will be sent to the application layer for processing. If the application layer does not process it, you can use the DH encryption algorithm provided by BluFi to negotiate the key. The application layer needs to register several security-related functions to BluFi:
typedef void (*esp_blufi_negotiate_data_handler_t)(uint8_t *data, int len, uint8_t **output_data, int *output_len, bool *need_free)
This function is for ESP32-S3 to receive normal data during negotiation, and after processing is completed, the data will be transmitted using Output_data and Output_len. BluFi will send output_data from Negotiate_data_handler after Negotiate_data_handler is called. Here are two o*p, because the length of the data to be emitted is unknown that requires the function to allocate itself (malloc) or point to the global variable, and to inform whether the memory needs to be freed by NEED_FREE.
typedef int (* esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len)
The data to be encrypted and decrypted must use the same length. The IV8 is a 8 bit sequence value of frames, which can be used as a 8 bit of IV.
typedef int (* esp_blufi_decrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len)
The data to be encrypted and decrypted must use the same length. The IV8 is a 8 bit sequence value of frames, which can be used as a 8 bit of IV.
typedef uint16_t (*esp_blufi_checksum_func_t)(uint8_t iv8, uint8_t *data, int len)
This function is used to compute CheckSum and return a value of CheckSum. BluFi uses the returned value to compare the CheckSum of the frame.
4.3.6 GATT Related Instructions
UUID
BluFi Service UUID: 0xFFFF, 16 bit BluFi (the mobile -> ESP32-S3): 0xFF01, writable Blufi (ESP32-S3 -> the mobile phone): 0xFF02, readable and callable
4.4 Bootloader
The ESP-IDF Software Bootloader performs the following functions: 1. Minimal initial configuration of internal modules; 2. Initialize Flash Encryption and/or Secure features, if configured; 3. Select the application partition to boot, based on the partition table and ota_data (if any); 4. Load this image to RAM (IRAM & DRAM) and transfer management to the image that was just loaded.

Espressif Systems

1639

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Bootloader is located at the address 0x0 in the flash. For a full description of the startup process including the the ESP-IDF bootloader, see Application Startup Flow.
4.4.1 Bootloader compatibility
It is recommended to update to newer versions of ESP-IDF: when they are released. The OTA (over the air) update process can flash new apps in the field but cannot flash a new bootloader. For this reason, the bootloader supports booting apps built from newer versions of ESP-IDF. The bootloader does not support booting apps from older versions of ESP-IDF. When updating ESP-IDF manually on an existing product that might need to downgrade the app to an older version, keep using the older ESP-IDF bootloader binary as well.
Note: If testing an OTA update for an existing product in production, always test it using the same ESP-IDF bootloader binary that is deployed in production.

SPI Flash Configuration
Each ESP-IDF application or bootloader .bin file contains a header with CONFIG_ESPTOOLPY_FLASHMODE, CONFIG_ESPTOOLPY_FLASHFREQ, CONFIG_ESPTOOLPY_FLASHSIZE embedded in it. These are used to configure the SPI flash during boot.
The First stage bootloader in ROM reads the Second stage bootloader header information from flash and uses this infomation to load the rest of the Second stage bootloader from flash. However, at this time the system clock speed is lower than configured and not all flash modes are supported. When the Second stage bootloader then runs, it will reconfigure the flash using values read from the currently selected app binaryns header (and NOT from the Second stage bootloader header). This allows an OTA update to change the SPI flash settings in use.
4.4.2 Log Level
The default bootloader log level is oInfop. By setting the CONFIG_BOOTLOADER_LOG_LEVEL option, itns possible to increase or decrease this level. This log level is separate from the log level used in the app (see Logging library).
Reducing bootloader log verbosity can improve the overall project boot time by a small amount.
4.4.3 Factory reset
Sometimes it is desirable to have a way for the device to fall back to a known-good state, in case of some problem with an update.
To roll back to the original ofactorypdevice configuration and clear any user settings, configure the config item CONFIG_BOOTLOADER_FACTORY_RESET in the bootloader.
The factory reset mechanism allows the device to be factory reset in two ways:
· Clear one or more data partitions. The CONFIG_BOOTLOADER_DATA_FACTORY_RESET option allows users to specify which data partitions will be erased when the factory reset is executed. Users can specify the names of partitions as a comma-delimited list with optional spaces for readability. (Like this: nvs, phy_init, nvs_custom). Make sure that the names of partitions specified in the option are the same as those found in the partition table. Partitions of type oapppcannot be specified here.
· Boot from ofactorypapp partition. Enabling the CONFIG_BOOTLOADER_OTA_DATA_ERASE option will cause the device to boot from the default ofactorypapp partition after a factory reset (or if there is no factory app partition in the partition table then the default ota app partition is selected instead). This reset process

Espressif Systems

1640

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

involves erasing the OTA data partition which holds the currently selected OTA partition slot. The ofactoryp app partition slot (if it exists) is never updated via OTA, so resetting to this allows reverting to aoknown goodp firmware application.
Either or both of these configuration options can be enabled independently.
In addition, the following configuration options control the reset condition:
· CONFIG_BOOTLOADER_NUM_PIN_FACTORY_RESET- The input GPIO number used to trigger a factory reset. This GPIO must be pulled low or high (configurable) on reset to trigger this.
· CONFIG_BOOTLOADER_HOLD_TIME_GPIO- this is hold time of GPIO for reset/test mode (by default 5 seconds). The GPIO must be held continuously for this period of time after reset before a factory reset or test partition boot (as applicable) is performed.
· CONFIG_BOOTLOADER_FACTORY_RESET_PIN_LEVEL - configure whether a factory reset should trigger on a high or low level of the GPIO. If the GPIO has an internal pullup then this is enabled before the pin is sampled, consult the ESP32-S3 datasheet for details on pin internal pullups.
4.4.4 Boot from Test Firmware
Itns possible to write a special firmware app for testing in production, and boot this firmware when needed. The project partition table will need a dedicated app partition entry for this testing app, type app and subtype test (see Partition Tables).
Implementing a dedicated test app firmware requires creating a totally separate ESP-IDF project for the test app (each project in ESP-IDF only builds one app). The test app can be developed and tested independently of the main project, and then integrated at production testing time as a pre-compiled .bin file which is flashed to the address of the main projectns test app partition.
To support this functionality in the main projectns bootloader, set the configuration item CONFIG_BOOTLOADER_APP_TEST and configure the following two items:
· CONFIG_BOOTLOADER_NUM_PIN_APP_TEST - GPIO number to boot TEST partition. The selected GPIO will be configured as an input with internal pull-up enabled. To trigger a test app, this GPIO must be pulled low on reset. Once the GPIO input is released (allowing it to be pulled up) and the device has been reboot, the normally configured application will boot (factory or any OTA app partition slot).
· CONFIG_BOOTLOADER_HOLD_TIME_GPIO - this is hold time of GPIO for reset/test mode (by default 5 seconds). The GPIO must be held low continuously for this period of time after reset before a factory reset or test partition boot (as applicable) is performed.
4.4.5 Rollback
Rollback and anti-rollback features must be configured in the bootloader as well.
Consult the App rollback and Anti-rollback sections in the OTA API reference document.
4.4.6 Watchdog
By default, the hardware RTC Watchdog timer remains running while the bootloader is running and will automatically reset the chip if no app has successfully started after 9 seconds.
· The timeout period can be adjusted by setting CONFIG_BOOTLOADER_WDT_TIME_MS and recompiling the bootloader.
· The appns behaviour can be adjusted so the RTC Watchdog remains enabled after app startup. The Watchdog would need to be explicitly reset (i.e., fed) by the app to avoid a reset. To do this, set the CONFIG_BOOTLOADER_WDT_DISABLE_IN_USER_CODE option, modify the app as needed, and then recompile the app.
· The RTC Watchdog can be disabled in the bootloader by disabling the CONFIG_BOOTLOADER_WDT_ENABLE setting and recompiling the bootloader. This is not recommended.

Espressif Systems

1641

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

4.4.7 Bootloader Size
When enabling additional bootloader functions, including Flash Encryption or Secure Boot, and especially if setting a high CONFIG_BOOTLOADER_LOG_LEVEL level, then it is important to monitor the bootloader .bin filens size.
When using the default CONFIG_PARTITION_TABLE_OFFSET value 0x8000, the size limit is 0x8000 (32768) bytes.
If the bootloader binary is too large, then the bootloader build will fail with an error oBootloader binary size [..] is too large for partition table offsetp. If the bootloader binary is flashed anyhow then the ESP32-S3 will fail to boot errors will be logged about either invalid partition table or invalid bootloader checksum.
Options to work around this are:
· Set bootloader compiler optimization back to oSizepif it has been changed from this default value. · Reduce bootloader log level. Setting log level to Warning, Error or None all significantly reduce the final binary
size (but may make it harder to debug). · Set CONFIG_PARTITION_TABLE_OFFSET to a higher value than 0x8000, to place the partition table later
in the flash. This increases the space available for the bootloader. If the partition table CSV file contains explicit partition offsets, they will need changing so no partition has an offset lower than CONFIG_PARTITION_TABLE_OFFSET + 0x1000. (This includes the default partition CSV files supplied with ESP-IDF.)
When Secure Boot V2 is enabled, there is also an absolute binary size limit of 64KB (0x10000 bytes) (excluding the 4 KB signature), because the bootloader is first loaded into a fixed size buffer for verification.
4.4.8 Fast boot from Deep Sleep
The bootloader has the CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP option which allows the wake-up time from deep sleep to be reduced (useful for reducing power consumption). This option is available when CONFIG_SECURE_BOOT option is disabled. Reduction of time is achieved due to the lack of image verification. During the first boot, the bootloader stores the address of the application being launched in the RTC FAST memory. And during the awakening, this address is used for booting without any checks, thus fast loading is achieved.
4.4.9 Custom bootloader
The current bootloader implementation allows a project to extend it or modify it. There are two ways of doing it: by implementing hooks or by overriding it. Both ways are presented in custom_bootloader folder in ESP-IDF examples:
· bootloader_hooks which presents how to connect some hooks to the bootloader initialization · bootloader_override which presents how to override the bootloader implementation
In the bootloader space, you cannot use the drivers and functions from other components. If necessary, then the required functionality should be placed in the projectns bootloader_components directory (note that this will increase its size).
If the bootloader grows too large then it can collide with the partition table, which is flashed at offset 0x8000 by default. Increase the partition table offset value to place the partition table later in the flash. This increases the space available for the bootloader.

4.5 Build System
This document explains the implementation of the ESP-IDF build system and the concept ofocomponentsp. Read this document if you want to know how to organize and build a new ESP-IDF project or component.

4.5.1 Overview
An ESP-IDF project can be seen as an amalgamation of a number of components. For example, for a webserver that shows the current humidity, there could be:

Espressif Systems

1642

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· The ESP-IDF base libraries (libc, ROM bindings, etc) · The Wi-Fi drivers · A TCP/IP stack · The FreeRTOS operating system · A webserver · A driver for the humidity sensor · Main code tying it all together
ESP-IDF makes these components explicit and configurable. To do that, when a project is compiled, the build system will look up all the components in the ESP-IDF directories, the project directories and (optionally) in additional custom component directories. It then allows the user to configure the ESP-IDF project using a text-based menu system to customize each component. After the components in the project are configured, the build system will compile the project.
Concepts
· A oprojectpis a directory that contains all the files and configuration to build a single oappp(executable), as well as additional supporting elements such as a partition table, data/filesystem partitions, and a bootloader.
·oProject configurationpis held in a single file called sdkconfig in the root directory of the project. This configuration file is modified via idf.py menuconfig to customise the configuration of the project. A single project contains exactly one project configuration.
· Anoapppis an executable which is built by ESP-IDF. A single project will usually build two apps - aoproject appp(the main executable, ie your custom firmware) and a obootloader appp(the initial bootloader program which launches the project app).
·ocomponentspare modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by ESP-IDF itself, others may be sourced from other places.
·oTargetpis the hardware for which an application is built. A full list of supported targets in your version if ESP-IDF can be seen by running idf.py list-targets.
Some things are not part of the project:
·oESP-IDFpis not part of the project. Instead it is standalone, and linked to the project via the IDF_PATH environment variable which holds the path of the esp-idf directory. This allows the IDF framework to be decoupled from your project.
· The toolchain for compilation is not part of the project. The toolchain should be installed in the system command line PATH.
4.5.2 Using the Build System
idf.py
The idf.py command-line tool provides a front-end for easily managing your project builds. It manages the following tools:
· CMake, which configures the project to be built · A command-line build tool (either Ninja build or GNU Make) · esptool.py for flashing the target.
The getting started guide contains a brief introduction to how to set up idf.py to configure, build, and flash projects.
idf.py should be run in an ESP-IDF oprojectpdirectory, i.e. one containing a CMakeLists.txt file. Older style projects with a Makefile will not work with idf.py.
Type idf.py --help for a list of commands. Here are a summary of the most useful ones:
· idf.py set-target <target> sets the target (chip) for which the project is built. See Selecting the Target.
· idf.py menuconfig runs the omenuconfigptool to configure the project. · idf.py build will build the project found in the current directory. This can involve multiple steps:

Espressif Systems

1643

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
­ Create the build directory if needed. The sub-directory build is used to hold build output, although this can be changed with the -B option.
­ Run CMake as necessary to configure the project and generate build files for the main build tool. ­ Run the main build tool (Ninja or GNU Make). By default, the build tool is automatically detected but it
can be explicitly set by passing the -G option to idf.py. Building is incremental so if no source files or configuration has changed since the last build, nothing will be done. · idf.py clean will ocleanpthe project by deleting build output files from the build directory, forcing a ofull rebuildpthe next time the project is built. Cleaning doesnnt delete CMake configuration output and some other files. · idf.py fullclean will delete the entireobuildpdirectory contents. This includes all CMake configuration output. The next time the project is built, CMake will configure it from scratch. Note that this option recursively deletes all files in the build directory, so use with care. Project configuration is not deleted. · idf.py flash will automatically build the project if necessary, and then flash it to the target. The -p and -b options can be used to set serial port name and flasher baud rate, respectively. · idf.py monitor will display serial output from the target. The -p option can be used to set the serial port name. Type Ctrl-] to exit the monitor. See IDF Monitor for more details about using the monitor.
Multiple idf.py commands can be combined into one. For example, idf.py -p COM4 clean flash monitor will clean the source tree, then build the project and flash it to the target before running the serial monitor.
For commands that are not known to idf.py an attempt to execute them as a build system target will be made.
The command idf.py supports shell autocompletion for bash, zsh and fish shells.
In order to make shell autocompletion supported, please make sure you have at least Python 3.5 and click 7.1 or newer (see also).
To enable autocompletion for idf.py use the export command (see this). Autocompletion is initiated by pressing the TAB key. Type oidf.py -pand press the TAB key to autocomplete options.
The autocomplete support for PowerShell is planned in the future.
Note: The environment variables ESPPORT and ESPBAUD can be used to set default values for the -p and -b options, respectively. Providing these options on the command line overrides the default.

Advanced Commands
· idf.py app, idf.py bootloader, idf.py partition-table can be used to build only the app, bootloader, or partition table from the project as applicable.
· There are matching commands idf.py app-flash, etc. to flash only that single part of the project to the target.
· idf.py -p PORT erase-flash will use esptool.py to erase the targetns entire flash chip. · idf.py size prints some size information about the app. size-components and size-files are
similar commands which print more detailed per-component or per-source-file information, respectively. If you define variable -DOUTPUT_JSON=1 when running CMake (or idf.py), the output will be formatted as JSON not as human readable text. See idf.py-size for more information. · idf.py reconfigure re-runs CMake even if it doesnnt seem to need re-running. This isnnt necessary during normal usage, but can be useful after adding/removing files from the source tree, or when modifying CMake cache variables. For example, idf.py -DNAME='VALUE' reconfigure can be used to set variable NAME in CMake cache to value VALUE. · idf.py python-clean deletes generated Python byte code from the IDF directory which may cause issues when switching between IDF and Python versions. It is advised to run this target after switching versions of Python. · idf.py docs will open direct link to documentation for projectns chip target and version in browser. To see all options use idf.py docs --help
The order of multiple idf.py commands on the same invocation is not important, they will automatically be executed in the correct order for everything to take effect (ie building before flashing, erasing before flashing, etc.).

Espressif Systems

1644

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

idf.py options To list all available root level options, run idf.py --help. To list options that are specific for a subcommand, run idf.py <command> --help, for example idf.py monitor --help. Here is a list of some useful options:
· -C <dir> allows overriding the project directory from the default current working directory. · -B <dir> allows overriding the build directory from the default build subdirectory of the project directory. · --ccache flag can be used to enable CCache when compiling source files, if the CCache tool is installed.
This can dramatically reduce some build times.
Note that some older versions of CCache may exhibit bugs on some platforms, so if files are not rebuilt as expected then try disabling CCache and build again. CCache can be enabled by default by setting the IDF_CCACHE_ENABLE environment variable to a non-zero value.
· -v flag causes both idf.py and the build system to produce verbose build output. This can be useful for debugging build problems.
· --cmake-warn-uninitialized (or -w) will cause CMake to print uninitialized variable warnings inside the project directory (not for directories not found inside the project directory). This only controls CMake variable warnings inside CMake itself, not other types of build warnings. This option can also be set permanently by setting the IDF_CMAKE_WARN_UNINITIALIZED environment variable to a non-zero value.

Start a new project
Use the command idf.py create-project for starting a new project. Execute idf.py createproject --help for more information. Example: idf.py create-project --path my_projects my_new_project
This example will create a new project called my_new_project directly into the directory my_projects.

Using CMake Directly

idf.py is a wrapper around CMake for convenience. However, you can also invoke CMake directly if you prefer.
When idf.py does something, it prints each command that it runs for easy reference. For example, the idf. py build command is the same as running these commands in a bash shell (or similar commands for Windows Command Prompt):

mkdir -p build cd build cmake .. -G Ninja ninja

# or 'Unix Makefiles'

In the above list, the cmake command configures the project and generates build files for use with the final build tool. In this case the final build tool is Ninja: running ninja actually builds the project.
Itns not necessary to run cmake more than once. After the first build, you only need to run ninja each time. ninja will automatically re-invoke cmake if the project needs reconfiguration.
If using CMake with ninja or make, there are also targets for more of the idf.py sub-commands - for example running make menuconfig or ninja menuconfig in the build directory will work the same as idf.py menuconfig.

Note: If younre already familiar with CMake, you may find the ESP-IDF CMake-based build system unusual because it wraps a lot of CMakens functionality to reduce boilerplate. See writing pure CMake components for some information about writing more oCMake stylepcomponents.

Espressif Systems

1645

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Flashing with ninja or make Itns possible to build and flash directly from ninja or make by running a target like: ninja flash
Or: make app-flash
Available targets are: flash, app-flash (app only), bootloader-flash (bootloader only). When flashing this way, optionally set the ESPPORT and ESPBAUD environment variables to specify the serial port and baud rate. You can set environment variables in your operating system or IDE project. Alternatively, set them directly on the command line: ESPPORT=/dev/ttyUSB0 ninja flash
Note: Providing environment variables at the start of the command like this is Bash shell Syntax. It will work on Linux and macOS. It wonnt work when using Windows Command Prompt, but it will work when using Bash-like shells on Windows.
Or: make -j3 app-flash ESPPORT=COM4 ESPBAUD=2000000
Note: Providing variables at the end of the command line is make syntax, and works for make on all platforms.
Using CMake in an IDE
You can also use an IDE with CMake integration. The IDE will want to know the path to the projectns CMakeLists.txt file. IDEs with CMake integration often provide their own build tools (CMake calls theseogeneratorsp ) to build the source files as part of the IDE. When adding custom non-build steps like oflashpto the IDE, it is recommended to execute idf.py for these ospecialpcommands. For more detailed information about integrating ESP-IDF with CMake into an IDE, see Build System Metadata.
Setting up the Python Interpreter
ESP-IDF works well with all supported Python versions. It should work out-of-box even if you have a legacy system where the default python interpreter is still Python 2.7, however, it is advised to switch to Python 3 if possible. idf.py and other Python scripts will run with the default Python interpreter, i.e. python. You can switch to a different one like python3 $IDF_PATH/tools/idf.py ..., or you can set up a shell alias or another script to simplify the command. If using CMake directly, running cmake -D PYTHON=python3 ... will cause CMake to override the default Python interpreter. If using an IDE with CMake, setting the PYTHON value as a CMake cache override in the IDE UI will override the default Python interpreter. To manage the Python version more generally via the command line, check out the tools pyenv or virtualenv. These let you change the default Python version.

Espressif Systems

1646

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Possible issues The user of idf.py may sometimes experience ImportError described below.
Traceback (most recent call last): File "/Users/user_name/e/esp-idf/tools/kconfig_new/confgen.py", line 27, in
<module> import kconfiglib
ImportError: bad magic number in 'kconfiglib': b'\x03\xf3\r\n'
The exception is often caused by .pyc files generated by different Python versions. To solve the issue run the following command:
idf.py python-clean

4.5.3 Example Project

An example project directory tree might look like this:

- myProject/

- CMakeLists.txt

- sdkconfig

- components/ - component1/ - CMakeLists.txt

- Kconfig

- src1.c

- component2/ - CMakeLists.txt

- Kconfig

- src1.c

- include/ - component2.h

- main/

- CMakeLists.txt

- src1.c

- src2.c

- build/

This example omyProjectpcontains the following elements:
· A top-level project CMakeLists.txt file. This is the primary file which CMake uses to learn how to build the project; and may set project-wide CMake variables. It includes the file /tools/cmake/project.cmake which implements the rest of the build system. Finally, it sets the project name and defines the project.
·osdkconfigpproject configuration file. This file is created/updated when idf.py menuconfig runs, and holds configuration for all of the components in the project (including ESP-IDF itself). The osdkconfigpfile may or may not be added to the source control system of the project.
· Optional ocomponentspdirectory contains components that are part of the project. A project does not have to contain custom components of this kind, but it can be useful for structuring reusable code or including third party components that arennt part of ESP-IDF. Alternatively, EXTRA_COMPONENT_DIRS can be set in the top-level CMakeLists.txt to look for components in other places. See the renaming main section for more info. If you have a lot of source files in your project, we recommend grouping most into components instead of putting them all in omainp.
·omainpdirectory is a special component that contains source code for the project itself. omainpis a default name, the CMake variable COMPONENT_DIRS includes this component but you can modify this variable.
·obuildpdirectory is where build output is created. This directory is created by idf.py if it doesnnt already exist. CMake configures the project and generates interim build files in this directory. Then, after the main build process is run, this directory will also contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code.
Component directories each contain a component CMakeLists.txt file. This file contains variable definitions to control the build process of the component, and its integration into the overall project. See Component CMakeLists Files for more details.
Each component may also include a Kconfig file defining the component configuration options that can be set via menuconfig. Some components may also include Kconfig.projbuild and project_include.cmake files, which are special files for overriding parts of the project.

Espressif Systems

1647

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.5.4 Project CMakeLists File
Each project has a single top-level CMakeLists.txt file that contains build settings for the entire project. By default, the project CMakeLists can be quite minimal.
Minimal Example CMakeLists Minimal project: cmake_minimum_required(VERSION 3.5) include($ENV{IDF_PATH}/tools/cmake/project.cmake) project(myProject)

Mandatory Parts
The inclusion of these three lines, in the order shown above, is necessary for every project:
· cmake_minimum_required(VERSION 3.5) tells CMake the minimum version that is required to build the project. ESP-IDF is designed to work with CMake 3.5 or newer. This line must be the first line in the CMakeLists.txt file.
· include($ENV{IDF_PATH}/tools/cmake/project.cmake) pulls in the rest of the CMake functionality to configure the project, discover all the components, etc.
· project(myProject) creates the project itself, and specifies the project name. The project name is used for the final binary output files of the app - ie myProject.elf, myProject.bin. Only one project can be defined per CMakeLists file.

Optional Project Variables

These variables all have default values that can be overridden for custom behaviour. /tools/cmake/project.cmake for all of the implementation details.

Look in

· COMPONENT_DIRS: Directories to search for components. Defaults to IDF_PATH/components, PROJECT_DIR/components, and EXTRA_COMPONENT_DIRS. Override this variable if you donnt want to search for components in these places.
· EXTRA_COMPONENT_DIRS: Optional list of additional directories to search for components. Paths can be relative to the project directory, or absolute.
· COMPONENTS: A list of component names to build into the project. Defaults to all components found in the COMPONENT_DIRS directories. Use this variable tootrim downpthe project for faster build times. Note that any component which orequirespanother component via the REQUIRES or PRIV_REQUIRES arguments on component registration will automatically have it added to this list, so the COMPONENTS list can be very short.

Any paths in these variables can be absolute paths, or set relative to the project directory.

To set these variables, use the cmake set command ie set(VARIABLE "VALUE"). The set() commands should be placed after the cmake_minimum(...) line but before the include(...) line.

Renaming main component
The build system provides special treatment to the main component. It is a component that gets automatically added to the build provided that it is in the expected location, PROJECT_DIR/main. All other components in the build are also added as its dependencies, saving the user from hunting down dependencies and providing a build that works right out of the box. Renaming the main component causes the loss of these behind-the-scenes heavy lifting, requiring the user to specify the location of the newly renamed component and manually specifying its dependencies. Specifically, the steps to renaming main are as follows:
1. Rename main directory.

Espressif Systems

1648

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
2. Set EXTRA_COMPONENT_DIRS in the project CMakeLists.txt to include the renamed main directory. 3. Specify the dependencies in the renamed componentns CMakeLists.txt file via REQUIRES or
PRIV_REQUIRES arguments on component registration.
Overriding default build specifications
The build sets some global build specifications (compile flags, definitions, etc.) that gets used in compiling all sources from all components. For example, one of the default build specifications set is the compile option -Wextra. Suppose a user wants to use override this with -Wno-extra, it should be done after project():
cmake_minimum_required(VERSION 3.5) include($ENV{IDF_PATH}/tools/cmake/project.cmake) project(myProject)
idf_build_set_property(COMPILE_OPTIONS "-Wno-error" APPEND)
This ensures that the compile options set by the user wonnt be overriden by the default build specifications, since the latter are set inside project().
4.5.5 Component CMakeLists Files
Each project contains one or more components. Components can be part of ESP-IDF, part of the projectns own components directory, or added from custom component directories (see above). A component is any directory in the COMPONENT_DIRS list which contains a CMakeLists.txt file.
Searching for Components
The list of directories in COMPONENT_DIRS is searched for the projectns components. Directories in this list can either be components themselves (ie they contain a CMakeLists.txt file), or they can be top-level directories whose sub-directories are components. When CMake runs to configure the project, it logs the components included in the build. This list can be useful for debugging the inclusion/exclusion of certain components.
Multiple components with the same name
When ESP-IDF is collecting all the components to compile, it will do this in the order specified by COMPONENT_DIRS; by default, this means ESP-IDFns internal components first (IDF_PATH/components), then any components in directories specified in EXTRA_COMPONENT_DIRS, and finally the projectns components (PROJECT_DIR/components). If two or more of these directories contain component sub-directories with the same name, the component in the last place searched is used. This allows, for example, overriding ESP-IDF components with a modified version by copying that component from the ESP-IDF components directory to the project components directory and then modifying it there. If used in this way, the ESP-IDF directory itself can remain untouched.
Note: If a component is overridden in an existing project by moving it to a new location, the project will not automatically see the new component path. Run idf.py reconfigure (or delete the project build folder) and then build again.

Espressif Systems

1649

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Minimal Component CMakeLists
The minimal component CMakeLists.txt file simply registers the component to the build system using idf_component_register:
idf_component_register(SRCS "foo.c" "bar.c" INCLUDE_DIRS "include" REQUIRES mbedtls)
· SRCS is a list of source files (*.c, *.cpp, *.cc, *.S). These source files will be compiled into the component library.
· INCLUDE_DIRS is a list of directories to add to the global include search path for any component which requires this component, and also the main source files.
· REQUIRES is not actually required, but it is very often required to declare what other components this component will use. See Component Requirements.
A library with the name of the component will be built and linked into the final app.
Directories are usually specified relative to the CMakeLists.txt file itself, although they can be absolute.
There are other arguments that can be passed to idf_component_register. These arguments are discussed here.
See example component requirements and example component CMakeLists for more complete component CMakeLists.txt examples.

Create a new component
Use the command idf.py create-component for creating a new component. The new component will contain set of files necessary for building a component. You may include the componentns header file into your project and use its functionality. For more information execute idf.py create-component --help. Example:
idf.py -C components create-component my_component
The example will create a new component in the subdirectory components under the current working directory. For more information about components follow the documentation page see above.

Preset Component Variables
The following component-specific variables are available for use inside component CMakeLists, but should not be modified:
· COMPONENT_DIR: The component directory. Evaluates to the absolute path of the directory containing CMakeLists.txt. The component path cannot contain spaces. This is the same as the CMAKE_CURRENT_SOURCE_DIR variable.
· COMPONENT_NAME: Name of the component. Same as the name of the component directory. · COMPONENT_ALIAS: Alias of the library created internally by the build system for the component. · COMPONENT_LIB: Name of the library created internally by the build system for the component.
The following variables are set at the project level, but available for use in component CMakeLists:
· CONFIG_*: Each value in the project configuration has a corresponding variable available in cmake. All names begin with CONFIG_. More information here.
· ESP_PLATFORM: Set to 1 when the CMake file is processed within ESP-IDF build system.

Build/Project Variables
The following are some project/build variables that are available as build properties and whose values can be queried using idf_build_get_property from the component CMakeLists.txt:

Espressif Systems

1650

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· PROJECT_NAME: Name of the project, as set in project CMakeLists.txt file. · PROJECT_DIR: Absolute path of the project directory containing the project CMakeLists. Same as the
CMAKE_SOURCE_DIR variable. · COMPONENTS: Names of all components that are included in this build, formatted as a semicolon-delimited
CMake list. · IDF_VER: Git version of ESP-IDF (produced by git describe) · IDF_VERSION_MAJOR, IDF_VERSION_MINOR, IDF_VERSION_PATCH: Components of ESP-IDF
version, to be used in conditional expressions. Note that this information is less precise than that provided by IDF_VER variable. v4.0-dev-*, v4.0-beta1, v4.0-rc1 and v4.0 will all have the same values of IDF_VERSION_* variables, but different IDF_VER values. · IDF_TARGET: Name of the target for which the project is being built. · PROJECT_VER: Project version.
­ If CONFIG_APP_PROJECT_VER_FROM_CONFIG option is set, the value of CONFIG_APP_PROJECT_VER will be used.
­ Else, if PROJECT_VER variable is set in project CMakeLists.txt file, its value will be used. ­ Else, if the PROJECT_DIR/version.txt exists, its contents will be used as PROJECT_VER. ­ Else, if the project is located inside a Git repository, the output of git describe will be used. ­ Otherwise, PROJECT_VER will be o1p. Other build properties are listed here.
Controlling Component Compilation
To pass compiler options when compiling source files belonging to a particular component, use the target_compile_options function:
target_compile_options(${COMPONENT_LIB} PRIVATE -Wno-unused-variable)
To apply the compilation flags to a single source file, use the CMake set_source_files_properties command:
set_source_files_properties(mysrc.c PROPERTIES COMPILE_FLAGS -Wno-unused-variable
)
This can be useful if there is upstream code that emits warnings. When using these commands, place them after the call to idf_component_register in the component CMakeLists file.
4.5.6 Component Configuration
Each component can also have a Kconfig file, alongside CMakeLists.txt. This contains configuration settings to add to the configuration menu for this component. These settings are found under the oComponent Settingspmenu when menuconfig is run. To create a component Kconfig file, it is easiest to start with one of the Kconfig files distributed with ESP-IDF. For an example, see Adding conditional configuration.
4.5.7 Preprocessor Definitions
The ESP-IDF build system adds the following C preprocessor definitions on the command line: · ESP_PLATFORM : Can be used to detect that build happens within ESP-IDF. · IDF_VER : Defined to a git version string. E.g. v2.0 for a tagged release or v1.0-275-g0efaa4f for an arbitrary commit.

Espressif Systems

1651

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.5.8 Component Requirements
When compiling each component, the ESP-IDF build system recursively evaluates its dependencies. This means each component needs to declare the components that it depends on (orequiresp).
When writing a component
idf_component_register(... REQUIRES mbedtls PRIV_REQUIRES console spiffs)
· REQUIRES should be set to all components whose header files are #included from the public header files of this component.
· PRIV_REQUIRES should be set to all components whose header files are #included from any source files in this component, unless already listed in REQUIRES. Also any component which is required to be linked in order for this component to function correctly.
· The values of REQUIRES and PRIV_REQUIRES should not depend on any configuration choices (CONFIG_xxx macros). This is because requirements are expanded before configuration is loaded. Other component variables (like include paths or source files) can depend on configuration choices.
· Not setting either or both REQUIRES variables is fine. If the component has no requirements except for the Common component requirements needed for RTOS, libc, etc.
If a components only supports some target chips (values of IDF_TARGET) then it can specify REQUIRED_IDF_TARGETS in the idf_component_register call to express these requirements. In this case the build system will generate an error if the component is included into the build, but does not support the selected target.
Note: In CMake terms, REQUIRES & PRIV_REQUIRES are approximate wrappers around the CMake functions target_link_libraries(... PUBLIC ...) and target_link_libraries(... PRIVATE . ..).

Example of component requirements
Imagine there is a car component, which uses the engine component, which uses the spark_plug component:
- autoProject/ - CMakeLists.txt - components/ - car/ - CMakeLists.txt - car.c - car.h - engine/ - CMakeLists.txt - engine.c - include/ - engine.h - spark_plug/ - CMakeLists.txt - plug.c - plug.h

Car component The car.h header file is the public interface for the car component. This header includes engine.h directly because it uses some declarations from this header:
/* car.h */ #include "engine.h"
#ifdef ENGINE_IS_HYBRID #define CAR_MODEL "Hybrid" #endif

Espressif Systems

1652

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

And car.c includes car.h as well:
/* car.c */ #include "car.h"
This means the car/CMakeLists.txt file needs to declare that car requires engine:
idf_component_register(SRCS "car.c" INCLUDE_DIRS "." REQUIRES engine)
· SRCS gives the list of source files in the car component. · INCLUDE_DIRS gives the list of public include directories for this component. Because the public interface
is car.h, the directory containing car.h is listed here. · REQUIRES gives the list of components required by the public interface of this component. Because car.h
is a public header and includes a header from engine, we include engine here. This makes sure that any other component which includes car.h will be able to recursively include the required engine.h also.
Engine component The engine component also has a public header file include/engine.h, but this header is simpler:
/* engine.h */ #define ENGINE_IS_HYBRID
void engine_start(void);
The implementation is in engine.c:
/* engine.c */ #include "engine.h" #include "spark_plug.h"
...
In this component, engine depends on spark_plug but this is a private dependency. spark_plug.h is needed to compile engine.c, but not needed to include engine.h. This means that the engine/CMakeLists.txt file can use PRIV_REQUIRES:
idf_component_register(SRCS "engine.c" INCLUDE_DIRS "include" PRIV_REQUIRES spark_plug)
As a result, source files in the car component donnt need the spark_plug include directories added to their compiler search path. This can speed up compilation, and stops compiler command lines from becoming longer than necessary.
Spark Plug Component The spark_plug component doesnnt depend on anything else. It has a public header file spark_plug.h, but this doesnnt include headers from any other components. This means that the spark_plug/CMakeLists.txt file doesnnt need any REQUIRES or PRIV_REQUIRES clauses:
idf_component_register(SRCS "spark_plug.c" INCLUDE_DIRS ".")

Source File Include Directories
Each componentns source file is compiled with these include path directories, as specified in the passed arguments to idf_component_register:

Espressif Systems

1653

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

idf_component_register(.. INCLUDE_DIRS "include" PRIV_INCLUDE_DIRS "other")
· The current componentns INCLUDE_DIRS and PRIV_INCLUDE_DIRS. · The INCLUDE_DIRS belonging to all other components listed in the REQUIRES and PRIV_REQUIRES
parameters (ie all the current componentns public and private dependencies). · Recursively, all of the INCLUDE_DIRS of those components REQUIRES lists (ie all public dependencies of
this componentns dependencies, recursively expanded).
Main component requirements
The component named main is special because it automatically requires all other components in the build. So itns not necessary to pass REQUIRES or PRIV_REQUIRES to this component. See renaming main for a description of what needs to be changed if no longer using the main component.
Common component requirements
To avoid duplication, every component automatically requires some ocommonpIDF components even if they are not mentioned explicitly. Headers from these components can always be included. The list of common components is: cxx, newlib, freertos, esp_hw_support, heap, log, lwip, soc, hal, esp_rom, esp_common, esp_system.
Including components in the build
· By default, every component is included in the build. · If you set the COMPONENTS variable to a minimal list of components used directly by your project, then the
build will expand to also include required components. The full list of components will be: ­ Components mentioned explicitly in COMPONENTS. ­ Those componentsnrequirements (evaluated recursively). ­ The ocommonpcomponents that every component depends on.
· Setting COMPONENTS to the minimal list of required components can significantly reduce compile times.
Circular Dependencies
Itns possible for a project to contain Component A that requires (REQUIRES or PRIV_REQUIRES) Component B, and Component B that requires Component A. This is known as a dependency cycle or a circular dependency. CMake will usually handle circular dependencies automatically by repeating the component library names twice on the linker command line. However this strategy doesnnt always work, and itns possible the build will fail with a linker error about oUndefined reference to lp, referencing a symbol defined by one of the components inside the circular dependency. This is particularly likely if there is a large circular dependency, i.e. A->B->C->D->A. The best solution is to restructure the components to remove the circular dependency. In most cases, a software architecture without circular dependencies has desirable properties of modularity and clean layering and will be more maintainable in the long term. However, removing circular dependencies is not always possible. To bypass a linker error caused by a circular dependency, the simplest workaround is to increase the CMake LINK_INTERFACE_MULTIPLICITY property of one of the component libraries. This causes CMake to repeat this library and its dependencies more than two times on the linker command line. For example:
set_property(TARGET ${COMPONENT_LIB} APPEND PROPERTY LINK_INTERFACE_MULTIPLICITY 3)
· This line should be placed after idf_component_register in the component CMakeLists.txt file.

Espressif Systems

1654

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

· If possible, place this line in the component that creates the circular dependency by depending on a lot of other components. However, the line can be placed inside any component that is part of the cycle. Choosing the component that owns the source file shown in the linker error message, or the component that defines the symbol(s) mentioned in the linker error message, is a good place to start.
· Usually increasing the value to 3 (default is 2) is enough, but if this doesnnt work then try increasing the number further.
· Adding this option will make the linker command line longer, and the linking stage slower.

Advanced Workaround: Undefined Symbols If only one or two symbols is causing a circular dependency, and all other dependencies are linear, then there is an alternative method to avoid linker errors: Specify the specific symbols required for the oreversepdependency as undefined symbols at link time.
For example, if component A depends on component B but component B also needs to reference reverse_ops from component A (but nothing else), then you can add a line like the following to the component B CMakeLists.txt to resolve the cycle at link time:
# This symbol is provided by 'Component A' at link time target_link_libraries(${COMPONENT_LIB} INTERFACE "-u reverse_ops")
· The -u argument means that the linker will always include this symbol in the link, regardless of dependency ordering.
· This line should be placed after idf_component_register in the component CMakeLists.txt file. · IfmComponent Bndoesnnt need to access any headers ofmComponent An, only link to a few symbol(s), then
this line can be used instead of any REQUIRES from B to A. This further simplifies the component structure in the build system.
See the target_link_libraries documentation for more information about this CMake function.

Requirements in the build system implementation
· Very early in the CMake configuration process, the script expand_requirements.cmake is run. This script does a partial evaluation of all component CMakeLists.txt files and builds a graph of component requirements (this graph may have cycles). The graph is used to generate a file component_depends.cmake in the build directory.
· The main CMake process then includes this file and uses it to determine the list of components to include in the build (internal BUILD_COMPONENTS variable). The BUILD_COMPONENTS variable is sorted so dependencies are listed first, however as the component dependency graph has cycles this cannot be guaranteed for all components. The order should be deterministic given the same set of components and component dependencies.
· The value of BUILD_COMPONENTS is logged by CMake as oComponent names: o · Configuration is then evaluated for the components included in the build. · Each component is included in the build normally and the CMakeLists.txt file is evaluated again to add the
component libraries to the build.

Component Dependency Order The order of components in the BUILD_COMPONENTS variable determines other orderings during the build:
· Order that project_include.cmake files are included into the project. · Order that the list of header paths is generated for compilation (via -I argument). (Note that for a given
componentns source files, only that componentns dependencyns header paths are passed to the compiler.)

4.5.9 Overriding Parts of the Project
project_include.cmake
For components that have build requirements which must be evaluated before any component CMakeLists files are evaluated, you can create a file called project_include.cmake in the component directory. This CMake file

Espressif Systems

1655

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
is included when project.cmake is evaluating the entire project. project_include.cmake files are used inside ESP-IDF, for defining project-wide build features such as esptool.py command line arguments and the bootloader ospecial appp. Unlike component CMakeLists.txt files, when including a project_include.cmake file the current source directory (CMAKE_CURRENT_SOURCE_DIR and working directory) is the project directory. Use the variable COMPONENT_DIR for the absolute directory of the component. Note that project_include.cmake isnnt necessary for the most common component uses - such as adding include directories to the project, or LDFLAGS to the final linking step. These values can be customised via the CMakeLists.txt file itself. See Optional Project Variables for details. project_include.cmake files are included in the order given in BUILD_COMPONENTS variable (as logged by CMake). This means that a componentns project_include.cmake file will be included after itns all dependenciesnproject_include.cmake files, unless both components are part of a dependency cycle. This is important if a project_include.cmake file relies on variables set by another component. See also above. Take great care when setting variables or targets in a project_include.cmake file. As the values are included into the top-level project CMake pass, they can influence or break functionality across all components!
KConfig.projbuild
This is an equivalent to project_include.cmake for Component Configuration KConfig files. If you want to include configuration options at the top-level of menuconfig, rather than inside the oComponent Configurationp sub-menu, then these can be defined in the KConfig.projbuild file alongside the CMakeLists.txt file. Take care when adding configuration values in this file, as they will be included across the entire project configuration. Where possible, itns generally better to create a KConfig file for Component Configuration. project_include.cmake files are used inside ESP-IDF, for defining project-wide build features such as esptool.py command line arguments and the bootloader ospecial appp.
4.5.10 Configuration-Only Components
Special components which contain no source files, only Kconfig.projbuild and KConfig, can have a one-line CMakeLists.txt file which calls the function idf_component_register() with no arguments specified. This function will include the component in the project build, but no library will be built and no header files will be added to any include paths.
4.5.11 Debugging CMake
For full details about CMake and CMake commands, see the CMake v3.5 documentation. Some tips for debugging the ESP-IDF CMake-based build system:
· When CMake runs, it prints quite a lot of diagnostic information including lists of components and component paths.
· Running cmake -DDEBUG=1 will produce more verbose diagnostic output from the IDF build system. · Running cmake with the --trace or --trace-expand options will give a lot of information about
control flow. See the cmake command line documentation. When included from a project CMakeLists file, the project.cmake file defines some utility modules and global variables and then sets IDF_PATH if it was not set in the system environment. It also defines an overridden custom version of the built-in CMake project function. This function is overridden to add all of the ESP-IDF specific project functionality.

Espressif Systems

1656

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Warning On Undefined Variables
By default, idf.py passes the --warn-uninitialized flag to CMake so it will print a warning if an undefined variable is referenced in the build. This can be very useful to find buggy CMake files. If you donnt want this behaviour, it can be disabled by passing --no-warnings to idf.py. Browse the /tools/cmake/project.cmake file and supporting functions in /tools/cmake/ for more details.
4.5.12 Example Component CMakeLists
Because the build environment tries to set reasonable defaults that will work most of the time, component CMakeLists.txt can be very small or even empty (see Minimal Component CMakeLists). However, overriding component variables is usually required for some functionality. Here are some more advanced examples of component CMakeLists files.
Adding conditional configuration
The configuration system can be used to conditionally compile some files depending on the options selected in the project configuration. Kconfig:
config FOO_ENABLE_BAR bool "Enable the BAR feature." help This enables the BAR feature of the FOO component.
CMakeLists.txt:
set(srcs "foo.c" "more_foo.c")
if(CONFIG_FOO_ENABLE_BAR) list(APPEND srcs "bar.c")
endif()
idf_component_register(SRCS "${srcs}" ...)
This example makes use of the CMake if function and list APPEND function. This can also be used to select or stub out an implementation, as such: Kconfig:
config ENABLE_LCD_OUTPUT bool "Enable LCD output." help Select this if your board has a LCD.
config ENABLE_LCD_CONSOLE bool "Output console text to LCD" depends on ENABLE_LCD_OUTPUT help Select this to output debugging output to the lcd
config ENABLE_LCD_PLOT bool "Output temperature plots to LCD" depends on ENABLE_LCD_OUTPUT help Select this to output temperature plots

Espressif Systems

1657

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
CMakeLists.txt:
if(CONFIG_ENABLE_LCD_OUTPUT) set(srcs lcd-real.c lcd-spi.c)
else() set(srcs lcd-dummy.c)
endif()
# We need font if either console or plot is enabled if(CONFIG_ENABLE_LCD_CONSOLE OR CONFIG_ENABLE_LCD_PLOT)
list(APPEND srcs "font.c") endif()
idf_component_register(SRCS "${srcs}" ...)
Conditions which depend on the target
The current target is available to CMake files via IDF_TARGET variable. In addition to that, if target xyz is used (IDF_TARGET=xyz), then Kconfig variable CONFIG_IDF_TARGET_XYZ will be set. Note that component dependencies may depend on IDF_TARGET variable, but not on Kconfig variables. Also one can not use Kconfig variables in include statements in CMake files, but IDF_TARGET can be used in such context.
Source Code Generation
Some components will have a situation where a source file isnnt supplied with the component itself but has to be generated from another file. Say our component has a header file that consists of the converted binary data of a BMP file, converted using a hypothetical tool called bmp2h. The header file is then included in as C source file called graphics_lib.c:
add_custom_command(OUTPUT logo.h COMMAND bmp2h -i ${COMPONENT_DIR}/logo.bmp -o log.h DEPENDS ${COMPONENT_DIR}/logo.bmp VERBATIM)
add_custom_target(logo DEPENDS logo.h) add_dependencies(${COMPONENT_LIB} logo)
set_property(DIRECTORY "${COMPONENT_DIR}" APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES logo.h)
This answer is adapted from the CMake FAQ entry, which contains some other examples that will also work with ESP-IDF builds. In this example, logo.h will be generated in the current directory (the build directory) while logo.bmp comes with the component and resides under the component path. Because logo.h is a generated file, it should be cleaned when the project is cleaned. For this reason it is added to the ADDITIONAL_MAKE_CLEAN_FILES property.
Note: If generating files as part of the project CMakeLists.txt file, not a component CMakeLists.txt, then use build property PROJECT_DIR instead of ${COMPONENT_DIR} and ${PROJECT_NAME}.elf instead of ${COMPONENT_LIB}.)
If a a source file from another component included logo.h, then add_dependencies would need to be called to add a dependency between the two components, to ensure that the component source files were always compiled in the correct order.

Espressif Systems

1658

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Embedding Binary Data
Sometimes you have a file with some binary or text data that yound like to make available to your component - but you donnt want to reformat the file as C source. You can specify argument EMBED_FILES in the component registration, giving space-delimited names of the files to embed:
idf_component_register(... EMBED_FILES server_root_cert.der)
Or if the file is a string, you can use the variable EMBED_TXTFILES. This will embed the contents of the text file as a null-terminated string:
idf_component_register(... EMBED_TXTFILES server_root_cert.pem)
The filens contents will be added to the .rodata section in flash, and are available via symbol names as follows:
extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_ pem_start"); extern const uint8_t server_root_cert_pem_end[] asm("_binary_server_root_cert_ pem_end");
The names are generated from the full name of the file, as given in EMBED_FILES. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files. To embed a file into a project, rather than a component, you can call the function target_add_binary_data like this:
target_add_binary_data(myproject.elf "main/data.bin" TEXT)
Place this line after the project() line in your project CMakeLists.txt file. Replace myproject.elf with your project name. The final argument can be TEXT to embed a null-terminated string, or BINARY to embed the content as-is. For an example of using this technique, see the omainpcomponent of the file_serving example protocols/http_server/file_serving/main/CMakeLists.txt - two files are loaded at build time and linked into the firmware. It is also possible embed a generated file:
add_custom_command(OUTPUT my_processed_file.bin COMMAND my_process_file_cmd my_unprocessed_file.bin)
target_add_binary_data(my_target "my_processed_file.bin" BINARY)
In the example above, my_processed_file.bin is generated from my_unprocessed_file.bin through some command my_process_file_cmd, then embedded into the target. To specify a dependence on a target, use the DEPENDS argument:
add_custom_target(my_process COMMAND ...) target_add_binary_data(my_target "my_embed_file.bin" BINARY DEPENDS my_process)
The DEPENDS argument to target_add_binary_data ensures that the target executes first.
Code and Data Placements
ESP-IDF has a feature called linker script generation that enables components to define where its code and data will be placed in memory through linker fragment files. These files are processed by the build system, and is used to augment the linker script used for linking app binary. See Linker Script Generation for a quick start guide as well as a detailed discussion of the mechanism.

Espressif Systems

1659

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Fully Overriding The Component Build Process
Obviously, there are cases where all these recipes are insufficient for a certain component, for example when the component is basically a wrapper around another third-party component not originally intended to be compiled under this build system. In that case, itns possible to forego the ESP-IDF build system entirely by using a CMake feature called ExternalProject. Example component CMakeLists:
# External build process for quirc, runs in source dir and # produces libquirc.a externalproject_add(quirc_build
PREFIX ${COMPONENT_DIR} SOURCE_DIR ${COMPONENT_DIR}/quirc CONFIGURE_COMMAND "" BUILD_IN_SOURCE 1 BUILD_COMMAND make CC=${CMAKE_C_COMPILER} libquirc.a INSTALL_COMMAND "" )
# Add libquirc.a to the build process add_library(quirc STATIC IMPORTED GLOBAL) add_dependencies(quirc quirc_build)
set_target_properties(quirc PROPERTIES IMPORTED_LOCATION ${COMPONENT_DIR}/quirc/libquirc.a)
set_target_properties(quirc PROPERTIES INTERFACE_INCLUDE_DIRECTORIES ${COMPONENT_DIR}/quirc/lib)
set_directory_properties( PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES "${COMPONENT_DIR}/quirc/libquirc.a")
(The above CMakeLists.txt can be used to create a component named quirc that builds the quirc project using its own Makefile.)
· externalproject_add defines an external build system. ­ SOURCE_DIR, CONFIGURE_COMMAND, BUILD_COMMAND and INSTALL_COMMAND should always be set. CONFIGURE_COMMAND can be set to an empty string if the build system has nooconfigurep step. INSTALL_COMMAND will generally be empty for ESP-IDF builds. ­ Setting BUILD_IN_SOURCE means the build directory is the same as the source directory. Otherwise you can set BUILD_DIR. ­ Consult the ExternalProject documentation for more details about externalproject_add()
· The second set of commands adds a library target, which points to the oimportedplibrary file built by the external system. Some properties need to be set in order to add include directories and tell CMake where this file is.
· Finally, the generated library is added to ADDITIONAL_MAKE_CLEAN_FILES. This means make clean will delete this library. (Note that the other object files from the build wonnt be deleted.)
ExternalProject dependencies, clean builds CMake has some unusual behaviour around external project builds:
· ADDITIONAL_MAKE_CLEAN_FILES only works when omakepis used as the build system. If Ninja or an IDE build system is used, it wonnt delete these files when cleaning.
· However, the ExternalProject configure & build commands will always be re-run after a clean is run. · Therefore, there are two alternative recommended ways to configure the external build command:
1. Have the external BUILD_COMMAND run a full clean compile of all sources. The build command will be run if any of the dependencies passed to externalproject_add with DEPENDS have changed, or if this is a clean build (ie any of idf.py clean, ninja clean, or make clean was run.)
2. Have the external BUILD_COMMAND be an incremental build command. Pass the parameter BUILD_ALWAYS 1 to externalproject_add. This means the external project will be built each time a build is run, regardless of dependencies. This is only recommended if the external project has correct incremental build behaviour, and doesnnt take too long to run.

Espressif Systems

1660

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
The best of these approaches for building an external project will depend on the project itself, its build system, and whether you anticipate needing to frequently recompile the project.
4.5.13 Custom sdkconfig defaults
For example projects or other projects where you donnt want to specify a full sdkconfig configuration, but you do want to override some key values from the ESP-IDF defaults, it is possible to create a file sdkconfig.defaults in the project directory. This file will be used when creating a new config from scratch, or when any new config value hasnnt yet been set in the sdkconfig file. To override the name of this file or to specify multiple files, set the SDKCONFIG_DEFAULTS environment variable or set SDKCONFIG_DEFAULTS in top-level CMakeLists.txt. If specifying multiple files, use semicolon as the list separator. File names not specified as full paths are resolved relative to current project. Some of the IDF examples include a sdkconfig.ci file. This is part of the continuous integration (CI) test framework and is ignored by the normal build process.
Target-dependent sdkconfig defaults
In addition to sdkconfig.defaults file, build system will also load defaults from sdkconfig.defaults. TARGET_NAME file, where TARGET_NAME is the value of IDF_TARGET. For example, for esp32 target, default settings will be taken from sdkconfig.defaults first, and then from sdkconfig.defaults.esp32. If SDKCONFIG_DEFAULTS is used to override the name of defaults file/files, the name of target-specific defaults file will be derived from SDKCONFIG_DEFAULTS value/values using the rule above.
4.5.14 Flash arguments
There are some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. Itns simple to write a script to save binaries and esptool.py. After running a project build, the build directory contains binary output files (.bin files) for the project and also the following flashing data files:
· flash_project_args contains arguments to flash the entire project (app, bootloader, partition table, PHY data if this is configured).
· flash_app_args contains arguments to flash only the app. · flash_bootloader_args contains arguments to flash only the bootloader. You can pass any of these flasher argument files to esptool.py as follows:
python esptool.py --chip esp32 write_flash @build/flash_project_args
Alternatively, it is possible to manually copy the parameters from the argument file and pass them on the command line. The build directory also contains a generated file flasher_args.json which contains project flash information, in JSON format. This file is used by idf.py and can also be used by other tools which need information about the project build.
4.5.15 Building the Bootloader
The bootloader is built by default as part of idf.py build, or can be built standalone via idf.py bootloader. The bootloader is a special osubprojectpinside /components/bootloader/subproject. It has its own project CMakeLists.txt file and builds separate .ELF and .BIN files to the main project. However it shares its configuration and build directory with the main project.

Espressif Systems

1661

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
The subproject is inserted as an external project from the top-level project, by the file /components/bootloader/project_include.cmake. The main build process runs CMake for the subproject, which includes discovering components (a subset of the main components) and generating a bootloader-specific config (derived from the main sdkconfig).
4.5.16 Selecting the Target
ESP-IDF supports multiple targets (chips). A full list of supported targets in your version if ESP-IDF can be seen by running idf.py list-targets. To select the target before building the project, use idf.py set-target <target> command, for example:
idf.py set-target esp32s2
Important: idf.py set-target will clear the build directory and re-generate the sdkconfig file from scratch. The old sdkconfig file will be saved as sdkconfig.old.
Note: The behavior of idf.py set-target command is equivalent to: 1. clearing the build directory (idf.py fullclean) 2. removing the sdkconfig file (mv sdkconfig sdkconfig.old) 3. configuring the project with the new target (idf.py -DIDF_TARGET=esp32 reconfigure)
It is also possible to pass the desired IDF_TARGET as an environment variable (e.g. export IDF_TARGET=esp32s2) or as a CMake variable (e.g. -DIDF_TARGET=esp32s2 argument to CMake or idf.py). Setting the environment variable is a convenient method if you mostly work with one type of the chip. To specify the _default_ value of IDF_TARGET for a given project, add CONFIG_IDF_TARGET value to sdkconfig.defaults. For example, CONFIG_IDF_TARGET="esp32s2". This value will be used if IDF_TARGET is not specified by other method: using an environment variable, CMake variable, or idf.py settarget command. If the target has not been set by any of these methods, the build system will default to esp32 target.
4.5.17 Writing Pure CMake Components
The ESP-IDF build systemowrapspCMake with the concept ofocomponentsp, and helper functions to automatically integrate these components into a project build. However, underneath the concept of ocomponentspis a full CMake build system. It is also possible to make a component which is pure CMake. Here is an example minimal opure CMakepcomponent CMakeLists file for a component named json:
add_library(json STATIC cJSON/cJSON.c cJSON/cJSON_Utils.c)
target_include_directories(json PUBLIC cJSON)
· This is actually an equivalent declaration to the IDF json component /components/json/CMakeLists.txt. · This file is quite simple as there are not a lot of source files. For components with a large number of files, the
globbing behaviour of ESP-IDFns component logic can make the component CMakeLists style simpler.) · Any time a component adds a library target with the component name, the ESP-IDF build system will auto-
matically add this to the build, expose public include directories, etc. If a component wants to add a library target with a different name, dependencies will need to be added manually via CMake commands.

Espressif Systems

1662

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.5.18 Using Third-Party CMake Projects with Components
CMake is used for a lot of open-source C and C++ projects icode that users can tap into for their applications. One of the benefits of having a CMake build system is the ability to import these third-party projects, sometimes even without modification! This allows for users to be able to get functionality that may not yet be provided by a component, or use another library for the same functionality. Importing a library might look like this for a hypothetical library foo to be used in the main component:
# Register the component idf_component_register(...)
# Set values of hypothetical variables that control the build of `foo` set(FOO_BUILD_STATIC OFF) set(FOO_BUILD_TESTS OFF)
# Create and import the library targets add_subdirectory(foo)
# Publicly link `foo` to `main` component target_link_libraries(main PUBLIC foo)
For an actual example, take a look at build_system/cmake/import_lib. Take note that what needs to be done in order to import the library may vary. It is recommended to read up on the libraryns documentation for instructions on how to import it from other projects. Studying the libraryns CMakeLists.txt and build structure can also be helpful. It is also possible to wrap a third-party library to be used as a component in this manner. For example, the mbedtls component is a wrapper for Espressifns fork of mbedtls. See its component CMakeLists.txt . The CMake variable ESP_PLATFORM is set to 1 whenever the ESP-IDF build system is being used. Tests such as if (ESP_PLATFORM) can be used in generic CMake code if special IDF-specific logic is required.
Using ESP-IDF components from external libraries
The above example assumes that the external library foo (or tinyxml in the case of the import_lib example) doesnnt need to use any ESP-IDF APIs apart from common APIs such as libc, libstdc++, etc. If the external library needs to use APIs provided by other ESP-IDF components, this needs to be specified in the external CMakeLists.txt file by adding a dependency on the library target idf::<componentname>. For example, in the foo/CMakeLists.txt file:
add_library(foo bar.c fizz.cpp buzz.cpp)
if(ESP_PLATFORM) # On ESP-IDF, bar.c needs to include esp_spi_flash.h from the spi_flash component target_link_libraries(foo PRIVATE idf::spi_flash)
endif()

4.5.19 Using Prebuilt Libraries with Components
Another possibility is that you have a prebuilt static library (.a file), built by some other build process. The ESP-IDF build system provides a utility function add_prebuilt_library for users to be able to easily import and use prebuilt libraries:
add_prebuilt_library(target_name lib_path [REQUIRES req1 req2 ...] [PRIV_REQUIRES req1 req2 ...])
where: · target_name- name that can be used to reference the imported library, such as when linking to other targets

Espressif Systems

1663

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· lib_path- path to prebuilt library; may be an absolute or relative path to the component directory Optional arguments REQUIRES and PRIV_REQUIRES specify dependency on other components. These have the same meaning as the arguments for idf_component_register. Take note that the prebuilt library must have been compiled for the same target as the consuming project. Configuration relevant to the prebuilt library must also match. If not paid attention to, these two factors may contribute to subtle bugs in the app. For an example, take a look at build_system/cmake/import_prebuilt.
4.5.20 Using ESP-IDF in Custom CMake Projects
ESP-IDF provides a template CMake project for easily creating an application. However, in some instances the user might already have an existing CMake project or may want to create a custom one. In these cases it is desirable to be able to consume IDF components as libraries to be linked to the userns targets (libraries/ executables). It is possible to do so by using the build system APIs provided by tools/cmake/idf.cmake. For example:
cmake_minimum_required(VERSION 3.5) project(my_custom_app C)
# Include CMake file that provides ESP-IDF CMake build system APIs. include($ENV{IDF_PATH}/tools/cmake/idf.cmake)
# Include ESP-IDF components in the build, may be thought as an equivalent of # add_subdirectory() but with some additional processing and magic for ESP-IDF build # specific build processes. idf_build_process(esp32)
# Create the project executable and plainly link the newlib component to it using # its alias, idf::newlib. add_executable(${CMAKE_PROJECT_NAME}.elf main.c) target_link_libraries(${CMAKE_PROJECT_NAME}.elf idf::newlib)
# Let the build system know what the project executable is to attach more targets, dependencies, etc. idf_build_executable(${CMAKE_PROJECT_NAME}.elf)
The example in build_system/cmake/idf_as_lib demonstrates the creation of an application equivalent to hello world application using a custom CMake project.
4.5.21 ESP-IDF CMake Build System API
idf-build-commands
idf_build_get_property(var property [GENERATOR_EXPRESSION])
Retrieve a build property property and store it in var accessible from the current scope. Specifying GENERATOR_EXPRESSION will retrieve the generator expression string for that property, instead of the actual value, which can be used with CMake commands that support generator expressions.
idf_build_set_property(property val [APPEND])
Set a build property property with value val. Specifying APPEND will append the specified value to the current value of the property. If the property does not previously exist or it is currently empty, the specified value becomes the first element/member instead.

Espressif Systems

1664

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
idf_build_component(component_dir)
Present a directory component_dir that contains a component to the build system. Relative paths are converted to absolute paths with respect to current directory. All calls to this command must be performed before idf_build_process.
This command does not guarantee that the component will be processed during build (see the COMPONENTS argument description for idf_build_process)
idf_build_process(target [PROJECT_DIR project_dir] [PROJECT_VER project_ver] [PROJECT_NAME project_name] [SDKCONFIG sdkconfig] [SDKCONFIG_DEFAULTS sdkconfig_defaults] [BUILD_DIR build_dir] [COMPONENTS component1 component2 ...])
Performs the bulk of the behind-the-scenes magic for including ESP-IDF components such as component configuration, libraries creation, dependency expansion and resolution. Among these functions, perhaps the most important from a userns perspective is the libraries creation by calling each componentns idf_component_register. This command creates the libraries for each component, which are accessible using aliases in the form idf::component_name. These aliases can be used to link the components to the userns own targets, either libraries or executables.
The call requires the target chip to be specified with target argument. Optional arguments for the call include:
· PROJECT_DIR - directory of the project; defaults to CMAKE_SOURCE_DIR · PROJECT_NAME - name of the project; defaults to CMAKE_PROJECT_NAME · PROJECT_VER - version/revision of the project; defaults to o1p · SDKCONFIG - output path of generated sdkconfig file; defaults to PROJECT_DIR/sdkconfig or
CMAKE_SOURCE_DIR/sdkconfig depending if PROJECT_DIR is set · SDKCONFIG_DEFAULTS - list of files containing default config to use in the build (list must contain full
paths); defaults to empty. For each value filename in the list, the config from file filename.target, if it exists, is also loaded. · BUILD_DIR - directory to place ESP-IDF build-related artifacts, such as generated binaries, text files, components; defaults to CMAKE_BINARY_DIR · COMPONENTS - select components to process among the components known by the build system (added via idf_build_component). This argument is used to trim the build. Other components are automatically added if they are required in the dependency chain, i.e. the public and private requirements of the components in this list are automatically added, and in turn the public and private requirements of those requirements, so on and so forth. If not specified, all components known to the build system are processed.
idf_build_executable(executable)
Specify the executable executable for ESP-IDF build. This attaches additional targets such as dependencies related to flashing, generating additional binary files, etc. Should be called after idf_build_process.
idf_build_get_config(var config [GENERATOR_EXPRESSION])
Get the value of the specified config. Much like build properties, specifying GENERATOR_EXPRESSION will retrieve the generator expression string for that config, instead of the actual value, which can be used with CMake commands that support generator expressions. Actual config values are only known after call to idf_build_process, however.
idf-build-properties
These are properties that describe the build. Values of build properties can be retrieved by using the build command idf_build_get_property. For example, to get the Python interpreter used for the build:

Espressif Systems

1665

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
idf_build_get_property(python PYTHON) message(STATUS "The Python intepreter is: ${python}")
· BUILD_DIR - build directory; set from idf_build_process BUILD_DIR argument · BUILD_COMPONENTS - list of components included in the build; set by idf_build_process · BUILD_COMPONENT_ALIASES - list of library alias of components included in the build; set by
idf_build_process · C_COMPILE_OPTIONS - compile options applied to all componentsnC source files · COMPILE_OPTIONS - compile options applied to all componentsnsource files, regardless of it being C or
C++ · COMPILE_DEFINITIONS - compile definitions applied to all component source files · CXX_COMPILE_OPTIONS - compile options applied to all componentsnC++ source files · EXECUTABLE - project executable; set by call to idf_build_executable · EXECUTABLE_NAME - name of project executable without extension; set by call to
idf_build_executable · EXECUTABLE_DIR - path containing the output executable · IDF_PATH - ESP-IDF path; set from IDF_PATH environment variable, if not, inferred from the location of
idf.cmake · IDF_TARGET - target chip for the build; set from the required target argument for idf_build_process · IDF_VER - ESP-IDF version; set from either a version file or the Git revision of the IDF_PATH repository · INCLUDE_DIRECTORIES - include directories for all component source files · KCONFIGS - list of Kconfig files found in components in build; set by idf_build_process · KCONFIG_PROJBUILDS - list of Kconfig.projbuild files found in components in build; set by
idf_build_process · PROJECT_NAME - name of the project; set from idf_build_process PROJECT_NAME argument · PROJECT_DIR - directory of the project; set from idf_build_process PROJECT_DIR argument · PROJECT_VER - version of the project; set from idf_build_process PROJECT_VER argument · PYTHON - Python interpreter used for the build; set from PYTHON environment variable if available, if not opythonpis used · SDKCONFIG - full path to output config file; set from idf_build_process SDKCONFIG argument · SDKCONFIG_DEFAULTS - list of files containing default config to use in the build; set from
idf_build_process SDKCONFIG_DEFAULTS argument · SDKCONFIG_HEADER - full path to C/C++ header file containing component configuration; set by
idf_build_process · SDKCONFIG_CMAKE - full path to CMake file containing component configuration; set by
idf_build_process · SDKCONFIG_JSON - full path to JSON file containing component configuration; set by
idf_build_process · SDKCONFIG_JSON_MENUS - full path to JSON file containing config menus; set by
idf_build_process
idf-component-commands
idf_component_get_property(var component property [GENERATOR_EXPRESSION])
Retrieve a specified componentns component property, property and store it in var accessible from the current scope. Specifying GENERATOR_EXPRESSION will retrieve the generator expression string for that property, instead of the actual value, which can be used with CMake commands that support generator expressions.
idf_component_set_property(component property val [APPEND])
Set a specified componentns component property, property with value val. Specifying APPEND will append the specified value to the current value of the property. If the property does not previously exist or it is currently empty, the specified value becomes the first element/member instead.

Espressif Systems

1666

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

idf_component_register([[SRCS src1 src2 ...] | [[SRC_DIRS dir1 dir2 ...] [EXCLUDE_ SRCS src1 src2 ...]]
[INCLUDE_DIRS dir1 dir2 ...] [PRIV_INCLUDE_DIRS dir1 dir2 ...] [REQUIRES component1 component2 ...] [PRIV_REQUIRES component1 component2 ...] [LDFRAGMENTS ldfragment1 ldfragment2 ...] [REQUIRED_IDF_TARGETS target1 target2 ...] [EMBED_FILES file1 file2 ...] [EMBED_TXTFILES file1 file2 ...] [KCONFIG kconfig] [KCONFIG_PROJBUILD kconfig_projbuild])
Register a component to the build system. Much like the project() CMake command, this should be called from the componentns CMakeLists.txt directly (not through a function or macro) and is recommended to be called before any other command. Here are some guidelines on what commands can not be called before idf_component_register:
· commands that are not valid in CMake script mode · custom commands defined in project_include.cmake · build system API commands except idf_build_get_property; although consider whether the property
may not have been set yet
Commands that set and operate on variables are generally okay to call before idf_component_register.
The arguments for idf_component_register include:
· SRCS - component source files used for creating a static library for the component; if not specified, component is a treated as a config-only component and an interface library is created instead.
· SRC_DIRS, EXCLUDE_SRCS - used to glob source files (.c, .cpp, .S) by specifying directories, instead of specifying source files manually via SRCS. Note that this is subject to the limitations of globbing in CMake. Source files specified in EXCLUDE_SRCS are removed from the globbed files.
· INCLUDE_DIRS - paths, relative to the component directory, which will be added to the include search path for all other components which require the current component
· PRIV_INCLUDE_DIRS - directory paths, must be relative to the component directory, which will be added to the include search path for this componentns source files only
· REQUIRES - public component requirements for the component · PRIV_REQUIRES - private component requirements for the component; ignored on config-only components · LDFRAGMENTS - component linker fragment files · REQUIRED_IDF_TARGETS - specify the only target the component supports · KCONFIG - override the default Kconfig file · KCONFIG_PROJBUILD - override the default Kconfig.projbuild file
The following are used for embedding data into the component, and is considered as source files when determining if a component is config-only. This means that even if the component does not specify source files, a static library is still created internally for the component if it specifies either:
· EMBED_FILES - binary files to be embedded in the component · EMBED_TXTFILES - text files to be embedded in the component
idf-component-properties
These are properties that describe a component. Values of component properties can be retrieved by using the build command idf_component_get_property. For example, to get the directory of the freertos component:
idf_component_get_property(dir freertos COMPONENT_DIR) message(STATUS "The 'freertos' component directory is: ${dir}")
· COMPONENT_ALIAS - alias for COMPONENT_LIB used for linking the component to external targets; set by idf_build_component and alias library itself is created by idf_component_register
· COMPONENT_DIR - component directory; set by idf_build_component

Espressif Systems

1667

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· COMPONENT_OVERRIDEN_DIR - contains the directory of the original component if this component overrides another component
· COMPONENT_LIB - name for created component static/interface library; set by idf_build_component and library itself is created by idf_component_register
· COMPONENT_NAME - name of the component; set by idf_build_component based on the component directory name
· COMPONENT_TYPE - type of the component, whether LIBRARY or CONFIG_ONLY. A component is of type LIBRARY if it specifies source files or embeds a file
· EMBED_FILES - list of files to embed in component; set from idf_component_register EMBED_FILES argument
· EMBED_TXTFILES - list of text files to embed in component; set from idf_component_register EMBED_TXTFILES argument
· INCLUDE_DIRS - list of component include directories; set from idf_component_register INCLUDE_DIRS argument
· KCONFIG - component Kconfig file; set by idf_build_component · KCONFIG_PROJBUILD - component Kconfig.projbuild; set by idf_build_component · LDFRAGMENTS - list of component linker fragment files; set from idf_component_register LD-
FRAGMENTS argument · PRIV_INCLUDE_DIRS - list of component private include directories; set from
idf_component_register PRIV_INCLUDE_DIRS on components of type LIBRARY · PRIV_REQUIRES - list of private component dependentices; set from idf_component_register
PRIV_REQUIRES argument · REQUIRED_IDF_TARGETS - list of targets the component supports; set from
idf_component_register EMBED_TXTFILES argument · REQUIRES - list of public component dependencies; set from idf_component_register REQUIRES
argument · SRCS - list of component source files; set from SRCS or SRC_DIRS/EXCLUDE_SRCS argument of
idf_component_register
4.5.22 File Globbing & Incremental Builds
The preferred way to include source files in an ESP-IDF component is to list them manually via SRCS argument to idf_component_register:
idf_component_register(SRCS library/a.c library/b.c platform/platform.c ...)
This preference reflects the CMake best practice of manually listing source files. This could, however, be inconvenient when there are lots of source files to add to the build. The ESP-IDF build system provides an alternative way for specifying source files using SRC_DIRS:
idf_component_register(SRC_DIRS library platform ...)
This uses globbing behind the scenes to find source files in the specified directories. Be aware, however, that if a new source file is added and this method is used, then CMake wonnt know to automatically re-run and this file wonnt be added to the build.
The trade-off is acceptable when younre adding the file yourself, because you can trigger a clean build or run idf. py reconfigure to manually re-run CMake. However, the problem gets harder when you share your project with others who may check out a new version using a source control tool like Gitl
For components which are part of ESP-IDF, we use a third party Git CMake integration module (/tools/cmake/third_party/GetGitRevisionDescription.cmake) which automatically re-runs CMake any time the repository commit changes. This means if you check out a new ESP-IDF version, CMake will automatically rerun.
For project components (not part of ESP-IDF), there are a few different options:

Espressif Systems

1668

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

· If keeping your project file in Git, ESP-IDF will automatically track the Git revision and re-run CMake if the revision changes.
· If some components are kept in a third git repository (not the project repository or ESP-IDF repository), you can add a call to the git_describe function in a component CMakeLists file in order to automatically trigger re-runs of CMake when the Git revision changes.
· If not using Git, remember to manually run idf.py reconfigure whenever a source file may change. · To avoid this problem entirely, use SRCS argument to idf_component_register to list all source files
in project components.
The best option will depend on your particular project and its users.
4.5.23 Build System Metadata
For integration into IDEs and other build systems, when CMake runs the build process generates a number of metadata files in the build/ directory. To regenerate these files, run cmake or idf.py reconfigure (or any other idf.py build command).
· compile_commands.json is a standard format JSON file which describes every source file which is compiled in the project. A CMake feature generates this file, and many IDEs know how to parse it.
· project_description.json contains some general information about the ESP-IDF project, configured paths, etc.
· flasher_args.json contains esptool.py arguments to flash the projectns binary files. There are also flash_*_args files which can be used directly with esptool.py. See Flash arguments.
· CMakeCache.txt is the CMake cache file which contains other information about the CMake process, toolchain, etc.
· config/sdkconfig.json is a JSON-formatted version of the project configuration values. · config/kconfig_menus.json is a JSON-formatted version of the menus shown in menuconfig, for
use in external IDE UIs.
JSON Configuration Server
A tool called confserver.py is provided to allow IDEs to easily integrate with the configuration system logic. confserver.py is designed to run in the background and interact with a calling process by reading and writing JSON over process stdin & stdout.
You can run confserver.py from a project via idf.py confserver or ninja confserver, or a similar target triggered from a different build generator.
For more information about confserver.py, see tools/kconfig_new/README.md.
4.5.24 Build System Internals
Build Scripts
The listfiles for the ESP-IDF build system reside in /tools/cmake. The modules which implement core build system functionality are as follows:
· build.cmake - Build related commands i.e. build initialization, retrieving/setting build properties, build processing.
· component.cmake - Component related commands i.e. adding components, retrieving/setting component properties, registering components.
· kconfig.cmake - Generation of configuration files (sdkconfig, sdkconfig.h, sdkconfig.cmake, etc.) from Kconfig files.
· ldgen.cmake - Generation of final linker script from linker fragment files. · target.cmake - Setting build target and toolchain file. · utilities.cmake - Miscellaneous helper commands.
Aside from these files, there are two other important CMake scripts in /tools/cmake:

Espressif Systems

1669

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· idf.cmake - Sets up the build and includes the core modules listed above. Included in CMake projects in order to access ESP-IDF build system functionality.
· project.cmake - Includes idf.cmake and provides a custom project() command that takes care of all the heavy lifting of building an executable. Included in the top-level CMakeLists.txt of standard ESP-IDF projects.
The rest of the files in /tools/cmake are support or third-party scripts used in the build process.
Build Process
This section describes the standard ESP-IDF application build process. The build process can be broken down roughly into four phases:

Fig. 3: ESP-IDF Build System Process
Initialization This phase sets up necessary parameters for the build.
· Upon inclusion of idf.cmake in project.cmake, the following steps are performed: ­ Set IDF_PATH from environment variable or inferred from path to project.cmake included in the top-level CMakeLists.txt. ­ Add /tools/cmake to CMAKE_MODULE_PATH and include core modules plus the various helper/third-party scripts. ­ Set build tools/executables such as default Python interpreter. ­ Get ESP-IDF git revision and store as IDF_VER. ­ Set global build specifications i.e. compile options, compile definitions, include directories for all components in the build. ­ Add components in components to the build.
· The initial part of the custom project() command performs the following steps: ­ Set IDF_TARGET from environment variable or CMake cache and the corresponding CMAKE_TOOLCHAIN_FILE to be used. ­ Add components in EXTRA_COMPONENTS_DIRS to the build. ­ Prepare arguments for calling command idf_build_process() from variables such as COMPONENTS/EXCLUDE_COMPONENTS, SDKCONFIG, SDKCONFIG_DEFAULTS.
The call to idf_build_process() command marks the end of this phase.
Enumeration
This phase builds a final list of components to be processed in the build, and is performed in the first half of idf_build_process().
· Retrieve each componentns public and private requirements. A child process is created which executes each componentns CMakeLists.txt in script mode. The values of idf_component_register REQUIRES and PRIV_REQUIRES argument is returned to the parent build process. This is called early expansion. The variable CMAKE_BUILD_EARLY_EXPANSION is defined during this step.
· Recursively include components based on public and private requirements.

Espressif Systems

1670

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Processing
This phase processes the components in the build, and is the second half of idf_build_process().
· Load project configuration from sdkconfig file and generate an sdkconfig.cmake and sdkconfig.h header. These define configuration variables/macros that are accessible from the build scripts and C/C++ source/header files, respectively.
· Include each componentns project_include.cmake. · Add each component as a subdirectory, processing its CMakeLists.txt. The component CMake-
Lists.txt calls the registration command, idf_component_register which adds source files, include directories, creates component library, links dependencies, etc.
Finalization
This phase is everything after idf_build_process().
· Create executable and link the component libraries to it. · Generate project metadata files such as project_description.json and display relevant information
about the project built.
Browse /tools/cmake/project.cmake for more details.
4.5.25 Migrating from ESP-IDF GNU Make System
Some aspects of the CMake-based ESP-IDF build system are very similar to the older GNU Make-based system. The developer needs to provide values the include directories, source files etc. There is a syntactical difference, however, as the developer needs to pass these as arguments to the registration command, idf_component_register.
Automatic Conversion Tool
An automatic project conversion tool is available in tools/cmake/convert_to_cmake.py in ESP-IDF v4.x releases. The script was removed in v5.0 because of its make build system dependency.
No Longer Available in CMake
Some features are significantly different or removed in the CMake-based system. The following variables no longer exist in the CMake-based build system:
· COMPONENT_BUILD_DIR: Use CMAKE_CURRENT_BINARY_DIR instead. · COMPONENT_LIBRARY: Defaulted to $(COMPONENT_NAME).a, but the library name could be overriden
by the component. The name of the component library can no longer be overriden by the component. · CC, LD, AR, OBJCOPY: Full paths to each tool from the gcc xtensa cross-toolchain. Use
CMAKE_C_COMPILER, CMAKE_C_LINK_EXECUTABLE, CMAKE_OBJCOPY, etc instead. Full list here. · HOSTCC, HOSTLD, HOSTAR: Full names of each tool from the host native toolchain. These are no longer
provided, external projects should detect any required host toolchain manually. · COMPONENT_ADD_LDFLAGS: Used to override linker flags. Use the CMake target_link_libraries command
instead. · COMPONENT_ADD_LINKER_DEPS: List of files that linking should depend on. target_link_libraries will
usually infer these dependencies automatically. For linker scripts, use the provided custom CMake function target_linker_scripts. · COMPONENT_SUBMODULES: No longer used, the build system will automatically enumerate all submodules in the ESP-IDF repository. · COMPONENT_EXTRA_INCLUDES: Used to be an alternative to COMPONENT_PRIV_INCLUDEDIRS for absolute paths. Use PRIV_INCLUDE_DIRS argument to idf_component_register for all cases now (can be relative or absolute). · COMPONENT_OBJS: Previously, component sources could be specified as a list of object files. Now they can be specified as a list of source files via SRCS argument to idf_component_register.

Espressif Systems

1671

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

· COMPONENT_OBJEXCLUDE: Has been replaced with EXCLUDE_SRCS argument to idf_component_register. Specify source files (as absolute paths or relative to component directory), instead.
· COMPONENT_EXTRA_CLEAN: Set property ADDITIONAL_MAKE_CLEAN_FILES instead but note CMake has some restrictions around this functionality.
· COMPONENT_OWNBUILDTARGET & COMPONENT_OWNCLEANTARGET: Use CMake ExternalProject instead. See Fully Overriding The Component Build Process for full details.
· COMPONENT_CONFIG_ONLY: Call idf_component_register without any arguments instead. See Configuration-Only Components.
· CFLAGS, CPPFLAGS, CXXFLAGS: Use equivalent CMake commands instead. See Controlling Component Compilation.
No Default Values
Unlike in the legacy Make-based build system, the following have no default values:
· Source directories (COMPONENT_SRCDIRS variable in Make, SRC_DIRS argument to idf_component_register in CMake)
· Include directories (COMPONENT_ADD_INCLUDEDIRS variable in Make, INCLUDE_DIRS argument to idf_component_register in CMake)
No Longer Necessary
· In the legacy Make-based build system, it is required to also set COMPONENT_SRCDIRS if COMPONENT_SRCS is set. In CMake, the equivalent is not necessary i.e. specifying SRC_DIRS to idf_component_register if SRCS is also specified (in fact, SRCS is ignored if SRC_DIRS is specified).
Flashing from make
make flash and similar targets still work to build and flash. However, project sdkconfig no longer specifies serial port and baud rate. Environment variables can be used to override these. See Flashing with ninja or make for more details.

4.6 Deep Sleep Wake Stubs
ESP32-S3 supports running aodeep sleep wake stubpwhen coming out of deep sleep. This function runs immediately as soon as the chip wakes up - before any normal initialisation, bootloader, or ESP-IDF code has run. After the wake stub runs, the SoC can go back to sleep or continue to start ESP-IDF normally.
Deep sleep wake stub code is loaded into oRTC Fast Memorypand any data which it uses must also be loaded into RTC memory. RTC memory regions hold their contents during deep sleep.

4.6.1 Rules for Wake Stubs
Wake stub code must be carefully written:
· As the SoC has freshly woken from sleep, most of the peripherals are in reset states. The SPI flash is unmapped. · The wake stub code can only call functions implemented in ROM or loaded into RTC Fast Memory (see below.) · The wake stub code can only access data loaded in RTC memory. All other RAM will be unintiailised and
have random contents. The wake stub can use other RAM for temporary storage, but the contents will be overwritten when the SoC goes back to sleep or starts ESP-IDF. · RTC memory must include any read-only data (.rodata) used by the stub. · Data in RTC memory is initialised whenever the SoC restarts, except when waking from deep sleep. When waking from deep sleep, the values which were present before going to sleep are kept.

Espressif Systems

1672

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

· Wake stub code is a part of the main esp-idf app. During normal running of esp-idf, functions can call the wake stub functions or access RTC memory. It is as if these were regular parts of the app.
4.6.2 Implementing A Stub
The wake stub in esp-idf is called esp_wake_deep_sleep(). This function runs whenever the SoC wakes from deep sleep. There is a default version of this function provided in esp-idf, but the default function is weak-linked so if your app contains a function named esp_wake_deep_sleep() then this will override the default. If supplying a custom wake stub, the first thing it does should be to call esp_default_wake_deep_sleep(). It is not necessary to implement esp_wake_deep_sleep() in your app in order to use deep sleep. It is only necessary if you want to have special behaviour immediately on wake. If you want to swap between different deep sleep stubs at runtime, it is also possible to do this by calling the esp_set_deep_sleep_wake_stub() function. This is not necessary if you only use the default esp_wake_deep_sleep() function. All of these functions are declared in the esp_sleep.h header under components/esp32s3.
4.6.3 Loading Code Into RTC Memory
Wake stub code must be resident in RTC Fast Memory. This can be done in one of two ways. The first way is to use the RTC_IRAM_ATTR attribute to place a function into RTC memory:
void RTC_IRAM_ATTR esp_wake_deep_sleep(void) { esp_default_wake_deep_sleep(); // Add additional functionality here
}
The second way is to place the function into any source file whose name starts with rtc_wake_stub. Files names rtc_wake_stub* have their contents automatically put into RTC memory by the linker. The first way is simpler for very short and simple code, or for source files where you want to mix onormalpand oRTCpcode. The second way is simpler when you want to write longer pieces of code for RTC memory.
4.6.4 Loading Data Into RTC Memory
Data used by stub code must be resident in RTC memory. The data can be placed in RTC Fast memory or in RTC Slow memory which is also used by the ULP. Specifying this data can be done in one of two ways: The first way is to use the RTC_DATA_ATTR and RTC_RODATA_ATTR to specify any data (writeable or read-only, respectively) which should be loaded into RTC memory:
RTC_DATA_ATTR int wake_count;
void RTC_IRAM_ATTR esp_wake_deep_sleep(void) { esp_default_wake_deep_sleep(); static RTC_RODATA_ATTR const char fmt_str[] = "Wake count %d\n"; esp_rom_printf(fmt_str, wake_count++);
}
The RTC memory area where this data will be placed can be configured via menuconfig option named CONFIG_ESP32S3_RTCDATA_IN_FAST_MEM. This option allows to keep slow memory area for ULP programs and once it is enabled the data marked with RTC_DATA_ATTR and RTC_RODATA_ATTR are placed in the RTC fast memory segment otherwise it goes to RTC slow memory (default option). This option depends on the CONFIG_FREERTOS_UNICORE because RTC fast memory can be accessed only by PRO_CPU.

Espressif Systems

1673

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
The attributes RTC_FAST_ATTR and RTC_SLOW_ATTR can be used to specify data that will be force placed into RTC_FAST and RTC_SLOW memory respectively. Any access to data marked with RTC_FAST_ATTR is allowed by PRO_CPU only and it is responsibility of user to make sure about it. Unfortunately, any string constants used in this way must be declared as arrays and marked with RTC_RODATA_ATTR, as shown in the example above. The second way is to place the data into any source file whose name starts with rtc_wake_stub. For example, the equivalent example in rtc_wake_stub_counter.c:
int wake_count;
void RTC_IRAM_ATTR esp_wake_deep_sleep(void) { esp_default_wake_deep_sleep(); esp_rom_printf("Wake count %d\n", wake_count++);
}
The second way is a better option if you need to use strings, or write other more complex code. To reduce wake-up time use the CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP Kconfig option, see more information in Fast boot from Deep Sleep.
4.6.5 CRC Check For Wake Stubs
During deep sleep, only the wake stubs area of RTC Fast memory is validated with CRC. When ESP32-S3 wakes up from deep sleep, the wake stubs area is validated again. If the validation passes, the wake stubs code will be executed. Otherwise, the normal initialization, bootloader, and esp-idf codes will be executed.
Note: When the CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP option is enabled, all the RTC fast memory except the wake stubs area is added to the heap.

4.7 Device Firmware Upgrade through USB

Device Firmware Upgrade (DFU) is a mechanism for upgrading the firmware of devices through Universal Serial Bus (USB). DFU is supported by ESP32-S3 chips. The necessary connections for the USB peripheral are shown in the following table.

GPIO 20 19 GND +5V

USB D+ (green) D- (white) GND (black) +5V (red)

By default, USB_SERIAL_JTAG module is connected to the internal PHY of the ESP32-S3, while USB_OTG peripheral can be used only if the external USB PHY is connected. Since DFU mode is provided via USB_OTG peripheral, it cannot be used through the internal PHY in this configuration.
You can permanently switch the internal USB PHY to work with USB_OTG peripheral instead of USB_SERIAL_JTAG by burning USB_PHY_SEL eFuse. See ESP32-S3 Technical Reference Manual for more details about USB_SERIAL_JTAG and USB_OTG.

Note: The ESP32-S3 chip needs to be in bootloader mode for the detection as a DFU device and flashing. This can be achieved by pulling GPIO0 down (e.g. pressing the BOOT button), pulsing RESET down for a moment and releasing GPIO0.

Espressif Systems

1674

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Warning: Some cables are wired up with non-standard colors and some drivers are able to work with swapped D+ and D- connections. Please try to swap the cables connecting to D+ and D- if your device is not detected.
The software requirements of DFU are included in Step 1. Install prerequisites of the Getting Started Guide. Section Building the DFU Image describes how to build firmware for DFU with ESP-IDF and Section Flashing the Chip with the DFU Image deals with flashing the firmware.
4.7.1 Building the DFU Image
The DFU image can be created by running: idf.py dfu
which creates dfu.bin in the build directory.
Note: Donnt forget to set the target chip by idf.py set-target before running idf.py dfu. Otherwise, you might create an image for a different chip or receive an error message something like unknown target 'dfu'.

4.7.2 Flashing the Chip with the DFU Image
The DFU image is downloaded into the chip by running: idf.py dfu-flash
which relies on dfu-util. Please see Step 1. Install prerequisites for installing dfu-util. dfu-util needs additional setup for USB drivers (Windows only) or setting up an udev rule (Linux only). Mac OS users should be able to use dfu-util without further setup. If there are more boards with the same chip connected then idf.py dfu-list can be used to list the available devices, for example: Found Runtime: [303a:0002] ver=0723, devnum=4, cfg=1, intf=2, path="1-10", alt=0, name="UNKNOWN", serial="0" Found Runtime: [303a:0002] ver=0723, devnum=6, cfg=1, intf=2, path="1-2", alt=0, name="UNKNOWN", serial="0"
Consequently, the desired device can be selected for flashing by the --path argument. For example, the devices listed above can be flashed individually by the following commands: idf.py dfu-flash --path 1-10 idf.py dfu-flash --path 1-2
Note: The vendor and product identificators are set based on the selected chip target by the idf.py set-target command and it is not selectable during the idf.py dfu-flash call.
See Common errors and known issues and their solutions.
udev rule (Linux only)
udev is a device manager for the Linux kernel. It allows us to run dfu-util (and idf.py dfu-flash) without sudo for gaining access to the chip.

Espressif Systems

1675

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Create file /etc/udev/rules.d/40-dfuse.rules with the following content:
SUBSYSTEMS=="usb", ATTRS{idVendor}=="303a", ATTRS{idProduct}=="00??", GROUP= "plugdev", MODE="0666"
Note: Please check the output of command groups. The user has to be a member of the GROUP specified above. You may use some other existing group for this purpose (e.g. uucp on some systems instead of plugdev) or create a new group for this purpose.
Restart your computer so the previous setting could take into affect or run sudo udevadm trigger to force manually udev to trigger your new rule.
USB drivers (Windows only)
dfu-util uses libusb to access the device. You have to register on Windows the device with the WinUSB driver. Please see the libusb wiki for more details. The drivers can be installed by the Zadig tool. Please make sure that the device is in download mode before running the tool and that it detects the ESP32-S3 device before installing the drivers. The Zadig tool might detect several USB interfaces of ESP32-S3. Please install the WinUSB driver for only that interface for which there is no driver installed (probably it is Interface 2) and donnt re-install the driver for the other interface.
Warning: The manual installation of the driver in Device Manager of Windows is not recommended because the flashing might not work properly.
Common errors and known issues
· dfu-util: command not found might indicate that the tool hasnnt been installed or is not available from the terminal. An easy way of checking the tool is running dfu-util --version. Please see Step 1. Install prerequisites for installing dfu-util.
· The reason for No DFU capable USB device available could be that the USB driver wasnnt properly installed on Windows (see USB drivers (Windows only)), udev rule was not setup on Linux (see udev rule (Linux only)) or the device isnnt in bootloader mode.
· Flashing with dfu-util on Windows fails on the first attempt with error Lost device after RESET?. Please retry the flashing and it should succeed the next time.
4.8 Error Handling
4.8.1 Overview
Identifying and handling run-time errors is important for developing robust applications. There can be multiple kinds of run-time errors:
· Recoverable errors: ­ Errors indicated by functions through return values (error codes) ­ C++ exceptions, thrown using throw keyword
· Unrecoverable (fatal) errors: ­ Failed assertions (using assert macro and equivalent methods, see Assertions) and abort() calls. ­ CPU exceptions: access to protected regions of memory, illegal instruction, etc. ­ System level checks: watchdog timeout, cache access error, stack overflow, stack smashing, heap corruption, etc.

Espressif Systems

1676

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

This guide explains ESP-IDF error handling mechanisms related to recoverable errors, and provides some common error handling patterns. For instructions on diagnosing unrecoverable errors, see Fatal Errors.
4.8.2 Error codes
The majority of ESP-IDF-specific functions use esp_err_t type to return error codes. esp_err_t is a signed integer type. Success (no error) is indicated with ESP_OK code, which is defined as zero. Various ESP-IDF header files define possible error codes using preprocessor defines. Usually these defines start with ESP_ERR_ prefix. Common error codes for generic failures (out of memory, timeout, invalid argument, etc.) are defined in esp_err.h file. Various components in ESP-IDF may define additional error codes for specific situations. For the complete list of error codes, see Error Code Reference.
4.8.3 Converting error codes to error messages
For each error code defined in ESP-IDF components, esp_err_t value can be converted to an error code name using esp_err_to_name() or esp_err_to_name_r() functions. For example, passing 0x101 to esp_err_to_name() will return oESP_ERR_NO_MEMpstring. Such strings can be used in log output to make it easier to understand which error has happened. Additionally, esp_err_to_name_r() function will attempt to interpret the error code as a standard POSIX error code, if no matching ESP_ERR_ value is found. This is done using strerror_r function. POSIX error codes (such as ENOENT, ENOMEM) are defined in errno.h and are typically obtained from errno variable. In ESP-IDF this variable is thread-local: multiple FreeRTOS tasks have their own copies of errno. Functions which set errno only modify its value for the task they run in. This feature is enabled by default, but can be disabled to reduce application binary size. See CONFIG_ESP_ERR_TO_NAME_LOOKUP. When this feature is disabled, esp_err_to_name() and esp_err_to_name_r() are still defined and can be called. In this case, esp_err_to_name() will return UNKNOWN ERROR, and esp_err_to_name_r() will return Unknown error 0xXXXX(YYYYY), where 0xXXXX and YYYYY are the hexadecimal and decimal representations of the error code, respectively.
4.8.4 ESP_ERROR_CHECK macro
ESP_ERROR_CHECK() macro serves similar purpose as assert, except that it checks esp_err_t value rather than a bool condition. If the argument of ESP_ERROR_CHECK() is not equal ESP_OK, then an error message is printed on the console, and abort() is called. Error message will typically look like this:
ESP_ERROR_CHECK failed: esp_err_t 0x107 (ESP_ERR_TIMEOUT) at 0x400d1fdf
file: "/Users/user/esp/example/main/main.c" line 20 func: app_main expression: sdmmc_card_init(host, &card)
Backtrace: 0x40086e7c:0x3ffb4ff0 0x40087328:0x3ffb5010 0x400d1fdf:0x3ffb5030 0x400d0816:0x3ffb5050

Note: If IDF monitor is used, addresses in the backtrace will be converted to file names and line numbers.

· The first line mentions the error code as a hexadecimal value, and the identifier used for this error in source code. The latter depends on CONFIG_ESP_ERR_TO_NAME_LOOKUP option being set. Address in the program where error has occured is printed as well.

Espressif Systems

1677

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

· Subsequent lines show the location in the program where ESP_ERROR_CHECK() macro was called, and the expression which was passed to the macro as an argument.
· Finally, backtrace is printed. This is part of panic handler output common to all fatal errors. See Fatal Errors for more information about the backtrace.

4.8.5 ESP_ERROR_CHECK_WITHOUT_ABORT macro
ESP_ERROR_CHECK_WITHOUT_ABORT() macro serves similar purpose as ESP_ERROR_CHECK, except that it wonnt call abort().

4.8.6 ESP_RETURN_ON_ERROR macro
ESP_RETURN_ON_ERROR() macro checks the error code, if the error code is not equal ESP_OK, it prints the message and returns.

4.8.7 ESP_GOTO_ON_ERROR macro
ESP_GOTO_ON_ERROR() macro checks the error code, if the error code is not equal ESP_OK, it prints the message, sets the local variable ret to the code, and then exits by jumping to goto_tag.

4.8.8 ESP_RETURN_ON_FALSE macro
ESP_RETURN_ON_FALSE() macro checks the condition, if the condition is not equal true, it prints the message and returns with the supplied err_code.

4.8.9 ESP_GOTO_ON_FALSE macro
ESP_GOTO_ON_FALSE() macro checks the condition, if the condition is not equal true, it prints the message, sets the local variable ret to the supplied err_code, and then exits by jumping to goto_tag.

4.8.10 CHECK MACROS Examples

Some examples: static const char* TAG = "Test";

esp_err_t test_func(void) {
esp_err_t ret = ESP_OK;

ESP_ERROR_CHECK(x);

// err message

printed if `x` is not `ESP_OK`, and then `abort()`.

ESP_ERROR_CHECK_WITHOUT_ABORT(x);

// err message

printed if `x` is not `ESP_OK`, without `abort()`.

ESP_RETURN_ON_ERROR(x, TAG, "fail reason 1");

// err message

printed if `x` is not `ESP_OK`, and then function returns with code `x`.

ESP_GOTO_ON_ERROR(x, err, TAG, "fail reason 2");

// err message

printed if `x` is not `ESP_OK`, `ret` is set to `x`, and then jumps to `err`.

ESP_RETURN_ON_FALSE(a, err_code, TAG, "fail reason 3");

// err message

printed if `a` is not `true`, and then function returns with code `err_code`.

ESP_GOTO_ON_FALSE(a, err_code, err, TAG, "fail reason 4"); // err message

printed if `a` is not `true`, `ret` is set to `err_code`, and then jumps to

`err`.

(continues on next page)

Espressif Systems

1678

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

err: // clean up return ret;
}

(continued from previous page)

Note: If the option CONFIG_COMPILER_OPTIMIZATION_CHECKS_SILENT in Kconfig is enabled, the err message will be discarded, while the other action works as is.
The ESP_RETURN_XX and ESP_GOTO_xx macros cannt be called from ISR. While there are xx_ISR versions for each of them, e.g., ESP_RETURN_ON_ERROR_ISR, these macros could be used in ISR.

4.8.11 Error handling patterns
1. Attempt to recover. Depending on the situation, this might mean to retry the call after some time, or attempt to de-initialize the driver and re-initialize it again, or fix the error condition using an out-of-band mechanism (e.g reset an external peripheral which is not responding). Example:
esp_err_t err; do {
err = sdio_slave_send_queue(addr, len, arg, timeout); // keep retrying while the sending queue is full } while (err == ESP_ERR_TIMEOUT); if (err != ESP_OK) { // handle other errors }
2. Propagate the error to the caller. In some middleware components this means that a function must exit with the same error code, making sure any resource allocations are rolled back. Example:
sdmmc_card_t* card = calloc(1, sizeof(sdmmc_card_t)); if (card == NULL) {
return ESP_ERR_NO_MEM; } esp_err_t err = sdmmc_card_init(host, &card); if (err != ESP_OK) {
// Clean up free(card); // Propagate the error to the upper layer (e.g. to notify the user). // Alternatively, application can define and return custom error code. return err; }
3. Convert into unrecoverable error, for example using ESP_ERROR_CHECK. See ESP_ERROR_CHECK macro section for details. Terminating the application in case of an error is usually undesirable behaviour for middleware components, but is sometimes acceptable at application level. Many ESP-IDF examples use ESP_ERROR_CHECK to handle errors from various APIs. This is not the best practice for applications, and is done to make example code more concise. Example:
ESP_ERROR_CHECK(spi_bus_initialize(host, bus_config, dma_chan));

Espressif Systems

1679

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.8.12 C++ Exceptions
Support for C++ Exceptions in ESP-IDF is disabled by default, but can be enabled using CONFIG_COMPILER_CXX_EXCEPTIONS option. Enabling exception handling normally increases application binary size by a few kB. Additionally it may be necessary to reserve some amount of RAM for exception emergency pool. Memory from this pool will be used if it is not possible to allocate exception object from the heap. Amount of memory in the emergency pool can be set using CONFIG_COMPILER_CXX_EXCEPTIONS_EMG_POOL_SIZE variable. If an exception is thrown, but there is no catch block, the program will be terminated by abort function, and backtrace will be printed. See Fatal Errors for more information about backtraces. See cxx/exceptions for an example of C++ exception handling.
4.9 ESP-BLE-MESH
Bluetooth® mesh networking enables many-to-many (m:m) device communications and is optimized for creating large-scale device networks. Devices may relay data to other devices not in direct radio range of the originating device. In this way, mesh networks can span very large physical areas and contain large numbers of devices. It is ideally suited for building automation, sensor networks, and other IoT solutions where tens, hundreds, or thousands of devices need to reliably and securely communicate with one another. Bluetooth mesh is not a wireless communications technology, but a networking technology. This technology is dependent upon Bluetooth Low Energy (BLE) - a wireless communications protocol stack. Built on top of Zephyr Bluetooth Mesh stack, the ESP-BLE-MESH implementation supports device provisioning and node control. It also supports such node features as Proxy, Relay, Low power and Friend. Please see the ESP-BLE-MESH Architecture for information about the implementation of ESP-BLE-MESH architecture and ESP-BLE-MESH API Reference for information about respective API. ESP-BLE-MESH is implemented and certified based on the latest Mesh Profile v1.0.1, users can refer here for the certification details of ESP-BLE-MESH.
Note: If you are looking for Wi-Fi based implementation of mesh for ESP32-S3, please check another product by Espressif called ESP-WIF-MESH. For more information and documentation see ESP-WIFI-MESH.

4.9.1 Getting Started with ESP-BLE-MESH
This section is intended to help you get started with ESP-BLE-MESH for the hardware based on the ESP32-S3 chip by Espressif.
We are going to demonstrate process of setting and operation of a small ESP-BLE-MESH network of three nodes. This process will cover device provisioning and node configuration, and then sending on/off commands to Generic OnOff Server Models on specific nodes.
If you are new to ESP-IDF, please first set up development environment, compile , flash and run example application following top level ESP-IDF Get Started documentation.

What You Need
Hardware: · Three ESP32-S3 boards, see options. · USB cables to connect the boards. · Computer configured with ESP-IDF.

Espressif Systems

1680

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· Mobile phone or tablet running Android or iOS. Software:
· Example application bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server code to load to the ESP32-S3 boards.
· Mobile App: nRF Mesh for Android or iOS. Optionally you can use some other Apps: ­ EspBleMesh Android App ­ Silicon Labs Android or iOS App
Installation Step by Step
This is a detailed roadmap to walk you through the installation process.
Step 1. Check Hardware Both ESP32-DevKitC and ESP-WROVER-KIT development boards are supported for ESP-BLE-MESH implementation. You can choose particular board through menuconfig: idf.py menuconfig > Example Configuration > Board selection for ESP-BLE-MESH
Note: If you plan to use ESP32-DevKitC, connect a RGB LED to GPIO pins 25, 26 and 27.
Step 2. Configure Software Enter the bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server example directory, run idf.py menuconfig to select your board and then run idf.py build to compile the example.
Step 3. Upload Application to Nodes After the bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server example is compiled successfully, users can run idf.py flash to upload the same generated binary files into each of the three development boards. Once boards are powered on, the RGB LED on each board should turn GREEN.
Step 4. Provision Nodes In this section, we will use the nRF Mesh Android App to demonstrate how to provision an unprovisioned device. Users can also get its iOS version from the App Store.
4.1 Scanner The Scanner is Appns functionality to search for unprovisioned devices in range. Open the App, press Scanner at the bottom and the search will start. After a short while we should see three unprovisioned devices displayed.
4.2 Identify Users can select any unprovisioned device, then the App will try to set up a connection with the selected device. After the BLE connection is established successfully (sometimes users need to try multiple times to get connected), and proper ESP-BLE-MESH GATT Service is discovered, users can see the IDENTIFY interface button on the screen. The IDENTIFY operation can be used to tell users which device is going to be provisioned.
Note: The IDENTIFY operation also needs some cooperation on the device side, then users can see which device is in the provisioning process. Currently when pressing the IDENTIFY interface button, no signs can been seen from the device except from the log on the serial monitor.
After the IDENTIFY interface button is pressed, users can see the PROVISION interface button.

Espressif Systems

1681

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 4: ESP-BLE-MESH Devices Power On

Espressif Systems

Fig. 5: nRF Mesh - Scanner

1682

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 6: nRF Mesh - IDENTIFY - PROVISION
4.3 Provision Then, the App will try to provision the unprovisioned device. When the device is provisioned successfully, the RGB LED on the board will turn off, and the App will implement the following procedures:
1. Disconnect with the node 2. Try to reconnect with the node 3. Connect successfully and discover ESP-BLE-MESH GATT Service 4. Get Composition Data of the node and add AppKey to it
When all the procedures are finished, the node is configured properly. And after pressing OK, users can see that unicast address is assigned, and Composition Data of the node is decoded successfully.
Sometimes in procedure 2, the App may fail to reconnect with the node. In this case, after pressing OK, users can see that only unicast address of the node has been assigned, but no Composition Data has been got. Then users need to press CONNECT on the top right, and the previously provisioned node will be displayed on the screen, and users need to choose it and try to connect with the node.
After connecting successfully, the App will show the interface buttons which can be used to get Composition Data and add AppKey.
If the device is the second or the third one which has been provisioned by the App, and after pressing CONNECT, users can see two or three nodes on the screen. In this situation, users can choose any device to connect with, once succeed then go back to the main screen to choose the node which needs to be configured.
Here an example of three devices listed.
· The left picture shows that the third device is provisioned successfully, but the App failed to connect with it. When it tries to reconnect with the third node, three nodes are displayed on the App.
· The right picture shows that after connecting with any node successfully, the App displays the information of the three nodes. Users can see that the App has got the Composition Data of the first and the second nodes, but for the third one, only the unicast address has been assigned to it while the Composition Data is unknown.
4.4 Configuration When provisioning and initial configuration are finished, users can start to configure the node, such as binding AppKey with each model with the elements, setting publication information to it, etc.

Espressif Systems

1683

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides Fig. 7: nRF Mesh - Configuration Complete

Espressif Systems

Fig. 8: nRF Mesh - Initial Configuration Failed

1684

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides Fig. 9: nRF Mesh - Reconnect - Initial Configuration

Espressif Systems

Fig. 10: nRF Mesh - Reconnect - Three Nodes

1685

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 11: nRF Mesh - Model Bind AppKey
Example below shows how to bind AppKey with Generic OnOff Server Model within the Primary Element.
Note: No need to bind AppKey with the Configuration Server Model, since it only uses the DevKey to encrypt messages in the Upper Transport Layer.

Step 5. Operate Network After all the Generic OnOff Server Models within the three elements are bound with proper AppKey, users can use the App to turn on/off the RGB LED.
In the bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server example, the first Generic OnOff Server Model is used to control the RED color, the second one is used to control the GREEN color and the third one is used to control the BLUE color.
The following screenshot shows different board with different color on.
Note: For nRF Mesh iOS App [version 1.0.4], when the node contains more than one element, the App is not behaving correctly. If users try to turn on/off the second or the third Generic OnOff Server Model, the message sent by the App is destinated to the first Generic OnOff Server Model within the Primary Element.

4.9.2 ESP-BLE-MESH Examples
· ESP-BLE-MESH Node OnOff Server - shows the use of ESP-BLE-MESH as a node having a Configuration Server model and a Generic OnOff Server model. A ESP-BLE-MESH Provisioner can then provision the unprovisioned device and control a RGB LED representing on/off state, see example code .
· ESP-BLE-MESH Node OnOff Client - shows how a Generic OnOff Client model works within a node. The node has a Configuration Server model and a Generic OnOff Client model, see example code .
· ESP-BLE-MESH Provisioner - shows how a device can act as an ESP-BLE-MESH Provisioner to provision devices. The Provisioner has a Configuration Server model, a Configuration Client model and a Generic OnOff Client model, see example code .

Espressif Systems

1686

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides Fig. 12: nRF Mesh - Generic OnOff Control

Espressif Systems

Fig. 13: Three ESP-BLE-MESH Nodes On

1687

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· ESP-BLE-MESH Fast Provisioning - Client and Server - this example is used for showing how fast provisioning can be used in order to create a mesh network. It takes no more than 60 seconds to provision 100 devices, see example client code and example server code .
· ESP-BLE-MESH and Wi-Fi Coexistence - an example that demonstrates the Wi-Fi and Bluetooth (BLE/BR/EDR) coexistence feature of ESP32-S3. Simply put, users can use the Wi-Fi while operating Bluetooth, see example code .
· ESP-BLE-MESH Console - an example that implements BLE Mesh basic features. Within this example a node can be scanned and provisioned by Provisioner and reply to get/set message from Provisioner, see example node code .
4.9.3 ESP-BLE-MESH Demo Videos
· Provisioning of ESP-BLE-MESH nodes using Smartphone App · Espressif Fast Provisioning using ESP-BLE-MESH App · Espressif ESP-BLE-MESH and Wi-Fi Coexistence
4.9.4 ESP-BLE-MESH FAQ
· 1. Provisioner Development · 2. Node Development · 3. ESP-BLE-MESH and Wi-Fi Coexistence · 4. Fast Provisioning · 5. Log Help · 6. Example Help · 7. Others
4.9.5 Related Documents
ESP-BLE-MESH Feature List
Supported Features
Mesh Core
· Provisioning: Node Role ­ PB-ADV and PB-GATT ­ OOB Authentication
· Provisioning: Provisioner Role ­ PB-ADV and PB-GATT ­ OOB Authentication
· Networking ­ Relay ­ Segmentation and Reassembly ­ Key Refresh Procedure ­ IV Update Procedure ­ Friend ­ Low Power ­ Proxy Server ­ Proxy Client
· Multiple Client Models Run Simultaneously ­ Support multiple client models send packets to different nodes simultaneously ­ No blocking between client model and server model
· NVS Storing ­ Store provisioning and configuration information of ESP-BLE-MESH Node

Espressif Systems

1688

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Mesh Models
· Foundation models ­ Configuration Server model ­ Configuration Client model ­ Health Server model ­ Health Client model
· Generic client models ­ Generic OnOff Client ­ Generic Level Client ­ Generic Default Transition Time Client ­ Generic Power OnOff Client ­ Generic Power Level Client ­ Generic Battery Client ­ Generic Location Client ­ Generic Property Client
· Sensor client models ­ Sensor Client
· Time and Scenes client models ­ Time Client ­ Scene Client ­ Scheduler Client
· Lighting client models ­ Light Lightness Client ­ Light CTL Client ­ Light HSL Client ­ Light xyL Client ­ Light LC Client
· Generic server models ­ Generic OnOff Server ­ Generic Level Server ­ Generic Default Transition Time Server ­ Generic Power OnOff Server ­ Generic Power OnOff Setup Server ­ Generic Power Level Server ­ Generic Power Level Setup Server ­ Generic Battery Server ­ Generic Location Server ­ Generic Location Setup Server ­ Generic User Property Server ­ Generic Admin Property Server ­ Generic Manufacturer Property Server ­ Generic Client Property Server
· Sensor server models ­ Sensor Server ­ Sensor Setup Server
· Time and Scenes server models ­ Time Server ­ Time Setup Server ­ Scene Server ­ Scene Setup Server ­ Scheduler Server ­ Scheduler Setup Server
· Lighting server models ­ Light Lightness Server ­ Light Lightness Setup Server ­ Light CTL Server ­ Light CTL Temperature Server ­ Light CTL Setup Server

Espressif Systems

1689

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
­ Light HSL Server ­ Light HSL Hue Server ­ Light HSL Saturation Server ­ Light HSL Setup Server ­ Light xyL Server ­ Light xyL Setup Server ­ Light LC Server ­ Light LC Setup Server
Mesh Applications
· ESP-BLE-MESH Node ­ Tutorial ­ Tutorial ­ Example
· ESP-BLE-MESH Provisioner ­ Tutorial ­ Example
· ESP-BLE-MESH Fast Provisioning ­ Fast Provisioning Client Model Tutorial ­ Fast Provisioning Server Model Tutorial ­ Example ­ Demo Video
· ESP-BLE-MESH and Wi-Fi Coexistence ­ Tutorial ­ Example ­ Demo Video
· ESP-BLE-MESH Console Commands ­ Example
Future Release Features
Mesh Core
· Provisioner NVS Storage
Mesh Applications
· Fast OTA · Friendship
ESP-BLE-MESH Architecture
This document introduces ESP-BLE-MESH architecture overview, ESP-BLE-MESH architecture implementation as well as ESP-BLE-MESH auxiliary routines.
· ESP-BLE-MESH Architecture Overview ­ Describes the five major parts of ESP-BLE-MESH architecture and the functionality of each part.
· ESP-BLE-MESH Architecture Implementation ­ Describes the basic functions of ESP-BLE-MESH files, the correspondence between files and ESP-BLEMESH architecture, and the interface for calling among files.
· ESP-BLE-MESH Auxiliary Routines ­ Describe the auxiliary routines of ESP-BLE-MESH, such as Mesh network management, Mesh features, etc.

Espressif Systems

1690

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

1. ESP-BLE-MESH Architecture Overview Currently ESP-BLE-MESH has implemented most functions of Mesh Profile and all the Client Models defined in Mesh Model specification. Those missing functions/models are under development and will be provided soon. ESP-BLE-MESH architecture has been granted the official Bluetooth certification.
ESP-BLE-MESH architecture includes five key parts:
· Mesh Protocol Stack ­ Mesh Networking is responsible for processing of messages of ESP-BLE-MESH nodes. ­ Mesh Provisioning is responsible for provisioning flow of ESP-BLE-MESH devices. ­ Mesh Models is responsible for the implementation of SIG-defined models.
· Network Management ­ Implements several network management procedures, including node removal procedure, IV Index recovery procedure, etc.
· Features ­ Include several ESP-BLE-MESH features, e.g. Low Power feature, Friend feature, Relay feature, etc.
· Mesh Bearer Layer ­ Includes Advertising Bearer and GATT Bearer. The bearer layer is crucial to ESP-BLEMESH protocol stack which is built on Bluetooth Low-Energy technology, because the protocol stack must make use of the bearer layer to transmit data via the BLE advertising channel and connection channel.
· Applications ­ Based on ESP-BLE-MESH protocol stack and Mesh Models. ­ By calling API and handling Event, Applications interact with Mesh Networking and Mesh Provisioning in ESP-BLE-MESH protocol stack, as well as a series of Models provided by Mesh Models.

1.1 Mesh Protocol Stack

1.1.1 Mesh Networking Mesh Networking in the protocol stack architecture implements the following functions:
· The communication between nodes in the Mesh network. · Encryption and decryption of messages in the Mesh network. · Management of Mesh network resources (Network Key, IV Index, etc.). · Segmentation and reassembly of Mesh network messages. · Model mapping of messages between different models. · For more features, please see ESP-BLE-MESH Feature List.
The implementation of Mesh Networking functions is based on hierarchy structure. Functions of each layer are shown in Table 1.1:

Layer Access Layer
Upper Transport Layer
Lower Transport Layer Network Layer

Table 1: Table 1.1 Mesh Networking Architecture Description Function Access Layer not only defines the format of application data, but also defines and controls the encryption and decryption of the data packets conducted by Upper Transport Layer. Upper Transport Layer encrypts, decrypts, and authenticates application data to and from the access layer; it also handles special messages called otransport control messagesp, including messages related to ofriendshippand heartbeat messages. Lower Transport Layer handles segmentation and reassembly of PDU.
Network Layer defines the address type and format of the network messages, and implements the relay function of the device.

1.1.2 Mesh Provisioning Mesh Provisioning in the protocol stack architecture implements the following functions:
· Provisioning of unprovisioned devices.

Espressif Systems

1691

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 14: Figure 1.1 ESP-BLE-MESH Architecture Diagram

Espressif Systems

1692

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

· Allocation of Mesh network resources (unicast address, IV Index, NetKey, etc.). · Four authentication methods support during provisioning. · For more features, please see ESP-BLE-MESH Feature List.
The implementation of Mesh Provisioning functions is based on hierarchy structure. Functions of each layer are shown in Table 1.2:

Table 2: Table 1.2 Mesh Provisioning Architecture Description

Layer

Function

Provisioning PDUs Provisioning PDUs from different layers are handled using provisioning protocol.

Generic Provisioning The Provisioning PDUs are transmitted to an unprovisioned device using a Generic Pro-

PDU/Proxy PDU

visioning layer or Proxy protocol layer.

PB-ADV/PB-GATT These layers define how the Provisioning PDUs are transmitted as transactions that can

be segmented and reassembled.

Advertising/ProvisioningThe provisioning bearers define how sessions are established such that the transactions

Service

from the generic provisioning layer can be delivered to a single device.

1.1.3 Mesh Models Mesh Models in the protocol stack architecture implements the following functions:
· Configuration Client/Server Models · Health Client/Server Models · Generic Client/Server Models · Sensor Client/Server Models · Time and Scenes Client/Server Models · Lighting Client/Server Models
Functions of each layer are shown in Table 1.3:

Layer Model Layer
Foundation Model Layer

Table 3: Table 1.3 Mesh Models Architecture Description
Function Model Layer implements models used to standardize the operation of typical user scenarios, including Generic Client/Server Models, Sensor Client/Server Models, Time and Scenes Client/Server Models, Lighting Client/Server Models and several vendor models. Foundation Model Layer implements models related to ESP-BLE-MESH configuration, management, self diagnosis, etc.

1.2 Mesh Network Management Network Management implements the following functions:
· Node removal procedure is used to remove a node from the network. · IV Index recovery procedure is used to recover a nodens IV Index. · IV update procedure is used to update the nodesnIV Index. · Key refresh procedure is used to update the nodesnNetKey, AppKey, etc. · Network creation procedure is used to create a mesh network. · NVS storage is used to store nodens networking information.
1.3 Mesh Features Features includes the following options:
· Low Power feature is used to reduce nodens power consumption. · Friend feature is used to store messages for Low Power nodes. · Relay feature is used to relay/forward Network PDUs received by a node over the advertising bearer. · Proxy Server/Client are two node roles in proxy protocol, which enable nodes to send and receive Network
PDUs, mesh beacons, proxy configuration messages and Provisioning PDUs over a connection-oriented bearer.
1.4 Mesh Bearer Layer Bearers in the protocol stack architecture are responsible for passing of data between ESP-BLE-MESH protocol stack and Bluetooth Low Energy Core.

Espressif Systems

1693

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Bearers can be taken as a carrier layer based on Bluetooth Low Energy Core, which implements the function of receiving and transmitting data for the ESP-BLE-MESH protocol stack.

Layer GATT Bearer
Advertising Bearer

Table 4: Table 1.3 Mesh Bearers Description
Function The GATT Bearer uses the Proxy protocol to transmit and receive Proxy PDUs between two devices over a GATT connection. When using the Advertising Bearer, a mesh packet shall be sent in the Advertising Data of a Bluetooth Low Energy advertising PDU using the Mesh Message AD Type.

1.5 Mesh Applications The Applications in the protocol stack architecture implement the corresponding functions by calling the API provided by the ESP-BLE-MESH protocol stack and processing the Event reported by the protocol stack. There are some common applications, such as gateway, lighting and etc.
Interaction between application layercApplicationsand API / Event
· Application layer calls API ­ Call the provisioning-related API for provisioning. ­ Call the model-related API to send messages. ­ Call the device-attributes-related API to get local information about the device.
· Application layer processes Event The application layer is designed based on events, which take parameters to the application layer. Events are mainly divided into two categories. ­ The events completed by calling API.  Such as nodes sending messages. ­ The events that the protocol stack actively reports to the application layer.  The Event that the protocol stack actively reports.  The Event that Model actively reports.
· The event is reported by the callback function registered by the application layer, and the callback function also contains the corresponding processing of the event.
Interaction between API / Event and ESP-BLE-MESH protocol stack
· API used by user mainly calls functions provided by Mesh Networking, Mesh Provisioning and Mesh Models.
· The interaction between API / Event and the protocol stack does not operate across the hierarchy of the protocol stack. For example, API does not call functions related to Network Layer.
2. ESP-BLE-MESH Architecture Implementation The design and implementation of ESP-BLE-MESH architecture is based on layers and modules. In details, Section 2.1 (Mesh Networking Implementation), Section 2.2 (Mesh Provisioning Implementation) and Section 2.3 (Mesh Bearers Implementation) are based on layers, and Section 2.4 (Mesh Models Implementation) is on modules.
· Layer-based Approach: With Layer-based approach, the architecture is designed according to the layers specified in the Mesh Profile Specification. Each layer has its unique files which include APIs of this layer and etc. The specific design is shown in Figure 2.1.
· Module-based Approach: Every file implements an independent function that can be called by other programs.
The design of ESP-BLE-MESH architecture uses layer-based approach. The sequence of layers which data packets are processed through is fixed, i.e., the processing of packets will form a message flow. Thus, we could see flows of messages from the Protocol Stack Interface Diagram in Figure 2.1.
2.1 Mesh Protocol Stack Implementation

Espressif Systems

1694

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 15: Figure 2.1 ESP-BLE-MESH Architecture Implementation Diagram

Espressif Systems

1695

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

2.1.1 Mesh Networking Implementation The list of files and the functions implemented in each file in Mesh Networking are shown in Table 2.1:

File access.c
transport.c
net.c adv.c

Table 5: Table 2.1 Mesh Networking File Description :widths: 40 150 :header-rows: 1 Functionality ESP-BLE-MESH Access Layer
ESP-BLE-MESH Lower/Upper Transport Layer
ESP-BLE-MESH Network Layer A task used to send ESP-BLE-MESH advertising packets, a callback used to handle received advertising packets and APIs used to allocate adv buffers

2.1.2 Mesh Provisioning Implementation The implementation of Mesh Provisioning is divided into two chunks due to the Node/Provisioner coexistence.
Specific files that provide implementation of provisioning of Node are shown in Table 2.2:

File prov.c proxy_server.c beacon.c

Table 6: Table 2.2 Mesh Provisioning (Node) File Description
Functionality ESP-BLE-MESH Node provisioning (PB-ADV & PB-GATT) ESP-BLE-MESH Proxy Server related functionalities APIs used to handle ESP-BLE-MESH Beacons

Specific files that implement functions of Provisioner are shown in Table 2.3:

File provisioner_prov.c proxy_client.c provisioner_main.c

Table 7: Table 2.3 Mesh Provisioning (Provisioner) File Description
Functionality ESP-BLE-MESH Provisioner provisioning (PB-ADV & PB-GATT) ESP-BLE-MESH Proxy Client related functionalities ESP-BLE-MESH Provisioner networking related functionalities

2.1.3 Mesh Models Implementation Mesh Models are used to implement the specific functions of model in nodes. Server model is used to maintain node status. Client model is used to obtain and modify node state.

Espressif Systems

1696

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

File cfg_cli.c cfg_srv.c health_cli.c health_srv.c client_common.c generic_client.c
lighting_client.c
sensor_client.c
time_scene_client.c
generic_server.c
lighting_server.c
sensor_server.c
time_scene_server.c

Table 8: Table 2.4 Mesh Models File Description
Functionality Send Configuration Client messages and receive corresponding response messages Receive Configuration Client messages and send proper response messages Send Health Client messages and receive corresponding response messages Receive Health Client messages and send proper response messages ESP-BLE-MESH model related operations Send ESP-BLE-MESH Generic Client messages and receive corresponding response messages Send ESP-BLE-MESH Lighting Client messages and receive corresponding response messages Send ESP-BLE-MESH Sensor Client messages and receive corresponding response messages Send ESP-BLE-MESH Time Scene Client messages and receive corresponding response messages Receive ESP-BLE-MESH Generic Client messages and send corresponding response messages Receive ESP-BLE-MESH Lighting Client messages and send corresponding response messages Receive ESP-BLE-MESH Sensor Client messages and send corresponding response messages Receive ESP-BLE-MESH Time Scene Client messages and send corresponding response messages

2.2 Mesh Bearers Implementation Portability is fully considered in the implementation of Mesh Bearers. When the ESP-BLE-MESH protocol stack is being ported to other platforms, users only need to modify mesh_bearer_adapt.c (example of NimBLE version ).

File mesh_bearer_adapt.c

Table 9: Table 2.5 Mesh Bearers File Description
Functionality ESP-BLE-MESH Bearer Layer adapterThis file provides the interfaces used to receive and send ESP-BLE-MESH ADV & GATT related packets.

Note: mesh_bearer_adapt.c is the implementation of Advertising Bearer and GATT Bearer in Mesh Networking framework.

2.3 Mesh Applications Implementation We have provided a series of application examples for customer development, and users can develop products based on ESP-BLE-MESH Examples.
3. Auxiliary Routine Auxiliary routine refers to optional functions in the ESP-BLE-MESH protocol stack. The design of the auxiliary routine generally implement the truncation of code through CONFIG_BLE_MESH.
3.1 Features · Low Power · Friend · Relay · Proxy Client/Server

Espressif Systems

1697

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

3.2 Network Management
· Node Removal procedure · IV Index Recovery procedure · IV Update procedure · Key Refresh procedure · Network Creation procedure · NVS Storage

3.3 Auxiliary Routine Implementation When adopting the design of independent module, the two main factors should be considered:
· The module can not be implemented hierarchically, and it can be completely independent, which means it does not rely on the implementation of other modules.
· The functions in the module will be used repeatedly, so it is reasonable to design it into a module. Independent module is shown in Table 3.1:

File lpn.c friend.c net.c
proxy_server.c proxy_client.c settings.c main.c

Table 10: Table 3.1 Module File Description
Functionality ESP-BLE-MESH Low Power functionality ESP-BLE-MESH Friend functionality ESP-BLE-MESH Relay feature, network creation, IV Update procedure, IV Index recovery procedure, Key Refresh procedure related functionalities ESP-BLE-MESH Proxy Server related functionalities ESP-BLE-MESH Proxy Client related functionalities ESP-BLE-MESH NVS storage functionality ESP-BLE-MESH stack initialize, stack enable, node removal related functionalities

ESP-BLE-MESH FAQ
This document provides a summary of frequently asked questions about developing with ESP-BLE-MESH, and is divided into seven sections:
· 1. Provisioner Development · 2. Node Development · 3. ESP-BLE-MESH and Wi-Fi Coexistence · 4. Fast Provisioning · 5. Log Help · 6. Example Help · 7. Others
Users could refer to the sections for quick answer to their questions. This document will be updated based on the feedback collected via various channels.
1. Provisioner Development Generally, a Provisioner is used to provision unprovisioned devices and form a mesh network. And after provisioning, roles of the unprovisioned devices will be changed to those of a node.
1.1 What is the flow for an unprovisioned device to join ESP-BLE-MESH network?
There are two phases for a device to join ESP-BLE-MESH network via a Provisioner, namely, provisioning and configuration.
· The phase of provisioning is to assign unicast address, add NetKey and etc. to a device. By provisioning, the device joins the ESP-BLE-MESH network and its role is changed from an unprovisioned device to a node.

Espressif Systems

1698

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· The phase of configuration is to add AppKeys to the node and bind AppKeys to corresponding models. And some items are optional during configuration, including adding subscription addresses to the node, set publication information, etc. By configuration, the node can actually transmit messages to a Provisioner and receive messages from it.
1.2 If a Provisioner wants to change states of a node, what requirements should be met for a Provisioner? · Client model that corresponds to server model of the node is required. · NetKey and AppKey used to encrypt messages shall be owned by both the node and the Provisioner. · The address owned by the node shall be known, which could be its unicast address or subscription address.
1.3 How can NetKey and AppKey be used? · NetKey is used for encryption of messages in Network Layer. Nodes with the same NetKey are assumed to be in the same subnet while those with different NetKeys cannot communicate with each other. · AppKey is used for encryption of messages in Upper Transport Layer. If client model and server model are bound to different AppKeys, the communication cannot be achieved.
1.4 How to generate a NetKey or AppKey for Provisioner? Can we use a fixed NetKey or AppKey? · The API esp_ble_mesh_provisioner_add_local_net_key() can be used to add a NetKey with a fixed or random value. · The API esp_ble_mesh_provisioner_add_local_app_key() can be used to add an AppKey with a fixed or random value.
1.5 Is the unicast address of Provisioner fixed? The value of prov_unicast_addr in esp_ble_mesh_prov_t is used to set the unicast address of Provisioner, it can be set only once during initialization and cannt be changed afterwards.
1.6 Can the address of Provisioner serve as destination address of the node-reporting-status message The unicast address of Provisioner can be set only once during initialization and cannt be changed afterwards. In theory, it can serve as the destination address of the node-reporting-status message, provided that the unicast address of the Provisioner is known by nodes. Nodes can know the unicast address of Provisioner during configuration since Provisioner sends messages to them with its unicast address used as the source address. Subscription address can also be used. Provisioner subscribes to a group address or virtual address, and nodes send messages to the subscription address.
1.7 Is the unicast address of the node that is firstly provisioned by Provisioner to ESP-BLE-MESH network fixed
The value of prov_start_address in esp_ble_mesh_prov_t is used to set the starting address when the Provisioner provisions unprovisioned devices, i.e. the unicast address of the node it firstly provisioned. It can be set only once during initialization and cannt be changed afterwards.
1.8 Is the unicast address of the node that mobile App firstly provisioned fixed? The App will decide the unicast address, and currently most of them are fixed.

Espressif Systems

1699

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

1.9 How to know which unprovisioned device is the Provisioner that is provisioning currently?
The value of prov_attention in esp_ble_mesh_prov_t is used by Provisioner set to unprovisioned device during provisioning. It can be set only once during initialization and cannt be changed afterwards. When the unprovisioned device is joining the mesh network, it can display in a specific way like flashing light to notify Provisioner that it is being provisioned.
1.10 How many ways to authenticate the devices during provisioning? Which way was used in the provided examples ?
There are four authentication methods, i.e. No OOB, Static OOB, Output OOB and Input OOB. In the provided examples, No OOB is used.
1.11 What information can be carried by the advertising packets of the unprovisioned device before provisioning into the network?
· Device UUID · OOB Info · URL Hash (optional)
1.12 Can such information be used for device identification?
For example, each unprovisioned device contains a unique Device UUID, which can be used for device identification.
1.13 How is the unicast address assigned when the node provisioned by Provisioner contains multiple elements?
· Provisioner will assign an unicast address for the primary element of the node, and unicast address of the remaining elements are incremented one by one.
· For example: If an unprovisioned device has three elements, i.e. the primary element, the second element and the third element. After provisioning, the primary element address of the node is 0x0002 while the second element address is 0x0003, and the third element address is 0x0004.
1.14 How can Provisioner get and parse the Composition Data of nodes through Configuration Client Model?
· Provisioner can get the Composition Data of nodes using the Configuration Client Model API esp_ble_mesh_config_client_set_state() with comp_data_get in the parameter esp_ble_mesh_cfg_client_get_state_t set properly.
· Users can refer to the following code to parse the Composition Data:
#include <stdio.h> #include <string.h> #include <stdint.h>
//test date: 0C001A0001000800030000010501000000800100001003103F002A00 //0C00 1A00 0100 0800 0300 0001 05 01 0000 0080 0100 0010 0310 3F002A00
// CID is 0x000C // PID is 0x001A // VID is 0x0001 // CRPL is 0x0008 // Features is 0x0003  Relay and Friend features. // Loc is ofrontp  0x0100 // NumS is 5 // NumV is 1 // The Bluetooth SIG Models supported are: 0x0000, 0x8000, 0x0001, 0x1000,  0x1003
(continues on next page)

Espressif Systems

1700

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

(continued from previous page) // The Vendor Models supported are: Company Identifier 0x003F and Model Identifier 0x002A
typedef struct { int16_t cid; int16_t pid; int16_t vid; int16_t crpl; int16_t features; int16_t all_models; uint8_t sig_models; uint8_t vnd_models;
} esp_ble_mesh_composition_head;
typedef struct { uint16_t model_id; uint16_t vendor_id;
} tsModel;
typedef struct { // reserve space for up to 20 SIG models uint16_t SIG_models[20]; uint8_t numSIGModels;
// reserve space for up to 4 vendor models tsModel Vendor_models[4]; uint8_t numVendorModels; } esp_ble_mesh_composition_decode;
int decode_comp_data(esp_ble_mesh_composition_head *head, esp_ble_mesh_ composition_decode *data, uint8_t *mystr, int size) {
int pos_sig_base; int pos_vnd_base; int i;
memcpy(head, mystr, sizeof(*head));
if(size < sizeof(*head) + head->sig_models * 2 + head->vnd_models * 4) {
return -1; }
pos_sig_base = sizeof(*head) - 1;
for(i = 1; i < head->sig_models * 2; i = i + 2) { data->SIG_models[i/2] = mystr[i + pos_sig_base] | (mystr[i + pos_
sig_base + 1] << 8); printf("%d: %4.4x\n", i/2, data->SIG_models[i/2]);
}
pos_vnd_base = head->sig_models * 2 + pos_sig_base;
for(i = 1; i < head->vnd_models * 2; i = i + 2) { data->Vendor_models[i/2].model_id = mystr[i + pos_vnd_base] |
(mystr[i + pos_vnd_base + 1] << 8); printf("%d: %4.4x\n", i/2, data->Vendor_models[i/2].model_id);
data->Vendor_models[i/2].vendor_id = mystr[i + pos_vnd_base + 2] | (mystr[i + pos_vnd_base + 3] << 8);
printf("%d: %4.4x\n", i/2, data->Vendor_models[i/2].vendor_id);
(continues on next page)

Espressif Systems

1701

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

(continued from previous page)
}
return 0; }
void app_main(void) {
esp_ble_mesh_composition_head head = {0}; esp_ble_mesh_composition_decode data = {0}; uint8_t mystr[] = { 0x0C, 0x00, 0x1A, 0x00,
0x01, 0x00, 0x08, 0x00, 0x03, 0x00, 0x00, 0x01, 0x05, 0x01, 0x00, 0x00, 0x00, 0x80, 0x01, 0x00, 0x00, 0x10, 0x03, 0x10, 0x3F, 0x00, 0x2A, 0x00}; int ret;
ret = decode_comp_data(&head, &data, mystr, sizeof(mystr)); if (ret == -1) {
printf("decode_comp_data error"); } }

1.15 How can Provisioner further configure nodes through obtained Composition Data?
Provisioner do the following configuration by calling the Configuration Client Model API esp_ble_mesh_config_client_set_state().
· Add AppKey to nodes with app_key_add in the parameter esp_ble_mesh_cfg_client_set_state_t set properly.
· Add subscription address to the models of nodes with model_sub_add in the parameter esp_ble_mesh_cfg_client_set_state_t set properly.
· Set publication information to the models of nodes with model_pub_set in the parameter esp_ble_mesh_cfg_client_set_state_t set properly.

1.16 Can nodes add corresponding configurations for themselves?
This method can be used in special cases like testing period.
· Here is an example to show nodes add new group addresses for their models.
esp_err_t example_add_fast_prov_group_address(uint16_t model_id, uint16_t group_addr) {
const esp_ble_mesh_comp_t *comp = NULL; esp_ble_mesh_elem_t *element = NULL; esp_ble_mesh_model_t *model = NULL; int i, j;

if (!ESP_BLE_MESH_ADDR_IS_GROUP(group_addr)) { return ESP_ERR_INVALID_ARG;
}

comp = esp_ble_mesh_get_composition_data(); if (!comp) {
return ESP_FAIL; }

for (i = 0; i < comp->element_count; i++) {

(continues on next page)

Espressif Systems

1702

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
(continued from previous page) element = &comp->elements[i]; model = esp_ble_mesh_find_sig_model(element, model_id); if (!model) {
continue; } for (j = 0; j < ARRAY_SIZE(model->groups); j++) {
if (model->groups[j] == group_addr) { break;
} } if (j != ARRAY_SIZE(model->groups)) {
ESP_LOGW(TAG, "%s: Group address already exists, element index: %d", __func__, i);
continue; } for (j = 0; j < ARRAY_SIZE(model->groups); j++) {
if (model->groups[j] == ESP_BLE_MESH_ADDR_UNASSIGNED) { model->groups[j] = group_addr; break;
} } if (j == ARRAY_SIZE(model->groups)) {
ESP_LOGE(TAG, "%s: Model is full of group addresses, element index: %d", __func__, i);
} }
return ESP_OK; }
Note: When the NVS storage of the node is enabled, group address added and AppKey bound by this method will not be saved in the NVS when the device is powered off currently. These configuration information can only be saved if they are configured by Configuration Client Model.

1.17 How does Provisioner control nodes by grouping?
Generally there are two approaches to implement group control in ESP-BLE-MESH network, group address approach and virtual address approach. And supposing there are 10 devices, i.e., five devices with blue lights and five devices with red lights.
· Method 1: 5 blue lights can subscribe to a group address, 5 red lights subscribe to another one. By sending messages to different group addresses, Provisioner can realize group control.
· Method 2: 5 blue lights can subscribe to a virtual address, 5 red lights subscribe to another one. By sending messages to different virtual addresses, Provisioner can realize group control.

1.18 How does Provisioner add nodes to multiple subnets?
Provisioner can add multiple NetKeys to nodes during configuration, and nodes sharing the same NetKey belong to the same subnet. Provisioner can communicate with nodes on different subnets by using different NetKeys.

1.19 How does Provisioner know if a node in the mesh network is offline?
Node offline is usually defined as: the condition that the node cannot be properly communicated with other nodes in the mesh network due to power failure or some other reasons.
There is no connection between nodes and nodes in the ESP-BLE-MESH network. They communicate with each other through advertising channels.

Espressif Systems

1703

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
An example is given here to show how to detect a node is offline by Provisioner. · The node can periodically send heartbeat messages to Provisioner. And if Provisioner failed to receive heartbeat messages in a certain period, the node is considered to be offline.
Note: The heartbeat message should be designed into a single package (less than 11 bytes), so the transmission and reception of it can be more efficient.

1.20 What operations should be performed when Provisioner removes nodes from the network?
Usually when Provisioner tries to remove node from the mesh network, the procedure includes three main steps:
· Firstly, Provisioner adds the node that need to be removed to the oblacklistp. · Secondly, Provisioner performs the Key Refresh procedure. · Lastly, the node performs node reset procedure, and switches itself to an unprovisioned device.
1.21 In the Key Refresh procedure, how does Provisioner update the Netkey owned by nodes?
· Provisioner updates the NetKey of nodes using the Configuration Client Model API esp_ble_mesh_config_client_set_state() with net_key_update in the parameter esp_ble_mesh_cfg_client_set_state_t set properly.
· Provisioner updates the AppKey of nodes using the Configuration Client Model API esp_ble_mesh_config_client_set_state() with app_key_update in the parameter esp_ble_mesh_cfg_client_set_state_t set properly.
1.22 How does Provisioner manage nodes in the mesh network?
ESP-BLE-MESH implements several functions related to basic node management in the example, such as esp_ble_mesh_store_node_info(). And ESP-BLE-MESH also provides the API esp_ble_mesh_provisioner_set_node_name() which can be used to set the nodens local name and the API esp_ble_mesh_provisioner_get_node_name() which can be used to get the nodens local name.
1.23 What does Provisioner need when trying to control the server model of nodes?
Provisioner must include corresponding client model before controlling the server model of nodes.
Provisioner shall add its local NetKey and AppKey.
· Provisioner add NetKey by calling the API esp_ble_mesh_provisioner_add_local_net_key(). · Provisioner add AppKey by calling the API esp_ble_mesh_provisioner_add_local_app_key().
Provisioner shall configure its own client model.
· Provisioner bind AppKey to its own client model by calling the API esp_ble_mesh_provisioner_bind_app_key_to_local_model().
1.24 How does Provisoner control the server model of nodes?
ESP-BLE-MESH supports all SIG-defined client models. Provisioner can use these client models to control the server models of nodes. And the client models are divided into 6 categories with each category has the corresponding functions.
· Configuration Client Model ­ The API esp_ble_mesh_config_client_get_state() can be used to get the esp_ble_mesh_cfg_client_get_state_t values of Configuration Server Model. ­ The API esp_ble_mesh_config_client_set_state() can be used to set the esp_ble_mesh_cfg_client_set_state_t values of Configuration Server Model.

Espressif Systems

1704

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· Health Client Model ­ The API esp_ble_mesh_health_client_get_state() can be used to get the esp_ble_mesh_health_client_get_state_t values of Health Server Model. ­ The API esp_ble_mesh_health_client_set_state() can be used to set the esp_ble_mesh_health_client_set_state_t values of Health Server Model.
· Generic Client Models ­ The API esp_ble_mesh_generic_client_get_state() can be used to get the esp_ble_mesh_generic_client_get_state_t values of Generic Server Models. ­ The API esp_ble_mesh_generic_client_set_state() can be used to set the esp_ble_mesh_generic_client_set_state_t values of Generic Server Models.
· Lighting Client Models ­ The API esp_ble_mesh_light_client_get_state() can be used to get the esp_ble_mesh_light_client_get_state_t values of Lighting Server Models. ­ The API esp_ble_mesh_light_client_set_state() can be used to set the esp_ble_mesh_light_client_set_state_t values of Lighting Server Models.
· Sensor Client Models ­ The API esp_ble_mesh_sensor_client_get_state() can be used to get the esp_ble_mesh_sensor_client_get_state_t values of Sensor Server Model. ­ The API esp_ble_mesh_sensor_client_set_state() can be used to set the esp_ble_mesh_sensor_client_set_state_t values of Sensor Server Model.
· Time and Scenes Client Models ­ The API esp_ble_mesh_time_scene_client_get_state() can be used to get the esp_ble_mesh_time_scene_client_get_state_t values of Time and Scenes Server Models. ­ The API esp_ble_mesh_time_scene_client_set_state() can be used to set the esp_ble_mesh_time_scene_client_set_state_t values of Time and Scenes Server Models.
2. Node Development
2.1 What kind of models are included by nodes?
· In ESP-BLE-MESH, nodes are all composed of a series of models with each model implements some functions of the node.
· Model has two types, client model and server model. Client model can get and set the states of server model. · Model can also be divided into SIG model and vendor model. All behaviors of SIG models are officially defined
while behaviors of vendor models are defined by users.
2.2 Is the format of messages corresponding to each model fixed?
· Messages, which consist of opcode and payload, are divided by opcode. · The type and the format of the messages corresponding to models are both fixed, which means the messages
transmitted between models are fixed.
2.3 Which functions can be used to send messages with the models of nodes?
· For client models, users can use the API esp_ble_mesh_client_model_send_msg() to send messages.
· For server models, users can use the API esp_ble_mesh_server_model_send_msg() to send messages.
· For publication, users call the API esp_ble_mesh_model_publish() to publish messages.
2.4 How to achieve the transmission of messages without packet loss?

Espressif Systems

1705

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Acknowledegd message is needed if users want to transmit messages without packet loss. The default time to wait for corresponding response is set in CONFIG_BLE_MESH_CLIENT_MSG_TIMEOUT. If the sender waits for the response until the timer expires, the corresponding timeout event would be triggered.
Note: Response timeout can be set in the API esp_ble_mesh_client_model_send_msg(). The default value (4 seconds) would be applied if the parameter msg_timeout is set to 0.

2.5 How to send unacknowledged messages? For client models, users can use the API esp_ble_mesh_client_model_send_msg() with the parameter need_rsp set to false to send unacknowledged messages. For server models, the messages sent by using the API esp_ble_mesh_server_model_send_msg() are always unacknowledged messages.
2.6 How to add subscription address to models? Subscription address can be added through Configuration Client Model.
2.7 What is the difference between messages sent and published by models? Messages sent by calling the API esp_ble_mesh_client_model_send_msg() or esp_ble_mesh_server_model_send_msg() will be sent in the duration determined by the Network Transmit state. Messages published by calling the API esp_ble_mesh_model_publish() will be published determined by the Model Publication state. And the publication of messages is generally periodic or with a fixed number of counts. The publication period and publication count are controlled by the Model Publication state, and can be configured through Configuration Client Model.
2.8 How many bytes can be carried when sending unsegmented messages? The total payload length (which can be set by users) of unsegmented message is 11 octets, so if the opcode of the message is 2 octets, then the message can carry 9-octets of valid information. For vendor messages, due to the 3-octets opcode, the remaining payload length is 8 octets.
2.9 When should the Relay feature of nodes be enabled? Users can enable the Relay feature of all nodes when nodes detected in the mesh network are sparse. For dense mesh network, users can choose to just enable the Relay feature of several nodes. And users can enable the Relay feature by default if the mesh network size is unknown.
2.10 When should the Proxy feature of node be enabled? If the unprovisioned device is expected to be provisioned by a phone, then it should enable the Proxy feature since almost all the phones do not support sending ESP-BLE-MESH packets through advertising bearer currently. And after the unprovisioned device is provisioned successfully and becoming a Proxy node, it will communicate with the phone using GATT bearer and using advertising bearer to communicate with other nodes in the mesh network.
2.11 How to use the Proxy filter? The Proxy filter is used to reduce the number of Network PDUs exchanged between a Proxy Client (e.g. the phone) and a Proxy Server (e.g. the node). And with the Proxy filter, Proxy Client can explicitly request to receive only mesh messages with certain destination addresses from Proxy Server.

Espressif Systems

1706

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
2.12 When a message can be relayed by a Relay node? If a message need to be relayed, the following conditions should be met. · The message is in the mesh network. · The message is not sent to the unicast address of the node. · The value of TTL in the message is greater than 1.
2.13 If a message is segmented into several segments, should the other Relay nodes just relay when one of these segments is received or wait until the message is received completely?
Relay nodes will forward segments when one of them are received rather than keeping waiting until all the segments are received.
2.14 What is the principle of reducing power consumption using Low Power feature? · When the radio is turned on for listening, the device is consuming energy. When low power feature of the node is enabled, it will turn off its radio in the most of the time. · And cooperation is needed between low power node and friend node, thus low power node can receive messages at an appropriate or lower frequency without the need to keep listening. · When there are some new messages for low power node, its friend node will store the messages for it. And low power node can poll friend nodes to see if there are new messages at a fixed interval.
2.15 How to continue the communication on the network after powering-down and powering-up again? Enable the configuration Store ESP-BLE-MESH Node configuration persistently in menuconfig.
2.16 How to send out the self-test results of nodes? It is recommended that nodes can publish its self-test results periodically through Health Server Model.
2.17 How to transmit information between nodes? One possible application scenario for transmitting information between nodes is that spray nodes would be triggered once smoke alarm detected high smoke concentration. There are two approaches in implementation. · Approach 1 is that spray node subscribes to a group address. When smoke alarm detects high smoke concentration, it will publish a message whose destination address is the group address which has been subscribed by spray node. · Approach 2 is that Provisioner can configure the unicast address of spray node to the smoke alarm. When high smoke concentration is detected, smoke alarm can use send messages to the spray node with the spray nodens unicast address as the destination address.
2.18 Is gateway a must for nodes communication? · Situation 1: nodes only communicate within the mesh network. In this situation, no gateway is need. ESP-BLEMESH network is a flooded network, messages in the network have no fixed paths, and nodes can communicate with each other freely. · Situation 2: if users want to control the nodes remotely, for example turn on some nodes before getting home, then a gateway is needed.
2.19 When will the IV Update procedure be performed? IV Update procedure would be performed once sequence number of messages sent detected by the bottom layer of node reached a critical value.

Espressif Systems

1707

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
2.20 How to perform IV Update procedure? Nodes can perform IV Update procedure with Secure Network Beacon.
3. ESP-BLE-MESH and Wi-Fi Coexistence
3.1 Which modes does Wi-Fi support when it coexists with ESP-BLE-MESH? Currently only Wi-Fi station mode supports the coexistence.
3.2 Why is the Wi-Fi throughput so low when Wi-Fi and ESP-BLE-MESH coexist? The ESP32-DevKitC board without PSRAM can run properly but the throughput of it is low since it has no PSRAM. When Bluetooth and Wi-Fi coexist, the throughput of ESP32-DevKitC with PSRAM can be stabilized to more than 1Mbps. And some configurations in menuconfig shall be enabled to support PSRAM. · ESP32-specific --> Support for external,SPI-connected RAM --> Try to allocate memories of Wi-Fi and LWIP... · Bluetooth --> Bluedroid Enable --> BT/BLE will first malloc the memory from the PSRAM · Bluetooth --> Bluedroid Enable --> Use dynamic memory allocation in BT/BLE stack. · Bluetooth --> Bluetooth controller --> BLE full scan feature supported. · Wi-Fi --> Software controls Wi-Fi/Bluetooth coexistence --> Wi-Fi
4. Fast Provisioning
4.1 Why is fast provisioning needed? Normally when they are several unprovisioned devices, users can provision them one by one. But when it comes to a large number of unprovisioned devices (e.g. 100), provisioning them one by one will take huge amount of time. With fast provisioning, users can provision 100 unprovisioned devices in about 50 seconds.
4.2 Why EspBleMesh App would wait for a long time during fast provisioning? After the App provisioned one Proxy node, it will disconnect from the App during fast provisioning, and reconnect with the App when all the nodes are provisioned.
4.3 Why is the number of node addresses displayed in the App is more than that of existing node addresses? Each time after a fast provisioning process, and before starting a new one, the node addresses in the App should be cleared, otherwise the number of the node address will be incorrect.
4.4 What is the usage of the count value which was input in EspBleMesh App? The count value is provided to the Proxy node which is provisioned by the App so as to determine when to start Proxy advertising in advance.
4.5 When will Configuration Client Model of the node running fast_prov_server example start to work? Configuration Client Model will start to work after the Temporary Provisioner functionality is enabled.

Espressif Systems

1708

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

4.6 Will the Temporary Provisioner functionality be enabled all the time?
After the nodes receive messages used to turn on/off lights, all the nodes will disable its Temporary Provisioner functionality and become nodes.

5. Log Help You can find meaning of errors or warnings when they appear at the bottom of ESP-BLE-MESH stack.

5.1 What is the meaning of warning ran out of retransmit attempts?
When the node transmits a segmented message, and due to some reasons, the receiver doesnnt receive the complete message. Then the node will retransmit the message. When the retransmission count reaches the maximum number, which is 4 currently, then this warning will appear.

5.2 What is the meaning of warning Duplicate found in Network Message Cache?
When the node receives a message, it will compare the message with the ones stored in the network cache. If the same has been found in the cache, which means it has been received before, then the message will be dropped.

5.3 What is the meaning of warning Incomplete timer expired?
When the node doesnnt receive all the segments of a segmented message during a certain period (e.g. 10 seconds), then the Incomplete timer will expire and this warning will appear.

5.4 What is the meaning of warning No matching TX context for ack?
When the node receives a segment ack and it doesnnt find any self-send segmented message related with this ack, then this warning will appear.

5.5 What is the meaning of warning No free slots for new incoming segmented messages?
When the node has no space for receiving new segmented message, this warning will appear. Users can make the space larger through the configuration CONFIG_BLE_MESH_RX_SEG_MSG_COUNT.

5.6 What is the meaning of error Model not bound to Appkey 0x0000
When the node sends messages with a model and the model has not been bound to the AppKey with AppKey Index 0x000, then this error will appear.

5.7 What is the meaning of error Busy sending message to DST xxxx?
This error means client model of the node has transmitted a message to the target node and now is waiting for a response, users can not send messages to the same node with the same unicast address. After the corresponding response is received or timer is expired, then another message can be sent.

6. Example Help

6.1 How are the ESP-BLE-MESH callback functions classified?
· The API esp_ble_mesh_register_prov_callback() is used to register callback function used to handle provisioning and networking related events.
· The API esp_ble_mesh_register_config_client_callback() is used to register callback function used to handle Configuration Client Model related events.
· The API esp_ble_mesh_register_config_server_callback() is used to register callback function used to handle Configuration Server Model related events.

Espressif Systems

1709

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· The API esp_ble_mesh_register_health_client_callback() is used to register callback function used to handle Health Client Model related events.
· The API esp_ble_mesh_register_health_server_callback() is used to register callback function used to handle Health Server Model related events.
· The API esp_ble_mesh_register_generic_client_callback() is used to register callback function used to handle Generic Client Models related events.
· The API esp_ble_mesh_register_light_client_callback() is used to register callback function used to handle Lighting Client Models related events.
· The API esp_ble_mesh_register_sensor_client_callback() is used to register callback function used to handle Sensor Client Model related events.
· The API esp_ble_mesh_register_time_scene_client_callback() is used to register callback function used to handle Time and Scenes Client Models related events.
· The API esp_ble_mesh_register_custom_model_callback() is used to register callback function used to handle vendor model and unrealized server models related events.
7. Others
7.1 How to print the message context? The examples use ESP_LOG_BUFFER_HEX() to print the message context while the ESP-BLEMESH protocol stack uses bt_hex().
7.2 Which API can be used to restart ESP32-S3? The API esp_restart().
7.3 How to monitor the remaining space of the stack of a task? The API vTaskList() can be used to print the remaining space of the task stack periodically.
7.4 How to change the level of log without changing the menuconfig output level? The API esp_log_level_set() can be used to change the log output level rather than using menuconfig to change it.

Espressif Systems

1710

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

ESP-BLE-MESH Terminology

Table 11: Table 1 ESP-BLE-MESH Terminology - Role

Term Official Definition UnprovisioAneddevice that is not a member of a mesh Device network is known as an unprovisioned
device. Node A node is a provisioned device.

Relay Node

A node that supports the Relay feature and has the Relay feature enabled is known as a Relay node.

Proxy Node

A node that supports the Proxy feature and has the Proxy feature enabled is known as a Proxy node.

Friend Node

A node that supports the Friend feature, has the Friend feature enabled, and has a friendship with a node that supports the Low Power feature is known as a Friend node.

Low A node that supports the Low Power Power feature and has a friendship with a Node node that supports the Friend feature is
known as a Low Power node. ProvisionerA node that is capable of adding a de-
vice to a mesh network.

Detailed Explanation Examples: lighting devices, temperature control devices, manufacturing equipments and electric doors, etc.
The role of unprovisioned device will change to node after being provisioned to ESP-BLE-MESH network. Nodes (such as lighting devices, temperature control devices, manufacturing equipments, and electric doors) are devices that can send, receive, or relay messages in ESP-BLE-MESH network, and they can optionally support one or more subnets. Relay nodes can receive and resend ESP-BLE-MESH messages, so the messages can be transferred further. Users can decide whether or not to enable forwarding function of nodes according to nodesnstatus. Messages can be relayed for multiple times, and each relay is considered as a ohopp. Messages can hop up to 126 times, which is enough for message transmission in a wide area. Proxy nodes receive messages from one bearer (it generally includes advertising bearer and GATT bearer) and resend it from another one. The purpose is to connect communication equipments that only support GATT bearer to ESPBLE-MESH network. Generally, mobile apps need a Proxy node to access Mesh network. Without Proxy nodes, mobile apps cannot communicate with members in Mesh network. Friend node, like the backup of Low Power node (LPN), can store messages that are sent to Low Power node and security updates; the stored information will be transferred to Low Power node when Low Power node needs it. Low Power node must establishofriendshippwith another node that supports the Friend Feature to reduce duty cycle of its receiver, thus power consumption of Low Power node can be reduced. Low Power node needs to find a Friend node to establish a friendship with it. The process involved is calledofriendship establishmentp. Cooperation between Low Power node and Friend nodes enables Low Power node to schedule the use of the radio, thus Low Power node can receive messages at an appropriate or lower frequency without the need of keeping listening. Low Power node will poll Friend node to see if there is new message. By polling, Low Power node gets information from Friend node, such as messages, security updates, and etc.
The device that can provision unprovisioned devices is called a Provisioner. This process usually needs to be implemented through an app that is typically provided by the product manufacturer and can be used on a gateway, a smartphone, tablet or other carriers.

Espressif Systems

1711

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Table 12: Table 2 ESP-BLE-MESH Terminology - Composition

Term State

Official Definition A value representing a condition of an element that is exposed by an element of a node.

Detailed Explanation Each node in a ESP-BLE-MESH network has an independent set of state values that indicate certain states of the device, like brightness, and color of lighting device. Change of state value will lead to change of the physical state of devices. For example, changing the on/off state of a device is actually turning on/off the device.

Model

A model defines the basic functionality of a node.

A node may contain multiple models, and each model defines basic functionalities of nodes, like the states needed by the nodes, the messages controlling the states, and actions resulted from messages handling. The function implementation of the nodes is based on models, which can be divided into SIG Model and Vendor Model, with the former defined by SIG and latter defined by users.

Element An addressable entity within a device.

A node can contain one or more elements, with each having a unicast address and one or more models, and the models contained by the same element must not be the same.

CompositioTnhe Composition Data state contains Data information about a node, the elements State it includes, and the supported models.

By reading the value of the Composition Data state, users can know basic information of the node, such as the number of elements, and the models in each element. Provisioner gets this message to further provision the device, such as configuring subscription address and publishing address of nodes.

Term Low Power Feature
Friend Feature
Relay Feature
Proxy Feature

Table 13: Table 3 ESP-BLE-MESH Terminology - Features

Official Definition

Detailed Explanation

The ability to operate within a mesh Low Power feature reduces power consumption of nodes.

network at significantly reduced re- When a Low Power node is searching for a Friend node, and

ceiver duty cycles only in conjunction there are multiple Friend nodes nearby, it selects the most

with a node supporting the Friend fea- suitable Friend node through algorithm.

ture.

The ability to help a node support- By enabling friend feature, the node can help to store infor-

ing the Low Power feature to operate mation for Low Power node. The nodes enabled with friend

by storing messages destined for those feature may cause more power and memory consumption.

nodes.

The ability to receive and retransmit The relay feature enables ESP-BLE-MESH messages to hop

mesh messages over the advertising among nodes for multiple times, and the transmission dis-

bearer to enable larger networks.

tance can exceed the range of direct radio transmission be-

tween two nodes, thereby covering the entire network. When

a node is enabled with the relay feature to relay messages, it

only relays the messages of its own subnet, and does not re-

lay the messages of other subnets. The data integrity will

not be considered when the node enabled with relay feature

relays segmented messages. The node would relay every seg-

mented message once it receives one rather than waiting for

the complete message.

The ability to receive and retransmit The purpose of the proxy feature is to allow nodes without an

mesh messages between GATT and ad- advertising bearer to access the ESP-BLE-MESH network.

vertising bearers.

The proxy feature is typically used in nodes that need to con-

nect to mobile apps.

Espressif Systems

1712

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Table 14: Table 4 ESP-BLE-MESH Terminology - Provisioning

Term PBADV
PBGATT

Official Definition PB-ADV is a provisioning bearer used to provision a device using Generic Provisioning PDUs over the advertising channels. PB-GATT is a provisioning bearer used to provision a device using Proxy PDUs to encapsulate Provisioning PDUs within the Mesh Provisioning Service.

ProvisioninPgrovisioning is a process of adding an unprovisioned device to a mesh network, managed by a Provisioner.
AuthenticaAtiuonthentication is a step during the proMethod visioning of nodes. Input Input Out-of-Band OOB

Output Output Out-of-Band OOB

Static Static Out-of-Band OOB

No OOB

No Out-of-Band

Detailed Explanation PB-ADV transfers packets generated during the provisioning process over the advertising channels. This way can only be used for provisioning when provisioner and unprovisioned device both support PB-ADV. PB-GATT uses connection channels to transfer packets generated during the provisioning process. If an unprovisioned device wants to be provisioned through this method, it needs to implement the related Mesh Provisioning Service. Unprovisioned devices which donnt implement such service cannot be provisioned into mesh network through PB-GATT bearer. The process of provisioning turns theounprovisioned devicep into aonodep, making it a member of the ESP-BLE-MESH network. There are four authentication methods for unprovisioned devices: Output OOB, Input OOB, Static OOB, and No OOB. For example, a Provisioner generates and displays a random number, and then prompts users to take appropriate actions to input the random number into the unprovisioned device. Taking lighting switch as an example, users can press the button for several times in a certain period of time to input the random number displayed on the Provisioner. Authentication method of the Input OOB is similar to that of Output OOB, but the role of the device is reversed. For example, an unprovisioned device will choose a random number and output the number in a way that is compatible with its functionality. If the unprovisioned device is a bulb, it can flash a specified number of times. If the unprovisioned device has an LCD screen, the random number can display as a multi-digit value. Users who start provisioning should input the observed number to authenticate the unprovisioned device. Authentication method of Static OOB: use Static OOB information. Use 0 as Static OOB information if No OOB information is needed. Use Static OOB information to authenticate devices which are going through provisioning if OOB information is needed. Authentication method of No OOB: Set the value of the Static OOB field to 0. Using this way is like not authenticating the unprovisioned devices.

Espressif Systems

1713

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Table 15: Table 5 ESP-BLE-MESH Terminology - Address

Term Official Definition

UnassignedThis is a special address type, with a

Ad-

value of 0x0000. Its use indicates that

dress an Element has not yet been configured

or had a Unicast Address assigned to it.

Detailed Explanation The addresses owned by elements which has not been configured yet or no address has been allocated are unassigned addresses. These elements will not be used for messages transfer because they have no fixed address. Unassigned address is recommended to set as the value of the address before setting the address of user code.

Unicast Address

A unicast address is a unique address allocated to each element.

During provisioning, the Provisioner will assign a unicast address to each element of node within the life cycle of the nodes in the network. A unicast address may appear in the source/destination address field of a message. Messages sent to a unicast address can only be processed by the element that owns the unicast address.

Virtual Address

A virtual address represents a set of destination addresses. Each virtual address logically represents a Label UUID, which is a 128-bit value that does not have to be managed centrally.

Associated with specific UUID labels, a virtual address may serve as the publishing or subscription address of the model. A UUID label is a 128-bit value associated with elements of one or more nodes. For virtual addresses, the 15th and 14th bits are set to 1 and 0 respectively; bits from 13th to 0 are set to hash values (providing 16384 hash values). The hash is a derivation of the Label UUID. To use subscribing elements to check the full 128-bit UUID is very inefficient while hash values provide a more efficient way to determine which elements that which messages are finally sent to.

Group Address

A group address is an address that is programmed into zero or more elements

Group address is another kind of multicast address in the ESP-BLE-MESH network, which is usually used to group nodes. A message sent to the all-proxies address shall be processed by the primary element of all nodes that have the proxy functionality enabled. A message sent to the allfriends address shall be processed by the primary element of all nodes that have the friend functionality enabled. A message sent to the all-relays address shall be processed by the primary element of all nodes that have the relay functionality enabled. A message sent to the all-nodes address shall be processed by the primary element of all nodes.

Espressif Systems

1714

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Table 16: Table 6 ESP-BLE-MESH Terminology - Security

Term Device Key (DevKey)

Official Definition There is also a device key, which is a special application key that is unique to each node, is known only to the node and a Configuration Client, and is used to secure communications between the node and a Configuration Client.

Detailed Explanation The device key enables you to provision the devices, configure the nodes. The device key is used to encrypt Configuration Messages, i.e. the message transferred between the Provisioner and the node when the device is configured.

ApplicationApplication keys are used to secure Key communications at the upper transport (App- layer. Key)

Application key is used for decryption of application data before delivering application data to application layer and encryption of them during the delivery of application layer. Some nodes in the network have a specific purpose and can restrict access to potentially sensitive data based on the needs of the application. With specific application keys, these nodes are associated with specific applications. Generally speaking, the fields using different application keys include security (access control of buildings, machine rooms and CEO offices), lighting (plant, exterior building and sidewalks) and HVAC systems. Application keys are bound to Network keys. This means application keys are only used in a context of a Network key they are bound to. An application key shall only be bound to a single Network key.

Master Security Material

The master security material is derived from the network key (NetKey) and can be used by other nodes in the same network. Messages encrypted with master security material can be decoded by any node in the same network.

The corresponding friendship messages encrypted with the friendship security material: 1. Friend Poll, 2. Friend Update, 3. Friend Subscription List, add/delete/confirm, 4. The Stored Messagespsent by friend nodes to Low Power node. The corresponding friendship messages encrypted with the master security material: 1. Friend Clear, 2. Friend Clear Confirm. Based on the setup of the applications, the messages sent from the Low Power node to the friend nodes will be encrypted with the friendship security material or master security material, with the former being used by the messages transmitted between Low Power node and friend nodes and the latter being used by other network messages.

Table 17: Table 7 ESP-BLE-MESH Terminology - Message

Term Official Definition

ReassemblSyegmentation and reassembly (SAR) is

/ Seg- a method of communication network,

menta- which is divided into small units before

tion

transmitting packets and reassembled

in a proper order at the communication

receiving end.

Detailed Explanation The lower transport layer will automatically segment the message whose size is too big. The receiving end will return a response message, and the transmitting end will send the data packet again that the receiving end does not receive according to the response message. This is automatically completed by the lower transport layer. Unsegmented messages have at most 15 bytes, of which 4 bytes are transMIC, so the remaining is 11 bytes; in the case of segmentation, there are 12 valid bytes in the first several packets, and 8 in the last one. Special case: A shorter packet requires mandatory segmentation from lower transport layer, in which case the valid byte is 8 bytes.

UnacknowTlehdegreedare two types of messages: Un/ Ac- acknowledged or Acknowledged knowledged

Based on the whether or not the receiving end needs to send the response message, the messages sent are divided into two kinds. The sending end should set the maximum number of retransmission.

Espressif Systems

1715

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Table 18: Table 8 ESP-BLE-MESH Terminology - Foundation Models

Term Official Definition ConfiguratTiohnis model is used to represent a mesh Server network configuration of a device. Model

Detailed Explanation The node must contain the Configuration Server Model, which is responsible for maintaining configuration-related states. The states that Configuration Server Model maintains include: NetKey List, AppKey List, Model to AppKey List, Node Identity, Key Refresh Phase, Heartbeat Publish, Heartbeat Subscription, Network Transmit, Relay Retransmit etc.

ConfiguratTiohne model is used to represent an eleClient ment that can control and monitor the Model configuration of a node.

The Configuration Client Model uses messages to control the state maintained by the Configuration Server Model. The Provisioner must contain the Configuration Client Model, with which the configuration messages, like Configuration Composition Data Get can be sent.

Health Server Model

This model is used to represent a mesh network diagnostics of a device.

The Health Server Model is primarily used by devices to check their states and see if there is an error. The states maintained by Health Server model include: Current Fault, Registered Fault, Health Period, and Attention Timer.

Health Client Model

The model is used to represent an ele- The Health Client Model uses messages to control the state

ment that can control and monitor the maintained by the Health Server Model. The model can get

health of a node.

the self-test information of other nodes through the message

oHealth Fault Getp.

Term Key Refresh procedure
IV (Initialisation Vector) Update Procedure

Table 19: Table 9 ESP-BLE-MESH Terminology - Network Management

Official Definition

Detailed Explanation

This procedure is used when the secu- Key Refresh Procedure is used to update network key and

rity of one or more network keys and/or application key of ESP-BLE-MESH network. Key Refresh

one or more of the application keys has Procedure is used when the security of one or more network

been compromised or could be com- keys and/or one or more application keys is threatened or

promised.

potentially threatened. Keys are usually updated after some

nodes in the network are removed.

A node can also use an IV Update pro- The IV Update procedure is used to update the value of ESP-

cedure to signal to peer nodes that it is BLE-MESH networkns IV Index. This value is related to

updating the IV Index.

the random number required for message encryption. To en-

sure that the value of the random number is not repeated, this

value is periodically incremented. IV Index is a 32-bit value

and a shared network resource. For example, all nodes in a

mesh network share the same IV Index value. Starting from

0x00000000, the IV Index increments during the IV Update

procedure and maintained by a specific process, ensuring the

IV Index shared in the mesh network is the same. This can be

done when the node believes that it has the risk of exhaust-

ing its sequence number, or when it determines that another

node is nearly exhausting its sequence number. Note: The

update time must not be less than 96 hours. It can be trig-

gered when a secure network beacon is received, or when the

node determines that its sequence number is greater than a

certain value.

For more terms, please see: ESP-BLE-MESH Glossary of Terms.

Bluetooth SIG Documentation
· BLE Mesh Core Specification · BLE Mesh Model Specification · An Intro to Bluetooth Mesh Part 1 / Part 2

Espressif Systems

1716

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· The Fundamental Concepts of Bluetooth Mesh Networking, Part 1 / Part 2 · Bluetooth Mesh Networking: Friendship · Management of Devices in a Bluetooth Mesh Network · Bluetooth Mesh Security Overview · Provisioning a Bluetooth Mesh Network Part 1 / Part 2
4.10 ESP-WIFI-MESH
This guide provides information regarding the ESP-WIFI-MESH protocol. Please see the ESP-WIFI-MESH API Reference for more information about API usage.
4.10.1 Overview
ESP-WIFI-MESH is a networking protocol built atop the Wi-Fi protocol. ESP-WIFI-MESH allows numerous devices (henceforth referred to as nodes) spread over a large physical area (both indoors and outdoors) to be interconnected under a single WLAN (Wireless Local-Area Network). ESP-WIFI-MESH is self-organizing and self-healing meaning the network can be built and maintained autonomously. The ESP-WIFI-MESH guide is split into the following sections:
1. Introduction 2. ESP-WIFI-MESH Concepts 3. Building a Network 4. Managing a Network 5. Data Transmission 6. Channel Switching 7. Performance 8. Further Notes
4.10.2 Introduction

Fig. 16: Traditional Wi-Fi Network Architecture
A traditional infrastructure Wi-Fi network is a point-to-multipoint network where a single central node known as the access point (AP) is directly connected to all other nodes known as stations. The AP is responsible for arbitrating and

Espressif Systems

1717

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides forwarding transmissions between the stations. Some APs also relay transmissions to/from an external IP network via a router. Traditional infrastructure Wi-Fi networks suffer the disadvantage of limited coverage area due to the requirement that every station must be in range to directly connect with the AP. Furthermore, traditional Wi-Fi networks are susceptible to overloading as the maximum number of stations permitted in the network is limited by the capacity of the AP.
Fig. 17: ESP-WIFI-MESH Network Architecture ESP-WIFI-MESH differs from traditional infrastructure Wi-Fi networks in that nodes are not required to connect to a central node. Instead, nodes are permitted to connect with neighboring nodes. Nodes are mutually responsible for relaying each others transmissions. This allows an ESP-WIFI-MESH network to have much greater coverage area as nodes can still achieve interconnectivity without needing to be in range of the central node. Likewise, ESP-WIFIMESH is also less susceptible to overloading as the number of nodes permitted on the network is no longer limited by a single central node.
4.10.3 ESP-WIFI-MESH Concepts

Espressif Systems

1718

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Terminology

Term Node Root Node Child Node
Parent Node Descendant Node Sibling Nodes Connection
Upstream Connection Downstream Connection Wireless Hop
Subnetwork
MAC Address DS

Description Any device that is or can be part of an ESP-WIFI-MESH network The top node in the network A node X is a child node when it is connected to another node Y where the connection makes node X more distant from the root node than node Y (in terms of number of connections). The converse notion of a child node Any node reachable by repeated proceeding from parent to child Nodes that share the same parent node A traditional Wi-Fi association between an AP and a station. A node in ESP-WIFIMESH will use its station interface to associate with the softAP interface of another node, thus forming a connection. The connection process includes the authentication and association processes in Wi-Fi. The connection from a node to its parent node The connection from a node to one of its child nodes The portion of the path between source and destination nodes that corresponds to a single wireless connection. A data packet that traverses a single connection is known as single-hop whereas traversing multiple connections is known as multi-hop. A subnetwork is subdivision of an ESP-WIFI-MESH network which consists of a node and all of its descendant nodes. Therefore the subnetwork of the root node consists of all nodes in an ESP-WIFI-MESH network. Media Access Control Address used to uniquely identify each node or router within an ESP-WIFI-MESH network. Distribution System (External IP Network)

Tree Topology
ESP-WIFI-MESH is built atop the infrastructure Wi-Fi protocol and can be thought of as a networking protocol that combines many individual Wi-Fi networks into a single WLAN. In Wi-Fi, stations are limited to a single connection with an AP (upstream connection) at any time, whilst an AP can be simultaneously connected to multiple stations (downstream connections). However ESP-WIFI-MESH allows nodes to simultaneously act as a station and an AP. Therefore a node in ESP-WIFI-MESH can have multiple downstream connections using its softAP interface, whilst simultaneously having a single upstream connection using its station interface. This naturally results in a tree network topology with a parent-child hierarchy consisting of multiple layers.
ESP-WIFI-MESH is a multiple hop (multi-hop) network meaning nodes can transmit packets to other nodes in the network through one or more wireless hops. Therefore, nodes in ESP-WIFI-MESH not only transmit their own packets, but simultaneously serve as relays for other nodes. Provided that a path exists between any two nodes on the physical layer (via one or more wireless hops), any pair of nodes within an ESP-WIFI-MESH network can communicate.
Note: The size (total number of nodes) in an ESP-WIFI-MESH network is dependent on the maximum number of layers permitted in the network, and the maximum number of downstream connections each node can have. Both of these variables can be configured to limit the size of the network.

Node Types
Root Node: The root node is the top node in the network and serves as the only interface between the ESP-WIFIMESH network and an external IP network. The root node is connected to a conventional Wi-Fi router and relays packets to/from the external IP network to nodes within the ESP-WIFI-MESH network. There can only be one root node within an ESP-WIFI-MESH network and the root nodens upstream connection may only be with the router. Referring to the diagram above, node A is the root node of the network.

Espressif Systems

1719

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides Fig. 18: ESP-WIFI-MESH Tree Topology

Espressif Systems

Fig. 19: ESP-WIFI-MESH Node Types

1720

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Leaf Nodes: A leaf node is a node that is not permitted to have any child nodes (no downstream connections). Therefore a leaf node can only transmit or receive its own packets, but cannot forward the packets of other nodes. If a node is situated on the networkns maximum permitted layer, it will be assigned as a leaf node. This prevents the node from forming any downstream connections thus ensuring the network does not add an extra layer. Some nodes without a softAP interface (station only) will also be assigned as leaf nodes due to the requirement of a softAP interface for any downstream connections. Referring to the diagram above, nodes L/M/N are situated on the networks maximum permitted layer hence have been assigned as leaf nodes .
Intermediate Parent Nodes: Connected nodes that are neither the root node or a leaf node are intermediate parent nodes. An intermediate parent node must have a single upstream connection (a single parent node), but can have zero to multiple downstream connections (zero to multiple child nodes). Therefore an intermediate parent node can transmit and receive packets, but also forward packets sent from its upstream and downstream connections. Referring to the diagram above, nodes B to J are intermediate parent nodes. Intermediate parent nodes without downstream connections such as nodes E/F/G/I/J are not equivalent to leaf nodes as they are still permitted to form downstream connections in the future.
Idle Nodes: Nodes that have yet to join the network are assigned as idle nodes. Idle nodes will attempt to form an upstream connection with an intermediate parent node or attempt to become the root node under the correct circumstances (see Automatic Root Node Selection). Referring to the diagram above, nodes K and O are idle nodes.
Beacon Frames & RSSI Thresholding
Every node in ESP-WIFI-MESH that is able to form downstream connections (i.e. has a softAP interface) will periodically transmit Wi-Fi beacon frames. A node uses beacon frames to allow other nodes to detect its presence and know of its status. Idle nodes will listen for beacon frames to generate a list of potential parent nodes, one of which the idle node will form an upstream connection with. ESP-WIFI-MESH uses the Vendor Information Element to store metadata such as:
· Node Type (Root, Intermediate Parent, Leaf, Idle) · Current layer of Node · Maximum number of layers permitted in the network · Current number of child nodes · Maximum number of downstream connections to accept
The signal strength of a potential upstream connection is represented by RSSI (Received Signal Strength Indication) of the beacon frames of the potential parent node. To prevent nodes from forming a weak upstream connection, ESP-WIFI-MESH implements an RSSI threshold mechanism for beacon frames. If a node detects a beacon frame with an RSSI below a preconfigured threshold, the transmitting node will be disregarded when forming an upstream connection.
Panel A of the illustration above demonstrates how the RSSI threshold affects the number of parent node candidates an idle node has.
Panel B of the illustration above demonstrates how an RF shielding object can lower the RSSI of a potential parent node. Due to the RF shielding object, the area in which the RSSI of node X is above the threshold is significantly reduced. This causes the idle node to disregard node X even though node X is physically adjacent. The idle node will instead form an upstream connection with the physically distant node Y due to a stronger RSSI.
Note: Nodes technically still receive all beacon frames on the MAC layer. The RSSI threshold is an ESP-WIFIMESH feature that simply filters out all received beacon frames that are below the preconfigured threshold.

Preferred Parent Node
When an idle node has multiple parent nodes candidates (potential parent nodes), the idle node will form an upstream connection with the preferred parent node. The preferred parent node is determined based on the following criteria:
· Which layer the parent node candidate is situated on · The number of downstream connections (child nodes) the parent node candidate currently has

Espressif Systems

1721

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 20: Effects of RSSI Thresholding
The selection of the preferred parent node will always prioritize the parent node candidate on the shallowest layer of the network (including the root node). This helps minimize the total number of layers in an ESP-WIFI-MESH network when upstream connections are formed. For example, given a second layer node and a third layer node, the second layer node will always be preferred.
If there are multiple parent node candidates within the same layer, the parent node candidate with the least child nodes will be preferred. This criteria has the effect of balancing the number of downstream connections amongst nodes of the same layer.

Fig. 21: Preferred Parent Node Selection
Panel A of the illustration above demonstrates an example of how the idle node G selects a preferred parent node given the five parent node candidates B/C/D/E/F. Nodes on the shallowest layer are preferred, hence nodes B/C are prioritized since they are second layer nodes whereas nodes D/E/F are on the third layer. Node C is selected as the preferred parent node due it having fewer downstream connections (fewer child nodes) compared to node B.
Panel B of the illustration above demonstrates the case where the root node is within range of the idle node G. In

Espressif Systems

1722

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
other words, the root nodens beacon frames are above the RSSI threshold when received by node G. The root node is always the shallowest node in an ESP-WIFI-MESH network hence is always the preferred parent node given multiple parent node candidates.
Note: Users may also define their own algorithm for selecting a preferred parent node, or force a node to only connect with a specific parent node (see the Mesh Manual Networking Example).
Routing Tables
Each node within an ESP-WIFI-MESH network will maintain its individual routing table used to correctly route ESPWIFI-MESH packets (see ESP-WIFI-MESH Packet) to the correct destination node. The routing table of a particular node will consist of the MAC addresses of all nodes within the particular nodens subnetwork (including the MAC address of the particular node itself). Each routing table is internally partitioned into multiple subtables with each subtable corresponding to the subnetwork of each child node.

Fig. 22: ESP-WIFI-MESH Routing Tables Example
Using the diagram above as an example, the routing table of node B would consist of the MAC addresses of nodes B to I (i.e. equivalent to the subnetwork of node B). Node Bns routing table is internally partitioned into two subtables containing of nodes C to F and nodes G to I (i.e. equivalent to the subnetworks of nodes C and G respectively).
ESP-WIFI-MESH utilizes routing tables to determine whether an ESP-WIFI-MESH packet should be forwarded upstream or downstream based on the following rules.
1. If the packetns destination MAC address is within the current nodens routing table and is not the current node, select the subtable that contains the destination MAC address and forward the data packet downstream to the child node corresponding to the subtable.
2. If the destination MAC address is not within the current nodens routing table, forward the data packet upstream to the current nodens parent node. Doing so repeatedly will result in the packet arriving at the root node where the routing table should contain all nodes within the network.

Note:

Users can call esp_mesh_get_routing_table() to obtain a nodens routing ta-

ble, or esp_mesh_get_routing_table_size() to obtain the size of a nodens routing table.

esp_mesh_get_subnet_nodes_list() can be used to obtain the corresponding subtable of a spe-

cific child node. Likewise esp_mesh_get_subnet_nodes_num() can be used to obtain the size of the

Espressif Systems

1723

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
subtable.
4.10.4 Building a Network
General Process
Warning: Before the ESP-WIFI-MESH network building process can begin, certain parts of the configuration must be uniform across each node in the network (see mesh_cfg_t). Each node must be configured with the same Mesh Network ID, router configuration, and softAP configuration.
An ESP-WIFI-MESH network building process involves selecting a root node, then forming downstream connections layer by layer until all nodes have joined the network. The exact layout of the network can be dependent on factors such as root node selection, parent node selection, and asynchronous power-on reset. However, the ESP-WIFI-MESH network building process can be generalized into the following steps:

Fig. 23: ESP-WIFI-MESH Network Building Process

1. Root Node Selection The root node can be designated during configuration (see section on User Designated Root Node), or dynamically elected based on the signal strength between each node and the router (see Automatic Root Node Selection). Once selected, the root node will connect with the router and begin allowing downstream connections to form. Referring to the figure above, node A is selected to be the root node hence node A forms an upstream connection with the router.

2. Second Layer Formation Once the root node has connected to the router, idle nodes in range of the root node will begin connecting with the root node thereby forming the second layer of the network. Once connected, the second layer nodes become intermediate parent nodes (assuming maximum permitted layers > 2) hence the next layer to form. Referring to the figure above, nodes B to D are in range of the root node. Therefore nodes B to D form upstream connections with the root node and become intermediate parent nodes.

3. Formation of remaining layers The remaining idle nodes will connect with intermediate parent nodes within range thereby forming a new layer in the network. Once connected, the idles nodes become intermediate parent node or leaf nodes depending on the networks maximum permitted layers. This step is repeated until there are no more idle

Espressif Systems

1724

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
nodes within the network or until the maximum permitted layer of the network has been reached. Referring to the figure above, nodes E/F/G connect with nodes B/C/D respectively and become intermediate parent nodes themselves.
4. Limiting Tree Depth To prevent the network from exceeding the maximum permitted number of layers, nodes on the maximum layer will automatically become leaf nodes once connected. This prevents any other idle node from connecting with the leaf node thereby prevent a new layer form forming. However if an idle node has no other potential parent node, it will remain idle indefinitely. Referring to the figure above, the networkns number of maximum permitted layers is set to four. Therefore when node H connects, it becomes a leaf node to prevent any downstream connections from forming.
Automatic Root Node Selection
The automatic selection of a root node involves an election process amongst all idle nodes based on their signal strengths with the router. Each idle node will transmit their MAC addresses and router RSSI values via Wi-Fi beacon frames. The MAC address is used to uniquely identify each node in the network whilst the router RSSI is used to indicate a nodens signal strength with reference to the router.
Each node will then simultaneously scan for the beacon frames from other idle nodes. If a node detects a beacon frame with a stronger router RSSI, the node will begin transmitting the contents of that beacon frame (i.e. voting for the node with the stronger router RSSI). The process of transmission and scanning will repeat for a preconfigured minimum number of iterations (10 iterations by default) and result in the beacon frame with the strongest router RSSI being propagated throughout the network.
After all iterations, each node will individually check for its vote percentage (number of votes/number of nodes participating in election) to determine if it should become the root node. If a node has a vote percentage larger than a preconfigured threshold (90% by default), the node will become a root node.
The following diagram demonstrates how an ESP-WIFI-MESH network is built when the root node is automatically selected.

Fig. 24: Root Node Election Example
1. On power-on reset, each node begins transmitting beacon frames consisting of their own MAC addresses and their router RSSIs. 2. Over multiple iterations of transmission and scanning, the beacon frame with the strongest router RSSI is propagated throughout the network. Node C has the strongest router RSSI (-10 dB) hence its beacon frame is propagated

Espressif Systems

1725

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

throughout the network. All nodes participating in the election vote for node C thus giving node C a vote percentage of 100%. Therefore node C becomes a root node and connects with the router.
3. Once Node C has connected with the router, nodes A/B/D/E connectwith node C as it is the preferred parent node (i.e. the shallowest node). Nodes A/B/D/E form the second layer of the network.
4. Node F and G connect with nodes D and E respectively and the network building process is complete.

Note:

The minimum number of iterations for the election process can be configured using

esp_mesh_set_attempts(). Users should adjust the number of iterations based on the number of

nodes within the network (i.e. the larger the network the larger number of scan iterations required).

Warning:

Vote percentage threshold can also be configured using

esp_mesh_set_vote_percentage(). Setting a low vote percentage threshold can result in two

or more nodes becoming root nodes within the same ESP-WIFI-MESH network leading to the building of

multiple networks. If such is the case, ESP-WIFI-MESH has internal mechanisms to autonomously resolve the

root node conflict. The networks of the multiple root nodes will be combined into a single network with a single

root node. However, root node conflicts where two or more root nodes have the same router SSID but different

router BSSID are not handled.

User Designated Root Node
The root node can also be designated by user which will entail the designated root node to directly connect with the router and forgo the election process. When a root node is designated, all other nodes within the network must also forgo the election process to prevent the occurrence of a root node conflict. The following diagram demonstrates how an ESP-WIFI-MESH network is built when the root node is designated by the user.

Fig. 25: Root Node Designation Example (Root Node = A, Max Layers = 4)
1. Node A is designated the root node by the user therefore directly connects with the router. All other nodes forgo the election process. 2. Nodes C/D connect with node A as their preferred parent node. Both nodes form the second layer of the network.

Espressif Systems

1726

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
3. Likewise, nodes B/E connect with node C, and node F connects with node D. Nodes B/E/F form the third layer of the network.
4. Node G connects with node E, forming the fourth layer of the network. However the maximum permitted number of layers in this network is configured as four, therefore node G becomes a leaf node to prevent any new layers from forming.
Note: When designating a root node, the root node should call esp_mesh_set_parent() in order to directly connect with the router. Likewise, all other nodes should call esp_mesh_fix_root() to forgo the election process.
Parent Node Selection
By default, ESP-WIFI-MESH is self organizing meaning that each node will autonomously select which potential parent node to form an upstream connection with. The autonomously selected parent node is known as the preferred parent node. The criteria used for selecting the preferred parent node is designed to reduce the number of layers in the ESP-WIFI-MESH network and to balance the number of downstream connections between potential parent nodes (see section on Preferred Parent Node).
However ESP-WIFI-MESH also allows users to disable self-organizing behavior which will allow users to define their own criteria for parent node selection, or to configure nodes to have designated parent nodes (see the Mesh Manual Networking Example).
Asynchronous Power-on Reset
ESP-WIFI-MESH network building can be affected by the order in which nodes power-on. If certain nodes within the network power-on asynchronously (i.e. separated by several minutes), the final structure of the network could differ from the ideal case where all nodes are powered on synchronously. Nodes that are delayed in powering on will adhere to the following rules:
Rule 1: If a root node already exists in the network, the delayed node will not attempt to elect a new root node, even if it has a stronger RSSI with the router. The delayed node will instead join the network like any other idle node by connecting with a preferred parent node. If the delayed node is the designated root node, all other nodes in the network will remain idle until the delayed node powers-on.
Rule 2: If a delayed node forms an upstream connection and becomes an intermediate parent node, it may also become the new preferred parent of other nodes (i.e. being a shallower node). This will cause the other nodes to switch their upstream connections to connect with the delayed node (see Parent Node Switching).
Rule 3: If an idle node has a designated parent node which is delayed in powering-on, the idle node will not attempt to form any upstream connections in the absence of its designated parent node. The idle node will remain idle indefinitely until its designated parent node powers-on.
The following example demonstrates the effects of asynchronous power-on with regards to network building.
1. Nodes A/C/D/F/G/H are powered-on synchronously and begin the root node election process by broadcasting their MAC addresses and router RSSIs. Node A is elected as the root node as it has the strongest RSSI.
2. Once node A becomes the root node, the remaining nodes begin forming upstream connections layer by layer with their preferred parent nodes. The result is a network with five layers.
3. Node B/E are delayed in powering-on but neither attempt to become the root node even though they have stronger router RSSIs (-20 dB and -10 dB) compared to node A. Instead both delayed nodes form upstream connections with their preferred parent nodes A and C respectively. Both nodes B/E become intermediate parent nodes after connecting.
4. Nodes D/G switch their upstream connections as node B is the new preferred parent node due to it being on a shallower layer (second layer node). Due to the switch, the resultant network has three layers instead of the original five layers.

Espressif Systems

1727

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 26: Network Building with Asynchronous Power On Example

Espressif Systems

1728

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Synchronous Power-On: Had all nodes powered-on synchronously, node E would have become the root node as it has the strongest router RSSI (-10 dB). This would result in a significantly different network layout compared to the network formed under the conditions of asynchronous power-on. However the synchronous power-on network layout can still be reached if the user manually switches the root node (see esp_mesh_waive_root()).
Note: Differences in parent node selection caused by asynchronous power-on are autonomously corrected for to some extent in ESP-WIFI-MESH (see Parent Node Switching)
Loop-back Avoidance, Detection, and Handling
A loop-back is the situation where a particular node forms an upstream connection with one of its descendant nodes (a node within the particular nodens subnetwork). This results in a circular connection path thereby breaking the tree topology. ESP-WIFI-MESH prevents loop-back during parent selection by excluding nodes already present in the selecting nodens routing table (see Routing Tables) thus prevents a particular node from attempting to connect to any node within its subnetwork. In the event that a loop-back occurs, ESP-WIFI-MESH utilizes a path verification mechanism and energy transfer mechanism to detect the loop-back occurrence. The parent node of the upstream connection that caused the loopback will then inform the child node of the loop-back and initiate a disconnection.
4.10.5 Managing a Network
ESP-WIFI-MESH is a self healing network meaning it can detect and correct for failures in network routing. Failures occur when a parent node with one or more child nodes breaks down, or when the connection between a parent node and its child nodes becomes unstable. Child nodes in ESP-WIFI-MESH will autonomously select a new parent node and form an upstream connection with it to maintain network interconnectivity. ESP-WIFI-MESH can handle both Root Node Failures and Intermediate Parent Node Failures.
Root Node Failure
If the root node breaks down, the nodes connected with it (second layer nodes) will promptly detect the failure of the root node. The second layer nodes will initially attempt to reconnect with the root node. However after multiple failed attempts, the second layer nodes will initialize a new round of root node election. The second layer node with the strongest router RSSI will be elected as the new root node whilst the remaining second layer nodes will form an upstream connection with the new root node (or a neighboring parent node if not in range). If the root node and multiple downstream layers simultaneously break down (e.g. root node, second layer, and third layer), the shallowest layer that is still functioning will initialize the root node election. The following example illustrates an example of self healing from a root node break down. 1. Node C is the root node of the network. Nodes A/B/D/E are second layer nodes connected to node C. 2. Node C breaks down. After multiple failed attempts to reconnect, the second layer nodes begin the election process by broadcasting their router RSSIs. Node B has the strongest router RSSI. 3. Node B is elected as the root node and begins accepting downstream connections. The remaining second layer nodes A/D/E form upstream connections with node B thus the network is healed and can continue operating normally.
Note: If a designated root node breaks down, the remaining nodes will not autonomously attempt to elect a new root node as an election process will never be attempted whilst a designated root node is used.

Espressif Systems

1729

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 27: Self Healing From Root Node Failure
Intermediate Parent Node Failure
If an intermediate parent node breaks down, the disconnected child nodes will initially attempt to reconnect with the parent node. After multiple failed attempts to reconnect, each child node will begin to scan for potential parent nodes (see Beacon Frames & RSSI Thresholding). If other potential parent nodes are available, each child node will individually select a new preferred parent node (see Preferred Parent Node) and form an upstream connection with it. If there are no other potential parent nodes for a particular child node, it will remain idle indefinitely. The following diagram illustrates an example of self healing from an Intermediate Parent Node break down.

Fig. 28: Self Healing From Intermediate Parent Node Failure
1. The following branch of the network consists of nodes A to G. 2. Node C breaks down. Nodes F/G detect the break down and attempt to reconnect with node C. After multiple failed attempts to reconnect, nodes F/G begin to select a new preferred parent node. 3. Node G is out of range from any other parent node hence remains idle for the time being. Node F is in range of nodes B/E, however node B is selected as it is the shallower node. Node F becomes an intermediate parent node after connecting with Node B thus node G can connect with node F. The network is healed, however the network routing as been affected and an extra layer has been added.
Note: If a child node has a designated parent node that breaks down, the child node will make no attempt to connect with a new parent node. The child node will remain idle indefinitely.

Espressif Systems

1730

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Root Node Switching
ESP-WIFI-MESH does not automatically switch the root node unless the root node breaks down. Even if the root nodens router RSSI degrades to the point of disconnection, the root node will remain unchanged. Root node switching is the act of explicitly starting a new election such that a node with a stronger router RSSI will be elected as the new root node. This can be a useful method of adapting to degrading root node performance.
To trigger a root node switch, the current root node must explicitly call esp_mesh_waive_root() to trigger a new election. The current root node will signal all nodes within the network to begin transmitting and scanning for beacon frames (see Automatic Root Node Selection) whilst remaining connected to the network (i.e. not idle). If another node receives more votes than the current root node, a root node switch will be initiated. The root node will remain unchanged otherwise.
A newly elected root node sends a switch request to the current root node which in turn will respond with an acknowledgment signifying both nodes are ready to switch. Once the acknowledgment is received, the newly elected root node will disconnect from its parent and promptly form an upstream connection with the router thereby becoming the new root node of the network. The previous root node will disconnect from the router whilst maintaining all of its downstream connections and enter the idle state. The previous root node will then begin scanning for potential parent nodes and selecting a preferred parent.
The following diagram illustrates an example of a root node switch.

Fig. 29: Root Node Switch Example
1. Node C is the current root node but has degraded signal strength with the router (-85db). The node C triggers a new election and all nodes begin transmitting and scanning for beacon frames whilst still being connected.
2. After multiple rounds of transmission and scanning, node B is elected as the new root node. Node B sends node C a switch request and node C responds with an acknowledgment.
3. Node B disconnects from its parent and connects with the router becoming the networkns new root node. Node C disconnects from the router, enters the idle state, and begins scanning for and selecting a new preferred parent node. Node C maintains all its downstream connections throughout this process.
4. Node C selects node B as its preferred parent node, forms an upstream connection, and becomes a second layer node. The network layout is similar after the switch as node C still maintains the same subnetwork. However each node in node Cns subnetwork has been placed one layer deeper as a result of the switch. Parent Node Switching may adjust the network layout afterwards if any nodes have a new preferred parent node as a result of the root node switch.

Espressif Systems

1731

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Note: Root node switching must require an election hence is only supported when using a self-organized ESP-WIFIMESH network. In other words, root node switching cannot occur if a designated root node is used.
Parent Node Switching
Parent Node Switching entails a child node switching its upstream connection to another parent node of a shallower layer. Parent Node Switching occurs autonomously meaning that a child node will change its upstream connection automatically if a potential parent node of a shallower layer becomes available (i.e. due to a Asynchronous Power-on Reset). All potential parent nodes periodically transmit beacon frames (see Beacon Frames & RSSI Thresholding) allowing for a child node to scan for the availability of a shallower parent node. Due to parent node switching, a self-organized ESP-WIFI-MESH network can dynamically adjust its network layout to ensure each connection has a good RSSI and that the number of layers in the network is minimized.
4.10.6 Data Transmission
ESP-WIFI-MESH Packet
ESP-WIFI-MESH network data transmissions use ESP-WIFI-MESH packets. ESP-WIFI-MESH packets are entirely contained within the frame body of a Wi-Fi data frame. A multi-hop data transmission in an ESP-WIFIMESH network will involve a single ESP-WIFI-MESH packet being carried over each wireless hop by a different Wi-Fi data frame. The following diagram shows the structure of an ESP-WIFI-MESH packet and its relation with a Wi-Fi data frame.

Fig. 30: ESP-WIFI-MESH Packet
The header of an ESP-WIFI-MESH packet contains the MAC addresses of the source and destination nodes. The options field contains information pertaining to the special types of ESP-WIFI-MESH packets such as a group transmission or a packet originating from the external IP network (see MESH_OPT_SEND_GROUP and MESH_OPT_RECV_DS_ADDR).
The payload of an ESP-WIFI-MESH packet contains the actual application data. This data can be raw binary data, or encoded under an application layer protocol such as HTTP, MQTT, and JSON (see mesh_proto_t).
Note: When sending an ESP-WIFI-MESH packet to the external IP network, the destination address field of the header will contain the IP address and port of the target server rather than the MAC address of a node (see mesh_addr_t). Furthermore the root node will handle the formation of the outgoing TCP/IP packet.

Group Control & Multicasting
Multicasting is a feature that allows a single ESP-WIFI-MESH packet to be transmitted simultaneously to multiple nodes within the network. Multicasting in ESP-WIFI-MESH can be achieved by either specifying a list

Espressif Systems

1732

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
of target nodes, or specifying a preconfigured group of nodes. Both methods of multicasting are called via esp_mesh_send().
To multicast by specifying a list of target nodes, users must first set the ESP-WIFI-MESH packetns destination address to the Multicast-Group Address (01:00:5E:xx:xx:xx). This signifies that the ESP-WIFIMESH packet is a multicast packet with a group of addresses, and that the address should be obtained from the header options. Users must then list the MAC addresses of the target nodes as options (see mesh_opt_t and MESH_OPT_SEND_GROUP). This method of multicasting requires no prior setup but can incur a large amount of overhead data as each target nodens MAC address must be listed in the options field of the header.
Multicasting by group allows a ESP-WIFI-MESH packet to be transmitted to a preconfigured group of nodes. Each grouping is identified by a unique ID, and a node can be placed into a group via esp_mesh_set_group_id(). Multicasting to a group involves setting the destination address of the ESP-WIFI-MESH packet to the target group ID. Furthermore, the MESH_DATA_GROUP flag must set. Using groups to multicast incurs less overhead, but requires nodes to previously added into groups.
Note: During a multicast, all nodes within the network still receive the ESP-WIFI-MESH packet on the MAC layer. However, nodes not included in the MAC address list or the target group will simply filter out the packet.

Broadcasting
Broadcasting is a feature that allows a single ESP-WIFI-MESH packet to be transmitted simultaneously to all nodes within the network. Each node essentially forwards a broadcast packet to all of its upstream and downstream connections such that the packet propagates throughout the network as quickly as possible. However, ESP-WIFI-MESH utilizes the following methods to avoid wasting bandwidth during a broadcast.
1. When an intermediate parent node receives a broadcast packet from its parent, it will forward the packet to each of its child nodes whilst storing a copy of the packet for itself.
2. When an intermediate parent node is the source node of the broadcast, it will transmit the broadcast packet upstream to is parent node and downstream to each of its child nodes.
3. When an intermediate parent node receives a broadcast packet from one of its child nodes, it will forward the packet to its parent node and each of its remaining child nodes whilst storing a copy of the packet for itself.
4. When a leaf node is the source node of a broadcast, it will directly transmit the packet to its parent node.
5. When the root node is the source node of a broadcast, the root node will transmit the packet to all of its child nodes.
6. When the root node receives a broadcast packet from one of its child nodes, it will forward the packet to each of its remaining child nodes whilst storing a copy of the packet for itself.
7. When a node receives a broadcast packet with a source address matching its own MAC address, the node will discard the broadcast packet.
8. When an intermediate parent node receives a broadcast packet from its parent node which was originally transmitted from one of its child nodes, it will discard the broadcast packet
Upstream Flow Control
ESP-WIFI-MESH relies on parent nodes to control the upstream data flow of their immediate child nodes. To prevent a parent nodens message buffer from overflowing due to an overload of upstream transmissions, a parent node will allocate a quota for upstream transmissions known as a receiving window for each of its child nodes. Each child node must apply for a receiving window before it is permitted to transmit upstream. The size of a receiving window can be dynamically adjusted. An upstream transmission from a child node to the parent node consists of the following steps:
1. Before each transmission, the child node sends a window request to its parent node. The window request consists of a sequence number which corresponds to the child nodens data packet that is pending transmission.

Espressif Systems

1733

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
2. The parent node receives the window request and compares the sequence number with the sequence number of the previous packet sent by the child node. The comparison is used to calculate the size of the receiving window which is transmitted back to the child node. 3. The child node transmits the data packet in accordance with the window size specified by the parent node. If the child node depletes its receiving window, it must obtain another receiving windows by sending a request before it is permitted to continue transmitting.
Note: ESP-WIFI-MESH does not support any downstream flow control.
Warning: Due to Parent Node Switching, packet loss may occur during upstream transmissions.
Due to the fact that the root node acts as the sole interface to an external IP network, it is critical that downstream nodes are aware of the root nodens connection status with the external IP network. Failing to do so can lead to nodes attempting to pass data upstream to the root node whilst it is disconnected from the IP network. This results in unnecessary transmissions and packet loss. ESP-WIFI-MESH address this issue by providing a mechanism to stabilize the throughput of outgoing data based on the connection status between the root node and the external IP network. The root node can broadcast its external IP network connection status to all other nodes by calling esp_mesh_post_toDS_state().
Bi-Directional Data Stream
The following diagram illustrates the various network layers involved in an ESP-WIFI-MESH Bidirectional Data Stream.

Fig. 31: ESP-WIFI-MESH Bidirectional Data Stream
Due to the use of Routing Tables, ESP-WIFI-MESH is able to handle pack forwarding entirely on the mesh layer. A TCP/IP layer is only required on the root node when it transmits/receives a packet to/from an external IP network.

4.10.7 Channel Switching
Background
In traditional Wi-Fi networks, channels are predetermined frequency ranges. In an infrastructure basic service set (BSS), the serving AP and its connected stations must be on the same operating channels (1 to 14) in which beacons are transmitted. Physically adjacent BSS (Basic Service Sets) operating on the same channel can lead to interference and degraded performance.

Espressif Systems

1734

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

In order to allow a BSS adapt to changing physical layer conditions and maintain performance, Wi-Fi contains mechanisms for network channel switching. A network channel switch is an attempt to move a BSS to a new operating channel whilst minimizing disruption to the BSS during this process. However it should be recognized that a channel switch may be unsuccessful in moving all stations to the new operating channel.
In an infrastructure Wi-Fi network, network channel switches are triggered by the AP with the aim of having the AP and all connected stations synchronously switch to a new channel. Network channel switching is implemented by embedding a Channel Switch Announcement (CSA) element within the APns periodically transmitted beacon frames. The CSA element is used to advertise to all connected stations regarding an upcoming network channel switch and will be included in multiple beacon frames up until the switch occurs.
A CSA element contains information regarding the New Channel Number and a Channel Switch Count which indicates the number of beacon frame intervals (TBTTs) remaining until the network channel switch occurs. Therefore, the Channel Switch Count is decremented every beacon frame and allows connected stations to synchronize their channel switch with the AP.
ESP-WIFI-MESH Network Channel Switching
ESP-WIFI-MESH Network Channel Switching also utilize beacon frames that contain a CSA element. However, being a multi-hop network makes the switching process in ESP-WIFI-MESH is more complex due to the fact that a beacon frame might not be able to reach all nodes within the network (i.e. in a single hop). Therefore, an ESP-WIFIMESH network relies on nodes to forward the CSA element so that it is propagated throughout the network.
When an intermediate parent node with one or more child nodes receives a beacon frame containing a CSA, the node will forward the CSA element by including the element in its next transmitted beacon frame (i.e. with the same New Channel Number and Channel Switch Count). Given that all nodes within an ESP-WIFI-MESH network receive the same CSA, the nodes can synchronize their channel switches using the Channel Switch Count, albeit with a short delay due to CSA element forwarding.
An ESP-WIFI-MESH network channel switch can be triggered by either the router or the root node.
Root Node Triggered A root node triggered channel switch can only occur when the ESP-WIFI-MESH network is not connected to a router. By calling esp_mesh_switch_channel(), the root node will set an initial Channel Switch Count value and begin including a CSA element in its beacon frames. Each CSA element is then received by second layer nodes, and forwarded downstream in the their own beacon frames.
Router Triggered When an ESP-WIFI-MESH network is connected to a router, the entire network must use the same channel as the router. Therefore, the root node will not be permitted to trigger a channel switch when it is connected to a router.
When the root node receives beacon frame containing a CSA element from the router, the root node will set Channel Switch Count value in the CSA element to a custom value before forwarding it downstream via beacon frames. It will also decrement the Channel Switch Count of subsequent CSA elements relative to the custom value. This custom value can be based on factors such as the number of network layers, the current number of nodes etc.
The setting the Channel Switch Count value to a custom value is due to the fact that the ESP-WIFI-MESH network and its router may have a different and varying beacon intervals. Therefore, the Channel Switch Count value provided by the router is irrelevant to an ESP-WIFI-MESH network. By using a custom value, nodes within the ESP-WIFI-MESH network are able to switch channels synchronously relative to the ESP-WIFI-MESH networkns beacon interval. However, this will also result in the ESP-WIFI-MESH networkns channel switch being unsynchronized with the channel switch of the router and its connected stations.
Impact of Network Channel Switching
· Due to the ESP-WIFI-MESH network channel switch being unsynchronized with the routerns channel switch, there w
­ The ESP-WIFI-MESH networkns channel switch time is dependent on the ESP-WIFI-MESH networkns beacon interval and the root nodens custom Channel Switch Count value.

Espressif Systems

1735

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
­ The channel discrepancy prevents any data exchange between the root node and the router during that ESP-WIFI-MESH networkns switch.
­ In the ESP-WIFI-MESH network, the root node and intermediate parent nodes will request their connected child nodes to stop transmissions until the channel switch takes place by setting the Channel Switch Mode field in the CSA element to 1.
­ Frequent router triggered network channel switches can degrade the ESP-WIFI-MESH networkn s performance. Note that this can be caused by the ESP-WIFI-MESH network itself (e.g. due to wireless medium contention with ESP-WIFI-MESH network). If this is the case, users should disable the automatic channel switching on the router and use a specified channel instead.
· When there is a temporary channel discrepancy, the root node remains technically connected to the router.
­ Disconnection occurs after the root node fails to receive any beacon frames or probe responses from the router over a fixed number of router beacon intervals.
­ Upon disconnection, the root node will automatically re-scan all channels for the presence of a router. · If the root node is unable to receive any of the routerns CSA beacon frames (e.g. due to short switch time given by the
­ After the router switches channels, the root node will no longer be able to receive the routerns beacon frames and probe responses and result in a disconnection after a fixed number of beacon intervals.
­ The root node will re-scan all channels for the router after disconnection. ­ The root node will maintain downstream connections throughout this process.
Note: Although ESP-WIFI-MESH network channel switching aims to move all nodes within the network to a new operating channel, it should be recognized that a channel switch might not successfully move all nodes (e.g. due to reasons such as node failures).
Channel and Router Switching Configuration
ESP-WIFI-MESH allows for autonomous channel switching to be enabled/disabled via configuration. Likewise, autonomous router switching (i.e. when a root node autonomously connects to another router) can also be enabled/disabled by configuration. Autonomous channel switching and router switching is dependent on the following configuration parameters and run-time conditions.
Allow Channel Switch: This parameter is set via the allow_channel_switch field of the mesh_cfg_t structure and permits an ESP-WIFI-MESH network to dynamically switch channels when set.
Preset Channel: An ESP-WIFI-MESH network can have a preset channel by setting the channel field of the mesh_cfg_t structure to the desired channel number. If this field is unset, the allow_channel_switch parameter is overridden such that channel switches are always permitted.
Allow Router Switch: This parameter is set via the allow_router_switch field of the mesh_router_t and permits an ESP-WIFI-MESH to dynamically switch to a different router when set.
Preset Router BSSID: An ESP-WIFI-MESH network can have a preset router by setting the bssid field of the mesh_router_t structure to the BSSID of the desired router. If this field is unset, the allow_router_switch parameter is overridden such that router switches are always permitted.
Root Node Present: The presence of a root node will can also affect whether or a channel or router switch is permitted.
The following table illustrates how the different combinations of parameters/conditions affect whether channel switching and/or router switching is permitted. Note that X represents a odonnt carepfor the parameter.

Espressif Systems

1736

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Preset Channel N
N N
Y
Y Y
Y Y Y Y
Y Y

Allow Channel Switch X
X X
Y
N N
Y N N Y
N N

Preset Router BSSID N
Y Y
N
N N
Y Y Y Y
Y Y

Allow Router Switch X
N Y
X
X X
N N N Y
Y Y

Root Node Present X
X X
X
N Y
X N Y X
N Y

Permitted Switches Channel and Router Channel Only Channel and Router Channel and Router Router Only Channel and Router Channel Only N Channel Only Channel and Router Router Only Channel and Router

4.10.8 Performance
The performance of an ESP-WIFI-MESH network can be evaluated based on multiple metrics such as the following:
Network Building Time: The amount of time taken to build an ESP-WIFI-MESH network from scratch.
Healing Time: The amount of time taken for the network to detect a node break down and carry out appropriate actions to heal the network (such as generating a new root node or forming new connections).
Per-hop latency: The latency of data transmission over one wireless hop. In other words, the time taken to transmit a data packet from a parent node to a child node or vice versa.
Network Node Capacity: The total number of nodes the ESP-WIFI-MESH network can simultaneously support. This number is determined by the maximum number of downstream connections a node can accept and the maximum number of layers permissible in the network.
The following table lists the common performance figures of an ESP-WIFI-MESH network:
· Network Building Time: < 60 seconds · Healing time:
­ Root node break down: < 10 seconds ­ Child node break down: < 5 seconds · Per-hop latency: 10 to 30 milliseconds
Note: The following test conditions were used to generate the performance figures above.
· Number of test devices: 100 · Maximum Downstream Connections to Accept: 6 · Maximum Permissible Layers: 6

Note: Throughput depends on packet error rate and hop count.

Note: The throughput of root nodens access to the external IP network is directly affected by the number of nodes in the ESP-WIFI-MESH network and the bandwidth of the router.

Espressif Systems

1737

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Note: The performance figures can vary greatly between installations based on network configuration and operating environment.

4.10.9 Further Notes
· Data transmission uses Wi-Fi WPA2-PSK encryption · Mesh networking IE uses AES encryption Router and internet icon made by Smashicons from www.flaticon.com

4.11 Core Dump
4.11.1 Overview
ESP-IDF provides support to generate core dumps on unrecoverable software errors. This useful technique allows post-mortem analysis of software state at the moment of failure. Upon the crash system enters panic state, prints some information and halts or reboots depending configuration. User can choose to generate core dump in order to analyse the reason of failure on PC later on. Core dump contains snapshots of all tasks in the system at the moment of failure. Snapshots include tasks control blocks (TCB) and stacks. So it is possible to find out what task, at what instruction (line of code) and what callstack of that task lead to the crash. It is also possible dumping variables content on demand if previously attributed accordingly. ESP-IDF provides special script espcoredump.py to help users to retrieve and analyse core dumps. This tool provides two commands for core dumps analysis:
· info_corefile - prints crashed taskns registers, callstack, list of available tasks in the system, memory regions and contents of memory stored in core dump (TCBs and stacks)
· dbg_corefile - creates core dump ELF file and runs GDB debug session with this file. User can examine memory, variables and tasks states manually. Note that since not all memory is saved in core dump only values of variables allocated on stack will be meaningful
For more information about core dump internals see the - Core dump internals

4.11.2 Configurations
There are a number of core dump related configuration options which user can choose in project configuration menu (idf.py menuconfig).
Core dump data destination (Components -> Core dump -> Data destination)
· Save core dump to Flash (Flash) · Print core dump to UART (UART) · Disable core dump generation (None)
Core dump data format (Components -> Core dump -> Core dump data format)
· ELF format (Executable and Linkable Format file for core dump) · Binary format (Basic binary format for core dump)
The ELF format contains extended features and allow to save more information about broken tasks and crashed software but it requires more space in the flash memory. This format of core dump is recommended for new software designs and is flexible enough to extend saved information for future revisions.
The Binary format is kept for compatibility standpoint, it uses less space in the memory to keep data and provides better performance.
Core dump data integrity check (Components -> Core dump -> Core dump data integrity check)
· Use CRC32 for core dump integrity verification

Espressif Systems

1738

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Maximum number of tasks snapshots in core dump (Components -> Core dump -> Maximum number of tasks)
Delay before core dump is printed to UART (Components -> Core dump -> Delay before print to UART)
The value is in ms.
Handling of UART core dumps in IDF Monitor (Components -> Core dump -> Delay before print to UART)
The value is base64 encoded.
· Decode and show summary (info_corefile) · Donnt decode

4.11.3 Save core dump to flash

When this option is selected core dumps are saved to special partition on flash. When using default partition table files which are provided with ESP-IDF it automatically allocates necessary space on flash, But if user wants to use its own layout file together with core dump feature it should define separate partition for core dump as it is shown below:

# Name, Type, SubType, Offset, Size

# Note: if you have increased the bootloader size, make sure to update the offsets

to avoid overlap

nvs,

data, nvs,

0x9000, 0x6000

phy_init, data, phy,

0xf000, 0x1000

factory, app, factory, 0x10000, 1M

coredump, data, coredump,,

64K

There are no special requirements for partition name. It can be chosen according to the user application needs, but partition type should be mdatanand sub-type should be mcoredumpn. Also when choosing partition size note that core dump data structure introduces constant overhead of 20 bytes and per-task overhead of 12 bytes. This overhead does not include size of TCB and stack for every task. So partition size should be at least 20 + max tasks number x (12 + TCB size + max task stack size) bytes.
The example of generic command to analyze core dump from flash is:
espcoredump.py -p </path/to/serial/port> info_corefile </path/to/program/elf/file>

or espcoredump.py -p </path/to/serial/port> dbg_corefile </path/to/program/elf/file>

4.11.4 Print core dump to UART
When this option is selected base64-encoded core dumps are printed on UART upon system panic. In this case user should save core dump text body to some file manually and then run the following command: espcoredump.py --chip esp32s3 info_corefile -t b64 -c </path/to/saved/base64/text> </path/to/program/elf/file>
or espcoredump.py --chip esp32s3 dbg_corefile -t b64 -c </path/to/saved/base64/text> </path/to/program/elf/file>
Base64-encoded body of core dump will be between the following header and footer: ================= CORE DUMP START ================= <body of base64-encoded core dump, save it to file on disk> ================= CORE DUMP END ===================
The CORE DUMP START and CORE DUMP END lines must not be included in core dump text file.

Espressif Systems

1739

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.11.5 ROM Functions in Backtraces
It is possible situation that at the moment of crash some tasks or/and crashed task itself have one or more ROM functions in their callstacks. Since ROM is not part of the program ELF it will be impossible for GDB to parse such callstacks, because it tries to analyse functionsnprologues to accomplish that. In that case callstack printing will be broken with error message at the first ROM function. To overcome this issue you can use ROM ELF provided by Espressif (https://dl.espressif.com/dl/esp32s3_rom.elf) and pass it to mespcoredump.pyn.
4.11.6 Dumping variables on demand
Sometimes you want to read the last value of a variable to understand the root cause of a crash. Core dump supports retrieving variable data over GDB by attributing special notations declared variables.
Supported notations and RAM regions
· COREDUMP_DRAM_ATTR places variable into DRAM area which will be included into dump. · COREDUMP_RTC_ATTR places variable into RTC area which will be included into dump. · COREDUMP_RTC_FAST_ATTR places variable into RTC_FAST area which will be included into dump.
Example
1. In Project Configuration Menu, enable COREDUMP TO FLASH, then save and exit. 2. In your project, create a global variable in DRAM area as such as: // uint8_t global_var; COREDUMP_DRAM_ATTR uint8_t global_var;
3. In main application, set the variable to any value and assert(0) to cause a crash. global_var = 25; assert(0);
4. Build, flash and run the application on a target device and wait for the dumping information. 5. Run the command below to start core dumping in GDB, where PORT is the device USB port: espcoredump.py -p PORT dbg_corefile <path/to/elf>
6. In GDB shell, type p global_var to get the variable content: (gdb) p global_var $1 = 25 '\031'

4.11.7 Running espcoredump.py
Generic command syntax: espcoredump.py [options] command [args]
Script Options chip {auto,esp32,esp32s2,esp32s3,esp32c3} Target chip type. Default value is oautop --port PORT, -p PORT Serial port device. Eitherochipporoportpneed to be specified to determine the port when you have multi-target connected at the same time. --baud BAUD, -b BAUD Serial port baud rate used when flashing/reading --gdb-timeout-sec GDB_TIMEOUT_SEC Overwrite the default internal delay for gdb responses
Commands dbg_corefile Starts GDB debugging session with specified corefile info_corefile Print core dump info from file

Espressif Systems

1740

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Command Arguments --debug DEBUG, -d DEBUG Log level (0..3) --gdb GDB, -g GDB Path to gdb --core CORE, -c CORE Path to core dump file (if skipped core dump will be read from flash)
core-format {b64,elf,raw}, -t {b64,elf,raw} File specified with o-cpis an ELF (oelfp), raw (raw) or base64-encoded (b64) binary --off OFF, -o OFF Offset of coredump partition in flash (typeoidf.py partitiontablepto see). --save-core SAVE_CORE, -s SAVE_CORE Save core to file. Otherwise temporary core file will be deleted. Does not work with o-cp --rom-elf ROM_ELF, -r ROM_ELF Path to ROM ELF file. Will use o<target>_rom.elfpif not specified --print-mem, -m Print memory dump. Only valid when info_corefile.
<prog> Path to program ELF file.
Related Documents
Anatomy of core dump image Core dump component can be configured to use old legacy binary format or the new ELF one. The ELF format is recommended for new designs. It provides more information about the CPU and memory state of a program at the moment when panic handler is entered. The memory state embeds a snapshot of all tasks mapped in the memory space of the program. The CPU state contains register values when the core dump has been generated. Core dump file uses a subset of the ELF structures to register these information. Loadable ELF segments are used for the memory state of the process while ELF notes (ELF.PT_NOTE) are used for process metadata (pid, registers, signal, l). Especially, the CPU status is stored in a note with a special name and type (CORE, NT_PRSTATUS type). Here is an overview of coredump layout: Note: The format of image file showed on the above pictures represents current version of image and can be changed in future releases.
Overview of implementation The figure below describes some basic aspects related to implementation of core dump: Note: The diagram above hide some details and represents current implementation of the core dump and can be changed later.
4.12 Event Handling
Several ESP-IDF components use events to inform application about state changes, such as connection or disconnection. This document gives an overview of these event mechanisms.
4.12.1 Wi-Fi, Ethernet, and IP Events
Before the introduction of esp_event library, events from Wi-Fi driver, Ethernet driver, and TCP/IP stack were dispatched using the so-called legacy event loop. The following sections explain each of the methods.
esp_event Library Event Loop
esp_event library is designed to supersede the legacy event loop for the purposes of event handling in ESP-IDF. In the legacy event loop, all possible event types and event data structures had to be defined in system_event_id_t enumeration and system_event_info_t union, which made it impossible to send custom events to the event loop, and use the event loop for other kinds of events (e.g. Mesh). Legacy event loop also supported only one event

Espressif Systems

1741

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 32: Core dump ELF image format

Espressif Systems

Fig. 33: Core dump binary image format

1742

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 34: Core dump implementation overview
handler function, therefore application components could not handle some of Wi-Fi or IP events themselves, and required application to forward these events from its event handler function. See esp_event library API reference for general information on using this library. Wi-Fi, Ethernet, and IP events are sent to the default event loop provided by this library.
Legacy Event Loop
This event loop implementation is started using esp_event_loop_init() function. Application typically supplies an event handler, a function with the following signature:
esp_err_t event_handler(void *ctx, system_event_t *event) { }
Both the pointer to event handler function, and an arbitrary context pointer are passed to esp_event_loop_init(). When Wi-Fi, Ethernet, or IP stack generate an event, this event is sent to a high-priority event task via a queue. Application-provided event handler function is called in the context of this task. Event task stack size and event queue size can be adjusted using CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE and CONFIG_ESP_SYSTEM_EVENT_QUEUE_SIZE options, respectively. Event handler receives a pointer to the event structure (system_event_t) which describes current event. This structure follows a tagged union pattern: event_id member indicates the type of event, and event_info member is a union of description structures. Application event handler will typically use switch(event->event_id) to handle different kinds of events. If application event handler needs to relay the event to some other task, it is important to note that event pointer

Espressif Systems

1743

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

passed to the event handler is a pointer to temporary structure. To pass the event to another task, application has to make a copy of the entire structure.

Event IDs and Corresponding Data Structures

Event ID (legacy event ID)

Wi-Fi

WIFI_EVENT_WIFI_READY (SYSTEM_EVENT_WIFI_READY)

WIFI_EVENT_SCAN_DONE (SYSTEM_EVENT_SCAN_DONE)

WIFI_EVENT_STA_START (SYSTEM_EVENT_STA_START)

WIFI_EVENT_STA_STOP (SYSTEM_EVENT_STA_STOP)

WIFI_EVENT_STA_CONNECTED

(SYS-

TEM_EVENT_STA_CONNECTED)

WIFI_EVENT_STA_DISCONNECTED

(SYS-

TEM_EVENT_STA_DISCONNECTED)

WIFI_EVENT_STA_AUTHMODE_CHANGE

(SYS-

TEM_EVENT_STA_AUTHMODE_CHANGE)

WIFI_EVENT_STA_WPS_ER_SUCCESS

(SYS-

TEM_EVENT_STA_WPS_ER_SUCCESS)

WIFI_EVENT_STA_WPS_ER_FAILED

(SYS-

TEM_EVENT_STA_WPS_ER_FAILED)

WIFI_EVENT_STA_WPS_ER_TIMEOUT

(SYS-

TEM_EVENT_STA_WPS_ER_TIMEOUT)

WIFI_EVENT_STA_WPS_ER_PIN

(SYS-

TEM_EVENT_STA_WPS_ER_PIN)

WIFI_EVENT_AP_START (SYSTEM_EVENT_AP_START)

WIFI_EVENT_AP_STOP (SYSTEM_EVENT_AP_STOP)

WIFI_EVENT_AP_STACONNECTED

(SYS-

TEM_EVENT_AP_STACONNECTED)

WIFI_EVENT_AP_STADISCONNECTED

(SYS-

TEM_EVENT_AP_STADISCONNECTED)

WIFI_EVENT_AP_PROBEREQRECVED

(SYS-

TEM_EVENT_AP_PROBEREQRECVED)

Ethernet

ETHERNET_EVENT_START (SYSTEM_EVENT_ETH_START)

ETHERNET_EVENT_STOP (SYSTEM_EVENT_ETH_STOP)

ETHERNET_EVENT_CONNECTED

(SYS-

TEM_EVENT_ETH_CONNECTED)

ETHERNET_EVENT_DISCONNECTED

(SYS-

TEM_EVENT_ETH_DISCONNECTED)

IP

IP_EVENT_STA_GOT_IP (SYSTEM_EVENT_STA_GOT_IP)

IP_EVENT_STA_LOST_IP (SYSTEM_EVENT_STA_LOST_IP)

IP_EVENT_AP_STAIPASSIGNED

(SYS-

TEM_EVENT_AP_STAIPASSIGNED)

IP_EVENT_GOT_IP6 (SYSTEM_EVENT_GOT_IP6)

IP_EVENT_ETH_GOT_IP (SYSTEM_EVENT_ETH_GOT_IP)

IP_EVENT_ETH_LOST_IP (SYSTEM_EVENT_ETH_LOST_IP)

Event data structure
n/a wifi_event_sta_scan_done_t n/a n/a wifi_event_sta_connected_t
wifi_event_sta_disconnected_t
wifi_event_sta_authmode_change_t
n/a
wifi_event_sta_wps_fail_reason_t
n/a
wifi_event_sta_wps_er_pin_t
n/a n/a wifi_event_ap_staconnected_t
wifi_event_ap_stadisconnected_t
wifi_event_ap_probe_req_rx_t
n/a n/a n/a
n/a
ip_event_got_ip_t n/a n/a
ip_event_got_ip6_t ip_event_got_ip_t n/a

4.12.2 Mesh Events
ESP-WIFI-MESH uses a system similar to the Legacy Event Loop to deliver events to the application. See System Events for details.

Espressif Systems

1744

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

4.12.3 Bluetooth Events

Various modules of the Bluetooth stack deliver events to applications via dedicated callback functions. Callback functions receive the event type (enumerated value) and event data (union of structures for each event type). The following list gives the registration API name, event enumeration type, and event parameters type.

· BLE GAP: esp_ble_gap_register_callback(), esp_gap_ble_cb_event_t,

esp_ble_gap_cb_param_t.

· BT GAP: esp_bt_gap_register_callback(),

esp_bt_gap_cb_event_t,

esp_bt_gap_cb_param_t.

· GATTC: esp_ble_gattc_register_callback(),

esp_bt_gattc_cb_event_t,

esp_bt_gattc_cb_param_t.

· GATTS: esp_ble_gatts_register_callback(),

esp_bt_gatts_cb_event_t,

esp_bt_gatts_cb_param_t.

· SPP: esp_spp_register_callback(), esp_spp_cb_event_t, esp_spp_cb_param_t.

· Blufi:

esp_blufi_register_callbacks(),

esp_blufi_cb_event_t,

esp_blufi_cb_param_t.

· A2DP: esp_a2d_register_callback(), esp_a2d_cb_event_t, esp_a2d_cb_param_t.

· AVRC:

esp_avrc_ct_register_callback(),

esp_avrc_ct_cb_event_t,

esp_avrc_ct_cb_param_t.

· HFP Client: esp_hf_client_register_callback(), esp_hf_client_cb_event_t,

esp_hf_client_cb_param_t.

· HFP

AG:

esp_hf_ag_register_callback(),

esp_hf_ag_cb_event_t,

esp_hf_ag_cb_param_t.

4.13 Support for External RAM
4.13.1 Introduction
ESP32-S3 has a few hundred kilobytes of internal RAM, residing on the same die as the rest of the chip components. It can be insufficient for some purposes, so ESP32-S3 has the ability to also use up to 16 MB of external SPI RAM memory. The external memory is incorporated in the memory map and, with certain restrictions, is usable in the same way as internal data RAM.
4.13.2 Hardware
ESP32-S3 supports SPI PSRAM (Psuedostatic RAM) connected in parallel with the SPI flash chip. While ESP32-S3 is capable of supporting several types of RAM chips, ESP-IDF currently only supports Espressif branded PSRAM chips (e.g., ESP-PSRAM32, ESP-PSRAM64, etc).
Note: Some PSRAM chips are 1.8 V devices and some are 3.3 V. The working voltage of the PSRAM chip must match the working voltage of the flash component. Consult the datasheet for your PSRAM chip and ESP32-S3 device to find out the working voltages. For a 1.8 V PSRAM chip, make sure to either set the MTDI pin to a high signal level on bootup, or program ESP32-S3 eFuses to always use the VDD_SIO level of 1.8 V. Not doing this can damage the PSRAM and/or flash chip.

Note: Espressif produces both modules and system-in-package chips that integrate compatible PSRAM and flash and are ready to mount on a product PCB. Consult the Espressif website for more information.
For specific details about connecting the SoC or module pins to an external PSRAM chip, consult the SoC or module datasheet.

Espressif Systems

1745

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.13.3 Configuring External RAM
ESP-IDF fully supports the use of external RAM in applications. Once the external RAM is initialized at startup, ESP-IDF can be configured to integrate the external RAM in several ways:
· Integrate RAM into the ESP32-S3 Memory Map · Add External RAM to the Capability Allocator · Provide External RAM via malloc() (default)
Integrate RAM into the ESP32-S3 Memory Map
Select this option by choosing oIntegrate RAM into memory mappfrom CONFIG_SPIRAM_USE. This is the most basic option for external SPI RAM integration. Most likely, you will need another, more advanced option. During the ESP-IDF startup, external RAM is mapped into the data address space, starting at address 0x3D000000 (byte-accessible). The length of this region is the same as the SPI RAM size (up to the limit of 16 MB). Applications can manually place data in external memory by creating pointers to this region. So if an application uses external memory, it is responsible for all management of the external SPI RAM: coordinating buffer usage, preventing corruption, etc.
Add External RAM to the Capability Allocator
Select this option by choosing oMake RAM allocatable using heap_caps_malloc(l, MALLOC_CAP_SPIRAM)p from CONFIG_SPIRAM_USE. When enabled, memory is mapped to address 0x3D000000 and also added to the capabilities-based heap memory allocator using MALLOC_CAP_SPIRAM. To allocate memory from external RAM, a program should call heap_caps_malloc(size, MALLOC_CAP_SPIRAM). After use, this memory can be freed by calling the normal free() function.
Provide External RAM via malloc()
Select this option by choosing oMake RAM allocatable using malloc() as wellpfrom CONFIG_SPIRAM_USE. This is the default option. In this case, memory is added to the capability allocator as described for the previous option. However, it is also added to the pool of RAM that can be returned by the standard malloc() function. This allows any application to use the external RAM without having to rewrite the code to use heap_caps_malloc(..., MALLOC_CAP_SPIRAM). An additional configuration item, CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL, can be used to set the size threshold when a single allocation should prefer external memory:
· When allocating a size less than the threshold, the allocator will try internal memory first. · When allocating a size equal to or larger than the threshold, the allocator will try external memory first. If a suitable block of preferred internal/external memory is not available, the allocator will try the other type of memory. Because some buffers can only be allocated in internal memory, a second configuration item CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL defines a pool of internal memory which is reserved for only explicitly internal allocations (such as memory for DMA use). Regular malloc() will not allocate from this pool. The MALLOC_CAP_DMA and MALLOC_CAP_INTERNAL flags can be used to allocate memory from this pool.

Espressif Systems

1746

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.13.4 Restrictions
External RAM use has the following restrictions:
· When flash cache is disabled (for example, if the flash is being written to), the external RAM also becomes inaccessible; any reads from or writes to it will lead to an illegal cache access exception. This is also the reason why ESP-IDF does not by default allocate any task stacks in external RAM (see below).
· External RAM cannot be used as a place to store DMA transaction descriptors or as a buffer for a DMA transfer to read from or write into. Any buffers that will be used in combination with DMA must be allocated using heap_caps_malloc(size, MALLOC_CAP_DMA) and can be freed using a standard free() call.
· External RAM uses the same cache region as the external flash. This means that frequently accessed variables in external RAM can be read and modified almost as quickly as in internal ram. However, when accessing large chunks of data (>32 KB), the cache can be insufficient, and speeds will fall back to the access speed of the external RAM. Moreover, accessing large chunks of data can opush outpcached flash, possibly making the execution of code slower afterwards.
· In general, external RAM cannot be used as task stack memory. Due to this, xTaskCreate() and similar functions will always allocate internal memory for stack and task TCBs, and functions such as xTaskCreateStatic() will check if the buffers passed are internal.
4.13.5 Failure to initialize
By default, failure to initialize external RAM will cause the ESP-IDF startup to abort. This can be disabled by enabling the config item CONFIG_SPIRAM_IGNORE_NOTFOUND.
4.13.6 Encryption
It is possible to enable automatic encryption for data stored in external RAM. When this is enabled any data read and written through the cache will automatically be encrypted/decrypted by the external memory encryption hardware.
This feature is enabled whenever flash encryption is enabled. For more information on how to enable and how it works see Flash Encryption.
4.14 Fatal Errors
4.14.1 Overview
In certain situations, execution of the program can not be continued in a well defined way. In ESP-IDF, these situations include:
· CPU Exceptions: Illegal Instruction, Load/Store Alignment Error, Load/Store Prohibited error, Double Exception.
· System level checks and safeguards: ­ Interrupt watchdog timeout ­ Task watchdog timeout (only fatal if CONFIG_ESP_TASK_WDT_PANIC is set) ­ Cache access error ­ Brownout detection event ­ Stack overflow ­ Stack smashing protection check ­ Heap integrity check ­ Undefined behavior sanitizer (UBSAN) checks
· Failed assertions, via assert, configASSERT and similar macros.
This guide explains the procedure used in ESP-IDF for handling these errors, and provides suggestions on troubleshooting the errors.

Espressif Systems

1747

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

4.14.2 Panic Handler
Every error cause listed in the Overview will be handled by the panic handler.
The panic handler will start by printing the cause of the error to the console. For CPU exceptions, the message will be similar to
Guru Meditation Error: Core 0 panic'ed (IllegalInstruction). Exception was unhandled.
For some of the system level checks (interrupt watchdog, cache access error), the message will be similar to
Guru Meditation Error: Core 0 panic'ed (Cache disabled but cached memory region accessed). Exception was unhandled.
In all cases, the error cause will be printed in parentheses. See Guru Meditation Errors for a list of possible error causes.
Subsequent behavior of the panic handler can be set using CONFIG_ESP_SYSTEM_PANIC configuration choice. The available options are:
· Print registers and reboot (CONFIG_ESP_SYSTEM_PANIC_PRINT_REBOOT) idefault option. This will print register values at the point of the exception, print the backtrace, and restart the chip.
· Print registers and halt (CONFIG_ESP_SYSTEM_PANIC_PRINT_HALT) Similar to the above option, but halt instead of rebooting. External reset is required to restart the program.
· Silent reboot (CONFIG_ESP_SYSTEM_PANIC_SILENT_REBOOT) Donnt print registers or backtrace, restart the chip immediately.
· Invoke GDB Stub (CONFIG_ESP_SYSTEM_PANIC_GDBSTUB) Start GDB server which can communicate with GDB over console UART port. This option will only provide read-only debugging or post-mortem debugging. See GDB Stub for more details.
· Invoke dynamic GDB Stub (ESP_SYSTEM_GDBSTUB_RUNTIME) Start GDB server which can communicate with GDB over console UART port. This option allows the user to debug a program at run time and set break points, alter the execution, etc. See GDB Stub for more details.
The behavior of the panic handler is affected by two other configuration options.
· If CONFIG_ESP32S3_DEBUG_OCDAWARE is enabled (which is the default), the panic handler will detect whether a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In this case, registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not used.
· If the Core Dump feature is enabled, then the system state (task stacks and registers) will be dumped to either Flash or UART, for later analysis.
· If CONFIG_ESP_PANIC_HANDLER_IRAM is disabled (disabled by default), the panic handler code is placed in flash memory, not IRAM. This means that if ESP-IDF crashes while flash cache is disabled, the panic handler will automatically re-enable flash cache before running GDB Stub or Core Dump. This adds some minor risk, if the flash cache status is also corrupted during the crash. If this option is enabled, the panic handler code (including required UART functions) is placed in IRAM, and hence will decrease the usable memory space in SRAM. But this may be necessary to debug some complex issues with crashes while flash cache is disabled (for example, when writing to SPI flash) or when flash cache is corrupted when an exception is triggered.
The following diagram illustrates the panic handler behavior:

4.14.3 Register Dump and Backtrace

Unless the CONFIG_ESP_SYSTEM_PANIC_SILENT_REBOOT option is enabled, the panic handler prints some of the CPU registers, and the backtrace, to the console

Core 0 register dump:

PC

: 0x400e14ed PS

0x3ffb5030

A2

: 0x00000000 A3

0x3ffb50dc

: 0x00060030 A0 : 0x00000001 A4

: 0x800d0805 A1

:

: 0x00000001 A5

:

(continues on next page)

Espressif Systems

1748

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 35: Panic Handler Flowchart (click to enlarge)

Espressif Systems

1749

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

A6

: 0x00000000

0x3ffb5000

A10

: 0x00000000

0x06ff1ff8

A14

: 0x3ffb7078

0x0000001d

EXCVADDR: 0x00000000

0xffffffff

A7 A11 A15 LBEG

: 0x00000001 A8 : 0x3ffb2bac A12 : 0x00000000 SAR : 0x4000c46c LEND

(continued from previous page)

: 0x00000000 A9

:

: 0x40082d1c A13

:

: 0x00000014 EXCCAUSE:

: 0x4000c477 LCOUNT :

Backtrace: 0x400e14ed:0x3ffb5030 0x400d0802:0x3ffb5050

The register values printed are the register values in the exception frame, i.e., values at the moment when the CPU exception or another fatal error has occurred.
A Register dump is not printed if the panic handler has been executed as a result of an abort() call.
In some cases, such as interrupt watchdog timeout, the panic handler may print additional CPU registers (EPC1EPC4) and the registers/backtrace of the code running on the other CPU.
The backtrace line contains PC:SP pairs, where PC is the Program Counter and SP is Stack Pointer, for each stack frame of the current task. If a fatal error happens inside an ISR, the backtrace may include PC:SP pairs both from the task which was interrupted, and from the ISR.
If IDF Monitor is used, Program Counter values will be converted to code locations (function name, file name, and line number), and the output will be annotated with additional lines:

Core 0 register dump:

PC

: 0x400e14ed PS

: 0x00060030 A0

: 0x800d0805 A1

:

0x3ffb5030

0x400e14ed: app_main at /Users/user/esp/example/main/main.cpp:36

A2

: 0x00000000 A3

: 0x00000001 A4

: 0x00000001 A5

:

0x3ffb50dc

A6

: 0x00000000 A7

: 0x00000001 A8

: 0x00000000 A9

:

0x3ffb5000

A10

: 0x00000000 A11

: 0x3ffb2bac A12

: 0x40082d1c A13

:

0x06ff1ff8

0x40082d1c: _calloc_r at /Users/user/esp/esp-idf/components/newlib/syscalls.c:51

A14

: 0x3ffb7078

0x0000001d

EXCVADDR: 0x00000000

0xffffffff

A15 LBEG

: 0x00000000 SAR : 0x4000c46c LEND

: 0x00000014 EXCCAUSE: : 0x4000c477 LCOUNT :

Backtrace: 0x400e14ed:0x3ffb5030 0x400d0802:0x3ffb5050 0x400e14ed: app_main at /Users/user/esp/example/main/main.cpp:36

0x400d0802: main_task at /Users/user/esp/esp-idf/components/esp32s3/cpu_start.c:470

To find the location where a fatal error has happened, look at the lines which follow the oBacktracepline. Fatal error location is the top line, and subsequent lines show the call stack.

4.14.4 GDB Stub
If the CONFIG_ESP_SYSTEM_PANIC_GDBSTUB option is enabled, the panic handler will not reset the chip when a fatal error happens. Instead, it will start a GDB remote protocol server, commonly referred to as GDB Stub. When this happens, a GDB instance running on the host computer can be instructed to connect to the ESP32-S3 UART port.
If IDF Monitor is used, GDB is started automatically when a GDB Stub prompt is detected on the UART. The output looks like this:

Espressif Systems

1750

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Entering gdb stub now.

$T0b#e6GNU gdb (crosstool-NG crosstool-ng-1.22.0-80-gff1f415) 7.10

Copyright (C) 2015 Free Software Foundation, Inc.

License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>

This is free software: you are free to change and redistribute it.

There is NO WARRANTY, to the extent permitted by law. Type "show copying"

and "show warranty" for details.

This GDB was configured as "--host=x86_64-build_apple-darwin16.3.0 --target=xtensa-

esp32s3-elf".

Type "show configuration" for configuration details.

For bug reporting instructions, please see:

<http://www.gnu.org/software/gdb/bugs/>.

Find the GDB manual and other documentation resources online at:

<http://www.gnu.org/software/gdb/documentation/>.

For help, type "help".

Type "apropos word" to search for commands related to "word"...

Reading symbols from /Users/user/esp/example/build/example.elf...done.

Remote debugging using /dev/cu.usbserial-31301

0x400e1b41 in app_main ()

at /Users/user/esp/example/main/main.cpp:36

36

*((int*) 0) = 0;

(gdb)

The GDB prompt can be used to inspect CPU registers, local and static variables, and arbitrary locations in memory. It is not possible to set breakpoints, change the PC, or continue execution. To reset the program, exit GDB and perform an external reset: Ctrl-T Ctrl-R in IDF Monitor, or using the external reset button on the development board.

4.14.5 Guru Meditation Errors
This section explains the meaning of different error causes, printed in parens after the Guru Meditation Error: Core panic'ed message.
Note: See the Guru Meditation Wikipedia article for historical origins of oGuru Meditationp.

IllegalInstruction
This CPU exception indicates that the instruction which was executed was not a valid instruction. Most common reasons for this error include:
· FreeRTOS task function has returned. In FreeRTOS, if a task function needs to terminate, it should call vTaskDelete() and delete itself, instead of returning.
· Failure to read next instruction from SPI flash. This usually happens if: ­ Application has reconfigured the SPI flash pins as some other function (GPIO, UART, etc.). Consult the Hardware Design Guidelines and the datasheet for the chip or module for details about the SPI flash pins. ­ Some external device has accidentally been connected to the SPI flash pins, and has interfered with communication between ESP32-S3 and SPI flash.
· In C++ code, exiting from a non-void function without returning a value is considered to be an undefined behavior. When optimizations are enabled, the compiler will often omit the epilogue in such functions. This most often results in an IllegalInstruction exception. By default, ESP-IDF build system enables -Werror=returntype which means that missing return statements are treated as compile time errors. However if the application project disables compiler warnings, this issue might go undetected and the IllegalInstruction exception will occur at run time.

Espressif Systems

1751

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
InstrFetchProhibited
This CPU exception indicates that the CPU could not read an instruction because the address of the instruction does not belong to a valid region in instruction RAM or ROM. Usually, this means an attempt to call a function pointer, which does not point to valid code. PC (Program Counter) register can be used as an indicator: it will be zero or will contain a garbage value (not 0x4xxxxxxx).
LoadProhibited, StoreProhibited
These CPU exceptions happen when an application attempts to read from or write to an invalid memory location. The address which has been written/read is found in the EXCVADDR register in the register dump. If this address is zero, it usually means that the application has attempted to dereference a NULL pointer. If this address is close to zero, it usually means that the application has attempted to access a member of a structure, but the pointer to the structure is NULL. If this address is something else (garbage value, not in 0x3fxxxxxx - 0x6xxxxxxx range), it likely means that the pointer used to access the data is either not initialized or has been corrupted.
IntegerDivideByZero
Application has attempted to do an integer division by zero.
LoadStoreAlignment
Application has attempted to read or write a memory location, and the address alignment does not match the load/store size. For example, a 32-bit read can only be done from a 4-byte aligned address, and a 16-bit write can only be done to a 2-byte aligned address.
LoadStoreError
This exception may happen in the following cases: · If the application has attempted to do an 8- or 16- bit read to, or write from, a memory region which only supports 32-bit reads/writes. For example, dereferencing a char* pointer to instruction memory (IRAM, IROM) will result in such an error. · If the application has attempted to write to a read-only memory region, such as IROM or DROM.
Unhandled debug exception
This will usually be followed by a message like: Debug exception reason: Stack canary watchpoint triggered (task_name)
This error indicates that the application has written past the end of the stack of the task with name task_name. Note that not every stack overflow is guaranteed to trigger this error. It is possible that the task writes to memory beyond the stack canary location, in which case the watchpoint will not be triggered.
Interrupt wdt timeout on CPU0 / CPU1
Indicates that an interrupt watchdog timeout has occurred. See Watchdogs for more information.

Espressif Systems

1752

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Cache disabled but cached memory region accessed
In some situations, ESP-IDF will temporarily disable access to external SPI Flash and SPI RAM via caches. For example, this happens when spi_flash APIs are used to read/write/erase/mmap regions of SPI Flash. In these situations, tasks are suspended, and interrupt handlers not registered with ESP_INTR_FLAG_IRAM are disabled. Make sure that any interrupt handlers registered with this flag have all the code and data in IRAM/DRAM. Refer to the SPI flash API documentation for more details.
4.14.6 Other Fatal Errors
Brownout
ESP32-S3 has a built-in brownout detector, which is enabled by default. The brownout detector can trigger a system reset if the supply voltage goes below a safe level. The brownout detector can be configured using CONFIG_ESP32S3_BROWNOUT_DET and CONFIG_ESP32S3_BROWNOUT_DET_LVL_SEL options. When the brownout detector triggers, the following message is printed: Brownout detector was triggered
The chip is reset after the message is printed. Note that if the supply voltage is dropping at a fast rate, only part of the message may be seen on the console.
Corrupt Heap
ESP-IDFns heap implementation contains a number of run-time checks of the heap structure. Additional checks ( oHeap Poisoningp) can be enabled in menuconfig. If one of the checks fails, a message similar to the following will
be printed: CORRUPT HEAP: Bad tail at 0x3ffe270a. Expected 0xbaad5678 got 0xbaac5678 assertion "head != NULL" failed: file "/Users/user/esp/esp-idf/components/heap/ multi_heap_poisoning.c", line 201, function: multi_heap_free abort() was called at PC 0x400dca43 on core 0
Consult Heap Memory Debugging documentation for further information.
Stack Smashing
Stack smashing protection (based on GCC -fstack-protector* flags) can be enabled in ESP-IDF using CONFIG_COMPILER_STACK_CHECK_MODE option. If stack smashing is detected, message similar to the following will be printed: Stack smashing protect failure!
abort() was called at PC 0x400d2138 on core 0
Backtrace: 0x4008e6c0:0x3ffc1780 0x4008e8b7:0x3ffc17a0 0x400d2138:0x3ffc17c0 0x400e79d5:0x3ffc17e0 0x400e79a7:0x3ffc1840 0x400e79df:0x3ffc18a0 0x400e2235:0x3ffc18c0 0x400e1916:0x3ffc18f0 0x400e19cd:0x3ffc1910 0x400e1a11:0x3ffc1930 0x400e1bb2:0x3ffc1950 0x400d2c44:0x3ffc1a80 0
The backtrace should point to the function where stack smashing has occurred. Check the function code for unbounded access to local arrays.

Espressif Systems

1753

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Undefined behavior sanitizer (UBSAN) checks
Undefined behavior sanitizer (UBSAN) is a compiler feature which adds run-time checks for potentially incorrect operations, such as:
· overflows (multiplication overflow, signed integer overflow) · shift base or exponent errors (e.g. shift by more than 32 bits) · integer conversion errors See GCC documentation of -fsanitize=undefined option for the complete list of supported checks.
Enabling UBSAN UBSAN is disabled by default. It can be enabled at file, component, or project level by adding the -fsanitize=undefined compiler option in the build system. When enabling UBSAN for code which uses the SOC hardware register header files (soc/xxx_reg.h), it is recommended to disable shift-base sanitizer using -fno-sanitize=shift-base option. This is due to the fact that ESP-IDF register header files currently contain patterns which cause false positives for this specific sanitizer option. To enable UBSAN at project level, add the following code at the end of the projectns CMakeLists.txt file:
idf_build_set_property(COMPILE_OPTIONS "-fsanitize=undefined" "-fno-sanitize=shiftbase" APPEND)
Alternatively, pass these options through the EXTRA_CFLAGS and EXTRA_CXXFLAGS environment variables. Enabling UBSAN results in significant increase of code and data size. Most applications, except for the trivial ones, will not fit into the available RAM of the microcontroller when UBSAN is enabled for the whole application. Therefore it is recommended that UBSAN is instead enabled for specific components under test. To enable UBSAN for a specific component (component_name) from the projectns CMakeLists.txt file, add the following code at the end of the file:
idf_component_get_property(lib component_name COMPONENT_LIB) target_compile_options(${lib} PRIVATE "-fsanitize=undefined" "-fno-sanitize=shiftbase")
Note: See the build system documentation for more information about build properties and component properties.
To enable UBSAN for a specific component (component_name) from CMakeLists.txt of the same component, add the following at the end of the file:
target_compile_options(${COMPONENT_LIB} PRIVATE "-fsanitize=undefined" "-fnosanitize=shift-base")

UBSAN output When UBSAN detects an error, a message and the backtrace are printed, for example:
Undefined behavior of type out_of_bounds
Backtrace:0x4008b383:0x3ffcd8b0 0x4008c791:0x3ffcd8d0 0x4008c587:0x3ffcd8f0 0x4008c6be:0x3ffcd950 0x400db74f:0x3ffcd970 0x400db99c:0x3ffcd9a0
When using IDF Monitor, the backtrace will be decoded to function names and source code locations, pointing to the location where the issue has happened (here it is main.c:128):
0x4008b383: panic_abort at /path/to/esp-idf/components/esp_system/panic.c:367
0x4008c791: esp_system_abort at /path/to/esp-idf/components/esp_system/system_api. c:106
(continues on next page)

Espressif Systems

1754

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

(continued from previous page)

0x4008c587: __ubsan_default_handler at /path/to/esp-idf/components/esp_system/ ubsan.c:152
0x4008c6be: __ubsan_handle_out_of_bounds at /path/to/esp-idf/components/esp_system/ ubsan.c:223
0x400db74f: test_ub at main.c:128
0x400db99c: app_main at main.c:56 (discriminator 1)

The types of errors reported by UBSAN can be as follows:

Name type_mismatch, type_mismatch_v1 add_overflow, sub_overflow, mul_overflow, negate_overflow divrem_overflow shift_out_of_bounds out_of_bounds unreachable missing_return
vla_bound_not_positive load_invalid_value
nonnull_arg
nonnull_return
builtin_unreachable pointer_overflow

Meaning Incorrect pointer value: null, unaligned, not compatible with the given type. Integer overflow during addition, subtraction, multiplication, negation. Integer division by 0 or INT_MIN. Overflow in left or right shift operators. Access outside of bounds of an array. Unreachable code executed. Non-void function has reached its end without returning a value (C++ only). Size of variable length array is not positive. Value of bool or enum (C++ only) variable is invalid (out of bounds). Null argument passed to a function which is declared with a nonnull attribute. Null value returned from a function which is declared with returns_nonnull attribute. __builtin_unreachable function called. Overflow in pointer arithmetic.

4.15 Flash Encryption
This is a quick start guide to ESP32-S3ns flash encryption feature. Using an application code example, it demonstrates how to test and verify flash encryption operations during development and production.
4.15.1 Introduction
Flash encryption is intended for encrypting the contents of the ESP32-S3ns off-chip flash memory. Once this feature is enabled, firmware is flashed as plaintext, and then the data is encrypted in place on the first boot. As a result, physical readout of flash will not be sufficient to recover most flash contents. With flash encryption enabled, the following types of data are encrypted by default:
· Firmware bootloader · Partition Table · All oappptype partitions Other types of data can be encrypted conditionally: · Any partition marked with the encrypted flag in the partition table. For details, see Encrypted Partition
Flag. · Secure Boot bootloader digest if Secure Boot is enabled (see below).

Espressif Systems

1755

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Important: For production use, flash encryption should be enabled in the oReleasepmode only.
Important: Enabling flash encryption limits the options for further updates of ESP32-S3. Before using this feature, read the document and make sure to understand the implications.

4.15.2 Relevant eFuses

The flash encryption operation is controlled by various eFuses available on ESP32-S3. The list of eFuses and their descriptions is given in the table below. The names in eFuse column are also used by espefuse.py tool. For usage in the eFuse API, modify the name by adding ESP_EFUSE_, for example: esp_efuse_read_field_bit(ESP_EFUSE_DISABLE_DL_ENCRYPT).

eFuse BLOCK_KEYN

Table 20: eFuses Used in Flash Encryption
Description AES key storage. N is between 0 and 5.

KEY_PURPOSE_N

Controls the purpose of eFuse block BLOCK_KEYN,

where N is between 0 and 5. Possible val-

ues:

2 for XTS_AES_256_KEY_1 , 3

for XTS_AES_256_KEY_2, and 4 for

XTS_AES_128_KEY. Final AES key is derived based

on the value of one or two of these purpose eFuses. For

a detailed description of the possible combinations, see

ESP32-S3 Technical Reference Manual > External Memory

Encryption and Decryption (XTS_AES) [PDF].

DIS_DOWNLOAD_MANUAL_ENCRYPIfTset, disables flash encryption when in download boot-

modes.

SPI_BOOT_CRYPT_CNT

Enables encryption and decryption, when an SPI boot mode

is set. Feature is enabled if 1 or 3 bits are set in the eFuse,

disabled otherwise.

Bit Depth One 256 bit key block for XTS_AES_128, Two 256 bit key blocks for XTS_AES_256 (512 bit total) 4
1
3

Note:
· R/W access control is available for all the eFuse bits listed in the table above. · The default value of these bits is 0 afer manufacturing.
Read and write access to eFuse bits is controlled by appropriate fields in the registers WR_DIS and RD_DIS. For more information on ESP32-S3 eFuses, see eFuse manager. To change protection bits of eFuse field using espefuse.py, use these two commands: read_protect_efuse and write_protect_efuse. Example espefuse.py write_protect_efuse DISABLE_DL_ENCRYPT.

Espressif Systems

1756

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

4.15.3 Flash Encryption Process
Assuming that the eFuse values are in their default states and the firmware bootloader is compiled to support flash encryption, the flash encryption process executes as shown below:
1. On the first power-on reset, all data in flash is un-encrypted (plaintext). The ROM bootloader loads the firmware bootloader.
2. Firmware bootloader reads the SPI_BOOT_CRYPT_CNT eFuse value (0b000). Since the value is 0 (even number of bits set), it configures and enables the flash encryption block. For more information on the flash encryption block, see ESP32-S3 Technical Reference Manual > eFuse Controller (eFuse) > Auto Encryption Block [PDF].
3. Firmware bootloader uses RNG (random) module to generate an 256 bit or 512 bit key, depending on the value of Size of generated AES-XTS key, and then writes it into respectively one or two BLOCK_KEYN eFuses. The software also updates the KEY_PURPOSE_N for the blocks where the keys were stored. The key cannot be accessed via software as the write and read protection bits for one or two BLOCK_KEYN eFuses are set. KEY_PURPOSE_N field is write-protected as well. The flash encryption operations happen entirely by hardware, and the key cannot be accessed via software.
4. Flash encryption block encrypts the flash contents - the firmware bootloader, applications and partitions marked as encrypted. Encrypting in-place can take time, up to a minute for large partitions.
5. Firmware bootloader sets the first available bit in SPI_BOOT_CRYPT_CNT (0b001) to mark the flash contents as encrypted. Odd number of bits is set.
6. For Development Mode, the firmware bootloader allows the UART bootloader to re-flash encrypted binaries. Also, the SPI_BOOT_CRYPT_CNT eFuse bits are NOT write-protected. In addition, the firmware bootloader by default sets the eFuse bits DIS_BOOT_REMAP, DIS_DOWNLOAD_ICACHE, DIS_DOWNLOAD_DCACHE, HARD_DIS_JTAG and DIS_LEGACY_SPI_BOOT.
7. For Release Mode, the firmware bootloader sets all the eFuse bits set under development mode as well as DIS_DOWNLOAD_MANUAL_ENCRYPT. It also write-protects the SPI_BOOT_CRYPT_CNT eFuse bits. To modify this behavior, see Enabling UART Bootloader Encryption/Decryption.
8. The device is then rebooted to start executing the encrypted image. The firmware bootloader calls the flash decryption block to decrypt the flash contents and then loads the decrypted contents into IRAM.
During the development stage, there is a frequent need to program different plaintext flash images and test the flash encryption process. This requires that Firmware Download mode is able to load new plaintext images as many times as it might be needed. However, during manufacturing or production stages, Firmware Download mode should not be allowed to access flash contents for security reasons.
Hence, two different flash encryption configurations were created: for development and for production. For details on these configurations, see Section Flash Encryption Configuration.

4.15.4 Flash Encryption Configuration
The following flash encryption modes are available:
· Development Mode - recommended for use ONLY DURING DEVELOPMENT, as it does not prevent modification and readout of encrypted flash contents.
· Release Mode - recommended for manufacturing and production to prevent physical readout of encrypted flash contents.
This section provides information on the mentioned flash encryption modes and step by step instructions on how to use them.

Development Mode During development, you can encrypt flash using either an ESP32-S3 generated key or external host-generated key.

Using ESP32-S3 Generated Key Development mode allows you to download multiple plaintext images using Firmware Download mode.
To test flash encryption process, take the following steps:

Espressif Systems

1757

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

1. Ensure that you have an ESP32-S3 device with default flash encryption eFuse settings as shown in Relevant eFuses.
See how to check ESP32-S3 Flash Encryption Status.
2. In Project Configuration Menu, do the following:
· Enable flash encryption on boot · Select encryption mode (Development mode by default) · Select UART ROM download mode (enabled by default.) · Set Size of generated AES-XTS key · Select the appropriate bootloader log verbosity · Save the configuration and exit.
Enabling flash encryption will increase the size of bootloader, which might require updating partition table offset. See Bootloader Size.
3. Run the command given below to build and flash the complete images.
idf.py flash monitor

Note: This command does not include any user files which should be written to the partitions on the flash memory. Please write them manually before running this command otherwise the files should be encrypted separately before writing.

This command will write to flash memory unencrypted images: the firmware bootloader, the partition table and applications. Once the flashing is complete, ESP32-S3 will reset. On the next boot, the firmware bootloader encrypts: the firmware bootloader, application partitions and partitions marked as encrypted then resets. Encrypting in-place can take time, up to a minute for large partitions. After that, the application is decrypted at runtime and executed.
A sample output of the first ESP32-S3 boot after enabling flash encryption is given below:

ESP-ROM:esp32s3-20210327

Build:Mar 27 2021

rst:0x1 (POWERON),boot:0x8 (SPI_FAST_FLASH_BOOT)

SPIWP:0xee

mode:DIO, clock div:1

load:0x3fcd0270,len:0x2598

load:0x403b6000,len:0x878

load:0x403ba000,len:0x3dd4

entry 0x403b61c0

I (27) boot: ESP-IDF v4.4-dev-2003-g72fdecc1b7-dirty 2nd stage bootloader

I (28) boot: compile time 14:15:37

I (28) boot: chip revision: 0

I (32) boot.esp32s3: SPI Speed

: 80MHz

I (36) boot.esp32s3: SPI Mode

: DIO

I (41) boot.esp32s3: SPI Flash Size : 2MB

I (46) boot: Enabling RNG early entropy source...

I (58) boot: Partition Table:

I (62) boot: ## Label

Usage

Type ST Offset Length

I (69) boot: 0 nvs

WiFi data

01 02 0000a000 00006000

I (76) boot: 1 storage

Unknown data

01 ff 00010000 00001000

I (84) boot: 2 factory

factory app

00 00 00020000 00100000

I (91) boot: 3 nvs_key

NVS keys

01 04 00120000 00001000

I (99) boot: End of partition table

I (103) esp_image: segment 0: paddr=00020020 vaddr=3c020020 size=08118h ( 33048)

map

I (117) esp_image: segment 1: paddr=00028140 vaddr=3fc8fa30 size=023f4h ( 9204)

load

I (122) esp_image: segment 2: paddr=0002a53c vaddr=40374000 size=05adch ( 23260)

load

(continues on next page)

Espressif Systems

1758

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

(continued from previous page)
I (134) esp_image: segment 3: paddr=00030020 vaddr=42000020 size=1a710h (108304) map I (156) esp_image: segment 4: paddr=0004a738 vaddr=40379adc size=05f48h ( 24392) load I (162) esp_image: segment 5: paddr=00050688 vaddr=600fe000 size=00010h ( 16) load I (167) boot: Loaded app from partition at offset 0x20000 I (168) boot: Checking flash encryption... I (173) efuse: Batch mode of writing fields is enabled I (179) flash_encrypt: Generating new flash encryption key... I (188) efuse: Writing EFUSE_BLK_KEY0 with purpose 4 W (194) flash_encrypt: Not disabling UART bootloader encryption I (197) flash_encrypt: Disable UART bootloader cache... I (203) flash_encrypt: Disable JTAG... I (212) efuse: Batch mode. Prepared fields are committed I (214) esp_image: segment 0: paddr=00000020 vaddr=3fcd0270 size=02598h ( 9624) I (223) esp_image: segment 1: paddr=000025c0 vaddr=403b6000 size=00878h ( 2168) I (230) esp_image: segment 2: paddr=00002e40 vaddr=403ba000 size=03dd4h ( 15828) I (534) flash_encrypt: bootloader encrypted successfully I (578) flash_encrypt: partition table encrypted and loaded successfully I (578) flash_encrypt: Encrypting partition 1 at offset 0x10000 (length 0x1000)... I (628) flash_encrypt: Done encrypting I (629) esp_image: segment 0: paddr=00020020 vaddr=3c020020 size=08118h ( 33048) map I (636) esp_image: segment 1: paddr=00028140 vaddr=3fc8fa30 size=023f4h ( 9204) I (640) esp_image: segment 2: paddr=0002a53c vaddr=40374000 size=05adch ( 23260) I (651) esp_image: segment 3: paddr=00030020 vaddr=42000020 size=1a710h (108304) map I (675) esp_image: segment 4: paddr=0004a738 vaddr=40379adc size=05f48h ( 24392) I (679) esp_image: segment 5: paddr=00050688 vaddr=600fe000 size=00010h ( 16) I (680) flash_encrypt: Encrypting partition 2 at offset 0x20000 (length 0x100000).. . I (11571) flash_encrypt: Done encrypting I (11571) flash_encrypt: Encrypting partition 3 at offset 0x120000 (length 0x1000). .. I (11617) flash_encrypt: Done encrypting I (11618) flash_encrypt: Flash encryption completed I (11623) boot: Resetting with flash encryption enabled...

A sample output of subsequent ESP32-S3 boots just mentions that flash encryption is already enabled:

ESP-ROM:esp32s3-20210327

Build:Mar 27 2021

rst:0x3 (RTC_SW_SYS_RST),boot:0x8 (SPI_FAST_FLASH_BOOT)

Saved PC:0x403bb1d6

SPIWP:0xee

mode:DIO, clock div:1

load:0x3fcd0270,len:0x2598

load:0x403b6000,len:0x878

load:0x403ba000,len:0x3dd4

entry 0x403b61c0

I (35) boot: ESP-IDF v4.4-dev-2003-g72fdecc1b7-dirty 2nd stage bootloader

I (35) boot: compile time 14:15:37

I (35) boot: chip revision: 0

I (39) boot.esp32s3: SPI Speed

: 80MHz

I (44) boot.esp32s3: SPI Mode

: DIO

I (48) boot.esp32s3: SPI Flash Size : 2MB

I (53) boot: Enabling RNG early entropy source...

I (65) boot: Partition Table:

I (69) boot: ## Label

Usage

Type ST Offset Length

I (76) boot: 0 nvs

WiFi data

01 02 0000a000 00006000

(continues on next page)

Espressif Systems

1759

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

(continued from previous page)

I (84) boot: 1 storage

Unknown data

01 ff 00010000 00001000

I (91) boot: 2 factory

factory app

00 00 00020000 00100000

I (99) boot: 3 nvs_key

NVS keys

01 04 00120000 00001000

I (106) boot: End of partition table

I (110) esp_image: segment 0: paddr=00020020 vaddr=3c020020 size=08118h ( 33048)

map

I (126) esp_image: segment 1: paddr=00028140 vaddr=3fc8fa30 size=023f4h ( 9204)

load

I (129) esp_image: segment 2: paddr=0002a53c vaddr=40374000 size=05adch ( 23260)

load

I (141) esp_image: segment 3: paddr=00030020 vaddr=42000020 size=1a710h (108304)

map

I (166) esp_image: segment 4: paddr=0004a738 vaddr=40379adc size=05f48h ( 24392)

load

I (172) esp_image: segment 5: paddr=00050688 vaddr=600fe000 size=00010h ( 16)

load

I (177) boot: Loaded app from partition at offset 0x20000

I (178) boot: Checking flash encryption...

I (183) flash_encrypt: flash encryption is enabled (1 plaintext flashes left)

I (190) boot: Disabling RNG early entropy source...

I (214) cpu_start: Pro cpu up.

I (214) cpu_start: Starting app cpu, entry point is 0x40374fa8

0x40374fa8: call_start_cpu1 at /home/marius/esp-idf_3/components/esp_system/port/

cpu_start.c:160

I (0) cpu_start: App cpu up.

I (228) cpu_start: Pro cpu start user code

I (228) cpu_start: cpu freq: 160000000

I (228) cpu_start: Application information:

I (231) cpu_start: Project name:

flash_encryption

I (237) cpu_start: App version:

v4.4-dev-2003-g72fdecc1b7-dirty

I (244) cpu_start: Compile time:

Jul 12 2021 14:15:34

I (250) cpu_start: ELF file SHA256: a7e6343c6a1c2215...

I (256) cpu_start: ESP-IDF:

v4.4-dev-2003-g72fdecc1b7-dirty

I (263) heap_init: Initializing. RAM available for dynamic allocation:

I (270) heap_init: At 3FC92810 len 0004D7F0 (309 KiB): D/IRAM

I (277) heap_init: At 3FCE0000 len 0000EE34 (59 KiB): STACK/DRAM

I (283) heap_init: At 3FCF0000 len 00008000 (32 KiB): DRAM

I (290) spi_flash: detected chip: generic

I (294) spi_flash: flash io: dio

W (298) spi_flash: Detected size(8192k) larger than the size in the binary image

header(2048k). Using the size in the binary image header.

I (311) flash_encrypt: Flash encryption mode is DEVELOPMENT (not secure)

I (318) cpu_start: Starting scheduler on PRO CPU.

I (0) cpu_start: Starting scheduler on APP CPU.

Example to check Flash Encryption status This is esp32s3 chip with 2 CPU core(s), WiFi/BLE, silicon revision 0, 2MB external flash FLASH_CRYPT_CNT eFuse value is 1 Flash encryption feature is enabled in DEVELOPMENT mode

At this stage, if you need to update and re-flash binaries, see Re-flashing Updated Partitions.

Using Host Generated Key It is possible to pre-generate a flash encryption key on the host computer and burn it into the eFuse. This allows you to pre-encrypt data on the host and flash already encrypted data without needing a plaintext flash update. This feature can be used in both Development Mode and Release Mode. Without a pregenerated key, data is flashed in plaintext and then ESP32-S3 encrypts the data in-place.

Espressif Systems

1760

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Note: This option is not recommended for production, unless a separate key is generated for each individual device.
To use a host generated key, take the following steps: 1. Ensure that you have an ESP32-S3 device with default flash encryption eFuse settings as shown in Relevant eFuses. See how to check ESP32-S3 Flash Encryption Status.
2. Generate a random key by running:
If Size of generated AES-XTS key is AES-128 (256-bit key):
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
else if Size of generated AES-XTS key is AES-256 (512-bit key):
espsecure.py generate_flash_encryption_key --keylen 512 my_flash_ encryption_key.bin
3. Before the first encrypted boot, burn the key into your devicens eFuse using the command below. This action can be done only once.
espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin KEYPURPOSE
where BLOCK is a free keyblock between BLOCK_KEY0 and BLOCK_KEY5. And KEYPURPOSE is either AES_256_KEY_1, XTS_AES_256_KEY_2, XTS_AES_128_KEY. See ESP32-S3 Technical Reference Manual for a description of the key purposes.
For AES-128 (256-bit key) - XTS_AES_128_KEY:
espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin XTS_ AES_128_KEY
For AES-256 (512-bit key) - XTS_AES_256_KEY_1 and XTS_AES_256_KEY_2. espefuse. py supports burning both these two key purposes together with a 512 bit key to two separate key blocks via the virtual key purpose XTS_AES_256_KEY. When this is used espefuse.py will burn the first 256 bit of the key to the specified BLOCK and burn the corresponding block key purpose to XTS_AES_256_KEY_1. The last 256 bit of the key will be burned to the first free key block after BLOCK and the corresponding block key purpose to XTS_AES_256_KEY_2
espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin XTS_ AES_256_KEY
If you wish to specify exactly which two blocks are used then it is possible to divide key into two 256 bit keys, and manually burn each half with XTS_AES_256_KEY_1 and XTS_AES_256_KEY_2 as key purposes:
split -b 32 my_flash_encryption_key.bin my_flash_encryption_key.bin. espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin.aa XTS_AES_256_KEY_1 espefuse.py --port PORT burn_key BLOCK+1 my_flash_encryption_key.bin.ab XTS_AES_256_KEY_2
If the key is not burned and the device is started after enabling flash encryption, the ESP32-S3 will generate a random key that software cannot access or modify.
4. In Project Configuration Menu, do the following: · Enable flash encryption on boot · Select encryption mode (Development mode by default) · Select the appropriate bootloader log verbosity

Espressif Systems

1761

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

· Save the configuration and exit. Enabling flash encryption will increase the size of bootloader, which might require updating partition table offset. See Bootloader Size.
5. Run the command given below to build and flash the complete images.
idf.py flash monitor
Note: This command does not include any user files which should be written to the partitions on the flash memory. Please write them manually before running this command otherwise the files should be encrypted separately before writing.
This command will write to flash memory unencrypted images: the firmware bootloader, the partition table and applications. Once the flashing is complete, ESP32-S3 will reset. On the next boot, the firmware bootloader encrypts: the firmware bootloader, application partitions and partitions marked as encrypted then resets. Encrypting in-place can take time, up to a minute for large partitions. After that, the application is decrypted at runtime and executed. If using Development Mode, then the easiest way to update and re-flash binaries is Re-flashing Updated Partitions. If using Release Mode, then it is possible to pre-encrypt the binaries on the host and then flash them as ciphertext. See Manually Encrypting Files.
Re-flashing Updated Partitions If you update your application code (done in plaintext) and want to re-flash it, you will need to encrypt it before flashing. To encrypt the application and flash it in one step, run:
idf.py encrypted-app-flash monitor
If all partitions needs to be updated in encrypted format, run:
idf.py encrypted-flash monitor

Release Mode
In Release mode, UART bootloader cannot perform flash encryption operations. New plaintext images can ONLY be downloaded using the over-the-air (OTA) scheme which will encrypt the plaintext image before writing to flash.
To use this mode, take the following steps:
1. Ensure that you have an ESP32-S3 device with default flash encryption eFuse settings as shown in Relevant eFuses.
See how to check ESP32-S3 Flash Encryption Status.
2. In Project Configuration Menu, do the following:
· Enable flash encryption on boot · Select Release mode (Note that once Release mode is selected, the
EFUSE_DIS_DOWNLOAD_MANUAL_ENCRYPT eFuse bit will be burned to disable flash encryption hardware in ROM Download Mode.) · Select UART ROM download mode (Permanently switch to Secure mode (recommended)). This is the default option, and is recommended. It is also possible to change this configuration setting to permanently disable UART ROM download mode, if this mode is not needed. · Select the appropriate bootloader log verbosity · Save the configuration and exit.
Enabling flash encryption will increase the size of bootloader, which might require updating partition table offset. See Bootloader Size.
3. Run the command given below to build and flash the complete images.

Espressif Systems

1762

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
idf.py flash monitor
Note: This command does not include any user files which should be written to the partitions on the flash memory. Please write them manually before running this command otherwise the files should be encrypted separately before writing.
This command will write to flash memory unencrypted images: the firmware bootloader, the partition table and applications. Once the flashing is complete, ESP32-S3 will reset. On the next boot, the firmware bootloader encrypts: the firmware bootloader, application partitions and partitions marked as encrypted then resets. Encrypting in-place can take time, up to a minute for large partitions. After that, the application is decrypted at runtime and executed. Once the flash encryption is enabled in Release mode, the bootloader will write-protect the SPI_BOOT_CRYPT_CNT eFuse. For subsequent plaintext field updates, use OTA scheme.
Note: If you have pre-generated the flash encryption key and stored a copy, and the UART download mode is not permanently disabled via CONFIG_SECURE_UART_ROM_DL_MODE , then it is possible to update the flash locally by pre-encrypting the files and then flashing the ciphertext. See Manually Encrypting Files.
Best Practices
When using Flash Encryption in production: · Do not reuse the same flash encryption key between multiple devices. This means that an attacker who copies encrypted data from one device cannot transfer it to a second device. · The UART ROM Download Mode should be disabled entirely if it is not needed, or permanently set to oSecure Download Modepotherwise. Secure Download Mode permanently limits the available commands to basic flash read and write only. The default behaviour is to set Secure Download Mode on first boot in Release mode. To disable Download Mode entirely select select the CONFIG_SECURE_UART_ROM_DL_MODE to oPermanently disable ROM Download Mode (recommended)p or call esp_efuse_disable_rom_download_mode() at runtime. · Enable Secure Boot as an extra layer of protection, and to prevent an attacker from selectively corrupting any part of the flash before boot.
4.15.5 Possible Failures
Once flash encryption is enabled, the SPI_BOOT_CRYPT_CNT eFuse value will have an odd number of bits set. It means that all the partitions marked with the encryption flag are expected to contain encrypted ciphertext. Below are the three typical failure cases if the ESP32-S3 is erroneously loaded with plaintext data:
1. If the bootloader partition is re-flashed with a plaintext firmware bootloader image, the ROM bootloader will fail to load the firmware bootloader resulting in the following failure:
rst:0x3 (SW_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) invalid header: 0xb414f76b invalid header: 0xb414f76b invalid header: 0xb414f76b invalid header: 0xb414f76b invalid header: 0xb414f76b invalid header: 0xb414f76b invalid header: 0xb414f76b

Espressif Systems

1763

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Note: The value of invalid header will be different for every application.

Note: This error also appears if the flash contents are erased or corrupted.

2. If the firmware bootloader is encrypted, but the partition table is re-flashed with a plaintext partition table image, the bootloader will fail to read the partition table resulting in the following failure:

rst:0x3 (SW_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)

configsip: 0, SPIWP:0xee

clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00

mode:DIO, clock div:2

load:0x3fff0018,len:4

load:0x3fff001c,len:10464

ho 0 tail 12 room 4

load:0x40078000,len:19168

load:0x40080400,len:6664

entry 0x40080764

I (60) boot: ESP-IDF v4.0-dev-763-g2c55fae6c-dirty 2nd stage bootloader

I (60) boot: compile time 19:15:54

I (62) boot: Enabling RNG early entropy source...

I (67) boot: SPI Speed

: 40MHz

I (72) boot: SPI Mode

: DIO

I (76) boot: SPI Flash Size : 4MB

E (80) flash_parts: partition 0 invalid magic number 0x94f6

E (86) boot: Failed to verify partition table

E (91) boot: load partition table error!

3. If the bootloader and partition table are encrypted, but the application is re-flashed with a plaintext application image, the bootloader will fail to load the application resulting in the following failure:

rst:0x3 (SW_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)

configsip: 0, SPIWP:0xee

clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00

mode:DIO, clock div:2

load:0x3fff0018,len:4

load:0x3fff001c,len:8452

load:0x40078000,len:13616

load:0x40080400,len:6664

entry 0x40080764

I (56) boot: ESP-IDF v4.0-dev-850-gc4447462d-dirty 2nd stage bootloader

I (56) boot: compile time 15:37:14

I (58) boot: Enabling RNG early entropy source...

I (64) boot: SPI Speed

: 40MHz

I (68) boot: SPI Mode

: DIO

I (72) boot: SPI Flash Size : 4MB

I (76) boot: Partition Table:

I (79) boot: ## Label

Usage

Type ST Offset Length

I (87) boot: 0 nvs

WiFi data

01 02 0000a000 00006000

I (94) boot: 1 phy_init

RF data

01 01 00010000 00001000

I (102) boot: 2 factory

factory app

00 00 00020000 00100000

I (109) boot: End of partition table

E (113) esp_image: image at 0x20000 has invalid magic byte

W (120) esp_image: image at 0x20000 has invalid SPI mode 108

W (126) esp_image: image at 0x20000 has invalid SPI size 11

E (132) boot: Factory app partition is not bootable

E (138) boot: No bootable app partitions in the partition table

Espressif Systems

1764

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.15.6 ESP32-S3 Flash Encryption Status
1. Ensure that you have an ESP32-S3 device with default flash encryption eFuse settings as shown in Relevant eFuses.
To check if flash encryption on your ESP32-S3 device is enabled, do one of the following: · flash the application example security/flash_encryption onto your device. This application prints the SPI_BOOT_CRYPT_CNT eFuse value and if flash encryption is enabled or disabled. · Find the serial port name under which your ESP32-S3 device is connected, replace PORT with your port name in the following command, and run it:
espefuse.py -p PORT summary
4.15.7 Reading and Writing Data in Encrypted Flash
ESP32-S3 application code can check if flash encryption is currently enabled by calling esp_flash_encryption_enabled(). Also, a device can identify the flash encryption mode by calling esp_get_flash_encryption_mode(). Once flash encryption is enabled, be more careful with accessing flash contents from code.
Scope of Flash Encryption
Whenever the SPI_BOOT_CRYPT_CNT eFuse is set to a value with an odd number of bits, all flash content accessed via the MMUns flash cache is transparently decrypted. It includes:
· Executable application code in flash (IROM). · All read-only data stored in flash (DROM). · Any data accessed via spi_flash_mmap(). · The firmware bootloader image when it is read by the ROM bootloader.
Important: The MMU flash cache unconditionally decrypts all existing data. Data which is stored unencrypted in flash memory will also be otransparently decryptedpvia the flash cache and will appear to software as random garbage.
Reading from Encrypted Flash
To read data without using a flash cache MMU mapping, you can use the partition read function esp_partition_read(). This function will only decrypt data when it is read from an encrypted partition. Data read from unencrypted partitions will not be decrypted. In this way, software can access encrypted and nonencrypted flash in the same way. You can also use the following SPI flash API functions:
· esp_flash_read() to read raw (encrypted) data which will not be decrypted · esp_flash_read_encrypted() to read and decrypt data The ROM function SPIRead() can read data without decryption, however, this function is not supported in esp-idf applications. Data stored using the Non-Volatile Storage (NVS) API is always stored and read decrypted from the perspective of flash encryption. It is up to the library to provide encryption feature if required. Refer to NVS Encryption for more details.

Espressif Systems

1765

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Writing to Encrypted Flash
It is recommended to use the partition write function esp_partition_write(). This function will only encrypt data when it is written to an encrypted partition. Data written to unencrypted partitions will not be encrypted. In this way, software can access encrypted and non-encrypted flash in the same way. You can also pre-encrypt and write data using the function esp_flash_write_encrypted() Also, the following ROM function exist but not supported in esp-idf applications:
· esp_rom_spiflash_write_encrypted pre-encrypts and writes data to flash · SPIWrite writes unencrypted data to flash Since data is encrypted in blocks, the minimum write size for encrypted data is 16 bytes and the alignment is also 16 bytes.
4.15.8 Updating Encrypted Flash
OTA Updates
OTA updates to encrypted partitions will automatically write encrypted data if the function esp_partition_write() is used. Before building the application image for OTA updating of an already encrypted device, enable the option Enable flash encryption on boot in project configuration menu. For general information about ESP-IDF OTA updates, please refer to OTA
Updating Encrypted Flash via Serial
Flashing an encrypted device via serial bootloader requires that the serial bootloader download interface has not been permanently disabled via eFuse. In Development Mode, the recommended method is Re-flashing Updated Partitions. In Release Mode, if a copy of the same key stored in eFuse is available on the host then itns possible to pre-encrypt files on the host and then flash them. See Manually Encrypting Files.
4.15.9 Disabling Flash Encryption
If flash encryption was enabled accidentally, flashing of plaintext data will soft-brick the ESP32-S3. The device will reboot continuously, printing the error flash read err, 1000 or invalid header: 0xXXXXXX. For flash encryption in Development mode, encryption can be disabled by burning the SPI_BOOT_CRYPT_CNT eFuse. It can only be done one time per chip by taking the following steps:
1. In Project Configuration Menu, disable Enable flash encryption on boot, then save and exit. 2. Open project configuration menu again and double-check that you have disabled this option! If this option is
left enabled, the bootloader will immediately re-enable encryption when it boots. 3. With flash encryption disabled, build and flash the new bootloader and application by running idf.py
flash. 4. Use espefuse.py (in components/esptool_py/esptool) to disable the
SPI_BOOT_CRYPT_CNT by running:
espefuse.py burn_efuse SPI_BOOT_CRYPT_CNT
Reset the ESP32-S3. Flash encryption will be disabled, and the bootloader will boot as usual.

Espressif Systems

1766

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.15.10 Key Points About Flash Encryption
· Flash memory contents is encrypted using XTS-AES-128 or XTS-AES-256. The flash encryption key is 256 bits and 512 bits respectively and stored in one or two BLOCK_KEYN eFuses internal to the chip and, by default, is protected from software access.
· Flash access is transparent via the flash cache mapping feature of ESP32-S3 - any flash regions which are mapped to the address space will be transparently decrypted when read. Some data partitions might need to remain unencrypted for ease of access or might require the use of flashfriendly update algorithms which are ineffective if the data is encrypted. NVS partitions for non-volatile storage cannot be encrypted since the NVS library is not directly compatible with flash encryption. For details, refer to NVS Encryption.
· If flash encryption might be used in future, the programmer must keep it in mind and take certain precautions when writing code that uses encrypted flash.
· If secure boot is enabled, re-flashing the bootloader of an encrypted device requires a oRe-flashablepsecure boot digest (see Flash Encryption and Secure Boot).
Enabling flash encryption will increase the size of bootloader, which might require updating partition table offset. See Bootloader Size.
Important: Do not interrupt power to the ESP32-S3 while the first boot encryption pass is running. If power is interrupted, the flash contents will be corrupted and will require flashing with unencrypted data again. In this case, re-flashing will not count towards the flashing limit.
4.15.11 Limitations of Flash Encryption
Flash encryption protects firmware against unauthorised readout and modification. It is important to understand the limitations of the flash encryption feature:
· Flash encryption is only as strong as the key. For this reason, we recommend keys are generated on the device during first boot (default behaviour). If generating keys off-device, ensure proper procedure is followed and donnt share the same key between all production devices.
· Not all data is stored encrypted. If storing data on flash, check if the method you are using (library, API, etc.) supports flash encryption.
· Flash encryption does not prevent an attacker from understanding the high-level layout of the flash. This is because the same AES key is used for every pair of adjacent 16 byte AES blocks. When these adjacent 16 byte blocks contain identical content (such as empty or padding areas), these blocks will encrypt to produce matching pairs of encrypted blocks. This may allow an attacker to make high-level comparisons between encrypted devices (i.e. to tell if two devices are probably running the same firmware version).
· Flash encryption alone may not prevent an attacker from modifying the firmware of the device. To prevent unauthorised firmware from running on the device, use flash encryption in combination with Secure Boot.
4.15.12 Flash Encryption and Secure Boot
It is recommended to use flash encryption in combination with Secure Boot. However, if Secure Boot is enabled, additional restrictions apply to device re-flashing:
· OTA Updates are not restricted, provided that the new app is signed correctly with the Secure Boot signing key.
4.15.13 Advanced Features
The following section covers advanced features of flash encryption.

Espressif Systems

1767

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Encrypted Partition Flag

Some partitions are encrypted by default. Other partitions can be marked in the partition table description as requiring encryption by adding the flag encrypted to the partitionsnflag field. As a result, data in these marked partitions will be treated as encrypted in the same manner as an app partition.

# Name, Type, SubType, Offset, Size, Flags

nvs,

data, nvs,

0x9000, 0x6000

phy_init, data, phy,

0xf000, 0x1000

factory, app, factory, 0x10000, 1M

secret_data, 0x40, 0x01, 0x20000, 256K, encrypted

For details on partition table description, see partition table.
Further information about encryption of partitions:
· Default partition tables do not include any encrypted data partitions. · With flash encryption enabled, the app partition is always treated as encrypted and does not require marking. · If flash encryption is not enabled, the flag oencryptedphas no effect. · You can also consider protecting phy_init data from physical access, readout, or modification, by marking
the optional phy partition with the flag encrypted. · The nvs partition cannot be encrypted, because the NVS library is not directly compatible with flash encryp-
tion.

Enabling UART Bootloader Encryption/Decryption
On the first boot, the flash encryption process burns by default the following eFuses:
· DIS_DOWNLOAD_MANUAL_ENCRYPT which disables flash encryption operation when running in UART bootloader boot mode.
· DIS_DOWNLOAD_ICACHE and DIS_DOWNLOAD_DCACHE which disables the entire MMU flash cache when running in UART bootloader mode.
· HARD_DIS_JTAG and DIS_USB_JTAG which disables JTAG. · DIS_LEGACY_SPI_BOOT which disables Legacy SPI boot mode
However, before the first boot you can choose to keep any of these features enabled by burning only selected eFuses and write-protect the rest of eFuses with unset value 0. For example:
espefuse.py --port PORT burn_efuse DIS_DOWNLOAD_MANUAL_ENCRYPT espefuse.py --port PORT write_protect_efuse DIS_DOWNLOAD_MANUAL_ENCRYPT

Note: Set all appropriate bits before write-protecting! Write protection of all the three eFuses is controlled by one bit. It means that write-protecting one eFuse bit will inevitably write-protect all unset eFuse bits.
Write protecting these eFuses to keep them unset is not currently very useful, as esptool.py does not support reading encrypted flash.
JTAG Debugging
By default, when Flash Encryption is enabled (in either Development or Release mode) then JTAG debugging is disabled via eFuse. The bootloader does this on first boot, at the same time it enables flash encryption. See JTAG with Flash Encryption or Secure Boot for more information about using JTAG Debugging with Flash Encryption.

Espressif Systems

1768

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Manually Encrypting Files
Manually encrypting or decrypting files requires the flash encryption key to be pre-burned in eFuse (see Using Host Generated Key) and a copy to be kept on the host. If the flash encryption is configured in Development Mode then itn s not necessary to keep a copy of the key or follow these steps, the simpler Re-flashing Updated Partitions steps can be used. The key file should be a single raw binary file (example: key.bin). For example, these are the steps to encrypt the file build/my-app.bin to flash at offset 0x10000. Run espsecure.py as follows: espsecure.py encrypt_flash_data --aes_xts --keyfile /path/to/key.bin --address 0x10000 --output my-app-ciphertext.bin build/my-app.bin
The file my-app-ciphertext.bin can then be flashed to offset 0x10000 using esptool.py. To see all of the command line options recommended for esptool.py, see the output printed when idf.py build succeeds.
Note: If the flashed ciphertext file is not recognized by the ESP32-S3 when it boots, check that the keys match and that the command line arguments match exactly, including the correct offset.
The command espsecure.py decrypt_flash_data can be used with the same options (and different input/output files), to decrypt ciphertext flash contents or a previously encrypted file.
4.15.14 External RAM
When Flash Encryption is enabled any data read from and written to external SPI RAM through the cache will also be encrypted/decrypted. This happens the same way and with the same key as for Flash Encryption. If Flash Encryption is enabled then encryption for external SPI RAM is also always enabled, it is not possible to separately control this functionality.
4.15.15 Technical Details
The following sections provide some reference information about the operation of flash encryption.
Flash Encryption Algorithm
· ESP32-S3 use the XTS-AES block cipher mode with 256 bit or 512 bit key size for flash encryption. · XTS-AES is a block cipher mode specifically designed for disc encryption and addresses the weaknesses other
potential modes (e.g. AES-CTR) have for this use case. A detailed description of the XTS-AES algorithm can be found in IEEE Std 1619-2007. · The flash encryption key is stored in one or two BLOCK_KEYN eFuses and, by default, is protected from further writes or software readout. · To see the full flash encryption algorithm implemented in Python, refer to the _flash_encryption_operation() function in the espsecure.py source code.
4.16 SPI Flash and External SPI RAM Configuration
This page is a guide for configuring SPI Flash and external SPI RAM. Supported frequency and mode combination, error handling are also elaborated.

Espressif Systems

1769

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

4.16.1 Terminology

Term SPI MSPI SDR DDR line mode FxRx

Definition Serial Peripheral Interface Memory SPI Peripheral, SPI Peripheral dedicated for memory Single Data Rate Double Data Rate Number of signals used to transfer data in the data phase of SPI transactions. e.g., for 4-bit-mode, the speed of the data phase would be 4 bit per clock cycle. F stands for Flash, R stands for PSRAM, x stands for line mode. e.g. F4R4 stands for an ESP32-S3 with Quad Flash and Quad PSRAM

Note: On ESP32-S3, MSPI stands for the SPI0/1. SPI0 and SPI1 share a common SPI bus. The main Flash and PSRAM are connected to the MSPI peripheral. CPU accesses them via Cache.

4.16.2 How to configure Flash and PSRAM
idf.py menuconfig is used to open the configuration menu.
Configure the Flash
The Flash related configurations are under Serial flasher config menu. 1. Flash type used on the board. For Octal Flash, select CONFIG_ESPTOOLPY_OCT_FLASH. For Quad Flash, uncheck this configuration. 2. Flash line mode. Select a line mode in CONFIG_ESPTOOLPY_FLASHMODE. The higher the line mode is, the faster the SPI speed is. See terminology above about the line mode. 3. Flash sample mode. Select a sample mode in CONFIG_ESPTOOLPY_FLASH_SAMPLE_MODE. DDR mode is faster than SDR mode. See terminology above about SDR and DDR mode. 4. Flash speed. Select a Flash frequency in CONFIG_ESPTOOLPY_FLASHFREQ. 5. Flash size. Flash size, in megabytes. Select a Flash size in CONFIG_ESPTOOLPY_FLASHSIZE.
Configure the PSRAM
To enable PSRAM, please enable the CONFIG_ESP32S3_SPIRAM_SUPPORT under Component config / ESP32-S3-Specific menu. Then all the PSRAM related configurations will be visible under SPI RAM config menu.
1. PSRAM type used on the board. Select a type in CONFIG_SPIRAM_MODE for Quad or Octal PSRAM. 2. PSRAM speed. Select a PSRAM frequency in CONFIG_SPIRAM_SPEED.
Note: Configuration 1 of Flash and PSRAM should be selected according to your actual hardware. For the reset of the above configurations:
· Flash and PSRAM share the same internal clock. · Quad Flash only supports STR mode. Octal Flash may support either/both STR/DTR modes under OPI mode,
depending on the flash model and the vendor. · Quad PSRAM only supports STR mode, while Octal PSRAM only supports DTR mode. Therefore, some limitations should be noticed when configuring configuration 2, 3 and 4 of Flash, and configuration 2 of PSRAM. Please refer to All Supported Modes and Speeds

Espressif Systems

1770

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Note: If a board with Octal Flash resets before the second-stage bootloader, please refer to Error Handling Chapter

4.16.3 All Supported Modes and Speeds
Note: For MSPI DDR mode, the data are sampled on both the positive edge and the negative edge. e.g.: if a Flash is set to 80 MHz and DDR mode, then the final speed of the Flash is 160 MHz. This is faster than the Flash setting to 120 Mhz and STR mode.

F8R8 Hardware

Group A B C C C D

Flash mode 120 MHz SDR 80 MHz DDR 80 MHz SDR 40 MHz DDR < 40 MHz

Group A B C C C D

PSRAM mode N.A. 80 MHz DDR 40 MHz DDR
disable

1. Flash mode in group A works with PSRAM mode in group A/D 2. Flash mode in group B/C works with PSRAM mode in group B/C/D

F4R8 Hardware

Group A B C C D

Flash mode 120 MHz SDR 80 MHz SDR 40 MHz SDR 20 MHz SDR

Group A B C C D

PSRAM mode N.A. 80MHz DDR 40MHz DDR
disable

1. Flash mode in group A works with PSRAM mode in group A/D 2. Flash mode in group B/C works with PSRAM mode in group B/C/D

F4R4 Hardware

Type A B C C D

Flash 120 MHz 80 MHz 40 MHz 20 MHz

Type A B C C D

PSRAM 120MHz 80MHz 40MHz
disable

1. Flash in A works with PSRAM in A/C/D 2. Flash in B works with PSRAM in B/C/D 3. Flash in C works with PSRAM in A/B/C/D

Espressif Systems

1771

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.16.4 Error handling
1. If a board with Octal Flash resets before the second-stage bootloader:
ESP-ROM:esp32s3-20210327 Build:Mar 27 2021 rst:0x7 (TG0WDT_SYS_RST),boot:0x18 (SPI_FAST_FLASH_BOOT) Saved PC:0x400454d5 SPIWP:0xee mode:DOUT, clock div:1 load:0x3fcd0108,len:0x171c ets_loader.c 78
it may mean that the necessary efuses are not correctly burnt. please check the eFuse bits of the chip using command espefuse.py summary. The 1st bootloader relies on an eFuse bit FLASH_TYPE to reset the Flash into the default mode (SPI mode). If this bit is not burnt and the flash is working in OPI mode, 1st bootloader may not be able to read from the flash and load the following images. Run this command to burn the eFuse bit:
python3 ./espefuse.py -p /dev/<serial_device> --do-not-confirm burn_efuse FLASH_ TYPE 1
Note: This step is irreversible. Please do check if your hardware is actually using an Octal Flash.

4.17 ESP-IDF FreeRTOS (SMP)

Note: This document assumes that the reader has a requisite understanding of Vanilla FreeRTOS (its features, behavior, and API usage). Refer to the Vanilla FreeRTOS documentation for more details.
This document describes the API and behavioral differences between Vanilla FreeRTOS and ESP-IDF FreeRTOS that were made in order to support Symmetric Multiprocessing (SMP). This document is split into the following parts.
Contents
· ESP-IDF FreeRTOS (SMP) ­ Overview ­ Symmetric Multiprocessing  Basic Concepts  SMP on an ESP Target ­ Tasks  Creation  Execution  Deletion ­ SMP Scheduler  Fixed Priority  Preemption  Time Slicing  Tick Interrupts  Idle Tasks  Scheduler Suspension  Disabling Interrupts

Espressif Systems

1772

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
 Startup and Termination ­ Critical Sections
 API Changes  Implementation  Restrictions and Considerations ­ Misc  Floating Point Usage  ESP-IDF FreeRTOS Single Core
4.17.1 Overview
The original FreeRTOS (hereinafter referred to as Vanilla FreeRTOS) is a small and efficient Real Time Operating System supported on many single-core MCUs and SoCs. However, numerous ESP targets (such as the ESP32 and ESP32-S3) are capable of dual core symmetric multiprocessing (SMP). Therefore, the version of FreeRTOS used in ESP-IDF (hereinafter referred to as ESP-IDF FreeRTOS) is a modified version of Vanilla FreeRTOS v10.4.3. Theses modifications allow ESP-IDF FreeRTOS to utilize the dual core SMP capabilities of ESP SoCs.
Note: · For information regarding features that have been added to ESP-IDF FreeRTOS, see ESP-IDF FreeRTOS Additions. · For a detailed ESP-IDF FreeRTOS API Reference, see FreeRTOS API reference.
4.17.2 Symmetric Multiprocessing
Basic Concepts
SMP (Symmetric Multiprocessing) is a computing architecture where two or more identical CPUs (cores) are connected to a single shared main memory and controlled by a single operating system. In general, an SMP system l
· has multiple cores running independently. Each core has its own register file, interrupts, and interrupt handling. · presents an identical view of memory to each core. Thus a piece of code that accesses a particular memory
address will have the same effect regardless of which core it runs on. The main advantages of an SMP system compared to single core or Asymmetric Multiprocessing systems are thatl
· the presence of multiple CPUs allows for multiple hardware threads, thus increases overall processing throughput.
· having symmetric memory means that threads can switch cores during execution. This in general can lead to better CPU utilization.
Although an SMP system allows threads to switch cores, there are scenarios where a thread must/should only run on a particular core. Therefore, threads in an SMP systems will also have a core affinity that specifies which particular core the thread is allowed to run on.
· A thread that is pinned to a particular core will only be able to run on that core · A thread that is unpinned will be allowed to switch between cores during execution instead of being pinned to
a particular core.
SMP on an ESP Target
ESP targets (such as the ESP32, ESP32-S3) are dual core SMP SoCs. These targets have the following hardware features that make them SMP capable:

Espressif Systems

1773

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· Two identical cores known as CPU0 (i.e., Protocol CPU or PRO_CPU) and CPU1 (i.e., Application CPU or APP_CPU). This means that the execution of a piece of code is identical regardless of which core it runs on.
· Symmetric memory (with some small exceptions). ­ If multiple cores access the same memory address, their access will be serialized at the memory bus level. ­ True atomic access to the same memory address is achieved via an atomic compare-and-swap instruction provided by the ISA.
· Cross-core interrupts that allow one CPU to trigger and interrupt on another CPU. This allows cores to signal each other.
Note: TheoPRO_CPUpandoAPP_CPUpaliases for CPU0 and CPU1 exist in ESP-IDF as they reflect how typical IDF applications will utilize the two CPUs. Typically, the tasks responsible for handling wireless networking (e.g., WiFi or Bluetooth) will be pinned to CPU0 (thus the name PRO_CPU), whereas the tasks handling the remainder of the application will be pinned to CPU1 (thus the name APP_CPU).
4.17.3 Tasks
Creation
Vanilla FreeRTOS provides the following functions to create a task: · xTaskCreate() creates a task. The taskns memory is dynamically allocated · xTaskCreateStatic() creates a task. The taskns memory is statically allocated (i.e., provided by the user)
However, in an SMP system, tasks need to be assigned a particular affinity. Therefore, ESP-IDF provides a PinnedToCore version of Vanilla FreeRTOSns task creation functions:
· xTaskCreatePinnedToCore() creates a task with a particular core affinity. The taskns memory is dynamically allocated.
· xTaskCreateStaticPinnedToCore() creates a task with a particular core affinity. The taskns memory is statically allocated (i.e., provided by the user)
The PinnedToCore versions of the task creation functions API differ from their vanilla counter parts by having an extra xCoreID parameter that is used to specify the created taskns core affinity. The valid values for core affinity are:
· 0 which pins the created task to CPU0 · 1 which pins the created task to CPU1 · tskNO_AFFINITY which allows the task to be run on both CPUs Note that ESP-IDF FreeRTOS still supports the vanilla versions of the task creation functions. However, they have been modified to simply call their PinnedToCore counterparts with tskNO_AFFINITY.
Note: ESP-IDF FreeRTOS also changes the units of ulStackDepth in the task creation functions. Task stack sizes in Vanilla FreeRTOS are specified in number of words, whereas in ESP-IDF FreeRTOS, the task stack sizes are specified in bytes.
Execution
The anatomy of a task in ESP-IDF FreeRTOS is the same as Vanilla FreeRTOS. More specifically, ESP-IDF FreeRTOS tasks:
· Can only be in one of following states: Running, Ready, Blocked, or Suspended. · Task functions are typically implemented as an infinite loop · Task functions should never return

Espressif Systems

1774

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Deletion
Task deletion in Vanilla FreeRTOS is called via vTaskDelete(). The function allows deletion of another task or the currently running task (if the provided task handle is NULL). The actual freeing of the taskns memory is sometimes delegated to the idle task (if the task being deleted is the currently running task).
ESP-IDF FreeRTOS provides the same vTaskDelete() function. However, due to the dual core nature, there are some behavioral differences when calling vTaskDelete() in ESP-IDF FreeRTOS:
· When deleting a task that is pinned to the other core, that taskns memory is always freed by the idle task of the other core (due to the need to clear FPU registers).
· When deleting a task that is currently running on the other core, a yield is triggered on the other core and the taskns memory is freed by one of the idle tasks (depending on the taskns core affinity)
· A deleted taskns memory is freed immediately ifl ­ The tasks is currently running on this core and is also pinned to this core ­ The task is not currently running and is not pinned to any core
Users should avoid calling vTaskDelete() on a task that is currently running on the other core. This is due to the fact that it is difficult to know what the task currently running on the other core is executing, thus can lead to unpredictable behavior such asl
· Deleting a task that is holding a mutex · Deleting a task that has yet to free memory it previously allocated
Where possible, users should design their application such that vTaskDelete() is only ever called on tasks in a known state. For example:
· Tasks self deleting (via vTaskDelete(NULL)) when their execution is complete and have also cleaned up all resources used within the task.
· Tasks placing themselves in the suspend state (via vTaskSuspend()) before being deleted by another task.
4.17.4 SMP Scheduler
The Vanilla FreeRTOS scheduler is best described as a Fixed Priority Preemptive scheduler with Time Slicing meaning that:
· Each tasks is given a constant priority upon creation. The scheduler executes highest priority ready state task · The scheduler can switch execution to another task without the cooperation of the currently running task · The scheduler will periodically switch execution between ready state tasks of the same priority (in a round
robin fashion). Time slicing is governed by a tick interrupt.
The ESP-IDF FreeRTOS scheduler supports the same scheduling features (i.e., Fixed Priority, Preemption, and Time Slicing) albeit with some small behavioral differences.
Fixed Priority
In Vanilla FreeRTOS, when scheduler selects a new task to run, it will always select the current highest priority ready state task. In ESP-IDF FreeRTOS, each core will independently schedule tasks to run. When a particular core selects a task, the core will select the highest priority ready state task that can be run by the core. A task can be run by the core if:
· The task has a compatible affinity (i.e., is either pinned to that core or is unpinned) · The task is not currently being run by another core
However, users should not assume that the two highest priority ready state tasks are always run by the scheduler as a taskns core affinity must also be accounted for. For example, given the following tasks:
· Task A of priority 10 pinned to CPU0 · Task B of priority 9 pinned to CPU0 · Task C of priority 8 pinned to CPU1

Espressif Systems

1775

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

The resulting schedule will have Task A running on CPU0 and Task C running on CPU1. Task B is not run even though it is the second highest priority task.

Preemption
In Vanilla FreeRTOS, the scheduler can preempt the currently running task if a higher priority task becomes ready to execute. Likewise in ESP-IDF FreeRTOS, each core can be individually preempted by the scheduler if the scheduler determines that a higher priority task can run on that core.
However, there are some instances where a higher priority task that becomes ready can be run on multiple cores. In this case, the scheduler will only preempt one core. The scheduler always gives preference to the current core when multiple cores can be preempted. In other words, if the higher priority ready task is unpinned and has a higher priority than the current priority of both cores, the scheduler will always choose to preempt the current core. For example, given the following tasks:
· Task A of priority 8 currently running on CPU0 · Task B of priority 9 currently running on CPU1 · Task C of priority 10 that is unpinned and was unblocked by Task B
The resulting schedule will have Task A running on CPU0 and Task C preempting Task B given that the scheduler always gives preference to the current core.

Time Slicing
The Vanilla FreeRTOS scheduler implements time slicing meaning that if current highest ready priority contains multiple ready tasks, the scheduler will switch between those tasks periodically in a round robin fashion. However, in ESP-IDF FreeRTOS, it is not possible to implement perfect Round Robin time slicing due to the fact that a particular task may not be able to run on a particular core due to the following reasons:
· The task is pinned to the another core. · For unpinned tasks, the task is already being run by another core. Therefore, when a core searches the ready state task list for a task to run, the core may need to skip over a few tasks in the same priority list or drop to a lower priority in order to find a ready state task that the core can run. The ESP-IDF FreeRTOS scheduler implements a Best Effort Round Robin time slicing for ready state tasks of the same priority by ensuring that tasks that have been selected to run will be placed at the back of the list, thus giving unselected tasks a higher priority on the next scheduling iteration (i.e., the next tick interrupt or yield) The following example demonstrates the Best Effort Round Robin time slicing in action. Assume that: · There are four ready state tasks of the same priority AX, B0, C1, D1 where: - The priority is the current
highest priority with ready state tasks - The first character represents the taskns names (i.e., A, B, C, D) - And the second character represents the tasks core pinning (and X means unpinned) · The task list is always searched from the head
--------------------------------------------------------------------------------
1. Starting state. None of the ready state tasks have been selected to run
Head [ AX , B0 , C1 , D0 ] Tail
--------------------------------------------------------------------------------
2. Core 0 has tick interrupt and searches for a task to run. Task A is selected and is moved to the back of the list
Core0--| Head [ AX , B0 , C1 , D0 ] Tail
0 (continues on next page)

Espressif Systems

1776

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Head [ B0 , C1 , D0 , AX ] Tail

(continued from previous page)

--------------------------------------------------------------------------------

3. Core 1 has a tick interrupt and searches for a task to run. Task B cannot be run due to incompatible affinity, so core 1 skips to Task C. Task C is selected and is moved to the back of the list

Core1-------|

0

Head [ B0 , C1 , D0 , AX ] Tail

01 Head [ B0 , D0 , AX , C1 ] Tail

--------------------------------------------------------------------------------

4. Core 0 has another tick interrupt and searches for a task to run. Task B is selected and moved to the back of the list

Core0--|

1

Head [ B0 , D0 , AX , C1 ] Tail

10 Head [ D0 , AX , C1 , B0 ] Tail
--------------------------------------------------------------------------------

5. Core 1 has another tick and searches for a task to run. Task D cannot be run due to incompatible affinity, so core 1 skips to Task A Task A is selected and moved to the back of the list

Core1-------|

0

Head [ D0 , AX , C1 , B0 ] Tail

01 Head [ D0 , C1 , B0 , AX ] Tail

The implications to users regarding the Best Effort Round Robin time slicing:
· Users cannot expect multiple ready state tasks of the same priority to run sequentially (as is the case in Vanilla FreeRTOS). As demonstrated in the example above, a core may need to skip over tasks.
· However, given enough ticks, a task will eventually be given some processing time. · If a core cannot find a task runnable task at the highest ready state priority, it will drop to a lower priority to
search for tasks. · To achieve ideal round robin time slicing, users should ensure that all tasks of a particular priority are pinned
to the same core.

Tick Interrupts
Vanilla FreeRTOS requires that a periodic tick interrupt occurs. The tick interrupt is responsible for:
· Incrementing the schedulerns tick count · Unblocking any blocked tasks that have timed out · Checking if time slicing is required (i.e., triggering a context switch) · Executing the application tick hook
In ESP-IDF FreeRTOS, each core will receive a periodic interrupt and independently run the tick interrupt. The tick interrupts on each core are of the same period but can be out of phase. Furthermore, the tick interrupt responsibilities listed above are not run by all cores:

Espressif Systems

1777

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· CPU0 will execute all of the tick interrupt responsibilities listed above · CPU1 will only check for time slicing and execute the application tick hook
Note: CPU0 is solely responsible for keeping time in ESP-IDF FreeRTOS. Therefore anything that prevents CPU0 from incrementing the tick count (such as suspending the scheduler on CPU0) will cause the entire schedulers time keeping to lag behind.
Idle Tasks
Vanilla FreeRTOS will implicitly create an idle task of priority 0 when the scheduler is started. The idle task runs when no other task is ready to run, and it has the following responsibilities:
· Freeing the memory of deleted tasks · Executing the application idle hook In ESP-IDF FreeRTOS, a separate pinned idle task is created for each core. The idle tasks on each core have the same responsibilities as their vanilla counterparts.
Scheduler Suspension
Vanilla FreeRTOS allows the scheduler to be suspended/resumed by calling vTaskSuspendAll() and xTaskResumeAll() respectively. While the scheduler is suspended:
· Task switching is disabled but interrupts are left enabled. · Calling any blocking/yielding function is forbidden, and time slicing is disabled. · The tick count is frozen (but the tick interrupt will still occur to execute the application tick hook) On scheduler resumption, xTaskResumeAll() will catch up all of the lost ticks and unblock any timed out tasks. In ESP-IDF FreeRTOS, suspending the scheduler across multiple cores is not possible. Therefore when vTaskSuspendAll() is called: · Task switching is disabled only on the current core but interrupts for the current core are left enabled · Calling any blocking/yielding function on the current core is forbidden. Time slicing is disabled on the current
core. · If suspending on CPU0, the tick count is frozen. The tick interrupt will still occur to execute the application
tick hook. When resuming the scheduler on CPU0, xTaskResumeAll() will catch up all of the lost ticks and unblock any timed out tasks.
Warning: Given that scheduler suspension on ESP-IDF FreeRTOS will only suspend scheduling on a particular core, scheduler suspension is NOT a valid method ensuring mutual exclusion between tasks when accessing shared data. Users should use proper locking primitives such as mutexes or spinlocks if they require mutual exclusion.
Disabling Interrupts
Vanilla FreeRTOS allows interrupts to be disabled and enabled by calling taskDISABLE_INTERRUPTS and taskENABLE_INTERRUPTS respectively. ESP-IDF FreeRTOS provides the same API, however interrupts will only disabled or enabled on the current core.
Warning: Disabling interrupts is a valid method of achieve mutual exclusion in Vanilla FreeRTOS (and single core systems in general). However, in an SMP system, disabling interrupts is NOT a valid method ensuring mutual exclusion. Refer to Critical Sections for more details.

Espressif Systems

1778

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Startup and Termination
ESP-IDF FreeRTOS does not require users to call vTaskStartScheduler() to start the scheduler. The startup flow of an ESP-IDF application will already call this automatically. The entry point for user code is a user defined void app_main(void) function. For more details regarding the startup of ESP-IDF FreeRTOS applications, see ESP-IDF FreeRTOS Applications.
ESP-IDF FreeRTOS does not support scheduler termination. Calling vTaskEndScheduler() will simply cause the application to abort.
4.17.5 Critical Sections
API Changes
Vanilla FreeRTOS implements critical sections by disabling interrupts, This prevents preemptive context switches and the servicing of ISRs during a critical section. Thus a task/ISR that enters a critical section is guaranteed to be the sole entity to access a shared resource. Critical sections in Vanilla FreeRTOS have the following API:
· taskENTER_CRITICAL() enters a critical section by disabling interrupts · taskEXIT_CRITICAL() exits a critical section by reenabling interrupts · taskENTER_CRITICAL_FROM_ISR() enters a critical section from an ISR by disabling interrupt nesting · taskEXIT_CRITICAL_FROM_ISR() exits a critical section from an ISR by reenabling interrupt nesting
However, in an SMP system, merely disabling interrupts does not constitute a critical section as the presence of other cores means that a shared resource can still be concurrently accessed. Therefore, critical sections in ESP-IDF FreeRTOS are implemented using spinlocks. To accommodate the spinlocks, the ESP-IDF FreeRTOS critical section APIs contain an additional spinlock parameter as shown below:
· Spinlocks are of portMUX_TYPE (not to be confused to FreeRTOS mutexes) · taskENTER_CRITICAL(&mux) enters a critical from a task context · taskEXIT_CRITICAL(&mux) exits a critical section from a task context · taskENTER_CRITICAL_ISR(&mux) enters a critical section from an interrupt context · taskEXIT_CRITICAL_ISR(&mux) exits a critical section from an interrupt context
Note: The critical section API can be called recursively (i.e., nested critical sections). Entering a critical section multiple times recursively is valid so long as the critical section is exited the same number of times it was entered. However, given that critical sections can target different spinlocks, users should take care to avoid dead locking when entering critical sections recursively.
Implementation
In ESP-IDF FreeRTOS, the process of a particular core entering and exiting a critical section is as follows:
· For taskENTER_CRITICAL(&mux) (or taskENTER_CRITICAL_ISR(&mux)) 1. The core disables its interrupts (or interrupt nesting) up to configMAX_SYSCALL_INTERRUPT_PRIORITY 2. The core then spins on the spinlock using an atomic compare-and-set instruction until it acquires the lock. A lock is acquired when the core is able to set the lockns owner value to the corens ID. 3. Once the spinlock is acquired, the function returns. The remainder of the critical section runs with interrupts (or interrupt nesting) disabled.
· For taskEXIT_CRITICAL(&mux) (or taskEXIT_CRITICAL_ISR(&mux)) 1. The core releases the spinlock by clearing the spinlockns owner value 2. The core re-enables interrupts (or interrupt nesting)

Espressif Systems

1779

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Restrictions and Considerations
Given that interrupts (or interrupt nesting) are disabled during a critical section, there are multiple restrictions regarding what can be done within a critical sections. During a critical section, users should keep the following restrictions and considerations in mind:
· Critical sections should be as kept as short as possible ­ The longer the critical section lasts, the longer a pending interrupt can be delayed. ­ A typical critical section should only access a few data structures and/or hardware registers ­ If possible, defer as much processing and/or event handling to the outside of critical sections.
· FreeRTOS API should not be called from within a critical section · Users should never call any blocking or yielding functions within a critical section
4.17.6 Misc
Floating Point Usage
Usually, when a context switch occurs:
· the current state of a CPUns registers are saved to the stack of task being switch out · the previously saved state of the CPUns registers are loaded from the stack of the task being switched in
However, ESP-IDF FreeRTOS implements Lazy Context Switching for the FPU (Floating Point Unit) registers of a CPU. In other words, when a context switch occurs on a particular core (e.g., CPU0), the state of the corens FPU registers are not immediately saved to the stack of the task getting switched out (e.g., Task A). The FPUns registers are left untouched until:
· A different task (e.g., Task B) runs on the same core and uses the FPU. This will trigger an exception that will save the FPU registers to Task Ans stack.
· Task A getns scheduled to the same core and continues execution. Saving and restoring the FPUns registers is not necessary in this case.
However, given that tasks can be unpinned thus can be scheduled on different cores (e.g., Task A switches to CPU1), it is unfeasible to copy and restore the FPUns registers across cores. Therefore, when a task utilizes the FPU (by using a float type in its call flow), ESP-IDF FreeRTOS will automatically pin the task to the current core it is running on. This ensures that all tasks that uses the FPU are always pinned to a particular core.
Furthermore, ESP-IDF FreeRTOS by default does not support the usage of the FPU within an interrupt context given that the FPUns register state is tied to a particular task.
Note: ESP targets that contain an FPU do not support hardware acceleration for double precision floating point arithmetic (double). Instead double is implemented via software hence the behavioral restrictions regarding the float type do not apply to double. Note that due to the lack of hardware acceleration, double operations may consume significantly more CPU time in comparison to float.

ESP-IDF FreeRTOS Single Core
Although ESP-IDF FreeRTOS is an SMP scheduler, some ESP targets are single core (such as the ESP32-S2 and ESP32-C3). When building ESP-IDF applications for these targets, ESP-IDF FreeRTOS is still used but the number of cores will be set to 1 (i.e., the CONFIG_FREERTOS_UNICORE will always be enabled for single core targets). For multicore targets (such as the ESP32 and ESP32-S3), CONFIG_FREERTOS_UNICORE can also be set. This will result in ESP-IDF FreeRTOS only running on CPU0, and all other cores will be inactive.
Note: Users should bear in mind that enabling CONFIG_FREERTOS_UNICORE is NOT equivalent to running Vanilla FreeRTOS. The additional API of ESP-IDF FreeRTOS can still be called, and the behavior changes of ESP-IDF FreeRTOS will incur a small amount of overhead even when compiled for only a single core.

Espressif Systems

1780

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.18 Hardware Abstraction
Hardware abstraction in ESP-IDF are a group of API that allow users to control peripherals at differing levels of abstraction, as opposed to interfacing with hardware using only the ESP-IDF drivers. ESP-IDF Hardware abstraction will likely be useful for users writing high performance bare-metal drivers, or for those attempting to port an ESP chip to another platform. This guide is split into the following sections:
1. Architecture 2. LL (Low Level) Layer 3. HAL (Hardware Abstraction Layer)
Warning: Hardware abstraction API (excluding the driver and xxx_types.h) should be considered an experimental feature, thus cannot be considered public API. Hardware abstraction API do not adhere to the API name changing restrictions of ESP-IDFns versioning scheme. In other words, it is possible that Hardware Abstraction API may change in between non-major release versions.
Note: Although this document mainly focuses on hardware abstraction of peripherals (e.g., UART, SPI, I2C), certain layers of hardware abstraction extend to other aspects of hardware as well (e.g., some of the CPUns features are partially abstracted).
4.18.1 Architecture
Hardware abstraction in ESP-IDF is comprised of the following layers, ordered from low level (closer to hardware) to high level (further away from hardware) of abstraction.
· Low Level (LL) Layer · Hardware Abstraction Layer (HAL) · Driver Layers The LL Layer, and HAL are entirely contained within the hal component. Each layer is dependent on the layer below it (i.e, driver depends on HAL, HAL depends on LL, LL depends on the register header files). For a particular peripheral xxx, its hardware abstraction will generally consist of the header files described in the table below. Files that are Target Specific will have a separate implementation for each target (i.e., a separate copy for each chip). However, the #include directive will still be target-independent (i.e., will be the same for different targets) as the build system will automatically include the correct version of the header and source files.

Espressif Systems

1781

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Include Directive
#include 'soc/ xxx_caps.h"
#include "soc/ xxx_struct.h" #include "soc/ xxx_reg.h" #include "soc/ xxx_pins.h" #include "soc/ xxx_periph.h" #include "hal/ xxx_types.h

Table 21: Hardware Abstraction Header Files
TargeDt escription Specific Y This header contains a list of C macros specifying the various capabilities of
the ESP32-S3ns peripheral xxx. Hardware capabilities of a peripheral include things such as the number of channels, DMA support, hardware FIFO/buffer lengths, etc. Y The two headers contain a representation of a peripheralns registers in C structure and C macro format respectively. Users can operate a peripheral at the register level via either of these two header files.
Y If certain signals of a peripheral are mapped to a particular pin of the ESP32S3, their mappings are defined in this header as C macros.
N This header is mainly used as a convenience header file to automatically include xxx_caps.h, xxx_struct.h, and xxx_reg.h.
N This header contains type definitions and macros that are shared among the LL, HAL, and driver layers. Moreover, it is considered public API thus can be included by the application level. The shared types and definitions usually related to non-implementation specific concepts such as the following: · Protocol related types/macros such a frames, modes, common bus speeds, etc. · Features/characteristics of an xxx peripheral that are likely to be present on any implementation (implementation-independent) such as channels, operating modes, signal amplification or attenuation intensities, etc.

#include "hal/ Y xxx_ll.h"
#include "hal/ Y xxx_hal.h"
#include "driver/ N xxx.h"

This header contains the Low Level (LL) Layer of hardware abstraction. LL Layer API are primarily used to abstract away register operations into readable functions. The Hardware Abstraction Layer (HAL) is used to abstract away peripheral operation steps into functions (e.g., reading a buffer, starting a transmission, handling an event, etc). The HAL is built on top of the LL Layer. The driver layer is the highest level of ESP-IDFns hardware abstraction. Driver layer API are meant to be called from ESP-IDF applications, and internally utilize OS primitives. Thus, driver layer API are event-driven, and can used in a multi-threaded environment.

4.18.2 LL (Low Level) Layer
The primary purpose of the LL Layer is to abstract away register field access into more easily understandable functions. LL functions essentially translate various in/out arguments into the register fields of a peripheral in the form of get/set functions. All the necessary bit shifting, masking, offsetting, and endianness of the register fields should be handled by the LL functions.
//Inside xxx_ll.h
static inline void xxx_ll_set_baud_rate(xxx_dev_t *hw, xxx_ll_clk_src_t clock_source, uint32_t baud_rate) {
uint32_t src_clk_freq = (source_clk == XXX_SCLK_APB) ? APB_CLK_FREQ : REF_CLK_ FREQ;
uint32_t clock_divider = src_clk_freq / baud; // Set clock select field hw->clk_div_reg.divider = clock_divider >> 4; // Set clock divider field hw->config.clk_sel = (source_clk == XXX_SCLK_APB) ? 0 : 1;
(continues on next page)

Espressif Systems

1782

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
(continued from previous page) }
static inline uint32_t xxx_ll_get_rx_byte_count(xxx_dev_t *hw) { return hw->status_reg.rx_cnt;
}
The code snippet above illustrates typical LL functions for a peripheral xxx. LL functions typically have the following characteristics:
· All LL functions are defined as static inline so that there is minimal overhead when calling these functions due to compiler optimization.
· The first argument should be a pointer to a xxx_dev_t type. The xxx_dev_t type is a structure representing the peripheralns registers, thus the first argument is always a pointer to the starting address of the peripheralns registers. Note that in some cases where the peripheral has multiple channels with identical register layouts, xxx_dev_t *hw may point to the registers of a particular channel instead.
· LL functions should be short and in most cases are deterministic. In other words, the worst case runtime of the LL function can be determined at compile time. Thus, any loops in LL functions should be finite bounded; however, there are currently a few exceptions to this rule.
· LL functions are not thread safe, it is the responsibility of the upper layers (driver layer) to ensure that registers or register fields are not accessed concurrently.
4.18.3 HAL (Hardware Abstraction Layer)
The HAL layer models the operational process of a peripheral as a set of general steps, where each step has an associated function. For each step, the details of a peripheralns register implementation (i.e., which registers need to be set/read) are hidden (abstracted away) by the HAL. By modelling peripheral operation as a set of functional steps, any minor hardware implementation differences of the peripheral between different targets or chip versions can be abstracted away by the HAL (i.e., handled transparently). In other words, the HAL API for a particular peripheral will remain mostly the same across multiple targets/chip versions.
The following HAL function examples are selected from the Watchdog Timer HAL as each function maps to one of the steps in a WDTns operation life cycle, thus illustrating how a HAL abstracts a peripheralns operation into functional steps.
// Initialize one of the WDTs void wdt_hal_init(wdt_hal_context_t *hal, wdt_inst_t wdt_inst, uint32_t prescaler, bool enable_intr);
// Configure a particular timeout stage of the WDT void wdt_hal_config_stage(wdt_hal_context_t *hal, wdt_stage_t stage, uint32_t timeout, wdt_stage_action_t behavior);
// Start the WDT void wdt_hal_enable(wdt_hal_context_t *hal);
// Feed (i.e., reset) the WDT void wdt_hal_feed(wdt_hal_context_t *hal);
// Handle a WDT timeout void wdt_hal_handle_intr(wdt_hal_context_t *hal);
// Stop the WDT void wdt_hal_disable(wdt_hal_context_t *hal);
// De-initialize the WDT void wdt_hal_deinit(wdt_hal_context_t *hal);
HAL functions will generally have the following characteristics:

Espressif Systems

1783

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

· The first argument to a HAL function has the xxx_hal_context_t * type. The HAL context type is used to store information about a particular instance of the peripheral (i.e. the context instance). A HAL context is initialized by the xxx_hal_init() function and can store information such as the following: ­ The channel number of this instance ­ Pointer to the peripheralns (or channelns) registers (i.e., a xxx_dev_t * type) ­ Information about an ongoing transaction (e.g., pointer to DMA descriptor list in use) ­ Some configuration values for the instance (e.g., channel configurations) ­ Variables to maintain state information regarding the instance (e.g., a flag to indicate if the instance is waiting for transaction to complete)
· HAL functions should not contain any OS primitives such as queues, semaphores, mutexes, etc. All synchronization/concurrency should be handled at higher layers (e.g., the driver).
· Some peripherals may have steps that cannot be further abstracted by the HAL, thus will end up being a direct wrapper (or macro) for an LL function.
· Some HAL functions may be placed in IRAM thus may carry an IRAM_ATTR or be placed in a separate xxx_hal_iram.c source file.

4.19 High-Level Interrupts
The Xtensa architecture has support for 32 interrupts, divided over 7 levels (levels 1 to 7, with 7 being an NMI), plus an assortment of exceptions. On the ESP32-S3, the interrupt mux allows most interrupt sources to be routed to these interrupts using the interrupt allocator. Normally, interrupts will be written in C, but ESP-IDF allows high-level interrupts to be written in assembly as well, resulting in very low interrupt latencies.

4.19.1 Interrupt Levels

Level 1 2-3 4 5 NMI dbg

Symbol N/A N/A xt_highint4 xt_highint5 xt_nmi xt_debugexception

Remark Exception and level 0 interrupts. Handled by ESP-IDF Medium level interrupts. Handled by ESP-IDF Normally used by ESP-IDF debug logic Free to use Free to use Debug exception. Called on e.g. a BREAK instruction.

Using these symbols is done by creating an assembly file (suffix .S) and defining the named symbols, like this:

.section .iram1,"ax"

.global

xt_highint5

.type

xt_highint5,@function

.align

4

xt_highint5:

... your code here

rsr

a0, EXCSAVE_5

rfi

5

For a real-life example, see the esp_system/port/soc/esp32s3/highint_hdl.S file; the panic handler interrupt is implemented there.

4.19.2 Notes
· Do not call C code from a high-level interrupt; as these interrupts are run from a critical section, this can cause the target to crash. Note that although the panic handler interrupt does call normal C code, this exception is allowed due to the fact that this handler never returns (i.e., the application will not continue to run after the panic handler). so breaking C code execution flow is not a problem.

Espressif Systems

1784

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· Make sure your assembly code gets linked in. Indeed, as the free-to-use symbols are declared as weak, the linker may discard the file containing the symbol. This will happen if the only symbol defined, or used, from the user file is the xt_* free-to-use symbol. To avoid this, in the assembly file containing the xt_* symbol, define another symbol, like:
.global ld_include_my_isr_file ld_include_my_isr_file:
Here it is called ``ld_include_my_isr_file`` but can have any name, as long as it is not defined anywhere else in the project.
Then, in the component ``CMakeLists.txt``, add this name as an unresolved symbol to the ld command line arguments::
target_link_libraries(${COMPONENT_TARGET} "-u ld_include_my_isr_file")
This should cause the linker to always include the file defining ``ld_include_ my_isr_file``, causing the ISR to always be linked in.
· High-level interrupts can be routed and handled using esp_intr_alloc() and associated functions. The handler and handler arguments to esp_intr_alloc() must be NULL, however.
· In theory, medium priority interrupts could also be handled in this way. ESP-IDF does not support this yet.
4.20 JTAG Debugging
This document provides a guide to installing OpenOCD for ESP32-S3 and debugging using GDB. The document is structured as follows: Introduction Introduction to the purpose of this guide. How it Works? Description how ESP32-S3, JTAG interface, OpenOCD and GDB are interconnected and working
together to enable debugging of ESP32-S3. Selecting JTAG Adapter What are the criteria and options to select JTAG adapter hardware. Setup of OpenOCD Procedure to install OpenOCD and verify that it is installed. Configuring ESP32-S3 Target Configuration of OpenOCD software and setting up of JTAG adapter hardware,
which together make up the debugging target. Launching Debugger Steps to start up a debug session with GDB from Eclipse and from Command Line. Debugging Examples If you are not familiar with GDB, check this section for debugging examples provided from
Eclipse as well as from Command Line. Building OpenOCD from Sources Procedure to build OpenOCD from sources for Windows, Linux and macOS op-
erating systems. Tips and Quirks This section provides collection of tips and quirks related to JTAG debugging of ESP32-S3 with
OpenOCD and GDB.
4.20.1 Introduction
Espressif has ported OpenOCD to support the ESP32-S3 processor and the multi-core FreeRTOS cwhich is the foundation of most ESP32-S3 apps). Additionally, some extra tools have been written to provide extra features that OpenOCD does not support natively. This document provides a guide to installing OpenOCD for ESP32-S3 and debugging using GDB under Linux, Windows and macOS. Except for OS specific installation procedures, the s/w user interface and use procedures are the same across all supported operating systems.
Note: Screenshots presented in this document have been made for Eclipse Neon 3 running on Ubuntu 16.04 LTS. There may be some small differences in what a particular user interface looks like, depending on whether you are using Windows, macOS or Linux and / or a different release of Eclipse.

Espressif Systems

1785

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.20.2 How it Works?
The key software and hardware components that perform debugging of ESP32-S3 with OpenOCD over JTAG (Joint Test Action Group) interface is presented in the diagram below under the oDebugging With JTAGplabel. These components include xtensa-esp32s3-elf-gdb debugger, OpenOCD on chip debugger, and the JTAG adapter connected to ESP32-S3 target.

Fig. 36: JTAG debugging - overview diagram
Likewise, theoApplication Loading and Monitoringplabel indicates the key software and hardware components that allow an application to be compiled, built, and flashed to ESP32-S3, as well as to provide means to monitor diagnostic messages from ESP32-S3.
oDebugging With JTAGpand oApplication Loading and Monitoringpis integrated under the Eclipse IDE in order to provide a quick and easy transition between writing/compiling/loading/debugging code. The Eclipse IDE (and the integrated debugging software) is available for Windows, Linux and macOS platforms. Depending on user preferences, both the debugger and idf.py build can also be used directly from terminal/command line, instead of Eclipse.
The connection from PC to ESP32-S3 is done effectively with a single USB cable. This is made possible by the ESP32S3 chip itself, which provides two USB channels, one for JTAG and the other for the USB terminal connection. The USB cable should be connected to the D+/D- USB pins of ESP32-S3 and not to the serial RxD/TxD through a USB-to-UART chip. The proper connection is explained later in subsection Configuring ESP32-S3 Target.
4.20.3 Selecting JTAG Adapter
The quickest and most convenient way to start with JTAG debugging is through a USB cable connected to the D+/DUSB pins of ESP32-S3. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to ESP32S3.
If you decide to use separate JTAG adapter, look for one that is compatible with both the voltage levels on the ESP32-S3 as well as with the OpenOCD software. The JTAG port on the ESP32-S3 is an industry-standard JTAG port which lacks (and does not need) the TRST pin. The JTAG I/O pins all are powered from the VDD_3P3_RTC pin (which normally would be powered by a 3.3 V rail) so the JTAG adapter needs to be able to work with JTAG pins in that voltage range.
On the software side, OpenOCD supports a fair amount of JTAG adapters. See http://openocd.org/doc/html/ Debug-Adapter-Hardware.html for an (unfortunately slightly incomplete) list of the adapters OpenOCD works with.

Espressif Systems

1786

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
This page lists SWD-compatible adapters as well; take note that the ESP32-S3 does not support SWD. JTAG adapters that are hardcoded to a specific product line, e.g. ST-LINK debugging adapters for STM32 families, will not work. The minimal signalling to get a working JTAG connection are TDI, TDO, TCK, TMS and GND. Some JTAG debuggers also need a connection from the ESP32-S3 power line to a line called e.g. Vtar to set the working voltage. SRST can optionally be connected to the CH_PD of the ESP32-S3, although for now, support in OpenOCD for that line is pretty minimal. ESP-Prog is an example for using an external board for debugging by connecting it to the JTAG pins of ESP32-S3.
4.20.4 Setup of OpenOCD
If you have already set up ESP-IDF with CMake build system according to the Getting Started Guide, then OpenOCD is already installed. After setting up the environment in your terminal, you should be able to run OpenOCD. Check this by executing the following command: openocd --version
The output should be as follows (although the version may be more recent than listed here): Open On-Chip Debugger v0.10.0-esp32-20190708 (2019-07-08-11:04) Licensed under GNU GPL v2 For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
You may also verify that OpenOCD knows where its configuration scripts are located by printing the value of OPENOCD_SCRIPTS environment variable, by typing echo $OPENOCD_SCRIPTS (for Linux and macOS) or echo %OPENOCD_SCRIPTS% (for Windows). If a valid path is printed, then OpenOCD is set up correctly. If any of these steps do not work, please go back to the setting up the tools section of the Getting Started Guide.
Note: It is also possible to build OpenOCD from source. Please refer to Building OpenOCD from Sources section for details.
4.20.5 Configuring ESP32-S3 Target
Once OpenOCD is installed, you can proceed to configuring the ESP32-S3 target (i.e ESP32-S3 board with JTAG interface). Configuring the target is split into the following three steps:
· Configure and connect JTAG interface · Run OpenOCD · Upload application for debugging
Configure and connect JTAG interface
This step depends on the JTAG and ESP32-S3 board you are using (see the two cases described below).
Configure ESP32-S3 built-in JTAG Interface ESP32-S3 has a built-in JTAG circuitry and can be debugged without any additional chip. Only an USB cable connected to the D+/D- pins is necessary. The necessary connections are shown in the following section.

Espressif Systems

1787

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

ESP32-S3 Pin GPIO19 GPIO20 5V GND

Configure Hardware
Table 22: ESP32-S3 pins and USB signals USB Signal DD+ V_BUS Ground

Please verify that the ESP32-S3 pins used for USB communication are not connected to some other HW that may disturb the JTAG operation.

Configure USB Drivers JTAG communication should work on all supported platforms. Windows users might get LIBUSB_ERROR_NOT_FOUND errors. Please use version 2.8 (or newer) of the ESP-IDF Tools Installer and select the driver oEspressif - WinUSB support for JTAG (ESP32-C3/S3)pin order to resolve this issue. If you donnt want to re-run the installer then the same can be achieved with idf-env by running the following command from PowerShell:
Invoke-WebRequest 'https://dl.espressif.com/dl/idf-env/idf-env.exe' -OutFile .\idfenv.exe; .\idf-env.exe driver install --espressif

Configure Other JTAG Interface Refer to section Selecting JTAG Adapter for guidance what JTAG interface to select, so it is able to operate with OpenOCD and ESP32-S3. Then follow three configuration steps below to get it working.

Configure eFuses By default, ESP32-S3 JTAG interface is connected to the built-in USB_SERIAL_JTAG peripheral. To use an external JTAG adapter instead, you need to switch the JTAG interface to the GPIO pins. This can be done by burning eFuses using espefuse.py tool.
Burning eFuses is an irreversible operation, so consider both options below before starting the process.
· Burning DIS_USB_JTAG eFuse will permanently disable the connection between USB_SERIAL_JTAG and the JTAG port of the CPU. JTAG interface can then be connected to GPIO39-GPIO42. Note that USB CDC functionality of USB_SERIAL_JTAG will still be useable, i.e. flashing and monitoring over USB CDC will still work.
· Burning JTAG_SEL_ENABLE eFuse will enable selection of JTAG interface by a strapping pin, GPIO3. If the strapping pin is low when ESP32-S3 is reset, JTAG interface will use GPIO39-GPIO42. If the strapping pin is high, USB_SERIAL_JTAG will be used as the JTAG interface.

Configure Hardware
1. Identify all pins / signals on JTAG interface and ESP32-S3 board, that should be connected to establish communication.

ESP32-S3 Pin MTDO / GPIO40 MTDI / GPIO41 MTCK / GPIO39 MTMS / GPIO42

Table 23: ESP32-S3 pins and JTAG signals
JTAG Signal TDO TDI TCK TMS

2. Verify if ESP32-S3 pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation.
3. Connect identified pin / signals of ESP32-S3 and JTAG interface.

Espressif Systems

1788

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Configure Drivers You may need to install driver s/w to make JTAG work with computer. Refer to documentation of JTAG adapter, that should provide related details.
Connect Connect JTAG interface to the computer. Power on ESP32-S3 and JTAG interface boards. Check if JTAG interface is visible by computer.
To carry on with debugging environment setup, proceed to section Run OpenOCD.
Run OpenOCD
Once target is configured and connected to computer, you are ready to launch OpenOCD.
Open a terminal and set it up for using the ESP-IDF as described in the setting up the environment section of the Getting Started Guide. Then run OpenOCD (this command works on Windows, Linux, and macOS):
openocd -f board/esp32s3-builtin.cfg
Note: The files provided after -f above are specific for ESP32-S3. You may need to provide different files depending on the hardware that is used. For guidance see Configuration of OpenOCD for specific target.
For example, board/esp32c3-ftdi.cfg can be used for a custom board with an FT2232H or FT232H chip used for JTAG connection, or with ESP-Prog.
You should now see similar output (this log is for ESP32-S3):
user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32s3-builtin.cfg Open On-Chip Debugger v0.10.0-esp32-20210902 (2021-10-05-23:44) Licensed under GNU GPL v2 For bug reports, read
http://openocd.org/doc/doxygen/bugs.html debug_level: 2
Info : only one transport option; autoselect 'jtag' Warn : Transport "jtag" was already selected Info : Listening on port 6666 for tcl connections Info : Listening on port 4444 for telnet connections Info : esp_usb_jtag: Device found. Base speed 40000KHz, div range 1 to 255 Info : clock speed 40000 kHz Info : JTAG tap: esp32s3.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica),  part: 0x2003, ver: 0x1) Info : JTAG tap: esp32s3.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica),  part: 0x2003, ver: 0x1) Info : esp32s3.cpu0: Debug controller was reset. Info : esp32s3.cpu0: Core was reset. Info : esp32s3.cpu1: Debug controller was reset. Info : esp32s3.cpu1: Core was reset. Info : Listening on port 3333 for gdb connections
· If there is an error indicating permission problems, please see section on oPermissions delegationpin the OpenOCD README file located in the ~/esp/openocd-esp32 directory.
· In case there is an error in finding the configuration files, e.g. Can't find board/esp32s3-builtin. cfg, check if the OPENOCD_SCRIPTS environment variable is set correctly. This variable is used by OpenOCD to look for the files specified after the -f option. See Setup of OpenOCD section for details. Also check if the file is indeed under the provided path.
· If you see JTAG errors (e.g., ...all ones or ...all zeroes), please check your JTAG connections, whether other signals are connected to JTAG besides ESP32-S3ns pins, and see if everything is powered on correctly.

Espressif Systems

1789

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Upload application for debugging
Build and upload your application to ESP32-S3 as usual, see Step 8. Build the Project. Another option is to write application image to flash using OpenOCD via JTAG with commands like this:
openocd -f board/esp32s3-builtin.cfg -c "program_esp filename.bin 0x10000 verify exit"
OpenOCD flashing command program_esp has the following format: program_esp <image_file> <offset> [verify] [reset] [exit]
· image_file - Path to program image file. · offset - Offset in flash bank to write image. · verify - Optional. Verify flash contents after writing. · reset - Optional. Reset target after programing. · exit - Optional. Finally exit OpenOCD. You are now ready to start application debugging. Follow the steps described in the section below.
4.20.6 Launching Debugger
The toolchain for ESP32-S3 features GNU Debugger, in short GDB. It is available with other toolchain programs under filename: xtensa-esp32s3-elf-gdb. GDB can be called and operated directly from command line in a terminal. Another option is to call it from within IDE (like Eclipse, Visual Studio Code, etc.) and operate indirectly with help of GUI instead of typing commands in a terminal. Both options of using debugger are discussed under links below.
· Eclipse · Command Line It is recommended to first check if debugger works from Command Line and then move to using Eclipse.
4.20.7 Debugging Examples
This section is intended for users not familiar with GDB. It presents example debugging session from Eclipse using simple application available under get-started/blink and covers the following debugging actions:
1. Navigating through the code, call stack and threads 2. Setting and clearing breakpoints 3. Halting the target manually 4. Stepping through the code 5. Checking and setting memory 6. Watching and setting program variables 7. Setting conditional breakpoints Similar debugging actions are provided using GDB from Command Line. Before proceeding to examples, set up your ESP32-S3 target and load it with get-started/blink.
4.20.8 Building OpenOCD from Sources
Please refer to separate documents listed below, that describe build process.

Espressif Systems

1790

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Building OpenOCD from Sources for Windows
The following instructions are alternative to downloading binary OpenOCD from Espressif GitHub. To quickly setup the binary OpenOCD, instead of compiling it yourself, backup and proceed to section Setup of OpenOCD.
Note: Following instructions are assumed to be runned in MSYS2 environment with MINGW32 subsystem!
Install Dependencies Install packages that are required to compile OpenOCD:
pacman -S --noconfirm --needed autoconf automake git make \ mingw-w64-i686-gcc \ mingw-w64-i686-toolchain \ mingw-w64-i686-libtool \ mingw-w64-i686-pkg-config \ mingw-w64-cross-winpthreads-git \ p7zip
Download Sources of OpenOCD The sources for the ESP32-S3-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands:
cd ~/esp git clone --recursive https://github.com/espressif/openocd-esp32.git
The clone of sources should be now saved in ~/esp/openocd-esp32 directory.
Downloading libusb Build and export variables for a following OpenOCD compilation:
wget https://github.com/libusb/libusb/releases/download/v1.0.22/libusb-1.0.22.7z 7z x -olibusb ./libusb-1.0.22.7z export CPPFLAGS="$CPPFLAGS -I${PWD}/libusb/include/libusb-1.0" export LDFLAGS="$LDFLAGS -L${PWD}/libusb/MinGW32/.libs/dll"
Build OpenOCD Proceed with configuring and building OpenOCD:
cd ~/esp/openocd-esp32 export CPPFLAGS="$CPPFLAGS -D__USE_MINGW_ANSI_STDIO=1 -Wno-error"; export CFLAGS=" $CFLAGS -Wno-error" ./bootstrap ./configure --disable-doxygen-pdf --enable-ftdi --enable-jlink --enable-ulink -build=i686-w64-mingw32 --host=i686-w64-mingw32 make cp ../libusb/MinGW32/dll/libusb-1.0.dll ./src cp /opt/i686-w64-mingw32/bin/libwinpthread-1.dll ./src
Optionally you can add make install step at the end. Skip it, if you have an existing OpenOCD (from e.g. another development platform), as it may get overwritten. Also you could use export DESTDIR="/custom/ install/dir"; make install.
Note: · Should an error occur, resolve it and try again until the command make works. · If there is a submodule problem from OpenOCD, please cd to the openocd-esp32 directory and input git submodule update --init.

Espressif Systems

1791

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· If the ./configure is successfully run, information of enabled JTAG will be printed under OpenOCD configuration summary.
· If the information of your device is not shown in the log, use ./configure to enable it as described in ../openocd-esp32/doc/INSTALL.txt.
· For details concerning compiling OpenOCD, please refer to openocd-esp32/README.Windows. · Donnt forget to copy libusb-1.0.dll and libwinpthread-1.dll into OOCD_INSTALLDIR/bin from ~/esp/
openocd-esp32/src.
Once make process is successfully completed, the executable of OpenOCD will be saved in ~/esp/openocdesp32/src directory.
Full Listing A complete described previously process is provided below for the faster execution, e.g. as a shell script:
pacman -S --noconfirm --needed autoconf automake git make mingw-w64-i686-gcc mingww64-i686-toolchain mingw-w64-i686-libtool mingw-w64-i686-pkg-config mingw-w64cross-winpthreads-git p7zip cd ~/esp git clone --recursive https://github.com/espressif/openocd-esp32.git
wget https://github.com/libusb/libusb/releases/download/v1.0.22/libusb-1.0.22.7z 7z x -olibusb ./libusb-1.0.22.7z export CPPFLAGS="$CPPFLAGS -I${PWD}/libusb/include/libusb-1.0"; export LDFLAGS=" $LDFLAGS -L${PWD}/libusb/MinGW32/.libs/dll"
export CPPFLAGS="$CPPFLAGS -D__USE_MINGW_ANSI_STDIO=1 -Wno-error"; export CFLAGS=" $CFLAGS -Wno-error" cd ~/esp/openocd-esp32 ./bootstrap ./configure --disable-doxygen-pdf --enable-ftdi --enable-jlink --enable-ulink -build=i686-w64-mingw32 --host=i686-w64-mingw32 make cp ../libusb/MinGW32/dll/libusb-1.0.dll ./src cp /opt/i686-w64-mingw32/bin/libwinpthread-1.dll ./src
# # optional # export DESTDIR="$PWD" # make install # cp ./src/libusb-1.0.dll $DESTDIR/mingw32/bin # cp ./src/libwinpthread-1.dll $DESTDIR/mingw32/bin
Next Steps To carry on with debugging environment setup, proceed to section Configuring ESP32-S3 Target.
Building OpenOCD from Sources for Linux
The following instructions are alternative to downloading binary OpenOCD from Espressif GitHub. To quickly setup the binary OpenOCD, instead of compiling it yourself, backup and proceed to section Setup of OpenOCD.
Download Sources of OpenOCD The sources for the ESP32-S3-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands:
cd ~/esp git clone --recursive https://github.com/espressif/openocd-esp32.git
The clone of sources should be now saved in ~/esp/openocd-esp32 directory.

Espressif Systems

1792

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Install Dependencies Install packages that are required to compile OpenOCD.
Note: Install the following packages one by one, check if installation was successful and then proceed to the next package. Resolve reported problems before moving to the next step.
sudo apt-get install make sudo apt-get install libtool sudo apt-get install pkg-config sudo apt-get install autoconf sudo apt-get install automake sudo apt-get install texinfo sudo apt-get install libusb-1.0
Note: · Version of pkg-config should be 0.2.3 or above. · Version of autoconf should be 2.6.4 or above. · Version of automake should be 1.9 or above. · When using USB-Blaster, ASIX Presto, OpenJTAG and FT2232 as adapters, drivers libFTDI and FTD2XX need to be downloaded and installed. · When using CMSIS-DAP, HIDAPI is needed.
Build OpenOCD Proceed with configuring and building OpenOCD:
cd ~/esp/openocd-esp32 ./bootstrap ./configure make
Optionally you can add sudo make install step at the end. Skip it, if you have an existing OpenOCD (from e.g. another development platform), as it may get overwritten.
Note: · Should an error occur, resolve it and try again until the command make works. · If there is a submodule problem from OpenOCD, please cd to the openocd-esp32 directory and input git submodule update --init. · If the ./configure is successfully run, information of enabled JTAG will be printed under OpenOCD configuration summary. · If the information of your device is not shown in the log, use ./configure to enable it as described in ../openocd-esp32/doc/INSTALL.txt. · For details concerning compiling OpenOCD, please refer to openocd-esp32/README.
Once make process is successfully completed, the executable of OpenOCD will be saved in ~/openocd-esp32/ bin directory.
Next Steps To carry on with debugging environment setup, proceed to section Configuring ESP32-S3 Target.
Building OpenOCD from Sources for MacOS
The following instructions are alternative to downloading binary OpenOCD from Espressif GitHub. To quickly setup the binary OpenOCD, instead of compiling it yourself, backup and proceed to section Setup of OpenOCD.

Espressif Systems

1793

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Download Sources of OpenOCD The sources for the ESP32-S3-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands:
cd ~/esp git clone --recursive https://github.com/espressif/openocd-esp32.git
The clone of sources should be now saved in ~/esp/openocd-esp32 directory.
Install Dependencies Install packages that are required to compile OpenOCD using Homebrew:
brew install automake libtool libusb wget [email protected] pkg-config
Build OpenOCD Proceed with configuring and building OpenOCD:
cd ~/esp/openocd-esp32 ./bootstrap ./configure make
Optionally you can add sudo make install step at the end. Skip it, if you have an existing OpenOCD (from e.g. another development platform), as it may get overwritten.
Note: · Should an error occur, resolve it and try again until the command make works. · If there is a submodule problem from OpenOCD, please cd to the openocd-esp32 directory and input git submodule update --init. · If the ./configure is successfully run, information of enabled JTAG will be printed under OpenOCD configuration summary. · If the information of your device is not shown in the log, use ./configure to enable it as described in ../openocd-esp32/doc/INSTALL.txt. · For details concerning compiling OpenOCD, please refer to openocd-esp32/README.OSX.
Once make process is successfully completed, the executable of OpenOCD will be saved in ~/esp/openocdesp32/src/openocd directory.
Next Steps To carry on with debugging environment setup, proceed to section Configuring ESP32-S3 Target. The examples of invoking OpenOCD in this document assume using pre-built binary distribution described in section Setup of OpenOCD. To use binaries build locally from sources, change the path to OpenOCD executable to src/openocd and set the OPENOCD_SCRIPTS environment variable so that OpenOCD can find the configuration files. For Linux and macOS:
cd ~/esp/openocd-esp32 export OPENOCD_SCRIPTS=$PWD/tcl
For Windows:
cd %USERPROFILE%\esp\openocd-esp32 set "OPENOCD_SCRIPTS=%CD%\tcl"
Example of invoking OpenOCD build locally from sources, for Linux and macOS:
src/openocd -f board/esp32s3-builtin.cfg

Espressif Systems

1794

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
and Windows:
src\openocd -f board/esp32s3-builtin.cfg
4.20.9 Tips and Quirks
This section provides collection of links to all tips and quirks referred to from various parts of this guide.
Tips and Quirks
This section provides collection of all tips and quirks referred to from various parts of this guide.
Breakpoints and watchpoints available ESP32-S3 debugger supports 2 hardware implemented breakpoints and 64 software ones. Hardware breakpoints are implemented by ESP32-S3 chipns logic and can be set anywhere in the code: either in flash or IRAM programns regions. Additionally there are 2 types of software breakpoints implemented by OpenOCD: flash (up to 32) and IRAM (up to 32) breakpoints. Currently GDB can not set software breakpoints in flash. So until this limitation is removed those breakpoints have to be emulated by OpenOCD as hardware ones (see below for details). ESP32-S3 also supports two watchpoints, so two variables can be watched for change or read by the GDB command watch myVariable. Note that menuconfig option CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK uses the 2nd watchpoint and will not provide expected results, if you also try to use it within OpenOCD / GDB. See menuconfigns help for detailed description.
What else should I know about breakpoints? Emulating part of hardware breakpoints using software flash ones means that the GDB command hb myFunction which is invoked for function in flash will use pure hardware breakpoint if it is avalable otherwise one of the 32 software flash breakpoints is used. The same rule applies to b myFunction-like commands. In this case GDB will decide what type of breakpoint to set itself. If myFunction is resided in writable region (IRAM) software IRAM breakpoint will be used otherwise hardware or software flash breakpoint is used as it is done for hb command.
Flash Mappings vs SW Flash Breakpoints In order to set/clear software breakpoints in flash, OpenOCD needs to know their flash addresses. To accomplish conversion from the ESP32-S3 address space to the flash one, OpenOCD uses mappings of programns code regions resided in flash. Those mappings are kept in the image header which is prepended to program binary data (code and data segments) and is specific to every application image written to the flash. So to support software flash breakpoints OpenOCD should know where application image under debugging is resided in the flash. By default OpenOCD reads partition table at 0x8000 and uses mappings from the first found application image, but there can be the cases when it will not work, e.g. partition table is not at standard flash location or even there can be multiple images: one factory and two OTA and you may want to debbug any of them. To cover all possible debugging scenarios OpenOCD supports special command which can be used to set arbitrary location of application image to debug. The command has the following format: esp appimage_offset <offset> Offset should be in hex format. To reset to the default behaviour you can specify -1 as offset.
Note: Since GDB requests memory map from OpenOCD only once when connecting to it, this command should be specified in one of the TCL configuration files, or passed to OpenOCD via its command line. In the latter case command line should look like below:
openocd -f board/esp32s3-builtin.cfg -c "init; halt; esp appimage_offset 0x210000"
Another option is to execute that command via OpenOCD telnet session and then connect GDB, but it seems to be less handy.

Espressif Systems

1795

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Why stepping with onextpdoes not bypass subroutine calls? When stepping through the code with next command, GDB is internally setting a breakpoint (one out of two available) ahead in the code to bypass the subroutine calls. This functionality will not work, if the two available breakpoints are already set elsewhere in the code. If this is the case, delete breakpoints to have one osparep. With both breakpoints already used, stepping through the code with next command will work as like with step command and debugger will step inside subroutine calls.
Support options for OpenOCD at compile time ESP-IDF has some support options for OpenOCD debugging which can be set at compile time:
· CONFIG_ESP32S3_DEBUG_OCDAWARE is enabled by default. If a panic or unhandled exception is thrown and a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger.
· CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK (disabled by default) sets watchpoint index 1 (the second of two) at the end of any task stack. This is the most accurate way to debug task stack overflows. Click the link for more details.
Please see the project configuration menu menu for more details on setting compile-time options.
FreeRTOS support OpenOCD has explicit support for the ESP-IDF FreeRTOS. GDB can see FreeRTOS tasks as threads. Viewing them all can be done using the GDB i threads command, changing to a certain task is done with thread n, with n being the number of the thread. FreeRTOS detection can be disabled in targetns configuration. For more details see Configuration of OpenOCD for specific target.
Optimize JTAG speed In order to achieve higher data rates and minimize number of dropped packets it is recommended to optimize setting of JTAG clock frequency, so it is at maximum and still provides stable operation of JTAG. To do so use the following tips.
1. The upper limit of JTAG clock frequency is 20 MHz if CPU runs at 80 MHz, or 26 MHz if CPU runs at 160 MHz or 240 MHz.
2. Depending on particular JTAG adapter and the length of connecting cables, you may need to reduce JTAG frequency below 20 / 26 MHz.
3. In particular reduce frequency, if you get DSR/DIR errors (and they do not relate to OpenOCD trying to read from a memory range without physical memory being present there).
4. ESP-WROVER-KIT operates stable at 20 / 26 MHz.
What is the meaning of debuggerns startup commands? On startup, debugger is issuing sequence of commands to reset the chip and halt it at specific line of code. This sequence (shown below) is user defined to pick up at most convenient / appropriate line and start debugging.
· set remote hardware-watchpoint-limit 2 iRestrict GDB to using two hardware watchpoints supported by the chip, 2 for ESP32-S3. For more information see https://sourceware.org/gdb/onlinedocs/gdb/ Remote-Configuration.html.
· mon reset halt ireset the chip and keep the CPUs halted · flushregs imonitor (mon) command can not inform GDB that the target state has changed. GDB will
assume that whatever stack the target had before mon reset halt will still be valid. In fact, after reset the target state will change, and executing flushregs is a way to force GDB to get new state from the target. · thb app_main iinsert a temporary hardware breakpoint at app_main, put here another function name if required · c iresume the program. It will then stop at breakpoint inserted at app_main.
Configuration of OpenOCD for specific target There are several kinds of OpenOCD configuration files (*. cfg). All configuration files are located in subdirectories of share/openocd/scripts directory of OpenOCD distribution (or tcl/scripts directory of the source repository). For the purposes of this guide, the most important ones are board, interface and target.
· interface configuration files describe the JTAG adapter. Examples of JTAG adapters are ESP-Prog and J-Link.
· target configuration files describe specific chips, or in some cases, modules.

Espressif Systems

1796

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

· board configuration files are provided for development boards with a built-in JTAG adapter. Such files include an interface configuration file to choose the adapter, and target configuration file to choose the chip/module.
The following configuration files are available for ESP32-S3:

Name board/esp32s3builtin.cfg board/esp32s3ftdi.cfg target/esp32s3. cfg interface/ftdi/ esp_usb_jtag.cfg interface/ftdi/ esp32_devkitj_v1. cfg

Table 24: OpenOCD configuration files for ESP32-S3 Description Board configuration file for ESP32-S3 for debugging via builtin USB JTAG, includes target and adapter configuration. Board configuration file for ESP32-S3 for via externally connected FTDI-based probe like ESP-Prog, includes target and adapter configuration. ESP32-S3 target configuration file. Can be used together with one of the interface/ configuration files. JTAG adapter configuration file for ESP32-S3 builtin USB JTAG.
JTAG adapter configuration file for ESP-Prog debug adapter board.

If you are using one of the boards which have a pre-defined configuration file, you only need to pass one -f argument to OpenOCD, specifying that file.
If you are using a board not listed here, you need to specify both the interface configuration file and target configuration file.

Custom configuration files OpenOCD configuration files are written in TCL, and include a variety of choices for customization and scripting. This can be useful for non-standard debugging situations. Please refer to OpenOCD Manual for the TCL scripting reference.

OpenOCD configuration variables The following variables can be optionally set before including the ESP-specific target configuration file. This can be done either in a custom configuration file, or from the command line. The syntax for setting a variable in TCL is:
set VARIABLE_NAME value

To set a variable from the command line (replace the name of .cfg file with the correct file for your board): openocd -c 'set VARIABLE_NAME value' -f board/esp-xxxxx-kit.cfg

It is important to set the variable before including the ESP-specific configuration file, otherwise the variable will not have effect. You can set multiple variables by repeating the -c option.

Table 25: Common ESP-related OpenOCD variables

Variable

Description

ESP_RTOS

Set to none to disable RTOS support. In this case, thread list will not be available

in GDB. Can be useful when debugging FreeRTOS itself, and stepping through the

scheduler code.

ESP_FLASH_SIZE

Set to 0 to disable Flash breakpoints support.

ESP_SEMIHOST_BASEDISRet to the path (on the host) which will be the default directory for semihosting func-

tions.

How debugger resets ESP32-S3? The board can be reset by entering mon reset or mon reset halt into GDB.

Espressif Systems

1797

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Do not use JTAG pins for something else Operation of JTAG may be disturbed, if some other h/w is connected to JTAG pins besides ESP32-S3 module and JTAG adapter. ESP32-S3 JTAG is using the following pins:

ESP32-S3 Pin MTDO / GPIO40 MTDI / GPIO41 MTCK / GPIO39 MTMS / GPIO42

Table 26: ESP32-S3 pins and JTAG signals
JTAG Signal TDO TDI TCK TMS

JTAG communication will likely fail, if configuration of JTAG pins is changed by user application. If OpenOCD initializes correctly (detects the two Tensilica cores), but loses sync and spews out a lot of DTR/DIR errors when the program is ran, it is likely that the application reconfigures the JTAG pins to something else, or the user forgot to connect Vtar to a JTAG adapter that needed it.
Below is an excerpt from series of errors reported by GDB after the application stepped into the code that reconfigured MTDO pin to be an input:
cpu0: xtensa_resume (line 431): DSR (FFFFFFFF) indicates target still busy! cpu0: xtensa_resume (line 431): DSR (FFFFFFFF) indicates DIR instruction generated an exception! cpu0: xtensa_resume (line 431): DSR (FFFFFFFF) indicates DIR instruction generated an overrun! cpu1: xtensa_resume (line 431): DSR (FFFFFFFF) indicates target still busy! cpu1: xtensa_resume (line 431): DSR (FFFFFFFF) indicates DIR instruction generated an exception! cpu1: xtensa_resume (line 431): DSR (FFFFFFFF) indicates DIR instruction generated an overrun!

JTAG with Flash Encryption or Secure Boot By default, enabling Flash Encryption and/or Secure Boot will disable JTAG debugging. On first boot, the bootloader will burn an eFuse bit to permanently disable JTAG at the same time it enables the other features.
The project configuration option CONFIG_SECURE_BOOT_ALLOW_JTAG will keep JTAG enabled at this time, removing all physical security but allowing debugging. (Although the name suggests Secure Boot, this option can be applied even when only Flash Encryption is enabled).
However, OpenOCD may attempt to automatically read and write the flash in order to set software breakpoints. This has two problems:
· Software breakpoints are incompatible with Flash Encryption, OpenOCD currently has no support for encrypting or decrypting flash contents.
· If Secure Boot is enabled, setting a software breakpoint will change the digest of a signed app and make the signature invalid. This means if a software breakpoint is set and then a reset occurs, the signature verification will fail on boot.
To disable software breakpoints while using JTAG, add an extra argument -c 'set ESP_FLASH_SIZE 0' to the start of the OpenOCD command line, see OpenOCD configuration variables.
Note: For the same reason, the ESP-IDF app may fail bootloader verification of app signatures, when this option is enabled and a software breakpoint is set.

Reporting issues with OpenOCD / GDB In case you encounter a problem with OpenOCD or GDB programs itself and do not find a solution searching available resources on the web, open an issue in the OpenOCD issue tracker under https://github.com/espressif/openocd-esp32/issues.
1. In issue report provide details of your configuration: a. JTAG adapter type, and the chip/module being debugged.

Espressif Systems

1798

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

b. Release of ESP-IDF used to compile and load application that is being debugged. c. Details of OS used for debugging. d. Is OS running natively on a PC or on a virtual machine? 2. Create a simple example that is representative to observed issue. Describe steps how to reproduce it. In such an example debugging should not be affected by non-deterministic behaviour introduced by the Wi-Fi stack, so problems will likely be easier to reproduce, if encountered once.
3. Prepare logs from debugging session by adding additional parameters to start up commands. OpenOCD:
openocd -l openocd_log.txt -d3 -f board/esp32s3-builtin.cfg
Logging to a file this way will prevent information displayed on the terminal. This may be a good thing taken amount of information provided, when increased debug level -d3 is set. If you still like to see the log on the screen, then use another command instead:
openocd -d3 -f board/esp32s3-builtin.cfg 2>&1 | tee openocd.log
Debugger:
xtensa-esp32s3-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
Optionally add command remotelogfile gdb_log.txt to the gdbinit file. 4. Attach both openocd_log.txt and gdb_log.txt files to your issue report.

4.20.10 Related Documents
Using Debugger
This section covers configuration and running debugger using several methods: · from Eclipse · from Command Line · using idf.py debug targets

Eclipse Note: It is recommended to first check if debugger works using idf.py debug targets or from Command Line and then move to using Eclipse.
Debugging functionality is provided out of box in standard Eclipse installation. Another option is to use pluggins like oGDB Hardware Debuggingpplugin. We have found this plugin quite convenient and decided to use throughout this
guide.
To begin with, install oGDB Hardware Debuggingpplugin by opening Eclipse and going to Help > Install New Software.
Once installation is complete, configure debugging session following steps below. Please note that some of configuration parameters are generic and some are project specific. This will be shown below by configuring debugging for oblinkpexample project. If not done already, add this project to Eclipse workspace following guidance in section Build and Flash with Eclipse IDE. The source of get-started/blink application is available in examples directory of ESP-IDF repository.
1. In Eclipse go to Run > Debug Configuration. A new window will open. In the windowns left pane double click oGDB Hardware Debuggingp(or select oGDB Hardware Debuggingpand press the oNewpbutton) to create a new configuration.
2. In a form that will show up on the right, enter the oName:pof this configuration, e.g. oBlink checkingp. 3. On the oMainptab below, under oProject:p, press oBrowsepbutton and select the oblinkpproject. 4. In next line oC/C++ Application:ppress oBrowsepbutton and select oblink.elfpfile. If oblink.elfpis
not there, then likely this project has not been build yet. See Build and Flash with Eclipse IDE how to do it. 5. Finally, under oBuild (if required) before launchingpclick oDisable auto buildp.
A sample window with settings entered in points 1 - 5 is shown below.

Espressif Systems

1799

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 37: Configuration of GDB Hardware Debugging - Main tab

Espressif Systems

1800

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
6. ClickoDebuggerptab. In fieldoGDB Commandpenter xtensa-esp32s3-elf-gdb to invoke debugger. 7. Change default configuration of oRemote hostpby entering 3333 under the oPort numberp.
Configuration entered in points 6 and 7 is shown on the following picture.

Fig. 38: Configuration of GDB Hardware Debugging - Debugger tab
8. The last tab to that requires changing of default configuration isoStartupp. UnderoInitialization Commandsp uncheck oReset and Delay (seconds)pand oHaltpp. Then, in entry field below, enter the following lines:
mon reset halt flushregs set remote hardware-watchpoint-limit 2
Note: If you want to update image in the flash automatically before starting new debug session add the following lines of commands at the beginning of oInitialization Commandsptextbox:
mon reset halt mon program_esp ${workspace_loc:blink/build/blink.bin} 0x10000 verify
For description of program_esp command see Upload application for debugging. 9. Under oLoad Image and Symbolspuncheck oLoad imagepoption. 10. Further down on the same tab, establish an initial breakpoint to halt CPUs after they are reset by debugger. The
plugin will set this breakpoint at the beginning of the function entered underoSet break point at:p. Checkout this option and enter app_main in provided field. 11. Checkout oResumepoption. This will make the program to resume after mon reset halt is invoked per point 8. The program will then stop at breakpoint inserted at app_main. Configuration described in points 8 - 11 is shown below. If the oStartuppsequence looks convoluted and respective oInitialization Commandspare not clear to you, check What is the meaning of debuggerns startup commands? for additional explanation.

Espressif Systems

1801

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 39: Configuration of GDB Hardware Debugging - Startup tab

Espressif Systems

1802

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
12. If you previously completed Configuring ESP32-S3 Target steps described above, so the target is running and ready to talk to debugger, go right to debugging by pressing oDebugpbutton. Otherwise press oApplypto save changes, go back to Configuring ESP32-S3 Target and return here to start debugging.
Once all 1 - 12 configuration steps are satisfied, the new Eclipse perspective called oDebugpwill open as shown on example picture below.

Fig. 40: Debug Perspective in Eclipse If you are not quite sure how to use GDB, check Eclipse example debugging session in section Debugging Examples.

Command Line
1. Begin with completing steps described under Configuring ESP32-S3 Target. This is prerequisite to start a debugging session.
2. Open a new terminal session and go to directory that contains project for debugging, e.g.
cd ~/esp/blink
3. When launching a debugger, you will need to provide couple of configuration parameters and commands. Instead of entering them one by one in command line, create a configuration file and name it gdbinit:
target remote :3333 set remote hardware-watchpoint-limit 2 mon reset halt flushregs thb app_main c
Save this file in current directory. For more details whatns inside gdbinit file, see What is the meaning of debuggerns startup commands?

Espressif Systems

1803

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

4. Now you are ready to launch GDB. Type the following in terminal: xtensa-esp32s3-elf-gdb -x gdbinit build/blink.elf

5. If previous steps have been done correctly, you will see a similar log concluded with (gdb) prompt:

user-name@computer-name:~/esp/blink$ xtensa-esp32s3-elf-gdb -x gdbinit build/

blink.elf

GNU gdb (crosstool-NG crosstool-ng-1.22.0-61-gab8375a) 7.10

Copyright (C) 2015 Free Software Foundation, Inc.

License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>

This is free software: you are free to change and redistribute it.

There is NO WARRANTY, to the extent permitted by law. Type "show copying"

and "show warranty" for details.

This GDB was configured as "--host=x86_64-build_pc-linux-gnu --target=xtensa-

esp32s3-elf".

Type "show configuration" for configuration details.

For bug reporting instructions, please see:

<http://www.gnu.org/software/gdb/bugs/>.

Find the GDB manual and other documentation resources online at:

<http://www.gnu.org/software/gdb/documentation/>.

For help, type "help".

Type "apropos word" to search for commands related to "word"...

Reading symbols from build/blink.elf...done.

0x400d10d8 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/

components/esp32s3/./freertos_hooks.c:52

52

asm("waiti 0");

JTAG tap: esp32s3.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica),

part: 0x2003, ver: 0x1)

JTAG tap: esp32s3.slave tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica),

part: 0x2003, ver: 0x1)

esp32s3: Debug controller was reset (pwrstat=0x5F, after clear 0x0F).

esp32s3: Core was reset (pwrstat=0x5F, after clear 0x0F).

Target halted. PRO_CPU: PC=0x5000004B (active) APP_CPU: PC=0x00000000

esp32s3: target state: halted

esp32s3: Core was reset (pwrstat=0x1F, after clear 0x0F).

Target halted. PRO_CPU: PC=0x40000400 (active) APP_CPU: PC=0x40000400

esp32s3: target state: halted

Hardware assisted breakpoint 1 at 0x400db717: file /home/user-name/esp/blink/

main/./blink.c, line 43.

0x0: 0x00000000

Target halted. PRO_CPU: PC=0x400DB717 (active) APP_CPU: PC=0x400D10D8

[New Thread 1073428656]

[New Thread 1073413708]

[New Thread 1073431316]

[New Thread 1073410672]

[New Thread 1073408876]

[New Thread 1073432196]

[New Thread 1073411552]

[Switching to Thread 1073411996]

Temporary breakpoint 1, app_main () at /home/user-name/esp/blink/main/./blink.

c:43

43

xTaskCreate(&blink_task, "blink_task", 512, NULL, 5, NULL);

(gdb)

Note the third line from bottom that shows debugger halting at breakpoint established in gdbinit file at function app_main(). Since the processor is halted, the LED should not be blinking. If this is what you see as well, you are ready to start debugging.
If you are not quite sure how to use GDB, check Command Line example debugging session in section Debugging Examples.

Espressif Systems

1804

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

idf.py debug targets It is also possible to execute the described debugging tools conveniently from idf.py. These commands are supported:
1. idf.py openocd Runs OpenOCD in a console with configuration defined in the environment or via command line. It uses default script directory defined as OPENOCD_SCRIPTS environmental variable, which is automatically added from an Export script (export.sh or export.bat). It is possible to override the script location using command line argument --openocd-scripts. As for the JTAG configuration of the current board, please use the environmental variable OPENOCD_COMMANDS or --openocd-commands command line argument. If none of the above is defined, OpenOCD is started with -f board/esp32s3-builtin.cfg board definition.
2. idf.py gdb Starts the gdb the same way as the Command Line, but generates the initial gdb scripts referring to the current project elf file.
3. idf.py gdbtui The same as 2, but starts the gdb with tui argument allowing very simple source code view.
4. idf.py gdbgui Starts gdbgui debugger frontend enabling out-of-the-box debugging in a browser window. Please run the install script with the oenable-gdbguipargument in order to make this option supported, e.g. install.sh -enable-gdbgui. It is possible to combine these debugging actions on a single command line allowing convenient setup of blocking and non-blocking actions in one step. idf.py implements a simple logic to move the background actions (such as openocd) to the beginning and the interactive ones (such as gdb, monitor) to the end of the action list. An example of a very useful combination is:
idf.py openocd gdbgui monitor
The above command runs OpenOCD in the background, starts gdbgui to open a browser window with active debugger frontend and opens a serial monitor in the active console.
Debugging Examples
This section describes debugging with GDB from Eclipse as well as from Command Line.
Eclipse Verify if your target is ready and loaded with get-started/blink example. Configure and start debugger following steps in section Eclipse. Pick up where target was left by debugger, i.e. having the application halted at breakpoint established at app_main().
Examples in this section
1. Navigating through the code, call stack and threads 2. Setting and clearing breakpoints 3. Halting the target manually 4. Stepping through the code 5. Checking and setting memory 6. Watching and setting program variables 7. Setting conditional breakpoints
Navigating through the code, call stack and threads When the target is halted, debugger shows the list of threads in oDebugpwindow. The line of code where program halted is highlighted in another window below, as shown on the following picture. The LED stops blinking.
Specific thread where the program halted is expanded showing the call stack. It represents function calls that lead up to the highlighted line of code, where the target halted. The first line of call stack under Thread #1 contains the last called function app_main(), that in turn was called from function main_task() shown in a line below. Each line of the stack also contains the file name and line number where the function was called. By clicking / highlighting the stack entries, in window below, you will see contents of this file.

Espressif Systems

1805

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 41: Debug Perspective in Eclipse

Espressif Systems

1806

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 42: Target halted during debugging

Espressif Systems

1807

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
By expanding threads you can navigate throughout the application. Expand Thread #5 that contains much longer call stack. You will see there, besides function calls, numbers like 0x4000000c. They represent addresses of binary code not provided in source form.

Fig. 43: Navigate through the call stack
In another window on right, you can see the disassembled machine code no matter if your project provides it in source or only the binary form.
Go back to the app_main() in Thread #1 to familiar code of blink.c file that will be examined in more details in the following examples. Debugger makes it easy to navigate through the code of entire application. This comes handy when stepping through the code and working with breakpoints and will be discussed below.

Setting and clearing breakpoints When debugging, we would like to be able to stop the application at critical lines of code and then examine the state of specific variables, memory and registers / peripherals. To do so we are using breakpoints. They provide a convenient way to quickly get to and halt the application at specific line.
Letns establish two breakpoints when the state of LED changes. Basing on code listing above, this happens at lines 33 and 36. To do so, hold the oControlpon the keyboard and double clink on number 33 in file blink.c file. A dialog will open where you can confirm your selection by pressingoOKpbutton. If you do not like to see the dialog just double click the line number. Set another breakpoint in line 36.
Information how many breakpoints are set and where is shown in windowoBreakpointspon top right. ClickoShow Breakpoints Supported by Selected Targetpto refresh this list. Besides the two just set breakpoints the list may contain temporary breakpoint at function app_main() established at debugger start. As maximum two breakpoints are allowed (see Breakpoints and watchpoints available), you need to delete it, or debugging will fail.
If you now click oResumep(click blink_task() under oTread #8p, if oResumepbutton is grayed out), the processor will run and halt at a breakpoint. Clicking oResumepanother time will make it run again, halt on second breakpoint, and so on.

Espressif Systems

1808

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 44: Setting a breakpoint

Espressif Systems

1809

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 45: Three breakpoints are set / maximum two are allowed

Espressif Systems

1810

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
You will be also able to see that LED is changing the state after each click to oResumepprogram execution. Read more about breakpoints under Breakpoints and watchpoints available and What else should I know about breakpoints?
Halting the target manually When debugging, you may resume application and enter code waiting for some event or staying in infinite loop without any break points defined. In such case, to go back to debugging mode, you can break program execution manually by pressing oSuspendpbutton. To check it, delete all breakpoints and click oResumep. Then click oSuspendp. Application will be halted at some random point and LED will stop blinking. Debugger will expand tread and highlight the line of code where application halted.

Fig. 46: Target halted manually
In particular case above, the application has been halted in line 52 of code in file freertos_hooks.c Now you can resume it again by pressing oResumepbutton or do some debugging as discussed below.

Stepping through the code It is also possible to step through the code using oStep Into (F5)pand oStep Over (F6)pcommands. The difference is that oStep Into (F5)pis entering inside subroutines calls, while oStep Over (F6)psteps over the call, treating it as a single source line.
Before being able to demonstrate this functionality, using information discussed in previous paragraph, make sure that you have only one breakpoint defined at line 36 of blink.c.
Resume program by entering pressing F8 and let it halt. Now press oStep Over (F6)p, one by one couple of times, to see how debugger is stepping one program line at a time.
If you press oStep Into (F5)pinstead, then debugger will step inside subroutine calls.
In this particular case debugger stepped inside gpio_set_level(BLINK_GPIO, 0) and effectively moved to gpio.c driver code.

Espressif Systems

1811

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 47: Stepping through the code with oStep Over (F6)p

Espressif Systems

1812

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 48: Stepping through the code with oStep Into (F5)p

Espressif Systems

1813

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
See Why stepping with onextpdoes not bypass subroutine calls? for potential limitation of using next command.
Checking and setting memory To display or set contents of memory useoMemoryptab at the bottom ofoDebugp perspective. With the oMemoryptab, we will read from and write to the memory location 0x3FF44004 labeled as GPIO_OUT_REG used to set and clear individual GPIOns. For more information, see ESP32-S3 Technical Reference Manual > IO MUX and GPIO Matrix (GPIO, IO_MUX) [PDF]. Being in the same blink.c project as before, set two breakpoints right after gpio_set_level instruction. Click oMemoryptab and then oAdd Memory Monitorpbutton. Enter 0x3FF44004 in provided dialog. Now resume program by pressing F8 and observe oMonitorptab.

Fig. 49: Observing memory location 0x3FF44004 changing one bit to oONp
You should see one bit being flipped over at memory location 0x3FF44004 (and LED changing the state) each time F8 is pressed.

Fig. 50: Observing memory location 0x3FF44004 changing one bit to oOFFp
To set memory use the sameoMonitorptab and the same memory location. Type in alternate bit pattern as previously observed. Immediately after pressing enter you will see LED changing the state.
Watching and setting program variables A common debugging tasks is checking the value of a program variable as the program runs. To be able to demonstrate this functionality, update file blink.c by adding a declaration of

Espressif Systems

1814

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
a global variable int i above definition of function blink_task. Then add i++ inside while(1) of this function to get i incremented on each blink. Exit debugger, so it is not confused with new code, build and flash the code to the ESP and restart debugger. There is no need to restart OpenOCD. Once application is halted, enter a breakpoint in the line where you put i++. In next step, in the window with oBreakpointsp, click the oExpressionsptab. If this tab is not visible, then add it by going to the top menu Window > Show View > Expressions. Then click oAdd new expressionpand enter i. Resume program execution by pressing F8. Each time the program is halted you will see i value being incremented.

Fig. 51: Watching program variable oip
To modify i enter a new number in oValuepcolumn. After pressing oResume (F8)pthe program will keep incrementing i starting from the new entered number.
Setting conditional breakpoints Here comes more interesting part. You may set a breakpoint to halt the program execution, if certain condition is satisfied. Right click on the breakpoint to open a context menu and selecot Breakpoint Propertiesp. Change the selection under oType:pto oHardwarepand enter a oCondition:plike i == 2. If current value of i is less than 2 (change it if required) and program is resumed, it will blink LED in a loop until condition i == 2 gets true and then finally halt.
Command Line Verify if your target is ready and loaded with get-started/blink example. Configure and start debugger following steps in section Command Line. Pick up where target was left by debugger, i.e. having the application halted at breakpoint established at app_main():

Espressif Systems

1815

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 52: Setting a conditional breakpoint

Espressif Systems

1816

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Temporary breakpoint 1, app_main () at /home/user-name/esp/blink/main/./blink.c:43

43

xTaskCreate(&blink_task, "blink_task", configMINIMAL_STACK_SIZE, NULL, 5,

NULL);

(gdb)

Examples in this section
1. Navigating through the code, call stack and threads 2. Setting and clearing breakpoints 3. Halting and resuming the application 4. Stepping through the code 5. Checking and setting memory 6. Watching and setting program variables 7. Setting conditional breakpoints

Navigating through the code, call stack and threads When you see the (gdb) prompt, the application is halted. LED should not be blinking.
To find out where exactly the code is halted, enter l or list, and debugger will show couple of lines of code around the halt point (line 43 of code in file blink.c)

(gdb) l

38

}

39 }

40

41 void app_main()

42 {

43

xTaskCreate(&blink_task, "blink_task", configMINIMAL_STACK_SIZE, NULL, 5,

NULL);

44 }

(gdb)

Check how code listing works by entering, e.g. l 30, 40 to see particular range of lines of code.
You can use bt or backtrace to see what function calls lead up to this code:
(gdb) bt #0 app_main () at /home/user-name/esp/blink/main/./blink.c:43 #1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/ esp32s3/./cpu_start.c:339 (gdb)

Line #0 of output provides the last function call before the application halted, i.e. app_main () we have listed previously. The app_main () was in turn called by function main_task from line 339 of code located in file cpu_start.c.
To get to the context of main_task in file cpu_start.c, enter frame N, where N = 1, because the main_task is listed under #1):

(gdb) frame 1

#1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/

esp32s3/./cpu_start.c:339

339

app_main();

(gdb)

Enter l and this will reveal the piece of code that called app_main() (in line 339):

(gdb) l

334

;

335

}

(continues on next page)

Espressif Systems

1817

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

(continued from previous page)

336 #endif

337

//Enable allocation in region where the startup stacks were located.

338

heap_caps_enable_nonos_stack_heaps();

339

app_main();

340

vTaskDelete(NULL);

341 }

342

(gdb)

By listing some lines before, you will see the function name main_task we have been looking for:

(gdb) l 326, 341

326 static void main_task(void* args)

327 {

328

// Now that the application is about to start, disable boot watchdogs

329

REG_CLR_BIT(TIMG_WDTCONFIG0_REG(0), TIMG_WDT_FLASHBOOT_MOD_EN_S);

330

REG_CLR_BIT(RTC_CNTL_WDTCONFIG0_REG, RTC_CNTL_WDT_FLASHBOOT_MOD_EN);

331 #if !CONFIG_FREERTOS_UNICORE

332

// Wait for FreeRTOS initialization to finish on APP CPU, before replacing

its startup stack

333

while (port_xSchedulerRunning[1] == 0) {

334

;

335

}

336 #endif

337

//Enable allocation in region where the startup stacks were located.

338

heap_caps_enable_nonos_stack_heaps();

339

app_main();

340

vTaskDelete(NULL);

341 }

(gdb)

To see the other code, enter i threads. This will show the list of threads running on target:

(gdb) i threads

Id Target Id

Frame

8 Thread 1073411336 (dport) 0x400d0848 in dport_access_init_core (arg=

<optimized out>)

at /home/user-name/esp/esp-idf/components/esp32s3/./dport_access.c:170

7 Thread 1073408744 (ipc0) xQueueGenericReceive (xQueue=0x3ffae694,

pvBuffer=0x0, xTicksToWait=1644638200,

xJustPeeking=0) at /home/user-name/esp/esp-idf/components/freertos/./queue.

c:1452

6 Thread 1073431096 (Tmr Svc) prvTimerTask (pvParameters=0x0)

at /home/user-name/esp/esp-idf/components/freertos/./timers.c:445

5 Thread 1073410208 (ipc1 : Running) 0x4000bfea in ?? ()

4 Thread 1073432224 (dport) dport_access_init_core (arg=0x0)

at /home/user-name/esp/esp-idf/components/esp32s3/./dport_access.c:150

3 Thread 1073413156 (IDLE) prvIdleTask (pvParameters=0x0)

at /home/user-name/esp/esp-idf/components/freertos/./tasks.c:3282

2 Thread 1073413512 (IDLE) prvIdleTask (pvParameters=0x0)

at /home/user-name/esp/esp-idf/components/freertos/./tasks.c:3282

* 1 Thread 1073411772 (main : Running) app_main () at /home/user-name/esp/blink/

main/./blink.c:43

(gdb)

The thread list shows the last function calls per each thread together with the name of C source file if available.
You can navigate to specific thread by entering thread N, where N is the thread Id. To see how it works go to thread thread 5:

(gdb) thread 5

(continues on next page)

Espressif Systems

1818

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

[Switching to thread 5 (Thread 1073410208)] #0 0x4000bfea in ?? () (gdb)

(continued from previous page)

Then check the backtrace:
(gdb) bt #0 0x4000bfea in ?? () #1 0x40083a85 in vPortCPUReleaseMutex (mux=<optimized out>) at /home/user-name/ esp/esp-idf/components/freertos/./port.c:415 #2 0x40083fc8 in vTaskSwitchContext () at /home/user-name/esp/esp-idf/components/ freertos/./tasks.c:2846 #3 0x4008532b in _frxt_dispatch () #4 0x4008395c in xPortStartScheduler () at /home/user-name/esp/esp-idf/components/ freertos/./port.c:222 #5 0x4000000c in ?? () #6 0x4000000c in ?? () #7 0x4000000c in ?? () #8 0x4000000c in ?? () (gdb)

As you see, the backtrace may contain several entries. This will let you check what exact sequence of function calls lead to the code where the target halted. Question marks ?? instead of a function name indicate that application is available only in binary format, without any source file in C language. The value like 0x4000bfea is the memory address of the function call.
Using bt, i threads, thread N and list commands we are now able to navigate through the code of entire application. This comes handy when stepping through the code and working with breakpoints and will be discussed below.

Setting and clearing breakpoints When debugging, we would like to be able to stop the application at critical lines of code and then examine the state of specific variables, memory and registers / peripherals. To do so we are using breakpoints. They provide a convenient way to quickly get to and halt the application at specific line.
Letns establish two breakpoints when the state of LED changes. Basing on code listing above this happens at lines 33 and 36. Breakpoints may be established using command break M where M is the code line number:
(gdb) break 33 Breakpoint 2 at 0x400db6f6: file /home/user-name/esp/blink/main/./blink.c, line 33. (gdb) break 36 Breakpoint 3 at 0x400db704: file /home/user-name/esp/blink/main/./blink.c, line 36.

If you new enter c, the processor will run and halt at a breakpoint. Entering c another time will make it run again, halt on second breakpoint, and so on:

(gdb) c Continuing. Target halted. PRO_CPU: PC=0x400DB6F6 (active)

APP_CPU: PC=0x400D10D8

Breakpoint 2, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./

blink.c:33

33

gpio_set_level(BLINK_GPIO, 0);

(gdb) c

Continuing.

Target halted. PRO_CPU: PC=0x400DB6F8 (active) APP_CPU: PC=0x400D10D8

Target halted. PRO_CPU: PC=0x400DB704 (active) APP_CPU: PC=0x400D10D8

Breakpoint 3, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./

blink.c:36

36

gpio_set_level(BLINK_GPIO, 1);

(continues on next page)

Espressif Systems

1819

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

(gdb)

(continued from previous page)

You will be also able to see that LED is changing the state only if you resume program execution by entering c. To examine how many breakpoints are set and where, use command info break:

(gdb) info break

Num

Type

Disp Enb Address What

2

breakpoint

keep y 0x400db6f6 in blink_task at /home/user-name/esp/

blink/main/./blink.c:33

breakpoint already hit 1 time

3

breakpoint

keep y 0x400db704 in blink_task at /home/user-name/esp/

blink/main/./blink.c:36

breakpoint already hit 1 time

(gdb)

Please note that breakpoint numbers (listed under Num) start with 2. This is because first breakpoint has been already established at function app_main() by running command thb app_main on debugger launch. As it was a temporary breakpoint, it has been automatically deleted and now is not listed anymore.
To remove breakpoints enter delete N command (in short d N), where N is the breakpoint number:
(gdb) delete 1 No breakpoint number 1. (gdb) delete 2 (gdb)

Read more about breakpoints under Breakpoints and watchpoints available and What else should I know about breakpoints?

Halting and resuming the application When debugging, you may resume application and enter code waiting for some event or staying in infinite loop without any break points defined. In such case, to go back to debugging mode, you can break program execution manually by entering Ctrl+C.
To check it delete all breakpoints and enter c to resume application. Then enter Ctrl+C. Application will be halted at some random point and LED will stop blinking. Debugger will print the following:

(gdb) c Continuing. ^CTarget halted. PRO_CPU: PC=0x400D0C00 [New Thread 1073433352]

APP_CPU: PC=0x400D0C00 (active)

Program received signal SIGINT, Interrupt.

[Switching to Thread 1073413512]

0x400d0c00 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/

components/esp32s3/./freertos_hooks.c:52

52

asm("waiti 0");

(gdb)

In particular case above, the application has been halted in line 52 of code in file freertos_hooks.c. Now you can resume it again by enter c or do some debugging as discussed below.

Note: In MSYS2 shell Ctrl+C does not halt the target but exists debugger. To resolve this issue consider debugging with Eclipse or check a workaround under http://www.mingw.org/wiki/Workaround_for_GDB_Ctrl_C_Interrupt.

Stepping through the code It is also possible to step through the code using step and next commands (in short s and n). The difference is that step is entering inside subroutines calls, while next steps over the call, treating it as a single source line.

Espressif Systems

1820

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

To demonstrate this functionality, using command break and delete discussed in previous paragraph, make sure that you have only one breakpoint defined at line 36 of blink.c:

(gdb) info break

Num

Type

Disp Enb Address What

3

breakpoint

keep y 0x400db704 in blink_task at /home/user-name/esp/

blink/main/./blink.c:36

breakpoint already hit 1 time

(gdb)

Resume program by entering c and let it halt:

(gdb) c Continuing. Target halted. PRO_CPU: PC=0x400DB754 (active)

APP_CPU: PC=0x400D1128

Breakpoint 3, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./

blink.c:36

36

gpio_set_level(BLINK_GPIO, 1);

(gdb)

Then enter n couple of times to see how debugger is stepping one program line at a time:

(gdb) n

Target halted. PRO_CPU: PC=0x400DB756 (active) APP_CPU: PC=0x400D1128

Target halted. PRO_CPU: PC=0x400DB758 (active) APP_CPU: PC=0x400D1128

Target halted. PRO_CPU: PC=0x400DC04C (active) APP_CPU: PC=0x400D1128

Target halted. PRO_CPU: PC=0x400DB75B (active) APP_CPU: PC=0x400D1128

37

vTaskDelay(1000 / portTICK_PERIOD_MS);

(gdb) n

Target halted. PRO_CPU: PC=0x400DB75E (active) APP_CPU: PC=0x400D1128

Target halted. PRO_CPU: PC=0x400846FC (active) APP_CPU: PC=0x400D1128

Target halted. PRO_CPU: PC=0x400DB761 (active) APP_CPU: PC=0x400D1128

Target halted. PRO_CPU: PC=0x400DB746 (active) APP_CPU: PC=0x400D1128

33

gpio_set_level(BLINK_GPIO, 0);

(gdb)

If you enter s instead, then debugger will step inside subroutine calls:

(gdb) s

Target halted. PRO_CPU: PC=0x400DB748 (active) APP_CPU: PC=0x400D1128

Target halted. PRO_CPU: PC=0x400DB74B (active) APP_CPU: PC=0x400D1128

Target halted. PRO_CPU: PC=0x400DC04C (active) APP_CPU: PC=0x400D1128

Target halted. PRO_CPU: PC=0x400DC04F (active) APP_CPU: PC=0x400D1128

gpio_set_level (gpio_num=GPIO_NUM_4, level=0) at /home/user-name/esp/esp-idf/

components/driver/./gpio.c:183

183

GPIO_CHECK(GPIO_IS_VALID_OUTPUT_GPIO(gpio_num), "GPIO output gpio_num error

", ESP_ERR_INVALID_ARG);

(gdb)

In this particular case debugger stepped inside gpio_set_level(BLINK_GPIO, 0) and effectively moved to gpio.c driver code.
See Why stepping with onextpdoes not bypass subroutine calls? for potential limitation of using next command.

Checking and setting memory Displaying the contents of memory is done with command x. With additional parameters you may vary the format and count of memory locations displayed. Run help x to see more details. Companion command to x is set that let you write values to the memory.
We will demonstrate how x and set work by reading from and writing to the memory location 0x3FF44004 labeled as GPIO_OUT_REG used to set and clear individual GPIOns.

Espressif Systems

1821

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

For more information, see ESP32-S3 Technical Reference Manual > IO MUX and GPIO Matrix (GPIO, IO_MUX) [PDF].
Being in the same blink.c project as before, set two breakpoints right after gpio_set_level instruction. Enter two times c to get to the break point followed by x /1wx 0x3FF44004 to display contents of GPIO_OUT_REG memory location:

(gdb) c Continuing. Target halted. PRO_CPU: PC=0x400DB75E (active) Target halted. PRO_CPU: PC=0x400DB74E (active)

APP_CPU: PC=0x400D1128 APP_CPU: PC=0x400D1128

Breakpoint 2, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./

blink.c:34

34

vTaskDelay(1000 / portTICK_PERIOD_MS);

(gdb) x /1wx 0x3FF44004

0x3ff44004: 0x00000000

(gdb) c

Continuing.

Target halted. PRO_CPU: PC=0x400DB751 (active) APP_CPU: PC=0x400D1128

Target halted. PRO_CPU: PC=0x400DB75B (active) APP_CPU: PC=0x400D1128

Breakpoint 3, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./

blink.c:37

37

vTaskDelay(1000 / portTICK_PERIOD_MS);

(gdb) x /1wx 0x3FF44004

0x3ff44004: 0x00000010

(gdb)

If your are blinking LED connected to GPIO4, then you should see fourth bit being flipped each time the LED changes the state:
0x3ff44004: 0x00000000 ... 0x3ff44004: 0x00000010

Now, when the LED is off, that corresponds to 0x3ff44004: 0x00000000 being displayed, try using set command to set this bit by writting 0x00000010 to the same memory location:
(gdb) x /1wx 0x3FF44004 0x3ff44004: 0x00000000 (gdb) set {unsigned int}0x3FF44004=0x000010

You should see the LED to turn on immediately after entering set int}0x3FF44004=0x000010 command.

{unsigned

Watching and setting program variables A common debugging tasks is checking the value of a program variable as the program runs. To be able to demonstrate this functionality, update file blink.c by adding a declaration of a global variable int i above definition of function blink_task. Then add i++ inside while(1) of this function to get i incremented on each blink.
Exit debugger, so it is not confused with new code, build and flash the code to the ESP and restart debugger. There is no need to restart OpenOCD.
Once application is halted, enter the command watch i:
(gdb) watch i Hardware watchpoint 2: i (gdb)
This will insert so called owatchpointpin each place of code where variable i is being modified. Now enter continue to resume the application and observe it being halted:

Espressif Systems

1822

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

(gdb) c Continuing. Target halted. PRO_CPU: PC=0x400DB751 (active) [New Thread 1073432196]

APP_CPU: PC=0x400D0811

Program received signal SIGTRAP, Trace/breakpoint trap.

[Switching to Thread 1073432196]

0x400db751 in blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./

blink.c:33

33

i++;

(gdb)

Resume application couple more times so i gets incremented. Now you can enter print i (in short p i) to check the current value of i:
(gdb) p i $1 = 3 (gdb)

To modify the value of i use set command as below (you can then print it out to check if it has been indeed changed):
(gdb) set var i = 0 (gdb) p i $3 = 0 (gdb)

You may have up to two watchpoints, see Breakpoints and watchpoints available.

Setting conditional breakpoints Here comes more interesting part. You may set a breakpoint to halt the program execution, if certain condition is satisfied. Delete existing breakpoints and try this:
(gdb) break blink.c:34 if (i == 2) Breakpoint 3 at 0x400db753: file /home/user-name/esp/blink/main/./blink.c, line 34. (gdb)

Above command sets conditional breakpoint to halt program execution in line 34 of blink.c if i == 2.
If current value of i is less than 2 and program is resumed, it will blink LED in a loop until condition i == 2 gets true and then finally halt:

(gdb) set var i = 0 (gdb) c Continuing. Target halted. PRO_CPU: PC=0x400DB755 (active) Target halted. PRO_CPU: PC=0x400DB753 (active) Target halted. PRO_CPU: PC=0x400DB755 (active) Target halted. PRO_CPU: PC=0x400DB753 (active)

APP_CPU: PC=0x400D112C APP_CPU: PC=0x400D112C APP_CPU: PC=0x400D112C APP_CPU: PC=0x400D112C

Breakpoint 3, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./

blink.c:34

34

gpio_set_level(BLINK_GPIO, 0);

(gdb)

Obtaining help on commands Commands presented so for should provide are very basis and intended to let you quickly get started with JTAG debugging. Check help what are the other commands at you disposal. To obtain help on syntax and functionality of particular command, being at (gdb) prompt type help and command name:

Espressif Systems

1823

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

(gdb) help next Step program, proceeding through subroutine calls. Usage: next [N] Unlike "step", if the current source line calls a subroutine, this command does not enter the subroutine, but instead steps over the call, in effect treating it as a single source line. (gdb)
By typing just help, you will get top level list of command classes, to aid you drilling down to more details. Optionally refer to available GDB cheat sheets, for instance https://darkdust.net/files/GDB%20Cheat%20Sheet.pdf. Good to have as a reference (even if not all commands are applicable in an embedded environment).
Ending debugger session To quit debugger enter q:
(gdb) q A debugging session is active.
Inferior 1 [Remote target] will be detached.
Quit anyway? (y or n) y Detaching from program: /home/user-name/esp/blink/build/blink.elf, Remote target Ending remote debugging. user-name@computer-name:~/esp/blink$
· Using Debugger · Debugging Examples · Tips and Quirks · Application Level Tracing library · Introduction to ESP-Prog Board

4.21 Linker Script Generation
4.21.1 Overview
There are several memory regions where code and data can be placed. Code and read-only data are placed by default in flash, writable data in RAM, etc. However, it is sometimes necessary to change these default placements. For example, it may be necessary to place critical code in RAM for performance reasons or to place code in RTC memory for use in a wake stub or the ULP coprocessor. With the linker script generation mechanism, it is possible to specify these placements at the component level within ESP-IDF. The component presents information on how it would like to place its symbols, objects or the entire archive. During build, the information presented by the components are collected, parsed and processed; and the placement rules generated is used to link the app.

4.21.2 Quick Start

This section presents a guide for quickly placing code/data to RAM and RTC memory - placements ESP-IDF provides out-of-the-box.
For this guide, suppose we have the following:

component  my_component
 CMakeLists.txt  component.mk  Kconfig

(continues on next page)

Espressif Systems

1824

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

 src/   my_src1.c   my_src2.c   my_src3.c  my_linker_fragment_file.lf

(continued from previous page)

· a component named my_component that is archived as library libmy_component.a during build · three source files archived under the library, my_src1.c, my_src2.c and my_src3.c which are com-
piled as my_src1.o, my_src2.o and my_src3.o, respectively · under my_src1.o, the function my_function1 is defined; under my_src2.o, the function
my_function2 is defined · there is bool-type config PERFORMANCE_MODE (y/n) and int type config PERFORMANCE_LEVEL (with
range 0-3) in my_componentns Kconfig

Creating and Specifying a Linker Fragment File
Before anything else, a linker fragment file needs to be created. A linker fragment file is simply a text file with a .lf extension upon which the desired placements will be written. After creating the file, it is then necessary to present it to the build system. The instructions for the build systems supported by ESP-IDF are as follows:
In the componentns CMakeLists.txt file, specify argument LDFRAGMENTS in the idf_component_register call. The value of LDFRAGMENTS can either be an absolute path or a relative path from the component directory to the created linker fragment file.
# file paths relative to CMakeLists.txt idf_component_register(...
LDFRAGMENTS "path/to/linker_fragment_file.lf" "path/to/ another_linker_fragment_file.lf"
... )

Specifying placements
It is possible to specify placements at the following levels of granularity: · object file (.obj or .o files) · symbol (function/variable) · archive (.a files)

Placing object files Suppose the entirety of my_src1.o is performance-critical, so it is desirable to place it in RAM. On the other hand, the entirety of my_src2.o contains symbols needed coming out of deep sleep, so it needs to be put under RTC memory. In the linker fragment file, we can write:

[mapping:my_component]

archive: libmy_component.a

entries:

my_src1 (noflash)

# places all my_src1 code/read-only data under IRAM/DRAM

my_src2 (rtc)

# places all my_src2 code/ data and read-only data under

RTC fast memory/RTC slow memory

What happens to my_src3.o? Since it is not specified, default placements are used for my_src3.o. More on default placements here.

Placing symbols Continuing our example, suppose that among functions defined under object1.o, only my_function1 is performance-critical; and under object2.o, only my_function2 needs to execute after the chip comes out of deep sleep. This could be accomplished by writing:

Espressif Systems

1825

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

[mapping:my_component] archive: libmy_component.a entries:
my_src1:my_function1 (noflash) my_src2:my_function2 (rtc)
The default placements are used for the rest of the functions in my_src1.o and my_src2.o and the entire object3.o. Something similar can be achieved for placing data by writing the variable name instead of the function name, like so:
my_src1:my_variable (noflash)
Warning: There are limitations in placing code/data at symbol granularity. In order to ensure proper placements, an alternative would be to group relevant code and data into source files, and use object-granularity placements.

Placing entire archive In this example, suppose that the entire component archive needs to be placed in RAM. This can be written as:
[mapping:my_component] archive: libmy_component.a entries:
* (noflash)
Similarly, this places the entire component in RTC memory:
[mapping:my_component] archive: libmy_component.a entries:
* (rtc)

Configuration-dependent placements Suppose that the entire component library should only have special placement when a certain condition is true; for example, when CONFIG_PERFORMANCE_MODE == y. This could be written as:
[mapping:my_component] archive: libmy_component.a entries:
if PERFORMANCE_MODE = y: * (noflash)
else: * (default)

For a more complex config-dependent placement, suppose the following requirements: when

CONFIG_PERFORMANCE_LEVEL == 1, only object1.o is put in RAM; when CON-

FIG_PERFORMANCE_LEVEL

==

2, object1.o and object2.o; and when CON-

FIG_PERFORMANCE_LEVEL == 3 all object files under the archive are to be put into RAM. When

these three are false however, put entire library in RTC memory. This scenario is a bit contrived, but, it can be

written as:

[mapping:my_component] archive: libmy_component.a entries:
if PERFORMANCE_LEVEL = 1: my_src1 (noflash)
elif PERFORMANCE_LEVEL = 2: my_src1 (noflash)

(continues on next page)

Espressif Systems

1826

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

my_src2 (noflash) elif PERFORMANCE_LEVEL = 3:
my_src1 (noflash) my_src2 (noflash) my_src3 (noflash) else: * (rtc)

(continued from previous page)

Nesting condition-checking is also possible. The following is equivalent to the snippet above:
[mapping:my_component] archive: libmy_component.a entries:
if PERFORMANCE_LEVEL <= 3 && PERFORMANCE_LEVEL > 0: if PERFORMANCE_LEVEL >= 1: object1 (noflash) if PERFORMANCE_LEVEL >= 2: object2 (noflash) if PERFORMANCE_LEVEL >= 3: object2 (noflash)
else: * (rtc)

The mdefaultnplacements
Up until this point, the term mdefault placementsnhas been mentioned as fallback placements when the placement rules rtc and noflash are not specified. It is important to note that the tokens noflash or rtc are not merely keywords, but are actually entities called fragments, specifically schemes. In the same manner as rtc and noflash are schemes, there exists a default scheme which defines what the default placement rules should be. As the name suggests, it is where code and data are usually placed, i.e. code/constants is placed in flash, variables placed in RAM, etc. More on the default scheme here.
Note: For an example of an ESP-IDF component using the linker script generation mechanism, see freertos/CMakeLists.txt. freertos uses this to place its object files to the instruction RAM for performance reasons.
This marks the end of the quick start guide. The following text discusses the internals of the mechanism in a little bit more detail. The following sections should be helpful in creating custom placements or modifying default behavior.
4.21.3 Linker Script Generation Internals
Linking is the last step in the process of turning C/C++ source files into an executable. It is performed by the toolchainns linker, and accepts linker scripts which specify code/data placements, among other things. With the linker script generation mechanism, this process is no different, except that the linker script passed to the linker is dynamically generated from: (1) the collected linker fragment files and (2) linker script template.
Note: The tool that implements the linker script generation mechanism lives under tools/ldgen.

Linker Fragment Files
As mentioned in the quick start guide, fragment files are simple text files with the .lf extension containing the desired placements. This is a simplified description of what fragment files contain, however. What fragment files actually contain are mfragmentsn. Fragments are entities which contain pieces of information which, when put

Espressif Systems

1827

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
together, form placement rules that tell where to place sections of object files in the output binary. There are three types of fragments: sections, scheme and mapping.
Grammar The three fragment types share a common grammar:
[type:name] key: value key:
value value value ...
· type: Corresponds to the fragment type, can either be sections, scheme or mapping. · name: The name of the fragment, should be unique for the specified fragment type. · key, value: Contents of the fragment; each fragment type may support different keys and different grammars
for the key values. ­ For sections and scheme, the only supported key is entries ­ For mappings, both archive and entries are supported.
Note: In cases where multiple fragments of the same type and name are encountered, an exception is thrown.

Note: The only valid characters for fragment names and keys are alphanumeric characters and underscore.

Condition Checking
Condition checking enable the linker script generation to be configuration-aware. Depending on whether expressions involving configuration values are true or not, a particular set of values for a key can be used. The evaluation uses eval_string from kconfiglib package and adheres to its required syntax and limitations. Supported operators are as follows:
· comparison ­ LessThan < ­ LessThanOrEqualTo <= ­ MoreThan > ­ MoreThanOrEqualTo >= ­ Equal = ­ NotEqual !=
· logical ­ Or || ­ And && ­ Negation !
· grouping ­ Parenthesis ()
Condition checking behaves as you would expect an if...elseif/elif...else block in other languages. Condition-checking is possible for both key values and entire fragments. The two sample fragments below are equivalent:

# Value for keys is dependent on config [type:name] key_1:
if CONDITION = y: value_1
else: value_2
key_2:

(continues on next page)

Espressif Systems

1828

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

if CONDITION = y: value_a
else: value_b

(continued from previous page)

# Entire fragment definition is dependent on config if CONDITION = y:
[type:name] key_1:
value_1 key_2:
value_b else:
[type:name] key_1:
value_2 key_2:
value_b
Comments
Comment in linker fragment files begin with #. Like in other languages, comment are used to provide helpful descriptions and documentation and are ignored during processing.

Types Sections
Sections fragments defines a list of object file sections that the GCC compiler emits. It may be a default section (e.g. .text, .data) or it may be user defined section through the __attribute__ keyword.
The use of an optionalm+nindicates the inclusion of the section in the list, as well as sections that start with it. This is the preferred method over listing both explicitly.
[sections:name] entries:
.section+ .section ...

Example:

# Non-preferred [sections:text] entries:
.text .text.* .literal .literal.*

# Preferred, equivalent to the one above

[sections:text]

entries:

.text+

# means .text and .text.*

.literal+

# means .literal and .literal.*

Scheme
Scheme fragments define what target a sections fragment is assigned to.
[scheme:name] entries:
sections -> target

(continues on next page)

Espressif Systems

1829

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

sections -> target ...

(continued from previous page)

Example:

[scheme:noflash] entries:
text -> iram0_text text will go to iram0_text
rodata -> dram0_data rodata will go to dram0_data

# the entries under the sections fragment named # the entries under the sections fragment named

The default scheme
There exists a special scheme with the name default. This scheme is special because catch-all placement rules are generated from its entries. This means that, if one of its entries is text -> flash_text, the placement rule will be generated for the target flash_text.
*(.literal .literal.* .text .text.*)

These catch-all rules then effectively serve as fallback rules for those whose mappings were not specified.
The default scheme is defined in esp_system/app.lf. The noflash and rtc scheme fragments which are built-in schemes referenced in the quick start guide are also defined in this file.
Mapping
Mapping fragments define what scheme fragment to use for mappable entities, i.e. object files, function names, variable names, archives.

[mapping:name] archive: archive a) entries:
object:symbol (scheme) object (scheme) * (scheme)

# output archive file name, as built (i.e. libxxx.
# symbol granularity # object granularity # archive granularity

There are three levels of placement granularity:
· symbol: The object file name and symbol name are specified. The symbol name can be a function name or a variable name.
· object: Only the object file name is specified. · archive: * is specified, which is a short-hand for all the object files under the archive.
To know what an entry means, let us expand a sample object-granularity placement:
object (scheme)

Then expanding the scheme fragment from its entries definitions, we have:
object (sections -> target, sections -> target, ...)

Expanding the sections fragment with its entries definition:

object (.section,

# given this object file

.section,

# put its sections listed here at this

... -> target, # target

.section,

(continues on next page)

Espressif Systems

1830

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

.section,

# same should be done for these sections

... -> target,

(continued from previous page)

...)

# and so on

Example:
[mapping:map] archive: libfreertos.a entries:
* (noflash)

Aside from the entity and scheme, flags can also be specified in an entry. The following flags are supported (note: <> = argument name, [] = optional):
1. ALIGN(<alignment>[, pre, post]) Align the placement by the amount specified in alignment. Generates
2. SORT([<sort_by_first>, <sort_by_second>]) Emits SORT_BY_NAME, SORT_BY_ALIGNMENT, SORT_BY_INIT_PRIORITY or SORT in the input section description. Possible values for sort_by_first and sort_by_second are: name, alignment, init_priority. If both sort_by_first and sort_by_second are not specified, the input sections are sorted by name. If both are specified, then the nested sorting follows the same rules discussed in https: //sourceware.org/binutils/docs/ld/Input-Section-Wildcards.html.
3. KEEP() Prevent the linker from discarding the placement by surrounding the input section description with KEEP command. See https://sourceware.org/binutils/docs/ld/Input-Section-Keep.html for more details.
4.SURROUND(<name>)
Generate symbols before and after the placement. The generated symbols follow the naming _<name>_start and _<name>_end. For example, if name == sym1,
When adding flags, the specific section -> target in the scheme needs to be specified. For multiple section -> target, use a comma as a separator. For example,
# Notes: # A. semicolon after entity-scheme # B. comma before section2 -> target2 # C. section1 -> target1 and section2 -> target2 should be defined in entries of scheme1 entity1 (scheme1);
section1 -> target1 KEEP() ALIGN(4, pre, post), section2 -> target2 SURROUND(sym) ALIGN(4, post) SORT()

Putting it all together, the following mapping fragment, for example,
[mapping:name] archive: lib1.a entries:
obj1 (noflash); rodata -> dram0_data KEEP() SORT() ALIGN(8) SURROUND(my_sym)

generates an output on the linker script:
. = ALIGN(8) _my_sym_start = ABSOLUTE(.) KEEP(lib1.a:obj1.*( SORT(.rodata) SORT(.rodata.*) )) _my_sym_end = ABSOLUTE(.)

Espressif Systems

1831

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Note that ALIGN and SURROUND, as mentioned in the flag descriptions, are order sensitive. Therefore, if for the same mapping fragment these two are switched, the following is generated instead:
_my_sym_start = ABSOLUTE(.) . = ALIGN(8) KEEP(lib1.a:obj1.*( SORT(.rodata) SORT(.rodata.*) )) _my_sym_end = ABSOLUTE(.)

On Symbol-Granularity Placements Symbol granularity placements is possible due to compiler flags ffunction-sections and -ffdata-sections. ESP-IDF compiles with these flags by default. If the user opts to remove these flags, then the symbol-granularity placements will not work. Furthermore, even with the presence of these flags, there are still other limitations to keep in mind due to the dependence on the compilerns emitted output sections.
For example, with -ffunction-sections, separate sections are emitted for each function; with section names predictably constructed i.e. .text.{func_name} and .literal.{func_name}. This is not the case for string literals within the function, as they go to pooled or generated section names.
With -fdata-sections, for global scope data the compiler predictably emits either .data.{var_name}, .rodata.{var_name} or .bss.{var_name}; and so Type I mapping entry works for these. However, this is not the case for static data declared in function scope, as the generated section name is a result of mangling the variable name with some other information.

Linker Script Template

The linker script template is the skeleton in which the generated placement rules are put into. It is an otherwise ordinary linker script, with a specific marker syntax that indicates where the generated placement rules are placed. To reference the placement rules collected under a target token, the following syntax is used:
mapping[target]

Example:
The example below is an excerpt from a possible linker script template. It defines an output section .iram0.text, and inside is a marker referencing the target iram0_text.
.iram0.text : {
/* Code marked as runnning out of IRAM */ _iram_text_start = ABSOLUTE(.);
/* Marker referencing iram0_text */ mapping[iram0_text]
_iram_text_end = ABSOLUTE(.); } > iram0_0_seg

Suppose the generator collected the fragment definitions below:
[sections:text] .text+ .literal+
[sections:iram] .iram1+
[scheme:default] entries:
text -> flash_text

(continues on next page)

Espressif Systems

1832

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

iram -> iram0_text
[scheme:noflash] entries:
text -> iram0_text
[mapping:freertos] archive: libfreertos.a entries:
* (noflash)

(continued from previous page)

Then the corresponding excerpt from the generated linker script will be as follows:
.iram0.text : {
/* Code marked as runnning out of IRAM */ _iram_text_start = ABSOLUTE(.);
/* Placement rules generated from the processed fragments, placed where the marker was in the template */
*(.iram1 .iram1.*) *libfreertos.a:(.literal .text .literal.* .text.*)
_iram_text_end = ABSOLUTE(.); } > iram0_0_seg

*libfreertos.a:(.literal .text .literal.* .text.*)
Rule generated from the entry * (noflash) of the freertos mapping fragment. All text sections of all object files under the archive libfreertos.a will be collected under the target iram0_text (as per the noflash scheme) and placed wherever in the template iram0_text is referenced by a marker.
*(.iram1 .iram1.*)
Rule generated from the default scheme entry iram -> iram0_text. Since the default scheme specifies an iram -> iram0_text entry, it too is placed wherever iram0_text is referenced by a marker. Since it is a rule generated from the default scheme, it comes first among all other rules collected under the same target name.
The linker script template currently used is esp_system/ld/esp32s3/sections.ld.in; the generated output script sections.ld is put under its build directory.

Migrate to ESP-IDF v5.0 Linker Script Fragment Files Grammar
The old grammar supported in ESP-IDF v3.x would be dropped in ESP-IDF v5.0. Here are a few notes on how to migrate properly:
1. Now indentation is enforced and improperly indented fragment files would generate a runtime parse exception. This was not enforced in the old version but previous documentation and examples demonstrate properly indented grammar.
2. Migrate the old condition entry to the if...elif...else structure for conditionals. You can refer to the earlier chapter for detailed grammar.
3. mapping fragments now requires a name like other fragment types.

4.22 Memory Types
ESP32-S3 chip has multiple memory types and flexible memory mapping features. This section describes how ESPIDF uses these features by default.

Espressif Systems

1833

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
ESP-IDF distinguishes between instruction memory bus (IRAM, IROM, RTC FAST memory) and data memory bus (DRAM, DROM). Instruction memory is executable, and can only be read or written via 4-byte aligned words. Data memory is not executable and can be accessed via individual byte operations. For more information about the different memory buses consult the ESP32-S3 Technical Reference Manual > System and Memory [PDF].
4.22.1 DRAM (Data RAM)
Non-constant static data (.data) and zero-initialized data (.bss) is placed by the linker into Internal SRAM as data memory. The remaining space in this region is used for the runtime heap.
Note: The maximum statically allocated DRAM size is reduced by the IRAM (Instruction RAM) size of the compiled application. The available heap memory at runtime is reduced by the total static IRAM and DRAM usage of the application.
Constant data may also be placed into DRAM, for example if it is used in an non-flash-safe ISR (see explanation under How to place code in IRAM).
onoinitpDRAM
The macro __NOINIT_ATTR can be used as attribute to place data into .noinit section. The values placed into this section will not be initialized at startup and should keep its value after software restart. Example: __NOINIT_ATTR uint32_t noinit_data;
4.22.2 IRAM (Instruction RAM)
Note: Any internal SRAM which is not used for Instruction RAM will be made available as DRAM (Data RAM) for static data and dynamic allocation (heap).
When to place code in IRAM
Cases when parts of the application should be placed into IRAM: · Interrupt handlers must be placed into IRAM if ESP_INTR_FLAG_IRAM is used when registering the interrupt handler. For more information, see IRAM-Safe Interrupt Handlers. · Some timing critical code may be placed into IRAM to reduce the penalty associated with loading the code from flash. ESP32-S3 reads code and data from flash via the MMU cache. In some cases, placing a function into IRAM may reduce delays caused by a cache miss and significantly improve that functionns performance.
How to place code in IRAM
Some code is automatically placed into the IRAM region using the linker script. If some specific application code needs to be placed into IRAM, it can be done by using the Linker Script Generation feature and adding a linker script fragment file to your component that targets at the entire source files or functions with the noflash placement. See the Linker Script Generation docs for more information. Alternatively, itns possible to specify IRAM placement in the source code using the IRAM_ATTR macro:

Espressif Systems

1834

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

#include "esp_attr.h"
void IRAM_ATTR gpio_isr_handler(void* arg) {
// ... }
There are some possible issues with placement in IRAM, that may cause problems with IRAM-safe interrupt handlers:
· Strings or constants inside an IRAM_ATTR function may not be placed in RAM automatically. Itns possible to use DRAM_ATTR attributes to mark these, or using the linker script method will cause these to be automatically placed correctly.
void IRAM_ATTR gpio_isr_handler(void* arg) {
const static DRAM_ATTR uint8_t INDEX_DATA[] = { 45, 33, 12, 0 }; const static char *MSG = DRAM_STR("I am a string stored in RAM"); }
Note that knowing which data should be marked with DRAM_ATTR can be hard, the compiler will sometimes recognize that a variable or expression is constant (even if it is not marked const) and optimize it into flash, unless it is marked with DRAM_ATTR.
· GCC optimizations that automatically generate jump tables or switch/case lookup tables place these tables in flash. IDF by default builds all files with -fno-jump-tables -fno-tree-switch-conversion flags to avoid this.
Jump table optimizations can be re-enabled for individual source files that donnt need to be placed in IRAM. For instructions on how to add the -fno-jump-tables -fno-tree-switch-conversion options when compiling individual source files, see Controlling Component Compilation.

4.22.3 IROM (code executed from flash)
If a function is not explicitly placed into IRAM (Instruction RAM) or RTC memory, it is placed into flash. The mechanism by which Flash MMU is used to allow code execution from flash is described in ESP32-S3 Technical Reference Manual > Memory Management and Protection Units (MMU, MPU) [PDF]. As IRAM is limited, most of an applicationns binary code must be placed into IROM instead.
During Application Startup Flow, the bootloader (which runs from IRAM) configures the MMU flash cache to map the appns instruction code region to the instruction space. Flash accessed via the MMU is cached using some internal SRAM and accessing cached flash data is as fast as accessing other types of internal memory.

4.22.4 RTC FAST memory
The same region of RTC FAST memory can be accessed as both instruction and data memory. Code which has to run after wake-up from deep sleep mode has to be placed into RTC memory. Please check detailed description in deep sleep documentation.
Remaining RTC FAST memory is added to the heap unless the option CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP is disabled. This memory can be used interchangeably with DRAM (Data RAM), but is slightly slower to access.

4.22.5 DROM (data stored in flash)
By default, constant data is placed by the linker into a region mapped to the MMU flash cache. This is the same as the IROM (code executed from flash) section, but is for read-only data not executable code. The only constant data not placed into this memory type by default are literal constants which are embedded by the compiler into application code. These are placed as the surrounding functionns executable instructions.

Espressif Systems

1835

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

The DRAM_ATTR attribute can be used to force constants from DROM into the DRAM (Data RAM) section (see above).
4.22.6 RTC Slow memory
Global and static variables used by code which runs from RTC memory must be placed into RTC Slow memory. For example deep sleep variables can be placed here instead of RTC FAST memory, or code and variables accessed by the ULP Coprocessor programming. The attribute macro named RTC_NOINIT_ATTR can be used to place data into this type of memory. The values placed into this section keep their value after waking from deep sleep. Example:
RTC_NOINIT_ATTR uint32_t rtc_noinit_data;

4.22.7 DMA Capable Requirement
Most peripheral DMA controllers (e.g. SPI, sdmmc, etc.) have requirements that sending/receiving buffers should be placed in DRAM and word-aligned. We suggest to place DMA buffers in static variables rather than in the stack. Use macro DMA_ATTR to declare global/local static variables like:
DMA_ATTR uint8_t buffer[]="I want to send something";
void app_main() {
// initialization code... spi_transaction_t temp = {
.tx_buffer = buffer, .length = 8 * sizeof(buffer), }; spi_device_transmit(spi, &temp); // other stuff }
Or:
void app_main() {
DMA_ATTR static uint8_t buffer[] = "I want to send something"; // initialization code... spi_transaction_t temp = {
.tx_buffer = buffer, .length = 8 * sizeof(buffer), }; spi_device_transmit(spi, &temp); // other stuff }
It is also possible to allocate DMA-capable memory buffers dynamically by using the MALLOC_CAP_DMA capabilities flag.

4.22.8 DMA Buffer in the stack
Placing DMA buffers in the stack is possible but discouraged. If doing so, pay attention to the following: · Placing DRAM buffers on the stack is not recommended if the stack may be in PSRAM. If the stack of a task is placed in the PSRAM, several steps have to be taken as described in Support for External RAM. · Use macro WORD_ALIGNED_ATTR in functions before variables to place them in proper positions like:

Espressif Systems

1836

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

void app_main() {
uint8_t stuff; WORD_ALIGNED_ATTR uint8_t buffer[] = "I want to send something"; the buffer will be placed right after stuff. // initialization code... spi_transaction_t temp = {
.tx_buffer = buffer, .length = 8 * sizeof(buffer), }; spi_device_transmit(spi, &temp); // other stuff }

//or

4.23 lwIP
ESP-IDF uses the open source lwIP lightweight TCP/IP stack. The ESP-IDF version of lwIP (esp-lwip) has some modifications and additions compared to the upstream project.
4.23.1 Supported APIs
ESP-IDF supports the following lwIP TCP/IP stack functions: · BSD Sockets API · Netconn API is enabled but not officially supported for ESP-IDF applications
Adapted APIs
Some common lwIP oapppAPIs are supported indirectly by ESP-IDF: · DHCP Server & Client are supported indirectly via the ESP-NETIF functionality · Simple Network Time Protocol (SNTP) is supported via the lwip/include/apps/sntp/sntp.h lwip/lwip/src/include/lwip/apps/sntp.h functions (see also SNTP Time Synchronization) · ICMP Ping is supported using a variation on the lwIP ping API. See ICMP Echo. · NetBIOS lookup is available using the standard lwIP API. protocols/http_server/restful_server has an option to demonstrate using NetBIOS to look up a host on the LAN. · mDNS uses a different implementation to the lwIP default mDNS (see mDNS Service), but lwIP can look up mDNS hosts using standard APIs such as gethostbyname() and the convention hostname.local, provided the CONFIG_LWIP_DNS_SUPPORT_MDNS_QUERIES setting is enabled.
4.23.2 BSD Sockets API
The BSD Sockets API is a common cross-platform TCP/IP sockets API that originated in the Berkeley Standard Distribution of UNIX but is now standardized in a section of the POSIX specification. BSD Sockets are sometimes called POSIX Sockets or Berkeley Sockets. As implemented in ESP-IDF, lwIP supports all of the common usages of the BSD Sockets API.
References
A wide range of BSD Sockets reference material is available, including: · Single UNIX Specification BSD Sockets page · Berkeley Sockets Wikipedia page

Espressif Systems

1837

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Examples
A number of ESP-IDF examples show how to use the BSD Sockets APIs:
· protocols/sockets/tcp_server · protocols/sockets/tcp_client · protocols/sockets/udp_server · protocols/sockets/udp_client · protocols/sockets/udp_multicast · protocols/http_request (Note: this is a simplified example of using a TCP socket to send an HTTP request.
The ESP HTTP Client is a much better option for sending HTTP requests.)
Supported functions
The following BSD socket API functions are supported. For full details see lwip/lwip/src/include/lwip/sockets.h.
· socket() · bind() · accept() · shutdown() · getpeername() · getsockopt() & setsockopt() (see Socket Options) · close() (via Virtual filesystem component) · read(), readv(), write(), writev() (via Virtual filesystem component) · recv(), recvmsg(), recvfrom() · send(), sendmsg(), sendto() · select() (via Virtual filesystem component) · poll() (Note: on ESP-IDF, poll() is implemented by calling select internally, so using select()
directly is recommended if a choice of methods is available.) · fcntl() (see fcntl)
Non-standard functions:
· ioctl() (see ioctls)
Note: Some lwIP application sample code uses prefixed versions of BSD APIs, for example lwip_socket() instead of the standard socket(). Both forms can be used with ESP-IDF, but using standard names is recommended.

Socket Error Handling
BSD Socket error handling code is very important for robust socket applications. Normally the socket error handling involves the following aspects:
· Detecting the error. · Geting the error reason code. · Handle the error according to the reason code. In lwIP, we have two different scenarios of handling socket errors: · Socket API returns an error. For more information, see Socket API Errors. · select(int maxfdp1, fd_set *readset, fd_set *writeset, fd_set *exceptset,
struct timeval *timeout) has exception descriptor indicating that the socket has an error. For more information, see select() Errors.
Socket API Errors The error detection

Espressif Systems

1838

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

· We can know that the socket API fails according to its return value. Get the error reason code
· When socket API fails, the return value doesnnt contain the failure reason and the application can get the error reason code by accessing errno. Different values indicate different meanings. For more information, see <Socket Error Reason Code>.
Example:
int err; int sockfd;
if (sockfd = socket(AF_INET,SOCK_STREAM,0) < 0) { // the error code is obtained from errno err = errno; return err;
}

select() Errors
The error detection · Socket error when select() has exception descriptor
Get the error reason code · If the select indicates that the socket fails, we cannt get the error reason code by accessing errno, instead we should call getsockopt() to get the failure reason code. Because select() has exception descriptor, the error code will not be given to errno.
Note: getsockopt function prototype int getsockopt(int s, int level, int optname, void *optval, socklen_t *optlen). Its function is to get the current value of the option of any type, any state socket, and store the result in optval. For example, when you get the error code on a socket, you can get it by getsockopt(sockfd, SOL_SOCKET, SO_ERROR, &err, &optlen).
Example:
int err;
if (select(sockfd + 1, NULL, NULL, &exfds, &tval) <= 0) { err = errno; return err;
} else { if (FD_ISSET(sockfd, &exfds)) { // select() exception set using getsockopt() int optlen = sizeof(int); getsockopt(sockfd, SOL_SOCKET, SO_ERROR, &err, &optlen); return err; }
}

Socket Error Reason Code Below is a list of common error codes. For more detailed list

of standard POSIX/C error codes, please see newlib errno.h <https://github.com/espressif/newlib-

esp32/blob/master/newlib/libc/include/sys/errno.h>

and

the

platform-specific

extensions

newlib/platform_include/errno.h

Espressif Systems

1839

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Error code ECONNREFUSED EADDRINUSE ECONNABORTED ENETUNREACH ENETDOWN ETIMEDOUT EHOSTDOWN EHOSTUNREACH EINPROGRESS EALREADY EDESTADDRREQ EPROTONOSUPPORT

Description Connection refused Address already in use Software caused connection abort Network is unreachable Network interface is not configured Connection timed out Host is down Host is unreachable Connection already in progress Socket already connected Destination address required Unknown protocol

Socket Options
The getsockopt() and setsockopt() functions allow getting/setting per-socket options.
Not all standard socket options are supported by lwIP in ESP-IDF. The following socket options are supported:
Common options Used with level argument SOL_SOCKET.
· SO_REUSEADDR (available if CONFIG_LWIP_SO_REUSE is set, behavior can be customized by setting CONFIG_LWIP_SO_REUSE_RXTOALL)
· SO_KEEPALIVE · SO_BROADCAST · SO_ACCEPTCONN · SO_RCVBUF (available if CONFIG_LWIP_SO_RCVBUF is set) · SO_SNDTIMEO / SO_RCVTIMEO · SO_ERROR (this option is only used with select(), see Socket Error Handling) · SO_TYPE · SO_NO_CHECK (for UDP sockets only)
IP options Used with level argument IPPROTO_IP.
· IP_TOS · IP_TTL · IP_PKTINFO (available if CONFIG_LWIP_NETBUF_RECVINFO is set)
For multicast UDP sockets:
· IP_MULTICAST_IF · IP_MULTICAST_LOOP · IP_MULTICAST_TTL · IP_ADD_MEMBERSHIP · IP_DROP_MEMBERSHIP
TCP options TCP sockets only. Used with level argument IPPROTO_TCP.
· TCP_NODELAY
Options relating to TCP keepalive probes:
· TCP_KEEPALIVE (int value, TCP keepalive period in milliseconds) · TCP_KEEPIDLE (same as TCP_KEEPALIVE, but the value is in seconds) · TCP_KEEPINTVL (int value, interval between keepalive probes in seconds) · TCP_KEEPCNT (int value, number of keepalive probes before timing out)

Espressif Systems

1840

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

IPv6 options IPv6 sockets only. Used with level argument IPPROTO_IPV6
· IPV6_CHECKSUM · IPV6_V6ONLY
For multicast IPv6 UDP sockets:
· IPV6_JOIN_GROUP / IPV6_ADD_MEMBERSHIP · IPV6_LEAVE_GROUP / IPV6_DROP_MEMBERSHIP · IPV6_MULTICAST_IF · IPV6_MULTICAST_HOPS · IPV6_MULTICAST_LOOP

fcntl
The fcntl() function is a standard API for manipulating options related to a file descriptor. In ESP-IDF, the Virtual filesystem component layer is used to implement this function.
When the file descriptor is a socket, only the following fcntl() values are supported:
· O_NONBLOCK to set/clear non-blocking I/O mode. Also supports O_NDELAY, which is identical to O_NONBLOCK.
· O_RDONLY, O_WRONLY, O_RDWR flags for different read/write modes. These can read via F_GETFL only, they cannot be set using F_SETFL. A TCP socket will return a different mode depending on whether the connection has been closed at either end or is still open at both ends. UDP sockets always return O_RDWR.

ioctls
The ioctl() function provides a semi-standard way to access some internal features of the TCP/IP stack. In ESP-IDF, the Virtual filesystem component layer is used to implement this function.
When the file descriptor is a socket, only the following ioctl() values are supported:
· FIONREAD returns the number of bytes of pending data already received in the socketns network buffer. · FIONBIO is an alternative way to set/clear non-blocking I/O status for a socket, equivalent to fcntl(fd,
F_SETFL, O_NONBLOCK, ...).

4.23.3 Netconn API
lwIP supports two lower level APIs as well as the BSD Sockets API: the Netconn API and the Raw API. The lwIP Raw API is designed for single threaded devices and is not supported in ESP-IDF. The Netconn API is used to implement the BSD Sockets API inside lwIP, and it can also be called directly from ESP-IDF apps. This API has lower resource usage than the BSD Sockets API, in particular it can send and receive data without needing to first copy it into internal lwIP buffers.
Important: Espressif does not test the Netconn API in ESP-IDF. As such, this functionality is enabled but not supported. Some functionality may only work correctly when used from the BSD Sockets API.
For more information about the Netconn API, consult lwip/lwip/src/include/lwip/api.h and this wiki page which is part of the unofficial lwIP Application Developers Manual.

4.23.4 lwIP FreeRTOS Task
lwIP creates a dedicated TCP/IP FreeRTOS task to handle socket API requests from other tasks. A number of configuration items are available to modify the task and the queues (omailboxesp) used to send data to/from the TCP/IP task:

Espressif Systems

1841

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· CONFIG_LWIP_TCPIP_RECVMBOX_SIZE · CONFIG_LWIP_TCPIP_TASK_STACK_SIZE · CONFIG_LWIP_TCPIP_TASK_AFFINITY
4.23.5 IPv6 Support
Both IPv4 and IPv6 are supported as dual stack and enabled by default (IPv6 may be disabled if itns not needed, see Minimum RAM usage). IPv6 support is limited to Stateless Autoconfiguration only, Stateful configuration is not supported in ESP-IDF (not in upstream lwip). IPv6 Address configuration is defined by means of these protocols or services:
· SLAAC IPv6 Stateless Address Autoconfiguration (RFC-2462) · DHCPv6 Dynamic Host Configuration Protocol for IPv6 (RFC-8415) None of these two types of address configuration is enabled by default, so the device uses only Link Local addresses or statically defined addresses.
Stateless Autoconfiguration Process
To enable address autoconfiguration using Router Advertisement protocol please enable: · CONFIG_LWIP_IPV6_AUTOCONFIG
This configuration option enables IPv6 autoconfiguration for all network interfaces (in contrast to the upstream lwIP, where the autoconfiguration needs to be explicitly enabled for each netif with netif>ip6_autoconfig_enabled=1
DHCPv6
DHCPv6 in lwIP is very simple and support only stateless configuration. It could be enabled using: · CONFIG_LWIP_IPV6_DHCP6
Since the DHCPv6 works only in its stateless configuration, the Stateless Autoconfiguration Process has to be enabled, too, by means of CONFIG_LWIP_IPV6_AUTOCONFIG. Moreover, the DHCPv6 needs to be explicitly enabled form the application code using
dhcp6_enable_stateless(netif);
DNS servers in IPv6 autoconfiguration
In order to autoconfigure DNS server(s), especially in IPv6 only networks, we have these two options · Recursive domain name system this belongs to the Neighbor Discovery Protocol (NDP), uses Stateless Autoconfiguration Process. Number of servers must be set CONFIG_LWIP_IPV6_RDNSS_MAX_DNS_SERVERS, this is option is disabled (set to 0) by default. · DHCPv6 stateless configuration uses DHCPv6 to configure DNS servers. Note that the this configuration assumes IPv6 Router Advertisement Flags (RFC-5175) to be set to ­ Managed Address Configuration Flag = 0 ­ Other Configuration Flag = 1
4.23.6 esp-lwip custom modifications
Additions
The following code is added which is not present in the upstream lwIP release:

Espressif Systems

1842

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Thread-safe sockets It is possible to close() a socket from a different thread to the one that created it. The close() call will block until any function calls currently using that socket from other tasks have returned. It is, however, not possible to delete a task while it is actively waiting on select() or poll() APIs. It is always necessary that these APIs exit before destroying the task, as this might corrupt internal structures and cause subsequent crashes of the lwIP. (These APIs allocate globally referenced callback pointers on stack, so that when the task gets destroyed before unrolling the stack, the lwIP would still hold pointers to the deleted stack)
On demand timers lwIP IGMP and MLD6 features both initialize a timer in order to trigger timeout events at certain times. The default lwIP implementation is to have these timers enabled all the time, even if no timeout events are active. This increases CPU usage and power consumption when using automatic light sleep mode. esp-lwip default behaviour is to set each timer oon demandpso it is only enabled when an event is pending. To return to the default lwIP behaviour (always-on timers), disable CONFIG_LWIP_TIMERS_ONDEMAND.
Lwip timers API When users are not using WiFi, these APIs provide users with the ability to turn off LwIP timer to reduce power consumption. The following API functions are supported. For full details see lwip/lwip/src/include/lwip/timeouts.h.
· sys_timeouts_init() · sys_timeouts_deinit()
Additional Socket Options · Some standard IPV4 and IPV6 multicast socket options are implemented (see Socket Options). · Possible to set IPV6-only UDP and TCP sockets with IPV6_V6ONLY socket option (normal lwIP is TCP only).
IP layer features · IPV4 source based routing implementation is different. · IPV4 mapped IPV6 addresses are supported.
Limitations
Calling send() or sendto() repeatedly on a UDP socket may eventually fail with errno equal to ENOMEM. This is a limitation of buffer sizes in the lower layer network interface drivers. If all driver transmit buffers are full then UDP transmission will fail. Applications sending a high volume of UDP datagrams who donnt wish for any to be dropped by the sender should check for this error code and re-send the datagram after a short delay. Increasing the number of TX buffers in the Wi-Fi project configuration may also help.
4.23.7 Performance Optimization
TCP/IP performance is a complex subject, and performance can be optimized towards multiple goals. The default settings of ESP-IDF are tuned for a compromise between throughput, latency, and moderate memory usage.
Maximum throughput
Espressif tests ESP-IDF TCP/IP throughput using the wifi/iperf example in an RF sealed enclosure. The wifi/iperf/sdkconfig.defaults file for the iperf example contains settings known to maximize TCP/IP throughput, usually at the expense of higher RAM usage. To get maximum TCP/IP throughput in an application at the expense of other factors then suggest applying settings from this file into the project sdkconfig.

Espressif Systems

1843

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Important: Suggest applying changes a few at a time and checking the performance each time with a particular application workload.
· If a lot of tasks are competing for CPU time on the system, consider that the lwIP task has configurable CPU affinity (CONFIG_LWIP_TCPIP_TASK_AFFINITY) and runs at fixed priority ESP_TASK_TCPIP_PRIO (18). Configure competing tasks to be pinned to a different core, or to run at a lower priority. See also Built-In Task Priorities.
· If using select() function with socket arguments only, disabling CONFIG_VFS_SUPPORT_SELECT will make select() calls faster.
· If there is enough free IRAM, select CONFIG_LWIP_IRAM_OPTIMIZATION to improve TX/RX throughput If using a Wi-Fi network interface, please also refer to Wi-Fi Buffer Usage.
Minimum latency
Except for increasing buffer sizes, most changes which increase throughput will also decrease latency by reducing the amount of CPU time spent in lwIP functions.
· For TCP sockets, lwIP supports setting the standard TCP_NODELAY flag to disable Naglens algorithm.
Minimum RAM usage
Most lwIP RAM usage is on-demand, as RAM is allocated from the heap as needed. Therefore, changing lwIP settings to reduce RAM usage may not change RAM usage at idle but can change it at peak.
· Reducing CONFIG_LWIP_MAX_SOCKETS reduces the maximum number of sockets in the system. This will also cause TCP sockets in the WAIT_CLOSE state to be closed and recycled more rapidly (if needed to open a new socket), further reducing peak RAM usage.
· Reducing CONFIG_LWIP_TCPIP_RECVMBOX_SIZE, CONFIG_LWIP_TCP_RECVMBOX_SIZE and CONFIG_LWIP_UDP_RECVMBOX_SIZE reduce memory usage at the expense of throughput, depending on usage.
· Disable CONFIG_LWIP_IPV6 can save about 39 KB for firmware size and 2KB RAM when system power up and 7KB RAM when TCPIP stack running. If there is no requirement for supporting IPV6 then it can be disabled to save flash and RAM footprint.
If using Wi-Fi, please also refer to Wi-Fi Buffer Usage.
Peak Buffer Usage The peak heap memory that lwIP consumes is the theoretically-maximum memory that the lwIP driver consumes. Generally, the peak heap memory that lwIP consumes depends on:
· the memory required to create a UDP connection: lwip_udp_conn · the memory required to create a TCP connection: lwip_tcp_conn · the number of UDP connections that the application has: lwip_udp_con_num · the number of TCP connections that the application has: lwip_tcp_con_num · the TCP TX window size: lwip_tcp_tx_win_size · the TCP RX window size: lwip_tcp_rx_win_size So, the peak heap memory that the LwIP consumes can be calculated with the following formula:
lwip_dynamic_peek_memory = (lwip_udp_con_num * lwip_udp_conn) + (lwip_tcp_con_num * (lwip_tcp_tx_win_size + lwip_tcp_rx_win_size + lwip_tcp_conn)) Some TCP-based applications need only one TCP connection. However, they may choose to close this TCP connection and create a new one when an error (such as a sending failure) occurs. This may result in multiple TCP connections existing in the system simultaneously, because it may take a long time for a TCP connection to close, according to the TCP state machine (refer to RFC793).

Espressif Systems

1844

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.24 OpenThread
OpenThread is a IP stack running on the 802.15.4 MAC layer which features mesh network and low power consumption.
4.24.1 Mode of the OpenThread stack
OpenThread can run under the following modes on Espressif chips:
Standalone node The full OpenThread stack and the application layer runs on the same chip. This mode is available on chips with 15.4 radio such as ESP32-H2.
Radio Co-Processor (RCP) The chip will be connected to another host running the OpenThread IP stack. It will send and received 15.4 packets on behalf of the host. This mode is available on chips with 15.4 radio such as ESP32-H2. The underlying transport between the chip and the host can be SPI or UART. For sake of latency, we recommend to use SPI as the underlying transport.
OpenThread host For chips without 15.4 radio, it can be connected to an RCP and run OpenThread under host mode. This mode enables OpenThread on Wi-Fi chips such as ESP32, ESP32-S2, ESP32-S3 and ESP32-C3. The following diagram shows how devices work under different modes:

Fig. 53: OpenThread device modes
4.24.2 How To Write an OpenThread Application
The OpenThread openthread/ot_cli example will be a good place to start at. It demonstrates basic OpenThread initialization and simple socket-based server and client.

Espressif Systems

1845

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Before OpenThread initialization
· s1.1 The main task calls esp_vfs_eventfd_register() to initialize the eventfd virtual filesystem. The eventfd file system is used for task notification in the OpenThread driver.
· s1.2 The main task calls nvs_flash_init() to initialize the NVS where the Thread network data is stored. · s1.3 Optional, The main task calls esp_netif_init() only when it wants to create the network interface
for Thread. · s1.4: The main task calls esp_event_loop_create() to create the system Event task and initialize an
application eventns callback function.
OpenThread stack initialization
· s2.1: Call esp_openthread_init() to initialize the OpenThread stack.
OpenThread network interface initialization
The whole stage is optional and only required if the application wants to create the network interface for Thread. - s3.1: Call esp_netif_new() with ESP_NETIF_DEFAULT_OPENTHREAD to create the interface. - s3.2: Call esp_openthread_netif_glue_init() to create the OpenThread interface handlers. - s3.3: Call esp_netif_attach() to attach the handlers to the interface.
The OpenThread main loop
· s4.3: Call esp_openthread_launch_mainloop() to launch the OpenThread main loop. Note that this is a busy loop and will not return until the OpenThread stack is terminated.
Calling OpenThread APIs
The OpenThread APIs are not thread-safe. When calling OpenThread APIs from other tasks, make sure to hold the lock with esp_openthread_lock_acquire() and release the lock with esp_openthread_lock_release() afterwards.
Deinitialization
The following steps are required to deintialize the OpenThread stack: - Call esp_netif_destroy() and esp_openthread_netif_glue_deinit() to deintialize the OpenThread network interface if you have created one. - Call esp_openthread_deinit() to deintialize the OpenThread stack.
4.24.3 The OpenThread border router
The OpenThread border router connects the Thread network with other IP networks. It will provide IPv6 connectivity, service registration and commission functionality. To launch an OpenThread border router on a ESP chip, you need to connect an RCP to a Wi-Fi capable chip such as ESP32. Call esp_openthread_border_router_init() during the initialization will launch all the border routing functionalities. You may refer to the openthread/ot_br example and the README for further border router details.
4.25 Partition Tables

Espressif Systems

1846

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

4.25.1 Overview
A single ESP32-S3ns flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to (default offset) 0x8000 in the flash.
Partition table length is 0xC00 bytes (maximum 95 partition table entries). An MD5 checksum, which is used for checking the integrity of the partition table, is appended after the table data.
Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded.
The simplest way to use the partition table is to open the project configuration menu (idf.py menuconfig) and choose one of the simple predefined partition tables under CONFIG_PARTITION_TABLE_TYPE:
·oSingle factory app, no OTAp ·oFactory app, two OTA definitionsp
In both cases the factory app is flashed at offset 0x10000. If you execute idf.py partition-table then it will print a summary of the partition table.

4.25.2 Built-in Partition Tables

Here is the summary printed for the oSingle factory app, no OTApconfiguration:

# ESP-IDF Partition Table

# Name, Type, SubType, Offset, Size, Flags

nvs,

data, nvs,

0x9000, 0x6000,

phy_init, data, phy,

0xf000, 0x1000,

factory, app, factory, 0x10000, 1M,

· At a 0x10000 (64 KB) offset in the flash is the app labelled ofactoryp. The bootloader will run this app by default.
· There are also two data regions defined in the partition table for storing NVS library partition and PHY init data.
Here is the summary printed for the oFactory app, two OTA definitionspconfiguration:

# ESP-IDF Partition Table

# Name, Type, SubType, Offset, Size, Flags

nvs,

data, nvs,

0x9000, 0x4000,

otadata, data, ota,

0xd000, 0x2000,

phy_init, data, phy,

0xf000, 0x1000,

factory, app, factory, 0x10000, 1M,

ota_0, app, ota_0, 0x110000, 1M,

ota_1, app, ota_1, 0x210000, 1M,

· There are now three app partition definitions. The type of the factory app (at 0x10000) and the next two oOTApapps are all set to oappp, but their subtypes are different. · There is also a new ootadatapslot, which holds the data for OTA updates. The bootloader consults this data
in order to know which app to execute. If oota datapis empty, it will execute the factory app.

4.25.3 Creating Custom Tables
If you choose oCustom partition table CSVpin menuconfig then you can also enter the name of a CSV file (in the project directory) to use for your partition table. The CSV file can describe any number of definitions for the table you need.
The CSV format is the same format as printed in the summaries shown above. However, not all fields are required in the CSV. For example, here is the oinputpCSV for the OTA partition table:

Espressif Systems

1847

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

# Name, Type, SubType, Offset, Size,

nvs,

data, nvs,

0x9000, 0x4000

otadata, data, ota,

0xd000, 0x2000

phy_init, data, phy,

0xf000, 0x1000

factory, app, factory, 0x10000, 1M

ota_0, app, ota_0, ,

1M

ota_1, app, ota_1, ,

1M

nvs_key, data, nvs_keys, ,

0x1000

Flags

· Whitespace between fields is ignored, and so is any line starting with # (comments). · Each non-comment line in the CSV file is a partition definition. · The oOffsetpfield for each partition is empty. The gen_esp32part.py tool fills in each blank offset, starting
after the partition table and making sure each partition is aligned correctly.

Name field
Name field can be any meaningful name. It is not significant to the ESP32-S3. Names longer than 16 characters will be truncated.

Type field
Partition type field can be specified as app (0x00) or data (0x01). Or it can be a number 0-254 (or as hex 0x000xFE). Types 0x00-0x3F are reserved for ESP-IDF core functions. If your app needs to store data in a format not already supported by ESP-IDF, then please add a custom partition type value in the range 0x40-0xFE. See esp_partition_type_t for the enum definitions for app and data partitions. If writing in C++ then specifying a application-defined partition type requires casting an integer to esp_partition_type_t in order to use it with the partition API. For example:
static const esp_partition_type_t APP_PARTITION_TYPE_A = (esp_partition_type_ t)0x40;
The ESP-IDF bootloader ignores any partition types other than app (0x00) and data (0x01).

SubType
The 8-bit subtype field is specific to a given partition type. ESP-IDF currently only specifies the meaning of the subtype field for app and data partition types.
See enum esp_partition_subtype_t for the full list of subtypes defined by ESP-IDF, including the following:
· When type is app, the subtype field can be specified as factory (0x00), ota_0 (0x10) lota_15 (0x1F) or test (0x20). ­ factory (0x00) is the default app partition. The bootloader will execute the factory app unless there it sees a partition of type data/ota, in which case it reads this partition to determine which OTA image to boot.  OTA never updates the factory partition.  If you want to conserve flash usage in an OTA project, you can remove the factory partition and use ota_0 instead. ­ ota_0 (0x10) lota_15 (0x1F) are the OTA app slots. When OTA is in use, the OTA data partition configures which app slot the bootloader should boot. When using OTA, an application should have at least two OTA application slots (ota_0 & ota_1). Refer to the OTA documentation for more details. ­ test (0x20) is a reserved subtype for factory test procedures. It will be used as the fallback boot partition if no other valid app partition is found. It is also possible to configure the bootloader to read a GPIO input during each boot, and boot this partition if the GPIO is held low, see Boot from Test Firmware.

Espressif Systems

1848

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· When type is data, the subtype field can be specified as ota (0x00), phy (0x01), nvs (0x02), nvs_keys (0x04), or a range of other component-specific subtypes (see subtype enum). ­ ota (0) is the OTA data partition which stores information about the currently selected OTA app slot. This partition should be 0x2000 bytes in size. Refer to the OTA documentation for more details. ­ phy (1) is for storing PHY initialisation data. This allows PHY to be configured per-device, instead of in firmware.  In the default configuration, the phy partition is not used and PHY initialisation data is compiled into the app itself. As such, this partition can be removed from the partition table to save space.  To load PHY data from this partition, open the project configuration menu (idf.py menuconfig) and enable CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION option. You will also need to flash your devices with phy init data as the esp-idf build system does not do this automatically. ­ nvs (2) is for the Non-Volatile Storage (NVS) API.  NVS is used to store per-device PHY calibration data (different to initialisation data).  NVS is used to store WiFi data if the esp_wifi_set_storage(WIFI_STORAGE_FLASH) initialisation function is used.  The NVS API can also be used for other application data.  It is strongly recommended that you include an NVS partition of at least 0x3000 bytes in your project.  If using NVS API to store a lot of data, increase the NVS partition size from the default 0x6000 bytes. ­ nvs_keys (4) is for the NVS key partition. See Non-Volatile Storage (NVS) API for more details.  It is used to store NVS encryption keys when NVS Encryption feature is enabled.  The size of this partition should be 4096 bytes (minimum partition size). ­ There are other predefined data subtypes for data storage supported by ESP-IDF. These include FAT filesystem (ESP_PARTITION_SUBTYPE_DATA_FAT), SPIFFS (ESP_PARTITION_SUBTYPE_DATA_SPIFFS), etc. Other subtypes of data type are reserved for future ESP-IDF uses.
· If the partition type is any application-defined value (range 0x40-0xFE), then subtype field can be any value chosen by the application (range 0x00-0xFE). Note that when writing in C++, an application-defined subtype value requires casting to type esp_partition_subtype_t in order to use it with the partition API.
Offset & Size
Partitions with blank offsets in the CSV file will start after the previous partition, or after the partition table in the case of the first partition.
Partitions of type app have to be placed at offsets aligned to 0x10000 (64K). If you leave the offset field blank, gen_esp32part.py will automatically align the partition. If you specify an unaligned offset for an app partition, the tool will return an error.
Sizes and offsets can be specified as decimal numbers, hex numbers with the prefix 0x, or size multipliers K or M (1024 and 1024*1024 bytes).
If you want the partitions in the partition table to work relative to any placement (CONFIG_PARTITION_TABLE_OFFSET) of the table itself, leave the offset field (in CSV file) for all partitions blank. Similarly, if changing the partition table offset then be aware that all blank partition offsets may change to match, and that any fixed offsets may now collide with the partition table (causing an error).
Flags
Only one flag is currently supported, encrypted. If this field is set to encrypted, this partition will be encrypted if Flash Encryption is enabled.
Note: app type partitions will always be encrypted, regardless of whether this flag is set or not.

Espressif Systems

1849

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.25.4 Generating Binary Partition Table
The partition table which is flashed to the ESP32-S3 is in a binary format, not CSV. The tool partition_table/gen_esp32part.py is used to convert between CSV and binary formats. If you configure the partition table CSV name in the project configuration (idf.py menuconfig) and then build the project or run idf.py partition-table, this conversion is done as part of the build process. To convert CSV to Binary manually: python gen_esp32part.py input_partitions.csv binary_partitions.bin
To convert binary format back to CSV manually: python gen_esp32part.py binary_partitions.bin input_partitions.csv
To display the contents of a binary partition table on stdout (this is how the summaries displayed when running idf.py partition-table are generated: python gen_esp32part.py binary_partitions.bin
4.25.5 Partition Size Checks
The ESP-IDF build system will automatically check if generated binaries fit in the available partition space, and will fail with an error if a binary is too large. Currently these checks are performed for the following binaries:
· Bootloader binary must fit in space before partition table (see Bootloader Size). · App binary should fit in at least one partition of typeoappp. If the app binary doesnnt fit in any app partition,
the build will fail. If it only fits in some of the app partitions, a warning is printed about this.
Note: Although the build process will fail if the size check returns an error, the binary files are still generated and can be flashed (although they may not work if they are too large for the available space.)
MD5 checksum
The binary format of the partition table contains an MD5 checksum computed based on the partition table. This checksum is used for checking the integrity of the partition table during the boot. The MD5 checksum generation can be disabled by the --disable-md5sum option of gen_esp32part.py or by the CONFIG_PARTITION_TABLE_MD5 option.
4.25.6 Flashing the partition table
· idf.py partition-table-flash: will flash the partition table with esptool.py. · idf.py flash: Will flash everything including the partition table. A manual flashing command is also printed as part of idf.py partition-table output.
Note: Note that updating the partition table doesnnt erase data that may have been stored according to the old partition table. You can use idf.py erase-flash (or esptool.py erase_flash) to erase the entire flash contents.

Espressif Systems

1850

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.25.7 Partition Tool (parttool.py)
The component partition_table provides a tool parttool.py for performing partition-related operations on a target device. The following operations can be performed using the tool:
· reading a partition and saving the contents to a file (read_partition) · writing the contents of a file to a partition (write_partition) · erasing a partition (erase_partition) · retrieving info such as name, offset, size and flag (oencryptedp) of a given partition (get_partition_info) The tool can either be imported and used from another Python script or invoked from shell script for users wanting to perform operation programmatically. This is facilitated by the toolns Python API and command-line interface, respectively.
Python API
Before anything else, make sure that the parttool module is imported.
import sys import os
idf_path = os.environ["IDF_PATH"] # get value of IDF_PATH from environment parttool_dir = os.path.join(idf_path, "components", "partition_table") # parttool. py lives in $IDF_PATH/components/partition_table
sys.path.append(parttool_dir) # this enables Python to find parttool module from parttool import * # import all names inside parttool module
The starting point for using the toolns Python API to do is create a ParttoolTarget object:
# Create a partool.py target device connected on serial port /dev/ttyUSB1 target = ParttoolTarget("/dev/ttyUSB1")
The created object can now be used to perform operations on the target device:
# Erase partition with name 'storage' target.erase_partition(PartitionName("storage"))
# Read partition with type 'data' and subtype 'spiffs' and save to file 'spiffs.bin ' target.read_partition(PartitionType("data", "spiffs"), "spiffs.bin")
# Write to partition 'factory' the contents of a file named 'factory.bin' target.write_partition(PartitionName("factory"), "factory.bin")
# Print the size of default boot partition storage = target.get_partition_info(PARTITION_BOOT_DEFAULT) print(storage.size)
The partition to operate on is specified using PartitionName or PartitionType or PARTITION_BOOT_DEFAULT. As the name implies, these can be used to refer to partitions of a particular name, type-subtype combination, or the default boot partition. More information on the Python API is available in the docstrings for the tool.
Command-line Interface
The command-line interface of parttool.py has the following structure:

Espressif Systems

1851

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
parttool.py [command-args] [subcommand] [subcommand-args]
- command-args - These are arguments that are needed for executing the main command (parttool.py), mostly pertaining to the target device - subcommand - This is the operation to be performed - subcommand-args - These are arguments that are specific to the chosen operation
# Erase partition with name 'storage' parttool.py --port "/dev/ttyUSB1" erase_partition --partition-name=storage
# Read partition with type 'data' and subtype 'spiffs' and save to file 'spiffs.bin ' parttool.py --port "/dev/ttyUSB1" read_partition --partition-type=data --partitionsubtype=spiffs --output "spiffs.bin"
# Write to partition 'factory' the contents of a file named 'factory.bin' parttool.py --port "/dev/ttyUSB1" write_partition --partition-name=factory "factory.bin"
# Print the size of default boot partition parttool.py --port "/dev/ttyUSB1" get_partition_info --partition-boot-default -info size
More information can be obtained by specifying help as argument:
# Display possible subcommands and show main command argument descriptions parttool.py --help
# Show descriptions for specific subcommand arguments parttool.py [subcommand] --help
4.26 Performance
ESP-IDF ships with default settings that are designed for a trade-off between performance, resource usage, and available functionality. These guides describe how to optimize a firmware application for a particular aspect of performance. Usually this involves some trade-off in terms of limiting available functions, or swapping one aspect of performance (such as execution speed) for another (such as RAM usage).
4.26.1 How to Optimize Performance
1. Decide what the performance-critical aspects of your application are (for example: a particular response time to a certain network operation, a particular startup time limit, particular peripheral data throughput, etc.).
2. Find a way to measure this performance (some methods are outlined in the guides below). 3. Modify the code and project configuration and compare the new measurement to the old measurement. 4. Repeat step 3 until the performance meets the requirements set out in step 1.
4.26.2 Guides
Maximizing Execution Speed
Overview Optimizing execution speed is a key element of software performance. Code that executes faster can also have other positive effects, like reducing overall power consumption. However, improving execution speed may have trade-offs with other aspects of performance such as Minimizing Binary Size.

Espressif Systems

1852

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Choose What To Optimize If a function in the application firmware is executed once per week in the background, it may not matter if that function takes 10 ms or 100 ms to execute. If a function is executed constantly at 10 Hz, it matters greatly if it takes 10 ms or 100 ms to execute.
Most application firmwares will only have a small set of functions which require optimal performance. Perhaps those functions are executed very often, or have to meet some application requirements for latency or throughput. Optimization efforts should be targeted at these particular functions.

Measuring Performance The first step to improving something is to measure it.

Basic Performance Measurements If measuring performance relative to an external interaction with the world, you may be able to measure this directly (for example see the examples wifi/iperf and ethernet/iperf for measuring general network performance, or you can use an oscilloscope or logic analyzer to measure timing of an interaction with a device peripheral.)
Otherwise, one way to measure performance is to augment the code to take timing measurements:
#include "esp_timer.h"
void measure_important_function(void) { const unsigned MEASUREMENTS = 5000; uint64_t start = esp_timer_get_time();
for (int retries = 0; retries < MEASUREMENTS; retries++) { important_function(); // This is the thing you need to measure
}
uint64_t end = esp_timer_get_time();
printf("%u iterations took %ull milliseconds (%ull microseconds per invocation)\n",
MEASUREMENTS, (end - start)/1000, (end - start)/MEASUREMENTS); }
Executing the target multiple times can help average out factors like RTOS context switches, overhead of measurements, etc.
· Using esp_timer_get_time() generatesowall clockptimestamps with microsecond precision, but has moderate overhead each time the timing functions are called.
· Itns also possible to use the standard Unix gettimeofday() and utime() functions, although the overhead is slightly higher.
· Otherwise, including hal/cpu_hal.h and calling the HAL function cpu_hal_get_cycle_count() will return the number of CPU cycles executed. This function has lower overhead than the others. It is good for measuring very short execution times with high precision. The CPU cycles are counted per-core, so only use this method from an interrupt handler, or a task that is pinned to a single core.
· If making omicrobenchmarksp(i.e. benchmarking only a very small routine of code that runs in less than 1-2 milliseconds) then flash cache performance can sometimes cause big variations in timing measurements depending on the binary. This happens because binary layout can cause different patterns of cache misses in a particular sequence of execution. If the test code is larger then this effect usually averages out. Executing a small function multiple times when benchmarking can help reduce the impact of flash cache misses. Alternatively, move this code to IRAM (see Targeted Optimizations).

External Tracing The Application Level Tracing library allows measuring code execution with minimal impact on the code itself.

Tasks If the option CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS is enabled then the FreeRTOS API vTaskGetRunTimeStats() can be used to retrieve runtime information about the processor time used by each FreeRTOS task.

Espressif Systems

1853

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
SEGGER SystemView is an excellent tool for visualizing task execution and looking for performance issues or improvements in the system as a whole.
Improving Overall Speed The following optimizations will improve the execution of nearly all code - including boot times, throughput, latency, etc:
· Set CONFIG_ESPTOOLPY_FLASHMODE to QIO or QOUT mode (Quad I/O). Both will almost double the speed at which code is loaded or executed from flash compared to the default DIO mode. QIO is slightly faster than QOUT if both are supported. Note that both the flash chip model and the electrical connections between the ESP32-S3 and the flash chip must support quad I/O modes or the SoC will not work correctly.
· Set CONFIG_COMPILER_OPTIMIZATION tooOptimize for performance (-O2)p. This may slightly increase binary size compared to the default setting, but will almost certainly increase performance of some code. Note that if your code contains C or C++ Undefined Behaviour then increasing the compiler optimization level may expose bugs that otherwise are not seen.
· Avoid using floating point arithmetic (float). Even though ESP32-S3 has a single precision hardware floating point unit, floating point calculations are always slower than integer calculations. If possible then use fixed point representations, a different method of integer representation, or convert part of the calculation to be integer only before switching to floating point.
· Avoid using double precision floating point arithmetic (double). These calculations are emulated in software and are very slow. If possible then use an integer-based representation, or single-precision floating point.
Reduce Logging Overhead Although standard output is buffered, itns possible for an application to be limited by the rate at which it can print data to log output once buffers are full. This is particularly relevant for startup time if a lot of output is logged, but can happen at other times as well. There are multiple ways to solve this problem:
· Reduce the volume of log output by lowering the app CONFIG_LOG_DEFAULT_LEVEL (the equivalent bootloader setting is CONFIG_BOOTLOADER_LOG_LEVEL). This also reduces the binary size, and saves some CPU time spent on string formatting.
· Increase the speed of logging output by increasing the CONFIG_ESP_CONSOLE_UART_BAUDRATE. (Unless using internal USB-CDC for serial console, in which case the serial throughput doesnnt depend on the configured baud rate.)
Not Recommended The following options will also increase execution speed, but are not recommended as they also reduce the debuggability of the firmware application and may increase the severity of any bugs.
· Set CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL to disabled. This also reduces firmware binary size by a small amount. However, it may increase the severity of bugs in the firmware including securityrelated bugs. If necessary to do this to optimize a particular function, consider adding #define NDEBUG in the top of that single source file instead.
Targeted Optimizations The following changes will increase the speed of a chosen part of the firmware application:
· Move frequently executed code to IRAM. By default, all code in the app is executed from flash cache. This means that itns possible for the CPU to have to wait on aocache misspwhile the next instructions are loaded from flash. Functions which are copied into IRAM are loaded once at boot time, and then will always execute at full speed. IRAM is a limited resource, and using more IRAM may reduce available DRAM, so a strategic approach is needed when moving code to IRAM. See IRAM (Instruction RAM) for more information.
· Jump table optimizations can be re-enabled for individual source files that donnt need to be placed in IRAM. For hot paths in large switch cases this will improve performance. For instructions on how to add the -fjump-tables ftree-switch-conversion options when compiling individual source files, see Controlling Component Compilation
Improving Startup Time In addition to the overall performance improvements shown above, the following options can be tweaked to specifically reduce startup time:

Espressif Systems

1854

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· Minimizing the CONFIG_LOG_DEFAULT_LEVEL and CONFIG_BOOTLOADER_LOG_LEVEL has a large impact on startup time. To enable more logging after the app starts up, set the CONFIG_LOG_MAXIMUM_LEVEL as well and then call esp_log_set_level() to restore higher level logs. The system/startup_time main function shows how to do this.
· If using deep sleep, setting CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP allows a faster wake from sleep. Note that if using Secure Boot this represents a security compromise, as Secure Boot validation will not be performed on wake.
· Setting CONFIG_BOOTLOADER_SKIP_VALIDATE_ON_POWER_ON will skip verifying the binary on every boot from power-on reset. How much time this saves depends on the binary size and the flash settings. Note that this setting carries some risk if the flash becomes corrupt unexpectedly. Read the help text of the config item for an explanation and recommendations if using this option.
· Itns possible to save a small amount of time during boot by disabling RTC slow clock calibration. To do so, set CONFIG_ESP32S3_RTC_CLK_CAL_CYCLES to 0. Any part of the firmware that uses RTC slow clock as a timing source will be less accurate as a result.
The example project system/startup_time is pre-configured to optimize startup time. The files system/startup_time/sdkconfig.defaults and system/startup_time/sdkconfig.defaults.esp32s3 contain all of these settings. You can append these to the end of your projectns own sdkconfig file to merge the settings, but please read the documentation for each setting first.
Task Priorities As ESP-IDF FreeRTOS is a real-time operating system, itns necessary to ensure that high throughput or low latency tasks are granted a high priority in order to run immediately. Priority is set when calling xTaskCreate() or xTaskCreatePinnedToCore() and can be changed at runtime by calling vTaskPrioritySet().
Itns also necessary to ensure that tasks yield CPU (by calling vTaskDelay(), sleep(), or by blocking on semaphores, queues, task notifications, etc) in order to not starve lower priority tasks and cause problems for the overall system. The Task Watchdog Timer provides a mechanism to automatically detect if task starvation happens, however note that a Task WDT timeout does not always indicate a problem (sometimes the correct operation of the firmware requires some long-running computation). In these cases tweaking the Task WDT timeout or even disabling the Task WDT may be necessary.
Built-In Task Priorities ESP-IDF starts a number of system tasks at fixed priority levels. Some are automatically started during the boot process, some are started only if the application firmware initializes a particular feature. To optimize performance, structure application task priorities so that they are not delayed by system tasks, while also not starving system tasks and impacting other functions of the system.
This may require splitting up a particular task. For example, perform a time-critical operation in a high priority task or an interrupt handler and do the non-time-critical part in a lower priority task.
Header components/esp_system/include/esp_task.h contains macros for the priority levels used for built-in ESP-IDF tasks system.
Common priorities are:
· Main task that executes app_main function has minimum priority (1). This task is pinned to Core 0 by default (configurable).
· High Resolution Timer system task to manage high precision timer events and execute callbacks has high priority (22, ESP_TASK_TIMER_PRIO). This task is pinned to Core 0.
· FreeRTOS Timer Task to handle FreeRTOS timer callbacks is created when the scheduler initializes and has minimum task priority (1, configurable). This task is pinned to Core 0.
· Event Handling system task to manage the default system event loop and execute callbacks has high priority (20, ESP_TASK_EVENT_PRIO) and pinned to Core 0. This configuration is only used if the application calls esp_event_loop_create_default(), itns possible to call esp_event_loop_create() with a custom task configuration instead.
· lwIP TCP/IP task has high priority (18, ESP_TASK_TCPIP_PRIO) and is not pinned to any core (configurable).
· Wi-Fi Driver task has high priority (23) and is pinned to Core 0 by default (configurable).

Espressif Systems

1855

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· Wi-Fi wpa_supplicant component may create dedicated tasks while the Wi-Fi Protected Setup (WPS), WPA2 EAP-TLS, Device Provisioning Protocol (DPP) or BSS Transition Management (BTM) features are in use. These tasks all have low priority (2) and are not pinned to any core.
· Bluetooth Controller task has high priority (23, ESP_TASK_BT_CONTROLLER_PRIO) and is pinned to Core 0 by default (configurable). The Bluetooth Controller needs to respond to requests with low latency, so it should always be close to the highest priority task assigned to a single CPU.
· NimBLE Bluetooth Host host task has high priority (21) and is pinned to Core 0 by default (configurable).
­ Stack event callback task (oBTCp) has high priority (19). ­ Stack BTU layer task has high priority (20). ­ Host HCI host task has high priority (22). All Bluedroid Tasks are pinned to the same core, which is Core 0 by default (configurable). · The Ethernet driver creates a task for the MAC to receive Ethernet frames. If using the default config ETH_MAC_DEFAULT_CONFIG then the priority is medium-high (15) and the task is not pinned to any core. These settings can be changed by passing a custom eth_mac_config_t struct when initializing the Ethernet MAC. · If using the mDNS component, it creates a task with default low priority 1 (configurable) and pinned to CPU0 (configurable). · If using the MQTT component, it creates a task with default priority 5 (configurable, depends on CONFIG_MQTT_USE_CUSTOM_CONFIG) and not pinned to any core (configurable).
Choosing application task priorities With a few exceptions (most importantly the lwIP TCP/IP task), in the default configuration most built-in tasks are pinned to Core 0. This makes it quite easy for the application to place high priority tasks on Core 1. Using priority 19 or higher will guarantee an application task can run on Core 1 without being preempted by any built-in task. To further isolate the tasks running on each CPU, configure the lwIP task to only run on Core 0 instead of either core (this may reduce total TCP/IP throughput depending on what other tasks are running).
In general, itns not recommended to set task priorities on Core 0 higher than the built-in Wi-Fi/BT operations as starving them of CPU may make the system unstable. Choosing priority 19 and Core 0 will allow lower layer Wi-Fi/BT functionality to run without delays, but still pre-empts the lwIP TCP/IP stack and other less time-critical internal functionality - this is an option for time-critical tasks that donnt perform network operations. Any task that does TCP/IP network operations should run at lower priority than the lwIP TCP/IP task (18) to avoid priority inversion issues.
Note: Setting a task to always run in preference to built-in ESP-IDF tasks does not require pinning to Core 1. The task can be left unpinned - at priority 17 or lower - to optionally run on Core 0 as well, if no higher priority built-in task is running there. Using unpinned tasks can improve the overall CPU utilization, however it makes reasoning about task scheduling more complex.
Note: Task execution is always completely suspended when writing to the built-in SPI flash chip. Only IRAM-Safe Interrupt Handlers will continue executing.

Improving Interrupt Performance ESP-IDF supports dynamic Interrupt allocation with interrupt preemption. Each interrupt in the system has a priority, and higher priority interrupts will preempt lower priority ones.
Interrupt handlers will execute in preference to any task (provided the task is not inside a critical section). For this reason, itns important to minimize the amount of time spent executing in an interrupt handler.
To obtain the best performance for a particular interrupt handler:
· Assign more important interrupts a higher priority using a flag such as ESP_INTR_FLAG_LEVEL2 or ESP_INTR_FLAG_LEVEL3 when calling esp_intr_alloc().
· Assign the interrupt on a CPU where built-in Wi-Fi/BT tasks are not configured to run (this means assigning on Core 1 by default, see Built-In Task Priorities). Interrupts are assigned on the same CPU where the esp_intr_alloc() function call is made.

Espressif Systems

1856

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

· If younre sure the entire interrupt handler can run from IRAM (see IRAM-Safe Interrupt Handlers) then set the ESP_INTR_FLAG_IRAM flag when calling esp_intr_alloc() to assign the interrupt. This prevents it being temporarily disabled if the application firmware writes to the internal SPI flash.
· Even if the interrupt handler is not IRAM safe, if it is going to be executed frequently then consider moving the handler function to IRAM anyhow. This minimizes the chance of a flash cache miss when the interrupt code is executed (see Targeted Optimizations). Itns possible to do this without adding the ESP_INTR_FLAG_IRAM flag to mark the interrupt as IRAM-safe, if only part of the handler is guaranteed to be in IRAM.

Improving Network Speed
· For Wi-Fi, see How to improve Wi-Fi performance and Wi-Fi Buffer Usage · For lwIP TCP/IP (Wi-Fi and Ethernet), see Performance Optimization · The wifi/iperf example contains a configuration that is heavily optimized for Wi-Fi TCP/IP through-
put. Append the contents of the files wifi/iperf/sdkconfig.defaults, wifi/iperf/sdkconfig.defaults.esp32s3 and wifi/iperf/sdkconfig.ci.99 to your project sdkconfig file in order to add all of these options. Note that some of these options may have trade-offs in terms of reduced debuggability, increased firmware size, increased memory usage, or reduced performance of other features. To get the best result, read the documentation pages linked above and use this information to determine exactly which options are best suited for your app.

Minimizing Binary Size
The ESP-IDF build system compiles all source files in the project and ESP-IDF, but only functions and variables that are actually referenced by the program are linked into the final binary. In some cases, it is necessary to reduce the total size of the firmware binary (for example, in order to fit it into the available flash partition size). The first step to reducing the total firmware binary size is measuring what is causing the size to increase.

Measuring Static Sizes To optimize both firmware binary size and memory usage itns necessary to measure statically allocated RAM (odatap, obssp), code (otextp) and read-only data (orodatap) in your project.
Using the idf.py sub-commands size, size-components and size-files provides a summary of memory used by the project:

Size Summary (idf.py size)

$ idf.py size

[...]

Total sizes:

DRAM .data size: 11584 bytes

DRAM .bss size: 19624 bytes

Used static DRAM:

0 bytes (

0 available, nan% used)

Used static IRAM:

0 bytes (

0 available, nan% used)

Used stat D/IRAM: 136276 bytes ( 519084 available, 20.8% used)

Flash code: 630508 bytes

Flash rodata: 177048 bytes

Total image size:~ 924208 bytes (.bin may be padded larger)

This output breaks down the size of all static memory regions in the firmware binary:
· DRAM .data size is statically allocated RAM that is assigned to non-zero values at startup. This uses RAM (DRAM) at runtime and also uses space in the binary file.
· DRAM .bss size is statically allocated RAM that is assigned zero at startup. This uses RAM (DRAM) at runtime but doesnnt use any space in the binary file.
· Used static DRAM, Used static IRAM - these options are kept for compatibility with ESP32 target, and currently read 0.
· Used stat D/IRAM - This is total internal RAM usage, the sum of static DRAM .data + .bss, and also static IRAM (Instruction RAM) used by the application for executable code. The available size is the estimated amount of DRAM which will be available as heap memory at runtime (due to metadata overhead

Espressif Systems

1857

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

and implementation constraints, and heap allocations done by ESP-IDF during startup, the actual free heap at startup will be lower than this). · Flash code is the total size of executable code executed from flash cache (IROM). This uses space in the binary file. · Flash rodata is the total size of read-only data loaded from flash cache (DROM). This uses space in the binary file. · Total image size is the estimated total binary file size, which is the total of all the used memory types except for .bss.

Component Usage Summary (idf.py size-components) The summary output provided by idf.py size does not give enough detail to find the main contributor to excessive binary size. To analyze in more detail, use idf.py size-components

$ idf.py size-components

[...]

Total sizes:

DRAM .data size: 14956 bytes

DRAM .bss size: 15808 bytes

Used static DRAM: 30764 bytes ( 149972 available, 17.0% used)

Used static IRAM: 83918 bytes ( 47154 available, 64.0% used)

Flash code: 559943 bytes

Flash rodata: 176736 bytes

Total image size:~ 835553 bytes (.bin may be padded larger)

Per-archive contributions to ELF file:

Archive File DRAM .data & .bss & other IRAM D/IRAM Flash code &

rodata Total libnet80211.a

1267 6044

0 5490

0

107445 

18484 138730 liblwip.a

21 3838

0

0

0

97465 

16116 117440 libmbedtls.a

60 524

0

0

0

27655 

69907 98146 libmbedcrypto.a

64

81

0

30

0

76645 

11661 88481 libpp.a

2427 1292

0 20851

0

37208 

4708 66486

libc.a

4

0

0

0

0

57056 

6455 63515 libphy.a

1439 715

0 7798

0

33074



 0 43026 libwpa_supplicant.a

12 848

0

0

0

35505 

1446 37811

libfreertos.a

3104 740

0 15711

0

367 

4228 24150 libnvs_flash.a

0

24

0

0

0

14347 

2924 17295 libspi_flash.a

1562 294

0 8851

0

1840 

1913 14460 libesp_system.a

245 206

0 3078

0

5990 

3817 13336 libesp-tls.a

0

4

0

0

0

5637 

3524

9165

[... removed some lines here ...]

libtcpip_adapter.a

0

17

0

0

0

216



0

233 libesp_rom.a

0

0

0 112

0

0



0

112 libcxx.a

0

0

0

0

0

47



0

47

(exe)

0

0

0

3

0

3



 12

18

(continues on next page)

Espressif Systems

1858

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

0 0 0

libesp_pm.a 8 libesp_eth.a 0
libmesh.a 0

0

0

0

0

0

0

0

0

0

0

0

0

(continued from previous page)

0

8



0

0



0

0



The first lines of output from idf.py size-components are the same as idf.py size. After this a table is printed ofoper-archive contributions to ELF filep. This means how much each static library archive has contributed to the final binary size.
Generally, one static library archive is built per component, although some are binary libraries included by a particular component (for example, libnet80211.a is included by esp_wifi component). There are also toolchain libraries such as libc.a and libgcc.a listed here, these provide Standard C/C++ Library and toolchain built-in functionality.
If your project is simple and only has a omainpcomponent, then all of the projectns code will be shown under libmain.a. If your project includes its own components (see Build System), then they will each be shown on a separate line.
The table is sorted in descending order of the total contribution to the binary size.
The columns are as follows:
· DRAM .data & .bss & other - .data and .bss are the same as for the totals shown above (static variables, these both reduce total available RAM at runtime but .bss doesnnt contribute to the binary file size). ootherp is a column for any custom section types that also contribute to RAM size (usually this value is 0).
· IRAM - is the same as for the totals shown above (code linked to execute from IRAM, uses space in the binary file and also reduces DRAM available as heap at runtime.
· Flash code & rodata - these are the same as the totals above, IROM and DROM space accessed from flash cache that contribute to the binary size.

Source File Usage Summary (idf.py size-files) For even more detail, run idf.py size-files to get a summary of the contribution each object file has made to the final binary size. Each object file corresponds to a single source file.

$ idf.py size-files

[...]

Total sizes:

DRAM .data size: 14956 bytes

DRAM .bss size: 15808 bytes

Used static DRAM: 30764 bytes ( 149972 available, 17.0% used)

Used static IRAM: 83918 bytes ( 47154 available, 64.0% used)

Flash code: 559943 bytes

Flash rodata: 176736 bytes

Total image size:~ 835553 bytes (.bin may be padded larger)

Per-file contributions to ELF file:

Object File DRAM .data & .bss & other IRAM D/IRAM Flash code &

rodata Total

x509_crt_bundle.S.o

0

0

0

0

0

0

64212 64212

wl_cnx.o

2 3183

0 221

0

13119 

3286 19811

phy_chip_v7.o

721 614

0 1642

0

16820



 0 19797

ieee80211_ioctl.o

740

96

0 437

0

15325 

2627 19225

pp.o

1142

45

0 8871

0

5030



537 15625

ieee80211_output.o

2

20

0 2118

0

11617



914 14671

(continues on next page)

Espressif Systems

1859

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

ieee80211_sta.o

1

41

2218 14616

lib_a-vfprintf.o

0

0

752 14581

lib_a-svfprintf.o

0

0

752 14003

ssl_tls.c.o

60

0

463 13292

sockets.c.o

0 648

1030 12774

nd6.c.o

8 932

314 12769

phy_chip_v7_cal.o

477

53

 0 12590

pm.o

32 364

782 11639

ieee80211_scan.o

18 288

1921 11116

lib_a-svfiprintf.o

0

0

1206 10860

lib_a-vfiprintf.o

0

0

734 10803

ieee80211_ht.o

0

4

898 10716

phy_chip_v7_ana.o

241

48

 0 10623

bignum.c.o

0

4

752 10408

tcp_in.c.o

0

52

1282 10084

trc.o

664

88

1108

9831

tasks.c.o

8 704

1475

9781

ecp_curves.c.o

28

0

2325

9737

ecp.c.o

0

64

286

9214

ieee80211_hostap.o

1

41

585

9205

wdev.o

121 125

580

9009

tcp_out.c.o

0

0

2161

7847

tcp.c.o

2

26

1617

7806

ieee80211_input.o

0

0

973

7770

wpa.c.o

0 656

 55

7539

[... additional lines removed ...]

0 1498

0

0

0

0

0

0

0

0

0

0

0 3499

0 2673

0

0

0

0

0

0

0 1186

0 2657

0

0

0

0

0 1726

0 7594

0

0

0

0

0

0

0 4499

0

0

0

0

0

0

0

0

(continued from previous page)

0

10858 

0

13829



0

13251



0

12769



0

11096 

0

11515



0

8561



0

7788



0

8889 

0

9654 

0

10069



0

8628



0

7677



0

9652



0

8750 

0

6245 

0

0

0

7384 

0

8864



0

8578



0

3684



0

5686 

0

6161 

0

6797



0

6828



After the summary of total sizes, a table of oPer-file contributions to ELF filepis printed.
The columns are the same as shown above for idy.py size-components, but this time the granularity is the contribution of each individual object file to the binary size.
For example, we can see that the file x509_crt_bundle.S.o contributed 64212 bytes to the total firmware size, all as .rodata in flash. Therefore we can guess that this application is using the ESP x509 Certificate Bundle feature and not using this feature would save at last this many bytes from the firmware size.
Some of the object files are linked from binary libraries and therefore you wonnt find a corresponding source file. To locate which component a source file belongs to, itns generally possible to search in the ESP-IDF source tree or

Espressif Systems

1860

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

look in the Linker Map File for the full path.

Comparing Two Binaries If making some changes that affect binary size, itns possible to use an ESP-IDF tool to break down the exact differences in size.
This operation isnnt part of idf.py, itns necessary to run the idf-size.py Python tool directly.
To do so, first locate the linker map file in the build directory. It will have the name PROJECTNAME.map. The idf-size.py tool performs its analysis based on the output of the linker map file.
To compare with another binary, you will also need its corresponding .map file saved from the build directory.
For example, to compare two builds: one with the default CONFIG_COMPILER_OPTIMIZATION setting oDebug (-Og)pconfiguration and one with oOptimize for size (-Os)p:

$ $IDF_PATH/tools/idf_size.py --diff build_Og/https_request.map build_Os/https_

request.map

<CURRENT> MAP file: build_Os/https_request.map

<REFERENCE> MAP file: build_Og/https_request.map

Difference is counted as <CURRENT> - <REFERENCE>, i.e. a positive number means

that <CURRENT> is larger.

Total sizes of <CURRENT>:

<REFERENCE>

Difference

DRAM .data size: 14516 bytes



14956

-440

DRAM .bss size: 15792 bytes



15808

-16

Used static DRAM: 30308 bytes ( 150428 available, 16.8% used)



30764

-456 ( +456 available,

+0 total)

Used static IRAM: 78498 bytes ( 52574 available, 59.9% used)



83918

-5420 ( +5420 available,

+0 total)

Flash code: 509183 bytes



559943

-50760

Flash rodata: 170592 bytes



176736

-6144

Total image size:~ 772789 bytes (.bin may be padded larger)



835553

-62764

We can see from the oDifferencepcolumn that changing this one setting caused the whole binary to be over 60 KB smaller and over 5 KB more RAM is available.
Itns also possible to use the odiffpmode to output a table of component-level (static library archive) differences:
$IDF_PATH/tools/idf_size.py --archives --diff build_Og/https_request.map build_ Oshttps_request.map

Also at the individual source file level:
$IDF_PATH/tools/idf_size.py --files --diff build_Og/https_request.map build_ Oshttps_request.map

Other options (like writing the output to a file) are available, pass --help to see the full list.

Showing Size When Linker Fails If too much static memory is used, then the linker will fail with an error such as DRAM segment data does not fit, region `iram0_0_seg' overflowed by 44 bytes, or similar.
In these cases, idf.py size will not succeed either. However it is possible to run idf_size.py manually in order to view the partial static memory usage (the memory usage will miss the variables which could not be linked, so there still appears to be some free space.)
The map file argument is <projectname>.map in the build directory

Espressif Systems

1861

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
$IDF_PATH/tools/idf_size.py build/project_name.map
It is also possible to view the equivalent of size-components or size-files output:
$IDF_PATH/tools/idf_size.py --archives build/project_name.map $IDF_PATH/tools/idf_size.py --files build/project_name.map
Linker Map File This is an advanced analysis method, but it can be very useful. Feel free to skip ahead to :ref:`reducing-overall-size` and possibly come back to this later.
The idf.py size analysis tools all work by parsing the GNU binutils olinker map filep, which is a summary of everything the linker did when it created (olinkedp) the final firmware binary file
Linker map files themselves are plain text files, so itns possible to read them and find out exactly what the linker did. However, they are also very complex and long - often 100,000 or more lines!
The map file itself is broken into parts and each part has a heading. The parts are:
· Archive member included to satisfy reference by file (symbol). This shows you: for each object file included in the link, what symbol (function or variable) was the linker searching for when it included that object file. If younre wondering why some object file in particular was included in the binary, this part may give a clue. This part can be used in conjunction with the Cross Reference Table at the end of the file. Note that not every object file shown in this list ends up included in the final binary, some end up in the Discarded input sections list instead.
· Allocating common symbols - This is a list of (some) global variables along with their sizes. Common symbols have a particular meaning in ELF binary files, but ESP-IDF doesnnt make much use of them.
· Discarded input sections - These sections were read by the linker as part of an object file to be linked into the final binary, but then nothing else referred to them so they were discarded from the final binary. For ESP-IDF this list can be very long, as we compile each function and static variable to a unique section in order to minimize the final binary size (specifically ESP-IDF uses compiler options -ffunction-sections -fdata-sections and linker option --gc-sections). Items mentioned in this list do not contribute to the final binary.
· Memory Configuration, Linker script and memory map These two parts go together. Some of the output comes directly from the linker command line and the Linker Script, both provided by the Build System. The linker script is partially generated from the ESP-IDF project using the Linker Script Generation feature. As the output of the Linker script and memory map part of the map unfolds, you can see each symbol (function or static variable) linked into the final binary along with its address (as a 16 digit hex number), its length (also in hex), and the library and object file it was linked from (which can be used to determine the component and the source file). Following all of the output sections that take up space in the final .bin file, the memory map also includes some sections in the ELF file that are only used for debugging (ELF sections .debug_*, etc.). These donnt contribute to the final binary size. Younll notice the address of these symbols is a very low number (starting from 0x0000000000000000 and counting up).
· Cross Reference Table. This table shows for each symbol (function or static variable), the list of object file(s) that referred to it. If younre wondering why a particular thing is included in the binary, this will help determine what included it.
Note: Unfortunately, the Cross Reference Table doesnnt only include symbols that made it into the final binary. It also includes symbols in discarded sections. Therefore, just because something is shown here doesnnt mean that it was included in the final binary - this needs to be checked separately.
Note: Linker map files are generated by the GNU binutils linker oldp, not ESP-IDF. You can find additional information online about the linker map file format. This quick summary is written from the perspective of ESP-IDF build system in particular.

Espressif Systems

1862

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Reducing Overall Size The following configuration options will reduce the final binary size of almost any ESP-IDF project:
· Set CONFIG_COMPILER_OPTIMIZATION to oOptimize for size (-Os)p. In some cases, oOptimize for performance (-O2)pwill also reduce the binary size compared to the default. Note that if your code contains C or C++ Undefined Behaviour then increasing the compiler optimization level may expose bugs that otherwise donnt happen.
· Reduce the compiled-in log output by lowering the app CONFIG_LOG_DEFAULT_LEVEL. If the CONFIG_LOG_MAXIMUM_LEVEL is changed from the default then this setting controls the binary size instead. Reducing compiled-in logging reduces the number of strings in the binary, and also the code size of the calls to logging functions.
· Set the CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL to oSilentp. This avoids compiling in a dedicated assertion string and source file name for each assert that may fail. Itns still possible to find the failed assert in the code by looking at the memory address where the assertion failed.
· Besides the CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL, you can disable or silent the assertion for HAL component separately by setting CONFIG_HAL_DEFAULT_ASSERTION_LEVEL.
· Set CONFIG_COMPILER_OPTIMIZATION_CHECKS_SILENT. This removes specific error messages for particular internal ESP-IDF error check macros. This may make it harder to debug some error conditions by reading the log output.
· Donnt enable CONFIG_COMPILER_CXX_EXCEPTIONS, CONFIG_COMPILER_CXX_RTTI, or set the CONFIG_COMPILER_STACK_CHECK_MODE to Overall. All of these options are already disabled by default, but they have a large impact on binary size.
· Disabling CONFIG_ESP_ERR_TO_NAME_LOOKUP will remove the lookup table to translate user-friendly names for error values (see Error Handling) in error logs, etc. This saves some binary size, but error values will be printed as integers only.
· Setting CONFIG_ESP_SYSTEM_PANIC to oSilent rebootpwill save a small amount of binary size, however this is only recommended if no one will use UART output to debug the device.
Note: In addition to the many configuration items shown here, there are a number of configuration options where changing the option from the default will increase binary size. These are not noted here. Where the increase is significant, this is usually noted in the configuration item help text.
Targeted Optimizations The following binary size optimizations apply to a particular component or a function:
Wi-Fi
· Disabling CONFIG_ESP32_WIFI_ENABLE_WPA3_SAE will save some Wi-Fi binary size if WPA3 support is not needed. (Note that WPA3 is mandatory for new Wi-Fi device certifications.)
· Disabling CONFIG_ESP_WIFI_SOFTAP_SUPPORT will save some Wi-Fi binary size if soft-AP support is not needed.
Bluetooth NimBLE If using NimBLE Bluetooth Host then the following modifications can reduce binary size:
· CONFIG_BT_NIMBLE_MAX_CONNECTIONS to 1 if only one BLE connection is needed. · Disable either CONFIG_BT_NIMBLE_ROLE_CENTRAL or CONFIG_BT_NIMBLE_ROLE_OBSERVER if
these roles are not needed. · Reducing CONFIG_BT_NIMBLE_LOG_LEVEL can reduce binary size. Note that if the overall log level has
been reduced as described above in Reducing Overall Size then this also reduces the NimBLE log level.
lwIP IPv6
· Setting CONFIG_LWIP_IPV6 to false will reduce the size of the lwIP TCP/IP stack, at the cost of only supporting IPv4.

Espressif Systems

1863

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Note: IPv6 is required by some components such as coap and ASIO port, These components will not be available if IPV6 is disabled.
Newlib nano formatting By default, ESP-IDF uses newlib ofullpformating for I/O (printf, scanf, etc.)
Enabling the config option CONFIG_NEWLIB_NANO_FORMAT will switch newlib to theonanopformatting mode. This both smaller in code size and a large part of the implementation is compiled into the ESP32-S3 ROM, so it doesnnt need to be included in the binary at all.
The exact difference in binary size depends on which features the firmware uses, but 25 KB ~ 50 KB is typical.
Enabling Nano formatting also reduces the stack usage of each function that calls printf() or another string formatting function, see Reducing Stack Sizes.
oNanopformatting doesnnt support 64-bit integers, or C99 formatting features. For a full list of restrictions, search for --enable-newlib-nano-formatted-io in the Newlib README file.
mbedTLS features Under Component Config -> mbedTLS there are multiple mbedTLS features which are enabled by default but can be disabled if not needed to save code size.
These include:
· CONFIG_MBEDTLS_HAVE_TIME · CONFIG_MBEDTLS_ECDSA_DETERMINISTIC · CONFIG_MBEDTLS_SHA512_C · CONFIG_MBEDTLS_SSL_PROTO_TLS1 · CONFIG_MBEDTLS_SSL_PROTO_TLS1_1 · CONFIG_MBEDTLS_CLIENT_SSL_SESSION_TICKETS · CONFIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS · CONFIG_MBEDTLS_SSL_ALPN · CONFIG_MBEDTLS_CCM_C · CONFIG_MBEDTLS_GCM_C · CONFIG_MBEDTLS_ECP_C (Alternatively: Leave this option enabled but disable some of the elliptic curves
listed in the sub-menu.) · CONFIG_MBEDTLS_SSL_RENEGOTIATION · Change CONFIG_MBEDTLS_TLS_MODE if both Server & Client are not needed · Consider disabling some ciphersuites listed in the oTLS Key Exchange Methodspsub-menu (i.e. CON-
FIG_MBEDTLS_KEY_EXCHANGE_RSA)
The help text for each option has some more information.
Important: It is strongly not recommended to disable all these mbedTLS options. Only disable options where you understand the functionality and are certain that it is not needed in the application. In particular:
· Ensure that any TLS server(s) the device connects to can still be used. If the server is controlled by a third party or a cloud service, recommend ensuring that the firmware supports at least two of the supported cipher suites in case one is disabled in a future update.
· Ensure that any TLS client(s) that connect to the device can still connect with supported/recommended cipher suites. Note that future versions of client operating systems may remove support for some features, so it is recommended to enable multiple supported cipher suites or algorithms for redundancy.
If depending on third party clients or servers, always pay attention to announcements about future changes to supported TLS features. If not, the ESP32-S3 device may become inaccessible if support changes.
Note: Not every combination of mbedTLS compile-time config is tested in ESP-IDF. If you find a combination that fails to compile or function as expected, please report the details on GitHub.

Espressif Systems

1864

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
FreeModBus If using Modbus, enable or disable CONFIG_FMB_COMM_MODE_TCP_EN, CONFIG_FMB_COMM_MODE_RTU_EN, CONFIG_FMB_COMM_MODE_ASCII_EN as applicable for the necessary functionality.
VFS Virtual filesystem feature in ESP-IDF allows multiple filesystem drivers and file-like peripheral drivers to be accessed using standard I/O functions (open, read, write, etc.) and C library functions (fopen, fread, fwrite, etc.). When filesystem or file-like peripheral driver functionality is not used in the application this feature can be fully or partially disabled. VFS component provides the following configuration options:
· CONFIG_VFS_SUPPORT_TERMIOS ican be disabled if the application doesnnt use termios family of functions. Currently, these functions are implemented only for UART VFS driver. Most applications can disable this option. Disabling this option reduces the code size by about 1.8 kB.
· CONFIG_VFS_SUPPORT_SELECT i can be disabled if the application doesnnt use select function with file descriptors. Currently, only the UART and eventfd VFS drivers implement select support. Note that when this option is disabled, select can still be used for socket file descriptors. Disabling this option reduces the code size by about 2.7 kB.
· CONFIG_VFS_SUPPORT_DIR ican be disabled if the application doesnnt use directory related functions, such as readdir (see the description of this option for the complete list). Applications which only open, read and write specific files and donnt need to enumerate or create directories can disable this option, reducing the code size by 0.5 kB or more, depending on the filesystem drivers in use.
· CONFIG_VFS_SUPPORT_IO ican be disabled if the application doesnnt use filesystems or file-like peripheral drivers. This disables all VFS functionality, including the three options mentioned above. When this option is disabled, console cannt be used. Note that the application can still use standard I/O functions with socket file descriptors when this option is disabled. Compared to the default configuration, disabling this option reduces code size by about 9.4 kB.
Bootloader Size This document deals with the size of an ESP-IDF app binary only, and not the ESP-IDF Second stage bootloader. For a discussion of ESP-IDF bootloader binary size, see Bootloader Size.
IRAM Binary Size If the IRAM section of a binary is too large, this issue can be resolved by reducing IRAM memory usage. See Optimizing IRAM Usage.
Minimizing RAM Usage
In some cases, a firmware applicationns available RAM may run low or run out entirely. In these cases, itns necessary to tune the memory usage of the firmware application. In general, firmware should aim to leave someoheadroompof free internal RAM in order to deal with extraordinary situations or changes in RAM usage in future updates.
Background Before optimizing ESP-IDF RAM usage, itns necessary to understand the basics of ESP32-S3 memory types, the difference between static and dynamic memory usage in C, and the way ESP-IDF uses stack and heap. This information can all be found in Heap Memory Allocation.
Measuring Static Memory Usage The idf.py tool can be used to generate reports about the static memory usage of an application. Refer to the Binary Size chapter for more information.
Measuring Dynamic Memory Usage ESP-IDF contains a range of heap APIs for measuring free heap at runtime. See Heap Memory Debugging.

Espressif Systems

1865

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Note: In embedded systems, heap fragmentation can be a significant issue alongside total RAM usage. The heap measurement APIs provide ways to measure the olargest free blockp. Monitoring this value along with the total number of free bytes can give a quick indication of whether heap fragmentation is becoming an issue.

Reducing Static Memory Usage
· Reducing the static memory usage of the application increases the amount of RAM available for heap at runtime, and vice versa.
· Generally speaking, minimizing static memory usage requires monitoring the .data and .bss sizes. For tools to do this, see Measuring Static Sizes.
· Internal ESP-IDF functions do not make heavy use of static RAM allocation in C. In many instances (including: Wi-Fi library, Bluetooth controller) ostaticpbuffers are still allocated from heap, but the allocation is done once when the feature is initialized and will be freed if the feature is deinitialized. This is done in order to maximize the amount of free memory at different points in the application life-cycle.
To minimize static memory use:
· Declare structures, buffers, or other variables const whenever possible. Constant data can be stored in flash not RAM. This may require changing functions in the firmware to take const * arguments instead of mutable pointer arguments. These changes can also reduce the stack usage of some functions.
· If using Bluedroid, setting the option CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY will cause Bluedroid to allocate memory on initialization and free it on deinitialization. This doesnnt necessarily reduce the peak memory usage, but changes it from static memory usage to runtime memory usage.

Reducing Stack Sizes In FreeRTOS, task stacks are usually allocated from the heap. The stack size for each task is fixed (passed as an argument to xTaskCreate()). Each task can use up to its allocated stack size, but using more than this will cause an otherwise valid program to crash with a stack overflow or heap corruption.
Therefore, determining the optimum sizes of each task stack can substantially reduce RAM usage.
To determine optimum task stack sizes:
· Combine tasks. The best task stack size is 0 bytes, achieved by combining a task with another existing task. Anywhere that the firmware can be structured to perform multiple functions sequentially in a single task will increase free memory. In some cases, using aoworker taskppattern where jobs are serialized into a FreeRTOS queue (or similar) and then processed by generic worker tasks may help.
· Consolidate task functions. String formatting functions (like printf) are particularly heavy users of stack, so any task which doesnnt ever call these can usually have its stack size reduced.
· Enabling Newlib nano formatting will reduce the stack usage of any task that calls printf() or other C string formatting functions.
· Avoid allocating large variables on the stack. In C, any large struct or array allocated as anoautomaticpvariable (i.e. default scope of a C declaration) will use space on the stack. Minimize the sizes of these, allocate them statically and/or see if you can save memory by allocating them from the heap only when they are needed.
· Avoid deep recursive function calls. Individual recursive function calls donnt always add a lot of stack usage each time they are called, but if each function includes large stack-based variables then the overhead can get quite high.
· At runtime, call the function uxTaskGetStackHighWaterMark() with the handle of any task where you think there is unused stack memory. This function returns the minimum lifetime free stack memory in bytes. The easiest time to call this is from the task itself: call uxTaskGetStackHighWaterMark(NULL) to get the current taskns high water mark after the time that the task has achieved its peak stack usage (i.e. if there is a main loop, execute the main loop a number of times with all possible states and then call uxTaskGetStackHighWaterMark()). Often, itns possible to subtract almost the entire value returned here from the total stack size of a task, but allow some safety margin to account for unexpected small increases in stack usage at runtime.
· Call uxTaskGetSystemState() at runtime to get a summary of all tasks in the system. This includes their individual stack ohigh watermarkpvalues.
· When debugger watchpoints are not being used, set the CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK option to trigger an immediate panic if a task writes the word at the end of its assigned stack. This is slightly

Espressif Systems

1866

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
more reliable than the default CONFIG_FREERTOS_CHECK_STACKOVERFLOW option of oCheck using canary bytesp, because the panic happens immediately, not on the next RTOS context switch. Neither option is perfect, itns possible in some cases for stack pointer to skip the watchpoint or canary bytes and corrupt another region of RAM, instead.
Internal Stack Sizes ESP-IDF allocates a number of internal tasks for housekeeping purposes or operating system functions. Some are created during the startup process, and some are created at runtime when particular features are initialized.
The default stack sizes for these tasks are usually set conservatively high, to allow all common usage patterns. Many of the stack sizes are configurable, and it may be possible to reduce them to match the real runtime stack usage of the task.
Important: If internal task stack sizes are set too small, ESP-IDF will crash unpredictably. Even if the root cause is task stack overflow, this is not always clear when debugging. It is recommended that internal stack sizes are only reduced carefully (if at all), with close attention to ohigh water markpfree space under load. If reporting an issue that occurs when internal task stack sizes have been reduced, please always include this information and the specific configuration that is being used.
· Main task that executes app_main function has stack size CONFIG_ESP_MAIN_TASK_STACK_SIZE. · High Resolution Timer system task which executes callbacks has stack size CON-
FIG_ESP_TIMER_TASK_STACK_SIZE. · FreeRTOS Timer Task to handle FreeRTOS timer callbacks has stack size CON-
FIG_FREERTOS_TIMER_TASK_STACK_DEPTH . · Event Handling system task to execute callbacks for the default system event loop has stack size CON-
FIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE. · lwIP TCP/IP task has stack size CONFIG_LWIP_TCPIP_TASK_STACK_SIZE · Bluedroid Bluetooth Host have task stack sizes CONFIG_BT_BTC_TASK_STACK_SIZE, CON-
FIG_BT_BTU_TASK_STACK_SIZE. · NimBLE Bluetooth Host has task stack size CONFIG_BT_NIMBLE_TASK_STACK_SIZE · The Ethernet driver creates a task for the MAC to receive Ethernet frames. If using the default config
ETH_MAC_DEFAULT_CONFIG then the task stack size is 4 KB. This setting can be changed by passing a custom eth_mac_config_t struct when initializing the Ethernet MAC. · FreeRTOS idle task stack size is configured by CONFIG_FREERTOS_IDLE_TASK_STACKSIZE. · If using the mDNS and/or MQTT components, they create tasks with stack sizes configured by CONFIG_MDNS_TASK_STACK_SIZE and CONFIG_MQTT_TASK_STACK_SIZE, respectively. MQTT stack size can also be configured using task_stack field of esp_mqtt_client_config_t.
Note: Aside from built-in system features such as esp-timer, if an ESP-IDF feature is not initialized by the firmware then no associated task is created. In those cases, the stack usage is zero and the stack size configuration for the task is not relevant.

Reducing Heap Usage For functions that assist in analyzing heap usage at runtime, see Heap Memory Debugging.
Normally, optimizing heap usage consists of analyzing the usage and removing calls to malloc() that arennt being used, reducing the corresponding sizes, or freeing previously allocated buffers earlier.
There are some ESP-IDF configuration options that can reduce heap usage at runtime:
· lwIP documentation has a section to configure Minimum RAM usage. · Wi-Fi Buffer Usage describes options to either reduce numbers of ostaticpbuffers or reduce the maximum
number of odynamicpbuffers in use, in order to minimize memory usage at possible cost of performance. Note that ostaticpWi-Fi buffers are still allocated from heap when Wi-Fi is initialized and will be freed if Wi-Fi is deinitialized. · mbedTLS TLS session memory usage can be minimized by enabling the ESP-IDF feature CONFIG_MBEDTLS_DYNAMIC_BUFFER.

Espressif Systems

1867

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Note: There are other configuration options that will increase heap usage at runtime if changed from the defaults. These are not listed here, but the help text for the configuration item will mention if there is some memory impact.
Optimizing IRAM Usage The available DRAM at runtime (for heap usage) is also reduced by the static IRAM usage. Therefore, one way to increase available DRAM is to reduce IRAM usage. If the app allocates more static IRAM than is available then the app will fail to build and linker errors such as section `.iram0.text' will not fit in region `iram0_0_seg', IRAM0 segment data does not fit and region `iram0_0_seg' overflowed by 84 bytes will be seen. If this happens, it is necessary to find ways to reduce static IRAM usage in order to link the application. To analyze the IRAM usage in the firmware binary, use Measuring Static Sizes. If the firmware failed to link, steps to analyze are shown at Showing Size When Linker Fails. The following options will reduce IRAM usage of some ESP-IDF features:
· Enable CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH. Provided these functions are not (incorrectly) used from ISRs, this option is safe to enable in all configurations.
· Enable CONFIG_FREERTOS_PLACE_SNAPSHOT_FUNS_INTO_FLASH. Enabling this option will place snapshot-related functions, such as vTaskGetSnapshot or uxTaskGetSnapshotAll, in flash.
· Disable Wi-Fi options CONFIG_ESP32_WIFI_IRAM_OPT and/or CONFIG_ESP32_WIFI_RX_IRAM_OPT. Disabling these options will free available IRAM at the cost of Wi-Fi performance.
· CONFIG_SPI_FLASH_ROM_IMPL enabling this option will free some IRAM but will mean that esp_flash bugfixes and new flash chip support is not available.
· Disabling CONFIG_ESP_EVENT_POST_FROM_IRAM_ISR prevents posting esp_event events from IRAM-Safe Interrupt Handlers but will save some IRAM.
· Disabling CONFIG_SPI_MASTER_ISR_IN_IRAM prevents spi_master interrupts from being serviced while writing to flash, and may otherwise reduce spi_master performance, but will save some IRAM.
· Setting CONFIG_HAL_DEFAULT_ASSERTION_LEVEL to disable assertion for HAL component will save some IRAM especially for HAL code who calls HAL_ASSERT a lot and resides in IRAM.
Note: Moving frequently-called functions from IRAM to flash may increase their execution time.
Note: Other configuration options exist that will increase IRAM usage by moving some functionality into IRAM, usually for performance, but the default option is not to do this. These are not listed here. The IRAM size impact of enabling these options is usually noted in the configuration item help text.
4.27 RF calibration
ESP32-S3 supports three RF calibration methods during RF initialization: 1. Partial calibration 2. Full calibration 3. No calibration
4.27.1 Partial calibration
During RF initialization, the partial calibration method is used by default for RF calibration. It is done based on the full calibration data which is stored in the NVS. To use this method, please go to menuconfig and enable CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE.

Espressif Systems

1868

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.27.2 Full calibration
Full calibration is triggered in the follwing conditions: 1. NVS does not exist. 2. The NVS partition to store calibration data is erased. 3. Hardware MAC address is changed. 4. PHY library version is changed. 5. The RF calibration data loaded from the NVS partition is broken.
It takes about 100ms more than partial calibration. If boot duration is not critical, it is suggested to use the full calibration method. To switch to the full calibration method, go to menuconfig and disable CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE. If you use the default method of RF calibration, there are two ways to add the function of triggering full calibration as a last-resort remedy.
1. Erase the NVS partition if you donnt mind all of the data stored in the NVS partition is erased. That is indeed the easiest way.
2. Call API esp_phy_erase_cal_data_in_nvs() before initializing WiFi and BT/BLE based on some conditions (e.g. an option provided in some diagnostic mode). In this case, only phy namespace of the NVS partition is erased.
4.27.3 No calibration
No calibration method is only used when the device wakes up from deep sleep.
4.27.4 PHY initialization data
The PHY initialization data is used for RF calibration. There are two ways to get the PHY initialization data. One is the default initialization data which is located in the header file components/esp_phy/esp32s3/include/phy_init_data.h. It is embedded into the application binary after compiling and then stored into read-only memory (DROM). To use the default initialization data, please go to menuconfig and disable CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION. Another is the initialization data which is stored in a partition. When using a custom partition table, make sure that PHY data partition is included (type: data, subtype: phy). With default partition table, this is done automatically. If initialization data is stored in a partition, it has to be flashed there, otherwise runtime error will occur. To switch to the initialization data stored in a partition, go to menuconfig and enable CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION.
4.28 Secure Boot V2
Important: This document is about Secure Boot V2, supported on the following chips: ESP32 (ECO3 onwards), ESP32-S2, ESP32-S3 and ESP32-C3 (ECO3 onwards). Except for ESP32, it is the only supported Secure Boot scheme. Secure Boot V2 uses RSA based app and bootloader verification. This document can also be used as a reference for signing apps using the RSA scheme without signing the bootloader.
4.28.1 Background
Secure Boot protects a device from running any unauthorized (i.e., unsigned) code by checking that each piece of software that is being booted is signed. On an ESP32-S3, these pieces of software include the second stage bootloader

Espressif Systems

1869

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
and each application binary. Note that the first stage bootloader does not require signing as it is ROM code thus cannot be changed.
A new RSA based Secure Boot verification scheme (Secure Boot V2) has been introduced on the ESP32 (ECO3 onwards), ESP32-S2, ESP32-S3 and ESP32-C3 (ECO3 onwards).
The Secure Boot process on the ESP32-S3 involves the following steps: 1. When the first stage bootloader loads the second stage bootloader, the second stage bootloaderns RSA-PSS signature is verified. If the verification is successful, the second stage bootloader is executed. 2. When the second stage bootloader loads a particular application image, the applicationns RSA-PSS signature is verified. If the verification is successful, the application image is executed.
4.28.2 Advantages
· The RSA public key is stored on the device. The corresponding RSA private key is kept at a secret place and is never accessed by the device.
· Up to three public keys can be generated and stored in the chip during manufacturing. · ESP32-S3 provides the facility to permanently revoke individual public keys. This can be configured conser-
vatively or aggressively. · Conservatively - The old key is revoked after the bootloader and application have successfully migrated to a
new key. Aggressively - The key is revoked as soon as verification with this key fails.
· Same image format and signature verification method is applied for applications and software bootloader. · No secrets are stored on the device. Therefore, it is immune to passive side-channel attacks (timing or power
analysis, etc.)
4.28.3 Secure Boot V2 Process
This is an overview of the Secure Boot V2 Process. Instructions how to enable Secure Boot are supplied in section How To Enable Secure Boot V2.
Secure Boot V2 verifies the bootloader image and application binary images using a dedicated signature block. Each image has a separately generated signature block which is appended to the end of the image.
Up to 3 signature blocks can be appended to the bootloader or application image in ESP32-S3.
Each signature block contains a signature of the preceding image as well as the corresponding RSA-3072 public key. For more details about the format, refer to Signature Block Format. A digest of the RSA-3072 public key is stored in the eFuse.
The application image is not only verified on every boot but also on each over the air (OTA) update. If the currently selected OTA app image cannot be verified, the bootloader will fall back and look for another correctly signed application image.
The Secure Boot V2 process follows these steps:
1. On startup, the ROM code checks the Secure Boot V2 bit in the eFuse. If Secure Boot is disabled, a normal boot will be executed. If Secure Boot is enabled, the boot will proceed according to the following steps.
2. The ROM code verifies the bootloaderns signature block (Verifying a Signature Block). If this fails, the boot process will be aborted.
3. The ROM code verifies the bootloader image using the raw image data, its corresponding signature block(s), and the eFuse (Verifying an Image). If this fails, the boot process will be aborted.
4. The ROM code executes the bootloader. 5. The bootloader verifies the application imagens signature block (Verifying a Signature Block). If this fails, the
boot process will be aborted. 6. The bootloader verifies the application image using the raw image data, its corresponding signature blocks and
the eFuse (Verifying an Image). If this fails, the boot process will be aborted. If the verification fails but another application image is found, the bootloader will then try to verify that other image using steps 5 to 7. This repeats until a valid image is found or no other images are found. 7. The bootloader executes the verified application image.

Espressif Systems

1870

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

4.28.4 Signature Block Format

The bootloader and application images are padded to the next 4096 byte boundary, thus the signature has a flash sector of its own. The signature is calculated over all bytes in the image including the padding bytes.
The content of each signature block is shown in the following table:

Offset 0 1 2 4 36
420
424 808 812
1196 1200

Size (bytes) 1 1 2 32 384
4
384 4 384
4 16

Table 27: Content of a Signature Block
Description Magic byte Version number byte (currently 0x02), 0x01 is for Secure Boot V1. Padding bytes, Reserved. Should be zero. SHA-256 hash of only the image content, not including the signature block. RSA Public Modulus used for signature verification. (value mnnin RFC8017). RSA Public Exponent used for signature verification (value menin RFC8017). Pre-calculated R, derived from mnn. Pre-calculated Mn, derived from mnn RSA-PSS Signature result (section 8.1.1 of RFC8017) of image content, computed using following PSS parameters: SHA256 hash, MFG1 function, salt length 32 bytes, default trailer field (0xBC). CRC32 of the preceding 1095 bytes. Zero padding to length 1216 bytes.

Note: R and Mnare used for hardware-assisted Montgomery Multiplication.
The remainder of the signature sector is erased flash (0xFF) which allows writing other signature blocks after previous signature block.
4.28.5 Verifying a Signature Block
A signature block is ovalidpif the first byte is 0xe7 and a valid CRC32 is stored at offset 1196. Otherwise itns invalid.
4.28.6 Verifying an Image
An image is overifiedpif the public key stored in any signature block is valid for this device, and if the stored signature is valid for the image data read from flash.
1. Compare the SHA-256 hash digest of the public key embedded in the bootloaderns signature block with the digest(s) saved in the eFuses. If public keyns hash doesnnt match any of the hashes from the eFuses, the verification fails.
2. Generate the application image digest and match it with the image digest in the signature block. If the digests donnt match, the verification fails.
3. Use the public key to verify the signature of the bootloader image, using RSA-PSS (section 8.1.2 of RFC8017) with the image digest calculated in step (2) for comparison.
4.28.7 Bootloader Size
Enabling Secure boot and/or flash encryption will increase the size of bootloader, which might require updating partition table offset. See Bootloader Size.

Espressif Systems

1871

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.28.8 eFuse usage
· SECURE_BOOT_EN - Enables Secure Boot protection on boot. · KEY_PURPOSE_X - Set the purpose of the key block on ESP32-S3 by programming SE-
CURE_BOOT_DIGESTX (X = 0, 1, 2) into KEY_PURPOSE_X (X = 0, 1, 2, 3, 4, 5). Example: If KEY_PURPOSE_2 is set to SECURE_BOOT_DIGEST1, then BLOCK_KEY2 will have the Secure Boot V2 public key digest. The write-protection bit must be set (this field does not have a read-protection bit). · BLOCK_KEYX - The block contains the data corresponding to its purpose programmed in KEY_PURPOSE_X. Stores the SHA-256 digest of the public key. SHA-256 hash of public key modulus, exponent, pre-calculated R & Mnvalues (represented as 776 bytes offsets 36 to 812 - as per the Signature Block Format) is written to an eFuse key block. The write-protection bit must be set, but the read-protection bit must not. · KEY_REVOKEX - The revocation bits corresponding to each of the 3 key block. Ex. Setting KEY_REVOKE2 revokes the key block whose key purpose is SECURE_BOOT_DIGEST2. · SECURE_BOOT_AGGRESSIVE_REVOKE - Enables aggressive revocation of keys. The key is revoked as soon as verification with this key fails.
To ensure no trusted keys can be added later by an attacker, each unused key digest slot should be revoked (KEY_REVOKEX). It will be checked during app startup in esp_secure_boot_init_checks() and fixed unless CONFIG_SECURE_BOOT_ALLOW_UNUSED_DIGEST_SLOTS is enabled.
The key(s) must be readable in order to give software access to it. If the key(s) is read-protected then the software reads the key(s) as all zeros and the signature verification process will fail, and the boot process will be aborted.
4.28.9 How To Enable Secure Boot V2
1. Open the Project Configuration Menu, inoSecurity featurespsetoEnable hardware Secure Boot in bootloaderp to enable Secure Boot.
2. The oSecure Boot V2poption will be selected and the oApp Signing Schemepwould be set to RSA by default.
3. Specify the path to Secure Boot signing key, relative to the project directory. 4. Select the desired UART ROM download mode in oUART ROM download modep. By default, it is set
tooPermanently switch to Secure modepwhich is generally recommended. For production devices, the most secure option is to set it to oPermanently disabledp.
5. Set other menuconfig options (as desired). Pay particular attention to theoBootloader Configpoptions, as you can only flash the bootloader once. Then exit menuconfig and save your configuration.
6. The first time you run idf.py build, if the signing key is not found then an error message will be printed with a command to generate a signing key via espsecure.py generate_signing_key.
Important: A signing key generated this way will use the best random number source available to the OS and its Python installation (/dev/urandom on OSX/Linux and CryptGenRandom() on Windows). If this random number source is weak, then the private key will be weak.
Important: For production environments, we recommend generating the key pair using openssl or another industry standard encryption program. See Generating Secure Boot Signing Key for more details.
7. Run idf.py bootloader to build a Secure Boot enabled bootloader. The build output will include a prompt for a flashing command, using esptool.py write_flash.
8. When younre ready to flash the bootloader, run the specified command (you have to enter it yourself, this step is not performed by the build system) and then wait for flashing to complete.
9. Run idf.py flash to build and flash the partition table and the just-built app image. The app image will be signed using the signing key you generated in step 4.

Espressif Systems

1872

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Note: idf.py flash doesnnt flash the bootloader if Secure Boot is enabled.
10. Reset the ESP32-S3 and it will boot the software bootloader you flashed. The software bootloader will enable Secure Boot on the chip, and then it verifies the app image signature and boots the app. You should watch the serial console output from the ESP32-S3 to verify that Secure Boot is enabled and no errors have occurred due to the build configuration.
Note: Secure boot wonnt be enabled until after a valid partition table and app image have been flashed. This is to prevent accidents before the system is fully configured.

Note: If the ESP32-S3 is reset or powered down during the first boot, it will start the process again on the next boot.
11. On subsequent boots, the Secure Boot hardware will verify the software bootloader has not changed and the software bootloader will verify the signed app image (using the validated public key portion of its appended signature block).
4.28.10 Restrictions after Secure Boot is enabled
· Any updated bootloader or app will need to be signed with a key matching the digest already stored in eFuse. · After Secure Boot is enabled, no further eFuses can be read protected. (If Flash Encryption is enabled then
the bootloader will ensure that any flash encryption key generated on first boot will already be read protected.) If CONFIG_SECURE_BOOT_INSECURE is enabled then this behavior can be disabled, but this is not recommended.
4.28.11 Generating Secure Boot Signing Key
The build system will prompt you with a command to generate a new signing key via espsecure.py generate_signing_key. The version 2 parameter will generate the RSA 3072 private key for Secure Boot V2. The strength of the signing key is proportional to (a) the random number source of the system, and (b) the correctness of the algorithm used. For production devices, we recommend generating signing keys from a system with a quality entropy source, and using the best available RSA key generation utilities. For example, to generate a signing key using the openssl command line: ` openssl genrsa -out my_secure_boot_signing_key.pem 3072 ` Remember that the strength of the Secure Boot system depends on keeping the signing key private.
4.28.12 Remote Signing of Images
For production builds, it can be good practice to use a remote signing server rather than have the signing key on the build machine (which is the default esp-idf Secure Boot configuration). The espsecure.py command line program can be used to sign app images & partition table data for Secure Boot, on a remote system. To use remote signing, disable the option oSign binaries during buildp. The private signing key does not need to be present on the build system. After the app image and partition table are built, the build system will print signing steps using espsecure.py:
espsecure.py sign_data --version 2 --keyfile PRIVATE_SIGNING_KEY BINARY_FILE
The above command appends the image signature to the existing binary. You can use the output argument to write the signed binary to a separate file:

Espressif Systems

1873

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

espsecure.py sign_data --version 2 --keyfile PRIVATE_SIGNING_KEY --output SIGNED_ BINARY_FILE BINARY_FILE
4.28.13 Secure Boot Best Practices
· Generate the signing key on a system with a quality source of entropy. · Keep the signing key private at all times. A leak of this key will compromise the Secure Boot system. · Do not allow any third party to observe any aspects of the key generation or signing process using espsecure.py.
Both processes are vulnerable to timing or other side-channel attacks. · Enable all Secure Boot options in the Secure Boot Configuration. These include flash encryption, disabling of
JTAG, disabling BASIC ROM interpreter, and disabling the UART bootloader encrypted flash access. · Use Secure Boot in combination with flash encryption to prevent local readout of the flash contents.
4.28.14 Key Management
· Between 1 and 3 RSA-3072 public key pairs (Keys #0, #1, #2) should be computed independently and stored separately.
· The KEY_DIGEST eFuses should be write protected after being programmed. · The unused KEY_DIGEST slots must have their corresponding KEY_REVOKE eFuse burned to permanently
disable them. This must happen before the device leaves the factory. · The eFuses can either be written by the software bootloader during during first boot after enabling oSecure
Boot V2pfrom menuconfig or can be done using espefuse.py which communicates with the serial bootloader program in ROM. · The KEY_DIGESTs should be numbered sequentially beginning at key digest #0. (i.e., if key digest #1 is used, key digest #0 should be used. If key digest #2 is used, key digest #0 & #1 must be used.) · The software bootloader (non OTA upgradeable) is signed using at least one, possibly all three, private keys and flashed in the factory. · Apps should only be signed with a single private key (the others being stored securely elsewhere), however they may be signed with multiple private keys if some are being revoked (see Key Revocation, below).
4.28.15 Multiple Keys
· The bootloader should be signed with all the private key(s) that are needed for the life of the device, before it is flashed.
· The build system can sign with at most one private key, user has to run manual commands to append more signatures if necessary.
· You can use the append functionality of espsecure.py, this command would also printed at the end of the Secure Bo espsecure.py sign_data -k secure_boot_signing_key2.pem -v 2 append_signatures -o signed_bootloader.bin build/bootloader/bootloader.bin
· While signing with multiple private keys, it is recommended that the private keys be signed independently, if possible on different servers and stored separately.
· You can check the signatures attached to a binary using - espsecure.py signature_info_v2 datafile.bin
4.28.16 Key Revocation
· Keys are processed in a linear order. (key #0, key #1, key #2). · Applications should be signed with only one key at a time, to minimize the exposure of unused private keys. · The bootloader can be signed with multiple keys from the factory.
Conservative approach:
Assuming a trusted private key (N-1) has been compromised, to update to new key pair (N).

Espressif Systems

1874

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

1. Server sends an OTA update with an application signed with the new private key (#N). 2. The new OTA update is written to an unused OTA app partition. 3. The new applicationns signature block is validated. The public keys are checked against the digests programmed
in the eFuse & the application is verified using the verified public key. 4. The active partition is set to the new OTA applicationns partition. 5. Device resets, loads the bootloader (verified with key #N-1) which then boots new app (verified with key #N). 6. The new app verifies bootloader with key #N (as a final check) and then runs code to revoke key #N-1 (sets
KEY_REVOKE eFuse bit). 7. The API esp_ota_revoke_secure_boot_public_key() can be used to revoke the key #N-1. · A similar approach can also be used to physically re-flash with a new key. For physical re-flashing, the boot-
loader content can also be changed at the same time.
Aggressive approach:
ROM code has an additional feature of revoking a public key digest if the signature verification fails. To enable this feature, you need to burn SECURE_BOOT_AGGRESSIVE_REVOKE efuse or enable CONFIG_SECURE_BOOT_ENABLE_AGGRESSIVE_KEY_REVOKE Key revocation is not applicable unless secure boot is successfully enabled. Also, a key is not revoked in case of invalid signature block or invalid image digest, it is only revoked in case the signature verification fails, i.e. revoke key only if failure in step 3 of Verifying an Image Once a key is revoked, it can never be used for verfying a signature of an image. This feature provides strong resistance against physical attacks on the device. However, this could also brick the device permanently if all the keys are revoked because of signature verification failure.
4.28.17 Technical Details
The following sections contain low-level reference descriptions of various Secure Boot elements:
Manual Commands
Secure boot is integrated into the esp-idf build system, so idf.py build will sign an app image and idf.py bootloader will produce a signed bootloader if secure signed binaries on build is enabled. However, it is possible to use the espsecure.py tool to make standalone signatures and digests. To sign a binary image:
espsecure.py sign_data --version 2 --keyfile ./my_signing_key.pem --output ./image_ signed.bin image-unsigned.bin
Keyfile is the PEM file containing an RSA-3072 private signing key.
4.28.18 Secure Boot & Flash Encryption
If Secure Boot is used without Flash Encryption, it is possible to launch otime-of-check to time-of-usepattack, where flash contents are swapped after the image is verified and running. Therefore, it is recommended to use both the features together.
4.28.19 Signed App Verification Without Hardware Secure Boot
The Secure Boot V2 signature of apps can be checked on OTA update, without enabling the hardware Secure Boot option. This option uses the same app signature scheme as Secure Boot V2, but unlike hardware Secure Boot it does not prevent an attacker who can write to flash from bypassing the signature protection.

Espressif Systems

1875

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
This may be desirable in cases where the delay of Secure Boot verification on startup is unacceptable, and/or where the threat model does not include physical access or attackers writing to bootloader or app partitions in flash.
In this mode, the public key which is present in the signature block of the currently running app will be used to verify the signature of a newly updated app. (The signature on the running app isnnt verified during the update process, itn s assumed to be valid.) In this way the system creates a chain of trust from the running app to the newly updated app.
For this reason, itns essential that the initial app flashed to the device is also signed. A check is run on app startup and the app will abort if no signatures are found. This is to try and prevent a situation where no update is possible. The app should have only one valid signature block in the first position. Note again that, unlike hardware Secure Boot V2, the signature of the running app isnnt verified on boot. The system only verifies a signature block in the first position and ignores any other appended signatures.
Although multiple trusted keys are supported when using hardware Secure Boot, only the first public key in the signature block is used to verify updates if signature checking without Secure Boot is configured. If multiple trusted public keys are required, itns necessary to enable the full Secure Boot feature instead.
Note: In general, itns recommended to use full hardware Secure Boot unless certain that this option is sufficient for application security needs.

How To Enable Signed App Verification
1. Open Project Configuration Menu -> Security features 2. Ensure App Signing Scheme is RSA 3. Enable CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT 4. By default, oSign binaries during buildpwill be enabled on selecting oRequire signed app imagespoption,
which will sign binary files as a part of build process. The file named in oSecure boot private signing keyp will be used to sign the image. 5. If you disable oSign binaries during buildpoption then all app binaries must be manually signed by following instructions in Remote Signing of Images.
Warning: It is very important that all apps flashed have been signed, either during the build or after the build.

4.28.20 Advanced Features
JTAG Debugging
By default, when Secure Boot is enabled then JTAG debugging is disabled via eFuse. The bootloader does this on first boot, at the same time it enables Secure Boot. See JTAG with Flash Encryption or Secure Boot for more information about using JTAG Debugging with either Secure Boot or signed app verification enabled.

4.29 Thread Local Storage
4.29.1 Overview
Thread-local storage (TLS) is a mechanism by which variables are allocated such that there is one instance of the variable per extant thread. ESP-IDF provides three ways to make use of such variables:
· FreeRTOS Native API: ESP-IDF FreeRTOS native API. · Pthread API: ESP-IDFns pthread API. · C11 Standard: C11 standard introduces special keyword to declare variables as thread local.

Espressif Systems

1876

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

4.29.2 FreeRTOS Native API
The ESP-IDF FreeRTOS provides the following API to manage thread local variables:
· vTaskSetThreadLocalStoragePointer() · pvTaskGetThreadLocalStoragePointer() · vTaskSetThreadLocalStoragePointerAndDelCallback()
In this case maximum number of variables that can be allocated is limited by CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS configuration value. Variables are kept in the task control block (TCB) and accessed by their index. Note that index 0 is reserved for ESP-IDF internal uses.
Using that API user can allocate thread local variables of an arbitrary size and assign them to any number of tasks. Different tasks can have different sets of TLS variables.
If size of the variable is more then 4 bytes then user is responsible for allocating/deallocating memory for it. Variablen s deallocation is initiated by FreeRTOS when task is deleted, but user must provide function (callback) to do proper cleanup.
4.29.3 Pthread API
The ESP-IDF provides the following pthread API to manage thread local variables:
· pthread_key_create() · pthread_key_delete() · pthread_getspecific() · pthread_setspecific()
This API has all benefits of the one above, but eliminates some its limits. The number of variables is limited only by size of available memory on the heap. Due to the dynamic nature this API introduces additional performance overhead compared to the native one.
4.29.4 C11 Standard
The ESP-IDF FreeRTOS supports thread local variables according to C11 standard (ones specified with __thread keyword). For details on this GCC feature please see https://gcc.gnu.org/onlinedocs/gcc-5.5.0/gcc/Thread-Local. html#Thread-Local. Storage for that kind of variables is allocated on the taskns stack. Note that area for all such variables in the program will be allocated on the stack of every task in the system even if that task does not use such variables at all. For example ESP-IDF system tasks (like ipc, timer tasks etc.) will also have that extra stack space allocated. So this feature should be used with care. There is a tradeoff: C11 thread local variables are quite handy to use in programming and can be accessed using minimal CPU instructions, but this benefit goes with the cost of additional stack usage for all tasks in the system. Due to static nature of variables allocation all tasks in the system have the same sets of C11 thread local variables.

4.30 Tools
4.30.1 Downloadable Tools
ESP-IDF build process relies on a number of tools: cross-compiler toolchains, CMake build system, and others. Installing the tools using an OS-specific package manager (like apt, yum, brew, etc.) is the preferred method when the required version of the tool is available. This recommendation is reflected in the Getting Started guide. For example, on Linux and macOS it is recommended to install CMake using an OS package manager. However, some of the tools are IDF-specific and are not available in OS package repositories. Furthermore, different versions of ESP-IDF require different versions of the tools to operate correctly. To solve these two problems, ESPIDF provides a set of scripts for downloading and installing the correct versions of tools, and exposing them in the environment.

Espressif Systems

1877

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
The rest of the document refers to these downloadable tools simply asotoolsp. Other kinds of tools used in ESP-IDF are:
· Python scripts bundled with ESP-IDF (such as idf.py) · Python packages installed from PyPI. The following sections explain the installation method, and provide the list of tools installed on each platform.
Note: This document is provided for advanced users who need to customize their installation, users who wish to understand the installation process, and ESP-IDF developers. If you are looking for instructions on how to install the tools, see the Getting Started Guide.
Tools metadata file
The list of tools and tool versions required for each platform is located in tools/tools.json. The schema of this file is defined by tools/tools_schema.json. This file is used by tools/idf_tools.py script when installing the tools or setting up the environment variables.
Tools installation directory
IDF_TOOLS_PATH environment variable specifies the location where the tools are to be downloaded and installed. If not set, IDF_TOOLS_PATH defaults to HOME/.espressif on Linux and macOS, and %USER_PROFILE%\ .espressif on Windows. Inside IDF_TOOLS_PATH, the scripts performing tools installation create the following directories and files:
· dist iwhere the archives of the tools are downloaded. · tools iwhere the tools are extracted. The tools are extracted into subdirectories: tools/TOOL_NAME/
VERSION/. This arrangement allows different versions of tools to be installed side by side. · idf-env.json iuser install options (targets, features) are stored in this file. Targets are selected chip
targets for which tools are installed and kept up-to-date. Features determine the Python package set which should be installed. These options will be discussed later. · python_env inot tools related; virtual Python environments are installed in the sub-directories. · espidf.constraints.*.txt ione constraint file for each ESP-IDF release containing Python package version requirements.
GitHub Assets Mirror
Most of the tools downloaded by the tools installer are GitHub Release Assets, which are files attached to a software release on GitHub. If GitHub downloads are inaccessible or slow to access, itns possible to configure a GitHub assets mirror. To use Espressifns download server, set the environment variable IDF_GITHUB_ASSETS to dl.espressif. com/github_assets. When the install process is downloading a tool from github.com, the URL will be rewritten to use this server instead. Any mirror server can be used provided the URL matches the github.com download URL format: the install process will replace https://github.com with https://${IDF_GITHUB_ASSETS} for any GitHub asset URL that it downloads.
Note: The Espressif download server doesnnt currently mirror everything from GitHub, it only mirrors files attached as Assets to some releases as well as source archives for some releases.

Espressif Systems

1878

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

idf_tools.py script
tools/idf_tools.py script bundled with ESP-IDF performs several functions:
· install: Download the tool into ${IDF_TOOLS_PATH}/dist directory, extract it into ${IDF_TOOLS_PATH}/tools/TOOL_NAME/VERSION. install command accepts the list of tools to install, in TOOL_NAME or TOOL_NAME@VERSION format. If all is given, all the tools (required and optional ones) are installed. If no argument or required is given, only the required tools are installed.
· download: Similar to install but doesnnt extract the tools. An optional --platform argument may be used to download the tools for the specific platform.
· export: Lists the environment variables which need to be set to use the installed tools. For most of the tools, setting PATH environment variable is sufficient, but some tools require extra environment variables. The environment variables can be listed in either of shell or key-value formats, set by --format parameter: ­ shell produces output suitable for evaluation in the shell. For example,
export PATH="/home/user/.espressif/tools/tool/v1.0.0/bin:$PATH"
on Linux and macOS, and
set "PATH=C:\Users\user\.espressif\tools\v1.0.0\bin;%PATH%"
on Windows.
Note: Exporting environment variables in Powershell format is not supported at the moment. keyvalue format may be used instead.
The output of this command may be used to update the environment variables, if the shell supports this. For example:
eval $($IDF_PATH/tools/idf_tools.py export)
­ key-value produces output in VARIABLE=VALUE format, suitable for parsing by other scripts:
PATH=/home/user/.espressif/tools/tool/v1.0.0:$PATH
Note that the script consuming this output has to perform expansion of $VAR or %VAR% patterns found in the output. · list: Lists the known versions of the tools, and indicates which ones are installed. · check: For each tool, checks whether the tool is available in the system path and in IDF_TOOLS_PATH. · install-python-env: Create a Python virtual environment in the ${IDF_TOOLS_PATH}/ python_env directory and install there the required Python packages. An optional --features argument allows one to specify a comma-separated list of features. For each feature a requirements file must exist. For example, feature XY is a valid feature if ${IDF_PATH}/requirements.XY.txt is an existing file with a list of Python packages to be installed. There is one mandatory core feature ensuring core functionality of ESP-IDF (build, flash, monitor, debug in console). There can be an arbitrary number of optional features. The selected list of features is stored in idf-env.json. The requirement files contain a list of the desired Python packages to be installed and espidf.constraints.*.txt downloaded from https://dl.espressif.com and stored in ${IDF_TOOLS_PATH} the package version requirements for a given ESP-IDF version. · check-python-dependencies: Checks if all required Python packages are installed. Packages from ${IDF_PATH}/requirements.*.txt files selected by the feature list of idf-env.json are checked with the package versions specified in the espidf.constraints.*.txt file. The constraint file will be downloaded from https://dl.espressif.com if this step hasnnt been done already in the last day.
Install scripts
Shell-specific user-facing scripts are provided in the root of ESP-IDF repository to facilitate tools installation. These are:
· install.bat for Windows Command Prompt

Espressif Systems

1879

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· install.ps1 for Powershell · install.sh for Bash · install.fish for Fish Aside from downloading and installing the tools into IDF_TOOLS_PATH, these scripts prepare a Python virtual environment, and install the required packages into that environment. These scripts accept optionally a comma separated list of chip targets and --enable-* arguments for enabling features. These arguments are passed to the idf_tools.py script which stores them in idf-env.json. Therefore, chip targets and features can be enabled incrementally. Running the scripts without any optional arguments will install tools for all chip targets (by running idf_tools.py install --targets=all) and Python packages for core ESP-IDF functionality (by running idf_tools.py install-python-env --features=core). Or for example, install.sh esp32 will install tools only for ESP32. See the Getting Started Guide for more examples. install.sh --enable-XY will enable feature XY (by running idf_tools.py install-python-env --features=core,XY).
Export scripts
Since the installed tools are not permanently added into the user or system PATH environment variable, an extra step is required to use them in the command line. The following scripts modify the environment variables in the current shell to make the correct versions of the tools available:
· export.bat for Windows Command Prompt · export.ps1 for Powershell · export.sh for Bash · export.fish for Fish
Note: To modify the shell environment in Bash, export.sh must be osourcedp: . ./export.sh (note the leading dot and space). export.sh may be used with shells other than Bash (such as zsh). However in this case the IDF_PATH environment variable must be set before running the script. When used in Bash, the script will guess the IDF_PATH value from its own location.
In addition to calling idf_tools.py, these scripts list the directories which have been added to the PATH.
Other installation methods
Depending on the environment, more user-friendly wrappers for idf_tools.py are provided: · IDF Tools installer for Windows can download and install the tools. Internally the installer uses idf_tools. py. · Eclipse plugin for ESP-IDF includes a menu item to set up the tools. Internally the plugin calls idf_tools. py. · Visual Studio Code extension for ESP-IDF includes an onboarding flow. This flow helps setting up the tools. Although the extension does not rely on idf_tools.py, the same installation method is used.
Custom installation
Although the methods above are recommended for ESP-IDF users, they are not a must for building ESP-IDF applications. ESP-IDF build system expects that all the necessary tools are installed somewhere, and made available in the PATH.

Espressif Systems

1880

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

List of IDF Tools

xtensa-esp32-elf Toolchain for Xtensa (ESP32) based on GCC License: GPL-3.0-with-GCC-exception More info: https://github.com/espressif/crosstool-NG

Platform Required Download

linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

amd64

xtensa-esp32-elf-gcc8_4_0-esp-2021r2-linux-amd64.tar.gz

SHA256: 3eb3d68b27fa6ba5af6f88da21cb8face9be0094daaa8960793cfe570ab785ff

linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

arm64

xtensa-esp32-elf-gcc8_4_0-esp-2021r2-linux-arm64.tar.gz

SHA256: aa534be24e45e06b7080a6a3bb8cd9e3cfb818f5f8bce2244d7cfb5e91336541

linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

armel

xtensa-esp32-elf-gcc8_4_0-esp-2021r2-linux-armel.tar.gz

SHA256: f0e49ce06fe7833ff5d76961dc2dac5449d320f823bb8c05a302cf85a3a6eb04

linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

i686

xtensa-esp32-elf-gcc8_4_0-esp-2021r2-linux-i686.tar.gz

SHA256: 06de09b74652de43e5b22db3b7fc992623044baa75e9faaab68317a986715ba3

macos required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

xtensa-esp32-elf-gcc8_4_0-esp-2021r2-macos.tar.gz

SHA256: 96443f69c8569417c780ee749d91ef33cffe22153fffa30a0fbf12107d87381b

win32 required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

xtensa-esp32-elf-gcc8_4_0-esp-2021r2-patch2-win32.zip

SHA256: c14cc88ddeff6d5494497de33fb5783268c6a171b3bb8c745aafae58507e2356

win64 required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

xtensa-esp32-elf-gcc8_4_0-esp-2021r2-patch2-win64.zip

SHA256: 68db46ed4f188e169b922d43215eea781de28f847e7caed3acd5991d0bfb67bd

xtensa-esp32s2-elf Toolchain for Xtensa (ESP32-S2) based on GCC License: GPL-3.0-with-GCC-exception More info: https://github.com/espressif/crosstool-NG

Espressif Systems

1881

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Platform Required Download

linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

amd64

xtensa-esp32s2-elf-gcc8_4_0-esp-2021r2-linux-amd64.tar.gz

SHA256: a6e0947c92b823ca04f062522249f0a428357e0b056f1ff4c6bcabef83cf63a7

linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

arm64

xtensa-esp32s2-elf-gcc8_4_0-esp-2021r2-linux-arm64.tar.gz

SHA256: d2e5600fc194b508bd393b236a09fd62ed70afb6c36619d4b106b696a56ca66d

linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

armel

xtensa-esp32s2-elf-gcc8_4_0-esp-2021r2-linux-armel.tar.gz

SHA256: 3fff4199e986dd74660f17ca27d9414cb98f1b911a7f13bb3b22e784cb1156cf

linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

i686

xtensa-esp32s2-elf-gcc8_4_0-esp-2021r2-linux-i686.tar.gz

SHA256: 7732f9fb371d36b6b324820e300beecc33c2719921a61cf1cdb5bc625016b346

macos required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

xtensa-esp32s2-elf-gcc8_4_0-esp-2021r2-macos.tar.gz

SHA256: e6dd32782fcff8f633299b97d1c671d6b6513390aca2ddbd7543c2cc62e72d7e

win32 required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

xtensa-esp32s2-elf-gcc8_4_0-esp-2021r2-patch2-win32.zip

SHA256: 2c6aea1a132c6caa5a71cb5389b43454276bf097c98bb25d5bb778ed65036aef

win64 required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

xtensa-esp32s2-elf-gcc8_4_0-esp-2021r2-patch2-win64.zip

SHA256: 2d57cb5d897592cf0abdae94d1d673cdad294007f6210a96f34e7cd9f26c48a1

xtensa-esp32s3-elf Toolchain for Xtensa (ESP32-S3) based on GCC License: GPL-3.0-with-GCC-exception More info: https://github.com/espressif/crosstool-NG

Platform Required Download

linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

amd64

xtensa-esp32s3-elf-gcc8_4_0-esp-2021r2-linux-amd64.tar.gz

SHA256: b958eb47f51fc2a91e3beda78a331a380eb8c96d5452f7795adf3f565d7fca2f

linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

arm64

xtensa-esp32s3-elf-gcc8_4_0-esp-2021r2-linux-arm64.tar.gz

SHA256: 5fb122f1109a0b1aa7a42b6b48f56c854c0a84d13047a3bb0a78bdc737bf70e2

linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

armel

xtensa-esp32s3-elf-gcc8_4_0-esp-2021r2-linux-armel.tar.gz

SHA256: d618be508629749110785ce0038b35959cc4e6953629e2dc6d65697425b905e1

linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

i686

xtensa-esp32s3-elf-gcc8_4_0-esp-2021r2-linux-i686.tar.gz

SHA256: 9701907da616992079d302acf5a04f97361b39ca3e74112690b2c896875f3a62

macos required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

xtensa-esp32s3-elf-gcc8_4_0-esp-2021r2-macos.tar.gz

SHA256: d417885a5d150d94b3b84f68460b7af399a789cb0c7c632e222feed666c8aaea

win32 required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

xtensa-esp32s3-elf-gcc8_4_0-esp-2021r2-patch2-win32.zip

SHA256: cfac4ec95f7cf64b7d81a66799e388062469d53ffb19698c2b30ccf78076e92f

win64 required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

xtensa-esp32s3-elf-gcc8_4_0-esp-2021r2-patch2-win64.zip

SHA256: 31c79edf0df6592da61869d5d85d8e8fd064f0a247f2a3849996facc17a9e972

xtensa-clang LLVM for Xtensa (ESP32, ESP32-S2) based on clang License: Apache-2.0 More info: https://github.com/espressif/llvm-project

Espressif Systems

1882

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Platform linuxamd64
macos
win64

Required Download optional https://github.com/espressif/llvm-project/releases/download/esp-12.0.1-20210914/
xtensa-esp32-elf-llvm12_0_1-esp-12.0.1-20210914-linux-amd64.tar.xz SHA256: d62d9234c702a86ed510777125ee97458204e28877806a73f9de5e41d7b65716 optional https://github.com/espressif/llvm-project/releases/download/esp-12.0.1-20210914/ xtensa-esp32-elf-llvm12_0_1-esp-12.0.1-20210914-macos.tar.xz SHA256: 6e7413e5fa515e403859ecf5301bdcdc3f8bf12c5de9aecaa11e9f17f32b05db optional https://github.com/espressif/llvm-project/releases/download/esp-12.0.1-20210914/ xtensa-esp32-elf-llvm12_0_1-esp-12.0.1-20210914-win64.zip SHA256: e056366959c722367e4144076c5383bd417ea199db5658bb7bb6c95b9aca014b

riscv32-esp-elf Toolchain for 32-bit RISC-V based on GCC License: GPL-3.0-with-GCC-exception More info: https://github.com/espressif/crosstool-NG

Platform Required Download

linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

amd64

riscv32-esp-elf-gcc8_4_0-esp-2021r2-linux-amd64.tar.gz

SHA256: 812d735063da9d063b374b59f55832a96c41fbd27ddaef19000a75de8607ba21

linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

arm64

riscv32-esp-elf-gcc8_4_0-esp-2021r2-linux-arm64.tar.gz

SHA256: 712f1fbc3e08304a6f32aa18b346b16bbcb413b507b3d4c7c3211bf0d7dc4813

linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

armel

riscv32-esp-elf-gcc8_4_0-esp-2021r2-linux-armel.tar.gz

SHA256: 80a3342cda2cd4b6b75ebb2b36d5d12fce7d375cfadadcff01ec3a907f0a16a2

linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

i686

riscv32-esp-elf-gcc8_4_0-esp-2021r2-linux-i686.tar.gz

SHA256: 7f0162a81558ab0ed09d6c5d356def25b5cb3d5c2d61358f20152fa260ccc8ae

macos required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

riscv32-esp-elf-gcc8_4_0-esp-2021r2-macos.tar.gz

SHA256: 3ff7e5427907cf8e271c1f959b70fb01e39625c3caf61a6567e7b38aa0c11578

win32 required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

riscv32-esp-elf-gcc8_4_0-esp-2021r2-patch2-win32.zip

SHA256: 937566910600d3d5b4ef6f272084fe59ea82dc3711b260a601be7487ef7a4626

win64 required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/

riscv32-esp-elf-gcc8_4_0-esp-2021r2-patch2-win64.zip

SHA256: 40570481ba0d78f7a51e523ce2e7d144b55352071adeeda0d7e81161c6c73245

esp32ulp-elf Toolchain for ESP32 ULP coprocessor License: GPL-2.0-or-later More info: https://github.com/espressif/binutils-esp32ulp

Espressif Systems

1883

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Platform Required Download

linux- required https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.

amd64

51-esp-20191205/binutils-esp32ulp-linux-amd64-2.28.51-esp-20191205.tar.gz

SHA256: 3016c4fc551181175bd9979869bc1d1f28fa8efa25a0e29ad7f833fca4bc03d7

linux- required https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.

armel

51-esp-20191205/binutils-esp32ulp-linux-armel-2.28.51-esp-20191205.tar.gz

SHA256: 88967c086a6e71834282d9ae05841ee74dae1815f27807b25cdd3f7775a47101

macos required https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.

51-esp-20191205/binutils-esp32ulp-macos-2.28.51-esp-20191205.tar.gz

SHA256: a35d9e7a0445247c7fc9dccd3fbc35682f0fafc28beeb10c94b59466317190c4

win32 required https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.

51-esp-20191205/binutils-esp32ulp-win32-2.28.51-esp-20191205.zip

SHA256: bade309353a9f0a4e5cc03bfe84845e33205f05502c4b199195e871ded271ab5

win64 required https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.

51-esp-20191205/binutils-esp32ulp-win32-2.28.51-esp-20191205.zip

SHA256: bade309353a9f0a4e5cc03bfe84845e33205f05502c4b199195e871ded271ab5

esp32s2ulp-elf Toolchain for ESP32-S2 and ESP32-S3 ULP coprocessors License: GPL-2.0-or-later More info: https://github.com/espressif/binutils-esp32ulp

Platform Required Download

linux- required https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.

amd64

51-esp-20191205/binutils-esp32s2ulp-linux-amd64-2.28.51-esp-20191205.tar.gz

SHA256: df7b2ff6c7c718a7cbe3b4b6dbcd68180d835d164d1913bc4698fd3781b9a466

linux- required https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.

armel

51-esp-20191205/binutils-esp32s2ulp-linux-armel-2.28.51-esp-20191205.tar.gz

SHA256: 893b213c8f716d455a6efb2b08b6cf1bc34d08b78ee19c31e82ac44b1b45417e

macos required https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.

51-esp-20191205/binutils-esp32s2ulp-macos-2.28.51-esp-20191205.tar.gz

SHA256: 5a9bb678a5246638cbda303f523d9bb8121a9a24dc01ecb22c21c46c41184155

win32 required https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.

51-esp-20191205/binutils-esp32s2ulp-win32-2.28.51-esp-20191205.zip

SHA256: 587de59fbb469a39f96168ae3eaa9f06b2601e6e0543c87eaf1bd97f23e5c4ca

win64 required https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.

51-esp-20191205/binutils-esp32s2ulp-win32-2.28.51-esp-20191205.zip

SHA256: 587de59fbb469a39f96168ae3eaa9f06b2601e6e0543c87eaf1bd97f23e5c4ca

cmake CMake build system On Linux and macOS, it is recommended to install CMake using the OS-specific package manager (like apt, yum, brew, etc.). However, for convenience it is possible to install CMake using idf_tools.py along with the other tools. License: BSD-3-Clause More info: https://github.com/Kitware/CMake

Espressif Systems

1884

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Platform Required Download

linux- optional https://github.com/Kitware/CMake/releases/download/v3.20.3/cmake-3.20.

amd64

3-linux-x86_64.tar.gz

SHA256: 97bf730372f9900b2dfb9206fccbcf92f5c7f3b502148b832e77451aa0f9e0e6

linux- optional https://github.com/Kitware/CMake/releases/download/v3.20.3/cmake-3.20.

arm64

3-linux-aarch64.tar.gz

SHA256: 77620f99e9d5f39cf4a49294c6a68c89a978ecef144894618974b9958efe3c2a

linux- optional https://dl.espressif.com/dl/cmake/cmake-3.20.3-Linux-armv7l.tar.gz

armel

SHA256: f8bd050c2745f0dcc4b7cef9738bbfef775950a10f5bd377abb0062835e669dc

macos optional https://github.com/Kitware/CMake/releases/download/v3.20.3/cmake-3.20.

3-macos-universal.tar.gz

SHA256: 5f72dba3aa5f3800fb29ab6115ae0b31f10bdb2aad66204e14c98f6ac7e6b6ed

win32 required https://github.com/Kitware/CMake/releases/download/v3.20.3/cmake-3.20.

3-windows-x86_64.zip

SHA256: e276cf7fbb3e3e88bc666e183bc3ddaceb143a4c83fb357b1dbb1a26fd6e4ea2

win64 required https://github.com/Kitware/CMake/releases/download/v3.20.3/cmake-3.20.

3-windows-x86_64.zip

SHA256: e276cf7fbb3e3e88bc666e183bc3ddaceb143a4c83fb357b1dbb1a26fd6e4ea2

openocd-esp32 OpenOCD for ESP32 License: GPL-2.0-only More info: https://github.com/espressif/openocd-esp32

Platform Required Download

linux- required https://github.com/espressif/openocd-esp32/releases/download/v0.11.

amd64

0-esp32-20211220/openocd-esp32-linux-amd64-0.11.0-esp32-20211220.tar.gz

SHA256: 3460945f3560ef673264a0259a33dcbf0dd18ac6b7b4862e89318655c62215c7

linux- required https://github.com/espressif/openocd-esp32/releases/download/v0.11.

arm64

0-esp32-20211220/openocd-esp32-linux-arm64-0.11.0-esp32-20211220.tar.gz

SHA256: 65d4de147d37c04e1c65d020e9c38e90db5a71e9e0bc602f5c8e0f44e46cd098

linux- required https://github.com/espressif/openocd-esp32/releases/download/v0.11.

armel

0-esp32-20211220/openocd-esp32-linux-armel-0.11.0-esp32-20211220.tar.gz

SHA256: 4c03c5fdf73d9a4357cb5e2918c8e3d99900c7a1bb6d50e8712a8d38477398a0

linux- required https://github.com/espressif/openocd-esp32/releases/download/v0.11.

armhf

0-esp32-20211220/openocd-esp32-linux-armhf-0.11.0-esp32-20211220.tar.gz

SHA256: acbb2bf74454ad2e45bab690538082cd6538a687ba2ba3d233309eb985702aba

macos required https://github.com/espressif/openocd-esp32/releases/download/v0.11.

0-esp32-20211220/openocd-esp32-macos-0.11.0-esp32-20211220.tar.gz

SHA256: 689149120965a8c36c78c1852035b72f500f2a5b406f53624ed4c0a85c4e9a60

win32 required https://github.com/espressif/openocd-esp32/releases/download/v0.11.

0-esp32-20211220/openocd-esp32-win32-0.11.0-esp32-20211220.zip

SHA256: 18f5515c4cecce5866e2f7cc7ff536f1a21a624e40a61d24c9dea4a910657cbb

win64 required https://github.com/espressif/openocd-esp32/releases/download/v0.11.

0-esp32-20211220/openocd-esp32-win32-0.11.0-esp32-20211220.zip

SHA256: 18f5515c4cecce5866e2f7cc7ff536f1a21a624e40a61d24c9dea4a910657cbb

ninja Ninja build system On Linux and macOS, it is recommended to install ninja using the OS-specific package manager (like apt, yum, brew, etc.). However, for convenience it is possible to install ninja using idf_tools.py along with the other tools. License: Apache-2.0 More info: https://github.com/ninja-build/ninja

Espressif Systems

1885

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Platform linuxamd64 macos
win64

Required Download optional https://dl.espressif.com/dl/ninja-1.10.2-linux64.tar.gz
SHA256: 32bb769de4d57aa7ee0e292cfcb7553e7cc8ea0961f7aa2b3aee60aa407c4033 optional https://dl.espressif.com/dl/ninja-1.10.2-osx.tar.gz
SHA256: 847bb1ca4bc16d8dba6aeed3ecb5055498b86bc68c364c37583eb5738bb440f1 required https://dl.espressif.com/dl/ninja-1.10.2-win64.zip
SHA256: bbde850d247d2737c5764c927d1071cbb1f1957dcabda4a130fa8547c12c695f

idf-exe IDF wrapper tool for Windows License: Apache-2.0 More info: https://github.com/espressif/idf_py_exe_tool

Platform win32
win64

Required Download required https://github.com/espressif/idf_py_exe_tool/releases/download/v1.0.3/idf-exe-v1.0.3.
zip SHA256: 7c81ef534c562354a5402ab6b90a6eb1cc8473a9f4a7b7a7f93ebbd23b4a2755 required https://github.com/espressif/idf_py_exe_tool/releases/download/v1.0.3/idf-exe-v1.0.3. zip SHA256: 7c81ef534c562354a5402ab6b90a6eb1cc8473a9f4a7b7a7f93ebbd23b4a2755

ccache Ccache (compiler cache) License: GPL-3.0-or-later More info: https://github.com/ccache/ccache
Platform Required Download win64 required https://github.com/ccache/ccache/releases/download/v4.3/ccache-4.3-windows-64.zip
SHA256: a9cacae73c3906d8193456328bee74f7748cb1559a32eaced9ee78eadd416105

dfu-util dfu-util (Device Firmware Upgrade Utilities) License: GPL-2.0-only More info: http://dfu-util.sourceforge.net/
Platform Required Download win64 required https://dl.espressif.com/dl/dfu-util-0.9-win64.zip
SHA256: 5816d7ec68ef3ac07b5ac9fb9837c57d2efe45b6a80a2f2bbe6b40b1c15c470e

4.30.2 IDF Docker Image
IDF Docker image (espressif/idf) is intended for building applications and libraries with specific versions of ESP-IDF, when doing automated builds.
The image contains:
· Common utilities such as git, wget, curl, zip. · Python 3.6 or newer. · A copy of a specific version of ESP-IDF (see below for information about versions). IDF_PATH environment
variable is set, and points to ESP-IDF location in the container. · All the build tools required for the specific version of ESP-IDF: CMake, ninja, cross-compiler toolchains, etc. · All Python packages required by ESP-IDF are installed in a virtual environment.

Espressif Systems

1886

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
The image entrypoint sets up PATH environment variable to point to the correct version of tools, and activates the Python virtual environment. As a result, the environment is ready to use the ESP-IDF build system. The image can also be used as a base for custom images, if additional utilities are required.
Tags
Multiple tags of this image are maintained: · latest: tracks master branch of ESP-IDF · vX.Y: corresponds to ESP-IDF release vX.Y · release-vX.Y: tracks release/vX.Y branch of ESP-IDF
Note: Versions of ESP-IDF released before this feature was introduced do not have corresponding Docker image versions. You can check the up-to-date list of available tags at https://hub.docker.com/r/espressif/idf/tags.
Usage
Setting up Docker Before using the espressif/idf Docker image locally, make sure you have Docker installed. Follow the instructions at https://docs.docker.com/install/, if it is not installed yet. If using the image in CI environment, consult the documentation of your CI service on how to specify the image used for the build process.
Building a project with CMake In the project directory, run: docker run --rm -v $PWD:/project -w /project espressif/idf idf.py build
The above command explained: · docker run: runs a Docker image. It is a shorter form of the command docker container run. · --rm: removes the container when the build is finished · -v $PWD:/project: mounts the current directory on the host ($PWD) as /project directory in the container · espressif/idf: uses Docker image espressif/idf with tag latest (implicitly added by Docker when no tag is specified) · idf.py build: runs this command inside the container
To build with a specific docker image tag, specify it as espressif/idf:TAG, for example: docker run --rm -v $PWD:/project -w /project espressif/idf:release-v4.0 idf.py build
You can check the up-to-date list of available tags at https://hub.docker.com/r/espressif/idf/tags.
Using the image interactively It is also possible to do builds interactively, to debug build issues or test the automated build scripts. Start the container with -i -t flags: docker run --rm -v $PWD:/project -w /project -it espressif/idf
Then inside the container, use idf.py as usual: idf.py menuconfig idf.py build

Espressif Systems

1887

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Note: Commands which communicate with the development board, such as idf.py flash and idf.py monitor will not work in the container unless the serial port is passed through into the container. However currently this is not possible with Docker for Windows (https://github.com/docker/for-win/issues/1018) and Docker for Mac (https://github.com/docker/for-mac/issues/900).

4.30.3 IDF Windows Installer
Command-line parameters
Windows Installer esp-idf-tools-setup provides the following command-line parameters:
· /CONFIG=[PATH] - Path to ini configuration file to override default configuration of the installer. Default: config.ini.
· /GITCLEAN=[yes|no] - Perform git clean and remove untracked directories in Offline mode installation. Default: yes.
· /GITRECURSIVE=[yes|no] - Clone recursively all git repository submodules. Default: yes · /GITREPO=[URL|PATH] - URL of repository to clone ESP-IDF. Default: https://github.com/espressif/
esp-idf.git · /GITRESET=[yes|no] - Enable/Disable git reset of repository during installation. Default: yes. · /HELP - Display command line options provided by Inno Setup installer. · /IDFDIR=[PATH] - Path to directory where it will be installed. Default: {userdesktop}\esp-idf} · /IDFVERSION=[v4.3|v4.1|master] - Use specific IDF version. E.g. v4.1, v4.2, master. Default:
empty, pick the first version in the list. · /IDFVERSIONSURL=[URL] - Use URL to download list of IDF versions. Default: https://dl.espressif.
com/dl/esp-idf/idf_versions.txt · /LOG=[PATH] - Store installation log file in specific directory. Default: empty. · /OFFLINE=[yes|no] - Execute installation of Python packages by PIP in offline mode. The same result
can be achieved by setting the environment variable PIP_NO_INDEX. Default: no. · /USEEMBEDDEDPYTHON=[yes|no] - Use Embedded Python version for the installation. Set to no to
allow Python selection screen in the installer. Default: yes. · /PYTHONNOUSERSITE=[yes|no] - Set PYTHONNOUSERSITE variable before launching any Python
command to avoid loading Python packages from AppDataRoaming. Default: yes. · /PYTHONWHEELSURL=[URL] - Specify URLs to PyPi repositories for resolving binary Python Wheel de-
pendencies. The same result can be achieved by setting the environment variable PIP_EXTRA_INDEX_URL. Default: https://dl.espressif.com/pypi · /SKIPSYSTEMCHECK=[yes|no] - Skip System Check page. Default: no. · /VERYSILENT /SUPPRESSMSGBOXES /SP- /NOCANCEL - Perform silent installation.
Unattended installation
The unattended installation of IDF can be achieved by following command-line parameters:
esp-idf-tools-setup-x.x.exe /VERYSILENT /SUPPRESSMSGBOXES /SP- /NOCANCEL
The installer detaches its process from the command-line. Waiting for installation to finish could be achieved by following PowerShell script:
esp-idf-tools-setup-x.x.exe /VERYSILENT /SUPPRESSMSGBOXES /SP- /NOCANCEL $InstallerProcess = Get-Process esp-idf-tools-setup Wait-Process -Id $InstallerProcess.id

Custom Python and custom location of Python wheels The IDF installer is using by default embedded Python with reference to Python Wheel mirror.

Espressif Systems

1888

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Following parameters allows to select custom Python and custom location of Python wheels:
esp-idf-tools-setup-x.x.exe /USEEMBEDDEDPYTHON=no /PYTHONWHEELSURL=https://pypi. org/simple/

4.30.4 IDF Component Manager
The IDF Component manager is a tool that downloads dependencies for any ESP-IDF CMake project. The download happens automatically during a run of CMake. It can source components either from the component registry or from a git repository. A list of components can be found on https://components.espressif.com/

Activating the Component Manager
If CMake is started using idf.py or ESP-IDF VSCode Extension then the component manager will be activated by default.
If CMake is used directly or with some CMake-based IDE like CLion, itns necessary to set the IDF_COMPONENT_MANAGER environment variable to 1 to enable the component manager integration with the build system.

Using with a project
Dependencies for each component in the project are defined in a separate manifest file named idf_component. yml placed in the root of the component. The manifest file template can be created for a component by running idf.py create-manifest --component=my_component. When a new manifest is added to one of the components in the project itns necessary to reconfigure it manually by running idf.py reconfigure. Then build will track changes in idf_component.yml manifests and automatically triggers CMake when necessary.
There is an example application: example:build_system/cmake/component_manager that uses components installed by the component manager.
Itns not necessary to have a manifest for components that donnt need any managed dependencies.
When CMake configures the project (e.g. idf.py reconfigure) component manager does a few things:
· Processes idf_component.yml manifests for every component in the project and recursively solves dependencies
· Creates a dependencies.lock file in the root of the project with a full list of dependencies · Downloads all dependencies to the managed_components directory
The lock-file dependencies.lock and content of managed_components directory is not supposed to be modified by a user. When the component manager runs it always make sure they are up to date. If these files were accidentally modified itns possible to re-run the component manager by triggering CMake with idf.py reconfigure

Defining dependencies in the manifest
dependencies: # Required IDF version idf: ">=4.1" # Defining a dependency from the registry: # https://components.espressif.com/component/example/cmp example/cmp: ">=1.0.0"
# # Other ways to define dependencies #

(continues on next page)

Espressif Systems

1889

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
(continued from previous page) # # For components maintained by Espressif only name can be used. # # Same as `espressif/cmp` # component: "~1.0.0" # # # Or in a longer form with extra parameters # component2: # version: ">=2.0.0" # # # For transient dependencies `public` flag can be set. # # `public` flag doesn't affect the `main` component. # # All dependencies of `main` are public by default. # public: true # # # For components hosted on non-default registry: # service_url: "https://componentregistry.company.com" # # # For components in git repository: # test_component: # path: test_component # git: ssh://[email protected]/user/components.git # # # For test projects during component development # # components can be used from a local directory # # with relative or absolute path # some_local_component: # path: ../../projects/component
4.30.5 IDF Clang Tidy
The IDF Clang Tidy is a tool that uses clang-tidy to run static analysis on your current app.
Warning: This functionality and the toolchain it relies on are still under development. There may be breaking changes before a final release.
Prerequisites
If you have never run this tool before, take the following steps to get this tool prepared.
1. Run the export scripts (export.sh / export.bat / l) to set up the environment variables. 2. Run pip install --upgrade pyclang to install this plugin. The extra commands would be activated
in idf.py automatically. 3. Run idf_tools.py install xtensa-clang to install the clang-tidy required binaries
Note: This toolchain is still under development. After the final release, you donnt have to install them manually.
4. Get file from the llvm repository and add the folder of this script to the $PATH. Or you could pass an optional argument --run-clang-tidy-py later when you call idf.py clang-check.
Note: This file would be bundled in future toolchain releases. This is a temporary workaround.
5. Run the export scripts (export.sh / export.bat / l) again to refresh the environment variables.

Espressif Systems

1890

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Extra Commands clang-check Run idf.py clang-check to re-generate the compilation database and run clang-tidy under your current project folder. The output would be written to <project_dir>/warnings.txt. Run idf.py clang-check --help to see the full documentation.
clang-html-report 1. Run pip install codereport to install the additional dependency. 2. Run idf.py clang-html-report to generate an HTML report in folder <project_dir>/ html_report according to the warnings.txt. Please open the <project_dir>/html_report/ index.html in your browser to check the report.
Bug Report This tool is hosted in espressif/clang-tidy-runner. If you faced any bugs or have any feature request, please report them via github issues.
4.31 ULP Coprocessor programming

Warning: This feature is not supported in v4.4

4.31.1 Programming ULP FSM coprocessor using C macros (legacy)

In addition to the existing binutils port for the ESP32 ULP coprocessor, it is possible to generate programs for the ULP by embedding assembly-like macros into an ESP32 application. Here is an example how this can be done:

const ulp_insn_t program[] = {

I_MOVI(R3, 16),

// R3 <- 16

I_LD(R0, R3, 0),

// R0 <- RTC_SLOW_MEM[R3 + 0]

I_LD(R1, R3, 1),

// R1 <- RTC_SLOW_MEM[R3 + 1]

I_ADDR(R2, R0, R1),

// R2 <- R0 + R1

I_ST(R2, R3, 2),

// R2 -> RTC_SLOW_MEM[R2 + 2]

I_HALT()

};

size_t load_addr = 0;

size_t size = sizeof(program)/sizeof(ulp_insn_t);

ulp_process_macros_and_load(load_addr, program, &size);

ulp_run(load_addr);

The program array is an array of ulp_insn_t, i.e. ULP coprocessor instructions. Each I_XXX preprocessor define translates into a single 32-bit instruction. Arguments of these preprocessor defines can be register numbers (R0 iR3) and literal constants. See ULP coprocessor instruction defines section for descriptions of instructions and arguments they take.

Note: Because some of the instruction macros expand to inline function calls, defining such array in global scope will cause the compiler to produce anoinitializer element is not constantperror. To fix this error, move the definition of instructions array into local scope.

Load and store instructions use addresses expressed in 32-bit words. Address 0 corresponds to the first word of RTC_SLOW_MEM (which is address 0x50000000 as seen by the main CPUs).

Espressif Systems

1891

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

To generate branch instructions, special M_ preprocessor defines are used. M_LABEL define can be used to define a branch target. Label identifier is a 16-bit integer. M_Bxxx defines can be used to generate branch instructions with target set to a particular label.
Implementation note: these M_ preprocessor defines will be translated into two ulp_insn_t values: one is a token value which contains label number, and the other is the actual instruction. ulp_process_macros_and_load function resolves the label number to the address, modifies the branch instruction to use the correct address, and removes the the extra ulp_insn_t token which contains the label numer.
Here is an example of using labels and branches:

const ulp_insn_t program[] = {

I_MOVI(R0, 34),

// R0 <- 34

M_LABEL(1),

// label_1

I_MOVI(R1, 32),

// R1 <- 32

I_LD(R1, R1, 0),

// R1 <- RTC_SLOW_MEM[R1]

I_MOVI(R2, 33),

// R2 <- 33

I_LD(R2, R2, 0),

// R2 <- RTC_SLOW_MEM[R2]

I_SUBR(R3, R1, R2),

// R3 <- R1 - R2

I_ST(R3, R0, 0),

// R3 -> RTC_SLOW_MEM[R0 + 0]

I_ADDI(R0, R0, 1),

// R0++

M_BL(1, 64),

// if (R0 < 64) goto label_1

I_HALT(),

};

RTC_SLOW_MEM[32] = 42;

RTC_SLOW_MEM[33] = 18;

size_t load_addr = 0;

size_t size = sizeof(program)/sizeof(ulp_insn_t);

ulp_process_macros_and_load(load_addr, program, &size);

ulp_run(load_addr);

Application Example Demonstration of entering into deep sleep mode and waking up using several wake up sources: system/deep_sleep.

API Reference
Header File · ulp/ulp_fsm/include/esp32s3/ulp.h

Functions esp_err_t ulp_process_macros_and_load(uint32_t load_addr, const ulp_insn_t *program, size_t
*psize) Resolve all macro references in a program and load it into RTC memory.
Return · ESP_OK on success · ESP_ERR_NO_MEM if auxiliary temporary structure can not be allocated · one of ESP_ERR_ULP_xxx if program is not valid or can not be loaded
Parameters · load_addr: address where the program should be loaded, expressed in 32-bit words · program: ulp_insn_t array with the program · psize: size of the program, expressed in 32-bit words
esp_err_t ulp_run(uint32_t entry_point) Run the program loaded into RTC memory.
Return ESP_OK on success Parameters
· entry_point: entry point, expressed in 32-bit words

Espressif Systems

1892

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Error codes ESP_ERR_ULP_BASE
Offset for ULP-related error codes ESP_ERR_ULP_SIZE_TOO_BIG
Program doesnnt fit into RTC memory reserved for the ULP
ESP_ERR_ULP_INVALID_LOAD_ADDR Load address is outside of RTC memory reserved for the ULP
ESP_ERR_ULP_DUPLICATE_LABEL More than one label with the same number was defined
ESP_ERR_ULP_UNDEFINED_LABEL Branch instructions references an undefined label
ESP_ERR_ULP_BRANCH_OUT_OF_RANGE Branch target is out of range of B instruction (try replacing with BX)
ULP coprocessor registers ULP co-processor has 4 16-bit general purpose registers. All registers have same functionality, with one exception. R0 register is used by some of the compare-and-branch instructions as a source register.
These definitions can be used for all instructions which require a register.
R0 general purpose register 0
R1 general purpose register 1
R2 general purpose register 2
R3 general purpose register 3
ULP coprocessor instruction defines I_DELAY(cycles_)
Delay (nop) for a given number of cycles I_HALT()
Halt the coprocessor.
This instruction halts the coprocessor, but keeps ULP timer active. As such, ULP program will be restarted again by timer. To stop the program and prevent the timer from restarting the program, use I_END(0) instruction.
I_END() Stop ULP program timer.
This is a convenience macro which disables the ULP program timer. Once this instruction is used, ULP program will not be restarted anymore until ulp_run function is called.
ULP program will continue running after this instruction. To stop the currently running program, use I_HALT().
I_ST(reg_val, reg_addr, offset_) Store value from register reg_val into RTC memory.
The value is written to an offset calculated by adding value of reg_addr register and offset_ field (this offset is expressed in 32-bit words). 32 bits written to RTC memory are built as follows:
· bits [31:21] hold the PC of current instruction, expressed in 32-bit words · bits [20:16] = 5nb1 · bits [15:0] are assigned the contents of reg_val

Espressif Systems

1893

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
RTC_SLOW_MEM[addr + offset_] = { 5nb0, insn_PC[10:0], val[15:0] }
I_LD(reg_dest, reg_addr, offset_) Load value from RTC memory into reg_dest register.
Loads 16 LSBs from RTC memory word given by the sum of value in reg_addr and value of offset_.
I_WR_REG(reg, low_bit, high_bit, val) Write literal value to a peripheral register
reg[high_bit : low_bit] = val This instruction can access RTC_CNTL_, RTC_IO_, SENS_, and RTC_I2C peripheral registers.
I_RD_REG(reg, low_bit, high_bit) Read from peripheral register into R0
R0 = reg[high_bit : low_bit] This instruction can access RTC_CNTL_, RTC_IO_, SENS_, and RTC_I2C peripheral registers.
I_BL(pc_offset, imm_value) Branch relative if R0 less than immediate value.
pc_offset is expressed in words, and can be from -127 to 127 imm_value is a 16-bit value to compare R0 against
I_BGE(pc_offset, imm_value) Branch relative if R0 greater or equal than immediate value.
pc_offset is expressed in words, and can be from -127 to 127 imm_value is a 16-bit value to compare R0 against
I_BXR(reg_pc) Unconditional branch to absolute PC, address in register.
reg_pc is the register which contains address to jump to. Address is expressed in 32-bit words.
I_BXI(imm_pc) Unconditional branch to absolute PC, immediate address.
Address imm_pc is expressed in 32-bit words.
I_BXZR(reg_pc) Branch to absolute PC if ALU result is zero, address in register.
reg_pc is the register which contains address to jump to. Address is expressed in 32-bit words.
I_BXZI(imm_pc) Branch to absolute PC if ALU result is zero, immediate address.
Address imm_pc is expressed in 32-bit words.
I_BXFR(reg_pc) Branch to absolute PC if ALU overflow, address in register
reg_pc is the register which contains address to jump to. Address is expressed in 32-bit words.
I_BXFI(imm_pc) Branch to absolute PC if ALU overflow, immediate address
Address imm_pc is expressed in 32-bit words.
I_ADDR(reg_dest, reg_src1, reg_src2) Addition: dest = src1 + src2
I_SUBR(reg_dest, reg_src1, reg_src2) Subtraction: dest = src1 - src2
I_ANDR(reg_dest, reg_src1, reg_src2) Logical AND: dest = src1 & src2

Espressif Systems

1894

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
I_ORR(reg_dest, reg_src1, reg_src2) Logical OR: dest = src1 | src2
I_MOVR(reg_dest, reg_src) Copy: dest = src
I_LSHR(reg_dest, reg_src, reg_shift) Logical shift left: dest = src << shift
I_RSHR(reg_dest, reg_src, reg_shift) Logical shift right: dest = src >> shift
I_ADDI(reg_dest, reg_src, imm_) Add register and an immediate value: dest = src1 + imm
I_SUBI(reg_dest, reg_src, imm_) Subtract register and an immediate value: dest = src - imm
I_ANDI(reg_dest, reg_src, imm_) Logical AND register and an immediate value: dest = src & imm
I_ORI(reg_dest, reg_src, imm_) Logical OR register and an immediate value: dest = src | imm
I_MOVI(reg_dest, imm_) Copy an immediate value into register: dest = imm
I_LSHI(reg_dest, reg_src, imm_) Logical shift left register value by an immediate: dest = src << imm
I_RSHI(reg_dest, reg_src, imm_) Logical shift right register value by an immediate: dest = val >> imm
M_LABEL(label_num) Define a label with number label_num.
This is a macro which doesnnt generate a real instruction. The token generated by this macro is removed by ulp_process_macros_and_load function. Label defined using this macro can be used in branch macros defined below.
M_BL(label_num, imm_value) Macro: branch to label label_num if R0 is less than immediate value.
This macro generates two ulp_insn_t values separated by a comma, and should be used when defining contents of ulp_insn_t arrays. First value is not a real instruction; it is a token which is removed by ulp_process_macros_and_load function.
M_BGE(label_num, imm_value) Macro: branch to label label_num if R0 is greater or equal than immediate value
This macro generates two ulp_insn_t values separated by a comma, and should be used when defining contents of ulp_insn_t arrays. First value is not a real instruction; it is a token which is removed by ulp_process_macros_and_load function.
M_BX(label_num) Macro: unconditional branch to label
This macro generates two ulp_insn_t values separated by a comma, and should be used when defining contents of ulp_insn_t arrays. First value is not a real instruction; it is a token which is removed by ulp_process_macros_and_load function.
M_BXZ(label_num) Macro: branch to label if ALU result is zero
This macro generates two ulp_insn_t values separated by a comma, and should be used when defining contents of ulp_insn_t arrays. First value is not a real instruction; it is a token which is removed by ulp_process_macros_and_load function.

Espressif Systems

1895

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
M_BXF(label_num) Macro: branch to label if ALU overflow
This macro generates two ulp_insn_t values separated by a comma, and should be used when defining contents of ulp_insn_t arrays. First value is not a real instruction; it is a token which is removed by ulp_process_macros_and_load function.
Defines RTC_SLOW_MEM
RTC slow memory, 8k size The ULP (Ultra Low Power) coprocessor is a simple FSM (Finite State Machine) which is designed to perform measurements using the ADC, temperature sensor, and external I2C sensors, while the main processors are in deep sleep mode. The ULP coprocessor can access the RTC_SLOW_MEM memory region, and registers in RTC_CNTL, RTC_IO, and SARADC peripherals. The ULP coprocessor uses fixed-width 32-bit instructions, 32-bit memory addressing, and has 4 general-purpose 16-bit registers.
4.31.2 Installing the Toolchain
The ULP coprocessor code is written in assembly and compiled using the binutils-esp32ulp toolchain.
If you have already set up ESP-IDF with CMake build system according to the Getting Started Guide, then the ULP toolchain will already be installed.
4.31.3 Compiling the ULP Code
To compile the ULP code as part of the component, the following steps must be taken:
1. The ULP code, written in assembly, must be added to one or more files with .S extension. These files must be placed into a separate directory inside the component directory, for instance ulp/.
2. Call ulp_embed_binary from the component CMakeLists.txt after registration. For example:
... idf_component_register()
set(ulp_app_name ulp_${COMPONENT_NAME}) set(ulp_s_sources ulp/ulp_assembly_source_file.S) set(ulp_exp_dep_srcs "ulp_c_source_file.c")
ulp_embed_binary(${ulp_app_name} "${ulp_s_sources}" "${ulp_exp_dep_srcs}")
The first argument to ulp_embed_binary specifies the ULP binary name. The name specified here will also be used by other generated artifacts such as the ELF file, map file, header file and linker export file. The second argument specifies the ULP assembly source files. Finally, the third argument specifies the list of component source files which include the header file to be generated. This list is needed to build the dependencies correctly and ensure that the generated header file will be created before any of these files are compiled. See section below for the concept of generated header files for ULP applications.
3. Build the application as usual (e.g. idf.py app) Inside, the build system will take the following steps to build ULP program: 1. Run each assembly file (foo.S) through the C preprocessor. This step generates the preprocessed assembly files (foo.ulp.S) in the component build directory. This step also generates dependency files (foo.ulp.d). 2. Run preprocessed assembly sources through the assembler. This produces object (foo.ulp.o) and listing (foo.ulp.lst) files. Listing files are generated for debugging purposes and are not used at later stages of the build process. 3. Run the linker script template through the C preprocessor. The template is located in components/ulp/ld directory.

Espressif Systems

1896

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

4. Link the object files into an output ELF file (ulp_app_name.elf). The Map file (ulp_app_name.map) generated at this stage may be useful for debugging purposes.
5. Dump the contents of the ELF file into a binary (ulp_app_name.bin) which can then be embedded into the application.
6. Generate a list of global symbols (ulp_app_name.sym) in the ELF file using esp32ulp-elfnm.
7. Create an LD export script and header file (ulp_app_name.ld and ulp_app_name.h) containing the symbols from ulp_app_name.sym. This is done using the esp32ulp_mapgen.py utility.
8. Add the generated binary to the list of binary files to be embedded into the application.

4.31.4 Accessing the ULP Program Variables

Global symbols defined in the ULP program may be used inside the main program.
For example, the ULP program may define a variable measurement_count which will define the number of ADC measurements the program needs to make before waking up the chip from deep sleep:

measurement_count:

.global measurement_count .long 0

/* later, use measurement_count */ move r3, measurement_count ld r3, r3, 0

The main program needs to initialize this variable before the ULP program is started. The build system makes this possible by generating the ${ULP_APP_NAME}.h and ${ULP_APP_NAME}.ld files which define the global symbols present in the ULP program. Each global symbol defined in the ULP program is included in these files and are prefixed with ulp_.
The header file contains the declaration of the symbol:
extern uint32_t ulp_measurement_count;

Note that all symbols (variables, arrays, functions) are declared as uint32_t. For functions and arrays, take the address of the symbol and cast it to the appropriate type. The generated linker script file defines the locations of symbols in RTC_SLOW_MEM:
PROVIDE ( ulp_measurement_count = 0x50000060 );

To access the ULP program variables from the main program, the generated header file should be included using an include statement. This will allow the ULP program variables to be accessed as regular variables:
#include "ulp_app_name.h"
// later void init_ulp_vars() {
ulp_measurement_count = 64; }

Note that the ULP program can only use lower 16 bits of each 32-bit word in RTC memory, because the registers are 16-bit, and there is no instruction to load from the high part of the word.
Likewise, the ULP store instruction writes register value into the lower 16 bits part of the 32-bit word. The upper 16 bits are written with a value which depends on the address of the store instruction, thus when reading variables written by the ULP, the main application needs to mask the upper 16 bits, e.g.:
printf("Last measurement value: %d\n", ulp_last_measurement & UINT16_MAX);

Espressif Systems

1897

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.31.5 Starting the ULP Program
To run a ULP program, the main application needs to load the ULP program into RTC memory using the ulp_load_binary function, and then start it using the ulp_run function.
Note thatoEnable Ultra Low Power (ULP) Coprocessorpoption must be enabled in menuconfig to reserve memory for the ULP. oRTC slow memory reserved for coprocessorpoption must be set to a value sufficient to store ULP code and data. If the application components contain multiple ULP programs, then the size of the RTC memory must be sufficient to hold the largest one.
Each ULP program is embedded into the ESP-IDF application as a binary blob. The application can reference this blob and load it in the following way (suppose ULP_APP_NAME was defined to ulp_app_name):
extern const uint8_t bin_start[] asm("_binary_ulp_app_name_bin_start"); extern const uint8_t bin_end[] asm("_binary_ulp_app_name_bin_end");
void start_ulp_program() { ESP_ERROR_CHECK( ulp_load_binary( 0 /* load address, set to 0 when using default linker scripts */, bin_start, (bin_end - bin_start) / sizeof(uint32_t)) );
}
esp_err_t ulp_load_binary(uint32_t load_addr, const uint8_t *program_binary, size_t program_size)
Load ULP program binary into RTC memory.
ULP program binary should have the following format (all values little-endian):
1. MAGIC, (value 0x00706c75, 4 bytes) 2. TEXT_OFFSET, offset of .text section from binary start (2 bytes) 3. TEXT_SIZE, size of .text section (2 bytes) 4. DATA_SIZE, size of .data section (2 bytes) 5. BSS_SIZE, size of .bss section (2 bytes) 6. (TEXT_OFFSET - 12) bytes of arbitrary data (will not be loaded into RTC memory) 7. .text section 8. .data section
Linker script in components/ulp/ld/esp32.ulp.ld produces ELF files which correspond to this format. This linker script produces binaries with load_addr == 0.
Return · ESP_OK on success · ESP_ERR_INVALID_ARG if load_addr is out of range · ESP_ERR_INVALID_SIZE if program_size doesnnt match (TEXT_OFFSET + TEXT_SIZE + DATA_SIZE) · ESP_ERR_NOT_SUPPORTED if the magic number is incorrect
Parameters · load_addr: address where the program should be loaded, expressed in 32-bit words · program_binary: pointer to program binary · program_size: size of the program binary
Once the program is loaded into RTC memory, the application can start it, passing the address of the entry point to the ulp_run function:
ESP_ERROR_CHECK( ulp_run(&ulp_entry - RTC_SLOW_MEM) );
esp_err_t ulp_run(uint32_t entry_point) Run the program loaded into RTC memory.
Return ESP_OK on success Parameters
· entry_point: entry point, expressed in 32-bit words

Espressif Systems

1898

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Declaration of the entry point symbol comes from the generated header file mentioned above, ${ULP_APP_NAME}.h. In the assembly source of the ULP application, this symbol must be marked as .global:
.global entry entry:
/* code starts here */

4.32 ULP-RISC-V Coprocessor programming

Warning: This feature is not supported in v4.4

The ULP-RISC-V coprocessor is a variant of the ULP, present in ESP32-S2. Similar to ULP, ULP RISC-V coprocessor can perform tasks such as sensor readings while the main CPU stays in low power modes. The main difference from the FSM ULP is this variant can be programmed in C using standard GNU tools. The ULP-RISC-V coprocessor can access the RTC_SLOW_MEM memory region, and registers in RTC_CNTL, RTC_IO, and SARADC peripherals. The RISC-V processor is a 32-bit, fixed point machine. Its instruction set is based on RV32IMC which includes hardware multiplication and division, and compressed code.

4.32.1 Installing the ULP-RISC-V Toolchain
The ULP-RISC-V coprocessor code is written in C (assembly is also possible) and compiled using RISC-V toolchain based on GCC. If you have already set up ESP-IDF with CMake build system according to the Getting Started Guide, then the toolchain should already be installed.

4.32.2 Compiling the ULP-RISC-V Code
To compile the ULP-RISC-V code as part of the component, the following steps must be taken:
1. The ULP-RISC-V code, written in C or assembly (must use the .S extension), must be placed into a separate directory inside the component directory, for instance ulp/.
2. Call ulp_embed_binary from the component CMakeLists.txt after registration. For example:
... idf_component_register()
set(ulp_app_name ulp_${COMPONENT_NAME}) set(ulp_sources "ulp/ulp_c_source_file.c" "ulp/ulp_assembly_source_file.S") set(ulp_exp_dep_srcs "ulp_c_source_file.c")
ulp_embed_binary(${ulp_app_name} "${ulp_sources}" "${ulp_exp_dep_srcs}")
The first argument to ulp_embed_binary specifies the ULP binary name. The name specified here will also be used by other generated artifacts such as the ELF file, map file, header file and linker export file. The second argument specifies the ULP source files. Finally, the third argument specifies the list of component source files which include the header file to be generated. This list is needed to build the dependencies correctly and ensure that the generated header file will be created before any of these files are compiled. See section below for the concept of generated header files for ULP applications.
3. Build the application as usual (e.g. idf.py app) Inside, the build system will take the following steps to build ULP program: 1. Run each source file through the C compiler and assembler. This step generates the object files (.obj.c or .obj.S depending of source file processed) in the component build directory.

Espressif Systems

1899

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

2. Run the linker script template through the C preprocessor. The template is located in components/ulp/ld directory.
4. Link the object files into an output ELF file (ulp_app_name.elf). The Map file (ulp_app_name.map) generated at this stage may be useful for debugging purposes.
5. Dump the contents of the ELF file into a binary (ulp_app_name.bin) which can then be embedded into the application.
6. Generate a list of global symbols (ulp_app_name.sym) in the ELF file using riscv32-espelf-nm.
7. Create an LD export script and header file (ulp_app_name.ld and ulp_app_name.h) containing the symbols from ulp_app_name.sym. This is done using the esp32ulp_mapgen.py utility.
8. Add the generated binary to the list of binary files to be embedded into the application.
4.32.3 Accessing the ULP-RISC-V Program Variables
Global symbols defined in the ULP-RISC-V program may be used inside the main program.
For example, the ULP-RISC-V program may define a variable measurement_count which will define the number of ADC measurements the program needs to make before waking up the chip from deep sleep
volatile int measurement_count;
int some_function() {
//read the measurement count for use it later. int temp = measurement_count;
...do something. }
The main program can access the global ULP-RISC-V program variables, the build system makes this possible by generating the ${ULP_APP_NAME}.h and ${ULP_APP_NAME}.ld files which define the global symbols present in the ULP program. Each global symbol defined in the ULP program is included in these files and are prefixed with ulp_.
The header file contains the declaration of the symbol
extern uint32_t ulp_measurement_count;
Note that all symbols (variables, arrays, functions) are declared as uint32_t. For functions and arrays, take the address of the symbol and cast it to the appropriate type.
The generated linker script file defines the locations of symbols in RTC_SLOW_MEM:
PROVIDE ( ulp_measurement_count = 0x50000060 );
To access the ULP-RISC-V program variables from the main program, the generated header file should be included using an include statement. This will allow the ULP program variables to be accessed as regular variables
#include "ulp_app_name.h"
void init_ulp_vars() { ulp_measurement_count = 64;
}

4.32.4 Starting the ULP-RISC-V Program
To run a ULP-RISC-V program, the main application needs to load the ULP program into RTC memory using the ulp_riscv_load_binary() function, and then start it using the ulp_riscv_run() function.

Espressif Systems

1900

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Note that CONFIG_ULP_COPROC_ENABLED and CONFIG_ULP_COPROC_TYPE_RISCV options must be enabled in menuconfig to reserve memory for the ULP. oRTC slow memory reserved for coprocessorpoption must be set to a value sufficient to store ULP code and data. If the application components contain multiple ULP programs, then the size of the RTC memory must be sufficient to hold the largest one.
Each ULP-RISC-V program is embedded into the ESP-IDF application as a binary blob. The application can reference this blob and load it in the following way (suppose ULP_APP_NAME was defined to ulp_app_name)
extern const uint8_t bin_start[] asm("_binary_ulp_app_name_bin_start"); extern const uint8_t bin_end[] asm("_binary_ulp_app_name_bin_end");
void start_ulp_program() { ESP_ERROR_CHECK( ulp_riscv_load_binary( bin_start, (bin_end - bin_start)) );
}
esp_err_t ulp_riscv_load_binary(const uint8_t *program_binary, size_t program_size_bytes) Load ULP-RISC-V program binary into RTC memory.
Different than ULP FSM, the binary program has no special format, it is the ELF file generated by RISC-V toolchain converted to binary format using objcopy.
Linker script in components/ulp/ld/ulp_riscv.ld produces ELF files which correspond to this format. This linker script produces binaries with load_addr == 0.
Return · ESP_OK on success · ESP_ERR_INVALID_SIZE if program_size_bytes is more than 8KiB
Parameters · program_binary: pointer to program binary · program_size_bytes: size of the program binary
Once the program is loaded into RTC memory, the application can start it, calling the ulp_riscv_run() function
ESP_ERROR_CHECK( ulp_riscv_run() );
esp_err_t ulp_riscv_run(void) Run the program loaded into RTC memory.
Return ESP_OK on success
4.32.5 ULP-RISC-V Program Flow
The ULP-RISC-V coprocessor is started by a timer. The timer is started once ulp_riscv_run() is called. The timer counts the number of RTC_SLOW_CLK ticks (by default, produced by an internal 150kHz RC oscillator). The number of ticks is set using RTC_CNTL_ULP_CP_TIMER_1_REG register. When starting the ULP, RTC_CNTL_ULP_CP_TIMER_1_REG will be used to set the number of timer ticks.
The application can set ULP timer period values (RTC_CNTL_ULP_CP_TIMER_1_REG) using the ulp_set_wakeup_period() function.
Once the timer counts the number of ticks set in the RTC_CNTL_ULP_CP_TIMER_1_REG register, the ULP coprocessor will power up and start running the program from the entry point set in the call to ulp_riscv_run().
The program runs until the field RTC_CNTL_COCPU_DONE in register RTC_CNTL_COCPU_CTRL_REG gets written or when a trap occurs due to illegal processor state. Once the program halts, the ULP coprocessor will power down, and the timer will be started again.
To disable the timer (effectively preventing the ULP program from running again), please clear the RTC_CNTL_ULP_CP_SLP_TIMER_EN bit in the RTC_CNTL_STATE0_REG register. This can be done both from the ULP code and from the main program.

Espressif Systems

1901

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.33 Unit Testing in ESP32-S3
ESP-IDF provides the following methods to test software. · Target based tests using a central unit test application which runs on the esp32s3. These tests use the Unity <https://www.throwtheswitch.org/unity> unit test framework. They can be integrated into an ESP-IDF component by placing them in the componentns test subdirectory. For the most part, this document is about target based tests. · Linux-host based unit tests in which all the hardware is abstracted via mocks. Linux-host based tests are still under development and only a small fraction of IDF components support them, currently. They are covered here: target based unit testing.
4.33.1 Normal Test Cases
Unit tests are located in the test subdirectory of a component. Tests are written in C, and a single C source file can contain multiple test cases. Test files start with the word otestp. Each test file should include the unity.h header and the header for the C module to be tested. Tests are added in a function in the C file as follows:
TEST_CASE("test name", "[module name]") {
// Add test here }
· The first argument is a descriptive name for the test. · The second argument is an identifier in square brackets. Identifiers are used to group related test, or tests with
specific properties.
Note: There is no need to add a main function with UNITY_BEGIN() and UNITY_END() in each test case. unity_platform.c will run UNITY_BEGIN() autonomously, and run the test cases, then call UNITY_END().
The test subdirectory should contain a component CMakeLists.txt, since they are themselves components (i.e., a test component). ESP-IDF uses the Unity test framework located in the unity component. Thus, each test component should specify the unity component as a component requirement using the REQUIRES argument. Normally, components should list their sources manually; for component tests however, this requirement is relaxed and the use of the SRC_DIRS argument in idf_component_register is advised. Overall, the minimal test subdirectory CMakeLists.txt file should contain the following:
idf_component_register(SRC_DIRS "." INCLUDE_DIRS "." REQUIRES unity)
See http://www.throwtheswitch.org/unity for more information about writing tests in Unity.
4.33.2 Multi-device Test Cases
The normal test cases will be executed on one DUT (Device Under Test). However, components that require some form of communication (e.g., GPIO, SPI) require another device to communicate with, thus cannot be tested normal test cases. Multi-device test cases involve writing multiple test functions, and running them on multiple DUTs. The following is an example of a multi-device test case:

Espressif Systems

1902

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

void gpio_master_test() {
gpio_config_t slave_config = { .pin_bit_mask = 1 << MASTER_GPIO_PIN, .mode = GPIO_MODE_INPUT,
}; gpio_config(&slave_config); unity_wait_for_signal("output high level"); TEST_ASSERT(gpio_get_level(MASTER_GPIO_PIN) == 1); }
void gpio_slave_test() {
gpio_config_t master_config = { .pin_bit_mask = 1 << SLAVE_GPIO_PIN, .mode = GPIO_MODE_OUTPUT,
}; gpio_config(&master_config); gpio_set_level(SLAVE_GPIO_PIN, 1); unity_send_signal("output high level"); }
TEST_CASE_MULTIPLE_DEVICES("gpio multiple devices test example", "[driver]", gpio_ master_test, gpio_slave_test);
The macro TEST_CASE_MULTIPLE_DEVICES is used to declare a multi-device test case.
· The first argument is test case name. · The second argument is test case description. · From the third argument, up to 5 test functions can be defined, each function will be the entry point of tests
running on each DUT.
Running test cases from different DUTs could require synchronizing between DUTs. We provide unity_wait_for_signal and unity_send_signal to support synchronizing with UART. As the scenario in the above example, the slave should get GPIO level after master set level. DUT UART console will prompt and user interaction is required:
DUT1 (master) console:
Waiting for signal: [output high level]! Please press "Enter" key to once any board send this signal.
DUT2 (slave) console:
Send signal: [output high level]!
Once the signal is sent from DUT2, you need to press oEnterpon DUT1, then DUT1 unblocks from unity_wait_for_signal and starts to change GPIO level.

4.33.3 Multi-stage Test Cases

The normal test cases are expected to finish without reset (or only need to check if reset happens). Sometimes we expect to run some specific tests after certain kinds of reset. For example, we want to test if the reset reason is correct after a wake up from deep sleep. We need to create a deep-sleep reset first and then check the reset reason. To support this, we can define multi-stage test cases, to group a set of test functions:

static void trigger_deepsleep(void) {
esp_sleep_enable_timer_wakeup(2000); esp_deep_sleep_start(); }

(continues on next page)

Espressif Systems

1903

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

(continued from previous page)
void check_deepsleep_reset_reason() {
soc_reset_reason_t reason = esp_rom_get_reset_reason(0); TEST_ASSERT(reason == RESET_REASON_CORE_DEEP_SLEEP); }
TEST_CASE_MULTIPLE_STAGES("reset reason check for deepsleep", "[esp32s3]", trigger_ deepsleep, check_deepsleep_reset_reason);
Multi-stage test cases present a group of test functions to users. It needs user interactions (select cases and select different stages) to run the case.

4.33.4 Tests For Different Targets
Some tests (especially those related to hardware) cannot run on all targets. Below is a guide how to make your unit tests run on only specified targets.
1. Wrap your test code by !(TEMPORARY_)DISABLED_FOR_TARGETS() macros and place them either in the original test file, or separate the code into files grouped by functions, but make sure all these files will be processed by the compiler. E.g.:
#if !TEMPORARY_DISABLED_FOR_TARGETS(ESP32, ESP8266) TEST_CASE("a test that is not ready for esp32 and esp8266 yet", "[]") { } #endif //!TEMPORARY_DISABLED_FOR_TARGETS(ESP32, ESP8266)
Once you need one of the tests to be compiled on a specified target, just modify the targets in the disabled list. Itns more encouraged to use some general conception that can be described in soc_caps.h to control the disabling of tests. If this is done but some of the tests are not ready yet, use both of them (and remove ! (TEMPORARY_)DISABLED_FOR_TARGETS() later). E.g.:
#if SOC_SDIO_SLAVE_SUPPORTED #if !TEMPORARY_DISABLED_FOR_TARGETS(ESP64) TEST_CASE("a sdio slave tests that is not ready for esp64 yet", "[sdio_slave]") {
//available for esp32 now, and will be available for esp64 in the future } #endif //!TEMPORARY_DISABLED_FOR_TARGETS(ESP64) #endif //SOC_SDIO_SLAVE_SUPPORTED
2. For test code that you are 100% for sure that will not be supported (e.g. no peripheral at all), use DISABLED_FOR_TARGETS; for test code that should be disabled temporarily, or due to lack of runners, etc., use TEMPORARY_DISABLED_FOR_TARGETS.
Some old ways of disabling unit tests for targets, that have obvious disadvantages, are deprecated:
· DONnT put the test code under test/target folder and use CMakeLists.txt to choose one of the target folder. This is prevented because test code is more likely to be reused than the implementations. If you put something into test/esp32 just to avoid building it on esp32s2, itns hard to make the code tidy if you want to enable the test again on esp32s3.
· DONnT use CONFIG_IDF_TARGET_xxx macros to disable the test items any more. This makes it harder to track disabled tests and enable them again. Also, a black-list style #if !disabled is preferred to whitelist style #if CONFIG_IDF_TARGET_xxx, since you will not silently disable cases when new targets are added in the future. But for test implementations, itns allowed to use #if CONFIG_IDF_TARGET_xxx to pick one of the implementation code. ­ Test item: some items that will be performed on some targets, but skipped on other targets. E.g. There are three test items SD 1-bit, SD 4-bit and SDSPI. For ESP32-S2, which doesnnt have SD host, among the tests only SDSPI is enabled on ESP32-S2.

Espressif Systems

1904

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

­ Test implementation: some code will always happen, but in different ways. E.g. There is no SDIO PKT_LEN register on ESP8266. If you want to get the length from the slave as a step in the test process, you can have different implementation code protected by #if CONFIG_IDF_TARGET_ reading in different ways. But please avoid using #else macro. When new target is added, the test case will fail at building stage, so that the maintainer will be aware of this, and choose one of the implementations explicitly.

4.33.5 Building Unit Test App
Follow the setup instructions in the top-level esp-idf README. Make sure that IDF_PATH environment variable is set to point to the path of esp-idf top-level directory.
Change into tools/unit-test-app directory to configure and build it:
· idf.py menuconfig - configure unit test app. · idf.py -T all build - build unit test app with tests for each component having tests in the test
subdirectory. · idf.py -T "xxx yyy" build - build unit test app with tests for some space-separated specific com-
ponents (For instance: idf.py -T heap build - build unit tests only for heap component directory). · idf.py -T all -E "xxx yyy" build - build unit test app with all unit tests, except for unit tests of
some components (For instance: idf.py -T all -E "ulp mbedtls" build - build all unit tests excludes ulp and mbedtls components).
Note: Due to inherent limitations of Windows command prompt, following syntax has to be used in order to build unit-test-app with multiple components: idf.py -T xxx -T yyy build or with escaped quotes: idf.py -T \`"xxx yyy\`" build in PowerShell or idf.py -T \^"ssd1306 hts221\^" build in Windows command prompt.
When the build finishes, it will print instructions for flashing the chip. You can simply run idf.py flash to flash all build output.
You can also run idf.py -T all flash or idf.py -T xxx flash to build and flash. Everything needed will be rebuilt automatically before flashing.
Use menuconfig to set the serial port for flashing.

4.33.6 Running Unit Tests

After flashing reset the ESP32-S3 and it will boot the unit test app. When unit test app is idle, press oEnterpwill make it print test menu with all available tests:

Here's the test menu, pick your combo:

(1)

"esp_ota_begin() verifies arguments" [ota]

(2)

"esp_ota_get_next_update_partition logic" [ota]

(3)

"Verify bootloader image in flash" [bootloader_support]

(4)

"Verify unit test app image" [bootloader_support]

(5)

"can use new and delete" [cxx]

(6)

"can call virtual functions" [cxx]

(7)

"can use static initializers for non-POD types" [cxx]

(8)

"can use std::vector" [cxx]

(9)

"static initialization guards work as expected" [cxx]

(10) "global initializers run in the correct order" [cxx]

(11) "before scheduler has started, static initializers work correctly" [cxx]

(12) "adc2 work with wifi" [adc]

(13) "gpio master/slave test example" [ignore][misc][test_env=UT_T2_1][multi_

device]

(1)

"gpio_master_test"

(continues on next page)

Espressif Systems

1905

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

(continued from previous page)

(2)

"gpio_slave_test"

(14) "SPI Master clockdiv calculation routines" [spi]

(15) "SPI Master test" [spi][ignore]

(16) "SPI Master test, interaction of multiple devs" [spi][ignore]

(17) "SPI Master no response when switch from host1 (SPI2) to host2 (SPI3)"

[spi]

(18) "SPI Master DMA test, TX and RX in different regions" [spi]

(19) "SPI Master DMA test: length, start, not aligned" [spi]

(20) "reset reason check for deepsleep" [esp32s3][test_env=UT_T2_1][multi_stage]

(1)

"trigger_deepsleep"

(2)

"check_deepsleep_reset_reason"

The normal case will print the case name and description. Master-slave cases will also print the sub-menu (the registered test function names).
Test cases can be run by inputting one of the following:
· Test case name in quotation marks to run a single test case · Test case index to run a single test case · Module name in square brackets to run all test cases for a specific module · An asterisk to run all test cases
[multi_device] and [multi_stage] tags tell the test runner whether a test case is a multiple devices or multiple stages of test case. These tags are automatically added by `TEST_CASE_MULTIPLE_STAGES and TEST_CASE_MULTIPLE_DEVICES macros.
After you select a multi-device test case, it will print sub-menu:

Running gpio master/slave test example...

gpio master/slave test example

(1)

"gpio_master_test"

(2)

"gpio_slave_test"

You need to input a number to select the test running on the DUT. Similar to multi-device test cases, multi-stage test cases will also print sub-menu:

Running reset reason check for deepsleep...

reset reason check for deepsleep

(1)

"trigger_deepsleep"

(2)

"check_deepsleep_reset_reason"

First time you execute this case, input 1 to run first stage (trigger deepsleep). After DUT is rebooted and able to run test cases, select this case again and input 2 to run the second stage. The case only passes if the last stage passes and all previous stages trigger reset.

4.33.7 Timing Code with Cache Compensated Timer
Instructions and data stored in external memory (e.g. SPI Flash and SPI RAM) are accessed through the CPUns unified instruction and data cache. When code or data is in cache, access is very fast (i.e., a cache hit).
However, if the instruction or data is not in cache, it needs to be fetched from external memory (i.e., a cache miss). Access to external memory is significantly slower, as the CPU must execute stall cycles whilst waiting for the instruction or data to be retrieved from external memory. This can cause the overall code execution speed to vary depending on the number of cache hits or misses.
Code and data placements can vary between builds, and some arrangements may be more favorable with regards to cache access (i.e., minimizing cache misses). This can technically affect execution speed, however these factors are usually irrelevant as their effect maverage outnover the devicens operation.
The effect of the cache on execution speed, however, can be relevant in benchmarking scenarios (especially micro benchmarks). There might be some variability in measured time between runs and between different builds. A tech-

Espressif Systems

1906

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
nique for eliminating for some of the variability is to place code and data in instruction or data RAM (IRAM/DRAM), respectively. The CPU can access IRAM and DRAM directly, eliminating the cache out of the equation. However, this might not always be viable as the size of IRAM and DRAM is limited.
The cache compensated timer is an alternative to placing the code/data to be benchmarked in IRAM/DRAM. This timer uses the processorns internal event counters in order to determine the amount of time spent on waiting for code/data in case of a cache miss, then subtract that from the recorded wall time.
// Start the timer ccomp_timer_start();
// Function to time func_code_to_time();
// Stop the timer, and return the elapsed time in microseconds relative to // ccomp_timer_start int64_t t = ccomp_timer_stop();
One limitation of the cache compensated timer is that the task that benchmarked functions should be pinned to a core. This is due to each core having its own event counters that are independent of each other. For example, if ccomp_timer_start gets called on one core, put to sleep by the scheduler, wakes up, and gets rescheduled on the other core, then the corresponding ccomp_timer_stop will be invalid.
4.33.8 Mocks
Note: Currently, mocking is only possible with some selected components when running on the Linux host. In the future, we plan to make essential components in IDF mockable. This will also include mocking when running on the ESP32-S3.
One of the biggest problems regarding unit testing of embedded systems are the strong hardware dependencies. Running unit tests directly on the ESP32-S3 can be especially difficult for higher layer components for the following reasons:
· Decreased test reliability due to lower layer components and/or hardware setup. · Increased difficulty in testing edge cases due to limitations of lower layer components and/or hardware setup · Increased difficulty in identifying the root cause due to the large number of dependencies influencing the be-
havior
When testing a particular component, (i.e., the component under test), software mocking allows the dependencies of the component under test to be substituted (i.e., mocked) entirely in software. To allow software mocking, ESPIDF integrates the CMock mocking framework as a component. With the addition of some CMake functions in the ESP-IDFns build system, it is possible to conveniently mock the entirety (or a part of) an IDF component.
Ideally, all components that the component under test is dependent on should be mocked, thus allowing the test environment complete control over all interactions with the component under test. However, if mocking all dependent components becomes too complex or too tedious (e.g. because you need to mock too many function calls) you have the following options:
· Include moreorealpIDF code in the tests. This may work but increases the dependency on theorealpcoden s behavior. Furthermore, once a test fails, you may not know if the failure is in your actual code under tests or the orealpIDF code.
· Re-evaluate the design of the code under test and attempt to reduce its dependencies by dividing the code under test into more manageable components. This may seem burdensome but it is common knowledge that unit tests often expose software design weaknesses. Fixing design weaknesses will not only help with unit testing in the short term, but will help future code maintenance as well.
Refer to cmock/CMock/docs/CMock_Summary.md for more details on how CMock works and how to create and use mocks.

Espressif Systems

1907

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Requirements
The following requirements are necessary to generate the mocks:
· Installed ESP-IDF with all its requirements · ruby · On the Linux target, which is the only target where mocking currently works, libbsd is required, too
Mock a Component
To create a mock version of a component, called a component mock, the component needs to be overwritten in a particular way. Overriding a component entails creating a component with the exact same name as the original component, then let the build system discover it later than the original component (see Multiple components with the same name <cmake-components-same-name> for more details).
In the component mock, the following parts are specified:
· The headers providing the functions to generate mocks for · Include paths of the aforementioned headers · Dependencies of the mock component (this is necessary e.g. if the headers include files from other components)
All these parts have to be specified using the IDF build system function idf_component_mock. You can use the IDF build system function idf_component_get_property with the tag COMPONENT_OVERRIDEN_DIR to access the component directory of the original component and then register the mock component parts using idf_component_mock:
idf_component_get_property(original_component_dir <original-component-name> COMPONENT_OVERRIDEN_DIR) ... idf_component_mock(INCLUDE_DIRS "${original_component_dir}/include"
REQUIRES freertos MOCK_HEADER_FILES ${original_component_dir}/include/header_containing_ functions_to_mock.h)
The component mock also requires a separate mock directory containing a mock_config.yaml file that configures CMock. A simple mock_config.yaml could look like this:
:cmock: :plugins: - expect - expect_any_args
For more details about the CMock configuration yaml file, have a look at cmock/CMock/docs/CMock_Summary.md.
Note that the component mock does not have to mock the original component in its entirety. As long as the test projectns dependencies and dependencies of other code to the original components are satisfied by the component mock, partial mocking is adequate. In fact, most of the component mocks in IDF in tools/mocks are only partially mocking the original component.
Examples of component mocks can be found under tools/mocks in the IDF directory. General information on how to override an IDF component can be found under the section oMultiple components with the same namepin the IDF build system documentation`.
Adjustments in Unit Test
The unit test needs to inform the cmake build system to mock dependent components (i.e., it needs to override the original component with the mock component). This is done by either placing the component mock into the projectn s components directory or adding the mock componentns directory using the following line in the projectns root CMakeLists.txt:

Espressif Systems

1908

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

list(APPEND EXTRA_COMPONENT_DIRS "<mock_component_dir>")
Both methods will override existing components in ESP-IDF with the component mock. The latter is particularly convenient if you use component mocks that are already supplied by IDF. Users should refer to the esp_event host-based unit test and its esp_event/host_test/esp_event_unit_test/CMakeLists.txt as an example of a component mock.
4.34 Unit Testing on Linux

Note: Host testing with IDF is experimental for now. We try our best to keep interfaces stable but cannt guarantee it for now. Feedback via github or the forum on esp32.com is highly welcome, though and may influence the future design of the host-based tests.
This article provides an overview of unit tests with IDF on Linux. For using unit tests on the target, please refer to target based unit testing.

4.34.1 Embedded Software Tests
Embedded software tests are challenging due to the following factors:
· Difficulties running tests efficiently. · Lack of many operating system abstractions when interfacing with hardware, making it difficult to isolate code
under test.
To solve these two problems, Linux host-based tests with CMock are introduced. Linux host-based tests are more efficient than unit tests on the target since they:
· Compile the necessary code only · Donnt need time to upload to a target · Run much faster on a host-computer, compared to an ESP
Using the CMock framework also solves the problem of hardware dependencies. Through mocking, hardware details are emulated and specified at run time, but only if necessary.
Of course, using code on the host and using mocks does not fully represent the target device. Thus, two kinds of tests are recommended:
1. Unit tests which test program logic on a Linux machine, isolated through mocks. 2. System/Integration tests which test the interaction of components and the whole system. They run on the target,
where irrelevant components and code may as well be emulated via mocks.
This documentation is about the first kind of tests. Refer to target based unit testing for more information on target tests (the second kind of tests).

4.34.2 IDF Unit Tests on Linux Host
The current focus of the Linux host tests is on creating isolated unit tests of components, while mocking the componentns dependencies with CMock. A complete implementation of IDF to run on Linux does not exist currently. There are currently two examples for running IDF-built code on Linux host:
· An example hello-world application · A unit test for NVS . Inside the component which should be tested, there is a separate directory host_test, besides the otraditionalp test directory or the test_apps directory. It has one or more subdirectories:

Espressif Systems

1909

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

- host_test/
- fixtures/ contains test fixtures (structs/functions to do test case set-up
and tear-down). If there are no fixtures, this can be ommitted.
- <test_name>/ IDF applications which run the tests
- <test_name2>/ Further tests are possible.
The IDF applications inside host_test set the mocking configuration as described in the IDF unit test documentation. The NVS page unit test provides some illustration of how to control the mocks.
Requirements
· Installed IDF including all IDF requirements · CMock requirements (Ruby) · libbsd The host tests have been tested on Ubuntu 20.04 with GCC version 9 and 10.
4.35 USB OTG Console
On chips with an integrated USB peripheral, it is possible to use USB Communication Device Class (CDC) to implement the serial console, instead of using UART with an external USB-UART bridge chip. ESP32-S3 ROM code contains a USB CDC implementation, which supports for some basic functionality without requiring the application to include the USB stack:
· Bidirectional serial console, which can be used with IDF Monitor or another serial monitor · Flashing using esptool.py and idf.py flash. · Device Firmware Update (DFU) interface for flashing the device using dfu-util and idf.py dfu.
Note: At the moment, this oUSB Consolepfeature is incompatible with TinyUSB stack. However, if TinyUSB is used, it can provide its own CDC implementation.

4.35.1 Hardware Requirements
Connect ESP32-S3 to the USB port as follows

GPIO 20 19 GND

USB D+ (green) D- (white) GND (black) +5V (red)

Some development boards may offer a USB connector for the internal USB peripheral iin that case, no extra connections are required.
By default, USB_SERIAL_JTAG module is connected to the internal PHY of the ESP32-S3, while USB_OTG peripheral can be used only if the external USB PHY is connected. Since CDC console is provided via USB_OTG peripheral, it cannot be used through the internal PHY in this configuration.

Espressif Systems

1910

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
You can permanently switch the internal USB PHY to work with USB_OTG peripheral instead of USB_SERIAL_JTAG by burning USB_PHY_SEL eFuse. See ESP32-S3 Technical Reference Manual for more details about USB_SERIAL_JTAG and USB_OTG. Note however that USB_SERIAL_JTAG also provides a CDC console, so enabling the CDC console shouldnnt be the primary reason for switching from USB_SERIAL_JTAG to USB_CDC.
4.35.2 Software Configuration
USB console feature can be enabled using CONFIG_ESP_CONSOLE_USB_CDC option in menuconfig tool (see CONFIG_ESP_CONSOLE_UART ). Once the option is enabled, build the project as usual.
4.35.3 Uploading the Application
Initial Upload
If the ESP32-S3 is not yet flashed with a program which enables USB console, we can not use idf.py flash command with the USB CDC port. There are 3 alternative options to perform the initial upload listed below. Once the initial upload is done, the application will start up and a USB CDC port will appear in the system.
Note: The port name may change after the initial upload, so check the port list again before running idf.py monitor.
Initial upload using the ROM download mode, over USB CDC · Press ESP32-S3 into download mode. To do this, keep GPIO0 low while toggling reset. On many development boards, theoBootpbutton is connected to GPIO0, and you can pressoResetpbutton while holdingoBootp . · A serial port will appear in the system. On most operating systems (Windows 8 and later, Linux, macOS) driver installation is not required. Find the port name using Device Manager (Windows) or by listing /dev/ ttyACM* devices on Linux or /dev/cu* devices on macOS. · Run idf.py flash -p PORT to upload the application, with PORT determined in the previous step
Initial upload using the ROM download mode, over USB DFU · Press ESP32-S3 into download mode. To do this, keep GPIO0 low while toggling reset. On many development boards, theoBootpbutton is connected to GPIO0, and you can pressoResetpbutton while holdingoBootp . · Run idf.py dfu-flash.
See Flashing the Chip with the DFU Image for details about DFU flashing.
Initial upload using UART On development boards with a USB-UART bridge, upload the application over UART: idf.py flash -p PORT where PORT is the name of the serial port provided by the USB-UART bridge.
Subsequent Usage
Once the application is uploaded for the first time, you can run idf.py flash and idf.py monitor as usual.

Espressif Systems

1911

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.35.4 Limitations
There are several limitations to the USB console feature. These may or may not be significant, depending on the type of application being developed, and the development workflow. Most of these limitations stem from the fact that USB CDC is implemented in software, so the console working over USB CDC is more fragile and complex than a console working over UART.
1. If the application crashes, panic handler output may not be sent over USB CDC in some cases. If the memory used by the CDC driver is corrupted, or there is some other system-level issue, CDC may not work for sending panic handler messages over USB. This does work in many situations, but is not guaranteed to work as reliably as the UART output does. Similarly, if the application enters a boot loop before the USB CDC driver has a chance to start up, there will be no console output.
2. If the application accidentally reconfigures the USB peripheral pins, or disables the USB peripheral, USB CDC device will disappear from the system. After fixing the issue in the application, you will need to follow the Initial Upload process to flash the application again.
3. If the application enters light sleep (including automatic light sleep) or deep sleep mode, USB CDC device will disappear from the system.
4. USB CDC driver reserves some amount of RAM and increases application code size. Keep this in mind if trying to optimize application memory usage.
5. By default, the low-level esp_rom_printf feature and ESP_EARLY_LOG are disabled when USB CDC is used. These can be enabled using CONFIG_ESP_CONSOLE_USB_CDC_SUPPORT_ETS_PRINTF option. With this option enabled, esp_rom_printf can be used, at the expense of increased IRAM usage. Keep in mind that the cost of esp_rom_printf and ESP_EARLY_LOG over USB CDC is significantly higher than over UART. This makes these logging mechanisms much less suitable foroprintf debuggingp, especially in the interrupt handlers.
6. If you are developing an application which uses the USB peripheral with the TinyUSB stack, this USB Console feature can not be used. This is mainly due to the following reasons: · This feature relies on a different USB CDC software stack in ESP32-S3 ROM. · USB descriptors used by the ROM CDC stack may be different from the descriptors used by TinyUSB. · When developing applications which use USB peripheral, it is very likely that USB functionality will not work or will not fully work at some moments during development. This can be due to misconfigured USB descriptors, errors in the USB stack usage, or other reasons. In this case, using the UART console for flashing and monitoring provides a much better development experience.
7. When debugging the application using JTAG, USB CDC may stop working if the CPU is stopped on a breakpoint. USB CDC operation relies on interrupts from the USB peripheral being serviced periodically. If the host computer doesnnt receive valid responses from the USB device side for some time, it may decide to disconnect the device. The actual time depends on the OS and the driver, and ranges from a few hundred milliseconds to a few seconds.
4.36 USB Serial/JTAG Controller Console
On chips with an integrated USB Serial/JTAG Controller, it is possible to use the part of this controller that implements a serial port (CDC) to implement the serial console, instead of using UART with an external USB-UART bridge chip. ESP32-S3 contains this controller, providing the following functions:
· Bidirectional serial console, which can be used with IDF Monitor or another serial monitor. · Flashing using esptool.py and idf.py flash. · JTAG debugging using e.g. OpenOCD, simultaneous with serial operations.
Note that, in contrast with the USB OTG peripheral in some Espressif chips, the USB Serial/JTAG Controller is a fixed function device, implemented entirely in hardware. This means it cannot be reconfigured to perform any function other than to provide a serial channel and JTAG debugging functionality.
4.36.1 Hardware Requirements
Connect ESP32-S3 to the USB port as follows:

Espressif Systems

1912

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

GPIO 20 19 GND

USB D+ (green) D- (white) GND (black) +5V (red)

Some development boards may offer a USB connector for the USB Serial/JTAG Controller iin that case, no extra connections are required.

4.36.2 Software Configuration
USB console feature can be enabled using CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG option in menuconfig tool (see CONFIG_ESP_CONSOLE_UART).
Once the option is enabled, build the project as usual.
Alternatively, you can access the output through usb_serial_jtag port but make sure the option CONFIG_ESP_CONSOLE_SECONDARY_USB_SERIAL_JTAG in choice ESP_CONSOLE_SECONDARY is selected.

Warning: Besides output, if you also want to input or use REPL with console, please select CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG.

4.36.3 Uploading the Application
The USB Serial/JTAG Controller is able to put the ESP32-S3 into download mode automatically. Simply flash as usual, but specify the USB Serial/JTAG Controller port on your system: idf.py flash -p PORT where PORT is the name of the proper port.
4.36.4 Limitations
There are several limitations to the USB console feature. These may or may not be significant, depending on the type of application being developed, and the development workflow.
1. If the application accidentally reconfigures the USB peripheral pins, or disables the USB Serial/JTAG Controller, the device will disappear from the system. After fixing the issue in the application, you will need to manually put the ESP32-S3 into download mode by pulling low GPIO0 and resetting the chip.
2. If the application enters deep sleep mode, USB CDC device will disappear from the system. 3. The behavior between an actual USB-to-serial bridge chip and the USB Serial/JTAG Controller is slightly
different if the ESP-IDF application does not listen for incoming bytes. An USB-to-serial bridge chip will just send the bytes to a (not listening) chip, while the USB Serial/JTAG Controller will block until the application reads the bytes. This can lead to a non-responsive looking terminal program. 4. If the application enters light-sleep (including automatic light-sleep) or software reset, etc. The USB CDC device will still work on the system. But be aware that this might increase the power consumption, if you donnt need USB CDC in sleep and want to keep low power consumption, please disable the menuconfig CONFIG_RTC_CLOCK_BBPLL_POWER_ON_WITH_USB. Moreover, the power consumption will only increase when your USB CDC port is really in use (like data transaction), therefore, if your USB CDC just connects with power bank or battery, rather than something like computer, you donnt need to care about the increasing power consumption mentioned above.
4.37 Wi-Fi Driver

Espressif Systems

1913

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.37.1 ESP32-S3 Wi-Fi Feature List
· Support station-only mode, AP-only mode, station/AP-coexistence mode · Support IEEE 802.11b, IEEE 802.11g, IEEE 802.11n and APIs to configure the protocol mode · Support WPA/WPA2/WPA3/WPA2-Enterprise and WPS · Support AMPDU, HT40, QoS and other key features · Support Modem-sleep · Support the Espressif-specific ESP-NOW protocol and Long Range mode, which supports up to 1 km of data
traffic · Up to 20 MBit/s TCP throughput and 30 MBit/s UDP throughput over the air · Support Sniffer · Support both fast scan and all-channel scan · Support multiple antennas · Support channel state information
4.37.2 How To Write a Wi-Fi Application
Preparation
Generally, the most effective way to begin your own Wi-Fi application is to select an example which is similar to your own application, and port the useful part into your project. It is not a MUST but it is strongly recommended that you take some time to read this article first, especially if you want to program a robust Wi-Fi application. This article is supplementary to the Wi-Fi APIs/Examples. It describes the principles of using the Wi-Fi APIs, the limitations of the current Wi-Fi API implementation, and the most common pitfalls in using Wi-Fi. This article also reveals some design details of the Wi-Fi driver. We recommend you to select an example .
Setting Wi-Fi Compile-time Options
Refer to Wi-Fi Menuconfig.
Init Wi-Fi
Refer to ESP32-S3 Wi-Fi station General Scenario, ESP32-S3 Wi-Fi AP General Scenario.
Start/Connect Wi-Fi
Refer to ESP32-S3 Wi-Fi station General Scenario, ESP32-S3 Wi-Fi AP General Scenario.
Event-Handling
Generally, it is easy to write code in osunny-daypscenarios, such as WIFI_EVENT_STA_START, WIFI_EVENT_STA_CONNECTED etc. The hard part is to write routines in orainy-daypscenarios, such as WIFI_EVENT_STA_DISCONNECTED etc. Good handling oforainy-daypscenarios is fundamental to robust Wi-Fi applications. Refer to ESP32-S3 Wi-Fi Event Description, ESP32-S3 Wi-Fi station General Scenario, ESP32-S3 Wi-Fi AP General Scenario. See also an overview of event handling in ESP-IDF.
Write Error-Recovery Routines Correctly at All Times
Just like the handling of orainy-daypscenarios, a good error-recovery routine is also fundamental to robust Wi-Fi applications. Refer to ESP32-S3 Wi-Fi API Error Code.

Espressif Systems

1914

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

4.37.3 ESP32-S3 Wi-Fi API Error Code
All of the ESP32-S3 Wi-Fi APIs have well-defined return values, namely, the error code. The error code can be categorized into:
· No errors, e.g. ESP_OK means that the API returns successfully. · Recoverable errors, such as ESP_ERR_NO_MEM, etc. · Non-recoverable, non-critical errors. · Non-recoverable, critical errors.
Whether the error is critical or not depends on the API and the application scenario, and it is defined by the API user.
The primary principle to write a robust application with Wi-Fi API is to always check the error code and write the error-handling code. Generally, the error-handling code can be used:
· for recoverable errors, in which case you can write a recoverable-error code. For example, when esp_wifi_start() returns ESP_ERR_NO_MEM, the recoverable-error code vTaskDelay can be called, in order to get a microsecondsndelay for another try.
· for non-recoverable, yet non-critical, errors, in which case printing the error code is a good method for error handling.
· for non-recoverable, critical errors, in which case oassertpmay be a good method for error handling. For example, if esp_wifi_set_mode() returns ESP_ERR_WIFI_NOT_INIT, it means that the Wi-Fi driver is not initialized by esp_wifi_init() successfully. You can detect this kind of error very quickly in the application development phase.
In esp_err.h, ESP_ERROR_CHECK checks the return values. It is a rather commonplace error-handling code and can be used as the default error-handling code in the application development phase. However, we strongly recommend that API users write their own error-handling code.

4.37.4 ESP32-S3 Wi-Fi API Parameter Initialization
When initializing struct parameters for the API, one of two approaches should be followed:
· explicitly set all fields of the parameter · use get API to get current configuration first, then set application specific fields
Initializing or getting the entire structure is very important because most of the time the value 0 indicates the default value is used. More fields may be added to the struct in the future and initializing these to zero ensures the application will still work correctly after IDF is updated to a new release.

4.37.5 ESP32-S3 Wi-Fi Programming Model
The ESP32-S3 Wi-Fi programming model is depicted as follows:
The Wi-Fi driver can be considered a black box that knows nothing about high-layer code, such as the TCP/IP stack, application task, event task, etc. The application task (code) generally calls Wi-Fi driver APIs to initialize Wi-Fi and handles Wi-Fi events when necessary. Wi-Fi driver receives API calls, handles them, and post events to the application.
Wi-Fi event handling is based on the esp_event library. Events are sent by the Wi-Fi driver to the default event loop. Application may handle these events in callbacks registered using esp_event_handler_register(). Wi-Fi events are also handled by esp_netif component to provide a set of default behaviors. For example, when Wi-Fi station connects to an AP, esp_netif will automatically start the DHCP client (by default).

4.37.6 ESP32-S3 Wi-Fi Event Description
WIFI_EVENT_WIFI_READY
The Wi-Fi driver will never generate this event, which, as a result, can be ignored by the application event callback. This event may be removed in future releases.

Espressif Systems

1915

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 54: Wi-Fi Programming Model

WIFI_EVENT_SCAN_DONE
The scan-done event is triggered by esp_wifi_scan_start() and will arise in the following scenarios:
· The scan is completed, e.g., the target AP is found successfully, or all channels have been scanned. · The scan is stopped by esp_wifi_scan_stop(). · The esp_wifi_scan_start() is called before the scan is completed. A new scan will override the
current scan and a scan-done event will be generated.
The scan-done event will not arise in the following scenarios:
· It is a blocked scan. · The scan is caused by esp_wifi_connect().
Upon receiving this event, the event task does nothing. The application event callback needs to call esp_wifi_scan_get_ap_num() and esp_wifi_scan_get_ap_records() to fetch the scanned AP list and trigger the Wi-Fi driver to free the internal memory which is allocated during the scan (do not forget to do this!). Refer to ESP32-S3 Wi-Fi Scan for a more detailed description.

WIFI_EVENT_STA_START
If esp_wifi_start() returns ESP_OK and the current Wi-Fi mode is station or station/AP, then this event will arise. Upon receiving this event, the event task will initialize the LwIP network interface (netif). Generally, the application event callback needs to call esp_wifi_connect() to connect to the configured AP.

WIFI_EVENT_STA_STOP
If esp_wifi_stop() returns ESP_OK and the current Wi-Fi mode is station or station/AP, then this event will arise. Upon receiving this event, the event task will release the stationns IP address, stop the DHCP client, remove TCP/UDP-related connections and clear the LwIP station netif, etc. The application event callback generally does not need to do anything.

WIFI_EVENT_STA_CONNECTED
If esp_wifi_connect() returns ESP_OK and the station successfully connects to the target AP, the connection event will arise. Upon receiving this event, the event task starts the DHCP client and begins the DHCP process of getting the IP address. Then, the Wi-Fi driver is ready for sending and receiving data. This moment is good for beginning the application work, provided that the application does not depend on LwIP, namely the IP address. However, if the application is LwIP-based, then you need to wait until the got ip event comes in.

Espressif Systems

1916

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

WIFI_EVENT_STA_DISCONNECTED
This event can be generated in the following scenarios:
· When esp_wifi_disconnect(), or esp_wifi_stop() is called and the station is already connected to the AP.
· When esp_wifi_connect() is called, but the Wi-Fi driver fails to set up a connection with the AP due to certain reasons, e.g. the scan fails to find the target AP, authentication times out, etc. If there are more than one AP with the same SSID, the disconnected event is raised after the station fails to connect all of the found APs.
· When the Wi-Fi connection is disrupted because of specific reasons, e.g., the station continuously loses N beacons, the AP kicks off the station, the APns authentication mode is changed, etc.
Upon receiving this event, the default behavior of the event task is:
· Shuts down the stationns LwIP netif. · Notifies the LwIP task to clear the UDP/TCP connections which cause the wrong status to all sockets. For
socket-based applications, the application callback can choose to close all sockets and re-create them, if necessary, upon receiving this event.
The most common event handle code for this event in application is to call esp_wifi_connect() to reconnect the Wi-Fi. However, if the event is raised because esp_wifi_disconnect() is called, the application should not call esp_wifi_connect() to reconnect. Itns applicationns responsibility to distinguish whether the event is caused by esp_wifi_disconnect() or other reasons. Sometimes a better reconnect strategy is required, refer to Wi-Fi Reconnect and Scan When Wi-Fi Is Connecting.
Another thing deserves our attention is that the default behavior of LwIP is to abort all TCP socket connections on receiving the disconnect. Most of time it is not a problem. However, for some special application, this may not be what they want, consider following scenarios:
· The application creates a TCP connection to maintain the application-level keep-alive data that is sent out every 60 seconds.
· Due to certain reasons, the Wi-Fi connection is cut off, and the WIFI_EVENT_STA_DISCONNECTED is raised. According to the current implementation, all TCP connections will be removed and the keep-alive socket will be in a wrong status. However, since the application designer believes that the network layer should NOT care about this error at the Wi-Fi layer, the application does not close the socket.
· Five seconds later, the Wi-Fi connection is restored because esp_wifi_connect() is called in the application event callback function. Moreover, the station connects to the same AP and gets the same IPV4 address as before.
· Sixty seconds later, when the application sends out data with the keep-alive socket, the socket returns an error and the application closes the socket and re-creates it when necessary.
In above scenarios, ideally, the application sockets and the network layer should not be affected, since the Wi-Fi connection only fails temporarily and recovers very quickly. The application can enable oKeep TCP connections when IP changedpvia LwIP menuconfig.

IP_EVENT_STA_GOT_IP
This event arises when the DHCP client successfully gets the IPV4 address from the DHCP server, or when the IPV4 address is changed. The event means that everything is ready and the application can begin its tasks (e.g., creating sockets).
The IPV4 may be changed because of the following reasons:
· The DHCP client fails to renew/rebind the IPV4 address, and the stationns IPV4 is reset to 0. · The DHCP client rebinds to a different address. · The static-configured IPV4 address is changed.
Whether the IPV4 address is changed or NOT is indicated by field ip_change of ip_event_got_ip_t.
The socket is based on the IPV4 address, which means that, if the IPV4 changes, all sockets relating to this IPV4 will become abnormal. Upon receiving this event, the application needs to close all sockets and recreate the application when the IPV4 changes to a valid one.

Espressif Systems

1917

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
IP_EVENT_GOT_IP6
This event arises when the IPV6 SLAAC support auto-configures an address for the ESP32-S3, or when this address changes. The event means that everything is ready and the application can begin its tasks (e.g., creating sockets).
IP_STA_LOST_IP
This event arises when the IPV4 address become invalid. IP_STA_LOST_IP doesnnt arise immediately after the Wi-Fi disconnects, instead it starts an IPV4 address lost timer, if the IPV4 address is got before ip lost timer expires, IP_EVENT_STA_LOST_IP doesnnt happen. Otherwise, the event arises when IPV4 address lost timer expires. Generally the application donnt need to care about this event, it is just a debug event to let the application know that the IPV4 address is lost.
WIFI_EVENT_AP_START
Similar to WIFI_EVENT_STA_START.
WIFI_EVENT_AP_STOP
Similar to WIFI_EVENT_STA_STOP.
WIFI_EVENT_AP_STACONNECTED
Every time a station is connected to ESP32-S3 AP, the WIFI_EVENT_AP_STACONNECTED will arise. Upon receiving this event, the event task will do nothing, and the application callback can also ignore it. However, you may want to do something, for example, to get the info of the connected STA, etc.
WIFI_EVENT_AP_STADISCONNECTED
This event can happen in the following scenarios: · The application calls esp_wifi_disconnect(), or esp_wifi_deauth_sta(), to manually disconnect the station. · The Wi-Fi driver kicks off the station, e.g. because the AP has not received any packets in the past five minutes, etc. The time can be modified by esp_wifi_set_inactive_time(). · The station kicks off the AP.
When this event happens, the event task will do nothing, but the application event callback needs to do something, e.g., close the socket which is related to this station, etc.
WIFI_EVENT_AP_PROBEREQRECVED
This event is disabled by default. The application can enable it via API esp_wifi_set_event_mask(). When this event is enabled, it will be raised each time the AP receives a probe request.
4.37.7 ESP32-S3 Wi-Fi Station General Scenario
Below is a obig scenariopwhich describes some small scenarios in station mode:

Espressif Systems

1918

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Espressif Systems

Fig. 55: Sample Wi-Fi Event Scenarios in Station Mode

1919

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

1. Wi-Fi/LwIP Init Phase

· s1.1: The main task calls esp_netif_init() to create an LwIP core task and initialize LwIP-related

work.

· s1.2: The main task calls esp_event_loop_create() to create a system Event task and initialize an

application eventns callback function. In the scenario above, the application eventns callback function does

nothing but relaying the event to the application task.

· s1.3:

The main task calls esp_netif_create_default_wifi_ap() or

esp_netif_create_default_wifi_sta() to create default network interface instance bind-

ing station or AP with TCP/IP stack.

· s1.4: The main task calls esp_wifi_init() to create the Wi-Fi driver task and initialize the Wi-Fi driver.

· s1.5: The main task calls OS API to create the application task.

Step 1.1 ~ 1.5 is a recommended sequence that initializes a Wi-Fi-/LwIP-based application. However, it is NOT a must-follow sequence, which means that you can create the application task in step 1.1 and put all other initializations in the application task. Moreover, you may not want to create the application task in the initialization phase if the application task depends on the sockets. Rather, you can defer the task creation until the IP is obtained.

2. Wi-Fi Configuration Phase
Once the Wi-Fi driver is initialized, you can start configuring the Wi-Fi driver. In this scenario, the mode is station, so you may need to call esp_wifi_set_mode() (WIFI_MODE_STA) to configure the Wi-Fi mode as station. You can call other esp_wifi_set_xxx APIs to configure more settings, such as the protocol mode, country code, bandwidth, etc. Refer to ESP32-S3 Wi-Fi Configuration.
Generally, we configure the Wi-Fi driver before setting up the Wi-Fi connection, but this is NOT mandatory, which means that you can configure the Wi-Fi connection anytime, provided that the Wi-Fi driver is initialized successfully. However, if the configuration does not need to change after the Wi-Fi connection is set up, you should configure the Wi-Fi driver at this stage, because the configuration APIs (such as esp_wifi_set_protocol()) will cause the Wi-Fi to reconnect, which may not be desirable.
If the Wi-Fi NVS flash is enabled by menuconfig, all Wi-Fi configuration in this phase, or later phases, will be stored into flash. When the board powers on/reboots, you do not need to configure the Wi-Fi driver from scratch. You only need to call esp_wifi_get_xxx APIs to fetch the configuration stored in flash previously. You can also configure the Wi-Fi driver if the previous configuration is not what you want.

3. Wi-Fi Start Phase
· s3.1: Call esp_wifi_start() to start the Wi-Fi driver. · s3.2: The Wi-Fi driver posts WIFI_EVENT_STA_START to the event task; then, the event task will do some
common things and will call the application event callback function. · s3.3: The application event callback function relays the WIFI_EVENT_STA_START to the application task. We
recommend that you call esp_wifi_connect(). However, you can also call esp_wifi_connect() in other phrases after the WIFI_EVENT_STA_START arises.

4. Wi-Fi Connect Phase
· s4.1: Once esp_wifi_connect() is called, the Wi-Fi driver will start the internal scan/connection process.
· s4.2: If the internal scan/connection process is successful, the WIFI_EVENT_STA_CONNECTED will be generated. In the event task, it starts the DHCP client, which will finally trigger the DHCP process.
· s4.3: In the above-mentioned scenario, the application event callback will relay the event to the application task. Generally, the application needs to do nothing, and you can do whatever you want, e.g., print a log, etc.
In step 4.2, the Wi-Fi connection may fail because, for example, the password is wrong, the AP is not found, etc. In a case like this, WIFI_EVENT_STA_DISCONNECTED will arise and the reason for such a failure will be provided. For handling events that disrupt Wi-Fi connection, please refer to phase 6.

Espressif Systems

1920

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

5. Wi-Fi mGot IPnPhase
· s5.1: Once the DHCP client is initialized in step 4.2, the got IP phase will begin. · s5.2: If the IP address is successfully received from the DHCP server, then IP_EVENT_STA_GOT_IP will arise
and the event task will perform common handling. · s5.3: In the application event callback, IP_EVENT_STA_GOT_IP is relayed to the application task. For LwIP-
based applications, this event is very special and means that everything is ready for the application to begin its tasks, e.g. creating the TCP/UDP socket, etc. A very common mistake is to initialize the socket before IP_EVENT_STA_GOT_IP is received. DO NOT start the socket-related work before the IP is received.

6. Wi-Fi Disconnect Phase

· s6.1: When the Wi-Fi connection is disrupted, e.g. because the AP is powered off, the RSSI is poor, etc.,

WIFI_EVENT_STA_DISCONNECTED will arise. This event may also arise in phase 3. Here, the event task

will notify the LwIP task to clear/remove all UDP/TCP connections. Then, all application sockets will be in a

wrong status. In other words, no socket can work properly when this event happens.

· s6.2: In the scenario described above, the application event callback function re-

lays WIFI_EVENT_STA_DISCONNECTED to the application task.

We recommend that

esp_wifi_connect() be called to reconnect the Wi-Fi, close all sockets and re-create them if

necessary. Refer to WIFI_EVENT_STA_DISCONNECTED.

7. Wi-Fi IP Change Phase
· s7.1: If the IP address is changed, the IP_EVENT_STA_GOT_IP will arise with oip_changepset to true. · s7.2: This event is important to the application. When it occurs, the timing is good for closing all
created sockets and recreating them.

8. Wi-Fi Deinit Phase
· s8.1: Call esp_wifi_disconnect() to disconnect the Wi-Fi connectivity. · s8.2: Call esp_wifi_stop() to stop the Wi-Fi driver. · s8.3: Call esp_wifi_deinit() to unload the Wi-Fi driver.

4.37.8 ESP32-S3 Wi-Fi AP General Scenario
Below is a obig scenariopwhich describes some small scenarios in AP mode:

4.37.9 ESP32-S3 Wi-Fi Scan
Currently, the esp_wifi_scan_start() API is supported only in station or station/AP mode.

Espressif Systems

1921

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Espressif Systems

Fig. 56: Sample Wi-Fi Event Scenarios in AP Mode

1922

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Scan Type

Mode Active Scan Passive Scan Foreground Scan
Background Scan
All-Channel Scan Specific Channel Scan

Description Scan by sending a probe request. The default scan is an active scan. No probe request is sent out. Just switch to the specific channel and wait for a beacon. Application can enable it via the scan_type field of wifi_scan_config_t. This scan is applicable when there is no Wi-Fi connection in station mode. Foreground or background scanning is controlled by the Wi-Fi driver and cannot be configured by the application. This scan is applicable when there is a Wi-Fi connection in station mode or in station/AP mode. Whether it is a foreground scan or background scan depends on the Wi-Fi driver and cannot be configured by the application. It scans all of the channels. If the channel field of wifi_scan_config_t is set to 0, it is an all-channel scan. It scans specific channels only. If the channel field of wifi_scan_config_t set to 1-14, it is a specific-channel scan.

The scan modes in above table can be combined arbitrarily, so we totally have 8 different scans:
· All-Channel Background Active Scan · All-Channel Background Passive Scan · All-Channel Foreground Active Scan · All-Channel Foreground Passive Scan · Specific-Channel Background Active Scan · Specific-Channel Background Passive Scan · Specific-Channel Foreground Active Scan · Specific-Channel Foreground Passive Scan

Scan Configuration
The scan type and other per-scan attributes are configured by esp_wifi_scan_start(). The table below provides a detailed description of wifi_scan_config_t.

Field ssid bssid channel
show_hidden
scan_type
scan_time

Description If the SSID is not NULL, it is only the AP with the same SSID that can be scanned. If the BSSID is not NULL, it is only the AP with the same BSSID that can be scanned. Ifochannelpis 0, there will be an all-channel scan; otherwise, there will be a specificchannel scan. If oshow_hiddenpis 0, the scan ignores the AP with a hidden SSID; otherwise, the scan considers the hidden AP a normal one. If oscan_typepis WIFI_SCAN_TYPE_ACTIVE, the scan is oactivep; otherwise, it is a opassivepone. This field is used to control how long the scan dwells on each channel. For passive scans, scan_time.passive designates the dwell time for each channel. For active scans, dwell times for each channel are listed in the table below. Here, min is short for scan time.active.min and max is short for scan_time.active.max.
· min=0, max=0: scan dwells on each channel for 120 ms. · min>0, max=0: scan dwells on each channel for 120 ms. · min=0, max>0: scan dwells on each channel for max ms. · min>0, max>0: the minimum time the scan dwells on each channel is min ms.
If no AP is found during this time frame, the scan switches to the next channel. Otherwise, the scan dwells on the channel for max ms. If you want to improve the performance of the the scan, you can try to modify these two parameters.

There are also some global scan attributes which are configured by API esp_wifi_set_config(), refer to

Espressif Systems

1923

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Station Basic Configuration Scan All APs on All Channels (Foreground) Scenario:

Fig. 57: Foreground Scan of all Wi-Fi Channels
The scenario above describes an all-channel, foreground scan. The foreground scan can only occur in station mode where the station does not connect to any AP. Whether it is a foreground or background scan is totally determined by the Wi-Fi driver, and cannot be configured by the application. Detailed scenario description:
Scan Configuration Phase · s1.1: Call esp_wifi_set_country() to set the country info if the default country info is not what you want, refer to Wi-Fi Country Code.

Espressif Systems

1924

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· s1.2: Call esp_wifi_scan_start() to configure the scan. To do so, you can refer to Scan Configuration. Since this is an all-channel scan, just set the SSID/BSSID/channel to 0.
Wi-Fi Driverns Internal Scan Phase · s2.1: The Wi-Fi driver switches to channel 1, in case the scan type is WIFI_SCAN_TYPE_ACTIVE, and broadcasts a probe request. Otherwise, the Wi-Fi will wait for a beacon from the APs. The Wi-Fi driver will stay in channel 1 for some time. The dwell time is configured in min/max time, with default value being 120 ms. · s2.2: The Wi-Fi driver switches to channel 2 and performs the same operation as in step 2.1. · s2.3: The Wi-Fi driver scans the last channel N, where N is determined by the country code which is configured in step 1.1.
Scan-Done Event Handling Phase · s3.1: When all channels are scanned, WIFI_EVENT_SCAN_DONE will arise. · s3.2: The applicationns event callback function notifies the application task that WIFI_EVENT_SCAN_DONE is received. esp_wifi_scan_get_ap_num() is called to get the number of APs that have been found in this scan. Then, it allocates enough entries and calls esp_wifi_scan_get_ap_records() to get the AP records. Please note that the AP records in the Wi-Fi driver will be freed, once esp_wifi_scan_get_ap_records() is called. Do not call esp_wifi_scan_get_ap_records() twice for a single scan-done event. If esp_wifi_scan_get_ap_records() is not called when the scan-done event occurs, the AP records allocated by the Wi-Fi driver will not be freed. So, make sure you call esp_wifi_scan_get_ap_records(), yet only once.
Scan All APs on All Channels (Background)
Scenario: The scenario above is an all-channel background scan. Compared to Scan All APs on All Channels (Foreground) , the difference in the all-channel background scan is that the Wi-Fi driver will scan the back-to-home channel for 30 ms before it switches to the next channel to give the Wi-Fi connection a chance to transmit/receive data.
Scan for Specific AP on All Channels
Scenario: This scan is similar to Scan All APs on All Channels (Foreground). The differences are:
· s1.1: In step 1.2, the target AP will be configured to SSID/BSSID. · s2.1 ~ s2.N: Each time the Wi-Fi driver scans an AP, it will check whether it is a target AP or not. If the scan
is WIFI_FAST_SCAN scan and the target AP is found, then the scan-done event will arise and scanning will end; otherwise, the scan will continue. Please note that the first scanned channel may not be channel 1, because the Wi-Fi driver optimizes the scanning sequence. If there are multiple APs which match the target AP info, for example, if we happen to scan two APs whose SSID is oapp. If the scan is WIFI_FAST_SCAN, then only the first scanned oappwill be found, if the scan is WIFI_ALL_CHANNEL_SCAN, both oappwill be found and the station will connect the oappaccording to the configured strategy, refer to Station Basic Configuration. You can scan a specific AP, or all of them, in any given channel. These two scenarios are very similar.
Scan in Wi-Fi Connect
When esp_wifi_connect() is called, the Wi-Fi driver will try to scan the configured AP first. The scan in oWi-Fi Connectpis the same as Scan for Specific AP On All Channels, except that no scan-done event will be generated

Espressif Systems

1925

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Espressif Systems

Fig. 58: Background Scan of all Wi-Fi Channels

1926

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 59: Scan of specific Wi-Fi Channels

Espressif Systems

1927

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

when the scan is completed. If the target AP is found, the Wi-Fi driver will start the Wi-Fi connection; otherwise, WIFI_EVENT_STA_DISCONNECTED will be generated. Refer to Scan for Specific AP On All Channels.

Scan In Blocked Mode
If the block parameter of esp_wifi_scan_start() is true, then the scan is a blocked one, and the application task will be blocked until the scan is done. The blocked scan is similar to an unblocked one, except that no scan-done event will arise when the blocked scan is completed.

Parallel Scan
Two application tasks may call esp_wifi_scan_start() at the same time, or the same application task calls esp_wifi_scan_start() before it gets a scan-done event. Both scenarios can happen. However, the WiFi driver does not support multiple concurrent scans adequately. As a result, concurrent scans should be avoided. Support for concurrent scan will be enhanced in future releases, as the ESP32-S3ns Wi-Fi functionality improves continuously.

Scan When Wi-Fi is Connecting
The esp_wifi_scan_start() fails immediately if the Wi-Fi is in connecting process because the connecting has higher priority than the scan. If scan fails because of connecting, the recommended strategy is to delay sometime and retry scan again, the scan will succeed once the connecting is completed.
However, the retry/delay strategy may not work all the time. Considering following scenario:
· The station is connecting a non-existed AP or if the station connects the existed AP with a wrong password, it always raises the event WIFI_EVENT_STA_DISCONNECTED.
· The application call esp_wifi_connect() to do reconnection on receiving the disconnect event. · Another application task, e.g. the console task, call esp_wifi_scan_start() to do scan, the scan always
fails immediately because the station is keeping connecting. · When scan fails, the application simply delay sometime and retry the scan.
In above scenario the scan will never succeed because the connecting is in process. So if the application supports similar scenario, it needs to implement a better reconnect strategy. E.g.
· The application can choose to define a maximum continuous reconnect counter, stop reconnect once the reconnect reaches the max counter.
· The application can choose to do reconnect immediately in the first N continous reconnect, then give a delay sometime and reconnect again.
The application can define its own reconnect strategy to avoid the scan starve to death. Refer to <Wi-Fi Reconnect>.

4.37.10 ESP32-S3 Wi-Fi Station Connecting Scenario
This scenario only depicts the case when there is only one target AP are found in scan phase, for the scenario that more than one AP with the same SSID are found, refer to ESP32-S3 Wi-Fi Station Connecting When Multiple APs Are Found.
Generally, the application does not need to care about the connecting process. Below is a brief introduction to the process for those who are really interested.
Scenario:

Scan Phase
· s1.1, The Wi-Fi driver begins scanning inoWi-Fi Connectp. Refer to Scan in Wi-Fi Connect for more details. · s1.2, If the scan fails to find the target AP, WIFI_EVENT_STA_DISCONNECTED will arise and the reason-code
will be WIFI_REASON_NO_AP_FOUND. Refer to Wi-Fi Reason Code.

Espressif Systems

1928

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Espressif Systems

Fig. 60: Wi-Fi Station Connecting Process

1929

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Auth Phase
· s2.1, The authentication request packet is sent and the auth timer is enabled. · s2.2, If the authentication response packet is not received before the authentication timer
times out, WIFI_EVENT_STA_DISCONNECTED will arise and the reason-code will be WIFI_REASON_AUTH_EXPIRE. Refer to Wi-Fi Reason Code. · s2.3, The auth-response packet is received and the auth-timer is stopped. · s2.4, The AP rejects authentication in the response and WIFI_EVENT_STA_DISCONNECTED arises, while the reason-code is WIFI_REASON_AUTH_FAIL or the reasons specified by the AP. Refer to Wi-Fi Reason Code.
Association Phase
· s3.1, The association request is sent and the association timer is enabled. · s3.2, If the association response is not received before the association timer times
out, WIFI_EVENT_STA_DISCONNECTED will arise and the reason-code will be WIFI_REASON_ASSOC_EXPIRE. Refer to Wi-Fi Reason Code. · s3.3, The association response is received and the association timer is stopped. · s3.4, The AP rejects the association in the response and WIFI_EVENT_STA_DISCONNECTED arises, while the reason-code is the one specified in the association response. Refer to Wi-Fi Reason Code.
Four-way Handshake Phase
· s4.1, The handshake timer is enabled, the 1/4 EAPOL is not received before the handshake timer expires, WIFI_EVENT_STA_DISCONNECTED will arise and the reason-code will be WIFI_REASON_HANDSHAKE_TIMEOUT. Refer to Wi-Fi Reason Code.
· s4.2, The 1/4 EAPOL is received. · s4.3, The station replies 2/4 EAPOL. · s4.4, If the 3/4 EAPOL is not received before the handshake timer ex-
pires, WIFI_EVENT_STA_DISCONNECTED will arise and the reason-code will be WIFI_REASON_HANDSHAKE_TIMEOUT. Refer to Wi-Fi Reason Code. · s4.5, The 3/4 EAPOL is received. · s4.6, The station replies 4/4 EAPOL. · s4.7, The station raises WIFI_EVENT_STA_CONNECTED.
Wi-Fi Reason Code
The table below shows the reason-code defined in ESP32-S3. The first column is the macro name defined in esp_wifi_types.h. The common prefix WIFI_REASON is removed, which means that UNSPECIFIED actually stands for WIFI_REASON_UNSPECIFIED and so on. The second column is the value of the reason. The third column is the standard value to which this reason is mapped in section 8.4.1.7 of IEEE 802.11-2012. (For more information, refer to the standard mentioned above.) The last column is a description of the reason.

Espressif Systems

1930

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

ReasonValue code UNSPEC1IFIED
AUTH_E2XPIRE

Mapped To 1
2

Description
Generally, it means an internal failure, e.g., the memory runs out, the internal TX fails, or the reason is received from the remote side, etc. The previous authentication is no longer valid. For the ESP station, this reason is reported when:
· auth is timed out. · the reason is received from the AP. For the ESP AP, this reason is reported when: · the AP has not received any packets from the station in the
past five minutes. · the AP is stopped by calling esp_wifi_stop(). · the station is de-authed by calling
esp_wifi_deauth_sta().

AUTH_L3EAVE

3

De-authenticated, because the sending station is leaving (or has left). For the ESP station, this reason is reported when:
· it is received from the AP.

ASSOC_4EXPIRE

4

Disassociated due to inactivity. For the ESP station, this reason is reported when:
· it is received from the AP. For the ESP AP, this reason is reported when:
· the AP has not received any packets from the station in the past five minutes.
· the AP is stopped by calling esp_wifi_stop(). · the station is de-authed by calling
esp_wifi_deauth_sta().

ASSOC_5TOOMANY 5

Disassociated, because the AP is unable to handle all currently associated STAs at the same time. For the ESP station, this reason is reported when:
· it is received from the AP. For the ESP AP, this reason is reported when:
· the stations associated with the AP reach the maximum number that the AP can support.

NOT_AU6 THED

6

Class-2 frame received from a non-authenticated STA. For the ESP station, this reason is reported when:
· it is received from the AP. For the ESP AP, this reason is reported when:
· the AP receives a packet with data from a non-authenticated station.

NOT_AS7SOCED

7

Class-3 frame received from a non-associated STA. For the ESP station, this reason is reported when:
· it is received from the AP. For the ESP AP, this reason is reported when:
· the AP receives a packet with data from a non-associated station.

ASSOC_8LEAVE

8

Espressif Systems ASSOC_9NOT_AUTHED9

Disassociated, because the sending station is leaving (or has left)

BSS.

For the ESP station, this reason is reported when:

· it is received from the AP.

· the

station

is

disconnected

by

esp_wifi_disconnect() and other APIs.

1931

Release v5.0-dev-1424-g2467aa7f6c

SubmisttaDtioocnurmeqeunesttiFnege(dreb)aascsokciation is not authenticated by the re-

sponding STA.

For the ESP station, this reason is reported when:

Chapter 4. API Guides

4.37.11 ESP32-S3 Wi-Fi Station Connecting When Multiple APs Are Found
This scenario is similar as ESP32-S3 Wi-Fi Station Connecting Scenario, the difference is the station will not raise the event WIFI_EVENT_STA_DISCONNECTED unless it fails to connect all of the found APs.

4.37.12 Wi-Fi Reconnect
The station may disconnect due to many reasons, e.g. the connected AP is restarted etc. Itns the applicationns responsibility to do the reconnect. The recommended reconnect strategy is to call esp_wifi_connect() on receiving event WIFI_EVENT_STA_DISCONNECTED.
Sometimes the application needs more complex reconnect strategy:
· If the disconnect event is raised because the esp_wifi_disconnect() is called, the application may not want to do reconnect.
· If the esp_wifi_scan_start() may be called at anytime, a better reconnect strategy is necessary, refer to Scan When Wi-Fi is Connecting.
Another thing we need to consider is the reconnect may not connect the same AP if there are more than one APs with the same SSID. The reconnect always select current best APs to connect.

4.37.13 Wi-Fi Beacon Timeout
The beacon timeout mechanism is used by ESP32-S3 station to detect whether the AP is alive or not. If the station continuously loses 60 beacons of the connected AP, the beacon timeout happens. After the beacon timeout happens, the station sends 5 probe requests to AP, it disconnects the AP and raises the event WIFI_EVENT_STA_DISCONNECTED if still no probe response or beacon is received from AP.

4.37.14 ESP32-S3 Wi-Fi Configuration
All configurations will be stored into flash when the Wi-Fi NVS is enabled; otherwise, refer to Wi-Fi NVS Flash.

Wi-Fi Mode

Call esp_wifi_set_mode() to set the Wi-Fi mode.

Mode WIFI_MODE_NULL
WIFI_MODE_STA WIFI_MODE_AP WIFI_MODE_APSTA

Description NULL mode: in this mode, the internal data struct is not allocated to the station and the AP, while both the station and AP interfaces are not initialized for RX/TX Wi-Fi data. Generally, this mode is used for Sniffer, or when you only want to stop both the station and the AP without calling esp_wifi_deinit() to unload the whole Wi-Fi driver. Station mode: in this mode, esp_wifi_start() will init the internal station data, while the stationns interface is ready for the RX and TX Wi-Fi data. After esp_wifi_connect(), the station will connect to the target AP. AP mode: in this mode, esp_wifi_start() will init the internal AP data, while the APns interface is ready for RX/TX Wi-Fi data. Then, the Wi-Fi driver starts broad-casting beacons, and the AP is ready to get connected to other stations. Station/AP coexistence mode: in this mode, esp_wifi_start() will simultaneously init both the station and the AP. This is done in station mode and AP mode. Please note that the channel of the external AP, which the ESP station is connected to, has higher priority over the ESP AP channel.

Espressif Systems

1932

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Station Basic Configuration

API esp_wifi_set_config() can be used to configure the station. The table below describes the fields in detail.

Field ssid password scan_method bssid_set bssid channel sort_method
threshold

Description This is the SSID of the target AP, to which the station wants to connect to. Password of the target AP. For WIFI_FAST_SCAN scan, the scan ends when the first matched AP is found. For WIFI_ALL_CHANNEL_SCAN, the scan finds all matched APs on all channels. The default scan is WIFI_FAST_SCAN. If bssid_set is 0, the station connects to the AP whose SSID is the same as the field ossidp, while the field obssidpis ignored. In all other cases, the station connects to the AP whose SSID is the same as the ossidpfield, while its BSSID is the same the obssidpfield . This is valid only when bssid_set is 1; see field obssid_setp. If the channel is 0, the station scans the channel 1 ~ N to search for the target AP; otherwise, the station starts by scanning the channel whose value is the same as that of the ochannelpfield, and then scans others to find the target AP. If you do not know which channel the target AP is running on, set it to 0. This field is only for WIFI_ALL_CHANNEL_SCAN. If the sort_method is WIFI_CONNECT_AP_BY_SIGNAL, all matched APs are sorted by signal, for AP with best signal will be connected firstly. E.g. if the station want to connect AP whose ssid is oapxxp, the scan finds two AP whose ssid equals to oapxxp, the first APns signal is -90 dBm, the second APns signal is -30 dBm, the station connects the second AP firstly, it doesnnt connect the first one unless it fails to connect the second one. If the sort_method is WIFI_CONNECT_AP_BY_SECURITY, all matched APs are sorted by security. E.g. if the station wants to connect AP whose ssid is oapxxp, the scan finds two AP whose ssid is oapxxp, the security of the first found AP is open while the second one is WPA2, the stations connects to the second AP firstly, it doesnn t connect the second one unless it fails to connect the first one. The threshold is used to filter the found AP, if the RSSI or security mode is less than the configured threshold, the AP will be discard. If the RSSI set to 0, it means default threshold, the default RSSI threshold is -127 dBm. If the authmode threshold is set to 0, it means default threshold, the default authmode threshold is open.

Attention: WEP/WPA security modes are deprecated in IEEE 802.11-2016 specifications and are recommended not to be used. These modes can be rejected using authmode threshold by setting threshold as WPA2 by threshold.authmode as WIFI_AUTH_WPA2_PSK.

AP Basic Configuration API esp_wifi_set_config() can be used to configure the AP. The table below describes the fields in detail.

Espressif Systems

1933

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Field ssid password ssid_len channel
authmode ssid_hidden max_connection beacon_interval

Description SSID of AP; if the ssid[0] is 0xFF and ssid[1] is 0xFF, the AP defaults the SSID to ESP_aabbcc, where oaabbccpis the last three bytes of the AP MAC. Password of AP; if the auth mode is WIFI_AUTH_OPEN, this field will be ignored. Length of SSID; if ssid_len is 0, check the SSID until there is a termination character. If ssid_len > 32, change it to 32; otherwise, set the SSID length according to ssid_len. Channel of AP; if the channel is out of range, the Wi-Fi driver defaults the channel to channel 1. So, please make sure the channel is within the required range. For more details, refer to Wi-Fi Country Code. Auth mode of ESP AP; currently, ESP Wi-Fi does not support AUTH_WEP. If the authmode is an invalid value, AP defaults the value to WIFI_AUTH_OPEN. If ssid_hidden is 1, AP does not broadcast the SSID; otherwise, it does broadcast the SSID. Currently, ESP Wi-Fi supports up to 10 Wi-Fi connections. If max_connection > 10, AP defaults the value to 10. Beacon interval; the value is 100 ~ 60000 ms, with default value being 100 ms. If the value is out of range, AP defaults it to 100 ms.

Wi-Fi Protocol Mode

Currently, the IDF supports the following protocol modes:

Protocol Mode 802.11b 802.11bg 802.11bgn
802.11 BGNLR
802.11 LR

Description

Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B) to set the station/AP to

802.11b-only mode.

Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G) to

set the station/AP to 802.11bg mode.

Call

esp_wifi_set_protocol(ifx,

WIFI_PROTOCOL_11B|

WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N) to set the station/ AP to BGN

mode.

Call

esp_wifi_set_protocol(ifx,

WIFI_PROTOCOL_11B|

WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N|WIFI_PROTOCOL_LR)

to

set the station/AP to BGN and the Espressif-specific mode.

Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_LR) to set the station/AP only to

the Espressif-specific mode.

This mode is an Espressif-patented mode which can achieve a one-kilometer line

of sight range. Please, make sure both the station and the AP are connected to an

ESP device.

Long Range (LR)
Long Range (LR) mode is an Espressif-patented Wi-Fi mode which can achieve a one-kilometer line of sight range. It has better reception sensitivity, stronger anti-interference ability and longer transmission distance than the traditional 802.11b mode.
LR Compatibility Since LR is Espressif unique Wi-Fi mode, only ESP32-S3 devices can transmit and receive the LR data. In other words, the ESP32-S3 device should NOT transmit the data in LR data rate if the connected device doesnnt support LR. The application can achieve this by configuring suitable Wi-Fi mode. If the negotiated mode supports LR, the ESP32-S3 may transmit data in LR rate, otherwise, ESP32-S3 will transmit all data in traditional Wi-Fi data rate.
Following table depicts the Wi-Fi mode negotiation:

Espressif Systems

1934

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

APSTA BGN BG B BGNLR BGLR BLR LR

BGN BGN BG B
· · · ·

BG BG BG B
· · · ·

B B B B
· · · ·

BGNLR BGLR

BLR

BGN

BG

B

BG

BG

B

B

B

B

BGNLR BGLR

BLR

BGLR

BGLR

BLR

BLR

BLR

BLR

LR

LR

LR

LR · · ·
LR LR LR LR

In above table, the row is the Wi-Fi mode of AP and the column is the Wi-Fi mode of station. The o-pindicates Wi-Fi mode of the AP and station are not compatible. According to the table, we can conclude that:
· For LR enabled in ESP32-S3 AP, itns incompatible with traditional 802.11 mode because the beacon is sent in LR mode.
· For LR enabled in ESP32-S3 station and the mode is NOT LR only mode, itns compatible with traditional 802.11 mode.
· If both station and AP are ESP32-S3 devices and both of them enable LR mode, the negotiated mode supports LR.
If the negotiated Wi-Fi mode supports both traditional 802.11 mode and LR mode, itns the Wi-Fi driverns responsibility to automatically select the best data rate in different Wi-Fi mode and the application donnt need to care about it.
LR Impacts to Traditional Wi-Fi device The data transmission in LR rate has no impacts on the traditional Wi-Fi device because:
· The CCA and backoff process in LR mode are consistent with 802.11 specification. · The traditional Wi-Fi device can detect the LR signal via CCA and do backoff. In other words, the impact transmission in LR mode is similar as the impact in 802.11b mode.
LR Transmission Distance The reception sensitivity of LR has about 4 dB gain than the traditional 802.11b mode, theoretically the transmission distance is about 2 to 2.5 times the distance of 11B.
LR Throughput The LR rate has very limited throughput because the raw PHY data rate LR is 1/2 Mbits and 1/4 Mbits.
When to Use LR The general conditions for using LR are: · Both the AP and station are devices. · Long distance Wi-Fi connection and data transmission is required. · Data throughput requirements are very small, such as remote device control, etc.

Espressif Systems

1935

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Wi-Fi Country Code
Call esp_wifi_set_country() to set the country info. The table below describes the fields in detail, please consult local 2.4 GHz RF operating regulations before configuring these fields.

Field cc[3]
schan nchan policy

Description Country code string, this attributes identify the country or noncountry entity in which the station/AP is operating. If itns a country, the first two octets of this string is the two character country info as described in document ISO/IEC3166-1. The third octect is one of the following:
· an ASCII space character, if the regulations under which the station/AP is operating encompass all environments for the current frequency band in the country.
· an ASCIImOncharacter if the regulations under which the station/AP is operating are for an outdoor environment only.
· an ASCIImIncharacter if the regulations under which the station/AP is operating are for an indoor environment only.
· an ASCIImXncharacter if the station/AP is operating under a noncountry entity. The first two octets of the noncountry entity is two ASCII mXXncharacters.
· the binary representation of the Operating Class table number currently in use. Refer to Annex E, IEEE Std 802.11-2012.
Start channel, itns the minimum channel number of the regulations under which the station/AP can operate. Total number of channels as per the regulations, e.g. if the schan=1, nchan=13, it means the station/AP can send data from channel 1 to 13. Country policy, this field control which country info will be used if the configured country info is conflict with the connected APns. More description about policy is provided in following section.

The default country info is {.cc=pCNp, .schan=1, .nchan=13, policy=WIFI_COUNTRY_POLICY_AUTO}, if the Wi-Fi Mode is station/AP coexist mode, they share the same configured country info. Sometimes, the country info of AP, to which the station is connected, is different from the country info of configured. For example, the configured station has country info {.cc=pJPp, .schan=1, .nchan=14, policy=WIFI_COUNTRY_POLICY_AUTO}, but the connected AP has country info {.cc=pCNp, .schan=1, .nchan=13}, then country info of connected APns is used.
Following table depicts which country info is used in different Wi-Fi Mode and different country policy, also describe the impact to active scan.

Espressif Systems

1936

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Wi-Fi Mode Station
Station AP AP Station/AP-coexistence

Policy

Description

WIFI_COUNTRY_POLICIfYt_hAe UcoTnOnected AP has country IE in its beacon, the coun-

try info equals to the country info in beacon, otherwise, use

default country info.

For scan:

· If schan+nchan-1 >11 :

Use active scan from schan to 11 and use passive scan

from 12 to schan+nchan-1.

· If schan+nchan-1 <= 11 :

Use active scan from schan to schan+nchan-1.

Always keep in mind that if an AP with hidden SSID

and station is set to a passive scan channel, the passive

scan will not find it. In other words, if the application

hopes to find the AP with hidden SSID in every chan-

nel, the policy of country info should be configured to

WIFI_COUNTRY_POLICY_MANUAL.

WIFI_COUNTRY_POLICAYlw_aMysAuNsUe AthLe configured country info. For scan, scans

channel oschanpto oschan+nchan-1pwith active scan.

WIFI_COUNTRY_POLICAYlw_aAyUs TusOe the configured country info.

WIFI_COUNTRY_POLICAYlw_aMysAuNseUAthLe configured country info.

WIFI_COUNTRY_POLICIfYt_hAe UstaTtOion doesnnt connects to any external AP, the AP

use the configured country info. If the station connects to an

external AP, the AP has the same country info as the station.

Same as station mode with policy

WIFI_COUNTRY_POLICY_AUTO.

Home Channel In AP mode, the home channel is defined as the AP channel. In station mode, home channel is defined as the channel of AP which the station is connected to. In station/AP-coexistence mode, the home channel of AP and station must be the same, if they are different, the stationns home channel is always in priority. Take the following as an example: the AP is on channel 6, and the station connects to an AP whose channel is 9. Since the stationns home channel has higher priority, the AP needs to switch its channel from 6 to make sure that it has the same home channel as the station. While switching channel, the ESP32-S3 in AP mode will notify the connected stations about the channel migration using a Channel Switch Announcement (CSA). Station that supports channel switching will transit without disconnecting and reconnecting to the AP.

Wi-Fi Vendor IE Configuration
By default, all Wi-Fi management frames are processed by the Wi-Fi driver, and the application does not need to care about them. Some applications, however, may have to handle the beacon, probe request, probe response and other management frames. For example, if you insert some vendor-specific IE into the management frames, it is only the management frames which contain this vendor-specific IE that will be processed. In ESP32-S3, esp_wifi_set_vendor_ie() and esp_wifi_set_vendor_ie_cb() are responsible for this kind of tasks.

4.37.15 Wi-Fi Easy ConnectTM (DPP)
Wi-Fi Easy ConnectTM (or Device Provisioning Protocol) is a secure and standardized provisioning protocol for configuration of Wi-Fi Devices. More information can be found on the API reference page esp_dpp.

WPA2-Enterprise
WPA2-Enterprise is the secure authentication mechanism for enterprise wireless networks. It uses RADIUS server for authentication of network users before connecting to the Access Point. The authentication process is based on 802.1X policy and comes with different Extended Authentication Protocol (EAP) methods like TLS, TTLS, PEAP

Espressif Systems

1937

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

etc. RADIUS server authenticates the users based on their credentials (username and password), digital certificates or both. When ESP32-S3 in station mode tries to connect to an AP in enterprise mode, it sends authentication request to AP which is sent to RADIUS server by AP for authenticating the station. Based on different EAP methods, the parameters can be set in configuration which can be opened using idf.py menuconfig. WPA2_Enterprise is supported by ESP32-S3 only in station mode.
For establishing a secure connection, AP and station negotiate and agree on the best possible cipher suite to be used. ESP32-S3 supports 802.1X/EAP (WPA) method of AKM and Advanced encryption standard with Counter Mode Cipher Block Chaining Message Authentication protocol (AES-CCM) cipher suite. It also supports the cipher suites supported by mbedtls if USE_MBEDTLS_CRYPTO flag is set.
ESP32-S3 currently supports the following EAP methods: · EAP-TLS: This is certificate based method and only requires SSID and EAP-IDF. · PEAP: This is Protected EAP method. Username and Password are mandatory. · EAP-TTLS: This is credentials based method. Only server authentication is mandatory while user authentication
­ PAP: Password Authentication Protocol. ­ CHAP: Challenge Handshake Authentication Protocol. ­ MSCHAP and MSCHAP-V2. · EAP-FAST: This is a Protected Access Credentials (PAC) based authentication method which also uses identity and password. Currently, USE_MBEDTLS_CRYPTO flag should be disabled to use this feature.
Detailed information on creating certificates and how to run wpa2_enterprise example on ESP32-S3 can be found in wifi/wifi_enterprise.
4.37.16 Wireless Network Management
Wireless Network Management allows client devices to exchange information about the network topology, including information related to RF environment. This makes each client network-aware, facilitating overall improvement in the performace of the wireless network. It is part of 802.11v specification. It also enables client to support Network assisted Roaming. - Network assisted Roaming: Enables WLAN to send messages to associated clients, resulting clients to associate with APs with better link metrics. This is useful for both load balancing and in directing poorly connected clients.
Current implementation of 802.11v includes support for BSS transition management frames.
4.37.17 Radio Resource Measurement
Radio Resource Measurement (802.11k) is intended to improve the way traffic is distributed within a network. In a wireless LAN, each device normally connects to the access point (AP) that provides the strongest signal. Depending on the number and geographic locations of the subscribers, this arrangement can sometimes lead to excessive demand on one AP and underutilization of others, resulting in degradation of overall network performance. In a network conforming to 802.11k, if the AP having the strongest signal is loaded to its full capacity, a wireless device can be moved to one of the underutilized APs. Even though the signal may be weaker, the overall throughput is greater because more efficient use is made of the network resources.
Current implementation of 802.11k includes support for beacon measurement report, link measurement report and neighbor request.
Refer IDF example examples/wifi/roaming/README.md to set up and use these APIs. Example code only demonstrates how these APIs can be used, the application should define its own algorithm and cases as required.
4.37.18 ESP32-S3 Wi-Fi Power-saving Mode
Station Sleep
Currently, ESP32-S3 Wi-Fi supports the Modem-sleep mode which refers to the legacy power-saving mode in the IEEE 802.11 protocol. Modem-sleep mode works in station-only mode and the station must connect to the AP first.

Espressif Systems

1938

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

If the Modem-sleep mode is enabled, station will switch between active and sleep state periodically. In sleep state, RF, PHY and BB are turned off in order to reduce power consumption. Station can keep connection with AP in modem-sleep mode.
Modem-sleep mode includes minimum and maximum power save modes. In minimum power save mode, station wakes up every DTIM to receive beacon. Broadcast data will not be lost because it is transmitted after DTIM. However, it can not save much more power if DTIM is short for DTIM is determined by AP.
In maximum power save mode, station wakes up every listen interval to receive beacon. This listen interval can be set longer than the AP DTIM period. Broadcast data may be lost because station may be in sleep state at DTIM time. If listen interval is longer, more power is saved but broadcast data is more easy to lose. Listen interval can be configured by calling API esp_wifi_set_config() before connecting to AP.
Call esp_wifi_set_ps(WIFI_PS_MIN_MODEM) to enable Modem-sleep minimum power save mode or esp_wifi_set_ps(WIFI_PS_MAX_MODEM) to enable Modem-sleep maximum power save mode after calling esp_wifi_init(). When station connects to AP, Modem-sleep will start. When station disconnects from AP, Modem-sleep will stop.
Call esp_wifi_set_ps(WIFI_PS_NONE) to disable modem sleep entirely. This has much higher power consumption, but provides minimum latency for receiving Wi-Fi data in real time. When modem sleep is enabled, received Wi-Fi data can be delayed for as long as the DTIM period (minimum power save mode) or the listen interval (maximum power save mode). Disabling modem sleep entirely is not possible for Wi-Fi and Bluetooth coexist mode.
The default Modem-sleep mode is WIFI_PS_MIN_MODEM.

AP Sleep
Currently ESP32-S3 AP doesnnt support all of the power save feature defined in Wi-Fi specification. To be specific, the AP only caches unicast data for the stations connect to this AP, but doesnnt cache the multicast data for the stations. If stations connected to the ESP32-S3 AP are power save enabled, they may experience multicast packet loss.
In the future, all power save features will be supported on ESP32-S3 AP.

4.37.19 ESP32-S3 Wi-Fi Throughput
The table below shows the best throughput results we got in Espressifns lab and in a shield box.

Type/ThroughpAuirt In Lab

Raw 802.11 N/A

Packet RX

Raw 802.11 N/A

Packet TX

UDP RX

30 MBit/s

UDP TX

30 MBit/s

TCP RX

20 MBit/s

TCP TX

20 MBit/s

Shield-box Test Tool 130 MBit/s Internal tool

130 MBit/s Internal tool

88 MBit/s 98 MBit/s 73 MBit/s 83 MBit/s

iperf example iperf example iperf example iperf example

IDF Version (commit ID) NA
NA
15575346 15575346 15575346 15575346

When the throughput is tested by iperf example, the sdkconfig is examples/wifi/iperf/sdkconfig.defaults.esp32s3.

4.37.20 Wi-Fi 80211 Packet Send
The esp_wifi_80211_tx() API can be used to: · Send the beacon, probe request, probe response, action frame. · Send the non-QoS data frame.
It cannot be used for sending encrypted or QoS frames.

Espressif Systems

1939

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Preconditions of Using esp_wifi_80211_tx()
· The Wi-Fi mode is station, or AP, or station/AP. · Either esp_wifi_set_promiscuous(true), or esp_wifi_start(), or both of these APIs return ESP_OK.
This is because we need to make sure that Wi-Fi hardware is initialized before esp_wifi_80211_tx() is called. In ESP32-S3, both esp_wifi_set_promiscuous(true) and esp_wifi_start() can trigger the initialization of Wi-Fi hardware. · The parameters of esp_wifi_80211_tx() are hereby correctly provided.
Data rate
· If there is no Wi-Fi connection, the data rate is 1 Mbps. · If there is Wi-Fi connection and the packet is from station to AP or from AP to station, the data rate is same
as the Wi-Fi connection. Otherwise the data rate is 1 Mbps.
Side-Effects to Avoid in Different Scenarios
Theoretically, if we do not consider the side-effects the API imposes on the Wi-Fi driver or other stations/APs, we can send a raw 802.11 packet over the air, with any destination MAC, any source MAC, any BSSID, or any other type of packet. However,robust/useful applications should avoid such side-effects. The table below provides some tips/recommendations on how to avoid the side-effects of esp_wifi_80211_tx() in different scenarios.

Espressif Systems

1940

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Scenario No Wi-Fi connection
Have Wi-Fi connection

Description In this scenario, no Wi-Fi connection is set up, so there are no side-effects on the Wi-Fi driver. If en_sys_seq==true, the Wi-Fi driver is responsible for the sequence control. If en_sys_seq==false, the application needs to ensure that the buffer has the correct sequence. Theoretically, the MAC address can be any address. However, this may impact other stations/APs with the same MAC/BSSID. Side-effect example#1 The application calls esp_wifi_80211_tx to send a beacon with BSSID == mac_x in AP mode, but the mac_x is not the MAC of the AP interface. Moreover, there is another AP, say oother-APp, whose bssid is mac_x. If this happens, an ounexpected behaviorpmay occur, because the stations which connect to the oother-APpcannot figure out whether the beacon is from the oother-APpor the esp_wifi_80211_tx. To avoid the above-mentioned side-effects, we recommend that:
· If esp_wifi_80211_tx is called in station mode, the first MAC should be a multicast MAC or the exact target-devicens MAC, while the second MAC should be that of the station interface.
· If esp_wifi_80211_tx is called in AP mode, the first MAC should be a multicast MAC or the exact target-devicens MAC, while the second MAC should be that of the AP interface.
The recommendations above are only for avoiding side-effects and can be ignored when there are good reasons for doing this. When the Wi-Fi connection is already set up, and the sequence is controlled by the application, the latter may impact the sequence control of the Wi-Fi connection, as a whole. So, the en_sys_seq need to be true, otherwise ESP_ERR_WIFI_ARG is returned. The MAC-address recommendations in the oNo Wi-Fi connectionpscenario also apply to this scenario. If the Wi-Fi mode is station mode and the MAC address1 is the MAC of AP to which the station is connected, the MAC address2 is the MAC of station interface, we say the packets is from the station to AP. On the other hand, if the Wi-Fi mode is AP mode and the MAC address1 is the MAC of the station who connects to this AP, the MAC address2 is the MAC of AP interface, we say the packet is from the AP to station. To avoid conflicting with Wi-Fi connections, the following checks are applied:
· If the packet type is data and is from the station to AP, the ToDS bit in IEEE 80211 frame control should be 1, the FromDS bit should be 0, otherwise the packet will be discarded by Wi-Fi driver.
· If the packet type is data and is from the AP to station, the ToDS bit in IEEE 80211 frame control should be 0, the FromDS bit should be 1, otherwise the packet will be discarded by Wi-Fi driver.
· If the packet is from station to AP or from AP to station, the Power Management, More Data, Re-Transmission bits should be 0, otherwise the packet will be discarded by Wi-Fi driver.
ESP_ERR_WIFI_ARG is returned if any check fails.

4.37.21 Wi-Fi Sniffer Mode
The Wi-Fi sniffer mode can be enabled by esp_wifi_set_promiscuous(). If the sniffer mode is enabled, the following packets can be dumped to the application:
· 802.11 Management frame. · 802.11 Data frame, including MPDU, AMPDU, AMSDU, etc. · 802.11 MIMO frame, for MIMO frame, the sniffer only dumps the length of the frame. · 802.11 Control frame. · 802.11 CRC error frame.
The following packets will NOT be dumped to the application:
· Other 802.11 error frames.
For frames that the sniffer can dump, the application can additionally decide which specific type of

Espressif Systems

1941

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

packets can be filtered to the application by using esp_wifi_set_promiscuous_filter() and esp_wifi_set_promiscuous_ctrl_filter(). By default, it will filter all 802.11 data and management frames to the application.
The Wi-Fi sniffer mode can be enabled in the Wi-Fi mode of WIFI_MODE_NULL, or WIFI_MODE_STA, or WIFI_MODE_AP, or WIFI_MODE_APSTA. In other words, the sniffer mode is active when the station is connected to the AP, or when the AP has a Wi-Fi connection. Please note that the sniffer has a great impact on the throughput of the station or AP Wi-Fi connection. Generally, we should NOT enable the sniffer, when the station/AP Wi-Fi connection experiences heavy traffic unless we have special reasons.
Another noteworthy issue about the sniffer is the callback wifi_promiscuous_cb_t. The callback will be called directly in the Wi-Fi driver task, so if the application has a lot of work to do for each filtered packet, the recommendation is to post an event to the application task in the callback and defer the real work to the application task.

4.37.22 Wi-Fi Multiple Antennas

The Wi-Fi multiple antennas selecting can be depicted as following picture:

__________

|Enabled |

___|Antenna 0 |\\

_

|__________| \\

 | --- antenna 0

RX/TX ___

\\____\

Antenna | --- antenna 1

\

__________ // /

 | ... ...

\ ___|Enabled | //

_| --- antenna 15

\ |Antenna 1 |//

|__________|

________

GPIO[0] <----> antenna_select[0] ---|



GPIO[1] <----> antenna_select[1] ---|

GPIO[2] <----> antenna_select[2] ---| Switch

GPIO[3] <----> antenna_select[3] ---|________

ESP32-S3 supports up to sixteen antennas through external antenna switch. The antenna switch can be controlled by up to four address pins - antenna_select[0:3]. Different input value of antenna_select[0:3] means selecting different antenna. E.g. the value m0b1011nmeans the antenna 11 is selected. The default value of antenna_select[3:0] is m0b0000n, it means the antenna 0 is selected by default.
Up to four GPIOs are connected to the four active high antenna_select pins. ESP32-S3 can select the antenna by control the GPIO[0:3]. The API esp_wifi_set_ant_gpio() is used to configure which GPIOs are connected to antenna_selects. If GPIO[x] is connected to antenna_select[x], then gpio_config->gpio_cfg[x].gpio_select should be set to 1 and gpio_config->gpio_cfg[x].gpio_num should be provided.
Although up to sixteen anteenas are supported, only one or two antennas can be simultaneously enabled for RX/TX. The API esp_wifi_set_ant() is used to configure which antennas are enabled.
The enabled antennas selecting algorithm is also configured by esp_wifi_set_ant(). The RX/TX antenna mode can be WIFI_ANT_MODE_ANT0, WIFI_ANT_MODE_ANT1 or WIFI_ANT_MODE_AUTO. If the antenna mode is WIFI_ANT_MODE_ANT0, the enabled antenna 0 is selected for RX/TX data. If the antenna mode is WIFI_ANT_MODE_ANT1, the enabled antenna 1 is selected for RX/TX data. Otherwise, Wi-Fi automatically selects the antenna that has better signal from the enabled antennas.
If the RX antenna mode is WIFI_ANT_MODE_AUTO, the default antenna mode also needs to be set. Because the RX antenna switching only happens when some conditions are met, e.g. the RX antenna starts to switch if the RSSI is lower than -65 dBm and if another antenna has better signal etc, RX uses the default antenna if the conditions are not met. If the default antenna mode is WIFI_ANT_MODE_ANT1, the enabled antenna 1 is used as the default RX antenna, otherwise the enabled antenna 0 is used as the default RX antenna.
Some limitations need to be considered:
· The TX antenna can be set to WIFI_ANT_MODE_AUTO only if the RX antenna mode is WIFI_ANT_MODE_AUTO because TX antenna selecting algorithm is based on RX antenna in WIFI_ANT_MODE_AUTO type.

Espressif Systems

1942

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· Currently Bluetooth® doesnnt support the multiple antennas feature, please donnt use multiple antennas related APIs.
Following is the recommended scenarios to use the multiple antennas:
· In Wi-Fi mode WIFI_MODE_STA, both RX/TX antenna modes are configured to WIFI_ANT_MODE_AUTO. The Wi-Fi driver selects the better RX/TX antenna automatically.
· The RX antenna mode is configured to WIFI_ANT_MODE_AUTO. The TX antenna mode is configured to WIFI_ANT_MODE_ANT0 or WIFI_ANT_MODE_ANT1. The applications can choose to always select a specified antenna for TX, or implement their own TX antenna selecting algorithm, e.g. selecting the TX antenna mode based on the channel switch information etc.
· Both RX/TX antenna modes are configured to WIFI_ANT_MODE_ANT0 or WIFI_ANT_MODE_ANT1.
Wi-Fi Multiple Antennas Configuration
Generally, following steps can be taken to configure the multiple antennas:
· Configure which GPIOs are connected to the antenna_selects, for example, if four antennas are supported and GPIO20/GPIO21 are connected to antenna_select[0]/antenna_select[1], the configurations look like:
wifi_ant_gpio_config_t config = { { .gpio_select = 1, .gpio_num = 20 }, { .gpio_select = 1, .gpio_num = 21 }
};
· Configure which antennas are enabled and how RX/TX use the enabled antennas, for example, if antenna1 and antenna3 are enabled, the RX needs to select the better antenna automatically and uses antenna1 as its default antenna, the TX always selects the antenna3. The configuration looks like:
wifi_ant_config_t config = { .rx_ant_mode = WIFI_ANT_MODE_AUTO, .rx_ant_default = WIFI_ANT_ANT0, .tx_ant_mode = WIFI_ANT_MODE_ANT1, .enabled_ant0 = 1, .enabled_ant1 = 3
};
4.37.23 Wi-Fi Channel State Information
Channel state information (CSI) refers to the channel information of a Wi-Fi connection. In ESP32-S3, this information consists of channel frequency responses of sub-carriers and is estimated when packets are received from the transmitter. Each channel frequency response of sub-carrier is recorded by two bytes of signed characters. The first one is imaginary part and the second one is real part. There are up to three fields of channel frequency responses according to the type of received packet. They are legacy long training field (LLTF), high throughput LTF (HT-LTF) and space time block code HT-LTF (STBC-HT-LTF). For different types of packets which are received on channels with different state, the sub-carrier index and total bytes of signed characters of CSI is shown in the following table.

Espressif Systems

1943

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

channelsecondanryone

below

above

chan-

nel

packet signal non HT

non HT

non HT

informamtioonde HT

HT

HT

channel20 20 MHz

20 20 MHz

40 MHz

20 20 MHz

40 MHz

band- MHz

MHz

MHz

width

STBC non non STBC non non STBC non STBC non non STBC non STBC

STBC STBC

STBC STBC

STBC

STBC STBC

STBC

sub- LLTF 0~31, 0~31, 0~31, 0~63 0~63 0~63 0~63 0~63 -

-

-

-

-

carrier

-

-

-

64~- 64~- 64~- 64~- 64~-

index

32~- 32~- 32~-

1

1

1

1

1

111

HTLTF

·

0~31, 0~31,

-

-

·

0~63

0~62

0~63, 0~60,

-

-

·

64~-

62~-

0~63, 0~60,

-

-

32~- 32~-

64~- 60~-

1 1 64~- 60~-

11

11

1

1

STBCHT-

·

·

0~31, -

·

· 0~62

·

0~60, -

·

·

62~-

·

0~60, -

LTF

32~-

60~-

1

60~-

1

1

1

total bytes 128 256 384 128 256 380 384 612 128 256 376 384 612

All of the information in the table can be found in the structure wifi_csi_info_t.
· Secondary channel refers to secondary_channel field of rx_ctrl field. · Signal mode of packet refers to sig_mode field of rx_ctrl field. · Channel bandwidth refers to cwb field of rx_ctrl field. · STBC refers to stbc field of rx_ctrl field. · Total bytes refers to len field. · The CSI data corresponding to each Long Training Field (LTF) type is stored in a buffer starting from the buf
field. Each item is stored as two bytes: imaginary part followed by real part. The order of each item is the same as the sub-carrier in the table. The order of LTF is: LLTF, HT-LTF, STBC-HT-LTF. However all 3 LTFs may not be present, depending on the channel and packet information (see above). · If first_word_invalid field of wifi_csi_info_t is true, it means that the first four bytes of CSI data is invalid due to a hardware limitation in ESP32-S3. · More information like RSSI, noise floor of RF, receiving time and antenna is in the rx_ctrl field.

Note:
· For STBC packet, CSI is provided for every space-time stream without CSD (cyclic shift delay). As each cyclic shift on the additional chains shall be -200 ns, only the CSD angle of first space-time stream is recorded in sub-carrier 0 of HT-LTF and STBC-HT-LTF for there is no channel frequency response in sub-carrier 0. CSD[10:0] is 11 bits, ranging from -pi to pi.
· If LLTF, HT-LTF or STBC-HT-LTF is not enabled by calling API esp_wifi_set_csi_config(), the total bytes of CSI data will be fewer than that in the table. For example, if LLTF and HT-LTF is not enabled and STBC-HT-LTF is enabled, when a packet is received with the condition above/HT/40MHz/STBC, the total bytes of CSI data is 244 ((61 + 60) * 2 + 2 = 244, the result is aligned to four bytes and the last two bytes is invalid).

4.37.24 Wi-Fi Channel State Information Configure
To use Wi-Fi CSI, the following steps need to be done.

Espressif Systems

1944

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

· Select Wi-Fi CSI in menuconfig. It is oMenuconfig > Components config > Wi-Fi > Wi-Fi CSI (Channel State Information)p.
· Set CSI receiving callback function by calling API esp_wifi_set_csi_rx_cb(). · Configure CSI by calling API esp_wifi_set_csi_config(). · Enable CSI by calling API esp_wifi_set_csi().
The CSI receiving callback function runs from Wi-Fi task. So, do not do lengthy operations in the callback function. Instead, post necessary data to a queue and handle it from a lower priority task. Because station does not receive any packet when it is disconnected and only receives packets from AP when it is connected, it is suggested to enable sniffer mode to receive more CSI data by calling esp_wifi_set_promiscuous().

4.37.25 Wi-Fi HT20/40
ESP32-S3 supports Wi-Fi bandwidth HT20 or HT40, it doesnnt support HT20/40 coexist. esp_wifi_set_bandwidth() can be used to change the default bandwidth of station or AP. The default bandwidth for ESP32-S3 station and AP is HT40.
In station mode, the actual bandwidth is firstly negotiated during the Wi-Fi connection. It is HT40 only if both the station and the connected AP support HT40, otherwise itns HT20. If the bandwidth of connected AP is changes, the actual bandwidth is negotiated again without Wi-Fi disconnecting.
Similarly, in AP mode, the actual bandwidth is negotiated between AP and the stations that connect to the AP. Itns HT40 if the AP and one of the stations support HT40, otherwise itns HT20.
In station/AP coexist mode, the station/AP can configure HT20/40 seperately. If both station and AP are negotiated to HT40, the HT40 channel should be the channel of station because the station always has higher priority than AP in ESP32-S3. E.g. the configured bandwidth of AP is HT40, the configured primary channel is 6 and the configured secondary channel is 10. The station is connected to an router whose primary channel is 6 and secondary channel is 2, then the actual channel of AP is changed to primary 6 and secondary 2 automatically.
Theoretically the HT40 can gain better throughput because the maximum raw physicial (PHY) data rate for HT40 is 150Mbps while itns 72Mbps for HT20. However, if the device is used in some special environment, e.g. there are too many other Wi-Fi devices around the ESP32-S3 device, the performance of HT40 may be degraded. So if the applications need to support same or similar scenarios, itns recommended that the bandwidth is always configured to HT20.

4.37.26 Wi-Fi QoS
ESP32-S3 supports all the mandatory features required in WFA Wi-Fi QoS Certification.
Four ACs (Access Category) are defined in Wi-Fi specification, each AC has a its own priority to access the Wi-Fi channel. Moreover a map rule is defined to map the QoS priority of other protocol, such as 802.11D or TCP/IP precedence to Wi-Fi AC.
Below is a table describes how the IP Precedences are mapped to Wi-Fi ACs in ESP32-S3, it also indicates whether the AMPDU is supported for this AC. The table is sorted with priority descending order, namely, the AC_VO has highest priority.

IP Precedence 6, 7 4, 5 3, 0 1, 2

Wi-Fi AC AC_VO (Voice) AC_VI (Video) AC_BE (Best Effort) AC_BK (Background)

Support AMPDU? No Yes Yes Yes

The application can make use of the QoS feature by configuring the IP precedence via socket option IP_TOS. Here is an example to make the socket to use VI queue:

Espressif Systems

1945

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

const int ip_precedence_vi = 4; const int ip_precedence_offset = 5; int priority = (ip_precedence_vi << ip_precedence_offset); setsockopt(socket_id, IPPROTO_IP, IP_TOS, &priority, sizeof(priority));
Theoretically the higher priority AC has better performance than the low priority AC, however, itns not always be true, here are some suggestions about how to use the Wi-Fi QoS:
· For some really important application traffic, can put it into AC_VO queue. Avoid sending big traffic via AC_VO queue. On one hand, the AC_VO queue doesnnt support AMPDU and it cannt get better performance than other queue if the traffic is big, on the other hand, it may impact the the management frames that also use AC_VO queue.
· Avoid using more than two different AMPDU supported precedences, e.g. socket A uses precedence 0, socket B uses precedence 1, socket C uses precedence 2, this is a bad design because it may need much more memory. To be detailed, the Wi-Fi driver may generate a Block Ack session for each precedence and it needs more memory if the Block Ack session is setup.
4.37.27 Wi-Fi AMSDU
ESP32-S3 supports receiving and transmitting AMSDU.
4.37.28 Wi-Fi Fragment
ESP32-S3 supports Wi-Fi receiving and transmitting fragment.
4.37.29 WPS Enrollee
ESP32-S3 supports WPS enrollee feature in Wi-Fi mode WIFI_MODE_STA or WIFI_MODE_APSTA. Currently ESP32-S3 supports WPS enrollee type PBC and PIN.
4.37.30 Wi-Fi Buffer Usage
This section is only about the dynamic buffer configuration.
Why Buffer Configuration Is Important
In order to get a , high-performance system, we need to consider the memory usage/configuration very carefully, because:
· the available memory in ESP32-S3 is limited. · currently, the default type of buffer in LwIP and Wi-Fi drivers is odynamicp, which means that both
the LwIP and Wi-Fi share memory with the application. Programmers should always keep this in mind; otherwise, they will face a memory issue, such as orunning out of heap memoryp. · it is very dangerous to run out of heap memory, as this will cause ESP32-S3 anoundefined behaviorp. Thus, enough heap memory should be reserved for the application, so that it never runs out of it. · the Wi-Fi throughput heavily depends on memory-related configurations, such as the TCP window size, Wi-Fi RX/TX dynamic buffer number, etc. · the peak heap memory that the ESP32-S3 LwIP/Wi-Fi may consume depends on a number of factors, such as the maximum TCP/UDP connections that the application may have, etc. · the total memory that the application requires is also an important factor when considering memory configuration. Due to these reasons, there is not a good-for-all application configuration. Rather, we have to consider memory configurations separately for every different application.

Espressif Systems

1946

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
Dynamic vs. Static Buffer
The default type of buffer in Wi-Fi drivers isodynamicp. Most of the time the dynamic buffer can significantly save memory. However, it makes the application programming a little more difficult, because in this case the application needs to consider memory usage in Wi-Fi. lwIP also allocates buffers at the TCP/IP layer, and this buffer allocation is also dynamic. See lwIP documentation section about memory use and performance.
Peak Wi-Fi Dynamic Buffer
The Wi-Fi driver supports several types of buffer (refer to Wi-Fi Buffer Configure). However, this section is about the usage of the dynamic Wi-Fi buffer only. The peak heap memory that Wi-Fi consumes is the theoretically-maximum memory that the Wi-Fi driver consumes. Generally, the peak memory depends on:
· the number of dynamic rx buffers that are configured: wifi_rx_dynamic_buf_num · the number of dynamic tx buffers that are configured: wifi_tx_dynamic_buf_num · the maximum packet size that the Wi-Fi driver can receive: wifi_rx_pkt_size_max · the maximum packet size that the Wi-Fi driver can send: wifi_tx_pkt_size_max So, the peak memory that the Wi-Fi driver consumes can be calculated with the following formula:
wifi_dynamic_peek_memory = (wifi_rx_dynamic_buf_num * wifi_rx_pkt_size_max) + (wifi_tx_dynamic_buf_num * wifi_tx_pkt_size_max) Generally, we do not need to care about the dynamic tx long buffers and dynamic tx long long buffers, because they are management frames which only have a small impact on the system.
4.37.31 How to improve Wi-Fi performance
The performance of ESP32-S3 Wi-Fi is affected by many parameters, and there are mutual constraints between each parameter. A proper configuration can not only improve performance but also increase available memory for applications and improve stability. In this section, we will briefly explain the operating mode of the Wi-Fi/LWIP protocol stack and explain the role of each parameter. We will give several recommended configuration ranks, user can choose the appropriate rank according to the usage scenario.
Protocol stack operation mode

Espressif Systems

Fig. 61: ESP32-S3 datapath

1947

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
The ESP32-S3 protocol stack is divided into four layers: Application, LWIP, Wi-Fi, and Hardware.
· During receiving, hardware puts the received packet into DMA buffer, and then transfers it into the RX buffer of Wi-Fi, LWIP in turn for related protocol processing, and finally to the application layer. The Wi-Fi RX buffer and the LWIP RX buffer shares the same buffer by default. In other words, the Wi-Fi forwards the packet to LWIP by reference by default.
· During sending, the application copies the messages to be sent into the TX buffer of the LWIP layer for TCP/IP encapsulation. The messages will then be passed to the TX buffer of the Wi-Fi layer for MAC encapsulation and wait to be sent.
Parameters
Increasing the size or number of the buffers mentioned above properly can improve Wi-Fi performance. Meanwhile, it will reduce available memory to the application. The following is an introduction to the parameters that users need to configure:
RX direction:
· CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM This parameter indicates the number of DMA buffer at the hardware layer. Increasing this parameter will increase the senderns one-time receiving throughput, thereby improving the Wi-Fi protocol stack ability to handle burst traffic.
· CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM This parameter indicates the number of RX buffer in the Wi-Fi layer. Increasing this parameter will improve the performance of packet reception. This parameter needs to match the RX buffer size of the LWIP layer.
· CONFIG_ESP32_WIFI_RX_BA_WIN This parameter indicates the size of the AMPDU BA Window at the receiving end. This parameter should be configured to the smaller value between twice of CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM and CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM.
· CONFIG_LWIP_TCP_WND_DEFAULT This parameter represents the RX buffer size of the LWIP layer for each TCP stream. Its value should be configured to the value of WIFI_DYNAMIC_RX_BUFFER_NUM (KB) to reach a high and stable performance. Meanwhile, in case of multiple streams, this value needs to be reduced proportionally.
TX direction:
· CONFIG_ESP32_WIFI_TX_BUFFER This parameter indicates the type of TX buffer, it is recommended to configure it as a dynamic buffer, which can make full use of memory.
· CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM This parameter indicates the number of TX buffer on the Wi-Fi layer. Increasing this parameter will improve the performance of packet sending. The parameter value needs to match the TX buffer size of the LWIP layer.
· CONFIG_LWIP_TCP_SND_BUF_DEFAULT This parameter represents the TX buffer size of the LWIP layer for each TCP stream. Its value should be configured to the value of WIFI_DYNAMIC_TX_BUFFER_NUM (KB) to reach a high and stable performance. In case of multiple streams, this value needs to be reduced proportionally.
Throughput optimization by placing code in IRAM:
CACHE:
· CONFIG_ESP32S3_INSTRUCTION_CACHE_SIZE Configure the size of the instruction Cache. · CONFIG_ESP32S3_INSTRUCTION_CACHE_LINE_SIZE Configure the size of the instruction Cache bus. · CONFIG_ESP32S3_ICACHE_ASSOCIATED_WAYS Configure the associated ways of the instruction Cache. · CONFIG_ESP32S3_DATA_CACHE_SIZE Configure the size of the Data Cache. · CONFIG_ESP32S3_DATA_CACHE_LINE_SIZE Configure the line size of the Data Cache. · CONFIG_ESP32S3_DCACHE_ASSOCIATED_WAYS Configure the associated ways of the Data Cache.
Note: The buffer size mentioned above is fixed as 1.6 KB.

Espressif Systems

1948

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

How to configure parameters

ESP32-S3ns memory is shared by protocol stack and applications.
Here, we have given several configuration ranks. In most cases, the user should select a suitable rank for parameter configuration according to the size of the memory occupied by the application.
The parameters not mentioned in the following table should be set to the default.

Rank

Iperf

Available memory (KB) 133.9

WIFI_STATIC_RX_BUFFER2_4NUM

WIFI_DYNAMIC_RX_BUFF6E4R_NUM

WIFI_DYNAMIC_TX_BUFF6E4R_NUM

WIFI_RX_BA_WIN

32

TCP_SND_BUF_DEFAULT 64

(KB)

TCP_WND_DEFAULT 64

(KB)

WIFI_IRAM_OPT

15

WIFI_RX_IRAM_OPT 16

LWIP_IRAM_OPTIMIZATIO1N3

INSTRUCTION_CACHE 32

INSTRUCTION_CACHE_LI3N2E

INSTRUCTION_CACHE_WA8 YS

TCP TX throughput 83.93

(Mbit/s)

TCP RX throughput 73.98

(Mbit/s)

UDP TX throughput 98.69

(Mbit/s)

UDP RX throughput 88.58

(Mbit/s)

Default 183.9 8 32 32 16 32
32
15 16 13 32 32 8 64.28
60.39
96.28
86.57

Minimum 273.6 3 6 6 6 6
6
15 16 0 16 32 4 23.17
18.11
48.78
59.45

Note: The test was performed with a single stream in a shielded box using an ASUS RT-N66U router. ESP32-S3n s CPU is dual core with 240 MHz, ESP32-S3ns flash is in QIO mode with 80 MHz.
Ranks: · Iperf rank ESP32-S3 extreme performance rank used to test extreme performance. · Default rank ESP32-S3ns default configuration rank, the available memory, and performance are in balance. · Minimum rank This is the minimum configuration rank of ESP32-S3. The protocol stack only uses the necessary memory for running. It is suitable for scenarios that have no requirement for performance and the application requires lots of space.
Using PSRAM
PSRAM is generally used when the application takes up a lot of memory. In this mode, the CONFIG_ESP32_WIFI_TX_BUFFER is forced to be static. CONFIG_ESP32_WIFI_STATIC_TX_BUFFER_NUM indicates the number of DMA buffers at the hardware layer, increase this parameter can improve performance. The following are the recommended ranks for using PSRAM: PSRAM with 4 lines:

Espressif Systems

1949

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Rank

Iperf

Default

Available memory 50.3

158.7

(KB)

WIFI_STATIC_RX_2B4UFFER_NUM 8

WIFI_DYNAMIC_R8X5_BUFFER_NU6M4

WIFI_STATIC_TX_B32UFFER_NUM 32

WIFI_RX_BA_WIN32

16

TCP_SND_BUF_DE8F5AULT

32

(KB)

TCP_WND_DEFAU8L5T

32

(KB)

WIFI_IRAM_OPT 15

15

WIFI_RX_IRAM_OP16T

16

LWIP_IRAM_OPTIM13IZATION 0

LWIP_UDP_RECVM16BOX_SIZE 16

INSTRUCTION_CA3C2HE

16

INSTRUCTION_CA3C2HE_LINE 16

INSTRUCTION_CA8CHE_WAYS 8

DATA_CACHE 64

16

DATA_CACHE_LIN3E2

32

DATA_CACHE_WA8YS

8

TCP TX through- 93.1

62.5

put (Mbit/s)

TCP RX through- 88.9

46.5

put (Mbit/s)

UDP TX through- 106.4

106.2

put (Mbit/s)

UDP RX through- 99.8

92.6

put (Mbit/s)

PSRAM with 8 lines:

Memory saving Minimum

198.2

228.9

6

4

32

32

6

4

12

Disable

32

32

32

32

15

0

0

0

0

0

16

16

16

16

16

16

8

8

16

16

32

32

8

8

41.3

42.7

46.2

37.9

60.7

50

94.3

53.3

Espressif Systems

1950

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Rank

Iperf

Default

Available memory 49.1

151.3

(KB)

WIFI_STATIC_RX_2B4UFFER_NUM 8

WIFI_DYNAMIC_R8X5_BUFFER_NU6M4

WIFI_STATIC_TX_B32UFFER_NUM 32

WIFI_RX_BA_WIN32

16

TCP_SND_BUF_DE8F5AULT

32

(KB)

TCP_WND_DEFAU8L5T

32

(KB)

WIFI_IRAM_OPT 15

15

WIFI_RX_IRAM_OP16T

16

LWIP_IRAM_OPTIM13IZATION 0

LWIP_UDP_RECVM16BOX_SIZE 16

INSTRUCTION_CA3C2HE

16

INSTRUCTION_CA3C2HE_LINE 16

INSTRUCTION_CA8CHE_WAYS 8

DATA_CACHE 64

16

DATA_CACHE_LIN3E2

32

DATA_CACHE_WA8YS

8

TCP TX through- 93.3

58.4

put (Mbit/s)

TCP RX through- 86.1

43.6

put (Mbit/s)

UDP TX through- 104.7

82.2

put (Mbit/s)

UDP RX through- 104.6

104.8

put (Mbit/s)

Memory saving Minimum

215.3

243.6

6

4

32

32

6

4

12

Disable

32

32

32

32

15

0

0

0

0

0

16

16

16

16

16

16

8

8

16

16

32

32

8

8

37.1

35.6

42.5

35

60.4

47.9

104

55.7

4.37.32 Wi-Fi Menuconfig
Wi-Fi Buffer Configure
If you are going to modify the default number or type of buffer, it would be helpful to also have an overview of how the buffer is allocated/freed in the data path. The following diagram shows this process in the TX direction:

Fig. 62: TX Buffer Allocation
Description: · The application allocates the data which needs to be sent out. · The application calls TCPIP-/Socket-related APIs to send the user data. These APIs will allocate a PBUF used in LwIP, and make a copy of the user data.

Espressif Systems

1951

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
· When LwIP calls a Wi-Fi API to send the PBUF, the Wi-Fi API will allocate a oDynamic Tx Bufferpor oStatic Tx Bufferp, make a copy of the LwIP PBUF, and finally send the data. The following diagram shows how buffer is allocated/freed in the RX direction:
Fig. 63: RX Buffer Allocation Description:
· The Wi-Fi hardware receives a packet over the air and puts the packet content to the oStatic Rx Bufferp, which is also called oRX DMA Bufferp.
· The Wi-Fi driver allocates a oDynamic Rx Bufferp, makes a copy of the oStatic Rx Bufferp, and returns the oStatic Rx Bufferpto hardware.
· The Wi-Fi driver delivers the packet to the upper-layer (LwIP), and allocates a PBUF for holding theoDynamic Rx Bufferp.
· The application receives data from LwIP. The diagram shows the configuration of the Wi-Fi internal buffer.

Espressif Systems

1952

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Buffer Type Static RX Buffer (Hardware RX Buffer)

Alloc Type Static

Dynamic RX Dynamic Buffer
Dynamic TX Dynamic Buffer
Static TX Static Buffer

Management Short Buffer Management Long Buffer Management Long Long Buffer

Dynamic Dynamic Dynamic

Default 10 * 1600 Bytes

32

32

16

*

1600Bytes

8

Configurable Description

Yes

This is a kind of DMA memory. It is

initialized in esp_wifi_init() and

freed in esp_wifi_deinit(). The

mStatic Rx Buffernforms the hardware re-

ceiving list. Upon receiving a frame over

the air, hardware writes the frame into

the buffer and raises an interrupt to the

CPU. Then, the Wi-Fi driver reads the

content from the buffer and returns the

buffer back to the list.

If the application want to reduce the

the memory statically allocated by Wi-Fi,

they can reduce this value from 10 to 6 to

save 6400 Bytes memory. Itns not recom-

mended to reduce the configuration to a

value less than 6 unless the AMPDU fea-

ture is disabled.

Yes

The buffer length is variable and it de-

pends on the received framesnlength.

When the Wi-Fi driver receives a frame

from themHardware Rx Buffern, themDy-

namic Rx Buffernneeds to be allocated

from the heap. The number of the Dy-

namic Rx Buffer, configured in the menu-

config, is used to limit the total un-freed

Dynamic Rx Buffer number.

Yes

This is a kind of DMA memory. It is

allocated to the heap. When the upper-

layer (LwIP) sends packets to the Wi-Fi

driver, it firstly allocates amDynamic TX

Buffernand makes a copy of the upper-

layer buffer.

The Dynamic and Static TX Buffers are

mutually exclusive.

Yes

This is a kind of DMA memory. It is

initialized in esp_wifi_init() and

freed in esp_wifi_deinit().

When the upper-layer (LwIP) sends

packets to the Wi-Fi driver, it firstly

allocates a mStatic TX Buffernand

makes a copy of the upper-layer buffer.

The Dynamic and Static TX Buffer are

mutually exclusive.

Since the TX buffer must be DMA buffer,

so when PSRAM is enabled, the TX

buffer must be static.

NO

Wi-Fi driverns internal buffer.

32

NO

Wi-Fi driverns internal buffer.

32

NO

Wi-Fi driverns internal buffer.

Espressif Systems

1953

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Wi-Fi NVS Flash
If the Wi-Fi NVS flash is enabled, all Wi-Fi configurations set via the Wi-Fi APIs will be stored into flash, and the Wi-Fi driver will start up with these configurations next time it powers on/reboots. However, the application can choose to disable the Wi-Fi NVS flash if it does not need to store the configurations into persistent memory, or has its own persistent storage, or simply due to debugging reasons, etc.
Wi-Fi AMPDU
ESP32-S3 supports both receiving and transmitting AMPDU, the AMPDU can greatly improve the Wi-Fi throughput. Generally, the AMPDU should be enabled. Disabling AMPDU is usually for debugging purposes.
4.37.33 Troubleshooting
Please refer to a separate document with Espressif Wireshark User Guide.
Espressif Wireshark User Guide
1. Overview
1.1 What is Wireshark? Wireshark (originally named oEtherealp) is a network packet analyzer that captures network packets and displays the packet data as detailed as possible. It uses WinPcap as its interface to directly capture network traffic going through a network interface controller (NIC). You could think of a network packet analyzer as a measuring device used to examine what is going on inside a network cable, just like a voltmeter is used by an electrician to examine what is going on inside an electric cable. In the past, such tools were either very expensive, proprietary, or both. However, with the advent of Wireshark, all that has changed. Wireshark is released under the terms of the GNU General Public License, which means you can use the software and the source code free of charge. It also allows you to modify and customize the source code. Wireshark is, perhaps, one of the best open source packet analyzers available today.
1.2 Some Intended Purposes Here are some examples of how Wireshark is typically used: · Network administrators use it to troubleshoot network problems. · Network security engineers use it to examine security problems. · Developers use it to debug protocol implementations. · People use it to learn more about network protocol internals.
Beside these examples, Wireshark can be used for many other purposes.
1.3 Features The main features of Wireshark are as follows: · Available for UNIX and Windows · Captures live packet data from a network interface · Displays packets along with detailed protocol information · Opens/saves the captured packet data · Imports/exports packets into a number of file formats, supported by other capture programs · Advanced packet filtering · Searches for packets based on multiple criteria · Colorizes packets according to display filters · Calculates statistics · land a lot more!

Espressif Systems

1954

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
1.4 Wireshark Can or Cannt Do
· Live capture from different network media. Wireshark can capture traffic from different network media, including wireless LAN.
· Import files from many other capture programs. Wireshark can import data from a large number of file formats, supported by other capture programs.
· Export files for many other capture programs. Wireshark can export data into a large number of file formats, supported by other capture programs.
· Numerous protocol dissectors. Wireshark can dissect, or decode, a large number of protocols.
· Wireshark is not an intrusion detection system. It will not warn you if there are any suspicious activities on your network. However, if strange things happen, Wireshark might help you figure out what is really going on.
· Wireshark does not manipulate processes on the network, it can only performomeasurementspwithin it. Wireshark does not send packets on the network or influence it in any other way, except for resolving names (converting numerical address values into a human readable format), but even that can be disabled.
2. Where to Get Wireshark You can get Wireshark from the official website: https://www.wireshark.org/ download.html
Wireshark can run on various operating systems. Please download the correct version according to the operating system you are using.
3. Step-by-step Guide This demonstration uses Wireshark 2.2.6 on Linux.
a) Start Wireshark
On Linux, you can run the shell script provided below. It starts Wireshark, then configures NIC and the channel for packet capture.
ifconfig $1 down iwconfig $1 mode monitor iwconfig $1 channel $2 ifconfig $1 up Wireshark&
In the above script, the parameter $1 represents NIC and $2 represents channel. For example, wlan0 in ./xxx.sh wlan0 6, specifies the NIC for packet capture, and 6 identifies the channel of an AP or Soft-AP.
b) Run the Shell Script to Open Wireshark and Display Capture Interface

Espressif Systems

Fig. 64: Wireshark Capture Interface

1955

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
c) Select the Interface to Start Packet Capture As the red markup shows in the picture above, many interfaces are available. The first one is a local NIC and the second one is a wireless NIC. Please select the NIC according to your requirements. This document will use the wireless NIC to demonstrate packet capture. Double click wlan0 to start packet capture. d) Set up Filters Since all packets in the channel will be captured, and many of them are not needed, you have to set up filters to get the packets that you need. Please find the picture below with the red markup, indicating where the filters should be set up.
Fig. 65: Setting up Filters in Wireshark Click Filter, the top left blue button in the picture below. The display filter dialogue box will appear.

Fig. 66: Display Filter Dialogue Box
Click the Expression button to bring up the Filter Expression dialogue box and set the filter according to your requirements. The quickest way: enter the filters directly in the toolbar. Click on this area to enter or modify the filters. If you enter a wrong or unfinished filter, the built-in syntax check turns the background red. As soon as the correct expression is entered, the background becomes green. The previously entered filters are automatically saved. You can access them anytime by opening the drop down list. For example, as shown in the picture below, enter two MAC addresses as the filters and click Apply (the blue arrow). In this case, only the packet data transmitted between these two MAC addresses will be captured.

Espressif Systems

1956

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Fig. 67: Filter Expression Dialogue Box

Fig. 68: Filter Toolbar

Fig. 69: Example of MAC Addresses applied in the Filter Toolbar

Espressif Systems

1957

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
e) Packet List You can click any packet in the packet list and check the detailed information about it in the box below the list. For example, if you click the first packet, its details will appear in that box.

Fig. 70: Example of Packet List Details
f) Stop/Start Packet Capture As shown in the picture below, click the red button to stop capturing the current packet.

Fig. 71: Stopping Packet Capture
Click the top left blue button to start or resume packet capture. g) Save the Current Packet On Linux, go to File -> Export Packet Dissections -> As Plain Text File to save the packet. Please note that All packets, Displayed and All expanded must be selected. By default, Wireshark saves the captured packet in a libpcap file. You can also save the file in other formats, e.g. txt, to analyze it in other tools.
4.38 Wi-Fi Security

Espressif Systems

1958

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides Fig. 72: Starting or Resuming the Packets Capture

Fig. 73: Saving Captured Packets

Espressif Systems

1959

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides
4.38.1 ESP32-S3 Wi-Fi Security Features
· Support for Protected Management Frames (PMF) · Support for WPA3-Personal
In addition to traditional security methods (WEP/WPA-TKIP/WPA2-CCMP), ESP32-S3 Wi-Fi supports state-ofthe-art security protocols, namely Protected Management Frames based on 802.11w standard and Wi-Fi Protected Access 3 (WPA3-Personal). Together, PMF and WPA3 provide better privacy and robustness against known attacks on traditional modes.
4.38.2 Protected Management Frames (PMF)
Introduction
In Wi-Fi, management frames such as beacons, probes, (de)authentication, (dis)association are used by non-AP stations to scan and connect to an AP. Unlike data frames, these frames are sent unencrypted. An attacker can use eavesdropping and packet injection to send spoofed (de)authentication/(dis)association frames at the right time, leading to the following attacks in case of unprotected management frame exchanges.
· DOS attack on one or all clients in the range of the attacker. · Tearing down existing association on AP side by sending association request. · Forcing a client to perform 4-way handshake again in case PSK is compromised in order to get PTK. · Getting SSID of hidden network from association request. · Launching man-in-the-middle attack by forcing clients to deauth from legitimate AP and associating to a rogue
one.
PMF provides protection against these attacks by encrypting unicast management frames and providing integrity checks for broadcast management frames. These include deauthentication, disassociation and robust management frames. It also provides Secure Association (SA) teardown mechanism to prevent spoofed association/authentication frames from disconnecting already connected clients.
API & Usage
esp_wifi_set_config() can be used to configure PMF mode by setting appropriate flags in pmf_cfg parameter. Currently, PMF is supported only in Station mode. While setting up a Station, configure PMF using two flags capable and required like below.
wifi_config_t wifi_config = { .sta = { .ssid = EXAMPLE_WIFI_SSID, .password = EXAMPLE_WIFI_PASSWORD, .pmf_cfg = { .capable = true, .required = false } }
};
ESP32-S3 supports three modes of PMF by combination of these two flags · PMF Optional : .capable = true, .required = false · PMF Required : .capable = true, .required = true · PMF Disabled : .capable = false, .required = false
Depending on what AP side PMF Mode is, the resulting connnection will behave differently. The table below summarises all possible outcomes -

Espressif Systems

1960

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

STA Setting PMF Optional PMF Optional PMF Required PMF Required PMF Disabled PMF Disabled

AP Setting PMF Optional/Required PMF Disabled PMF Optional/Required PMF Disabled PMF Optional/Disabled PMF Required

Outcome Mgmt Frames Protected Mgmt Frames Not Protected Mgmt Frames Protected STA refuses Connection Mgmt Frames Not Protected AP refuses Connection

PMF Optional Mode, which is shown in the example of wifi_confit_t, is suggested to be used in all Station configurations. This is to take the additional security benefit of PMF whenever possible without breaking connections with legacy APns.

4.38.3 WPA3-Personal
Introduction
Wi-Fi Protected Access-3 (WPA3) is a set of enhancements to Wi-Fi access security intended to replace the current WPA2 standard. It includes new features and capabilities that offer significantly better protection against different types of attacks. It improves upon WPA2-Personal in following ways:
· WPA3 uses Simultaneous Authentication of Equals (SAE), which is password-authenticated key agreement method based on Diffie-Hellman key exchange. Unlike WPA2, the technology is resistant to offline-dictionary attack, where the attacker attempts to determine shared password based on captured 4-way handshake without any further network interaction.
· Disallows outdated protocols such as TKIP, which is susceptible to simple attacks like MIC key recovery attack. · Mandates Protected Management Frames (PMF), which provides protection for unicast and multicast robust
management frames which include Disassoc and Deauth frames. This means that the attacker cannot disrupt an established WPA3 session by sending forged Assoc frames to the AP or Deauth/Disassoc frames to the Station. · Provides forward secrecy, which means the captured data cannot be decrypted even if password is compromised after data transmission.
Please refer to Security section of Wi-Fi Alliancens official website for further details.

Setting up WPA3 with ESP32-S3
In IDF Menuconfig under Wi-Fi component, a config optionoEnable WPA3-Personalpis provided to Enable/Disable WPA3. By default it is kept enabled, if disabled ESP32-S3 will not be able to establish a WPA3 connection. Currently, WPA3 is supported only in the Station mode. Additionally, since PMF is mandated by WPA3 protocol, PMF Mode should be set to either Optional or Required while setting WiFi config.
Refer to Protected Management Frames (PMF) on how to set this mode.
After these settings are done, Station is ready to use WPA3-Personal. Application developers need not worry about the underlying security mode of the AP. WPA3-Personal is now the highest supported protocol in terms of security, so it will be automatically selected for the connection whenever available. For example, if an AP is configured to be in WPA3 Transition Mode, where it will advertise as both WPA2 and WPA3 capable, Station will choose WPA3 for the connection with above settings. Note that Wi-Fi stack size requirement will increase 3kB when WPA3 is used.

Espressif Systems

1961

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 4. API Guides

Espressif Systems

1962

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 5
ESP-IDF 5.0 Migration Guides
5.1 Migrate Build System to ESP-IDF 5.0
5.1.1 Migrating from make to cmake
Please follow the build system guide for migrating make-based projects no longer supported in ESP-IDF v5.0.
5.1.2 Update fragment file grammar
Please follow the migrate linker script fragment files grammar chapter for migrating v3.x grammar to the new one.
5.2 Migrate Windows Environment to ESP-IDF 5.0
The Msys/Mingw-based Windows environment support got deprecated in ESP-IDF v4.0 and was entirely removed in v5.0. Please use ESP-IDF Tools Installer to set up a compatible environment. The options include Windows Command Line, Power Shell and the graphical user interface based on Eclipse IDE. In addition, a VS Code-based environment can be set up with the supported plugin: https://github.com/espressif/vscode-esp-idf-extension.
5.3 Migrate Ethernet Drivers to ESP-IDF 5.0
5.3.1 esp_eth_ioctl() API
esp_eth_ioctl() third argument could take int (bool) number as an input in some cases. However, it was not properly documented and, in addition, the number had to beounnaturallyptype casted to void * datatype to prevent compiler warnings as shown in below example: esp_eth_ioctl(eth_handle, ETH_CMD_S_FLOW_CTRL, (void *)true); This could lead to misuse of the esp_eth_ioctl(). Therefore, ESP-IDF 5.0 unified usage of esp_eth_ioctl(). Its third argument now always acts as pointer to a memory location of specific type from/to where the configuration option is read/stored. Usage example to set Ethernet configuration: eth_duplex_t new_duplex_mode = ETH_DUPLEX_HALF; esp_eth_ioctl(eth_handle, ETH_CMD_S_DUPLEX_MODE, &new_duplex_mode); Usage example to get Ethernet configuration:
1963

Chapter 5. ESP-IDF 5.0 Migration Guides
eth_duplex_t duplex_mode; esp_eth_ioctl(eth_handle, ETH_CMD_G_DUPLEX_MODE, &duplex_mode);
5.3.2 KSZ8041/81 and LAN8720 Driver Update
KSZ8041/81 and LAN8720 Drivers were updated to support more devices (generations) from associated product family. The drivers are able to recognize particular chip number and its potential support by the driver. As a result, the specific ochip numberpfunctions calls were replaced by generic ones as follows:
· esp_eth_phy_new_ksz8041() and esp_eth_phy_new_ksz8081() were removed, use esp_eth_phy_new_ksz80xx() instead
· esp_eth_phy_new_lan8720() was removed, use esp_eth_phy_new_lan87xx() instead
5.3.3 ESP NETIF Glue Event Handlers
esp_eth_set_default_handlers() and esp_eth_clear_default_handlers() functions were removed. Registration of the default IP layer handlers for Ethernet is now handled automatically. If users have already followed the recommendation to fully initialize the Ethernet driver and network interface prior to registering their Ethernet/IP event handlers, then no action is required (except for deleting the affected functions). Otherwise, users should ensure that they register the user event handlers as the last thing prior to starting the Ethernet driver.
5.4 Migrate FreeRTOS to ESP-IDF 5.0
5.4.1 Tasks Snapshot
The header task_snapshot.h has been removed from freertos/task.h. ESP-IDF developers should include "freertos/task_snapshot.h` in case they need tasks snapshot API.
5.4.2 FreeRTOS Asserts
Previously FreeRTOS asserts were configured separately from the rest of the system using the FREERTOS_ASSERT kconfig option. This option has now been removed and the configuration is now done through COMPILER_OPTIMIZATION_ASSERTION_LEVEL.
5.5 Migrate Peripherals to ESP-IDF 5.0
5.5.1 Peripheral Clock Gating
As usual, peripheral clock gating is still handled by driver itself, users donnt need to take care of the peripheral module clock gating. However, for advanced users who implement their own drivers based on hal and soc components, the previous clock gating include path has been changed from driver/periph_ctrl.h to esp_private/periph_ctrl.h.
5.5.2 SPI Flash Interface
Version before v5.0, spi flash functions in rom can be included by esp32**/rom/spi_flash.h. However, your code written for different chips may be filled with ROM headers of different versions. At the meantime not all the APIs can be used on all chips.

Espressif Systems

1964

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 5. ESP-IDF 5.0 Migration Guides

Therefore, the common APIs are extracted to esp_rom_spiflash.h. Although itns not a breaking change, it is strongly recommended to only use the functions with prefix esp_rom_spiflash included by esp_rom_spiflash.h for better cross-compatibility.

To make the API clearer, we renamed the function esp_rom_spiflash_lock to

esp_rom_spiflash_set_bp.

We renamed esp_rom_spiflash_unlock to

esp_rom_spiflash_clear_bp.

5.5.3 ADC
Previous driver/adc2_wifi_private.h has been moved to esp_private/adc2_wifi.h.

5.5.4 GPIO
The previous Kconfig option RTCIO_SUPPORT_RTC_GPIO_DESC has been removed, thus the rtc_gpio_desc array is unavailable. Please use rtc_io_desc array instead.

5.5.5 Timer Group Driver
Timer Group driver has been redesigned into GPTimer, which aims to unify and simplify the usage of general purpose timer. Although itns recommended to use the the new driver APIs, the legacy driver is till available in the previous include path driver/timer.h. However, by default, including driver/timer.h will bring a build warning like olegacy timer group driver is deprecated, please migrate to driver/gptimer.hp. The warning can be suppressed by the Kconfig option CONFIG_GPTIMER_SUPPRESS_DEPRECATE_WARN.
The major breaking changes in concept and usage are listed as follows:

Breaking Changes in Concepts
· timer_group_t and timer_idx_t which used to identify the hardware timer are removed from usern s code. In the new driver, a timer is represented by gptimer_handle_t.
· Definition of timer source clock is moved to gptimer_clock_source_t, the previous timer_src_clk_t is not used.
· Definition of timer count direction is moved to gptimer_count_direction_t, the previous timer_count_dir_t is not used.
· Only level interrupt is supported, timer_intr_t and timer_intr_mode_t are not used. · Auto-reload is enabled by set the auto_reload_on_alarm flag. timer_autoreload_t is not used.

Breaking Changes in Usage
· Timer initialization is done by creating a timer instance from gptimer_new_timer(). Basic configurations like clock source, resolution and direction should be set in gptimer_config_t. Note that, alarm event specific configurations are not needed during the driver install stage.
· Alarm event is configured by gptimer_set_alarm_action(), with parameters set in the gptimer_alarm_config_t.
· Setting and getting count value are done by gptimer_get_raw_count() and gptimer_set_raw_count(). The driver doesnnt help convert the raw value into UTC time-stamp. Instead, the conversion should be done form userns side as the timer resolution is also known to the user.
· The driver will install the interrupt service as well if on_alarm is set to a valid callback function. In the callback, user doesnnt have to deal with the low level registers (like oclear interrupt statusp, oreenable alarm eventpand so on). So functions like timer_group_get_intr_status_in_isr and timer_group_get_auto_reload_in_isr are not used anymore.
· To update the alarm configurations when alarm event happens, one can call gptimer_set_alarm_action() in the interrupt callback, then the alarm will be re-enabled again.
· Alarm will always be re-enabled by the driver if auto_reload_on_alarm is set to true.

Espressif Systems

1965

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 5. ESP-IDF 5.0 Migration Guides
UART
· uart_isr_register and uart_isr_free have been removed as the UART interrupt handling is closely related to the driver implementation.
I2C
· i2c_isr_register and i2c_isr_free have been removed as the I2C interrupt handling is closely related to the driver implementation.
5.6 Removed or deprecated components
Following components are removed from ESP-IDF and moved to IDF Component Registry: · libsodium · cbor · jsmn · esp_modem · nghttp
Note: Please note that http parser functionality which was previously part of nghttp component is now part of http_parser component.
· sh2lib · expat These components can be installed using idf.py add-dependency command. For example, to install libsodium component with exact version X.Y, run: idf.py add-dependency libsodium==X.Y. To install libsodium component with the latest version compatible to X.Y according to semver rules, run: idf.py add-dependency libsodium~X.Y. To find out which versions of each component are available, open https://components.espressif.com, search for the component by its name and check the versions listed on the component page.
5.7 Migrate System to ESP-IDF 5.0
5.7.1 Inter-Processor Call
IPC (Inter-Processor Call) component has been moved to esp_system. Thus, any project presenting a CMakeLists.txt file with the parameters PRIV_REQUIRES esp_ipc or REQUIRES esp_ipc, should be modified to simply remove these options as esp_system component is included by default.
5.7.2 ESP Clock
The old headers ESP32-S3/clk.h, esp_clk.h have been removed. Therefore, If you want to use the function with the prefix esp_clk please include esp_private/esp_clk.h instead.

Espressif Systems

1966

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 5. ESP-IDF 5.0 Migration Guides

5.7.3 Cache Error Interrupt
The old headers ESP32-S3/cache_err_int.h have been removed. Please include esp_private/ cache_err_int.h instead.
5.7.4 Brownout
The header brownout.h has been made private. ESP-IDF developers should include esp_private/ brownout.h instead.
5.7.5 Trax
The header trax.h has been made private. ESP-IDF developers should include esp_private/trax.h instead.
5.7.6 ROM
Deprecated ROM related header files from components/esp32/rom/ (old include path: rom/*.h) have been deleted. Please update to use the new target-specific path from components/esp_rom/include/ESP32-S3/ (new include path: ESP32-S3/rom/*.h).
5.7.7 ESP HW Support
· The header files soc/cpu.h have been deleted and deprecated CPU util functions have been removed. ESPIDF developers should include esp_cpu.h instead for equivalent functions.
· The header file esp_intr.h has been deleted. Please include esp_intr_alloc.h to allocate and manipulate interrupts.
· The header file esp_panic.h has been deleted. ESP-IDF developers should include esp_private/ panic_reason.h to get supported panic reasons. And should include esp_debug_helpers.h to use any debug related helper functions, e.g. print backtrace.
5.7.8 SOC dependency
· Public API headers who are listed in the Doxyfiles wonnt expose unstable and unnecessary soc header files like soc/soc.h, soc/rtc.h. That means, the user has to explicitly include them in their code if these
omissingpheader files are still wanted. · Kconfig option LEGACY_INCLUDE_COMMON_HEADERS is also removed.
5.7.9 APP Trace
One of the timestamp sources has changed from the legacy timer group driver to the new GPTimer. Kconfig choices like APPTRACE_SV_TS_SOURCE_TIMER00 has been changed to APPTRACE_SV_TS_SOURCE_GPTIMER. User doesnnt need to choose the group and timer ID any more.

5.8 Migrate Tools to ESP-IDF 5.0

5.8.1 IDF Monitor
IDF Monitor follows the custom console baud-rate (CONFIG_ESP_CONSOLE_UART_BAUDRATE) by default instead of 115200. Setting a custom baud rate is not supported from menuconfig anymore. A custom baud-rate can be specified from command line with the idf.py monitor -B <baud> command or through setting environment variables. Run idf.py monitor --help for more information.

Espressif Systems

1967

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 5. ESP-IDF 5.0 Migration Guides

Espressif Systems

1968

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 6
Libraries and Frameworks
6.1 Cloud Frameworks
ESP32-S3 supports multiple cloud frameworks using agents built on top of ESP-IDF. Here are the pointers to various supported cloud frameworksnagents and examples:
6.1.1 ESP RainMaker
ESP RainMaker is a complete solution for accelerated AIoT development. ESP RainMaker on GitHub.
6.1.2 AWS IoT
https://github.com/espressif/esp-aws-iot is an open source repository for ESP32-S3 based on Amazon Web Servicesn aws-iot-device-sdk-embedded-C.
6.1.3 Azure IoT
https://github.com/espressif/esp-azure is an open source repository for ESP32-S3 based on Microsoft Azurens azure-iot-sdk-c SDK.
6.1.4 Google IoT Core
https://github.com/espressif/esp-google-iot is an open source repository for ESP32-S3 based on Googlens iot-devicesdk-embedded-c SDK.
6.1.5 Aliyun IoT
https://github.com/espressif/esp-aliyun is an open source repository for ESP32-S3 based on Aliyunns iotkitembedded SDK.
6.1.6 Joylink IoT
https://github.com/espressif/esp-joylink is an open source repository for ESP32-S3 based on Joylinkns joylink_dev_sdk SDK.
1969

Chapter 6. Libraries and Frameworks
6.1.7 Tencent IoT
https://github.com/espressif/esp-welink is an open source repository for ESP32-S3 based on Tencentns welink SDK.
6.1.8 Tencentyun IoT
https://github.com/espressif/esp-qcloud is an open source repository for ESP32-S3 based on Tencentyunns qcloudiot-sdk-embedded-c SDK.
6.1.9 Baidu IoT
https://github.com/espressif/esp-baidu-iot is an open source repository for ESP32-S3 based on Baiduns iot-sdk-c SDK.
6.2 Espressifns Frameworks
Here you will find a collection of the official Espressif libraries and frameworks.
6.2.1 Espressif Audio Development Framework
The ESP-ADF is a comprehensive framework for audio applications including: · CODECns HAL · Music Players and Recorders · Audio Processing · Bluetooth Speakers · Internet Radios · Hands-free devices · Speech Recognition
This framework is available at GitHub: ESP-ADF.
6.2.2 ESP-CSI
ESP-CSI is an experimental implementation that uses the Wi-Fi Channel State Information to detect the presence of a human body. See ESP-CSI project for more information about it.
6.2.3 Espressif DSP Library
The library provides algorithms optimized specifically for digital signal processing applications. This library supports: · Matrix multiplication · Dot product · FFT (Fast Fourier Transform) · IIR (Infinite Impulse Response) · FIR (Finite Impulse Response) · Vector math operations
This library is available here: ESP-DSP library.

Espressif Systems

1970

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 6. Libraries and Frameworks
6.2.4 ESP-WIFI-MESH Development Framework
This framework is based on the ESP-WIFI-MESH protocol with the following features: · Fast network configuration · Stable upgrade · Efficient debugging · LAN control · Various application demos
ESP-MDF.
6.2.5 ESP-WHO
The ESP-WHO is a face detection and recognition framework using the ESP32 and camera. To know more about the project, see ESP-WHO on GitHub.
6.2.6 ESP RainMaker
ESP RainMaker is a complete solution for accelerated AIoT development. Using ESP RainMaker, you can create AIoT devices from the firmware to the integration with voice-assistant, phone apps and cloud backend. ESP RainMaker on GitHub.
6.2.7 ESP-IoT-Solution
ESP-IoT-Solution contains commonly used device drivers and code frameworks when developing IoT systems. The device drivers and code frameworks within the ESP-IoT-Solution are organized as separate components, allowing them to be easily integrated into an ESP-IDF project. ESP-IoT-Solution includes:
· Device drivers for sensors, display, audio, GUI, input, actuators, etc. · Framework and documentation for low power, security, storage, etc. · Guide for Espressif open source solutions from practical application point. ESP-IoT-Solution on GitHub.
6.2.8 ESP-Protocols
ESP-Protocols repository contains collection of protocol components for ESP-IDF. The code within the ESPProtocols is organized into separate components, allowing them to be easily integrated into an ESP-IDF project. In addition to that, each component is available in IDF Component Registry. ESP-Protocols components:
· esp_modem enables connectivity with GSM/LTE modems using AT commands or PPP protocol, see the esp_modem documentation.

Espressif Systems

1971

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 6. Libraries and Frameworks

Espressif Systems

1972

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 7
Contributions Guide
We welcome contributions to the esp-idf project!
7.1 How to Contribute
Contributions to esp-idf - fixing bugs, adding features, adding documentation - are welcome. We accept contributions via Github Pull Requests.
7.2 Before Contributing
Before sending us a Pull Request, please consider this list of points: · Is the contribution entirely your own work, or already licensed under an Apache License 2.0 compatible Open Source License? If not then we unfortunately cannot accept it. Please check the Copyright Header Guide for additional information. · Does any new code conform to the esp-idf Style Guide? · Have you installed the pre-commit hook for esp-idf project? · Does the code documentation follow requirements in Documenting Code? · Is the code adequately commented for people to understand how it is structured? · Is there documentation or examples that go with code contributions? There are additional suggestions for writing good examples in examples readme. · Are comments and documentation written in clear English, with no spelling or grammar errors? · Example contributions are also welcome. Please check the Creating Examples guide for these. · If the contribution contains multiple commits, are they grouped together into logical changes (one major change per pull request)? Are any commits with names like ofixed typopsquashed into previous commits? · If younre unsure about any of these points, please open the Pull Request anyhow and then ask us for feedback.
7.3 Pull Request Process
After you open the Pull Request, there will probably be some discussion in the comments field of the request itself. Once the Pull Request is ready to merge, it will first be merged into our internal git system for in-house automated testing. If this process passes, it will be merged onto the public github repository.
1973

Chapter 7. Contributions Guide

7.4 Legal Part
Before a contribution can be accepted, you will need to sign our Contributor Agreement. You will be prompted for this automatically as part of the Pull Request process.

7.5 Related Documents
7.5.1 Espressif IoT Development Framework Style Guide
About This Guide
Purpose of this style guide is to encourage use of common coding practices within the ESP-IDF. Style guide is a set of rules which are aimed to help create readable, maintainable, and robust code. By writing code which looks the same way across the code base we help others read and comprehend the code. By using same conventions for spaces and newlines we reduce chances that future changes will produce huge unreadable diffs. By following common patterns for module structure and by using language features consistently we help others understand code behavior. We try to keep rules simple enough, which means that they can not cover all potential cases. In some cases one has to bend these simple rules to achieve readability, maintainability, or robustness. When doing modifications to third-party code used in ESP-IDF, follow the way that particular project is written. That will help propose useful changes for merging into upstream project.

C Code Formatting
Naming
· Any variable or function which is only used in a single source file should be declared static. · Public names (non-static variables and functions) should be namespaced with a per-component or per-unit
prefix, to avoid naming collisions. ie esp_vfs_register() or esp_console_run(). Starting the prefix with esp_ for Espressif-specific names is optional, but should be consistent with any other names in the same component. · Static variables should be prefixed with s_ for easy identification. For example, static bool s_invert. · Avoid unnecessary abbreviations (ie shortening data to dat), unless the resulting name would otherwise be very long.

Indentation Use 4 spaces for each indentation level. Donnt use tabs for indentation. Configure the editor to emit 4 spaces each time you press tab key.

Vertical Space Place one empty line between functions. Donnt begin or end a function with an empty line.
void function1() {
do_one_thing(); do_another_thing();
// INCORRECT, don't place empty line here }
// place empty line here void function2() {
// INCORRECT, don't use an empty line here int var = 0; while (var < SOME_CONSTANT) {
do_stuff(&var);
(continues on next page)

Espressif Systems

1974

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 7. Contributions Guide

} }

(continued from previous page)

The maximum line length is 120 characters as long as it doesnnt seriously affect the readability.

Horizontal Space Always add single space after conditional and loop keywords:

if (condition) { // ...
}

// correct

switch (n) { case 0: // ...
}

// correct

for(int i = 0; i < CONST; ++i) { // ...
}

// INCORRECT

Add single space around binary operators. No space is necessary for unary operators. It is okay to drop space around multiply and divide operators:
const int y = y0 + (x - x0) * (y1 - y0) / (x1 - x0); // correct

const int y = y0 + (x - x0)*(y1 - y0)/(x1 - x0);

// also okay

int y_cur = -y; ++y_cur;

// correct

const int y = y0+(x-x0)*(y1-y0)/(x1-x0);

// INCORRECT

No space is necessary around . and -> operators.
Sometimes adding horizontal space within a line can help make code more readable. For example, you can add space to align function arguments:
esp_rom_gpio_connect_in_signal(PIN_CAM_D6, I2S0I_DATA_IN14_IDX, false); esp_rom_gpio_connect_in_signal(PIN_CAM_D7, I2S0I_DATA_IN15_IDX, false); esp_rom_gpio_connect_in_signal(PIN_CAM_HREF, I2S0I_H_ENABLE_IDX, false); esp_rom_gpio_connect_in_signal(PIN_CAM_PCLK, I2S0I_DATA_IN15_IDX, false);

Note however that if someone goes to add new line with a longer identifier as first argument (e.g. PIN_CAM_VSYNC), it will not fit. So other lines would have to be realigned, adding meaningless changes to the commit. Therefore, use horizontal alignment sparingly, especially if you expect new lines to be added to the list later. Never use TAB characters for horizontal alignment. Never add trailing whitespace at the end of the line.

Braces · Function definition should have a brace on a separate line:
// This is correct: void function(int arg) {
}

(continues on next page)

Espressif Systems

1975

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 7. Contributions Guide

// NOT like this: void function(int arg) {

(continued from previous page)

} · Within a function, place opening brace on the same line with conditional and loop statements:

if (condition) { do_one();
} else if (other_condition) { do_two();
}

Comments Use // for single line comments. For multi-line comments it is okay to use either // on each line or a /* */ block.
Although not directly related to formatting, here are a few notes about using comments effectively.
· Donnt use single comments to disable some functionality:

void init_something() {
setup_dma(); // load_resources(); the reader? start_timer(); }

// WHY is this thing commented, asks

· If some code is no longer required, remove it completely. If you need it you can always look it up in git history of this file. If you disable some call because of temporary reasons, with an intention to restore it in the future, add explanation on the adjacent line:

void init_something() {
setup_dma(); // TODO: we should load resources here, but loader is not fully integrated yet. // load_resources(); start_timer(); }
· Same goes for #if 0 ... #endif blocks. Remove code block completely if it is not used. Otherwise, add comment explaining why the block is disabled. Donnt use #if 0 ... #endif or comments to store code snippets which you may need in the future.
· Donnt add trivial comments about authorship and change date. You can always look up who modified any given line using git. E.g. this comment adds clutter to the code without adding any useful information:

void init_something() {
setup_dma(); // XXX add 2016-09-01 init_dma_list(); fill_dma_item(0); // end XXX add start_timer(); }

Line Endings Commits should only contain files with LF (Unix style) endings.
Windows users can configure git to check out CRLF (Windows style) endings locally and commit LF endings by setting the core.autocrlf setting. Github has a document about setting this option <github-line-endings>.

Espressif Systems

1976

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 7. Contributions Guide
If you accidentally have some commits in your branch that add LF endings, you can convert them to Unix by running this command in an MSYS2 or Unix terminal (change directory to the IDF working directory and check the correct branch is currently checked out, beforehand):
git rebase --exec 'git diff-tree --no-commit-id --name-only -r HEAD | xargs dos2unix && git commit -a --amend --no-edit --allow-empty' master
(Note that this line rebases on master, change the branch name at the end to rebase on another branch.) For updating a single commit, itns possible to run dos2unix FILENAME and then run git commit --amend
Formatting Your Code You can use astyle program to format your code according to the above recommendations. If you are writing a file from scratch, or doing a complete rewrite, feel free to re-format the entire file. If you are changing a small portion of file, donnt re-format the code you didnnt change. This will help others when they review your changes. To re-format a file, run:
tools/format.sh components/my_component/file.c
Type Definitions Should be snake_case, ending with _t suffix:
typedef int signed_32_bit_t;
Enum Enums should be defined through the typedef and be namespaced:
typedef enum {
MODULE_FOO_ONE, MODULE_FOO_TWO, MODULE_FOO_THREE } module_foo_t;
Assertions The standard C assert() function, defined in assert.h should be used to check conditions that should be true in source code. In the default configuration, an assert condition that returns false or 0 will call abort() and trigger a Fatal Error. assert() should only be used to detect unrecoverable errors due to a serious internal logic bug or corruption, where itns not possible for the program to continue. For recoverable errors, including errors that are possible due to invalid external input, an error value should be returned.
Note: When asserting a value of type esp_err_t``is equal to ``ESP_OK, use the ESP_ERROR_CHECK macro instead of an assert().
Itns possible to configure ESP-IDF projects with assertions disabled (see CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL). Therefore, functions called in an assert() statement should not have side-effects. Itns also necessary to use particular techniques to avoid ovariable set but not usedpwarnings when assertions are disabled, due to code patterns such as:
int res = do_something(); assert(res == 0);

Espressif Systems

1977

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 7. Contributions Guide

Once the assert is optimized out, the res value is unused and the compiler will warn about this. However the function do_something() must still be called, even if assertions are disabled.
When the variable is declared and initialized in a single statement, a good strategy is to cast it to void on a new line. The compiler will not produce a warning, and the variable can still be optimized out of the final binary:
int res = do_something(); assert(res == 0); (void)res;
If the variable is declared separately, for example if it is used for multiple assertions, then it can be declared with the GCC attribute __attribute__((unused)). The compiler will not produce any unused variable warnings, but the variable can still be optimized out:
int res __attribute__((unused));
res = do_something(); assert(res == 0);
res = do_something_else(); assert(res != 0);

Header file guards
All public facing header files should have preprocessor guards. A pragma is preferred:
#pragma once
over the following pattern:
#ifndef FILE_NAME_H #define FILE_NAME_H ... #endif // FILE_NAME_H
In addition to guard macros, all C header files should have extern "C" guards to allow the header to be used from C++ code. Note that the following order should be used: pragma once, then any #include statements, then extern "C" guards:
#pragma once
#include <stdint.h>
#ifdef __cplusplus extern "C" { #endif
/* declarations go here */
#ifdef __cplusplus } #endif

Include statements
When writing #include statements, try to maintain the following order: · C standard library headers. · Other POSIX standard headers and common extensions to them (such as sys/queue.h.) · Common IDF headers (esp_log.h, esp_system.h, esp_timer.h, esp_sleep.h, etc.)

Espressif Systems

1978

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 7. Contributions Guide

· Headers of other components, such as FreeRTOS. · Public headers of the current component. · Private headers. Use angle brackets for C standard library headers and other POSIX headers (#include <stdio.h>). Use double quotes for all other headers (#include "esp_log.h").
C++ Code Formatting
The same rules as for C apply. Where they are not enough, apply the following rules.
File Naming C++ Header files have the extension .hpp. C++ source files have the extension .cpp. The latter is important for the compiler to distinguish them from normal C source files.
Naming · Class and struct names shall be written in CamelCase with a capital letter as beginning. Member variables and methods shall be in snake_case. · Namespaces shall be in lower snake_case. · Templates are specified in the line above the function declaration. · Interfaces in terms of Object-Oriented Programming shall be named without the suffix ...Interface. Later, this makes it easier to extract interfaces from normal classes and vice versa without making a breaking change.
Member Order in Classes In order of precedence: · First put the public members, then the protected, then private ones. Omit public, protected or private sections without any members. · First put constructors/destructors, then member functions, then member variables.
For example:
class ForExample { public:
// first constructors, then default constructor, then destructor ForExample(double example_factor_arg); ForExample(); ~ForExample();
// then remaining pubic methods set_example_factor(double example_factor_arg);
// then public member variables uint32_t public_data_member;
private: // first private methods void internal_method();
// then private member variables double example_factor; };

Spacing
· Donnt indent inside namespaces. · Put public, protected and private labels at the same indentation level as the corresponding class
label.

Espressif Systems

1979

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 7. Contributions Guide

Simple Example
// file spaceship.h #ifndef SPACESHIP_H_ #define SPACESHIP_H_ #include <cstdlib>

namespace spaceships {

class SpaceShip { public:
SpaceShip(size_t crew); size_t get_crew_size() const;

private: const size_t crew;
};

class SpaceShuttle : public SpaceShip { public:
SpaceShuttle(); };

class Sojuz : public SpaceShip { public:
Sojuz(); };

template <typename T> class CargoShip { public:
CargoShip(const T &cargo);

private: T cargo;
};

} // namespace spaceships

#endif // SPACESHIP_H_

// file spaceship.cpp #include "spaceship.h"

namespace spaceships {

// Putting the curly braces in the same line for constructors is OK if it only initializes // values in the initializer list SpaceShip::SpaceShip(size_t crew) : crew(crew) { }

size_t SpaceShip::get_crew_size() const {
return crew; }

SpaceShuttle::SpaceShuttle() : SpaceShip(7) {
// doing further initialization }

Sojuz::Sojuz() : SpaceShip(3) {

(continues on next page)

Espressif Systems

1980

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 7. Contributions Guide

// doing further initialization }
template <typename T> CargoShip<T>::CargoShip(const T &cargo) : cargo(cargo) { }
} // namespace spaceships

(continued from previous page)

CMake Code Style
· Indent with four spaces. · Maximum line length 120 characters. When splitting lines, try to focus on readability where possible (for
example, by pairing up keyword/argument pairs on individual lines). · Donnt put anything in the optional parentheses after endforeach(), endif(), etc. · Use lowercase (with_underscores) for command, function, and macro names. · For locally scoped variables, use lowercase (with_underscores). · For globally scoped variables, use uppercase (WITH_UNDERSCORES). · Otherwise follow the defaults of the cmake-lint project.
Configuring the Code Style for a Project Using EditorConfig
EditorConfig helps developers define and maintain consistent coding styles between different editors and IDEs. The EditorConfig project consists of a file format for defining coding styles and a collection of text editor plugins that enable editors to read the file format and adhere to defined styles. EditorConfig files are easily readable and they work nicely with version control systems. For more information, see EditorConfig Website.
Documenting Code
Please see the guide here: Documenting Code.
Structure
To be written.
Language Features
To be written.
7.5.2 Install pre-commit Hook for ESP-IDF Project
Required Dependency
Python 3.6.1 or above. This is our recommended python version for IDF developers. If you still have python versions not compatible, update your python versions before installing the pre-commit hook.
Install pre-commit
Run pip install pre-commit

Espressif Systems

1981

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 7. Contributions Guide
Install pre-commit hook
1. Go to the IDF Project Directory 2. Run pre-commit install --allow-missing-config. Install hook by this approach will let you
commit successfully even in branches without the .pre-commit-config.yaml 3. pre-commit hook will run automatically when younre running git commit command
Uninstall pre-commit
Run pre-commit uninstall
Whatns More?
For detailed usage, please refer to the documentation of pre-commit.
Common Problems For Windows Users
/usr/bin/env: python: Permission denied. If younre in Git Bash, please check the python executable location by run which python. If the executable is under ~/AppData/Local/Microsoft/WindowsApps/, then itns a link to Windows AppStore, not a real one. Please install python manually and update this in your PATH environment variable.
Your %USERPROFILE% contains non-ASCII characters pre-commit may fail when initializing an environment for a particular hook when the path of precommitns cache contains non-ASCII characters. The solution is to set PRE_COMMIT_HOME to a path containing only standard characters before running pre-commit. · CMD: set PRE_COMMIT_HOME=C:\somepath\pre-commit · PowerShell: $Env:PRE_COMMIT_HOME = "C:\somepath\pre-commit" · git bash: export PRE_COMMIT_HOME="/c/somepath/pre-commit"
7.5.3 Documenting Code
The purpose of this description is to provide quick summary on documentation style used in espressif/esp-idf repository and how to add new documentation.
Introduction
When documenting code for this repository, please follow Doxygen style. You are doing it by inserting special commands, for instance @param, into standard comments blocks, for example: /**
* @param ratio this is oxygen to air ratio */
Doxygen is phrasing the code, extracting the commands together with subsequent text, and building documentation out of it. Typical comment block, that contains documentation of a function, looks like below.

Espressif Systems

1982

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 7. Contributions Guide
Doxygen supports couple of formatting styles. It also gives you great flexibility on level of details to include in documentation. To get familiar with available features, please check data rich and very well organized Doxygen Manual. Why we need it? The ultimate goal is to ensure that all the code is consistently documented, so we can use tools like Sphinx and Breathe to aid preparation and automatic updates of API documentation when the code changes. With these tools the above piece of code renders like below:

Go for it!
When writing code for this repository, please follow guidelines below.
1. Document all building blocks of code: functions, structs, typedefs, enums, macros, etc. Provide enough information about purpose, functionality and limitations of documented items, as you would like to see them documented when reading the code by others.
2. Documentation of function should describe what this function does. If it accepts input parameters and returns some value, all of them should be explained.
3. Do not add a data type before parameter or any other characters besides spaces. All spaces and line breaks are compressed into a single space. If you like to break a line, then break it twice.

Espressif Systems

1983

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 7. Contributions Guide

4. If function has void input or does not return any value, then skip @param or @return

5. When documenting a define as well as members of a struct or enum, place specific comment like below after each member.

6. To provide well formatted lists, break the line after command (like @return in example below).

* * @return * - ESP_OK if erase operation was successful

(continues on next page)

Espressif Systems

1984

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 7. Contributions Guide

(continued from previous page)
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL * - ESP_ERR_NVS_READ_ONLY if handle was opened as read only * - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist * - other error codes from the underlying storage driver *
7. Overview of functionality of documented header file, or group of files that make a library, should be placed in a separate README.rst file of the same directory. If this directory contains header files for different APIs, then the file name should be apiname-readme.rst.

Go one extra mile

Here are a couple of tips on how you can make your documentation even better and more useful to the reader and writer.
When writing codes, please follow the guidelines below:
1. Add code snippets to illustrate implementation. To do so, enclose snippet using @code{c} and @endcode commands.

* * @code{c} * // Example of using nvs_get_i32: * int32_t max_buffer_size = 4096; // default value * esp_err_t err = nvs_get_i32(my_handle, "max_buffer_size", &max_buffer_size); * assert(err == ESP_OK || err == ESP_ERR_NVS_NOT_FOUND); * // if ESP_ERR_NVS_NOT_FOUND was returned, max_buffer_size will still * // have its default value. * @endcode *
The code snippet should be enclosed in a comment block of the function that it illustrates. 2. To highlight some important information use command @attention or @note.

*

* @attention

*

1. This API only impact WIFI_MODE_STA or WIFI_MODE_APSTA mode

*

2. If the ESP32 is connected to an AP, call esp_wifi_disconnect to

disconnect.

*

Above example also shows how to use a numbered list. 3. To provide common description to a group of similar functions, enclose them using /**@{*/ and /**@}*/
markup commands:

/**@{*/ /**
* @brief common description of similar functions * */ void first_similar_function (void); void second_similar_function (void); /**@}*/
For practical example see nvs_flash/include/nvs.h. 4. You may want to go even further and skip some code like repetitive defines or enumerations. In such case,
enclose the code within /** @cond */ and /** @endcond */ commands. Example of such implementation is provided in driver/include/driver/gpio.h. 5. Use markdown to make your documentation even more readable. You will add headers, links, tables and more.

Espressif Systems

1985

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 7. Contributions Guide
* * [ESP32-S3 Technical Reference Manual](https://www.espressif.com/sites/ default/files/documentation/esp32-s3_technical_reference_manual_en.pdf) *
Note: Code snippets, notes, links, etc. will not make it to the documentation, if not enclosed in a comment block associated with one of documented objects.
6. Prepare one or more complete code examples together with description. Place description to a separate file README.md in specific folder of examples directory.
Standardize Document Format When it comes to text, please follow guidelines below to provide well formatted Markdown (.md) or reST (.rst) documents.
1. Please ensure that one paragraph is written in one line. Donnt break lines like below. Breaking lines to enhance readability is only suitable for writing codes. To make the text easier to read, it is recommended to place an empty line to separate the paragraph.
Fig. 1: One line for one paragraph (click to enlarge)

Fig. 2: No line breaks within the same paragraph (click to enlarge)
2. Please make the line number of CN and EN documents consistent like below. The benefit of this approach is that it can save time for both writers and translators. When non-bilingual writers need to update text, they only need to update the same line in the corresponding CN or EN document. For translators, if documents are updated in English, then translators can quickly locate where to update in the corresponding CN document later. Besides, by comparing the total number of lines in EN and CN documents, you can quickly find out whether the CN version lags behind the EN version.

Building Documentation
The documentation is built with the esp-docs Python package, which is a wrapper around Sphinx To install it simply do:

Espressif Systems

1986

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 7. Contributions Guide

Fig. 3: Keep the line number for EN and CN documents consistent (click to enlarge)

pip install esp-docs After a successful install then the documentation can be built from the docs folder with: build-docs build or for specific target and language with: build-docs -t esp32 -l en build For more in-depth documentation about esp-docs features please see the documentation in the esp-docs repository.

Wrap up
We love good code that is doing cool things. We love it even better, if it is well documented, so we can quickly make it run and also do the cool things. Go ahead, contribute your code and documentation!

Related Documents · API Documentation Template

7.5.4 Creating Examples
Each ESP-IDF example is a complete project that someone else can copy and adapt the code to solve their own problem. Examples should demonstrate ESP-IDF functionality, while keeping this purpose in mind.

Structure
· The main directory should contain a source file named (something)_example_main.c with the main functionality.
· If the example has additional functionality, split it logically into separate C or C++ source files under main and place a corresponding header file in the same directory.
· If the example has a lot of additional functionality, consider adding a components directory to the example project and make some example-specific components with library functionality. Only do this if the components are specific to the example, if theynre generic or common functionality then they should be added to ESP-IDF itself.

Espressif Systems

1987

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 7. Contributions Guide
· The example should have a README.md file. Use the template example README and adapt it for your particular example.
· Examples should have an example_test.py file for running an automated example test. If submitting a GitHub Pull Request which includes an example, itns OK not to include this file initially. The details can be discussed as part of the Pull Request.
General Guidelines
Example code should follow the Espressif IoT Development Framework Style Guide.
Checklist
Checklist before submitting a new example:
· Example project name (in README.md) uses the word oexamplep. Use oexamplepinstead of odemop, otestpor similar words. · Example does one distinct thing. If the example does more than one thing at a time, split it into two or more
examples. · Example has a README.md file which is similar to the template example README . · Functions and variables in the example are named according to naming section of the style guide. (For non-static
names which are only specific to the examplens source files, you can use example or something similar as a prefix.) · All code in the example is well structured and commented. · Any unnecessary code (old debugging logs, commented-out code, etc.) is removed from the example. · Options in the example (like network names, addresses, etc) are not hard-coded. Use configuration items if possible, or otherwise declare macros or constants) · Configuration items are provided in a KConfig.projbuild file with a menu named oExample Configurationp. See existing example projects to see how this is done. · All original example code has a license header saying it is oin the public domain / CC0p, and a warranty disclaimer clause. Alternatively, the example is licensed under Apache License 2.0. See existing examples for headers to adapt from. · Any adapted or third party example code has the original license header on it. This code must be licensed compatible with Apache License 2.0.
7.5.5 API Documentation Template
Note: INSTRUCTIONS
1. Use this file (docs/en/api-reference/template.rst) as a template to document API. 2. Change the file name to the name of the header file that represents documented API. 3. Include respective files with descriptions from the API folder using ..include::
· README.rst · example.rst ·l 4. Optionally provide description right in this file. 5. Once done, remove all instructions like this one and any superfluous headers.

Overview
Note: INSTRUCTIONS 1. Provide overview where and how this API may be used. 2. Where applicable include code snippets to illustrate functionality of particular functions.

Espressif Systems

1988

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 7. Contributions Guide
3. To distinguish between sections, use the following heading levels: · # with overline, for parts · * with overline, for chapters · =, for sections · -, for subsections · ^, for subsubsections · ", for paragraphs
Application Example
Note: INSTRUCTIONS 1. Prepare one or more practical examples to demonstrate functionality of this API. 2. Each example should follow pattern of projects located in esp-idf/examples/ folder. 3. Place example in this folder complete with README.md file. 4. Provide overview of demonstrated functionality in README.md. 5. With good overview reader should be able to understand what example does without opening the source code. 6. Depending on complexity of example, break down description of code into parts and provide overview of functionality of each part. 7. Include flow diagram and screenshots of application output if applicable. 8. Finally add in this section synopsis of each example together with link to respective folder in esp-idf/ examples/.
API Reference
Note: INSTRUCTIONS 1. This repository provides for automatic update of API reference documentation using code markup retrieved by Doxygen from header files. 1. Update is done on each documentation build by invoking Sphinx extension :esp_extensions/run_doxygen.py for all header files listed in the INPUT statement of docs/doxygen/Doxyfile. 1. Each line of the INPUT statement (other than a comment that begins with ##) contains a path to header file *.h that will be used to generate corresponding *.inc files:
## ## Wi-Fi - API Reference ## ../components/esp32/include/esp_wifi.h \ ../components/esp32/include/esp_smartconfig.h \
1. When the headers are expanded, any macros defined by default in sdkconfig.h as well as any macros defined in SOC-specific include/soc/*_caps.h headers will be expanded. This allows the headers to include/exclude material based on the IDF_TARGET value.
1. The *.inc files contain formatted reference of API members generated automatically on each documentation build. All *.inc files are placed in Sphinx _build directory. To see directives generated for e.g. esp_wifi.h, run python gen-dxd.py esp32/include/esp_wifi.h.
1. To show contents of *.inc file in documentation, include it as follows:
.. include-build-file:: inc/esp_wifi.inc For example see docs/en/api-reference/network/esp_wifi.rst

Espressif Systems

1989

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 7. Contributions Guide
1. Optionally, rather that using *.inc files, you may want to describe API in you own way. See docs/en/apiguides/ulp.rst for example. Below is the list of common .. doxygen...:: directives: · Functions - .. doxygenfunction:: name_of_function · Unions -.. doxygenunion:: name_of_union · Structures -.. doxygenstruct:: name_of_structure together with :members: · Macros - .. doxygendefine:: name_of_define · Type Definitions - .. doxygentypedef:: name_of_type · Enumerations - .. doxygenenum:: name_of_enumeration See Breathe documentation for additional information. To provide a link to header file, use the link custom role directive as follows:
* :component_file:`path_to/header_file.h`
1. In any case, to generate API reference, the file docs/doxygen/Doxyfile should be updated with paths to *.h headers that are being documented.
1. When changes are committed and documentation is build, check how this section has been rendered. Correct annotations in respective header files, if required.

7.5.6 Contributor Agreement
Individual Contributor Non-Exclusive License Agreement
including the Traditional Patent License OPTION
Thank you for your interest in contributing to Espressif IoT Development Framework (esp-idf) (oWepor oUsp). The purpose of this contributor agreement (oAgreementp) is to clarify and document the rights granted by contributors to Us. To make this document effective, please follow the instructions at CONTRIBUTING.rst
1. DEFINITIONS oYoup means the Individual Copyright owner who submits a Contribution to Us. If You are an employee and submit the Contribution as part of your employment, You have had Your employer approve this Agreement or sign the Entity version of this document. oContributionpmeans any original work of authorship (software and/or documentation) including any modifications or additions to an existing work, Submitted by You to Us, in which You own the Copyright. If You do not own the Copyright in the entire work of authorship, please contact Us at [email protected]. oCopyrightpmeans all rights protecting works of authorship owned or controlled by You, including copyright, moral and neighboring rights, as appropriate, for the full term of their existence including any extensions by You. oMaterialp means the software or documentation made available by Us to third parties. When this Agreement covers more than one software project, the Material means the software or documentation to which the Contribution was Submitted. After You Submit the Contribution, it may be included in the Material. oSubmitpmeans any form of physical, electronic, or written communication sent to Us, including but not limited to electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, Us, but excluding communication that is conspicuously marked or otherwise designated in writing by You as oNot a Contribution.p oSubmission Datep means the date You Submit a Contribution to Us. oDocumentationp means any non-software portion of a Contribution.
2. LICENSE GRANT 2.1 Copyright License to Us Subject to the terms and conditions of this Agreement, You hereby grant to Us a worldwide, royalty-free, NONexclusive, perpetual and irrevocable license, with the right to transfer an unlimited number of non-exclusive licenses

Espressif Systems

1990

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 7. Contributions Guide
or to grant sublicenses to third parties, under the Copyright covering the Contribution to use the Contribution by all means, including, but not limited to:
· to publish the Contribution, · to modify the Contribution, to prepare derivative works based upon or containing the Contribution and to
combine the Contribution with other software code, · to reproduce the Contribution in original or modified form, · to distribute, to make the Contribution available to the public, display and publicly perform the Contribution
in original or modified form.
2.2 Moral Rights remain unaffected to the extent they are recognized and not waivable by applicable law. Notwithstanding, You may add your name in the header of the source code files of Your Contribution and We will respect this attribution when using Your Contribution.
3. PATENTS 3.1 Patent License
Subject to the terms and conditions of this Agreement You hereby grant to us a worldwide, royalty-free, non-exclusive, perpetual and irrevocable (except as stated in Section 3.2) patent license, with the right to transfer an unlimited number of non-exclusive licenses or to grant sublicenses to third parties, to make, have made, use, sell, offer for sale, import and otherwise transfer the Contribution and the Contribution in combination with the Material (and portions of such combination). This license applies to all patents owned or controlled by You, whether already acquired or hereafter acquired, that would be infringed by making, having made, using, selling, offering for sale, importing or otherwise transferring of Your Contribution(s) alone or by combination of Your Contribution(s) with the Material.
3.2 Revocation of Patent License
You reserve the right to revoke the patent license stated in section 3.1 if we make any infringement claim that is targeted at your Contribution and not asserted for a Defensive Purpose. An assertion of claims of the Patents shall be considered for a oDefensive Purposepif the claims are asserted against an entity that has filed, maintained, threatened, or voluntarily participated in a patent infringement lawsuit against Us or any of Our licensees.
4. DISCLAIMER THE CONTRIBUTION IS PROVIDED oAS ISp. MORE PARTICULARLY, ALL EXPRESS OR IMPLIED WARRANTIES INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE EXPRESSLY DISCLAIMED BY YOU TO US AND BY US TO YOU. TO THE EXTENT THAT ANY SUCH WARRANTIES CANNOT BE DISCLAIMED, SUCH WARRANTY IS LIMITED IN DURATION TO THE MINIMUM PERIOD PERMITTED BY LAW.
5. Consequential Damage Waiver TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT WILL YOU OR US BE LIABLE FOR ANY LOSS OF PROFITS, LOSS OF ANTICIPATED SAVINGS, LOSS OF DATA, INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL AND EXEMPLARY DAMAGES ARISING OUT OF THIS AGREEMENT REGARDLESS OF THE LEGAL OR EQUITABLE THEORY (CONTRACT, TORT OR OTHERWISE) UPON WHICH THE CLAIM IS BASED.
6. Approximation of Disclaimer and Damage Waiver IF THE DISCLAIMER AND DAMAGE WAIVER MENTIONED IN SECTION 4 AND SECTION 5 CANNOT BE GIVEN LEGAL EFFECT UNDER APPLICABLE LOCAL LAW, REVIEWING COURTS SHALL APPLY LOCAL LAW THAT MOST CLOSELY APPROXIMATES AN ABSOLUTE WAIVER OF ALL CIVIL LIABILITY IN CONNECTION WITH THE CONTRIBUTION.
7. Term 7.1 This Agreement shall come into effect upon Your acceptance of the terms and conditions.
7.2 In the event of a termination of this Agreement Sections 4, 5, 6, 7 and 8 shall survive such termination and shall remain in full force thereafter. For the avoidance of doubt, Contributions that are already licensed under a free and open source license at the date of the termination shall remain in full force after the termination of this Agreement.

Espressif Systems

1991

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 7. Contributions Guide
8. Miscellaneous 8.1 This Agreement and all disputes, claims, actions, suits or other proceedings arising out of this agreement or relating in any way to it shall be governed by the laws of Peoplens Republic of China excluding its private international law provisions. 8.2 This Agreement sets out the entire agreement between You and Us for Your Contributions to Us and overrides all other agreements or understandings. 8.3 If any provision of this Agreement is found void and unenforceable, such provision will be replaced to the extent possible with a provision that comes closest to the meaning of the original provision and that is enforceable. The terms and conditions set forth in this Agreement shall apply notwithstanding any failure of essential purpose of this Agreement or any limited remedy to the maximum extent possible under law. 8.4 You agree to notify Us of any facts or circumstances of which you become aware that would make this Agreement inaccurate in any respect.
You
Date: Name: Title: Address:
Us
Date: Name: Title: Address:
7.5.7 Copyright Header Guide
ESP-IDF is released under the Apache License 2.0 with some additional third-party copyrighted code released under various licenses. For further information please refer to the list of copyrights and licenses. This page explains how the source code should be properly marked with a copyright header. ESP-IDF uses The Software Package Data Exchange (SPDX) format which is short and can be easily read by humans or processed by automated tools for copyright checks.
How to Check the Copyright Headers
Please make sure you have installed the pre-commit hooks which contain a copyright header checker as well. The checker can suggest a header if it is not able to detect a properly formatted SPDX header.
What if the Checkerns Suggestion is Incorrect?
No automated checker (no matter how good is) can replace humans. So the developerns responsibility is to modify the offered header to be in line with the law and the license restrictions of the original code on which the work is based on. Certain licenses are not compatible between each other. Such corner cases will be covered by the following examples. The checker can be configured with the tools/ci/check_copyright_config.yaml configuration file. Please check the options it offers and consider updating it in order to match the headers correctly.

Espressif Systems

1992

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 7. Contributions Guide
Common Examples of Copyright Headers
The simplest case is when the code is not based on any licensed previous work, e.g. it was written completely from scratch. Such code can be decorated with the following copyright header and put under the license of ESP-IDF:
/* * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */
Less restrictive parts of ESP-IDF Some parts of ESP-IDF are deliberately under less restrictive licenses in order to ease their re-use in commercial closed source projects. This is the case for ESP-IDF examples which are in Public domain or under the Creative Commons Zero Universal (CC0) license. The following header can be used in such source files:
/* * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Unlicense OR CC0-1.0 */
The option allowing multiple licenses joined with the OR keyword from the above example can be achieved with the definition of multiple allowed licenses in the tools/ci/check_copyright_config.yaml configuration file. Please use this option with care and only selectively for a limited part of ESP-IDF.
Third party licenses Code licensed under different licenses, modified by Espressif Systems and included in ESPIDF cannot be licensed under Apache License 2.0 not even if the checker suggests it. It is advised to keep the original copyright header and add an SPDX before it.
The following example is a suitable header for a code licensed under theoGNU General Public License v2.0 or laterp held by John Doe with some additional modifications done by Espressif Systems:
/* * SPDX-FileCopyrightText: 1991 John Doe * * SPDX-License-Identifier: GPL-2.0-or-later * * SPDX-FileContributor: 2019-2022 Espressif Systems (Shanghai) CO LTD */
The licenses can be identified and the short SPDX identifiers can be found in the official SPDX license list. Other very common licenses are the GPL-2.0-only, the BSD-3-Clause, and the BSD-2-Clause.
The configuration stored in tools/ci/check_copyright_config.yaml offers features useful for third party licenses:
· A different license can be defined for the files part of a third party library. · The check for a selected set of files can be permanently disabled. Please use this option with care and only in
cases when none of the other options are suitable.

Espressif Systems

1993

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 7. Contributions Guide

Espressif Systems

1994

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 8
ESP-IDF Versions
The ESP-IDF GitHub repository is updated regularly, especially the master branch where new development takes place. For production use, there are also stable releases available.
8.1 Releases
The documentation for the current stable release version can always be found at this URL: https://docs.espressif.com/projects/esp-idf/en/stable/ Documentation for the latest version (master branch) can always be found at this URL: https://docs.espressif.com/projects/esp-idf/en/latest/ The full history of releases can be found on the GitHub repository Releases page. There you can find release notes, links to each version of the documentation, and instructions for obtaining each version.
8.2 Which Version Should I Start With?
· For production purposes, use the current stable version. Stable versions have been manually tested, and are updated with obugfix releasespwhich fix bugs without changing other functionality (see Versioning Scheme for more details). Every stable release version can be found on the Releases page.
· For prototyping, experimentation or for developing new ESP-IDF features, use the latest version (master branch in Git). The latest version in the master branch has all the latest features and has passed automated testing, but has not been completely manually tested (obleeding edgep).
· If a required feature is not yet available in a stable release, but you do not want to use the master branch, it is possible to check out a pre-release version or a release branch. It is recommended to start from a stable version and then follow the instructions for Updating to a Pre-Release Version or Updating to a Release Branch.
See Updating ESP-IDF if you already have a local copy of ESP-IDF and wish to update it.
8.3 Versioning Scheme
ESP-IDF uses Semantic Versioning. This means that: · Major Releases, like v3.0, add new functionality and may change functionality. This includes removing deprecated functionality.
1995

Chapter 8. ESP-IDF Versions

If updating to a new major release (for example, from v2.1 to v3.0), some of your projectns code may need updating and functionality may need to be re-tested. The release notes on the Releases page include lists of Breaking Changes to refer to. · Minor Releases like v3.1 add new functionality and fix bugs but will not change or remove documented functionality, or make incompatible changes to public APIs. If updating to a new minor release (for example, from v3.0 to v3.1), your projectns code does not require updating, but you should re-test your project. Pay particular attention to the items mentioned in the release notes on the Releases page. · Bugfix Releases like v3.0.1 only fix bugs and do not add new functionality. If updating to a new bugfix release (for example, from v3.0 to v3.0.1), you do not need to change any code in your project, and you only need to re-test the functionality directly related to bugs listed in the release notes on the Releases page.

8.4 Support Periods

Each ESP-IDF major and minor release version has an associated support period. After this period, the release is End of Life and no longer supported.
The ESP-IDF Support Period Policy explains this in detail, and describes how the support periods for each release are determined.
Each release on the Releases page includes information about the support period for that particular release.
As a general guideline:
· If starting a new project, use the latest stable release. · If you have a GitHub account, click the oWatchpbutton in the top-right of the Releases page and choose oReleases onlyp. GitHub will notify you whenever a new release is available. Whenever a bug fix release is
available for the version you are using, plan to update to it. · If possible, periodically update the project to a new major or minor ESP-IDF version (for example, once a
year.) The update process should be straightforward for Minor updates, but may require some planning and checking of the release notes for Major updates. · Always plan to update to a newer release before the release you are using becomes End of Life.
Each ESP-IDF major and minor release (V4.1, V4.2, etc) is supported for 30 months after the initial stable release date.
Supported means that the ESP-IDF team will continue to apply bug fixes, security fixes, etc to the release branch on GitHub, and periodically make new bugfix releases as needed.
Support period is divided into oServicepand oMaintenancepperiod:

Period Service Maintenance

Duration 12 months 18 months

Recommended for new projects? Yes No

During the Service period, bugfixes releases are more frequent. In some cases, support for new features may be added during the Service period (this is reserved for features which are needed to meet particular regulatory requirements or standards for new products, and which carry a very low risk of introducing regressions.)
During the Maintenance period, the version is still supported but only bugfixes for high severity issues or security issues will be applied.
Using an oIn Servicepversion is recommended when starting a new project.
Users are encouraged to upgrade all projects to a newer ESP-IDF release before the support period finishes and the release becomes End of Life (EOL). It is our policy to not continue fixing bugs in End of Life releases.
Pre-release versions (betas, previews, -rc and -dev versions, etc) are not covered by any support period. Sometimes a particular feature is marked as oPreviewpin a release, which means it is also not covered by the support period.

Espressif Systems

1996

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 8. ESP-IDF Versions The ESP-IDF Programming Guide has information about the different versions of ESP-IDF (major, minor, bugfix, etc).
8.5 Checking the Current Version
The local ESP-IDF version can be checked by using idf.py: idf.py --version The ESP-IDF version is also compiled into the firmware and can be accessed (as a string) via the macro IDF_VER. The default ESP-IDF bootloader will print the version on boot (the version information is not always updated if the code in the GitHub repo is updated, it only changes if there is a clean build or if that particular source file is recompiled). If writing code that needs to support multiple ESP-IDF versions, the version can be checked at compile time using compile-time macros. Examples of ESP-IDF versions:

Espressif Systems

1997

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 8. ESP-IDF Versions Version String v3.2-dev-306-gbeb3611ca
v3.0.2 v3.1-beta1-75-g346d6b0ea
v3.0.1-dirty

Meaning
Master branch pre-release. - v3.2-dev - in development for version 3.2. - 306 - number of commits after v3.2 development started. - beb3611ca - commit identifier.
Stable release, tagged v3.0.2.
Beta version in development (on a release branch). - v3.1-beta1 - pre-release tag. - 75 - number of commits after the pre-release beta tag was assigned. - 346d6b0ea - commit identifier.
Stable release, tagged v3.0.1. - dirty means that there are modifications in the local ESP-IDF directory.

8.6 Git Workflow
The development (Git) workflow of the Espressif ESP-IDF team is as follows:
· New work is always added on the master branch (latest version) first. The ESP-IDF version on master is always tagged with -dev (for oin developmentp), for example v3.1-dev.
· Changes are first added to an internal Git repository for code review and testing but are pushed to GitHub after automated testing passes.
· When a new version (developed on master) becomes feature complete and obetapquality, a new branch is made for the release, for example release/v3.1. A pre-release tag is also created, for example v3.1beta1. You can see a full list of branches and a list of tags on GitHub. Beta pre-releases have release notes which may include a significant number of Known Issues.
· As testing of the beta version progresses, bug fixes will be added to both the master branch and the release branch. New features for the next release may start being added to master at the same time.
· Once testing is nearly complete a new release candidate is tagged on the release branch, for example v3.1rc1. This is still a pre-release version.
· If no more significant bugs are found or reported, then the final Major or Minor Version is tagged, for example v3.1. This version appears on the Releases page.
· As bugs are reported in released versions, the fixes will continue to be committed to the same release branch. · Regular bugfix releases are made from the same release branch. After manual testing is complete, a bugfix
release is tagged (i.e. v3.1.1) and appears on the Releases page.

8.7 Updating ESP-IDF
Updating ESP-IDF depends on which version(s) you wish to follow: · Updating to Stable Release is recommended for production use.

Espressif Systems

1998

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 8. ESP-IDF Versions
· Updating to Master Branch is recommended for the latest features, development use, and testing. · Updating to a Release Branch is a compromise between the first two.
Note: These guides assume that you already have a local copy of ESP-IDF cloned. To get one, check Step 2 in the Getting Started guide for any ESP-IDF version.
8.7.1 Updating to Stable Release
To update to a new ESP-IDF release (recommended for production use), this is the process to follow: · Check the Releases page regularly for new releases. · When a bugfix release for the version you are using is released (for example, if using v3.0.1 and v3.0.2 is released), check out the new bugfix version into the existing ESP-IDF directory:
cd $IDF_PATH git fetch git checkout vX.Y.Z git submodule update --init --recursive
· When major or minor updates are released, check the Release Notes on the releases page and decide if you want to update or to stay with your current release. Updating is via the same Git commands shown above.
Note: If you installed the stable release via zip file instead of using git, it might not be possible to update versions using the commands. In this case, update by downloading a new zip file and replacing the entire IDF_PATH directory with its contents.
8.7.2 Updating to a Pre-Release Version
It is also possible to git checkout a tag corresponding to a pre-release version or release candidate, the process is the same as Updating to Stable Release. Pre-release tags are not always found on the Releases page. Consult the list of tags on GitHub for a full list. Caveats for using a pre-release are similar to Updating to a Release Branch.
8.7.3 Updating to Master Branch
Note: Using Master branch means living oon the bleeding edgepwith the latest ESP-IDF code.
To use the latest version on the ESP-IDF master branch, this is the process to follow: · Check out the master branch locally: cd $IDF_PATH git checkout master git pull git submodule update --init --recursive · Periodically, re-run git pull to pull the latest version of master. Note that you may need to change your project or report bugs after updating your master branch. · To switch from master to a release branch or stable version, run git checkout as shown in the other sections.

Espressif Systems

1999

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 8. ESP-IDF Versions
Important: It is strongly recommended to regularly run git pull and then git submodule update -init --recursive so a local copy of master does not get too old. Arbitrary old master branch revisions are effectively unsupportable osnapshotspthat may have undocumented bugs. For a semi-stable version, try Updating to a Release Branch instead.
8.7.4 Updating to a Release Branch
In terms of stability, using a release branch is part-way between using the master branch and only using stable releases. A release branch is always beta quality or better, and receives bug fixes before they appear in each stable release. You can find a list of branches on GitHub. For example, to follow the branch for ESP-IDF v3.1, including any bugfixes for future releases like v3.1.1, etc: cd $IDF_PATH git fetch git checkout release/v3.1 git pull git submodule update --init --recursive
Each time you git pull this branch, ESP-IDF will be updated with fixes for this release.
Note: There is no dedicated documentation for release branches. It is recommended to use the documentation for the closest version to the branch which is currently checked out.

Espressif Systems

2000

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 9
Resources
9.1 PlatformIO
· What is PlatformIO? · Installation · Configuration · Tutorials · Project Examples · Next Steps
9.1.1 What is PlatformIO?
PlatformIO is a cross-platform embedded development environment with out-of-the-box support for ESP-IDF. Since ESP-IDF support within PlatformIO is not maintained by the Espressif team, please report any issues with PlatformIO directly to its developers in the official PlatformIO repositories. A detailed overview of the PlatformIO ecosystem and its philosophy can be found in the official PlatformIO documentation.
9.1.2 Installation
· PlatformIO IDE is a toolset for embedded C/C++ development available on Windows, macOS and Linux platforms
· PlatformIO Core (CLI) is a command-line tool that consists of multi-platform build system, platform and library managers and other integration components. It can be used with a variety of code development environments and allows integration with cloud platforms and web services
2001

Chapter 9. Resources
9.1.3 Configuration
Please go through the official PlatformIO configuration guide for ESP-IDF.
9.1.4 Tutorials
· ESP-IDF and ESP32-DevKitC: debugging, unit testing, project analysis
9.1.5 Project Examples
Please check ESP-IDF page in the official PlatformIO documentation
9.1.6 Next Steps
Here are some useful links for exploring the PlatformIO ecosystem: · Learn more about integrations with other IDEs/Text Editors · Get help from PlatformIO community
9.2 Useful Links
· The esp32.com forum is a place to ask questions and find community resources. · Check the Issues section on GitHub if you find a bug or have a feature request. Please check existing Issues
before opening a new one. · A comprehensive collection of solutions, practical applications, components and drivers based on ESP-IDF is
available in ESP IoT Solution repository. In most of cases descriptions are provided both in English and in  . · To develop applications using Arduino platform, refer to Arduino core for the ESP32, ESP32-S2 and ESP32C3. · Several books have been written about ESP32 and they are listed on Espressif web site. · If younre interested in contributing to ESP-IDF, please check the Contributions Guide. · For additional ESP32-S3 product related information, please refer to documentation section of Espressif site. · Download latest and previous versions of this documentation in PDF and HTML format.

Espressif Systems

2002

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 10
Copyrights and Licenses
10.1 Software Copyrights
All original source code in this repository is Copyright (C) 2015-2022 Espressif Systems. This source code is licensed under the Apache License 2.0 as described in the file LICENSE. Additional third party copyrighted code is included under the following licenses. Where source code headers specify Copyright & License information, this information takes precedence over the summaries made here. Some examples use external components which are not Apache licensed, please check the copyright description in each example source code.
10.1.1 Firmware Components
These third party libraries can be included into the application (firmware) produced by ESP-IDF. · Newlib is licensed under the BSD License and is Copyright of various parties, as described in COPYING.NEWLIB. · Xtensa header files are Copyright (C) 2013 Tensilica Inc and are licensed under the MIT License as reproduced in the individual header files. · Original parts of FreeRTOS (components/freertos) are Copyright (C) 2017 Amazon.com, Inc. or its affiliates are licensed under the MIT License, as described in license.txt. · Original parts of LWIP (components/lwip) are Copyright (C) 2001, 2002 Swedish Institute of Computer Science and are licensed under the BSD License as described in COPYING file. · wpa_supplicant Copyright (c) 2003-2005 Jouni Malinen and licensed under the BSD license. · FreeBSD net80211 Copyright (c) 2004-2008 Sam Leffler, Errno Consulting and licensed under the BSD license. · argtable3 argument parsing library Copyright (C) 1998-2001,2003-2011,2013 Stewart Heitmann and licensed under 3-clause BSD license. · linenoise line editing library Copyright (c) 2010-2014 Salvatore Sanfilippo, Copyright (c) 2010-2013 Pieter Noordhuis, licensed under 2-clause BSD license. · libcoap COAP library Copyright (c) 2010-2017 Olaf Bergmann and others, is licensed under 2-clause BSD license as described in LICENSE file and COPYING file . · FatFS library, Copyright (C) 2017 ChaN, is licensed under a BSD-style license . · cJSON library, Copyright (c) 2009-2017 Dave Gamble and cJSON contributors, is licensed under MIT license as described in LICENSE file . · micro-ecc library, Copyright (c) 2014 Kenneth MacKay, is licensed under 2-clause BSD license. · Mbed TLS library, Copyright (C) 2006-2018 ARM Limited, is licensed under Apache License 2.0 as described in LICENSE file . · SPIFFS library, Copyright (c) 2013-2017 Peter Andersson, is licensed under MIT license as described in LICENSE file .
2003

Chapter 10. Copyrights and Licenses

· SD/MMC driver is derived from OpenBSD SD/MMC driver, Copyright (c) 2006 Uwe Stuehler, and is licensed under BSD license.
· Asio , Copyright (c) 2003-2018 Christopher M. Kohlhoff is licensed under the Boost Software License as described in COPYING file.
· ESP-MQTT MQTT Package (contiki-mqtt) - Copyright (c) 2014, Stephen Robinson, MQTT-ESP - Tuan PM <tuanpm at live dot com> is licensed under Apache License 2.0 as described in LICENSE file .
· BLE Mesh is adapted from Zephyr Project, Copyright (c) 2017-2018 Intel Corporation and licensed under Apache License 2.0
· mynewt-nimble Apache Mynewt NimBLE, Copyright 2015-2018, The Apache Software Foundation, is licensed under Apache License 2.0 as described in LICENSE file.
· cryptoauthlib Microchip CryptoAuthentication Library - Copyright (c) 2015 - 2018 Microchip Technology Inc, is licensed under common Microchip software License as described in LICENSE file
· TLSF allocator Two Level Segregated Fit memory allocator, Copyright (c) 2006-2016, Matthew Conte, and licensed under the BSD license.
· qrcode QR Code generator library Copyright (c) Project Nayuki, is licensed under MIT license. · openthread, Copyright (c) The OpenThread Authors, is licensed under BSD License as described in LICENSE
file. · UBSAN runtime iCopyright (c) 2016, Linaro Limited and Jií Zárevúcky, licensed under the BSD 2-clause
license. · freemodbus Copyright (c) 2006-2013 Christian Walter, Armink and licensed under the BSD license. · HTTP Parser Based on src/http/ngx_http_parse.c from NGINX copyright Igor Sysoev. Additional changes
are licensed under the same terms as NGINX and Joyent, Inc. and other Node contributors. For details please check LICENSE file.
10.1.2 Build Tools
This is the list of licenses for tools included in this repository, which are used to build applications. The tools do not become part of the application (firmware), so their license does not affect licensing of the application.
· esptool.py is Copyright (C) 2014-2016 Fredrik Ahlberg, Angus Gratton and is licensed under the GNU General Public License v2, as described in LICENSE file.
10.1.3 Documentation
· HTML version of the ESP-IDF Programming Guide uses the Sphinx theme sphinx_idf_theme, which is Copyright (c) 2013-2020 Dave Snider, Read the Docs, Inc. & contributors, and Espressif Systems (Shanghai) CO., LTD. It is based on sphinx_rtd_theme. Both are licensed under MIT license.

10.2 ROM Source Code Copyrights
ESP32, ESP32-S and ESP32-C Series SoCs mask ROM hardware includes binaries compiled from portions of the following third party software:
· Newlib , licensed under the BSD License and is Copyright of various parties, as described in COPYING.NEWLIB.
· Xtensa libhal, Copyright (c) Tensilica Inc and licensed under the MIT license (see below). · TinyBasic Plus, Copyright Mike Field & Scott Lawrence and licensed under the MIT license (see below). · miniz, by Rich Geldreich - placed into the public domain. · wpa_supplicant Copyright (c) 2003-2005 Jouni Malinen and licensed under the BSD license. · TJpgDec Copyright (C) 2011, ChaN, all right reserved. See below for license.

10.3 Xtensa libhal MIT License
Copyright (c) 2003, 2006, 2010 Tensilica Inc.

Espressif Systems

2004

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 10. Copyrights and Licenses
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the oSoftwarep), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDEDoAS ISp, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
10.4 TinyBasic Plus MIT License
Copyright (c) 2012-2013
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the oSoftwarep), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDEDoAS ISp, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
10.5 TJpgDec License
TJpgDec - Tiny JPEG Decompressor R0.01 (C)ChaN, 2011 The TJpgDec is a generic JPEG decompressor module for tiny embedded systems. This is a free software that opened for education, research and commercial developments under license policy of following terms.
Copyright (C) 2011, ChaN, all right reserved.
· The TJpgDec module is a free software and there is NO WARRANTY. · No restriction on use. You can use, modify and redistribute it for personal, non-profit or commercial products
UNDER YOUR RESPONSIBILITY. · Redistributions of source code must retain the above copyright notice.

Espressif Systems

2005

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 10. Copyrights and Licenses

Espressif Systems

2006

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 11
About
This is documentation of ESP-IDF, the framework to develop applications for ESP32-S3. The ESP32-S3 is a 2.4 GHz Wi-Fi Bluetooth Low Energy combo SoC, which integrates a Xtensa® 32-bit LX7 CPU.
Fig. 1: Espressif IoT Integrated Development Framework The ESP-IDF, Espressif IoT Development Framework, provides toolchain, API, components and workflows to develop applications for ESP32-S3 using Windows, Linux and Mac OS operating systems.
2007

Chapter 11. About

Espressif Systems

2008

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Chapter 12
Switch Between Languages
The ESP-IDF Programming Guide is now available in two languages. Please refer to the English version if there is any discrepancy.
· English · Chinese You can easily change from one language to another by clicking the language link you can find at the top of every document that has a translation.
· genindex
2009

Chapter 12. Switch Between Languages

Espressif Systems

2010

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

Symbols
_ESP_LOG_EARLY_ENABLED (C macro), 1310 _ESP_NETIF_SUPPRESS_LEGACY_WARNING_ (C
macro), 495 _XFER_2_RD (C macro), 928 _XFER_2_WR (C macro), 928 _XFER_4_RD (C macro), 928 _XFER_4_WR (C macro), 928 [anonymous] (C++ enum), 54, 209
A
ADC1_CHANNEL_0 (C++ enumerator), 510 ADC1_CHANNEL_0_GPIO_NUM (C macro), 519 ADC1_CHANNEL_1 (C++ enumerator), 510 ADC1_CHANNEL_1_GPIO_NUM (C macro), 519 ADC1_CHANNEL_2 (C++ enumerator), 510 ADC1_CHANNEL_2_GPIO_NUM (C macro), 519 ADC1_CHANNEL_3 (C++ enumerator), 510 ADC1_CHANNEL_3_GPIO_NUM (C macro), 519 ADC1_CHANNEL_4 (C++ enumerator), 510 ADC1_CHANNEL_4_GPIO_NUM (C macro), 519 ADC1_CHANNEL_5 (C++ enumerator), 510 ADC1_CHANNEL_5_GPIO_NUM (C macro), 519 ADC1_CHANNEL_6 (C++ enumerator), 510 ADC1_CHANNEL_6_GPIO_NUM (C macro), 519 ADC1_CHANNEL_7 (C++ enumerator), 510 ADC1_CHANNEL_7_GPIO_NUM (C macro), 519 ADC1_CHANNEL_8 (C++ enumerator), 510 ADC1_CHANNEL_8_GPIO_NUM (C macro), 519 ADC1_CHANNEL_9 (C++ enumerator), 510 ADC1_CHANNEL_9_GPIO_NUM (C macro), 519 ADC1_CHANNEL_MAX (C++ enumerator), 510 adc1_channel_t (C++ enum), 510 adc1_config_channel_atten (C++ function),
504 adc1_config_width (C++ function), 505 adc1_get_raw (C++ function), 505 ADC1_GPIO10_CHANNEL (C macro), 519 ADC1_GPIO1_CHANNEL (C macro), 519 ADC1_GPIO2_CHANNEL (C macro), 519 ADC1_GPIO3_CHANNEL (C macro), 519 ADC1_GPIO4_CHANNEL (C macro), 519 ADC1_GPIO5_CHANNEL (C macro), 519 ADC1_GPIO6_CHANNEL (C macro), 519 ADC1_GPIO7_CHANNEL (C macro), 519 ADC1_GPIO8_CHANNEL (C macro), 519 ADC1_GPIO9_CHANNEL (C macro), 519

adc1_pad_get_io_num (C++ function), 504 adc1_ulp_enable (C++ function), 506 ADC2_CHANNEL_0 (C++ enumerator), 511 ADC2_CHANNEL_0_GPIO_NUM (C macro), 519 ADC2_CHANNEL_1 (C++ enumerator), 511 ADC2_CHANNEL_1_GPIO_NUM (C macro), 519 ADC2_CHANNEL_2 (C++ enumerator), 511 ADC2_CHANNEL_2_GPIO_NUM (C macro), 519 ADC2_CHANNEL_3 (C++ enumerator), 511 ADC2_CHANNEL_3_GPIO_NUM (C macro), 519 ADC2_CHANNEL_4 (C++ enumerator), 511 ADC2_CHANNEL_4_GPIO_NUM (C macro), 519 ADC2_CHANNEL_5 (C++ enumerator), 511 ADC2_CHANNEL_5_GPIO_NUM (C macro), 519 ADC2_CHANNEL_6 (C++ enumerator), 511 ADC2_CHANNEL_6_GPIO_NUM (C macro), 520 ADC2_CHANNEL_7 (C++ enumerator), 511 ADC2_CHANNEL_7_GPIO_NUM (C macro), 520 ADC2_CHANNEL_8 (C++ enumerator), 511 ADC2_CHANNEL_8_GPIO_NUM (C macro), 520 ADC2_CHANNEL_9 (C++ enumerator), 511 ADC2_CHANNEL_9_GPIO_NUM (C macro), 520 ADC2_CHANNEL_MAX (C++ enumerator), 511 adc2_channel_t (C++ enum), 511 adc2_config_channel_atten (C++ function),
506 adc2_get_raw (C++ function), 507 ADC2_GPIO11_CHANNEL (C macro), 519 ADC2_GPIO12_CHANNEL (C macro), 519 ADC2_GPIO13_CHANNEL (C macro), 519 ADC2_GPIO14_CHANNEL (C macro), 519 ADC2_GPIO15_CHANNEL (C macro), 519 ADC2_GPIO16_CHANNEL (C macro), 519 ADC2_GPIO17_CHANNEL (C macro), 519 ADC2_GPIO18_CHANNEL (C macro), 520 ADC2_GPIO19_CHANNEL (C macro), 520 ADC2_GPIO20_CHANNEL (C macro), 520 adc2_pad_get_io_num (C++ function), 506 adc2_vref_to_gpio (C++ function), 508 ADC_ARB_MODE_FIX (C++ enumerator), 515 ADC_ARB_MODE_LOOP (C++ enumerator), 515 ADC_ARB_MODE_SHIELD (C++ enumerator), 515 ADC_ARBITER_CONFIG_DEFAULT (C macro), 513 adc_arbiter_mode_t (C++ enum), 515 adc_arbiter_t (C++ class), 512 adc_arbiter_t::dig_pri (C++ member), 512 adc_arbiter_t::mode (C++ member), 512

2011

Index

adc_arbiter_t::pwdet_pri (C++ member), ADC_DIGI_FILTER_IIR_16 (C++ enumerator),

512

516

adc_arbiter_t::rtc_pri (C++ member), 512 ADC_DIGI_FILTER_IIR_2 (C++ enumerator), 515

ADC_ATTEN_0db (C macro), 510

ADC_DIGI_FILTER_IIR_4 (C++ enumerator), 516

ADC_ATTEN_11db (C macro), 510

ADC_DIGI_FILTER_IIR_64 (C++ enumerator),

ADC_ATTEN_2_5db (C macro), 510

516

ADC_ATTEN_6db (C macro), 510

ADC_DIGI_FILTER_IIR_8 (C++ enumerator), 516

ADC_ATTEN_DB_0 (C++ enumerator), 514

ADC_DIGI_FILTER_IIR_MAX (C++ enumerator),

ADC_ATTEN_DB_11 (C++ enumerator), 514

516

ADC_ATTEN_DB_2_5 (C++ enumerator), 514

adc_digi_filter_mode_t (C++ enum), 515

ADC_ATTEN_DB_6 (C++ enumerator), 514

adc_digi_filter_t (C++ class), 512

ADC_ATTEN_MAX (C++ enumerator), 514

adc_digi_filter_t::adc_unit (C++ mem-

adc_atten_t (C++ enum), 514

ber), 512

adc_bits_width_t (C++ enum), 514

adc_digi_filter_t::channel (C++ member),

ADC_CHANNEL_0 (C++ enumerator), 513

512

ADC_CHANNEL_1 (C++ enumerator), 513

adc_digi_filter_t::mode (C++ member), 512

ADC_CHANNEL_2 (C++ enumerator), 513

ADC_DIGI_FORMAT_11BIT (C++ enumerator), 515

ADC_CHANNEL_3 (C++ enumerator), 514

ADC_DIGI_FORMAT_12BIT (C++ enumerator), 515

ADC_CHANNEL_4 (C++ enumerator), 514

ADC_DIGI_FORMAT_MAX (C++ enumerator), 515

ADC_CHANNEL_5 (C++ enumerator), 514

adc_digi_init_config_s (C++ class), 509

ADC_CHANNEL_6 (C++ enumerator), 514

adc_digi_init_config_s::adc1_chan_mask

ADC_CHANNEL_7 (C++ enumerator), 514

(C++ member), 509

ADC_CHANNEL_8 (C++ enumerator), 514

adc_digi_init_config_s::adc2_chan_mask

ADC_CHANNEL_9 (C++ enumerator), 514

(C++ member), 509

ADC_CHANNEL_MAX (C++ enumerator), 514

adc_digi_init_config_s::conv_num_each_intr

adc_channel_t (C++ enum), 513

(C++ member), 509

ADC_CONV_ALTER_UNIT (C++ enumerator), 515 adc_digi_init_config_s::max_store_buf_size

ADC_CONV_BOTH_UNIT (C++ enumerator), 514

(C++ member), 509

ADC_CONV_SINGLE_UNIT_1 (C++ enumerator), adc_digi_init_config_t (C++ type), 510

514

adc_digi_initialize (C++ function), 508

ADC_CONV_SINGLE_UNIT_2 (C++ enumerator), ADC_DIGI_MONITOR_HIGH (C++ enumerator), 516

514

ADC_DIGI_MONITOR_IDX0 (C++ enumerator), 516

ADC_CONV_UNIT_MAX (C++ enumerator), 515

ADC_DIGI_MONITOR_IDX1 (C++ enumerator), 516

adc_digi_configuration_t (C++ class), 509 ADC_DIGI_MONITOR_IDX_MAX (C++ enumerator),

adc_digi_configuration_t::adc_pattern

516

(C++ member), 509

adc_digi_monitor_idx_t (C++ enum), 516

adc_digi_configuration_t::conv_limit_enADC_DIGI_MONITOR_LOW (C++ enumerator), 516

(C++ member), 509

ADC_DIGI_MONITOR_MAX (C++ enumerator), 516

adc_digi_configuration_t::conv_limit_nuamdc_digi_monitor_mode_t (C++ enum), 516

(C++ member), 509

adc_digi_monitor_t (C++ class), 513

adc_digi_configuration_t::conv_mode adc_digi_monitor_t::adc_unit (C++ mem-

(C++ member), 509

ber), 513

adc_digi_configuration_t::format (C++ adc_digi_monitor_t::channel (C++ mem-

member), 509

ber), 513

adc_digi_configuration_t::pattern_num adc_digi_monitor_t::mode (C++ member),

(C++ member), 509

513

adc_digi_configuration_t::sample_freq_hazdc_digi_monitor_t::threshold (C++

(C++ member), 509

member), 513

adc_digi_controller_configure (C++ func- adc_digi_output_data_t (C++ class), 512

tion), 509

adc_digi_output_data_t::channel (C++

adc_digi_convert_mode_t (C++ enum), 514

member), 512

adc_digi_deinitialize (C++ function), 508 adc_digi_output_data_t::data (C++ mem-

ADC_DIGI_FILTER_IDX0 (C++ enumerator), 515

ber), 512

ADC_DIGI_FILTER_IDX1 (C++ enumerator), 515 adc_digi_output_data_t::reserved17_31

ADC_DIGI_FILTER_IDX_MAX (C++ enumerator),

(C++ member), 512

515

adc_digi_output_data_t::type2 (C++

adc_digi_filter_idx_t (C++ enum), 515

member), 512

adc_digi_output_data_t::unit (C++ mem-

Espressif Systems

2012

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

ber), 512 adc_digi_output_data_t::val (C++ mem-
ber), 512 adc_digi_output_format_t (C++ enum), 515 ADC_DIGI_OUTPUT_FORMAT_TYPE1 (C++ enu-
merator), 515 ADC_DIGI_OUTPUT_FORMAT_TYPE2 (C++ enu-
merator), 515 adc_digi_pattern_config_t (C++ class), 511 adc_digi_pattern_config_t::atten (C++
member), 511 adc_digi_pattern_config_t::bit_width
(C++ member), 512 adc_digi_pattern_config_t::channel
(C++ member), 511 adc_digi_pattern_config_t::unit (C++
member), 511 adc_digi_read_bytes (C++ function), 508 adc_digi_start (C++ function), 508 adc_digi_stop (C++ function), 508 ADC_ENCODE_11BIT (C++ enumerator), 511 ADC_ENCODE_12BIT (C++ enumerator), 511 ADC_ENCODE_MAX (C++ enumerator), 511 ADC_I2S_DATA_SRC_ADC (C++ enumerator), 516 ADC_I2S_DATA_SRC_IO_SIG (C++ enumerator),
516 ADC_I2S_DATA_SRC_MAX (C++ enumerator), 516 adc_i2s_encode_t (C++ enum), 511 adc_i2s_source_t (C++ enum), 516 ADC_MAX_DELAY (C macro), 510 adc_power_acquire (C++ function), 504 adc_power_off (C++ function), 504 adc_power_on (C++ function), 504 adc_power_release (C++ function), 504 adc_set_clk_div (C++ function), 506 adc_set_data_inv (C++ function), 506 adc_set_data_width (C++ function), 506 ADC_UNIT_1 (C++ enumerator), 513 ADC_UNIT_2 (C++ enumerator), 513 ADC_UNIT_ALTER (C++ enumerator), 513 ADC_UNIT_BOTH (C++ enumerator), 513 ADC_UNIT_MAX (C++ enumerator), 513 adc_unit_t (C++ enum), 513 adc_vref_to_gpio (C++ function), 507 ADC_WIDTH_10Bit (C macro), 510 ADC_WIDTH_11Bit (C macro), 510 ADC_WIDTH_12Bit (C macro), 510 ADC_WIDTH_9Bit (C macro), 510 ADC_WIDTH_BIT_12 (C++ enumerator), 514 ADC_WIDTH_BIT_DEFAULT (C macro), 510 ADC_WIDTH_MAX (C++ enumerator), 514 ADD_DEV_FLUSHABLE_DEV_FLAG (C macro), 191 ADD_DEV_RM_AFTER_PROV_FLAG (C macro), 191 ADD_DEV_START_PROV_NOW_FLAG (C macro),
191 ADV_CHNL_37 (C++ enumerator), 102 ADV_CHNL_38 (C++ enumerator), 102 ADV_CHNL_39 (C++ enumerator), 102

ADV_CHNL_ALL (C++ enumerator), 102 ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY
(C++ enumerator), 102 ADV_FILTER_ALLOW_SCAN_ANY_CON_WLST
(C++ enumerator), 102 ADV_FILTER_ALLOW_SCAN_WLST_CON_ANY
(C++ enumerator), 102 ADV_FILTER_ALLOW_SCAN_WLST_CON_WLST
(C++ enumerator), 102 ADV_TYPE_DIRECT_IND_HIGH (C++ enumerator),
102 ADV_TYPE_DIRECT_IND_LOW (C++ enumerator),
102 ADV_TYPE_IND (C++ enumerator), 102 ADV_TYPE_NONCONN_IND (C++ enumerator), 102 ADV_TYPE_SCAN_IND (C++ enumerator), 102 async_memcpy_config_t (C++ class), 1092 async_memcpy_config_t::backlog (C++
member), 1092 async_memcpy_config_t::flags (C++ mem-
ber), 1092 async_memcpy_config_t::psram_trans_align
(C++ member), 1092 async_memcpy_config_t::sram_trans_align
(C++ member), 1092 ASYNC_MEMCPY_DEFAULT_CONFIG (C macro),
1092 async_memcpy_event_t (C++ class), 1092 async_memcpy_event_t::data (C++ member),
1092 async_memcpy_isr_cb_t (C++ type), 1092 async_memcpy_t (C++ type), 1092
B
BD_ADDR (C++ type), 202 BD_ADDR_LEN (C macro), 190 BLE_ADDR_TYPE_PUBLIC (C++ enumerator), 59 BLE_ADDR_TYPE_RANDOM (C++ enumerator), 59 BLE_ADDR_TYPE_RPA_PUBLIC (C++ enumerator),
59 BLE_ADDR_TYPE_RPA_RANDOM (C++ enumerator),
59 BLE_BIT (C macro), 97 BLE_HCI_UART_H4_ACL (C macro), 156 BLE_HCI_UART_H4_CMD (C macro), 156 BLE_HCI_UART_H4_EVT (C macro), 156 BLE_HCI_UART_H4_NONE (C macro), 156 BLE_HCI_UART_H4_SCO (C macro), 156 BLE_SCAN_DUPLICATE_DISABLE (C++ enumera-
tor), 104 BLE_SCAN_DUPLICATE_ENABLE (C++ enumera-
tor), 104 BLE_SCAN_DUPLICATE_MAX (C++ enumerator),
104 BLE_SCAN_FILTER_ALLOW_ALL (C++ enumera-
tor), 103 BLE_SCAN_FILTER_ALLOW_ONLY_WLST (C++
enumerator), 103

Espressif Systems

2013

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

BLE_SCAN_FILTER_ALLOW_UND_RPA_DIR

CONFIG_ESPTOOLPY_FLASHSIZE, 1038

(C++ enumerator), 103

CONFIG_FEATURE_CACHE_TX_BUF_BIT

(C

BLE_SCAN_FILTER_ALLOW_WLIST_RPA_DIR

macro), 385

(C++ enumerator), 103

CONFIG_FEATURE_FTM_INITIATOR_BIT (C

BLE_SCAN_TYPE_ACTIVE (C++ enumerator), 103

macro), 385

BLE_SCAN_TYPE_PASSIVE (C++ enumerator), 103 CONFIG_FEATURE_FTM_RESPONDER_BIT (C

BLE_UUID128_VAL_LENGTH (C macro), 968

macro), 385

BLE_WL_ADDR_TYPE_PUBLIC (C++ enumerator), CONFIG_FEATURE_WPA3_SAE_BIT (C macro),

59

385

BLE_WL_ADDR_TYPE_RANDOM (C++ enumerator), CONFIG_HEAP_TRACING_STACK_DEPTH

(C

59

macro), 1288

bootloader_fill_random (C++ function), 1339 CONFIG_LWIP_SNTP_UPDATE_DELAY, 1355

bootloader_random_disable (C++ function), CONFIG_VFS_SUPPORT_SELECT, 1066

1339 bootloader_random_enable

(C++

function),

D

1339

dedic_gpio_bundle_config_t (C++ class),

BT_CONTROLLER_INIT_CONFIG_DEFAULT (C

550

macro), 54

dedic_gpio_bundle_config_t::array_size

BT_OCTET32 (C++ type), 202

(C++ member), 550

BT_OCTET32_LEN (C macro), 190

dedic_gpio_bundle_config_t::flags

C

(C++ member), 551 dedic_gpio_bundle_config_t::gpio_array

cap_event_data_t (C++ class), 633

(C++ member), 550

cap_event_data_t::cap_edge (C++ member), dedic_gpio_bundle_config_t::in_en

633

(C++ member), 550

cap_event_data_t::cap_value (C++ mem- dedic_gpio_bundle_config_t::in_invert

ber), 633

(C++ member), 550

cap_isr_cb_t (C++ type), 635

dedic_gpio_bundle_config_t::out_en

CDC_EVENT_LINE_CODING_CHANGED (C++ enu-

(C++ member), 551

merator), 772

dedic_gpio_bundle_config_t::out_invert

CDC_EVENT_LINE_STATE_CHANGED (C++ enu-

(C++ member), 551

merator), 772

dedic_gpio_bundle_handle_t (C++ type), 551

CDC_EVENT_RX (C++ enumerator), 772

dedic_gpio_bundle_read_in (C++ function),

CDC_EVENT_RX_WANTED_CHAR (C++ enumerator),

550

772

dedic_gpio_bundle_read_out (C++ function),

cdcacm_event_line_coding_changed_data_t

550

(C++ class), 771

dedic_gpio_bundle_write (C++ function), 550

cdcacm_event_line_coding_changed_data_td:e:dpi_cl_ignpei_oc_oddeiln_gbundle (C++ function), 550

(C++ member), 771

dedic_gpio_get_in_mask (C++ function), 549

cdcacm_event_line_state_changed_data_t dedic_gpio_get_out_mask (C++ function), 549

(C++ class), 771

dedic_gpio_new_bundle (C++ function), 549

cdcacm_event_line_state_changed_data_t:D:EdFtArULT_HTTP_BUF_SIZE (C macro), 861

(C++ member), 771

DEL_DEV_ADDR_FLAG (C macro), 191

cdcacm_event_line_state_changed_data_t:D:ErLt_sDEV_UUID_FLAG (C macro), 191

(C++ member), 771

DPP_BOOTSTRAP_NFC_URI (C++ enumerator), 451

cdcacm_event_rx_wanted_char_data_t

DPP_BOOTSTRAP_PKEX (C++ enumerator), 451

(C++ class), 770

DPP_BOOTSTRAP_QR_CODE (C++ enumerator), 451

cdcacm_event_rx_wanted_char_data_t::wandtpepd__bcohoatrstrap_type (C++ enum), 451

(C++ member), 771 cdcacm_event_t (C++ class), 771

E

cdcacm_event_t::line_coding_changed_dateaAbortSleep (C++ enumerator), 1178

(C++ member), 771

eBlocked (C++ enumerator), 1178

cdcacm_event_t::line_state_changed_dataeDeleted (C++ enumerator), 1178

(C++ member), 771

EFD_SUPPORT_ISR (C macro), 1076

cdcacm_event_t::rx_wanted_char_data eIncrement (C++ enumerator), 1178

(C++ member), 771

eInvalid (C++ enumerator), 1178

cdcacm_event_t::type (C++ member), 771

EMAC_APPL_CLK_OUT_GPIO (C++ enumerator),

cdcacm_event_type_t (C++ enum), 772

469

Espressif Systems

2014

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

EMAC_CLK_DEFAULT (C++ enumerator), 469

ESP_ADC_CAL_VAL_DEFAULT_VREF (C++ enu-

EMAC_CLK_EXT_IN (C++ enumerator), 469

merator), 518

EMAC_CLK_IN_GPIO (C++ enumerator), 469

ESP_ADC_CAL_VAL_EFUSE_TP (C++ enumerator),

EMAC_CLK_OUT (C++ enumerator), 469

518

EMAC_CLK_OUT_180_GPIO (C++ enumerator), 470 ESP_ADC_CAL_VAL_EFUSE_TP_FIT (C++ enu-

EMAC_CLK_OUT_GPIO (C++ enumerator), 470

merator), 518

emac_rmii_clock_gpio_t (C++ enum), 469

ESP_ADC_CAL_VAL_EFUSE_VREF (C++ enumera-

emac_rmii_clock_mode_t (C++ enum), 469

tor), 518

eNoAction (C++ enumerator), 1178

ESP_ADC_CAL_VAL_MAX (C++ enumerator), 518

eNoTasksWaitingTimeout (C++ enumerator), ESP_ADC_CAL_VAL_NOT_SUPPORTED (C++ enu-

1178

merator), 518

eNotifyAction (C++ enum), 1178

esp_adc_cal_value_t (C++ enum), 518

environment variable

esp_alloc_failed_hook_t (C++ type), 1274

CONFIG_ESPTOOLPY_FLASHSIZE, 1038

ESP_APP_DESC_MAGIC_WORD (C macro), 1084

CONFIG_LWIP_SNTP_UPDATE_DELAY, 1355 esp_app_desc_t (C++ class), 1083

CONFIG_VFS_SUPPORT_SELECT, 1066

esp_app_desc_t::app_elf_sha256 (C++

eReady (C++ enumerator), 1178

member), 1083

eRunning (C++ enumerator), 1178

esp_app_desc_t::date (C++ member), 1083

eSetBits (C++ enumerator), 1178

esp_app_desc_t::idf_ver (C++ member),

eSetValueWithoutOverwrite (C++ enumera-

1083

tor), 1178

esp_app_desc_t::magic_word (C++ member),

eSetValueWithOverwrite (C++ enumerator),

1083

1178

esp_app_desc_t::project_name (C++ mem-

eSleepModeStatus (C++ enum), 1178

ber), 1083

ESP32S3_ERR_HW_CRYPTO_DS_HMAC_FAIL (C esp_app_desc_t::reserv1 (C++ member),

macro), 558

1083

ESP32S3_ERR_HW_CRYPTO_DS_INVALID_DIGESTesp_app_desc_t::reserv2 (C++ member),

(C macro), 558

1083

ESP32S3_ERR_HW_CRYPTO_DS_INVALID_KEY esp_app_desc_t::secure_version (C++

(C macro), 558

member), 1083

ESP32S3_ERR_HW_CRYPTO_DS_INVALID_PADDINeGsp_app_desc_t::time (C++ member), 1083

(C macro), 558

esp_app_desc_t::version (C++ member),

esp_adc_cal_characteristics_t (C++

1083

class), 518

ESP_APP_ID_MAX (C macro), 58

esp_adc_cal_characteristics_t::adc_num ESP_APP_ID_MIN (C macro), 58

(C++ member), 518

esp_apptrace_buffer_get (C++ function),

esp_adc_cal_characteristics_t::atten

1086

(C++ member), 518

esp_apptrace_buffer_put (C++ function),

esp_adc_cal_characteristics_t::bit_width

1086

(C++ member), 518

ESP_APPTRACE_DEST_JTAG (C++ enumerator),

esp_adc_cal_characteristics_t::coeff_a

1088

(C++ member), 518

ESP_APPTRACE_DEST_MAX (C++ enumerator),

esp_adc_cal_characteristics_t::coeff_b

1089

(C++ member), 518

ESP_APPTRACE_DEST_NUM (C++ enumerator),

esp_adc_cal_characteristics_t::high_curve

1089

(C++ member), 518

esp_apptrace_dest_t (C++ enum), 1088

esp_adc_cal_characteristics_t::low_curvEeSP_APPTRACE_DEST_TRAX (C++ enumerator),

(C++ member), 518

1088

esp_adc_cal_characteristics_t::version ESP_APPTRACE_DEST_UART0 (C++ enumerator),

(C++ member), 518

1089

esp_adc_cal_characteristics_t::vref esp_apptrace_down_buffer_config (C++

(C++ member), 518

function), 1085

esp_adc_cal_characterize (C++ function), esp_apptrace_down_buffer_get (C++ func-

517

tion), 1087

esp_adc_cal_check_efuse (C++ function), 517 esp_apptrace_down_buffer_put (C++ func-

esp_adc_cal_get_voltage (C++ function), 517

tion), 1087

esp_adc_cal_raw_to_voltage (C++ function), esp_apptrace_fclose (C++ function), 1087

517

esp_apptrace_flush (C++ function), 1086

Espressif Systems

2015

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_apptrace_flush_nolock (C++ function), 1086
esp_apptrace_fopen (C++ function), 1087 esp_apptrace_fread (C++ function), 1088 esp_apptrace_fseek (C++ function), 1088 esp_apptrace_fstop (C++ function), 1088 esp_apptrace_ftell (C++ function), 1088 esp_apptrace_fwrite (C++ function), 1087 esp_apptrace_host_is_connected (C++
function), 1087 esp_apptrace_init (C++ function), 1085 esp_apptrace_read (C++ function), 1087 esp_apptrace_vprintf (C++ function), 1086 esp_apptrace_vprintf_to (C++ function),
1086 esp_apptrace_write (C++ function), 1086 esp_async_memcpy (C++ function), 1091 esp_async_memcpy_install (C++ function),
1091 esp_async_memcpy_uninstall (C++ function),
1091 esp_attr_control_t (C++ class), 107 esp_attr_control_t::auto_rsp (C++ mem-
ber), 107 esp_attr_desc_t (C++ class), 106 esp_attr_desc_t::length (C++ member), 106 esp_attr_desc_t::max_length (C++ mem-
ber), 106 esp_attr_desc_t::perm (C++ member), 106 esp_attr_desc_t::uuid_length (C++ mem-
ber), 106 esp_attr_desc_t::uuid_p (C++ member), 106 esp_attr_desc_t::value (C++ member), 106 esp_attr_value_t (C++ class), 107 esp_attr_value_t::attr_len (C++ member),
107 esp_attr_value_t::attr_max_len (C++
member), 107 esp_attr_value_t::attr_value (C++ mem-
ber), 107 esp_base_mac_addr_get (C++ function), 1316 esp_base_mac_addr_set (C++ function), 1316 ESP_BD_ADDR_HEX (C macro), 58 ESP_BD_ADDR_LEN (C macro), 58, 152 ESP_BD_ADDR_STR (C macro), 58 esp_bd_addr_t (C++ type), 58, 152 ESP_BLE_AD_MANUFACTURER_SPECIFIC_TYPE
(C++ enumerator), 102 ESP_BLE_AD_TYPE_128SERVICE_DATA (C++
enumerator), 102 ESP_BLE_AD_TYPE_128SOL_SRV_UUID (C++
enumerator), 101 ESP_BLE_AD_TYPE_128SRV_CMPL (C++ enumer-
ator), 101 ESP_BLE_AD_TYPE_128SRV_PART (C++ enumer-
ator), 101 ESP_BLE_AD_TYPE_16SRV_CMPL (C++ enumera-
tor), 101

ESP_BLE_AD_TYPE_16SRV_PART (C++ enumerator), 101
ESP_BLE_AD_TYPE_32SERVICE_DATA (C++ enumerator), 102
ESP_BLE_AD_TYPE_32SOL_SRV_UUID (C++ enumerator), 102
ESP_BLE_AD_TYPE_32SRV_CMPL (C++ enumerator), 101
ESP_BLE_AD_TYPE_32SRV_PART (C++ enumerator), 101
ESP_BLE_AD_TYPE_ADV_INT (C++ enumerator), 101
ESP_BLE_AD_TYPE_APPEARANCE (C++ enumerator), 101
ESP_BLE_AD_TYPE_CHAN_MAP_UPDATE (C++ enumerator), 102
ESP_BLE_AD_TYPE_DEV_CLASS (C++ enumerator), 101
ESP_BLE_AD_TYPE_FLAG (C++ enumerator), 101 ESP_BLE_AD_TYPE_INDOOR_POSITION (C++
enumerator), 102 ESP_BLE_AD_TYPE_INT_RANGE (C++ enumera-
tor), 101 ESP_BLE_AD_TYPE_LE_DEV_ADDR (C++ enumer-
ator), 101 ESP_BLE_AD_TYPE_LE_ROLE (C++ enumerator),
101 ESP_BLE_AD_TYPE_LE_SECURE_CONFIRM
(C++ enumerator), 102 ESP_BLE_AD_TYPE_LE_SECURE_RANDOM (C++
enumerator), 102 ESP_BLE_AD_TYPE_LE_SUPPORT_FEATURE
(C++ enumerator), 102 ESP_BLE_AD_TYPE_NAME_CMPL (C++ enumera-
tor), 101 ESP_BLE_AD_TYPE_NAME_SHORT (C++ enumera-
tor), 101 ESP_BLE_AD_TYPE_PUBLIC_TARGET (C++ enu-
merator), 101 ESP_BLE_AD_TYPE_RANDOM_TARGET (C++ enu-
merator), 101 ESP_BLE_AD_TYPE_SERVICE_DATA (C++ enu-
merator), 101 ESP_BLE_AD_TYPE_SM_OOB_FLAG (C++ enumer-
ator), 101 ESP_BLE_AD_TYPE_SM_TK (C++ enumerator), 101 ESP_BLE_AD_TYPE_SOL_SRV_UUID (C++ enu-
merator), 101 ESP_BLE_AD_TYPE_SPAIR_C256 (C++ enumera-
tor), 102 ESP_BLE_AD_TYPE_SPAIR_R256 (C++ enumera-
tor), 102 ESP_BLE_AD_TYPE_TRANS_DISC_DATA (C++
enumerator), 102 ESP_BLE_AD_TYPE_TX_PWR (C++ enumerator),
101 ESP_BLE_AD_TYPE_URI (C++ enumerator), 102 esp_ble_addr_type_t (C++ enum), 59

Espressif Systems

2016

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_adv_channel_t (C++ enum), 102

macro), 98

ESP_BLE_ADV_DATA_LEN_MAX (C macro), 97

ESP_BLE_ADV_REPORT_EXT_DIRECT_ADV (C

esp_ble_adv_data_t (C++ class), 85

macro), 98

esp_ble_adv_data_t::appearance (C++ ESP_BLE_ADV_REPORT_EXT_SCAN_IND

(C

member), 86

macro), 98

esp_ble_adv_data_t::flag (C++ member), 86 ESP_BLE_ADV_REPORT_EXT_SCAN_RSP

(C

esp_ble_adv_data_t::include_name (C++

macro), 98

member), 85

esp_ble_adv_type_t (C++ enum), 102

esp_ble_adv_data_t::include_txpower ESP_BLE_APP_ENC_KEY_SIZE (C++ enumerator),

(C++ member), 86

103

esp_ble_adv_data_t::manufacturer_len ESP_BLE_APPEARANCE_BLOOD_PRESSURE_ARM

(C++ member), 86

(C macro), 96

esp_ble_adv_data_t::max_interval (C++ ESP_BLE_APPEARANCE_BLOOD_PRESSURE_WRIST

member), 86

(C macro), 96

esp_ble_adv_data_t::min_interval (C++ ESP_BLE_APPEARANCE_CYCLING_CADENCE (C

member), 86

macro), 96

esp_ble_adv_data_t::p_manufacturer_dataESP_BLE_APPEARANCE_CYCLING_COMPUTER (C

(C++ member), 86

macro), 96

esp_ble_adv_data_t::p_service_data

ESP_BLE_APPEARANCE_CYCLING_POWER (C

(C++ member), 86

macro), 96

esp_ble_adv_data_t::p_service_uuid

ESP_BLE_APPEARANCE_CYCLING_SPEED (C

(C++ member), 86

macro), 96

esp_ble_adv_data_t::service_data_len ESP_BLE_APPEARANCE_CYCLING_SPEED_CADENCE

(C++ member), 86

(C macro), 96

esp_ble_adv_data_t::service_uuid_len ESP_BLE_APPEARANCE_GENERIC_BARCODE_SCANNER

(C++ member), 86

(C macro), 96

esp_ble_adv_data_t::set_scan_rsp (C++ ESP_BLE_APPEARANCE_GENERIC_BLOOD_PRESSURE

member), 85

(C macro), 96

esp_ble_adv_data_type (C++ enum), 101

ESP_BLE_APPEARANCE_GENERIC_CLOCK (C

esp_ble_adv_filter_t (C++ enum), 102

macro), 95

ESP_BLE_ADV_FLAG_BREDR_NOT_SPT

(C ESP_BLE_APPEARANCE_GENERIC_COMPUTER (C

macro), 95

macro), 95

ESP_BLE_ADV_FLAG_DMT_CONTROLLER_SPT (C ESP_BLE_APPEARANCE_GENERIC_CONTINUOUS_GLUCOSE_MON

macro), 95

(C macro), 97

ESP_BLE_ADV_FLAG_DMT_HOST_SPT (C macro), ESP_BLE_APPEARANCE_GENERIC_CYCLING (C

95

macro), 96

ESP_BLE_ADV_FLAG_GEN_DISC (C macro), 95 ESP_BLE_APPEARANCE_GENERIC_DISPLAY (C

ESP_BLE_ADV_FLAG_LIMIT_DISC (C macro), 95

macro), 96

ESP_BLE_ADV_FLAG_NON_LIMIT_DISC

(C ESP_BLE_APPEARANCE_GENERIC_EYEGLASSES

macro), 95

(C macro), 96

esp_ble_adv_params_t (C++ class), 85

ESP_BLE_APPEARANCE_GENERIC_GLUCOSE (C

esp_ble_adv_params_t::adv_filter_policy

macro), 96

(C++ member), 85

ESP_BLE_APPEARANCE_GENERIC_HEART_RATE

esp_ble_adv_params_t::adv_int_max

(C macro), 96

(C++ member), 85

ESP_BLE_APPEARANCE_GENERIC_HID

(C

esp_ble_adv_params_t::adv_int_min

macro), 96

(C++ member), 85

ESP_BLE_APPEARANCE_GENERIC_INSULIN_PUMP

esp_ble_adv_params_t::adv_type (C++

(C macro), 97

member), 85

ESP_BLE_APPEARANCE_GENERIC_KEYRING (C

esp_ble_adv_params_t::channel_map

macro), 96

(C++ member), 85

ESP_BLE_APPEARANCE_GENERIC_MEDIA_PLAYER

esp_ble_adv_params_t::own_addr_type

(C macro), 96

(C++ member), 85

ESP_BLE_APPEARANCE_GENERIC_MEDICATION_DELIVERY

esp_ble_adv_params_t::peer_addr (C++

(C macro), 97

member), 85

ESP_BLE_APPEARANCE_GENERIC_OUTDOOR_SPORTS

esp_ble_adv_params_t::peer_addr_type

(C macro), 97

(C++ member), 85

ESP_BLE_APPEARANCE_GENERIC_PERSONAL_MOBILITY_DEVI

ESP_BLE_ADV_REPORT_EXT_ADV_IND

(C

(C macro), 96

Espressif Systems

2017

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

ESP_BLE_APPEARANCE_GENERIC_PHONE (C ESP_BLE_APPEARANCE_THERMOMETER_EAR (C

macro), 95

macro), 96

ESP_BLE_APPEARANCE_GENERIC_PULSE_OXIMETEESRP_BLE_APPEARANCE_UNKNOWN (C macro), 95

(C macro), 96

ESP_BLE_APPEARANCE_WALKING_IN_SHOE (C

ESP_BLE_APPEARANCE_GENERIC_REMOTE (C

macro), 96

macro), 96

ESP_BLE_APPEARANCE_WALKING_ON_HIP (C

ESP_BLE_APPEARANCE_GENERIC_TAG

(C

macro), 96

macro), 96

ESP_BLE_APPEARANCE_WALKING_ON_SHOE (C

ESP_BLE_APPEARANCE_GENERIC_THERMOMETER

macro), 96

(C macro), 96

esp_ble_auth_cmpl_t (C++ class), 90

ESP_BLE_APPEARANCE_GENERIC_WALKING (C esp_ble_auth_cmpl_t::addr_type (C++

macro), 96

member), 90

ESP_BLE_APPEARANCE_GENERIC_WATCH (C esp_ble_auth_cmpl_t::auth_mode (C++

macro), 95

member), 90

ESP_BLE_APPEARANCE_GENERIC_WEIGHT (C esp_ble_auth_cmpl_t::bd_addr (C++ mem-

macro), 96

ber), 90

ESP_BLE_APPEARANCE_HEART_RATE_BELT (C esp_ble_auth_cmpl_t::dev_type (C++

macro), 96

member), 90

ESP_BLE_APPEARANCE_HID_BARCODE_SCANNER esp_ble_auth_cmpl_t::fail_reason (C++

(C macro), 96

member), 90

ESP_BLE_APPEARANCE_HID_CARD_READER (C esp_ble_auth_cmpl_t::key (C++ member), 90

macro), 96

esp_ble_auth_cmpl_t::key_present (C++

ESP_BLE_APPEARANCE_HID_DIGITAL_PEN (C

member), 90

macro), 96

esp_ble_auth_cmpl_t::key_type (C++

ESP_BLE_APPEARANCE_HID_DIGITIZER_TABLET

member), 90

(C macro), 96

esp_ble_auth_cmpl_t::success (C++ mem-

ESP_BLE_APPEARANCE_HID_GAMEPAD

(C

ber), 90

macro), 96

esp_ble_auth_req_t (C++ type), 98

ESP_BLE_APPEARANCE_HID_JOYSTICK

(C esp_ble_bond_dev_t (C++ class), 89

macro), 96

esp_ble_bond_dev_t::bd_addr (C++ mem-

ESP_BLE_APPEARANCE_HID_KEYBOARD

(C

ber), 89

macro), 96

esp_ble_bond_dev_t::bond_key (C++ mem-

ESP_BLE_APPEARANCE_HID_MOUSE (C macro),

ber), 89

96

esp_ble_bond_key_info_t (C++ class), 89

ESP_BLE_APPEARANCE_INSULIN_PEN

(C esp_ble_bond_key_info_t::key_mask

macro), 97

(C++ member), 89

ESP_BLE_APPEARANCE_INSULIN_PUMP_DURABLEe_sPpU_MbPle_bond_key_info_t::pcsrk_key

(C macro), 97

(C++ member), 89

ESP_BLE_APPEARANCE_INSULIN_PUMP_PATCH_PeUsMpP_ble_bond_key_info_t::penc_key

(C macro), 97

(C++ member), 89

ESP_BLE_APPEARANCE_MOBILITY_SCOOTER (C esp_ble_bond_key_info_t::pid_key (C++

macro), 97

member), 89

ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATeIsOpN_ble_confirm_reply (C++ function), 66

(C macro), 97

ESP_BLE_CONN_INT_MAX (C macro), 57

ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATEISOPN__BALNED__CNOANVN_INT_MIN (C macro), 57

(C macro), 97

ESP_BLE_CONN_LATENCY_MAX (C macro), 57

ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATEISOPN__BPLOED_CONN_PARAM_UNDEF (C macro), 57

(C macro), 97

ESP_BLE_CONN_SUP_TOUT_MAX (C macro), 57

ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATEISOPN__BPLOED__CAONNDN__NSAUVP_TOUT_MIN (C macro), 57

(C macro), 97

esp_ble_conn_update_params_t (C++ class),

ESP_BLE_APPEARANCE_POWERED_WHEELCHAIR

87

(C macro), 97

esp_ble_conn_update_params_t::bda

ESP_BLE_APPEARANCE_PULSE_OXIMETER_FINGERTIP (C++ member), 87

(C macro), 96

esp_ble_conn_update_params_t::latency

ESP_BLE_APPEARANCE_PULSE_OXIMETER_WRIST

(C++ member), 87

(C macro), 96

esp_ble_conn_update_params_t::max_int

ESP_BLE_APPEARANCE_SPORTS_WATCH

(C

(C++ member), 87

macro), 95

esp_ble_conn_update_params_t::min_int

Espressif Systems

2018

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 87

(C++ member), 92

esp_ble_conn_update_params_t::timeout esp_ble_ext_scan_params_t::filter_policy

(C++ member), 87

(C++ member), 91

ESP_BLE_CSR_KEY_MASK (C macro), 58

esp_ble_ext_scan_params_t::own_addr_type

esp_ble_duplicate_exceptional_info_type_t (C++ member), 91

(C++ enum), 105

esp_ble_ext_scan_params_t::scan_duplicate

ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_ADD

(C++ member), 92

(C++ enumerator), 105

esp_ble_ext_scan_params_t::uncoded_cfg

ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_CLEAN

(C++ member), 92

(C++ enumerator), 105

esp_ble_gap_add_duplicate_scan_exceptional_device

ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_REMOVE

(C++ function), 65

(C++ enumerator), 105

esp_ble_gap_adv_type_t (C++ type), 99

ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_ADDRe_sLpI_SbTle_gap_all_phys_t (C++ type), 98

(C++ enumerator), 105

esp_ble_gap_cb_param_t (C++ union), 72

ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_ALL_eLsIpS_Tble_gap_cb_param_t::adv_data_cmpl

(C++ enumerator), 105

(C++ member), 72

ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFOe_sApD_Vb_lAeD_DgRap_cb_param_t::adv_data_raw_cmpl

(C++ enumerator), 105

(C++ member), 73

ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFOe_sMpE_SbHl_eB_EgAaCpO_Nc_bT_YpPaEram_t::adv_start_cmpl

(C++ enumerator), 105

(C++ member), 73

ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFOe_sMpE_SbHl_eL_IgNaKp__IcDb_param_t::adv_stop_cmpl

(C++ enumerator), 105

(C++ member), 73

ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFOe_sMpE_SbHl_eP_RgOaVp__ScRbV__pAaDrVam_t::adv_terminate

(C++ enumerator), 105

(C++ member), 74

ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFOe_sMpE_SbHl_eP_RgOaXpY__cSbR_Vp_aArDaVm_t::ble_adv_data_cmpl_evt_par

(C++ enumerator), 105

(C++ class), 75

ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESHe_sBpE_AbClOeN__gTaYpP_Ec_bL_IpSaTram_t::ble_adv_data_cmpl_evt_par

(C++ enumerator), 105

(C++ member), 75

ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESHe_sLpI_NbKl_eI_Dg_aLpI_ScTb_param_t::ble_adv_data_raw_cmpl_evt

(C++ enumerator), 105

(C++ class), 75

ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESHe_sPpR_ObVl_eS_RgVa_pA_DcVb__LpIaSrTam_t::ble_adv_data_raw_cmpl_evt

(C++ enumerator), 105

(C++ member), 75

ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESHe_sPpR_ObXlYe__SgRaVp__AcDbV__pLaIrSaTm_t::ble_adv_start_cmpl_evt_pa

(C++ enumerator), 105

(C++ class), 75

ESP_BLE_ENC_KEY_MASK (C macro), 58

esp_ble_gap_cb_param_t::ble_adv_start_cmpl_evt_pa

ESP_BLE_EVT_CONN_ADV (C++ enumerator), 104

(C++ member), 75

ESP_BLE_EVT_CONN_DIR_ADV (C++ enumerator), esp_ble_gap_cb_param_t::ble_adv_stop_cmpl_evt_par

104

(C++ class), 75

ESP_BLE_EVT_DISC_ADV (C++ enumerator), 104 esp_ble_gap_cb_param_t::ble_adv_stop_cmpl_evt_par

ESP_BLE_EVT_NON_CONN_ADV (C++ enumerator),

(C++ member), 75

104

esp_ble_gap_cb_param_t::ble_adv_terminate_param

ESP_BLE_EVT_SCAN_RSP (C++ enumerator), 104

(C++ class), 75

esp_ble_evt_type_t (C++ enum), 104

esp_ble_gap_cb_param_t::ble_adv_terminate_param::

esp_ble_ext_adv_type_mask_t (C++ type),

(C++ member), 75

98

esp_ble_gap_cb_param_t::ble_adv_terminate_param::

esp_ble_ext_scan_cfg_mask_t (C++ type),

(C++ member), 76

99

esp_ble_gap_cb_param_t::ble_adv_terminate_param::

esp_ble_ext_scan_cfg_t (C++ class), 91

(C++ member), 76

esp_ble_ext_scan_cfg_t::scan_interval esp_ble_gap_cb_param_t::ble_adv_terminate_param::

(C++ member), 91

(C++ member), 75

esp_ble_ext_scan_cfg_t::scan_type

esp_ble_gap_cb_param_t::ble_channel_sel_alg_param

(C++ member), 91

(C++ class), 76

esp_ble_ext_scan_cfg_t::scan_window esp_ble_gap_cb_param_t::ble_channel_sel_alg_param

(C++ member), 91

(C++ member), 76

esp_ble_ext_scan_params_t (C++ class), 91 esp_ble_gap_cb_param_t::ble_channel_sel_alg_param

esp_ble_ext_scan_params_t::cfg_mask

(C++ member), 76

(C++ member), 92

esp_ble_gap_cb_param_t::ble_clear_bond_dev_cmpl_e

esp_ble_ext_scan_params_t::coded_cfg

(C++ class), 76

Espressif Systems

2019

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_gap_cb_param_t::ble_clear_bond_edsepv__bclmep_lg_aepv_tc_bp_apraarma:m:_stt:a:tbulse_local_privacy_cmpl_ev

(C++ member), 76

(C++ class), 78

esp_ble_gap_cb_param_t::ble_ext_adv_dateas_ps_ebtl_ec_mgpalp__ecvbt__ppaarraamm_t::ble_local_privacy_cmpl_ev

(C++ class), 76

(C++ member), 78

esp_ble_gap_cb_param_t::ble_ext_adv_dateas_ps_ebtl_ec_mgpalp__ecvbt__ppaarraamm_:t::s:tbalteu_speriod_adv_add_dev_cm

(C++ member), 76

(C++ class), 78

esp_ble_gap_cb_param_t::ble_ext_adv_repeosrpt__bplaer_agmap_cb_param_t::ble_period_adv_add_dev_cm

(C++ class), 76

(C++ member), 78

esp_ble_gap_cb_param_t::ble_ext_adv_repeosrpt__bplaer_agma:p:_pcabr_apmasram_t::ble_period_adv_clear_dev_

(C++ member), 76

(C++ class), 78

esp_ble_gap_cb_param_t::ble_ext_adv_scaens_pr_sbpl_es_egta_pc_mcpbl__peavrta_mp_atr:a:mble_period_adv_clear_dev_

(C++ class), 76

(C++ member), 78

esp_ble_gap_cb_param_t::ble_ext_adv_scaens_pr_sbpl_es_egta_pc_mcpbl__peavrta_mp_atr:a:mb:l:es_tpaetruisod_adv_create_syn

(C++ member), 76

(C++ class), 78

esp_ble_gap_cb_param_t::ble_ext_adv_sete_scpl_ebalre__cgmappl__cebv_tp_apraarma_mt::ble_period_adv_create_syn

(C++ class), 76

(C++ member), 79

esp_ble_gap_cb_param_t::ble_ext_adv_sete_scpl_ebalre__cgmappl__cebv_tp_apraarma_mt::::sbtlaet_upseriod_adv_remove_dev

(C++ member), 77

(C++ class), 79

esp_ble_gap_cb_param_t::ble_ext_adv_sete_sppa_rbalmes__gcampp_lc_be_vpta_rpaamr_atm::ble_period_adv_remove_dev

(C++ class), 77

(C++ member), 79

esp_ble_gap_cb_param_t::ble_ext_adv_sete_sppa_rbalmes__gcampp_lc_be_vpta_rpaamr_atm::::bsltea_tpuesriod_adv_sync_cance

(C++ member), 77

(C++ class), 79

esp_ble_gap_cb_param_t::ble_ext_adv_sete_srpa_nbdl_ea_dgdarp__ccmbp_lp_aervatm__pta:r:abmle_period_adv_sync_cance

(C++ class), 77

(C++ member), 79

esp_ble_gap_cb_param_t::ble_ext_adv_sete_srpa_nbdl_ea_dgdarp__ccmbp_lp_aervatm__pta:r:abml:e:_spteartiuosd_adv_sync_termi

(C++ member), 77

(C++ class), 79

esp_ble_gap_cb_param_t::ble_ext_adv_sete_srpe_mbolvee__gcampp_lc_be_vpta_rpaamr_atm::ble_period_adv_sync_termi

(C++ class), 77

(C++ member), 79

esp_ble_gap_cb_param_t::ble_ext_adv_sete_srpe_mbolvee__gcampp_lc_be_vpta_rpaamr_atm::::bsltea_tpuesriodic_adv_data_set

(C++ member), 77

(C++ class), 79

esp_ble_gap_cb_param_t::ble_ext_adv_staerstp__cbmlpel__geavpt__cpba_rpaamram_t::ble_periodic_adv_data_set

(C++ class), 77

(C++ member), 79

esp_ble_gap_cb_param_t::ble_ext_adv_staerstp__cbmlpel__geavpt__cpba_rpaamr:a:ms_tta:t:ubsle_periodic_adv_report_p

(C++ member), 77

(C++ class), 79

esp_ble_gap_cb_param_t::ble_ext_adv_stoeps_pc_mbplle__egvatp__pcabr_apmaram_t::ble_periodic_adv_report_p

(C++ class), 77

(C++ member), 79

esp_ble_gap_cb_param_t::ble_ext_adv_stoeps_pc_mbplle__egvatp__pcabr_apma:r:asmt_att:u:sble_periodic_adv_set_para

(C++ member), 77

(C++ class), 79

esp_ble_gap_cb_param_t::ble_ext_conn_paersapm_sb_lsee_tg_acpm_pclb__ppaarraamm_t::ble_periodic_adv_set_para

(C++ class), 77

(C++ member), 79

esp_ble_gap_cb_param_t::ble_ext_conn_paersapm_sb_lsee_tg_acpm_pclb__ppaarraamm:_:ts:t:abtlues_periodic_adv_start_cm

(C++ member), 77

(C++ class), 79

esp_ble_gap_cb_param_t::ble_ext_scan_steasrpt__bclmep_lg_appa_rcabm_param_t::ble_periodic_adv_start_cm

(C++ class), 77

(C++ member), 80

esp_ble_gap_cb_param_t::ble_ext_scan_steasrpt__bclmep_lg_appa_rcabm_:p:asrtaamt_uts::ble_periodic_adv_stop_cmp

(C++ member), 78

(C++ class), 80

esp_ble_gap_cb_param_t::ble_ext_scan_steospp__cbmlpel__gpaapr_acmb_param_t::ble_periodic_adv_stop_cmp

(C++ class), 78

(C++ member), 80

esp_ble_gap_cb_param_t::ble_ext_scan_steospp__cbmlpel__gpaapr_acmb:_:psatraatmu_st::ble_periodic_adv_sync_est

(C++ member), 78

(C++ class), 80

esp_ble_gap_cb_param_t::ble_get_bond_deevs_pc_mbplle__egvatp__pcabr_apmaram_t::ble_periodic_adv_sync_est

(C++ class), 78

(C++ member), 80

esp_ble_gap_cb_param_t::ble_get_bond_deevs_pc_mbplle__egvatp__pcabr_apma:r:abmo_ntd:_:dbelve_periodic_adv_sync_est

(C++ member), 78

(C++ member), 80

esp_ble_gap_cb_param_t::ble_get_bond_deevs_pc_mbplle__egvatp__pcabr_apma:r:adme_vt_:n:ubmle_periodic_adv_sync_est

(C++ member), 78

(C++ member), 80

esp_ble_gap_cb_param_t::ble_get_bond_deevs_pc_mbplle__egvatp__pcabr_apma:r:asmt_att:u:sble_periodic_adv_sync_est

(C++ member), 78

(C++ member), 80

Espressif Systems

2020

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_gap_cb_param_t::ble_periodic_adevs_ps_ybnlce__egsatpa_bc_bp_apraarma:m:_pte:r:ibolde__asdcva_ni_nrteeqr_vraelceived_par

(C++ member), 80

(C++ member), 82

esp_ble_gap_cb_param_t::ble_periodic_adevs_ps_ybnlce__egsatpa_bc_bp_apraarma:m:_sti:d:ble_scan_req_received_par

(C++ member), 80

(C++ member), 82

esp_ble_gap_cb_param_t::ble_periodic_adevs_ps_ybnlce__egsatpa_bc_bp_apraarma:m:_stt:a:tbulse_scan_req_received_par

(C++ member), 80

(C++ member), 82

esp_ble_gap_cb_param_t::ble_periodic_adevs_ps_ybnlce__egsatpa_bc_bp_apraarma:m:_sty:n:cb_lhea_nsdclaen_result_evt_param

(C++ member), 80

(C++ class), 82

esp_ble_gap_cb_param_t::ble_periodic_adevs_ps_ybnlce__lgoaspt__cpba_rpaamram_t::ble_scan_result_evt_param

(C++ class), 80

(C++ member), 82

esp_ble_gap_cb_param_t::ble_periodic_adevs_ps_ybnlce__lgoaspt__cpba_rpaamr:a:ms_ytn:c:_bhlaen_dslcean_result_evt_param

(C++ member), 80

(C++ member), 82

esp_ble_gap_cb_param_t::ble_phy_update_ecsmpp_lb_lpea_rgaamp_cb_param_t::ble_scan_result_evt_param

(C++ class), 80

(C++ member), 82

esp_ble_gap_cb_param_t::ble_phy_update_ecsmpp_lb_lpea_rgaamp:_:cbbd_aparam_t::ble_scan_result_evt_param

(C++ member), 80

(C++ member), 82

esp_ble_gap_cb_param_t::ble_phy_update_ecsmpp_lb_lpea_rgaamp:_:crbx__ppahryam_t::ble_scan_result_evt_param

(C++ member), 81

(C++ member), 82

esp_ble_gap_cb_param_t::ble_phy_update_ecsmpp_lb_lpea_rgaamp:_:csbt_aptaursam_t::ble_scan_result_evt_param

(C++ member), 80

(C++ member), 82

esp_ble_gap_cb_param_t::ble_phy_update_ecsmpp_lb_lpea_rgaamp:_:ctbx__ppahryam_t::ble_scan_result_evt_param

(C++ member), 80

(C++ member), 82

esp_ble_gap_cb_param_t::ble_pkt_data_leensgpt_hb_lcem_pgla_pe_vctb__ppaarraamm_t::ble_scan_result_evt_param

(C++ class), 81

(C++ member), 82

esp_ble_gap_cb_param_t::ble_pkt_data_leensgpt_hb_lcem_pgla_pe_vctb__ppaarraamm:_:tp:a:rbalmes_scan_result_evt_param

(C++ member), 81

(C++ member), 82

esp_ble_gap_cb_param_t::ble_pkt_data_leensgpt_hb_lcem_pgla_pe_vctb__ppaarraamm:_:ts:t:abtlues_scan_result_evt_param

(C++ member), 81

(C++ member), 82

esp_ble_gap_cb_param_t::ble_read_phy_cmepslp__ebvlte__pgaarpa_mcb_param_t::ble_scan_result_evt_param

(C++ class), 81

(C++ member), 82

esp_ble_gap_cb_param_t::ble_read_phy_cmepslp__ebvlte__pgaarpa_mc:b:_bpdaaram_t::ble_scan_result_evt_param

(C++ member), 81

(C++ member), 82

esp_ble_gap_cb_param_t::ble_read_phy_cmepslp__ebvlte__pgaarpa_mc:b:_rpxa_rpahmy_t::ble_scan_rsp_data_cmpl_ev

(C++ member), 81

(C++ class), 82

esp_ble_gap_cb_param_t::ble_read_phy_cmepslp__ebvlte__pgaarpa_mc:b:_sptaartaums_t::ble_scan_rsp_data_cmpl_ev

(C++ member), 81

(C++ member), 83

esp_ble_gap_cb_param_t::ble_read_phy_cmepslp__ebvlte__pgaarpa_mc:b:_tpxa_rpahmy_t::ble_scan_rsp_data_raw_cmp

(C++ member), 81

(C++ class), 83

esp_ble_gap_cb_param_t::ble_read_rssi_cemsppl__belvet__gpaapr_acmb_param_t::ble_scan_rsp_data_raw_cmp

(C++ class), 81

(C++ member), 83

esp_ble_gap_cb_param_t::ble_read_rssi_cemsppl__belvet__gpaapr_acmb:_:praermaomt_et_:a:dbdlre_scan_start_cmpl_evt_p

(C++ member), 81

(C++ class), 83

esp_ble_gap_cb_param_t::ble_read_rssi_cemsppl__belvet__gpaapr_acmb:_:prasrsaim_t::ble_scan_start_cmpl_evt_p

(C++ member), 81

(C++ member), 83

esp_ble_gap_cb_param_t::ble_read_rssi_cemsppl__belvet__gpaapr_acmb:_:psatraatmu_st::ble_scan_stop_cmpl_evt_pa

(C++ member), 81

(C++ class), 83

esp_ble_gap_cb_param_t::ble_remove_bonde_sdpe_vb_lcem_pgla_pe_vctb__ppaarraamm_t::ble_scan_stop_cmpl_evt_pa

(C++ class), 81

(C++ member), 83

esp_ble_gap_cb_param_t::ble_remove_bonde_sdpe_vb_lcem_pgla_pe_vctb__ppaarraamm:_:tb:d:_balded_rsecurity

(C++ member), 81

(C++ member), 73

esp_ble_gap_cb_param_t::ble_remove_bonde_sdpe_vb_lcem_pgla_pe_vctb__ppaarraamm:_:ts:t:abtlues_set_channels

(C++ member), 81

(C++ member), 73

esp_ble_gap_cb_param_t::ble_scan_param_ecsmpp_lb_leev_tg_appa_rcabm_param_t::ble_set_channels_evt_para

(C++ class), 81

(C++ class), 83

esp_ble_gap_cb_param_t::ble_scan_param_ecsmpp_lb_leev_tg_appa_rcabm_:p:asrtaamt_uts::ble_set_channels_evt_para

(C++ member), 82

(C++ member), 83

esp_ble_gap_cb_param_t::ble_scan_req_reecsepi_vbelde__pgaarpa_mcb_param_t::ble_set_ext_scan_params_c

(C++ class), 82

(C++ class), 83

Espressif Systems

2021

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_gap_cb_param_t::ble_set_ext_scaens_pp_abrlaem_sg_acpm_pclb__ppaarraamm:_:ts:t:aetxuts_adv_set_params

(C++ member), 83

(C++ member), 73

esp_ble_gap_cb_param_t::ble_set_perf_deefs_pp_hbyl_ec_mgpalp__ecvbt__ppaarraamm_t::ext_adv_set_rand_addr

(C++ class), 83

(C++ member), 73

esp_ble_gap_cb_param_t::ble_set_perf_deefs_pp_hbyl_ec_mgpalp__ecvbt__ppaarraamm_:t::s:teaxttu_sadv_start

(C++ member), 84

(C++ member), 74

esp_ble_gap_cb_param_t::ble_set_perf_pheys_pc_mbplle__egvatp__pcabr_apmaram_t::ext_adv_stop

(C++ class), 84

(C++ member), 74

esp_ble_gap_cb_param_t::ble_set_perf_pheys_pc_mbplle__egvatp__pcabr_apma:r:asmt_att:u:sext_conn_params_set

(C++ member), 84

(C++ member), 74

esp_ble_gap_cb_param_t::ble_set_rand_cmepslp__ebvlte__pgaarpa_mcb_param_t::ext_scan_start

(C++ class), 84

(C++ member), 74

esp_ble_gap_cb_param_t::ble_set_rand_cmepslp__ebvlte__pgaarpa_mc:b:_sptaartaums_t::ext_scan_stop

(C++ member), 84

(C++ member), 74

esp_ble_gap_cb_param_t::ble_update_conne_sppa_rbalmes__geavpt__cpba_rpaamram_t::get_bond_dev_cmpl

(C++ class), 84

(C++ member), 73

esp_ble_gap_cb_param_t::ble_update_conne_sppa_rbalmes__geavpt__cpba_rpaamr:a:mb_dta::local_privacy_cmpl

(C++ member), 84

(C++ member), 73

esp_ble_gap_cb_param_t::ble_update_conne_sppa_rbalmes__geavpt__cpba_rpaamr:a:mc_otn:n:_pienrtiod_adv_add_dev

(C++ member), 84

(C++ member), 74

esp_ble_gap_cb_param_t::ble_update_conne_sppa_rbalmes__geavpt__cpba_rpaamr:a:ml_att:e:npceyriod_adv_clear_dev

(C++ member), 84

(C++ member), 74

esp_ble_gap_cb_param_t::ble_update_conne_sppa_rbalmes__geavpt__cpba_rpaamr:a:mm_atx:_:ipnetriod_adv_create_sync

(C++ member), 84

(C++ member), 74

esp_ble_gap_cb_param_t::ble_update_conne_sppa_rbalmes__geavpt__cpba_rpaamr:a:mm_itn:_:ipnetriod_adv_data_set

(C++ member), 84

(C++ member), 74

esp_ble_gap_cb_param_t::ble_update_conne_sppa_rbalmes__geavpt__cpba_rpaamr:a:ms_tta:t:upseriod_adv_remove_dev

(C++ member), 84

(C++ member), 74

esp_ble_gap_cb_param_t::ble_update_conne_sppa_rbalmes__geavpt__cpba_rpaamr:a:mt_itm:e:opuetriod_adv_report

(C++ member), 84

(C++ member), 75

esp_ble_gap_cb_param_t::ble_update_dupleiscpa_tbel_ee_xgcaepp_tcibo_npaalr_almi_stt:_:cpmeprli_oedv_ta_dpva_rsatmart

(C++ class), 84

(C++ member), 74

esp_ble_gap_cb_param_t::ble_update_dupleiscpa_tbel_ee_xgcaepp_tcibo_npaalr_almi_stt:_:cpmeprli_oedv_ta_dpva_rsatmo:p:device_inf

(C++ member), 85

(C++ member), 74

esp_ble_gap_cb_param_t::ble_update_dupleiscpa_tbel_ee_xgcaepp_tcibo_npaalr_almi_stt:_:cpmeprli_oedv_ta_dpva_rsaymn:c:_lceanngctehl

(C++ member), 84

(C++ member), 74

esp_ble_gap_cb_param_t::ble_update_dupleiscpa_tbel_ee_xgcaepp_tcibo_npaalr_almi_stt:_:cpmeprli_oedv_ta_dpva_rsaymn:c:_stteartmus

(C++ member), 84

(C++ member), 74

esp_ble_gap_cb_param_t::ble_update_dupleiscpa_tbel_ee_xgcaepp_tcibo_npaalr_almi_stt:_:cpmeprli_oedvitc__paadrva_ms:y:nscu_becsotdaeb

(C++ member), 84

(C++ member), 75

esp_ble_gap_cb_param_t::ble_update_whiteeslpi_sbtl_ec_mgpalp__ecvbt__ppaarraamm_t::periodic_adv_sync_lost

(C++ class), 85

(C++ member), 75

esp_ble_gap_cb_param_t::ble_update_whiteeslpi_sbtl_ec_mgpalp__ecvbt__ppaarraamm_:t::s:tpaetruosid_adv_set_params

(C++ member), 85

(C++ member), 74

esp_ble_gap_cb_param_t::ble_update_whiteeslpi_sbtl_ec_mgpalp__ecvbt__ppaarraamm_:t::w:lp_hoyp_ruaptdiaotne

(C++ member), 85

(C++ member), 75

esp_ble_gap_cb_param_t::channel_sel_algesp_ble_gap_cb_param_t::pkt_data_lenth_cmpl

(C++ member), 74

(C++ member), 73

esp_ble_gap_cb_param_t::clear_bond_dev_ecsmpp_lble_gap_cb_param_t::read_phy (C++

(C++ member), 73

member), 73

esp_ble_gap_cb_param_t::ext_adv_clear esp_ble_gap_cb_param_t::read_rssi_cmpl

(C++ member), 74

(C++ member), 73

esp_ble_gap_cb_param_t::ext_adv_data_seetsp_ble_gap_cb_param_t::remove_bond_dev_cmpl

(C++ member), 74

(C++ member), 73

esp_ble_gap_cb_param_t::ext_adv_remove esp_ble_gap_cb_param_t::scan_param_cmpl

(C++ member), 74

(C++ member), 72

esp_ble_gap_cb_param_t::ext_adv_report esp_ble_gap_cb_param_t::scan_req_received

(C++ member), 75

(C++ member), 74

Espressif Systems

2022

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_gap_cb_param_t::scan_rsp_data_cmpl (C++ member), 92

(C++ member), 72

esp_ble_gap_conn_params_t::scan_interval

esp_ble_gap_cb_param_t::scan_rsp_data_raw_cmpl(C++ member), 92

(C++ member), 73

esp_ble_gap_conn_params_t::scan_window

esp_ble_gap_cb_param_t::scan_rsp_set

(C++ member), 92

(C++ member), 74

esp_ble_gap_conn_params_t::supervision_timeout

esp_ble_gap_cb_param_t::scan_rst (C++

(C++ member), 92

member), 72

esp_ble_gap_disconnect (C++ function), 67

esp_ble_gap_cb_param_t::scan_start_cmplESP_BLE_GAP_EXT_ADV_DATA_COMPLETE (C

(C++ member), 73

macro), 98

esp_ble_gap_cb_param_t::scan_stop_cmpl ESP_BLE_GAP_EXT_ADV_DATA_INCOMPLETE (C

(C++ member), 73

macro), 98

esp_ble_gap_cb_param_t::set_ext_scan_paersapm_sble_gap_ext_adv_data_status_t

(C++ member), 74

(C++ type), 99

esp_ble_gap_cb_param_t::set_perf_def_phEySP_BLE_GAP_EXT_ADV_DATA_TRUNCATED (C

(C++ member), 73

macro), 98

esp_ble_gap_cb_param_t::set_perf_phy esp_ble_gap_ext_adv_params_t (C++ class),

(C++ member), 73

90

esp_ble_gap_cb_param_t::set_rand_addr_cemsppl_ble_gap_ext_adv_params_t::channel_map

(C++ member), 73

(C++ member), 91

esp_ble_gap_cb_param_t::update_conn_pareasmps_ble_gap_ext_adv_params_t::filter_policy

(C++ member), 73

(C++ member), 91

esp_ble_gap_cb_param_t::update_duplicatees_pe_xbcleep_tgiaopn_aelx_tl_iasdtv__cpmaprlams_t::interval_max

(C++ member), 73

(C++ member), 91

esp_ble_gap_cb_param_t::update_whitelisets_pc_mbplle_gap_ext_adv_params_t::interval_min

(C++ member), 73

(C++ member), 91

esp_ble_gap_clean_duplicate_scan_excepteisopn_abll_el_igsatp_ext_adv_params_t::max_skip

(C++ function), 65

(C++ member), 91

esp_ble_gap_clear_rand_addr (C++ func- esp_ble_gap_ext_adv_params_t::own_addr_type

tion), 63

(C++ member), 91

esp_ble_gap_clear_whitelist (C++ func- esp_ble_gap_ext_adv_params_t::peer_addr

tion), 63

(C++ member), 91

esp_ble_gap_config_adv_data (C++ func- esp_ble_gap_ext_adv_params_t::peer_addr_type

tion), 61

(C++ member), 91

esp_ble_gap_config_adv_data_raw (C++ esp_ble_gap_ext_adv_params_t::primary_phy

function), 64

(C++ member), 91

esp_ble_gap_config_ext_adv_data_raw esp_ble_gap_ext_adv_params_t::scan_req_notif

(C++ function), 69

(C++ member), 91

esp_ble_gap_config_ext_scan_rsp_data_raewsp_ble_gap_ext_adv_params_t::secondary_phy

(C++ function), 69

(C++ member), 91

esp_ble_gap_config_local_icon (C++ func- esp_ble_gap_ext_adv_params_t::sid

tion), 63

(C++ member), 91

esp_ble_gap_config_local_privacy (C++ esp_ble_gap_ext_adv_params_t::tx_power

function), 63

(C++ member), 91

esp_ble_gap_config_periodic_adv_data_raewsp_ble_gap_ext_adv_params_t::type

(C++ function), 70

(C++ member), 91

esp_ble_gap_config_scan_rsp_data_raw esp_ble_gap_ext_adv_reprot_t (C++ class),

(C++ function), 64

93

esp_ble_gap_conn_params_t (C++ class), 92 esp_ble_gap_ext_adv_reprot_t::addr

esp_ble_gap_conn_params_t::interval_max

(C++ member), 93

(C++ member), 92

esp_ble_gap_ext_adv_reprot_t::addr_type

esp_ble_gap_conn_params_t::interval_min

(C++ member), 93

(C++ member), 92

esp_ble_gap_ext_adv_reprot_t::adv_data

esp_ble_gap_conn_params_t::latency

(C++ member), 94

(C++ member), 92

esp_ble_gap_ext_adv_reprot_t::adv_data_len

esp_ble_gap_conn_params_t::max_ce_len

(C++ member), 94

(C++ member), 92

esp_ble_gap_ext_adv_reprot_t::data_status

esp_ble_gap_conn_params_t::min_ce_len

(C++ member), 94

Espressif Systems

2023

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_gap_ext_adv_reprot_t::dir_addr esp_ble_gap_periodic_adv_params_t::interval_min

(C++ member), 94

(C++ member), 93

esp_ble_gap_ext_adv_reprot_t::dir_addr_etsypp_eble_gap_periodic_adv_params_t::properties

(C++ member), 93

(C++ member), 93

esp_ble_gap_ext_adv_reprot_t::event_typeesp_ble_gap_periodic_adv_remove_dev_from_list

(C++ member), 93

(C++ function), 71

esp_ble_gap_ext_adv_reprot_t::per_adv_ienstpe_rbvlael_gap_periodic_adv_report_t

(C++ member), 93

(C++ class), 94

esp_ble_gap_ext_adv_reprot_t::primary_pehsyp_ble_gap_periodic_adv_report_t::data

(C++ member), 93

(C++ member), 94

esp_ble_gap_ext_adv_reprot_t::rssi

esp_ble_gap_periodic_adv_report_t::data_length

(C++ member), 93

(C++ member), 94

esp_ble_gap_ext_adv_reprot_t::secondly_epshpy_ble_gap_periodic_adv_report_t::data_status

(C++ member), 93

(C++ member), 94

esp_ble_gap_ext_adv_reprot_t::sid

esp_ble_gap_periodic_adv_report_t::rssi

(C++ member), 93

(C++ member), 94

esp_ble_gap_ext_adv_reprot_t::tx_power esp_ble_gap_periodic_adv_report_t::sync_handle

(C++ member), 93

(C++ member), 94

esp_ble_gap_ext_adv_set_clear (C++ func- esp_ble_gap_periodic_adv_report_t::tx_power

tion), 69

(C++ member), 94

esp_ble_gap_ext_adv_set_params (C++ esp_ble_gap_periodic_adv_set_params

function), 68

(C++ function), 69

esp_ble_gap_ext_adv_set_rand_addr

esp_ble_gap_periodic_adv_start (C++

(C++ function), 68

function), 70

esp_ble_gap_ext_adv_set_remove (C++ esp_ble_gap_periodic_adv_stop (C++ func-

function), 69

tion), 70

esp_ble_gap_ext_adv_start (C++ function), esp_ble_gap_periodic_adv_sync_cancel

69

(C++ function), 71

esp_ble_gap_ext_adv_stop (C++ function), 69 esp_ble_gap_periodic_adv_sync_estab_t

esp_ble_gap_ext_adv_t (C++ class), 92

(C++ class), 94

esp_ble_gap_ext_adv_t::duration (C++ esp_ble_gap_periodic_adv_sync_estab_t::addr_type

member), 92

(C++ member), 94

esp_ble_gap_ext_adv_t::instance (C++ esp_ble_gap_periodic_adv_sync_estab_t::adv_addr

member), 92

(C++ member), 94

esp_ble_gap_ext_adv_t::max_events

esp_ble_gap_periodic_adv_sync_estab_t::adv_clk_ac

(C++ member), 92

(C++ member), 94

ESP_BLE_GAP_EXT_SCAN_CFG_CODE_MASK (C esp_ble_gap_periodic_adv_sync_estab_t::adv_phy

macro), 98

(C++ member), 94

ESP_BLE_GAP_EXT_SCAN_CFG_UNCODE_MASK esp_ble_gap_periodic_adv_sync_estab_t::period_adv

(C macro), 98

(C++ member), 94

esp_ble_gap_get_local_used_addr (C++ esp_ble_gap_periodic_adv_sync_estab_t::sid

function), 64

(C++ member), 94

esp_ble_gap_get_whitelist_size (C++ esp_ble_gap_periodic_adv_sync_estab_t::status

function), 63

(C++ member), 94

ESP_BLE_GAP_NO_PREFER_RECEIVE_PHY (C esp_ble_gap_periodic_adv_sync_estab_t::sync_handl

macro), 97

(C++ member), 94

ESP_BLE_GAP_NO_PREFER_TRANSMIT_PHY (C esp_ble_gap_periodic_adv_sync_params_t

macro), 97

(C++ class), 93

esp_ble_gap_periodic_adv_add_dev_to_lisetsp_ble_gap_periodic_adv_sync_params_t::addr

(C++ function), 71

(C++ member), 93

esp_ble_gap_periodic_adv_clear_dev

esp_ble_gap_periodic_adv_sync_params_t::addr_type

(C++ function), 71

(C++ member), 93

esp_ble_gap_periodic_adv_create_sync esp_ble_gap_periodic_adv_sync_params_t::filter_po

(C++ function), 70

(C++ member), 93

esp_ble_gap_periodic_adv_params_t

esp_ble_gap_periodic_adv_sync_params_t::sid

(C++ class), 92

(C++ member), 93

esp_ble_gap_periodic_adv_params_t::inteersvpa_lb_lmea_xgap_periodic_adv_sync_params_t::skip

(C++ member), 93

(C++ member), 93

Espressif Systems

2024

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_gap_periodic_adv_sync_params_t::sync_t(Cimmeaocruot), 97

(C++ member), 93

ESP_BLE_GAP_SET_EXT_ADV_PROP_MASK (C

esp_ble_gap_periodic_adv_sync_terminate

macro), 97

(C++ function), 71

ESP_BLE_GAP_SET_EXT_ADV_PROP_NONCONN_NONSCANNABLE

ESP_BLE_GAP_PHY_1M (C macro), 97

(C macro), 97

ESP_BLE_GAP_PHY_1M_PREF_MASK (C macro), ESP_BLE_GAP_SET_EXT_ADV_PROP_SCANNABLE

98

(C macro), 97

ESP_BLE_GAP_PHY_2M (C macro), 97

esp_ble_gap_set_ext_scan_params (C++

ESP_BLE_GAP_PHY_2M_PREF_MASK (C macro),

function), 70

98

esp_ble_gap_set_pkt_data_len (C++ func-

ESP_BLE_GAP_PHY_CODED (C macro), 97

tion), 62

ESP_BLE_GAP_PHY_CODED_PREF_MASK

(C esp_ble_gap_set_prefer_conn_params

macro), 98

(C++ function), 63

esp_ble_gap_phy_mask_t (C++ type), 98

esp_ble_gap_set_prefered_default_phy

ESP_BLE_GAP_PHY_OPTIONS_NO_PREF

(C

(C++ function), 68

macro), 98

esp_ble_gap_set_prefered_phy (C++ func-

ESP_BLE_GAP_PHY_OPTIONS_PREF_S2_CODING

tion), 68

(C macro), 98

esp_ble_gap_set_rand_addr (C++ function),

ESP_BLE_GAP_PHY_OPTIONS_PREF_S8_CODING

62

(C macro), 98

esp_ble_gap_set_scan_params (C++ func-

esp_ble_gap_phy_t (C++ type), 98

tion), 62

esp_ble_gap_prefer_ext_connect_params_seestp_ble_gap_set_security_param (C++

(C++ function), 71

function), 65

esp_ble_gap_prefer_phy_options_t (C++ esp_ble_gap_start_advertising (C++ func-

type), 98

tion), 62

ESP_BLE_GAP_PRI_PHY_1M (C macro), 98

esp_ble_gap_start_ext_scan (C++ function),

ESP_BLE_GAP_PRI_PHY_CODED (C macro), 98

70

esp_ble_gap_pri_phy_t (C++ type), 98

esp_ble_gap_start_scanning (C++ function),

esp_ble_gap_read_phy (C++ function), 68

62

esp_ble_gap_read_rssi (C++ function), 65

esp_ble_gap_stop_advertising (C++ func-

esp_ble_gap_register_callback (C++ func-

tion), 62

tion), 61

esp_ble_gap_stop_ext_scan (C++ function),

esp_ble_gap_remove_duplicate_scan_exceptional_7d0evice

(C++ function), 65

esp_ble_gap_stop_scanning (C++ function),

esp_ble_gap_security_rsp (C++ function), 66

62

esp_ble_gap_set_device_name (C++ func- ESP_BLE_GAP_SYNC_POLICY_BY_ADV_INFO (C

tion), 64

macro), 98

ESP_BLE_GAP_SET_EXT_ADV_PROP_ANON_ADV ESP_BLE_GAP_SYNC_POLICY_BY_PERIODIC_LIST

(C macro), 97

(C macro), 98

ESP_BLE_GAP_SET_EXT_ADV_PROP_CONNECTABLeEsp_ble_gap_sync_t (C++ type), 99

(C macro), 97

esp_ble_gap_update_conn_params (C++

ESP_BLE_GAP_SET_EXT_ADV_PROP_DIRECTED

function), 62

(C macro), 97

esp_ble_gap_update_whitelist (C++ func-

ESP_BLE_GAP_SET_EXT_ADV_PROP_HD_DIRECTED

tion), 63

(C macro), 97

esp_ble_gattc_app_register (C++ function),

ESP_BLE_GAP_SET_EXT_ADV_PROP_INCLUDE_TX_PWR 129

(C macro), 97

esp_ble_gattc_app_unregister (C++ func-

ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY (C

tion), 129

macro), 97

esp_ble_gattc_aux_open (C++ function), 129

ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_HD_eDsIpR_ble_gattc_cache_assoc (C++ function),

(C macro), 97

135

ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_INDesp_ble_gattc_cache_clean (C++ function),

(C macro), 97

136

ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_LD_eDsIpR_ble_gattc_cache_get_addr_list

(C macro), 97

(C++ function), 136

ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_NONeCsOpN_Nble_gattc_cache_refresh (C++ func-

(C macro), 97

tion), 135

ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_SCAeNsp_ble_gattc_cb_param_t (C++ union), 136

Espressif Systems

2025

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_gattc_cb_param_t::cfg_mtu

esp_ble_gattc_cb_param_t::gattc_disconnect_evt_pa

(C++ member), 136

(C++ member), 139

esp_ble_gattc_cb_param_t::close (C++ esp_ble_gattc_cb_param_t::gattc_disconnect_evt_pa

member), 136

(C++ member), 139

esp_ble_gattc_cb_param_t::congest

esp_ble_gattc_cb_param_t::gattc_exec_cmpl_evt_par

(C++ member), 137

(C++ class), 139

esp_ble_gattc_cb_param_t::connect

esp_ble_gattc_cb_param_t::gattc_exec_cmpl_evt_par

(C++ member), 137

(C++ member), 139

esp_ble_gattc_cb_param_t::dis_srvc_cmplesp_ble_gattc_cb_param_t::gattc_exec_cmpl_evt_par

(C++ member), 137

(C++ member), 139

esp_ble_gattc_cb_param_t::disconnect esp_ble_gattc_cb_param_t::gattc_get_addr_list_evt

(C++ member), 137

(C++ class), 139

esp_ble_gattc_cb_param_t::exec_cmpl esp_ble_gattc_cb_param_t::gattc_get_addr_list_evt

(C++ member), 137

(C++ member), 139

esp_ble_gattc_cb_param_t::gattc_cfg_mtue_sepv_tb_lpea_rgaamttc_cb_param_t::gattc_get_addr_list_evt

(C++ class), 137

(C++ member), 139

esp_ble_gattc_cb_param_t::gattc_cfg_mtue_sepv_tb_lpea_rgaamt:t:cc_ocnbn__piadram_t::gattc_get_addr_list_evt

(C++ member), 137

(C++ member), 139

esp_ble_gattc_cb_param_t::gattc_cfg_mtue_sepv_tb_lpea_rgaamt:t:cm_tcub_param_t::gattc_notify_evt_param

(C++ member), 137

(C++ class), 139

esp_ble_gattc_cb_param_t::gattc_cfg_mtue_sepv_tb_lpea_rgaamt:t:cs_tcabt_upsaram_t::gattc_notify_evt_param:

(C++ member), 137

(C++ member), 139

esp_ble_gattc_cb_param_t::gattc_close_eevstp__pbalrea_mgattc_cb_param_t::gattc_notify_evt_param:

(C++ class), 137

(C++ member), 139

esp_ble_gattc_cb_param_t::gattc_close_eevstp__pbalrea_mg:a:tctocn_nc_bi_dparam_t::gattc_notify_evt_param:

(C++ member), 138

(C++ member), 139

esp_ble_gattc_cb_param_t::gattc_close_eevstp__pbalrea_mg:a:trteca_scobn_param_t::gattc_notify_evt_param:

(C++ member), 138

(C++ member), 139

esp_ble_gattc_cb_param_t::gattc_close_eevstp__pbalrea_mg:a:trtecm_octbe__pbadraam_t::gattc_notify_evt_param:

(C++ member), 138

(C++ member), 139

esp_ble_gattc_cb_param_t::gattc_close_eevstp__pbalrea_mg:a:tsttca_tcubs_param_t::gattc_notify_evt_param:

(C++ member), 138

(C++ member), 139

esp_ble_gattc_cb_param_t::gattc_congeste_sepv_tb_lpea_rgaamttc_cb_param_t::gattc_open_evt_param

(C++ class), 138

(C++ class), 139

esp_ble_gattc_cb_param_t::gattc_congeste_sepv_tb_lpea_rgaamt:t:cc_ocnbg_epsatreadm_t::gattc_open_evt_param::c

(C++ member), 138

(C++ member), 140

esp_ble_gattc_cb_param_t::gattc_congeste_sepv_tb_lpea_rgaamt:t:cc_ocnbn__piadram_t::gattc_open_evt_param::m

(C++ member), 138

(C++ member), 140

esp_ble_gattc_cb_param_t::gattc_connecte_sepv_tb_lpea_rgaamttc_cb_param_t::gattc_open_evt_param::r

(C++ class), 138

(C++ member), 140

esp_ble_gattc_cb_param_t::gattc_connecte_sepv_tb_lpea_rgaamt:t:cc_ocnbn__piadram_t::gattc_open_evt_param::s

(C++ member), 138

(C++ member), 140

esp_ble_gattc_cb_param_t::gattc_connecte_sepv_tb_lpea_rgaamt:t:cc_ocnbn__ppaarraamm_st::gattc_queue_full_evt_pa

(C++ member), 138

(C++ class), 140

esp_ble_gattc_cb_param_t::gattc_connecte_sepv_tb_lpea_rgaamt:t:cl_icnbk__praorlaem_t::gattc_queue_full_evt_pa

(C++ member), 138

(C++ member), 140

esp_ble_gattc_cb_param_t::gattc_connecte_sepv_tb_lpea_rgaamt:t:cr_ecmbo_tpea_rbadma_t::gattc_queue_full_evt_pa

(C++ member), 138

(C++ member), 140

esp_ble_gattc_cb_param_t::gattc_dis_srvecs_pc_mbplle__egvatt_tpca_rcabm_param_t::gattc_queue_full_evt_pa

(C++ class), 138

(C++ member), 140

esp_ble_gattc_cb_param_t::gattc_dis_srvecs_pc_mbplle__egvatt_tpca_rcabm_:p:acroanmn__ti:d:gattc_read_char_evt_par

(C++ member), 138

(C++ class), 140

esp_ble_gattc_cb_param_t::gattc_dis_srvecs_pc_mbplle__egvatt_tpca_rcabm_:p:asrtaamt_uts::gattc_read_char_evt_par

(C++ member), 138

(C++ member), 140

esp_ble_gattc_cb_param_t::gattc_disconneescpt__belvet__gpaatrtacm_cb_param_t::gattc_read_char_evt_par

(C++ class), 138

(C++ member), 140

esp_ble_gattc_cb_param_t::gattc_disconneescpt__belvet__gpaatrtacm_:c:bc_opnanr_aimd_t::gattc_read_char_evt_par

(C++ member), 139

(C++ member), 140

Espressif Systems

2026

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_gattc_cb_param_t::gattc_read_cheasrp__ebvlte__pgaartatmc:_:cvba_lpuaeram_t::gattc_write_evt_param::

(C++ member), 140

(C++ member), 142

esp_ble_gattc_cb_param_t::gattc_read_cheasrp__ebvlte__pgaartatmc:_:cvba_lpuaer_alme_nt::get_addr_list

(C++ member), 140

(C++ member), 137

esp_ble_gattc_cb_param_t::gattc_reg_evte_sppa_rbalme_gattc_cb_param_t::notify (C++

(C++ class), 140

member), 137

esp_ble_gattc_cb_param_t::gattc_reg_evte_sppa_rbalme:_:gaaptpt_ci_dcb_param_t::open (C++

(C++ member), 140

member), 136

esp_ble_gattc_cb_param_t::gattc_reg_evte_sppa_rbalme:_:gsattattcu_scb_param_t::queue_full

(C++ member), 140

(C++ member), 137

esp_ble_gattc_cb_param_t::gattc_reg_fore_snpo_tbilfey__geavttt_cp_acrba_mparam_t::read (C++

(C++ class), 140

member), 137

esp_ble_gattc_cb_param_t::gattc_reg_fore_snpo_tbilfey__geavttt_cp_acrba_mp:a:rhaamn_dtl:e:reg (C++

(C++ member), 141

member), 136

esp_ble_gattc_cb_param_t::gattc_reg_fore_snpo_tbilfey__geavttt_cp_acrba_mp:a:rsatma_ttu:s:reg_for_notify

(C++ member), 141

(C++ member), 137

esp_ble_gattc_cb_param_t::gattc_search_ecsmpp_lb_leev_tg_aptatrca_mcb_param_t::search_cmpl

(C++ class), 141

(C++ member), 136

esp_ble_gattc_cb_param_t::gattc_search_ecsmpp_lb_leev_tg_aptatrca_mc:b:_cpoanrna_mi_dt::search_res

(C++ member), 141

(C++ member), 136

esp_ble_gattc_cb_param_t::gattc_search_ecsmpp_lb_leev_tg_aptatrca_mc:b:_speaarracmh_etd:_:sseertv_iacses_osco_ucrmcpe

(C++ member), 141

(C++ member), 137

esp_ble_gattc_cb_param_t::gattc_search_ecsmpp_lb_leev_tg_aptatrca_mc:b:_sptaartaums_t::srvc_chg

(C++ member), 141

(C++ member), 137

esp_ble_gattc_cb_param_t::gattc_search_erseps__belvet__gpaatrtacm_cb_param_t::unreg_for_notify

(C++ class), 141

(C++ member), 137

esp_ble_gattc_cb_param_t::gattc_search_erseps__belvet__gpaatrtacm_:c:bc_opnanr_aimd_t::write (C++

(C++ member), 141

member), 137

esp_ble_gattc_cb_param_t::gattc_search_erseps__belvet__gpaatrtacm_:c:leonsde_(hCa+n+dlfuenction), 129

(C++ member), 141

esp_ble_gattc_execute_write (C++ func-

esp_ble_gattc_cb_param_t::gattc_search_res_evtti_onp)a, r13a5m::is_primary

(C++ member), 141

esp_ble_gattc_get_all_char (C++ function),

esp_ble_gattc_cb_param_t::gattc_search_res_evt1_30param::srvc_id

(C++ member), 141

esp_ble_gattc_get_all_descr (C++ func-

esp_ble_gattc_cb_param_t::gattc_search_res_evtti_onp)a, r13a0m::start_handle

(C++ member), 141

esp_ble_gattc_get_attr_count (C++ func-

esp_ble_gattc_cb_param_t::gattc_set_assoc_addrti_onc)m, p13_2evt_param

(C++ class), 141

esp_ble_gattc_get_char_by_uuid (C++

esp_ble_gattc_cb_param_t::gattc_set_assoc_addrfu_nccmtiopn_)e, 1v3t1_param::status

(C++ member), 141

esp_ble_gattc_get_db (C++ function), 132

esp_ble_gattc_cb_param_t::gattc_srvc_chegs_pe_vbtl_ep_agraatmtc_get_descr_by_char_handle

(C++ class), 141

(C++ function), 131

esp_ble_gattc_cb_param_t::gattc_srvc_chegs_pe_vbtl_ep_agraatmt:c:_rgeemto_tdee_sbcdra_by_uuid (C++

(C++ member), 141

function), 131

esp_ble_gattc_cb_param_t::gattc_unreg_feosrp__nboltei_fgya_tetvct__gpeatr_aimnclude_service

(C++ class), 141

(C++ function), 132

esp_ble_gattc_cb_param_t::gattc_unreg_feosrp__nboltei_fgya_tetvct__gpeatr_asme:r:vhiacnedl(eC++ function),

(C++ member), 142

130

esp_ble_gattc_cb_param_t::gattc_unreg_feosrp__nboltei_fgya_tetvct__oppaerna(mC:+:+stfuantcutiosn), 129

(C++ member), 142

esp_ble_gattc_prepare_write (C++ func-

esp_ble_gattc_cb_param_t::gattc_write_evt_paratimon), 134

(C++ class), 142

esp_ble_gattc_prepare_write_char_descr

esp_ble_gattc_cb_param_t::gattc_write_evt_para(Cm+:+:cfounncnti_oin)d, 134

(C++ member), 142

esp_ble_gattc_read_by_type (C++ function),

esp_ble_gattc_cb_param_t::gattc_write_evt_para1m33::handle

(C++ member), 142

esp_ble_gattc_read_char (C++ function), 133

esp_ble_gattc_cb_param_t::gattc_write_eevstp__pbalrea_mg:a:totfcf_sreetad_char_descr (C++ func-

(C++ member), 142

tion), 133

Espressif Systems

2027

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_gattc_read_multiple (C++ func- esp_ble_gatts_cb_param_t::gatts_add_attr_tab_evt_

tion), 133

(C++ member), 121

esp_ble_gattc_register_callback (C++ esp_ble_gatts_cb_param_t::gatts_add_attr_tab_evt_

function), 129

(C++ member), 121

esp_ble_gattc_register_for_notify

esp_ble_gatts_cb_param_t::gatts_add_attr_tab_evt_

(C++ function), 135

(C++ member), 121

esp_ble_gattc_search_service (C++ func- esp_ble_gatts_cb_param_t::gatts_add_char_descr_ev

tion), 130

(C++ class), 121

esp_ble_gattc_send_mtu_req (C++ function), esp_ble_gatts_cb_param_t::gatts_add_char_descr_ev

129

(C++ member), 121

esp_ble_gattc_unregister_for_notify esp_ble_gatts_cb_param_t::gatts_add_char_descr_ev

(C++ function), 135

(C++ member), 121

esp_ble_gattc_write_char (C++ function), esp_ble_gatts_cb_param_t::gatts_add_char_descr_ev

134

(C++ member), 121

esp_ble_gattc_write_char_descr (C++ esp_ble_gatts_cb_param_t::gatts_add_char_descr_ev

function), 134

(C++ member), 121

esp_ble_gatts_add_char (C++ function), 117 esp_ble_gatts_cb_param_t::gatts_add_char_evt_para

esp_ble_gatts_add_char_descr (C++ func-

(C++ class), 121

tion), 118

esp_ble_gatts_cb_param_t::gatts_add_char_evt_para

esp_ble_gatts_add_included_service

(C++ member), 122

(C++ function), 117

esp_ble_gatts_cb_param_t::gatts_add_char_evt_para

esp_ble_gatts_app_register (C++ function),

(C++ member), 122

116

esp_ble_gatts_cb_param_t::gatts_add_char_evt_para

esp_ble_gatts_app_unregister (C++ func-

(C++ member), 122

tion), 117

esp_ble_gatts_cb_param_t::gatts_add_char_evt_para

esp_ble_gatts_cb_param_t (C++ union), 120

(C++ member), 122

esp_ble_gatts_cb_param_t::add_attr_tab esp_ble_gatts_cb_param_t::gatts_add_incl_srvc_evt

(C++ member), 121

(C++ class), 122

esp_ble_gatts_cb_param_t::add_char

esp_ble_gatts_cb_param_t::gatts_add_incl_srvc_evt

(C++ member), 120

(C++ member), 122

esp_ble_gatts_cb_param_t::add_char_descersp_ble_gatts_cb_param_t::gatts_add_incl_srvc_evt

(C++ member), 120

(C++ member), 122

esp_ble_gatts_cb_param_t::add_incl_srvcesp_ble_gatts_cb_param_t::gatts_add_incl_srvc_evt

(C++ member), 120

(C++ member), 122

esp_ble_gatts_cb_param_t::cancel_open esp_ble_gatts_cb_param_t::gatts_cancel_open_evt_p

(C++ member), 120

(C++ class), 122

esp_ble_gatts_cb_param_t::close (C++ esp_ble_gatts_cb_param_t::gatts_cancel_open_evt_p

member), 121

(C++ member), 122

esp_ble_gatts_cb_param_t::conf (C++ esp_ble_gatts_cb_param_t::gatts_close_evt_param

member), 120

(C++ class), 122

esp_ble_gatts_cb_param_t::congest

esp_ble_gatts_cb_param_t::gatts_close_evt_param::

(C++ member), 121

(C++ member), 122

esp_ble_gatts_cb_param_t::connect

esp_ble_gatts_cb_param_t::gatts_close_evt_param::

(C++ member), 120

(C++ member), 122

esp_ble_gatts_cb_param_t::create (C++ esp_ble_gatts_cb_param_t::gatts_conf_evt_param

member), 120

(C++ class), 122

esp_ble_gatts_cb_param_t::del (C++ esp_ble_gatts_cb_param_t::gatts_conf_evt_param::c

member), 120

(C++ member), 122

esp_ble_gatts_cb_param_t::disconnect esp_ble_gatts_cb_param_t::gatts_conf_evt_param::h

(C++ member), 120

(C++ member), 122

esp_ble_gatts_cb_param_t::exec_write esp_ble_gatts_cb_param_t::gatts_conf_evt_param::l

(C++ member), 120

(C++ member), 122

esp_ble_gatts_cb_param_t::gatts_add_atters_pt_abbl_ee_vgta_tptasr_acmb_param_t::gatts_conf_evt_param::s

(C++ class), 121

(C++ member), 122

esp_ble_gatts_cb_param_t::gatts_add_atters_pt_abbl_ee_vgta_tptasr_acmb:_:phaarnadml_ets::gatts_conf_evt_param::v

(C++ member), 121

(C++ member), 123

esp_ble_gatts_cb_param_t::gatts_add_atters_pt_abbl_ee_vgta_tptasr_acmb:_:pnaurma_mh_atn:d:lgeatts_congest_evt_param

(C++ member), 121

(C++ class), 123

Espressif Systems

2028

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_gatts_cb_param_t::gatts_congeste_sepv_tb_lpea_rgaamt:t:sc_ocnbg_epsatreadm_t::gatts_read_evt_param::b

(C++ member), 123

(C++ member), 125

esp_ble_gatts_cb_param_t::gatts_congeste_sepv_tb_lpea_rgaamt:t:sc_ocnbn__piadram_t::gatts_read_evt_param::c

(C++ member), 123

(C++ member), 125

esp_ble_gatts_cb_param_t::gatts_connecte_sepv_tb_lpea_rgaamtts_cb_param_t::gatts_read_evt_param::h

(C++ class), 123

(C++ member), 125

esp_ble_gatts_cb_param_t::gatts_connecte_sepv_tb_lpea_rgaamt:t:sc_ocnbn__piadram_t::gatts_read_evt_param::i

(C++ member), 123

(C++ member), 125

esp_ble_gatts_cb_param_t::gatts_connecte_sepv_tb_lpea_rgaamt:t:sc_ocnbn__ppaarraamm_st::gatts_read_evt_param::n

(C++ member), 123

(C++ member), 125

esp_ble_gatts_cb_param_t::gatts_connecte_sepv_tb_lpea_rgaamt:t:sl_icnbk__praorlaem_t::gatts_read_evt_param::o

(C++ member), 123

(C++ member), 125

esp_ble_gatts_cb_param_t::gatts_connecte_sepv_tb_lpea_rgaamt:t:sr_ecmbo_tpea_rbadma_t::gatts_read_evt_param::t

(C++ member), 123

(C++ member), 125

esp_ble_gatts_cb_param_t::gatts_create_eesvpt__bplaer_agmatts_cb_param_t::gatts_reg_evt_param

(C++ class), 123

(C++ class), 125

esp_ble_gatts_cb_param_t::gatts_create_eesvpt__bplaer_agma:t:tsse_rcvbi_cpea_rhaamn_dtl:e:gatts_reg_evt_param::ap

(C++ member), 123

(C++ member), 125

esp_ble_gatts_cb_param_t::gatts_create_eesvpt__bplaer_agma:t:tsse_rcvbi_cpea_riadm_t::gatts_reg_evt_param::st

(C++ member), 123

(C++ member), 125

esp_ble_gatts_cb_param_t::gatts_create_eesvpt__bplaer_agma:t:tsst_actbu_sparam_t::gatts_rsp_evt_param

(C++ member), 123

(C++ class), 125

esp_ble_gatts_cb_param_t::gatts_delete_eesvpt__bplaer_agmatts_cb_param_t::gatts_rsp_evt_param::ha

(C++ class), 123

(C++ member), 125

esp_ble_gatts_cb_param_t::gatts_delete_eesvpt__bplaer_agma:t:tsse_rcvbi_cpea_rhaamn_dtl:e:gatts_rsp_evt_param::st

(C++ member), 123

(C++ member), 125

esp_ble_gatts_cb_param_t::gatts_delete_eesvpt__bplaer_agma:t:tsst_actbu_sparam_t::gatts_send_service_chan

(C++ member), 123

(C++ class), 125

esp_ble_gatts_cb_param_t::gatts_disconneescpt__belvet__gpaatrtasm_cb_param_t::gatts_send_service_chan

(C++ class), 124

(C++ member), 125

esp_ble_gatts_cb_param_t::gatts_disconneescpt__belvet__gpaatrtasm_:c:bc_opnanr_aimd_t::gatts_set_attr_val_evt_

(C++ member), 124

(C++ class), 125

esp_ble_gatts_cb_param_t::gatts_disconneescpt__belvet__gpaatrtasm_:c:br_epaasroanm_t::gatts_set_attr_val_evt_

(C++ member), 124

(C++ member), 126

esp_ble_gatts_cb_param_t::gatts_disconneescpt__belvet__gpaatrtasm_:c:br_epmaortaem__btd:a:gatts_set_attr_val_evt_

(C++ member), 124

(C++ member), 126

esp_ble_gatts_cb_param_t::gatts_exec_wreistpe__belvet__gpaatrtasm_cb_param_t::gatts_set_attr_val_evt_

(C++ class), 124

(C++ member), 126

esp_ble_gatts_cb_param_t::gatts_exec_wreistpe__belvet__gpaatrtasm_:c:bb_dpaaram_t::gatts_start_evt_param

(C++ member), 124

(C++ class), 126

esp_ble_gatts_cb_param_t::gatts_exec_wreistpe__belvet__gpaatrtasm_:c:bc_opnanr_aimd_t::gatts_start_evt_param::

(C++ member), 124

(C++ member), 126

esp_ble_gatts_cb_param_t::gatts_exec_wreistpe__belvet__gpaatrtasm_:c:be_xpeacr_awmr_itt:e:_gfaltatgs_start_evt_param::

(C++ member), 124

(C++ member), 126

esp_ble_gatts_cb_param_t::gatts_exec_wreistpe__belvet__gpaatrtasm_:c:bt_rpaanrsa_mi_dt::gatts_stop_evt_param

(C++ member), 124

(C++ class), 126

esp_ble_gatts_cb_param_t::gatts_mtu_evte_sppa_rbalme_gatts_cb_param_t::gatts_stop_evt_param::s

(C++ class), 124

(C++ member), 126

esp_ble_gatts_cb_param_t::gatts_mtu_evte_sppa_rbalme:_:gcaotntns__icdb_param_t::gatts_stop_evt_param::s

(C++ member), 124

(C++ member), 126

esp_ble_gatts_cb_param_t::gatts_mtu_evte_sppa_rbalme:_:gmattuts_cb_param_t::gatts_write_evt_param

(C++ member), 124

(C++ class), 126

esp_ble_gatts_cb_param_t::gatts_open_evets_pp_abrlaem_gatts_cb_param_t::gatts_write_evt_param::

(C++ class), 124

(C++ member), 126

esp_ble_gatts_cb_param_t::gatts_open_evets_pp_abrlaem_:g:astttast_ucsb_param_t::gatts_write_evt_param::

(C++ member), 124

(C++ member), 126

esp_ble_gatts_cb_param_t::gatts_read_evets_pp_abrlaem_gatts_cb_param_t::gatts_write_evt_param::

(C++ class), 124

(C++ member), 126

Espressif Systems

2029

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_gatts_cb_param_t::gatts_write_eevstp__pbalrea_mg:e:ti_sb_opnrde_pdevice_num (C++ func-

(C++ member), 126

tion), 67

esp_ble_gatts_cb_param_t::gatts_write_eevstp__pbalrea_mg:e:tl_ecnurrent_conn_params (C++

(C++ member), 126

function), 67

esp_ble_gatts_cb_param_t::gatts_write_eEvStP__pBaLrEa_mI:D:_nKeEeYd__MrAsSpK (C macro), 58

(C++ member), 126

esp_ble_io_cap_t (C++ type), 98

esp_ble_gatts_cb_param_t::gatts_write_eEvStP__pBaLrEa_mI:S:_oVfAfLsIeDt_PARAM (C macro), 57

(C++ member), 126

esp_ble_key_mask_t (C++ type), 58

esp_ble_gatts_cb_param_t::gatts_write_eevstp__pbalrea_mk:e:yt_rta(nCs+_+idclass), 89

(C++ member), 126

esp_ble_key_t::bd_addr (C++ member), 90

esp_ble_gatts_cb_param_t::gatts_write_eevstp__pbalrea_mk:e:yv_atl:u:ekey_type (C++ member), 90

(C++ member), 126

esp_ble_key_t::p_key_value (C++ member),

esp_ble_gatts_cb_param_t::mtu (C++

90

member), 120

esp_ble_key_type_t (C++ type), 98

esp_ble_gatts_cb_param_t::open (C++ esp_ble_key_value_t (C++ union), 72

member), 120

esp_ble_key_value_t::lcsrk_key (C++

esp_ble_gatts_cb_param_t::read (C++

member), 72

member), 120

esp_ble_key_value_t::lenc_key (C++

esp_ble_gatts_cb_param_t::reg (C++

member), 72

member), 120

esp_ble_key_value_t::pcsrk_key (C++

esp_ble_gatts_cb_param_t::rsp (C++

member), 72

member), 121

esp_ble_key_value_t::penc_key (C++

esp_ble_gatts_cb_param_t::service_change

member), 72

(C++ member), 121

esp_ble_key_value_t::pid_key (C++ mem-

esp_ble_gatts_cb_param_t::set_attr_val

ber), 72

(C++ member), 121

esp_ble_lcsrk_keys (C++ class), 88

esp_ble_gatts_cb_param_t::start (C++ esp_ble_lcsrk_keys::counter (C++ mem-

member), 120

ber), 89

esp_ble_gatts_cb_param_t::stop (C++ esp_ble_lcsrk_keys::csrk (C++ member), 89

member), 120

esp_ble_lcsrk_keys::div (C++ member), 89

esp_ble_gatts_cb_param_t::write (C++ esp_ble_lcsrk_keys::sec_level (C++

member), 120

member), 89

esp_ble_gatts_close (C++ function), 119

ESP_BLE_LEGACY_ADV_TYPE_DIRECT_IND (C

esp_ble_gatts_create_attr_tab (C++ func-

macro), 98

tion), 117

ESP_BLE_LEGACY_ADV_TYPE_IND (C macro), 98

esp_ble_gatts_create_service (C++ func- ESP_BLE_LEGACY_ADV_TYPE_NONCON_IND (C

tion), 117

macro), 98

esp_ble_gatts_delete_service (C++ func- ESP_BLE_LEGACY_ADV_TYPE_SCAN_IND (C

tion), 118

macro), 98

esp_ble_gatts_get_attr_value (C++ func- ESP_BLE_LEGACY_ADV_TYPE_SCAN_RSP_TO_ADV_IND

tion), 119

(C macro), 98

esp_ble_gatts_open (C++ function), 119

ESP_BLE_LEGACY_ADV_TYPE_SCAN_RSP_TO_ADV_SCAN_IND

esp_ble_gatts_register_callback (C++

(C macro), 98

function), 116

esp_ble_lenc_keys_t (C++ class), 88

esp_ble_gatts_send_indicate (C++ func- esp_ble_lenc_keys_t::div (C++ member), 88

tion), 118

esp_ble_lenc_keys_t::key_size (C++

esp_ble_gatts_send_response (C++ func-

member), 88

tion), 119

esp_ble_lenc_keys_t::ltk (C++ member), 88

esp_ble_gatts_send_service_change_indiceastpi_obnle_lenc_keys_t::sec_level (C++

(C++ function), 119

member), 88

esp_ble_gatts_set_attr_value (C++ func- ESP_BLE_LINK_KEY_MASK (C macro), 58

tion), 119

esp_ble_local_id_keys_t (C++ class), 90

esp_ble_gatts_start_service (C++ func- esp_ble_local_id_keys_t::dhk (C++ mem-

tion), 118

ber), 90

esp_ble_gatts_stop_service (C++ function), esp_ble_local_id_keys_t::ir (C++ mem-

118

ber), 90

esp_ble_get_bond_device_list (C++ func- esp_ble_local_id_keys_t::irk (C++ mem-

tion), 67

ber), 90

Espressif Systems

2030

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

ESP_BLE_MESH_ACTUATOR_BLOCKED_ERROR (C

(C++ class), 245

macro), 258

esp_ble_mesh_cfg_app_key_list_cb_t::app_idx

ESP_BLE_MESH_ACTUATOR_BLOCKED_WARNING

(C++ member), 245

(C macro), 258

esp_ble_mesh_cfg_app_key_list_cb_t::net_idx

ESP_BLE_MESH_ADDR_ALL_NODES (C macro),

(C++ member), 245

188

esp_ble_mesh_cfg_app_key_list_cb_t::status

ESP_BLE_MESH_ADDR_FRIENDS (C macro), 188

(C++ member), 245

ESP_BLE_MESH_ADDR_IS_GROUP (C macro), 189 esp_ble_mesh_cfg_app_key_status_cb_t

ESP_BLE_MESH_ADDR_IS_RFU (C macro), 189

(C++ class), 243

ESP_BLE_MESH_ADDR_IS_UNICAST (C macro), esp_ble_mesh_cfg_app_key_status_cb_t::app_idx

189

(C++ member), 243

ESP_BLE_MESH_ADDR_IS_VIRTUAL (C macro), esp_ble_mesh_cfg_app_key_status_cb_t::net_idx

189

(C++ member), 243

ESP_BLE_MESH_ADDR_PROXIES (C macro), 188 esp_ble_mesh_cfg_app_key_status_cb_t::status

ESP_BLE_MESH_ADDR_RELAYS (C macro), 188

(C++ member), 243

ESP_BLE_MESH_ADDR_TYPE_PUBLIC (C macro), esp_ble_mesh_cfg_app_key_update_t

190

(C++ class), 239

ESP_BLE_MESH_ADDR_TYPE_RANDOM (C macro), esp_ble_mesh_cfg_app_key_update_t::app_idx

191

(C++ member), 239

ESP_BLE_MESH_ADDR_TYPE_RPA_PUBLIC (C esp_ble_mesh_cfg_app_key_update_t::app_key

macro), 191

(C++ member), 239

ESP_BLE_MESH_ADDR_TYPE_RPA_RANDOM (C esp_ble_mesh_cfg_app_key_update_t::net_idx

macro), 191

(C++ member), 239

esp_ble_mesh_addr_type_t (C++ type), 202 esp_ble_mesh_cfg_beacon_set_t (C++

ESP_BLE_MESH_ADDR_UNASSIGNED (C macro),

class), 234

188

esp_ble_mesh_cfg_beacon_set_t::beacon

ESP_BLE_MESH_BATTERY_LOW_ERROR

(C

(C++ member), 235

macro), 257

esp_ble_mesh_cfg_beacon_status_cb_t

ESP_BLE_MESH_BATTERY_LOW_WARNING (C

(C++ class), 241

macro), 257

esp_ble_mesh_cfg_beacon_status_cb_t::beacon

esp_ble_mesh_bd_addr_t (C++ type), 202

(C++ member), 241

ESP_BLE_MESH_BEACON_DISABLED (C macro), esp_ble_mesh_cfg_client_cb_event_t

189

(C++ enum), 250

ESP_BLE_MESH_BEACON_ENABLED (C macro), esp_ble_mesh_cfg_client_cb_param_t

189

(C++ class), 246

ESP_BLE_MESH_BEEP (C++ enumerator), 204

esp_ble_mesh_cfg_client_cb_param_t::error_code

ESP_BLE_MESH_BLINK (C++ enumerator), 204

(C++ member), 246

esp_ble_mesh_cb_t (C++ type), 202

esp_ble_mesh_cfg_client_cb_param_t::params

esp_ble_mesh_cb_type_t (C++ enum), 204

(C++ member), 246

esp_ble_mesh_cfg_app_key_add_t (C++ esp_ble_mesh_cfg_client_cb_param_t::status_cb

class), 235

(C++ member), 246

esp_ble_mesh_cfg_app_key_add_t::app_idxesp_ble_mesh_cfg_client_cb_t (C++ type),

(C++ member), 236

250

esp_ble_mesh_cfg_app_key_add_t::app_keyesp_ble_mesh_cfg_client_common_cb_param_t

(C++ member), 236

(C++ union), 230

esp_ble_mesh_cfg_app_key_add_t::net_idxesp_ble_mesh_cfg_client_common_cb_param_t::appkey

(C++ member), 236

(C++ member), 230

esp_ble_mesh_cfg_app_key_delete_t

esp_ble_mesh_cfg_client_common_cb_param_t::appkey

(C++ class), 239

(C++ member), 230

esp_ble_mesh_cfg_app_key_delete_t::app_eisdpx_ble_mesh_cfg_client_common_cb_param_t::beacon

(C++ member), 240

(C++ member), 230

esp_ble_mesh_cfg_app_key_delete_t::net_eisdpx_ble_mesh_cfg_client_common_cb_param_t::comp_d

(C++ member), 240

(C++ member), 230

esp_ble_mesh_cfg_app_key_get_t (C++ esp_ble_mesh_cfg_client_common_cb_param_t::defaul

class), 233

(C++ member), 230

esp_ble_mesh_cfg_app_key_get_t::net_idxesp_ble_mesh_cfg_client_common_cb_param_t::friend

(C++ member), 234

(C++ member), 230

esp_ble_mesh_cfg_app_key_list_cb_t

esp_ble_mesh_cfg_client_common_cb_param_t::gatt_p

Espressif Systems

2031

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 230

(C++ enumerator), 250

esp_ble_mesh_cfg_client_common_cb_parame_stp:_:bhleea_rmtebseha_tc_fpgu_bc_lsiteanttu_sset_state_t

(C++ member), 230

(C++ union), 228

esp_ble_mesh_cfg_client_common_cb_parame_stp:_:bhleea_rmtebseha_tc_fsgu_bc_lsiteanttu_sset_state_t::app_key_add

(C++ member), 230

(C++ member), 229

esp_ble_mesh_cfg_client_common_cb_parame_stp:_:bklre__pmheasshe__csftga_tculsient_set_state_t::app_key_dele

(C++ member), 231

(C++ member), 229

esp_ble_mesh_cfg_client_common_cb_parame_stp:_:bllpen__mteismhe_ocuftg__sctlaiteunst_set_state_t::app_key_upda

(C++ member), 231

(C++ member), 229

esp_ble_mesh_cfg_client_common_cb_parame_stp:_:bmloed_emle_sahp_pc_flgi_sctlient_set_state_t::beacon_set

(C++ member), 231

(C++ member), 229

esp_ble_mesh_cfg_client_common_cb_parame_stp:_:bmloed_emle_sahp_pc_fsgt_actluisent_set_state_t::default_ttl_

(C++ member), 230

(C++ member), 229

esp_ble_mesh_cfg_client_common_cb_parame_stp:_:bmloed_emle_sphu_bc_fsgt_actluisent_set_state_t::friend_set

(C++ member), 230

(C++ member), 229

esp_ble_mesh_cfg_client_common_cb_parame_stp:_:bmloed_emle_sshu_bc_flgi_sctlient_set_state_t::gatt_proxy_s

(C++ member), 230

(C++ member), 229

esp_ble_mesh_cfg_client_common_cb_parame_stp:_:bmloed_emle_sshu_bc_fsgt_actluisent_set_state_t::heartbeat_pu

(C++ member), 230

(C++ member), 229

esp_ble_mesh_cfg_client_common_cb_parame_stp:_:bnleet__mtersahn_scmfigt__csltiaetnuts_set_state_t::heartbeat_su

(C++ member), 230

(C++ member), 229

esp_ble_mesh_cfg_client_common_cb_parame_stp:_:bnleet_kmeeys_hl_icsftg_client_set_state_t::kr_phase_set

(C++ member), 230

(C++ member), 230

esp_ble_mesh_cfg_client_common_cb_parame_stp:_:bnleet_kmeeys_hs_tcaftgu_sclient_set_state_t::model_app_bi

(C++ member), 230

(C++ member), 229

esp_ble_mesh_cfg_client_common_cb_parame_stp:_:bnloed_em_eisdhe_nctfigt_yc_lsiteanttu_sset_state_t::model_app_un

(C++ member), 231

(C++ member), 230

esp_ble_mesh_cfg_client_common_cb_parame_stp:_:brleel_amye_ssht_actfugs_client_set_state_t::model_pub_se

(C++ member), 230

(C++ member), 229

ESP_BLE_MESH_CFG_CLIENT_EVT_MAX (C++ esp_ble_mesh_cfg_client_set_state_t::model_pub_va

enumerator), 250

(C++ member), 229

ESP_BLE_MESH_CFG_CLIENT_GET_STATE_EVT esp_ble_mesh_cfg_client_set_state_t::model_sub_ad

(C++ enumerator), 250

(C++ member), 229

esp_ble_mesh_cfg_client_get_state_t esp_ble_mesh_cfg_client_set_state_t::model_sub_de

(C++ union), 228

(C++ member), 229

esp_ble_mesh_cfg_client_get_state_t::apeps_pk_ebyl_eg_emtesh_cfg_client_set_state_t::model_sub_de

(C++ member), 228

(C++ member), 229

esp_ble_mesh_cfg_client_get_state_t::coemspp__dbaltea__mgeesth_cfg_client_set_state_t::model_sub_ov

(C++ member), 228

(C++ member), 229

esp_ble_mesh_cfg_client_get_state_t::kre_spph_abslee__gmeetsh_cfg_client_set_state_t::model_sub_va

(C++ member), 228

(C++ member), 229

esp_ble_mesh_cfg_client_get_state_t::lpens_pp_oblllet_om_egseht_cfg_client_set_state_t::model_sub_va

(C++ member), 228

(C++ member), 229

esp_ble_mesh_cfg_client_get_state_t::moedsepl__bplueb__mgeesth_cfg_client_set_state_t::model_sub_va

(C++ member), 228

(C++ member), 229

esp_ble_mesh_cfg_client_get_state_t::noedsep__ibdleen_tmietsyh__gceftg_client_set_state_t::net_key_add

(C++ member), 228

(C++ member), 229

esp_ble_mesh_cfg_client_get_state_t::siegs_pm_obdleel__maepsph__gceftg_client_set_state_t::net_key_dele

(C++ member), 228

(C++ member), 229

esp_ble_mesh_cfg_client_get_state_t::siegs_pm_obdleel__mseusbh__gceftg_client_set_state_t::net_key_upda

(C++ member), 228

(C++ member), 229

esp_ble_mesh_cfg_client_get_state_t::vneds_pm_obdleel__maepsph__gceftg_client_set_state_t::net_transmit

(C++ member), 228

(C++ member), 230

esp_ble_mesh_cfg_client_get_state_t::vneds_pm_obdleel__mseusbh__gceftg_client_set_state_t::node_identit

(C++ member), 228

(C++ member), 230

ESP_BLE_MESH_CFG_CLIENT_PUBLISH_EVT esp_ble_mesh_cfg_client_set_state_t::relay_set

(C++ enumerator), 250

(C++ member), 229

ESP_BLE_MESH_CFG_CLIENT_SET_STATE_EVT ESP_BLE_MESH_CFG_CLIENT_TIMEOUT_EVT

Espressif Systems

2032

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ enumerator), 250

(C++ member), 244

esp_ble_mesh_cfg_comp_data_status_cb_t esp_ble_mesh_cfg_hb_sub_status_cb_t::min_hops

(C++ class), 241

(C++ member), 244

esp_ble_mesh_cfg_comp_data_status_cb_t:e:scpo_mbploes_imteisohn__cdfagt_ahb_sub_status_cb_t::period

(C++ member), 241

(C++ member), 244

esp_ble_mesh_cfg_comp_data_status_cb_t:e:sppa_gbele_mesh_cfg_hb_sub_status_cb_t::src

(C++ member), 241

(C++ member), 244

esp_ble_mesh_cfg_composition_data_get_tesp_ble_mesh_cfg_hb_sub_status_cb_t::status

(C++ class), 233

(C++ member), 244

esp_ble_mesh_cfg_composition_data_get_te:s:pp_abglee_mesh_cfg_heartbeat_pub_set_t

(C++ member), 233

(C++ class), 240

esp_ble_mesh_cfg_default_ttl_set_t

esp_ble_mesh_cfg_heartbeat_pub_set_t::count

(C++ class), 235

(C++ member), 241

esp_ble_mesh_cfg_default_ttl_set_t::ttlesp_ble_mesh_cfg_heartbeat_pub_set_t::dst

(C++ member), 235

(C++ member), 241

esp_ble_mesh_cfg_default_ttl_status_cb_etsp_ble_mesh_cfg_heartbeat_pub_set_t::feature

(C++ class), 241

(C++ member), 241

esp_ble_mesh_cfg_default_ttl_status_cb_ets:p:_dbelfea_umlets_ht_tclfg_heartbeat_pub_set_t::net_idx

(C++ member), 241

(C++ member), 241

esp_ble_mesh_cfg_friend_set_t (C++ esp_ble_mesh_cfg_heartbeat_pub_set_t::period

class), 235

(C++ member), 241

esp_ble_mesh_cfg_friend_set_t::friend_setsapt_eble_mesh_cfg_heartbeat_pub_set_t::ttl

(C++ member), 235

(C++ member), 241

esp_ble_mesh_cfg_friend_status_cb_t esp_ble_mesh_cfg_heartbeat_sub_set_t

(C++ class), 243

(C++ class), 241

esp_ble_mesh_cfg_friend_status_cb_t::freisepn_db_lset_amteesh_cfg_heartbeat_sub_set_t::dst

(C++ member), 244

(C++ member), 241

esp_ble_mesh_cfg_gatt_proxy_set_t

esp_ble_mesh_cfg_heartbeat_sub_set_t::period

(C++ class), 235

(C++ member), 241

esp_ble_mesh_cfg_gatt_proxy_set_t::gatte_sppr_obxlye_mesh_cfg_heartbeat_sub_set_t::src

(C++ member), 235

(C++ member), 241

esp_ble_mesh_cfg_gatt_proxy_status_cb_tesp_ble_mesh_cfg_kr_phase_get_t (C++

(C++ class), 241

class), 234

esp_ble_mesh_cfg_gatt_proxy_status_cb_te:s:pg_abtlte__pmreosxhy_cfg_kr_phase_get_t::net_idx

(C++ member), 242

(C++ member), 234

esp_ble_mesh_cfg_hb_pub_status_cb_t esp_ble_mesh_cfg_kr_phase_set_t (C++

(C++ class), 244

class), 240

esp_ble_mesh_cfg_hb_pub_status_cb_t::coeusnpt_ble_mesh_cfg_kr_phase_set_t::net_idx

(C++ member), 244

(C++ member), 240

esp_ble_mesh_cfg_hb_pub_status_cb_t::dsetsp_ble_mesh_cfg_kr_phase_set_t::transition

(C++ member), 244

(C++ member), 240

esp_ble_mesh_cfg_hb_pub_status_cb_t::feeastpu_rbelse_mesh_cfg_kr_phase_status_cb_t

(C++ member), 244

(C++ class), 246

esp_ble_mesh_cfg_hb_pub_status_cb_t::neets_pi_dbxle_mesh_cfg_kr_phase_status_cb_t::net_idx

(C++ member), 244

(C++ member), 246

esp_ble_mesh_cfg_hb_pub_status_cb_t::peersipo_dble_mesh_cfg_kr_phase_status_cb_t::phase

(C++ member), 244

(C++ member), 246

esp_ble_mesh_cfg_hb_pub_status_cb_t::steastpu_sble_mesh_cfg_kr_phase_status_cb_t::status

(C++ member), 244

(C++ member), 246

esp_ble_mesh_cfg_hb_pub_status_cb_t::ttelsp_ble_mesh_cfg_lpn_polltimeout_get_t

(C++ member), 244

(C++ class), 234

esp_ble_mesh_cfg_hb_sub_status_cb_t esp_ble_mesh_cfg_lpn_polltimeout_get_t::lpn_addr

(C++ class), 244

(C++ member), 234

esp_ble_mesh_cfg_hb_sub_status_cb_t::coeusnpt_ble_mesh_cfg_lpn_pollto_status_cb_t

(C++ member), 244

(C++ class), 246

esp_ble_mesh_cfg_hb_sub_status_cb_t::dsetsp_ble_mesh_cfg_lpn_pollto_status_cb_t::lpn_addr

(C++ member), 244

(C++ member), 246

esp_ble_mesh_cfg_hb_sub_status_cb_t::maexs_ph_obplse_mesh_cfg_lpn_pollto_status_cb_t::poll_tim

Espressif Systems

2033

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 246

(C++ member), 236

esp_ble_mesh_cfg_mod_app_status_cb_t esp_ble_mesh_cfg_model_pub_set_t::element_addr

(C++ class), 243

(C++ member), 236

esp_ble_mesh_cfg_mod_app_status_cb_t::aepspp__ibdlxe_mesh_cfg_model_pub_set_t::model_id

(C++ member), 243

(C++ member), 236

esp_ble_mesh_cfg_mod_app_status_cb_t::ceosmpp_abnlye__imdesh_cfg_model_pub_set_t::publish_addr

(C++ member), 243

(C++ member), 236

esp_ble_mesh_cfg_mod_app_status_cb_t::eelsepm_ebnlte__amdedsrh_cfg_model_pub_set_t::publish_app_idx

(C++ member), 243

(C++ member), 236

esp_ble_mesh_cfg_mod_app_status_cb_t::meosdpe_lb_lied_mesh_cfg_model_pub_set_t::publish_period

(C++ member), 243

(C++ member), 236

esp_ble_mesh_cfg_mod_app_status_cb_t::setsapt_ubsle_mesh_cfg_model_pub_set_t::publish_retrans

(C++ member), 243

(C++ member), 236

esp_ble_mesh_cfg_model_app_bind_t

esp_ble_mesh_cfg_model_pub_set_t::publish_ttl

(C++ class), 236

(C++ member), 236

esp_ble_mesh_cfg_model_app_bind_t::compeasnpy__bilde_mesh_cfg_model_pub_status_cb_t

(C++ member), 236

(C++ class), 242

esp_ble_mesh_cfg_model_app_bind_t::elemeesnpt__balded_rmesh_cfg_model_pub_status_cb_t::app_idx

(C++ member), 236

(C++ member), 242

esp_ble_mesh_cfg_model_app_bind_t::modeels_pa_pbpl_ei_dmxesh_cfg_model_pub_status_cb_t::company_i

(C++ member), 236

(C++ member), 242

esp_ble_mesh_cfg_model_app_bind_t::modeels_pi_dble_mesh_cfg_model_pub_status_cb_t::cred_flag

(C++ member), 236

(C++ member), 242

esp_ble_mesh_cfg_model_app_list_cb_t esp_ble_mesh_cfg_model_pub_status_cb_t::element_a

(C++ class), 246

(C++ member), 242

esp_ble_mesh_cfg_model_app_list_cb_t::aepspp__ibdlxe_mesh_cfg_model_pub_status_cb_t::model_id

(C++ member), 246

(C++ member), 242

esp_ble_mesh_cfg_model_app_list_cb_t::ceosmpp_abnlye__imdesh_cfg_model_pub_status_cb_t::period

(C++ member), 246

(C++ member), 242

esp_ble_mesh_cfg_model_app_list_cb_t::eelsepm_ebnlte__amdedsrh_cfg_model_pub_status_cb_t::publish_a

(C++ member), 246

(C++ member), 242

esp_ble_mesh_cfg_model_app_list_cb_t::meosdpe_lb_lied_mesh_cfg_model_pub_status_cb_t::status

(C++ member), 246

(C++ member), 242

esp_ble_mesh_cfg_model_app_list_cb_t::setsapt_ubsle_mesh_cfg_model_pub_status_cb_t::transmit

(C++ member), 246

(C++ member), 242

esp_ble_mesh_cfg_model_app_unbind_t esp_ble_mesh_cfg_model_pub_status_cb_t::ttl

(C++ class), 240

(C++ member), 242

esp_ble_mesh_cfg_model_app_unbind_t::coemsppa_nbyl_ei_dmesh_cfg_model_pub_va_set_t

(C++ member), 240

(C++ class), 238

esp_ble_mesh_cfg_model_app_unbind_t::eleesmpe_nbtl_ea_dmdersh_cfg_model_pub_va_set_t::company_id

(C++ member), 240

(C++ member), 239

esp_ble_mesh_cfg_model_app_unbind_t::moedsepl__balpep__miedsxh_cfg_model_pub_va_set_t::cred_flag

(C++ member), 240

(C++ member), 238

esp_ble_mesh_cfg_model_app_unbind_t::moedsepl__bilde_mesh_cfg_model_pub_va_set_t::element_addr

(C++ member), 240

(C++ member), 238

esp_ble_mesh_cfg_model_pub_get_t (C++ esp_ble_mesh_cfg_model_pub_va_set_t::label_uuid

class), 233

(C++ member), 238

esp_ble_mesh_cfg_model_pub_get_t::compaensyp__ibdle_mesh_cfg_model_pub_va_set_t::model_id

(C++ member), 233

(C++ member), 238

esp_ble_mesh_cfg_model_pub_get_t::elemeenstp__abdlder_mesh_cfg_model_pub_va_set_t::publish_app_

(C++ member), 233

(C++ member), 238

esp_ble_mesh_cfg_model_pub_get_t::modele_sipd_ble_mesh_cfg_model_pub_va_set_t::publish_peri

(C++ member), 233

(C++ member), 238

esp_ble_mesh_cfg_model_pub_set_t (C++ esp_ble_mesh_cfg_model_pub_va_set_t::publish_retr

class), 236

(C++ member), 238

esp_ble_mesh_cfg_model_pub_set_t::compaensyp__ibdle_mesh_cfg_model_pub_va_set_t::publish_ttl

(C++ member), 236

(C++ member), 238

esp_ble_mesh_cfg_model_pub_set_t::cred_efslpa_gble_mesh_cfg_model_sub_add_t (C++

Espressif Systems

2034

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

class), 236

(C++ member), 243

esp_ble_mesh_cfg_model_sub_add_t::compaensyp__ibdle_mesh_cfg_model_sub_status_cb_t::sub_addr

(C++ member), 237

(C++ member), 243

esp_ble_mesh_cfg_model_sub_add_t::elemeenstp__abdlder_mesh_cfg_model_sub_va_add_t

(C++ member), 237

(C++ class), 237

esp_ble_mesh_cfg_model_sub_add_t::modele_sipd_ble_mesh_cfg_model_sub_va_add_t::company_id

(C++ member), 237

(C++ member), 237

esp_ble_mesh_cfg_model_sub_add_t::sub_aedsdpr_ble_mesh_cfg_model_sub_va_add_t::element_addr

(C++ member), 237

(C++ member), 237

esp_ble_mesh_cfg_model_sub_delete_all_tesp_ble_mesh_cfg_model_sub_va_add_t::label_uuid

(C++ class), 239

(C++ member), 237

esp_ble_mesh_cfg_model_sub_delete_all_te:s:pc_obmlpea_nmye_sihd_cfg_model_sub_va_add_t::model_id

(C++ member), 239

(C++ member), 237

esp_ble_mesh_cfg_model_sub_delete_all_te:s:pe_lbelmee_nmte_sahd_dcrfg_model_sub_va_delete_t

(C++ member), 239

(C++ class), 238

esp_ble_mesh_cfg_model_sub_delete_all_te:s:pm_obdleel__miedsh_cfg_model_sub_va_delete_t::company_i

(C++ member), 239

(C++ member), 238

esp_ble_mesh_cfg_model_sub_delete_t esp_ble_mesh_cfg_model_sub_va_delete_t::element_a

(C++ class), 237

(C++ member), 238

esp_ble_mesh_cfg_model_sub_delete_t::coemsppa_nbyl_ei_dmesh_cfg_model_sub_va_delete_t::label_uui

(C++ member), 237

(C++ member), 238

esp_ble_mesh_cfg_model_sub_delete_t::eleesmpe_nbtl_ea_dmdersh_cfg_model_sub_va_delete_t::model_id

(C++ member), 237

(C++ member), 238

esp_ble_mesh_cfg_model_sub_delete_t::moedsepl__bilde_mesh_cfg_model_sub_va_overwrite_t

(C++ member), 237

(C++ class), 238

esp_ble_mesh_cfg_model_sub_delete_t::suebs_pa_dbdlre_mesh_cfg_model_sub_va_overwrite_t::compan

(C++ member), 237

(C++ member), 238

esp_ble_mesh_cfg_model_sub_list_cb_t esp_ble_mesh_cfg_model_sub_va_overwrite_t::elemen

(C++ class), 245

(C++ member), 238

esp_ble_mesh_cfg_model_sub_list_cb_t::ceosmpp_abnlye__imdesh_cfg_model_sub_va_overwrite_t::label_

(C++ member), 245

(C++ member), 238

esp_ble_mesh_cfg_model_sub_list_cb_t::eelsepm_ebnlte__amdedsrh_cfg_model_sub_va_overwrite_t::model_

(C++ member), 245

(C++ member), 238

esp_ble_mesh_cfg_model_sub_list_cb_t::meosdpe_lb_lied_mesh_cfg_net_key_add_t (C++

(C++ member), 245

class), 235

esp_ble_mesh_cfg_model_sub_list_cb_t::setsapt_ubsle_mesh_cfg_net_key_add_t::net_idx

(C++ member), 245

(C++ member), 235

esp_ble_mesh_cfg_model_sub_list_cb_t::seusbp__abdlder_mesh_cfg_net_key_add_t::net_key

(C++ member), 245

(C++ member), 235

esp_ble_mesh_cfg_model_sub_overwrite_t esp_ble_mesh_cfg_net_key_delete_t

(C++ class), 237

(C++ class), 239

esp_ble_mesh_cfg_model_sub_overwrite_t:e:scpo_mbplaen_ym_eisdh_cfg_net_key_delete_t::net_idx

(C++ member), 237

(C++ member), 239

esp_ble_mesh_cfg_model_sub_overwrite_t:e:sepl_ebmleen_tm_easdhd_rcfg_net_key_list_cb_t

(C++ member), 237

(C++ class), 245

esp_ble_mesh_cfg_model_sub_overwrite_t:e:smpo_dbelle__imdesh_cfg_net_key_list_cb_t::net_idx

(C++ member), 237

(C++ member), 245

esp_ble_mesh_cfg_model_sub_overwrite_t:e:sspu_bb_laed_dmresh_cfg_net_key_status_cb_t

(C++ member), 237

(C++ class), 243

esp_ble_mesh_cfg_model_sub_status_cb_t esp_ble_mesh_cfg_net_key_status_cb_t::net_idx

(C++ class), 242

(C++ member), 243

esp_ble_mesh_cfg_model_sub_status_cb_t:e:scpo_mbplaen_ym_eisdh_cfg_net_key_status_cb_t::status

(C++ member), 243

(C++ member), 243

esp_ble_mesh_cfg_model_sub_status_cb_t:e:sepl_ebmleen_tm_easdhd_rcfg_net_key_update_t

(C++ member), 243

(C++ class), 239

esp_ble_mesh_cfg_model_sub_status_cb_t:e:smpo_dbelle__imdesh_cfg_net_key_update_t::net_idx

(C++ member), 243

(C++ member), 239

esp_ble_mesh_cfg_model_sub_status_cb_t:e:sspt_abtlues_mesh_cfg_net_key_update_t::net_key

Espressif Systems

2035

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 239

enumerator), 251

esp_ble_mesh_cfg_net_trans_status_cb_t ESP_BLE_MESH_CFG_SERVER_STATE_CHANGE_EVT

(C++ class), 244

(C++ enumerator), 251

esp_ble_mesh_cfg_net_trans_status_cb_t:e:snpe_tb_lter_amness_hc_ocufngt_server_state_change_t

(C++ member), 245

(C++ union), 231

esp_ble_mesh_cfg_net_trans_status_cb_t:e:snpe_tb_lter_amness_hs_tcefpg_server_state_change_t::appkey_ad

(C++ member), 245

(C++ member), 231

esp_ble_mesh_cfg_net_transmit_set_t esp_ble_mesh_cfg_server_state_change_t::appkey_de

(C++ class), 240

(C++ member), 231

esp_ble_mesh_cfg_net_transmit_set_t::neets_pt_rbalnes_mmietsh_cfg_server_state_change_t::appkey_up

(C++ member), 240

(C++ member), 231

esp_ble_mesh_cfg_node_id_status_cb_t esp_ble_mesh_cfg_server_state_change_t::kr_phase_

(C++ class), 245

(C++ member), 231

esp_ble_mesh_cfg_node_id_status_cb_t::iedsepn_tbiltey_mesh_cfg_server_state_change_t::mod_app_b

(C++ member), 245

(C++ member), 231

esp_ble_mesh_cfg_node_id_status_cb_t::neestp__ibdlxe_mesh_cfg_server_state_change_t::mod_app_u

(C++ member), 245

(C++ member), 231

esp_ble_mesh_cfg_node_id_status_cb_t::setsapt_ubsle_mesh_cfg_server_state_change_t::mod_pub_s

(C++ member), 245

(C++ member), 231

esp_ble_mesh_cfg_node_identity_get_t esp_ble_mesh_cfg_server_state_change_t::mod_sub_a

(C++ class), 234

(C++ member), 231

esp_ble_mesh_cfg_node_identity_get_t::neestp__ibdlxe_mesh_cfg_server_state_change_t::mod_sub_d

(C++ member), 234

(C++ member), 231

esp_ble_mesh_cfg_node_identity_set_t esp_ble_mesh_cfg_server_state_change_t::netkey_ad

(C++ class), 240

(C++ member), 231

esp_ble_mesh_cfg_node_identity_set_t::iedsepn_tbiltey_mesh_cfg_server_state_change_t::netkey_de

(C++ member), 240

(C++ member), 231

esp_ble_mesh_cfg_node_identity_set_t::neestp__ibdlxe_mesh_cfg_server_state_change_t::netkey_up

(C++ member), 240

(C++ member), 231

esp_ble_mesh_cfg_relay_set_t (C++ class), esp_ble_mesh_cfg_sig_model_app_get_t

235

(C++ class), 234

esp_ble_mesh_cfg_relay_set_t::relay esp_ble_mesh_cfg_sig_model_app_get_t::element_add

(C++ member), 235

(C++ member), 234

esp_ble_mesh_cfg_relay_set_t::relay_retersapn_sbmliet_mesh_cfg_sig_model_app_get_t::model_id

(C++ member), 235

(C++ member), 234

esp_ble_mesh_cfg_relay_status_cb_t

esp_ble_mesh_cfg_sig_model_sub_get_t

(C++ class), 242

(C++ class), 233

esp_ble_mesh_cfg_relay_status_cb_t::releasyp_ble_mesh_cfg_sig_model_sub_get_t::element_add

(C++ member), 242

(C++ member), 233

esp_ble_mesh_cfg_relay_status_cb_t::retersapn_sbmliet_mesh_cfg_sig_model_sub_get_t::model_id

(C++ member), 242

(C++ member), 233

esp_ble_mesh_cfg_server_cb_event_t

esp_ble_mesh_cfg_srv (C++ class), 232

(C++ enum), 251

esp_ble_mesh_cfg_srv::beacon (C++ mem-

esp_ble_mesh_cfg_server_cb_param_t

ber), 232

(C++ class), 249

esp_ble_mesh_cfg_srv::count (C++ mem-

esp_ble_mesh_cfg_server_cb_param_t::ctx

ber), 232

(C++ member), 250

esp_ble_mesh_cfg_srv::default_ttl

esp_ble_mesh_cfg_server_cb_param_t::model

(C++ member), 232

(C++ member), 250

esp_ble_mesh_cfg_srv::dst (C++ member),

esp_ble_mesh_cfg_server_cb_param_t::value

232

(C++ member), 250

esp_ble_mesh_cfg_srv::expiry (C++ mem-

esp_ble_mesh_cfg_server_cb_t (C++ type),

ber), 232

250

esp_ble_mesh_cfg_srv::feature (C++

esp_ble_mesh_cfg_server_cb_value_t

member), 232

(C++ union), 231

esp_ble_mesh_cfg_srv::friend_state

esp_ble_mesh_cfg_server_cb_value_t::state_chan(Cg+e+ member), 232

(C++ member), 231

esp_ble_mesh_cfg_srv::gatt_proxy (C++

ESP_BLE_MESH_CFG_SERVER_EVT_MAX (C++

member), 232

Espressif Systems

2036

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_mesh_cfg_srv::heartbeat_pub

(C macro), 196

(C++ member), 232

ESP_BLE_MESH_CFG_STATUS_SUCCESS

(C

esp_ble_mesh_cfg_srv::heartbeat_recv_cb

macro), 195

(C++ member), 232

esp_ble_mesh_cfg_status_t (C++ type), 203

esp_ble_mesh_cfg_srv::heartbeat_sub ESP_BLE_MESH_CFG_STATUS_TEMP_UNABLE_TO_CHANGE_STA

(C++ member), 233

(C macro), 196

esp_ble_mesh_cfg_srv::max_hops (C++ ESP_BLE_MESH_CFG_STATUS_UNSPECIFIED_ERROR

member), 232

(C macro), 196

esp_ble_mesh_cfg_srv::min_hops (C++ esp_ble_mesh_cfg_vnd_model_app_get_t

member), 232

(C++ class), 234

esp_ble_mesh_cfg_srv::model (C++ mem- esp_ble_mesh_cfg_vnd_model_app_get_t::company_id

ber), 232

(C++ member), 234

esp_ble_mesh_cfg_srv::net_idx (C++ esp_ble_mesh_cfg_vnd_model_app_get_t::element_add

member), 232

(C++ member), 234

esp_ble_mesh_cfg_srv::net_transmit

esp_ble_mesh_cfg_vnd_model_app_get_t::model_id

(C++ member), 232

(C++ member), 234

esp_ble_mesh_cfg_srv::period (C++ mem- esp_ble_mesh_cfg_vnd_model_sub_get_t

ber), 232

(C++ class), 233

esp_ble_mesh_cfg_srv::relay (C++ mem- esp_ble_mesh_cfg_vnd_model_sub_get_t::company_id

ber), 232

(C++ member), 233

esp_ble_mesh_cfg_srv::relay_retransmit esp_ble_mesh_cfg_vnd_model_sub_get_t::element_add

(C++ member), 232

(C++ member), 233

esp_ble_mesh_cfg_srv::src (C++ member), esp_ble_mesh_cfg_vnd_model_sub_get_t::model_id

232

(C++ member), 233

esp_ble_mesh_cfg_srv::timer (C++ mem- ESP_BLE_MESH_CID_NVAL (C macro), 188

ber), 232

esp_ble_mesh_client_common_param_t

esp_ble_mesh_cfg_srv::ttl (C++ member),

(C++ class), 186

232

esp_ble_mesh_client_common_param_t::ctx

esp_ble_mesh_cfg_srv_t (C++ type), 250

(C++ member), 186

ESP_BLE_MESH_CFG_STATUS_CANNOT_BIND (C esp_ble_mesh_client_common_param_t::model

macro), 196

(C++ member), 186

ESP_BLE_MESH_CFG_STATUS_CANNOT_REMOVE esp_ble_mesh_client_common_param_t::msg_role

(C macro), 196

(C++ member), 186

ESP_BLE_MESH_CFG_STATUS_CANNOT_SET (C esp_ble_mesh_client_common_param_t::msg_timeout

macro), 196

(C++ member), 186

ESP_BLE_MESH_CFG_STATUS_CANNOT_UPDATE esp_ble_mesh_client_common_param_t::opcode

(C macro), 196

(C++ member), 186

ESP_BLE_MESH_CFG_STATUS_FEATURE_NOT_SUPePsOpR_TbElDe_mesh_client_model_deinit (C++

(C macro), 196

function), 214

ESP_BLE_MESH_CFG_STATUS_INSUFFICIENT_REeSsOpU_RbClEeS_mesh_client_model_init (C++

(C macro), 196

function), 214

ESP_BLE_MESH_CFG_STATUS_INVALID_ADDRESSESP_BLE_MESH_CLIENT_MODEL_RECV_PUBLISH_MSG_EVT

(C macro), 195

(C++ enumerator), 210

ESP_BLE_MESH_CFG_STATUS_INVALID_APPKEY esp_ble_mesh_client_model_send_msg

(C macro), 196

(C++ function), 214

ESP_BLE_MESH_CFG_STATUS_INVALID_BINDINGESP_BLE_MESH_CLIENT_MODEL_SEND_TIMEOUT_EVT

(C macro), 196

(C++ enumerator), 210

ESP_BLE_MESH_CFG_STATUS_INVALID_MODEL esp_ble_mesh_client_op_pair_t (C++

(C macro), 196

class), 185

ESP_BLE_MESH_CFG_STATUS_INVALID_NETKEY esp_ble_mesh_client_op_pair_t::cli_op

(C macro), 196

(C++ member), 186

ESP_BLE_MESH_CFG_STATUS_INVALID_PUBLISHe_sPpA_RbAlMeE_TmEeRsSh_client_op_pair_t::status_op

(C macro), 196

(C++ member), 186

ESP_BLE_MESH_CFG_STATUS_KEY_INDEX_ALREAeDsYp__SbTlOeR_EmDesh_client_t (C++ class), 186

(C macro), 196

esp_ble_mesh_client_t::internal_data

ESP_BLE_MESH_CFG_STATUS_NOT_A_SUBSCRIBE_MODEL (C++ member), 186

(C macro), 196

esp_ble_mesh_client_t::model (C++ mem-

ESP_BLE_MESH_CFG_STATUS_STORAGE_FAILURE

ber), 186

Espressif Systems

2037

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_mesh_client_t::msg_role (C++

macro), 258

member), 186

ESP_BLE_MESH_DEVICE_NAME_MAX_LEN (C

esp_ble_mesh_client_t::op_pair (C++

macro), 188

member), 186

ESP_BLE_MESH_DISPLAY_NUMBER (C++ enumer-

esp_ble_mesh_client_t::op_pair_size

ator), 204

(C++ member), 186

ESP_BLE_MESH_DISPLAY_STRING (C++ enumer-

esp_ble_mesh_client_t::publish_status

ator), 204

(C++ member), 186

esp_ble_mesh_elem_t (C++ class), 180

esp_ble_mesh_comp_t (C++ class), 183

esp_ble_mesh_elem_t::element_addr

esp_ble_mesh_comp_t::cid (C++ member),

(C++ member), 180

183

esp_ble_mesh_elem_t::location (C++

esp_ble_mesh_comp_t::element_count

member), 180

(C++ member), 183

esp_ble_mesh_elem_t::sig_model_count

esp_ble_mesh_comp_t::elements (C++

(C++ member), 180

member), 183

esp_ble_mesh_elem_t::sig_models (C++

esp_ble_mesh_comp_t::pid (C++ member),

member), 180

183

esp_ble_mesh_elem_t::vnd_model_count

esp_ble_mesh_comp_t::vid (C++ member),

(C++ member), 180

183

esp_ble_mesh_elem_t::vnd_models (C++

ESP_BLE_MESH_CONDENSATION_ERROR

(C

member), 180

macro), 257

ESP_BLE_MESH_ELEMENT (C macro), 190

ESP_BLE_MESH_CONDENSATION_WARNING (C ESP_BLE_MESH_ELEMENT_NOT_CALIBRATED_ERROR

macro), 257

(C macro), 258

esp_ble_mesh_config_client_get_state ESP_BLE_MESH_ELEMENT_NOT_CALIBRATED_WARNING

(C++ function), 227

(C macro), 258

esp_ble_mesh_config_client_set_state ESP_BLE_MESH_EMPTY_ERROR (C macro), 258

(C++ function), 227

ESP_BLE_MESH_EMPTY_WARNING (C macro), 258

ESP_BLE_MESH_CONFIGURATION_ERROR (C ESP_BLE_MESH_ENTER_NUMBER (C++ enumera-

macro), 257

tor), 204

ESP_BLE_MESH_CONFIGURATION_WARNING (C ESP_BLE_MESH_ENTER_STRING (C++ enumera-

macro), 257

tor), 204

esp_ble_mesh_deinit (C++ function), 210

esp_ble_mesh_fast_prov_action_t (C++

ESP_BLE_MESH_DEINIT_MESH_COMP_EVT

enum), 205

(C++ enumerator), 209

esp_ble_mesh_fast_prov_info_t (C++

esp_ble_mesh_deinit_param_t (C++ class),

class), 185

180

esp_ble_mesh_fast_prov_info_t::flags

esp_ble_mesh_deinit_param_t::erase_flash

(C++ member), 185

(C++ member), 180

esp_ble_mesh_fast_prov_info_t::iv_index

esp_ble_mesh_dev_add_flag_t (C++ type),

(C++ member), 185

203

esp_ble_mesh_fast_prov_info_t::match_len

esp_ble_mesh_dev_role_t (C++ enum), 205

(C++ member), 185

esp_ble_mesh_device_delete_t (C++ class), esp_ble_mesh_fast_prov_info_t::match_val

184

(C++ member), 185

esp_ble_mesh_device_delete_t::addr

esp_ble_mesh_fast_prov_info_t::net_idx

(C++ member), 184

(C++ member), 185

esp_ble_mesh_device_delete_t::addr_typeesp_ble_mesh_fast_prov_info_t::offset

(C++ member), 184

(C++ member), 185

esp_ble_mesh_device_delete_t::flag

esp_ble_mesh_fast_prov_info_t::unicast_max

(C++ member), 184

(C++ member), 185

esp_ble_mesh_device_delete_t::uuid

esp_ble_mesh_fast_prov_info_t::unicast_min

(C++ member), 184

(C++ member), 185

ESP_BLE_MESH_DEVICE_DROPPED_ERROR (C ESP_BLE_MESH_FEATURE_ALL_SUPPORTED (C

macro), 258

macro), 189

ESP_BLE_MESH_DEVICE_DROPPED_WARNING (C ESP_BLE_MESH_FEATURE_FRIEND (C macro),

macro), 258

189

ESP_BLE_MESH_DEVICE_MOVED_ERROR

(C ESP_BLE_MESH_FEATURE_LOW_POWER

(C

macro), 258

macro), 189

ESP_BLE_MESH_DEVICE_MOVED_WARNING (C ESP_BLE_MESH_FEATURE_PROXY (C macro), 189

Espressif Systems

2038

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

ESP_BLE_MESH_FEATURE_RELAY (C macro), 189

(C++ member), 267

esp_ble_mesh_find_element (C++ function), esp_ble_mesh_gen_admin_property_status_cb_t

211

(C++ class), 271

esp_ble_mesh_find_sig_model (C++ func- esp_ble_mesh_gen_admin_property_status_cb_t::op_e

tion), 211

(C++ member), 271

esp_ble_mesh_find_vendor_model (C++ esp_ble_mesh_gen_admin_property_status_cb_t::prop

function), 211

(C++ member), 271

ESP_BLE_MESH_FRIEND_DISABLED (C macro), esp_ble_mesh_gen_admin_property_status_cb_t::prop

189

(C++ member), 271

ESP_BLE_MESH_FRIEND_ENABLED (C macro), esp_ble_mesh_gen_admin_property_status_cb_t::user

189

(C++ member), 271

ESP_BLE_MESH_FRIEND_FRIENDSHIP_ESTABLISeHs_pE_VbTle_mesh_gen_battery_srv_t (C++

(C++ enumerator), 208

class), 275

ESP_BLE_MESH_FRIEND_FRIENDSHIP_TERMINATeEs_pE_VbTle_mesh_gen_battery_srv_t::model

(C++ enumerator), 208

(C++ member), 276

ESP_BLE_MESH_FRIEND_NOT_SUPPORTED (C esp_ble_mesh_gen_battery_srv_t::rsp_ctrl

macro), 189

(C++ member), 276

ESP_BLE_MESH_GATT_PROXY_DISABLED (C esp_ble_mesh_gen_battery_srv_t::state

macro), 189

(C++ member), 276

ESP_BLE_MESH_GATT_PROXY_ENABLED

(C esp_ble_mesh_gen_battery_state_t (C++

macro), 189

class), 275

ESP_BLE_MESH_GATT_PROXY_NOT_SUPPORTED esp_ble_mesh_gen_battery_state_t::battery_flags

(C macro), 189

(C++ member), 275

ESP_BLE_MESH_GEN_ADMIN_ACCESS_READ

esp_ble_mesh_gen_battery_state_t::battery_level

(C++ enumerator), 289

(C++ member), 275

ESP_BLE_MESH_GEN_ADMIN_ACCESS_READ_WRITeEsp_ble_mesh_gen_battery_state_t::time_to_charge

(C++ enumerator), 289

(C++ member), 275

ESP_BLE_MESH_GEN_ADMIN_ACCESS_WRITE esp_ble_mesh_gen_battery_state_t::time_to_dischar

(C++ enumerator), 289

(C++ member), 275

ESP_BLE_MESH_GEN_ADMIN_NOT_USER_PROP esp_ble_mesh_gen_battery_status_cb_t

(C++ enumerator), 289

(C++ class), 269

esp_ble_mesh_gen_admin_prop_access_t esp_ble_mesh_gen_battery_status_cb_t::battery_lev

(C++ enum), 289

(C++ member), 270

esp_ble_mesh_gen_admin_prop_srv_t

esp_ble_mesh_gen_battery_status_cb_t::flags

(C++ class), 277

(C++ member), 270

esp_ble_mesh_gen_admin_prop_srv_t::modeelsp_ble_mesh_gen_battery_status_cb_t::time_to_cha

(C++ member), 277

(C++ member), 270

esp_ble_mesh_gen_admin_prop_srv_t::propeesrpt_ibelse_mesh_gen_battery_status_cb_t::time_to_dis

(C++ member), 277

(C++ member), 270

esp_ble_mesh_gen_admin_prop_srv_t::propeesrpt_yb_lceo_umnetsh_gen_client_prop_srv_t

(C++ member), 277

(C++ class), 278

esp_ble_mesh_gen_admin_prop_srv_t::rsp_ecstpr_lble_mesh_gen_client_prop_srv_t::id_count

(C++ member), 277

(C++ member), 278

esp_ble_mesh_gen_admin_properties_statuess_pc_bb_lte_mesh_gen_client_prop_srv_t::model

(C++ class), 271

(C++ member), 278

esp_ble_mesh_gen_admin_properties_statuess_pc_bb_lte:_:mpersohp_egretny__cildisent_prop_srv_t::property_ids

(C++ member), 271

(C++ member), 278

esp_ble_mesh_gen_admin_property_get_t esp_ble_mesh_gen_client_prop_srv_t::rsp_ctrl

(C++ class), 267

(C++ member), 278

esp_ble_mesh_gen_admin_property_get_t::epsrpo_pbelret_ym_eisdh_gen_client_properties_get_t

(C++ member), 267

(C++ class), 268

esp_ble_mesh_gen_admin_property_set_t esp_ble_mesh_gen_client_properties_get_t::propert

(C++ class), 267

(C++ member), 268

esp_ble_mesh_gen_admin_property_set_t::epsrpo_pbelret_ym_eisdh_gen_client_properties_status_cb_t

(C++ member), 267

(C++ class), 272

esp_ble_mesh_gen_admin_property_set_t::epsrpo_pbelret_ym_evsahl_ugeen_client_properties_status_cb_t::p

(C++ member), 267

(C++ member), 272

esp_ble_mesh_gen_admin_property_set_t::eusspe_rb_laec_cmeesssh_gen_client_status_cb_t

Espressif Systems

2039

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ union), 261

265

esp_ble_mesh_gen_client_status_cb_t::ademsipn__bplreo_pmeersthi_egse_ns_tdaetlutsa_set_t::delay

(C++ member), 262

(C++ member), 265

esp_ble_mesh_gen_client_status_cb_t::ademsipn__bplreo_pmeersthy__gsetna_tdueslta_set_t::level

(C++ member), 262

(C++ member), 265

esp_ble_mesh_gen_client_status_cb_t::baetstpe_rbyl_es_tmaetsuhs_gen_delta_set_t::op_en

(C++ member), 262

(C++ member), 265

esp_ble_mesh_gen_client_status_cb_t::cleisepn_tb_lper_ompeesrht_igeesn__sdtealttuas_set_t::tid

(C++ member), 262

(C++ member), 265

esp_ble_mesh_gen_client_status_cb_t::deefs_pt_rbalnes__mteismhe__gsetna_tdueslta_set_t::trans_time

(C++ member), 261

(C++ member), 265

esp_ble_mesh_gen_client_status_cb_t::leevsepl__bsltea_tmuessh_gen_level_set_t (C++ class),

(C++ member), 261

264

esp_ble_mesh_gen_client_status_cb_t::loecsapt_ibolne__gmleosbha_lg_esnt_alteuvsel_set_t::delay

(C++ member), 262

(C++ member), 264

esp_ble_mesh_gen_client_status_cb_t::loecsapt_ibolne__lmoecsahl__gsetna_tluesvel_set_t::level

(C++ member), 262

(C++ member), 264

esp_ble_mesh_gen_client_status_cb_t::maensupf_abclteu_rmeers_hp_rgoepne_rlteiveesl__ssteatt_uts::op_en

(C++ member), 262

(C++ member), 264

esp_ble_mesh_gen_client_status_cb_t::maensupf_abclteu_rmeers_hp_rgoepne_rlteyv_eslt_asteuts_t::tid

(C++ member), 262

(C++ member), 264

esp_ble_mesh_gen_client_status_cb_t::oneosfpf__bsltea_tmuessh_gen_level_set_t::trans_time

(C++ member), 261

(C++ member), 264

esp_ble_mesh_gen_client_status_cb_t::onepsopw_ebrluep__msetsaht_ugsen_level_srv_t (C++ class),

(C++ member), 261

273

esp_ble_mesh_gen_client_status_cb_t::poewsepr__bdleef_amuelsth__sgteant_ulsevel_srv_t::last

(C++ member), 261

(C++ member), 273

esp_ble_mesh_gen_client_status_cb_t::poewsepr__bllaes_tm_esstha_tguesn_level_srv_t::model

(C++ member), 261

(C++ member), 273

esp_ble_mesh_gen_client_status_cb_t::poewsepr__blleev_emle_ssht_agteuns_level_srv_t::rsp_ctrl

(C++ member), 261

(C++ member), 273

esp_ble_mesh_gen_client_status_cb_t::poewsepr__brlaen_gmee_ssht_agteuns_level_srv_t::state

(C++ member), 261

(C++ member), 273

esp_ble_mesh_gen_client_status_cb_t::useesrp__pbrloep_emretsihe_sg_esnt_alteuvsel_srv_t::transition

(C++ member), 262

(C++ member), 273

esp_ble_mesh_gen_client_status_cb_t::useesrp__pbrloep_emretsyh__sgteant_ulsevel_srv_t::tt_delta_level

(C++ member), 262

(C++ member), 273

esp_ble_mesh_gen_def_trans_time_set_t esp_ble_mesh_gen_level_state_t (C++

(C++ class), 265

class), 272

esp_ble_mesh_gen_def_trans_time_set_t::etsrpa_nbsl_et_immeesh_gen_level_state_t::last_delta

(C++ member), 265

(C++ member), 273

esp_ble_mesh_gen_def_trans_time_srv_t esp_ble_mesh_gen_level_state_t::last_level

(C++ class), 273

(C++ member), 273

esp_ble_mesh_gen_def_trans_time_srv_t::emsopd_eblle_mesh_gen_level_state_t::level

(C++ member), 273

(C++ member), 273

esp_ble_mesh_gen_def_trans_time_srv_t::ersspp__bclter_lmesh_gen_level_state_t::move_start

(C++ member), 273

(C++ member), 273

esp_ble_mesh_gen_def_trans_time_srv_t::esstpa_tbele_mesh_gen_level_state_t::positive

(C++ member), 274

(C++ member), 273

esp_ble_mesh_gen_def_trans_time_state_tesp_ble_mesh_gen_level_state_t::target_level

(C++ class), 273

(C++ member), 273

esp_ble_mesh_gen_def_trans_time_state_te:s:pt_rbalnes__mteismhe_gen_level_status_cb_t

(C++ member), 273

(C++ class), 268

esp_ble_mesh_gen_def_trans_time_status_ecsbp__tble_mesh_gen_level_status_cb_t::op_en

(C++ class), 268

(C++ member), 268

esp_ble_mesh_gen_def_trans_time_status_ecsbp__tb:l:et_rmaenssh__tgiemne_level_status_cb_t::present_level

(C++ member), 268

(C++ member), 268

esp_ble_mesh_gen_delta_set_t (C++ class), esp_ble_mesh_gen_level_status_cb_t::remain_time

Espressif Systems

2040

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 268

(C++ member), 276

esp_ble_mesh_gen_level_status_cb_t::taregsept__blleev_emlesh_gen_location_state_t

(C++ member), 268

(C++ class), 276

esp_ble_mesh_gen_loc_global_set_t

esp_ble_mesh_gen_location_state_t::floor_number

(C++ class), 266

(C++ member), 276

esp_ble_mesh_gen_loc_global_set_t::globeaslp__ablltei_tmuedseh_gen_location_state_t::global_altitud

(C++ member), 266

(C++ member), 276

esp_ble_mesh_gen_loc_global_set_t::globeaslp__lbaltei_tmuedseh_gen_location_state_t::global_latitud

(C++ member), 266

(C++ member), 276

esp_ble_mesh_gen_loc_global_set_t::globeaslp__lbolneg_imteusdhe_gen_location_state_t::global_longitu

(C++ member), 266

(C++ member), 276

esp_ble_mesh_gen_loc_global_status_cb_tesp_ble_mesh_gen_location_state_t::local_altitude

(C++ class), 270

(C++ member), 276

esp_ble_mesh_gen_loc_global_status_cb_te:s:pg_lbolbea_lm_easlht_igteund_elocation_state_t::local_east

(C++ member), 270

(C++ member), 276

esp_ble_mesh_gen_loc_global_status_cb_te:s:pg_lbolbea_lm_elsaht_igteund_elocation_state_t::local_north

(C++ member), 270

(C++ member), 276

esp_ble_mesh_gen_loc_global_status_cb_te:s:pg_lbolbea_lm_elsohn_ggietnu_dleocation_state_t::uncertainty

(C++ member), 270

(C++ member), 276

esp_ble_mesh_gen_loc_local_set_t (C++ ESP_BLE_MESH_GEN_MANU_ACCESS_READ

class), 266

(C++ enumerator), 290

esp_ble_mesh_gen_loc_local_set_t::floorE_SnPu_mBbLeEr_MESH_GEN_MANU_NOT_USER_PROP

(C++ member), 267

(C++ enumerator), 289

esp_ble_mesh_gen_loc_local_set_t::locale_sapl_tbilteu_dmeesh_gen_manu_prop_access_t

(C++ member), 266

(C++ enum), 289

esp_ble_mesh_gen_loc_local_set_t::locale_sepa_sbtle_mesh_gen_manu_prop_srv_t (C++

(C++ member), 266

class), 277

esp_ble_mesh_gen_loc_local_set_t::locale_snpo_rbtlhe_mesh_gen_manu_prop_srv_t::model

(C++ member), 266

(C++ member), 278

esp_ble_mesh_gen_loc_local_set_t::unceretsapi_nbtlye_mesh_gen_manu_prop_srv_t::properties

(C++ member), 267

(C++ member), 278

esp_ble_mesh_gen_loc_local_status_cb_t esp_ble_mesh_gen_manu_prop_srv_t::property_count

(C++ class), 270

(C++ member), 278

esp_ble_mesh_gen_loc_local_status_cb_t:e:sfpl_obolre__nmuemsbhe_rgen_manu_prop_srv_t::rsp_ctrl

(C++ member), 270

(C++ member), 278

esp_ble_mesh_gen_loc_local_status_cb_t:e:slpo_cballe__amletsiht_ugdeen_manufacturer_properties_status_c

(C++ member), 270

(C++ class), 271

esp_ble_mesh_gen_loc_local_status_cb_t:e:slpo_cballe__emaessth_gen_manufacturer_properties_status_c

(C++ member), 270

(C++ member), 271

esp_ble_mesh_gen_loc_local_status_cb_t:e:slpo_cballe__nmoersthh_gen_manufacturer_property_get_t

(C++ member), 270

(C++ class), 267

esp_ble_mesh_gen_loc_local_status_cb_t:e:supn_cbelret_amiensthy_gen_manufacturer_property_get_t::pro

(C++ member), 270

(C++ member), 267

esp_ble_mesh_gen_location_setup_srv_t esp_ble_mesh_gen_manufacturer_property_set_t

(C++ class), 276

(C++ class), 267

esp_ble_mesh_gen_location_setup_srv_t::emsopd_eblle_mesh_gen_manufacturer_property_set_t::pro

(C++ member), 276

(C++ member), 268

esp_ble_mesh_gen_location_setup_srv_t::ersspp__bclter_lmesh_gen_manufacturer_property_set_t::use

(C++ member), 276

(C++ member), 268

esp_ble_mesh_gen_location_setup_srv_t::esstpa_tbele_mesh_gen_manufacturer_property_status_cb_

(C++ member), 277

(C++ class), 271

esp_ble_mesh_gen_location_srv_t (C++ esp_ble_mesh_gen_manufacturer_property_status_cb_

class), 276

(C++ member), 271

esp_ble_mesh_gen_location_srv_t::model esp_ble_mesh_gen_manufacturer_property_status_cb_

(C++ member), 276

(C++ member), 271

esp_ble_mesh_gen_location_srv_t::rsp_cterslp_ble_mesh_gen_manufacturer_property_status_cb_

(C++ member), 276

(C++ member), 271

esp_ble_mesh_gen_location_srv_t::state esp_ble_mesh_gen_manufacturer_property_status_cb_

Espressif Systems

2041

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 271

(C++ class), 274

esp_ble_mesh_gen_move_set_t (C++ class), esp_ble_mesh_gen_onpowerup_state_t::onpowerup

265

(C++ member), 274

esp_ble_mesh_gen_move_set_t::delay

esp_ble_mesh_gen_onpowerup_status_cb_t

(C++ member), 265

(C++ class), 268

esp_ble_mesh_gen_move_set_t::delta_leveelsp_ble_mesh_gen_onpowerup_status_cb_t::onpowerup

(C++ member), 265

(C++ member), 269

esp_ble_mesh_gen_move_set_t::op_en

esp_ble_mesh_gen_power_default_set_t

(C++ member), 265

(C++ class), 266

esp_ble_mesh_gen_move_set_t::tid (C++ esp_ble_mesh_gen_power_default_set_t::power

member), 265

(C++ member), 266

esp_ble_mesh_gen_move_set_t::trans_timeesp_ble_mesh_gen_power_default_status_cb_t

(C++ member), 265

(C++ class), 269

esp_ble_mesh_gen_onoff_set_t (C++ class), esp_ble_mesh_gen_power_default_status_cb_t::power

264

(C++ member), 269

esp_ble_mesh_gen_onoff_set_t::delay esp_ble_mesh_gen_power_last_status_cb_t

(C++ member), 264

(C++ class), 269

esp_ble_mesh_gen_onoff_set_t::onoff esp_ble_mesh_gen_power_last_status_cb_t::power

(C++ member), 264

(C++ member), 269

esp_ble_mesh_gen_onoff_set_t::op_en esp_ble_mesh_gen_power_level_set_t

(C++ member), 264

(C++ class), 265

esp_ble_mesh_gen_onoff_set_t::tid

esp_ble_mesh_gen_power_level_set_t::delay

(C++ member), 264

(C++ member), 266

esp_ble_mesh_gen_onoff_set_t::trans_timeesp_ble_mesh_gen_power_level_set_t::op_en

(C++ member), 264

(C++ member), 266

esp_ble_mesh_gen_onoff_srv_t (C++ class), esp_ble_mesh_gen_power_level_set_t::power

272

(C++ member), 266

esp_ble_mesh_gen_onoff_srv_t::last

esp_ble_mesh_gen_power_level_set_t::tid

(C++ member), 272

(C++ member), 266

esp_ble_mesh_gen_onoff_srv_t::model esp_ble_mesh_gen_power_level_set_t::trans_time

(C++ member), 272

(C++ member), 266

esp_ble_mesh_gen_onoff_srv_t::rsp_ctrl esp_ble_mesh_gen_power_level_setup_srv_t

(C++ member), 272

(C++ class), 275

esp_ble_mesh_gen_onoff_srv_t::state esp_ble_mesh_gen_power_level_setup_srv_t::model

(C++ member), 272

(C++ member), 275

esp_ble_mesh_gen_onoff_srv_t::transitioensp_ble_mesh_gen_power_level_setup_srv_t::rsp_ctr

(C++ member), 272

(C++ member), 275

esp_ble_mesh_gen_onoff_state_t (C++ esp_ble_mesh_gen_power_level_setup_srv_t::state

class), 272

(C++ member), 275

esp_ble_mesh_gen_onoff_state_t::onoff esp_ble_mesh_gen_power_level_srv_t

(C++ member), 272

(C++ class), 275

esp_ble_mesh_gen_onoff_state_t::target_eosnpo_fbfle_mesh_gen_power_level_srv_t::last

(C++ member), 272

(C++ member), 275

esp_ble_mesh_gen_onoff_status_cb_t

esp_ble_mesh_gen_power_level_srv_t::model

(C++ class), 268

(C++ member), 275

esp_ble_mesh_gen_onoff_status_cb_t::op_eesnp_ble_mesh_gen_power_level_srv_t::rsp_ctrl

(C++ member), 268

(C++ member), 275

esp_ble_mesh_gen_onoff_status_cb_t::preessepn_tb_loen_omfefsh_gen_power_level_srv_t::state

(C++ member), 268

(C++ member), 275

esp_ble_mesh_gen_onoff_status_cb_t::remeasipn__btliem_emesh_gen_power_level_srv_t::transition

(C++ member), 268

(C++ member), 275

esp_ble_mesh_gen_onoff_status_cb_t::taregsept__bolneo_fmfesh_gen_power_level_srv_t::tt_delta_leve

(C++ member), 268

(C++ member), 275

esp_ble_mesh_gen_onpowerup_set_t (C++ esp_ble_mesh_gen_power_level_state_t

class), 265

(C++ class), 274

esp_ble_mesh_gen_onpowerup_set_t::onpoweesrpu_pble_mesh_gen_power_level_state_t::power_actua

(C++ member), 265

(C++ member), 274

esp_ble_mesh_gen_onpowerup_state_t

esp_ble_mesh_gen_power_level_state_t::power_defau

Espressif Systems

2042

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 274

(C++ enumerator), 289

esp_ble_mesh_gen_power_level_state_t::peoswpe_rb_llea_smtesh_gen_user_prop_access_t

(C++ member), 274

(C++ enum), 289

esp_ble_mesh_gen_power_level_state_t::peoswpe_rb_lrea_nmgees_hm_agxen_user_prop_srv_t (C++

(C++ member), 275

class), 277

esp_ble_mesh_gen_power_level_state_t::peoswpe_rb_lrea_nmgees_hm_ignen_user_prop_srv_t::model

(C++ member), 274

(C++ member), 277

esp_ble_mesh_gen_power_level_state_t::setsapt_ubsl_ec_omdeesh_gen_user_prop_srv_t::properties

(C++ member), 274

(C++ member), 277

esp_ble_mesh_gen_power_level_state_t::teasrpg_ebtl_ep_omweesrh__agcetnu_aulser_prop_srv_t::property_count

(C++ member), 274

(C++ member), 277

esp_ble_mesh_gen_power_level_status_cb_etsp_ble_mesh_gen_user_prop_srv_t::rsp_ctrl

(C++ class), 269

(C++ member), 277

esp_ble_mesh_gen_power_level_status_cb_ets:p:_obpl_ee_nmesh_gen_user_properties_status_cb_t

(C++ member), 269

(C++ class), 270

esp_ble_mesh_gen_power_level_status_cb_ets:p:_pbrlees_emnets_hp_ogweenr_user_properties_status_cb_t::pro

(C++ member), 269

(C++ member), 270

esp_ble_mesh_gen_power_level_status_cb_ets:p:_rbelmea_imne_sthi_mgeen_user_property_get_t

(C++ member), 269

(C++ class), 267

esp_ble_mesh_gen_power_level_status_cb_ets:p:_tbalreg_emte_spho_wgeern_user_property_get_t::property_id

(C++ member), 269

(C++ member), 267

esp_ble_mesh_gen_power_onoff_setup_srv_etsp_ble_mesh_gen_user_property_set_t

(C++ class), 274

(C++ class), 267

esp_ble_mesh_gen_power_onoff_setup_srv_ets:p:_mboldee_lmesh_gen_user_property_set_t::property_id

(C++ member), 274

(C++ member), 267

esp_ble_mesh_gen_power_onoff_setup_srv_ets:p:_rbslpe__cmterslh_gen_user_property_set_t::property_va

(C++ member), 274

(C++ member), 267

esp_ble_mesh_gen_power_onoff_setup_srv_ets:p:_sbtlaet_emesh_gen_user_property_status_cb_t

(C++ member), 274

(C++ class), 270

esp_ble_mesh_gen_power_onoff_srv_t

esp_ble_mesh_gen_user_property_status_cb_t::op_en

(C++ class), 274

(C++ member), 271

esp_ble_mesh_gen_power_onoff_srv_t::modeeslp_ble_mesh_gen_user_property_status_cb_t::prope

(C++ member), 274

(C++ member), 271

esp_ble_mesh_gen_power_onoff_srv_t::rspe_scpt_rblle_mesh_gen_user_property_status_cb_t::prope

(C++ member), 274

(C++ member), 271

esp_ble_mesh_gen_power_onoff_srv_t::staetsep_ble_mesh_gen_user_property_status_cb_t::user_

(C++ member), 274

(C++ member), 271

esp_ble_mesh_gen_power_range_set_t

esp_ble_mesh_generic_client_cb_event_t

(C++ class), 266

(C++ enum), 289

esp_ble_mesh_gen_power_range_set_t::ranegsep__mbalxe_mesh_generic_client_cb_param_t

(C++ member), 266

(C++ class), 272

esp_ble_mesh_gen_power_range_set_t::ranegsep__mbilne_mesh_generic_client_cb_param_t::error_cod

(C++ member), 266

(C++ member), 272

esp_ble_mesh_gen_power_range_status_cb_etsp_ble_mesh_generic_client_cb_param_t::params

(C++ class), 269

(C++ member), 272

esp_ble_mesh_gen_power_range_status_cb_ets:p:_rbalneg_em_emsahx_generic_client_cb_param_t::status_cb

(C++ member), 269

(C++ member), 272

esp_ble_mesh_gen_power_range_status_cb_ets:p:_rbalneg_em_emsihn_generic_client_cb_t (C++

(C++ member), 269

type), 289

esp_ble_mesh_gen_power_range_status_cb_EtS:P:_sBtLaEt_uMsE_ScHo_dGeENERIC_CLIENT_EVT_MAX

(C++ member), 269

(C++ enumerator), 289

ESP_BLE_MESH_GEN_USER_ACCESS_PROHIBIT esp_ble_mesh_generic_client_get_state

(C++ enumerator), 289

(C++ function), 259

ESP_BLE_MESH_GEN_USER_ACCESS_READ

ESP_BLE_MESH_GENERIC_CLIENT_GET_STATE_EVT

(C++ enumerator), 289

(C++ enumerator), 289

ESP_BLE_MESH_GEN_USER_ACCESS_READ_WRITEesp_ble_mesh_generic_client_get_state_t

(C++ enumerator), 289

(C++ union), 260

ESP_BLE_MESH_GEN_USER_ACCESS_WRITE

esp_ble_mesh_generic_client_get_state_t::admin_pr

Espressif Systems

2043

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 260

(C++ member), 277

esp_ble_mesh_generic_client_get_state_te:s:pc_lbileen_tm_epsrho_pgeernteireisc__gpertoperty_t::id

(C++ member), 260

(C++ member), 277

esp_ble_mesh_generic_client_get_state_te:s:pm_abnluef_amcetsuhr_egre_nperroipce_rptryo_pgeertty_t::manu_access

(C++ member), 260

(C++ member), 277

esp_ble_mesh_generic_client_get_state_te:s:pu_sbelre__pmreosphe_rgteyn_egreitc_property_t::user_access

(C++ member), 260

(C++ member), 277

ESP_BLE_MESH_GENERIC_CLIENT_PUBLISH_EVTesp_ble_mesh_generic_property_t::val

(C++ enumerator), 289

(C++ member), 277

esp_ble_mesh_generic_client_set_state esp_ble_mesh_generic_server_cb_event_t

(C++ function), 260

(C++ enum), 290

ESP_BLE_MESH_GENERIC_CLIENT_SET_STATE_EeVsTp_ble_mesh_generic_server_cb_param_t

(C++ enumerator), 289

(C++ class), 285

esp_ble_mesh_generic_client_set_state_tesp_ble_mesh_generic_server_cb_param_t::ctx

(C++ union), 260

(C++ member), 285

esp_ble_mesh_generic_client_set_state_te:s:pa_dbmlien__mpersohp_egretnye_rsiect_server_cb_param_t::model

(C++ member), 261

(C++ member), 285

esp_ble_mesh_generic_client_set_state_te:s:pd_ebfl_et_rmaenssh__tgiemnee_rsiect_server_cb_param_t::value

(C++ member), 260

(C++ member), 285

esp_ble_mesh_generic_client_set_state_te:s:pd_eblltea__mseesth_generic_server_cb_t (C++

(C++ member), 260

type), 289

esp_ble_mesh_generic_client_set_state_te:s:pl_ebvleel__mseesth_generic_server_cb_value_t

(C++ member), 260

(C++ union), 264

esp_ble_mesh_generic_client_set_state_te:s:pl_obcl_eg_lmoebsahl__gseenteric_server_cb_value_t::get

(C++ member), 261

(C++ member), 264

esp_ble_mesh_generic_client_set_state_te:s:pl_obcl_el_omceaslh__sgeetneric_server_cb_value_t::set

(C++ member), 261

(C++ member), 264

esp_ble_mesh_generic_client_set_state_te:s:pm_abnluef_amcetsuhr_egre_nperroipce_rsteyr_vseert_cb_value_t::state_cha

(C++ member), 261

(C++ member), 264

esp_ble_mesh_generic_client_set_state_tE:S:Pm_oBvLeE__sMeEtSH_GENERIC_SERVER_EVT_MAX

(C++ member), 260

(C++ enumerator), 290

esp_ble_mesh_generic_client_set_state_tE:S:Po_nBoLfEf__MsEeStH_GENERIC_SERVER_RECV_GET_MSG_EVT

(C++ member), 260

(C++ enumerator), 290

esp_ble_mesh_generic_client_set_state_te:s:pp_obwleer__mdeesfha_ugletn_esreitc_server_recv_get_msg_t

(C++ member), 261

(C++ union), 263

esp_ble_mesh_generic_client_set_state_te:s:pp_obwleer__mleesvhe_lg_esneetric_server_recv_get_msg_t::admin

(C++ member), 261

(C++ member), 263

esp_ble_mesh_generic_client_set_state_te:s:pp_obwleer__mreasnhg_eg_esneetric_server_recv_get_msg_t::clien

(C++ member), 261

(C++ member), 263

esp_ble_mesh_generic_client_set_state_te:s:pp_obwleer__mseesth_generic_server_recv_get_msg_t::manu_

(C++ member), 261

(C++ member), 263

esp_ble_mesh_generic_client_set_state_te:s:pu_sbelre__pmreosphe_rgteyn_esreitc_server_recv_get_msg_t::user_

(C++ member), 261

(C++ member), 263

ESP_BLE_MESH_GENERIC_CLIENT_TIMEOUT_EVTESP_BLE_MESH_GENERIC_SERVER_RECV_SET_MSG_EVT

(C++ enumerator), 289

(C++ enumerator), 290

ESP_BLE_MESH_GENERIC_LEVEL_STATE (C++ esp_ble_mesh_generic_server_recv_set_msg_t

enumerator), 209

(C++ union), 263

esp_ble_mesh_generic_message_opcode_t esp_ble_mesh_generic_server_recv_set_msg_t::admin

(C++ type), 203

(C++ member), 264

ESP_BLE_MESH_GENERIC_ONOFF_STATE (C++ esp_ble_mesh_generic_server_recv_set_msg_t::def_t

enumerator), 209

(C++ member), 263

ESP_BLE_MESH_GENERIC_ONPOWERUP_STATE esp_ble_mesh_generic_server_recv_set_msg_t::delta

(C++ enumerator), 209

(C++ member), 263

ESP_BLE_MESH_GENERIC_POWER_ACTUAL_STATEesp_ble_mesh_generic_server_recv_set_msg_t::level

(C++ enumerator), 209

(C++ member), 263

esp_ble_mesh_generic_property_t (C++ esp_ble_mesh_generic_server_recv_set_msg_t::locat

class), 277

(C++ member), 263

esp_ble_mesh_generic_property_t::admin_eascpc_ebslse_mesh_generic_server_recv_set_msg_t::locat

Espressif Systems

2044

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 263

(C++ function), 211

esp_ble_mesh_generic_server_recv_set_msEgS_Pt_:B:LmEa_nMuE_SpHr_oGpEeTr_tPyUBLISH_TRANSMIT_COUNT

(C++ member), 264

(C macro), 190

esp_ble_mesh_generic_server_recv_set_msEgS_Pt_:B:LmEo_vMeESH_GET_PUBLISH_TRANSMIT_INTERVAL

(C++ member), 263

(C macro), 190

esp_ble_mesh_generic_server_recv_set_msEgS_Pt_:B:LoEn_oMfEfSH_GET_SENSOR_DATA_FORMAT (C

(C++ member), 263

macro), 303

esp_ble_mesh_generic_server_recv_set_msEgS_Pt_:B:LoEn_pMoEwSeHr_uGpET_SENSOR_DATA_LENGTH (C

(C++ member), 263

macro), 303

esp_ble_mesh_generic_server_recv_set_msEgS_Pt_:B:LpEo_wMeErS_Hd_eGfEaTu_lStENSOR_DATA_PROPERTY_ID

(C++ member), 263

(C macro), 303

esp_ble_mesh_generic_server_recv_set_msEgS_Pt_:B:LpEo_wMeErS_Hl_eGvEeTl_TRANSMIT_COUNT

(C

(C++ member), 263

macro), 189

esp_ble_mesh_generic_server_recv_set_msEgS_Pt_:B:LpEo_wMeErS_Hr_aGnEgTe_TRANSMIT_INTERVAL (C

(C++ member), 263

macro), 189

esp_ble_mesh_generic_server_recv_set_msegs_pt_:b:lues_emre_sphr_ohpeearlttyh_attention_off_cb_t

(C++ member), 263

(C++ class), 256

ESP_BLE_MESH_GENERIC_SERVER_STATE_CHANGeEs_pE_VbTle_mesh_health_attention_off_cb_t::model

(C++ enumerator), 290

(C++ member), 256

esp_ble_mesh_generic_server_state_changees_pt_ble_mesh_health_attention_on_cb_t

(C++ union), 262

(C++ class), 256

esp_ble_mesh_generic_server_state_changees_pt_:b:laed_mmiens_hp_rhoepaelrtthy__astettention_on_cb_t::model

(C++ member), 263

(C++ member), 256

esp_ble_mesh_generic_server_state_changees_pt_:b:ldee_fm_etsrha_nhse_atlitmhe__astettention_on_cb_t::time

(C++ member), 262

(C++ member), 256

esp_ble_mesh_generic_server_state_changees_pt_:b:ldee_lmteas_hs_ehtealth_attention_set_t

(C++ member), 262

(C++ class), 254

esp_ble_mesh_generic_server_state_changees_pt_:b:llee_vmeels_hs_ehtealth_attention_set_t::attention

(C++ member), 262

(C++ member), 254

esp_ble_mesh_generic_server_state_changees_pt_:b:lleo_cm_egslho_bhaela_lsteht_attention_status_cb_t

(C++ member), 262

(C++ class), 255

esp_ble_mesh_generic_server_state_changees_pt_:b:lleo_cm_elsohc_ahle_asletth_attention_status_cb_t::attent

(C++ member), 262

(C++ member), 255

esp_ble_mesh_generic_server_state_changees_pt_:b:lmea_nmue_sphr_ohpeearlttyh__sceltient_cb_event_t

(C++ member), 263

(C++ enum), 259

esp_ble_mesh_generic_server_state_changees_pt_:b:lmeo_vmee_sshe_thealth_client_cb_param_t

(C++ member), 262

(C++ class), 255

esp_ble_mesh_generic_server_state_changees_pt_:b:loen_omfefs_hs_ehtealth_client_cb_param_t::error_code

(C++ member), 262

(C++ member), 255

esp_ble_mesh_generic_server_state_changees_pt_:b:loen_pmoewsehr_uhpe_asletth_client_cb_param_t::params

(C++ member), 262

(C++ member), 255

esp_ble_mesh_generic_server_state_changees_pt_:b:lpeo_wmeers_hd_ehfeaaulltth__sceltient_cb_param_t::status_cb

(C++ member), 262

(C++ member), 255

esp_ble_mesh_generic_server_state_changees_pt_:b:lpeo_wmeers_hl_ehveeall_tshe_tclient_cb_t (C++

(C++ member), 262

type), 258

esp_ble_mesh_generic_server_state_changees_pt_:b:lpeo_wmeers_hr_ahnegael_tshe_tclient_common_cb_param_t

(C++ member), 262

(C++ union), 252

esp_ble_mesh_generic_server_state_changees_pt_:b:lues_emre_sphr_ohpeearlttyh__sceltient_common_cb_param_t::att

(C++ member), 263

(C++ member), 252

esp_ble_mesh_get_composition_data

esp_ble_mesh_health_client_common_cb_param_t::cur

(C++ function), 211

(C++ member), 252

esp_ble_mesh_get_element_count (C++ esp_ble_mesh_health_client_common_cb_param_t::fau

function), 211

(C++ member), 252

esp_ble_mesh_get_fast_prov_app_key

esp_ble_mesh_health_client_common_cb_param_t::per

(C++ function), 220

(C++ member), 252

esp_ble_mesh_get_model_publish_period ESP_BLE_MESH_HEALTH_CLIENT_EVT_MAX

(C++ function), 211

(C++ enumerator), 259

esp_ble_mesh_get_primary_element_addresessp_ble_mesh_health_client_get_state

Espressif Systems

2045

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ function), 251

(C++ class), 256

ESP_BLE_MESH_HEALTH_CLIENT_GET_STATE_EVeTsp_ble_mesh_health_fault_test_cb_t::company_id

(C++ enumerator), 259

(C++ member), 256

esp_ble_mesh_health_client_get_state_t esp_ble_mesh_health_fault_test_cb_t::model

(C++ union), 252

(C++ member), 256

esp_ble_mesh_health_client_get_state_t:e:sfpa_ubllte__gmeetsh_health_fault_test_cb_t::test_id

(C++ member), 252

(C++ member), 256

ESP_BLE_MESH_HEALTH_CLIENT_PUBLISH_EVT esp_ble_mesh_health_fault_test_t (C++

(C++ enumerator), 259

class), 254

esp_ble_mesh_health_client_set_state esp_ble_mesh_health_fault_test_t::company_id

(C++ function), 251

(C++ member), 254

ESP_BLE_MESH_HEALTH_CLIENT_SET_STATE_EVeTsp_ble_mesh_health_fault_test_t::test_id

(C++ enumerator), 259

(C++ member), 254

esp_ble_mesh_health_client_set_state_t esp_ble_mesh_health_fault_update_comp_cb_t

(C++ union), 252

(C++ class), 256

esp_ble_mesh_health_client_set_state_t:e:sapt_tbelnet_imoens_hs_ehtealth_fault_update_comp_cb_t::eleme

(C++ member), 252

(C++ member), 256

esp_ble_mesh_health_client_set_state_t:e:sfpa_ubllte__cmleesahr_health_fault_update_comp_cb_t::error

(C++ member), 252

(C++ member), 256

esp_ble_mesh_health_client_set_state_t:e:sfpa_ubllte__tmeessth_health_model_status_t

(C++ member), 252

(C++ type), 203

esp_ble_mesh_health_client_set_state_t:e:sppe_rbiloed__mseesth_health_period_set_t (C++

(C++ member), 252

class), 254

ESP_BLE_MESH_HEALTH_CLIENT_TIMEOUT_EVT esp_ble_mesh_health_period_set_t::fast_period_div

(C++ enumerator), 259

(C++ member), 254

esp_ble_mesh_health_current_status_cb_tesp_ble_mesh_health_period_status_cb_t

(C++ class), 255

(C++ class), 255

esp_ble_mesh_health_current_status_cb_te:s:pc_obmlpea_nmye_sihd_health_period_status_cb_t::fast_peri

(C++ member), 255

(C++ member), 255

esp_ble_mesh_health_current_status_cb_tE:S:Pf_aBuLlEt__MaErSrHa_yHEALTH_PUB_DEFINE

(C

(C++ member), 255

macro), 257

esp_ble_mesh_health_current_status_cb_tE:S:Pt_eBsLtE__iMdESH_HEALTH_SERVER_ATTENTION_OFF_EVT

(C++ member), 255

(C++ enumerator), 259

ESP_BLE_MESH_HEALTH_FAULT_ARRAY_SIZE ESP_BLE_MESH_HEALTH_SERVER_ATTENTION_ON_EVT

(C macro), 258

(C++ enumerator), 259

esp_ble_mesh_health_fault_clear_cb_t esp_ble_mesh_health_server_cb_event_t

(C++ class), 256

(C++ enum), 259

esp_ble_mesh_health_fault_clear_cb_t::ceosmpp_abnlye__imdesh_health_server_cb_param_t

(C++ member), 256

(C++ union), 252

esp_ble_mesh_health_fault_clear_cb_t::meosdpe_lble_mesh_health_server_cb_param_t::attention_

(C++ member), 256

(C++ member), 253

esp_ble_mesh_health_fault_clear_t

esp_ble_mesh_health_server_cb_param_t::attention_

(C++ class), 254

(C++ member), 253

esp_ble_mesh_health_fault_clear_t::compeasnpy__bilde_mesh_health_server_cb_param_t::fault_clea

(C++ member), 255

(C++ member), 253

esp_ble_mesh_health_fault_get_t (C++ esp_ble_mesh_health_server_cb_param_t::fault_test

class), 254

(C++ member), 253

esp_ble_mesh_health_fault_get_t::companeys_pi_dble_mesh_health_server_cb_param_t::fault_upda

(C++ member), 254

(C++ member), 253

esp_ble_mesh_health_fault_status_cb_t esp_ble_mesh_health_server_cb_t (C++

(C++ class), 255

type), 259

esp_ble_mesh_health_fault_status_cb_t::EcSoPm_pBaLnEy__MiEdSH_HEALTH_SERVER_EVT_MAX

(C++ member), 255

(C++ enumerator), 259

esp_ble_mesh_health_fault_status_cb_t::EfSaPu_lBtL_Ea_rMrEaSyH_HEALTH_SERVER_FAULT_CLEAR_EVT

(C++ member), 255

(C++ enumerator), 259

esp_ble_mesh_health_fault_status_cb_t::EtSePs_tB_LiEd_MESH_HEALTH_SERVER_FAULT_TEST_EVT

(C++ member), 255

(C++ enumerator), 259

esp_ble_mesh_health_fault_test_cb_t esp_ble_mesh_health_server_fault_update

Espressif Systems

2046

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ function), 251

ESP_BLE_MESH_HOUSING_OPENED_WARNING (C

ESP_BLE_MESH_HEALTH_SERVER_FAULT_UPDATE_COMP_EmVaTcro), 258

(C++ enumerator), 259

esp_ble_mesh_init (C++ function), 210

esp_ble_mesh_health_srv_cb_t (C++ class), esp_ble_mesh_input_action_t (C++ enum),

253

204

esp_ble_mesh_health_srv_cb_t::attentionE_SoPf_fBLE_MESH_INPUT_NO_CHANGE_ERROR (C

(C++ member), 253

macro), 258

esp_ble_mesh_health_srv_cb_t::attentionE_SoPn_BLE_MESH_INPUT_NO_CHANGE_WARNING

(C++ member), 253

(C macro), 258

esp_ble_mesh_health_srv_cb_t::fault_cleEaSrP_BLE_MESH_INPUT_OOB (C++ enumerator),

(C++ member), 253

204

esp_ble_mesh_health_srv_cb_t::fault_tesEtSP_BLE_MESH_INPUT_TOO_HIGH_ERROR (C

(C++ member), 253

macro), 258

esp_ble_mesh_health_srv_t (C++ class), 253 ESP_BLE_MESH_INPUT_TOO_HIGH_WARNING (C

esp_ble_mesh_health_srv_t::attention_timer macro), 258

(C++ member), 254

ESP_BLE_MESH_INPUT_TOO_LOW_ERROR (C

esp_ble_mesh_health_srv_t::attention_timer_stamratcro), 258

(C++ member), 254

ESP_BLE_MESH_INPUT_TOO_LOW_WARNING (C

esp_ble_mesh_health_srv_t::health_cb

macro), 258

(C++ member), 254

ESP_BLE_MESH_INTERNAL_BUS_ERROR

(C

esp_ble_mesh_health_srv_t::health_test

macro), 258

(C++ member), 254

ESP_BLE_MESH_INTERNAL_BUS_WARNING (C

esp_ble_mesh_health_srv_t::model (C++

macro), 258

member), 254

ESP_BLE_MESH_INVALID_NODE_INDEX

(C

ESP_BLE_MESH_HEALTH_STANDARD_TEST (C

macro), 189

macro), 257

ESP_BLE_MESH_INVALID_SCENE_NUMBER (C

esp_ble_mesh_health_test_t (C++ class),

macro), 324

253

ESP_BLE_MESH_INVALID_SENSOR_PROPERTY_ID

esp_ble_mesh_health_test_t::company_id

(C macro), 302

(C++ member), 253

ESP_BLE_MESH_INVALID_SENSOR_SETTING_PROPERTY_ID

esp_ble_mesh_health_test_t::current_faults (C macro), 302

(C++ member), 253

ESP_BLE_MESH_INVALID_SETTINGS_IDX (C

esp_ble_mesh_health_test_t::id_count

macro), 188

(C++ member), 253

esp_ble_mesh_is_model_subscribed_to_group

esp_ble_mesh_health_test_t::prev_test_id

(C++ function), 211

(C++ member), 253

ESP_BLE_MESH_KEY_ANY (C macro), 188

esp_ble_mesh_health_test_t::registered_EfSaPu_lBtLsE_MESH_KEY_DEV (C macro), 188

(C++ member), 253

ESP_BLE_MESH_KEY_PRIMARY (C macro), 188

esp_ble_mesh_health_test_t::test_ids ESP_BLE_MESH_KEY_UNUSED (C macro), 188

(C++ member), 253

esp_ble_mesh_last_msg_info_t (C++ class),

ESP_BLE_MESH_HEARTBEAT_FILTER_ACCEPTLIST

187

(C macro), 191

esp_ble_mesh_last_msg_info_t::dst

ESP_BLE_MESH_HEARTBEAT_FILTER_ADD (C

(C++ member), 187

macro), 191

esp_ble_mesh_last_msg_info_t::src

esp_ble_mesh_heartbeat_filter_info_t

(C++ member), 187

(C++ class), 185

esp_ble_mesh_last_msg_info_t::tid

esp_ble_mesh_heartbeat_filter_info_t::hb_dst (C++ member), 187

(C++ member), 185

esp_ble_mesh_last_msg_info_t::timestamp

esp_ble_mesh_heartbeat_filter_info_t::hb_src (C++ member), 187

(C++ member), 185

ESP_BLE_MESH_LC_FADE (C++ enumerator), 368

ESP_BLE_MESH_HEARTBEAT_FILTER_REJECTLISETSP_BLE_MESH_LC_FADE_ON (C++ enumerator),

(C macro), 191

368

ESP_BLE_MESH_HEARTBEAT_FILTER_REMOVE ESP_BLE_MESH_LC_FADE_STANDBY_AUTO

(C macro), 191

(C++ enumerator), 368

ESP_BLE_MESH_HEARTBEAT_MESSAGE_RECV_EVTESP_BLE_MESH_LC_FADE_STANDBY_MANUAL

(C++ enumerator), 208

(C++ enumerator), 368

ESP_BLE_MESH_HOUSING_OPENED_ERROR (C ESP_BLE_MESH_LC_OFF (C++ enumerator), 368

macro), 258

ESP_BLE_MESH_LC_PROLONG (C++ enumerator),

Espressif Systems

2047

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

368

(C++ member), 329

ESP_BLE_MESH_LC_RUN (C++ enumerator), 368 esp_ble_mesh_light_client_set_state_t::lc_propert

ESP_BLE_MESH_LC_STANDBY (C++ enumerator),

(C++ member), 329

368

esp_ble_mesh_light_client_set_state_t::lightness_

esp_ble_mesh_lc_state_t (C++ enum), 368

(C++ member), 328

esp_ble_mesh_light_client_cb_event_t esp_ble_mesh_light_client_set_state_t::lightness_

(C++ enum), 367

(C++ member), 328

esp_ble_mesh_light_client_cb_param_t esp_ble_mesh_light_client_set_state_t::lightness_

(C++ class), 344

(C++ member), 328

esp_ble_mesh_light_client_cb_param_t::eersrpo_rb_lceo_dmeesh_light_client_set_state_t::lightness_

(C++ member), 344

(C++ member), 328

esp_ble_mesh_light_client_cb_param_t::peasrpa_mbsle_mesh_light_client_set_state_t::xyl_defaul

(C++ member), 344

(C++ member), 328

esp_ble_mesh_light_client_cb_param_t::setsapt_ubsl_ec_bmesh_light_client_set_state_t::xyl_range_

(C++ member), 344

(C++ member), 328

esp_ble_mesh_light_client_cb_t (C++ esp_ble_mesh_light_client_set_state_t::xyl_set

type), 367

(C++ member), 328

ESP_BLE_MESH_LIGHT_CLIENT_EVT_MAX

esp_ble_mesh_light_client_status_cb_t

(C++ enumerator), 368

(C++ union), 329

esp_ble_mesh_light_client_get_state esp_ble_mesh_light_client_status_cb_t::ctl_defaul

(C++ function), 327

(C++ member), 329

ESP_BLE_MESH_LIGHT_CLIENT_GET_STATE_EVTesp_ble_mesh_light_client_status_cb_t::ctl_status

(C++ enumerator), 367

(C++ member), 329

esp_ble_mesh_light_client_get_state_t esp_ble_mesh_light_client_status_cb_t::ctl_temper

(C++ union), 327

(C++ member), 329

esp_ble_mesh_light_client_get_state_t::elscp__pbrloep_emretsyh__gleitght_client_status_cb_t::ctl_temper

(C++ member), 327

(C++ member), 329

ESP_BLE_MESH_LIGHT_CLIENT_PUBLISH_EVT esp_ble_mesh_light_client_status_cb_t::hsl_defaul

(C++ enumerator), 368

(C++ member), 329

esp_ble_mesh_light_client_set_state esp_ble_mesh_light_client_status_cb_t::hsl_hue_st

(C++ function), 327

(C++ member), 329

ESP_BLE_MESH_LIGHT_CLIENT_SET_STATE_EVTesp_ble_mesh_light_client_status_cb_t::hsl_range_

(C++ enumerator), 367

(C++ member), 329

esp_ble_mesh_light_client_set_state_t esp_ble_mesh_light_client_status_cb_t::hsl_satura

(C++ union), 327

(C++ member), 329

esp_ble_mesh_light_client_set_state_t::ecstpl__bdleef_amuelsth__sleitght_client_status_cb_t::hsl_status

(C++ member), 328

(C++ member), 329

esp_ble_mesh_light_client_set_state_t::ecstpl__bsleet_mesh_light_client_status_cb_t::hsl_target

(C++ member), 328

(C++ member), 329

esp_ble_mesh_light_client_set_state_t::ecstpl__btleem_pmeersaht_ulrieg_hrta_ncglei_esnett_status_cb_t::lc_light_o

(C++ member), 328

(C++ member), 330

esp_ble_mesh_light_client_set_state_t::ecstpl__btleem_pmeersaht_ulrieg_hste_tclient_status_cb_t::lc_mode_st

(C++ member), 328

(C++ member), 330

esp_ble_mesh_light_client_set_state_t::ehsspl__bdleef_amuelsth__sleitght_client_status_cb_t::lc_om_stat

(C++ member), 328

(C++ member), 330

esp_ble_mesh_light_client_set_state_t::ehsspl__bhluee__mseesth_light_client_status_cb_t::lc_propert

(C++ member), 328

(C++ member), 330

esp_ble_mesh_light_client_set_state_t::ehsspl__brlaen_gmee_sshe_tlight_client_status_cb_t::lightness_

(C++ member), 328

(C++ member), 329

esp_ble_mesh_light_client_set_state_t::ehsspl__bslaet_umreasthi_olni_gshett_client_status_cb_t::lightness_

(C++ member), 328

(C++ member), 329

esp_ble_mesh_light_client_set_state_t::ehsspl__bsleet_mesh_light_client_status_cb_t::lightness_

(C++ member), 328

(C++ member), 329

esp_ble_mesh_light_client_set_state_t::elscp__lbilgeh_tm_eosnho_flfi_gshett_client_status_cb_t::lightness_

(C++ member), 329

(C++ member), 329

esp_ble_mesh_light_client_set_state_t::elscp__mboldee__mseesth_light_client_status_cb_t::lightness_

(C++ member), 328

(C++ member), 329

esp_ble_mesh_light_client_set_state_t::elscp__obml_es_emtesh_light_client_status_cb_t::xyl_defaul

Espressif Systems

2048

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 330

(C++ member), 346

esp_ble_mesh_light_client_status_cb_t::exsypl__brlaen_gmee_ssht_altiugsht_ctl_srv_t (C++ class),

(C++ member), 330

346

esp_ble_mesh_light_client_status_cb_t::exsypl__bsltea_tmuessh_light_ctl_srv_t::last

(C++ member), 329

(C++ member), 346

esp_ble_mesh_light_client_status_cb_t::exsypl__btlaer_gmeets_hs_tlaitguhst_ctl_srv_t::model

(C++ member), 329

(C++ member), 346

ESP_BLE_MESH_LIGHT_CLIENT_TIMEOUT_EVT esp_ble_mesh_light_ctl_srv_t::rsp_ctrl

(C++ enumerator), 368

(C++ member), 346

esp_ble_mesh_light_control_t (C++ class), esp_ble_mesh_light_ctl_srv_t::state

353

(C++ member), 346

esp_ble_mesh_light_control_t::prop_stateesp_ble_mesh_light_ctl_srv_t::transition

(C++ member), 353

(C++ member), 346

esp_ble_mesh_light_control_t::state esp_ble_mesh_light_ctl_srv_t::tt_delta_delta_uv

(C++ member), 353

(C++ member), 346

esp_ble_mesh_light_control_t::state_macehsipn_eble_mesh_light_ctl_srv_t::tt_delta_lightness

(C++ member), 353

(C++ member), 346

esp_ble_mesh_light_ctl_default_set_t esp_ble_mesh_light_ctl_srv_t::tt_delta_temperatur

(C++ class), 334

(C++ member), 346

esp_ble_mesh_light_ctl_default_set_t::deeslpt_ab_luev_mesh_light_ctl_state_t (C++

(C++ member), 334

class), 345

esp_ble_mesh_light_ctl_default_set_t::leisgph_tbnlees_smesh_light_ctl_state_t::delta_uv

(C++ member), 334

(C++ member), 345

esp_ble_mesh_light_ctl_default_set_t::teesmpp_ebrlaet_umreesh_light_ctl_state_t::delta_uv_default

(C++ member), 334

(C++ member), 346

esp_ble_mesh_light_ctl_default_status_cebs_pt_ble_mesh_light_ctl_state_t::lightness

(C++ class), 340

(C++ member), 345

esp_ble_mesh_light_ctl_default_status_cebs_pt_:b:ldee_lmteas_hu_vlight_ctl_state_t::lightness_default

(C++ member), 340

(C++ member), 346

esp_ble_mesh_light_ctl_default_status_cebs_pt_:b:llei_gmhetsnhe_slsight_ctl_state_t::status_code

(C++ member), 340

(C++ member), 346

esp_ble_mesh_light_ctl_default_status_cebs_pt_:b:ltee_mmpeesrha_tluirgeht_ctl_state_t::target_delta_uv

(C++ member), 340

(C++ member), 345

ESP_BLE_MESH_LIGHT_CTL_LIGHTNESS_STATE esp_ble_mesh_light_ctl_state_t::target_lightness

(C++ enumerator), 209

(C++ member), 345

esp_ble_mesh_light_ctl_set_t (C++ class), esp_ble_mesh_light_ctl_state_t::target_temperatur

333

(C++ member), 345

esp_ble_mesh_light_ctl_set_t::ctl_deltae_supv_ble_mesh_light_ctl_state_t::temperature

(C++ member), 334

(C++ member), 345

esp_ble_mesh_light_ctl_set_t::ctl_lightenseps_sble_mesh_light_ctl_state_t::temperature_defau

(C++ member), 333

(C++ member), 346

esp_ble_mesh_light_ctl_set_t::ctl_tempeersapt_rbulee_mesh_light_ctl_state_t::temperature_range

(C++ member), 333

(C++ member), 346

esp_ble_mesh_light_ctl_set_t::delay esp_ble_mesh_light_ctl_state_t::temperature_range

(C++ member), 334

(C++ member), 346

esp_ble_mesh_light_ctl_set_t::op_en esp_ble_mesh_light_ctl_status_cb_t

(C++ member), 333

(C++ class), 339

esp_ble_mesh_light_ctl_set_t::tid

esp_ble_mesh_light_ctl_status_cb_t::op_en

(C++ member), 334

(C++ member), 339

esp_ble_mesh_light_ctl_set_t::trans_timeesp_ble_mesh_light_ctl_status_cb_t::present_ctl_l

(C++ member), 334

(C++ member), 339

esp_ble_mesh_light_ctl_setup_srv_t

esp_ble_mesh_light_ctl_status_cb_t::present_ctl_t

(C++ class), 346

(C++ member), 339

esp_ble_mesh_light_ctl_setup_srv_t::modeeslp_ble_mesh_light_ctl_status_cb_t::remain_time

(C++ member), 346

(C++ member), 339

esp_ble_mesh_light_ctl_setup_srv_t::rspe_scpt_rblle_mesh_light_ctl_status_cb_t::target_ctl_li

(C++ member), 346

(C++ member), 339

esp_ble_mesh_light_ctl_setup_srv_t::staetsep_ble_mesh_light_ctl_status_cb_t::target_ctl_te

Espressif Systems

2049

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 339

(C++ member), 340

ESP_BLE_MESH_LIGHT_CTL_TEMP_DELTA_UV_STeAsTpE_ble_mesh_light_ctl_temperature_status_cb_t::t

(C++ enumerator), 209

(C++ member), 340

esp_ble_mesh_light_ctl_temp_srv_t

esp_ble_mesh_light_hsl_default_set_t

(C++ class), 346

(C++ class), 336

esp_ble_mesh_light_ctl_temp_srv_t::lastesp_ble_mesh_light_hsl_default_set_t::hue

(C++ member), 347

(C++ member), 336

esp_ble_mesh_light_ctl_temp_srv_t::modeelsp_ble_mesh_light_hsl_default_set_t::lightness

(C++ member), 347

(C++ member), 336

esp_ble_mesh_light_ctl_temp_srv_t::rsp_ecstpr_lble_mesh_light_hsl_default_set_t::saturation

(C++ member), 347

(C++ member), 336

esp_ble_mesh_light_ctl_temp_srv_t::stateesp_ble_mesh_light_hsl_default_status_cb_t

(C++ member), 347

(C++ class), 341

esp_ble_mesh_light_ctl_temp_srv_t::tranessipt_ibolne_mesh_light_hsl_default_status_cb_t::hue

(C++ member), 347

(C++ member), 341

esp_ble_mesh_light_ctl_temp_srv_t::tt_deeslpt_ab_ldee_lmteas_hu_vlight_hsl_default_status_cb_t::light

(C++ member), 347

(C++ member), 341

esp_ble_mesh_light_ctl_temp_srv_t::tt_deeslpt_ab_ltee_mmpeesrha_tluirgeht_hsl_default_status_cb_t::satur

(C++ member), 347

(C++ member), 341

esp_ble_mesh_light_ctl_temperature_rangees_ps_ebtl_et_mesh_light_hsl_hue_set_t (C++

(C++ class), 334

class), 335

esp_ble_mesh_light_ctl_temperature_rangees_ps_ebtl_et_:m:ersahn_glei_gmhatx_hsl_hue_set_t::delay

(C++ member), 334

(C++ member), 335

esp_ble_mesh_light_ctl_temperature_rangees_ps_ebtl_et_:m:ersahn_glei_gmhitn_hsl_hue_set_t::hue

(C++ member), 334

(C++ member), 335

esp_ble_mesh_light_ctl_temperature_rangees_ps_tbalteu_sm_ecsbh__tlight_hsl_hue_set_t::op_en

(C++ class), 340

(C++ member), 335

esp_ble_mesh_light_ctl_temperature_rangees_ps_tbalteu_sm_ecsbh__tl:i:grhatn_ghes_lm_ahxue_set_t::tid

(C++ member), 340

(C++ member), 335

esp_ble_mesh_light_ctl_temperature_rangees_ps_tbalteu_sm_ecsbh__tl:i:grhatn_ghes_lm_ihnue_set_t::trans_time

(C++ member), 340

(C++ member), 335

esp_ble_mesh_light_ctl_temperature_rangees_ps_tbalteu_sm_ecsbh__tl:i:gshtta_thussl__choudee_srv_t (C++

(C++ member), 340

class), 348

esp_ble_mesh_light_ctl_temperature_set_etsp_ble_mesh_light_hsl_hue_srv_t::last

(C++ class), 334

(C++ member), 348

esp_ble_mesh_light_ctl_temperature_set_ets:p:_cbtlle__dmeelstha__luivght_hsl_hue_srv_t::model

(C++ member), 334

(C++ member), 348

esp_ble_mesh_light_ctl_temperature_set_ets:p:_cbtlle__tmeemsphe_rlaitgrhute_hsl_hue_srv_t::rsp_ctrl

(C++ member), 334

(C++ member), 348

esp_ble_mesh_light_ctl_temperature_set_ets:p:_dbellea_ymesh_light_hsl_hue_srv_t::state

(C++ member), 334

(C++ member), 348

esp_ble_mesh_light_ctl_temperature_set_ets:p:_obpl_ee_nmesh_light_hsl_hue_srv_t::transition

(C++ member), 334

(C++ member), 348

esp_ble_mesh_light_ctl_temperature_set_ets:p:_tbilde_mesh_light_hsl_hue_srv_t::tt_delta_hue

(C++ member), 334

(C++ member), 349

esp_ble_mesh_light_ctl_temperature_set_EtS:P:_tBrLaEn_sM_EtSiHm_eLIGHT_HSL_HUE_STATE (C++

(C++ member), 334

enumerator), 209

esp_ble_mesh_light_ctl_temperature_stateussp__cbbl_et_mesh_light_hsl_hue_status_cb_t

(C++ class), 339

(C++ class), 341

esp_ble_mesh_light_ctl_temperature_stateussp__cbbl_et_:m:eosph__elnight_hsl_hue_status_cb_t::op_en

(C++ member), 339

(C++ member), 341

esp_ble_mesh_light_ctl_temperature_stateussp__cbbl_et_:m:epsrhe_sleingth_tc_thls_ld_ehlutea__sutvatus_cb_t::present_h

(C++ member), 339

(C++ member), 341

esp_ble_mesh_light_ctl_temperature_stateussp__cbbl_et_:m:epsrhe_sleingth_tc_thls_lt_ehmupee_rsattautrues_cb_t::remain_ti

(C++ member), 339

(C++ member), 341

esp_ble_mesh_light_ctl_temperature_stateussp__cbbl_et_:m:ersehm_aliing_htti_mhesl_hue_status_cb_t::target_hu

(C++ member), 340

(C++ member), 341

esp_ble_mesh_light_ctl_temperature_statEuSsP__cBbL_Et_:M:EtSaHr_gLeItG_HcTt_lH_SdLe_lLtIaG_HuTvNESS_STATE

Espressif Systems

2050

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ enumerator), 209

(C++ member), 341

esp_ble_mesh_light_hsl_range_set_t

esp_ble_mesh_light_hsl_saturation_status_cb_t::ta

(C++ class), 336

(C++ member), 341

esp_ble_mesh_light_hsl_range_set_t::huee_srpa_nbglee__mmaexsh_light_hsl_set_t (C++ class),

(C++ member), 336

334

esp_ble_mesh_light_hsl_range_set_t::huee_srpa_nbglee__mmiensh_light_hsl_set_t::delay

(C++ member), 336

(C++ member), 335

esp_ble_mesh_light_hsl_range_set_t::sateusrpa_tbiloen__mreasnhg_el_imgahxt_hsl_set_t::hsl_hue

(C++ member), 336

(C++ member), 335

esp_ble_mesh_light_hsl_range_set_t::sateusrpa_tbiloen__mreasnhg_el_imgihnt_hsl_set_t::hsl_lightness

(C++ member), 336

(C++ member), 335

esp_ble_mesh_light_hsl_range_status_cb_etsp_ble_mesh_light_hsl_set_t::hsl_saturation

(C++ class), 342

(C++ member), 335

esp_ble_mesh_light_hsl_range_status_cb_ets:p:_hbulee__rmaensghe__lmiagxht_hsl_set_t::op_en

(C++ member), 342

(C++ member), 335

esp_ble_mesh_light_hsl_range_status_cb_ets:p:_hbulee__rmaensghe__lmiignht_hsl_set_t::tid

(C++ member), 342

(C++ member), 335

esp_ble_mesh_light_hsl_range_status_cb_ets:p:_sbalteu_rmaetsiho_nl_irgahntg_eh_smla_xset_t::trans_time

(C++ member), 342

(C++ member), 335

esp_ble_mesh_light_hsl_range_status_cb_ets:p:_sbalteu_rmaetsiho_nl_irgahntg_eh_smli_nsetup_srv_t

(C++ member), 342

(C++ class), 348

esp_ble_mesh_light_hsl_range_status_cb_ets:p:_sbtlaet_umse_scho_dleight_hsl_setup_srv_t::model

(C++ member), 342

(C++ member), 348

esp_ble_mesh_light_hsl_sat_srv_t (C++ esp_ble_mesh_light_hsl_setup_srv_t::rsp_ctrl

class), 349

(C++ member), 348

esp_ble_mesh_light_hsl_sat_srv_t::last esp_ble_mesh_light_hsl_setup_srv_t::state

(C++ member), 349

(C++ member), 348

esp_ble_mesh_light_hsl_sat_srv_t::modelesp_ble_mesh_light_hsl_srv_t (C++ class),

(C++ member), 349

348

esp_ble_mesh_light_hsl_sat_srv_t::rsp_cetsrpl_ble_mesh_light_hsl_srv_t::last

(C++ member), 349

(C++ member), 348

esp_ble_mesh_light_hsl_sat_srv_t::stateesp_ble_mesh_light_hsl_srv_t::model

(C++ member), 349

(C++ member), 348

esp_ble_mesh_light_hsl_sat_srv_t::transeistpi_obnle_mesh_light_hsl_srv_t::rsp_ctrl

(C++ member), 349

(C++ member), 348

esp_ble_mesh_light_hsl_sat_srv_t::tt_deelstpa__bslaet_umreasthi_olnight_hsl_srv_t::state

(C++ member), 349

(C++ member), 348

esp_ble_mesh_light_hsl_saturation_set_tesp_ble_mesh_light_hsl_srv_t::transition

(C++ class), 335

(C++ member), 348

esp_ble_mesh_light_hsl_saturation_set_te:s:pd_ebllaey_mesh_light_hsl_srv_t::tt_delta_hue

(C++ member), 335

(C++ member), 348

esp_ble_mesh_light_hsl_saturation_set_te:s:po_pb_leen_mesh_light_hsl_srv_t::tt_delta_lightness

(C++ member), 335

(C++ member), 348

esp_ble_mesh_light_hsl_saturation_set_te:s:ps_abtluer_amteisohn_light_hsl_srv_t::tt_delta_saturation

(C++ member), 335

(C++ member), 348

esp_ble_mesh_light_hsl_saturation_set_tE:S:Pt_iBdLE_MESH_LIGHT_HSL_STATE (C++ enu-

(C++ member), 335

merator), 209

esp_ble_mesh_light_hsl_saturation_set_te:s:pt_rbalnes__mteismhe_light_hsl_state_t (C++

(C++ member), 335

class), 347

ESP_BLE_MESH_LIGHT_HSL_SATURATION_STATEesp_ble_mesh_light_hsl_state_t::hue

(C++ enumerator), 209

(C++ member), 347

esp_ble_mesh_light_hsl_saturation_statuess_pc_bb_lte_mesh_light_hsl_state_t::hue_default

(C++ class), 341

(C++ member), 347

esp_ble_mesh_light_hsl_saturation_statuess_pc_bb_lte:_:moeps_he_nlight_hsl_state_t::hue_range_max

(C++ member), 341

(C++ member), 347

esp_ble_mesh_light_hsl_saturation_statuess_pc_bb_lte:_:mpersehs_elnitg_hsta_thusrla_tsitoante_t::hue_range_min

(C++ member), 341

(C++ member), 347

esp_ble_mesh_light_hsl_saturation_statuess_pc_bb_lte:_:mreesmha_ilni_gthitm_ehsl_state_t::lightness

Espressif Systems

2051

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 347

(C++ class), 343

esp_ble_mesh_light_hsl_state_t::lightneesssp__dbelfea_umletsh_light_lc_light_onoff_status_cb_t::op

(C++ member), 347

(C++ member), 343

esp_ble_mesh_light_hsl_state_t::saturateisopn_ble_mesh_light_lc_light_onoff_status_cb_t::pr

(C++ member), 347

(C++ member), 343

esp_ble_mesh_light_hsl_state_t::saturateisopn__bdleef_amuelsth_light_lc_light_onoff_status_cb_t::re

(C++ member), 347

(C++ member), 344

esp_ble_mesh_light_hsl_state_t::saturateisopn__brlaen_gmee_smha_xlight_lc_light_onoff_status_cb_t::ta

(C++ member), 347

(C++ member), 343

esp_ble_mesh_light_hsl_state_t::saturateisopn__brlaen_gmee_smhi_nlight_lc_mode_set_t (C++

(C++ member), 347

class), 337

esp_ble_mesh_light_hsl_state_t::status_ecsopd_eble_mesh_light_lc_mode_set_t::mode

(C++ member), 347

(C++ member), 337

esp_ble_mesh_light_hsl_state_t::target_ehsupe_ble_mesh_light_lc_mode_status_cb_t

(C++ member), 347

(C++ class), 343

esp_ble_mesh_light_hsl_state_t::target_elsipg_hbtlnee_smsesh_light_lc_mode_status_cb_t::mode

(C++ member), 347

(C++ member), 343

esp_ble_mesh_light_hsl_state_t::target_essapt_ubrlaet_imoensh_light_lc_om_set_t (C++

(C++ member), 347

class), 337

esp_ble_mesh_light_hsl_status_cb_t

esp_ble_mesh_light_lc_om_set_t::mode

(C++ class), 340

(C++ member), 337

esp_ble_mesh_light_hsl_status_cb_t::hsle_shpu_eble_mesh_light_lc_om_status_cb_t

(C++ member), 340

(C++ class), 343

esp_ble_mesh_light_hsl_status_cb_t::hsle_slpi_gbhlten_emsessh_light_lc_om_status_cb_t::mode

(C++ member), 340

(C++ member), 343

esp_ble_mesh_light_hsl_status_cb_t::hsle_sspa_tbulrea_tmieosnh_light_lc_property_get_t

(C++ member), 340

(C++ class), 338

esp_ble_mesh_light_hsl_status_cb_t::op_eesnp_ble_mesh_light_lc_property_get_t::property_id

(C++ member), 340

(C++ member), 338

esp_ble_mesh_light_hsl_status_cb_t::remeasipn__btliem_emesh_light_lc_property_set_t

(C++ member), 340

(C++ class), 338

esp_ble_mesh_light_hsl_target_status_cbe_stp_ble_mesh_light_lc_property_set_t::property_id

(C++ class), 340

(C++ member), 338

esp_ble_mesh_light_hsl_target_status_cbe_stp:_:bhlsel__mheuseh__tlairgghett_lc_property_set_t::property_va

(C++ member), 341

(C++ member), 338

esp_ble_mesh_light_hsl_target_status_cbe_stp:_:bhlsel__mleisghh_tlniegshst__tlacr_gpertoperty_state_t

(C++ member), 341

(C++ class), 351

esp_ble_mesh_light_hsl_target_status_cbe_stp:_:bhlsel__mseasthu_rlaitgihotn__ltca_rpgreotperty_state_t::ambient_l

(C++ member), 341

(C++ member), 352

esp_ble_mesh_light_hsl_target_status_cbe_stp:_:bolpe__emnesh_light_lc_property_state_t::ambient_l

(C++ member), 341

(C++ member), 352

esp_ble_mesh_light_hsl_target_status_cbe_stp:_:brleem_amiens_ht_ilmieght_lc_property_state_t::ambient_l

(C++ member), 341

(C++ member), 352

esp_ble_mesh_light_lc_light_onoff_set_tesp_ble_mesh_light_lc_property_state_t::lightness

(C++ class), 337

(C++ member), 351

esp_ble_mesh_light_lc_light_onoff_set_te:s:pd_ebllaey_mesh_light_lc_property_state_t::lightness

(C++ member), 337

(C++ member), 352

esp_ble_mesh_light_lc_light_onoff_set_te:s:pl_ibglhet__moensohf_flight_lc_property_state_t::lightness

(C++ member), 337

(C++ member), 352

esp_ble_mesh_light_lc_light_onoff_set_te:s:po_pb_leen_mesh_light_lc_property_state_t::regulator

(C++ member), 337

(C++ member), 352

esp_ble_mesh_light_lc_light_onoff_set_te:s:pt_ibdle_mesh_light_lc_property_state_t::regulator

(C++ member), 337

(C++ member), 352

esp_ble_mesh_light_lc_light_onoff_set_te:s:pt_rbalnes__mteismhe_light_lc_property_state_t::regulator

(C++ member), 337

(C++ member), 352

ESP_BLE_MESH_LIGHT_LC_LIGHT_ONOFF_STATEesp_ble_mesh_light_lc_property_state_t::regulator

(C++ enumerator), 209

(C++ member), 352

esp_ble_mesh_light_lc_light_onoff_statuess_pc_bb_lte_mesh_light_lc_property_state_t::regulator

Espressif Systems

2052

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 352

(C++ member), 353

esp_ble_mesh_light_lc_property_state_t:e:sspe_tb_loec_cmuepsahn_clyi_gthot__1l_cd_esltaayte_t (C++

(C++ member), 352

class), 350

esp_ble_mesh_light_lc_property_state_t:e:stpi_mbel_ef_amdeesh_light_lc_state_t::ambient_luxlevel

(C++ member), 351

(C++ member), 351

esp_ble_mesh_light_lc_property_state_t:e:stpi_mbel_ef_amdees_ho_nlight_lc_state_t::light_onoff

(C++ member), 351

(C++ member), 351

esp_ble_mesh_light_lc_property_state_t:e:stpi_mbel_ef_amdees_hs_tlaingdhbty__lacu_tsotate_t::linear_output

(C++ member), 351

(C++ member), 351

esp_ble_mesh_light_lc_property_state_t:e:stpi_mbel_ef_amdees_hs_tlaingdhbty__lmca_nsutaalte_t::mode

(C++ member), 351

(C++ member), 350

esp_ble_mesh_light_lc_property_state_t:e:stpi_mbel_eo_cmceuspha_nlciyg_hdte_llacy_state_t::occupancy

(C++ member), 351

(C++ member), 351

esp_ble_mesh_light_lc_property_state_t:e:stpi_mbel_ep_rmoelsohn_glight_lc_state_t::occupancy_mode

(C++ member), 351

(C++ member), 351

esp_ble_mesh_light_lc_property_state_t:e:stpi_mbel_er_umne_sohn_light_lc_state_t::target_light_onoff

(C++ member), 351

(C++ member), 351

esp_ble_mesh_light_lc_property_status_cEbS_Pt_BLE_MESH_LIGHT_LIGHTNESS_ACTUAL_STATE

(C++ class), 344

(C++ enumerator), 209

esp_ble_mesh_light_lc_property_status_cebs_pt_:b:lper_ompeesrht_yl_iigdht_lightness_default_set_t

(C++ member), 344

(C++ class), 333

esp_ble_mesh_light_lc_property_status_cebs_pt_:b:lper_ompeesrht_yl_ivgahltu_elightness_default_set_t::light

(C++ member), 344

(C++ member), 333

esp_ble_mesh_light_lc_setup_srv_t

esp_ble_mesh_light_lightness_default_status_cb_t

(C++ class), 353

(C++ class), 339

esp_ble_mesh_light_lc_setup_srv_t::lc esp_ble_mesh_light_lightness_default_status_cb_t:

(C++ member), 354

(C++ member), 339

esp_ble_mesh_light_lc_setup_srv_t::modeelsp_ble_mesh_light_lightness_last_status_cb_t

(C++ member), 354

(C++ class), 338

esp_ble_mesh_light_lc_setup_srv_t::rsp_ecstpr_lble_mesh_light_lightness_last_status_cb_t::li

(C++ member), 354

(C++ member), 339

esp_ble_mesh_light_lc_srv_t (C++ class), esp_ble_mesh_light_lightness_linear_set_t

353

(C++ class), 333

esp_ble_mesh_light_lc_srv_t::last

esp_ble_mesh_light_lightness_linear_set_t::delay

(C++ member), 353

(C++ member), 333

esp_ble_mesh_light_lc_srv_t::lc (C++ esp_ble_mesh_light_lightness_linear_set_t::lightn

member), 353

(C++ member), 333

esp_ble_mesh_light_lc_srv_t::model

esp_ble_mesh_light_lightness_linear_set_t::op_en

(C++ member), 353

(C++ member), 333

esp_ble_mesh_light_lc_srv_t::rsp_ctrl esp_ble_mesh_light_lightness_linear_set_t::tid

(C++ member), 353

(C++ member), 333

esp_ble_mesh_light_lc_srv_t::transitionesp_ble_mesh_light_lightness_linear_set_t::trans_

(C++ member), 353

(C++ member), 333

esp_ble_mesh_light_lc_state_machine_t ESP_BLE_MESH_LIGHT_LIGHTNESS_LINEAR_STATE

(C++ class), 352

(C++ enumerator), 209

esp_ble_mesh_light_lc_state_machine_t::efsapd_eble_mesh_light_lightness_linear_status_cb_t

(C++ member), 353

(C++ class), 338

esp_ble_mesh_light_lc_state_machine_t::efsapd_eb_loen_mesh_light_lightness_linear_status_cb_t::

(C++ member), 353

(C++ member), 338

esp_ble_mesh_light_lc_state_machine_t::efsapd_eb_lset_amnedsbhy__laiugthot_lightness_linear_status_cb_t::

(C++ member), 353

(C++ member), 338

esp_ble_mesh_light_lc_state_machine_t::efsapd_eb_lset_amnedsbhy__lmiagnhuta_llightness_linear_status_cb_t::

(C++ member), 353

(C++ member), 338

esp_ble_mesh_light_lc_state_machine_t::esstpa_tbele_mesh_light_lightness_linear_status_cb_t::

(C++ member), 353

(C++ member), 338

esp_ble_mesh_light_lc_state_machine_t::etsipm_ebrle_mesh_light_lightness_range_set_t

(C++ member), 353

(C++ class), 333

esp_ble_mesh_light_lc_state_machine_t::etsrpa_nbsl_et_immeesh_light_lightness_range_set_t::range_m

Espressif Systems

2053

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 333

(C++ member), 344

esp_ble_mesh_light_lightness_range_set_ets:p:_rbalneg_em_emsihn_light_lightness_state_t::lightness_r

(C++ member), 333

(C++ member), 344

esp_ble_mesh_light_lightness_range_stateussp__cbbl_et_mesh_light_lightness_state_t::lightness_r

(C++ class), 339

(C++ member), 344

esp_ble_mesh_light_lightness_range_stateussp__cbbl_et_:m:ersahn_glei_gmhatx_lightness_state_t::status_code

(C++ member), 339

(C++ member), 344

esp_ble_mesh_light_lightness_range_stateussp__cbbl_et_:m:ersahn_glei_gmhitn_lightness_state_t::target_ligh

(C++ member), 339

(C++ member), 344

esp_ble_mesh_light_lightness_range_stateussp__cbbl_et_:m:esstha_tluisg_hcto_dleightness_state_t::target_ligh

(C++ member), 339

(C++ member), 344

esp_ble_mesh_light_lightness_set_t

esp_ble_mesh_light_lightness_status_cb_t

(C++ class), 332

(C++ class), 338

esp_ble_mesh_light_lightness_set_t::deleasyp_ble_mesh_light_lightness_status_cb_t::op_en

(C++ member), 333

(C++ member), 338

esp_ble_mesh_light_lightness_set_t::ligehstpn_ebslse_mesh_light_lightness_status_cb_t::present

(C++ member), 332

(C++ member), 338

esp_ble_mesh_light_lightness_set_t::op_eesnp_ble_mesh_light_lightness_status_cb_t::remain_

(C++ member), 332

(C++ member), 338

esp_ble_mesh_light_lightness_set_t::tidesp_ble_mesh_light_lightness_status_cb_t::target_

(C++ member), 333

(C++ member), 338

esp_ble_mesh_light_lightness_set_t::traenssp__tbilmee_mesh_light_message_opcode_t

(C++ member), 333

(C++ type), 203

esp_ble_mesh_light_lightness_setup_srv_etsp_ble_mesh_light_xyl_default_set_t

(C++ class), 345

(C++ class), 336

esp_ble_mesh_light_lightness_setup_srv_ets:p:_mboldee_lmesh_light_xyl_default_set_t::lightness

(C++ member), 345

(C++ member), 337

esp_ble_mesh_light_lightness_setup_srv_ets:p:_rbslpe__cmterslh_light_xyl_default_set_t::xyl_x

(C++ member), 345

(C++ member), 337

esp_ble_mesh_light_lightness_setup_srv_ets:p:_sbtlaet_emesh_light_xyl_default_set_t::xyl_y

(C++ member), 345

(C++ member), 337

esp_ble_mesh_light_lightness_srv_t

esp_ble_mesh_light_xyl_default_status_cb_t

(C++ class), 344

(C++ class), 342

esp_ble_mesh_light_lightness_srv_t::acteusapl__btlrea_nmseisthi_olnight_xyl_default_status_cb_t::light

(C++ member), 345

(C++ member), 343

esp_ble_mesh_light_lightness_srv_t::lasetsp_ble_mesh_light_xyl_default_status_cb_t::xyl_x

(C++ member), 345

(C++ member), 343

esp_ble_mesh_light_lightness_srv_t::lineesapr__btlrea_nmseisthi_olnight_xyl_default_status_cb_t::xyl_y

(C++ member), 345

(C++ member), 343

esp_ble_mesh_light_lightness_srv_t::modEeSlP_BLE_MESH_LIGHT_XYL_LIGHTNESS_STATE

(C++ member), 345

(C++ enumerator), 209

esp_ble_mesh_light_lightness_srv_t::rspe_scpt_rblle_mesh_light_xyl_range_set_t

(C++ member), 345

(C++ class), 337

esp_ble_mesh_light_lightness_srv_t::staetsep_ble_mesh_light_xyl_range_set_t::xyl_x_range_m

(C++ member), 345

(C++ member), 337

esp_ble_mesh_light_lightness_srv_t::tt_edsepl_tbal_el_imgehsthn_elsisg_hatc_txuyall_range_set_t::xyl_x_range_m

(C++ member), 345

(C++ member), 337

esp_ble_mesh_light_lightness_srv_t::tt_edsepl_tbal_el_imgehsthn_elsisg_hlti_nxeyalr_range_set_t::xyl_y_range_m

(C++ member), 345

(C++ member), 337

esp_ble_mesh_light_lightness_state_t esp_ble_mesh_light_xyl_range_set_t::xyl_y_range_m

(C++ class), 344

(C++ member), 337

esp_ble_mesh_light_lightness_state_t::leisgph_tbnlees_sm_eascht_ulailght_xyl_range_status_cb_t

(C++ member), 344

(C++ class), 343

esp_ble_mesh_light_lightness_state_t::leisgph_tbnlees_sm_edsehf_aluilgtht_xyl_range_status_cb_t::status_

(C++ member), 344

(C++ member), 343

esp_ble_mesh_light_lightness_state_t::leisgph_tbnlees_sm_elsahs_tlight_xyl_range_status_cb_t::xyl_x_r

(C++ member), 344

(C++ member), 343

esp_ble_mesh_light_lightness_state_t::leisgph_tbnlees_sm_elsihn_elairght_xyl_range_status_cb_t::xyl_x_r

Espressif Systems

2054

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 343

(C++ member), 349

esp_ble_mesh_light_xyl_range_status_cb_ets:p:_xbylle__ym_ersahn_glei_gmhatx_xyl_state_t::target_y

(C++ member), 343

(C++ member), 349

esp_ble_mesh_light_xyl_range_status_cb_ets:p:_xbylle__ym_ersahn_glei_gmhitn_xyl_state_t::x

(C++ member), 343

(C++ member), 349

esp_ble_mesh_light_xyl_set_t (C++ class), esp_ble_mesh_light_xyl_state_t::x_default

336

(C++ member), 349

esp_ble_mesh_light_xyl_set_t::delay esp_ble_mesh_light_xyl_state_t::x_range_max

(C++ member), 336

(C++ member), 350

esp_ble_mesh_light_xyl_set_t::op_en esp_ble_mesh_light_xyl_state_t::x_range_min

(C++ member), 336

(C++ member), 349

esp_ble_mesh_light_xyl_set_t::tid

esp_ble_mesh_light_xyl_state_t::y

(C++ member), 336

(C++ member), 349

esp_ble_mesh_light_xyl_set_t::trans_timeesp_ble_mesh_light_xyl_state_t::y_default

(C++ member), 336

(C++ member), 349

esp_ble_mesh_light_xyl_set_t::xyl_lightenseps_sble_mesh_light_xyl_state_t::y_range_max

(C++ member), 336

(C++ member), 350

esp_ble_mesh_light_xyl_set_t::xyl_x esp_ble_mesh_light_xyl_state_t::y_range_min

(C++ member), 336

(C++ member), 350

esp_ble_mesh_light_xyl_set_t::xyl_y esp_ble_mesh_light_xyl_status_cb_t

(C++ member), 336

(C++ class), 342

esp_ble_mesh_light_xyl_setup_srv_t

esp_ble_mesh_light_xyl_status_cb_t::op_en

(C++ class), 350

(C++ member), 342

esp_ble_mesh_light_xyl_setup_srv_t::modeeslp_ble_mesh_light_xyl_status_cb_t::remain_time

(C++ member), 350

(C++ member), 342

esp_ble_mesh_light_xyl_setup_srv_t::rspe_scpt_rblle_mesh_light_xyl_status_cb_t::xyl_lightness

(C++ member), 350

(C++ member), 342

esp_ble_mesh_light_xyl_setup_srv_t::staetsep_ble_mesh_light_xyl_status_cb_t::xyl_x

(C++ member), 350

(C++ member), 342

esp_ble_mesh_light_xyl_srv_t (C++ class), esp_ble_mesh_light_xyl_status_cb_t::xyl_y

350

(C++ member), 342

esp_ble_mesh_light_xyl_srv_t::last

esp_ble_mesh_light_xyl_target_status_cb_t

(C++ member), 350

(C++ class), 342

esp_ble_mesh_light_xyl_srv_t::model esp_ble_mesh_light_xyl_target_status_cb_t::op_en

(C++ member), 350

(C++ member), 342

esp_ble_mesh_light_xyl_srv_t::rsp_ctrl esp_ble_mesh_light_xyl_target_status_cb_t::remain

(C++ member), 350

(C++ member), 342

esp_ble_mesh_light_xyl_srv_t::state esp_ble_mesh_light_xyl_target_status_cb_t::target

(C++ member), 350

(C++ member), 342

esp_ble_mesh_light_xyl_srv_t::transitioensp_ble_mesh_light_xyl_target_status_cb_t::target

(C++ member), 350

(C++ member), 342

esp_ble_mesh_light_xyl_srv_t::tt_delta_elsipg_hbtlnee_smsesh_light_xyl_target_status_cb_t::target

(C++ member), 350

(C++ member), 342

esp_ble_mesh_light_xyl_srv_t::tt_delta_exsp_ble_mesh_lighting_server_cb_event_t

(C++ member), 350

(C++ enum), 368

esp_ble_mesh_light_xyl_srv_t::tt_delta_eysp_ble_mesh_lighting_server_cb_param_t

(C++ member), 350

(C++ class), 363

esp_ble_mesh_light_xyl_state_t (C++ esp_ble_mesh_lighting_server_cb_param_t::ctx

class), 349

(C++ member), 364

esp_ble_mesh_light_xyl_state_t::lightneesssp_ble_mesh_lighting_server_cb_param_t::model

(C++ member), 349

(C++ member), 364

esp_ble_mesh_light_xyl_state_t::lightneesssp__dbelfea_umletsh_lighting_server_cb_param_t::value

(C++ member), 349

(C++ member), 364

esp_ble_mesh_light_xyl_state_t::status_ecsopd_eble_mesh_lighting_server_cb_t

(C++ member), 349

(C++ type), 367

esp_ble_mesh_light_xyl_state_t::target_elsipg_hbtlnee_smsesh_lighting_server_cb_value_t

(C++ member), 349

(C++ union), 332

esp_ble_mesh_light_xyl_state_t::target_exsp_ble_mesh_lighting_server_cb_value_t::get

Espressif Systems

2055

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 332

(C++ member), 332

esp_ble_mesh_lighting_server_cb_value_tE:S:Ps_eBtLE_MESH_LIGHTING_SERVER_RECV_STATUS_MSG_EVT

(C++ member), 332

(C++ enumerator), 368

esp_ble_mesh_lighting_server_cb_value_te:s:ps_tbaltee__mcehsahn_gleighting_server_recv_status_msg_t

(C++ member), 332

(C++ union), 332

esp_ble_mesh_lighting_server_cb_value_te:s:ps_tbalteu_smesh_lighting_server_recv_status_msg_t::s

(C++ member), 332

(C++ member), 332

ESP_BLE_MESH_LIGHTING_SERVER_EVT_MAX ESP_BLE_MESH_LIGHTING_SERVER_STATE_CHANGE_EVT

(C++ enumerator), 368

(C++ enumerator), 368

ESP_BLE_MESH_LIGHTING_SERVER_RECV_GET_MeSsGp__EbVlTe_mesh_lighting_server_state_change_t

(C++ enumerator), 368

(C++ union), 330

esp_ble_mesh_lighting_server_recv_get_messgp__tble_mesh_lighting_server_state_change_t::ctl_

(C++ union), 331

(C++ member), 330

esp_ble_mesh_lighting_server_recv_get_messgp__tb:l:el_cm_epsrho_pleirgthyting_server_state_change_t::ctl_

(C++ member), 331

(C++ member), 330

ESP_BLE_MESH_LIGHTING_SERVER_RECV_SET_MeSsGp__EbVlTe_mesh_lighting_server_state_change_t::ctl_

(C++ enumerator), 368

(C++ member), 330

esp_ble_mesh_lighting_server_recv_set_messgp__tble_mesh_lighting_server_state_change_t::ctl_

(C++ union), 331

(C++ member), 330

esp_ble_mesh_lighting_server_recv_set_messgp__tb:l:ec_tmlesh_lighting_server_state_change_t::hsl_

(C++ member), 331

(C++ member), 330

esp_ble_mesh_lighting_server_recv_set_messgp__tb:l:ec_tmle_sdhe_flaiuglhtting_server_state_change_t::hsl_

(C++ member), 331

(C++ member), 330

esp_ble_mesh_lighting_server_recv_set_messgp__tb:l:ec_tmle_sthe_mlpighting_server_state_change_t::hsl_

(C++ member), 331

(C++ member), 330

esp_ble_mesh_lighting_server_recv_set_messgp__tb:l:ec_tmle_sthe_mlpi_grhatnigneg_server_state_change_t::hsl_

(C++ member), 331

(C++ member), 330

esp_ble_mesh_lighting_server_recv_set_messgp__tb:l:eh_smlesh_lighting_server_state_change_t::hsl_

(C++ member), 331

(C++ member), 330

esp_ble_mesh_lighting_server_recv_set_messgp__tb:l:eh_smle_sdhe_flaiuglhtting_server_state_change_t::lc_l

(C++ member), 332

(C++ member), 331

esp_ble_mesh_lighting_server_recv_set_messgp__tb:l:eh_smle_shhu_elighting_server_state_change_t::lc_m

(C++ member), 331

(C++ member), 331

esp_ble_mesh_lighting_server_recv_set_messgp__tb:l:eh_smle_srha_nlgieghting_server_state_change_t::lc_o

(C++ member), 332

(C++ member), 331

esp_ble_mesh_lighting_server_recv_set_messgp__tb:l:eh_smle_ssha_tluirgahttiionng_server_state_change_t::lc_p

(C++ member), 331

(C++ member), 331

esp_ble_mesh_lighting_server_recv_set_messgp__tb:l:el_cm_elsihg_hlti_gohntoifnfg_server_state_change_t::ligh

(C++ member), 332

(C++ member), 330

esp_ble_mesh_lighting_server_recv_set_messgp__tb:l:el_cm_emsohd_elighting_server_state_change_t::ligh

(C++ member), 332

(C++ member), 330

esp_ble_mesh_lighting_server_recv_set_messgp__tb:l:el_cm_eosmh_lighting_server_state_change_t::ligh

(C++ member), 332

(C++ member), 330

esp_ble_mesh_lighting_server_recv_set_messgp__tb:l:el_cm_epsrho_pleirgthyting_server_state_change_t::ligh

(C++ member), 332

(C++ member), 330

esp_ble_mesh_lighting_server_recv_set_messgp__tb:l:el_imgehsthn_elsisghting_server_state_change_t::sens

(C++ member), 331

(C++ member), 331

esp_ble_mesh_lighting_server_recv_set_messgp__tb:l:el_imgehsthn_elsisg_hdteifnagu_lsterver_state_change_t::xyl_

(C++ member), 331

(C++ member), 330

esp_ble_mesh_lighting_server_recv_set_messgp__tb:l:el_imgehsthn_elsisg_hltiinnega_rserver_state_change_t::xyl_

(C++ member), 331

(C++ member), 331

esp_ble_mesh_lighting_server_recv_set_messgp__tb:l:el_imgehsthn_elsisg_hrtainngge_server_state_change_t::xyl_

(C++ member), 331

(C++ member), 330

esp_ble_mesh_lighting_server_recv_set_messgp__tb:l:ex_ymlesh_lpn_disable (C++ function),

(C++ member), 332

213

esp_ble_mesh_lighting_server_recv_set_mEsSgP__tB:L:Ex_yMlE_SdHe_fLaPuNl_tDISABLE_COMP_EVT

(C++ member), 332

(C++ enumerator), 208

esp_ble_mesh_lighting_server_recv_set_messgp__tb:l:ex_ymle_srha_nlgpen_enable (C++ function), 213

Espressif Systems

2056

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

ESP_BLE_MESH_LPN_ENABLE_COMP_EVT (C++

(C++ member), 178

enumerator), 208

esp_ble_mesh_model_cb_param_t::ble_mesh_mod_recv_

ESP_BLE_MESH_LPN_FRIENDSHIP_ESTABLISH_EVT (C++ member), 178

(C++ enumerator), 208

esp_ble_mesh_model_cb_param_t::ble_mesh_mod_recv_

ESP_BLE_MESH_LPN_FRIENDSHIP_TERMINATE_EVT (C++ member), 178

(C++ enumerator), 208

esp_ble_mesh_model_cb_param_t::ble_mesh_mod_recv_

esp_ble_mesh_lpn_poll (C++ function), 213

(C++ member), 178

ESP_BLE_MESH_LPN_POLL_COMP_EVT (C++ esp_ble_mesh_model_cb_param_t::ble_mesh_mod_recv_

enumerator), 208

(C++ member), 178

ESP_BLE_MESH_MECHANISM_JAMMED_ERROR (C esp_ble_mesh_model_cb_param_t::ble_mesh_model_ope

macro), 258

(C++ class), 178

ESP_BLE_MESH_MECHANISM_JAMMED_WARNING esp_ble_mesh_model_cb_param_t::ble_mesh_model_ope

(C macro), 258

(C++ member), 179

ESP_BLE_MESH_MEMORY_ERROR (C macro), 258 esp_ble_mesh_model_cb_param_t::ble_mesh_model_ope

ESP_BLE_MESH_MEMORY_WARNING (C macro),

(C++ member), 179

258

esp_ble_mesh_model_cb_param_t::ble_mesh_model_ope

ESP_BLE_MESH_MIC_LONG (C macro), 188

(C++ member), 179

ESP_BLE_MESH_MIC_SHORT (C macro), 188

esp_ble_mesh_model_cb_param_t::ble_mesh_model_ope

esp_ble_mesh_model (C++ class), 181

(C++ member), 179

esp_ble_mesh_model::cb (C++ member), 182 esp_ble_mesh_model_cb_param_t::ble_mesh_model_ope

esp_ble_mesh_model::company_id (C++

(C++ member), 179

member), 182

esp_ble_mesh_model_cb_param_t::ble_mesh_model_pub

esp_ble_mesh_model::element (C++ mem-

(C++ class), 179

ber), 182

esp_ble_mesh_model_cb_param_t::ble_mesh_model_pub

esp_ble_mesh_model::element_idx (C++

(C++ member), 179

member), 182

esp_ble_mesh_model_cb_param_t::ble_mesh_model_pub

esp_ble_mesh_model::flags (C++ member),

(C++ member), 179

182

esp_ble_mesh_model_cb_param_t::ble_mesh_model_pub

esp_ble_mesh_model::groups (C++ member),

(C++ class), 179

182

esp_ble_mesh_model_cb_param_t::ble_mesh_model_pub

esp_ble_mesh_model::keys (C++ member),

(C++ member), 179

182

esp_ble_mesh_model_cb_param_t::ble_mesh_model_sen

esp_ble_mesh_model::model_id (C++ mem-

(C++ class), 179

ber), 182

esp_ble_mesh_model_cb_param_t::ble_mesh_model_sen

esp_ble_mesh_model::model_idx (C++

(C++ member), 179

member), 182

esp_ble_mesh_model_cb_param_t::ble_mesh_model_sen

esp_ble_mesh_model::op (C++ member), 182

(C++ member), 179

esp_ble_mesh_model::pub (C++ member), 182 esp_ble_mesh_model_cb_param_t::ble_mesh_model_sen

esp_ble_mesh_model::user_data (C++

(C++ member), 179

member), 182

esp_ble_mesh_model_cb_param_t::ble_mesh_model_sen

esp_ble_mesh_model::vnd (C++ member), 182

(C++ member), 179

esp_ble_mesh_model::[anonymous] (C++ esp_ble_mesh_model_cb_param_t::ble_mesh_server_mo

member), 182

(C++ class), 179

esp_ble_mesh_model_cb_event_t (C++ esp_ble_mesh_model_cb_param_t::ble_mesh_server_mo

enum), 209

(C++ member), 180

esp_ble_mesh_model_cb_param_t (C++ esp_ble_mesh_model_cb_param_t::ble_mesh_server_mo

union), 177

(C++ member), 180

esp_ble_mesh_model_cb_param_t::ble_meshe_scpl_ibelnet__mmeosdhe_lm_osdeenld__ctbi_mpeaoruatm__pta:r:abmle_mesh_server_mo

(C++ class), 178

(C++ member), 180

esp_ble_mesh_model_cb_param_t::ble_meshe_scpl_ibelnet__mmeosdhe_lm_osdeenld__ctbi_mpeaoruatm__pta:r:acml:i:ecnttx_recv_publis

(C++ member), 178

(C++ member), 178

esp_ble_mesh_model_cb_param_t::ble_meshe_scpl_ibelnet__mmeosdhe_lm_osdeenld__ctbi_mpeaoruatm__pta:r:acml:i:emnotd_eslend_timeou

(C++ member), 178

(C++ member), 178

esp_ble_mesh_model_cb_param_t::ble_meshe_scpl_ibelnet__mmeosdhe_lm_osdeenld__ctbi_mpeaoruatm__pta:r:ammo:d:eolp_coopdeeration

(C++ member), 178

(C++ member), 178

esp_ble_mesh_model_cb_param_t::ble_meshe_smpo_db_lree_cmve_sphu_bmloidsehl__mcsbg__ppaarraamm_t::model_publish_comp

(C++ class), 178

(C++ member), 178

esp_ble_mesh_model_cb_param_t::ble_meshe_smpo_db_lree_cmve_sphu_bmloidsehl__mcsbg__ppaarraamm_:t::c:tmxodel_publish_upda

Espressif Systems

2057

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 178

257

esp_ble_mesh_model_cb_param_t::model_seEnSdP__cBoLmEp_MESH_MODEL_HEALTH_SRV (C macro),

(C++ member), 178

257

esp_ble_mesh_model_cb_param_t::server_mEoSdPe_lB_LuEp_dMaEtSeH__sMtOaDtEeL_ID_CONFIG_CLI (C

(C++ member), 178

macro), 191

esp_ble_mesh_model_cb_t (C++ type), 220

ESP_BLE_MESH_MODEL_ID_CONFIG_SRV (C

esp_ble_mesh_model_cbs_t (C++ class), 181

macro), 191

esp_ble_mesh_model_cbs_t::init_cb

ESP_BLE_MESH_MODEL_ID_GEN_ADMIN_PROP_SRV

(C++ member), 181

(C macro), 192

ESP_BLE_MESH_MODEL_CFG_CLI (C macro), 250 ESP_BLE_MESH_MODEL_ID_GEN_BATTERY_CLI

ESP_BLE_MESH_MODEL_CFG_SRV (C macro), 250

(C macro), 192

ESP_BLE_MESH_MODEL_EVT_MAX (C++ enumera- ESP_BLE_MESH_MODEL_ID_GEN_BATTERY_SRV

tor), 210

(C macro), 192

ESP_BLE_MESH_MODEL_GEN_ADMIN_PROP_SRV ESP_BLE_MESH_MODEL_ID_GEN_CLIENT_PROP_SRV

(C macro), 288

(C macro), 192

ESP_BLE_MESH_MODEL_GEN_BATTERY_CLI (C ESP_BLE_MESH_MODEL_ID_GEN_DEF_TRANS_TIME_CLI

macro), 286

(C macro), 192

ESP_BLE_MESH_MODEL_GEN_BATTERY_SRV (C ESP_BLE_MESH_MODEL_ID_GEN_DEF_TRANS_TIME_SRV

macro), 287

(C macro), 192

ESP_BLE_MESH_MODEL_GEN_CLIENT_PROP_SRV ESP_BLE_MESH_MODEL_ID_GEN_LEVEL_CLI (C

(C macro), 288

macro), 192

ESP_BLE_MESH_MODEL_GEN_DEF_TRANS_TIME_CELSIP_BLE_MESH_MODEL_ID_GEN_LEVEL_SRV (C

(C macro), 285

macro), 192

ESP_BLE_MESH_MODEL_GEN_DEF_TRANS_TIME_SERSVP_BLE_MESH_MODEL_ID_GEN_LOCATION_CLI

(C macro), 286

(C macro), 192

ESP_BLE_MESH_MODEL_GEN_LEVEL_CLI (C ESP_BLE_MESH_MODEL_ID_GEN_LOCATION_SETUP_SRV

macro), 285

(C macro), 192

ESP_BLE_MESH_MODEL_GEN_LEVEL_SRV (C ESP_BLE_MESH_MODEL_ID_GEN_LOCATION_SRV

macro), 286

(C macro), 192

ESP_BLE_MESH_MODEL_GEN_LOCATION_CLI (C ESP_BLE_MESH_MODEL_ID_GEN_MANUFACTURER_PROP_SRV

macro), 286

(C macro), 192

ESP_BLE_MESH_MODEL_GEN_LOCATION_SETUP_SERSVP_BLE_MESH_MODEL_ID_GEN_ONOFF_CLI (C

(C macro), 288

macro), 192

ESP_BLE_MESH_MODEL_GEN_LOCATION_SRV (C ESP_BLE_MESH_MODEL_ID_GEN_ONOFF_SRV (C

macro), 288

macro), 191

ESP_BLE_MESH_MODEL_GEN_MANUFACTURER_PROEPS_PS_RBVLE_MESH_MODEL_ID_GEN_POWER_LEVEL_CLI

(C macro), 288

(C macro), 192

ESP_BLE_MESH_MODEL_GEN_ONOFF_CLI (C ESP_BLE_MESH_MODEL_ID_GEN_POWER_LEVEL_SETUP_SRV

macro), 285

(C macro), 192

ESP_BLE_MESH_MODEL_GEN_ONOFF_SRV (C ESP_BLE_MESH_MODEL_ID_GEN_POWER_LEVEL_SRV

macro), 286

(C macro), 192

ESP_BLE_MESH_MODEL_GEN_POWER_LEVEL_CLI ESP_BLE_MESH_MODEL_ID_GEN_POWER_ONOFF_CLI

(C macro), 285

(C macro), 192

ESP_BLE_MESH_MODEL_GEN_POWER_LEVEL_SETUEPS_PS_RBVLE_MESH_MODEL_ID_GEN_POWER_ONOFF_SETUP_SRV

(C macro), 287

(C macro), 192

ESP_BLE_MESH_MODEL_GEN_POWER_LEVEL_SRV ESP_BLE_MESH_MODEL_ID_GEN_POWER_ONOFF_SRV

(C macro), 287

(C macro), 192

ESP_BLE_MESH_MODEL_GEN_POWER_ONOFF_CLI ESP_BLE_MESH_MODEL_ID_GEN_PROP_CLI (C

(C macro), 285

macro), 192

ESP_BLE_MESH_MODEL_GEN_POWER_ONOFF_SETUEPS_PS_RBVLE_MESH_MODEL_ID_GEN_USER_PROP_SRV

(C macro), 287

(C macro), 192

ESP_BLE_MESH_MODEL_GEN_POWER_ONOFF_SRV ESP_BLE_MESH_MODEL_ID_HEALTH_CLI (C

(C macro), 287

macro), 191

ESP_BLE_MESH_MODEL_GEN_PROPERTY_CLI (C ESP_BLE_MESH_MODEL_ID_HEALTH_SRV (C

macro), 286

macro), 191

ESP_BLE_MESH_MODEL_GEN_USER_PROP_SRV ESP_BLE_MESH_MODEL_ID_LIGHT_CTL_CLI (C

(C macro), 288

macro), 192

ESP_BLE_MESH_MODEL_HEALTH_CLI (C macro), ESP_BLE_MESH_MODEL_ID_LIGHT_CTL_SETUP_SRV

Espressif Systems

2058

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C macro), 192

macro), 364

ESP_BLE_MESH_MODEL_ID_LIGHT_CTL_SRV (C ESP_BLE_MESH_MODEL_LIGHT_CTL_SETUP_SRV

macro), 192

(C macro), 365

ESP_BLE_MESH_MODEL_ID_LIGHT_CTL_TEMP_SREVSP_BLE_MESH_MODEL_LIGHT_CTL_SRV (C

(C macro), 192

macro), 365

ESP_BLE_MESH_MODEL_ID_LIGHT_HSL_CLI (C ESP_BLE_MESH_MODEL_LIGHT_CTL_TEMP_SRV

macro), 193

(C macro), 365

ESP_BLE_MESH_MODEL_ID_LIGHT_HSL_HUE_SRVESP_BLE_MESH_MODEL_LIGHT_HSL_CLI (C

(C macro), 193

macro), 364

ESP_BLE_MESH_MODEL_ID_LIGHT_HSL_SAT_SRVESP_BLE_MESH_MODEL_LIGHT_HSL_HUE_SRV

(C macro), 193

(C macro), 366

ESP_BLE_MESH_MODEL_ID_LIGHT_HSL_SETUP_SERSVP_BLE_MESH_MODEL_LIGHT_HSL_SAT_SRV

(C macro), 193

(C macro), 366

ESP_BLE_MESH_MODEL_ID_LIGHT_HSL_SRV (C ESP_BLE_MESH_MODEL_LIGHT_HSL_SETUP_SRV

macro), 193

(C macro), 366

ESP_BLE_MESH_MODEL_ID_LIGHT_LC_CLI (C ESP_BLE_MESH_MODEL_LIGHT_HSL_SRV (C

macro), 193

macro), 365

ESP_BLE_MESH_MODEL_ID_LIGHT_LC_SETUP_SREVSP_BLE_MESH_MODEL_LIGHT_LC_CLI

(C

(C macro), 193

macro), 364

ESP_BLE_MESH_MODEL_ID_LIGHT_LC_SRV (C ESP_BLE_MESH_MODEL_LIGHT_LC_SETUP_SRV

macro), 193

(C macro), 367

ESP_BLE_MESH_MODEL_ID_LIGHT_LIGHTNESS_CELSIP_BLE_MESH_MODEL_LIGHT_LC_SRV

(C

(C macro), 192

macro), 367

ESP_BLE_MESH_MODEL_ID_LIGHT_LIGHTNESS_SEESTPU_PB_LSER_VMESH_MODEL_LIGHT_LIGHTNESS_CLI

(C macro), 192

(C macro), 364

ESP_BLE_MESH_MODEL_ID_LIGHT_LIGHTNESS_SERSVP_BLE_MESH_MODEL_LIGHT_LIGHTNESS_SETUP_SRV

(C macro), 192

(C macro), 365

ESP_BLE_MESH_MODEL_ID_LIGHT_XYL_CLI (C ESP_BLE_MESH_MODEL_LIGHT_LIGHTNESS_SRV

macro), 193

(C macro), 364

ESP_BLE_MESH_MODEL_ID_LIGHT_XYL_SETUP_SERSVP_BLE_MESH_MODEL_LIGHT_XYL_CLI (C

(C macro), 193

macro), 364

ESP_BLE_MESH_MODEL_ID_LIGHT_XYL_SRV (C ESP_BLE_MESH_MODEL_LIGHT_XYL_SETUP_SRV

macro), 193

(C macro), 366

ESP_BLE_MESH_MODEL_ID_SCENE_CLI

(C ESP_BLE_MESH_MODEL_LIGHT_XYL_SRV (C

macro), 192

macro), 366

ESP_BLE_MESH_MODEL_ID_SCENE_SETUP_SRV esp_ble_mesh_model_msg_opcode_init

(C macro), 192

(C++ function), 214

ESP_BLE_MESH_MODEL_ID_SCENE_SRV

(C ESP_BLE_MESH_MODEL_NONE (C macro), 191

macro), 192

ESP_BLE_MESH_MODEL_OP (C macro), 191

ESP_BLE_MESH_MODEL_ID_SCHEDULER_CLI (C ESP_BLE_MESH_MODEL_OP_1 (C macro), 190

macro), 192

ESP_BLE_MESH_MODEL_OP_2 (C macro), 190

ESP_BLE_MESH_MODEL_ID_SCHEDULER_SETUP_SERSVP_BLE_MESH_MODEL_OP_3 (C macro), 190

(C macro), 192

ESP_BLE_MESH_MODEL_OP_APP_KEY_ADD (C

ESP_BLE_MESH_MODEL_ID_SCHEDULER_SRV (C

macro), 194

macro), 192

ESP_BLE_MESH_MODEL_OP_APP_KEY_DELETE

ESP_BLE_MESH_MODEL_ID_SENSOR_CLI (C

(C macro), 195

macro), 192

ESP_BLE_MESH_MODEL_OP_APP_KEY_GET (C

ESP_BLE_MESH_MODEL_ID_SENSOR_SETUP_SRV

macro), 193

(C macro), 192

ESP_BLE_MESH_MODEL_OP_APP_KEY_LIST (C

ESP_BLE_MESH_MODEL_ID_SENSOR_SRV (C

macro), 195

macro), 192

ESP_BLE_MESH_MODEL_OP_APP_KEY_STATUS

ESP_BLE_MESH_MODEL_ID_TIME_CLI

(C

(C macro), 195

macro), 192

ESP_BLE_MESH_MODEL_OP_APP_KEY_UPDATE

ESP_BLE_MESH_MODEL_ID_TIME_SETUP_SRV

(C macro), 194

(C macro), 192

ESP_BLE_MESH_MODEL_OP_ATTENTION_GET (C

ESP_BLE_MESH_MODEL_ID_TIME_SRV

(C

macro), 196

macro), 192

ESP_BLE_MESH_MODEL_OP_ATTENTION_SET (C

ESP_BLE_MESH_MODEL_LIGHT_CTL_CLI (C

macro), 196

Espressif Systems

2059

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

ESP_BLE_MESH_MODEL_OP_ATTENTION_SET_UNACK (C macro), 197

(C macro), 196

ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIME_STATUS

ESP_BLE_MESH_MODEL_OP_ATTENTION_STATUS

(C macro), 197

(C macro), 196

ESP_BLE_MESH_MODEL_OP_GEN_DELTA_SET (C

ESP_BLE_MESH_MODEL_OP_BEACON_GET (C

macro), 197

macro), 193

ESP_BLE_MESH_MODEL_OP_GEN_DELTA_SET_UNACK

ESP_BLE_MESH_MODEL_OP_BEACON_SET (C

(C macro), 197

macro), 194

ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_GET (C

ESP_BLE_MESH_MODEL_OP_BEACON_STATUS (C

macro), 197

macro), 195

ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_SET (C

ESP_BLE_MESH_MODEL_OP_COMPOSITION_DATA_GET macro), 197

(C macro), 193

ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_SET_UNACK

ESP_BLE_MESH_MODEL_OP_COMPOSITION_DATA_STATUS (C macro), 197

(C macro), 195

ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_STATUS

ESP_BLE_MESH_MODEL_OP_DEFAULT_TTL_GET

(C macro), 197

(C macro), 193

ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_GET

ESP_BLE_MESH_MODEL_OP_DEFAULT_TTL_SET

(C macro), 198

(C macro), 194

ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_SET

ESP_BLE_MESH_MODEL_OP_DEFAULT_TTL_STATUS

(C macro), 198

(C macro), 195

ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_SET_UNACK

ESP_BLE_MESH_MODEL_OP_END (C macro), 191

(C macro), 198

ESP_BLE_MESH_MODEL_OP_FRIEND_GET (C ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_STATUS

macro), 193

(C macro), 198

ESP_BLE_MESH_MODEL_OP_FRIEND_SET (C ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_GET

macro), 194

(C macro), 198

ESP_BLE_MESH_MODEL_OP_FRIEND_STATUS (C ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_SET

macro), 195

(C macro), 198

ESP_BLE_MESH_MODEL_OP_GATT_PROXY_GET ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_SET_UNACK

(C macro), 193

(C macro), 198

ESP_BLE_MESH_MODEL_OP_GATT_PROXY_SET ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_STATUS

(C macro), 194

(C macro), 198

ESP_BLE_MESH_MODEL_OP_GATT_PROXY_STATUSESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTIES

(C macro), 195

(C macro), 198

ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTEISEPS__BGLEET_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTIES

(C macro), 198

(C macro), 198

ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTEISEPS__BSLTEA_TMUESSH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_G

(C macro), 198

(C macro), 198

ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTEYS_PG_EBTLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_S

(C macro), 198

(C macro), 198

ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTEYS_PS_EBTLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_S

(C macro), 198

(C macro), 198

ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTEYS_PS_EBTL_EU_NMAECSKH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_S

(C macro), 198

(C macro), 198

ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTEYS_PS_TBALTEU_SMESH_MODEL_OP_GEN_MOVE_SET (C

(C macro), 198

macro), 197

ESP_BLE_MESH_MODEL_OP_GEN_BATTERY_GET ESP_BLE_MESH_MODEL_OP_GEN_MOVE_SET_UNACK

(C macro), 197

(C macro), 197

ESP_BLE_MESH_MODEL_OP_GEN_BATTERY_STATUESSP_BLE_MESH_MODEL_OP_GEN_ONOFF_GET (C

(C macro), 197

macro), 196

ESP_BLE_MESH_MODEL_OP_GEN_CLIENT_PROPERETSIPE_SB_LGEE_TMESH_MODEL_OP_GEN_ONOFF_SET (C

(C macro), 198

macro), 197

ESP_BLE_MESH_MODEL_OP_GEN_CLIENT_PROPERETSIPE_SB_LSET_AMTEUSSH_MODEL_OP_GEN_ONOFF_SET_UNACK

(C macro), 198

(C macro), 197

ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIMEES_PG_EBTLE_MESH_MODEL_OP_GEN_ONOFF_STATUS

(C macro), 197

(C macro), 197

ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIMEES_PS_EBTLE_MESH_MODEL_OP_GEN_ONPOWERUP_GET

(C macro), 197

(C macro), 197

ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIMEES_PS_EBTL_EU_NMAECSKH_MODEL_OP_GEN_ONPOWERUP_SET

Espressif Systems

2060

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C macro), 197

(C macro), 196

ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_SETE_SUPN_ABCLKE_MESH_MODEL_OP_HEALTH_PERIOD_GET

(C macro), 197

(C macro), 196

ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_STAETSUPS_BLE_MESH_MODEL_OP_HEALTH_PERIOD_SET

(C macro), 197

(C macro), 196

ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULTE_SGPE_TBLE_MESH_MODEL_OP_HEALTH_PERIOD_SET_UNACK

(C macro), 197

(C macro), 196

ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULTE_SSPE_TBLE_MESH_MODEL_OP_HEALTH_PERIOD_STATUS

(C macro), 197

(C macro), 196

ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULTE_SSPE_TB_LUEN_AMCEKSH_MODEL_OP_HEARTBEAT_PUB_GET

(C macro), 197

(C macro), 193

ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULTE_SSPT_ABTLUES_MESH_MODEL_OP_HEARTBEAT_PUB_SET

(C macro), 197

(C macro), 194

ESP_BLE_MESH_MODEL_OP_GEN_POWER_LAST_GEETSP_BLE_MESH_MODEL_OP_HEARTBEAT_PUB_STATUS

(C macro), 197

(C macro), 195

ESP_BLE_MESH_MODEL_OP_GEN_POWER_LAST_STEASTPU_SBLE_MESH_MODEL_OP_HEARTBEAT_SUB_GET

(C macro), 197

(C macro), 193

ESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_GEESTP_BLE_MESH_MODEL_OP_HEARTBEAT_SUB_SET

(C macro), 197

(C macro), 194

ESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_SEESTP_BLE_MESH_MODEL_OP_HEARTBEAT_SUB_STATUS

(C macro), 197

(C macro), 195

ESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_SEESTP__UBNLAEC_KMESH_MODEL_OP_KEY_REFRESH_PHASE_GET

(C macro), 197

(C macro), 193

ESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_SETSAPT_UBSLE_MESH_MODEL_OP_KEY_REFRESH_PHASE_SET

(C macro), 197

(C macro), 195

ESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_GEESTP_BLE_MESH_MODEL_OP_KEY_REFRESH_PHASE_STATUS

(C macro), 197

(C macro), 195

ESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_SEESTP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULT_GET

(C macro), 197

(C macro), 200

ESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_SEESTP__UBNLAEC_KMESH_MODEL_OP_LIGHT_CTL_DEFAULT_SET

(C macro), 197

(C macro), 200

ESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_SETSAPT_UBSLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULT_SET_UNACK

(C macro), 197

(C macro), 200

ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTIEESSP__GBELTE_MESH_MODEL_OP_LIGHT_CTL_DEFAULT_STATUS

(C macro), 198

(C macro), 200

ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTIEESSP__SBTLAET_UMSESH_MODEL_OP_LIGHT_CTL_GET (C

(C macro), 198

macro), 200

ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTYE_SGPE_TBLE_MESH_MODEL_OP_LIGHT_CTL_SET (C

(C macro), 198

macro), 200

ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTYE_SSPE_TBLE_MESH_MODEL_OP_LIGHT_CTL_SET_UNACK

(C macro), 198

(C macro), 200

ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTYE_SSPE_TB_LUEN_AMCEKSH_MODEL_OP_LIGHT_CTL_STATUS

(C macro), 198

(C macro), 200

ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTYE_SSPT_ABTLUES_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_GET

(C macro), 198

(C macro), 200

ESP_BLE_MESH_MODEL_OP_HEALTH_CURRENT_STEASTPU_SBLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_RANGE

(C macro), 196

(C macro), 200

ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_CLEAERSP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_RANGE

(C macro), 196

(C macro), 200

ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_CLEAERS_PU_NBALCEK_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_RANGE

(C macro), 196

(C macro), 201

ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_GET ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_RANGE

(C macro), 196

(C macro), 200

ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_STATEUSSP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_SET

(C macro), 196

(C macro), 200

ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_TESTESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_SET_U

(C macro), 196

(C macro), 200

ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_TESTE_SUPN_ABCLKE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_STATU

Espressif Systems

2061

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C macro), 200

(C macro), 202

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULTE_SGPE_TBLE_MESH_MODEL_OP_LIGHT_LC_MODE_STATUS

(C macro), 201

(C macro), 202

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULTE_SSPE_TBLE_MESH_MODEL_OP_LIGHT_LC_OM_GET

(C macro), 201

(C macro), 202

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULTE_SSPE_TB_LUEN_AMCEKSH_MODEL_OP_LIGHT_LC_OM_SET

(C macro), 201

(C macro), 202

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULTE_SSPT_ABTLUES_MESH_MODEL_OP_LIGHT_LC_OM_SET_UNACK

(C macro), 201

(C macro), 202

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_GET (C ESP_BLE_MESH_MODEL_OP_LIGHT_LC_OM_STATUS

macro), 201

(C macro), 202

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_GETESP_BLE_MESH_MODEL_OP_LIGHT_LC_PROPERTY_GET

(C macro), 201

(C macro), 202

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_SETESP_BLE_MESH_MODEL_OP_LIGHT_LC_PROPERTY_SET

(C macro), 201

(C macro), 202

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_SETE_SUPN_ABCLKE_MESH_MODEL_OP_LIGHT_LC_PROPERTY_SET_UNACK

(C macro), 201

(C macro), 202

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_STAETSUPS_BLE_MESH_MODEL_OP_LIGHT_LC_PROPERTY_STATUS

(C macro), 201

(C macro), 202

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_GEESTP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEFAULT_GET

(C macro), 201

(C macro), 200

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_SEESTP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEFAULT_SET

(C macro), 201

(C macro), 200

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_SEESTP__UBNLAEC_KMESH_MODEL_OP_LIGHT_LIGHTNESS_DEFAULT_SET

(C macro), 201

(C macro), 200

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_SETSAPT_UBSLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEFAULT_STA

(C macro), 201

(C macro), 200

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SATURATEISOPN__BGLEET_MESH_MODEL_OP_LIGHT_LIGHTNESS_GET

(C macro), 201

(C macro), 200

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SATURATEISOPN__BSLEET_MESH_MODEL_OP_LIGHT_LIGHTNESS_LAST_GET

(C macro), 201

(C macro), 200

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SATURATEISOPN__BSLEET__MUENSAHC_KMODEL_OP_LIGHT_LIGHTNESS_LAST_STATUS

(C macro), 201

(C macro), 200

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SATURATEISOPN__BSLTEA_TMUESSH_MODEL_OP_LIGHT_LIGHTNESS_LINEAR_GET

(C macro), 201

(C macro), 200

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SET (C ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LINEAR_SET

macro), 201

(C macro), 200

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SET_UNAECSKP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LINEAR_SET_

(C macro), 201

(C macro), 200

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_STATUS ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LINEAR_STAT

(C macro), 201

(C macro), 200

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_TARGET_EGSEPT_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_RANGE_GET

(C macro), 201

(C macro), 200

ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_TARGET_ESSTPA_TBULSE_MESH_MODEL_OP_LIGHT_LIGHTNESS_RANGE_SET

(C macro), 201

(C macro), 200

ESP_BLE_MESH_MODEL_OP_LIGHT_LC_LIGHT_ONEOSFPF__BGLEET_MESH_MODEL_OP_LIGHT_LIGHTNESS_RANGE_SET_U

(C macro), 202

(C macro), 200

ESP_BLE_MESH_MODEL_OP_LIGHT_LC_LIGHT_ONEOSFPF__BSLEET_MESH_MODEL_OP_LIGHT_LIGHTNESS_RANGE_STATU

(C macro), 202

(C macro), 200

ESP_BLE_MESH_MODEL_OP_LIGHT_LC_LIGHT_ONEOSFPF__BSLEET__MUENSAHC_KMODEL_OP_LIGHT_LIGHTNESS_SET

(C macro), 202

(C macro), 200

ESP_BLE_MESH_MODEL_OP_LIGHT_LC_LIGHT_ONEOSFPF__BSLTEA_TMUESSH_MODEL_OP_LIGHT_LIGHTNESS_SET_UNACK

(C macro), 202

(C macro), 200

ESP_BLE_MESH_MODEL_OP_LIGHT_LC_MODE_GETESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_STATUS

(C macro), 202

(C macro), 200

ESP_BLE_MESH_MODEL_OP_LIGHT_LC_MODE_SETESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULT_GET

(C macro), 202

(C macro), 201

ESP_BLE_MESH_MODEL_OP_LIGHT_LC_MODE_SETE_SUPN_ABCLKE_MESH_MODEL_OP_LIGHT_XYL_DEFAULT_SET

Espressif Systems

2062

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C macro), 201

(C macro), 194

ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULTE_SSPE_TB_LUEN_AMCEKSH_MODEL_OP_NET_KEY_ADD (C

(C macro), 201

macro), 194

ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULTE_SSPT_ABTLUES_MESH_MODEL_OP_NET_KEY_DELETE

(C macro), 201

(C macro), 194

ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_GET (C ESP_BLE_MESH_MODEL_OP_NET_KEY_GET (C

macro), 201

macro), 193

ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_GEESTP_BLE_MESH_MODEL_OP_NET_KEY_LIST (C

(C macro), 201

macro), 195

ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_SEESTP_BLE_MESH_MODEL_OP_NET_KEY_STATUS

(C macro), 201

(C macro), 195

ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_SEESTP__UBNLAEC_KMESH_MODEL_OP_NET_KEY_UPDATE

(C macro), 202

(C macro), 194

ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_SETSAPT_UBSLE_MESH_MODEL_OP_NETWORK_TRANSMIT_GET

(C macro), 201

(C macro), 194

ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_SET (C ESP_BLE_MESH_MODEL_OP_NETWORK_TRANSMIT_SET

macro), 201

(C macro), 195

ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_SET_UNAECSKP_BLE_MESH_MODEL_OP_NETWORK_TRANSMIT_STATUS

(C macro), 201

(C macro), 195

ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_STATUS ESP_BLE_MESH_MODEL_OP_NODE_IDENTITY_GET

(C macro), 201

(C macro), 193

ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_TARGET_EGSEPT_BLE_MESH_MODEL_OP_NODE_IDENTITY_SET

(C macro), 201

(C macro), 195

ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_TARGET_ESSTPA_TBULSE_MESH_MODEL_OP_NODE_IDENTITY_STATUS

(C macro), 201

(C macro), 195

ESP_BLE_MESH_MODEL_OP_LPN_POLLTIMEOUT_GEESTP_BLE_MESH_MODEL_OP_NODE_RESET (C

(C macro), 194

macro), 194

ESP_BLE_MESH_MODEL_OP_LPN_POLLTIMEOUT_SETSAPT_UBSLE_MESH_MODEL_OP_NODE_RESET_STATUS

(C macro), 195

(C macro), 195

ESP_BLE_MESH_MODEL_OP_MODEL_APP_BIND ESP_BLE_MESH_MODEL_OP_RELAY_GET

(C

(C macro), 194

macro), 193

ESP_BLE_MESH_MODEL_OP_MODEL_APP_STATUS ESP_BLE_MESH_MODEL_OP_RELAY_SET

(C

(C macro), 195

macro), 194

ESP_BLE_MESH_MODEL_OP_MODEL_APP_UNBIND ESP_BLE_MESH_MODEL_OP_RELAY_STATUS (C

(C macro), 195

macro), 195

ESP_BLE_MESH_MODEL_OP_MODEL_PUB_GET (C ESP_BLE_MESH_MODEL_OP_SCENE_DELETE (C

macro), 193

macro), 199

ESP_BLE_MESH_MODEL_OP_MODEL_PUB_SET (C ESP_BLE_MESH_MODEL_OP_SCENE_DELETE_UNACK

macro), 194

(C macro), 199

ESP_BLE_MESH_MODEL_OP_MODEL_PUB_STATUS ESP_BLE_MESH_MODEL_OP_SCENE_GET

(C

(C macro), 195

macro), 199

ESP_BLE_MESH_MODEL_OP_MODEL_PUB_VIRTUALE_SAPD_DBRL_ES_EMTESH_MODEL_OP_SCENE_RECALL (C

(C macro), 195

macro), 199

ESP_BLE_MESH_MODEL_OP_MODEL_SUB_ADD (C ESP_BLE_MESH_MODEL_OP_SCENE_RECALL_UNACK

macro), 194

(C macro), 199

ESP_BLE_MESH_MODEL_OP_MODEL_SUB_DELETE ESP_BLE_MESH_MODEL_OP_SCENE_REGISTER_GET

(C macro), 194

(C macro), 199

ESP_BLE_MESH_MODEL_OP_MODEL_SUB_DELETE_EASLPL_BLE_MESH_MODEL_OP_SCENE_REGISTER_STATUS

(C macro), 195

(C macro), 199

ESP_BLE_MESH_MODEL_OP_MODEL_SUB_OVERWRIETSEP_BLE_MESH_MODEL_OP_SCENE_STATUS (C

(C macro), 194

macro), 199

ESP_BLE_MESH_MODEL_OP_MODEL_SUB_STATUS ESP_BLE_MESH_MODEL_OP_SCENE_STORE (C

(C macro), 195

macro), 199

ESP_BLE_MESH_MODEL_OP_MODEL_SUB_VIRTUALE_SAPD_DBRL_EA_DMDESH_MODEL_OP_SCENE_STORE_UNACK

(C macro), 194

(C macro), 199

ESP_BLE_MESH_MODEL_OP_MODEL_SUB_VIRTUALE_SAPD_DBRL_ED_EMLEESTHE_MODEL_OP_SCHEDULER_ACT_GET

(C macro), 194

(C macro), 199

ESP_BLE_MESH_MODEL_OP_MODEL_SUB_VIRTUALE_SAPD_DBRL_EO_VMEERSWHR_IMTOEDEL_OP_SCHEDULER_ACT_SET

Espressif Systems

2063

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C macro), 200

esp_ble_mesh_model_op_t::param_cb

ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_SET_UNACK (C++ member), 181

(C macro), 200

ESP_BLE_MESH_MODEL_OP_TAI_UTC_DELTA_GET

ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_STATUS (C macro), 199

(C macro), 199

ESP_BLE_MESH_MODEL_OP_TAI_UTC_DELTA_SET

ESP_BLE_MESH_MODEL_OP_SCHEDULER_GET (C

(C macro), 199

macro), 199

ESP_BLE_MESH_MODEL_OP_TAI_UTC_DELTA_STATUS

ESP_BLE_MESH_MODEL_OP_SCHEDULER_STATUS

(C macro), 199

(C macro), 200

ESP_BLE_MESH_MODEL_OP_TIME_GET

(C

ESP_BLE_MESH_MODEL_OP_SENSOR_CADENCE_GET

macro), 199

(C macro), 199

ESP_BLE_MESH_MODEL_OP_TIME_ROLE_GET (C

ESP_BLE_MESH_MODEL_OP_SENSOR_CADENCE_SET

macro), 199

(C macro), 199

ESP_BLE_MESH_MODEL_OP_TIME_ROLE_SET (C

ESP_BLE_MESH_MODEL_OP_SENSOR_CADENCE_SET_UNACKmacro), 199

(C macro), 199

ESP_BLE_MESH_MODEL_OP_TIME_ROLE_STATUS

ESP_BLE_MESH_MODEL_OP_SENSOR_CADENCE_STATUS (C macro), 199

(C macro), 199

ESP_BLE_MESH_MODEL_OP_TIME_SET

(C

ESP_BLE_MESH_MODEL_OP_SENSOR_COLUMN_GET

macro), 199

(C macro), 198

ESP_BLE_MESH_MODEL_OP_TIME_STATUS (C

ESP_BLE_MESH_MODEL_OP_SENSOR_COLUMN_STATUS macro), 199

(C macro), 198

ESP_BLE_MESH_MODEL_OP_TIME_ZONE_GET (C

ESP_BLE_MESH_MODEL_OP_SENSOR_DESCRIPTOR_GET macro), 199

(C macro), 198

ESP_BLE_MESH_MODEL_OP_TIME_ZONE_SET (C

ESP_BLE_MESH_MODEL_OP_SENSOR_DESCRIPTOR_STATUSmacro), 199

(C macro), 198

ESP_BLE_MESH_MODEL_OP_TIME_ZONE_STATUS

ESP_BLE_MESH_MODEL_OP_SENSOR_GET (C

(C macro), 199

macro), 198

ESP_BLE_MESH_MODEL_OP_VENDOR_MODEL_APP_GET

ESP_BLE_MESH_MODEL_OP_SENSOR_SERIES_GET

(C macro), 193

(C macro), 198

ESP_BLE_MESH_MODEL_OP_VENDOR_MODEL_APP_LIST

ESP_BLE_MESH_MODEL_OP_SENSOR_SERIES_STATUS (C macro), 195

(C macro), 199

ESP_BLE_MESH_MODEL_OP_VENDOR_MODEL_SUB_GET

ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_GET

(C macro), 193

(C macro), 199

ESP_BLE_MESH_MODEL_OP_VENDOR_MODEL_SUB_LIST

ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_SET

(C macro), 195

(C macro), 199

ESP_BLE_MESH_MODEL_OPERATION_EVT (C++

ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_SET_UNACKenumerator), 209

(C macro), 199

ESP_BLE_MESH_MODEL_PUB_DEFINE (C macro),

ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_STATUS 191

(C macro), 199

esp_ble_mesh_model_pub_t (C++ class), 180

ESP_BLE_MESH_MODEL_OP_SENSOR_SETTINGS_GeEsTp_ble_mesh_model_pub_t::app_idx

(C macro), 199

(C++ member), 180

ESP_BLE_MESH_MODEL_OP_SENSOR_SETTINGS_SeTsApT_UbSle_mesh_model_pub_t::count (C++

(C macro), 199

member), 181

ESP_BLE_MESH_MODEL_OP_SENSOR_STATUS (C esp_ble_mesh_model_pub_t::cred (C++

macro), 198

member), 180

ESP_BLE_MESH_MODEL_OP_SIG_MODEL_APP_GETesp_ble_mesh_model_pub_t::dev_role

(C macro), 193

(C++ member), 181

ESP_BLE_MESH_MODEL_OP_SIG_MODEL_APP_LISeTsp_ble_mesh_model_pub_t::fast_period

(C macro), 195

(C++ member), 181

ESP_BLE_MESH_MODEL_OP_SIG_MODEL_SUB_GETesp_ble_mesh_model_pub_t::model (C++

(C macro), 193

member), 180

ESP_BLE_MESH_MODEL_OP_SIG_MODEL_SUB_LISeTsp_ble_mesh_model_pub_t::msg (C++

(C macro), 195

member), 181

esp_ble_mesh_model_op_t (C++ class), 181 esp_ble_mesh_model_pub_t::period (C++

esp_ble_mesh_model_op_t::min_len (C++

member), 181

member), 181

esp_ble_mesh_model_pub_t::period_div

esp_ble_mesh_model_op_t::opcode (C++

(C++ member), 181

member), 181

esp_ble_mesh_model_pub_t::period_start

Espressif Systems

2064

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 181

esp_ble_mesh_model_unsubscribe_group_addr

esp_ble_mesh_model_pub_t::publish_addr

(C++ function), 212

(C++ member), 180

ESP_BLE_MESH_MODEL_UNSUBSCRIBE_GROUP_ADDR_COMP_EV

esp_ble_mesh_model_pub_t::retransmit

(C++ enumerator), 209

(C++ member), 181

esp_ble_mesh_msg_ctx_t (C++ class), 182

esp_ble_mesh_model_pub_t::send_rel

esp_ble_mesh_msg_ctx_t::addr (C++ mem-

(C++ member), 180

ber), 182

esp_ble_mesh_model_pub_t::timer (C++ esp_ble_mesh_msg_ctx_t::app_idx (C++

member), 181

member), 182

esp_ble_mesh_model_pub_t::ttl (C++ esp_ble_mesh_msg_ctx_t::model (C++

member), 181

member), 183

esp_ble_mesh_model_pub_t::update (C++ esp_ble_mesh_msg_ctx_t::net_idx (C++

member), 181

member), 182

esp_ble_mesh_model_publish (C++ function), esp_ble_mesh_msg_ctx_t::recv_dst (C++

215

member), 182

ESP_BLE_MESH_MODEL_PUBLISH_COMP_EVT esp_ble_mesh_msg_ctx_t::recv_op (C++

(C++ enumerator), 209

member), 183

ESP_BLE_MESH_MODEL_PUBLISH_UPDATE_EVT esp_ble_mesh_msg_ctx_t::recv_rssi

(C++ enumerator), 210

(C++ member), 183

ESP_BLE_MESH_MODEL_SCENE_CLI (C macro), esp_ble_mesh_msg_ctx_t::recv_ttl (C++

323

member), 183

ESP_BLE_MESH_MODEL_SCENE_SETUP_SRV (C esp_ble_mesh_msg_ctx_t::send_rel (C++

macro), 324

member), 183

ESP_BLE_MESH_MODEL_SCENE_SRV (C macro), esp_ble_mesh_msg_ctx_t::send_ttl (C++

323

member), 183

ESP_BLE_MESH_MODEL_SCHEDULER_CLI (C esp_ble_mesh_msg_ctx_t::srv_send (C++

macro), 323

member), 183

ESP_BLE_MESH_MODEL_SCHEDULER_SETUP_SRV ESP_BLE_MESH_NET_PRIMARY (C macro), 188

(C macro), 324

ESP_BLE_MESH_NO_FAULT (C macro), 257

ESP_BLE_MESH_MODEL_SCHEDULER_SRV (C ESP_BLE_MESH_NO_INPUT (C++ enumerator), 204

macro), 324

ESP_BLE_MESH_NO_LOAD_ERROR (C macro), 257

ESP_BLE_MESH_MODEL_SEND_COMP_EVT (C++ ESP_BLE_MESH_NO_LOAD_WARNING (C macro),

enumerator), 209

257

ESP_BLE_MESH_MODEL_SENSOR_CLI (C macro), ESP_BLE_MESH_NO_OOB (C++ enumerator), 204

302

ESP_BLE_MESH_NO_OUTPUT (C++ enumerator),

ESP_BLE_MESH_MODEL_SENSOR_SETUP_SRV (C

204

macro), 302

esp_ble_mesh_node_add_local_app_key

ESP_BLE_MESH_MODEL_SENSOR_SRV (C macro),

(C++ function), 212

302

ESP_BLE_MESH_NODE_ADD_LOCAL_APP_KEY_COMP_EVT

ESP_BLE_MESH_MODEL_STATUS_CANNOT_SET_RANGE_MAX(C++ enumerator), 206

(C macro), 202

esp_ble_mesh_node_add_local_net_key

ESP_BLE_MESH_MODEL_STATUS_CANNOT_SET_RANGE_MIN(C++ function), 212

(C macro), 202

ESP_BLE_MESH_NODE_ADD_LOCAL_NET_KEY_COMP_EVT

ESP_BLE_MESH_MODEL_STATUS_SUCCESS (C

(C++ enumerator), 206

macro), 202

esp_ble_mesh_node_bind_app_key_to_local_model

esp_ble_mesh_model_status_t (C++ type),

(C++ function), 213

203

ESP_BLE_MESH_NODE_BIND_APP_KEY_TO_MODEL_COMP_EVT

esp_ble_mesh_model_subscribe_group_addr

(C++ enumerator), 206

(C++ function), 212

esp_ble_mesh_node_get_local_app_key

ESP_BLE_MESH_MODEL_SUBSCRIBE_GROUP_ADDR_COMP_E(CV+T+ function), 212

(C++ enumerator), 209

esp_ble_mesh_node_get_local_net_key

esp_ble_mesh_model_t (C++ type), 202

(C++ function), 212

ESP_BLE_MESH_MODEL_TIME_CLI (C macro), ESP_BLE_MESH_NODE_IDENTITY_NOT_SUPPORTED

323

(C macro), 189

ESP_BLE_MESH_MODEL_TIME_SETUP_SRV (C ESP_BLE_MESH_NODE_IDENTITY_RUNNING (C

macro), 323

macro), 189

ESP_BLE_MESH_MODEL_TIME_SRV (C macro), ESP_BLE_MESH_NODE_IDENTITY_STOPPED (C

323

macro), 189

Espressif Systems

2065

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_mesh_node_input_number (C++

member), 185

function), 221

esp_ble_mesh_node_t::dev_key (C++ mem-

esp_ble_mesh_node_input_string (C++

ber), 185

function), 221

esp_ble_mesh_node_t::dev_uuid (C++

esp_ble_mesh_node_is_provisioned (C++

member), 184

function), 221

esp_ble_mesh_node_t::element_num (C++

esp_ble_mesh_node_local_reset (C++ func-

member), 184

tion), 215

esp_ble_mesh_node_t::flags (C++ member),

ESP_BLE_MESH_NODE_NAME_MAX_LEN

(C

184

macro), 188

esp_ble_mesh_node_t::iv_index (C++

ESP_BLE_MESH_NODE_PROV_COMPLETE_EVT

member), 185

(C++ enumerator), 206

esp_ble_mesh_node_t::name (C++ member),

esp_ble_mesh_node_prov_disable (C++

185

function), 221

esp_ble_mesh_node_t::net_idx (C++ mem-

ESP_BLE_MESH_NODE_PROV_DISABLE_COMP_EVT

ber), 184

(C++ enumerator), 205

esp_ble_mesh_node_t::oob_info (C++

esp_ble_mesh_node_prov_enable (C++ func-

member), 184

tion), 221

esp_ble_mesh_node_t::unicast_addr

ESP_BLE_MESH_NODE_PROV_ENABLE_COMP_EVT

(C++ member), 184

(C++ enumerator), 205

ESP_BLE_MESH_OCTET16_LEN (C macro), 188

ESP_BLE_MESH_NODE_PROV_INPUT_EVT (C++ esp_ble_mesh_octet16_t (C++ type), 202

enumerator), 206

ESP_BLE_MESH_OCTET8_LEN (C macro), 188

ESP_BLE_MESH_NODE_PROV_INPUT_NUMBER_COMePs_pE_VbTle_mesh_octet8_t (C++ type), 202

(C++ enumerator), 206

esp_ble_mesh_oob_method_t (C++ enum), 204

ESP_BLE_MESH_NODE_PROV_INPUT_STRING_COMePs_pE_VbTle_mesh_opcode_config_client_get_t

(C++ enumerator), 206

(C++ type), 203

ESP_BLE_MESH_NODE_PROV_LINK_CLOSE_EVT esp_ble_mesh_opcode_config_client_set_t

(C++ enumerator), 205

(C++ type), 203

ESP_BLE_MESH_NODE_PROV_LINK_OPEN_EVT esp_ble_mesh_opcode_config_status_t

(C++ enumerator), 205

(C++ type), 203

ESP_BLE_MESH_NODE_PROV_OOB_PUB_KEY_EVT esp_ble_mesh_opcode_health_client_get_t

(C++ enumerator), 205

(C++ type), 203

ESP_BLE_MESH_NODE_PROV_OUTPUT_NUMBER_EVeTsp_ble_mesh_opcode_health_client_set_t

(C++ enumerator), 205

(C++ type), 203

ESP_BLE_MESH_NODE_PROV_OUTPUT_STRING_EVeTsp_ble_mesh_opcode_t (C++ type), 203

(C++ enumerator), 205

esp_ble_mesh_output_action_t (C++ enum),

ESP_BLE_MESH_NODE_PROV_RESET_EVT (C++

204

enumerator), 206

ESP_BLE_MESH_OUTPUT_OOB (C++ enumerator),

ESP_BLE_MESH_NODE_PROV_SET_OOB_PUB_KEY_COMP_EV2T04

(C++ enumerator), 206

ESP_BLE_MESH_OVERFLOW_ERROR (C macro),

ESP_BLE_MESH_NODE_PROXY_GATT_DISABLE_COMP_EVT 258

(C++ enumerator), 206

ESP_BLE_MESH_OVERFLOW_WARNING (C macro),

ESP_BLE_MESH_NODE_PROXY_GATT_ENABLE_COMP_EVT 258

(C++ enumerator), 206

ESP_BLE_MESH_OVERHEAT_ERROR (C macro),

ESP_BLE_MESH_NODE_PROXY_IDENTITY_ENABLE_COMP_E2V57T

(C++ enumerator), 206

ESP_BLE_MESH_OVERHEAT_WARNING (C macro),

esp_ble_mesh_node_set_oob_pub_key

257

(C++ function), 221

ESP_BLE_MESH_OVERLOAD_ERROR (C macro),

ESP_BLE_MESH_NODE_SET_UNPROV_DEV_NAME_COMP_EVT257

(C++ enumerator), 205

ESP_BLE_MESH_OVERLOAD_WARNING (C macro),

esp_ble_mesh_node_t (C++ class), 184

257

esp_ble_mesh_node_t::addr (C++ member), ESP_BLE_MESH_POWER_SUPPLY_INTERRUPTED_ERROR

184

(C macro), 257

esp_ble_mesh_node_t::addr_type (C++ ESP_BLE_MESH_POWER_SUPPLY_INTERRUPTED_WARNING

member), 184

(C macro), 257

esp_ble_mesh_node_t::comp_data (C++ ESP_BLE_MESH_PROV (C macro), 190

member), 185

ESP_BLE_MESH_PROV_ADV (C++ enumerator), 204

esp_ble_mesh_node_t::comp_length (C++ esp_ble_mesh_prov_adv_cb_t (C++ type), 225

Espressif Systems

2066

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_mesh_prov_bearer_t (C++ enum), esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_friend

204

(C++ member), 164

esp_ble_mesh_prov_cb_event_t (C++ enum), esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_friend

205

(C++ class), 164

esp_ble_mesh_prov_cb_param_t

(C++ esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_friend

union), 157

(C++ member), 164

esp_ble_mesh_prov_cb_param_t::ble_mesh_edsepi_nbilte__mmeesshh__cpormopv__pcabr_apmaram_t::ble_mesh_lpn_poll_c

(C++ class), 162

(C++ class), 164

esp_ble_mesh_prov_cb_param_t::ble_mesh_edsepi_nbilte__mmeesshh__cpormopv__pcabr_apma:r:aemr_rt_:c:obdlee_mesh_lpn_poll_c

(C++ member), 162

(C++ member), 164

esp_ble_mesh_prov_cb_param_t::ble_mesh_efsrpi_ebnlde__fmreisehn_dpsrhoivp__cebs_tpaabrlaims_ht_:p:abrlaem_mesh_model_sub_

(C++ class), 162

(C++ class), 164

esp_ble_mesh_prov_cb_param_t::ble_mesh_efsrpi_ebnlde__fmreisehn_dpsrhoivp__cebs_tpaabrlaims_ht_:p:abrlaem_:m:elsphn__maoddderl_sub_

(C++ member), 162

(C++ member), 165

esp_ble_mesh_prov_cb_param_t::ble_mesh_efsrpi_ebnlde__fmreisehn_dpsrhoivp__ctbe_rpmairnaamt_et_:p:abrlaem_mesh_model_sub_

(C++ class), 162

(C++ member), 165

esp_ble_mesh_prov_cb_param_t::ble_mesh_efsrpi_ebnlde__fmreisehn_dpsrhoivp__ctbe_rpmairnaamt_et_:p:abrlaem_:m:elsphn__maoddderl_sub_

(C++ member), 163

(C++ member), 165

esp_ble_mesh_prov_cb_param_t::ble_mesh_efsrpi_ebnlde__fmreisehn_dpsrhoivp__ctbe_rpmairnaamt_et_:p:abrlaem_:m:erseha_smoondel_sub_

(C++ member), 163

(C++ member), 165

esp_ble_mesh_prov_cb_param_t::ble_mesh_ehsepa_rbtlbee_amte_smhs_gp_rroevc_vc_bp_apraarmam_t::ble_mesh_model_sub_

(C++ class), 163

(C++ member), 165

esp_ble_mesh_prov_cb_param_t::ble_mesh_ehsepa_rbtlbee_amte_smhs_gp_rroevc_vc_bp_apraarma:m:_fte:a:tbulree_mesh_model_unsu

(C++ member), 163

(C++ class), 165

esp_ble_mesh_prov_cb_param_t::ble_mesh_ehsepa_rbtlbee_amte_smhs_gp_rroevc_vc_bp_apraarma:m:_hto:p:sble_mesh_model_unsu

(C++ member), 163

(C++ member), 165

esp_ble_mesh_prov_cb_param_t::ble_mesh_eisnpp_ubtl_ee_vmte_spha_rparmov_cb_param_t::ble_mesh_model_unsu

(C++ class), 163

(C++ member), 165

esp_ble_mesh_prov_cb_param_t::ble_mesh_eisnpp_ubtl_ee_vmte_spha_rparmo:v:_accbt_ipoanram_t::ble_mesh_model_unsu

(C++ member), 163

(C++ member), 165

esp_ble_mesh_prov_cb_param_t::ble_mesh_eisnpp_ubtl_ee_vmte_spha_rparmo:v:_scibz_eparam_t::ble_mesh_model_unsu

(C++ member), 163

(C++ member), 165

esp_ble_mesh_prov_cb_param_t::ble_mesh_eisnpp_ubtl_en_ummebsehr__pcroomvp__cpba_rpaamram_t::ble_mesh_model_unsu

(C++ class), 163

(C++ member), 165

esp_ble_mesh_prov_cb_param_t::ble_mesh_eisnpp_ubtl_en_ummebsehr__pcroomvp__cpba_rpaamr:a:me_rtr:_:cboldee_mesh_node_add_l

(C++ member), 163

(C++ class), 165

esp_ble_mesh_prov_cb_param_t::ble_mesh_eisnpp_ubtl_es_tmreisnhg__pcroomvp__cpba_rpaamram_t::ble_mesh_node_add_l

(C++ class), 163

(C++ member), 165

esp_ble_mesh_prov_cb_param_t::ble_mesh_eisnpp_ubtl_es_tmreisnhg__pcroomvp__cpba_rpaamr:a:me_rtr:_:cboldee_mesh_node_add_l

(C++ member), 163

(C++ member), 165

esp_ble_mesh_prov_cb_param_t::ble_mesh_elsipn_kb_lcel_omsees_he_vptr_opva_rcabm_param_t::ble_mesh_node_add_l

(C++ class), 163

(C++ member), 165

esp_ble_mesh_prov_cb_param_t::ble_mesh_elsipn_kb_lcel_omsees_he_vptr_opva_rcabm_:p:abreaamr_etr::ble_mesh_node_add_l

(C++ member), 164

(C++ class), 165

esp_ble_mesh_prov_cb_param_t::ble_mesh_elsipn_kb_loep_emne_sehv_tp_rpoavr_acmb_param_t::ble_mesh_node_add_l

(C++ class), 164

(C++ member), 165

esp_ble_mesh_prov_cb_param_t::ble_mesh_elsipn_kb_loep_emne_sehv_tp_rpoavr_acmb:_:pbaeraarme_rt::ble_mesh_node_add_l

(C++ member), 164

(C++ member), 165

esp_ble_mesh_prov_cb_param_t::ble_mesh_elsppn__bdlies_ambelseh__cpormopv__pcabr_apmaram_t::ble_mesh_node_bind_

(C++ class), 164

(C++ class), 165

esp_ble_mesh_prov_cb_param_t::ble_mesh_elsppn__bdlies_ambelseh__cpormopv__pcabr_apma:r:aemr_rt_:c:obdlee_mesh_node_bind_

(C++ member), 164

(C++ member), 166

esp_ble_mesh_prov_cb_param_t::ble_mesh_elsppn__belnea_bmlees_hc_opmrpo_vp_acrba_mparam_t::ble_mesh_node_bind_

(C++ class), 164

(C++ member), 166

esp_ble_mesh_prov_cb_param_t::ble_mesh_elsppn__belnea_bmlees_hc_opmrpo_vp_acrba_mp:a:rearmr__tc:o:dbele_mesh_node_bind_

(C++ member), 164

(C++ member), 166

esp_ble_mesh_prov_cb_param_t::ble_mesh_elsppn__bflrei_emnedsshh_ippr_oevs_tcabb_lpiasrha_mp_atr:a:mble_mesh_node_bind_

(C++ class), 164

(C++ member), 166

Espressif Systems

2067

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_mesh_prov_cb_param_t::ble_mesh_ensopd_eb_lbei_nmde_slho_cparlo_vm_ocdb__appapr_acmo_mtp:_:pbalrea_mm:e:smho_dperlo_viidsione

(C++ member), 166

(C++ member), 168

esp_ble_mesh_prov_cb_param_t::ble_mesh_eosupt_pbulte__nmuems_he_vptr_opva_rcabm_param_t::ble_mesh_provisione

(C++ class), 166

(C++ member), 168

esp_ble_mesh_prov_cb_param_t::ble_mesh_eosupt_pbulte__nmuems_he_vptr_opva_rcabm_:p:aarcatmi_otn::ble_mesh_provisione

(C++ member), 166

(C++ member), 168

esp_ble_mesh_prov_cb_param_t::ble_mesh_eosupt_pbulte__nmuems_he_vptr_opva_rcabm_:p:anruammb_etr::ble_mesh_provisione

(C++ member), 166

(C++ member), 168

esp_ble_mesh_prov_cb_param_t::ble_mesh_eosupt_pbulte__smters_he_vptr_opva_rcabm_param_t::ble_mesh_provisione

(C++ class), 166

(C++ member), 168

esp_ble_mesh_prov_cb_param_t::ble_mesh_eosupt_pbulte__smters_he_vptr_opva_rcabm_:p:asrtarmi_ntg::ble_mesh_provisione

(C++ member), 166

(C++ class), 168

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vb_ldei_smaebslhe__pcroomvp__cpba_rpaamram_t::ble_mesh_provisione

(C++ class), 166

(C++ member), 168

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vb_ldei_smaebslhe__pcroomvp__cpba_rpaamr:a:me_rtr:_:cboldee_mesh_provisione

(C++ member), 166

(C++ class), 168

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vb_leen_ambelseh__cpormopv__pcabr_apmaram_t::ble_mesh_provisione

(C++ class), 166

(C++ member), 168

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vb_leen_ambelseh__cpormopv__pcabr_apma:r:aemr_rt_:c:obdlee_mesh_provisione

(C++ member), 166

(C++ member), 168

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vb_lree_gmiessthe_rp_rcoovm_pc_bp_apraarmam_t::ble_mesh_provisione

(C++ class), 166

(C++ class), 168

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vb_lree_gmiessthe_rp_rcoovm_pc_bp_apraarma:m:_etr:r:_bcloed_emesh_provisione

(C++ member), 167

(C++ member), 168

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omne_scho_mpprloevt_ec_be_vpta_rpaamr_atm::ble_mesh_provisione

(C++ class), 167

(C++ member), 168

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omne_scho_mpprloevt_ec_be_vpta_rpaamr_atm::::balded_rmesh_provisione

(C++ member), 167

(C++ class), 168

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omne_scho_mpprloevt_ec_be_vpta_rpaamr_atm::::bfllea_gmsesh_provisione

(C++ member), 167

(C++ member), 169

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omne_scho_mpprloevt_ec_be_vpta_rpaamr_atm::::bilve__imnedsehx_provisione

(C++ member), 167

(C++ member), 169

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omne_scho_mpprloevt_ec_be_vpta_rpaamr_atm::::bnleet__miedsxh_provisione

(C++ member), 167

(C++ class), 169

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omne_scho_mpprloevt_ec_be_vpta_rpaamr_atm::::bnleet__mkeesyh_provisione

(C++ member), 167

(C++ member), 169

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omne_srhe_sperto_vp_acrba_mparam_t::ble_mesh_provisione

(C++ class), 167

(C++ class), 169

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__apdrdo_vl_occba_lp_aarpapm__kte:y:_bcloem_pm_epsahr_apmrovisione

(C++ class), 167

(C++ member), 169

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__apdrdo_vl_occba_lp_aarpapm__kte:y:_bcloem_pm_epsahr_apmr:o:vaipspi_oindex

(C++ member), 167

(C++ member), 169

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__apdrdo_vl_occba_lp_aarpapm__kte:y:_bcloem_pm_epsahr_apmr:o:veirsri_ocnoed

(C++ member), 167

(C++ member), 169

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__apdrdo_vl_occba_lp_aarpapm__kte:y:_bcloem_pm_epsahr_apmr:o:vniesti_oindex

(C++ member), 167

(C++ member), 169

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__apdrdo_vl_occba_lp_anreatm__kte:y:_bcloem_pm_epsahr_apmrovisione

(C++ class), 167

(C++ member), 169

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__apdrdo_vl_occba_lp_anreatm__kte:y:_bcloem_pm_epsahr_apmr:o:veirsri_ocnoed

(C++ member), 167

(C++ class), 169

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__apdrdo_vl_occba_lp_anreatm__kte:y:_bcloem_pm_epsahr_apmr:o:vniesti_oindex

(C++ member), 167

(C++ member), 169

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__apdrdo_vu_ncpbr_opva_rdaemv__tc:o:mbpl_ep_amreasmh_provisione

(C++ class), 167

(C++ class), 169

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__apdrdo_vu_ncpbr_opva_rdaemv__tc:o:mbpl_ep_amreasmh:_:perrorv_icsoidoene

(C++ member), 168

(C++ member), 169

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__bpirnodv__lcobc_apla_rmaomd__ta:p:pb_lceo_mmpe_spha_rparmovisione

(C++ class), 168

(C++ class), 169

Espressif Systems

2068

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__ecnba_bplaer_acmo_mtp:_:pbalrea_mm:e:sehr_rp_rcoovdiesione

(C++ member), 170

(C++ member), 171

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__icnbp_upta_reavmt__tp:a:rbalme_mesh_provisione

(C++ class), 170

(C++ class), 171

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__icnbp_upta_reavmt__tp:a:rbalme:_:maecsthi_opnrovisione

(C++ member), 170

(C++ member), 171

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__icnbp_upta_reavmt__tp:a:rbalme:_:mleisnhk__pirdoxvisione

(C++ member), 170

(C++ class), 171

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__icnbp_upta_reavmt__tp:a:rbalme:_:mmeesthh_opdrovisione

(C++ member), 170

(C++ member), 172

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__icnbp_upta_reavmt__tp:a:rbalme:_:mseiszhe_provisione

(C++ member), 170

(C++ member), 172

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__icnbp_upta_rnaumm__tc:o:mbpl_ep_amreasmh_provisione

(C++ class), 170

(C++ class), 172

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__icnbp_upta_rnaumm__tc:o:mbpl_ep_amreasmh:_:perrorv_icsoidoene

(C++ member), 170

(C++ member), 172

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__icnbp_upta_rsatmr__tc:o:mbpl_ep_amreasmh_provisione

(C++ class), 170

(C++ class), 172

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__icnbp_upta_rsatmr__tc:o:mbpl_ep_amreasmh:_:perrorv_icsoidoene

(C++ member), 170

(C++ member), 172

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__ocubt_ppuatr_aemv_tt_:p:abrlaem_mesh_provisione

(C++ class), 170

(C++ class), 172

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__ocubt_ppuatr_aemv_tt_:p:abrlaem_:m:eascht_ipornovisione

(C++ member), 170

(C++ member), 172

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__ocubt_ppuatr_aemv_tt_:p:abrlaem_:m:elsihn_kp_riodvxisione

(C++ member), 170

(C++ class), 172

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__ocubt_ppuatr_aemv_tt_:p:abrlaem_:m:emseht_hpordovisione

(C++ member), 170

(C++ member), 172

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__ocubt_ppuatr_aemv_tt_:p:abrlaem_:m:ensuhm_bperrovisione

(C++ member), 170

(C++ member), 172

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__ocubt_ppuatr_aemv_tt_:p:abrlaem_:m:essihz_eprovisione

(C++ member), 170

(C++ class), 172

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__ocubt_ppuatr_aemv_tt_:p:abrlaem_:m:essthr_ipnrgovisione

(C++ member), 170

(C++ member), 172

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__ocubt_ppuatr_aemv_tt_:p:abrlaem_:m:e[sahn_opnryomvoiussi]one

(C++ member), 170

(C++ member), 172

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__rceba_dp_aoroabm__ptu:b:_bkleey__mceosmhp__ppraorvaimsione

(C++ class), 171

(C++ member), 172

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__rceba_dp_aoroabm__ptu:b:_bkleey__mceosmhp__ppraorvaims:i:oenrer

(C++ member), 171

(C++ class), 172

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__rceba_dp_aoroabm__ptu:b:_bkleey__meevsth__pparroavmisione

(C++ class), 171

(C++ member), 173

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__rceba_dp_aoroabm__ptu:b:_bkleey__meevsth__pparroavmi:s:iloinnek

(C++ member), 171

(C++ member), 173

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__rpercovv__ucnbp_rpoavr_aamd_vt_:p:kbtl_ep_amreasmh_proxy_clie

(C++ class), 171

(C++ class), 173

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__rpercovv__ucnbp_rpoavr_aamd_vt_:p:kbtl_ep_amreasmh:_:pardodxry_clie

(C++ member), 171

(C++ member), 173

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__rpercovv__ucnbp_rpoavr_aamd_vt_:p:kbtl_ep_amreasmh:_:pardodxry__tcylpiee

(C++ member), 171

(C++ member), 173

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__rpercovv__ucnbp_rpoavr_aamd_vt_:p:kbtl_ep_amreasmh:_:pardovx_yt_ycpleie

(C++ member), 171

(C++ member), 173

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__rpercovv__ucnbp_rpoavr_aamd_vt_:p:kbtl_ep_amreasmh:_:pbreoaxrye_rclie

(C++ member), 171

(C++ class), 173

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__rpercovv__ucnbp_rpoavr_aamd_vt_:p:kbtl_ep_amreasmh:_:pdreovx_yu_ucildie

(C++ member), 171

(C++ member), 173

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__rpercovv__ucnbp_rpoavr_aamd_vt_:p:kbtl_ep_amreasmh:_:poroobx_yi_ncfloie

(C++ member), 171

(C++ member), 173

Espressif Systems

2069

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pcroonvn_eccbt__pcaormapm__pta:r:abml:e:_emrers_hc_opdreoxy_clie

(C++ member), 173

(C++ member), 175

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pcroonvn_eccbt__pcaormapm__pta:r:abml:e:_nmeets_hi_dpxroxy_clie

(C++ member), 173

(C++ member), 175

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pcroonvn_eccbt_epda_rpaamr_atm::ble_mesh_proxy_clie

(C++ class), 173

(C++ member), 175

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pcroonvn_eccbt_epda_rpaamr_atm::::balded_rmesh_proxy_clie

(C++ member), 173

(C++ class), 175

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pcroonvn_eccbt_epda_rpaamr_atm::::balded_rm_etsyhp_eproxy_clie

(C++ member), 173

(C++ member), 175

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pcroonvn_eccbt_epda_rpaamr_atm::::bcloen_nm_ehsahn_dplreoxy_clie

(C++ member), 173

(C++ member), 175

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pcroonvn_eccbt_epda_rpaamr_atm::::bnleet__miedsxh_proxy_clie

(C++ member), 173

(C++ member), 175

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pdriosvc_ocnbn_epcatr_acmo_mtp:_:pbalrea_mmesh_proxy_gatt

(C++ class), 173

(C++ class), 175

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pdriosvc_ocnbn_epcatr_acmo_mtp:_:pbalrea_mm:e:scho_npnr_ohxayn_dglaett

(C++ member), 174

(C++ member), 175

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pdriosvc_ocnbn_epcatr_acmo_mtp:_:pbalrea_mm:e:sehr_rp_rcooxdye_gatt

(C++ member), 174

(C++ class), 175

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pdriosvc_ocnbn_epcatreadm__pta:r:abmle_mesh_proxy_gatt

(C++ class), 174

(C++ member), 175

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pdriosvc_ocnbn_epcatreadm__pta:r:abml:e:_amdedsrh_proxy_iden

(C++ member), 174

(C++ class), 175

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pdriosvc_ocnbn_epcatreadm__pta:r:abml:e:_amdedsrh__tpyrpoexy_iden

(C++ member), 174

(C++ member), 175

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pdriosvc_ocnbn_epcatreadm__pta:r:abml:e:_cmoensnh__hsaentd_lfeast_p

(C++ member), 174

(C++ class), 175

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pdriosvc_ocnbn_epcatreadm__pta:r:abml:e:_nmeets_hi_dsxet_fast_p

(C++ member), 174

(C++ member), 176

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pdriosvc_ocnbn_epcatreadm__pta:r:abml:e:_rmeeassho_nset_fast_p

(C++ member), 174

(C++ class), 176

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__prreocvv__cabd_vp_aprkatm__pta:r:abmle_mesh_set_fast_p

(C++ class), 174

(C++ member), 176

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__prreocvv__cabd_vp_aprkatm__pta:r:abml:e:_amdedsrh_set_fast_p

(C++ member), 174

(C++ member), 176

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__prreocvv__cabd_vp_aprkatm__pta:r:abml:e:_amdedsrh__tsyepte_fast_p

(C++ member), 174

(C++ member), 176

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__prreocvv__cabd_vp_aprkatm__pta:r:abml:e:_nmeets_hi_dset_oob_pu

(C++ member), 174

(C++ class), 176

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__prreocvv__cabd_vp_aprkatm__pta:r:abml:e:_nmeets_hi_dsxet_oob_pu

(C++ member), 174

(C++ member), 176

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__prreocvv__cabd_vp_aprkatm__pta:r:abml:e:_rmsessih_set_unprov

(C++ member), 174

(C++ class), 176

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__prreocvv__cfbi_lptaerra_ms_tta:t:ubsl_ep_amreasmh_set_unprov

(C++ class), 174

(C++ member), 176

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__prreocvv__cfbi_lptaerra_ms_tta:t:udse_ipnairta_mm:e:scho_ncno_mhpandl

(C++ member), 174

(C++ member), 162

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__prreocvv__cfbi_lptaerra_ms_tta:t:uesn_apbalream::filter_typ

(C++ member), 174

(C++ member), 160

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__prreocvv__cfbi_lptaerra_ms_tta:t:uesr_rp_acroadme::list_size

(C++ member), 175

(C++ member), 159

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__prreocvv__cfbi_lptaerra_ms_tta:t:uEsS_Pp_aBrLaEm_:M:EnSeHt__FiRdNxD_F

(C++ member), 174

(C++ enumerator), 162

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__prreocvv__cfbi_lptaerra_ms_tta:t:uEsS_Pp_aBrLaEm_:M:EsSeHr_vFeRrN_Da_dFd

(C++ member), 174

(C++ enumerator), 162

esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__prreomvo_vceb__fpialrtaemr__ta:d:dErS_Pc_oBmLpE__pMaErSaHm_FRND_F

(C++ class), 175

(C++ enumerator), 162

Espressif Systems

2070

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_mesh_prov_cb_param_t::ESP_BLE_MeEsSpH__bFlReN_Dm_eFsRhI_EpNrDoSvH_IcPb__TpEaRrMaImN_AtT:E:_nRoEdCeV__pFrRoNvD__oCuLtEpAuRt_nu

(C++ enumerator), 162

(C++ member), 158

esp_ble_mesh_prov_cb_param_t::ESP_BLE_MeEsSpH__bFlReN_Dm_eFsRhI_EpNrDoSvH_IcPb__TpEaRrMaImN_AtT:E:_nRoEdCeV__pFrRoNvD__oRuEtQput_st

(C++ enumerator), 162

(C++ member), 158

esp_ble_mesh_prov_cb_param_t::feature esp_ble_mesh_prov_cb_param_t::node_prov_reset

(C++ member), 160

(C++ member), 158

esp_ble_mesh_prov_cb_param_t::frnd_frieensdps_hbilpe__emsetsahb_lpirsohv_cb_param_t::node_prov_set_oob_p

(C++ member), 161

(C++ member), 158

esp_ble_mesh_prov_cb_param_t::frnd_frieensdps_hbilpe__tmeersmhi_npartoev_cb_param_t::node_proxy_gatt_dis

(C++ member), 161

(C++ member), 158

esp_ble_mesh_prov_cb_param_t::hb_dst esp_ble_mesh_prov_cb_param_t::node_proxy_gatt_ena

(C++ member), 160

(C++ member), 158

esp_ble_mesh_prov_cb_param_t::hb_src esp_ble_mesh_prov_cb_param_t::node_proxy_identity

(C++ member), 160

(C++ member), 158

esp_ble_mesh_prov_cb_param_t::heartbeate_smps_gb_lree_cmvesh_prov_cb_param_t::node_set_unprov_dev

(C++ member), 161

(C++ member), 157

esp_ble_mesh_prov_cb_param_t::hops

esp_ble_mesh_prov_cb_param_t::op (C++

(C++ member), 160

member), 160

esp_ble_mesh_prov_cb_param_t::index esp_ble_mesh_prov_cb_param_t::prov_register_comp

(C++ member), 160

(C++ member), 157

esp_ble_mesh_prov_cb_param_t::init_ttl esp_ble_mesh_prov_cb_param_t::provisioner_add_app

(C++ member), 160

(C++ member), 159

esp_ble_mesh_prov_cb_param_t::lpn_disabelsep__cbolmep_mesh_prov_cb_param_t::provisioner_add_net

(C++ member), 161

(C++ member), 159

esp_ble_mesh_prov_cb_param_t::lpn_enablees_pc_obmlpe_mesh_prov_cb_param_t::provisioner_add_unp

(C++ member), 161

(C++ member), 159

esp_ble_mesh_prov_cb_param_t::lpn_frienedssph_ibpl_ee_smteasbhl_ipsrhov_cb_param_t::provisioner_bind_ap

(C++ member), 161

(C++ member), 159

esp_ble_mesh_prov_cb_param_t::lpn_frienedssph_ibpl_et_emremsihn_aptreov_cb_param_t::provisioner_close_s

(C++ member), 161

(C++ member), 161

esp_ble_mesh_prov_cb_param_t::lpn_poll_ecsopm_pble_mesh_prov_cb_param_t::provisioner_close_s

(C++ member), 161

(C++ member), 161

esp_ble_mesh_prov_cb_param_t::model_sube_sgpr_obulpe__amdedsrh__cpormopv_cb_param_t::provisioner_delete_

(C++ member), 162

(C++ member), 159

esp_ble_mesh_prov_cb_param_t::model_unseusbp__gbrloeu_pm_easdhd_rp_rcoovm_pcb_param_t::provisioner_delete_

(C++ member), 162

(C++ member), 159

esp_ble_mesh_prov_cb_param_t::node_add_easppp__bkleey__mceosmhp_prov_cb_param_t::provisioner_delete_

(C++ member), 158

(C++ member), 159

esp_ble_mesh_prov_cb_param_t::node_add_ensept__bkleey__mceosmhp_prov_cb_param_t::provisioner_delete_

(C++ member), 158

(C++ member), 161

esp_ble_mesh_prov_cb_param_t::node_binde_sapp_pb_lkee_ym_etsoh__mpordoevl__ccbo_mpparam_t::provisioner_delete_

(C++ member), 158

(C++ member), 161

esp_ble_mesh_prov_cb_param_t::node_prove_scpo_mbpllee_tmeesh_prov_cb_param_t::provisioner_direct_

(C++ member), 158

(C++ member), 160

esp_ble_mesh_prov_cb_param_t::node_prove_sdpi_sbalbel_em_ecsohm_pprov_cb_param_t::provisioner_enable_

(C++ member), 157

(C++ member), 160

esp_ble_mesh_prov_cb_param_t::node_prove_sepn_abbllee__mceosmhp_prov_cb_param_t::provisioner_open_se

(C++ member), 157

(C++ member), 160

esp_ble_mesh_prov_cb_param_t::node_prove_sipn_pbulte_mesh_prov_cb_param_t::provisioner_open_se

(C++ member), 158

(C++ member), 161

esp_ble_mesh_prov_cb_param_t::node_prove_sipn_pbulte__nmuems_hc_opmrpov_cb_param_t::provisioner_prov_co

(C++ member), 158

(C++ member), 158

esp_ble_mesh_prov_cb_param_t::node_prove_sipn_pbulte__smters_hc_opmrpov_cb_param_t::provisioner_prov_de

(C++ member), 158

(C++ member), 159

esp_ble_mesh_prov_cb_param_t::node_prove_slpi_nbkl_ec_lmoesseh_prov_cb_param_t::provisioner_prov_di

(C++ member), 157

(C++ member), 158

esp_ble_mesh_prov_cb_param_t::node_prove_slpi_nbkl_eo_pmeensh_prov_cb_param_t::provisioner_prov_en

(C++ member), 157

(C++ member), 158

Espressif Systems

2071

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_mesh_prov_cb_param_t::provisioneesrp__pbrloev__miensphu_tprov_cb_param_t::rssi

(C++ member), 158

(C++ member), 160

esp_ble_mesh_prov_cb_param_t::provisioneesrp__pbrloev__miensphu_tp_rnouvm__ccbo_mpparam_t::rx_ttl

(C++ member), 159

(C++ member), 160

esp_ble_mesh_prov_cb_param_t::provisioneesrp__pbrloev__miensphu_tp_rsotvr__ccbo_mpparam_t::set_fast_prov_actio

(C++ member), 159

(C++ member), 161

esp_ble_mesh_prov_cb_param_t::provisioneesrp__pbrloev__mleisnhk__pcrloovs_ecb_param_t::set_fast_prov_info_

(C++ member), 158

(C++ member), 161

esp_ble_mesh_prov_cb_param_t::provisioneesrp__pbrloev__mleisnhk__porpoevn_cb_param_t::type

(C++ member), 158

(C++ member), 160

esp_ble_mesh_prov_cb_param_t::provisioneesrp__pbrloev__moeusthp_uptrov_cb_param_t::uid

(C++ member), 158

(C++ member), 161

esp_ble_mesh_prov_cb_param_t::provisioneesrp__pbrloev__mreesahd__poroobv__pcubb__pkaeryam_t::[anonymous]

(C++ member), 158

(C++ enum), 162

esp_ble_mesh_prov_cb_param_t::provisioneesrp__pbrloev__mreesahd__poroobv__pcubb__tk(eCy+_+cotymppe), 225

(C++ member), 159

esp_ble_mesh_prov_data_info_t (C++

esp_ble_mesh_prov_cb_param_t::provisioner_recvcl_ahsse),a1r8t4beat

(C++ member), 160

esp_ble_mesh_prov_data_info_t::flag

esp_ble_mesh_prov_cb_param_t::provisioner_recv(C_+u+npmreomvb_ear)d, v18_4pkt

(C++ member), 158

esp_ble_mesh_prov_data_info_t::flags

esp_ble_mesh_prov_cb_param_t::provisioner_set_(Cd+e+v_mueumibde_r)m, a18t4ch_comp

(C++ member), 159

esp_ble_mesh_prov_data_info_t::iv_index

esp_ble_mesh_prov_cb_param_t::provisioner_set_(Ch+e+armtebmebaetr)_, f18i4lter_info_comp

(C++ member), 160

esp_ble_mesh_prov_data_info_t::net_idx

esp_ble_mesh_prov_cb_param_t::provisioner_set_(Ch+e+armtebmebaetr)_, f18i4lter_type_comp

(C++ member), 160

ESP_BLE_MESH_PROV_EVT_MAX (C++ enumera-

esp_ble_mesh_prov_cb_param_t::provisioner_set_tonro),d2e0_9name_comp

(C++ member), 159

ESP_BLE_MESH_PROV_GATT (C++ enumerator),

esp_ble_mesh_prov_cb_param_t::provisioner_set_2p04rimary_elem_addr_comp

(C++ member), 159

ESP_BLE_MESH_PROV_INPUT_OOB_MAX_LEN (C

esp_ble_mesh_prov_cb_param_t::provisioner_set_mparcroov),_1d9a0ta_info_comp

(C++ member), 159

ESP_BLE_MESH_PROV_OOB_2D_CODE (C++ enu-

esp_ble_mesh_prov_cb_param_t::provisioner_set_msetraatotri),c2_0o4ob_val_comp

(C++ member), 159

ESP_BLE_MESH_PROV_OOB_BAR_CODE (C++

esp_ble_mesh_prov_cb_param_t::provisioner_storeneu_mneordateo_r)c, o20m4p_data_comp

(C++ member), 159

ESP_BLE_MESH_PROV_OOB_IN_BOX (C++ enu-

esp_ble_mesh_prov_cb_param_t::provisioner_updamteera_toarp),p2_0k5ey_comp

(C++ member), 159

ESP_BLE_MESH_PROV_OOB_IN_MANUAL (C++

esp_ble_mesh_prov_cb_param_t::provisioner_updaentuem_enreatto_r)k, e20y5_comp

(C++ member), 159

esp_ble_mesh_prov_oob_info_t (C++ enum),

esp_ble_mesh_prov_cb_param_t::proxy_client_add2_04filter_addr_comp

(C++ member), 162

ESP_BLE_MESH_PROV_OOB_NFC (C++ enumera-

esp_ble_mesh_prov_cb_param_t::proxy_client_contonre),c2t0_5comp

(C++ member), 161

ESP_BLE_MESH_PROV_OOB_NUMBER (C++ enu-

esp_ble_mesh_prov_cb_param_t::proxy_client_conmneeractotre),d205

(C++ member), 161

ESP_BLE_MESH_PROV_OOB_ON_BOX (C++ enu-

esp_ble_mesh_prov_cb_param_t::proxy_client_dismceorantonre),c2t0_5comp

(C++ member), 162

ESP_BLE_MESH_PROV_OOB_ON_DEV (C++ enu-

esp_ble_mesh_prov_cb_param_t::proxy_client_dismceorantonre),c2t0e5d

(C++ member), 161

ESP_BLE_MESH_PROV_OOB_ON_PAPER (C++

esp_ble_mesh_prov_cb_param_t::proxy_client_recenvu_maedrvat_opr)k, t205

(C++ member), 161

ESP_BLE_MESH_PROV_OOB_OTHER (C++ enumer-

esp_ble_mesh_prov_cb_param_t::proxy_client_recavto_r)f, i2l04ter_status

(C++ member), 161

ESP_BLE_MESH_PROV_OOB_STRING (C++ enu-

esp_ble_mesh_prov_cb_param_t::proxy_client_remmoevraeto_rf),i2l0t5er_addr_comp

(C++ member), 162

ESP_BLE_MESH_PROV_OOB_URI (C++ enumera-

esp_ble_mesh_prov_cb_param_t::proxy_client_setto_rf),i2l0t4er_type_comp

(C++ member), 162

ESP_BLE_MESH_PROV_OUTPUT_OOB_MAX_LEN

Espressif Systems

2072

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C macro), 190

esp_ble_mesh_provisioner_get_local_app_key

ESP_BLE_MESH_PROV_REGISTER_COMP_EVT

(C++ function), 217

(C++ enumerator), 205

esp_ble_mesh_provisioner_get_local_net_key

ESP_BLE_MESH_PROV_STATIC_OOB_MAX_LEN

(C++ function), 218

(C macro), 190

esp_ble_mesh_provisioner_get_node_index

esp_ble_mesh_prov_t (C++ class), 183

(C++ function), 216

esp_ble_mesh_provisioner_add_local_app_eksepy_ble_mesh_provisioner_get_node_name

(C++ function), 217

(C++ function), 216

ESP_BLE_MESH_PROVISIONER_ADD_LOCAL_APP_eKsEpY__bClOeM_Pm_eEsVhT_provisioner_get_node_table_entry

(C++ enumerator), 207

(C++ function), 216

esp_ble_mesh_provisioner_add_local_net_eksepy_ble_mesh_provisioner_get_node_with_addr

(C++ function), 218

(C++ function), 216

ESP_BLE_MESH_PROVISIONER_ADD_LOCAL_NET_eKsEpY__bClOeM_Pm_eEsVhT_provisioner_get_node_with_name

(C++ enumerator), 207

(C++ function), 216

esp_ble_mesh_provisioner_add_unprov_devesp_ble_mesh_provisioner_get_node_with_uuid

(C++ function), 222

(C++ function), 216

ESP_BLE_MESH_PROVISIONER_ADD_UNPROV_DEVe_sCpO_MbPl_eE_VmTesh_provisioner_get_prov_node_count

(C++ enumerator), 206

(C++ function), 216

esp_ble_mesh_provisioner_bind_app_key_teos_pl_obclael__mmeosdhe_lprovisioner_get_settings_index

(C++ function), 217

(C++ function), 220

ESP_BLE_MESH_PROVISIONER_BIND_APP_KEY_TeOs_pM_ObDlEeL__mCeOsMhP__pErVoTvisioner_get_settings_uid

(C++ enumerator), 207

(C++ function), 220

esp_ble_mesh_provisioner_close_settingse_swpi_tbhl_ei_nmdeesxh_provisioner_input_number

(C++ function), 219

(C++ function), 222

ESP_BLE_MESH_PROVISIONER_CLOSE_SETTINGSe_sWpI_TbHl_eI_NmDeEsXh__CpOrMoPv_iEsViToner_input_string

(C++ enumerator), 208

(C++ function), 222

esp_ble_mesh_provisioner_close_settingse_swpi_tbhl_eu_imdesh_provisioner_open_settings_with_index

(C++ function), 219

(C++ function), 219

ESP_BLE_MESH_PROVISIONER_CLOSE_SETTINGSE_SWPI_TBHL_EU_IMDE_SCHO_MPPR_OEVVITSIONER_OPEN_SETTINGS_WITH_INDEX

(C++ enumerator), 208

(C++ enumerator), 207

esp_ble_mesh_provisioner_delete_dev esp_ble_mesh_provisioner_open_settings_with_uid

(C++ function), 224

(C++ function), 219

ESP_BLE_MESH_PROVISIONER_DELETE_DEV_COMEPS_PE_VBTLE_MESH_PROVISIONER_OPEN_SETTINGS_WITH_UID_C

(C++ enumerator), 207

(C++ enumerator), 208

esp_ble_mesh_provisioner_delete_node_wiEtShP__aBdLdEr_MESH_PROVISIONER_PROV_COMPLETE_EVT

(C++ function), 217

(C++ enumerator), 206

ESP_BLE_MESH_PROVISIONER_DELETE_NODE_WIETSHP__ABDLDER__MCEOSMHP__PERVOTVISIONER_PROV_DEV_WITH_ADDR_COMP_

(C++ enumerator), 207

(C++ enumerator), 206

esp_ble_mesh_provisioner_delete_node_wietshp__ubulied_mesh_provisioner_prov_device_with_addr

(C++ function), 217

(C++ function), 223

ESP_BLE_MESH_PROVISIONER_DELETE_NODE_WIeTsHp__UbUlIeD__mCeOsMhP__pErVoTvisioner_prov_disable

(C++ enumerator), 207

(C++ function), 222

esp_ble_mesh_provisioner_delete_settingEsS_Pw_iBtLhE__iMnEdSeHx_PROVISIONER_PROV_DISABLE_COMP_EVT

(C++ function), 220

(C++ enumerator), 206

ESP_BLE_MESH_PROVISIONER_DELETE_SETTINGeSs_pW_IbTlHe__ImNeDsEhX__pCrOoMvPi_sEiVoTner_prov_enable

(C++ enumerator), 208

(C++ function), 222

esp_ble_mesh_provisioner_delete_settingEsS_Pw_iBtLhE__uMiEdSH_PROVISIONER_PROV_ENABLE_COMP_EVT

(C++ function), 220

(C++ enumerator), 206

ESP_BLE_MESH_PROVISIONER_DELETE_SETTINGESS_PW_IBTLHE__UMIEDS_HC_OPMRPO_VEIVSTIONER_PROV_INPUT_EVT

(C++ enumerator), 208

(C++ enumerator), 206

esp_ble_mesh_provisioner_direct_erase_sEeStPt_iBnLgEs_MESH_PROVISIONER_PROV_INPUT_NUMBER_COMP_E

(C++ function), 219

(C++ enumerator), 207

ESP_BLE_MESH_PROVISIONER_DRIECT_ERASE_SEESTPT_IBNLGES__MCEOSMHP__PERVOTVISIONER_PROV_INPUT_STRING_COMP_E

(C++ enumerator), 207

(C++ enumerator), 207

ESP_BLE_MESH_PROVISIONER_ENABLE_HEARTBEEASTP__RBELCEV__MCEOSMHP__PERVOTVISIONER_PROV_LINK_CLOSE_EVT

(C++ enumerator), 207

(C++ enumerator), 206

esp_ble_mesh_provisioner_get_free_settiEnSgPs__BcLoEu_nMtESH_PROVISIONER_PROV_LINK_OPEN_EVT

(C++ function), 220

(C++ enumerator), 206

Espressif Systems

2073

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

ESP_BLE_MESH_PROVISIONER_PROV_OUTPUT_EVeTsp_ble_mesh_proxy_client_connect

(C++ enumerator), 206

(C++ function), 226

ESP_BLE_MESH_PROVISIONER_PROV_READ_OOB_EPSUPB__BKLEEY__MCEOSMHP__PERVOTXY_CLIENT_CONNECT_COMP_EVT

(C++ enumerator), 207

(C++ enumerator), 208

ESP_BLE_MESH_PROVISIONER_PROV_READ_OOB_EPSUPB__BKLEEY__MEEVSTH_PROXY_CLIENT_CONNECTED_EVT

(C++ enumerator), 206

(C++ enumerator), 208

esp_ble_mesh_provisioner_read_oob_pub_keesyp_ble_mesh_proxy_client_disconnect

(C++ function), 222

(C++ function), 226

esp_ble_mesh_provisioner_recv_heartbeatESP_BLE_MESH_PROXY_CLIENT_DISCONNECT_COMP_EVT

(C++ function), 218

(C++ enumerator), 208

ESP_BLE_MESH_PROVISIONER_RECV_HEARTBEATE_SMPE_SBSLAEG_EM_EESVHT_PROXY_CLIENT_DISCONNECTED_EVT

(C++ enumerator), 207

(C++ enumerator), 208

ESP_BLE_MESH_PROVISIONER_RECV_UNPROV_ADEVS_PP_KBTL_EE_VMTESH_PROXY_CLIENT_RECV_ADV_PKT_EVT

(C++ enumerator), 206

(C++ enumerator), 208

esp_ble_mesh_provisioner_set_dev_uuid_mEaStPc_hBLE_MESH_PROXY_CLIENT_RECV_FILTER_STATUS_EVT

(C++ function), 224

(C++ enumerator), 208

ESP_BLE_MESH_PROVISIONER_SET_DEV_UUID_MeAsTpC_Hb_lCeO_MmPe_sEhV_Tproxy_client_remove_filter_addr

(C++ enumerator), 207

(C++ function), 226

esp_ble_mesh_provisioner_set_heartbeat_EfSiPl_tBeLrE__iMnEfSoH_PROXY_CLIENT_REMOVE_FILTER_ADDR_COMP

(C++ function), 218

(C++ enumerator), 209

ESP_BLE_MESH_PROVISIONER_SET_HEARTBEAT_eFsIpL_TbElRe__ImNeFsOh__CpOrMoPx_yE_VcTlient_set_filter_type

(C++ enumerator), 207

(C++ function), 226

esp_ble_mesh_provisioner_set_heartbeat_EfSiPl_tBeLrE__tMyEpSeH_PROXY_CLIENT_SET_FILTER_TYPE_COMP_EV

(C++ function), 218

(C++ enumerator), 208

ESP_BLE_MESH_PROVISIONER_SET_HEARTBEAT_eFsIpL_TbElRe__TmYePsEh__CpOrMoPx_yE_VfTilter_type_t (C++

(C++ enumerator), 207

enum), 205

esp_ble_mesh_provisioner_set_node_name esp_ble_mesh_proxy_gatt_disable (C++

(C++ function), 215

function), 226

ESP_BLE_MESH_PROVISIONER_SET_NODE_NAME_eCsOpM_Pb_lEeV_Tmesh_proxy_gatt_enable (C++

(C++ enumerator), 207

function), 226

esp_ble_mesh_provisioner_set_primary_eleesmp__abdlder_mesh_proxy_identity_enable

(C++ function), 224

(C++ function), 225

ESP_BLE_MESH_PROVISIONER_SET_PRIMARY_ELEESMP__ABDLDER__MCEOSMHP__PEUVBTLISH_TRANSMIT (C macro),

(C++ enumerator), 207

190

esp_ble_mesh_provisioner_set_prov_data_EiSnPf_oBLE_MESH_PUSH (C++ enumerator), 204

(C++ function), 224

esp_ble_mesh_register_config_client_callback

ESP_BLE_MESH_PROVISIONER_SET_PROV_DATA_INFO_CO(CM+P+_EfVunTction), 227

(C++ enumerator), 207

esp_ble_mesh_register_config_server_callback

esp_ble_mesh_provisioner_set_static_oob_value (C++ function), 227

(C++ function), 224

esp_ble_mesh_register_custom_model_callback

ESP_BLE_MESH_PROVISIONER_SET_STATIC_OOB_VALUE_(CC+O+MPf_unEcVtiTon), 213

(C++ enumerator), 207

esp_ble_mesh_register_generic_client_callback

esp_ble_mesh_provisioner_store_node_comp_data (C++ function), 259

(C++ function), 216

esp_ble_mesh_register_generic_server_callback

ESP_BLE_MESH_PROVISIONER_STORE_NODE_COMP_DATA_(CC+O+MPf_unEcVtiTon), 260

(C++ enumerator), 207

esp_ble_mesh_register_health_client_callback

esp_ble_mesh_provisioner_update_local_app_key (C++ function), 251

(C++ function), 217

esp_ble_mesh_register_health_server_callback

ESP_BLE_MESH_PROVISIONER_UPDATE_LOCAL_APP_KEY_(CC+O+MPf_unEcVtiTon), 251

(C++ enumerator), 207

esp_ble_mesh_register_light_client_callback

esp_ble_mesh_provisioner_update_local_net_key (C++ function), 327

(C++ function), 218

esp_ble_mesh_register_lighting_server_callback

ESP_BLE_MESH_PROVISIONER_UPDATE_LOCAL_NET_KEY_(CC+O+MPf_unEcVtiTon), 327

(C++ enumerator), 207

esp_ble_mesh_register_prov_callback

esp_ble_mesh_proxy_client_add_filter_addr

(C++ function), 221

(C++ function), 226

esp_ble_mesh_register_sensor_client_callback

ESP_BLE_MESH_PROXY_CLIENT_ADD_FILTER_ADDR_COMP(C_+E+VTfunction), 290

(C++ enumerator), 208

esp_ble_mesh_register_sensor_server_callback

Espressif Systems

2074

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ function), 290

esp_ble_mesh_scene_register_t::scene_number

esp_ble_mesh_register_time_scene_client_callba(Cc+k+ member), 315

(C++ function), 305

esp_ble_mesh_scene_register_t::scene_type

esp_ble_mesh_register_time_scene_server_callba(Cc+k+ member), 315

(C++ function), 306

esp_ble_mesh_scene_register_t::scene_value

ESP_BLE_MESH_RELAY_DISABLED (C macro),

(C++ member), 315

188

esp_ble_mesh_scene_setup_srv_t (C++

ESP_BLE_MESH_RELAY_ENABLED (C macro), 189

class), 316

ESP_BLE_MESH_RELAY_NOT_SUPPORTED (C esp_ble_mesh_scene_setup_srv_t::model

macro), 189

(C++ member), 316

ESP_BLE_MESH_SAMPLE_FUNC_ACCUMULATED esp_ble_mesh_scene_setup_srv_t::rsp_ctrl

(C++ enumerator), 305

(C++ member), 316

ESP_BLE_MESH_SAMPLE_FUNC_ARITHMETIC_MEAeNsp_ble_mesh_scene_setup_srv_t::state

(C++ enumerator), 305

(C++ member), 316

ESP_BLE_MESH_SAMPLE_FUNC_COUNT (C++ esp_ble_mesh_scene_srv_t (C++ class), 316

enumerator), 305

esp_ble_mesh_scene_srv_t::last (C++

ESP_BLE_MESH_SAMPLE_FUNC_INSTANTANEOUS

member), 316

(C++ enumerator), 305

esp_ble_mesh_scene_srv_t::model (C++

ESP_BLE_MESH_SAMPLE_FUNC_MAXIMUM (C++

member), 316

enumerator), 305

esp_ble_mesh_scene_srv_t::rsp_ctrl

ESP_BLE_MESH_SAMPLE_FUNC_MINIMUM (C++

(C++ member), 316

enumerator), 305

esp_ble_mesh_scene_srv_t::state (C++

ESP_BLE_MESH_SAMPLE_FUNC_RMS (C++ enu-

member), 316

merator), 305

esp_ble_mesh_scene_srv_t::transition

ESP_BLE_MESH_SAMPLE_FUNC_UNSPECIFIED

(C++ member), 316

(C++ enumerator), 305

esp_ble_mesh_scene_status_cb_t (C++

esp_ble_mesh_scene_delete_t (C++ class),

class), 312

310

esp_ble_mesh_scene_status_cb_t::current_scene

esp_ble_mesh_scene_delete_t::scene_number (C++ member), 312

(C++ member), 310

esp_ble_mesh_scene_status_cb_t::op_en

ESP_BLE_MESH_SCENE_NOT_FOUND (C macro),

(C++ member), 312

326

esp_ble_mesh_scene_status_cb_t::remain_time

ESP_BLE_MESH_SCENE_NUMBER_LEN (C macro),

(C++ member), 312

324

esp_ble_mesh_scene_status_cb_t::status_code

esp_ble_mesh_scene_recall_t (C++ class),

(C++ member), 312

310

esp_ble_mesh_scene_status_cb_t::target_scene

esp_ble_mesh_scene_recall_t::delay

(C++ member), 312

(C++ member), 310

esp_ble_mesh_scene_store_t (C++ class),

esp_ble_mesh_scene_recall_t::op_en

309

(C++ member), 310

esp_ble_mesh_scene_store_t::scene_number

esp_ble_mesh_scene_recall_t::scene_number

(C++ member), 310

(C++ member), 310

ESP_BLE_MESH_SCENE_SUCCESS (C macro), 325

esp_ble_mesh_scene_recall_t::tid (C++ esp_ble_mesh_scenes_state_t (C++ class),

member), 310

315

esp_ble_mesh_scene_recall_t::trans_timeesp_ble_mesh_scenes_state_t::current_scene

(C++ member), 310

(C++ member), 315

ESP_BLE_MESH_SCENE_REG_FULL (C macro), esp_ble_mesh_scenes_state_t::in_progress

325

(C++ member), 316

esp_ble_mesh_scene_register_status_cb_tesp_ble_mesh_scenes_state_t::scene_count

(C++ class), 312

(C++ member), 315

esp_ble_mesh_scene_register_status_cb_te:s:pc_ubrlree_nmte_sshc_esnceenes_state_t::scenes

(C++ member), 312

(C++ member), 315

esp_ble_mesh_scene_register_status_cb_te:s:ps_cbelnee_smesh_scenes_state_t::status_code

(C++ member), 312

(C++ member), 316

esp_ble_mesh_scene_register_status_cb_te:s:ps_tbalteu_sm_ecsohd_escenes_state_t::target_scene

(C++ member), 312

(C++ member), 315

esp_ble_mesh_scene_register_t (C++ ESP_BLE_MESH_SCHEDULE_ACT_NO_ACTION (C

class), 314

macro), 325

Espressif Systems

2075

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

ESP_BLE_MESH_SCHEDULE_ACT_SCENE_RECALL esp_ble_mesh_scheduler_act_get_t (C++

(C macro), 325

class), 310

ESP_BLE_MESH_SCHEDULE_ACT_TURN_OFF (C esp_ble_mesh_scheduler_act_get_t::index

macro), 325

(C++ member), 310

ESP_BLE_MESH_SCHEDULE_ACT_TURN_ON (C esp_ble_mesh_scheduler_act_set_t (C++

macro), 325

class), 310

ESP_BLE_MESH_SCHEDULE_DAY_ANY_DAY (C esp_ble_mesh_scheduler_act_set_t::action

macro), 325

(C++ member), 311

ESP_BLE_MESH_SCHEDULE_ENTRY_MAX_INDEX esp_ble_mesh_scheduler_act_set_t::day

(C macro), 325

(C++ member), 310

ESP_BLE_MESH_SCHEDULE_HOUR_ANY_HOUR (C esp_ble_mesh_scheduler_act_set_t::day_of_week

macro), 325

(C++ member), 311

ESP_BLE_MESH_SCHEDULE_HOUR_ONCE_A_DAY esp_ble_mesh_scheduler_act_set_t::hour

(C macro), 325

(C++ member), 310

esp_ble_mesh_schedule_register_t (C++ esp_ble_mesh_scheduler_act_set_t::index

class), 316

(C++ member), 310

esp_ble_mesh_schedule_register_t::actioensp_ble_mesh_scheduler_act_set_t::minute

(C++ member), 317

(C++ member), 310

esp_ble_mesh_schedule_register_t::day esp_ble_mesh_scheduler_act_set_t::month

(C++ member), 316

(C++ member), 310

esp_ble_mesh_schedule_register_t::day_oefs_pw_ebelke_mesh_scheduler_act_set_t::scene_number

(C++ member), 317

(C++ member), 311

esp_ble_mesh_schedule_register_t::hour esp_ble_mesh_scheduler_act_set_t::second

(C++ member), 316

(C++ member), 311

esp_ble_mesh_schedule_register_t::in_useesp_ble_mesh_scheduler_act_set_t::trans_time

(C++ member), 316

(C++ member), 311

esp_ble_mesh_schedule_register_t::minuteesp_ble_mesh_scheduler_act_set_t::year

(C++ member), 316

(C++ member), 310

esp_ble_mesh_schedule_register_t::monthesp_ble_mesh_scheduler_act_status_cb_t

(C++ member), 316

(C++ class), 312

esp_ble_mesh_schedule_register_t::scenee_snpu_mbbleer_mesh_scheduler_act_status_cb_t::action

(C++ member), 317

(C++ member), 313

esp_ble_mesh_schedule_register_t::seconedsp_ble_mesh_scheduler_act_status_cb_t::day

(C++ member), 317

(C++ member), 313

esp_ble_mesh_schedule_register_t::transe_stpi_mbele_mesh_scheduler_act_status_cb_t::day_of_we

(C++ member), 317

(C++ member), 313

esp_ble_mesh_schedule_register_t::year esp_ble_mesh_scheduler_act_status_cb_t::hour

(C++ member), 316

(C++ member), 313

ESP_BLE_MESH_SCHEDULE_SCENE_NO_SCENE esp_ble_mesh_scheduler_act_status_cb_t::index

(C macro), 325

(C++ member), 313

ESP_BLE_MESH_SCHEDULE_SEC_ANY_OF_HOUR esp_ble_mesh_scheduler_act_status_cb_t::minute

(C macro), 325

(C++ member), 313

ESP_BLE_MESH_SCHEDULE_SEC_ANY_OF_MIN esp_ble_mesh_scheduler_act_status_cb_t::month

(C macro), 325

(C++ member), 313

ESP_BLE_MESH_SCHEDULE_SEC_EVERY_15_MIN esp_ble_mesh_scheduler_act_status_cb_t::scene_num

(C macro), 325

(C++ member), 313

ESP_BLE_MESH_SCHEDULE_SEC_EVERY_15_SEC esp_ble_mesh_scheduler_act_status_cb_t::second

(C macro), 325

(C++ member), 313

ESP_BLE_MESH_SCHEDULE_SEC_EVERY_20_MIN esp_ble_mesh_scheduler_act_status_cb_t::trans_tim

(C macro), 325

(C++ member), 313

ESP_BLE_MESH_SCHEDULE_SEC_EVERY_20_SEC esp_ble_mesh_scheduler_act_status_cb_t::year

(C macro), 325

(C++ member), 313

ESP_BLE_MESH_SCHEDULE_SEC_ONCE_AN_HOUR esp_ble_mesh_scheduler_setup_srv_t

(C macro), 325

(C++ class), 317

ESP_BLE_MESH_SCHEDULE_SEC_ONCE_AN_MIN esp_ble_mesh_scheduler_setup_srv_t::model

(C macro), 325

(C++ member), 317

ESP_BLE_MESH_SCHEDULE_YEAR_ANY_YEAR (C esp_ble_mesh_scheduler_setup_srv_t::rsp_ctrl

macro), 325

(C++ member), 317

Espressif Systems

2076

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_mesh_scheduler_setup_srv_t::state (C++ member), 297

(C++ member), 317

esp_ble_mesh_sensor_cadence_t::min_interval

esp_ble_mesh_scheduler_srv_t (C++ class),

(C++ member), 297

317

esp_ble_mesh_sensor_cadence_t::period_divisor

esp_ble_mesh_scheduler_srv_t::model

(C++ member), 297

(C++ member), 317

esp_ble_mesh_sensor_cadence_t::trigger_delta_down

esp_ble_mesh_scheduler_srv_t::rsp_ctrl

(C++ member), 297

(C++ member), 317

esp_ble_mesh_sensor_cadence_t::trigger_delta_up

esp_ble_mesh_scheduler_srv_t::state

(C++ member), 297

(C++ member), 317

esp_ble_mesh_sensor_cadence_t::trigger_type

esp_ble_mesh_scheduler_state_t (C++

(C++ member), 297

class), 317

esp_ble_mesh_sensor_client_cb_event_t

esp_ble_mesh_scheduler_state_t::schedule_count(C++ enum), 304

(C++ member), 317

esp_ble_mesh_sensor_client_cb_param_t

esp_ble_mesh_scheduler_state_t::schedules

(C++ class), 296

(C++ member), 317

esp_ble_mesh_sensor_client_cb_param_t::error_code

esp_ble_mesh_scheduler_status_cb_t

(C++ member), 296

(C++ class), 312

esp_ble_mesh_sensor_client_cb_param_t::params

esp_ble_mesh_scheduler_status_cb_t::schedules (C++ member), 296

(C++ member), 312

esp_ble_mesh_sensor_client_cb_param_t::status_cb

ESP_BLE_MESH_SDU_MAX_LEN (C macro), 188

(C++ member), 296

ESP_BLE_MESH_SELF_TEST_ERROR (C macro), esp_ble_mesh_sensor_client_cb_t (C++

258

type), 304

ESP_BLE_MESH_SELF_TEST_WARNING

(C ESP_BLE_MESH_SENSOR_CLIENT_EVT_MAX

macro), 258

(C++ enumerator), 304

esp_ble_mesh_sensor_cadence_get_t

esp_ble_mesh_sensor_client_get_state

(C++ class), 293

(C++ function), 290

esp_ble_mesh_sensor_cadence_get_t::propEeSrPt_yB_LiEd_MESH_SENSOR_CLIENT_GET_STATE_EVT

(C++ member), 293

(C++ enumerator), 304

esp_ble_mesh_sensor_cadence_set_t

esp_ble_mesh_sensor_client_get_state_t

(C++ class), 293

(C++ union), 291

esp_ble_mesh_sensor_cadence_set_t::faste_scpa_dbelnec_em_ehsihg_hsensor_client_get_state_t::cadence_g

(C++ member), 293

(C++ member), 291

esp_ble_mesh_sensor_cadence_set_t::faste_scpa_dbelnec_em_elsohw_sensor_client_get_state_t::column_ge

(C++ member), 293

(C++ member), 291

esp_ble_mesh_sensor_cadence_set_t::faste_scpa_dbelnec_em_epsehr_isoedn_sdoirv_icsloirent_get_state_t::descripto

(C++ member), 293

(C++ member), 291

esp_ble_mesh_sensor_cadence_set_t::propeesrpt_yb_lied_mesh_sensor_client_get_state_t::sensor_ge

(C++ member), 293

(C++ member), 291

esp_ble_mesh_sensor_cadence_set_t::stateussp__mbilne__imnetsehr_vsaelnsor_client_get_state_t::series_ge

(C++ member), 293

(C++ member), 291

esp_ble_mesh_sensor_cadence_set_t::stateussp__tbrlieg_gmeers_hd_esletnas_odro_wcnlient_get_state_t::setting_g

(C++ member), 293

(C++ member), 291

esp_ble_mesh_sensor_cadence_set_t::stateussp__tbrlieg_gmeers_hd_esletnas_ourp_client_get_state_t::settings_

(C++ member), 293

(C++ member), 291

esp_ble_mesh_sensor_cadence_set_t::statEuSsP__tBrLiEg_gMeErS_Ht_ySpEeNSOR_CLIENT_PUBLISH_EVT

(C++ member), 293

(C++ enumerator), 304

esp_ble_mesh_sensor_cadence_status_cb_tesp_ble_mesh_sensor_client_set_state

(C++ class), 295

(C++ function), 290

esp_ble_mesh_sensor_cadence_status_cb_tE:S:Pp_rBoLpEe_rMtEyS_Hi_dSENSOR_CLIENT_SET_STATE_EVT

(C++ member), 295

(C++ enumerator), 304

esp_ble_mesh_sensor_cadence_status_cb_te:s:ps_ebnlseo_rm_ecsahd_esnecnes_ovra_lculeient_set_state_t

(C++ member), 295

(C++ union), 291

esp_ble_mesh_sensor_cadence_t (C++ esp_ble_mesh_sensor_client_set_state_t::cadence_s

class), 297

(C++ member), 291

esp_ble_mesh_sensor_cadence_t::fast_cadeesnpc_eb_lhei_gmhesh_sensor_client_set_state_t::setting_s

(C++ member), 297

(C++ member), 291

esp_ble_mesh_sensor_cadence_t::fast_cadeesnpc_eb_lleo_wmesh_sensor_client_status_cb_t

Espressif Systems

2077

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ union), 291

macro), 302

esp_ble_mesh_sensor_client_status_cb_t:e:scpa_dbelnec_em_esstha_tsuesnsor_descriptor_status_cb_t

(C++ member), 291

(C++ class), 295

esp_ble_mesh_sensor_client_status_cb_t:e:scpo_lbulmen__msetsaht_ussensor_descriptor_status_cb_t::descr

(C++ member), 292

(C++ member), 295

esp_ble_mesh_sensor_client_status_cb_t:e:sdpe_sbclrei_pmteosrh__ssteantsuosr_descriptor_t (C++

(C++ member), 291

class), 296

esp_ble_mesh_sensor_client_status_cb_t:e:sspe_nbsloer__msetsaht_ussensor_descriptor_t::measure_period

(C++ member), 292

(C++ member), 297

esp_ble_mesh_sensor_client_status_cb_t:e:sspe_rbilees__msetsaht_ussensor_descriptor_t::negative_tolera

(C++ member), 292

(C++ member), 296

esp_ble_mesh_sensor_client_status_cb_t:e:sspe_tbtlien_gm_esstha_tsuesnsor_descriptor_t::positive_tolera

(C++ member), 291

(C++ member), 296

esp_ble_mesh_sensor_client_status_cb_t:e:sspe_tbtlien_gmse_ssht_asteunssor_descriptor_t::sampling_functi

(C++ member), 291

(C++ member), 297

ESP_BLE_MESH_SENSOR_CLIENT_TIMEOUT_EVT esp_ble_mesh_sensor_descriptor_t::update_interval

(C++ enumerator), 304

(C++ member), 297

esp_ble_mesh_sensor_column_get_t (C++ ESP_BLE_MESH_SENSOR_DIVISOR_TRIGGER_TYPE_LEN

class), 294

(C macro), 303

esp_ble_mesh_sensor_column_get_t::propeerstpy__bilde_mesh_sensor_get_t (C++ class), 294

(C++ member), 294

esp_ble_mesh_sensor_get_t::op_en (C++

esp_ble_mesh_sensor_column_get_t::raw_value_x member), 294

(C++ member), 294

esp_ble_mesh_sensor_get_t::property_id

esp_ble_mesh_sensor_column_status_cb_t

(C++ member), 294

(C++ class), 296

esp_ble_mesh_sensor_message_opcode_t

esp_ble_mesh_sensor_column_status_cb_t::proper(Ct+y+_itydpe), 203

(C++ member), 296

ESP_BLE_MESH_SENSOR_NOT_APPL_MEASURE_PERIOD

esp_ble_mesh_sensor_column_status_cb_t::sensor(C_cmoalcruom),n3_0v2alue

(C++ member), 296

ESP_BLE_MESH_SENSOR_NOT_APPL_UPDATE_INTERVAL

ESP_BLE_MESH_SENSOR_DATA_FORMAT_A (C

(C macro), 302

macro), 303

ESP_BLE_MESH_SENSOR_PERIOD_DIVISOR_MAX_VALUE

ESP_BLE_MESH_SENSOR_DATA_FORMAT_A_MPID

(C macro), 303

(C macro), 303

ESP_BLE_MESH_SENSOR_PROPERTY_ID_LEN (C

ESP_BLE_MESH_SENSOR_DATA_FORMAT_A_MPID_LEN macro), 302

(C macro), 303

esp_ble_mesh_sensor_sample_func (C++

ESP_BLE_MESH_SENSOR_DATA_FORMAT_B (C

enum), 305

macro), 303

esp_ble_mesh_sensor_series_column_t

ESP_BLE_MESH_SENSOR_DATA_FORMAT_B_MPID

(C++ class), 298

(C macro), 304

esp_ble_mesh_sensor_series_column_t::column_width

ESP_BLE_MESH_SENSOR_DATA_FORMAT_B_MPID_LEN (C++ member), 298

(C macro), 303

esp_ble_mesh_sensor_series_column_t::raw_value_x

esp_ble_mesh_sensor_data_t (C++ class),

(C++ member), 298

297

esp_ble_mesh_sensor_series_column_t::raw_value_y

esp_ble_mesh_sensor_data_t::format

(C++ member), 298

(C++ member), 297

esp_ble_mesh_sensor_series_get_t (C++

esp_ble_mesh_sensor_data_t::length

class), 294

(C++ member), 298

esp_ble_mesh_sensor_series_get_t::op_en

esp_ble_mesh_sensor_data_t::raw_value

(C++ member), 295

(C++ member), 298

esp_ble_mesh_sensor_series_get_t::property_id

ESP_BLE_MESH_SENSOR_DATA_ZERO_LEN (C

(C++ member), 295

macro), 303

esp_ble_mesh_sensor_series_get_t::raw_value_x1

esp_ble_mesh_sensor_descriptor_get_t

(C++ member), 295

(C++ class), 293

esp_ble_mesh_sensor_series_get_t::raw_value_x2

esp_ble_mesh_sensor_descriptor_get_t::op_en (C++ member), 295

(C++ member), 293

esp_ble_mesh_sensor_series_status_cb_t

esp_ble_mesh_sensor_descriptor_get_t::property(C_+i+d class), 296

(C++ member), 293

esp_ble_mesh_sensor_series_status_cb_t::property_

ESP_BLE_MESH_SENSOR_DESCRIPTOR_LEN (C

(C++ member), 296

Espressif Systems

2078

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_mesh_sensor_series_status_cb_t:E:SsPe_nBsLoEr__MsEeSrHi_eSsE_NvSaOlRu_eSETTING_ACCESS_LEN

(C++ member), 296

(C macro), 302

esp_ble_mesh_sensor_server_cb_event_t ESP_BLE_MESH_SENSOR_SETTING_ACCESS_READ

(C++ enum), 305

(C macro), 302

esp_ble_mesh_sensor_server_cb_param_t ESP_BLE_MESH_SENSOR_SETTING_ACCESS_READ_WRITE

(C++ class), 301

(C macro), 302

esp_ble_mesh_sensor_server_cb_param_t::ecstpx_ble_mesh_sensor_setting_get_t

(C++ member), 301

(C++ class), 294

esp_ble_mesh_sensor_server_cb_param_t::emsopd_eblle_mesh_sensor_setting_get_t::sensor_propert

(C++ member), 301

(C++ member), 294

esp_ble_mesh_sensor_server_cb_param_t::evsapl_ubele_mesh_sensor_setting_get_t::sensor_setting

(C++ member), 301

(C++ member), 294

esp_ble_mesh_sensor_server_cb_t (C++ ESP_BLE_MESH_SENSOR_SETTING_PROPERTY_ID_LEN

type), 304

(C macro), 302

esp_ble_mesh_sensor_server_cb_value_t esp_ble_mesh_sensor_setting_set_t

(C++ union), 292

(C++ class), 294

esp_ble_mesh_sensor_server_cb_value_t::egsept_ble_mesh_sensor_setting_set_t::sensor_propert

(C++ member), 293

(C++ member), 294

esp_ble_mesh_sensor_server_cb_value_t::essept_ble_mesh_sensor_setting_set_t::sensor_setting

(C++ member), 293

(C++ member), 294

esp_ble_mesh_sensor_server_cb_value_t::esstpa_tbel_ec_hmaensghe_sensor_setting_set_t::sensor_setting

(C++ member), 293

(C++ member), 294

ESP_BLE_MESH_SENSOR_SERVER_EVT_MAX

esp_ble_mesh_sensor_setting_status_cb_t

(C++ enumerator), 305

(C++ class), 295

ESP_BLE_MESH_SENSOR_SERVER_RECV_GET_MSGe_sEpV_Tble_mesh_sensor_setting_status_cb_t::op_en

(C++ enumerator), 305

(C++ member), 295

esp_ble_mesh_sensor_server_recv_get_msge_stp_ble_mesh_sensor_setting_status_cb_t::sensor_p

(C++ union), 292

(C++ member), 295

esp_ble_mesh_sensor_server_recv_get_msge_stp:_:bsleen_smoers_hc_asdeennscoer_setting_status_cb_t::sensor_s

(C++ member), 292

(C++ member), 295

esp_ble_mesh_sensor_server_recv_get_msge_stp:_:bsleen_smoers_hc_osleunmsnor_setting_status_cb_t::sensor_s

(C++ member), 292

(C++ member), 295

esp_ble_mesh_sensor_server_recv_get_msge_stp:_:bsleen_smoers_hd_asteansor_setting_status_cb_t::sensor_s

(C++ member), 292

(C++ member), 296

esp_ble_mesh_sensor_server_recv_get_msge_stp:_:bsleen_smoers_hd_essecnrsioprt_osretting_t (C++

(C++ member), 292

class), 297

esp_ble_mesh_sensor_server_recv_get_msge_stp:_:bsleen_smoers_hs_esreinessor_setting_t::access

(C++ member), 292

(C++ member), 297

esp_ble_mesh_sensor_server_recv_get_msge_stp:_:bsleen_smoers_hs_estetnisnogr_setting_t::property_id

(C++ member), 292

(C++ member), 297

esp_ble_mesh_sensor_server_recv_get_msge_stp:_:bsleen_smoers_hs_estetnisnogrs_setting_t::raw

(C++ member), 292

(C++ member), 297

ESP_BLE_MESH_SENSOR_SERVER_RECV_SET_MSGe_sEpV_Tble_mesh_sensor_settings_get_t

(C++ enumerator), 305

(C++ class), 293

esp_ble_mesh_sensor_server_recv_set_msge_stp_ble_mesh_sensor_settings_get_t::sensor_proper

(C++ union), 292

(C++ member), 294

esp_ble_mesh_sensor_server_recv_set_msge_stp:_:bsleen_smoers_hc_asdeennscoer_settings_status_cb_t

(C++ member), 292

(C++ class), 295

esp_ble_mesh_sensor_server_recv_set_msge_stp:_:bsleen_smoers_hs_estetnisnogr_settings_status_cb_t::sensor_

(C++ member), 292

(C++ member), 295

ESP_BLE_MESH_SENSOR_SERVER_STATE_CHANGEe_sEpV_Tble_mesh_sensor_settings_status_cb_t::sensor_

(C++ enumerator), 305

(C++ member), 295

esp_ble_mesh_sensor_server_state_changee_stp_ble_mesh_sensor_setup_srv_t (C++

(C++ union), 292

class), 299

esp_ble_mesh_sensor_server_state_changee_stp:_:bsleen_smoers_hc_asdeennscoer__sseettup_srv_t::model

(C++ member), 292

(C++ member), 299

esp_ble_mesh_sensor_server_state_changee_stp:_:bsleen_smoers_hs_estetnisnogr__sseettup_srv_t::rsp_ctrl

(C++ member), 292

(C++ member), 299

Espressif Systems

2079

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_mesh_sensor_setup_srv_t::state_count (C++ class), 281

(C++ member), 299

esp_ble_mesh_server_recv_gen_admin_property_get_t

esp_ble_mesh_sensor_setup_srv_t::states

(C++ member), 281

(C++ member), 299

esp_ble_mesh_server_recv_gen_admin_property_set_t

esp_ble_mesh_sensor_srv_t (C++ class), 298

(C++ class), 284

esp_ble_mesh_sensor_srv_t::model (C++ esp_ble_mesh_server_recv_gen_admin_property_set_t

member), 298

(C++ member), 284

esp_ble_mesh_sensor_srv_t::rsp_ctrl esp_ble_mesh_server_recv_gen_admin_property_set_t

(C++ member), 298

(C++ member), 284

esp_ble_mesh_sensor_srv_t::state_count esp_ble_mesh_server_recv_gen_admin_property_set_t

(C++ member), 298

(C++ member), 284

esp_ble_mesh_sensor_srv_t::states

esp_ble_mesh_server_recv_gen_client_properties_ge

(C++ member), 299

(C++ class), 281

esp_ble_mesh_sensor_state_t (C++ class), esp_ble_mesh_server_recv_gen_client_properties_ge

298

(C++ member), 281

esp_ble_mesh_sensor_state_t::cadence esp_ble_mesh_server_recv_gen_def_trans_time_set_t

(C++ member), 298

(C++ class), 282

esp_ble_mesh_sensor_state_t::descriptoresp_ble_mesh_server_recv_gen_def_trans_time_set_t

(C++ member), 298

(C++ member), 283

esp_ble_mesh_sensor_state_t::sensor_dateasp_ble_mesh_server_recv_gen_delta_set_t

(C++ member), 298

(C++ class), 282

esp_ble_mesh_sensor_state_t::sensor_proepsepr_tbyl_ei_dmesh_server_recv_gen_delta_set_t::delay

(C++ member), 298

(C++ member), 282

esp_ble_mesh_sensor_state_t::series_coleusmpn_ble_mesh_server_recv_gen_delta_set_t::delta_l

(C++ member), 298

(C++ member), 282

esp_ble_mesh_sensor_state_t::setting_coeusnpt_ble_mesh_server_recv_gen_delta_set_t::op_en

(C++ member), 298

(C++ member), 282

esp_ble_mesh_sensor_state_t::settings esp_ble_mesh_server_recv_gen_delta_set_t::tid

(C++ member), 298

(C++ member), 282

esp_ble_mesh_sensor_status_cb_t (C++ esp_ble_mesh_server_recv_gen_delta_set_t::trans_t

class), 296

(C++ member), 282

esp_ble_mesh_sensor_status_cb_t::marshaelslpe_db_lsee_nmseosrh__dsaetraver_recv_gen_level_set_t

(C++ member), 296

(C++ class), 281

ESP_BLE_MESH_SENSOR_STATUS_MIN_INTERVALe_sLpE_Nble_mesh_server_recv_gen_level_set_t::delay

(C macro), 303

(C++ member), 282

ESP_BLE_MESH_SENSOR_STATUS_MIN_INTERVALe_sMpA_Xble_mesh_server_recv_gen_level_set_t::level

(C macro), 303

(C++ member), 282

ESP_BLE_MESH_SENSOR_STATUS_TRIGGER_TYPEe_sCpH_AbRle_mesh_server_recv_gen_level_set_t::op_en

(C macro), 303

(C++ member), 282

ESP_BLE_MESH_SENSOR_STATUS_TRIGGER_TYPEe_sUpI_NbTl1e6_mesh_server_recv_gen_level_set_t::tid

(C macro), 303

(C++ member), 282

ESP_BLE_MESH_SENSOR_UNSPECIFIED_NEG_TOLeEsRpA_NbClEe_mesh_server_recv_gen_level_set_t::trans_t

(C macro), 302

(C++ member), 282

ESP_BLE_MESH_SENSOR_UNSPECIFIED_POS_TOLeEsRpA_NbClEe_mesh_server_recv_gen_loc_global_set_t

(C macro), 302

(C++ class), 283

ESP_BLE_MESH_SERVER_AUTO_RSP (C macro), esp_ble_mesh_server_recv_gen_loc_global_set_t::gl

202

(C++ member), 284

ESP_BLE_MESH_SERVER_FLAG_MAX (C++ enu- esp_ble_mesh_server_recv_gen_loc_global_set_t::gl

merator), 209

(C++ member), 284

esp_ble_mesh_server_model_send_msg

esp_ble_mesh_server_recv_gen_loc_global_set_t::gl

(C++ function), 214

(C++ member), 284

ESP_BLE_MESH_SERVER_MODEL_STATE_MAX esp_ble_mesh_server_recv_gen_loc_local_set_t

(C++ enumerator), 209

(C++ class), 284

esp_ble_mesh_server_model_update_state esp_ble_mesh_server_recv_gen_loc_local_set_t::flo

(C++ function), 215

(C++ member), 284

ESP_BLE_MESH_SERVER_MODEL_UPDATE_STATE_eCsOpM_Pb_lEeV_Tmesh_server_recv_gen_loc_local_set_t::loc

(C++ enumerator), 210

(C++ member), 284

esp_ble_mesh_server_recv_gen_admin_propeesrpt_yb_lgee_tm_etsh_server_recv_gen_loc_local_set_t::loc

Espressif Systems

2080

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 284

(C++ member), 283

esp_ble_mesh_server_recv_gen_loc_local_essept__btl:e:_lmoecsahl__sneorrvtehr_recv_gen_power_range_set_t

(C++ member), 284

(C++ class), 283

esp_ble_mesh_server_recv_gen_loc_local_essept__btl:e:_umnecsehr_tsaeirnvteyr_recv_gen_power_range_set_t::r

(C++ member), 284

(C++ member), 283

esp_ble_mesh_server_recv_gen_manufactureesrp__pbrloep_emretsyh__gseetr_vter_recv_gen_power_range_set_t::r

(C++ class), 281

(C++ member), 283

esp_ble_mesh_server_recv_gen_manufactureesrp__pbrloep_emretsyh__gseetr_vte:r:_prreocpve_rgteyn__iudser_property_get_t

(C++ member), 281

(C++ class), 280

esp_ble_mesh_server_recv_gen_manufactureesrp__pbrloep_emretsyh__sseetr_vter_recv_gen_user_property_get_t:

(C++ class), 284

(C++ member), 281

esp_ble_mesh_server_recv_gen_manufactureesrp__pbrloep_emretsyh__sseetr_vte:r:_prreocpve_rgteyn__iudser_property_set_t

(C++ member), 285

(C++ class), 284

esp_ble_mesh_server_recv_gen_manufactureesrp__pbrloep_emretsyh__sseetr_vte:r:_urseecrv__agcecne_susser_property_set_t:

(C++ member), 285

(C++ member), 284

esp_ble_mesh_server_recv_gen_move_set_tesp_ble_mesh_server_recv_gen_user_property_set_t:

(C++ class), 282

(C++ member), 284

esp_ble_mesh_server_recv_gen_move_set_te:s:pd_ebllaey_mesh_server_recv_light_ctl_default_set_t

(C++ member), 282

(C++ class), 360

esp_ble_mesh_server_recv_gen_move_set_te:s:pd_eblltea__mleesvhe_lserver_recv_light_ctl_default_set_t:

(C++ member), 282

(C++ member), 360

esp_ble_mesh_server_recv_gen_move_set_te:s:po_pb_leen_mesh_server_recv_light_ctl_default_set_t:

(C++ member), 282

(C++ member), 360

esp_ble_mesh_server_recv_gen_move_set_te:s:pt_ibdle_mesh_server_recv_light_ctl_default_set_t:

(C++ member), 282

(C++ member), 360

esp_ble_mesh_server_recv_gen_move_set_te:s:pt_rbalnes__mteismhe_server_recv_light_ctl_set_t

(C++ member), 282

(C++ class), 359

esp_ble_mesh_server_recv_gen_onoff_set_etsp_ble_mesh_server_recv_light_ctl_set_t::delay

(C++ class), 281

(C++ member), 359

esp_ble_mesh_server_recv_gen_onoff_set_ets:p:_dbellea_ymesh_server_recv_light_ctl_set_t::delta_u

(C++ member), 281

(C++ member), 359

esp_ble_mesh_server_recv_gen_onoff_set_ets:p:_obnloef_fmesh_server_recv_light_ctl_set_t::lightne

(C++ member), 281

(C++ member), 359

esp_ble_mesh_server_recv_gen_onoff_set_ets:p:_obpl_ee_nmesh_server_recv_light_ctl_set_t::op_en

(C++ member), 281

(C++ member), 359

esp_ble_mesh_server_recv_gen_onoff_set_ets:p:_tbilde_mesh_server_recv_light_ctl_set_t::tempera

(C++ member), 281

(C++ member), 359

esp_ble_mesh_server_recv_gen_onoff_set_ets:p:_tbrlaen_sm_etsihm_eserver_recv_light_ctl_set_t::tid

(C++ member), 281

(C++ member), 359

esp_ble_mesh_server_recv_gen_onpowerup_essept__btle_mesh_server_recv_light_ctl_set_t::trans_t

(C++ class), 283

(C++ member), 359

esp_ble_mesh_server_recv_gen_onpowerup_essept__btl:e:_omnepsohw_esreurpver_recv_light_ctl_temperature_ra

(C++ member), 283

(C++ class), 360

esp_ble_mesh_server_recv_gen_power_defaeuslpt__bsleet__mtesh_server_recv_light_ctl_temperature_ra

(C++ class), 283

(C++ member), 360

esp_ble_mesh_server_recv_gen_power_defaeuslpt__bsleet__mte:s:hp_osweerrver_recv_light_ctl_temperature_ra

(C++ member), 283

(C++ member), 360

esp_ble_mesh_server_recv_gen_power_leveels_ps_ebtl_et_mesh_server_recv_light_ctl_temperature_se

(C++ class), 283

(C++ class), 359

esp_ble_mesh_server_recv_gen_power_leveels_ps_ebtl_et_:m:edsehl_asyerver_recv_light_ctl_temperature_se

(C++ member), 283

(C++ member), 360

esp_ble_mesh_server_recv_gen_power_leveels_ps_ebtl_et_:m:eosph__esnerver_recv_light_ctl_temperature_se

(C++ member), 283

(C++ member), 359

esp_ble_mesh_server_recv_gen_power_leveels_ps_ebtl_et_:m:epsohw_esrerver_recv_light_ctl_temperature_se

(C++ member), 283

(C++ member), 359

esp_ble_mesh_server_recv_gen_power_leveels_ps_ebtl_et_:m:etsihd_server_recv_light_ctl_temperature_se

(C++ member), 283

(C++ member), 359

esp_ble_mesh_server_recv_gen_power_leveels_ps_ebtl_et_:m:etsrha_nsse_rtviemre_recv_light_ctl_temperature_se

Espressif Systems

2081

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 359

(C++ member), 360

esp_ble_mesh_server_recv_light_ctl_tempeesrpa_tbulree__mseesth__ts:e:rtvrearn_sr_etcivm_elight_hsl_set_t::trans_t

(C++ member), 360

(C++ member), 360

esp_ble_mesh_server_recv_light_hsl_defaeuslpt__bsleet__mtesh_server_recv_light_lc_light_onoff_set

(C++ class), 361

(C++ class), 363

esp_ble_mesh_server_recv_light_hsl_defaeuslpt__bsleet__mte:s:hh_useerver_recv_light_lc_light_onoff_set

(C++ member), 361

(C++ member), 363

esp_ble_mesh_server_recv_light_hsl_defaeuslpt__bsleet__mte:s:hl_isgehrtvneers_srecv_light_lc_light_onoff_set

(C++ member), 361

(C++ member), 363

esp_ble_mesh_server_recv_light_hsl_defaeuslpt__bsleet__mte:s:hs_asteurrvaetri_ornecv_light_lc_light_onoff_set

(C++ member), 361

(C++ member), 363

esp_ble_mesh_server_recv_light_hsl_hue_essept__btle_mesh_server_recv_light_lc_light_onoff_set

(C++ class), 360

(C++ member), 363

esp_ble_mesh_server_recv_light_hsl_hue_essept__btl:e:_dmeelsahy_server_recv_light_lc_light_onoff_set

(C++ member), 361

(C++ member), 363

esp_ble_mesh_server_recv_light_hsl_hue_essept__btl:e:_hmueesh_server_recv_light_lc_mode_set_t

(C++ member), 361

(C++ class), 362

esp_ble_mesh_server_recv_light_hsl_hue_essept__btl:e:_ompe_sehn_server_recv_light_lc_mode_set_t::mod

(C++ member), 361

(C++ member), 363

esp_ble_mesh_server_recv_light_hsl_hue_essept__btl:e:_tmiedsh_server_recv_light_lc_om_set_t

(C++ member), 361

(C++ class), 363

esp_ble_mesh_server_recv_light_hsl_hue_essept__btl:e:_tmreasnhs__steirmveer_recv_light_lc_om_set_t::mode

(C++ member), 361

(C++ member), 363

esp_ble_mesh_server_recv_light_hsl_rangees_ps_ebtl_et_mesh_server_recv_light_lc_property_get_t

(C++ class), 361

(C++ class), 358

esp_ble_mesh_server_recv_light_hsl_rangees_ps_ebtl_et_:m:ehsuhe__srearnvgeer__mraexcv_light_lc_property_get_t:

(C++ member), 361

(C++ member), 358

esp_ble_mesh_server_recv_light_hsl_rangees_ps_ebtl_et_:m:ehsuhe__srearnvgeer__mriencv_light_lc_property_set_t

(C++ member), 361

(C++ class), 363

esp_ble_mesh_server_recv_light_hsl_rangees_ps_ebtl_et_:m:essaht_usreartvieorn__rreacnvg_el_imgahxt_lc_property_set_t:

(C++ member), 362

(C++ member), 363

esp_ble_mesh_server_recv_light_hsl_rangees_ps_ebtl_et_:m:essaht_usreartvieorn__rreacnvg_el_imgihnt_lc_property_set_t:

(C++ member), 361

(C++ member), 363

esp_ble_mesh_server_recv_light_hsl_satuersapt_ibolne__smeets_ht_server_recv_light_lightness_default_

(C++ class), 361

(C++ class), 359

esp_ble_mesh_server_recv_light_hsl_satuersapt_ibolne__smeets_ht_:s:edrevleary_recv_light_lightness_default_

(C++ member), 361

(C++ member), 359

esp_ble_mesh_server_recv_light_hsl_satuersapt_ibolne__smeets_ht_:s:eorpv_eern_recv_light_lightness_linear_s

(C++ member), 361

(C++ class), 358

esp_ble_mesh_server_recv_light_hsl_satuersapt_ibolne__smeets_ht_:s:esravteurr_arteicovn_light_lightness_linear_s

(C++ member), 361

(C++ member), 358

esp_ble_mesh_server_recv_light_hsl_satuersapt_ibolne__smeets_ht_:s:etrivder_recv_light_lightness_linear_s

(C++ member), 361

(C++ member), 358

esp_ble_mesh_server_recv_light_hsl_satuersapt_ibolne__smeets_ht_:s:etrrvaenrs__rteicmve_light_lightness_linear_s

(C++ member), 361

(C++ member), 358

esp_ble_mesh_server_recv_light_hsl_set_etsp_ble_mesh_server_recv_light_lightness_linear_s

(C++ class), 360

(C++ member), 358

esp_ble_mesh_server_recv_light_hsl_set_ets:p:_dbellea_ymesh_server_recv_light_lightness_linear_s

(C++ member), 360

(C++ member), 358

esp_ble_mesh_server_recv_light_hsl_set_ets:p:_hbulee_mesh_server_recv_light_lightness_range_se

(C++ member), 360

(C++ class), 359

esp_ble_mesh_server_recv_light_hsl_set_ets:p:_lbilgeh_tmneesshs_server_recv_light_lightness_range_se

(C++ member), 360

(C++ member), 359

esp_ble_mesh_server_recv_light_hsl_set_ets:p:_obpl_ee_nmesh_server_recv_light_lightness_range_se

(C++ member), 360

(C++ member), 359

esp_ble_mesh_server_recv_light_hsl_set_ets:p:_sbalteu_rmaetsiho_nserver_recv_light_lightness_set_t

(C++ member), 360

(C++ class), 358

esp_ble_mesh_server_recv_light_hsl_set_ets:p:_tbilde_mesh_server_recv_light_lightness_set_t::d

Espressif Systems

2082

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 358

(C++ member), 321

esp_ble_mesh_server_recv_light_lightnesess_ps_ebtl_et_:m:elsihg_hstenrevsesr_recv_scene_store_t

(C++ member), 358

(C++ class), 321

esp_ble_mesh_server_recv_light_lightnesess_ps_ebtl_et_:m:eosph__esnerver_recv_scene_store_t::scene_num

(C++ member), 358

(C++ member), 321

esp_ble_mesh_server_recv_light_lightnesess_ps_ebtl_et_:m:etsihd_server_recv_scheduler_act_get_t

(C++ member), 358

(C++ class), 320

esp_ble_mesh_server_recv_light_lightnesess_ps_ebtl_et_:m:etsrha_nsse_rtviemre_recv_scheduler_act_get_t::ind

(C++ member), 358

(C++ member), 320

esp_ble_mesh_server_recv_light_xyl_defaeuslpt__bsleet__mtesh_server_recv_scheduler_act_set_t

(C++ class), 362

(C++ class), 321

esp_ble_mesh_server_recv_light_xyl_defaeuslpt__bsleet__mte:s:hl_isgehrtvneers_srecv_scheduler_act_set_t::act

(C++ member), 362

(C++ member), 322

esp_ble_mesh_server_recv_light_xyl_defaeuslpt__bsleet__mte:s:hx_server_recv_scheduler_act_set_t::day

(C++ member), 362

(C++ member), 322

esp_ble_mesh_server_recv_light_xyl_defaeuslpt__bsleet__mte:s:hy_server_recv_scheduler_act_set_t::day

(C++ member), 362

(C++ member), 322

esp_ble_mesh_server_recv_light_xyl_rangees_ps_ebtl_et_mesh_server_recv_scheduler_act_set_t::hou

(C++ class), 362

(C++ member), 322

esp_ble_mesh_server_recv_light_xyl_rangees_ps_ebtl_et_:m:exs_hr_asnegrev_emra_xrecv_scheduler_act_set_t::ind

(C++ member), 362

(C++ member), 321

esp_ble_mesh_server_recv_light_xyl_rangees_ps_ebtl_et_:m:exs_hr_asnegrev_emri_nrecv_scheduler_act_set_t::min

(C++ member), 362

(C++ member), 322

esp_ble_mesh_server_recv_light_xyl_rangees_ps_ebtl_et_:m:eys_hr_asnegrev_emra_xrecv_scheduler_act_set_t::mon

(C++ member), 362

(C++ member), 321

esp_ble_mesh_server_recv_light_xyl_rangees_ps_ebtl_et_:m:eys_hr_asnegrev_emri_nrecv_scheduler_act_set_t::sce

(C++ member), 362

(C++ member), 322

esp_ble_mesh_server_recv_light_xyl_set_etsp_ble_mesh_server_recv_scheduler_act_set_t::sec

(C++ class), 362

(C++ member), 322

esp_ble_mesh_server_recv_light_xyl_set_ets:p:_dbellea_ymesh_server_recv_scheduler_act_set_t::tra

(C++ member), 362

(C++ member), 322

esp_ble_mesh_server_recv_light_xyl_set_ets:p:_lbilgeh_tmneesshs_server_recv_scheduler_act_set_t::yea

(C++ member), 362

(C++ member), 321

esp_ble_mesh_server_recv_light_xyl_set_ets:p:_obpl_ee_nmesh_server_recv_sensor_cadence_get_t

(C++ member), 362

(C++ class), 300

esp_ble_mesh_server_recv_light_xyl_set_ets:p:_tbilde_mesh_server_recv_sensor_cadence_get_t::pr

(C++ member), 362

(C++ member), 300

esp_ble_mesh_server_recv_light_xyl_set_ets:p:_tbrlaen_sm_etsihm_eserver_recv_sensor_cadence_set_t

(C++ member), 362

(C++ class), 301

esp_ble_mesh_server_recv_light_xyl_set_ets:p:_xble_mesh_server_recv_sensor_cadence_set_t::ca

(C++ member), 362

(C++ member), 301

esp_ble_mesh_server_recv_light_xyl_set_ets:p:_yble_mesh_server_recv_sensor_cadence_set_t::pr

(C++ member), 362

(C++ member), 301

esp_ble_mesh_server_recv_scene_delete_tesp_ble_mesh_server_recv_sensor_column_get_t

(C++ class), 321

(C++ class), 300

esp_ble_mesh_server_recv_scene_delete_te:s:ps_cbelnee__mneusmhb_esrerver_recv_sensor_column_get_t::pro

(C++ member), 321

(C++ member), 301

esp_ble_mesh_server_recv_scene_recall_tesp_ble_mesh_server_recv_sensor_column_get_t::raw

(C++ class), 321

(C++ member), 301

esp_ble_mesh_server_recv_scene_recall_te:s:pd_ebllaey_mesh_server_recv_sensor_descriptor_get_t

(C++ member), 321

(C++ class), 300

esp_ble_mesh_server_recv_scene_recall_te:s:po_pb_leen_mesh_server_recv_sensor_descriptor_get_t:

(C++ member), 321

(C++ member), 300

esp_ble_mesh_server_recv_scene_recall_te:s:ps_cbelnee__mneusmhb_esrerver_recv_sensor_descriptor_get_t:

(C++ member), 321

(C++ member), 300

esp_ble_mesh_server_recv_scene_recall_te:s:pt_ibdle_mesh_server_recv_sensor_get_t

(C++ member), 321

(C++ class), 300

esp_ble_mesh_server_recv_scene_recall_te:s:pt_rbalnes__mteismhe_server_recv_sensor_get_t::op_en

Espressif Systems

2083

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 300

(C++ member), 320

esp_ble_mesh_server_recv_sensor_get_t::epsrpo_pbelret_ym_eisdh_server_recv_time_status_t

(C++ member), 300

(C++ class), 322

esp_ble_mesh_server_recv_sensor_series_egsept__btle_mesh_server_recv_time_status_t::subsecond

(C++ class), 301

(C++ member), 322

esp_ble_mesh_server_recv_sensor_series_egsept__btl:e:_ompe_sehn_server_recv_time_status_t::tai_secon

(C++ member), 301

(C++ member), 322

esp_ble_mesh_server_recv_sensor_series_egsept__btl:e:_pmreosphe_rsteyr_viedr_recv_time_status_t::tai_utc_d

(C++ member), 301

(C++ member), 322

esp_ble_mesh_server_recv_sensor_series_egsept__btl:e:_rmaews_hv_asleurever_recv_time_status_t::time_auth

(C++ member), 301

(C++ member), 322

esp_ble_mesh_server_recv_sensor_settinge_sgpe_tb_lte_mesh_server_recv_time_status_t::time_zone

(C++ class), 300

(C++ member), 322

esp_ble_mesh_server_recv_sensor_settinge_sgpe_tb_lte:_:mpersohp_esretryv_eird_recv_time_status_t::uncertain

(C++ member), 300

(C++ member), 322

esp_ble_mesh_server_recv_sensor_settinge_sgpe_tb_lte:_:mseestht_isnegr_vperro_preerctvy__tiidme_zone_set_t

(C++ member), 300

(C++ class), 320

esp_ble_mesh_server_recv_sensor_settinge_sspe_tb_lte_mesh_server_recv_time_zone_set_t::tai_zon

(C++ class), 301

(C++ member), 320

esp_ble_mesh_server_recv_sensor_settinge_sspe_tb_lte:_:mpersohp_esretryv_eird_recv_time_zone_set_t::time_zo

(C++ member), 301

(C++ member), 320

esp_ble_mesh_server_recv_sensor_settingE_SsPe_tB_LtE:_:MsEeStHt_iSnEgR_VpErRo_pReSrPt_yB_Yi_dAPP

(C

(C++ member), 301

macro), 202

esp_ble_mesh_server_recv_sensor_settinge_sspe_tb_lte:_:mseestht_isnegr_vrearw_rsp_ctrl_t (C++

(C++ member), 301

class), 187

esp_ble_mesh_server_recv_sensor_settingess_pg_ebtl_et_mesh_server_rsp_ctrl_t::get_auto_rsp

(C++ class), 300

(C++ member), 187

esp_ble_mesh_server_recv_sensor_settingess_pg_ebtl_et_:m:epsrho_pseerrtvye_ri_drsp_ctrl_t::set_auto_rsp

(C++ member), 300

(C++ member), 188

esp_ble_mesh_server_recv_sensor_status_etsp_ble_mesh_server_rsp_ctrl_t::status_auto_rsp

(C++ class), 363

(C++ member), 188

esp_ble_mesh_server_recv_sensor_status_ets:p:_dbaltea_mesh_server_state_type_t (C++

(C++ member), 363

enum), 209

esp_ble_mesh_server_recv_tai_utc_delta_essept__btle_mesh_server_state_value_t

(C++ class), 320

(C++ union), 176

esp_ble_mesh_server_recv_tai_utc_delta_essept__btl:e:_pmaedsdhi_nsgerver_state_value_t::delta_uv

(C++ member), 320

(C++ member), 177

esp_ble_mesh_server_recv_tai_utc_delta_essept__btl:e:_tmaeis_hd_esletrav_ecrh_asntgaete_value_t::gen_level

(C++ member), 321

(C++ member), 176

esp_ble_mesh_server_recv_tai_utc_delta_essept__btl:e:_tmaeis_hu_tsce_rdveelrt_as_tnaetwe_value_t::gen_onoff

(C++ member), 320

(C++ member), 176

esp_ble_mesh_server_recv_time_role_set_etsp_ble_mesh_server_state_value_t::gen_onpowerup

(C++ class), 321

(C++ member), 176

esp_ble_mesh_server_recv_time_role_set_ets:p:_tbilmee__mreoslhe_server_state_value_t::gen_power_actu

(C++ member), 321

(C++ member), 177

esp_ble_mesh_server_recv_time_set_t esp_ble_mesh_server_state_value_t::hue

(C++ class), 320

(C++ member), 177

esp_ble_mesh_server_recv_time_set_t::suebsspe_cbolned_mesh_server_state_value_t::level

(C++ member), 320

(C++ member), 176

esp_ble_mesh_server_recv_time_set_t::taeis_ps_ebcloen_dmsesh_server_state_value_t::light_ctl_ligh

(C++ member), 320

(C++ member), 177

esp_ble_mesh_server_recv_time_set_t::taeis_pu_tbcl_ed_emletsah_server_state_value_t::light_ctl_temp

(C++ member), 320

(C++ member), 177

esp_ble_mesh_server_recv_time_set_t::tiemsep__abulteh_omreisthy_server_state_value_t::light_hsl

(C++ member), 320

(C++ member), 177

esp_ble_mesh_server_recv_time_set_t::tiemsep__zbolnee__moefsfhs_esterver_state_value_t::light_hsl_hue

(C++ member), 320

(C++ member), 177

esp_ble_mesh_server_recv_time_set_t::unecsepr_tbalien_tmyesh_server_state_value_t::light_hsl_ligh

Espressif Systems

2084

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 177

esp_ble_mesh_state_change_cfg_appkey_update_t::ne

esp_ble_mesh_server_state_value_t::light_hsl_s(Ca+t+urmaetmiboenr), 248

(C++ member), 177

esp_ble_mesh_state_change_cfg_kr_phase_set_t

esp_ble_mesh_server_state_value_t::light_lc_li(Cg+h+t_colansso)f, 2f49

(C++ member), 177

esp_ble_mesh_state_change_cfg_kr_phase_set_t::kr_

esp_ble_mesh_server_state_value_t::light_light(Cn+e+ssm_eamcbteur)a, l249

(C++ member), 177

esp_ble_mesh_state_change_cfg_kr_phase_set_t::net

esp_ble_mesh_server_state_value_t::light_light(Cn+e+ssm_elmibneer)a, r249

(C++ member), 177

esp_ble_mesh_state_change_cfg_mod_pub_set_t

esp_ble_mesh_server_state_value_t::light_xyl_l(Ci+g+htcnlaesss)s, 246

(C++ member), 177

esp_ble_mesh_state_change_cfg_mod_pub_set_t::app_

esp_ble_mesh_server_state_value_t::lightness (C++ member), 247

(C++ member), 177

esp_ble_mesh_state_change_cfg_mod_pub_set_t::comp

esp_ble_mesh_server_state_value_t::onoff

(C++ member), 247

(C++ member), 176

esp_ble_mesh_state_change_cfg_mod_pub_set_t::cred

esp_ble_mesh_server_state_value_t::onpowerup (C++ member), 247

(C++ member), 176

esp_ble_mesh_state_change_cfg_mod_pub_set_t::elem

esp_ble_mesh_server_state_value_t::power

(C++ member), 247

(C++ member), 177

esp_ble_mesh_state_change_cfg_mod_pub_set_t::mode

esp_ble_mesh_server_state_value_t::saturation (C++ member), 247

(C++ member), 177

esp_ble_mesh_state_change_cfg_mod_pub_set_t::pub_

esp_ble_mesh_server_state_value_t::temperature(C++ member), 247

(C++ member), 177

esp_ble_mesh_state_change_cfg_mod_pub_set_t::pub_

ESP_BLE_MESH_SERVER_TRANS_TIMER_START

(C++ member), 247

(C++ enumerator), 209

esp_ble_mesh_state_change_cfg_mod_pub_set_t::pub_

esp_ble_mesh_set_fast_prov_action

(C++ member), 247

(C++ function), 225

esp_ble_mesh_state_change_cfg_mod_pub_set_t::pub_

ESP_BLE_MESH_SET_FAST_PROV_ACTION_COMP_EVT (C++ member), 247

(C++ enumerator), 208

esp_ble_mesh_state_change_cfg_model_app_bind_t

esp_ble_mesh_set_fast_prov_info (C++

(C++ class), 249

function), 225

esp_ble_mesh_state_change_cfg_model_app_bind_t::a

ESP_BLE_MESH_SET_FAST_PROV_INFO_COMP_EVT

(C++ member), 249

(C++ enumerator), 208

esp_ble_mesh_state_change_cfg_model_app_bind_t::c

esp_ble_mesh_set_unprovisioned_device_name (C++ member), 249

(C++ function), 221

esp_ble_mesh_state_change_cfg_model_app_bind_t::e

ESP_BLE_MESH_SETTINGS_UID_SIZE

(C

(C++ member), 249

macro), 188

esp_ble_mesh_state_change_cfg_model_app_bind_t::m

ESP_BLE_MESH_SIG_MODEL (C macro), 190

(C++ member), 249

esp_ble_mesh_state_change_cfg_appkey_adeds_pt_ble_mesh_state_change_cfg_model_app_unbind_t

(C++ class), 248

(C++ class), 249

esp_ble_mesh_state_change_cfg_appkey_adeds_pt_:b:laep_pm_eisdhx_state_change_cfg_model_app_unbind_t:

(C++ member), 248

(C++ member), 249

esp_ble_mesh_state_change_cfg_appkey_adeds_pt_:b:laep_pm_eksehy_state_change_cfg_model_app_unbind_t:

(C++ member), 248

(C++ member), 249

esp_ble_mesh_state_change_cfg_appkey_adeds_pt_:b:lnee_tm_eisdhx_state_change_cfg_model_app_unbind_t:

(C++ member), 248

(C++ member), 249

esp_ble_mesh_state_change_cfg_appkey_deelsept_eb_lte_mesh_state_change_cfg_model_app_unbind_t:

(C++ class), 248

(C++ member), 249

esp_ble_mesh_state_change_cfg_appkey_deelsept_eb_lte:_:maepsph__isdtxate_change_cfg_model_sub_add_t

(C++ member), 249

(C++ class), 247

esp_ble_mesh_state_change_cfg_appkey_deelsept_eb_lte:_:mneesth__isdtxate_change_cfg_model_sub_add_t::co

(C++ member), 249

(C++ member), 247

esp_ble_mesh_state_change_cfg_appkey_upedsapt_eb_lte_mesh_state_change_cfg_model_sub_add_t::el

(C++ class), 248

(C++ member), 247

esp_ble_mesh_state_change_cfg_appkey_upedsapt_eb_lte:_:maepsph__isdtxate_change_cfg_model_sub_add_t::mo

(C++ member), 248

(C++ member), 247

esp_ble_mesh_state_change_cfg_appkey_upedsapt_eb_lte:_:maepsph__ksetyate_change_cfg_model_sub_add_t::su

(C++ member), 248

(C++ member), 247

Espressif Systems

2085

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_mesh_state_change_cfg_model_sube_sdpe_lbeltee__mtesh_state_change_gen_loc_local_set_t::ea

(C++ class), 247

(C++ member), 280

esp_ble_mesh_state_change_cfg_model_sube_sdpe_lbeltee__mte:s:hc_osmtpaatney__cihdange_gen_loc_local_set_t::fl

(C++ member), 247

(C++ member), 280

esp_ble_mesh_state_change_cfg_model_sube_sdpe_lbeltee__mte:s:he_lsetmaetnet__cahdadnrge_gen_loc_local_set_t::no

(C++ member), 247

(C++ member), 280

esp_ble_mesh_state_change_cfg_model_sube_sdpe_lbeltee__mte:s:hm_osdtealt_ei_dchange_gen_loc_local_set_t::un

(C++ member), 247

(C++ member), 280

esp_ble_mesh_state_change_cfg_model_sube_sdpe_lbeltee__mte:s:hs_usbt_aatded_rchange_gen_manu_property_set_t

(C++ member), 247

(C++ class), 280

esp_ble_mesh_state_change_cfg_netkey_adeds_pt_ble_mesh_state_change_gen_manu_property_set_t

(C++ class), 248

(C++ member), 280

esp_ble_mesh_state_change_cfg_netkey_adeds_pt_:b:lnee_tm_eisdhx_state_change_gen_manu_property_set_t

(C++ member), 248

(C++ member), 280

esp_ble_mesh_state_change_cfg_netkey_adeds_pt_:b:lnee_tm_eksehy_state_change_gen_move_set_t

(C++ member), 248

(C++ class), 278

esp_ble_mesh_state_change_cfg_netkey_deelsept_eb_lte_mesh_state_change_gen_move_set_t::level

(C++ class), 248

(C++ member), 279

esp_ble_mesh_state_change_cfg_netkey_deelsept_eb_lte:_:mneesth__isdtxate_change_gen_onoff_set_t

(C++ member), 248

(C++ class), 278

esp_ble_mesh_state_change_cfg_netkey_upedsapt_eb_lte_mesh_state_change_gen_onoff_set_t::onoff

(C++ class), 248

(C++ member), 278

esp_ble_mesh_state_change_cfg_netkey_upedsapt_eb_lte:_:mneesth__isdtxate_change_gen_onpowerup_set_t

(C++ member), 248

(C++ class), 279

esp_ble_mesh_state_change_cfg_netkey_upedsapt_eb_lte:_:mneesth__ksetyate_change_gen_onpowerup_set_t::on

(C++ member), 248

(C++ member), 279

esp_ble_mesh_state_change_gen_admin_proepsepr_tbyl_es_emte_sth_state_change_gen_power_default_set_t

(C++ class), 280

(C++ class), 279

esp_ble_mesh_state_change_gen_admin_proepsepr_tbyl_es_emte_sth:_:satcactees_schange_gen_power_default_set_t

(C++ member), 280

(C++ member), 279

esp_ble_mesh_state_change_gen_admin_proepsepr_tbyl_es_emte_sth:_:sitdate_change_gen_power_level_set_t

(C++ member), 280

(C++ class), 279

esp_ble_mesh_state_change_gen_admin_proepsepr_tbyl_es_emte_sth:_:svtaaltuee_change_gen_power_level_set_t::

(C++ member), 280

(C++ member), 279

esp_ble_mesh_state_change_gen_def_transe_stpi_mbel_es_emte_sth_state_change_gen_power_range_set_t

(C++ class), 279

(C++ class), 279

esp_ble_mesh_state_change_gen_def_transe_stpi_mbel_es_emte_sth:_:sttraatnes__cthiamnege_gen_power_range_set_t::

(C++ member), 279

(C++ member), 279

esp_ble_mesh_state_change_gen_delta_sete_stp_ble_mesh_state_change_gen_power_range_set_t::

(C++ class), 278

(C++ member), 279

esp_ble_mesh_state_change_gen_delta_sete_stp:_:blleev_emlesh_state_change_gen_user_property_set_t

(C++ member), 278

(C++ class), 280

esp_ble_mesh_state_change_gen_level_sete_stp_ble_mesh_state_change_gen_user_property_set_t

(C++ class), 278

(C++ member), 280

esp_ble_mesh_state_change_gen_level_sete_stp:_:blleev_emlesh_state_change_gen_user_property_set_t

(C++ member), 278

(C++ member), 280

esp_ble_mesh_state_change_gen_loc_globaels_ps_ebtl_et_mesh_state_change_light_ctl_default_set_t

(C++ class), 279

(C++ class), 355

esp_ble_mesh_state_change_gen_loc_globaels_ps_ebtl_et_:m:easlht_isttuadtee_change_light_ctl_default_set_t

(C++ member), 280

(C++ member), 355

esp_ble_mesh_state_change_gen_loc_globaels_ps_ebtl_et_:m:elsaht_isttuadtee_change_light_ctl_default_set_t

(C++ member), 279

(C++ member), 355

esp_ble_mesh_state_change_gen_loc_globaels_ps_ebtl_et_:m:elsohn_gsittautdee_change_light_ctl_default_set_t

(C++ member), 279

(C++ member), 355

esp_ble_mesh_state_change_gen_loc_locale_sspe_tb_lte_mesh_state_change_light_ctl_set_t

(C++ class), 280

(C++ class), 354

esp_ble_mesh_state_change_gen_loc_locale_sspe_tb_lte:_:maelsthi_tsutdaete_change_light_ctl_set_t::delta_

(C++ member), 280

(C++ member), 354

Espressif Systems

2086

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_mesh_state_change_light_ctl_sete_stp:_:bllieg_hmtensehs_sstate_change_light_lc_om_set_t

(C++ member), 354

(C++ class), 357

esp_ble_mesh_state_change_light_ctl_sete_stp:_:btleem_pmeersaht_usrteate_change_light_lc_om_set_t::mode

(C++ member), 354

(C++ member), 357

esp_ble_mesh_state_change_light_ctl_temepsepr_abtluer_em_ersahn_gset_asteet__cthange_light_lc_property_set_t

(C++ class), 355

(C++ class), 357

esp_ble_mesh_state_change_light_ctl_temepsepr_abtluer_em_ersahn_gset_asteet__cth:a:nrgaen_glei_gmhatx_lc_property_set_t

(C++ member), 355

(C++ member), 357

esp_ble_mesh_state_change_light_ctl_temepsepr_abtluer_em_ersahn_gset_asteet__cth:a:nrgaen_glei_gmhitn_lc_property_set_t

(C++ member), 355

(C++ member), 357

esp_ble_mesh_state_change_light_ctl_temepsepr_abtluer_em_esseht__sttate_change_light_lightness_default

(C++ class), 354

(C++ class), 354

esp_ble_mesh_state_change_light_ctl_temepsepr_abtluer_em_esseht__stt:a:tdee_lcthaa_nugve_light_lightness_default

(C++ member), 355

(C++ member), 354

esp_ble_mesh_state_change_light_ctl_temepsepr_abtluer_em_esseht__stt:a:ttee_mcphearnagteu_rleight_lightness_linear_

(C++ member), 355

(C++ class), 354

esp_ble_mesh_state_change_light_hsl_defeasupl_tb_lsee_tm_etsh_state_change_light_lightness_linear_

(C++ class), 356

(C++ member), 354

esp_ble_mesh_state_change_light_hsl_defeasupl_tb_lsee_tm_ets:h:_hsuteate_change_light_lightness_range_s

(C++ member), 356

(C++ class), 354

esp_ble_mesh_state_change_light_hsl_defeasupl_tb_lsee_tm_ets:h:_lsitgahtten_ecshsange_light_lightness_range_s

(C++ member), 356

(C++ member), 354

esp_ble_mesh_state_change_light_hsl_defeasupl_tb_lsee_tm_ets:h:_ssattautrea_tcihoannge_light_lightness_range_s

(C++ member), 356

(C++ member), 354

esp_ble_mesh_state_change_light_hsl_huee_sspe_tb_lte_mesh_state_change_light_lightness_set_t

(C++ class), 355

(C++ class), 354

esp_ble_mesh_state_change_light_hsl_huee_sspe_tb_lte:_:mheuseh_state_change_light_lightness_set_t::

(C++ member), 355

(C++ member), 354

esp_ble_mesh_state_change_light_hsl_ranegsep__sbelte__tmesh_state_change_light_xyl_default_set_t

(C++ class), 356

(C++ class), 356

esp_ble_mesh_state_change_light_hsl_ranegsep__sbelte__tm:e:shhu_es_traatneg_ec_hmaanxge_light_xyl_default_set_t

(C++ member), 356

(C++ member), 356

esp_ble_mesh_state_change_light_hsl_ranegsep__sbelte__tm:e:shhu_es_traatneg_ec_hmainnge_light_xyl_default_set_t

(C++ member), 356

(C++ member), 356

esp_ble_mesh_state_change_light_hsl_ranegsep__sbelte__tm:e:ssha_tsutraattei_ocnh_arnagneg_el_imgahxt_xyl_default_set_t

(C++ member), 356

(C++ member), 356

esp_ble_mesh_state_change_light_hsl_ranegsep__sbelte__tm:e:ssha_tsutraattei_ocnh_arnagneg_el_imgihnt_xyl_range_set_t

(C++ member), 356

(C++ class), 357

esp_ble_mesh_state_change_light_hsl_sateusrpa_tbiloen__mseesth__tstate_change_light_xyl_range_set_t::

(C++ class), 355

(C++ member), 357

esp_ble_mesh_state_change_light_hsl_sateusrpa_tbiloen__mseesth__ts:t:astaet_ucrhaatnigoen_light_xyl_range_set_t::

(C++ member), 356

(C++ member), 357

esp_ble_mesh_state_change_light_hsl_sete_stp_ble_mesh_state_change_light_xyl_range_set_t::

(C++ class), 355

(C++ member), 357

esp_ble_mesh_state_change_light_hsl_sete_stp:_:bhluee_mesh_state_change_light_xyl_range_set_t::

(C++ member), 355

(C++ member), 357

esp_ble_mesh_state_change_light_hsl_sete_stp:_:bllieg_hmtensehs_sstate_change_light_xyl_set_t

(C++ member), 355

(C++ class), 356

esp_ble_mesh_state_change_light_hsl_sete_stp:_:bslaet_umreasthi_osntate_change_light_xyl_set_t::lightn

(C++ member), 355

(C++ member), 356

esp_ble_mesh_state_change_light_lc_lighets_po_nbolfef__mseesth__tstate_change_light_xyl_set_t::x

(C++ class), 357

(C++ member), 356

esp_ble_mesh_state_change_light_lc_lighets_po_nbolfef__mseesth__ts:t:aotneo_fcfhange_light_xyl_set_t::y

(C++ member), 357

(C++ member), 356

esp_ble_mesh_state_change_light_lc_modee_sspe_tb_lte_mesh_state_change_scene_delete_t

(C++ class), 357

(C++ class), 319

esp_ble_mesh_state_change_light_lc_modee_sspe_tb_lte:_:mmeosdhe_state_change_scene_delete_t::scene_n

(C++ member), 357

(C++ member), 319

Espressif Systems

2087

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_mesh_state_change_scene_recall_etsp_ble_mesh_state_change_sensor_status_t

(C++ class), 319

(C++ class), 357

esp_ble_mesh_state_change_scene_recall_ets:p:_sbcleen_em_ensuhm_bsetrate_change_sensor_status_t::ambien

(C++ member), 319

(C++ member), 358

esp_ble_mesh_state_change_scene_store_tesp_ble_mesh_state_change_sensor_status_t::occupa

(C++ class), 319

(C++ member), 358

esp_ble_mesh_state_change_scene_store_te:s:ps_cbelnee__mneusmhb_esrtate_change_sensor_status_t::proper

(C++ member), 319

(C++ member), 358

esp_ble_mesh_state_change_scheduler_acte_sspe_tb_lte_mesh_state_change_sensor_status_t::set_oc

(C++ class), 319

(C++ member), 358

esp_ble_mesh_state_change_scheduler_acte_sspe_tb_lte:_:maecsthi_osntate_change_sensor_status_t::state

(C++ member), 320

(C++ member), 358

esp_ble_mesh_state_change_scheduler_acte_sspe_tb_lte:_:mdeasyh_state_change_tai_utc_delta_set_t

(C++ member), 319

(C++ class), 318

esp_ble_mesh_state_change_scheduler_acte_sspe_tb_lte:_:mdeasyh__osft_awteee_kchange_tai_utc_delta_set_t::ta

(C++ member), 319

(C++ member), 318

esp_ble_mesh_state_change_scheduler_acte_sspe_tb_lte:_:mheosuhr_state_change_tai_utc_delta_set_t::ta

(C++ member), 319

(C++ member), 318

esp_ble_mesh_state_change_scheduler_acte_sspe_tb_lte:_:miensdhe_xstate_change_time_role_set_t

(C++ member), 319

(C++ class), 319

esp_ble_mesh_state_change_scheduler_acte_sspe_tb_lte:_:mmeisnhu_tsetate_change_time_role_set_t::time_r

(C++ member), 319

(C++ member), 319

esp_ble_mesh_state_change_scheduler_acte_sspe_tb_lte:_:mmeosnht_hstate_change_time_set_t

(C++ member), 319

(C++ class), 317

esp_ble_mesh_state_change_scheduler_acte_sspe_tb_lte:_:msecsehn_es_tnautmeb_ecrhange_time_set_t::subsecond

(C++ member), 320

(C++ member), 318

esp_ble_mesh_state_change_scheduler_acte_sspe_tb_lte:_:mseescho_nsdtate_change_time_set_t::tai_seconds

(C++ member), 319

(C++ member), 318

esp_ble_mesh_state_change_scheduler_acte_sspe_tb_lte:_:mtersahn_ss_ttaitmee_change_time_set_t::tai_utc_del

(C++ member), 320

(C++ member), 318

esp_ble_mesh_state_change_scheduler_acte_sspe_tb_lte:_:myeesahr_state_change_time_set_t::time_author

(C++ member), 319

(C++ member), 318

esp_ble_mesh_state_change_sensor_cadencees_ps_ebtl_et_mesh_state_change_time_set_t::time_zone_o

(C++ class), 299

(C++ member), 318

esp_ble_mesh_state_change_sensor_cadencees_ps_ebtl_et_:m:efsahs_ts_tcaatdee_ncchea_nhgieg_htime_set_t::uncertainty

(C++ member), 299

(C++ member), 318

esp_ble_mesh_state_change_sensor_cadencees_ps_ebtl_et_:m:efsahs_ts_tcaatdee_ncchea_nlgoew_time_status_t

(C++ member), 299

(C++ class), 318

esp_ble_mesh_state_change_sensor_cadencees_ps_ebtl_et_:m:emsihn__sitnatteer_vcahlange_time_status_t::subsecon

(C++ member), 299

(C++ member), 318

esp_ble_mesh_state_change_sensor_cadencees_ps_ebtl_et_:m:epsehr_isotda_tdei_vcihsaonrge_time_status_t::tai_seco

(C++ member), 299

(C++ member), 318

esp_ble_mesh_state_change_sensor_cadencees_ps_ebtl_et_:m:epsrho_psetrattye__icdhange_time_status_t::tai_utc_

(C++ member), 299

(C++ member), 318

esp_ble_mesh_state_change_sensor_cadencees_ps_ebtl_et_:m:etsrhi_gsgteart_ed_eclhtaan_gdeo_wtnime_status_t::time_aut

(C++ member), 299

(C++ member), 318

esp_ble_mesh_state_change_sensor_cadencees_ps_ebtl_et_:m:etsrhi_gsgteart_ed_eclhtaan_guep_time_status_t::time_zon

(C++ member), 299

(C++ member), 318

esp_ble_mesh_state_change_sensor_cadencees_ps_ebtl_et_:m:etsrhi_gsgteart_et_ycpheange_time_status_t::uncertai

(C++ member), 299

(C++ member), 318

esp_ble_mesh_state_change_sensor_settinegs_ps_ebtl_et_mesh_state_change_time_zone_set_t

(C++ class), 299

(C++ class), 318

esp_ble_mesh_state_change_sensor_settinegs_ps_ebtl_et_:m:epsrho_psetrattye__icdhange_time_zone_set_t::tai_zo

(C++ member), 299

(C++ member), 318

esp_ble_mesh_state_change_sensor_settinegs_ps_ebtl_et_:m:esseht_tsitnagt_ep_rcohpaenrgtey__tiidme_zone_set_t::time_z

(C++ member), 299

(C++ member), 318

esp_ble_mesh_state_change_sensor_settinegs_ps_ebtl_et_:m:esseht_tsitnagt_ev_atlruaensition_t (C++

(C++ member), 299

class), 186

Espressif Systems

2088

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_mesh_state_transition_t::BLE_MEESSHP__ABTLOEM_IMCE_SDHE_FTIANMEPER_ERROR (C macro), 258

(C++ function), 186

ESP_BLE_MESH_TAMPER_WARNING (C macro),

esp_ble_mesh_state_transition_t::counter

258

(C++ member), 187

ESP_BLE_MESH_TIME_AUTHORITY (C macro),

esp_ble_mesh_state_transition_t::delay

325

(C++ member), 187

ESP_BLE_MESH_TIME_CLINET (C macro), 325

esp_ble_mesh_state_transition_t::just_sEtSaPr_tBeLdE_MESH_TIME_NONE (C macro), 325

(C++ member), 187

ESP_BLE_MESH_TIME_RELAY (C macro), 325

esp_ble_mesh_state_transition_t::quo_ttesp_ble_mesh_time_role_set_t (C++ class),

(C++ member), 187

309

esp_ble_mesh_state_transition_t::remaine_stpi_mbele_mesh_time_role_set_t::time_role

(C++ member), 187

(C++ member), 309

esp_ble_mesh_state_transition_t::start_etsipm_ebsltea_mmpesh_time_role_status_cb_t

(C++ member), 187

(C++ class), 312

esp_ble_mesh_state_transition_t::timer esp_ble_mesh_time_role_status_cb_t::time_role

(C++ member), 187

(C++ member), 312

esp_ble_mesh_state_transition_t::total_edsupr_abtlieo_nmesh_time_scene_client_cb_event_t

(C++ member), 187

(C++ enum), 326

esp_ble_mesh_state_transition_t::trans_etsipm_eble_mesh_time_scene_client_cb_param_t

(C++ member), 187

(C++ class), 313

ESP_BLE_MESH_STATIC_OOB (C++ enumerator), esp_ble_mesh_time_scene_client_cb_param_t::error_

204

(C++ member), 313

ESP_BLE_MESH_SUPPLY_VOLTAGE_TOO_HIGH_EReRsOpR_ble_mesh_time_scene_client_cb_param_t::params

(C macro), 257

(C++ member), 313

ESP_BLE_MESH_SUPPLY_VOLTAGE_TOO_HIGH_WAeRsNpI_NbGle_mesh_time_scene_client_cb_param_t::status

(C macro), 257

(C++ member), 313

ESP_BLE_MESH_SUPPLY_VOLTAGE_TOO_LOW_ERReOsRp_ble_mesh_time_scene_client_cb_t

(C macro), 257

(C++ type), 326

ESP_BLE_MESH_SUPPLY_VOLTAGE_TOO_LOW_WARENSIPN_GBLE_MESH_TIME_SCENE_CLIENT_EVT_MAX

(C macro), 257

(C++ enumerator), 326

ESP_BLE_MESH_TAI_OF_DELTA_CHANGE_LEN esp_ble_mesh_time_scene_client_get_state

(C macro), 324

(C++ function), 305

ESP_BLE_MESH_TAI_OF_ZONE_CHANGE_LEN (C ESP_BLE_MESH_TIME_SCENE_CLIENT_GET_STATE_EVT

macro), 324

(C++ enumerator), 326

ESP_BLE_MESH_TAI_SECONDS_LEN (C macro), esp_ble_mesh_time_scene_client_get_state_t

324

(C++ union), 306

ESP_BLE_MESH_TAI_UTC_DELTA_MAX_VALUE esp_ble_mesh_time_scene_client_get_state_t::sched

(C macro), 324

(C++ member), 306

esp_ble_mesh_tai_utc_delta_set_t (C++ ESP_BLE_MESH_TIME_SCENE_CLIENT_PUBLISH_EVT

class), 309

(C++ enumerator), 326

esp_ble_mesh_tai_utc_delta_set_t::paddiensgp_ble_mesh_time_scene_client_set_state

(C++ member), 309

(C++ function), 306

esp_ble_mesh_tai_utc_delta_set_t::tai_dEeSlPt_aB_LcEh_aMnEgSeH_TIME_SCENE_CLIENT_SET_STATE_EVT

(C++ member), 309

(C++ enumerator), 326

esp_ble_mesh_tai_utc_delta_set_t::tai_uetscp__dbellet_am_ensehw_time_scene_client_set_state_t

(C++ member), 309

(C++ union), 306

esp_ble_mesh_tai_utc_delta_status_cb_t esp_ble_mesh_time_scene_client_set_state_t::scene

(C++ class), 311

(C++ member), 306

esp_ble_mesh_tai_utc_delta_status_cb_t:e:sppa_dbdlien_gm_e1sh_time_scene_client_set_state_t::scene

(C++ member), 311

(C++ member), 306

esp_ble_mesh_tai_utc_delta_status_cb_t:e:sppa_dbdlien_gm_e2sh_time_scene_client_set_state_t::scene

(C++ member), 312

(C++ member), 306

esp_ble_mesh_tai_utc_delta_status_cb_t:e:stpa_ib_ldee_lmteas_hc_htainmgee_scene_client_set_state_t::sched

(C++ member), 312

(C++ member), 306

esp_ble_mesh_tai_utc_delta_status_cb_t:e:stpa_ib_luet_cm_edsehl_ttai_mceu_rsrcene_client_set_state_t::tai_u

(C++ member), 311

(C++ member), 306

esp_ble_mesh_tai_utc_delta_status_cb_t:e:stpa_ib_luet_cm_edsehl_ttai_mnee_wscene_client_set_state_t::time_

(C++ member), 312

(C++ member), 306

Espressif Systems

2089

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_ble_mesh_time_scene_client_set_statees_pt_:b:ltei_mmee_sshe_ttime_scene_server_recv_set_msg_t

(C++ member), 306

(C++ union), 308

esp_ble_mesh_time_scene_client_set_statees_pt_:b:ltei_mmee_szho_ntei_msee_tscene_server_recv_set_msg_t::sc

(C++ member), 306

(C++ member), 308

esp_ble_mesh_time_scene_client_status_cebs_pt_ble_mesh_time_scene_server_recv_set_msg_t::sc

(C++ union), 307

(C++ member), 308

esp_ble_mesh_time_scene_client_status_cebs_pt_:b:lsec_emnees_hr_etgiimset_esrc_esntea_tsuesrver_recv_set_msg_t::sc

(C++ member), 307

(C++ member), 308

esp_ble_mesh_time_scene_client_status_cebs_pt_:b:lsec_emnees_hs_ttaitmues_scene_server_recv_set_msg_t::sc

(C++ member), 307

(C++ member), 308

esp_ble_mesh_time_scene_client_status_cebs_pt_:b:lsec_hmeedsuhl_etri_maec_ts_csetnaet_usserver_recv_set_msg_t::ta

(C++ member), 307

(C++ member), 308

esp_ble_mesh_time_scene_client_status_cebs_pt_:b:lsec_hmeedsuhl_etri_mset_astcuesne_server_recv_set_msg_t::ti

(C++ member), 307

(C++ member), 308

esp_ble_mesh_time_scene_client_status_cebs_pt_:b:ltea_im_eusthc__tdiemlet_as_csetnaet_usserver_recv_set_msg_t::ti

(C++ member), 307

(C++ member), 308

esp_ble_mesh_time_scene_client_status_cebs_pt_:b:ltei_mmee_srho_ltei_mset_astcuesne_server_recv_set_msg_t::ti

(C++ member), 307

(C++ member), 308

esp_ble_mesh_time_scene_client_status_cEbS_Pt_:B:LtEi_mMeE_SsHt_aTtIuMsE_SCENE_SERVER_RECV_STATUS_MSG_EV

(C++ member), 307

(C++ enumerator), 326

esp_ble_mesh_time_scene_client_status_cebs_pt_:b:ltei_mmee_szho_ntei_mset_astcuesne_server_recv_status_msg_t

(C++ member), 307

(C++ union), 308

ESP_BLE_MESH_TIME_SCENE_CLIENT_TIMEOUT_eEsVpT_ble_mesh_time_scene_server_recv_status_msg_t:

(C++ enumerator), 326

(C++ member), 308

esp_ble_mesh_time_scene_message_opcode_EtSP_BLE_MESH_TIME_SCENE_SERVER_STATE_CHANGE_EVT

(C++ type), 203

(C++ enumerator), 326

esp_ble_mesh_time_scene_server_cb_evente_stp_ble_mesh_time_scene_server_state_change_t

(C++ enum), 326

(C++ union), 307

esp_ble_mesh_time_scene_server_cb_parame_stp_ble_mesh_time_scene_server_state_change_t::sc

(C++ class), 322

(C++ member), 307

esp_ble_mesh_time_scene_server_cb_parame_stp:_:bcltex_mesh_time_scene_server_state_change_t::sc

(C++ member), 322

(C++ member), 307

esp_ble_mesh_time_scene_server_cb_parame_stp:_:bmloed_emlesh_time_scene_server_state_change_t::sc

(C++ member), 322

(C++ member), 307

esp_ble_mesh_time_scene_server_cb_parame_stp:_:bvlael_umeesh_time_scene_server_state_change_t::sc

(C++ member), 322

(C++ member), 307

esp_ble_mesh_time_scene_server_cb_t esp_ble_mesh_time_scene_server_state_change_t::ta

(C++ type), 326

(C++ member), 307

esp_ble_mesh_time_scene_server_cb_valuee_stp_ble_mesh_time_scene_server_state_change_t::ti

(C++ union), 308

(C++ member), 307

esp_ble_mesh_time_scene_server_cb_valuee_stp:_:bgleet_mesh_time_scene_server_state_change_t::ti

(C++ member), 308

(C++ member), 307

esp_ble_mesh_time_scene_server_cb_valuee_stp:_:bsleet_mesh_time_scene_server_state_change_t::ti

(C++ member), 308

(C++ member), 307

esp_ble_mesh_time_scene_server_cb_valuee_stp:_:bsltea_tmee_schh_atnigmee_scene_server_state_change_t::ti

(C++ member), 308

(C++ member), 307

esp_ble_mesh_time_scene_server_cb_valuee_stp:_:bsltea_tmuessh_time_set_t (C++ class), 309

(C++ member), 308

esp_ble_mesh_time_set_t::sub_second

ESP_BLE_MESH_TIME_SCENE_SERVER_EVT_MAX

(C++ member), 309

(C++ enumerator), 327

esp_ble_mesh_time_set_t::tai_seconds

ESP_BLE_MESH_TIME_SCENE_SERVER_RECV_GET_MSG_EV(CT++ member), 309

(C++ enumerator), 326

esp_ble_mesh_time_set_t::tai_utc_delta

esp_ble_mesh_time_scene_server_recv_get_msg_t (C++ member), 309

(C++ union), 307

esp_ble_mesh_time_set_t::time_authority

esp_ble_mesh_time_scene_server_recv_get_msg_t:(C:+s+chmeedmubleer)r, _30a9ct

(C++ member), 308

esp_ble_mesh_time_set_t::time_zone_offset

ESP_BLE_MESH_TIME_SCENE_SERVER_RECV_SET_MSG_EV(CT++ member), 309

(C++ enumerator), 326

esp_ble_mesh_time_set_t::uncertainty

Espressif Systems

2090

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 309

(C++ member), 309

esp_ble_mesh_time_setup_srv_t (C++ esp_ble_mesh_time_zone_set_t::time_zone_offset_ne

class), 314

(C++ member), 309

esp_ble_mesh_time_setup_srv_t::model esp_ble_mesh_time_zone_status_cb_t

(C++ member), 314

(C++ class), 311

esp_ble_mesh_time_setup_srv_t::rsp_ctrlesp_ble_mesh_time_zone_status_cb_t::tai_zone_chan

(C++ member), 314

(C++ member), 311

esp_ble_mesh_time_setup_srv_t::state esp_ble_mesh_time_zone_status_cb_t::time_zone_off

(C++ member), 314

(C++ member), 311

esp_ble_mesh_time_srv_t (C++ class), 314 esp_ble_mesh_time_zone_status_cb_t::time_zone_off

esp_ble_mesh_time_srv_t::model (C++

(C++ member), 311

member), 314

ESP_BLE_MESH_TRANSMIT (C macro), 189

esp_ble_mesh_time_srv_t::rsp_ctrl

ESP_BLE_MESH_TTL_DEFAULT (C macro), 188

(C++ member), 314

ESP_BLE_MESH_TTL_MAX (C macro), 188

esp_ble_mesh_time_srv_t::state (C++ ESP_BLE_MESH_TWIST (C++ enumerator), 204

member), 314

ESP_BLE_MESH_TYPE_COMPLETE_CB (C++ enu-

esp_ble_mesh_time_state_t (C++ class), 313

merator), 204

esp_ble_mesh_time_state_t::subsecond ESP_BLE_MESH_TYPE_INTPUT_CB (C++ enumer-

(C++ member), 313

ator), 204

esp_ble_mesh_time_state_t::tai_delta_chEaSnPg_eBLE_MESH_TYPE_LINK_CLOSE_CB (C++

(C++ member), 314

enumerator), 204

esp_ble_mesh_time_state_t::tai_seconds ESP_BLE_MESH_TYPE_LINK_OPEN_CB (C++

(C++ member), 313

enumerator), 204

esp_ble_mesh_time_state_t::tai_utc_deltEaS_Pc_uBrLrE_MESH_TYPE_OUTPUT_NUM_CB (C++

(C++ member), 314

enumerator), 204

esp_ble_mesh_time_state_t::tai_utc_deltEaS_Pn_eBwLE_MESH_TYPE_OUTPUT_STR_CB (C++

(C++ member), 314

enumerator), 204

esp_ble_mesh_time_state_t::tai_zone_chaEnSgPe_BLE_MESH_TYPE_PROV_CB (C++ enumera-

(C++ member), 314

tor), 204

esp_ble_mesh_time_state_t::time (C++ ESP_BLE_MESH_TYPE_RESET_CB (C++ enumera-

member), 314

tor), 204

esp_ble_mesh_time_state_t::time_authoriEtSyP_BLE_MESH_UNKNOWN_TAI_DELTA_CHANGE

(C++ member), 314

(C macro), 324

esp_ble_mesh_time_state_t::time_role ESP_BLE_MESH_UNKNOWN_TAI_SECONDS (C

(C++ member), 314

macro), 324

esp_ble_mesh_time_state_t::time_zone_ofEfSsPe_tB_LcEu_rMrESH_UNKNOWN_TAI_ZONE_CHANGE

(C++ member), 314

(C macro), 324

esp_ble_mesh_time_state_t::time_zone_ofefsspe_tb_lnee_wmesh_unprov_dev_add_t (C++

(C++ member), 314

class), 183

esp_ble_mesh_time_state_t::uncertainty esp_ble_mesh_unprov_dev_add_t::addr

(C++ member), 313

(C++ member), 183

esp_ble_mesh_time_status_cb_t (C++ esp_ble_mesh_unprov_dev_add_t::addr_type

class), 311

(C++ member), 183

esp_ble_mesh_time_status_cb_t::sub_secoensdp_ble_mesh_unprov_dev_add_t::bearer

(C++ member), 311

(C++ member), 183

esp_ble_mesh_time_status_cb_t::tai_secoensdps_ble_mesh_unprov_dev_add_t::oob_info

(C++ member), 311

(C++ member), 183

esp_ble_mesh_time_status_cb_t::tai_utc_edsepl_tbale_mesh_unprov_dev_add_t::uuid

(C++ member), 311

(C++ member), 183

esp_ble_mesh_time_status_cb_t::time_autEhSoPr_iBtLyE_MESH_VENDOR_MODEL (C macro), 190

(C++ member), 311

ESP_BLE_MESH_VIBRATE (C++ enumerator), 204

esp_ble_mesh_time_status_cb_t::time_zonEeS_Po_fBfLsEe_tMESH_VIBRATION_ERROR (C macro),

(C++ member), 311

257

esp_ble_mesh_time_status_cb_t::uncertaiEnStPy_BLE_MESH_VIBRATION_WARNING

(C

(C++ member), 311

macro), 257

esp_ble_mesh_time_zone_set_t (C++ class), ESP_BLE_ONLY_ACCEPT_SPECIFIED_AUTH_DISABLE

309

(C macro), 95

esp_ble_mesh_time_zone_set_t::tai_zone_EcShPa_nBgLeE_ONLY_ACCEPT_SPECIFIED_AUTH_ENABLE

Espressif Systems

2091

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C macro), 95

esp_ble_remove_bond_device (C++ function),

ESP_BLE_OOB_DISABLE (C macro), 95

66

ESP_BLE_OOB_ENABLE (C macro), 95

esp_ble_resolve_adv_data (C++ function), 64

esp_ble_oob_req_reply (C++ function), 67

ESP_BLE_SCA_100PPM (C++ enumerator), 54

esp_ble_passkey_reply (C++ function), 66

ESP_BLE_SCA_150PPM (C++ enumerator), 54

esp_ble_pcsrk_keys_t (C++ class), 88

ESP_BLE_SCA_20PPM (C++ enumerator), 55

esp_ble_pcsrk_keys_t::counter (C++ ESP_BLE_SCA_250PPM (C++ enumerator), 54

member), 88

ESP_BLE_SCA_30PPM (C++ enumerator), 55

esp_ble_pcsrk_keys_t::csrk (C++ member), ESP_BLE_SCA_500PPM (C++ enumerator), 54

88

ESP_BLE_SCA_50PPM (C++ enumerator), 54

esp_ble_pcsrk_keys_t::sec_level (C++ ESP_BLE_SCA_75PPM (C++ enumerator), 54

member), 88

esp_ble_scan_dupilcate_list_flush

esp_ble_penc_keys_t (C++ class), 87

(C++ function), 52

esp_ble_penc_keys_t::ediv (C++ member), esp_ble_scan_duplicate_t (C++ enum), 103

88

esp_ble_scan_filter_t (C++ enum), 103

esp_ble_penc_keys_t::key_size (C++ ESP_BLE_SCAN_PARAM_UNDEF (C macro), 57

member), 88

esp_ble_scan_params_t (C++ class), 86

esp_ble_penc_keys_t::ltk (C++ member), 87 esp_ble_scan_params_t::own_addr_type

esp_ble_penc_keys_t::rand (C++ member),

(C++ member), 86

87

esp_ble_scan_params_t::scan_duplicate

esp_ble_penc_keys_t::sec_level (C++

(C++ member), 86

member), 88

esp_ble_scan_params_t::scan_filter_policy

esp_ble_pid_keys_t (C++ class), 88

(C++ member), 86

esp_ble_pid_keys_t::addr_type (C++ esp_ble_scan_params_t::scan_interval

member), 88

(C++ member), 86

esp_ble_pid_keys_t::irk (C++ member), 88 esp_ble_scan_params_t::scan_type (C++

esp_ble_pid_keys_t::static_addr (C++

member), 86

member), 88

esp_ble_scan_params_t::scan_window

esp_ble_pkt_data_length_params_t (C++

(C++ member), 86

class), 87

ESP_BLE_SCAN_RSP_DATA_LEN_MAX (C macro),

esp_ble_pkt_data_length_params_t::rx_len

97

(C++ member), 87

esp_ble_scan_type_t (C++ enum), 103

esp_ble_pkt_data_length_params_t::tx_leensp_ble_sec_act_t (C++ enum), 102

(C++ member), 87

ESP_BLE_SEC_ENCRYPT (C++ enumerator), 102

esp_ble_power_type_t (C++ enum), 55

ESP_BLE_SEC_ENCRYPT_MITM (C++ enumerator),

ESP_BLE_PWR_TYPE_ADV (C++ enumerator), 55

103

ESP_BLE_PWR_TYPE_CONN_HDL0 (C++ enumera- ESP_BLE_SEC_ENCRYPT_NO_MITM (C++ enumer-

tor), 55

ator), 102

ESP_BLE_PWR_TYPE_CONN_HDL1 (C++ enumera- esp_ble_sec_key_notif_t (C++ class), 89

tor), 55

esp_ble_sec_key_notif_t::bd_addr (C++

ESP_BLE_PWR_TYPE_CONN_HDL2 (C++ enumera-

member), 89

tor), 55

esp_ble_sec_key_notif_t::passkey (C++

ESP_BLE_PWR_TYPE_CONN_HDL3 (C++ enumera-

member), 89

tor), 55

esp_ble_sec_req_t (C++ class), 89

ESP_BLE_PWR_TYPE_CONN_HDL4 (C++ enumera- esp_ble_sec_req_t::bd_addr (C++ member),

tor), 55

89

ESP_BLE_PWR_TYPE_CONN_HDL5 (C++ enumera- esp_ble_sec_t (C++ union), 72

tor), 55

esp_ble_sec_t::auth_cmpl (C++ member), 72

ESP_BLE_PWR_TYPE_CONN_HDL6 (C++ enumera- esp_ble_sec_t::ble_id_keys (C++ member),

tor), 55

72

ESP_BLE_PWR_TYPE_CONN_HDL7 (C++ enumera- esp_ble_sec_t::ble_key (C++ member), 72

tor), 55

esp_ble_sec_t::ble_req (C++ member), 72

ESP_BLE_PWR_TYPE_CONN_HDL8 (C++ enumera- esp_ble_sec_t::key_notif (C++ member), 72

tor), 55

esp_ble_set_encryption (C++ function), 66

ESP_BLE_PWR_TYPE_DEFAULT (C++ enumerator), ESP_BLE_SM_AUTHEN_REQ_MODE (C++ enumera-

55

tor), 103

ESP_BLE_PWR_TYPE_NUM (C++ enumerator), 55 ESP_BLE_SM_CLEAR_STATIC_PASSKEY (C++

ESP_BLE_PWR_TYPE_SCAN (C++ enumerator), 55

enumerator), 103

Espressif Systems

2092

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

ESP_BLE_SM_IOCAP_MODE (C++ enumerator), 103 esp_blufi_cb_param_t::blufi_connect_evt_param::co

ESP_BLE_SM_MAX_KEY_SIZE (C++ enumerator),

(C++ member), 147

103

esp_blufi_cb_param_t::blufi_connect_evt_param::re

ESP_BLE_SM_MAX_PARAM (C++ enumerator), 103

(C++ member), 147

ESP_BLE_SM_MIN_KEY_SIZE (C++ enumerator), esp_blufi_cb_param_t::blufi_connect_evt_param::se

103

(C++ member), 147

ESP_BLE_SM_ONLY_ACCEPT_SPECIFIED_SEC_AUeTsHp_blufi_cb_param_t::blufi_deinit_finish_evt_par

(C++ enumerator), 103

(C++ class), 147

ESP_BLE_SM_OOB_SUPPORT (C++ enumerator), esp_blufi_cb_param_t::blufi_deinit_finish_evt_par

103

(C++ member), 147

esp_ble_sm_param_t (C++ enum), 103

esp_blufi_cb_param_t::blufi_disconnect_evt_param

ESP_BLE_SM_PASSKEY (C++ enumerator), 103

(C++ class), 147

ESP_BLE_SM_SET_INIT_KEY (C++ enumerator), esp_blufi_cb_param_t::blufi_disconnect_evt_param:

103

(C++ member), 147

ESP_BLE_SM_SET_RSP_KEY (C++ enumerator), esp_blufi_cb_param_t::blufi_get_error_evt_param

103

(C++ class), 147

ESP_BLE_SM_SET_STATIC_PASSKEY (C++ enu- esp_blufi_cb_param_t::blufi_get_error_evt_param::

merator), 103

(C++ member), 147

esp_ble_tx_power_get (C++ function), 49

esp_blufi_cb_param_t::blufi_init_finish_evt_param

esp_ble_tx_power_set (C++ function), 49

(C++ class), 147

ESP_BLE_WHITELIST_ADD (C++ enumerator), 104 esp_blufi_cb_param_t::blufi_init_finish_evt_param

ESP_BLE_WHITELIST_REMOVE (C++ enumerator),

(C++ member), 147

104

esp_blufi_cb_param_t::blufi_recv_ca_evt_param

esp_ble_wl_addr_type_t (C++ enum), 59

(C++ class), 147

esp_ble_wl_opration_t (C++ enum), 104

esp_blufi_cb_param_t::blufi_recv_ca_evt_param::ce

esp_bluedroid_deinit (C++ function), 60

(C++ member), 147

esp_bluedroid_disable (C++ function), 60

esp_blufi_cb_param_t::blufi_recv_ca_evt_param::ce

esp_bluedroid_enable (C++ function), 60

(C++ member), 147

esp_bluedroid_get_status (C++ function), 60 esp_blufi_cb_param_t::blufi_recv_client_cert_evt_

esp_bluedroid_init (C++ function), 60

(C++ class), 147

ESP_BLUEDROID_STATUS_CHECK (C macro), 57 esp_blufi_cb_param_t::blufi_recv_client_cert_evt_

ESP_BLUEDROID_STATUS_ENABLED (C++ enu-

(C++ member), 148

merator), 60

esp_blufi_cb_param_t::blufi_recv_client_cert_evt_

ESP_BLUEDROID_STATUS_INITIALIZED (C++

(C++ member), 148

enumerator), 60

esp_blufi_cb_param_t::blufi_recv_client_pkey_evt_

esp_bluedroid_status_t (C++ enum), 60

(C++ class), 148

ESP_BLUEDROID_STATUS_UNINITIALIZED

esp_blufi_cb_param_t::blufi_recv_client_pkey_evt_

(C++ enumerator), 60

(C++ member), 148

esp_blufi_ap_record_t (C++ class), 151

esp_blufi_cb_param_t::blufi_recv_client_pkey_evt_

esp_blufi_ap_record_t::rssi (C++ mem-

(C++ member), 148

ber), 151

esp_blufi_cb_param_t::blufi_recv_custom_data_evt_

esp_blufi_ap_record_t::ssid (C++ mem-

(C++ class), 148

ber), 151

esp_blufi_cb_param_t::blufi_recv_custom_data_evt_

esp_blufi_callbacks_t (C++ class), 151

(C++ member), 148

esp_blufi_callbacks_t::checksum_func esp_blufi_cb_param_t::blufi_recv_custom_data_evt_

(C++ member), 151

(C++ member), 148

esp_blufi_callbacks_t::decrypt_func esp_blufi_cb_param_t::blufi_recv_server_cert_evt_

(C++ member), 151

(C++ class), 148

esp_blufi_callbacks_t::encrypt_func esp_blufi_cb_param_t::blufi_recv_server_cert_evt_

(C++ member), 151

(C++ member), 148

esp_blufi_callbacks_t::event_cb (C++ esp_blufi_cb_param_t::blufi_recv_server_cert_evt_

member), 151

(C++ member), 148

esp_blufi_callbacks_t::negotiate_data_heasnpd_lbelrufi_cb_param_t::blufi_recv_server_pkey_evt_

(C++ member), 151

(C++ class), 148

esp_blufi_cb_event_t (C++ enum), 152

esp_blufi_cb_param_t::blufi_recv_server_pkey_evt_

esp_blufi_cb_param_t (C++ union), 145

(C++ member), 148

esp_blufi_cb_param_t::blufi_connect_evte_sppa_rbalmufi_cb_param_t::blufi_recv_server_pkey_evt_

(C++ class), 146

(C++ member), 148

Espressif Systems

2093

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_blufi_cb_param_t::blufi_recv_softape_sapu_tbhl_umfoid_ec_be_vpta_rpaamr_atm::custom_data

(C++ class), 148

(C++ member), 146

esp_blufi_cb_param_t::blufi_recv_softape_sapu_tbhl_umfoid_ec_be_vpta_rpaamr_atm::::daeuitnhi_tm_ofdienish

(C++ member), 149

(C++ member), 146

esp_blufi_cb_param_t::blufi_recv_softape_scph_abnlnuefli__ecvbt__ppaarraamm_t::disconnect (C++

(C++ class), 149

member), 146

esp_blufi_cb_param_t::blufi_recv_softape_scph_abnlnuefli__ecvbt__ppaarraamm_:t::c:hianninte_lfinish

(C++ member), 149

(C++ member), 146

esp_blufi_cb_param_t::blufi_recv_softape_smpa_xb_lcuofnin__cnbu_mp_aervatm__pta:r:armeport_error

(C++ class), 149

(C++ member), 146

esp_blufi_cb_param_t::blufi_recv_softape_smpa_xb_lcuofnin__cnbu_mp_aervatm__pta:r:asme:r:vmearx__cceorntn_num

(C++ member), 149

(C++ member), 146

esp_blufi_cb_param_t::blufi_recv_softape_sppa_sbslwudf_ie_vctb__ppaarraamm_t::server_pkey

(C++ class), 149

(C++ member), 146

esp_blufi_cb_param_t::blufi_recv_softape_sppa_sbslwudf_ie_vctb__ppaarraamm:_:tp:a:sssowfdtap_auth_mode

(C++ member), 149

(C++ member), 146

esp_blufi_cb_param_t::blufi_recv_softape_sppa_sbslwudf_ie_vctb__ppaarraamm:_:tp:a:sssowfdt_alpe_nchannel

(C++ member), 149

(C++ member), 146

esp_blufi_cb_param_t::blufi_recv_softape_ssps_ibdl_uefvit__cpba_rpaamram_t::softap_max_conn_num

(C++ class), 149

(C++ member), 146

esp_blufi_cb_param_t::blufi_recv_softape_ssps_ibdl_uefvit__cpba_rpaamr:a:ms_sti:d:softap_passwd

(C++ member), 149

(C++ member), 146

esp_blufi_cb_param_t::blufi_recv_softape_ssps_ibdl_uefvit__cpba_rpaamr:a:ms_sti:d:_sloefntap_ssid

(C++ member), 149

(C++ member), 146

esp_blufi_cb_param_t::blufi_recv_sta_bsessipd__belvutf_ip_acrba_mparam_t::sta_bssid (C++

(C++ class), 149

member), 146

esp_blufi_cb_param_t::blufi_recv_sta_bsessipd__belvutf_ip_acrba_mp:a:rbasms_itd::sta_passwd (C++

(C++ member), 149

member), 146

esp_blufi_cb_param_t::blufi_recv_sta_paessspw_db_leuvfti__pcabr_apmaram_t::sta_ssid (C++

(C++ class), 149

member), 146

esp_blufi_cb_param_t::blufi_recv_sta_paessspw_db_leuvfti__pcabr_apma:r:apma_sts:w:dusername (C++

(C++ member), 150

member), 146

esp_blufi_cb_param_t::blufi_recv_sta_paessspw_db_leuvfti__pcabr_apma:r:apma_sts:w:dw_ilfein_mode (C++

(C++ member), 150

member), 146

esp_blufi_cb_param_t::blufi_recv_sta_ssEiSdP__eBvLtU_FpIa_rCaHmECKSUM_ERROR (C++ enumerator),

(C++ class), 150

154

esp_blufi_cb_param_t::blufi_recv_sta_sseisdp__ebvltu_fpia_rcahme:c:ksssuimd_func_t (C++ type), 152

(C++ member), 150

ESP_BLUFI_DATA_FORMAT_ERROR (C++ enumer-

esp_blufi_cb_param_t::blufi_recv_sta_ssid_evt_aptoar)r, a1m54::ssid_len

(C++ member), 150

ESP_BLUFI_DECRYPT_ERROR (C++ enumerator),

esp_blufi_cb_param_t::blufi_recv_username_evt_1p54aram

(C++ class), 150

esp_blufi_decrypt_func_t (C++ type), 152

esp_blufi_cb_param_t::blufi_recv_usernaEmSeP__eBvLtU_FpIa_rDaEmI:N:InTa_mFeAILED (C++ enumerator),

(C++ member), 150

153

esp_blufi_cb_param_t::blufi_recv_usernaEmSeP__eBvLtU_FpIa_rDaEmI:N:InTa_mOeK_(lCe+n+ enumerator), 153

(C++ member), 150

esp_blufi_deinit_state_t (C++ enum), 153

esp_blufi_cb_param_t::blufi_set_wifi_moEdSeP__eBvLtU_FpIa_rDaHm_MALLOC_ERROR (C++ enumera-

(C++ class), 150

tor), 154

esp_blufi_cb_param_t::blufi_set_wifi_moEdSeP__eBvLtU_FpIa_rDaHm_:P:AoRpA_Mm_oEdReROR (C++ enumerator),

(C++ member), 150

154

esp_blufi_cb_param_t::ca (C++ member), ESP_BLUFI_ENCRYPT_ERROR (C++ enumerator),

146

154

esp_blufi_cb_param_t::client_cert

esp_blufi_encrypt_func_t (C++ type), 152

(C++ member), 146

esp_blufi_error_state_t (C++ enum), 153

esp_blufi_cb_param_t::client_pkey

ESP_BLUFI_EVENT_BLE_CONNECT (C++ enumer-

(C++ member), 146

ator), 153

esp_blufi_cb_param_t::connect (C++ ESP_BLUFI_EVENT_BLE_DISCONNECT (C++

member), 146

enumerator), 153

Espressif Systems

2094

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_blufi_event_cb_t (C++ type), 152

esp_blufi_extra_info_t::softap_channel_set

ESP_BLUFI_EVENT_DEAUTHENTICATE_STA

(C++ member), 151

(C++ enumerator), 153

esp_blufi_extra_info_t::softap_max_conn_num

ESP_BLUFI_EVENT_DEINIT_FINISH (C++ enu-

(C++ member), 151

merator), 152

esp_blufi_extra_info_t::softap_max_conn_num_set

ESP_BLUFI_EVENT_GET_WIFI_LIST (C++ enu-

(C++ member), 151

merator), 153

esp_blufi_extra_info_t::softap_passwd

ESP_BLUFI_EVENT_GET_WIFI_STATUS (C++

(C++ member), 151

enumerator), 153

esp_blufi_extra_info_t::softap_passwd_len

ESP_BLUFI_EVENT_INIT_FINISH (C++ enumer-

(C++ member), 151

ator), 152

esp_blufi_extra_info_t::softap_ssid

ESP_BLUFI_EVENT_RECV_CA_CERT (C++ enu-

(C++ member), 151

merator), 153

esp_blufi_extra_info_t::softap_ssid_len

ESP_BLUFI_EVENT_RECV_CLIENT_CERT (C++

(C++ member), 151

enumerator), 153

esp_blufi_extra_info_t::sta_bssid

ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY

(C++ member), 150

(C++ enumerator), 153

esp_blufi_extra_info_t::sta_bssid_set

ESP_BLUFI_EVENT_RECV_CUSTOM_DATA (C++

(C++ member), 150

enumerator), 153

esp_blufi_extra_info_t::sta_passwd

ESP_BLUFI_EVENT_RECV_SERVER_CERT (C++

(C++ member), 150

enumerator), 153

esp_blufi_extra_info_t::sta_passwd_len

ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY

(C++ member), 150

(C++ enumerator), 153

esp_blufi_extra_info_t::sta_ssid (C++

ESP_BLUFI_EVENT_RECV_SLAVE_DISCONNECT_BLE

member), 150

(C++ enumerator), 153

esp_blufi_extra_info_t::sta_ssid_len

ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE

(C++ member), 150

(C++ enumerator), 153

esp_blufi_get_version (C++ function), 145

ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL ESP_BLUFI_INIT_FAILED (C++ enumerator), 153

(C++ enumerator), 153

ESP_BLUFI_INIT_OK (C++ enumerator), 153

ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUEMSP_BLUFI_INIT_SECURITY_ERROR (C++ enu-

(C++ enumerator), 153

merator), 154

ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD

esp_blufi_init_state_t (C++ enum), 153

(C++ enumerator), 153

ESP_BLUFI_MAKE_PUBLIC_ERROR (C++ enumer-

ESP_BLUFI_EVENT_RECV_SOFTAP_SSID (C++

ator), 154

enumerator), 153

esp_blufi_negotiate_data_handler_t

ESP_BLUFI_EVENT_RECV_STA_BSSID (C++

(C++ type), 152

enumerator), 153

esp_blufi_profile_deinit (C++ function),

ESP_BLUFI_EVENT_RECV_STA_PASSWD (C++

145

enumerator), 153

esp_blufi_profile_init (C++ function), 145

ESP_BLUFI_EVENT_RECV_STA_SSID (C++ enu- ESP_BLUFI_READ_PARAM_ERROR (C++ enumera-

merator), 153

tor), 154

ESP_BLUFI_EVENT_RECV_USERNAME (C++ enu- esp_blufi_register_callbacks (C++ func-

merator), 153

tion), 145

ESP_BLUFI_EVENT_REPORT_ERROR (C++ enu- esp_blufi_send_custom_data (C++ function),

merator), 153

145

ESP_BLUFI_EVENT_REQ_CONNECT_TO_AP

esp_blufi_send_error_info (C++ function),

(C++ enumerator), 153

145

ESP_BLUFI_EVENT_REQ_DISCONNECT_FROM_AP esp_blufi_send_wifi_conn_report (C++

(C++ enumerator), 153

function), 145

ESP_BLUFI_EVENT_SET_WIFI_OPMODE (C++ esp_blufi_send_wifi_list (C++ function),

enumerator), 152

145

esp_blufi_extra_info_t (C++ class), 150

ESP_BLUFI_SEQUENCE_ERROR (C++ enumerator),

esp_blufi_extra_info_t::softap_authmode

154

(C++ member), 151

ESP_BLUFI_STA_CONN_FAIL (C++ enumerator),

esp_blufi_extra_info_t::softap_authmode_set 153

(C++ member), 151

esp_blufi_sta_conn_state_t (C++ enum),

esp_blufi_extra_info_t::softap_channel

153

(C++ member), 151

ESP_BLUFI_STA_CONN_SUCCESS (C++ enumera-

Espressif Systems

2095

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

tor), 153

esp_bt_controller_init (C++ function), 50

esp_bredr_sco_datapath_set (C++ function), esp_bt_controller_mem_release (C++ func-

50

tion), 51

esp_bredr_tx_power_get (C++ function), 50 ESP_BT_CONTROLLER_STATUS_ENABLED (C++

esp_bredr_tx_power_set (C++ function), 49

enumerator), 55

ESP_BT_CONTROLLER_CONFIG_MAGIC_VAL (C ESP_BT_CONTROLLER_STATUS_IDLE (C++ enu-

macro), 54

merator), 55

esp_bt_controller_config_t (C++ class), 53 ESP_BT_CONTROLLER_STATUS_INITED (C++

esp_bt_controller_config_t::auto_latency

enumerator), 55

(C++ member), 53

ESP_BT_CONTROLLER_STATUS_NUM (C++ enu-

esp_bt_controller_config_t::ble_max_conn

merator), 55

(C++ member), 53

esp_bt_controller_status_t (C++ enum), 55

esp_bt_controller_config_t::ble_sca esp_bt_dev_get_address (C++ function), 61

(C++ member), 53

esp_bt_dev_set_device_name (C++ function),

esp_bt_controller_config_t::bt_legacy_auth_vs_6e1vt

(C++ member), 53

esp_bt_dev_type_t (C++ enum), 59

esp_bt_controller_config_t::bt_max_acl_EcSoPn_nBT_DEVICE_TYPE_BLE (C++ enumerator), 59

(C++ member), 53

ESP_BT_DEVICE_TYPE_BREDR (C++ enumerator),

esp_bt_controller_config_t::bt_max_sync_conn 59

(C++ member), 53

ESP_BT_DEVICE_TYPE_DUMO (C++ enumerator),

esp_bt_controller_config_t::bt_sco_datapath 59

(C++ member), 53

esp_bt_duplicate_exceptional_subcode_type_t

esp_bt_controller_config_t::controller_debug_f(Cl+a+g enum), 105

(C++ member), 53

esp_bt_mem_release (C++ function), 51

esp_bt_controller_config_t::controller_EtSaPs_kB_Tp_rMiOoDE_BLE (C++ enumerator), 54

(C++ member), 53

ESP_BT_MODE_BTDM (C++ enumerator), 54

esp_bt_controller_config_t::controller_EtSaPs_kB_Ts_tMaOcDkE__sCiLzAeSSIC_BT (C++ enumerator), 54

(C++ member), 53

ESP_BT_MODE_IDLE (C++ enumerator), 54

esp_bt_controller_config_t::hci_uart_baeusdpr_abtte_mode_t (C++ enum), 54

(C++ member), 53

ESP_BT_OCTET16_LEN (C macro), 57

esp_bt_controller_config_t::hci_uart_noesp_bt_octet16_t (C++ type), 58

(C++ member), 53

ESP_BT_OCTET8_LEN (C macro), 57

esp_bt_controller_config_t::hli (C++ esp_bt_octet8_t (C++ type), 58

member), 53

esp_bt_sleep_disable (C++ function), 52

esp_bt_controller_config_t::magic

esp_bt_sleep_enable (C++ function), 52

(C++ member), 54

ESP_BT_STATUS_AUTH_FAILURE (C++ enumera-

esp_bt_controller_config_t::mesh_adv_size

tor), 58

(C++ member), 53

ESP_BT_STATUS_AUTH_REJECTED (C++ enumer-

esp_bt_controller_config_t::mode (C++

ator), 59

member), 53

ESP_BT_STATUS_BUSY (C++ enumerator), 58

esp_bt_controller_config_t::normal_adv_EsSiPz_eBT_STATUS_CONTROL_LE_DATA_LEN_UNSUPPORTED

(C++ member), 53

(C++ enumerator), 59

esp_bt_controller_config_t::pcm_polar ESP_BT_STATUS_DONE (C++ enumerator), 58

(C++ member), 53

ESP_BT_STATUS_EIR_TOO_LARGE (C++ enumer-

esp_bt_controller_config_t::pcm_role

ator), 59

(C++ member), 53

ESP_BT_STATUS_ERR_ILLEGAL_PARAMETER_FMT

esp_bt_controller_config_t::scan_duplicate_mod(Ce++ enumerator), 59

(C++ member), 53

ESP_BT_STATUS_FAIL (C++ enumerator), 58

esp_bt_controller_config_t::scan_duplicEaStPe__BtTy_pSeTATUS_INVALID_STATIC_RAND_ADDR

(C++ member), 53

(C++ enumerator), 59

esp_bt_controller_config_t::send_adv_reEsSePr_vBeTd__SsTiAzTeUS_MEMORY_FULL (C++ enumera-

(C++ member), 53

tor), 59

esp_bt_controller_deinit (C++ function), 50 ESP_BT_STATUS_NOMEM (C++ enumerator), 58

esp_bt_controller_disable (C++ function), ESP_BT_STATUS_NOT_READY (C++ enumerator),

50

58

esp_bt_controller_enable (C++ function), 50 ESP_BT_STATUS_PARAM_OUT_OF_RANGE (C++

esp_bt_controller_get_status (C++ func-

enumerator), 59

tion), 50

ESP_BT_STATUS_PARM_INVALID (C++ enumera-

Espressif Systems

2096

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

tor), 58

class), 1099

ESP_BT_STATUS_PEER_LE_DATA_LEN_UNSUPPOReTsEpD_console_dev_uart_config_t::baud_rate

(C++ enumerator), 59

(C++ member), 1099

ESP_BT_STATUS_PENDING (C++ enumerator), 59 esp_console_dev_uart_config_t::channel

ESP_BT_STATUS_RMT_DEV_DOWN (C++ enumera-

(C++ member), 1099

tor), 59

esp_console_dev_uart_config_t::rx_gpio_num

ESP_BT_STATUS_SUCCESS (C++ enumerator), 58

(C++ member), 1099

esp_bt_status_t (C++ enum), 58

esp_console_dev_uart_config_t::tx_gpio_num

ESP_BT_STATUS_TIMEOUT (C++ enumerator), 59

(C++ member), 1099

ESP_BT_STATUS_UNACCEPT_CONN_INTERVAL esp_console_dev_usb_cdc_config_t (C++

(C++ enumerator), 59

class), 1099

ESP_BT_STATUS_UNHANDLED (C++ enumerator), esp_console_get_completion (C++ function),

58

1097

ESP_BT_STATUS_UNSUPPORTED (C++ enumera- esp_console_get_hint (C++ function), 1097

tor), 58

esp_console_init (C++ function), 1096

esp_bt_uuid_t (C++ class), 57

esp_console_new_repl_uart (C++ function),

esp_bt_uuid_t::len (C++ member), 57

1097

esp_bt_uuid_t::uuid (C++ member), 57

esp_console_new_repl_usb_cdc (C++ func-

esp_bt_uuid_t::uuid128 (C++ member), 57

tion), 1098

esp_bt_uuid_t::uuid16 (C++ member), 57

esp_console_register_help_command

esp_bt_uuid_t::uuid32 (C++ member), 57

(C++ function), 1097

ESP_CHIP_ID_ESP32 (C++ enumerator), 1084

ESP_CONSOLE_REPL_CONFIG_DEFAULT

(C

ESP_CHIP_ID_ESP32C2 (C++ enumerator), 1084

macro), 1100

ESP_CHIP_ID_ESP32C3 (C++ enumerator), 1084 esp_console_repl_config_t (C++ class),

ESP_CHIP_ID_ESP32S2 (C++ enumerator), 1084

1099

ESP_CHIP_ID_ESP32S3 (C++ enumerator), 1084 esp_console_repl_config_t::history_save_path

ESP_CHIP_ID_INVALID (C++ enumerator), 1084

(C++ member), 1099

esp_chip_id_t (C++ enum), 1084

esp_console_repl_config_t::max_cmdline_length

esp_console_cmd_func_t (C++ type), 1100

(C++ member), 1099

esp_console_cmd_register (C++ function), esp_console_repl_config_t::max_history_len

1096

(C++ member), 1099

esp_console_cmd_t (C++ class), 1099

esp_console_repl_config_t::prompt

esp_console_cmd_t::argtable (C++ mem-

(C++ member), 1099

ber), 1100

esp_console_repl_config_t::task_priority

esp_console_cmd_t::command (C++ member),

(C++ member), 1099

1099

esp_console_repl_config_t::task_stack_size

esp_console_cmd_t::func (C++ member),

(C++ member), 1099

1100

esp_console_repl_s (C++ class), 1100

esp_console_cmd_t::help (C++ member), esp_console_repl_s::del (C++ member),

1099

1100

esp_console_cmd_t::hint (C++ member), esp_console_repl_t (C++ type), 1100

1099

esp_console_run (C++ function), 1096

ESP_CONSOLE_CONFIG_DEFAULT (C macro), 1100 esp_console_split_argv (C++ function), 1097

esp_console_config_t (C++ class), 1098

esp_console_start_repl (C++ function), 1098

esp_console_config_t::hint_bold (C++ esp_crt_bundle_attach (C++ function), 958

member), 1099

esp_crt_bundle_detach (C++ function), 958

esp_console_config_t::hint_color (C++ esp_crt_bundle_set (C++ function), 958

member), 1098

esp_deep_sleep (C++ function), 1346

esp_console_config_t::max_cmdline_args esp_deep_sleep_disable_rom_logging

(C++ member), 1098

(C++ function), 1347

esp_console_config_t::max_cmdline_lengtehsp_deep_sleep_start (C++ function), 1346

(C++ member), 1098

esp_deep_sleep_wake_stub_fn_t (C++

esp_console_deinit (C++ function), 1096

type), 1347

ESP_CONSOLE_DEV_CDC_CONFIG_DEFAULT (C ESP_DEFAULT_GATT_IF (C macro), 57

macro), 1100

esp_default_wake_deep_sleep (C++ func-

ESP_CONSOLE_DEV_UART_CONFIG_DEFAULT (C

tion), 1347

macro), 1100

esp_deregister_freertos_idle_hook

esp_console_dev_uart_config_t (C++

(C++ function), 1266

Espressif Systems

2097

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_deregister_freertos_idle_hook_for_cepsup_efuse_check_secure_version (C++

(C++ function), 1266

function), 1114

esp_deregister_freertos_tick_hook

esp_efuse_count_unused_key_blocks

(C++ function), 1267

(C++ function), 1118

esp_deregister_freertos_tick_hook_for_cepsup_efuse_desc_t (C++ class), 1119

(C++ function), 1267

esp_efuse_desc_t::bit_count (C++ mem-

esp_derive_local_mac (C++ function), 1317

ber), 1119

esp_digital_signature_data (C++ class), esp_efuse_desc_t::bit_start (C++ mem-

557

ber), 1119

esp_digital_signature_data::c (C++ esp_efuse_desc_t::efuse_block (C++

member), 558

member), 1119

esp_digital_signature_data::iv (C++ esp_efuse_disable_rom_download_mode

member), 558

(C++ function), 1114

esp_digital_signature_data::rsa_length esp_efuse_enable_rom_secure_download_mode

(C++ member), 557

(C++ function), 1114

esp_digital_signature_length_t (C++ esp_efuse_find_purpose (C++ function), 1117

enum), 559

esp_efuse_find_unused_key_block (C++

ESP_DRAM_LOGD (C macro), 1311

function), 1118

ESP_DRAM_LOGE (C macro), 1310

esp_efuse_get_chip_ver (C++ function), 1113

ESP_DRAM_LOGI (C macro), 1311

esp_efuse_get_coding_scheme (C++ func-

ESP_DRAM_LOGV (C macro), 1311

tion), 1113

ESP_DRAM_LOGW (C macro), 1311

esp_efuse_get_digest_revoke (C++ func-

ESP_DS_C_LEN (C macro), 558

tion), 1118

esp_ds_context_t (C++ type), 558

esp_efuse_get_field_size (C++ function),

esp_ds_data_t (C++ type), 558

1112

esp_ds_encrypt_params (C++ function), 557 esp_efuse_get_key (C++ function), 1117

esp_ds_finish_sign (C++ function), 557

esp_efuse_get_key_dis_read (C++ function),

esp_ds_is_busy (C++ function), 557

1116

ESP_DS_IV_LEN (C macro), 558

esp_efuse_get_key_dis_write (C++ func-

esp_ds_p_data_t (C++ class), 558

tion), 1116

esp_ds_p_data_t::length (C++ member), 558 esp_efuse_get_key_purpose (C++ function),

esp_ds_p_data_t::M (C++ member), 558

1117

esp_ds_p_data_t::M_prime (C++ member), esp_efuse_get_keypurpose_dis_write

558

(C++ function), 1117

esp_ds_p_data_t::Rb (C++ member), 558

esp_efuse_get_pkg_ver (C++ function), 1114

esp_ds_p_data_t::Y (C++ member), 558

esp_efuse_get_purpose_field (C++ func-

ESP_DS_RSA_1024 (C++ enumerator), 559

tion), 1117

ESP_DS_RSA_2048 (C++ enumerator), 559

esp_efuse_get_write_protect_of_digest_revoke

ESP_DS_RSA_3072 (C++ enumerator), 559

(C++ function), 1118

ESP_DS_RSA_4096 (C++ enumerator), 559

esp_efuse_key_block_unused (C++ function),

esp_ds_sign (C++ function), 556

1116

esp_ds_start_sign (C++ function), 556

esp_efuse_mac_get_custom (C++ function),

esp_duplicate_info_t (C++ type), 98

1317

esp_duplicate_scan_exceptional_list_typees_pt_efuse_mac_get_default (C++ function),

(C++ enum), 105

1317

ESP_EARLY_LOGD (C macro), 1310

esp_efuse_read_block (C++ function), 1113

ESP_EARLY_LOGE (C macro), 1310

esp_efuse_read_field_bit (C++ function),

ESP_EARLY_LOGI (C macro), 1310

1111

ESP_EARLY_LOGV (C macro), 1310

esp_efuse_read_field_blob (C++ function),

ESP_EARLY_LOGW (C macro), 1310

1111

esp_efuse_batch_write_begin (C++ func- esp_efuse_read_field_cnt (C++ function),

tion), 1115

1111

esp_efuse_batch_write_cancel (C++ func- esp_efuse_read_reg (C++ function), 1112

tion), 1115

esp_efuse_read_secure_version (C++ func-

esp_efuse_batch_write_commit (C++ func-

tion), 1114

tion), 1116

esp_efuse_reset (C++ function), 1114

esp_efuse_block_is_empty (C++ function), ESP_EFUSE_ROM_LOG_ALWAYS_OFF (C++ enu-

1116

merator), 1120

Espressif Systems

2098

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

ESP_EFUSE_ROM_LOG_ALWAYS_ON (C++ enumer- ESP_ERR_HTTP_CONNECT (C macro), 861

ator), 1120

ESP_ERR_HTTP_CONNECTING (C macro), 862

ESP_EFUSE_ROM_LOG_ON_GPIO_HIGH (C++ ESP_ERR_HTTP_CONNECTION_CLOSED

(C

enumerator), 1120

macro), 862

ESP_EFUSE_ROM_LOG_ON_GPIO_LOW (C++ enu- ESP_ERR_HTTP_EAGAIN (C macro), 862

merator), 1120

ESP_ERR_HTTP_FETCH_HEADER (C macro), 861

esp_efuse_rom_log_scheme_t (C++ enum), ESP_ERR_HTTP_INVALID_TRANSPORT

(C

1120

macro), 862

esp_efuse_set_digest_revoke (C++ func- ESP_ERR_HTTP_MAX_REDIRECT (C macro), 861

tion), 1118

ESP_ERR_HTTP_WRITE_DATA (C macro), 861

esp_efuse_set_key_dis_read (C++ function), ESP_ERR_HTTPD_ALLOC_MEM (C macro), 883

1116

ESP_ERR_HTTPD_BASE (C macro), 883

esp_efuse_set_key_dis_write (C++ func- ESP_ERR_HTTPD_HANDLER_EXISTS (C macro),

tion), 1116

883

esp_efuse_set_key_purpose (C++ function), ESP_ERR_HTTPD_HANDLERS_FULL (C macro),

1117

883

esp_efuse_set_keypurpose_dis_write

ESP_ERR_HTTPD_INVALID_REQ (C macro), 883

(C++ function), 1117

ESP_ERR_HTTPD_RESP_HDR (C macro), 883

esp_efuse_set_read_protect (C++ function), ESP_ERR_HTTPD_RESP_SEND (C macro), 883

1112

ESP_ERR_HTTPD_RESULT_TRUNC (C macro), 883

esp_efuse_set_rom_log_scheme (C++ func- ESP_ERR_HTTPD_TASK (C macro), 883

tion), 1114

ESP_ERR_HTTPS_OTA_BASE (C macro), 1125

esp_efuse_set_write_protect (C++ func- ESP_ERR_HTTPS_OTA_IN_PROGRESS (C macro),

tion), 1112

1125

esp_efuse_set_write_protect_of_digest_rEeSvPo_kEeRR_HW_CRYPTO_BASE (C macro), 1121

(C++ function), 1118

ESP_ERR_INVALID_ARG (C macro), 1121

esp_efuse_update_secure_version (C++ ESP_ERR_INVALID_CRC (C macro), 1121

function), 1115

ESP_ERR_INVALID_MAC (C macro), 1121

esp_efuse_write_block (C++ function), 1113 ESP_ERR_INVALID_RESPONSE (C macro), 1121

esp_efuse_write_field_bit (C++ function), ESP_ERR_INVALID_SIZE (C macro), 1121

1112

ESP_ERR_INVALID_STATE (C macro), 1121

esp_efuse_write_field_blob (C++ function), ESP_ERR_INVALID_VERSION (C macro), 1121

1111

ESP_ERR_MEMPROT_BASE (C macro), 1122

esp_efuse_write_field_cnt (C++ function), ESP_ERR_MESH_ARGUMENT (C macro), 444

1111

ESP_ERR_MESH_BASE (C macro), 1121

esp_efuse_write_key (C++ function), 1118

ESP_ERR_MESH_DISCARD (C macro), 445

esp_efuse_write_keys (C++ function), 1119 ESP_ERR_MESH_DISCARD_DUPLICATE

(C

esp_efuse_write_reg (C++ function), 1113

macro), 445

ESP_ERR_CODING (C macro), 1120

ESP_ERR_MESH_DISCONNECTED (C macro), 444

ESP_ERR_DAMAGED_READING (C macro), 1120

ESP_ERR_MESH_EXCEED_MTU (C macro), 444

ESP_ERR_DPP_FAILURE (C macro), 451

ESP_ERR_MESH_INTERFACE (C macro), 444

ESP_ERR_DPP_INVALID_ATTR (C macro), 451

ESP_ERR_MESH_NO_MEMORY (C macro), 444

ESP_ERR_DPP_TX_FAILURE (C macro), 451

ESP_ERR_MESH_NO_PARENT_FOUND (C macro),

ESP_ERR_EFUSE (C macro), 1119

444

ESP_ERR_EFUSE_CNT_IS_FULL (C macro), 1120 ESP_ERR_MESH_NO_ROUTE_FOUND (C macro),

ESP_ERR_EFUSE_REPEATED_PROG (C macro),

444

1120

ESP_ERR_MESH_NOT_ALLOWED (C macro), 444

ESP_ERR_ESPNOW_ARG (C macro), 416

ESP_ERR_MESH_NOT_CONFIG (C macro), 444

ESP_ERR_ESPNOW_BASE (C macro), 416

ESP_ERR_MESH_NOT_INIT (C macro), 444

ESP_ERR_ESPNOW_EXIST (C macro), 416

ESP_ERR_MESH_NOT_START (C macro), 444

ESP_ERR_ESPNOW_FULL (C macro), 416

ESP_ERR_MESH_NOT_SUPPORT (C macro), 444

ESP_ERR_ESPNOW_IF (C macro), 416

ESP_ERR_MESH_OPTION_NULL (C macro), 444

ESP_ERR_ESPNOW_INTERNAL (C macro), 416

ESP_ERR_MESH_OPTION_UNKNOWN (C macro),

ESP_ERR_ESPNOW_NO_MEM (C macro), 416

444

ESP_ERR_ESPNOW_NOT_FOUND (C macro), 416

ESP_ERR_MESH_PS (C macro), 445

ESP_ERR_ESPNOW_NOT_INIT (C macro), 416

ESP_ERR_MESH_QUEUE_FAIL (C macro), 444

ESP_ERR_FLASH_BASE (C macro), 1121

ESP_ERR_MESH_QUEUE_FULL (C macro), 444

ESP_ERR_HTTP_BASE (C macro), 861

ESP_ERR_MESH_QUEUE_READ (C macro), 445

Espressif Systems

2099

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

ESP_ERR_MESH_RECV_RELEASE (C macro), 445

ESP_ERR_MESH_TIMEOUT (C macro), 444

ESP_ERR_MESH_VOTING (C macro), 445

ESP_ERR_MESH_WIFI_NOT_START (C macro),

444

ESP_ERR_MESH_XMIT (C macro), 445

ESP_ERR_MESH_XON_NO_WINDOW (C macro), 444

ESP_ERR_NO_MEM (C macro), 1121

ESP_ERR_NOT_ENOUGH_UNUSED_KEY_BLOCKS

(C macro), 1120

ESP_ERR_NOT_FINISHED (C macro), 1121

ESP_ERR_NOT_FOUND (C macro), 1121

ESP_ERR_NOT_SUPPORTED (C macro), 1121

ESP_ERR_NVS_BASE (C macro), 1016

ESP_ERR_NVS_CONTENT_DIFFERS (C macro),

1017

ESP_ERR_NVS_CORRUPT_KEY_PART (C macro),

1017

ESP_ERR_NVS_ENCR_NOT_SUPPORTED

(C

macro), 1017

ESP_ERR_NVS_INVALID_HANDLE (C macro), 1017

ESP_ERR_NVS_INVALID_LENGTH (C macro), 1017

ESP_ERR_NVS_INVALID_NAME (C macro), 1016

ESP_ERR_NVS_INVALID_STATE (C macro), 1017

ESP_ERR_NVS_KEY_TOO_LONG (C macro), 1017

ESP_ERR_NVS_KEYS_NOT_INITIALIZED (C

macro), 1017

ESP_ERR_NVS_NEW_VERSION_FOUND (C macro),

1017

ESP_ERR_NVS_NO_FREE_PAGES (C macro), 1017

ESP_ERR_NVS_NOT_ENOUGH_SPACE (C macro),

1016

ESP_ERR_NVS_NOT_FOUND (C macro), 1016

ESP_ERR_NVS_NOT_INITIALIZED (C macro),

1016

ESP_ERR_NVS_PAGE_FULL (C macro), 1017

ESP_ERR_NVS_PART_NOT_FOUND (C macro), 1017

ESP_ERR_NVS_READ_ONLY (C macro), 1016

ESP_ERR_NVS_REMOVE_FAILED (C macro), 1017

ESP_ERR_NVS_TYPE_MISMATCH (C macro), 1016

ESP_ERR_NVS_VALUE_TOO_LONG (C macro), 1017

ESP_ERR_NVS_WRONG_ENCRYPTION (C macro),

1017

ESP_ERR_NVS_XTS_CFG_FAILED (C macro), 1017

ESP_ERR_NVS_XTS_CFG_NOT_FOUND (C macro),

1017

ESP_ERR_NVS_XTS_DECR_FAILED (C macro),

1017

ESP_ERR_NVS_XTS_ENCR_FAILED (C macro),

1017

ESP_ERR_OTA_BASE (C macro), 1327

ESP_ERR_OTA_PARTITION_CONFLICT

(C

macro), 1327

ESP_ERR_OTA_ROLLBACK_FAILED (C macro),

1328

ESP_ERR_OTA_ROLLBACK_INVALID_STATE (C

macro), 1328

ESP_ERR_OTA_SELECT_INFO_INVALID

(C

macro), 1327

ESP_ERR_OTA_SMALL_SEC_VER (C macro), 1328

ESP_ERR_OTA_VALIDATE_FAILED (C macro),

1327

esp_err_t (C++ type), 1122

ESP_ERR_TIMEOUT (C macro), 1121

esp_err_to_name (C++ function), 1120

esp_err_to_name_r (C++ function), 1120

ESP_ERR_ULP_BASE (C macro), 1893

ESP_ERR_ULP_BRANCH_OUT_OF_RANGE

(C

macro), 1893

ESP_ERR_ULP_DUPLICATE_LABEL (C macro),

1893

ESP_ERR_ULP_INVALID_LOAD_ADDR (C macro),

1893

ESP_ERR_ULP_SIZE_TOO_BIG (C macro), 1893

ESP_ERR_ULP_UNDEFINED_LABEL (C macro),

1893

ESP_ERR_WIFI_BASE (C macro), 1121

ESP_ERR_WIFI_CONN (C macro), 384

ESP_ERR_WIFI_IF (C macro), 384

ESP_ERR_WIFI_INIT_STATE (C macro), 385

ESP_ERR_WIFI_MAC (C macro), 384

ESP_ERR_WIFI_MODE (C macro), 384

ESP_ERR_WIFI_NOT_ASSOC (C macro), 385

ESP_ERR_WIFI_NOT_CONNECT (C macro), 385

ESP_ERR_WIFI_NOT_INIT (C macro), 384

ESP_ERR_WIFI_NOT_STARTED (C macro), 384

ESP_ERR_WIFI_NOT_STOPPED (C macro), 384

ESP_ERR_WIFI_NVS (C macro), 384

ESP_ERR_WIFI_PASSWORD (C macro), 384

ESP_ERR_WIFI_POST (C macro), 385

ESP_ERR_WIFI_SSID (C macro), 384

ESP_ERR_WIFI_STATE (C macro), 384

ESP_ERR_WIFI_STOP_STATE (C macro), 385

ESP_ERR_WIFI_TIMEOUT (C macro), 384

ESP_ERR_WIFI_TX_DISALLOW (C macro), 385

ESP_ERR_WIFI_WAKE_FAIL (C macro), 384

ESP_ERR_WIFI_WOULD_BLOCK (C macro), 384

ESP_ERROR_CHECK (C macro), 1122

ESP_ERROR_CHECK_WITHOUT_ABORT (C macro),

1122

esp_esptouch_set_timeout (C++ function),

408

esp_eth_config_t (C++ class), 461

esp_eth_config_t::check_link_period_ms

(C++ member), 461

esp_eth_config_t::mac (C++ member), 461

esp_eth_config_t::on_lowlevel_deinit_done

(C++ member), 461

esp_eth_config_t::on_lowlevel_init_done

(C++ member), 461

esp_eth_config_t::phy (C++ member), 461

esp_eth_config_t::read_phy_reg (C++

member), 461

esp_eth_config_t::stack_input (C++

member), 461

Espressif Systems

2100

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_eth_config_t::write_phy_reg (C++ member), 462
esp_eth_decrease_reference (C++ function), 460
esp_eth_del_netif_glue (C++ function), 474 esp_eth_detect_phy_addr (C++ function), 463 esp_eth_driver_install (C++ function), 458 esp_eth_driver_uninstall (C++ function),
458 esp_eth_handle_t (C++ type), 462 esp_eth_increase_reference (C++ function),
460 esp_eth_io_cmd_t (C++ enum), 462 esp_eth_ioctl (C++ function), 459 esp_eth_mac_s (C++ class), 465 esp_eth_mac_s::deinit (C++ member), 465 esp_eth_mac_s::del (C++ member), 468 esp_eth_mac_s::enable_flow_ctrl (C++
member), 468 esp_eth_mac_s::get_addr (C++ member), 467 esp_eth_mac_s::init (C++ member), 465 esp_eth_mac_s::read_phy_reg (C++ mem-
ber), 466 esp_eth_mac_s::receive (C++ member), 466 esp_eth_mac_s::set_addr (C++ member), 467 esp_eth_mac_s::set_duplex (C++ member),
467 esp_eth_mac_s::set_link (C++ member), 468 esp_eth_mac_s::set_mediator (C++ mem-
ber), 465 esp_eth_mac_s::set_peer_pause_ability
(C++ member), 468 esp_eth_mac_s::set_promiscuous (C++
member), 468 esp_eth_mac_s::set_speed (C++ member),
467 esp_eth_mac_s::start (C++ member), 466 esp_eth_mac_s::stop (C++ member), 466 esp_eth_mac_s::transmit (C++ member), 466 esp_eth_mac_s::write_phy_reg (C++ mem-
ber), 467 esp_eth_mac_t (C++ type), 469 esp_eth_mediator_s (C++ class), 463 esp_eth_mediator_s::on_state_changed
(C++ member), 464 esp_eth_mediator_s::phy_reg_read (C++
member), 463 esp_eth_mediator_s::phy_reg_write
(C++ member), 463 esp_eth_mediator_s::stack_input (C++
member), 464 esp_eth_mediator_t (C++ type), 464 esp_eth_netif_glue_handle_t (C++ type),
474 esp_eth_new_netif_glue (C++ function), 474 ESP_ETH_PHY_ADDR_AUTO (C macro), 473 ESP_ETH_PHY_AUTONEGO_DIS (C++ enumerator),
474

ESP_ETH_PHY_AUTONEGO_EN (C++ enumerator), 474
ESP_ETH_PHY_AUTONEGO_G_STAT (C++ enumerator), 474
ESP_ETH_PHY_AUTONEGO_RESTART (C++ enumerator), 474
esp_eth_phy_new_dp83848 (C++ function), 470 esp_eth_phy_new_ip101 (C++ function), 470 esp_eth_phy_new_ksz80xx (C++ function), 470 esp_eth_phy_new_lan87xx (C++ function), 470 esp_eth_phy_new_rtl8201 (C++ function), 470 esp_eth_phy_s (C++ class), 471 esp_eth_phy_s::advertise_pause_ability
(C++ member), 472 esp_eth_phy_s::autonego_ctrl (C++ mem-
ber), 471 esp_eth_phy_s::deinit (C++ member), 471 esp_eth_phy_s::del (C++ member), 473 esp_eth_phy_s::get_addr (C++ member), 472 esp_eth_phy_s::get_link (C++ member), 472 esp_eth_phy_s::init (C++ member), 471 esp_eth_phy_s::loopback (C++ member), 472 esp_eth_phy_s::pwrctl (C++ member), 472 esp_eth_phy_s::reset (C++ member), 471 esp_eth_phy_s::reset_hw (C++ member), 471 esp_eth_phy_s::set_addr (C++ member), 472 esp_eth_phy_s::set_duplex (C++ member),
473 esp_eth_phy_s::set_mediator (C++ mem-
ber), 471 esp_eth_phy_s::set_speed (C++ member),
473 esp_eth_phy_t (C++ type), 474 esp_eth_receive (C++ function), 459 esp_eth_start (C++ function), 458 esp_eth_state_t (C++ enum), 464 esp_eth_stop (C++ function), 459 esp_eth_transmit (C++ function), 459 esp_eth_update_input_path (C++ function),
459 ESP_EVENT_ANY_BASE (C macro), 1141 ESP_EVENT_ANY_ID (C macro), 1141 ESP_EVENT_DECLARE_BASE (C macro), 1141 ESP_EVENT_DEFINE_BASE (C macro), 1141 esp_event_dump (C++ function), 1139 esp_event_handler_instance_register
(C++ function), 1136 esp_event_handler_instance_register_with
(C++ function), 1135 esp_event_handler_instance_t (C++ type),
1141 esp_event_handler_instance_unregister
(C++ function), 1138 esp_event_handler_instance_unregister_with
(C++ function), 1137 esp_event_handler_register (C++ function),
1134 esp_event_handler_register_with (C++

Espressif Systems

2101

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

function), 1135

(C++ function), 1043

esp_event_handler_t (C++ type), 1141

ESP_FLASH_ENC_MODE_DEVELOPMENT (C++

esp_event_handler_unregister (C++ func-

enumerator), 1060

tion), 1136

ESP_FLASH_ENC_MODE_DISABLED (C++ enumer-

esp_event_handler_unregister_with

ator), 1060

(C++ function), 1137

ESP_FLASH_ENC_MODE_RELEASE (C++ enumera-

esp_event_isr_post (C++ function), 1139

tor), 1060

esp_event_isr_post_to (C++ function), 1139 esp_flash_enc_mode_t (C++ enum), 1060

esp_event_loop_args_t (C++ class), 1140

esp_flash_encrypt_check_and_update

esp_event_loop_args_t::queue_size

(C++ function), 1059

(C++ member), 1140

esp_flash_encrypt_region (C++ function),

esp_event_loop_args_t::task_core_id

1059

(C++ member), 1140

esp_flash_encryption_enable_secure_features

esp_event_loop_args_t::task_name (C++

(C++ function), 1060

member), 1140

esp_flash_encryption_enabled (C++ func-

esp_event_loop_args_t::task_priority

tion), 1059

(C++ member), 1140

esp_flash_encryption_init_checks (C++

esp_event_loop_args_t::task_stack_size

function), 1059

(C++ member), 1140

esp_flash_encryption_set_release_mode

esp_event_loop_create (C++ function), 1133

(C++ function), 1060

esp_event_loop_create_default (C++ func- esp_flash_erase_chip (C++ function), 1043

tion), 1134

esp_flash_erase_region (C++ function), 1043

esp_event_loop_delete (C++ function), 1134 esp_flash_get_chip_write_protect (C++

esp_event_loop_delete_default (C++ func-

function), 1044

tion), 1134

esp_flash_get_protectable_regions

esp_event_loop_handle_t (C++ type), 1141

(C++ function), 1044

esp_event_loop_init (C++ function), 1142

esp_flash_get_protected_region (C++

esp_event_loop_run (C++ function), 1134

function), 1044

esp_event_loop_set_cb (C++ function), 1142 esp_flash_get_size (C++ function), 1043

esp_event_post (C++ function), 1138

esp_flash_init (C++ function), 1042

esp_event_post_to (C++ function), 1138

esp_flash_io_mode_t (C++ enum), 1052

esp_event_process_default (C++ function), esp_flash_is_quad_mode (C++ function), 1046

1142

esp_flash_os_functions_t (C++ class), 1046

esp_event_send (C++ function), 1141

esp_flash_os_functions_t::check_yield

esp_event_send_internal (C++ function),

(C++ member), 1047

1141

esp_flash_os_functions_t::delay_us

esp_event_set_default_eth_handlers

(C++ member), 1047

(C++ function), 1142

esp_flash_os_functions_t::end (C++

esp_event_set_default_wifi_handlers

member), 1046

(C++ function), 1142

esp_flash_os_functions_t::get_system_time

ESP_EXECUTE_EXPRESSION_WITH_STACK (C

(C++ member), 1047

macro), 1300

esp_flash_os_functions_t::get_temp_buffer

esp_execute_shared_stack_function

(C++ member), 1047

(C++ function), 1299

esp_flash_os_functions_t::region_protected

ESP_EXT1_WAKEUP_ALL_LOW (C++ enumerator),

(C++ member), 1047

1347

esp_flash_os_functions_t::release_temp_buffer

ESP_EXT1_WAKEUP_ANY_HIGH (C++ enumerator),

(C++ member), 1047

1347

esp_flash_os_functions_t::start (C++

ESP_FAIL (C macro), 1121

member), 1046

esp_fill_random (C++ function), 1339

esp_flash_os_functions_t::yield (C++

ESP_FLASH_10MHZ (C++ enumerator), 1051

member), 1047

ESP_FLASH_120MHZ (C++ enumerator), 1052

esp_flash_read (C++ function), 1045

ESP_FLASH_20MHZ (C++ enumerator), 1051

esp_flash_read_encrypted (C++ function),

ESP_FLASH_26MHZ (C++ enumerator), 1051

1046

ESP_FLASH_40MHZ (C++ enumerator), 1052

esp_flash_read_id (C++ function), 1043

ESP_FLASH_5MHZ (C++ enumerator), 1051

esp_flash_read_unique_chip_id (C++ func-

ESP_FLASH_80MHZ (C++ enumerator), 1052

tion), 1043

esp_flash_chip_driver_initialized

esp_flash_region_t (C++ class), 1046

Espressif Systems

2102

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_flash_region_t::offset (C++ member),

tor), 99

1046

esp_gap_ble_cb_event_t (C++ enum), 99

esp_flash_region_t::size (C++ member), esp_gap_ble_cb_t (C++ type), 99

1046

ESP_GAP_BLE_CHANNEL_SELETE_ALGORITHM_EVT

esp_flash_set_chip_write_protect (C++

(C++ enumerator), 101

function), 1044

esp_gap_ble_channels (C++ type), 98

esp_flash_set_protected_region (C++ ESP_GAP_BLE_CHANNELS_LEN (C macro), 97

function), 1045

ESP_GAP_BLE_CLEAR_BOND_DEV_COMPLETE_EVT

ESP_FLASH_SPEED_MAX (C++ enumerator), 1052

(C++ enumerator), 100

ESP_FLASH_SPEED_MIN (C macro), 1051

ESP_GAP_BLE_EVT_MAX (C++ enumerator), 101

esp_flash_speed_t (C++ enum), 1051

ESP_GAP_BLE_EXT_ADV_DATA_SET_COMPLETE_EVT

esp_flash_spi_device_config_t (C++

(C++ enumerator), 100

class), 1042

ESP_GAP_BLE_EXT_ADV_REPORT_EVT (C++

esp_flash_spi_device_config_t::cs_id

enumerator), 101

(C++ member), 1042

ESP_GAP_BLE_EXT_ADV_SET_CLEAR_COMPLETE_EVT

esp_flash_spi_device_config_t::cs_io_num

(C++ enumerator), 100

(C++ member), 1042

ESP_GAP_BLE_EXT_ADV_SET_PARAMS_COMPLETE_EVT

esp_flash_spi_device_config_t::host_id

(C++ enumerator), 100

(C++ member), 1042

ESP_GAP_BLE_EXT_ADV_SET_RAND_ADDR_COMPLETE_EVT

esp_flash_spi_device_config_t::input_delay_ns (C++ enumerator), 100

(C++ member), 1042

ESP_GAP_BLE_EXT_ADV_SET_REMOVE_COMPLETE_EVT

esp_flash_spi_device_config_t::io_mode

(C++ enumerator), 100

(C++ member), 1042

ESP_GAP_BLE_EXT_ADV_START_COMPLETE_EVT

esp_flash_spi_device_config_t::speed

(C++ enumerator), 100

(C++ member), 1042

ESP_GAP_BLE_EXT_ADV_STOP_COMPLETE_EVT

esp_flash_t (C++ class), 1047

(C++ enumerator), 100

esp_flash_t (C++ type), 1048

ESP_GAP_BLE_EXT_SCAN_RSP_DATA_SET_COMPLETE_EVT

esp_flash_t::busy (C++ member), 1047

(C++ enumerator), 100

esp_flash_t::chip_drv (C++ member), 1047 ESP_GAP_BLE_EXT_SCAN_START_COMPLETE_EVT

esp_flash_t::chip_id (C++ member), 1047

(C++ enumerator), 101

esp_flash_t::host (C++ member), 1047

ESP_GAP_BLE_EXT_SCAN_STOP_COMPLETE_EVT

esp_flash_t::os_func (C++ member), 1047

(C++ enumerator), 101

esp_flash_t::os_func_data (C++ member), ESP_GAP_BLE_GET_BOND_DEV_COMPLETE_EVT

1047

(C++ enumerator), 100

esp_flash_t::read_mode (C++ member), 1047 ESP_GAP_BLE_KEY_EVT (C++ enumerator), 99

esp_flash_t::reserved_flags (C++ mem- ESP_GAP_BLE_LOCAL_ER_EVT (C++ enumerator),

ber), 1047

99

esp_flash_t::size (C++ member), 1047

ESP_GAP_BLE_LOCAL_IR_EVT (C++ enumerator),

esp_flash_write (C++ function), 1045

99

esp_flash_write_encrypted (C++ function), ESP_GAP_BLE_NC_REQ_EVT (C++ enumerator), 99

1045

ESP_GAP_BLE_OOB_REQ_EVT (C++ enumerator),

esp_flash_write_protect_crypt_cnt

99

(C++ function), 1059

ESP_GAP_BLE_PASSKEY_NOTIF_EVT (C++ enu-

esp_freertos_idle_cb_t (C++ type), 1267

merator), 99

esp_freertos_tick_cb_t (C++ type), 1267

ESP_GAP_BLE_PASSKEY_REQ_EVT (C++ enumer-

ESP_GAP_BLE_ADD_WHITELIST_COMPLETE_EVT

ator), 99

(C macro), 97

ESP_GAP_BLE_PERIODIC_ADV_ADD_DEV_COMPLETE_EVT

ESP_GAP_BLE_ADV_DATA_RAW_SET_COMPLETE_EVT

(C++ enumerator), 100

(C++ enumerator), 99

ESP_GAP_BLE_PERIODIC_ADV_CLEAR_DEV_COMPLETE_EVT

ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT

(C++ enumerator), 100

(C++ enumerator), 99

ESP_GAP_BLE_PERIODIC_ADV_CREATE_SYNC_COMPLETE_EVT

ESP_GAP_BLE_ADV_START_COMPLETE_EVT

(C++ enumerator), 100

(C++ enumerator), 99

ESP_GAP_BLE_PERIODIC_ADV_DATA_SET_COMPLETE_EVT

ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT

(C++ enumerator), 100

(C++ enumerator), 99

ESP_GAP_BLE_PERIODIC_ADV_REMOVE_DEV_COMPLETE_EVT

ESP_GAP_BLE_ADV_TERMINATED_EVT (C++

(C++ enumerator), 100

enumerator), 101

ESP_GAP_BLE_PERIODIC_ADV_REPORT_EVT

ESP_GAP_BLE_AUTH_CMPL_EVT (C++ enumera-

(C++ enumerator), 101

Espressif Systems

2103

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

ESP_GAP_BLE_PERIODIC_ADV_SET_PARAMS_COMPLETE_E(CV+T+ enumerator), 100

(C++ enumerator), 100

ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT

ESP_GAP_BLE_PERIODIC_ADV_START_COMPLETE_EVT (C++ enumerator), 100

(C++ enumerator), 100

ESP_GAP_BLE_UPDATE_DUPLICATE_EXCEPTIONAL_LIST_COM

ESP_GAP_BLE_PERIODIC_ADV_STOP_COMPLETE_EVT (C++ enumerator), 100

(C++ enumerator), 100

ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT

ESP_GAP_BLE_PERIODIC_ADV_SYNC_CANCEL_COMPLETE_(CE+V+T enumerator), 100

(C++ enumerator), 100

esp_gap_conn_params_t (C++ class), 87

ESP_GAP_BLE_PERIODIC_ADV_SYNC_ESTAB_EVTesp_gap_conn_params_t::interval (C++

(C++ enumerator), 101

member), 87

ESP_GAP_BLE_PERIODIC_ADV_SYNC_LOST_EVT esp_gap_conn_params_t::latency (C++

(C++ enumerator), 101

member), 87

ESP_GAP_BLE_PERIODIC_ADV_SYNC_TERMINATEe_sCpO_MgPaLpE_TcEo_nEnV_Tparams_t::timeout (C++

(C++ enumerator), 100

member), 87

ESP_GAP_BLE_PHY_UPDATE_COMPLETE_EVT ESP_GAP_SEARCH_DI_DISC_CMPL_EVT (C++

(C++ enumerator), 101

enumerator), 104

ESP_GAP_BLE_PREFER_EXT_CONN_PARAMS_SET_ECSOPM_PGLAEPT_ES_EEAVRTCH_DISC_BLE_RES_EVT (C++

(C++ enumerator), 101

enumerator), 104

ESP_GAP_BLE_READ_PHY_COMPLETE_EVT

ESP_GAP_SEARCH_DISC_CMPL_EVT (C++ enu-

(C++ enumerator), 100

merator), 104

ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT

ESP_GAP_SEARCH_DISC_RES_EVT (C++ enumer-

(C++ enumerator), 100

ator), 104

ESP_GAP_BLE_REMOVE_BOND_DEV_COMPLETE_EVeTsp_gap_search_evt_t (C++ enum), 104

(C++ enumerator), 100

ESP_GAP_SEARCH_INQ_CMPL_EVT (C++ enumer-

ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT

ator), 104

(C++ enumerator), 99

ESP_GAP_SEARCH_INQ_DISCARD_NUM_EVT

ESP_GAP_BLE_SCAN_REQ_RECEIVED_EVT

(C++ enumerator), 104

(C++ enumerator), 101

ESP_GAP_SEARCH_INQ_RES_EVT (C++ enumera-

ESP_GAP_BLE_SCAN_RESULT_EVT (C++ enumer-

tor), 104

ator), 99

ESP_GAP_SEARCH_SEARCH_CANCEL_CMPL_EVT

ESP_GAP_BLE_SCAN_RSP_DATA_RAW_SET_COMPLETE_EVT(C++ enumerator), 104

(C++ enumerator), 99

ESP_GATT_ALREADY_OPEN (C++ enumerator), 114

ESP_GAP_BLE_SCAN_RSP_DATA_SET_COMPLETE_EESVPT_GATT_APP_RSP (C++ enumerator), 114

(C++ enumerator), 99

ESP_GATT_ATTR_HANDLE_MAX (C macro), 112

ESP_GAP_BLE_SCAN_START_COMPLETE_EVT ESP_GATT_AUTH_FAIL (C++ enumerator), 114

(C++ enumerator), 99

ESP_GATT_AUTH_REQ_MITM (C++ enumerator),

ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT

115

(C++ enumerator), 99

ESP_GATT_AUTH_REQ_NO_MITM (C++ enumera-

ESP_GAP_BLE_SCAN_TIMEOUT_EVT (C++ enu-

tor), 115

merator), 101

ESP_GATT_AUTH_REQ_NONE (C++ enumerator),

ESP_GAP_BLE_SEC_REQ_EVT (C++ enumerator),

115

99

ESP_GATT_AUTH_REQ_SIGNED_MITM (C++ enu-

esp_gap_ble_set_authorization (C++ func-

merator), 115

tion), 67

ESP_GATT_AUTH_REQ_SIGNED_NO_MITM (C++

esp_gap_ble_set_channels (C++ function), 67

enumerator), 115

ESP_GAP_BLE_SET_CHANNELS_EVT (C++ enu- esp_gatt_auth_req_t (C++ enum), 115

merator), 100

ESP_GATT_AUTO_RSP (C macro), 113

ESP_GAP_BLE_SET_EXT_SCAN_PARAMS_COMPLETEES_PE_VGTATT_BODY_SENSOR_LOCATION (C macro),

(C++ enumerator), 101

112

ESP_GAP_BLE_SET_LOCAL_PRIVACY_COMPLETE_EESVPT_GATT_BUSY (C++ enumerator), 114

(C++ enumerator), 100

ESP_GATT_CANCEL (C++ enumerator), 114

ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVTESP_GATT_CCC_CFG_ERR (C++ enumerator), 114

(C++ enumerator), 100

ESP_GATT_CHAR_PROP_BIT_AUTH (C macro),

ESP_GAP_BLE_SET_PREFERED_DEFAULT_PHY_COMPLETE_1E13VT

(C++ enumerator), 100

ESP_GATT_CHAR_PROP_BIT_BROADCAST (C

ESP_GAP_BLE_SET_PREFERED_PHY_COMPLETE_EVT

macro), 113

(C++ enumerator), 100

ESP_GATT_CHAR_PROP_BIT_EXT_PROP

(C

ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT

macro), 113

Espressif Systems

2104

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

ESP_GATT_CHAR_PROP_BIT_INDICATE

(C

macro), 113

ESP_GATT_CHAR_PROP_BIT_NOTIFY (C macro),

113

ESP_GATT_CHAR_PROP_BIT_READ (C macro),

113

ESP_GATT_CHAR_PROP_BIT_WRITE (C macro),

113

ESP_GATT_CHAR_PROP_BIT_WRITE_NR

(C

macro), 113

esp_gatt_char_prop_t (C++ type), 113

ESP_GATT_CMD_STARTED (C++ enumerator), 114

ESP_GATT_CONGESTED (C++ enumerator), 114

ESP_GATT_CONN_CONN_CANCEL (C++ enumera-

tor), 115

ESP_GATT_CONN_FAIL_ESTABLISH (C++ enu-

merator), 115

ESP_GATT_CONN_L2C_FAILURE (C++ enumera-

tor), 115

ESP_GATT_CONN_LMP_TIMEOUT (C++ enumera-

tor), 115

ESP_GATT_CONN_NONE (C++ enumerator), 115

esp_gatt_conn_params_t (C++ class), 108

esp_gatt_conn_params_t::interval (C++

member), 108

esp_gatt_conn_params_t::latency (C++

member), 108

esp_gatt_conn_params_t::timeout (C++

member), 108

esp_gatt_conn_reason_t (C++ enum), 115

ESP_GATT_CONN_TERMINATE_LOCAL_HOST

(C++ enumerator), 115

ESP_GATT_CONN_TERMINATE_PEER_USER

(C++ enumerator), 115

ESP_GATT_CONN_TIMEOUT (C++ enumerator), 115

ESP_GATT_CONN_UNKNOWN (C++ enumerator), 115

ESP_GATT_DB_ALL (C++ enumerator), 116

esp_gatt_db_attr_type_t (C++ enum), 115

ESP_GATT_DB_CHARACTERISTIC (C++ enumera-

tor), 116

ESP_GATT_DB_DESCRIPTOR (C++ enumerator),

116

ESP_GATT_DB_FULL (C++ enumerator), 114

ESP_GATT_DB_INCLUDED_SERVICE (C++ enu-

merator), 116

ESP_GATT_DB_PRIMARY_SERVICE (C++ enumer-

ator), 116

ESP_GATT_DB_SECONDARY_SERVICE (C++ enu-

merator), 116

ESP_GATT_DUP_REG (C++ enumerator), 114

ESP_GATT_ENCRYPED_MITM (C++ enumerator),

114

ESP_GATT_ENCRYPED_NO_MITM (C++ enumera-

tor), 114

ESP_GATT_ERR_UNLIKELY (C++ enumerator), 114

ESP_GATT_ERROR (C++ enumerator), 114

ESP_GATT_HEART_RATE_CNTL_POINT

(C

macro), 112

ESP_GATT_HEART_RATE_MEAS (C macro), 112

esp_gatt_id_t (C++ class), 106

esp_gatt_id_t::inst_id (C++ member), 106

esp_gatt_id_t::uuid (C++ member), 106

ESP_GATT_IF_NONE (C macro), 113

esp_gatt_if_t (C++ type), 113

ESP_GATT_ILLEGAL_HANDLE (C macro), 112

ESP_GATT_ILLEGAL_PARAMETER (C++ enumera-

tor), 114

ESP_GATT_ILLEGAL_UUID (C macro), 112

ESP_GATT_INSUF_AUTHENTICATION (C++ enu-

merator), 114

ESP_GATT_INSUF_AUTHORIZATION (C++ enu-

merator), 114

ESP_GATT_INSUF_ENCRYPTION (C++ enumera-

tor), 114

ESP_GATT_INSUF_KEY_SIZE (C++ enumerator),

114

ESP_GATT_INSUF_RESOURCE (C++ enumerator),

114

ESP_GATT_INTERNAL_ERROR (C++ enumerator),

114

ESP_GATT_INVALID_ATTR_LEN (C++ enumera-

tor), 114

ESP_GATT_INVALID_CFG (C++ enumerator), 114

ESP_GATT_INVALID_HANDLE (C++ enumerator),

113

ESP_GATT_INVALID_OFFSET (C++ enumerator),

114

ESP_GATT_INVALID_PDU (C++ enumerator), 114

ESP_GATT_MAX_ATTR_LEN (C macro), 113

ESP_GATT_MAX_READ_MULTI_HANDLES

(C

macro), 112

ESP_GATT_MORE (C++ enumerator), 114

ESP_GATT_NO_RESOURCES (C++ enumerator), 114

ESP_GATT_NOT_ENCRYPTED (C++ enumerator),

114

ESP_GATT_NOT_FOUND (C++ enumerator), 114

ESP_GATT_NOT_LONG (C++ enumerator), 114

ESP_GATT_OK (C++ enumerator), 113

ESP_GATT_OUT_OF_RANGE (C++ enumerator), 115

ESP_GATT_PENDING (C++ enumerator), 114

ESP_GATT_PERM_READ (C macro), 112

ESP_GATT_PERM_READ_AUTHORIZATION (C

macro), 113

ESP_GATT_PERM_READ_ENC_MITM (C macro),

112

ESP_GATT_PERM_READ_ENCRYPTED (C macro),

112

esp_gatt_perm_t (C++ type), 113

ESP_GATT_PERM_WRITE (C macro), 113

ESP_GATT_PERM_WRITE_AUTHORIZATION (C

macro), 113

ESP_GATT_PERM_WRITE_ENC_MITM (C macro),

113

ESP_GATT_PERM_WRITE_ENCRYPTED (C macro),

113

ESP_GATT_PERM_WRITE_SIGNED (C macro), 113

Espressif Systems

2105

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

ESP_GATT_PERM_WRITE_SIGNED_MITM

(C

macro), 113

ESP_GATT_PRC_IN_PROGRESS (C++ enumerator),

114

ESP_GATT_PREP_WRITE_CANCEL (C macro), 127

ESP_GATT_PREP_WRITE_CANCEL (C++ enumera-

tor), 113

ESP_GATT_PREP_WRITE_EXEC (C macro), 127

ESP_GATT_PREP_WRITE_EXEC (C++ enumerator),

113

esp_gatt_prep_write_type (C++ enum), 113

ESP_GATT_PREPARE_Q_FULL (C++ enumerator),

114

ESP_GATT_READ_NOT_PERMIT (C++ enumerator),

113

ESP_GATT_REQ_NOT_SUPPORTED (C++ enumera-

tor), 114

ESP_GATT_RSP_BY_APP (C macro), 113

esp_gatt_rsp_t (C++ union), 106

esp_gatt_rsp_t::attr_value (C++ member),

106

esp_gatt_rsp_t::handle (C++ member), 106

ESP_GATT_SERVICE_FROM_NVS_FLASH (C++

enumerator), 115

ESP_GATT_SERVICE_FROM_REMOTE_DEVICE

(C++ enumerator), 115

ESP_GATT_SERVICE_FROM_UNKNOWN (C++ enu-

merator), 115

ESP_GATT_SERVICE_STARTED (C++ enumerator),

114

esp_gatt_srvc_id_t (C++ class), 106

esp_gatt_srvc_id_t::id (C++ member), 106

esp_gatt_srvc_id_t::is_primary (C++

member), 106

ESP_GATT_STACK_RSP (C++ enumerator), 114

esp_gatt_status_t (C++ enum), 113

ESP_GATT_UNKNOWN_ERROR (C++ enumerator),

114

ESP_GATT_UNSUPPORT_GRP_TYPE (C++ enumer-

ator), 114

ESP_GATT_UUID_ALERT_LEVEL (C macro), 111

ESP_GATT_UUID_ALERT_NTF_SVC (C macro),

110

ESP_GATT_UUID_ALERT_STATUS (C macro), 111

ESP_GATT_UUID_Automation_IO_SVC

(C

macro), 110

ESP_GATT_UUID_BATTERY_LEVEL (C macro),

112

ESP_GATT_UUID_BATTERY_SERVICE_SVC (C

macro), 110

ESP_GATT_UUID_BLOOD_PRESSURE_SVC (C

macro), 110

ESP_GATT_UUID_BODY_COMPOSITION

(C

macro), 110

ESP_GATT_UUID_BOND_MANAGEMENT_SVC (C

macro), 110

ESP_GATT_UUID_CHAR_AGG_FORMAT (C macro),

111

ESP_GATT_UUID_CHAR_CLIENT_CONFIG (C

macro), 111

ESP_GATT_UUID_CHAR_DECLARE (C macro), 111

ESP_GATT_UUID_CHAR_DESCRIPTION

(C

macro), 111

ESP_GATT_UUID_CHAR_EXT_PROP (C macro),

111

ESP_GATT_UUID_CHAR_PRESENT_FORMAT (C

macro), 111

ESP_GATT_UUID_CHAR_SRVR_CONFIG

(C

macro), 111

ESP_GATT_UUID_CHAR_VALID_RANGE

(C

macro), 111

ESP_GATT_UUID_CONT_GLUCOSE_MONITOR_SVC

(C macro), 110

ESP_GATT_UUID_CSC_FEATURE (C macro), 112

ESP_GATT_UUID_CSC_MEASUREMENT (C macro),

112

ESP_GATT_UUID_CURRENT_TIME (C macro), 111

ESP_GATT_UUID_CURRENT_TIME_SVC

(C

macro), 110

ESP_GATT_UUID_CYCLING_POWER_SVC

(C

macro), 110

ESP_GATT_UUID_CYCLING_SPEED_CADENCE_SVC

(C macro), 110

ESP_GATT_UUID_DEVICE_INFO_SVC (C macro),

110

ESP_GATT_UUID_ENV_SENSING_CONFIG_DESCR

(C macro), 111

ESP_GATT_UUID_ENV_SENSING_MEASUREMENT_DESCR

(C macro), 111

ESP_GATT_UUID_ENV_SENSING_TRIGGER_DESCR

(C macro), 111

ESP_GATT_UUID_ENVIRONMENTAL_SENSING_SVC

(C macro), 110

ESP_GATT_UUID_EXT_RPT_REF_DESCR

(C

macro), 111

ESP_GATT_UUID_FW_VERSION_STR (C macro),

112

ESP_GATT_UUID_GAP_CENTRAL_ADDR_RESOL

(C macro), 111

ESP_GATT_UUID_GAP_DEVICE_NAME (C macro),

111

ESP_GATT_UUID_GAP_ICON (C macro), 111

ESP_GATT_UUID_GAP_PREF_CONN_PARAM (C

macro), 111

ESP_GATT_UUID_GATT_SRV_CHGD (C macro),

111

ESP_GATT_UUID_GLUCOSE_SVC (C macro), 110

ESP_GATT_UUID_GM_CONTEXT (C macro), 111

ESP_GATT_UUID_GM_CONTROL_POINT

(C

macro), 111

ESP_GATT_UUID_GM_FEATURE (C macro), 111

ESP_GATT_UUID_GM_MEASUREMENT (C macro),

111

ESP_GATT_UUID_HEALTH_THERMOM_SVC (C

macro), 110

ESP_GATT_UUID_HEART_RATE_SVC (C macro),

Espressif Systems

2106

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

110

macro), 112

ESP_GATT_UUID_HID_BT_KB_INPUT (C macro), ESP_GATT_UUID_SCAN_INT_WINDOW (C macro),

112

112

ESP_GATT_UUID_HID_BT_KB_OUTPUT

(C ESP_GATT_UUID_SCAN_PARAMETERS_SVC (C

macro), 112

macro), 110

ESP_GATT_UUID_HID_BT_MOUSE_INPUT (C ESP_GATT_UUID_SCAN_REFRESH (C macro), 112

macro), 112

ESP_GATT_UUID_SEC_SERVICE (C macro), 111

ESP_GATT_UUID_HID_CONTROL_POINT

(C ESP_GATT_UUID_SENSOR_LOCATION (C macro),

macro), 112

112

ESP_GATT_UUID_HID_INFORMATION (C macro), ESP_GATT_UUID_SERIAL_NUMBER_STR

(C

112

macro), 112

ESP_GATT_UUID_HID_PROTO_MODE (C macro), ESP_GATT_UUID_SW_VERSION_STR (C macro),

112

112

ESP_GATT_UUID_HID_REPORT (C macro), 112

ESP_GATT_UUID_SYSTEM_ID (C macro), 111

ESP_GATT_UUID_HID_REPORT_MAP (C macro), ESP_GATT_UUID_TIME_TRIGGER_DESCR (C

112

macro), 111

ESP_GATT_UUID_HID_SVC (C macro), 110

ESP_GATT_UUID_TX_POWER_LEVEL (C macro),

ESP_GATT_UUID_HW_VERSION_STR (C macro),

111

112

ESP_GATT_UUID_TX_POWER_SVC (C macro), 110

ESP_GATT_UUID_IEEE_DATA (C macro), 112

ESP_GATT_UUID_USER_DATA_SVC (C macro),

ESP_GATT_UUID_IMMEDIATE_ALERT_SVC (C

110

macro), 110

ESP_GATT_UUID_VALUE_TRIGGER_DESCR (C

ESP_GATT_UUID_INCLUDE_SERVICE (C macro),

macro), 111

111

ESP_GATT_UUID_WEIGHT_SCALE_SVC

(C

ESP_GATT_UUID_LINK_LOSS_SVC (C macro),

macro), 110

110

esp_gatt_value_t (C++ class), 108

ESP_GATT_UUID_LOCAL_TIME_INFO (C macro), esp_gatt_value_t::auth_req (C++ member),

111

108

ESP_GATT_UUID_LOCATION_AND_NAVIGATION_SeVsCp_gatt_value_t::handle (C++ member),

(C macro), 110

108

ESP_GATT_UUID_MANU_NAME (C macro), 112

esp_gatt_value_t::len (C++ member), 108

ESP_GATT_UUID_MODEL_NUMBER_STR

(C esp_gatt_value_t::offset (C++ member),

macro), 111

108

ESP_GATT_UUID_NEXT_DST_CHANGE_SVC (C esp_gatt_value_t::value (C++ member), 108

macro), 110

ESP_GATT_WRITE_NOT_PERMIT (C++ enumera-

ESP_GATT_UUID_NUM_DIGITALS_DESCR (C

tor), 113

macro), 111

ESP_GATT_WRITE_TYPE_NO_RSP (C++ enumera-

ESP_GATT_UUID_NW_STATUS (C macro), 111

tor), 115

ESP_GATT_UUID_NW_TRIGGER (C macro), 111

ESP_GATT_WRITE_TYPE_RSP (C++ enumerator),

ESP_GATT_UUID_PHONE_ALERT_STATUS_SVC

115

(C macro), 110

esp_gatt_write_type_t (C++ enum), 115

ESP_GATT_UUID_PNP_ID (C macro), 112

ESP_GATT_WRONG_STATE (C++ enumerator), 114

ESP_GATT_UUID_PRI_SERVICE (C macro), 111 ESP_GATTC_ACL_EVT (C++ enumerator), 143

ESP_GATT_UUID_REF_TIME_INFO (C macro), ESP_GATTC_ADV_DATA_EVT (C++ enumerator),

111

143

ESP_GATT_UUID_REF_TIME_UPDATE_SVC (C ESP_GATTC_ADV_VSC_EVT (C++ enumerator), 144

macro), 110

ESP_GATTC_BTH_SCAN_CFG_EVT (C++ enumera-

ESP_GATT_UUID_RINGER_CP (C macro), 111

tor), 143

ESP_GATT_UUID_RINGER_SETTING (C macro), ESP_GATTC_BTH_SCAN_DIS_EVT (C++ enumera-

111

tor), 143

ESP_GATT_UUID_RPT_REF_DESCR (C macro), ESP_GATTC_BTH_SCAN_ENB_EVT (C++ enumera-

111

tor), 143

ESP_GATT_UUID_RSC_FEATURE (C macro), 112 ESP_GATTC_BTH_SCAN_PARAM_EVT (C++ enu-

ESP_GATT_UUID_RSC_MEASUREMENT (C macro),

merator), 143

112

ESP_GATTC_BTH_SCAN_RD_EVT (C++ enumera-

ESP_GATT_UUID_RUNNING_SPEED_CADENCE_SVC

tor), 143

(C macro), 110

ESP_GATTC_BTH_SCAN_THR_EVT (C++ enumera-

ESP_GATT_UUID_SC_CONTROL_POINT

(C

tor), 143

Espressif Systems

2107

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

ESP_GATTC_CANCEL_OPEN_EVT (C++ enumera-

tor), 143

tor), 143

esp_gattc_multi_t (C++ class), 108

esp_gattc_cb_event_t (C++ enum), 142

esp_gattc_multi_t::handles (C++ member),

esp_gattc_cb_t (C++ type), 142

108

ESP_GATTC_CFG_MTU_EVT (C++ enumerator), 143 esp_gattc_multi_t::num_attr (C++ mem-

esp_gattc_char_elem_t (C++ class), 109

ber), 108

esp_gattc_char_elem_t::char_handle

ESP_GATTC_NOTIFY_EVT (C++ enumerator), 143

(C++ member), 109

ESP_GATTC_OPEN_EVT (C++ enumerator), 142

esp_gattc_char_elem_t::properties

ESP_GATTC_PREP_WRITE_EVT (C++ enumerator),

(C++ member), 109

143

esp_gattc_char_elem_t::uuid (C++ mem- ESP_GATTC_QUEUE_FULL_EVT (C++ enumerator),

ber), 109

144

ESP_GATTC_CLOSE_EVT (C++ enumerator), 142 ESP_GATTC_READ_CHAR_EVT (C++ enumerator),

ESP_GATTC_CONGEST_EVT (C++ enumerator), 143

142

ESP_GATTC_CONNECT_EVT (C++ enumerator), 144 ESP_GATTC_READ_DESCR_EVT (C++ enumerator),

esp_gattc_db_elem_t (C++ class), 108

143

esp_gattc_db_elem_t::attribute_handle ESP_GATTC_READ_MULTIPLE_EVT (C++ enumer-

(C++ member), 109

ator), 144

esp_gattc_db_elem_t::end_handle (C++ ESP_GATTC_REG_EVT (C++ enumerator), 142

member), 109

ESP_GATTC_REG_FOR_NOTIFY_EVT (C++ enu-

esp_gattc_db_elem_t::properties (C++

merator), 144

member), 109

ESP_GATTC_SCAN_FLT_CFG_EVT (C++ enumera-

esp_gattc_db_elem_t::start_handle

tor), 143

(C++ member), 109

ESP_GATTC_SCAN_FLT_PARAM_EVT (C++ enu-

esp_gattc_db_elem_t::type (C++ member),

merator), 144

109

ESP_GATTC_SCAN_FLT_STATUS_EVT (C++ enu-

esp_gattc_db_elem_t::uuid (C++ member),

merator), 144

109

ESP_GATTC_SEARCH_CMPL_EVT (C++ enumera-

esp_gattc_descr_elem_t (C++ class), 109

tor), 142

esp_gattc_descr_elem_t::handle (C++ ESP_GATTC_SEARCH_RES_EVT (C++ enumerator),

member), 109

142

esp_gattc_descr_elem_t::uuid (C++ mem- esp_gattc_service_elem_t (C++ class), 109

ber), 109

esp_gattc_service_elem_t::end_handle

ESP_GATTC_DIS_SRVC_CMPL_EVT (C++ enumer-

(C++ member), 109

ator), 144

esp_gattc_service_elem_t::is_primary

ESP_GATTC_DISCONNECT_EVT (C++ enumerator),

(C++ member), 109

144

esp_gattc_service_elem_t::start_handle

ESP_GATTC_ENC_CMPL_CB_EVT (C++ enumera-

(C++ member), 109

tor), 143

esp_gattc_service_elem_t::uuid (C++

ESP_GATTC_EXEC_EVT (C++ enumerator), 143

member), 109

ESP_GATTC_GET_ADDR_LIST_EVT (C++ enumer- ESP_GATTC_SET_ASSOC_EVT (C++ enumerator),

ator), 144

144

esp_gattc_incl_svc_elem_t (C++ class), 110 ESP_GATTC_SRVC_CHG_EVT (C++ enumerator),

esp_gattc_incl_svc_elem_t::handle

143

(C++ member), 110

ESP_GATTC_UNREG_EVT (C++ enumerator), 142

esp_gattc_incl_svc_elem_t::incl_srvc_e_EhSaPn_dGlAeTTC_UNREG_FOR_NOTIFY_EVT (C++

(C++ member), 110

enumerator), 144

esp_gattc_incl_svc_elem_t::incl_srvc_s_EhSaPn_dGlAeTTC_WRITE_CHAR_EVT (C++ enumerator),

(C++ member), 110

142

esp_gattc_incl_svc_elem_t::uuid (C++ ESP_GATTC_WRITE_DESCR_EVT (C++ enumera-

member), 110

tor), 143

ESP_GATTC_MULT_ADV_DATA_EVT (C++ enumer- ESP_GATTS_ADD_CHAR_DESCR_EVT (C++ enu-

ator), 143

merator), 127

ESP_GATTC_MULT_ADV_DIS_EVT (C++ enumera- ESP_GATTS_ADD_CHAR_EVT (C++ enumerator),

tor), 143

127

ESP_GATTC_MULT_ADV_ENB_EVT (C++ enumera- ESP_GATTS_ADD_INCL_SRVC_EVT (C++ enumer-

tor), 143

ator), 127

ESP_GATTC_MULT_ADV_UPD_EVT (C++ enumera- esp_gatts_attr_db_t (C++ class), 107

Espressif Systems

2108

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_gatts_attr_db_t::att_desc (C++

function), 1315

member), 107

esp_hmac_calculate (C++ function), 553

esp_gatts_attr_db_t::attr_control

esp_hmac_jtag_disable (C++ function), 554

(C++ member), 107

esp_hmac_jtag_enable (C++ function), 553

ESP_GATTS_CANCEL_OPEN_EVT (C++ enumera- esp_http_client_add_auth (C++ function),

tor), 128

858

esp_gatts_cb_event_t (C++ enum), 127

esp_http_client_auth_type_t (C++ enum),

esp_gatts_cb_t (C++ type), 127

863

ESP_GATTS_CLOSE_EVT (C++ enumerator), 128 esp_http_client_cleanup (C++ function), 858

ESP_GATTS_CONF_EVT (C++ enumerator), 127

esp_http_client_close (C++ function), 857

ESP_GATTS_CONGEST_EVT (C++ enumerator), 128 esp_http_client_config_t (C++ class), 860

ESP_GATTS_CONNECT_EVT (C++ enumerator), 128 esp_http_client_config_t::auth_type

ESP_GATTS_CREAT_ATTR_TAB_EVT (C++ enu-

(C++ member), 860

merator), 128

esp_http_client_config_t::buffer_size

ESP_GATTS_CREATE_EVT (C++ enumerator), 127

(C++ member), 861

ESP_GATTS_DELETE_EVT (C++ enumerator), 127 esp_http_client_config_t::buffer_size_tx

ESP_GATTS_DISCONNECT_EVT (C++ enumerator),

(C++ member), 861

128

esp_http_client_config_t::cert_len

ESP_GATTS_EXEC_WRITE_EVT (C++ enumerator),

(C++ member), 860

127

esp_http_client_config_t::cert_pem

esp_gatts_incl128_svc_desc_t (C++ class),

(C++ member), 860

107

esp_http_client_config_t::client_cert_len

esp_gatts_incl128_svc_desc_t::end_hdl

(C++ member), 860

(C++ member), 108

esp_http_client_config_t::client_cert_pem

esp_gatts_incl128_svc_desc_t::start_hdl

(C++ member), 860

(C++ member), 108

esp_http_client_config_t::client_key_len

esp_gatts_incl_svc_desc_t (C++ class), 107

(C++ member), 860

esp_gatts_incl_svc_desc_t::end_hdl

esp_http_client_config_t::client_key_password

(C++ member), 107

(C++ member), 860

esp_gatts_incl_svc_desc_t::start_hdl esp_http_client_config_t::client_key_password_len

(C++ member), 107

(C++ member), 860

esp_gatts_incl_svc_desc_t::uuid (C++ esp_http_client_config_t::client_key_pem

member), 107

(C++ member), 860

ESP_GATTS_LISTEN_EVT (C++ enumerator), 128 esp_http_client_config_t::crt_bundle_attach

ESP_GATTS_MTU_EVT (C++ enumerator), 127

(C++ member), 861

ESP_GATTS_OPEN_EVT (C++ enumerator), 128

esp_http_client_config_t::disable_auto_redirect

ESP_GATTS_READ_EVT (C++ enumerator), 127

(C++ member), 860

ESP_GATTS_REG_EVT (C++ enumerator), 127

esp_http_client_config_t::event_handler

ESP_GATTS_RESPONSE_EVT (C++ enumerator),

(C++ member), 861

128

esp_http_client_config_t::host (C++

ESP_GATTS_SEND_SERVICE_CHANGE_EVT

member), 860

(C++ enumerator), 128

esp_http_client_config_t::if_name

ESP_GATTS_SET_ATTR_VAL_EVT (C++ enumera-

(C++ member), 861

tor), 128

esp_http_client_config_t::is_async

ESP_GATTS_START_EVT (C++ enumerator), 127

(C++ member), 861

ESP_GATTS_STOP_EVT (C++ enumerator), 127

esp_http_client_config_t::keep_alive_count

ESP_GATTS_UNREG_EVT (C++ enumerator), 127

(C++ member), 861

ESP_GATTS_WRITE_EVT (C++ enumerator), 127 esp_http_client_config_t::keep_alive_enable

esp_gcov_dump (C++ function), 1088

(C++ member), 861

esp_get_deep_sleep_wake_stub (C++ func- esp_http_client_config_t::keep_alive_idle

tion), 1347

(C++ member), 861

esp_get_flash_encryption_mode (C++ func- esp_http_client_config_t::keep_alive_interval

tion), 1059

(C++ member), 861

esp_get_free_heap_size (C++ function), 1315 esp_http_client_config_t::max_authorization_retri

esp_get_free_internal_heap_size (C++

(C++ member), 861

function), 1315

esp_http_client_config_t::max_redirection_count

esp_get_idf_version (C++ function), 1316

(C++ member), 861

esp_get_minimum_free_heap_size (C++ esp_http_client_config_t::method (C++

Espressif Systems

2109

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

member), 860

855

esp_http_client_config_t::password

esp_http_client_get_password (C++ func-

(C++ member), 860

tion), 855

esp_http_client_config_t::path (C++ esp_http_client_get_post_field (C++

member), 860

function), 854

esp_http_client_config_t::port (C++ esp_http_client_get_status_code (C++

member), 860

function), 857

esp_http_client_config_t::query (C++ esp_http_client_get_transport_type

member), 860

(C++ function), 858

esp_http_client_config_t::skip_cert_comemsopn__hntatmpe__cclhieecnkt_get_url (C++ function), 859

(C++ member), 861

esp_http_client_get_username (C++ func-

esp_http_client_config_t::timeout_ms

tion), 855

(C++ member), 860

esp_http_client_handle_t (C++ type), 862

esp_http_client_config_t::transport_typeesp_http_client_init (C++ function), 853

(C++ member), 861

esp_http_client_is_chunked_response

esp_http_client_config_t::url (C++

(C++ function), 857

member), 860

esp_http_client_is_complete_data_received

esp_http_client_config_t::use_global_ca_store (C++ function), 858

(C++ member), 861

esp_http_client_method_t (C++ enum), 863

esp_http_client_config_t::user_agent esp_http_client_open (C++ function), 856

(C++ member), 860

esp_http_client_perform (C++ function), 854

esp_http_client_config_t::user_data esp_http_client_read (C++ function), 857

(C++ member), 861

esp_http_client_read_response (C++ func-

esp_http_client_config_t::username

tion), 858

(C++ member), 860

esp_http_client_set_authtype (C++ func-

esp_http_client_delete_header (C++ func-

tion), 856

tion), 856

esp_http_client_set_header (C++ function),

esp_http_client_event (C++ class), 859

854

esp_http_client_event::client (C++ esp_http_client_set_method (C++ function),

member), 859

856

esp_http_client_event::data (C++ mem- esp_http_client_set_password (C++ func-

ber), 859

tion), 855

esp_http_client_event::data_len (C++ esp_http_client_set_post_field (C++

member), 859

function), 854

esp_http_client_event::event_id (C++ esp_http_client_set_redirection (C++

member), 859

function), 858

esp_http_client_event::header_key

esp_http_client_set_timeout_ms (C++

(C++ member), 859

function), 856

esp_http_client_event::header_value esp_http_client_set_url (C++ function), 854

(C++ member), 860

esp_http_client_set_username (C++ func-

esp_http_client_event::user_data (C++

tion), 855

member), 859

esp_http_client_transport_t (C++ enum),

esp_http_client_event_handle_t (C++

862

type), 862

esp_http_client_write (C++ function), 857

esp_http_client_event_id_t (C++ enum), esp_https_ota (C++ function), 1123

862

esp_https_ota_abort (C++ function), 1124

esp_http_client_event_t (C++ type), 862

esp_https_ota_begin (C++ function), 1123

esp_http_client_fetch_headers (C++ func- esp_https_ota_config_t (C++ class), 1125

tion), 857

esp_https_ota_config_t::bulk_flash_erase

esp_http_client_flush_response (C++

(C++ member), 1125

function), 859

esp_https_ota_config_t::http_client_init_cb

esp_http_client_get_chunk_length (C++

(C++ member), 1125

function), 859

esp_https_ota_config_t::http_config

esp_http_client_get_content_length

(C++ member), 1125

(C++ function), 857

esp_https_ota_config_t::max_http_request_size

esp_http_client_get_errno (C++ function),

(C++ member), 1125

856

esp_https_ota_config_t::partial_http_download

esp_http_client_get_header (C++ function),

(C++ member), 1125

Espressif Systems

2110

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_https_ota_finish (C++ function), 1124 esp_image_header_t::wp_pin (C++ member),

esp_https_ota_get_image_len_read (C++

1082

function), 1125

ESP_IMAGE_MAX_SEGMENTS (C macro), 1084

esp_https_ota_get_image_size (C++ func- esp_image_segment_header_t (C++ class),

tion), 1125

1083

esp_https_ota_get_img_desc (C++ function), esp_image_segment_header_t::data_len

1124

(C++ member), 1083

esp_https_ota_handle_t (C++ type), 1126

esp_image_segment_header_t::load_addr

esp_https_ota_is_complete_data_received

(C++ member), 1083

(C++ function), 1124

esp_image_spi_freq_t (C++ enum), 1084

esp_https_ota_perform (C++ function), 1123 ESP_IMAGE_SPI_MODE_DIO (C++ enumerator),

esp_https_server_user_cb (C++ type), 888

1084

esp_https_server_user_cb_arg (C++ class), ESP_IMAGE_SPI_MODE_DOUT (C++ enumerator),

887

1084

esp_https_server_user_cb_arg_t (C++ ESP_IMAGE_SPI_MODE_FAST_READ (C++ enu-

type), 888

merator), 1084

ESP_IDF_VERSION (C macro), 1316

ESP_IMAGE_SPI_MODE_QIO (C++ enumerator),

ESP_IDF_VERSION_MAJOR (C macro), 1316

1084

ESP_IDF_VERSION_MINOR (C macro), 1316

ESP_IMAGE_SPI_MODE_QOUT (C++ enumerator),

ESP_IDF_VERSION_PATCH (C macro), 1316

1084

ESP_IDF_VERSION_VAL (C macro), 1316

ESP_IMAGE_SPI_MODE_SLOW_READ (C++ enu-

ESP_IMAGE_FLASH_SIZE_16MB (C++ enumera-

merator), 1084

tor), 1085

esp_image_spi_mode_t (C++ enum), 1084

ESP_IMAGE_FLASH_SIZE_1MB (C++ enumerator), ESP_IMAGE_SPI_SPEED_20M (C++ enumerator),

1085

1084

ESP_IMAGE_FLASH_SIZE_2MB (C++ enumerator), ESP_IMAGE_SPI_SPEED_26M (C++ enumerator),

1085

1084

ESP_IMAGE_FLASH_SIZE_4MB (C++ enumerator), ESP_IMAGE_SPI_SPEED_40M (C++ enumerator),

1085

1084

ESP_IMAGE_FLASH_SIZE_8MB (C++ enumerator), ESP_IMAGE_SPI_SPEED_80M (C++ enumerator),

1085

1085

ESP_IMAGE_FLASH_SIZE_MAX (C++ enumerator), esp_int_wdt_init (C++ function), 1351

1085

esp_intr_alloc (C++ function), 1302

esp_image_flash_size_t (C++ enum), 1085 esp_intr_alloc_intrstatus (C++ function),

ESP_IMAGE_HEADER_MAGIC (C macro), 1084

1302

esp_image_header_t (C++ class), 1082

ESP_INTR_DISABLE (C macro), 1305

esp_image_header_t::chip_id (C++ mem- esp_intr_disable (C++ function), 1303

ber), 1082

esp_intr_disable_source (C++ function),

esp_image_header_t::entry_addr (C++

1304

member), 1082

ESP_INTR_ENABLE (C macro), 1305

esp_image_header_t::hash_appended

esp_intr_enable (C++ function), 1304

(C++ member), 1083

esp_intr_enable_source (C++ function), 1304

esp_image_header_t::magic (C++ member), ESP_INTR_FLAG_EDGE (C macro), 1305

1082

ESP_INTR_FLAG_HIGH (C macro), 1305

esp_image_header_t::min_chip_rev (C++ ESP_INTR_FLAG_INTRDISABLED (C macro), 1305

member), 1083

ESP_INTR_FLAG_IRAM (C macro), 1305

esp_image_header_t::reserved (C++ mem- ESP_INTR_FLAG_LEVEL1 (C macro), 1304

ber), 1083

ESP_INTR_FLAG_LEVEL2 (C macro), 1304

esp_image_header_t::segment_count

ESP_INTR_FLAG_LEVEL3 (C macro), 1304

(C++ member), 1082

ESP_INTR_FLAG_LEVEL4 (C macro), 1304

esp_image_header_t::spi_mode (C++ mem- ESP_INTR_FLAG_LEVEL5 (C macro), 1305

ber), 1082

ESP_INTR_FLAG_LEVEL6 (C macro), 1305

esp_image_header_t::spi_pin_drv (C++ ESP_INTR_FLAG_LEVELMASK (C macro), 1305

member), 1082

ESP_INTR_FLAG_LOWMED (C macro), 1305

esp_image_header_t::spi_size (C++ mem- ESP_INTR_FLAG_NMI (C macro), 1305

ber), 1082

ESP_INTR_FLAG_SHARED (C macro), 1305

esp_image_header_t::spi_speed (C++ esp_intr_flags_to_level (C++ function),

member), 1082

1304

Espressif Systems

2111

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_intr_free (C++ function), 1303

esp_lcd_i80_bus_config_t::wr_gpio_num

esp_intr_get_cpu (C++ function), 1303

(C++ member), 594

esp_intr_get_intno (C++ function), 1303

esp_lcd_i80_bus_handle_t (C++ type), 595

esp_intr_mark_shared (C++ function), 1302 esp_lcd_new_i80_bus (C++ function), 592

esp_intr_noniram_disable (C++ function), esp_lcd_new_panel_io_i2c (C++ function),

1304

592

esp_intr_noniram_enable (C++ function), esp_lcd_new_panel_io_i80 (C++ function),

1304

593

esp_intr_reserve (C++ function), 1302

esp_lcd_new_panel_io_spi (C++ function),

esp_intr_set_in_iram (C++ function), 1304

592

ESP_IO_CAP_IN (C macro), 95

esp_lcd_new_panel_nt35510 (C++ function),

ESP_IO_CAP_IO (C macro), 95

601

ESP_IO_CAP_KBDISP (C macro), 95

esp_lcd_new_panel_ssd1306 (C++ function),

ESP_IO_CAP_NONE (C macro), 95

601

ESP_IO_CAP_OUT (C macro), 95

esp_lcd_new_panel_st7789 (C++ function),

esp_ip4addr_aton (C++ function), 493

601

esp_ip4addr_ntoa (C++ function), 493

esp_lcd_new_rgb_panel (C++ function), 597

esp_ipc_call (C++ function), 1297

esp_lcd_panel_del (C++ function), 596

esp_ipc_call_blocking (C++ function), 1297 esp_lcd_panel_dev_config_t (C++ class),

esp_ipc_func_t (C++ type), 1297

601

esp_ipc_isr_asm_call (C++ function), 1297 esp_lcd_panel_dev_config_t::bits_per_pixel

esp_ipc_isr_asm_call_blocking (C++ func-

(C++ member), 601

tion), 1298

esp_lcd_panel_dev_config_t::color_space

esp_ipc_isr_func_t (C++ type), 1298

(C++ member), 601

esp_ipc_isr_release_other_cpu (C++ func- esp_lcd_panel_dev_config_t::reset_active_high

tion), 1298

(C++ member), 601

esp_ipc_isr_stall_abort (C++ function), esp_lcd_panel_dev_config_t::reset_gpio_num

1298

(C++ member), 601

esp_ipc_isr_stall_other_cpu (C++ func- esp_lcd_panel_disp_off (C++ function), 597

tion), 1298

esp_lcd_panel_draw_bitmap (C++ function),

esp_ipc_isr_stall_pause (C++ function),

596

1298

esp_lcd_panel_handle_t (C++ type), 591

esp_ipc_isr_stall_resume (C++ function), esp_lcd_panel_init (C++ function), 596

1298

esp_lcd_panel_invert_color (C++ function),

ESP_LCD_COLOR_SPACE_BGR (C++ enumerator),

597

591

esp_lcd_panel_io_color_trans_done_cb_t

ESP_LCD_COLOR_SPACE_MONOCHROME (C++

(C++ type), 595

enumerator), 591

esp_lcd_panel_io_del (C++ function), 592

ESP_LCD_COLOR_SPACE_RGB (C++ enumerator), esp_lcd_panel_io_event_data_t (C++

591

class), 593

esp_lcd_color_space_t (C++ enum), 591

esp_lcd_panel_io_handle_t (C++ type), 591

esp_lcd_del_i80_bus (C++ function), 592

esp_lcd_panel_io_i2c_config_t (C++

esp_lcd_i2c_bus_handle_t (C++ type), 595

class), 594

esp_lcd_i80_bus_config_t (C++ class), 594 esp_lcd_panel_io_i2c_config_t::control_phase_byte

esp_lcd_i80_bus_config_t::bus_width

(C++ member), 594

(C++ member), 594

esp_lcd_panel_io_i2c_config_t::dc_bit_offset

esp_lcd_i80_bus_config_t::clk_src

(C++ member), 594

(C++ member), 594

esp_lcd_panel_io_i2c_config_t::dc_low_on_data

esp_lcd_i80_bus_config_t::data_gpio_nums

(C++ member), 594

(C++ member), 594

esp_lcd_panel_io_i2c_config_t::dev_addr

esp_lcd_i80_bus_config_t::dc_gpio_num

(C++ member), 594

(C++ member), 594

esp_lcd_panel_io_i2c_config_t::lcd_cmd_bits

esp_lcd_i80_bus_config_t::max_transfer_bytes (C++ member), 594

(C++ member), 594

esp_lcd_panel_io_i2c_config_t::lcd_param_bits

esp_lcd_i80_bus_config_t::psram_trans_align (C++ member), 594

(C++ member), 594

esp_lcd_panel_io_i2c_config_t::on_color_trans_don

esp_lcd_i80_bus_config_t::sram_trans_align (C++ member), 594

(C++ member), 594

esp_lcd_panel_io_i2c_config_t::user_ctx

Espressif Systems

2112

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 594

(C++ member), 593

esp_lcd_panel_io_i80_config_t (C++ esp_lcd_panel_io_spi_config_t::trans_queue_depth

class), 594

(C++ member), 593

esp_lcd_panel_io_i80_config_t::cs_activees_ph_ilgchd_panel_io_spi_config_t::user_ctx

(C++ member), 595

(C++ member), 593

esp_lcd_panel_io_i80_config_t::cs_gpio_ensupm_lcd_panel_io_tx_color (C++ function),

(C++ member), 595

591

esp_lcd_panel_io_i80_config_t::dc_cmd_leesvpe_llcd_panel_io_tx_param (C++ function),

(C++ member), 595

591

esp_lcd_panel_io_i80_config_t::dc_data_elsepv_ellcd_panel_mirror (C++ function), 596

(C++ member), 595

esp_lcd_panel_reset (C++ function), 596

esp_lcd_panel_io_i80_config_t::dc_dummye_slpe_vlecld_panel_set_gap (C++ function), 597

(C++ member), 595

esp_lcd_panel_swap_xy (C++ function), 597

esp_lcd_panel_io_i80_config_t::dc_idle_elsepv_ellcd_rgb_panel_config_t (C++ class),

(C++ member), 595

599

esp_lcd_panel_io_i80_config_t::dc_levelessp_lcd_rgb_panel_config_t::clk_src

(C++ member), 595

(C++ member), 600

esp_lcd_panel_io_i80_config_t::lcd_cmd_ebsipt_slcd_rgb_panel_config_t::data_gpio_nums

(C++ member), 595

(C++ member), 600

esp_lcd_panel_io_i80_config_t::lcd_paraems_pb_iltcsd_rgb_panel_config_t::data_width

(C++ member), 595

(C++ member), 600

esp_lcd_panel_io_i80_config_t::on_colore_stpr_alncsd__drognbe_panel_config_t::de_gpio_num

(C++ member), 595

(C++ member), 600

esp_lcd_panel_io_i80_config_t::pclk_acteisvpe__lncedg_rgb_panel_config_t::disp_active_low

(C++ member), 595

(C++ member), 600

esp_lcd_panel_io_i80_config_t::pclk_hz esp_lcd_rgb_panel_config_t::disp_gpio_num

(C++ member), 595

(C++ member), 600

esp_lcd_panel_io_i80_config_t::pclk_idlees_pl_olwcd_rgb_panel_config_t::fb_in_psram

(C++ member), 595

(C++ member), 600

esp_lcd_panel_io_i80_config_t::reverse_ecsopl_olrc_db_irtgsb_panel_config_t::hsync_gpio_num

(C++ member), 595

(C++ member), 600

esp_lcd_panel_io_i80_config_t::swap_coleosrp__blyctde_srgb_panel_config_t::on_frame_trans_done

(C++ member), 595

(C++ member), 600

esp_lcd_panel_io_i80_config_t::trans_queesupe__ldcedp_trhgb_panel_config_t::pclk_gpio_num

(C++ member), 595

(C++ member), 600

esp_lcd_panel_io_i80_config_t::user_ctxesp_lcd_rgb_panel_config_t::psram_trans_align

(C++ member), 595

(C++ member), 600

esp_lcd_panel_io_spi_config_t (C++ esp_lcd_rgb_panel_config_t::relax_on_idle

class), 593

(C++ member), 600

esp_lcd_panel_io_spi_config_t::cs_gpio_ensupm_lcd_rgb_panel_config_t::sram_trans_align

(C++ member), 593

(C++ member), 600

esp_lcd_panel_io_spi_config_t::dc_as_cmeds_pp_hlacsde_rgb_panel_config_t::timings

(C++ member), 593

(C++ member), 600

esp_lcd_panel_io_spi_config_t::dc_gpio_ensupm_lcd_rgb_panel_config_t::user_ctx

(C++ member), 593

(C++ member), 600

esp_lcd_panel_io_spi_config_t::dc_low_oens_pd_altcad_rgb_panel_config_t::vsync_gpio_num

(C++ member), 593

(C++ member), 600

esp_lcd_panel_io_spi_config_t::lcd_cmd_ebsipt_slcd_rgb_panel_event_data_t (C++

(C++ member), 593

class), 599

esp_lcd_panel_io_spi_config_t::lcd_paraems_pb_iltcsd_rgb_panel_frame_trans_done_cb_t

(C++ member), 593

(C++ type), 600

esp_lcd_panel_io_spi_config_t::octal_moedsep_lcd_rgb_timing_t (C++ class), 598

(C++ member), 593

esp_lcd_rgb_timing_t::de_idle_high

esp_lcd_panel_io_spi_config_t::on_color_trans_(Cd+o+nemember), 599

(C++ member), 593

esp_lcd_rgb_timing_t::h_res (C++ mem-

esp_lcd_panel_io_spi_config_t::pclk_hz

ber), 599

(C++ member), 593

esp_lcd_rgb_timing_t::hsync_back_porch

esp_lcd_panel_io_spi_config_t::spi_mode

(C++ member), 599

Espressif Systems

2113

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_lcd_rgb_timing_t::hsync_front_porch

tion), 897

(C++ member), 599

esp_local_ctrl_get_transport_ble (C++

esp_lcd_rgb_timing_t::hsync_idle_low

function), 896

(C++ member), 599

esp_local_ctrl_get_transport_httpd

esp_lcd_rgb_timing_t::hsync_pulse_width

(C++ function), 897

(C++ member), 599

esp_local_ctrl_handlers (C++ class), 899

esp_lcd_rgb_timing_t::pclk_active_neg esp_local_ctrl_handlers::get_prop_values

(C++ member), 599

(C++ member), 899

esp_lcd_rgb_timing_t::pclk_hz (C++ esp_local_ctrl_handlers::set_prop_values

member), 599

(C++ member), 899

esp_lcd_rgb_timing_t::pclk_idle_high esp_local_ctrl_handlers::usr_ctx (C++

(C++ member), 599

member), 899

esp_lcd_rgb_timing_t::v_res (C++ mem- esp_local_ctrl_handlers::usr_ctx_free_fn

ber), 599

(C++ member), 900

esp_lcd_rgb_timing_t::vsync_back_porch esp_local_ctrl_handlers_t (C++ type), 900

(C++ member), 599

esp_local_ctrl_prop (C++ class), 898

esp_lcd_rgb_timing_t::vsync_front_porchesp_local_ctrl_prop::ctx (C++ member),

(C++ member), 599

898

esp_lcd_rgb_timing_t::vsync_idle_low esp_local_ctrl_prop::ctx_free_fn (C++

(C++ member), 599

member), 898

esp_lcd_rgb_timing_t::vsync_pulse_widthesp_local_ctrl_prop::flags (C++ member),

(C++ member), 599

898

esp_lcd_spi_bus_handle_t (C++ type), 595 esp_local_ctrl_prop::name (C++ member),

ESP_LE_AUTH_BOND (C macro), 95

898

ESP_LE_AUTH_NO_BOND (C macro), 95

esp_local_ctrl_prop::size (C++ member),

ESP_LE_AUTH_REQ_BOND_MITM (C macro), 95

898

ESP_LE_AUTH_REQ_MITM (C macro), 95

esp_local_ctrl_prop::type (C++ member),

ESP_LE_AUTH_REQ_SC_BOND (C macro), 95

898

ESP_LE_AUTH_REQ_SC_MITM (C macro), 95

esp_local_ctrl_prop_t (C++ type), 900

ESP_LE_AUTH_REQ_SC_MITM_BOND (C macro), esp_local_ctrl_prop_val (C++ class), 898

95

esp_local_ctrl_prop_val::data (C++

ESP_LE_AUTH_REQ_SC_ONLY (C macro), 95

member), 899

ESP_LE_KEY_LCSRK (C macro), 95

esp_local_ctrl_prop_val::free_fn (C++

ESP_LE_KEY_LENC (C macro), 95

member), 899

ESP_LE_KEY_LID (C macro), 95

esp_local_ctrl_prop_val::size (C++

ESP_LE_KEY_LLK (C macro), 95

member), 899

ESP_LE_KEY_NONE (C macro), 95

esp_local_ctrl_prop_val_t (C++ type), 900

ESP_LE_KEY_PCSRK (C macro), 95

esp_local_ctrl_proto_sec (C++ enum), 901

ESP_LE_KEY_PENC (C macro), 95

esp_local_ctrl_proto_sec_cfg (C++ class),

ESP_LE_KEY_PID (C macro), 95

900

ESP_LE_KEY_PLK (C macro), 95

esp_local_ctrl_proto_sec_cfg::custom_handle

esp_light_sleep_start (C++ function), 1346

(C++ member), 900

esp_link_key (C++ type), 58

esp_local_ctrl_proto_sec_cfg::pop

esp_local_ctrl_add_property (C++ func-

(C++ member), 900

tion), 897

esp_local_ctrl_proto_sec_cfg::version

esp_local_ctrl_config (C++ class), 900

(C++ member), 900

esp_local_ctrl_config::handlers (C++ esp_local_ctrl_proto_sec_cfg_t (C++

member), 900

type), 901

esp_local_ctrl_config::max_properties esp_local_ctrl_proto_sec_t (C++ type), 901

(C++ member), 900

esp_local_ctrl_remove_property (C++

esp_local_ctrl_config::proto_sec (C++

function), 897

member), 900

esp_local_ctrl_set_handler (C++ function),

esp_local_ctrl_config::transport (C++

897

member), 900

esp_local_ctrl_start (C++ function), 897

esp_local_ctrl_config::transport_configesp_local_ctrl_stop (C++ function), 897

(C++ member), 900

ESP_LOCAL_CTRL_TRANSPORT_BLE (C macro),

esp_local_ctrl_config_t (C++ type), 901

900

esp_local_ctrl_get_property (C++ func- esp_local_ctrl_transport_config_ble_t

Espressif Systems

2114

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ type), 901

esp_mesh_enable_ps (C++ function), 435

esp_local_ctrl_transport_config_httpd_tesp_mesh_fix_root (C++ function), 433

(C++ type), 901

esp_mesh_flush_scan_result (C++ function),

esp_local_ctrl_transport_config_t

434

(C++ union), 898

esp_mesh_flush_upstream_packets (C++

esp_local_ctrl_transport_config_t::ble

function), 434

(C++ member), 898

esp_mesh_get_active_duty_cycle (C++

esp_local_ctrl_transport_config_t::httpd

function), 436

(C++ member), 898

esp_mesh_get_ap_assoc_expire (C++ func-

ESP_LOCAL_CTRL_TRANSPORT_HTTPD

(C

tion), 430

macro), 900

esp_mesh_get_ap_authmode (C++ function),

esp_local_ctrl_transport_t (C++ type), 900

428

ESP_LOG_BUFFER_CHAR (C macro), 1309

esp_mesh_get_ap_connections (C++ func-

ESP_LOG_BUFFER_CHAR_LEVEL (C macro), 1309

tion), 428

ESP_LOG_BUFFER_HEX (C macro), 1309

esp_mesh_get_capacity_num (C++ function),

ESP_LOG_BUFFER_HEX_LEVEL (C macro), 1309

432

ESP_LOG_BUFFER_HEXDUMP (C macro), 1309

esp_mesh_get_config (C++ function), 426

ESP_LOG_DEBUG (C++ enumerator), 1311

esp_mesh_get_group_list (C++ function), 431

ESP_LOG_EARLY_IMPL (C macro), 1310

esp_mesh_get_group_num (C++ function), 431

esp_log_early_timestamp (C++ function), esp_mesh_get_id (C++ function), 427

1308

esp_mesh_get_ie_crypto_key (C++ function),

ESP_LOG_ERROR (C++ enumerator), 1311

432

ESP_LOG_INFO (C++ enumerator), 1311

esp_mesh_get_layer (C++ function), 428

ESP_LOG_LEVEL (C macro), 1310

esp_mesh_get_max_layer (C++ function), 427

esp_log_level_get (C++ function), 1308

esp_mesh_get_network_duty_cycle (C++

ESP_LOG_LEVEL_LOCAL (C macro), 1310

function), 437

esp_log_level_set (C++ function), 1307

esp_mesh_get_non_mesh_connections

esp_log_level_t (C++ enum), 1311

(C++ function), 428

ESP_LOG_NONE (C++ enumerator), 1311

esp_mesh_get_parent_bssid (C++ function),

esp_log_set_vprintf (C++ function), 1308

428

esp_log_system_timestamp (C++ function), esp_mesh_get_root_healing_delay (C++

1308

function), 432

esp_log_timestamp (C++ function), 1308

esp_mesh_get_router (C++ function), 426

ESP_LOG_VERBOSE (C++ enumerator), 1311

esp_mesh_get_router_bssid (C++ function),

ESP_LOG_WARN (C++ enumerator), 1311

435

esp_log_write (C++ function), 1308

esp_mesh_get_routing_table (C++ function),

esp_log_writev (C++ function), 1308

430

ESP_LOGD (C macro), 1310

esp_mesh_get_routing_table_size (C++

ESP_LOGE (C macro), 1310

function), 430

ESP_LOGI (C macro), 1310

esp_mesh_get_running_active_duty_cycle

ESP_LOGV (C macro), 1310

(C++ function), 437

ESP_LOGW (C macro), 1310

esp_mesh_get_rx_pending (C++ function), 430

ESP_MAC_BT (C++ enumerator), 1318

esp_mesh_get_self_organized (C++ func-

ESP_MAC_ETH (C++ enumerator), 1318

tion), 429

ESP_MAC_IEEE802154 (C++ enumerator), 1318 esp_mesh_get_subnet_nodes_list (C++

esp_mac_type_t (C++ enum), 1317

function), 434

ESP_MAC_WIFI_SOFTAP (C++ enumerator), 1317 esp_mesh_get_subnet_nodes_num (C++ func-

ESP_MAC_WIFI_STA (C++ enumerator), 1317

tion), 434

esp_mesh_allow_root_conflicts (C++ func- esp_mesh_get_topology (C++ function), 435

tion), 431

esp_mesh_get_total_node_num (C++ func-

esp_mesh_available_txupQ_num (C++ func-

tion), 430

tion), 430

esp_mesh_get_tsf_time (C++ function), 435

esp_mesh_connect (C++ function), 434

esp_mesh_get_tx_pending (C++ function), 430

esp_mesh_deinit (C++ function), 423

esp_mesh_get_type (C++ function), 427

esp_mesh_delete_group_id (C++ function), esp_mesh_get_vote_percentage (C++ func-

431

tion), 429

esp_mesh_disable_ps (C++ function), 435

esp_mesh_get_xon_qsize (C++ function), 431

esp_mesh_disconnect (C++ function), 434

esp_mesh_init (C++ function), 422

Espressif Systems

2115

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_mesh_is_device_active (C++ function), 435
esp_mesh_is_my_group (C++ function), 432 esp_mesh_is_ps_enabled (C++ function), 435 esp_mesh_is_root (C++ function), 428 esp_mesh_is_root_conflicts_allowed
(C++ function), 431 esp_mesh_is_root_fixed (C++ function), 433 esp_mesh_post_toDS_state (C++ function),
430 esp_mesh_ps_duty_signaling (C++ function),
437 esp_mesh_recv (C++ function), 424 esp_mesh_recv_toDS (C++ function), 425 esp_mesh_scan_get_ap_ie_len (C++ func-
tion), 433 esp_mesh_scan_get_ap_record (C++ func-
tion), 433 esp_mesh_send (C++ function), 423 esp_mesh_send_block_time (C++ function),
424 esp_mesh_set_active_duty_cycle (C++
function), 436 esp_mesh_set_ap_assoc_expire (C++ func-
tion), 429 esp_mesh_set_ap_authmode (C++ function),
427 esp_mesh_set_ap_connections (C++ func-
tion), 428 esp_mesh_set_ap_password (C++ function),
427 esp_mesh_set_capacity_num (C++ function),
432 esp_mesh_set_config (C++ function), 425 esp_mesh_set_group_id (C++ function), 431 esp_mesh_set_id (C++ function), 426 esp_mesh_set_ie_crypto_funcs (C++ func-
tion), 432 esp_mesh_set_ie_crypto_key (C++ function),
432 esp_mesh_set_max_layer (C++ function), 427 esp_mesh_set_network_duty_cycle (C++
function), 436 esp_mesh_set_parent (C++ function), 433 esp_mesh_set_root_healing_delay (C++
function), 432 esp_mesh_set_router (C++ function), 426 esp_mesh_set_self_organized (C++ func-
tion), 428 esp_mesh_set_topology (C++ function), 435 esp_mesh_set_type (C++ function), 427 esp_mesh_set_vote_percentage (C++ func-
tion), 429 esp_mesh_set_xon_qsize (C++ function), 431 esp_mesh_start (C++ function), 423 esp_mesh_stop (C++ function), 423 esp_mesh_switch_channel (C++ function), 434 esp_mesh_topology_t (C++ enum), 449

esp_mesh_waive_root (C++ function), 429 esp_mqtt_client_config_t (C++ class), 808 esp_mqtt_client_config_t::alpn_protos
(C++ member), 810 esp_mqtt_client_config_t::buffer_size
(C++ member), 809 esp_mqtt_client_config_t::cert_len
(C++ member), 809 esp_mqtt_client_config_t::cert_pem
(C++ member), 809 esp_mqtt_client_config_t::client_cert_len
(C++ member), 810 esp_mqtt_client_config_t::client_cert_pem
(C++ member), 810 esp_mqtt_client_config_t::client_id
(C++ member), 809 esp_mqtt_client_config_t::client_key_len
(C++ member), 810 esp_mqtt_client_config_t::client_key_pem
(C++ member), 810 esp_mqtt_client_config_t::clientkey_password
(C++ member), 810 esp_mqtt_client_config_t::clientkey_password_len
(C++ member), 810 esp_mqtt_client_config_t::crt_bundle_attach
(C++ member), 810 esp_mqtt_client_config_t::disable_auto_reconnect
(C++ member), 809 esp_mqtt_client_config_t::disable_clean_session
(C++ member), 809 esp_mqtt_client_config_t::disable_keepalive
(C++ member), 811 esp_mqtt_client_config_t::ds_data
(C++ member), 810 esp_mqtt_client_config_t::event_handle
(C++ member), 808 esp_mqtt_client_config_t::event_loop_handle
(C++ member), 808 esp_mqtt_client_config_t::host (C++
member), 809 esp_mqtt_client_config_t::keepalive
(C++ member), 809 esp_mqtt_client_config_t::lwt_msg
(C++ member), 809 esp_mqtt_client_config_t::lwt_msg_len
(C++ member), 809 esp_mqtt_client_config_t::lwt_qos
(C++ member), 809 esp_mqtt_client_config_t::lwt_retain
(C++ member), 809 esp_mqtt_client_config_t::lwt_topic
(C++ member), 809 esp_mqtt_client_config_t::message_retransmit_time
(C++ member), 811 esp_mqtt_client_config_t::network_timeout_ms
(C++ member), 810 esp_mqtt_client_config_t::out_buffer_size
(C++ member), 810

Espressif Systems

2116

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_mqtt_client_config_t::password

(C++ member), 808

(C++ member), 809

esp_mqtt_error_codes::error_type (C++

esp_mqtt_client_config_t::path (C++

member), 807

member), 811

esp_mqtt_error_codes::esp_tls_cert_verify_flags

esp_mqtt_client_config_t::port (C++

(C++ member), 807

member), 809

esp_mqtt_error_codes::esp_tls_last_esp_err

esp_mqtt_client_config_t::protocol_ver

(C++ member), 807

(C++ member), 810

esp_mqtt_error_codes::esp_tls_stack_err

esp_mqtt_client_config_t::psk_hint_key

(C++ member), 807

(C++ member), 810

esp_mqtt_error_codes::esp_transport_sock_errno

esp_mqtt_client_config_t::reconnect_timeout_ms(C++ member), 808

(C++ member), 810

esp_mqtt_error_codes_t (C++ type), 811

esp_mqtt_client_config_t::refresh_conneecstpi_omnq_tatf_teerrr_omrs_type_t (C++ enum), 812

(C++ member), 810

esp_mqtt_event_handle_t (C++ type), 811

esp_mqtt_client_config_t::set_null_clieenstp__imdqtt_event_id_t (C++ enum), 811

(C++ member), 809

esp_mqtt_event_t (C++ class), 808

esp_mqtt_client_config_t::skip_cert_comemsopn__mnqatmte__ecvheenctk_t::client (C++ member),

(C++ member), 810

808

esp_mqtt_client_config_t::task_prio esp_mqtt_event_t::current_data_offset

(C++ member), 809

(C++ member), 808

esp_mqtt_client_config_t::task_stack esp_mqtt_event_t::data (C++ member), 808

(C++ member), 809

esp_mqtt_event_t::data_len (C++ member),

esp_mqtt_client_config_t::transport

808

(C++ member), 810

esp_mqtt_event_t::dup (C++ member), 808

esp_mqtt_client_config_t::uri (C++ esp_mqtt_event_t::error_handle (C++

member), 809

member), 808

esp_mqtt_client_config_t::use_global_cae_sspt_omrqett_event_t::event_id (C++ member),

(C++ member), 810

808

esp_mqtt_client_config_t::use_secure_eleesmpe_nmtqtt_event_t::msg_id (C++ member),

(C++ member), 810

808

esp_mqtt_client_config_t::user_context esp_mqtt_event_t::qos (C++ member), 808

(C++ member), 809

esp_mqtt_event_t::retain (C++ member),

esp_mqtt_client_config_t::username

808

(C++ member), 809

esp_mqtt_event_t::session_present

esp_mqtt_client_destroy (C++ function), 806

(C++ member), 808

esp_mqtt_client_disconnect (C++ function), esp_mqtt_event_t::topic (C++ member), 808

805

esp_mqtt_event_t::topic_len (C++ mem-

esp_mqtt_client_enqueue (C++ function), 806

ber), 808

esp_mqtt_client_get_outbox_size (C++ esp_mqtt_event_t::total_data_len (C++

function), 807

member), 808

esp_mqtt_client_handle_t (C++ type), 811 esp_mqtt_event_t::user_context (C++

esp_mqtt_client_init (C++ function), 805

member), 808

esp_mqtt_client_publish (C++ function), 806 esp_mqtt_protocol_ver_t (C++ enum), 813

esp_mqtt_client_reconnect (C++ function), esp_mqtt_set_config (C++ function), 807

805

esp_mqtt_transport_t (C++ enum), 813

esp_mqtt_client_register_event (C++ esp_netif_action_add_ip6_address (C++

function), 807

function), 487

esp_mqtt_client_set_uri (C++ function), 805 esp_netif_action_connected (C++ function),

esp_mqtt_client_start (C++ function), 805

486

esp_mqtt_client_stop (C++ function), 805

esp_netif_action_disconnected (C++ func-

esp_mqtt_client_subscribe (C++ function),

tion), 487

805

esp_netif_action_got_ip (C++ function), 487

esp_mqtt_client_unsubscribe (C++ func- esp_netif_action_join_ip6_multicast_group

tion), 806

(C++ function), 487

esp_mqtt_connect_return_code_t (C++ esp_netif_action_leave_ip6_multicast_group

enum), 812

(C++ function), 487

esp_mqtt_error_codes (C++ class), 807

esp_netif_action_remove_ip6_address

esp_mqtt_error_codes::connect_return_code

(C++ function), 487

Espressif Systems

2117

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_netif_action_start (C++ function), 486

489

esp_netif_action_stop (C++ function), 486 esp_netif_get_route_prio (C++ function),

esp_netif_attach (C++ function), 485

494

esp_netif_attach_wifi_ap (C++ function), esp_netif_init (C++ function), 484

495

esp_netif_is_netif_up (C++ function), 488

esp_netif_attach_wifi_station (C++ func- esp_netif_netstack_buf_free (C++ func-

tion), 495

tion), 495

esp_netif_create_default_wifi_ap (C++ esp_netif_netstack_buf_ref (C++ function),

function), 496

495

esp_netif_create_default_wifi_mesh_netiefssp_netif_new (C++ function), 484

(C++ function), 496

esp_netif_next (C++ function), 494

esp_netif_create_default_wifi_sta

esp_netif_post_transmit_hook_attach

(C++ function), 496

(C++ function), 485

esp_netif_create_ip6_linklocal (C++ esp_netif_post_transmit_hook_detach

function), 492

(C++ function), 486

esp_netif_create_wifi (C++ function), 496 esp_netif_receive (C++ function), 485

esp_netif_deinit (C++ function), 484

esp_netif_recv_hook_attach (C++ function),

esp_netif_destroy (C++ function), 484

485

esp_netif_destroy_default_wifi (C++ esp_netif_recv_hook_detach (C++ function),

function), 496

486

esp_netif_dhcpc_get_status (C++ function), esp_netif_set_dns_info (C++ function), 491

491

esp_netif_set_driver_config (C++ func-

esp_netif_dhcpc_option (C++ function), 490

tion), 484

esp_netif_dhcpc_start (C++ function), 490 esp_netif_set_hostname (C++ function), 488

esp_netif_dhcpc_stop (C++ function), 491

esp_netif_set_ip4_addr (C++ function), 493

esp_netif_dhcps_get_status (C++ function), esp_netif_set_ip_info (C++ function), 489

491

esp_netif_set_mac (C++ function), 488

esp_netif_dhcps_option (C++ function), 490 esp_netif_set_old_ip_info (C++ function),

esp_netif_dhcps_start (C++ function), 491

489

esp_netif_dhcps_stop (C++ function), 491

esp_netif_str_to_ip4 (C++ function), 493

esp_netif_free_rx_buffer (C++ function), esp_netif_str_to_ip6 (C++ function), 493

499

esp_netif_transmit (C++ function), 499

esp_netif_get_all_ip6 (C++ function), 493 esp_netif_transmit_hook_attach (C++

esp_netif_get_desc (C++ function), 494

function), 485

esp_netif_get_dns_info (C++ function), 492 esp_netif_transmit_hook_detach (C++

esp_netif_get_event_id (C++ function), 494

function), 486

esp_netif_get_flags (C++ function), 494

esp_netif_transmit_wrap (C++ function), 499

esp_netif_get_handle_from_ifkey (C++ esp_nimble_hci_and_controller_deinit

function), 494

(C++ function), 156

esp_netif_get_handle_from_netif_impl esp_nimble_hci_and_controller_init

(C++ function), 499

(C++ function), 155

esp_netif_get_hostname (C++ function), 488 esp_nimble_hci_deinit (C++ function), 156

esp_netif_get_ifkey (C++ function), 494

esp_nimble_hci_init (C++ function), 155

esp_netif_get_io_driver (C++ function), 494 esp_now_add_peer (C++ function), 413

esp_netif_get_ip6_global (C++ function), esp_now_deinit (C++ function), 412

493

esp_now_del_peer (C++ function), 413

esp_netif_get_ip6_linklocal (C++ func- ESP_NOW_ETH_ALEN (C macro), 416

tion), 492

esp_now_fetch_peer (C++ function), 414

esp_netif_get_ip_info (C++ function), 488 esp_now_get_peer (C++ function), 414

esp_netif_get_mac (C++ function), 488

esp_now_get_peer_num (C++ function), 414

esp_netif_get_netif_impl (C++ function), esp_now_get_version (C++ function), 412

499

esp_now_init (C++ function), 412

esp_netif_get_netif_impl_index (C++ esp_now_is_peer_exist (C++ function), 414

function), 490

ESP_NOW_KEY_LEN (C macro), 416

esp_netif_get_netif_impl_name (C++ func- ESP_NOW_MAX_DATA_LEN (C macro), 416

tion), 490

ESP_NOW_MAX_ENCRYPT_PEER_NUM (C macro),

esp_netif_get_nr_of_ifs (C++ function), 494

416

esp_netif_get_old_ip_info (C++ function), ESP_NOW_MAX_TOTAL_PEER_NUM (C macro), 416

Espressif Systems

2118

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_now_mod_peer (C++ function), 414

esp_openthread_launch_mainloop (C++

esp_now_peer_info (C++ class), 415

function), 475

esp_now_peer_info::channel (C++ member), esp_openthread_lock_acquire (C++ func-

415

tion), 478

esp_now_peer_info::encrypt (C++ member), esp_openthread_lock_deinit (C++ function),

415

478

esp_now_peer_info::ifidx (C++ member), esp_openthread_lock_init (C++ function),

415

478

esp_now_peer_info::lmk (C++ member), 415 esp_openthread_lock_release (C++ func-

esp_now_peer_info::peer_addr (C++ mem-

tion), 478

ber), 415

esp_openthread_mainloop_context_t

esp_now_peer_info::priv (C++ member), 415

(C++ class), 475

esp_now_peer_info_t (C++ type), 416

esp_openthread_mainloop_context_t::error_fds

esp_now_peer_num (C++ class), 415

(C++ member), 475

esp_now_peer_num::encrypt_num (C++ esp_openthread_mainloop_context_t::max_fd

member), 415

(C++ member), 476

esp_now_peer_num::total_num (C++ mem- esp_openthread_mainloop_context_t::read_fds

ber), 415

(C++ member), 475

esp_now_peer_num_t (C++ type), 416

esp_openthread_mainloop_context_t::timeout

esp_now_recv_cb_t (C++ type), 416

(C++ member), 476

esp_now_register_recv_cb (C++ function), esp_openthread_mainloop_context_t::write_fds

412

(C++ member), 475

esp_now_register_send_cb (C++ function), esp_openthread_netif_glue_deinit (C++

413

function), 478

esp_now_send (C++ function), 413

esp_openthread_netif_glue_init (C++

esp_now_send_cb_t (C++ type), 416

function), 478

ESP_NOW_SEND_FAIL (C++ enumerator), 417

esp_openthread_platform_config_t (C++

esp_now_send_status_t (C++ enum), 417

class), 476

ESP_NOW_SEND_SUCCESS (C++ enumerator), 417 esp_openthread_platform_config_t::host_config

esp_now_set_pmk (C++ function), 414

(C++ member), 477

esp_now_set_wake_window (C++ function), 415 esp_openthread_platform_config_t::port_config

esp_now_unregister_recv_cb (C++ function),

(C++ member), 477

413

esp_openthread_platform_config_t::radio_config

esp_now_unregister_send_cb (C++ function),

(C++ member), 477

413

esp_openthread_port_config_t (C++ class),

ESP_OK (C macro), 1121

476

ESP_OK_EFUSE_CNT (C macro), 1119

esp_openthread_port_config_t::netif_queue_size

esp_openthread_border_router_deinit

(C++ member), 476

(C++ function), 479

esp_openthread_port_config_t::storage_partition_n

esp_openthread_border_router_init

(C++ member), 476

(C++ function), 479

esp_openthread_port_config_t::task_queue_size

esp_openthread_deinit (C++ function), 475

(C++ member), 476

esp_openthread_event_t (C++ enum), 477

esp_openthread_radio_config_t (C++

esp_openthread_get_backbone_netif

class), 476

(C++ function), 479

esp_openthread_radio_config_t::radio_mode

esp_openthread_get_instance (C++ func-

(C++ member), 476

tion), 475

esp_openthread_radio_config_t::radio_uart_config

esp_openthread_get_netif (C++ function),

(C++ member), 476

478

esp_openthread_radio_mode_t (C++ enum),

esp_openthread_host_connection_config_t

477

(C++ class), 476

esp_openthread_set_backbone_netif

esp_openthread_host_connection_config_t::host_(Cc+o+nnfeunccttiioon)n, _4m79ode

(C++ member), 476

esp_openthread_uart_config_t (C++ class),

esp_openthread_host_connection_config_t::host_4u76art_config

(C++ member), 476

esp_openthread_uart_config_t::port

esp_openthread_host_connection_mode_t

(C++ member), 476

(C++ enum), 477

esp_openthread_uart_config_t::rx_pin

esp_openthread_init (C++ function), 475

(C++ member), 476

Espressif Systems

2119

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_openthread_uart_config_t::tx_pin esp_partition_mmap (C++ function), 1055

(C++ member), 476

esp_partition_next (C++ function), 1053

esp_openthread_uart_config_t::uart_confeisgp_partition_read (C++ function), 1053

(C++ member), 476

esp_partition_read_raw (C++ function), 1054

esp_ota_abort (C++ function), 1325

esp_partition_register_external (C++

esp_ota_begin (C++ function), 1323

function), 1056

esp_ota_check_rollback_is_possible

ESP_PARTITION_SUBTYPE_ANY (C++ enumera-

(C++ function), 1327

tor), 1059

esp_ota_end (C++ function), 1324

ESP_PARTITION_SUBTYPE_APP_FACTORY

esp_ota_erase_last_boot_app_partition

(C++ enumerator), 1057

(C++ function), 1327

ESP_PARTITION_SUBTYPE_APP_OTA_0 (C++

esp_ota_get_app_description (C++ func-

enumerator), 1058

tion), 1323

ESP_PARTITION_SUBTYPE_APP_OTA_1 (C++

esp_ota_get_app_elf_sha256 (C++ function),

enumerator), 1058

1323

ESP_PARTITION_SUBTYPE_APP_OTA_10 (C++

esp_ota_get_app_partition_count (C++

enumerator), 1058

function), 1326

ESP_PARTITION_SUBTYPE_APP_OTA_11 (C++

esp_ota_get_boot_partition (C++ function),

enumerator), 1058

1325

ESP_PARTITION_SUBTYPE_APP_OTA_12 (C++

esp_ota_get_last_invalid_partition

enumerator), 1058

(C++ function), 1326

ESP_PARTITION_SUBTYPE_APP_OTA_13 (C++

esp_ota_get_next_update_partition

enumerator), 1058

(C++ function), 1326

ESP_PARTITION_SUBTYPE_APP_OTA_14 (C++

esp_ota_get_partition_description

enumerator), 1058

(C++ function), 1326

ESP_PARTITION_SUBTYPE_APP_OTA_15 (C++

esp_ota_get_running_partition (C++ func-

enumerator), 1058

tion), 1325

ESP_PARTITION_SUBTYPE_APP_OTA_2 (C++

esp_ota_get_state_partition (C++ func-

enumerator), 1058

tion), 1327

ESP_PARTITION_SUBTYPE_APP_OTA_3 (C++

esp_ota_handle_t (C++ type), 1328

enumerator), 1058

esp_ota_mark_app_invalid_rollback_and_rEeSbPo_oPtARTITION_SUBTYPE_APP_OTA_4 (C++

(C++ function), 1326

enumerator), 1058

esp_ota_mark_app_valid_cancel_rollback ESP_PARTITION_SUBTYPE_APP_OTA_5 (C++

(C++ function), 1326

enumerator), 1058

esp_ota_revoke_secure_boot_public_key ESP_PARTITION_SUBTYPE_APP_OTA_6 (C++

(C++ function), 1327

enumerator), 1058

esp_ota_secure_boot_public_key_index_t ESP_PARTITION_SUBTYPE_APP_OTA_7 (C++

(C++ enum), 1328

enumerator), 1058

esp_ota_set_boot_partition (C++ function), ESP_PARTITION_SUBTYPE_APP_OTA_8 (C++

1325

enumerator), 1058

esp_ota_write (C++ function), 1324

ESP_PARTITION_SUBTYPE_APP_OTA_9 (C++

esp_ota_write_with_offset (C++ function),

enumerator), 1058

1324

ESP_PARTITION_SUBTYPE_APP_OTA_MAX

esp_partition_check_identity (C++ func-

(C++ enumerator), 1058

tion), 1056

ESP_PARTITION_SUBTYPE_APP_OTA_MIN

esp_partition_deregister_external

(C++ enumerator), 1057

(C++ function), 1056

ESP_PARTITION_SUBTYPE_APP_TEST (C++

esp_partition_erase_range (C++ function),

enumerator), 1058

1055

ESP_PARTITION_SUBTYPE_DATA_COREDUMP

esp_partition_find (C++ function), 1052

(C++ enumerator), 1058

esp_partition_find_first (C++ function), ESP_PARTITION_SUBTYPE_DATA_EFUSE_EM

1053

(C++ enumerator), 1059

esp_partition_get (C++ function), 1053

ESP_PARTITION_SUBTYPE_DATA_ESPHTTPD

esp_partition_get_sha256 (C++ function),

(C++ enumerator), 1059

1055

ESP_PARTITION_SUBTYPE_DATA_FAT (C++

esp_partition_iterator_release (C++

enumerator), 1059

function), 1053

ESP_PARTITION_SUBTYPE_DATA_NVS (C++

esp_partition_iterator_t (C++ type), 1057

enumerator), 1058

Espressif Systems

2120

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

ESP_PARTITION_SUBTYPE_DATA_NVS_KEYS (C++ enumerator), 1058
ESP_PARTITION_SUBTYPE_DATA_OTA (C++ enumerator), 1058
ESP_PARTITION_SUBTYPE_DATA_PHY (C++ enumerator), 1058
ESP_PARTITION_SUBTYPE_DATA_SPIFFS (C++ enumerator), 1059
ESP_PARTITION_SUBTYPE_DATA_UNDEFINED (C++ enumerator), 1059
ESP_PARTITION_SUBTYPE_OTA (C macro), 1057 esp_partition_subtype_t (C++ enum), 1057 esp_partition_t (C++ class), 1056 esp_partition_t::address (C++ member),
1057 esp_partition_t::encrypted (C++ member),
1057 esp_partition_t::flash_chip (C++ mem-
ber), 1057 esp_partition_t::label (C++ member), 1057 esp_partition_t::size (C++ member), 1057 esp_partition_t::subtype (C++ member),
1057 esp_partition_t::type (C++ member), 1057 ESP_PARTITION_TYPE_ANY (C++ enumerator),
1057 ESP_PARTITION_TYPE_APP (C++ enumerator),
1057 ESP_PARTITION_TYPE_DATA (C++ enumerator),
1057 esp_partition_type_t (C++ enum), 1057 esp_partition_verify (C++ function), 1053 esp_partition_write (C++ function), 1054 esp_partition_write_raw (C++ function),
1054 ESP_PD_DOMAIN_CPU (C++ enumerator), 1348 ESP_PD_DOMAIN_MAX (C++ enumerator), 1348 ESP_PD_DOMAIN_RTC8M (C++ enumerator), 1348 ESP_PD_DOMAIN_RTC_FAST_MEM (C++ enumera-
tor), 1348 ESP_PD_DOMAIN_RTC_PERIPH (C++ enumerator),
1347 ESP_PD_DOMAIN_RTC_SLOW_MEM (C++ enumera-
tor), 1348 ESP_PD_DOMAIN_VDDSDIO (C++ enumerator),
1348 ESP_PD_DOMAIN_XTAL (C++ enumerator), 1348 ESP_PD_OPTION_AUTO (C++ enumerator), 1348 ESP_PD_OPTION_OFF (C++ enumerator), 1348 ESP_PD_OPTION_ON (C++ enumerator), 1348 esp_ping_callbacks_t (C++ class), 891 esp_ping_callbacks_t::cb_args (C++
member), 892 esp_ping_callbacks_t::on_ping_end
(C++ member), 892 esp_ping_callbacks_t::on_ping_success
(C++ member), 892 esp_ping_callbacks_t::on_ping_timeout

(C++ member), 892 esp_ping_config_t (C++ class), 892 esp_ping_config_t::count (C++ member),
892 esp_ping_config_t::data_size (C++ mem-
ber), 892 esp_ping_config_t::interface (C++ mem-
ber), 892 esp_ping_config_t::interval_ms (C++
member), 892 esp_ping_config_t::target_addr (C++
member), 892 esp_ping_config_t::task_prio (C++ mem-
ber), 892 esp_ping_config_t::task_stack_size
(C++ member), 892 esp_ping_config_t::timeout_ms (C++
member), 892 esp_ping_config_t::tos (C++ member), 892 ESP_PING_COUNT_INFINITE (C macro), 892 ESP_PING_DEFAULT_CONFIG (C macro), 892 esp_ping_delete_session (C++ function), 891 esp_ping_get_profile (C++ function), 891 esp_ping_handle_t (C++ type), 892 esp_ping_new_session (C++ function), 891 ESP_PING_PROF_DURATION (C++ enumerator),
893 ESP_PING_PROF_IPADDR (C++ enumerator), 893 ESP_PING_PROF_REPLY (C++ enumerator), 893 ESP_PING_PROF_REQUEST (C++ enumerator), 893 ESP_PING_PROF_SEQNO (C++ enumerator), 892 ESP_PING_PROF_SIZE (C++ enumerator), 893 ESP_PING_PROF_TIMEGAP (C++ enumerator), 893 ESP_PING_PROF_TTL (C++ enumerator), 893 esp_ping_profile_t (C++ enum), 892 esp_ping_start (C++ function), 891 esp_ping_stop (C++ function), 891 ESP_PM_APB_FREQ_MAX (C++ enumerator), 1337 esp_pm_config_esp32s3_t (C++ class), 1337 esp_pm_config_esp32s3_t::light_sleep_enable
(C++ member), 1337 esp_pm_config_esp32s3_t::max_freq_mhz
(C++ member), 1337 esp_pm_config_esp32s3_t::min_freq_mhz
(C++ member), 1337 esp_pm_configure (C++ function), 1335 ESP_PM_CPU_FREQ_MAX (C++ enumerator), 1337 esp_pm_dump_locks (C++ function), 1337 esp_pm_get_configuration (C++ function),
1335 esp_pm_lock_acquire (C++ function), 1336 esp_pm_lock_create (C++ function), 1335 esp_pm_lock_delete (C++ function), 1336 esp_pm_lock_handle_t (C++ type), 1337 esp_pm_lock_release (C++ function), 1336 esp_pm_lock_type_t (C++ enum), 1337 ESP_PM_NO_LIGHT_SLEEP (C++ enumerator),
1337

Espressif Systems

2121

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_power_level_t (C++ enum), 55

ESP_RST_EXT (C++ enumerator), 1315

esp_pthread_cfg_t (C++ class), 1129

ESP_RST_INT_WDT (C++ enumerator), 1315

esp_pthread_cfg_t::inherit_cfg (C++ ESP_RST_PANIC (C++ enumerator), 1315

member), 1129

ESP_RST_POWERON (C++ enumerator), 1315

esp_pthread_cfg_t::pin_to_core (C++ ESP_RST_SDIO (C++ enumerator), 1315

member), 1129

ESP_RST_SW (C++ enumerator), 1315

esp_pthread_cfg_t::prio (C++ member), ESP_RST_TASK_WDT (C++ enumerator), 1315

1129

ESP_RST_UNKNOWN (C++ enumerator), 1315

esp_pthread_cfg_t::stack_size (C++ ESP_RST_WDT (C++ enumerator), 1315

member), 1129

ESP_SCO_DATA_PATH_HCI (C++ enumerator), 56

esp_pthread_cfg_t::thread_name (C++ ESP_SCO_DATA_PATH_PCM (C++ enumerator), 56

member), 1129

esp_sco_data_path_t (C++ enum), 56

esp_pthread_get_cfg (C++ function), 1129

esp_secure_boot_read_key_digests (C++

esp_pthread_get_default_config (C++

function), 1119

function), 1129

esp_service_source_t (C++ enum), 115

esp_pthread_init (C++ function), 1129

esp_set_deep_sleep_wake_stub (C++ func-

esp_pthread_set_cfg (C++ function), 1129

tion), 1347

ESP_PWR_LVL_N0 (C++ enumerator), 56

esp_sleep_config_gpio_isolate (C++ func-

ESP_PWR_LVL_N11 (C++ enumerator), 56

tion), 1347

ESP_PWR_LVL_N12 (C++ enumerator), 56

esp_sleep_cpu_pd_low_init (C++ function),

ESP_PWR_LVL_N14 (C++ enumerator), 56

1347

ESP_PWR_LVL_N2 (C++ enumerator), 56

esp_sleep_disable_wakeup_source (C++

ESP_PWR_LVL_N3 (C++ enumerator), 56

function), 1343

ESP_PWR_LVL_N5 (C++ enumerator), 56

esp_sleep_disable_wifi_wakeup (C++ func-

ESP_PWR_LVL_N6 (C++ enumerator), 56

tion), 1345

ESP_PWR_LVL_N8 (C++ enumerator), 56

esp_sleep_enable_ext0_wakeup (C++ func-

ESP_PWR_LVL_N9 (C++ enumerator), 56

tion), 1344

ESP_PWR_LVL_P1 (C++ enumerator), 56

esp_sleep_enable_ext1_wakeup (C++ func-

ESP_PWR_LVL_P3 (C++ enumerator), 56

tion), 1344

ESP_PWR_LVL_P4 (C++ enumerator), 56

esp_sleep_enable_gpio_switch (C++ func-

ESP_PWR_LVL_P6 (C++ enumerator), 56

tion), 1347

ESP_PWR_LVL_P7 (C++ enumerator), 56

esp_sleep_enable_gpio_wakeup (C++ func-

ESP_PWR_LVL_P9 (C++ enumerator), 56

tion), 1345

esp_random (C++ function), 1339

esp_sleep_enable_timer_wakeup (C++ func-

esp_read_mac (C++ function), 1317

tion), 1344

esp_register_freertos_idle_hook (C++ esp_sleep_enable_touchpad_wakeup (C++

function), 1266

function), 1344

esp_register_freertos_idle_hook_for_cpuesp_sleep_enable_uart_wakeup (C++ func-

(C++ function), 1266

tion), 1345

esp_register_freertos_tick_hook (C++ esp_sleep_enable_ulp_wakeup (C++ func-

function), 1266

tion), 1343

esp_register_freertos_tick_hook_for_cpuesp_sleep_enable_wifi_wakeup (C++ func-

(C++ function), 1266

tion), 1345

esp_register_shutdown_handler (C++ func- esp_sleep_ext1_wakeup_mode_t (C++ enum),

tion), 1314

1347

esp_reset_reason (C++ function), 1314

esp_sleep_get_ext1_wakeup_status (C++

esp_reset_reason_t (C++ enum), 1315

function), 1346

esp_restart (C++ function), 1314

esp_sleep_get_touchpad_wakeup_status

esp_rom_delay_us (C++ function), 1357

(C++ function), 1344

esp_rom_get_reset_reason (C++ function), esp_sleep_get_wakeup_cause (C++ function),

1357

1346

esp_rom_install_channel_putc (C++ func- esp_sleep_is_valid_wakeup_gpio (C++

tion), 1357

function), 1344

esp_rom_install_uart_printf (C++ func- esp_sleep_pd_config (C++ function), 1346

tion), 1357

esp_sleep_pd_domain_t (C++ enum), 1347

esp_rom_printf (C++ function), 1357

esp_sleep_pd_option_t (C++ enum), 1348

ESP_RST_BROWNOUT (C++ enumerator), 1315

esp_sleep_source_t (C++ enum), 1348

ESP_RST_DEEPSLEEP (C++ enumerator), 1315

ESP_SLEEP_WAKEUP_ALL (C++ enumerator), 1348

Espressif Systems

2122

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

ESP_SLEEP_WAKEUP_BT (C++ enumerator), 1349 esp_sleep_wakeup_cause_t (C++ type), 1347 ESP_SLEEP_WAKEUP_COCPU (C++ enumerator),
1349 ESP_SLEEP_WAKEUP_COCPU_TRAP_TRIG (C++
enumerator), 1349 ESP_SLEEP_WAKEUP_EXT0 (C++ enumerator),
1348 ESP_SLEEP_WAKEUP_EXT1 (C++ enumerator),
1348 ESP_SLEEP_WAKEUP_GPIO (C++ enumerator),
1348 ESP_SLEEP_WAKEUP_TIMER (C++ enumerator),
1348 ESP_SLEEP_WAKEUP_TOUCHPAD (C++ enumera-
tor), 1348 ESP_SLEEP_WAKEUP_UART (C++ enumerator),
1348 ESP_SLEEP_WAKEUP_ULP (C++ enumerator), 1348 ESP_SLEEP_WAKEUP_UNDEFINED (C++ enumera-
tor), 1348 ESP_SLEEP_WAKEUP_WIFI (C++ enumerator),
1349 esp_smartconfig_fast_mode (C++ function),
409 esp_smartconfig_get_rvd_data (C++ func-
tion), 409 esp_smartconfig_get_version (C++ func-
tion), 408 esp_smartconfig_set_type (C++ function),
409 esp_smartconfig_start (C++ function), 408 esp_smartconfig_stop (C++ function), 408 esp_spiffs_format (C++ function), 1063 esp_spiffs_info (C++ function), 1063 esp_spiffs_mounted (C++ function), 1063 esp_supp_dpp_bootstrap_gen (C++ function),
450 esp_supp_dpp_bootstrap_t (C++ type), 451 ESP_SUPP_DPP_CFG_RECVD (C++ enumerator),
451 esp_supp_dpp_deinit (C++ function), 450 esp_supp_dpp_event_cb_t (C++ type), 451 esp_supp_dpp_event_t (C++ enum), 451 ESP_SUPP_DPP_FAIL (C++ enumerator), 451 esp_supp_dpp_init (C++ function), 450 esp_supp_dpp_start_listen (C++ function),
450 esp_supp_dpp_stop_listen (C++ function),
451 ESP_SUPP_DPP_URI_READY (C++ enumerator),
451 esp_system_abort (C++ function), 1315 esp_sysview_flush (C++ function), 1089 esp_sysview_heap_trace_alloc (C++ func-
tion), 1089 esp_sysview_heap_trace_free (C++ func-
tion), 1089

esp_sysview_heap_trace_start (C++ function), 1089
esp_sysview_heap_trace_stop (C++ function), 1089
esp_sysview_vprintf (C++ function), 1089 esp_task_wdt_add (C++ function), 1351 esp_task_wdt_deinit (C++ function), 1351 esp_task_wdt_delete (C++ function), 1352 esp_task_wdt_init (C++ function), 1351 esp_task_wdt_reset (C++ function), 1352 esp_task_wdt_status (C++ function), 1352 esp_timer_cb_t (C++ type), 1294 esp_timer_create (C++ function), 1291 esp_timer_create_args_t (C++ class), 1293 esp_timer_create_args_t::arg (C++ mem-
ber), 1293 esp_timer_create_args_t::callback
(C++ member), 1293 esp_timer_create_args_t::dispatch_method
(C++ member), 1293 esp_timer_create_args_t::name (C++
member), 1294 esp_timer_create_args_t::skip_unhandled_events
(C++ member), 1294 esp_timer_deinit (C++ function), 1291 esp_timer_delete (C++ function), 1292 esp_timer_dispatch_t (C++ enum), 1294 esp_timer_dump (C++ function), 1293 esp_timer_early_init (C++ function), 1291 esp_timer_get_expiry_time (C++ function),
1293 esp_timer_get_next_alarm (C++ function),
1292 esp_timer_get_next_alarm_for_wake_up
(C++ function), 1292 esp_timer_get_period (C++ function), 1292 esp_timer_get_time (C++ function), 1292 esp_timer_handle_t (C++ type), 1294 esp_timer_init (C++ function), 1291 esp_timer_is_active (C++ function), 1293 ESP_TIMER_MAX (C++ enumerator), 1294 esp_timer_start_once (C++ function), 1291 esp_timer_start_periodic (C++ function),
1291 esp_timer_stop (C++ function), 1292 ESP_TIMER_TASK (C++ enumerator), 1294 esp_tls (C++ class), 822 esp_tls::cacert (C++ member), 822 esp_tls::cacert_ptr (C++ member), 822 esp_tls::clientcert (C++ member), 822 esp_tls::clientkey (C++ member), 822 esp_tls::conf (C++ member), 822 esp_tls::conn_state (C++ member), 822 esp_tls::ctr_drbg (C++ member), 822 esp_tls::entropy (C++ member), 822 esp_tls::error_handle (C++ member), 823 esp_tls::is_tls (C++ member), 823 esp_tls::read (C++ member), 822

Espressif Systems

2123

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_tls::role (C++ member), 823 esp_tls::rset (C++ member), 822 esp_tls::server_fd (C++ member), 822 esp_tls::sockfd (C++ member), 822 esp_tls::ssl (C++ member), 822 esp_tls::write (C++ member), 822 esp_tls::wset (C++ member), 823 esp_tls_cfg (C++ class), 820 esp_tls_cfg::alpn_protos (C++ member),
820 esp_tls_cfg::cacert_buf (C++ member), 821 esp_tls_cfg::cacert_bytes (C++ member),
821 esp_tls_cfg::cacert_pem_buf (C++ mem-
ber), 821 esp_tls_cfg::cacert_pem_bytes (C++
member), 821 esp_tls_cfg::clientcert_buf (C++ mem-
ber), 821 esp_tls_cfg::clientcert_bytes (C++
member), 821 esp_tls_cfg::clientcert_pem_buf (C++
member), 821 esp_tls_cfg::clientcert_pem_bytes
(C++ member), 821 esp_tls_cfg::clientkey_buf (C++ member),
821 esp_tls_cfg::clientkey_bytes (C++ mem-
ber), 821 esp_tls_cfg::clientkey_password (C++
member), 821 esp_tls_cfg::clientkey_password_len
(C++ member), 821 esp_tls_cfg::clientkey_pem_buf (C++
member), 821 esp_tls_cfg::clientkey_pem_bytes (C++
member), 821 esp_tls_cfg::common_name (C++ member),
821 esp_tls_cfg::crt_bundle_attach (C++
member), 822 esp_tls_cfg::ds_data (C++ member), 822 esp_tls_cfg::if_name (C++ member), 822 esp_tls_cfg::is_plain_tcp (C++ member),
822 esp_tls_cfg::keep_alive_cfg (C++ mem-
ber), 821 esp_tls_cfg::non_block (C++ member), 821 esp_tls_cfg::psk_hint_key (C++ member),
822 esp_tls_cfg::skip_common_name (C++
member), 821 esp_tls_cfg::timeout_ms (C++ member), 821 esp_tls_cfg::use_global_ca_store (C++
member), 821 esp_tls_cfg::use_secure_element (C++
member), 821 esp_tls_cfg_t (C++ type), 823

ESP_TLS_CLIENT (C++ enumerator), 823 esp_tls_conn_delete (C++ function), 818 esp_tls_conn_destroy (C++ function), 818 esp_tls_conn_http_new (C++ function), 816 esp_tls_conn_http_new_async (C++ func-
tion), 817 esp_tls_conn_new (C++ function), 816 esp_tls_conn_new_async (C++ function), 817 esp_tls_conn_new_sync (C++ function), 816 esp_tls_conn_read (C++ function), 817 esp_tls_conn_state (C++ enum), 823 esp_tls_conn_state_t (C++ type), 823 esp_tls_conn_write (C++ function), 817 ESP_TLS_CONNECTING (C++ enumerator), 823 ESP_TLS_DONE (C++ enumerator), 823 ESP_TLS_FAIL (C++ enumerator), 823 esp_tls_free_global_ca_store (C++ func-
tion), 819 esp_tls_get_and_clear_error_type (C++
function), 819 esp_tls_get_and_clear_last_error (C++
function), 819 esp_tls_get_bytes_avail (C++ function), 818 esp_tls_get_conn_sockfd (C++ function), 818 esp_tls_get_global_ca_store (C++ func-
tion), 819 ESP_TLS_HANDSHAKE (C++ enumerator), 823 ESP_TLS_INIT (C++ enumerator), 823 esp_tls_init (C++ function), 816 esp_tls_init_global_ca_store (C++ func-
tion), 818 esp_tls_plain_tcp_connect (C++ function),
819 esp_tls_role (C++ enum), 823 esp_tls_role_t (C++ type), 823 ESP_TLS_SERVER (C++ enumerator), 823 esp_tls_set_global_ca_store (C++ func-
tion), 818 esp_tls_t (C++ type), 823 esp_tusb_deinit_console (C++ function), 772 esp_tusb_init_console (C++ function), 772 esp_unregister_shutdown_handler (C++
function), 1314 ESP_UUID_LEN_128 (C macro), 58 ESP_UUID_LEN_16 (C macro), 58 ESP_UUID_LEN_32 (C macro), 58 esp_vendor_ie_cb_t (C++ type), 386 esp_vfs_close (C++ function), 1068 esp_vfs_dev_uart_port_set_rx_line_endings
(C++ function), 1075 esp_vfs_dev_uart_port_set_tx_line_endings
(C++ function), 1075 esp_vfs_dev_uart_register (C++ function),
1074 esp_vfs_dev_uart_set_rx_line_endings
(C++ function), 1074 esp_vfs_dev_uart_set_tx_line_endings
(C++ function), 1075

Espressif Systems

2124

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_vfs_dev_uart_use_driver (C++ func- esp_vfs_select_sem_t::is_sem_local

tion), 1075

(C++ member), 1070

esp_vfs_dev_uart_use_nonblocking (C++ esp_vfs_select_sem_t::sem (C++ member),

function), 1075

1070

ESP_VFS_EVENTD_CONFIG_DEFAULT (C macro), esp_vfs_select_triggered (C++ function),

1076

1070

esp_vfs_eventfd_config_t (C++ class), 1076 esp_vfs_select_triggered_isr (C++ func-

esp_vfs_eventfd_config_t::max_fds

tion), 1070

(C++ member), 1076

esp_vfs_spiffs_conf_t (C++ class), 1063

esp_vfs_eventfd_register (C++ function), esp_vfs_spiffs_conf_t::base_path (C++

1076

member), 1063

esp_vfs_eventfd_unregister (C++ function), esp_vfs_spiffs_conf_t::format_if_mount_failed

1076

(C++ member), 1063

esp_vfs_fat_mount_config_t (C++ class), esp_vfs_spiffs_conf_t::max_files (C++

992, 1078

member), 1063

esp_vfs_fat_mount_config_t::allocation_eusnpi_tv_fssi_zsepiffs_conf_t::partition_label

(C++ member), 992, 1078

(C++ member), 1063

esp_vfs_fat_mount_config_t::format_if_meosupn_tv_ffsa_islpeidffs_register (C++ function),

(C++ member), 992, 1078

1062

esp_vfs_fat_mount_config_t::max_files esp_vfs_spiffs_unregister (C++ function),

(C++ member), 992, 1078

1062

esp_vfs_fat_rawflash_mount (C++ function), esp_vfs_stat (C++ function), 1068

993

esp_vfs_t (C++ class), 1070

esp_vfs_fat_rawflash_unmount (C++ func- esp_vfs_t::access (C++ member), 1073

tion), 993

esp_vfs_t::access_p (C++ member), 1073

esp_vfs_fat_register (C++ function), 990

esp_vfs_t::close (C++ member), 1071

esp_vfs_fat_sdcard_unmount (C++ function), esp_vfs_t::close_p (C++ member), 1071

992

esp_vfs_t::closedir (C++ member), 1072

esp_vfs_fat_sdmmc_mount (C++ function), 991 esp_vfs_t::closedir_p (C++ member), 1072

esp_vfs_fat_sdspi_mount (C++ function), 991 esp_vfs_t::end_select (C++ member), 1074

esp_vfs_fat_spiflash_mount (C++ function), esp_vfs_t::fcntl (C++ member), 1073

1077

esp_vfs_t::fcntl_p (C++ member), 1072

esp_vfs_fat_spiflash_unmount (C++ func- esp_vfs_t::flags (C++ member), 1071

tion), 1078

esp_vfs_t::fstat (C++ member), 1071

esp_vfs_fat_unregister_path (C++ func- esp_vfs_t::fstat_p (C++ member), 1071

tion), 990

esp_vfs_t::fsync (C++ member), 1073

ESP_VFS_FLAG_CONTEXT_PTR (C macro), 1074 esp_vfs_t::fsync_p (C++ member), 1073

ESP_VFS_FLAG_DEFAULT (C macro), 1074

esp_vfs_t::get_socket_select_semaphore

esp_vfs_fstat (C++ function), 1068

(C++ member), 1074

esp_vfs_id_t (C++ type), 1074

esp_vfs_t::ioctl (C++ member), 1073

esp_vfs_link (C++ function), 1068

esp_vfs_t::ioctl_p (C++ member), 1073

esp_vfs_lseek (C++ function), 1068

esp_vfs_t::link (C++ member), 1072

esp_vfs_open (C++ function), 1068

esp_vfs_t::link_p (C++ member), 1072

ESP_VFS_PATH_MAX (C macro), 1074

esp_vfs_t::lseek (C++ member), 1071

esp_vfs_pread (C++ function), 1070

esp_vfs_t::lseek_p (C++ member), 1071

esp_vfs_pwrite (C++ function), 1070

esp_vfs_t::mkdir (C++ member), 1072

esp_vfs_read (C++ function), 1068

esp_vfs_t::mkdir_p (C++ member), 1072

esp_vfs_register (C++ function), 1068

esp_vfs_t::open (C++ member), 1071

esp_vfs_register_fd (C++ function), 1069

esp_vfs_t::open_p (C++ member), 1071

esp_vfs_register_fd_range (C++ function), esp_vfs_t::opendir (C++ member), 1072

1068

esp_vfs_t::opendir_p (C++ member), 1072

esp_vfs_register_fd_with_local_fd

esp_vfs_t::pread (C++ member), 1071

(C++ function), 1069

esp_vfs_t::pread_p (C++ member), 1071

esp_vfs_register_with_id (C++ function), esp_vfs_t::pwrite (C++ member), 1071

1068

esp_vfs_t::pwrite_p (C++ member), 1071

esp_vfs_rename (C++ function), 1068

esp_vfs_t::read (C++ member), 1071

esp_vfs_select (C++ function), 1069

esp_vfs_t::read_p (C++ member), 1071

esp_vfs_select_sem_t (C++ class), 1070

esp_vfs_t::readdir (C++ member), 1072

Espressif Systems

2125

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_vfs_t::readdir_p (C++ member), 1072 esp_vfs_write (C++ function), 1068

esp_vfs_t::readdir_r (C++ member), 1072 esp_vhci_host_callback (C++ class), 54

esp_vfs_t::readdir_r_p (C++ member), 1072 esp_vhci_host_callback::notify_host_recv

esp_vfs_t::rename (C++ member), 1072

(C++ member), 54

esp_vfs_t::rename_p (C++ member), 1072

esp_vhci_host_callback::notify_host_send_availabl

esp_vfs_t::rmdir (C++ member), 1072

(C++ member), 54

esp_vfs_t::rmdir_p (C++ member), 1072

esp_vhci_host_callback_t (C++ type), 54

esp_vfs_t::seekdir (C++ member), 1072

esp_vhci_host_check_send_available

esp_vfs_t::seekdir_p (C++ member), 1072

(C++ function), 50

esp_vfs_t::socket_select (C++ member), esp_vhci_host_register_callback (C++

1074

function), 51

esp_vfs_t::start_select (C++ member), esp_vhci_host_send_packet (C++ function),

1074

51

esp_vfs_t::stat (C++ member), 1071

esp_wake_deep_sleep (C++ function), 1346

esp_vfs_t::stat_p (C++ member), 1071

esp_websocket_client_close (C++ function),

esp_vfs_t::stop_socket_select (C++

940

member), 1074

esp_websocket_client_close_with_code

esp_vfs_t::stop_socket_select_isr

(C++ function), 940

(C++ member), 1074

esp_websocket_client_config_t (C++

esp_vfs_t::tcdrain (C++ member), 1073

class), 941

esp_vfs_t::tcdrain_p (C++ member), 1073 esp_websocket_client_config_t::buffer_size

esp_vfs_t::tcflow (C++ member), 1073

(C++ member), 942

esp_vfs_t::tcflow_p (C++ member), 1073

esp_websocket_client_config_t::cert_len

esp_vfs_t::tcflush (C++ member), 1073

(C++ member), 942

esp_vfs_t::tcflush_p (C++ member), 1073 esp_websocket_client_config_t::cert_pem

esp_vfs_t::tcgetattr (C++ member), 1073

(C++ member), 942

esp_vfs_t::tcgetattr_p (C++ member), 1073 esp_websocket_client_config_t::client_cert

esp_vfs_t::tcgetsid (C++ member), 1073

(C++ member), 942

esp_vfs_t::tcgetsid_p (C++ member), 1073 esp_websocket_client_config_t::client_cert_len

esp_vfs_t::tcsendbreak (C++ member), 1074

(C++ member), 942

esp_vfs_t::tcsendbreak_p (C++ member), esp_websocket_client_config_t::client_key

1074

(C++ member), 942

esp_vfs_t::tcsetattr (C++ member), 1073 esp_websocket_client_config_t::client_key_len

esp_vfs_t::tcsetattr_p (C++ member), 1073

(C++ member), 942

esp_vfs_t::telldir (C++ member), 1072

esp_websocket_client_config_t::disable_auto_recon

esp_vfs_t::telldir_p (C++ member), 1072

(C++ member), 942

esp_vfs_t::truncate (C++ member), 1073

esp_websocket_client_config_t::disable_pingpong_d

esp_vfs_t::truncate_p (C++ member), 1073

(C++ member), 943

esp_vfs_t::unlink (C++ member), 1072

esp_websocket_client_config_t::headers

esp_vfs_t::unlink_p (C++ member), 1072

(C++ member), 943

esp_vfs_t::utime (C++ member), 1073

esp_websocket_client_config_t::host

esp_vfs_t::utime_p (C++ member), 1073

(C++ member), 942

esp_vfs_t::write (C++ member), 1071

esp_websocket_client_config_t::if_name

esp_vfs_t::write_p (C++ member), 1071

(C++ member), 943

esp_vfs_tusb_cdc_register (C++ function), esp_websocket_client_config_t::keep_alive_count

773

(C++ member), 943

esp_vfs_tusb_cdc_unregister (C++ func- esp_websocket_client_config_t::keep_alive_enable

tion), 773

(C++ member), 943

esp_vfs_unlink (C++ function), 1068

esp_websocket_client_config_t::keep_alive_idle

esp_vfs_unregister (C++ function), 1069

(C++ member), 943

esp_vfs_unregister_fd (C++ function), 1069 esp_websocket_client_config_t::keep_alive_interva

esp_vfs_unregister_with_id (C++ function),

(C++ member), 943

1069

esp_websocket_client_config_t::password

esp_vfs_usb_serial_jtag_use_driver

(C++ member), 942

(C++ function), 1075

esp_websocket_client_config_t::path

esp_vfs_usb_serial_jtag_use_nonblocking

(C++ member), 942

(C++ function), 1076

esp_websocket_client_config_t::ping_interval_sec

esp_vfs_utime (C++ function), 1068

(C++ member), 943

Espressif Systems

2126

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_websocket_client_config_t::pingponge_stpi_mweeobusto_cskeect_event_id_t (C++ enum), 943

(C++ member), 943

esp_websocket_register_events (C++ func-

esp_websocket_client_config_t::port

tion), 941

(C++ member), 942

esp_websocket_transport_t (C++ enum), 943

esp_websocket_client_config_t::skip_cerets_pc_owmimfoin__8n0a2m1e1__cthxe(cCk++ function), 378

(C++ member), 943

esp_wifi_ap_get_sta_aid (C++ function), 377

esp_websocket_client_config_t::subprotoecsopl_wifi_ap_get_sta_list (C++ function),

(C++ member), 942

377

esp_websocket_client_config_t::task_prieosp_wifi_bt_power_domain_off (C++ func-

(C++ member), 942

tion), 52

esp_websocket_client_config_t::task_staecskp_wifi_bt_power_domain_on (C++ func-

(C++ member), 942

tion), 52

esp_websocket_client_config_t::transporetsp_wifi_clear_default_wifi_driver_and_handlers

(C++ member), 942

(C++ function), 495

esp_websocket_client_config_t::uri

esp_wifi_clear_fast_connect (C++ func-

(C++ member), 942

tion), 371

esp_websocket_client_config_t::use_globeaslp__cwai_fsit_ocroenfig_11b_rate (C++ function),

(C++ member), 943

381

esp_websocket_client_config_t::user_ageenstp_wifi_config_80211_tx_rate (C++ func-

(C++ member), 942

tion), 383

esp_websocket_client_config_t::user_conetsepx_twifi_config_espnow_rate (C++ func-

(C++ member), 942

tion), 382

esp_websocket_client_config_t::usernameesp_wifi_connect (C++ function), 370

(C++ member), 942

esp_wifi_deauth_sta (C++ function), 371

esp_websocket_client_destroy (C++ func- esp_wifi_deinit (C++ function), 369

tion), 940

esp_wifi_disconnect (C++ function), 371

esp_websocket_client_handle_t (C++ esp_wifi_ftm_end_session (C++ function),

type), 943

381

esp_websocket_client_init (C++ function), esp_wifi_ftm_initiate_session (C++ func-

939

tion), 381

esp_websocket_client_is_connected

esp_wifi_ftm_resp_set_offset (C++ func-

(C++ function), 941

tion), 381

esp_websocket_client_send_bin (C++ func- esp_wifi_get_ant (C++ function), 380

tion), 940

esp_wifi_get_ant_gpio (C++ function), 380

esp_websocket_client_send_text (C++ esp_wifi_get_bandwidth (C++ function), 373

function), 940

esp_wifi_get_channel (C++ function), 374

esp_websocket_client_set_uri (C++ func- esp_wifi_get_config (C++ function), 376

tion), 939

esp_wifi_get_country (C++ function), 374

esp_websocket_client_start (C++ function), esp_wifi_get_country_code (C++ function),

939

382

esp_websocket_client_stop (C++ function), esp_wifi_get_event_mask (C++ function), 378

939

esp_wifi_get_inactive_time (C++ function),

esp_websocket_event_data_t (C++ class),

380

941

esp_wifi_get_mac (C++ function), 375

esp_websocket_event_data_t::client

esp_wifi_get_max_tx_power (C++ function),

(C++ member), 941

378

esp_websocket_event_data_t::data_len esp_wifi_get_mode (C++ function), 370

(C++ member), 941

esp_wifi_get_promiscuous (C++ function),

esp_websocket_event_data_t::data_ptr

375

(C++ member), 941

esp_wifi_get_promiscuous_ctrl_filter

esp_websocket_event_data_t::op_code

(C++ function), 376

(C++ member), 941

esp_wifi_get_promiscuous_filter (C++

esp_websocket_event_data_t::payload_len

function), 375

(C++ member), 941

esp_wifi_get_protocol (C++ function), 373

esp_websocket_event_data_t::payload_offessept_wifi_get_ps (C++ function), 372

(C++ member), 941

esp_wifi_get_tsf_time (C++ function), 380

esp_websocket_event_data_t::user_contexetsp_wifi_init (C++ function), 369

(C++ member), 941

ESP_WIFI_MAX_CONN_NUM (C macro), 399

Espressif Systems

2127

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

esp_wifi_restore (C++ function), 370

essl_handle_t (C++ type), 951

esp_wifi_scan_get_ap_num (C++ function), essl_init (C++ function), 948

372

essl_read_reg (C++ function), 950

esp_wifi_scan_get_ap_records (C++ func- essl_reset_cnt (C++ function), 949

tion), 372

essl_sdio_config_t (C++ class), 952

esp_wifi_scan_start (C++ function), 371

essl_sdio_config_t::card (C++ member),

esp_wifi_scan_stop (C++ function), 371

952

esp_wifi_set_ant (C++ function), 380

essl_sdio_config_t::recv_buffer_size

esp_wifi_set_ant_gpio (C++ function), 379

(C++ member), 952

esp_wifi_set_bandwidth (C++ function), 373 essl_sdio_deinit_dev (C++ function), 952

esp_wifi_set_channel (C++ function), 373

essl_sdio_init_dev (C++ function), 951

esp_wifi_set_config (C++ function), 376

essl_send_packet (C++ function), 949

esp_wifi_set_connectionless_wake_interveaslsl_send_slave_intr (C++ function), 951

(C++ function), 382

essl_set_intr_ena (C++ function), 951

esp_wifi_set_country (C++ function), 374

essl_spi_config_t (C++ class), 956

esp_wifi_set_country_code (C++ function), essl_spi_config_t::rx_sync_reg (C++

382

member), 956

esp_wifi_set_csi (C++ function), 379

essl_spi_config_t::spi (C++ member), 956

esp_wifi_set_csi_config (C++ function), 379 essl_spi_config_t::tx_buf_size (C++

esp_wifi_set_csi_rx_cb (C++ function), 379

member), 956

esp_wifi_set_default_wifi_ap_handlers essl_spi_config_t::tx_sync_reg (C++

(C++ function), 495

member), 956

esp_wifi_set_default_wifi_sta_handlers essl_spi_deinit_dev (C++ function), 952

(C++ function), 495

essl_spi_get_packet (C++ function), 953

esp_wifi_set_event_mask (C++ function), 378 essl_spi_init_dev (C++ function), 952

esp_wifi_set_inactive_time (C++ function), essl_spi_rdbuf (C++ function), 954

380

essl_spi_rdbuf_polling (C++ function), 954

esp_wifi_set_mac (C++ function), 374

essl_spi_rddma (C++ function), 955

esp_wifi_set_max_tx_power (C++ function), essl_spi_rddma_done (C++ function), 955

378

essl_spi_rddma_seg (C++ function), 955

esp_wifi_set_mode (C++ function), 369

essl_spi_read_reg (C++ function), 952

esp_wifi_set_promiscuous (C++ function), essl_spi_reset_cnt (C++ function), 953

375

essl_spi_send_packet (C++ function), 953

esp_wifi_set_promiscuous_ctrl_filter essl_spi_wrbuf (C++ function), 954

(C++ function), 376

essl_spi_wrbuf_polling (C++ function), 954

esp_wifi_set_promiscuous_filter (C++ essl_spi_wrdma (C++ function), 955

function), 375

essl_spi_wrdma_done (C++ function), 956

esp_wifi_set_promiscuous_rx_cb (C++ essl_spi_wrdma_seg (C++ function), 956

function), 375

essl_spi_write_reg (C++ function), 953

esp_wifi_set_protocol (C++ function), 372 essl_wait_for_ready (C++ function), 948

esp_wifi_set_ps (C++ function), 372

essl_wait_int (C++ function), 950

esp_wifi_set_rssi_threshold (C++ func- essl_write_reg (C++ function), 950

tion), 381

eStandardSleep (C++ enumerator), 1178

esp_wifi_set_storage (C++ function), 377

eSuspended (C++ enumerator), 1178

esp_wifi_set_vendor_ie (C++ function), 377 eTaskGetState (C++ function), 1156

esp_wifi_set_vendor_ie_cb (C++ function), eTaskState (C++ enum), 1178

377

ETH_CMD_G_AUTONEGO (C++ enumerator), 462

esp_wifi_sta_get_ap_info (C++ function), ETH_CMD_G_DUPLEX_MODE (C++ enumerator), 463

372

ETH_CMD_G_MAC_ADDR (C++ enumerator), 462

esp_wifi_start (C++ function), 370

ETH_CMD_G_PHY_ADDR (C++ enumerator), 462

esp_wifi_statis_dump (C++ function), 381

ETH_CMD_G_SPEED (C++ enumerator), 462

esp_wifi_stop (C++ function), 370

ETH_CMD_S_AUTONEGO (C++ enumerator), 462

essl_clear_intr (C++ function), 950

ETH_CMD_S_DUPLEX_MODE (C++ enumerator), 463

essl_get_intr (C++ function), 950

ETH_CMD_S_FLOW_CTRL (C++ enumerator), 463

essl_get_intr_ena (C++ function), 951

ETH_CMD_S_MAC_ADDR (C++ enumerator), 462

essl_get_packet (C++ function), 949

ETH_CMD_S_PHY_ADDR (C++ enumerator), 462

essl_get_rx_data_size (C++ function), 949 ETH_CMD_S_PHY_LOOPBACK (C++ enumerator),

essl_get_tx_buffer_num (C++ function), 948

463

Espressif Systems

2128

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

ETH_CMD_S_PROMISCUOUS (C++ enumerator), 462 ETH_CMD_S_SPEED (C++ enumerator), 462 ETH_DEFAULT_CONFIG (C macro), 462 eth_event_t (C++ enum), 464 eth_mac_clock_config_t (C++ union), 465 eth_mac_clock_config_t::clock_gpio
(C++ member), 465 eth_mac_clock_config_t::clock_mode
(C++ member), 465 eth_mac_clock_config_t::mii (C++ mem-
ber), 465 eth_mac_clock_config_t::rmii (C++ mem-
ber), 465 eth_mac_config_t (C++ class), 468 eth_mac_config_t::clock_config (C++
member), 469 eth_mac_config_t::flags (C++ member), 469 eth_mac_config_t::interface (C++ mem-
ber), 469 eth_mac_config_t::rx_task_prio (C++
member), 468 eth_mac_config_t::rx_task_stack_size
(C++ member), 468 eth_mac_config_t::smi_mdc_gpio_num
(C++ member), 469 eth_mac_config_t::smi_mdio_gpio_num
(C++ member), 469 eth_mac_config_t::sw_reset_timeout_ms
(C++ member), 468 ETH_MAC_DEFAULT_CONFIG (C macro), 469 ETH_MAC_FLAG_PIN_TO_CORE (C macro), 469 ETH_MAC_FLAG_WORK_WITH_CACHE_DISABLE
(C macro), 469 eth_phy_autoneg_cmd_t (C++ enum), 474 eth_phy_config_t (C++ class), 473 eth_phy_config_t::autonego_timeout_ms
(C++ member), 473 eth_phy_config_t::phy_addr (C++ member),
473 eth_phy_config_t::reset_gpio_num (C++
member), 473 eth_phy_config_t::reset_timeout_ms
(C++ member), 473 ETH_PHY_DEFAULT_CONFIG (C macro), 473 ETH_STATE_DEINIT (C++ enumerator), 464 ETH_STATE_DUPLEX (C++ enumerator), 464 ETH_STATE_LINK (C++ enumerator), 464 ETH_STATE_LLINIT (C++ enumerator), 464 ETH_STATE_PAUSE (C++ enumerator), 464 ETH_STATE_SPEED (C++ enumerator), 464 ETHERNET_EVENT_CONNECTED (C++ enumerator),
464 ETHERNET_EVENT_DISCONNECTED (C++ enumer-
ator), 465 ETHERNET_EVENT_START (C++ enumerator), 464 ETHERNET_EVENT_STOP (C++ enumerator), 464 ETS_INTERNAL_INTR_SOURCE_OFF (C macro),
1305

ETS_INTERNAL_PROFILING_INTR_SOURCE (C

macro), 1305

ETS_INTERNAL_SW0_INTR_SOURCE (C macro),

1305

ETS_INTERNAL_SW1_INTR_SOURCE (C macro),

1305

ETS_INTERNAL_TIMER0_INTR_SOURCE

(C

macro), 1305

ETS_INTERNAL_TIMER1_INTR_SOURCE

(C

macro), 1305

ETS_INTERNAL_TIMER2_INTR_SOURCE

(C

macro), 1305

EventBits_t (C++ type), 1234

eventfd (C++ function), 1076

EventGroupHandle_t (C++ type), 1234

F
FAST_PROV_ACT_ENTER (C++ enumerator), 205 FAST_PROV_ACT_EXIT (C++ enumerator), 205 FAST_PROV_ACT_MAX (C++ enumerator), 205 FAST_PROV_ACT_NONE (C++ enumerator), 205 FAST_PROV_ACT_SUSPEND (C++ enumerator), 205 ff_diskio_impl_t (C++ class), 993 ff_diskio_impl_t::init (C++ member), 994 ff_diskio_impl_t::ioctl (C++ member), 994 ff_diskio_impl_t::read (C++ member), 994 ff_diskio_impl_t::status (C++ member),
994 ff_diskio_impl_t::write (C++ member), 994 ff_diskio_register (C++ function), 993 ff_diskio_register_raw_partition (C++
function), 994 ff_diskio_register_sdmmc (C++ function),
994 ff_diskio_register_wl_partition (C++
function), 994 FTM_STATUS_CONF_REJECTED (C++ enumerator),
407 FTM_STATUS_FAIL (C++ enumerator), 408 FTM_STATUS_NO_RESPONSE (C++ enumerator),
408 FTM_STATUS_SUCCESS (C++ enumerator), 407 FTM_STATUS_UNSUPPORTED (C++ enumerator),
407

G
gpio_config (C++ function), 521 gpio_config_t (C++ class), 527 gpio_config_t::intr_type (C++ member),
528 gpio_config_t::mode (C++ member), 527 gpio_config_t::pin_bit_mask (C++ mem-
ber), 527 gpio_config_t::pull_down_en (C++ mem-
ber), 528 gpio_config_t::pull_up_en (C++ member),
527

Espressif Systems

2129

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

gpio_deep_sleep_hold_dis (C++ function), 526
gpio_deep_sleep_hold_en (C++ function), 526 GPIO_DRIVE_CAP_0 (C++ enumerator), 534 GPIO_DRIVE_CAP_1 (C++ enumerator), 534 GPIO_DRIVE_CAP_2 (C++ enumerator), 534 GPIO_DRIVE_CAP_3 (C++ enumerator), 534 GPIO_DRIVE_CAP_DEFAULT (C++ enumerator),
534 GPIO_DRIVE_CAP_MAX (C++ enumerator), 534 gpio_drive_cap_t (C++ enum), 534 GPIO_FLOATING (C++ enumerator), 534 gpio_force_hold_all (C++ function), 526 gpio_force_unhold_all (C++ function), 526 gpio_get_drive_capability (C++ function),
525 gpio_get_level (C++ function), 522 gpio_hold_dis (C++ function), 525 gpio_hold_en (C++ function), 525 gpio_install_isr_service (C++ function),
524 gpio_int_type_t (C++ enum), 533 GPIO_INTR_ANYEDGE (C++ enumerator), 533 GPIO_INTR_DISABLE (C++ enumerator), 533 gpio_intr_disable (C++ function), 522 gpio_intr_enable (C++ function), 522 GPIO_INTR_HIGH_LEVEL (C++ enumerator), 533 GPIO_INTR_LOW_LEVEL (C++ enumerator), 533 GPIO_INTR_MAX (C++ enumerator), 533 GPIO_INTR_NEGEDGE (C++ enumerator), 533 GPIO_INTR_POSEDGE (C++ enumerator), 533 gpio_iomux_in (C++ function), 526 gpio_iomux_out (C++ function), 526 GPIO_IS_VALID_GPIO (C macro), 527 GPIO_IS_VALID_OUTPUT_GPIO (C macro), 527 gpio_isr_handle_t (C++ type), 527 gpio_isr_handler_add (C++ function), 524 gpio_isr_handler_remove (C++ function), 525 gpio_isr_register (C++ function), 523 gpio_isr_t (C++ type), 531 GPIO_MODE_DISABLE (C++ enumerator), 533 GPIO_MODE_INPUT (C++ enumerator), 534 GPIO_MODE_INPUT_OUTPUT (C++ enumerator),
534 GPIO_MODE_INPUT_OUTPUT_OD (C++ enumera-
tor), 534 GPIO_MODE_OUTPUT (C++ enumerator), 534 GPIO_MODE_OUTPUT_OD (C++ enumerator), 534 gpio_mode_t (C++ enum), 533 GPIO_NUM_0 (C++ enumerator), 531 GPIO_NUM_1 (C++ enumerator), 531 GPIO_NUM_10 (C++ enumerator), 532 GPIO_NUM_11 (C++ enumerator), 532 GPIO_NUM_12 (C++ enumerator), 532 GPIO_NUM_13 (C++ enumerator), 532 GPIO_NUM_14 (C++ enumerator), 532 GPIO_NUM_15 (C++ enumerator), 532 GPIO_NUM_16 (C++ enumerator), 532

GPIO_NUM_17 (C++ enumerator), 532 GPIO_NUM_18 (C++ enumerator), 532 GPIO_NUM_19 (C++ enumerator), 532 GPIO_NUM_2 (C++ enumerator), 531 GPIO_NUM_20 (C++ enumerator), 532 GPIO_NUM_21 (C++ enumerator), 532 GPIO_NUM_26 (C++ enumerator), 532 GPIO_NUM_27 (C++ enumerator), 532 GPIO_NUM_28 (C++ enumerator), 532 GPIO_NUM_29 (C++ enumerator), 532 GPIO_NUM_3 (C++ enumerator), 531 GPIO_NUM_30 (C++ enumerator), 532 GPIO_NUM_31 (C++ enumerator), 532 GPIO_NUM_32 (C++ enumerator), 532 GPIO_NUM_33 (C++ enumerator), 532 GPIO_NUM_34 (C++ enumerator), 532 GPIO_NUM_35 (C++ enumerator), 532 GPIO_NUM_36 (C++ enumerator), 533 GPIO_NUM_37 (C++ enumerator), 533 GPIO_NUM_38 (C++ enumerator), 533 GPIO_NUM_39 (C++ enumerator), 533 GPIO_NUM_4 (C++ enumerator), 531 GPIO_NUM_40 (C++ enumerator), 533 GPIO_NUM_41 (C++ enumerator), 533 GPIO_NUM_42 (C++ enumerator), 533 GPIO_NUM_43 (C++ enumerator), 533 GPIO_NUM_44 (C++ enumerator), 533 GPIO_NUM_45 (C++ enumerator), 533 GPIO_NUM_46 (C++ enumerator), 533 GPIO_NUM_47 (C++ enumerator), 533 GPIO_NUM_48 (C++ enumerator), 533 GPIO_NUM_5 (C++ enumerator), 531 GPIO_NUM_6 (C++ enumerator), 531 GPIO_NUM_7 (C++ enumerator), 531 GPIO_NUM_8 (C++ enumerator), 531 GPIO_NUM_9 (C++ enumerator), 532 GPIO_NUM_MAX (C++ enumerator), 533 GPIO_NUM_NC (C++ enumerator), 531 gpio_num_t (C++ enum), 531 GPIO_PIN_COUNT (C macro), 527 GPIO_PIN_REG_0 (C macro), 530 GPIO_PIN_REG_1 (C macro), 530 GPIO_PIN_REG_10 (C macro), 530 GPIO_PIN_REG_11 (C macro), 530 GPIO_PIN_REG_12 (C macro), 530 GPIO_PIN_REG_13 (C macro), 530 GPIO_PIN_REG_14 (C macro), 530 GPIO_PIN_REG_15 (C macro), 530 GPIO_PIN_REG_16 (C macro), 530 GPIO_PIN_REG_17 (C macro), 530 GPIO_PIN_REG_18 (C macro), 530 GPIO_PIN_REG_19 (C macro), 530 GPIO_PIN_REG_2 (C macro), 530 GPIO_PIN_REG_20 (C macro), 530 GPIO_PIN_REG_21 (C macro), 530 GPIO_PIN_REG_22 (C macro), 530 GPIO_PIN_REG_23 (C macro), 530 GPIO_PIN_REG_24 (C macro), 530

Espressif Systems

2130

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

GPIO_PIN_REG_25 (C macro), 530 GPIO_PIN_REG_26 (C macro), 530 GPIO_PIN_REG_27 (C macro), 530 GPIO_PIN_REG_28 (C macro), 530 GPIO_PIN_REG_29 (C macro), 530 GPIO_PIN_REG_3 (C macro), 530 GPIO_PIN_REG_30 (C macro), 530 GPIO_PIN_REG_31 (C macro), 530 GPIO_PIN_REG_32 (C macro), 530 GPIO_PIN_REG_33 (C macro), 530 GPIO_PIN_REG_34 (C macro), 530 GPIO_PIN_REG_35 (C macro), 531 GPIO_PIN_REG_36 (C macro), 531 GPIO_PIN_REG_37 (C macro), 531 GPIO_PIN_REG_38 (C macro), 531 GPIO_PIN_REG_39 (C macro), 531 GPIO_PIN_REG_4 (C macro), 530 GPIO_PIN_REG_40 (C macro), 531 GPIO_PIN_REG_41 (C macro), 531 GPIO_PIN_REG_42 (C macro), 531 GPIO_PIN_REG_43 (C macro), 531 GPIO_PIN_REG_44 (C macro), 531 GPIO_PIN_REG_45 (C macro), 531 GPIO_PIN_REG_46 (C macro), 531 GPIO_PIN_REG_47 (C macro), 531 GPIO_PIN_REG_48 (C macro), 531 GPIO_PIN_REG_5 (C macro), 530 GPIO_PIN_REG_6 (C macro), 530 GPIO_PIN_REG_7 (C macro), 530 GPIO_PIN_REG_8 (C macro), 530 GPIO_PIN_REG_9 (C macro), 530 GPIO_PORT_0 (C++ enumerator), 531 GPIO_PORT_MAX (C++ enumerator), 531 gpio_port_t (C++ enum), 531 gpio_pull_mode_t (C++ enum), 534 gpio_pulldown_dis (C++ function), 524 GPIO_PULLDOWN_DISABLE (C++ enumerator), 534 gpio_pulldown_en (C++ function), 524 GPIO_PULLDOWN_ENABLE (C++ enumerator), 534 GPIO_PULLDOWN_ONLY (C++ enumerator), 534 gpio_pulldown_t (C++ enum), 534 gpio_pullup_dis (C++ function), 524 GPIO_PULLUP_DISABLE (C++ enumerator), 534 gpio_pullup_en (C++ function), 524 GPIO_PULLUP_ENABLE (C++ enumerator), 534 GPIO_PULLUP_ONLY (C++ enumerator), 534 GPIO_PULLUP_PULLDOWN (C++ enumerator), 534 gpio_pullup_t (C++ enum), 534 gpio_reset_pin (C++ function), 522 GPIO_SEL_0 (C macro), 528 GPIO_SEL_1 (C macro), 528 GPIO_SEL_10 (C macro), 528 GPIO_SEL_11 (C macro), 528 GPIO_SEL_12 (C macro), 528 GPIO_SEL_13 (C macro), 528 GPIO_SEL_14 (C macro), 528 GPIO_SEL_15 (C macro), 528 GPIO_SEL_16 (C macro), 528

GPIO_SEL_17 (C macro), 528 GPIO_SEL_18 (C macro), 528 GPIO_SEL_19 (C macro), 528 GPIO_SEL_2 (C macro), 528 GPIO_SEL_20 (C macro), 529 GPIO_SEL_21 (C macro), 529 GPIO_SEL_26 (C macro), 529 GPIO_SEL_27 (C macro), 529 GPIO_SEL_28 (C macro), 529 GPIO_SEL_29 (C macro), 529 GPIO_SEL_3 (C macro), 528 GPIO_SEL_30 (C macro), 529 GPIO_SEL_31 (C macro), 529 GPIO_SEL_32 (C macro), 529 GPIO_SEL_33 (C macro), 529 GPIO_SEL_34 (C macro), 529 GPIO_SEL_35 (C macro), 529 GPIO_SEL_36 (C macro), 529 GPIO_SEL_37 (C macro), 529 GPIO_SEL_38 (C macro), 529 GPIO_SEL_39 (C macro), 529 GPIO_SEL_4 (C macro), 528 GPIO_SEL_40 (C macro), 529 GPIO_SEL_41 (C macro), 529 GPIO_SEL_42 (C macro), 529 GPIO_SEL_43 (C macro), 529 GPIO_SEL_44 (C macro), 529 GPIO_SEL_45 (C macro), 529 GPIO_SEL_46 (C macro), 529 GPIO_SEL_47 (C macro), 530 GPIO_SEL_48 (C macro), 530 GPIO_SEL_5 (C macro), 528 GPIO_SEL_6 (C macro), 528 GPIO_SEL_7 (C macro), 528 GPIO_SEL_8 (C macro), 528 GPIO_SEL_9 (C macro), 528 gpio_set_direction (C++ function), 523 gpio_set_drive_capability (C++ function),
525 gpio_set_intr_type (C++ function), 522 gpio_set_level (C++ function), 522 gpio_set_pull_mode (C++ function), 523 gpio_sleep_sel_dis (C++ function), 526 gpio_sleep_sel_en (C++ function), 526 gpio_sleep_set_direction (C++ function),
527 gpio_sleep_set_pull_mode (C++ function),
527 gpio_uninstall_isr_service (C++ function),
524 gpio_wakeup_disable (C++ function), 523 gpio_wakeup_enable (C++ function), 523 gptimer_alarm_cb_t (C++ type), 546 gptimer_alarm_config_t (C++ class), 546 gptimer_alarm_config_t::alarm_count
(C++ member), 546 gptimer_alarm_config_t::auto_reload_on_alarm
(C++ member), 546

Espressif Systems

2131

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

gptimer_alarm_config_t::reload_count heap_caps_enable_nonos_stack_heaps

(C++ member), 546

(C++ function), 1274

gptimer_alarm_event_data_t (C++ class), heap_caps_free (C++ function), 1269

545

heap_caps_get_allocated_size (C++ func-

gptimer_alarm_event_data_t::alarm_value

tion), 1273

(C++ member), 546

heap_caps_get_free_size (C++ function),

gptimer_alarm_event_data_t::count_value

1270

(C++ member), 546

heap_caps_get_info (C++ function), 1271

GPTIMER_CLK_SRC_APB (C++ enumerator), 547 heap_caps_get_largest_free_block (C++

GPTIMER_CLK_SRC_XTAL (C++ enumerator), 547

function), 1271

gptimer_clock_source_t (C++ enum), 547

heap_caps_get_minimum_free_size (C++

gptimer_config_t (C++ class), 546

function), 1270

gptimer_config_t::clk_src (C++ member), heap_caps_get_total_size (C++ function),

546

1270

gptimer_config_t::direction (C++ mem- heap_caps_init (C++ function), 1274

ber), 546

heap_caps_malloc (C++ function), 1269

gptimer_config_t::intr_shared (C++ heap_caps_malloc_extmem_enable (C++

member), 546

function), 1272

gptimer_config_t::resolution_hz (C++ heap_caps_malloc_prefer (C++ function),

member), 546

1272

gptimer_count_direction_t (C++ enum), 547 heap_caps_print_heap_info (C++ function),

GPTIMER_COUNT_DOWN (C++ enumerator), 547

1271

GPTIMER_COUNT_UP (C++ enumerator), 547

heap_caps_realloc (C++ function), 1269

gptimer_del_timer (C++ function), 544

heap_caps_realloc_prefer (C++ function),

gptimer_event_callbacks_t (C++ class), 546

1272

gptimer_event_callbacks_t::on_alarm heap_caps_register_failed_alloc_callback

(C++ member), 546

(C++ function), 1269

gptimer_get_raw_count (C++ function), 544 HEAP_TRACE_ALL (C++ enumerator), 1288

gptimer_handle_t (C++ type), 546

heap_trace_dump (C++ function), 1288

gptimer_new_timer (C++ function), 544

heap_trace_get (C++ function), 1288

gptimer_register_event_callbacks (C++ heap_trace_get_count (C++ function), 1287

function), 544

heap_trace_init_standalone (C++ function),

gptimer_set_alarm_action (C++ function),

1287

545

heap_trace_init_tohost (C++ function), 1287

gptimer_set_raw_count (C++ function), 544 HEAP_TRACE_LEAKS (C++ enumerator), 1288

gptimer_start (C++ function), 545

heap_trace_mode_t (C++ enum), 1288

gptimer_stop (C++ function), 545

heap_trace_record_t (C++ class), 1288

heap_trace_record_t::address (C++ mem-

H

ber), 1288

heap_caps_add_region (C++ function), 1274 heap_caps_add_region_with_caps (C++
function), 1275 heap_caps_aligned_alloc (C++ function),
1269 heap_caps_aligned_calloc (C++ function),
1270 heap_caps_aligned_free (C++ function), 1270 heap_caps_calloc (C++ function), 1270 heap_caps_calloc_prefer (C++ function),
1272 heap_caps_check_integrity (C++ function),
1271 heap_caps_check_integrity_addr (C++
function), 1271 heap_caps_check_integrity_all (C++ func-
tion), 1271 heap_caps_dump (C++ function), 1272 heap_caps_dump_all (C++ function), 1272

heap_trace_record_t::alloced_by (C++ member), 1288
heap_trace_record_t::ccount (C++ member), 1288
heap_trace_record_t::freed_by (C++ member), 1288
heap_trace_record_t::size (C++ member), 1288
heap_trace_resume (C++ function), 1287 heap_trace_start (C++ function), 1287 heap_trace_stop (C++ function), 1287 HMAC_KEY0 (C++ enumerator), 554 HMAC_KEY1 (C++ enumerator), 554 HMAC_KEY2 (C++ enumerator), 554 HMAC_KEY3 (C++ enumerator), 554 HMAC_KEY4 (C++ enumerator), 554 HMAC_KEY5 (C++ enumerator), 554 hmac_key_id_t (C++ enum), 554 HMAC_KEY_MAX (C++ enumerator), 554

Espressif Systems

2132

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

HOST_CONNECTION_MODE_CLI_UART (C++ enumerator), 478
HOST_CONNECTION_MODE_NONE (C++ enumerator), 478
HOST_CONNECTION_MODE_RCP_UART (C++ enumerator), 478
HTTP_AUTH_TYPE_BASIC (C++ enumerator), 863 HTTP_AUTH_TYPE_DIGEST (C++ enumerator), 864 HTTP_AUTH_TYPE_NONE (C++ enumerator), 863 http_client_init_cb_t (C++ type), 1126 HTTP_EVENT_DISCONNECTED (C++ enumerator),
862 HTTP_EVENT_ERROR (C++ enumerator), 862 http_event_handle_cb (C++ type), 862 HTTP_EVENT_HEADER_SENT (C++ enumerator),
862 HTTP_EVENT_HEADERS_SENT (C++ enumerator),
862 HTTP_EVENT_ON_CONNECTED (C++ enumerator),
862 HTTP_EVENT_ON_DATA (C++ enumerator), 862 HTTP_EVENT_ON_FINISH (C++ enumerator), 862 HTTP_EVENT_ON_HEADER (C++ enumerator), 862 HTTP_EVENT_REDIRECT (C++ enumerator), 862 HTTP_METHOD_COPY (C++ enumerator), 863 HTTP_METHOD_DELETE (C++ enumerator), 863 HTTP_METHOD_GET (C++ enumerator), 863 HTTP_METHOD_HEAD (C++ enumerator), 863 HTTP_METHOD_LOCK (C++ enumerator), 863 HTTP_METHOD_MAX (C++ enumerator), 863 HTTP_METHOD_MKCOL (C++ enumerator), 863 HTTP_METHOD_MOVE (C++ enumerator), 863 HTTP_METHOD_NOTIFY (C++ enumerator), 863 HTTP_METHOD_OPTIONS (C++ enumerator), 863 HTTP_METHOD_PATCH (C++ enumerator), 863 HTTP_METHOD_POST (C++ enumerator), 863 HTTP_METHOD_PROPFIND (C++ enumerator), 863 HTTP_METHOD_PROPPATCH (C++ enumerator), 863 HTTP_METHOD_PUT (C++ enumerator), 863 HTTP_METHOD_SUBSCRIBE (C++ enumerator), 863 HTTP_METHOD_UNLOCK (C++ enumerator), 863 HTTP_METHOD_UNSUBSCRIBE (C++ enumerator),
863 HTTP_TRANSPORT_OVER_SSL (C++ enumerator),
862 HTTP_TRANSPORT_OVER_TCP (C++ enumerator),
862 HTTP_TRANSPORT_UNKNOWN (C++ enumerator),
862 HTTPD_200 (C macro), 882 HTTPD_204 (C macro), 882 HTTPD_207 (C macro), 882 HTTPD_400 (C macro), 882 HTTPD_400_BAD_REQUEST (C++ enumerator), 886 HTTPD_401_UNAUTHORIZED (C++ enumerator),
886 HTTPD_403_FORBIDDEN (C++ enumerator), 886 HTTPD_404 (C macro), 882

HTTPD_404_NOT_FOUND (C++ enumerator), 886 HTTPD_405_METHOD_NOT_ALLOWED (C++ enu-
merator), 886 HTTPD_408 (C macro), 883 HTTPD_408_REQ_TIMEOUT (C++ enumerator), 886 HTTPD_411_LENGTH_REQUIRED (C++ enumera-
tor), 886 HTTPD_414_URI_TOO_LONG (C++ enumerator),
886 HTTPD_431_REQ_HDR_FIELDS_TOO_LARGE
(C++ enumerator), 886 HTTPD_500 (C macro), 883 HTTPD_500_INTERNAL_SERVER_ERROR (C++
enumerator), 886 HTTPD_501_METHOD_NOT_IMPLEMENTED (C++
enumerator), 886 HTTPD_505_VERSION_NOT_SUPPORTED (C++
enumerator), 886 httpd_close_func_t (C++ type), 885 httpd_config (C++ class), 880 httpd_config::backlog_conn (C++ member),
880 httpd_config::close_fn (C++ member), 881 httpd_config::core_id (C++ member), 880 httpd_config::ctrl_port (C++ member), 880 httpd_config::global_transport_ctx
(C++ member), 880 httpd_config::global_transport_ctx_free_fn
(C++ member), 880 httpd_config::global_user_ctx (C++
member), 880 httpd_config::global_user_ctx_free_fn
(C++ member), 880 httpd_config::lru_purge_enable (C++
member), 880 httpd_config::max_open_sockets (C++
member), 880 httpd_config::max_resp_headers (C++
member), 880 httpd_config::max_uri_handlers (C++
member), 880 httpd_config::open_fn (C++ member), 880 httpd_config::recv_wait_timeout (C++
member), 880 httpd_config::send_wait_timeout (C++
member), 880 httpd_config::server_port (C++ member),
880 httpd_config::stack_size (C++ member),
880 httpd_config::task_priority (C++ mem-
ber), 880 httpd_config::uri_match_fn (C++ member),
881 httpd_config_t (C++ type), 885 HTTPD_DEFAULT_CONFIG (C macro), 883 HTTPD_ERR_CODE_MAX (C++ enumerator), 886 httpd_err_code_t (C++ enum), 885

Espressif Systems

2133

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

httpd_err_handler_func_t (C++ type), 884 httpd_free_ctx_fn_t (C++ type), 885 httpd_get_client_list (C++ function), 879 httpd_get_global_transport_ctx (C++
function), 879 httpd_get_global_user_ctx (C++ function),
878 httpd_handle_t (C++ type), 885 HTTPD_MAX_REQ_HDR_LEN (C macro), 882 HTTPD_MAX_URI_LEN (C macro), 882 httpd_method_t (C++ type), 885 httpd_open_func_t (C++ type), 885 httpd_pending_func_t (C++ type), 884 httpd_query_key_value (C++ function), 871 httpd_queue_work (C++ function), 877 httpd_recv_func_t (C++ type), 884 httpd_register_err_handler (C++ function),
876 httpd_register_uri_handler (C++ function),
867 httpd_req (C++ class), 881 httpd_req::aux (C++ member), 881 httpd_req::content_len (C++ member), 881 httpd_req::free_ctx (C++ member), 882 httpd_req::handle (C++ member), 881 httpd_req::ignore_sess_ctx_changes
(C++ member), 882 httpd_req::method (C++ member), 881 httpd_req::sess_ctx (C++ member), 881 httpd_req::uri (C++ member), 881 httpd_req::user_ctx (C++ member), 881 httpd_req_get_cookie_val (C++ function),
871 httpd_req_get_hdr_value_len (C++ func-
tion), 869 httpd_req_get_hdr_value_str (C++ func-
tion), 870 httpd_req_get_url_query_len (C++ func-
tion), 870 httpd_req_get_url_query_str (C++ func-
tion), 870 httpd_req_recv (C++ function), 869 httpd_req_t (C++ type), 883 httpd_req_to_sockfd (C++ function), 869 httpd_resp_send (C++ function), 872 httpd_resp_send_404 (C++ function), 874 httpd_resp_send_408 (C++ function), 875 httpd_resp_send_500 (C++ function), 875 httpd_resp_send_chunk (C++ function), 872 httpd_resp_send_err (C++ function), 874 httpd_resp_sendstr (C++ function), 873 httpd_resp_sendstr_chunk (C++ function),
873 httpd_resp_set_hdr (C++ function), 874 httpd_resp_set_status (C++ function), 873 httpd_resp_set_type (C++ function), 873 HTTPD_RESP_USE_STRLEN (C macro), 883 httpd_send (C++ function), 875

httpd_send_func_t (C++ type), 883 httpd_sess_get_ctx (C++ function), 878 httpd_sess_get_transport_ctx (C++ func-
tion), 878 httpd_sess_set_ctx (C++ function), 878 httpd_sess_set_pending_override (C++
function), 868 httpd_sess_set_recv_override (C++ func-
tion), 868 httpd_sess_set_send_override (C++ func-
tion), 868 httpd_sess_set_transport_ctx (C++ func-
tion), 878 httpd_sess_trigger_close (C++ function),
879 httpd_sess_update_lru_counter (C++ func-
tion), 879 HTTPD_SOCK_ERR_FAIL (C macro), 882 HTTPD_SOCK_ERR_INVALID (C macro), 882 HTTPD_SOCK_ERR_TIMEOUT (C macro), 882 httpd_socket_recv (C++ function), 876 httpd_socket_send (C++ function), 876 httpd_ssl_config (C++ class), 887 httpd_ssl_config::cacert_len (C++ mem-
ber), 887 httpd_ssl_config::cacert_pem (C++ mem-
ber), 887 httpd_ssl_config::client_verify_cert_len
(C++ member), 887 httpd_ssl_config::client_verify_cert_pem
(C++ member), 887 httpd_ssl_config::httpd (C++ member), 887 httpd_ssl_config::port_insecure (C++
member), 888 httpd_ssl_config::port_secure (C++
member), 888 httpd_ssl_config::prvtkey_len (C++
member), 888 httpd_ssl_config::prvtkey_pem (C++
member), 888 httpd_ssl_config::session_tickets
(C++ member), 888 httpd_ssl_config::transport_mode (C++
member), 888 httpd_ssl_config::user_cb (C++ member),
888 HTTPD_SSL_CONFIG_DEFAULT (C macro), 888 httpd_ssl_config_t (C++ type), 888 httpd_ssl_start (C++ function), 887 httpd_ssl_stop (C++ function), 887 HTTPD_SSL_TRANSPORT_INSECURE (C++ enu-
merator), 888 httpd_ssl_transport_mode_t (C++ enum),
888 HTTPD_SSL_TRANSPORT_SECURE (C++ enumera-
tor), 888 httpd_start (C++ function), 877 httpd_stop (C++ function), 877

Espressif Systems

2134

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

HTTPD_TYPE_JSON (C macro), 883 HTTPD_TYPE_OCTET (C macro), 883 HTTPD_TYPE_TEXT (C macro), 883 httpd_unregister_uri (C++ function), 868 httpd_unregister_uri_handler (C++ func-
tion), 868 httpd_uri (C++ class), 882 httpd_uri::handler (C++ member), 882 httpd_uri::method (C++ member), 882 httpd_uri::uri (C++ member), 882 httpd_uri::user_ctx (C++ member), 882 httpd_uri_match_func_t (C++ type), 885 httpd_uri_match_wildcard (C++ function),
871 httpd_uri_t (C++ type), 883 httpd_work_fn_t (C++ type), 885 HttpStatus_BadRequest (C++ enumerator), 864 HttpStatus_Code (C++ enum), 864 HttpStatus_Forbidden (C++ enumerator), 864 HttpStatus_Found (C++ enumerator), 864 HttpStatus_InternalError (C++ enumerator),
864 HttpStatus_MovedPermanently (C++ enumer-
ator), 864 HttpStatus_MultipleChoices (C++ enumera-
tor), 864 HttpStatus_NotFound (C++ enumerator), 864 HttpStatus_Ok (C++ enumerator), 864 HttpStatus_TemporaryRedirect (C++ enu-
merator), 864 HttpStatus_Unauthorized (C++ enumerator),
864
I
i2c_ack_type_t (C++ enum), 574 I2C_ADDR_BIT_10 (C++ enumerator), 574 I2C_ADDR_BIT_7 (C++ enumerator), 574 I2C_ADDR_BIT_MAX (C++ enumerator), 574 i2c_addr_mode_t (C++ enum), 574 I2C_APB_CLK_FREQ (C macro), 572 I2C_CLK_FREQ_MAX (C macro), 573 i2c_cmd_handle_t (C++ type), 573 i2c_cmd_link_create (C++ function), 567 i2c_cmd_link_create_static (C++ function),
566 i2c_cmd_link_delete (C++ function), 567 i2c_cmd_link_delete_static (C++ function),
567 i2c_config_t (C++ class), 572 i2c_config_t::addr_10bit_en (C++ mem-
ber), 572 i2c_config_t::clk_flags (C++ member), 572 i2c_config_t::clk_speed (C++ member), 572 i2c_config_t::master (C++ member), 572 i2c_config_t::maximum_speed (C++ mem-
ber), 572 i2c_config_t::mode (C++ member), 572

i2c_config_t::scl_io_num (C++ member), 572
i2c_config_t::scl_pullup_en (C++ member), 572
i2c_config_t::sda_io_num (C++ member), 572
i2c_config_t::sda_pullup_en (C++ member), 572
i2c_config_t::slave (C++ member), 572 i2c_config_t::slave_addr (C++ member),
572 I2C_DATA_MODE_LSB_FIRST (C++ enumerator),
574 I2C_DATA_MODE_MAX (C++ enumerator), 574 I2C_DATA_MODE_MSB_FIRST (C++ enumerator),
574 i2c_driver_delete (C++ function), 565 i2c_driver_install (C++ function), 564 i2c_filter_disable (C++ function), 570 i2c_filter_enable (C++ function), 569 i2c_get_data_mode (C++ function), 571 i2c_get_data_timing (C++ function), 571 i2c_get_period (C++ function), 569 i2c_get_start_timing (C++ function), 570 i2c_get_stop_timing (C++ function), 570 i2c_get_timeout (C++ function), 571 I2C_INTERNAL_STRUCT_SIZE (C macro), 573 I2C_LINK_RECOMMENDED_SIZE (C macro), 573 I2C_MASTER_ACK (C++ enumerator), 574 I2C_MASTER_ACK_MAX (C++ enumerator), 574 i2c_master_cmd_begin (C++ function), 568 I2C_MASTER_LAST_NACK (C++ enumerator), 574 I2C_MASTER_NACK (C++ enumerator), 574 I2C_MASTER_READ (C++ enumerator), 573 i2c_master_read (C++ function), 568 i2c_master_read_byte (C++ function), 568 i2c_master_read_from_device (C++ func-
tion), 566 i2c_master_start (C++ function), 567 i2c_master_stop (C++ function), 568 I2C_MASTER_WRITE (C++ enumerator), 573 i2c_master_write (C++ function), 567 i2c_master_write_byte (C++ function), 567 i2c_master_write_read_device (C++ func-
tion), 566 i2c_master_write_to_device (C++ function),
565 I2C_MODE_MASTER (C++ enumerator), 573 I2C_MODE_MAX (C++ enumerator), 573 I2C_MODE_SLAVE (C++ enumerator), 573 i2c_mode_t (C++ enum), 573 I2C_NUM_0 (C macro), 572 I2C_NUM_1 (C macro), 572 I2C_NUM_MAX (C macro), 572 i2c_param_config (C++ function), 565 i2c_port_t (C++ type), 573 i2c_reset_rx_fifo (C++ function), 565 i2c_reset_tx_fifo (C++ function), 565

Espressif Systems

2135

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

i2c_rw_t (C++ enum), 573 I2C_SCLK_DEFAULT (C++ enumerator), 574 I2C_SCLK_MAX (C++ enumerator), 574 I2C_SCLK_RTC (C++ enumerator), 574 I2C_SCLK_SRC_FLAG_AWARE_DFS (C macro),
573 I2C_SCLK_SRC_FLAG_FOR_NOMAL (C macro),
572 I2C_SCLK_SRC_FLAG_LIGHT_SLEEP (C macro),
573 i2c_sclk_t (C++ enum), 574 I2C_SCLK_XTAL (C++ enumerator), 574 i2c_set_data_mode (C++ function), 571 i2c_set_data_timing (C++ function), 571 i2c_set_period (C++ function), 569 i2c_set_pin (C++ function), 565 i2c_set_start_timing (C++ function), 570 i2c_set_stop_timing (C++ function), 570 i2c_set_timeout (C++ function), 571 i2c_slave_read_buffer (C++ function), 569 i2c_slave_write_buffer (C++ function), 569 i2c_trans_mode_t (C++ enum), 573 I2S_BITS_PER_CHAN_16BIT (C++ enumerator),
586 I2S_BITS_PER_CHAN_24BIT (C++ enumerator),
586 I2S_BITS_PER_CHAN_32BIT (C++ enumerator),
586 I2S_BITS_PER_CHAN_8BIT (C++ enumerator),
586 I2S_BITS_PER_CHAN_DEFAULT (C++ enumera-
tor), 586 i2s_bits_per_chan_t (C++ enum), 586 I2S_BITS_PER_SAMPLE_16BIT (C++ enumera-
tor), 586 I2S_BITS_PER_SAMPLE_24BIT (C++ enumera-
tor), 586 I2S_BITS_PER_SAMPLE_32BIT (C++ enumera-
tor), 586 I2S_BITS_PER_SAMPLE_8BIT (C++ enumerator),
586 i2s_bits_per_sample_t (C++ enum), 586 I2S_CHANNEL_FMT_ALL_LEFT (C++ enumerator),
588 I2S_CHANNEL_FMT_ALL_RIGHT (C++ enumera-
tor), 588 I2S_CHANNEL_FMT_MULTIPLE (C++ enumerator),
588 I2S_CHANNEL_FMT_ONLY_LEFT (C++ enumera-
tor), 588 I2S_CHANNEL_FMT_ONLY_RIGHT (C++ enumera-
tor), 588 I2S_CHANNEL_FMT_RIGHT_LEFT (C++ enumera-
tor), 588 i2s_channel_fmt_t (C++ enum), 588 I2S_CHANNEL_MONO (C++ enumerator), 586 I2S_CHANNEL_STEREO (C++ enumerator), 586 i2s_channel_t (C++ enum), 586

I2S_CLK_D2CLK (C++ enumerator), 588 i2s_clock_src_t (C++ enum), 588 I2S_COMM_FORMAT_I2S (C++ enumerator), 587 I2S_COMM_FORMAT_I2S_LSB (C++ enumerator),
588 I2S_COMM_FORMAT_I2S_MSB (C++ enumerator),
587 I2S_COMM_FORMAT_PCM (C++ enumerator), 588 I2S_COMM_FORMAT_PCM_LONG (C++ enumerator),
588 I2S_COMM_FORMAT_PCM_SHORT (C++ enumera-
tor), 588 I2S_COMM_FORMAT_STAND_I2S (C++ enumera-
tor), 587 I2S_COMM_FORMAT_STAND_MAX (C++ enumera-
tor), 587 I2S_COMM_FORMAT_STAND_MSB (C++ enumera-
tor), 587 I2S_COMM_FORMAT_STAND_PCM_LONG (C++
enumerator), 587 I2S_COMM_FORMAT_STAND_PCM_SHORT (C++
enumerator), 587 i2s_comm_format_t (C++ enum), 587 i2s_config_t (C++ type), 585 i2s_driver_config_t (C++ class), 584 i2s_driver_config_t::big_edin (C++
member), 585 i2s_driver_config_t::bit_order_msb
(C++ member), 585 i2s_driver_config_t::bits_per_chan
(C++ member), 584 i2s_driver_config_t::bits_per_sample
(C++ member), 584 i2s_driver_config_t::chan_mask (C++
member), 584 i2s_driver_config_t::channel_format
(C++ member), 584 i2s_driver_config_t::communication_format
(C++ member), 584 i2s_driver_config_t::dma_buf_count
(C++ member), 584 i2s_driver_config_t::dma_buf_len (C++
member), 584 i2s_driver_config_t::dma_desc_num
(C++ member), 584 i2s_driver_config_t::dma_frame_num
(C++ member), 584 i2s_driver_config_t::fixed_mclk (C++
member), 584 i2s_driver_config_t::intr_alloc_flags
(C++ member), 584 i2s_driver_config_t::left_align (C++
member), 584 i2s_driver_config_t::mclk_multiple
(C++ member), 584 i2s_driver_config_t::mode (C++ member),
584 i2s_driver_config_t::sample_rate (C++

Espressif Systems

2136

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

member), 584

I2S_PDM_SIG_SCALING_MUL_2 (C++ enumera-

i2s_driver_config_t::skip_msk (C++

tor), 589

member), 585

I2S_PDM_SIG_SCALING_MUL_4 (C++ enumera-

i2s_driver_config_t::total_chan (C++

tor), 589

member), 584

i2s_pdm_tx_upsample_cfg_t (C++ class), 583

i2s_driver_config_t::tx_desc_auto_cleari2s_pdm_tx_upsample_cfg_t::fp (C++

(C++ member), 584

member), 583

i2s_driver_config_t::use_apll (C++ i2s_pdm_tx_upsample_cfg_t::fs (C++

member), 584

member), 583

i2s_driver_install (C++ function), 580

i2s_pdm_tx_upsample_cfg_t::sample_rate

i2s_driver_uninstall (C++ function), 580

(C++ member), 583

I2S_EVENT_DMA_ERROR (C++ enumerator), 585 i2s_pin_config_t (C++ class), 583

I2S_EVENT_MAX (C++ enumerator), 586

i2s_pin_config_t::bck_io_num (C++ mem-

I2S_EVENT_RX_DONE (C++ enumerator), 585

ber), 583

I2S_EVENT_RX_Q_OVF (C++ enumerator), 586

i2s_pin_config_t::data_in_num (C++

i2s_event_t (C++ class), 585

member), 583

i2s_event_t::size (C++ member), 585

i2s_pin_config_t::data_out_num (C++

i2s_event_t::type (C++ member), 585

member), 583

I2S_EVENT_TX_DONE (C++ enumerator), 585

i2s_pin_config_t::mck_io_num (C++ mem-

I2S_EVENT_TX_Q_OVF (C++ enumerator), 585

ber), 583

i2s_event_type_t (C++ enum), 585

i2s_pin_config_t::ws_io_num (C++ mem-

i2s_get_clk (C++ function), 583

ber), 583

i2s_isr_handle_t (C++ type), 585

I2S_PIN_NO_CHANGE (C macro), 585

I2S_MCLK_MULTIPLE_128 (C++ enumerator), 589 i2s_port_t (C++ enum), 585

I2S_MCLK_MULTIPLE_256 (C++ enumerator), 589 i2s_read (C++ function), 581

I2S_MCLK_MULTIPLE_384 (C++ enumerator), 589 i2s_set_clk (C++ function), 582

I2S_MCLK_MULTIPLE_DEFAULT (C++ enumera- i2s_set_pdm_rx_down_sample (C++ function),

tor), 589

579

i2s_mclk_multiple_t (C++ enum), 588

i2s_set_pdm_tx_up_sample (C++ function),

I2S_MODE_MASTER (C++ enumerator), 588

580

I2S_MODE_PDM (C++ enumerator), 588

i2s_set_pin (C++ function), 579

I2S_MODE_RX (C++ enumerator), 588

i2s_set_sample_rates (C++ function), 581

I2S_MODE_SLAVE (C++ enumerator), 588

i2s_start (C++ function), 582

i2s_mode_t (C++ enum), 588

i2s_stop (C++ function), 582

I2S_MODE_TX (C++ enumerator), 588

I2S_TDM_ACTIVE_CH0 (C++ enumerator), 586

I2S_NUM_0 (C++ enumerator), 585

I2S_TDM_ACTIVE_CH1 (C++ enumerator), 586

I2S_NUM_1 (C++ enumerator), 585

I2S_TDM_ACTIVE_CH10 (C++ enumerator), 587

I2S_NUM_MAX (C++ enumerator), 585

I2S_TDM_ACTIVE_CH11 (C++ enumerator), 587

I2S_PCM_A_COMPRESS (C++ enumerator), 589

I2S_TDM_ACTIVE_CH12 (C++ enumerator), 587

I2S_PCM_A_DECOMPRESS (C++ enumerator), 589 I2S_TDM_ACTIVE_CH13 (C++ enumerator), 587

i2s_pcm_cfg_t (C++ class), 583

I2S_TDM_ACTIVE_CH14 (C++ enumerator), 587

i2s_pcm_cfg_t::pcm_type (C++ member), 583 I2S_TDM_ACTIVE_CH15 (C++ enumerator), 587

i2s_pcm_compress_t (C++ enum), 589

I2S_TDM_ACTIVE_CH2 (C++ enumerator), 587

i2s_pcm_config (C++ function), 582

I2S_TDM_ACTIVE_CH3 (C++ enumerator), 587

I2S_PCM_DISABLE (C++ enumerator), 589

I2S_TDM_ACTIVE_CH4 (C++ enumerator), 587

I2S_PCM_U_COMPRESS (C++ enumerator), 589

I2S_TDM_ACTIVE_CH5 (C++ enumerator), 587

I2S_PCM_U_DECOMPRESS (C++ enumerator), 589 I2S_TDM_ACTIVE_CH6 (C++ enumerator), 587

I2S_PDM_DEFAULT_UPSAMPLE_CONFIG

(C I2S_TDM_ACTIVE_CH7 (C++ enumerator), 587

macro), 585

I2S_TDM_ACTIVE_CH8 (C++ enumerator), 587

I2S_PDM_DSR_16S (C++ enumerator), 589

I2S_TDM_ACTIVE_CH9 (C++ enumerator), 587

I2S_PDM_DSR_8S (C++ enumerator), 589

i2s_write (C++ function), 580

I2S_PDM_DSR_MAX (C++ enumerator), 589

i2s_write_expand (C++ function), 581

i2s_pdm_dsr_t (C++ enum), 589

i2s_zero_dma_buffer (C++ function), 582

i2s_pdm_sig_scale_t (C++ enum), 589

I_ADDI (C macro), 1895

I2S_PDM_SIG_SCALING_DIV_2 (C++ enumera- I_ADDR (C macro), 1894

tor), 589

I_ANDI (C macro), 1895

I2S_PDM_SIG_SCALING_MUL_1 (C++ enumera- I_ANDR (C macro), 1894

tor), 589

I_BGE (C macro), 1894

Espressif Systems

2137

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

I_BL (C macro), 1894 I_BXFI (C macro), 1894 I_BXFR (C macro), 1894 I_BXI (C macro), 1894 I_BXR (C macro), 1894 I_BXZI (C macro), 1894 I_BXZR (C macro), 1894 I_DELAY (C macro), 1893 I_END (C macro), 1893 I_HALT (C macro), 1893 I_LD (C macro), 1894 I_LSHI (C macro), 1895 I_LSHR (C macro), 1895 I_MOVI (C macro), 1895 I_MOVR (C macro), 1895 I_ORI (C macro), 1895 I_ORR (C macro), 1894 I_RD_REG (C macro), 1894 I_RSHI (C macro), 1895 I_RSHR (C macro), 1895 I_ST (C macro), 1893 I_SUBI (C macro), 1895 I_SUBR (C macro), 1894 I_WR_REG (C macro), 1894 iface_destroy (C++ type), 929 iface_init (C++ type), 929 iface_setup (C++ type), 929 iface_start (C++ type), 929 intr_handle_data_t (C++ type), 1306 intr_handle_t (C++ type), 1306 intr_handler_t (C++ type), 1306
L
LCD_CLK_SRC_APLL (C++ enumerator), 590 LCD_CLK_SRC_PLL160M (C++ enumerator), 590 LCD_CLK_SRC_XTAL (C++ enumerator), 590 lcd_clock_source_t (C++ enum), 590 LEDC_APB_CLK (C++ enumerator), 615 LEDC_APB_CLK_HZ (C macro), 613 LEDC_AUTO_CLK (C++ enumerator), 614 ledc_bind_channel_timer (C++ function), 609 ledc_cb_event_t (C++ enum), 613 ledc_cb_param_t (C++ class), 613 ledc_cb_param_t::channel (C++ member),
613 ledc_cb_param_t::duty (C++ member), 613 ledc_cb_param_t::event (C++ member), 613 ledc_cb_param_t::speed_mode (C++ mem-
ber), 613 ledc_cb_register (C++ function), 611 ledc_cb_t (C++ type), 613 ledc_cbs_t (C++ class), 613 ledc_cbs_t::fade_cb (C++ member), 613 LEDC_CHANNEL_0 (C++ enumerator), 615 LEDC_CHANNEL_1 (C++ enumerator), 615 LEDC_CHANNEL_2 (C++ enumerator), 615 LEDC_CHANNEL_3 (C++ enumerator), 615 LEDC_CHANNEL_4 (C++ enumerator), 615

LEDC_CHANNEL_5 (C++ enumerator), 615 LEDC_CHANNEL_6 (C++ enumerator), 615 LEDC_CHANNEL_7 (C++ enumerator), 615 ledc_channel_config (C++ function), 605 ledc_channel_config_t (C++ class), 612 ledc_channel_config_t::channel (C++
member), 612 ledc_channel_config_t::duty (C++ mem-
ber), 612 ledc_channel_config_t::flags (C++ mem-
ber), 612 ledc_channel_config_t::gpio_num (C++
member), 612 ledc_channel_config_t::hpoint (C++
member), 612 ledc_channel_config_t::intr_type (C++
member), 612 ledc_channel_config_t::output_invert
(C++ member), 612 ledc_channel_config_t::speed_mode
(C++ member), 612 ledc_channel_config_t::timer_sel (C++
member), 612 LEDC_CHANNEL_MAX (C++ enumerator), 615 ledc_channel_t (C++ enum), 615 ledc_clk_cfg_t (C++ enum), 614 ledc_clk_src_t (C++ enum), 614 LEDC_DUTY_DIR_DECREASE (C++ enumerator),
614 LEDC_DUTY_DIR_INCREASE (C++ enumerator),
614 LEDC_DUTY_DIR_MAX (C++ enumerator), 614 ledc_duty_direction_t (C++ enum), 614 LEDC_ERR_DUTY (C macro), 613 LEDC_ERR_VAL (C macro), 613 LEDC_FADE_END_EVT (C++ enumerator), 613 ledc_fade_func_install (C++ function), 610 ledc_fade_func_uninstall (C++ function),
610 LEDC_FADE_MAX (C++ enumerator), 616 ledc_fade_mode_t (C++ enum), 616 LEDC_FADE_NO_WAIT (C++ enumerator), 616 ledc_fade_start (C++ function), 610 ledc_fade_stop (C++ function), 610 LEDC_FADE_WAIT_DONE (C++ enumerator), 616 ledc_get_duty (C++ function), 607 ledc_get_freq (C++ function), 606 ledc_get_hpoint (C++ function), 607 LEDC_INTR_DISABLE (C++ enumerator), 614 LEDC_INTR_FADE_END (C++ enumerator), 614 LEDC_INTR_MAX (C++ enumerator), 614 ledc_intr_type_t (C++ enum), 614 ledc_isr_handle_t (C++ type), 613 ledc_isr_register (C++ function), 608 LEDC_LOW_SPEED_MODE (C++ enumerator), 614 ledc_mode_t (C++ enum), 614 LEDC_REF_CLK_HZ (C macro), 613 LEDC_SCLK (C++ enumerator), 615

Espressif Systems

2138

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

ledc_set_duty (C++ function), 607 ledc_set_duty_and_update (C++ function),
610 ledc_set_duty_with_hpoint (C++ function),
606 ledc_set_fade (C++ function), 607 ledc_set_fade_step_and_start (C++ func-
tion), 611 ledc_set_fade_time_and_start (C++ func-
tion), 611 ledc_set_fade_with_step (C++ function), 609 ledc_set_fade_with_time (C++ function), 609 ledc_set_freq (C++ function), 606 ledc_set_pin (C++ function), 606 LEDC_SLOW_CLK_APB (C++ enumerator), 614 LEDC_SLOW_CLK_RTC8M (C++ enumerator), 614 ledc_slow_clk_sel_t (C++ enum), 614 LEDC_SLOW_CLK_XTAL (C++ enumerator), 614 LEDC_SPEED_MODE_MAX (C++ enumerator), 614 ledc_stop (C++ function), 606 LEDC_TIMER_0 (C++ enumerator), 615 LEDC_TIMER_1 (C++ enumerator), 615 LEDC_TIMER_10_BIT (C++ enumerator), 616 LEDC_TIMER_11_BIT (C++ enumerator), 616 LEDC_TIMER_12_BIT (C++ enumerator), 616 LEDC_TIMER_13_BIT (C++ enumerator), 616 LEDC_TIMER_14_BIT (C++ enumerator), 616 LEDC_TIMER_1_BIT (C++ enumerator), 615 LEDC_TIMER_2 (C++ enumerator), 615 LEDC_TIMER_2_BIT (C++ enumerator), 615 LEDC_TIMER_3 (C++ enumerator), 615 LEDC_TIMER_3_BIT (C++ enumerator), 615 LEDC_TIMER_4_BIT (C++ enumerator), 615 LEDC_TIMER_5_BIT (C++ enumerator), 616 LEDC_TIMER_6_BIT (C++ enumerator), 616 LEDC_TIMER_7_BIT (C++ enumerator), 616 LEDC_TIMER_8_BIT (C++ enumerator), 616 LEDC_TIMER_9_BIT (C++ enumerator), 616 LEDC_TIMER_BIT_MAX (C++ enumerator), 616 ledc_timer_bit_t (C++ enum), 615 ledc_timer_config (C++ function), 605 ledc_timer_config_t (C++ class), 612 ledc_timer_config_t::bit_num (C++ mem-
ber), 612 ledc_timer_config_t::clk_cfg (C++ mem-
ber), 613 ledc_timer_config_t::duty_resolution
(C++ member), 612 ledc_timer_config_t::freq_hz (C++ mem-
ber), 612 ledc_timer_config_t::speed_mode (C++
member), 612 ledc_timer_config_t::timer_num (C++
member), 612 LEDC_TIMER_MAX (C++ enumerator), 615 ledc_timer_pause (C++ function), 608 ledc_timer_resume (C++ function), 608 ledc_timer_rst (C++ function), 608

ledc_timer_set (C++ function), 608 ledc_timer_t (C++ enum), 615 ledc_update_duty (C++ function), 605 LEDC_USE_APB_CLK (C++ enumerator), 614 LEDC_USE_RTC8M_CLK (C++ enumerator), 614 LEDC_USE_XTAL_CLK (C++ enumerator), 614 linenoiseCompletions (C++ type), 1100
M
M_BGE (C macro), 1895 M_BL (C macro), 1895 M_BX (C macro), 1895 M_BXF (C macro), 1895 M_BXZ (C macro), 1895 M_LABEL (C macro), 1895 MALLOC_CAP_32BIT (C macro), 1273 MALLOC_CAP_8BIT (C macro), 1273 MALLOC_CAP_DEFAULT (C macro), 1273 MALLOC_CAP_DMA (C macro), 1273 MALLOC_CAP_EXEC (C macro), 1273 MALLOC_CAP_INTERNAL (C macro), 1273 MALLOC_CAP_INVALID (C macro), 1273 MALLOC_CAP_IRAM_8BIT (C macro), 1273 MALLOC_CAP_PID2 (C macro), 1273 MALLOC_CAP_PID3 (C macro), 1273 MALLOC_CAP_PID4 (C macro), 1273 MALLOC_CAP_PID5 (C macro), 1273 MALLOC_CAP_PID6 (C macro), 1273 MALLOC_CAP_PID7 (C macro), 1273 MALLOC_CAP_RETENTION (C macro), 1273 MALLOC_CAP_RTCRAM (C macro), 1273 MALLOC_CAP_SPIRAM (C macro), 1273 MAX_BLE_DEVNAME_LEN (C macro), 968 MAX_BLE_MANUFACTURER_DATA_LEN (C macro),
968 MAX_FDS (C macro), 1074 MAX_PASSPHRASE_LEN (C macro), 400 MAX_SSID_LEN (C macro), 400 MAX_WPS_AP_CRED (C macro), 400 mb_communication_info_t (C++ union), 927 mb_communication_info_t::baudrate
(C++ member), 928 mb_communication_info_t::dummy_port
(C++ member), 928 mb_communication_info_t::ip_addr (C++
member), 928 mb_communication_info_t::ip_addr_type
(C++ member), 928 mb_communication_info_t::ip_mode (C++
member), 928 mb_communication_info_t::ip_netif_ptr
(C++ member), 928 mb_communication_info_t::ip_port (C++
member), 928 mb_communication_info_t::mode (C++
member), 928 mb_communication_info_t::parity (C++
member), 928

Espressif Systems

2139

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

mb_communication_info_t::port (C++ member), 928
mb_communication_info_t::slave_addr (C++ member), 928
mb_communication_info_t::[anonymous] (C++ member), 928
MB_CONTROLLER_PRIORITY (C macro), 928 MB_CONTROLLER_STACK_SIZE (C macro), 928 mb_descr_size_t (C++ enum), 934 mb_descr_type_t (C++ enum), 934 MB_DEVICE_ADDRESS (C macro), 928 MB_DEVICE_SPEED (C macro), 928 MB_EVENT_COILS_RD (C++ enumerator), 929 MB_EVENT_COILS_WR (C++ enumerator), 929 MB_EVENT_DISCRETE_RD (C++ enumerator), 929 mb_event_group_t (C++ enum), 929 MB_EVENT_HOLDING_REG_RD (C++ enumerator),
929 MB_EVENT_HOLDING_REG_WR (C++ enumerator),
929 MB_EVENT_INPUT_REG_RD (C++ enumerator), 929 MB_EVENT_NO_EVENTS (C++ enumerator), 929 MB_EVENT_STACK_STARTED (C++ enumerator),
929 MB_IPV4 (C++ enumerator), 930 MB_IPV6 (C++ enumerator), 930 MB_MASTER_ASSERT (C macro), 934 MB_MASTER_CHECK (C macro), 934 MB_MODE_ASCII (C++ enumerator), 930 MB_MODE_RTU (C++ enumerator), 930 MB_MODE_TCP (C++ enumerator), 930 mb_mode_type_t (C++ enum), 930 MB_MODE_UDP (C++ enumerator), 930 MB_PAR_INFO_TOUT (C macro), 928 MB_PARAM_COIL (C++ enumerator), 930 MB_PARAM_COUNT (C++ enumerator), 930 MB_PARAM_DISCRETE (C++ enumerator), 930 MB_PARAM_HOLDING (C++ enumerator), 929 mb_param_info_t (C++ class), 936 mb_param_info_t::address (C++ member),
936 mb_param_info_t::mb_offset (C++ member),
936 mb_param_info_t::size (C++ member), 936 mb_param_info_t::time_stamp (C++ mem-
ber), 936 mb_param_info_t::type (C++ member), 936 MB_PARAM_INPUT (C++ enumerator), 930 mb_param_perms_t (C++ enum), 935 mb_param_request_t (C++ class), 934 mb_param_request_t::command (C++ mem-
ber), 934 mb_param_request_t::reg_size (C++ mem-
ber), 934 mb_param_request_t::reg_start (C++
member), 934 mb_param_request_t::slave_addr (C++
member), 934

mb_param_type_t (C++ enum), 929 MB_PARAM_UNKNOWN (C++ enumerator), 930 mb_parameter_descriptor_t (C++ class), 933 mb_parameter_descriptor_t::access
(C++ member), 933 mb_parameter_descriptor_t::cid (C++
member), 933 mb_parameter_descriptor_t::mb_param_type
(C++ member), 933 mb_parameter_descriptor_t::mb_reg_start
(C++ member), 933 mb_parameter_descriptor_t::mb_size
(C++ member), 933 mb_parameter_descriptor_t::mb_slave_addr
(C++ member), 933 mb_parameter_descriptor_t::param_key
(C++ member), 933 mb_parameter_descriptor_t::param_offset
(C++ member), 933 mb_parameter_descriptor_t::param_opts
(C++ member), 933 mb_parameter_descriptor_t::param_size
(C++ member), 933 mb_parameter_descriptor_t::param_type
(C++ member), 933 mb_parameter_descriptor_t::param_units
(C++ member), 933 mb_parameter_opt_t (C++ union), 932 mb_parameter_opt_t::max (C++ member), 933 mb_parameter_opt_t::min (C++ member), 933 mb_parameter_opt_t::opt1 (C++ member),
933 mb_parameter_opt_t::opt2 (C++ member),
933 mb_parameter_opt_t::opt3 (C++ member),
933 mb_parameter_opt_t::step (C++ member),
933 mb_parameter_opt_t::[anonymous] (C++
member), 933 MB_PARITY_NONE (C macro), 928 MB_PORT_COUNT (C++ enumerator), 929 MB_PORT_INACTIVE (C++ enumerator), 929 MB_PORT_SERIAL_MASTER (C++ enumerator), 929 MB_PORT_SERIAL_SLAVE (C++ enumerator), 929 MB_PORT_TCP_MASTER (C++ enumerator), 929 MB_PORT_TCP_SLAVE (C++ enumerator), 929 mb_port_type_t (C++ enum), 929 mb_register_area_descriptor_t (C++
class), 937 mb_register_area_descriptor_t::address
(C++ member), 937 mb_register_area_descriptor_t::size
(C++ member), 937 mb_register_area_descriptor_t::start_offset
(C++ member), 937 mb_register_area_descriptor_t::type
(C++ member), 937

Espressif Systems

2140

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

MB_RETURN_ON_FALSE (C macro), 928 MB_SLAVE_ASSERT (C macro), 937 MB_SLAVE_CHECK (C macro), 937 mb_tcp_addr_type_t (C++ enum), 930 MB_UART_PORT (C macro), 928 mbc_master_destroy (C++ function), 931 mbc_master_get_cid_info (C++ function), 931 mbc_master_get_parameter (C++ function),
932 mbc_master_init (C++ function), 930 mbc_master_init_iface (C++ function), 931 mbc_master_init_tcp (C++ function), 930 mbc_master_send_request (C++ function), 931 mbc_master_set_descriptor (C++ function),
931 mbc_master_set_parameter (C++ function),
932 mbc_master_setup (C++ function), 931 mbc_master_start (C++ function), 931 mbc_slave_check_event (C++ function), 936 mbc_slave_destroy (C++ function), 935 mbc_slave_get_param_info (C++ function),
936 mbc_slave_init (C++ function), 935 mbc_slave_init_iface (C++ function), 935 mbc_slave_init_tcp (C++ function), 935 mbc_slave_set_descriptor (C++ function),
936 mbc_slave_setup (C++ function), 936 mbc_slave_start (C++ function), 936 MCPWM0A (C++ enumerator), 635 MCPWM0B (C++ enumerator), 635 MCPWM1A (C++ enumerator), 635 MCPWM1B (C++ enumerator), 635 MCPWM2A (C++ enumerator), 636 MCPWM2B (C++ enumerator), 636 MCPWM_ACTION_FORCE_HIGH (C++ enumerator),
640 MCPWM_ACTION_FORCE_LOW (C++ enumerator),
640 MCPWM_ACTION_NO_CHANGE (C++ enumerator),
640 mcpwm_action_on_pwmxa_t (C++ type), 635 mcpwm_action_on_pwmxb_t (C++ type), 635 MCPWM_ACTION_TOGGLE (C++ enumerator), 640 MCPWM_ACTIVE_HIGH_COMPLIMENT_MODE
(C++ enumerator), 639 MCPWM_ACTIVE_HIGH_MODE (C++ enumerator),
639 MCPWM_ACTIVE_LOW_COMPLIMENT_MODE (C++
enumerator), 639 MCPWM_ACTIVE_LOW_MODE (C++ enumerator), 639 MCPWM_ACTIVE_RED_FED_FROM_PWMXA (C++
enumerator), 639 MCPWM_ACTIVE_RED_FED_FROM_PWMXB (C++
enumerator), 639 MCPWM_BOTH_EDGE (C++ enumerator), 638 MCPWM_BYPASS_FED (C++ enumerator), 639

MCPWM_BYPASS_RED (C++ enumerator), 639 MCPWM_CAP_0 (C++ enumerator), 636 MCPWM_CAP_1 (C++ enumerator), 636 MCPWM_CAP_2 (C++ enumerator), 636 mcpwm_capture_channel_id_t (C++ type), 635 mcpwm_capture_config_t (C++ class), 634 mcpwm_capture_config_t::cap_edge (C++
member), 634 mcpwm_capture_config_t::cap_prescale
(C++ member), 634 mcpwm_capture_config_t::capture_cb
(C++ member), 634 mcpwm_capture_config_t::user_data
(C++ member), 634 mcpwm_capture_disable (C++ function), 630 mcpwm_capture_disable_channel (C++ func-
tion), 630 mcpwm_capture_enable (C++ function), 630 mcpwm_capture_enable_channel (C++ func-
tion), 630 mcpwm_capture_on_edge_t (C++ enum), 638 mcpwm_capture_signal_get_edge (C++ func-
tion), 631 mcpwm_capture_signal_get_value (C++
function), 631 mcpwm_capture_signal_t (C++ enum), 640 mcpwm_carrier_config_t (C++ class), 634 mcpwm_carrier_config_t::carrier_duty
(C++ member), 634 mcpwm_carrier_config_t::carrier_ivt_mode
(C++ member), 634 mcpwm_carrier_config_t::carrier_os_mode
(C++ member), 634 mcpwm_carrier_config_t::carrier_period
(C++ member), 634 mcpwm_carrier_config_t::pulse_width_in_os
(C++ member), 634 mcpwm_carrier_disable (C++ function), 627 mcpwm_carrier_enable (C++ function), 627 mcpwm_carrier_init (C++ function), 627 mcpwm_carrier_oneshot_mode_disable
(C++ function), 628 mcpwm_carrier_oneshot_mode_enable
(C++ function), 628 mcpwm_carrier_os_t (C++ enum), 637 MCPWM_CARRIER_OUT_IVT_DIS (C++ enumera-
tor), 637 MCPWM_CARRIER_OUT_IVT_EN (C++ enumerator),
637 mcpwm_carrier_out_ivt_t (C++ enum), 637 mcpwm_carrier_output_invert (C++ func-
tion), 628 mcpwm_carrier_set_duty_cycle (C++ func-
tion), 628 mcpwm_carrier_set_period (C++ function),
627 mcpwm_config_t (C++ class), 633 mcpwm_config_t::cmpr_a (C++ member), 633

Espressif Systems

2141

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

mcpwm_config_t::cmpr_b (C++ member), 633 mcpwm_config_t::counter_mode (C++ mem-
ber), 633 mcpwm_config_t::duty_mode (C++ member),
633 mcpwm_config_t::frequency (C++ member),
633 MCPWM_COUNTER_MAX (C++ enumerator), 639 mcpwm_counter_type_t (C++ enum), 638 MCPWM_DEADTIME_BYPASS (C++ enumerator), 639 mcpwm_deadtime_disable (C++ function), 629 mcpwm_deadtime_enable (C++ function), 628 MCPWM_DEADTIME_TYPE_MAX (C++ enumerator),
639 mcpwm_deadtime_type_t (C++ enum), 639 MCPWM_DOWN_COUNTER (C++ enumerator), 638 MCPWM_DUTY_MODE_0 (C++ enumerator), 639 MCPWM_DUTY_MODE_1 (C++ enumerator), 639 MCPWM_DUTY_MODE_MAX (C++ enumerator), 639 mcpwm_duty_type_t (C++ enum), 639 MCPWM_FAULT_0 (C++ enumerator), 636 MCPWM_FAULT_1 (C++ enumerator), 636 MCPWM_FAULT_2 (C++ enumerator), 636 mcpwm_fault_deinit (C++ function), 630 mcpwm_fault_init (C++ function), 629 mcpwm_fault_input_level_t (C++ enum), 638 mcpwm_fault_set_cyc_mode (C++ function),
629 mcpwm_fault_set_oneshot_mode (C++ func-
tion), 629 mcpwm_fault_signal_t (C++ enum), 637 MCPWM_FORCE_MCPWMXA_HIGH (C macro), 635 MCPWM_FORCE_MCPWMXA_LOW (C macro), 635 MCPWM_FORCE_MCPWMXB_HIGH (C macro), 635 MCPWM_FORCE_MCPWMXB_LOW (C macro), 635 MCPWM_FREEZE_COUNTER (C++ enumerator), 638 MCPWM_GEN_A (C++ enumerator), 636 MCPWM_GEN_ACTION_HIGH (C++ enumerator), 624 MCPWM_GEN_ACTION_KEEP (C++ enumerator), 623 MCPWM_GEN_ACTION_LOW (C++ enumerator), 623 MCPWM_GEN_ACTION_TOGGLE (C++ enumerator),
624 MCPWM_GEN_B (C++ enumerator), 637 MCPWM_GEN_MAX (C++ enumerator), 637 mcpwm_generator_action_t (C++ enum), 623 mcpwm_generator_t (C++ enum), 636 mcpwm_get_duty (C++ function), 626 mcpwm_get_duty_in_us (C++ function), 626 mcpwm_get_frequency (C++ function), 626 mcpwm_gpio_init (C++ function), 624 mcpwm_group_set_resolution (C++ function),
624 MCPWM_HAL_GENERATOR_MODE_FORCE_HIGH
(C++ enumerator), 639 MCPWM_HAL_GENERATOR_MODE_FORCE_LOW
(C++ enumerator), 639 MCPWM_HIGH_LEVEL_TGR (C++ enumerator), 638 mcpwm_init (C++ function), 624

mcpwm_intr_t (C++ enum), 638 mcpwm_io_signals_t (C++ enum), 635 mcpwm_isr_register (C++ function), 632 MCPWM_LL_INTR_CAP0 (C++ enumerator), 638 MCPWM_LL_INTR_CAP1 (C++ enumerator), 638 MCPWM_LL_INTR_CAP2 (C++ enumerator), 638 MCPWM_LOW_LEVEL_TGR (C++ enumerator), 638 MCPWM_NEG_EDGE (C++ enumerator), 638 MCPWM_NO_CHANGE_IN_MCPWMXA (C macro), 635 MCPWM_NO_CHANGE_IN_MCPWMXB (C macro), 635 MCPWM_ONESHOT_MODE_DIS (C++ enumerator),
637 MCPWM_ONESHOT_MODE_EN (C++ enumerator), 637 mcpwm_operator_t (C++ type), 635 MCPWM_OPR_A (C macro), 634 MCPWM_OPR_B (C macro), 634 MCPWM_OPR_MAX (C macro), 634 mcpwm_output_action_t (C++ enum), 639 mcpwm_pin_config_t (C++ class), 632 mcpwm_pin_config_t::mcpwm0a_out_num
(C++ member), 632 mcpwm_pin_config_t::mcpwm0b_out_num
(C++ member), 632 mcpwm_pin_config_t::mcpwm1a_out_num
(C++ member), 632 mcpwm_pin_config_t::mcpwm1b_out_num
(C++ member), 633 mcpwm_pin_config_t::mcpwm2a_out_num
(C++ member), 633 mcpwm_pin_config_t::mcpwm2b_out_num
(C++ member), 633 mcpwm_pin_config_t::mcpwm_cap0_in_num
(C++ member), 633 mcpwm_pin_config_t::mcpwm_cap1_in_num
(C++ member), 633 mcpwm_pin_config_t::mcpwm_cap2_in_num
(C++ member), 633 mcpwm_pin_config_t::mcpwm_fault0_in_num
(C++ member), 633 mcpwm_pin_config_t::mcpwm_fault1_in_num
(C++ member), 633 mcpwm_pin_config_t::mcpwm_fault2_in_num
(C++ member), 633 mcpwm_pin_config_t::mcpwm_sync0_in_num
(C++ member), 633 mcpwm_pin_config_t::mcpwm_sync1_in_num
(C++ member), 633 mcpwm_pin_config_t::mcpwm_sync2_in_num
(C++ member), 633 MCPWM_POS_EDGE (C++ enumerator), 638 MCPWM_SELCT_SYNC0 (C macro), 634 MCPWM_SELCT_SYNC1 (C macro), 634 MCPWM_SELCT_SYNC2 (C macro), 635 MCPWM_SELECT_CAP0 (C++ enumerator), 640 MCPWM_SELECT_CAP1 (C++ enumerator), 640 MCPWM_SELECT_CAP2 (C++ enumerator), 640 MCPWM_SELECT_F0 (C++ enumerator), 637 MCPWM_SELECT_F1 (C++ enumerator), 637

Espressif Systems

2142

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

MCPWM_SELECT_F2 (C++ enumerator), 637 MCPWM_SELECT_GPIO_SYNC0 (C++ enumerator),
637 MCPWM_SELECT_GPIO_SYNC1 (C++ enumerator),
637 MCPWM_SELECT_GPIO_SYNC2 (C++ enumerator),
637 MCPWM_SELECT_NO_INPUT (C++ enumerator), 637 MCPWM_SELECT_TIMER0_SYNC (C++ enumerator),
637 MCPWM_SELECT_TIMER1_SYNC (C++ enumerator),
637 MCPWM_SELECT_TIMER2_SYNC (C++ enumerator),
637 mcpwm_set_duty (C++ function), 625 mcpwm_set_duty_in_us (C++ function), 625 mcpwm_set_duty_type (C++ function), 625 mcpwm_set_frequency (C++ function), 625 mcpwm_set_pin (C++ function), 624 mcpwm_set_signal_high (C++ function), 626 mcpwm_set_signal_low (C++ function), 626 mcpwm_set_timer_sync_output (C++ func-
tion), 631 mcpwm_start (C++ function), 627 mcpwm_stop (C++ function), 627 MCPWM_SWSYNC_SOURCE_DISABLED (C++ enu-
merator), 638 MCPWM_SWSYNC_SOURCE_SYNCIN (C++ enumera-
tor), 638 MCPWM_SWSYNC_SOURCE_TEP (C++ enumerator),
638 MCPWM_SWSYNC_SOURCE_TEZ (C++ enumerator),
638 MCPWM_SYNC_0 (C++ enumerator), 636 MCPWM_SYNC_1 (C++ enumerator), 636 MCPWM_SYNC_2 (C++ enumerator), 636 mcpwm_sync_config_t (C++ class), 634 mcpwm_sync_config_t::count_direction
(C++ member), 634 mcpwm_sync_config_t::sync_sig (C++
member), 634 mcpwm_sync_config_t::timer_val (C++
member), 634 mcpwm_sync_configure (C++ function), 631 mcpwm_sync_disable (C++ function), 631 mcpwm_sync_enable (C++ function), 631 mcpwm_sync_invert_gpio_synchro (C++
function), 632 mcpwm_sync_signal_t (C++ enum), 637 MCPWM_TIMER_0 (C++ enumerator), 636 MCPWM_TIMER_1 (C++ enumerator), 636 MCPWM_TIMER_2 (C++ enumerator), 636 MCPWM_TIMER_COUNT_MODE_DOWN (C++ enumer-
ator), 623 MCPWM_TIMER_COUNT_MODE_PAUSE (C++ enu-
merator), 623 mcpwm_timer_count_mode_t (C++ enum), 623

MCPWM_TIMER_COUNT_MODE_UP (C++ enumerator), 623
MCPWM_TIMER_COUNT_MODE_UP_DOWN (C++ enumerator), 623
MCPWM_TIMER_DIRECTION_DOWN (C++ enumerator), 623
mcpwm_timer_direction_t (C++ enum), 623 MCPWM_TIMER_DIRECTION_UP (C++ enumerator),
623 MCPWM_TIMER_EVENT_PEAK (C++ enumerator),
623 mcpwm_timer_event_t (C++ enum), 623 MCPWM_TIMER_EVENT_ZERO (C++ enumerator),
623 mcpwm_timer_execute_cmd_t (C++ enum), 623 MCPWM_TIMER_MAX (C++ enumerator), 636 mcpwm_timer_set_resolution (C++ function),
625 MCPWM_TIMER_START_NO_STOP (C++ enumera-
tor), 623 MCPWM_TIMER_START_STOP_AT_PEAK (C++
enumerator), 623 MCPWM_TIMER_START_STOP_AT_ZERO (C++
enumerator), 623 MCPWM_TIMER_STOP_AT_PEAK (C++ enumerator),
623 MCPWM_TIMER_STOP_AT_ZERO (C++ enumerator),
623 mcpwm_timer_sync_trigger_t (C++ enum),
637 mcpwm_timer_t (C++ enum), 636 mcpwm_timer_trigger_soft_sync (C++ func-
tion), 632 MCPWM_TOG_MCPWMXA (C macro), 635 MCPWM_TOG_MCPWMXB (C macro), 635 MCPWM_TRIP_TYPE_CBC (C++ enumerator), 624 MCPWM_TRIP_TYPE_OST (C++ enumerator), 624 mcpwm_trip_type_t (C++ enum), 624 MCPWM_UNIT_0 (C++ enumerator), 636 MCPWM_UNIT_1 (C++ enumerator), 636 MCPWM_UNIT_MAX (C++ enumerator), 636 mcpwm_unit_t (C++ enum), 636 MCPWM_UP_COUNTER (C++ enumerator), 638 MCPWM_UP_DOWN_COUNTER (C++ enumerator), 638 mdns_delegate_hostname_add (C++ function),
904 mdns_delegate_hostname_remove (C++ func-
tion), 905 mdns_free (C++ function), 904 mdns_handle_system_event (C++ function),
913 mdns_hostname_exists (C++ function), 905 mdns_hostname_set (C++ function), 904 MDNS_IF_AP (C++ enumerator), 915 MDNS_IF_ETH (C++ enumerator), 915 mdns_if_internal (C++ enum), 915 MDNS_IF_MAX (C++ enumerator), 915 MDNS_IF_STA (C++ enumerator), 915

Espressif Systems

2143

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

mdns_if_t (C++ type), 915 mdns_init (C++ function), 904 mdns_instance_name_set (C++ function), 905 mdns_ip_addr_s (C++ class), 914 mdns_ip_addr_s::addr (C++ member), 914 mdns_ip_addr_s::next (C++ member), 914 mdns_ip_addr_t (C++ type), 915 MDNS_IP_PROTOCOL_MAX (C++ enumerator), 915 mdns_ip_protocol_t (C++ enum), 915 MDNS_IP_PROTOCOL_V4 (C++ enumerator), 915 MDNS_IP_PROTOCOL_V6 (C++ enumerator), 915 mdns_query (C++ function), 912 mdns_query_a (C++ function), 913 mdns_query_aaaa (C++ function), 913 mdns_query_async_delete (C++ function), 911 mdns_query_async_get_results (C++ func-
tion), 911 mdns_query_async_new (C++ function), 911 mdns_query_generic (C++ function), 911 MDNS_QUERY_MULTICAST (C++ enumerator), 915 mdns_query_notify_t (C++ type), 915 mdns_query_ptr (C++ function), 912 mdns_query_results_free (C++ function), 912 mdns_query_srv (C++ function), 912 mdns_query_transmission_type_t (C++
enum), 915 mdns_query_txt (C++ function), 912 MDNS_QUERY_UNICAST (C++ enumerator), 915 mdns_result_s (C++ class), 914 mdns_result_s::addr (C++ member), 914 mdns_result_s::hostname (C++ member), 914 mdns_result_s::instance_name (C++ mem-
ber), 914 mdns_result_s::ip_protocol (C++ member),
914 mdns_result_s::next (C++ member), 914 mdns_result_s::port (C++ member), 914 mdns_result_s::proto (C++ member), 914 mdns_result_s::service_type (C++ mem-
ber), 914 mdns_result_s::tcpip_if (C++ member), 914 mdns_result_s::ttl (C++ member), 914 mdns_result_s::txt (C++ member), 914 mdns_result_s::txt_count (C++ member),
914 mdns_result_s::txt_value_len (C++ mem-
ber), 914 mdns_result_t (C++ type), 915 mdns_search_once_t (C++ type), 915 mdns_service_add (C++ function), 905 mdns_service_add_for_host (C++ function),
905 mdns_service_exists (C++ function), 906 mdns_service_exists_with_instance
(C++ function), 906 mdns_service_instance_name_set (C++
function), 907

mdns_service_instance_name_set_for_host (C++ function), 907
mdns_service_port_set (C++ function), 907 mdns_service_port_set_for_host (C++
function), 907 mdns_service_remove (C++ function), 906 mdns_service_remove_all (C++ function), 911 mdns_service_remove_for_host (C++ func-
tion), 906 mdns_service_subtype_add_for_host
(C++ function), 910 mdns_service_txt_item_remove (C++ func-
tion), 910 mdns_service_txt_item_remove_for_host
(C++ function), 910 mdns_service_txt_item_set (C++ function),
908 mdns_service_txt_item_set_for_host
(C++ function), 909 mdns_service_txt_item_set_for_host_with_explicit_
(C++ function), 909 mdns_service_txt_item_set_with_explicit_value_len
(C++ function), 908 mdns_service_txt_set (C++ function), 908 mdns_service_txt_set_for_host (C++ func-
tion), 908 mdns_txt_item_t (C++ class), 913 mdns_txt_item_t::key (C++ member), 914 mdns_txt_item_t::value (C++ member), 914 MDNS_TYPE_A (C macro), 915 MDNS_TYPE_AAAA (C macro), 915 MDNS_TYPE_ANY (C macro), 915 MDNS_TYPE_NSEC (C macro), 915 MDNS_TYPE_OPT (C macro), 915 MDNS_TYPE_PTR (C macro), 915 MDNS_TYPE_SRV (C macro), 915 MDNS_TYPE_TXT (C macro), 915 mesh_addr_t (C++ union), 437 mesh_addr_t::addr (C++ member), 437 mesh_addr_t::mip (C++ member), 437 mesh_ap_cfg_t (C++ class), 442 mesh_ap_cfg_t::max_connection (C++
member), 442 mesh_ap_cfg_t::nonmesh_max_connection
(C++ member), 442 mesh_ap_cfg_t::password (C++ member), 442 MESH_ASSOC_FLAG_NETWORK_FREE (C macro),
445 MESH_ASSOC_FLAG_ROOT_FIXED (C macro), 445 MESH_ASSOC_FLAG_ROOTS_FOUND (C macro),
445 MESH_ASSOC_FLAG_VOTE_IN_PROGRESS (C
macro), 445 mesh_cfg_t (C++ class), 442 mesh_cfg_t::allow_channel_switch (C++
member), 442 mesh_cfg_t::channel (C++ member), 442 mesh_cfg_t::crypto_funcs (C++ member),

Espressif Systems

2144

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

443

mesh_event_info_t::find_network (C++

mesh_cfg_t::mesh_ap (C++ member), 443

member), 438

mesh_cfg_t::mesh_id (C++ member), 443

mesh_event_info_t::layer_change (C++

mesh_cfg_t::router (C++ member), 443

member), 438

MESH_DATA_DROP (C macro), 445

mesh_event_info_t::network_state (C++

MESH_DATA_ENC (C macro), 445

member), 438

MESH_DATA_FROMDS (C macro), 445

mesh_event_info_t::no_parent (C++ mem-

MESH_DATA_GROUP (C macro), 445

ber), 438

MESH_DATA_NONBLOCK (C macro), 445

mesh_event_info_t::ps_duty (C++ member),

MESH_DATA_P2P (C macro), 445

438

mesh_data_t (C++ class), 441

mesh_event_info_t::root_addr (C++ mem-

mesh_data_t::data (C++ member), 442

ber), 438

mesh_data_t::proto (C++ member), 442

mesh_event_info_t::root_conflict (C++

mesh_data_t::size (C++ member), 442

member), 438

mesh_data_t::tos (C++ member), 442

mesh_event_info_t::root_fixed (C++

MESH_DATA_TODS (C macro), 445

member), 438

mesh_disconnect_reason_t (C++ enum), 448 mesh_event_info_t::router_switch (C++

MESH_EVENT_CHANNEL_SWITCH (C++ enumera-

member), 438

tor), 446

mesh_event_info_t::routing_table (C++

mesh_event_channel_switch_t (C++ class),

member), 438

439

mesh_event_info_t::scan_done (C++ mem-

mesh_event_channel_switch_t::channel

ber), 438

(C++ member), 439

mesh_event_info_t::switch_req (C++

MESH_EVENT_CHILD_CONNECTED (C++ enumera-

member), 438

tor), 446

mesh_event_info_t::toDS_state (C++

mesh_event_child_connected_t (C++ type),

member), 438

446

mesh_event_info_t::vote_started (C++

MESH_EVENT_CHILD_DISCONNECTED (C++ enu-

member), 438

merator), 446

MESH_EVENT_LAYER_CHANGE (C++ enumerator),

mesh_event_child_disconnected_t (C++

447

type), 446

mesh_event_layer_change_t (C++ class), 439

mesh_event_connected_t (C++ class), 439

mesh_event_layer_change_t::new_layer

mesh_event_connected_t::connected

(C++ member), 440

(C++ member), 439

MESH_EVENT_MAX (C++ enumerator), 447

mesh_event_connected_t::duty (C++ mem- MESH_EVENT_NETWORK_STATE (C++ enumerator),

ber), 439

447

mesh_event_connected_t::self_layer

mesh_event_network_state_t (C++ class),

(C++ member), 439

441

mesh_event_disconnected_t (C++ type), 446 mesh_event_network_state_t::is_rootless

MESH_EVENT_FIND_NETWORK (C++ enumerator),

(C++ member), 441

447

MESH_EVENT_NO_PARENT_FOUND (C++ enumera-

mesh_event_find_network_t (C++ class), 440

tor), 446

mesh_event_find_network_t::channel

mesh_event_no_parent_found_t (C++ class),

(C++ member), 440

439

mesh_event_find_network_t::router_bssidmesh_event_no_parent_found_t::scan_times

(C++ member), 440

(C++ member), 439

mesh_event_id_t (C++ enum), 446

MESH_EVENT_PARENT_CONNECTED (C++ enumer-

mesh_event_info_t (C++ union), 438

ator), 446

mesh_event_info_t::channel_switch

MESH_EVENT_PARENT_DISCONNECTED (C++

(C++ member), 438

enumerator), 446

mesh_event_info_t::child_connected

MESH_EVENT_PS_CHILD_DUTY (C++ enumerator),

(C++ member), 438

447

mesh_event_info_t::child_disconnected MESH_EVENT_PS_DEVICE_DUTY (C++ enumera-

(C++ member), 438

tor), 447

mesh_event_info_t::connected (C++ mem- mesh_event_ps_duty_t (C++ class), 441

ber), 438

mesh_event_ps_duty_t::child_connected

mesh_event_info_t::disconnected (C++

(C++ member), 441

member), 438

mesh_event_ps_duty_t::duty (C++ member),

Espressif Systems

2145

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

441

mesh_event_vote_started_t::rc_addr

MESH_EVENT_PS_PARENT_DUTY (C++ enumera-

(C++ member), 440

tor), 447

mesh_event_vote_started_t::reason

MESH_EVENT_ROOT_ADDRESS (C++ enumerator),

(C++ member), 440

447

MESH_EVENT_VOTE_STOPPED (C++ enumerator),

mesh_event_root_address_t (C++ type), 446

447

MESH_EVENT_ROOT_ASKED_YIELD (C++ enumer- MESH_IDLE (C++ enumerator), 447

ator), 447

MESH_INIT_CONFIG_DEFAULT (C macro), 446

mesh_event_root_conflict_t (C++ class), MESH_LEAF (C++ enumerator), 448

440

MESH_MPS (C macro), 444

mesh_event_root_conflict_t::addr (C++ MESH_MTU (C macro), 444

member), 440

MESH_NODE (C++ enumerator), 448

mesh_event_root_conflict_t::capacity MESH_OPT_RECV_DS_ADDR (C macro), 445

(C++ member), 440

MESH_OPT_SEND_GROUP (C macro), 445

mesh_event_root_conflict_t::rssi (C++ mesh_opt_t (C++ class), 441

member), 440

mesh_opt_t::len (C++ member), 441

MESH_EVENT_ROOT_FIXED (C++ enumerator), 447 mesh_opt_t::type (C++ member), 441

mesh_event_root_fixed_t (C++ class), 441 mesh_opt_t::val (C++ member), 441

mesh_event_root_fixed_t::is_fixed

MESH_PROTO_AP (C++ enumerator), 448

(C++ member), 441

MESH_PROTO_BIN (C++ enumerator), 448

MESH_EVENT_ROOT_SWITCH_ACK (C++ enumera- MESH_PROTO_HTTP (C++ enumerator), 448

tor), 447

MESH_PROTO_JSON (C++ enumerator), 448

MESH_EVENT_ROOT_SWITCH_REQ (C++ enumera- MESH_PROTO_MQTT (C++ enumerator), 448

tor), 447

MESH_PROTO_STA (C++ enumerator), 448

mesh_event_root_switch_req_t (C++ class), mesh_proto_t (C++ enum), 448

440

MESH_PS_DEVICE_DUTY_DEMAND (C macro), 446

mesh_event_root_switch_req_t::rc_addr MESH_PS_DEVICE_DUTY_REQUEST (C macro),

(C++ member), 440

445

mesh_event_root_switch_req_t::reason MESH_PS_NETWORK_DUTY_APPLIED_ENTIRE (C

(C++ member), 440

macro), 446

MESH_EVENT_ROUTER_SWITCH (C++ enumerator), MESH_PS_NETWORK_DUTY_APPLIED_UPLINK (C

447

macro), 446

mesh_event_router_switch_t (C++ type), 446 MESH_PS_NETWORK_DUTY_MASTER (C macro),

MESH_EVENT_ROUTING_TABLE_ADD (C++ enu-

446

merator), 446

mesh_rc_config_t (C++ union), 438

mesh_event_routing_table_change_t

mesh_rc_config_t::attempts (C++ member),

(C++ class), 440

439

mesh_event_routing_table_change_t::rt_smiezseh__crhca_ncgoenfig_t::rc_addr (C++ member),

(C++ member), 441

439

mesh_event_routing_table_change_t::rt_sMiEzSeH__nReEwASON_CYCLIC (C++ enumerator), 448

(C++ member), 441

MESH_REASON_DIFF_ID (C++ enumerator), 449

MESH_EVENT_ROUTING_TABLE_REMOVE (C++ MESH_REASON_EMPTY_PASSWORD (C++ enumera-

enumerator), 446

tor), 449

MESH_EVENT_SCAN_DONE (C++ enumerator), 447 MESH_REASON_IE_UNKNOWN (C++ enumerator),

mesh_event_scan_done_t (C++ class), 441

449

mesh_event_scan_done_t::number (C++ MESH_REASON_LEAF (C++ enumerator), 449

member), 441

MESH_REASON_PARENT_IDLE (C++ enumerator),

MESH_EVENT_STARTED (C++ enumerator), 446

448

MESH_EVENT_STOP_RECONNECTION (C++ enu- MESH_REASON_PARENT_STOPPED (C++ enumera-

merator), 447

tor), 449

MESH_EVENT_STOPPED (C++ enumerator), 446

MESH_REASON_PARENT_UNENCRYPTED (C++

MESH_EVENT_TODS_STATE (C++ enumerator), 447

enumerator), 449

mesh_event_toDS_state_t (C++ enum), 449 MESH_REASON_PARENT_WORSE (C++ enumerator),

MESH_EVENT_VOTE_STARTED (C++ enumerator),

449

447

MESH_REASON_ROOTS (C++ enumerator), 449

mesh_event_vote_started_t (C++ class), 440 MESH_REASON_SCAN_FAIL (C++ enumerator), 449

mesh_event_vote_started_t::attempts MESH_REASON_WAIVE_ROOT (C++ enumerator),

(C++ member), 440

449

Espressif Systems

2146

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

MESH_ROOT (C++ enumerator), 448 MESH_ROOT_LAYER (C macro), 444 mesh_router_t (C++ class), 442 mesh_router_t::allow_router_switch
(C++ member), 442 mesh_router_t::bssid (C++ member), 442 mesh_router_t::password (C++ member), 442 mesh_router_t::ssid (C++ member), 442 mesh_router_t::ssid_len (C++ member), 442 mesh_rx_pending_t (C++ class), 443 mesh_rx_pending_t::toDS (C++ member), 443 mesh_rx_pending_t::toSelf (C++ member),
443 MESH_STA (C++ enumerator), 448 MESH_TODS_REACHABLE (C++ enumerator), 449 MESH_TODS_UNREACHABLE (C++ enumerator), 449 MESH_TOPO_CHAIN (C++ enumerator), 449 MESH_TOPO_TREE (C++ enumerator), 449 MESH_TOS_DEF (C++ enumerator), 448 MESH_TOS_E2E (C++ enumerator), 448 MESH_TOS_P2P (C++ enumerator), 448 mesh_tos_t (C++ enum), 448 mesh_tx_pending_t (C++ class), 443 mesh_tx_pending_t::broadcast (C++ mem-
ber), 443 mesh_tx_pending_t::mgmt (C++ member), 443 mesh_tx_pending_t::to_child (C++ mem-
ber), 443 mesh_tx_pending_t::to_child_p2p (C++
member), 443 mesh_tx_pending_t::to_parent (C++ mem-
ber), 443 mesh_tx_pending_t::to_parent_p2p (C++
member), 443 mesh_type_t (C++ enum), 447 MESH_VOTE_REASON_CHILD_INITIATED (C++
enumerator), 448 MESH_VOTE_REASON_ROOT_INITIATED (C++
enumerator), 448 mesh_vote_reason_t (C++ enum), 448 mesh_vote_t (C++ class), 443 mesh_vote_t::config (C++ member), 443 mesh_vote_t::is_rc_specified (C++ mem-
ber), 443 mesh_vote_t::percentage (C++ member), 443 MessageBufferHandle_t (C++ type), 1249 mip_t (C++ class), 439 mip_t::ip4 (C++ member), 439 mip_t::port (C++ member), 439 MQTT_CONNECTION_ACCEPTED (C++ enumerator),
812 MQTT_CONNECTION_REFUSE_BAD_USERNAME
(C++ enumerator), 812 MQTT_CONNECTION_REFUSE_ID_REJECTED
(C++ enumerator), 812 MQTT_CONNECTION_REFUSE_NOT_AUTHORIZED
(C++ enumerator), 812 MQTT_CONNECTION_REFUSE_PROTOCOL (C++

enumerator), 812 MQTT_CONNECTION_REFUSE_SERVER_UNAVAILABLE
(C++ enumerator), 812 MQTT_ERROR_TYPE_CONNECTION_REFUSED
(C++ enumerator), 812 MQTT_ERROR_TYPE_ESP_TLS (C macro), 811 MQTT_ERROR_TYPE_NONE (C++ enumerator), 812 MQTT_ERROR_TYPE_TCP_TRANSPORT (C++ enu-
merator), 812 MQTT_EVENT_ANY (C++ enumerator), 811 MQTT_EVENT_BEFORE_CONNECT (C++ enumera-
tor), 812 mqtt_event_callback_t (C++ type), 811 MQTT_EVENT_CONNECTED (C++ enumerator), 811 MQTT_EVENT_DATA (C++ enumerator), 812 MQTT_EVENT_DELETED (C++ enumerator), 812 MQTT_EVENT_DISCONNECTED (C++ enumerator),
811 MQTT_EVENT_ERROR (C++ enumerator), 811 MQTT_EVENT_PUBLISHED (C++ enumerator), 812 MQTT_EVENT_SUBSCRIBED (C++ enumerator), 811 MQTT_EVENT_UNSUBSCRIBED (C++ enumerator),
812 MQTT_PROTOCOL_UNDEFINED (C++ enumerator),
813 MQTT_PROTOCOL_V_3_1 (C++ enumerator), 813 MQTT_PROTOCOL_V_3_1_1 (C++ enumerator), 813 MQTT_TRANSPORT_OVER_SSL (C++ enumerator),
813 MQTT_TRANSPORT_OVER_TCP (C++ enumerator),
813 MQTT_TRANSPORT_OVER_WS (C++ enumerator),
813 MQTT_TRANSPORT_OVER_WSS (C++ enumerator),
813 MQTT_TRANSPORT_UNKNOWN (C++ enumerator),
813 multi_heap_aligned_alloc (C++ function),
1275 multi_heap_aligned_free (C++ function),
1276 multi_heap_check (C++ function), 1277 multi_heap_dump (C++ function), 1277 multi_heap_free (C++ function), 1276 multi_heap_free_size (C++ function), 1277 multi_heap_get_allocated_size (C++ func-
tion), 1276 multi_heap_get_info (C++ function), 1277 multi_heap_handle_t (C++ type), 1278 multi_heap_info_t (C++ class), 1278 multi_heap_info_t::allocated_blocks
(C++ member), 1278 multi_heap_info_t::free_blocks (C++
member), 1278 multi_heap_info_t::largest_free_block
(C++ member), 1278 multi_heap_info_t::minimum_free_bytes
(C++ member), 1278

Espressif Systems

2147

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

multi_heap_info_t::total_allocated_bytensvs_get_u32 (C++ function), 1011

(C++ member), 1278

nvs_get_u64 (C++ function), 1011

multi_heap_info_t::total_blocks (C++ nvs_get_u8 (C++ function), 1011

member), 1278

nvs_get_used_entry_count (C++ function),

multi_heap_info_t::total_free_bytes

1014

(C++ member), 1278

nvs_handle (C++ type), 1018

multi_heap_malloc (C++ function), 1276

nvs_handle_t (C++ type), 1018

multi_heap_minimum_free_size (C++ func- nvs_iterator_t (C++ type), 1018

tion), 1277

NVS_KEY_NAME_MAX_SIZE (C macro), 1017

multi_heap_realloc (C++ function), 1276

NVS_KEY_SIZE (C macro), 1009

multi_heap_register (C++ function), 1276

nvs_open (C++ function), 1012

multi_heap_set_lock (C++ function), 1276

nvs_open_from_partition (C++ function),

1012

N

nvs_open_mode (C++ type), 1018

name_uuid (C++ class), 968 name_uuid::name (C++ member), 968 name_uuid::uuid (C++ member), 968 nvs_close (C++ function), 1014 nvs_commit (C++ function), 1013 NVS_DEFAULT_PART_NAME (C macro), 1017 nvs_entry_find (C++ function), 1015 nvs_entry_info (C++ function), 1015 nvs_entry_info_t (C++ class), 1016 nvs_entry_info_t::key (C++ member), 1016 nvs_entry_info_t::namespace_name (C++
member), 1016 nvs_entry_info_t::type (C++ member), 1016 nvs_entry_next (C++ function), 1015 nvs_erase_all (C++ function), 1013 nvs_erase_key (C++ function), 1013 nvs_flash_deinit (C++ function), 1007 nvs_flash_deinit_partition (C++ function),
1007 nvs_flash_erase (C++ function), 1007 nvs_flash_erase_partition (C++ function),
1007 nvs_flash_erase_partition_ptr (C++ func-
tion), 1007 nvs_flash_generate_keys (C++ function),
1008 nvs_flash_init (C++ function), 1006 nvs_flash_init_partition (C++ function),
1006 nvs_flash_init_partition_ptr (C++ func-
tion), 1006 nvs_flash_read_security_cfg (C++ func-
tion), 1008 nvs_flash_secure_init (C++ function), 1007 nvs_flash_secure_init_partition (C++
function), 1008 nvs_get_blob (C++ function), 1012 nvs_get_i16 (C++ function), 1011 nvs_get_i32 (C++ function), 1011

nvs_open_mode_t (C++ enum), 1018 NVS_PART_NAME_MAX_SIZE (C macro), 1017 NVS_READONLY (C++ enumerator), 1018 NVS_READWRITE (C++ enumerator), 1018 nvs_release_iterator (C++ function), 1016 nvs_sec_cfg_t (C++ class), 1008 nvs_sec_cfg_t::eky (C++ member), 1009 nvs_sec_cfg_t::tky (C++ member), 1009 nvs_set_blob (C++ function), 1013 nvs_set_i16 (C++ function), 1009 nvs_set_i32 (C++ function), 1009 nvs_set_i64 (C++ function), 1009 nvs_set_i8 (C++ function), 1009 nvs_set_str (C++ function), 1010 nvs_set_u16 (C++ function), 1009 nvs_set_u32 (C++ function), 1009 nvs_set_u64 (C++ function), 1010 nvs_set_u8 (C++ function), 1009 nvs_stats_t (C++ class), 1016 nvs_stats_t::free_entries (C++ member),
1016 nvs_stats_t::namespace_count (C++ mem-
ber), 1016 nvs_stats_t::total_entries (C++ member),
1016 nvs_stats_t::used_entries (C++ member),
1016 NVS_TYPE_ANY (C++ enumerator), 1018 NVS_TYPE_BLOB (C++ enumerator), 1018 NVS_TYPE_I16 (C++ enumerator), 1018 NVS_TYPE_I32 (C++ enumerator), 1018 NVS_TYPE_I64 (C++ enumerator), 1018 NVS_TYPE_I8 (C++ enumerator), 1018 NVS_TYPE_STR (C++ enumerator), 1018 nvs_type_t (C++ enum), 1018 NVS_TYPE_U16 (C++ enumerator), 1018 NVS_TYPE_U32 (C++ enumerator), 1018 NVS_TYPE_U64 (C++ enumerator), 1018 NVS_TYPE_U8 (C++ enumerator), 1018

nvs_get_i64 (C++ function), 1011 nvs_get_i8 (C++ function), 1010

O

nvs_get_stats (C++ function), 1014

OPENTHREAD_EVENT_GOT_IP6 (C++ enumerator),

nvs_get_str (C++ function), 1011

477

nvs_get_u16 (C++ function), 1011

Espressif Systems

2148

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

OPENTHREAD_EVENT_IF_DOWN (C++ enumerator), PCNT_CHANNEL_LEVEL_ACTION_INVERSE

477

(C++ enumerator), 649

OPENTHREAD_EVENT_IF_UP (C++ enumerator), PCNT_CHANNEL_LEVEL_ACTION_KEEP (C++

477

enumerator), 649

OPENTHREAD_EVENT_LOST_IP6 (C++ enumera- pcnt_channel_level_action_t (C++ enum),

tor), 477

649

OPENTHREAD_EVENT_MULTICAST_GROUP_JOIN PCNT_CHANNEL_MAX (C++ enumerator), 648

(C++ enumerator), 477

pcnt_channel_t (C++ enum), 648

OPENTHREAD_EVENT_MULTICAST_GROUP_LEAVE pcnt_config_t (C++ class), 646

(C++ enumerator), 477

pcnt_config_t::channel (C++ member), 647

OPENTHREAD_EVENT_START (C++ enumerator), pcnt_config_t::counter_h_lim (C++ mem-

477

ber), 647

OPENTHREAD_EVENT_STOP (C++ enumerator), 477 pcnt_config_t::counter_l_lim (C++ mem-

OPENTHREAD_EVENT_TREL_ADD_IP6 (C++ enu-

ber), 647

merator), 477

pcnt_config_t::ctrl_gpio_num (C++ mem-

OPENTHREAD_EVENT_TREL_MULTICAST_GROUP_JOIN ber), 646

(C++ enumerator), 477

pcnt_config_t::hctrl_mode (C++ member),

OPENTHREAD_EVENT_TREL_REMOVE_IP6 (C++

647

enumerator), 477

pcnt_config_t::lctrl_mode (C++ member),

OTA_SIZE_UNKNOWN (C macro), 1327

646

OTA_WITH_SEQUENTIAL_WRITES (C macro), 1327 pcnt_config_t::neg_mode (C++ member), 647

pcnt_config_t::pos_mode (C++ member), 647

P

pcnt_config_t::pulse_gpio_num (C++

PAR_PERMS_READ (C++ enumerator), 935

member), 646

PAR_PERMS_READ_TRIGGER (C++ enumerator), pcnt_config_t::unit (C++ member), 647

935

PCNT_COUNT_DEC (C macro), 647

PAR_PERMS_READ_WRITE (C++ enumerator), 935 PCNT_COUNT_DIS (C macro), 647

PAR_PERMS_READ_WRITE_TRIGGER (C++ enu- PCNT_COUNT_INC (C macro), 647

merator), 935

PCNT_COUNT_MAX (C macro), 647

PAR_PERMS_TRIGGER (C++ enumerator), 935

pcnt_count_mode_t (C++ type), 647

PAR_PERMS_WRITE (C++ enumerator), 935

pcnt_counter_clear (C++ function), 642

PAR_PERMS_WRITE_TRIGGER (C++ enumerator), pcnt_counter_pause (C++ function), 642

935

pcnt_counter_resume (C++ function), 642

PARAM_MAX_SIZE (C++ enumerator), 934

pcnt_ctrl_mode_t (C++ type), 647

PARAM_SIZE_ASCII (C++ enumerator), 934

pcnt_event_disable (C++ function), 643

PARAM_SIZE_ASCII24 (C++ enumerator), 934

pcnt_event_enable (C++ function), 643

PARAM_SIZE_FLOAT (C++ enumerator), 934

PCNT_EVT_H_LIM (C++ enumerator), 648

PARAM_SIZE_U16 (C++ enumerator), 934

PCNT_EVT_L_LIM (C++ enumerator), 648

PARAM_SIZE_U32 (C++ enumerator), 934

PCNT_EVT_MAX (C++ enumerator), 648

PARAM_SIZE_U8 (C++ enumerator), 934

PCNT_EVT_THRES_0 (C++ enumerator), 648

PARAM_TYPE_ASCII (C++ enumerator), 934

PCNT_EVT_THRES_1 (C++ enumerator), 648

PARAM_TYPE_FLOAT (C++ enumerator), 934

pcnt_evt_type_t (C++ enum), 648

PARAM_TYPE_U16 (C++ enumerator), 934

PCNT_EVT_ZERO (C++ enumerator), 648

PARAM_TYPE_U32 (C++ enumerator), 934

pcnt_filter_disable (C++ function), 645

PARAM_TYPE_U8 (C++ enumerator), 934

pcnt_filter_enable (C++ function), 645

PCNT_CHANNEL_0 (C++ enumerator), 648

pcnt_get_counter_value (C++ function), 642

PCNT_CHANNEL_1 (C++ enumerator), 648

pcnt_get_event_status (C++ function), 644

PCNT_CHANNEL_EDGE_ACTION_DECREASE

pcnt_get_event_value (C++ function), 643

(C++ enumerator), 649

pcnt_get_filter_value (C++ function), 645

PCNT_CHANNEL_EDGE_ACTION_HOLD (C++ enu- pcnt_intr_disable (C++ function), 643

merator), 649

pcnt_intr_enable (C++ function), 643

PCNT_CHANNEL_EDGE_ACTION_INCREASE

pcnt_isr_handle_t (C++ type), 647

(C++ enumerator), 649

pcnt_isr_handler_add (C++ function), 645

pcnt_channel_edge_action_t (C++ enum), pcnt_isr_handler_remove (C++ function), 646

649

pcnt_isr_register (C++ function), 644

PCNT_CHANNEL_LEVEL_ACTION_HOLD (C++ pcnt_isr_service_install (C++ function),

enumerator), 649

646

Espressif Systems

2149

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

pcnt_isr_service_uninstall (C++ function), protocomm_ble_stop (C++ function), 968

646

protocomm_close_session (C++ function), 963

pcnt_isr_unregister (C++ function), 644

protocomm_delete (C++ function), 962

PCNT_MODE_DISABLE (C macro), 647

protocomm_http_server_config_t (C++

PCNT_MODE_KEEP (C macro), 647

class), 967

PCNT_MODE_MAX (C macro), 647

protocomm_http_server_config_t::port

PCNT_MODE_REVERSE (C macro), 647

(C++ member), 967

PCNT_PIN_NOT_USED (C macro), 647

protocomm_http_server_config_t::stack_size

PCNT_PORT_0 (C++ enumerator), 648

(C++ member), 967

PCNT_PORT_MAX (C++ enumerator), 648

protocomm_http_server_config_t::task_priority

pcnt_port_t (C++ enum), 648

(C++ member), 967

pcnt_set_event_value (C++ function), 643

protocomm_httpd_config_data_t (C++

pcnt_set_filter_value (C++ function), 645

union), 966

pcnt_set_mode (C++ function), 645

protocomm_httpd_config_data_t::config

pcnt_set_pin (C++ function), 644

(C++ member), 967

PCNT_UNIT_0 (C++ enumerator), 648

protocomm_httpd_config_data_t::handle

PCNT_UNIT_1 (C++ enumerator), 648

(C++ member), 967

PCNT_UNIT_2 (C++ enumerator), 648

protocomm_httpd_config_t (C++ class), 967

PCNT_UNIT_3 (C++ enumerator), 648

protocomm_httpd_config_t::data (C++

pcnt_unit_config (C++ function), 642

member), 967

PCNT_UNIT_COUNT_SIGN_NEG (C++ enumerator), protocomm_httpd_config_t::ext_handle_provided

649

(C++ member), 967

PCNT_UNIT_COUNT_SIGN_POS (C++ enumerator), PROTOCOMM_HTTPD_DEFAULT_CONFIG

(C

649

macro), 967

pcnt_unit_count_sign_t (C++ enum), 649

protocomm_httpd_start (C++ function), 966

PCNT_UNIT_COUNT_SIGN_ZERO_NEG (C++ enu- protocomm_httpd_stop (C++ function), 966

merator), 649

protocomm_new (C++ function), 962

PCNT_UNIT_COUNT_SIGN_ZERO_POS (C++ enu- protocomm_open_session (C++ function), 962

merator), 649

protocomm_remove_endpoint (C++ function),

PCNT_UNIT_MAX (C++ enumerator), 648

962

pcnt_unit_t (C++ enum), 648

protocomm_req_handle (C++ function), 963

pcQueueGetName (C++ function), 1185

protocomm_req_handler_t (C++ type), 964

pcTaskGetName (C++ function), 1162

protocomm_security (C++ class), 965

pcTimerGetName (C++ function), 1216

protocomm_security::cleanup (C++ mem-

PendedFunction_t (C++ type), 1226

ber), 965

portGET_ARGUMENT_COUNT_INNER (C macro), protocomm_security::close_transport_session

1310

(C++ member), 965

print_class_descriptor_cb (C++ type), 790 protocomm_security::decrypt (C++ mem-

PROTOCOM_SEC0 (C++ enumerator), 901

ber), 965

PROTOCOM_SEC1 (C++ enumerator), 901

protocomm_security::encrypt (C++ mem-

PROTOCOM_SEC_CUSTOM (C++ enumerator), 901

ber), 965

protocomm_add_endpoint (C++ function), 962 protocomm_security::init (C++ member),

protocomm_ble_config (C++ class), 968

965

protocomm_ble_config::device_name

protocomm_security::new_transport_session

(C++ member), 968

(C++ member), 965

protocomm_ble_config::manufacturer_dataprotocomm_security::security_req_handler

(C++ member), 968

(C++ member), 965

protocomm_ble_config::manufacturer_datap_rloetnocomm_security::ver (C++ member), 965

(C++ member), 968

protocomm_security_handle_t (C++ type),

protocomm_ble_config::nu_lookup (C++

966

member), 968

protocomm_security_pop (C++ class), 965

protocomm_ble_config::nu_lookup_count protocomm_security_pop::data (C++ mem-

(C++ member), 968

ber), 965

protocomm_ble_config::service_uuid

protocomm_security_pop::len (C++ mem-

(C++ member), 968

ber), 965

protocomm_ble_config_t (C++ type), 969

protocomm_security_pop_t (C++ type), 966

protocomm_ble_name_uuid_t (C++ type), 969 protocomm_security_t (C++ type), 966

protocomm_ble_start (C++ function), 967

protocomm_set_security (C++ function), 963

Espressif Systems

2150

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

protocomm_set_version (C++ function), 964 protocomm_t (C++ type), 965 protocomm_unset_security (C++ function),
964 protocomm_unset_version (C++ function), 964 PROV_DATA_FLAGS_FLAG (C macro), 191 PROV_DATA_IV_INDEX_FLAG (C macro), 191 PROV_DATA_NET_IDX_FLAG (C macro), 191 PROXY_FILTER_BLACKLIST (C++ enumerator),
205 PROXY_FILTER_WHITELIST (C++ enumerator),
205 psk_hint_key_t (C++ type), 823 psk_key_hint (C++ class), 820 psk_key_hint::hint (C++ member), 820 psk_key_hint::key (C++ member), 820 psk_key_hint::key_size (C++ member), 820 PTHREAD_STACK_MIN (C macro), 1130 pvTaskGetThreadLocalStoragePointer
(C++ function), 1163 pvTimerGetTimerID (C++ function), 1213 pxTaskGetStackStart (C++ function), 1162
Q
QueueHandle_t (C++ type), 1196 QueueSetHandle_t (C++ type), 1196 QueueSetMemberHandle_t (C++ type), 1196
R
R0 (C macro), 1893 R1 (C macro), 1893 R2 (C macro), 1893 R3 (C macro), 1893 RADIO_MODE_NATIVE (C++ enumerator), 477 RADIO_MODE_SPI_RCP (C++ enumerator), 477 RADIO_MODE_UART_RCP (C++ enumerator), 477 RINGBUF_TYPE_ALLOWSPLIT (C++ enumerator),
1265 RINGBUF_TYPE_BYTEBUF (C++ enumerator), 1265 RINGBUF_TYPE_MAX (C++ enumerator), 1265 RINGBUF_TYPE_NOSPLIT (C++ enumerator), 1265 RingbufferType_t (C++ enum), 1265 RingbufHandle_t (C++ type), 1265 rmt_add_channel_to_group (C++ function),
663 RMT_BASECLK_APB (C++ enumerator), 668 RMT_BASECLK_MAX (C++ enumerator), 668 RMT_BASECLK_XTAL (C++ enumerator), 668 RMT_CARRIER_LEVEL_HIGH (C++ enumerator),
669 RMT_CARRIER_LEVEL_LOW (C++ enumerator), 669 RMT_CARRIER_LEVEL_MAX (C++ enumerator), 669 rmt_carrier_level_t (C++ enum), 669 RMT_CHANNEL_0 (C++ enumerator), 667 RMT_CHANNEL_1 (C++ enumerator), 667 RMT_CHANNEL_2 (C++ enumerator), 667 RMT_CHANNEL_3 (C++ enumerator), 667 RMT_CHANNEL_4 (C++ enumerator), 668

RMT_CHANNEL_5 (C++ enumerator), 668 RMT_CHANNEL_6 (C++ enumerator), 668 RMT_CHANNEL_7 (C++ enumerator), 668 RMT_CHANNEL_BUSY (C++ enumerator), 669 RMT_CHANNEL_FLAGS_AWARE_DFS (C macro),
666 RMT_CHANNEL_FLAGS_INVERT_SIG (C macro),
666 RMT_CHANNEL_IDLE (C++ enumerator), 669 RMT_CHANNEL_MAX (C++ enumerator), 668 rmt_channel_status_result_t (C++ class),
667 rmt_channel_status_result_t::status
(C++ member), 667 rmt_channel_status_t (C++ enum), 669 rmt_channel_t (C++ enum), 667 RMT_CHANNEL_UNINIT (C++ enumerator), 669 rmt_clr_intr_enable_mask (C++ function),
664 rmt_config (C++ function), 660 rmt_config_t (C++ class), 666 rmt_config_t::channel (C++ member), 666 rmt_config_t::clk_div (C++ member), 666 rmt_config_t::flags (C++ member), 666 rmt_config_t::gpio_num (C++ member), 666 rmt_config_t::mem_block_num (C++ mem-
ber), 666 rmt_config_t::rmt_mode (C++ member), 666 rmt_config_t::rx_config (C++ member), 666 rmt_config_t::tx_config (C++ member), 666 RMT_DATA_MODE_FIFO (C++ enumerator), 668 RMT_DATA_MODE_MAX (C++ enumerator), 668 RMT_DATA_MODE_MEM (C++ enumerator), 668 rmt_data_mode_t (C++ enum), 668 RMT_DEFAULT_CONFIG_RX (C macro), 666 RMT_DEFAULT_CONFIG_TX (C macro), 666 rmt_driver_install (C++ function), 661 rmt_driver_uninstall (C++ function), 661 rmt_enable_tx_loop_autostop (C++ func-
tion), 664 rmt_fill_tx_items (C++ function), 660 rmt_get_channel_status (C++ function), 661 rmt_get_clk_div (C++ function), 654 rmt_get_counter_clock (C++ function), 661 rmt_get_idle_level (C++ function), 659 rmt_get_mem_block_num (C++ function), 655 rmt_get_mem_pd (C++ function), 656 rmt_get_memory_owner (C++ function), 657 rmt_get_ringbuf_handle (C++ function), 662 rmt_get_rx_idle_thresh (C++ function), 655 rmt_get_source_clk (C++ function), 658 rmt_get_status (C++ function), 659 rmt_get_tx_loop_mode (C++ function), 658 RMT_IDLE_LEVEL_HIGH (C++ enumerator), 669 RMT_IDLE_LEVEL_LOW (C++ enumerator), 669 RMT_IDLE_LEVEL_MAX (C++ enumerator), 669 rmt_idle_level_t (C++ enum), 668 rmt_isr_deregister (C++ function), 660

Espressif Systems

2151

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

rmt_isr_handle_t (C++ type), 667 rmt_isr_register (C++ function), 660 rmt_item32_t (C++ class), 665 rmt_item32_t::duration0 (C++ member), 665 rmt_item32_t::duration1 (C++ member), 665 rmt_item32_t::level0 (C++ member), 665 rmt_item32_t::level1 (C++ member), 665 rmt_item32_t::val (C++ member), 665 RMT_MEM_ITEM_NUM (C macro), 666 RMT_MEM_OWNER_MAX (C++ enumerator), 668 RMT_MEM_OWNER_RX (C++ enumerator), 668 rmt_mem_owner_t (C++ enum), 668 RMT_MEM_OWNER_TX (C++ enumerator), 668 rmt_memory_rw_rst (C++ function), 664 RMT_MODE_MAX (C++ enumerator), 668 RMT_MODE_RX (C++ enumerator), 668 rmt_mode_t (C++ enum), 668 RMT_MODE_TX (C++ enumerator), 668 rmt_register_tx_end_callback (C++ func-
tion), 663 rmt_remove_channel_from_group (C++ func-
tion), 663 rmt_rx_config_t (C++ class), 665 rmt_rx_config_t::carrier_duty_percent
(C++ member), 666 rmt_rx_config_t::carrier_freq_hz (C++
member), 666 rmt_rx_config_t::carrier_level (C++
member), 666 rmt_rx_config_t::filter_en (C++ member),
665 rmt_rx_config_t::filter_ticks_thresh
(C++ member), 665 rmt_rx_config_t::idle_threshold (C++
member), 665 rmt_rx_config_t::rm_carrier (C++ mem-
ber), 665 rmt_rx_memory_reset (C++ function), 657 rmt_rx_start (C++ function), 657 rmt_rx_stop (C++ function), 657 rmt_set_clk_div (C++ function), 654 rmt_set_err_intr_en (C++ function), 659 rmt_set_gpio (C++ function), 660 rmt_set_idle_level (C++ function), 659 rmt_set_intr_enable_mask (C++ function),
664 rmt_set_mem_block_num (C++ function), 655 rmt_set_mem_pd (C++ function), 656 rmt_set_memory_owner (C++ function), 657 rmt_set_pin (C++ function), 664 rmt_set_rx_filter (C++ function), 658 rmt_set_rx_idle_thresh (C++ function), 654 rmt_set_rx_intr_en (C++ function), 659 rmt_set_rx_thr_intr_en (C++ function), 663 rmt_set_source_clk (C++ function), 658 rmt_set_tx_carrier (C++ function), 656 rmt_set_tx_intr_en (C++ function), 659 rmt_set_tx_loop_count (C++ function), 664

rmt_set_tx_loop_mode (C++ function), 657 rmt_set_tx_thr_intr_en (C++ function), 659 rmt_source_clk_t (C++ enum), 668 rmt_translator_get_context (C++ function),
662 rmt_translator_init (C++ function), 662 rmt_translator_set_context (C++ function),
662 rmt_tx_config_t (C++ class), 665 rmt_tx_config_t::carrier_duty_percent
(C++ member), 665 rmt_tx_config_t::carrier_en (C++ mem-
ber), 665 rmt_tx_config_t::carrier_freq_hz (C++
member), 665 rmt_tx_config_t::carrier_level (C++
member), 665 rmt_tx_config_t::idle_level (C++ mem-
ber), 665 rmt_tx_config_t::idle_output_en (C++
member), 665 rmt_tx_config_t::loop_count (C++ mem-
ber), 665 rmt_tx_config_t::loop_en (C++ member),
665 rmt_tx_end_callback_t (C++ class), 666 rmt_tx_end_callback_t::arg (C++ member),
666 rmt_tx_end_callback_t::function (C++
member), 666 rmt_tx_end_fn_t (C++ type), 667 rmt_tx_memory_reset (C++ function), 657 rmt_tx_start (C++ function), 656 rmt_tx_stop (C++ function), 656 rmt_wait_tx_done (C++ function), 662 rmt_write_items (C++ function), 661 rmt_write_sample (C++ function), 663 ROLE_FAST_PROV (C++ enumerator), 205 ROLE_NODE (C++ enumerator), 205 ROLE_PROVISIONER (C++ enumerator), 205 rtc_gpio_deinit (C++ function), 535 rtc_gpio_force_hold_all (C++ function), 537 rtc_gpio_force_hold_dis_all (C++ func-
tion), 538 rtc_gpio_get_drive_capability (C++ func-
tion), 537 rtc_gpio_get_level (C++ function), 535 rtc_gpio_hold_dis (C++ function), 537 rtc_gpio_hold_en (C++ function), 537 rtc_gpio_init (C++ function), 535 RTC_GPIO_IS_VALID_GPIO (C macro), 538 rtc_gpio_is_valid_gpio (C++ function), 535 rtc_gpio_isolate (C++ function), 537 RTC_GPIO_MODE_DISABLED (C++ enumerator),
538 RTC_GPIO_MODE_INPUT_ONLY (C++ enumerator),
538

Espressif Systems

2152

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

RTC_GPIO_MODE_INPUT_OUTPUT (C++ enumerator), 538
RTC_GPIO_MODE_INPUT_OUTPUT_OD (C++ enumerator), 538
RTC_GPIO_MODE_OUTPUT_OD (C++ enumerator), 538
RTC_GPIO_MODE_OUTPUT_ONLY (C++ enumerator), 538
rtc_gpio_mode_t (C++ enum), 538 rtc_gpio_pulldown_dis (C++ function), 536 rtc_gpio_pulldown_en (C++ function), 536 rtc_gpio_pullup_dis (C++ function), 536 rtc_gpio_pullup_en (C++ function), 536 rtc_gpio_set_direction (C++ function), 535 rtc_gpio_set_direction_in_sleep (C++
function), 536 rtc_gpio_set_drive_capability (C++ func-
tion), 537 rtc_gpio_set_level (C++ function), 535 rtc_gpio_wakeup_disable (C++ function), 538 rtc_gpio_wakeup_enable (C++ function), 538 rtc_io_number_get (C++ function), 535 RTC_SLOW_MEM (C macro), 1896
S
sample_to_rmt_t (C++ type), 667 SC_EVENT_FOUND_CHANNEL (C++ enumerator),
410 SC_EVENT_GOT_SSID_PSWD (C++ enumerator),
410 SC_EVENT_SCAN_DONE (C++ enumerator), 410 SC_EVENT_SEND_ACK_DONE (C++ enumerator),
410 SC_TYPE_AIRKISS (C++ enumerator), 410 SC_TYPE_ESPTOUCH (C++ enumerator), 410 SC_TYPE_ESPTOUCH_AIRKISS (C++ enumerator),
410 SC_TYPE_ESPTOUCH_V2 (C++ enumerator), 410 sdmmc_card_init (C++ function), 1027 sdmmc_card_print_info (C++ function), 1027 sdmmc_card_t (C++ class), 1033 sdmmc_card_t::cid (C++ member), 1033 sdmmc_card_t::csd (C++ member), 1033 sdmmc_card_t::ext_csd (C++ member), 1034 sdmmc_card_t::host (C++ member), 1033 sdmmc_card_t::is_ddr (C++ member), 1034 sdmmc_card_t::is_mem (C++ member), 1034 sdmmc_card_t::is_mmc (C++ member), 1034 sdmmc_card_t::is_sdio (C++ member), 1034 sdmmc_card_t::log_bus_width (C++ mem-
ber), 1034 sdmmc_card_t::max_freq_khz (C++ member),
1034 sdmmc_card_t::num_io_functions (C++
member), 1034 sdmmc_card_t::ocr (C++ member), 1033 sdmmc_card_t::raw_cid (C++ member), 1033 sdmmc_card_t::rca (C++ member), 1034

sdmmc_card_t::reserved (C++ member), 1034 sdmmc_card_t::scr (C++ member), 1033 sdmmc_cid_t (C++ class), 1031 sdmmc_cid_t::date (C++ member), 1031 sdmmc_cid_t::mfg_id (C++ member), 1031 sdmmc_cid_t::name (C++ member), 1031 sdmmc_cid_t::oem_id (C++ member), 1031 sdmmc_cid_t::revision (C++ member), 1031 sdmmc_cid_t::serial (C++ member), 1031 sdmmc_command_t (C++ class), 1032 sdmmc_command_t::arg (C++ member), 1032 sdmmc_command_t::blklen (C++ member),
1032 sdmmc_command_t::data (C++ member), 1032 sdmmc_command_t::datalen (C++ member),
1032 sdmmc_command_t::error (C++ member), 1032 sdmmc_command_t::flags (C++ member), 1032 sdmmc_command_t::opcode (C++ member),
1032 sdmmc_command_t::response (C++ member),
1032 sdmmc_command_t::timeout_ms (C++ mem-
ber), 1032 sdmmc_csd_t (C++ class), 1031 sdmmc_csd_t::capacity (C++ member), 1031 sdmmc_csd_t::card_command_class (C++
member), 1031 sdmmc_csd_t::csd_ver (C++ member), 1031 sdmmc_csd_t::mmc_ver (C++ member), 1031 sdmmc_csd_t::read_block_len (C++ mem-
ber), 1031 sdmmc_csd_t::sector_size (C++ member),
1031 sdmmc_csd_t::tr_speed (C++ member), 1031 sdmmc_ext_csd_t (C++ class), 1032 sdmmc_ext_csd_t::power_class (C++ mem-
ber), 1032 SDMMC_FREQ_26M (C macro), 1034 SDMMC_FREQ_52M (C macro), 1034 SDMMC_FREQ_DEFAULT (C macro), 1034 SDMMC_FREQ_HIGHSPEED (C macro), 1034 SDMMC_FREQ_PROBING (C macro), 1034 sdmmc_get_status (C++ function), 1027 SDMMC_HOST_DEFAULT (C macro), 675 sdmmc_host_deinit (C++ function), 674 sdmmc_host_do_transaction (C++ function),
673 SDMMC_HOST_FLAG_1BIT (C macro), 1034 SDMMC_HOST_FLAG_4BIT (C macro), 1034 SDMMC_HOST_FLAG_8BIT (C macro), 1034 SDMMC_HOST_FLAG_DDR (C macro), 1034 SDMMC_HOST_FLAG_DEINIT_ARG (C macro), 1034 SDMMC_HOST_FLAG_SPI (C macro), 1034 sdmmc_host_get_slot_width (C++ function),
673 sdmmc_host_init (C++ function), 672 sdmmc_host_init_slot (C++ function), 672

Espressif Systems

2153

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

sdmmc_host_io_int_enable (C++ function), 673
sdmmc_host_io_int_wait (C++ function), 674 sdmmc_host_pullup_en (C++ function), 674 sdmmc_host_set_bus_ddr_mode (C++ func-
tion), 673 sdmmc_host_set_bus_width (C++ function),
672 sdmmc_host_set_card_clk (C++ function), 673 SDMMC_HOST_SLOT_0 (C macro), 675 SDMMC_HOST_SLOT_1 (C macro), 675 sdmmc_host_t (C++ class), 1032 sdmmc_host_t::command_timeout_ms (C++
member), 1033 sdmmc_host_t::deinit (C++ member), 1033 sdmmc_host_t::deinit_p (C++ member), 1033 sdmmc_host_t::do_transaction (C++ mem-
ber), 1033 sdmmc_host_t::flags (C++ member), 1033 sdmmc_host_t::get_bus_width (C++ mem-
ber), 1033 sdmmc_host_t::init (C++ member), 1033 sdmmc_host_t::io_int_enable (C++ mem-
ber), 1033 sdmmc_host_t::io_int_wait (C++ member),
1033 sdmmc_host_t::io_voltage (C++ member),
1033 sdmmc_host_t::max_freq_khz (C++ member),
1033 sdmmc_host_t::set_bus_ddr_mode (C++
member), 1033 sdmmc_host_t::set_bus_width (C++ mem-
ber), 1033 sdmmc_host_t::set_card_clk (C++ member),
1033 sdmmc_host_t::slot (C++ member), 1033 sdmmc_io_enable_int (C++ function), 1030 sdmmc_io_get_cis_data (C++ function), 1030 sdmmc_io_print_cis_info (C++ function),
1030 sdmmc_io_read_blocks (C++ function), 1029 sdmmc_io_read_byte (C++ function), 1028 sdmmc_io_read_bytes (C++ function), 1028 sdmmc_io_wait_int (C++ function), 1030 sdmmc_io_write_blocks (C++ function), 1029 sdmmc_io_write_byte (C++ function), 1028 sdmmc_io_write_bytes (C++ function), 1029 sdmmc_read_sectors (C++ function), 1028 sdmmc_response_t (C++ type), 1035 sdmmc_scr_t (C++ class), 1031 sdmmc_scr_t::bus_width (C++ member), 1032 sdmmc_scr_t::sd_spec (C++ member), 1032 SDMMC_SLOT_CONFIG_DEFAULT (C macro), 675 sdmmc_slot_config_t (C++ class), 674 sdmmc_slot_config_t::cd (C++ member), 675 sdmmc_slot_config_t::clk (C++ member),
674

sdmmc_slot_config_t::cmd (C++ member),

674

sdmmc_slot_config_t::d0 (C++ member), 674

sdmmc_slot_config_t::d1 (C++ member), 674

sdmmc_slot_config_t::d2 (C++ member), 674

sdmmc_slot_config_t::d3 (C++ member), 674

sdmmc_slot_config_t::d4 (C++ member), 674

sdmmc_slot_config_t::d5 (C++ member), 674

sdmmc_slot_config_t::d6 (C++ member), 675

sdmmc_slot_config_t::d7 (C++ member), 675

sdmmc_slot_config_t::flags (C++ member),

675

sdmmc_slot_config_t::gpio_cd (C++ mem-

ber), 675

sdmmc_slot_config_t::gpio_wp (C++ mem-

ber), 675

sdmmc_slot_config_t::width (C++ member),

675

sdmmc_slot_config_t::wp (C++ member), 675

SDMMC_SLOT_FLAG_INTERNAL_PULLUP

(C

macro), 675

SDMMC_SLOT_NO_CD (C macro), 675

SDMMC_SLOT_NO_WP (C macro), 675

SDMMC_SLOT_WIDTH_DEFAULT (C macro), 675

sdmmc_switch_func_rsp_t (C++ class), 1032

sdmmc_switch_func_rsp_t::data (C++

member), 1032

sdmmc_write_sectors (C++ function), 1028

SDSPI_DEFAULT_HOST (C macro), 680

sdspi_dev_handle_t (C++ type), 680

SDSPI_DEVICE_CONFIG_DEFAULT (C macro),

680

sdspi_device_config_t (C++ class), 679

sdspi_device_config_t::gpio_cd (C++

member), 679

sdspi_device_config_t::gpio_cs (C++

member), 679

sdspi_device_config_t::gpio_int (C++

member), 679

sdspi_device_config_t::gpio_wp (C++

member), 679

sdspi_device_config_t::host_id (C++

member), 679

SDSPI_HOST_DEFAULT (C macro), 680

sdspi_host_deinit (C++ function), 678

sdspi_host_do_transaction (C++ function),

678

sdspi_host_init (C++ function), 678

sdspi_host_init_device (C++ function), 678

sdspi_host_init_slot (C++ function), 679

sdspi_host_io_int_enable (C++ function),

679

sdspi_host_io_int_wait (C++ function), 679

sdspi_host_remove_device (C++ function),

678

sdspi_host_set_card_clk (C++ function), 678

SDSPI_SLOT_CONFIG_DEFAULT (C macro), 680

sdspi_slot_config_t (C++ class), 679

Espressif Systems

2154

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

sdspi_slot_config_t::dma_channel (C++ sigmadelta_set_pin (C++ function), 682

member), 680

sigmadelta_set_prescale (C++ function), 682

sdspi_slot_config_t::gpio_cd (C++ mem- slave_transaction_cb_t (C++ type), 707

ber), 680

smartconfig_event_got_ssid_pswd_t

sdspi_slot_config_t::gpio_cs (C++ mem-

(C++ class), 409

ber), 680

smartconfig_event_got_ssid_pswd_t::bssid

sdspi_slot_config_t::gpio_int (C++

(C++ member), 409

member), 680

smartconfig_event_got_ssid_pswd_t::bssid_set

sdspi_slot_config_t::gpio_miso (C++

(C++ member), 409

member), 680

smartconfig_event_got_ssid_pswd_t::cellphone_ip

sdspi_slot_config_t::gpio_mosi (C++

(C++ member), 409

member), 680

smartconfig_event_got_ssid_pswd_t::password

sdspi_slot_config_t::gpio_sck (C++

(C++ member), 409

member), 680

smartconfig_event_got_ssid_pswd_t::ssid

sdspi_slot_config_t::gpio_wp (C++ mem-

(C++ member), 409

ber), 680

smartconfig_event_got_ssid_pswd_t::token

SDSPI_SLOT_NO_CD (C macro), 680

(C++ member), 409

SDSPI_SLOT_NO_INT (C macro), 680

smartconfig_event_got_ssid_pswd_t::type

SDSPI_SLOT_NO_WP (C macro), 680

(C++ member), 409

SECURE_BOOT_PUBLIC_KEY_INDEX_0 (C++ smartconfig_event_t (C++ enum), 410

enumerator), 1328

SMARTCONFIG_START_CONFIG_DEFAULT (C

SECURE_BOOT_PUBLIC_KEY_INDEX_1 (C++

macro), 410

enumerator), 1328

smartconfig_start_config_t (C++ class),

SECURE_BOOT_PUBLIC_KEY_INDEX_2 (C++

410

enumerator), 1328

smartconfig_start_config_t::enable_log

SemaphoreHandle_t (C++ type), 1209

(C++ member), 410

semBINARY_SEMAPHORE_QUEUE_LENGTH (C smartconfig_start_config_t::esp_touch_v2_enable_c

macro), 1196

(C++ member), 410

semGIVE_BLOCK_TIME (C macro), 1196

smartconfig_start_config_t::esp_touch_v2_key

semSEMAPHORE_QUEUE_ITEM_LENGTH

(C

(C++ member), 410

macro), 1196

smartconfig_type_t (C++ enum), 410

shared_stack_function (C++ type), 1300

sntp_get_sync_interval (C++ function), 1356

shutdown_handler_t (C++ type), 1315

sntp_get_sync_mode (C++ function), 1356

SIGMADELTA_CHANNEL_0 (C++ enumerator), 683 sntp_get_sync_status (C++ function), 1356

SIGMADELTA_CHANNEL_1 (C++ enumerator), 683 sntp_restart (C++ function), 1356

SIGMADELTA_CHANNEL_2 (C++ enumerator), 683 sntp_set_sync_interval (C++ function), 1356

SIGMADELTA_CHANNEL_3 (C++ enumerator), 683 sntp_set_sync_mode (C++ function), 1356

SIGMADELTA_CHANNEL_4 (C++ enumerator), 683 sntp_set_sync_status (C++ function), 1356

SIGMADELTA_CHANNEL_5 (C++ enumerator), 683 sntp_set_time_sync_notification_cb

SIGMADELTA_CHANNEL_6 (C++ enumerator), 683

(C++ function), 1356

SIGMADELTA_CHANNEL_7 (C++ enumerator), 683 SNTP_SYNC_MODE_IMMED (C++ enumerator), 1357

SIGMADELTA_CHANNEL_MAX (C++ enumerator), SNTP_SYNC_MODE_SMOOTH (C++ enumerator),

683

1357

sigmadelta_channel_t (C++ enum), 683

sntp_sync_mode_t (C++ enum), 1357

sigmadelta_config (C++ function), 682

SNTP_SYNC_STATUS_COMPLETED (C++ enumera-

sigmadelta_config_t (C++ class), 682

tor), 1357

sigmadelta_config_t::channel (C++ mem- SNTP_SYNC_STATUS_IN_PROGRESS (C++ enu-

ber), 683

merator), 1357

sigmadelta_config_t::sigmadelta_duty SNTP_SYNC_STATUS_RESET (C++ enumerator),

(C++ member), 683

1357

sigmadelta_config_t::sigmadelta_gpio sntp_sync_status_t (C++ enum), 1357

(C++ member), 683

sntp_sync_time (C++ function), 1355

sigmadelta_config_t::sigmadelta_prescalsentp_sync_time_cb_t (C++ type), 1356

(C++ member), 683

SPI1_HOST (C++ enumerator), 690

SIGMADELTA_PORT_0 (C++ enumerator), 683

SPI2_HOST (C++ enumerator), 690

SIGMADELTA_PORT_MAX (C++ enumerator), 683 SPI3_HOST (C++ enumerator), 691

sigmadelta_port_t (C++ enum), 683

spi_bus_add_device (C++ function), 694

sigmadelta_set_duty (C++ function), 682

spi_bus_add_flash_device (C++ function),

Espressif Systems

2155

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

1042

spi_device_interface_config_t::command_bits

spi_bus_config_t (C++ class), 692

(C++ member), 698

spi_bus_config_t::data0_io_num (C++ spi_device_interface_config_t::cs_ena_posttrans

member), 692

(C++ member), 698

spi_bus_config_t::data1_io_num (C++ spi_device_interface_config_t::cs_ena_pretrans

member), 692

(C++ member), 698

spi_bus_config_t::data2_io_num (C++ spi_device_interface_config_t::dummy_bits

member), 692

(C++ member), 698

spi_bus_config_t::data3_io_num (C++ spi_device_interface_config_t::duty_cycle_pos

member), 692

(C++ member), 698

spi_bus_config_t::data4_io_num (C++ spi_device_interface_config_t::flags

member), 692

(C++ member), 698

spi_bus_config_t::data5_io_num (C++ spi_device_interface_config_t::input_delay_ns

member), 693

(C++ member), 698

spi_bus_config_t::data6_io_num (C++ spi_device_interface_config_t::mode

member), 693

(C++ member), 698

spi_bus_config_t::data7_io_num (C++ spi_device_interface_config_t::post_cb

member), 693

(C++ member), 698

spi_bus_config_t::flags (C++ member), 693 spi_device_interface_config_t::pre_cb

spi_bus_config_t::intr_flags (C++ mem-

(C++ member), 698

ber), 693

spi_device_interface_config_t::queue_size

spi_bus_config_t::max_transfer_sz

(C++ member), 698

(C++ member), 693

spi_device_interface_config_t::spics_io_num

spi_bus_config_t::miso_io_num (C++

(C++ member), 698

member), 692

SPI_DEVICE_NO_DUMMY (C macro), 700

spi_bus_config_t::mosi_io_num (C++ spi_device_polling_end (C++ function), 696

member), 692

spi_device_polling_start (C++ function),

spi_bus_config_t::quadhd_io_num (C++

696

member), 692

spi_device_polling_transmit (C++ func-

spi_bus_config_t::quadwp_io_num (C++

tion), 696

member), 692

SPI_DEVICE_POSITIVE_CS (C macro), 700

spi_bus_config_t::sclk_io_num (C++ spi_device_queue_trans (C++ function), 695

member), 692

spi_device_release_bus (C++ function), 697

spi_bus_free (C++ function), 692

SPI_DEVICE_RXBIT_LSBFIRST (C macro), 700

spi_bus_initialize (C++ function), 691

spi_device_transmit (C++ function), 695

spi_bus_remove_device (C++ function), 695 SPI_DEVICE_TXBIT_LSBFIRST (C macro), 700

spi_bus_remove_flash_device (C++ func- SPI_DMA_CH_AUTO (C++ enumerator), 694

tion), 1042

spi_dma_chan_t (C++ type), 694

spi_cal_clock (C++ function), 697

SPI_DMA_DISABLED (C++ enumerator), 694

SPI_CLK_APB (C++ enumerator), 691

SPI_EV_BUF_RX (C++ enumerator), 691

SPI_CLK_XTAL (C++ enumerator), 691

SPI_EV_BUF_TX (C++ enumerator), 691

spi_clock_source_t (C++ enum), 691

SPI_EV_CMD9 (C++ enumerator), 691

spi_common_dma_t (C++ enum), 694

SPI_EV_CMDA (C++ enumerator), 691

SPI_DEVICE_3WIRE (C macro), 700

SPI_EV_RECV (C++ enumerator), 691

spi_device_acquire_bus (C++ function), 696 SPI_EV_RECV_DMA_READY (C++ enumerator), 691

SPI_DEVICE_BIT_LSBFIRST (C macro), 700

SPI_EV_SEND (C++ enumerator), 691

SPI_DEVICE_CLK_AS_CS (C macro), 700

SPI_EV_SEND_DMA_READY (C++ enumerator), 691

SPI_DEVICE_DDRCLK (C macro), 700

SPI_EV_TRANS (C++ enumerator), 691

spi_device_get_trans_result (C++ func- spi_event_t (C++ enum), 691

tion), 695

spi_flash_chip_t (C++ type), 1048

SPI_DEVICE_HALFDUPLEX (C macro), 700

SPI_FLASH_CONFIG_CONF_BITS (C macro), 1051

spi_device_handle_t (C++ type), 701

SPI_FLASH_DIO (C++ enumerator), 1052

spi_device_interface_config_t (C++ SPI_FLASH_DOUT (C++ enumerator), 1052

class), 697

spi_flash_encryption_t (C++ class), 1049

spi_device_interface_config_t::address_sbpiit_sflash_encryption_t::flash_encryption_check

(C++ member), 698

(C++ member), 1049

spi_device_interface_config_t::clock_spsepeid__fhlzash_encryption_t::flash_encryption_data_pre

(C++ member), 698

(C++ member), 1049

Espressif Systems

2156

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

spi_flash_encryption_t::flash_encryptioSnP_Id_eFsLtArSoHy_OPI_DTR (C++ enumerator), 1052

(C++ member), 1049

SPI_FLASH_OPI_FLAG (C macro), 1051

spi_flash_encryption_t::flash_encryptioSnP_Id_iFsLaAbSlHe_OPI_STR (C++ enumerator), 1052

(C++ member), 1049

SPI_FLASH_QIO (C++ enumerator), 1052

spi_flash_encryption_t::flash_encryptioSnP_Id_oFnLeASH_QOUT (C++ enumerator), 1052

(C++ member), 1049

SPI_FLASH_READ_MODE_MAX (C++ enumerator),

spi_flash_encryption_t::flash_encryption_enabl1e052

(C++ member), 1049

SPI_FLASH_READ_MODE_MIN (C macro), 1051

SPI_FLASH_FASTRD (C++ enumerator), 1052

SPI_FLASH_SLOWRD (C++ enumerator), 1052

spi_flash_host_driver_s (C++ class), 1049 spi_flash_sus_cmd_conf (C++ class), 1048

spi_flash_host_driver_s::check_suspend spi_flash_sus_cmd_conf::cmd_rdsr (C++

(C++ member), 1051

member), 1048

spi_flash_host_driver_s::common_commandspi_flash_sus_cmd_conf::res_cmd (C++

(C++ member), 1049

member), 1049

spi_flash_host_driver_s::configure_hosts_piio__fmloadseh_sus_cmd_conf::reserved (C++

(C++ member), 1050

member), 1049

spi_flash_host_driver_s::dev_config spi_flash_sus_cmd_conf::sus_cmd (C++

(C++ member), 1049

member), 1049

spi_flash_host_driver_s::erase_block spi_flash_sus_cmd_conf::sus_mask (C++

(C++ member), 1050

member), 1048

spi_flash_host_driver_s::erase_chip SPI_FLASH_TRANS_FLAG_BYTE_SWAP

(C

(C++ member), 1050

macro), 1051

spi_flash_host_driver_s::erase_sector SPI_FLASH_TRANS_FLAG_CMD16 (C macro), 1051

(C++ member), 1050

SPI_FLASH_TRANS_FLAG_IGNORE_BASEIO (C

spi_flash_host_driver_s::flush_cache

macro), 1051

(C++ member), 1051

spi_flash_trans_t (C++ class), 1048

spi_flash_host_driver_s::host_status spi_flash_trans_t::address (C++ member),

(C++ member), 1050

1048

spi_flash_host_driver_s::poll_cmd_done spi_flash_trans_t::address_bitlen

(C++ member), 1050

(C++ member), 1048

spi_flash_host_driver_s::program_page spi_flash_trans_t::command (C++ member),

(C++ member), 1050

1048

spi_flash_host_driver_s::read (C++ spi_flash_trans_t::dummy_bitlen (C++

member), 1050

member), 1048

spi_flash_host_driver_s::read_data_slicsepri_flash_trans_t::flags (C++ member),

(C++ member), 1050

1048

spi_flash_host_driver_s::read_id (C++ spi_flash_trans_t::io_mode (C++ member),

member), 1050

1048

spi_flash_host_driver_s::read_status spi_flash_trans_t::miso_data (C++ mem-

(C++ member), 1050

ber), 1048

spi_flash_host_driver_s::resume (C++ spi_flash_trans_t::miso_len (C++ mem-

member), 1051

ber), 1048

spi_flash_host_driver_s::set_write_protsepcit_flash_trans_t::mosi_data (C++ mem-

(C++ member), 1050

ber), 1048

spi_flash_host_driver_s::supports_direcstp_ir_efaldash_trans_t::mosi_len (C++ mem-

(C++ member), 1050

ber), 1048

spi_flash_host_driver_s::supports_direcstp_iw_rfiltaesh_trans_t::reserved (C++ mem-

(C++ member), 1050

ber), 1048

spi_flash_host_driver_s::sus_setup

SPI_FLASH_YIELD_REQ_SUSPEND (C macro),

(C++ member), 1051

1048

spi_flash_host_driver_s::suspend (C++ SPI_FLASH_YIELD_REQ_YIELD (C macro), 1048

member), 1051

SPI_FLASH_YIELD_STA_RESUME (C macro), 1048

spi_flash_host_driver_s::write_data_sliscpeir_get_actual_clock (C++ function), 697

(C++ member), 1050

spi_get_freq_limit (C++ function), 697

spi_flash_host_driver_t (C++ type), 1051 spi_get_timing (C++ function), 697

spi_flash_host_inst_t (C++ class), 1049

spi_host_device_t (C++ enum), 690

spi_flash_host_inst_t::driver (C++ SPI_HOST_MAX (C++ enumerator), 691

member), 1049

spi_line_mode_t (C++ class), 690

Espressif Systems

2157

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

spi_line_mode_t::addr_lines (C++ mem- SPI_TRANS_MODE_QIO (C macro), 701

ber), 690

SPI_TRANS_MULTILINE_ADDR (C macro), 701

spi_line_mode_t::cmd_lines (C++ member), SPI_TRANS_MULTILINE_CMD (C macro), 701

690

SPI_TRANS_USE_RXDATA (C macro), 701

spi_line_mode_t::data_lines (C++ mem- SPI_TRANS_USE_TXDATA (C macro), 701

ber), 690

SPI_TRANS_VARIABLE_ADDR (C macro), 701

SPI_MASTER_FREQ_10M (C macro), 700

SPI_TRANS_VARIABLE_CMD (C macro), 701

SPI_MASTER_FREQ_11M (C macro), 700

SPI_TRANS_VARIABLE_DUMMY (C macro), 701

SPI_MASTER_FREQ_13M (C macro), 700

spi_transaction_ext_t (C++ class), 699

SPI_MASTER_FREQ_16M (C macro), 700

spi_transaction_ext_t::address_bits

SPI_MASTER_FREQ_20M (C macro), 700

(C++ member), 699

SPI_MASTER_FREQ_26M (C macro), 700

spi_transaction_ext_t::base (C++ mem-

SPI_MASTER_FREQ_40M (C macro), 700

ber), 699

SPI_MASTER_FREQ_80M (C macro), 700

spi_transaction_ext_t::command_bits

SPI_MASTER_FREQ_8M (C macro), 700

(C++ member), 699

SPI_MASTER_FREQ_9M (C macro), 700

spi_transaction_ext_t::dummy_bits

SPI_MAX_DMA_LEN (C macro), 693

(C++ member), 699

SPI_SLAVE_BIT_LSBFIRST (C macro), 707

spi_transaction_t (C++ class), 699

spi_slave_free (C++ function), 705

spi_transaction_t (C++ type), 701

spi_slave_get_trans_result (C++ function), spi_transaction_t::addr (C++ member), 699

705

spi_transaction_t::cmd (C++ member), 699

spi_slave_initialize (C++ function), 704

spi_transaction_t::flags (C++ member),

spi_slave_interface_config_t (C++ class),

699

706

spi_transaction_t::length (C++ member),

spi_slave_interface_config_t::flags

699

(C++ member), 706

spi_transaction_t::rx_buffer (C++ mem-

spi_slave_interface_config_t::mode

ber), 699

(C++ member), 706

spi_transaction_t::rx_data (C++ member),

spi_slave_interface_config_t::post_setup_cb 699

(C++ member), 706

spi_transaction_t::rxlength (C++ mem-

spi_slave_interface_config_t::post_trans_cb ber), 699

(C++ member), 706

spi_transaction_t::tx_buffer (C++ mem-

spi_slave_interface_config_t::queue_size

ber), 699

(C++ member), 706

spi_transaction_t::tx_data (C++ member),

spi_slave_interface_config_t::spics_io_num 699

(C++ member), 706

spi_transaction_t::user (C++ member), 699

spi_slave_queue_trans (C++ function), 705 SPICOMMON_BUSFLAG_DUAL (C macro), 694

SPI_SLAVE_RXBIT_LSBFIRST (C macro), 707

SPICOMMON_BUSFLAG_GPIO_PINS (C macro),

spi_slave_transaction_t (C++ class), 706

693

spi_slave_transaction_t (C++ type), 707

SPICOMMON_BUSFLAG_IO4_IO7 (C macro), 694

spi_slave_transaction_t::length (C++ SPICOMMON_BUSFLAG_IOMUX_PINS (C macro),

member), 706

693

spi_slave_transaction_t::rx_buffer

SPICOMMON_BUSFLAG_MASTER (C macro), 693

(C++ member), 706

SPICOMMON_BUSFLAG_MISO (C macro), 694

spi_slave_transaction_t::trans_len

SPICOMMON_BUSFLAG_MOSI (C macro), 694

(C++ member), 706

SPICOMMON_BUSFLAG_NATIVE_PINS (C macro),

spi_slave_transaction_t::tx_buffer

694

(C++ member), 706

SPICOMMON_BUSFLAG_OCTAL (C macro), 694

spi_slave_transaction_t::user (C++ SPICOMMON_BUSFLAG_QUAD (C macro), 694

member), 706

SPICOMMON_BUSFLAG_SCLK (C macro), 693

spi_slave_transmit (C++ function), 705

SPICOMMON_BUSFLAG_SLAVE (C macro), 693

SPI_SLAVE_TXBIT_LSBFIRST (C macro), 707

SPICOMMON_BUSFLAG_WPHD (C macro), 694

SPI_SWAP_DATA_RX (C macro), 693

StaticRingbuffer_t (C++ type), 1265

SPI_SWAP_DATA_TX (C macro), 693

StreamBufferHandle_t (C++ type), 1242

SPI_TRANS_CS_KEEP_ACTIVE (C macro), 701

SYSTEM_EVENT_ACTION_TX_STATUS (C++ enu-

SPI_TRANS_MODE_DIO (C macro), 701

merator), 1145

SPI_TRANS_MODE_DIOQIO_ADDR (C macro), 701 system_event_ap_probe_req_rx_t (C++

SPI_TRANS_MODE_OCT (C macro), 701

type), 1144

Espressif Systems

2158

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

SYSTEM_EVENT_AP_PROBEREQRECVED (C++ system_event_info_t::sta_connected

enumerator), 1145

(C++ member), 1143

SYSTEM_EVENT_AP_STA_GOT_IP6 (C macro), system_event_info_t::sta_disconnected

1143

(C++ member), 1143

SYSTEM_EVENT_AP_STACONNECTED (C++ enu- system_event_info_t::sta_er_fail_reason

merator), 1145

(C++ member), 1143

system_event_ap_staconnected_t (C++ system_event_info_t::sta_er_pin (C++

type), 1144

member), 1143

SYSTEM_EVENT_AP_STADISCONNECTED (C++ system_event_info_t::sta_er_success

enumerator), 1145

(C++ member), 1143

system_event_ap_stadisconnected_t

SYSTEM_EVENT_MAX (C++ enumerator), 1146

(C++ type), 1144

SYSTEM_EVENT_ROC_DONE (C++ enumerator),

SYSTEM_EVENT_AP_STAIPASSIGNED (C++ enu-

1145

merator), 1145

SYSTEM_EVENT_SCAN_DONE (C++ enumerator),

system_event_ap_staipassigned_t (C++

1144

type), 1144

SYSTEM_EVENT_STA_AUTHMODE_CHANGE (C++

SYSTEM_EVENT_AP_START (C++ enumerator),

enumerator), 1145

1145

system_event_sta_authmode_change_t

SYSTEM_EVENT_AP_STOP (C++ enumerator), 1145

(C++ type), 1143

system_event_cb_t (C++ type), 1144

SYSTEM_EVENT_STA_BEACON_TIMEOUT (C++

SYSTEM_EVENT_ETH_CONNECTED (C++ enumera-

enumerator), 1145

tor), 1145

SYSTEM_EVENT_STA_BSS_RSSI_LOW (C++ enu-

SYSTEM_EVENT_ETH_DISCONNECTED (C++ enu-

merator), 1145

merator), 1146

SYSTEM_EVENT_STA_CONNECTED (C++ enumera-

SYSTEM_EVENT_ETH_GOT_IP (C++ enumerator),

tor), 1144

1146

system_event_sta_connected_t (C++ type),

SYSTEM_EVENT_ETH_LOST_IP (C++ enumerator),

1143

1146

SYSTEM_EVENT_STA_DISCONNECTED (C++ enu-

SYSTEM_EVENT_ETH_START (C++ enumerator),

merator), 1144

1145

system_event_sta_disconnected_t (C++

SYSTEM_EVENT_ETH_STOP (C++ enumerator),

type), 1143

1145

SYSTEM_EVENT_STA_GOT_IP (C++ enumerator),

SYSTEM_EVENT_FTM_REPORT (C++ enumerator),

1145

1145

system_event_sta_got_ip_t (C++ type), 1144

system_event_ftm_report_t (C++ type), 1144 SYSTEM_EVENT_STA_LOST_IP (C++ enumerator),

SYSTEM_EVENT_GOT_IP6 (C++ enumerator), 1145

1145

system_event_got_ip6_t (C++ type), 1144

system_event_sta_scan_done_t (C++ type),

system_event_handler_t (C++ type), 1144

1143

system_event_id_t (C++ enum), 1144

SYSTEM_EVENT_STA_START (C++ enumerator),

system_event_info_t (C++ union), 1142

1144

system_event_info_t::ap_probereqrecved SYSTEM_EVENT_STA_STOP (C++ enumerator),

(C++ member), 1143

1144

system_event_info_t::ap_staipassigned SYSTEM_EVENT_STA_WPS_ER_FAILED (C++

(C++ member), 1143

enumerator), 1145

system_event_info_t::auth_change (C++ SYSTEM_EVENT_STA_WPS_ER_PBC_OVERLAP

member), 1143

(C++ enumerator), 1145

system_event_info_t::connected (C++ SYSTEM_EVENT_STA_WPS_ER_PIN (C++ enumer-

member), 1142

ator), 1145

system_event_info_t::disconnected

system_event_sta_wps_er_pin_t (C++

(C++ member), 1142

type), 1144

system_event_info_t::ftm_report (C++ SYSTEM_EVENT_STA_WPS_ER_SUCCESS (C++

member), 1143

enumerator), 1145

system_event_info_t::got_ip (C++ mem- system_event_sta_wps_er_success_t

ber), 1143

(C++ type), 1144

system_event_info_t::got_ip6 (C++ mem- SYSTEM_EVENT_STA_WPS_ER_TIMEOUT (C++

ber), 1143

enumerator), 1145

system_event_info_t::scan_done (C++ system_event_sta_wps_fail_reason_t

member), 1142

(C++ type), 1143

Espressif Systems

2159

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

system_event_t (C++ class), 1143

tinyusb_config_t::descriptor (C++ mem-

system_event_t::event_id (C++ member),

ber), 769

1143

tinyusb_config_t::external_phy (C++

system_event_t::event_info (C++ member),

member), 769

1143

tinyusb_config_t::string_descriptor

SYSTEM_EVENT_WIFI_READY (C++ enumerator),

(C++ member), 769

1144

tinyusb_driver_install (C++ function), 768

T

TINYUSB_USBDEV_0 (C++ enumerator), 769 tinyusb_usbdev_t (C++ enum), 769

taskDISABLE_INTERRUPTS (C macro), 1176

tls_keep_alive_cfg (C++ class), 820

taskENABLE_INTERRUPTS (C macro), 1176

tls_keep_alive_cfg::keep_alive_count

taskENTER_CRITICAL (C macro), 1175

(C++ member), 820

taskENTER_CRITICAL_FROM_ISR (C macro), tls_keep_alive_cfg::keep_alive_enable

1175

(C++ member), 820

taskENTER_CRITICAL_ISR (C macro), 1175

tls_keep_alive_cfg::keep_alive_idle

taskEXIT_CRITICAL (C macro), 1175

(C++ member), 820

taskEXIT_CRITICAL_FROM_ISR (C macro), 1175 tls_keep_alive_cfg::keep_alive_interval

taskEXIT_CRITICAL_ISR (C macro), 1176

(C++ member), 820

TaskHandle_t (C++ type), 1177

tls_keep_alive_cfg_t (C++ type), 823

TaskHookFunction_t (C++ type), 1177

TlsDeleteCallbackFunction_t (C++ type),

taskSCHEDULER_NOT_STARTED (C macro), 1176

1177

taskSCHEDULER_RUNNING (C macro), 1176

tmrCOMMAND_CHANGE_PERIOD (C macro), 1217

taskSCHEDULER_SUSPENDED (C macro), 1176

tmrCOMMAND_CHANGE_PERIOD_FROM_ISR (C

taskYIELD (C macro), 1175

macro), 1217

TimerCallbackFunction_t (C++ type), 1226 tmrCOMMAND_DELETE (C macro), 1217

TimerHandle_t (C++ type), 1226

tmrCOMMAND_EXECUTE_CALLBACK (C macro),

TINYUSB_CDC_ACM_0 (C++ enumerator), 772

1217

TINYUSB_CDC_ACM_1 (C++ enumerator), 772

tmrCOMMAND_EXECUTE_CALLBACK_FROM_ISR

TINYUSB_CDC_ACM_MAX (C++ enumerator), 772

(C macro), 1217

tinyusb_cdcacm_itf_t (C++ enum), 772

tmrCOMMAND_RESET (C macro), 1217

tinyusb_cdcacm_read (C++ function), 770

tmrCOMMAND_RESET_FROM_ISR (C macro), 1217

tinyusb_cdcacm_register_callback (C++ tmrCOMMAND_START (C macro), 1217

function), 769

tmrCOMMAND_START_DONT_TRACE (C macro),

tinyusb_cdcacm_unregister_callback

1217

(C++ function), 769

tmrCOMMAND_START_FROM_ISR (C macro), 1217

tinyusb_cdcacm_write_flush (C++ function), tmrCOMMAND_STOP (C macro), 1217

770

tmrCOMMAND_STOP_FROM_ISR (C macro), 1217

tinyusb_cdcacm_write_queue (C++ function), tmrFIRST_FROM_ISR_COMMAND (C macro), 1217

770

touch_cnt_slope_t (C++ enum), 725

tinyusb_cdcacm_write_queue_char (C++ TOUCH_DEBOUNCE_CNT_MAX (C macro), 723

function), 770

touch_filter_config (C++ class), 722

tinyusb_config_cdcacm_t (C++ class), 771 touch_filter_config::debounce_cnt

tinyusb_config_cdcacm_t::callback_line_coding_(Cc+h+anmgeemdber), 722

(C++ member), 772

touch_filter_config::jitter_step (C++

tinyusb_config_cdcacm_t::callback_line_state_cmheamnbgere)d, 722

(C++ member), 771

touch_filter_config::mode (C++ member),

tinyusb_config_cdcacm_t::callback_rx

722

(C++ member), 771

touch_filter_config::noise_thr (C++

tinyusb_config_cdcacm_t::callback_rx_wanted_chmaermber), 722

(C++ member), 771

touch_filter_config::smh_lvl (C++ mem-

tinyusb_config_cdcacm_t::cdc_port

ber), 722

(C++ member), 771

touch_filter_config_t (C++ type), 723

tinyusb_config_cdcacm_t::rx_unread_buf_tsozuch_filter_mode_t (C++ enum), 727

(C++ member), 771

TOUCH_FSM_MODE_MAX (C++ enumerator), 725

tinyusb_config_cdcacm_t::usb_dev (C++ TOUCH_FSM_MODE_SW (C++ enumerator), 725

member), 771

touch_fsm_mode_t (C++ enum), 725

tinyusb_config_t (C++ class), 769

TOUCH_FSM_MODE_TIMER (C++ enumerator), 725

touch_high_volt_t (C++ enum), 724

Espressif Systems

2160

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

TOUCH_HVOLT_2V4 (C++ enumerator), 724 TOUCH_HVOLT_2V5 (C++ enumerator), 724 TOUCH_HVOLT_2V6 (C++ enumerator), 724 TOUCH_HVOLT_2V7 (C++ enumerator), 724 TOUCH_HVOLT_ATTEN_0V (C++ enumerator), 725 TOUCH_HVOLT_ATTEN_0V5 (C++ enumerator), 725 TOUCH_HVOLT_ATTEN_1V (C++ enumerator), 725 TOUCH_HVOLT_ATTEN_1V5 (C++ enumerator), 724 TOUCH_HVOLT_ATTEN_KEEP (C++ enumerator),
724 TOUCH_HVOLT_ATTEN_MAX (C++ enumerator), 725 TOUCH_HVOLT_KEEP (C++ enumerator), 724 TOUCH_HVOLT_MAX (C++ enumerator), 724 TOUCH_JITTER_STEP_MAX (C macro), 723 touch_low_volt_t (C++ enum), 724 TOUCH_LVOLT_0V5 (C++ enumerator), 724 TOUCH_LVOLT_0V6 (C++ enumerator), 724 TOUCH_LVOLT_0V7 (C++ enumerator), 724 TOUCH_LVOLT_0V8 (C++ enumerator), 724 TOUCH_LVOLT_KEEP (C++ enumerator), 724 TOUCH_LVOLT_MAX (C++ enumerator), 724 TOUCH_NOISE_THR_MAX (C macro), 723 TOUCH_PAD_ATTEN_VOLTAGE_THRESHOLD (C
macro), 722 TOUCH_PAD_BIT_MASK_ALL (C macro), 722 TOUCH_PAD_BIT_MASK_MAX (C macro), 722 touch_pad_clear_channel_mask (C++ func-
tion), 711 touch_pad_clear_status (C++ function), 720 touch_pad_config (C++ function), 711 TOUCH_PAD_CONN_GND (C++ enumerator), 727 TOUCH_PAD_CONN_HIGHZ (C++ enumerator), 727 TOUCH_PAD_CONN_MAX (C++ enumerator), 727 touch_pad_conn_type_t (C++ enum), 727 touch_pad_deinit (C++ function), 718 touch_pad_denoise (C++ class), 721 touch_pad_denoise::cap_level (C++ mem-
ber), 721 touch_pad_denoise::grade (C++ member),
721 TOUCH_PAD_DENOISE_BIT10 (C++ enumerator),
726 TOUCH_PAD_DENOISE_BIT12 (C++ enumerator),
726 TOUCH_PAD_DENOISE_BIT4 (C++ enumerator),
726 TOUCH_PAD_DENOISE_BIT8 (C++ enumerator),
726 TOUCH_PAD_DENOISE_CAP_L0 (C++ enumerator),
726 TOUCH_PAD_DENOISE_CAP_L1 (C++ enumerator),
726 TOUCH_PAD_DENOISE_CAP_L2 (C++ enumerator),
726 TOUCH_PAD_DENOISE_CAP_L3 (C++ enumerator),
727 TOUCH_PAD_DENOISE_CAP_L4 (C++ enumerator),
727

TOUCH_PAD_DENOISE_CAP_L5 (C++ enumerator), 727
TOUCH_PAD_DENOISE_CAP_L6 (C++ enumerator), 727
TOUCH_PAD_DENOISE_CAP_L7 (C++ enumerator), 727
TOUCH_PAD_DENOISE_CAP_MAX (C++ enumerator), 727
touch_pad_denoise_cap_t (C++ enum), 726 touch_pad_denoise_disable (C++ function),
714 touch_pad_denoise_enable (C++ function),
714 touch_pad_denoise_get_config (C++ func-
tion), 714 touch_pad_denoise_grade_t (C++ enum), 726 TOUCH_PAD_DENOISE_MAX (C++ enumerator), 726 touch_pad_denoise_read_data (C++ func-
tion), 714 touch_pad_denoise_set_config (C++ func-
tion), 714 touch_pad_denoise_t (C++ type), 723 touch_pad_filter_disable (C++ function),
714 touch_pad_filter_enable (C++ function), 713 touch_pad_filter_get_config (C++ func-
tion), 713 TOUCH_PAD_FILTER_IIR_128 (C++ enumerator),
728 TOUCH_PAD_FILTER_IIR_16 (C++ enumerator),
728 TOUCH_PAD_FILTER_IIR_256 (C++ enumerator),
728 TOUCH_PAD_FILTER_IIR_32 (C++ enumerator),
728 TOUCH_PAD_FILTER_IIR_4 (C++ enumerator),
728 TOUCH_PAD_FILTER_IIR_64 (C++ enumerator),
728 TOUCH_PAD_FILTER_IIR_8 (C++ enumerator),
728 TOUCH_PAD_FILTER_JITTER (C++ enumerator),
728 TOUCH_PAD_FILTER_MAX (C++ enumerator), 728 touch_pad_filter_read_smooth (C++ func-
tion), 713 touch_pad_filter_set_config (C++ func-
tion), 713 touch_pad_fsm_start (C++ function), 709 touch_pad_fsm_stop (C++ function), 710 touch_pad_get_channel_mask (C++ function),
711 touch_pad_get_cnt_mode (C++ function), 719 touch_pad_get_current_meas_channel
(C++ function), 711 touch_pad_get_fsm_mode (C++ function), 720 touch_pad_get_idle_channel_connect
(C++ function), 710

Espressif Systems

2161

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

touch_pad_get_meas_time (C++ function), 710

touch_pad_get_status (C++ function), 720

touch_pad_get_thresh (C++ function), 711

touch_pad_get_voltage (C++ function), 719

touch_pad_get_wakeup_status (C++ func-

tion), 719

TOUCH_PAD_GPIO10_CHANNEL (C macro), 721

TOUCH_PAD_GPIO11_CHANNEL (C macro), 721

TOUCH_PAD_GPIO12_CHANNEL (C macro), 721

TOUCH_PAD_GPIO13_CHANNEL (C macro), 721

TOUCH_PAD_GPIO14_CHANNEL (C macro), 721

TOUCH_PAD_GPIO1_CHANNEL (C macro), 720

TOUCH_PAD_GPIO2_CHANNEL (C macro), 720

TOUCH_PAD_GPIO3_CHANNEL (C macro), 720

TOUCH_PAD_GPIO4_CHANNEL (C macro), 720

TOUCH_PAD_GPIO5_CHANNEL (C macro), 720

TOUCH_PAD_GPIO6_CHANNEL (C macro), 720

TOUCH_PAD_GPIO7_CHANNEL (C macro), 721

TOUCH_PAD_GPIO8_CHANNEL (C macro), 721

TOUCH_PAD_GPIO9_CHANNEL (C macro), 721

TOUCH_PAD_HIGH_VOLTAGE_THRESHOLD (C

macro), 722

TOUCH_PAD_IDLE_CH_CONNECT_DEFAULT (C

macro), 722

touch_pad_init (C++ function), 718

touch_pad_intr_clear (C++ function), 712

touch_pad_intr_disable (C++ function), 712

touch_pad_intr_enable (C++ function), 712

TOUCH_PAD_INTR_MASK_ACTIVE (C++ enumera-

tor), 726

TOUCH_PAD_INTR_MASK_ALL (C macro), 723

TOUCH_PAD_INTR_MASK_DONE (C++ enumerator),

726

TOUCH_PAD_INTR_MASK_INACTIVE (C++ enu-

merator), 726

TOUCH_PAD_INTR_MASK_PROXI_MEAS_DONE

(C++ enumerator), 726

TOUCH_PAD_INTR_MASK_SCAN_DONE (C++ enu-

merator), 726

touch_pad_intr_mask_t (C++ enum), 726

TOUCH_PAD_INTR_MASK_TIMEOUT (C++ enumer-

ator), 726

touch_pad_io_init (C++ function), 718

touch_pad_isr_deregister (C++ function),

719

touch_pad_isr_register (C++ function), 712

TOUCH_PAD_LOW_VOLTAGE_THRESHOLD

(C

macro), 722

TOUCH_PAD_MAX (C++ enumerator), 724

touch_pad_meas_is_done (C++ function), 720

TOUCH_PAD_MEASURE_CYCLE_DEFAULT

(C

macro), 723

TOUCH_PAD_NUM0 (C++ enumerator), 723

TOUCH_PAD_NUM1 (C++ enumerator), 723

TOUCH_PAD_NUM10 (C++ enumerator), 724

TOUCH_PAD_NUM10_GPIO_NUM (C macro), 721

TOUCH_PAD_NUM11 (C++ enumerator), 724

TOUCH_PAD_NUM11_GPIO_NUM (C macro), 721

TOUCH_PAD_NUM12 (C++ enumerator), 724 TOUCH_PAD_NUM12_GPIO_NUM (C macro), 721 TOUCH_PAD_NUM13 (C++ enumerator), 724 TOUCH_PAD_NUM13_GPIO_NUM (C macro), 721 TOUCH_PAD_NUM14 (C++ enumerator), 724 TOUCH_PAD_NUM14_GPIO_NUM (C macro), 721 TOUCH_PAD_NUM1_GPIO_NUM (C macro), 720 TOUCH_PAD_NUM2 (C++ enumerator), 723 TOUCH_PAD_NUM2_GPIO_NUM (C macro), 720 TOUCH_PAD_NUM3 (C++ enumerator), 723 TOUCH_PAD_NUM3_GPIO_NUM (C macro), 720 TOUCH_PAD_NUM4 (C++ enumerator), 723 TOUCH_PAD_NUM4_GPIO_NUM (C macro), 720 TOUCH_PAD_NUM5 (C++ enumerator), 723 TOUCH_PAD_NUM5_GPIO_NUM (C macro), 720 TOUCH_PAD_NUM6 (C++ enumerator), 723 TOUCH_PAD_NUM6_GPIO_NUM (C macro), 720 TOUCH_PAD_NUM7 (C++ enumerator), 723 TOUCH_PAD_NUM7_GPIO_NUM (C macro), 721 TOUCH_PAD_NUM8 (C++ enumerator), 723 TOUCH_PAD_NUM8_GPIO_NUM (C macro), 721 TOUCH_PAD_NUM9 (C++ enumerator), 723 TOUCH_PAD_NUM9_GPIO_NUM (C macro), 721 touch_pad_proximity_enable (C++ function),
715 touch_pad_proximity_get_count (C++ func-
tion), 715 touch_pad_proximity_get_data (C++ func-
tion), 716 touch_pad_proximity_set_count (C++ func-
tion), 715 touch_pad_read_benchmark (C++ function),
713 touch_pad_read_intr_status_mask (C++
function), 712 touch_pad_read_raw_data (C++ function), 713 touch_pad_reset (C++ function), 711 touch_pad_reset_benchmark (C++ function),
713 touch_pad_set_channel_mask (C++ function),
711 touch_pad_set_cnt_mode (C++ function), 719 touch_pad_set_fsm_mode (C++ function), 719 touch_pad_set_idle_channel_connect
(C++ function), 710 touch_pad_set_meas_time (C++ function), 710 touch_pad_set_thresh (C++ function), 710 touch_pad_set_voltage (C++ function), 718 touch_pad_shield_driver_t (C++ enum), 727 TOUCH_PAD_SHIELD_DRV_L0 (C++ enumerator),
727 TOUCH_PAD_SHIELD_DRV_L1 (C++ enumerator),
727 TOUCH_PAD_SHIELD_DRV_L2 (C++ enumerator),
727 TOUCH_PAD_SHIELD_DRV_L3 (C++ enumerator),
727

Espressif Systems

2162

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

TOUCH_PAD_SHIELD_DRV_L4 (C++ enumerator), touch_pad_t (C++ enum), 723

727

TOUCH_PAD_THRESHOLD_MAX (C macro), 722

TOUCH_PAD_SHIELD_DRV_L5 (C++ enumerator), TOUCH_PAD_TIE_OPT_DEFAULT (C macro), 722

727

TOUCH_PAD_TIE_OPT_HIGH (C++ enumerator),

TOUCH_PAD_SHIELD_DRV_L6 (C++ enumerator),

725

727

TOUCH_PAD_TIE_OPT_LOW (C++ enumerator), 725

TOUCH_PAD_SHIELD_DRV_L7 (C++ enumerator), TOUCH_PAD_TIE_OPT_MAX (C++ enumerator), 725

727

touch_pad_timeout_resume (C++ function),

TOUCH_PAD_SHIELD_DRV_MAX (C++ enumerator),

712

727

touch_pad_timeout_set (C++ function), 712

touch_pad_sleep_channel_enable (C++ touch_pad_waterproof (C++ class), 721

function), 716

touch_pad_waterproof::guard_ring_pad

touch_pad_sleep_channel_enable_proximity

(C++ member), 721

(C++ function), 716

touch_pad_waterproof::shield_driver

touch_pad_sleep_channel_get_info (C++

(C++ member), 721

function), 716

touch_pad_waterproof_disable (C++ func-

touch_pad_sleep_channel_read_benchmark

tion), 715

(C++ function), 717

touch_pad_waterproof_enable (C++ func-

touch_pad_sleep_channel_read_data

tion), 715

(C++ function), 717

touch_pad_waterproof_get_config (C++

touch_pad_sleep_channel_read_proximity_cnt function), 715

(C++ function), 717

touch_pad_waterproof_set_config (C++

touch_pad_sleep_channel_read_smooth

function), 714

(C++ function), 717

touch_pad_waterproof_t (C++ type), 723

touch_pad_sleep_channel_reset_benchmarkTOUCH_PROXIMITY_MEAS_NUM_MAX (C macro),

(C++ function), 717

723

touch_pad_sleep_channel_set_work_time touch_smooth_mode_t (C++ enum), 728

(C++ function), 718

touch_tie_opt_t (C++ enum), 725

touch_pad_sleep_channel_t (C++ class), 722 TOUCH_TRIGGER_ABOVE (C++ enumerator), 726

touch_pad_sleep_channel_t::en_proximityTOUCH_TRIGGER_BELOW (C++ enumerator), 726

(C++ member), 722

TOUCH_TRIGGER_MAX (C++ enumerator), 726

touch_pad_sleep_channel_t::touch_num touch_trigger_mode_t (C++ enum), 725

(C++ member), 722

TOUCH_TRIGGER_SOURCE_BOTH (C++ enumera-

TOUCH_PAD_SLEEP_CYCLE_DEFAULT (C macro),

tor), 726

722

TOUCH_TRIGGER_SOURCE_MAX (C++ enumerator),

touch_pad_sleep_get_threshold (C++ func-

726

tion), 717

TOUCH_TRIGGER_SOURCE_SET1 (C++ enumera-

touch_pad_sleep_set_threshold (C++ func-

tor), 726

tion), 716

touch_trigger_src_t (C++ enum), 726

TOUCH_PAD_SLOPE_0 (C++ enumerator), 725

touch_volt_atten_t (C++ enum), 724

TOUCH_PAD_SLOPE_1 (C++ enumerator), 725

transaction_cb_t (C++ type), 701

TOUCH_PAD_SLOPE_2 (C++ enumerator), 725

tskDEFAULT_INDEX_TO_NOTIFY (C macro), 1175

TOUCH_PAD_SLOPE_3 (C++ enumerator), 725

tskIDLE_PRIORITY (C macro), 1175

TOUCH_PAD_SLOPE_4 (C++ enumerator), 725

tskKERNEL_VERSION_BUILD (C macro), 1175

TOUCH_PAD_SLOPE_5 (C++ enumerator), 725

tskKERNEL_VERSION_MAJOR (C macro), 1175

TOUCH_PAD_SLOPE_6 (C++ enumerator), 725

tskKERNEL_VERSION_MINOR (C macro), 1175

TOUCH_PAD_SLOPE_7 (C++ enumerator), 725

tskKERNEL_VERSION_NUMBER (C macro), 1175

TOUCH_PAD_SLOPE_DEFAULT (C macro), 722

tskMPU_REGION_DEVICE_MEMORY (C macro),

TOUCH_PAD_SLOPE_MAX (C++ enumerator), 725

1175

TOUCH_PAD_SMOOTH_IIR_2 (C++ enumerator), tskMPU_REGION_EXECUTE_NEVER (C macro),

728

1175

TOUCH_PAD_SMOOTH_IIR_4 (C++ enumerator), tskMPU_REGION_NORMAL_MEMORY (C macro),

728

1175

TOUCH_PAD_SMOOTH_IIR_8 (C++ enumerator), tskMPU_REGION_READ_ONLY (C macro), 1175

728

tskMPU_REGION_READ_WRITE (C macro), 1175

TOUCH_PAD_SMOOTH_MAX (C++ enumerator), 728 tskNO_AFFINITY (C macro), 1175

TOUCH_PAD_SMOOTH_OFF (C++ enumerator), 728 tusb_cdc_acm_init (C++ function), 769

touch_pad_sw_start (C++ function), 710

tusb_cdc_acm_initialized (C++ function),

Espressif Systems

2163

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

770 tusb_cdcacm_callback_t (C++ type), 772 tusb_run_task (C++ function), 773 tusb_stop_task (C++ function), 773 twai_clear_receive_queue (C++ function),
742 twai_clear_transmit_queue (C++ function),
742 twai_driver_install (C++ function), 740 twai_driver_uninstall (C++ function), 740 TWAI_ERR_PASS_THRESH (C macro), 739 TWAI_EXTD_ID_MASK (C macro), 739 twai_filter_config_t (C++ class), 739 twai_filter_config_t::acceptance_code
(C++ member), 739 twai_filter_config_t::acceptance_mask
(C++ member), 739 twai_filter_config_t::single_filter
(C++ member), 739 TWAI_FRAME_EXTD_ID_LEN_BYTES (C macro),
739 TWAI_FRAME_MAX_DLC (C macro), 739 TWAI_FRAME_STD_ID_LEN_BYTES (C macro),
739 twai_general_config_t (C++ class), 742 twai_general_config_t::alerts_enabled
(C++ member), 743 twai_general_config_t::bus_off_io
(C++ member), 743 twai_general_config_t::clkout_divider
(C++ member), 743 twai_general_config_t::clkout_io (C++
member), 742 twai_general_config_t::intr_flags
(C++ member), 743 twai_general_config_t::mode (C++ mem-
ber), 742 twai_general_config_t::rx_io (C++ mem-
ber), 742 twai_general_config_t::rx_queue_len
(C++ member), 743 twai_general_config_t::tx_io (C++ mem-
ber), 742 twai_general_config_t::tx_queue_len
(C++ member), 743 twai_get_status_info (C++ function), 742 twai_initiate_recovery (C++ function), 742 TWAI_IO_UNUSED (C macro), 743 twai_message_t (C++ class), 738 twai_message_t::data (C++ member), 738 twai_message_t::data_length_code (C++
member), 738 twai_message_t::dlc_non_comp (C++ mem-
ber), 738 twai_message_t::extd (C++ member), 738 twai_message_t::flags (C++ member), 738 twai_message_t::identifier (C++ member),
738

twai_message_t::reserved (C++ member), 738
twai_message_t::rtr (C++ member), 738 twai_message_t::self (C++ member), 738 twai_message_t::ss (C++ member), 738 TWAI_MODE_LISTEN_ONLY (C++ enumerator), 739 TWAI_MODE_NO_ACK (C++ enumerator), 739 TWAI_MODE_NORMAL (C++ enumerator), 739 twai_mode_t (C++ enum), 739 twai_read_alerts (C++ function), 741 twai_receive (C++ function), 741 twai_reconfigure_alerts (C++ function), 741 twai_start (C++ function), 740 TWAI_STATE_BUS_OFF (C++ enumerator), 744 TWAI_STATE_RECOVERING (C++ enumerator), 744 TWAI_STATE_RUNNING (C++ enumerator), 744 TWAI_STATE_STOPPED (C++ enumerator), 744 twai_state_t (C++ enum), 743 twai_status_info_t (C++ class), 743 twai_status_info_t::arb_lost_count
(C++ member), 743 twai_status_info_t::bus_error_count
(C++ member), 743 twai_status_info_t::msgs_to_rx (C++
member), 743 twai_status_info_t::msgs_to_tx (C++
member), 743 twai_status_info_t::rx_error_counter
(C++ member), 743 twai_status_info_t::rx_missed_count
(C++ member), 743 twai_status_info_t::rx_overrun_count
(C++ member), 743 twai_status_info_t::state (C++ member),
743 twai_status_info_t::tx_error_counter
(C++ member), 743 twai_status_info_t::tx_failed_count
(C++ member), 743 TWAI_STD_ID_MASK (C macro), 739 twai_stop (C++ function), 740 twai_timing_config_t (C++ class), 738 twai_timing_config_t::brp (C++ member),
738 twai_timing_config_t::sjw (C++ member),
738 twai_timing_config_t::triple_sampling
(C++ member), 738 twai_timing_config_t::tseg_1 (C++ mem-
ber), 738 twai_timing_config_t::tseg_2 (C++ mem-
ber), 738 twai_transmit (C++ function), 740
U
uart_at_cmd_t (C++ class), 761 uart_at_cmd_t::char_num (C++ member), 761 uart_at_cmd_t::cmd_char (C++ member), 761

Espressif Systems

2164

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

uart_at_cmd_t::gap_tout (C++ member), 762

uart_at_cmd_t::post_idle (C++ member),

762

uart_at_cmd_t::pre_idle (C++ member), 762

UART_BITRATE_MAX (C macro), 761

UART_BREAK (C++ enumerator), 761

UART_BUFFER_FULL (C++ enumerator), 761

uart_clear_intr_status (C++ function), 752

uart_config_t (C++ class), 762

uart_config_t::baud_rate (C++ member),

762

uart_config_t::data_bits (C++ member),

762

uart_config_t::flow_ctrl (C++ member),

762

uart_config_t::parity (C++ member), 762

uart_config_t::rx_flow_ctrl_thresh

(C++ member), 762

uart_config_t::source_clk (C++ member),

762

uart_config_t::stop_bits (C++ member),

762

uart_config_t::use_ref_tick (C++ mem-

ber), 762

UART_CTS_GPIO19_DIRECT_CHANNEL

(C

macro), 765

UART_CTS_GPIO6_DIRECT_CHANNEL (C macro),

765

UART_CTS_GPIO8_DIRECT_CHANNEL (C macro),

766

UART_DATA (C++ enumerator), 761

UART_DATA_5_BITS (C++ enumerator), 763

UART_DATA_6_BITS (C++ enumerator), 763

UART_DATA_7_BITS (C++ enumerator), 763

UART_DATA_8_BITS (C++ enumerator), 763

UART_DATA_BITS_MAX (C++ enumerator), 763

UART_DATA_BREAK (C++ enumerator), 761

uart_disable_intr_mask (C++ function), 753

uart_disable_pattern_det_intr (C++ func-

tion), 756

uart_disable_rx_intr (C++ function), 753

uart_disable_tx_intr (C++ function), 753

uart_driver_delete (C++ function), 750

uart_driver_install (C++ function), 750

uart_enable_intr_mask (C++ function), 753

uart_enable_pattern_det_baud_intr

(C++ function), 757

uart_enable_rx_intr (C++ function), 753

uart_enable_tx_intr (C++ function), 753

UART_EVENT_MAX (C++ enumerator), 761

uart_event_t (C++ class), 760

uart_event_t::size (C++ member), 760

uart_event_t::timeout_flag (C++ member),

760

uart_event_t::type (C++ member), 760

uart_event_type_t (C++ enum), 761

UART_FIFO_LEN (C macro), 761

UART_FIFO_OVF (C++ enumerator), 761

uart_flush (C++ function), 756

uart_flush_input (C++ function), 756

UART_FRAME_ERR (C++ enumerator), 761

uart_get_baudrate (C++ function), 752

uart_get_buffered_data_len (C++ function),

756

uart_get_collision_flag (C++ function), 758

uart_get_hw_flow_ctrl (C++ function), 752

uart_get_parity (C++ function), 751

uart_get_stop_bits (C++ function), 751

uart_get_wakeup_threshold (C++ function),

759

uart_get_word_length (C++ function), 751

UART_GPIO10_DIRECT_CHANNEL (C macro), 765

UART_GPIO11_DIRECT_CHANNEL (C macro), 765

UART_GPIO16_DIRECT_CHANNEL (C macro), 766

UART_GPIO17_DIRECT_CHANNEL (C macro), 765

UART_GPIO19_DIRECT_CHANNEL (C macro), 765

UART_GPIO1_DIRECT_CHANNEL (C macro), 765

UART_GPIO22_DIRECT_CHANNEL (C macro), 765

UART_GPIO3_DIRECT_CHANNEL (C macro), 765

UART_GPIO6_DIRECT_CHANNEL (C macro), 765

UART_GPIO7_DIRECT_CHANNEL (C macro), 766

UART_GPIO8_DIRECT_CHANNEL (C macro), 766

UART_GPIO9_DIRECT_CHANNEL (C macro), 765

uart_hw_flowcontrol_t (C++ enum), 763

UART_HW_FLOWCTRL_CTS (C++ enumerator), 764

UART_HW_FLOWCTRL_CTS_RTS (C++ enumerator),

764

UART_HW_FLOWCTRL_DISABLE (C++ enumerator),

764

UART_HW_FLOWCTRL_MAX (C++ enumerator), 764

UART_HW_FLOWCTRL_RTS (C++ enumerator), 764

uart_intr_config (C++ function), 755

uart_intr_config_t (C++ class), 760

uart_intr_config_t::intr_enable_mask

(C++ member), 760

uart_intr_config_t::rx_timeout_thresh

(C++ member), 760

uart_intr_config_t::rxfifo_full_thresh

(C++ member), 760

uart_intr_config_t::txfifo_empty_intr_thresh

(C++ member), 760

uart_is_driver_installed (C++ function),

750

uart_isr_handle_t (C++ type), 761

UART_MODE_IRDA (C++ enumerator), 763

UART_MODE_RS485_APP_CTRL (C++ enumerator),

763

UART_MODE_RS485_COLLISION_DETECT (C++

enumerator), 763

UART_MODE_RS485_HALF_DUPLEX (C++ enumer-

ator), 763

uart_mode_t (C++ enum), 763

UART_MODE_UART (C++ enumerator), 763

UART_NUM_0 (C macro), 760

UART_NUM_0_CTS_DIRECT_GPIO_NUM

(C

macro), 765

Espressif Systems

2165

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

UART_NUM_0_RTS_DIRECT_GPIO_NUM

(C

macro), 765

UART_NUM_0_RXD_DIRECT_GPIO_NUM

(C

macro), 765

UART_NUM_0_TXD_DIRECT_GPIO_NUM

(C

macro), 765

UART_NUM_1 (C macro), 760

UART_NUM_1_CTS_DIRECT_GPIO_NUM

(C

macro), 765

UART_NUM_1_RTS_DIRECT_GPIO_NUM

(C

macro), 765

UART_NUM_1_RXD_DIRECT_GPIO_NUM

(C

macro), 765

UART_NUM_1_TXD_DIRECT_GPIO_NUM

(C

macro), 765

UART_NUM_2 (C macro), 760

UART_NUM_2_CTS_DIRECT_GPIO_NUM

(C

macro), 766

UART_NUM_2_RTS_DIRECT_GPIO_NUM

(C

macro), 766

UART_NUM_2_RXD_DIRECT_GPIO_NUM

(C

macro), 766

UART_NUM_2_TXD_DIRECT_GPIO_NUM

(C

macro), 766

UART_NUM_MAX (C macro), 760

uart_param_config (C++ function), 754

UART_PARITY_DISABLE (C++ enumerator), 763

UART_PARITY_ERR (C++ enumerator), 761

UART_PARITY_EVEN (C++ enumerator), 763

UART_PARITY_ODD (C++ enumerator), 763

uart_parity_t (C++ enum), 763

UART_PATTERN_DET (C++ enumerator), 761

uart_pattern_get_pos (C++ function), 757

uart_pattern_pop_pos (C++ function), 757

uart_pattern_queue_reset (C++ function),

757

UART_PIN_NO_CHANGE (C macro), 761

uart_port_t (C++ type), 762

uart_read_bytes (C++ function), 756

UART_RTS_GPIO11_DIRECT_CHANNEL

(C

macro), 765

UART_RTS_GPIO22_DIRECT_CHANNEL

(C

macro), 765

UART_RTS_GPIO7_DIRECT_CHANNEL (C macro),

766

UART_RXD_GPIO16_DIRECT_CHANNEL

(C

macro), 766

UART_RXD_GPIO3_DIRECT_CHANNEL (C macro),

765

UART_RXD_GPIO9_DIRECT_CHANNEL (C macro),

765

UART_SCLK_APB (C++ enumerator), 764

UART_SCLK_RTC (C++ enumerator), 764

uart_sclk_t (C++ enum), 764

UART_SCLK_XTAL (C++ enumerator), 764

uart_set_always_rx_timeout (C++ function),

760

uart_set_baudrate (C++ function), 751

uart_set_dtr (C++ function), 754

uart_set_hw_flow_ctrl (C++ function), 752

uart_set_line_inverse (C++ function), 752

uart_set_loop_back (C++ function), 759

uart_set_mode (C++ function), 758

uart_set_parity (C++ function), 751

uart_set_pin (C++ function), 754

uart_set_rts (C++ function), 754

uart_set_rx_full_threshold (C++ function),

758

uart_set_rx_timeout (C++ function), 758

uart_set_stop_bits (C++ function), 751

uart_set_sw_flow_ctrl (C++ function), 752

uart_set_tx_empty_threshold (C++ func-

tion), 758

uart_set_tx_idle_num (C++ function), 754

uart_set_wakeup_threshold (C++ function),

759

uart_set_word_length (C++ function), 751

UART_SIGNAL_CTS_INV (C++ enumerator), 764

UART_SIGNAL_DSR_INV (C++ enumerator), 764

UART_SIGNAL_DTR_INV (C++ enumerator), 764

UART_SIGNAL_INV_DISABLE (C++ enumerator),

764

uart_signal_inv_t (C++ enum), 764

UART_SIGNAL_IRDA_RX_INV (C++ enumerator),

764

UART_SIGNAL_IRDA_TX_INV (C++ enumerator),

764

UART_SIGNAL_RTS_INV (C++ enumerator), 764

UART_SIGNAL_RXD_INV (C++ enumerator), 764

UART_SIGNAL_TXD_INV (C++ enumerator), 764

UART_STOP_BITS_1 (C++ enumerator), 763

UART_STOP_BITS_1_5 (C++ enumerator), 763

UART_STOP_BITS_2 (C++ enumerator), 763

UART_STOP_BITS_MAX (C++ enumerator), 763

uart_stop_bits_t (C++ enum), 763

uart_sw_flowctrl_t (C++ class), 762

uart_sw_flowctrl_t::xoff_char (C++

member), 762

uart_sw_flowctrl_t::xoff_thrd (C++

member), 762

uart_sw_flowctrl_t::xon_char (C++ mem-

ber), 762

uart_sw_flowctrl_t::xon_thrd (C++ mem-

ber), 762

uart_tx_chars (C++ function), 755

UART_TXD_GPIO10_DIRECT_CHANNEL

(C

macro), 765

UART_TXD_GPIO17_DIRECT_CHANNEL

(C

macro), 766

UART_TXD_GPIO1_DIRECT_CHANNEL (C macro),

765

uart_wait_tx_done (C++ function), 755

uart_wait_tx_idle_polling (C++ function),

759

uart_word_length_t (C++ enum), 763

uart_write_bytes (C++ function), 755

Espressif Systems

2166

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

uart_write_bytes_with_break (C++ func- USB_B_DESCRIPTOR_TYPE_WIRE_ADAPTER (C

tion), 755

macro), 797

UINT16 (C++ type), 202

USB_B_DESCRIPTOR_TYPE_WIRELESS_ENDPOINT_COMP

UINT32 (C++ type), 202

(C macro), 797

UINT64 (C++ type), 202

USB_B_ENDPOINT_ADDRESS_EP_DIR_MASK (C

UINT8 (C++ type), 202

macro), 800

ulp_load_binary (C++ function), 1898

USB_B_ENDPOINT_ADDRESS_EP_NUM_MASK (C

ulp_process_macros_and_load (C++ func-

macro), 800

tion), 1892

USB_B_REQUEST_CLEAR_FEATURE (C macro),

ulp_riscv_load_binary (C++ function), 1901

798

ulp_riscv_run (C++ function), 1901

USB_B_REQUEST_GET_CONFIGURATION

(C

ulp_run (C++ function), 1892, 1898

macro), 798

ulTaskGenericNotifyTake (C++ function), USB_B_REQUEST_GET_DESCRIPTOR (C macro),

1171

798

ulTaskGenericNotifyValueClear (C++ func- USB_B_REQUEST_GET_INTERFACE (C macro),

tion), 1173

798

ulTaskGetIdleRunTimeCounter (C++ func- USB_B_REQUEST_GET_STATUS (C macro), 798

tion), 1167

USB_B_REQUEST_SET_ADDRESS (C macro), 798

ulTaskNotifyTake (C macro), 1177

USB_B_REQUEST_SET_CONFIGURATION

(C

ulTaskNotifyTakeIndexed (C macro), 1177

macro), 798

ulTaskNotifyValueClear (C macro), 1177

USB_B_REQUEST_SET_DESCRIPTOR (C macro),

ulTaskNotifyValueClearIndexed (C macro),

798

1177

USB_B_REQUEST_SET_FEATURE (C macro), 798

USB_B_DESCRIPTOR_TYPE_BOS (C macro), 797 USB_B_REQUEST_SET_INTERFACE (C macro),

USB_B_DESCRIPTOR_TYPE_CONFIGURATION (C

798

macro), 797

USB_B_REQUEST_SYNCH_FRAME (C macro), 798

USB_B_DESCRIPTOR_TYPE_CS_RADIO_CONTROL USB_BM_ATTRIBUTES_BATTERY (C macro), 800

(C macro), 797

USB_BM_ATTRIBUTES_ONE (C macro), 800

USB_B_DESCRIPTOR_TYPE_DEBUG (C macro), USB_BM_ATTRIBUTES_SELFPOWER (C macro),

797

800

USB_B_DESCRIPTOR_TYPE_DEVICE (C macro), USB_BM_ATTRIBUTES_SYNC_ADAPTIVE

(C

797

macro), 800

USB_B_DESCRIPTOR_TYPE_DEVICE_CAPABILITYUSB_BM_ATTRIBUTES_SYNC_ASYNC (C macro),

(C macro), 797

800

USB_B_DESCRIPTOR_TYPE_DEVICE_QUALIFIER USB_BM_ATTRIBUTES_SYNC_NONE (C macro),

(C macro), 797

800

USB_B_DESCRIPTOR_TYPE_ENCRYPTION_TYPE USB_BM_ATTRIBUTES_SYNC_SYNC (C macro),

(C macro), 797

800

USB_B_DESCRIPTOR_TYPE_ENDPOINT

(C USB_BM_ATTRIBUTES_SYNCTYPE_MASK

(C

macro), 797

macro), 800

USB_B_DESCRIPTOR_TYPE_INTERFACE

(C USB_BM_ATTRIBUTES_USAGE_DATA (C macro),

macro), 797

800

USB_B_DESCRIPTOR_TYPE_INTERFACE_ASSOCIAUTSIBO_NBM_ATTRIBUTES_USAGE_FEEDBACK (C

(C macro), 797

macro), 800

USB_B_DESCRIPTOR_TYPE_INTERFACE_POWER USB_BM_ATTRIBUTES_USAGE_IMPLICIT_FB (C

(C macro), 797

macro), 800

USB_B_DESCRIPTOR_TYPE_KEY (C macro), 797 USB_BM_ATTRIBUTES_USAGETYPE_MASK (C

USB_B_DESCRIPTOR_TYPE_OTG (C macro), 797

macro), 800

USB_B_DESCRIPTOR_TYPE_OTHER_SPEED_CONFIUGSUBR_ABTMI_OANTTRIBUTES_WAKEUP (C macro), 800

(C macro), 797

USB_BM_ATTRIBUTES_XFER_BULK (C macro),

USB_B_DESCRIPTOR_TYPE_PIPE_USAGE (C

800

macro), 798

USB_BM_ATTRIBUTES_XFER_CONTROL

(C

USB_B_DESCRIPTOR_TYPE_RPIPE (C macro),

macro), 800

797

USB_BM_ATTRIBUTES_XFER_INT (C macro), 800

USB_B_DESCRIPTOR_TYPE_SECURITY

(C USB_BM_ATTRIBUTES_XFER_ISOC (C macro),

macro), 797

800

USB_B_DESCRIPTOR_TYPE_STRING (C macro), USB_BM_ATTRIBUTES_XFERTYPE_MASK

(C

797

macro), 800

Espressif Systems

2167

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

USB_BM_REQUEST_TYPE_DIR_IN (C macro), 798

ber), 795

USB_BM_REQUEST_TYPE_DIR_OUT (C macro), usb_config_desc_t::bNumInterfaces

798

(C++ member), 795

USB_BM_REQUEST_TYPE_RECIP_DEVICE (C usb_config_desc_t::iConfiguration

macro), 798

(C++ member), 795

USB_BM_REQUEST_TYPE_RECIP_ENDPOINT (C usb_config_desc_t::USB_DESC_ATTR (C++

macro), 798

member), 795

USB_BM_REQUEST_TYPE_RECIP_INTERFACE (C usb_config_desc_t::val (C++ member), 795

macro), 798

usb_config_desc_t::wTotalLength (C++

USB_BM_REQUEST_TYPE_RECIP_MASK

(C

member), 795

macro), 798

USB_DESC_ATTR (C macro), 797

USB_BM_REQUEST_TYPE_RECIP_OTHER

(C USB_DEVICE_DESC_SIZE (C macro), 799

macro), 798

usb_device_desc_t (C++ union), 794

USB_BM_REQUEST_TYPE_TYPE_CLASS

(C usb_device_desc_t::bcdDevice (C++ mem-

macro), 798

ber), 794

USB_BM_REQUEST_TYPE_TYPE_MASK (C macro), usb_device_desc_t::bcdUSB (C++ member),

798

794

USB_BM_REQUEST_TYPE_TYPE_RESERVED (C usb_device_desc_t::bDescriptorType

macro), 798

(C++ member), 794

USB_BM_REQUEST_TYPE_TYPE_STANDARD (C usb_device_desc_t::bDeviceClass (C++

macro), 798

member), 794

USB_BM_REQUEST_TYPE_TYPE_VENDOR

(C usb_device_desc_t::bDeviceProtocol

macro), 798

(C++ member), 794

USB_CLASS_APP_SPEC (C macro), 799

usb_device_desc_t::bDeviceSubClass

USB_CLASS_AUDIO (C macro), 799

(C++ member), 794

USB_CLASS_AUDIO_VIDEO (C macro), 799

usb_device_desc_t::bLength (C++ member),

USB_CLASS_BILLBOARD (C macro), 799

794

USB_CLASS_CDC_DATA (C macro), 799

usb_device_desc_t::bMaxPacketSize0

USB_CLASS_COMM (C macro), 799

(C++ member), 794

USB_CLASS_CONTENT_SEC (C macro), 799

usb_device_desc_t::bNumConfigurations

USB_CLASS_CSCID (C macro), 799

(C++ member), 794

USB_CLASS_HID (C macro), 799

usb_device_desc_t::idProduct (C++ mem-

USB_CLASS_HUB (C macro), 799

ber), 794

USB_CLASS_MASS_STORAGE (C macro), 799

usb_device_desc_t::idVendor (C++ mem-

USB_CLASS_MISC (C macro), 799

ber), 794

USB_CLASS_PER_INTERFACE (C macro), 799

usb_device_desc_t::iManufacturer (C++

USB_CLASS_PERSONAL_HEALTHCARE (C macro),

member), 794

799

usb_device_desc_t::iProduct (C++ mem-

USB_CLASS_PHYSICAL (C macro), 799

ber), 794

USB_CLASS_PRINTER (C macro), 799

usb_device_desc_t::iSerialNumber (C++

USB_CLASS_STILL_IMAGE (C macro), 799

member), 794

USB_CLASS_USB_TYPE_C_BRIDGE (C macro), usb_device_desc_t::USB_DESC_ATTR (C++

799

member), 794

USB_CLASS_VENDOR_SPEC (C macro), 799

usb_device_desc_t::val (C++ member), 795

USB_CLASS_VIDEO (C macro), 799

usb_device_handle_t (C++ type), 792

USB_CLASS_WIRELESS_CONTROLLER (C macro), usb_device_info_t (C++ class), 790

799

usb_device_info_t::bConfigurationValue

USB_CONFIG_DESC_SIZE (C macro), 800

(C++ member), 790

usb_config_desc_t (C++ union), 795

usb_device_info_t::bMaxPacketSize0

usb_config_desc_t::bConfigurationValue

(C++ member), 790

(C++ member), 795

usb_device_info_t::dev_addr (C++ mem-

usb_config_desc_t::bDescriptorType

ber), 790

(C++ member), 795

usb_device_info_t::speed (C++ member),

usb_config_desc_t::bLength (C++ member),

790

795

usb_device_info_t::str_desc_manufacturer

usb_config_desc_t::bmAttributes (C++

(C++ member), 790

member), 795

usb_device_info_t::str_desc_product

usb_config_desc_t::bMaxPower (C++ mem-

(C++ member), 790

Espressif Systems

2168

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

usb_device_info_t::str_desc_serial_num usb_host_client_event_msg_t::event

(C++ member), 790

(C++ member), 786

USB_DEVICE_STATE_ADDRESS (C++ enumerator), USB_HOST_CLIENT_EVENT_NEW_DEV (C++ enu-

801

merator), 787

USB_DEVICE_STATE_ATTACHED (C++ enumera- usb_host_client_event_t (C++ enum), 787

tor), 801

usb_host_client_handle_events (C++ func-

USB_DEVICE_STATE_CONFIGURED (C++ enumer-

tion), 782

ator), 801

usb_host_client_handle_t (C++ type), 787

USB_DEVICE_STATE_DEFAULT (C++ enumerator), usb_host_client_register (C++ function),

801

782

USB_DEVICE_STATE_NOT_ATTACHED (C++ enu- usb_host_client_unblock (C++ function), 782

merator), 801

usb_host_config_t (C++ class), 786

USB_DEVICE_STATE_POWERED (C++ enumerator), usb_host_config_t::intr_flags (C++

801

member), 786

USB_DEVICE_STATE_SUSPENDED (C++ enumera- usb_host_config_t::skip_phy_setup

tor), 801

(C++ member), 786

usb_device_state_t (C++ enum), 801

usb_host_device_addr_list_fill (C++

USB_EP_DESC_GET_EP_DIR (C macro), 800

function), 783

USB_EP_DESC_GET_EP_NUM (C macro), 800

usb_host_device_close (C++ function), 782

USB_EP_DESC_GET_MPS (C macro), 800

usb_host_device_free_all (C++ function),

USB_EP_DESC_GET_XFERTYPE (C macro), 800

783

USB_EP_DESC_SIZE (C macro), 800

usb_host_device_info (C++ function), 783

usb_ep_desc_t (C++ union), 796

usb_host_device_open (C++ function), 782

usb_ep_desc_t::bDescriptorType (C++ usb_host_endpoint_clear (C++ function), 785

member), 796

usb_host_endpoint_flush (C++ function), 784

usb_ep_desc_t::bEndpointAddress (C++ usb_host_endpoint_halt (C++ function), 784

member), 796

usb_host_get_active_config_descriptor

usb_ep_desc_t::bInterval (C++ member),

(C++ function), 783

796

usb_host_get_device_descriptor (C++

usb_ep_desc_t::bLength (C++ member), 796

function), 783

usb_ep_desc_t::bmAttributes (C++ mem- usb_host_install (C++ function), 781

ber), 796

usb_host_interface_claim (C++ function),

usb_ep_desc_t::USB_DESC_ATTR (C++ mem-

784

ber), 797

usb_host_interface_release (C++ function),

usb_ep_desc_t::val (C++ member), 797

784

usb_ep_desc_t::wMaxPacketSize (C++ USB_HOST_LIB_EVENT_FLAGS_ALL_FREE (C

member), 796

macro), 787

USB_ESPRESSIF_VID (C macro), 769

USB_HOST_LIB_EVENT_FLAGS_NO_CLIENTS (C

usb_host_client_config_t (C++ class), 786

macro), 787

usb_host_client_config_t::callback_arg usb_host_lib_handle_events (C++ function),

(C++ member), 787

781

usb_host_client_config_t::client_event_ucsabl_lhboasctk_lib_info (C++ function), 781

(C++ member), 787

usb_host_lib_info_t (C++ class), 786

usb_host_client_config_t::is_synchronouussb_host_lib_info_t::num_clients (C++

(C++ member), 787

member), 786

usb_host_client_config_t::max_num_eventu_smbs_ghost_lib_info_t::num_devices (C++

(C++ member), 787

member), 786

usb_host_client_deregister (C++ function), usb_host_lib_unblock (C++ function), 781

782

usb_host_transfer_alloc (C++ function), 785

usb_host_client_event_cb_t (C++ type), 787 usb_host_transfer_free (C++ function), 785

USB_HOST_CLIENT_EVENT_DEV_GONE (C++ usb_host_transfer_submit (C++ function),

enumerator), 787

785

usb_host_client_event_msg_t (C++ class), usb_host_transfer_submit_control (C++

786

function), 785

usb_host_client_event_msg_t::address usb_host_uninstall (C++ function), 781

(C++ member), 786

USB_IAD_DESC_SIZE (C macro), 800

usb_host_client_event_msg_t::dev_hdl usb_iad_desc_t (C++ union), 795

(C++ member), 786

usb_iad_desc_t::bDescriptorType (C++

Espressif Systems

2169

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

member), 795

(C++ function), 788

usb_iad_desc_t::bFirstInterface (C++ usb_print_config_descriptor (C++ func-

member), 795

tion), 789

usb_iad_desc_t::bFunctionClass (C++ usb_print_device_descriptor (C++ func-

member), 795

tion), 789

usb_iad_desc_t::bFunctionProtocol

usb_print_string_descriptor (C++ func-

(C++ member), 795

tion), 789

usb_iad_desc_t::bFunctionSubClass

usb_round_up_to_mps (C++ function), 789

(C++ member), 795

USB_SETUP_PACKET_INIT_GET_CONFIG (C

usb_iad_desc_t::bInterfaceCount (C++

macro), 799

member), 795

USB_SETUP_PACKET_INIT_GET_CONFIG_DESC

usb_iad_desc_t::bLength (C++ member), 795

(C macro), 799

usb_iad_desc_t::iFunction (C++ member), USB_SETUP_PACKET_INIT_GET_DEVICE_DESC

796

(C macro), 799

usb_iad_desc_t::USB_DESC_ATTR (C++ USB_SETUP_PACKET_INIT_GET_STR_DESC (C

member), 796

macro), 799

usb_iad_desc_t::val (C++ member), 796

USB_SETUP_PACKET_INIT_SET_ADDR

(C

USB_INTF_DESC_SIZE (C macro), 800

macro), 798

usb_intf_desc_t (C++ union), 796

USB_SETUP_PACKET_INIT_SET_CONFIG (C

usb_intf_desc_t::bAlternateSetting

macro), 799

(C++ member), 796

USB_SETUP_PACKET_INIT_SET_INTERFACE (C

usb_intf_desc_t::bDescriptorType (C++

macro), 799

member), 796

USB_SETUP_PACKET_SIZE (C macro), 798

usb_intf_desc_t::bInterfaceClass (C++ usb_setup_packet_t (C++ union), 793

member), 796

usb_setup_packet_t::bmRequestType

usb_intf_desc_t::bInterfaceNumber

(C++ member), 793

(C++ member), 796

usb_setup_packet_t::bRequest (C++ mem-

usb_intf_desc_t::bInterfaceProtocol

ber), 793

(C++ member), 796

usb_setup_packet_t::val (C++ member), 793

usb_intf_desc_t::bInterfaceSubClass usb_setup_packet_t::wIndex (C++ member),

(C++ member), 796

793

usb_intf_desc_t::bLength (C++ member), usb_setup_packet_t::wLength (C++ mem-

796

ber), 793

usb_intf_desc_t::bNumEndpoints (C++ usb_setup_packet_t::wValue (C++ member),

member), 796

793

usb_intf_desc_t::iInterface (C++ mem- usb_setup_packet_t::[anonymous] (C++

ber), 796

member), 793

usb_intf_desc_t::USB_DESC_ATTR (C++ USB_SPEED_FULL (C++ enumerator), 792

member), 796

USB_SPEED_LOW (C++ enumerator), 792

usb_intf_desc_t::val (C++ member), 796

usb_speed_t (C++ enum), 792

usb_isoc_packet_desc_t (C++ class), 790

USB_STANDARD_DESC_SIZE (C macro), 799

usb_isoc_packet_desc_t::actual_num_byteussb_standard_desc_t (C++ union), 794

(C++ member), 790

usb_standard_desc_t::bDescriptorType

usb_isoc_packet_desc_t::num_bytes

(C++ member), 794

(C++ member), 790

usb_standard_desc_t::bLength (C++ mem-

usb_isoc_packet_desc_t::status (C++

ber), 794

member), 790

usb_standard_desc_t::USB_DESC_ATTR

usb_parse_endpoint_descriptor_by_address

(C++ member), 794

(C++ function), 789

usb_standard_desc_t::val (C++ member),

usb_parse_endpoint_descriptor_by_index

794

(C++ function), 788

USB_STR_DESC_SIZE (C macro), 800

usb_parse_interface_descriptor (C++ usb_str_desc_t (C++ union), 797

function), 788

usb_str_desc_t::bDescriptorType (C++

usb_parse_interface_number_of_alternate

member), 797

(C++ function), 788

usb_str_desc_t::bLength (C++ member), 797

usb_parse_next_descriptor (C++ function), usb_str_desc_t::USB_DESC_ATTR (C++

787

member), 797

usb_parse_next_descriptor_of_type

usb_str_desc_t::val (C++ member), 797

Espressif Systems

2170

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

usb_str_desc_t::wData (C++ member), 797 USB_STRING_DESCRIPTOR_ARRAY_SIZE (C
macro), 769 USB_SUBCLASS_VENDOR_SPEC (C macro), 800 usb_transfer_cb_t (C++ type), 792 USB_TRANSFER_FLAG_ZERO_PACK (C macro),
791 usb_transfer_s (C++ class), 791 usb_transfer_s::actual_num_bytes (C++
member), 791 usb_transfer_s::bEndpointAddress (C++
member), 791 usb_transfer_s::callback (C++ member),
791 usb_transfer_s::context (C++ member), 791 usb_transfer_s::data_buffer (C++ mem-
ber), 791 usb_transfer_s::data_buffer_size (C++
member), 791 usb_transfer_s::device_handle (C++
member), 791 usb_transfer_s::flags (C++ member), 791 usb_transfer_s::isoc_packet_desc (C++
member), 791 usb_transfer_s::num_bytes (C++ member),
791 usb_transfer_s::num_isoc_packets (C++
member), 791 usb_transfer_s::status (C++ member), 791 usb_transfer_s::timeout_ms (C++ member),
791 USB_TRANSFER_STATUS_CANCELED (C++ enu-
merator), 793 USB_TRANSFER_STATUS_COMPLETED (C++ enu-
merator), 793 USB_TRANSFER_STATUS_ERROR (C++ enumera-
tor), 793 USB_TRANSFER_STATUS_NO_DEVICE (C++ enu-
merator), 793 USB_TRANSFER_STATUS_OVERFLOW (C++ enu-
merator), 793 USB_TRANSFER_STATUS_SKIPPED (C++ enumer-
ator), 793 USB_TRANSFER_STATUS_STALL (C++ enumera-
tor), 793 usb_transfer_status_t (C++ enum), 793 USB_TRANSFER_STATUS_TIMED_OUT (C++ enu-
merator), 793 usb_transfer_t (C++ type), 792 USB_TRANSFER_TYPE_BULK (C++ enumerator),
793 USB_TRANSFER_TYPE_CTRL (C++ enumerator),
792 USB_TRANSFER_TYPE_INTR (C++ enumerator),
793 USB_TRANSFER_TYPE_ISOCHRONOUS (C++ enu-
merator), 792 usb_transfer_type_t (C++ enum), 792

USB_W_VALUE_DT_CONFIG (C macro), 798

USB_W_VALUE_DT_DEVICE (C macro), 798

USB_W_VALUE_DT_DEVICE_QUALIFIER

(C

macro), 798

USB_W_VALUE_DT_ENDPOINT (C macro), 798

USB_W_VALUE_DT_INTERFACE (C macro), 798

USB_W_VALUE_DT_INTERFACE_POWER

(C

macro), 798

USB_W_VALUE_DT_OTHER_SPEED_CONFIG (C

macro), 798

USB_W_VALUE_DT_STRING (C macro), 798

uxQueueMessagesWaiting (C++ function), 1182

uxQueueMessagesWaitingFromISR (C++ func-

tion), 1184

uxQueueSpacesAvailable (C++ function), 1182

uxSemaphoreGetCount (C macro), 1209

uxTaskGetNumberOfTasks (C++ function), 1162

uxTaskGetStackHighWaterMark (C++ func-

tion), 1162

uxTaskGetStackHighWaterMark2 (C++ func-

tion), 1162

uxTaskGetSystemState (C++ function), 1164

uxTaskPriorityGet (C++ function), 1155

uxTaskPriorityGetFromISR (C++ function),

1156

uxTimerGetReloadMode (C++ function), 1216

V
vApplicationGetIdleTaskMemory (C++ function), 1164
vApplicationGetTimerTaskMemory (C++ function), 1217
vendor_ie_data_t (C++ class), 391 vendor_ie_data_t::element_id (C++ mem-
ber), 391 vendor_ie_data_t::length (C++ member),
391 vendor_ie_data_t::payload (C++ member),
391 vendor_ie_data_t::vendor_oui (C++ mem-
ber), 391 vendor_ie_data_t::vendor_oui_type
(C++ member), 391 vEventGroupDelete (C++ function), 1232 vMessageBufferDelete (C macro), 1248 vprintf_like_t (C++ type), 1311 vQueueAddToRegistry (C++ function), 1184 vQueueDelete (C++ function), 1182 vQueueUnregisterQueue (C++ function), 1185 vRingbufferDelete (C++ function), 1263 vRingbufferGetInfo (C++ function), 1264 vRingbufferReturnItem (C++ function), 1263 vRingbufferReturnItemFromISR (C++ func-
tion), 1263 vSemaphoreCreateBinary (C macro), 1196 vSemaphoreDelete (C macro), 1208 vStreamBufferDelete (C++ function), 1238

Espressif Systems

2171

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

vTaskAllocateMPURegions (C++ function), wifi_action_tx_req_t::rx_cb (C++ mem-

1150

ber), 395

vTaskDelay (C++ function), 1154

wifi_active_scan_time_t (C++ class), 387

vTaskDelayUntil (C macro), 1176

wifi_active_scan_time_t::max (C++ mem-

vTaskDelete (C++ function), 1153

ber), 387

vTaskEndScheduler (C++ function), 1159

wifi_active_scan_time_t::min (C++ mem-

vTaskGenericNotifyGiveFromISR (C++ func-

ber), 387

tion), 1171

WIFI_ALL_CHANNEL_SCAN (C++ enumerator), 403

vTaskGetInfo (C++ function), 1156

WIFI_AMPDU_RX_ENABLED (C macro), 385

vTaskGetRunTimeStats (C++ function), 1166 WIFI_AMPDU_TX_ENABLED (C macro), 385

vTaskList (C++ function), 1166

WIFI_AMSDU_TX_ENABLED (C macro), 385

vTaskNotifyGiveFromISR (C macro), 1177

WIFI_ANT_ANT0 (C++ enumerator), 403

vTaskNotifyGiveIndexedFromISR (C macro), WIFI_ANT_ANT1 (C++ enumerator), 403

1177

wifi_ant_config_t (C++ class), 394

vTaskPrioritySet (C++ function), 1157

wifi_ant_config_t::enabled_ant0 (C++

vTaskResume (C++ function), 1158

member), 394

vTaskSetApplicationTaskTag (C++ function), wifi_ant_config_t::enabled_ant1 (C++

1163

member), 394

vTaskSetThreadLocalStoragePointer

wifi_ant_config_t::rx_ant_default

(C++ function), 1163

(C++ member), 394

vTaskSetThreadLocalStoragePointerAndDelwCiaflil_baanctk_config_t::rx_ant_mode (C++

(C++ function), 1163

member), 394

vTaskSetTimeOutState (C++ function), 1174 wifi_ant_config_t::tx_ant_mode (C++

vTaskStartScheduler (C++ function), 1159

member), 394

vTaskSuspend (C++ function), 1157

wifi_ant_gpio_config_t (C++ class), 394

vTaskSuspendAll (C++ function), 1160

wifi_ant_gpio_config_t::gpio_cfg (C++

vTimerSetReloadMode (C++ function), 1216

member), 394

vTimerSetTimerID (C++ function), 1213

wifi_ant_gpio_t (C++ class), 394

wifi_ant_gpio_t::gpio_num (C++ member),

W

394

WEBSOCKET_EVENT_ANY (C++ enumerator), 943 WEBSOCKET_EVENT_CLOSED (C++ enumerator),
943 WEBSOCKET_EVENT_CONNECTED (C++ enumera-
tor), 943 WEBSOCKET_EVENT_DATA (C++ enumerator), 943 WEBSOCKET_EVENT_DISCONNECTED (C++ enu-
merator), 943 WEBSOCKET_EVENT_ERROR (C++ enumerator), 943 WEBSOCKET_EVENT_MAX (C++ enumerator), 943 WEBSOCKET_TRANSPORT_OVER_SSL (C++ enu-
merator), 944 WEBSOCKET_TRANSPORT_OVER_TCP (C++ enu-
merator), 944 WEBSOCKET_TRANSPORT_UNKNOWN (C++ enumer-
ator), 943 wifi_action_rx_cb_t (C++ type), 400 wifi_action_tx_req_t (C++ class), 394 wifi_action_tx_req_t::data (C++ member),
395 wifi_action_tx_req_t::data_len (C++
member), 395 wifi_action_tx_req_t::dest_mac (C++
member), 395 wifi_action_tx_req_t::ifx (C++ member),
395 wifi_action_tx_req_t::no_ack (C++ mem-
ber), 395

wifi_ant_gpio_t::gpio_select (C++ member), 394
WIFI_ANT_MAX (C++ enumerator), 403 WIFI_ANT_MODE_ANT0 (C++ enumerator), 404 WIFI_ANT_MODE_ANT1 (C++ enumerator), 404 WIFI_ANT_MODE_AUTO (C++ enumerator), 405 WIFI_ANT_MODE_MAX (C++ enumerator), 405 wifi_ant_mode_t (C++ enum), 404 wifi_ant_t (C++ enum), 403 wifi_ap_config_t (C++ class), 389 wifi_ap_config_t::authmode (C++ member),
389 wifi_ap_config_t::beacon_interval
(C++ member), 389 wifi_ap_config_t::channel (C++ member),
389 wifi_ap_config_t::ftm_responder (C++
member), 389 wifi_ap_config_t::max_connection (C++
member), 389 wifi_ap_config_t::pairwise_cipher
(C++ member), 389 wifi_ap_config_t::password (C++ member),
389 wifi_ap_config_t::ssid (C++ member), 389 wifi_ap_config_t::ssid_hidden (C++
member), 389 wifi_ap_config_t::ssid_len (C++ member),

Espressif Systems

2172

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

389 wifi_ap_record_t (C++ class), 387 wifi_ap_record_t::ant (C++ member), 388 wifi_ap_record_t::authmode (C++ member),
388 wifi_ap_record_t::bssid (C++ member), 387 wifi_ap_record_t::country (C++ member),
388 wifi_ap_record_t::ftm_initiator (C++
member), 388 wifi_ap_record_t::ftm_responder (C++
member), 388 wifi_ap_record_t::group_cipher (C++
member), 388 wifi_ap_record_t::pairwise_cipher
(C++ member), 388 wifi_ap_record_t::phy_11b (C++ member),
388 wifi_ap_record_t::phy_11g (C++ member),
388 wifi_ap_record_t::phy_11n (C++ member),
388 wifi_ap_record_t::phy_lr (C++ member),
388 wifi_ap_record_t::primary (C++ member),
387 wifi_ap_record_t::reserved (C++ member),
388 wifi_ap_record_t::rssi (C++ member), 388 wifi_ap_record_t::second (C++ member),
388 wifi_ap_record_t::ssid (C++ member), 387 wifi_ap_record_t::wps (C++ member), 388 WIFI_AUTH_MAX (C++ enumerator), 401 wifi_auth_mode_t (C++ enum), 401 WIFI_AUTH_OPEN (C++ enumerator), 401 WIFI_AUTH_WAPI_PSK (C++ enumerator), 401 WIFI_AUTH_WEP (C++ enumerator), 401 WIFI_AUTH_WPA2_ENTERPRISE (C++ enumera-
tor), 401 WIFI_AUTH_WPA2_PSK (C++ enumerator), 401 WIFI_AUTH_WPA2_WPA3_PSK (C++ enumerator),
401 WIFI_AUTH_WPA3_PSK (C++ enumerator), 401 WIFI_AUTH_WPA_PSK (C++ enumerator), 401 WIFI_AUTH_WPA_WPA2_PSK (C++ enumerator),
401 wifi_bandwidth_t (C++ enum), 403 WIFI_BW_HT20 (C++ enumerator), 404 WIFI_BW_HT40 (C++ enumerator), 404 WIFI_CACHE_TX_BUFFER_NUM (C macro), 385 WIFI_CIPHER_TYPE_AES_CMAC128 (C++ enu-
merator), 403 WIFI_CIPHER_TYPE_AES_GMAC128 (C++ enu-
merator), 403 WIFI_CIPHER_TYPE_AES_GMAC256 (C++ enu-
merator), 403 WIFI_CIPHER_TYPE_CCMP (C++ enumerator), 402

WIFI_CIPHER_TYPE_GCMP (C++ enumerator), 403 WIFI_CIPHER_TYPE_GCMP256 (C++ enumerator),
403 WIFI_CIPHER_TYPE_NONE (C++ enumerator), 402 WIFI_CIPHER_TYPE_SMS4 (C++ enumerator), 403 wifi_cipher_type_t (C++ enum), 402 WIFI_CIPHER_TYPE_TKIP (C++ enumerator), 402 WIFI_CIPHER_TYPE_TKIP_CCMP (C++ enumera-
tor), 402 WIFI_CIPHER_TYPE_UNKNOWN (C++ enumerator),
403 WIFI_CIPHER_TYPE_WEP104 (C++ enumerator),
402 WIFI_CIPHER_TYPE_WEP40 (C++ enumerator),
402 wifi_config_t (C++ union), 386 wifi_config_t::ap (C++ member), 386 wifi_config_t::sta (C++ member), 386 WIFI_CONNECT_AP_BY_SECURITY (C++ enumer-
ator), 403 WIFI_CONNECT_AP_BY_SIGNAL (C++ enumera-
tor), 403 WIFI_COUNTRY_POLICY_AUTO (C++ enumerator),
400 WIFI_COUNTRY_POLICY_MANUAL (C++ enumera-
tor), 401 wifi_country_policy_t (C++ enum), 400 wifi_country_t (C++ class), 386 wifi_country_t::cc (C++ member), 386 wifi_country_t::max_tx_power (C++ mem-
ber), 386 wifi_country_t::nchan (C++ member), 386 wifi_country_t::policy (C++ member), 386 wifi_country_t::schan (C++ member), 386 wifi_csi_cb_t (C++ type), 386 wifi_csi_config_t (C++ class), 393 wifi_csi_config_t::channel_filter_en
(C++ member), 393 wifi_csi_config_t::htltf_en (C++ mem-
ber), 393 wifi_csi_config_t::lltf_en (C++ member),
393 wifi_csi_config_t::ltf_merge_en (C++
member), 393 wifi_csi_config_t::manu_scale (C++
member), 393 wifi_csi_config_t::shift (C++ member),
393 wifi_csi_config_t::stbc_htltf2_en
(C++ member), 393 WIFI_CSI_ENABLED (C macro), 385 wifi_csi_info_t (C++ class), 393 wifi_csi_info_t::buf (C++ member), 394 wifi_csi_info_t::first_word_invalid
(C++ member), 394 wifi_csi_info_t::len (C++ member), 394 wifi_csi_info_t::mac (C++ member), 394 wifi_csi_info_t::rx_ctrl (C++ member),

Espressif Systems

2173

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

394

(C++ member), 398

WIFI_DEFAULT_RX_BA_WIN (C macro), 385

wifi_event_ftm_report_t::rtt_est (C++

WIFI_DYNAMIC_TX_BUFFER_NUM (C macro), 385

member), 398

wifi_err_reason_t (C++ enum), 401

wifi_event_ftm_report_t::rtt_raw (C++

WIFI_EVENT_ACTION_TX_STATUS (C++ enumer-

member), 398

ator), 407

wifi_event_ftm_report_t::status (C++

wifi_event_action_tx_status_t (C++

member), 398

class), 398

WIFI_EVENT_MASK_ALL (C macro), 400

wifi_event_action_tx_status_t::context WIFI_EVENT_MASK_AP_PROBEREQRECVED (C

(C++ member), 398

macro), 400

wifi_event_action_tx_status_t::da

WIFI_EVENT_MASK_NONE (C macro), 400

(C++ member), 398

WIFI_EVENT_MAX (C++ enumerator), 407

wifi_event_action_tx_status_t::ifx

WIFI_EVENT_ROC_DONE (C++ enumerator), 407

(C++ member), 398

wifi_event_roc_done_t (C++ class), 398

wifi_event_action_tx_status_t::status wifi_event_roc_done_t::context (C++

(C++ member), 398

member), 398

wifi_event_ap_probe_req_rx_t (C++ class), WIFI_EVENT_SCAN_DONE (C++ enumerator), 406

397

WIFI_EVENT_STA_AUTHMODE_CHANGE (C++

wifi_event_ap_probe_req_rx_t::mac

enumerator), 406

(C++ member), 397

wifi_event_sta_authmode_change_t (C++

wifi_event_ap_probe_req_rx_t::rssi

class), 396

(C++ member), 397

wifi_event_sta_authmode_change_t::new_mode

WIFI_EVENT_AP_PROBEREQRECVED (C++ enu-

(C++ member), 396

merator), 407

wifi_event_sta_authmode_change_t::old_mode

WIFI_EVENT_AP_STACONNECTED (C++ enumera-

(C++ member), 396

tor), 407

WIFI_EVENT_STA_BEACON_TIMEOUT (C++ enu-

wifi_event_ap_staconnected_t (C++ class),

merator), 407

396

WIFI_EVENT_STA_BSS_RSSI_LOW (C++ enumer-

wifi_event_ap_staconnected_t::aid

ator), 407

(C++ member), 397

WIFI_EVENT_STA_CONNECTED (C++ enumerator),

wifi_event_ap_staconnected_t::is_mesh_child 406

(C++ member), 397

wifi_event_sta_connected_t (C++ class),

wifi_event_ap_staconnected_t::mac

395

(C++ member), 397

wifi_event_sta_connected_t::authmode

WIFI_EVENT_AP_STADISCONNECTED (C++ enu-

(C++ member), 396

merator), 407

wifi_event_sta_connected_t::bssid

wifi_event_ap_stadisconnected_t (C++

(C++ member), 395

class), 397

wifi_event_sta_connected_t::channel

wifi_event_ap_stadisconnected_t::aid

(C++ member), 396

(C++ member), 397

wifi_event_sta_connected_t::ssid (C++

wifi_event_ap_stadisconnected_t::is_mesh_childmember), 395

(C++ member), 397

wifi_event_sta_connected_t::ssid_len

wifi_event_ap_stadisconnected_t::mac

(C++ member), 395

(C++ member), 397

WIFI_EVENT_STA_DISCONNECTED (C++ enumer-

WIFI_EVENT_AP_START (C++ enumerator), 407

ator), 406

WIFI_EVENT_AP_STOP (C++ enumerator), 407

wifi_event_sta_disconnected_t (C++

wifi_event_bss_rssi_low_t (C++ class), 397

class), 396

wifi_event_bss_rssi_low_t::rssi (C++ wifi_event_sta_disconnected_t::bssid

member), 397

(C++ member), 396

WIFI_EVENT_FTM_REPORT (C++ enumerator), 407 wifi_event_sta_disconnected_t::reason

wifi_event_ftm_report_t (C++ class), 398

(C++ member), 396

wifi_event_ftm_report_t::dist_est

wifi_event_sta_disconnected_t::ssid

(C++ member), 398

(C++ member), 396

wifi_event_ftm_report_t::ftm_report_datwaifi_event_sta_disconnected_t::ssid_len

(C++ member), 398

(C++ member), 396

wifi_event_ftm_report_t::ftm_report_numw_iefnit_reiveesnt_sta_scan_done_t (C++ class),

(C++ member), 398

395

wifi_event_ftm_report_t::peer_mac

wifi_event_sta_scan_done_t::number

Espressif Systems

2174

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 395

wifi_ftm_report_entry_t::t4 (C++ mem-

wifi_event_sta_scan_done_t::scan_id

ber), 398

(C++ member), 395

wifi_ftm_status_t (C++ enum), 407

wifi_event_sta_scan_done_t::status

WIFI_IF_AP (C++ enumerator), 400

(C++ member), 395

WIFI_IF_STA (C++ enumerator), 400

WIFI_EVENT_STA_START (C++ enumerator), 406 WIFI_INIT_CONFIG_DEFAULT (C macro), 385

WIFI_EVENT_STA_STOP (C++ enumerator), 406 WIFI_INIT_CONFIG_MAGIC (C macro), 385

WIFI_EVENT_STA_WPS_ER_FAILED (C++ enu- wifi_init_config_t (C++ class), 383

merator), 406

wifi_init_config_t::ampdu_rx_enable

WIFI_EVENT_STA_WPS_ER_PBC_OVERLAP

(C++ member), 383

(C++ enumerator), 407

wifi_init_config_t::ampdu_tx_enable

WIFI_EVENT_STA_WPS_ER_PIN (C++ enumera-

(C++ member), 383

tor), 407

wifi_init_config_t::amsdu_tx_enable

wifi_event_sta_wps_er_pin_t (C++ class),

(C++ member), 383

396

wifi_init_config_t::beacon_max_len

wifi_event_sta_wps_er_pin_t::pin_code

(C++ member), 384

(C++ member), 396

wifi_init_config_t::cache_tx_buf_num

WIFI_EVENT_STA_WPS_ER_SUCCESS (C++ enu-

(C++ member), 383

merator), 406

wifi_init_config_t::csi_enable (C++

wifi_event_sta_wps_er_success_t (C++

member), 383

class), 396

wifi_init_config_t::dynamic_rx_buf_num

wifi_event_sta_wps_er_success_t::ap_cred

(C++ member), 383

(C++ member), 396

wifi_init_config_t::dynamic_tx_buf_num

wifi_event_sta_wps_er_success_t::ap_cred_cnt (C++ member), 383

(C++ member), 396

wifi_init_config_t::event_handler

wifi_event_sta_wps_er_success_t::passphrase (C++ member), 383

(C++ member), 396

wifi_init_config_t::feature_caps (C++

wifi_event_sta_wps_er_success_t::ssid

member), 384

(C++ member), 396

wifi_init_config_t::magic (C++ member),

WIFI_EVENT_STA_WPS_ER_TIMEOUT (C++ enu-

384

merator), 407

wifi_init_config_t::mgmt_sbuf_num

wifi_event_sta_wps_fail_reason_t (C++

(C++ member), 384

enum), 407

wifi_init_config_t::nano_enable (C++

wifi_event_t (C++ enum), 406

member), 384

WIFI_EVENT_WIFI_READY (C++ enumerator), 406 wifi_init_config_t::nvs_enable (C++

WIFI_FAST_SCAN (C++ enumerator), 403

member), 383

wifi_ftm_initiator_cfg_t (C++ class), 395 wifi_init_config_t::osi_funcs (C++

wifi_ftm_initiator_cfg_t::burst_period

member), 383

(C++ member), 395

wifi_init_config_t::rx_ba_win (C++

wifi_ftm_initiator_cfg_t::channel

member), 384

(C++ member), 395

wifi_init_config_t::sta_disconnected_pm

wifi_ftm_initiator_cfg_t::frm_count

(C++ member), 384

(C++ member), 395

wifi_init_config_t::static_rx_buf_num

wifi_ftm_initiator_cfg_t::resp_mac

(C++ member), 383

(C++ member), 395

wifi_init_config_t::static_tx_buf_num

wifi_ftm_report_entry_t (C++ class), 397

(C++ member), 383

wifi_ftm_report_entry_t::dlog_token wifi_init_config_t::tx_buf_type (C++

(C++ member), 397

member), 383

wifi_ftm_report_entry_t::rssi (C++ wifi_init_config_t::wifi_task_core_id

member), 397

(C++ member), 384

wifi_ftm_report_entry_t::rtt (C++ mem- wifi_init_config_t::wpa_crypto_funcs

ber), 397

(C++ member), 383

wifi_ftm_report_entry_t::t1 (C++ mem- wifi_interface_t (C++ enum), 400

ber), 397

WIFI_MGMT_SBUF_NUM (C macro), 385

wifi_ftm_report_entry_t::t2 (C++ mem- WIFI_MODE_AP (C++ enumerator), 400

ber), 398

WIFI_MODE_APSTA (C++ enumerator), 400

wifi_ftm_report_entry_t::t3 (C++ mem- WIFI_MODE_MAX (C++ enumerator), 400

ber), 398

WIFI_MODE_NULL (C++ enumerator), 400

Espressif Systems

2175

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

WIFI_MODE_STA (C++ enumerator), 400 wifi_mode_t (C++ enum), 400 WIFI_NANO_FORMAT_ENABLED (C macro), 385 WIFI_NVS_ENABLED (C macro), 385 WIFI_OFFCHAN_TX_CANCEL (C macro), 399 WIFI_OFFCHAN_TX_REQ (C macro), 399 WIFI_PHY_RATE_11M_L (C++ enumerator), 405 WIFI_PHY_RATE_11M_S (C++ enumerator), 405 WIFI_PHY_RATE_12M (C++ enumerator), 405 WIFI_PHY_RATE_18M (C++ enumerator), 405 WIFI_PHY_RATE_1M_L (C++ enumerator), 405 WIFI_PHY_RATE_24M (C++ enumerator), 405 WIFI_PHY_RATE_2M_L (C++ enumerator), 405 WIFI_PHY_RATE_2M_S (C++ enumerator), 405 WIFI_PHY_RATE_36M (C++ enumerator), 405 WIFI_PHY_RATE_48M (C++ enumerator), 405 WIFI_PHY_RATE_54M (C++ enumerator), 405 WIFI_PHY_RATE_5M_L (C++ enumerator), 405 WIFI_PHY_RATE_5M_S (C++ enumerator), 405 WIFI_PHY_RATE_6M (C++ enumerator), 405 WIFI_PHY_RATE_9M (C++ enumerator), 405 WIFI_PHY_RATE_LORA_250K (C++ enumerator),
406 WIFI_PHY_RATE_LORA_500K (C++ enumerator),
406 WIFI_PHY_RATE_MAX (C++ enumerator), 406 WIFI_PHY_RATE_MCS0_LGI (C++ enumerator),
405 WIFI_PHY_RATE_MCS0_SGI (C++ enumerator),
406 WIFI_PHY_RATE_MCS1_LGI (C++ enumerator),
405 WIFI_PHY_RATE_MCS1_SGI (C++ enumerator),
406 WIFI_PHY_RATE_MCS2_LGI (C++ enumerator),
405 WIFI_PHY_RATE_MCS2_SGI (C++ enumerator),
406 WIFI_PHY_RATE_MCS3_LGI (C++ enumerator),
405 WIFI_PHY_RATE_MCS3_SGI (C++ enumerator),
406 WIFI_PHY_RATE_MCS4_LGI (C++ enumerator),
405 WIFI_PHY_RATE_MCS4_SGI (C++ enumerator),
406 WIFI_PHY_RATE_MCS5_LGI (C++ enumerator),
406 WIFI_PHY_RATE_MCS5_SGI (C++ enumerator),
406 WIFI_PHY_RATE_MCS6_LGI (C++ enumerator),
406 WIFI_PHY_RATE_MCS6_SGI (C++ enumerator),
406 WIFI_PHY_RATE_MCS7_LGI (C++ enumerator),
406 WIFI_PHY_RATE_MCS7_SGI (C++ enumerator),
406

wifi_phy_rate_t (C++ enum), 405 WIFI_PKT_CTRL (C++ enumerator), 404 WIFI_PKT_DATA (C++ enumerator), 404 WIFI_PKT_MGMT (C++ enumerator), 404 WIFI_PKT_MISC (C++ enumerator), 404 wifi_pkt_rx_ctrl_t (C++ class), 391 wifi_pkt_rx_ctrl_t::__pad0__ (C++ mem-
ber), 391 wifi_pkt_rx_ctrl_t::__pad10__ (C++
member), 392 wifi_pkt_rx_ctrl_t::__pad11__ (C++
member), 392 wifi_pkt_rx_ctrl_t::__pad12__ (C++
member), 392 wifi_pkt_rx_ctrl_t::__pad13__ (C++
member), 392 wifi_pkt_rx_ctrl_t::__pad1__ (C++ mem-
ber), 391 wifi_pkt_rx_ctrl_t::__pad2__ (C++ mem-
ber), 391 wifi_pkt_rx_ctrl_t::__pad3__ (C++ mem-
ber), 392 wifi_pkt_rx_ctrl_t::__pad4__ (C++ mem-
ber), 392 wifi_pkt_rx_ctrl_t::__pad5__ (C++ mem-
ber), 392 wifi_pkt_rx_ctrl_t::__pad6__ (C++ mem-
ber), 392 wifi_pkt_rx_ctrl_t::__pad7__ (C++ mem-
ber), 392 wifi_pkt_rx_ctrl_t::__pad8__ (C++ mem-
ber), 392 wifi_pkt_rx_ctrl_t::__pad9__ (C++ mem-
ber), 392 wifi_pkt_rx_ctrl_t::aggregation (C++
member), 392 wifi_pkt_rx_ctrl_t::ampdu_cnt (C++
member), 392 wifi_pkt_rx_ctrl_t::ant (C++ member), 392 wifi_pkt_rx_ctrl_t::channel (C++ mem-
ber), 392 wifi_pkt_rx_ctrl_t::cwb (C++ member), 391 wifi_pkt_rx_ctrl_t::fec_coding (C++
member), 392 wifi_pkt_rx_ctrl_t::mcs (C++ member), 391 wifi_pkt_rx_ctrl_t::noise_floor (C++
member), 392 wifi_pkt_rx_ctrl_t::not_sounding (C++
member), 392 wifi_pkt_rx_ctrl_t::rate (C++ member),
391 wifi_pkt_rx_ctrl_t::rssi (C++ member),
391 wifi_pkt_rx_ctrl_t::rx_state (C++ mem-
ber), 393 wifi_pkt_rx_ctrl_t::secondary_channel
(C++ member), 392 wifi_pkt_rx_ctrl_t::sgi (C++ member), 392

Espressif Systems

2176

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

wifi_pkt_rx_ctrl_t::sig_len (C++ mem- wifi_promiscuous_pkt_t::rx_ctrl (C++

ber), 392

member), 393

wifi_pkt_rx_ctrl_t::sig_mode (C++ mem- wifi_promiscuous_pkt_type_t (C++ enum),

ber), 391

404

wifi_pkt_rx_ctrl_t::smoothing (C++ WIFI_PROTOCOL_11B (C macro), 399

member), 391

WIFI_PROTOCOL_11G (C macro), 399

wifi_pkt_rx_ctrl_t::stbc (C++ member), WIFI_PROTOCOL_11N (C macro), 399

392

WIFI_PROTOCOL_LR (C macro), 399

wifi_pkt_rx_ctrl_t::timestamp (C++ wifi_prov_cb_event_t (C++ enum), 985

member), 392

wifi_prov_cb_func_t (C++ type), 985

wifi_pmf_config_t (C++ class), 388

wifi_prov_config_data_handler (C++ func-

wifi_pmf_config_t::capable (C++ member),

tion), 987

389

wifi_prov_config_get_data_t (C++ class),

wifi_pmf_config_t::required (C++ mem-

988

ber), 389

wifi_prov_config_get_data_t::conn_info

WIFI_PROMIS_CTRL_FILTER_MASK_ACK (C

(C++ member), 988

macro), 399

wifi_prov_config_get_data_t::fail_reason

WIFI_PROMIS_CTRL_FILTER_MASK_ALL (C

(C++ member), 988

macro), 399

wifi_prov_config_get_data_t::wifi_state

WIFI_PROMIS_CTRL_FILTER_MASK_BA

(C

(C++ member), 988

macro), 399

wifi_prov_config_handlers (C++ class), 988

WIFI_PROMIS_CTRL_FILTER_MASK_BAR (C wifi_prov_config_handlers::apply_config_handler

macro), 399

(C++ member), 988

WIFI_PROMIS_CTRL_FILTER_MASK_CFEND (C wifi_prov_config_handlers::ctx (C++

macro), 399

member), 988

WIFI_PROMIS_CTRL_FILTER_MASK_CFENDACK wifi_prov_config_handlers::get_status_handler

(C macro), 400

(C++ member), 988

WIFI_PROMIS_CTRL_FILTER_MASK_CTS (C wifi_prov_config_handlers::set_config_handler

macro), 399

(C++ member), 988

WIFI_PROMIS_CTRL_FILTER_MASK_PSPOLL (C wifi_prov_config_handlers_t (C++ type),

macro), 399

989

WIFI_PROMIS_CTRL_FILTER_MASK_RTS (C wifi_prov_config_set_data_t (C++ class),

macro), 399

988

WIFI_PROMIS_CTRL_FILTER_MASK_WRAPPER wifi_prov_config_set_data_t::bssid

(C macro), 399

(C++ member), 988

WIFI_PROMIS_FILTER_MASK_ALL (C macro), wifi_prov_config_set_data_t::channel

399

(C++ member), 988

WIFI_PROMIS_FILTER_MASK_CTRL (C macro), wifi_prov_config_set_data_t::password

399

(C++ member), 988

WIFI_PROMIS_FILTER_MASK_DATA (C macro), wifi_prov_config_set_data_t::ssid

399

(C++ member), 988

WIFI_PROMIS_FILTER_MASK_DATA_AMPDU (C WIFI_PROV_CRED_FAIL (C++ enumerator), 985

macro), 399

WIFI_PROV_CRED_RECV (C++ enumerator), 985

WIFI_PROMIS_FILTER_MASK_DATA_MPDU (C WIFI_PROV_CRED_SUCCESS (C++ enumerator),

macro), 399

985

WIFI_PROMIS_FILTER_MASK_FCSFAIL

(C wifi_prov_ctx_t (C++ type), 989

macro), 399

WIFI_PROV_DEINIT (C++ enumerator), 986

WIFI_PROMIS_FILTER_MASK_MGMT (C macro), WIFI_PROV_END (C++ enumerator), 986

399

WIFI_PROV_EVENT_HANDLER_NONE (C macro),

WIFI_PROMIS_FILTER_MASK_MISC (C macro),

985

399

wifi_prov_event_handler_t (C++ class), 984

wifi_promiscuous_cb_t (C++ type), 385

wifi_prov_event_handler_t::event_cb

wifi_promiscuous_filter_t (C++ class), 393

(C++ member), 984

wifi_promiscuous_filter_t::filter_mask wifi_prov_event_handler_t::user_data

(C++ member), 393

(C++ member), 984

wifi_promiscuous_pkt_t (C++ class), 393

WIFI_PROV_INIT (C++ enumerator), 985

wifi_promiscuous_pkt_t::payload (C++ wifi_prov_mgr_config_t (C++ class), 984

member), 393

wifi_prov_mgr_config_t::app_event_handler

Espressif Systems

2177

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

(C++ member), 985

(C macro), 987

wifi_prov_mgr_config_t::scheme (C++ WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BT

member), 984

(C macro), 987

wifi_prov_mgr_config_t::scheme_event_haWnIdFlIe_rPROV_SCHEME_BLE_EVENT_HANDLER_FREE_BTDM

(C++ member), 985

(C macro), 987

wifi_prov_mgr_configure_sta (C++ func- wifi_prov_scheme_ble_set_mfg_data

tion), 983

(C++ function), 986

wifi_prov_mgr_deinit (C++ function), 979

wifi_prov_scheme_ble_set_service_uuid

wifi_prov_mgr_disable_auto_stop (C++

(C++ function), 986

function), 981

wifi_prov_scheme_softap_set_httpd_handle

wifi_prov_mgr_endpoint_create (C++ func-

(C++ function), 987

tion), 982

wifi_prov_scheme_t (C++ type), 985

wifi_prov_mgr_endpoint_register (C++ wifi_prov_security (C++ enum), 986

function), 982

WIFI_PROV_SECURITY_0 (C++ enumerator), 986

wifi_prov_mgr_endpoint_unregister

WIFI_PROV_SECURITY_1 (C++ enumerator), 986

(C++ function), 982

wifi_prov_security_t (C++ type), 985

wifi_prov_mgr_event_handler (C++ func- WIFI_PROV_STA_AP_NOT_FOUND (C++ enumera-

tion), 982

tor), 989

wifi_prov_mgr_get_wifi_disconnect_reasoWnIFI_PROV_STA_AUTH_ERROR (C++ enumerator),

(C++ function), 983

989

wifi_prov_mgr_get_wifi_state (C++ func- wifi_prov_sta_conn_info_t (C++ class), 987

tion), 983

wifi_prov_sta_conn_info_t::auth_mode

wifi_prov_mgr_init (C++ function), 979

(C++ member), 988

wifi_prov_mgr_is_provisioned (C++ func- wifi_prov_sta_conn_info_t::bssid (C++

tion), 980

member), 987

wifi_prov_mgr_reset_provisioning (C++ wifi_prov_sta_conn_info_t::channel

function), 983

(C++ member), 988

wifi_prov_mgr_reset_sm_state_on_failurewifi_prov_sta_conn_info_t::ip_addr

(C++ function), 983

(C++ member), 987

wifi_prov_mgr_set_app_info (C++ function), wifi_prov_sta_conn_info_t::ssid (C++

981

member), 988

wifi_prov_mgr_start_provisioning (C++ WIFI_PROV_STA_CONNECTED (C++ enumerator),

function), 980

989

wifi_prov_mgr_stop_provisioning (C++ WIFI_PROV_STA_CONNECTING (C++ enumerator),

function), 980

989

wifi_prov_mgr_wait (C++ function), 981

WIFI_PROV_STA_DISCONNECTED (C++ enumera-

wifi_prov_scheme (C++ class), 984

tor), 989

wifi_prov_scheme::delete_config (C++ wifi_prov_sta_fail_reason_t (C++ enum),

member), 984

989

wifi_prov_scheme::new_config (C++ mem- wifi_prov_sta_state_t (C++ enum), 989

ber), 984

WIFI_PROV_START (C++ enumerator), 985

wifi_prov_scheme::prov_start (C++ mem- WIFI_PS_MAX_MODEM (C++ enumerator), 403

ber), 984

WIFI_PS_MIN_MODEM (C++ enumerator), 403

wifi_prov_scheme::prov_stop (C++ mem- WIFI_PS_NONE (C++ enumerator), 403

ber), 984

wifi_ps_type_t (C++ enum), 403

wifi_prov_scheme::set_config_endpoint WIFI_REASON_4WAY_HANDSHAKE_TIMEOUT

(C++ member), 984

(C++ enumerator), 401

wifi_prov_scheme::set_config_service WIFI_REASON_802_1X_AUTH_FAILED (C++

(C++ member), 984

enumerator), 402

wifi_prov_scheme::wifi_mode (C++ mem- WIFI_REASON_AKMP_INVALID (C++ enumerator),

ber), 984

402

wifi_prov_scheme_ble_event_cb_free_ble WIFI_REASON_AP_TSF_RESET (C++ enumerator),

(C++ function), 986

402

wifi_prov_scheme_ble_event_cb_free_bt WIFI_REASON_ASSOC_EXPIRE (C++ enumerator),

(C++ function), 986

401

wifi_prov_scheme_ble_event_cb_free_btdmWIFI_REASON_ASSOC_FAIL (C++ enumerator),

(C++ function), 986

402

WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREEW_IBFLIE_REASON_ASSOC_LEAVE (C++ enumerator),

Espressif Systems

2178

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

401 WIFI_REASON_ASSOC_NOT_AUTHED (C++ enu-
merator), 401 WIFI_REASON_ASSOC_TOOMANY (C++ enumera-
tor), 401 WIFI_REASON_AUTH_EXPIRE (C++ enumerator),
401 WIFI_REASON_AUTH_FAIL (C++ enumerator), 402 WIFI_REASON_AUTH_LEAVE (C++ enumerator),
401 WIFI_REASON_BEACON_TIMEOUT (C++ enumera-
tor), 402 WIFI_REASON_BSS_TRANSITION_DISASSOC
(C++ enumerator), 401 WIFI_REASON_CIPHER_SUITE_REJECTED
(C++ enumerator), 402 WIFI_REASON_CONNECTION_FAIL (C++ enumer-
ator), 402 WIFI_REASON_DISASSOC_PWRCAP_BAD (C++
enumerator), 401 WIFI_REASON_DISASSOC_SUPCHAN_BAD (C++
enumerator), 401 WIFI_REASON_GROUP_CIPHER_INVALID (C++
enumerator), 402 WIFI_REASON_GROUP_KEY_UPDATE_TIMEOUT
(C++ enumerator), 401 WIFI_REASON_HANDSHAKE_TIMEOUT (C++ enu-
merator), 402 WIFI_REASON_IE_IN_4WAY_DIFFERS (C++
enumerator), 401 WIFI_REASON_IE_INVALID (C++ enumerator),
401 WIFI_REASON_INVALID_PMKID (C++ enumera-
tor), 402 WIFI_REASON_INVALID_RSN_IE_CAP (C++
enumerator), 402 WIFI_REASON_MIC_FAILURE (C++ enumerator),
401 WIFI_REASON_NO_AP_FOUND (C++ enumerator),
402 WIFI_REASON_NOT_ASSOCED (C++ enumerator),
401 WIFI_REASON_NOT_AUTHED (C++ enumerator),
401 WIFI_REASON_PAIRWISE_CIPHER_INVALID
(C++ enumerator), 402 WIFI_REASON_ROAMING (C++ enumerator), 402 WIFI_REASON_UNSPECIFIED (C++ enumerator),
401 WIFI_REASON_UNSUPP_RSN_IE_VERSION
(C++ enumerator), 402 WIFI_ROC_CANCEL (C macro), 399 WIFI_ROC_REQ (C macro), 399 wifi_scan_config_t (C++ class), 387 wifi_scan_config_t::bssid (C++ member),
387 wifi_scan_config_t::channel (C++ mem-
ber), 387

wifi_scan_config_t::scan_time (C++ member), 387
wifi_scan_config_t::scan_type (C++ member), 387
wifi_scan_config_t::show_hidden (C++ member), 387
wifi_scan_config_t::ssid (C++ member), 387
wifi_scan_method_t (C++ enum), 403 wifi_scan_threshold_t (C++ class), 388 wifi_scan_threshold_t::authmode (C++
member), 388 wifi_scan_threshold_t::rssi (C++ mem-
ber), 388 wifi_scan_time_t (C++ class), 387 wifi_scan_time_t::active (C++ member),
387 wifi_scan_time_t::passive (C++ member),
387 WIFI_SCAN_TYPE_ACTIVE (C++ enumerator), 402 WIFI_SCAN_TYPE_PASSIVE (C++ enumerator),
402 wifi_scan_type_t (C++ enum), 402 WIFI_SECOND_CHAN_ABOVE (C++ enumerator),
402 WIFI_SECOND_CHAN_BELOW (C++ enumerator),
402 WIFI_SECOND_CHAN_NONE (C++ enumerator), 402 wifi_second_chan_t (C++ enum), 402 WIFI_SOFTAP_BEACON_MAX_LEN (C macro), 385 wifi_sort_method_t (C++ enum), 403 wifi_sta_config_t (C++ class), 389 wifi_sta_config_t::bssid (C++ member),
390 wifi_sta_config_t::bssid_set (C++ mem-
ber), 389 wifi_sta_config_t::btm_enabled (C++
member), 390 wifi_sta_config_t::channel (C++ member),
390 wifi_sta_config_t::listen_interval
(C++ member), 390 wifi_sta_config_t::mbo_enabled (C++
member), 390 wifi_sta_config_t::password (C++ mem-
ber), 389 wifi_sta_config_t::pmf_cfg (C++ member),
390 wifi_sta_config_t::reserved (C++ mem-
ber), 390 wifi_sta_config_t::rm_enabled (C++
member), 390 wifi_sta_config_t::scan_method (C++
member), 389 wifi_sta_config_t::sort_method (C++
member), 390 wifi_sta_config_t::ssid (C++ member), 389 wifi_sta_config_t::threshold (C++ mem-

Espressif Systems

2179

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

ber), 390 WIFI_STA_DISCONNECTED_PM_ENABLED (C
macro), 385 wifi_sta_info_t (C++ class), 390 wifi_sta_info_t::is_mesh_child (C++
member), 390 wifi_sta_info_t::mac (C++ member), 390 wifi_sta_info_t::phy_11b (C++ member),
390 wifi_sta_info_t::phy_11g (C++ member),
390 wifi_sta_info_t::phy_11n (C++ member),
390 wifi_sta_info_t::phy_lr (C++ member), 390 wifi_sta_info_t::reserved (C++ member),
390 wifi_sta_info_t::rssi (C++ member), 390 wifi_sta_list_t (C++ class), 390 wifi_sta_list_t::num (C++ member), 391 wifi_sta_list_t::sta (C++ member), 391 WIFI_STATIC_TX_BUFFER_NUM (C macro), 385 WIFI_STATIS_ALL (C macro), 400 WIFI_STATIS_BUFFER (C macro), 400 WIFI_STATIS_DIAG (C macro), 400 WIFI_STATIS_HW (C macro), 400 WIFI_STATIS_PS (C macro), 400 WIFI_STATIS_RXTX (C macro), 400 WIFI_STORAGE_FLASH (C++ enumerator), 404 WIFI_STORAGE_RAM (C++ enumerator), 404 wifi_storage_t (C++ enum), 404 WIFI_TASK_CORE_ID (C macro), 385 WIFI_VENDOR_IE_ELEMENT_ID (C macro), 399 wifi_vendor_ie_id_t (C++ enum), 404 wifi_vendor_ie_type_t (C++ enum), 404 WIFI_VND_IE_ID_0 (C++ enumerator), 404 WIFI_VND_IE_ID_1 (C++ enumerator), 404 WIFI_VND_IE_TYPE_ASSOC_REQ (C++ enumera-
tor), 404 WIFI_VND_IE_TYPE_ASSOC_RESP (C++ enumer-
ator), 404 WIFI_VND_IE_TYPE_BEACON (C++ enumerator),
404 WIFI_VND_IE_TYPE_PROBE_REQ (C++ enumera-
tor), 404 WIFI_VND_IE_TYPE_PROBE_RESP (C++ enumer-
ator), 404 wl_erase_range (C++ function), 1079 wl_handle_t (C++ type), 1080 WL_INVALID_HANDLE (C macro), 1080 wl_mount (C++ function), 1078 wl_read (C++ function), 1079 wl_sector_size (C++ function), 1080 wl_size (C++ function), 1079 wl_unmount (C++ function), 1079 wl_write (C++ function), 1079 WPS_FAIL_REASON_MAX (C++ enumerator), 407 WPS_FAIL_REASON_NORMAL (C++ enumerator),
407

WPS_FAIL_REASON_RECV_M2D (C++ enumerator), 407
X
xEventGroupClearBits (C++ function), 1229 xEventGroupClearBitsFromISR (C macro),
1232 xEventGroupCreate (C++ function), 1226 xEventGroupCreateStatic (C++ function),
1227 xEventGroupGetBits (C macro), 1234 xEventGroupGetBitsFromISR (C++ function),
1232 xEventGroupSetBits (C++ function), 1229 xEventGroupSetBitsFromISR (C macro), 1233 xEventGroupSync (C++ function), 1230 xEventGroupWaitBits (C++ function), 1227 xMessageBufferCreate (C macro), 1242 xMessageBufferCreateStatic (C macro), 1243 xMessageBufferIsEmpty (C macro), 1248 xMessageBufferIsFull (C macro), 1248 xMessageBufferNextLengthBytes (C macro),
1249 xMessageBufferReceive (C macro), 1246 xMessageBufferReceiveCompletedFromISR
(C macro), 1249 xMessageBufferReceiveFromISR (C macro),
1247 xMessageBufferReset (C macro), 1248 xMessageBufferSend (C macro), 1243 xMessageBufferSendCompletedFromISR (C
macro), 1249 xMessageBufferSendFromISR (C macro), 1245 xMessageBufferSpaceAvailable (C macro),
1248 xMessageBufferSpacesAvailable (C macro),
1249 xQueueAddToSet (C++ function), 1186 xQueueCreate (C macro), 1187 xQueueCreateSet (C++ function), 1185 xQueueCreateStatic (C macro), 1188 xQueueGenericCreate (C++ function), 1185 xQueueGenericCreateStatic (C++ function),
1185 xQueueGenericSend (C++ function), 1178 xQueueGenericSendFromISR (C++ function),
1182 xQueueGiveFromISR (C++ function), 1183 xQueueIsQueueEmptyFromISR (C++ function),
1184 xQueueIsQueueFullFromISR (C++ function),
1184 xQueueOverwrite (C macro), 1192 xQueueOverwriteFromISR (C macro), 1194 xQueuePeek (C++ function), 1179 xQueuePeekFromISR (C++ function), 1180 xQueueReceive (C++ function), 1181 xQueueReceiveFromISR (C++ function), 1183

Espressif Systems

2180

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

xQueueRemoveFromSet (C++ function), 1186

xQueueReset (C macro), 1196

xQueueSelectFromSet (C++ function), 1186

xQueueSelectFromSetFromISR (C++ function),

1187

xQueueSend (C macro), 1190

xQueueSendFromISR (C macro), 1195

xQueueSendToBack (C macro), 1189

xQueueSendToBackFromISR (C macro), 1193

xQueueSendToFront (C macro), 1189

xQueueSendToFrontFromISR (C macro), 1193

xRingbufferAddToQueueSetRead (C++ func-

tion), 1264

xRingbufferCanRead (C++ function), 1264

xRingbufferCreate (C++ function), 1260

xRingbufferCreateNoSplit (C++ function),

1260

xRingbufferCreateStatic (C++ function),

1260

xRingbufferGetCurFreeSize (C++ function),

1264

xRingbufferGetMaxItemSize (C++ function),

1263

xRingbufferPrintInfo (C++ function), 1265

xRingbufferReceive (C++ function), 1261

xRingbufferReceiveFromISR (C++ function),

1261

xRingbufferReceiveSplit (C++ function),

1262

xRingbufferReceiveSplitFromISR (C++

function), 1262

xRingbufferReceiveUpTo (C++ function), 1262

xRingbufferReceiveUpToFromISR (C++ func-

tion), 1263

xRingbufferRemoveFromQueueSetRead

(C++ function), 1264

xRingbufferSend (C++ function), 1260

xRingbufferSendAcquire (C++ function), 1261

xRingbufferSendComplete (C++ function),

1261

xRingbufferSendFromISR (C++ function), 1260

xSemaphoreCreateBinary (C macro), 1196

xSemaphoreCreateBinaryStatic (C macro),

1197

xSemaphoreCreateCounting (C macro), 1205

xSemaphoreCreateCountingStatic

(C

macro), 1207

xSemaphoreCreateMutex (C macro), 1204

xSemaphoreCreateMutexStatic (C macro),

1204

xSemaphoreGetMutexHolder (C macro), 1208

xSemaphoreGetMutexHolderFromISR

(C

macro), 1209

xSemaphoreGive (C macro), 1200

xSemaphoreGiveFromISR (C macro), 1202

xSemaphoreGiveRecursive (C macro), 1201

xSemaphoreTake (C macro), 1198

xSemaphoreTakeFromISR (C macro), 1203

xSemaphoreTakeRecursive (C macro), 1199 xSTATIC_RINGBUFFER (C++ class), 1265 xStreamBufferBytesAvailable (C++ func-
tion), 1239 xStreamBufferCreate (C macro), 1240 xStreamBufferCreateStatic (C macro), 1241 xStreamBufferIsEmpty (C++ function), 1238 xStreamBufferIsFull (C++ function), 1238 xStreamBufferReceive (C++ function), 1236 xStreamBufferReceiveCompletedFromISR
(C++ function), 1240 xStreamBufferReceiveFromISR (C++ func-
tion), 1237 xStreamBufferReset (C++ function), 1239 xStreamBufferSend (C++ function), 1234 xStreamBufferSendCompletedFromISR
(C++ function), 1239 xStreamBufferSendFromISR (C++ function),
1235 xStreamBufferSetTriggerLevel (C++ func-
tion), 1239 xStreamBufferSpacesAvailable (C++ func-
tion), 1239 xTaskAbortDelay (C++ function), 1155 xTaskCallApplicationTaskHook (C++ func-
tion), 1164 xTaskCatchUpTicks (C++ function), 1175 xTaskCheckForTimeOut (C++ function), 1174 xTaskCreate (C++ function), 1147 xTaskCreatePinnedToCore (C++ function),
1147 xTaskCreateStatic (C++ function), 1149 xTaskCreateStaticPinnedToCore (C++ func-
tion), 1148 xTaskDelayUntil (C++ function), 1154 xTaskGenericNotify (C++ function), 1167 xTaskGenericNotifyFromISR (C++ function),
1168 xTaskGenericNotifyStateClear (C++ func-
tion), 1173 xTaskGenericNotifyWait (C++ function), 1169 xTaskGetApplicationTaskTag (C++ function),
1163 xTaskGetApplicationTaskTagFromISR
(C++ function), 1163 xTaskGetHandle (C++ function), 1162 xTaskGetIdleTaskHandle (C++ function), 1164 xTaskGetTickCount (C++ function), 1161 xTaskGetTickCountFromISR (C++ function),
1161 xTaskNotify (C macro), 1176 xTaskNotifyAndQuery (C macro), 1176 xTaskNotifyAndQueryFromISR (C macro), 1176 xTaskNotifyAndQueryIndexed (C macro), 1176 xTaskNotifyAndQueryIndexedFromISR (C
macro), 1176 xTaskNotifyFromISR (C macro), 1176 xTaskNotifyGive (C macro), 1176

Espressif Systems

2181

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback

Index

xTaskNotifyGiveIndexed (C macro), 1177

xTimerStopFromISR (C macro), 1223

xTaskNotifyIndexed (C macro), 1176

xTaskNotifyIndexedFromISR (C macro), 1176

xTaskNotifyStateClear (C macro), 1177

xTaskNotifyStateClearIndexed (C macro),

1177

xTaskNotifyWait (C macro), 1176

xTaskNotifyWaitIndexed (C macro), 1176

xTaskResumeAll (C++ function), 1161

xTaskResumeFromISR (C++ function), 1159

xtensa_perfmon_config (C++ class), 1331

xtensa_perfmon_config::call_function

(C++ member), 1331

xtensa_perfmon_config::call_params

(C++ member), 1331

xtensa_perfmon_config::callback (C++

member), 1331

xtensa_perfmon_config::callback_params

(C++ member), 1331

xtensa_perfmon_config::counters_size

(C++ member), 1331

xtensa_perfmon_config::max_deviation

(C++ member), 1331

xtensa_perfmon_config::repeat_count

(C++ member), 1331

xtensa_perfmon_config::select_mask

(C++ member), 1331

xtensa_perfmon_config::tracelevel

(C++ member), 1331

xtensa_perfmon_config_t (C++ type), 1332

xtensa_perfmon_dump (C++ function), 1330

xtensa_perfmon_exec (C++ function), 1331

xtensa_perfmon_init (C++ function), 1330

xtensa_perfmon_overflow (C++ function),

1330

xtensa_perfmon_reset (C++ function), 1330

xtensa_perfmon_start (C++ function), 1330

xtensa_perfmon_stop (C++ function), 1330

xtensa_perfmon_value (C++ function), 1330

xtensa_perfmon_view_cb (C++ function), 1331

xTimerChangePeriod (C macro), 1218

xTimerChangePeriodFromISR (C macro), 1224

xTimerCreate (C++ function), 1209

xTimerCreateStatic (C++ function), 1211

xTimerDelete (C macro), 1219

xTimerGetExpiryTime (C++ function), 1216

xTimerGetPeriod (C++ function), 1216

xTimerGetTimerDaemonTaskHandle (C++

function), 1214

xTimerIsTimerActive (C++ function), 1214

xTimerPendFunctionCall (C++ function), 1215

xTimerPendFunctionCallFromISR (C++ func-

tion), 1214

xTimerReset (C macro), 1220

xTimerResetFromISR (C macro), 1225

xTimerStart (C macro), 1217

xTimerStartFromISR (C macro), 1222

xTimerStop (C macro), 1218

Espressif Systems

2182

Release v5.0-dev-1424-g2467aa7f6c

Submit Document Feedback


LaTeX with hyperref xdvipdfmx (20190824)

Search Any Device: